finding: the two `listRemoteTables` route twins diverge on `?schema=` — the admin spelling drops it

[hotlong]

Symptom

IExternalDatasourceService.listRemoteTables is reachable through two live routes:

route	package	call
GET /api/v1/datasources/:name/external/tables	packages/rest/src/external-datasource-routes.ts	listRemoteTables(name, { schema })
GET /api/v1/datasources/:name/remote-tables	packages/services/service-datasource/src/admin-routes.ts	listRemoteTables(name)

The federation spelling forwards ?schema=; the admin spelling does not read the query at all, so a caller that passes ?schema=public to it silently gets the unfiltered result rather than an error or the filtered set.

The same twin relationship holds for generateObjectDraft (POST /:name/object-draft vs POST /:name/external/tables/:remote/draft), which does forward its options bag — so this divergence is specific to the schema filter on the listing route.

Why this is a finding and not part of #7744

The twins are known and deliberate: #4249 reconciled their failure contract ("One operation, one failure contract now, on both paths", external-datasource-routes.ts) rather than removing either. #7744 ledgered the admin spelling at its live path and was explicitly scoped away from renaming or removing a live route. What #4249 reconciled was the error path; the request path was never compared, and this is the residue.

Options

1. Forward req.query.schema on the admin route so the twins accept the same request shape (smallest change; makes the paths interchangeable, which is what "one operation" implies).
2. Leave it, and record the divergence as intended — in which case the admin route arguably ought to refuse an unsupported query parameter rather than ignore it, since silently dropping a filter is the "declared ≠ enforced" shape (Prime Directive chore: version packages #10).

Not fixed in #7744 because either option changes request-handling behaviour on a live route, which that card ruled out of scope.

Reproduction

GET /api/v1/datasources/<name>/remote-tables?schema=public and GET /api/v1/datasources/<name>/external/tables?schema=public against the same datasource: the second is filtered, the first is not.

[hotlong]

Triage: pm:queue, routed domain:services (the divergent side is packages/services/service-datasource/src/admin-routes.ts), type Bug.

• Grade rationale (ruling inheritance): The same three datasource-admin routes answer 400 with the wrong service's error code (#4225 follow-up, one field over) #4249 reconciled these twins on the principle "one operation, one failure contract"; the request path is the unfinished half of the same principle. Route A — forward req.query.schema on the admin spelling — is the dispatch default: smallest change, makes the twins interchangeable, and the sibling (generateObjectDraft) already forwards its options bag, so this restores symmetry rather than inventing policy.
• Relation to [rest] Unknown query parameters are silently dropped on every REST route except /approvals/requests — decide whether the closed-parameter-set rule becomes ingress policy #7606 (not blocking): the refuse-unknown-query-param question is the ingress-policy card's to answer globally. If [rest] Unknown query parameters are silently dropped on every REST route except /approvals/requests — decide whether the closed-parameter-set rule becomes ingress policy #7606 later rules refusal, the twins move together then; today's fix is honoring the parameter, which stands under either outcome.
• Acceptance: the card's own repro pair — ?schema= on both spellings against the same datasource returns the same filtered set.

本评论来自分诊座位（scheduled session session_0199Rq2oEnNNRmdhmWwqUwvQ），不构成认领。

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 7
Session: session_01JVfWSQN9RDDGwdVSmMc29x
Branch: claude/issue-7955-admin-remote-tables-schema
Worktree: cloud session's own clone (mode:cloud)
Domain: domain:services
File surface: packages/services/service-datasource/src/admin-routes.ts (the GET /:name/remote-tables handler) + its tests. packages/rest/src/external-datasource-routes.ts is a read surface — the reference spelling to converge on, ⛔ not to edit.
Container & model: M (small diff, but the acceptance is a cross-package equivalence and the sibling route's shape is the specification), mode:cloud, model: opus

Route adopted from triage (comment 5265176592), endorsed as-is: Route A — forward req.query.schema on the admin spelling. Rationale I'm carrying into the dispatch verbatim: #4249 reconciled these twins on "one operation, one failure contract", and the request path is the unfinished half of that same principle; the sibling operation (generateObjectDraft) already forwards its options bag, so this restores symmetry rather than inventing policy.

⛔ Route B is NOT this card. Refusing an unsupported query parameter is the ingress-policy question and belongs to #7606, which owns it globally. Today's fix — honoring the parameter — stands under either outcome of that card, which is exactly why it can land now without pre-empting it. If #7606 later rules refusal, the twins move together then.

Serial constraints cleared: service-datasource had no card in rounds 1–6; no in-flight PR touches it. ⚠️ Adjacent-but-disjoint: #7990 (the sys_metadata cleartext-sink class card, filed by this seat from the #7902 survey) names datasource-admin-plugin.ts / datasource-admin-service.ts in the same package — it is unassigned and ungraded, so nothing is in flight against it, and this card touches neither file. Flagged so the next selection round does not read the overlap as new.

---

Generated by Claude Code

[huangyiirene]

PR: #7998 (draft) · Branch: claude/issue-7955-admin-remote-tables-schema · Route A implemented as ruled.

§4 premise: the twins ARE the same operation — no STOP

Measured, not assumed:

• Same service slot: admin-routes.ts:201 resolves ctx.getService('external-datasource'); external-datasource-routes.ts:81 resolves the same name. The admin module's own ServiceName union and SERVICE_ERROR_CODE table already attribute this route to external-datasource (Three datasource-admin routes answer 503 naming the wrong service (carried out of #3973 so it is not buried) #4225/The same three datasource-admin routes answer 400 with the wrong service's error code (#4225 follow-up, one field over) #4249), so the codebase does not treat it as a differently-scoped admin listing.
• Same method, same argument: both call listRemoteTables(req.params.name, …). Nothing narrows or widens the datasource, and there is no second service method behind either path.
• The filter is meaningful on both: the service's opts?.schema filter runs after external.allowedSchemas, so ?schema= narrows within whatever the datasource already permits — no policy is bypassed by honouring it on the admin path.
• datasource-route-ledger.ts already stated the overlap in prose and cited this issue.

So the premise holds and the ruling applies unchanged. I found nothing suggesting the federation spelling is the wrong one.

Reverse-verification (red before / green after)

The equivalence test drives both spellings against one ExternalDatasourceService on one real HonoHttpServer.

• Before (admin-routes.ts reverted to origin/main, package rebuilt): 2 failed | 3 passed. ?schema=public → federation [public.customers, public.orders], admin all three including analytics.events; ?schema=nonexistent → federation [], admin all three.
• After: 5 passed.

The 3 that pass in both directions are the unfiltered arms — which is exactly why the absent-parameter case earns its place: a fix that always filtered would satisfy criterion 1 and break every existing caller.

Full suites: @objectstack/rest 1536 ✓ (95 files), @objectstack/service-datasource 334 ✓ (13 files).

§5.3 — what I mirrored for validation

packages/rest/src/external-datasource-routes.ts:122, verbatim:

const schema = typeof req.query?.schema === 'string' ? req.query.schema : undefined;

The federation spelling coerces, it does not validate: there is no refusal on this path today, so I added none — stricter would invent policy, looser would drop the parameter again. Two consequences are now pinned as shared rather than incidental: a repeated ?schema=a&schema=b arrives as an array and both spellings fall back to no filter; an empty ?schema= stays a string and the service's own opts?.schema && guard treats it as no filter. Both come from the one service / one coercion, so they cannot diverge without the test going red.

Acceptance criteria

1. ✅ packages/rest/src/remote-tables-twin.equivalence.test.ts drives both routes and compares the sets (5 cases: filtered, absent, no-match, repeated key, empty).
2. ✅ Absent-parameter case included, and it is the case that fails an always-filtering fix.
3. ✅ Validation mirrored — see above.
4. n/a — no engine fake (the fixture is ExternalDatasourceService over a fake introspect/getDatasource; no engine double, so check:engine-double-contract is not implicated).
5. n/a — no refusal added or changed, so no ADR-0112 assertion is due. Existing refusal coverage (EXTERNAL_DATASOURCE_ERROR on this route) is untouched and still green.
6. n/a — checked rather than assumed: no packages/spec/src/** file is touched (git diff --stat covers only service-datasource sources/tests, the new rest test, packages/rest/package.json, pnpm-lock.yaml, one changeset), so no gen:schema / gen:docs is due.
7. ✅ Reported above.

Test placement (worth a reviewer's eye)

The equivalence test sits in packages/rest, not next to the changed route. registerDatasourceAdminRoutes is public API of @objectstack/service-datasource; registerExternalDatasourceRoutes is deliberately not exported from @objectstack/rest's index (it is composed internally by rest-api-plugin.ts). Putting the test on the services side would have required widening the reference package's public surface; putting it here required only two dev-only workspace deps (service-datasource, plugin-hono-server) on an edge that is not a cycle. Same reasoning shape the client-side ledger guard used. service-datasource's own suite still gains the local forwarding case, so a regression there fails in-package too.

CI state

Local: both package suites, typecheck and eslint clean; check:route-envelope, check:cross-package-test-inputs, check:published-files, check:empty-changeset, check:adr-0087-registration pass. GitHub CI on #7998 not yet reported at the time of writing.

Deliberately not done

• No refusal / warning / deprecation for an unusable ?schema= — that is [rest] Unknown query parameters are silently dropped on every REST route except /approvals/requests — decide whether the closed-parameter-set rule becomes ingress policy #7606's global ingress question, and honouring the parameter stands under either outcome.
• packages/rest/src/external-datasource-routes.ts untouched — the reference spelling.
• Changeset declares @objectstack/service-datasource patch only. @objectstack/rest changed only its devDependencies, so its published artifact is byte-identical and a release entry would be a phantom bump.
• Updated the two datasource-route-ledger.ts notes that recorded the divergence as live ("only the federation twin forwards ?schema=") — leaving them would have made the ledger wrong the moment this lands.

---

Generated by Claude Code