@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/utils/video-evidence-git.js

@@ -0,0 +1,81 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const ENTRY = '/.playcraft/video-replication/';
+/** Keep local analysis evidence out of a repository without changing its tracked ignore rules. */
+export async function ensureVideoEvidenceGitExcluded(directory) {
+    let root = await realpath(directory);
+    while (true) {
+        const marker = await lstat(join(root, '.git')).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (marker) {
+            // Cloud workspaces own a real .git directory; never follow a redirected Git metadata tree.
+            if (!marker.isDirectory() || marker.isSymbolicLink())
+                return false;
+            try {
+                await appendExclude(root);
+                return true;
+            }
+            catch (error) {
+                if (['EACCES', 'EPERM', 'EROFS'].includes(error.code ?? ''))
+                    return false;
+                throw error;
+            }
+        }
+        const parent = dirname(root);
+        if (parent === root)
+            return true;
+        root = parent;
+    }
+}
+async function appendExclude(root) {
+    const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+    const handles = [];
+    let file;
+    try {
+        const directory = await open(root, flags);
+        handles.push(directory);
+        const pinned = (handle, fallback) => process.platform === 'linux' ? `/proc/self/fd/${handle.fd}` : fallback;
+        const git = await open(join(pinned(directory, root), '.git'), flags);
+        handles.push(git);
+        const gitPath = pinned(git, join(root, '.git'));
+        await mkdir(join(gitPath, 'info')).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        const info = await open(join(gitPath, 'info'), flags);
+        handles.push(info);
+        const exclude = join(pinned(info, join(root, '.git/info')), 'exclude');
+        const readable = await open(exclude, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+            .catch((error) => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (readable) {
+            try {
+                const stat = await readable.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+                    throw new Error('invalid_git_exclude');
+                if ((await readable.readFile('utf8')).split('\n').some(line => line.trim() === ENTRY))
+                    return;
+            }
+            finally {
+                await readable.close();
+            }
+        }
+        file = await open(exclude, constants.O_RDWR | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o666);
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_git_exclude');
+        const current = await file.readFile('utf8');
+        if (!current.split('\n').some(line => line.trim() === ENTRY)) {
+            await file.writeFile(`${current && !current.endsWith('\n') ? '\n' : ''}${ENTRY}\n`);
+        }
+    }
+    finally {
+        await file?.close();
+        for (const handle of handles.reverse())
+            await handle.close();
+    }
+}

package/dist/video-replication/client.js

@@ -0,0 +1,234 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { videoAnalysisRequestSchema, videoAnalysisRunSchema, videoMediaInitResultSchema, videoMediaResultSchema, videoModelCatalogSchema, videoUnderstandingAnalysisSchema, } from '@playcraft/common/agent-tools';
+import { VideoCliError, videoMessage } from './messages.js';
+import { describeVideoFailure, remoteVideoFailure } from './diagnostics.js';
+import { openVideo, verifyVideo } from './media.js';
+import { loadSavedRequest, prepareArtifactDirectory, writeJsonAtomic, } from './evidence.js';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function requireVideoId(value) {
+    if (!uuid.test(value))
+        throw new VideoCliError('invalidArguments', 64);
+    return value.toLowerCase();
+}
+export async function resolveVideoWorkspace(explicit, cwd = process.cwd()) {
+    let context;
+    for (let path = resolve(cwd);; path = dirname(path)) {
+        try {
+            const file = join(path, '.playcraft/workspace-context.json');
+            if ((await stat(file)).size > 8192)
+                throw new VideoCliError('workspaceMissing', 64);
+            const value = JSON.parse(await readFile(file, 'utf8'));
+            if (value.schemaVersion !== 'playcraft.workspace-context.v1' || typeof value.workspaceId !== 'string')
+                throw new VideoCliError('workspaceMissing', 64);
+            context = requireVideoId(value.workspaceId);
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (dirname(path) === path)
+            break;
+    }
+    const workspace = explicit === undefined ? context : requireVideoId(explicit);
+    if (!workspace)
+        throw new VideoCliError('workspaceMissing', 64);
+    if (context && explicit && context !== workspace)
+        throw new VideoCliError('workspaceMismatch', 64);
+    return workspace;
+}
+export function parseVideoPolicy(options) {
+    const processing = options.processing ?? 'auto';
+    if (!['auto', 'agentic', 'static'].includes(processing))
+        throw new VideoCliError('invalidArguments', 64);
+    const fps = options.fps === undefined ? undefined : Number(options.fps);
+    if (fps !== undefined && ![1, 2, 4, 8].includes(fps))
+        throw new VideoCliError('invalidArguments', 64);
+    let clip;
+    if (options.clip !== undefined) {
+        if (!/^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(options.clip))
+            throw new VideoCliError('invalidArguments', 64);
+        const [startMs, endMs] = options.clip.split(':').map(value => Number(value) * 1000);
+        if (!Number.isFinite(endMs) || endMs <= startMs)
+            throw new VideoCliError('invalidArguments', 64);
+        clip = { startMs, endMs };
+    }
+    if (processing === 'agentic' && (fps !== undefined || clip))
+        throw new VideoCliError('invalidArguments', 64);
+    return { processing: processing, ...(fps !== undefined && { fps: fps }), ...(clip && { clip }) };
+}
+export function videoTimeout(options) {
+    const seconds = options.timeout === undefined ? 600 : Number(options.timeout);
+    if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 86_400)
+        throw new VideoCliError('invalidArguments', 64);
+    return seconds * 1000;
+}
+async function readContext(path, video) {
+    if (!path)
+        return undefined;
+    try {
+        if ((await stat(path)).size > 2 * 1024 * 1024)
+            throw new Error('large');
+        const analysis = videoUnderstandingAnalysisSchema.parse(JSON.parse(await readFile(path, 'utf8')));
+        if (analysis.source.sha256 !== video.source.sha256)
+            throw new Error('different video');
+        return analysis;
+    }
+    catch {
+        throw new VideoCliError('invalidContext', 64);
+    }
+}
+export async function uploadVideo(video, workspaceId, deps, signal, onStage) {
+    onStage?.('upload-init');
+    const mediaId = randomUUID();
+    const init = videoMediaInitResultSchema.parse(await deps.client.post('/video-media/init', {
+        workspaceId, mediaId, filename: basename(video.path), sha256: video.source.sha256,
+        sizeBytes: video.source.sizeBytes, mimeType: video.source.mimeType, contentMd5: video.contentMd5,
+    }, { signal }));
+    if (init.mediaId !== mediaId || Date.parse(init.upload.expiresAt) <= Date.now())
+        throw new VideoCliError('uploadFailed');
+    onStage?.('upload-content');
+    const file = await openVideo(video.path);
+    try {
+        await verifyVideo(file, video.source);
+        const stream = file.createReadStream({ start: 0, autoClose: false });
+        if (init.upload.authenticated) {
+            await deps.client.putVideoMedia(init.upload.url, stream, init.upload.headers, signal);
+        }
+        else {
+            const url = new URL(init.upload.url);
+            const allowed = new Set(['content-type', 'content-md5', 'content-length', 'x-cos-acl']);
+            if (url.protocol !== 'https:' || url.username || url.password || url.hash || Object.entries(init.upload.headers).some(([key, value]) => !allowed.has(key.toLowerCase()) || (key.toLowerCase() === 'x-cos-acl' && value !== 'private')))
+                throw new VideoCliError('uploadFailed');
+            const response = await fetch(url, { method: 'PUT', redirect: 'error', signal, headers: init.upload.headers, body: stream, duplex: 'half' });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new VideoCliError('uploadFailed', 4, { cause: new Error(`video_upload_failed:${response.status} ${response.statusText}`) });
+            }
+            await response.body?.cancel();
+        }
+        await verifyVideo(file, video.source);
+    }
+    finally {
+        await file.close();
+    }
+    onStage?.('upload-finalize');
+    const finalized = videoMediaResultSchema.parse(await deps.client.post('/video-media/finalize', { workspaceId, mediaId }, { signal }));
+    if (finalized.mediaId !== mediaId || finalized.source.sha256 !== video.source.sha256 || finalized.source.sizeBytes !== video.source.sizeBytes)
+        throw new VideoCliError('sourceChanged');
+    return mediaId;
+}
+export async function readVideoRun(client, runId, workspaceId, signal) {
+    const run = videoAnalysisRunSchema.parse(await client.get(`/video-analysis/${runId}`, { workspaceId }, { signal }));
+    if (run.runId !== runId || run.workspaceId !== workspaceId || (run.analysis && run.analysis.runId !== runId))
+        throw new VideoCliError('invalidResult');
+    return run;
+}
+async function waitForVideoRun(run, deps, signal) {
+    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 readVideoRun(deps.client, run.runId, run.workspaceId, signal);
+    }
+    return run;
+}
+export async function executeVideoUnderstanding(options, signal, deps) {
+    let runId;
+    let out;
+    let saved;
+    let submitted = false;
+    let stage = 'prepare';
+    try {
+        const workspaceId = await resolveVideoWorkspace(options.workspace);
+        const policy = parseVideoPolicy(options);
+        if (options.question !== undefined && (!options.question.trim() || options.question.length > 8000))
+            throw new VideoCliError('invalidArguments', 64);
+        if (options.resume && [options.video, options.question, options.context, options.processing, options.fps, options.clip, options.modelConfig].some(value => value !== undefined))
+            throw new VideoCliError('invalidArguments', 64);
+        if (!options.resume && !options.video)
+            throw new VideoCliError('invalidArguments', 64);
+        runId = options.resume ? requireVideoId(options.resume) : randomUUID();
+        out = resolve(options.out ?? join('.playcraft/video-replication', runId));
+        await prepareArtifactDirectory(out, runId, !!options.resume);
+        let run;
+        if (options.resume) {
+            saved = await loadSavedRequest(out, runId, workspaceId);
+            submitted = true;
+            // Recovery only reads the existing task. No upload or POST can be triggered here.
+            stage = 'poll';
+            run = await readVideoRun(deps.client, runId, workspaceId, signal);
+            if (saved.request && run.mediaId !== saved.request.mediaId)
+                throw new VideoCliError('invalidResult');
+        }
+        else {
+            deps.progress('probing');
+            stage = 'probe';
+            const video = await deps.probe(resolve(options.video), signal);
+            if (policy.clip && policy.clip.endMs > video.source.durationMs)
+                throw new VideoCliError('invalidArguments', 64);
+            const context = await readContext(options.context, video);
+            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);
+            const mode = policy.processing === 'auto'
+                ? policy.fps !== undefined || policy.clip || !model?.processing.includes('agentic') ? 'static' : 'agentic'
+                : policy.processing;
+            if (!model || !model.processing.includes(mode))
+                throw new VideoCliError('modelUnavailable', 64);
+            saved = { schemaVersion: 'playcraft.video-request.v1', runId, workspaceId, videoPath: video.path, out, state: 'uploading', createdAt: new Date().toISOString() };
+            await writeJsonAtomic(join(out, 'request.json'), saved);
+            deps.progress('uploading');
+            const mediaId = await uploadVideo(video, workspaceId, deps, signal, value => { stage = value; });
+            stage = 'submit';
+            const request = videoAnalysisRequestSchema.parse({
+                workspaceId, runId, mediaId, modelConfigId: configId, ...policy,
+                ...(options.question && { question: options.question }), ...(context && { context }),
+            });
+            saved = { ...saved, request, state: 'submitting' };
+            await writeJsonAtomic(join(out, 'request.json'), saved);
+            deps.progress('submitting');
+            submitted = true;
+            run = videoAnalysisRunSchema.parse(await deps.client.post('/video-analysis', request, {
+                signal,
+                onPrepared: async (operation) => {
+                    saved = { ...saved, requestId: operation.requestId };
+                    await writeJsonAtomic(join(out, 'request.json'), saved);
+                },
+            }));
+            if (run.runId !== runId || run.workspaceId !== workspaceId || run.mediaId !== mediaId)
+                throw new VideoCliError('invalidResult');
+        }
+        stage = 'poll';
+        run = await waitForVideoRun(run, deps, signal);
+        await writeJsonAtomic(join(out, 'task.json'), run);
+        if (run.state !== 'completed') {
+            if (run.state === 'uncertain' && saved)
+                await writeJsonAtomic(join(out, 'request.json'), { ...saved, state: 'uncertain' }).catch(() => { });
+            return { exitCode: run.state === 'uncertain' ? 75 : 4,
+                envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video understand', runId, state: run.state, ok: false,
+                    artifacts: { request: join(out, 'request.json') }, error: remoteVideoFailure(run.state, run.error) } };
+        }
+        if (!run.analysis || !saved || run.analysis.runId !== runId ||
+            (saved.request?.modelConfigId && run.analysis.model.configId !== saved.request.modelConfigId))
+            throw new VideoCliError('invalidResult');
+        deps.progress('extracting');
+        stage = 'extract';
+        const artifacts = await deps.materialize({ analysis: run.analysis, sourcePath: saved.videoPath, out, request: saved.request, signal });
+        await writeJsonAtomic(join(out, 'request.json'), { ...saved, state: 'completed' });
+        return { exitCode: 0, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video understand', runId, state: 'completed', ok: true, artifacts } };
+    }
+    catch (error) {
+        const timeout = signal.aborted && signal.reason?.name === 'TimeoutError';
+        const interrupted = signal.aborted && !timeout;
+        const known = error instanceof VideoCliError;
+        const code = timeout ? 'timeoutReached' : interrupted ? 'interrupted' : known ? error.code : submitted ? 'uncertain' : 'failed';
+        const exitCode = timeout ? 75 : interrupted ? 130 : known ? error.exitCode : submitted ? 75 : 4;
+        if (saved && out && submitted && (exitCode === 75 || exitCode === 130))
+            await writeJsonAtomic(join(out, 'request.json'), { ...saved, state: 'uncertain' }).catch(() => { });
+        return { exitCode, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video understand', runId, state: exitCode === 75 || exitCode === 130 ? 'uncertain' : 'failed', ok: false, ...(saved && out && { artifacts: { request: join(out, 'request.json') } }), error: { code, ...describeVideoFailure(videoMessage(code), error, stage), ...(interrupted && { remoteCancellationConfirmed: false }) } } };
+    }
+}

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

