feat(scripts): census — do package-root Markdown TS blocks compile?

[huangyiirene]

Part of #18715 — this PR answers the card's own "⛔ Not measured" question with a number. It deliberately does not close the blind spot: nothing here gates anything, so the half left open is the wiring decision, which is a new required gate and therefore the maintainer's floor (live precedent: the PR parked in the decision box for that reason, referenced in the dispatch). #18715 stays open on merge.

Clause-②: no

What landed

One file: scripts/measure-markdown-ts-blocks.mjs, 1086 lines, a member of the existing scripts/measure-*.mjs family (8 prior members). It is a measurement instrument, not a gate:

• it exits 0 on every census outcome;
• it is wired into no CI job, no package.json script, no package test/lint chain;
• it exits non-zero for exactly one reason — the instrument itself could not run. "Could not run" is a failure, not a skip.

Usage: node scripts/measure-markdown-ts-blocks.mjs (census, 12s on a warm build) · --json · --only PATH · --controls-only · --self-test (30 batteries, no build needed).

The census

Population: *.md at the root of every directory under packages/ that carries a package.json — 76 package roots, 141 Markdown files, 1002 fenced ts/typescript/tsx blocks. content/docs/** is a different population with its own gates and is out of scope.

Three numbers, because two would hide the answer inside the convention (see below). RAW counts a block failing on any diagnostic; TOLERANT counts it failing on any diagnostic outside the forgiven set; WELL-FORMED AND WRONG counts blocks that parse as a TypeScript module and still fail — the class the repaired kernel.logger block belonged to.

stratum	files	blocks	RAW	TOLERANT	WELL-FORMED AND WRONG
HAND-WRITTEN (repairable by an author)	54	282	195 (69.1%)	76 (27.0%)	58 (20.6%)
CHANGELOG.md (release-owned history)	46	720	646 (89.7%)	356 (49.4%)	109 (15.1%)
sub-stratum: the literal packages/*/*.md glob the card names	42	654	574 (87.8%)	314 (48.0%)	131 (20.0%)

RAW is an upper bound — it counts fragments that were never meant to stand alone. TOLERANT is a lower bound, and that is the direction that matters: a forgiven "cannot find name" leaves that name typed any, so every downstream use of it goes unchecked. Real defects hide behind an elision; they never appear because of one. The honest sentence is "between TOLERANT and RAW".

