@playcraft/cli 0.1.42 → 0.1.43-beta

package/dist/video-replication/comparison-messages.js

@@ -0,0 +1,104 @@
+const messages = {
+    en: {
+        compare: 'Compare a recorded playable with its reference and extract paired evidence',
+        processing: 'static | agentic (defaults to static)',
+        reference: 'Original local reference video', analysis: 'Completed reference analysis.json',
+        candidate: 'Locally recorded candidate video', recording: 'Recording metadata.json with input and control evidence',
+        policy: 'Optional versioned comparison policy JSON', kind: 'understanding | comparison (defaults to understanding)',
+        invalidComparison: 'Comparison arguments or policy are invalid.',
+        unsafeOutput: 'The comparison output contains a linked or invalid directory or artifact. Choose a safe output directory.',
+        invalidRecording: 'Recording metadata, source hashes, input logs, or controls are invalid.',
+        staleRecording: 'The project changed after recording. Make a fresh recording before comparison.',
+        comparisonContext: 'The reference analysis does not match the reference video.',
+        comparisonResume: 'The saved comparison request is missing or does not match this run and workspace.',
+        comparisonUnavailable: 'No authorized model supports the requested comparison.',
+        comparisonResult: 'The comparison service returned invalid or incomplete evidence.',
+        comparisonFailed: 'Comparison failed. Inspect its saved request and task before retrying.',
+        summary: 'Comparison', decision: 'Policy decision', alignment: 'Model event alignment',
+        differences: 'Model-observed differences and modification suggestions', coverage: 'Coverage and uncertainty',
+        evidence: 'Paired evidence', controls: 'Model interpretation of interaction controls',
+        reportStatus: 'Result', reportRequiredKinds: 'Required event kinds', reportMissingKinds: 'Missing event kinds',
+        reportMissingEvidence: 'Missing or uncertain evidence', reportTimingChecks: 'Deterministic timing checks', reportNone: 'none',
+        modelObservations: 'Model observations', modelSummary: 'Model summary', modelDimensions: 'Model dimension judgments',
+        modelObservationNotice: 'These are model observations and interpretations. A model pass does not override the policy decision or missing evidence above.',
+        policyPassedNotice: 'Policy acceptance passed for this recorded scenario.',
+        policyNotPassedNotice: 'Policy acceptance has not passed. Gameplay equivalence has not been established.',
+        deterministicNotice: 'Coverage and timing checks below are deterministic. Missing evidence remains unverified even when a model observation says pass.',
+        interactionUnverified: 'Interaction is not fully verified: required causal or control evidence is missing or uncertain.',
+        timingUnverified: 'Timing is not fully verified: evidence precision or coverage is insufficient for the policy tolerance.',
+        reasonReferenceKindMissing: 'Reference analysis lacks a required event kind.',
+        reasonEventPairMissing: 'Reference and candidate lack a sufficiently confident event pair.',
+        reasonDimensionUncertain: 'The model judgment for this dimension is uncertain or below the required confidence.',
+        reasonDimensionEventMissing: 'This dimension does not cover a required event.',
+        reasonProgressionEvidenceMissing: 'Evidence for event progression timing is missing or insufficient.',
+        reasonTimingPrecisionInsufficient: 'Timing precision or coverage cannot resolve the policy tolerance.',
+        reasonTimingFailureUnverified: 'The model timing failure is not confirmed by deterministic timing checks.',
+        reasonRequiredEffectsMissing: 'Required gameplay results are not linked to recorded input steps.',
+        reasonControlRuntimeUncertain: 'A control recording contains runtime errors or failed requests.',
+        reasonControlEvidenceMissing: 'Required control evidence is missing, uncertain, or does not cover the candidate result window.',
+        reasonRequestsFailed: 'The candidate recording contains failed network requests.',
+        reportScope: 'Scope', reportModel: 'Model', reportPolicy: 'Policy', reportRecording: 'Recording',
+        reportExpected: 'Expected', reportObserved: 'Observed', reportSuggestedFix: 'Suggested fix',
+        reportConfidence: 'Confidence', reportEvidence: 'evidence', reportReference: 'reference', reportCandidate: 'candidate',
+        reportRequired: 'Required', reportEvaluated: 'Evaluated', reportMissing: 'Missing', reportTiming: 'Timing',
+        reportTolerance: 'tolerance', reportRequested: 'requested', reportDecoded: 'decoded', reportFrame: 'frame',
+        coverageNotice: 'This result covers only the recorded scenario. Audio and unshown gameplay branches were not evaluated.',
+    },
+    zh: {
+        compare: '比较复刻玩法录像与参考视频，并抽取成对证据',
+        processing: 'static | agentic，默认 static',
+        reference: '本地原始参考视频', analysis: '已完成的参考分析 analysis.json',
+        candidate: '本地录制的候选视频', recording: '包含输入和对照证据的录制 metadata.json',
+        policy: '可选的版本化比较策略 JSON', kind: 'understanding | comparison，默认 understanding',
+        invalidComparison: '比较参数或策略无效。',
+        unsafeOutput: '比较输出目录或制品包含符号链接或无效文件，请使用安全的输出目录。',
+        invalidRecording: '录制元数据、视频摘要、输入日志或对照证据无效。',
+        staleRecording: '工程在录制后发生了变化，请重新录制再比较。',
+        comparisonContext: '参考分析与参考视频不一致。',
+        comparisonResume: '比较请求不存在，或与任务、工作区不一致。',
+        comparisonUnavailable: '没有有权使用且支持所需比较模式的模型。',
+        comparisonResult: '比较服务返回的证据无效或不完整。',
+        comparisonFailed: '比较失败，请先核对已保存的请求和任务再重试。',
+        summary: '比较报告', decision: '策略结论', alignment: '模型事件配对',
+        differences: '模型观察到的差异和修改建议', coverage: '覆盖范围与未知项', evidence: '成对证据',
+        controls: '模型对交互对照的解释', coverageNotice: '结论仅覆盖本次录制场景；音频及未展示的玩法分支尚未评估。',
+        reportStatus: '结论', reportRequiredKinds: '必需事件类型', reportMissingKinds: '缺失事件类型',
+        reportMissingEvidence: '缺失或不确定的证据', reportTimingChecks: '确定性时序检查', reportNone: '无',
+        modelObservations: '模型观察', modelSummary: '模型摘要', modelDimensions: '模型维度判断',
+        modelObservationNotice: '以下内容是模型的观察和解释。模型判断为 pass，不会覆盖前面的策略结论或证据缺口。',
+        policyPassedNotice: '本次录制场景已通过策略验收。',
+        policyNotPassedNotice: '策略验收尚未通过，玩法等价性尚未得到验证。',
+        deterministicNotice: '以下覆盖范围和时序检查由确定性规则计算。即使模型判断为 pass，缺失证据的部分仍未得到验证。',
+        interactionUnverified: '交互尚未完整验证：必需的因果或对照证据缺失或不确定。',
+        timingUnverified: '时序尚未完整验证：证据精度或覆盖不足，无法满足策略容差。',
+        reasonReferenceKindMissing: '参考分析缺少必需的事件类型。',
+        reasonEventPairMissing: '参考视频与候选视频缺少达到置信度要求的事件配对。',
+        reasonDimensionUncertain: '模型对该维度的判断不确定，或未达到置信度要求。',
+        reasonDimensionEventMissing: '该维度尚未覆盖必需事件。',
+        reasonProgressionEvidenceMissing: '事件进展的时序证据缺失或不足。',
+        reasonTimingPrecisionInsufficient: '时序证据的精度或覆盖不足，无法按策略容差得出结论。',
+        reasonTimingFailureUnverified: '模型报告的时序失败尚未得到确定性时序检查的确认。',
+        reasonRequiredEffectsMissing: '必需的玩法结果尚未关联到录制输入步骤。',
+        reasonControlRuntimeUncertain: '对照录制存在运行错误或网络请求失败。',
+        reasonControlEvidenceMissing: '必需的对照证据缺失、不确定，或未覆盖候选结果的时间窗口。',
+        reasonRequestsFailed: '候选录制存在网络请求失败。',
+        reportScope: '范围', reportModel: '模型', reportPolicy: '策略', reportRecording: '录制',
+        reportExpected: '预期', reportObserved: '实际', reportSuggestedFix: '修改建议',
+        reportConfidence: '置信度', reportEvidence: '证据', reportReference: '参考', reportCandidate: '候选',
+        reportRequired: '必需', reportEvaluated: '已评估', reportMissing: '缺失', reportTiming: '时序',
+        reportTolerance: '容差', reportRequested: '请求时刻', reportDecoded: '解码时刻', reportFrame: '帧',
+    },
+};
+export function comparisonMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}
+export class ComparisonCliError extends Error {
+    code;
+    exitCode;
+    constructor(code, exitCode = 4) {
+        super(comparisonMessage(code));
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}

package/dist/video-replication/comparison-output.js

@@ -0,0 +1,63 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, parse, resolve, sep } from 'node:path';
+import { ComparisonCliError } from './comparison-messages.js';
+export async function comparisonOutputRoot(root, create = false) {
+    const absolute = resolve(root), prefix = parse(absolute).root;
+    let current = prefix;
+    for (const part of absolute.slice(prefix.length).split(sep).filter(Boolean)) {
+        current = join(current, part);
+        if (create)
+            await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink()) {
+            // macOS exposes system-managed temporary directories through these aliases.
+            const systemAlias = process.platform === 'darwin' && ['/tmp', '/var'].includes(current)
+                && await realpath(current) === `/private${current}`;
+            if (!systemAlias)
+                throw new ComparisonCliError('unsafeOutput', 64);
+            current = await realpath(current);
+        }
+        else if (!stat.isDirectory())
+            throw new ComparisonCliError('unsafeOutput', 64);
+    }
+    return realpath(current);
+}
+/** Refuse linked output directories and files, including artifacts left before resume. */
+export async function comparisonOutputPath(root, relative) {
+    if (isAbsolute(relative) || relative.includes('\\') || relative.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new ComparisonCliError('unsafeOutput', 64);
+    let current = await comparisonOutputRoot(root);
+    const parts = relative.split('/');
+    for (const part of parts.slice(0, -1)) {
+        current = join(current, part);
+        await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new ComparisonCliError('unsafeOutput', 64);
+    }
+    const path = join(current, parts.at(-1));
+    const stat = await lstat(path).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (stat && (!stat.isFile() || stat.isSymbolicLink()))
+        throw new ComparisonCliError('unsafeOutput', 64);
+    return path;
+}
+/** Writers use a private random sibling and replace the destination without following it. */
+export async function writeComparisonArtifact(root, relative, writer) {
+    const target = await comparisonOutputPath(root, relative);
+    const temporary = join(dirname(target), `.comparison-${randomUUID()}.tmp${extname(target)}`);
+    try {
+        await writer(temporary);
+        await comparisonOutputPath(root, relative);
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function writeComparisonJson(root, relative, value) {
+    await writeComparisonArtifact(root, relative, temporary => writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' }));
+}

package/dist/video-replication/comparison-preflight.js

@@ -0,0 +1,66 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { canonicalReplicaJson, replicaRecordingMetadataSchema, videoUnderstandingAnalysisSchema, validateVideoUnderstandingContent, } from '@playcraft/common/agent-tools';
+import { computeProjectInputDigest } from '../recording/project-digest.js';
+import { probeVideo } from './media.js';
+import { ComparisonCliError } from './comparison-messages.js';
+import { validateComparisonConsoleLog, validateComparisonInputLog } from './comparison-log.js';
+import { comparisonSha256, readComparisonJson, recordingArtifactPath, verifyRecordingArtifact } from './comparison-files.js';
+function sameSource(actual, expected) {
+    return actual.sha256 === expected.sha256 && actual.sizeBytes === expected.sizeBytes && actual.mimeType === expected.mimeType
+        && Math.abs(actual.durationMs - expected.durationMs) < 1 && actual.width === expected.width && actual.height === expected.height;
+}
+/** Validate hashes and the live checkout before any managed upload or model submission. */
+export async function preflightComparison(input) {
+    const probe = input.probe ?? probeVideo;
+    let recording;
+    let analysis;
+    try {
+        recording = replicaRecordingMetadataSchema.parse(await readComparisonJson(input.recording));
+        analysis = videoUnderstandingAnalysisSchema.parse(await readComparisonJson(input.analysis));
+        validateVideoUnderstandingContent({ summary: analysis.summary, observations: analysis.observations, events: analysis.events, evidence: analysis.evidence, inferences: analysis.inferences, unknowns: analysis.unknowns, reconstructionHints: analysis.reconstructionHints }, analysis.source);
+    }
+    catch {
+        throw new ComparisonCliError('invalidRecording', 64);
+    }
+    if (comparisonSha256(canonicalReplicaJson(recording.scenario)) !== recording.scenarioSha256)
+        throw new ComparisonCliError('invalidRecording', 64);
+    const cwd = resolve(input.cwd ?? process.cwd());
+    const root = dirname(resolve(input.recording));
+    const current = await computeProjectInputDigest(cwd, [root, resolve(input.out)]);
+    if (resolve(recording.project.root) !== current.root || recording.project.sha256 !== current.sha256 || recording.project.fileCount !== current.fileCount)
+        throw new ComparisonCliError('staleRecording', 64);
+    const reference = await probe(resolve(input.reference), input.signal);
+    if (!sameSource(reference.source, analysis.source))
+        throw new ComparisonCliError('comparisonContext', 64);
+    const candidatePath = await recordingArtifactPath(root, recording.candidate.video.path);
+    const candidate = await probe(resolve(input.candidate), input.signal);
+    if (candidate.path !== candidatePath || !sameSource(candidate.source, recording.candidate.video.source))
+        throw new ComparisonCliError('invalidRecording', 64);
+    const inputs = [{ id: 'reference', role: 'reference', video: reference }, { id: recording.candidate.id, role: 'candidate', video: candidate }];
+    for (const artifact of [recording.candidate, ...recording.controls]) {
+        input.signal.throwIfAborted();
+        const events = await verifyRecordingArtifact(root, artifact.events);
+        const consolePath = await verifyRecordingArtifact(root, artifact.console);
+        for (const shot of artifact.screenshots ?? [])
+            await verifyRecordingArtifact(root, shot, 16 * 1024 * 1024);
+        // Logs must contain structured records; an empty candidate input log cannot establish real interaction.
+        const text = await readFile(events, 'utf8');
+        try {
+            const records = text.trim() ? text.trim().split('\n').map(line => JSON.parse(line)) : [];
+            validateComparisonInputLog(records, recording.scenario, artifact);
+            const consoleText = await readFile(consolePath, 'utf8');
+            validateComparisonConsoleLog(consoleText.trim() ? consoleText.trim().split('\n').map(line => JSON.parse(line)) : [], artifact);
+        }
+        catch {
+            throw new ComparisonCliError('invalidRecording', 64);
+        }
+        if (artifact.kind !== 'candidate') {
+            const video = await probe(await recordingArtifactPath(root, artifact.video.path), input.signal);
+            if (!sameSource(video.source, artifact.video.source))
+                throw new ComparisonCliError('invalidRecording', 64);
+            inputs.push({ id: artifact.id, role: 'control', video });
+        }
+    }
+    return { recording, analysis, inputs };
+}

package/dist/video-replication/comparison.js

@@ -0,0 +1,230 @@
+import { randomUUID } from 'node:crypto';
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { canonicalReplicaJson, evaluateReplicaComparison, replicaDefaultPolicy, replicaPolicySchema, replicaValidationResultSchema, validateReplicaComparisonContext, validateReplicaComparisonContent, videoComparisonRequestSchema, videoComparisonRunSchema, videoModelCatalogSchema, } from '@playcraft/common/agent-tools';
+import { ensureVideoEvidenceGitExcluded } from '../utils/video-evidence-git.js';
+import { requireVideoId, resolveVideoWorkspace, uploadVideo } from './client.js';
+import { VideoCliError, videoMessage } from './messages.js';
+import { describeVideoFailure, remoteVideoFailure } from './diagnostics.js';
+import { comparisonMessage, ComparisonCliError } from './comparison-messages.js';
+import { comparisonSha256, readComparisonJson } from './comparison-files.js';
+import { preflightComparison } from './comparison-preflight.js';
+import { comparisonOutputPath, comparisonOutputRoot, writeComparisonJson } from './comparison-output.js';
+async function prepareComparisonOutput(out, runId, resume) {
+    if (!(await ensureVideoEvidenceGitExcluded(process.cwd())))
+        console.error(videoMessage('gitExcludeWarning'));
+    await comparisonOutputRoot(out, true);
+    await comparisonOutputPath(out, 'request.json');
+    const names = await readdir(out);
+    if (!names.length && !resume)
+        return;
+    try {
+        const saved = await readComparisonJson(join(out, 'request.json'));
+        if (resume && saved.schemaVersion === 'playcraft.video-comparison-local-request.v1' && saved.runId === runId && saved.out === out)
+            return;
+    }
+    catch { /* Preserve unrelated output directories. */ }
+    throw new VideoCliError('outputConflict', 64);
+}
+export async function readComparisonRun(client, runId, workspaceId, signal, cancel = false) {
+    const value = cancel ? await client.post(`/video-comparison/${runId}/cancel`, { workspaceId, runId }, { signal })
+        : await client.get(`/video-comparison/${runId}`, { workspaceId }, { signal });
+    let run;
+    try {
+        run = videoComparisonRunSchema.parse(value);
+    }
+    catch {
+        throw new ComparisonCliError('comparisonResult');
+    }
+    if (run.runId !== runId || run.workspaceId !== workspaceId || run.comparison && run.comparison.runId !== runId)
+        throw new ComparisonCliError('comparisonResult');
+    return run;
+}
+export function comparisonRunResult(command, run) {
+    const status = run.comparison?.status;
+    const exitCode = run.state === 'uncertain' ? 75 : ['failed', 'cancelled'].includes(run.state) ? 4
+        : status === 'fail' ? 2 : status === 'inconclusive' ? 3 : 0;
+    const error = remoteVideoFailure(run.state, run.error);
+    return { exitCode, envelope: { schemaVersion: 'playcraft.video-cli.v1', command, runId: run.runId, state: run.state,
+            ok: run.state === 'completed' && status === 'pass', result: run,
+            ...(error && { error }) } };
+}
+export function validateComparisonResult(value, request, local) {
+    try {
+        const result = replicaValidationResultSchema.parse(value);
+        if (result.runId !== request.runId || result.model.configId !== request.modelConfigId || result.model.processing !== request.processing
+            || result.recordingHash !== comparisonSha256(canonicalReplicaJson(request.recording))
+            || result.policySha256 !== comparisonSha256(canonicalReplicaJson(request.policy))
+            || canonicalReplicaJson(result.policy) !== canonicalReplicaJson(request.policy))
+            throw new Error('identity');
+        const expectedInputs = local.inputs.map(item => ({ id: item.id, role: item.role, source: item.video.source }));
+        if (canonicalReplicaJson([...result.inputs].sort((a, b) => a.id.localeCompare(b.id))) !== canonicalReplicaJson([...expectedInputs].sort((a, b) => a.id.localeCompare(b.id))))
+            throw new Error('sources');
+        const context = { inputs: result.inputs, analysis: request.analysis, recording: request.recording, policy: request.policy, processing: request.processing, fps: request.fps };
+        const content = validateReplicaComparisonContent({ summary: result.summary, evidence: result.evidence, alignments: result.alignments,
+            dimensions: result.dimensions, findings: result.findings, controlChecks: result.controlChecks,
+            timings: result.timings, missingEvidence: result.missingEvidence }, context);
+        // Recompute acceptance, including all missing evidence reported by the service.
+        const computed = evaluateReplicaComparison(content, context);
+        if (result.status !== computed.status || result.ok !== computed.ok || result.scope !== request.policy.scope
+            || canonicalReplicaJson(result.coverage) !== canonicalReplicaJson(computed.coverage)
+            || canonicalReplicaJson(result.timingChecks) !== canonicalReplicaJson(computed.timingChecks))
+            throw new Error('decision');
+        return result;
+    }
+    catch {
+        throw new ComparisonCliError('comparisonResult');
+    }
+}
+async function recheckComparisonInputs(saved, deps, signal) {
+    const actual = await preflightComparison({ reference: saved.referencePath, analysis: saved.analysisPath, candidate: saved.candidatePath,
+        recording: saved.recordingPath, out: saved.out, signal, probe: deps.probe });
+    if (canonicalReplicaJson(actual.recording) !== canonicalReplicaJson(saved.local.recording)
+        || canonicalReplicaJson(actual.analysis) !== canonicalReplicaJson(saved.local.analysis)
+        || canonicalReplicaJson(actual.inputs.map(item => ({ id: item.id, role: item.role, source: item.video.source })))
+            !== canonicalReplicaJson(saved.local.inputs.map(item => ({ id: item.id, role: item.role, source: item.video.source }))))
+        throw new ComparisonCliError('invalidRecording', 64);
+    return actual;
+}
+export async function executeVideoComparison(options, signal, deps) {
+    let saved;
+    let runId;
+    let out;
+    let submitted = false;
+    let stage = 'prepare';
+    try {
+        const workspaceId = await resolveVideoWorkspace(options.workspace);
+        if (options.resume && [options.reference, options.analysis, options.candidate, options.recording, options.policy, options.processing, options.fps, options.modelConfig].some(value => value !== undefined))
+            throw new ComparisonCliError('invalidComparison', 64);
+        if (!options.resume && (!options.reference || !options.analysis || !options.candidate || !options.recording))
+            throw new ComparisonCliError('invalidComparison', 64);
+        const processing = options.processing ?? 'static';
+        const fps = options.fps === undefined ? processing === 'static' ? 4 : undefined : Number(options.fps);
+        if (!['static', 'agentic'].includes(processing) || fps !== undefined && ![1, 2, 4, 8].includes(fps) || processing === 'agentic' && fps !== undefined)
+            throw new ComparisonCliError('invalidComparison', 64);
+        runId = options.resume ? requireVideoId(options.resume) : randomUUID();
+        out = resolve(options.out ?? join('.playcraft/video-replication', runId));
+        await prepareComparisonOutput(out, runId, !!options.resume);
+        let run;
+        if (options.resume) {
+            try {
+                saved = await readComparisonJson(join(out, 'request.json'), 8 * 1024 * 1024);
+                if (saved.schemaVersion !== 'playcraft.video-comparison-local-request.v1' || saved.runId !== runId || saved.workspaceId !== workspaceId || saved.out !== out || !saved.request)
+                    throw new Error('identity');
+                saved.request = videoComparisonRequestSchema.parse(saved.request);
+                if (saved.request.runId !== runId || saved.request.workspaceId !== workspaceId)
+                    throw new Error('request');
+            }
+            catch {
+                throw new ComparisonCliError('comparisonResume', 64);
+            }
+            submitted = true;
+            stage = 'probe';
+            saved.local = await preflightComparison({ reference: saved.referencePath, analysis: saved.analysisPath, candidate: saved.candidatePath,
+                recording: saved.recordingPath, out, signal, probe: deps.probe });
+            if (canonicalReplicaJson(saved.local.recording) !== canonicalReplicaJson(saved.request.recording)
+                || canonicalReplicaJson(saved.local.analysis) !== canonicalReplicaJson(saved.request.analysis))
+                throw new ComparisonCliError('comparisonResume', 64);
+            // Recovery only reads the existing task. It cannot upload or submit another inference.
+            stage = 'poll';
+            run = await readComparisonRun(deps.client, runId, workspaceId, signal);
+        }
+        else {
+            let policy;
+            try {
+                policy = options.policy ? replicaPolicySchema.parse(await readComparisonJson(resolve(options.policy))) : replicaDefaultPolicy;
+            }
+            catch {
+                throw new ComparisonCliError('invalidComparison', 64);
+            }
+            deps.progress('probing');
+            stage = 'probe';
+            const local = await preflightComparison({ reference: options.reference, analysis: options.analysis, candidate: options.candidate,
+                recording: options.recording, out, signal, probe: deps.probe });
+            try {
+                validateReplicaComparisonContext({ inputs: local.inputs.map(item => ({ id: item.id, role: item.role, source: item.video.source })),
+                    analysis: local.analysis, recording: local.recording, policy, processing: processing, fps });
+            }
+            catch {
+                throw new ComparisonCliError('invalidComparison', 64);
+            }
+            stage = 'models';
+            const catalog = videoModelCatalogSchema.parse(await deps.client.get('/video-models', { workspaceId }, { signal }));
+            const configId = options.modelConfig ? requireVideoId(options.modelConfig) : catalog.defaultConfigId;
+            const model = catalog.models.find(item => item.configId === configId);
+            if (!model || !model.processing.includes(processing) || model.maxVideos < local.inputs.length)
+                throw new ComparisonCliError('comparisonUnavailable', 64);
+            saved = { schemaVersion: 'playcraft.video-comparison-local-request.v1', runId, workspaceId, out,
+                referencePath: resolve(options.reference), analysisPath: resolve(options.analysis), candidatePath: resolve(options.candidate), recordingPath: resolve(options.recording),
+                local, state: 'uploading', createdAt: new Date().toISOString() };
+            await writeComparisonJson(out, 'request.json', saved);
+            const inputs = [];
+            for (const input of local.inputs) {
+                deps.progress('uploading');
+                const mediaId = await uploadVideo(input.video, workspaceId, deps, signal, value => { stage = value; });
+                inputs.push({ id: input.id, role: input.role, mediaId });
+            }
+            stage = 'submit';
+            const request = videoComparisonRequestSchema.parse({ schemaVersion: 'playcraft.video-comparison-request.v1', workspaceId, runId,
+                inputs, analysis: local.analysis, recording: local.recording, policy, processing, ...(fps !== undefined && { fps }), modelConfigId: configId });
+            saved = { ...saved, request, state: 'submitting' };
+            await writeComparisonJson(out, 'request.json', saved);
+            await recheckComparisonInputs(saved, deps, signal);
+            deps.progress('submitting');
+            submitted = true;
+            const response = await deps.client.post('/video-comparison', request, { signal, onPrepared: async (operation) => {
+                    saved = { ...saved, requestId: operation.requestId };
+                    await writeComparisonJson(out, 'request.json', saved);
+                } });
+            try {
+                run = videoComparisonRunSchema.parse(response);
+            }
+            catch {
+                throw new ComparisonCliError('comparisonResult');
+            }
+            if (run.runId !== runId || run.workspaceId !== workspaceId)
+                throw new ComparisonCliError('comparisonResult');
+        }
+        stage = 'poll';
+        while (['pending', 'uploading', 'submitting', 'running'].includes(run.state)) {
+            deps.progress('waiting');
+            await delay(Math.max(250, Math.min(run.pollAfterMs, 10_000)), undefined, { signal });
+            run = await readComparisonRun(deps.client, runId, workspaceId, signal);
+        }
+        await writeComparisonJson(out, 'task.json', run);
+        if (run.state === 'uncertain' && saved)
+            await writeComparisonJson(out, 'request.json', { ...saved, state: 'uncertain' }).catch(() => { });
+        if (run.state !== 'completed') {
+            const result = comparisonRunResult('video compare', run);
+            result.envelope.artifacts = { request: join(out, 'request.json') };
+            return result;
+        }
+        if (!saved.request || !run.comparison)
+            throw new ComparisonCliError('comparisonResult');
+        await recheckComparisonInputs(saved, deps, signal);
+        const comparison = validateComparisonResult(run.comparison, saved.request, saved.local);
+        deps.progress('extracting');
+        stage = 'extract';
+        const artifacts = await deps.materialize({ comparison, request: saved.request, inputs: saved.local.inputs, out, signal });
+        await writeComparisonJson(out, 'request.json', { ...saved, state: 'completed' });
+        const result = comparisonRunResult('video compare', { ...run, comparison });
+        result.envelope.artifacts = artifacts;
+        result.envelope.result = { status: comparison.status, scope: comparison.scope, coverage: comparison.coverage };
+        return result;
+    }
+    catch (error) {
+        const timeout = signal.aborted && signal.reason?.name === 'TimeoutError';
+        const interrupted = signal.aborted && !timeout;
+        const known = error instanceof VideoCliError || error instanceof ComparisonCliError;
+        const code = timeout ? 'timeoutReached' : interrupted ? 'interrupted' : known ? error.code : submitted ? 'uncertain' : 'comparisonFailed';
+        const exitCode = timeout ? 75 : interrupted ? 130 : known ? error.exitCode : submitted ? 75 : 4;
+        if (saved && out && submitted && (exitCode === 75 || exitCode === 130))
+            await writeComparisonJson(out, 'request.json', { ...saved, state: 'uncertain' }).catch(() => { });
+        const message = error instanceof ComparisonCliError ? comparisonMessage(error.code) : error instanceof VideoCliError ? videoMessage(error.code)
+            : timeout ? videoMessage('timeoutReached') : interrupted ? videoMessage('interrupted') : submitted ? videoMessage('uncertain') : comparisonMessage('comparisonFailed');
+        return { exitCode, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video compare', runId,
+                state: exitCode === 75 || exitCode === 130 ? 'uncertain' : 'failed', ok: false,
+                ...(saved && out && { artifacts: { request: join(out, 'request.json') } }), error: { code, ...describeVideoFailure(message, error, stage), ...(interrupted && { remoteCancellationConfirmed: false }) } } };
+    }
+}

package/dist/video-replication/diagnostics.js

@@ -0,0 +1,41 @@
+import { videoMessage } from './messages.js';
+import { redactDiagnosticText } from '../utils/error-diagnostics.js';
+export { redactDiagnosticText as redactVideoDiagnostic } from '../utils/error-diagnostics.js';
+const stageMessages = {
+    prepare: 'preparing', probe: 'probing', models: 'loadingModels',
+    'upload-init': 'initializingUpload', 'upload-content': 'uploading', 'upload-finalize': 'finalizingUpload',
+    submit: 'submitting', poll: 'waiting', extract: 'extracting', cancel: 'cancel',
+};
+/** Read messages and a bounded cause chain, never arbitrary error/response objects. */
+export function videoFailureDetails(error) {
+    const messages = [], seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < 5 && current != null && !seen.has(current); depth++) {
+        seen.add(current);
+        const record = typeof current === 'object' ? current : undefined;
+        const raw = typeof current === 'string' ? current : typeof record?.message === 'string' ? record.message : '';
+        const code = typeof record?.code === 'string' && /^[A-Z][A-Z0-9_]+$/.test(record.code) ? record.code : '';
+        const text = redactDiagnosticText(code && !raw.includes(code) ? `${code}: ${raw}` : raw).slice(0, 1600);
+        if (text && !messages.some(previous => previous.includes(text)))
+            messages.push(text);
+        current = record?.cause;
+    }
+    return messages.join(' <- ').slice(0, 4000) || undefined;
+}
+export function describeVideoFailure(summary, error, stage) {
+    const details = videoFailureDetails(error);
+    const reason = details?.startsWith(`${summary} <- `) ? details.slice(summary.length + 4)
+        : details && details !== summary ? details : undefined;
+    return {
+        message: [summary, stage && `${videoMessage('failureStage')}: ${videoMessage(stageMessages[stage])}.`,
+            reason && `${videoMessage('failureReason')}: ${reason}`].filter(Boolean).join(' '),
+        ...(reason && { details: reason }), ...(stage && { stage }),
+    };
+}
+export function remoteVideoFailure(state, error) {
+    if (!['failed', 'cancelled', 'uncertain'].includes(state))
+        return undefined;
+    const key = state === 'uncertain' ? 'uncertain' : 'remoteFailed';
+    return { code: state === 'uncertain' ? key : error?.code ?? key,
+        ...describeVideoFailure(videoMessage(key), error?.code, 'poll') };
+}