fix(service-datasource)!: Sync refuses a managed datasource with the existing 400 (ADR-0015 §4.2) - #25167

📓 Docs Drift Check

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

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

• content/docs/releases/v17/17-2.mdx (via datasources.external.draft (sdk, the route ledger binds it to POST /api/v1/datasources/:name/external/tables/:remote/draft, selected by route anchor /tables/:remote/draft), datasources.external.import (sdk, the route ledger binds it to POST /api/v1/datasources/:name/external/tables/:remote/import, selected by route anchor /tables/:remote/import), /tables/:remote/draft (route, bridged from symbol generateObjectDraft — its route source's handler names it), /tables/:remote/import (route, bridged from symbol importObject — its route source's handler names it))
• content/docs/releases/v17/17-7.mdx (via EXTERNAL_IMPORT_ERROR (literal, a string literal in importObject; a string literal in notAFederationSourceError; a string literal in primaryDatasourceNotFederatedError))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c646f942b89c5fb88062ba85657064c4f10773b1 && git checkout c646f942b89c5fb88062ba85657064c4f10773b1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 425c743fd9b80005d83e528dfdc8a5f8c68c8b30 658d9d0b54fb68201710b21904e6adf9e8b03159 && git checkout -B drift-repro 425c743fd9b80005d83e528dfdc8a5f8c68c8b30 && git merge --no-ff 658d9d0b54fb68201710b21904e6adf9e8b03159

node scripts/docs-audit/affected-docs.mjs --json 425c743fd9b80005d83e528dfdc8a5f8c68c8b30

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 658d9d0b54fb68201710b21904e6adf9e8b03159
Local-runs: none
Scope: packages/services/service-datasource/src/external-datasource-service.ts, packages/services/service-datasource/src/tests/managed-datasource-sync-refusal.test.ts, packages/services/service-datasource/src/tests/primary-datasource-test-and-sync.test.ts, packages/services/service-datasource/src/tests/external-metadata-read-at-use.test.ts, packages/rest/src/remote-tables-twin.equivalence.test.ts + packages/rest/src/external-datasource-routes.ts, packages/services/service-datasource/src/admin-routes.ts, packages/services/service-datasource/src/plugin.ts, packages/spec/src/data/datasource.zod.ts, packages/spec/src/data/object.zod.ts, docs/adr/0015-external-datasource-federation.md

Inputs: card #24837 (body and comments 6331033735, 6332488694, 6332519276, 6332527785), PR #25167 (body, file list, the net diff of this head against main: 6 files, +550/-53), and the check-runs on this head. The five required contexts are success on this head (Lint & Repo Gates, TypeScript Type Check, Test Core, Build Core, Governed Surface Queue Guard); Check Changeset and Check PR Size are success; the PR-run Dogfood Regression Gate is success (fast set; its shards skipped by path). Nothing was built, run or re-run locally.

① Derived judgments

(a) The accept set of the six Sync doors, each read to its producer and its catch — right. The one producer is ExternalDatasourceService; the new private assertFederationSource(datasource, door) is the first statement of listRemoteTables, generateObjectDraft, importObject and refreshCatalog. It refuses, in this order: default by name (primaryDatasourceNotFederatedError, unchanged text), then anything isFederationSource(ds) rejects, where isFederationSource is Boolean(ds?.schemaMode) && ds?.schemaMode !== 'managed' over config.getDatasource(name). That rejects exactly three shapes: a declared schemaMode: 'managed', a definition with no schemaMode, and no definition at all (undefined); with SchemaModeSchema closed to managed | external | validate-only, nothing else is refused. Codes and statuses per door, read in the cited code:

