docs(objectql): correct MetadataFacade's class docblock — it is not the installed 'metadata' kernel service

[os-musk]

Fixes #14019

Prose only. One TSDoc block in packages/objectql/src/metadata-facade.ts, plus its changeset.

What was wrong

The class docblock said MetadataFacade is "Registered as the 'metadata' kernel service".
Sixty lines down the same file, registerObjectBothPlaces' header says the opposite —
nothing installs a MetadataFacade into that slot — and the second statement is the true
one. The false half is load-bearing: a reader grepping for who fills the metadata slot
lands on the class docblock first and stops there.

The docblock now says what the class is (an injectable IMetadataService over a
SchemaRegistry, exported from this package's root and core entrypoints for a downstream
host that chooses to install it) and what it is not (installed into the 'metadata'
slot by anything in this repository), names the two real fillers, and points at the
registerObjectBothPlaces header so the two statements cannot be read apart.

Premise re-verified on this branch, not taken from the card

Check	Result on 329608eb0
git grep -n "registerService('metadata'" -- packages	exactly one non-test site: packages/metadata/src/plugin.ts:365, registering this.manager
positive control: git grep -c "registerService(" -- packages	wide hits (e.g. packages/core/src/kernel.ts:5) — the pattern engine does see this tree, so a zero above would have meant something
variable-key path	packages/core/src/kernel.ts:270 (preInjectCoreFallbacks) and :303 (validateSystemRequirements) register CORE_FALLBACK_FACTORIES.metadata, which is createMemoryMetadata (packages/core/src/fallbacks/index.ts:41)
git grep -n "new MetadataFacade" -- packages	test files only; no production construction site

One drift from the card's own text, recorded rather than silently corrected: the manager
registration is at plugin.ts:365 here, not :353. Substance unchanged.

The dist/*.d.ts measurement (PM assumption 2 — CONFIRMED)

Built with pnpm --filter '@objectstack/objectql^...' build && pnpm --filter @objectstack/objectql build
(under the shared verify lock; VERDICT command-exit 0), then grepped the emitted declarations:

• New phrase — the sentence "Nothing in this repository installs a MetadataFacade": 1 hit in
  dist/util-BKgrGIUi.d.ts, 0 in dist/index.d.ts / dist/core.d.ts.
• Positive control — the sentence the rewrite deliberately keeps ("multi-kernel servers
  can give every kernel its own…"): 1 hit, same file, 0 in the other two. So the zeroes
  above are about which file carries the declaration, not about TSDoc being stripped.
• Negative control — the removed false sentence: absent from the whole dist/ tree.
• Reachability: dist/index.d.ts and dist/core.d.ts both re-export M as MetadataFacade
  from ./util-BKgrGIUi.js, types is dist/index.d.ts, and files is ["dist", …].

⇒ The class docblock does ship to consumers — it is what an editor hover shows on an
imported MetadataFacade — so this is a reader-visible change in the published package and
a @objectstack/objectql: patch changeset is owed. It is in the diff; no skip-changeset
label is claimed.

Clause-②: no, read from this diff

git diff over the source file: 18 added / 5 removed lines, every one a * TSDoc
comment-body line — the complement grep (changed lines that are not comment-body lines)
returns nothing. No emitted runtime byte, no public type, no accept/reject behaviour, no
gate move. No ablation is owed for a comment-only diff, and none was run.

Scope

No registration change. Installing a MetadataFacade into the metadata slot is behaviour
and belongs to #13331's solution space (a priority:p0 card, mentioned here only as the
card whose premise this docblock likely produced — nothing about it is claimed or changed
by this PR).

The registerObjectBothPlaces header at :134 was not edited: it already carries the
true statement, and the rewritten class docblock now agrees with it and points at it, which
is the one-voice requirement the triage set. Editing it too would have been churn on a
sentence that was never wrong.

Verification (all at 329608eb0, the final commit)

• Gate family re-derived on this tree after the last commit:
  node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands → 30 commands.
  All 30 run; 27 exit 0, and 3 report NOT MEASURED in their own words rather than a red:
  check-test-completeness.mjs (exit 3 — needs a saved turbo run test log; "It is not a red,
  and there is nothing here to fix"), scripts/pm/check-half-states.mjs (exit 3 — needs
  repo-scoped REST egress this container does not have), and check:dual-build-cjs-loads
  (exit 3 — "PREREQUISITE NOT MET … Run pnpm build first"; only objectql's closure is built
  locally, CI builds the workspace).
• Always-runs named in the dispatch: pnpm lint whole repo, exit 0 in 74s (no narrowing
  needed), pnpm check:nul-bytes exit 0 (7922 files scanned), pnpm check:error-status-conformance
  exit 0, pnpm --filter @objectstack/objectql typecheck exit 0 (source, scripts, and the
  test-layer project — 44 test files).
• Every exit code above was captured after a redirect, never through a pipe.
• Declared narrowing: objectql's full vitest run was not run locally. Grounds: every
  changed line is inside a TSDoc block (proof above), no test or gate reads this file as text
  (git grep for the removed sentence returns nothing tree-wide), the package builds and
  type-checks green, and CI's Test Core runs the suite on this PR. The box was also running
  another seat's full objectql suite under the shared lock at the time.

The derivation printed a STALE TREE warning (this branch is 4 commits behind origin/main,
one family file changed in that range: scripts/measure-durability-swallow-family.mjs).
Inspected: that diff only repoints the durability self-test's "dark control" example file and
rewrites its prose — it does not change which families my two paths map to, and re-deriving
after git fetch origin main produced a byte-identical command list.

🤖 Generated with Claude Code

https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/metadata-facade.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/metadata-facade.ts) — pages documenting those are invisible to this run
• 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 — 16 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 8e9e63087c6846da3f669c85e529e74f657e73d1 → packageMentionDocs.

[os-musk]

Landing provenance (engine execution seat, session_0112hMx9hjJ9BgB28X97DS68) — flipped to ready at 13:10Z and auto-merge (squash) armed at 13:11Z on head 329608eb0 (the 10:36Z flip window was missed while the seat's session was held by a rate limit; nothing about the PR changed in between).

• ACCEPT on the card: [finding] MetadataFacade's class docblock claims it is "Registered as the 'metadata' kernel service" — the same file says 60 lines later that nothing on main installs it #14019 (comment 5507951322).
• Pre-landing checks at flip time: every check run on 329608eb0 completed with conclusion success or skipped (33 runs, perPage: 50; Lint & Repo Gates success at 10:31:46Z, all Type Check jobs success); node scripts/pm/check-governed-merges.mjs --test on the PR's 2 changed paths: 0 of 2 hit the register — not governed, ordinary queue landing applies.
• The enable_pr_auto_merge call echoed an empty method and time (a known echo shape on a PR that is nonetheless armed — PR fix(objectql): carry an ADR-0112 envelope on registerObject's cross-package ownership refusal (#14367) #14476 precedent); the queue build ref is the reading that confirms it, checked at the next landing window.
• Clause-② self-reading no, concurred at ACCEPT: TSDoc only; @objectstack/objectql: patch because the class docblock ships in the published declarations (measured). No needs:contract-review carrier.
• Closing keyword: Fixes #14019 only; the card closes at MERGED and its pm:dispatched is stripped in the landing record.

---

Generated by Claude Code