@playcraft/cli 0.1.36-beta1 → 0.1.38-beta

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,216 @@
+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 { 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;
+    return { exitCode, envelope: { schemaVersion: 'playcraft.video-cli.v1', command, runId: run.runId, state: run.state,
+            ok: run.state === 'completed' && status === 'pass', result: run } };
+}
+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;
+    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;
+            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.
+            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');
+            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);
+            }
+            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);
+                inputs.push({ id: input.id, role: input.role, mediaId });
+            }
+            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');
+        }
+        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')
+            throw new VideoCliError('uncertain', 75);
+        if (run.state !== 'completed')
+            return comparisonRunResult('video compare', run);
+        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');
+        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, message, ...(interrupted && { remoteCancellationConfirmed: false }) } } };
+    }
+}

package/dist/video-replication/evidence.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import sharp from 'sharp';
+import { videoUnderstandingAnalysisSchema, validateVideoUnderstandingContent, } from '@playcraft/common/agent-tools';
+import { openVideo, runMediaTool, verifyVideo } from './media.js';
+import { VideoCliError, videoMessage } from './messages.js';
+import { ensureVideoEvidenceGitExcluded } from '../utils/video-evidence-git.js';
+import { comparisonOutputPath, comparisonOutputRoot, writeComparisonArtifact, writeComparisonJson } from './comparison-output.js';
+import { ComparisonCliError } from './comparison-messages.js';
+async function videoOutput(action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (error instanceof ComparisonCliError && error.code === 'unsafeOutput')
+            throw new VideoCliError('unsafeOutput', 64);
+        throw error;
+    }
+}
+export async function writeJsonAtomic(path, value) {
+    await videoOutput(async () => {
+        await comparisonOutputRoot(dirname(path), true);
+        await writeComparisonJson(dirname(path), basename(path), value);
+    });
+}
+export async function prepareArtifactDirectory(out, runId, resume) {
+    if (!(await ensureVideoEvidenceGitExcluded(process.cwd())))
+        console.error(videoMessage('gitExcludeWarning'));
+    await videoOutput(async () => {
+        await comparisonOutputRoot(out, true);
+        await comparisonOutputPath(out, 'request.json');
+    });
+    const names = await readdir(out);
+    if (!names.length && !resume)
+        return;
+    try {
+        const saved = JSON.parse(await readFile(join(out, 'request.json'), 'utf8'));
+        if (resume && saved.schemaVersion === 'playcraft.video-request.v1' && saved.runId === runId && saved.out === resolve(out))
+            return;
+    }
+    catch { /* An unrelated or incomplete output directory must not be overwritten. */ }
+    throw new VideoCliError('outputConflict', 64);
+}
+export async function loadSavedRequest(out, runId, workspaceId) {
+    try {
+        await videoOutput(() => comparisonOutputPath(out, 'request.json'));
+        const value = JSON.parse(await readFile(join(out, 'request.json'), 'utf8'));
+        if (value.schemaVersion !== 'playcraft.video-request.v1' || value.runId !== runId || value.workspaceId !== workspaceId || value.out !== resolve(out) || typeof value.videoPath !== 'string')
+            throw new Error('invalid');
+        return value;
+    }
+    catch {
+        throw new VideoCliError('resumeMissing', 64);
+    }
+}
+const escapeXml = (text) => text.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
+const escapeMarkdown = (text) => text.replace(/([\\`*_[\]<>])/g, '\\$1');
+export function renderVideoAnalysis(analysis, frames) {
+    const lines = [`# ${videoMessage('summary')}`, '', escapeMarkdown(analysis.summary), '', videoMessage('transcriptNotice'), ''];
+    for (const [key, items] of [
+        ['observations', analysis.observations], ['inferences', analysis.inferences], ['unknowns', analysis.unknowns],
+    ]) {
+        lines.push(`## ${videoMessage(key)}`, '');
+        for (const item of items) {
+            const confidence = 'confidence' in item ? ` (${item.confidence})` : '';
+            lines.push(`- **${escapeMarkdown(item.id)}**${confidence}: ${escapeMarkdown(item.text)}`);
+        }
+        lines.push('');
+    }
+    lines.push(`## ${videoMessage('events')}`, '');
+    for (const event of analysis.events)
+        lines.push(`- ${escapeMarkdown(event.id)} [${event.startMs}–${event.endMs} ms]: ${event.kind}`);
+    lines.push('', `## ${videoMessage('hints')}`, '');
+    for (const [key, items] of Object.entries(analysis.reconstructionHints)) {
+        lines.push(`### ${videoMessage(key === 'candidateRules' ? 'rules' : key)}`, '');
+        for (const item of items)
+            lines.push(`- ${escapeMarkdown(item)}`);
+        lines.push('');
+    }
+    lines.push(`## ${videoMessage('evidence')}`, '');
+    for (const evidence of analysis.evidence)
+        lines.push(`- ${escapeMarkdown(evidence.id)} [${evidence.startMs}–${evidence.endMs} ms]: [frame](${frames.get(evidence.id)})`);
+    return `${lines.join('\n')}\n`;
+}
+/** Materialize only validated original-video timestamps; the model never supplies file paths. */
+export async function materializeVideoEvidence(input) {
+    let analysis;
+    try {
+        analysis = videoUnderstandingAnalysisSchema.parse(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, input.request?.clip);
+    }
+    catch {
+        throw new VideoCliError('invalidResult');
+    }
+    // Refuse any redirected destination before replacing evidence from a previous attempt.
+    await videoOutput(async () => {
+        await comparisonOutputRoot(input.out, true);
+        for (const path of [...analysis.evidence.map(item => `keyframes/${item.id}.png`), 'analysis.json', 'analysis.md', 'manifest.json', 'contact-sheet.jpg'])
+            await comparisonOutputPath(input.out, path);
+    });
+    const file = await openVideo(input.sourcePath);
+    const frames = new Map();
+    const manifestFrames = [];
+    const tiles = [];
+    const width = 240;
+    const height = 200;
+    const columns = Math.min(4, analysis.evidence.length);
+    try {
+        await verifyVideo(file, analysis.source);
+        const frameOutput = 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 rawFrameTimes = frameOutput.split('\n').map(line => Number.parseFloat(line) * 1000).filter(Number.isFinite);
+        const firstFrameTime = rawFrameTimes[0] ?? 0;
+        const frameTimes = rawFrameTimes.map(time => time - firstFrameTime).filter(time => time >= 0 && time < analysis.source.durationMs);
+        if (!frameTimes.length)
+            throw new VideoCliError('invalidResult');
+        for (const [index, evidence] of analysis.evidence.entries()) {
+            input.signal?.throwIfAborted();
+            const path = `keyframes/${evidence.id}.png`;
+            // Quantize the model's suggested midpoint to a real decoded frame, including the final frame.
+            const requestedTimeMs = (evidence.startMs + evidence.endMs) / 2;
+            const timeMs = frameTimes.reduce((best, candidate) => Math.abs(candidate - requestedTimeMs) < Math.abs(best - requestedTimeMs) ? candidate : best);
+            await videoOutput(() => 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 VideoCliError('invalidResult');
+            frames.set(evidence.id, path);
+            manifestFrames.push({ evidenceId: evidence.id, timeMs, requestedTimeMs, path, sha256: createHash('sha256').update(bytes).digest('hex') });
+            const thumbnail = await sharp(bytes).resize(width, height - 30, { fit: 'contain', background: '#f4f4f4' }).png().toBuffer();
+            const label = Buffer.from(`<svg width="${width}" height="30"><rect width="100%" height="100%" fill="white"/><text x="8" y="20" font-size="12">${escapeXml(evidence.id)} ${(timeMs / 1000).toFixed(2)}s</text></svg>`);
+            const tile = await sharp({ create: { width, height, channels: 3, background: '#ffffff' } }).composite([{ input: thumbnail, top: 0, left: 0 }, { input: label, top: height - 30, left: 0 }]).png().toBuffer();
+            tiles.push({ input: tile, left: (index % columns) * width, top: Math.floor(index / columns) * height });
+        }
+        await verifyVideo(file, analysis.source);
+    }
+    finally {
+        await file.close();
+    }
+    const contactSheet = join(input.out, 'contact-sheet.jpg');
+    await videoOutput(() => writeComparisonArtifact(input.out, 'contact-sheet.jpg', temporary => sharp({ create: { width: columns * width, height: Math.ceil(tiles.length / columns) * height, channels: 3, background: '#dddddd' } }).composite(tiles).jpeg({ quality: 85 }).toFile(temporary)));
+    // Keep analysis.json compatible with the shared schema; local frame references live in the manifest.
+    const analysisPath = join(input.out, 'analysis.json');
+    const markdown = join(input.out, 'analysis.md');
+    await writeJsonAtomic(analysisPath, analysis);
+    await videoOutput(() => writeComparisonArtifact(input.out, 'analysis.md', temporary => writeFile(temporary, renderVideoAnalysis(analysis, frames), { mode: 0o600, flag: 'wx' })));
+    const manifest = join(input.out, 'manifest.json');
+    await writeJsonAtomic(manifest, {
+        schemaVersion: 'playcraft.video-evidence.v1', runId: analysis.runId, state: 'completed', source: analysis.source, model: analysis.model,
+        analysis: 'analysis.json', markdown: 'analysis.md', contactSheet: 'contact-sheet.jpg',
+        frames: manifestFrames, frameTimeSemantics: 'nearest-decoded-original-video-frame',
+    });
+    return { manifest, analysis: analysisPath, markdown, contactSheet, keyframes: manifestFrames.map(frame => join(input.out, frame.path)) };
+}

package/dist/video-replication/media.js

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { open, realpath } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { VIDEO_MAX_BYTES, videoSourceSchema, } from '@playcraft/common/agent-tools';
+import { VideoCliError } from './messages.js';
+/** No shell, external protocols, or unbounded child-process output. */
+export function runMediaTool(tool, args, inputFd, signal) {
+    return new Promise((resolve, reject) => {
+        const override = process.env[tool === 'ffmpeg' ? 'FFMPEG_PATH' : 'FFPROBE_PATH'];
+        if (override && !isAbsolute(override)) {
+            reject(new VideoCliError('mediaTool'));
+            return;
+        }
+        const child = spawn(override || tool, args, { stdio: ['ignore', 'pipe', 'pipe', inputFd], signal });
+        let output = '';
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(new VideoCliError('mediaTool'));
+        }, 30_000);
+        child.stdout.on('data', chunk => {
+            output += chunk.toString();
+            if (output.length > 1024 * 1024) {
+                child.kill('SIGKILL');
+                finish(new VideoCliError('videoFormat'));
+            }
+        });
+        child.stderr.on('data', () => { });
+        child.once('error', error => finish(error.name === 'AbortError' ? error : new VideoCliError('mediaTool')));
+        child.once('close', code => finish(code === 0 ? undefined : new VideoCliError('videoFormat')));
+    });
+}
+export async function openVideo(path) {
+    try {
+        const file = await open(path, 'r');
+        const stat = await file.stat();
+        if (!stat.isFile()) {
+            await file.close();
+            throw new VideoCliError('videoMissing', 64);
+        }
+        if (stat.size <= 0 || stat.size > VIDEO_MAX_BYTES) {
+            await file.close();
+            throw new VideoCliError('videoQuota', 64);
+        }
+        return file;
+    }
+    catch (error) {
+        if (error instanceof VideoCliError)
+            throw error;
+        throw new VideoCliError('videoMissing', 64);
+    }
+}
+async function digests(file) {
+    const sha = createHash('sha256');
+    const md5 = createHash('md5');
+    for await (const chunk of file.createReadStream({ autoClose: false, start: 0 })) {
+        sha.update(chunk);
+        md5.update(chunk);
+    }
+    return { sha256: sha.digest('hex'), contentMd5: md5.digest('base64') };
+}
+export async function probeVideo(path, signal) {
+    const absolute = await realpath(path).catch(() => { throw new VideoCliError('videoMissing', 64); });
+    const file = await openVideo(absolute);
+    try {
+        const stat = await file.stat();
+        const magic = Buffer.alloc(16);
+        await file.read(magic, 0, magic.length, 0);
+        const isIso = magic.subarray(4, 8).toString('ascii') === 'ftyp';
+        const isWebm = magic.readUInt32BE(0) === 0x1a45dfa3;
+        if (!isIso && !isWebm)
+            throw new VideoCliError('videoFormat', 64);
+        const output = await runMediaTool('ffprobe', [
+            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-format_whitelist', 'mov,matroska,webm',
+            '-show_entries', 'format=duration,format_name:stream=codec_type,width,height,duration',
+            '-of', 'json', '/dev/fd/3',
+        ], file.fd, signal);
+        const result = JSON.parse(output);
+        const video = result.streams?.find(stream => stream.codec_type === 'video');
+        if (!video)
+            throw new VideoCliError('videoFormat', 64);
+        const durationMs = Number(result.format?.duration ?? video.duration) * 1000;
+        const hashes = await digests(file);
+        const parsed = videoSourceSchema.safeParse({
+            sha256: hashes.sha256, sizeBytes: stat.size, durationMs, width: video.width, height: video.height,
+            mimeType: isWebm ? 'video/webm' : magic.subarray(8, 12).toString('ascii') === 'qt  ' ? 'video/quicktime' : 'video/mp4',
+        });
+        if (!parsed.success)
+            throw new VideoCliError('videoQuota', 64);
+        return { path: absolute, source: parsed.data, contentMd5: hashes.contentMd5 };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function verifyVideo(file, expected) {
+    const stat = await file.stat();
+    if (stat.size !== expected.sizeBytes || (await digests(file)).sha256 !== expected.sha256)
+        throw new VideoCliError('sourceChanged', 64);
+}