harnery 0.34.1 → 0.36.0

package/src/core/conversations/query.ts

@@ -0,0 +1,318 @@
+import type { HarneryConversationCatalog } from "./catalog.ts";
+import type {
+  HarneryConversationCitation,
+  HarneryConversationQueryHit,
+  HarneryConversationQueryRequest,
+  HarneryConversationQueryResult,
+  HarneryConversationRecordV1,
+  HarneryConversationSourceSnapshot,
+  HarneryConversationSummary,
+  HarneryNativeConversationRecord,
+} from "./contract.ts";
+import { normalizeConversationRecord } from "./normalize.ts";
+
+export async function queryConversationCatalog(
+  catalog: HarneryConversationCatalog,
+  request: HarneryConversationQueryRequest,
+): Promise<HarneryConversationQueryResult> {
+  validateRequest(request);
+  const started = performance.now();
+  const deadline = started + request.budgets.max_wall_ms;
+  const controller = new AbortController();
+  const records: HarneryConversationRecordV1[] = [];
+  const snapshots: HarneryConversationSourceSnapshot[] = [];
+  let decodedBytes = 0;
+  let sourceRecords = 0;
+  let sourceTruncation: HarneryConversationQueryResult["truncation_reason"];
+  const providers = request.provider_id ? [catalog.require(request.provider_id)] : catalog.list();
+  try {
+    providerLoop: for (const provider of providers) {
+      if (!provider.capabilities.can_list || !provider.capabilities.can_stream_source) continue;
+      if (deadlineExpired(deadline)) {
+        sourceTruncation = "wall_budget";
+        break;
+      }
+      let summaries: readonly HarneryConversationSummary[];
+      try {
+        summaries = await beforeDeadline(
+          provider.list(request.project_scope_id, { signal: controller.signal }),
+          deadline,
+          controller,
+        );
+      } catch (error) {
+        if (!isWallBudgetError(error)) throw error;
+        sourceTruncation = "wall_budget";
+        break;
+      }
+      for (const summary of summaries) {
+        if (deadlineExpired(deadline)) {
+          controller.abort();
+          sourceTruncation = "wall_budget";
+          break providerLoop;
+        }
+        if (summary.project_scope_id !== request.project_scope_id) continue;
+        if (request.conversation_id && summary.conversation_id !== request.conversation_id)
+          continue;
+        let snapshot: HarneryConversationSourceSnapshot;
+        try {
+          snapshot = await beforeDeadline(
+            provider.snapshot(request.project_scope_id, summary.conversation_id, {
+              signal: controller.signal,
+            }),
+            deadline,
+            controller,
+          );
+        } catch (error) {
+          if (!isWallBudgetError(error)) throw error;
+          sourceTruncation = "wall_budget";
+          break providerLoop;
+        }
+        snapshots.push(snapshot);
+        let sequence = 0;
+        const iterator = provider
+          .stream(request.project_scope_id, summary.conversation_id, {
+            signal: controller.signal,
+          })
+          [Symbol.asyncIterator]();
+        let iteratorCompleted = false;
+        try {
+          while (true) {
+            if (sourceRecords >= request.budgets.max_source_records) {
+              sourceTruncation = "record_budget";
+              break;
+            }
+            let next: IteratorResult<HarneryNativeConversationRecord>;
+            try {
+              next = await beforeDeadline(iterator.next(), deadline, controller);
+            } catch (error) {
+              if (!isWallBudgetError(error)) throw error;
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            if (next.done) {
+              iteratorCompleted = true;
+              break;
+            }
+            sourceRecords += 1;
+            sequence += 1;
+            const native = next.value;
+            const rawBytes =
+              typeof native.content === "string" ? Buffer.byteLength(native.content) : 0;
+            if (decodedBytes + rawBytes > request.budgets.max_decoded_bytes) {
+              sourceTruncation = "byte_budget";
+              break;
+            }
+            if (deadlineExpired(deadline)) {
+              controller.abort();
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            const normalized = normalizeConversationRecord({
+              capabilities: provider.capabilities,
+              snapshot,
+              native,
+              captured_at: snapshot.observed_at,
+              sequence,
+            });
+            decodedBytes += rawBytes;
+            if (deadlineExpired(deadline)) {
+              controller.abort();
+              sourceTruncation = "wall_budget";
+              break;
+            }
+            if (normalized.record) records.push(normalized.record);
+          }
+        } finally {
+          if (!iteratorCompleted) requestIteratorReturn(iterator);
+        }
+        if (sourceTruncation) break providerLoop;
+      }
+    }
+  } finally {
+    if (sourceTruncation) controller.abort();
+  }
+  const result = queryConversationRecords(records, snapshots, request, { started_at: started });
+  if (!sourceTruncation || result.truncated) return result;
+  return { ...result, truncated: true, truncation_reason: sourceTruncation };
+}
+
+class ConversationWallBudgetError extends Error {}
+
+async function beforeDeadline<T>(
+  operation: Promise<T>,
+  deadline: number,
+  controller: AbortController,
+): Promise<T> {
+  const remaining = deadline - performance.now();
+  if (remaining <= 0) {
+    controller.abort();
+    throw new ConversationWallBudgetError();
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new ConversationWallBudgetError());
+      }, remaining);
+    });
+    const result = await Promise.race([operation, timeout]);
+    if (deadlineExpired(deadline)) {
+      controller.abort();
+      throw new ConversationWallBudgetError();
+    }
+    return result;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+function deadlineExpired(deadline: number): boolean {
+  return performance.now() >= deadline;
+}
+
+function isWallBudgetError(error: unknown): error is ConversationWallBudgetError {
+  return error instanceof ConversationWallBudgetError;
+}
+
+function requestIteratorReturn<T>(iterator: AsyncIterator<T>): void {
+  try {
+    const returned = iterator.return?.();
+    if (returned) void Promise.resolve(returned).catch(() => undefined);
+  } catch {
+    // A provider cleanup failure cannot widen the query budget or replace its reason code.
+  }
+}
+
+export function queryConversationRecords(
+  inputRecords: readonly HarneryConversationRecordV1[],
+  snapshots: readonly HarneryConversationSourceSnapshot[],
+  request: HarneryConversationQueryRequest,
+  internal: { started_at?: number } = {},
+): HarneryConversationQueryResult {
+  validateRequest(request);
+  const started = internal.started_at ?? performance.now();
+  const records = [...inputRecords].sort(
+    (left, right) =>
+      left.project_scope_id.localeCompare(right.project_scope_id) ||
+      left.provider_id.localeCompare(right.provider_id) ||
+      left.conversation_id.localeCompare(right.conversation_id) ||
+      left.sequence - right.sequence ||
+      left.record_id.localeCompare(right.record_id),
+  );
+  const regex = request.regex
+    ? compileRegex(request.regex, request.budgets.max_regex_chars)
+    : undefined;
+  const hits: HarneryConversationQueryHit[] = [];
+  let scannedRecords = 0;
+  let decodedBytes = 0;
+  let truncation: HarneryConversationQueryResult["truncation_reason"];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]!;
+    if (!structuredMatch(record, request)) continue;
+    if (scannedRecords >= request.budgets.max_source_records) {
+      truncation = "record_budget";
+      break;
+    }
+    if (decodedBytes + record.content_bytes > request.budgets.max_decoded_bytes) {
+      truncation = "byte_budget";
+      break;
+    }
+    if (performance.now() - started > request.budgets.max_wall_ms) {
+      truncation = "wall_budget";
+      break;
+    }
+    scannedRecords += 1;
+    decodedBytes += record.content_bytes;
+    if (request.text && !record.content.includes(request.text)) continue;
+    if (regex && !regex.test(record.content)) continue;
+    if (hits.length >= Math.min(request.limit, request.budgets.max_matches)) {
+      truncation = "match_budget";
+      break;
+    }
+    hits.push({
+      record,
+      citation: citation(record),
+      neighbors: neighbors(records, index, request.context_before ?? 0, request.context_after ?? 0),
+    });
+  }
+  return {
+    schema: "harnery.conversation-query/v1",
+    request,
+    hits,
+    scanned_records: scannedRecords,
+    decoded_bytes: decodedBytes,
+    truncated: truncation !== undefined,
+    ...(truncation ? { truncation_reason: truncation } : {}),
+    snapshots: [...snapshots].sort((left, right) =>
+      left.snapshot_id.localeCompare(right.snapshot_id),
+    ),
+  };
+}
+
+export function citation(record: HarneryConversationRecordV1): HarneryConversationCitation {
+  return {
+    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,
+  };
+}
+
+function structuredMatch(
+  record: HarneryConversationRecordV1,
+  request: HarneryConversationQueryRequest,
+): boolean {
+  return (
+    record.project_scope_id === request.project_scope_id &&
+    (!request.provider_id || record.provider_id === request.provider_id) &&
+    (!request.role || record.role === request.role) &&
+    (!request.session_id || record.session_id === request.session_id) &&
+    (!request.conversation_id || record.conversation_id === request.conversation_id) &&
+    (!request.record_id || record.record_id === request.record_id) &&
+    (!request.since || record.occurred_at >= new Date(request.since).toISOString()) &&
+    (!request.until || record.occurred_at <= new Date(request.until).toISOString())
+  );
+}
+
+function neighbors(
+  records: readonly HarneryConversationRecordV1[],
+  index: number,
+  before: number,
+  after: number,
+): HarneryConversationRecordV1[] {
+  const target = records[index]!;
+  return records
+    .slice(Math.max(0, index - before), index + after + 1)
+    .filter(
+      (record) =>
+        record.record_id !== target.record_id &&
+        record.project_scope_id === target.project_scope_id &&
+        record.provider_id === target.provider_id &&
+        record.conversation_id === target.conversation_id,
+    );
+}
+
+function compileRegex(pattern: string, maxChars: number): RegExp {
+  if (pattern.length === 0 || pattern.length > maxChars)
+    throw new Error("conversation regex limit");
+  if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern)) throw new Error("unsafe nested conversation regex");
+  return new RegExp(pattern, "iu");
+}
+
+function validateRequest(request: HarneryConversationQueryRequest): void {
+  if (!request.project_scope_id) throw new Error("conversation query requires project_scope_id");
+  for (const [field, value] of Object.entries({ limit: request.limit, ...request.budgets })) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+      throw new Error(`invalid conversation ${field}`);
+  }
+  if (request.role && request.role !== "user" && request.role !== "assistant") {
+    throw new Error("excluded conversation role");
+  }
+  if (request.text && request.regex)
+    throw new Error("conversation query accepts text or regex, not both");
+}

