@hecer/yoke 1.3.0 → 1.5.0

package/dist/loop/worker.js

@@ -0,0 +1,254 @@
+import { isAcceptanceCriterion } from './prd.js';
+import { runQualityRepairLoop } from '../quality/loop.js';
+function emptyEvidence() { return { criteria: [] }; }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertNever(value) {
+    throw new Error(`Unexpected worker result: ${String(value)}`);
+}
+function cancellationReason(cancellation) {
+    if (cancellation?.signal?.aborted) {
+        return typeof cancellation.signal.reason === 'string' && cancellation.signal.reason.length > 0
+            ? cancellation.signal.reason
+            : 'worker cancellation requested';
+    }
+    return cancellation?.handle?.isCancelled() ? 'worker cancellation requested' : null;
+}
+function runGate(gate, worktree, storyId) {
+    const previous = process.env.YOKE_STORY;
+    process.env.YOKE_STORY = storyId;
+    try {
+        return gate(worktree);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.YOKE_STORY;
+        else
+            process.env.YOKE_STORY = previous;
+    }
+}
+function reviewOutcome(result) {
+    if (result.reviewOutcome)
+        return result.reviewOutcome;
+    if (result.success)
+        return { kind: 'approved', verdict: { approved: true, summary: result.summary, findings: [] } };
+    return { kind: 'malformed', summary: result.summary };
+}
+function runMechanicalGates(input, context, evidence) {
+    const criteria = context.story.acceptance.filter(isAcceptanceCriterion);
+    if (criteria.length === 0) {
+        if (input.requireCriterionEvidence)
+            return { kind: 'failed', stage: 'criterion', summary: `story ${context.story.id} lacks executable criterion evidence` };
+    }
+    else {
+        if (!input.verifyCriterion)
+            return { kind: 'failed', stage: 'criterion', summary: `story ${context.story.id} has criteria but no criterion verifier` };
+        for (const criterion of criteria) {
+            const cancelled = cancellationReason(input.cancellation);
+            if (cancelled)
+                return { kind: 'cancelled', summary: cancelled };
+            const result = input.verifyCriterion(context.targetDir, context.story, criterion);
+            const criteriaEvidence = [...evidence.criteria, { id: criterion.id, passed: result.passed, summary: result.summary }];
+            evidence.criteria = criteriaEvidence;
+            input.callbacks?.onGate?.('criterion', result);
+            if (!result.passed)
+                return { kind: 'failed', stage: 'criterion', summary: result.summary };
+        }
+    }
+    const cancelled = cancellationReason(input.cancellation);
+    if (cancelled)
+        return { kind: 'cancelled', summary: cancelled };
+    input.reporter?.phase('verifying');
+    const verify = runGate(input.verify, context.targetDir, context.story.id);
+    evidence.verify = verify;
+    input.callbacks?.onGate?.('verify', verify);
+    if (!verify.passed)
+        return { kind: 'failed', stage: 'verify', summary: verify.summary };
+    const afterVerifyCancellation = cancellationReason(input.cancellation);
+    if (afterVerifyCancellation)
+        return { kind: 'cancelled', summary: afterVerifyCancellation };
+    if (input.perf) {
+        input.reporter?.phase('perf');
+        const perf = runGate(input.perf, context.targetDir, context.story.id);
+        evidence.perf = perf;
+        input.callbacks?.onGate?.('perf', perf);
+        if (!perf.passed)
+            return { kind: 'failed', stage: 'perf', summary: perf.summary };
+        const afterPerfCancellation = cancellationReason(input.cancellation);
+        if (afterPerfCancellation)
+            return { kind: 'cancelled', summary: afterPerfCancellation };
+    }
+    if (input.audit) {
+        input.reporter?.phase('audit');
+        const audit = runGate(input.audit, context.targetDir, context.story.id);
+        evidence.audit = audit;
+        input.callbacks?.onGate?.('audit', audit);
+        if (!audit.passed)
+            return { kind: 'failed', stage: 'audit', summary: audit.summary };
+        const afterAuditCancellation = cancellationReason(input.cancellation);
+        if (afterAuditCancellation)
+            return { kind: 'cancelled', summary: afterAuditCancellation };
+    }
+    return { kind: 'passed' };
+}
+function finalResult(input, result) {
+    input.callbacks?.onResult?.(result);
+    return result;
+}
+function baseResult(input, evidence, summary) {
+    return {
+        storyId: input.story.id,
+        worktree: input.worktree,
+        baseCommit: input.baseCommit,
+        provider: input.provider,
+        summary,
+        evidence,
+    };
+}
+function resultFromQuality(input, evidence, summary, outcome) {
+    switch (outcome.kind) {
+        case 'approved':
+            return {
+                ...baseResult(input, evidence, summary),
+                kind: 'candidate',
+                routing: { outcome: 'pending-integration' },
+            };
+        case 'paused':
+            return { ...baseResult(input, evidence, summary), kind: 'paused' };
+        case 'cancelled':
+            return { ...baseResult(input, evidence, outcome.summary), kind: 'cancelled' };
+        case 'blocked':
+            switch (outcome.reason) {
+                case 'quality-inconsistent':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'quality-failure', reason: 'inconsistent' };
+                case 'quality-infrastructure':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'quality-failure', reason: 'infrastructure' };
+                case 'review-malformed':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'review-failure', reason: 'malformed' };
+                case 'review-infrastructure':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'review-failure', reason: 'infrastructure' };
+                case 'gate-failed':
+                    return { ...baseResult(input, evidence, outcome.summary), kind: 'mechanical-failure', stage: outcome.stage };
+                case 'no-actionable-finding':
+                case 'round-budget-exhausted':
+                case 'time-budget-exhausted':
+                case 'repair-failed':
+                    return { ...baseResult(input, evidence, outcome.summary ?? outcome.reason), kind: 'mechanical-failure', stage: 'quality' };
+                default:
+                    return assertNever(outcome);
+            }
+        default:
+            return assertNever(outcome);
+    }
+}
+export async function runStoryWorker(input) {
+    const evidence = emptyEvidence();
+    const cancelled = cancellationReason(input.cancellation);
+    if (cancelled)
+        return finalResult(input, { ...baseResult(input, evidence, cancelled), kind: 'cancelled' });
+    const workerStory = structuredClone(input.story);
+    const context = { targetDir: input.worktree, story: workerStory };
+    const qualityEnabled = input.qualityEnabled?.(workerStory) ?? input.qualityStage !== undefined;
+    const preflight = qualityEnabled ? input.qualityPreflight?.(context) : undefined;
+    if (preflight?.kind === 'blocked') {
+        return finalResult(input, { ...baseResult(input, evidence, preflight.summary), kind: 'mechanical-failure', stage: 'quality' });
+    }
+    let implementation;
+    try {
+        implementation = await input.runner(context);
+    }
+    catch (error) {
+        return finalResult(input, {
+            ...baseResult(input, evidence, `worker implementation failed: ${errorMessage(error)}`),
+            kind: 'mechanical-failure',
+            stage: 'implementation',
+        });
+    }
+    if (implementation.tokens)
+        input.reporter?.addTokens(implementation.tokens);
+    const afterImplementationCancellation = cancellationReason(input.cancellation);
+    if (afterImplementationCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, afterImplementationCancellation), kind: 'cancelled' });
+    }
+    const decision = input.beforeGates?.(context);
+    if (decision) {
+        return finalResult(input, { ...baseResult(input, evidence, decision), kind: 'paused', reason: 'decision' });
+    }
+    const gates = runMechanicalGates(input, context, evidence);
+    if (gates.kind === 'cancelled') {
+        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'cancelled' });
+    }
+    if (gates.kind === 'failed') {
+        implementation.routing?.recordOutcome(false);
+        return finalResult(input, { ...baseResult(input, evidence, gates.summary), kind: 'mechanical-failure', stage: gates.stage });
+    }
+    const summary = implementation.success
+        ? implementation.summary
+        : `${implementation.summary} (runner exited non-zero but verify is green)`;
+    if (!qualityEnabled && !input.review) {
+        return finalResult(input, {
+            ...baseResult(input, evidence, summary),
+            kind: 'candidate',
+            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+        });
+    }
+    const beforeQualityCancellation = cancellationReason(input.cancellation);
+    if (beforeQualityCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, beforeQualityCancellation), kind: 'cancelled' });
+    }
+    const qualityStage = qualityEnabled ? input.qualityStage : undefined;
+    const review = input.review;
+    const quality = runQualityRepairLoop({
+        ...(qualityStage
+            ? { quality: (round) => {
+                    input.reporter?.phase('comparing');
+                    return qualityStage(context, round);
+                } }
+            : {}),
+        ...(review
+            ? { review: () => {
+                    input.reporter?.phase('reviewing');
+                    return reviewOutcome(review(context));
+                } }
+            : {}),
+        repair: request => {
+            if (!input.repair)
+                return { kind: 'blocked', summary: 'repair callback is not configured' };
+            input.reporter?.phase('repairing');
+            const repair = input.repair(context, request);
+            return repair.success ? { kind: 'repaired' } : { kind: 'blocked', summary: repair.summary };
+        },
+        rerunGates: () => {
+            const rerun = runMechanicalGates(input, context, evidence);
+            if (rerun.kind === 'passed')
+                return { kind: 'passed' };
+            if (rerun.kind === 'cancelled')
+                return rerun;
+            return { kind: 'failed', stage: rerun.stage, summary: rerun.summary };
+        },
+        ...(input.repairLimits ? { limits: input.repairLimits } : {}),
+        pause: input.pause,
+        onStatus: status => {
+            const metadata = input.qualityMetadata?.(context);
+            input.reporter?.quality({ ...status, ...(metadata ?? { policy: 'blocking' }) });
+        },
+    });
+    evidence.quality = quality;
+    const afterQualityCancellation = cancellationReason(input.cancellation);
+    if (afterQualityCancellation) {
+        return finalResult(input, { ...baseResult(input, evidence, afterQualityCancellation), kind: 'cancelled' });
+    }
+    const result = resultFromQuality(input, evidence, summary, quality);
+    if (result.kind !== 'candidate' && result.kind !== 'paused')
+        implementation.routing?.recordOutcome(false);
+    if (result.kind === 'candidate') {
+        return finalResult(input, {
+            ...result,
+            routing: { outcome: 'pending-integration', ...(implementation.routing ? { recordOutcome: implementation.routing.recordOutcome } : {}) },
+            ...(implementation.tokens ? { tokens: implementation.tokens } : {}),
+        });
+    }
+    return finalResult(input, result);
+}

