VERSIONING

August 23, 2026 · View on GitHub

STATUS: ACTIVE CONTRACT (written 2026-07-03). This document is the human-maintained source of truth for which published package versions speak the wire of the live mainnet program, and the release contract every future breaking change must follow. It complements VERSIONS.md (the P6.5 on-chain surface-revision mechanism — how a client detects what is deployed); this file is the off-chain matrix — which npm versions a consumer may pin, and what happens to old pins when the program changes.

Program: agenc-coordination — HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK, Solana mainnet. Upgradeable (2-of-3 multisig upgrade authority, see UPGRADE_AUTHORITY.md); one program ID across every surface revision, so the address alone never tells you the wire format — the matrix below and getDeployedSurface do.

1. Support matrix

1.1 Current compatible set (as of 2026-07-22)

The live program wire is the full 101-instruction revision-5 surface (surface_revision = 5, audit hardening; deployed 2026-07-22 via the Squads 2-of-3, executable SHA-256 049a66e30da166c1e02ee379993425c32386f774fd9ff8861153e21900b496f2), with 405 program error variants (6000–6404). It supersedes the prior 99-instruction revision-4 surface (surface_revision = 4, batch-4 goods; live 2026-07-09 → 2026-07-22, slot 431918664). Its gate shapes descend from the P1.2 hardened open roster build (deployed 2026-07-03, slot 430491216): moderation-consumption gates at 9/14/13 accounts with a required trailing moderator: Pubkey argument. The batch-2 upgrade (2026-07-05, surface_revision = 2) was additive — 90 → 94 instructions (store identity lifecycle + moderation_heartbeat) and the dispute referrer legs — with no flag-day wire change: every P1.2-wire client keeps working, which is why the sdk range below spans several minor lines. The batch-3 upgrade (2026-07-05, surface_revision = 3) added the contest model (94 → 96 instructions, submission-rent return + ghost-split + reclaim_terminal_claim) with two narrow additive ABI extensions (optional accounts appended). The batch-4 upgrade (2026-07-09, surface_revision = 4) added the goods market (96 → 99 instructions: create_goods_listing, purchase_good, update_goods_listing — rivalrous direct-buy with per-unit SaleReceipt provenance and the protocol fee on every sale), fully additive; the goods surface is revision-gated, so pre-0.11 SDKs simply do not expose it. The exact live wire artifact is revision 5 (101 instructions / 43 accounts / 102 events / 405 errors). The committed workspace IDL SHA-256 is f8eb548c6c521a4a327bc2adf1cd8920fdf0f15597ae831fb7a1824bc31efd2e (instruction docs only vs the prior 8cfd094d… hash; ABI unchanged). Current generated references at reference/INSTRUCTIONS.md and reference/ERRORS.md now describe the live 101-instruction revision-5 surface. npm run check:idl-reference keeps those references aligned with the committed IDL.

The revision-4 published set below now fails closed against the live revision-5 program; the coordinated revision-5 client set is in §1.1.1. The prior revision-4 wire-compatible published set was:

Package	Compatible range	Notes
`@tetsuo-ai/protocol`	0.3.x (latest 0.3.0)	generated IDL + types for the 99-ix surface (354 error variants); 0.3.0 shipped with batch-4
`@tetsuo-ai/marketplace-sdk`	0.8.x – 0.11.x (latest 0.11.0)	0.8.0 = the P1.2 wire cutover; 0.9.0 adds the additive batch-2 store surface; 0.10.0 adds the batch-3 contest facade; 0.10.1 decoder hardening; 0.11.0 adds the batch-4 goods facade + the revision-gated `goods` capability
`@tetsuo-ai/marketplace-react`	0.4.x (latest 0.4.1)
`@tetsuo-ai/marketplace-tools`	0.4.x (latest 0.4.0)
`@tetsuo-ai/marketplace-mcp`	0.4.x (latest 0.4.0)
`@tetsuo-ai/marketplace-moderation`	0.1.x (latest 0.1.0)	first published alongside the roster work
`@tetsuo-ai/agenc-cli`	0.2.x (latest 0.2.0)	CLI against the revision-4 99-ix surface
`@tetsuo-ai/agenc-worker`	0.1.x (latest 0.1.1)	worker daemon against the revision-4 99-ix surface
`@tetsuo-ai/store-core`	0.5.x or exactly 0.6.0	0.5.x speaks the same wire; 0.6.0 is additive; 0.6.1 crosses the revision-5 boundary despite sharing this pre-1.0 minor
`create-agenc-store`	0.5.x or exactly 0.6.0	scaffolds the revision-4 template pins; 0.6.1 is reserved for the coordinated revision-5 cutover