package/src/core/conversations/search-index.ts

@@ -0,0 +1,48 @@
+import type { HarneryConversationRecordV1 } from "./contract.ts";
+import { digest } from "./normalize.ts";
+
+export interface HarneryConversationSearchIndexV1 {
+  schema: "harnery.conversation-search-index/v1";
+  source_digest: `sha256:${string}`;
+  terms: Readonly<Record<string, readonly string[]>>;
+}
+
+export function buildConversationSearchIndex(
+  records: readonly HarneryConversationRecordV1[],
+): HarneryConversationSearchIndexV1 {
+  const terms = new Map<string, Set<string>>();
+  const ordered = [...records].sort((left, right) => left.record_id.localeCompare(right.record_id));
+  for (const record of ordered) {
+    for (const term of record.content.toLocaleLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) ?? []) {
+      const ids = terms.get(term) ?? new Set<string>();
+      ids.add(record.record_id);
+      terms.set(term, ids);
+    }
+  }
+  return {
+    schema: "harnery.conversation-search-index/v1",
+    source_digest: digest(
+      ordered.map((record) => `${record.record_id}:${record.content_digest}`).join("\n"),
+    ),
+    terms: Object.fromEntries(
+      [...terms]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([term, ids]) => [term, [...ids].sort()]),
+    ),
+  };
+}
+
+export function verifyIndexedRecords(
+  index: HarneryConversationSearchIndexV1,
+  records: readonly HarneryConversationRecordV1[],
+  term: string,
+): HarneryConversationRecordV1[] {
+  const byId = new Map(records.map((record) => [record.record_id, record]));
+  return (index.terms[term.toLocaleLowerCase()] ?? []).map((id) => {
+    const record = byId.get(id);
+    if (!record?.content.toLocaleLowerCase().includes(term.toLocaleLowerCase())) {
+      throw new Error(`stale conversation index hit: ${id}`);
+    }
+    return record;
+  });
+}

