harnery 0.45.1 → 0.46.0

package/src/core/context/observation.ts

@@ -1,11 +1,13 @@
 /**
  * Repository observation contract shared by context recovery and workflow proof.
  *
- * This module has no runtime imports so read-only consumers (the Codec
- * dashboard, proof readers) can use it without reaching the Git-running
- * snapshot code in ./index.ts.
+ * This module runs no Git and touches no files, so read-only consumers (the
+ * Codec dashboard, proof readers) can use it without reaching the
+ * Git-running snapshot code in ./index.ts.
  */
 
+import { isAbsolute } from "node:path";
+
 export type RepoObservation = "ok" | "unavailable" | "partial";
 
 export interface RepoSnapshot {
@@ -20,10 +22,39 @@ export interface RepoSnapshot {
   dirty_paths_truncated?: boolean;
 }
 
-/** Only explicitly successful observations can establish repository drift. */
-export function observationsComparable(
-  a: { observation?: string },
-  b: { observation?: string },
-): boolean {
-  return a.observation === "ok" && b.observation === "ok";
+/**
+ * Every reason two snapshots cannot establish repository drift. Only an empty
+ * list lets a caller compare branch, HEAD and dirty paths; anything else
+ * leaves the whole comparison unknown.
+ */
+export function repoComparisonProblems(
+  a: RepoSnapshot,
+  b: RepoSnapshot,
+  labels: readonly [string, string],
+): string[] {
+  const sides = [
+    [labels[0], a],
+    [labels[1], b],
+  ] as const;
+  const failed = sides.flatMap(([label, repo]) =>
+    repo.observation === "ok"
+      ? []
+      : [
+          // Snapshots recorded before observations existed carry none.
+          `${label} snapshot is ${repo.observation ?? "unavailable"}${repo.observation_detail ? ` (${repo.observation_detail})` : ""}`,
+        ],
+  );
+  if (failed.length > 0) return failed;
+  const problems: string[] = [];
+  if (a.dirty_paths_truncated || b.dirty_paths_truncated) {
+    problems.push("dirty path list is truncated");
+  }
+  if (!a.root || !b.root || !isAbsolute(a.root) || !isAbsolute(b.root)) {
+    problems.push("repository root is unknown");
+  } else if (a.root !== b.root) {
+    problems.push("repository roots differ");
+  }
+  if (!a.branch?.trim() || !b.branch?.trim()) problems.push("branch is unknown");
+  if (!a.head?.trim() || !b.head?.trim()) problems.push("HEAD is unknown");
+  return problems;
 }

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/runtime-build.ts

@@ -40,3 +40,65 @@ export function currentHarneryRuntimeBuild(): string {
 export function harneryPackageRoot(): string {
   return resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
 }
+
+export interface HarneryBuild {
+  version: string;
+  revision: string;
+}
+
+/** The installed package version and runtime revision; "unknown" when unreadable. */
+export function installedHarneryBuild(): HarneryBuild {
+  let version = "unknown";
+  let revision = "unknown";
+  try {
+    const manifest = JSON.parse(
+      readFileSync(resolve(harneryPackageRoot(), "package.json"), "utf8"),
+    ) as { version?: unknown };
+    if (typeof manifest.version === "string" && manifest.version.length <= 100)
+      version = manifest.version;
+  } catch {
+    // Missing package metadata cannot establish that a running build is current.
+  }
+  try {
+    revision = currentHarneryRuntimeBuild();
+  } catch {
+    // Status still reports the unavailable build instead of guessing a match.
+  }
+  return { version, revision };
+}
+
+export interface ServiceBuildStatus {
+  running_build: HarneryBuild | null;
+  installed_build: HarneryBuild;
+  restart_needed: boolean;
+  build_status: string;
+}
+
+/** A missing or unknown running build, or any difference, means restart. */
+export function serviceBuildStatus(recorded: unknown): ServiceBuildStatus {
+  const installed_build = installedHarneryBuild();
+  const candidate = recorded as Partial<HarneryBuild> | undefined;
+  const known = (value: unknown): value is string =>
+    typeof value === "string" && value.length > 0 && value.length <= 100 && value !== "unknown";
+  const running_build =
+    candidate && known(candidate.version) && known(candidate.revision)
+      ? { version: candidate.version, revision: candidate.revision }
+      : null;
+  const restart_needed =
+    running_build === null ||
+    installed_build.version === "unknown" ||
+    installed_build.revision === "unknown" ||
+    running_build.version !== installed_build.version ||
+    running_build.revision !== installed_build.revision;
+  return {
+    running_build,
+    installed_build,
+    restart_needed,
+    build_status:
+      running_build === null
+        ? "running build unknown; restart needed"
+        : restart_needed
+          ? "restart needed"
+          : "current",
+  };
+}