botmux 2.111.0 → 2.112.0

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

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

package/dist/workflows/v3/run-envelope.js

@@ -0,0 +1,681 @@
+/**
+ * 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 { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, join } from 'node:path';
+import { z } from 'zod';
+import { fsyncDirectorySyncPortable, fsyncFilesAndDirectorySync, } from '../../utils/fs-durability.js';
+import { validateDag } from './dag.js';
+import { validateSpec } from './spec.js';
+export const V3_RUN_ENVELOPE_FILE = 'run.json';
+export const V3_RUN_ENVELOPE_SCHEMA_VERSION = 1;
+export const V3_RUN_ENGINE = 'workflow-v3';
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/;
+const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const sha256Schema = z.string()
+    .regex(SHA256_RE, 'must be sha256:<64 lowercase hex>')
+    .transform((value) => value);
+const runIdSchema = z.string().regex(RUN_ID_RE, 'must be a path-safe v3 run id');
+const timestampSchema = z.string().datetime({ offset: true });
+const nonEmptyString = z.string().min(1);
+const chatBindingSchema = z.object({
+    larkAppId: nonEmptyString,
+    chatId: nonEmptyString,
+    chatType: z.enum(['group', 'p2p']).optional(),
+    rootMessageId: nonEmptyString.optional(),
+    sessionId: nonEmptyString.optional(),
+    ownerOpenId: nonEmptyString.optional(),
+}).strict();
+function artifactRefSchema(path) {
+    return z.object({
+        path: z.literal(path),
+        sha256: sha256Schema,
+    }).strict();
+}
+const baseShape = {
+    schemaVersion: z.literal(V3_RUN_ENVELOPE_SCHEMA_VERSION),
+    engine: z.literal(V3_RUN_ENGINE),
+    runId: runIdSchema,
+    createdAt: timestampSchema,
+    chatBinding: chatBindingSchema.optional(),
+};
+const adHocEnvelopeSchema = z.object({
+    ...baseShape,
+    source: z.object({
+        kind: z.literal('ad_hoc'),
+        grillStatePath: z.literal('grill.state.json'),
+    }).strict(),
+    artifacts: z.object({
+        dag: artifactRefSchema('dag.json'),
+        spec: artifactRefSchema('spec.json'),
+        botSnapshots: artifactRefSchema('bots.snapshot.json'),
+    }).strict(),
+    authorization: z.object({
+        kind: z.literal('gate2'),
+        authorizedAt: timestampSchema,
+        authorizedByOpenId: nonEmptyString.optional(),
+        dagSha256: sha256Schema,
+        specSha256: sha256Schema,
+    }).strict(),
+}).strict();
+const savedDefinitionEnvelopeSchema = z.object({
+    ...baseShape,
+    source: z.object({
+        kind: z.literal('saved_definition'),
+        workflowId: runIdSchema,
+        revisionId: nonEmptyString,
+        humanVersion: z.number().int().positive(),
+    }).strict(),
+    artifacts: z.object({
+        dag: artifactRefSchema('dag.json'),
+        spec: artifactRefSchema('spec.json'),
+        botSnapshots: artifactRefSchema('bots.snapshot.json'),
+        resolvedParams: artifactRefSchema('params.resolved.json'),
+        definitionSnapshot: artifactRefSchema('definition.snapshot.json'),
+    }).strict(),
+    authorization: z.object({
+        kind: z.literal('published_revision'),
+        authorizedAt: timestampSchema,
+        workflowId: runIdSchema,
+        revisionId: nonEmptyString,
+        definitionSnapshotSha256: sha256Schema,
+        dagSha256: sha256Schema,
+        specSha256: sha256Schema,
+    }).strict(),
+}).strict();
+const manualCliEnvelopeSchema = z.object({
+    ...baseShape,
+    source: z.object({ kind: z.literal('manual_cli') }).strict(),
+    artifacts: z.object({
+        dag: artifactRefSchema('dag.json'),
+        botSnapshots: artifactRefSchema('bots.snapshot.json'),
+    }).strict(),
+    authorization: z.object({
+        kind: z.literal('local_cli'),
+        authorizedAt: timestampSchema,
+        dagSha256: sha256Schema,
+    }).strict(),
+}).strict();
+const legacyV3EnvelopeSchema = z.object({
+    ...baseShape,
+    source: z.object({
+        kind: z.literal('legacy_v3'),
+        original: z.enum(['grill', 'manual_cli']),
+    }).strict(),
+    artifacts: z.object({
+        dag: artifactRefSchema('dag.json'),
+        spec: artifactRefSchema('spec.json').optional(),
+        botSnapshots: artifactRefSchema('bots.snapshot.json').optional(),
+    }).strict(),
+    authorization: z.object({
+        kind: z.literal('legacy_backfill'),
+        backfilledAt: timestampSchema,
+        basis: z.enum(['grill_dag_approved', 'runtime_started']),
+        integrity: z.literal('unverifiable_before_backfill'),
+        dagSha256: sha256Schema,
+        specSha256: sha256Schema.optional(),
+    }).strict(),
+}).strict();
+/** Strict v1 schema. Unknown keys are rejected at every envelope-owned level. */
+export const V3RunEnvelopeSchema = z.union([
+    adHocEnvelopeSchema,
+    savedDefinitionEnvelopeSchema,
+    manualCliEnvelopeSchema,
+    legacyV3EnvelopeSchema,
+]).superRefine((envelope, ctx) => {
+    if (envelope.authorization.dagSha256 !== envelope.artifacts.dag.sha256) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['authorization', 'dagSha256'],
+            message: 'must match artifacts.dag.sha256',
+        });
+    }
+    if (envelope.authorization.kind === 'gate2') {
+        const artifacts = envelope.artifacts;
+        if (envelope.authorization.specSha256 !== artifacts.spec.sha256) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'specSha256'],
+                message: 'must match artifacts.spec.sha256',
+            });
+        }
+    }
+    else if (envelope.authorization.kind === 'published_revision') {
+        const source = envelope.source;
+        const artifacts = envelope.artifacts;
+        if (envelope.authorization.workflowId !== source.workflowId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'workflowId'],
+                message: 'must match source.workflowId',
+            });
+        }
+        if (envelope.authorization.revisionId !== source.revisionId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'revisionId'],
+                message: 'must match source.revisionId',
+            });
+        }
+        if (envelope.authorization.definitionSnapshotSha256 !== artifacts.definitionSnapshot.sha256) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'definitionSnapshotSha256'],
+                message: 'must match artifacts.definitionSnapshot.sha256',
+            });
+        }
+        if (envelope.authorization.specSha256 !== artifacts.spec.sha256) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'specSha256'],
+                message: 'must match artifacts.spec.sha256',
+            });
+        }
+    }
+    else if (envelope.authorization.kind === 'legacy_backfill') {
+        const artifacts = envelope.artifacts;
+        if (artifacts.spec) {
+            if (envelope.authorization.specSha256 !== artifacts.spec.sha256) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['authorization', 'specSha256'],
+                    message: 'must match artifacts.spec.sha256 when a legacy spec is present',
+                });
+            }
+        }
+        else if (envelope.authorization.specSha256 !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['authorization', 'specSha256'],
+                message: 'must be absent when artifacts.spec is absent',
+            });
+        }
+    }
+});
+export class RunEnvelopeValidationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Invalid v3 run envelope:\n  - ${problems.join('\n  - ')}`);
+        this.problems = problems;
+        this.name = 'RunEnvelopeValidationError';
+    }
+}
+export class RunEnvelopeConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RunEnvelopeConflictError';
+    }
+}
+export class RunEnvelopeIntegrityError extends Error {
+    code;
+    artifact;
+    constructor(code, message, artifact) {
+        super(message);
+        this.code = code;
+        this.artifact = artifact;
+        this.name = 'RunEnvelopeIntegrityError';
+    }
+}
+function zodProblems(error) {
+    return error.issues.map((issue) => {
+        const where = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
+        return `${where}${issue.message}`;
+    });
+}
+export function validateRunEnvelope(raw, expectedRunId) {
+    const parsed = V3RunEnvelopeSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new RunEnvelopeValidationError(zodProblems(parsed.error));
+    if (expectedRunId !== undefined && parsed.data.runId !== expectedRunId) {
+        throw new RunEnvelopeValidationError([
+            `runId must match run directory "${expectedRunId}" (got "${parsed.data.runId}")`,
+        ]);
+    }
+    return parsed.data;
+}
+/**
+ * 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 function readRunEnvelope(runDir, expectedRunId = basename(runDir)) {
+    const path = join(runDir, V3_RUN_ENVELOPE_FILE);
+    // Boundary 1: the initial lstat is the only place a true "file was never
+    // there" can be told apart from "path mutated while we were reading".
+    // It also must run before any open — open(O_RDONLY) on a FIFO with no
+    // writer blocks indefinitely regardless of O_NOFOLLOW.
+    let linkStat;
+    try {
+        linkStat = lstatSync(path);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { kind: 'missing', path };
+        return {
+            kind: 'invalid',
+            path,
+            problems: [`cannot read run.json: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    if (!linkStat.isFile()) {
+        return {
+            kind: 'invalid',
+            path,
+            problems: ['run.json must be a regular file'],
+        };
+    }
+    // Boundary 2: lstat saw a regular file, so from here every failure —
+    // ENOENT included — means the path changed underneath us and must fail
+    // closed as invalid, never as missing.
+    let fd;
+    let bytes;
+    try {
+        // O_NONBLOCK makes an open on a race-swapped FIFO return immediately
+        // instead of blocking (it is a no-op for regular files); O_NOFOLLOW
+        // rejects a swap to a symlink.
+        fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const st = fstatSync(fd);
+        // Re-confirm on the open fd and pin the inode identity: anything that is
+        // not the exact regular file lstat approved fails closed.
+        if (!st.isFile() || st.dev !== linkStat.dev || st.ino !== linkStat.ino) {
+            return {
+                kind: 'invalid',
+                path,
+                problems: ['run.json must be a regular file'],
+            };
+        }
+        bytes = readFileSync(fd);
+    }
+    catch (err) {
+        const code = err.code;
+        // ELOOP (Linux O_NOFOLLOW on symlink), EPERM (some NOFOLLOW platforms),
+        // EISDIR, and a raced ENOENT all mean "the observed path stopped being a
+        // stable regular file".
+        if (code === 'ELOOP' || code === 'EPERM' || code === 'EISDIR' || code === 'ENOTDIR' || code === 'ENOENT') {
+            return {
+                kind: 'invalid',
+                path,
+                problems: [`run.json must be a stable regular file (${code})`],
+            };
+        }
+        return {
+            kind: 'invalid',
+            path,
+            problems: [`cannot read run.json: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString('utf-8'));
+    }
+    catch (err) {
+        return {
+            kind: 'invalid',
+            path,
+            problems: [`cannot read/parse run.json: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    try {
+        return { kind: 'ok', path, envelope: validateRunEnvelope(raw, expectedRunId), bytes };
+    }
+    catch (err) {
+        return {
+            kind: 'invalid',
+            path,
+            problems: err instanceof RunEnvelopeValidationError ? err.problems : [String(err)],
+        };
+    }
+}
+/** SHA-256 of exact bytes (no JSON parse/re-serialization). */
+export function sha256Bytes(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function artifactPath(runDir, path) {
+    return join(runDir, path);
+}
+function readRegularArtifact(runDir, path) {
+    const absolutePath = artifactPath(runDir, path);
+    let stat;
+    try {
+        stat = lstatSync(absolutePath);
+    }
+    catch (err) {
+        throw new RunEnvelopeIntegrityError('artifact_missing', `v3 run artifact ${path} is missing: ${err instanceof Error ? err.message : String(err)}`, path);
+    }
+    // Reject symlinks as well as directories/devices. A fixed basename plus a
+    // symlink to outside runDir would otherwise bypass the path allowlist.
+    if (!stat.isFile()) {
+        throw new RunEnvelopeIntegrityError('artifact_not_regular_file', `v3 run artifact ${path} must be a regular file`, path);
+    }
+    // Same TOCTOU discipline as readRunEnvelope: O_NONBLOCK so a race-swapped
+    // FIFO cannot block the open, O_NOFOLLOW against symlink swaps, then fstat
+    // dev+ino must match the inode lstat approved.
+    let fd;
+    try {
+        fd = openSync(absolutePath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        const st = fstatSync(fd);
+        if (!st.isFile() || st.dev !== stat.dev || st.ino !== stat.ino) {
+            throw new RunEnvelopeIntegrityError('artifact_not_regular_file', `v3 run artifact ${path} must be a regular file`, path);
+        }
+        return readFileSync(fd);
+    }
+    catch (err) {
+        if (err instanceof RunEnvelopeIntegrityError)
+            throw err;
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new RunEnvelopeIntegrityError('artifact_missing', `v3 run artifact ${path} is missing: ${err instanceof Error ? err.message : String(err)}`, path);
+        }
+        throw new RunEnvelopeIntegrityError('artifact_not_regular_file', `v3 run artifact ${path} must be a regular file (${code ?? String(err)})`, path);
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+/** Build an exact-byte artifact ref for an already-materialized run file. */
+export function artifactRef(runDir, path) {
+    return { path, sha256: sha256Bytes(readRegularArtifact(runDir, path)) };
+}
+function parseJsonArtifact(bytes, path) {
+    try {
+        return JSON.parse(bytes.toString('utf-8'));
+    }
+    catch (err) {
+        throw new RunEnvelopeIntegrityError('artifact_invalid_json', `v3 run artifact ${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, path);
+    }
+}
+function verifyArtifact(runDir, ref) {
+    const bytes = readRegularArtifact(runDir, ref.path);
+    const actual = sha256Bytes(bytes);
+    if (actual !== ref.sha256) {
+        throw new RunEnvelopeIntegrityError('artifact_digest_mismatch', `v3 run artifact ${ref.path} digest mismatch: expected ${ref.sha256}, got ${actual}`, ref.path);
+    }
+    return bytes;
+}
+/** Strictly read, authorize, hash-check, and parse a materialized v3 run. */
+export function loadAuthorizedV3Run(runDir, options = {}) {
+    const expectedRunId = options.expectedRunId ?? basename(runDir);
+    const read = readRunEnvelope(runDir, expectedRunId);
+    if (read.kind === 'missing') {
+        throw new RunEnvelopeIntegrityError('envelope_missing', `v3 run envelope is missing at ${read.path}`);
+    }
+    if (read.kind === 'invalid') {
+        throw new RunEnvelopeIntegrityError('envelope_invalid', `v3 run envelope is invalid: ${read.problems.join('; ')}`);
+    }
+    const envelope = read.envelope;
+    if (options.allowedSources && !options.allowedSources.includes(envelope.source.kind)) {
+        throw new RunEnvelopeIntegrityError('source_not_allowed', `v3 run source "${envelope.source.kind}" is not allowed here`);
+    }
+    const dagBytes = verifyArtifact(runDir, envelope.artifacts.dag);
+    let dag;
+    try {
+        dag = validateDag(parseJsonArtifact(dagBytes, 'dag.json'));
+    }
+    catch (err) {
+        if (err instanceof RunEnvelopeIntegrityError)
+            throw err;
+        throw new RunEnvelopeIntegrityError('artifact_invalid_content', `v3 run artifact dag.json failed validation: ${err instanceof Error ? err.message : String(err)}`, 'dag.json');
+    }
+    if (dag.runId !== envelope.runId) {
+        throw new RunEnvelopeIntegrityError('run_id_mismatch', `dag.runId "${dag.runId}" does not match envelope.runId "${envelope.runId}"`, 'dag.json');
+    }
+    const bytes = {
+        runEnvelope: read.bytes,
+        dag: dagBytes,
+    };
+    let spec;
+    let botSnapshots;
+    let resolvedParams;
+    let definitionSnapshot;
+    if ('spec' in envelope.artifacts && envelope.artifacts.spec) {
+        const specBytes = verifyArtifact(runDir, envelope.artifacts.spec);
+        bytes.spec = specBytes;
+        try {
+            spec = validateSpec(parseJsonArtifact(specBytes, 'spec.json'));
+        }
+        catch (err) {
+            if (err instanceof RunEnvelopeIntegrityError)
+                throw err;
+            throw new RunEnvelopeIntegrityError('artifact_invalid_content', `v3 run artifact spec.json failed validation: ${err instanceof Error ? err.message : String(err)}`, 'spec.json');
+        }
+        if (spec.runId !== envelope.runId) {
+            throw new RunEnvelopeIntegrityError('run_id_mismatch', `spec.runId "${spec.runId}" does not match envelope.runId "${envelope.runId}"`, 'spec.json');
+        }
+    }
+    if ('botSnapshots' in envelope.artifacts && envelope.artifacts.botSnapshots) {
+        const botBytes = verifyArtifact(runDir, envelope.artifacts.botSnapshots);
+        bytes.botSnapshots = botBytes;
+        botSnapshots = parseJsonArtifact(botBytes, 'bots.snapshot.json');
+    }
+    if ('resolvedParams' in envelope.artifacts) {
+        const paramBytes = verifyArtifact(runDir, envelope.artifacts.resolvedParams);
+        bytes.resolvedParams = paramBytes;
+        resolvedParams = parseJsonArtifact(paramBytes, 'params.resolved.json');
+    }
+    if ('definitionSnapshot' in envelope.artifacts) {
+        const definitionBytes = verifyArtifact(runDir, envelope.artifacts.definitionSnapshot);
+        bytes.definitionSnapshot = definitionBytes;
+        definitionSnapshot = parseJsonArtifact(definitionBytes, 'definition.snapshot.json');
+    }
+    if (envelope.source.kind === 'saved_definition') {
+        if (!definitionSnapshot || typeof definitionSnapshot !== 'object' || Array.isArray(definitionSnapshot)) {
+            throw new RunEnvelopeIntegrityError('artifact_invalid_content', 'definition.snapshot.json must be an object for a saved-definition run', 'definition.snapshot.json');
+        }
+        const snapshot = definitionSnapshot;
+        if (snapshot.workflowId !== envelope.source.workflowId ||
+            snapshot.revisionId !== envelope.source.revisionId ||
+            snapshot.humanVersion !== envelope.source.humanVersion) {
+            throw new RunEnvelopeIntegrityError('artifact_invalid_content', 'definition.snapshot.json identity does not match run.json source revision', 'definition.snapshot.json');
+        }
+    }
+    return { envelope, dag, spec, botSnapshots, resolvedParams, definitionSnapshot, bytes };
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).filter((k) => source[k] !== undefined).sort()) {
+        out[key] = canonicalize(source[key]);
+    }
+    return out;
+}
+export function serializeRunEnvelope(envelope) {
+    return `${JSON.stringify(canonicalize(envelope))}\n`;
+}
+function fsyncEnvelopeArtifacts(runDir, envelope) {
+    const refs = Object.values(envelope.artifacts);
+    fsyncFilesAndDirectorySync(runDir, refs.filter((ref) => ref !== undefined)
+        .map((ref) => join(runDir, ref.path)));
+}
+/**
+ * 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 function publishRunEnvelopeOnce(runDir, raw) {
+    const expectedRunId = basename(runDir);
+    const envelope = validateRunEnvelope(raw, expectedRunId);
+    mkdirSync(runDir, { recursive: true });
+    const path = join(runDir, V3_RUN_ENVELOPE_FILE);
+    const existingBefore = readRunEnvelope(runDir, expectedRunId);
+    if (existingBefore.kind === 'ok') {
+        if (serializeRunEnvelope(existingBefore.envelope) === serializeRunEnvelope(envelope)) {
+            // Besides validating an idempotent retry, this heals a process that
+            // crashed after link(2) but before syncing the directory entry, and
+            // upgrades envelopes published before artifact fsync was introduced.
+            fsyncEnvelopeArtifacts(runDir, existingBefore.envelope);
+            return { created: false, path, envelope: existingBefore.envelope };
+        }
+        throw new RunEnvelopeConflictError(`run.json already exists with different content at ${path}`);
+    }
+    if (existingBefore.kind === 'invalid') {
+        throw new RunEnvelopeConflictError(`run.json already exists but is invalid at ${path}: ${existingBefore.problems.join('; ')}`);
+    }
+    // The authorization marker must never become durable before the exact bytes
+    // it authorizes. atomicWrite's rename gives atomic visibility, while these
+    // fsyncs provide the separate crash-durability guarantee.
+    fsyncEnvelopeArtifacts(runDir, envelope);
+    const tmp = `${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    let fd;
+    try {
+        fd = openSync(tmp, 'wx', 0o600);
+        writeFileSync(fd, serializeRunEnvelope(envelope), 'utf-8');
+        fchmodSync(fd, 0o600);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        try {
+            linkSync(tmp, path);
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const raced = readRunEnvelope(runDir, expectedRunId);
+            if (raced.kind === 'ok' && serializeRunEnvelope(raced.envelope) === serializeRunEnvelope(envelope)) {
+                fsyncDirectorySyncPortable(runDir);
+                return { created: false, path, envelope: raced.envelope };
+            }
+            const detail = raced.kind === 'invalid' ? `: ${raced.problems.join('; ')}` : '';
+            throw new RunEnvelopeConflictError(`run.json was concurrently published with different content at ${path}${detail}`);
+        }
+        // Persist the newly-created directory entry as well as the file inode.
+        // Without this, a crash can lose run.json after Gate-2 has advanced even
+        // though the file itself was fsync'd.
+        fsyncDirectorySyncPortable(runDir);
+        return { created: true, path, envelope };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort */ }
+        }
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* temp may already be absent */ }
+    }
+}
+export function makeAdHocRunEnvelope(input) {
+    return validateRunEnvelope({
+        schemaVersion: V3_RUN_ENVELOPE_SCHEMA_VERSION,
+        engine: V3_RUN_ENGINE,
+        runId: input.runId,
+        createdAt: input.createdAt,
+        ...(input.chatBinding ? { chatBinding: input.chatBinding } : {}),
+        source: { kind: 'ad_hoc', grillStatePath: 'grill.state.json' },
+        artifacts: input.artifacts,
+        authorization: {
+            kind: 'gate2',
+            authorizedAt: input.authorizedAt,
+            ...(input.authorizedByOpenId ? { authorizedByOpenId: input.authorizedByOpenId } : {}),
+            dagSha256: input.artifacts.dag.sha256,
+            specSha256: input.artifacts.spec.sha256,
+        },
+    });
+}
+export function makeSavedDefinitionRunEnvelope(input) {
+    return validateRunEnvelope({
+        schemaVersion: V3_RUN_ENVELOPE_SCHEMA_VERSION,
+        engine: V3_RUN_ENGINE,
+        runId: input.runId,
+        createdAt: input.createdAt,
+        ...(input.chatBinding ? { chatBinding: input.chatBinding } : {}),
+        source: {
+            kind: 'saved_definition',
+            workflowId: input.workflowId,
+            revisionId: input.revisionId,
+            humanVersion: input.humanVersion,
+        },
+        artifacts: input.artifacts,
+        authorization: {
+            kind: 'published_revision',
+            authorizedAt: input.authorizedAt,
+            workflowId: input.workflowId,
+            revisionId: input.revisionId,
+            definitionSnapshotSha256: input.artifacts.definitionSnapshot.sha256,
+            dagSha256: input.artifacts.dag.sha256,
+            specSha256: input.artifacts.spec.sha256,
+        },
+    });
+}
+export function makeManualCliRunEnvelope(input) {
+    return validateRunEnvelope({
+        schemaVersion: V3_RUN_ENVELOPE_SCHEMA_VERSION,
+        engine: V3_RUN_ENGINE,
+        runId: input.runId,
+        createdAt: input.createdAt,
+        ...(input.chatBinding ? { chatBinding: input.chatBinding } : {}),
+        source: { kind: 'manual_cli' },
+        artifacts: input.artifacts,
+        authorization: {
+            kind: 'local_cli',
+            authorizedAt: input.authorizedAt,
+            dagSha256: input.artifacts.dag.sha256,
+        },
+    });
+}
+export function makeLegacyV3RunEnvelope(input) {
+    return validateRunEnvelope({
+        schemaVersion: V3_RUN_ENVELOPE_SCHEMA_VERSION,
+        engine: V3_RUN_ENGINE,
+        runId: input.runId,
+        createdAt: input.createdAt,
+        ...(input.chatBinding ? { chatBinding: input.chatBinding } : {}),
+        source: { kind: 'legacy_v3', original: input.original },
+        artifacts: input.artifacts,
+        authorization: {
+            kind: 'legacy_backfill',
+            backfilledAt: input.backfilledAt,
+            basis: input.basis,
+            integrity: 'unverifiable_before_backfill',
+            dagSha256: input.artifacts.dag.sha256,
+            ...(input.artifacts.spec ? { specSha256: input.artifacts.spec.sha256 } : {}),
+        },
+    });
+}
+//# sourceMappingURL=run-envelope.js.map