@playcraft/cli 0.1.46-beta → 0.1.47-beta

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

@@ -1,12 +1,14 @@
-import { lstat, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { rm, writeFile } from 'node:fs/promises';
 import { statfs } from 'node:fs/promises';
 import { batchSourceFreezeResultSchema, batchSourceRemoteRef, sandboxBatchSourceFreezeRequestSchema, workspaceDiskAdmission, } from '@playcraft/common/cloud-workspace/runtime';
 import { stopBackgroundWriter } from '../processes/managed-writes.js';
 import { workspaceRoot } from '../workspaces/registry.js';
-import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
-import { archiveSource, captureIndependentSource } from './source-capture.js';
+import { gitRead } from './git.js';
+import { captureIndependentSource } from './source-capture.js';
 import { filesystemObjectStore, readSnapshot, serializeFreeze, sourceCacheDir, writeSnapshot, } from './records.js';
+import { assertSourceIdentity, readSourceCandidate, writeSourceCandidate } from './source-candidate.js';
+import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
+import { publishSourceCandidate } from './source-publish.js';
 async function usagePercent(path) {
     const disk = await statfs(path);
     if (disk.blocks <= 0)
@@ -27,76 +29,73 @@ async function stopManagedWriters(state, workspaceId, directoryName) {
         await state.journal.putManagedWrite({ ...write, stoppedAt: new Date().toISOString() });
     }
 }
-async function pushHiddenRef(cache, sourceRoot, remote, commit, ref) {
-    await copyCredentialHelpers(sourceRoot, cache);
-    try {
-        await gitWrite(cache, ['push', remote, `${commit}:${ref}`]);
-    }
-    catch {
-        throw new Error('batch_source_push_failed');
-    }
-    const remoteHash = (await gitWrite(cache, ['ls-remote', remote, ref]).catch(() => '')).slice(0, commit.length);
-    if (remoteHash !== commit)
-        throw new Error('batch_source_push_failed');
-}
 export async function freezeBatchSource(state, body, options) {
     const parsed = sandboxBatchSourceFreezeRequestSchema.safeParse(body);
     if (!parsed.success)
         throw new Error('invalid_batch_request');
     const request = parsed.data;
     return serializeFreeze(async () => {
-        const existing = await readSnapshot(state, request.batchId);
-        if (existing)
-            return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
-        const source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
-        const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
-        if (workspaceDiskAdmission(percent) === 'paused')
-            throw new Error('disk_admission_paused');
-        await stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName);
-        const cache = sourceCacheDir(state, request.batchId);
-        await rm(cache, { recursive: true, force: true });
-        const captured = await captureIndependentSource(source, cache);
-        await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
-        const binding = state.journal.getWorkspace(request.workspaceId);
-        const frozenAt = new Date((await gitRead(cache, ['show', '-s', '--format=%cI', 'HEAD'])).trim()).toISOString();
-        const snapshot = {
-            batchId: request.batchId,
-            commitHash: captured.commitHash,
-            digest: captured.digest,
-            sourceWorkspaceId: request.workspaceId,
-            sourceDirectoryName: request.sourceDirectoryName,
-            frozenAt,
-        };
+        let candidate;
+        let source;
         try {
-            if (request.persist === 'remote_ref') {
-                if (!binding?.repositoryUrl)
-                    throw new Error('batch_source_push_failed');
-                const ref = batchSourceRemoteRef(request.batchId);
-                await pushHiddenRef(cache, source, binding.repositoryUrl, captured.commitHash, ref);
-                snapshot.remoteRef = ref;
+            const pending = await readSourceCandidate(state, request.batchId);
+            const existing = await readSnapshot(state, request.batchId);
+            if (existing) {
+                assertSourceIdentity(state, request, existing, pending);
+                return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
+            }
+            if (!pending && 'resumeOnly' in request && request.resumeOnly === true) {
+                throw await sourceFreezeError(state, request.batchId, { code: 'batch_source_candidate_lost', stage: 'capture', retryable: false, outcome: 'unknown' });
             }
+            if (pending)
+                assertSourceIdentity(state, request, pending.snapshot, pending);
+            source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
+            if (pending)
+                candidate = pending;
             else {
-                const key = `workspaces/${request.workspaceId}/batches/${request.batchId}/source/${captured.digest}.json.gz`;
-                const store = options?.objectStore ?? filesystemObjectStore(state);
-                try {
-                    await store.put(key, await archiveSource(cache, captured));
-                }
-                catch (error) {
-                    if (error instanceof Error && error.message === 'batch_object_key_invalid')
-                        throw error;
-                    throw new Error('batch_source_upload_failed');
-                }
-                snapshot.artifactKey = key;
+                const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
+                if (workspaceDiskAdmission(percent) === 'paused')
+                    throw new Error('disk_admission_paused');
+                await stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName);
+                const cache = sourceCacheDir(state, request.batchId);
+                await rm(cache, { recursive: true, force: true });
+                const captured = await captureIndependentSource(source, cache);
+                await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
+                const binding = state.journal.getWorkspace(request.workspaceId);
+                const snapshot = {
+                    batchId: request.batchId, commitHash: captured.commitHash, digest: captured.digest,
+                    sourceWorkspaceId: request.workspaceId, sourceDirectoryName: request.sourceDirectoryName,
+                    frozenAt: new Date((await gitRead(cache, ['show', '-s', '--format=%cI', 'HEAD'])).trim()).toISOString(),
+                    ...(request.persist === 'remote_ref' ? { remoteRef: batchSourceRemoteRef(request.batchId) }
+                        : { artifactKey: `workspaces/${request.workspaceId}/batches/${request.batchId}/source/${captured.digest}.json.gz` }),
+                };
+                candidate = {
+                    version: 1, persist: request.persist, repositoryUrl: binding?.repositoryUrl ?? undefined, projectId: binding?.projectId,
+                    branchName: request.sourceDirectoryName === 'basic' ? binding?.branchName ?? undefined
+                        : binding?.directories?.find(directory => directory.directoryName === request.sourceDirectoryName)?.branchName ?? undefined,
+                    snapshot,
+                };
+                await writeSourceCandidate(state, candidate);
             }
         }
         catch (error) {
-            await rm(cache, { recursive: true, force: true });
-            await rm(`${cache}.digest`, { force: true });
-            throw error;
+            if (error instanceof BatchSourceFreezeError)
+                throw error;
+            const known = new Set(['disk_admission_paused', 'disk_usage_unavailable', 'batch_source_changed', 'batch_source_path_invalid',
+                'workspace_not_registered', 'batch_source_identity_mismatch', 'batch_source_snapshot_mismatch']);
+            const code = error instanceof Error && known.has(error.message) ? error.message : 'batch_source_capture_failed';
+            throw await sourceFreezeError(state, request.batchId, {
+                code, stage: 'capture', retryable: !['batch_source_path_invalid', 'batch_source_identity_mismatch', 'batch_source_snapshot_mismatch'].includes(code),
+                outcome: code === 'batch_source_identity_mismatch' || code === 'batch_source_snapshot_mismatch' ? 'unknown' : 'not_published',
+            }, error);
+        }
+        await publishSourceCandidate(state, candidate, source, options?.objectStore ?? filesystemObjectStore(state));
+        try {
+            await writeSnapshot(state, candidate.snapshot);
+        }
+        catch (error) {
+            throw await sourceFreezeError(state, request.batchId, { code: 'batch_source_verification_failed', stage: 'verify', retryable: true, outcome: 'unknown' }, error);
         }
-        if (!await lstat(join(cache, '.git')).catch(() => undefined))
-            throw new Error('batch_source_capture_failed');
-        await writeSnapshot(state, snapshot);
-        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot });
+        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: candidate.snapshot });
     });
 }

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

