finding: the datasource-admin lifecycle family has no SDK expression — decide `server-only` vs `gap`

[hotlong]

Symptom

Surfaced while ledgering the datasource-admin route family for #7744.

ObjectStackClient reaches none of the ten routes registerDatasourceAdminRoutes mounts under /api/v1/datasources. Its datasources namespace contains exactly one sub-namespace, external, whose five methods all target the federation family in @objectstack/rest (/:name/external/…, ledgered in packages/rest/src/rest-route-ledger.ts). The CLI is the same story: its three datasource commands (introspect, list-tables, validate) all call /external/*.

So the whole runtime datasource lifecycle — list, read, create, patch, remove, connection probe, driver catalog — is reachable only by the Setup/Studio console and by one declared metadata-type action (test_connection).

The decision this needs

The new packages/services/service-datasource/src/datasource-route-ledger.ts records all ten rows as server-only, on the grounds that:

• the family is mounted by objectstack serve (a CLI-composed plugin registering on http.server), not by @objectstack/rest, so it is not part of the platform's advertised SDK composition; and
• its actual consumers are the console and a metadata-type action.

That classification is defensible but it is the conservative reading, chosen deliberately: writing ten gap rows instead would have been a product decision — "the SDK should be able to manage datasources" — made inside a bookkeeping fix. The ledger vocabulary forces one of the two, and this issue is where the choice should actually be reviewed.

If the answer is "yes, the SDK should express datasource lifecycle", the rows become gap (and the ledger's gap ratchet, currently pinned at 0, moves with them) until the client methods land. If the answer is "no", the current server-only rows are already correct and this can close as documented-by-the-ledger.

Source

Extracted from #7744 (route-ledger parity for the datasource-admin family).

[hotlong]

Triage disposition: server-only stands — closing as documented-by-the-ledger (not planned), type Task, routed domain:cli for the record (the counterfactual work would have landed in packages/client). This is the findings-round close power with the auto-adjudication analysis attached; veto window: listed in this round's 代裁清单 — reopening is one click and no argument.

Four-lens block:

1. Platform long-term coherence — the server-only rows are the honest reading: the family is mounted by objectstack serve's CLI-composed plugin, not by @objectstack/rest, so it is genuinely outside the platform's advertised SDK composition. Writing gap would blur that composition boundary from inside a bookkeeping ledger.
2. Measured business pull — zero. The measured consumers are the Setup/Studio console and one declared metadata-type action (test_connection); the CLI's three datasource commands all target the federation family. Nobody has asked the SDK to manage datasource lifecycle.
3. AI-agent error-resistance — ten gap rows are ten standing declarations of surface nobody builds; declared-but-unimplemented SDK affordances are exactly the pattern this repo fights. A closed ledger stating server-only is the shape an AI consumer can trust.
4. Startup scope discipline — gap moves the gap ratchet off 0 and creates a permanent build obligation with no pull behind it. Remove/decline beats declare-and-maintain.

Mechanical boundary check: choosing gap (SDK should express datasource lifecycle) would expand the public surface ⇒ that direction is a Feature-class product decision and stays maintainer-only. Declining it changes nothing — the ledger rows already say server-only — which is what makes this adjudicable at triage.

Reopen trigger: the first concrete demand — a user or shipped app needing programmatic datasource lifecycle outside the console — reopens this card straight into the decision box with that evidence attached.

本评论来自分诊座位（scheduled session session_0199Rq2oEnNNRmdhmWwqUwvQ），auto-adjudicated per the 2026-08-12 maintainer ruling on the triage adjudication lane。

---

Generated by Claude Code