harnery 0.45.2 → 0.46.0

package/src/core/config.ts

@@ -92,6 +92,8 @@ interface HarneryConfig {
     requireGitFinalization?: boolean;
     finalizationRoots?: AgentFinalizationRoot[];
   };
+  /** Admission resource defaults and the heavy-command guard. Project config only. */
+  admission?: unknown;
   /** Host-owned agent instruction settings. */
   instructions?: {
     hostAddendumFile?: unknown;
@@ -633,6 +635,89 @@ export function ripgrepAutoInstall(coordRoot?: string | null): boolean {
   return readConfig(root).tools?.ripgrep?.autoInstall === true;
 }
 
+/** Wait before queueing while Linux memory pressure is high (PSI `full avg10`). */
+export interface AdmissionPressureConfig {
+  psi_full_avg10: number;
+  max_wait_seconds: number;
+}
+
+/** Per-resource defaults for `admission run`; command-line flags win. */
+export interface AdmissionResourceConfig {
+  capacity?: number;
+  timeout_minutes?: number;
+  defer_on_pressure?: AdmissionPressureConfig;
+}
+
+export interface AdmissionProjectConfig {
+  resources: Record<string, AdmissionResourceConfig>;
+  /** Present when the agent hook should wrap heavy shell commands in a slot. */
+  guard?: { resource: string };
+}
+
+function positiveNumber(value: unknown, max: number): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= max
+    ? value
+    : undefined;
+}
+
+/**
+ * Admission settings from `.harnery/config.jsonc`:
+ *
+ * ```jsonc
+ * "admission": {
+ *   "resources": {
+ *     "build": {
+ *       "capacity": 2,
+ *       "timeout_minutes": 30,
+ *       "defer_on_pressure": { "psi_full_avg10": 40, "max_wait_seconds": 300 }
+ *     }
+ *   },
+ *   "guard": { "resource": "build" }
+ * }
+ * ```
+ *
+ * Project config only, like other machine-shaping policy. Malformed values are
+ * dropped one by one rather than rejecting the whole block. Undefined when the
+ * project declares no admission settings.
+ */
+export function readAdmissionConfig(coordRoot?: string | null): AdmissionProjectConfig | undefined {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return undefined;
+  const raw = readProjectConfig(root).admission;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const record = raw as { resources?: unknown; guard?: unknown };
+  const resources: Record<string, AdmissionResourceConfig> = {};
+  if (
+    record.resources &&
+    typeof record.resources === "object" &&
+    !Array.isArray(record.resources)
+  ) {
+    for (const [name, value] of Object.entries(record.resources as Record<string, unknown>)) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+      const entry = value as Record<string, unknown>;
+      const capacity = positiveNumber(entry.capacity, 32);
+      const timeout = positiveNumber(entry.timeout_minutes, 1440);
+      const pressure = entry.defer_on_pressure as Record<string, unknown> | undefined;
+      const threshold = positiveNumber(pressure?.psi_full_avg10, 100);
+      const maxWait = positiveNumber(pressure?.max_wait_seconds, 86_400);
+      resources[name] = {
+        ...(capacity !== undefined && Number.isInteger(capacity) ? { capacity } : {}),
+        ...(timeout !== undefined && Number.isInteger(timeout) ? { timeout_minutes: timeout } : {}),
+        ...(threshold !== undefined && maxWait !== undefined
+          ? { defer_on_pressure: { psi_full_avg10: threshold, max_wait_seconds: maxWait } }
+          : {}),
+      };
+    }
+  }
+  const guard = record.guard as { resource?: unknown } | undefined;
+  return {
+    resources,
+    ...(guard && typeof guard.resource === "string" && guard.resource
+      ? { guard: { resource: guard.resource } }
+      : {}),
+  };
+}
+
 /**
  * Whether this repo pins workflow runs to subscription billing:
  * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.

package/src/core/diagnostics/path-identity.ts

@@ -1,15 +1,61 @@
-import { createHash } from "node:crypto";
+import { createHmac, randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { PERSONAL_DIR_MODE, PERSONAL_FILE_MODE } from "../storage/modes.ts";
 
 const HOME_PATH =
   /(?:[A-Za-z]:[\\/]Users[\\/](?:[^\\/\r\n\0:"<>|]+(?=[\\/])|[^\\/\s\0:]+)|\/home\/[^/\s\0:]+|\/Users\/[^/\s\0:]+)/g;
 
-/** One stable representation for private home paths in values and identity inputs. */
+const KEY_PATTERN = /^[0-9a-f]{64}$/;
+let cachedKey: Buffer | undefined;
+
+/**
+ * Per-install secret for home-path pseudonyms. An unkeyed digest would let
+ * anyone holding a bundle recover the user name by hashing guesses, so the
+ * key stays in local state and never enters a bundle. Sanitized values carry
+ * the pseudonym itself, so replay elsewhere needs no key.
+ */
+function identityKeyPath(): string {
+  const xdg = process.env.XDG_STATE_HOME;
+  const base = xdg?.trim() ? xdg : join(homedir(), ".local", "state");
+  return join(base, "harnery", "diagnostic-identity.key");
+}
+
+function readKey(path: string): Buffer | undefined {
+  try {
+    const text = readFileSync(path, "utf8").trim();
+    return KEY_PATTERN.test(text) ? Buffer.from(text, "hex") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function identityKey(): Buffer {
+  if (cachedKey) return cachedKey;
+  const path = identityKeyPath();
+  let key = readKey(path);
+  if (!key) {
+    const fresh = randomBytes(32);
+    try {
+      mkdirSync(dirname(path), { recursive: true, mode: PERSONAL_DIR_MODE });
+      writeFileSync(path, `${fresh.toString("hex")}\n`, { flag: "wx", mode: PERSONAL_FILE_MODE });
+      chmodSync(path, PERSONAL_FILE_MODE);
+      key = fresh;
+    } catch {
+      // A concurrent writer won the race, or state is unwritable. Prefer the
+      // stored key; otherwise stay private with a process-local key.
+      key = readKey(path) ?? fresh;
+    }
+  }
+  cachedKey = key;
+  return key;
+}
+
+/** One stable, non-reversible representation for private home paths in values and identity inputs. */
 export function canonicalizeDiagnosticIdentity(value: string): string {
   return value.replace(HOME_PATH, (home) => {
-    const digest = createHash("sha256")
-      .update("harnery-diagnostic-home-v1\0")
-      .update(home)
-      .digest("hex");
+    const digest = createHmac("sha256", identityKey()).update(home).digest("hex");
     return `[REDACTED:home:${digest}]`;
   });
 }

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

@@ -104,10 +104,19 @@ export function normalizeNativeIdV3(
   return `hid_${digest}`;
 }
 
+/**
+ * NFC leaves ASCII unchanged, so ASCII strings and key sets skip normalization
+ * and the collision map. Every reader re-serializes each ledger frame to prove
+ * it is canonical, which makes this the hottest function on a cold read.
+ */
+const NON_ASCII = /[\u0080-\uffff]/;
+
 function serialize(value: unknown, ancestors: Set<object>): string {
   if (value === null) return "null";
   if (typeof value === "boolean") return value ? "true" : "false";
-  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "string") {
+    return JSON.stringify(NON_ASCII.test(value) ? value.normalize("NFC") : value);
+  }
   if (typeof value === "number") {
     if (!Number.isFinite(value)) throw new Error("canonical JSON rejects non-finite numbers");
     return JSON.stringify(Object.is(value, -0) ? 0 : value);
@@ -119,29 +128,53 @@ function serialize(value: unknown, ancestors: Set<object>): string {
   ancestors.add(value);
   try {
     if (Array.isArray(value)) {
-      return `[${value.map((item) => serialize(item, ancestors)).join(",")}]`;
+      let out = "[";
+      for (let index = 0; index < value.length; index++) {
+        if (index > 0) out += ",";
+        out += serialize(value[index], ancestors);
+      }
+      return `${out}]`;
     }
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null) {
       throw new Error("canonical JSON accepts only plain objects");
     }
-    const normalized = new Map<string, unknown>();
-    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-      const normalizedKey = key.normalize("NFC");
-      if (normalized.has(normalizedKey)) {
-        throw new Error("canonical JSON key collision after Unicode normalization");
-      }
-      normalized.set(normalizedKey, item);
+    const object = value as Record<string, unknown>;
+    const keys = Object.keys(object);
+    if (keys.some((key) => NON_ASCII.test(key))) {
+      return serializeNormalizedObject(object, ancestors);
     }
-    const keys = [...normalized.keys()].sort(compareUtf16);
-    return `{${keys
-      .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
-      .join(",")}}`;
+    keys.sort(compareUtf16);
+    let out = "{";
+    for (let index = 0; index < keys.length; index++) {
+      const key = keys[index] as string;
+      if (index > 0) out += ",";
+      out += `${JSON.stringify(key)}:${serialize(object[key], ancestors)}`;
+    }
+    return `${out}}`;
   } finally {
     ancestors.delete(value);
   }
 }
 
+function serializeNormalizedObject(
+  object: Record<string, unknown>,
+  ancestors: Set<object>,
+): string {
+  const normalized = new Map<string, unknown>();
+  for (const [key, item] of Object.entries(object)) {
+    const normalizedKey = key.normalize("NFC");
+    if (normalized.has(normalizedKey)) {
+      throw new Error("canonical JSON key collision after Unicode normalization");
+    }
+    normalized.set(normalizedKey, item);
+  }
+  const keys = [...normalized.keys()].sort(compareUtf16);
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
+    .join(",")}}`;
+}
+
 function compareUtf16(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }

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

@@ -247,7 +247,9 @@ export {
   type DrainHookIntakeSpoolV3Result,
   drainHookIntakeSpoolV3,
   type HookProducerStateRecordV3,
+  type HookProducerStateScanV3,
   type HookProducerStateV3,
+  type InvalidHookProducerStateFileV3,
   listHookProducerStateRecordsV3,
   type RecordApprovedSessionEndV3Input,
   type RecordApprovedSessionEndV3Result,
@@ -256,6 +258,7 @@ export {
   readHookProducerStateV3,
   recordApprovedSessionEndV3,
   recordHookSignalV3,
+  scanHookProducerStateRecordsV3,
 } from "./producers/recorder.ts";
 export {
   type ClaimProjectionV3,

package/src/core/events/v3/producers/recorder.ts

@@ -465,7 +465,18 @@ function sessionHashForSignal(
   // single live producer authority instead of hashing the instance into a
   // second state path. Ambiguous or absent matches keep the fail-closed fallback.
   if (adapterBehavior(input.adapter).sessionIdentityOnStartOnly) {
-    const matches = listHookProducerStateRecordsV3(input.coordRoot).filter(
+    const scan = scanHookProducerStateRecordsV3(input.coordRoot);
+    // This instance's own state is unreadable: fail closed rather than hash
+    // the instance into a second state path beside it.
+    if (
+      scan.invalid.some(
+        (file) => file.adapter === input.adapter && file.instance_id === input.instance_id,
+      )
+    ) {
+      throw new Error("V3 producer state is invalid");
+    }
+    for (const file of scan.invalid) recordInvalidProducerStateDiagnostic(input.coordRoot, file);
+    const matches = scan.records.filter(
       ({ state }) => state.adapter === input.adapter && state.instance_id === input.instance_id,
     );
     if (matches.length === 1) {
@@ -3476,15 +3487,44 @@ export function salvageOpenSpansV3(input: SalvageOpenSpansV3Input): SalvageOpenS
   }
 }
 
-export function listHookProducerStateRecordsV3(
+/** One producer-state file the validator refused during a listing scan. */
+export interface InvalidHookProducerStateFileV3 {
+  path: string;
+  adapter: EventAdapterIdV3;
+  session_hash: `hid_${string}`;
+  reason: string;
+  /**
+   * The file's raw `instance_id` when it parses as JSON and carries a
+   * well-formed one. Readers that target one instance use it to keep failing
+   * closed on that instance's own invalid state.
+   */
+  instance_id?: `inst_${string}`;
+}
+
+export interface HookProducerStateScanV3 {
+  records: HookProducerStateRecordV3[];
+  invalid: InvalidHookProducerStateFileV3[];
+}
+
+/**
+ * Scan every producer-state file of the active epoch. A file the validator
+ * refuses is reported in `invalid` instead of failing the scan, so one
+ * session's bad state cannot take coordination away from every other session
+ * in the checkout. An unsafe adapter directory still throws.
+ */
+export function scanHookProducerStateRecordsV3(
   coordRoot: string,
   options: { includeTerminal?: boolean } = {},
-): HookProducerStateRecordV3[] {
+): HookProducerStateScanV3 {
   const control = readEventV3ControlState(coordRoot);
-  if (control.state !== "candidate" && control.state !== "active") return [];
+  if (control.state !== "candidate" && control.state !== "active") {
+    return { records: [], invalid: [] };
+  }
+  const genesisId = control.genesis.event.payload.genesis_id;
   const producerRoot = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers");
-  if (!existsSync(producerRoot)) return [];
+  if (!existsSync(producerRoot)) return { records: [], invalid: [] };
   const records: HookProducerStateRecordV3[] = [];
+  const invalid: InvalidHookProducerStateFileV3[] = [];
   for (const adapter of EVENT_ADAPTER_IDS_V3) {
     const directory = join(producerRoot, adapter);
     if (!existsSync(directory)) continue;
@@ -3496,19 +3536,86 @@ export function listHookProducerStateRecordsV3(
       /^hid_[a-f0-9]{64}\.json$/.test(entry),
     )) {
       const path = join(directory, name);
-      const state = readProducerState(path);
+      let state: HookProducerStateV3;
+      try {
+        state = readProducerState(path);
+      } catch (error) {
+        const raw = rawProducerStateIdentity(path);
+        // A refused file from a replaced epoch would have been skipped anyway.
+        if (raw.epoch_genesis_id !== undefined && raw.epoch_genesis_id !== genesisId) continue;
+        invalid.push({
+          path,
+          adapter,
+          session_hash: name.slice(0, -".json".length) as `hid_${string}`,
+          reason: error instanceof Error ? error.message : String(error),
+          ...(raw.instance_id ? { instance_id: raw.instance_id } : {}),
+        });
+        continue;
+      }
       // Skip authorities left behind by a replaced epoch: their sequences and
       // causal links belong to the archived ledger, not this one.
-      if (state.epoch_genesis_id !== control.genesis.event.payload.genesis_id) continue;
+      if (state.epoch_genesis_id !== genesisId) continue;
       if (!options.includeTerminal && state.terminal) continue;
       records.push({ path, modified_at_ms: lstatSync(path).mtimeMs, state });
     }
   }
-  return records.sort(
+  records.sort(
     (left, right) =>
       left.state.generation_id.localeCompare(right.state.generation_id) ||
       left.path.localeCompare(right.path),
   );
+  invalid.sort((left, right) => left.path.localeCompare(right.path));
+  return { records, invalid };
+}
+
+/**
+ * List the valid producer states of the active epoch. An invalid file is
+ * skipped and recorded as a `producer_state_invalid_skipped` diagnostic that
+ * names its adapter and session hash; readers of that one session's state
+ * still fail closed through `readHookProducerStateV3`.
+ */
+export function listHookProducerStateRecordsV3(
+  coordRoot: string,
+  options: { includeTerminal?: boolean } = {},
+): HookProducerStateRecordV3[] {
+  const scan = scanHookProducerStateRecordsV3(coordRoot, options);
+  for (const file of scan.invalid) recordInvalidProducerStateDiagnostic(coordRoot, file);
+  return scan.records;
+}
+
+function recordInvalidProducerStateDiagnostic(
+  coordRoot: string,
+  file: InvalidHookProducerStateFileV3,
+): void {
+  writeProducerDiagnosticV3(coordRoot, "producer_state_invalid_skipped", {
+    adapter: file.adapter,
+    session_hash: file.session_hash,
+    reason: file.reason,
+    ...(file.instance_id ? { instance_id: file.instance_id } : {}),
+  });
+}
+
+function rawProducerStateIdentity(path: string): {
+  instance_id?: `inst_${string}`;
+  epoch_genesis_id?: string;
+} {
+  try {
+    const metadata = lstatSync(path);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return {
+      ...(typeof parsed.instance_id === "string" &&
+      /^inst_[a-zA-Z0-9._-]{1,128}$/.test(parsed.instance_id)
+        ? { instance_id: parsed.instance_id as `inst_${string}` }
+        : {}),
+      ...(typeof parsed.epoch_genesis_id === "string"
+        ? { epoch_genesis_id: parsed.epoch_genesis_id }
+        : {}),
+    };
+  } catch {
+    return {};
+  }
 }
 
 export interface ReanchorArchivedHookProducersV3Input {
@@ -4277,6 +4384,15 @@ function acquireStateLease(coordRoot: string, statePath: string) {
   };
 }
 
+/** Test seam: publish a producer state through the real write-side validator. */
+export function publishHookProducerStateForTestV3(
+  coordRoot: string,
+  path: string,
+  state: HookProducerStateV3,
+): void {
+  publishProducerState(coordRoot, path, state);
+}
+
 function publishProducerState(coordRoot: string, path: string, state: HookProducerStateV3): void {
   const control = readEventV3ControlState(coordRoot);
   if (
@@ -4285,11 +4401,19 @@ function publishProducerState(coordRoot: string, path: string, state: HookProduc
   ) {
     return;
   }
+  const serialized = JSON.stringify(state);
+  // Validate the exact bytes about to land with the reader's own validator.
+  // The previous file stays in place when this refuses.
+  try {
+    validateProducerStateDocument(JSON.parse(serialized));
+  } catch {
+    throw new Error("V3 producer state is invalid; refusing to publish");
+  }
   const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
   let fd: number | undefined;
   try {
     fd = openSync(temporary, "wx", stateFileMode());
-    writeFileSync(fd, `${JSON.stringify(state)}\n`, "utf8");
+    writeFileSync(fd, `${serialized}\n`, "utf8");
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
@@ -4314,6 +4438,16 @@ function readProducerState(path: string): HookProducerStateV3 {
   } catch {
     throw new Error("V3 producer state is unreadable");
   }
+  return validateProducerStateDocument(parsed);
+}
+
+/**
+ * The single producer-state validator. Readers run it on every file they
+ * load, and `publishProducerState` runs it on the serialized document before
+ * the rename, so a state no reader would accept fails in the producing hook
+ * instead of in every later reader of the checkout.
+ */
+function validateProducerStateDocument(parsed: unknown): HookProducerStateV3 {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("V3 producer state is invalid");
   }
@@ -4589,8 +4723,10 @@ function validPendingRuntimeContext(value: unknown): value is PendingRuntimeCont
     Number.isFinite(Date.parse(pending.terminal_observed_at)) &&
     typeof pending.turn_id === "string" &&
     /^tid_[a-f0-9]{64}$/.test(pending.turn_id) &&
-    (pending.run_id === undefined || /^run_[0-9a-f-]{36}$/.test(pending.run_id)) &&
-    (pending.workflow_id === undefined || /^wf_[0-9a-f-]{36}$/.test(pending.workflow_id)) &&
+    // Same shapes the event contract accepts: workflow children carry
+    // stableScopeId hashes (run_<64 hex>), not UUIDs.
+    (pending.run_id === undefined || /^run_[a-zA-Z0-9._-]{1,128}$/.test(pending.run_id)) &&
+    (pending.workflow_id === undefined || /^wf_[a-zA-Z0-9._-]{1,128}$/.test(pending.workflow_id)) &&
     (pending.workflow_agent_id === undefined ||
       /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.workflow_agent_id)) &&
     typeof pending.native_session_id === "string" &&
@@ -4606,9 +4742,11 @@ function validPendingRuntimeContext(value: unknown): value is PendingRuntimeCont
     (pending.runtime_version === undefined ||
       (typeof pending.runtime_version === "string" &&
         /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,127}$/.test(pending.runtime_version))) &&
+    // Externally driven reconciles (`deferRetryLimit`) keep counting past
+    // RUNTIME_CONTEXT_RETRY_LIMIT until their own final attempt, and publish
+    // those counts, so the reader must accept them.
     Number.isSafeInteger(pending.attempts) &&
-    pending.attempts >= 0 &&
-    pending.attempts < RUNTIME_CONTEXT_RETRY_LIMIT
+    pending.attempts >= 0
   );
 }
 

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

@@ -19,6 +19,7 @@ import {
   readEventV3SegmentManifest,
 } from "./catalog.ts";
 import type { EventV3 } from "./contract.ts";
+import { readAdvanceableControlWitnessV3 } from "./control-witness.ts";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
 import {
   type EventV3RecoveryFailure,
@@ -442,7 +443,9 @@ export function readLedgerV3(
   }
 
   const discovered = discoverLedgerFramesV3(coordRoot);
-  const validated = validateLedgerFramesV3(discovered.frames, options);
+  const validated =
+    validateWitnessedFramesV3(coordRoot, storage, discovered, options) ??
+    validateLedgerFramesV3(discovered.frames, options);
   const recovery = discoverRecoveryReceiptsV3(coordRoot);
   const diagnostics = [
     ...discovered.diagnostics,
@@ -514,9 +517,40 @@ export function readLedgerFramesV3(
   return validateLedgerFramesV3(frames, options).result;
 }
 
+/**
+ * Cold-process fast path. Writers advance an authenticated validation
+ * checkpoint under the append lease after every drain, so when the witness
+ * names exactly the storage this read observed, each frame already passed the
+ * contract and canonical-byte checks that dominate a full read. Those two
+ * checks are skipped; every ledger-level rule still runs and rebuilds the
+ * validator state. The result is used only if that state reproduces the
+ * witnessed checkpoint byte for byte with no diagnostics and storage did not
+ * move during the read; anything else returns undefined and the caller runs
+ * the canonical full validation.
+ */
+function validateWitnessedFramesV3(
+  coordRoot: string,
+  storage: LedgerStorageVersionV3,
+  discovered: DiscoveredFramesV3,
+  options: ReadLedgerV3Options,
+): { result: ReadLedgerV3Result; state: LedgerValidationStateV3 } | undefined {
+  if (!discovered.active || discovered.diagnostics.length > 0) return undefined;
+  const witness = readAdvanceableControlWitnessV3(coordRoot);
+  if (!witness || witness.payload.storage.fingerprint !== sha256V3(storage.fingerprint)) {
+    return undefined;
+  }
+  const trusted = validateLedgerFramesV3(discovered.frames, options, true);
+  if (trusted.state.diagnostics.length > 0) return undefined;
+  const reproduced = checkpointFromValidationStateV3(trusted.state, discovered.active);
+  if (canonicalJsonV3(reproduced) !== canonicalJsonV3(witness.checkpoint)) return undefined;
+  if (ledgerStorageVersionV3(coordRoot).fingerprint !== storage.fingerprint) return undefined;
+  return trusted;
+}
+
 function validateLedgerFramesV3(
   frames: readonly LedgerFrameV3[],
   options: ReadLedgerV3Options,
+  witnessed = false,
 ): { result: ReadLedgerV3Result; state: LedgerValidationStateV3 } {
   const state: LedgerValidationStateV3 = {
     diagnostics: [],
@@ -530,13 +564,18 @@ function validateLedgerFramesV3(
     clocks: new Map(),
     event_count: 0,
   };
-  validateLedgerFramesIntoStateV3(frames, state);
+  validateLedgerFramesIntoStateV3(frames, state, witnessed);
   return { result: finishLedgerValidationV3(state, options, ledgerFramesBytesV3(frames)), state };
 }
 
+/**
+ * `witnessed` skips only the per-frame contract and canonical-byte checks, and
+ * only validateWitnessedFramesV3 may pass it, after authenticating the frames.
+ */
 function validateLedgerFramesIntoStateV3(
   frames: readonly LedgerFrameV3[],
   state: LedgerValidationStateV3,
+  witnessed = false,
 ): void {
   state.first_position ??= frames[0]?.position;
   const {
@@ -576,17 +615,22 @@ function validateLedgerFramesIntoStateV3(
       diagnostics.push(diagnostic("unsupported_major", frame));
       continue;
     }
-    const validation = validateEventV3(parsed);
-    if (!validation.ok || !validation.event) {
-      diagnostics.push(diagnostic("invalid_contract", frame));
-      continue;
+    let event: EventV3;
+    if (witnessed) {
+      event = parsed as EventV3;
+    } else {
+      const validation = validateEventV3(parsed);
+      if (!validation.ok || !validation.event) {
+        diagnostics.push(diagnostic("invalid_contract", frame));
+        continue;
+      }
+      event = validation.event;
+      if (canonicalJsonV3(event) !== frame.raw) {
+        diagnostics.push(diagnostic("noncanonical_frame", frame, event.event_id));
+        continue;
+      }
     }
-    const event = validation.event;
     const shape = event as unknown as EventShape;
-    if (canonicalJsonV3(event) !== frame.raw) {
-      diagnostics.push(diagnostic("noncanonical_frame", frame, shape.event_id));
-      continue;
-    }
     const priorFrame = seenIds.get(shape.event_id);
     if (priorFrame !== undefined) {
       if (priorFrame !== frame.raw) {

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

@@ -45,8 +45,49 @@ interface RecoveryShape {
   elapsed_upper_bound_ms?: ObservationShape;
 }
 
+type EventVariantSchema = (typeof EventV3Schema.anyOf)[number];
+
+/**
+ * Every union member requires its own literal `event_type`, so only the member
+ * named by a value's `event_type` can accept it. Checking that one member gives
+ * the union's verdict without trying the other variants, which more than halves
+ * a full-ledger read. Returns null, falling back to the whole union, if a member
+ * ever stops carrying a required unique literal.
+ */
+let eventVariantsByType: Map<string, EventVariantSchema> | null | undefined;
+
+function eventVariantsByTypeV3(): Map<string, EventVariantSchema> | null {
+  if (eventVariantsByType !== undefined) return eventVariantsByType;
+  const variants = new Map<string, EventVariantSchema>();
+  for (const variant of EventV3Schema.anyOf) {
+    const literal = (variant.properties as Record<string, { const?: unknown }>).event_type?.const;
+    if (
+      typeof literal !== "string" ||
+      !(variant.required as readonly string[] | undefined)?.includes("event_type") ||
+      variants.has(literal)
+    ) {
+      eventVariantsByType = null;
+      return null;
+    }
+    variants.set(literal, variant);
+  }
+  eventVariantsByType = variants;
+  return variants;
+}
+
+function checkEventSchemaV3(value: unknown): boolean {
+  const variants = eventVariantsByTypeV3();
+  if (!variants) return Value.Check(EventV3Schema, value);
+  const eventType =
+    typeof value === "object" && value !== null
+      ? (value as { event_type?: unknown }).event_type
+      : undefined;
+  const variant = typeof eventType === "string" ? variants.get(eventType) : undefined;
+  return variant !== undefined && Value.Check(variant, value);
+}
+
 export function validateEventV3(value: unknown): EventV3ValidationResult {
-  if (!Value.Check(EventV3Schema, value)) {
+  if (!checkEventSchemaV3(value)) {
     return {
       ok: false,
       issues: [...Value.Errors(EventV3Schema, value)]