⚠️ The two strata are reported separately and never summed. CHANGELOG.md is compiled by changeset version from .changeset/*.md and is release-owned: its blocks are before/after migration snippets that deliberately document removed APIs (57 of its counted diagnostics are TS2305 "has no exported member"). A failing block there is frequently correct documentation, and it cannot be repaired in a code PR at all.

Diagnostic composition over the whole corpus:

  forgiven  elided-name                 1297 diagnostics in  527 blocks   TS2304x1275 TS2503x20 TS2552x2
  COUNTED   syntax                       772 diagnostics in  265 blocks   TS1005x370 TS1128x170 TS1109x115 TS1127x73
  COUNTED   semantic                     332 diagnostics in  141 blocks   TS2305x57 TS2300x56 TS2451x49 TS18004x47
  COUNTED   implicit-any                  65 diagnostics in   42 blocks   TS7006x54 TS7031x8 TS7008x2 TS7023x1
  forgiven  doc-local-path                12 diagnostics in    9 blocks   TS2307x12
  COUNTED   unpublished-subpath            8 diagnostics in    7 blocks   TS2307x8
  forgiven  missing-ambient-environment     1 diagnostic  in    1 block    TS2593x1

Per-file breakdown (blocks / RAW fail / TOLERANT fail), every file carrying at least one TOLERANT failure:

   259  229  141  packages/spec/CHANGELOG.md                        4    4    4  packages/plugins/plugin-auth/ARCHITECTURE.md
    33   29   23  packages/services/service-automation/CHANGELOG.md 7    7    4  packages/plugins/plugin-auth/CHANGELOG.md
    37   35   22  packages/runtime/CHANGELOG.md                     9    9    4  packages/plugins/plugin-sharing/CHANGELOG.md
    50   46   19  packages/objectql/CHANGELOG.md                    6    4    4  packages/services/service-analytics/CHANGELOG.md
    25   23   15  packages/metadata-protocol/CHANGELOG.md           7    6    4  packages/services/service-datasource/CHANGELOG.md
    18   16   12  packages/lint/CHANGELOG.md                        4    4    4  packages/triggers/trigger-record-change/CHANGELOG.md
    20   18   11  packages/cli/CHANGELOG.md                         4    4    3  packages/client/README.md
    27   25   11  packages/client/CHANGELOG.md                      7    7    3  packages/core/CHANGELOG.md
    23   23   10  packages/rest/CHANGELOG.md                        4    3    3  packages/drivers/driver-memory/README.md
    14   14    9  packages/client-react/README.md                   8    8    3  packages/plugins/plugin-hono-server/CHANGELOG.md
    17   15    9  packages/drivers/driver-mongodb/CHANGELOG.md      3    3    3  packages/rest/README.md
    10   10    9  packages/metadata/CHANGELOG.md                   15   13    3  packages/spec/DEVELOPMENT_PLAN.md
    10   10    8  packages/platform-objects/CHANGELOG.md
    20   20    8  packages/runtime/README.md                       ... 2 each: client-react/CHANGELOG, metadata-core/CHANGELOG,
    33   27    7  packages/drivers/driver-sql/CHANGELOG.md             plugin-audit/CHANGELOG, plugin-auth/README,
    10    9    6  packages/core/ADVANCED_FEATURES.md                   plugin-reports/CHANGELOG, service-i18n/CHANGELOG,
    12   12    6  packages/plugins/plugin-security/CHANGELOG.md        service-job/README, service-queue/CHANGELOG,
    11    7    5  packages/services/service-automation/README.md       service-realtime/README, service-sms/CHANGELOG,
     7    5    5  packages/spec/V3_MIGRATION_GUIDE.md                  service-storage/CHANGELOG, spec/PLUGIN_STANDARDS,
    14   12    4  packages/drivers/driver-memory/CHANGELOG.md          trigger-record-change/README, trigger-schedule/CHANGELOG,
                                                                      trigger-schedule/README
 ... 1 each: cli/README, driver-mongodb/README, driver-turso/README, mcp/CHANGELOG, mcp/README, observability/README,
             knowledge-ragflow/README, service-cache/README, service-cluster/CHANGELOG, service-i18n/README,
             service-package/README, service-queue/README, service-settings/CHANGELOG, service-storage/README,
             spec/README, spec/REST_API_PLUGIN, spec/ZOD_SCHEMA_AUDIT_REPORT, types/CHANGELOG, types/README,
             verify/CHANGELOG

  33 file(s) with TS blocks and zero TOLERANT failures.

The full per-block record, with every diagnostic, is node scripts/measure-markdown-ts-blocks.mjs --json.

The elision convention — the design question, and why the obvious answer is disqualified

The card says the convention is the real design question, not the extraction. It is, and the obvious answer fails.

⛔ Exclusion is disqualified, and this PR proves it rather than asserting it. The obvious rule is: a block carrying an elision marker (// ...) is skipped. Run that rule against the one failure this repository has already measured — the pre-#18712 kernel.logger block in packages/core/PHASE2_IMPLEMENTATION.md, tsc --noEmit --strict exit 2 with TS2341 — and it is excluded, because that block ends with the line // ... plugin registration code .... An exclusion rule would have hidden the only defect in this family anyone has ever measured. The instrument reports the exclusion reading on every run, labelled disqualified, so the number cannot hide inside the convention:

reading	hand-written	CHANGELOG
[disqualified] EXCLUSION	188 fail of 272 considered, 10 blocks skipped	642 fail of 716 considered, 4 blocks skipped

✅ The rule used is a TOLERANCE rule. Every block is compiled; what a legitimately partial block can produce is forgiven and nothing else is:

• forgiven — TS2304 / TS2552 / TS2503: a name or namespace the block elided.
• forgiven — TS2307 on a relative specifier (./my-kernel, ./objectstack.config.js): the reader's own file.
• forgiven — "cannot find name it / describe / process", and a third-party module that ships no declarations: the reader's ambient environment.
• counted — everything else, including TS2341 (private member), TS2339, TS2345, TS2305 / TS2724, and TS2307 on an @objectstack/* specifier. The paths map is generated from each package's own exports map, so an unresolved one means the document tells a reader to import a subpath the package does not publish.
• counted — syntax. A tolerance rule that forgave TS1xxx would forgive a typo.

The forward convention, for what tolerance cannot absolve. A block that is a bare fragment — a method-signature listing, half an object literal — produces syntax errors, and those need an explicit declaration. Proposed spelling: an info-string tag, ```ts partial. Zero blocks carry it today, so it contributes nothing to this census; the instrument reads it, and counts how many blocks would need one: 18 hand-written, 239 in CHANGELOGs.

The firing control

An instrument that finds zero failures and was never shown capable of finding one has measured nothing. Two controls run on every census, through the identical extractor, normalisation and compiler path as corpus blocks, and the run refuses to print a census if either misbehaves:

• GREEN_CONTROL must compile. Its failure means the workspace is not built — the state in which every other block would report TS2307 and the census would read as a catastrophe made of nothing.
• FIRING_CONTROL is the pre-docs(core): repair four copy-fails in PHASE2_IMPLEMENTATION.md #18712 kernel.logger block, reconstructed line-for-line from that PR's diff. It must be reported failing, must carry TS2341, must survive the tolerance rule, and must still carry its elision marker.

Observed, every run:

  GREEN_CONTROL  compiles clean — `@objectstack/*` resolves through the built exports maps.
  FIRING_CONTROL reports 5 diagnostic(s) including TS2341 at block line 13 — the pre-#18712
                 `kernel.logger` block, reconstructed from that PR's diff, is caught.
  FIRING_CONTROL also carries an elision marker, so the EXCLUSION reading SKIPS it.

Five TS2341, at block lines 13–17: one per constructor the block passed kernel.logger to.

⭐ The firing control earned its keep during this task. The instrument was first written against ts.createProgram + getPreEmitDiagnostics, then rewritten onto the tsc binary because check:parse-guard correctly forbids the parser API outside scripts/ts-parse.mjs (and createProgramChecked is the wrong tool here — it exits 3 on the first syntactic diagnostic, and blocks that do not parse are this census's subject). The first binary version reported zero diagnostics for the firing control, and the control refused the run. Cause, a measured property of the CLI: when any file in a program has a syntax error, tsc reports the syntax errors and never type-checks ANY file. One pass over this corpus returned 772 TS1xxx and not one semantic diagnostic. Hence two passes: pass 1 finds the blocks that do not parse, pass 2 re-runs over the ones that do. Without the firing control this would have shipped as "the corpus has no type errors".

Cross-check: over all 1002 corpus blocks, the binary implementation and the compiler-API one it replaced agree on every block's verdict — raw, tolerant and well-formed-and-wrong — with zero disagreements.

Wiring options, with costs, for the maintainer's letter

Nothing below is done in this PR. What it would take for the number to reach zero is stated first, because it decides everything else.

Reaching zero, hand-written stratum: 76 blocks across 31 files — 58 repairs (a block that parses and is wrong) plus 18 explicit partial tags (a block that is a signature listing or a fragment). Reaching zero, CHANGELOG stratum: impossible in principle. Those files are release-owned, compiled from changesets, and deliberately show removed APIs. Any gate whose population includes CHANGELOG.md is a gate that can never be green without rewriting published release history. ⇒ The only gate-able population is hand-written package-root Markdown.

1. Leave it unwired (what this PR does). Cost: zero CI time. The number is known only when someone runs it — the declared-not-enforced shape this family of cards is about, mitigated only by the instrument being cheap (12s) and carrying its own controls.
2. Advisory job, printing the census on every PR. Cost: it resolves through built .d.ts, so it must piggyback on a job that has already built (or pay a full build). Nothing blocks. Risk: an advisory red rides main's merge ref into every later PR until someone stanches it.
3. Shrink-only ratchet with a checked-in per-file baseline. Cost: a required job (maintainer's floor) plus a baseline artefact and its merge-driver discipline. Opening number to hold: 76 hand-written TOLERANT failures. Buys: the number can only go down, and grandfathered debt is visible rather than forgotten.
4. Gate at zero over hand-written package-root Markdown. Cost: the 76-block entry price above, paid before the gate can be armed, plus the partial tag convention landing first. Buys: the strongest guarantee, and the only one that makes the card's class genuinely closed.
5. Diff-scoped gate — only blocks a PR adds or edits. Cost: block identity across edits; today's debt is grandfathered on day one. Buys: catches the PR-docs(core): repair four copy-fails in PHASE2_IMPLEMENTATION.md #18712 class at the moment it is written, at near-zero entry price. ⚠️ Grandfathering is exactly the failure mode core: PHASE2_IMPLEMENTATION.md teaches @objectstack/core/security, a subpath the package exports in no entry #15931 demonstrated, so this option is only honest if the standing debt number is recorded somewhere that gets re-read — which is what option 3 is for. 3 + 5 together is the combination with no known hole.

Verification

• node scripts/measure-markdown-ts-blocks.mjs --self-test — 30 cases pass, 30 batteries at or above the pinned floor of 30. Roster-and-handshake shape copied from scripts/check-agent-model-declared.mjs; needs no build.
• node scripts/measure-markdown-ts-blocks.mjs — exit 0, both controls fire, 12s under the shared verify lock.
• All 26 gates scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives for this diff: 26/26 exit 0. Two were red on the first draft and drove real corrections — check:parse-guard (the parser-API rule) and check:entry-guard (the import guard).
• eslint . --no-inline-config --format json — the union, not a narrowing: 6830 files governed by eslint's own config, 0 errors, 0 warnings, at 3c64a03c4e.
• Control-character self-scan over the new file: no match.
• skip-changeset, measured with a positive control rather than assumed: the new file's basename has 0 hits anywhere under any package's built dist/; the positive control ObjectKernel has 4 hits in packages/core/dist; no package's files[] names a path outside its own directory, so a repo-root scripts/ file cannot enter any tarball.

Acceptance notes

• Not repaired, by instruction. 58 hand-written blocks parse and are wrong. A sample, all real: packages/runtime/README.md — TS2339, Property 'use' does not exist on the promise the kernel builder returns, because the front-page example chains .use(...) without awaiting it (the type in the diagnostic is a Promise parameterised by ObjectKernel; spelled out here because a raw angle-bracket fragment does not survive this surface); packages/plugins/plugin-auth/README.md — 'plugins' does not exist in type 'ObjectKernelConfig'; packages/services/service-job/README.md — 'timeout' does not exist in type 'JobScheduleOptions'. Did you mean 'timeoutMs'?; packages/drivers/driver-mongodb/README.md — 'driver' does not exist in type 'ObjectStackDefinitionInput'; packages/services/service-cache/README.md — the documented MyCache class does not implement ICacheService.
• The sharpest instance found, not filed by me: packages/spec/V3_MIGRATION_GUIDE.md tells a reader to import @objectstack/spec/hub, @objectstack/core/errors and @objectstack/core/plugin. None of the three is in its package's exports map, so the import fails for anyone who copies it. This is the check-published-readme-exports family arriving through a document that gate's population does not reach — V3_MIGRATION_GUIDE.md is not in @objectstack/spec's files[]. Reported to the dispatching seat with dedupe words rather than filed here, to keep this PR a census.
• Noted, not filed: the census counts packages/*/CHANGELOG.md because they are package-root Markdown, and they dominate the raw number (720 of 1002 blocks). They are structurally unrepairable in a code PR. Successor: whoever writes the wiring letter — the stratum split exists precisely so that reader does not have to re-derive it.
• No census snapshot is committed. A number checked into a file is a number that rots; the instrument regenerates it in 12 seconds. The census lives in this PR body and in the report comment on [finding] packages/core/PHASE2_IMPLEMENTATION.md's fenced TypeScript blocks are in no tsc program — a block that has NEVER compiled survived two sweeps, and the gate #15931 proposed would not have caught it #18715.
• Population note: the card's example glob is packages/*/*.md, which misses nested package roots such as packages/plugins/plugin-auth/. The instrument measures every package root and reports the card's literal glob as a named sub-stratum, so both readings are available and neither is assumed.

