harnery 0.35.0 → 0.37.0

package/src/core/events/v3/live-route-observer.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { ADAPTER_CAPABILITY_PROFILES_V3 } from "./capabilities.ts";
+import {
+  type EventV3ControlState,
+  type EventV3WriteMode,
+  readEventV3ControlState,
+} from "./control.ts";
+import { liveEventV3BuildId } from "./runtime-identity.ts";
+
+export type LiveEventLedgerRouteV3 =
+  | {
+      state: "v3";
+      mode: EventV3WriteMode;
+      build_id: `build_${string}`;
+      /** Genesis id of the epoch this route was resolved against: the epoch fence for derived writes. */
+      genesis_id: `gex_${string}`;
+    }
+  | { state: "blocked"; reason: string };
+
+/**
+ * Observe the V3-only ledger route without repairing control pairs, replacing
+ * epochs, launching processes, or writing files. Read-only consumers fail
+ * closed until a command or producer repairs the route.
+ */
+export function observeLiveEventLedgerRouteV3(coordRoot: string): LiveEventLedgerRouteV3 {
+  return liveEventLedgerRouteFromControlV3(readEventV3ControlState(coordRoot));
+}
+
+/** Project one already-read control state into the passive route contract. */
+export function liveEventLedgerRouteFromControlV3(
+  control: EventV3ControlState,
+): LiveEventLedgerRouteV3 {
+  if (control.state === "closed") return { state: "blocked", reason: "v3_not_initialized" };
+  if (control.state !== "candidate" && control.state !== "active") {
+    return { state: "blocked", reason: `${control.state}:${control.reason}` };
+  }
+  if (!runtimeCapabilityProfileCurrentV3(control)) {
+    return { state: "blocked", reason: "runtime_capability_profile_incompatible" };
+  }
+  const buildId = liveEventV3BuildId(control.genesis.profile.harnery_commit);
+  if (!control.genesis.profile.producer_build_ids.includes(buildId)) {
+    return { state: "blocked", reason: "live_producer_build_not_approved" };
+  }
+  return {
+    state: "v3",
+    mode: control.state,
+    build_id: buildId,
+    genesis_id: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  };
+}
+
+export function runtimeCapabilityProfileCurrentV3(
+  control: Extract<EventV3ControlState, { state: "candidate" | "active" }>,
+): boolean {
+  const expected = Object.values(ADAPTER_CAPABILITY_PROFILES_V3).map((profile) =>
+    sha256V3(canonicalJsonV3(profile)),
+  );
+  const approved = control.genesis.profile.adapter_capability_profile_digests;
+  const expectedDigests = new Set<string>(expected);
+  return control.state === "candidate"
+    ? approved.some((digest) => expectedDigests.has(digest))
+    : expected.every((digest) => approved.includes(digest));
+}
+
+export function liveInstanceIdV3(instanceId: string): `inst_${string}` {
+  if (/^inst_[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return instanceId as `inst_${string}`;
+  if (/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return `inst_${instanceId}`;
+  return `inst_${createHash("sha256").update(instanceId.normalize("NFC")).digest("hex")}`;
+}
+
+/**
+ * The adapter-native id a canonical `inst_*` id carries, for display and for
+ * joins against native-keyed records. Only the direct prefix form round-trips:
+ * a hashed id has no recoverable native form and is returned unchanged, so
+ * never treat this as a guaranteed inverse of `liveInstanceIdV3`.
+ */
+export function nativeInstanceIdV3(instanceId: string): string {
+  return instanceId.startsWith("inst_") ? instanceId.slice("inst_".length) : instanceId;
+}

package/src/core/events/v3/live-routing.ts

@@ -1,26 +1,38 @@
-import { createHash } from "node:crypto";
 import type { Adapter } from "../../adapter.ts";
 import type { ParsedPayload } from "../../hooks/adapter/parse.ts";
+import { refreshIncompatibleEventLedgerV3, rotateOversizedEventLedgerV3 } from "./bootstrap.ts";
 import type { EventV3 } from "./contract.ts";
+import { readEventV3ControlState } from "./control.ts";
+import { repairEventV3ControlPair } from "./control-writer.ts";
 import {
-  type EventV3WriteMode,
-  readEventV3ControlState,
-  repairEventV3ControlPair,
-} from "./control.ts";
+  type LiveEventLedgerRouteV3,
+  liveEventLedgerRouteFromControlV3,
+  liveInstanceIdV3,
+  runtimeCapabilityProfileCurrentV3,
+} from "./live-route-observer.ts";
 import type { HookSignalV3 } from "./producers/hook.ts";
 import type { TurnRitualEvidenceV3 } from "./producers/hook-base.ts";
-import { type RecordHookSignalV3Result, recordHookSignalV3 } from "./producers/recorder.ts";
+import {
+  type ReconcilePendingRuntimeContextV3Result,
+  type RecordHookSignalV3Result,
+  reconcilePendingRuntimeContextV3,
+  recordHookSignalV3,
+} from "./producers/recorder.ts";
+import { livePlatformV3 } from "./runtime-identity.ts";
+
+export {
+  type LiveEventLedgerRouteV3,
+  liveInstanceIdV3,
+  nativeInstanceIdV3,
+} from "./live-route-observer.ts";
+export { liveEventV3BuildId, livePlatformV3 } from "./runtime-identity.ts";
 
 export const LIVE_HOOK_V3_PRODUCER_ID = "prd_agent-hook" as const;
 export const LIVE_COMMAND_V3_PRODUCER_ID = "prd_session-tee" as const;
 
-export type LiveEventLedgerRouteV3 =
-  | { state: "v3"; mode: EventV3WriteMode; build_id: `build_${string}` }
-  | { state: "blocked"; reason: string };
-
 /**
  * Resolve the V3-only ledger route. A root without an initialized V3 control
- * packet is blocked; no producer or consumer may fall back to an older ledger.
+ * packet is blocked; no mutating producer may fall back to an older ledger.
  * Manifest-first crashes are repaired from the immutable packet and every
  * other invalid state closes the writer gate.
  */
@@ -28,36 +40,32 @@ export function resolveLiveEventLedgerRouteV3(coordRoot: string): LiveEventLedge
   let control = readEventV3ControlState(coordRoot);
   if (control.state === "closed") return { state: "blocked", reason: "v3_not_initialized" };
   if (control.state === "repairable") control = repairEventV3ControlPair(coordRoot);
-  if (control.state !== "candidate" && control.state !== "active") {
-    return { state: "blocked", reason: `${control.state}:${control.reason}` };
+  if (
+    (control.state === "invalid" && control.reason === "genesis_schema_digest_incompatible") ||
+    ((control.state === "candidate" || control.state === "active") &&
+      !runtimeCapabilityProfileCurrentV3(control))
+  ) {
+    try {
+      control = refreshIncompatibleEventLedgerV3(coordRoot).control;
+    } catch (error) {
+      return {
+        state: "blocked",
+        reason: `runtime_refresh_failed:${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
   }
-  const buildId = liveEventV3BuildId(control.genesis.profile.harnery_commit);
-  if (!control.genesis.profile.producer_build_ids.includes(buildId)) {
-    return { state: "blocked", reason: "live_producer_build_not_approved" };
+  if (control.state === "active") {
+    // Bound the epoch every producer must re-validate: an oversized active
+    // segment rotates into the archive here, on the shared route boundary.
+    // Rotation failure never blocks recording; the current epoch stays live.
+    try {
+      const rotated = rotateOversizedEventLedgerV3(coordRoot);
+      if (rotated.state === "rotated" && rotated.control) control = rotated.control;
+    } catch {
+      // The oversized epoch keeps serving; the next route resolution retries.
+    }
   }
-  return { state: "v3", mode: control.state, build_id: buildId };
-}
-
-export function liveEventV3BuildId(harneryCommit: string): `build_${string}` {
-  const exact = harneryCommit.normalize("NFC");
-  if (/^[a-zA-Z0-9._-]{1,120}$/.test(exact)) return `build_${exact}`;
-  return `build_${createHash("sha256").update(exact).digest("hex")}`;
-}
-
-export function liveInstanceIdV3(instanceId: string): `inst_${string}` {
-  if (/^inst_[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return instanceId as `inst_${string}`;
-  if (/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return `inst_${instanceId}`;
-  return `inst_${createHash("sha256").update(instanceId.normalize("NFC")).digest("hex")}`;
-}
-
-/**
- * The adapter-native id a canonical `inst_*` id carries, for display and for
- * joins against native-keyed records. Only the direct prefix form round-trips:
- * a hashed id has no recoverable native form and is returned unchanged, so
- * never treat this as a guaranteed inverse of `liveInstanceIdV3`.
- */
-export function nativeInstanceIdV3(instanceId: string): string {
-  return instanceId.startsWith("inst_") ? instanceId.slice("inst_".length) : instanceId;
+  return liveEventLedgerRouteFromControlV3(control);
 }
 
 export function hookSignalV3(eventName: string): HookSignalV3 | undefined {
@@ -65,6 +73,7 @@ export function hookSignalV3(eventName: string): HookSignalV3 | undefined {
     case "session-start":
     case "session-end":
     case "user-prompt-submit":
+    case "after-agent-response":
     case "stop":
     case "stop-failure":
     case "pre-tool-use":
@@ -158,6 +167,23 @@ export function recordLiveHookSignalV3(input: {
   });
 }
 
+export function reconcileLivePendingRuntimeContextV3(input: {
+  coordRoot: string;
+  route: Extract<LiveEventLedgerRouteV3, { state: "v3" }>;
+  nativeSessionId: string;
+  finalAttempt?: boolean;
+}): ReconcilePendingRuntimeContextV3Result {
+  return reconcilePendingRuntimeContextV3({
+    coordRoot: input.coordRoot,
+    mode: input.route.mode,
+    nativeSessionId: input.nativeSessionId,
+    producer_id: LIVE_HOOK_V3_PRODUCER_ID,
+    build_id: input.route.build_id,
+    platform: livePlatformV3(),
+    finalAttempt: input.finalAttempt,
+  });
+}
+
 /**
  * Open the child generation named by a native SubagentStart event.
  *
@@ -245,10 +271,3 @@ export function recordLiveDelegatedChildSessionV3(input: {
   });
   return started;
 }
-
-export function livePlatformV3(): "linux" | "windows" | "macos" | "unknown" {
-  if (process.platform === "linux") return "linux";
-  if (process.platform === "win32") return "windows";
-  if (process.platform === "darwin") return "macos";
-  return "unknown";
-}

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

@@ -6,6 +6,7 @@ import {
   fsyncSync,
   mkdirSync,
   openSync,
+  readdirSync,
   readFileSync,
   renameSync,
   statSync,
@@ -13,7 +14,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { hostname } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import type { Adapter } from "../../../adapter.ts";
 import { fsyncParentDirectory } from "../../../workflow/durable-record.ts";
 import { acquireNoClobberLease } from "../../../workflow/workspaces/leases.ts";
@@ -21,6 +22,7 @@ import {
   type AuthorityReceiptV3,
   type AuthorityReconcilerV3,
   type AuthorityTransactionV3,
+  authorityRecoveryIntentPathV3,
   buildAuthorityTransactionV3,
   publishAuthorityTransactionV3,
   reconcileAuthorityTransactionV3,
@@ -78,6 +80,11 @@ interface CoordinationRecorderStateV3 {
   pending?: PendingCoordinationTransactionV3;
 }
 
+export interface PendingCoordinationTransactionV3Location {
+  producer_state_file: string;
+  transaction: AuthorityTransactionV3;
+}
+
 export interface RecordCoordinationAuthorityV3Input<
   S extends CoordinationAuthoritySignalV3 = CoordinationAuthoritySignalV3,
 > {
@@ -141,6 +148,9 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
 
   const rootId = control.genesis.event.scope.root_id as `root_${string}`;
   const epochId = control.genesis.profile.privacy_key_epoch;
+  const epochFence = {
+    expectedGenesisId: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  };
   const rootContext = fingerprintContextV3(input.coordRoot, rootId, undefined, epochId);
   const producerSource = normalizeNativeIdV3(
     rootContext,
@@ -170,6 +180,17 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
       state.attestation_id = hook.attestation_id;
     }
     if (state?.pending) {
+      if (
+        existsSync(
+          authorityRecoveryIntentPathV3(input.coordRoot, state.pending.transaction.transaction_id),
+        )
+      ) {
+        return {
+          state: "pending_transaction",
+          transaction_id: state.pending.transaction.transaction_id,
+          mutation_kind: state.pending.transaction.mutation.kind,
+        };
+      }
       if (state.pending.source_id !== sourceId) {
         // A writer that died mid-commit leaves `pending` owned by an
         // observation that will never retry (hook observations are one-shot).
@@ -180,11 +201,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
         // still refuses rather than guessing at a conflicting mutation.
         const stale = state.pending;
         try {
-          publishAuthorityTransactionV3(input.coordRoot, stale.transaction);
+          publishAuthorityTransactionV3(input.coordRoot, stale.transaction, epochFence);
           reconcileAuthorityTransactionV3(
             input.coordRoot,
             stale.transaction.transaction_id,
             input.reconciler,
+            epochFence,
           );
         } catch {
           return {
@@ -203,11 +225,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
         publishCoordinationState(path, state);
       } else {
         const pending = state.pending;
-        publishAuthorityTransactionV3(input.coordRoot, pending.transaction);
+        publishAuthorityTransactionV3(input.coordRoot, pending.transaction, epochFence);
         const receipt = reconcileAuthorityTransactionV3(
           input.coordRoot,
           pending.transaction.transaction_id,
           input.reconciler,
+          epochFence,
         );
         const event = eventFromTransaction(pending.transaction);
         applyCoordinationEvent(state, pending.source_id, pending.transaction, event);
@@ -307,11 +330,12 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
     if (input.signal === "wait-ended" && waitId) delete state.open_waits[waitId];
     state.pending = { source_id: sourceId, transaction };
     publishCoordinationState(path, state);
-    publishAuthorityTransactionV3(input.coordRoot, transaction);
+    publishAuthorityTransactionV3(input.coordRoot, transaction, epochFence);
     const receipt = reconcileAuthorityTransactionV3(
       input.coordRoot,
       transaction.transaction_id,
       input.reconciler,
+      epochFence,
     );
     applyCoordinationEvent(state, sourceId, transaction, normalized.event);
     state.pending = undefined;
@@ -322,6 +346,68 @@ export function recordCoordinationAuthorityV3<S extends CoordinationAuthoritySig
   }
 }
 
+/** Locate the one private producer state that owns a pending authority transaction. */
+export function findPendingCoordinationTransactionV3(
+  coordRoot: string,
+  transactionId: string,
+): PendingCoordinationTransactionV3Location | null {
+  const directory = coordinationProducerDirectory(coordRoot);
+  if (!existsSync(directory)) return null;
+  const matches = readdirSync(directory)
+    .filter((name) => /^hid_[a-f0-9]{64}\.json$/.test(name))
+    .sort()
+    .flatMap((name) => {
+      const state = readCoordinationState(join(directory, name));
+      return state.pending?.transaction.transaction_id === transactionId
+        ? [{ producer_state_file: name, transaction: state.pending.transaction }]
+        : [];
+    });
+  if (matches.length > 1) {
+    throw new Error("authority transaction is pending in more than one coordination producer");
+  }
+  return matches[0] ?? null;
+}
+
+/** Clear one transaction from its exact producer state after durable quarantine is established. */
+export function withPendingCoordinationTransactionRecoveryV3<T>(
+  coordRoot: string,
+  producerStateFile: string,
+  transaction: AuthorityTransactionV3,
+  allowAlreadyCleared: boolean,
+  operation: (control: { clearPending: () => "cleared" | "already_cleared" }) => T,
+): T {
+  if (!/^hid_[a-f0-9]{64}\.json$/.test(producerStateFile)) {
+    throw new Error("coordination producer state file is invalid");
+  }
+  const path = join(coordinationProducerDirectory(coordRoot), basename(producerStateFile));
+  if (!existsSync(path)) throw new Error("coordination producer state is missing");
+  const lease = acquireCoordinationLease(coordRoot, path);
+  try {
+    const state = readCoordinationState(path);
+    if (!state.pending && !allowAlreadyCleared) {
+      throw new Error("coordination producer no longer owns the pending transaction");
+    }
+    if (state.pending) {
+      if (
+        state.pending.transaction.transaction_id !== transaction.transaction_id ||
+        canonicalJsonV3(state.pending.transaction) !== canonicalJsonV3(transaction)
+      ) {
+        throw new Error("coordination producer pending transaction changed during recovery");
+      }
+    }
+    return operation({
+      clearPending: () => {
+        if (!state.pending) return "already_cleared";
+        state.pending = undefined;
+        publishCoordinationState(path, state);
+        return "cleared";
+      },
+    });
+  } finally {
+    lease.release();
+  }
+}
+
 function newCoordinationState<S extends CoordinationAuthoritySignalV3>(
   input: RecordCoordinationAuthorityV3Input<S>,
   hook: NonNullable<ReturnType<typeof readJoinableHookProducerStateV3>>,
@@ -392,12 +478,11 @@ function eventFromTransaction(transaction: AuthorityTransactionV3): EventV3 {
 }
 
 function coordinationStatePath(coordRoot: string, producerSource: `hid_${string}`): string {
-  return join(
-    resolve(coordRoot),
-    EVENT_V3_LEDGER_RELATIVE_ROOT,
-    "private-producers/agent-coord",
-    `${producerSource}.json`,
-  );
+  return join(coordinationProducerDirectory(coordRoot), `${producerSource}.json`);
+}
+
+function coordinationProducerDirectory(coordRoot: string): string {
+  return join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT, "private-producers/agent-coord");
 }
 
 function acquireCoordinationLease(coordRoot: string, statePath: string) {