package/dist/output/artifact.js

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+function safeLabel(value) {
+    const cleaned = (value ?? '')
+        .replace(/[^A-Za-z0-9._-]+/gu, '-')
+        .replace(/^[.-]+|[.-]+$/gu, '')
+        .slice(0, 80);
+    return cleaned || 'session';
+}
+function assertContained(root, candidate) {
+    const fromRoot = relative(resolve(root), resolve(candidate));
+    if (fromRoot.startsWith('..') || isAbsolute(fromRoot))
+        throw new Error('artifact path escaped the project artifact root');
+}
+export function writeOutputArtifact(targetDir, raw, options) {
+    const sha256 = createHash('sha256').update(raw).digest('hex');
+    const label = safeLabel(options.storyId);
+    const relativeDir = join('.yoke', 'artifacts', label);
+    const projectRoot = realpathSync(targetDir);
+    const yokeRoot = join(targetDir, '.yoke');
+    if (existsSync(yokeRoot)) {
+        if (lstatSync(yokeRoot).isSymbolicLink())
+            throw new Error('artifact root parent must not be a symlink');
+        assertContained(projectRoot, realpathSync(yokeRoot));
+    }
+    else {
+        mkdirSync(yokeRoot, { mode: 0o700 });
+    }
+    const artifactRoot = join(targetDir, '.yoke', 'artifacts');
+    mkdirSync(artifactRoot, { recursive: true, mode: 0o700 });
+    if (lstatSync(artifactRoot).isSymbolicLink())
+        throw new Error('artifact root must not be a symlink');
+    const resolvedArtifactRoot = realpathSync(artifactRoot);
+    assertContained(projectRoot, resolvedArtifactRoot);
+    const artifactDir = join(artifactRoot, label);
+    mkdirSync(artifactDir, { recursive: true, mode: 0o700 });
+    assertContained(resolvedArtifactRoot, realpathSync(artifactDir));
+    let digestLength = 12;
+    let filename = `${options.phase}-${sha256.slice(0, digestLength)}.log`;
+    let file = join(artifactDir, filename);
+    while (existsSync(file) && !lstatSync(file).isSymbolicLink() && createHash('sha256').update(readFileSync(file)).digest('hex') !== sha256) {
+        if (digestLength === sha256.length)
+            throw new Error('artifact digest path contains mismatched content');
+        digestLength = Math.min(sha256.length, digestLength + 8);
+        filename = `${options.phase}-${sha256.slice(0, digestLength)}.log`;
+        file = join(artifactDir, filename);
+    }
+    if (existsSync(file) && lstatSync(file).isSymbolicLink())
+        throw new Error('artifact file must not be a symlink');
+    if (!existsSync(file))
+        writeFileSync(file, raw, { encoding: 'utf8', mode: 0o600 });
+    else
+        chmodSync(file, 0o600);
+    const relativePath = `${relativeDir.replace(/\\/gu, '/')}/${filename}`;
+    const bytes = Buffer.byteLength(raw);
+    return {
+        relativePath,
+        bytes,
+        sha256,
+        marker: `[full output: ${relativePath} | ${bytes} bytes | sha256:${sha256}]`,
+    };
+}

