fix(service-datasource)!: on objectstack start, read the metadata service when it is used, so validate and the boot gate compare every federated object

[objectstack-fleet]

Fixes #21876
Clause-②: no (narrowing)

What this changes

ExternalDatasourceServicePlugin.init() read the metadata service once and kept the answer. objectstack start composes no metadata plugin. Its metadata service is the kernel's in-memory fallback, which the kernel pre-injects after every plugin's init(), just before the start phase. The start log shows the order: Service 'external-datasource' registered, then Service 'metadata' registered, then Phase 2: Start plugins. So on start, every reader of the kept value saw no service for the life of the process.

The plugin now looks up the metadata service when each reader runs. It uses a resolver function called at each use, the same pattern metadataSaveDoor already follows in this init() (AGENTS.md, "Startup registry reads", cure 1). That covers getDatasource, getObject, listObjects, getNamespace and the catalog write. The catalog write was a conditional spread, so init() decided whether the persistCatalog slot existed at all (H2). It is now a getter, as persistObject already is. With no metadata service at all, each reader returns the same fallback it always did.

Not changed: what validation judges, what each onMismatch value does, and the boot gate's code (packages/runtime). The import's save call (persistObject, landed with #21874) is not changed either. Objects are still read from the metadata service's copy. #21842's PR #21875 moves them to the engine registry.

The object reads, called out. getObject and listObjects read the same kept value, so replacing it with a resolver also changes how those two readers are spelled: each calls the resolver instead of using the constant. They read the same members with the same fallback as before. Only the moment the service is looked up moves. Without this, the card's "Done when" cannot hold: on start, validate would still list no objects. These are the lines PR #21875 replaces. When #21875 merges main, its getObject and listObjects should replace these, and it should keep this PR's getDatasource line.

Files: packages/services/service-datasource/src/plugin.ts, one new unit file beside it, one new dogfood file, and a minor changeset with the ! banner. No packages/spec edit, no new export, and no edit to an existing packages/qa file.

Measured on the real composition (showcase, objectstack start and objectstack dev)

Remote fixture for the probe: customers.lifetime_value is TEXT on the remote, while showcase_ext_customer declares a currency field. That is a type_mismatch at severity error. A missing column would not survive the boot, because the showcase's own onEnable adds missing columns. A column type it leaves alone. The base build of service-datasource is plugin.ts at 2e780467. The branch build is plugin.ts at 10dd86129b, which is this head's plugin.ts minus #21874's one-line writeFace change from the merge.

objectstack start	base	branch
boot gate, drift, showcase's onMismatch: 'warn'	all federated objects match their remote schema {"objects":0}	external schema drift (warn) on showcase_ext_customer: type_mismatch lifetime_value, expected currency, actual text
boot gate, no drift	(objects: 0 whatever the remote holds)	all federated objects match their remote schema {"objects":2}
boot gate, drift, datasource set to onMismatch: 'fail' for the probe (restored after; blob equals HEAD)	boots, objects: 0	refuses to boot: "Object 'showcase_ext_customer' does not match its remote table on datasource 'showcase_external': type_mismatch: customers.lifetime_value (expected currency, actual text)"
POST /datasources/showcase_external/external/validate	{ ok: true, results: [] }	2 rows: showcase_ext_customer ok: false with the type_mismatch, showcase_ext_order ok: true
POST …/external/refresh-catalog, then GET /meta/external_catalog/showcase_external_catalog	snapshot answered; the read answers RESOURCE_NOT_FOUND (never stored)	snapshot answered; the read returns the stored record
GET …/external/tables	2 tables	same (the showcase sets no allowedSchemas)
POST …/tables/customers/draft	customers, with the TODO(namespace) note	same (see the namespace note below)
import orders as probe_ext_orders_21876, then as showcase_probe_orders_21876	201, 201	201, 201 (same note)
validate after both imports	results: []	the 2 code-defined rows only; the imported objects are not listed until restart (H5, #21842's)

objectstack dev, the control (H4): base and branch gave byte-identical answers from validate, validate-after-import, tables, the catalog read and both imports, after stripping snapshotAt. Both boot gates log the same drift warning. dev answers exactly what the branch now answers on start.

The namespace note. The showcase's code-defined datasource carries no _packageId on either composition, dev included, so its namespace never resolves there. The namespace half (the draft's prefix, the import's name check) is pinned in the unit file, with a datasource that carries package provenance. On start it was blind on every deployment, and it now answers as on dev.

Introspection (data service). It is still read at init(). On start it is already registered by then: base start answered tables, draft and refresh. See Acceptance notes.

Tests

• New packages/services/service-datasource/src/__tests__/external-metadata-read-at-use.test.ts: 10 cases, relative import, so it measures src/. The metadata service is registered AFTER init(), as on start. Under that ordering: validate compares each federated object and reports the drifted column, and the boot gate's sweep (validateAll) lists every federated object. The draft takes the namespace of the datasource's package. An import's explicit name that breaks the prefix is refused, asserting code: 'EXTERNAL_IMPORT_ERROR' and status: 400, and the save door is never called. The refreshed catalog is persisted. allowedSchemas is honoured. The service is looked up again at each use, never remembered. Control: a service registered BEFORE init() (the dev ordering) gives the same answers. With no metadata service, every reader keeps its fallback.
• New packages/qa/dogfood/test/external-validate-start-ordering.dogfood.test.ts: 3 cases, booted showcase. The remote's customers.email is renamed away after provisioning; the harness does not run onEnable at boot, so the drift survives. A precondition asserts that the harness's metadata service is the kernel's in-memory fallback, the start shape. Validate compares both federated objects and reports missing_column email. validateAll() lists both.
• Red at base (ce28b73809: the two test files on the base plugin.ts): unit 7 failed, 3 passed, for example expected [] to deeply equal [ 'wh_customer', 'wh_order' ] and expected "vi.fn()" to be called 1 times, but got 0 times. Dogfood 2 failed, 1 passed (the precondition), expected [] to deeply equal [ 'showcase_ext_customer', … ].
• Ablation at 10dd86129b (fix committed first), through scripts/ablation-replace.mjs in WRAP mode. The resolver line was replaced by a capture taken at init() and a resolver returning that capture (anchor hits 1, blob 3f9f1968 to 2dbc3ade, marker ABLATION-21876 count 1 on disk, anchor count 0). Unit: 7 of 10 failed, the same 7 as at base. Dogfood: 2 of 3 failed. Restore: blob after restore 3f9f1968 equals HEAD, git diff HEAD is empty and git status is clean. No dist/ is on either path: the unit file imports src/ relatively, and the dogfood config aliases @objectstack/service-datasource to src/.
• At this head c6f237478c (origin/main e864db56df merged, which carries fix(service-datasource): a destructive re-import's refusal names the remedies that work from the import route #21874): closure build (@objectstack/dogfood dependencies plus service-datasource) 63 of 63 tasks. @objectstack/service-datasource: 38 files, 728 tests passed. tsc --noEmit passes, and --listFiles includes the new unit file (count 1). Dogfood: the new file plus external-import-saves-like-meta and external-import-destructive-remedy (the other two files that mount this plugin), 3 files, 10 tests passed. Dogfood tsc --noEmit passes, with the new file in --listFiles (count 1).

The gap, named. The dogfood file boots the verify harness, not the objectstack start CLI. The harness composes no metadata plugin, so its metadata service is the same kernel fallback, injected at the same moment as on start. The precondition case holds that. The harness does not mount the boot gate. Mounting it from this file would need @objectstack/runtime as a value import, which the dogfood package does not alias. That would mean a new pair in check:test-source-alias's shrink-only ledger or an edit to the dogfood vitest config, and both are outside this dispatch. So the file pins the gate's input (validateAll()), and the gate's own verdict on start is the probe table above.

Gates

At c6f237478c: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 67 commands: the dispatch's 59 plus 8 that the changeset brings. All 67 were run and all exit 0. --ran reconciles 67 run, 0 NOT-MEASURED, 0 UNRUN. check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3), because 8 unrelated packages had no dist/. check:type-check-debt's re-measure later in the same battery built them, and the gate was re-run on the same head to exit 0. Also run: pnpm check:startup-registry-verdict exit 0 ("43 startup/open-registry seam(s) … none recording a verdict the boot can contradict").

Narrowed eslint (--no-inline-config, --format json) on the 3 touched .ts files: 3 files, 0 errors, 0 warnings. The changeset .md is outside eslint's population: eslint answers "File ignored because no matching configuration was supplied". eslint.config.mjs enables no type-aware linting (no parserOptions.project), so this diff cannot move the verdict on any untouched file.

Docs

No content/docs sentence is made false. data-modeling/external-datasources.mdx promises a federated datasource is "validated at boot" and that a mismatch "fails boot". That was false on start and is now true.

Acceptance notes

• engine (the data service) is still read at init(). It is not part of this card. On both start and dev, ObjectQLPlugin registers it in its own init(), which runs before this plugin. Base start introspected (tables, draft, refresh answered), so nothing was measured wrong. Carrier: none.
• The showcase's code-defined datasources carry no package provenance, so the federation draft and import never resolve a namespace for them, on dev as on start. It is reported to the seat with its evidence, not filed from here.
• A federated object saved at runtime is still listed by the validate door only after the next restart. That is service-datasource: POST /external/validate does not see a federated object saved at runtime (through PUT /meta/object or the import) until the next restart #21842's, fixed by PR fix(service-datasource): external validate sees a federated object saved at runtime, with no restart #21875 after this lands.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 3 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-6.mdx (via external_catalog (literal, a string literal in ExternalDatasourceServicePlugin))

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.

What this run could not see

• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 1 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 e864db56dffc2dec3290e5f0700f9d1606a1c830 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f8fc103aa30985061cce2bbb8d975c136bd17ff1 — the merge of head c6f237478c0554db62139694cb3867b9fb845bdd into base e864db56dffc2dec3290e5f0700f9d1606a1c830, 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 f8fc103aa30985061cce2bbb8d975c136bd17ff1 && git checkout f8fc103aa30985061cce2bbb8d975c136bd17ff1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e864db56dffc2dec3290e5f0700f9d1606a1c830 c6f237478c0554db62139694cb3867b9fb845bdd && git checkout -B drift-repro e864db56dffc2dec3290e5f0700f9d1606a1c830 && git merge --no-ff c6f237478c0554db62139694cb3867b9fb845bdd

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

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e864db56dffc2dec3290e5f0700f9d1606a1c830 → pass the list as
args.docs, on the commit named under Which tree this was computed on.