These rows are wire-admissible version buckets, not a Cartesian product. Installed packages must also satisfy one another's published dependency and peer-dependency ranges. For example, SDK 0.11 speaks the revision-4 wire by itself, but the published React 0.4.1 artifact declares SDK ^0.8.0; that pair is not a coherent npm installation and must not pass a production-readiness check.

Every published major/minor below these ranges fails closed against mainnet today (transactions reject at Borsh decode or account resolution — no funds at risk, but the flow is down). See §1.2 for exactly which upgrade broke which range.

1.1.1 Revision-5 coordinated client set

This repository contains the following coordinated revision-5 clients. The store-core and create-agenc-store packages live in their separate store repositories; they are not agenc-protocol workspace packages. The revision-5 program cutover executed on 2026-07-22, so these clients, not the revision-4 pins above, speak the live wire. Scoped packages in this table were on npm at these versions when checked 2026-08-23:

Package	Published (2026-07-22 train)	Coordination note
`@tetsuo-ai/protocol`	0.4.0	101-instruction revision-5 IDL/types
`@tetsuo-ai/marketplace-sdk`	0.12.0	revision-5 generated client; its changed hire/activation writes reject revision 4
`@tetsuo-ai/marketplace-react`	0.5.0	breaking revision-5 input and SDK-peer cutover
`@tetsuo-ai/marketplace-tools`	0.5.0	depends on SDK `^0.12.0`
`@tetsuo-ai/marketplace-mcp`	0.5.0	depends on tools `^0.5.0` and SDK `^0.12.0`
`@tetsuo-ai/marketplace-moderation`	0.2.0	strict JSON canonicalization plus capability-gated complete semantic-v2 payloads; 0.1.0 remains the immutable legacy-v1 release
`@tetsuo-ai/agenc-worker`	0.2.0	depends on SDK `^0.12.0`
`@tetsuo-ai/agenc-cli`	0.3.0	pins SDK `^0.12.0` and worker `^0.2.0`
`agenc-cli` (unscoped alias)	workspace 0.3.0; npm 0.2.0	alias workspace tracks 0.3.0; npm still served 0.2.0 as of 2026-08-23
`@tetsuo-ai/store-core`	0.6.2	external store repo; published 0.6.2 per CHANGELOG 2026-07-22 (npm 2026-08-23)
`create-agenc-store`	0.6.1	external scaffolder; npm still 0.6.1 as of 2026-08-23

Every revision-5 package requires Node 22.23.1 or newer. Node 20 is EOL and is intentionally outside this release train's support contract.

agenc init and agenc promote know this set. promote selects it only when finalized chain evidence reports surface revision 5; revision 4 selects only the published set above. The sets are never unioned.

REVIEWED_MAINNET_RELEASES in packages/agenc-cli/src/promote.ts still lists only revision 4. The support matrix already has revision 5 pins, but identity matching still needs the observed 2026-07-22 ProgramData address, slot, vault, executable SHA-256, and source commit before promote will treat a revision-5 RPC as a reviewed release. Do not invent those values.

1.1.2 Coherent installed combinations

agenc promote reads these relationships from the installed package manifests and evaluates them with npm SemVer rules. A package can be absent when the application does not use it. If it is present, its manifest must be readable, well-formed, versioned, and coherent with every required first-party dependency or peer:

