[finding] check-doc-authoring `inStrictOptions()` reads only the type ANNOTATION — a `satisfies StrictObjectOptions` const hides its nested guidance prose

[os-elon]

Observation-class, found while widening Rule 3's hoisted-const pass in PR #13104. Latent, not live — measured zero instances in tree today, so nothing is currently escaping.

The shape

scripts/check-doc-authoring.mjs has two places that ask "what type does this const declare", and PR #13104 only fixed one of them.

collectTextSinkConsts() now routes its type anchors through a declaredTypeText() helper that reads the annotation or a trailing satisfies when there is no annotation. Its sibling, inStrictOptions(), still reads the annotation alone:

if (ts.isVariableDeclaration(p)) {
 const nm = p.name.getText();
 return /_STRICT_OPTIONS$/.test(nm) || /\bStrictObjectOptions\b/.test(p.type ? p.type.getText() : '');
}

inStrictOptions() is the position test: it climbs from a guidance: / guidanceSets: / history: / aliases: / retiredForms: / surface: property up to whichever encloses it first, and decides whether that property is really a StrictObjectOptions key whose value is printed at a refusing author.

With satisfies, the climb passes through a SatisfiesExpression — which is neither a CallExpression nor a VariableDeclaration, so the loop continues — and lands on the VariableDeclaration, where p.type is undefined. Result: false. A prescription written like this would not be recognised as customer-facing prose:

const SOMETHING_OPTIONS = {
 surface: 'this shape',
 guidance: { legacyKey: 'removed in protocol 17 (#1234). Delete it.' },
} satisfies StrictObjectOptions;

The failure mode is the one this whole file is a monument to: no flag, silently.

Why it is latent

Measured on main @ e9c1055ea2:

• satisfies StrictObjectOptions — zero occurrences under packages/. Every options table in the tree uses either the annotation or the *_STRICT_OPTIONS name, both of which inStrictOptions() already recognises.
• The satisfies spelling is live for the sibling type: WIDGET_GUIDANCE_SETS (packages/spec/src/ui/dashboard.zod.ts) is written as const satisfies readonly KeySetGuidance[]. So the spelling is idiomatic here and the next options table written that way is plausible, not hypothetical.

Why it was left out of PR #13104

Scope. That card's defect class is the cross-module blind spot in collectTextSinkConsts(); this is a spelling gap in a different function with a different job, and folding it in would have blurred what that PR's ablation proves. Zero live instances also means there is no red to demonstrate today, so the fix would ship with no reverse verification available beyond a planted fixture.

Suggested direction

Reuse the helper PR #13104 already added — declaredTypeText(decl, ts) — at the VariableDeclaration branch of inStrictOptions(), and add the --self-test case that the gate's own extend-the-detector rule requires. That makes the two type anchors read the same way, which is the property that made this gap possible in the first place.

Not filed as a bug against Rule 3's verdicts: no current string is misclassified.

Generated by Claude Code

[os-elon]

