feat(contract): @forgegraph/contract — Effect HttpApi → operation IR compiler #564

Merged

gmackie merged 1 commit from feat/contract-package into main 2026-09-12 02:08:40 +00:00

Conversation 2 Commits 1 Files changed 18 +2252 -65

gmackie commented 2026-09-09 22:32:14 +00:00

Owner

Copy link

What

New workspace package packages/contract (@forgegraph/contract 0.1.0): compile an Effect HttpApi into ForgeGraph's operation contract IR with no hand-authored endpoint, schema, error or auth catalogs.

Phase 1, tasks 1.1–1.7 of the plan: https://7n04n7hhuesf.postplan.dev

Surface

entry	needs effect	contents
@forgegraph/contract / ./ir	no	Zod IR schema, validateContract, fingerprints
./sla	no	leaf-merged SLA resolver with provenance
./effect	peer ≥ 4.0.0-rc.112	compileHttpApi, Sla / IsPublic / Authentication annotations, forgeGraph({...}) helper

Design points

• Identity is semantic: <serviceId>.<group>.<endpoint>; matches the group.endpoint span name the create-gmacko-app template already emits. A route move does not change identity (tested).
• Only public Effect APIs: HttpApi.reflect (identity, middleware, statuses, merged annotations) and OpenApi.fromApi (JSON Schema + components). No AST walking.
• SLA merges per leaf across global → service → api → group → endpoint → environment; every leaf records the level that set it; invalid values fail the build.
• Private by default; Authentication is derived from the security middleware (cookie/basic → user, bearer/header key → service, both → mixed, none → anonymous). An explicit annotation overrides and sets mismatch: true for ForgeGraph to flag.
• Fingerprints are sha256 over canonical JSON; a schema fingerprint covers the transitive closure of referenced components, so it changes exactly when the client-visible shape changes.
• The hub stays Effect-free: it will validate ingested contracts with the ./ir Zod schema (Phase 2).

Verification

• 37 unit tests (pnpm -F @forgegraph/contract test), typecheck and tsc -p tsconfig.build.json clean, oxlint clean of errors.
• Lockfile change is additive only (new importer + effect rc.112 and its deps).

Not in this PR

Ingest endpoint, tables, UI tab (Phase 2) and the template-side annotations + contract.json generation (tasks 1.8–1.10, separate PR in create-gmacko-app).

🤖 Generated with Claude Code

## What New workspace package `packages/contract` (`@forgegraph/contract` 0.1.0): compile an Effect `HttpApi` into ForgeGraph's operation contract IR with no hand-authored endpoint, schema, error or auth catalogs. Phase 1, tasks 1.1–1.7 of the plan: https://7n04n7hhuesf.postplan.dev ## Surface | entry | needs `effect` | contents | |---|---|---| | `@forgegraph/contract` / `./ir` | no | Zod IR schema, `validateContract`, fingerprints | | `./sla` | no | leaf-merged SLA resolver with provenance | | `./effect` | peer ≥ 4.0.0-rc.112 | `compileHttpApi`, `Sla` / `IsPublic` / `Authentication` annotations, `forgeGraph({...})` helper | ## Design points - **Identity is semantic**: `<serviceId>.<group>.<endpoint>`; matches the `group.endpoint` span name the create-gmacko-app template already emits. A route move does not change identity (tested). - **Only public Effect APIs**: `HttpApi.reflect` (identity, middleware, statuses, merged annotations) and `OpenApi.fromApi` (JSON Schema + components). No AST walking. - **SLA** merges per leaf across global → service → api → group → endpoint → environment; every leaf records the level that set it; invalid values fail the build. - **Private by default**; `Authentication` is derived from the security middleware (cookie/basic → user, bearer/header key → service, both → mixed, none → anonymous). An explicit annotation overrides and sets `mismatch: true` for ForgeGraph to flag. - **Fingerprints** are sha256 over canonical JSON; a schema fingerprint covers the transitive closure of referenced components, so it changes exactly when the client-visible shape changes. - The hub stays Effect-free: it will validate ingested contracts with the `./ir` Zod schema (Phase 2). ## Verification - 37 unit tests (`pnpm -F @forgegraph/contract test`), typecheck and `tsc -p tsconfig.build.json` clean, oxlint clean of errors. - Lockfile change is additive only (new importer + `effect` rc.112 and its deps). ## Not in this PR Ingest endpoint, tables, UI tab (Phase 2) and the template-side annotations + `contract.json` generation (tasks 1.8–1.10, separate PR in create-gmacko-app). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gmackie added 1 commit 2026-09-09 22:32:14 +00:00

feat(contract): add @forgegraph/contract, the Effect HttpApi → operation IR compiler ... b916218360

