fix(service-datasource): a destructive re-import's refusal names the remedies that work from the import route

[objectstack-fleet]

Fixes #21841
Clause-②: yes (widening)

What this changes

"Import as Object" (POST /api/v1/datasources/:name/external/tables/:remote/import) saves through the metadata door's saveMetaItem. A re-import that would drop a field the stored object still carries is refused by that save's destructive-change gate, and the import route relays the refusal as 400 EXTERNAL_IMPORT_ERROR. The refusal ended re-submit with ?force=true to proceed. The import route reads no force, so following that sentence returned the identical refusal.

• persistObject (packages/services/service-datasource/src/plugin.ts) now sends writeFace: 'external-import' on its save. The server states the face. The import's options cannot carry a face or a force into the save (pinned).
• destructiveChangeRemedy (packages/metadata-protocol/src/protocol.ts) gains a case for that face, in the existing faces' grammar: name the door, deny the mechanism, then prescribe. The served sentence is now: this import cannot be forced: the external-table import route accepts no force. Import the table under a new name, or save the changed definition of 'NAME' through PUT /api/v1/meta/object/NAME?force=true, which accepts the destructive change on purpose. Those are the words of the import's earlier changeset.
• SaveMetaItemRequestSchema.writeFace (packages/spec/src/api/protocol.zod.ts) and the local MetadataWriteFace gain the one member. The reference row is regenerated.
• The refusal itself stays: still 400 EXTERNAL_IMPORT_ERROR, and the stored definition does not move (pinned before and after). The other faces' text is unchanged. On this face the 422 clause keeps its full-prose default, because the import route's envelope carries no issues. That is pinned, and ablated below.

Route taken: an import face, not a working force (four axes)

All four axes point the same way, so there is no trade-off to hand up.

• Business need (measured). The external-table import route has no first-party caller that re-imports. In objectui at the pinned .objectui-sha 0abd4f9f (and at its main f1a177c), there are 0 calls of that route. The console's import dialog (importObjectDraft, app-shell/src/views/metadata-admin/external/api.ts) calls POST …/draft and then PUT /api/v1/meta/object/:name. Control: the draft route and the PUT both hit in that file. In this repo at 2df3d13d, there are 0 callers of datasources.external.import( outside packages/client. That SDK method sends its options as a JSON body and has no query-string channel at all. The door the face names already serves this case, from raw HTTP and from the SDK (meta.saveItem(…, { force: true })). The door pin measures it at 200. A force on the import route would have zero pull.
• Long-term soundness. This follows the precedent the class's earlier ruling set. A force was threaded only where a twin door already read it. The import route has no such twin. Acknowledging a destructive change stays on one door, where the caller authors the whole definition. A working force here would also add a query parameter to a route with no closed query set, and a force through IExternalDatasourceService.importObject's published contract.
• Preventing AI mistakes. Both routes make the sentence true. But a force on the import would let a body that holds only table options overwrite an existing object's fields under a colliding name, including an object no import created. The face keeps the stricter contract: the import never overwrites destructively.
• Startup focus. The face costs one enum member, one case and one call-site argument. A force would be a new accepted parameter on a REST route plus a service-contract change, with no caller.

Measured

• H1 reproduced first (red pin committed in 28bf4c43, run on base src and base metadata-protocol dist/): Tests 3 failed | 1 passed (4). Served message: … Field 'region' removed — existing data in this column will become inaccessible. — re-submit with ?force=true to proceed. The case that follows that prescription got past expect(followed).toBe(message): the import with ?force=true answered the byte-identical refusal, and the stored definition was unchanged.
• After (HEAD 5e5dedaa): the door pin test/external-import-destructive-remedy.dogfood.test.ts passes Tests 4 passed (4). Run beside fix(service-datasource)!: Import as Object saves through the metadata door's save #21837's pin, Test Files 2 passed / Tests 7 passed. Each remedy is followed: the import under a new name answers 201 and serves 3 rows, and PUT /api/v1/meta/object/NAME?force=true answers 200 and drops region. Control: the same PUT without force answers 409 DESTRUCTIVE_CHANGE with the stored definition unchanged.
• Ablation 1 (scripts/ablation-replace.mjs, the import stops stating its face; plugin.ts blob b0385ebd to 2c89cd8f, anchor x1 to x0). Direction predicted before running. Door pin Tests 3 failed | 1 passed (4), with the served text back to re-submit with ?force=true to proceed.. Seam pin Tests 2 failed | 3 passed (5). The dogfood alias resolves @objectstack/service-datasource to src, so no rebuild. Restore: blob b0385ebd equals HEAD, git diff HEAD empty.
• Ablation 2 (case 'external-import': unmatched in protocol.ts; blob 4e881baf to 66cce7ad). Face inventory Tests 2 failed | 24 passed (26), exactly the "never re-submit" and "names the door" cases. Restore proven, blob equals HEAD.
• Ablation 3 (the import face added to the 422 trimming case; blob 4e881baf to d1f48892). Face inventory Tests 1 failed | 25 passed (26), exactly the [COUPLING] case. Restore proven, blob equals HEAD.
• Reverse type check ('external-importt' pasted into plugin.ts): service-datasource typecheck TS2820 … not assignable to type '"package-duplicate" | "meta-envelope" | "meta-dispatch" | "external-import" | undefined'. That union is read from the rebuilt spec .d.ts. Restore proven, blob equals HEAD.

