fix(runtime,service-datasource): an import over a code-defined datasource is held to its package's ADR-0028 namespace

[objectstack-fleet]

Fixes #21889
Clause-②: no

An import over a code-defined datasource is now held to the ADR-0028 namespace of the package that declares the datasource, and the draft door answers the prefixed name. This follows triage's direction A (5999047022, which amends 5998041661). There are two halves.

What changed

• Writer (packages/runtime/src/app-plugin.ts). AppPlugin registers each code-defined datasource through applyProtection (@objectstack/spec/shared), the stamping helper the other load paths use. The datasource is stamped with the id and version of the package body that declares it. The owner is read the way the metadata plugin's artifact door reads it (ADR-0130 D4):
  • packages absent: every datasource takes the manifest's id, the key registerApp installs the package under. The list read is the same one as before (D7).
  • packages present: each body's datasources take that body's id (artifactPackageId, in resolveArtifactPackageOrder order). The artifact's top-level manifest id is never stamped onto every entry (the Multi-package artifact: the metadata service attributes every top-level object to the artifact's manifest.id while the registry owns it per package — crm_order is served twice on GET /api/v1/meta/object, listed under com.example.multi.core, and Studio's Data pillar for the App package shows the module's object #14599 misattribution class), and no name-to-package index is built over the flattened list.
  • A top-level datasource that no body declares keeps its registration under the artifact's own id, as the door's residual sweep does, and a warning names it.
• Reader (packages/services/service-datasource/src/plugin.ts, getNamespace and its docblock only). The package record is read from the engine registry (registry.getPackage on the objectql service), the store the publish gate reads for the same check (publishPackageDrafts, metadata-protocol). It used to be asked of the metadata service, which holds no package records in any composition. The id comes only from the stamped _packageId: no guess, no fallback store, no second resolution path. The engine is resolved when it is used, like metadata() (the read-at-use posture).

Outside getNamespace, plugin.ts changes two docblock words, so that neither docblock names package reads: the metadata() docblock ("every datasource read below") and the MetadataServiceLike docblock ("datasource definitions"). Nothing under packages/spec, no metadata-door change, and no new error code.

The ruling's pins, at the real doors

Measured at 8e5ff7aa on the showcase's showcase_external, under objectstack dev (pnpm dev -- --fresh -p 38931) and objectstack start (--compile -p 38933, fresh database). Both gave the same readings:

door	answer
POST …/external/tables/orders/import {"name":"probe_orders_21889"}	400 EXTERNAL_IMPORT_ERROR "Object 'probe_orders_21889' is missing the package namespace prefix. Rename it to 'showcase_probe_orders_21889' (namespace = 'showcase')." GET /meta/object/probe_orders_21889 answers 404.
POST …/external/tables/orders/draft	200, name: 'showcase_orders', no TODO(namespace) in the source
import {"name":"showcase_probe_orders_21889"} (control)	201, and GET /data/showcase_probe_orders_21889 answers 200 with 4 rows
import with no name override (the carry)	201, saved as showcase_customers
PATCH / DELETE / PUT /api/v1/datasources/showcase_external (control)	400 DATASOURCE_ADMIN_ERROR / 400 DATASOURCE_ADMIN_ERROR / 405 METHOD_NOT_ALLOWED, unchanged
POST …/external/validate (control)	200, ok: true, over showcase_ext_customer and showcase_ext_order
GET /data/showcase_ext_order (control)	200, 4 rows

Clause-② readings

• GET /api/v1/meta/datasource, showcase_external, after the change (dev and start alike): _diagnostics, _packageId, _packageVersion, _provenance, active, autoConnect, config, driver, external, label, name, origin, schemaMode. The values are com.example.showcase, 0.1.0 and package. Before the change the item carried none of the three (the writer ablation below, on the harness). All three are declared on DatasourceSchema (...MetadataProtectionFields). On an item with no protection block, applyProtection writes exactly those three (shared/protection.zod.ts), so no _lock* key and no further key is added.
• The host default item is unchanged: _diagnostics, config, driver, label, name, origin, with no _packageId.
• The admin list (GET /api/v1/datasources) is unchanged on dev and start for both items: active, driver, label, name, origin, schemaMode, status.
• No published entry gains an export. codeDefinedDatasourceOwners is a private method, and artifact-collections.ts is not touched.