_{⚠️ Line count corrected by the dispatching seat, not by the author. This body first read 「918 lines」, which was the count at the first commit, before the two-pass tsc rewrite; the landed file at 3c64a03c4e is 1086 lines (git show … | wc -l, taken by the seat). The author found the slip after the single permitted body write and reported it rather than patching, because the role file allows a dev exactly one body write in the POST /pulls stroke and routes later changes through its report to the seat. ⛔ Nothing else in this body was changed, and everything else in it was re-verified by the author at the landed head.}

---

Generated by Claude Code

[huangyiirene]

Pre-landing readings for PR #18751, written 2026-09-17T19:03Z — ⭐ including two REQUIRED contexts that are SKIPPED, and why that is not a gap.

domain:engine execution seat, session_01CqmCgU5RGDoJYhHUMVp2af. ACCEPT and the full review are on card #18715.

check	reading
① in-seat clause-② review	⛔ none owed — Clause-②: no, and --pair confirms both carriers agree with no widening tell
② check-clause2-carriers.mjs --pair 18751	exit 0, re-taken at this stroke
③ CI on 3c64a03c4e	31 names · 0 pending · 0 non-green
governed-surface predicate (--pr 18751)	0 of 1 path ⇒ ordinary queue landing

⚠️⚠️ Build Core and Temporal Conformance (live PG + MySQL) read skipped, and both are REQUIRED contexts

