@kontourai/flow-agents 3.12.0 → 4.0.0

package/src/narrative/resolver.ts

@@ -0,0 +1,195 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { assertPathContained } from "../lib/fs.js";
+import { parseSourceId } from "./source-ids.js";
+import type { IntegrityClass, UnavailableReason } from "./integrity.js";
+import {
+  validateNarrativeSourceManifest,
+  type NarrativeLineageEvent,
+  type NarrativeSourceManifest,
+  type NarrativeSourceManifestEntry,
+  type NarrativeSourceOrigin,
+} from "./snapshot.js";
+
+export type ResolveSourceResult =
+  | {
+      status: "resolved";
+      sourceId: string;
+      integrityClass: IntegrityClass;
+      sha256: string;
+      content: Uint8Array;
+      capturedAt: string;
+      origin: NarrativeSourceOrigin;
+      lineage: NarrativeLineageEvent[];
+    }
+  | { status: "unavailable"; sourceId: string; reason: UnavailableReason; detail: string };
+
+export interface ResolveSourceOptions { scope?: string }
+
+export interface VerifyManifestReport {
+  ok: boolean;
+  perSource: Array<{
+    sourceId: string;
+    status: "resolved" | "unavailable";
+    reason?: UnavailableReason;
+    /**
+     * Post-compile divergence between the frozen snapshot and its raw origin,
+     * e.g. `raw_source_rotated_away` once telemetry rotation deletes the log.
+     * Reported here (the manifest itself is frozen and never mutated).
+     */
+    lineageNote?: "raw_source_rotated_away";
+  }>;
+}
+
+function unavailable(sourceId: string, reason: UnavailableReason, detail: string): ResolveSourceResult {
+  return { status: "unavailable", sourceId, reason, detail };
+}
+
+function readRegularFile(file: string): Buffer {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("not a regular file");
+  const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+  try {
+    const opened = fs.fstatSync(descriptor);
+    // The descriptor must be the same inode the pre-open lstat admitted.
+    if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino) throw new Error("file changed between validation and read");
+    return fs.readFileSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function safeNarrativeDir(narrativeDir: string, scope?: string): string {
+  const real = fs.realpathSync(narrativeDir);
+  if (!fs.lstatSync(real).isDirectory()) throw new Error("narrative directory is invalid");
+  if (scope) assertPathContained(fs.realpathSync(scope), real);
+  return real;
+}
+
+function readManifest(narrativeDir: string): { manifest?: NarrativeSourceManifest; malformedIds: string[] } {
+  const bytes = readRegularFile(path.join(narrativeDir, "source-manifest.json"));
+  let parsed: unknown;
+  try { parsed = JSON.parse(bytes.toString("utf8")); }
+  catch { return { malformedIds: [] }; }
+  const malformedIds = parsed && typeof parsed === "object" && Array.isArray((parsed as Record<string, unknown>).sources)
+    ? ((parsed as Record<string, unknown>).sources as unknown[]).map((entry) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) return "manifest";
+        const sourceId = (entry as Record<string, unknown>).source_id;
+        return typeof sourceId === "string" && sourceId.startsWith("fa1:") ? sourceId : "manifest";
+      })
+    : [];
+  if (validateNarrativeSourceManifest(parsed).length) return { malformedIds };
+  return { manifest: parsed as NarrativeSourceManifest, malformedIds: [] };
+}
+
+export function resolveSource(narrativeDir: string, sourceId: string, opts: ResolveSourceOptions = {}): ResolveSourceResult {
+  let root: string;
+  try { root = safeNarrativeDir(narrativeDir, opts.scope); }
+  catch { return unavailable(sourceId, "unauthorized", "narrative directory is outside the authorized artifact scope"); }
+
+  let manifest: NarrativeSourceManifest | undefined;
+  try { manifest = readManifest(root).manifest; }
+  catch { return unavailable(sourceId, "corrupt", "source manifest could not be read safely"); }
+  if (!manifest) return unavailable(sourceId, "corrupt", "source manifest is malformed");
+  const matches = manifest.sources.filter((entry) => entry.source_id === sourceId);
+  if (matches.length === 0) return unavailable(sourceId, "not_captured", "source id is not present in the manifest");
+  if (matches.length !== 1) return unavailable(sourceId, "corrupt", "source id is not unique in the manifest");
+  const entry = matches[0];
+  if (entry.status === "unavailable") return unavailable(sourceId, entry.unavailable_reason, "source was recorded as unavailable during snapshot");
+  return resolveEntry(root, entry);
+}
+
+/** The frozen-manifest existence + provenance of a source, independent of content availability. */
+export interface FrozenManifestEntry {
+  sourceId: string;
+  /** The source's own frozen `captured_at` — the authoritative at-capture timestamp. */
+  capturedAt: string;
+  status: NarrativeSourceManifestEntry["status"];
+}
+
+/**
+ * Resolve a source's FROZEN MANIFEST ENTRY (existence + authoritative captured_at),
+ * NOT its content. #622 (R1): at-action intent annotation co-binds to the action's
+ * PRESENCE in the frozen manifest and its own captured_at. A source that is present
+ * but content-unavailable (redacted / expired / rotated away) still legitimately
+ * EXISTS and is frozen — only an ABSENT / fabricated ref, an unreadable/malformed
+ * manifest, or a non-unique id yields `undefined` (fail closed).
+ */
+export function resolveManifestEntry(narrativeDir: string, sourceId: string): FrozenManifestEntry | undefined {
+  let root: string;
+  try { root = safeNarrativeDir(narrativeDir); }
+  catch { return undefined; }
+  let manifest: NarrativeSourceManifest | undefined;
+  try { manifest = readManifest(root).manifest; }
+  catch { return undefined; }
+  if (!manifest) return undefined;
+  const matches = manifest.sources.filter((entry) => entry.source_id === sourceId);
+  if (matches.length !== 1) return undefined;
+  const entry = matches[0];
+  return { sourceId, capturedAt: entry.captured_at, status: entry.status };
+}
+
+function resolveEntry(root: string, entry: Extract<NarrativeSourceManifestEntry, { status: "snapshotted" }>): ResolveSourceResult {
+  const sourcesDir = path.join(root, "sources");
+  const blob = path.join(sourcesDir, entry.sha256);
+  let bytes: Buffer;
+  try {
+    // The blob's ancestor must be a real directory inside the narrative dir —
+    // a symlinked sources/ would silently serve content from elsewhere.
+    const dirStat = fs.lstatSync(sourcesDir);
+    if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) throw new Error("sources directory is not a real directory");
+    assertPathContained(root, blob);
+    bytes = readRegularFile(blob);
+  } catch {
+    return unavailable(entry.source_id, "corrupt", "snapshot blob could not be read safely");
+  }
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (digest !== entry.sha256 || bytes.length !== entry.bytes) return unavailable(entry.source_id, "corrupt", "snapshot blob integrity check failed");
+  return {
+    status: "resolved", sourceId: entry.source_id, integrityClass: entry.integrity_class,
+    sha256: entry.sha256, content: bytes, capturedAt: entry.captured_at,
+    origin: entry.origin, lineage: entry.lineage ?? [],
+  };
+}
+
+export function verifyManifest(narrativeDir: string): VerifyManifestReport {
+  let root: string;
+  try { root = safeNarrativeDir(narrativeDir); }
+  catch { return { ok: false, perSource: [{ sourceId: "manifest", status: "unavailable", reason: "corrupt" }] }; }
+  let read: ReturnType<typeof readManifest>;
+  try { read = readManifest(root); }
+  catch { return { ok: false, perSource: [{ sourceId: "manifest", status: "unavailable", reason: "corrupt" }] }; }
+  if (!read.manifest) {
+    const ids = read.malformedIds.length ? read.malformedIds : ["manifest"];
+    return { ok: false, perSource: ids.map((sourceId) => ({ sourceId, status: "unavailable", reason: "corrupt" })) };
+  }
+  const perSource = read.manifest.sources.map((entry) => {
+    const result = resolveSource(root, entry.source_id);
+    const lineageNote = rawSourceRotatedAway(entry) ? ({ lineageNote: "raw_source_rotated_away" as const }) : {};
+    return result.status === "resolved"
+      ? { sourceId: entry.source_id, status: "resolved" as const, ...lineageNote }
+      : { sourceId: entry.source_id, status: "unavailable" as const, reason: result.reason, ...lineageNote };
+  });
+  return { ok: perSource.every((result) => result.status === "resolved"), perSource };
+}
+
+function rawSourceRotatedAway(entry: NarrativeSourceManifestEntry): boolean {
+  if (entry.status !== "snapshotted") return false;
+  const originPath = entry.origin?.path;
+  if (typeof originPath !== "string") return false;
+  if (!fs.existsSync(originPath)) return true;
+  // Telemetry origins record the log directory; the rotatable stores are the
+  // channel files inside it, so divergence means no channel file remains.
+  if (entry.origin.store !== "telemetry") return false;
+  try {
+    const parsed = parseSourceId(entry.source_id);
+    if (parsed.stream !== "telemetry") return false;
+    const names = fs.readdirSync(originPath);
+    const channel = parsed.scope.channel;
+    return !names.some((name) => name === `${channel}.jsonl` || new RegExp(`^${channel}\\.[1-9][0-9]*\\.jsonl$`).test(name));
+  } catch {
+    return false;
+  }
+}

