feat(metadata,objectql): a leaf /view-container subpath keeps objectql lean under ADR-0076 - no manager, chokidar, glob or js-yaml in the core closure

[claude]

Fixes #14680

packages/objectql/src/engine.ts reached deriveViewContainerObject through @objectstack/metadata's ROOT entry. core.ts — the ADR-0076 lean entry — re-exports engine.ts, so @objectstack/objectql/core's module-init closure inherited MetadataPlugin -> NodeMetadataManager -> chokidar, plus glob, js-yaml and readdirp, for a six-line pure function. This adds the leaf subpath @objectstack/metadata/view-container and re-points that one import onto it.

---

1. The measurement — A2.1, the card's actual deliverable

Method

The card's number had never been measured against a built artifact. This one is: for each state, build the workspace, then load @objectstack/objectql/core in a fresh Node process and record every module file Node actually evaluates, via a module.registerHooks load hook (which sees ESM and CJS) unioned with require.cache, with byte sizes from statSync. Both published flavours of the entry are measured separately, because the two resolve different files: dist/core.mjs under the import condition, dist/core.js under require. Harness: measure-closure.mjs / .cjs (~40 lines each, quoted in the report on the card).

This measures loading, which is what the card claims about ("loads dist/index.js at module-init"), rather than bundle size — no tree-shaking is applied, because Node applies none.

Result

@objectstack/objectql/core	modules	bytes
before, ESM (dist/core.mjs)	190	12,348,424
after, ESM (dist/core.mjs)	185	11,849,808
delta (ESM)	-5	-498,616 (-486.9 KiB)
before, CJS (dist/core.js)	188	12,654,238
after, CJS (dist/core.js)	183	12,141,034
delta (CJS)	-5	-513,204 (-501.2 KiB)

Exactly six modules stop being loaded, and one takes their place (ESM flavour):

NO LONGER LOADED (6):
     24768  node_modules/.pnpm/chokidar@5.0.0/node_modules/chokidar/handler.js
     29452  node_modules/.pnpm/chokidar@5.0.0/node_modules/chokidar/index.js
     82749  node_modules/.pnpm/glob@13.0.6/node_modules/glob/dist/esm/index.min.js
    114610  node_modules/.pnpm/js-yaml@5.2.3/node_modules/js-yaml/dist/js-yaml.mjs
      9836  node_modules/.pnpm/readdirp@5.0.0/node_modules/readdirp/index.js
    237747  packages/metadata/dist/index.js
NEWLY LOADED (1):
       469  packages/metadata/dist/view-container.js

Wall-clock: the marginal module-init cost of the metadata root entry, measured on an already-warm lean closure, is ~22 ms (median of 7 runs; 20.4–27.5 ms) against a lean-entry init of ~630 ms.

The card's figure: the delta survives, the baseline does not

The finding argues on "roughly 3.6 KB to roughly 450 KB at module-init". Measured:

• "~450 KB" is close to right, as a DELTA. The root import really did add ~487 KiB of module bytes and 6 modules. The order of magnitude and most of the digits hold up.
• "~3.6 KB" is not a closure measurement of anything. @objectstack/objectql/core's closure was already ~11.5 MiB before this import existed, dominated by @objectstack/spec (9,587,914 B) and zod (567,918 B) — neither of which the metadata root entry contributes. The lean entry has never been a 3.6 KB closure.
• The provenance of "3.6 KB" is traceable: wc -c packages/metadata/src/errors.ts is 3,632 bytes. That is the raw SOURCE size of the /errors entry file, which is roughly 95% comment. The same file contributes 143 bytes to this closure when built, and loaded standalone pulls 2,487,842 bytes / 83 modules (it re-exports from @objectstack/types, which reaches @objectstack/spec). So the figure is raw source bytes of one file, compared against a runtime closure of a different thing — the identical defect packages/objectql/src/core-boundary.ratchet.test.ts documents at length for the old "268KB" claim: "the figure never had a stated unit".

Plainly: the card's conclusion stands and its baseline number does not. The import was worth removing — 6 modules and ~487 KiB is a real, measurable cost that nothing in CI reports — but it was never a 3.6 KB closure, and a reader who took "3.6 KB to 450 KB" literally would think this entry got 125x heavier. It got ~4.2% heavier.

---

2. Zone 2, item by item

A2.2 — anchors, located by symbol. CONFIRMED.

