harnery 0.35.0 → 0.36.0

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

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

@@ -3,11 +3,16 @@ import { join } from "node:path";
 import { buildEventV3 } from "./builder.ts";
 import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
 import type { EventV3 } from "./contract.ts";
+import { activeControlWitnessMatchesV3, publishActiveControlWitnessV3 } from "./control-witness.ts";
 import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
 import { activationIdV3, eventIdV3, genesisIdV3 } from "./ids.ts";
-import { type ReadLedgerV3Result, readLedgerV3 } from "./reader.ts";
+import {
+  eventV3AuthorityStorageVersionV3,
+  type ReadLedgerV3Result,
+  readEventV3AppendValidationCheckpointV3,
+  readLedgerV3,
+} from "./reader.ts";
 import { validateEventV3 } from "./validate.ts";
-import { writeEventV3 } from "./writer.ts";
 
 export const EVENT_V3_GENESIS_MANIFEST = ".harnery/ledgers/v3/genesis.json" as const;
 export const EVENT_V3_ACTIVATION_MANIFEST = ".harnery/ledgers/v3/activation.json" as const;
@@ -210,6 +215,26 @@ export function validateActivationManifestV3(
  * Resolve the session/evidence gate from exact control-file and ledger-event pairs.
  * This function never repairs or creates state. Any ambiguity keeps the gate closed.
  */
+/**
+ * The live epoch's genesis id from the immutable manifest, or undefined when
+ * no valid genesis is published. This is the cheap epoch-identity read the
+ * writer fence uses: one small canonical file, never the event history.
+ */
+export function liveGenesisIdV3(coordRoot: string): `gex_${string}` | undefined {
+  return genesisIdFromManifestV3(join(coordRoot, EVENT_V3_GENESIS_MANIFEST));
+}
+
+/** Same read for a caller that already holds the manifest path (the writer's drain). */
+export function genesisIdFromManifestV3(genesisPath: string): `gex_${string}` | undefined {
+  if (!existsSync(genesisPath)) return undefined;
+  const genesis = readGenesisManifest(genesisPath);
+  if (!genesis.ok) return undefined;
+  const genesisId = genesis.value.event.payload.genesis_id;
+  return typeof genesisId === "string" && genesisId.startsWith("gex_")
+    ? (genesisId as `gex_${string}`)
+    : undefined;
+}
+
 export function readEventV3ControlState(coordRoot: string): EventV3ControlState {
   const genesisPath = join(coordRoot, EVENT_V3_GENESIS_MANIFEST);
   const activationPath = join(coordRoot, EVENT_V3_ACTIVATION_MANIFEST);
@@ -232,6 +257,25 @@ export function readEventV3ControlState(coordRoot: string): EventV3ControlState
   if (!genesisResult.ok) return { state: "invalid", reason: genesisResult.reason };
   const genesis = genesisResult.value;
   const candidateDigest = candidateManifestDigestV3(genesis);
+  const activationForWitness = hasActivation
+    ? readActivationManifest(activationPath, genesis, candidateDigest)
+    : undefined;
+  if (
+    activationForWitness?.ok &&
+    activeControlWitnessMatchesV3(coordRoot, {
+      genesis,
+      activation: activationForWitness.value,
+      candidate_manifest_digest: candidateDigest,
+    })
+  ) {
+    return {
+      state: "active",
+      genesis,
+      activation: activationForWitness.value,
+      candidate_manifest_digest: candidateDigest,
+    };
+  }
+  const storageBeforeValidation = eventV3AuthorityStorageVersionV3(coordRoot);
   const ledger = readControlLedger(coordRoot);
   if (!ledger.complete) {
     return { state: "invalid", reason: "ledger_integrity_failure" };
@@ -253,7 +297,8 @@ export function readEventV3ControlState(coordRoot: string): EventV3ControlState
     return { state: "candidate", genesis, candidate_manifest_digest: candidateDigest };
   }
 
-  const activationResult = readActivationManifest(activationPath, genesis, candidateDigest);
+  const activationResult =
+    activationForWitness ?? readActivationManifest(activationPath, genesis, candidateDigest);
   if (!activationResult.ok) return { state: "invalid", reason: activationResult.reason };
   const activation = activationResult.value;
   const activationPair = exactEventPair(
@@ -271,12 +316,17 @@ export function readEventV3ControlState(coordRoot: string): EventV3ControlState
       activation,
     };
   }
-  return {
+  const active: Extract<EventV3ControlState, { state: "active" }> = {
     state: "active",
     genesis,
     activation,
     candidate_manifest_digest: candidateDigest,
   };
+  const checkpoint = readEventV3AppendValidationCheckpointV3(coordRoot);
+  if (checkpoint) {
+    publishActiveControlWitnessV3(coordRoot, active, storageBeforeValidation, checkpoint);
+  }
+  return active;
 }
 
 export function eventV3WriteGateOpen(coordRoot: string, mode: EventV3WriteMode): boolean {
@@ -284,20 +334,6 @@ export function eventV3WriteGateOpen(coordRoot: string, mode: EventV3WriteMode):
   return mode === "candidate" ? control.state === "candidate" : control.state === "active";
 }
 
-/** 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);
-}
-
 export function candidateProfileDigestV3(profile: CandidateProfileV3): `sha256:${string}` {
   return sha256V3(canonicalJsonV3(profile));
 }