feat(meta): the /meta item read serves the version token, If-None-Match: * pins a first write, and the 409 carries currentVersion

[objectstack-fleet]

Fixes #22114

The client half, objectstack-ai/objectui#11773 (PR objectstack-ai/objectui#11826), is unlocked by the published release that carries this change, not by this merge.

Clause-②: yes (narrowing)

yes is for the widened read member, request header and conflict field. The (narrowing) arm is for two request shapes on PUT /meta/:type/:name that were answered 200 and are now refused 400 VALIDATION_ERROR: an If-None-Match value other than *, and If-None-Match beside If-Match. The changeset carries the BREAKING line with the remedy (send * alone, never beside If-Match), and the ADR-0087 disposition not-required (no-migration-prescription): no key, export, response field or stored shape moves, no first-party sender puts If-None-Match on a PUT, and which precondition the client meant is a choice no conversion entry can derive. The level stays minor, because .changeset/pre.json is absent on origin/main (51290bca2).

What changes

ADR-0008 says clients pass If-Match with the version they read, and a client can send only a token it was served. Before this PR, only a save receipt served one. So the first save after a load could not be pinned, and two editors who each loaded and saved once overwrote each other. This PR closes the three gaps the card names, at the /meta door. Spec end and runtime end land together.

1. The read serves the token. GET /meta/:type/:name now carries a version member, declared on GetMetaItemResponseSchema. It is the keyed token of the stored row that a save to this item compares against, at the read's scope (the caller's organization partition and ?package=) and lifecycle (?state=draft reads the draft row, the plain read the active row). It comes from the same producer as the save receipt's version and covers the same row, so a read after a save serves the receipt's token byte for byte. null means no stored row is there, so the next save is a create.
2. "Expect no row" can be said. If-None-Match: * on PUT /meta/:type/:name saves only where no row of the target lifecycle exists. Once a row exists it is refused 409 METADATA_CONFLICT. This is the parentVersion: null pin that SaveMetaItemRequestSchema already declared, now reachable over HTTP. A save with neither header is last-writer-wins, as before.
3. The conflict body carries the current version as data. The 409 of the /meta item write doors now carries currentVersion beside today's unchanged sentence: the token the sentence names, or null when no row of the target lifecycle exists. The body shape is declared as MetadataConflictErrorSchema, and the SDK exposes the field as err.details.currentVersion with no client change.

Where each half lands

Package	Change
@objectstack/spec	GetMetaItemResponseSchema.version (string, null or absent); MetadataConflictErrorSchema plus its two type aliases; the parentVersion describe now names If-None-Match: *; the receipts' version describes are corrected (below). Generated artifacts regenerated (authorable surface, json-schema manifest, api-surface, export origins, declaration map, reference docs, strictness-ledger counts).
@objectstack/metadata-protocol	One head read, storedHeadAt, is shared by the save door's token check and the read's version (readVersionToken), so no second token derivation exists. getMetaItem serves version on the draft branch and on the active branch. metadataConflictRefusal, the single builder all four item doors (save, publish, rollback, reset) answer through, now also sets currentVersion.
@objectstack/rest	PUT /meta/:type/:name reads its pin through metaSavePreconditionPin: If-Match as before, If-None-Match: * as the expect-no-row pin. A comment on the cached arm records why its ETag is not the token.
@objectstack/types	One METADATA_CONFLICT arm in structuredCodeAnswer serializes currentVersion into the flat ADR-0112 body. This is outside the claim's declared file surface, and the reason is the repo's own rule: error-response.ts says a new bespoke code arm "belongs in structuredCodeAnswer, where both doors read it", and that function moved to @objectstack/types. The arm keys on the code and on a stated currentVersion, so a METADATA_CONFLICT that states none keeps today's body byte for byte.

No objectui change. No change to packages/client either: the read type is the spec's own GetMetaItemResponse, and the flat conflict body already reaches err.details.

Decisions taken, with the measurement behind each

• What version names: the address of the save, not the row whose content was served. A read falls back from the caller's organization to the environment-wide row (ADR-0005), and from a package's own row to the package-less one (ADR-0048). A save does not fall back; it writes its own partition. A token for a row the save would not overwrite would be refused by that save every time. So such a read serves null, which is the honest create pin. This is pinned at the protocol: an env-wide row read under an organization serves null, and parentVersion: null is then honoured once and refused once.
• Where version is absent:
  • On the cached published-value branch, which is the default plain read. That branch already publishes no lock, and the schema's existing contract sends OCC readers to the uncached path.
  • On ?preview=draft, a render path that mixes two lifecycles.
  • Both cases are declared in the describe, where absence means "not published here" and never "no row".