Surface	Installed source artifact	Required coherent first-party peer/dependency
revision 4	React `0.4.1`	SDK `^0.8.0`
revision 4	tools `0.4.0`	SDK `^0.8.0`
revision 4	MCP `0.4.0`	tools `^0.4.0` and SDK `^0.8.0`
revision 4	worker `0.1.1`	SDK `^0.8.2 \|\| ^0.9.0`
revision 4	store-core `0.6.0`	React `^0.4.0` and SDK `^0.8.0`
revision 5	React/tools/worker `0.5.0`/`0.5.0`/`0.2.0`	SDK `^0.12.0`
revision 5	MCP `0.5.0`	tools `^0.5.0` and SDK `^0.12.0`
revision 5	external store-core `0.6.2`	React `^0.5.0` and SDK `^0.12.0`

This means a full revision-4 installation containing all published consumers uses SDK 0.8.2 (or another version admitted by every installed range), even though SDK 0.9–0.11 remain valid for applications whose installed consumers declare compatible ranges. Revision 5 has one coordinated combination: SDK 0.12 with the published train in §1.1.1.

1.2 Break-event history (why this document exists)

Date	Event	Program surface	Gate shapes	What broke (fails closed since that date)	Deprecation window given
2026-06-11	Full-surface upgrade (Phase 9, `MAINNET_ROLLOUT_RUNBOOK.md`)	25 ix → 84 ix, `surface_revision` stamped FULL	—	sdk 0.3.0 Borsh-broke; templates in the wild still scaffolded that pin	ZERO — no announcement preceded the deploy
2026-07-02	WP-A1 roster gates	84 ix (gate hardening)	8/13/12 accounts	sdk ≤0.6.x, react ≤0.2.x, tools+mcp ≤0.2.0	Same-day lockstep republish (sdk 0.7.0, react/tools/mcp 0.3.0, store 0.3.0); no advance notice
2026-07-03	P1.2 hardened open roster (`P1_2_OPEN_ROSTER_SPEC.md`)	84 ix → 90 ix	9/14/13 accounts + required trailing `moderator` arg	sdk 0.7.x, react/tools/mcp 0.3.x, store-core ≤0.4.x	Same-day lockstep republish (§2.6 runbook pattern): sdk 0.8.0, react/tools/mcp 0.4.0, store-core/create 0.4.0
2026-07-05	Batch-2 store + heartbeat	90 → 94 ix, `surface_revision = 2`	additive (no flag-day gate change)	none (old pins keep working)	sdk 0.9.0 additive facade
2026-07-05	Batch-3 contest (`design/batch-3-contest-tasks.md`)	94 → 96 ix, `surface_revision = 3`	additive optional accounts	none	sdk 0.10.0 / 0.10.1 additive facade
2026-07-09	Batch-4 goods (`design/batch-4-goods.md`)	96 → 99 ix, `surface_revision = 4`	goods handlers require rev ≥ 4	none for pre-goods flows; goods needs sdk ≥ 0.11.0	sdk 0.11.0, protocol 0.3.0
2026-07-22	Revision-5 audit hardening (executed; `REVISION_5_CUTOVER.md`)	99 → 101 production ix, `surface_revision = 5`	coordinated account/argument hardening across hire, claim, settlement, cancellation, goods, staking, skills, and governance paths; the three hire/activation writes use explicit v2 discriminators; the O(1) bid-accept redesign added `promote_bid` / `demote_ineligible_best` / `settle_dispute_claim`	sdk ≤0.11.x and the corresponding old first-party clients fail closed on changed writes; v2 clients also reject the revision-4 program	flag-day release: protocol 0.4.0, sdk 0.12.0, react 0.5.0, tools/MCP 0.5.0, moderation/worker 0.2.0, CLI 0.3.0, store-core/create 0.6.1; every first-party writer and hosted transaction builder staged before the paused cutover

