@fitlab-ai/agent-infra 0.9.2 → 0.9.4

package/lib/process-data/sources.ts

@@ -0,0 +1,354 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createGitHubClient } from '../platform/github-client.ts';
+import { enumerateAllTaskDirs } from '../task/resolve-ref.ts';
+import { captureText, inspectPrivacy, redactExcerpt } from './privacy.ts';
+import { canonicalJsonBytes, sha256 } from './store.ts';
+
+import type { GitHubClient } from '../platform/github-client.ts';
+import type {
+  CapturedObject,
+  ProcessResult,
+  RestCollectionEvidence,
+  RestPageEvidence
+} from './types.ts';
+
+type RestPage = { evidence: RestPageEvidence; bytes: Buffer };
+type RestCollection<T> = { items: T[]; evidence: RestCollectionEvidence; pageObjects: CapturedObject[] };
+
+type FetchRestCollectionOptions<T> = {
+  client: GitHubClient;
+  endpoint: string;
+  identify: (item: T) => string;
+  select?: (item: T) => T;
+  perPage?: number;
+};
+
+type GitHubCapture = {
+  repository: string;
+  objects: CapturedObject[];
+  endpoints: RestCollectionEvidence[];
+};
+
+function endpointForPage(endpoint: string, page: number, perPage: number): string {
+  const parsed = new URL(endpoint, 'https://api.github.invalid/');
+  if (parsed.searchParams.has('page') || parsed.searchParams.has('per_page')) {
+    throw new Error('endpoint must not predefine page or per_page');
+  }
+  parsed.searchParams.set('per_page', String(perPage));
+  parsed.searchParams.set('page', String(page));
+  return `${parsed.pathname.replace(/^\//, '')}${parsed.search}`;
+}
+
+function fetchRestCollection<T>(options: FetchRestCollectionOptions<T>): ProcessResult<RestCollection<T>> {
+  const perPage = options.perPage ?? 100;
+  if (!Number.isInteger(perPage) || perPage < 1 || perPage > 100) {
+    return { ok: false, error: { code: 'PAGINATION_INVALID', message: 'perPage must be between 1 and 100' } };
+  }
+  let pageIndex = 1;
+  let previousHash: string | null = null;
+  const identities = new Set<string>();
+  const items: T[] = [];
+  const pages: RestPage[] = [];
+
+  while (true) {
+    let url: string;
+    try {
+      url = endpointForPage(options.endpoint, pageIndex, perPage);
+    } catch (error) {
+      return { ok: false, error: { code: 'PAGINATION_INVALID', message: String(error) } };
+    }
+    const response = options.client.json<unknown>(['api', url]);
+    if (!response.ok) return { ok: false, error: response.error };
+    if (!Array.isArray(response.value) || response.value.length > perPage) {
+      return {
+        ok: false,
+        error: { code: 'INVALID_PLATFORM_RESPONSE', message: `GitHub page ${pageIndex} is not a valid array page` }
+      };
+    }
+    let selected: T[];
+    try {
+      selected = (response.value as T[]).map((entry) => options.select ? options.select(entry) : entry);
+    } catch (error) {
+      return { ok: false, error: { code: 'INVALID_PLATFORM_RESPONSE', message: String(error) } };
+    }
+    let bytes: Buffer;
+    try {
+      bytes = canonicalJsonBytes(selected);
+    } catch (error) {
+      return { ok: false, error: { code: 'INVALID_PLATFORM_RESPONSE', message: String(error) } };
+    }
+    const canonicalSha256 = sha256(bytes);
+    if (previousHash === canonicalSha256 && response.value.length > 0) {
+      return {
+        ok: false,
+        error: { code: 'PAGINATION_UNSTABLE', message: `GitHub page ${pageIndex} repeats the previous page` }
+      };
+    }
+    for (const entry of selected) {
+      const identity = options.identify(entry);
+      if (!identity || identities.has(identity)) {
+        return {
+          ok: false,
+          error: { code: 'PAGINATION_UNSTABLE', message: `duplicate or empty identity on page ${pageIndex}` }
+        };
+      }
+      identities.add(identity);
+      items.push(entry);
+    }
+    pages.push({ evidence: { index: pageIndex, itemCount: response.value.length, canonicalSha256 }, bytes });
+    previousHash = canonicalSha256;
+    if (response.value.length < perPage) break;
+    pageIndex += 1;
+  }
+
+  const evidence: RestCollectionEvidence = {
+    endpoint: options.endpoint,
+    requestCount: pages.length,
+    dataPageCount: pages.filter((page) => page.evidence.itemCount > 0).length,
+    itemCount: items.length,
+    termination: 'short-page',
+    pages: pages.map((page) => page.evidence)
+  };
+  return {
+    ok: true,
+    value: {
+      items,
+      evidence,
+      pageObjects: pages.map((page) => ({
+        sourceKind: 'github-rest',
+        sourceIdentity: `${options.endpoint}#page=${page.evidence.index}`,
+        sha256: page.evidence.canonicalSha256,
+        bytes: page.bytes.length,
+        content: page.bytes.toString('utf8'),
+        disposition: { state: 'included' }
+      }))
+    }
+  };
+}
+
+function relativeIdentity(repoRoot: string, filePath: string): string {
+  const relative = path.relative(repoRoot, filePath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`path escapes repository: ${filePath}`);
+  return relative.split(path.sep).join('/');
+}
+
+function readStableFile(repoRoot: string, filePath: string, sourceKind: CapturedObject['sourceKind']): CapturedObject {
+  const before = fs.lstatSync(filePath);
+  if (!before.isFile() || before.isSymbolicLink()) throw new Error(`unsafe source file: ${filePath}`);
+  const content = fs.readFileSync(filePath, 'utf8');
+  const after = fs.lstatSync(filePath);
+  if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+    throw new Error(`source changed while reading: ${filePath}`);
+  }
+  return captureText(sourceKind, relativeIdentity(repoRoot, filePath), content);
+}
+
+function listFiles(directory: string): string[] {
+  if (!fs.existsSync(directory)) return [];
+  const output: string[] = [];
+  const walk = (current: string) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`symlink source is not allowed: ${candidate}`);
+      if (entry.isDirectory()) walk(candidate);
+      else if (entry.isFile()) output.push(candidate);
+    }
+  };
+  walk(directory);
+  return output;
+}
+
+function structuredReceipt(repoRoot: string, filePath: string): CapturedObject {
+  const raw = readStableFile(repoRoot, filePath, 'structured-telemetry');
+  if (!raw.content) return raw;
+  try {
+    const parsed = JSON.parse(raw.content) as Record<string, unknown>;
+    const fields = ['client', 'model', 'reasoning', 'stage', 'toolCategory', 'time', 'status', 'retry', 'error', 'fallback'];
+    const selected = Object.fromEntries(
+      fields.filter((field) => parsed[field] !== undefined).map((field) => [field, jsonClone(parsed[field])])
+    );
+    selected.sourceSha256 = raw.sha256;
+    return captureText('structured-telemetry', raw.sourceIdentity, canonicalJsonBytes(selected).toString('utf8'));
+  } catch {
+    return { ...raw, content: undefined, disposition: { state: 'unavailable', reason: 'invalid receipt JSON' } };
+  }
+}
+
+function unavailableLog(repoRoot: string, filePath: string, includeExcerpts: boolean): CapturedObject {
+  const raw = readStableFile(repoRoot, filePath, 'local-file');
+  if (raw.disposition?.state === 'excluded-sensitive') return raw;
+  const recognizedBody = /\/(?:sessions?|tools?)(?:\/|[-_])/i.test(raw.sourceIdentity);
+  if (includeExcerpts && recognizedBody && raw.content) {
+    const excerpt = redactExcerpt(raw.content);
+    if (excerpt !== null) return captureText('local-file', `${raw.sourceIdentity}#excerpt`, excerpt);
+  }
+  return {
+    sourceKind: 'local-file',
+    sourceIdentity: raw.sourceIdentity,
+    sha256: raw.sha256,
+    bytes: raw.bytes,
+    disposition: { state: 'unavailable', reason: recognizedBody ? 'body-excerpts-disabled' : 'unknown-log-format' }
+  };
+}
+
+function collectLocalObjects(repoRoot: string, options: { includeExcerpts?: boolean } = {}): ProcessResult<CapturedObject[]> {
+  try {
+    const objects: CapturedObject[] = [];
+    for (const task of enumerateAllTaskDirs(repoRoot)) {
+      for (const filePath of listFiles(task.taskDir)) {
+        if (!/\.(?:md|json)$/i.test(filePath)) continue;
+        objects.push(readStableFile(repoRoot, filePath, 'local-file'));
+      }
+    }
+    const logsRoot = path.join(repoRoot, '.agents', 'workspace', 'logs');
+    for (const filePath of listFiles(logsRoot)) {
+      if (!/\.(?:md|json)$/i.test(filePath)) continue;
+      const identity = relativeIdentity(repoRoot, filePath);
+      if (/\/entropy-check\/.*\.md$/i.test(identity)) {
+        objects.push(readStableFile(repoRoot, filePath, 'operational-report'));
+      } else if (/\/(?:delegation|orchestration)(?:\/|[-_]).*\.json$/i.test(identity)) {
+        objects.push(structuredReceipt(repoRoot, filePath));
+      } else {
+        objects.push(unavailableLog(repoRoot, filePath, options.includeExcerpts === true));
+      }
+    }
+    return { ok: true, value: objects.sort((a, b) => a.sourceIdentity.localeCompare(b.sourceIdentity)) };
+  } catch (error) {
+    return { ok: false, error: { code: 'LOCAL_SOURCE_UNSTABLE', message: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+function githubIdentity(item: unknown): string {
+  if (!item || typeof item !== 'object') return '';
+  const record = item as Record<string, unknown>;
+  for (const key of ['id', 'node_id', 'sha', 'number']) {
+    if (typeof record[key] === 'string' || typeof record[key] === 'number') return `${key}:${String(record[key])}`;
+  }
+  return '';
+}
+
+function jsonClone(value: unknown): unknown {
+  return JSON.parse(JSON.stringify(value)) as unknown;
+}
+
+function projectFields(value: unknown, fields: string[]): Record<string, unknown> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  return Object.fromEntries(
+    fields.filter((field) => record[field] !== undefined).map((field) => [field, jsonClone(record[field])])
+  );
+}
+
+function projectSensitiveText(value: unknown): unknown {
+  if (typeof value !== 'string') return undefined;
+  const disposition = inspectPrivacy(value);
+  return disposition.state === 'included'
+    ? value
+    : { state: 'unavailable', reason: 'privacy-excluded', ruleId: disposition.ruleId, sha256: sha256(value) };
+}
+
+function projectGitHubItem(item: unknown): unknown {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error('GitHub item must be an object');
+  const source = item as Record<string, unknown>;
+  const output: Record<string, unknown> = {};
+  const scalarFields = [
+    'id', 'node_id', 'number', 'html_url', 'url', 'state', 'title', 'created_at', 'updated_at', 'closed_at',
+    'merged_at', 'review_state', 'commit_id', 'sha', 'merge_commit_sha', 'milestone'
+  ];
+  for (const field of scalarFields) {
+    if (source[field] !== undefined) output[field] = jsonClone(source[field]);
+  }
+  for (const field of ['user', 'head', 'base', 'author', 'committer']) {
+    const projected = projectFields(source[field], ['id', 'login', 'sha', 'ref']);
+    if (projected) output[field] = projected;
+  }
+  for (const field of ['labels', 'assignees']) {
+    if (Array.isArray(source[field])) output[field] = jsonClone(source[field]);
+  }
+  for (const field of ['body', 'message']) {
+    const projected = projectSensitiveText(source[field]);
+    if (projected !== undefined) output[field] = projected;
+  }
+  if (Array.isArray(source.parents)) {
+    output.parents = source.parents.flatMap((parent) => {
+      const projected = projectFields(parent, ['sha']);
+      return projected ? [projected] : [];
+    });
+  }
+  const commit = projectFields(source.commit, []);
+  if (commit) {
+    const sourceCommit = source.commit as Record<string, unknown>;
+    const projectedCommit: Record<string, unknown> = {};
+    const message = projectSensitiveText(sourceCommit.message);
+    if (message !== undefined) projectedCommit.message = message;
+    const tree = projectFields(sourceCommit.tree, ['sha']);
+    if (tree) projectedCommit.tree = tree;
+    for (const field of ['author', 'committer']) {
+      const actor = projectFields(sourceCommit[field], ['name', 'email', 'date']);
+      if (actor) projectedCommit[field] = actor;
+    }
+    output.commit = projectedCommit;
+  }
+  return output;
+}
+
+function collectGitHubObjects(repoRoot: string, client: GitHubClient = createGitHubClient()): ProcessResult<GitHubCapture> {
+  const repoResult = client.json<{ nameWithOwner?: string }>(['repo', 'view', '--json', 'nameWithOwner'], { cwd: repoRoot });
+  if (!repoResult.ok) return { ok: false, error: repoResult.error };
+  const repository = repoResult.value.nameWithOwner;
+  if (!repository || !/^[^/]+\/[^/]+$/.test(repository)) {
+    return { ok: false, error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub repository identity is missing' } };
+  }
+  const objects: CapturedObject[] = [];
+  const evidence: RestCollectionEvidence[] = [];
+  const captureEndpoint = (endpoint: string) => {
+    const result = fetchRestCollection({
+      client,
+      endpoint,
+      identify: githubIdentity,
+      select: (item) => projectGitHubItem(item) as unknown
+    });
+    if (!result.ok) return result;
+    objects.push(...result.value.pageObjects);
+    evidence.push(result.value.evidence);
+    return result;
+  };
+
+  const issues = captureEndpoint(`repos/${repository}/issues?state=all&sort=created&direction=asc`);
+  if (!issues.ok) return issues;
+  const pulls = captureEndpoint(`repos/${repository}/pulls?state=all&sort=created&direction=asc`);
+  if (!pulls.ok) return pulls;
+
+  for (const issue of issues.value.items) {
+    const number = (issue as Record<string, unknown>).number;
+    if (typeof number !== 'number') return { ok: false, error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'Issue number is missing' } };
+    const comments = captureEndpoint(`repos/${repository}/issues/${number}/comments`);
+    if (!comments.ok) return comments;
+  }
+  for (const pull of pulls.value.items) {
+    const record = pull as Record<string, unknown>;
+    const number = record.number;
+    const head = record.head as Record<string, unknown> | undefined;
+    const headSha = head?.sha;
+    if (typeof number !== 'number' || typeof headSha !== 'string') {
+      return { ok: false, error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'Pull request identity or head SHA is missing' } };
+    }
+    for (const suffix of ['comments', 'reviews', 'commits']) {
+      const nested = captureEndpoint(`repos/${repository}/pulls/${number}/${suffix}`);
+      if (!nested.ok) return nested;
+    }
+    const current = client.json<unknown>(['api', `repos/${repository}/pulls/${number}`]);
+    if (!current.ok) return { ok: false, error: current.error };
+    const projected = projectGitHubItem(current.value) as Record<string, unknown>;
+    const currentHead = projected.head as Record<string, unknown> | undefined;
+    if (currentHead?.sha !== headSha) {
+      return { ok: false, error: { code: 'SOURCE_DRIFT', message: `Pull request ${number} head changed during capture` } };
+    }
+  }
+  return { ok: true, value: { repository, objects, endpoints: evidence } };
+}
+
+export { collectGitHubObjects, collectLocalObjects, fetchRestCollection, projectGitHubItem };
+export type { FetchRestCollectionOptions, GitHubCapture, RestCollection };

package/lib/process-data/store.ts

@@ -0,0 +1,315 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type {
+  JsonValue,
+  NormalizedRecord,
+  QualityFinding,
+  RepairAction,
+  RestCollectionEvidence,
+  SnapshotManifest,
+  StoredObjectEvidence
+} from './types.ts';
+
+type ObjectWrite = { sha256: string; path: string; created: boolean };
+type ObjectStore = { put(bytes: Buffer): ObjectWrite; pathFor(sha256: string): string };
+
+type PublishInput = {
+  scope: 'all' | 'local' | 'github';
+  repository: string;
+  observedFrom: string;
+  observedTo: string;
+  objects: StoredObjectEvidence[];
+  endpoints: RestCollectionEvidence[];
+  excerptsEnabled: boolean;
+  records: NormalizedRecord[];
+  quality: QualityFinding[];
+  repairs: RepairAction[];
+};
+
+type VerificationResult = {
+  ok: boolean;
+  snapshotId: string;
+  snapshotPath: string | null;
+  errors: string[];
+  manifest?: SnapshotManifest;
+};
+
+function sha256(bytes: Buffer | string): string {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function compareCodePoints(left: string, right: string): number {
+  const a = Array.from(left, (char) => char.codePointAt(0)!);
+  const b = Array.from(right, (char) => char.codePointAt(0)!);
+  for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+    if (a[index] !== b[index]) return a[index]! - b[index]!;
+  }
+  return a.length - b.length;
+}
+
+function canonicalString(value: unknown, seen: Set<object>): string {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('canonical JSON accepts only finite JSON values');
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error('canonical JSON accepts only acyclic JSON values');
+    seen.add(value);
+    const output = `[${value.map((entry) => canonicalString(entry, seen)).join(',')}]`;
+    seen.delete(value);
+    return output;
+  }
+  if (typeof value === 'object') {
+    if (seen.has(value)) throw new Error('canonical JSON accepts only acyclic JSON values');
+    seen.add(value);
+    const record = value as Record<string, unknown>;
+    const fields = Object.keys(record)
+      .sort(compareCodePoints)
+      .map((key) => `${JSON.stringify(key)}:${canonicalString(record[key], seen)}`);
+    seen.delete(value);
+    return `{${fields.join(',')}}`;
+  }
+  throw new Error('canonical JSON accepts only JSON values');
+}
+
+function canonicalJsonBytes(value: JsonValue | unknown): Buffer {
+  return Buffer.from(canonicalString(value, new Set()), 'utf8');
+}
+
+function ensurePrivateDirectory(directory: string): void {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') fs.chmodSync(directory, 0o700);
+}
+
+function writeExclusive(filePath: string, bytes: Buffer): boolean {
+  ensurePrivateDirectory(path.dirname(filePath));
+  try {
+    const fd = fs.openSync(filePath, 'wx', 0o600);
+    try {
+      fs.writeFileSync(fd, bytes);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    return false;
+  }
+}
+
+function createObjectStore(root: string): ObjectStore {
+  const objectRoot = path.join(root, 'objects', 'sha256');
+  ensurePrivateDirectory(objectRoot);
+  return {
+    pathFor(digest: string) {
+      if (!/^[a-f0-9]{64}$/.test(digest)) throw new Error(`invalid SHA-256: ${digest}`);
+      return path.join(objectRoot, digest.slice(0, 2), digest);
+    },
+    put(bytes: Buffer) {
+      const digest = sha256(bytes);
+      const objectPath = path.join(objectRoot, digest.slice(0, 2), digest);
+      const created = writeExclusive(objectPath, bytes);
+      const stored = fs.readFileSync(objectPath);
+      if (sha256(stored) !== digest) throw new Error(`CAS hash mismatch for ${digest}`);
+      return { sha256: digest, path: objectPath, created };
+    }
+  };
+}
+
+function dispositionCounts(objects: StoredObjectEvidence[]): SnapshotManifest['dispositionCounts'] {
+  const counts: SnapshotManifest['dispositionCounts'] = { included: 0, 'excluded-sensitive': 0, unavailable: 0 };
+  for (const object of objects) counts[object.disposition?.state ?? 'included'] += 1;
+  return counts;
+}
+
+function jsonLine(value: JsonValue | unknown): string {
+  return `${canonicalJsonBytes(value).toString('utf8')}\n`;
+}
+
+function writePrivateFile(filePath: string, content: string | Buffer): void {
+  fs.writeFileSync(filePath, content, { mode: 0o600, flag: 'wx' });
+  if (process.platform !== 'win32') fs.chmodSync(filePath, 0o600);
+}
+
+function manifestDigest(manifest: Omit<SnapshotManifest, 'manifestSha256'>): string {
+  return sha256(canonicalJsonBytes(manifest));
+}
+
+function publishSnapshot(root: string, input: PublishInput): { snapshotId: string; path: string; created: boolean } {
+  ensurePrivateDirectory(root);
+  ensurePrivateDirectory(path.join(root, 'repairs'));
+  const date = new Date(input.observedTo);
+  if (!Number.isFinite(date.getTime())) throw new Error('observedTo must be an ISO timestamp');
+
+  const identity = {
+    scope: input.scope,
+    repository: input.repository,
+    observedFrom: input.observedFrom,
+    observedTo: input.observedTo,
+    objects: input.objects,
+    endpoints: input.endpoints,
+    excerptsEnabled: input.excerptsEnabled,
+    dispositionCounts: dispositionCounts(input.objects),
+    recordCount: input.records.length,
+    findingCount: input.quality.length,
+    repairCount: input.repairs.length
+  };
+  const identityDigest = sha256(canonicalJsonBytes(identity));
+  const stamp = input.observedTo.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  const snapshotId = `${stamp}-${identityDigest.slice(0, 12)}`;
+  const partialManifest: Omit<SnapshotManifest, 'manifestSha256'> = {
+    schema: 'raw-manifest/v1',
+    snapshotId,
+    ...identity,
+    privacyPolicyVersion: 'process-data-privacy/v1'
+  };
+  const manifest: SnapshotManifest = { ...partialManifest, manifestSha256: manifestDigest(partialManifest) };
+
+  const stagingRoot = path.join(root, '.staging');
+  ensurePrivateDirectory(stagingRoot);
+  const staging = fs.mkdtempSync(path.join(stagingRoot, `${snapshotId}-`));
+  if (process.platform !== 'win32') fs.chmodSync(staging, 0o700);
+  try {
+    writePrivateFile(path.join(staging, 'manifest.json'), jsonLine(manifest));
+    writePrivateFile(
+      path.join(staging, 'normalized.jsonl'),
+      input.records.map((record) => jsonLine({ schema: 'normalized/v1', ...record })).join('')
+    );
+    writePrivateFile(path.join(staging, 'quality.json'), jsonLine({ schema: 'quality/v1', findings: input.quality }));
+    writePrivateFile(
+      path.join(staging, 'repair-manifest.jsonl'),
+      input.repairs.map((repair) => jsonLine({ schema: 'repair/v1', ...repair })).join('')
+    );
+
+    const destination = path.join(
+      root,
+      'snapshots',
+      String(date.getUTCFullYear()),
+      String(date.getUTCMonth() + 1).padStart(2, '0'),
+      String(date.getUTCDate()).padStart(2, '0'),
+      snapshotId
+    );
+    ensurePrivateDirectory(path.dirname(destination));
+    if (fs.existsSync(destination)) {
+      const existing = fs.readFileSync(path.join(destination, 'manifest.json'), 'utf8');
+      if (existing !== jsonLine(manifest)) throw new Error(`snapshot collision: ${snapshotId}`);
+      fs.rmSync(staging, { recursive: true, force: true });
+      return { snapshotId, path: destination, created: false };
+    }
+    fs.renameSync(staging, destination);
+    return { snapshotId, path: destination, created: true };
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function findSnapshot(root: string, snapshotId: string): string | null {
+  const snapshotRoot = path.join(root, 'snapshots');
+  if (!fs.existsSync(snapshotRoot)) return null;
+  const stack = [snapshotRoot];
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(current, entry.name);
+      if (entry.name === snapshotId && fs.existsSync(path.join(candidate, 'manifest.json'))) return candidate;
+      stack.push(candidate);
+    }
+  }
+  return null;
+}
+
+function verifySnapshot(root: string, snapshotId: string): VerificationResult {
+  const snapshotPath = findSnapshot(root, snapshotId);
+  if (!snapshotPath) return { ok: false, snapshotId, snapshotPath: null, errors: ['snapshot not found'] };
+  const errors: string[] = [];
+  const checkMode = (target: string, expected: number, label: string) => {
+    if (process.platform === 'win32' || !fs.existsSync(target)) return;
+    const actual = fs.statSync(target).mode & 0o777;
+    if (actual !== expected) errors.push(`${label} permission mismatch: expected ${expected.toString(8)}, got ${actual.toString(8)}`);
+  };
+  checkMode(snapshotPath, 0o700, 'snapshot directory');
+  for (const file of ['manifest.json', 'normalized.jsonl', 'quality.json', 'repair-manifest.jsonl']) {
+    checkMode(path.join(snapshotPath, file), 0o600, file);
+  }
+  let manifest: SnapshotManifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'manifest.json'), 'utf8')) as SnapshotManifest;
+  } catch {
+    return { ok: false, snapshotId, snapshotPath, errors: ['manifest is invalid JSON'] };
+  }
+  if (manifest.schema !== 'raw-manifest/v1') errors.push(`unsupported manifest schema: ${manifest.schema}`);
+  if (manifest.snapshotId !== snapshotId) errors.push('snapshot identity mismatch');
+  if (typeof manifest.excerptsEnabled !== 'boolean') errors.push('manifest excerpts opt-in is invalid');
+  if (!manifest.dispositionCounts || canonicalJsonBytes(manifest.dispositionCounts).toString('utf8') !== canonicalJsonBytes(dispositionCounts(manifest.objects)).toString('utf8')) {
+    errors.push('manifest disposition counts mismatch');
+  }
+  const { manifestSha256, ...partial } = manifest;
+  if (manifestDigest(partial) !== manifestSha256) errors.push('manifest hash mismatch');
+  const store = createObjectStore(root);
+  try {
+    const lines = fs.readFileSync(path.join(snapshotPath, 'normalized.jsonl'), 'utf8').split('\n').filter(Boolean);
+    const ids = new Set<string>();
+    for (const line of lines) {
+      const record = JSON.parse(line) as { schema?: string; recordId?: string };
+      if (record.schema !== 'normalized/v1' || typeof record.recordId !== 'string') {
+        errors.push('normalized record schema is invalid');
+        continue;
+      }
+      if (ids.has(record.recordId)) errors.push(`duplicate normalized record: ${record.recordId}`);
+      ids.add(record.recordId);
+    }
+    if (lines.length !== manifest.recordCount) errors.push('normalized record count mismatch');
+    const quality = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'quality.json'), 'utf8')) as { schema?: string; findings?: unknown[] };
+    if (quality.schema !== 'quality/v1' || !Array.isArray(quality.findings)) errors.push('quality schema is invalid');
+    else if (quality.findings.length !== manifest.findingCount) errors.push('quality finding count mismatch');
+    const repairLines = fs.readFileSync(path.join(snapshotPath, 'repair-manifest.jsonl'), 'utf8').split('\n').filter(Boolean);
+    for (const line of repairLines) {
+      const repair = JSON.parse(line) as { schema?: string; repairId?: string };
+      if (repair.schema !== 'repair/v1' || typeof repair.repairId !== 'string') errors.push('repair manifest schema is invalid');
+    }
+    if (repairLines.length !== manifest.repairCount) errors.push('repair manifest count mismatch');
+  } catch {
+    errors.push('snapshot derived files are missing or invalid');
+  }
+  for (const object of manifest.objects) {
+    if (object.disposition?.state && object.disposition.state !== 'included') continue;
+    try {
+      const objectPath = store.pathFor(object.sha256);
+      checkMode(path.dirname(objectPath), 0o700, `object directory ${object.sha256.slice(0, 2)}`);
+      checkMode(objectPath, 0o600, `object ${object.sourceIdentity}`);
+      const bytes = fs.readFileSync(objectPath);
+      if (sha256(bytes) !== object.sha256) errors.push(`object hash mismatch: ${object.sourceIdentity}`);
+      if (bytes.length !== object.bytes) errors.push(`object byte count mismatch: ${object.sourceIdentity}`);
+    } catch {
+      errors.push(`object missing: ${object.sourceIdentity}`);
+    }
+  }
+  for (const page of manifest.endpoints.flatMap((endpoint) => endpoint.pages)) {
+    try {
+      if (sha256(fs.readFileSync(store.pathFor(page.canonicalSha256))) !== page.canonicalSha256) {
+        errors.push(`page hash mismatch: ${page.index}`);
+      }
+    } catch {
+      errors.push(`page object missing: ${page.canonicalSha256}`);
+    }
+  }
+  return { ok: errors.length === 0, snapshotId, snapshotPath, errors, manifest };
+}
+
+export {
+  canonicalJsonBytes,
+  createObjectStore,
+  findSnapshot,
+  publishSnapshot,
+  sha256,
+  verifySnapshot
+};
+export type { ObjectStore, ObjectWrite, PublishInput, VerificationResult };