docs(spec): the routes / App.apis retire text stops sending app authors to an imperative http.server route (ruling C′ item 2)

[objectstack-fleet]

Fixes #23216

Clause-②: no

Ruling C′ on #23128 (6142279866), item 2: the imperative http.server route is retired as an app-author surface. This PR changes the retire text and the published copies so they no longer send app authors to a kernel:ready handler. An app declares defineStack({ apis }) (type: 'object_operation' or 'flow', ADR-0121), computes in a flow, and registers code as a stack function (defineStack({ functions })) or a connector. The http.server service, core-service-contracts.ts and the platform plugins that mount on it are untouched. No key is added or removed.

What changed

Site	Change
packages/spec/src/kernel/manifest.zod.ts (contributes.routes retire message + TSDoc)	The imperative sentence is replaced by the app-author rule, with the reason: a code-mounted route gets no caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry.
packages/spec/src/ui/app.zod.ts (App.apis retire message)	Surface extension, declared here. The dispatch hypothesis said this row was a different key and should be edited only if it said the same thing. It does: it said "A route that genuinely needs handler CODE is mounted imperatively instead: resolve the http.server service … register the route on kernel:ready". This is the source of the metadata.mdx / app.mdx hits that the acceptance grep covers, and the claim names metadata.mdx "where it renders the same text". Code now goes to a flow plus a stack function or connector.
packages/spec/src/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts	The published replacement no longer gives the imperative advice or names the deleted showcase POST /api/v1/showcase/recalc route. acceptanceCriteria now describes the current teaching sites. reason is kept as is, because it records the earlier ruling.
packages/spec/src/api/plugin-rest-api.zod.ts:34-39 TSDoc	The example now says it shows a platform plugin mounting its own doors, and states the app-author rule. The deleted recalc-endpoint "real consumer" claim is removed.
packages/spec/src/api/dispatcher.zod.ts docblock item 4 (+ generated api/dispatcher.mdx)	Patch round (contract review FAIL 6206636299 on 3c31cd913e): http.server is the platform plugins' own door-building primitive; an app declares defineStack({ apis }), computes in a flow, and registers code as a stack function or connector. The contributes.routes removal clause is kept.
packages/spec/src/kernel/metadata-plugin.zod.ts:119,127, manifest.zod.ts:753, retired-keys/18.kernel__Manifest__contributes.routes.ts:10, migration 18 reason	Sweep fixes: the comments no longer present the imperative mount as the app answer, and the 2026-08-22 provenance gains one sentence saying ruling record 6142279866 narrowed the redirect.
packages/spec/liveness/manifest.json row note	Same correction: the recalc-endpoint mention is removed and http.server is described as the platform plugins' primitive.
scripts/check-optional-error-sink-contract.mjs:164 scope comment	examples/** now holds zero further red sinks, not one, because the recalc route was deleted. Comment only.
packages/spec/src/kernel/manifest.test.ts	The pin's regex used to match …http\.server (the old advice). It now asserts the new rule's substance (does not mount routes on http.server … defineStack({ apis }) … flow … defineStack({ functions }) … connector) and that kernel:ready / the imperative wording does not come back. The pin is changed, not deleted.
content/docs/references/** (5 pages)	Generated, not hand-edited: pnpm --filter @objectstack/spec check:generated --fix (it proved only check:docs stale) rewrote kernel/manifest.mdx, api/package-api.mdx, api/metadata.mdx, ui/app.mdx, api/plugin-rest-api.mdx.
.changeset/23216-routes-retire-text.md	@objectstack/spec patch.

Each of the four pointer sites from 6147168221 was re-read on main at 4fe8b3def. All four were still stale, and all four are edited here; none had been fixed already.

Acceptance

• git grep -n "mounted imperatively" -- packages/spec content/docs finds nothing (exit 1).
• The manifest reference page renders the new sentence (content/docs/references/kernel/manifest.mdx:92): "… Delete the key. An app does not mount routes on http.server — that service is the platform's own door-building primitive, … Declare the endpoint under defineStack({ apis }) (type: 'object_operation' or 'flow', ADR-0121), compute in a flow, and register code as a stack function (defineStack({ functions })) or a connector."
• pnpm --filter @objectstack/spec build && pnpm --filter @objectstack/spec check:generated: "All 14 generated artifacts are up to date", exit 0.
• pnpm --filter @objectstack/spec typecheck && pnpm --filter @objectstack/spec test: 680 files, 20784 passed, 1 todo, exit 0. This includes retired-key-migrate-sentence.test.ts and its family, and manifest.test.ts.
• Derived gates at head 846feb0c (134 families): 131 exit 0, 3 NOT MEASURED (exit 3, declared to CI: teardown-shape self-test, dual-build-cjs-loads, lean-entry-closure); --ran reconciles 134 / 131 / 3 / 0 UNRUN, exit 0.

Imperativ sweep (patch round)

git grep -n -i imperativ -- packages/spec/src content/docs (releases/ excluded) at 846feb0. FIXED (app-author route advice): api/dispatcher.zod.ts:17 + references/api/dispatcher.mdx:19; kernel/metadata-plugin.zod.ts:119,127; kernel/manifest.zod.ts:753 (provenance, supersede note added); migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts:10 (same); semantic/18.plugin-manifest-contributes-routes-retired.ts reason (closing sentence added). KEPT, platform-only: api/plugin-rest-api.zod.ts:32 + plugin-rest-api.mdx:32 heading, now 'Serving routes from a platform plugin (imperative http.server mount)'; the example is a platform plugin mounting its own doors, which the ruling keeps. KEPT, provenance of the 2026-08-22 ruling, with the narrowing now stated in the same field: semantic/18…routes-retired.ts reason lines 23/33/41. KEPT, different capability (not routes or http.server): manifest.zod.ts:811 and semantic/18.plugin-manifest-contributes-dead-members-retired.ts:15/36 plus retired-keys/18…contributes.events.ts:10 (event subscription in plugin code); manifest.zod.ts:851 + package-api.mdx:233/manifest.mdx:88 (engine.registerAction); studio/plugin.zod.ts + references/studio/plugin.mdx (Studio component activation). KEPT, unrelated word sense: concepts/glossary/protocol prose 'imperative code' vs declarative; retired-key.ts:303, retired-key.test.ts:159, ui/component.test.ts:1375/1382, ui/form-option-enum-derive.test.ts:86, kernel/manifest.test.ts:406/552 ('an imperative fix' = an imperative-mood prescription); manifest.test.ts:462 is the negative pin itself. kernel:ready beside http.server sweep: only content/docs/kernel/events.mdx:22/35 and contracts/plugin-lifecycle-events.ts:77, which describe kernel lifecycle and platform HTTP middleware, not app routes; kept. git grep 'mounted imperatively' -- packages/spec content/docs: exit 1.

Acceptance notes

• The published skill skills/objectstack-api/SKILL.md:119 still has a decision-table row: "http.server mount (plugin code) — The endpoint needs real handler CODE … Mount it on http.server." It is the same retired advice, and its eval skills/objectstack-api/evals/endpoints-auth-routes.json may pin it. Both are outside this card's claimed surface, and skills/** is a Tier H governed surface, so they are not edited here. They are reported to the seat to file.

🤖 Generated with Claude Code

https://claude.ai/code/session_017dvSKLgBT3sjuE98di6PW1

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 6 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/liveness/manifest.json, packages/spec/src/api/plugin-rest-api.zod.ts, packages/spec/src/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/api/declarative-endpoints.mdx (via object_operation (literal, a string literal in a comment on a changed line))
• content/docs/getting-started/quick-reference.mdx (via AppSchema (symbol, a top-level const), ManifestSchema (symbol, a top-level const object), object_operation (literal, a string literal in a comment on a changed line))
• content/docs/plugins/development.mdx (via ManifestSchema (symbol, a top-level const object))
• content/docs/protocol/kernel/http-protocol.mdx (via object_operation (literal, a string literal in a comment on a changed line))
• 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 MetadataTypeSchema (symbol, a top-level const))
• content/docs/releases/v14.mdx (via AppSchema (symbol, a top-level const))
• content/docs/releases/v15.mdx (via ManifestSchema (symbol, a top-level const object))
• content/docs/releases/v17/17-0.mdx (via AppSchema (symbol, a top-level const))

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

• 3 changed file(s) yielded no anchor (packages/spec/liveness/manifest.json, packages/spec/src/api/plugin-rest-api.zod.ts, packages/spec/src/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts) — pages documenting those are invisible to this run
• 3 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 142 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 d3df3ba24bbbb280d138d98fed7af5fe05f4a9ce → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

席位核对 · ACCEPT · PR #23785 @ 3c31cd913e (#23216) · domain:spec seat 1 · os-elon-musk · session session_01HjR8RUwTPQ3TgbfKihmxp9 · 2026-10-16T02:19Z

Reviewer of record. Every item below was checked against GitHub, not against the report (6206484307 on #23216).

• Shape:
  • Draft, base main. The first line is Fixes #23216, the body's only closing keyword, then Clause-②: no, matching claim 6205765363.
  • 13 files, +67/−41, none governed. Assignee os-elon-musk.
• Ruling C′ item 2 (6142279866), read in the diff:
  • The manifest.contributes.routes retire message no longer says "mounted imperatively … on kernel:ready".
  • It now gives the app-author rule: declare under defineStack({ apis }) (object_operation or flow, ADR-0121), compute in a flow, and register code as a stack function (defineStack({ functions })) or a connector.
  • http.server is named as the platform's own door-building primitive and is untouched. No key moved.
• The acceptance grep: git grep -n "mounted imperatively" -- packages/spec content/docs at the head finds nothing. The five reference pages are regenerated (check:generated reported up to date), and none was hand-edited.
• Outside the claimed file surface, accepted: app.zod.ts, the App.apis retire text, carried the same imperative advice. It is that sentence's producer, the acceptance grep cannot pass without it, and the PR body names it. The four pointer-6147168221 sites are edited as briefed: migration entry 18, the plugin-rest-api.zod.ts TSDoc, the liveness row note, and the error-sink scope comment.
• The pin: manifest.test.ts now asserts the new rule's substance, plus not.toMatch(/kernel:ready|imperativ/). It was changed, not deleted.
• The report's open question, the seat's call: A, keep the reason clause. "No caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry" is the reasoning of analysis 6142067136 (axis ①), which the maintainer's 「同意」 ratified as C′. A refusal that says why is harder for an AI author to route around.
• Changeset: @objectstack/spec patch, sentences checked against the diff. The message text changes, no key is added or removed, and the http.server sentence matches the ruling's last clause.
• Out of scope, filed: skills/objectstack-api/SKILL.md:116-:120 and :201 onward still teach app authors the http.server mount, and its eval pins that. Filed as skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787 for the domain:skills seat (Tier H).
• Before the queue: a CONTRACT_REVIEW_TIER contract review (face packages/spec/src/**), and every check green on the head.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3c31cd913e9d28d305724b49ed4ae27c35a02dea
Local-runs: none
Scope: packages/spec/src/api/plugin-rest-api.zod.ts, packages/spec/src/kernel/manifest.zod.ts, packages/spec/src/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts, packages/spec/src/ui/app.zod.ts + packages/spec/src/kernel/manifest.test.ts (the pin the routes message changes), packages/spec/src/shared/retired-key.ts (the tombstone contract both messages sit in), packages/spec/src/api/endpoint.zod.ts (the type vocabulary the new text cites), docs/adr/0121-declarative-endpoint-routing-namespace-and-channel-split.md (cited), packages/cli/src/commands/migrate/meta.ts (where entry 18's replacement and acceptanceCriteria print), packages/spec/src/api/dispatcher.zod.ts and content/docs/references/api/dispatcher.mdx (a former teaching site entry 18's new acceptanceCriteria makes a claim about), packages/spec/src/kernel/metadata-plugin.zod.ts (named in entry 18's reason), packages/spec/liveness/manifest.json, .changeset/23216-routes-retire-text.md, scripts/check-optional-error-sink-contract.mjs, and the five regenerated pages content/docs/references/kernel/manifest.mdx, api/package-api.mdx, api/metadata.mdx, api/plugin-rest-api.mdx, ui/app.mdx. The rest of the diff (none remains outside this list) is the lane seat's ACCEPT at TIER_DEFAULT.

Inputs read: card #23216 body and all three comments (pointer 6147168221, claim 6205765363, dev report 6206484307), PR #23785 body and file list, the net diff of the branch against main at its merge-base 4fe8b3def (13 files, +67/-41, identical to the diff against current origin/main), and the check-runs on the head.

① Derived judgments

Accept set: nothing moves. ManifestSchema.contributes.routes and AppSchema.apis stay retiredKey() tombstones; no key is added, removed or re-typed; http.server (core-service-contracts.ts, contracts/http-server.ts) and the platform plugins that mount on it are untouched. Judged right.

Public-surface text changes the diff implies, each judged:

1. manifest.zod.ts:884-895 — the contributes.routes tombstone message (the zod issue an author sees at os plugin build) and its TSDoc line. The imperative kernel:ready / http.server sentence is replaced by the app-author rule with the reason clause. The cited facts hold: endpoint.zod.ts:174 is the type enum and says only object_operation and flow execute in 17.x; ADR-0121 exists; the sibling contributes.functions tombstone three lines up already names defineStack({ functions }) as the hook-binder route to registerFunction; the reason clause (no caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry) is the card body's own finding from showcase: the "Recalculate Estimate" / "Recalculate Selection" api actions answer 500 — recalc-endpoint.ts calls ctx.ql.update with no execution context, which the security layer refuses as a principal-less write #23128. The message keeps "Delete the key" and carries no os migrate meta sentence, correctly, since no ADR-0087 conversion covers a package manifest (the retired-keys entry says why). Judged right.
2. app.zod.ts:1620-1630 — the App.apis tombstone message. The surface extension is right: the row carried the identical imperative sentence, it is the producer of the metadata.mdx and app.mdx hits, metadata.mdx is on the card's own list, and the card's acceptance grep over content/docs cannot pass without it. The standardized closing os migrate meta --from 16 sentence is byte-unchanged, so the migrate-sentence pin family is untouched. Judged right.
3. 18.plugin-manifest-contributes-routes-retired.ts replacement — printed by os migrate meta as the headline; the deleted showcase POST /api/v1/showcase/recalc example and the imperative advice are gone, the "live since protocol 17" provenance is kept. reason is left as the record of the 2026-08-22 ruling. Judged right.
4. 18.plugin-manifest-contributes-routes-retired.ts acceptanceCriteria — printed by os migrate meta as verify: (packages/cli/src/commands/migrate/meta.ts:802), so it is author-facing. The new sentence claims: "No author-facing material still recommends the key, and none sends an app author to an imperative http.server mount: every former teaching site points at defineStack({ apis }), a flow, and a stack function or connector for code." Judged wrong at this head. The entry's own reason names "the dispatcher protocol doc" as one of the former teaching sites, and at 3c31cd9 packages/spec/src/api/dispatcher.zod.ts:16-21 still reads "Plugins that need a code handler mount it imperatively on the http.server service (resolve it from the plugin context on kernel:ready)", with the generated copy published at content/docs/references/api/dispatcher.mdx:18-23. That is the sentence this card retires, one inflection away from the card's acceptance grep ("mount it imperatively" versus "mounted imperatively"), and it draws no platform/app line, which is exactly the line this PR had to draw in plugin-rest-api.zod.ts by inserting "A PLATFORM plugin". A verify: line that tells an upgrading author every teaching site is corrected while a sibling file in the same package still teaches the retired door is the declared-not-delivered claim the house rules refuse. Both files sit inside the card's governed surface (packages/spec prose plus content/docs/**), so the fix is in reach on this branch: either edit dispatcher.zod.ts the way plugin-rest-api.zod.ts was edited (a platform plugin mounts in code; an app declares apis:, computes in a flow, registers a stack function or connector) and regenerate dispatcher.mdx with check:generated --fix, or narrow the acceptanceCriteria sentence to the sites this PR actually corrected. The first is the one the ruling asks for.
5. plugin-rest-api.zod.ts:32-39 module TSDoc and its generated plugin-rest-api.mdx — the example now says a platform plugin mounts its own doors and states the app-author rule; the deleted recalc-endpoint "real consumer" claim is removed (the file is absent at the head). Judged right.
6. manifest.test.ts:433-463 — the pin is changed, not deleted: the positive regex follows the new message's order (Delete the key → does not mount routes on http.server → defineStack({ apis }) → flow → defineStack({ functions }) → connector, read against the message at head, in that order) and a negative match on kernel:ready|imperativ is added so the retired advice cannot return silently. A rule and its gate as one change. Judged right.
7. liveness/manifest.json:194 row note, scripts/check-optional-error-sink-contract.mjs:163-168 scope comment — both say what is true at head: the recalc route is gone, examples/** holds zero red sinks, http.server is the platform plugins' primitive. The liveness gate (Spec property liveness) is green on the head. Judged right.
8. The five content/docs/references/** pages — each hunk is byte-for-byte the rendering of its source string above; Build Docs, Lint & Repo Gates (which carries check:generated) and Check Documentation Links are green on the head. Judged right.

Gate verdicts on the head at the time of this record: 27 check-runs green, 5 skipped by path filter (Console Pin Gate, Temporal Conformance, Dogfood shards, Packed-tarball smoke), and 7 still in progress (Test Core 1/6 to 6/6, Type Check · workspace). The dev's three locally unmeasured families are CI-owned and sit under Build Core (green) and the still-running jobs; nothing in this record depends on their outcome, since the verdict is decided by item 4 above.

② Semver level

.changeset/23216-routes-retire-text.md declares @objectstack/spec patch with Clause-②: no and no arm, and Check Changeset is green. That matches what the diff publishes: tombstone issue messages, a semantic-migration notice and TSDoc inside a released package change, so skip-changeset would be wrong, and no accept set widens or narrows, so nothing above patch is owed. The changeset body states the FROM → TO rule in the words the messages use. Clause-②: no — right.

③ Boundary flags

• Dev deviation, app.zod.ts + ui/app.mdx added to the surface: answered, accepted (judgment 2).
• Dev deviation, manifest.test.ts outside the claimed list: answered, accepted (judgment 6); a pin that follows its message is part of the same change.
• Dev deviation, model-free commit trailers: process only, no contract bearing; accepted.
• Dev deviation, three derived families NOT MEASURED locally and declared to CI: answered by the head's check-runs as listed under ①; the still-running jobs must be green before any landing, as Tier S requires regardless of this record.
• Dev deviation, primary checkout detached to free the branch for a worktree: process only; accepted.
• Dev open_questions, keep the reason clause in the retire text or trim to the bare rule: answered — keep it. The clause states the card body's own finding, adds no key or accept set, and a refusal that names its reason is harder for an upgrading agent to route around by re-deriving the mount from core-service-contracts.ts.
• Escalated, blocking on this branch: packages/spec/src/api/dispatcher.zod.ts:16-21 and generated content/docs/references/api/dispatcher.mdx:18-23 (judgment 4). Inside the card's governed surface; fix on this branch and re-render the record on the new head.
• Escalated to the seat to file, Tier H and outside this card: skills/objectstack-api/SKILL.md:119 (decision-table row "http.server mount (plugin code) … Mount it on http.server") and its eval skills/objectstack-api/evals/endpoints-auth-routes.json:27-30 (must_contain pins http.server, kernel:ready, getService), both still teaching the retired door, as the dev reported; and docs/adr/0088-*.md:40, whose router row records the 2026-08-22 ruling's "corrected to point at the imperative mount" and now needs an amended line under ruling C′, by the ADR's own hand.
• Noted, not blocking: packages/spec/src/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts:10 is an unpublished code comment recording the 2026-08-22 ruling's redirect; history, like entry 18's reason.

Implemented-by: claude/issue-23216-routes-retire-text
Reviewed-by: session_01HjR8RUwTPQ3TgbfKihmxp9

VERDICT: FAIL

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 846feb0c37f9c98ea5e4ed13e8d0638c222cb5f7
Local-runs: none
Scope: packages/spec/src/api/dispatcher.zod.ts, packages/spec/src/api/plugin-rest-api.zod.ts, packages/spec/src/kernel/manifest.zod.ts, packages/spec/src/kernel/metadata-plugin.zod.ts, packages/spec/src/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts, packages/spec/src/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts, packages/spec/src/ui/app.zod.ts + packages/spec/src/kernel/manifest.test.ts (the pin the routes message changes), packages/spec/src/api/endpoint.zod.ts (the type vocabulary the new text cites), packages/spec/src/migrations/types.ts (what acceptanceCriteria is for), packages/cli/src/commands/migrate/meta.ts (where entry 18's replacement, reason and acceptanceCriteria print as the headline, why: and verify:), packages/spec/src/contracts/plugin-lifecycle-events.ts (the one kernel:ready beside http.server sweep hit outside the diff), docs/adr/0121-declarative-endpoint-routing-namespace-and-channel-split.md (cited), docs/adr/0088-metadata-kind-admission-and-retirement.md and skills/objectstack-api/SKILL.md with skills/objectstack-api/evals/endpoints-auth-routes.json (the two former teaching sites entry 18's own reason names that this PR does not touch, read at the head to judge the acceptanceCriteria sentence), packages/spec/liveness/manifest.json, scripts/check-optional-error-sink-contract.mjs, .changeset/23216-routes-retire-text.md, content/docs/plugins/index.mdx (the one hand-written http.server hit), and the six regenerated pages content/docs/references/api/dispatcher.mdx, api/plugin-rest-api.mdx, api/metadata.mdx, api/package-api.mdx, kernel/manifest.mdx, ui/app.mdx. The rest of the diff (none remains outside this list) is the lane seat's ACCEPT at TIER_DEFAULT.

Inputs read: card #23216 body and all six comments (pointer 6147168221, claim 6205765363, round-1 dev report 6206484307, ACCEPT pointer 6206598227, patch round 6206654655, round-2 dev report 6207289001); PR #23785 body, its 17-file list, and its three comments including the first contract review 6206636299 (FAIL on the earlier head 3c31cd9); the net diff of the branch against main at its merge-base 4fe8b3d (17 files, +108/-64, identical to the three-dot diff against current origin/main, four commits on the branch past the merge-base and no foreign commit); and the check-runs on the head. This is the second record on this PR and judges the whole PR at the new head as a fresh record.

① Derived judgments

Accept set: nothing moves. ManifestSchema.contributes.routes and AppSchema.apis stay retiredKey() tombstones; no key is added, removed or re-typed; http.server (core-service-contracts.ts, contracts/http-server.ts) and the platform plugins that mount on it are untouched; no governed path is in the file list (Governed Surface Queue Guard green). Judged right.

Public-surface text changes the diff implies, each judged:

1. dispatcher.zod.ts:16-24 docblock item 4 and its generated dispatcher.mdx:18-26 — the first review's blocking finding. The sentence "Plugins that need a code handler mount it imperatively on the http.server service (resolve it from the plugin context on kernel:ready)" is gone. The item now draws the platform/app line the ruling asks for: http.server is the platform plugins' own door-building primitive, not an app-author surface; an app declares under defineStack({ apis }) (type: 'object_operation' or 'flow', ADR-0121), computes in a flow, and registers code as a stack function (defineStack({ functions })) or a connector. The contributes.routes removal clause and its commit reference are kept. The generated page is the byte-for-byte rendering. Judged right, and it closes the first review's judgment 4.
2. manifest.zod.ts:886-895 — the contributes.routes tombstone message (the zod issue an author sees at os plugin build) and its TSDoc line. The imperative sentence is replaced by the app-author rule with the reason clause. The cited facts hold at the head: endpoint.zod.ts:174 is the type enum and says only object_operation and flow execute in 17.x; ADR-0121 exists; the sibling contributes.functions tombstone already names defineStack({ functions }) as the hook-binder route to engine.registerFunction; the reason clause (no caller identity, auth gate, rate limit, namespace carve-out or OpenAPI entry) is the card body's own finding from showcase: the "Recalculate Estimate" / "Recalculate Selection" api actions answer 500 — recalc-endpoint.ts calls ctx.ql.update with no execution context, which the security layer refuses as a principal-less write #23128. The message keeps "Delete the key" and rightly carries no os migrate meta sentence (no ADR-0087 conversion covers a package manifest). Judged right.
3. manifest.zod.ts:751-757 provenance comment (sweep) — the 2026-08-22 Option B record is preserved verbatim and gains, in the same parenthesis, that ruling record 6142279866 narrowed the redirect. History is kept, the narrowing is attributed to the record that made it, and the trail is findable from the code (Prime Directive [WIP] Add Chinese version of the documentation #13's corollary: leave the ruling's id where the decision is implemented). Judged right.
4. app.zod.ts:1620-1630 — the App.apis tombstone message. The surface extension stands: the row carried the identical imperative sentence, it is the producer of the metadata.mdx and app.mdx hits, and the card's acceptance grep over content/docs cannot pass without it. The closing os migrate meta --from 16 sentence is byte-unchanged, so the migrate-sentence pin family is untouched. Judged right.
5. plugin-rest-api.zod.ts:32-39 module TSDoc and its generated plugin-rest-api.mdx — the heading now reads "from a platform plugin", the comment states the app-author rule, and the deleted recalc-endpoint "real consumer" claim is gone. The code beneath (:43-:52) is a RestApiPlugin mounting /api/v1/discovery and /api/v1/data/:object, the platform's own routes, so the heading is true of what sits under it; the closing paragraph (:58-:60) keeps defineStack({ apis }) as the no-code alternative. Judged right.
6. metadata-plugin.zod.ts:118-130 — the ADR-0088 router comments. The first now says the app's form is declarative apis: while http.server mounts stay the platform plugins' own primitive; the second, inside the ADR-0088 admission-test paragraph, says the router kind's delivered form is "the platform's imperative http.server mount", which is still a code contribution, so the kind's retirement reasoning is unchanged. The comment leads ADR-0088:40's own text until skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787 amends it; the ADR's decision (router is not a metadata kind) is not reversed here. Judged right.
7. retired-keys/18.kernel__Manifest__contributes.routes.ts:8-14 — an unpublished code comment; the 2026-08-22 record is kept and the narrowing by ruling record 6142279866 is added beside it. Judged right.
8. 18.plugin-manifest-contributes-routes-retired.ts replacement — printed by os migrate meta as the headline (meta.ts:800). The deleted showcase POST /api/v1/showcase/recalc example and the imperative advice are gone; the "live since protocol 17" provenance is kept inside the apis parenthesis. Judged right.
9. Same entry, reason — printed as why:. The 2026-08-22 ruling's record, including its list of the six former teaching sites (the skill's decision table, the dispatcher protocol doc, ADR-0088:40, app.mdx, the plugin-rest-api example, the metadata-plugin router comments), is preserved verbatim; one closing sentence states that a later ruling narrowed the redirect. Judged right.
10. Same entry, acceptanceCriteria — printed as verify: (meta.ts:802), defined in types.ts:111 as how the consumer proves the hand-migration correct. The sentence reads: "No author-facing material still recommends the key, and none sends an app author to an imperative http.server mount: every former teaching site points at defineStack({ apis }), a flow, and a stack function or connector for code." Its first clause is true. Its second clause is true at this head for every former teaching site inside packages/spec and content/docs — the four this PR corrected (judgments 1, 4, 5, 6) — and it is the sentence the first review required to be made true or narrowed. Judged right within the card's surface. Its universal "every" still outruns two of the six sites the same entry's reason names, both outside this PR by the seat's carry: skills/objectstack-api/SKILL.md:119 (decision-table row "http.server mount (plugin code) … Mount it on http.server"), :201-:214 (the "Code routes: mounting on http.server" section) with its eval evals/endpoints-auth-routes.json:27-30 pinning http.server, kernel:ready, getService; and docs/adr/0088-metadata-kind-admission-and-retirement.md:40. The dev report's "so acceptanceCriteria is now true" is therefore overstated by those two sites; the reach beyond this PR is recorded in ③ as the carry, not as a defect of this PR.
11. manifest.test.ts:433-463 — the pin is changed, not deleted. The positive regex follows the message's order at the head (Delete the key → does not mount routes on http.server`` → defineStack({ apis }) → `flow` → `defineStack({ functions })` → `connector`), and the negative match on `kernel:ready|imperativ` keeps the retired advice from returning silently. Test Core 1/6 to 6/6 green on the head. A rule and its gate as one change. Judged right.
12. liveness/manifest.json:194 row note and scripts/check-optional-error-sink-contract.mjs:163-168 scope comment — both say what is true at the head: the recalc route is gone, examples/** holds zero red sinks, http.server is the platform plugins' primitive, the app's form is defineStack({ apis }). Spec property liveness green. Judged right.
13. The six content/docs/references/** pages — each hunk is byte-for-byte the rendering of its source string; build-docs.ts --check runs under check:generated, which Lint & Repo Gates carries; Build Docs and Check Documentation Links are green. None hand-edited. Judged right.

The dev's sweep ledger was re-derived, not trusted: git grep -n -i imperativ over packages/spec/src and content/docs (releases excluded) at the head returns exactly the dev's FIXED and KEPT sets — the surviving hits are the platform-plugin example heading, provenance with the narrowing stated beside it, a different capability (events, actions, Studio activation), or the declarative-versus-imperative word sense. git grep -n "http.server" over hand-written content/docs returns one hit, plugins/index.mdx:217, which names the providing plugin and teaches no mount. git grep -n "kernel:ready" beside http.server returns the platform-plugin example and plugin-lifecycle-events.ts:77-83, which describes platform middleware ordering, not app routes. The card's own grep, git grep -n "mounted imperatively" -- packages/spec content/docs, returns nothing at the head.

Gate verdicts on the head at the time of this record: 48 check-runs, 41 success, 7 skipped by path filter (Auto Label, Check PR Size, Console Pin Gate, Dogfood Regression Gate matrix, Dogfood Verify CLI, Packed-tarball smoke, Temporal Conformance), 0 failed, 0 in progress. The four in_progress duplicates seen at this record's first read (Check Changeset, two claim guards, Part-of PR) completed green before it was posted. The dev's three locally unmeasured families are CI-owned and sit under Build Core, Test Core 1/6 to 6/6 and Type Check · workspace, all green.

② Semver level

.changeset/23216-routes-retire-text.md declares @objectstack/spec patch with Clause-②: no and no arm, and Check Changeset is green. That matches what the diff publishes: tombstone issue messages, a semantic-migration notice, TSDoc and docblocks inside a released package change, so skip-changeset would be wrong, and no accept set widens or narrows, so nothing above patch is owed. The changeset body states the FROM → TO rule in the words the messages use and names http.server as unchanged for platform plugins; it does not list the patch round's dispatcher docblock, which is prose in the same package under the same sentence and needs no row of its own. Clause-②: no — right.

③ Boundary flags

• The first review's blocking finding is closed. Review 6206636299 (FAIL on the earlier head 3c31cd9) found dispatcher.zod.ts:16-21 and generated dispatcher.mdx:18-23 still teaching the imperative http.server mount, which made entry 18's acceptanceCriteria false. At 846feb0c37f9c98ea5e4ed13e8d0638c222cb5f7 both sites carry the platform/app split (judgment 1), the page is regenerated and not hand-edited, and the sweep the patch round asked for was run and its ledger holds under re-derivation. Closed.
• Dev deviation (round 2), the sweep edited four further source sites beyond the dispatcher (metadata-plugin.zod.ts:119,127, manifest.zod.ts:753, the retired-keys routes comment, entry 18 reason): answered, accepted — each is item 3 of the patch round ("every app-author hit is fixed"), each is judged above (3, 6, 7, 9), and the claim amendment 6206654655 covers the dispatcher while the seat's round text covers the rest.
• Dev deviation (round 2), the worktree recreated from the branch at 3c31cd9: process only; the branch carries exactly four commits past the merge-base and no foreign commit. Accepted.
• Dev deviations from round 1 (app.zod.ts and ui/app.mdx added to the surface; manifest.test.ts outside the claimed list; model-free commit trailers; three derived families NOT MEASURED locally; the primary checkout detached): answered in the first record and re-affirmed here (judgments 4 and 11); the three CI-owned families are now green on this head.
• Dev open_questions: round 1's one question (keep the reason clause or trim to the bare rule) was answered A by the seat at 6206575239 and by the first record; round 2 declares none. Nothing open.
• Carried to skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787 (Tier H), out of this PR by the seat's decision — a boundary flag, not a defect of this PR: skills/objectstack-api/SKILL.md:119 and :201-:214 with the eval evals/endpoints-auth-routes.json:27-30 still teach an app author to mount on http.server, and docs/adr/0088-metadata-kind-admission-and-retirement.md:40 still records the imperative mount as the 2026-08-22 correction. Two consequences the seat owns, escalated: (a) entry 18's verify: line (judgment 10) is universal and these two sites are among the six its own reason names, so the printed line is fully true only once skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787 lands; if skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787 does not land in the same release as this PR, the seat owes a one-sentence narrowing of acceptanceCriteria in packages/spec (no Tier H touch) so the shipped verify: does not outclaim the shipped skill — Prime Directive chore: version packages #10's "keep the claim as narrow as the enforcement". (b) Prime Directive [WIP] Add Chinese version of the documentation #13: this PR implements ruling record 6142279866 and leaves that id in the code at every site it touched; the amended status line on ADR-0088:40 that records the narrowing by the ADR's own hand rides skills(objectstack-api): the "Choosing between apis: and a code handler" table and the "Code routes" section still teach app authors to mount on http.server, which ruling C′ (#23128) retired as an app-author surface #23787, and until it lands the code comments in metadata-plugin.zod.ts lead the ADR's text.
• Noted, not blocking: the PR body's "content/docs/references/** (5 pages)" row counts round 1; the dispatcher row adds the sixth regenerated page. Cosmetic.
• Noted, not blocking: the Docs Drift Check lists five hand-written pages by symbol anchor (object_operation, AppSchema, ManifestSchema); the http.server and kernel:ready sweeps above cover them, and none teaches the retired door.

Implemented-by: claude/issue-23216-routes-retire-text
Reviewed-by: session_01HjR8RUwTPQ3TgbfKihmxp9

VERDICT: PASS

---

Generated by Claude Code