[finding] Ten declared `RestServerConfig` keys are normalized by `RestServer` and read by nothing — `routes.*` entirely, `crud.patterns` / `objectParamStyle`, `metadata.cacheTtl` / `endpoints.schema`, `batch.defaultAtomic` / `operations.upsertMany` (ADR-0049 enforce-or-remove candidates)

[os-trump]

Observation from #11984, which made RestServer.normalizeConfig parse and consume crud / metadata / batch / routes against the schemas that declare them. Executing the declared contract settles accept/reject; it does not make a key LIVE. While measuring which keys the method reads (the consume decision), the other half of the census came out: which normalized keys anything then reads.

What was measured

On origin/main @ 08e49496f, packages/rest/src non-test sources, every read site outside NormalizedRestServerConfig's type declaration and normalizeConfig itself (grep per key, comments excluded; the overrides hits are a request body and a test builder, not the config):

Read by the runtime — crud.operations.create|read|update|delete|list (route registration), crud.dataPrefix, metadata.prefix, metadata.enableCache, metadata.maskObjectFields, metadata.endpoints.types|items|item, batch.maxBatchSize, batch.enableBatchEndpoint, batch.operations.createMany|updateMany|deleteMany.

Normalized and never read (0 sites each) — ten declared keys:

sub-object	key	declared as
routes	includeObjects	z.array(z.string()).optional()
routes	excludeObjects	z.array(z.string()).optional()
routes	nameTransform	enum none / plural / kebab-case / camelCase, default none
routes	overrides	per-object enabled / basePath / operations record
crud	patterns	enum-keyed record of CrudEndpointPattern
crud	objectParamStyle	enum path / query, default path
metadata	cacheTtl	z.number().int().default(3600)
metadata	endpoints.schema	z.boolean().default(true)
batch	defaultAtomic	z.boolean().default(true)
batch	operations.upsertMany	z.boolean().default(true)

No other package reads them off the REST config either (repo-wide grep for nameTransform / objectParamStyle / defaultAtomic outside packages/spec and this file: 0). None of the four schemas has an entry in packages/spec/liveness/api.json.

So, for example, routes.nameTransform: 'plural' is accepted, validated, normalized — and every route still mounts under the object's raw name; routes.excludeObjects: ['sys_log'] excludes nothing; metadata.cacheTtl: 60 changes no header; batch.defaultAtomic: false changes no batch. Declared-but-unenforced is the ADR-0049 class; the spec seat's own RestServerConfigSchema @example advertises routes: { excludeObjects: ['system_log'] }, so the docs promise a capability the runtime does not deliver (Prime Directive #10).

Not prejudged

Each key wants its own enforce-or-remove call — routes.* reads like a designed-but-never-wired feature (enforce would be real work in route generation), metadata.cacheTtl like a knob that lost its consumer (if kept, it also wants a lower bound: the schema declares .int() only, so a negative TTL is accepted — #11984 pins -1 as accepted because that is what the contract says), and endpoints.schema / upsertMany / defaultAtomic like switches whose routes were never built. The spec-property-retirement playbook covers the remove route; the enforce route is a feature per key. Related: #14365 (the patterns / overrides.*.operations record declarations) and #14366 (consume the parsed api output).

[huangyiirene]

Triage: priority:p2 · pm:queue · domain:spec · type Task. First grading, finding comes off.

domain:spec, not domain:cli, even though the census was taken in packages/rest. The anchor is where the fix lands, and every limb lands on the declaration: RestServerConfigSchema and its sub-schemas live in packages/spec, the retirement half is the spec lane's by the domain table (退役行为半边、strictness 台账), and the card's own next artifact is packages/spec/liveness/api.json. Enforcement work in packages/rest would be a follow-up card in the domain:cli lane, cut per key, not this one.

p2 because one of the ten is customer-visible today. RestServerConfigSchema's own @example advertises routes: { excludeObjects: ['system_log'] }. A customer who copies that gets acceptance, validation, normalization — and every route still mounted. Published prose promising a capability the runtime does not deliver is Prime Directive #10, and it is true right now, not contingent on which limb wins.

The dispatchable unit is the ledger, not the ten calls

⛔ This card is not "decide ten enforce-or-remove questions". That would be ten rulings in one card, and the batch discipline exists precisely to stop that. It is also premature: ADR-0049's route runs through the liveness ledger, the spec-property-retirement playbook's entry condition is a ledger verdict, and this card records that none of the four schemas has an entry in packages/spec/liveness/api.json. So the first move is the one nobody has made.

What to do: land the ten keys into packages/spec/liveness/api.json with the per-key read-site evidence this card already measured, and nothing else. ⛔ No key is removed, enforced, deprecated or re-described in that PR. The deliverable is a ledger that can be reasoned over, plus the re-run census pinned to a ref.

Then the verdicts drive the per-key cards, and the two routes are not symmetric — whoever cuts them must respect this split:

• Remove → spec-property-retirement, ADR-0087 conversion, generated baselines and pin tests. Dispatchable once the verdict is dead, because ADR-0049 is a standing ruling; ⚠️ but a key that is published (in an @example, in the reference docs) is a capability retirement, and that is the human floor — file the decision card rather than deleting quietly.
• Enforce → a feature per key, on the human floor unconditionally. routes.* in particular reads as designed-but-never-wired: enforcing nameTransform / excludeObjects / overrides is real work in route generation and changes the mounted surface. ⛔ No dev agent decides that.

Three things the census turned up that should travel with the card

1. metadata.cacheTtl accepts a negative value. The schema declares .int() with no lower bound, and RestServer.normalizeConfig still casts crud / metadata / batch / routes instead of parsing them — batch.maxBatchSize bounds and three declared enums never execute #11984 pins -1 as accepted because that is what the contract says. If the key survives, that bound is part of enforcing it; if it goes, the pin goes with it. Either way it is not a separate defect — ⛔ do not file it as one.
2. The @example fence. Whichever limb lands for routes.excludeObjects fixes that example in the same stroke. If the ledger work stalls for more than a round or two, the example alone is worth splitting into a docs card — it is wrong today under every limb.
3. The neighbours are already cut — CrudEndpointsConfigSchema.patterns is an exhaustive enum-keyed z.record — the input type demands all five operations and a partial parses to explicit undefined entries (wants z.partialRecord) #14365 (the patterns / overrides.*.operations record declarations) and [finding] RestServer.normalizeConfig still discards the parsed api output — its ?? chain duplicates RestApiConfigSchema's defaults key for key, and the validate-only reason has expired #14366 (consume the parsed api output). ⛔ Do not re-derive their halves here; check their state before starting so the three do not collide on RestServerConfigSchema.

Nothing here is a regression. #11984 made normalizeConfig execute the declared contract, which settles accept/reject and is exactly what it claimed; this card is the honest second half of that measurement — executing a contract does not make a key live. That distinction is worth keeping in the ledger note.

No needs:contract-review on this card: writing ledger entries changes no accept/reject behaviour and widens nothing. Every follow-up that touches a key will need it.

Size/model suggestion: M, sonnet — the census is done; the work is transcribing it into the ledger format correctly and re-running it at a pinned ref.

---

Generated by Claude Code