package/dist/output/compact.js

@@ -0,0 +1,192 @@
+const OSC = /(?:\x1B\]|\u009D)[^\x07\x1B\u009C]*(?:\x07|\x1B\\|\u009C)/gu;
+const ANSI = /(?:\x1B\[|\u009B)[0-?]*[ -/]*[@-~]/gu;
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/gu;
+const ERROR_SIGNAL = /(?:(?:^|[^A-Za-z0-9])error(?:[^A-Za-z0-9]|$)|\bfail(?:ed|ure)?\b|\bnot ok\b|\bassertionerror\b|\bfatal\b|\bpanic\b|\bexception\b|\btraceback\b|\bE\d{4}\b|\bTS\d{4}\b|(?:^|\s)[✗✘×](?:\s|$))/iu;
+const WARNING_SIGNAL = /(?:\bwarn(?:ing)?\b|\bdeprecat(?:ed|ion)\b)/iu;
+const SUMMARY_SIGNAL = /^\s*(?:Test Files|Tests?|Test Suites?|Suites?|Ran all test suites|Failures?|Passed|Failed)(?:\s|:|$)/iu;
+function cleanLine(line) {
+    return line.replace(OSC, '').replace(ANSI, '').replace(CONTROL, '').trimEnd();
+}
+function utf8Prefix(value, maxBytes) {
+    if (maxBytes <= 0)
+        return '';
+    let used = 0;
+    let result = '';
+    for (const char of value) {
+        const bytes = Buffer.byteLength(char);
+        if (used + bytes > maxBytes)
+            break;
+        result += char;
+        used += bytes;
+    }
+    return result;
+}
+const MAX_PRIORITY_CANDIDATES = 1_024;
+const MAX_DISTINCT_LINES = 4_096;
+function addCandidate(candidates, indexes, entry) {
+    if (!entry || entry.line.trim() === '' || indexes.has(entry.index))
+        return;
+    if (candidates.length >= MAX_PRIORITY_CANDIDATES)
+        return;
+    indexes.add(entry.index);
+    candidates.push(entry);
+}
+function scanLines(raw, maxLineBytes) {
+    const errorCandidates = [];
+    const warningCandidates = [];
+    const errorIndexes = new Set();
+    const warningIndexes = new Set();
+    const tail = [];
+    const fallback = [];
+    const distinctNonEmpty = new Set();
+    let distinctOverflow = false;
+    let clippedLine = false;
+    let previous;
+    let pendingErrorContext = false;
+    let pendingWarningContext = false;
+    let firstError;
+    let firstWarning;
+    let firstNonEmpty;
+    let finalLine;
+    let finalSummary;
+    let index = 0;
+    let start = 0;
+    while (true) {
+        const newline = raw.indexOf('\n', start);
+        const end = newline === -1 ? raw.length : newline;
+        const cleaned = cleanLine(raw.slice(start, end));
+        const cleanedBytes = Buffer.byteLength(cleaned);
+        const line = cleanedBytes <= maxLineBytes ? cleaned : utf8Prefix(cleaned, maxLineBytes);
+        if (line !== cleaned)
+            clippedLine = true;
+        const current = { index, line };
+        if (index < 2)
+            fallback.push(current);
+        tail.push(current);
+        if (tail.length > 4)
+            tail.shift();
+        const nonEmpty = cleaned.trim() !== '';
+        if (nonEmpty) {
+            firstNonEmpty ??= line;
+            finalLine = line;
+            if (!distinctOverflow) {
+                distinctNonEmpty.add(line);
+                if (distinctNonEmpty.size > MAX_DISTINCT_LINES) {
+                    distinctOverflow = true;
+                    distinctNonEmpty.clear();
+                }
+            }
+        }
+        if (SUMMARY_SIGNAL.test(cleaned))
+            finalSummary = line;
+        if (pendingErrorContext)
+            addCandidate(errorCandidates, errorIndexes, current);
+        if (pendingWarningContext)
+            addCandidate(warningCandidates, warningIndexes, current);
+        pendingErrorContext = false;
+        pendingWarningContext = false;
+        if (ERROR_SIGNAL.test(cleaned)) {
+            firstError ??= line;
+            addCandidate(errorCandidates, errorIndexes, current);
+            addCandidate(errorCandidates, errorIndexes, previous);
+            pendingErrorContext = true;
+        }
+        if (WARNING_SIGNAL.test(cleaned)) {
+            firstWarning ??= line;
+            addCandidate(warningCandidates, warningIndexes, current);
+            addCandidate(warningCandidates, warningIndexes, previous);
+            pendingWarningContext = true;
+        }
+        previous = current;
+        if (newline === -1)
+            break;
+        index++;
+        start = newline + 1;
+    }
+    return {
+        originalLines: index + 1,
+        errorCandidates,
+        warningCandidates,
+        tail,
+        fallback,
+        firstSignal: firstError ?? firstWarning ?? firstNonEmpty,
+        ...(finalLine === undefined ? {} : { finalLine }),
+        ...(finalSummary === undefined ? {} : { finalSummary }),
+        distinctNonEmpty,
+        completePossible: !distinctOverflow && !clippedLine,
+    };
+}
+function uniqueCandidateLines(scan) {
+    const seenIndexes = new Set();
+    const seenLines = new Set();
+    const selected = [];
+    const prioritized = [
+        ...scan.errorCandidates,
+        ...scan.warningCandidates,
+        ...scan.tail,
+        ...(scan.errorCandidates.length + scan.warningCandidates.length === 0 ? scan.fallback : []),
+    ];
+    for (const entry of prioritized) {
+        if (entry.line.trim() === '' || seenIndexes.has(entry.index))
+            continue;
+        seenIndexes.add(entry.index);
+        if (seenLines.has(entry.line))
+            continue;
+        seenLines.add(entry.line);
+        selected.push(entry.line);
+    }
+    return selected;
+}
+export function compactCommandOutput(raw, options) {
+    const originalBytes = Buffer.byteLength(raw);
+    if (raw === '')
+        return { preview: '', originalBytes: 0, originalLines: 0, omitted: false };
+    const scan = scanLines(raw, options.previewBytes);
+    const originalLines = scan.originalLines;
+    const candidates = uniqueCandidateLines(scan);
+    const complete = scan.completePossible && candidates.length >= scan.distinctNonEmpty.size;
+    const joined = candidates.join('\n');
+    if (complete && Buffer.byteLength(joined) <= options.previewBytes) {
+        return { preview: joined, originalBytes, originalLines, omitted: false };
+    }
+    const marker = `[… omitted; ${originalLines} lines, ${originalBytes} bytes total …]`;
+    const markerBytes = Buffer.byteLength(marker);
+    const contentBudget = Math.max(0, options.previewBytes - markerBytes - 1);
+    const selected = [];
+    let used = 0;
+    const essentials = [...new Set([scan.firstSignal, scan.finalSummary ?? scan.finalLine]
+            .filter((line) => Boolean(line)))];
+    for (const [index, line] of essentials.entries()) {
+        const separator = selected.length === 0 ? 0 : 1;
+        const remaining = essentials.length - index - 1;
+        const available = Math.max(0, contentBudget - used - separator - remaining);
+        const lineBudget = remaining === 0 ? available : Math.floor(available / (remaining + 1));
+        const value = utf8Prefix(line, lineBudget);
+        if (!value)
+            continue;
+        selected.push(value);
+        used += separator + Buffer.byteLength(value);
+    }
+    for (const line of candidates) {
+        if (essentials.includes(line))
+            continue;
+        const separator = selected.length === 0 ? 0 : 1;
+        const bytes = Buffer.byteLength(line);
+        if (used + separator + bytes <= contentBudget) {
+            selected.push(line);
+            used += separator + bytes;
+            continue;
+        }
+        if (selected.length === 0 && contentBudget > 0) {
+            const truncated = utf8Prefix(line, contentBudget);
+            selected.push(truncated);
+            used = Buffer.byteLength(truncated);
+            break;
+        }
+    }
+    const content = selected.filter(Boolean).join('\n');
+    const preview = content
+        ? `${content}\n${utf8Prefix(marker, options.previewBytes - Buffer.byteLength(content) - 1)}`
+        : utf8Prefix(marker, options.previewBytes);
+    return { preview, originalBytes, originalLines, omitted: true };
+}

package/dist/output/types.js

@@ -0,0 +1,4 @@
+export const DEFAULT_OUTPUT_POLICY = {
+    previewBytes: 2_048,
+    artifactThresholdBytes: 8_192,
+};

package/dist/quality/artifacts.js

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { hasShellControlOperator, parseQualityCommand } from './process-command.js';
+export function collectCandidateArtifacts(input, adapters) {
+    const captured = captureCandidateArtifacts(input, adapters);
+    if (captured.kind === 'rejected')
+        return captured;
+    return { kind: 'collected', artifacts: captured.artifacts.map(value => value.artifact), digests: captured.digests };
+}
+export function captureCandidateArtifacts(input, adapters) {
+    if ('command' in input.candidate) {
+        if (hasShellControlOperator(input.candidate.command))
+            return { kind: 'rejected', reason: 'shell-control' };
+        if (!parseQualityCommand(input.candidate.command))
+            return { kind: 'rejected', reason: 'invalid-command' };
+        const bytes = input.candidate.kind === 'command-output'
+            ? adapters.commandOutput(input.candidate.command)
+            : adapters.benchmark(input.candidate.command);
+        const artifact = { kind: input.candidate.kind, source: input.candidate.command, bytes: bytes.byteLength, digest: digest(bytes) };
+        return { kind: 'captured', artifacts: [{ artifact, bytes }], digests: [artifact.digest] };
+    }
+    const projectRoot = resolve(input.projectDir);
+    const proofRoot = join(projectRoot, '.yoke', 'proof');
+    const kind = input.candidate.kind === 'screenshots' ? 'screenshot' : 'file';
+    const artifacts = [];
+    for (const source of input.candidate.paths) {
+        if (containsTraversal(source))
+            return { kind: 'rejected', reason: 'path-traversal' };
+        if (isAbsolute(source))
+            return { kind: 'rejected', reason: 'outside-project' };
+        const path = resolve(projectRoot, source);
+        if (!isInside(projectRoot, path))
+            return { kind: 'rejected', reason: 'outside-project' };
+        if (kind === 'screenshot' && !isInside(proofRoot, path))
+            return { kind: 'rejected', reason: 'outside-proof' };
+        const canonicalRoot = adapters.realpath?.(projectRoot) ?? projectRoot;
+        const canonicalPath = adapters.realpath?.(path) ?? path;
+        if (!isInside(canonicalRoot, canonicalPath))
+            return { kind: 'rejected', reason: 'outside-project' };
+        if (kind === 'screenshot' && !isInside(adapters.realpath?.(proofRoot) ?? proofRoot, canonicalPath))
+            return { kind: 'rejected', reason: 'outside-proof' };
+        const bytes = adapters.readFile(canonicalPath);
+        if (bytes === null)
+            return { kind: 'rejected', reason: 'missing' };
+        artifacts.push({ artifact: { kind, path: canonicalPath, bytes: bytes.byteLength, digest: digest(bytes) }, bytes });
+    }
+    artifacts.sort((left, right) => left.artifact.digest.localeCompare(right.artifact.digest) || (left.artifact.path ?? '').localeCompare(right.artifact.path ?? ''));
+    return { kind: 'captured', artifacts, digests: artifacts.map(artifact => artifact.artifact.digest) };
+}
+function digest(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function containsTraversal(path) {
+    return path.split(/[\\/]+/).includes('..');
+}
+function isInside(root, path) {
+    const relativePath = relative(root, path);
+    return relativePath === '' || (!relativePath.startsWith(`..${sep}`) && relativePath !== '..' && !isAbsolute(relativePath));
+}