@@ -0,0 +1,149 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { replicaValidationResultSchema, validateReplicaComparisonContent, } from '@playcraft/common/agent-tools';
+import { openVideo, runMediaTool, verifyVideo } from './media.js';
+import { comparisonOutputPath, writeComparisonArtifact, writeComparisonJson } from './comparison-output.js';
+import { comparisonMessage as t, ComparisonCliError } from './comparison-messages.js';
+import { comparisonSha256 } from './comparison-files.js';
+const xml = (text) => text.replace(/[&<>"']/g, value => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[value]);
+const md = (text) => text.replace(/([\\`*_[\]<>])/g, '\\$1');
+const reasonMessages = {
+    'video.eventPairMissing': 'reasonEventPairMissing', 'video.dimensionUncertain': 'reasonDimensionUncertain',
+    'video.dimensionEventMissing': 'reasonDimensionEventMissing', 'video.progressionEvidenceMissing': 'reasonProgressionEvidenceMissing',
+    'video.timingPrecisionInsufficient': 'reasonTimingPrecisionInsufficient', 'video.timingFailureUnverified': 'reasonTimingFailureUnverified',
+    'video.requiredEffectsMissing': 'reasonRequiredEffectsMissing', 'video.controlRuntimeUncertain': 'reasonControlRuntimeUncertain',
+    'video.controlEvidenceMissing': 'reasonControlEvidenceMissing', 'video.requestsFailed': 'reasonRequestsFailed',
+};
+const renderReason = (reason) => {
+    const key = reason.startsWith('video.referenceKindMissing:') ? 'reasonReferenceKindMissing'
+        : Object.prototype.hasOwnProperty.call(reasonMessages, reason) ? reasonMessages[reason] : undefined;
+    return md(key ? `${t(key)} (${reason})` : reason);
+};
+async function tile(frame, out) {
+    const image = await sharp(join(out, frame.path)).resize(260, 190, { fit: 'contain', background: '#f4f4f4' }).png().toBuffer();
+    const label = Buffer.from(`<svg width="260" height="34"><rect width="100%" height="100%" fill="white"/><text x="8" y="14" font-size="11">${xml(frame.inputId)} · ${xml(frame.evidenceId)}</text><text x="8" y="29" font-size="11">${(frame.timeMs / 1000).toFixed(3)}s</text></svg>`);
+    return sharp({ create: { width: 260, height: 224, channels: 3, background: '#fff' } }).composite([{ input: image, top: 0, left: 0 }, { input: label, top: 190, left: 0 }]).png().toBuffer();
+}
+export function renderComparisonReport(comparison, frames) {
+    const frameMap = new Map(frames.map(frame => [frame.evidenceId, frame]));
+    const refs = (ids) => ids.map(id => `[${md(id)}](${frameMap.get(id)?.path})`).join(', ');
+    const list = (values) => values.length ? values.map(md).join(', ') : t('reportNone');
+    const timingStatus = comparison.timingChecks.some(check => check.status === 'fail') ? 'fail'
+        : !comparison.timingChecks.length || comparison.timingChecks.some(check => check.status === 'inconclusive') ? 'inconclusive' : 'pass';
+    const lines = [`# ${t('summary')}: ${comparison.status}`, '', t('coverageNotice'), '',
+        `## ${t('decision')}`, '', `- ${t('reportStatus')}: **${comparison.status}**`, `- ${t('reportScope')}: ${comparison.scope}`,
+        `- ${t('reportPolicy')}: ${comparison.policySha256}`, `- ${t('reportRecording')}: ${comparison.recordingHash}`, ''];
+    lines.push(t(comparison.status === 'pass' ? 'policyPassedNotice' : 'policyNotPassedNotice'), '', `## ${t('coverage')}`, '', t('deterministicNotice'), '', `- ${t('reportRequired')}: ${list(comparison.coverage.requiredEventIds)}`, `- ${t('reportEvaluated')}: ${list(comparison.coverage.evaluatedEventIds)}`, `- ${t('reportMissing')}: ${list(comparison.coverage.missingEventIds)}`, `- ${t('reportRequiredKinds')}: ${list(comparison.coverage.requiredKinds)}`, `- ${t('reportMissingKinds')}: ${list(comparison.coverage.missingKinds)}`, '', `### ${t('reportMissingEvidence')}`, '');
+    if (comparison.missingEvidence.some(item => item.dimension === 'interaction'))
+        lines.push(t('interactionUnverified'), '');
+    for (const item of comparison.missingEvidence)
+        lines.push(`- ${item.eventId ? `${md(item.eventId)}: ` : ''}${item.dimension ? `${item.dimension}: ` : ''}${renderReason(item.reason)}`);
+    if (!comparison.missingEvidence.length)
+        lines.push(`- ${t('reportNone')}`);
+    lines.push('', `### ${t('reportTimingChecks')}: ${timingStatus}`, '');
+    if (timingStatus === 'inconclusive')
+        lines.push(t('timingUnverified'), '');
+    for (const check of comparison.timingChecks)
+        lines.push(`- ${t('reportTiming')} ${md(check.eventId)} (${check.measurement}): ${check.status}; ${t('reportReference')} ${check.referenceRangeMs.join('–')} ms; ${t('reportCandidate')} ${check.candidateRangeMs.join('–')} ms; ${t('reportTolerance')} ${check.toleranceMs} ms`);
+    lines.push('', `## ${t('modelObservations')}`, '', t('modelObservationNotice'), '', `- ${t('reportModel')}: ${comparison.model.provider}/${comparison.model.model} (${comparison.model.processing})`, '', `### ${t('modelSummary')}`, '', md(comparison.summary), '', `### ${t('modelDimensions')}`, '');
+    for (const [dimension, judgment] of Object.entries(comparison.dimensions))
+        lines.push(`- **${dimension}: ${judgment.status}** (${judgment.confidence}) — ${md(judgment.reason)} ${refs(judgment.evidenceIds)}`);
+    lines.push('', `## ${t('differences')}`, '');
+    for (const finding of comparison.findings)
+        lines.push(`### ${md(finding.id)} · ${finding.severity} · ${finding.dimension}`, '', `- ${t('reportExpected')}: ${md(finding.expected)}`, `- ${t('reportObserved')}: ${md(finding.observed)}`, `- ${t('reportSuggestedFix')}: ${md(finding.suggestedFix)}`, `- ${t('reportConfidence')}: ${finding.confidence}; ${t('reportEvidence')}: ${refs(finding.evidenceIds)}`, '');
+    lines.push(`## ${t('alignment')}`, '');
+    for (const alignment of comparison.alignments) {
+        const reference = frameMap.get(alignment.referenceEvidenceId);
+        const candidate = frameMap.get(alignment.candidateEvidenceId);
+        lines.push(`- **${md(alignment.eventId)}** (${alignment.confidence}): ${t('reportReference')} ${reference?.timeMs} ms ↔ ${t('reportCandidate')} ${candidate?.timeMs} ms; ${refs([alignment.referenceEvidenceId, alignment.candidateEvidenceId])}`);
+    }
+    lines.push('', `## ${t('controls')}`, '');
+    for (const check of comparison.controlChecks)
+        lines.push(`- ${md(check.stepId)} → ${md(check.eventId)}; ${md(check.controlInputId)}: ${check.effect} (${check.confidence}); ${refs([check.candidateEvidenceId, check.controlEvidenceId])}`);
+    lines.push('', `## ${t('evidence')}`, '');
+    for (const frame of frames)
+        lines.push(`- ${md(frame.evidenceId)} · ${md(frame.inputId)}: ${t('reportRequested')} ${frame.requestedTimeMs} ms, ${t('reportDecoded')} ${frame.timeMs} ms; [${t('reportFrame')}](${frame.path})`);
+    return `${lines.join('\n')}\n`;
+}
+/** Extract real source frames for each validated input; model output never supplies local paths. */
+export async function materializeComparisonEvidence(input) {
+    let comparison;
+    try {
+        comparison = replicaValidationResultSchema.parse(input.comparison);
+        validateReplicaComparisonContent({ summary: comparison.summary, evidence: comparison.evidence, alignments: comparison.alignments,
+            dimensions: comparison.dimensions, findings: comparison.findings, controlChecks: comparison.controlChecks, timings: comparison.timings, missingEvidence: comparison.missingEvidence }, { inputs: comparison.inputs, analysis: input.request.analysis, recording: input.request.recording, policy: input.request.policy, processing: input.request.processing, fps: input.request.fps });
+    }
+    catch {
+        throw new ComparisonCliError('comparisonResult');
+    }
+    // Validate every destination before replacing any prior artifact.
+    for (const path of [...comparison.evidence.map(item => `keyframes/${item.inputId}/${item.id}.png`), 'comparison.json', 'comparison.md', 'manifest.json', 'contact-sheet.jpg', 'paired-contact-sheet.jpg'])
+        await comparisonOutputPath(input.out, path);
+    const frames = [];
+    for (const source of comparison.inputs) {
+        const local = input.inputs.find(item => item.id === source.id && item.role === source.role);
+        if (!local)
+            throw new ComparisonCliError('comparisonResult');
+        const evidence = comparison.evidence.filter(item => item.inputId === source.id);
+        if (!evidence.length)
+            continue;
+        const file = await openVideo(local.video.path);
+        try {
+            await verifyVideo(file, source.source);
+            const output = await runMediaTool('ffprobe', ['-v', 'error', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+                '-select_streams', 'v:0', '-show_entries', 'frame=best_effort_timestamp_time', '-of', 'csv=p=0', '/dev/fd/3'], file.fd, input.signal);
+            const raw = output.split('\n').map(line => Number.parseFloat(line) * 1000).filter(Number.isFinite);
+            const origin = raw[0] ?? 0;
+            const times = raw.map(time => time - origin).filter(time => time >= 0 && time < source.source.durationMs);
+            if (!times.length)
+                throw new ComparisonCliError('comparisonResult');
+            for (const item of evidence) {
+                input.signal?.throwIfAborted();
+                const requestedTimeMs = (item.startMs + item.endMs) / 2;
+                const timeMs = times.reduce((best, time) => Math.abs(time - requestedTimeMs) < Math.abs(best - requestedTimeMs) ? time : best);
+                const path = `keyframes/${source.id}/${item.id}.png`;
+                await writeComparisonArtifact(input.out, path, temporary => runMediaTool('ffmpeg', ['-v', 'error', '-nostdin', '-y', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+                    '-ss', (Math.max(0, timeMs - 0.01) / 1000).toFixed(6), '-i', '/dev/fd/3', '-map', '0:v:0', '-frames:v', '1',
+                    '-vf', 'scale=min(1280\\,iw):-2', '-threads', '1', temporary], file.fd, input.signal));
+                const bytes = await readFile(join(input.out, path));
+                const metadata = await sharp(bytes).metadata();
+                if (!metadata.width || !metadata.height)
+                    throw new ComparisonCliError('comparisonResult');
+                frames.push({ evidenceId: item.id, inputId: source.id, requestedTimeMs, timeMs, path, sha256: comparisonSha256(bytes) });
+            }
+            await verifyVideo(file, source.source);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    if (frames.length !== comparison.evidence.length)
+        throw new ComparisonCliError('comparisonResult');
+    const tiles = await Promise.all(frames.map(frame => tile(frame, input.out)));
+    const columns = Math.min(4, tiles.length);
+    const contactSheet = join(input.out, 'contact-sheet.jpg');
+    await writeComparisonArtifact(input.out, 'contact-sheet.jpg', temporary => sharp({ create: { width: columns * 260, height: Math.ceil(tiles.length / columns) * 224, channels: 3, background: '#ddd' } })
+        .composite(tiles.map((value, index) => ({ input: value, left: index % columns * 260, top: Math.floor(index / columns) * 224 }))).jpeg({ quality: 85 }).toFile(temporary));
+    const pairs = comparison.alignments.flatMap(alignment => [alignment.referenceEvidenceId, alignment.candidateEvidenceId]);
+    const selected = pairs.length ? pairs.map(id => tiles[frames.findIndex(frame => frame.evidenceId === id)])
+        : ['reference', 'candidate'].flatMap(inputId => { const index = frames.findIndex(frame => frame.inputId === inputId); return index >= 0 ? [tiles[index]] : []; });
+    if (!selected.length)
+        throw new ComparisonCliError('comparisonResult');
+    const pairedContactSheet = join(input.out, 'paired-contact-sheet.jpg');
+    await writeComparisonArtifact(input.out, 'paired-contact-sheet.jpg', temporary => sharp({ create: { width: 520, height: Math.ceil(selected.length / 2) * 224, channels: 3, background: '#ddd' } })
+        .composite(selected.map((value, index) => ({ input: value, left: index % 2 * 260, top: Math.floor(index / 2) * 224 }))).jpeg({ quality: 85 }).toFile(temporary));
+    const resultPath = join(input.out, 'comparison.json');
+    const markdown = join(input.out, 'comparison.md');
+    await writeComparisonJson(input.out, 'comparison.json', comparison);
+    await writeComparisonArtifact(input.out, 'comparison.md', temporary => writeFile(temporary, renderComparisonReport(comparison, frames), { mode: 0o600, flag: 'wx' }));
+    const files = [];
+    for (const path of ['comparison.json', 'comparison.md', 'contact-sheet.jpg', 'paired-contact-sheet.jpg'])
+        files.push({ path, sha256: comparisonSha256(await readFile(join(input.out, path))) });
+    const manifest = join(input.out, 'manifest.json');
+    await writeComparisonJson(input.out, 'manifest.json', { schemaVersion: 'playcraft.replica-evidence.v1', runId: comparison.runId, state: 'completed', status: comparison.status,
+        recordingHash: comparison.recordingHash, policySha256: comparison.policySha256, model: comparison.model, inputs: comparison.inputs,
+        comparison: 'comparison.json', markdown: 'comparison.md', contactSheet: 'contact-sheet.jpg', pairedContactSheet: 'paired-contact-sheet.jpg',
+        files, frames, frameTimeSemantics: 'nearest-decoded-original-video-frame', audio: 'not_evaluated' });
+    return { manifest, comparison: resultPath, markdown, contactSheet, pairedContactSheet, keyframes: frames.map(frame => join(input.out, frame.path)) };
+}

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

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { ComparisonCliError } from './comparison-messages.js';
+export function comparisonSha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export async function readComparisonJson(path, maxBytes = 2 * 1024 * 1024) {
+    const file = await open(path, 'r');
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size <= 0 || stat.size > maxBytes)
+            throw new ComparisonCliError('invalidRecording', 64);
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Only recorder-owned, regular files under the exact recording directory may become evidence. */
+export async function recordingArtifactPath(root, path) {
+    if (!path || isAbsolute(path) || path.includes('\\') || path.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new ComparisonCliError('invalidRecording', 64);
+    const base = await realpath(root);
+    const target = resolve(base, path);
+    const local = relative(base, target);
+    if (!local || local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local))
+        throw new ComparisonCliError('invalidRecording', 64);
+    let current = base;
+    for (const part of local.split(sep)) {
+        current = resolve(current, part);
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink())
+            throw new ComparisonCliError('invalidRecording', 64);
+    }
+    if (await realpath(target) !== target || !(await lstat(target)).isFile())
+        throw new ComparisonCliError('invalidRecording', 64);
+    return target;
+}
+export async function verifyRecordingArtifact(root, artifact, maxBytes = 8 * 1024 * 1024) {
+    const path = await recordingArtifactPath(root, artifact.path);
+    const file = await open(path, 'r');
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            throw new ComparisonCliError('invalidRecording', 64);
+        const hash = createHash('sha256');
+        for await (const chunk of file.createReadStream({ autoClose: false, start: 0 }))
+            hash.update(chunk);
+        if (hash.digest('hex') !== artifact.sha256)
+            throw new ComparisonCliError('invalidRecording', 64);
+    }
+    finally {
+        await file.close();
+    }
+    return path;
+}

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

@@ -0,0 +1,72 @@
+import { canonicalReplicaJson } from '@playcraft/common/agent-tools';
+import { ComparisonCliError } from './comparison-messages.js';
+/** Completed capture and every real/omitted scenario step must be represented in the hashed log. */
+export function validateComparisonInputLog(records, scenario, artifact) {
+    const invalid = () => { throw new ComparisonCliError('invalidRecording', 64); };
+    const finiteTime = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+    if (records.some(value => value === null || typeof value !== 'object' || Array.isArray(value)))
+        invalid();
+    const log = records;
+    const starts = log.filter(record => record.kind === 'recording-start'), ends = log.filter(record => record.kind === 'recording-end');
+    if (starts.length !== 1 || ends.length !== 1 || log[0] !== starts[0] || log.at(-1) !== ends[0])
+        invalid();
+    const start = starts[0], end = ends[0];
+    if (start.plannedAtMs !== 0 || start.actualAtMs !== 0 || start.device !== scenario.pointer || canonicalReplicaJson(start.reset) !== canonicalReplicaJson(scenario.reset)
+        || end.plannedAtMs !== scenario.durationMs || !finiteTime(end.actualAtMs) || end.actualAtMs < scenario.durationMs || end.status !== 'completed')
+        invalid();
+    if (log.some(record => record.status === 'failed' || !finiteTime(record.actualAtMs) || !finiteTime(record.plannedAtMs)))
+        invalid();
+    const finals = log.filter(record => ['tap', 'drag'].includes(String(record.kind)) && ['dispatched', 'omitted'].includes(String(record.status)));
+    if (finals.length !== scenario.steps.length)
+        invalid();
+    let previousEnd = -1;
+    for (const step of scenario.steps) {
+        const matching = finals.filter(record => record.stepId === step.id);
+        if (matching.length !== 1)
+            invalid();
+        const record = matching[0], omitted = artifact.omittedStepIds.includes(step.id);
+        if (record.kind !== step.type || record.plannedAtMs !== step.atMs || record.device !== scenario.pointer || record.status !== (omitted ? 'omitted' : 'dispatched')
+            || !finiteTime(record.actualAtMs) || record.actualAtMs + 2 < step.atMs || record.actualAtMs < previousEnd)
+            invalid();
+        const expected = (step.type === 'tap' ? [{ offsetMs: 0, x: step.x, y: step.y }] : step.path).map(point => ({ ...point, actual: {
+                x: (scenario.contentRect.x + point.x * scenario.contentRect.width) * scenario.viewport.width,
+                y: (scenario.contentRect.y + point.y * scenario.contentRect.height) * scenario.viewport.height,
+            } }));
+        if (canonicalReplicaJson(record.points) !== canonicalReplicaJson(expected))
+            invalid();
+        if (!omitted) {
+            if (!finiteTime(record.completedAtMs) || record.completedAtMs < record.actualAtMs
+                || record.completedAtMs > artifact.video.source.durationMs + artifact.timing.uncertaintyMs)
+                invalid();
+            const pointers = log.filter(pointer => pointer.stepId === step.id && pointer.kind === 'pointer' && pointer.status === 'dispatched');
+            if (step.type === 'tap' ? !pointers.some(pointer => pointer.phase === 'tap') : !['start', 'move', 'end'].every(phase => pointers.some(pointer => pointer.phase === phase)))
+                invalid();
+            previousEnd = record.completedAtMs;
+        }
+        else
+            previousEnd = record.actualAtMs;
+    }
+}
+/** Runtime counters must agree with the hashed console and browser event evidence. */
+export function validateComparisonConsoleLog(records, artifact) {
+    const counts = { pageErrors: 0, consoleErrors: 0, failedRequests: 0 };
+    for (const value of records) {
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            throw new ComparisonCliError('invalidRecording', 64);
+        const record = value;
+        if (typeof record.atMs !== 'number' || !Number.isFinite(record.atMs) || record.atMs < 0)
+            throw new ComparisonCliError('invalidRecording', 64);
+        if (record.kind === 'console') {
+            if (record.level === 'error')
+                counts.consoleErrors++;
+        }
+        else if (['pageerror', 'popup', 'dialog'].includes(String(record.kind)))
+            counts.pageErrors++;
+        else if (record.kind === 'requestfailed')
+            counts.failedRequests++;
+        else
+            throw new ComparisonCliError('invalidRecording', 64);
+    }
+    if (canonicalReplicaJson(counts) !== canonicalReplicaJson(artifact.runtime))
+        throw new ComparisonCliError('invalidRecording', 64);
+}