fix(service-datasource)!: an object imported from a package's external datasource is saved into that package or its customization package - #30602

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 19 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-datasource/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

33 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json bdbaf80cdb01ececd5af069757fb1f35c653bb8a.

⛔ 14 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 30c41ab2cf5c1418e009eee1a827db5266d1b452 && git checkout 30c41ab2cf5c1418e009eee1a827db5266d1b452
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin bdbaf80cdb01ececd5af069757fb1f35c653bb8a 100d47a7055d824e7733fc68075a2732d6c2a6b9 && git checkout -B drift-repro bdbaf80cdb01ececd5af069757fb1f35c653bb8a && git merge --no-ff 100d47a7055d824e7733fc68075a2732d6c2a6b9

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

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

domain:server#6 · os-bill · session_01Utp6CXCS98uhsFQYk64epE

Contract-review-claim: session_01Utp6CXCS98uhsFQYk64epE · head 100d47a · 2026-11-05T17:42Z

domain:server#6 · os-bill · session_01Utp6CXCS98uhsFQYk64epE

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 100d47a7055d824e7733fc68075a2732d6c2a6b9
Local-runs: none
Scope: packages/services/service-datasource/src/plugin.ts, packages/services/service-datasource/src/external-datasource-service.ts, packages/services/service-datasource/src/index.ts, packages/services/service-datasource/src/tests/external-namespace-reads-engine-registry.test.ts, packages/qa/dogfood/test/external-import-code-datasource-namespace.dogfood.test.ts, packages/qa/dogfood/test/external-federation-read-capability.dogfood.test.ts, packages/qa/dogfood/test/external-import-destructive-remedy.dogfood.test.ts, packages/qa/dogfood/test/external-import-saves-like-meta.dogfood.test.ts, packages/qa/dogfood/test/external-validate-sees-runtime-save.dogfood.test.ts + packages/metadata-protocol/src/package-writability.ts, packages/metadata-protocol/src/protocol-customization-package.ts, packages/metadata-protocol/src/protocol-save.ts (NAMESPACE_PREFIX and the ADR-0070 writability gate), packages/metadata-protocol/src/protocol-tenant-authored-write.ts, packages/core/src/security/admission-tenancy-posture.ts, packages/core/src/security/authz-store-unavailable.ts, packages/spec/src/security/tenancy-posture.ts, packages/spec/src/kernel/customization-package.ts, packages/spec/src/contracts/external-datasource-service.ts, packages/rest/src/external-datasource-routes.ts, packages/rest/src/error-response.ts, packages/runtime/src/domains/packages.ts (ensure route, refuseWalledCatalogPackageWrite), packages/runtime/src/domains/mcp.ts, packages/mcp/src/mcp-http-tools.ts, packages/services/service-datasource/src/admin-routes.ts, docs/adr/0146 D2/D3/D11, docs/adr/0070 D3, docs/adr/0131 D3, docs/adr/0028, content/docs/data-modeling/odata-datasources.mdx, .changeset/30469-import-lands-in-datasource-package.md (read for ②, not reviewed). Not reviewed: nothing else is in the diff (10 files, 0 governed, no lockfile or generated output).

Inputs: card #30469 body and all 8 comments (ruling B is record 6660988968; the dev's os-dev-report is 6664934445), PR #30602 body, file list and the net diff bdbaf80c…main...100d47a7, and the head's 46 check-runs. Gate verdicts at review time: every completed run is success or skipped (Check Changeset — which carries the ADR-0087 disposition step —, Governed Surface Queue Guard, Dogfood Regression Gate, Test UI, Check PR Size, Spec property liveness, PR-body guards, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests); still in_progress, not waited on: Build Core, Test Core (1–8/8), Type Check · (source gates, workspace, debt ledger, consumer gates), Lint · (ESLint, repo & tooling gates, docs & code guards, CI/release/engine gates, scoped · query-options erasure, scoped · slot lookup & corpus), Live E2E UI. The seat lands only once those are success.

① Derived judgments

