@planu/cli 4.14.1 → 5.1.1

package/dist/engine/execution/durable-job-heartbeat-runtime.js

@@ -0,0 +1,400 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isMainThread, parentPort, Worker, workerData } from 'node:worker_threads';
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+function heartbeatWorkerUrl() {
+    const sibling = new URL('./durable-job-heartbeat-runtime.js', import.meta.url);
+    if (existsSync(sibling)) {
+        return sibling;
+    }
+    const built = resolvePath(process.cwd(), 'dist/engine/execution/durable-job-heartbeat-runtime.js');
+    if (existsSync(built)) {
+        return pathToFileURL(built);
+    }
+    throw new Error('[Planu] Durable heartbeat worker artifact is missing; run the production build');
+}
+function positiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function heartbeatIdentifier(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value);
+}
+function heartbeatTimingIsValid(candidate) {
+    return (positiveSafeInteger(candidate.fencingToken) &&
+        positiveSafeInteger(candidate.leaseMs) &&
+        positiveSafeInteger(candidate.heartbeatMs) &&
+        Number(candidate.heartbeatMs) < Number(candidate.leaseMs) &&
+        positiveSafeInteger(candidate.databaseBusyTimeoutMs) &&
+        Number(candidate.databaseBusyTimeoutMs) <
+            Number(candidate.leaseMs) - Number(candidate.heartbeatMs));
+}
+function workerDataIsValid(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.kind === 'planu-durable-job-heartbeat' &&
+        candidate.schemaVersion === 1 &&
+        typeof candidate.databasePath === 'string' &&
+        isAbsolute(candidate.databasePath) &&
+        candidate.databasePath !== ':memory:' &&
+        typeof candidate.projectId === 'string' &&
+        /^[a-f0-9]{32}$/u.test(candidate.projectId) &&
+        heartbeatIdentifier(candidate.workspaceId) &&
+        heartbeatIdentifier(candidate.operationId) &&
+        heartbeatIdentifier(candidate.workerId) &&
+        heartbeatTimingIsValid(candidate));
+}
+function sameIdentity(message, input) {
+    return (message.schemaVersion === 1 &&
+        message.projectId === input.projectId &&
+        message.workspaceId === input.workspaceId &&
+        message.operationId === input.operationId &&
+        message.workerId === input.workerId &&
+        message.fencingToken === input.fencingToken);
+}
+function asError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback);
+}
+async function terminateWithinBudget(worker, timeoutMs) {
+    worker.unref();
+    let timeout;
+    const expired = new Promise((resolveTimeout) => {
+        timeout = setTimeout(() => {
+            resolveTimeout('timeout');
+        }, timeoutMs);
+        timeout.unref();
+    });
+    const termination = worker.terminate().then(() => 'terminated', (error) => {
+        throw asError(error, '[Planu] Durable heartbeat Worker termination failed');
+    });
+    try {
+        if ((await Promise.race([termination, expired])) === 'timeout') {
+            throw new Error('[Planu] Durable heartbeat Worker termination timed out');
+        }
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+function heartbeatAuthorityReason(value) {
+    return (value === 'cancelled-or-stale' || value === 'database-failure' || value === 'worker-failure');
+}
+/** Start one autonomous, fenced heartbeat and wait for its typed ready acknowledgement. */
+// eslint-disable-next-line max-lines-per-function -- all controller settlement guards surround one Worker
+export async function createDurableJobHeartbeat(input, options = {}) {
+    const data = {
+        kind: 'planu-durable-job-heartbeat',
+        schemaVersion: 1,
+        databasePath: input.databasePath,
+        projectId: input.projectId,
+        workspaceId: input.workspaceId,
+        operationId: input.operationId,
+        workerId: input.workerId,
+        fencingToken: input.fencingToken,
+        leaseMs: input.leaseMs,
+        heartbeatMs: input.heartbeatMs,
+        databaseBusyTimeoutMs: input.databaseBusyTimeoutMs,
+    };
+    if (!workerDataIsValid(data)) {
+        throw new Error('[Planu] Durable heartbeat configuration is invalid');
+    }
+    if (!Number.isSafeInteger(input.startupTimeoutMs) ||
+        input.startupTimeoutMs <= 0 ||
+        !Number.isSafeInteger(input.shutdownTimeoutMs) ||
+        input.shutdownTimeoutMs <= 0) {
+        throw new Error('[Planu] Durable heartbeat lifecycle budgets are invalid');
+    }
+    const worker = options.workerFactory
+        ? options.workerFactory(new URL('./durable-job-heartbeat-runtime.js', import.meta.url), data)
+        : new Worker(heartbeatWorkerUrl(), {
+            workerData: data,
+            execArgv: process.execArgv.filter((argument) => !argument.startsWith('--input-type')),
+        });
+    let ready = false;
+    let stopping = false;
+    let lost = false;
+    let exited = false;
+    let startFailed = false;
+    let lastSequence = 0;
+    let stopPromise;
+    let resolveReady;
+    let rejectReady;
+    let resolveStopped;
+    let resolveExited;
+    const readyPromise = new Promise((resolveReadyPromise, rejectReadyPromise) => {
+        resolveReady = resolveReadyPromise;
+        rejectReady = rejectReadyPromise;
+    });
+    const stoppedPromise = new Promise((settleStopped) => {
+        resolveStopped = settleStopped;
+    });
+    const exitedPromise = new Promise((settleExited) => {
+        resolveExited = settleExited;
+    });
+    const authorityLost = (error) => {
+        if (lost || stopping) {
+            return;
+        }
+        lost = true;
+        try {
+            input.onAuthorityLost(error);
+        }
+        catch (callbackError) {
+            reportClassifiedDegradation('VALIDATE_JOB_HEARTBEAT_FAILURE', callbackError);
+        }
+    };
+    const settleLocally = () => {
+        worker.removeAllListeners();
+    };
+    const failStart = (error) => {
+        if (ready) {
+            authorityLost(error);
+            return;
+        }
+        if (startFailed) {
+            return;
+        }
+        startFailed = true;
+        authorityLost(error);
+        clearTimeout(startupTimer);
+        void (async () => {
+            try {
+                if (!exited) {
+                    await terminateWithinBudget(worker, input.shutdownTimeoutMs);
+                }
+            }
+            catch (cleanupError) {
+                reportClassifiedDegradation('VALIDATE_JOB_HEARTBEAT_FAILURE', cleanupError);
+            }
+            finally {
+                settleLocally();
+                rejectReady(error);
+            }
+        })();
+    };
+    const startupTimer = setTimeout(() => {
+        const error = new Error('[Planu] Durable heartbeat Worker startup timed out');
+        failStart(error);
+    }, input.startupTimeoutMs);
+    startupTimer.unref();
+    worker.on('message', (value) => {
+        const message = value;
+        if (!sameIdentity(message, input)) {
+            failStart(new Error('[Planu] Durable heartbeat message identity mismatch'));
+            return;
+        }
+        if (message.type === 'ready') {
+            if (!ready) {
+                ready = true;
+                clearTimeout(startupTimer);
+                resolveReady();
+            }
+            return;
+        }
+        if (message.type === 'renewed' && ready && Number.isSafeInteger(message.sequence)) {
+            const sequence = Number(message.sequence);
+            if (sequence <= 0) {
+                authorityLost(new Error('[Planu] Durable heartbeat sequence is invalid'));
+                return;
+            }
+            if (sequence <= lastSequence) {
+                return;
+            }
+            if (sequence !== lastSequence + 1) {
+                authorityLost(new Error('[Planu] Durable heartbeat sequence gap'));
+                return;
+            }
+            lastSequence = sequence;
+            return;
+        }
+        if (message.type === 'authorityLost' &&
+            Number.isSafeInteger(message.sequence) &&
+            heartbeatAuthorityReason(message.reason) &&
+            Number(message.sequence) === lastSequence + 1) {
+            const error = new Error(`[Planu] Durable heartbeat authority lost (${message.reason})`);
+            lastSequence = Number(message.sequence);
+            if (ready) {
+                authorityLost(error);
+            }
+            else {
+                failStart(error);
+            }
+            return;
+        }
+        if (message.type === 'stopped' && stopping) {
+            resolveStopped();
+            return;
+        }
+        const error = new Error('[Planu] Durable heartbeat protocol violation');
+        if (ready) {
+            authorityLost(error);
+        }
+        else {
+            failStart(error);
+        }
+    });
+    worker.once('error', (error) => {
+        failStart(asError(error, '[Planu] Durable heartbeat Worker failed'));
+    });
+    worker.once('exit', (code) => {
+        exited = true;
+        resolveExited();
+        if (!stopping) {
+            failStart(new Error(`[Planu] Durable heartbeat Worker exited ${String(code)}`));
+        }
+    });
+    await readyPromise;
+    return {
+        stop() {
+            stopPromise ??= (async () => {
+                stopping = true;
+                if (exited) {
+                    settleLocally();
+                    return;
+                }
+                try {
+                    worker.postMessage({ ...data, type: 'stop' });
+                }
+                catch (postError) {
+                    reportClassifiedDegradation('VALIDATE_JOB_HEARTBEAT_FAILURE', postError);
+                    try {
+                        await terminateWithinBudget(worker, input.shutdownTimeoutMs);
+                    }
+                    finally {
+                        settleLocally();
+                    }
+                    return;
+                }
+                let shutdownTimer;
+                const shutdownExpired = new Promise((resolveShutdown) => {
+                    shutdownTimer = setTimeout(() => {
+                        resolveShutdown('timeout');
+                    }, input.shutdownTimeoutMs);
+                    shutdownTimer.unref();
+                });
+                const outcome = await Promise.race([
+                    stoppedPromise.then(() => 'stopped'),
+                    exitedPromise.then(() => 'exited'),
+                    shutdownExpired,
+                ]);
+                try {
+                    if (outcome === 'stopped') {
+                        const exitOutcome = await Promise.race([
+                            exitedPromise.then(() => 'exited'),
+                            shutdownExpired,
+                        ]);
+                        if (exitOutcome === 'timeout') {
+                            await terminateWithinBudget(worker, input.shutdownTimeoutMs);
+                        }
+                    }
+                    if (outcome === 'timeout') {
+                        await terminateWithinBudget(worker, input.shutdownTimeoutMs);
+                    }
+                }
+                finally {
+                    if (shutdownTimer) {
+                        clearTimeout(shutdownTimer);
+                    }
+                    settleLocally();
+                }
+            })();
+            return stopPromise;
+        },
+    };
+}
+// eslint-disable-next-line max-lines-per-function -- one Worker owns one contained database lifecycle
+function runHeartbeatWorker(data) {
+    const port = parentPort;
+    if (!port || !workerDataIsValid(data)) {
+        throw new Error('[Planu] Durable heartbeat Worker data is invalid');
+    }
+    const identity = {
+        schemaVersion: 1,
+        projectId: data.projectId,
+        workspaceId: data.workspaceId,
+        operationId: data.operationId,
+        workerId: data.workerId,
+        fencingToken: data.fencingToken,
+    };
+    const database = new RuntimeDatabase({
+        path: data.databasePath,
+        busyTimeoutMs: data.databaseBusyTimeoutMs,
+        checkIntegrity: false,
+        maxConnections: 1,
+    });
+    let sequence = 0;
+    let settled = false;
+    const stop = (notify) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearInterval(timer);
+        try {
+            database.close();
+        }
+        finally {
+            if (notify) {
+                port.postMessage({ ...identity, type: 'stopped' });
+            }
+            port.close();
+        }
+    };
+    const lose = (reason) => {
+        if (settled) {
+            return;
+        }
+        sequence += 1;
+        port.postMessage({ ...identity, type: 'authorityLost', sequence, reason });
+        stop(false);
+    };
+    const renew = (notify) => {
+        try {
+            const renewed = database.renewJobLease({
+                id: data.operationId,
+                projectId: data.projectId,
+                workspaceId: data.workspaceId,
+                workerId: data.workerId,
+                fencingToken: data.fencingToken,
+                leaseMs: data.leaseMs,
+            });
+            if (!renewed) {
+                lose('cancelled-or-stale');
+                return false;
+            }
+            if (notify) {
+                sequence += 1;
+                port.postMessage({ ...identity, type: 'renewed', sequence });
+            }
+            return true;
+        }
+        catch (databaseError) {
+            reportClassifiedDegradation('VALIDATE_JOB_HEARTBEAT_FAILURE', databaseError);
+            lose('database-failure');
+            return false;
+        }
+    };
+    const timer = setInterval(() => {
+        renew(true);
+    }, data.heartbeatMs);
+    timer.unref();
+    port.on('message', (message) => {
+        const command = message;
+        if (command.type === 'stop' && sameIdentity(command, data)) {
+            stop(true);
+        }
+    });
+    if (renew(false)) {
+        port.postMessage({ ...identity, type: 'ready' });
+    }
+}
+if (!isMainThread &&
+    workerData?.kind === 'planu-durable-job-heartbeat') {
+    runHeartbeatWorker(workerData);
+}
+//# sourceMappingURL=durable-job-heartbeat-runtime.js.map

package/dist/engine/execution/job-runtime.d.ts

@@ -9,6 +9,8 @@ export declare class DurableJobRuntime implements Disposable {
     private readonly database;
     private readonly ownsDatabase;
     constructor(options?: DurableJobRuntimeOptions);
+    /** Runtime database path for contained infrastructure workers. */
+    runtimeDatabasePath(): string;
     accept(input: {
         readonly projectId: string;
         readonly workspaceId?: string;
@@ -27,6 +29,8 @@ export declare class DurableJobRuntime implements Disposable {
         readonly maxAttempts?: number;
     }): DurableJobRecord;
     get(input: DurableJobIdentity): DurableJobRecord;
+    /** Return the allowlisted public projection for one job and its current queue scope. */
+    observe(input: DurableJobIdentity | DurableJobRecord): ReturnType<typeof publicJobObservation>;
     list(projectId: string, workspaceId?: string): readonly DurableJobRecord[];
     listRunnableScopes(): readonly {
         projectId: string;
@@ -43,6 +47,7 @@ export declare class DurableJobRuntime implements Disposable {
     }): boolean;
     recordProgress(input: DurableJobIdentity & {
         readonly workerId: string;
+        readonly leaseMs: number;
         readonly fencingToken: number;
         readonly checkpoint: unknown;
     }): DurableJobRecord;
@@ -63,6 +68,7 @@ export declare class DurableJobRuntime implements Disposable {
     }): DurableJobRecord;
     retry(input: DurableJobIdentity): DurableJobRecord;
     restart(input: DurableJobIdentity): DurableJobRecord;
+    restartReceiptPublication(input: DurableJobIdentity): DurableJobRecord;
     restartWithPayload(input: DurableJobIdentity & {
         readonly payload: unknown;
     }): DurableJobRecord;
@@ -75,4 +81,28 @@ export declare class DurableJobRuntime implements Disposable {
 }
 /** Stable watcher cursor that detects state changes even within one clock millisecond. */
 export declare function durableJobCursor(job: DurableJobRecord): string;
+/** Build a privacy-safe job projection from existing durable records. */
+export declare function publicJobObservation(job: DurableJobRecord, scopeJobs: readonly DurableJobRecord[], now?: number): {
+    id: string;
+    projectId: string;
+    workspaceId: string;
+    state: DurableJobRecord['state'];
+    checkpoint?: unknown;
+    result?: unknown;
+    error?: string;
+    attempts: number;
+    maxAttempts: number;
+    cancelRequested: boolean;
+    createdAt: string;
+    updatedAt: string;
+    queue: {
+        status: 'active' | 'queued' | 'terminal';
+        position: number | null;
+        aheadCount: number;
+        capacity: number;
+        remainingBudgetMs: number;
+    };
+};
+/** Stable public cursor: queue movement and semantic progress count, leases and time do not. */
+export declare function publicJobCursor(job: ReturnType<typeof publicJobObservation>): string;
 //# sourceMappingURL=job-runtime.d.ts.map

package/dist/engine/execution/job-runtime.js

@@ -1,11 +1,14 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { RuntimeDatabase, } from '../../storage/runtime-db.js';
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { getRuntimePolicy } from '../runtime-policy.js';
 import { isNativeWorkerOperation } from './native-worker-protocol.js';
 import { getExecutionContext } from './context.js';
+import { sanitizePublicJobValue } from './public-job-sanitizer.js';
 const DEFAULT_WORKSPACE_ID = 'global';
 const MAX_WATCH_MS = 30_000;
 const TERMINAL_STATES = new Set(['cancelled', 'failed', 'dead-letter', 'completed']);
+const DURATION_ONLY_CHECKPOINT_KEYS = new Set(['durationMs', 'elapsedMs']);
 export class DurableJobNotFoundError extends Error {
     constructor(operationId) {
         super(`[Planu] Job ${operationId} was not found`);
@@ -23,6 +26,10 @@ export class DurableJobRuntime {
         this.ownsDatabase = true;
         this.database.recoverExpiredJobs();
     }
+    /** Runtime database path for contained infrastructure workers. */
+    runtimeDatabasePath() {
+        return this.database.path;
+    }
     accept(input) {
         const operationId = input.operationId ?? randomUUID();
         const workspaceId = input.workspaceId ?? DEFAULT_WORKSPACE_ID;
@@ -60,6 +67,11 @@ export class DurableJobRuntime {
     get(input) {
         return this.requireJob(input);
     }
+    /** Return the allowlisted public projection for one job and its current queue scope. */
+    observe(input) {
+        const job = 'id' in input ? input : this.requireJob(input);
+        return publicJobObservation(job, this.list(job.projectId, job.workspaceId));
+    }
     list(projectId, workspaceId = DEFAULT_WORKSPACE_ID) {
         return this.database.listJobs(projectId, workspaceId);
     }
@@ -74,7 +86,7 @@ export class DurableJobRuntime {
     }
     recordProgress(input) {
         return this.database.recordJobProgress({
-            ...this.leaseInput({ ...input, leaseMs: 100 }),
+            ...this.leaseInput(input),
             checkpoint: input.checkpoint,
         });
     }
@@ -102,6 +114,12 @@ export class DurableJobRuntime {
     restart(input) {
         return this.database.restartJob(input.projectId, input.workspaceId ?? DEFAULT_WORKSPACE_ID, input.operationId);
     }
+    restartReceiptPublication(input) {
+        return this.database.restartReceiptPublication(input.projectId, input.workspaceId ?? DEFAULT_WORKSPACE_ID, input.operationId, {
+            logMaxBytes: getRuntimePolicy().validation.receiptCheckpointLogMaxBytes,
+            resultMaxBytes: getRuntimePolicy().validation.receiptCheckpointResultMaxBytes,
+        });
+    }
     restartWithPayload(input) {
         return this.database.restartJobWithPayload(input.projectId, input.workspaceId ?? DEFAULT_WORKSPACE_ID, input.operationId, input.payload);
     }
@@ -132,9 +150,10 @@ export class DurableJobRuntime {
         const deadline = Date.now() + timeoutMs;
         for (;;) {
             const job = this.requireJob(input);
+            const cursor = publicJobCursor(this.observe(job));
             if (TERMINAL_STATES.has(job.state) ||
                 input.afterCursor === undefined ||
-                durableJobCursor(job) !== input.afterCursor ||
+                cursor !== input.afterCursor ||
                 Date.now() >= deadline) {
                 return job;
             }
@@ -172,20 +191,109 @@ export class DurableJobRuntime {
 }
 /** Stable watcher cursor that detects state changes even within one clock millisecond. */
 export function durableJobCursor(job) {
+    const capacity = getRuntimePolicy().validation.workerConcurrency;
+    const status = queueStatus(job);
+    return publicJobCursor({
+        ...publicJobFields(job),
+        queue: {
+            status,
+            position: status === 'terminal' ? null : 1,
+            aheadCount: 0,
+            capacity,
+            remainingBudgetMs: remainingBudgetMs(job),
+        },
+    });
+}
+/** Build a privacy-safe job projection from existing durable records. */
+export function publicJobObservation(job, scopeJobs, now = Date.now()) {
+    const status = queueStatus(job);
+    const queueJobs = scopeJobs.filter(isQueueRelevant).filter((candidate) => !isTerminal(candidate));
+    const positionIndex = queueJobs.findIndex((candidate) => candidate.id === job.id);
+    const position = status === 'terminal' ? null : Math.max(0, positionIndex) + 1;
+    return {
+        ...publicJobFields(job),
+        queue: {
+            status,
+            position,
+            aheadCount: position === null ? 0 : position - 1,
+            capacity: getRuntimePolicy().validation.workerConcurrency,
+            remainingBudgetMs: status === 'terminal' ? 0 : remainingBudgetMs(job, now),
+        },
+    };
+}
+/** Stable public cursor: queue movement and semantic progress count, leases and time do not. */
+export function publicJobCursor(job) {
     return createHash('sha256')
         .update(JSON.stringify({
         state: job.state,
-        checkpoint: job.checkpoint,
+        checkpoint: omitDurationOnlyFields(job.checkpoint),
         result: job.result,
         error: job.error,
         attempts: job.attempts,
         cancelRequested: job.cancelRequested,
-        leaseOwner: job.leaseOwner,
-        leaseExpiresAt: job.leaseExpiresAt,
-        updatedAt: job.updatedAt,
+        queue: {
+            status: job.queue.status,
+            position: job.queue.position,
+            aheadCount: job.queue.aheadCount,
+            capacity: job.queue.capacity,
+        },
     }))
         .digest('hex');
 }
+function publicJobFields(job) {
+    return {
+        id: job.id,
+        projectId: job.projectId,
+        workspaceId: job.workspaceId,
+        state: job.state,
+        ...(job.checkpoint === undefined ? {} : { checkpoint: sanitizePublicJobValue(job.checkpoint) }),
+        ...(job.result === undefined ? {} : { result: sanitizePublicJobValue(job.result) }),
+        ...(job.error === undefined ? {} : { error: sanitizePublicJobValue(job.error) }),
+        attempts: job.attempts,
+        maxAttempts: job.maxAttempts,
+        cancelRequested: job.cancelRequested,
+        createdAt: job.createdAt,
+        updatedAt: job.updatedAt,
+    };
+}
+function queueStatus(job) {
+    if (isTerminal(job)) {
+        return 'terminal';
+    }
+    return job.state === 'running' ? 'active' : 'queued';
+}
+function isTerminal(job) {
+    return TERMINAL_STATES.has(job.state);
+}
+function isQueueRelevant(job) {
+    if (!job.payload || typeof job.payload !== 'object') {
+        return true;
+    }
+    const kind = job.payload.kind;
+    return kind === undefined || kind === 'validate';
+}
+function remainingBudgetMs(job, now = Date.now()) {
+    const payload = job.payload && typeof job.payload === 'object'
+        ? job.payload
+        : undefined;
+    const explicitDeadline = payload?.deadlineAt;
+    const fallbackDeadline = Date.parse(job.createdAt) + getRuntimePolicy().validation.defaultDeadlineMs;
+    const deadline = typeof explicitDeadline === 'number' && Number.isFinite(explicitDeadline)
+        ? explicitDeadline
+        : fallbackDeadline;
+    return Math.max(0, Math.floor(deadline - now));
+}
+function omitDurationOnlyFields(value) {
+    if (Array.isArray(value)) {
+        return value.map(omitDurationOnlyFields);
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => !DURATION_ONLY_CHECKPOINT_KEYS.has(key))
+            .map(([key, nested]) => [key, omitDurationOnlyFields(nested)]));
+    }
+    return value;
+}
 function abortableDelay(delayMs, signals) {
     const activeSignals = signals.filter((signal) => signal !== undefined);
     const aborted = activeSignals.find((signal) => signal.aborted);

package/dist/engine/execution/operation-journal.js

@@ -54,9 +54,15 @@ export class OperationJournal {
             const existing = this.get(operation, idempotencyKey);
             if (existing) {
                 if (existing.requestDigest !== requestDigest) {
-                    throw new BoundaryFailure('Conflict', 'operation begin', 'Use a new idempotency key for a different request.');
+                    // SPEC-1348: a rolled-back attempt produced no durable effects, so the
+                    // key is re-claimable even when the retry payload differs byte-wise.
+                    if (existing.state !== 'rolled-back') {
+                        throw new BoundaryFailure('Conflict', 'operation begin', 'Use a new idempotency key for a different request.');
+                    }
+                }
+                else {
+                    return existing;
                 }
-                return existing;
             }
             const now = new Date().toISOString();
             const entry = {
@@ -66,8 +72,8 @@ export class OperationJournal {
                 requestDigest,
                 state: 'intent',
                 ...(recovery ?? {}),
-                recoveryAttempts: 0,
-                createdAt: now,
+                recoveryAttempts: existing?.recoveryAttempts ?? 0,
+                createdAt: existing?.createdAt ?? now,
                 updatedAt: now,
             };
             this.put(entry);

package/dist/engine/execution/public-job-sanitizer.d.ts

@@ -0,0 +1,4 @@
+/** Recursively remove secrets and absolute paths from public durable-job values. */
+export declare function sanitizePublicJobValue(value: string): string;
+export declare function sanitizePublicJobValue(value: unknown): unknown;
+//# sourceMappingURL=public-job-sanitizer.d.ts.map