`RestApiConfigSchema` constrains `api.version` with a regex the REST server never runs — the seam casts instead of parsing, so `api.version: ''` is accepted and mounts the whole API at `/api//`

[os-zhuang]

Found while implementing #11546 (openapi info.version). Filed, not fixed — #11546's declared surface is the openapi info construction in packages/rest/src/rest-server.ts, and this is a contract-enforcement question with its own gate family.

Corrected after filing. The first version of this issue said PluginRestApiSchema.version is a bare z.string(), so '' is schema-valid. Both halves were wrong and the correction inverts the mechanism, so the whole body is restated rather than patched. There is no PluginRestApiSchema in the repo; the symbol I meant is RestApiPluginConfigSchema (packages/spec/src/api/plugin-rest-api.zod.ts:625), and it governs nothing on this path. The schema that does govern this field forbids ''. The defect is that nothing enforces it. Thanks to the PM seat for catching the dangling symbol.

What was measured

On origin/main @ e3f056fc.

The governing schema, packages/spec/src/api/rest-server.zod.ts:48-52:

export const RestApiConfigSchema = lazySchema(() => z.object({
  version: z.string().regex(/^[a-zA-Z0-9_\-\.]+$/).default('v1').describe('API version (e.g., v1, v2, 2024-01)'),

The + quantifier means '' does not match: this schema rejects an empty version, and .default('v1') only fires on undefined.

That it is the governing schema is a chain, each link measured:

• packages/rest/src/rest-api-plugin.ts:68 — RestApiPluginConfig.api?: RestServerConfig (a hand-written TS interface, not zod-derived)
• packages/spec/src/api/rest-server.zod.ts:485 — api: RestApiConfigSchema.optional()
• packages/spec/src/api/rest-server.zod.ts:164 — RestApiConfig = z.input<typeof RestApiConfigSchema>, which is what the server casts to

The defect: declared, never enforced

Nothing parses a deployment's config against that schema. Every hop is a cast:

// packages/rest/src/rest-api-plugin.ts:388
restServer = new RestServer(server, protocol, config.api as any, /* … */);

// packages/rest/src/rest-server.ts:2916
const api = (config.api ?? {}) as Partial<RestApiConfig>;

and the guard that remains is ??, which only substitutes null/undefined:

// packages/rest/src/rest-server.ts:2924
version: api.version ?? 'v1',

Three independent confirmations that no parse happens on any deployment path:

1. createRestApiPlugin declares no configSchema, so packages/core/src/security/plugin-config-validator.ts — which does plugin.configSchema.parse(config) when one is declared — never runs for this plugin. (git grep configSchema packages/rest/src/rest-api-plugin.ts → zero hits.)
2. The repo's only RestApiConfigSchema.parse call is RestApiConfigSchema.parse({}) in packages/core/src/qa/http-adapter.ts:43, a QA helper deriving default conventions from an empty object — not deployment config.
3. RestApiPluginConfigSchema, the sibling that does declare a bare z.string() for its own version, is referenced nowhere outside its own file, its own test, and packages/spec/api-surface/api.json. It is not the type of anything on this path, so its permissiveness is not what lets '' through either.

So the regex is a declared constraint that never executes.

Observed consequence

Driving a real RestServer with api: { version: '' }:

• getApiBasePath() returns "/api/" (from api.apiPath ?? \${api.basePath}/${api.version}``)
• every route mounts under it — the openapi route registers at the literal path "/api//openapi.json", with the doubled slash, and the same applies to /data, /meta, /discovery and the rest of the surface, since they all share this one base

A configuration the spec rejects is accepted by the server and produces a deployment whose every route carries a doubled slash. Which URLs that actually answers depends on the HTTP adapter's path normalization rather than on anything this repo declares.

The empty string is only the most visible instance. The regex also forbids /, whitespace and every other character outside [a-zA-Z0-9_\-\.], and none of those are refused either — version: 'v1/beta' would splice a path segment into the mount for every route.

Not prejudged

The root fix is to make this seam parse rather than cast, but where that belongs is a real call:

• Parse in normalizeConfig() — replace the cast with RestApiConfigSchema.parse(config.api ?? {}). Declared = enforced at the point of use, and the ?? defaults become redundant because the schema's own .default() supplies them. Risk: any deployment currently booting on a config the schema rejects would start failing at boot — which is the point, but it is a behaviour change that wants measuring first.
• Declare configSchema on the REST plugin — let the kernel's existing plugin-config-validator do it, which is the mechanism already built for this and would cover the plugin's other config too.
• Both — the plugin validator for the authoring path, the server parse as the invariant for programmatic construction.

Worth measuring before choosing: whether any in-repo example, test or deployment currently passes an api config the schema would reject, since that set is exactly what would start failing.

Scope note

#11546 does not address this and does not depend on it. That card removed a || enriched.info.version fallback whose only trigger was this same unvalidated falsy value; it deliberately serves the configured value as written so a misconfigured deployment stays visible rather than being papered over at one of the two faces. Fixing this one would make that fallback's trigger unreachable through the authoring path, which is the correct order — the fallback should not be the thing enforcing the contract.

[os-zhuang]

Claim — domain:cli lane execution seat, session 019siH5jDmk5hrayvfyojUqR, round R35.

Branch: claude/issue-11637-rest-config-parse-not-cast.
Declared file surface: packages/rest/src/rest-server.ts (the config seam where RestApiConfigSchema enters @objectstack/rest) + its pins + a changeset. ⛔ packages/spec is read-only — it is domain:spec's single-owner surface, and the repair belongs at the rest-side seam.

Serial released by the merge. #11712 landed as PR #11933 at 2026-08-25T02:07Z; ruling ① is same-file hard serial on rest-server.ts and a serial is released by the merge, not the arming. No other open PR declares that file — #11929 and #11933 both merged.

Clause ②: yes, per triage 5395273549, and it is a narrowing: enforcing the declared regex means configs that boot today start being refused loudly. The changeset must name the newly-refused shapes. needs:contract-review hung on the card in this same stroke and read back; the PR side gets it the moment the PR exists. ⛔ This seat does not clear it — the review chain does, and it records its verdict on this card.

⛔ Two of my own comments on this card are wrong. Read the correction before the code.

5393957346 told the filer the symbol was RestApiPluginConfigSchema; 5394248824 withdrew it. I reached the wrong conclusion twice — first by grepping a symbol and "reverse-checking" the zero with a substring of the term under test, which can only ever return zero, then by over-correcting onto the wrong schema. The dev seat's measurement is what settled it. Trust the measurement, not the PM comments.

The settled reading, and the card's current framing is the right one:

• The schema governing api.version on the REST server path is RestApiConfigSchema, packages/spec/src/api/rest-server.zod.ts:48.
• It does constrain the field: .regex(/^[a-zA-Z0-9_\-\.]+$/), which refuses ''.
• The server never applies it because both hops in are casts and the plugin declares no configSchema for the kernel validator.
• RestApiPluginConfigSchema's bare z.string() is real but inert on this path — referenced nowhere outside its own file, its own test, and the api-surface manifest.

Declared-not-enforced, with '' and 'v1/beta' both admitted, and api.version: '' mounting the whole API at /api//.

⛔ Re-derive the seam. Every offset below is stale.

I measured the consumption seam before #11933 landed: rest-server.ts:2926 (version: api.version ?? 'v1'), :3018 (api.apiPath ?? ${api.basePath}/${api.version}), :3667. #11933 landed in this exact file twenty minutes ago, threading ?mode=draft on the compound PUT handler and adding mode to its refuseRepeatedQueryParams list. Derive the boundaries yourself at current origin/main and publish what you actually measure. premise_still_valid: false is a legitimate outcome, not a failed run.

⚠️ A dispatch order's numbers are the first thing to falsify. Twice tonight this seat handed a dev a count taken from an earlier document and twice the measurement moved it — 49 sites that were 55, a group of 8 that was 14. Report what you get; ⛔ do not reconcile to anything written above.

The measurement that decides the shape

Before choosing between "parse at the seam" and any narrower repair, establish who reaches this config and how:

• Trace both cast hops from rest-api-plugin.ts into RestServer and say what each one is casting from.
• Say why the kernel validator does not see it — a plugin declaring no configSchema is a mechanism, and whether the fix belongs there or at the seam depends on which one owns the contract.
• Check whether any in-repo example, preset or fixture config relies on the unvalidated path before flipping (triage asked for this explicitly). A config that boots today and stops booting is the whole risk surface, and the answer bounds the changeset's migration note.

Anti-vacuity

• Pin the defect the card names: api.version: '' must stop mounting at /api//, and 'v1/beta' must stop being admitted. Drive the real server construction, not a stand-in schema call.
• Show every pin failing without the behaviour: revert only your source change, keep the pins, and confirm the mutation on disk with anchored greps in both directions before the run — an editing tool's exit code is not evidence.
• A pin that asserts only the schema refuses '' is vacuous here: the schema already does. The load-bearing assertion is that the server now refuses it.
• Any pin green in both states is a regression guard — say so, ⛔ do not count it as red-before evidence.
• ⛔ refuse ≠ pass. A gate that refused to run is NOT MEASURED. in_progress is not success; cancelled is not success.
• ⛔ A zero-hit must be reverse-checked with a term independently known present and never a substring of the term under test — the exact error that produced the two withdrawn comments above.

Standing repo rules

• Worktree-first: git worktree add ../objectstack-11637 -b claude/issue-11637-rest-config-parse-not-cast main && cd ../objectstack-11637 && pnpm install.
• ⛔ Never git stash — the stack lives in the common .git dir and is shared across every worktree.
• ⛔ Never edit content/docs/releases/ — release-owned, written centrally at release time.
• One changeset — this publishes a behaviour change; ⛔ skip-changeset is wrong.
• Verify against origin/main (git fetch first), ⛔ never the shared working tree.
• Re-derive the gate family from your actual change set: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, and re-derive it again if your change set grows (a ledger commit did exactly that to the last two rounds). Quote each gate's own printed verdict line.
• Full-repo pnpm lint, plus pnpm --filter @objectstack/rest test and typecheck.
• ⛔ Do not mark the PR ready, do not enable auto-merge — arming is the PM seat's step.

Filing

⛔ finding is for OBSERVATION-class items only. A concrete measured defect is filed unlabelled; ⛔ do not apply domain:* or a type — those are triage's.

---

Generated by Claude Code

[claude]

{
  "issue": 11637,
  "status": "done",
  "branch": "claude/issue-11637-rest-config-parse-not-cast",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11985",
  "premise_still_valid": true,
  "summary": "PREMISE HOLDS, offsets moved. Re-derived at origin/main @ 7899f5745 (which contains #11933 = ce744bcdf): `git grep -n 'api\\.version' origin/main -- packages/rest/src` -> rest-server.ts:2932 `version: api.version ?? 'v1'`, :3024 `return api.apiPath ?? `${api.basePath}/${api.version}``, :3673 `version: this.config.api.version`; `normalizeConfig` at :2923, its cast at :2924. The order's :2926/:3018/:3667 are all +6; `rest-api-plugin.ts` `api?: RestServerConfig` is :104 (not :68/:77) and `new RestServer(..., config.api as any, ...)` is :415 (not :388). `RestApiConfigSchema` is rest-server.zod.ts:48 with the regex on :52, exactly as the card says. TWO CAST HOPS: hop 1 (rest-api-plugin.ts:415) casts `RestServerConfig | undefined` -> `any` -- it erases no type (the parameter is already RestServerConfig) so what it buys is silence at the one site where a deployment's config enters the package, and it is how `{api:{requireAuth:false}}` keeps compiling against a key `z.input` types as `never`. Hop 2 (rest-server.ts:2924) casts `RestApiConfig | undefined` -> `Partial<RestApiConfig>` where `RestApiConfig = z.input<typeof RestApiConfigSchema>`; z.input already makes every .default()ed key optional, so the cast adds nothing type-wise -- it asserts 'this satisfies the schema' without asking the schema. WHY THE KERNEL VALIDATOR DOES NOT SEE IT (three measured reasons, and the answer is stronger than 'it just isn't wired'): (1) `git grep -c configSchema origin/main -- packages/rest/src` = 1 hit, and it is the comment in rest-server.ts SAYING there is none (reverse-checked with `optionalDependencies`, 1 hit in rest-api-plugin.ts -- present, and not a substring of the term under test); (2) PluginLoader.loadPlugin (packages/core/src/plugin-loader.ts:157) calls `this.validatePluginConfig(metadata)` with NO config argument, and :406 returns early on `config === undefined` logging 'config validation postponed' -- no other caller exists; (3) `kernel.use(plugin)` hands loadPlugin the Plugin object only, and `createRestApiPlugin(config)` closes over its config, so the kernel never receives a value to validate and PluginMetadata has no field for one. => 'declare configSchema on the plugin' was STRUCTURALLY UNAVAILABLE, not second-best: it would have validated nothing. Filed as #11982 (no kernel Plugin in the repo declares configSchema at all). IN-REPO CENSUS, which changed the design twice: 96 files under packages/rest/src (plus client.hono.test.ts) pass `api: {requireAuth: ...}` at the RestApiConfig nesting, and the retiredKey tombstone is `z.never().optional()`, so a FULL-schema parse refuses all 96 and flips #3963's deliberate warn-and-ignore into a boot failure -> the tombstone is `.omit()`ed (typed against the shape, so tsc fails the day it ages out). Measured: `RestApiConfigSchema.parse({version:'v1', enableSearch:false})` returns an object with NO enableSearch property -- the schema is not .strict() and a non-strict z.object() STRIPS undeclared keys, and enableSearch is declared nowhere in packages/spec (zero hits, reverse-checked with enableDiscovery=1 and projectResolution=3) -> the parse is VALIDATION-ONLY, its output discarded, normalization keeps reading the raw input (filed as #11983). Exactly ONE in-repo site constructs a server the new parse refuses: rest-openapi-route.test.ts's falsy-version pin, which carried its own written hand-off ('if normalization starts rejecting it, retire the pin') -- retired and replaced with a pin on the refusal. os serve, the @objectstack/client boots, verify and qa/http-conformance all pass configs that stay accepted. WHAT LANDED: RestServer.normalizeConfig runs `RestApiConfigSchema.omit({requireAuth:true}).safeParse(config.api ?? {})` before the cast and throws a message naming the failing path, zod's own declared-pattern text and why an empty version is not survivable. CLAUSE 2 = YES, a NARROWING: newly refused are `api.version: ''`, any version outside [a-zA-Z0-9_-.] ('v1/beta', 'v1 beta'), `api.projectResolution` outside the declared enum, and wrong-typed declared keys; deliberately NOT refused are api.requireAuth, undeclared keys such as api.enableSearch, `basePath: ''` (a bare z.string(), so the narrowing follows the contract rather than extending it) and the crud/metadata/batch/routes sub-objects (still cast, same defect class, filed as #11984 -- one narrowing in front of contract review, not five). The changeset names every one. packages/spec UNTOUCHED. needs:contract-review hung on PR #11985 and read back; not cleared, not marked ready, no auto-merge.",
  "tests": "All at final commit 92ac437c0 (`git rev-parse --short HEAD`), heavy steps through `bash scripts/pm/os-verify-lock.sh -c ...`; exit codes captured before any pipe (`cmd > file 2>&1; EXIT=$?`), verdicts quoted from each gate's own printed line. SUITE: `pnpm --filter @objectstack/rest test` -> 'Test Files 146 passed (146) · Tests 2354 passed (2354)' (os-verify-lock: VERDICT command-exit 0 · held the lock 82s). `pnpm --filter @objectstack/rest typecheck` -> TYPECHECK_EXIT=0 (tsc --noEmit). `pnpm lint` = `eslint . --no-inline-config` FULL REPO, no narrowing claimed -> VERDICT command-exit 0 · held the lock 87s. GATE FAMILY re-derived from the actual change set with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (stderr line confirms: derived from the tree of objectstack-ai/objectstack at commit 0b44a2093, --repo checked against this checkout's origin -- it holds); 4 paths, 19 path-matched families + 6 convention-triggered; re-derived AGAIN after the change set moved -> same 4 paths. Union re-run at 92ac437c0, all exit 0: check:nul-bytes ('check-nul-bytes: OK (scanned 6658 text file(s) ...; no raw ASCII control bytes)'), check:type-check-debt ('--re-measure: OK -- 32 ledger entr(ies) re-measured in 233.4s, 1898 raw tsc error(s) total, none above its recorded number'), check:type-check-coverage ('OK -- 65/78 workspace packages type-checked'), check:slot-lookup ('ratchet holds: 107 unswept site(s) in 25 file(s), none new'), check:query-options-erasure ('ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new'), check:where-matcher ('conformance holds: 297 matcher(s) discovered, 297 answer the combinator battery correctly or refuse it loudly (184 refuse)'), check:engine-double-contract ('OK -- 405 pinned, 133 in the DEBT ledger, 2 exempt'), check:cross-package-test-inputs ('OK: 16 package(s) read outside themselves, all declared'), check:test-source-alias ('OK -- 72 packages with tests scanned'), check:type-source-resolution ('OK -- 93 tsc program(s) across 77 packages scanned'), check:route-envelope, check:authz-resolver ('single shared authorization resolver intact'), check:dispatcher-error-vocabulary ('OK -- 21 unregistered code-stamping site(s), all classified'), check:published-files, check:plugin-teardown-shape, check:changeset-gate-self-tests, check:objectui-changeset, release-rehearsal-clone --self-test, check-adr-0087-registration ('1 declared-breaking changeset(s), each carrying an ADR-0087 disposition'), check-changeset-no-major ('introduces no `major` bump'), check-empty-changeset, check-ci-filter-parity, docs-audit/check-affected-docs + check-drift-comment ('56 cases pass across 5 fixture diff(s)'). ONE GATE WENT RED AND WAS FIXED, NOT RATCHETED AROUND: check:type-check-debt --re-measure reported '@objectstack/rest: TEST_DEBT records 155 raw tsc error(s), tsc --noEmit now reports 157 (+2)'. Both were TS2835 on the new pin file's extensionless './rest-server' / './rest-api-plugin' imports (packages/rest/tsconfig.json excludes **/*.test.ts, so the package's own typecheck never saw them). Remedy taken was the author's -- explicit .js extensions -- never raising the entry; back to 155. ABLATION. Fix committed FIRST (0b44a2093), then `git checkout 0b44a2093~1 -- packages/rest/src/rest-server.ts` inside a script carrying `trap '<restore>' EXIT INT TERM`; pins untouched. NO REBUILD LEG, and none is claimed: the pins import the mutated file RELATIVELY (`import { RestServer } from './rest-server.js'`), which vitest resolves to src/, never through dist/ -- the only exports-resolved dependency in play is @objectstack/spec, untouched by the mutation. MUTATION CONFIRMED ON DISK IN BOTH DIRECTIONS BEFORE THE RUN (an editing tool's exit code is not evidence): injected marker `assertDeclaredApiConfig` 4 -> 0 (absent), control marker `getApiBasePath(): string` known-present stays 1, pin files still show 4 x '#11637' and 1 x the replacement pin, `git status --short` shows ONLY 'M packages/rest/src/rest-server.ts'. After the run the trap restored it: marker back to 4, control 1, git status clean. PREDICTED vs MEASURED, written before running: SectionA 'server refuses' (6 cases: '', 'v1/beta', whitespace, bad projectResolution enum, message content, no doubled slash) predicted ALL RED -> measured 6 RED. SectionB CONTROL 'this ctx really boots a REST server' predicted GREEN (guard) -> GREEN; SectionB plugin-path rejection predicted RED -> RED. SectionC 6 regression guards (/api/v1 mount, allowed spellings v2/2024-01/v1.2/v1_beta, basePath:'', apiPath override, enableSearch:false survives normalization, requireAuth:false still constructs) predicted GREEN IN BOTH STATES -> 6 GREEN. rest-openapi-route.test.ts replacement pin predicted RED -> RED; its remaining 16 predicted GREEN -> GREEN. Totals: ablated 'Tests 8 failed | 23 passed (31)' = exactly the 8 predicted red; restored 'Tests 31 passed (31)'. SectionC and the SectionB CONTROL are REGRESSION GUARDS and are NOT counted as red-before evidence -- the CONTROL is load-bearing because createRestApiPlugin.start() returns quietly when http.server or protocol is missing, so without it a rejection could be attributed to a thin ctx rather than to the config. No pin asserts 'the schema refuses \"\"' (vacuous -- green before the change); every SectionA/B assertion drives real construction, SectionB through the real createRestApiPlugin(...).start(ctx) composition, i.e. both cast hops. DOCS-DRIFT CLASS checked specifically since this is a behaviour change: NO hand-written page makes an acceptance claim about api.version. content/docs/references/api/rest-server.mdx is AUTO-GENERATED from RestApiConfigSchema (untouched, so still accurate); content/docs/api/index.mdx:143 and content/docs/protocol/kernel/http-protocol.mdx:85-88 describe what discovery's `version` field MEANS since #11292, not what config is accepted; no createRestApiPlugin example under content/docs/** passes an api.version at all. docs-drift-check.yml's own two gates are green above. content/docs/releases/** untouched.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #11982: PluginConfigValidator can never run -- PluginLoader.loadPlugin calls its own validatePluginConfig(metadata) with no config and returns early ('config validation postponed'), a plugin factory closes over its config so the kernel never receives one, and no kernel Plugin in the repo declares configSchema; the mechanism has zero live consumers",
    "filed as #11983: api.enableSearch (and metadata.maskObjectFields) are live REST config keys no schema in packages/spec declares -- read through `as any`, and STRIPPED by any parse of their own config object, which is why this PR's parse had to discard its output",
    "filed as #11984: RestServer.normalizeConfig still casts crud/metadata/batch/routes instead of parsing them -- batch.maxBatchSize's int/min(1)/max(1000) bounds and three declared enums never execute"
  ]
}

---

Generated by Claude Code

[claude]

Round 2 — supersedes 5404833472: CI was red at 92ac437c0, fixed at 567e20a4e.

{
  "issue": 11637,
  "status": "done",
  "branch": "claude/issue-11637-rest-config-parse-not-cast",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11985",
  "premise_still_valid": true,
  "summary": "ROUND 2 — CI red at 92ac437c0 fixed at 567e20a4e; this supersedes my round-1 report on one point, and the correction is mine to own. THE CI FAILURE WAS REAL AND MINE: five packages/cli e2e boots (serve-no-artifact, serve-organizations-host-resolution, serve-organizations-mount-failure, serve-process-child-env, serve-stdio-stdout-purity) died at 'Plugin startup failed: com.objectstack.rest.api -- api.projectResolution: Invalid option: expected one of \"required\"|\"optional\"|\"auto\"'. ROOT CAUSE, measured: `projectResolution: 'none'` is not a stray literal -- packages/runtime/src/standalone-stack.ts:247 DECLARES the return type `api: { enableProjectScoping: false; projectResolution: 'none' }` and emits it at :760-763; packages/cli/src/commands/serve.ts:3086-3088 reads it (`apiConfig.projectResolution ?? 'auto'` does NOT fire -- 'none' is not nullish) and forwards it into BOTH plugins, :3139 (REST) and :3160 (Dispatcher); merge-boot-config.ts:12 documents it and merge-boot-config.test.ts:7 pins it `as const`. So three packages disagree about this key's vocabulary and have disagreed silently for exactly as long as nothing executed the schema -- the same family as #11983. FIX: `projectResolution` added to the `.omit()` beside `requireAuth`, typed against the shape so tsc fails if the key ever changes, with the reasoning written next to it. ⛔ Did NOT add 'none' to the enum (packages/spec is domain:spec's) and ⛔ did NOT change the CLI to stop using it (project-scoping semantics). Filed unlabelled as #11999, which names both sites, both consumers, and states the value was accepted only because the schema never ran; closing it is what lets the omit come out. CENSUS RADIUS -- the lesson, and I am recording it rather than explaining it away: my round-1 census was scoped to packages/rest/src because that is where the CHANGE lives; the risk surface is every package that CONSTRUCTS a REST server. I reported 'exactly ONE in-repo site'; measured against CI it was six. Re-run mechanically and repo-wide: `git grep -n -E 'new RestServer\\(|createRestApiPlugin\\(' origin/main -- . ':!**/dist/**' ':!**/*.md'` = 237 construction sites (225 packages/rest, 12 elsewhere, of which 5 are docstrings/docs, leaving 7 real: os serve, 3 client tests, plugin-dev, qa/http-conformance, verify); then a script that brace-matches every `api: { … }` block repo-wide and parses every scalar literal at each of the 14 declared keys against the schema this seam runs: 173 files scanned, 316 blocks matched, TOTAL REFUSED = 2, and both are the deliberate '' cases in this change's own pin file. Three gaps a literal census cannot see, closed by hand: nested documentation/responseFormat literals exist only in packages/spec's own schema tests (never construct a server); of the 237 sites exactly ONE feeds computed values (os serve), traced to the typed literal above; the 96 requireAuth fixtures are unaffected by the omit. A NEW DEFECT I INTRODUCED AND THE ABLATION CAUGHT: the refusal message appended the whole 'an empty version mounts the entire API at /api//' paragraph to EVERY failure, so a projectResolution refusal diagnosed a key the operator never wrote. Now scoped to `issues.some(i => i.path[0] === 'version')`, with a pin. CLAUSE 2 unchanged in kind (still a NARROWING) but the set moved: newly refused are `api.version: ''`, any version outside [a-zA-Z0-9_-.] ('v1/beta', 'v1 beta'), and wrong-typed declared keys; `api.projectResolution` MOVED from refused to deliberately-not-refused, and the changeset and PR body were both rewritten to match -- a changeset promising a narrowing I then omitted would be worse than one that never claimed it. packages/spec UNTOUCHED. needs:contract-review still hangs on PR #11985 and read back after the size-labeler's write; not cleared, still draft, no auto-merge.",
  "tests": "All at final commit 567e20a4e (`git rev-parse --short HEAD`), heavy steps through `bash scripts/pm/os-verify-lock.sh -c ...`; exit codes captured before any pipe; verdicts quoted from each gate's own printed line. THE CI-FAILING TESTS THEMSELVES, which is the verification round 1 lacked: `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/serve-no-artifact.e2e.test.ts test/serve-organizations-host-resolution.e2e.test.ts test/serve-organizations-mount-failure.e2e.test.ts test/serve-process-child-env.e2e.test.ts test/serve-stdio-stdout-purity.e2e.test.ts` -> 'Test Files 5 passed (5) · Tests 19 passed (19)', run against the REBUILT dist. `pnpm --filter @objectstack/rest test` -> 'Test Files 146 passed (146) · Tests 2356 passed (2356)' (2354 -> 2356: one pin removed, three added). `pnpm --filter @objectstack/rest typecheck` -> exit 0. `pnpm lint` = `eslint . --no-inline-config` FULL REPO -> VERDICT command-exit 0 · held the lock 86s. ROUND-2 ABLATION, AND MY FIRST ATTEMPT AT IT WAS INVALID -- recording that because the false green is the dangerous direction. I mutated packages/rest/src, did NOT rebuild, ran serve-no-artifact.e2e and got '1 passed (5 tests)', i.e. GREEN, and briefly had a result that would have certified the fix as unverified. The cause is exactly the documented hazard: the CLI e2e spawns a CHILD PROCESS that resolves @objectstack/rest through its exports -> `require.resolve` = packages/rest/dist/index.cjs, never src/. Redone with a rebuild on BOTH legs and scripts/ablation-dist-preflight.mjs proving the marker reached the artifact each time. MUTATION LEG: source two-key omit 1 -> 0, one-key omit 0 -> 1, control marker `assertDeclaredApiConfig` still 4, `git status --short` shows only the expected files; rebuild exit 0; preflight --absent -> 'marker absent from all 6 built files -- the artifact the suite consumes no longer carries it'; the 5 e2e files -> 8 tests RED reproducing CI's exact text ('api.projectResolution: Invalid option: expected one of \"required\"|\"optional\"|\"auto\"', 'Plugin com.objectstack.rest.api failed to start - rollback complete'), with the stack naming _RestServer.assertDeclaredApiConfig in dist/index.js. RESTORE LEG (trap EXIT INT TERM, which also rebuilds): preflight -> 'marker present in 2 built files (plus 2 sourcemap hits, not counted)'; e2e back to 5 files / 19 tests green; git status clean. PREDICTED vs MEASURED round 2: predicted the 5 e2e boots RED with the omit ablated -> measured 8 tests RED across those 5 files; predicted GREEN restored -> 19 green. Round-1 ablation (packages/rest pins, unchanged and still valid, no rebuild leg needed because those pins import './rest-server.js' RELATIVELY and vitest resolves that to src/): ablated 'Tests 8 failed | 23 passed (31)' exactly as predicted, restored 31/31. GATE FAMILY re-derived after the change (`node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack`) -> same 4 paths, same 19 path-matched + 6 convention-triggered families. Union re-run at 567e20a4e, all exit 0: check:nul-bytes ('OK (scanned 6658 text file(s) ...; no raw ASCII control bytes)'), check:type-check-debt ('--re-measure: OK -- 32 ledger entr(ies) re-measured in 286.5s, 1898 raw tsc error(s) total, none above its recorded number' -- held the line, nothing loosened), check:type-check-coverage, check:slot-lookup ('ratchet holds: 107 unswept site(s) in 25 file(s), none new'), check:query-options-erasure ('ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new'), check:where-matcher ('297 matcher(s) discovered, 297 answer the combinator battery correctly or refuse it loudly'), check:engine-double-contract ('OK -- 405 pinned, 133 in the DEBT ledger, 2 exempt'), check:cross-package-test-inputs, check:test-source-alias, check:type-source-resolution, check:route-envelope, check:authz-resolver, check:dispatcher-error-vocabulary, check:published-files, check:plugin-teardown-shape, check:changeset-gate-self-tests, check:objectui-changeset, release-rehearsal-clone --self-test, check-adr-0087-registration ('1 declared-breaking changeset(s), each carrying an ADR-0087 disposition'), check-changeset-no-major, check-empty-changeset, check-ci-filter-parity, docs-audit/check-affected-docs, docs-audit/check-drift-comment ('56 cases pass across 5 fixture diff(s)'). PR CARRIER: body updated and read back -- the session-URL footer survived; the platform APPENDED a second bare-form footer on the edit (that appended one is the form documented to be stripped on the next edit). Labels read back AFTER the size-labeler's write: ['documentation','size/m','tests','tooling','needs:contract-review'] -- my additive write survived, and I did not touch the bot's labels. Draft: true. All four filed findings verified labels=[] assignees=[].",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #11999: projectResolution: 'none' is shipped by @objectstack/runtime (StandaloneStackResult.api declares the literal type) and forwarded by os serve into both the REST and Dispatcher plugins, but RestApiConfigSchema declares only required|optional|auto -- accepted only because the schema was never executed; this is what CI caught, and closing it is what lets #11985's .omit() come out",
    "filed as #11982: PluginConfigValidator can never run -- PluginLoader.loadPlugin calls its own validatePluginConfig(metadata) with no config and returns early ('config validation postponed'), a plugin factory closes over its config so the kernel never receives one, and no kernel Plugin in the repo declares configSchema",
    "filed as #11983: api.enableSearch (and metadata.maskObjectFields) are live REST config keys no schema in packages/spec declares -- read through `as any`, and STRIPPED by any parse of their own config object",
    "filed as #11984: RestServer.normalizeConfig still casts crud/metadata/batch/routes instead of parsing them -- batch.maxBatchSize's int/min(1)/max(1000) bounds and three declared enums never execute"
  ]
}

---

Generated by Claude Code

[os-zhuang]

Contract review: PASS — PR #11985 at head 567e20a4e (round 2). Reviewed the actual diff (fetched branch, rest-server.ts + pins + changeset read in full), not the report:

• Tier is correct: minor for @objectstack/rest, changeset headlined as an accept-set tightening — the established minor class for behavior-narrowing on a published interface. The ADR-0087 not-required (no-migration-prescription) disposition is properly argued: no authorable key moves; a config the spec always rejected now fails loudly, and which path segment the author meant is intent no transform can decide. check-changeset-no-major green.
• The narrowing is exactly the declared contract, and provably no more. The parse is RestApiConfigSchema.omit({requireAuth, projectResolution}).safeParse — and each omit is the right kind of refusal-to-overreach: requireAuth keeps 把 public 从"全局开关的副产品"升级为声明式能力,然后删掉 api.requireAuth 开关 #3963's ruled warn-and-ignore posture with a typed omit that fails tsc the day the tombstone ages out; projectResolution is a real three-package vocabulary disagreement (@objectstack/runtime ships 'none' as a declared literal type; enforcing the enum would crash every os serve boot) that belongs to domain:spec and is filed as projectResolution: 'none' is shipped by @objectstack/runtime and forwarded by os serve, but RestApiConfigSchema declares only required|optional|auto — accepted only because the schema was never executed #11999 with the omit's exit condition named. Validation-only with output discarded is measured, not stylistic: the non-strict schema strips live undeclared keys (enableSearch), so consuming the parse would silently flip a deployment's settings — the ADR-0104 silent-strip class, filed as api.enableSearch and metadata.maskObjectFields are live REST config keys that no schema in packages/spec declares — read through as any, and stripped by any parse of their own config object #11983.
• Triage's two explicit demands are both met: the changeset names every newly-refused shape ('', off-pattern versions, wrong-typed declared keys) AND every deliberately-not-refused one; the in-repo reliance census was run — and when CI proved round 1's census radius wrong (scoped to the package the change lives in, not to everyone who constructs a REST server), the correction was owned, redone mechanically repo-wide (237 construction sites, 316 api: blocks, exactly 2 refusals = this change's own pin file), and the lesson recorded rather than explained away.
• Evidence quality is the strongest part: predicted-vs-measured ablation with on-disk mutation proof in both directions; the round-2 leg caught its own first false-green (dist-resolving child processes) and was redone with rebuilt artifacts and a preflight marker check on both legs; the CI failure was reproduced, root-caused to the shipped 'none', and the refusal-message over-reach the ablation exposed (version rationale appended to non-version failures) was fixed and pinned. check:type-check-debt's +2 was fixed at the author's remedy, never ratcheted.
• Lane boundary held: packages/spec untouched; the four adjacent defects (PluginConfigValidator can never run: PluginLoader calls its own validatePluginConfig(metadata) with no config, and a plugin factory closes over its config so the kernel never receives it #11982 dead validator mechanism, api.enableSearch and metadata.maskObjectFields are live REST config keys that no schema in packages/spec declares — read through as any, and stripped by any parse of their own config object #11983 undeclared live keys, RestServer.normalizeConfig still casts crud / metadata / batch / routes instead of parsing them — batch.maxBatchSize bounds and three declared enums never execute #11984 still-cast sub-objects, projectResolution: 'none' is shipped by @objectstack/runtime and forwarded by os serve, but RestApiConfigSchema declares only required|optional|auto — accepted only because the schema was never executed #11999 vocabulary split) filed unlabelled instead of smuggled — one narrowing in front of this review, not five.

Tier reading this round: get_session.external_metadata.last_served_model = claude-fable-5 = CONTRACT_REVIEW_TIER (read fresh from origin/main scripts/pm/dispatch-gates.mjs:3070). Standing authorization: maintainer 2026-08-23 「要不还是你挂个定时处理审核吧」. Clearing needs:contract-review from both carriers in this stroke; enqueue and arming remain the dispatching domain:cli seat's per its claim.

---

Generated by Claude Code