harnery 0.35.0 → 0.36.0

package/src/core/events/v3/coordination-transaction-recovery.ts

@@ -0,0 +1,477 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
+import {
+  type AuthorityTransactionV3,
+  authorityRecoveryIntentPathV3,
+  readAuthorityTransactionV3,
+} from "./authority-outbox.ts";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import {
+  findPendingCoordinationTransactionV3,
+  withPendingCoordinationTransactionRecoveryV3,
+} from "./producers/coordination-recorder.ts";
+import { readLedgerV3 } from "./reader.ts";
+import { ensureEventV3Layout } from "./writer.ts";
+
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const TX_PATTERN = /^txn_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const INSTANCE_PATTERN = /^inst_[a-zA-Z0-9._-]{1,128}$/;
+const PRODUCER_STATE_PATTERN = /^hid_[a-f0-9]{64}\.json$/;
+const APPROVAL_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,199}$/;
+
+export type CoordinationTransactionRecoveryStep =
+  | "intent_published"
+  | "transaction_quarantined"
+  | "producer_pending_cleared"
+  | "outbox_ready_removed"
+  | "receipt_committed";
+
+interface CoordinationTransactionQuarantineCommonV3 {
+  transaction_id: `txn_${string}`;
+  transaction_digest: `sha256:${string}`;
+  event_id: string;
+  event_row_digest: `sha256:${string}`;
+  actor_instance_id: string;
+  subject_instance_id: string;
+  mutation_kind: string;
+  expected_prior_state_digest: `sha256:${string}`;
+  desired_state_digest: `sha256:${string}`;
+  observed_current_state_digest: `sha256:${string}`;
+  approval_record_id: string;
+  producer_state_file: string;
+  reason: "current_state_conflict";
+  created_at: string;
+}
+
+export interface CoordinationTransactionQuarantineIntentV3
+  extends CoordinationTransactionQuarantineCommonV3 {
+  format: "harnery-v3-coordination-transaction-quarantine-intent";
+  format_version: 1;
+}
+
+export interface CoordinationTransactionQuarantineReceiptV3
+  extends CoordinationTransactionQuarantineCommonV3 {
+  format: "harnery-v3-coordination-transaction-quarantine-receipt";
+  format_version: 1;
+  completed_at: string;
+  quarantine_file: string;
+}
+
+export interface QuarantineConflictingCoordinationTransactionV3Input {
+  transaction_id: string;
+  actor_instance_id: string;
+  observed_current_state_digest: `sha256:${string}`;
+  approval_record_id: string;
+  now?: () => Date;
+  onStep?: (step: CoordinationTransactionRecoveryStep) => void;
+}
+
+/**
+ * Abandon one authority transaction only after proving that normal recovery is
+ * impossible and that its event never entered the ledger or ready spool.
+ */
+export function quarantineConflictingCoordinationTransactionV3(
+  coordRoot: string,
+  input: QuarantineConflictingCoordinationTransactionV3Input,
+): CoordinationTransactionQuarantineReceiptV3 {
+  assertTransactionId(input.transaction_id);
+  assertInstanceId(input.actor_instance_id);
+  assertDigest(input.observed_current_state_digest, "observed current state digest");
+  assertApprovalRecordId(input.approval_record_id);
+  const paths = recoveryPaths(coordRoot, input.transaction_id);
+  ensureRecoveryLayout(paths);
+
+  if (existsSync(paths.receipt)) {
+    const receipt = readReceipt(paths.receipt);
+    assertRecoveryBinding(receipt, input);
+    removeIfExists(paths.intent);
+    return receipt;
+  }
+
+  let intent: CoordinationTransactionQuarantineIntentV3;
+  let transaction: AuthorityTransactionV3;
+  let serializedTransaction: string;
+  const recoveryAlreadyStarted = existsSync(paths.intent);
+  if (recoveryAlreadyStarted) {
+    intent = readIntent(paths.intent);
+    assertRecoveryBinding(intent, input);
+    ({ transaction, serialized: serializedTransaction } = readQuarantinedOrReadyTransaction(paths));
+    assertTransactionMatchesIntent(transaction, serializedTransaction, intent);
+  } else {
+    if (!existsSync(paths.ready)) {
+      throw new Error("authority transaction is not ready for recovery");
+    }
+    transaction = readAuthorityTransactionV3(paths.ready);
+    serializedTransaction = readFileSync(paths.ready, "utf8");
+    if (transaction.actor_instance_id !== input.actor_instance_id) {
+      throw new Error("authority transaction actor does not match the recovery target");
+    }
+    if (
+      input.observed_current_state_digest === transaction.expected_prior_state_digest ||
+      input.observed_current_state_digest === transaction.desired_state_digest
+    ) {
+      throw new Error("authority transaction is still reconcilable and cannot be quarantined");
+    }
+    assertEventNeverCommitted(coordRoot, transaction.event_id, paths.committed);
+    const pending = findPendingCoordinationTransactionV3(coordRoot, transaction.transaction_id);
+    if (!pending) throw new Error("authority transaction has no matching pending producer state");
+    if (canonicalJsonV3(pending.transaction) !== canonicalJsonV3(transaction)) {
+      throw new Error("authority outbox and producer state transactions do not match");
+    }
+    const createdAt = (input.now ?? (() => new Date()))().toISOString();
+    intent = {
+      format: "harnery-v3-coordination-transaction-quarantine-intent",
+      format_version: 1,
+      ...transactionFacts(transaction, serializedTransaction),
+      observed_current_state_digest: input.observed_current_state_digest,
+      approval_record_id: input.approval_record_id,
+      producer_state_file: pending.producer_state_file,
+      reason: "current_state_conflict",
+      created_at: createdAt,
+    };
+  }
+
+  return withPendingCoordinationTransactionRecoveryV3(
+    coordRoot,
+    intent.producer_state_file,
+    transaction,
+    recoveryAlreadyStarted,
+    ({ clearPending }) => {
+      assertEventNeverCommitted(coordRoot, transaction.event_id, paths.committed);
+      publishCanonicalExclusive(paths.intent, intent);
+      input.onStep?.("intent_published");
+
+      publishSerializedExclusive(paths.quarantine, serializedTransaction);
+      input.onStep?.("transaction_quarantined");
+
+      clearPending();
+      input.onStep?.("producer_pending_cleared");
+
+      if (existsSync(paths.ready)) {
+        if (readFileSync(paths.ready, "utf8") !== serializedTransaction) {
+          throw new Error("authority ready transaction changed during recovery");
+        }
+        unlinkSync(paths.ready);
+        fsyncParentDirectory(paths.ready);
+      }
+      input.onStep?.("outbox_ready_removed");
+
+      const receipt: CoordinationTransactionQuarantineReceiptV3 = {
+        format: "harnery-v3-coordination-transaction-quarantine-receipt",
+        format_version: 1,
+        ...commonIntentFields(intent),
+        completed_at: (input.now ?? (() => new Date()))().toISOString(),
+        quarantine_file: `quarantine/${input.transaction_id}.json`,
+      };
+      if (Date.parse(receipt.completed_at) < Date.parse(receipt.created_at)) {
+        throw new Error("authority transaction recovery clock moved backwards");
+      }
+      publishCanonicalExclusive(paths.receipt, receipt);
+      input.onStep?.("receipt_committed");
+      removeIfExists(paths.intent);
+      return receipt;
+    },
+  );
+}
+
+function transactionFacts(
+  transaction: AuthorityTransactionV3,
+  serialized: string,
+): Pick<
+  CoordinationTransactionQuarantineCommonV3,
+  | "transaction_id"
+  | "transaction_digest"
+  | "event_id"
+  | "event_row_digest"
+  | "actor_instance_id"
+  | "subject_instance_id"
+  | "mutation_kind"
+  | "expected_prior_state_digest"
+  | "desired_state_digest"
+> {
+  return {
+    transaction_id: transaction.transaction_id,
+    transaction_digest: sha256V3(serialized),
+    event_id: transaction.event_id,
+    event_row_digest: sha256V3(transaction.event_row),
+    actor_instance_id: transaction.actor_instance_id,
+    subject_instance_id: transaction.subject_instance_id,
+    mutation_kind: transaction.mutation.kind,
+    expected_prior_state_digest: transaction.expected_prior_state_digest,
+    desired_state_digest: transaction.desired_state_digest,
+  };
+}
+
+function commonIntentFields(
+  intent: CoordinationTransactionQuarantineIntentV3,
+): CoordinationTransactionQuarantineCommonV3 {
+  const { format: _format, format_version: _formatVersion, ...common } = intent;
+  return common;
+}
+
+function assertEventNeverCommitted(
+  coordRoot: string,
+  eventId: string,
+  committedReceiptPath: string,
+): void {
+  if (existsSync(committedReceiptPath)) {
+    throw new Error("authority transaction already has a committed receipt");
+  }
+  if (readLedgerV3(coordRoot).events.some(({ event }) => event.event_id === eventId)) {
+    throw new Error("authority transaction event is already present in the ledger");
+  }
+  const spool = ensureEventV3Layout(coordRoot).spool;
+  for (const name of readdirSync(spool)
+    .filter((entry) => entry.endsWith(".ready"))
+    .sort()) {
+    let event: unknown;
+    try {
+      event = JSON.parse(readFileSync(join(spool, name), "utf8"));
+    } catch {
+      throw new Error("V3 ready spool is unreadable during authority recovery");
+    }
+    if (
+      event &&
+      typeof event === "object" &&
+      !Array.isArray(event) &&
+      (event as Record<string, unknown>).event_id === eventId
+    ) {
+      throw new Error("authority transaction event is already present in the ready spool");
+    }
+  }
+}
+
+function readQuarantinedOrReadyTransaction(paths: ReturnType<typeof recoveryPaths>): {
+  transaction: AuthorityTransactionV3;
+  serialized: string;
+} {
+  const path = existsSync(paths.quarantine) ? paths.quarantine : paths.ready;
+  if (!existsSync(path)) throw new Error("authority transaction recovery lost its durable record");
+  return { transaction: readAuthorityTransactionV3(path), serialized: readFileSync(path, "utf8") };
+}
+
+function assertTransactionMatchesIntent(
+  transaction: AuthorityTransactionV3,
+  serialized: string,
+  intent: CoordinationTransactionQuarantineIntentV3,
+): void {
+  const facts = transactionFacts(transaction, serialized);
+  for (const [key, value] of Object.entries(facts)) {
+    if (intent[key as keyof typeof intent] !== value) {
+      throw new Error("authority transaction recovery intent no longer matches its transaction");
+    }
+  }
+}
+
+function assertRecoveryBinding(
+  record: CoordinationTransactionQuarantineIntentV3 | CoordinationTransactionQuarantineReceiptV3,
+  input: QuarantineConflictingCoordinationTransactionV3Input,
+): void {
+  if (
+    record.transaction_id !== input.transaction_id ||
+    record.actor_instance_id !== input.actor_instance_id ||
+    record.approval_record_id !== input.approval_record_id
+  ) {
+    throw new Error("authority transaction recovery record does not match this request");
+  }
+}
+
+function recoveryPaths(coordRoot: string, transactionId: string) {
+  const ledger = ensureEventV3Layout(coordRoot);
+  const root = join(ledger.root, "authority-recoveries");
+  return {
+    root,
+    quarantineRoot: join(root, "quarantine"),
+    intent: authorityRecoveryIntentPathV3(coordRoot, transactionId),
+    receipt: join(root, `${transactionId}.committed.json`),
+    quarantine: join(root, "quarantine", `${transactionId}.json`),
+    ready: join(ledger.authorityOutbox, `${transactionId}.ready.json`),
+    committed: join(ledger.authorityOutbox, `${transactionId}.committed.json`),
+  };
+}
+
+function ensureRecoveryLayout(paths: ReturnType<typeof recoveryPaths>): void {
+  for (const path of [paths.root, paths.quarantineRoot]) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    chmodSync(path, 0o700);
+  }
+}
+
+function publishCanonicalExclusive(path: string, value: unknown): void {
+  publishSerializedExclusive(path, `${canonicalJsonV3(value)}\n`);
+}
+
+function publishSerializedExclusive(path: string, serialized: string): void {
+  if (existsSync(path)) {
+    if (readFileSync(path, "utf8") !== serialized) {
+      throw new Error("authority transaction recovery record conflicts with an existing record");
+    }
+    return;
+  }
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, serialized, "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    linkSync(temporary, path);
+    fsyncParentDirectory(path);
+    unlinkSync(temporary);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function readIntent(path: string): CoordinationTransactionQuarantineIntentV3 {
+  return readCanonicalRecord(path, validateIntent);
+}
+
+function readReceipt(path: string): CoordinationTransactionQuarantineReceiptV3 {
+  return readCanonicalRecord(path, validateReceipt);
+}
+
+function readCanonicalRecord<T>(path: string, validate: (value: unknown) => T): T {
+  let text: string;
+  let parsed: unknown;
+  try {
+    text = readFileSync(path, "utf8");
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error("authority transaction recovery record is malformed");
+  }
+  const value = validate(parsed);
+  if (text !== `${canonicalJsonV3(value)}\n`) {
+    throw new Error("authority transaction recovery record is not canonical");
+  }
+  return value;
+}
+
+function validateIntent(value: unknown): CoordinationTransactionQuarantineIntentV3 {
+  const record = validateCommon(value, ["format", "format_version"]);
+  if (
+    record.format !== "harnery-v3-coordination-transaction-quarantine-intent" ||
+    record.format_version !== 1
+  ) {
+    throw new Error("authority transaction recovery intent is invalid");
+  }
+  return record as unknown as CoordinationTransactionQuarantineIntentV3;
+}
+
+function validateReceipt(value: unknown): CoordinationTransactionQuarantineReceiptV3 {
+  const record = validateCommon(value, [
+    "completed_at",
+    "format",
+    "format_version",
+    "quarantine_file",
+  ]);
+  if (
+    record.format !== "harnery-v3-coordination-transaction-quarantine-receipt" ||
+    record.format_version !== 1 ||
+    !timestamp(record.completed_at) ||
+    Date.parse(String(record.completed_at)) < Date.parse(String(record.created_at)) ||
+    record.quarantine_file !== `quarantine/${record.transaction_id}.json`
+  ) {
+    throw new Error("authority transaction recovery receipt is invalid");
+  }
+  return record as unknown as CoordinationTransactionQuarantineReceiptV3;
+}
+
+function validateCommon(value: unknown, extraKeys: string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("authority transaction recovery record is invalid");
+  }
+  const record = value as Record<string, unknown>;
+  const commonKeys = [
+    "actor_instance_id",
+    "approval_record_id",
+    "created_at",
+    "desired_state_digest",
+    "event_id",
+    "event_row_digest",
+    "expected_prior_state_digest",
+    "mutation_kind",
+    "observed_current_state_digest",
+    "producer_state_file",
+    "reason",
+    "subject_instance_id",
+    "transaction_digest",
+    "transaction_id",
+  ];
+  if (Object.keys(record).sort().join("\0") !== [...commonKeys, ...extraKeys].sort().join("\0")) {
+    throw new Error("authority transaction recovery record has unsupported fields");
+  }
+  if (
+    typeof record.transaction_id !== "string" ||
+    !TX_PATTERN.test(record.transaction_id) ||
+    typeof record.transaction_digest !== "string" ||
+    !SHA256_PATTERN.test(record.transaction_digest) ||
+    typeof record.event_id !== "string" ||
+    record.event_id.length === 0 ||
+    typeof record.event_row_digest !== "string" ||
+    !SHA256_PATTERN.test(record.event_row_digest) ||
+    typeof record.actor_instance_id !== "string" ||
+    !INSTANCE_PATTERN.test(record.actor_instance_id) ||
+    typeof record.subject_instance_id !== "string" ||
+    !INSTANCE_PATTERN.test(record.subject_instance_id) ||
+    typeof record.mutation_kind !== "string" ||
+    record.mutation_kind.length === 0 ||
+    typeof record.expected_prior_state_digest !== "string" ||
+    !SHA256_PATTERN.test(record.expected_prior_state_digest) ||
+    typeof record.desired_state_digest !== "string" ||
+    !SHA256_PATTERN.test(record.desired_state_digest) ||
+    typeof record.observed_current_state_digest !== "string" ||
+    !SHA256_PATTERN.test(record.observed_current_state_digest) ||
+    typeof record.approval_record_id !== "string" ||
+    !APPROVAL_PATTERN.test(record.approval_record_id) ||
+    typeof record.producer_state_file !== "string" ||
+    !PRODUCER_STATE_PATTERN.test(record.producer_state_file) ||
+    record.reason !== "current_state_conflict" ||
+    !timestamp(record.created_at)
+  ) {
+    throw new Error("authority transaction recovery record values are invalid");
+  }
+  return record;
+}
+
+function assertTransactionId(value: string): asserts value is `txn_${string}` {
+  if (!TX_PATTERN.test(value)) throw new Error("authority transaction ID is invalid");
+}
+
+function assertInstanceId(value: string): void {
+  if (!INSTANCE_PATTERN.test(value)) throw new Error("authority recovery actor is invalid");
+}
+
+function assertDigest(value: string, label: string): void {
+  if (!SHA256_PATTERN.test(value)) throw new Error(`${label} is invalid`);
+}
+
+function assertApprovalRecordId(value: string): void {
+  if (!APPROVAL_PATTERN.test(value)) throw new Error("approval record ID is invalid");
+}
+
+function timestamp(value: unknown): boolean {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+
+function removeIfExists(path: string): void {
+  if (!existsSync(path)) return;
+  unlinkSync(path);
+  fsyncParentDirectory(path);
+}

package/src/core/events/v3/coordination-view.ts

@@ -68,6 +68,17 @@ export class CoordinationViewV3Error extends Error {
   }
 }
 
