You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled #11942
⚠️State as of 2026-08-25T06:5xZ (devx seat, session_01UjM2ia8Av1v5NqfqQEQmC6). The page-level half of this card is delivered in PR #12045 (Part of, not Fixes — deliberately). What is left is not this lane's to fix.
Measured on the dispatch: this page cannot be opted in at all. All 13 fences were marked, the gate run, the tree reverted — 128 diagnostics, not one a doc-vs-SDK divergence. Three are a surface-resolution gap (content/docs/** sits in a surface that cannot resolve @objectstack/client); ten are deliberate continuation fragments sharing Quick Start's client. Triage's binding scope sentence — "each red is a real doc-vs-SDK divergence, not a marker problem" — is falsified. Full review: comment 5406662596.
Restart-when:#12048 lands (the docs surface can resolve @objectstack/client). Unlock-action: re-run the marking exercise on this page; the reds that remain will then be the real divergences this card was filed to catch. The in-page note PR #12045 adds names the same condition, so the next agent reads the answer instead of re-deriving it.
⚠️ Also spun off: #12051 — one JSX block fenced typescript silently disables the semantic pass for all 227 marked examples while the gate reports green. PR #12045 retags the one known instance; the class is unswept.
⚠️This body carries sanitizer damage, found by the dev. The sentence below beginning "The operative word is marked" contains an empty backtick pair where the marker's spelling used to be — GitHub's body sanitizer ate it, backticks notwithstanding. Take the spelling from the tree, not from here: the docs/MDX root uses an MDX comment ({/* … */}) because MDX has no HTML comments; only the skills/.md and TSDoc roots use the angle-comment form. ⛔ Copying the angle form into .mdx breaks the docs build outright.
Found while verifying the docs-drift advisory on PR #11929 (#8140). Observation class: the gate
works exactly as designed — this is about its opt-in coverage, not a defect in it. ⛔ No gate was
built or changed on that PR.
Measured at 65c2b2a43.
What happened, concretely
#8140 narrowed 51 client SDK return types. Two TypeScript examples in content/docs/api/client-sdk.mdx were falsified by that change and would not compile:
error TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
-> client-sdk.mdx:404 run.runId passed to resume(flowName: string, runId: string)
error TS2345: Argument of type 'unknown' is not assignable to parameter of type 'string'.
-> client-sdk.mdx:441 suggestions[0].id passed to confirm(id: string)
Both were fixed on that PR. CI would not have caught either, and the reason is not that the
repo lacks the instrument — it has a good one.
The instrument exists and is genuinely strong
pnpm --filter @objectstack/spec check:skill-examples type-checks prose TypeScript across three
surfaces, content/docs/** among them, and it is not shallow — it resolves real workspace types,
refuses to run against an unbuilt dist rather than scoring a false green (#7122), and carries a
substantial self-test. On 65c2b2a43 it reports:
256 marked example(s) across 99 file(s), 3 surface(s)
✅ 256 prose examples type-check across 3 surface(s)
The operative word is marked: a block is compiled only when an `` comment sits
on the line directly above it. That opt-in is a deliberate, sound design — it lets a page carry
deliberately-partial illustrations without the gate choking on them.
The coverage gap, measured
$ python3 - <<'PY' # hand-written pages only; content/docs/references (generated) excluded
... counts top-level ```ts/```tsx/```typescript fences and os:check markers per page ...
PY
hand-written content/docs pages with a ts/tsx fence : 137
total top-level ts/tsx/typescript fences : 871
total os:check markers : 192
pages with fences but ZERO markers : 59
So roughly a fifth of the fenced examples are marked, and 59 pages have fences but not one
marker. The heaviest:
⭐ client-sdk.mdx is the sharp end of this. It is the page a customer opens to learn the SDK,
its single largest fence contains 15 live SDK call sites, and it is exactly the page a change to packages/client is most likely to falsify — which is what just happened. It has zero markers.
Why this is worth recording rather than shrugging at
The docs-drift advisory on #11929 did its job: it named the 9 pages mentioning ObjectStackClient.
But an advisory is a prompt to a human, and it cannot distinguish "prose that is still true"
from "a fence that no longer compiles" — it flagged 9 pages of which 8 were noise and 1 was real.
The gate can make that distinction mechanically, on exactly the pages that opt in.
⚠️ Being explicit about the limit of this finding: an unmarked block is not evidence of rot. Many
are pseudo-code, partial snippets, or non-TypeScript-in-a-ts-fence, and marking those would be wrong.
The claim here is narrower: nobody has decided, page by page, which side of that line each block is
on — and on the SDK's own reference page the answer was never recorded, so a real break shipped
past CI.
Suggested shape (for whoever grades this — not a plan)
Start with client-sdk.mdx. One page, 13 fences, highest customer value, and it has a
demonstrated break. Marking its examples one at a time — fixing or deliberately leaving each —
is a bounded, checkable piece of work.
A per-page ratchet ("a page that has any marker must have all its ts fences marked") would keep a
page from regressing once converted, without demanding the whole corpus at once.
Related: #8140 (the narrowing that surfaced this), PR #11929 (where the two examples were fixed).
Blocked-by: #12048
session_01UjM2ia8Av1v5NqfqQEQmC6). The page-level half of this card is delivered in PR #12045 (Part of, notFixes— deliberately). What is left is not this lane's to fix.Measured on the dispatch: this page cannot be opted in at all. All 13 fences were marked, the gate run, the tree reverted — 128 diagnostics, not one a doc-vs-SDK divergence. Three are a surface-resolution gap (
content/docs/**sits in a surface that cannot resolve@objectstack/client); ten are deliberate continuation fragments sharing Quick Start'sclient. Triage's binding scope sentence — "each red is a real doc-vs-SDK divergence, not a marker problem" — is falsified. Full review: comment5406662596.Restart-when:#12048 lands (the docs surface can resolve@objectstack/client).Unlock-action:re-run the marking exercise on this page; the reds that remain will then be the real divergences this card was filed to catch. The in-page note PR #12045 adds names the same condition, so the next agent reads the answer instead of re-deriving it.typescriptsilently disables the semantic pass for all 227 marked examples while the gate reports green. PR #12045 retags the one known instance; the class is unswept.{/* … */}) because MDX has no HTML comments; only theskills/.md and TSDoc roots use the angle-comment form. ⛔ Copying the angle form into.mdxbreaks the docs build outright.Found while verifying the docs-drift advisory on PR #11929 (#8140). Observation class: the gate
works exactly as designed — this is about its opt-in coverage, not a defect in it. ⛔ No gate was
built or changed on that PR.
Measured at
65c2b2a43.What happened, concretely
#8140 narrowed 51 client SDK return types. Two TypeScript examples in
content/docs/api/client-sdk.mdxwere falsified by that change and would not compile:Both were fixed on that PR. CI would not have caught either, and the reason is not that the
repo lacks the instrument — it has a good one.
The instrument exists and is genuinely strong
pnpm --filter @objectstack/spec check:skill-examplestype-checks prose TypeScript across threesurfaces,
content/docs/**among them, and it is not shallow — it resolves real workspace types,refuses to run against an unbuilt
distrather than scoring a false green (#7122), and carries asubstantial self-test. On
65c2b2a43it reports:The operative word is marked: a block is compiled only when an `` comment sits
on the line directly above it. That opt-in is a deliberate, sound design — it lets a page carry
deliberately-partial illustrations without the gate choking on them.
The coverage gap, measured
So roughly a fifth of the fenced examples are marked, and 59 pages have fences but not one
marker. The heaviest:
content/docs/data-modeling/field-types.mdxcontent/docs/kernel/contracts/metadata-service.mdxcontent/docs/kernel/cluster.mdxcontent/docs/data-modeling/seed-data.mdxcontent/docs/api/client-sdk.mdxcontent/docs/data-modeling/drivers.mdx⭐
client-sdk.mdxis the sharp end of this. It is the page a customer opens to learn the SDK,its single largest fence contains 15 live SDK call sites, and it is exactly the page a change to
packages/clientis most likely to falsify — which is what just happened. It has zero markers.Why this is worth recording rather than shrugging at
The docs-drift advisory on #11929 did its job: it named the 9 pages mentioning
ObjectStackClient.But an advisory is a prompt to a human, and it cannot distinguish "prose that is still true"
from "a fence that no longer compiles" — it flagged 9 pages of which 8 were noise and 1 was real.
The gate can make that distinction mechanically, on exactly the pages that opt in.
are pseudo-code, partial snippets, or non-TypeScript-in-a-ts-fence, and marking those would be wrong.
The claim here is narrower: nobody has decided, page by page, which side of that line each block is
on — and on the SDK's own reference page the answer was never recorded, so a real break shipped
past CI.
Suggested shape (for whoever grades this — not a plan)
blocks nobody verified would either fail loudly on day one or, worse, be "fixed" by editing correct
documentation to satisfy a compiler.
client-sdk.mdx. One page, 13 fences, highest customer value, and it has ademonstrated break. Marking its examples one at a time — fixing or deliberately leaving each —
is a bounded, checkable piece of work.
page from regressing once converted, without demanding the whole corpus at once.
Related: #8140 (the narrowing that surfaced this), PR #11929 (where the two examples were fixed).
Generated by Claude Code