@@ -4,6 +4,7 @@ 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',
@@ -49,6 +50,8 @@ export async function dispatchBatchRoute(state, request, url) {
         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;

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');
+    }
+}

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

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class BatchSourceFreezeError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.code);
+        this.failure = failure;
+        this.name = 'BatchSourceFreezeError';
+    }
+}
+/** Diagnostics keep the upstream reason without command arguments, authentication or remote addresses. */
+function redactedReason(error) {
+    const detail = error;
+    const text = typeof detail?.stderr === 'string' || typeof detail?.stdout === 'string'
+        ? `${typeof detail.stderr === 'string' ? detail.stderr : ''}\n${typeof detail.stdout === 'string' ? detail.stdout : ''}`
+        : typeof detail?.message === 'string' ? detail.message : 'unknown';
+    return text
+        .replace(/https?:\/\/[^\s<>"']+/gi, '<remote>')
+        .replace(/\b(Bearer|Basic)\s+[^\s,;"']+/gi, '$1 <redacted>')
+        .replace(/((?:password|token|secret|authorization|credential)\s*[:=]\s*)[^\s,;"']+/gi, '$1<redacted>')
+        .replace(/\b(?:gh[pousr]_|github_pat_|glpat-)[A-Za-z0-9_-]+/g, '<redacted>')
+        .slice(0, 16_384);
+}
+export async function sourceFreezeError(state, batchId, failure, cause) {
+    if (cause === undefined)
+        return new BatchSourceFreezeError(failure);
+    const diagnosticId = randomUUID();
+    const directory = join(state.config.stateDir, 'batch-source-diagnostics');
+    const detail = cause;
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await writeFile(join(directory, `${diagnosticId}.json`), JSON.stringify({
+            diagnosticId, batchId, ...failure, recordedAt: new Date().toISOString(), reason: redactedReason(cause),
+            exitCode: typeof detail?.code === 'number' ? detail.code : undefined,
+            signal: typeof detail?.signal === 'string' && /^SIG[A-Z]+$/.test(detail.signal) ? detail.signal : undefined,
+        }), { mode: 0o600, flag: 'wx' });
+        return new BatchSourceFreezeError({ ...failure, diagnosticId });
+    }
+    catch {
+        return new BatchSourceFreezeError(failure);
+    }
+}

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

@@ -0,0 +1,132 @@
+import { lstat, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
+import { archiveSource, digestFiles, readSourceFiles, restoreArchive } from './source-capture.js';
+import { sourceCacheDir } from './records.js';
+import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
+async function reject(state, candidate, code, stage, retryable, outcome, cause) {
+    throw await sourceFreezeError(state, candidate.snapshot.batchId, { code, stage, retryable, outcome }, cause);
+}
+async function verifyCache(cache, candidate) {
+    if ((await gitRead(cache, ['rev-parse', '--verify', 'HEAD']).catch(() => '')).trim() !== candidate.snapshot.commitHash)
+        return false;
+    return digestFiles(await readSourceFiles(cache)) === candidate.snapshot.digest;
+}
+function pushFailureCode(error) {
+    const detail = error;
+    return /not support[^\n]*(?:ref|push)|unsupported[^\n]*(?:ref|namespace)/i.test(`${detail?.stderr ?? ''}\n${detail?.stdout ?? ''}`)
+        ? 'batch_source_ref_unsupported' : 'batch_source_push_failed';
+}
+function definitelyRejected(error) {
+    const detail = error;
+    return /remote rejected|\[rejected\]|authentication failed|access denied|permission denied|not allowed|not support|hook declined|protected|returned error: (?:401|403)/i
+        .test(`${detail?.stderr ?? ''}\n${detail?.stdout ?? ''}`);
+}
+async function publishRemote(state, candidate, source) {
+    const { snapshot, repositoryUrl: remote } = candidate;
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    if (!remote || !snapshot.remoteRef)
+        return reject(state, candidate, 'batch_source_push_failed', 'publish', false, 'not_published');
+    await mkdir(cache, { recursive: true, mode: 0o700 });
+    if (!await lstat(join(cache, '.git')).catch(() => undefined))
+        await gitWrite(cache, ['init', '--initial-branch', 'source']);
+    await copyCredentialHelpers(source, cache);
+    // All remote operations share the copied authentication, including read-only verification.
+    const remoteHash = async () => {
+        const output = await gitWrite(cache, ['ls-remote', '--refs', remote, snapshot.remoteRef]);
+        const rows = output.trim().split('\n').filter(Boolean).map(line => line.split(/\s+/));
+        if (rows.some(([hash, ref]) => !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(hash) || ref !== snapshot.remoteRef) || rows.length > 1) {
+            throw new Error('batch_source_remote_response_invalid');
+        }
+        return rows[0]?.[0];
+    };
+    let found;
+    try {
+        found = await remoteHash();
+    }
+    catch (error) {
+        return reject(state, candidate, 'batch_source_verification_failed', 'verify', true, 'unknown', error);
+    }
+    if (found && found !== snapshot.commitHash)
+        return reject(state, candidate, 'batch_source_ref_conflict', 'verify', false, 'unknown');
+    if (!found) {
+        if (!await verifyCache(cache, candidate))
+            return reject(state, candidate, 'batch_source_candidate_lost', 'capture', false, 'not_published');
+        let pushError;
+        try {
+            await gitWrite(cache, ['push', '--porcelain', remote, `${snapshot.commitHash}:${snapshot.remoteRef}`]);
+        }
+        catch (error) {
+            pushError = error;
+        }
+        try {
+            found = await remoteHash();
+        }
+        catch (error) {
+            const unsupported = pushError !== undefined && pushFailureCode(pushError) === 'batch_source_ref_unsupported';
+            return reject(state, candidate, pushError ? pushFailureCode(pushError) : 'batch_source_verification_failed', pushError ? 'publish' : 'verify', !unsupported, unsupported ? 'not_published' : 'unknown', pushError ?? error);
+        }
+        if (found && found !== snapshot.commitHash)
+            return reject(state, candidate, 'batch_source_ref_conflict', 'verify', false, 'unknown', pushError);
+        if (!found) {
+            const rejected = pushError !== undefined && definitelyRejected(pushError);
+            return reject(state, candidate, pushError ? pushFailureCode(pushError) : 'batch_source_verification_failed', pushError ? 'publish' : 'verify', !rejected, rejected ? 'not_published' : 'unknown', pushError);
+        }
+    }
+    if (!await verifyCache(cache, candidate)) {
+        try {
+            await gitWrite(cache, ['fetch', '--no-tags', remote, snapshot.remoteRef]);
+            if ((await gitRead(cache, ['rev-parse', 'FETCH_HEAD^{commit}'])).trim() !== snapshot.commitHash) {
+                return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+            }
+            await gitWrite(cache, ['checkout', '--detach', snapshot.commitHash]);
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_verification_failed', 'verify', true, 'unknown', error);
+        }
+        if (!await verifyCache(cache, candidate))
+            return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+    }
+    await writeFile(`${cache}.digest`, snapshot.digest, { mode: 0o600 });
+}
+async function publishArtifact(state, candidate, store) {
+    const { snapshot } = candidate;
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    if (!snapshot.artifactKey)
+        return reject(state, candidate, 'batch_source_snapshot_mismatch', 'capture', false, 'not_published');
+    if (!await verifyCache(cache, candidate)) {
+        // A lost cache can only be restored from this candidate's already published archive.
+        try {
+            const archive = await store.get(snapshot.artifactKey);
+            await rm(cache, { recursive: true, force: true });
+            const restored = await restoreArchive(archive, cache, snapshot.digest);
+            if (restored.commitHash !== snapshot.commitHash)
+                return reject(state, candidate, 'batch_source_snapshot_mismatch', 'verify', false, 'unknown');
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_candidate_lost', 'capture', false, 'unknown', error);
+        }
+    }
+    else {
+        try {
+            await store.put(snapshot.artifactKey, await archiveSource(cache, snapshot));
+        }
+        catch (error) {
+            return reject(state, candidate, 'batch_source_upload_failed', 'publish', true, 'unknown', error);
+        }
+    }
+    await writeFile(`${cache}.digest`, snapshot.digest, { mode: 0o600 });
+}
+export async function publishSourceCandidate(state, candidate, source, store) {
+    try {
+        if (candidate.persist === 'remote_ref')
+            await publishRemote(state, candidate, source);
+        else
+            await publishArtifact(state, candidate, store);
+    }
+    catch (error) {
+        if (error instanceof BatchSourceFreezeError)
+            throw error;
+        throw await sourceFreezeError(state, candidate.snapshot.batchId, { code: 'batch_source_verification_failed', stage: 'verify', retryable: true, outcome: 'unknown' }, error);
+    }
+}

package/dist/workspace-runtime/server/http.js

@@ -93,6 +93,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 permissionsVersion: 1,
                 composerContextVersion: 1,
                 remixReferencesVersion: 1,
+                batchSourceFreezeRevision: 2,
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
                 ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
                 ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),

package/dist/workspace-runtime/verify-artifact.js

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { readFile, mkdtemp, rm } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { batchSourceRemoteRef, parseSandboxRuntimeConfig } from '@playcraft/common/cloud-workspace/runtime';
+import { createLoopbackNativeAdapter } from './codex/loopback.js';
+import { startWorkspaceRuntime } from './serve.js';
+async function dependencyVersion(name, entry) {
+    let directory = dirname(createRequire(import.meta.url).resolve(entry));
+    for (;;) {
+        const metadata = await readFile(join(directory, 'package.json'), 'utf8').then(JSON.parse).catch(() => undefined);
+        if (metadata?.name === name)
+            return metadata.version;
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error(`package_metadata_missing:${name}`);
+        directory = parent;
+    }
+}
+/** Starts only an isolated temporary runtime; never reads or changes an existing workspace. */
+export async function verifyRuntimeArtifact(expectedVersion) {
+    assert.match(expectedVersion, /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/);
+    const metadata = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+    assert.equal(metadata.version, expectedVersion, 'command package version differs from the release target');
+    assert.equal(await dependencyVersion('@playcraft/common', '@playcraft/common/cloud-workspace/runtime'), expectedVersion);
+    assert.equal(await dependencyVersion('@playcraft/build', '@playcraft/build'), expectedVersion);
+    const batchId = randomUUID();
+    assert.equal(batchSourceRemoteRef(batchId), `refs/tags/playcraft/batch/${batchId}/source`, 'installed shared library lacks standard tag references for source snapshots');
+    const directory = await mkdtemp(join(tmpdir(), 'playcraft-artifact-verify-'));
+    let runtime;
+    try {
+        const config = parseSandboxRuntimeConfig({
+            protocolMajor: 1, protocolMinor: 0, environment: 'artifact-verification',
+            runtimeId: randomUUID(), userId: 'artifact-verification', generation: 1, runtimeEpoch: 0,
+            workspaceMode: 'multi', workspaceRoot: join(directory, 'workspaces'), stateDir: join(directory, 'state'),
+            publicBaseUrl: 'http://127.0.0.1:9', controlToken: randomUUID(), cliVersion: expectedVersion,
+            listen: { host: '127.0.0.1', port: 0 },
+        });
+        runtime = await startWorkspaceRuntime(config, { nativeAdapter: createLoopbackNativeAdapter() });
+        const response = await fetch(`${runtime.url}/runtime/identity`, {
+            headers: { authorization: `Bearer ${config.controlToken}` }, signal: AbortSignal.timeout(10_000),
+        });
+        assert.equal(response.status, 200, 'built runtime identity is unavailable');
+        const identity = await response.json();
+        assert.equal(identity.runtimeId, config.runtimeId);
+        assert.equal(identity.batchSourceFreezeRevision, 2, 'built runtime lacks the required batch source freeze implementation');
+    }
+    finally {
+        await runtime?.close();
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    await verifyRuntimeArtifact(process.argv[2] ?? '');
+    console.log('Runtime artifact verified: batchSourceFreezeRevision=2');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.46-beta",
+  "version": "0.1.47-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -51,8 +51,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.46-beta",
-    "@playcraft/common": "^0.1.46-beta",
+    "@playcraft/build": "0.1.47-beta",
+    "@playcraft/common": "0.1.47-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",