taskflow-core 0.2.0 → 0.2.1

package/dist/resources/permits.js

@@ -0,0 +1,240 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { PersistentFileMutex, readJsonFile, writeJsonAtomicDurable, } from "./persistence.js";
+import { cloneExecutionOwner, minimalCanonicalScopeCover, sameCanonicalScopes, sameExecutionOwner, } from "./types.js";
+export class PermitValidationError extends Error {
+    code = "TFWS_PERMIT_INVALID";
+    constructor(message) {
+        super(message);
+        this.name = "PermitValidationError";
+    }
+}
+const BRANDED_PERMITS = new WeakSet();
+/** Runtime-only brand check for SandboxPlan sealing. Serialized/reconstructed
+ * lookalikes deliberately fail even when every public field is identical. */
+export function isIssuedMutationPermit(value) {
+    return typeof value === "object" && value !== null && BRANDED_PERMITS.has(value);
+}
+function freezeOwner(owner) {
+    const cloned = cloneExecutionOwner(owner);
+    Object.freeze(cloned.ancestry);
+    return Object.freeze(cloned);
+}
+function freezeScopes(scopes) {
+    return Object.freeze(minimalCanonicalScopeCover(scopes).map((scope) => Object.freeze({ ...scope })));
+}
+function mintPermit(record) {
+    const permit = Object.freeze({
+        permitId: record.permitId,
+        intentId: record.intentId,
+        journalEpoch: record.journalEpoch,
+        owner: freezeOwner(record.owner),
+        issuedAt: record.issuedAt,
+        expiresAt: record.expiresAt,
+        nonce: record.nonce,
+        scopes: freezeScopes(record.scopes),
+    });
+    BRANDED_PERMITS.add(permit);
+    return permit;
+}
+function samePendingIntent(a, b) {
+    return a.intentId === b.intentId &&
+        a.intentSequence === b.intentSequence &&
+        a.journalEpoch === b.journalEpoch &&
+        sameExecutionOwner(a.owner, b.owner) &&
+        sameCanonicalScopes(a.scopes, b.scopes);
+}
+function samePermitRecord(permit, record) {
+    return permit.permitId === record.permitId &&
+        permit.intentId === record.intentId &&
+        permit.journalEpoch === record.journalEpoch &&
+        permit.nonce === record.nonce &&
+        permit.issuedAt === record.issuedAt &&
+        permit.expiresAt === record.expiresAt &&
+        sameExecutionOwner(permit.owner, record.owner) &&
+        sameCanonicalScopes(permit.scopes, record.scopes);
+}
+export class MutationPermitRegistry {
+    statePath;
+    journalEpoch;
+    now;
+    #mutex;
+    constructor(options) {
+        if (!Number.isSafeInteger(options.journalEpoch) || options.journalEpoch < 1) {
+            throw new Error("journalEpoch must be a positive safe integer");
+        }
+        this.journalEpoch = options.journalEpoch;
+        this.statePath = path.join(options.directory, "mutation-permits.json");
+        this.now = options.now ?? Date.now;
+        this.#mutex = new PersistentFileMutex(path.join(options.directory, "mutation-permits.lock"), options);
+    }
+    #read() {
+        const state = readJsonFile(this.statePath, { version: 1, records: [] });
+        if (state.version !== 1 || !Array.isArray(state.records))
+            throw new Error(`Invalid permit registry: ${this.statePath}`);
+        return state;
+    }
+    #expire(state) {
+        let changed = false;
+        const now = this.now();
+        for (const record of state.records) {
+            // expiresAt bounds the prepare-to-activate replay window. Once activated,
+            // an execution may legitimately outlive that window; its live lease and
+            // the journal's crash recovery own termination from that point forward.
+            // Expiring an active permit here would turn every long-running successful
+            // agent into dirty-unknown when it attempts to commit.
+            if (record.state === "issued" && Date.parse(record.expiresAt) <= now) {
+                record.state = "expired";
+                record.settledAt = new Date(now).toISOString();
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    /** Internal durability-plane hook. Call only after the matching intent WAL
+     * record has been appended and fsynced. JournalManager is the public issuer. */
+    async issueForDurableIntent(intent, ttlMs) {
+        if (intent.journalEpoch !== this.journalEpoch)
+            throw new PermitValidationError("Journal epoch does not match permit registry epoch");
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0)
+            throw new Error("Permit ttlMs must be positive");
+        const scopes = minimalCanonicalScopeCover(intent.scopes);
+        if (scopes.length === 0)
+            throw new PermitValidationError("A mutation permit requires at least one scope");
+        return this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            const changed = this.#expire(state);
+            if (state.records.some((record) => record.intentId === intent.intentId && (record.state === "issued" || record.state === "active"))) {
+                throw new PermitValidationError(`Intent ${intent.intentId} already has a live permit`);
+            }
+            const issuedAtMs = this.now();
+            const record = {
+                intentId: intent.intentId,
+                intentSequence: intent.intentSequence,
+                journalEpoch: intent.journalEpoch,
+                owner: cloneExecutionOwner(intent.owner),
+                scopes,
+                permitId: crypto.randomUUID(),
+                nonce: crypto.randomBytes(24).toString("base64url"),
+                issuedAt: new Date(issuedAtMs).toISOString(),
+                expiresAt: new Date(issuedAtMs + ttlMs).toISOString(),
+                state: "issued",
+            };
+            state.records.push(record);
+            writeJsonAtomicDurable(this.statePath, state);
+            void changed;
+            return mintPermit(record);
+        });
+    }
+    /** Atomically activate every permit in a sealed execution plan exactly once. */
+    async activateMany(permits, activation) {
+        if (permits.length === 0)
+            throw new PermitValidationError("No permits supplied for activation");
+        await this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            const expired = this.#expire(state);
+            if (expired)
+                writeJsonAtomicDurable(this.statePath, state);
+            const seen = new Set();
+            const records = [];
+            for (const permit of permits) {
+                if (!isIssuedMutationPermit(permit)) {
+                    throw new PermitValidationError("Unbranded or reconstructed mutation permit");
+                }
+                if (seen.has(permit.permitId))
+                    throw new PermitValidationError(`Duplicate permit ${permit.permitId}`);
+                seen.add(permit.permitId);
+                const record = state.records.find((candidate) => candidate.permitId === permit.permitId);
+                if (!record || !samePermitRecord(permit, record))
+                    throw new PermitValidationError(`Permit ${permit.permitId} does not match its registry record`);
+                if (record.state !== "issued")
+                    throw new PermitValidationError(`Permit ${permit.permitId} is ${record.state}; activation replay rejected`);
+                if (record.journalEpoch !== this.journalEpoch)
+                    throw new PermitValidationError(`Permit ${permit.permitId} belongs to an obsolete journal epoch`);
+                if (!sameExecutionOwner(record.owner, activation.owner))
+                    throw new PermitValidationError(`Permit ${permit.permitId} owner mismatch`);
+                const pending = activation.pendingIntents.find((candidate) => candidate.intentId === record.intentId);
+                if (!pending || !samePendingIntent(record, pending))
+                    throw new PermitValidationError(`Permit ${permit.permitId} has no identical pending journal intent`);
+                records.push(record);
+            }
+            const activatedAt = new Date(this.now()).toISOString();
+            for (const record of records) {
+                record.state = "active";
+                record.activatedAt = activatedAt;
+            }
+            if (records.length > 0)
+                writeJsonAtomicDurable(this.statePath, state);
+        });
+    }
+    async assertIntentActive(intentId, owner) {
+        await this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            if (this.#expire(state))
+                writeJsonAtomicDurable(this.statePath, state);
+            const active = state.records.find((record) => record.intentId === intentId && record.state === "active");
+            if (!active)
+                throw new PermitValidationError(`Intent ${intentId} has no active mutation permit`);
+            if (!sameExecutionOwner(active.owner, owner))
+                throw new PermitValidationError(`Intent ${intentId} active permit owner mismatch`);
+        });
+    }
+    async assertActive(permit, owner) {
+        await this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            const expired = this.#expire(state);
+            if (expired)
+                writeJsonAtomicDurable(this.statePath, state);
+            if (!isIssuedMutationPermit(permit))
+                throw new PermitValidationError("Unbranded mutation permit");
+            const record = state.records.find((candidate) => candidate.permitId === permit.permitId);
+            if (!record || !samePermitRecord(permit, record) || record.state !== "active") {
+                throw new PermitValidationError(`Permit ${permit.permitId} is not active`);
+            }
+            if (!sameExecutionOwner(record.owner, owner))
+                throw new PermitValidationError(`Permit ${permit.permitId} owner mismatch`);
+        });
+    }
+    async settleIntent(intentId) {
+        await this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            let changed = this.#expire(state);
+            const settledAt = new Date(this.now()).toISOString();
+            for (const record of state.records) {
+                if (record.intentId !== intentId || (record.state !== "issued" && record.state !== "active"))
+                    continue;
+                record.state = "settled";
+                record.settledAt = settledAt;
+                changed = true;
+            }
+            if (changed)
+                writeJsonAtomicDurable(this.statePath, state);
+        });
+    }
+    async stateOf(permitId) {
+        return this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            if (this.#expire(state))
+                writeJsonAtomicDurable(this.statePath, state);
+            return state.records.find((record) => record.permitId === permitId)?.state;
+        });
+    }
+    async invalidateOlderEpochs() {
+        return this.#mutex.runExclusive(() => {
+            const state = this.#read();
+            let count = 0;
+            const settledAt = new Date(this.now()).toISOString();
+            for (const record of state.records) {
+                if (record.journalEpoch === this.journalEpoch || (record.state !== "issued" && record.state !== "active"))
+                    continue;
+                record.state = "expired";
+                record.settledAt = settledAt;
+                count++;
+            }
+            if (count > 0)
+                writeJsonAtomicDurable(this.statePath, state);
+            return count;
+        });
+    }
+}
+//# sourceMappingURL=permits.js.map

