@playcraft/cli 0.1.57-beta → 0.1.59-beta

package/dist/workspace-runtime/server/directory-access.js

@@ -0,0 +1,414 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { isTurnControl, takesWorkspaceDirectory, takesExecutionSlot, transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+import { listMembers, readSnapshot } from '../batch/records.js';
+const context = new AsyncLocalStorage();
+const gates = new WeakMap();
+const instances = new WeakMap();
+const executing = new WeakMap();
+const freezing = new WeakMap();
+const TERMINAL = new Set(['completed', 'failed', 'interrupted']);
+const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'delivery.build', 'directory.create',
+    'directory.rename', 'directory.delete', 'workspace.references.import', 'skills.update', 'parameter.verify',
+    'checkpoint.create', 'checkpoint.restore']);
+export function managedDirectoryScope(state, value) {
+    if (state.config.workspaceMode !== 'multi')
+        return { directoryName: 'basic' };
+    const [workspaceId, directoryName = 'basic'] = value.split(':');
+    return { workspaceId, directoryName };
+}
+function overlaps(a, b) {
+    return (a.workspaceId ?? '') === (b.workspaceId ?? '') &&
+        ((a.directoryName ?? 'basic') === (b.directoryName ?? 'basic') || a.directoryName === 'root' || b.directoryName === 'root');
+}
+function covers(parent, child) {
+    return (parent.workspaceId ?? '') === (child.workspaceId ?? '') &&
+        (parent.directoryName === 'root' || (parent.directoryName ?? 'basic') === (child.directoryName ?? 'basic'));
+}
+export function operationDirectoryMode(operation) {
+    return operation.directoryAccessMode ?? (EXCLUSIVE_OPERATIONS.has(operation.kind) || operation.kind.startsWith('git.') ? 'exclusive' : 'shared');
+}
+function activeSessionOwner(state, gate, scope, sessionId, except) {
+    if (!sessionId)
+        return undefined;
+    const operation = state.journal.listOperations().map(item => item.operation).find(item => item.sessionId === sessionId &&
+        item.operationId !== except && ['session.turn', 'session.review', 'session.compact'].includes(item.kind) &&
+        ['dispatched', 'accepted', 'uncertain'].includes(item.status) && covers(item, scope) && gate.has(`operation:${item.operationId}`));
+    return operation ? `operation:${operation.operationId}` : undefined;
+}
+/** A directory has many ordinary writers, or one build, freeze, maintenance job or member Run. */
+export class DirectoryAccessGate {
+    normalize;
+    held = new Map();
+    pending = [];
+    constructor(normalize = claim => claim) {
+        this.normalize = normalize;
+    }
+    claim(input) {
+        const claim = this.normalize(input);
+        const held = this.held.get(claim.owner);
+        if (held) {
+            if (!covers(held, claim) || held.mode === 'shared' && claim.mode === 'exclusive')
+                return Promise.reject(new Error('directory_access_upgrade_forbidden'));
+            return Promise.resolve();
+        }
+        const existing = this.pending.find(item => item.owner === claim.owner);
+        if (existing) {
+            if (!covers(existing, claim) || existing.mode === 'shared' && claim.mode === 'exclusive')
+                return Promise.reject(new Error('directory_access_upgrade_forbidden'));
+            if (existing.paused && !claim.paused) {
+                existing.paused = false;
+                this.drain();
+            }
+            return existing.ready;
+        }
+        let resolve;
+        let reject;
+        const ready = new Promise((done, fail) => { resolve = done; reject = fail; });
+        this.pending.push({ ...claim, ready, resolve, reject });
+        this.drain();
+        return ready;
+    }
+    restore(claim) { this.held.set(claim.owner, this.normalize(claim)); }
+    has(owner) { return this.held.has(owner); }
+    permits(owner, scope, mode) {
+        const held = this.held.get(owner);
+        return Boolean(held && covers(held, this.normalize({ ...scope, owner, mode })) && (held.mode === 'exclusive' || mode === 'shared'));
+    }
+    tryClaim(claim) {
+        const ready = this.claim(claim);
+        if (this.has(claim.owner))
+            return true;
+        void ready.catch(() => undefined);
+        this.release(claim.owner);
+        return false;
+    }
+    adopt(owner, parentOwner) {
+        const child = this.pending.find(item => item.owner === owner);
+        const parent = this.held.get(parentOwner);
+        if (!child || !parent || parent.mode !== 'exclusive' || !covers(parent, child))
+            return;
+        child.parentOwner = parentOwner;
+        this.drain();
+    }
+    cancelPending(owner) {
+        if (this.held.has(owner) || !this.pending.some(item => item.owner === owner))
+            return false;
+        this.release(owner);
+        return true;
+    }
+    release(owner) {
+        this.held.delete(owner);
+        const pending = this.pending.find(item => item.owner === owner);
+        if (pending) {
+            this.pending.splice(this.pending.indexOf(pending), 1);
+            pending.reject(new Error('directory_access_cancelled'));
+        }
+        this.drain();
+    }
+    owners() { return [...this.held.keys(), ...this.pending.map(item => item.owner)]; }
+    drain() {
+        const earlier = [];
+        for (const item of [...this.pending]) {
+            if (item.paused) {
+                earlier.push(item);
+                continue;
+            }
+            const parent = item.parentOwner ? this.held.get(item.parentOwner) : undefined;
+            const family = parent && covers(parent, item) && (parent.mode === 'exclusive' || item.mode === 'shared');
+            const conflict = [...this.held.values()].some(held => !(family && (held.owner === parent.owner || held.parentOwner === parent.owner)) && overlaps(item, held) &&
+                (item.mode === 'exclusive' || held.mode === 'exclusive' || Boolean(item.sessionId && held.sessionId === item.sessionId)));
+            const queuedWriter = !family && earlier.some(prior => overlaps(item, prior) && (item.mode === 'exclusive' || prior.mode === 'exclusive'));
+            if (conflict || queuedWriter) {
+                earlier.push(item);
+                continue;
+            }
+            this.pending.splice(this.pending.indexOf(item), 1);
+            this.held.set(item.owner, item);
+            item.resolve();
+        }
+    }
+}
+async function gateFor(state) {
+    let pending = gates.get(state);
+    if (!pending) {
+        pending = (async () => {
+            const gate = new DirectoryAccessGate(claim => state.config.workspaceMode === 'multi'
+                ? claim : { ...claim, workspaceId: undefined, directoryName: 'basic' });
+            instances.set(state, gate);
+            const members = await listMembers(state);
+            for (const member of members)
+                if (member.holding)
+                    gate.restore({ ...member, owner: `run:${member.runId}`, mode: 'exclusive' });
+            for (const { operation } of state.journal.listOperations()) {
+                if (!takesWorkspaceDirectory(operation.kind) || isTurnControl(operation.kind) ||
+                    !['dispatched', 'accepted', 'uncertain'].includes(operation.status) ||
+                    members.some(member => member.holding && (member.operationId === operation.operationId || Boolean(member.sessionId && member.sessionId === operation.sessionId))))
+                    continue;
+                gate.restore({ ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation) });
+            }
+            for (const terminal of state.journal.listTerminals())
+                if (terminal.status !== 'destroyed')
+                    gate.restore({ ...terminal, owner: `terminal:${terminal.terminalId}`, mode: 'shared' });
+            for (const writer of state.journal.listManagedWrites())
+                if (!writer.stoppedAt) {
+                    gate.restore({ ...managedDirectoryScope(state, writer.workspaceId), owner: `managed:${writer.writeId}`, mode: 'shared' });
+                }
+            const waiting = [];
+            for (const barrier of state.journal.directoryBarriers()) {
+                const snapshot = barrier.owner.startsWith('freeze:')
+                    ? await readSnapshot(state, barrier.owner.slice('freeze:'.length)).catch(() => undefined) : undefined;
+                if (snapshot?.sourceWorkspaceId === barrier.workspaceId && snapshot.sourceDirectoryName === barrier.directoryName) {
+                    await state.journal.deleteDirectoryBarrier(barrier.owner);
+                    continue;
+                }
+                if (barrier.phase !== 'pending') {
+                    gate.restore({ ...barrier, mode: 'exclusive' });
+                    continue;
+                }
+                if (barrier.deadline && Date.parse(barrier.deadline) <= Date.now()) {
+                    await state.journal.deleteDirectoryBarrier(barrier.owner);
+                    continue;
+                }
+                waiting.push({ claim: { ...barrier, mode: 'exclusive', paused: true }, queuedAt: barrier.queuedAt ?? '' });
+                const timeout = setTimeout(() => {
+                    if (gate.cancelPending(barrier.owner))
+                        void state.journal.deleteDirectoryBarrier(barrier.owner).catch(() => undefined);
+                }, Math.max(0, Date.parse(barrier.deadline ?? new Date(Date.now() + 60_000).toISOString()) - Date.now()));
+                timeout.unref?.();
+            }
+            for (const pending of state.journal.deferredDirectoryOperations()) {
+                const operation = state.journal.getOperationById(pending.operationId);
+                if (operation?.status !== 'queued')
+                    continue;
+                waiting.push({ claim: { ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation),
+                        ...(operation.kind.startsWith('session.') ? { sessionId: operation.sessionId } : {}) }, queuedAt: pending.queuedAt ?? operation.createdAt });
+            }
+            for (const item of waiting.sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)))
+                void gate.claim(item.claim).catch(() => undefined);
+            state.journal.onChange(() => reconcileDirectoryAccess(state));
+            return gate;
+        })();
+        gates.set(state, pending);
+    }
+    return pending;
+}
+/** The journal is the long-lived execution truth; only confirmed terminal writers release a lease. */
+export function reconcileDirectoryAccess(state) {
+    const gate = instances.get(state);
+    if (!gate)
+        return;
+    for (const owner of gate.owners()) {
+        if (owner.startsWith('operation:')) {
+            const operation = state.journal.getOperationById(owner.slice('operation:'.length));
+            if (operation && TERMINAL.has(operation.status))
+                gate.release(owner);
+        }
+        else if (owner.startsWith('terminal:')) {
+            if (state.journal.getTerminal(owner.slice('terminal:'.length))?.status === 'destroyed')
+                gate.release(owner);
+        }
+        else if (owner.startsWith('managed:')) {
+            if (state.journal.listManagedWrites().find(writer => writer.writeId === owner.slice('managed:'.length))?.stoppedAt)
+                gate.release(owner);
+        }
+    }
+}
+export async function holdDirectoryAccess(state, scope, owner, mode = 'shared') {
+    const gate = await gateFor(state);
+    const inherited = context.getStore();
+    await gate.claim({ ...scope, owner, mode,
+        ...(inherited?.state === state && gate.permits(inherited.claim.owner, scope, mode) ? { parentOwner: inherited.claim.owner } : {}) });
+    return () => gate.release(owner);
+}
+/** A build may join its known installer that was queued behind the build's own exclusive lease. */
+export async function adoptDirectoryAccess(state, owner) {
+    const inherited = context.getStore();
+    if (inherited?.state !== state || inherited.claim.mode !== 'exclusive')
+        return;
+    (await gateFor(state)).adopt(owner, inherited.claim.owner);
+}
+/** Cancelling a not-yet-spawned writer cannot release a process that is already running. */
+export async function cancelPendingDirectoryAccess(state, owner) {
+    return (await gateFor(state)).cancelPending(owner);
+}
+export async function withDirectoryOwner(state, scope, owner, action) {
+    if (!(await gateFor(state)).permits(owner, scope, 'exclusive'))
+        throw new Error('directory_owner_not_held');
+    return context.run({ state, claim: { ...scope, owner, mode: 'exclusive' } }, action);
+}
+export async function withDirectoryWrite(state, scope, action) {
+    const inherited = context.getStore();
+    const gate = await gateFor(state);
+    if (inherited?.state === state && gate.permits(inherited.claim.owner, scope, scope.mode ?? 'shared'))
+        return action();
+    if (inherited?.state === state && scope.mode === 'exclusive' && gate.permits(inherited.claim.owner, scope, 'shared'))
+        throw new Error('directory_busy');
+    const parentOwner = scope.mode !== 'exclusive' ? activeSessionOwner(state, gate, scope, scope.sessionId) : undefined;
+    const claim = { ...scope, sessionId: undefined, owner: scope.owner ?? `write:${randomUUID()}`, mode: scope.mode ?? 'shared',
+        ...(parentOwner ? { parentOwner } : {}) };
+    if (scope.wait === false && !gate.tryClaim(claim))
+        throw new Error('directory_busy');
+    if (scope.wait !== false)
+        await gate.claim(claim);
+    const release = () => gate.release(claim.owner);
+    try {
+        return await context.run({ state, claim }, action);
+    }
+    finally {
+        release();
+    }
+}
+export async function withOperationDirectoryAccess(state, operation, action, deferred) {
+    if (!takesWorkspaceDirectory(operation.kind) || isTurnControl(operation.kind) || operation.kind === 'runtime.destroy')
+        return action();
+    const inherited = context.getStore();
+    const mode = operationDirectoryMode(operation);
+    const gate = await gateFor(state);
+    if (inherited?.state === state && gate.permits(inherited.claim.owner, operation, mode))
+        return action();
+    const active = executing.get(state) ?? new Set();
+    executing.set(state, active);
+    if (active.has(operation.operationId))
+        return state.journal.getOperationById(operation.operationId) ?? operation;
+    active.add(operation.operationId);
+    const parentOwner = !takesExecutionSlot(operation.kind) && mode === 'shared'
+        ? activeSessionOwner(state, gate, operation, operation.sessionId, operation.operationId) : undefined;
+    const claim = { ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation),
+        ...(operation.kind.startsWith('session.') ? { sessionId: operation.sessionId } : {}),
+        ...(parentOwner ? { parentOwner } : {}) };
+    if (inherited?.state === state && mode === 'shared' && gate.permits(inherited.claim.owner, operation, mode))
+        claim.parentOwner = inherited.claim.owner;
+    const ready = gate.claim(claim);
+    const run = async () => {
+        try {
+            await ready;
+            const current = state.journal.getOperationById(operation.operationId);
+            if (current && TERMINAL.has(current.status))
+                return current;
+            return await context.run({ state, claim }, action);
+        }
+        finally {
+            active.delete(operation.operationId);
+            const current = state.journal.getOperationById(operation.operationId);
+            if (!current || current.status === 'queued' || TERMINAL.has(current.status))
+                gate.release(claim.owner);
+            if (deferred && current?.status !== 'queued')
+                await state.journal.deleteDeferredDirectoryOperation(operation.operationId);
+        }
+    };
+    if (gate.has(claim.owner))
+        return run();
+    if (!deferred)
+        return run();
+    try {
+        await state.journal.deferDirectoryOperation(deferred);
+    }
+    catch (error) {
+        active.delete(operation.operationId);
+        void ready.catch(() => undefined);
+        gate.release(claim.owner);
+        throw error;
+    }
+    void run().catch(async (error) => {
+        const current = state.journal.getOperationById(operation.operationId);
+        if (!current || TERMINAL.has(current.status))
+            return;
+        await state.journal.putOperation(deferred.scopeKey, transitionOperation(current, 'uncertain', {
+            error: error instanceof Error && error.message === 'directory_access_cancelled' ? 'cancelled' : 'native_receipt_lost',
+        }));
+    }).catch(() => undefined);
+    return state.journal.getOperationById(operation.operationId) ?? operation;
+}
+/** A queued command is replayed only if it never started; accepted or uncertain work is only observed. */
+export async function restoreDeferredDirectoryOperations(state, execute) {
+    for (const pending of state.journal.deferredDirectoryOperations()) {
+        const operation = state.journal.getOperationById(pending.operationId);
+        if (operation?.status === 'queued') {
+            if (operation.generation !== state.config.generation || operation.runtimeEpoch !== state.runtimeEpoch) {
+                await state.journal.putOperation(pending.scopeKey, transitionOperation(operation, 'failed', { error: 'generation_mismatch' }));
+                continue;
+            }
+            void execute(pending.scopeKey, operation, pending.payload, pending.recovery).catch(() => undefined);
+        }
+        else
+            await state.journal.deleteDeferredDirectoryOperation(pending.operationId);
+    }
+}
+export async function claimBatchDirectory(state, member) {
+    await holdDirectoryAccess(state, member, `run:${member.runId}`, 'exclusive');
+}
+export function releaseBatchDirectory(state, member) {
+    if (!member.holding && member.writersStopped)
+        instances.get(state)?.release(`run:${member.runId}`);
+}
+export async function withDirectoryFreeze(state, scope, action, quiesce, options) {
+    const pending = freezing.get(state) ?? new Map();
+    freezing.set(state, pending);
+    const existing = pending.get(scope.batchId);
+    if (existing) {
+        if (existing.scope.workspaceId !== scope.workspaceId || (existing.scope.directoryName ?? 'basic') !== (scope.directoryName ?? 'basic'))
+            throw new Error('batch_source_identity_mismatch');
+        return existing.task;
+    }
+    const task = performDirectoryFreeze(state, scope, action, quiesce, options);
+    pending.set(scope.batchId, { scope, task });
+    try {
+        return await task;
+    }
+    finally {
+        if (pending.get(scope.batchId)?.task === task)
+            pending.delete(scope.batchId);
+    }
+}
+async function performDirectoryFreeze(state, scope, action, quiesce, options) {
+    const deadline = options?.deadline ?? new Date(Date.now() + 60_000).toISOString();
+    const signal = AbortSignal.any([...(options?.signal ? [options.signal] : []), AbortSignal.timeout(Math.max(0, Date.parse(deadline) - Date.now()))]);
+    if (signal.aborted)
+        throw new Error('directory_access_cancelled');
+    const owner = `freeze:${scope.batchId}`;
+    const gate = await gateFor(state);
+    const previous = state.journal.directoryBarriers().find(barrier => barrier.owner === owner);
+    if (previous && (previous.workspaceId !== scope.workspaceId || previous.directoryName !== (scope.directoryName ?? 'basic')))
+        throw new Error('batch_source_identity_mismatch');
+    // A restored capture may still have writers. Retrying its publication is not a new admission,
+    // and a missing candidate or a lost request cannot provide the old capture's stop proof.
+    const restoredCapture = Boolean(previous && previous.phase !== 'pending');
+    const claimed = gate.claim({ ...scope, owner, mode: 'exclusive' });
+    void claimed.catch(() => undefined);
+    let started = restoredCapture;
+    const cancel = () => {
+        if (started)
+            return;
+        gate.release(owner);
+        void state.journal.deleteDirectoryBarrier(owner).catch(() => undefined);
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+        if (!restoredCapture)
+            await state.journal.putDirectoryBarrier({ owner, workspaceId: scope.workspaceId,
+                directoryName: scope.directoryName ?? 'basic', runtimeEpoch: state.runtimeEpoch, phase: 'pending', deadline });
+        await quiesce?.();
+        await claimed;
+        if (signal.aborted)
+            throw new Error('directory_access_cancelled');
+        started = true;
+        if (!restoredCapture)
+            await state.journal.putDirectoryBarrier({ owner, workspaceId: scope.workspaceId,
+                directoryName: scope.directoryName ?? 'basic', runtimeEpoch: state.runtimeEpoch, phase: 'capturing', deadline });
+        return await withDirectoryOwner(state, scope, owner, action);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        const snapshot = restoredCapture ? await readSnapshot(state, scope.batchId).catch(() => undefined) : undefined;
+        if (!restoredCapture || (snapshot?.sourceWorkspaceId === scope.workspaceId && snapshot.sourceDirectoryName === (scope.directoryName ?? 'basic'))) {
+            await state.journal.deleteDirectoryBarrier(owner);
+            gate.release(owner);
+        }
+    }
+}
+export async function clearDirectoryFreeze(state, batchId) {
+    const owner = `freeze:${batchId}`;
+    await state.journal.deleteDirectoryBarrier(owner);
+    instances.get(state)?.release(owner);
+}