harnery 0.34.1 → 0.36.0

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

@@ -9,10 +9,13 @@ import {
   openSync,
   readFileSync,
   renameSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
+import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
+import { acquireNoClobberLease } from "../../workflow/workspaces/leases.ts";
 import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
 import { ADAPTER_CAPABILITY_PROFILES_V3 } from "./capabilities.ts";
 import {
@@ -23,11 +26,13 @@ import {
   EVENT_V3_GENESIS_MANIFEST,
   type EventV3ControlState,
   readEventV3ControlState,
-  repairEventV3ControlPair,
 } from "./control.ts";
+import { repairEventV3ControlPair } from "./control-writer.ts";
 import { loadOrCreateFingerprintKeyStoreV3 } from "./fingerprint-keys.ts";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
-import { liveEventV3BuildId, livePlatformV3 } from "./live-routing.ts";
+import { resolveEventLedgerRotateActiveBytesV3 } from "./rotation-config.ts";
+import { currentHarneryRuntimeBuild, liveEventV3BuildId, livePlatformV3 } from "./runtime-build.ts";
+import { drainReadyEventsV3 } from "./writer.ts";
 
 export interface InitializeEventLedgerV3Input {
   coordRoot: string;
@@ -47,6 +52,17 @@ export interface InitializeEventLedgerV3Result {
   control: Extract<EventV3ControlState, { state: "active" }>;
 }
 
+export interface RefreshIncompatibleEventLedgerV3Result {
+  state: "current" | "refreshed";
+  archived_epoch?: string;
+  control: Extract<EventV3ControlState, { state: "active" }>;
+}
+
+const BOOTSTRAP_LEASE_RETRIES = 12;
+const BOOTSTRAP_LEASE_RETRY_MS = 25;
+const BOOTSTRAP_LEASE_STALE_MS = 10_000;
+const bootstrapSleepCell = new Int32Array(new SharedArrayBuffer(4));
+
 /**
  * Ensure programmatic Harnery entry points have the same universal V3
  * boundary as `harn init`. Only a genuinely absent control pair is created;
@@ -79,6 +95,133 @@ export function ensureEventLedgerV3(
  */
 export function initializeEventLedgerV3(
   input: InitializeEventLedgerV3Input,
+): InitializeEventLedgerV3Result {
+  return withBootstrapLease(input.coordRoot, () => initializeEventLedgerV3Locked(input));
+}
+
+/**
+ * Replace only a runtime-incompatible epoch that the current code can name
+ * exactly. Corruption and ambiguous control failures remain closed for the
+ * explicit recovery command.
+ */
+export function refreshIncompatibleEventLedgerV3(
+  coordRoot: string,
+): RefreshIncompatibleEventLedgerV3Result {
+  const root = resolve(coordRoot);
+  return withBootstrapLease(root, () => {
+    const current = readEventV3ControlState(root);
+    if (current.state === "active" && runtimeCapabilityProfileCurrent(current)) {
+      return { state: "current", control: current };
+    }
+    const refreshable =
+      (current.state === "invalid" && current.reason === "genesis_schema_digest_incompatible") ||
+      ((current.state === "candidate" || current.state === "active") &&
+        !runtimeCapabilityProfileCurrent(current));
+    if (!refreshable) {
+      const reason = "reason" in current ? `${current.state}:${current.reason}` : current.state;
+      throw new Error(`event_v3_runtime_refresh_refused:${reason}`);
+    }
+    const configPath = join(root, ".harnery", "config.jsonc");
+    const initialized = initializeEventLedgerV3Locked({
+      coordRoot: root,
+      harneryBuild: currentHarneryRuntimeBuild(),
+      hostBuild: repositoryBuild(root),
+      configDigest: sha256V3(
+        existsSync(configPath) ? readFileSync(configPath) : Buffer.from("{}\n"),
+      ),
+      approvalRecordId: "harnery-runtime-v3-auto-refresh",
+      forceNewEpoch: true,
+    });
+    return {
+      state: "refreshed",
+      ...(initialized.archived_epoch ? { archived_epoch: initialized.archived_epoch } : {}),
+      control: initialized.control,
+    };
+  });
+}
+
+export interface RotateOversizedEventLedgerV3Result {
+  state: "rotated" | "not_oversized" | "not_active" | "disabled";
+  active_bytes: number;
+  threshold_bytes: number;
+  archived_epoch?: string;
+  control?: Extract<EventV3ControlState, { state: "active" }>;
+}
+
+/**
+ * Archive a valid oversized epoch intact and start a fresh one.
+ *
+ * Every canonical read validates the complete epoch, and hook producers are
+ * one-shot processes, so an unbounded active segment makes every hook's cold
+ * read scale with all history. Rotation bounds that cost: the replaced epoch
+ * (events, spool, producer states, manifests) moves whole into the V3
+ * archive, live sessions re-onboard into the new epoch on their next signal,
+ * and the writer's epoch fence keeps in-flight producers of the old epoch
+ * from ever committing into the new one. Only a currently valid, active
+ * ledger rotates; integrity failures stay closed for the explicit recovery
+ * command. The threshold comes from the isolated Event V3 config resolver
+ * unless the caller pins one; a non-positive threshold disables rotation.
+ */
+export function rotateOversizedEventLedgerV3(
+  coordRoot: string,
+  options: { thresholdBytes?: number } = {},
+): RotateOversizedEventLedgerV3Result {
+  const root = resolve(coordRoot);
+  const threshold = options.thresholdBytes ?? resolveEventLedgerRotateActiveBytesV3(root);
+  const activePath = join(root, ".harnery", "ledgers", "v3", "active.ndjson");
+  const measure = () => {
+    try {
+      return statSync(activePath).size;
+    } catch {
+      return 0;
+    }
+  };
+  if (threshold <= 0) {
+    return { state: "disabled", active_bytes: measure(), threshold_bytes: threshold };
+  }
+  if (measure() < threshold) {
+    return { state: "not_oversized", active_bytes: measure(), threshold_bytes: threshold };
+  }
+  return withBootstrapLease(root, () => {
+    const activeBytes = measure();
+    if (activeBytes < threshold) {
+      return { state: "not_oversized", active_bytes: activeBytes, threshold_bytes: threshold };
+    }
+    const current = readEventV3ControlState(root);
+    if (current.state !== "active") {
+      return { state: "not_active", active_bytes: activeBytes, threshold_bytes: threshold };
+    }
+    // Flush durable ready rows into the epoch they were produced for, so the
+    // archive carries them committed instead of stranded in its spool.
+    try {
+      drainReadyEventsV3(root);
+    } catch {
+      // A busy append lease only leaves rows in the archived spool; rotation
+      // itself stays safe.
+    }
+    const configPath = join(root, ".harnery", "config.jsonc");
+    const initialized = initializeEventLedgerV3Locked({
+      coordRoot: root,
+      harneryBuild: currentHarneryRuntimeBuild(),
+      hostBuild: repositoryBuild(root),
+      configDigest: sha256V3(
+        existsSync(configPath) ? readFileSync(configPath) : Buffer.from("{}\n"),
+      ),
+      approvalRecordId: "harnery-runtime-v3-size-rotation",
+      forceNewEpoch: true,
+    });
+    return {
+      state: "rotated",
+      active_bytes: activeBytes,
+      threshold_bytes: threshold,
+      ...(initialized.archived_epoch ? { archived_epoch: initialized.archived_epoch } : {}),
+      control: initialized.control,
+    };
+  });
+}
+
+function initializeEventLedgerV3Locked(
+  input: InitializeEventLedgerV3Input,
 ): InitializeEventLedgerV3Result {
   const root = resolve(input.coordRoot);
   let current = readEventV3ControlState(root);
@@ -147,6 +290,56 @@ export function initializeEventLedgerV3(
   };
 }
 
+function runtimeCapabilityProfileCurrent(
+  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));
+}
+
+function withBootstrapLease<T>(coordRoot: string, operation: () => T): T {
+  const root = resolve(coordRoot);
+  const authority = createHash("sha256").update(root).digest("hex");
+  let lease: ReturnType<typeof acquireNoClobberLease> | undefined;
+  for (let attempt = 0; attempt < BOOTSTRAP_LEASE_RETRIES; attempt += 1) {
+    try {
+      lease = acquireNoClobberLease({
+        path: join(root, ".harnery", "private", "event-v3-bootstrap-lease"),
+        scope: "event-v3-bootstrap",
+        authoritySha256: authority,
+        staleAfterMs: BOOTSTRAP_LEASE_STALE_MS,
+        validateStaleOwner: (owner) => owner.host === hostname() && !pidIsAlive(owner.pid),
+      });
+      break;
+    } catch (error) {
+      if (attempt === BOOTSTRAP_LEASE_RETRIES - 1) throw error;
+      Atomics.wait(bootstrapSleepCell, 0, 0, BOOTSTRAP_LEASE_RETRY_MS);
+    }
+  }
+  if (!lease) throw new Error("event_v3_bootstrap_lease_busy");
+  try {
+    return operation();
+  } finally {
+    lease.release();
+  }
+}
+
+function pidIsAlive(pid: number): boolean {
+  if (!Number.isSafeInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
 function activateCandidateEpoch(
   root: string,
   candidate: CandidateGenesisManifestV3,

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

@@ -14,6 +14,21 @@ export type AdapterWaitKindV3 =
   | "rate_limit"
   | "unknown";
 
+export const ADAPTER_WAIT_KINDS_V3: readonly AdapterWaitKindV3[] = [
+  "permission",
+  "needs_input",
+  "decision",
+  "approval",
+  "scheduled",
+  "rate_limit",
+  "unknown",
+] as const;
+
+export interface WaitKindCapabilityV3 {
+  span_delivery: CapabilitySupportV3;
+  turn_completeness: CapabilitySupportV3;
+}
+
 export type BaseAdapterSignalV3 =
   | "session_start"
   | "session_end"
@@ -69,7 +84,7 @@ const BASE_SIGNAL_SUPPORT: Record<Adapter, Record<BaseAdapterSignalV3, Capabilit
     turn_id: "conditional",
     permission: "native",
     post_compaction: "native",
-    context_usage: "unsupported",
+    context_usage: "conditional",
   },
   codex: {
     ...SHARED_SIGNAL_SUPPORT,
@@ -77,7 +92,7 @@ const BASE_SIGNAL_SUPPORT: Record<Adapter, Record<BaseAdapterSignalV3, Capabilit
     turn_id: "native",
     permission: "native",
     post_compaction: "native",
-    context_usage: "unsupported",
+    context_usage: "derived",
   },
   cursor: {
     ...SHARED_SIGNAL_SUPPORT,
@@ -91,7 +106,7 @@ const BASE_SIGNAL_SUPPORT: Record<Adapter, Record<BaseAdapterSignalV3, Capabilit
     shell: "conditional",
     permission: "conditional",
     post_compaction: "unsupported",
-    context_usage: "unsupported",
+    context_usage: "conditional",
   },
 };
 
@@ -159,6 +174,25 @@ export function adapterTurnWaitCountSupportV3(_adapter: Adapter): CapabilitySupp
   return "unsupported";
 }
 
+/**
+ * Per-kind wait matrix for native adapter turns. Span delivery and independent
+ * completed-turn completeness are deliberately separate: observing a span
+ * never proves that an absent span means zero.
+ */
+export function adapterWaitCoverageMatrixV3(
+  adapter: Adapter,
+): Record<AdapterWaitKindV3, WaitKindCapabilityV3> {
+  return Object.fromEntries(
+    ADAPTER_WAIT_KINDS_V3.map((kind) => [
+      kind,
+      {
+        span_delivery: adapterWaitKindSupportV3(adapter, kind),
+        turn_completeness: adapterTurnWaitCountSupportV3(adapter),
+      },
+    ]),
+  ) as Record<AdapterWaitKindV3, WaitKindCapabilityV3>;
+}
+
 /**
  * Local Cursor sessions expose the generic tool channel. Cloud/private-worker
  * sessions cannot guarantee whole-turn delivery because hooks may start only

package/src/core/events/v3/control-witness.ts

@@ -0,0 +1,339 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
+import { canonicalJsonV3, type FingerprintV3, fingerprintV3, sha256V3 } from "./canonical.ts";
+import type { ActivationManifestV3, CandidateGenesisManifestV3 } from "./control.ts";
+import { fingerprintContextV3 } from "./fingerprint-keys.ts";
+import {
+  advanceEventV3AppendValidationCheckpointV3,
+  EVENT_V3_CONTROL_CHECKPOINT_RELATIVE_PATH,
+  EVENT_V3_CONTROL_WITNESS_RELATIVE_PATH,
+  type EventV3AppendValidationCheckpointV3,
+  type EventV3AuthorityStorageVersionV3,
+  eventV3AuthorityStorageVersionV3,
+  eventV3ControlCheckpointPathV3,
+  eventV3ControlWitnessPathV3,
+  parseEventV3AppendValidationCheckpointV3,
+} from "./reader.ts";
+
+export { EVENT_V3_CONTROL_CHECKPOINT_RELATIVE_PATH, EVENT_V3_CONTROL_WITNESS_RELATIVE_PATH };
+
+interface EventV3ControlWitnessPayload {
+  format: "harnery-event-v3-control-witness";
+  format_version: 1;
+  genesis_id: `gex_${string}`;
+  activation_id: `act_${string}`;
+  genesis_event_id: `evt_${string}`;
+  activation_event_id: `evt_${string}`;
+  genesis_manifest_digest: `sha256:${string}`;
+  activation_manifest_digest: `sha256:${string}`;
+  candidate_manifest_digest: `sha256:${string}`;
+  privacy_key_epoch: `pep_${string}`;
+  root_id: `root_${string}`;
+  storage: EventV3AuthorityStorageVersionV3;
+  checkpoint_digest: `sha256:${string}`;
+}
+
+interface EventV3ControlWitness {
+  payload: EventV3ControlWitnessPayload;
+  authentication: FingerprintV3;
+}
+
+export interface ActiveControlWitnessBindingV3 {
+  genesis: CandidateGenesisManifestV3;
+  activation: ActivationManifestV3;
+  candidate_manifest_digest: `sha256:${string}`;
+}
+
+/** True only when one authenticated witness names this exact active control pair and storage. */
+export function activeControlWitnessMatchesV3(
+  coordRoot: string,
+  binding: ActiveControlWitnessBindingV3,
+): boolean {
+  try {
+    const before = eventV3AuthorityStorageVersionV3(coordRoot);
+    const witness = readAuthenticatedWitnessV3(coordRoot);
+    if (!witness) return false;
+    const expected = witnessPayloadV3(binding, before, witness.payload.checkpoint_digest);
+    if (canonicalJsonV3(witness.payload) !== canonicalJsonV3(expected)) return false;
+    const after = eventV3AuthorityStorageVersionV3(coordRoot);
+    return sameStorageVersion(before, after);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Publish a witness only when the storage validated by the caller is still current.
+ * Failure is intentionally silent: the next read retains the canonical full-scan fallback.
+ */
+export function publishActiveControlWitnessV3(
+  coordRoot: string,
+  binding: ActiveControlWitnessBindingV3,
+  validatedStorage: EventV3AuthorityStorageVersionV3,
+  checkpoint: EventV3AppendValidationCheckpointV3,
+): boolean {
+  try {
+    const current = eventV3AuthorityStorageVersionV3(coordRoot);
+    if (!sameStorageVersion(validatedStorage, current)) return false;
+    return publishWitnessV3(
+      coordRoot,
+      witnessPayloadV3(binding, current, checkpointDigestV3(checkpoint)),
+      checkpoint,
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Capture a previously authenticated witness before the append lease mutates storage.
+ * The returned payload is safe to advance only while the caller continues to hold that lease.
+ */
+export function readAdvanceableControlWitnessV3(coordRoot: string):
+  | {
+      payload: EventV3ControlWitnessPayload;
+      checkpoint: EventV3AppendValidationCheckpointV3;
+    }
+  | undefined {
+  try {
+    const storage = eventV3AuthorityStorageVersionV3(coordRoot);
+    const witness = readAuthenticatedWitnessV3(coordRoot);
+    if (!witness || !sameStorageVersion(witness.payload.storage, storage)) return undefined;
+    const checkpoint = readAuthenticatedCheckpointV3(coordRoot, witness.payload.checkpoint_digest);
+    return checkpoint && checkpoint.validated_active_bytes === storage.active_bytes
+      ? { payload: witness.payload, checkpoint }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Advance a lease-held witness after durable appends without changing writer success semantics. */
+export function advanceControlWitnessV3(
+  coordRoot: string,
+  prior: {
+    payload: EventV3ControlWitnessPayload;
+    checkpoint: EventV3AppendValidationCheckpointV3;
+  },
+  currentGenesisId: string | undefined,
+): boolean {
+  try {
+    if (currentGenesisId !== prior.payload.genesis_id) return false;
+    const storageBeforeValidation = eventV3AuthorityStorageVersionV3(coordRoot);
+    const checkpoint = advanceEventV3AppendValidationCheckpointV3(coordRoot, prior.checkpoint);
+    if (!checkpoint) return false;
+    const storage = eventV3AuthorityStorageVersionV3(coordRoot);
+    if (
+      storageBeforeValidation.fingerprint !== storage.fingerprint ||
+      prior.payload.storage.stable_fingerprint !== storage.stable_fingerprint ||
+      checkpoint.validated_active_bytes !== storage.active_bytes
+    ) {
+      return false;
+    }
+    return publishWitnessV3(
+      coordRoot,
+      {
+        ...prior.payload,
+        storage,
+        checkpoint_digest: checkpointDigestV3(checkpoint),
+      },
+      checkpoint,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function witnessPayloadV3(
+  binding: ActiveControlWitnessBindingV3,
+  storage: EventV3AuthorityStorageVersionV3,
+  checkpointDigest: `sha256:${string}`,
+): EventV3ControlWitnessPayload {
+  const scope = binding.genesis.event.scope as { root_id: `root_${string}` };
+  return {
+    format: "harnery-event-v3-control-witness",
+    format_version: 1,
+    genesis_id: binding.genesis.event.payload.genesis_id as `gex_${string}`,
+    activation_id: binding.activation.activation_id,
+    genesis_event_id: binding.genesis.event.event_id as `evt_${string}`,
+    activation_event_id: binding.activation.event.event_id as `evt_${string}`,
+    genesis_manifest_digest: sha256V3(canonicalJsonV3(binding.genesis)),
+    activation_manifest_digest: sha256V3(canonicalJsonV3(binding.activation)),
+    candidate_manifest_digest: binding.candidate_manifest_digest,
+    privacy_key_epoch: binding.genesis.profile.privacy_key_epoch,
+    root_id: scope.root_id,
+    storage,
+    checkpoint_digest: checkpointDigest,
+  };
+}
+
+function readAuthenticatedWitnessV3(coordRoot: string): EventV3ControlWitness | undefined {
+  const path = eventV3ControlWitnessPathV3(coordRoot);
+  if (!existsSync(path)) return undefined;
+  const raw = readFileSync(path, "utf8");
+  const value: unknown = JSON.parse(raw);
+  const witness = parseWitnessV3(value);
+  if (`${canonicalJsonV3(witness)}\n` !== raw) return undefined;
+  const expected = authenticatePayloadV3(coordRoot, witness.payload);
+  return canonicalJsonV3(witness.authentication) === canonicalJsonV3(expected)
+    ? witness
+    : undefined;
+}
+
+function publishWitnessV3(
+  coordRoot: string,
+  payload: EventV3ControlWitnessPayload,
+  checkpoint: EventV3AppendValidationCheckpointV3,
+): boolean {
+  if (!publishCanonicalFileV3(eventV3ControlCheckpointPathV3(coordRoot), checkpoint)) return false;
+  const witness: EventV3ControlWitness = {
+    payload,
+    authentication: authenticatePayloadV3(coordRoot, payload),
+  };
+  return publishCanonicalFileV3(eventV3ControlWitnessPathV3(coordRoot), witness);
+}
+
+function publishCanonicalFileV3(path: string, value: unknown): boolean {
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, `${canonicalJsonV3(value)}\n`, "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, path);
+    fsyncParentDirectory(path);
+    return true;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function readAuthenticatedCheckpointV3(
+  coordRoot: string,
+  expectedDigest: `sha256:${string}`,
+): EventV3AppendValidationCheckpointV3 | undefined {
+  try {
+    const raw = readFileSync(eventV3ControlCheckpointPathV3(coordRoot), "utf8");
+    const value: unknown = JSON.parse(raw);
+    if (
+      `${canonicalJsonV3(value)}\n` !== raw ||
+      sha256V3(canonicalJsonV3(value)) !== expectedDigest
+    ) {
+      return undefined;
+    }
+    return parseEventV3AppendValidationCheckpointV3(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function checkpointDigestV3(checkpoint: EventV3AppendValidationCheckpointV3): `sha256:${string}` {
+  return sha256V3(canonicalJsonV3(checkpoint));
+}
+
+function authenticatePayloadV3(
+  coordRoot: string,
+  payload: EventV3ControlWitnessPayload,
+): FingerprintV3 {
+  const context = fingerprintContextV3(
+    coordRoot,
+    payload.root_id,
+    undefined,
+    payload.privacy_key_epoch,
+  );
+  return fingerprintV3(context, "control-state-witness", payload, "root");
+}
+
+function parseWitnessV3(value: unknown): EventV3ControlWitness {
+  const envelope = object(value);
+  if (Object.keys(envelope).sort().join("\0") !== "authentication\0payload") {
+    throw new Error("control witness envelope is invalid");
+  }
+  const payload = object(envelope.payload);
+  const expectedPayloadKeys = [
+    "activation_event_id",
+    "activation_id",
+    "activation_manifest_digest",
+    "candidate_manifest_digest",
+    "checkpoint_digest",
+    "format",
+    "format_version",
+    "genesis_event_id",
+    "genesis_id",
+    "genesis_manifest_digest",
+    "privacy_key_epoch",
+    "root_id",
+    "storage",
+  ];
+  if (Object.keys(payload).sort().join("\0") !== expectedPayloadKeys.sort().join("\0")) {
+    throw new Error("control witness payload shape is invalid");
+  }
+  const storage = object(payload.storage);
+  if (Object.keys(storage).sort().join("\0") !== "active_bytes\0fingerprint\0stable_fingerprint") {
+    throw new Error("control witness storage shape is invalid");
+  }
+  if (
+    payload.format !== "harnery-event-v3-control-witness" ||
+    payload.format_version !== 1 ||
+    !token(payload.genesis_id, "gex_") ||
+    !token(payload.activation_id, "act_") ||
+    !token(payload.genesis_event_id, "evt_") ||
+    !token(payload.activation_event_id, "evt_") ||
+    !digest(payload.genesis_manifest_digest) ||
+    !digest(payload.activation_manifest_digest) ||
+    !digest(payload.candidate_manifest_digest) ||
+    !digest(payload.checkpoint_digest) ||
+    !token(payload.privacy_key_epoch, "pep_") ||
+    !token(payload.root_id, "root_") ||
+    !digest(storage.fingerprint) ||
+    !digest(storage.stable_fingerprint) ||
+    !Number.isSafeInteger(storage.active_bytes) ||
+    (storage.active_bytes as number) < 0
+  ) {
+    throw new Error("control witness payload is invalid");
+  }
+  const authentication = object(envelope.authentication);
+  return {
+    payload: payload as unknown as EventV3ControlWitnessPayload,
+    authentication: authentication as unknown as FingerprintV3,
+  };
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("control witness value is not an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function token(value: unknown, prefix: string): value is string {
+  return (
+    typeof value === "string" && value.startsWith(prefix) && /^[a-zA-Z0-9._-]{1,160}$/.test(value)
+  );
+}
+
+function digest(value: unknown): value is `sha256:${string}` {
+  return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+
+function sameStorageVersion(
+  left: EventV3AuthorityStorageVersionV3,
+  right: EventV3AuthorityStorageVersionV3,
+): boolean {
+  return left.fingerprint === right.fingerprint && left.active_bytes === right.active_bytes;
+}

package/src/core/events/v3/control-writer.ts

@@ -0,0 +1,16 @@
+import { type EventV3ControlState, readEventV3ControlState } from "./control.ts";
+import { writeEventV3 } from "./writer.ts";
+
+/** Repair only a manifest-first crash by appending the exact pre-minted event. */
+export function repairEventV3ControlPair(coordRoot: string): EventV3ControlState {
+  const control = readEventV3ControlState(coordRoot);
+  if (control.state !== "repairable") return control;
+  const event =
+    control.reason === "genesis_event_missing" ? control.genesis.event : control.activation?.event;
+  if (!event) return { state: "invalid", reason: "repair_event_unavailable" };
+  const result = writeEventV3(coordRoot, event);
+  if (result.state !== "committed") {
+    return { state: "invalid", reason: "control_event_repair_not_committed" };
+  }
+  return readEventV3ControlState(coordRoot);
+}