• The ETag (H3). The cached arm's ETag stays the cache validator and is not the token. That validator is simpleHash over the scope (organization, locale) plus the served bytes, folded with the caller's field-visibility fingerprint (ADR-0106 D3) and the public-form intake fingerprint. The version token moves with none of locale, visibility or served-but-unstored bytes. An item served from code has a validator but no token. getMetaItemCached's own comment forbids hashing "a version marker" instead of the content, with get-meta-item-cached-etag-scope.test.ts §3 as its pin. So triage's "an ETag equal to it where the door sets one" cannot hold on the one branch that sets one without breaking that validator. The body member satisfies the card's "a body member, an ETag, or both". No new ETag is minted on the uncached arms: a strong validator shared across locale and mask variants would be false, and the runtime dispatcher serves the same envelope with no such header. The pin is meta-item-version-token-occ.test.ts: the cached arm has no version and its ETag is not token-shaped.
• If-None-Match takes * alone, and never beside If-Match.
  • Measured readers and senders before this PR. On this route, rest-server.ts read if-none-match only on the cached GET. The adapters and plugin-hono-server read it nowhere. The SDK sends it only from getCached (a GET). objectui's useETagCache has zero in-repo callers.
  • A non-* value is refused 400 VALIDATION_ERROR, because a write-unless-the-head-is-one-of-these condition is one this door does not evaluate. Silently dropping a precondition the caller asked for would write that caller unguarded.
  • The pair If-Match plus If-None-Match: * is refused 400. Under RFC 9110 §13.2.2 both are evaluated, so the pair can never hold, and a 409 would send the caller round a re-read that serves a token it would pair with * again.
• The receipts' version describes are corrected (seat round 1). SaveMetaItemResponseSchema.version, PublishMetaItemResponseSchema.version and the package publish door's published[].version (PublishPackageDraftsResponseSchema, the same receiptVersion token, so the same falsehood in the same file) said "Content hash … currently emitted as sha256:" and "409 metadata_conflict". They now say the token is the keyed hmac-sha256: digest of the stored content hash, never the hash itself, and that the conflict is 409 METADATA_CONFLICT. Only description text moves. The reference docs are regenerated; no spec test reads these describes, so none is pinned.
• currentVersion is relayed as null, not dropped. null is the answer "no row". The arm therefore reads presence, not truthiness. The record-level CONCURRENT_UPDATE arm reads truthiness, and its producer never states null.

Tests

All pins are at the HTTP door on the real stack (better-sqlite3 :memory:, the real sys_metadata* objects, the real ObjectStackProtocolImplementation, the real routes). Every refusal pin asserts the ADR-0112 code and the HTTP status, and reads the store to show the refused write did not land.

packages/rest/src/meta-item-version-token-occ.test.ts:

• ?state=draft serves the draft receipt's version, which survives GetMetaItemResponseSchema.parse.
• Read, then save with the served token: 200. The next read serves the new receipt's token.
• Two readers save in turn: the second gets 409. Its currentVersion equals the winner's receipt and the next read's version, the sentence is unchanged, and MetadataConflictErrorSchema parses the body. The loser re-pins from currentVersion and is accepted.
• If-None-Match: *: a first draft gets 200. Once a draft exists it gets 409, with currentVersion equal to the draft's token.
• After a publish (no draft row): a held If-Match gets 409 with currentVersion: null, and If-None-Match: * writes the next draft.
• Control: with neither header, the second writer wins and both saves get 200.
• Active row, uncached read: it serves the active receipt's token, and If-None-Match: * pins the create. An item registered in code serves version: null.
• The reset door's 409 carries currentVersion too.
• The cached arm publishes no version.
• If-None-Match beside If-Match, or set to an entity-tag, a weak wildcard, a list, or empty: 400 VALIDATION_ERROR, nothing written. A wildcard with surrounding whitespace is still the wildcard.

Other suites:

