@embrasure/ember 0.2.0

package/dist/operator.js

@@ -0,0 +1,493 @@
+import { createHash } from "node:crypto";
+import { EmbrasureApiClient } from "@embrasure/api-client";
+import { readCatalog } from "./catalog.js";
+import { editPluginCatalog, editPluginIngestion } from "./plugin-edits.js";
+import { operatePluginDeletion, isDeletionAction } from "./plugin-deletion.js";
+import { operatePluginPolicy } from "./plugin-policy.js";
+import { queryHistoryResponseSchema, queryResponseSchema, queryResultsResponseSchema } from "./query-response.js";
+const SOURCE_KINDS = new Set(["postgres", "supabase", "salesforce", "stripe", "hubspot", "posthog", "mixpanel", "apollo", "google_sheets", "openapi"]);
+const SECRET_KEY = /(secret|password|credential|token|api[_-]?key|private[_-]?key)/i;
+const SAFE_OPAQUE_KEYS = new Set(["next_token", "nextToken"]);
+const MAX_LIST_ITEMS = 100;
+const MAX_CONNECTOR_LOOKUP_ITEMS = 200;
+const MAX_OUTPUT_BYTES = 64_000;
+const MAX_UPSTREAM_BYTES = 2_097_152;
+const MAX_INGESTION_TABLES = 50;
+function asJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function bounded(value) {
+    let remaining = MAX_OUTPUT_BYTES;
+    let truncated = false;
+    const spend = (amount) => { remaining -= amount; if (remaining < 0)
+        truncated = true; };
+    const walk = (current, key = "", depth = 0) => {
+        spend(4);
+        if (remaining <= 0 || depth > 12) {
+            truncated = true;
+            return "[truncated]";
+        }
+        if (!SAFE_OPAQUE_KEYS.has(key) && SECRET_KEY.test(key))
+            return "[redacted]";
+        if (typeof current === "string") {
+            const text = current.slice(0, Math.min(12_000, remaining));
+            spend(text.length);
+            if (text.length < current.length)
+                truncated = true;
+            return text;
+        }
+        if (current === null || ["number", "boolean"].includes(typeof current)) {
+            spend(16);
+            return current;
+        }
+        if (Array.isArray(current)) {
+            if (current.length > MAX_LIST_ITEMS)
+                truncated = true;
+            return current.slice(0, MAX_LIST_ITEMS).map((item) => walk(item, "", depth + 1));
+        }
+        if (typeof current === "object") {
+            const entries = Object.entries(current);
+            if (entries.length > MAX_LIST_ITEMS)
+                truncated = true;
+            return Object.fromEntries(entries.slice(0, MAX_LIST_ITEMS).map(([childKey, child]) => {
+                const safeKey = childKey.slice(0, 256);
+                if (safeKey.length < childKey.length)
+                    truncated = true;
+                spend(safeKey.length);
+                return [safeKey, walk(child, safeKey, depth + 1)];
+            }));
+        }
+        return String(current);
+    };
+    const result = walk(value);
+    const object = typeof result === "object" && result !== null && !Array.isArray(result) ? result : { value: result };
+    const boundedResult = truncated ? { ...object, _truncated: true } : object;
+    const serialized = JSON.stringify(boundedResult);
+    if (Buffer.byteLength(serialized, "utf8") <= MAX_OUTPUT_BYTES)
+        return boundedResult;
+    return {
+        _truncated: true,
+        message: "Output exceeded the structured response limit. Narrow the request or use pagination.",
+        preview: serialized.slice(0, 8_000),
+    };
+}
+function summarizeIngestion(value) {
+    const record = value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : { value };
+    const rawTables = Array.isArray(record.tables) ? record.tables : [];
+    const tableCount = typeof record.table_count === "number" ? record.table_count : rawTables.length;
+    const statuses = {};
+    for (const raw of rawTables) {
+        const table = raw && typeof raw === "object" ? raw : {};
+        const status = String(table.status ?? "unknown");
+        statuses[status] = (statuses[status] ?? 0) + 1;
+    }
+    const tables = rawTables.slice(0, MAX_INGESTION_TABLES).map((raw) => {
+        const table = raw && typeof raw === "object" ? raw : {};
+        return {
+            id: table.id,
+            source_schema: table.source_schema,
+            source_table: table.source_table,
+            destination_schema: table.destination_schema,
+            destination_table: table.destination_table,
+            status: table.status,
+            cursor_column: table.cursor_column,
+            incremental_strategy: table.incremental_strategy,
+            primary_key_columns: table.primary_key_columns,
+            selected_columns_count: Array.isArray(table.selected_columns) ? table.selected_columns.length : undefined,
+            schema_drift_status: table.schema_drift_status,
+            schema_change_status: table.schema_change_status,
+            lag_seconds: table.lag_seconds,
+            rows_inserted: table.rows_inserted,
+            rows_updated: table.rows_updated,
+            rows_deleted: table.rows_deleted,
+            last_synced_at: table.last_synced_at,
+            last_error_code: table.last_error_code,
+            last_error_message: table.last_error_message,
+        };
+    });
+    const events = (Array.isArray(record.events) ? record.events : []).slice(0, 20).map((raw) => {
+        const event = raw && typeof raw === "object" ? raw : {};
+        return {
+            id: event.id,
+            event_type: event.event_type,
+            severity: event.severity,
+            message: event.message,
+            table_id: event.table_id,
+            run_id: event.run_id,
+            created_at: event.created_at,
+        };
+    });
+    const { tables: _tables, events: _events, setup_guidance: _setupGuidance, ...summary } = record;
+    return {
+        ...summary,
+        table_count: tableCount,
+        table_status_counts: statuses,
+        tables,
+        tables_truncated: tableCount > tables.length,
+        recent_events: events,
+    };
+}
+function withHandle(value, key, fallback) {
+    const record = value && typeof value === "object" && !Array.isArray(value) ? value : { value };
+    const handle = record[key] ?? record.id ?? fallback;
+    const output = bounded(record);
+    if (typeof handle !== "string" || !handle || handle.length > 128)
+        return output;
+    const withHandle = { ...output, [key]: handle };
+    return Buffer.byteLength(JSON.stringify(withHandle), "utf8") <= MAX_OUTPUT_BYTES ? withHandle : {
+        [key]: handle, _truncated: true, message: "Operation accepted; inspect this handle for details.",
+    };
+}
+export class EmberOperatorError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "EmberOperatorError";
+    }
+}
+function invalidQueryResponse(action) {
+    throw new EmberOperatorError("invalid_api_response", `The API returned an invalid response for query.${action}. No usable result was returned. Inspect query status/history before retrying a run or cancellation; the operation may already have been accepted.`);
+}
+export class EmberOperator {
+    client;
+    workspaceId;
+    constructor(options) {
+        if (!options.workspaceId)
+            throw new EmberOperatorError("workspace_required", "Select a workspace first.");
+        if (!options.accessToken)
+            throw new EmberOperatorError("authentication_required", "Log in before using Ember.");
+        this.workspaceId = options.workspaceId;
+        this.client = new EmbrasureApiClient({
+            baseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            fetchImpl: async (url, init) => {
+                const isReceipt = String(url).endsWith("/operator/tool-events");
+                const timeout = AbortSignal.timeout(isReceipt ? 2_000 : options.requestTimeoutMs ?? 60_000);
+                const signal = AbortSignal.any([timeout, ...(!isReceipt && options.signal ? [options.signal] : []), ...(init?.signal ? [init.signal] : [])]);
+                signal.throwIfAborted();
+                const response = await (options.fetchImpl ?? globalThis.fetch)(url, { ...init, signal });
+                if (!response.body)
+                    return response;
+                let receivedBytes = 0;
+                const body = response.body.pipeThrough(new TransformStream({
+                    transform(chunk, controller) {
+                        receivedBytes += chunk.byteLength;
+                        if (receivedBytes > MAX_UPSTREAM_BYTES) {
+                            throw new EmberOperatorError("upstream_response_too_large", "The API response exceeded 2 MiB. Narrow the request or reduce its page size. If a change was started, inspect status/history before retrying it.");
+                        }
+                        controller.enqueue(chunk);
+                    },
+                }), { signal });
+                return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+            },
+            clientName: options.clientName ?? "ember",
+        });
+    }
+    async execute(request) {
+        const startedAt = performance.now();
+        try {
+            let result;
+            switch (request.tool) {
+                case "warehouse":
+                    result = await this.warehouse(request.input);
+                    break;
+                case "sources":
+                    result = await this.sources(request.input);
+                    break;
+                case "ingestion":
+                    result = await this.ingestion(request.input);
+                    break;
+                case "query":
+                    result = await this.query(request.input);
+                    break;
+                case "catalog":
+                    result = await this.catalog(request.input);
+                    break;
+            }
+            await this.recordToolEvent(request, result, "success", performance.now() - startedAt);
+            return result;
+        }
+        catch (error) {
+            await this.recordToolEvent(request, undefined, "error", performance.now() - startedAt);
+            throw error;
+        }
+    }
+    async setup(input) {
+        const data = await this.client.request(`/v1/ember/workspaces/${encodeURIComponent(this.workspaceId)}/operator/setup`, {
+            method: "POST",
+            body: { action: input.action, database: input.database ?? "ember" },
+        });
+        return { ok: true, action: `setup.${input.action}`, data: bounded(data) };
+    }
+    async status() {
+        const data = await this.client.request(`/v1/ember/workspaces/${encodeURIComponent(this.workspaceId)}/operator/status`);
+        const output = bounded(data);
+        return {
+            ok: true,
+            action: "status",
+            data: output,
+            next_action: typeof output.next_action === "string" ? output.next_action : undefined,
+        };
+    }
+    async sources(input) {
+        if (input.action === "types") {
+            const data = await this.client.request(`/v1/workspaces/${encodeURIComponent(this.workspaceId)}/warehouse/ingestion-sources`);
+            const items = data.filter((source) => SOURCE_KINDS.has(source.kind) && source.release_stage !== "in_progress");
+            return { ok: true, action: "sources.types", data: bounded({ items }) };
+        }
+        if (input.action === "list") {
+            const data = await this.client.listConnectors(this.workspaceId, MAX_LIST_ITEMS, { connectorUsage: "warehouse_ingestion" });
+            const truncated = data.length >= MAX_LIST_ITEMS;
+            return {
+                ok: true, action: "sources.list", data: bounded({ items: data, truncated }),
+                ...(truncated ? { next_action: "The source list reached its limit and may be incomplete. Inspect a known connection_id with sources status; do not infer that an unlisted source is absent." } : {}),
+            };
+        }
+        if (input.action === "connect") {
+            if (!SOURCE_KINDS.has(input.kind)) {
+                throw new EmberOperatorError("unsupported_source", `Unsupported source kind: ${input.kind}`);
+            }
+            const data = await this.client.request(`/v1/ember/workspaces/${encodeURIComponent(this.workspaceId)}/operator/source-handoffs`, {
+                method: "POST",
+                body: { kind: input.kind, name: input.name, mode: input.mode, return_to: input.return_to },
+            });
+            return { ok: true, action: "sources.connect", data: bounded(data), next_action: "Open authorization_url to finish connecting the source." };
+        }
+        const lookup = input;
+        const connectors = await this.client.listConnectors(this.workspaceId, MAX_CONNECTOR_LOOKUP_ITEMS, { connectorUsage: "warehouse_ingestion" });
+        const connector = connectors.find((item) => item.id === lookup.connection_id);
+        if (!connector && connectors.length >= MAX_CONNECTOR_LOOKUP_ITEMS) {
+            throw new EmberOperatorError("source_lookup_incomplete", "The bounded source list is full, so this lookup cannot establish whether the connection exists. Inspect the source in Ember; do not create a duplicate connection.");
+        }
+        if (!connector)
+            throw new EmberOperatorError("connection_not_found", "Source connection was not found in this workspace.");
+        if (input.action === "status")
+            return { ok: true, action: "sources.status", data: withHandle(connector, "connection_id", connector.id) };
+        const verification = await this.client.request(`/v1/connectors/${encodeURIComponent(connector.kind)}/verify`, {
+            method: "POST",
+            body: { workspace_id: this.workspaceId, connector_id: connector.id },
+        });
+        return { ok: true, action: "sources.verify", data: withHandle(verification, "connection_id", connector.id) };
+    }
+    async ingestion(input) {
+        if (input.action === "inspect_table" || input.action === "edit_table") {
+            return { ok: true, action: `ingestion.${input.action}`, data: bounded(await editPluginIngestion(this.client, this.workspaceId, input)) };
+        }
+        if (input.action === "status") {
+            const data = input.ingestion_run_id
+                ? await this.client.getWarehouseIngestionConnection(this.workspaceId, input.ingestion_run_id)
+                : await this.listIngestionSummaries();
+            return {
+                ok: true,
+                action: "ingestion.status",
+                data: Array.isArray(data)
+                    ? bounded({ items: data.map(summarizeIngestion) })
+                    : withHandle(summarizeIngestion(data), "ingestion_run_id", input.ingestion_run_id),
+            };
+        }
+        if (input.action === "sync" || input.action === "pause" || input.action === "resume") {
+            const suffix = input.action;
+            const data = await this.client.request(`/v1/workspaces/${encodeURIComponent(this.workspaceId)}/warehouse/ingestion-connections/${encodeURIComponent(input.ingestion_run_id)}/${suffix}`, { method: "POST" });
+            return { ok: true, action: `ingestion.${input.action}`, data: withHandle(data, "ingestion_run_id", input.ingestion_run_id) };
+        }
+        const startInput = input;
+        if (startInput.tables && startInput.tables.length === 0)
+            throw new EmberOperatorError("no_selected_tables", "An explicit empty table list selects no tables. Omit tables to connect all eligible tables, or provide the intended selection.");
+        const databaseId = startInput.database_id ?? (await this.defaultDatabaseId());
+        const engine = startInput.ingestion_engine ?? "worker_batch";
+        const allTables = startInput.tables === undefined;
+        const selectedTables = (startInput.tables ?? []).map((table) => ({
+            ...table,
+            primary_key_columns: table.primary_key_columns ?? [],
+            selected_columns: table.selected_columns ?? [],
+            incremental_strategy: table.incremental_strategy ?? (engine === "worker_batch" ? "cursor" : "cdc"),
+        }));
+        const body = {
+            connector_id: startInput.connection_id,
+            warehouse_database_id: databaseId,
+            source_kind: startInput.source_kind,
+            ingestion_engine: engine,
+            schedule_interval_minutes: startInput.cadence_minutes,
+            tables: selectedTables,
+            ...(startInput.action === "start" ? { name: startInput.name ?? `${startInput.source_kind} ingestion` } : {}),
+        };
+        const plan = await this.client.preflightWarehouseIngestionConnection(this.workspaceId, body);
+        const autoAddNewTables = allTables && engine === "worker_batch";
+        if (startInput.action === "plan")
+            return { ok: true, action: "ingestion.plan", data: bounded({ ...plan, selection_mode: allTables ? "all_eligible" : "explicit", auto_add_new_tables: autoAddNewTables }) };
+        if (allTables && typeof plan.summary?.total === "number" && plan.summary.total !== plan.tables?.length) {
+            throw new EmberOperatorError("incomplete_table_inventory", "The preflight table inventory is incomplete. Inspect ingestion plan before starting; no tables were connected.");
+        }
+        const plannedTables = selectedTables.length
+            ? selectedTables
+            : (plan.tables ?? [])
+                .filter((table) => !table.blocking_reasons?.length && table.recommended_selection)
+                .map((table) => table.recommended_selection);
+        if (!plannedTables.length)
+            throw new EmberOperatorError("no_eligible_tables", "No eligible tables passed ingestion preflight.");
+        const data = await this.client.createWarehouseIngestionConnection(this.workspaceId, { ...body, tables: plannedTables, auto_add_new_tables: autoAddNewTables });
+        const skipped = allTables ? Math.max(0, (plan.tables?.length ?? 0) - plannedTables.length) : 0;
+        return {
+            ok: true, action: `ingestion.${startInput.action}`,
+            data: withHandle({ ...data, selection_mode: allTables ? "all_eligible" : "explicit", selected_table_count: plannedTables.length, blocked_table_count: skipped }, "ingestion_run_id"),
+            next_action: skipped
+                ? `${skipped} discovered tables need attention and were not connected. Inspect ingestion plan for exact blocking reasons; keep working with the connected tables and report this coverage gap.`
+                : "Inspect ingestion status until tables are synced, then use catalog and read-only queries to produce the first answer with evidence.",
+        };
+    }
+    async query(input) {
+        if (input.action === "run") {
+            if (input.max_result_rows !== undefined && input.max_result_rows !== 10000) {
+                throw new EmberOperatorError("invalid_result_row_cap", "The retained-result cap must be 10000. Use SQL LIMIT for fewer rows or query.results limit for smaller pages.");
+            }
+            const data = await this.client.createWarehouseReadonlyQuery(this.workspaceId, {
+                sql: input.sql,
+                default_database: input.database ?? "ember",
+                max_result_rows: input.max_result_rows,
+            });
+            const parsed = queryResponseSchema.safeParse(data);
+            if (!parsed.success)
+                invalidQueryResponse(input.action);
+            return { ok: true, action: "query.run", data: withHandle({ ...parsed.data, query_id: parsed.data.id }, "query_id") };
+        }
+        if (input.action === "history") {
+            const data = await this.client.listWarehouseQueries(this.workspaceId, { limit: Math.min(input.limit ?? 25, 100) });
+            const parsed = queryHistoryResponseSchema.safeParse(data);
+            if (!parsed.success)
+                invalidQueryResponse(input.action);
+            return { ok: true, action: "query.history", data: bounded({ items: parsed.data }) };
+        }
+        if (input.action === "results") {
+            const data = await this.client.getWarehouseQueryResults(this.workspaceId, input.query_id, {
+                maxResults: Math.min(input.limit ?? 100, 100),
+                nextToken: input.next_token,
+            });
+            const parsed = queryResultsResponseSchema.safeParse(data);
+            if (!parsed.success || parsed.data.query.id !== input.query_id)
+                invalidQueryResponse(input.action);
+            const page = bounded(parsed.data);
+            if (page._truncated) {
+                throw new EmberOperatorError("result_page_too_large", "This result page exceeds the response budget. Retry the SAME query_id and next_token with a smaller limit. If one row is still too large, select fewer columns or shorter values. No rows or advanced cursor were returned.");
+            }
+            return { ok: true, action: "query.results", data: page };
+        }
+        const data = input.action === "cancel"
+            ? await this.client.cancelWarehouseQuery(this.workspaceId, input.query_id)
+            : await this.client.getWarehouseQuery(this.workspaceId, input.query_id);
+        const parsed = queryResponseSchema.safeParse(data);
+        if (!parsed.success || parsed.data.id !== input.query_id)
+            invalidQueryResponse(input.action);
+        return { ok: true, action: `query.${input.action}`, data: withHandle({ ...parsed.data, query_id: parsed.data.id }, "query_id") };
+    }
+    async warehouse(input) {
+        if (input.action === "usage") {
+            const data = await this.client.request("/v1/workspace-usage", {
+                query: { workspace_id: this.workspaceId, window: input.window ?? "month_to_date" },
+            });
+            return { ok: true, action: "warehouse.usage", data: bounded(data) };
+        }
+        const result = input.action === "status" ? await this.status() : await this.setup(input);
+        return { ...result, action: `warehouse.${input.action}` };
+    }
+    async catalog(input) {
+        if (isDeletionAction(input)) {
+            const data = bounded(await operatePluginDeletion(this.client, this.workspaceId, input));
+            if (data._truncated)
+                throw new EmberOperatorError("deletion_response_too_large", "Open Governance deletion history for the complete request; do not infer completion from a partial result.");
+            return { ok: true, action: `catalog.${input.action}`, data, next_action: ["preview_deletion", "preview_automatic_request"].includes(input.action) ? "Review the affected counts and scope with the user. Execute this exact request only after explicit confirmation." : ["automatic_requests", "configure_automatic_requests", "check_automatic_requests"].includes(input.action) ? "Automatic requests only collect consent withdrawals and expiry. Review a pending request with preview_automatic_request; deletion still requires a fresh preview and explicit confirmation." : "Read deletion_history for request outcomes. Unconfigured copies and re-ingestion are not covered." };
+        }
+        if (input.action === "save_requirements" || input.action === "policy_context" || input.action === "record_assessment") {
+            const data = bounded(await operatePluginPolicy(this.client, this.workspaceId, input));
+            if (data._truncated)
+                throw new EmberOperatorError("policy_context_too_large", "The policy context exceeds the response budget. Open its Embrasure policy page for complete requirements and evidence; do not treat a partial response as complete coverage.");
+            return { ok: true, action: `catalog.${input.action}`, data,
+                next_action: input.action === "policy_context"
+                    ? "Use the pinned revision and source-backed requirements in your existing coding agent. Resolve open questions and coverage gaps before implementing. Report evidence against this revision; this context is not a compliance certification."
+                    : input.preview !== false
+                        ? "Review the proposed source or assessment, then apply the requested change with preview=false."
+                        : "Read policy_context to confirm the saved state. External assessment results are reported evidence, not independent verification." };
+        }
+        if (input.action === "save" || input.action === "correct") {
+            return { ok: true, action: `catalog.${input.action}`, data: bounded(await editPluginCatalog(this.client, this.workspaceId, input)) };
+        }
+        const result = await readCatalog(this.client, this.workspaceId, input);
+        const data = bounded(result.data);
+        if (data._truncated && input.action !== "search") {
+            throw new EmberOperatorError("catalog_page_too_large", "This catalog page exceeds the response budget. Retry the SAME cursor or column_offset with a smaller limit/column_limit. For context describe, set include_related=false. No partial definition or advanced cursor was returned.");
+        }
+        return {
+            ...result, data,
+            ...(data._truncated ? { next_action: "The search response exceeded its budget. Narrow the terms or reduce limit; retrieve a complete definition with catalog describe before SQL." } : {}),
+        };
+    }
+    async defaultDatabaseId() {
+        const databases = await this.client.listWarehouseDatabases(this.workspaceId);
+        const database = databases.find((item) => item.name === "ember") ?? databases[0];
+        if (!database)
+            throw new EmberOperatorError("setup_required", "Run ember setup before configuring ingestion.");
+        return database.id;
+    }
+    async listIngestionSummaries() {
+        return this.client.request(`/v1/workspaces/${encodeURIComponent(this.workspaceId)}/warehouse/ingestion-connections`, { query: { details: false } });
+    }
+    async recordToolEvent(request, result, outcome, durationMs) {
+        const handles = request.tool === "catalog" && isDeletionAction(request.input)
+            ? resourceHandles({ request_id: result?.data.request_id })
+            : resourceHandles(result?.data);
+        const cost = result?.data.cost_usd;
+        await this.client.recordEmberOperatorToolEvent(this.workspaceId, {
+            tool: request.tool,
+            action: result?.action ?? `${request.tool}.${String(request.input.action ?? "run")}`,
+            argument_hash: createHash("sha256").update(stableJson(request.input)).digest("hex"),
+            outcome,
+            duration_ms: Math.min(Math.max(durationMs, 0), 300_000),
+            resource_handles: handles,
+            cost_usd: typeof cost === "number" && Number.isFinite(cost) && cost >= 0 ? cost : undefined,
+        }).catch(() => undefined);
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function resourceHandles(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const handles = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (Object.keys(handles).length >= 10)
+            break;
+        if (key.endsWith("_id") && typeof child === "string" && child)
+            handles[key.slice(0, 100)] = child.slice(0, 200);
+    }
+    return handles;
+}
+export function stableError(error) {
+    if (error instanceof Error && ["AbortError", "TimeoutError"].includes(error.name)) {
+        return {
+            ok: false, action: "error",
+            data: { code: error.name === "TimeoutError" ? "operation_timed_out" : "operation_cancelled", retryable: false,
+                message: "The request stopped before its outcome was confirmed. Check warehouse, ingestion, or query status/history before retrying a change; disconnecting does not undo work already accepted by the API." },
+        };
+    }
+    const known = error instanceof EmberOperatorError;
+    const apiError = (error && typeof error === "object" ? error : {});
+    const code = known ? error.code : apiError.code ?? (apiError.status === 401 ? "authentication_required" : "operation_failed");
+    return {
+        ok: false,
+        action: "error",
+        data: bounded({ code, message: error instanceof Error ? error.message : "The Ember operation failed.", retryable: known ? error.retryable : false }),
+    };
+}
+export { bounded as boundOperatorOutput, asJson };

package/dist/plugin-deletion.d.ts

@@ -0,0 +1,29 @@
+import type { EmbrasureApiClient } from "@embrasure/api-client";
+import type { PluginDeletionInput } from "./types.js";
+export declare function isDeletionAction(input: {
+    action: string;
+}): input is PluginDeletionInput;
+/** Uses the same scoped preview/confirmation API as Governance, never caller-provided SQL. */
+export declare function operatePluginDeletion(client: EmbrasureApiClient, workspaceId: string, input: PluginDeletionInput): Promise<import("@embrasure/api-client").AutomaticRequestsState | import("@embrasure/api-client").DeletionConfiguration | {
+    requests: import("@embrasure/api-client").DeletionRequest[];
+    truncated: boolean;
+} | {
+    request_id: string;
+    id: string;
+    status: "preview" | "running" | "completed" | "failed" | "unknown";
+    subject_id: string;
+    configuration_revision: string;
+    created_at: string;
+    expires_at: string;
+    requested_by: string;
+    executed_by?: string;
+    started_at?: string;
+    completed_at?: string;
+    error?: string;
+    targets: Array<import("@embrasure/api-client").DeletionTarget & {
+        matched_rows: number;
+        deleted_rows?: number;
+        remaining_rows?: number;
+        query_id?: string | null;
+    }>;
+}>;

package/dist/plugin-deletion.js

@@ -0,0 +1,30 @@
+const actions = new Set(["deletion_config", "configure_deletion", "preview_deletion", "execute_deletion", "deletion_history", "automatic_requests", "configure_automatic_requests", "check_automatic_requests", "preview_automatic_request"]);
+export function isDeletionAction(input) {
+    return actions.has(input.action);
+}
+/** Uses the same scoped preview/confirmation API as Governance, never caller-provided SQL. */
+export async function operatePluginDeletion(client, workspaceId, input) {
+    switch (input.action) {
+        case "automatic_requests": return client.getAutomaticRequests(workspaceId);
+        case "configure_automatic_requests": {
+            const { action: _action, ...configuration } = input;
+            return client.saveAutomaticRequests(workspaceId, configuration);
+        }
+        case "check_automatic_requests": return client.checkAutomaticRequests(workspaceId);
+        case "preview_automatic_request": {
+            const data = await client.previewAutomaticRequest(workspaceId, input.request_id);
+            return { ...data, request_id: data.id };
+        }
+        case "deletion_config": return client.getDeletionConfiguration(workspaceId);
+        case "deletion_history": return client.listDeletionRequests(workspaceId);
+        case "configure_deletion": return client.saveDeletionConfiguration(workspaceId, { targets: input.targets, expected_revision: input.expected_revision });
+        case "preview_deletion": {
+            const data = await client.previewDeletionRequest(workspaceId, { subject_id: input.subject_id, configuration_revision: input.configuration_revision });
+            return { ...data, request_id: data.id };
+        }
+        case "execute_deletion": {
+            const data = await client.executeDeletionRequest(workspaceId, input.request_id, { confirmation: input.confirmation });
+            return { ...data, request_id: data.id };
+        }
+    }
+}