Tests

• packages/runtime/src/app-plugin.datasource-provenance.test.ts (new, 5 cases): the single-package bundle in both datasource spellings, the two-body ADDITIVE packages[] artifact and the option-B artifact (each datasource carries its own body's id and is registered once), and the residual top-level datasource (the artifact's own id, plus the warning). No in-repo example declares a datasource in a multi-package artifact, so the two-body cases are pinned here.
• packages/services/service-datasource/src/__tests__/external-namespace-reads-engine-registry.test.ts (new, 11 cases): the namespace pins now sit on the store the reader reads.
  • The draft is prefixed and carries no TODO.
  • An unprefixed import name is refused with code + status and the shared validator's own ADR-0028 message, and nothing is saved.
  • A prefixed import name is saved, and an import with no override saves the derived prefixed name.
  • The engine is read at each use, and the start and dev orderings give the same answer.
  • Nothing else resolves a namespace: a package item in the metadata service (seeded with a different namespace) is never read, a datasource with no _packageId or with sys_metadata resolves none, a package with no namespace resolves none, and with no engine the documented fallback holds.
• external-metadata-read-at-use.test.ts: the package map the metadata fake seeded (a store no composition fills) is removed. Its two namespace cases and the dev ordering's draft line moved to the file above.
• packages/qa/dogfood/test/external-import-code-datasource-namespace.dogfood.test.ts (new, 7 cases, a real boot of the showcase):
  • Premise: the provenance on GET /meta/datasource/showcase_external.
  • The two ruling pins.
  • Controls: the prefixed import with its rows, the default datasource with no package, the admin service's refusals and its list (the harness mounts no admin routes, so the door's status and code are the dev/start readings above), and validate with the federated read.
