ultracode-for-codex 0.2.0

package/dist/runtime/workflow-journal.js

@@ -0,0 +1,681 @@
+import { createHash } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export class WorkflowJournalError extends Error {
+    cause;
+    code = 'workflow_journal_write_failed';
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'WorkflowJournalError';
+    }
+}
+export class WorkflowJournalValidationError extends Error {
+    code = 'workflow_journal_invalid';
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowJournalValidationError';
+    }
+}
+export class WorkflowJournalWriter {
+    options;
+    journalPath;
+    queue = Promise.resolve();
+    poisoned;
+    seq = 0;
+    previousEntryHash = ZERO_HASH;
+    constructor(options) {
+        this.options = options;
+        this.journalPath = join(options.transcriptDir, JOURNAL_FILE_NAME);
+    }
+    static async create(options) {
+        await ensureWorkflowTranscriptDir(options.transcriptDir);
+        const journalPath = join(options.transcriptDir, JOURNAL_FILE_NAME);
+        let handle;
+        try {
+            handle = await open(journalPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, JOURNAL_FILE_MODE);
+            await handle.sync();
+        }
+        catch (err) {
+            throw new WorkflowJournalError(`Workflow journal cannot be initialized at ${journalPath}.`, err);
+        }
+        finally {
+            await handle?.close().catch(() => undefined);
+        }
+        await chmod(journalPath, JOURNAL_FILE_MODE).catch(() => undefined);
+        await durableDirectorySync(options.transcriptDir, options.durability);
+        await durableDirectorySync(dirname(options.transcriptDir), options.durability);
+        return new WorkflowJournalWriter(options);
+    }
+    async append(payload) {
+        const terminalPayload = TERMINAL_KINDS.has(payload.kind);
+        if (this.poisoned && !terminalPayload)
+            throw this.poisoned;
+        let entry;
+        const queue = terminalPayload ? this.queue.catch(() => undefined) : this.queue;
+        const appendWork = queue.then(async () => {
+            if (this.poisoned && !terminalPayload)
+                throw this.poisoned;
+            entry = this.nextEntry(payload);
+            await appendJournalLine(this.journalPath, entry, this.options.durability);
+            this.seq = entry.seq;
+            this.previousEntryHash = entry.entryHash;
+        });
+        this.queue = appendWork.catch((err) => {
+            const journalError = toWorkflowJournalError(err, `Workflow journal append failed at ${this.journalPath}.`);
+            if (!terminalPayload && !this.poisoned)
+                this.poisoned = journalError;
+            throw journalError;
+        });
+        this.queue.catch(() => undefined);
+        try {
+            await appendWork;
+        }
+        catch (err) {
+            const journalError = toWorkflowJournalError(err, `Workflow journal append failed at ${this.journalPath}.`);
+            if (!terminalPayload && !this.poisoned)
+                this.poisoned = journalError;
+            throw terminalPayload ? journalError : this.poisoned ?? journalError;
+        }
+        return entry;
+    }
+    nextEntry(payload) {
+        const base = {
+            version: 1,
+            seq: this.seq + 1,
+            previousEntryHash: this.previousEntryHash,
+            recordedAt: new Date().toISOString(),
+            taskId: this.options.taskId,
+            runId: this.options.runId,
+            ...payload,
+        };
+        const entryHash = workflowJournalHash(base);
+        const entry = { ...base, entryHash };
+        assertValidWorkflowJournalEntry(entry);
+        return entry;
+    }
+}
+const JOURNAL_FILE_NAME = 'journal.jsonl';
+const JOURNAL_FILE_MODE = 0o600;
+const TRANSCRIPT_DIR_MODE = 0o700;
+const ZERO_HASH = '0'.repeat(64);
+const MAX_LINE_BYTES = 1024 * 1024;
+const MAX_STRING_BYTES = 512 * 1024;
+const HASH_RE = /^[0-9a-f]{64}$/;
+const TERMINAL_KINDS = new Set(['workflow.run.completed', 'workflow.run.failed']);
+export const WORKFLOW_JOURNAL_GENESIS_HASH = ZERO_HASH;
+export const WORKFLOW_JOURNAL_GENESIS_AGENT_CALL_KEY = ZERO_HASH;
+export const WORKFLOW_JOURNAL_WRITE_FAILED_REASON = 'workflow_journal_write_failed';
+const ENTRY_KEYS = {
+    'workflow.run.started': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'workflowName',
+        'workflowSource',
+        'workflowSourcePath',
+        'scriptPath',
+        'scriptHash',
+        'args',
+        'runtime',
+    ],
+    'workflow.agent.started': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'agentIndex',
+        'agentId',
+        'agentCallKey',
+        'previousAgentCallKey',
+        'prompt',
+        'semanticOpts',
+    ],
+    'workflow.agent.completed': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'agentIndex',
+        'agentId',
+        'agentCallKey',
+        'result',
+        'usage',
+        'toolCalls',
+    ],
+    'workflow.agent.failed': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'agentIndex',
+        'agentId',
+        'agentCallKey',
+        'reason',
+        'message',
+    ],
+    'workflow.run.completed': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'result',
+        'resultPath',
+        'agentCount',
+        'usage',
+        'toolCalls',
+        'durationMs',
+    ],
+    'workflow.run.failed': [
+        'version',
+        'seq',
+        'previousEntryHash',
+        'entryHash',
+        'recordedAt',
+        'taskId',
+        'runId',
+        'kind',
+        'reason',
+        'message',
+        'recovery',
+        'durationMs',
+    ],
+};
+export function workflowJournalPath(transcriptDir) {
+    return join(transcriptDir, JOURNAL_FILE_NAME);
+}
+export function isWorkflowJournalError(err) {
+    return err instanceof WorkflowJournalError || (Boolean(err) && err.code === WORKFLOW_JOURNAL_WRITE_FAILED_REASON);
+}
+export function normalizeJournalJsonValue(value, label) {
+    return normalizeJsonValue(value, label, new WeakSet());
+}
+export function stableJson(value) {
+    return stableSerialize(normalizeJournalJsonValue(value, 'value'));
+}
+export function computeWorkflowAgentCallKey(input) {
+    if (!HASH_RE.test(input.previousAgentCallKey)) {
+        throw new WorkflowJournalValidationError('previousAgentCallKey must be a 64-character sha256 hex digest.');
+    }
+    return sha256(`${input.previousAgentCallKey}\0${input.prompt}\0${stableJson(input.semanticOpts)}`);
+}
+export function workflowJournalHash(entryWithoutEntryHash) {
+    return sha256(stableJson(entryWithoutEntryHash));
+}
+export async function readWorkflowJournal(journalPath) {
+    const raw = await readFile(journalPath, 'utf8');
+    const endsWithNewline = raw.endsWith('\n');
+    const lines = raw.split('\n');
+    if (endsWithNewline)
+        lines.pop();
+    let truncatedTail = false;
+    if (!endsWithNewline && lines.length > 0) {
+        const tail = lines[lines.length - 1] ?? '';
+        try {
+            JSON.parse(tail);
+            throw new WorkflowJournalValidationError('workflow journal has a non-newline-terminated JSON entry.');
+        }
+        catch (err) {
+            if (err instanceof WorkflowJournalValidationError)
+                throw err;
+            if (!isTruncationParseError(err))
+                throw err;
+            lines.pop();
+            truncatedTail = true;
+        }
+    }
+    const entries = lines.map((line, index) => parseJournalLine(line, index + 1));
+    validateWorkflowJournal(entries);
+    return { entries, truncatedTail };
+}
+export async function cleanupWorkflowJournalTranscriptDir(transcriptDir) {
+    await rm(transcriptDir, { recursive: true, force: true });
+}
+function parseJournalLine(line, lineNumber) {
+    if (Buffer.byteLength(line, 'utf8') > MAX_LINE_BYTES) {
+        throw new WorkflowJournalValidationError(`journal line ${lineNumber} exceeds ${MAX_LINE_BYTES} bytes.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (err) {
+        throw new WorkflowJournalValidationError(`journal line ${lineNumber} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const entry = value;
+    assertValidWorkflowJournalEntry(entry);
+    return entry;
+}
+function validateWorkflowJournal(entries) {
+    if (entries.length === 0)
+        throw new WorkflowJournalValidationError('workflow journal is empty.');
+    if (entries[0]?.kind !== 'workflow.run.started') {
+        throw new WorkflowJournalValidationError('workflow journal must start with workflow.run.started.');
+    }
+    const started = entries[0];
+    let previousEntryHash = ZERO_HASH;
+    let expectedAgentPreviousKey = ZERO_HASH;
+    let terminalSeen = false;
+    const startedAgents = new Map();
+    const startedAgentIndexes = new Set();
+    const finalizedAgents = new Set();
+    const agentCallKeys = new Set();
+    for (const [index, entry] of entries.entries()) {
+        if (entry.seq !== index + 1)
+            throw new WorkflowJournalValidationError(`workflow journal seq gap at ${entry.seq}.`);
+        if (entry.previousEntryHash !== previousEntryHash) {
+            throw new WorkflowJournalValidationError(`workflow journal hash chain mismatch at seq ${entry.seq}.`);
+        }
+        const { entryHash: _ignored, ...withoutEntryHash } = entry;
+        if (workflowJournalHash(withoutEntryHash) !== entry.entryHash) {
+            throw new WorkflowJournalValidationError(`workflow journal entryHash mismatch at seq ${entry.seq}.`);
+        }
+        if (entry.taskId !== started.taskId || entry.runId !== started.runId) {
+            throw new WorkflowJournalValidationError(`workflow journal task/run mismatch at seq ${entry.seq}.`);
+        }
+        if (terminalSeen) {
+            throw new WorkflowJournalValidationError(`workflow journal has non-terminal entry after terminal at seq ${entry.seq}.`);
+        }
+        if (entry.kind === 'workflow.agent.started') {
+            if (startedAgents.has(entry.agentId)) {
+                throw new WorkflowJournalValidationError(`duplicate agentId at seq ${entry.seq}.`);
+            }
+            if (startedAgentIndexes.has(entry.agentIndex)) {
+                throw new WorkflowJournalValidationError(`duplicate agentIndex at seq ${entry.seq}.`);
+            }
+            if (entry.previousAgentCallKey !== expectedAgentPreviousKey) {
+                throw new WorkflowJournalValidationError(`agent call key chain mismatch at seq ${entry.seq}.`);
+            }
+            const expectedAgentCallKey = computeWorkflowAgentCallKey({
+                previousAgentCallKey: entry.previousAgentCallKey,
+                prompt: entry.prompt,
+                semanticOpts: entry.semanticOpts,
+            });
+            if (entry.agentCallKey !== expectedAgentCallKey) {
+                throw new WorkflowJournalValidationError(`agent call key derivation mismatch at seq ${entry.seq}.`);
+            }
+            if (agentCallKeys.has(entry.agentCallKey)) {
+                throw new WorkflowJournalValidationError(`duplicate agentCallKey at seq ${entry.seq}.`);
+            }
+            agentCallKeys.add(entry.agentCallKey);
+            startedAgentIndexes.add(entry.agentIndex);
+            expectedAgentPreviousKey = entry.agentCallKey;
+            startedAgents.set(entry.agentId, entry);
+        }
+        else if (entry.kind === 'workflow.agent.completed' || entry.kind === 'workflow.agent.failed') {
+            const agent = startedAgents.get(entry.agentId);
+            if (!agent)
+                throw new WorkflowJournalValidationError(`agent final entry without started entry at seq ${entry.seq}.`);
+            if (finalizedAgents.has(entry.agentId))
+                throw new WorkflowJournalValidationError(`duplicate agent final entry at seq ${entry.seq}.`);
+            if (entry.agentIndex !== agent.agentIndex)
+                throw new WorkflowJournalValidationError(`agent final index mismatch at seq ${entry.seq}.`);
+            if (entry.agentCallKey !== agent.agentCallKey)
+                throw new WorkflowJournalValidationError(`agent final key mismatch at seq ${entry.seq}.`);
+            finalizedAgents.add(entry.agentId);
+        }
+        else if (entry.kind === 'workflow.run.completed' || entry.kind === 'workflow.run.failed') {
+            const openAgentCount = startedAgents.size - finalizedAgents.size;
+            if (openAgentCount > 0
+                && (entry.kind === 'workflow.run.completed' || entry.reason !== WORKFLOW_JOURNAL_WRITE_FAILED_REASON)) {
+                throw new WorkflowJournalValidationError(`workflow journal terminal entry has ${openAgentCount} unfinalized agent(s) at seq ${entry.seq}.`);
+            }
+            terminalSeen = true;
+        }
+        previousEntryHash = entry.entryHash;
+    }
+}
+function assertValidWorkflowJournalEntry(value) {
+    const record = asRecord(value);
+    if (!record)
+        throw new WorkflowJournalValidationError('journal entry must be an object.');
+    if (record.version !== 1)
+        throw new WorkflowJournalValidationError('journal entry version must be 1.');
+    if (!isPositiveInteger(record.seq))
+        throw new WorkflowJournalValidationError('journal entry seq must be a positive integer.');
+    if (!isHash(record.previousEntryHash))
+        throw new WorkflowJournalValidationError('journal entry previousEntryHash must be sha256 hex.');
+    if (!isHash(record.entryHash))
+        throw new WorkflowJournalValidationError('journal entry entryHash must be sha256 hex.');
+    if (typeof record.recordedAt !== 'string' || !record.recordedAt)
+        throw new WorkflowJournalValidationError('journal entry recordedAt must be a string.');
+    if (typeof record.taskId !== 'string' || !record.taskId)
+        throw new WorkflowJournalValidationError('journal entry taskId must be a string.');
+    if (typeof record.runId !== 'string' || !record.runId)
+        throw new WorkflowJournalValidationError('journal entry runId must be a string.');
+    if (!isWorkflowJournalKind(record.kind))
+        throw new WorkflowJournalValidationError('journal entry kind is unknown.');
+    rejectUnknownEntryFields(record, record.kind);
+    assertNoOversizedStrings(record, 'entry');
+    switch (record.kind) {
+        case 'workflow.run.started':
+            assertRunStarted(record);
+            break;
+        case 'workflow.agent.started':
+            assertAgentStarted(record);
+            break;
+        case 'workflow.agent.completed':
+            assertAgentCompleted(record);
+            break;
+        case 'workflow.agent.failed':
+            assertAgentFailed(record);
+            break;
+        case 'workflow.run.completed':
+            assertRunCompleted(record);
+            break;
+        case 'workflow.run.failed':
+            assertRunFailed(record);
+            break;
+    }
+}
+function assertRunStarted(record) {
+    if (typeof record.workflowName !== 'string' || !record.workflowName)
+        throw new WorkflowJournalValidationError('workflowName must be a string.');
+    if (typeof record.workflowSource !== 'string' || !record.workflowSource)
+        throw new WorkflowJournalValidationError('workflowSource must be a string.');
+    if (record.workflowSourcePath !== undefined && typeof record.workflowSourcePath !== 'string')
+        throw new WorkflowJournalValidationError('workflowSourcePath must be a string.');
+    if (typeof record.scriptPath !== 'string' || !record.scriptPath)
+        throw new WorkflowJournalValidationError('scriptPath must be a string.');
+    if (typeof record.scriptHash !== 'string' || !record.scriptHash.startsWith('sha256:'))
+        throw new WorkflowJournalValidationError('scriptHash must start with sha256:.');
+    normalizeJournalJsonValue(record.args, 'args');
+    const runtime = asRecord(record.runtime);
+    if (!runtime || runtime.schemaVersion !== 1 || typeof runtime.cwd !== 'string') {
+        throw new WorkflowJournalValidationError('runtime must include schemaVersion 1 and cwd.');
+    }
+}
+function assertAgentStarted(record) {
+    assertAgentCommon(record);
+    if (!isHash(record.previousAgentCallKey))
+        throw new WorkflowJournalValidationError('previousAgentCallKey must be sha256 hex.');
+    if (typeof record.prompt !== 'string' || record.prompt.trim() === '')
+        throw new WorkflowJournalValidationError('prompt must be a non-empty string.');
+    assertWorkflowAgentSemanticOpts(record.semanticOpts);
+}
+function assertAgentCompleted(record) {
+    assertAgentCommon(record);
+    normalizeJournalJsonValue(record.result, 'result');
+    assertUsage(record.usage);
+    if (!isNonNegativeInteger(record.toolCalls))
+        throw new WorkflowJournalValidationError('toolCalls must be a non-negative integer.');
+}
+function assertAgentFailed(record) {
+    assertAgentCommon(record);
+    if (typeof record.reason !== 'string' || !record.reason)
+        throw new WorkflowJournalValidationError('reason must be a string.');
+    if (typeof record.message !== 'string')
+        throw new WorkflowJournalValidationError('message must be a string.');
+}
+function assertRunCompleted(record) {
+    normalizeJournalJsonValue(record.result, 'result');
+    if (typeof record.resultPath !== 'string' || !record.resultPath)
+        throw new WorkflowJournalValidationError('resultPath must be a string.');
+    if (!isNonNegativeInteger(record.agentCount))
+        throw new WorkflowJournalValidationError('agentCount must be a non-negative integer.');
+    assertUsage(record.usage);
+    if (!isNonNegativeInteger(record.toolCalls))
+        throw new WorkflowJournalValidationError('toolCalls must be a non-negative integer.');
+    if (!isNonNegativeNumber(record.durationMs))
+        throw new WorkflowJournalValidationError('durationMs must be a non-negative finite number.');
+}
+function assertRunFailed(record) {
+    if (typeof record.reason !== 'string' || !record.reason)
+        throw new WorkflowJournalValidationError('reason must be a string.');
+    if (typeof record.message !== 'string')
+        throw new WorkflowJournalValidationError('message must be a string.');
+    if (record.recovery !== undefined) {
+        const recovery = asRecord(record.recovery);
+        if (!recovery || typeof recovery.retryable !== 'boolean' || typeof recovery.reason !== 'string') {
+            throw new WorkflowJournalValidationError('recovery must include retryable and reason.');
+        }
+    }
+    if (!isNonNegativeNumber(record.durationMs))
+        throw new WorkflowJournalValidationError('durationMs must be a non-negative finite number.');
+}
+function assertAgentCommon(record) {
+    if (!isNonNegativeInteger(record.agentIndex))
+        throw new WorkflowJournalValidationError('agentIndex must be a non-negative integer.');
+    if (typeof record.agentId !== 'string' || !record.agentId)
+        throw new WorkflowJournalValidationError('agentId must be a string.');
+    if (!isHash(record.agentCallKey))
+        throw new WorkflowJournalValidationError('agentCallKey must be sha256 hex.');
+}
+function assertUsage(value) {
+    const usage = asRecord(value);
+    if (!usage)
+        throw new WorkflowJournalValidationError('usage must be an object.');
+    for (const key of ['inputTokens', 'outputTokens', 'totalTokens']) {
+        if (!isNonNegativeNumber(usage[key]))
+            throw new WorkflowJournalValidationError(`usage.${key} must be a non-negative finite number.`);
+    }
+}
+function assertWorkflowAgentSemanticOpts(value) {
+    const opts = asRecord(value);
+    if (!opts)
+        throw new WorkflowJournalValidationError('semanticOpts must be an object.');
+    rejectUnknownKeys(opts, ['schema', 'model', 'effort', 'isolation', 'agentType'], 'semanticOpts');
+    if (typeof opts.model !== 'string' || !opts.model)
+        throw new WorkflowJournalValidationError('semanticOpts.model must be a string.');
+    for (const key of ['effort', 'isolation', 'agentType']) {
+        if (opts[key] !== undefined && typeof opts[key] !== 'string') {
+            throw new WorkflowJournalValidationError(`semanticOpts.${key} must be a string.`);
+        }
+    }
+    if (opts.schema !== undefined)
+        normalizeJournalJsonValue(opts.schema, 'semanticOpts.schema');
+}
+function rejectUnknownEntryFields(record, kind) {
+    rejectUnknownKeys(record, ENTRY_KEYS[kind], kind);
+}
+function rejectUnknownKeys(record, allowed, label) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(record)) {
+        if (!allowedSet.has(key))
+            throw new WorkflowJournalValidationError(`${label} contains unknown field ${key}.`);
+    }
+}
+function assertNoOversizedStrings(value, path) {
+    if (typeof value === 'string') {
+        if (Buffer.byteLength(value, 'utf8') > MAX_STRING_BYTES) {
+            throw new WorkflowJournalValidationError(`${path} exceeds ${MAX_STRING_BYTES} bytes.`);
+        }
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries())
+            assertNoOversizedStrings(item, `${path}[${index}]`);
+        return;
+    }
+    for (const [key, item] of Object.entries(value))
+        assertNoOversizedStrings(item, `${path}.${key}`);
+}
+function normalizeJsonValue(value, label, seen) {
+    if (value === null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new WorkflowJournalValidationError(`${label} must not contain NaN or Infinity.`);
+        return value;
+    }
+    if (value === undefined || typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') {
+        throw new WorkflowJournalValidationError(`${label} must be JSON-serializable.`);
+    }
+    if (typeof value !== 'object')
+        throw new WorkflowJournalValidationError(`${label} must be JSON-serializable.`);
+    if (seen.has(value))
+        throw new WorkflowJournalValidationError(`${label} must not contain cycles.`);
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item, index) => normalizeJsonValue(item, `${label}[${index}]`, seen));
+        }
+        if (!isPlainJsonObject(value)) {
+            throw new WorkflowJournalValidationError(`${label} must be a plain JSON object.`);
+        }
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = normalizeJsonValue(item, `${label}.${key}`, seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function stableSerialize(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableSerialize(item)).join(',')}]`;
+    }
+    const objectValue = value;
+    const keys = Object.keys(objectValue).sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableSerialize(objectValue[key])}`).join(',')}}`;
+}
+function toWorkflowJournalError(err, message) {
+    return err instanceof WorkflowJournalError ? err : new WorkflowJournalError(message, err);
+}
+function isPlainJsonObject(value) {
+    if (Object.prototype.toString.call(value) !== '[object Object]')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === null)
+        return true;
+    return Object.getPrototypeOf(prototype) === null;
+}
+async function ensureWorkflowTranscriptDir(transcriptDir) {
+    let before;
+    try {
+        before = await lstat(transcriptDir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT')
+            throw new WorkflowJournalError(`Workflow transcript directory cannot be inspected: ${transcriptDir}.`, err);
+    }
+    if (before?.isSymbolicLink())
+        throw new WorkflowJournalError(`Workflow transcript directory must not be a symlink: ${transcriptDir}.`);
+    if (before && !before.isDirectory())
+        throw new WorkflowJournalError(`Workflow transcript path must be a directory: ${transcriptDir}.`);
+    if (!before) {
+        try {
+            await mkdir(transcriptDir, { recursive: true, mode: TRANSCRIPT_DIR_MODE });
+        }
+        catch (err) {
+            throw new WorkflowJournalError(`Workflow transcript directory cannot be created: ${transcriptDir}.`, err);
+        }
+    }
+    const after = await lstat(transcriptDir);
+    if (after.isSymbolicLink() || !after.isDirectory()) {
+        throw new WorkflowJournalError(`Workflow transcript path must be a real directory: ${transcriptDir}.`);
+    }
+    await chmod(transcriptDir, TRANSCRIPT_DIR_MODE).catch(() => undefined);
+}
+async function appendJournalLine(journalPath, entry, durability) {
+    const line = `${JSON.stringify(entry)}\n`;
+    let handle;
+    let beforeSize;
+    try {
+        handle = await open(journalPath, fsConstants.O_APPEND | fsConstants.O_WRONLY, JOURNAL_FILE_MODE);
+        beforeSize = (await handle.stat()).size;
+        await handle.writeFile(line, 'utf8');
+        if (durability?.syncFile) {
+            await durability.syncFile(journalPath, entry);
+        }
+        else if (typeof handle.datasync === 'function') {
+            await handle.datasync();
+        }
+        else {
+            await handle.sync();
+        }
+    }
+    catch (err) {
+        if (handle && beforeSize !== undefined) {
+            await handle.truncate(beforeSize).catch(() => undefined);
+            await handle.sync().catch(() => undefined);
+        }
+        throw new WorkflowJournalError(`Workflow journal entry ${entry.kind} could not be durably written.`, err);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function durableDirectorySync(directoryPath, durability) {
+    if (durability?.syncDirectory) {
+        await durability.syncDirectory(directoryPath);
+        return;
+    }
+    let handle;
+    try {
+        await stat(directoryPath);
+        handle = await open(directoryPath, fsConstants.O_RDONLY);
+        await handle.sync();
+    }
+    catch (err) {
+        if (isDirectorySyncUnsupported(err))
+            return;
+        throw new WorkflowJournalError(`Workflow journal directory could not be durably synced: ${directoryPath}.`, err);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function isDirectorySyncUnsupported(err) {
+    const code = err.code;
+    return code === 'EINVAL' || code === 'EISDIR' || code === 'ENOTSUP' || code === 'EPERM' || code === 'EACCES';
+}
+function isTruncationParseError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /Unexpected end|unterminated|end of JSON input|Expected ',' or '}' after property value/i.test(message);
+}
+function isWorkflowJournalKind(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(ENTRY_KEYS, value);
+}
+function isHash(value) {
+    return typeof value === 'string' && HASH_RE.test(value);
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && value > 0;
+}
+function isNonNegativeInteger(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+function isNonNegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}