harnery 0.35.0 → 0.37.0

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,31 @@ 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;
+    archive_max_bytes?: number;
+    archive_max_age_days?: number;
+    archive_keep_min?: number;
+    archive_auto_clean?: boolean;
+  };
   /**
    * 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;
+    max_bytes?: number;
+    max_unit_bytes?: number;
+  };
   /**
    * `harn backup` (restic) defaults: `repo` path/URL, `password_file`, and the
    * `keep_daily`/`keep_weekly`/`keep_monthly` prune policy. Read via `backupConfig()`.
@@ -232,6 +263,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 +452,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 +618,66 @@ 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);
+}
+
+const DEFAULT_EVENT_ARCHIVE_MAX_BYTES = 1024 * 1024 * 1024;
+const DEFAULT_EVENT_ARCHIVE_MAX_AGE_DAYS = 7;
+const DEFAULT_EVENT_ARCHIVE_KEEP_MIN = 2;
+
+export interface EventLedgerArchivePolicy {
+  maxBytes: number;
+  maxAgeDays: number;
+  keepMin: number;
+  autoClean: boolean;
+}
+
+/** Bounded retention for closed V3 epochs under `ledgers/v3-archives`. */
+export function eventLedgerArchivePolicy(coordRoot?: string | null): EventLedgerArchivePolicy {
+  const root = coordRoot ?? findCoordRoot();
+  const configured = root ? readConfig(root).events : undefined;
+  return {
+    maxBytes: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_MAX_BYTES"),
+      configured?.archive_max_bytes,
+      64 * 1024 * 1024,
+      1024 * 1024 * 1024 * 1024,
+      DEFAULT_EVENT_ARCHIVE_MAX_BYTES,
+    ),
+    maxAgeDays: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_MAX_AGE_DAYS"),
+      configured?.archive_max_age_days,
+      1,
+      3650,
+      DEFAULT_EVENT_ARCHIVE_MAX_AGE_DAYS,
+    ),
+    keepMin: integerSetting(
+      coordEnv("EVENT_V3_ARCHIVE_KEEP_MIN"),
+      configured?.archive_keep_min,
+      1,
+      1000,
+      DEFAULT_EVENT_ARCHIVE_KEEP_MIN,
+    ),
+    autoClean: booleanSetting(
+      coordEnv("EVENT_V3_ARCHIVE_AUTO_CLEAN"),
+      configured?.archive_auto_clean,
+      true,
+    ),
+  };
+}
+
 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 +759,89 @@ export function artifactDefaultRetentionDays(coordRoot?: string | null): number
     : 3;
 }
 
