ForgeGraph

One package. Equivalent behaviour on Cloudflare, AWS and Node.

ForgeGraph is a compiler and an application runtime. You describe your domain once in a .forge package — resources, functions, workflows, channels, policies, data classifications — and write the behaviour once as ordinary Effect code. The compiler produces a deployment plan for each target it supports, and the runtime executes that plan with the same observable semantics everywhere:

	Cloudflare	AWS	Node / self-hosted
compute	Workers	Lambda + HTTP API	Node 24+ HTTP server
data	D1	DynamoDB	PostgreSQL, SQLite, libsql
blobs	R2	S3	filesystem / S3-compatible
queues	Queues	SQS	PostgreSQL outbox
workflows	Workflows	Step Functions	built-in driver or Temporal
realtime	Durable Objects	API Gateway WebSocket	in-process hub
schedules	Cron Triggers	EventBridge Scheduler	node-cron

Equivalent behavior is the contract exercised by 15 conformance scenarios and provider differential tests. Certification is revision-specific: the retained RELEASE_MANIFEST.json currently withholds the required profile certifications. Recent source features and narrow provider traces do not make every current combination certified. See the implementation and beta review.

Install

brew install gmackorg/tap/forgec   # macOS and Linux
cargo install forgegraph-cli       # from source, any platform with Rust 1.97+

Prebuilt binaries for macOS (arm64, x86_64) and Linux (arm64, x86_64) are attached to every release with SHA-256 checksums.

pnpm add @forgegraph/runtime       # the runtime your impl/ code imports

Start a package

forgec init task-app --name @example/tasks
cd task-app
forgec check .
forgec build .

init creates a portable, dependency-free resource package in a new directory. It is available in compiler builds containing this change; published release availability remains tracked by FORG-6. See getting started for the compiler workflow and host setup.

A ten-line tour

Create acme/forge.toml with [package], name = "@acme/commerce" and version = "1.0.0", then put this model in acme/src/order.forge:

export resource Order @crud("/v1/orders") {
  id : id
  total : decimal
  placedAt : datetime
  lifecycle status {
    initial Pending
    terminal Paid
    pay: Pending -> Paid
  }
}

forgec check ./acme            # parse, resolve, type-check, resolve path deps
forgec build ./acme            # generates plans for the configured hosts

forgec build emits the deployment plan, the SQL or DynamoDB access plan, the migrations, the typed TypeScript client, the OpenAPI document, the Smithy model and the ForgeGraph contract (contract.json, see docs/contract-ir.md). Both physical plans are in the bundle. Host selection happens in deployment configuration. Your handwritten business code lives in impl/ and never mentions a provider.

Start with docs/getting-started.md, then docs/language.md.

What is in this repository

Compiler (Rust, published to crates.io):

crate	what it is
forgegraph-cli	the forgec binary and the language server
forgegraph-syntax	lexer and lossless parser (logos + rowan)
forgegraph-semantic	name resolution, type check, domain-ir/1, capability algebra, diff
forgegraph-planner	contracts, SQL and DynamoDB access plans, migration planning
forgegraph-codegen	TypeScript client, OpenAPI, Smithy, OpenAPI import

Runtime and tooling (TypeScript, published to npm under @forgegraph/):

package	what it is	stability
@forgegraph/runtime	the engine: hosts, executors, policy, outbox, workflows, telemetry	stable candidate
@forgegraph/react	descriptor-driven forms, edit buffers and gizmo workspaces	stable candidate
@forgegraph/interfaces	OpenAPI/Smithy export, discovery, RPC bindings, MCP server, dashboards	stable candidate
@forgegraph/capability-manifest	the capability manifest contract	stable candidate
@forgegraph/registry	signed artifacts, catalog, deployment inventory, dependency grants	experimental
@forgegraph/governance	disposition planning, subject rights, redaction, control packs	experimental
@forgegraph/adapters	provider packs, certification matrix, Terraform and self-hosted emitters	experimental
@forgegraph/release-gates	promotion gates over compatibility and evidence	experimental

Stability tiers are defined in docs/stability.md and recorded in each package.json under forgegraph.stability. Everything is 0.x: the tiers say how much churn to expect, not that anything is frozen.

Reference application: examples/acme is a real commerce application — orders, payments, fulfilment, a React workspace, an edition-2027 walkthrough — deployed to both clouds during certification. The conformance suite in conformance/ runs against it.

Design notes worth knowing before you adopt it

• Authentication fails closed. Every host requires an AuthHost. There is a development mode that trusts x-forge-tenant / x-forge-actor headers; it must be opted into by name (FORGE_AUTH=dev-headers) and it announces itself loudly at startup. There is no default that silently trusts a header.
• Portability is bounded, not universal. The portable profile defines exactly what is guaranteed across targets. Outside it, the compiler tells you what differs instead of pretending it does not.
• Uncertainty is reported, not averaged away. Missing metrics render as missing, never as a healthy zero; error budgets carry a band when telemetry export was incomplete; sampled data is labelled sampled.
• Compatibility is computed. forgec compat diffs two bundles and classifies each change by direction and stream; forgec migrate produces a phased plan. Neither guesses.

Full documentation is in docs/; architectural decisions and their alternatives are in docs/decisions/.

Status

0.3.0 was the first public release; the current version is 0.5.0. The API surface is 0.x and will move — pin exact versions.

No profile is certified against this build. RELEASE_MANIFEST.json reports allRequiredProfilesCertified: false:

profile	state on this build
cloudflare-d1, aws-dynamodb	unverified — live evidence exists (15 scenarios, 221 steps, realtime, switching both ways) but is bound to build cfc8286aa3a7, and this is 92d084e2bbea
node-postgres, sqlite-node, runtime-memory	unverified — no evidence on this build

Live evidence is bound to the build it ran against and to a 90-day window. If either moves, the manifest downgrades that profile to unverified on its own rather than carrying the claim forward — so a stale manifest tells you it is stale instead of quietly lying. That is what has happened here: the rule fired and this prose, which used to claim all five were certified, did not follow it down until an audit caught it.

To restore the claim, run pnpm certify against live Cloudflare and AWS endpoints (FORGE_CF_URL/FORGE_CF_WS, FORGE_AWS_URL/FORGE_AWS_WS) and sign the manifest in CI — an unsigned manifest is a draft by its own rule. conformance/certification/latest.json holds the last full run; only the private hostnames are withheld, and they are marked as withheld.

Known gaps are stated as gaps: see the notCertified entries in RELEASE_MANIFEST.json and docs/security-review.md.

Where this lives

Development and releases happen here, at gmackie/forgec — issues, pull requests and the published artifacts all point at this repository, and npm provenance attests to builds from it. ForgeGraph as a whole lives at gmackorg and forgegraf.com; if the compiler moves into that monorepo, the repository URLs move with it in a single commit and this note changes with them. Nothing in the published metadata points at a repository that did not build it.

Management console

The Forge console uses Cloudflare Kumo, React and Effect to manage applications, environment configuration and signed packages stored in an OCI registry. Run it on Cloudflare Workers or Docker with your own authority, storage and credentials; no central service is required.

Contributing

Read CONTRIBUTING.md. The short version: behaviour changes start with a failing test, portability claims start with a conformance scenario, and a claim without evidence does not land.

Security reports go to the process in SECURITY.md, not to the issue tracker.

Licence

Apache-2.0. See LICENSE.