A landing decision taken on 「0 non-green」 alone would have passed two required contexts unmeasured. It is not a gap, and the roster says why in its own words — check-expected-skips' CORE_REASON:

gated on ci.yml's filter job core output; a diff outside the core path set skips it on the PR head, and the merge-queue build widens every output to true and runs it on the merged tree

Verified against the filter contract itself (ci.yml:173-179): the core path set is packages/**, examples/**, apps/!(docs)/**, package.json, pnpm-lock.yaml, tsconfig.json. ⇒ scripts/** is not in it, and this PR changes exactly one file under scripts/.

⇒ ⭐ The two contexts skip by design on the PR head and their verdict is taken in the queue build, on the merged tree. ⛔ Landing does not skip them; it is where they run.

The other skips are roster members too: Check PR Size and Auto Label (the labeled-event re-fire), Check Changeset (this PR carries skip-changeset, measured with a positive control), Packed-tarball smoke (opt-in), Console Pin Gate and Build Docs (their own filter outputs), and the raw matrix-template check name (the Dogfood Regression Gate shard row, whose literal spelling carries an un-expanded Actions expression — reproduced here with the brace syntax elided, because post-stamped correctly refuses a double-brace opener it does not recognise) / Dogfood Verify CLI — the raw matrix template name a job reports before expansion, while the aggregate Dogfood Regression Gate runs if: always() and reads success.

⏹️ ⛔ This card does NOT close on merge: the PR is Part of #18715, deliberately. At landing the seat strips pm:dispatched in the same stroke — a Part of card does ⛔ not auto-close and would otherwise count as in-flight forever — and moves it to needs-user-decision with the four-axis analysis for the wiring letter.

⇒ Going ready and into the merge queue (SQUASH). This seat follows it to MERGED.

---

Generated by Claude Code