harnery 0.34.1 → 0.36.0

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

@@ -34,12 +34,18 @@ export {
 } from "./canonical.ts";
 export {
   ADAPTER_CAPABILITY_PROFILES_V3,
+  ADAPTER_WAIT_KINDS_V3,
   type AdapterCapabilityProfileV3,
   type AdapterSignalV3,
+  type AdapterWaitKindV3,
   adapterCapabilityProfileDigestV3,
   adapterCapabilityProfileV3,
   adapterSignalSupportV3,
+  adapterWaitCoverageMatrixV3,
+  adapterWaitKindSupportV3,
   type CapabilitySupportV3,
+  type CursorExecutionModeV3,
+  type WaitKindCapabilityV3,
 } from "./capabilities.ts";
 export {
   type CapabilityDeliveryV3,
@@ -86,10 +92,10 @@ export {
   type EventV3WriteMode,
   eventV3WriteGateOpen,
   readEventV3ControlState,
-  repairEventV3ControlPair,
   validateActivationManifestV3,
   validateCandidateGenesisManifestV3,
 } from "./control.ts";
+export { repairEventV3ControlPair } from "./control-writer.ts";
 export {
   type CoordinationGenerationViewV3,
   type CoordinationViewV3,
@@ -153,8 +159,12 @@ export {
   type LatencyProjectionDiagnosticV3,
   type LatencyProjectionV3,
   projectLatencyV3,
+  type ResponseLatencyV3,
+  runtimeTelemetryEvidenceKeyV3,
   type ToolLatencyV3,
   type TurnLatencyV3,
+  type WaitKindCompletenessV3,
+  type WaitKindCoverageV3,
 } from "./latency.ts";
 export {
   EVENT_V3_LIVE_RELATIVE_ROOT,
@@ -169,11 +179,14 @@ export {
   writeLiveDisplayV3,
 } from "./live-feed.ts";
 export type { LiveCoordinationObservationV3 } from "./live-observation.ts";
+export {
+  type LiveEventLedgerRouteV3,
+  observeLiveEventLedgerRouteV3,
+} from "./live-route-observer.ts";
 export {
   hookSignalV3,
   LIVE_COMMAND_V3_PRODUCER_ID,
   LIVE_HOOK_V3_PRODUCER_ID,
-  type LiveEventLedgerRouteV3,
   liveEventV3BuildId,
   liveInstanceIdV3,
   livePlatformV3,
@@ -245,6 +258,7 @@ export {
 } from "./projection.ts";
 export {
   digestEventV3AuthorityDirectoryV3,
+  eventV3ActiveWatchPath,
   inspectInvalidActiveAuthorityV3,
   type LedgerCursorV3,
   type LedgerDiagnosticCodeV3,
@@ -277,6 +291,16 @@ export {
   validateEventV3RecoveryIntent,
   validateEventV3RecoveryReceipt,
 } from "./recovery-record.ts";
+export {
+  effectiveRuntimeTelemetryCapabilitiesV3,
+  type RuntimeContextCapabilityEvidenceV3,
+  type RuntimeTelemetryCapabilitiesV3,
+  type RuntimeTelemetryCapabilityEvidenceV3,
+  type RuntimeTelemetryCapabilityObservationV3,
+  type RuntimeTelemetryCapabilityValueV3,
+  type RuntimeTelemetryChannelV3,
+  type RuntimeTelemetryCompletenessV3,
+} from "./runtime-telemetry-capabilities.ts";
 export {
   type CloseSpanV3Input,
   captureSpanClockV3,

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

@@ -1,6 +1,9 @@
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { ADAPTER_WAIT_KINDS_V3, type AdapterWaitKindV3 } from "./capabilities.ts";
 import type { ReadLedgerV3Result } from "./reader.ts";
+import type { RuntimeTelemetryCapabilitiesV3 } from "./runtime-telemetry-capabilities.ts";
 
-export const EVENT_V3_LATENCY_PROJECTION_VERSION = "event-v3-latency-v1" as const;
+export const EVENT_V3_LATENCY_PROJECTION_VERSION = "event-v3-latency-v3" as const;
 
 export type LatencyMetricV3 =
   | { state: "observed"; value_ms: number }
@@ -25,6 +28,30 @@ export interface ContextCoverageV3 {
   reason: string | null;
 }
 
+export interface ResponseLatencyV3 {
+  /** Turn start to first tool request, or terminal response for an attested no-tool turn. */
+  agent_action_ms: LatencyMetricV3;
+  /** Turn start to first tool request; unknown with `no_tool_request` for no-tool turns. */
+  first_tool_request_ms: LatencyMetricV3;
+  /** Last complete tool terminal to the turn terminal. */
+  post_tool_response_ms: LatencyMetricV3;
+  /** Turn start to terminal response, only when an attested turn used no tools. */
+  no_tool_terminal_response_ms: LatencyMetricV3;
+  method: "canonical_event_timestamps_v1";
+}
+
+export type WaitKindCompletenessV3 = "complete" | "lower_bound" | "unknown" | "unsupported";
+
+export interface WaitKindCoverageV3 {
+  kind: AdapterWaitKindV3;
+  started_count: number;
+  ended_count: number;
+  open_count: number;
+  duration_ms: LatencyMetricV3;
+  completeness: WaitKindCompletenessV3;
+  reason: string | null;
+}
+
 export interface TurnLatencyV3 {
   generation_id: string;
   turn_id: string;
@@ -39,6 +66,7 @@ export interface TurnLatencyV3 {
   wait_ms: LatencyMetricV3;
   occupied_ms: LatencyMetricV3;
   inference_ms: LatencyMetricV3;
+  response_latency: ResponseLatencyV3;
   harness_ms: LatencyMetricV3;
   slowest_hook: string | null;
   slowest_hook_ms: number | null;
@@ -46,6 +74,10 @@ export interface TurnLatencyV3 {
   over_attributed_ms: number;
   context_percent: number | null;
   context_coverage: ContextCoverageV3;
+  telemetry_capabilities: RuntimeTelemetryCapabilitiesV3 | null;
+  /** Equal keys are required before a report compares telemetry-backed values. */
+  telemetry_evidence_key: `sha256:${string}` | null;
+  wait_coverage_by_kind: Record<AdapterWaitKindV3, WaitKindCoverageV3>;
   span_counts: { tool: number; command: number; wait: number };
   tool_breakdown: ToolLatencyV3[];
 }
@@ -72,6 +104,7 @@ interface EventShape {
   event_id: string;
   event_type: string;
   scope: { generation_id?: string; turn_id?: string };
+  time: { observed_at?: string };
   payload: Record<string, unknown>;
 }
 
@@ -92,6 +125,7 @@ export function projectLatencyV3(read: ReadLedgerV3Result): LatencyProjectionV3
   const events = read.events.map(({ event }) => event as unknown as EventShape);
   const diagnostics: LatencyProjectionDiagnosticV3[] = [];
   const terminalByTurn = new Map<string, EventShape>();
+  const telemetryByGeneration = latestTelemetryByGeneration(events);
 
   for (const event of events) {
     if (event.event_type !== "turn.completed") continue;
@@ -104,7 +138,12 @@ export function projectLatencyV3(read: ReadLedgerV3Result): LatencyProjectionV3
   const turns = [...terminalByTurn.values()].map((terminal) => {
     const key = turnKey(terminal);
     const turnEvents = events.filter((event) => turnKey(event) === key);
-    return projectTurn(terminal, turnEvents, diagnostics);
+    return projectTurn(
+      terminal,
+      turnEvents,
+      diagnostics,
+      telemetryByGeneration.get(terminal.scope.generation_id ?? "") ?? null,
+    );
   });
   turns.sort(
     (left, right) =>
@@ -118,6 +157,7 @@ function projectTurn(
   terminal: EventShape,
   events: EventShape[],
   diagnostics: LatencyProjectionDiagnosticV3[],
+  telemetryCapabilities: RuntimeTelemetryCapabilitiesV3 | null,
 ): TurnLatencyV3 {
   const span = record(terminal.payload.span);
   const wall = metricFromObservation(span.duration_ms, "turn_duration_unknown");
@@ -157,6 +197,10 @@ function projectTurn(
   ) {
     waits.reasons.push("wait_terminal_count_mismatch");
   }
+  const waitCoverageComplete =
+    expectedWaitCount !== undefined &&
+    expectedWaitCount === endedWaitIds.size &&
+    !waitStartEvents.some(({ payload }) => !endedWaitIds.has(string(record(payload).wait_id)));
 
   const tool = metricFromIntervals(tools);
   const command = metricFromIntervals(commands);
@@ -176,6 +220,7 @@ function projectTurn(
     "api_time_ms",
     "inference_timing_unknown",
   );
+  const responseLatency = projectResponseLatency(terminal, events, wall, tools, expectedToolCount);
   const harness = metricFromNestedObservation(
     terminal.payload.harness,
     "hook_time_ms",
@@ -217,6 +262,7 @@ function projectTurn(
     wait_ms: wait,
     occupied_ms: occupied,
     inference_ms: inference,
+    response_latency: responseLatency,
     harness_ms: harness,
     slowest_hook: slowestHook.name,
     slowest_hook_ms: slowestHook.duration_ms,
@@ -224,6 +270,18 @@ function projectTurn(
     over_attributed_ms: overAttributed,
     context_percent: context.percent,
     context_coverage: context.coverage,
+    telemetry_capabilities: telemetryCapabilities,
+    telemetry_evidence_key: telemetryCapabilities
+      ? runtimeTelemetryEvidenceKeyV3(telemetryCapabilities)
+      : null,
+    wait_coverage_by_kind: projectWaitCoverageByKind(
+      waitStartEvents,
+      waitEvents,
+      wallInterval,
+      waitCoverageComplete,
+      waitCount,
+      diagnostics,
+    ),
     span_counts: {
       tool: toolEvents.length,
       command: commandEvents.length,
@@ -233,6 +291,159 @@ function projectTurn(
   };
 }
 
+/** Reports may compare a telemetry-backed channel only inside one evidence key. */
+export function runtimeTelemetryEvidenceKeyV3(
+  telemetry: RuntimeTelemetryCapabilitiesV3,
+): `sha256:${string}` {
+  return sha256V3(canonicalJsonV3(telemetry));
+}
+
+function latestTelemetryByGeneration(
+  events: EventShape[],
+): Map<string, RuntimeTelemetryCapabilitiesV3> {
+  const result = new Map<string, RuntimeTelemetryCapabilitiesV3>();
+  for (const event of events) {
+    if (
+      event.event_type !== "session.started" &&
+      event.event_type !== "session.attestation_changed"
+    ) {
+      continue;
+    }
+    const attestation = record(event.payload.runtime_attestation);
+    const telemetry = record(attestation.telemetry);
+    if (Object.keys(telemetry).length === 0) continue;
+    result.set(event.scope.generation_id ?? "", telemetry as RuntimeTelemetryCapabilitiesV3);
+  }
+  return result;
+}
+
+function projectResponseLatency(
+  terminal: EventShape,
+  events: EventShape[],
+  wall: LatencyMetricV3,
+  tools: IntervalSet,
+  expectedToolCount: number | undefined,
+): ResponseLatencyV3 {
+  const turnStart = Date.parse(string(record(terminal.payload.span).opened_at));
+  const turnEnd =
+    Number.isFinite(turnStart) && wall.state === "observed" ? turnStart + wall.value_ms : undefined;
+  const requests = events
+    .filter(({ event_type }) => event_type === "tool.requested")
+    .map(({ time }) => Date.parse(string(time.observed_at)))
+    .filter(Number.isFinite)
+    .sort((left, right) => left - right);
+  const firstRequest = requests[0];
+  const firstTool =
+    Number.isFinite(turnStart) && firstRequest !== undefined
+      ? observedLatency(firstRequest - turnStart)
+      : unknownLatency(expectedToolCount === 0 ? "no_tool_request" : "tool_request_unobserved");
+  const noToolTerminal =
+    expectedToolCount === 0
+      ? wall
+      : unknownLatency(
+          expectedToolCount === undefined ? "tool_channel_unattested" : "turn_contains_tools",
+        );
+  const agentAction =
+    firstRequest !== undefined
+      ? firstTool
+      : expectedToolCount === 0
+        ? noToolTerminal
+        : unknownLatency(
+            expectedToolCount === undefined ? "tool_channel_unattested" : "tool_request_unobserved",
+          );
+
+  let postTool = unknownLatency(
+    expectedToolCount === 0
+      ? "no_tool_completion"
+      : expectedToolCount === undefined
+        ? "tool_channel_unattested"
+        : "final_tool_completion_unknown",
+  );
+  if (
+    turnEnd !== undefined &&
+    expectedToolCount !== undefined &&
+    expectedToolCount > 0 &&
+    tools.reasons.length === 0 &&
+    tools.intervals.length === expectedToolCount
+  ) {
+    postTool = observedLatency(turnEnd - Math.max(...tools.intervals.map(({ end }) => end)));
+  }
+
+  return {
+    agent_action_ms: agentAction,
+    first_tool_request_ms: firstTool,
+    post_tool_response_ms: postTool,
+    no_tool_terminal_response_ms: noToolTerminal,
+    method: "canonical_event_timestamps_v1",
+  };
+}
+
+function projectWaitCoverageByKind(
+  starts: EventShape[],
+  ends: EventShape[],
+  wall: Interval | undefined,
+  complete: boolean,
+  waitCount: Record<string, unknown>,
+  diagnostics: LatencyProjectionDiagnosticV3[],
+): Record<AdapterWaitKindV3, WaitKindCoverageV3> {
+  const endedIds = new Set(ends.map(({ payload }) => string(record(payload).wait_id)));
+  const unsupported = waitCount.state === "unsupported";
+  return Object.fromEntries(
+    ADAPTER_WAIT_KINDS_V3.map((kind) => {
+      const kindStarts = starts.filter(({ payload }) => waitKind(payload) === kind);
+      const kindEnds = ends.filter(({ payload }) => waitKind(payload) === kind);
+      const openCount = kindStarts.filter(
+        ({ payload }) => !endedIds.has(string(record(payload).wait_id)),
+      ).length;
+      const set = intervalSet(kindEnds, wall, diagnostics);
+      if (!complete) set.reasons.push("wait_kind_completeness_unattested");
+      const completeness: WaitKindCompletenessV3 = complete
+        ? "complete"
+        : unsupported
+          ? kindStarts.length > 0 || kindEnds.length > 0
+            ? "lower_bound"
+            : "unsupported"
+          : kindStarts.length > 0 || kindEnds.length > 0
+            ? "lower_bound"
+            : "unknown";
+      const reason = complete
+        ? null
+        : unsupported
+          ? "turn_wait_count_unsupported"
+          : "turn_wait_count_unattested";
+      return [
+        kind,
+        {
+          kind,
+          started_count: kindStarts.length,
+          ended_count: kindEnds.length,
+          open_count: openCount,
+          duration_ms: metricFromIntervals(set),
+          completeness,
+          reason,
+        },
+      ];
+    }),
+  ) as Record<AdapterWaitKindV3, WaitKindCoverageV3>;
+}
+
+function waitKind(payload: Record<string, unknown>): AdapterWaitKindV3 {
+  const value = string(record(payload).kind);
+  return ADAPTER_WAIT_KINDS_V3.includes(value as AdapterWaitKindV3)
+    ? (value as AdapterWaitKindV3)
+    : "unknown";
+}
+
+function observedLatency(value: number): LatencyMetricV3 {
+  return Number.isFinite(value) && value >= 0
+    ? { state: "observed", value_ms: Math.floor(value) }
+    : unknownLatency("event_time_order_invalid");
+}
+
+function unknownLatency(reason: string): LatencyMetricV3 {
+  return { state: "unknown", known_ms: 0, reasons: [reason] };
+}
+
 function groupByTool(events: EventShape[]): Map<string, EventShape[]> {
   const groups = new Map<string, EventShape[]>();
   for (const event of events) {

package/src/core/events/v3/live-route-observer.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { ADAPTER_CAPABILITY_PROFILES_V3 } from "./capabilities.ts";
+import {
+  type EventV3ControlState,
+  type EventV3WriteMode,
+  readEventV3ControlState,
+} from "./control.ts";
+import { liveEventV3BuildId } from "./runtime-identity.ts";
+
+export type LiveEventLedgerRouteV3 =
+  | {
+      state: "v3";
+      mode: EventV3WriteMode;
+      build_id: `build_${string}`;
+      /** Genesis id of the epoch this route was resolved against: the epoch fence for derived writes. */
+      genesis_id: `gex_${string}`;
+    }
+  | { state: "blocked"; reason: string };
+
+/**
+ * Observe the V3-only ledger route without repairing control pairs, replacing
+ * epochs, launching processes, or writing files. Read-only consumers fail
+ * closed until a command or producer repairs the route.
+ */
+export function observeLiveEventLedgerRouteV3(coordRoot: string): LiveEventLedgerRouteV3 {
+  return liveEventLedgerRouteFromControlV3(readEventV3ControlState(coordRoot));
+}
+
+/** Project one already-read control state into the passive route contract. */
+export function liveEventLedgerRouteFromControlV3(
+  control: EventV3ControlState,
+): LiveEventLedgerRouteV3 {
+  if (control.state === "closed") return { state: "blocked", reason: "v3_not_initialized" };
+  if (control.state !== "candidate" && control.state !== "active") {
+    return { state: "blocked", reason: `${control.state}:${control.reason}` };
+  }
+  if (!runtimeCapabilityProfileCurrentV3(control)) {
+    return { state: "blocked", reason: "runtime_capability_profile_incompatible" };
+  }
+  const buildId = liveEventV3BuildId(control.genesis.profile.harnery_commit);
+  if (!control.genesis.profile.producer_build_ids.includes(buildId)) {
+    return { state: "blocked", reason: "live_producer_build_not_approved" };
+  }
+  return {
+    state: "v3",
+    mode: control.state,
+    build_id: buildId,
+    genesis_id: control.genesis.event.payload.genesis_id as `gex_${string}`,
+  };
+}
+
+export function runtimeCapabilityProfileCurrentV3(
+  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));
+}
+
+export function liveInstanceIdV3(instanceId: string): `inst_${string}` {
+  if (/^inst_[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return instanceId as `inst_${string}`;
+  if (/^[a-zA-Z0-9._-]{1,128}$/.test(instanceId)) return `inst_${instanceId}`;
+  return `inst_${createHash("sha256").update(instanceId.normalize("NFC")).digest("hex")}`;
+}
+
+/**
+ * The adapter-native id a canonical `inst_*` id carries, for display and for
+ * joins against native-keyed records. Only the direct prefix form round-trips:
+ * a hashed id has no recoverable native form and is returned unchanged, so
+ * never treat this as a guaranteed inverse of `liveInstanceIdV3`.
+ */
+export function nativeInstanceIdV3(instanceId: string): string {
+  return instanceId.startsWith("inst_") ? instanceId.slice("inst_".length) : instanceId;
+}