flipstream 0.5.0 → 0.6.0

package/dist/lib/output/table.js

@@ -1,4 +1,5 @@
 import { makeTable } from '@oclif/table';
+import { sanitizeDeep } from './sanitize.js';
 // Render a table to STDOUT — HUMAN output ONLY. Callers invoke this from a
 // respond/respondList human formatter, which never runs under --json/--ndjson, so
 // the agent contract (machine output is pure JSON/NDJSON) is preserved. Honors
@@ -8,10 +9,13 @@ export function renderTable(data, columns, emptyMessage = '(none)') {
         process.stdout.write(`${emptyMessage}\n`);
         return;
     }
+    // Sanitize the DATA, not the rendered table: makeTable adds its own ANSI for
+    // borders and colour, so cleaning the finished string would strip that too.
+    // Every value here came from a service, so none of it may carry control bytes.
     const table = makeTable({
         borderStyle: 'vertical-with-outline',
         columns,
-        data,
+        data: sanitizeDeep(data),
         noStyle: Boolean(process.env.NO_COLOR),
         overflow: 'truncate-end',
     });

package/dist/lib/output/trace.d.ts

@@ -0,0 +1,11 @@
+export declare function enableStderrTrace(): void;
+export declare function resetTrace(): void;
+export declare function traceRequest(method: string, url: string, body?: unknown): void;
+export declare function traceFailure(method: string, url: string, reason: string, ms: number): void;
+export declare function traceResponse(response: {
+    bodyText?: string;
+    method: string;
+    ms: number;
+    status: number;
+    url: string;
+}): void;

package/dist/lib/output/trace.js

@@ -0,0 +1,89 @@
+import { redact } from './redact.js';
+import { appendRunLog, currentRunLogPath } from './runlog.js';
+import { sanitizeTerminal } from './sanitize.js';
+// Wire tracing (E11-6, #105): one line per request and response for every
+// first-party API call. Two sinks with different rules:
+//
+//   run log  — always receives every line (context + order for post-mortems)
+//   stderr   — only when enabled (FLIPSTREAM_LOG=debug or --verbose), which is
+//              also what fixes #92: trace lines are emitted AS THEY HAPPEN, so
+//              the failure path has diagnostics too, not just the happy path.
+//
+// Bodies and headers are OMITTED by default. FLIPSTREAM_LOG_SANITIZE=false
+// includes bodies — still through redact(), which is the floor that never
+// comes off (tokens never reach any sink).
+let stderrEnabled = false;
+// Called once per command from BaseCommand.init (flag) — the env var works
+// even before that, for code paths that run pre-parse.
+export function enableStderrTrace() {
+    stderrEnabled = true;
+}
+// Test seam.
+export function resetTrace() {
+    stderrEnabled = false;
+    bodyNoticeShown = false;
+}
+function debugEnv() {
+    return process.env.FLIPSTREAM_LOG === 'debug';
+}
+function includeBodies() {
+    return process.env.FLIPSTREAM_LOG_SANITIZE === 'false';
+}
+let bodyNoticeShown = false;
+function emit(line) {
+    // The run log is a file — it keeps the byte-faithful line for post-mortem.
+    // stderr is a terminal, so a body line under FLIPSTREAM_LOG_SANITIZE=false
+    // could carry cursor/erase escapes that rewrite the display; sanitize it
+    // there (every other human-facing writer already does).
+    appendRunLog(line);
+    if (stderrEnabled || debugEnv())
+        process.stderr.write(`${sanitizeTerminal(line)}\n`);
+}
+// FLIPSTREAM_LOG_SANITIZE=false writes full bodies to the run log even with no
+// on-screen tracing — so the operator learns, once, that turning off
+// sanitization also turned on persistence (E11-6 review).
+function noticeBodiesPersist() {
+    if (bodyNoticeShown || stderrEnabled || debugEnv())
+        return;
+    bodyNoticeShown = true;
+    const path = currentRunLogPath();
+    process.stderr.write(`FLIPSTREAM_LOG_SANITIZE=false: unsanitized request/response bodies are being written to ${path ?? 'the run log'}\n`);
+}
+export function traceRequest(method, url, body) {
+    emit(`-- REQUEST ${method} ${redact(url)}`);
+    if (body === undefined)
+        return;
+    if (includeBodies()) {
+        noticeBodiesPersist();
+        emit(`   body: ${JSON.stringify(redact(body))}`);
+    }
+    else {
+        emit('   body: omitted; set FLIPSTREAM_LOG_SANITIZE=false to include redacted data');
+    }
+}
+export function traceFailure(method, url, reason, ms) {
+    emit(`-- FAILED ${method} ${redact(url)} (${ms} ms): ${redact(reason)}`);
+}
+// A body STRING gets structural redaction: parsed as JSON when possible so
+// secret-NAMED keys are masked (string-level redaction only catches
+// param-style and JWT-shaped values, not `{"access_token": "..."}`).
+function redactBodyText(bodyText) {
+    try {
+        return JSON.stringify(redact(JSON.parse(bodyText)));
+    }
+    catch {
+        return redact(bodyText);
+    }
+}
+export function traceResponse(response) {
+    emit(`-- RESPONSE ${response.status} ${response.method} ${redact(response.url)} (${response.ms} ms)`);
+    if (response.bodyText === undefined || response.bodyText.length === 0)
+        return;
+    if (includeBodies()) {
+        noticeBodiesPersist();
+        emit(`   body: ${redactBodyText(response.bodyText)}`);
+    }
+    else {
+        emit('   body: omitted; set FLIPSTREAM_LOG_SANITIZE=false to include redacted data');
+    }
+}