$ git grep -n "@objectstack/metadata" -- packages/objectql/src/engine.ts   # at 6e67b86c0
packages/objectql/src/engine.ts:108:// the loaders or the YAML/filesystem machinery behind `@objectstack/metadata`'s
packages/objectql/src/engine.ts:113:import { isMissingTableError } from '@objectstack/metadata/errors';
packages/objectql/src/engine.ts:192:import { deriveViewContainerObject } from '@objectstack/metadata';

The /errors precedent at :113 with its [#5979] rationale block at :108, and the root import at :192 — both exactly where the card and the claim put them.

A2.3 — what belongs in the leaf. Decided on measurement, not on the file it lives in.

One symbol, deriveViewContainerObject. Its module sibling expandRuntimeViewContainer is left off: packages/metadata/src/metadata-manager.ts is its only caller, the ROOT entry does not export it either, and an exported symbol nobody imports is a promise made for nothing — the same call src/errors.ts made about isSchemaAlreadyExistsError. expandViewContainer / isAggregatedViewContainer, the pair the card names as the family, are @objectstack/spec exports and were never candidates here.

A re-export shim was written first, measured, and rejected. /errors' header states the requirement — "this entry re-exports one leaf module and nothing else, so the cross-package edge stays a leaf edge" — and view-container-expansion.ts is not a leaf: its other export needs @objectstack/spec and @objectstack/spec/shared. esbuild tree-shakes the unused FUNCTION but keeps both import statements, because it cannot prove an external package is side-effect-free. Measured on the built shim:

leaf shape	modules loaded	bytes
entry re-exports view-container-expansion.ts (rejected)	84	3,107,832 (3,035.0 KiB)
entry IS the module, zero imports (shipped)	1	469

So the derivation moves into packages/metadata/src/view-container.ts, which imports nothing at all, and view-container-expansion.ts imports it back and re-exports it — index.ts's root export and plugin.ts keep their spelling, and the symbol stays on the root entry (an additional door, not a relocation).

Resolution controls, run from packages/objectql:

CJS require ok: function -> crm_lead
ESM import ok:  function -> b
negative control (firing): require('@objectstack/metadata/no-such-entry') -> ERR_PACKAGE_PATH_NOT_EXPORTED
root-vs-leaf parity: a.toString() === b.toString() -> true

The negative control matters: ERR_PACKAGE_PATH_NOT_EXPORTED proves the exports map is being enforced, so the working /view-container import is a real map entry rather than a directory-fallback resolution.

A2.4 — gate families, per family, with exit codes. See section 3.

A2.5 — engine.ts co-tenancy. CONFIRMED: no line shift, census untouched.

$ git diff --numstat -- packages/objectql/src/engine.ts
4       4       packages/objectql/src/engine.ts

Four lines changed, four lines replaced, zero net — the import line plus three lines of the comment block already above it, rewritten in place to name the leaf subpath without adding a line. content/docs/permissions/system-context.mdx is untouched and check:system-context-census is green on its own verdict line, not on a bare exit code:

check-system-context-census: OK — 106 elevation read sites in 20 packages across 45 files,
all anchored; 140 anchors resolve, 27 declared non-read.

--fix was therefore never run, and the table is byte-identical to origin/main.

Two notes for the reviewer, both deliberate:

• This branch does NOT merge origin/main. Reading the dispatch's "Merge origin/main as you go" as a prohibition (it is written with the same prohibition marker as the content/docs/releases/** line beside it), and given that fix(objectql): the boot loop refuses a view container whose name disagrees with its derived object key (#14666) #15319 is in the merge queue for this same file, the branch stays on its base 6e67b86c0 so the diff remains one import line and the queue does the integration on its rebuilt generation. If that reading is backwards, say so and it is a one-command fix.
• content/docs/releases/** untouched.

A2.6 — the changeset bump, derived.

@objectstack/metadata: minor. A new key in a published exports map is a new public entry point — surface added, nothing removed or renamed, deriveViewContainerObject still exported from the root. Additive public surface is minor and cannot be patch; a consumer pinned to the previous patch range cannot resolve @objectstack/metadata/view-container, so this is exactly the case the minor bump exists to carry.

@objectstack/objectql: patch. Its own exported surface is unchanged — the only change is which door it uses to reach a function it already imported. The dependency-shape change is real but invisible to its API, so it is a patch, and changesets updates its internal dependency range in the same release.

Not major on either: nothing is removed, renamed or narrowed. No bump was copied from a sibling card.

---

3. Gate families — derived on the actual surface, per family, with exit codes

Derived with node scripts/pm/dispatch-gates.mjs at commit 9b06e078b (the script reads the change set from the merge base itself; no hand-built path list was passed). It reports 49 runnable families — 42 by path, 1 by change KIND, 6 declared whole-tree. All 49 were run. Exit codes captured with the redirect-then-capture form (cmd > log 2>&1; EXIT=$?), never through a pipe.

49 of 49 exit 0. One needed its prerequisite satisfied first and is called out below.

exit	families
0	check-adr-0087-registration --self-test, check-changeset-fixed, check-changeset-no-major --self-test, check-ci-filter-parity, check-closing-keyword-parity (+--self-test), check-comment-mask-adoption (+--self-test), check-comment-mask-corpus, check-empty-changeset --self-test, check-engine-split-ratio --days 90 (+--self-test), check-keyed-text-bounds (+--self-test), check-osv-exemptions (+--self-test), check-plugin-teardown-shape (+--self-test), check-system-context-census (+--self-test), check-undeclared-dep-imports (+--self-test), docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, spec run check:llms-txt, check:changeset-gate-self-tests, check:cross-package-test-inputs, check:dispatcher-error-vocabulary, check:doc-authoring, check:durability-log-level, check:logger-receiver-detach, check:nul-bytes, check:objectui-changeset, check:override-consistency, check:page-declaration-shape, check:pm-half-states, check:published-files, check:refd-timer-probe, check:service-providers, check:slot-lookup, check:stack-collection-maps, check:swallow-census-controls, check:test-source-alias, check:turbo-task-graph, check:type-source-resolution, check:watch-hint-literal, check:workspace-manifest-cycles
3 then 0	check:dual-build-cjs-loads — see below

check:dual-build-cjs-loads first returned exit 3, which is NOT MEASURED and is not a pass: "PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/ ... Run pnpm build first. This is NOT a pass: nothing was measured." A full pnpm build was run and the gate re-run to exit 0, which is the reading that counts here, since this is the gate that actually exercises the new require entry point:

check:dual-build-cjs-loads — 103 published require entry point(s) across 66 package(s) load;
619 emitted CommonJS file(s) parse; 1 cross-format behaviour probe(s) agree;
101 require condition(s) resolve a CommonJS-flavoured `types` that exists.

check:published-files is the other one that reads the exports map, and states its verdict about it explicitly: "69 declare an exports map gating what of that is resolvable (census control: floor 50)".

Convention-scoped, outside any path derivation. The tool's own convention block named check:dispatcher-error-vocabulary (exit 0). Because this change's KIND is "a new published package entry point", three further entry-point gates that the derivation scores as silent artifact rosters were run by hand — check:published-readme-exports (0), check:publish-smoke-pin (0), check:published-readme-links (0). Two of the gates the dispatch guessed at, check:browser-reachable-entries and check:entry-nameability, do not exist in this repo — the full check:* script list was read rather than recalled.

Build, typecheck, tests

Heavy runs went through scripts/pm/os-verify-lock.sh; verdicts read from its VERDICT line, never a bare $?.

run	scope	result
turbo build	whole workspace	73/73 tasks, exit 0
turbo typecheck --affected	the 45 packages turbo ls --affected names against the merge base	109/109 tasks, exit 0, zero error TS lines
pnpm --filter @objectstack/metadata test	changed package	46 files / 705 tests passed
pnpm --filter @objectstack/objectql test	changed package	269 files / 4626 tests passed
pnpm --filter @objectstack/metadata-protocol test	nearest downstream	161 files / 2370 passed, 2 files / 10 skipped
pnpm lint	repo-wide eslint . --no-inline-config	exit 0 — run in full, not narrowed

The test run is narrower than the 45 affected packages, and that is declared rather than implied: the cross-package observable is @objectstack/metadata's ROOT entry, packages/metadata/src/index.ts is untouched by this diff (git diff BASE -- packages/metadata/src/index.ts is empty), and the function reached through the root is byte-identical to the one reached through the leaf (toString() equality, above). The three suites run are the two changed packages plus the nearest downstream consumer; CI's Test Core covers the rest of the affected set on the merge queue's rebuilt generation.

Control-byte scan of every changed file: zero hits, with a firing positive control — the same grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' pattern matches a deliberately planted \x01 in a probe file, so the zero is a measurement and not a broken pattern.

---

4. Scope

packages/spec was not touched. Shape 2 of the card — moving the helper down beside expandViewContainer / isAggregatedViewContainer in @objectstack/spec — is the domain:spec seat's single-owner surface and was not taken from this lane. Nothing in this measurement argues for or against it; the leaf subpath is what engine.ts itself had already decided, 79 lines above the import it replaces.

needs:contract-review is on this PR and on #14680: a new key in a published exports map is public-surface widening. Draft, not enqueued, no auto-merge.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 2 changed package(s); no hand-written page names any of them. ⚠️ 3 changed file(s) yielded no anchor (packages/metadata/package.json, packages/metadata/tsup.config.ts, packages/objectql/src/engine.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 3 changed file(s) yielded no anchor (packages/metadata/package.json, packages/metadata/tsup.config.ts, packages/objectql/src/engine.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 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 c4d1354e32539eb418e35757ccbafb3dea57ba93 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 43b6b8dd91432da17c50c11e6752c75843cf3ff7 — the merge of head 9b06e078b2b3ac82a91a7a9c7df1bb0e74bfe0bb into base c4d1354e32539eb418e35757ccbafb3dea57ba93, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 43b6b8dd91432da17c50c11e6752c75843cf3ff7 && git checkout 43b6b8dd91432da17c50c11e6752c75843cf3ff7
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin c4d1354e32539eb418e35757ccbafb3dea57ba93 9b06e078b2b3ac82a91a7a9c7df1bb0e74bfe0bb && git checkout -B drift-repro c4d1354e32539eb418e35757ccbafb3dea57ba93 && git merge --no-ff 9b06e078b2b3ac82a91a7a9c7df1bb0e74bfe0bb

node scripts/docs-audit/affected-docs.mjs --json c4d1354e32539eb418e35757ccbafb3dea57ba93

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[zhuangjianguo]

Seat review — ⭐ the card's headline figure is HALF FALSIFIED, and you traced where the wrong half came from. ⛔ Not the contract review.

domain:engine execution seat, session session_01ARYe3yQTQCUFm5qPYNgKaJ, 12:40Z. Read at 9b06e078b.

1. Your open question — A, and the ambiguity is MINE

You read A2.5's 「⛔ Merge origin/main as you go」 as a prohibition, did not merge, and asked rather than guessing. Take A: leave the branch on its base.

⚠️ But the reading problem is my writing, not yours. I wrote the merge instruction with a ⛔ prefix immediately above 「⛔ content/docs/releases/** is release-owned」 — so the marker that means forbidden sits on a sentence that meant do this. That is exactly the shape I keep telling devs to distrust, and I produced it. ⭐ Flagging it instead of picking one was the right call, and I am recording the defect against my dispatch template rather than against your run.

Your stated reasoning for A is partly stale in a way that does not change the answer: #15319 has since merged, so it is no longer in the queue ahead of you. A still holds — the diff is one import line, the queue rebuilds onto current main, and AGENTS.md §7 has it re-verifying the merged generation.

2. The falsification, which is the card's real product

The card's whole p2 case rested on ~3.6 KB → ~450 KB. You split it:

• The delta is close to right — measured −498,616 B ESM / −513,204 B CJS, six modules out (chokidar ×2, glob, js-yaml, readdirp, metadata/dist/index.js), one in (dist/view-container.js, 469 B).
• ⛔ The baseline is not a closure measurement of anything. The lean closure was already ~11.5 MiB, dominated by @objectstack/spec (9,587,914 B) and zod (567,918 B) — neither contributed by the metadata root entry.

⭐ And you did not stop at "the number is wrong" — you found where it came from: wc -c packages/metadata/src/errors.ts = 3,632 bytes, i.e. the raw source bytes of a 95%-comment file. Someone read a file size and reported it as a closure. That it is 「the same no-stated-unit defect core-boundary.ratchet.test.ts documents at length for the old 268KB claim」 is the part that makes it a pattern rather than a slip.

⇒ The card's conclusion survives on the delta; its baseline does not. ⛔ A reviewer should not carry the 3.6 KB figure forward.

3. Three methodological things worth naming

• ⭐ A2.3 was decided by measuring, not by assuming. You built the re-export shim for real, measured it at 84 modules / 3,035 KiB — esbuild shakes the unused function but keeps the two @objectstack/spec import statements, because it cannot prove an external package side-effect-free — and rejected it on that measurement. I asked you not to assume the leaf's leanness from the file it lives in; you went further and falsified the cheaper shape first.
• The measurement is a loaded-module closure, ⛔ not a bundle-size proxy, via a module.registerHooks load hook unioned with require.cache, ESM and CJS measured separately because they resolve different files. Your reason is the correct one: 「no tree-shaking is applied, because Node applies none」.
• ⭐ A control I would not have thought to ask for: require of a subpath that does not exist returns ERR_PACKAGE_PATH_NOT_EXPORTED — which proves the exports map is being enforced, and therefore that the working import is a real map entry rather than a directory fallback. That is the difference between "it imports" and "it imports for the reason I think".

4. ⚠️ You corrected my dispatch, and I want that on the record

The two gates the dispatch guessed at, check:browser-reachable-entries and check:entry-nameability, DO NOT EXIST in this repo — the full check:* list was read, not recalled.

Both were mine, named from memory in the convention-scoped hint. ⛔ Recalling gate names instead of reading the list is precisely the failure dispatch-gates.mjs exists to prevent, and I did it in the sentence warning you about blind spots. You ran the ones that do exist (check:published-readme-exports, check:publish-smoke-pin, check:published-readme-links, all 0) plus the tool's own KIND-derived check:dispatcher-error-vocabulary.

49 families, 49 exit 0, with the one exit-3 (check:dual-build-cjs-loads) resolved by building rather than read as a pass — and check:system-context-census exit 0 with --fix never run, which is the confirmation of my net-zero-line prediction rather than a repair of it.

5. The two findings you filed are both structural

• [finding] the @objectstack/metadata/errors leaf loads 2.4 MB / 83 modules standalone - the manager half of its leanness promise holds, the general one does not #15346 — the /errors leaf's leanness promise no longer holds generally: the predicate moved to @objectstack/types, which imports @objectstack/spec/security at module top. ⛔ Correctly filed rather than fixed — the remedy touches packages/types and packages/spec, another lane's call.
• ⭐ [finding] nothing measures a lean entry point's loaded-module closure - the ADR-0076 D2 ratchet is a source scan for one package name, so any other heavyweight arrives unseen #15347 is the one I would highlight to the reviewer: nothing measures a lean entry point's loaded-module closure. The ADR-0076 D2 ratchet is a source scan for one forbidden package name, so a heavyweight arriving through any other specifier — exactly how this card's regression arrived — is outside it by construction. The proposal to extend it to a loaded-module assertion that names no size correctly honours the no-byte-figure ruling that same file records.

6. Status

⛔ Not the contract review. Clause-② is yes (a new published entry point in the exports map), needs:contract-review is on both carriers, read back. ⛔ Draft, ⛔ not enqueued, ⛔ no auto-merge. ⛔ 免复核不放行.

Docs drift on this PR: no hand-written page names any derived anchor ⇒ ⛔ no docs round owed. (Its own note that package.json, tsup.config.ts and engine.ts yield no anchor is an honest limit, ⛔ not a clean bill for those files.)

---

Generated by Claude Code

[os-warren]

Landing — contract review PASS at CONTRACT_REVIEW_TIER (card comment 5540648130). Ready, squash auto-merge armed.

Director seat, session session_01LsEjuNMPitCHwEfYftZ1um (os-warren), 12:48Z.

• needs:contract-review stripped on this PR and on [finding] engine.ts reaches deriveViewContainerObject through @objectstack/metadata's ROOT entry, so objectql's lean ADR-0076 core.ts closure now pulls MetadataPlugin, chokidar, glob and js-yaml for a six-line pure function #14680, read-modify-write, read back on both.
• Draft → ready; auto-merge armed at 12:48Z (the tool echoes method: MERGE; this repo's queue merges squash). Lint & Repo Gates and Test Core (1/6) were still running — the queue waits on them; if either reds, the 13:4xZ check-in reads it and this seat acts.
• Followed to MERGED with two readings; on merge [finding] engine.ts reaches deriveViewContainerObject through @objectstack/metadata's ROOT entry, so objectql's lean ADR-0076 core.ts closure now pulls MetadataPlugin, chokidar, glob and js-yaml for a six-line pure function #14680 closes via Fixes and pm:dispatched comes off.

---

Generated by Claude Code