harnery 0.33.0 → 0.34.0

package/src/core/events/v3/capability-drift.ts

@@ -0,0 +1,177 @@
+import type { Adapter } from "../../adapter.ts";
+import {
+  type AdapterSignalV3,
+  adapterSignalSupportV3,
+  type CapabilitySupportV3,
+} from "./capabilities.ts";
+import type { EventPayloadV3, EventV3 } from "./contract.ts";
+
+export interface CapabilityDeliveryV3 {
+  signal: AdapterSignalV3;
+  expected_count: number;
+  observed_count: number;
+}
+
+export type CapabilityDriftPayloadV3 = EventPayloadV3<"health.capability_drift">;
+
+/**
+ * Compare measurable adapter promises against one completed generation.
+ *
+ * Conditional and unsupported promises never drift: absence is allowed by
+ * their contract. Native and derived promises report only when a concrete
+ * opportunity existed, keeping a quiet generation from manufacturing health
+ * failures.
+ */
+export function capabilityDriftPayloadsV3(
+  adapter: Adapter,
+  events: readonly EventV3[],
+  options: { generation_ended?: boolean } = {},
+): CapabilityDriftPayloadV3[] {
+  const generationEnded =
+    options.generation_ended ?? events.some((event) => eventType(event) === "session.ended");
+  if (!generationEnded) return [];
+
+  return measurableDeliveries(events)
+    .filter(({ signal, expected_count, observed_count }) => {
+      const promised = adapterSignalSupportV3(adapter, signal);
+      return (
+        promised !== "unsupported" && promised !== "conditional" && expected_count > observed_count
+      );
+    })
+    .map(({ signal, expected_count, observed_count }) => ({
+      signal,
+      promised: adapterSignalSupportV3(adapter, signal) as Exclude<
+        CapabilitySupportV3,
+        "unsupported"
+      >,
+      expected_count,
+      observed_count,
+      generation_ended: true,
+    }));
+}
+
+export function measurableDeliveriesV3(events: readonly EventV3[]): CapabilityDeliveryV3[] {
+  return measurableDeliveries(events);
+}
+
+function measurableDeliveries(events: readonly EventV3[]): CapabilityDeliveryV3[] {
+  const counts = new Map<string, number>();
+  const observed = new Map<string, number>();
+  const increment = (map: Map<string, number>, key: string) =>
+    map.set(key, (map.get(key) ?? 0) + 1);
+
+  for (const event of events) {
+    const type = eventType(event);
+    const payload = record((event as { payload?: unknown }).payload);
+    switch (type) {
+      case "session.started":
+        increment(observed, "session_start");
+        if (record(record(payload.runtime_attestation).model).state === "observed") {
+          increment(observed, "model_identity");
+        }
+        break;
+      case "session.ended":
+        increment(observed, "session_end");
+        break;
+      case "turn.started":
+        increment(counts, "turn_completion");
+        break;
+      case "turn.completed":
+        increment(observed, "turn_completion");
+        increment(counts, "harness_timing");
+        increment(counts, "context_usage");
+        increment(counts, "model_usage");
+        increment(counts, "inference_timing");
+        if (observationObserved(payload.harness)) increment(observed, "harness_timing");
+        if (observationObserved(payload.usage)) increment(observed, "model_usage");
+        if (observationObserved(payload.inference)) increment(observed, "inference_timing");
+        break;
+      case "tool.requested":
+        increment(observed, "tool_request");
+        increment(counts, "tool_result");
+        break;
+      case "tool.completed":
+        increment(counts, "tool_request");
+        increment(observed, "tool_result");
+        increment(counts, "tool_duration");
+        if (observationObserved(record(payload.span).duration_ms)) {
+          increment(observed, "tool_duration");
+        }
+        break;
+      case "wait.started":
+        increment(counts, "permission");
+        break;
+      case "wait.ended":
+        increment(observed, "permission");
+        break;
+      case "agent.started":
+        increment(counts, "subagent");
+        break;
+      case "agent.completed":
+        increment(observed, "subagent");
+        break;
+      case "context.compaction_started":
+        increment(counts, "post_compaction");
+        break;
+      case "context.compaction_completed":
+        increment(observed, "post_compaction");
+        break;
+      case "context.observed":
+        if (observationObserved(payload.measurement)) increment(observed, "context_usage");
+        break;
+    }
+  }
+
+  const sessionExpected = events.length > 0 ? 1 : 0;
+  const deliveries: CapabilityDeliveryV3[] = [
+    delivery("session_start", sessionExpected, observed),
+    delivery("session_end", sessionExpected, observed),
+    deliveryFrom("turn_completion", counts, observed),
+    delivery(
+      "tool_request",
+      Math.max(counts.get("tool_request") ?? 0, observed.get("tool_request") ?? 0),
+      observed,
+    ),
+    deliveryFrom("tool_result", counts, observed),
+    deliveryFrom("tool_duration", counts, observed),
+    deliveryFrom("permission", counts, observed),
+    deliveryFrom("subagent", counts, observed),
+    deliveryFrom("post_compaction", counts, observed),
+    deliveryFrom("context_usage", counts, observed),
+    deliveryFrom("model_identity", new Map([["model_identity", sessionExpected]]), observed),
+    deliveryFrom("model_usage", counts, observed),
+    deliveryFrom("inference_timing", counts, observed),
+    deliveryFrom("harness_timing", counts, observed),
+  ];
+  return deliveries.filter(({ expected_count }) => expected_count > 0);
+}
+
+function delivery(
+  signal: AdapterSignalV3,
+  expected_count: number,
+  observed: Map<string, number>,
+): CapabilityDeliveryV3 {
+  return { signal, expected_count, observed_count: observed.get(signal) ?? 0 };
+}
+
+function deliveryFrom(
+  signal: AdapterSignalV3,
+  expected: Map<string, number>,
+  observed: Map<string, number>,
+): CapabilityDeliveryV3 {
+  return delivery(signal, expected.get(signal) ?? 0, observed);
+}
+
+function eventType(event: EventV3): string {
+  return String((event as { event_type?: unknown }).event_type ?? "");
+}
+
+function observationObserved(value: unknown): boolean {
+  return record(value).state === "observed";
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

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

@@ -0,0 +1,202 @@
+import { readFileSync } from "node:fs";
+import { canonicalJsonV3 } from "./canonical.ts";
+
+export interface EventV3SegmentManifest {
+  format: "harnery-event-v3-segment";
+  format_version: 1;
+  ordinal: number;
+  segment_file: string;
+  bytes: number;
+  row_count: number;
+  segment_digest: `sha256:${string}`;
+  schema_digests: string[];
+  first_event_id: string;
+  last_event_id: string;
+  sealed_at: string;
+}
+
+export interface EventV3CatalogSegment {
+  ordinal: number;
+  segment_file: string;
+  manifest_file: string;
+  segment_digest: `sha256:${string}`;
+  manifest_digest: `sha256:${string}`;
+  bytes: number;
+  row_count: number;
+}
+
+export interface EventV3Catalog {
+  format: "harnery-event-v3-catalog";
+  format_version: 1;
+  segments: EventV3CatalogSegment[];
+  active: {
+    ordinal: number;
+    device: string;
+    inode: string;
+    birthtime_ns: string;
+  };
+}
+
+export function readEventV3Catalog(path: string): EventV3Catalog {
+  return validateCanonicalMetadata(path, validateCatalog, "V3 catalog");
+}
+
+export function readEventV3SegmentManifest(path: string): EventV3SegmentManifest {
+  return validateCanonicalMetadata(path, validateManifest, "V3 segment manifest");
+}
+
+function validateCanonicalMetadata<T>(
+  path: string,
+  validate: (value: unknown) => T,
+  label: string,
+): T {
+  let text: string;
+  let parsed: unknown;
+  try {
+    text = readFileSync(path, "utf8");
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${label} is missing or malformed`);
+  }
+  const value = validate(parsed);
+  if (text !== `${canonicalJsonV3(value)}\n`) throw new Error(`${label} is not canonical`);
+  return value;
+}
+
+function validateCatalog(value: unknown): EventV3Catalog {
+  const record = object(value, "V3 catalog envelope is invalid");
+  if (record.format !== "harnery-event-v3-catalog" || record.format_version !== 1) {
+    throw new Error("V3 catalog format is unsupported");
+  }
+  exactKeys(record, ["active", "format", "format_version", "segments"], "V3 catalog");
+  if (!Array.isArray(record.segments)) throw new Error("V3 catalog segments are invalid");
+  const segments = record.segments.map((segment, index) =>
+    validateCatalogSegment(segment, index + 1),
+  );
+  const active = object(record.active, "V3 catalog active identity is invalid");
+  exactKeys(active, ["birthtime_ns", "device", "inode", "ordinal"], "V3 catalog active");
+  if (
+    active.ordinal !== segments.length + 1 ||
+    typeof active.device !== "string" ||
+    typeof active.inode !== "string" ||
+    typeof active.birthtime_ns !== "string"
+  ) {
+    throw new Error("V3 catalog active identity is invalid");
+  }
+  return {
+    format: "harnery-event-v3-catalog",
+    format_version: 1,
+    segments,
+    active: active as unknown as EventV3Catalog["active"],
+  };
+}
+
+function validateCatalogSegment(value: unknown, expectedOrdinal: number): EventV3CatalogSegment {
+  const record = object(value, "V3 catalog segment is invalid");
+  exactKeys(
+    record,
+    [
+      "bytes",
+      "manifest_digest",
+      "manifest_file",
+      "ordinal",
+      "row_count",
+      "segment_digest",
+      "segment_file",
+    ],
+    "V3 catalog segment",
+  );
+  if (
+    record.ordinal !== expectedOrdinal ||
+    !nonnegativeInteger(record.bytes) ||
+    !nonnegativeInteger(record.row_count) ||
+    record.segment_file !== segmentFileName(expectedOrdinal) ||
+    record.manifest_file !== manifestFileName(expectedOrdinal) ||
+    !sha256(record.segment_digest) ||
+    !sha256(record.manifest_digest)
+  ) {
+    throw new Error("V3 catalog segment values are invalid");
+  }
+  return record as unknown as EventV3CatalogSegment;
+}
+
+function validateManifest(value: unknown): EventV3SegmentManifest {
+  const record = object(value, "V3 segment manifest envelope is invalid");
+  if (record.format !== "harnery-event-v3-segment" || record.format_version !== 1) {
+    throw new Error("V3 segment manifest format is unsupported");
+  }
+  exactKeys(
+    record,
+    [
+      "bytes",
+      "first_event_id",
+      "format",
+      "format_version",
+      "last_event_id",
+      "ordinal",
+      "row_count",
+      "schema_digests",
+      "sealed_at",
+      "segment_digest",
+      "segment_file",
+    ],
+    "V3 segment manifest",
+  );
+  if (
+    !positiveInteger(record.ordinal) ||
+    !nonnegativeInteger(record.bytes) ||
+    !positiveInteger(record.row_count) ||
+    record.segment_file !== segmentFileName(record.ordinal as number) ||
+    !sha256(record.segment_digest) ||
+    typeof record.first_event_id !== "string" ||
+    typeof record.last_event_id !== "string" ||
+    typeof record.sealed_at !== "string" ||
+    !Array.isArray(record.schema_digests) ||
+    record.schema_digests.length === 0 ||
+    record.schema_digests.some((digest) => !sha256(digest)) ||
+    [...record.schema_digests].sort().join("\0") !== record.schema_digests.join("\0") ||
+    new Set(record.schema_digests).size !== record.schema_digests.length
+  ) {
+    throw new Error("V3 segment manifest values are invalid");
+  }
+  return record as unknown as EventV3SegmentManifest;
+}
+
+function object(value: unknown, message: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(message);
+  return value as Record<string, unknown>;
+}
+
+function exactKeys(record: Record<string, unknown>, expected: string[], label: string): void {
+  if (Object.keys(record).sort().join("\0") !== expected.join("\0")) {
+    throw new Error(`${label} has unsupported fields`);
+  }
+}
+
+function positiveInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && (value as number) > 0;
+}
+
+function nonnegativeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+
+function sha256(value: unknown): value is `sha256:${string}` {
+  return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+
+export function segmentFileNameV3(ordinal: number): string {
+  return segmentFileName(ordinal);
+}
+
+export function manifestFileNameV3(ordinal: number): string {
+  return manifestFileName(ordinal);
+}
+
+function segmentFileName(ordinal: number): string {
+  return `${String(ordinal).padStart(12, "0")}.ndjson`;
+}
+
+function manifestFileName(ordinal: number): string {
+  return `${String(ordinal).padStart(12, "0")}.manifest.json`;
+}

package/src/core/events/v3/clock-order.ts

@@ -0,0 +1,41 @@
+/**
+ * Producer-side wall-clock ordering for V3 events.
+ *
+ * The canonical reader fails closed on an unmarked wall-clock regression
+ * (`wall_clock_regression_unmarked`). Once one row carries an `observed_at`
+ * earlier than the previous row on the same `clock_id`, the whole authority
+ * stops validating and no later generation can be minted, so every live agent
+ * disappears from coordination at once.
+ *
+ * Producers already drop a regressing `monotonic_ns`. Wall clock had no
+ * equivalent, so two events stamped microseconds apart inside one hook
+ * invocation could darken the ledger: on 2026-08-19 a `tool.completed`
+ * observed at `19:39:36.078Z` was followed by the `turn.completed` it caused,
+ * observed at `19:39:36.077Z`.
+ *
+ * Rewriting the timestamp is not an option — a producer must not manufacture
+ * history — so the row is marked instead. `skew: "regressed"` is the contract's
+ * own vocabulary for this, and the reader accepts a marked regression.
+ */
+
+/** The slice of a V3 event this rule reads and marks. */
+interface ClockOrderedEventV3 {
+  time: { observed_at: string; skew: "normal" | "regressed" | "unknown" };
+}
+
+/**
+ * Mark `event` as regressed when its `observed_at` precedes the last one this
+ * producer stamped on the same clock. Unparseable or absent evidence leaves the
+ * event untouched: an unmarked row that never regressed stays unmarked.
+ */
+export function markObservedClockRegressionV3(
+  event: ClockOrderedEventV3,
+  lastObservedAt: string | undefined,
+): void {
+  if (!lastObservedAt) return;
+  const observed = Date.parse(event.time.observed_at);
+  const prior = Date.parse(lastObservedAt);
+  if (!Number.isFinite(observed) || !Number.isFinite(prior)) return;
+  if (observed >= prior) return;
+  event.time.skew = "regressed";
+}