New workspace package that turns an Effect `HttpApi` into ForgeGraph's operation
contract IR without any hand-authored endpoint, schema, error or auth catalog.

- `./effect`: `compileHttpApi(api, { serviceId, globalSla?, serviceSla?, environmentSla? })`
  built on `HttpApi.reflect` for identity, middleware, success/error statuses and
  merged annotations, and on `OpenApi.fromApi` for JSON Schema. No private Effect
  internals are read.
- Annotation vocabulary as `Context.Reference`s with defaults: `Sla` ({}),
  `IsPublic` (false), `Authentication` (derived from security middleware unless
  overridden; an override sets `mismatch: true`).
- `./sla`: leaf-merged resolution global → service → api → group → endpoint →
  environment with per-leaf provenance and value validation.
- `./ir`: Effect-free Zod schema + `validateContract` (shape, unique ids,
  id/parts agreement, per-operation and contract fingerprints, dangling $refs)
  so the ForgeGraph server can validate ingested contracts without Effect.
- Stable semantic ids `<serviceId>.<group>.<endpoint>` match the `group.endpoint`
  span names the create-gmacko-app template already emits.

`effect` is an optional peer (≥ 4.0.0-rc.112, pinned to the template catalog).
37 unit tests. Plan: https://7n04n7hhuesf.postplan.dev (Phase 1, tasks 1.1–1.7).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

gmackie force-pushed feat/contract-package from b916218360 to 47a91edcff 2026-09-09 22:36:47 +00:00 Compare

gmackie commented 2026-09-09 22:37:54 +00:00

Author

Owner

Copy link

Preview environment is live: https://pr-564-forgegraph.forgegraf.com

Deployed b9162183 with the beta stage's environment. It redeploys on every push and is destroyed when this PR closes.

Preview environment is live: https://pr-564-forgegraph.forgegraf.com Deployed `b9162183` with the beta stage's environment. It redeploys on every push and is destroyed when this PR closes.

gmackie force-pushed feat/contract-package from 47a91edcff to c2f1c4ef6e 2026-09-09 22:47:52 +00:00 Compare

gmackie commented 2026-09-09 22:52:04 +00:00

Author

Owner

Copy link

Preview environment is live: https://pr-564-forgegraph.forgegraf.com

Deployed c2f1c4ef with the beta stage's environment. It redeploys on every push and is destroyed when this PR closes.

Preview environment is live: https://pr-564-forgegraph.forgegraf.com Deployed `c2f1c4ef` with the beta stage's environment. It redeploys on every push and is destroyed when this PR closes.

gmackie referenced this pull request 2026-09-09 23:45:26 +00:00

feat(contracts): ingest published API contracts and gate changesets on them #567

gmackie referenced this pull request 2026-09-09 23:50:29 +00:00

feat(contracts): API tab showing declared operations and what each stage serves #568

gmackie referenced this pull request 2026-09-09 23:53:51 +00:00

feat(cli): fg contract publish — send an app's compiled contract to ForgeGraph #569

gmackie merged commit 0e7be2a33a into main 2026-09-12 02:08:40 +00:00

gmackie referenced this pull request from a commit 2026-09-12 02:08:42 +00:00

Merge pull request 'feat(contract): @forgegraph/contract — Effect HttpApi → operation IR' (#564) from feat/contract-package into main

gmackie referenced this pull request 2026-09-14 02:33:22 +00:00

fix(deploy): stop Corepack prompting on the runner's pty after a reboot #574

gmackie referenced this pull request from a commit 2026-09-14 02:33:23 +00:00

fix(deploy): stop Corepack prompting on the runner's pty after a reboot

gmackie referenced this pull request from a commit 2026-09-14 04:04:56 +00:00

fix(deploy): make main deployable again after the contract package landed

gmackie referenced this pull request 2026-09-14 04:04:56 +00:00

fix(deploy): make main deployable again after the contract package landed #575

gmackie referenced this pull request 2026-09-14 05:22:03 +00:00

ci: build the web app in CI, on the runner with memory for it #576

gmackie referenced this pull request from a commit 2026-09-14 05:22:04 +00:00

ci: build the web app in CI, on the runner with memory for it

gmackie referenced this pull request from a commit 2026-09-14 05:38:24 +00:00

merge: bring main into feat/contract-operations-tab

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

community

Community process, governance, contribution UX

  

docs

Documentation improvements

  

forgegraph:public-update

Publish approved PR lifecycle updates to the ForgeGraph public feed.

  

good first issue

Suitable for first-time contributors

  

help wanted

Extra attention is needed; maintainers welcome a PR

No labels

community

docs

forgegraph:public-update

good first issue

help wanted

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

gmackie/ForgeGraph!564

No description provided.