package/dist/lib/planner/catalog.d.ts

@@ -0,0 +1,26 @@
+export interface CatalogItem {
+    description: string;
+    label: string;
+    name: string;
+    type: string;
+}
+export interface CatalogSource {
+    customDimensionsMax?: number;
+    description: string;
+    dimensions: CatalogItem[];
+    label: string;
+    metrics: CatalogItem[];
+    name: string;
+}
+export interface CatalogSourceSummary {
+    dimensions: number;
+    label: string;
+    metrics: number;
+    name: string;
+}
+export interface CatalogIndex {
+    defaultSource?: string;
+    sources: CatalogSourceSummary[];
+}
+export declare function parseCatalogIndex(payload: unknown): CatalogIndex;
+export declare function parseCatalogSource(payload: unknown): CatalogSource;

package/dist/lib/planner/catalog.js

@@ -0,0 +1,60 @@
+// Narrowing for the catalog documents the planner serves. The wire payload is
+// untrusted, so it arrives as `unknown` and every field is proven here rather
+// than asserted — the repo rule for API boundaries (see api/http.ts).
+//
+// What the planner publishes is an ALLOWLIST projection built by data-model:
+// name, label, description, format and nothing else. `field`, `agg_func`,
+// `table`, `grain`, `tier` and `routing` are absent by construction, not by
+// filtering. We deliberately do not re-filter here — inventing a second
+// allowlist would hide the day the first one breaks.
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+function arr(value) {
+    return Array.isArray(value) ? value : [];
+}
+function parseItem(value) {
+    const record = asRecord(value) ?? {};
+    // `format` may be absent or null; its `type` is what the human table shows.
+    const format = asRecord(record.format) ?? {};
+    return {
+        description: str(record.description),
+        label: str(record.label),
+        name: str(record.name),
+        type: str(format.type),
+    };
+}
+// GET /catalog — the index of sources.
+export function parseCatalogIndex(payload) {
+    const record = asRecord(payload) ?? {};
+    const sources = arr(record.sources).map((entry) => {
+        const source = asRecord(entry) ?? {};
+        return {
+            dimensions: arr(source.dimensions).length,
+            label: str(source.label),
+            metrics: arr(source.metrics).length,
+            name: str(source.name),
+        };
+    });
+    const defaultSource = typeof record.defaultSource === 'string' ? record.defaultSource : undefined;
+    return { defaultSource, sources };
+}
+// GET /catalog/<source> — one source's full vocabulary.
+export function parseCatalogSource(payload) {
+    const record = asRecord(payload) ?? {};
+    const custom = asRecord(record.customDimensions);
+    const max = custom !== undefined && typeof custom.max === 'number' ? custom.max : undefined;
+    return {
+        customDimensionsMax: max,
+        description: str(record.description),
+        dimensions: arr(record.dimensions).map((item) => parseItem(item)),
+        label: str(record.label),
+        metrics: arr(record.metrics).map((item) => parseItem(item)),
+        name: str(record.name),
+    };
+}

