os datasource list-tables/introspect/validate are non-functional — CLI reads pre-#3843 flat envelope

[baozhoutao]

Found by QA run #10663 driving cli.datasource-introspect-codegen against a live showcase boot at framework 79ebb37.

Symptom

All three os datasource subcommands are broken on the happy path:

• os datasource list-tables showcase_external → No remote tables found. (exit 0), while the server returns two tables.
• os datasource introspect showcase_external --table customers → Error: Failed to generate draft (exit 2).
• os datasource validate showcase_external → No federated objects to validate. (exit 0) even against induced drift the server flags as missing_column region severity:error — a silent CI-breaking pass.
• Unknown datasource → TypeError: first argument must be a string or instance of Error (exit 1, a crash rather than the server's error text).

Root cause

The commands read the pre-#3843 flat response shape (body.tables / body.draft / body.results, and body.error as a string), but the server emits the current wrapped envelope from packages/types/src/response-envelope.ts: sendOk → {success:true, data:{…}}, sendError → {success:false, error:{code,message}}. So payloads (nested under data) read as undefined, and passing the error object to oclif's this.error(...) crashes. Mechanism at list-tables.ts:42-48, introspect.ts:53-63, validate.ts:43-53. This is these commands' first functional coverage — they never worked against the current envelope.

Reproduction

1. Boot showcase on a scratch port, mint an admin token.
2. os datasource list-tables showcase_external --url <U> --token <T> → No remote tables found. exit 0; oracle GET /api/v1/datasources/showcase_external/external/tables = {success:true,data:{tables:[{"name":"customers","columnCount":7},{"name":"orders","columnCount":7}]}}.
3. os datasource introspect showcase_external --table customers … → Error: Failed to generate draft exit 2; oracle POST …/tables/customers/draft returns data.draft.source.
4. Induce drift (rename customers.region in the fixture DB), os datasource validate … → No federated objects to validate. exit 0; oracle POST …/external/validate = ok:false … missing_column region.

Suggested fix

Unwrap the envelope in all three commands: read body.data.tables|draft|results and body.error?.message. Secondary quality gap: even once unwrapped, the generated draft fails os build as-is (object name lacks ${namespace}_ prefix; no sharingModel).

QA-source: #10663 · integration-system.external-schema-introspection · CLI lane (the introspection feature's CLI door)

[os-zhuang]

Triage: lands in packages/cli (datasource/list-tables.ts, introspect.ts, validate.ts) ⇒ pm:queue · domain:cli · type Bug. Rationale: three shipped subcommands are non-functional against the current server envelope, including a validate that green-lights induced drift (silent CI-breaking pass) and a crash on the error path — full reproduction in the card.

Dispatch notes:

• Fix = unwrap the Envelope drift is not just service-storage: four more route modules emit bare bodies, two of them the pre-#3675 { error: '<string>' } #3843 envelope (body.data.*, body.error?.message) in all three commands; add coverage that drives them against the wrapped envelope so this can't regress silently.
• The secondary draft-quality gap is explicitly OUT of scope (draft failing os build: namespace prefix + sharingModel) — extracted to [finding] External object-draft output fails os build as generated — object name lacks the ${namespace}_ prefix and no sharingModel is emitted #10712 (server-side, service-datasource). Do not fold it in.
• Cross-lane sibling: External object-draft drops the introspected primary key (isPrimary vs primaryKey seam) #10676 (services) changes what the server's draft contains; this card only changes how the CLI reads responses — file surfaces don't intersect, but if you pin introspect output content, don't assert the PK absence External object-draft drops the introspected primary key (isPrimary vs primaryKey seam) #10676 is about to fix.

Size/model suggestion: M, opus floor (three commands + error-path behavior + tests).

---

Generated by Claude Code

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10675-datasource-envelope-unwrap
Worktree: objectstack-issue-10675
Domain: domain:cli
File surface: the three packages/cli datasource subcommands triage names — datasource/list-tables.ts, introspect.ts, validate.ts — plus their tests. ⛔ Re-derive the real paths at head; do not trust a path copied from a comment.
Container & model: M, mode:subagent, model: opus (triage's stated floor for this card, and I am not going below it)
Clause-②: no — this changes how the CLI reads a response. The server accepts and refuses exactly what it did before, and nothing published widens. ⚠️ If your diff starts changing what the server sends, you have left the card.
Serial constraints cleared: measured — all 13 open PRs listed and checked; none touches packages/cli's datasource commands. Cross-lane sibling #10676 is in service-datasource (a different package, different lane) — see the fence below.

Triage has already ruled the scope — quoting it as binding

From comment 5368004440, verbatim:

Fix = unwrap the #3843 envelope (body.data.*, body.error?.message) in all three commands; add coverage that drives them against the wrapped envelope so this can't regress silently.

The secondary draft-quality gap is explicitly OUT of scope (draft failing os build: namespace prefix + sharingModel) — extracted to #10712 (server-side, service-datasource). Do not fold it in.

⛔ #10712 is not yours. If you find yourself editing anything that changes what the draft contains, stop — that is the other card.

The two failure modes are not equally interesting — rank them

Triage's rationale names three broken subcommands, but they do not fail the same way:

1. validate green-lights induced drift — a silent pass on a CI-breaking condition. ⭐ This is the severe one: a gate that answers "fine" about something it never actually read is worse than one that crashes, because nothing downstream ever learns. Reproduce this one first and make it the centre of your coverage.
2. A crash on the error path — loud, therefore self-reporting.
3. list-tables / introspect reading the wrong shape.

Your reverse verification should be against (1): induce the drift, show validate passing today, apply the unwrap, show it correctly failing. A test that only proves the happy path now parses is not evidence for the defect this card is actually about.

Fences

• ⛔ Do not assert the PK absence that External object-draft drops the introspected primary key (isPrimary vs primaryKey seam) #10676 is about to fix. Triage: "if you pin introspect output content, don't assert the PK absence External object-draft drops the introspected primary key (isPrimary vs primaryKey seam) #10676 is about to fix." Pinning a bug as if it were the contract is how a cross-lane fix gets blocked by a test that was wrong on the day it was written.
• ⛔ Never weaken a gate: no threshold moved, no baseline raised, no test skipped, quarantined or retry-wrapped. If the unwrap makes an existing test go red, that is a fork to report — ⛔ not an assertion to rewrite.
• ⛔ Nothing under content/docs/releases/**. Your changeset is the release-notes input.

premise_still_valid: false is a legitimate delivery if the envelope is already unwrapped at head.

⚠️ Race arbitration: re-read this card's comments in full before your first edit. An earlier Claim: from a different session ID wins on timestamp regardless of the assignee field.

---

Generated by Claude Code