• packages/metadata-protocol/src/protocol.served-content-hash.test.ts: read token equals receipt token, keyed, never the stored hash; null at an empty save address; no version on previewDrafts; the refusal states currentVersion.
• packages/rest/src/error-response-structured-arm-door-parity.test.ts: two parity cases (a token, and null) plus a control with no currentVersion, which keeps the passthrough body.
• packages/rest/src/error-response-sandbox-arm-message.test.ts: the arm joins the derived census.
• packages/spec/src/api/meta-item-response-shapes.test.ts: both schemas at runtime and at the type level.

Readings (repository objectstack-ai/objectstack)

Round 1, on the merged head. origin/main 51290bca2 was merged through bash scripts/pm/os-regen-merge.sh as merge commit 0bb0202bc, with parents 8f04870ef (this branch) and 51290bca2 (main). It was a clean merge: main touched none of this diff's files, and step 2 kept the branch's bytes of the 8 routed artifacts main did not move. After it came the describe fix (3950502c6) and the docs regeneration (54ae811d4). gen:schema did not run in MERGE state.

• Gates on the merged head 54ae811d4. node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 113 families against merge base 51290bca2. All 113 ran, each exit code captured before any pipe.
  • Two first readings were exit 3, PREREQUISITE NOT MET (nothing measured): check:skill-examples (no client / client-react dist) and check:dual-build-cjs-loads (37 packages with no dist). The recreated worktree had built only this diff's closure. Both read exit 0 once the battery's own full build had run.
  • --ran reconciliation: 113 derived, 113 run, 0 NOT-MEASURED, 0 UNRUN, a derived zero.
  • check:adr-0087-registration reads 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition … [BREAKING+clause-②-narrowing] not-required (no-migration-prescription). check:changeset-no-major reads no major bump. check:generated reports all 15 artifacts up to date.
• Suites on 54ae811d4, under the verify lock, --maxWorkers=2, after rebuilding the closure on the merged tree:
  • @objectstack/spec meta-item-response-shapes.test.ts + protocol.test.ts: 197 tests passed.
  • @objectstack/metadata-protocol protocol.served-content-hash.test.ts: 27 passed.
  • @objectstack/rest meta-item-version-token-occ.test.ts: 15 passed; --project repo: 5 files, 191 passed and 1 skipped.
  • @objectstack/spec and @objectstack/rest typecheck: exit 0.
• .changeset/pre.json is absent at origin/main 51290bca2, read at this push. The contents API answers 404, against a 200 for .changeset/config.json at the same ref as the control.

Round 0, on the pre-merge head (base 54ace18c6).

• Gates. Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at head 8f04870ef: 113 families, all run there, each exit code captured before any pipe, 113 of 113 exit 0. The --ran reconciliation reads 113 derived, 113 run, 0 NOT-MEASURED, 0 UNRUN ("a DERIVED zero — all 113 recorded an exit code"). The list includes check:dispatcher-error-vocabulary, check:route-envelope, check:durability-log-level, check:engine-double-contract, check:query-options-erasure, check:spec-parsed-alias, check:adr-0087-registration, check:changeset-no-major, check:nul-bytes, check:type-check-coverage / -debt, and the spec check:* set including check:generated (all 15 artifacts up to date).
• Package suites, real output. All runs used --maxWorkers=2 under the shared verify lock, with each package's built dependency closure.
  • At 12a0d8525:
    • @objectstack/types: test and typecheck exit 0.
    • @objectstack/metadata-protocol: typecheck exit 0; test 221 files passed and 3 skipped, 28243 tests passed.
    • @objectstack/rest: typecheck exit 0, including check:test-typecheck (0 debt); --project local 261 files and 4929 tests passed.
  • At e5e7817b8:
    • @objectstack/spec: typecheck exit 0; test 622 files and 18583 tests passed.
    • @objectstack/client: typecheck exit 0.
    • @objectstack/runtime: the 7 /meta item-read and parity suites, 812 tests passed. The dispatcher's item read serves the same protocol envelope, so it carries version too.
  • At 8f04870ef: @objectstack/rest --project repo 5 files passed. Its first run reddened the sandbox-arm census on METADATA_CONFLICT, which is the census working as designed; the arm now has its row.