package/dist/lib/planner/client.d.ts

@@ -0,0 +1,14 @@
+import { type RefreshDeps } from '../api/retry.js';
+export interface PlannerCallOptions {
+    timeoutMs?: number;
+}
+export interface PlannerClient {
+    getCatalog(source?: string, options?: PlannerCallOptions): Promise<unknown>;
+    postQuery(body: unknown, options?: PlannerCallOptions): Promise<unknown>;
+}
+export interface AuthedPlannerClientDeps extends RefreshDeps {
+    timeoutMs?: number;
+    url?: string;
+}
+export declare function createAuthedPlannerClient(deps: AuthedPlannerClientDeps): PlannerClient;
+export declare function getPlannerHealth(url: string, options?: PlannerCallOptions): Promise<unknown>;

package/dist/lib/planner/client.js

@@ -0,0 +1,47 @@
+import { requestJson } from '../api/http.js';
+import { withFreshToken } from '../api/retry.js';
+import { PLANNER_HOST } from '../config/constants.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+// The authed QUERY-PLANNER client. Transport only: it knows the two paths and
+// nothing about what a catalog document or a LogicalRequest contains.
+//
+// Wrapped in the SAME withFreshToken 401->refresh->retry-once used by the data and
+// admin clients, and refresh always targets the AUTH issuer (deps.authHost) rather
+// than the planner — the planner issues nothing, it only verifies and forwards.
+export function createAuthedPlannerClient(deps) {
+    const base = rstrip(deps.url ?? PLANNER_HOST);
+    const defaultTimeout = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        getCatalog(source, options = {}) {
+            // encodeURIComponent so a source name can never escape the path segment.
+            const path = source === undefined ? '/catalog' : `/catalog/${encodeURIComponent(source)}`;
+            return withFreshToken(deps, (token) => requestJson({
+                method: 'GET',
+                timeoutMs: options.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            }));
+        },
+        postQuery(body, options = {}) {
+            return withFreshToken(deps, (token) => requestJson({
+                body,
+                method: 'POST',
+                timeoutMs: options.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}/query`,
+            }));
+        },
+    };
+}
+// GET /health — the one endpoint that takes NO token (it is open on the planner),
+// so it answers "is it me or is it them" before any auth debugging starts.
+export async function getPlannerHealth(url, options = {}) {
+    return requestJson({
+        method: 'GET',
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        url: `${rstrip(url)}/health`,
+    });
+}

package/dist/lib/planner/connection.d.ts

@@ -0,0 +1,14 @@
+import { type AdminClient } from '../api/admin-client.js';
+export interface ResolveOptions {
+    note?: (message: string) => void;
+}
+export interface ResolvedConnection {
+    active: boolean;
+    clientId: string;
+    id: string;
+    name: string;
+}
+export declare function connectionsUrl(clientId: string): string;
+export declare function assertConnectionActive(connection: ResolvedConnection): void;
+export declare function resolveConnection(client: AdminClient, value: string, options?: ResolveOptions): Promise<ResolvedConnection>;
+export declare function connectionIsVisible(client: AdminClient, connectionId: string): Promise<boolean | undefined>;

package/dist/lib/planner/connection.js

@@ -0,0 +1,139 @@
+import { fetchConnections } from '../api/connections.js';
+import { isUuid } from '../api/ids.js';
+import { projectConnection } from '../api/projections.js';
+import { uuidToShort } from '../api/short-uuid.js';
+import { PULSE_FE_HOST } from '../config/constants.js';
+import { CliError, UsageError } from '../errors.js';
+import { ExitCode } from '../exit-codes.js';
+const MAX_LISTED = 10;
+// Read a string field, falling back into the projected `raw` passthrough.
+// projectConnection() promotes only its core fields (name, type, active, …), so
+// `slug` — which the admin API does carry — survives ONLY inside `raw`. Reading
+// just the top level would make slug matching silently never fire.
+// Candidate connections as "  <id>  <name>" lines, capped, so a refusal names what
+// the search found and the retry is a copy-paste rather than a second guess.
+function listed(candidates) {
+    return candidates
+        .slice(0, MAX_LISTED)
+        .map((record) => `  ${label(record, 'id')}  ${label(record, 'name')}`)
+        .join('\n');
+}
+function label(record, key) {
+    const direct = record[key];
+    if (typeof direct === 'string')
+        return direct;
+    const raw = record.raw;
+    const nested = raw?.[key];
+    return typeof nested === 'string' ? nested : '';
+}
+// A projected admin record → the few fields the query path cares about.
+// `active` defaults to TRUE when the field is missing: this check is a
+// convenience over the server's, and inventing "inactive" from an absent field
+// would block a working connection on a schema change. The server (pulse-data#49)
+// is what actually enforces this.
+function toResolved(record) {
+    const active = record.active ?? record.raw?.active;
+    return {
+        active: active !== false,
+        clientId: label(record, 'client_id'),
+        id: label(record, 'id'),
+        name: label(record, 'name'),
+    };
+}
+// Where a human goes to switch a connection back on. The workspace segment is the
+// client_id in pulse-fe's short-UUID encoding — derived from the record we already
+// hold, so building this costs no extra request.
+export function connectionsUrl(clientId) {
+    if (!isUuid(clientId))
+        return `${PULSE_FE_HOST}/client-space`;
+    return `${PULSE_FE_HOST}/client-space/${uuidToShort(clientId)}/connections`;
+}
+// Refuse a query against an inactive connection.
+//
+// This is a CONVENIENCE, not the control. It saves a round trip and turns an
+// opaque engine failure into an instruction, but the authoritative refusal lives
+// in pulse-data (#49) — a check on this side of the wire can be edited out by
+// anyone running a modified client, so it must never be the only thing standing
+// between an inactive connector and its data.
+export function assertConnectionActive(connection) {
+    if (connection.active)
+        return;
+    const where = connection.name.length > 0 ? `'${connection.name}'` : connection.id;
+    throw new CliError(`Connection ${where} is inactive, so it cannot be queried. Reactivate it at ` +
+        `${connectionsUrl(connection.clientId)}`, 'connection_inactive', ExitCode.USAGE);
+}
+// A UUID passes through; anything else is looked up by name or slug.
+//
+// Ambiguity is REFUSED rather than resolved to the first hit. Querying the wrong
+// connection returns numbers rather than an error, and numbers are the one
+// failure nobody notices — so a name that matches two connections is a usage
+// error listing both, not a coin flip.
+//
+// The lookup reads the same pulse-admin list that pulse-data resolves against,
+// with the same token and the same connections:read scope, so what resolves here
+// is exactly what the query can reach and nothing more.
+export async function resolveConnection(client, value, options = {}) {
+    // A UUID still costs one GET. It used to pass straight through, but the caller
+    // needs `active`, and skipping the lookup for the id form would make "use the
+    // UUID instead of the name" a one-word bypass of the inactive check.
+    if (isUuid(value)) {
+        const raw = await client.get(`/connections/${value}`);
+        return toResolved(projectConnection(raw));
+    }
+    const { records } = await fetchConnections(client, { all: true, limit: 50, offset: 0, q: value });
+    // Only an EXACT name/slug hit is an identity. The server's free-text results are
+    // SUGGESTIONS: 'acme' matching the single connection 'acme-staging' is not the
+    // user naming it, and resolving to it would query a connection they never asked
+    // for — which returns numbers rather than an error, and numbers are the one
+    // failure nobody notices. Refusing costs one retry; guessing costs a decision
+    // made on the wrong client's data.
+    const folded = value.toLowerCase();
+    const exact = records.filter((record) => label(record, 'name').toLowerCase() === folded || label(record, 'slug').toLowerCase() === folded);
+    if (exact.length === 0) {
+        if (records.length === 0) {
+            throw new UsageError(`No connection matches '${value}' — run \`flipstream connections list\` to see yours.`);
+        }
+        // Name what the search DID find, so the retry is a copy-paste rather than a
+        // second guess.
+        throw new UsageError(`No connection is named exactly '${value}'. Did you mean:\n${listed(records)}`);
+    }
+    if (exact.length > 1) {
+        throw new UsageError(`'${value}' matches ${exact.length} connections:\n${listed(exact)}`);
+    }
+    const found = exact[0] ?? {};
+    const resolved = toResolved(found);
+    if (resolved.id.length === 0)
+        throw new UsageError(`Connection '${value}' resolved to a record with no id.`);
+    options.note?.(`connection '${value}' → ${resolved.id} (${resolved.name})`);
+    return resolved;
+}
+// Can this token resolve that connection? `undefined` when we could not find out.
+//
+// Only ever used to EXPLAIN a failure that already happened. pulse-data resolves
+// the connection through pulse-admin as the caller, so a connection belonging to
+// another account fails there — and the planner is right not to say which, since
+// the engine's own words name tables. This asks the same question from the
+// outside, where the answer is the caller's to know.
+export async function connectionIsVisible(client, connectionId) {
+    // This id can come from an opaque --body, so it is caller-controlled and goes
+    // straight into a path. `../../oauth/token` normalises out of /connections/
+    // entirely, which would point an authenticated GET at another admin route. Same
+    // origin and the caller's own token, so the blast radius is small — but this
+    // CLI is driven by agents that may be working from untrusted content, and a
+    // non-UUID is not a connection id in any case. Undefined is also the honest
+    // answer: we cannot determine visibility for something that cannot be one.
+    if (!isUuid(connectionId))
+        return undefined;
+    try {
+        await client.get(`/connections/${connectionId}`);
+        return true;
+    }
+    catch (error) {
+        const { status } = error;
+        if (status === 404)
+            return false;
+        // 403, 5xx, a timeout: we genuinely do not know, and guessing here would put
+        // a confident wrong hint in front of a real failure.
+        return undefined;
+    }
+}

