@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/workspace-runtime/batch/prepare.js

@@ -0,0 +1,317 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { sandboxBatchMemberPrepareSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { registerWorkspaceDirectory } from '../workspaces/directories.js';
+import { workspaceContainerRoot } from '../workspaces/registry.js';
+import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
+import { restoreArchive } from './source-capture.js';
+import { groupExited, runProcessGroup } from './processes.js';
+import { filesystemObjectStore, memberStatus, readMember, readSnapshot, readStopMarker, serializeRun, sourceCacheDir, writeMember, } from './records.js';
+const BRANCH = /^remix\/draft-[a-f0-9]{16}$/;
+const LOCKS = [
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+    'yarn.lock',
+    'bun.lock',
+    'bun.lockb',
+];
+export function frozenInstallCommand() {
+    return (process.env.PLAYCRAFT_BATCH_INSTALL_COMMAND ??
+        'pnpm install --frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --ignore-scripts');
+}
+function hashCommand(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+async function materialize(state, snapshot, destination, store, sourceRoot) {
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    const cachedDigest = await readFile(`${cache}.digest`, 'utf8').catch(() => '');
+    if (cachedDigest.trim() === snapshot.digest &&
+        (await lstat(join(cache, '.git')).catch(() => undefined))) {
+        await gitWrite(dirnameOf(destination), [
+            'clone',
+            '--local',
+            '--no-hardlinks',
+            '--',
+            cache,
+            destination,
+        ]);
+        await assertFrozenCommit(destination, snapshot.commitHash);
+        return;
+    }
+    if (snapshot.remoteRef) {
+        const binding = state.journal.getWorkspace(snapshot.sourceWorkspaceId);
+        if (!binding?.repositoryUrl)
+            throw new Error('batch_snapshot_mismatch');
+        await gitWrite(dirnameOf(destination), ['init', '--initial-branch', 'source', destination]);
+        await copyCredentialHelpers(sourceRoot, destination);
+        await gitWrite(destination, ['remote', 'add', 'origin', binding.repositoryUrl]);
+        try {
+            await gitWrite(destination, ['fetch', '--no-tags', 'origin', snapshot.remoteRef]);
+        }
+        catch {
+            throw new Error('batch_snapshot_mismatch');
+        }
+        await gitWrite(destination, ['checkout', '--detach', 'FETCH_HEAD']);
+        await assertFrozenCommit(destination, snapshot.commitHash);
+        return;
+    }
+    if (!snapshot.artifactKey)
+        throw new Error('batch_snapshot_mismatch');
+    const body = await store.get(snapshot.artifactKey).catch(() => {
+        throw new Error('batch_snapshot_mismatch');
+    });
+    await restoreArchive(body, destination, snapshot.digest);
+}
+function dirnameOf(path) {
+    return join(path, '..');
+}
+async function assertFrozenCommit(root, commit) {
+    if ((await gitRead(root, ['rev-parse', 'HEAD'])).trim() !== commit)
+        throw new Error('batch_snapshot_mismatch');
+}
+/** A bound workspace keeps origin aligned. A local workspace only needs the branch. */
+async function checkoutBranch(root, branchName, commit, repositoryUrl) {
+    await gitWrite(root, ['checkout', '-B', branchName, commit]);
+    if (repositoryUrl) {
+        const origin = await gitRead(root, ['remote', 'get-url', 'origin']).catch(() => '');
+        if (!origin.trim())
+            await gitWrite(root, ['remote', 'add', 'origin', repositoryUrl]);
+        else if (origin.trim() !== repositoryUrl)
+            await gitWrite(root, ['remote', 'set-url', 'origin', repositoryUrl]);
+    }
+    else {
+        await gitWrite(root, ['remote', 'remove', 'origin']).catch(() => undefined);
+    }
+    await gitWrite(root, ['config', 'user.name', 'PlayCraft']);
+    await gitWrite(root, ['config', 'user.email', 'playcraft@localhost']);
+}
+async function resumeBranch(repositoryUrl, branchName, commit, destination, sourceRoot) {
+    if (repositoryUrl) {
+        await gitWrite(dirnameOf(destination), [
+            'clone',
+            '--branch',
+            branchName,
+            '--single-branch',
+            '--',
+            repositoryUrl,
+            destination,
+        ]);
+        await copyCredentialHelpers(sourceRoot, destination);
+    }
+    else {
+        await gitWrite(dirnameOf(destination), [
+            'clone',
+            '--local',
+            '--no-hardlinks',
+            '--',
+            sourceRoot,
+            destination,
+        ]);
+    }
+    if ((await gitRead(destination, ['rev-parse', 'HEAD'])).trim() !== commit &&
+        !(await gitRead(destination, ['cat-file', '-e', `${commit}^{commit}`]).then(() => true, () => false))) {
+        throw new Error('batch_commit_mismatch');
+    }
+    await gitWrite(destination, ['checkout', '-B', branchName, commit]);
+}
+export async function assertMemberDependencies(root) {
+    let manifest;
+    try {
+        manifest = await readFile(join(root, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'skip';
+        throw error;
+    }
+    let names = [];
+    try {
+        const pkg = JSON.parse(manifest);
+        names = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+    }
+    catch {
+        throw new Error('dependency_lock_mismatch');
+    }
+    const present = [];
+    for (const lock of LOCKS)
+        if (await lstat(join(root, lock)).catch(() => undefined))
+            present.push(lock);
+    if (present.length > 1)
+        throw new Error('dependency_locks_conflict');
+    if (present.length === 0)
+        return 'skip';
+    if (present[0] !== 'pnpm-lock.yaml')
+        throw new Error('dependency_lock_mismatch');
+    const lock = await readFile(join(root, 'pnpm-lock.yaml'), 'utf8');
+    if (names.some((name) => !lock.includes(`${name}:`) &&
+        !lock.includes(`/${name}@`) &&
+        !lock.includes(`'${name}'`) &&
+        !lock.includes(`"${name}"`))) {
+        throw new Error('dependency_lock_mismatch');
+    }
+    return 'install';
+}
+export async function prepareBatchMember(state, body, options) {
+    if (!body ||
+        typeof body !== 'object' ||
+        !('occupancyId' in body) ||
+        !body.occupancyId)
+        throw new Error('occupancy_required');
+    const parsed = sandboxBatchMemberPrepareSchema.safeParse(body);
+    if (!parsed.success)
+        throw new Error(parsed.error.issues.some((issue) => issue.path.includes('branchName'))
+            ? 'batch_branch_invalid'
+            : 'invalid_batch_request');
+    const command = parsed.data;
+    if (!BRANCH.test(command.branchName))
+        throw new Error('batch_branch_invalid');
+    const hash = hashCommand(command);
+    return serializeRun(command.runId, async () => {
+        const marker = await readStopMarker(state, command.runId);
+        const existing = await readMember(state, command.runId);
+        if (existing && command.ownerFence < existing.ownerFence)
+            throw new Error('stale_owner');
+        if (marker)
+            return memberStatus(await sealStopped(state, command, existing));
+        if (existing &&
+            existing.ownerFence === command.ownerFence &&
+            existing.commandHash?.prepare === hash &&
+            existing.state !== 'running' &&
+            existing.state !== 'failed') {
+            return memberStatus(existing);
+        }
+        if (existing &&
+            existing.ownerFence === command.ownerFence &&
+            existing.commandHash?.prepare &&
+            existing.commandHash.prepare !== hash)
+            throw new Error('batch_command_conflict');
+        if (existing?.processes.some((process) => process.role === 'install' && !process.stopped && !groupExited(process.pid)))
+            return memberStatus(existing);
+        const snapshot = command.snapshot;
+        if ((await readSnapshot(state, snapshot.batchId))?.digest === snapshot.digest) {
+            /* The local snapshot record is an accelerator; the command snapshot remains authoritative. */
+        }
+        let record = await writeMember(state, {
+            runId: command.runId,
+            ownerFence: command.ownerFence,
+            occupancyId: command.occupancyId,
+            workspaceId: command.workspaceId,
+            directoryName: command.directoryName,
+            phase: 'prepare',
+            state: 'running',
+            writersStopped: false,
+            holding: true,
+            stopRequested: false,
+            processes: existing?.processes ?? [],
+            commandHash: { ...existing?.commandHash, prepare: hash },
+            snapshotDigest: snapshot.digest,
+            branchName: command.branchName,
+            sourceCommit: snapshot.commitHash,
+            beforeTree: existing?.beforeTree,
+            updatedAt: new Date().toISOString(),
+        });
+        let staging;
+        try {
+            const parent = await workspaceContainerRoot(state, command.workspaceId);
+            const root = join(parent, command.directoryName);
+            staging = join(parent, `.batch-member-${randomUUID()}`);
+            const binding = state.journal.getWorkspace(command.workspaceId);
+            if (!binding)
+                throw new Error('workspace_not_registered');
+            const repositoryUrl = binding.repositoryUrl ?? undefined;
+            const sourceRoot = join(parent, snapshot.sourceDirectoryName);
+            if (!(await lstat(root).catch(() => undefined))) {
+                await mkdir(parent, { recursive: true });
+                if (command.resumeFromCommit)
+                    await resumeBranch(repositoryUrl, command.branchName, command.resumeFromCommit, staging, sourceRoot);
+                else
+                    await materialize(state, snapshot, staging, options?.objectStore ?? filesystemObjectStore(state), sourceRoot);
+                const commit = command.resumeFromCommit ?? snapshot.commitHash;
+                await checkoutBranch(staging, command.branchName, commit, repositoryUrl);
+                const { rename } = await import('node:fs/promises');
+                await rename(staging, root);
+            }
+            await registerWorkspaceDirectory(state, {
+                workspaceId: command.workspaceId,
+                directoryName: command.directoryName,
+                remixId: command.remixId,
+                branchName: command.branchName,
+                sourceCommit: command.resumeFromCommit ?? snapshot.commitHash,
+            }, state.acceptedLeaseFence);
+            const plan = await assertMemberDependencies(root);
+            if (plan === 'install') {
+                const installed = await runProcessGroup(root, frozenInstallCommand(), 'install', async (process) => {
+                    record = await writeMember(state, {
+                        ...record,
+                        processes: [...record.processes, process],
+                    });
+                });
+                record = await writeMember(state, {
+                    ...record,
+                    processes: record.processes.map((process) => process.pid === installed.process.pid
+                        ? { ...installed.process, role: 'install' }
+                        : process),
+                });
+                if (await readStopMarker(state, command.runId))
+                    return memberStatus(await sealStopped(state, command, record));
+                if (installed.code !== 0)
+                    throw new Error('batch_install_failed');
+            }
+            const head = (await gitRead(root, ['rev-parse', 'HEAD'])).trim();
+            record = await writeMember(state, {
+                ...record,
+                state: 'completed',
+                writersStopped: true,
+                holding: true,
+                headCommit: head,
+                error: undefined,
+            });
+            return memberStatus(record);
+        }
+        catch (error) {
+            const code = error instanceof Error && /^[a-z0-9_]+$/.test(error.message)
+                ? error.message
+                : 'batch_prepare_failed';
+            record = await writeMember(state, {
+                ...record,
+                state: 'failed',
+                writersStopped: true,
+                holding: false,
+                error: code,
+            });
+            return memberStatus(record);
+        }
+        finally {
+            if (staging)
+                await rm(staging, { recursive: true, force: true });
+        }
+    });
+}
+async function sealStopped(state, command, existing) {
+    return writeMember(state, {
+        runId: command.runId,
+        ownerFence: Math.max(command.ownerFence, existing?.ownerFence ?? 0),
+        occupancyId: command.occupancyId,
+        workspaceId: command.workspaceId,
+        directoryName: command.directoryName,
+        phase: existing?.phase ?? 'prepare',
+        state: 'stopped',
+        writersStopped: true,
+        holding: false,
+        stopRequested: true,
+        processes: existing?.processes ?? [],
+        sessionId: existing?.sessionId,
+        operationId: existing?.operationId,
+        headCommit: existing?.headCommit,
+        evidence: existing?.evidence,
+        commandHash: existing?.commandHash,
+        snapshotDigest: existing?.snapshotDigest,
+        branchName: existing?.branchName,
+        sourceCommit: existing?.sourceCommit,
+        beforeTree: existing?.beforeTree,
+        updatedAt: new Date().toISOString(),
+    });
+}

package/dist/workspace-runtime/batch/processes.js

@@ -0,0 +1,72 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+export async function processBirth(pid) {
+    if (process.platform !== 'linux') {
+        return promisify(execFile)('ps', ['-p', String(pid), '-o', 'lstart='], { timeout: 2000 }).then(value => value.stdout.trim() || undefined, () => undefined);
+    }
+    try {
+        const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function groupExited(pid) {
+    try {
+        process.kill(-pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+/**
+ * Stops one run's process group. A mismatched birth means the pid was reused, which is not proof
+ * that the original writers exited, so the caller must not report writersStopped.
+ */
+export async function stopProcessGroup(record) {
+    if (record.stopped || groupExited(record.pid))
+        return true;
+    if (record.birth && await processBirth(record.pid) !== record.birth)
+        return false;
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        try {
+            process.kill(-record.pid, signal);
+        }
+        catch { /* Recheck the group. */ }
+        const deadline = Date.now() + 2000;
+        while (Date.now() < deadline) {
+            if (groupExited(record.pid))
+                return true;
+            await delay(25);
+        }
+    }
+    return groupExited(record.pid);
+}
+export async function runProcessGroup(cwd, command, role, onStart) {
+    const child = spawn('bash', ['-lc', command], {
+        cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { PATH: process.env.PATH, HOME: cwd, GIT_TERMINAL_PROMPT: '0' },
+    });
+    const pid = child.pid;
+    if (!pid)
+        throw new Error('batch_process_not_started');
+    let output = '';
+    const collect = (chunk) => { output = (output + String(chunk)).slice(-64 * 1024); };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+    // Subscribe before any await. A short command can exit during processBirth or onStart,
+    // and a late listener never sees that close event.
+    const finished = new Promise((resolve) => {
+        child.once('error', () => resolve(null));
+        child.once('close', resolve);
+    });
+    const tracked = { pid, birth: await processBirth(pid), stopped: false, role };
+    await onStart(tracked);
+    const code = await finished;
+    tracked.stopped = groupExited(pid);
+    return { code, output, process: tracked };
+}

package/dist/workspace-runtime/batch/records.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { batchSourceSnapshotRefSchema, sandboxBatchMemberStatusSchema, } from '@playcraft/common/cloud-workspace/runtime';
+const runs = new Map();
+let freezeChain = Promise.resolve();
+export function serializeFreeze(action) {
+    const run = freezeChain.then(action, action);
+    freezeChain = run.then(() => undefined, () => undefined);
+    return run;
+}
+export function serializeRun(runId, action) {
+    const previous = runs.get(runId) ?? Promise.resolve();
+    const run = previous.then(action, action);
+    runs.set(runId, run.then(() => undefined, () => undefined));
+    return run;
+}
+export function snapshotFile(state, batchId) {
+    return join(state.config.stateDir, 'batch-sources', `${batchId}.json`);
+}
+export function memberFile(state, runId) {
+    return join(state.config.stateDir, 'batch-members', `${runId}.json`);
+}
+export function stopMarkerFile(state, runId) {
+    return join(state.config.stateDir, 'batch-stops', `${runId}.json`);
+}
+export function sourceCacheDir(state, batchId) {
+    return join(state.config.stateDir, 'batch-source-cache', batchId);
+}
+export function objectFile(state, key) {
+    if (key.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new Error('batch_object_key_invalid');
+    return join(state.config.stateDir, 'batch-objects', key);
+}
+async function writeAtomic(path, body) {
+    await mkdir(join(path, '..'), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, body, { mode: 0o600 });
+    await rename(temporary, path);
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function readSnapshot(state, batchId) {
+    const value = await readJson(snapshotFile(state, batchId));
+    return value ? batchSourceSnapshotRefSchema.parse(value) : undefined;
+}
+export async function writeSnapshot(state, snapshot) {
+    const parsed = batchSourceSnapshotRefSchema.parse(snapshot);
+    await writeAtomic(snapshotFile(state, parsed.batchId), JSON.stringify(parsed));
+}
+export async function readMember(state, runId) {
+    return readJson(memberFile(state, runId));
+}
+export async function writeMember(state, record) {
+    const next = { ...record, updatedAt: new Date().toISOString() };
+    await writeAtomic(memberFile(state, record.runId), JSON.stringify(next));
+    return next;
+}
+export async function listMembers(state) {
+    const directory = join(state.config.stateDir, 'batch-members');
+    const names = await readdir(directory).catch(error => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    const records = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const record = await readJson(join(directory, name));
+        if (record)
+            records.push(record);
+    }
+    return records;
+}
+export async function readStopMarker(state, runId) {
+    return readJson(stopMarkerFile(state, runId));
+}
+export async function writeStopMarker(state, runId, ownerFence) {
+    const path = stopMarkerFile(state, runId);
+    if (await readStopMarker(state, runId))
+        return;
+    await writeAtomic(path, JSON.stringify({ runId, ownerFence, at: new Date().toISOString() }));
+}
+export function memberStatus(record) {
+    return sandboxBatchMemberStatusSchema.parse({
+        runId: record.runId,
+        ownerFence: record.ownerFence,
+        phase: record.phase,
+        state: record.state,
+        writersStopped: record.writersStopped,
+        ...(record.sessionId ? { sessionId: record.sessionId } : {}),
+        ...(record.operationId ? { operationId: record.operationId } : {}),
+        ...(record.headCommit ? { headCommit: record.headCommit } : {}),
+        ...(record.evidence ? { evidence: record.evidence } : {}),
+        ...(record.error ? { error: record.error.slice(0, 128) } : {}),
+        updatedAt: record.updatedAt,
+    });
+}
+export function filesystemObjectStore(state) {
+    return {
+        async put(key, body) { await writeAtomic(objectFile(state, key), body); },
+        async get(key) { return readFile(objectFile(state, key)); },
+    };
+}

package/dist/workspace-runtime/batch/routes.js

@@ -0,0 +1,61 @@
+import { batchSourceFreezeResultSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { stopBatchMember, readBatchMemberStatus } from './control.js';
+import { deliverBatchMember } from './deliver.js';
+import { freezeBatchSource } from './freeze.js';
+import { generateBatchMember } from './generate.js';
+import { prepareBatchMember } from './prepare.js';
+import { BatchSourceFreezeError } from './source-failure.js';
+const CLIENT_ERRORS = new Set([
+    'occupancy_required', 'invalid_batch_request', 'batch_branch_invalid', 'stale_owner', 'disk_admission_paused',
+    'batch_source_push_failed', 'batch_source_upload_failed', 'batch_source_changed', 'batch_source_path_invalid',
+    'batch_command_conflict', 'batch_snapshot_mismatch', 'batch_commit_mismatch', 'workspace_not_registered',
+    'disk_usage_unavailable', 'batch_object_key_invalid',
+]);
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > 1024 * 1024)
+            throw new Error('request_body_too_large');
+        chunks.push(Buffer.from(chunk));
+    }
+    if (!size)
+        return {};
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export async function dispatchBatchRoute(state, request, url) {
+    const method = request.method ?? 'GET';
+    const path = url.pathname;
+    const member = /^\/runtime\/batch-members\/([^/]+)(?:\/(stop))?$/.exec(path);
+    if (method === 'GET' && member && !member[2]) {
+        const status = await readBatchMemberStatus(state, decodeURIComponent(member[1]));
+        return status ? { status: 200, body: status } : { status: 404, body: { error: 'batch_member_not_found' } };
+    }
+    if (method !== 'POST')
+        return undefined;
+    try {
+        if (path === '/runtime/batch-sources/freeze') {
+            const result = batchSourceFreezeResultSchema.parse(await freezeBatchSource(state, await readBody(request)));
+            return { status: 200, body: result };
+        }
+        if (path === '/runtime/batch-members/prepare')
+            return { status: 200, body: await prepareBatchMember(state, await readBody(request)) };
+        if (path === '/runtime/batch-members/generate')
+            return { status: 200, body: await generateBatchMember(state, await readBody(request)) };
+        if (path === '/runtime/batch-members/deliver')
+            return { status: 200, body: await deliverBatchMember(state, await readBody(request)) };
+        if (member?.[2] === 'stop')
+            return { status: 200, body: await stopBatchMember(state, decodeURIComponent(member[1]), await readBody(request)) };
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof BatchSourceFreezeError)
+            return { status: 409, body: { error: error.message, failure: error.failure } };
+        const code = error instanceof Error && CLIENT_ERRORS.has(error.message) ? error.message : undefined;
+        if (!code)
+            throw error;
+        const status = code === 'occupancy_required' || code === 'invalid_batch_request' || code === 'batch_branch_invalid' ? 400 : 409;
+        return { status, body: { error: code } };
+    }
+}

package/dist/workspace-runtime/batch/source-candidate.js

@@ -0,0 +1,86 @@
+import { randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { batchSourceSnapshotRefSchema, } from '@playcraft/common/cloud-workspace/runtime';
+export function sourceCandidateFile(state, batchId) {
+    return join(state.config.stateDir, 'batch-source-candidates', `${batchId}.json`);
+}
+export async function readSourceCandidate(state, batchId) {
+    let body;
+    try {
+        body = await readFile(sourceCandidateFile(state, batchId), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let stored;
+    try {
+        stored = JSON.parse(body);
+    }
+    catch {
+        throw new Error('batch_source_snapshot_mismatch');
+    }
+    if (!stored || stored.version !== 1 || !['remote_ref', 'artifact'].includes(stored.persist)
+        || (stored.repositoryUrl !== undefined && typeof stored.repositoryUrl !== 'string')
+        || (stored.projectId !== undefined && stored.projectId !== null && typeof stored.projectId !== 'string')
+        || (stored.branchName !== undefined && typeof stored.branchName !== 'string'))
+        throw new Error('batch_source_snapshot_mismatch');
+    const parsed = batchSourceSnapshotRefSchema.safeParse(stored.snapshot);
+    if (!parsed.success)
+        throw new Error('batch_source_snapshot_mismatch');
+    const snapshot = parsed.data;
+    if (snapshot.batchId !== batchId)
+        throw new Error('batch_source_identity_mismatch');
+    return { ...stored, snapshot };
+}
+/** The immutable candidate is committed to disk before any request can publish its commit. */
+export async function writeSourceCandidate(state, candidate) {
+    const path = sourceCandidateFile(state, candidate.snapshot.batchId);
+    const directory = join(path, '..');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(candidate));
+        await handle.sync();
+        await handle.close();
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await readSourceCandidate(state, candidate.snapshot.batchId);
+            if (JSON.stringify(existing) !== JSON.stringify(candidate))
+                throw new Error('batch_source_identity_mismatch');
+        }
+        const folder = await open(directory, 'r');
+        try {
+            await folder.sync();
+        }
+        finally {
+            await folder.close();
+        }
+    }
+    finally {
+        await handle.close();
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+export function assertSourceIdentity(state, request, snapshot, candidate) {
+    const binding = state.journal.getWorkspace(request.workspaceId);
+    const branchName = request.sourceDirectoryName === 'basic' ? binding?.branchName
+        : binding?.directories?.find(directory => directory.directoryName === request.sourceDirectoryName)?.branchName;
+    if (snapshot.batchId !== request.batchId || snapshot.sourceWorkspaceId !== request.workspaceId
+        || snapshot.sourceDirectoryName !== request.sourceDirectoryName
+        || (request.persist === 'remote_ref' ? !snapshot.remoteRef || Boolean(snapshot.artifactKey) : !snapshot.artifactKey || Boolean(snapshot.remoteRef))
+        || (candidate && (candidate.persist !== request.persist || candidate.repositoryUrl !== (binding?.repositoryUrl ?? undefined)
+            || candidate.projectId !== binding?.projectId || candidate.branchName !== (branchName ?? undefined)
+            || candidate.snapshot.commitHash !== snapshot.commitHash || candidate.snapshot.digest !== snapshot.digest
+            || candidate.snapshot.frozenAt !== snapshot.frozenAt || candidate.snapshot.remoteRef !== snapshot.remoteRef
+            || candidate.snapshot.artifactKey !== snapshot.artifactKey))) {
+        throw new Error('batch_source_identity_mismatch');
+    }
+}