harnery 0.35.0 → 0.37.0

package/src/core/events/v3/support-storage/classify.ts

@@ -0,0 +1,209 @@
+import type { EventV3SupportFamily } from "./pack-contract.ts";
+
+export type EventV3SupportDisposition =
+  | "live-required"
+  | "recovery-required"
+  | "pack-eligible"
+  | "quarantine"
+  | "unsupported";
+
+export const EVENT_V3_SUPPORT_CLASSIFICATION_REASONS = [
+  "active_committed_receipt_deferred",
+  "active_epoch_family_not_enabled",
+  "archive_has_ready_authority_transaction",
+  "authority_lease_live",
+  "authority_ready_active",
+  "command_state_lease_live",
+  "command_state_open",
+  "command_state_pending",
+  "committed_receipt_grace_not_elapsed",
+  "committed_receipt_reconciled",
+  "diagnostic_consumer_window_elapsed",
+  "diagnostic_timestamp_mismatch",
+  "diagnostic_within_loose_window",
+  "epoch_not_enabled_for_maintenance_slice",
+  "event_reference_cross_epoch",
+  "event_reference_unresolved",
+  "file_contract_invalid",
+  "file_not_owner_only",
+  "file_not_regular",
+  "finalization_not_complete",
+  "maintenance_transaction_owns_path",
+  "producer_pending_reference",
+  "recovery_bound_archive_not_enabled",
+  "receipt_digest_mismatch",
+  "receipt_has_ready_sibling",
+  "sealed_terminal_state",
+  "stale_writer_grace_not_elapsed",
+  "transaction_digest_mismatch",
+  "turn_not_sealed",
+  "unknown_support_family",
+] as const;
+
+export type EventV3SupportClassificationReason =
+  (typeof EVENT_V3_SUPPORT_CLASSIFICATION_REASONS)[number];
+
+export interface EventV3SupportClassificationEvidence {
+  family?: EventV3SupportFamily;
+  authority_state: "active" | "archived";
+  recovery_bound?: boolean;
+  recovery_packing_enabled?: boolean;
+  epoch_maintenance_enabled?: boolean;
+  active_session_tee_enabled?: boolean;
+  active_committed_receipt_enabled?: boolean;
+  file_regular?: boolean;
+  file_owner_only?: boolean;
+  contract_valid?: boolean;
+  maintenance_owned?: boolean;
+  recorded_at?: string;
+  filename_recorded_at?: string;
+  now: string;
+  maximum_loose_consumer_window_ms?: number;
+  fixed_consumer_grace_ms?: number;
+  writer_tolerance_ms?: number;
+  terminal?: boolean;
+  pending?: boolean;
+  turn_sealed?: boolean;
+  finalization_complete?: boolean;
+  event_references_resolved?: boolean;
+  event_references_same_epoch?: boolean;
+  lease_live?: boolean;
+  stale_writer_grace_elapsed?: boolean;
+  ready_sibling?: boolean;
+  producer_pending_reference?: boolean;
+  event_row_digest_matches?: boolean;
+  transaction_digest_matches?: boolean;
+  receipt_grace_elapsed?: boolean;
+  archive_has_ready_transaction?: boolean;
+}
+
+export interface EventV3SupportClassification {
+  disposition: EventV3SupportDisposition;
+  reasons: EventV3SupportClassificationReason[];
+}
+
+export const EVENT_V3_DIAGNOSTIC_CONSUMER_WINDOW_MS = 48 * 60 * 60 * 1000;
+export const EVENT_V3_DIAGNOSTIC_FIXED_GRACE_MS = 24 * 60 * 60 * 1000;
+
+/** The only disposition decision point for V3 support files. */
+export function classifyEventV3Support(
+  evidence: EventV3SupportClassificationEvidence,
+): EventV3SupportClassification {
+  if (!evidence.family) return result("unsupported", ["unknown_support_family"]);
+  if (evidence.file_regular === false) return result("quarantine", ["file_not_regular"]);
+  if (evidence.file_owner_only === false) return result("quarantine", ["file_not_owner_only"]);
+  if (evidence.contract_valid === false) return result("quarantine", ["file_contract_invalid"]);
+  if (evidence.maintenance_owned) {
+    return result("live-required", ["maintenance_transaction_owns_path"]);
+  }
+  if (evidence.archive_has_ready_transaction) {
+    return result("quarantine", ["archive_has_ready_authority_transaction"]);
+  }
+  if (evidence.recovery_bound && !evidence.recovery_packing_enabled) {
+    return result("recovery-required", ["recovery_bound_archive_not_enabled"]);
+  }
+  if (!evidence.epoch_maintenance_enabled) {
+    return result("live-required", ["epoch_not_enabled_for_maintenance_slice"]);
+  }
+
+  switch (evidence.family) {
+    case "diagnostic":
+      return classifyDiagnostic(evidence);
+    case "session-tee":
+      return classifyCommandState(evidence);
+    case "authority-ready":
+      return evidence.authority_state === "active"
+        ? result("recovery-required", ["authority_ready_active"])
+        : result("quarantine", ["archive_has_ready_authority_transaction"]);
+    case "authority-committed":
+      return classifyCommittedReceipt(evidence);
+    case "authority-residue":
+      return result("quarantine", ["file_contract_invalid"]);
+  }
+}
+
+function classifyDiagnostic(
+  evidence: EventV3SupportClassificationEvidence,
+): EventV3SupportClassification {
+  if (!evidence.recorded_at || !evidence.filename_recorded_at) {
+    return result("quarantine", ["file_contract_invalid"]);
+  }
+  const recorded = Date.parse(evidence.recorded_at);
+  const filename = Date.parse(evidence.filename_recorded_at);
+  const now = Date.parse(evidence.now);
+  if (![recorded, filename, now].every(Number.isFinite)) {
+    return result("quarantine", ["file_contract_invalid"]);
+  }
+  const tolerance = evidence.writer_tolerance_ms ?? 1000;
+  if (Math.abs(recorded - filename) > tolerance) {
+    return result("quarantine", ["diagnostic_timestamp_mismatch"]);
+  }
+  const consumer =
+    evidence.maximum_loose_consumer_window_ms ?? EVENT_V3_DIAGNOSTIC_CONSUMER_WINDOW_MS;
+  const grace = evidence.fixed_consumer_grace_ms ?? EVENT_V3_DIAGNOSTIC_FIXED_GRACE_MS;
+  if (now - recorded < consumer + grace) {
+    return result("live-required", ["diagnostic_within_loose_window"]);
+  }
+  return result("pack-eligible", ["diagnostic_consumer_window_elapsed"]);
+}
+
+function classifyCommandState(
+  evidence: EventV3SupportClassificationEvidence,
+): EventV3SupportClassification {
+  if (evidence.authority_state === "active" && !evidence.active_session_tee_enabled) {
+    return result("live-required", ["active_epoch_family_not_enabled"]);
+  }
+  if (!evidence.terminal) return result("recovery-required", ["command_state_open"]);
+  if (evidence.pending) return result("recovery-required", ["command_state_pending"]);
+  if (!evidence.turn_sealed) return result("recovery-required", ["turn_not_sealed"]);
+  if (!evidence.finalization_complete) {
+    return result("recovery-required", ["finalization_not_complete"]);
+  }
+  if (!evidence.event_references_resolved) {
+    return result("quarantine", ["event_reference_unresolved"]);
+  }
+  if (!evidence.event_references_same_epoch) {
+    return result("quarantine", ["event_reference_cross_epoch"]);
+  }
+  if (evidence.lease_live) return result("recovery-required", ["command_state_lease_live"]);
+  if (!evidence.stale_writer_grace_elapsed) {
+    return result("live-required", ["stale_writer_grace_not_elapsed"]);
+  }
+  return result("pack-eligible", ["sealed_terminal_state"]);
+}
+
+function classifyCommittedReceipt(
+  evidence: EventV3SupportClassificationEvidence,
+): EventV3SupportClassification {
+  if (evidence.authority_state === "active" && !evidence.active_committed_receipt_enabled) {
+    return result("live-required", ["active_committed_receipt_deferred"]);
+  }
+  if (evidence.ready_sibling) return result("recovery-required", ["receipt_has_ready_sibling"]);
+  if (evidence.producer_pending_reference) {
+    return result("recovery-required", ["producer_pending_reference"]);
+  }
+  if (!evidence.event_references_resolved) {
+    return result("quarantine", ["event_reference_unresolved"]);
+  }
+  if (!evidence.event_references_same_epoch) {
+    return result("quarantine", ["event_reference_cross_epoch"]);
+  }
+  if (!evidence.event_row_digest_matches) {
+    return result("quarantine", ["receipt_digest_mismatch"]);
+  }
+  if (!evidence.transaction_digest_matches) {
+    return result("quarantine", ["transaction_digest_mismatch"]);
+  }
+  if (evidence.lease_live) return result("recovery-required", ["authority_lease_live"]);
+  if (!evidence.receipt_grace_elapsed) {
+    return result("live-required", ["committed_receipt_grace_not_elapsed"]);
+  }
+  return result("pack-eligible", ["committed_receipt_reconciled"]);
+}
+
+function result(
+  disposition: EventV3SupportDisposition,
+  reasons: EventV3SupportClassificationReason[],
+): EventV3SupportClassification {
+  return { disposition, reasons: [...new Set(reasons)].sort() };
+}

