harnery 0.34.1 → 0.36.0

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

@@ -186,7 +186,7 @@ export function digestEventV3AuthorityDirectoryV3(root: string): `sha256:${strin
   return `sha256:${createHash("sha256").update(canonicalJsonV3(files)).digest("hex")}`;
 }
 
-interface PendingAdvance {
+export interface PendingAdvance {
   event_id: string;
   next_schema_digest: string;
   position: LedgerFrameV3["position"];
@@ -228,6 +228,29 @@ interface LedgerStorageVersionV3 {
   };
 }
 
+export interface EventV3AuthorityStorageVersionV3 {
+  fingerprint: `sha256:${string}`;
+  stable_fingerprint: `sha256:${string}`;
+  active_bytes: number;
+}
+
+export interface EventV3AppendValidationCheckpointV3 {
+  format: "harnery-event-v3-append-validation-checkpoint";
+  format_version: 1;
+  reader_build: string;
+  accepted_schema_digests: string[];
+  seen_event_ids: string[];
+  producer_sequences: Array<[string, number]>;
+  attestation_ids: string[];
+  clocks: Array<[string, number, string?]>;
+  event_count: number;
+  genesis_id?: string;
+  active_schema_digest?: string;
+  pending?: PendingAdvance;
+  active_segment_ordinal: number;
+  validated_active_bytes: number;
+}
+
 interface LedgerValidationStateV3 {
   diagnostics: LedgerDiagnosticV3[];
   events: PositionedEventV3[];
@@ -238,6 +261,7 @@ interface LedgerValidationStateV3 {
   producer_sequences: Map<string, number>;
   attestations: Set<string>;
   clocks: Map<string, { observed_at_ms: number; monotonic_ns?: bigint }>;
+  event_count: number;
   first_position?: LedgerFrameV3["position"];
   genesis_id?: string;
   active_schema_digest?: string;
@@ -255,6 +279,10 @@ const MAX_CACHED_LEDGER_READS = 4;
 const ledgerReadCacheV3 = new Map<string, CachedLedgerReadV3>();
 
 export const EVENT_V3_LEDGER_RELATIVE_ROOT = ".harnery/ledgers/v3" as const;
+export const EVENT_V3_CONTROL_WITNESS_RELATIVE_PATH =
+  `${EVENT_V3_LEDGER_RELATIVE_ROOT}/control-state-witness.json` as const;
+export const EVENT_V3_CONTROL_CHECKPOINT_RELATIVE_PATH =
+  `${EVENT_V3_LEDGER_RELATIVE_ROOT}/control-state-validation.json` as const;
 
 export function eventV3Paths(coordRoot: string) {
   const root = join(resolve(coordRoot), EVENT_V3_LEDGER_RELATIVE_ROOT);
@@ -271,6 +299,128 @@ export function eventV3ActiveWatchPath(coordRoot: string): string {
   return eventV3Paths(coordRoot).active;
 }
 
+/** Stable auxiliary control-cache target; canonical event reads remain inside this module. */
+export function eventV3ControlWitnessPathV3(coordRoot: string): string {
+  return join(eventV3Paths(coordRoot).root, "control-state-witness.json");
+}
+
+/** Stable auxiliary validator-checkpoint target owned by the control witness. */
+export function eventV3ControlCheckpointPathV3(coordRoot: string): string {
+  return join(eventV3Paths(coordRoot).root, "control-state-validation.json");
+}
+
+/**
+ * Content-independent identity for the complete filesystem authority.
+ *
+ * The control witness authenticates this value after a complete validation.
+ * Any append, rewrite, inode replacement, catalog change, sealed-segment
+ * change, or recovery-record change produces a different fingerprint and
+ * sends the control reader back through the canonical full validation path.
+ */
+export function eventV3AuthorityStorageVersionV3(
+  coordRoot: string,
+): EventV3AuthorityStorageVersionV3 {
+  const storage = ledgerStorageVersionV3(coordRoot);
+  return {
+    fingerprint: sha256V3(storage.fingerprint),
+    stable_fingerprint: sha256V3(storage.stable_fingerprint),
+    active_bytes: storage.active?.size ?? 0,
+  };
+}
+
+/** Serialize the validator tail produced by the current complete cached read. */
+export function readEventV3AppendValidationCheckpointV3(
+  coordRoot: string,
+): EventV3AppendValidationCheckpointV3 | undefined {
+  const options: ReadLedgerV3Options = {};
+  const result = readLedgerV3(coordRoot, options);
+  if (!result.complete) return undefined;
+  const cached = ledgerReadCacheV3.get(ledgerReadCacheKeyV3(coordRoot, options));
+  if (!cached?.active || !cached.result.complete) return undefined;
+  return checkpointFromValidationStateV3(cached.validation_state, cached.active);
+}
+
+/**
+ * Validate only the bytes appended after an authenticated checkpoint.
+ * Unsupported or semantically invalid transitions return undefined so the
+ * control reader falls back to a complete canonical validation.
+ */
+export function advanceEventV3AppendValidationCheckpointV3(
+  coordRoot: string,
+  checkpoint: EventV3AppendValidationCheckpointV3,
+): EventV3AppendValidationCheckpointV3 | undefined {
+  const parsed = parseEventV3AppendValidationCheckpointV3(checkpoint);
+  if (!parsed) return undefined;
+  const storage = ledgerStorageVersionV3(coordRoot);
+  if (!storage.active || storage.active.size <= parsed.validated_active_bytes) return undefined;
+  const appended = readActiveRangeV3(
+    storage.active.path,
+    parsed.validated_active_bytes,
+    storage.active.size,
+    parsed.active_segment_ordinal,
+  );
+  if (!appended || appended.diagnostics.length > 0) return undefined;
+  const state = validationStateFromCheckpointV3(parsed);
+  validateLedgerFramesIntoStateV3(appended.frames, state);
+  if (state.diagnostics.length > 0) return undefined;
+  return checkpointFromValidationStateV3(state, {
+    bytes: storage.active.size,
+    path: storage.active.path,
+    segment_ordinal: parsed.active_segment_ordinal,
+  });
+}
+
+/** Parse an untrusted persisted checkpoint without weakening the writer fence. */
+export function parseEventV3AppendValidationCheckpointV3(
+  value: unknown,
+): EventV3AppendValidationCheckpointV3 | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const checkpoint = value as Partial<EventV3AppendValidationCheckpointV3>;
+  if (
+    checkpoint.format !== "harnery-event-v3-append-validation-checkpoint" ||
+    checkpoint.format_version !== 1 ||
+    typeof checkpoint.reader_build !== "string" ||
+    !Array.isArray(checkpoint.accepted_schema_digests) ||
+    !checkpoint.accepted_schema_digests.every((item) => typeof item === "string") ||
+    !Array.isArray(checkpoint.seen_event_ids) ||
+    !checkpoint.seen_event_ids.every((item) => typeof item === "string") ||
+    !Array.isArray(checkpoint.producer_sequences) ||
+    !checkpoint.producer_sequences.every(
+      (item) =>
+        Array.isArray(item) &&
+        item.length === 2 &&
+        typeof item[0] === "string" &&
+        Number.isSafeInteger(item[1]) &&
+        item[1] > 0,
+    ) ||
+    !Array.isArray(checkpoint.attestation_ids) ||
+    !checkpoint.attestation_ids.every((item) => typeof item === "string") ||
+    !Array.isArray(checkpoint.clocks) ||
+    !checkpoint.clocks.every(
+      (item) =>
+        Array.isArray(item) &&
+        (item.length === 2 || item.length === 3) &&
+        typeof item[0] === "string" &&
+        typeof item[1] === "number" &&
+        Number.isFinite(item[1]) &&
+        (item[2] === undefined || (typeof item[2] === "string" && /^\d+$/.test(item[2]))),
+    ) ||
+    !Number.isSafeInteger(checkpoint.event_count) ||
+    (checkpoint.event_count ?? -1) < 0 ||
+    !Number.isSafeInteger(checkpoint.active_segment_ordinal) ||
+    (checkpoint.active_segment_ordinal ?? 0) < 1 ||
+    !Number.isSafeInteger(checkpoint.validated_active_bytes) ||
+    (checkpoint.validated_active_bytes ?? -1) < 0 ||
+    (checkpoint.genesis_id !== undefined && typeof checkpoint.genesis_id !== "string") ||
+    (checkpoint.active_schema_digest !== undefined &&
+      typeof checkpoint.active_schema_digest !== "string") ||
+    !validPendingAdvanceV3(checkpoint.pending)
+  ) {
+    return undefined;
+  }
+  return checkpoint as EventV3AppendValidationCheckpointV3;
+}
+
 /** Read the complete V3 ledger through catalog-bound filesystem discovery. */
 export function readLedgerV3(
   coordRoot: string,
@@ -384,6 +534,7 @@ function validateLedgerFramesV3(
     producer_sequences: new Map(),
     attestations: new Set(),
     clocks: new Map(),
+    event_count: 0,
   };
   validateLedgerFramesIntoStateV3(frames, state);
   return { result: finishLedgerValidationV3(state, options, ledgerFramesBytesV3(frames)), state };
@@ -456,7 +607,7 @@ function validateLedgerFramesIntoStateV3(
         diagnostics.push(diagnostic("multiple_genesis", frame, shape.event_id));
         continue;
       }
-      if (events.length !== 0)
+      if (state.event_count !== 0)
         diagnostics.push(diagnostic("genesis_not_first", frame, shape.event_id));
       const payload = shape.payload;
       state.genesis_id = string(payload.genesis_id);
@@ -524,6 +675,7 @@ function validateLedgerFramesIntoStateV3(
     }
 
     events.push({ event, position: frame.position });
+    state.event_count += 1;
   }
 }
 
@@ -816,6 +968,95 @@ function isolateValidationStateV3(state: LedgerValidationStateV3): LedgerValidat
   };
 }
 
+function checkpointFromValidationStateV3(
+  state: LedgerValidationStateV3,
+  active: NonNullable<DiscoveredFramesV3["active"]>,
+): EventV3AppendValidationCheckpointV3 {
+  return {
+    format: "harnery-event-v3-append-validation-checkpoint",
+    format_version: 1,
+    reader_build: state.reader_build,
+    accepted_schema_digests: [...state.accepted].sort(),
+    seen_event_ids: [...state.seen_ids.keys()].sort(),
+    producer_sequences: [...state.producer_sequences.entries()].sort(([left], [right]) =>
+      left.localeCompare(right),
+    ),
+    attestation_ids: [...state.attestations].sort(),
+    clocks: [...state.clocks.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([clockId, clock]): [string, number, string?] =>
+        clock.monotonic_ns !== undefined
+          ? [clockId, clock.observed_at_ms, clock.monotonic_ns.toString()]
+          : [clockId, clock.observed_at_ms],
+      ),
+    event_count: state.event_count,
+    ...(state.genesis_id ? { genesis_id: state.genesis_id } : {}),
+    ...(state.active_schema_digest ? { active_schema_digest: state.active_schema_digest } : {}),
+    ...(state.pending
+      ? {
+          pending: {
+            ...state.pending,
+            position: { ...state.pending.position },
+          },
+        }
+      : {}),
+    active_segment_ordinal: active.segment_ordinal,
+    validated_active_bytes: active.bytes,
+  };
+}
+
+function validationStateFromCheckpointV3(
+  checkpoint: EventV3AppendValidationCheckpointV3,
+): LedgerValidationStateV3 {
+  return {
+    diagnostics: [],
+    events: [],
+    advances: [],
+    accepted: new Set(checkpoint.accepted_schema_digests),
+    reader_build: checkpoint.reader_build,
+    seen_ids: new Map(checkpoint.seen_event_ids.map((eventId) => [eventId, ""])),
+    producer_sequences: new Map(checkpoint.producer_sequences),
+    attestations: new Set(checkpoint.attestation_ids),
+    clocks: new Map(
+      checkpoint.clocks.map(([clockId, observedAtMs, monotonicNs]) => [
+        clockId,
+        {
+          observed_at_ms: observedAtMs,
+          ...(monotonicNs !== undefined ? { monotonic_ns: BigInt(monotonicNs) } : {}),
+        },
+      ]),
+    ),
+    event_count: checkpoint.event_count,
+    ...(checkpoint.genesis_id ? { genesis_id: checkpoint.genesis_id } : {}),
+    ...(checkpoint.active_schema_digest
+      ? { active_schema_digest: checkpoint.active_schema_digest }
+      : {}),
+    ...(checkpoint.pending
+      ? {
+          pending: {
+            ...checkpoint.pending,
+            position: { ...checkpoint.pending.position },
+          },
+        }
+      : {}),
+  };
+}
+
+function validPendingAdvanceV3(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const pending = value as Partial<PendingAdvance>;
+  return (
+    typeof pending.event_id === "string" &&
+    typeof pending.next_schema_digest === "string" &&
+    Boolean(pending.position) &&
+    Number.isSafeInteger(pending.position?.segment_ordinal) &&
+    Number.isSafeInteger(pending.position?.byte_offset) &&
+    (pending.position?.segment_ordinal ?? 0) > 0 &&
+    (pending.position?.byte_offset ?? -1) >= 0
+  );
+}
+
 function readActiveRangeV3(
   path: string,
   start: number,

package/src/core/events/v3/rotation-config.ts

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Default active-segment size that triggers automatic V3 epoch rotation. */
+export const DEFAULT_EVENT_LEDGER_ROTATE_ACTIVE_BYTES = 32 * 1024 * 1024;
+
+interface EventLedgerConfigFile {
+  events?: { rotate_active_bytes?: unknown };
+}
+
+/** Strip JSONC comments without treating comment-like text inside strings as syntax. */
+function stripJsonComments(input: string): string {
+  let out = "";
+  let index = 0;
+  let inString = false;
+  while (index < input.length) {
+    const character = input[index];
+    if (inString) {
+      out += character;
+      if (character === "\\" && index + 1 < input.length) {
+        out += input[index + 1];
+        index += 2;
+        continue;
+      }
+      if (character === '"') inString = false;
+      index++;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+      out += character;
+      index++;
+      continue;
+    }
+    if (character === "/" && input[index + 1] === "/") {
+      while (index < input.length && input[index] !== "\n") index++;
+      continue;
+    }
+    if (character === "/" && input[index + 1] === "*") {
+      index += 2;
+      while (index < input.length && !(input[index] === "*" && input[index + 1] === "/")) {
+        index++;
+      }
+      index += 2;
+      continue;
+    }
+    out += character;
+    index++;
+  }
+  return out;
+}
+
+function readConfig(path: string): EventLedgerConfigFile {
+  try {
+    const parsed = JSON.parse(stripJsonComments(readFileSync(path, "utf8"))) as unknown;
+    if (parsed && typeof parsed === "object") return parsed as EventLedgerConfigFile;
+  } catch {
+    // Missing or malformed config falls through to the next precedence layer.
+  }
+  return {};
+}
+
+function configuredThreshold(config: EventLedgerConfigFile): {
+  present: boolean;
+  value: unknown;
+} {
+  const events = config.events;
+  if (!events || typeof events !== "object") return { present: false, value: undefined };
+  return {
+    present: Object.hasOwn(events, "rotate_active_bytes"),
+    value: events.rotate_active_bytes,
+  };
+}
+
+/**
+ * Resolve the active-segment byte threshold without importing the host CLI's
+ * configuration layer. Event V3 is vendored into clients as a closed runtime,
+ * so this leaf reads only process state and JSONC files.
+ */
+export function resolveEventLedgerRotateActiveBytesV3(coordRoot: string | null): number {
+  const env = process.env.HARNERY_EVENT_V3_ROTATE_ACTIVE_BYTES;
+  if (env !== undefined) {
+    const parsed = Number.parseInt(env, 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+
+  if (coordRoot) {
+    const project = configuredThreshold(readConfig(join(coordRoot, ".harnery", "config.jsonc")));
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const userBase = xdg?.trim() ? xdg : join(homedir(), ".config");
+    const user = configuredThreshold(readConfig(join(userBase, "harnery", "config.jsonc")));
+    const configured = project.present ? project.value : user.value;
+    if (typeof configured === "number" && Number.isSafeInteger(configured)) return configured;
+  }
+
+  return DEFAULT_EVENT_LEDGER_ROTATE_ACTIVE_BYTES;
+}

package/src/core/events/v3/runtime-build.ts

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export { liveEventV3BuildId, livePlatformV3 } from "./runtime-identity.ts";
+
+/**
+ * Identify the code running this producer.
+ *
+ * Source checkouts use the exact Git commit. Published packages use their
+ * package version, which changes at the installation boundary without tying
+ * the authority profile to a machine-specific install path.
+ */
+export function currentHarneryRuntimeBuild(): string {
+  const root = harneryPackageRoot();
+  if (existsSync(resolve(root, ".git"))) {
+    const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      timeout: 5_000,
+    });
+    const commit = result.status === 0 ? result.stdout.trim() : "";
+    if (/^[0-9a-f]{40,64}$/.test(commit)) return commit;
+  }
+
+  const packagePath = resolve(root, "package.json");
+  if (existsSync(packagePath)) {
+    try {
+      const value = JSON.parse(readFileSync(packagePath, "utf8")) as { version?: unknown };
+      if (typeof value.version === "string" && /^[0-9A-Za-z._+-]{1,100}$/.test(value.version)) {
+        return `npm-${value.version}`;
+      }
+    } catch {
+      // A malformed package manifest falls through to a stable source digest.
+    }
+  }
+  throw new Error("harnery_runtime_build_unavailable");
+}
+
+export function harneryPackageRoot(): string {
+  return resolve(import.meta.dir, "../../../..");
+}

package/src/core/events/v3/runtime-identity.ts

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+
+/** Stable producer build id bound into one V3 epoch. */
+export function liveEventV3BuildId(harneryBuild: string): `build_${string}` {
+  const exact = harneryBuild.normalize("NFC");
+  if (/^[a-zA-Z0-9._-]{1,120}$/.test(exact)) return `build_${exact}`;
+  return `build_${createHash("sha256").update(exact).digest("hex")}`;
+}
+
+/** Platform recorded by runtime-owned V3 producers. */
+export function livePlatformV3(): "linux" | "windows" | "macos" | "unknown" {
+  if (process.platform === "linux") return "linux";
+  if (process.platform === "win32") return "windows";
+  if (process.platform === "darwin") return "macos";
+  return "unknown";
+}

package/src/core/events/v3/runtime-telemetry-capabilities.ts

@@ -0,0 +1,143 @@
+import type { Adapter } from "../../adapter.ts";
+import {
+  adapterSignalSupportV3,
+  type CapabilitySupportV3,
+  type CursorExecutionModeV3,
+} from "./capabilities.ts";
+
+export type RuntimeTelemetryChannelV3 =
+  | "context_usage"
+  | "wait_spans"
+  | "wait_completeness"
+  | "response_latency"
+  | "inference_timing";
+
+export type RuntimeTelemetryCompletenessV3 =
+  | "exact"
+  | "inferred"
+  | "percentage_only"
+  | "lower_bound"
+  | "unknown";
+
+export interface RuntimeTelemetryCapabilityValueV3 {
+  support: Exclude<CapabilitySupportV3, "unsupported">;
+  source: string;
+  completeness: RuntimeTelemetryCompletenessV3;
+}
+
+export type RuntimeTelemetryCapabilityObservationV3 =
+  | {
+      state: "observed";
+      value: RuntimeTelemetryCapabilityValueV3;
+      attestation: "native" | "derived" | "inferred";
+      confidence: "exact" | "high" | "medium" | "low";
+    }
+  | { state: "expected_but_missing"; capability: string; reason: string }
+  | { state: "unsupported"; capability: string };
+
+export type RuntimeContextCapabilityEvidenceV3 =
+  | {
+      state: "observed";
+      source: string;
+      attestation: "native" | "derived" | "inferred";
+      confidence: "exact" | "high" | "medium" | "low";
+      completeness?: "exact" | "inferred" | "percentage_only";
+    }
+  | { state: "partial"; reason: string }
+  | { state: "unsupported" };
+
+export interface RuntimeTelemetryCapabilityEvidenceV3 {
+  adapter: Adapter;
+  cursor_mode?: CursorExecutionModeV3;
+  context: RuntimeContextCapabilityEvidenceV3;
+  canonical_turn_boundaries: boolean;
+  independent_wait_completeness?: boolean;
+}
+
+export type RuntimeTelemetryCapabilitiesV3 = Record<
+  RuntimeTelemetryChannelV3,
+  RuntimeTelemetryCapabilityObservationV3
+>;
+
+/**
+ * Resolve the telemetry support that one runtime session can actually prove.
+ *
+ * This is deliberately separate from AdapterCapabilityProfileV3. The static
+ * profile gates the event contract; this projection describes effective
+ * session evidence without moving a genesis-approved digest when a local
+ * source is missing, late, or unreadable.
+ */
+export function effectiveRuntimeTelemetryCapabilitiesV3(
+  evidence: RuntimeTelemetryCapabilityEvidenceV3,
+): RuntimeTelemetryCapabilitiesV3 {
+  return {
+    context_usage: contextCapability(evidence.context),
+    wait_spans: waitSpanCapability(evidence.adapter, evidence.cursor_mode),
+    wait_completeness: evidence.independent_wait_completeness
+      ? observed("native", "runtime.wait_aggregate", "exact", "native", "exact")
+      : unsupported("wait_turn_completeness"),
+    response_latency: evidence.canonical_turn_boundaries
+      ? observed("derived", "canonical.event_clocks", "exact", "derived", "exact")
+      : missing("response_latency", "turn_boundaries_not_delivered"),
+    inference_timing: unsupported("provider_inference_timing"),
+  };
+}
+
+function contextCapability(
+  evidence: RuntimeContextCapabilityEvidenceV3,
+): RuntimeTelemetryCapabilityObservationV3 {
+  if (evidence.state === "observed") {
+    return observed(
+      evidence.attestation === "native" ? "native" : "derived",
+      evidence.source,
+      evidence.completeness ?? (evidence.attestation === "inferred" ? "inferred" : "exact"),
+      evidence.attestation,
+      evidence.confidence,
+    );
+  }
+  if (evidence.state === "partial") {
+    return missing("context_usage", evidence.reason);
+  }
+  return unsupported("context_usage");
+}
+
+function waitSpanCapability(
+  adapter: Adapter,
+  cursorMode: CursorExecutionModeV3 | undefined,
+): RuntimeTelemetryCapabilityObservationV3 {
+  if (adapter === "cursor" && cursorMode === "cloud") {
+    return unsupported("wait_span_delivery");
+  }
+  const support = adapterSignalSupportV3(adapter, "permission");
+  if (support === "unsupported") return unsupported("wait_span_delivery");
+  return observed(
+    support,
+    adapter === "cursor" ? "cursor.permission_hooks" : `${adapter}.permission_hooks`,
+    "lower_bound",
+    support === "native" ? "native" : "derived",
+    support === "native" ? "exact" : "high",
+  );
+}
+
+function observed(
+  support: Exclude<CapabilitySupportV3, "unsupported">,
+  source: string,
+  completeness: RuntimeTelemetryCompletenessV3,
+  attestation: "native" | "derived" | "inferred",
+  confidence: "exact" | "high" | "medium" | "low",
+): RuntimeTelemetryCapabilityObservationV3 {
+  return {
+    state: "observed",
+    value: { support, source, completeness },
+    attestation,
+    confidence,
+  };
+}
+
+function missing(capability: string, reason: string): RuntimeTelemetryCapabilityObservationV3 {
+  return { state: "expected_but_missing", capability, reason };
+}
+
+function unsupported(capability: string): RuntimeTelemetryCapabilityObservationV3 {
+  return { state: "unsupported", capability };
+}