fix(objectql): MetadataFacade reads return the stored document — content is a real authorable field, not a storage envelope

[os-zhuang]

Fixes#7519

What

MetadataFacade.get, list, and listNames unwrapped every stored item through the content-or-item fallback (and a content-dot-name fallback limb in listNames), presuming content marked the facade's own storage envelope. But content is a real authorable field — packages/spec/src/system/doc.zod.ts declares it as the doc's required raw-Markdown body (line 92 at HEAD, located by symbol), and packages/spec/src/ai/knowledge-document.zod.ts declares it on both of its shapes — so register('doc', name, document) followed by get('doc', name) answered the Markdown string instead of the document: truthy, string-typed, silent. That is exactly the silent non-round-trip the #7378 three-cell ruling (2026-08-12) forbids: register(t, n, d) then get(t, n) round-trips or refuses loudly.

All three reads now return the stored document verbatim.

Why removal, not a renamed envelope

The envelope the unwrap presumed has no producer — measured, not assumed:

• The only writer that ever produced one was the facade's own interim boxing of non-object values (fix(objectql,spec): rule the name argument as IMetadataService's effective key (#7378) #7511 cell 3). fix(core,metadata,objectql): enforce the #7378 three-cell IMetadataService register ruling in every shipped implementation #8349 replaced it with the shared guard's loud refusal (assertMetadataRegisterContract), so the facade never writes an envelope.
• DB hydration (loadMetaFromDb, metadata-protocol) parses the sys_metadata.metadata column and registers the parsed document itself — never a wrapper.
• Every other in-tree SchemaRegistry.registerItem caller stores the document as-is, keyed by name.

With no envelope on any write path, an unwrap on the read path can only corrupt. And because no replacement envelope key is introduced, there is no next authorable key to collide with — the collision surface is gone, not moved. This is a restore-the-invariant change riding the #7378 ruling, not a second envelope beside it.

Both directions pinned

• New block in metadata-facade.test.ts: a doc with real content round-trips whole through get / list / listNames / exists / getEntry; a knowledge_document too; and a content-less document still round-trips unchanged (the surviving path).
• New driver-local pin in metadata-service-roundtrip-conformance.test.ts (the "beyond the table" block — deliberately NOT the shared table, which lives under packages/spec/src/ and is the spec seat's half of MetadataFacade answers three register → get round-trip cases differently from every other shipped IMetadataService #7378, tracked on spec: the IMetadataService contract still states the SUPERSEDED 2026-08-11 register ruling — including a "do not implement" instruction for behaviour now shipped (#7378 spec half) #8350; that scope is untouched here): all four shipped IMetadataService implementations agree a content-carrying document round-trips whole.
• The listNames fallback limb was dead in both directions (the envelope nothing produces, and a real doc whose content is a string has no content.name) — removed, with the measurement in the docblock.

Reverse verification — direction predicted before running

Predicted: with the unwrap restored from origin/main, the get-document, list, knowledge_document, and conformance (MetadataFacade subject only) pins go red; listNames / exists / getEntry / content-less pins stay green, because those members already answered name-carrying documents correctly. Observed exactly that: 4 failed, 98 passed. Fix restored from the committed branch, not from working-tree memory.

Blast radius

Re-measured at HEAD: new MetadataFacade appears only in test files and one migration doc — no production caller constructs one. The defect stays dormant until a host wires the facade; the class is exported from the package root, so downstream hosts pick up the fix via the changeset (patch, @objectstack/objectql).

Verification

• Full @objectstack/objectql suite: 196 files, 3506 tests, all green.
• pnpm --filter @objectstack/objectql typecheck clean.
• Gates: check:durability-log-level, check:engine-double-contract, check-engine-split-ratio (informational), check:query-options-erasure (test-surface ceiling unchanged), check:type-check-coverage, check:nul-bytes — all green; dispatch-gates.mjs re-derived on the changed paths names no family beyond these.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 13, 2026 10:05am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql.

15 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx(via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/objectql)
• content/docs/deployment/vercel.mdx(via @objectstack/objectql)
• content/docs/kernel/contracts/data-engine.mdx(via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx(via packages/objectql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/objectql)
• content/docs/kernel/services.mdx(via @objectstack/objectql)
• content/docs/permissions/authentication.mdx(via @objectstack/objectql)
• content/docs/permissions/system-context.mdx(via packages/objectql)
• content/docs/plugins/index.mdx(via @objectstack/objectql)
• content/docs/plugins/packages.mdx(via @objectstack/objectql)
• content/docs/protocol/kernel/index.mdx(via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx(via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx(via @objectstack/objectql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/objectql)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.