• admin GET /datasources/:name/remote-tables and POST /datasources/:name/object-draft (admin-routes.ts): the handler calls the service inside try, and badRequest answers 400 with SERVICE_ERROR_CODE['external-datasource'] = EXTERNAL_DATASOURCE_ERROR for every throw except a 503 SERVICE_UNAVAILABLE relay (the guard throws status: 400, so the relay arm is not taken). Right.
• REST GET …/external/tables, POST …/external/tables/:remote/draft, POST …/external/refresh-catalog (external-datasource-routes.ts): the catch is refused, i.e. answerThrown(res, err, 'EXTERNAL_DATASOURCE_ERROR'), which answers 400 with that literal code for any non-sandbox throw. Right.
• REST POST …/external/tables/:remote/import: the catch is answerThrown(res, err, 'EXTERNAL_IMPORT_ERROR'), 400 with that code for every refusal — the code that door already served for default's refusal and for every other refusal it relays. The guard's door: 'import' spells the same code at the throw, so the declaration and the served envelope agree. Right, and the card's literal "EXTERNAL_DATASOURCE_ERROR for Sync's three routes" is correctly read as "the code each door already serves": no code is minted or moved, and check:dispatcher-error-vocabulary reads both literals (green in Lint & Repo Gates).
• A name with no definition answers 400, not 404: on these doors an unknown name already answered 400 EXTERNAL_DATASOURCE_ERROR (the introspector's "no driver introspection available" throw, through the same catch), so 400 is the existing answer and a 404 would have been a new code on the door. Right under the card's constraint.

(b) external and validate-only keep every answer — right. isFederationSource admits both. listRemoteTables reads the same definition it read before (now from the guard's return instead of Promise.all, a serialisation with no answer change) and keeps the allowedSchemas and unattributed-schema logic byte for byte; generateObjectDraft delegates to the private draftObject, which is the old body unchanged; importObject keeps its persistObject, name and prefix checks and now calls draftObject instead of re-entering generateObjectDraft (one judgment per request, under the import's own code); refreshCatalog is the old body after the guard. testConnection does not call the guard (Test is unchanged). The pins hold lake (external) and mirror (validate-only) at 200 list, 200 draft, an import that saves one object, and a refresh, over the real ObjectQL, connection service, driver factory, plugin wiring and Hono admin routes; the twin fixture now declares schemaMode: 'external' and its 10 cases compare both spellings on a federation source, which is what twin equivalence needs.

(c) default's existing refusal — unchanged. The guard's first line is the DEFAULT_DATASOURCE_NAME check with the same helper and the same message; it still precedes any definition read. The door-kind parameter yields EXTERNAL_IMPORT_ERROR on the import and EXTERNAL_DATASOURCE_ERROR elsewhere, the two literals main passed in by hand. Pinned ("remote-tables on default answers as #24772 left it").

(d) Decided before any introspection — right. All four methods await the guard before config.introspect; main's listRemoteTables ran introspect and getDatasource concurrently, so a refused datasource WAS introspected there, and is not now. The REST and admin handlers call nothing but the admission gate before the service. Pinned twice: introspectSchema spies on every managed driver and the primary one stay uncalled across all four doors, and introspectDatasource is uncalled for an undeclared name.

(e) The seat's answer A (refuse a name with no definition) — consistent, a narrowing within ADR-0015, not a widening beyond it. The spec default is schemaMode: SchemaModeSchema.default('managed') (datasource.zod.ts), so a definition without the key is managed; ADR-0015 §1 makes remote-ness a property the datasource DECLARES (schemaMode !== 'managed'), and §4.2 allows object.external only there — a name nothing declares has declared no such thing. validateObject on main already read !ds as "not federated, nothing to validate", so before this PR an import on such a name produced an object the sweep never checked and the §5.3 write gate (which exempts managed datasources) never gated; A closes that with the one predicate both now ask. The composition cost is the hypothetical one the dev named: a host whose live drivers have no datasource record in the 'metadata' service. plugin.ts wires getDatasource to metadata().get('datasource', n) resolved per call, and the dev's federation dogfood (the booted showcase's code-declared showcase_external, 20 tests) and the full battery passed on 145e52859, which is the evidence that the shipped composition does read code-declared datasources through that door. The reversed pin in external-metadata-read-at-use is the honest record of the change and keeps the validate half.

Public-surface changes implied by the diff, each named: the four REST doors' and two admin doors' accept set narrows on the three shapes above (right, the card's route B); validateObject / validateDatasource / validateAll semantics unchanged (!ds || !ds.schemaMode || ds.schemaMode === 'managed' is exactly !isFederationSource(ds)); no export, type, route, query parameter, status or code is added or removed; packages/rest source is untouched; packages/spec, packages/objectql, objectui and ADR-0015 are untouched, as the claim required.

② Semver level

Right. The changeset is '@objectstack/service-datasource': patch with Clause-②: no (narrowing) and Metadata-protocol: none on their own line-initial lines, a **BREAKING** banner, FROM / TO / Unchanged / fix-for-an-integrator lines, and the adr-0087 marker not-required (no-migration-prescription); the PR body carries the same two declaration lines and the title carries !. Metadata-protocol: none is the correct kind: no key, accepted value, default or meaning that an author writes moves (the datasource schema and the object schema are untouched; the authoring door for object.external on a managed datasource is deliberately not narrowed here, see ③). A non-protocol breaking change ships patch with its banner and disposition (AGENTS.md Post-Task Checklist step 3, the closed card #25105's ruling A as the brief states it). Check Changeset is success on this head, and the dev reports the level axis and check-adr-0087-registration exit 0 on the body.

The (narrowing) arm's full dogfood battery: run by the dev on 145e52859 (VERDICT command-exit 0, Test Files 287 passed, 3 skipped; Tests 2395 passed, 18 skipped). This head is 145e52859 plus exactly one hunk: one line in packages/rest/src/remote-tables-twin.equivalence.test.ts (the fixture's schemaMode: 'external' as const). That file is a vitest file, not a build input (packages/rest publishes dist only; nothing outside it imports it), and the dogfood battery is @objectstack/dogfood's own suite over a booted app, so none of the battery's inputs moved between 145e52859 and this head. The battery stands for this head. The PR-run Dogfood Regression Gate on this head is success (the fast set, as PR runs carry); the full battery runs on main after landing.

③ Boundary flags

1. Console still offers "Sync objects" on managed rows (PR Acceptance notes; dev finding 1). Routed by the seat: an objectui card is filed when this PR lands (6332519276, item 1). Until then the button on a managed row opens the dialog with this refusal's message, which names the rule and the remedy, so the console is not silently broken. Not this PR's.
2. ADR-0015 §4.2's "enforced at metadata-load time" has no enforcing site: defineStack and the metadata save door accept object.external on a managed datasource (dev finding 2). Routed by the seat as ADR-0015 §4.2 is declared "enforced at metadata-load time", but defineStack (and, unmeasured, the metadata save door) accepts an object.external binding on a datasource whose schemaMode is managed #25168 for triage (spec or objectql lane). This PR closes the Sync producer of such objects only, and says so; retiring or amending the rule would be an ADR change this PR correctly does not take.
3. No ADR anchor JSON for the guard (scripts/adr-anchors/). Answered, not blocking: the ADR id is in the code and the refusal text, check:adr-anchors is green, and no anchor for ADR-0015 names this service today (the only anchor citing 0015 is packages__objectql__src__search-companion.ts.json), so the omission adds no drift. Escalated to the seat as a lane follow-up: anchor assertFederationSource under Prime Directive 13's corollary when the file surface is declared.
4. REST-door refusal pins (draft, import, refresh on a managed datasource) measured once, not committed (they belong in packages/rest, domain:cli). Answered, not blocking: the REST catches map every service throw to a fixed 400 code per door by construction (read above), and the service-level pins hold each method's code and status; the twin test pins the external list path at 200 on both spellings. Escalated to the seat: a packages/rest pin of the four doors refusing a managed datasource with their codes, alongside the twin file, when the lane declares it.
5. The import door answers EXTERNAL_IMPORT_ERROR, and refresh-catalog is refused too (dev deviations, accepted by the seat in 6332519276). Both right: see ①(a); the fourth method sits behind the same producer and default's refusal already covered it.
6. origin/main not merged before opening; first commit titled wip(…). main has moved by docs and spec-prose commits with no overlap with the touched packages; the PR is mergeable clean, and the queue rebuilds the merge. The squash landing takes the PR title. No action.

Implemented-by: claude/issue-24837-managed-datasource-sync
Reviewed-by: session_01UnHcTADjeg3VwxF21QHj7W

VERDICT: PASS

Generated by Claude Code

席位核对

domain:services seat 2 (seat post #21118) · os-bill · session_01UnHcTADjeg3VwxF21QHj7W · 2026-10-22T06:00Z · ACCEPT at head 658d9d0b54fb68201710b21904e6adf9e8b03159 · dev reports on #24837 (round 1 6332488694, patch round 6333805584)

1. Shape: a draft PR to main whose first line is Fixes #24837, assigned os-bill, title marked !.
   • Clause-②: no (narrowing) and Metadata-protocol: none are at line start in the body and the changeset. The changeset carries the BREAKING banner, the FROM / TO / Unchanged / fix-for-an-integrator lines and the ADR-0087 marker not-required (no-migration-prescription). The level is patch under changeset levels: minor only when the metadata protocol changes (added / narrowed / semantic), patch otherwise; release notes grouped by what the reader must do (maintainer ruling A, 2026-10-21) #25105 ruling A.
   • The file surface is the amended claim 6332527785. The one packages/rest fixture line is declared cross-lane on [PM seat] domain:cli · seat 2 — ⏳ vacant #22648 (6332535245). Nothing under packages/spec, packages/objectql or objectui is touched.
2. Premises measured (round 1, re-read on the patch head):
   • the Sync doors refused only default, and a runtime datasource saved in Setup with no schemaMode (managed by the spec's default) listed, drafted and imported;
   • the seat's answers 6332519276 hold in the code: a name with no definition is refused (answer A), the import keeps EXTERNAL_IMPORT_ERROR, and the catalog refresh sits behind the same guard.
3. Gates (check-runs pinned to this head, the newest run of each name):
   • 32 success, including Lint & Repo Gates, TypeScript Type Check, Build Core, Governed Surface Queue Guard, Check Changeset, Dogfood Regression Gate and Test Core 1–6.
   • 9 skipped, each on the check-expected-skips.mjs roster. Auto Label and Check PR Size skip on the run the seat's body edit started and were success on the push run, as the roster records for an edited body.
   • mergeable_state: clean. check-governed-merges.mjs --pr 25167: NOT governed, +550 / −53.
   • Contract review at CONTRACT_REVIEW_TIER (isolated reviewer): PASS, 6333095709, on this head. It confirmed:
     • the six doors refuse exactly a declared managed datasource, one with no schemaMode and a name with no definition, each with the 400 code that door already served, and no code is minted;
     • external and validate-only keep every answer, and default's refusal is unchanged;
     • the refusal is decided before any introspection (main introspected a refused datasource concurrently);
     • answer A is a narrowing within ADR-0015, not beyond it;
     • the full dogfood battery run on 145e52859 stands for this head, whose one added line is a test fixture no battery input reads.
4. Seat read of the diff (beyond the review): the changeset's remedy for a runtime datasource holds in the code. PATCH /datasources/:name accepts schemaMode and external (RECORD_JUDGED_PATCH_KEYS), the Setup door stores the record with metadata.register('datasource', …), and the guard reads metadata.get('datasource', …), which is the same store. So a datasource re-declared external is admitted on its next Sync.
5. Accepted deviations: origin/main was not merged before opening, and the first commit is titled wip(…). The PR is clean, and the queue landing takes the PR title as the commit subject. The net diff is unaffected.
6. Out of scope (all in the PR's Acceptance notes, with carriers):
   • the console still offers "Sync objects" on managed rows → an objectui card, filed by the seat at landing;
   • ADR-0015 §4.2's authoring and load half has no enforcing site → ADR-0015 §4.2 is declared "enforced at metadata-load time", but defineStack (and, unmeasured, the metadata save door) accepts an object.external binding on a datasource whose schemaMode is managed #25168, for triage;
   • no ADR anchor file for the guard, and no committed packages/rest pins of the four REST doors' refusals → named by the review as lane follow-ups; carrier none (no user-visible defect).

Landing: ordinary queue landing. The seat sets ready and auto-merge through the relay in this act. After the merge, #24837 closes by Fixes; the seat removes pm:dispatched, files the objectui card and records the landing.

Changeset sentences checked against the diff:

• FROM: the six requests on a managed datasource answered with tables, drafts, a saved import and a stored catalog, and an undeclared name was introspected;
• TO: each answers the door's existing 400 code with the rule and the remedy, nothing is introspected, drafted, saved or stored, and an undeclared name gets the same refusal;
• Unchanged: default's refusal, the two federation modes, Test and validation (validation now asks the same predicate), and no code added;
• the fix for an integrator: declare external or validate-only, by PATCH for a runtime datasource.

All hold.

Generated by Claude Code