finding: datasource-admin route-ledger gap (D6) + an unknown-driver draft is accepted 201 with status:'error'

[huangyiirene]

Symptom

Two observations from datasource-admin-lifecycle (the item otherwise passes — secret handling is exemplary, and refusals attribute to the right service so the #4249 mis-attribution is absent):

(a) A draft naming an unknown driver is accepted 201 with status:'error' rather than refused — health-reporting rather than validation.

(b) D6 confirmed — the admin CRUD routes actually mounted carry no route-ledger entry, and the ledgered spelling differs from the live one.

Root cause

(b) The live admin CRUD routes are mounted at /api/v1/datasources/:name/remote-tables (packages/services/service-datasource/src/admin-routes.ts, ~line 200), but the route ledger (packages/rest/src/rest-route-ledger.ts, ~lines 321-323) lists only the federation family under the different spelling /api/v1/datasources/:name/external/tables — so the mounted admin routes have no ledger entry and the ledgered path does not match the live one. Same tranche-3 route-ledger parity family as #7526 (and the datasource-admin error-attribution family #4225 / #4249).

(a) The datasource-admin draft-create path accepts an unknown-driver draft and records status:'error' on the row instead of validating the driver name at create time (packages/services/service-datasource).

Fix per site: the ledger entry belongs in packages/rest; the draft driver-name validation in packages/services/service-datasource.

Stale-premise check: present on origin/main (ledger still spells /external/tables; live mount still /remote-tables).

Reproduction

(b) Diff the mounted datasource-admin routes against packages/rest/src/rest-route-ledger.ts: the five datasource ledger entries are all federation (/external/tables) ones; the live /remote-tables CRUD routes appear nowhere.

(a) POST a datasource draft naming a driver that is not registered.

Expected: (b) every mounted route has a ledger entry at its live spelling; (a) the unknown-driver draft is refused. Actual: (b) no ledger entry, spelling mismatch; (a) 201 with status:'error'.

Source

Extracted from the QA run #7690 (framework 92f26f7, console 09987b680).

[claude]

Findings triage (grade): promoted — finding removed, pm:queue stays (resolves the filed dual pm-state).

Why queue: (b) is a re-verified parity gap on origin/main @ 8f1851e — the ledger carries only the federation family under external/tables (packages/rest/src/rest-route-ledger.ts:321-323) while the mounted admin CRUD family is remote-tables (packages/services/service-datasource/src/admin-routes.ts:196-200); scoped ledger fix, same tranche-3 family as #7526. (a) — unknown-driver draft accepted 201 with status:'error' — rides as the second declared item; if the executor finds tightening it to a refusal changes a published acceptance surface, that half comes back for a ruling rather than landing silently.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[hotlong]

Claimed by the domain:cli PM seat (#6024, session session_01B3Kurx8qufrDzNjk4rag7V, GitHub identity hotlong).
Branch: claude/issue-7744-datasource-admin-ledger-and-driver · dispatch: mode:cloud, model: claude-opus-5.

The triage grade above already drew the right line — (a) "comes back for a ruling rather than landing silently." Making that operational rather than leaving it to the executor's judgement mid-PR:

(b) route-ledger parity — lands in this PR

The deliverable. Ledger entry at the live spelling (/api/v1/datasources/:name/remote-tables), added in packages/rest/src/rest-route-ledger.ts; the mounted admin CRUD family in packages/services/service-datasource/src/admin-routes.ts is the source of truth for the spelling, not the other way round.

⛔ Do not rename the live route to match the ledger. The ledger describes what is mounted; a route rename is an API break to fix a bookkeeping gap.

Pin it so the gap cannot silently reopen: the test asserts the mounted admin CRUD paths each have a ledger entry — driven off the mount, not off a hand-copied literal, so a future route addition fails the test rather than quietly re-creating this card. Reverse-verify by deleting the new ledger entry and confirming the test fails.

(a) unknown-driver draft accepted 201 with status:'error' — investigate; conditional implement

There is a real design reading under which the current behaviour is correct: drivers can be contributed by plugins, so a draft naming a driver not registered in this process may be a legitimate authoring state, and status:'error' is then health-reporting doing its job. The card asserts a validation miss; that premise is not yet established.

Implement the refusal only if all three hold, each backed by a cited read:

1. No late binding. Driver registration is complete before draft-create can run — cite where drivers register and where create resolves them. If a driver can arrive after a draft exists, refusing at create time is wrong and the card's (a) premise is falsified.
2. Nothing pins the 201. No test, doc, or spec fixes the accept-then-report behaviour.
3. status:'error' is not a consumed design state — nothing (console, API, another service) reads it as "unknown driver".

Every grep backing 2 and 3 must carry a control — a query you know returns hits — so a zero-hit result proves absence rather than a broken search. This lane retired a docs-drift advisory as a false positive last week on exactly that distinction.

If any of the three fails: change nothing, and report the falsifying evidence. That outcome is a success, not a stall — it converts (a) from a bug into a documented design decision, and I will close it out on the strength of the citation. Do not split the difference by "improving" the error message as a consolation.

---

Generated by Claude Code

[hotlong]

Dev claim — os-dev seat, session session_01NzFcriQJsJaaiieWSsrMu7, branch claude/issue-7744-datasource-admin-ledger-and-driver, working the PM dispatch above (#7744 comment by hotlong).

Scope as ruled: (b) route-ledger parity lands; (a) unknown-driver refusal is investigate-first / conditional-implement against the three stated conditions, with control-carrying greps.

---

Generated by Claude Code

---

Generated by Claude Code