feat(spec)!: PROTOCOL_VERSION 17 → 18 in an ordinary PR — regenerated spec-changes.json and upgrade guide, ^18 handshakes, pre-mode lockstep exception (#22085 Q1 → B)

[objectstack-fleet]

Fixes #22130
Clause-②: yes (narrowing: the handshake refuses a manifest pinned to protocol 17 ('^17', '^17.x.y', '17.x'), while the exported PROTOCOL_VERSION moves to '18.0.0' and a '^18' manifest is admitted)

Executes #22085 Q1 → B (ruling record 6049734955, the maintainer's 「22082 22085 同意」): the protocol major moves in an ordinary pull request that runs the full CI, not in the version pass.

• PROTOCOL_VERSION reads '18.0.0'.
• The two generated documents are regenerated by their own tooling: spec-changes.json, and the 17 → 18 section of the protocol upgrade guide.
• Every in-repo handshake that means "the current protocol" reads ^18.
• The lockstep gets one narrow exception, routed by ruling record 6056808625 (letter E, maintainer 「同意」):
  • the local lockstep test recognises only the exception's shape;
  • scripts/check-changeset-no-major.mjs judges the evidence: Changesets pre mode AND a pending major for @objectstack/spec.

Status. os-zhuang approved this PR on c96d8e9446 (an authorized APPROVED review, Tier H); the owning seat lands it after the re-sync rounds below and a delta at-tier contract review. PR #22084 (pre mode plus the major marker) merged as a87d8be299 and is merged into this branch, so the pre-mode condition is live.

Size: 8,611 changed lines against the merge base e148ca9842 (+7,854 / −757, 52 files). 7,819 of them are the two generated documents. That is over the human-merge line (3,000 since #22490; AGENTS.md §7 class (c)), so this PR lands like a Tier H surface: an authorized approval and then the owning seat, or a human merge.

First measurements (answered before the edit, on ef1fcb26a2)

M1 — which packages/cli fixtures declare ^17 on purpose. Only packages/cli/src/utils/protocol-version-gap.test.ts:68.

• That file's advisory judges a range against an explicit installed '17.2.0', never against PROTOCOL_VERSION. ^17 there is the "the range covers the install" control.
• packages/cli/CHANGELOG.md is release-owned history.
• The other 19 files (33 sites) are manifest fixtures standing for a valid current app, and none of them asserts on the range. They read ^18.

M2 — may #5082's 17 → 18 conversions (PR #22103) take effect before ADR-0131 C8? The bump does not change when any conversion applies, and no step-18 entry assumes C8. No fork.

• applyConversions and the stored-row seam walk every conversion with no PROTOCOL_MAJOR filter.
• The artifact door keys its conversion window on the declared floor against the installed spec package version.
• os migrate meta already ends at 18: CHAIN_TERMINUS_MAJOR = Math.max(PROTOCOL_MAJOR, ...MIGRATION_MAJORS).
• declared-index-unique-scope rewrites bare true to 'global', which is the same physical index. 'organization' is NULL-safe through COALESCE (ADR-0120 D3).
• The step-18 entries that cite ADR-0131 cite D7 or D8 and describe the pre-C8 shape (rows with no organization are still answered). None assumes organization_id is NOT NULL.

What changes

• packages/spec/src/kernel/protocol-version.ts: PROTOCOL_VERSION = '18.0.0'; its docblock names the exception.
• packages/spec/spec-changes.json, docs/protocol-upgrade-guide.md: regenerated by gen:spec-changes and gen:upgrade-guide after each merge of main, never by hand.
  • Both generators read PROTOCOL_VERSION from source plus the two registries. Neither reads the pre-mode state.
  • The 17 → 18 record carries 64 conversions and 329 semantic entries (406 in the 16 → 18 aggregate). The merges of main since b460153912 added five semantic entries, sys-view-definition-retired (feat(metadata-core,metadata-protocol,metadata,platform-objects,spec)!: sys_view_definition retires as inert (ADR-0131 D13, C5 stage S1) #22374), try-catch-and-retry-policy-undeclared-keys-refused (fix(spec)!: close the shared retry policy, and judge try_catch config keys at the build doors #22380), flow-text-slot-single-brace-refused (feat(spec)!: flow text slots read the {{ }} delimiter, refusing a single-brace token with its hole spelling (#22110) #22315), manage-org-presentation-retired and meta-doors-organization-scope-retired (feat(metadata-core,rest,runtime,plugin-email,spec)!: the /meta doors carry no organization; organization-admin metadata authoring closes (ADR-0131 D6, #15206 S3) #22447), reworded flow-builtin-node-config-undeclared-keys-refused (fix(spec)!: close the shared retry policy, and judge try_catch config keys at the build doors #22380) and six rationales (chore(objectui): bump the console pin to f0268ad78485 (carries objectui#11880) #22412), and added no conversion.
• Handshakes: 55 sites in 39 files read ^18. Two runtime fixtures read >=17.1.0 (see Judgments).
  • main added no ^17 handshake between 959c209d56 and d1dbe70ebd: per-file counts are equal.
  • Between d1dbe70ebd and 6729e107e8 it added one: packages/cli/test/package-union-readers.test.ts:86, a current-app fixture (fix(cli): read a multi-package artifact's package bodies in the capability preflight and the translation readers #22285), which now reads ^18.
  • Between 6729e107e8 and 41d0d4038c it added none. git diff 6729e107e8 41d0d4038c | grep -E "protocol.*'\^17" matches nothing; the same grep over this PR's own diff matches 60 lines. Per-file counts of '^17…' literals are equal across the merge.
  • Between b460153912 and e02833c240 it added two current-app fixtures, which now read ^18: packages/qa/dogfood/test/security-catalog-cold-boot-environment-holder.dogfood.test.ts (feat(objectql)!: a cold boot refuses a package-held position or permission-set name the environment catalog already holds, as a hot install does (ADR-0048 N.3) #22365) and packages/cli/test/retry-policy-key-validate-door.test.ts (fix(spec)!: close the shared retry policy, and judge try_catch config keys at the build doors #22380). Later, feat(core,cli,verify): bootStack composes what serve composes — item 1 stage 2 of #22301 (HELD at stop conditions) #22381 added a third, packages/cli/test/verify-host-root.test.ts:56, which now reads ^18 (round 12).
• The specVersion prescription: packages/spec/src/kernel/manifest.zod.ts's guidance.specVersion spells the range it prescribes from PROTOCOL_MAJOR (imported from ./protocol-version, which imports nothing), so it prints engines: { protocol: '^18' } at this protocol and follows the next major. manifest-unknown-keys.test.ts pins the current-major range and refuses the previous one (ablation: restoring the '^17' literal turns it red).
• packages/spec/src/kernel/protocol-version.test.ts (local; release.yml runs it by that project):
  • The lockstep is unchanged when the majors are equal.
  • It recognises the exception's shape — a stable package version exactly one major behind — and hands the judgement to check-changeset-no-major.mjs.
  • Any other drift is red. It reads nothing outside the package.
• scripts/check-changeset-no-major.mjs gains a third question, the protocol lockstep evidence:
  • It reads the protocol major from the source text of protocol-version.ts, not from a build. The regex is the declaration sync-protocol-version.mjs rewrites.
  • When that major is one ahead of @objectstack/spec's stable version, the gate requires .changeset/pre.json mode: 'pre' AND a pending top-level .changeset/*.md declaring "@objectstack/spec": major.
  • Without that evidence it refuses with one ::error:: annotation that names the remedy: set the constant back to the package major, or changeset pre enter plus a spec major.
  • Unreadable inputs are a failure, never a pass.
  • Its new self-test battery (39 cases, floor 19 → 20) covers both directions.
• scripts/check-future-spec-major.mjs: the generated copies carry the witnessed measurement entries. QUOTATION_EXEMPTIONS gains two kind: 'measurement' entries, modelled on the registry.ts one and witnessed by the same regex: packages/spec/spec-changes.json (covers: 2) and docs/protocol-upgrade-guide.md (covers: 1), major 4997.
  • From protocol 18 on, the two generators project that entry's evidence sentence ("controls objectstack 12966 and @objectstack/spec 4997 on the same corpus") into the 17 → 18 records: the per-major and aggregate records in spec-changes.json, and the guide section.
  • The matcher, the path scope and the recorded rationale are unchanged.
• packages/cli/test/migrate-meta-default-range.test.ts (the os migrate meta --from 17 — the invocation the spec 17 tombstones prescribe — reports Nothing to migrate for the conversions it is meant to list, because --to defaults to the current major and the conversions are toMajor: 18 #17134 pins), re-premised for protocol 18:
  • The spawned cases now run the tombstone's own --from N. N is one below the toMajor of the step that carries the rename conversion, read off the registry (17).
  • They used to run --from PROTOCOL_MAJOR. At protocol 18 that range lies above the rename, so four cases read an empty chain (Test Core (1/6) on dd4ea171fb).
  • The new --to default, Math.max(PROTOCOL_MAJOR, ...MIGRATION_MAJORS), differs from the old one, PROTOCOL_MAJOR, only while the registry carries a step past the runtime major.
  • Measured: MIGRATION_MAJORS is [17, 18], and no conversion registers toMajor: 19 on this branch or on main b460153912. Both defaults are 18, so no run of the installed CLI tells them apart.
  • The anti-vacuity line (TERMINUS > PROTOCOL_MAJOR) therefore cannot hold in the spawned file. It moved, word for word, to migrate-meta-default-range-window.test.ts (unit).
  • That file runs the real command in-process. Only the kernel's two protocol constants are replaced, by the authoring major: the window the card was measured in. There the line tells the two defaults apart in every release.
• .changeset/22130-protocol-18.md: now major, because pre mode is on main. Its Clause-② line declares the arm narrowing; the second line of this body is that line, byte for byte. It keeps the BREAKING banner and not-required (already-registered …) naming the 64 step-18 conversions. check:adr-0087-registration exits 0.

Directory	Files	^17 before	^17 after	^18 after
content/docs	3	3	0	3
examples/app-crm	1	1	0	1
examples/app-multi-package	2	2	0	2
examples/app-showcase	1	1	0	1
examples/app-todo	1	1	0	1
packages/cli	21	35	0	35
packages/lint	2	2	0	2
packages/mcp	1	2	0	2
packages/metadata	1	2	0	2
packages/qa	4	4	0	4
Total	37	53	0	53

Why the evidence lives in check-changeset-no-major.mjs (H3 falsified; ruling E)

H3 put the exception inside protocol-version.test.ts, reading .changeset/pre.json. Measured, that cannot stand:

• A spec test reading .changeset/ must move to the repo project. check:cross-package-test-inputs exits 1 otherwise.
• release.yml runs this file by --project local. A file in the repo list then answers No test files found, exiting with code 1.
• The first draft of this PR (route R) used a repo-project test. It had to declare .changeset/** as a CI scheduling surface, and that reddened dispatch-gates' extractWatchHints reads a noise-floor EXCLUSION constant as a watch hint: .changeset derives check:pm-half-states onto every changeset-adding card #15753 invariant: a changeset path alone must reach no value-bearing family.

The maintainer ruled E. R's repo-project test and its six declaration edits are reverted. Each of these files now equals main at b460153912, measured:

• vitest.repo-tests.json
• cross-package-test-inputs.mjs
• check-cross-package-test-inputs.mjs
• turbo.json
• ci.yml
• check-ci-filter-parity.mjs
• protocol-version-pre-mode.test.ts

scripts/pm/dispatch-gates.mjs, release.yml, cut-rc.yml and sync-protocol-version.mjs are untouched.

The gate's verdict, measured three ways:

Tree	Verdict	Exit
This branch (protocol 18, @objectstack/spec@17.7.0, pre mode, the #22084 marker pending)	✓ Protocol lockstep: … the one exception, evidenced: pre mode (tag next) and a pending major for @objectstack/spec (.changeset/22080-v18-line-opens.md)	0
main 3513ac7781 with this gate copied in (an ordinary PR, no shape)	✓ Protocol lockstep: PROTOCOL_VERSION major 17, @objectstack/spec@17.7.0 — not one major ahead of a stable version, so there is no pre-mode exception to judge.	0
The same tree with the constant at 18 and the marker removed	⛔ … protocol lockstep refused … no pending changeset declares "@objectstack/spec": major. Either put the constant back in lockstep — PROTOCOL_VERSION = '17.0.0' … or open the next major line first …	1

Residuals, stated:

• The Check Changeset step is skipped under the skip-changeset and allow-major labels.
• Check Changeset is not one of the seven required contexts AGENTS.md §7 names.

Judgments: every handshake left at ^17, with its reason

Site	Reason
packages/cli/src/utils/protocol-version-gap.test.ts:68	Paired with an explicit installed '17.2.0' (M1).
packages/cli/CHANGELOG.md:7788	Release-owned history.
content/docs/releases/v17/17-5.mdx, 17-6.mdx, 17-7.mdx	Release-owned; each describes a 17.x release.
packages/create-objectstack/src/templates/blank/objectstack.config.ts:39	The version pass stamps it together with the template's @objectstack/* ranges (replay: engines.protocol → '^18' beside ^18.0.0). Moving it now would scaffold ^18 over ^17.0.0 dependencies. template-consistency.test.ts holds it equal to the scaffolder major.
packages/metadata/src/__fixtures__/forward-probe-17.4-built.artifact.json:11, hotcrm-17.1-built-bare-root-predicates.artifact.json:12, hotcrm-17.1-built-permissions.artifact.json:12	Frozen artifacts built by 17.x. Their floor is the subject, and the metadata plugin door runs no handshake.
packages/metadata/src/plugin-artifact-forward-conversion-retired-after.test.ts:194, plugin-artifact-forward-conversion.test.ts:221	The artifact's age is the subject.
packages/metadata-core/src/artifact-forward-conversion.test.ts:228, form-predicate-root-policy.test.ts:26,50	Age fixtures against an injected runtime version, or a repro shape. No handshake runs.
packages/runtime/src/app-plugin-artifact-forward-conversion.test.ts:81	The real incident's floor. Its readers run no handshake, and it is green at protocol 18.
packages/spec/src/kernel/manifest-unknown-keys.test.ts:53,278,282, manifest-permissions-string-list.test.ts:53	ManifestSchema shape samples; the schema never judges the major.
skills/objectstack-platform/SKILL.md:143, skills/objectstack-platform/evals/config-plugins-ops.json:7, skills/objectstack-upgrade/SKILL.md:91	Governed Tier H; the seat routes them.
.github/workflows/scaffold-e2e.yml:106	A comment.

Moved to >=17.1.0:

• packages/runtime/src/standalone-stack-security-registrar.test.ts:49
• standalone-stack-seeder-declaration-copy.test.ts:117

Both boot through the load seam, which refused ^17.1.0 at protocol 18. Their subject is the forward-conversion window, and that window opens on the floor. >=17.1.0 keeps the floor and admits 18.

Re-premised for protocol 18. This is not a handshake: it is a --from that meant the authoring major.

Site	Before	After
packages/cli/test/migrate-meta-default-range.test.ts (#17134)	--from String(PROTOCOL_MAJOR), with the anti-vacuity line TERMINUS > PROTOCOL_MAJOR	--from the rename step's toMajor − 1. The anti-vacuity line moved, word for word, to migrate-meta-default-range-window.test.ts, which holds the runtime major at that authoring major in-process.

Replay of the root version script (throwaway clone of bdee4d2da1)

A clone of the merged branch. pre.json and the major marker come from main, so no overlay was needed. release-rehearsal-clone.mjs --prepare answered FIT. Then pnpm install --frozen-lockfile and pnpm run version:

✓ PROTOCOL_VERSION already 18.0.0 — in lockstep with @objectstack/spec@18.0.0-next.0
✓ blank/objectstack.config.ts: engines.protocol → '^18'

release.yml's shape filter (SURFACES, stampedPaths(), syncedPaths(), the fixed pattern):

• 361 moved paths, with UNEXPECTED empty.
• protocol-version.ts not moved, so UNVALIDATED is empty.

Content gates on that tree:

Gate	Result
vitest run --project local src/kernel/protocol-version.test.ts	3/3
check:spec-changes	exit 0
check:upgrade-guide	exit 0
check:template-manifests	exit 0
pnpm --filter create-objectstack test	17 files, 254 tests
check-changeset-no-major.mjs	exit 0; not one major ahead of a stable version (18 vs 18.0.0-next.0)

Control leg (round 1), the same overlay on ef1fcb26a2: ✓ PROTOCOL_VERSION 17.0.0 → 18.0.0, and protocol-version.ts is in the moved set. That is the UNVALIDATED refusal this PR removes.

Verification

Round 12, at 6ec484243e (report on #22130). The merge queue ejected 4ba5952ea1 in a group behind PR #22381, whose new fixture verify-host-root.test.ts:56 declared ^17 (triage 6081302430). main 8b713fad78 merged (3b97df5a7f, nothing of its own); the fixture moved to ^18 in its own commit (5159d64866), red before it and green after it. main e148ca9842 merged (462a24045b); #22447 had added two step-18 semantic entries, so both documents were regenerated in a separate commit (4d1a408a75: +28 and +6 lines), and the changeset's count tokens moved 327 → 329 in their own commit (6ec484243e). 138 derived gates run, 0 not measured. CI on 6ec484243e: 35 runs, 33 success, 2 expected skips.

Round 11, at 4ba5952ea1 (report 6080275052 on #22130). The merge queue ejected 5ef8ab6ac5 when PR #22315 landed first with a new step-18 semantic entry. main 3ca71b6e05 merged (a46840ee68, no path of its own per git diff-tree --cc); spec-changes.json (+14) and the upgrade guide (+4/−1) regenerated in a separate commit (b8a3e2a45c; 64 conversions, 327 semantic entries, aggregate 404 = the registry's 404); the changeset's two count tokens 326 → 327 in their own commit (4ba5952ea1). At-tier delta contract review PASS 6079895139. CI on 4ba5952ea1: 35 runs, 33 success, 2 expected skips.

Round 10, at 5ef8ab6ac5 (report 6077854211 on #22130; seat ACCEPT 6078284011). A pure regeneration: main bf492c8548 (#22412) merged (b50d5c3866), then spec-changes.json (+12/−12) and the upgrade guide (+6/−6) regenerated in a separate commit; every changed line is a rationale of the six step-18 entries #22412 reworded, and the counts stay 64 / 326. The at-tier PASS 6076766071 is carried by the Regen-provenance: line in PR comment 6077906555. CI on 5ef8ab6ac5: 35 runs, 33 success, 2 expected skips.

Patch round 1, at eb23db8a82 (report 6076558925 on #22130). main e02833c240 merged with os-regen-merge.sh (c80423bc16, committed before any generator ran); no step-18 entry arrived, check:spec-changes and check:upgrade-guide exited 0 on the merged tree, and both generators rewrite byte-identical (64 / 326). The specVersion prescription fix above. spec test 627 files / 18,757 passed and test:repo 54 files / 915; cli protocol-version-gap.test.ts 16 passed; the dogfood cold-boot file 4 passed. The 32 steps of Type Check · source gates exit 0, check:future-spec-major included; dispatch-gates: 138 derived, 138 run. CI on eb23db8a82: 35 runs, 33 success, 2 expected skips.

Round 9, at 4ff2827472 (report 6075705847; seat review 6075740377). The re-sync the handover named: main e75dceddd7 merged (e04231ab07), spec-changes.json and the upgrade guide regenerated after the merge commit (062e3545c8, 324 → 326 semantic entries), the changeset count updated, the two current-app fixtures main added moved to ^18, and PR #22416's one-file fix ported verbatim (02d07755d7; main now carries the identical blob, so it no longer shows in the diff). The merge-queue build of c96d8e9446 had failed check:spec-changes for exactly this staleness.

Round 8, at c96d8e9446. A merge of main b460153912 only, with os-regen-merge.sh (merge commit c96d8e9446). main touched no migration, conversion or kernel file and added no ^17 handshake since 41d0d4038c.

• gen:spec-changes and gen:upgrade-guide both rewrote their files byte for byte: git diff HEAD is empty.
• check:spec-changes, check:upgrade-guide, spec check:generated (15 artifacts), check:future-spec-major and check:adr-0087-registration --base origin/main exit 0. check-changeset-no-major --base origin/main --event exits 0 against this body.
• The two Test Core timeouts on c78f55e352 are not this PR's. Both now exit 0:
  • @objectstack/lint src/build-access-matrix.test.ts (fixed on main by test(lint): index the access-matrix rows once in the exhaustive fold case #22358): 8 tests, 3.5s.
  • @objectstack/spec src/integration/connector-author-shape.test.ts (local): 11 tests, 16.4s. One case, "compiles every full connector example verbatim", takes 11.5s against a 60s testTimeout.

Round 7, at c78f55e352. main 41d0d4038c was merged with os-regen-merge.sh (merge commit ecde207250, no regeneration in MERGE state). Then gen:spec-changes and gen:upgrade-guide were run (fed6cd402f), and the changeset now counts 324 semantic entries (c78f55e352).

• Every step of lint.yml's Type Check · source gates job exits 0, run in order: 32 run steps. They include check:spec-changes, check:upgrade-guide, check:authorable-surface and check:future-spec-major (8 witnessed ledger entries; the new generated copies cite no @objectstack/spec major).
• Spec check:generated (all 15 artifacts) exits 0.
• check:adr-0087-registration --base origin/main, check:empty-changeset, check:changeset-gate-self-tests and check:nul-bytes exit 0. check-changeset-no-major --base origin/main --event exits 0 against this body.
• dispatch-gates --commands derives the same 138 families; the merge adds none.
• The full test task of every touched package, each exit 0:
  • @objectstack/spec: test 626 files, 18,740 tests passed, 1 todo; test:repo 54 files, 914 tests.
  • @objectstack/cli test (both projects): 366 files (269 unit + 97 integration), 4,877 tests passed, 2 skipped. typecheck exits 0.
  • @objectstack/runtime: test 340 files, 4,776 tests passed, 19 skipped; test:repo 3 files, 751 tests.
  • @objectstack/dogfood: 226 files passed, 1 skipped; 1,770 tests passed, 9 skipped.
  • @objectstack/lint 127 files, 5,843 tests. @objectstack/mcp 35 files, 390 tests. @objectstack/metadata 58 files, 870 tests.
  • example-crm 5 files, 45 tests. example-showcase 33 files, 408 tests. example-todo 7 files, 238 tests.

Round 6, at 99b16b2999. Test Core (1/6) was red on dd4ea171fb in @objectstack/cli's integration project: migrate-meta-default-range.test.ts, 4 tests. My earlier rounds ran --project unit only. Now:

• pnpm --filter @objectstack/cli test (both projects) passes. 361 files (267 unit + 94 integration): 4,839 tests passed, 2 skipped, exit 0.
• pnpm --filter @objectstack/cli typecheck exits 0. It includes check:test-typecheck over test/.
• The full test task of every other touched package with more than one vitest project, each exit 0:
  • @objectstack/dogfood: 221 files passed, 1 skipped; 1,753 tests passed, 9 skipped.
  • @objectstack/runtime: test 336 files, 4,749 tests passed, 19 skipped; test:repo 3 files, 751 tests.
  • @objectstack/spec: test 625 files, 18,711 tests passed, 1 todo; test:repo 54 files, 914 tests.
  • lint, mcp, metadata, example-crm, example-showcase and example-todo have one project each. example-multi-package has no test script.
• Two ablations, run from the committed state with scripts/ablation-replace.mjs. Each mutation was proven on disk, and each restore was proven by blob = HEAD and an empty git diff HEAD. Both subjects resolve to src/, so no build leg applies.
  • With the --to default reverted to PROTOCOL_MAJOR, exactly the window file's three default pins go red: expected 17 to be 18, expected [] to deeply equal [ …(5) ], and a missing Applied 5 mechanical change(s). The spawned file stays green under the same mutation, which measures that it cannot tell the defaults apart at protocol 18.
  • With the window mock neutralised (runtime major left at 18), the window guard and the anti-vacuity line go red: the registry carries a step past the runtime major: expected 18 to be greater than 18.

Round 5, at dd4ea171fb. Every step of lint.yml's Type Check · source gates job exits 0, run in the job's order: 32 run steps, from pnpm install --frozen-lockfile to check:llms-txt.

• Before the two ledger entries, check:future-spec-major was red on three sites: docs/protocol-upgrade-guide.md:1039 and packages/spec/spec-changes.json:2340, :5880.
• After them: self-test 29 cases, 10,167 files scanned, 8 witnessed ledger entries, every witness still matching.
• readClause2Line reads the changeset as { value: yes, arm: narrowing }.
• These exit 0 against this body: check-changeset-no-major --base origin/main --event, check:adr-0087-registration --base origin/main, check:empty-changeset and check:changeset-gate-self-tests.

All runs below happened after merging main (3513ac7781, then d1dbe70ebd), on a shared box, through the verify lock.

After the third merge (6729e107e8, which added one step-18 semantic entry), at 23e9e302d9, these all exit 0:

• check:spec-changes, check:upgrade-guide and spec check:generated;
• check-adr-0087-registration --base origin/main;
• check-changeset-no-major --base origin/main --event, against this body;
• the spec local tests under src/kernel src/migrations src/conversions (70 files, 1,853 tests);
• package-union-readers.test.ts (7/7).

dispatch-gates --commands derives the same 137 families as at bdee4d2da1; the merge adds none.

Builds. The turbo closure of dogfood, cli, cloud-connection, the examples, create-objectstack and mcp: 65/65 tasks. Then lint/cli (59/59) and the seven dist-only packages (43/43). check:generated: all 15 artifacts up to date.

Tests

Package	Scope	Result
@objectstack/spec	local, full	625 files, 18,661 tests
@objectstack/spec	repo, full	53 files, 903 tests (in shards; build-schemas-check-mode.test.ts alone 88/88 in 909s)
@objectstack/spec	after the second merge: src/kernel src/migrations src/conversions	71 files, 1,861 tests
@objectstack/spec	typecheck	exit 0
@objectstack/runtime	local, full	335 files (3 shards: 112 + 112 + 111)
@objectstack/runtime	repo	3 files, 751 tests
@objectstack/metadata-protocol	full	221 files, 28,277 tests
@objectstack/metadata	full	58
@objectstack/metadata-core	full	18
@objectstack/cloud-connection	full	41
@objectstack/lint	full, after the second merge	127 files, 5,843 tests
create-objectstack	full	17
@objectstack/cli	--project unit	263 files (2 shards), 3,901 tests
@objectstack/cli	touched .e2e files	2 files, 45 tests
@objectstack/dogfood	touched files	6 files, 44 tests
example-crm	full	5
example-todo	full	7
example-showcase	full	33
check-changeset-no-major.mjs --self-test	—	378 assertions

Gates at bdee4d2da1:

• I ran every gate dispatch-gates --commands derives (137) together with the claim-time list (146 commands in all).
• dispatch-gates --ran: "137 derived, 137 run, 0 NOT-MEASURED, 0 UNRUN". All exit 0.
• pnpm check:pm-dispatch-gates: 1,976 of 1,976 cases pass, the extractWatchHints reads a noise-floor EXCLUSION constant as a watch hint: .changeset derives check:pm-half-states onto every changeset-adding card #15753 case included.
• Three gates were re-run after a build:
  • check:skill-examples and check:dual-build-cjs-loads first answered PREREQUISITE NOT MET.
  • check:docs-transcript-drift first read a stale lint dist (49 against the docs' 50).
  • All three exit 0 after rebuilding.

Acceptance notes

• Docs versus npm latest. The getting-started, CLI and upgrading pages show ^18, as the ruling directs for docs snippets. npm latest stays 17.x until 18 GA, and a 17.x runtime refuses ^18. Noted for the v18 release page (release(v18): the version-pr lane refuses the major boundary at Validate the post-version tree, so #21988 never refreshes into 18.0.0-next.0 — wire the lane's major-only gates in, and stop prerelease cuts re-dating the last GA #22085 Q2).
• os migrate meta and the declared range. Measured on this branch, which carries the cli(migrate meta): os migrate meta --from 17 --write leaves engines.protocol: '^17', so the load refusal that names this command as its resolution still refuses the migrated manifest #22219 fix 9f0de32a03, with a probe manifest declaring engines: { protocol: '^17' } and one bare unique: true declared index.
  • The dry run (--from 17) names it: ⚠ manifest.engines.protocol '^17' does not admit protocol 18, so the load refuses this stack even after migrating; --write rewrites it to '^18'.
  • --write rewrote both edits: Rewrote the declared protocol range, so the load admits protocol 18: objectstack.config.ts:2 manifest.engines.protocol: '^17' → '^18', beside the declared-index-unique-scope edit.
  • The changeset's "What you change" bullet says the same in the house sentence's shape.
• CLI advisory versus handshake. Until the first next.0 version pass, main's CLI advisory judges ranges against the installed spec package (17.7.0), while the handshake judges against PROTOCOL_VERSION (18). A published 18.0.0-next.N has both on 18.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/mcp, @objectstack/spec, touching 2 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/mcp/README.md, packages/spec/spec-changes.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/getting-started/quick-reference.mdx (via ManifestSchema (symbol, a top-level const object))
• content/docs/plugins/development.mdx (via ManifestSchema (symbol, a top-level const object))
• content/docs/protocol/kernel/plugin-spec.mdx (via ManifestSchema (symbol, a top-level const object))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v12.mdx (via PROTOCOL_VERSION (symbol, a top-level const object))
• content/docs/releases/v13.mdx (via PROTOCOL_VERSION (symbol, a top-level const object))
• content/docs/releases/v14.mdx (via PROTOCOL_VERSION (symbol, a top-level const object))
• content/docs/releases/v15.mdx (via ManifestSchema (symbol, a top-level const object))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/mcp/README.md, packages/spec/spec-changes.json) — pages documenting those are invisible to this run
• 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 — 144 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 e148ca984258c7c0d162eefd04b1f0f77c3fa9fd → packageMentionDocs.

Which tree this was computed on

This run read content/docs from faf473962ac6defe325d4c5ad2487aa1725185fb — the merge of head 6ec484243e3808af9680bb5b05822d768fb24cc0 into base e148ca984258c7c0d162eefd04b1f0f77c3fa9fd, 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 faf473962ac6defe325d4c5ad2487aa1725185fb && git checkout faf473962ac6defe325d4c5ad2487aa1725185fb
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e148ca984258c7c0d162eefd04b1f0f77c3fa9fd 6ec484243e3808af9680bb5b05822d768fb24cc0 && git checkout -B drift-repro e148ca984258c7c0d162eefd04b1f0f77c3fa9fd && git merge --no-ff 6ec484243e3808af9680bb5b05822d768fb24cc0

node scripts/docs-audit/affected-docs.mjs --json e148ca984258c7c0d162eefd04b1f0f77c3fa9fd

⚠️ 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 e148ca984258c7c0d162eefd04b1f0f77c3fa9fd → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Read at 2026-10-09T16:26Z · PR #22215 (open, non-draft, auto-merge off, mergeable_state clean) at merge base e148ca9842 · card #22130 · delta review (round 12, the re-sync after the merge queue ejected 4ba5952ea1 at verify-host-root.test.ts, triage 6081302430) after the at-tier PASS 6079895139 at 4ba5952ea1 · isolated, read-only, at tier.

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6ec484243e3808af9680bb5b05822d768fb24cc0
Local-runs: none

Inputs: the card body and its 29 comments (the ruling 6056808625, the claim 6074102194, the round-11 ACCEPT 6080960782, the holder note 6081559243, the round-12 dev report 6084728061); the PR body as re-edited after that report (it now carries a Round 12 entry), its file list (52), its 18 comments and its one review; the five first-parent commits since 4ba5952ea1; the net diff git diff e148ca9842 6ec484243e (52 paths, +7,854 / −757, path for path and count for count equal to the files API) compared path by path, index and hunk headers stripped, with the round-11 net diff git diff 3ca71b6e05 4ba5952ea1; git diff-tree --cc of both merges; the two generated documents at the head parsed as JSON and as Markdown; the entries/semantic/18.*.ts tree and the two registries at 3ca71b6e05, e148ca9842, the head and today's main tip 2e10c9abe0; .changeset/pre.json, the #22084 marker, packages/spec/package.json and protocol-version.ts at the head; #22447's changeset at e148ca9842; HUMAN_MERGE_LINE_THRESHOLD and GOVERNED_SURFACES in scripts/pm/check-governed-merges.mjs and AGENTS.md §7 on main; the head's check-runs, read twice. Nothing was built, tested or re-run; every reading is git show / git diff / git diff-tree / git grep / git ls-tree / git merge-base / a JSON parse / a gh api GET.

① Derived judgments

What this delta is, read off the trees. Five first-parent commits. 3b97df5a7f merges main 8b713fad78 (14 first-parent commits past 3ca71b6e05, #22381 among them); 462a24045b merges main e148ca9842 (9 more, #22447 and #22490 among them). git diff-tree --cc of each merge prints only its own sha: neither introduced a line of its own. Between the merges 5159d64866 edits one file; after them 4d1a408a75 regenerates the two documents and 6ec484243e edits the changeset. Both merge targets are ancestors of today's main; the merge base is e148ca9842, equal to the PR's API base.

The hand-edited fixture, judged. packages/cli/test/verify-host-root.test.ts was ADDED by #22381 (97610a5339, +141, on main after the round-11 merge base). Its STACK.manifest is a current-app fixture: os verify is spawned on it, the boot runs the real load seam and the ADR-0087 D1 handshake, and nothing in the file asserts on the range text (^17 / ^18 occur at line 56 alone). So '^17' there is the same class as the 52 sites the PR already swept, and the queue's red — targets protocol ^17 (engines.protocol) but this runtime is protocol 18.0.0 — is the handshake doing what the Clause-② line declares. 5159d64866 is +1 / −1 on line 56, '^17' → '^18', and nothing else (word diff). Right. It is the ONLY added caret-17 protocol literal in main's delta 3ca71b6e05..e148ca9842 (one hit, that line), and main's one commit since the merge base (#22495, 2e10c9abe0) adds none and touches no packages/spec path. Per-file counts of caret / tilde / greater-or-equal 17 protocol literals over the tree (release pages excluded) are equal at 4ba5952ea1 and at this head; the intermediate merge 3b97df5a7f differs by exactly that one file. The path set grew 51 → 52 by exactly this file: comm -12 of main's delta paths with the PR's 52 is that one path, and nothing else main touched intersects the PR.

The regenerated documents equal the merged registries. What main added since 3ca71b6e05 under packages/spec/src/migrations is #22447 (7895671162): 18.manage-org-presentation-retired.ts, 18.meta-doors-organization-scope-retired.ts, and registry.ts +88 (the two entries, nothing else); its changeset at e148ca9842 carries adr-0087: registered manage-org-presentation-retired, meta-doors-organization-scope-retired. The conversions registry blob (aa4b618125) is identical at 3ca71b6e05, e148ca9842, the head and the tip; the migrations registry blob (ed7eda14f4) is identical at e148ca9842, the head and the tip. 4d1a408a75 is +34 / −0: spec-changes.json +28 in four hunks (each entry once in the 17 → 18 record, once in the aggregate), the guide +6 in two hunks (one three-line bullet per entry under Semantic). No conversionId was added. Parsed at the head: protocolVersion 18.0.0; the 17 → 18 record holds 64 converted (64 distinct, every toMajor 18) and 329 migrated (329 distinct migrationIds, every toMajor 18); the aggregate 16 → 18 holds 121 and 406, which are the per-major records summed (57 + 64, 77 + 329). The 329 ids equal, as a set, the 329 entries/semantic/18.*.ts stems at the head and at the main tip (set difference empty both ways). The guide's 17 → 18 section carries a 64-row mechanical table and 329 semantic bullets. The generators' own checks are the verdict: Type Check · source gates (check:spec-changes, check:upgrade-guide, check:future-spec-major among its steps) concludes success on this head. Right.

The hand-edited changeset, line by line. The word diff of .changeset/22130-protocol-18.md from 4ba5952ea1 is two tokens, 327 → 329: the adr-0087 marker's prose ("the step's 329 D3 semantic entries") and the bullet "64 mechanical conversions and 329 semantic entries". Both equal the regenerated record's migrated count and the guide's bullet count; 64 equals the converted count. The marker's already-registered list (the first match, ids up to the first close paren) is 64 ids, set-equal to the head's 64 step-18 conversionIds, unchanged since the merge base, and each id pre-dates the merge base because the conversions registry did not move. Clause-② (line 8) is byte-identical to its state at 4ba5952ea1 and at eb23db8a82. Right.

Nothing else the PR owns moved. Of the 52 paths, 48 have byte-identical +/− lines in the two net diffs (3ca71b6e05..4ba5952ea1 against e148ca9842..6ec484243e, headers stripped). The four that differ are exactly the four this delta names, compared as sorted multisets: the changeset 2 only-before / 2 only-after (the count tokens); the guide 0 / 6; spec-changes.json 0 / 28; verify-host-root.test.ts 0 / 2 (new to the set). So every judgment the at-tier records 6076766071 and 6079895139 made about the 48 — the accept and refuse sets at every door, the specVersion prescription from PROTOCOL_MAJOR, the lockstep exception's shape and the gate's third question, the #17134 re-premise and the window file, the two runtime fixtures at greater-or-equal 17.1.0 — stands by identity.

No accept set moves beyond what the PR already declared. The one new site is a fixture (a test input), not a door; the two documents project entries the registries already carried; the changeset edit is prose. No door, schema, export or refusal string changed in this delta. The public surface of the PR is the one 6076766071 judged. The lockstep evidence is live at the head: pre.json mode: pre, tag next; .changeset/22080-v18-line-opens.md pending with "@objectstack/spec": major; @objectstack/spec at 17.7.0; PROTOCOL_VERSION '18.0.0'.

Re-sync at my read: none owed. main is one commit past the merge base (#22495): 0 spec paths, 0 added caret-17 literals, 0 paths in common with the PR.

② Semver level

Unchanged in grade and re-verified where the delta could touch it: major for @objectstack/spec under pre mode, patch for @objectstack/mcp, the **BREAKING** banner, feat(spec)!:; no skip-changeset and no allow-major label (labels: documentation, ci/cd, size/xl, tests, tooling). The disposition is one not-required (already-registered …) marker whose 64 ids equal the generated set and whose count prose now says 329 = the record. Clause-②: yes (narrowing: …) — the PR body's line 2 (as re-edited after the dev report) and the changeset's line 8 are byte-identical (same SHA-1, 3300cfb220a1); the delta widens no accept set and narrows none beyond the declared arm (one more current-app fixture sits on the admitted side of the same door). Gate verdicts on this head: Check Changeset concludes success twice — the run on the push (113881328945) and the re-run the body edit fired (113913066996), neither skipped — and Type Check · source gates concludes success. The Clause-②: line is right.

③ Boundary flags

Dev flags (report 6084728061): open_questions empty; out_of_scope_findings empty; three deviations, each answered.

• D1, the second merge and the stale path. Beyond the seat's expectation but inside the dispatch: main took feat(metadata-core,rest,runtime,plugin-email,spec)!: the /meta doors carry no organization; organization-admin metadata authoring closes (ADR-0131 D6, #15206 S3) #22447 mid-round, the documents went stale, and the dev took the separate-regeneration-then-separate-count shape. Judged above as right; the trees are the proof, not the report.
• D2, lock scope (the 138 derived commands run unlocked, per os-dev.md). Process only; CI's conclusions on this head are the verdict, and every derived family concludes success.
• D3, two intermediate WIP pushes (3b97df5a7f, red by construction; 5159d64866). Fast-forward only; the head is what is judged. The claim that 3b97df5a7f reproduces the queue red and 5159d64866 clears it is consistent with the per-file caret-17 counts above and with Test Core (2/6) concluding success on the head.
• The holder note 6081559243, second item (create-objectstack/.../blank/objectstack.config.ts:39 at '^17'): pre-existing, unchanged in this delta, already judged in the body's sweep table (the version pass stamps it together with the template's @objectstack/* ranges; template-consistency.test.ts holds it). Confirmed, not re-opened.
• B1, the PR body. Done this round for the load-bearing parts: Size reads 8,611 / 52 files against e148ca9842 with the 3,000 line; the counts read 64 / 329 / 406 with the five added entries named; a Round 12 paragraph exists; the handshake bullet names the feat(core,cli,verify): bootStack composes what serve composes — item 1 stage 2 of #22301 (HELD at stop conditions) #22381 fixture. Record-only residual: the sweep table (packages/cli 20 files / 34; Total 36 / 52) and the headline "54 sites in 38 files" still carry the round-11 totals, one row short. Nothing a gate reads; the seat's residual.
• B2, the Tier H approval and the human-merge line. Review 5465505916 (os-zhuang, APPROVED at c96d8e9446, not dismissed) is spent once per PR and stands for later pushes; the owning seat lands it (Prime Directive feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14). chore(governance): the human-merge line threshold is 3,000 changed lines (HUMAN_MERGE_LINE_THRESHOLD), per the maintainer's 2026-10-09 ruling #22490 moved HUMAN_MERGE_LINE_THRESHOLD to 3,000 (check-governed-merges.mjs:1115; AGENTS.md §7 class (c) on main now reads 3,000). This PR was over the line at 5,000 and is over it at 3,000 (8,611, generated files included); the landing route is unchanged — class (c) lands the way a Tier H surface does, an authorized APPROVED review and then the owning seat, or a human merge — and that review is on file. The threshold move changes nothing for this landing. No governed path is among the 52 (register: docs/adr/, .claude/, skills/, AGENTS.md, CLAUDE.md, docs/NORTH-STAR.md); Governed Surface Queue Guard concludes success.
• Residuals, unchanged: Check Changeset's two label skips; docs snippets at ^18 versus npm latest (release(v18): the version-pr lane refuses the major boundary at Validate the post-version tree, so #21988 never refreshes into 18.0.0-next.0 — wire the lane's major-only gates in, and stop prerelease cuts re-dating the last GA #22085 Q2); the CLI-advisory window until the first next.0 pass; the hot-file queue — any step-18 writer that lands on main before this PR means one more regeneration-only re-sync of exactly this shape, and any new current-app fixture at ^17 means one more fixture edit of exactly 5159d64866's shape (the queue runs the full suite while PR-side CI runs the affected subset, so the second class shows only in the queue).

Check-runs on this head at my reads (42 runs across 35 names; seven names ran twice because the body edit after the dev report fired a second pull_request run on the same head). First read, newest per name: 30 success, 4 skipped, 1 in_progress (Check Changeset, its second run). Second read, six minutes later: 31 success, 4 skipped, 0 in progress, 0 red; across all 42 runs 38 success, 4 skipped. The seven required contexts conclude success: Lint & Repo Gates, TypeScript Type Check, Dogfood Regression Gate (and its three shards), Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard, Test Core (and its six shards, (2/6) included — the shard the queue failed on); also Check Changeset, the four Type Check · jobs, Build Docs, Dogfood Verify CLI, Spec property liveness, Flag docs affected by code changes, Check Documentation Links, the claim / single-writer / part-of guards, filter. Skipped: Console Pin Gate (no .objectui-sha move), Packed-tarball smoke (opt-in), and the second runs of Auto Label and Check PR Size (their first runs on this head, 113881487819 and 113881328312, conclude success; the re-run on the edit event skipped by its own condition). Red — none.

Implemented-by: claude/issue-22130-protocol-18
Reviewed-by: session_01VZqqwTj2wsihZEbfT6yyYN

VERDICT: PASS