codex-workflow-v2 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/src/state/lock.js

@@ -1,21 +1,30 @@
-import { closeSync, existsSync, openSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { STATE_SCHEMA_VERSION } from '../contracts.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { STATE_SCHEMA_VERSION, } from '../contracts.js';
 import { WorkflowError } from '../errors.js';
-import { ensureDirectory, readJson, writeJsonAtomic } from '../fs-utils.js';
+import { ensureDirectory, writeJsonAtomic } from '../fs-utils.js';
 const DEFAULT_LEASE_MS = 30 * 60 * 1000;
+const LOCK_ENTITY_PATTERN = /^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}$/;
+const LOCK_FILE_PATTERN = /^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}\.json$/;
+const coreHandles = new WeakMap();
+const writerHandles = new WeakMap();
 export class WriterLockManager {
     locksRoot;
     now;
-    constructor(locksRoot, now = () => new Date()) {
+    trustedRoot;
+    constructor(locksRoot, now = () => new Date(), trustedRoot) {
         this.locksRoot = locksRoot;
         this.now = now;
+        this.trustedRoot = trustedRoot;
+        assertLockRootPath(locksRoot, trustedRoot);
         ensureDirectory(locksRoot);
+        assertLockRootPath(locksRoot, trustedRoot);
     }
     acquire(entityId, owner, leaseMs = DEFAULT_LEASE_MS) {
         const file = this.file(entityId);
+        assertLockRootPath(this.locksRoot, this.trustedRoot);
         const timestamp = this.now();
         const lease = {
             schemaVersion: STATE_SCHEMA_VERSION,
@@ -28,79 +37,622 @@ export class WriterLockManager {
             heartbeatAt: timestamp.toISOString(),
             expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
         };
+        let descriptor = null;
         try {
-            const descriptor = openSync(file, 'wx', 0o600);
+            descriptor = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
             writeFileSync(descriptor, `${JSON.stringify(lease, null, 2)}\n`, 'utf8');
             closeSync(descriptor);
+            descriptor = null;
             return lease;
         }
         catch (error) {
-            if (existsSync(file)) {
-                const current = readJson(file);
+            if (descriptor !== null)
+                closeSync(descriptor);
+            if (lstatIfPresent(file)) {
+                const snapshot = readLockSnapshot(this.locksRoot, entityId, this.trustedRoot);
+                if (isCoreTaskOperationMutex(snapshot.record)) {
+                    throw new WorkflowError('LOCKED', `${entityId} already has a Core Task operation`, {
+                        owner: snapshot.record.owner,
+                        operationId: snapshot.record.operationId,
+                        transitionId: snapshot.record.transitionId,
+                        expiresAt: snapshot.record.expiresAt,
+                        stale: lockExpiry(snapshot.record, file) <= timestamp.getTime(),
+                    });
+                }
+                const current = snapshot.record;
                 throw new WorkflowError('LOCKED', `${entityId} already has a writer`, {
                     owner: current.owner,
                     pid: current.pid,
                     hostname: current.hostname,
                     heartbeatAt: current.heartbeatAt,
                     expiresAt: current.expiresAt,
-                    stale: Date.parse(current.expiresAt) <= timestamp.getTime(),
+                    stale: leaseExpiry(current, file) <= timestamp.getTime(),
                 });
             }
             throw error;
         }
     }
     heartbeat(entityId, token, leaseMs = DEFAULT_LEASE_MS) {
-        const current = this.requireToken(entityId, token);
         const timestamp = this.now();
+        const current = this.requireConsumableToken(entityId, token, timestamp);
         const updated = {
-            ...current,
+            ...current.lease,
             heartbeatAt: timestamp.toISOString(),
             expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
         };
+        assertSameLeaseIdentity(this.file(entityId), current.identity);
         writeJsonAtomic(this.file(entityId), updated);
         return updated;
     }
     release(entityId, token) {
-        this.requireToken(entityId, token);
-        unlinkSync(this.file(entityId));
+        const current = this.requireConsumableToken(entityId, token, this.now());
+        const file = this.file(entityId);
+        assertSameLeaseIdentity(file, current.identity);
+        unlinkSync(file);
+    }
+    prove(entityId, token) {
+        const snapshot = this.requireConsumableToken(entityId, token, this.now());
+        const handle = Object.freeze(Object.create(null));
+        writerHandles.set(handle, {
+            locksRoot: path.resolve(this.locksRoot),
+            ...(this.trustedRoot === undefined ? {} : { trustedRoot: path.resolve(this.trustedRoot) }),
+            snapshot,
+        });
+        return handle;
+    }
+    proofBinding(handle) {
+        const snapshot = assertWriterLeaseHandle(this.locksRoot, this.trustedRoot, handle, this.now());
+        return Object.freeze({
+            entityId: snapshot.lease.entityId,
+            owner: snapshot.lease.owner,
+            expiresAt: snapshot.lease.expiresAt,
+            tokenSha256: createHash('sha256').update(snapshot.lease.token).digest('hex'),
+            contentSha256: createHash('sha256').update(snapshot.content).digest('hex'),
+        });
     }
     inspect(entityId) {
-        const file = this.file(entityId);
-        return existsSync(file) ? readJson(file) : null;
+        return inspectWriterLease(this.locksRoot, entityId, this.trustedRoot);
     }
     list() {
-        return readdirSync(this.locksRoot, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && /^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}\.json$/.test(entry.name))
-            .map((entry) => readJson(path.join(this.locksRoot, entry.name)))
-            .sort((left, right) => left.entityId.localeCompare(right.entityId));
+        return listWriterLeases(this.locksRoot, this.trustedRoot);
     }
     repairStale(entityId) {
         const file = this.file(entityId);
-        if (!existsSync(file))
+        const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
+        if (!current)
             throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
-        const current = readJson(file);
-        if (Date.parse(current.expiresAt) > this.now().getTime()) {
+        const expiresAt = leaseExpiry(current.lease, file);
+        if (expiresAt > this.now().getTime()) {
             throw new WorkflowError('TRANSITION_BLOCKED', `Writer lock is not stale for ${entityId}`, {
-                expiresAt: current.expiresAt,
+                expiresAt: current.lease.expiresAt,
             });
         }
+        assertSameLeaseIdentity(file, current.identity);
         unlinkSync(file);
-        return current;
+        return current.lease;
     }
-    requireToken(entityId, token) {
-        const current = this.inspect(entityId);
+    requireConsumableToken(entityId, token, now) {
+        const current = readLeaseSnapshotOrNull(this.locksRoot, entityId, this.trustedRoot);
         if (!current)
             throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
-        if (current.token !== token) {
+        if (current.lease.token !== token) {
             throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer token does not own ${entityId}`);
         }
+        if (leaseExpiry(current.lease, this.file(entityId)) <= now.getTime()) {
+            throw new WorkflowError('TRANSITION_BLOCKED', `Writer lock has expired for ${entityId}; explicit stale-lock repair is required.`, {
+                entityId,
+                expiresAt: current.lease.expiresAt,
+                requiredAction: 'locks repair',
+            });
+        }
         return current;
     }
     file(entityId) {
-        if (!/^(TASK|MS)-[0-9A-HJKMNP-TV-Z]{26}$/.test(entityId)) {
-            throw new WorkflowError('INVALID_ARGUMENT', `Invalid lock entity: ${entityId}`);
-        }
+        assertLockEntity(entityId);
         return path.join(this.locksRoot, `${entityId}.json`);
     }
 }
+export function listWriterLeases(locksRoot, trustedRoot) {
+    if (!lstatIfPresent(locksRoot))
+        return [];
+    assertLockRootPath(locksRoot, trustedRoot);
+    return readdirSync(locksRoot, { withFileTypes: true })
+        .filter((entry) => LOCK_FILE_PATTERN.test(entry.name))
+        .flatMap((entry) => {
+        const snapshot = readLockSnapshot(locksRoot, entry.name.slice(0, -'.json'.length), trustedRoot);
+        return isCoreTaskOperationMutex(snapshot.record) ? [] : [snapshot.record];
+    })
+        .sort((left, right) => left.entityId.localeCompare(right.entityId));
+}
+export function inspectWriterLease(locksRoot, entityId, trustedRoot) {
+    assertLockEntity(entityId);
+    if (!lstatIfPresent(locksRoot))
+        return null;
+    const file = path.join(locksRoot, `${entityId}.json`);
+    if (!lstatIfPresent(file))
+        return null;
+    const record = readLockSnapshot(locksRoot, entityId, trustedRoot).record;
+    return isCoreTaskOperationMutex(record) ? null : record;
+}
+export function listCoreTaskOperationMutexes(locksRoot, trustedRoot) {
+    if (!lstatIfPresent(locksRoot))
+        return [];
+    assertLockRootPath(locksRoot, trustedRoot);
+    return readdirSync(locksRoot, { withFileTypes: true })
+        .filter((entry) => LOCK_FILE_PATTERN.test(entry.name))
+        .flatMap((entry) => {
+        const record = readLockSnapshot(locksRoot, entry.name.slice(0, -'.json'.length), trustedRoot).record;
+        return isCoreTaskOperationMutex(record) ? [record] : [];
+    })
+        .sort((left, right) => left.entityId.localeCompare(right.entityId));
+}
+export function toPublicWriterLease(lease, now) {
+    const expiresAt = leaseExpiry(lease, '<writer-lease>');
+    return {
+        schemaVersion: lease.schemaVersion,
+        entityId: lease.entityId,
+        owner: lease.owner,
+        pid: lease.pid,
+        hostname: lease.hostname,
+        acquiredAt: lease.acquiredAt,
+        heartbeatAt: lease.heartbeatAt,
+        expiresAt: lease.expiresAt,
+        stale: expiresAt <= now.getTime(),
+    };
+}
+function readLeaseSnapshotOrNull(locksRoot, entityId, trustedRoot) {
+    assertLockEntity(entityId);
+    if (!lstatIfPresent(locksRoot))
+        return null;
+    assertLockRootPath(locksRoot, trustedRoot);
+    const file = path.join(locksRoot, `${entityId}.json`);
+    if (!lstatIfPresent(file))
+        return null;
+    return readLeaseSnapshot(locksRoot, entityId, trustedRoot);
+}
+function readLeaseSnapshot(locksRoot, entityId, trustedRoot) {
+    const snapshot = readLockSnapshot(locksRoot, entityId, trustedRoot);
+    if (isCoreTaskOperationMutex(snapshot.record)) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer token does not own ${entityId}`);
+    }
+    return { lease: snapshot.record, identity: snapshot.identity, content: snapshot.content };
+}
+function readLockSnapshot(locksRoot, entityId, trustedRoot) {
+    assertLockEntity(entityId);
+    assertLockRootPath(locksRoot, trustedRoot);
+    const file = path.join(locksRoot, `${entityId}.json`);
+    const boundary = trustedBoundary(locksRoot, trustedRoot);
+    assertNoSymlinkBelowBoundary(file, boundary, 'Writer lease path');
+    const before = lstatIfPresent(file);
+    if (!before)
+        throw new WorkflowError('NOT_FOUND', `No writer lock for ${entityId}`);
+    if (before.isSymbolicLink() || !before.isFile()) {
+        throw new WorkflowError('STATE_CORRUPT', `Writer lease must be a regular file: ${file}`);
+    }
+    let descriptor = null;
+    try {
+        descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const opened = fstatSync(descriptor);
+        if (!sameIdentity(before, opened) || !opened.isFile()) {
+            throw new WorkflowError('STATE_CONFLICT', `Writer lease changed while opening: ${file}`);
+        }
+        const content = readFileSync(descriptor, 'utf8');
+        let record;
+        try {
+            record = JSON.parse(content);
+        }
+        catch (error) {
+            throw new WorkflowError('STATE_CORRUPT', `Cannot read JSON state: ${file}`, {
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        validateLockRecord(record, entityId, file);
+        const after = lstatIfPresent(file);
+        if (!after || !sameIdentity(opened, after)) {
+            throw new WorkflowError('STATE_CONFLICT', `Writer lease changed while reading: ${file}`);
+        }
+        return { record, identity: { dev: opened.dev, ino: opened.ino }, content };
+    }
+    finally {
+        if (descriptor !== null)
+            closeSync(descriptor);
+    }
+}
+export class CoreTaskOperationLockManager {
+    locksRoot;
+    now;
+    trustedRoot;
+    constructor(locksRoot, now = () => new Date(), trustedRoot) {
+        this.locksRoot = locksRoot;
+        this.now = now;
+        this.trustedRoot = trustedRoot;
+        assertLockRootPath(locksRoot, trustedRoot);
+        ensureDirectory(locksRoot);
+        assertLockRootPath(locksRoot, trustedRoot);
+    }
+    acquire(input) {
+        assertLockEntity(input.entityId);
+        if (!input.entityId.startsWith('TASK-')) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Core corrective-replan operations require a Task entity.');
+        }
+        if (!/^[a-f0-9]{64}$/.test(input.operationId)) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation id must be lowercase SHA-256.');
+        }
+        if (!isSupportedCoreTaskTransition(input.transitionId)) {
+            throw new WorkflowError('INVALID_ARGUMENT', `Unsupported Core Task transition: ${input.transitionId}`);
+        }
+        const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+        if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation lease must be between 1 ms and 30 minutes.');
+        }
+        const timestamp = this.now();
+        const nonce = randomUUID();
+        const mutex = {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            kind: 'core-task-operation-mutex',
+            entityId: input.entityId,
+            operationId: input.operationId,
+            transitionId: input.transitionId,
+            mutexId: randomUUID(),
+            nonceSha256: createHash('sha256').update(nonce).digest('hex'),
+            owner: 'workflow-core',
+            acquiredAt: timestamp.toISOString(),
+            expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+        };
+        const file = path.join(this.locksRoot, `${input.entityId}.json`);
+        let descriptor = null;
+        try {
+            descriptor = openSync(file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            writeFileSync(descriptor, `${JSON.stringify(mutex, null, 2)}\n`, 'utf8');
+            closeSync(descriptor);
+            descriptor = null;
+        }
+        catch (error) {
+            if (descriptor !== null)
+                closeSync(descriptor);
+            if (lstatIfPresent(file)) {
+                const current = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot).record;
+                throw new WorkflowError('LOCKED', `${input.entityId} already has a Task operation owner`, {
+                    owner: isCoreTaskOperationMutex(current) ? current.owner : current.owner,
+                    ...(isCoreTaskOperationMutex(current) ? {
+                        operationId: current.operationId,
+                        transitionId: current.transitionId,
+                    } : {}),
+                    expiresAt: current.expiresAt,
+                    stale: lockExpiry(current, file) <= timestamp.getTime(),
+                });
+            }
+            throw error;
+        }
+        return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+    }
+    acquireForRecovery(input) {
+        assertLockEntity(input.entityId);
+        if (!input.entityId.startsWith('TASK-')
+            || !/^[a-f0-9]{64}$/.test(input.operationId)
+            || !isSupportedCoreTaskTransition(input.transitionId)) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Invalid Core Task recovery operation identity.');
+        }
+        const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+        if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Core Task recovery lease must be between 1 ms and 30 minutes.');
+        }
+        const file = path.join(this.locksRoot, `${input.entityId}.json`);
+        if (!lstatIfPresent(file))
+            return this.acquire(input);
+        const now = this.now();
+        const snapshot = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot);
+        if (!isCoreTaskOperationMutex(snapshot.record)
+            || snapshot.record.operationId !== input.operationId
+            || snapshot.record.transitionId !== input.transitionId) {
+            throw new WorkflowError('LOCKED', `${input.entityId} is owned by another Task operation.`, {
+                expiresAt: snapshot.record.expiresAt,
+            });
+        }
+        if (lockExpiry(snapshot.record, file) > now.getTime()) {
+            throw new WorkflowError('LOCKED', `${input.entityId} still has an active Core Task operation.`, {
+                operationId: snapshot.record.operationId,
+                expiresAt: snapshot.record.expiresAt,
+            });
+        }
+        assertSameLeaseIdentity(file, snapshot.identity);
+        unlinkSync(file);
+        return this.acquire(input);
+    }
+    transferFromWriter(writerHandle, input) {
+        const writer = assertWriterLeaseHandle(this.locksRoot, this.trustedRoot, writerHandle, this.now());
+        if (writer.lease.entityId !== input.entityId) {
+            throw new WorkflowError('LOCK_TOKEN_INVALID', `Writer lease does not own ${input.entityId}`);
+        }
+        const mutex = this.materializeMutex(input);
+        const file = path.join(this.locksRoot, `${input.entityId}.json`);
+        assertSameLeaseIdentity(file, writer.identity);
+        writeJsonAtomic(file, mutex);
+        writerHandles.delete(writerHandle);
+        return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+    }
+    acquireYieldRecovery(input) {
+        assertHash64(input.expectedWriterContentSha256, 'Expected writer lease content hash');
+        assertHash64(input.expectedWriterTokenSha256, 'Expected writer lease token hash');
+        const file = path.join(this.locksRoot, `${input.entityId}.json`);
+        if (!lstatIfPresent(file))
+            return this.acquire(input);
+        const snapshot = readLockSnapshot(this.locksRoot, input.entityId, this.trustedRoot);
+        if (isCoreTaskOperationMutex(snapshot.record))
+            return this.acquireForRecovery(input);
+        const now = this.now();
+        if (leaseExpiry(snapshot.record, file) > now.getTime()) {
+            throw new WorkflowError('LOCKED', `${input.entityId} still has an active writer lease.`);
+        }
+        if (createHash('sha256').update(snapshot.content).digest('hex') !== input.expectedWriterContentSha256
+            || createHash('sha256').update(snapshot.record.token).digest('hex') !== input.expectedWriterTokenSha256) {
+            throw new WorkflowError('STATE_CONFLICT', 'Stale writer lease does not match the corrective-yield intent.');
+        }
+        const mutex = this.materializeMutex(input);
+        assertSameLeaseIdentity(file, snapshot.identity);
+        writeJsonAtomic(file, mutex);
+        return issueCoreHandle(this.locksRoot, this.trustedRoot, mutex);
+    }
+    release(handle) {
+        const record = assertCoreTaskOperationHandle(this.locksRoot, this.trustedRoot, handle, this.now());
+        const file = path.join(this.locksRoot, `${record.entityId}.json`);
+        const snapshot = readLockSnapshot(this.locksRoot, record.entityId, this.trustedRoot);
+        if (!isCoreTaskOperationMutex(snapshot.record) || snapshot.record.mutexId !== record.mutexId) {
+            throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${record.entityId}`);
+        }
+        assertSameLeaseIdentity(file, snapshot.identity);
+        unlinkSync(file);
+        closeSync(coreHandles.get(handle).descriptor);
+        coreHandles.delete(handle);
+    }
+    materializeMutex(input) {
+        assertLockEntity(input.entityId);
+        if (!input.entityId.startsWith('TASK-') || !/^[a-f0-9]{64}$/.test(input.operationId)
+            || !isSupportedCoreTaskTransition(input.transitionId)) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Invalid Core Task operation identity.');
+        }
+        const leaseMs = input.leaseMs ?? DEFAULT_LEASE_MS;
+        if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || leaseMs > DEFAULT_LEASE_MS) {
+            throw new WorkflowError('INVALID_ARGUMENT', 'Core Task operation lease must be between 1 ms and 30 minutes.');
+        }
+        const timestamp = this.now();
+        return {
+            schemaVersion: STATE_SCHEMA_VERSION,
+            kind: 'core-task-operation-mutex',
+            entityId: input.entityId,
+            operationId: input.operationId,
+            transitionId: input.transitionId,
+            mutexId: randomUUID(),
+            nonceSha256: createHash('sha256').update(randomUUID()).digest('hex'),
+            owner: 'workflow-core',
+            acquiredAt: timestamp.toISOString(),
+            expiresAt: new Date(timestamp.getTime() + leaseMs).toISOString(),
+        };
+    }
+}
+export function assertCoreTaskOperationHandle(locksRoot, trustedRoot, handle, now, expected) {
+    if (!handle || typeof handle !== 'object') {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine Core Task operation handle is required.');
+    }
+    const issued = coreHandles.get(handle);
+    if (!issued || issued.locksRoot !== path.resolve(locksRoot)
+        || (issued.trustedRoot ?? undefined) !== (trustedRoot === undefined ? undefined : path.resolve(trustedRoot))) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine Core Task operation handle is required.');
+    }
+    if (expected?.entityId !== undefined && issued.mutex.entityId !== expected.entityId) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${expected.entityId}`);
+    }
+    if (expected?.operationId !== undefined && issued.mutex.operationId !== expected.operationId) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'Core Task operation id mismatch.');
+    }
+    if (expected?.transitionId !== undefined && issued.mutex.transitionId !== expected.transitionId) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'Core Task operation transition mismatch.');
+    }
+    const snapshot = readLockSnapshot(locksRoot, issued.mutex.entityId, trustedRoot);
+    const anchored = fstatSync(issued.descriptor);
+    if (!isCoreTaskOperationMutex(snapshot.record)
+        || snapshot.record.mutexId !== issued.mutex.mutexId
+        || snapshot.record.nonceSha256 !== issued.mutex.nonceSha256
+        || !sameIdentity(snapshot.identity, issued.identity)
+        || !sameIdentity(snapshot.identity, anchored)) {
+        closeSync(issued.descriptor);
+        coreHandles.delete(handle);
+        throw new WorkflowError('LOCK_TOKEN_INVALID', `Core Task operation does not own ${issued.mutex.entityId}`);
+    }
+    if (lockExpiry(snapshot.record, path.join(locksRoot, `${issued.mutex.entityId}.json`)) <= now.getTime()) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Core Task operation has expired for ${issued.mutex.entityId}.`);
+    }
+    return snapshot.record;
+}
+export function inspectCoreTaskOperationMutex(locksRoot, entityId, trustedRoot) {
+    assertLockEntity(entityId);
+    if (!lstatIfPresent(locksRoot))
+        return null;
+    const file = path.join(locksRoot, `${entityId}.json`);
+    if (!lstatIfPresent(file))
+        return null;
+    const record = readLockSnapshot(locksRoot, entityId, trustedRoot).record;
+    return isCoreTaskOperationMutex(record) ? record : null;
+}
+export function toPublicCoreTaskOperation(mutex, now) {
+    return {
+        schemaVersion: mutex.schemaVersion,
+        entityId: mutex.entityId,
+        operationId: mutex.operationId,
+        transitionId: mutex.transitionId,
+        owner: mutex.owner,
+        acquiredAt: mutex.acquiredAt,
+        expiresAt: mutex.expiresAt,
+        stale: lockExpiry(mutex, '<core-task-operation>') <= now.getTime(),
+    };
+}
+function assertLockRootPath(locksRoot, trustedRoot) {
+    const boundary = trustedBoundary(locksRoot, trustedRoot);
+    assertNoSymlinkBelowBoundary(locksRoot, boundary, 'Writer lock root');
+    const stat = lstatIfPresent(locksRoot);
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+        throw new WorkflowError('STATE_CORRUPT', `Writer lock root must be a directory: ${locksRoot}`);
+    }
+}
+function assertNoSymlinkBelowBoundary(candidate, boundary, label) {
+    const resolvedCandidate = path.resolve(candidate);
+    if (resolvedCandidate !== boundary && !resolvedCandidate.startsWith(`${boundary}${path.sep}`)) {
+        throw new WorkflowError('INVALID_ARGUMENT', `${label} is outside of the trusted root: ${candidate}`, {
+            trustedRoot: boundary,
+        });
+    }
+    let current = boundary;
+    for (const segment of path.relative(boundary, resolvedCandidate).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        const stat = lstatIfPresent(current);
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink()) {
+            throw new WorkflowError('STATE_CORRUPT', `${label} must not traverse a symlink: ${candidate}`, {
+                symlinkPath: current,
+            });
+        }
+    }
+}
+function trustedBoundary(locksRoot, trustedRoot) {
+    const boundary = path.resolve(trustedRoot ?? path.dirname(locksRoot));
+    const stat = lstatIfPresent(boundary);
+    if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new WorkflowError('STATE_CORRUPT', `Writer lock trusted root must be an existing directory: ${boundary}`);
+    }
+    return boundary;
+}
+function assertSameLeaseIdentity(file, expected) {
+    const current = lstatIfPresent(file);
+    if (!current || current.isSymbolicLink() || !current.isFile() || !sameIdentity(expected, current)) {
+        throw new WorkflowError('STATE_CONFLICT', `Writer lease changed before mutation: ${file}`);
+    }
+}
+function leaseExpiry(lease, file) {
+    if (typeof lease.expiresAt !== 'string') {
+        throw new WorkflowError('STATE_CORRUPT', `Writer lease expiresAt must be a finite ISO timestamp: ${file}`);
+    }
+    const expiresAt = Date.parse(lease.expiresAt);
+    if (!Number.isFinite(expiresAt) || new Date(expiresAt).toISOString() !== lease.expiresAt) {
+        throw new WorkflowError('STATE_CORRUPT', `Writer lease expiresAt must be a finite ISO timestamp: ${file}`, {
+            expiresAt: lease.expiresAt,
+        });
+    }
+    return expiresAt;
+}
+function lockExpiry(record, file) {
+    return leaseExpiry(record, file);
+}
+function isCoreTaskOperationMutex(record) {
+    return record.kind === 'core-task-operation-mutex';
+}
+function validateLockRecord(record, expectedEntityId, file) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+        throw new WorkflowError('STATE_CORRUPT', `Task operation lock must be an object: ${file}`);
+    }
+    if (record.schemaVersion !== STATE_SCHEMA_VERSION || record.entityId !== expectedEntityId) {
+        throw new WorkflowError('STATE_CORRUPT', `Task operation lock identity mismatch: ${file}`);
+    }
+    if (isCoreTaskOperationMutex(record)) {
+        const keys = Object.keys(record).sort();
+        const expected = [
+            'acquiredAt', 'entityId', 'expiresAt', 'kind', 'mutexId', 'nonceSha256', 'operationId',
+            'owner', 'schemaVersion', 'transitionId',
+        ].sort();
+        if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+            throw new WorkflowError('STATE_CORRUPT', `Core Task operation lock has unknown or missing fields: ${file}`);
+        }
+        if (record.owner !== 'workflow-core' || !isSupportedCoreTaskTransition(record.transitionId)) {
+            throw new WorkflowError('STATE_CORRUPT', `Core Task operation lock semantic identity mismatch: ${file}`);
+        }
+        assertHash64(record.operationId, 'Core Task operation id');
+        assertHash64(record.nonceSha256, 'Core Task operation nonce hash');
+        if (typeof record.mutexId !== 'string' || !/^[0-9a-f-]{36}$/.test(record.mutexId)) {
+            throw new WorkflowError('STATE_CORRUPT', `Core Task operation mutexId is invalid: ${file}`);
+        }
+        const acquiredAt = typeof record.acquiredAt === 'string' ? Date.parse(record.acquiredAt) : Number.NaN;
+        if (!Number.isFinite(acquiredAt) || new Date(acquiredAt).toISOString() !== record.acquiredAt) {
+            throw new WorkflowError('STATE_CORRUPT', `Core Task operation acquiredAt is invalid: ${file}`);
+        }
+    }
+    lockExpiry(record, file);
+}
+function assertWriterLeaseHandle(locksRoot, trustedRoot, handle, now) {
+    if (!handle || typeof handle !== 'object') {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine writer lease handle is required.');
+    }
+    const issued = writerHandles.get(handle);
+    if (!issued || issued.locksRoot !== path.resolve(locksRoot)
+        || (issued.trustedRoot ?? undefined) !== (trustedRoot === undefined ? undefined : path.resolve(trustedRoot))) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'A genuine writer lease handle is required.');
+    }
+    const current = readLeaseSnapshot(locksRoot, issued.snapshot.lease.entityId, trustedRoot);
+    if (!sameIdentity(current.identity, issued.snapshot.identity)
+        || current.lease.token !== issued.snapshot.lease.token
+        || current.content !== issued.snapshot.content) {
+        throw new WorkflowError('LOCK_TOKEN_INVALID', 'Writer lease changed after proof issuance.');
+    }
+    if (leaseExpiry(current.lease, path.join(locksRoot, `${current.lease.entityId}.json`)) <= now.getTime()) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Writer lease has expired for ${current.lease.entityId}.`);
+    }
+    return current;
+}
+function issueCoreHandle(locksRoot, trustedRoot, mutex) {
+    const issued = readLockSnapshot(locksRoot, mutex.entityId, trustedRoot);
+    if (!isCoreTaskOperationMutex(issued.record) || issued.record.mutexId !== mutex.mutexId) {
+        throw new WorkflowError('STATE_CONFLICT', 'Core Task operation changed during lock transfer.');
+    }
+    const file = path.join(locksRoot, `${mutex.entityId}.json`);
+    let descriptor = null;
+    try {
+        descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const anchored = fstatSync(descriptor);
+        if (!anchored.isFile() || !sameIdentity(issued.identity, anchored)) {
+            throw new WorkflowError('STATE_CONFLICT', 'Core Task operation changed while anchoring its handle.');
+        }
+    }
+    catch (error) {
+        if (descriptor !== null)
+            closeSync(descriptor);
+        throw error;
+    }
+    const handle = Object.freeze(Object.create(null));
+    coreHandles.set(handle, {
+        locksRoot: path.resolve(locksRoot),
+        ...(trustedRoot === undefined ? {} : { trustedRoot: path.resolve(trustedRoot) }),
+        mutex,
+        identity: issued.identity,
+        descriptor,
+    });
+    return handle;
+}
+function isSupportedCoreTaskTransition(value) {
+    return value === 'task.plan.corrective-replan' || value === 'task.coordination.corrective-yield';
+}
+function assertHash64(value, label) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be a lowercase SHA-256 value.`);
+    }
+}
+function assertLockEntity(entityId) {
+    if (!LOCK_ENTITY_PATTERN.test(entityId)) {
+        throw new WorkflowError('INVALID_ARGUMENT', `Invalid lock entity: ${entityId}`);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function lstatIfPresent(candidate) {
+    try {
+        return lstatSync(candidate);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
 //# sourceMappingURL=lock.js.map