feat(spec)!: publish the dependentRequired rule, and make the projection's two halves one call

[os-elon-musk]

Part of #18670 — item 2, the third of the ruling's four named arms. #18670 remains open: banned keys is still untaken, and this body deliberately carries no closing keyword for that number.

Clause-②: yes (narrowing)

Director ruling batch #154 item 3, letter C (comment 5725370614, maintainer 「同意」): 「the projection emits a refinement only where the rule is a complete, mechanically derivable JSON Schema pattern — banned keys, required-one-of, non-blank — one ledger row at a time; everything else stays annotated as x-dropped-refinements」.

Continues PR #18952 (squash 5e5ec9fa42194723cc523a274e7221c8447c4487), which landed required-one-of and non-blank-string.

1. The arm: dependentRequired

data/SSLConfig's refinement is hasCert === hasKey — precisely dependentRequired { cert: ['key'], key: ['cert'] }. It is emitted through the same closed-vocabulary mechanism the previous arm built: src/shared/refinement-projection.ts declares, scripts/lib/refinement-projection.ts emits. No second mechanism was introduced.

Exact, not approximate. A key absent from a JSON object is the only way for its value to read undefined, and dependentRequired triggers on PRESENCE — so a key present with any JSON value, null included, arms its dependency exactly as the predicate's !== undefined does. The dependency map is read once into the declaration and the predicate reads it from there, so the published keyword and the enforced rule cannot name different keys.

Ledger: the rows retired, by name

packages/spec/dropped-refinements.baseline.json, 201 entries / 553 sites → 200 / 551:

row	before	after
data/SSLConfig	sites: [""]	deleted — drops nothing now
data/SQLDriverConfig	sites: ["", "sslConfig"]	sites: [""] — the sslConfig site closed

1 row deleted, 1 row shrunk, 2 sites closed, 0 sites added anywhere; the ledger diff is deletions only. Generator census after: 551 dropped across 200 published schemas, 199 projected — 137 required-one-of, 60 non-blank-string, 2 dependent-required — 3 undecidable.

data/SQLDriverConfig's remaining "" site is its own separate rule, "sslConfig is required when ssl is true". That judges a VALUE, is if/then rather than this arm, and correctly stays dropped and annotated.

Banned keys (propertyNames / not) — NOT taken, and not forced

