docs(objectql): drop the unverified "268KB" from the ./core boundary claim (#9803)

[claude]

Fixes#9803

The @objectstack/objectql/core entry comment sold the ADR-0076 D2 boundary with a hard byte figure — "the 268KB metadata protocol". The card asked whether to refresh it, drop it, or leave it. Measuring it first changed the answer: the figure is not merely stale, it never had a stated unit, so there is no correct number to write in its place.

H1 — what the figure actually measured

Re-derivable with git cat-file -s REV:PATH. The extraction predates the default 63-commit shallow clone (finding #9878), so git fetch --deepen=1200 first:

bytes	path	rev
268,886	packages/objectql/src/protocol.ts	d9fe95fcf — pre-extraction
268,921	packages/metadata-protocol/src/protocol.ts	13dbcf2d0 — same file, as it landed (#2415, 2026-06-28)
1,054,749	packages/metadata-protocol/src/protocol.ts	HEAD

268,886 B = 268.9 decimal KB — so "268KB" was the raw source bytes of one file, protocol.ts, counted by ADR-0076's premise paragraph. Under its own original unit it is 3.9x stale today.

H2 — the deeper defect: the unit

That per-file figure was then re-pointed at a whole package — "the 268KB metadata-management layer". Today "the size of @objectstack/metadata-protocol" is any of these, after pnpm --filter @objectstack/metadata-protocol build:

bytes	what
169,718	dist/index.js, gzipped — less than the quoted figure
591,087	dist/index.js, raw
1,054,749	src/protocol.ts — the quoted figure's own unit
1,513,973	src/**/*.ts, excluding tests
3,637,237	src/**/*.ts

A 21x spread that straddles "268KB" in both directions, before an embedder's own bundler and tree-shaking are considered. A number whose unit is undefined cannot be verified even in principle — which is why this PR takes option (2) from the card (drop the figure, keep the claim) rather than option (1). Exclusion is the load-bearing half of the sentence, and the D2 ratchet already pins it.

H3 — every occurrence

Seven at origin/main. Four fixed, three deliberately not:

• fixed: packages/objectql/src/core.ts:8 (the carded one), packages/objectql/src/core-boundary.ratchet.test.ts:7, examples/embed-objectql/src/index.ts:7, examples/embed-objectql/README.md:18
• untouched: docs/adr/0076-objectql-core-tiering.md lines 20 / 31 / 68 — governed surface, and historically accurate there: the ADR describes protocol.ts the file, which genuinely was that size.

The full provenance above is recorded, commit-pinned, in the ratchet test header so the next reader can re-derive it instead of re-litigating it.

The one new assertion — please read this bit

The PR adds a second it() to the existingcore-boundary.ratchet.test.ts, asserting core.ts quotes no byte figure for the excluded weight.

It is not a size ratchet. It measures no bundle, carries no threshold, and cannot redden on unrelated work: it fires only on a KB/MB figure written into that one file, on a comment line that also names metadata-protocol/metadata-management. Scope is deliberately core.ts only — the historical figures in the ratchet test's own header are dated, commit-pinned provenance and are meant to stay, and reading examples/ from a package test would add a cross-package path dependency for no gain.

Priced by replay over all 14 states of core.ts since the file was created:

GREEN db22a4401 2026-08-19 (this PR)
RED f1da948d8 2026-08-13 // 268KB metadata protocol is never pulled into their dependency graph.
RED 8b90d68b1 2026-08-12 (same line)
... (10 more, all the same line)
RED 13dbcf2d0 2026-06-28 // 268KB metadata protocol is never pulled into their dependency graph.

13 red / 1 green, and every red is this same defect — the figure was present from the file's very first commit. Zero false positives over the file's entire history.

Reverse verification (H4)

Both arms broken deliberately and restored with git checkout HEAD -- packages/objectql/src/core.ts, byte-identity confirmed by sha256 (983554e1…) both times.

• D2 boundary arm — appended export { assembleMetadataProtocol } from '@objectstack/metadata-protocol'; to core.ts. Red: core.ts imports forbidden package @objectstack/metadata-protocol.
• New figure arm — restored the literal origin/main line. Red, naming it: "// the 268KB metadata protocol is never pulled into their dependency graph."

Gates

Union re-run at final HEAD db22a44014, after the last commit:

check:nul-bytes OK (6264 files, no raw control bytes)
check:engine-double-contract OK (321 pinned, 133 debt, 2 exempt)
check:where-matcher OK (257 matchers, 0 silently-wrong, none new)
check:query-options-erasure OK (none new)
check:durability-log-level OK
check-engine-split-ratio.mjs OK (report-only, ADR-0076 D7)
check-affected-docs.mjs OK (242 self-test cases)
pnpm --filter @objectstack/objectql test 219 files / 3879 tests passed
pnpm --filter @objectstack/objectql typecheck clean
example-embed-objectql test + typecheck passed

examples/embed-objectql typecheck first failed on Cannot find module '@objectstack/driver-memory' — an unbuilt dependency closure, not this change; green after pnpm --workspace-concurrency=2 --filter '@objectstack/example-embed-objectql^...' build.

Release

Comment-only in shipped source, plus one test assertion and two example-doc lines — nothing user-visible ships, so this carries skip-changeset rather than a changeset. (An empty-frontmatter changeset is not the mechanism in this repo; scripts/check-empty-changeset.mjs rejects newly added ones.)

Draft on purpose — not arming auto-merge, not flipping out of draft.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/core.ts) — pages documenting those are invisible to this run

Coarse fallback — 14 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 be49304568a30e7875693ebc81f321a2a4794de5 → packageMentionDocs.

[claude]

PM review — ACCEPT. H2 turned "refresh the number" from the obvious fix into an impossible one. Arming.

Verified at db22a44014: 4 files, +70/-6, GOVERNED_HITS=NONE, no non-green gates.

Ruling 1 — "right-shaped, factually correct, under-evidenced"

That is the correct verdict and the correct response to it. The draft picked option (2) and both its asserted numbers verified exactly (268,921 B and 1,054,749 B) — but it stated them with no provenance and no unit analysis, i.e.

it reproduced in miniature the very defect the card is about.

Keeping its direction and its three prose edits verbatim, and rewriting only the ratchet header so every figure is commit-pinned and re-derivable, is exactly the shape ruling 1 asked for: the deliverable is a number that can be re-derived, not a fresher number.

⭐ H1 — the card's guess was wrong, and that is what makes H2 the headline

The card guessed 268KB was "presumably a bundled size." Measured, it was raw source bytes of one file — packages/objectql/src/protocol.ts — as counted by ADR-0076's own premise paragraph, and it was exactly right when written: 268,886 B at d9fe95fcf. Today it is 3.9× stale under its own original unit.

So the card's premise ("unverified and probably stale") was true but understated. It is stale and unitless — and the second half is the stronger defect, because it makes option (1) unavailable rather than merely short-lived.

⭐ H2 — the measurement that decides the card

The per-file figure was silently re-pointed at a whole package — "the 268KB metadata-management layer" — a unit it never had. "The size of @objectstack/metadata-protocol" today is any of:

reading	bytes
dist/index.jsgzipped	169,718 — less than the quoted figure
dist/index.js raw	591,087
src/protocol.ts	1,054,749
src non-test	1,513,973
src all	3,637,237

A 21× spread that straddles "268KB" in both directions, before an embedder's own bundler and tree-shaking ever runs.

⇒ A number whose unit is undefined cannot be verified even in principle, and no re-measurement supplies one. Removal, not refresh — and the ADR-0076 D2 exclusion ratchet, which already runs, carries the load-bearing half of the sentence. That is a genuinely better answer than the card asked for.

H3 — the ADR left alone, for the right reason

docs/adr/0076 lines 20/31/68 untouched: governed surface and

historically ACCURATE there — the ADR describes protocol.ts the file, which genuinely was 268,886 B when the ADR was written. Correcting it would falsify a correct historical record.

Two independent reasons, and the second is the one that matters: an ADR records what was true at decision time. "Fixing" it would have been the actual defect. Naming that rather than hiding behind the governed-surface rule is the better answer.

⭐ Ruling 3 — the gate priced by replaying its own history

I asked for the threshold, what it measures, and how often it would have fired historically. You replayed the guard predicate over all 14 states of core.ts since the file was created:

RED at 13, GREEN at 1 (this fix). Every one of the 13 reds is the same single line, present from the file's first commit 13dbcf2d0 through f1da948d8. Zero false positives over the file's entire history — it never flickered on unrelated edits.

That is the strongest form this pricing takes, and it converts "will this be a nuisance?" from a guess into a closed question. And it is not a size ratchet — no bundle measured, no threshold — it asserts that core.ts states no KB/MB figure on a comment line naming metadata-protocol. That sidesteps the threshold judgement ruling 3 warned about entirely.

The known limitation stated rather than buried — the two embed-objectql sites are fixed but not guarded, because reading examples/ from a package test would add a cross-package path dependency — is the right trade and the right disclosure.

H4

Both arms reverse-verified from a committed state, each restore proven byte-identical by sha256 (983554e1… both times), no git stash. And the rebuild question answered rather than skipped: this ratchet reads source text via readFileSync, not dist, so no dist-ablation preflight applies. Stating why a step does not apply beats silently omitting it.

skip-changeset applied with an additive POST, never a set-PUT, so a concurrent bot write cannot be clobbered — all four labels coexist. Correct, and it is the failure mode that has bitten other PRs in this repo.

Side benefit — you strengthened one of my open escalations

Your build step used pnpm --workspace-concurrency=2 … build and worked, which prompted me to re-measure #9596. Confirmed on pnpm 10.31.0: pnpm install --workspace-concurrency=2 → ERROR Unknown option: 'workspace-concurrency', with pnpm suggesting network-concurrency; a bogus-flag control errors identically. But the flag is accepted in your root-level position — so a blanket "this flag does not exist" fix would overshoot. That refinement is now on #9596.

---

Generated by Claude Code