botmux 2.111.0 → 2.112.0

package/dist/workflows/v3/run-envelope.d.ts

@@ -0,0 +1,1279 @@
+/**
+ * Immutable v3 run execution envelope.
+ *
+ * `run.json` is the durable authorization/identity boundary between the
+ * pre-runtime product flows (grill Gate-2, saved-definition instantiation, or
+ * the local developer CLI) and the v3 scheduler.  It deliberately contains no
+ * mutable phase/status: once execution starts, `journal.ndjson` is the only
+ * state truth and `STATE` remains a derived projection.
+ *
+ * Publication is create-once.  Every referenced artifact is pinned by the
+ * SHA-256 of its exact bytes; readers verify and parse those same bytes so a
+ * caller cannot approve one DAG and execute a different one after a re-read.
+ */
+import { z } from 'zod';
+import { type V3Dag } from './dag.js';
+import type { Spec } from './contract.js';
+import type { RunChatBinding } from './grill-state.js';
+export declare const V3_RUN_ENVELOPE_FILE = "run.json";
+export declare const V3_RUN_ENVELOPE_SCHEMA_VERSION: 1;
+export declare const V3_RUN_ENGINE: "workflow-v3";
+export type Sha256Digest = `sha256:${string}`;
+export type V3RunArtifactPath = 'dag.json' | 'spec.json' | 'bots.snapshot.json' | 'params.resolved.json' | 'definition.snapshot.json';
+export interface V3ArtifactRef<Path extends V3RunArtifactPath = V3RunArtifactPath> {
+    path: Path;
+    sha256: Sha256Digest;
+}
+/** Strict v1 schema. Unknown keys are rejected at every envelope-owned level. */
+export declare const V3RunEnvelopeSchema: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
+    source: z.ZodObject<{
+        kind: z.ZodLiteral<"ad_hoc">;
+        grillStatePath: z.ZodLiteral<"grill.state.json">;
+    }, "strict", z.ZodTypeAny, {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    }, {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    }>;
+    artifacts: z.ZodObject<{
+        dag: z.ZodObject<{
+            path: z.ZodLiteral<"dag.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        }, {
+            sha256: string;
+            path: "dag.json";
+        }>;
+        spec: z.ZodObject<{
+            path: z.ZodLiteral<"spec.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        }, {
+            sha256: string;
+            path: "spec.json";
+        }>;
+        botSnapshots: z.ZodObject<{
+            path: z.ZodLiteral<"bots.snapshot.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        }, {
+            sha256: string;
+            path: "bots.snapshot.json";
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    }, {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    }>;
+    authorization: z.ZodObject<{
+        kind: z.ZodLiteral<"gate2">;
+        authorizedAt: z.ZodString;
+        authorizedByOpenId: z.ZodOptional<z.ZodString>;
+        dagSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        specSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        authorizedByOpenId?: string | undefined;
+    }, {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        authorizedByOpenId?: string | undefined;
+    }>;
+    schemaVersion: z.ZodLiteral<1>;
+    engine: z.ZodLiteral<"workflow-v3">;
+    runId: z.ZodString;
+    createdAt: z.ZodString;
+    chatBinding: z.ZodOptional<z.ZodObject<{
+        larkAppId: z.ZodString;
+        chatId: z.ZodString;
+        chatType: z.ZodOptional<z.ZodEnum<["group", "p2p"]>>;
+        rootMessageId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        ownerOpenId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    engine: "workflow-v3";
+    source: {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        authorizedByOpenId?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}, {
+    engine: "workflow-v3";
+    source: {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        authorizedByOpenId?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    source: z.ZodObject<{
+        kind: z.ZodLiteral<"saved_definition">;
+        workflowId: z.ZodString;
+        revisionId: z.ZodString;
+        humanVersion: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    }, {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    }>;
+    artifacts: z.ZodObject<{
+        dag: z.ZodObject<{
+            path: z.ZodLiteral<"dag.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        }, {
+            sha256: string;
+            path: "dag.json";
+        }>;
+        spec: z.ZodObject<{
+            path: z.ZodLiteral<"spec.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        }, {
+            sha256: string;
+            path: "spec.json";
+        }>;
+        botSnapshots: z.ZodObject<{
+            path: z.ZodLiteral<"bots.snapshot.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        }, {
+            sha256: string;
+            path: "bots.snapshot.json";
+        }>;
+        resolvedParams: z.ZodObject<{
+            path: z.ZodLiteral<"params.resolved.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "params.resolved.json";
+        }, {
+            sha256: string;
+            path: "params.resolved.json";
+        }>;
+        definitionSnapshot: z.ZodObject<{
+            path: z.ZodLiteral<"definition.snapshot.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "definition.snapshot.json";
+        }, {
+            sha256: string;
+            path: "definition.snapshot.json";
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: `sha256:${string}`;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: `sha256:${string}`;
+            path: "definition.snapshot.json";
+        };
+    }, {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: string;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: string;
+            path: "definition.snapshot.json";
+        };
+    }>;
+    authorization: z.ZodObject<{
+        kind: z.ZodLiteral<"published_revision">;
+        authorizedAt: z.ZodString;
+        workflowId: z.ZodString;
+        revisionId: z.ZodString;
+        definitionSnapshotSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        dagSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        specSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: `sha256:${string}`;
+    }, {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: string;
+    }>;
+    schemaVersion: z.ZodLiteral<1>;
+    engine: z.ZodLiteral<"workflow-v3">;
+    runId: z.ZodString;
+    createdAt: z.ZodString;
+    chatBinding: z.ZodOptional<z.ZodObject<{
+        larkAppId: z.ZodString;
+        chatId: z.ZodString;
+        chatType: z.ZodOptional<z.ZodEnum<["group", "p2p"]>>;
+        rootMessageId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        ownerOpenId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    engine: "workflow-v3";
+    source: {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: `sha256:${string}`;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: `sha256:${string}`;
+            path: "definition.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: `sha256:${string}`;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}, {
+    engine: "workflow-v3";
+    source: {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: string;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: string;
+            path: "definition.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: string;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    source: z.ZodObject<{
+        kind: z.ZodLiteral<"manual_cli">;
+    }, "strict", z.ZodTypeAny, {
+        kind: "manual_cli";
+    }, {
+        kind: "manual_cli";
+    }>;
+    artifacts: z.ZodObject<{
+        dag: z.ZodObject<{
+            path: z.ZodLiteral<"dag.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        }, {
+            sha256: string;
+            path: "dag.json";
+        }>;
+        botSnapshots: z.ZodObject<{
+            path: z.ZodLiteral<"bots.snapshot.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        }, {
+            sha256: string;
+            path: "bots.snapshot.json";
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    }, {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    }>;
+    authorization: z.ZodObject<{
+        kind: z.ZodLiteral<"local_cli">;
+        authorizedAt: z.ZodString;
+        dagSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+    }, {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: string;
+    }>;
+    schemaVersion: z.ZodLiteral<1>;
+    engine: z.ZodLiteral<"workflow-v3">;
+    runId: z.ZodString;
+    createdAt: z.ZodString;
+    chatBinding: z.ZodOptional<z.ZodObject<{
+        larkAppId: z.ZodString;
+        chatId: z.ZodString;
+        chatType: z.ZodOptional<z.ZodEnum<["group", "p2p"]>>;
+        rootMessageId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        ownerOpenId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    engine: "workflow-v3";
+    source: {
+        kind: "manual_cli";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}, {
+    engine: "workflow-v3";
+    source: {
+        kind: "manual_cli";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: string;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}>, z.ZodObject<{
+    source: z.ZodObject<{
+        kind: z.ZodLiteral<"legacy_v3">;
+        original: z.ZodEnum<["grill", "manual_cli"]>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    }, {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    }>;
+    artifacts: z.ZodObject<{
+        dag: z.ZodObject<{
+            path: z.ZodLiteral<"dag.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        }, {
+            sha256: string;
+            path: "dag.json";
+        }>;
+        spec: z.ZodOptional<z.ZodObject<{
+            path: z.ZodLiteral<"spec.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        }, {
+            sha256: string;
+            path: "spec.json";
+        }>>;
+        botSnapshots: z.ZodOptional<z.ZodObject<{
+            path: z.ZodLiteral<"bots.snapshot.json">;
+            sha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        }, "strict", z.ZodTypeAny, {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        }, {
+            sha256: string;
+            path: "bots.snapshot.json";
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        } | undefined;
+    }, {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: string;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        } | undefined;
+    }>;
+    authorization: z.ZodObject<{
+        kind: z.ZodLiteral<"legacy_backfill">;
+        backfilledAt: z.ZodString;
+        basis: z.ZodEnum<["grill_dag_approved", "runtime_started"]>;
+        integrity: z.ZodLiteral<"unverifiable_before_backfill">;
+        dagSha256: z.ZodEffects<z.ZodString, `sha256:${string}`, string>;
+        specSha256: z.ZodOptional<z.ZodEffects<z.ZodString, `sha256:${string}`, string>>;
+    }, "strict", z.ZodTypeAny, {
+        kind: "legacy_backfill";
+        dagSha256: `sha256:${string}`;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: `sha256:${string}` | undefined;
+    }, {
+        kind: "legacy_backfill";
+        dagSha256: string;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: string | undefined;
+    }>;
+    schemaVersion: z.ZodLiteral<1>;
+    engine: z.ZodLiteral<"workflow-v3">;
+    runId: z.ZodString;
+    createdAt: z.ZodString;
+    chatBinding: z.ZodOptional<z.ZodObject<{
+        larkAppId: z.ZodString;
+        chatId: z.ZodString;
+        chatType: z.ZodOptional<z.ZodEnum<["group", "p2p"]>>;
+        rootMessageId: z.ZodOptional<z.ZodString>;
+        sessionId: z.ZodOptional<z.ZodString>;
+        ownerOpenId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }, {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    engine: "workflow-v3";
+    source: {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        } | undefined;
+    };
+    authorization: {
+        kind: "legacy_backfill";
+        dagSha256: `sha256:${string}`;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: `sha256:${string}` | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}, {
+    engine: "workflow-v3";
+    source: {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: string;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        } | undefined;
+    };
+    authorization: {
+        kind: "legacy_backfill";
+        dagSha256: string;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}>]>, {
+    engine: "workflow-v3";
+    source: {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        authorizedByOpenId?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: `sha256:${string}`;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: `sha256:${string}`;
+            path: "definition.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+        specSha256: `sha256:${string}`;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: `sha256:${string}`;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "manual_cli";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: `sha256:${string}`;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: `sha256:${string}`;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: `sha256:${string}`;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: `sha256:${string}`;
+            path: "bots.snapshot.json";
+        } | undefined;
+    };
+    authorization: {
+        kind: "legacy_backfill";
+        dagSha256: `sha256:${string}`;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: `sha256:${string}` | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}, {
+    engine: "workflow-v3";
+    source: {
+        kind: "ad_hoc";
+        grillStatePath: "grill.state.json";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "gate2";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        authorizedByOpenId?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "saved_definition";
+        workflowId: string;
+        revisionId: string;
+        humanVersion: number;
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        spec: {
+            sha256: string;
+            path: "spec.json";
+        };
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+        resolvedParams: {
+            sha256: string;
+            path: "params.resolved.json";
+        };
+        definitionSnapshot: {
+            sha256: string;
+            path: "definition.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "published_revision";
+        authorizedAt: string;
+        dagSha256: string;
+        specSha256: string;
+        workflowId: string;
+        revisionId: string;
+        definitionSnapshotSha256: string;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "manual_cli";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        botSnapshots: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        };
+    };
+    authorization: {
+        kind: "local_cli";
+        authorizedAt: string;
+        dagSha256: string;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+} | {
+    engine: "workflow-v3";
+    source: {
+        kind: "legacy_v3";
+        original: "manual_cli" | "grill";
+    };
+    runId: string;
+    schemaVersion: 1;
+    createdAt: string;
+    artifacts: {
+        dag: {
+            sha256: string;
+            path: "dag.json";
+        };
+        spec?: {
+            sha256: string;
+            path: "spec.json";
+        } | undefined;
+        botSnapshots?: {
+            sha256: string;
+            path: "bots.snapshot.json";
+        } | undefined;
+    };
+    authorization: {
+        kind: "legacy_backfill";
+        dagSha256: string;
+        backfilledAt: string;
+        basis: "grill_dag_approved" | "runtime_started";
+        integrity: "unverifiable_before_backfill";
+        specSha256?: string | undefined;
+    };
+    chatBinding?: {
+        larkAppId: string;
+        chatId: string;
+        sessionId?: string | undefined;
+        chatType?: "group" | "p2p" | undefined;
+        ownerOpenId?: string | undefined;
+        rootMessageId?: string | undefined;
+    } | undefined;
+}>;
+export type V3RunEnvelope = z.infer<typeof V3RunEnvelopeSchema>;
+export type V3AdHocRunEnvelope = Extract<V3RunEnvelope, {
+    source: {
+        kind: 'ad_hoc';
+    };
+}>;
+export type V3SavedDefinitionRunEnvelope = Extract<V3RunEnvelope, {
+    source: {
+        kind: 'saved_definition';
+    };
+}>;
+export type V3ManualCliRunEnvelope = Extract<V3RunEnvelope, {
+    source: {
+        kind: 'manual_cli';
+    };
+}>;
+export type V3LegacyRunEnvelope = Extract<V3RunEnvelope, {
+    source: {
+        kind: 'legacy_v3';
+    };
+}>;
+export type V3RunSourceKind = V3RunEnvelope['source']['kind'];
+export declare class RunEnvelopeValidationError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export declare class RunEnvelopeConflictError extends Error {
+    constructor(message: string);
+}
+export declare class RunEnvelopeIntegrityError extends Error {
+    readonly code: 'envelope_missing' | 'envelope_invalid' | 'source_not_allowed' | 'artifact_missing' | 'artifact_not_regular_file' | 'artifact_digest_mismatch' | 'artifact_invalid_json' | 'artifact_invalid_content' | 'run_id_mismatch';
+    readonly artifact?: V3RunArtifactPath | undefined;
+    constructor(code: 'envelope_missing' | 'envelope_invalid' | 'source_not_allowed' | 'artifact_missing' | 'artifact_not_regular_file' | 'artifact_digest_mismatch' | 'artifact_invalid_json' | 'artifact_invalid_content' | 'run_id_mismatch', message: string, artifact?: V3RunArtifactPath | undefined);
+}
+export declare function validateRunEnvelope(raw: unknown, expectedRunId?: string): V3RunEnvelope;
+export type ReadRunEnvelopeResult = {
+    kind: 'missing';
+    path: string;
+} | {
+    kind: 'invalid';
+    path: string;
+    problems: string[];
+} | {
+    kind: 'ok';
+    path: string;
+    envelope: V3RunEnvelope;
+    bytes: Buffer;
+};
+/**
+ * Defensive reader that preserves the crucial missing-vs-corrupt distinction.
+ * Compatibility callers may fall back to grill state only for `missing`; an
+ * existing invalid envelope must fail closed.
+ *
+ * Only an ENOENT from the initial lstat is `missing`. An existing path that
+ * is a symlink, FIFO, directory, device, or otherwise non-regular file is
+ * always `invalid` — even when a dangling symlink would make existsSync/stat
+ * follow-and-miss. The type check runs on lstat BEFORE any open: a plain
+ * open(2) on a writerless FIFO blocks forever, and this reader sits on
+ * daemon-side integrity paths. The open then uses O_NOFOLLOW + O_NONBLOCK and
+ * re-confirms via fstat dev+ino so a lstat→open TOCTOU swap can neither block
+ * nor substitute another file. Once lstat has observed the path, every later
+ * error — including ENOENT from a removal race — is `invalid`: the path
+ * changed mid-read, and missing-only legacy fallbacks must not engage.
+ */
+export declare function readRunEnvelope(runDir: string, expectedRunId?: string): ReadRunEnvelopeResult;
+/** SHA-256 of exact bytes (no JSON parse/re-serialization). */
+export declare function sha256Bytes(bytes: string | Buffer): Sha256Digest;
+/** Build an exact-byte artifact ref for an already-materialized run file. */
+export declare function artifactRef<Path extends V3RunArtifactPath>(runDir: string, path: Path): V3ArtifactRef<Path>;
+export interface LoadedAuthorizedV3Run {
+    envelope: V3RunEnvelope;
+    /** Validated from the exact bytes whose digest was checked. */
+    dag: V3Dag;
+    spec?: Spec;
+    /** Shape validation belongs to the bot-snapshot materializer; kept as exact JSON here. */
+    botSnapshots?: unknown;
+    resolvedParams?: unknown;
+    definitionSnapshot?: unknown;
+    /** Exact verified bytes, for a caller that must avoid a second filesystem read. */
+    bytes: {
+        runEnvelope: Buffer;
+        dag: Buffer;
+        spec?: Buffer;
+        botSnapshots?: Buffer;
+        resolvedParams?: Buffer;
+        definitionSnapshot?: Buffer;
+    };
+}
+export interface LoadAuthorizedV3RunOptions {
+    expectedRunId?: string;
+    allowedSources?: readonly V3RunSourceKind[];
+}
+/** Strictly read, authorize, hash-check, and parse a materialized v3 run. */
+export declare function loadAuthorizedV3Run(runDir: string, options?: LoadAuthorizedV3RunOptions): LoadedAuthorizedV3Run;
+export declare function serializeRunEnvelope(envelope: V3RunEnvelope): string;
+export interface PublishRunEnvelopeResult {
+    created: boolean;
+    path: string;
+    envelope: V3RunEnvelope;
+}
+/**
+ * Atomically publish run.json without ever replacing an existing envelope.
+ * A hard-link publishes a fully-written same-filesystem temp inode with
+ * create-only semantics; an exact semantic repeat is accepted idempotently.
+ *
+ * run.json is also the commit marker for every digest-pinned artifact. Before
+ * exposing it we fsync each referenced regular file and the run directory, so
+ * a crash cannot retain the authorization while losing its DAG/spec/snapshot.
+ */
+export declare function publishRunEnvelopeOnce(runDir: string, raw: V3RunEnvelope): PublishRunEnvelopeResult;
+interface CommonBuilderInput {
+    runId: string;
+    createdAt: string;
+    chatBinding?: RunChatBinding;
+}
+export declare function makeAdHocRunEnvelope(input: CommonBuilderInput & {
+    authorizedAt: string;
+    authorizedByOpenId?: string;
+    artifacts: V3AdHocRunEnvelope['artifacts'];
+}): V3AdHocRunEnvelope;
+export declare function makeSavedDefinitionRunEnvelope(input: CommonBuilderInput & {
+    workflowId: string;
+    revisionId: string;
+    humanVersion: number;
+    authorizedAt: string;
+    artifacts: V3SavedDefinitionRunEnvelope['artifacts'];
+}): V3SavedDefinitionRunEnvelope;
+export declare function makeManualCliRunEnvelope(input: CommonBuilderInput & {
+    authorizedAt: string;
+    artifacts: V3ManualCliRunEnvelope['artifacts'];
+}): V3ManualCliRunEnvelope;
+export declare function makeLegacyV3RunEnvelope(input: CommonBuilderInput & {
+    original: 'grill' | 'manual_cli';
+    basis: 'grill_dag_approved' | 'runtime_started';
+    backfilledAt: string;
+    artifacts: V3LegacyRunEnvelope['artifacts'];
+}): V3LegacyRunEnvelope;
+export {};
+//# sourceMappingURL=run-envelope.d.ts.map