+const DEFAULT_ARTIFACT_MAX_BYTES = 20 * 1024 * 1024 * 1024;
+const DEFAULT_ARTIFACT_MAX_UNIT_BYTES = 1024 * 1024 * 1024;
+
+/** Soft repository budget for managed working artifacts. */
+export function artifactMaxBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MAX_BYTES"),
+    root ? readConfig(root).artifacts?.max_bytes : undefined,
+    64 * 1024 * 1024,
+    1024 * 1024 * 1024 * 1024,
+    DEFAULT_ARTIFACT_MAX_BYTES,
+  );
+}
+
+/** Size at which one bundle requires an explicit `artifacts create --big` acknowledgement. */
+export function artifactMaxUnitBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MAX_UNIT_BYTES"),
+    root ? readConfig(root).artifacts?.max_unit_bytes : undefined,
+    16 * 1024 * 1024,
+    1024 * 1024 * 1024 * 1024,
+    DEFAULT_ARTIFACT_MAX_UNIT_BYTES,
+  );
+}
+
+/**
+ * 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;
+}
+
+function integerSetting(
+  envValue: string | undefined,
+  configured: unknown,
+  minimum: number,
+  maximum: number,
+  fallback: number,
+): number {
+  for (const value of [envValue, configured]) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum) return parsed;
+  }
+  return fallback;
+}
+
+function booleanSetting(
+  envValue: string | undefined,
+  configured: unknown,
+  fallback: boolean,
+): boolean {
+  if (envValue !== undefined) {
+    if (envValue === "1" || envValue.toLowerCase() === "true") return true;
+    if (envValue === "0" || envValue.toLowerCase() === "false") return false;
+  }
+  return typeof configured === "boolean" ? configured : fallback;
+}
+
 /** 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: [] };
+}

package/src/core/conversations/catalog.ts

@@ -0,0 +1,79 @@
+import type { HarneryConversationProvider } from "./contract.ts";
+
+export class HarneryConversationCatalog {
+  readonly #providers: ReadonlyMap<string, HarneryConversationProvider>;
+
+  constructor(providers: readonly HarneryConversationProvider[]) {
+    const entries = new Map<string, HarneryConversationProvider>();
+    for (const provider of providers) {
+      const id = provider.capabilities.provider_id;
+      if (!/^[a-z][a-z0-9-]{1,63}$/.test(id))
+        throw new Error(`invalid conversation provider id: ${id}`);
+      if (entries.has(id)) throw new Error(`duplicate conversation provider: ${id}`);
+      if (provider.capabilities.roles.some((role) => role !== "user" && role !== "assistant")) {
+        throw new Error(`provider ${id} exposes an excluded role`);
+      }
+      entries.set(id, Object.freeze(provider));
+    }
+    this.#providers = entries;
+  }
+
+  get(id: string): HarneryConversationProvider | undefined {
+    return this.#providers.get(id);
+  }
+
+  require(id: string): HarneryConversationProvider {
+    const provider = this.get(id);
+    if (!provider) throw new Error(`unknown conversation provider: ${id}`);
+    return provider;
+  }
+
+  list(): readonly HarneryConversationProvider[] {
+    return [...this.#providers.values()].sort((left, right) =>
+      left.capabilities.provider_id.localeCompare(right.capabilities.provider_id),
+    );
+  }
+}
+
+export function unavailableAdapterProviders(): readonly HarneryConversationProvider[] {
+  return ["claude-code", "codex", "cursor"].map((providerId) => ({
+    capabilities: {
+      provider_id: providerId,
+      roles: ["user", "assistant"] as const,
+      can_list: false,
+      can_stream_source: false,
+      can_replay_archive: false,
+      default_completeness: "unavailable" as const,
+      default_omissions: [
+        "adapter-native source reader is not registered by this host",
+        "system, developer, tool, reasoning, command, and attachment bodies are excluded",
+      ],
+      retention_behavior: "adapter-owned and unavailable to portable core",
+    },
+    async list() {
+      return [];
+    },
+    async snapshot(projectScopeId: string, conversationId: string) {
+      return {
+        snapshot_id: `${providerId}:unavailable:${conversationId}`,
+        provider_id: providerId,
+        project_scope_id: projectScopeId,
+        conversation_id: conversationId,
+        observed_at: new Date().toISOString(),
+        completeness: "unavailable" as const,
+        omissions: ["adapter-native source unavailable"],
+      };
+    },
+    stream() {
+      return {
+        [Symbol.asyncIterator]() {
+          return {
+            async next(): Promise<IteratorResult<never>> {
+              throw new Error(`conversation provider unavailable: ${providerId}`);
+            },
+          };
+        },
+      };
+    },
+  }));
+}

package/src/core/conversations/context-pack.ts

@@ -0,0 +1,72 @@
+import type { HarneryConversationContextPack, HarneryConversationQueryResult } from "./contract.ts";
+
+export function buildConversationContextPack(
+  result: HarneryConversationQueryResult,
+  budget: { max_tokens: number; max_bytes: number },
+): HarneryConversationContextPack {
+  if (
+    !Number.isSafeInteger(budget.max_tokens) ||
+    budget.max_tokens <= 0 ||
+    !Number.isSafeInteger(budget.max_bytes) ||
+    budget.max_bytes <= 0
+  ) {
+    throw new Error("invalid conversation context budget");
+  }
+  const ordered = new Map(
+    result.hits
+      .flatMap((hit) => [...hit.neighbors, hit.record])
+      .sort(
+        (left, right) =>
+          left.provider_id.localeCompare(right.provider_id) ||
+          left.conversation_id.localeCompare(right.conversation_id) ||
+          left.sequence - right.sequence,
+      )
+      .map((record) => [record.record_id, record]),
+  );
+  const excerpts: HarneryConversationContextPack["excerpts"][number][] = [];
+  let bytes = 0;
+  let tokens = 0;
+  let truncated = result.truncated;
+  for (const record of ordered.values()) {
+    const recordBytes = Buffer.byteLength(record.content);
+    const recordTokens = Math.ceil(recordBytes / 4);
+    if (bytes + recordBytes > budget.max_bytes || tokens + recordTokens > budget.max_tokens) {
+      truncated = true;
+      break;
+    }
+    excerpts.push({
+      citation: {
+        record_id: record.record_id,
+        provider_id: record.provider_id,
+        conversation_id: record.conversation_id,
+        role: record.role,
+        occurred_at: record.occurred_at,
+        native_conversation_id: record.source.native_conversation_id,
+        ...(record.source.native_record_id
+          ? { native_record_id: record.source.native_record_id }
+          : {}),
+        content_digest: record.content_digest,
+      },
+      content: record.content,
+      sequence: record.sequence,
+    });
+    bytes += recordBytes;
+    tokens += recordTokens;
+  }
+  return {
+    schema: "harnery.conversation-context-pack/v1",
+    boundary: "untrusted-historical-data",
+    automatic_injection: false,
+    project_scope_id: result.request.project_scope_id,
+    excerpts,
+    completeness: result.snapshots.map((snapshot) => ({
+      provider_id: snapshot.provider_id,
+      conversation_id: snapshot.conversation_id,
+      completeness: snapshot.completeness,
+      omissions: snapshot.omissions,
+    })),
+    bytes,
+    estimated_tokens: tokens,
+    truncated,
+  };
+}