package/src/core/events/v3/support-storage/eligibility.ts

@@ -0,0 +1,58 @@
+import type { EventV3SupportInventoryEntry } from "./inventory.ts";
+
+export interface EventV3AuthorityPackingCandidate {
+  authority_root: string;
+  state: "active" | "archived";
+  genesis_id: string;
+  recovery_receipt_id?: string;
+  has_ready_transaction: boolean;
+  has_pending_producer_state: boolean;
+  has_maintenance_transaction: boolean;
+  regular_file_count: number;
+  entries: EventV3SupportInventoryEntry[];
+}
+
+export interface EventV3AuthorityPackingGate {
+  eligible: boolean;
+  reasons: string[];
+}
+
+export function assessEventV3AuthorityPackingGate(
+  candidate: EventV3AuthorityPackingCandidate,
+  options: { allow_active?: boolean; allow_recovery_bound?: boolean } = {},
+): EventV3AuthorityPackingGate {
+  const reasons: string[] = [];
+  if (candidate.state === "active" && !options.allow_active)
+    reasons.push("active_epoch_not_enabled");
+  if (candidate.recovery_receipt_id && !options.allow_recovery_bound) {
+    reasons.push("recovery_bound_archive_not_enabled");
+  }
+  if (candidate.has_ready_transaction) reasons.push("ready_authority_transaction_present");
+  if (candidate.has_pending_producer_state) reasons.push("pending_producer_state_present");
+  if (candidate.has_maintenance_transaction) reasons.push("maintenance_transaction_present");
+  if (candidate.entries.length === 0) reasons.push("no_support_files");
+  if (candidate.entries.some((entry) => entry.disposition !== "pack-eligible")) {
+    reasons.push("support_entry_not_pack_eligible");
+  }
+  return { eligible: reasons.length === 0, reasons: reasons.sort() };
+}
+
+/** Choose one deterministic smallest unbound archive canary; never mutate it. */
+export function planEventV3ArchiveCanary(candidates: EventV3AuthorityPackingCandidate[]): {
+  candidate?: EventV3AuthorityPackingCandidate;
+  rejected: Array<{ authority_root: string; reasons: string[] }>;
+} {
+  const rejected: Array<{ authority_root: string; reasons: string[] }> = [];
+  const eligible: EventV3AuthorityPackingCandidate[] = [];
+  for (const candidate of candidates) {
+    const gate = assessEventV3AuthorityPackingGate(candidate);
+    if (gate.eligible) eligible.push(candidate);
+    else rejected.push({ authority_root: candidate.authority_root, reasons: gate.reasons });
+  }
+  eligible.sort(
+    (left, right) =>
+      left.regular_file_count - right.regular_file_count ||
+      left.authority_root.localeCompare(right.authority_root),
+  );
+  return { candidate: eligible[0], rejected };
+}