Confirmed against the tree, not assumed: the nearest sites judge a banned VALUE on a string (FILTER_ARRAY_LOGIC_KEYWORDS) or an allowed key set that is data-dependent (ai.paramHints against the action's own params). Neither is mechanically derivable, so no candidate was constructed. This is why the body says Part of and carries no closing keyword.

2. Mechanism fix A — the verdict is per NODE, the rules are per CHECK

verdictFor compared a node with ALL custom checks against the node with NONE, so any one declared arm marked the whole node projected. Reproduced on the landed code before changing it:

mixed(declared+undeclared)  dropped: []   projected: [{count: 2, declaredPatterns: ['non-blank-string']}]
undeclared-alone  (lit)     dropped: [{count: 1, declaredPatterns: []}]   projected: []
declared-alone    (lit)     dropped: []   projected: [{count: 1, declaredPatterns: ['non-blank-string']}]

A second refinement on a declared node was therefore neither ledgered nor annotated, and the generator's UNDECLARED line could not see it — silently violating the ruling's own 「A refinement that is not one of these named patterns stays dropped and annotated」.

Fix: projected now requires customs.length === declaredPatterns.length; anything else is dropped conservatively. The RAW differential is kept as a new projectionMoved field so the detector still MEASURES rather than asserts — collapsing it would have made the instrument blind to the zod upgrade it exists to notice — and the generator prints partially-stated sites on their own line.

Ablation, both directions (anchor-verified on disk, scripts/ablation-replace.mjs):

leg	blob	result
mutated — drop the total === stated guard	54ed82dbe4c2 to 2c1bff777363	1 test red, 42 green: "a DECLARED arm beside an UNDECLARED rule stays dropped"
restored	back to 54ed82dbe4c2, git diff HEAD empty	43 / 43 green; mutant text on disk 0, guard text 1

3. Mechanism fix B — generator/detector coupling, by construction

build-schemas.ts (three toJSONSchema calls) and projectOrNull each passed the override independently. Measured on the pristine base with only the generator's import stubbed out:

leg	gate exit	shared/Expression.json allOf	x-dropped-refinements	files carrying the non-blank pattern
base, untouched (dark control)	0	present	absent	35
base, generator-side override dropped	0 — GREEN	absent (wide)	absent (SILENT)	0

Census identical to an untouched run (553 / 201 / 197). That is the item-1 silence restored, standing behind a green ratchet — worse than the state the card was filed about, because the ledger now certifies it. A merge-conflict resolution was enough to cause it.

Chosen fix: one shared projection helper — projectPublishedJsonSchema in scripts/lib/refinement-projection.ts. All three generator calls, the union-branch projector behind the third, and the detector's differential now reach z.toJSONSchema through it, and projectByPruningUnionBranches no longer takes an override option at all. There is no argument left for a caller to forget.

Why the sandbox-builder pin was rejected, not overlooked: a pin detects after the fact and can be skipped, deleted or made vacuous, and it leaves the two-argument shape in place so the next merge conflict can still separate them. The choke point makes the one-sided failure unrepresentable rather than caught. Both halves now lose the override together or not at all — which is what turns the ablation from silent into loud. The test file's own publish() helper was rewired through the same call for the same reason, so the unit pins measure the real seam rather than a re-spelling of it.

Ablation, both directions:

leg	gate exit	Expression.json allOf	x-dropped-refinements
mutated — override removed from the ONE helper	1 — RED: 46 undeclared schemas + 76 miscounted ledger entries	absent (wide)	present (annotated)
restored	0	present	absent

The contrast is the whole point: before, one-sided removal was green and silent; now it is red and the file confesses.

4. Contract: the published file narrows toward what the runtime already refuses

Whole published tree, base vs head: 1530 of 1532 files byte-identical. The two that move are data/SSLConfig.json and data/SQLDriverConfig.json, each gaining dependentRequired and losing the matching x-dropped-refinements row. Nothing else in packages/spec/json-schema/** changed.

Parse-equivalence probe — 10,368 documents (2,592 SSLConfig-shaped over the full presence lattice of 4 keys times 6 value shapes including null, a wrong type and an unrecognised extra key; 7,776 SQLDriverConfig documents embedding each of those under three ssl states). Published-side verdicts computed with ajv 8.20.0 (draft 2020-12) against the two real snapshots.

reading	SSLConfig	SQLDriverConfig
documents	2,592	7,776
runtime accepts	60	180
published accepts, base	27	54
published accepts, head	15	30
narrowed by this arm	12	24
widened	0	0
documents the runtime ACCEPTS that the published file now refuses	0	0

Runtime behaviour did not move. The runtime verdict vector is byte-identical at merge base and head over all 10,368 documents — sha 9e7c848f04e0c687 (SSL) and 4f18f835d4d1a62e (SQL) on both sides. The base leg was run against the real base blobs (git checkout of the two source files at d8b12fca9, blob hashes asserted both ways, restore proven by an empty git diff HEAD), not against a retyped predicate.

LIT CONTROL for that zero — weakening the dependency map to one direction ({ cert: ['key'] }) moves 96 documents (24 SSL + 72 SQL) and lifts runtime accepts from 60 to 84 and 180 to 252. The zero is a reading, not a silence.

Note the published-accepts figures sit below runtime-accepts on both sides: SSLConfig.json is the OUTPUT shape and lists rejectUnauthorized as required because the runtime applies its .default(true). That asymmetry is pre-existing, is the x-io convention, and is unchanged by this PR — it is reported rather than netted out.

5. Verification

• Gates: derived from the merge base with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, re-derived after the origin/main merge (identical, 84 commands). Every exit code captured by redirecting to a file first, never through a pipe. 80 exit 0, 0 findings. The remaining 4 — check:doc-formula-expressions, check:dual-build-cjs-loads, check:lean-entry-closure, check:type-check-debt — exit 3, which those gates define as PREREQUISITE NOT MET ("Nothing was measured ... It is NOT a finding"): each reads BUILT output of packages outside this diff. They are NOT MEASURED, not red; the re-run against a full build is reported on the card.
• The derivation's own caveats are carried, not netted out: 50 artifact-roster families score silent for every card in the tree, 11 declare a population too wide to place, 5 take a value from the workflow, and 5 path-scheduled CI jobs run 30 steps with no local invocation. None of those is a clearance, and CI owns them.
• pnpm --filter @objectstack/spec check:generated: all 16 generated artifacts up to date. content/docs/references/** does not move — see acceptance notes.
• Targeted tests: scripts/refinement-projection.test.ts, scripts/dropped-refinements.test.ts, scripts/union-branch-projection.test.ts — 91 / 91. packages/spec typechecks clean (tsc --noEmit over both the package and tsconfig.scripts.json). The full @objectstack/spec suite reading is on the card.
• Lint, declared narrowing: eslint run over the 9 changed lintable files, 0 errors / 0 warnings, file count read from --format json. The population is eslint.config.mjs's own files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']; the config states in its own words that this repo "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file", so this diff cannot move the verdict on a file it does not touch. The repo-wide sweep is CI's run.
• origin/main merged through bash scripts/pm/os-regen-merge.sh (no rebase, no force-push). It brought one docs-only commit, docs(spec): SYNC_ARCHITECTURE stops teaching retryConfig as the rate-limit remedy #18979, overlapping none of this branch's paths and no merge=os-regen path. The previous arm's implementation body was asserted still present by quoted-exact-name git grep against origin/main, with a dark control at 0.

Acceptance notes

Noted, not filed — out of scope for this card and not one of the three filable classes:

• packages/spec/scripts/build-schemas.ts (the authorable-surface docblock, near line 846) still names the retired api-surface-signatures.json. The previous seat handed this to "the next editor of build-schemas.ts", which is this PR. It is left untouched deliberately: it is a stale code comment, not a defect, a contract violation or an authoring trap, and the bounded in-place exemption requires the finding to be the same defect class as this card, which it is not. Carrier: the next PR that edits that docblock for its own reasons.
• The dispatch's overlap warning — that a new keyword might move content/docs/references/**, four pages of which open PR spec: hold a predicate to what the engine can run; declare its fault semantics (ADR-0136) #18985 edits — measured FALSE. dependentRequired is a sibling keyword the reference renderer does not read, check:docs is green and check:generated reports all 16 artifacts current. No reference page moves, so there is no collision with spec: hold a predicate to what the engine can run; declare its fault semantics (ADR-0136) #18985 on that directory.

Reported for the seat to file (a candidate class-(b) finding, deliberately NOT fixed here):

• packages/spec ships src/**/*.zod.ts in files[], and scripts/check-published-files.mjs allows it with the reason "The Zod schemas are themselves the contract (Prime Directive Add metamodel interfaces for ObjectQL/ObjectUI contract #1); downstream code imports them directly, so these sources are product rather than build input." Two measurements contradict that reason: (1) the package's exports map exposes no ./src/* subpath and no wildcard, so no consumer can import those files at all; (2) 188 of the 202 shipped *.zod.ts files carry a relative import resolving to one of 35 modules under src/ that the glob does NOT ship (src/shared/lazy-schema.ts alone is imported by 181 of them), so they would not resolve even if reachable. Overwhelmingly pre-existing and far outside this card; this PR adds the third importer of one of those 35. Not verified by npm pack and not by a real consumer import — that is the next step for whoever takes it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

4 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ⚠️ 1 changed file(s) yielded no anchor (packages/spec/dropped-refinements.baseline.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/dropped-refinements.baseline.json) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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.

Coarse fallback — 136 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 43f4766889e39d7a4590c5787d38e5956d0b4cb6 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 43f4766889e39d7a4590c5787d38e5956d0b4cb6

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[os-elon-musk]

Contract review

129/129 Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6007a484a50cf8a985390a795cb69832f3df6af3

① Derived judgments

Isolated at-tier review; this seat serves below the tier constant and does not self-review. Tier verified by census of the reviewer's own transcript — a subagent cannot self-attest, since its get_session reads the parent — at 129 of 129 assistant turns, zero at any other model.

The decisive question was the ledger shrink: 201 to 200 entries, 553 to 551 sites, 197 to 199 projected, deletions only. A shrinking ratchet is either a defect fixed or a gate weakened, and the two are indistinguishable in the diff. It is a defect fixed, proven in both directions:

• data/SSLConfig.json at head carries dependentRequired in BOTH directions, {cert:[key], key:[cert]}, and the base row it retired was count: 1 — that one .refine() being hasCert === hasKey. The retired row corresponds to exactly that constraint and nothing more.
• Ablation (c), the exact shape "row deleted while the drop persists" — arm emission silenced with the head ledger kept — drives the generator to exit 1, naming the undeclared schema and the miscounted entry. Ablation (a), the retired row re-inserted against pristine code, also exit 1. Pristine control exit 0. So the build itself adjudicates the ledger in both directions and a bad deletion cannot land.
• Independently re-derived over a 5,003-document corpus with ajv: runtime verdict vectors byte-identical base and head (f78d5a62d223296f, 0dec47ca8fe169bb); published side narrowed 4 and 8, widened 0; the runtime-accepts-but-published-refuses asymmetry is 12 to 12 and 41 to 41, i.e. unchanged. Lit controls fired: a one-direction dependency map moves the runtime vector by 8 documents and the published vector by 2.

The remaining data/SQLDriverConfig "" site is a different rule — it judges the VALUE of ssl, which carries .default(false), so a dependentRequired would over-narrow and refuse documents the runtime accepts. Correctly left dropped, and not conflated with the retired row.

② Semver level

minor with a **BREAKING (published artifact narrows)** banner, line-initial Clause-②: yes (narrowing) in both the changeset and the PR body. Right rather than merely permitted: not in pre-mode, and the launch-window convention carries breaking-ness by banner plus ADR-0087 disposition. ADR-0087 D3 entry is not owed — the disposition is not-required (no-migration-prescription) per the maintainer ruling in comment 5725370614, matching the previous arm's precedent already on main. check-adr-0087-registration.mjs and check-changeset-no-major.mjs both exit 0 locally against an explicit base, and Check Changeset is green in CI.

③ Boundary flags

Governed surface: 0 of 11 paths hit the register, derived by check-governed-merges.mjs --pr 19005 three-dot by construction, not from a caller-supplied list and not recalled. Release-owned content/docs/releases/: 0 paths, lit control 2. Generated api-surface-declarations/** and api-surface/**: 0 paths, and not a stale omission — the moved module is not publicly re-exported. Gate-weakening: none. Floors unmoved, ratchet deletions only, zero tests skipped, disabled, quarantined or .only-ed (lit control: a synthetic it.skip line reads 1), it() blocks +16/−0, vitest 91/91 at head against 75/75 at base.

Implemented-by: claude/issue-18670-dependent-required-arm
Reviewed-by: session_019srGWGCBBCBHqcDoRZpQRh

VERDICT: PASS

Non-blocking, carried and not fixed here: the PR body's "1530 of 1532" is an under-count, the true census being 1528 of 1532 identical, with objectstack.json and .build-input-hash-schema also moving derivatively; packages/spec/scripts/build-openapi.ts:95 is a second override-less projection path, which this seat is filing as its own card; and two in-module header sentences are now stale.

---

Generated by Claude Code

[os-elon-musk]

Contract review

Served-tier: 129/129 CONTRACT_REVIEW_TIER
Head-sha: 6007a484a50cf8a985390a795cb69832f3df6af3

① Derived judgments

Isolated at-tier review; this seat serves below the tier constant and does not self-review. Tier verified by census of the reviewer's own transcript — a subagent cannot self-attest, since its get_session reads the parent — at 129 of 129 assistant turns, zero at any other model.

The decisive question was the ledger shrink: 201 to 200 entries, 553 to 551 sites, 197 to 199 projected, deletions only. A shrinking ratchet is either a defect fixed or a gate weakened, and the two are indistinguishable in the diff. It is a defect fixed, proven in both directions:

• data/SSLConfig.json at head carries dependentRequired in BOTH directions, {cert:[key], key:[cert]}, and the base row it retired was count: 1 — that one .refine() being hasCert === hasKey. The retired row corresponds to exactly that constraint and nothing more.
• Ablation (c), the exact shape "row deleted while the drop persists" — arm emission silenced with the head ledger kept — drives the generator to exit 1, naming the undeclared schema and the miscounted entry. Ablation (a), the retired row re-inserted against pristine code, also exit 1. Pristine control exit 0. So the build itself adjudicates the ledger in both directions and a bad deletion cannot land.
• Independently re-derived over a 5,003-document corpus with ajv: runtime verdict vectors byte-identical base and head (f78d5a62d223296f, 0dec47ca8fe169bb); published side narrowed 4 and 8, widened 0; the runtime-accepts-but-published-refuses asymmetry is 12 to 12 and 41 to 41, i.e. unchanged. Lit controls fired: a one-direction dependency map moves the runtime vector by 8 documents and the published vector by 2.

The remaining data/SQLDriverConfig "" site is a different rule — it judges the VALUE of ssl, which carries .default(false), so a dependentRequired would over-narrow and refuse documents the runtime accepts. Correctly left dropped, and not conflated with the retired row.

② Semver level

minor with a **BREAKING (published artifact narrows)** banner, line-initial Clause-②: yes (narrowing) in both the changeset and the PR body. Right rather than merely permitted: not in pre-mode, and the launch-window convention carries breaking-ness by banner plus ADR-0087 disposition. ADR-0087 D3 entry is not owed — the disposition is not-required (no-migration-prescription) per the maintainer ruling in comment 5725370614, matching the previous arm's precedent already on main. check-adr-0087-registration.mjs and check-changeset-no-major.mjs both exit 0 locally against an explicit base, and Check Changeset is green in CI.

③ Boundary flags

Governed surface: 0 of 11 paths hit the register, derived by check-governed-merges.mjs --pr 19005 three-dot by construction, not from a caller-supplied list and not recalled. Release-owned content/docs/releases/: 0 paths, lit control 2. Generated api-surface-declarations/** and api-surface/**: 0 paths, and not a stale omission — the moved module is not publicly re-exported. Gate-weakening: none. Floors unmoved, ratchet deletions only, zero tests skipped, disabled, quarantined or .only-ed (lit control: a synthetic it.skip line reads 1), it() blocks +16/−0, vitest 91/91 at head against 75/75 at base.

Implemented-by: claude/issue-18670-dependent-required-arm
Reviewed-by: session_019srGWGCBBCBHqcDoRZpQRh

VERDICT: PASS

Non-blocking, carried and not fixed here: the PR body's "1530 of 1532" is an under-count, the true census being 1528 of 1532 identical, with objectstack.json and .build-input-hash-schema also moving derivatively; packages/spec/scripts/build-openapi.ts:95 is a second override-less projection path, which this seat is filing as its own card; and two in-module header sentences are now stale.

---

Supersedes comment 5729571884 on this same head. That record spelled the line 129/129 Served-tier: ..., putting the at-tier stamp control before the KEY, so the line did not begin with Served-tier: and --pair read it as absent (C7, exit 4). The stamp control may precede the CONSTANT, not the key. Nothing about the review changed — same head, same reviewer, same 129/129 transcript census, same verdict; only this line's spelling is repaired.

---

Generated by Claude Code