@atmin.ai/review 0.1.0-alpha.2

package/dist/provider-error.js

@@ -0,0 +1,21 @@
+// Only controller-owned messages and allowlisted codes are safe to persist.
+const funding = new Set(['credit_balance_exhausted', 'insufficient_quota', 'organization_spend_limit_exceeded', 'project_spend_limit_exceeded']);
+export class ProviderRequestError extends Error {
+    failure;
+    constructor(stage, status, code) {
+        const kind = code && funding.has(code) ? 'funding'
+            : status === 401 || status === 403 ? 'authentication'
+                : status === 429 ? 'rate-limit'
+                    : status !== undefined && status >= 400 && status < 500 ? 'request' : 'unavailable';
+        const messages = {
+            funding: 'Provider funding unavailable: add API credits or check the account spending limit.',
+            authentication: 'Provider authentication or access denied: check the configured API project and key.',
+            'rate-limit': 'Provider rate limit reached: pause the experiment before another attempt.',
+            request: 'Provider rejected the request: inspect adapter compatibility before another attempt.',
+            unavailable: 'Provider unavailable: the request failed without confirmed usage.',
+        };
+        super(messages[kind]);
+        this.failure = { kind, stage, status: Number.isInteger(status) && status >= 100 && status <= 599 ? status : null,
+            code: code && funding.has(code) ? code : null };
+    }
+}

package/dist/render.d.ts

@@ -0,0 +1,4 @@
+import type { Packet, Result } from './contracts.js';
+import type { Assessment } from './assessment.js';
+export declare function escapeMarkdown(value: string): string;
+export declare function renderMarkdown(packet: Packet, result: Result, assessment: Assessment): string;

package/dist/render.js

