`@objectstack/objectql/core`'s "268KB metadata protocol" figure is unverified at HEAD — the structural claim holds, the number does not reproduce

[os-steve]

Found while sweeping multi-entry exports maps for unmeasured weight/safety subpath claims (H4 of #9772, PR #9802). Filed rather than folded in because the number needs judgement, not a mechanical correction — #9772's brief was "fold in only what is unambiguously false by your own measurement, card anything needing judgement".

The claim

packages/objectql/src/core.ts, lines 3-8 — the header of the ./core subpath entry:

Lean engine entry (ADR-0076). Exposes the data engine surface [...] WITHOUT the kernel plugin (ObjectQLPlugin), the kernel factory, or any metadata management (@objectstack/metadata-protocol). Embedders that want only the engine (e.g. a thin gateway) import from @objectstack/objectql/core so the 268KB metadata protocol is never pulled into their dependency graph.

What I measured

Static import-graph walk over packages/objectql/src from each entry, value imports only (import type excluded), at main = 11b779e0f:

entry	modules reached	src bytes	value import of @objectstack/metadata-protocol?
.	39	1,560,047	yes
./core	31	1,326,133 (85.0%)	no

The structural half of the claim is true and is the load-bearing half. ./core genuinely does not pull @objectstack/metadata-protocol into its graph, and the ADR-0076 D2 boundary ratchet the comment names is what keeps it that way. Nothing here suggests the entry is misdescribed the way @objectstack/lint's ./runtime was.

What does not reproduce

The 268KB figure. packages/metadata-protocol/src is 3,622,216 bytes today. That does not falsify the number — it is presumably a bundled size from the ADR-0076 round, and comparing like for like needs metadata-protocol built and its dist bundle measured, which I did not do (out of scope for #9772, and it is a build I had no reason to pay for on a prose card).

So the honest status is unverified, and probably stale: a hard byte figure written once at authoring time, in a comment whose whole rhetorical weight rests on it, with nothing in CI that re-measures it. That is the same shape #9772 was filed about — the difference is that there the surrounding claim was false too, and here it is not.

Suggested disposition (not a recommendation to act now)

Three options, cheapest first:

1. Re-measure and update the figure. Build metadata-protocol, stat the published bundle, write today's number. Cheap, and stale again in a month.
2. Drop the figure, keep the claim. "so @objectstack/metadata-protocol is never pulled into their dependency graph" says everything the sentence needs and is exactly what the ADR-0076 D2 ratchet already enforces. A claim a gate holds true does not need a number a gate does not.
3. Leave it. It is a comment on an entry whose substantive claim is correct and machine-checked; a stale order-of-magnitude figure misleads far less than ./runtime's did, because acting on it lands the reader somewhere correct anyway.

My weak preference is (2) — it removes the only unpinned assertion in the sentence at zero cost and leaves the pinned one standing. But this is a judgement about how much precision a doc comment owes, which is why it is a card and not a commit.

Not in scope of this card

No change to ./core's contents, the exports map, or the ADR-0076 D2 ratchet. This is about one figure in one comment.

Refs: #9772 · #9707 · PR #9802

[os-steve]

Claiming this card.

• Session ID: session_01XqDQYVU5smx29ts9pAErja
• Branch: claude/issue-9803-objectql-core-figure (pushed)
• Container & model: S, mode:subagent, model: opus

Working H1 (what did 268KB measure) first, since it decides whether any number ships at all; then H3 re-verification, then the H2/H4 sweeps.

---

Generated by Claude Code

[os-steve]

Claim supplement — widened file surface (H2 sweep result).

The figure is not confined to the carded comment. It appears in four code/example sites, all attached to the same claim:

file	line
packages/objectql/src/core.ts	8 (the carded one)
packages/objectql/src/core-boundary.ratchet.test.ts	7 (the ratchet's own header)
examples/embed-objectql/src/index.ts	7
examples/embed-objectql/README.md	18

Fixing one would leave three copies disagreeing, which the dispatch names as worse than today. Taking all four under the bounded in-place exemption: same defect class, same figure, mechanical fix, no competing claim on any of the files (searched: nothing open), same gate family.

docs/adr/0076-objectql-core-tiering.md (lines 20/31/68) also carries it and is not being touched — governed surface, and its usage is historically accurate there (it describes protocol.ts the file, which genuinely was that size).

---

Generated by Claude Code

[claude]

⚠️ PM: the previous dispatch on this card died mid-run — work survives on disk

Recording this on the card so the state is not mistaken for progress. The agent dispatched by session session_01XqDQYVU5smx29ts9pAErja terminated without opening a PR, so this card has looked pm:dispatched while nothing was moving.

Measured state of claude/issue-9803-objectql-core-figure:

• pushed to origin: yes
• own commits vs origin/main: (none) (0 commits, 4 files in progress)
• PR: none was ever opened — which is why it was invisible in the PR list

Any uncommitted files have been preserved to /home/user/dead-run-salvage/9803/ (tracked.patch + verbatim copies of untracked files). Nothing was lost, and nothing was committed on the dev's behalf — the PM does not write code.

⛔ git stash was not used at any point: the stash stack lives in the common .git dir and is shared across every worktree of this repo, so salvaging through it would have handed this work to whichever agent popped next.

Re-dispatching now as a resume, not a restart.

---

Generated by Claude Code

[claude]

{
 "issue": 9803,
 "status": "done",
 "branch": "claude/issue-9803-objectql-core-figure",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/9909",
 "premise_still_valid": true,
 "summary": "RULING 1 VERDICT ON THE DRAFT: right-shaped, factually correct, under-evidenced — kept and built on, not discarded. It chose the card's option (2) (drop the figure, keep the claim), which measurement confirms is the only defensible option, and both numbers it asserted 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. Kept its direction and its three prose edits verbatim; rewrote the ratchet header so every figure is commit-pinned and re-derivable, and added the measurement that actually decides the question (H2, below). No new number ships in prose anywhere: the figure is gone from core.ts and both embed-objectql sites, and a second assertion on the EXISTING ratchet test keeps it from growing back into core.ts. Premise held and deepened: the card said 'unverified and probably stale'; it is stale (3.9x under its own unit) AND unitless, which is the stronger defect because it makes option (1) — refresh the number — unavailable rather than merely short-lived.",
 "h1_measured_figure": {
 "what_268KB_actually_measured": "raw source bytes of ONE file, packages/objectql/src/protocol.ts, as counted by ADR-0076's premise paragraph",
 "exact_command": "git fetch --deepen=1200 && git cat-file -s REV:PATH (extraction predates the 63-commit shallow clone, finding #9878)",
 "evidence": [
 "268,886 B packages/objectql/src/protocol.ts @ d9fe95fcf (parent of the extraction commit)",
 "268,921 B packages/metadata-protocol/src/protocol.ts @ 13dbcf2d0 (same file as it landed; 2026-06-28, #2415, 'extract metadata-protocol + add lean ./core entry (ADR-0076 Step 1)')",
 "1,054,749 B packages/metadata-protocol/src/protocol.ts @ HEAD (wc -c)"
 ],
 "how_far_off": "268,886 B = 268.9 decimal KB, so the figure was exactly right when written. Under its own original unit it is 3.9x stale today.",
 "verdict": "The card guessed it was 'presumably a bundled size'. It was not — it was raw source bytes of a single file. That guess being wrong is what makes H2 the headline."
 },
 "h2_unit_decision": {
 "unit_the_fix_adopts": "NONE — no byte figure ships, deliberately.",
 "why": "The per-file figure was re-pointed at a whole package ('the 268KB metadata-management layer'), a unit it never had. 'The size of @objectstack/metadata-protocol' today, after `pnpm --filter @objectstack/metadata-protocol build`, is any of: 169,718 B (dist/index.js gzipped — LESS than the quoted figure) / 591,087 B (dist/index.js raw) / 1,054,749 B (src/protocol.ts) / 1,513,973 B (src non-test) / 3,637,237 B (src all). A 21x spread that straddles '268KB' in BOTH directions, before an embedder's own bundler and tree-shaking. A number whose unit is undefined cannot be verified even in principle, and no re-measurement supplies one — so removal, not refresh.",
 "what_carries_the_claim_instead": "The ADR-0076 D2 exclusion ratchet, which already runs and is the load-bearing half of the sentence."
 },
 "h3_occurrences": {
 "total_at_origin_main": 7,
 "fixed": 4,
 "fixed_list": [
 "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"
 ],
 "deliberately_untouched": "docs/adr/0076-objectql-core-tiering.md lines 20/31/68 — governed surface (ruling 4), 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."
 },
 "h4_ratchet_red_green": {
 "note": "The pre-existing D2 ratchet is not new in this PR; the PR adds one assertion to it. Both arms reverse-verified from a COMMITTED state.",
 "arm_1_d2_boundary": "MUTATION: appended `export { assembleMetadataProtocol } from '@objectstack/metadata-protocol';` to core.ts. RED as predicted: 'core.ts imports forbidden package @objectstack/metadata-protocol' (Test Files 1 failed, Tests 1 failed | 1 passed).",
 "arm_2_new_figure_guard": "MUTATION: restored the literal origin/main line. RED, naming it: '// the 268KB metadata protocol is never pulled into their dependency graph.' (Test Files 1 failed, Tests 1 failed | 1 passed).",
 "green": "Both tests green before and after: Test Files 1 passed, Tests 2 passed (2).",
 "restore": "git checkout HEAD -- packages/objectql/src/core.ts after each leg; byte-identity proven by sha256 983554e1846eb55dc311c136768f7f4c7d06a753de985624f11e2c74c4d26a35 both times. No git stash at any point.",
 "rebuild": "N/A and stated rather than omitted: this ratchet reads SOURCE TEXT via readFileSync, not dist, so no dist ablation preflight applies to either leg."
 },
 "ruling_3_gate_pricing": {
 "is_it_a_size_ratchet": "No. It measures no bundle and carries no threshold — it asserts that core.ts states no KB/MB figure on a comment line that also names metadata-protocol/metadata-management.",
 "scope": "packages/objectql/src/core.ts ONLY. Deliberate: the ratchet test's own header carries dated, commit-pinned provenance figures that must stay, and reading examples/ from a package test would add a cross-package path dependency. Known limitation: the two embed-objectql sites are fixed but not guarded.",
 "historical_firing": "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 (2026-06-28) through f1da948d8 (2026-08-13). Zero false positives over the file's entire history — it never flickered on unrelated edits to that file.",
 "when_it_would_redden_in_future": "Only if someone writes a KB/MB figure back into core.ts's header comment."
 },
 "tests": "Gate union re-run AT FINAL HEAD db22a44014 (after the last commit, so the ratchet readings are of the pushed tree): check:nul-bytes OK (6264 text 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 (29 catch seams, 66 read seams). Path-derived via `node scripts/pm/dispatch-gates.mjs` on the 4 changed paths: also ran check-engine-split-ratio.mjs (OK, report-only per ADR-0076 D7) and scripts/docs-audit/check-affected-docs.mjs (OK, 242 self-test cases). The convention-triggered set fired on 'edits a test file' — engine-double-contract / where-matcher / query-options-erasure all run above and are green; check:type-check-debt --re-measure was NOT run (it needs the whole workspace closure built) — flagged rather than claimed, and it is structurally unmoved here since no NEW test file was added, only an assertion inside an existing one. Suite: `pnpm --filter @objectstack/objectql test` -> Test Files 219 passed (219), Tests 3879 passed (3879). `pnpm --filter @objectstack/objectql typecheck` -> clean, and the run echoed '> tsc --noEmit' so it was not a zero-match silent pass. `pnpm --filter @objectstack/example-embed-objectql typecheck` + `test` -> clean / Test Files 1 passed, Tests 2 passed. That example FIRST failed with \"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`. Control-byte self-scan of all 4 changed files with grep -naP: clean (exit 1). CI convergence deliberately NOT awaited (maintainer 2026-08-10); reporting at draft-PR time.",
 "release_declaration": "skip-changeset label APPLIED to PR #9909 and read back (labels observed: size/s, skip-changeset). Its repo description — 'PR has no user-facing published change; bypasses the changeset gate' — matches exactly: comment-only in shipped source, one test assertion, two example-doc lines. Applied with an additive POST /issues/9909/labels, never a set-PUT, so a concurrent bot write cannot be clobbered by mine. An empty-frontmatter changeset was considered and rejected: scripts/check-empty-changeset.mjs REJECTS newly added ones in this repo (that is the objectui convention, not this one). Nothing under .changeset/** was touched, so the #9465 epic fence is not crossed.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code