@collage-dam/mcp-server 0.1.0

package/dist/conventions/dry-run/types.d.ts

@@ -0,0 +1,597 @@
+import { z } from 'zod';
+/**
+ * Severity classifier for risk flags surfaced in the preview.
+ * `info` is purely informational, `warning` is recoverable, `critical`
+ * indicates the operation will overwrite data or affect many records.
+ */
+export declare const RiskSeveritySchema: z.ZodEnum<["info", "warning", "critical"]>;
+export type RiskSeverity = z.infer<typeof RiskSeveritySchema>;
+export declare const RiskFlagSchema: z.ZodObject<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["info", "warning", "critical"]>;
+    message: z.ZodString;
+    count: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "critical";
+    count?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "critical";
+    count?: number | undefined;
+}>;
+export type RiskFlag = z.infer<typeof RiskFlagSchema>;
+/**
+ * A single proposed change. `before` and `after` are arbitrary JSON
+ * projections of the field(s) that will mutate. `id` is a stable identifier
+ * for the underlying record so the per-item ledger can correlate failures
+ * back to the planned change.
+ */
+export declare const ChangeRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    operation: z.ZodEnum<["create", "update", "delete"]>;
+    before: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    after: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Tool-specific metadata copied through to the executor. */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    operation: "create" | "update" | "delete";
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    id: string;
+    operation: "create" | "update" | "delete";
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type ChangeRecord = z.infer<typeof ChangeRecordSchema>;
+/**
+ * The serialisable change-script produced by the `plan` phase. This is the
+ * single artefact that flows through the state store and into the executor.
+ *
+ * Generic over the tool-specific input shape so consumers can recover the
+ * original arguments at execute time without re-deriving them.
+ */
+export declare const dryRunPlanSchema: <I extends z.ZodTypeAny>(inputSchema: I) => z.ZodObject<{
+    tool: z.ZodString;
+    input: I;
+    changes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operation: z.ZodEnum<["create", "update", "delete"]>;
+        before: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        after: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Tool-specific metadata copied through to the executor. */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+    risk_flags: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<["info", "warning", "critical"]>;
+        message: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }>, "many">;
+    aggregates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    /** ISO timestamp the plan was generated. */
+    generated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    tool: z.ZodString;
+    input: I;
+    changes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operation: z.ZodEnum<["create", "update", "delete"]>;
+        before: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        after: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Tool-specific metadata copied through to the executor. */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+    risk_flags: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<["info", "warning", "critical"]>;
+        message: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }>, "many">;
+    aggregates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    /** ISO timestamp the plan was generated. */
+    generated_at: z.ZodString;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<{
+    tool: z.ZodString;
+    input: I;
+    changes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operation: z.ZodEnum<["create", "update", "delete"]>;
+        before: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        after: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Tool-specific metadata copied through to the executor. */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: Record<string, unknown> | null;
+        after: Record<string, unknown> | null;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+    risk_flags: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<["info", "warning", "critical"]>;
+        message: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }>, "many">;
+    aggregates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    /** ISO timestamp the plan was generated. */
+    generated_at: z.ZodString;
+}> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>;
+export interface DryRunPlan<TInput> {
+    tool: string;
+    input: TInput;
+    changes: ChangeRecord[];
+    risk_flags: RiskFlag[];
+    /** Numeric counts keyed by category (e.g. `updates`, `creates`, `overwrites`). */
+    aggregates: Record<string, number>;
+    generated_at: string;
+    /**
+     * Stable order-independent hash of the change list. Used by the
+     * auto-refresh path to verify that a re-planned mutation matches the
+     * user's prior intent before continuing past a soft-expired token.
+     */
+    fingerprint: string;
+    /**
+     * The token's soft expiry. After this timestamp an execute call hits
+     * the auto-refresh path; the plan record itself stays in the store
+     * for the longer memo TTL.
+     */
+    token_expires_at: string;
+}
+/**
+ * Tabular row produced by the preview renderer. Cells are stringified for
+ * deterministic display; structured data lives in `DryRunPlan.changes`.
+ */
+export declare const PreviewRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    operation: z.ZodEnum<["create", "update", "delete"]>;
+    field: z.ZodString;
+    before: z.ZodString;
+    after: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    operation: "create" | "update" | "delete";
+    before: string;
+    after: string;
+    field: string;
+}, {
+    id: string;
+    operation: "create" | "update" | "delete";
+    before: string;
+    after: string;
+    field: string;
+}>;
+export type PreviewRow = z.infer<typeof PreviewRowSchema>;
+export declare const DryRunPreviewSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operation: z.ZodEnum<["create", "update", "delete"]>;
+        field: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: string;
+        after: string;
+        field: string;
+    }, {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: string;
+        after: string;
+        field: string;
+    }>, "many">;
+    /** Column headers in order. */
+    columns: z.ZodArray<z.ZodString, "many">;
+    summary: z.ZodString;
+    risk_flags: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<["info", "warning", "critical"]>;
+        message: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }, {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }>, "many">;
+    aggregates: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    /** True if `rows` was truncated for display. */
+    truncated: z.ZodBoolean;
+    /** Total row count before truncation. */
+    total_rows: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    rows: {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: string;
+        after: string;
+        field: string;
+    }[];
+    columns: string[];
+    summary: string;
+    risk_flags: {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }[];
+    aggregates: Record<string, number>;
+    truncated: boolean;
+    total_rows: number;
+}, {
+    rows: {
+        id: string;
+        operation: "create" | "update" | "delete";
+        before: string;
+        after: string;
+        field: string;
+    }[];
+    columns: string[];
+    summary: string;
+    risk_flags: {
+        code: string;
+        message: string;
+        severity: "info" | "warning" | "critical";
+        count?: number | undefined;
+    }[];
+    aggregates: Record<string, number>;
+    truncated: boolean;
+    total_rows: number;
+}>;
+export type DryRunPreview = z.infer<typeof DryRunPreviewSchema>;
+export declare const ItemLedgerEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    operation: z.ZodEnum<["create", "update", "delete"]>;
+    ok: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodEnum<["UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION", "RATE_LIMITED", "UPSTREAM", "CONFIRMATION_STALE", "CONFIRMATION_MISSING", "CONFIRMATION_STATE_DIVERGED", "ENTITLEMENT", "INTERNAL"]>;
+        message: z.ZodString;
+        retriable: z.ZodBoolean;
+        cause: z.ZodOptional<z.ZodObject<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+        message: string;
+        retriable: boolean;
+        cause?: z.objectOutputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+        message: string;
+        retriable: boolean;
+        cause?: z.objectInputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    }>>;
+    /** Optional opaque result payload (e.g. updated record id). */
+    result: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    ok: boolean;
+    operation: "create" | "update" | "delete";
+    error?: {
+        code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+        message: string;
+        retriable: boolean;
+        cause?: z.objectOutputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    result?: unknown;
+}, {
+    id: string;
+    ok: boolean;
+    operation: "create" | "update" | "delete";
+    error?: {
+        code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+        message: string;
+        retriable: boolean;
+        cause?: z.objectInputType<{
+            upstream_status: z.ZodOptional<z.ZodNumber>;
+            request_id: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough"> | undefined;
+    } | undefined;
+    result?: unknown;
+}>;
+export type ItemLedgerEntry = z.infer<typeof ItemLedgerEntrySchema>;
+export declare const ProgressEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"progress">;
+    completed: z.ZodNumber;
+    total: z.ZodNumber;
+    /** Wall-clock timestamp for the event. */
+    ts: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "progress";
+    total: number;
+    completed: number;
+    ts: string;
+}, {
+    type: "progress";
+    total: number;
+    completed: number;
+    ts: string;
+}>;
+export type ProgressEvent = z.infer<typeof ProgressEventSchema>;
+export declare const ExecuteResultSchema: z.ZodObject<{
+    tool: z.ZodString;
+    confirmation_id: z.ZodString;
+    ledger: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        operation: z.ZodEnum<["create", "update", "delete"]>;
+        ok: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodObject<{
+            code: z.ZodEnum<["UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "VALIDATION", "RATE_LIMITED", "UPSTREAM", "CONFIRMATION_STALE", "CONFIRMATION_MISSING", "CONFIRMATION_STATE_DIVERGED", "ENTITLEMENT", "INTERNAL"]>;
+            message: z.ZodString;
+            retriable: z.ZodBoolean;
+            cause: z.ZodOptional<z.ZodObject<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough">>>;
+        }, "strip", z.ZodTypeAny, {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        }, {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectInputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        }>>;
+        /** Optional opaque result payload (e.g. updated record id). */
+        result: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        ok: boolean;
+        operation: "create" | "update" | "delete";
+        error?: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        } | undefined;
+        result?: unknown;
+    }, {
+        id: string;
+        ok: boolean;
+        operation: "create" | "update" | "delete";
+        error?: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectInputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        } | undefined;
+        result?: unknown;
+    }>, "many">;
+    totals: z.ZodObject<{
+        attempted: z.ZodNumber;
+        succeeded: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    }, {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    }>;
+    /** Rolled-up progress events when streaming is unavailable (HTTP transport). */
+    progress: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"progress">;
+        completed: z.ZodNumber;
+        total: z.ZodNumber;
+        /** Wall-clock timestamp for the event. */
+        ts: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "progress";
+        total: number;
+        completed: number;
+        ts: string;
+    }, {
+        type: "progress";
+        total: number;
+        completed: number;
+        ts: string;
+    }>, "many">;
+    started_at: z.ZodString;
+    completed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tool: string;
+    progress: {
+        type: "progress";
+        total: number;
+        completed: number;
+        ts: string;
+    }[];
+    confirmation_id: string;
+    ledger: {
+        id: string;
+        ok: boolean;
+        operation: "create" | "update" | "delete";
+        error?: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectOutputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        } | undefined;
+        result?: unknown;
+    }[];
+    totals: {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    };
+    started_at: string;
+    completed_at: string;
+}, {
+    tool: string;
+    progress: {
+        type: "progress";
+        total: number;
+        completed: number;
+        ts: string;
+    }[];
+    confirmation_id: string;
+    ledger: {
+        id: string;
+        ok: boolean;
+        operation: "create" | "update" | "delete";
+        error?: {
+            code: "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION" | "RATE_LIMITED" | "UPSTREAM" | "CONFIRMATION_STALE" | "CONFIRMATION_MISSING" | "CONFIRMATION_STATE_DIVERGED" | "ENTITLEMENT" | "INTERNAL";
+            message: string;
+            retriable: boolean;
+            cause?: z.objectInputType<{
+                upstream_status: z.ZodOptional<z.ZodNumber>;
+                request_id: z.ZodOptional<z.ZodString>;
+            }, z.ZodTypeAny, "passthrough"> | undefined;
+        } | undefined;
+        result?: unknown;
+    }[];
+    totals: {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    };
+    started_at: string;
+    completed_at: string;
+}>;
+export interface ExecuteResult<TItemResult = unknown> {
+    tool: string;
+    confirmation_id: string;
+    ledger: Array<Omit<ItemLedgerEntry, 'result'> & {
+        result?: TItemResult;
+    }>;
+    totals: {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    };
+    progress: ProgressEvent[];
+    started_at: string;
+    completed_at: string;
+}
+/**
+ * The dry-run envelope returned to the caller after the plan phase. The
+ * caller echoes back `confirmation.signed_token` to invoke execute.
+ */
+export interface DryRunResponse<TInput> {
+    dry_run: true;
+    plan: DryRunPlan<TInput>;
+    preview: DryRunPreview;
+    confirmation: {
+        confirmation_id: string;
+        signed_token: string;
+        expires_at: string;
+        /** TTL of the token in seconds (matches `expires_at` modulo `now`). */
+        ttl_seconds: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/conventions/dry-run/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/conventions/dry-run/types.ts"],"names":[],"mappings":"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"}