fix(service-datasource): external validate sees a federated object saved at runtime, with no restart

[objectstack-fleet]

Fixes #21842
Clause-②: no

What this changes

ExternalDatasourceServicePlugin wired the federation service's listObjects and getObject to the metadata service. That service holds a copy of the engine's object registry, taken once at boot by ObjectQLPlugin's startup bridge. PUT /api/v1/meta/object/:name, and the import that saves through it since #21837, write sys_metadata and the engine registry (applyRegistryWriteThrough), never that copy. So POST /api/v1/datasources/:name/external/validate did not see a runtime-saved object until the next restart.

Both object reads now come from the engine's object registry on the objectql service (IObjectQLEngine.registry, its getAllObjects and getObject). The registry is looked up when validation runs, never at init() (AGENTS.md, "Startup registry reads"), the same way the import's save door is. There is no second copy and no hand refresh. The service's comparison is untouched, and datasource definitions, the package namespace and the catalog write still go through the metadata service exactly as before (see Decision needed below).

Files: packages/services/service-datasource/src/plugin.ts, one new unit file beside it, one new dogfood file, and a patch changeset. No packages/spec edit, no new export, no content/docs sentence changed (none describes where the validate door reads its objects).

Measured on the real composition (objectstack dev, showcase)

step	base 2df3d13d	this branch
validate showcase_external, before any save	2 rows, showcase_ext_customer and showcase_ext_order, both ok	same
PUT /meta/object/dg21842_saved (bound to remote customers, fields name, email, ghost_col), then validate	200, then still 2 rows	200, then 3 rows; dg21842_saved is ok: false with one diff, missing_column ghost_col
import remote orders as dg21842_imported, then validate	201, then still 2 rows	201, then 4 rows; dg21842_imported ok
re-save dg21842_saved without ghost_col, then validate	not run	dg21842_saved ok, no diffs
restart on the same database, then validate	4 rows	the same 4 rows, the same verdicts

The injected anchors (organization_id, the audit pair, owner_id, owning_business_unit_id) are not reported on the runtime-saved object: the registry's copy carries them, and the #21837 skip handles them.

H2 (does getObject already see the save?): falsified. With only listObjects moved (an intermediate build), the saved and imported rows answered unreachable with Object 'dg21842_saved' not found. and Object 'dg21842_imported' not found.. The metadata service's getObject reads the same boot copy, so both reads moved.

H3 (the boot gate), on objectstack dev: holds. Base and branch give the same boot gate output. On a fresh boot both log "all federated objects match their remote schema" with objects: 2. Booted on copies of one database that holds the stored objects, both log the same single drift warning (dg21842_saved, missing_column ghost_col). The bridge logs 109 of 109 registry objects copied, so at boot the copy and the registry hold the same objects.

Decision needed: objectstack start

Measured on objectstack start (production mode), showcase:

• Base: the boot gate logs objects: 0, and validate answers { ok: true, results: [] }. The code-defined federated objects are not listed at all. The plugin reads the metadata service at init(), and on start that service is the kernel's in-memory fallback, registered just before the start phase and after this plugin's init() (the log shows Service 'external-datasource' registered, then Service 'metadata' registered, then Phase 2: Start plugins). So the plugin holds no metadata service for its whole life.
• This branch: objects are listed now, because the registry is read when validation runs. The datasource definition is still read from the service captured at init(), which is absent, so validateObject takes its "not federated" branch. Every row answers ok: true with no diffs, and nothing is compared. The boot gate logs objects: 2. A saved object with ghost_col answered ok: true.

The boot gate's pass or abort does not move on either composition, but on start this branch turns "no rows" into rows that claim ok without a comparison. That is close to this dispatch's stop line, so the landing is the seat's call:

• A. Land as is, and the init-time metadata capture becomes its own card. Cost: until that card lands, start answers per-object ok: true that it never compared.
• B. Widen this PR: read the metadata service (datasource, namespace, catalog write) when it is used. Cost: on start the boot gate starts judging, so a deployment with drift under the default onMismatch: 'fail' refuses to boot where it started before. That is a boot-behaviour change outside this card.
• C. The init-time capture becomes its own card and lands first; this PR then lands unchanged. Cost: this PR waits.

Recommendation: C. Each landing stays honest on every composition. The boot-behaviour change gets its own changeset and its own decision, and this PR's diff and changeset stay as they are.

