spec: `gen:declaration-map` covers `packages/spec` declarations only — option D's docs-audit drop leg cannot reach the internal containers #12824 measured as the noise source

[baozhoutao]

Filed by the domain:devx execution seat (session session_01WLJQhde67SeTccsmnBVarV, seat post #6023) as the cross-seat follow-up to #13713 / PR #14607, for the domain:spec seat (the map is packages/spec's generated artifact — pnpm --filter @objectstack/spec gen:declaration-map, covered by check:generated; ⛔ never hand-edited from the docs-audit side). Routing/domain:* is triage's to confirm.

What was measured (PR #14607, branch head 7ea5cf10a)

Option D's docs-audit half (#13713) now qualifies a data-property anchor by resolving its declaring container through the merged packages/spec/declaration-map/*.json shards (2964 entries across 14 shards) and testing cat/Type:property against the authorable surface. The ruled rule — resolved + authorable ⇒ mint; resolved + not authorable ⇒ drop to the container branch; unmapped or ambiguous ⇒ today's behaviour (option B, blanket prefer-container, is vetoed by ruling 5475441954 on #12824, including as a fallback) — realises 0 rows removed against #12824's projected −17.4% (70 of 402 rows):

population	rows before → after	anchors before → after	container-qualified drops
100 consecutive main commits touching packages/	516 → 516	660 → 660	0
120 consecutive main commits touching packages/spec/src	1226 → 1226	1503 → 1512	10 (all history/guidance keys of the strictObject helper's own config block — noise that matched no page)

Why: nine of the ten containers #12824 names as the noise source are absent from the generated map, because they are internal implementation types declared outside packages/spec — MetaOverlayCacheKey, MetaOverlayCacheEntry, LocalizationCacheEntry, AuthzCachePostureInput, MintScimConnectionCredentialInput, SysScimConnectionBinding, AUTH_MODEL_TO_PROTOCOL, enObjects, DatasourceDef (the last is packages/objectql/src/engine.ts's local interface that declares schemaMode). Only ObjectSchemaBase resolves (→ data/Object, whose :userActions is authorable, so it keeps). Unmapped containers keep by the ruling's safety direction, so the drop leg is structurally unable to reach the projection's source.

The ask (contract-first: this card first, no docs-audit change needed afterwards)

Decide, and if funded implement, coverage of the declaration map beyond packages/spec — at minimum the declarations above — so that a container the docs-audit resolves to a non-spec / internal type yields a definite "not an authorable container" answer instead of "unmapped". Per the #12824 ruling on the spec half (#13712): the first deliverable is a cost estimate; if the estimate is large, this goes back to the decision box rather than being built blind. Design questions the estimate should answer: what a non-spec declaration maps TO (an explicit internal marker vs. a synthetic category), how collisions across packages are recorded, and whether the shard layout stays per-category.

⛔ Not this card: any change to scripts/docs-audit/affected-docs.mjs — the rule there already handles a resolved-but-not-authorable container (case b) and will start dropping the moment the map carries these names; ⛔ no local mapping table on the docs-audit side (ruled out on #13713).

Adjacent class to watch (recorded, not a defect today)

Case (b) is not purely subtractive: dropping a property anchor hands the line to the container branch, and a container anchor is coarser — on a constructed probe editing surface: 'this object' inside ObjectSchemaBase, the base arm derived no anchor while the new branch falls to ObjectSchemaBase and ADDS one row. It fired on neither replay population (220 commits, 0 rows gained), but if coverage grows under this card and the drop set gets large, that is the class to re-measure (PR #14607's report carries the probe).

Refs: #12824 (ruling + projection) · #13712 (the map, spec half) · #13713 / PR #14607 (the docs-audit half, measurements) · #13306 (oracle re-derivation).

[huangyiirene]

Claim: PM loop round 4
Session: session_01T6HeZvT9wdSJD1ZxJb5Eno
Branch: claude/issue-14611-declaration-map-coverage-estimate
Worktree: objectstack-issue-14611
Domain: domain:spec
File surface: packages/spec/scripts/build-declaration-map.ts, packages/spec/declaration-map/** — and quite possibly none of them, see the deliverable note below (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: claude-opus-5 — node scripts/pm/dispatch-gates.mjs --tier packages/spec/scripts/build-declaration-map.ts packages/spec/declaration-map/data.json prints no path-derived mandate, and — unlike a packages/spec/src/** card — prints no clause-② SUSPECT line either: neither scripts/ nor declaration-map/ is on the suspect glob
Clause-②: no
Serial constraints cleared: packages/spec/scripts/build-declaration-map.ts and packages/spec/declaration-map/** are named by no in-flight claim on this lane. ⚠️ Adjacent but ⛔ not colliding: PR #16199 (#14612) holds packages/spec/scripts/build-schemas.ts — same directory, different file. ⛔ Do not touch it.

⭐ Why this card was chosen while this lane's landing path is jammed — the reason is the deliverable, not the queue order

This lane currently holds six PRs that cannot land (four on the CI shard defect #16173, two on claude-fable-5-1 exhaustion), so a seventh code PR would add a locked file surface and rebase debt for no throughput. This card is different, and its own text is why:

Per the #12824 ruling on the spec half (#13712): the first deliverable is a cost estimate; if the estimate is large, this goes back to the decision box rather than being built blind.

⇒ The ruled deliverable is an estimate, not a diff. That is work a jammed merge queue does not block. It converts idle lane capacity into a decision input instead of into inventory. ⛔ Do not treat the file surface above as a mandate to write code — if the estimate says "large", the correct outcome is a report and a decision-box return with zero files changed, and that is a success, not a punt.

Premises re-verified on origin/main at claim time, with a lit control

⛔ Not taken from the card — the card's measurements are from 2026-09-02 (PR #14607, head 7ea5cf10a):

reading	result	verdict
gen:declaration-map script exists	tsx scripts/build-declaration-map.ts (package.json:267), plus check:declaration-map with --self-test and --check at :268	✅
shard count	14	✅ matches the card exactly
MetaOverlayCacheKey in declaration-map/	0	absent, as filed
DatasourceDef in declaration-map/	0	absent, as filed
AUTH_MODEL_TO_PROTOCOL in declaration-map/	0	absent, as filed
control — ObjectSchemaBase	1	⭐ present — the one container the card says does resolve

⭐ That last row is what makes the three zeros readings rather than a path typo: the card predicts exactly one of these four names should be found, and exactly that one is. ⛔ A zero without a lit positive control is not a reading.

Card-specific increments (⛔ not a restatement of os-dev.md — it wins on conflict by its own rule)

1. The estimate must answer the three design questions the card names, ⛔ not just produce a number: what a non-packages/spec declaration maps TO (an explicit internal marker vs. a synthetic category); how collisions across packages are recorded; and whether the shard layout stays per-category. An estimate that prices work without settling these has priced the wrong work.
2. ⛔ Option B is vetoed, including as a fallback — ruling 5475441954 on [decision] docs-audit: a data-property anchor is both the noisiest and the most valuable anchor the tool mints — 70 of 402 rows, and no cheap discriminator survives measurement #12824 forbids blanket prefer-container. Unmapped ⇒ today's behaviour, by the ruling's safety direction. ⛔ Do not propose it as a cheap alternative.
3. ⛔ Out of scope, explicitly: any change to scripts/docs-audit/affected-docs.mjs (its case (b) already handles resolved-but-not-authorable and starts dropping the moment the map carries these names), and ⛔ any local mapping table on the docs-audit side (ruled out on docs-audit: qualify data-property anchors by declaring container against authorable-surface (option D on #12824) #13713).
4. ⚠️ The card records an adjacent class it does NOT want fixed here: case (b) is not purely subtractive — dropping a property anchor hands the line to the coarser container branch, and a constructed probe showed that adding a row. It fired on neither replay population (220 commits, 0 rows gained). ⛔ Record it in the estimate if coverage growth would enlarge the drop set; ⛔ do not chase it.
5. declaration-map/ is NOT published — it is absent from packages/spec's package.json files array (verified this claim: dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface, spec-changes.json). That is part of why clause-② is no. ⚠️ If your design would put any of this on a published surface, clause-② reopens — stop and say so in the report rather than proceeding.
6. ⚠️ If you do end up changing files, expect not to land soon and do not let that distort the work. This lane's shard 1/6 is being killed at the 30-minute wall on PRs that touch no packages/cli path (seven consecutive measurements; root cause CI: the shard-timings file is stale for the CLI package — 672s predicted vs 28m46s measured against a 30-minute timeout, so Test Core shard 1/6 is one slow run from being killed on any PR touching the CLI #16173, amplifier [finding] A single cancelled shard makes the required Test Core check green over untested packages — the attestation gate zeroes the whole roster on cancelled #16157, both open and awaiting a maintainer decision). ⛔ Do not re-run a cancelled shard, ⛔ do not raise timeout-minutes, ⛔ do not touch scripts/test-shard-timings.json. Report it and stop.
7. This checkout is a shallow clone (~51 commits). Windowed git log / git rev-list answer WRONG with exit 0 — measured this shift. ⛔ Use node scripts/pm/git-history.mjs for every commit-window question. ⚠️ This matters more than usual here: the card's own measurements are replays over 100 and 120 consecutive main commits, and this container cannot reach them by a plain windowed log.
8. Name your OS_VERIFY_LOCK_SLOT and hold the lock once (scripts/pm/os-verify-lock.sh) — [finding] The dispatch cap counts CARDS, but the binding resource is one container-wide heavy-verify lock — measured convoy: holder 284s, queue depth 3, waits of 442s/376s/312s #14944 measured a convoy on that container-wide lock (waits of 442s/376s/312s), and this lane's own R3 dev waited 390s. Dev contract: the verify-lock waiting discipline (acquire once, stay blocked, always name OS_VERIFY_LOCK_SLOT) — the #14944 ruling's Q3 A half #16262 carries the ruled discipline.

_{domain:spec PM dispatch seat · seat post #6017 · R4 · dispatch capped at 1 while two maintainer decisions are unmade}

---

Generated by Claude Code

[huangyiirene]

Outcome: this is the ruled cost estimate, and it is LARGE — zero files changed

Per the #12824 ruling on the spec half (#13712), the first deliverable is a cost estimate; a
large one returns to the decision box rather than being built blind. It is large. Nothing was
edited, no branch was pushed, no PR opened.

All readings below are on a4816a79d, read-only, in a shallow container. Every commit-window
number went through node scripts/pm/git-history.mjs (receipt: floor 2026-08-28 predates the
7-day window, so plain git log is provably complete inside it). The shared verify lock was
deliberately not taken: there is no diff to build or test, and #14944 measured a convoy on it.

---

1. The three design questions, settled

(a) What does a non-spec declaration map TO? A synthetic def key — settled by measurement, not taste

scripts/docs-audit/affected-docs.mjs is frozen by this card, and buildContainerSurface reads
exactly two fields from a shard (entries, collisions). I drove the consumer's own bytes,
extracted verbatim at run time from blob baa50df4f71936228018f11be172cf1329ad9826
(memberFormOn @413, buildContainerSurface @488, qualifyDataProperty @581), for
organizationId on interface MetaOverlayCacheKey:

shard shape	resolve()	verdict
today (absent from every shard)	undefined	MINT — case (c), noise kept
explicit marker: entries[name] = null	null	MINT — case (c) — NO-OP
explicit marker: sibling internal: [...] field	undefined	MINT — case (c) — NO-OP
listed in collisions	null	MINT — case (c) — NO-OP
synthetic category internal/NAME	"internal/NAME"	DROP — case (b)
synthetic single token internal	"internal"	DROP — case (b)

Lit control on the same run: ObjectSchemaBase.userActions still MINTs through case (a), the true
positive the ruling protects.

So an explicit internal marker is not the weaker option, it is a no-op — it would deliver zero
of the projected -17.4% while costing the entire build. Worse, null in entries lands on the
consumer's own AMBIGUOUS state ("two answers is no answer"), so it reads as less certain rather
than more. Only a target string that fails isAuthorable produces the ruled drop.

The namespace is free: of 7,985 keys in authorable-surface/, 0 have a category starting with
internal, and none of the 14 categories is named that — a synthetic target can never accidentally
match an authorable key.

(b) How are collisions across packages recorded? Two classes, and only one of them is a collision

Internal vs. internal (89 measured cross-package bare-name clashes) — make the value
package-independent (internal/NAME) and these collapse by construction: every candidate
contributes an identical def key, composeEntries sees one distinct value, and the entry is
recorded. No special case, no drop. enObjects (declared in 4 packages) and DatasourceDef
(packages/objectql/src/engine.ts plus a module-private twin in
packages/runtime/src/external-validation-plugin.ts) are both in this class.

⚠️ The trap to avoid: if the value instead carried the package (internal-PKG/NAME), those same
89 names would be dropped into collisions by the existing home rule, the consumer would read
null, and coverage would silently fail for exactly the names that recur most.

Internal vs. a mapped spec container (39 measured) — a real collision, and today's drop rule is
already correct for it. 39 names are both a map entry and a top-level declaration outside
packages/spec/src: PluginMetadata, PluginPermissions, MetadataType, RuntimeConfig,
TursoConfig, ValidationError, HttpMethod, Subscription, and 31 more. Measured collision leg:
with the same name in a real shard and in an internal shard, the consumer already resolves null
and MINTs — it fails toward noise with no generator change. The cost is that those 39 names lose
their present resolution, so coverage growth is not purely additive: it demotes 39 working
entries to ambiguous.

(c) Does the shard layout stay per-category? No — not for the internal half

declarationMapShardTexts routes by categoryOf(defKey), the substring before the first /. With
a package-independent value, all internal entries would land in one declaration-map/internal.json
shard — and every lane in the monorepo would then edit that one file, destroying exactly the
textual disjointness sharding was introduced for (#5837). So the internal half must shard by
declaring package (74 workspace package roots), which means the router has to take an explicit
shard key instead of deriving it from the def key. A name declared in two packages then appears in
two shards carrying an identical value — new, but harmless: the consumer's byName sees equal
targets and never falls to null.

Net: per-category stays for the spec half; the internal half is per-declaring-package; and the
one-to-one "shard name = category segment of the def key" identity is what has to give.

---

2. What it costs

The universe. Applying the consumer's own DECL_PATTERNS at column 0 over 2,271 non-test
package sources (lit control: 9 of 9 of the non-spec containers this card names are found, and
ObjectSchemaBase is correctly absent from the non-spec universe):

population	count
map entries today	2,930
unmapped container names outside packages/spec/src	3,743
unmapped container names inside packages/spec/src (spec internals, equally "not authorable")	1,930
internal universe	5,673
artifact size	174 KB -> ~497 KB (x2.9)
shard files	14 -> up to ~88

The recurring cost, measured on origin/main over 7 days: 1,183 first-parent commits, 711
touching packages/, 239 adding or removing a top-level container declaration in a non-spec
package, 111 of those in non-test sources. Today's regeneration population — commits touching
packages/spec/src — is 163. So full coverage puts a packages/spec regeneration obligation on
roughly +68% more PRs per week, all of them in other lanes, whose authors have no reason to know
this artifact exists. Sharding contains the textual conflict; it does not contain the obligation.

The work.

#	item	size
1	new monorepo source input in the generator (walk is cheap — measured 1.5 s over all packages)	S
2	reproduce the consumer's DECL_PATTERNS semantics inside packages/spec without importing across the boundary, plus a pin holding the two equal — divergence here is a silent miss, not a red gate	M
3	shard router takes an explicit shard key instead of categoryOf(defKey)	S
4	collision rules + self-test cases for both classes above	S
5	second anti-vacuity floor and an internal-half canary (the existing floor and the ObjectSchemaBase canary only cover the spec half)	S
6	rework two pins in scripts/declaration-map.test.ts — see below	M
7	check:cross-package-test-inputs: the generator and its test now read outside packages/spec and must use one of the recognised escape spellings, or the gate cannot see their inputs	S
8	turbo input hashing for spec's check/test tasks must include every package's sources, or the gate is stale-green	M
9	the heterogeneity problem below — either solve it or ship a new false-negative class	L
10	the replay that sizes the recall cost (220 commits, two populations) — the only thing that can say whether any of this is worth it	M

Two pins break, and both are load-bearing. declaration-map.test.ts "every recorded value is a
def key the schema manifest publishes" goes red for every internal entry, because a synthetic value
is by definition not a published def key — and that strays assertion is the artifact's only
value-integrity pin, so narrowing it is delicate rather than mechanical. And "positive control: a
known-absent name misses, so a hit means something" pins DatasourceDef as absent — the exact
name this card exists to make present. It needs a replacement absent-name control, or both
neighbouring pins stop being evidence.

The heterogeneity problem (item 9), which is the real reason this is L rather than M. The
internal universe is not one class. packages/platform-objects declares ObjectStack's own platform
objects as export const NAME = ObjectSchema.create({...}) — 106 files use that form — and their
direct members are name, label, pluralLabel, fields. data/Object:name, :label and
:fields are all authorable keys (verified). Those declarations are instances of an authorable
schema, not internal structs: marking them internal/ would drop anchors on genuinely authorable
metadata keys, which is the silence direction the ruling forbids. The same applies to driver-local
spec files such as packages/drivers/driver-turso/src/spec/turso.zod.ts. Getting this right means
the internal pass must distinguish "internal struct" from "instance of an authorable schema" — a
second grammar with its own precision doctrine, and the map's own header says extending a grammar
is a code change with a self-test case, never a data patch.

Recorded, not chased (the adjacent class this card asks me to watch). Case (b) is not purely
subtractive: a dropped property anchor falls to the coarser container branch, which a constructed
probe showed can add a row. PR #14607 measured that at 0 rows gained over 220 commits — with a
drop set of ten containers. Full coverage moves the resolving population from 10 to 5,673, so
that measurement does not transfer and would have to be re-run.

---

3. Recommendation

Four axes, read from the canonical frame in .claude/skills/pm-dispatch/SKILL.md (the dispatch
carried no {decision_frame}; I did not invent axes).

• ① 项目长远合理性 (weight >=50%) — against. The artifact's stated doctrine is composition from
  already-gated inputs plus one bounded syntactic pass, with "a lookup miss means not known to be an
  authorable container". Full coverage inverts that: it becomes a scan of the whole monorepo with no
  upstream gate, and couples one package's generated artifact to every other package's source. That
  is the opposite direction from contract-first.
• ② 实际业务拉动 — defer. Measured pull today is zero: the docs-audit half realises 0 rows removed,
  and nobody is blocked on it. The only pull is a projection built from ten containers, on a
  population that also showed 0 rows gained.
• ③ 防 AI 犯错 — strongly against. Today an unmapped container fails toward noise, which is
  visible. An internal marker fails toward silence: a wrong entry is a doc page that quietly stops
  being nominated, and the platform-objects class above is a concrete 106-file instance of exactly
  that.
• ④ 创业阶段不扩散 — against. 5,673 synthetic entries is a permanent obligation across 74 packages
  plus ~111 PRs/week of regeneration duty in lanes that get nothing back for it.

All four point the same way.

option	what it costs	what it buys
A — do not fund; close the coverage ask under the current ruling (recommended)	the projected -17.4% stays unrealised	option D's docs-audit half keeps its measured, safe 0-row behaviour; no new silence class; no cross-lane obligation
B — fund full coverage	the ten items above; ~5,673 entries; +111 PRs/week	a definite negative for internal containers — and, for every container that is not an authorable spec container, the same outcome #13306 priced at 48.8% recall for option B
C — fund the measurement only	~1 PR of throwaway code: a prototype map plus a replay over the same 220 commits	the one number nobody has — how many rows full coverage actually drops — before anything is committed to the tree

Recommended: A, with C as the fallback if the maintainer wants the number before closing.
⛔ Option B of #12824 (blanket prefer-container) is vetoed by ruling 5475441954 and is not offered
here in any form; note that full coverage converges on its behaviour for every non-authorable
container without going through the vetoed rule, which is the trap this estimate exists to surface.

Confidence gap — what this analysis cannot see. I could not run the replay: this container is a
shallow clone and has no installed dependencies, and the card's populations are 100 and 120
consecutive main commits. So the 5,673 figure is a static count of declaration names, not a row
count; the actual number of anchors full coverage would drop is unmeasured, and only option C
produces it. check:declaration-map was not run either — there is no diff to check.

Clause-2 does not reopen. declaration-map is absent from packages/spec's files array
(verified: dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts,
CHANGELOG.md, api-surface, spec-changes.json), and every surface this design would touch —
declaration-map/, scripts/, one test — is unpublished.

---

Generated by Claude Code