The 2026-06-11 row is the motivating failure: a flag-day wire change shipped with no deprecation window while the old sdk pin was still being scaffolded by public templates. The contract in §2 exists so that never happens again.

2. The contract going forward

2.1 Capability detection is REQUIRED in first-party consumers

Every first-party consumer (react/tools/mcp packages, store-core, the store templates, agenc.ag, the marketplace kit) MUST gate surface-dependent flows on the SDK's capability API instead of assuming a deploy state:

getDeployedSurface(rpc) — reads the live ProtocolConfig.surface_revision size-tolerantly and returns a CapabilitySet (never throws on old layouts).
capabilitiesForRevision(revision) — pure mapping, for tests/offline use.
assertCapability(surface, capability) — throws a typed SurfaceNotDeployedError before a transaction that the cluster would reject.

All three are exported from the @tetsuo-ai/marketplace-sdk root (implementation: packages/sdk-ts/src/facade/surface.ts, re-exported in packages/sdk-ts/src/index.ts). Mechanism details and the revision table: VERSIONS.md.

2.2 Breaking wire changes are announced BEFORE the program deploys

A breaking wire change (instruction args, account order/count, seeds, layout) MUST, before the on-chain deploy:

update the §1 support matrix in this file (new row in §1.2, new ranges in §1.1);
carry an explicit breaking-change announcement in the release notes of the npm versions that implement the new wire, and in the marketplace binary release notes (tetsuo-ai/agenc-marketplace-releases).

The model is the P1.2 cutover choreography — MAINNET_ROLLOUT_RUNBOOK.md §2.6: packages regenerated and tested on-branch first, program upgrade, then immediate lockstep publish to minimize the skew window, then dependent services (attest.agenc.ag) redeployed on the new client.

2.3 Deprecation-window policy

Additive changes (new instruction, appended account field behind a migration, new SDK export — e.g. sdk 0.8.1's settlementReceiptUrl): no window needed. Publish as a minor/patch; old clients keep working.
Flag-day wire changes (old clients fail closed, as in all three §1.2 events):
- ALL first-party packages are republished the same day (lockstep), per §2.6 of the runbook;
- the old majors/minors are documented as fail-closed immediately in §1.2 — no grace period is promised for the old wire, because the program cannot serve both shapes;
- the quickstart and the store templates/create-agenc-store pins are bumped the same day, so nothing public scaffolds a dead pin (the 2026-06-11 failure mode).
On-chain account layouts remain append-only with migrations — that policy lives in VERSIONS.md ("Deprecation policy") and is unchanged.

2.4 Template/starter pins must sit inside the matrix (enforced)

The agenc-store-templates repo (source of the three store templates and the create-agenc-store scaffolder) enforces this mechanically: npm run check:pins (scripts/check-pins.mjs) asserts every @tetsuo-ai/marketplace-* and @tetsuo-ai/store-core pin's minimum resolvable version falls inside the §1.1 ranges, and fails with instructions to update its SUPPORT_MATRIX constant alongside any lockstep republish.

CI is deliberately disabled in these repos (cost), so this check runs as part of the pre-release gate (the local check-script pass before any publish/deploy), not GitHub Actions. A lockstep republish (§2.3) MUST include: bump template pins → update the script's SUPPORT_MATRIX → npm run check:pins green → publish.

3. Maintenance

Update this file in the same release window as any of:

a program deploy that changes the wire (add a §1.2 row, rewrite §1.1);
a lockstep npm republish (rewrite §1.1 ranges);
a coordinated candidate-version change (rewrite §1.1.1 and the CLI matrix);
a change to the capability-detection exports (§2.1 links).

Related: VERSIONS.md (on-chain surface detection), MAINNET_MAINLINE.md (live deployment record), MAINNET_ROLLOUT_RUNBOOK.md (deploy choreography, §2.6 flag-day pattern), P1_2_OPEN_ROSTER_SPEC.md (the current wire's spec).