docs(types): compile the types README's 7 blocks and drop its ledger entry - #8038
Merged
Merged
Conversation
…entry Part of objectui#5174 — batch 21 of the `UNGATED_DOCS` burn-down. `packages/types/README.md` leaves the ledger and all 7 of its ts/tsx blocks now compile against the built types. Two of them were PARSE failures: the discriminated-union excerpt ended on a dangling `|` before a comment, and the composable-nesting example used bare elision brackets in two slots. Both are fence shape, repaired by writing the real values rather than by declaring a fragment. The two semantic failures were ambient names — the `DataSource` excerpt and the Tailwind `ButtonSchema` example now carry real self-imports, and the excerpt is pinned to the shipped interface so it cannot drift silently. No `packages/**` source touched, no public type widened, no gate loosened, and no new fragment marker: declared fragments stay at 158, so all 7 blocks earn their coverage by compiling. The gate file's only change is the two lines of that one entry. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr
Contributor
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
Contributor
|
Standing-down note — Generated by Claude Code |
This was referenced Sep 6, 2026
baozhoutao
marked this pull request as ready for review
September 6, 2026 12:33
This was referenced Sep 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #5174 — batch 21 of the
UNGATED_DOCSburn-down.packages/types/README.mdleaves the ledger and all 7 of its ts/tsx blocks nowcompile against the built types. The gate file's only change is the two lines of
that one entry.
Notation, read this first
This repository has measured that GitHub's body sanitizer deletes tag-shaped
fragments even inside backticks and fenced blocks, which is how a before/after
table can render as though nothing changed. So generic parameters are spelled
out in words below — "a Pick of DataSource over find and create", "a Promise of
QueryResult" — rather than in their real angle-bracket form. The README itself
carries the real spellings; this page does not.
Concurrency
Batch 20 (PR #8025) merged while this batch was measuring.
origin/mainmoved from
6891277toa9e6f04b4at 11:38:59Z. This branch had no commits ofits own yet, so it was fast-forwarded onto the new base rather than carrying a
merge commit, and the census, every gate, every test and all ten probe legs were
taken on
a9e6f04b4afterwards. The census table is byte-identical on the twobases, and so is the pick.
All 10 open pull requests' file lists were read over the REST files endpoint and
each count reconciled against that PR's own
changed_files: 8032/7, 8030/8,8028/5, 8027/3, 7749/4, 7685/67, 7058/24, 7054/2, 7053/2, 5400/1048. #5400's
1048-file list was paged to exhaustion (11 pages) because the endpoint pages at
100 and a truncated list renders as a confident absence. No open PR touches
packages/types/README.mdor the gate file. The only README any open PRtouches at all is
packages/auth/README.md(PR #7685), which is excludedanyway.
packages/types/src/field-types.tsand six
packages/types/src/__tests__/files. It does not touch this README, soit is not an exclusion, but it is the one open change that could move the
shipped types this page is now checked against.
Live E2E (informational)is red on every branch today for an upstream reason(objectui#7990 / objectstack#16186), not because of this diff.
Ledger arithmetic
a9e6f04b47a06a9673UNGATED_DOCSentriescheck:readme-exports)Both rows were MEASURED, not computed. The base row is a real
pnpm check:doc-snippetsrun (probe M0) with both changed files checked out atorigin/mainbytes — on-disk hashes proven equal to theorigin/mainblobs(
8cba9476…and30beb8aa…) — and restored afterwards under a trap. The basecheck:readme-exportsrow is its own run against base README bytes.Programmatic diff of the two
UNGATED_DOCSobjects — both imported as OBJECTS,never diffed as text: removed =
['packages/types/README.md'], added =[],reason-changed =
[], key order preserved for survivors = true.git diff --numstaton the gate file is exactly0 2. On the branch: typesentries 0,
packages/NAME/README.mdentries 15 (from 16), control'packages/auth/README.md'1.The strictness region — the
Fence scanningbanner line to EOF, 1178 lines onboth sides — hashes to
f46b5662ba336f026bca3a0003e0b7979789d48d0291fa5760be7d23c8ed0160onorigin/mainand on the branch. Re-measured here, not inherited; it is thevalue batches 15 through 20 recorded, as it must be with nothing landing in the
region since.
Census and the rung that decided
Re-taken on this branch's base through the gate's exported
analyze()/compileSnippets()over every non-excluded ledger candidate — once on theoriginal base
6891277(17 entries, 14 candidates) and again ona9e6f04b4after the fast-forward (16 entries, 14 candidates). Both runs give the same
table and the same pick.
Rung 1 (larger measured debt: blocks, then diagnostics) DECIDES OUTRIGHT:
types ties on blocks with layout and is ahead of it on diagnostics. Rung 2 was
never reached.
The dispatch's assumption A1 is CONFIRMED: every block and diagnostic total
matches the batch-20 census exactly. Two per-code figures differ from it and are
reported rather than smoothed: react-runtime reads 7 distinct codes here,
not 6, and plugin-ai reads 3, not 2. That is batch 20's own finding about
this census holding — per-code splits move with the shape of the compiler
program while the totals do not — and neither column is read by rung 1, which
decided outright.
Exclusions re-verified against GitHub on this base, not inherited: the root
README.mdis not apackages/NAME/README.md;packages/permissions/README.mdwas batch 20's and has now landed, so it is out of the ledger entirely rather
than merely reserved;
packages/auth/README.mdis held by open draft PR #7685(67 paths, read again here);
packages/plugin-chatbot/README.mdis deferred byan earlier ruling on the card.
A4 is CONFIRMED and it mattered: every block this diff repaired imports from
@object-ui/typesitself, so all seven now resolve against this package's ownbuilt
dist/index.d.ts(the gate's resolution control names that exact file).The forced build came first.
What the 6 diagnostics were, and what each repair did
Two of the seven blocks never reached the semantic phase, which made this a
fence-shape job before it was a type job — and, as the dispatch predicted, the
two parse-failed blocks were hiding semantics nobody had ever seen. Both turned
out clean once they parsed. Nothing on this page was a documented-API lie: the
findandcreatesignatures it quotes match the shippedDataSourceexactly.QueryParamsandQueryResult, and a hand-writtenDataSourceinterface that nothing compared with the shipped one — TS2304 x2DataSourceExcerptand pinned with a Pick of DataSource over find and create, so it is now checked against the interface it quotesButtonSchema— TS2304 x1pipe slash-star 50+ more star-slash semicolon— the block never reached the semantic phase, and the localtype AnySchemait declared shadowed the shipped union rather than referring to itAnySchemaplus the three named members; the three-member slice is now a separate alias and is ASSIGNED toAnySchema, which is what proves the slice really is part of the shipped union. Therenderfunction and its two case comments are unchangednavand the innerchildren, each a spread with no operandNavLinkwith the label and href it requires, and a nested node. The two leaves are lifted out and ANNOTATED (SidebarSchema,ContainerSchema) so the nesting is checked against the shipped types instead of being absorbed byBaseSchema's index signature — probe P2 shows that annotation is load-bearingThe remaining three blocks (Basic Example, Advanced Example, Type Narrowing)
already compiled and are untouched.
No
packages/**source touched, no public type widened, no lenient alias added,no gate loosened, and no new fragment marker — declared fragments stay at
158, so all 7 blocks earn their coverage by COMPILING.
An overclaim this batch wrote and then removed
draft of the Protocol Agnostic block carried the comment "the
extendsis whatkeeps the quotation honest: it stops compiling the day either signature
drifts." Probe P7 was written to prove that and falsified it: with the
parameter type changed from a Partial of T to a bare T the gate stayed green,
because TypeScript compares method declarations bivariantly and
DataSource'sown default type parameter is
any, which collapses the two spellings anyway.A lab sweep over six variants then measured what the pin does and does not
catch:
The comment was rewritten to claim exactly those two and nothing more, and P7
was replaced by two probes that the pin really does answer (P7b and P8 below).
Shipping the original wording would have put an unverifiable claim on a
published page — the same defect class this gate's
VERIFICATION_CLAIMruleexists to stop one line lower down.
Probes — one base measurement and nine probes, each predicted in writing first
Predictions were written to the scratchpad (
5174-b21-PREDICTIONS.md) at commitefbb2300awith a clean tree, before any leg ran; the P7b / P8 amendment wasappended after P7 was falsified and before either of those two ran, and it says
so in the file. Every mutation is proven on disk by occurrence counts of BOTH
the injected and the deleted text plus
git hash-objectagainst the HEAD blob;every restore is
git checkout HEAD -- ABSOLUTE_PATH, never a bare checkout,proven by an empty
git diff HEAD; every leg runs under atrapwith absolutepaths. No rebuild is owed on any leg, and that was reasoned rather than assumed:
the gate reads the mutated bytes straight from the working tree and no leg
touches
dist/.210 covered … 17 ungated,700 — 542 to compile,542 of 542 judged, 0 failedorigin/mainblobs210 covered (108 …), 17 ungated,700 — 542 to compile,542 of 542 judged, 0 failed; numstat vs HEAD exactly2 0, README proven untouched, restored gate file byte-identical to theorigin/mainblob. The entry is what suppressed the verificationhreffrom the NavLink placeholder this diff added549 of 549 judged, 1 failed,README.md:277:9 TS2741: Property 'href' is missing in type … but required in type 'NavLink'— proving theSidebarSchemaannotation is load-bearing rather than absorbed by the index signature248:19 TS1110,272:37 TS1109,273:44 TS1109(2 blocks failed to parse); semantic221:35and221:57 TS2304(QueryParams, QueryResult) and232:15 TS2304(ButtonSchema).489 real, 0 wrong-path, 0 fabricated; mutated exit 1,488 real, 0 wrong-path, 1 fabricated, namingpackages/types/README.md:2361 block(s) failed to parse and were NOT semantically checked,README.md:254:76.README.md:293:21 TS1109: Expression expected,1 block(s) failed to parse and were NOT semantically checked1 failed,README.md:225:11 TS2430: Interface 'DataSourceExcerpt' incorrectly extends … The types returned by 'create(...)' are incompatible1 failed,README.md:225:66 TS2344: … does not satisfy the constraint 'keyof DataSource'. Did you mean "create"?Nine of ten legs ended in the predicted direction. The tenth, P7, is the reason
the shipped comment is narrower than the one first written. No probe leg was a
no-op: every mutation moved the blob hash and every restore returned an empty
git diff HEAD.Gates — all at
7a06a9673, clean tree, nothing pushed afterExit codes captured by redirect-then-capture, never read through a pipe; each
row quotes the gate's own verdict line.
pnpm check:doc-snippetsScanned 227 document(s): 211 covered (109 of them hold a ts/tsx block), 16 ungated·Covered blocks: 707 — 549 to compile, 158 declared fragment(s)·549 of 549 block(s) judged, 0 failed·Every covered documentation snippet compiles against the built types.pnpm check:doc-fencesevery TypeScript block in 227 document(s) is fenced ts/tsx/typescriptpnpm check:readme-exports489 of them self-imports judged (489 real, 0 wrong-path, 0 fabricated)pnpm check:doc-typesEvery documented component type is registered.node scripts/check-doc-links.mjsLinks are valid across 17 scan roots.pnpm check:doc-example-readersOK 80 documented symbol(s), 3947 call site(s)pnpm check:control-bytesOK (scanned 6448 tracked text file(s); skipped 85 binary); plus a manual C0/DEL scan of both changed paths withgrep -naP, no hitnode scripts/check-node-esm-load.mjs --force-buildProvenance leg: 37 of 37 gradable entries were built by this tree.(its threeERR_UNKNOWN_FILE_EXTENSIONlines are the gate's own by-design entries)pnpm type-check:scriptsnode scripts/check-changeset-presence.mjs2 file(s) changed, 0 of them published source of a package the release covers … no changeset is owedcheck-governed-queue-guard.mjs --test(both paths)NOT GOVERNED — 2 path(s) checked against 5 governed surface(s); none matchedThe build came first and was FORCED:
turbo run build --filter=./packages/* --concurrency=2 --force,39 successful, 0 cached, and then again insidecheck-node-esm-load.mjs --force-build(
43 successful, 0 cached). Forced because turbo shares one cache across everyworktree of a checkout and that gate's provenance leg refuses artifacts a
different tree produced — the hazard batch 20 hit. It did not fire here: the
provenance leg was green on the first run, at 37 of 37 built by this tree. Every
reading quoted above was taken after that force-build.
No
skip-changesetlabel was applied and none is owed: this repository declareswith an empty-frontmatter changeset rather than that label, and the presence
gate says nothing is owed, so nothing was labelled at all.
Tests:
pnpm exec vitest runover every test file that reads either changedpath, derived with
git grep -lon both paths and not guessed — 15 files,Test Files 15 passed (15) / Tests 568 passed (568). That set includesscripts/__tests__/check-doc-snippet-types.test.ts, which this diff's own editedscript owes, and
scripts/__tests__/check-readme-exports.test.ts, which namesthis README path by name. Owning package:
pnpm exec vitest run packages/types/—Test Files 131 passed (131) / Tests 2418 passed (2418);pnpm --filter @object-ui/types type-checkexit 0,its output echoing
tsc --noEmit && tsc -p tsconfig.examples.json && tsc -p tsconfig.test.json, so the test tsconfig really is included.named
scripts/__tests__/check-readme-exports.test.tsas a live pin on thisREADME — CONFIRMED, it names the path. It also offered
scripts/__tests__/doc-version-claims.test.ts"if it names the path". It doesNOT:
git grep -lforpackages/types/README.mdacross the tree returnsexactly two files,
check-readme-exports.test.tsandcheck-readme-exports.mjs, and nothing else. So this page has one live test pin,not two, and the 15-file reader set is one smaller than batch 20's 16 for that
reason.
Lint, as a declared narrowing with its three evidence items:
pnpm linthere is
turbo run lintper package, so the repository-wide sweep is CI's run.The narrowed run over exactly this diff is
pnpm exec eslint --no-inline-config --format jsonon both paths — 2 entries,0 errors; eslint's own answer for the README is
File ignored because no matching configuration was supplied, so the real lint surface of this diff isthe one
.mjsat 0 errors / 0 warnings. (1) The population eslint wouldotherwise judge is 4356 files by its own count. (2) That run exits 1 with 93
errors and 12145 warnings, all of them in files this diff does not touch and all
pre-existing on the base — reported rather than smoothed, so nobody reads the
narrowed green as a statement about the repository. (3)
eslint.config.jsdeclares no
project/projectService/parserOptions.project(grep count0), so type-aware linting is off and this diff cannot move the verdict on any
untouched file.
Readers of the changed paths
Derived with
git grep -lon both changed paths, then run — not assumed.scripts/check-doc-snippet-types.mjs— the gate itself, which now COMPILESthis page instead of excusing it (P1 proves the entry was what suppressed it).
scripts/check-doc-fence-languages.mjs(check:doc-fences) — reads everyfence in this README; green at the final commit over 227 documents.
scripts/check-readme-exports.mjs— reads this README's self-imports; provenlive by P4. This diff ADDS self-imports (478 to 489 across the repository), so
it hands that gate more to check than it had. Six of the seven blocks imported
something already; the two parse-failed ones imported nothing, which is part of
why the page's shape survived unnoticed.
scripts/__tests__/check-readme-exports.test.ts— the only test file namingthis README path (A3 re-derived; see the correction above); green inside the
15-file run.
Out of scope, filed rather than repaired here
objectui#8037, unassigned and unlabelled, two measured prose defects on this
same page that no gate in this family reads, so neither is repaired here: the
architecture diagram names the
@objectstack/specfloor as v15.x whilepackages/types/package.jsondemands^17.0.0(installed 17.2.0); and the pagecarries two separate
## Linkssections that disagree on the documentationhost. Neither lives in a ts/tsx block, so both are outside this batch's licence.
This PR is a DRAFT and stays a draft: this seat does not flip ready, does not
enable auto-merge, and touches no labels or assignee.
🤖 Generated with Claude Code
https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr
Generated by Claude Code