@playcraft/cli 0.1.71 → 0.1.72

package/dist/cli-root-help.js

@@ -8,6 +8,7 @@ export function getCliTopicsHelpText() {
         '  素材库     library list/search/facets/get/files/download',
         '  生成任务   assets estimate/generate/tasks/get/wait/cancel/download | assets animation',
         '  Remix 参考 references list/search/import（发现参考并读取当前工程中的固定快照）',
+        '             references prepare-starter-template（准备默认起始模板）',
         '  视频理解   video models | video understand | video jobs get/cancel',
         '  平台       build, build-base, build-playable, build-all, analyze, inspect, upgrade',
         '             tools 除 generate-* 外（Git / 沙箱构建 / 发布 / 列表 / Prefab 等，需后端 API）',

package/dist/commands/references.js

@@ -20,6 +20,8 @@ export function registerReferenceCommands(program) {
             const output = { schemaVersion: 'playcraft.references.v1', command: `references.${action}`, ...result };
             if (options.json)
                 console.log(JSON.stringify(output));
+            else if (action === 'prepare-starter-template')
+                console.log(result.path);
             else if (action === 'import') {
                 const reference = result.reference;
                 console.log(`${reference.name}\n${reference.resolvedPath}`);
@@ -43,6 +45,7 @@ export function registerReferenceCommands(program) {
     const scope = (command) => command.option('--workspace <id>', message('workspace'))
         .option('--directory <name>', message('directory')).option('--json', message('json'));
     scope(references.command('list').description(message('list'))).action(options => run('list', options));
+    scope(references.command('prepare-starter-template').description(message('prepareStarterTemplate'))).action(options => run('prepare-starter-template', options));
     scope(references.command('search [query]').description(message('search'))
         .option('--source <source>', message('source'), 'recommended')
         .option('--tag <value>', message('tag'), (value, previous) => [...previous, value], [])

package/dist/commands/tools-batch.js

@@ -100,6 +100,8 @@ export function registerBatchCommands(tools) {
     tools.command('get-batch')
         .description(t.status)
         .requiredOption('--batch-id <id>', t.id)
+        // Output is always JSON; accept the flag so status reads match create-batch and sync-batch.
+        .option('--json', 'JSON (JavaScript Object Notation, 数据交换格式)')
         .action(async (opts) => {
         try {
             const client = new AgentApiClient();

package/dist/references/messages.js

@@ -3,6 +3,7 @@ const messages = {
         description: 'Discover and import Remix source references for the current cloud workspace',
         list: 'List verified local Remix references and their paths', search: 'Search accessible recommended or community Remixes',
         import: 'Import a fixed Remix source snapshot into the current engineering directory',
+        prepareStarterTemplate: 'Prepare a verified starter template in a temporary directory',
         query: 'Search names, branches, tags, creators or templates', source: 'recommended or community', project: 'Source project identifier', branch: 'Exact source branch',
         tag: 'Match a tag value; repeat to match any of the values', tagCategory: 'Tag category; defaults to Gameplay when --tag is used',
         workspace: 'Current cloud workspace identifier (must match this conversation)', directory: 'Current engineering directory (must match this conversation)',
@@ -22,6 +23,7 @@ const messages = {
     zh: {
         description: '为当前云工作区发现并导入 Remix 源码参考',
         list: '列出已验证的本地 Remix 参考及路径', search: '搜索可访问的推荐或社区 Remix', import: '把固定版本的 Remix 源码参考导入当前工程',
+        prepareStarterTemplate: '将经过校验的起始模板准备到临时目录',
         query: '搜索名称、分支、标签、创建者或模板', source: 'recommended（推荐）或 community（社区）', project: '来源项目标识', branch: '准确的来源分支名',
         tag: '匹配的标签值；可重复指定，匹配任意一个值', tagCategory: '标签分类；使用 --tag 时默认为 Gameplay',
         workspace: '当前云工作区标识（必须与本对话一致）', directory: '当前工程目录（必须与本对话一致）',

package/dist/references/protocol.js

@@ -3,18 +3,38 @@ import { z } from 'zod';
 const scope = {
     cwd: z.string().min(1).max(4096),
     workspaceId: z.string().uuid().optional(),
-    directoryName: z.string().regex(/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/).optional(),
+    directoryName: z
+        .string()
+        .regex(/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/)
+        .optional(),
 };
-export const remixReferenceToolRequestSchema = z.discriminatedUnion('action', [
+export const remixReferenceToolRequestSchema = z
+    .discriminatedUnion('action', [
     z.object({ ...scope, action: z.literal('list') }).strict(),
-    z.object({ ...scope, action: z.literal('search'), source: z.enum(['recommended', 'community']),
+    z.object({ ...scope, action: z.literal('prepare-starter-template') }).strict(),
+    z
+        .object({
+        ...scope,
+        action: z.literal('search'),
+        source: z.enum(['recommended', 'community']),
         tagCategory: z.string().trim().min(1).max(128).optional(),
         tagValues: z.array(z.string().trim().min(1).max(255)).min(1).max(20).optional(),
-        q: z.string().max(200).optional(), page: z.number().int().min(1).max(10000).default(1),
-        limit: z.number().int().min(1).max(50).default(12) }).strict(),
-    z.object({ ...scope, action: z.literal('import'), projectUuid: z.string().uuid(),
-        branchName: z.string().min(1).max(255) }).strict(),
-]).refine(input => input.action !== 'search' || (input.tagCategory === undefined) === (input.tagValues === undefined));
+        q: z.string().max(200).optional(),
+        page: z.number().int().min(1).max(10000).default(1),
+        limit: z.number().int().min(1).max(50).default(12),
+    })
+        .strict(),
+    z
+        .object({
+        ...scope,
+        action: z.literal('import'),
+        projectUuid: z.string().uuid(),
+        branchName: z.string().min(1).max(255),
+    })
+        .strict(),
+])
+    .refine((input) => input.action !== 'search' ||
+    (input.tagCategory === undefined) === (input.tagValues === undefined));
 export class RemixReferenceToolError extends Error {
     code;
     constructor(code) {
@@ -25,8 +45,15 @@ export class RemixReferenceToolError extends Error {
 }
 export function localRemixReference(root, reference) {
     const { files, omittedFiles, ...metadata } = reference;
-    return { ...metadata, source: { ...metadata.source,
-            recommended: metadata.source.recommended ?? metadata.source.category === 'recommended' },
-        resolvedPath: join(root, reference.path), fileCount: files.length,
-        omittedFileCount: omittedFiles?.length ?? 0 };
+    return {
+        ...metadata,
+        source: {
+            ...metadata.source,
+            recommended: ('recommended' in metadata.source ? metadata.source.recommended : undefined) ??
+                metadata.source.category === 'recommended',
+        },
+        resolvedPath: join(root, reference.path),
+        fileCount: files.length,
+        omittedFileCount: omittedFiles?.length ?? 0,
+    };
 }

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

@@ -6,11 +6,11 @@ import { workspaceRoot } from '../workspaces/registry.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 { assertSourceIdentity, readSourceCandidate, writeSourceCandidate, } from './source-candidate.js';
 import { BatchSourceFreezeError, sourceFreezeError } from './source-failure.js';
 import { publishSourceCandidate } from './source-publish.js';
 import { clearDirectoryFreeze, withDirectoryFreeze } from '../server/directory-access.js';
-import { adoptPublicationBinding, publicationBinding, publicationGitOptions } from './publication.js';
+import { adoptPublicationBinding, publicationBinding, publicationGitOptions, } from './publication.js';
 async function usagePercent(path) {
     const disk = await statfs(path);
     if (disk.blocks <= 0)
@@ -23,7 +23,7 @@ async function stopManagedWriters(state, workspaceId, directoryName) {
     for (const write of state.journal.listManagedWrites()) {
         if (write.stoppedAt || write.workspaceId !== scope)
             continue;
-        if (write.pid === undefined || !await stopBackgroundWriter(write.pid))
+        if (write.pid === undefined || !(await stopBackgroundWriter(write.pid)))
             continue;
         await state.journal.putManagedWrite({ ...write, stoppedAt: new Date().toISOString() });
     }
@@ -42,8 +42,11 @@ export async function freezeBatchSource(state, body, options) {
         await clearDirectoryFreeze(state, request.batchId);
         return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: frozen });
     }
-    return withDirectoryFreeze(state, { workspaceId: request.workspaceId,
-        directoryName: request.sourceDirectoryName, batchId: request.batchId }, () => serializeFreeze(async () => {
+    return withDirectoryFreeze(state, {
+        workspaceId: request.workspaceId,
+        directoryName: request.sourceDirectoryName,
+        batchId: request.batchId,
+    }, () => serializeFreeze(async () => {
         let candidate;
         let source;
         try {
@@ -56,7 +59,12 @@ export async function freezeBatchSource(state, body, options) {
                 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' });
+                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);
@@ -70,26 +78,40 @@ export async function freezeBatchSource(state, body, options) {
             if (pending)
                 candidate = pending;
             else {
-                const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
+                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);
+                const captured = await captureIndependentSource(source, cache, request.starterTemplate, {
+                    batchId: request.batchId,
+                    workspaceId: request.workspaceId,
+                    directoryName: request.sourceDirectoryName,
+                });
                 // private
                 await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
                 const snapshot = {
-                    batchId: request.batchId, commitHash: captured.commitHash, digest: captured.digest,
-                    sourceWorkspaceId: request.workspaceId, sourceDirectoryName: request.sourceDirectoryName,
+                    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` }),
+                    ...(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,
+                    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);
@@ -98,12 +120,44 @@ export async function freezeBatchSource(state, body, options) {
         catch (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';
+            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',
+                'batch_source_candidate_lost',
+                'starter_template_unavailable',
+                'starter_template_invalid',
+                'starter_template_path_conflict',
+                'batch_source_ignored_files',
+            ]);
+            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',
+                code,
+                stage: 'capture',
+                retryable: !(code === 'batch_source_changed' &&
+                    request.starterTemplate &&
+                    'snapshot' in request.starterTemplate) &&
+                    ![
+                        'batch_source_path_invalid',
+                        'batch_source_identity_mismatch',
+                        'batch_source_snapshot_mismatch',
+                        'batch_source_candidate_lost',
+                        'starter_template_unavailable',
+                        'starter_template_invalid',
+                        'starter_template_path_conflict',
+                        'batch_source_ignored_files',
+                    ].includes(code),
+                outcome: code === 'batch_source_identity_mismatch' ||
+                    code === 'batch_source_snapshot_mismatch' ||
+                    code === 'batch_source_candidate_lost'
+                    ? 'unknown'
+                    : 'not_published',
             }, error);
         }
         await publishSourceCandidate(state, candidate, source, options?.objectStore ?? filesystemObjectStore(state), request.publication);
@@ -113,14 +167,30 @@ export async function freezeBatchSource(state, body, options) {
             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);
+            throw await sourceFreezeError(state, request.batchId, {
+                code: 'batch_source_verification_failed',
+                stage: 'verify',
+                retryable: true,
+                outcome: 'unknown',
+            }, error);
         }
-        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: candidate.snapshot });
+        return batchSourceFreezeResultSchema.parse({
+            status: 'frozen',
+            snapshot: candidate.snapshot,
+        });
     }), () => stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName), {
-        signal: options?.signal, deadline: 'deadline' in request && typeof request.deadline === 'string' ? request.deadline : undefined,
+        signal: options?.signal,
+        deadline: 'deadline' in request && typeof request.deadline === 'string'
+            ? request.deadline
+            : undefined,
     }).catch(async (error) => {
         if (error instanceof Error && error.message === 'directory_access_cancelled')
-            throw await sourceFreezeError(state, request.batchId, { code: 'source_freeze_timeout', stage: 'capture', retryable: false, outcome: 'not_published' });
+            throw await sourceFreezeError(state, request.batchId, {
+                code: 'source_freeze_timeout',
+                stage: 'capture',
+                retryable: false,
+                outcome: 'not_published',
+            });
         throw error;
     });
 }

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

@@ -1,7 +1,7 @@
 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';
+import { batchSourceSnapshotRefSchema, normalizeLegacyBatchSourceSnapshot, sandboxBatchMemberStatusSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { releaseBatchDirectory } from '../server/directory-access.js';
 const runs = new Map();
 let freezeChain = Promise.resolve();
@@ -29,7 +29,7 @@ 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 === '..'))
+    if (key.split('/').some((part) => !part || part === '.' || part === '..'))
         throw new Error('batch_object_key_invalid');
     return join(state.config.stateDir, 'batch-objects', key);
 }
@@ -53,7 +53,9 @@ async function readJson(path) {
 }
 export async function readSnapshot(state, batchId) {
     const value = await readJson(snapshotFile(state, batchId));
-    return value ? batchSourceSnapshotRefSchema.parse(value) : undefined;
+    return value
+        ? batchSourceSnapshotRefSchema.parse(normalizeLegacyBatchSourceSnapshot(value))
+        : undefined;
 }
 export async function writeSnapshot(state, snapshot) {
     const parsed = batchSourceSnapshotRefSchema.parse(snapshot);
@@ -70,7 +72,7 @@ export async function writeMember(state, record) {
 }
 export async function listMembers(state) {
     const directory = join(state.config.stateDir, 'batch-members');
-    const names = await readdir(directory).catch(error => {
+    const names = await readdir(directory).catch((error) => {
         if (error.code === 'ENOENT')
             return [];
         throw error;
@@ -111,7 +113,11 @@ export function memberStatus(record) {
 }
 export function filesystemObjectStore(state) {
     return {
-        async put(key, body) { await writeAtomic(objectFile(state, key), body); },
-        async get(key) { return readFile(objectFile(state, key)); },
+        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

@@ -1,4 +1,4 @@
-import { batchSourceFreezeResultSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { batchSourceFreezeResultSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
 import { stopBatchMember, readBatchMemberStatus } from './control.js';
 import { deliverBatchMember } from './deliver.js';
 import { freezeBatchSource } from './freeze.js';
@@ -6,17 +6,28 @@ 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',
+    '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) {
+async function readBody(request, maxBytes = 1024 * 1024) {
     const chunks = [];
     let size = 0;
     for await (const chunk of request) {
         size += chunk.length;
-        if (size > 1024 * 1024)
+        if (size > maxBytes)
             throw new Error('request_body_too_large');
         chunks.push(Buffer.from(chunk));
     }
@@ -30,7 +41,9 @@ export async function dispatchBatchRoute(state, request, url) {
     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' } };
+        return status
+            ? { status: 200, body: status }
+            : { status: 404, body: { error: 'batch_member_not_found' } };
     }
     if (method !== 'POST')
         return undefined;
@@ -40,7 +53,7 @@ export async function dispatchBatchRoute(state, request, url) {
             const disconnected = () => controller.abort();
             request.socket.once('close', disconnected);
             try {
-                const result = batchSourceFreezeResultSchema.parse(await freezeBatchSource(state, await readBody(request), { signal: controller.signal }));
+                const result = batchSourceFreezeResultSchema.parse(await freezeBatchSource(state, await readBody(request, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES), { signal: controller.signal }));
                 return { status: 200, body: result };
             }
             finally {
@@ -54,7 +67,10 @@ export async function dispatchBatchRoute(state, request, url) {
         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 {
+                status: 200,
+                body: await stopBatchMember(state, decodeURIComponent(member[1]), await readBody(request)),
+            };
         return undefined;
     }
     catch (error) {
@@ -63,7 +79,11 @@ export async function dispatchBatchRoute(state, request, url) {
         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;
+        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

@@ -1,7 +1,7 @@
 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';
+import { batchSourceSnapshotRefSchema, normalizeLegacyBatchSourceSnapshot, } from '@playcraft/common/cloud-workspace/runtime';
 import { publicationBinding } from './publication.js';
 export function sourceCandidateFile(state, batchId) {
     return join(state.config.stateDir, 'batch-source-candidates', `${batchId}.json`);
@@ -23,12 +23,16 @@ export async function readSourceCandidate(state, batchId) {
     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'))
+    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);
+    const parsed = batchSourceSnapshotRefSchema.safeParse(normalizeLegacyBatchSourceSnapshot(stored.snapshot));
     if (!parsed.success)
         throw new Error('batch_source_snapshot_mismatch');
     const snapshot = parsed.data;
@@ -74,16 +78,25 @@ export async function writeSourceCandidate(state, candidate) {
 }
 export function assertSourceIdentity(state, request, snapshot, candidate) {
     const binding = publicationBinding(state, request.workspaceId, request.sourceDirectoryName, request.publication);
-    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))) {
+    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');
     }
 }