Tests

• New packages/services/service-datasource/src/__tests__/external-validate-reads-live-registry.test.ts (4 cases, relative import, measures src/). The fakes model the measured mechanism: metadata holds the boot copy, the objectql registry is live, and a save writes only the registry. A runtime-saved object is listed and judged by validateDatasource and by validateAll, and the code-defined one is still listed. A re-save is judged on what was saved. The registry is resolved when validation runs. The boot copy's object reads are never called.
• New packages/qa/dogfood/test/external-validate-sees-runtime-save.dogfood.test.ts (3 cases, booted showcase): validate lists the code-defined objects, then also an object saved through PUT /meta/object/:name, then also an imported one. Under this harness the federation service finds no metadata service at init() (the same cause as start), so this file pins the listing only. The verdict half is the unit file's, and was measured on objectstack dev above.
• At b44c1c87bb (after merging origin/main): @objectstack/service-datasource 38 files, 721 tests pass. tsc --noEmit passes, and --listFiles includes the new test file. Dogfood: the new file and external-import-saves-like-meta.dogfood.test.ts, 2 files, 6 tests pass.
• Ablation, with the fix committed (94e3056d62), through scripts/ablation-replace.mjs: both readers were put back to the boot-copy reads (anchor hit 1, blob 5fd02852 to cad2f3a6). Unit: 4 of 4 failed, for example expected [ 'code_cust' ] to deeply equal [ 'code_cust', 'saved_cust' ]. Dogfood: 3 of 3 failed, expected [] to deeply equal [ 'showcase_ext_customer', … ]. Under the harness all three read [], because there is no metadata service at init() there; the unit file is what separates "boot copy" from "live registry". Restore: blob equals HEAD (5fd02852), and git diff HEAD is empty. No dist/ is on either path: the unit file imports src/ relatively, and the dogfood config aliases @objectstack/service-datasource to src/.

Gates

At c68487ae6c (this head; it differs from b44c1c87bb by the changeset text only): node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 67 commands. All 67 were run and all exit 0, and --ran reconciles 67 run, 0 NOT-MEASURED, 0 UNRUN. That is the dispatch's 59 plus 8 the changeset brings (check-adr-0087-registration and check-empty-changeset, each with --self-test, release-rehearsal-clone --self-test, release-pending-publish --self-test, check:objectui-changeset, check:pm-changeset-deadline-census). check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (8 unrelated packages had no dist/). Those packages were built, and it was re-run to exit 0.

Narrowed eslint (--no-inline-config, --format json) on the 3 touched .ts files: 3 files, 0 errors, 0 warnings. The config enables no type-aware linting (no parserOptions.project), so this diff cannot move the verdict on any untouched file.

Acceptance notes

• The boot gate's completeness probe (announceAllClear, packages/runtime) still asks metadata.listDiagnosed('object'), a list the sweep no longer reads. It only shapes the all-clear sentence, never a verdict. Carrier: none.
• persistCatalog and getNamespace read the same init-time metadata capture as the datasource read above. This was already noted on fix(service-datasource)!: Import as Object saves through the metadata door's save #21837.
• origin/main was merged at b44c1c87bb. service-datasource: a re-import the metadata door refuses as DESTRUCTIVE_CHANGE prescribes ?force=true, which the import route never reads — a third face of #11095's class (reachable once #21788 lands) #21841 has not landed, and nothing on main since the base touches service-datasource.

Seat's append: patch round 1 (written by domain:services seat 1 from the dev's report 5999337391; the dev does not edit this body)

Patch round 1 (head 9489265ae0): main merged after #21887, and objectstack start measured again

The merge. origin/main 607463d736 was merged as 80dfcc30b7. It carries #21887 (merge bc7747cb) and #21874. There was one conflict, in plugin.ts's object readers. Resolution: getObject and listObjects read the engine registry (objectRegistry()). getDatasource, getNamespace and the persistCatalog getter keep #21887's resolver, metadata(). MetadataServiceLike keeps only get and register. One sentence of the resolver's docblock said object reads went through it. It now says objects come from the registry.

#21887's unit file moved with it (9489265ae0). At the merge commit, its 4 object-listing cases went red (expected [] to deeply equal [ 'wh_customer', 'wh_order' ]), because its harness served objects only from the metadata fake. The harness now also serves them from an objectql registry fake. The re-ask case tells the two services apart by the datasource definition: a managed replacement compares nothing. The no-metadata case also runs with no registry. Every other case is unchanged.