Tests (all at HEAD 5e5dedaa)

• @objectstack/metadata-protocol: Test Files 214 passed | 3 skipped (217), Tests 27751 passed | 19 skipped; typecheck exit 0.
• @objectstack/service-datasource: Test Files 37 passed (37), Tests 718 passed (718); typecheck exit 0.
• @objectstack/spec: Test Files 668 passed (668), Tests 19289 passed | 1 todo; typecheck exit 0; check:generated: All 15 generated artifacts are up to date after gen:docs.
• @objectstack/dogfood: typecheck exit 0.
• Each edited test file is in its package's typecheck program (tsc --listFiles count 1 for each of the three).
• Gates: dispatch-gates --commands derived 114 commands at this HEAD. All 114 ran, and all exit 0. Two of them first refused PREREQUISITE NOT MET: check:skill-examples needed client-react's dist/, and check:dual-build-cjs-loads needed eight packages' dist/. Both were built and re-run to exit 0. dispatch-gates --ran: 114 derived famil(ies) accounted for — 114 run, 0 NOT-MEASURED.
• Lint, narrowed: eslint over the 7 changed TypeScript files (--no-inline-config --format json) reported 7 files, 0 errors, 0 warnings. eslint's own config ignores the other two changed paths (.md, .mdx: "no matching configuration"). eslint.config.mjs enables no type-aware linting, so this diff cannot move a verdict on an untouched file. The whole-repo pnpm lint is CI's.

Acceptance notes

• The import route lives in packages/rest/src/external-datasource-routes.ts, not in external-datasource-service.ts as the claim's file surface says. It is unchanged: it already relays the message verbatim.
• @objectstack/rest lists @objectstack/metadata-protocol as a devDependency, so its dist/ bundles a full copy of the protocol, destructiveChangeRemedy included. The running protocol service is registered by metadata-protocol's own plugin, and rest never states this face, so the bundled copy's new case is unreachable from rest. Observation only. No carrier.
• The face-inventory docblock in protocol.destructive-409-face-inventory.test.ts still lists the compound-name PUT /meta/:type/:a/:b as row 2. That route was retired by commit 7986d973f. This is pre-existing drift in a test comment and is untouched here. No carrier.
• Not measured: the console's import dialog saves its draft through PUT /meta/object/:name and sends no force, so a console re-import that shrinks an object would get the meta-envelope 409, whose ?force=true the dialog does not offer. That is objectui-side, and it was not reproduced here.
• The branch is not merged with origin/main. It is 4 commits behind (2df3d13d..9f9510f2), and none of those commits touches any of this PR's 9 paths (git diff --stat over them is empty). dispatch-gates reported one stale gate input (scripts/engine-double-contract.pinned.json), which concerns fake engines, and this diff adds none.

Changeset: .changeset/21841-import-refusal-working-remedy.md. @objectstack/spec and @objectstack/metadata-protocol are minor (the widened enum and parameter). @objectstack/service-datasource is patch (its published exports and types do not move; its import now states a face).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/data-flow.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy))
• content/docs/api/wire-format.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy), /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin; a path literal in a comment on a changed line))
• content/docs/protocol/diagram.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy))
• content/docs/protocol/kernel/error-handling.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy))
• content/docs/protocol/kernel/http-protocol.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy), /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin; a path literal in a comment on a changed line))
• content/docs/protocol/objectql/state-machine.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy), /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin; a path literal in a comment on a changed line))
• content/docs/ui/forms.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy), /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin; a path literal in a comment on a changed line))

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

• content/docs/releases/v17/17-1.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy), /api/v1/meta/object/:name (route, a path literal in a comment in ExternalDatasourceServicePlugin; a path literal in a comment on a changed line))
• content/docs/releases/v17/17-5.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy))
• content/docs/releases/v17/17-6.mdx (via /api/v1/meta/object (route, a path literal in destructiveChangeRemedy))

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 — 139 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 aead296874176b1bcf2f2b8a916223b11cf30c4b → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5e5dedaa1356d89a40d25aa7618687b165e6f031
Local-runs: none

① Derived judgments