package/dist/lib/planner/diagnose.d.ts

@@ -0,0 +1,8 @@
+import { type CliError } from '../errors.js';
+export interface DiagnoseOptions {
+    bin: string;
+    body: unknown;
+    fetchCatalog: (source?: string) => Promise<unknown>;
+    onSkip?: (reason: string) => void;
+}
+export declare function attachVocabularyDiagnosis(error: CliError, options: DiagnoseOptions): Promise<void>;

package/dist/lib/planner/diagnose.js

@@ -0,0 +1,50 @@
+import { parseCatalogIndex, parseCatalogSource } from './catalog.js';
+import { didYouMean } from './suggest.js';
+import { describeProblems, diagnoseUnknownNames } from './vocabulary.js';
+export async function attachVocabularyDiagnosis(error, options) {
+    const upstream = error.details.upstreamCode;
+    if (upstream === undefined || !upstream.startsWith('UNKNOWN_'))
+        return;
+    // Structural guard, not just the planner's vocabulary discipline: a
+    // retryable failure (429/5xx) must never trigger an immediate follow-up
+    // fetch against a service that just asked us to back off.
+    if (error.details.retryable === true)
+        return;
+    const source = options.body?.source;
+    const sourceName = typeof source === 'string' && /^[\w.-]{1,64}$/.test(source) ? source : undefined;
+    try {
+        if (upstream === 'UNKNOWN_SOURCE') {
+            if (sourceName === undefined)
+                return;
+            const index = parseCatalogIndex(await options.fetchCatalog());
+            const suggestion = didYouMean(sourceName, index.sources.map((entry) => entry.name).filter((name) => name.length > 0));
+            // The next command must be RUNNABLE: never the name the planner just
+            // rejected — the bare index when there is no better idea, the suggested
+            // source when there is.
+            error.withDetails({
+                hint: suggestion === undefined
+                    ? `Unknown source "${sourceName}" — list the real ones first.`
+                    : `Unknown source "${sourceName}" — did you mean "${suggestion}"?`,
+                next: [`${options.bin} catalog${suggestion === undefined ? '' : ` ${suggestion}`}`],
+                retryable: false,
+            });
+            return;
+        }
+        if (sourceName === undefined)
+            return;
+        const catalog = parseCatalogSource(await options.fetchCatalog(sourceName));
+        // An empty vocabulary means we did NOT get a catalog: a 200 carrying an
+        // HTML interstitial or a drifted shape parses to empty arrays, and diffing
+        // against that would accuse every CORRECT name in the request.
+        if (catalog.dimensions.length === 0 && catalog.metrics.length === 0) {
+            options.onSkip?.('catalog response carried no vocabulary');
+            return;
+        }
+        const problems = diagnoseUnknownNames(options.body, catalog);
+        if (problems.length > 0)
+            error.withDetails({ hint: describeProblems(problems) });
+    }
+    catch (error_) {
+        options.onSkip?.(error_ instanceof Error ? error_.message : String(error_));
+    }
+}