package/src/core/events/v3/support-storage/index.ts

@@ -0,0 +1,9 @@
+export * from "./classify.ts";
+export * from "./eligibility.ts";
+export * from "./inventory.ts";
+export * from "./logical-authority.ts";
+export * from "./maintenance.ts";
+export * from "./pack-contract.ts";
+export * from "./pack-reader.ts";
+export * from "./pack-writer.ts";
+export * from "./recovery.ts";

package/src/core/events/v3/support-storage/inventory.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import {
+  classifyEventV3Support,
+  type EventV3SupportClassificationEvidence,
+  type EventV3SupportDisposition,
+} from "./classify.ts";
+import type { EventV3SupportFamily } from "./pack-contract.ts";
+
+export interface EventV3SupportAuthorityIdentity {
+  state: "active" | "archived";
+  epoch_directory?: string;
+  genesis_id?: string;
+  recovery_receipt_id?: string;
+}
+
+export interface EventV3SupportInventoryEntry {
+  authority: EventV3SupportAuthorityIdentity;
+  family: EventV3SupportFamily;
+  relative_path: string;
+  bytes: number;
+  digest: `sha256:${string}`;
+  disposition: EventV3SupportDisposition;
+  reasons: string[];
+  observed: {
+    recorded_at?: string;
+    modified_at: string;
+  };
+}
+
+export interface InventoryEventV3SupportInput {
+  authority_root: string;
+  authority: EventV3SupportAuthorityIdentity;
+  now: string;
+  evidence?: Record<
+    string,
+    Omit<EventV3SupportClassificationEvidence, "family" | "authority_state" | "now">
+  >;
+}
+
+const SUPPORT_ROOTS: Array<{ prefix: string; family: EventV3SupportFamily }> = [
+  { prefix: "diagnostics", family: "diagnostic" },
+  { prefix: "private-producers/session-tee", family: "session-tee" },
+  { prefix: "authority-outbox", family: "authority-residue" },
+];
+
+/** Enumerate only V3 support roots, never canonical streams and never symlink targets. */
+export async function inventoryEventV3Support(
+  input: InventoryEventV3SupportInput,
+): Promise<EventV3SupportInventoryEntry[]> {
+  const root = resolve(input.authority_root);
+  const rootStat = await lstat(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error("event_v3_support_inventory_authority_invalid");
+  }
+  const rootReal = await realpath(root);
+  const results: EventV3SupportInventoryEntry[] = [];
+  for (const support of SUPPORT_ROOTS) {
+    const directory = join(root, ...support.prefix.split("/"));
+    try {
+      const stat = await lstat(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`event_v3_support_inventory_root_invalid:${support.prefix}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    const directoryReal = await realpath(directory);
+    if (relative(rootReal, directoryReal).startsWith("..")) {
+      throw new Error("event_v3_support_inventory_root_escape");
+    }
+    await visit(directory, support.prefix, support.family);
+  }
+  return results.sort((left, right) => left.relative_path.localeCompare(right.relative_path));
+
+  async function visit(
+    directory: string,
+    prefix: string,
+    defaultFamily: EventV3SupportFamily,
+  ): Promise<void> {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    )) {
+      const path = join(directory, entry.name);
+      const relativePath = `${prefix}/${entry.name}`;
+      const fileStat = await lstat(path);
+      if (fileStat.isSymbolicLink()) throw new Error("event_v3_support_inventory_symlink");
+      if (fileStat.isDirectory()) {
+        await visit(path, relativePath, defaultFamily);
+        continue;
+      }
+      if (!fileStat.isFile()) throw new Error("event_v3_support_inventory_special_file");
+      const family = familyFor(relativePath, defaultFamily);
+      const supplied = input.evidence?.[relativePath] ?? {};
+      const classification = classifyEventV3Support({
+        ...supplied,
+        family,
+        authority_state: input.authority.state,
+        now: input.now,
+        file_regular: true,
+        file_owner_only: (fileStat.mode & 0o077) === 0,
+      });
+      results.push({
+        authority: input.authority,
+        family,
+        relative_path: relativePath,
+        bytes: fileStat.size,
+        digest: await hashFile(path),
+        disposition: classification.disposition,
+        reasons: classification.reasons,
+        observed: {
+          ...(supplied.recorded_at ? { recorded_at: supplied.recorded_at } : {}),
+          modified_at: fileStat.mtime.toISOString(),
+        },
+      });
+    }
+  }
+}
+
+function familyFor(path: string, fallback: EventV3SupportFamily): EventV3SupportFamily {
+  if (fallback !== "authority-residue") return fallback;
+  const name = basename(path);
+  if (name.endsWith(".ready.json")) return "authority-ready";
+  if (name.endsWith(".committed.json")) return "authority-committed";
+  return fallback;
+}
+
+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")}`;
+}

package/src/core/events/v3/support-storage/logical-authority.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { canonicalJsonV3 } from "../canonical.ts";
+import type { EventV3LogicalAuthorityEntry } from "./pack-contract.ts";
+import { readEventV3SupportPackManifest, streamEventV3SupportPackRecords } from "./pack-reader.ts";
+
+export interface EventV3LogicalAuthorityView {
+  entries: EventV3LogicalAuthorityEntry[];
+  quarantined_packs: Array<{ manifest_path: string; reason: string }>;
+  physical_files: number;
+  packed_entries: number;
+}
+
+/** Build a pack-aware authority view without following symlinks or granting pack precedence. */
+export async function iterateEventV3LogicalAuthority(
+  authorityRoot: string,
+): Promise<EventV3LogicalAuthorityView> {
+  const root = resolve(authorityRoot);
+  const rootStat = await lstat(root);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error("event_v3_logical_authority_root_invalid");
+  }
+  const rootReal = await realpath(root);
+  const physical = new Map<string, EventV3LogicalAuthorityEntry>();
+  const manifests: string[] = [];
+  let physicalFiles = 0;
+
+  const visit = async (directory: string, prefix: string): Promise<void> => {
+    const directoryStat = await lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+      throw new Error("event_v3_logical_authority_directory_invalid");
+    }
+    const directoryReal = await realpath(directory);
+    if (relative(rootReal, directoryReal).startsWith("..")) {
+      throw new Error("event_v3_logical_authority_directory_escape");
+    }
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    )) {
+      const path = join(directory, entry.name);
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const stat = await lstat(path);
+      if (stat.isSymbolicLink()) throw new Error("event_v3_logical_authority_symlink");
+      if (stat.isDirectory()) {
+        if (prefix === "" && entry.name === "support-packs") {
+          for (const candidate of await readdir(path)) {
+            if (candidate.endsWith(".manifest.json")) manifests.push(join(path, candidate));
+          }
+        } else {
+          await visit(path, relativePath);
+        }
+        continue;
+      }
+      if (!stat.isFile()) throw new Error("event_v3_logical_authority_special_file");
+      const digest = await hashFile(path);
+      physical.set(relativePath, { path: relativePath, bytes: stat.size, digest });
+      physicalFiles += 1;
+    }
+  };
+  await visit(root, "");
+
+  const packedByPath = new Map<string, { entry: EventV3LogicalAuthorityEntry; manifest: string }>();
+  const quarantined: EventV3LogicalAuthorityView["quarantined_packs"] = [];
+  let packedEntries = 0;
+  for (const manifestPath of manifests.sort()) {
+    await readEventV3SupportPackManifest(manifestPath);
+    const candidate: EventV3LogicalAuthorityEntry[] = [];
+    for await (const record of streamEventV3SupportPackRecords(manifestPath)) {
+      const priorPack = packedByPath.get(record.path);
+      if (priorPack)
+        throw new Error(`event_v3_logical_authority_cross_pack_duplicate:${record.path}`);
+      candidate.push({ path: record.path, bytes: record.bytes, digest: record.digest });
+    }
+    const conflict = candidate.find((entry) => {
+      const loose = physical.get(entry.path);
+      return loose && (loose.bytes !== entry.bytes || loose.digest !== entry.digest);
+    });
+    if (conflict) {
+      quarantined.push({
+        manifest_path: manifestPath,
+        reason: `loose_pack_digest_conflict:${conflict.path}`,
+      });
+      continue;
+    }
+    for (const entry of candidate) packedByPath.set(entry.path, { entry, manifest: manifestPath });
+    packedEntries += candidate.length;
+  }
+
+  const combined = new Map(physical);
+  for (const { entry } of packedByPath.values()) {
+    if (!combined.has(entry.path)) combined.set(entry.path, entry);
+  }
+  return {
+    entries: [...combined.values()].sort((left, right) => left.path.localeCompare(right.path)),
+    quarantined_packs: quarantined,
+    physical_files: physicalFiles,
+    packed_entries: packedEntries,
+  };
+}
+
+export async function digestEventV3LogicalAuthority(
+  authorityRoot: string,
+): Promise<`sha256:${string}`> {
+  const view = await iterateEventV3LogicalAuthority(authorityRoot);
+  if (view.quarantined_packs.length > 0) {
+    throw new Error("event_v3_logical_authority_has_quarantined_pack");
+  }
+  return `sha256:${createHash("sha256").update(canonicalJsonV3(view.entries)).digest("hex")}`;
+}
+
+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")}`;
+}