Accept-set moves at POST /datasources/:name/external/tables/:remote/import and the MCP import_object (both reach ExternalDatasourceService.importObject; the draft door is untouched):

1. Datasource with no _packageId, the sys_metadata sentinel, or an unreadable row → package-less save, request byte-identical to before (persistObject adds packageId only when set). Right — ruling item 1; pinned by the two controls.
2. Datasource declared by a writable package (isWritablePackage on the 'protocol' service, the save door's own ADR-0070 predicate) → saved with that packageId, named in its namespace. Right — ruling item 1; the save door's writability gate (protocol-save.ts ~L1880) admits it.
3. Datasource declared by a read-only installed base, non-walled posture → ensureCustomizationPackage({ basePackageId }) right before the save, saved into the pair BASE.custom, named BASE_NS_custom_TABLE. Right — the name is the one objectNamespacePrefixViolation judges against the WRITTEN package (protocol-save.ts ~L928), measured by the dev and pinned by the showcase dogfood; the pair comes from the one creation path ADR-0146 D3 names.
4. Explicit name in the base's own namespace over a read-only base → refused 400 EXTERNAL_IMPORT_ERROR with ADR-0028's prescription for the pair namespace, before the pair and before introspection. Right, and the BREAKING narrowing — previously accepted and saved package-less under a name the pair could never hold.
5. Walled posture (group/isolated, read through classifyAdmissionTenancyPosture), pair absent → refused 400 EXTERNAL_IMPORT_ERROR naming the platform operator and POST /api/v1/packages/BASE/ensure-customization; nothing saved, no pair made. Right — mirrors the ensure route's walled refusal (packages.ts L2755–2760, refuseWalledCatalogPackageWrite) instead of side-stepping it with a package-less row (ADR-0070 D3's forbidden fallback).
6. Walled posture, pair present → saved into it, ensure door not asked. Right as ruled (B); the caller-side remainder is the out-of-band observation in ④.
7. 'protocol' service without isWritablePackage/ensureCustomizationPackage and a packaged datasource → refused, nothing saved. Right — no guessing; a host without the doors keeps the old placement only through a config that wires no resolveImportLanding.
8. Public surface (@objectstack/service-datasource): ImportLanding type exported from index.ts; ExternalDatasourceServiceConfig.resolveImportLanding?; persistObject's optional third packageId. All additive widenings, right; a host-built config without them behaves as on main (importLanding() falls back to getNamespace).
9. plugin.ts now value-imports @objectstack/core (was type-only). Right — @objectstack/core is a runtime dependency of the package and admin-routes.ts already value-imports it.
10. Tenancy read: kernel getServiceAsync('tenancy') with the same accessor-presence guard the datasource admin routes use; a LiteKernel host answers undefined and takes the non-walled path. Right — the per-seam justification matches admin-routes.ts L440–466.

② Semver level