• The carry, as triage accepted it:
  • external-import-saves-like-meta.dogfood.test.ts moves to showcase_dogfood_ext_cust_21788. Its control used to import orders under the remote table's own name, a shape the namespace now refuses. It now imports with no name override and asserts the saved name showcase_orders across a cold boot.
  • external-import-destructive-remedy.dogfood.test.ts moves to showcase_dogfood_ext_cust_21841 and …_v2.
  • external-validate-sees-runtime-save.dogfood.test.ts (landed on main by fix(service-datasource): external validate sees a federated object saved at runtime, with no restart #21875 after this PR branched) moves its imported object to showcase_dogfood_ext_ord_21842. Nothing else in it changes: SAVED goes through PUT /meta/object, which runs no namespace check, and the later assertions pass on the renamed object.
  • A repo-wide grep for other pins of an unprefixed import, or of TODO(namespace), on a datasource whose package resolves found none. The remaining draft tests drive ExternalDatasourceService with an injected getNamespace, and the REST tests mock the service.

Runs at 3ec0e9f6, the current head (it carries merges of origin/main at d2ed5e04 and 374ca5cb). Each ran through the shared verify lock, VERDICT command-exit 0:

• pnpm --filter @objectstack/runtime test: 328 files passed, 4644 passed, 19 skipped.
• pnpm --filter @objectstack/service-datasource test: 40 files, 741 passed.
• typecheck for runtime, service-datasource and dogfood: exit 0.
• Dogfood, 6 files (the three import files, external-validate-sees-runtime-save, external-validate-start-ordering and showcase-external-autoconnect): 23 passed.

Ablations (one-time; restored by blob hash and an empty git diff HEAD, then rebuilt)

Every leg went through scripts/ablation-replace.mjs (anchor hit and landed) and scripts/ablation-dist-preflight.mjs (the mutation reached dist/, and the restore removed it).

• W, writer stamp removed (applyProtection(…) replaced by an unstamped copy, runtime rebuilt):
  • The runtime unit file went red, 5 of 5.
  • Dogfood went red, 3 of 7: the premise, the refusal (it answered 201 and saved dogfood_ext_order_21889, the defect itself), and the draft ('orders'). The 4 controls stayed green.
  • The rebuild's DTS step exited 1 on TS6133 (the now-unused applyProtection and owner). The JS was emitted, and the preflight read the stamp absent from dist/index.js.
  • The first attempt was a no-op that the tool refused (the replacement text already occurred inside the anchor). It is void, and the reading above is the second attempt.
• R, reader reverted to asking the metadata service (service-datasource rebuilt, build exit 0):
  • The new service-datasource unit file went red, 8 of 11.
  • Dogfood went red, 2 of 7: the refusal (201) and the draft ('orders'). The premise and the controls stayed green.
• A, every body stamped with the top-level manifest's coordinates (source-level suite, no build): the runtime unit file went red, 3 of 5 (additive, option-B and residual). The two single-package cases stayed green.

Gates

All at 3ec0e9f6.

• node scripts/pm/dispatch-gates.mjs --ran: 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN.
• 73 commands exit 0: those 69, the full pnpm lint (eslint . --no-inline-config), and the three PR-context checks run against this PR (check-closing-target-claim, check-partof-closing-keyword, check-single-claim-paths).
• The dispatch's whole list (134 commands) last ran at f7d3aac1, and every one exits 0. Two of them (check:dual-build-cjs-loads, check:published-readme-exports) exit 0 only after a workspace build cleared their prerequisite.

Acceptance notes

• Wider than the title, by construction. Any datasource that carries _packageId now resolves its package's namespace, including one the metadata plugin's artifact door registers. That was the reader's documented intent all along. It is measured here only on showcase_external.
• Serial: [finding] The metadata door saves an edit to a code-defined datasource (PUT /api/v1/meta/datasource/:name answers 200) and the metadata read then serves it, while the datasource admin door refuses the same edit as read-only #21899 remains open and owns the metadata door's refusal for origin: 'code' datasources. Until it lands, a meta-door save can replace the stamped item and drop _packageId.
• fix(service-datasource): external validate sees a federated object saved at runtime, with no restart #21875 landed first. This PR carries both docblock words its reader change made false (the metadata() docblock and MetadataServiceLike), and moves fix(service-datasource): external validate sees a federated object saved at runtime, with no restart #21875's runtime-save validate pin to the prefixed import name.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/kernel/services-checklist.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/permissions/capabilities.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/permissions/system-context.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/plugins/index.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/protocol/kernel/plugin-spec.mdx (via AppPlugin (symbol, a top-level class))

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

• content/docs/releases/v15.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via AppPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via AppPlugin (symbol, a top-level class))

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

• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 26 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 cab639671528ef6f3a201e8995794378a4a28bfe → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

Five checks on head 3ec0e9f6 were cancelled because no runner picked them up. No test failed, and nothing here is this PR's to fix. Read by the domain:cli seat (session_01RWZbGvPFcRKvUqASZtunCU) at 2026-10-05T21:19Z.

• Which checks, and why:
  • Test Core, the rollup (CI run 37361292771). All six shards ran and passed at 19:09–19:43Z. The rollup job then sat unacquired and was cancelled at 19:58Z.
  • The four body-reading gates that re-ran on the PR-body edit at 19:48:40Z: The card this PR closes must claim this branch, Part-of PR must not also close its card, No other open PR may claim the same issue and Check Changeset (runs 37365791677, 37365791576, 37365791548, 37365791444). Each was cancelled at 20:03:43Z.
  • In each case the job carries no runner name, and the check annotation reads "The job was not acquired by Runner of type hosted even after multiple attempts". Every one of these checks already passed on this same head in its 19:09Z run.
• What is needed: one "Re-run failed jobs" on those five runs. The rest of CI on 3ec0e9f6 is green, with expected skips only.
• Why the seat does not do it: its write channel (the fleet relay) has no workflow re-run op, and it writes nothing through other channels. ⛔ No empty commit and no close/reopen to kick CI.

The seat keeps this PR watched. Once these five are green, it runs the landing pre-checks and lands.