package/src/core/events/legacy-storage/canary.ts

@@ -0,0 +1,177 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import { canonicalJsonV3 } from "../v3/canonical.ts";
+import { verifyLegacyV1HardFence } from "./fence.ts";
+import { type LegacyV1SegmentManifest, validateLegacyV1SegmentManifest } from "./manifest.ts";
+import { streamLegacyV1Rows } from "./reader.ts";
+
+export interface LegacyV1CanaryResult {
+  manifest: LegacyV1SegmentManifest;
+  manifest_path: string;
+  payload_path: string;
+  source_unchanged: true;
+  replacement_enabled: false;
+}
+
+/** Shadow-compress one fenced legacy segment, then prove byte and row parity. */
+export async function writeLegacyV1Canary(input: {
+  coord_root: string;
+  source_filename: string;
+  output_directory: string;
+  minimum_harnery_version: string;
+  created_at: string;
+}): Promise<LegacyV1CanaryResult> {
+  await verifyLegacyV1HardFence(input.coord_root);
+  if (
+    !/^events.+\.ndjson$/.test(input.source_filename) ||
+    input.source_filename.includes("/") ||
+    input.source_filename.includes("\\")
+  ) {
+    throw new Error("legacy_v1_canary_source_name_invalid");
+  }
+  const harnery = resolve(input.coord_root, ".harnery");
+  const source = join(harnery, input.source_filename);
+  const sourceStat = await lstat(source);
+  if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+    throw new Error("legacy_v1_canary_source_not_regular");
+  }
+  const sourceDigest = await hashFile(source);
+  const sourceFacts = await inspectRows(source);
+  const segmentId = `v1s_${createHash("sha256")
+    .update(`${input.source_filename}\0${sourceStat.size}\0${sourceDigest}`)
+    .digest("hex")
+    .slice(0, 32)}` as const;
+  const outputDirectory = resolve(input.output_directory);
+  await mkdir(outputDirectory, { recursive: true, mode: 0o700 });
+  await chmod(outputDirectory, 0o700);
+  const payloadPath = join(outputDirectory, `${segmentId}.ndjson.gz`);
+  const manifestPath = join(outputDirectory, `${segmentId}.manifest.json`);
+  const partialPayload = `${payloadPath}.partial`;
+  const partialManifest = `${manifestPath}.partial`;
+  await rejectExisting([payloadPath, manifestPath, partialPayload, partialManifest]);
+  try {
+    await pipeline(
+      createReadStream(source),
+      createGzip({ level: 9 }),
+      createWriteStream(partialPayload, { flags: "wx", mode: 0o600 }),
+    );
+    await rename(partialPayload, payloadPath);
+    const payloadStat = await lstat(payloadPath);
+    const manifest = validateLegacyV1SegmentManifest({
+      format: "harnery-legacy-v1-segment",
+      format_version: 1,
+      segment_id: segmentId,
+      source: {
+        filename: input.source_filename,
+        bytes: sourceStat.size,
+        digest: sourceDigest,
+        row_count: sourceFacts.rows,
+        minimum_recorded_at: sourceFacts.minimum,
+        maximum_recorded_at: sourceFacts.maximum,
+      },
+      payload: {
+        algorithm: "gzip",
+        path: basename(payloadPath),
+        bytes: payloadStat.size,
+        digest: await hashFile(payloadPath),
+      },
+      minimum_harnery_version: input.minimum_harnery_version,
+      created_at: input.created_at,
+    });
+    const handle = await open(
+      partialManifest,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+      0o600,
+    );
+    try {
+      await handle.writeFile(`${canonicalJsonV3(manifest)}\n`, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(partialManifest, manifestPath);
+    await proveRowParity(source, manifestPath);
+    const after = await lstat(source);
+    if (after.size !== sourceStat.size || (await hashFile(source)) !== sourceDigest) {
+      throw new Error("legacy_v1_canary_source_changed");
+    }
+    return {
+      manifest,
+      manifest_path: manifestPath,
+      payload_path: payloadPath,
+      source_unchanged: true,
+      replacement_enabled: false,
+    };
+  } catch (error) {
+    await rm(partialPayload, { force: true });
+    await rm(partialManifest, { force: true });
+    await rm(payloadPath, { force: true });
+    await rm(manifestPath, { force: true });
+    throw error;
+  }
+}
+
+export function activateLegacyV1CanaryReplacement(): never {
+  throw new Error("legacy_v1_replacement_activation_disabled");
+}
+
+async function inspectRows(
+  path: string,
+): Promise<{ rows: number; minimum: string | null; maximum: string | null }> {
+  let rows = 0;
+  const timestamps: string[] = [];
+  for await (const row of streamLegacyV1Rows(path)) {
+    rows += 1;
+    const value = JSON.parse(row.bytes.toString("utf8")) as Record<string, unknown>;
+    const candidate =
+      typeof value.at === "string"
+        ? value.at
+        : typeof value.timestamp === "string"
+          ? value.timestamp
+          : value.time &&
+              typeof value.time === "object" &&
+              typeof (value.time as Record<string, unknown>).observed_at === "string"
+            ? ((value.time as Record<string, unknown>).observed_at as string)
+            : undefined;
+    if (candidate && Number.isFinite(Date.parse(candidate)))
+      timestamps.push(new Date(candidate).toISOString());
+  }
+  timestamps.sort();
+  return { rows, minimum: timestamps[0] ?? null, maximum: timestamps.at(-1) ?? null };
+}
+
+async function proveRowParity(loose: string, manifest: string): Promise<void> {
+  const left = streamLegacyV1Rows(loose)[Symbol.asyncIterator]();
+  const right = streamLegacyV1Rows(manifest)[Symbol.asyncIterator]();
+  while (true) {
+    const [looseRow, packedRow] = await Promise.all([left.next(), right.next()]);
+    if (looseRow.done || packedRow.done) {
+      if (looseRow.done !== packedRow.done) throw new Error("legacy_v1_canary_row_count_mismatch");
+      break;
+    }
+    if (!looseRow.value.bytes.equals(packedRow.value.bytes)) {
+      throw new Error(`legacy_v1_canary_row_mismatch:${looseRow.value.row_number}`);
+    }
+  }
+}
+
+async function hashFile(path: string): Promise<`sha256:${string}`> {
+  const hash = createHash("sha256");
+  for await (const current of createReadStream(path)) hash.update(current as Buffer);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+async function rejectExisting(paths: string[]): Promise<void> {
+  for (const path of paths) {
+    try {
+      await lstat(path);
+      throw new Error("legacy_v1_canary_output_exists");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}

package/src/core/events/legacy-storage/fence.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { canonicalJsonV3 } from "../v3/canonical.ts";
+
+export interface LegacyV1HardFence {
+  manifest_version: 1;
+  kind: "v1_hard_path_fence";
+  terminal_archive: string;
+  terminal_digest: `sha256:${string}`;
+}
+
+export interface VerifiedLegacyV1HardFence {
+  fence_directory: string;
+  marker_path: string;
+  terminal_archive_path: string;
+  marker: LegacyV1HardFence;
+}
+
+const MARKER = "V1-SEALED.json";
+const LEGACY_ACTIVE_NAME = ["events", "ndjson"].join(".");
+
+/** Verify the exact read-only V1 path fence and its terminal sealed segment. */
+export async function verifyLegacyV1HardFence(
+  coordRoot: string,
+): Promise<VerifiedLegacyV1HardFence> {
+  const root = resolve(coordRoot);
+  const harnery = join(root, ".harnery");
+  const harneryStat = await lstat(harnery);
+  if (!harneryStat.isDirectory() || harneryStat.isSymbolicLink()) {
+    throw new Error("legacy_v1_harnery_root_invalid");
+  }
+  const harneryReal = await realpath(harnery);
+  const fence = join(harnery, LEGACY_ACTIVE_NAME);
+  let fenceStat: Awaited<ReturnType<typeof lstat>>;
+  try {
+    fenceStat = await lstat(fence);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error("legacy_v1_hard_fence_missing");
+    }
+    throw error;
+  }
+  if (!fenceStat.isDirectory() || fenceStat.isSymbolicLink()) {
+    throw new Error("legacy_v1_active_file_present_or_fence_invalid");
+  }
+  if ((fenceStat.mode & 0o222) !== 0) throw new Error("legacy_v1_hard_fence_is_writable");
+  const fenceReal = await realpath(fence);
+  if (relative(harneryReal, fenceReal).startsWith(".."))
+    throw new Error("legacy_v1_hard_fence_escape");
+  const names = (await readdir(fence)).sort();
+  if (names.length !== 1 || names[0] !== MARKER) throw new Error("legacy_v1_hard_fence_not_exact");
+
+  const markerPath = join(fence, MARKER);
+  const markerStat = await lstat(markerPath);
+  if (!markerStat.isFile() || markerStat.isSymbolicLink()) {
+    throw new Error("legacy_v1_hard_fence_marker_invalid");
+  }
+  if ((markerStat.mode & 0o222) !== 0) throw new Error("legacy_v1_hard_fence_marker_writable");
+  if (markerStat.size > 64 * 1024) throw new Error("legacy_v1_hard_fence_marker_too_large");
+  const markerText = await readFileNoFollow(markerPath);
+  const marker = validateFenceMarker(JSON.parse(markerText) as unknown);
+  if (markerText.trim() !== canonicalJsonV3(marker)) {
+    throw new Error("legacy_v1_hard_fence_marker_noncanonical");
+  }
+  const terminalName = marker.terminal_archive.replace(/^\.harnery\//, "");
+  if (!/^events-[0-9]{4}-[0-9]{2}-[0-9]{2}(?:\.[1-9][0-9]*)?\.ndjson$/.test(terminalName)) {
+    throw new Error("legacy_v1_terminal_archive_name_invalid");
+  }
+  const terminalPath = join(harnery, terminalName);
+  const terminalStat = await lstat(terminalPath);
+  if (!terminalStat.isFile() || terminalStat.isSymbolicLink()) {
+    throw new Error("legacy_v1_terminal_archive_invalid");
+  }
+  if ((await hashFile(terminalPath)) !== marker.terminal_digest) {
+    throw new Error("legacy_v1_terminal_archive_digest_mismatch");
+  }
+  return {
+    fence_directory: fence,
+    marker_path: markerPath,
+    terminal_archive_path: terminalPath,
+    marker,
+  };
+}
+
+function validateFenceMarker(value: unknown): LegacyV1HardFence {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("legacy_v1_hard_fence_marker_invalid");
+  }
+  const marker = value as Record<string, unknown>;
+  if (
+    Object.keys(marker).sort().join("\0") !==
+      ["kind", "manifest_version", "terminal_archive", "terminal_digest"].sort().join("\0") ||
+    marker.manifest_version !== 1 ||
+    marker.kind !== "v1_hard_path_fence" ||
+    typeof marker.terminal_archive !== "string" ||
+    typeof marker.terminal_digest !== "string" ||
+    !/^sha256:[0-9a-f]{64}$/.test(marker.terminal_digest)
+  ) {
+    throw new Error("legacy_v1_hard_fence_marker_invalid");
+  }
+  return marker as unknown as LegacyV1HardFence;
+}
+
+async function readFileNoFollow(path: string): Promise<string> {
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error("legacy_v1_hard_fence_marker_invalid");
+    return handle.readFile("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+async function hashFile(path: string): Promise<`sha256:${string}`> {
+  const hash = createHash("sha256");
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error(`legacy_v1_segment_not_regular:${basename(path)}`);
+    const stream = createReadStream(path, { fd: handle.fd, autoClose: false });
+    for await (const current of stream) hash.update(current as Buffer);
+  } finally {
+    await handle.close();
+  }
+  return `sha256:${hash.digest("hex")}`;
+}

package/src/core/events/legacy-storage/index.ts

@@ -0,0 +1,5 @@
+export * from "./canary.ts";
+export * from "./fence.ts";
+export * from "./inventory.ts";
+export * from "./manifest.ts";
+export * from "./reader.ts";