• Lint (a proven narrowing; the repo-wide pnpm lint is CI's). eslint --no-inline-config --format json over the 9 changed .ts files: 9 files, 0 errors, 0 warnings, with no ignore-pattern warning, so all 9 are inside the config's population. eslint --print-config shows no parserOptions.project or projectService, and eslint.config.mjs states it never enables type-aware linting. So this diff cannot move a verdict on an untouched file.
• Ablations (one-off, not kept). Each leg went through scripts/ablation-replace.mjs (anchor hit 1 to 0, blob changed), and the dist legs through scripts/ablation-dist-preflight.mjs (marker present in 2 built files, then absent after the restore and rebuild). The tree reads git diff HEAD empty afterwards.
  • R, the REST door ignoring If-None-Match: * (source): meta-item-version-token-occ.test.ts 2 failed of 15.
  • P, the draft read serving no version (rebuilt metadata-protocol dist): the REST door test 5 failed of 15; protocol.served-content-hash.test.ts 1 failed of 27.
  • T, the @objectstack/types arm never firing (rebuilt types dist): 9 failed of 73 across the door test and the parity test.
• .changeset/pre.json: absent at origin/main 15ec50e52, read before opening this PR. The changeset is a plain minor for @objectstack/spec, @objectstack/metadata-protocol, @objectstack/rest and @objectstack/types.
• The branch is 2 commits behind origin/main (15ec50e52). Neither commit touches a file this diff touches, generated shards included. It was not merged; the queue rebuilds on main.

Acceptance notes

• Cost. A read that serves a stored row now makes one extra keyed findOne for the save address's head. This includes the cached arm's internal getMetaItem call, whose envelope discards it. A read that served no stored row makes no extra call.
• Not covered by this PR.
  • GET /meta/:type/:name/layers does not serve version. It is the diagnostic view, and Studio's designers edit from ?state=draft.
  • The runtime dispatcher's PUT /meta reads neither If-Match nor If-None-Match, and no host in this repository routes /meta writes to it (measured).
    • handleMetadataRequest(deps, path, _context, method, body, query) (packages/runtime/src/domains/meta.ts:874) takes no header argument.
    • The PUT branch (:1274) calls protocol.saveMetaItem({ type, name, item, organizationId, writeFace: 'meta-dispatch', ...packageId }) (:1430–:1434), with no parentVersion and no mode.
    • The file has 0 occurrences of if-match, if-none-match or parentVersion.
    • The shipped hosts here, objectstack serve and os dev, mount createRestApiPlugin (packages/cli/src/commands/serve.ts:4508–:4511) and then createDispatcherPlugin (:4519–:4535).
    • The dispatcher plugin mounts explicit routes only, and mounts no ${prefix}/meta route (0 matches). Its own comment says "the standalone / os dev server mounts ONLY the explicit routes here" (packages/runtime/src/dispatcher-plugin.ts:1283–:1285). So /meta writes on those hosts are the REST door's.
    • The ${prefix}/* catch-all that does reach domains/meta.ts is @objectstack/hono's createHonoApp (packages/adapters/hono/src/index.ts:725, :739). No app, example or package in this repository calls it.
    • The dispatcher plugin's comments name it as what "the cloud hosts mount underneath" (dispatcher-plugin.ts:1321). The cloud runtime is not in this session, so whether a cloud host's PUT /meta reaches the catch-all before RestServer is NOT MEASURED. This is for the seat to file separately if it is reached.
  • GET /meta/:type/:name?package=all hands the protocol the literal all, while the save door drops it. So such a read serves version: null for a package-less row the save would write. This is a read-only observation.
• finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128, the package-less draft path. The seat filed it from this PR's out-of-scope finding. A second package-less PUT /meta/view/NAME?mode=draft, sent with no If-Match, over an item whose active row is package-bound, answers 409 METADATA_CONFLICT. The save door's head read asks for the package-unbound draft, while the repository bound the draft to the active row's package. This PR's read token follows the same head read (storedHeadAt). So on that path, until finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128 lands, ?state=draft serves version: null while a draft exists. The describe stays as written: the change finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128 carries makes it true there too, at the one shared head read.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/metadata-protocol, @objectstack/rest, @objectstack/spec, @objectstack/types, touching 31 documentable anchor(s). ⚠️ 5 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/authorable-surface/api.json, packages/spec/declaration-map/api.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

31 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 8fc50b7647d30db2a0837877cf251c1163a3239e.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 5 changed file(s) yielded no anchor (packages/spec/api-surface/api.json, packages/spec/authorable-surface/api.json, packages/spec/declaration-map/api.json, …) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 143 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 8fc50b7647d30db2a0837877cf251c1163a3239e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4f51f8374f71df82b70ea92fd6c83d733e6ec14a — the merge of head e2a28fadf1c02a48c965f0303776872e1a323b79 into base 8fc50b7647d30db2a0837877cf251c1163a3239e, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 4f51f8374f71df82b70ea92fd6c83d733e6ec14a && git checkout 4f51f8374f71df82b70ea92fd6c83d733e6ec14a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8fc50b7647d30db2a0837877cf251c1163a3239e e2a28fadf1c02a48c965f0303776872e1a323b79 && git checkout -B drift-repro 8fc50b7647d30db2a0837877cf251c1163a3239e && git merge --no-ff e2a28fadf1c02a48c965f0303776872e1a323b79

node scripts/docs-audit/affected-docs.mjs --json 8fc50b7647d30db2a0837877cf251c1163a3239e

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 8fc50b7647d30db2a0837877cf251c1163a3239e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: e2a28fadf1c02a48c965f0303776872e1a323b79
Local-runs: none

PR #22126 (card #22114), branch claude/issue-22114-meta-read-version-token, draft, head repo = base repo, base main at 8fc50b7647d30db2a0837877cf251c1163a3239e, 12 commits, 20 files, +899 / -43 (942 changed lines). Inputs read: the card body and all 7 comments (triage, claim, three dev reports, the round-1 patch order, the ACCEPT), the PR body, its file list, its one comment (docs drift, advisory), the net diff main...head, and the head's check-runs. Source at the head was read through the contents API only: protocol.ts, rest-server.ts, metadata-redaction.ts. Nothing was built, run or re-run.

Check-runs on the head (REST check-runs API, both reads): first read at 2026-10-08T02:54:41Z — 39 runs, 33 success, 5 skipped, 1 in_progress (Check Changeset, the re-run the labeled event started); second read at 2026-10-08T03:01:10Z — 39 runs, 34 success, 5 skipped, 0 failed, 0 in progress. All seven required contexts success: Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard. The five skipped are the opt-in tarball smoke, Console Pin Gate and the labeled-event duplicates of Auto Label / Check PR Size. No path in the file list is a governed surface; the review is owed on the Clause-②: yes limb and on the published-schema path limb (packages/spec/src/api/protocol.zod.ts, error-code-ledger.zod.ts, non-test).

① Derived judgments

1. GetMetaItemResponseSchema.version — string | null, optional (protocol.zod.ts). A widened response accept set: a non-strict z.object used to strip the key, a parse now keeps it. Right, and the describe's three states match the runtime at the head: the draft branch always sets it (protocol.ts draft return); the active branch sets it unless previewDrafts (absent), and serves null when no stored row was found in scope or when the save's own address holds none. readVersionToken builds getOverlayRepo(orgId ?? null), ref = {singular type, name, org: orgId ?? 'env'} and storedHeadAt(repo, ref, state, packageId ?? null); the save door builds the identical four facts at its own storedHeadAt call (orgId = request.organizationId ?? null, singularTypeForRepo, org: orgId ?? 'env', packageId ?? null). One head read, one producer (receiptVersion), so the read's token is the save's comparand byte for byte. The read side's orgId is organizationIdForMetaRead(type, organizationId) and the REST PUT folds its scope through organizationIdForMetaWrite before the protocol, so at the HTTP door both halves address one partition. The REST GET uncached arm passes packageId = req.query.package || undefined plus state / previewDrafts / organizationId; the cached-arm selector diverts ?state=draft, ?preview=draft, ?package=, app / dashboard / book / doc types and enableCache: false deployments to that arm, so Studio's draft and package-scoped reads serve version, and the default cached plain read does not (its ETag stays the cache validator; pinned). Meets the card's Done-when ("at least state=draft, and the stored-row read a client edits from").

2. New public exports MetadataConflictErrorSchema, MetadataConflictError, MetadataConflictErrorParsed from @objectstack/spec/api. A public-surface widening. The eight generated artifacts moved in step: api-surface +3, export-origins +3, declaration-map +2, json-schema.manifest +1, authorable-surface +4 (GetMetaItemResponse:version, MetadataConflictError:{code,currentVersion,error}), strictness-ledger count 433 → 434, reference docs; check:generated sits inside the green required jobs. Right. The schema declares currentVersion REQUIRED (string | null) and code as the one literal. Judged against the producer: metadataConflictRefusal sets currentVersion whenever servedContentHash(actualHead, digest) is not undefined; storedHashDigest() always returns a digest (the provider's keyed digest or the ephemeral process key), and servedContentHash is undefined only for a non-string non-null head, which the repository does not produce — so every refusal the builder composes states it. All five metadataConflictRefusal call sites at the head are the four item doors (save, both the token-resolution and the repository-race site; publish; rollback; reset). The schema's scope note excludes the batch publish's failed[] rows and raw repository shapes, and the @objectstack/types arm keys on presence, keeping the passthrough body for a METADATA_CONFLICT that states none (the parity control). Right.

3. PUT /meta/:type/:name request accept set (metaSavePreconditionPin, rest-server.ts).

   • If-None-Match: * (whitespace tolerated) → parentVersion: null, the first-write pin SaveMetaItemRequestSchema already declared, now reachable over HTTP; refused 409 METADATA_CONFLICT once a row of the target lifecycle exists. A widening. Right, pinned on draft and active.
   • If-None-Match with any value other than *, and If-None-Match beside If-Match → 400 VALIDATION_ERROR, nothing written. Before the head the door did not read the header, so these requests were answered 200 and written: a narrowing of a published door's accept set, and the dev's original (widening) grade for it was wrong; the round-1 regrade to narrowing is right. Refusing rather than dropping is right (a dropped precondition writes a caller unguarded who asked for a guard — route rule 5's reason); the pair refusal is right under RFC 9110 §13.2.2 (both are evaluated, the pair can never hold, and a 409 would loop the caller through a re-read). The 400 body is the nested ADR-0112 form this route's other VALIDATION_ERROR refusals use; check:route-envelope is green. The closed value set is declared the day the header is first read on this route.
   • If-Match alone (quotes stripped) and neither header (last-writer-wins): unchanged, with the control pinned. Right.

4. @objectstack/types structuredCodeAnswer — the METADATA_CONFLICT arm. Serializes currentVersion (presence-keyed; null relayed as the answer "no row") into the flat 409 body on both doors, keyed on the code AND a stated currentVersion; the door-parity test (token, null, control) and the sandbox-arm census row cover it. A published behaviour change of @objectstack/types, so its minor is right. error-code-ledger.zod.ts registers the stamp site under the @objectstack/types owner key — provenance only, the ErrorCode union unchanged — which is what turned check:error-code-provenance green on this head after the red on 54ae811d4. Right.

5. Describe-only corrections on SaveMetaItemResponseSchema.version, PublishMetaItemResponseSchema.version, PublishPackageDraftsResponseSchema.published[].version and SaveMetaItemRequestSchema.parentVersion: no type or accept-set change; the text now names the served hmac-sha256: token and the METADATA_CONFLICT wire code, and the regenerated reference docs carry the same words. Right.

6. packages/objectql/src/protocol-meta.test.ts: the count-of-2 pin became the exact read sequence (app, apps, then the save-address head; version: null because the served row sits under the other spelling). Test only; the third read is the one extra keyed findOne the PR declares as cost. Right.

7. Unchanged, as the PR states: GET …/layers serves no version; the DELETE door reads no If-None-Match; packages/client is untouched (the read type is the spec's, and the flat conflict body already reaches err.details); the runtime dispatcher's item read carries version because it rides the protocol envelope (parity suites green). No lenient alias or consumer fallback was added anywhere in the diff.

② Semver level

• Changeset .changeset/22114-meta-read-version-token.md: @objectstack/spec, @objectstack/metadata-protocol, @objectstack/rest, @objectstack/types — all minor. Every published package the diff moves is named; the other touched trees (packages/objectql test only, content/docs/references/**, docs/audits/**) publish nothing. Matches the diff.
• The PR body and the changeset both carry the line reading Clause-②: yes (narrowing). A legal combination of the closed grammar: yes for the widened read member, new exports, request header and conflict field; (narrowing) for the two PUT /meta request shapes now refused 400. Right — yes takes at least minor (held), and the arm is BREAKING, so the changeset owes the two launch-window carriers: the **BREAKING** paragraph names both refused shapes and the remedy (send * alone, or If-Match with the version read, never both), and exactly one ADR-0087 marker reads not-required (no-migration-prescription). The category is right: no authorable key, export, response field or stored shape moves, so there is nothing for objectstack migrate meta to rewrite, and which precondition a sender meant is client intent no conversion entry can derive. check:adr-0087-registration and check:changeset-no-major run inside the green Lint & Repo Gates / Check Changeset.
• Level minor, not major: the launch-window convention (check-changeset-no-major.mjs) ships a breaking change as minor and refuses a major outside pre-mode; .changeset/pre.json is absent on main at the PR's base 8fc50b764 (contents API 404, against 200 for .changeset/config.json at the same ref — read by this review, not taken from the report). Right.
• The card claim's arm-less Clause-②: yes is not the carrier; the PR body is, and it reads the arm.

③ Boundary flags

• open_questions[0] (H3, an ETag equal to the token?) — seat ruled A (body member only): answered, judged right. The only branch that sets an ETag is the cached arm, whose validator folds locale, the ADR-0106 D3 visibility fingerprint and the served bytes; the token varies with none of those, and getMetaItemCached's pinned contract forbids a version marker in its place. The card's Done-when takes "a body member, an ETag, or both".
• open_questions[1] (grade of the two 400 refusals) — seat ruled A plus the narrowing arm: answered, judged right (①-3, ②). Option B (ignore a non-* value) would write a caller unguarded and is rightly not taken.
• Dev deviation: packages/types/src/data-error-classification.ts outside the claimed surface — seat accepted: right; the producer of the flat body is structuredCodeAnswer, which error-response.ts names as the home of a new code arm, and it carries its own minor.
• Dev deviations: error-code-ledger.zod.ts (a provenance row, not the details declaration the claim anticipated) and packages/objectql/src/protocol-meta.test.ts (a consumer pin this read's extra findOne broke) — seat recorded both: right, both are what the red on 54ae811d4 demanded and no production line moved for the second.
• Round-0 "not merged with main" — closed: origin/main was merged twice since (0bb0202bc, 68a14c74b) through os-regen-merge.sh; the compare against the base is clean.
• Out-of-scope finding 0 → finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128 (package-less draft path; this read's version inherits it, serving null while a draft exists on that path): filed, named in the PR body, the describe left true by finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128's fix at the shared head read. Carried.
• Dispatcher / hono catch-all PUT /meta ignoring If-Match, If-None-Match and ?mode=draft → finding(runtime): through the @objectstack/hono catch-all, PUT /meta/:type/:name ignores If-Match, If-None-Match and ?mode=draft — a stale token writes (200, not 409) and a draft save lands ACTIVE #22141; cloud hosts' routing NOT MEASURED from this session: filed by the seat, pre-existing, not this PR's. Carried.
• plugin-rest-api.zod.ts /publish describe still says metadata_conflict — rides finding(metadata-protocol): a second package-less draft save of a package-owned item is refused 409 METADATA_CONFLICT with no If-Match — the save door's head read and the repository's draft package inheritance read different rows #22128 per the seat. Carried.
• GET /meta/:type/:name?package=all serves version: null for the package-less row the save would write — noted by the dev, kept in the Acceptance notes by the seat. Confirmed at the head: the GET hands the literal all to the protocol as packageId, the PUT folds all to the env-local overlay. A client that reads and saves with ?package=all gets a null it would pin with If-None-Match: * and is refused 409 when the package-less row exists; it recovers from the 409's currentVersion, and no write lands unguarded, so this is not a FAIL. Escalated to the seat: a reproducible wrong first answer at a public door is a Prime Directive chore: version packages #10 card, not an acceptance note — file it (or rule it a note on the record) before the PR's Acceptance notes are the only place it lives.
• dispatch-gates --commands leaving the artifact-roster block outside the harvest — documented tool behaviour per the dev; for the seat's dispatch brief, no action in this record.
• Probe hygiene (the one-off hono harness, deleted and never committed; the --shallow-since fetch): nothing reaches the diff. No model identifier appears in the PR title, body, changeset or diff.

Implemented-by: claude/issue-22114-meta-read-version-token
Reviewed-by: session_01RPo7FUd6bSnAfkWMAKi848

VERDICT: PASS