harnery 0.35.0 → 0.37.0

package/src/core/events/v3/writer.ts

@@ -23,7 +23,13 @@ import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
 import { acquireNoClobberLease } from "../../workflow/workspaces/leases.ts";
 import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
 import type { EventV3 } from "./contract.ts";
+import { genesisIdFromManifestV3, liveGenesisIdV3 } from "./control.ts";
+import { advanceControlWitnessV3, readAdvanceableControlWitnessV3 } from "./control-witness.ts";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
+import {
+  type EventV3AppendValidationCheckpointV3,
+  readEventV3AppendValidationCheckpointV3,
+} from "./reader.ts";
 import { assertEventV3 } from "./validate.ts";
 
 const MAX_LINE_BYTES = 16 * 1024;
@@ -34,7 +40,7 @@ export const EVENT_V3_LEDGER_RELATIVE_ROOT = ".harnery/ledgers/v3" as const;
 export type EventV3DurabilityState = "committed" | "ready";
 
 export interface WriteEventV3Result {
-  state: EventV3DurabilityState;
+  state: EventV3DurabilityState | "epoch_replaced";
   event_id: string;
   row_digest: `sha256:${string}`;
   ready_path?: string;
@@ -50,6 +56,16 @@ export interface WriteEventV3Options {
    * the option exists for matched harness-cost experiments.
    */
   deferDrain?: boolean;
+  /**
+   * Epoch fence: the genesis id of the epoch this event was produced for.
+   * An event carries per-epoch authority (producer boot sequences start at 1
+   * and every causal link must resolve inside its own epoch), so committing
+   * it into a replaced epoch would poison the new authority. When set, the
+   * write refuses with `epoch_replaced` if the live genesis no longer
+   * matches, the spooled ready row is tagged with the id, and the drain
+   * quarantines any tagged row whose epoch has been replaced underneath it.
+   */
+  expectedGenesisId?: `gex_${string}`;
   now?: () => number;
   onStep?: (step: EventV3WriteStep, eventId?: string) => void;
 }
@@ -86,7 +102,11 @@ export function writeEventV3(
   }
   const paths = ensureEventV3Layout(coordRoot);
   const rowDigest = sha256V3(row);
-  const readyName = `${String(event.producer.sequence).padStart(16, "0")}-${event.event_id}-${rowDigest.slice(7)}.ready`;
+  if (options.expectedGenesisId && liveGenesisIdV3(coordRoot) !== options.expectedGenesisId) {
+    return { state: "epoch_replaced", event_id: event.event_id, row_digest: rowDigest };
+  }
+  const epochTag = options.expectedGenesisId ? `-${options.expectedGenesisId}` : "";
+  const readyName = `${String(event.producer.sequence).padStart(16, "0")}-${event.event_id}-${rowDigest.slice(7)}${epochTag}.ready`;
   const readyPath = join(paths.spool, readyName);
   writeReadyRecord(paths.spool, readyPath, row, event.event_id, options.onStep);
 
@@ -110,14 +130,18 @@ export function writeEventV3(
       diagnostic_code: "wal_drain_failed",
     };
   }
-  return existsSync(readyPath)
-    ? {
-        state: "ready",
-        event_id: event.event_id,
-        row_digest: rowDigest,
-        ready_path: readyPath,
-      }
-    : { state: "committed", event_id: event.event_id, row_digest: rowDigest };
+  if (existsSync(readyPath)) {
+    return {
+      state: "ready",
+      event_id: event.event_id,
+      row_digest: rowDigest,
+      ready_path: readyPath,
+    };
+  }
+  if (existsSync(`${readyPath.slice(0, -".ready".length)}.epoch-replaced`)) {
+    return { state: "epoch_replaced", event_id: event.event_id, row_digest: rowDigest };
+  }
+  return { state: "committed", event_id: event.event_id, row_digest: rowDigest };
 }
 
 /** Drain every durable ready record under the fenced append lease. */