.changeset/30469-import-lands-in-datasource-package.md: '@objectstack/service-datasource': patch, title with !, body **BREAKING** accept-set narrowing. Clause-②: yes (narrowing) in the PR body and the changeset, line-initial, identical — matches the diff (item ①4 and ①5 are refusals of previously accepted requests). Metadata-protocol: none — right: no key, value or type an author writes changes; ImportObjectOpts (packages/spec/src/contracts/external-datasource-service.ts) keeps its shape, and packages/spec is untouched (the ruling's item 4). none ⇒ patch per the Post-Task Checklist rule (a non-protocol breaking change ships patch with its banner and disposition); the three public-surface widenings in ①8 ride the same patch. ADR-0087 marker: exactly one, not-required (no-migration-prescription); the gate that re-validates that category against the changeset's own prose runs inside Check Changeset, which is success on this head. Skills-docs: none holds: skills/** and content/docs/data-modeling/odata-datasources.mdx name the import without saying where it lands or what it is named.

③ Boundary flags

From the os-dev-report (6664934445):

• Five packages/qa/dogfood files outside the claimed surface. Answered: accepted. Four carry explicit import names in the base namespace that ①4 now refuses (stale fixtures the change reds, fixed in the same PR as os-dev.md allows); the fifth holds the showcase pins the dispatch asked for.
• Walled clause built as the seat's pick A (never creates under a wall; refuses while the pair is absent) rather than relaying an ensure-door 403. Answered: accepted in substance — the ruling's three fixed points hold (never package-less, names the operator and the route, no pair made by an import). What pick A leaves open at the caller is the out-of-band observation in ④.
• Metadata-protocol: none where the claim was provisional. Answered: right (②).
• PR body order; model-free commit trailers. Not this review's to judge; nothing in the diff turns on them.
• security_findings: "withheld". Per .claude/agents/os-dev.md, the public comment always reads withheld/none and the finding itself lives only in the dev's private final report. withheld rather than none means the private report carries one. Escalated to the seat: read the dev's final report's security_findings and reconcile it with the out-of-band note before landing.
• out_of_scope_findings: ADR-0146 D3 "It receives" + D11 half-sentence — the maintainer's Tier H todo per ruling item 5, correctly not edited here; the import's label (toLabel(name) ⇒ Showcase Custom Customers) — noted, not a defect of this card.
• open_questions: none. Confirmed; the ruling's open check (prefix rule read, not run) was closed by the dev's measurement on a booted showcase and the dogfood pin.

④ Design judgment

The narrowing against the published spec on main. IExternalDatasourceService.importObject and ImportObjectOpts declare no placement and no namespace for the saved object; the docs say "Import saves one". Nothing declared at the consumer is taken away. What the narrowing makes real are two refusals the spec's own doors already own: the save door's NAMESPACE_PREFIX rule judged against the package written (protocol-save.ts, ADR-0129 D2 / ADR-0028), which the package-less import had been slipping past, and the ensure route's walled refusal (packages.ts, ADR-0131 D12 / ADR-0146 D3), which a package-less landing would have made moot. Ordering holds under reading: landing → explicit-name verdict → draft (introspection) → prepare → save, so every refusal writes nothing and makes no pair (pinned, with an ablation of the walled condition). Ruling item 3 (no migration, old rows untouched, re-import lands beside) is pinned on the showcase.

Attempts to break it, and what held:

• Pair present but malformed (non-walled): the derived namespace names the object, the ensure door refuses 409, the import refuses, nothing saved. Holds.
• Writable _packageId not installed in the registry: namespace absent, save names the package, the save door's uninstalledNamedBaseRefusal refuses. Holds — no silent package-less landing.
• Unreadable datasource row → package-less: the ruling's item 1 says so explicitly; noted that the same catch now decides placement, not only the prefix (as before).
• single with a registered tenancy service, and a host with no async accessor: both reach the ensure door, consistent with the ensure route's single rule (manage_metadata, which the REST import route and the MCP write kind both require via federationCapabilityRefusal).

should-fix (one card, packages/rest, outside this PR's surface): the posture read can throw AuthzStoreUnavailableError (status 503, code SERVICE_UNAVAILABLE — a registered tenancy service that cannot answer, by the #16013 rule in admission-tenancy-posture.ts). external-datasource-routes.ts answerThrown relays only sandbox faults and 404 RESOURCE_NOT_FOUND, so the REST import route serves that outage as 400 EXTERNAL_IMPORT_ERROR — "your request was malformed" where the truth is "retry". Nothing is saved, so it is not permissive; but the twin in admin-routes.ts (badRequest) already relays the 503/SERVICE_UNAVAILABLE envelope, and the MCP tool relays it correctly (thrownRefusalEnvelope reads status and code). Remedy: give answerThrown the same 503 relay badRequest has, with a pin. This PR is the first thrower of that class on the federation import path, which is why it surfaces here.

should-fix (one card): one security observation handed to the seat out of band (pre-existing at this door on main; this PR's walled clause inherits it rather than creates it).

No must-fix.

Implemented-by: claude/project-thread-0aje2v
Reviewed-by: session_01Utp6CXCS98uhsFQYk64epE

VERDICT: PASS

domain:server#6 · os-bill · session_01Utp6CXCS98uhsFQYk64epE

席位记录 · 2026-11-05T18:04Z · Head-sha 100d47a7 · ACCEPT

维护者速读(席位按 diff 校正)

• 改了什么：从外部数据源导入的表，按数据源归属来存。Setup 里加的数据源照旧不进包；可写包声明的数据源，存进该包；只读已装包声明的数据源，存进它的定制包 包名.custom，跟着该包导出。只读包下导入的对象名换成定制包前缀，例如 showcase 的 customers 从 showcase_customers 变成 showcase_custom_customers。
• 为什么改：Datasource table sync: the generated object draft gives its fields no label, so forms show raw column names; where the synced object lives (package, export) is unstated #30469 第 2 项，你 14:46Z 裁定 B（裁定记录 6660988968）。之前导入对象的名字说属于某个包，存储却不在任何包里，包导出带不走。
• 风险与回滚：BREAKING 收窄，有两处变化。一是只读包数据源上沿用旧前缀的显式名字会被拒，提示里给出新名字。二是墙内形态（group/isolated）下定制包还不存在时，导入被拒，提示请平台运营方先建。已导入的旧对象不迁移、不改名。回滚即 revert 本 PR。
• 先看：service-datasource 的 plugin.ts（resolveImportLanding）和 external-datasource-service.ts（importObject 先定落点，最后才建定制包、保存）。
• 两分钟验证：pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/external-namespace-reads-engine-registry.test.ts -t "lands in the package of its datasource"，14 条通过。
• 需要你做的：无。非受管面、非 Tier H、667 行，收窄的 CONTRACT_REVIEW_TIER 全量复核 PASS（6665235060），技能不要求你审，席位落地。ADR-0146 D3/D11 两句仍是你的 Tier H 待办。

席位意见：同意落地。这次收窄不拿走 spec 声明过的能力：ImportObjectOpts 没有声明落点或命名。它让保存门已有的 NAMESPACE_PREFIX 规则和 ensure 门的墙内拒绝真正生效。各种拒绝都发生在建定制包和保存之前，所以被拒的导入什么都不写。

席位核对

1. 形态：draft→ready，目标 main，Fixes #30469（item 1 已由 fix(service-datasource): fields of an object drafted from a datasource table carry a readable label #30530 落地，本 PR 交付 item 2，卡随之关闭）；作者 objectstack-fleet[bot]（中继）。
2. 前提实测：报告 6664934445 在合并基上有 10 条单测红、4 条 showcase 红，消融一次转红后已还原。全量 dogfood 3500 条通过，66 道派生门禁全过。
3. 门禁 check-runs(钉 head 100d47a7)：全部 success 或 skipped，0 失败（落地前席位复读）。
4. 接受的偏差：5 个 packages/qa/dogfood 文件在认领面外：其中 4 个是被本次收窄打红的旧显式名，1 个是派单要求的 showcase 钉。墙内分支按席位 15:06Z 选的 A 实现：从不建定制包，已有定制包就存进去。两项都接受。
5. 范围外去向：复核的两条 should-fix 去向如下。REST 导入把 tenancy 服务故障答成 400，已立卡 External import over REST answers a tenancy-service outage as 400 instead of 503 #30609（p3）。另一条按 security-findings 规则走私有渠道，已交 security#1，不在此处写。Skills-docs: none 成立。changeset patch，Clause-②: yes (narrowing)，Metadata-protocol: none，ADR-0087 not-required。
6. 落地条款：check-governed-merges --pr 30602 结果 NOT governed，667 行 ≤ 3000，非 Tier H；按 13:47Z 规则，BREAKING 不等维护者，复核 PASS 且全绿后席位 ready + auto-merge。合并后席位在 Datasource table sync: the generated object draft gives its fields no label, so forms show raw column names; where the synced object lives (package, export) is unstated #30469 写落地并结线程。