package/src/narrative/snapshot.ts

@@ -0,0 +1,365 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { atomicWriteFile, ensureSafeDirectory } from "../lib/fs.js";
+import type { CaptureCompleteness, IntegrityClass, UnavailableReason } from "./integrity.js";
+import { integrityClassForSource } from "./integrity.js";
+import { filterNarrativeRecord } from "./policy-filter.js";
+import {
+  NarrativeReaderError,
+  readAgentEventCandidate,
+  readCommandLogCandidate,
+  readDelegationCandidate,
+  readFileCandidate,
+  readFlowReportCandidate,
+  readFlowStateCandidate,
+  readFlowTransitionCandidate,
+  readTelemetryCandidates,
+  readSurfaceExplanationCandidate,
+  readTranscriptCandidate,
+  readTrustClaimCandidate,
+  readTrustEvidenceCandidate,
+  type ReadCandidate,
+} from "./readers.js";
+import { formatSourceId, type NarrativeSourceId } from "./source-ids.js";
+
+export interface NarrativeSourceRoots {
+  telemetryDir?: string;
+  sessionDir?: string;
+  flowRoot?: string;
+  transcriptPath?: string;
+  repoRoot?: string;
+}
+
+export interface NarrativeLineageEvent { at: string; event: string }
+
+export interface NarrativeSourceRequest {
+  source: NarrativeSourceId;
+  roots: NarrativeSourceRoots;
+  lineage?: NarrativeLineageEvent[];
+}
+
+export interface NarrativeSourceOrigin {
+  store: string;
+  path_class: string;
+  path?: string;
+  chain?: { seq: number; prevHash: string; hash: string };
+  package?: { name: string; version: string };
+}
+
+interface NarrativeSourceBase {
+  source_id: string;
+  integrity_class: IntegrityClass;
+  captured_at: string;
+  origin: NarrativeSourceOrigin;
+  redactions?: string[];
+  lineage: NarrativeLineageEvent[];
+}
+
+export type NarrativeSourceManifestEntry =
+  | (NarrativeSourceBase & { status: "snapshotted"; sha256: string; bytes: number })
+  | (NarrativeSourceBase & { status: "unavailable"; unavailable_reason: UnavailableReason });
+
+export interface NarrativeSourceManifest {
+  schema_version: "1.0";
+  narrative_id: string;
+  captured_at: string;
+  compiler: { name: string; version: string; policy_hash: string };
+  capture_completeness: CaptureCompleteness;
+  sources: NarrativeSourceManifestEntry[];
+}
+
+export interface SnapshotNarrativeInput {
+  narrativeDir: string;
+  narrativeId: string;
+  requests: NarrativeSourceRequest[];
+  redactionFields: readonly string[];
+  compiler: NarrativeSourceManifest["compiler"];
+  captureCompleteness: CaptureCompleteness;
+  /**
+   * Transcript content is DEFAULT-DENY: transcripts are arbitrary runtime
+   * payloads that whole-field policy cannot meaningfully filter, so without
+   * this explicit grant a transcript request is recorded path_only as
+   * unavailable/redacted and no content is snapshotted.
+   */
+  allowTranscriptContent?: boolean;
+}
+
+export interface SnapshotNarrativeDependencies {
+  now?: () => string;
+  writeBlob?: (root: string, file: string, data: Buffer) => void;
+  writeManifest?: (root: string, file: string, value: unknown) => void;
+}
+
+type SchemaIssue = { path: string; message: string };
+type JsonSchema = Record<string, any>;
+const dateTimeRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function schemaMatches(value: unknown, schema: JsonSchema, root: JsonSchema): boolean {
+  const issues: SchemaIssue[] = [];
+  validateSchemaValue(value, schema, "$", issues, root);
+  return issues.length === 0;
+}
+
+function resolveSchemaRef(ref: string, root: JsonSchema): JsonSchema | undefined {
+  if (!ref.startsWith("#/$defs/")) return undefined;
+  return root.$defs?.[ref.slice("#/$defs/".length)];
+}
+
+function validateSchemaValue(value: unknown, schema: JsonSchema, loc: string, issues: SchemaIssue[], root = schema): void {
+  if (schema.$ref) {
+    const resolved = resolveSchemaRef(schema.$ref, root);
+    if (!resolved) issues.push({ path: loc, message: `unsupported schema ref ${schema.$ref}` });
+    else validateSchemaValue(value, resolved, loc, issues, root);
+    return;
+  }
+  if (schema.anyOf && !schema.anyOf.some((sub: JsonSchema) => schemaMatches(value, sub, root))) issues.push({ path: loc, message: "must match at least one allowed schema" });
+  if (schema.oneOf) {
+    const matches = schema.oneOf.filter((sub: JsonSchema) => schemaMatches(value, sub, root)).length;
+    if (matches !== 1) issues.push({ path: loc, message: "must match exactly one allowed schema" });
+  }
+  if (schema.not && schemaMatches(value, schema.not, root)) issues.push({ path: loc, message: "must not match forbidden schema" });
+  for (const sub of schema.allOf ?? []) validateSchemaValue(value, sub, loc, issues, root);
+  if (schema.const !== undefined && value !== schema.const) issues.push({ path: loc, message: `must equal ${String(schema.const)}` });
+  if (schema.enum && !schema.enum.includes(value)) issues.push({ path: loc, message: `must be one of ${schema.enum.join(", ")}` });
+  if (schema.type === "string") {
+    if (typeof value !== "string") { issues.push({ path: loc, message: "must be string" }); return; }
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) issues.push({ path: loc, message: "must not be empty" });
+    if (schema.pattern && !(new RegExp(schema.pattern)).test(value)) issues.push({ path: loc, message: "has invalid format" });
+    if (schema.format === "date-time" && (!dateTimeRe.test(value) || Number.isNaN(Date.parse(value)))) issues.push({ path: loc, message: "must be date-time" });
+    return;
+  }
+  if (schema.type === "integer") {
+    if (!Number.isInteger(value)) { issues.push({ path: loc, message: "must be integer" }); return; }
+    if (typeof schema.minimum === "number" && (value as number) < schema.minimum) issues.push({ path: loc, message: `must be at least ${schema.minimum}` });
+    return;
+  }
+  if (schema.type === "array") {
+    if (!Array.isArray(value)) { issues.push({ path: loc, message: "must be array" }); return; }
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) issues.push({ path: loc, message: `must contain at least ${schema.minItems} item(s)` });
+    if (schema.uniqueItems && new Set(value.map((item) => JSON.stringify(item))).size !== value.length) issues.push({ path: loc, message: "must contain unique items" });
+    if (schema.items) value.forEach((item, index) => validateSchemaValue(item, schema.items, `${loc}[${index}]`, issues, root));
+    return;
+  }
+  if (schema.type === "object" || schema.required || schema.properties) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) { issues.push({ path: loc, message: "must be object" }); return; }
+    const object = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) if (!(key in object)) issues.push({ path: `${loc}.${key}`, message: "is required" });
+    const properties = schema.properties ?? {};
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(object)) if (!(key in properties)) issues.push({ path: `${loc}.${key}`, message: "is not allowed" });
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      for (const key of Object.keys(object)) if (!(key in properties)) validateSchemaValue(object[key], schema.additionalProperties, `${loc}.${key}`, issues, root);
+    }
+    for (const [key, child] of Object.entries<JsonSchema>(properties)) if (key in object) validateSchemaValue(object[key], child, `${loc}.${key}`, issues, root);
+  }
+}
+
+function schemaPath(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../schemas/narrative-source-manifest.schema.json");
+}
+
+export function validateNarrativeSourceManifest(value: unknown): SchemaIssue[] {
+  let schema: JsonSchema;
+  try { schema = JSON.parse(fs.readFileSync(schemaPath(), "utf8")) as JsonSchema; }
+  catch { return [{ path: "$", message: "narrative source manifest schema is unavailable" }]; }
+  const issues: SchemaIssue[] = [];
+  validateSchemaValue(value, schema, "$", issues, schema);
+  return issues;
+}
+
+function requiredRoot(root: string | undefined, sourceId: string, label: string): string {
+  if (!root) throw new NarrativeReaderError("not_captured", sourceId, `${sourceId} requires ${label}`);
+  return root;
+}
+
+function originFor(request: NarrativeSourceRequest): NarrativeSourceOrigin {
+  const { source, roots } = request;
+  const store = source.stream;
+  if (source.stream === "telemetry") return { store, path_class: "telemetry_root", ...(roots.telemetryDir ? { path: roots.telemetryDir } : {}) };
+  if (["cmdlog", "agent-event", "delegation", "trust-claim", "trust-evidence", "surface-explanation"].includes(source.stream)) return { store, path_class: "session_root", ...(roots.sessionDir ? { path: roots.sessionDir } : {}) };
+  if (source.stream === "flow-state" || source.stream === "flow-report" || source.stream === "flow-transition") return { store, path_class: "flow_root", ...(roots.flowRoot ? { path: roots.flowRoot } : {}) };
+  if (source.stream === "transcript") return { store, path_class: "external_path", ...(roots.transcriptPath ? { path: roots.transcriptPath } : {}) };
+  return { store, path_class: "repository", ...(roots.repoRoot ? { path: roots.repoRoot } : {}) };
+}
+
+function sessionRootForSlug(roots: NarrativeSourceRoots, slug: string, sourceId: string): string {
+  const sessionDir = requiredRoot(roots.sessionDir, sourceId, "session root");
+  // A session-scoped ID names its slug; the supplied root must BE that session,
+  // not merely any directory the caller controls.
+  if (path.basename(path.resolve(sessionDir)) !== slug) {
+    throw new NarrativeReaderError("unauthorized", sourceId, `${sourceId} names slug ${slug} but the session root does not`);
+  }
+  return sessionDir;
+}
+
+function locate(request: NarrativeSourceRequest): ReadCandidate | Buffer {
+  const sourceId = formatSourceId(request.source);
+  const { source, roots } = request;
+  switch (source.stream) {
+    case "telemetry": {
+      const matches = readTelemetryCandidates({ telemetryDir: requiredRoot(roots.telemetryDir, sourceId, "telemetry root"), channel: source.scope.channel, sessionId: source.scope.sessionId, eventId: source.locator.eventId, sha8: source.locator.sha8, ordinal: source.ordinal });
+      if (matches.length === 0) throw new NarrativeReaderError("not_captured", sourceId, `${sourceId} was not captured`);
+      if (matches.length > 1) throw new NarrativeReaderError("corrupt", sourceId, `${sourceId} requires an ordinal because it is not unique`);
+      return matches[0];
+    }
+    case "cmdlog": return readCommandLogCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), locator: source.locator });
+    case "agent-event": return readAgentEventCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), agentId: source.scope.agentId, lineIndex: source.locator.lineIndex, sha8: source.locator.sha8 });
+    case "delegation": return readDelegationCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), agentId: source.scope.agentId, lineIndex: source.locator.lineIndex, sha8: source.locator.sha8 });
+    case "trust-claim": return readTrustClaimCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), bundleSha8: source.scope.bundleSha8, id: source.locator.id });
+    case "trust-evidence": return readTrustEvidenceCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), bundleSha8: source.scope.bundleSha8, id: source.locator.id });
+    case "flow-state": return readFlowStateCandidate({ flowRoot: requiredRoot(roots.flowRoot, sourceId, "flow root"), runId: source.scope.runId, sha8: source.locator.sha8 });
+    case "flow-report": return readFlowReportCandidate({ flowRoot: requiredRoot(roots.flowRoot, sourceId, "flow root"), runId: source.scope.runId, sha8: source.locator.sha8 });
+    case "flow-transition": return readFlowTransitionCandidate({ flowRoot: requiredRoot(roots.flowRoot, sourceId, "flow root"), runId: source.scope.runId, index: source.locator.index, sha8: source.locator.sha8 });
+    case "surface-explanation": return readSurfaceExplanationCandidate({ sessionDir: sessionRootForSlug(roots, source.scope.slug, sourceId), bundleSha8: source.scope.bundleSha8, claimId: source.locator.claimId });
+    case "transcript": {
+      const absolutePath = path.resolve(requiredRoot(roots.transcriptPath, sourceId, "transcript path"));
+      // The ID's scope pin names one exact path; a mismatched root is a rebind.
+      const pathSha8 = createHash("sha256").update(absolutePath, "utf8").digest("hex").slice(0, 8);
+      if (pathSha8 !== source.scope.pathSha8) throw new NarrativeReaderError("corrupt", sourceId, `${sourceId} path pin does not match the supplied transcript path`);
+      return readTranscriptCandidate({ absolutePath, byteStart: source.locator.byteStart, byteEnd: source.locator.byteEnd });
+    }
+    case "file": return readFileCandidate({ repoRoot: requiredRoot(roots.repoRoot, sourceId, "repository root"), repoRelativePath: source.scope.repoRelativePath, hash: source.locator.hash });
+  }
+}
+
+function chainFrom(candidate: ReadCandidate | Buffer): NarrativeSourceOrigin["chain"] | undefined {
+  if (Buffer.isBuffer(candidate) || !candidate.record || typeof candidate.record !== "object" || Buffer.isBuffer(candidate.record)) return undefined;
+  const chain = (candidate.record as Record<string, unknown>)["_chain"] as Record<string, unknown> | undefined;
+  if (!chain || !Number.isSafeInteger(chain.seq) || typeof chain.prevHash !== "string" || typeof chain.hash !== "string") return undefined;
+  return { seq: chain.seq as number, prevHash: chain.prevHash, hash: chain.hash };
+}
+
+function lineageFor(request: NarrativeSourceRequest, capturedAt: string): NarrativeLineageEvent[] {
+  return request.lineage ?? [{ at: capturedAt, event: "source_snapshotted" }];
+}
+
+function unavailableEntry(request: NarrativeSourceRequest, capturedAt: string, reason: UnavailableReason, redactions?: string[]): NarrativeSourceManifestEntry {
+  return {
+    source_id: formatSourceId(request.source), integrity_class: integrityClassForSource(request.source), captured_at: capturedAt,
+    origin: originFor(request), status: "unavailable", unavailable_reason: reason,
+    ...(redactions?.length ? { redactions } : {}), lineage: lineageFor(request, capturedAt),
+  };
+}
+
+function matchingObjectKeys(value: unknown, configuredFields: readonly string[]): string[] {
+  const fields = [...new Set(configuredFields.map((field) => field.trim()).filter(Boolean))];
+  if (fields.length === 0) return [];
+  const configured = new Set(fields);
+  const matched = new Set<string>();
+  const visit = (candidate: unknown): void => {
+    if (!candidate || typeof candidate !== "object") return;
+    if (Array.isArray(candidate)) {
+      for (const item of candidate) visit(item);
+      return;
+    }
+    for (const [key, child] of Object.entries(candidate as Record<string, unknown>)) {
+      if (configured.has(key)) matched.add(key);
+      visit(child);
+    }
+  };
+  visit(value);
+  return fields.filter((field) => matched.has(field));
+}
+
+function createOnlyWriteManifest(root: string, file: string, value: unknown): void {
+  // Creation-only publication: link(2) fails with EEXIST if any concurrent
+  // writer published first, so a frozen manifest can never be replaced by a
+  // second racer (a replace-style atomic rename would let the loser win).
+  const temp = path.join(root, `.source-manifest.${process.pid}.${Date.now().toString(36)}.tmp`);
+  atomicWriteFile(root, temp, Buffer.from(`${JSON.stringify(value, null, 2)}\n`));
+  try {
+    fs.linkSync(temp, file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("narrative source manifest already exists");
+    throw error;
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+export function snapshotNarrative(input: SnapshotNarrativeInput, dependencies: SnapshotNarrativeDependencies = {}): { narrativeDir: string; manifest: NarrativeSourceManifest } {
+  const now = dependencies.now ?? (() => new Date().toISOString());
+  const writeBlob = dependencies.writeBlob ?? atomicWriteFile;
+  const writeManifest = dependencies.writeManifest ?? createOnlyWriteManifest;
+  const capturedAt = now();
+  const sources: NarrativeSourceManifestEntry[] = [];
+  const written = new Set<string>();
+  if (fs.existsSync(path.join(input.narrativeDir, "source-manifest.json"))) throw new Error("narrative source manifest already exists");
+  ensureSafeDirectory(input.narrativeDir, path.join(input.narrativeDir, "sources"));
+
+  for (const request of input.requests) {
+    const sourceCapturedAt = now();
+    if (request.source.stream === "transcript" && input.allowTranscriptContent !== true) {
+      sources.push(unavailableEntry(request, sourceCapturedAt, "redacted"));
+      continue;
+    }
+    let candidate: ReadCandidate | Buffer;
+    try { candidate = locate(request); }
+    catch (error) {
+      const reason = error instanceof NarrativeReaderError ? error.reason : "corrupt";
+      sources.push(unavailableEntry(request, sourceCapturedAt, reason));
+      continue;
+    }
+    const origin = {
+      ...originFor(request),
+      ...(!Buffer.isBuffer(candidate) && candidate.originPackage ? { package: candidate.originPackage } : {}),
+      ...(chainFrom(candidate) ? { chain: chainFrom(candidate) } : {}),
+    };
+    if (request.source.stream === "flow-report" || request.source.stream === "surface-explanation") {
+      // These streams are already authority-authored capture products. Preserve
+      // Flow's foreign formatting and Surface's stableStringify bytes exactly.
+      // Because rewriting those bytes would destroy that authority property,
+      // configured redaction keys make the entire source unavailable instead.
+      let authorityRecord: unknown;
+      try { authorityRecord = JSON.parse((candidate as ReadCandidate).raw.toString("utf8")); }
+      catch {
+        sources.push({ ...unavailableEntry(request, sourceCapturedAt, "corrupt"), origin });
+        continue;
+      }
+      const matchedFields = matchingObjectKeys(authorityRecord, input.redactionFields);
+      if (matchedFields.length > 0) {
+        sources.push({ ...unavailableEntry(request, sourceCapturedAt, "redacted", matchedFields), origin });
+        continue;
+      }
+      const bytes = Buffer.from((candidate as ReadCandidate).raw);
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (!written.has(digest)) {
+        writeBlob(input.narrativeDir, path.join(input.narrativeDir, "sources", digest), bytes);
+        written.add(digest);
+      }
+      sources.push({
+        source_id: formatSourceId(request.source), integrity_class: integrityClassForSource(request.source), captured_at: sourceCapturedAt,
+        origin, status: "snapshotted", sha256: digest, bytes: bytes.length, lineage: lineageFor(request, sourceCapturedAt),
+      });
+      continue;
+    }
+    const record = Buffer.isBuffer(candidate) ? candidate : candidate.record;
+    const filtered = filterNarrativeRecord(record, input.redactionFields);
+    if (filtered.kind === "redacted") {
+      sources.push({ ...unavailableEntry(request, sourceCapturedAt, "redacted", filtered.fields), origin });
+      continue;
+    }
+    const bytes = Buffer.from(JSON.stringify(filtered.record));
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (!written.has(digest)) {
+      writeBlob(input.narrativeDir, path.join(input.narrativeDir, "sources", digest), bytes);
+      written.add(digest);
+    }
+    sources.push({
+      source_id: formatSourceId(request.source), integrity_class: integrityClassForSource(request.source), captured_at: sourceCapturedAt,
+      origin, status: "snapshotted", sha256: digest, bytes: bytes.length,
+      ...(filtered.redactions.length ? { redactions: filtered.redactions } : {}), lineage: lineageFor(request, sourceCapturedAt),
+    });
+  }
+
+  const manifest: NarrativeSourceManifest = {
+    schema_version: "1.0", narrative_id: input.narrativeId, captured_at: capturedAt,
+    compiler: input.compiler, capture_completeness: input.captureCompleteness, sources,
+  };
+  const issues = validateNarrativeSourceManifest(manifest);
+  if (issues.length) throw new Error(`narrative source manifest validation failed: ${issues.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`);
+  writeManifest(input.narrativeDir, path.join(input.narrativeDir, "source-manifest.json"), manifest);
+  return { narrativeDir: input.narrativeDir, manifest };
+}