package/dist/resources/permits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permits.js","sourceRoot":"","sources":["../../src/resources/permits.ts"],"names":[],"mappings":"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"}

package/dist/resources/persistence.d.ts

@@ -0,0 +1,63 @@
+/** Exact, platform-native process-birth identity when the platform exposes one.
+ * Never return an uptime estimate or a lower-precision timestamp: incomparable
+ * identities could falsely reclaim a live owner's lock. */
+export declare function readProcessBirthToken(pid: number): string | undefined;
+export type ProcessBirthTokenKind = "native" | "opaque";
+export interface ProcessIdentity {
+    pid: number;
+    birthToken: string;
+    birthTokenKind: ProcessBirthTokenKind;
+}
+export interface ObservedProcess {
+    alive: boolean;
+    /** Omitted when exact cross-process birth identity is unavailable. Alive but
+     * unidentifiable owners are never reclaimed. */
+    birthToken?: string;
+    birthTokenKind?: ProcessBirthTokenKind;
+}
+export type ProcessInspector = (pid: number) => ObservedProcess;
+export interface PersistentCoordinatorOptions {
+    directory: string;
+    namespace?: string;
+    pollMs?: number;
+    /** A malformed mutex file is recoverable only after this grace period. */
+    corruptLockStaleMs?: number;
+    processIdentity?: ProcessIdentity;
+    inspectProcess?: ProcessInspector;
+    now?: () => number;
+}
+export declare class CoordinatorTimeoutError extends Error {
+    readonly code = "TFWS_LEASE_TIMEOUT";
+    constructor(message: string);
+}
+export declare class CoordinatorAbortError extends Error {
+    readonly code = "ABORT_ERR";
+    constructor(message?: string);
+}
+export declare function defaultProcessIdentity(): ProcessIdentity;
+export declare function defaultProcessInspector(pid: number): ObservedProcess;
+export declare function namespaceToken(namespace: string): string;
+export declare function ensureDirectory(directory: string): void;
+export declare function fsyncDirectory(directory: string): void;
+export declare function writeJsonAtomicDurable(filePath: string, value: unknown): void;
+export declare function readJsonFile<T>(filePath: string, fallback: T): T;
+export declare function appendJsonLinesDurable(filePath: string, records: readonly unknown[]): void;
+export declare function readJsonLines<T>(filePath: string): T[];
+export interface MutexAcquireOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare class PersistentFileMutex {
+    #private;
+    readonly lockPath: string;
+    readonly identity: ProcessIdentity;
+    readonly inspectProcess: ProcessInspector;
+    readonly pollMs: number;
+    readonly corruptLockStaleMs: number;
+    readonly now: () => number;
+    constructor(lockPath: string, options?: Omit<PersistentCoordinatorOptions, "directory">);
+    acquire(options?: MutexAcquireOptions): Promise<() => void>;
+    runExclusive<T>(fn: () => T | Promise<T>, options?: MutexAcquireOptions): Promise<T>;
+}
+export declare function isPersistedOwnerStale(record: ProcessIdentity, identity: ProcessIdentity, inspect: ProcessInspector): boolean;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/resources/persistence.d.ts.map

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