@@ -158,16 +182,24 @@ export function drainReadyEventsUnderLeaseV3(
   paths: ReturnType<typeof eventV3Paths>,
   options: WriteEventV3Options = {},
 ): number {
+  let priorWitness = readAdvanceableControlWitnessV3(paths.coordRoot);
   if (repairUnterminatedActiveFrame(paths.active)) {
     options.onStep?.("active_tail_repaired");
+    // The repair can remove IDs that the old witness considered committed.
+    // Never use that stale checkpoint to release a dependent ready row.
+    priorWitness = undefined;
   }
   requeueCommittedReceipts(paths.spool);
   const readyNames = readdirSync(paths.spool)
     .filter((name) => name.endsWith(".ready"))
     .sort();
   if (readyNames.length === 0) return 0;
+  const drainableNames = quarantineReplacedEpochRows(paths, readyNames);
+  if (drainableNames.length === 0) return 0;
+  const checkpoint =
+    priorWitness?.checkpoint ?? readEventV3AppendValidationCheckpointV3(paths.coordRoot);
   const readyRows = causallyOrderedReadyRows(
-    readyNames.map((readyName) => {
+    drainableNames.map((readyName) => {
       const readyPath = join(paths.spool, readyName);
       const row = readAndValidateReadyRow(readyPath);
       return {
@@ -177,7 +209,9 @@ export function drainReadyEventsUnderLeaseV3(
         event: JSON.parse(row) as EventV3,
       };
     }),
+    checkpoint?.genesis_id ? checkpoint : undefined,
   );
+  if (readyRows.length === 0) return 0;
   const activeFd = openSync(paths.active, "a", 0o600);
   let committed = 0;
   try {
@@ -199,6 +233,13 @@ export function drainReadyEventsUnderLeaseV3(
   } finally {
     closeSync(activeFd);
   }
+  if (committed > 0 && priorWitness) {
+    advanceControlWitnessV3(
+      paths.coordRoot,
+      priorWitness,
+      genesisIdFromManifestV3(join(paths.root, "genesis.json")),
+    );
+  }
   return committed;
 }
 
@@ -210,11 +251,51 @@ interface ReadyEventRowV3 {
 }
 
 /**
- * Keep the spool's deterministic filename order except where a ready event
- * names another ready event as a cause. Those dependencies are committed
- * first; a cycle stays in the WAL and never poisons the active authority.
+ * Keep the spool's deterministic filename order except where an event depends
+ * on an uncommitted cause or attestation declaration. The authenticated
+ * checkpoint proves what the active authority already contains; rows whose
+ * prerequisite has not reached either the authority or this ready batch stay
+ * in the WAL. This covers the cross-process window where a dependent row is
+ * published before the row that mints its attestation.
  */
-function causallyOrderedReadyRows(rows: ReadyEventRowV3[]): ReadyEventRowV3[] {
+function causallyOrderedReadyRows(
+  rows: ReadyEventRowV3[],
+  checkpoint?: EventV3AppendValidationCheckpointV3,
+): ReadyEventRowV3[] {
+  // Bare writer fixtures and pre-genesis bootstrap rows have no semantic
+  // authority to consult. Preserve the original within-batch causal ordering;
+  // once a genesis exists, the validated checkpoint becomes the writer fence.
+  if (!checkpoint) return causallyOrderedReadyRowsWithinBatch(rows);
+
+  const pending = new Map(rows.map((row) => [row.event.event_id, row]));
+  const ordered: ReadyEventRowV3[] = [];
+  const committedEventIds = new Set(checkpoint.seen_event_ids);
+  const committedAttestationIds = new Set(checkpoint.attestation_ids);
+  while (pending.size > 0) {
+    const next = rows.find(({ event }) => {
+      const causes = (event.links as { caused_by: string[] }).caused_by;
+      return (
+        pending.has(event.event_id) &&
+        causes.every((eventId) => committedEventIds.has(eventId)) &&
+        attestationPrerequisitesV3(event).every((attestationId) =>
+          committedAttestationIds.has(attestationId),
+        )
+      );
+    });
+    if (!next) break;
+    pending.delete(next.event.event_id);
+    ordered.push(next);
+    committedEventIds.add(next.event.event_id);
+    const minted = mintedAttestationV3(next.event);
+    if (minted) committedAttestationIds.add(minted);
+  }
+  if (pending.size > 0 && dependenciesResolveInsidePendingV3(pending, committedEventIds)) {
+    throw new Error("ready V3 events contain a causal dependency cycle");
+  }
+  return ordered;
+}
+
+function causallyOrderedReadyRowsWithinBatch(rows: ReadyEventRowV3[]): ReadyEventRowV3[] {
   const pending = new Map(rows.map((row) => [row.event.event_id, row]));
   const ordered: ReadyEventRowV3[] = [];
   while (pending.size > 0) {
@@ -229,6 +310,42 @@ function causallyOrderedReadyRows(rows: ReadyEventRowV3[]): ReadyEventRowV3[] {
   return ordered;
 }
 
+function mintedAttestationV3(event: EventV3): string | undefined {
+  return event.event_type === "session.started" ||
+    event.event_type === "session.attestation_changed"
+    ? event.attestation_id
+    : undefined;
+}
+
+function attestationPrerequisitesV3(event: EventV3): string[] {
+  if (event.event_type === "session.started") return [];
+  if (event.event_type === "session.attestation_changed") {
+    return [event.payload.prior_attestation_id];
+  }
+  return event.attestation_id ? [event.attestation_id] : [];
+}
+
+function dependenciesResolveInsidePendingV3(
+  pending: Map<string, ReadyEventRowV3>,
+  committedEventIds: Set<string>,
+): boolean {
+  const pendingAttestations = new Set(
+    [...pending.values()]
+      .map(({ event }) => mintedAttestationV3(event))
+      .filter((value): value is string => value !== undefined),
+  );
+  return [...pending.values()].every(({ event }) => {
+    const causes = (event.links as { caused_by: string[] }).caused_by;
+    const causesStayInside = causes.every(
+      (eventId) => committedEventIds.has(eventId) || pending.has(eventId),
+    );
+    const attestationsStayInside = attestationPrerequisitesV3(event).every((attestationId) =>
+      pendingAttestations.has(attestationId),
+    );
+    return causesStayInside && attestationsStayInside;
+  });
+}
+
 /**
  * A `.committed` receipt is created only after the active row is flushed. If
  * the process dies before unlinking it, replaying the exact canonical row is
@@ -255,8 +372,10 @@ function requeueCommittedReceipts(spool: string): void {
 }
 
 export function eventV3Paths(coordRoot: string) {
-  const root = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT);
+  const resolvedCoordRoot = resolve(coordRoot);
+  const root = join(resolvedCoordRoot, EVENT_V3_LEDGER_RELATIVE_ROOT);
   return {
+    coordRoot: resolvedCoordRoot,
     root,
     active: join(root, "active.ndjson"),
     catalog: join(root, "catalog.json"),
@@ -378,6 +497,39 @@ function eventIdFromReadyName(name: string): string | undefined {
   return match?.[1];
 }
 
+function epochTagFromReadyName(name: string): `gex_${string}` | undefined {
+  const match = name.match(/-(gex_[0-9a-f-]{36})\.ready$/);
+  return match ? (match[1] as `gex_${string}`) : undefined;
+}
+
+/**
+ * Move every ready row tagged with a replaced epoch out of the drainable
+ * spool. A tagged row was produced for exactly one epoch; committing it into
+ * a successor would break that epoch's boot-sequence and causal-link
+ * authority, so the row is preserved beside the spool as `.epoch-replaced`
+ * evidence instead of ever reaching the active file.
+ */
+function quarantineReplacedEpochRows(
+  paths: ReturnType<typeof eventV3Paths>,
+  readyNames: string[],
+): string[] {
+  if (!readyNames.some((name) => epochTagFromReadyName(name) !== undefined)) return readyNames;
+  const liveGenesisId = genesisIdFromManifestV3(join(paths.root, "genesis.json"));
+  const drainable: string[] = [];
+  for (const name of readyNames) {
+    const tag = epochTagFromReadyName(name);
+    if (tag === undefined || tag === liveGenesisId) {
+      drainable.push(name);
+      continue;
+    }
+    const readyPath = join(paths.spool, name);
+    const quarantinePath = `${readyPath.slice(0, -".ready".length)}.epoch-replaced`;
+    renameSync(readyPath, quarantinePath);
+    fsyncParentDirectory(quarantinePath);
+  }
+  return drainable;
+}
+
 function readFileTail(fd: number, buffer: Buffer, position: number): number {
   let read = 0;
   while (read < buffer.length) {

package/src/core/governor/plan-read.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { readSegmentedJsonlFileSync } from "../storage/durable-history.ts";
 import { readWorkItem } from "../work/read.ts";
 import {
   GOVERNOR_PLAN_SCHEMA_VERSION,
@@ -29,8 +30,6 @@ const PLAN_KEY = /^[a-z][a-z0-9-]{0,31}$/;
 const TEMPLATE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const MAX_PLANS = 100;
 const MAX_RECORD_BYTES = 256 * 1024;
-const MAX_EVENTS_BYTES = 512 * 1024;
-const MAX_EVENTS = 100;
 const EVENT_TYPES = new Set<GovernorPlanEventType>([
   "plan.awaiting_approval",
   "plan.resumed",
@@ -232,22 +231,10 @@ function deriveStatus(
 }
 
 function readEvents(path: string, planId: string): GovernorPlanEvent[] {
-  if (!existsSync(path)) return [];
-  const size = statSync(path).size;
-  if (size > MAX_EVENTS_BYTES) throw new Error("governor plan events exceed their byte limit");
-  const body = readFileSync(path, "utf8");
-  if (body && !body.endsWith("\n")) throw new Error(`governor plan ${planId} has a partial event`);
-  const lines = body.split("\n").filter(Boolean);
-  if (lines.length > MAX_EVENTS) throw new Error(`governor plan exceeds ${MAX_EVENTS} events`);
-  return lines.map((line, index) => {
-    let event: GovernorPlanEvent;
-    try {
-      event = JSON.parse(line) as GovernorPlanEvent;
-    } catch (error) {
-      throw new Error(
-        `cannot parse governor plan ${planId} event ${index + 1}: ${(error as Error).message}`,
-      );
-    }
+  return readSegmentedJsonlFileSync<GovernorPlanEvent>(path, {
+    max_record_bytes: MAX_RECORD_BYTES,
+    max_records: 1_000_000,
+  }).map((event, index) => {
     validateEvent(event, planId, index + 1);
     return event;
   });

package/src/core/governor/planning.ts

@@ -1,6 +1,5 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import {
-  appendFileSync,
   chmodSync,
   existsSync,
   linkSync,
@@ -11,6 +10,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { appendSegmentedJsonlFile } from "../storage/durable-history.ts";
 import { createWorkItem, readWorkItem } from "../work/index.ts";
 import {
   digestResult,
@@ -1573,13 +1573,10 @@ function appendPlanEvent(
     actor: bounded(input.actor, "plan actor", 200),
     reason: bounded(input.reason, "plan reason", MAX_REASON),
   };
-  const line = `${JSON.stringify(event)}\n`;
-  const existing = existsSync(path) ? statSync(path).size : 0;
-  if (existing + Buffer.byteLength(line) > MAX_EVENTS_BYTES) {
-    throw new Error("governor plan event log would exceed its byte limit");
-  }
-  appendFileSync(path, line, { encoding: "utf8", mode: 0o600 });
-  chmodSync(path, 0o600);
+  appendSegmentedJsonlFile(path, event, {
+    max_record_bytes: MAX_RECORD_BYTES,
+    max_segment_bytes: MAX_EVENTS_BYTES,
+  });
 }
 
 function appendPlanEventIfMissing(

package/src/core/governor/service-read.ts

@@ -1,6 +1,12 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { coordEnv } from "../../lib/env.ts";
+import { createStorageCatalog } from "../storage/catalog.ts";
+import type { HarneryLogRecordV1 } from "../storage/jsonl.ts";
+import { parseLogRecord } from "../storage/jsonl.ts";
+import { familyLogDirectory, readSegmentManifest } from "../storage/segments.ts";
 import type {
   GovernorServiceConfig,
   GovernorServiceRuntime,
@@ -9,6 +15,7 @@ import type {
 } from "./service.ts";
 
 const MAX_FILE_BYTES = 512 * 1024;
+const MAX_LOG_RECORDS = 10_000;
 const MAX_GOALS = 100;
 const FOREIGN_STATUS_STALE_MS = 30_000;
 
@@ -81,7 +88,318 @@ export function readGovernorServiceStatus(coordRootRaw: string): GovernorService
 }
 
 export function governorServiceLogPath(coordRoot: string): string {
-  return join(serviceDir(resolve(coordRoot)), "service.log");
+  const root = resolve(coordRoot);
+  const legacy = join(serviceDir(root), "service.log");
+  if (coordEnv("SHARED_LOGS") === "0") return legacy;
+  try {
+    const family = createStorageCatalog({ coord_root: root }).require("governor-service-log");
+    const directory = familyLogDirectory(family);
+    readSegmentManifest(directory, family);
+    const active = join(directory, "active.jsonl");
+    return existsSync(active) || !existsSync(legacy) ? active : legacy;
+  } catch {
+    return legacy;
+  }
+}
+
+export interface GovernorServiceLogReadOptions {
+  max_bytes?: number;
+  max_records?: number;
+}
+
+export interface GovernorServiceLogReadResult {
+  lines: readonly string[];
+  bytes_read: number;
+  records_examined: number;
+  truncated: boolean;
+}
+
+interface GovernorLogEntry {
+  identity: string;
+  line: string;
+  timestamp?: string;
+}
+
+interface GovernorLogRead {
+  entries: GovernorLogEntry[];
+  bytes: number;
+  records: number;
+  truncated: boolean;
+}
+
+/** Read shared generations plus untouched legacy history under one aggregate budget. */
+export function readGovernorServiceLogs(
+  coordRootRaw: string,
+  options: GovernorServiceLogReadOptions = {},
+): GovernorServiceLogReadResult {
+  const coordRoot = resolve(coordRootRaw);
+  const maxBytes = options.max_bytes ?? MAX_FILE_BYTES;
+  const maxRecords = options.max_records ?? MAX_LOG_RECORDS;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error("governor service log byte budget must be a positive integer");
+  }
+  if (!Number.isSafeInteger(maxRecords) || maxRecords <= 0) {
+    throw new Error("governor service log record budget must be a positive integer");
+  }
+
+  let bytes = 0;
+  let records = 0;
+  let truncated = false;
+  const reads: GovernorLogEntry[][] = [];
+  if (coordEnv("SHARED_LOGS") !== "0") {
+    try {
+      const shared = readSharedGovernorLogs(coordRoot, maxBytes, maxRecords);
+      reads.push(shared.entries);
+      bytes += shared.bytes;
+      records += shared.records;
+      truncated ||= shared.truncated;
+    } catch {
+      // A corrupt or racing shared generation fails closed into bounded legacy history.
+      truncated = true;
+    }
+  }
+  for (const legacy of [
+    { path: join(serviceDir(coordRoot), "events.jsonl"), structured: true },
+    { path: join(serviceDir(coordRoot), "service.log"), structured: false },
+  ]) {
+    const remainingBytes = maxBytes - bytes;
+    const remainingRecords = maxRecords - records;
+    if (remainingBytes <= 0 || remainingRecords <= 0) {
+      if (existsSync(legacy.path)) truncated = true;
+      continue;
+    }
+    const read = readLegacyGovernorLog(
+      legacy.path,
+      legacy.structured,
+      remainingBytes,
+      remainingRecords,
+    );
+    reads.push(read.entries);
+    bytes += read.bytes;
+    records += read.records;
+    truncated ||= read.truncated;
+  }
+
+  const merged = new Map<string, GovernorLogEntry>();
+  for (const entries of reads) {
+    for (const entry of entries) if (!merged.has(entry.identity)) merged.set(entry.identity, entry);
+  }
+  const lines = [...merged.values()]
+    .sort(
+      (left, right) =>
+        (left.timestamp ?? "").localeCompare(right.timestamp ?? "") ||
+        left.identity.localeCompare(right.identity),
+    )
+    .map(({ line }) => line);
+  return { lines, bytes_read: bytes, records_examined: records, truncated };
+}
+
+function readSharedGovernorLogs(
+  coordRoot: string,
+  maxBytes: number,
+  maxRecords: number,
+): GovernorLogRead {
+  const family = createStorageCatalog({ coord_root: coordRoot }).require("governor-service-log");
+  const directory = familyLogDirectory(family);
+  let totalBytes = 0;
+  let totalRecords = 0;
+  let raced = false;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const remainingBytes = maxBytes - totalBytes;
+    const remainingRecords = maxRecords - totalRecords;
+    if (remainingBytes <= 0 || remainingRecords <= 0) break;
+    const manifest = readSegmentManifest(directory, family);
+    const generation = manifestGeneration(manifest);
+    const sources = [
+      ...manifest.segments.map((segment) => ({ path: join(directory, segment.file), gzip: true })),
+      { path: join(directory, "active.jsonl"), gzip: false },
+    ];
+    const read = readSharedSources(sources, remainingBytes, remainingRecords);
+    totalBytes += read.bytes;
+    totalRecords += read.records;
+    const after = readSegmentManifest(directory, family);
+    if (manifestGeneration(after) === generation) {
+      return {
+        entries: read.entries,
+        bytes: totalBytes,
+        records: totalRecords,
+        truncated: raced || read.truncated,
+      };
+    }
+    raced = true;
+  }
+  return { entries: [], bytes: totalBytes, records: totalRecords, truncated: raced };
+}
+
+function readSharedSources(
+  sources: readonly { path: string; gzip: boolean }[],
+  maxBytes: number,
+  maxRecords: number,
+): GovernorLogRead {
+  const entries: GovernorLogEntry[] = [];
+  let bytes = 0;
+  let records = 0;
+  let truncated = false;
+  for (const source of sources) {
+    if (!existsSync(source.path)) continue;
+    if (bytes >= maxBytes || records >= maxRecords) {
+      truncated = true;
+      break;
+    }
+    const body = readBoundedSource(source.path, source.gzip, maxBytes - bytes, false);
+    bytes += body.bytes;
+    truncated ||= body.truncated;
+    for (const line of completeLines(body.body, false)) {
+      if (records >= maxRecords) {
+        truncated = true;
+        break;
+      }
+      records += 1;
+      try {
+        entries.push(normalizeSharedGovernorRecord(parseLogRecord(line)));
+      } catch {
+        // Malformed rows count against the source budget but cannot poison the readable tail.
+      }
+    }
+  }
+  return { entries, bytes, records, truncated };
+}
+
+function readLegacyGovernorLog(
+  path: string,
+  structured: boolean,
+  maxBytes: number,
+  maxRecords: number,
+): GovernorLogRead {
+  if (!existsSync(path)) return { entries: [], bytes: 0, records: 0, truncated: false };
+  const source = readBoundedSource(path, false, maxBytes, true);
+  const entries: GovernorLogEntry[] = [];
+  let records = 0;
+  let truncated = source.truncated;
+  for (const line of completeLines(source.body, source.truncated)) {
+    if (records >= maxRecords) {
+      truncated = true;
+      break;
+    }
+    records += 1;
+    if (!structured) {
+      entries.push({ identity: `text:${line}`, line });
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (isRecord(parsed)) entries.push(normalizeLegacyGovernorRecord(parsed));
+    } catch {
+      // Malformed legacy lines stay excluded while consuming their source budget.
+    }
+  }
+  return { entries, bytes: source.bytes, records, truncated };
+}
+
+function readBoundedSource(
+  path: string,
+  gzip: boolean,
+  maxBytes: number,
+  tail: boolean,
+): { body: string; bytes: number; truncated: boolean } {
+  if (maxBytes <= 0) return { body: "", bytes: 0, truncated: true };
+  const size = statSync(path).size;
+  if (size <= 0) return { body: "", bytes: 0, truncated: false };
+  if (gzip) {
+    if (size > maxBytes) return { body: "", bytes: maxBytes, truncated: true };
+    try {
+      const output = gunzipSync(readFileSync(path), { maxOutputLength: maxBytes });
+      return {
+        body: output.toString("utf8"),
+        bytes: Math.max(size, output.byteLength),
+        truncated: false,
+      };
+    } catch {
+      return { body: "", bytes: maxBytes, truncated: true };
+    }
+  }
+  const length = Math.min(size, maxBytes);
+  const buffer = Buffer.allocUnsafe(length);
+  const descriptor = openSync(path, "r");
+  try {
+    const bytes = readSync(descriptor, buffer, 0, length, tail ? size - length : 0);
+    return {
+      body: buffer.subarray(0, bytes).toString("utf8"),
+      bytes,
+      truncated: size > bytes,
+    };
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function completeLines(body: string, truncatedPrefix: boolean): string[] {
+  const start = truncatedPrefix ? body.indexOf("\n") + 1 : 0;
+  const end = body.lastIndexOf("\n");
+  if (start < 0 || end < start) return [];
+  return body.slice(start, end).split("\n").filter(Boolean);
+}
+
+function normalizeSharedGovernorRecord(record: HarneryLogRecordV1): GovernorLogEntry {
+  if (record.family_id !== "governor-service-log") throw new Error("wrong governor log family");
+  const payload = {
+    ...Object.fromEntries(
+      Object.entries(record.fields).map(([key, value]) => [key, parseJsonField(value)]),
+    ),
+    ts: record.emitted_at,
+    event: record.event,
+  };
+  return normalizedGovernorEntry(payload);
+}
+
+function normalizeLegacyGovernorRecord(record: Record<string, unknown>): GovernorLogEntry {
+  const { schema_version: _schemaVersion, ...payload } = record;
+  return normalizedGovernorEntry(payload);
+}
+
+function normalizedGovernorEntry(payload: Record<string, unknown>): GovernorLogEntry {
+  const identity = stableJson(payload);
+  return {
+    identity,
+    line: JSON.stringify(payload),
+    ...(typeof payload.ts === "string" ? { timestamp: payload.ts } : {}),
+  };
+}
+
+function parseJsonField(value: unknown): unknown {
+  if (typeof value !== "string" || (!value.startsWith("[") && !value.startsWith("{"))) {
+    return value;
+  }
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+function manifestGeneration(manifest: {
+  next_sequence: number;
+  segments: readonly { file: string; sha256: string }[];
+}): string {
+  return JSON.stringify([
+    manifest.next_sequence,
+    manifest.segments.map((segment) => [segment.file, segment.sha256]),
+  ]);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function readStatusRecord(coordRoot: string): GovernorServiceStatusRecord | undefined {