harnery 0.34.1 → 0.36.0

package/src/core/artifacts/index.ts

@@ -23,11 +23,14 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
-import { artifactDefaultRetentionDays } from "../config.ts";
+import {
+  artifactAutoCleanEnabled,
+  artifactAutoCleanIntervalHours,
+  artifactDefaultRetentionDays,
+} from "../config.ts";
+import { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
 
-export const ARTIFACTS_DIR = join(".harnery", "artifacts");
-export const ARTIFACT_MANIFEST = ".harnery-artifact.json";
-export const ARTIFACT_SCHEMA_VERSION = 1 as const;
+export { ARTIFACT_MANIFEST, ARTIFACT_SCHEMA_VERSION, ARTIFACTS_DIR } from "./constants.ts";
 
 export interface ArtifactActor {
   instance_id: string;
@@ -72,6 +75,7 @@ export interface ArtifactInventoryEntry {
   artifact_id: string | null;
   slug: string | null;
   created_at: string | null;
+  last_modified_at: string | null;
   expires_at: string | null;
   owner_instance_id: string | null;
 }
@@ -277,6 +281,65 @@ export function cleanArtifacts(
   });
 }
 
+/** Sibling of the artifacts root so the stamp never appears in the inventory scan. */
+const AUTO_CLEAN_STAMP = ".harnery/artifacts-auto-clean.json";
+
+export interface ArtifactAutoCleanResult {
+  ran: boolean;
+  reason: "swept" | "disabled" | "fresh" | "no-root";
+  deleted: number;
+  bytes: number;
+}
+
+/**
+ * Throttled expired-artifact sweep, fired as a SessionStart effect.
+ *
+ * Retention was previously enforced only when someone remembered to run
+ * `artifacts clean --yes`, so expired workspaces accumulated indefinitely on
+ * busy hosts. This runs the exact same guarded deletion (only
+ * `managed-expired` entries, each re-classified immediately before removal;
+ * unmanaged and legacy directories are never touched) at most once per
+ * interval (default 24h), claim-first via a stamp file so concurrent session
+ * starts do not double-sweep. Disable with `artifacts.auto_clean: false` or
+ * `HARNERY_ARTIFACT_AUTO_CLEAN=0`.
+ */
+export function autoCleanArtifacts(
+  repoRoot: string,
+  opts: { now?: Date } = {},
+): ArtifactAutoCleanResult {
+  const now = opts.now ?? new Date();
+  assertValidDate(now, "now");
+  if (!existsSync(artifactsRoot(repoRoot))) {
+    return { ran: false, reason: "no-root", deleted: 0, bytes: 0 };
+  }
+  if (!artifactAutoCleanEnabled(repoRoot)) {
+    return { ran: false, reason: "disabled", deleted: 0, bytes: 0 };
+  }
+  const stampPath = join(resolve(repoRoot), AUTO_CLEAN_STAMP);
+  const intervalMs = artifactAutoCleanIntervalHours() * 60 * 60 * 1000;
+  try {
+    const stamp = JSON.parse(readFileSync(stampPath, "utf8")) as { last_run_at?: string };
+    const last = Date.parse(stamp.last_run_at ?? "");
+    if (Number.isFinite(last) && now.getTime() - last < intervalMs) {
+      return { ran: false, reason: "fresh", deleted: 0, bytes: 0 };
+    }
+  } catch {
+    // Missing or unreadable stamp: sweep now and write a fresh one.
+  }
+  // Claim first: a crash mid-sweep costs one skipped interval, while claiming
+  // after would let two concurrent session starts both walk the store.
+  writeFileSync(stampPath, `${JSON.stringify({ last_run_at: now.toISOString() }, null, 2)}\n`);
+  const rows = cleanArtifacts(repoRoot, { yes: true, now });
+  const deletedRows = rows.filter((row) => row.action === "deleted");
+  const deleted = deletedRows.length;
+  const bytes = deletedRows.reduce((sum, row) => sum + (row.bytes ?? 0), 0);
+  writeFileSync(
+    stampPath,
+    `${JSON.stringify({ last_run_at: now.toISOString(), deleted, bytes }, null, 2)}\n`,
+  );
+  return { ran: true, reason: "swept", deleted, bytes };
+}
+
 export function resolveArtifactRef(repoRoot: string, ref: string): string {
   const root = artifactsRoot(repoRoot);
   const candidate = isAbsolute(ref) ? resolve(ref) : resolve(root, ref);
@@ -328,16 +391,22 @@ function classifyArtifactPath(
   }
   const manifest = parsed.manifest;
   const bytes = safeTreeSize(path);
+  const lastModifiedMs = safeTreeLastModified(path, now);
+  const retentionAnchorMs = Date.parse(manifest.retention.renewed_at ?? manifest.created_at);
+  const retentionWindowMs = Date.parse(manifest.retention.expires_at) - retentionAnchorMs;
+  const effectiveLastModifiedMs = Math.max(retentionAnchorMs, lastModifiedMs ?? 0);
+  const effectiveExpiresAt = new Date(effectiveLastModifiedMs + retentionWindowMs).toISOString();
   const base = rowFor(path, name, repoRoot, "managed-current", "retention has not expired", bytes);
   Object.assign(base, {
     artifact_id: manifest.artifact_id,
     slug: manifest.slug,
     created_at: manifest.created_at,
-    expires_at: manifest.retention.expires_at,
+    last_modified_at: new Date(effectiveLastModifiedMs).toISOString(),
+    expires_at: effectiveExpiresAt,
     owner_instance_id: manifest.created_by?.instance_id ?? null,
   });
 
-  if (base.bytes === null) {
+  if (base.bytes === null || lastModifiedMs === null) {
     return {
       ...base,
       classification: "unknown",
@@ -372,11 +441,11 @@ function classifyArtifactPath(
       };
     }
   }
-  if (Date.parse(manifest.retention.expires_at) > now.getTime()) return base;
+  if (Date.parse(effectiveExpiresAt) > now.getTime()) return base;
   return {
     ...base,
     classification: "managed-expired",
-    reason: `retention expired at ${manifest.retention.expires_at}`,
+    reason: `retention expired at ${effectiveExpiresAt}`,
     action: "would-delete",
   };
 }
@@ -410,6 +479,13 @@ function readManifest(path: string): ParsedManifest | ManifestError {
   if (!m.retention || typeof m.retention !== "object" || !validIso(m.retention.expires_at)) {
     return { ok: false, reason: "invalid retention.expires_at" };
   }
+  if (m.retention.renewed_at !== undefined && !validIso(m.retention.renewed_at)) {
+    return { ok: false, reason: "invalid retention.renewed_at" };
+  }
+  const retentionAnchor = Date.parse(m.retention.renewed_at ?? m.created_at);
+  if (Date.parse(m.retention.expires_at) <= retentionAnchor) {
+    return { ok: false, reason: "retention.expires_at must follow its retention anchor" };
+  }
   if (m.released_at !== undefined && !validIso(m.released_at)) {
     return { ok: false, reason: "invalid released_at" };
   }
@@ -478,6 +554,34 @@ function safeTreeSize(path: string): number | null {
   }
 }
 
+/**
+ * Return the newest filesystem change in a managed tree without following
+ * symlinks. A small future tolerance protects a write racing the inventory
+ * scan; timestamps farther ahead are ignored as clock-skewed metadata.
+ */
+function safeTreeLastModified(path: string, now: Date): number | null {
+  const nowMs = now.getTime();
+  const futureToleranceMs = 5 * 60 * 1000;
+  try {
+    const st = lstatSync(path);
+    let latest = 0;
+    for (const timestamp of [st.mtimeMs, st.ctimeMs]) {
+      if (Number.isFinite(timestamp) && timestamp <= nowMs + futureToleranceMs) {
+        latest = Math.max(latest, Math.min(timestamp, nowMs));
+      }
+    }
+    if (st.isSymbolicLink() || !st.isDirectory()) return latest;
+    for (const child of readdirSync(path)) {
+      const childLatest = safeTreeLastModified(join(path, child), now);
+      if (childLatest === null) return null;
+      latest = Math.max(latest, childLatest);
+    }
+    return latest;
+  } catch {
+    return null;
+  }
+}
+
 function rowFor(
   path: string,
   name: string,
@@ -497,6 +601,7 @@ function rowFor(
     artifact_id: null,
     slug: null,
     created_at: null,
+    last_modified_at: null,
     expires_at: null,
     owner_instance_id: null,
   };

package/src/core/config.ts

@@ -7,8 +7,9 @@
  *   2. `<project-root>/.harnery/config.jsonc` — project override (authoritative)
  *
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
- * `hooksSetupHint`, `agents`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
- * `coord` (heartbeat freshness), `artifacts` (working-file retention),
+ * `hooksSetupHint`, `agents`, `instructions`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
+ * `coord` (heartbeat freshness), `logs` (structured-log storage budgets),
+ * `artifacts` (working-file retention),
  * `backup` (restic repo/password/prune policy), `sync` (rclone
  * remote/prefix), and `web` (dashboard port) sections. The `files` deny/override section
  * is parsed separately by `web/lib/files.ts`.
@@ -22,16 +23,21 @@ import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { coordEnv } from "../lib/env.ts";
+import { DEFAULT_WEB_PORT } from "../lib/local-file-url.ts";
+import { resolveEventLedgerRotateActiveBytesV3 } from "./events/v3/rotation-config.ts";
 import { findCoordRoot } from "./hooks/resolve/coord-root.ts";
 
+export { DEFAULT_WEB_PORT } from "../lib/local-file-url.ts";
+export { DEFAULT_EVENT_LEDGER_ROTATE_ACTIVE_BYTES } from "./events/v3/rotation-config.ts";
+
 /** The standalone CLI's bin name: the resolution floor when nothing else is set. */
 export const DEFAULT_BIN_NAME = "harn";
 
 /** Heartbeat-freshness default (seconds): the sweep window when nothing overrides it. */
 export const DEFAULT_FRESHNESS_SECS = 600;
 
-/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
-export const DEFAULT_WEB_PORT = 4276;
+/** Keep a fresh host reminder bounded to one short prompt-context line. */
+export const MAX_HOST_PROMPT_REMINDER_CHARS = 500;
 
 export interface SessionFinalizationConfig {
   archiveGraceSeconds: number;
@@ -76,6 +82,11 @@ interface HarneryConfig {
     requireGitFinalization?: boolean;
     finalizationRoots?: AgentFinalizationRoot[];
   };
+  /** Host-owned agent instruction settings. */
+  instructions?: {
+    hostAddendumFile?: unknown;
+    promptReminder?: unknown;
+  };
   /**
    * Managed-tool provisioning consent. `{ ripgrep: { autoInstall: true } }`
    * lets `grep` download the pinned, checksum-verified ripgrep into the
@@ -118,11 +129,20 @@ interface HarneryConfig {
       reconcile_interval_seconds?: number;
     };
   };
+  /** Strictly validated structured-log storage overrides. */
+  logs?: { storage?: unknown };
+  /**
+   * Universal event-ledger V3 tunables. `rotate_active_bytes` is the active
+   * segment size at which the epoch is archived and replaced automatically
+   * (default 32 MiB; `0` disables rotation). Read via
+   * `eventLedgerRotateActiveBytes()`.
+   */
+  events?: { rotate_active_bytes?: number };
   /**
    * Managed working-artifact defaults. `default_retention_days` is the
    * create-time TTL when the caller does not pass `artifacts create --days`.
    */
-  artifacts?: { default_retention_days?: number };
+  artifacts?: { default_retention_days?: number; auto_clean?: boolean };
   /**
    * `harn backup` (restic) defaults: `repo` path/URL, `password_file`, and the
    * `keep_daily`/`keep_weekly`/`keep_monthly` prune policy. Read via `backupConfig()`.
@@ -232,6 +252,40 @@ export interface CoordRunQualityConfigSource {
   digest_seed: unknown;
 }
 
+export interface LogStorageConfigLayerSource {
+  layer: "user" | "project";
+  value: unknown;
+  invalid: boolean;
+  /** Stable file signature for bounded diagnostics without retaining values. */
+  signature: string | null;
+}
+
+export interface LogStorageConfigSource {
+  layers: readonly [LogStorageConfigLayerSource, LogStorageConfigLayerSource];
+}
+
+/**
+ * Raw user and project `logs.storage` layers with their origin intact.
+ *
+ * Storage retention validates these as one fail-closed unit. It cannot use the
+ * ordinary merged reader because commands must explain whether each effective
+ * scalar came from a user class, user family, project class, or project family.
+ */
+export function logStorageConfigSource(root: string): LogStorageConfigSource {
+  const projectPath = join(root, ".harnery", "config.jsonc");
+  const user = parseConfigLayer(userConfigPath());
+  const project = parseConfigLayer(projectPath);
+  const layer = (source: ReturnType<typeof parseConfigLayer>): LogStorageConfigLayerSource => ({
+    layer: source.path_kind,
+    value: source.config.logs?.storage,
+    invalid: source.invalid,
+    signature: source.signature,
+  });
+  return {
+    layers: [layer(user), layer(project)],
+  };
+}
+
 /**
  * Effective user-plus-project `coord.run_quality` value with parse diagnostics.
  * The ordinary config reader stays fail-soft; this one lets the guard visibly
@@ -387,6 +441,28 @@ export function resolveHooksSetupHint(coordRoot?: string | null): string | null
   return typeof hint === "string" && hint.trim() ? hint.trim() : null;
 }
 
+/**
+ * One project-owned reminder that a supported prompt hook can place immediately
+ * before a model response. The value is deliberately project-only: host policy
+ * must not follow the user-global config into unrelated repositories. It is
+ * emitted directly from config and never copied into coordination state.
+ *
+ * The reminder must be one non-empty line of at most 500 characters. Invalid
+ * values fail closed to no reminder so a malformed optional setting cannot
+ * break the prompt hook.
+ */
+export function hostPromptReminder(coordRoot?: string | null): string | null {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return null;
+  const value = readProjectConfig(root).instructions?.promptReminder;
+  if (typeof value !== "string") return null;
+  const reminder = value.trim();
+  if (!reminder || reminder.length > MAX_HOST_PROMPT_REMINDER_CHARS || /[\r\n]/.test(reminder)) {
+    return null;
+  }
+  return reminder;
+}
+
 /**
  * Whether the host requires the guarded Git check at the end of tool-using
  * turns. Default false: Harnery exposes `agents status --end-turn` as a capability
@@ -531,6 +607,21 @@ export function coordFreshnessSeconds(coordRoot?: string | null): number {
   return DEFAULT_FRESHNESS_SECS;
 }
 
+/**
+ * Active-segment byte size at which the V3 event ledger rotates to a fresh
+ * epoch. Every reader validates the complete epoch, so an unbounded active
+ * segment makes each cold read (one per hook process) scale with all history.
+ * Precedence:
+ *   1. `HARNERY_EVENT_V3_ROTATE_ACTIVE_BYTES` env
+ *   2. `.harnery/config.jsonc` `events.rotate_active_bytes`
+ *   3. 33554432 (32 MiB)
+ * `0` (or a negative value) disables automatic rotation.
+ */
+export function eventLedgerRotateActiveBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return resolveEventLedgerRotateActiveBytesV3(root);
+}
+
 function parseWebPort(value: unknown, source: string): number {
   const port = typeof value === "number" ? value : Number(value);
   if (!Number.isInteger(port) || port < 1024 || port > 65535) {
@@ -612,6 +703,36 @@ export function artifactDefaultRetentionDays(coordRoot?: string | null): number
     : 3;
 }
 
+/**
+ * Whether the daily SessionStart sweep of expired artifact workspaces runs.
+ * Precedence: `HARNERY_ARTIFACT_AUTO_CLEAN` (0/false disables) ->
+ * `artifacts.auto_clean` -> enabled. The sweep only ever deletes
+ * `managed-expired` entries via the same guarded classifier as
+ * `artifacts clean --yes`.
+ */
+export function artifactAutoCleanEnabled(coordRoot?: string | null): boolean {
+  const env = coordEnv("ARTIFACT_AUTO_CLEAN");
+  if (env !== undefined) return !(env === "0" || env.toLowerCase() === "false");
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return true;
+  return readConfig(root).artifacts?.auto_clean !== false;
+}
+
+/**
+ * Sweep cadence in hours. Env-only (`HARNERY_ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS`,
+ * mainly for tests): the cadence is an implementation detail, not policy, and
+ * retention itself is quantized in whole days, so the 24h default is not a
+ * config surface.
+ */
+export function artifactAutoCleanIntervalHours(): number {
+  const env = coordEnv("ARTIFACT_AUTO_CLEAN_INTERVAL_HOURS");
+  if (env !== undefined) {
+    const n = Number(env);
+    if (Number.isFinite(n) && n > 0 && n <= 24 * 365) return n;
+  }
+  return 24;
+}
+
 /** Resolved `harn backup` defaults (restic repo/password + prune policy). */
 export interface BackupConfig {
   repo: string;

package/src/core/conversations/archive.ts

@@ -0,0 +1,237 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  appendDurableHistoryRecord,
+  type DurableHistoryFaultBoundary,
+  readDurableHistorySync,
+} from "../storage/durable-history.ts";
+import type {
+  HarneryConversationAccessMode,
+  HarneryConversationArchiveAuthorityMode,
+  HarneryConversationProvider,
+  HarneryConversationRecordV1,
+  HarneryConversationSourceSnapshot,
+} from "./contract.ts";
+import { digest, normalizeConversationRecord } from "./normalize.ts";
+
+export const HARNERY_CONVERSATION_MANIFEST_SCHEMA = "harnery.conversation-manifest/v1" as const;
+
+export interface HarneryConversationArchiveManifest {
+  schema: typeof HARNERY_CONVERSATION_MANIFEST_SCHEMA;
+  policy_version: "conversation-archive-v1";
+  provider_id: string;
+  project_scope_id: string;
+  conversation_id: string;
+  source_snapshot_id: string;
+  completeness: HarneryConversationSourceSnapshot["completeness"];
+  omissions: readonly string[];
+  record_count: number;
+  logical_bytes: number;
+  first_occurred_at?: string;
+  last_occurred_at?: string;
+  record_set_digest: `sha256:${string}`;
+  authority_mode: HarneryConversationArchiveAuthorityMode;
+  updated_at: string;
+}
+
+export interface CaptureConversationOptions {
+  coord_root: string;
+  project_scope_id: string;
+  conversation_id: string;
+  access_mode: HarneryConversationAccessMode;
+  authority_mode: HarneryConversationArchiveAuthorityMode;
+  now?: () => Date;
+  fault?: (
+    boundary:
+      | DurableHistoryFaultBoundary
+      | "after_record_append"
+      | "before_manifest_publish"
+      | "after_manifest_publish",
+  ) => void;
+}
+
+export interface CaptureConversationResult {
+  state: "disabled" | "source-only" | "captured";
+  accepted: number;
+  duplicates: number;
+  omissions: readonly string[];
+  manifest?: HarneryConversationArchiveManifest;
+}
+
+export async function captureProviderConversation(
+  provider: HarneryConversationProvider,
+  options: CaptureConversationOptions,
+): Promise<CaptureConversationResult> {
+  if (options.access_mode === "off") return result("disabled");
+  if (options.access_mode === "source") return result("source-only");
+  const objectDir = conversationArchiveDir(
+    options.coord_root,
+    provider.capabilities.provider_id,
+    options.conversation_id,
+  );
+  mkdirSync(objectDir, { recursive: true, mode: 0o700 });
+  const lease = join(objectDir, ".capture.lease");
+  try {
+    mkdirSync(lease, { mode: 0o700 });
+  } catch {
+    throw new Error(`conversation capture lease busy: ${options.conversation_id}`);
+  }
+  try {
+    const snapshot = await provider.snapshot(options.project_scope_id, options.conversation_id);
+    const existing = readConversationArchive(objectDir);
+    const seen = new Map(existing.map((record) => [record.record_id, record.content_digest]));
+    let accepted = 0;
+    let duplicates = 0;
+    const omissions = new Set(snapshot.omissions);
+    let sequence = existing.at(-1)?.sequence ?? 0;
+    for await (const native of provider.stream(options.project_scope_id, options.conversation_id)) {
+      const normalized = normalizeConversationRecord({
+        capabilities: provider.capabilities,
+        snapshot,
+        native,
+        captured_at: (options.now?.() ?? new Date()).toISOString(),
+        sequence: sequence + 1,
+      });
+      if (!normalized.record) {
+        omissions.add(normalized.omission ?? "record_excluded");
+        continue;
+      }
+      const prior = seen.get(normalized.record.record_id);
+      if (prior) {
+        if (prior !== normalized.record.content_digest) {
+          throw new Error(`conversation record collision: ${normalized.record.record_id}`);
+        }
+        duplicates += 1;
+        continue;
+      }
+      sequence += 1;
+      normalized.record.sequence = sequence;
+      appendDurableHistoryRecord(objectDir, normalized.record, {
+        max_record_bytes: 1_048_576,
+        max_segment_bytes: 8_388_608,
+        fault: options.fault,
+      });
+      options.fault?.("after_record_append");
+      seen.set(normalized.record.record_id, normalized.record.content_digest);
+      accepted += 1;
+    }
+    const records = readConversationArchive(objectDir);
+    const manifest = manifestFor(
+      records,
+      { ...snapshot, omissions: [...omissions].sort() },
+      options.authority_mode,
+      options.now?.() ?? new Date(),
+    );
+    options.fault?.("before_manifest_publish");
+    publishManifest(objectDir, manifest);
+    options.fault?.("after_manifest_publish");
+    return { state: "captured", accepted, duplicates, omissions: [...omissions].sort(), manifest };
+  } finally {
+    rmSync(lease, { recursive: true, force: true });
+  }
+}
+
+export function readConversationArchive(
+  objectDirOrCoordRoot: string,
+  providerId?: string,
+  conversationId?: string,
+): HarneryConversationRecordV1[] {
+  const objectDir =
+    providerId && conversationId
+      ? conversationArchiveDir(objectDirOrCoordRoot, providerId, conversationId)
+      : objectDirOrCoordRoot;
+  return readDurableHistorySync<HarneryConversationRecordV1>(objectDir, {
+    max_record_bytes: 1_048_576,
+    max_records: 1_000_000,
+  });
+}
+
+export function reconcileConversationArchive(input: {
+  coord_root: string;
+  provider_id: string;
+  conversation_id: string;
+  snapshot: HarneryConversationSourceSnapshot;
+  authority_mode: HarneryConversationArchiveAuthorityMode;
+  now: Date;
+}): HarneryConversationArchiveManifest {
+  const objectDir = conversationArchiveDir(
+    input.coord_root,
+    input.provider_id,
+    input.conversation_id,
+  );
+  const manifest = manifestFor(
+    readConversationArchive(objectDir),
+    input.snapshot,
+    input.authority_mode,
+    input.now,
+  );
+  publishManifest(objectDir, manifest);
+  return manifest;
+}
+
+export function loadConversationManifest(
+  coordRoot: string,
+  providerId: string,
+  conversationId: string,
+): HarneryConversationArchiveManifest | undefined {
+  const path = join(conversationArchiveDir(coordRoot, providerId, conversationId), "manifest.json");
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as HarneryConversationArchiveManifest;
+    if (parsed.schema !== HARNERY_CONVERSATION_MANIFEST_SCHEMA) throw new Error("unknown schema");
+    return parsed;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new Error(`conversation manifest invalid: ${(error as Error).message}`);
+  }
+}
+
+export function conversationArchiveDir(
+  coordRoot: string,
+  providerId: string,
+  conversationId: string,
+): string {
+  const provider = opaque(providerId);
+  const conversation = digest(`${providerId}\0${conversationId}`).slice("sha256:".length, 38);
+  return join(resolve(coordRoot), ".harnery", "conversations", provider, conversation);
+}
+
+function manifestFor(
+  records: readonly HarneryConversationRecordV1[],
+  snapshot: HarneryConversationSourceSnapshot,
+  authorityMode: HarneryConversationArchiveAuthorityMode,
+  now: Date,
+): HarneryConversationArchiveManifest {
+  return {
+    schema: HARNERY_CONVERSATION_MANIFEST_SCHEMA,
+    policy_version: "conversation-archive-v1",
+    provider_id: snapshot.provider_id,
+    project_scope_id: snapshot.project_scope_id,
+    conversation_id: snapshot.conversation_id,
+    source_snapshot_id: snapshot.snapshot_id,
+    completeness: snapshot.completeness,
+    omissions: [...snapshot.omissions],
+    record_count: records.length,
+    logical_bytes: records.reduce((sum, record) => sum + record.content_bytes, 0),
+    ...(records[0] ? { first_occurred_at: records[0].occurred_at } : {}),
+    ...(records.at(-1) ? { last_occurred_at: records.at(-1)!.occurred_at } : {}),
+    record_set_digest: digest(records.map((record) => record.record_id).join("\n")),
+    authority_mode: authorityMode,
+    updated_at: now.toISOString(),
+  };
+}
+
+function publishManifest(objectDir: string, manifest: HarneryConversationArchiveManifest): void {
+  const path = join(objectDir, "manifest.json");
+  const temp = `${path}.tmp-${process.pid}`;
+  writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+}
+
+function opaque(value: string): string {
+  if (!/^[a-z][a-z0-9-]{1,63}$/.test(value)) throw new Error(`invalid provider id: ${value}`);
+  return value;
+}
+
+function result(state: "disabled" | "source-only"): CaptureConversationResult {
+  return { state, accepted: 0, duplicates: 0, omissions: [] };
+}