harbour-contracts

The single source of truth for every data shape that crosses a boundary between Isomorph components. Schema-first: hand-written JSON Schema in schema/ is the source; the Go package (gen-go/) and TypeScript package (gen-ts/ → @fourier-labs/harbour-contracts) are generated and committed. No handler, infra stack, or MCP op is built against a shape that does not exist here first.

Layout

The schemas

Runtime resource profiles are a closed contract shared by transformation, artifacts, and well-defined application manifests. The supported profiles are standard, memory-1g, and memory-2g; consumers must reject unrecognized raw CPU or memory overrides.

Two schemas carry logic beyond structural types, generated into helpers:

• error-category.enum.json → IsRetryable(category) (Go) / isRetryable(category) (TS), handling both concrete categories and family prefixes (storage.unsupported-engine.<engine>). Unknown categories fail closed (non-retryable).
• version-state.schema.json → CanTransition(environment, from, to) / IsTerminal(state) (Go) and canTransition / isTerminal (TS), driven by the x-transitions edge list — so control-plane and any consumer agree on legality from one source.
• binding-classification-subject.schema.json and sanitized-binding-evidence.schema.json → canonical length-prefixed SHA-256 preimage/digest helpers plus exact-name, requested-mapping and allocation-receipt validators in Go and TypeScript.
• integration-execute-request.schema.json → IntegrationExecuteInputRules + validateIntegrationExecuteInput(operation, input) (TS) / ValidateIntegrationExecuteInput (Go), derived from each operation's then-block (propertyNames.enum, required, per-field maximum/default). The governance execute route, the app SDK and the kit's local check all refuse a request with the same sentence (limit must be an integer between 1 and 15); the SDK vendors the TypeScript file because it ships with no dependencies.

Workflow

make gen       # regenerate gen-go/ + gen-ts/ from schema/ (Node only — no Go needed)
make verify    # regenerate, then fail if git shows a diff  ← the staleness gate (CI runs this)
make build     # compile-check the generated Go + TS (needs go + local tsc)
make test      # generator determinism + contract-logic tests (Node; Go when installed)

Codegen is Node-only so make gen is reproducible anywhere; a Go toolchain and tsc are used solely to compile-check the output (make build), not to generate it.

Changing a shape

1. Edit the schema in schema/. The category enum and state machine are closed — extend them only by PR to this repo (that PR is where consumers are notified).
2. make gen and commit gen-go/ + gen-ts/ alongside the schema change.
3. CI (make verify) fails any PR whose committed generated code does not match its schema.
4. Do not edit VERSION, package.json's version or CHANGELOG.md: the release version comes from the vX.Y.Z tag pushed after merge (ADR 0050).
5. A shape change is a (contracts) change: it lands via /review + /code-review ultra → /ship.

Consumers should pin both the three-part publish version and the schemasDigest/aiFixturesDigest in contract-release.json. Their CI should validate the canonical fixtures against the pinned generated types or schemas; it must not silently skip validation when the contracts checkout is absent. The npm artifact contains schema/, fixtures/ai/, gen-ts/ and the release manifest, so every TypeScript byte named by the manifest is available from the same release. Go source remains available through the tagged Go module.

generatedGo and generatedTypeScript seal every .go/.ts file in their package directories. gen-go/contract_release.go and gen-ts/contract-release.ts are the only exclusions: those generated files embed the aggregate digests themselves, so including them would create a self-reference with no finite digest. The manifest names both exclusions and their reason; tests reject any different exclusion set and independently recompute every included file and aggregate.

Platform-neutral workload and secret references are identifiers, not general URLs. They use scheme://authority/path with a reviewed additive scheme registry (aws-sm, iam-role, k8s-sa, secretref, spiffe, vault, vault-v2). A new platform extends that registry in a contracts release. Userinfo, ports, percent encoding, query strings, fragments and empty path segments are deliberately unrepresentable, preventing reference fields from becoming a credential or arbitrary-value transport.

The v2 metering schemas are projections linked to existing v1 policy/trace identities. During migration, consumers dual-read v1 and v2 and may dual-write both. Old records are never rewritten; corrections are append-only adjustment or superseding records. Removal of v1 writes requires separately recorded consumer cutover evidence.

Consuming

• Go: go get github.com/Fourier-Labs-AI/harbour-contracts/[email protected]

  Two things make this work, and the second is not the obvious one.

  The publish tag must be 3-part semver. Go and npm require MAJOR.MINOR.PATCH, while this repository records MAJOR.MINOR.PATCH.MICRO. A publishable release therefore requires MICRO to be zero and maps deterministically: repository 0.9.0.0 → package 0.9.0 → publish tag v0.9.0. The optional four-part bookkeeping tag v0.9.0.0 may point at the same commit but does not publish. CI verifies this mapping, the changelog heading and either tag form.

  The repo is private, and Go fetches it from a global cache. Set this once per machine:

  go env -w GOPRIVATE=github.com/Fourier-Labs-AI/*
  git config --global credential."https://github.com/Fourier-Labs-AI".helper '!gh auth git-credential'
  git config --global credential."https://github.com/Fourier-Labs-AI".useHttpPath true
  

  The credential config has to be global and URL-scoped, and that combination is not incidental:

  • It cannot be folder-scoped (includeIf gitdir:…). Go runs git ls-remote inside ~/go/pkg/mod/cache/vcs/…, not inside your repo, so a per-directory helper never applies. This fails identically from /tmp and from inside an Isomorph repo, which makes it look like a bad tag rather than an auth problem.
  • Scoping by URL prefix keeps it off your other GitHub accounts: only github.com/Fourier-Labs-AI/* uses this credential.
  • An SSH insteadOf rewrite is the usual advice and is wrong here unless your SSH key belongs to an account with Fourier org access. Check with ssh -T [email protected] before reaching for it.

  Without the above, go get fails with Repository not found — which reads as a missing tag, not as missing access.

• TS: npm i @fourier-labs/harbour-contracts — published from the tag by CI. The hand-written AI policy resolver (resolver/index.ts) ships in the same package as the @fourier-labs/harbour-contracts/resolver subpath export (package.json exports).

Notes

gen.mjs produces both languages deterministically from Node. Go struct field alignment is not gofmt-normalized by the generator (gofmt is optional hygiene via make fmt); this never affects compilation, and the staleness gate compares raw generator output, so it stays green.