package/dist/lib/planner/errors.d.ts

@@ -0,0 +1,14 @@
+import { CliError } from '../errors.js';
+export interface PlannerFailure {
+    code: string;
+    message: string;
+}
+export declare function parsePlannerFailure(bodyText: string): PlannerFailure | undefined;
+export declare function plannerCode(bodyText: string): string;
+export interface CatalogContext {
+    bin: string;
+    source?: string;
+    url: string;
+}
+export declare function mapCatalogError(error: unknown, context: CatalogContext): CliError;
+export declare function mapPlannerError(error: unknown): CliError;

package/dist/lib/planner/errors.js

@@ -0,0 +1,129 @@
+import { mapDataError, rateLimited } from '../api/errors.js';
+import { AuthFailedError, CliError, DataHttpError, NetworkError, retryPolicy, UsageError } from '../errors.js';
+import { ExitCode } from '../exit-codes.js';
+import { redact } from '../output/redact.js';
+const MESSAGE_MAX = 500;
+// The planner's codes are SCREAMING_SNAKE enum members. Anything else is not a
+// planner code and gets no trust: `code` flows to stdout as `upstream_code`,
+// so this shape check is what keeps that field bounded and unable to smuggle
+// tokens/ANSI — the one envelope field that would otherwise skip redaction.
+const CODE_SHAPE = /^[A-Z][A-Z0-9_]{0,63}$/;
+// The planner's own error envelope is {code, message} — NOT the {error,
+// error_description} of OAuth nor the {detail} of FastAPI's own validation, so
+// api/errors.ts cannot read it. `detail` (which names tables and columns) is
+// logged server-side and never returned, so there is nothing else to look for.
+export function parsePlannerFailure(bodyText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    if (typeof record.code !== 'string' || !CODE_SHAPE.test(record.code))
+        return undefined;
+    return {
+        code: record.code,
+        message: typeof record.message === 'string' ? record.message.slice(0, MESSAGE_MAX) : '',
+    };
+}
+// The service's own error code for a response body, or '' when this did not come
+// from the planner. Telling those apart is the difference between "typo" and
+// "wrong build" — see the two 404s the catalog command distinguishes.
+export function plannerCode(bodyText) {
+    return parsePlannerFailure(bodyText)?.code ?? '';
+}
+// A catalog failure, with the ONE distinction the generic mapper cannot make.
+//
+// Two different 404s reach this endpoint and they send you to different places:
+// the planner's own UNKNOWN_SOURCE names a source that is not in the catalog (a
+// typo), while FastAPI's bare "Not Found" means the route does not exist at all
+// (an older deployment). Collapsing them into "not found" is how you spend an
+// afternoon checking spelling against a build that never had the endpoint.
+export function mapCatalogError(error, context) {
+    if (!(error instanceof DataHttpError) || error.status !== 404)
+        return mapPlannerError(error);
+    if (plannerCode(error.bodyText) === 'UNKNOWN_SOURCE') {
+        return new CliError(`No catalog entry for '${context.source ?? ''}' — run \`${context.bin} catalog\` to list them.`, 'not_found', ExitCode.GENERIC).withDetails({
+            hint: 'The source name is a catalog key, not a table name.',
+            next: [`${context.bin} catalog`],
+            retryable: false,
+            upstreamCode: 'UNKNOWN_SOURCE',
+        });
+    }
+    const path = context.source === undefined ? '/catalog' : `/catalog/${context.source}`;
+    return new CliError(`${context.url} serves no ${path} — is it running a build that has one?`, 'not_found', ExitCode.GENERIC);
+}
+// Map a planner failure onto the E3 error model. Falls through to mapDataError for
+// anything that is not a recognisable planner envelope, so transport failures,
+// timeouts and already-typed CliErrors keep their existing behaviour.
+//
+// Every planner `message` is built from PUBLIC vocabulary only — the logical names
+// the caller already sent us — which is why it is safe to surface verbatim
+// (redacted defensively all the same).
+export function mapPlannerError(error) {
+    if (!(error instanceof DataHttpError))
+        return mapDataError(error);
+    const failure = parsePlannerFailure(error.bodyText);
+    if (!failure)
+        return mapDataError(error);
+    // Every planner-mapped error carries the planner's own code verbatim (#96):
+    // ENGINE_FAILED and UNKNOWN_DIMENSION are different situations for an agent
+    // even when our own classification of them coincides.
+    return classifyPlannerFailure(error, failure).withDetails({ upstreamCode: failure.code });
+}
+function classifyPlannerFailure(error, failure) {
+    const message = redact(failure.message || `HTTP ${error.status}`);
+    switch (failure.code) {
+        // Unlike the generic 403 mapper (which returns a FIXED message so an upstream
+        // body cannot leak), the planner's INSUFFICIENT_SCOPE message is designed to be
+        // returned: it names the missing scope, or the roles that would do instead.
+        // That is the whole point of checking scopes at the front door rather than
+        // letting a 403 surface two services away as an opaque PULSE_SERVICE_ERROR.
+        // Deterministic auth failures: explicitly NOT retryable — re-presenting the
+        // same token gets the same answer, and `false` is the anti-retry-loop
+        // signal the envelope exists to carry.
+        case 'INSUFFICIENT_SCOPE': {
+            return new AuthFailedError(message, 'role_forbidden').withDetails({ retryable: false });
+        }
+        // The planner's own "I broke, try again" — NetworkError is retryable by
+        // class; thread the server-stated wait through when one was sent.
+        case 'INTERNAL_ERROR': {
+            return new NetworkError(message, 'data_upstream_error').withDetails(retryPolicy(error.retryAfterMs));
+        }
+        case 'INVALID_AUDIENCE': {
+            return new AuthFailedError(`invalid_target: re-bind required — ${message}`, 'invalid_target').withDetails({
+                retryable: false,
+            });
+        }
+        // TOKEN_EXPIRED reaching here means the 401->refresh->retry wrapper already
+        // refreshed successfully and the planner rejected the NEW token too — which is
+        // an auth failure, not an expiry. A refresh that cannot renew raises
+        // session_expired (exit 4) from the wrapper and never gets this far.
+        case 'INVALID_TOKEN':
+        case 'TOKEN_EXPIRED': {
+            return new AuthFailedError(message, 'data_auth_failed').withDetails({ retryable: false });
+        }
+        default: {
+            break;
+        }
+    }
+    // ENGINE_FAILED carries the engine's status: 502 for transport/5xx, 400 when the
+    // engine itself refused. Classify on the status rather than the code so a
+    // retryable upstream failure is exit 7 and a bad request stays exit 1.
+    if (error.status >= 500) {
+        return new NetworkError(message, 'data_upstream_error').withDetails(retryPolicy(error.retryAfterMs));
+    }
+    if (error.status === 429)
+        return rateLimited(message, error.retryAfterMs);
+    if (error.status === 404)
+        return new CliError(message, 'not_found', ExitCode.GENERIC);
+    // A 422 is FastAPI refusing the body shape (`extra="forbid"`), which means WE
+    // emitted something the contract does not allow — a usage error on our side.
+    if (error.status === 422)
+        return new UsageError(message);
+    return new CliError(message, 'data_request_failed', ExitCode.GENERIC);
+}

package/dist/lib/planner/filters.d.ts

@@ -0,0 +1,8 @@
+export type FilterEntry = Record<string, unknown>;
+export interface SortSpec {
+    by: string;
+    dir: 'asc' | 'desc';
+}
+export declare function parseFilter(raw: string): FilterEntry;
+export declare function describeSelections(entries: FilterEntry[]): string[];
+export declare function parseSort(spec: string): SortSpec;