@evomap/evolver-core 2.0.0-beta.6 → 2.0.0-beta.8

package/dist/util/fileLock.js

@@ -1,10 +1,12 @@
 import { randomUUID } from 'node:crypto';
-import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { closeSync, constants, existsSync, fstatSync, linkSync, lstatSync, openSync, readSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 export function syncSleep(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+const MALFORMED_LOCK_GRACE_NS = 1000000000n;
 const ownedLocks = new Map();
+const malformedLockObservations = new Map();
 export class LockTimeoutError extends Error {
     code = 'LOCK_TIMEOUT';
     constructor(_lockPath) {
@@ -60,7 +62,7 @@ function currentOwnerStat(path) {
         throw error;
     }
 }
-function readOwnerBounded(path) {
+function readOwnerFileBounded(path) {
     const before = currentOwnerStat(path);
     if (before === null)
         return null;
@@ -95,12 +97,25 @@ function readOwnerBounded(path) {
         }
         if (total > MAX_LOCK_OWNER_BYTES)
             throw new UnsafeLockPathError('owner_too_large');
-        return buffer.subarray(0, total).toString('utf8');
+        const settled = fstatSync(fd, { bigint: true });
+        assertRegularOwnerStat(settled);
+        const settledPath = currentOwnerStat(path);
+        if (settledPath === null
+            || settledPath.dev !== settled.dev
+            || settledPath.ino !== settled.ino
+            || settledPath.size !== settled.size
+            || settledPath.mtimeNs !== settled.mtimeNs) {
+            throw new UnsafeLockPathError('path_changed');
+        }
+        return { raw: buffer.subarray(0, total).toString('utf8'), stat: settled };
     }
     finally {
         closeSync(fd);
     }
 }
+function readOwnerBounded(path) {
+    return readOwnerFileBounded(path)?.raw ?? null;
+}
 /** True if pid is a live process (cross-platform via signal 0; EPERM = exists but owned by another user). */
 function pidAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -147,11 +162,19 @@ function parseOwner(raw) {
         return null;
     return parseJsonOwner(trimmed) ?? parseLegacyOwner(trimmed);
 }
-/** Owner recorded in the lock file; null if missing/unparseable. */
-function lockOwner(lockPath) {
+/** Snapshot of the lock inode and its owner payload; null if the path disappeared. */
+function lockSnapshot(lockPath) {
     try {
-        const raw = readOwnerBounded(lockPath);
-        return raw === null ? null : parseOwner(raw);
+        const read = readOwnerFileBounded(lockPath);
+        if (read === null)
+            return null;
+        return {
+            owner: parseOwner(read.raw),
+            dev: read.stat.dev,
+            ino: read.stat.ino,
+            size: read.stat.size,
+            mtimeNs: read.stat.mtimeNs,
+        };
     }
     catch (error) {
         // A valid owner can release and another waiter can acquire between lstat/open/fstat. Treat that snapshot as
@@ -161,6 +184,31 @@ function lockOwner(lockPath) {
         throw error;
     }
 }
+function sameInode(left, right) {
+    return left !== null && right !== null && left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+    return sameInode(left, right)
+        && left?.size === right?.size
+        && left?.mtimeNs === right?.mtimeNs;
+}
+function forgetMalformedObservation(lockPath) {
+    malformedLockObservations.delete(lockKey(lockPath));
+}
+function reclaimableSnapshot(lockPath, snapshot) {
+    if (snapshot.owner !== null) {
+        forgetMalformedObservation(lockPath);
+        return snapshot.owner.pid !== process.pid && !pidAlive(snapshot.owner.pid);
+    }
+    const key = lockKey(lockPath);
+    const now = process.hrtime.bigint();
+    const observed = malformedLockObservations.get(key);
+    if (observed === undefined || !sameSnapshot(observed.snapshot, snapshot)) {
+        malformedLockObservations.set(key, { snapshot, firstSeenAtNs: now });
+        return false;
+    }
+    return now - observed.firstSeenAtNs >= MALFORMED_LOCK_GRACE_NS;
+}
 function sameOwner(parsed, owner) {
     return parsed?.pid === owner.pid && parsed.token === owner.token;
 }
@@ -179,12 +227,68 @@ function removeFileIfExists(path) {
             throw error;
     }
 }
+function pathExists(path) {
+    return existsSync(path);
+}
+function restoreMovedFile(lockPath, movedPath, moved) {
+    try {
+        linkSync(movedPath, lockPath);
+        removeFileIfExists(movedPath);
+        forgetMalformedObservation(lockPath);
+        return;
+    }
+    catch (error) {
+        if (!isErrno(error, 'EEXIST'))
+            throw error;
+    }
+    const current = lockSnapshot(lockPath);
+    if (sameInode(current, moved)) {
+        removeFileIfExists(movedPath);
+        forgetMalformedObservation(lockPath);
+        return;
+    }
+    throw new Error(`文件锁在安全回收期间被替换，已保留候选文件: ${movedPath}`);
+}
+function removeUnchangedLock(lockPath, expected, kind) {
+    const movedPath = sidecarPath(lockPath, kind);
+    try {
+        renameSync(lockPath, movedPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+    const moved = lockSnapshot(movedPath);
+    if (!sameSnapshot(moved, expected)) {
+        if (moved !== null)
+            restoreMovedFile(lockPath, movedPath, moved);
+        return false;
+    }
+    removeFileIfExists(movedPath);
+    forgetMalformedObservation(lockPath);
+    return true;
+}
+function removeFileIfOwned(lockPath, owner) {
+    const snapshot = lockSnapshot(lockPath);
+    if (snapshot === null || !sameOwner(snapshot.owner, owner))
+        return false;
+    return removeUnchangedLock(lockPath, snapshot, 'released');
+}
 function createLockFile(lockPath, owner, trackOwnership) {
+    const guardPath = mutationGuardPath(lockPath);
+    if (trackOwnership && pathExists(guardPath))
+        return false;
     for (let permissionAttempt = 0; permissionAttempt < 2; permissionAttempt++) {
         try {
             writeFileSync(lockPath, serializeOwner(owner), { flag: 'wx', mode: 0o600 });
+            if (trackOwnership && pathExists(guardPath)) {
+                removeFileIfOwned(lockPath, owner);
+                return false;
+            }
             if (trackOwnership)
                 ownedLocks.set(lockKey(lockPath), { owner, releasePending: false });
+            forgetMalformedObservation(lockPath);
             return true;
         }
         catch (error) {
@@ -210,55 +314,25 @@ function tryAcquireMutationGuard(lockPath) {
     const guard = newOwner();
     if (createLockFile(guardPath, guard, false))
         return guard;
-    const owner = lockOwner(guardPath);
-    if (owner === null || owner.pid === process.pid || pidAlive(owner.pid))
+    const snapshot = lockSnapshot(guardPath);
+    if (snapshot === null || !reclaimableSnapshot(guardPath, snapshot))
+        return null;
+    if (!removeUnchangedLock(guardPath, snapshot, 'stale'))
         return null;
-    const stalePath = sidecarPath(guardPath, 'stale');
-    try {
-        renameSync(guardPath, stalePath);
-    }
-    catch (error) {
-        if (isErrno(error, 'ENOENT'))
-            return null;
-        throw error;
-    }
-    removeFileIfExists(stalePath);
     return createLockFile(guardPath, guard, false) ? guard : null;
 }
 function releaseMutationGuard(lockPath, guard) {
-    const guardPath = mutationGuardPath(lockPath);
-    if (!sameOwner(lockOwner(guardPath), guard))
-        return;
-    const releasedPath = sidecarPath(guardPath, 'released');
-    try {
-        renameSync(guardPath, releasedPath);
-    }
-    catch (error) {
-        if (isErrno(error, 'ENOENT'))
-            return;
-        throw error;
-    }
-    removeFileIfExists(releasedPath);
+    removeFileIfOwned(mutationGuardPath(lockPath), guard);
 }
 function reclaimStaleLock(lockPath) {
     const guard = tryAcquireMutationGuard(lockPath);
     if (guard === null)
         return false;
     try {
-        const owner = lockOwner(lockPath);
-        if (owner === null || owner.pid === process.pid || pidAlive(owner.pid))
+        const snapshot = lockSnapshot(lockPath);
+        if (snapshot === null || !reclaimableSnapshot(lockPath, snapshot))
             return false;
-        const stalePath = sidecarPath(lockPath, 'stale');
-        try {
-            renameSync(lockPath, stalePath);
-        }
-        catch (error) {
-            if (isErrno(error, 'ENOENT'))
-                return false;
-            throw error;
-        }
-        removeFileIfExists(stalePath);
-        return true;
+        return removeUnchangedLock(lockPath, snapshot, 'stale');
     }
     finally {
         releaseMutationGuard(lockPath, guard);
@@ -270,9 +344,11 @@ function reclaimStaleLock(lockPath) {
  * The lock file records the owner pid and token. If a waiter finds the lock held by a pid that is no longer
  * alive (the owner crashed without releaseLock), it reclaims the stale lock instead of spinning
  * until timeout — otherwise one crashed process would deadlock every future writer until the file
- * is removed by hand. Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside
- * under a mutation guard before deletion so waiters cannot delete each other's newly-created locks.
- * A live owner's lock (including this process's own) is never stolen.
+ * is removed by hand. Empty or truncated locks are reclaimed only after the same inode and contents
+ * remain malformed for a grace period, so a live creator can finish publishing its owner payload.
+ * Acquisition stays atomic (O_EXCL), and stale reclaim moves the old lock aside under a mutation
+ * guard, then verifies the inode snapshot before deletion. A live owner's lock (including this
+ * process's own) is never stolen.
  *
  * NOTE: still synchronous (blocks the event loop while waiting) by design — it guards short
  * synchronous critical sections (append-only writes).
@@ -291,12 +367,17 @@ export function acquireLock(lockPath, opts = {}) {
         if (createLockFile(lockPath, owner, true)) {
             return;
         }
-        const current = lockOwner(lockPath);
-        if (current !== null && current.pid !== process.pid && !pidAlive(current.pid)) {
+        const current = lockSnapshot(lockPath);
+        if (current !== null && reclaimableSnapshot(lockPath, current)) {
             if (!reclaimStaleLock(lockPath))
                 syncSleep(waitMs);
             continue;
         }
+        if (current === null && pathExists(mutationGuardPath(lockPath))) {
+            const guard = tryAcquireMutationGuard(lockPath);
+            if (guard !== null)
+                releaseMutationGuard(lockPath, guard);
+        }
         syncSleep(waitMs);
     }
     throw new LockTimeoutError();

package/dist/workflow/dsl.d.ts

@@ -14,13 +14,26 @@ export interface CoreCall {
     fn: string;
     args: Value[];
 }
-export interface ScriptStep {
+export type WorkflowErrorClass = 'transient' | 'permanent' | 'safety' | 'unknown';
+export declare function containsWorkflowSensitiveText(value: string): boolean;
+export interface WorkflowRetryPolicy {
+    maxAttempts: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    multiplier?: number;
+}
+export interface DurableStepOptions {
+    /** Agent steps default to non-idempotent; script steps default to idempotent. */
+    idempotency?: 'idempotent' | 'non_idempotent';
+    retry?: WorkflowRetryPolicy;
+}
+export interface ScriptStep extends DurableStepOptions {
     id: string;
     kind: 'script';
     setOutput: string;
     call: CoreCall;
 }
-export interface AgentStep {
+export interface AgentStep extends DurableStepOptions {
     id: string;
     kind: 'agent';
     prompt: string;
@@ -42,8 +55,16 @@ export interface IfStep {
     then: WorkflowStep[];
     else?: WorkflowStep[];
 }
-export type WorkflowStep = ScriptStep | AgentStep | ForeachStep | IfStep;
+/** Durable human gate. Execution stops before subsequent steps until an operator approves or rejects it. */
+export interface ApprovalStep {
+    id: string;
+    kind: 'approval';
+    label?: string;
+}
+export type WorkflowStep = ScriptStep | AgentStep | ForeachStep | IfStep | ApprovalStep;
 export interface WorkflowSpec {
+    /** Stable caller-supplied identity. If omitted, the durable runtime derives one from the definition. */
+    workflowId?: string;
     name: string;
     input?: Record<string, unknown>;
     steps: WorkflowStep[];

package/dist/workflow/dsl.js

@@ -3,6 +3,10 @@
  * 表达式表示为**结构化对象**(非字符串解析): 引用 Ref + 白名单 core 调用, 安全 by-construction.
  */
 export function isRef(v) { return typeof v === 'object' && v !== null && 'ref' in v; }
+const WORKFLOW_SENSITIVE_TEXT_RE = /(?:\bBearer\s+[A-Za-z0-9._~+/=-]{8,}|\bsk-[A-Za-z0-9_-]{12,}|\b(?:gh[oprsu]|npm)_[A-Za-z0-9_-]{8,}|\bgithub_pat_[A-Za-z0-9_]{8,}|\b(?:AKIA|ASIA)[0-9A-Z]{16}\b|\bAIza[0-9A-Za-z_-]{35}\b|-----BEGIN [A-Z ]*PRIVATE KEY-----|\b(?:password|passwd|secret|token|api[_-]?key|accountkey)\s*[:=]\s*\S+)/i;
+export function containsWorkflowSensitiveText(value) {
+    return WORKFLOW_SENSITIVE_TEXT_RE.test(value);
+}
 export const CORE_WHITELIST = {
     list_len: (a) => (Array.isArray(a) ? a.length : 0),
     filter_by_mask: (items, mask) => (Array.isArray(items) && Array.isArray(mask) ? items.filter((_, i) => Boolean(mask[i])) : []),

package/dist/workflow/engine.d.ts

@@ -4,8 +4,12 @@ export interface WorkflowContext {
     steps: Record<string, unknown>;
     item?: unknown;
 }
+export interface AgentBridgeOptions {
+    /** Cooperative cancellation for the current durable attempt. */
+    signal?: AbortSignal;
+}
 /** agent step 桥(注入 runtime; 孵化期可注 stub). */
-export type AgentBridge = (prompt: string, ctx: WorkflowContext) => Promise<unknown> | unknown;
+export type AgentBridge = (prompt: string, ctx: WorkflowContext, options?: AgentBridgeOptions) => Promise<unknown> | unknown;
 export interface WorkflowEngineDeps {
     core?: Record<string, CoreFn>;
     agent: AgentBridge;

package/dist/workflow/engine.js

@@ -68,6 +68,9 @@ export class WorkflowEngine {
                 await this.runSteps(branch, ctx);
                 return;
             }
+            case 'approval': {
+                throw new WorkflowError('approval steps require DurableWorkflowRuntime');
+            }
             case 'foreach': {
                 const items = resolveRef(step.over.ref, ctx);
                 if (!Array.isArray(items))

package/dist/workflow/index.d.ts

@@ -1,2 +1,4 @@
 export * from './dsl.js';
-export * from './engine.js';
+export * from './engine.js';
+export * from './stateStore.js';
+export * from './runtime.js';

package/dist/workflow/index.js

@@ -1,2 +1,4 @@
 export * from './dsl.js';
-export * from './engine.js';
+export * from './engine.js';
+export * from './stateStore.js';
+export * from './runtime.js';

package/dist/workflow/runtime.d.ts

@@ -0,0 +1,110 @@
+import { type CoreFn, type WorkflowErrorClass, type WorkflowSpec } from './dsl.js';
+import type { AgentBridge, WorkflowContext } from './engine.js';
+import { WorkflowStateError, WorkflowStateStore, type WorkflowControlState, type WorkflowOperatorOptions, type WorkflowRunState, type WorkflowStateStoreOptions, type WorkflowStepState } from './stateStore.js';
+export declare const MAX_WORKFLOW_DEFINITION_STEPS = 256;
+export declare const MAX_WORKFLOW_NESTING_DEPTH = 16;
+export declare const MAX_WORKFLOW_FOREACH_ITEMS = 1000;
+export interface WorkflowRuntimeDeps {
+    agent: AgentBridge;
+    stateDir?: string;
+    core?: Record<string, CoreFn>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    classifyError?: (error: unknown) => WorkflowErrorClass;
+    generateRunId?: () => string;
+    maxConcurrentRuns?: number;
+    maxQueuedRuns?: number;
+    maxStepExecutions?: number;
+    /** Test/embedding seam invoked only after a durable checkpoint has completed. */
+    afterCheckpoint?: (state: Readonly<WorkflowRunState>) => void | Promise<void>;
+    /** Synchronous fault-injection seam invoked under the commit lock; callbacks must not re-enter the store. */
+    onTransactionPhase?: WorkflowStateStoreOptions['onTransactionPhase'];
+    /** Bounded startup-recovery diagnostic; raw errors are never exposed. */
+    onRecoveryFailure?: (failure: WorkflowRecoveryFailure) => void;
+    lock?: {
+        maxTries?: number;
+        waitMs?: number;
+    };
+}
+export interface WorkflowRecoveryFailure {
+    runId: string;
+    code: WorkflowStateError['code'] | 'RUN_FAILED' | 'RECOVERY_FAILED';
+}
+export interface WorkflowRunResult {
+    runId: string;
+    workflowId: string;
+    status: WorkflowRunState['status'];
+    output: unknown;
+    ctx: WorkflowContext;
+}
+export declare class WorkflowRuntimeError extends Error {
+    readonly code: 'SENSITIVE_STATE' | 'INVALID_STATE' | 'UNSUPPORTED_PARALLELISM' | 'RUN_NOT_RESUMABLE' | 'INVALID_RETRY' | 'INVALID_CONCURRENCY' | 'RESOURCE_LIMIT';
+    constructor(message: string, code: 'SENSITIVE_STATE' | 'INVALID_STATE' | 'UNSUPPORTED_PARALLELISM' | 'RUN_NOT_RESUMABLE' | 'INVALID_RETRY' | 'INVALID_CONCURRENCY' | 'RESOURCE_LIMIT');
+}
+export declare class WorkflowRunFailedError extends Error {
+    readonly runId: string;
+    readonly status: 'failed' | 'unsafe_to_resume';
+    readonly errorClass: WorkflowStepState['lastErrorClass'];
+    constructor(runId: string, status: 'failed' | 'unsafe_to_resume', errorClass: WorkflowStepState['lastErrorClass']);
+}
+export declare class ClassifiedWorkflowError extends Error {
+    readonly errorClass: WorkflowErrorClass;
+    constructor(errorClass: WorkflowErrorClass, message?: string);
+}
+export declare function defaultWorkflowStateDir(): string;
+export declare function deriveWorkflowId(spec: WorkflowSpec): string;
+export declare function assertValidWorkflowSpec(value: unknown): asserts value is WorkflowSpec;
+export declare class DurableWorkflowRuntime {
+    private readonly deps;
+    readonly store: WorkflowStateStore;
+    private readonly core;
+    private readonly now;
+    private readonly sleep;
+    private readonly classifyError;
+    private readonly generateRunId;
+    private readonly scheduler;
+    private readonly maxConcurrentRuns;
+    private readonly maxStepExecutions;
+    private readonly inFlight;
+    constructor(deps: WorkflowRuntimeDeps);
+    start(spec: WorkflowSpec, options?: {
+        runId?: string;
+    } | string): Promise<WorkflowRunResult>;
+    resume(runId: string, options?: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    operatorResume(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    pause(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    cancel(runId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    approve(runId: string, gateId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    reject(runId: string, gateId: string, options: WorkflowOperatorOptions): Promise<WorkflowRunResult>;
+    status(runId: string): WorkflowRunState;
+    history(runId: string): ReturnType<WorkflowStateStore['readHistory']>;
+    recoverPending(): Promise<WorkflowRunResult[]>;
+    protected isRecoveryCandidate(state: WorkflowRunState, control: WorkflowControlState): boolean;
+    protected recoverRuns(shouldRecover: (runId: string) => boolean | Promise<boolean>, reportFailure: (runId: string, error: unknown) => void): Promise<WorkflowRunResult[]>;
+    private scheduleRecoveryRun;
+    private scheduleRun;
+    private resumeLocked;
+    private withLockedRun;
+    private withConcurrencySlot;
+    private validateResumeStateOrFail;
+    private execute;
+    private runSteps;
+    private runStep;
+    private lastStepOutput;
+    private failState;
+    private runApproval;
+    private runLeaf;
+    private runAgentAttempt;
+    private observeCancellation;
+    private checkpointCompletion;
+    private enforceControlBoundary;
+    private finalizeCancellation;
+    private checkpoint;
+    private safetyCheckpoint;
+    private ensureApprovalDecisionHistory;
+    private appendHistoryUnlessUnavailable;
+    private historyEvent;
+    private timestamp;
+    private result;
+    private reportRecoveryFailure;
+}