The door pin now asserts the verdict. Under the harness the metadata service is read when it is used (#21887), so the runtime-saved object's row is a real comparison. It answers ok: false with one diff, missing_column loyalty_tier. The imported row answers ok with no diffs.

objectstack start (showcase): this branch against origin/main 607463d736 as the control, with the same steps.

step	origin/main	this branch
fresh boot, boot gate	all federated objects match their remote schema {"objects":2}	same
PUT /meta/object/dg21842_saved (declares loyalty_tier, which the remote customers table lacks), then validate	2 rows; the saved object is not listed	3 rows; dg21842_saved is ok: false with missing_column loyalty_tier
import orders as dg21842_imported, then validate	2 rows	4 rows; dg21842_imported is ok: true with no diffs
restart on the same home, boot gate	one external schema drift warn: dg21842_saved, missing_column loyalty_tier	same

The question in this PR's Decision needed section is closed: on start, validate judges a runtime-saved object, and no row answers ok without a comparison. The seat decided option C (5995103062), and #21876 landed first as PR #21887. The boot gate output matches #21887's on both the fresh boot and the restart.

Measured at 9489265ae0:

• @objectstack/service-datasource: 39 files, 732 tests pass. Typecheck passes, and --listFiles includes both unit files.
• Dogfood typecheck passes. The three door pins (this one, fix(service-datasource)!: on objectstack start, read the metadata service when it is used, so validate and the boot gate compare every federated object #21887's external-validate-start-ordering and service-datasource: importing an external table under a name that differs from its remoteName creates an object that answers 500 "no such table" — and the import does not survive a restart #21788's external-import-saves-like-meta): 3 files, 9 tests pass.
• Ablation, both object readers put back to metadata() through scripts/ablation-replace.mjs: the unit file went 4 of 4 red. The door pin went 2 of 3 red: the saved and imported cases failed, and the code-defined listing stayed green because the metadata service now answers it. The restore proved the blob equal to HEAD.
• Gates: 67 derived, all exit 0. --ran: 67 run, 0 NOT-MEASURED, 0 UNRUN.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/wire-format.mdx (via /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin))
• content/docs/kernel/contracts/metadata-service.mdx (via getObject (symbol, a field of interface MetadataServiceLike), listObjects (symbol, a field of interface MetadataServiceLike), getObject (literal, a string literal in ObjectRegistryReads))
• content/docs/protocol/kernel/http-protocol.mdx (via /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin))
• content/docs/protocol/objectql/state-machine.mdx (via /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin), /object/:name/state/:field (route, bridged from symbol getObject — its route source's handler names it))
• content/docs/ui/forms.mdx (via /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin))

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

• content/docs/releases/v17/17-0.mdx (via getLegalNextStates (sdk, the bare tail of client method meta.getLegalNextStates, bound to GET /api/v1/meta/object/:name/state/:field; the bare tail of client method meta.getLegalNextStates, bound to GET /meta/object/:name/state/:field), meta.getLegalNextStates (sdk, the route ledger binds it to GET /api/v1/meta/object/:name/state/:field, selected by route anchor /object/:name/state/:field; the route ledger binds it to GET /meta/object/:name/state/:field, selected by route anchor /object/:name/state/:field))
• content/docs/releases/v17/17-1.mdx (via /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin))
• content/docs/releases/v17/17-2.mdx (via getLegalNextStates (sdk, the bare tail of client method meta.getLegalNextStates, bound to GET /api/v1/meta/object/:name/state/:field; the bare tail of client method meta.getLegalNextStates, bound to GET /meta/object/:name/state/:field), meta.getLegalNextStates (sdk, the route ledger binds it to GET /api/v1/meta/object/:name/state/:field, selected by route anchor /object/:name/state/:field; the route ledger binds it to GET /meta/object/:name/state/:field, selected by route anchor /object/:name/state/:field))

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

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• 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 607463d736046d8d692d64cf16ea6804d1609f38 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 607463d736046d8d692d64cf16ea6804d1609f38

⚠️ 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 607463d736046d8d692d64cf16ea6804d1609f38 → pass the list as
args.docs, on the commit named under Which tree this was computed on.