+/**
+ * A canonical ledger read is immutable and readLedgerV3 returns the same result
+ * object until the authority changes. Several web helpers derive the
+ * coordination view independently during one server render; without this
+ * cache each helper reduces the complete append-only history again.
+ *
+ * Weak keys bind the projection lifetime to the reader snapshot. A newly
+ * appended event produces a new ReadLedgerV3Result and therefore a fresh view.
+ */
+const coordinationViewCacheV3 = new WeakMap<ReadLedgerV3Result, CoordinationViewV3>();
+
 /** Read the complete V3 catalog and derive the disposable coordination view. */
 export function readCoordinationViewV3(coordRoot: string): CoordinationViewV3 {
   return projectCoordinationViewV3(readLedgerV3(coordRoot));
@@ -78,6 +89,9 @@ export function readCoordinationViewV3(coordRoot: string): CoordinationViewV3 {
  * finalization, web, and Codec adapters. This function performs no writes.
  */
 export function projectCoordinationViewV3(read: ReadLedgerV3Result): CoordinationViewV3 {
+  const cached = coordinationViewCacheV3.get(read);
+  if (cached) return cached;
+
   const safety = reduceSafetyProjectionV3(read);
   const starts = new Map<string, Extract<EventV3, { event_type: "session.started" }>>();
   const eventGeneration = new Map<string, string>();
@@ -169,7 +183,7 @@ export function projectCoordinationViewV3(read: ReadLedgerV3Result): Coordinatio
     }
   }
 
-  return {
+  const view: CoordinationViewV3 = {
     projection_version: EVENT_V3_COORDINATION_VIEW_VERSION,
     contract_major: 2,
     reducer_build_id: EVENT_V3_SAFETY_REDUCER_BUILD,
@@ -182,6 +196,8 @@ export function projectCoordinationViewV3(read: ReadLedgerV3Result): Coordinatio
     decisions: safety.decisions,
     health: safety.health,
   };
+  coordinationViewCacheV3.set(read, view);
+  return view;
 }
 
 /** Refuse authority decisions while still allowing callers to render diagnostics. */

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

@@ -1,6 +1,6 @@
 /** Generated by scripts/generate-event-v3-contract.ts. Do not edit. */
 export const EVENT_V3_SCHEMA_DIGEST =
-  "sha256:297ed06021fd046c6f1a2061de4341c7765840bf4f0d9b597ad7c9d78b7a9ba6" as const;
+  "sha256:bdcee8d7839add0c786740ba9d5cfd0b6573f0ad4974bf53272737468734aa36" as const;
 export const EVENT_V3_GENERATED_CORE_TYPES = [
   "ledger.genesis",
   "ledger.activated",

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

@@ -92,10 +92,10 @@ export {
   type EventV3WriteMode,
   eventV3WriteGateOpen,
   readEventV3ControlState,
-  repairEventV3ControlPair,
   validateActivationManifestV3,
   validateCandidateGenesisManifestV3,
 } from "./control.ts";
+export { repairEventV3ControlPair } from "./control-writer.ts";
 export {
   type CoordinationGenerationViewV3,
   type CoordinationViewV3,
@@ -179,11 +179,14 @@ export {
   writeLiveDisplayV3,
 } from "./live-feed.ts";
 export type { LiveCoordinationObservationV3 } from "./live-observation.ts";
+export {
+  type LiveEventLedgerRouteV3,
+  observeLiveEventLedgerRouteV3,
+} from "./live-route-observer.ts";
 export {
   hookSignalV3,
   LIVE_COMMAND_V3_PRODUCER_ID,
   LIVE_HOOK_V3_PRODUCER_ID,
-  type LiveEventLedgerRouteV3,
   liveEventV3BuildId,
   liveInstanceIdV3,
   livePlatformV3,

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;
+}