1. SaveMetaItemRequestSchema.writeFace (packages/spec/src/api/protocol.zod.ts) gains the member 'external-import': an additive widening of a published schema's accept-set, nothing accepted before is refused. Right. The spec pin loops all four members and still refuses 'rest'; no committed JSON artefact enumerates the faces (only the generated reference row, regenerated in this diff), and no hand-written page under content/docs/** or skills/** names writeFace or meta-dispatch, so no prose is made false.
2. saveMetaItem's inline request type on the exported ObjectStackProtocolImplementation (packages/metadata-protocol/src/protocol.ts, the local MetadataWriteFace union) gains the same member: an additive widening of that package's published .d.ts. Right. The two unions are held equal by typecheck, since plugin.ts types its door as a Pick of the spec's MetadataProtocol, so neither member can move alone.
3. destructiveChangeRemedy gains one case; the three existing arms and the default string are byte-unchanged in the diff, and the face-inventory switch case pins that the other faces did not move. Right, and inside the claim's constraint that the existing faces' text stays.
4. specValidationFindings (the 422 clause) is not edited; the new member falls to its full-prose default, which is the right polarity because the import route relays sendError(res, 400, 'EXTERNAL_IMPORT_ERROR', message) with no issues channel (packages/rest/src/external-datasource-routes.ts, read at the head). Pinned by the COUPLING case. Right; the validation path 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 owns is untouched.
5. The 409 envelope itself does not move: still DESTRUCTIVE_CHANGE at 409 with issues[] at the producer, relayed as 400 EXTERNAL_IMPORT_ERROR by the import route, stored definition unchanged. Pinned at unit level and at the door. Right; the card's refusal-stays constraint holds and nothing overwrites silently.
6. persistObject in packages/services/service-datasource/src/plugin.ts adds writeFace: 'external-import' to its save, server-stated. The REST import route hands req.body to importObject as opts, and importObject builds item from the draft definition plus name, label and external only, so neither a force nor a writeFace in a wire body reaches the request's top level; the no-smuggle unit case pins the exact key set. Right. The tenantAuthoredWriteRefusal branch keyed on writeFace !== 'package-duplicate' evaluates the same as before for this save, so no other accept-set moves.
7. No new accepted parameter on the import route; ImportObjectOpts and IExternalDatasourceService.importObject in spec are untouched. Right, and consistent with the earlier ruling recorded above destructiveChangeRemedy (a force threaded only where a twin door already read it; this route has no twin, and the door that does read ?force exists for the same item and is the one the clause names).
8. Generated artefacts: the one reference row in content/docs/references/api/protocol.mdx is regenerated; Lint & Repo Gates and Check Changeset are green on the head. Right.
9. The dogfood pin is a new file in packages/qa/dogfood/test/, selected by the isolated project's glob include and served from service-datasource source through the alias that already exists in the dogfood config; it follows both prescribed remedies to 201 and 200, and the old prescription (?force=true on the import) to the byte-identical 400. Dogfood Regression Gate is green on the head. Right.
10. Check-runs on the head, latest run per name: every check is success; Console Pin Gate and Packed-tarball smoke (opt-in) skipped by design; Auto Label and Check PR Size succeeded on their first run and skipped only on the label-event re-run; Build Docs ran and passed. No path in the file list is a governed surface. origin/main has moved 10 commits past the merge-base 2df3d13d, and the diff over the nine paths between the two is empty.

② Semver level

• Changeset .changeset/21841-import-refusal-working-remedy.md: @objectstack/spec minor, @objectstack/metadata-protocol minor, @objectstack/service-datasource patch; @objectstack/dogfood is private and owes none. This matches what the diff publishes: the two packages whose published surfaces widen (the schema enum and the exported method's parameter union) take at least minor; service-datasource's exported surface does not move (one argument added inside a closure), so its bug fix takes patch. No skip-changeset label, correctly.
• The line-start Clause-②: yes (widening) is carried by the PR body and by the changeset body, and the arm matches the diff: an additive member on a published schema, nothing narrowed. The level axis holds (the moved packages graded minor are exactly the widened ones). Not breaking, so no BREAKING banner, migration mapping or ADR-0087 marker is owed, and none is present.

③ Boundary flags

open_questions is empty. Each dev flag, answered:

• The import route lives in packages/rest/src/external-datasource-routes.ts, not in the service file the claim named: accepted; it relays the message verbatim and needed no edit.
• Changeset grades: judged right in ②.
• Three existing unit-test files edited outside packages/qa: inside the claim's tests surface; no packages/qa file was edited, the door pin is a new file as the claim required.
• Branch behind main: re-measured at this review as 10 commits, with an empty diff over the nine paths; the stale engine-double-contract.pinned.json gate input concerns fake engines, and this diff adds none.
• Lock queue-timeouts, trailer spelling, worktree removal: operational; the trailer pair is the one AGENTS.md prescribes, and neither the diff, the changeset nor the PR body carries a model identifier.
• Out-of-scope findings, noted and not filed: (a) the face-inventory docblock still lists as row 2 the compound-name PUT that commit 7986d97 retired, pre-existing drift shared with the docblock above destructiveChangeRemedy; a stale comment, not a reproducible defect, so the acceptance note is the right carrier; (b) @objectstack/rest bundling a devDependency copy of the protocol: observation only, the running protocol service is metadata-protocol's own plugin and rest never states this face; (c) the console's import dialog saving its draft through the meta PUT without offering force: objectui-side and not reproduced, and the envelope prescription on that door is true, so a note is right until it is reproduced. None escalated.
• No governed surface is touched; the review is owed on the published-schema face (packages/spec/src/**) and on the Clause-② declaration, both judged above.

Implemented-by: claude/issue-21841-import-refusal-working-remedy
Reviewed-by: session_011K3zqE8Pv1Evw5hc8tZCnN

VERDICT: PASS