@planu/cli 4.13.0 → 5.0.0

package/dist/engine/execution/context.js

@@ -0,0 +1,130 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const executionStorage = new AsyncLocalStorage();
+export class ExecutionCancelledError extends Error {
+    code = 'EXECUTION_CANCELLED';
+    constructor(message = 'Execution was cancelled before commit') {
+        super(message);
+        this.name = 'ExecutionCancelledError';
+    }
+}
+export function getExecutionContext() {
+    return executionStorage.getStore();
+}
+export function getExecutionSignal() {
+    return getExecutionContext()?.signal;
+}
+export function remainingExecutionMs() {
+    return getExecutionContext()?.remainingMs() ?? Number.POSITIVE_INFINITY;
+}
+/**
+ * Must be called immediately before a mutation crosses its commit boundary.
+ * AsyncLocalStorage keeps the cancelled state visible to work that outlives its
+ * request, so abandoned handlers cannot commit after acknowledgement.
+ */
+export function assertExecutionCanCommit(signal) {
+    signal?.throwIfAborted();
+    const context = getExecutionContext();
+    if (context !== undefined) {
+        context.assertCanCommit();
+    }
+}
+export async function guardExecutionCommit(commit) {
+    assertExecutionCanCommit();
+    return commit();
+}
+export function createExecutionScope(options) {
+    const controller = new AbortController();
+    const state = { phase: 'running' };
+    const abortFromUpstream = () => {
+        cancel(options.upstreamSignal?.reason ?? new ExecutionCancelledError());
+    };
+    const cancel = (reason = new ExecutionCancelledError()) => {
+        if (state.phase !== 'acknowledged') {
+            state.phase = 'cancelled';
+        }
+        if (!controller.signal.aborted) {
+            controller.abort(reason);
+        }
+    };
+    if (options.upstreamSignal?.aborted === true) {
+        abortFromUpstream();
+    }
+    else {
+        options.upstreamSignal?.addEventListener('abort', abortFromUpstream, { once: true });
+    }
+    const context = {
+        requestId: options.requestId ?? randomUUID(),
+        ...(options.idempotencyKey === undefined ? {} : { idempotencyKey: options.idempotencyKey }),
+        deadlineAt: options.deadlineAt,
+        signal: controller.signal,
+        get phase() {
+            return state.phase;
+        },
+        remainingMs: () => Math.max(0, options.deadlineAt - Date.now()),
+        assertCanCommit: () => {
+            if (controller.signal.aborted ||
+                state.phase === 'cancelled' ||
+                state.phase === 'acknowledged') {
+                throw new ExecutionCancelledError();
+            }
+            if (state.phase === 'committed') {
+                throw new Error('Execution has already crossed its commit boundary');
+            }
+            if (Date.now() >= options.deadlineAt) {
+                cancel(new ExecutionCancelledError('Execution deadline elapsed before commit'));
+                throw new ExecutionCancelledError('Execution deadline elapsed before commit');
+            }
+        },
+        markCommitted: () => {
+            context.assertCanCommit();
+            state.phase = 'committed';
+        },
+    };
+    return {
+        context,
+        run: (fn) => executionStorage.run(context, fn),
+        cancel,
+        acknowledge: () => {
+            if (state.phase !== 'cancelled') {
+                state.phase = 'acknowledged';
+            }
+        },
+        dispose: () => {
+            options.upstreamSignal?.removeEventListener('abort', abortFromUpstream);
+        },
+    };
+}
+/** Creates a child cancellation node whose deadline never exceeds its parent. */
+export function createChildCancellationScope(requestedMs) {
+    const parent = getExecutionContext();
+    const parentRemaining = parent?.remainingMs() ?? Number.POSITIVE_INFINITY;
+    const normalizedMs = Number.isFinite(requestedMs) ? Math.max(0, requestedMs) : 0;
+    const timeoutMs = Math.max(0, Math.min(normalizedMs, parentRemaining));
+    const controller = new AbortController();
+    let deadlineElapsed = false;
+    const abortFromParent = () => {
+        controller.abort(parent?.signal.reason ?? new ExecutionCancelledError());
+    };
+    if (parent?.signal.aborted === true) {
+        abortFromParent();
+    }
+    else {
+        parent?.signal.addEventListener('abort', abortFromParent, { once: true });
+    }
+    const timer = setTimeout(() => {
+        deadlineElapsed = true;
+        controller.abort(new ExecutionCancelledError(`Execution budget elapsed after ${String(timeoutMs)}ms`));
+    }, timeoutMs);
+    timer.unref();
+    return {
+        signal: controller.signal,
+        timeoutMs,
+        didDeadlineElapse: () => deadlineElapsed,
+        dispose: () => {
+            clearTimeout(timer);
+            parent?.signal.removeEventListener('abort', abortFromParent);
+        },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/engine/execution/deadline-io.d.ts

@@ -0,0 +1,21 @@
+import type { MakeDirectoryOptions, WriteFileOptions } from 'node:fs';
+/** Fetch under the active request cancellation tree. */
+export declare function executionFetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+/** Create a directory only while the request remains pre-commit and active. */
+export declare function executionMkdir(path: string, options: MakeDirectoryOptions & {
+    recursive: true;
+}): Promise<string | undefined>;
+/** Exclusive-create helper for idempotency claims; never overwrites an owner. */
+export declare function executionWriteFileExclusive(path: string, content: string, options?: Omit<WriteFileOptions, 'flag'>): Promise<void>;
+export declare function executionRename(source: string, target: string): Promise<void>;
+export declare function executionLink(source: string, target: string): Promise<void>;
+export declare function executionRemove(path: string, options?: {
+    force?: boolean;
+    recursive?: boolean;
+}): Promise<void>;
+/** Roll back artifacts owned by the interrupted operation; never targets user input. */
+export declare function cleanupExecutionArtifact(path: string, options?: {
+    force?: boolean;
+    recursive?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=deadline-io.d.ts.map

package/dist/engine/execution/deadline-io.js

@@ -0,0 +1,45 @@
+import { link, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { assertExecutionCanCommit, getExecutionSignal } from './context.js';
+function operationSignal(signal) {
+    const parent = getExecutionSignal();
+    if (!signal) {
+        return parent;
+    }
+    if (!parent || parent === signal) {
+        return signal;
+    }
+    return AbortSignal.any([parent, signal]);
+}
+/** Fetch under the active request cancellation tree. */
+export function executionFetch(input, init = {}) {
+    const signal = operationSignal(init.signal);
+    signal?.throwIfAborted();
+    return fetch(input, { ...init, ...(signal ? { signal } : {}) });
+}
+/** Create a directory only while the request remains pre-commit and active. */
+export async function executionMkdir(path, options) {
+    assertExecutionCanCommit();
+    return mkdir(path, options);
+}
+/** Exclusive-create helper for idempotency claims; never overwrites an owner. */
+export async function executionWriteFileExclusive(path, content, options = {}) {
+    assertExecutionCanCommit();
+    await writeFile(path, content, { ...options, flag: 'wx' });
+}
+export async function executionRename(source, target) {
+    assertExecutionCanCommit();
+    await rename(source, target);
+}
+export async function executionLink(source, target) {
+    assertExecutionCanCommit();
+    await link(source, target);
+}
+export async function executionRemove(path, options = {}) {
+    assertExecutionCanCommit();
+    await rm(path, options);
+}
+/** Roll back artifacts owned by the interrupted operation; never targets user input. */
+export async function cleanupExecutionArtifact(path, options = {}) {
+    await rm(path, options);
+}
+//# sourceMappingURL=deadline-io.js.map

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

@@ -0,0 +1,4 @@
+import type { DurableJobHeartbeatController, DurableJobHeartbeatRuntimeOptions, DurableJobHeartbeatStartInput } from '../../types/durable-validation.js';
+/** Start one autonomous, fenced heartbeat and wait for its typed ready acknowledgement. */
+export declare function createDurableJobHeartbeat(input: DurableJobHeartbeatStartInput, options?: DurableJobHeartbeatRuntimeOptions): Promise<DurableJobHeartbeatController>;
+//# sourceMappingURL=durable-job-heartbeat-runtime.d.ts.map

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-executor.d.ts

@@ -0,0 +1,16 @@
+import type { DurableJobExecutorOptions } from '../../types/durable-job.js';
+import type { DurableJobRecord } from '../../storage/runtime-db.js';
+/** Claims and executes allowlisted native jobs while preserving lease and cancellation fencing. */
+export declare class DurableJobExecutor {
+    private readonly runtime;
+    private readonly workerId;
+    private readonly leaseMs;
+    private readonly heartbeatMs;
+    private readonly maxConcurrency;
+    private readonly runNative;
+    constructor(options: DurableJobExecutorOptions);
+    /** Execute one bounded batch. Jobs not claimed by this worker remain untouched. */
+    runOnce(projectId: string, workspaceId?: string): Promise<readonly DurableJobRecord[]>;
+    private execute;
+}
+//# sourceMappingURL=job-executor.d.ts.map