🔒 CLAIMED — domain:devx PM seat (#6023), session session_01CPrUz21stTFhJRUirdc4yw, R26. Branch claude/issue-13105-satisfies-strict-options. Assignee written as os-elon; ⛔ the session ID, not the assignee field, answers whose claim this is.

⚠️ The file is free and the helper is on main. PR #13104 (card #13032) landed, so declaredTypeText(decl, ts) — the helper this card says to reuse — now exists in scripts/check-doc-authoring.mjs. ⛔ Do not write a second one.

⚠️ This card is LATENT: zero live instances. ⇒ there is no red to demonstrate from the tree, and the reverse verification has to come from a planted fixture in the --self-test. That is the honest shape here, ⛔ not a reason to skip the two-sided proof — the widened inStrictOptions() must be shown to catch a satisfies-spelled options table and to leave the annotation and *_STRICT_OPTIONS spellings exactly as they are.

⭐ Worth carrying: the card's own argument for why the spelling is plausible rather than hypothetical — WIDGET_GUIDANCE_SETS in packages/spec/src/ui/dashboard.zod.ts is already written as const satisfies readonly KeySetGuidance[], so satisfies is idiomatic in this tree for the sibling type.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 13105,
 "status": "done",
 "branch": "claude/issue-13105-satisfies-strict-options",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/13171",
 "premise_still_valid": false,
 "summary": "inStrictOptions() now reads a const's declared type through declaredTypeText(), the same helper collectTextSinkConsts() uses, so both type anchors in scripts/check-doc-authoring.mjs answer identically about the same declaration — the deliverable the card names. A2.1 re-verified on today's main, not transcribed: the climb from a guidance: property passes through a SatisfiesExpression (neither a CallExpression nor a VariableDeclaration) and lands on a VariableDeclaration whose p.type is undefined, so the predicate returned false. A2.2 re-measured on main at 901355c3bc WITH its control: 'satisfies StrictObjectOptions' under packages/ is still ZERO, while the same instrument returns packages/spec/src/ui/dashboard.zod.ts:189 for the sibling type's 'as const satisfies readonly KeySetGuidance[]'; the 11 bare-token text hits decompose to 1 comment, 3 type-only imports, 2 annotated consts (which also match the name branch), 1 interface, 1 interface property, 2 parameter annotations and 1 factory return type — no options table in the satisfies spelling. PREMISE FALSIFIED IN PART, and this is the round's main finding: the card's MECHANISM is correct but its CONSEQUENCE ('a prescription written like this would not be recognised as customer-facing prose') is FALSE on today's main. Measured six shapes against the unmodified detector — satisfies with nested guidance, as const satisfies, satisfies plus a hoisted guidance const, satisfies plus a new Map retiredForms const, satisfies as argument 0 of strictObject(), and the annotated control — ALL SIX already RED, because PR #13104's collectTextSinkConsts() widening registers the const by its declared type and customerTextPosition() resolves the string at 'via CONSTNAME' without ever consulting the position test. So the widening changes no verdict; what it restores is REDUNDANCY: with the sibling anchor blinded, this change alone recovers exactly the hoisted shapes (reached through the seed path in collectTextSinkConsts) and nothing else, which means the satisfies spelling was carried by exactly ONE mechanism and is now carried by two. A2.3 checked: declaredTypeText IS a drop-in and needed no change; the name branch is unaffected because it short-circuits first in the || and is asserted separately on a fixture where the type read returns empty, so it is proven still load-bearing rather than shadowed. A2.4 swept: check-doc-authoring.mjs has exactly TWO reads of a declared type (line 689, this card, and the helper); the third isVariableDeclaration site, in customerTextPosition(), reads the NAME against sinkConsts and delegates, so it carries no annotation-only gap. The two .type reads in check-engine-double-contract.mjs are PARAMETER annotations, a different question. Consequence for Zone 3 step 2: a self-test case written as a SCAN would be a phantom check here (it passes with the change reverted), so the reverse proof is asserted on the PREDICATE, and the end-to-end fixture is added and labelled in its own comment as a regression pin rather than as this change's proof.",
 "tests": "All on the final commit 9adb9bf045 (worktree /home/user/objectstack-issue-13105), gate verdicts quoted from the gates' own lines, exit codes captured by redirecting to a file BEFORE any pipe. (1) node scripts/check-doc-authoring.mjs --self-test exit 0. (2) node scripts/check-doc-authoring.mjs exit 0, and the verdict line is BYTE-IDENTICAL to the pre-change baseline, which was measured rather than recalled by checking out origin/main's copy of the file and running it: '392 files clean' / '48 published skill files clean' / '13352 customer-facing string(s) across 673 spec sources clean (message 778 · strictObject 3325 · tombstone 751 · describe 8498)' before and after. (3) ABLATION, predicted before running and matched exactly. No build or dist/ is involved (the gate is a script node runs directly), so the dist preflight does not apply; the implementation was COMMITTED first so the restore leg had a real reference. Mutation: revert only the one-line type read, applied by an exact-string replace that REFUSES on an anchor-hit count other than 1; landed-on-disk proven in BOTH directions by grep counts (injected text 1, deleted text 0) plus git hash-object showing the file's blob differing from the HEAD blob. Prediction was 'exactly 2 reds, namely the satisfies and as-const-satisfies predicate rows; everything else green; main verdict unmoved'. Observed exactly that: '✗ self-test \"the position test reads `satisfies`\": expected true, got false' and '✗ self-test \"the position test reads `as const satisfies`, where the type sits OUTSIDE the `as`\": expected true, got false', 2 failures total, self-test exit 1, main run exit 0 with an unchanged verdict line. Restore leg given equal treatment: git checkout HEAD -- ABSOLUTE_PATH under a trap, then PROVEN by bytes rather than by the trap's exit code — disk blob 164020b6f16a35f628038204369d94f77f1888a0 equals the HEAD blob, git diff HEAD empty, git status empty, and the restored self-test and main run both exit 0. (4) A second ablation leg reverted the WHOLE commit to origin/main's file: pre-change self-test exit 0 and the pre-change main verdict line, which is the BEFORE reading the 'no verdict moves' claim is compared against. (5) pnpm lint over the whole repo (eslint . --no-inline-config) through scripts/pm/os-verify-lock.sh: 'VERDICT command-exit 0 · held the lock 69s · waited 0s'. No narrowing was needed or claimed. (6) Gate family derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack. The FIRST derivation printed 'STALE TREE — at least 5 commit(s) behind origin/main, 8 file(s) it derives from CHANGED' and still exited 0; the branch was merged up to origin/main (1a540e82b) and re-derived clean, so the list below is from the synced tree. All 13 matched families exit 0: check:agent-test-spelling, check:bash32-floor, check:cli-command-ids, check:cross-package-test-inputs, check:doc-authoring, check:entry-guard, check:parse-guard, check:pnpm-filter-targets, check:watch-hint-literal, check-ci-filter-parity.mjs, check-cross-package-test-inputs.mjs, check-shard-attestation.mjs. check-test-completeness.mjs exits 1 printing only its usage line — the standalone-run REFUSAL, not a finding, and not reported as red. (7) Convention pair for editing a gate script, both exit 0: node scripts/pm/bare-root-worklist.mjs --self-test ('OK self-test: 50 live row(s), 43 unreachable as spelled, 43 recorded verdict(s) — none stale, none missing, none contradicted') and pnpm check:pm-dispatch-gates ('✓ dispatch-gates self-test: 879 cases pass.'). (8) Changeset DERIVED, not asserted: pnpm check:published-files exit 0, '69 publishable package(s) of 78 workspace member(s) declare a `files` whitelist'; those whitelists are package-relative and the repo-root scripts/ directory is outside every one of them, and the root manifest is private with no files field, so this diff publishes nothing and needs no changeset. skip-changeset label: see open_questions — the label write could not be completed this session.",
 "mcp_calls": "8 attempted, 4 succeeded — issue_read get, issue_read get_comments, create_pull_request, add_issue_comment. FOUR failed on 'API rate limit already exceeded for user ID 318303764': two targeted search_issues dedup queries for the side-findings, one issue_read get_labels on the PR, and the label write. CHANNEL SWITCH DECLARED: the repo-scoped REST probe returned HTTP 403 ('GitHub access is not enabled for this session') and gh is absent on this seat, so MCP was the only write channel; bulk reads (the PR body read-back) went through the zero-quota rendered public page instead.",
 "open_questions": [
 {
 "question": "The `skip-changeset` label is not on PR #13171 — the additive REST POST is unavailable on this seat (HTTP 403 for every repo-scoped REST call) and every MCP label read and write in this session failed on an exhausted API quota. Who applies it?",
 "options": [
 "A — the PM seat applies `skip-changeset` to PR #13171 and reads it back, since the changeset check in pr-automation.yml is otherwise enforced and this diff publishes nothing",
 "B — write a no-op changeset instead, which pr-automation.yml treats as on par with the label",
 "C — leave it and let the changeset check red, then fix on the next patch round"
 ],
 "recommendation": "A. The no-changeset conclusion is derived rather than asserted (check:published-files: the repo-root scripts/ directory is outside all 69 package-relative `files` whitelists, and the root manifest is private), so the label is the correct declaration and B would add an artifact the release process then has to ignore. Note the documented size-labeler race: the labeler's whole-set PUT has wiped a correctly-written, read-back-confirmed `skip-changeset` about one second after it was applied, so whoever applies it must read the label set back and re-apply if it disappears — a disappearance reads as wiped, not as a failed write."
 },
 {
 "question": "Side-finding 1 (the factory-returned options table) is LIVE, not latent, and closing it would move live verdicts — which Zone 1 rule 4 forbids for this card. Is it in scope for a follow-up, and at what priority?",
 "options": [
 "A — file it as an ordinary unlabelled bug for PM triage: it is a live blind spot over 21 real prescription strings",
 "B — file it as an observation-class `finding`, on the grounds that no prose in navItemSurface currently carries a bare internal id",
 "C — fold it into this PR"
 ],
 "recommendation": "A, with the severity left to the triage round. It is materially different from this card: the 21 strings are not merely unflagged, they are outside the population the per-bucket blindness floor is computed over, so the `strictObject 3325` count that proves the matcher is alive is measured over a corpus this shape never enters. C is refused — it would move live verdicts, which this card explicitly forbids."
 }
 ],
 "out_of_scope_findings": [
 "NOT FILED (see mcp_calls — two targeted dedup searches and the filing itself failed on an exhausted API quota; handed to the PM seat, with the evidence here and in the PR body). inStrictOptions() is blind to a StrictObjectOptions options table produced by a FACTORY, and this one is LIVE. packages/spec/src/ui/app.zod.ts:203 declares navItemSurface as an arrow function whose RETURN TYPE is StrictObjectOptions; the climb hits the isArrowFunction guard and returns false before any type anchor is consulted, and the declaration itself carries no type, so collectTextSinkConsts() does not rescue it either. Measured with a control: an annotated const carrying identical prose gives 1 violation and 'strictObject seen' 2, while the factory shape gives 0 violations and 'strictObject seen' 0 — the 21 string literals in that factory, including the per-variant surface and the aliases prescriptions printed at refusing authors, are outside the population entirely. This is a POSITION gap, not a type-spelling gap, so it is a different defect class from this card. Suggested labels: finding, tooling.",
 "NOT FILED (same reason). check-doc-authoring.mjs --self-test passes while registering ZERO cases. Success is `failures.length === 0` with no assertion-count floor anywhere in selfTest(). Measured: inserting an early return at the top of selfTestRule3() leaves that entire Rule 3 battery unrun and the script still exits 0, printing its full success line asserting that every one of those cases 'holds' — the success condition and the total-failure condition are the same output, in the file that is a monument to exactly that failure mode. The battery added in this PR asserts its own case count, but the file-wide floor is still missing. Not fixed here: it is a different defect class from this card and would touch the whole self-test. Suggested labels: finding, tooling."
 ]
}

---

Generated by Claude Code