@@ -0,0 +1,56 @@
+export function escapeMarkdown(value) {
+    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f\u202a-\u202e\u2066-\u2069]/g, '')
+        .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+        .replaceAll('@', '@\u200b').replace(/([\\`*_{}[\]()#+!|])/g, '\\$1');
+}
+function sourceLink(packet, anchor) {
+    const revision = anchor.side === 'head' ? packet.headSha : packet.mergeBaseSha;
+    const path = anchor.path.split('/').map(part => encodeURIComponent(part).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join('/');
+    const line = anchor.line === null ? '' : `#L${anchor.line}`;
+    const label = escapeMarkdown(anchor.path.replaceAll('\n', '\\n')) + (anchor.line === null ? '' : `:${anchor.line}`);
+    return `[${label}](https://github.com/${packet.repository}/blob/${revision}/${path}${line})`;
+}
+export function renderMarkdown(packet, result, assessment) {
+    const e = escapeMarkdown;
+    const headline = assessment.freshness.status === 'current' ? assessment.findingsVerdict : assessment.outcome;
+    const icon = headline === 'No issues found' ? '✅' : headline === 'Changes needed' ? '🔴' : '⚠️';
+    const count = (priorities) => assessment.findings.filter(f => priorities.includes(f.priority)).length;
+    const reviewed = result.coverage.filter(c => c.status === 'reviewed').length;
+    const validation = { passed: '✅ Passed', failed: '❌ Failed', missing: '⏳ Not verified', 'not-applicable': 'Not required' }[assessment.validation];
+    const lines = [
+        `## ${icon} ${headline}`, '',
+        `**atmin review** · ${assessment.scope === 'complete' ? 'Source review complete' : 'Source review incomplete'}`, '',
+        '| Changes needed · P0–P2 | Minor issues · P3 | Optional · P4 | Files reviewed |',
+        '| :---: | :---: | :---: | :---: |',
+        `| **${count(['P0', 'P1', 'P2'])}** | ${count(['P3'])} | ${count(['P4'])}${assessment.hiddenOptionalCount ? ` (${assessment.hiddenOptionalCount} hidden)` : ''} | ${reviewed} / ${packet.changedFiles.length} |`, '',
+        `**Required validation: ${validation}.**${assessment.validation === 'missing' ? ' Repository tests have not been verified.' : ''}`, '',
+        e(result.summary), '',
+    ];
+    if (assessment.freshness.status !== 'current')
+        lines.push(`**${assessment.freshness.status === 'superseded' ? 'Historical result' : 'Freshness unverified'}:** ${e(assessment.freshness.reason)}`, '');
+    if (assessment.scope !== 'complete')
+        lines.push('**Review incomplete:** unresolved work remains; zero findings is not a clean result.', '');
+    if (assessment.findings.length)
+        lines.push('### Findings', '');
+    for (const f of assessment.findings) {
+        lines.push(`#### ${f.priority} · ${e(f.title)}${f.priority === 'P4' ? ' (optional)' : ''}`, '', sourceLink(packet, f.anchor), '', `- Trigger: ${e(f.trigger)}`, `- Consequence: ${e(f.consequence)}`, `- Suggested change: ${e(f.suggestion)}`, '', '<details><summary>Reasoning and evidence</summary>', '', `- Priority rationale: ${e(f.priorityReason)}`, `- Counterevidence checked: ${e(f.counterEvidence)}`, `- Evidence: ${f.evidenceIds.map(e).join(', ')}`, '', '</details>', '');
+    }
+    if (assessment.hiddenOptionalCount)
+        lines.push(`${assessment.hiddenOptionalCount} optional P4 suggestion(s) hidden by target-branch policy.`, '');
+    lines.push('<details><summary>Validation and review evidence</summary>', '', '### Required validation', '');
+    for (const check of assessment.validationChecks) {
+        lines.push(`- ${e(check.name)}: **${check.status}** — ${e(check.reason)}${check.url ? ` [GitHub check](${check.url})` : ''}`);
+    }
+    lines.push('', '### Evidence', '');
+    if (!result.evidence.length)
+        lines.push('No investigation evidence recorded.');
+    for (const item of result.evidence)
+        lines.push(`- ${e(item.id)} · ${item.kind} · ${item.provenance}: ${e(item.summary)} ${item.anchors.map(a => sourceLink(packet, a)).join(', ')}`);
+    lines.push('', '### Coverage and limitations', '');
+    for (const file of packet.changedFiles) {
+        const coverage = result.coverage.find(c => c.path === file.path);
+        lines.push(`- ${e(file.path)} · ${file.change}/${file.kind} · ${coverage.status}`);
+    }
+    lines.push(...result.limitations.map(reason => `- Limitation: ${e(reason)}`), '', '</details>', '', '<details><summary>Run details</summary>', '', `Repository: ${e(packet.repository)} · PR ${packet.pr}`, `Head: \`${packet.headSha}\` · Target: \`${packet.baseSha}\` · Merge base: \`${packet.mergeBaseSha}\``, `Reviewer: ${e(result.reviewer.name)} · Model: ${e(result.reviewer.model)} · Context: ${result.reviewer.context}`, '', '**Advisory evidence.** Captured source ranges are checked against Git objects. Reasoning and declared test claims are not independently verified. This is not merge approval.', '', ...assessment.reasons.map(reason => `- ${e(reason)}`), '', `Rubric ${packet.policy.rubricVersion} · Policy digest \`${packet.policyHash}\``, `Captured: ${packet.createdAt} · Live check: ${assessment.freshness.checkedAt ?? 'not performed'}`, '', '</details>', '');
+    return lines.join('\n');
+}

package/dist/run.d.ts

@@ -0,0 +1,6 @@
+import { type Model, type Profile } from './investigation.js';
+export declare function readProfile(path: string): Profile;
+export declare function runReview(directory: string, profile: Profile, injectedModel?: Model, signal?: AbortSignal): Promise<{
+    result: import("./contracts.js").Result;
+    receipt: import("./investigation.js").Receipt;
+}>;

package/dist/run.js

@@ -0,0 +1,39 @@
+import { closeSync, existsSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { investigate, parseProfile } from './investigation.js';
+import { openAIModel } from './openai-model.js';
+import { openRouterModel } from './openrouter-model.js';
+import { loadReview } from './snapshot.js';
+export function readProfile(path) {
+    const bytes = readFileSync(path);
+    if (bytes.length > 8000)
+        throw new Error('Profile exceeds 8 KB');
+    return parseProfile(JSON.parse(bytes.toString('utf8')));
+}
+export async function runReview(directory, profile, injectedModel, signal) {
+    // No rerun/resume that can accidentally reset the same run's budget after an uncertain request.
+    const { packet, result } = loadReview(directory);
+    if (result.status !== 'not-started')
+        throw new Error('Investigation already started; prepare a new snapshot for another run');
+    const model = injectedModel ?? (profile.provider === 'openrouter' ? openRouterModel(profile) : openAIModel(profile));
+    const lock = join(directory, 'investigation.lock');
+    const fd = openSync(lock, 'wx', 0o600);
+    closeSync(fd);
+    const persist = (name, value) => {
+        const temporary = join(directory, `${name}.pending`);
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx', flush: true });
+        renameSync(temporary, join(directory, name));
+    };
+    try {
+        if (existsSync(join(directory, 'receipt.json')) || loadReview(directory).result.status !== 'not-started') {
+            throw new Error('Run has existing investigation or spending evidence; prepare a new snapshot');
+        }
+        return await investigate(directory, packet, profile, model, (result, receipt) => {
+            persist('receipt.json', receipt);
+            persist('result.json', result);
+        }, signal);
+    }
+    finally {
+        unlinkSync(lock);
+    }
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,46 @@
+import { type EvidenceAnchor, type Packet } from './contracts.js';
+import { type Freshness } from './assessment.js';
+export declare const withGitDeadline: <T>(deadlineMs: number, operation: () => T) => T;
+export declare const hash: (value: string | Uint8Array) => string;
+export interface PullState {
+    repository: string;
+    pr: number;
+    headSha: string;
+    baseSha: string;
+    baseRef: string;
+    state: 'open' | 'closed';
+}
+export declare function git(repository: string, args: string[]): Buffer;
+export declare function parsePullUrl(input: string): {
+    repository: string;
+    pr: number;
+};
+type Request = (endpoint: string) => unknown;
+export declare function readPull(repository: string, pr: number, request?: Request): PullState;
+export declare function compareCurrent(packet: Packet, current: PullState): Freshness;
+export declare function checkCurrent(packet: Packet): Freshness;
+export declare function capture(repository: string, identity: PullState): {
+    packet: Packet;
+    diff: Buffer;
+};
+export declare function prepare(url: string, output?: string): {
+    directory: string;
+    packet: Packet;
+};
+export declare function validateAnchor(repository: string, packet: Packet, anchor: EvidenceAnchor): void;
+export declare function sourceText(repository: string, revision: string, path: string): string | null;
+export declare function sourcePaths(repository: string, revision: string): string[];
+export declare function sourceSlice(repository: string, revision: string, path: string, startLine: number, count: number): {
+    text: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    contentHash: string;
+    revision: string;
+};
+export declare function validateCapturedEvidence(repository: string, packet: Packet, item: import('./contracts.js').Evidence): void;
+export declare function loadReview(directory: string): {
+    packet: Packet;
+    result: import("./contracts.js").Result;
+};
+export {};

package/dist/snapshot.js

@@ -0,0 +1,246 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ReviewInputError, defaultPolicy, initialResult, parsePacket, parsePolicy, parseResult } from './contracts.js';
+import { validateEvidence } from './assessment.js';
+const MAX_BYTES = 16 * 1024 * 1024;
+const commandDeadline = new AsyncLocalStorage();
+export const withGitDeadline = (deadlineMs, operation) => commandDeadline.run(Date.now() + deadlineMs, operation);
+const shaPattern = /^[a-f0-9]{40}$/;
+const decode = (bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+export const hash = (value) => createHash('sha256').update(value).digest('hex');
+function requireValue(condition, message) {
+    if (!condition)
+        throw new ReviewInputError(message);
+}
+// Do not inherit GIT_CONFIG_COUNT, GIT_DIR, replace objects, SSH overrides,
+// NODE_OPTIONS, loaders or arbitrary Git config from the caller or checkout.
+function commandEnv() {
+    const env = {};
+    for (const key of ['PATH', 'HOME', 'TMPDIR', 'SYSTEMROOT', 'GH_TOKEN', 'GITHUB_TOKEN', 'GH_CONFIG_DIR']) {
+        if (process.env[key] !== undefined)
+            env[key] = process.env[key];
+    }
+    return { ...env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_ATTR_NOSYSTEM: '1',
+        GIT_LITERAL_PATHSPECS: '1', GH_PROMPT_DISABLED: '1', GH_HOST: 'github.com' };
+}
+function command(program, args, cwd, operation = args[0] ?? '') {
+    const timeout = Math.min(120000, (commandDeadline.getStore() ?? (Date.now() + 120000)) - Date.now());
+    requireValue(timeout > 0, 'Review deadline reached');
+    try {
+        return execFileSync(program, args, { ...(cwd ? { cwd } : {}), env: commandEnv(), maxBuffer: MAX_BYTES, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch {
+        // Child-process exceptions include arguments/output. Do not echo private data.
+        throw new Error(`${program} ${operation} failed or exceeded its time/output limit. Check access and the requested revision.`);
+    }
+}
+export function git(repository, args) {
+    return command('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false',
+        '-c', 'core.attributesFile=/dev/null', '-c', 'credential.helper=',
+        '-c', 'credential.https://github.com.helper=!gh auth git-credential',
+        '-c', 'protocol.file.allow=never', '-c', 'protocol.ext.allow=never',
+        '-c', 'protocol.ssh.allow=never', '-C', repository, ...args], undefined, args[0]);
+}
+function gitText(repository, args) { return decode(git(repository, args)); }
+export function parsePullUrl(input) {
+    const url = new URL(input);
+    requireValue(url.protocol === 'https:' && url.hostname === 'github.com' && !url.port && !url.username && !url.password && !url.search && !url.hash, 'Use an HTTPS github.com pull request URL without credentials, query or fragment');
+    const match = /^\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/pull\/([1-9]\d*)\/?$/.exec(url.pathname);
+    requireValue(match && !['.', '..'].includes(match[1]) && !['.', '..'].includes(match[2]), 'Invalid GitHub pull request URL');
+    const pr = Number(match[3]);
+    requireValue(Number.isSafeInteger(pr), 'Invalid PR number');
+    return { repository: `${match[1]}/${match[2]}`, pr };
+}
+const api = endpoint => JSON.parse(decode(command('gh', ['api', '--hostname', 'github.com', endpoint])));
+function record(value) {
+    requireValue(value !== null && typeof value === 'object' && !Array.isArray(value), 'Unexpected GitHub response');
+    return value;
+}
+export function readPull(repository, pr, request = api) {
+    // Validate identity before constructing API paths, including callers other than the CLI.
+    parsePullUrl(`https://github.com/${repository}/pull/${pr}`);
+    const pull = record(request(`repos/${repository}/pulls/${pr}`));
+    const base = record(pull.base);
+    const head = record(pull.head);
+    const baseRepo = record(base.repo);
+    requireValue(pull.number === pr && typeof baseRepo.full_name === 'string' && baseRepo.full_name.toLowerCase() === repository.toLowerCase(), 'GitHub PR identity changed');
+    requireValue(typeof base.ref === 'string' && base.ref.length > 0, 'Missing target branch');
+    // The PR object's base.sha may lag the actual target branch.
+    const ref = record(request(`repos/${repository}/git/ref/heads/${encodeURIComponent(base.ref)}`));
+    const object = record(ref.object);
+    requireValue(object.type === 'commit' && typeof object.sha === 'string' && shaPattern.test(object.sha), 'Cannot resolve current target commit');
+    requireValue(typeof head.sha === 'string' && shaPattern.test(head.sha), 'Cannot resolve PR head');
+    requireValue(pull.state === 'open' || pull.state === 'closed', 'Unknown PR state');
+    return { repository: baseRepo.full_name, pr, headSha: head.sha, baseSha: object.sha, baseRef: base.ref, state: pull.state };
+}
+export function compareCurrent(packet, current) {
+    const same = current.state === 'open' && current.repository.toLowerCase() === packet.repository.toLowerCase()
+        && current.pr === packet.pr && current.headSha === packet.headSha && current.baseSha === packet.baseSha && current.baseRef === packet.baseRef;
+    return { status: same ? 'current' : 'superseded', checkedAt: new Date().toISOString(),
+        reason: same ? 'Head and current target matched at the recorded check time; later pushes invalidate this result.'
+            : 'The PR closed, was retargeted, or its head/current target changed. This report applies only to the captured snapshot.' };
+}
+export function checkCurrent(packet) {
+    try {
+        return compareCurrent(packet, readPull(packet.repository, packet.pr));
+    }
+    catch {
+        return { status: 'unverified', checkedAt: new Date().toISOString(), reason: 'Live PR state could not be verified. No current-review conclusion is available.' };
+    }
+}
+function fileAt(repository, revision, path) {
+    requireValue(shaPattern.test(revision), 'Invalid immutable revision');
+    const entry = gitText(repository, ['ls-tree', '-z', '--full-tree', revision, '--', path]);
+    if (!entry)
+        return null;
+    const match = /^([0-7]{6}) (blob|commit) ([a-f0-9]{40})\t([\s\S]+)\0$/.exec(entry);
+    requireValue(match && match[4] === path, 'Expected one exact file object');
+    if (match[1] === '160000')
+        return { mode: match[1], bytes: Buffer.alloc(0) };
+    const size = Number(gitText(repository, ['cat-file', '-s', match[3]]).trim());
+    requireValue(Number.isSafeInteger(size) && size <= MAX_BYTES, 'File exceeds the 16 MiB capture limit; snapshot is unavailable');
+    return { mode: match[1], bytes: git(repository, ['cat-file', 'blob', match[3]]) };
+}
+function fileKind(file) {
+    if (file.mode === '120000')
+        return 'symlink';
+    if (file.mode === '160000')
+        return 'submodule';
+    if (file.bytes.includes(0))
+        return 'binary';
+    try {
+        decode(file.bytes);
+    }
+    catch {
+        return 'binary';
+    }
+    return 'text';
+}
+export function capture(repository, identity) {
+    requireValue(shaPattern.test(identity.headSha) && shaPattern.test(identity.baseSha), 'Invalid capture revisions');
+    const mergeBaseSha = gitText(repository, ['merge-base', identity.baseSha, identity.headSha]).trim();
+    requireValue(shaPattern.test(mergeBaseSha), 'No valid common ancestor; capture unavailable');
+    const inventory = gitText(repository, ['diff', '--no-ext-diff', '--no-textconv', '--no-renames', '--name-status', '-z', mergeBaseSha, identity.headSha, '--']).split('\0');
+    requireValue(inventory.pop() === '', 'Incomplete diff inventory');
+    requireValue(inventory.length % 2 === 0 && inventory.length <= 2000, 'Invalid inventory or more than 1000 changed paths');
+    const changedFiles = [];
+    for (let i = 0; i < inventory.length; i += 2) {
+        const status = inventory[i];
+        const path = inventory[i + 1];
+        requireValue(['A', 'M', 'D', 'T'].includes(status), 'Unsupported change type');
+        const before = fileAt(repository, mergeBaseSha, path);
+        const after = fileAt(repository, identity.headSha, path);
+        requireValue(before || after, 'Changed path has no captured object');
+        const kinds = [before, after].filter((v) => v !== null).map(fileKind);
+        const kind = kinds.find(k => k !== 'text') ?? 'text';
+        changedFiles.push({ path, change: status === 'A' ? 'added' : status === 'D' ? 'deleted' : 'modified', kind });
+    }
+    const policyObject = fileAt(repository, identity.baseSha, '.atmin/review.json');
+    requireValue(!policyObject || policyObject.mode === '100644' || policyObject.mode === '100755', 'Review policy must be a regular file');
+    const policy = policyObject ? parsePolicy(JSON.parse(decode(policyObject.bytes))) : defaultPolicy();
+    const diff = git(repository, ['diff', '--no-ext-diff', '--no-textconv', '--no-renames', mergeBaseSha, identity.headSha, '--']);
+    // Keep the actual diff bytes: non-UTF8 source can still be captured but never marked text-reviewed.
+    const packet = parsePacket({ schemaVersion: 1, repository: identity.repository, pr: identity.pr,
+        baseRef: identity.baseRef, headSha: identity.headSha, baseSha: identity.baseSha, mergeBaseSha,
+        createdAt: new Date().toISOString(), policy, policyHash: hash(JSON.stringify(policy)), diffHash: hash(diff), changedFiles });
+    return { packet, diff };
+}
+function saveJson(path, data) {
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+}
+export function prepare(url, output) {
+    const parsed = parsePullUrl(url);
+    const current = readPull(parsed.repository, parsed.pr);
+    requireValue(current.state === 'open', 'Only open pull requests can be prepared');
+    const directory = output ? resolve(output) : mkdtempSync(join(tmpdir(), 'atmin-review-'));
+    if (output)
+        mkdirSync(directory, { mode: 0o700 }); // Never overwrite an existing packet/workspace.
+    const source = join(directory, 'source.git');
+    mkdirSync(source, { mode: 0o700 });
+    git(source, ['init', '--bare', '--template=']);
+    git(source, ['remote', 'add', 'origin', `https://github.com/${current.repository}.git`]);
+    // Investigation has no GitHub credential. Capture all objects now so reading
+    // unchanged guidance and callers cannot trigger an authenticated lazy fetch.
+    git(source, ['fetch', '--no-tags', 'origin', current.headSha, current.baseSha]);
+    const { packet, diff } = capture(source, current);
+    requireValue(compareCurrent(packet, readPull(current.repository, current.pr)).status === 'current', 'PR changed during capture; prepare a new snapshot');
+    writeFileSync(join(directory, 'change.diff'), diff, { mode: 0o600, flag: 'wx' });
+    saveJson(join(directory, 'packet.json'), packet);
+    saveJson(join(directory, 'result.json'), initialResult(packet));
+    return { directory, packet };
+}
+function jsonFile(path) {
+    const bytes = readFileSync(path);
+    requireValue(bytes.length <= MAX_BYTES, 'Review JSON exceeds the 16 MiB limit');
+    return JSON.parse(decode(bytes));
+}
+export function validateAnchor(repository, packet, anchor) {
+    const revision = anchor.side === 'head' ? packet.headSha : packet.mergeBaseSha;
+    const file = fileAt(repository, revision, anchor.path);
+    requireValue(file && fileKind(file) === 'text', 'Anchor does not reference a regular UTF-8 text file');
+    if (anchor.line === null)
+        return;
+    const content = decode(file.bytes);
+    const lineCount = content.length === 0 ? 0 : content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+    requireValue(anchor.line <= lineCount, 'Anchor line is outside its immutable source file');
+}
+// Source tools expose only immutable Git text, never host files or repository commands.
+export function sourceText(repository, revision, path) {
+    const file = fileAt(repository, revision, path);
+    if (!file)
+        return null;
+    requireValue(fileKind(file) === 'text', 'Only regular UTF-8 text can be read');
+    return decode(file.bytes);
+}
+export function sourcePaths(repository, revision) {
+    requireValue(shaPattern.test(revision), 'Invalid immutable revision');
+    const output = gitText(repository, ['ls-tree', '-r', '--name-only', '-z', revision]);
+    return output ? output.slice(0, -1).split('\0') : [];
+}
+export function sourceSlice(repository, revision, path, startLine, count) {
+    requireValue(Number.isSafeInteger(startLine) && startLine >= 1 && Number.isSafeInteger(count) && count >= 1 && count <= 200, 'Read requires a positive line and 1–200 lines');
+    const content = sourceText(repository, revision, path);
+    requireValue(content !== null, 'Path does not exist at this snapshot');
+    const lines = content === '' ? [] : content.split('\n');
+    if (content.endsWith('\n'))
+        lines.pop();
+    requireValue(startLine <= Math.max(1, lines.length), 'Start line is outside source');
+    const selected = lines.slice(startLine - 1, startLine - 1 + count);
+    const text = selected.join('\n');
+    requireValue(Buffer.byteLength(text) <= 24000, 'Source range exceeds 24 KB; request fewer lines');
+    return { text, startLine, endLine: startLine - 1 + selected.length, totalLines: lines.length, contentHash: hash(text), revision };
+}
+export function validateCapturedEvidence(repository, packet, item) {
+    if (item.provenance !== 'controller-captured')
+        return;
+    const anchor = item.anchors[0];
+    const revision = anchor.side === 'head' ? packet.headSha : packet.mergeBaseSha;
+    const actual = sourceSlice(repository, revision, anchor.path, item.capture.startLine, Math.max(1, item.capture.endLine - item.capture.startLine + 1));
+    const { text: _text, ...capture } = actual;
+    requireValue(isDeepStrictEqual(capture, item.capture) && anchor.line === (capture.totalLines ? capture.startLine : null), 'Captured source evidence does not match its immutable range and digest');
+}
+export function loadReview(directory) {
+    const packet = parsePacket(jsonFile(join(directory, 'packet.json')));
+    const result = parseResult(jsonFile(join(directory, 'result.json')));
+    const repository = join(directory, 'source.git');
+    const actual = capture(repository, { ...packet, state: 'open' }).packet;
+    const { createdAt: _recordedTime, ...recorded } = packet;
+    const { createdAt: _recomputedTime, ...recomputed } = actual;
+    requireValue(isDeepStrictEqual(recorded, recomputed), 'Packet differs from immutable Git inventory, diff or target-branch policy');
+    requireValue(hash(readFileSync(join(directory, 'change.diff'))) === packet.diffHash, 'Saved diff differs from its captured digest');
+    validateEvidence(packet, result);
+    for (const finding of result.findings)
+        validateAnchor(repository, packet, finding.anchor);
+    for (const item of result.evidence)
+        for (const anchor of item.anchors)
+            validateAnchor(repository, packet, anchor);
+    for (const item of result.evidence)
+        validateCapturedEvidence(repository, packet, item);
+    return { packet, result };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@atmin.ai/review",
+  "version": "0.1.0-alpha.2",
+  "private": false,
+  "type": "module",
+  "description": "atmin review — immutable review evidence and deterministic verdicts",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "atmin-review": "dist/cli.js",
+    "atmin-review-github": "dist/github/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "openai": "7.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3"
+  },
+  "files": [
+    "dist",
+    "profiles",
+    "LICENSE",
+    "NOTICE",
+    "DEPENDENCIES.md"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atmin-ca/review.git"
+  },
+  "bugs": {
+    "url": "https://github.com/atmin-ca/review/issues"
+  },
+  "homepage": "https://github.com/atmin-ca/review#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}

package/profiles/baseline-deepseek.json

@@ -0,0 +1,10 @@
+{
+  "provider": "openrouter",
+  "model": "deepseek/deepseek-v3.2",
+  "maxUsd": 2,
+  "maxTurns": 24,
+  "maxToolCalls": 80,
+  "maxInputTokens": 100000,
+  "maxOutputTokens": 8192,
+  "deadlineMs": 600000
+}

package/profiles/smoke-openai.json

@@ -0,0 +1,10 @@
+{
+  "provider": "openai",
+  "model": "gpt-5.4-2026-03-05",
+  "maxUsd": 2,
+  "maxTurns": 30,
+  "maxToolCalls": 60,
+  "maxInputTokens": 50000,
+  "maxOutputTokens": 4096,
+  "deadlineMs": 600000
+}

package/profiles/smoke-openrouter-free.json

@@ -0,0 +1,10 @@
+{
+  "provider": "openrouter",
+  "model": "cohere/north-mini-code:free",
+  "maxUsd": 0,
+  "maxTurns": 8,
+  "maxToolCalls": 40,
+  "maxInputTokens": 80000,
+  "maxOutputTokens": 4096,
+  "deadlineMs": 600000
+}