harnery 0.35.0 → 0.37.0

package/src/core/storage/sink-graph.ts

@@ -0,0 +1,343 @@
+export type HarnerySinkEdgeKind = "primary" | "diagnostic" | "fallback";
+export type HarnerySinkRecordOrigin = "structured-log" | "raw-process" | "cli-emission";
+export type HarneryCapturedStream = "stdout" | "stderr";
+
+export interface HarnerySinkRecord<T = unknown> {
+  origin: HarnerySinkRecordOrigin;
+  payload: T;
+}
+
+export interface HarnerySinkDelivery<T = unknown> extends HarnerySinkRecord<T> {
+  entry_sink_id: string;
+  sink_id: string;
+  route: "entry" | HarnerySinkEdgeKind;
+  source_sink_id?: string;
+}
+
+export interface HarnerySink {
+  id: string;
+  deliver(delivery: HarnerySinkDelivery): void | Promise<void>;
+  emits_stream?: HarneryCapturedStream;
+  captures?: {
+    origin: HarneryCapturedStream | "cli-emission";
+    origin_sink_id?: string;
+  };
+}
+
+export interface HarnerySinkEdge {
+  from: string;
+  to: string;
+  kind: HarnerySinkEdgeKind;
+}
+
+export type HarnerySinkGraphErrorCode =
+  | "duplicate_sink"
+  | "invalid_sink"
+  | "unknown_sink"
+  | "duplicate_edge"
+  | "self_edge"
+  | "cycle"
+  | "cli_emission_capture"
+  | "capture_origin_invalid"
+  | "capture_loop"
+  | "fanout_limit"
+  | "graph_limit";
+
+export class HarnerySinkGraphError extends Error {
+  constructor(
+    readonly code: HarnerySinkGraphErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "HarnerySinkGraphError";
+  }
+}
+
+export type HarnerySinkDeliveryFailureCode = "sink_delivery_failed" | "delivery_budget_exhausted";
+
+export class HarnerySinkDeliveryError extends Error {
+  constructor(
+    readonly code: HarnerySinkDeliveryFailureCode,
+    readonly sink_id: string,
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "HarnerySinkDeliveryError";
+  }
+}
+
+export interface HarnerySinkDeliveryFailure {
+  code: HarnerySinkDeliveryFailureCode;
+  sink_id: string;
+  route: HarnerySinkDelivery["route"];
+  error: HarnerySinkDeliveryError;
+}
+
+export interface HarnerySinkDeliveryResult {
+  attempted: number;
+  delivered: readonly string[];
+  failures: readonly HarnerySinkDeliveryFailure[];
+  truncated: boolean;
+}
+
+export interface HarnerySinkGraphOptions {
+  max_sinks?: number;
+  max_edges?: number;
+  max_fanout?: number;
+  max_deliveries?: number;
+}
+
+interface QueuedDelivery {
+  sink_id: string;
+  route: HarnerySinkDelivery["route"];
+  source_sink_id?: string;
+  record: HarnerySinkRecord;
+}
+
+const ID = /^[a-z][a-z0-9._-]{0,63}$/;
+
+export class HarnerySinkGraph {
+  readonly sinks: readonly Readonly<HarnerySink>[];
+  readonly edges: readonly Readonly<HarnerySinkEdge>[];
+  readonly #byId: ReadonlyMap<string, Readonly<HarnerySink>>;
+  readonly #outgoing: ReadonlyMap<string, readonly Readonly<HarnerySinkEdge>[]>;
+  readonly #maxDeliveries: number;
+
+  constructor(
+    sinks: readonly HarnerySink[],
+    edges: readonly HarnerySinkEdge[],
+    options: HarnerySinkGraphOptions = {},
+  ) {
+    const limits = {
+      max_sinks: positive(options.max_sinks ?? 32, "max_sinks"),
+      max_edges: positive(options.max_edges ?? 128, "max_edges"),
+      max_fanout: positive(options.max_fanout ?? 8, "max_fanout"),
+      max_deliveries: positive(options.max_deliveries ?? 64, "max_deliveries"),
+    };
+    if (sinks.length > limits.max_sinks || edges.length > limits.max_edges) {
+      throw new HarnerySinkGraphError("graph_limit", "sink graph exceeds its construction limit");
+    }
+    const sinkCopies = sinks.map((sink) => Object.freeze({ ...sink }));
+    const byId = new Map<string, Readonly<HarnerySink>>();
+    for (const sink of sinkCopies) {
+      if (!ID.test(sink.id) || typeof sink.deliver !== "function") {
+        throw new HarnerySinkGraphError("invalid_sink", `invalid sink: ${sink.id}`);
+      }
+      if (byId.has(sink.id)) {
+        throw new HarnerySinkGraphError("duplicate_sink", `duplicate sink: ${sink.id}`);
+      }
+      if (sink.captures?.origin === "cli-emission") {
+        throw new HarnerySinkGraphError(
+          "cli_emission_capture",
+          `sink ${sink.id} cannot capture CLI emission`,
+        );
+      }
+      byId.set(sink.id, sink);
+    }
+    const edgeCopies = edges.map((edge) => Object.freeze({ ...edge }));
+    const outgoing = new Map<string, readonly Readonly<HarnerySinkEdge>[]>();
+    const edgeKeys = new Set<string>();
+    for (const edge of edgeCopies) {
+      if (!byId.has(edge.from) || !byId.has(edge.to)) {
+        throw new HarnerySinkGraphError(
+          "unknown_sink",
+          `sink edge references an unknown sink: ${edge.from}->${edge.to}`,
+        );
+      }
+      if (edge.from === edge.to) {
+        throw new HarnerySinkGraphError(
+          "self_edge",
+          `sink ${edge.from} cannot route ${edge.kind} delivery through itself`,
+        );
+      }
+      if (!new Set<HarnerySinkEdgeKind>(["primary", "diagnostic", "fallback"]).has(edge.kind)) {
+        throw new HarnerySinkGraphError("invalid_sink", `invalid sink edge kind: ${edge.kind}`);
+      }
+      const key = `${edge.from}\0${edge.to}\0${edge.kind}`;
+      if (edgeKeys.has(key)) {
+        throw new HarnerySinkGraphError(
+          "duplicate_edge",
+          `duplicate sink edge: ${edge.from}->${edge.to}`,
+        );
+      }
+      edgeKeys.add(key);
+      const next = [...(outgoing.get(edge.from) ?? []), edge];
+      if (next.length > limits.max_fanout) {
+        throw new HarnerySinkGraphError("fanout_limit", `sink ${edge.from} exceeds fan-out limit`);
+      }
+      outgoing.set(edge.from, Object.freeze(next));
+    }
+    rejectCycles(byId, outgoing);
+    rejectCaptureLoops(byId, outgoing);
+    this.sinks = Object.freeze(sinkCopies);
+    this.edges = Object.freeze(edgeCopies);
+    this.#byId = byId;
+    this.#outgoing = outgoing;
+    this.#maxDeliveries = limits.max_deliveries;
+    Object.freeze(this);
+  }
+
+  async deliver(
+    entrySinkId: string,
+    record: HarnerySinkRecord,
+  ): Promise<HarnerySinkDeliveryResult> {
+    if (!this.#byId.has(entrySinkId)) {
+      throw new HarnerySinkGraphError("unknown_sink", `unknown entry sink: ${entrySinkId}`);
+    }
+    if (record.origin === "cli-emission") {
+      throw new HarnerySinkGraphError(
+        "cli_emission_capture",
+        "CLI emission is not a structured sink record",
+      );
+    }
+    const queue: QueuedDelivery[] = [{ sink_id: entrySinkId, route: "entry", record }];
+    const visited = new Set<string>();
+    const delivered: string[] = [];
+    const failures: HarnerySinkDeliveryFailure[] = [];
+    let attempted = 0;
+    let truncated = false;
+    while (queue.length > 0) {
+      const next = queue.shift()!;
+      const visitKey = `${next.sink_id}\0${next.route}`;
+      if (visited.has(visitKey)) continue;
+      if (attempted >= this.#maxDeliveries) {
+        truncated = true;
+        failures.push(deliveryFailure("delivery_budget_exhausted", next, undefined));
+        break;
+      }
+      visited.add(visitKey);
+      attempted += 1;
+      const sink = this.#byId.get(next.sink_id)!;
+      try {
+        await sink.deliver({
+          ...next.record,
+          entry_sink_id: entrySinkId,
+          sink_id: next.sink_id,
+          route: next.route,
+          ...(next.source_sink_id ? { source_sink_id: next.source_sink_id } : {}),
+        });
+        delivered.push(next.sink_id);
+        if (next.route === "entry" || next.route === "primary") {
+          enqueueEdges(queue, this.#outgoing.get(next.sink_id), "primary", next.record);
+        }
+      } catch (error) {
+        const failure = deliveryFailure("sink_delivery_failed", next, error);
+        failures.push(failure);
+        // Recovery lanes are terminal. Their failures remain typed return data
+        // and never emit another diagnostic through this graph.
+        if (next.route === "entry" || next.route === "primary") {
+          enqueueEdges(queue, this.#outgoing.get(next.sink_id), "diagnostic", {
+            origin: "structured-log",
+            payload: failure,
+          });
+          enqueueEdges(queue, this.#outgoing.get(next.sink_id), "fallback", next.record);
+        }
+      }
+    }
+    return Object.freeze({
+      attempted,
+      delivered: Object.freeze(delivered),
+      failures: Object.freeze(failures),
+      truncated,
+    });
+  }
+}
+
+function enqueueEdges(
+  queue: QueuedDelivery[],
+  edges: readonly Readonly<HarnerySinkEdge>[] | undefined,
+  kind: HarnerySinkEdgeKind,
+  record: HarnerySinkRecord,
+): void {
+  for (const edge of edges ?? []) {
+    if (edge.kind !== kind) continue;
+    queue.push({ sink_id: edge.to, route: kind, source_sink_id: edge.from, record });
+  }
+}
+
+function deliveryFailure(
+  code: HarnerySinkDeliveryFailureCode,
+  delivery: QueuedDelivery,
+  cause: unknown,
+): HarnerySinkDeliveryFailure {
+  const error = new HarnerySinkDeliveryError(
+    code,
+    delivery.sink_id,
+    code === "sink_delivery_failed"
+      ? `sink delivery failed: ${delivery.sink_id}`
+      : `sink delivery budget exhausted before ${delivery.sink_id}`,
+    cause,
+  );
+  return Object.freeze({ code, sink_id: delivery.sink_id, route: delivery.route, error });
+}
+
+function rejectCycles(
+  sinks: ReadonlyMap<string, Readonly<HarnerySink>>,
+  outgoing: ReadonlyMap<string, readonly Readonly<HarnerySinkEdge>[]>,
+): void {
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (id: string) => {
+    if (visiting.has(id)) throw new HarnerySinkGraphError("cycle", `sink graph cycle at ${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const edge of outgoing.get(id) ?? []) visit(edge.to);
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of sinks.keys()) visit(id);
+}
+
+function rejectCaptureLoops(
+  sinks: ReadonlyMap<string, Readonly<HarnerySink>>,
+  outgoing: ReadonlyMap<string, readonly Readonly<HarnerySinkEdge>[]>,
+): void {
+  for (const sink of sinks.values()) {
+    const capture = sink.captures;
+    if (!capture || capture.origin === "cli-emission") continue;
+    if (!capture.origin_sink_id) {
+      throw new HarnerySinkGraphError(
+        "capture_origin_invalid",
+        `capturing sink ${sink.id} must name its origin sink`,
+      );
+    }
+    const origin = sinks.get(capture.origin_sink_id);
+    if (!origin || origin.emits_stream !== capture.origin) {
+      throw new HarnerySinkGraphError(
+        "capture_origin_invalid",
+        `capturing sink ${sink.id} has an invalid ${capture.origin} origin`,
+      );
+    }
+    if (sink.id === origin.id || reachable(sink.id, origin.id, outgoing)) {
+      throw new HarnerySinkGraphError(
+        "capture_loop",
+        `captured ${capture.origin} from ${origin.id} routes back through ${sink.id}`,
+      );
+    }
+  }
+}
+
+function reachable(
+  from: string,
+  target: string,
+  outgoing: ReadonlyMap<string, readonly Readonly<HarnerySinkEdge>[]>,
+): boolean {
+  const pending = [from];
+  const seen = new Set<string>();
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    if (current === target) return true;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    for (const edge of outgoing.get(current) ?? []) pending.push(edge.to);
+  }
+  return false;
+}
+
+function positive(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new HarnerySinkGraphError("graph_limit", `${name} must be a positive safe integer`);
+  }
+  return value;
+}

package/src/core/storage/storm-control.ts

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import type { HarneryLogLevel } from "./contract.ts";
+
+export interface HarneryStormSummary {
+  key: string;
+  count: number;
+  represented_bytes: number;
+  first_emitted_at: string;
+  last_emitted_at: string;
+  exemplar_digests: readonly string[];
+}
+
+export interface ProcessStormControllerOptions {
+  enabled: boolean;
+  window_ms: number;
+  max_exemplars: number;
+  burst?: number;
+  now?: () => number;
+}
+
+interface Bucket {
+  started: number;
+  admitted: number;
+  dropped: number;
+  representedBytes: number;
+  first: string;
+  last: string;
+  exemplars: string[];
+}
+
+export class ProcessStormController {
+  readonly #options: Required<ProcessStormControllerOptions>;
+  readonly #buckets = new Map<string, Bucket>();
+
+  constructor(options: ProcessStormControllerOptions) {
+    this.#options = { ...options, burst: options.burst ?? 100, now: options.now ?? Date.now };
+  }
+
+  admit(key: string, level: HarneryLogLevel, bytes: number): boolean {
+    if (!this.#options.enabled || level === "error" || level === "fatal") return true;
+    const now = this.#options.now();
+    let bucket = this.#buckets.get(key);
+    if (!bucket || now - bucket.started >= this.#options.window_ms) {
+      bucket = {
+        started: now,
+        admitted: 0,
+        dropped: 0,
+        representedBytes: 0,
+        first: new Date(now).toISOString(),
+        last: new Date(now).toISOString(),
+        exemplars: [],
+      };
+      this.#buckets.set(key, bucket);
+    }
+    if (bucket.admitted < this.#options.burst) {
+      bucket.admitted += 1;
+      return true;
+    }
+    bucket.dropped += 1;
+    bucket.representedBytes += bytes;
+    bucket.last = new Date(now).toISOString();
+    const digest = createHash("sha256").update(`${key}:${bytes}`).digest("hex").slice(0, 16);
+    if (
+      bucket.exemplars.length < this.#options.max_exemplars &&
+      !bucket.exemplars.includes(digest)
+    ) {
+      bucket.exemplars.push(digest);
+    }
+    return false;
+  }
+
+  drainSummaries(force = false): HarneryStormSummary[] {
+    const now = this.#options.now();
+    const summaries: HarneryStormSummary[] = [];
+    for (const [key, bucket] of this.#buckets) {
+      if (!force && now - bucket.started < this.#options.window_ms) continue;
+      if (bucket.dropped > 0) {
+        summaries.push({
+          key,
+          count: bucket.dropped,
+          represented_bytes: bucket.representedBytes,
+          first_emitted_at: bucket.first,
+          last_emitted_at: bucket.last,
+          exemplar_digests: bucket.exemplars,
+        });
+      }
+      this.#buckets.delete(key);
+    }
+    return summaries;
+  }
+}

package/src/core/supervisor/activity.ts

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+  SUPERVISOR_DIAGNOSTIC_LIMITS,
+  SUPERVISOR_FINDING_POLICY,
+  type SupervisorActivitySnapshot,
+  type SupervisorDeclaredActivity,
+  type SupervisorSourceReference,
+} from "./contract.ts";
+
+interface ActivityCache {
+  schema_version?: number;
+  instance_id?: string;
+  session_id?: string;
+  activity?: string;
+  task_state?: string;
+  last_heartbeat?: string;
+  v3_instance_id?: string;
+  v3_generation_id?: string;
+}
+
+interface CandidateFile {
+  name: string;
+  path: string;
+  bytes: number;
+  mtimeMs: number;
+}
+
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export function collectSupervisorActivitySnapshot(
+  coordRoot: string,
+  now = new Date(),
+): SupervisorActivitySnapshot {
+  const observedAt = now.toISOString();
+  const directory = join(resolve(coordRoot), ".harnery", "active");
+  if (!existsSync(directory)) return unavailable(observedAt, "activity-projection-missing");
+
+  const candidates: CandidateFile[] = [];
+  let rejected = 0;
+  try {
+    for (const entry of readdirSync(directory)) {
+      if (!/^[A-Za-z0-9_-]{1,128}\.json$/.test(entry)) {
+        rejected += 1;
+        continue;
+      }
+      const path = join(directory, entry);
+      const stat = lstatSync(path);
+      if (
+        stat.isSymbolicLink() ||
+        !stat.isFile() ||
+        stat.size < 2 ||
+        stat.size > SUPERVISOR_FINDING_POLICY.max_activity_file_bytes
+      ) {
+        rejected += 1;
+        continue;
+      }
+      candidates.push({ name: entry.slice(0, -5), path, bytes: stat.size, mtimeMs: stat.mtimeMs });
+    }
+  } catch {
+    return unavailable(observedAt, "activity-projection-read-failed", "error");
+  }
+
+  candidates.sort(
+    (left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name),
+  );
+  const entries: SupervisorDeclaredActivity[] = [];
+  let totalBytes = 0;
+  let stale = 0;
+  for (const candidate of candidates) {
+    if (
+      entries.length >= SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries ||
+      totalBytes + candidate.bytes > SUPERVISOR_FINDING_POLICY.max_activity_total_bytes
+    ) {
+      rejected += 1;
+      continue;
+    }
+    totalBytes += candidate.bytes;
+    let cache: ActivityCache;
+    try {
+      cache = JSON.parse(readFileSync(candidate.path, "utf8")) as ActivityCache;
+    } catch {
+      rejected += 1;
+      continue;
+    }
+    if (!validCache(cache, candidate.name)) {
+      rejected += 1;
+      continue;
+    }
+    const age = now.getTime() - Date.parse(cache.last_heartbeat!);
+    if (
+      !Number.isFinite(age) ||
+      age < -30_000 ||
+      age > SUPERVISOR_FINDING_POLICY.activity_freshness_ms
+    ) {
+      stale += 1;
+      continue;
+    }
+    entries.push(activityEntry(cache as Required<ActivityCache>));
+  }
+
+  const state = rejected > 0 ? "partial" : "supported";
+  return {
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    observed_at: observedAt,
+    max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+    entries: entries.sort((left, right) => left.scope_id.localeCompare(right.scope_id)),
+    omitted_entry_count: rejected + stale,
+    capability: {
+      source_kind: "coordination.activity-projection",
+      state,
+      ...(state === "partial" ? { reason_code: "bounded-cache-rejection" } : {}),
+      ...(rejected + stale > 0
+        ? { detail: `${rejected} invalid or over-budget and ${stale} stale activity rows omitted.` }
+        : {}),
+    },
+  };
+}
+
+function validCache(cache: ActivityCache, fileId: string): boolean {
+  return (
+    cache.schema_version === 2 &&
+    cache.instance_id === fileId &&
+    typeof cache.session_id === "string" &&
+    cache.session_id.length > 0 &&
+    isActivity(cache.activity) &&
+    isTaskState(cache.task_state) &&
+    typeof cache.last_heartbeat === "string" &&
+    typeof cache.v3_instance_id === "string" &&
+    cache.v3_instance_id.startsWith("inst_") &&
+    typeof cache.v3_generation_id === "string" &&
+    cache.v3_generation_id.startsWith("gen_")
+  );
+}
+
+function activityEntry(cache: Required<ActivityCache>): SupervisorDeclaredActivity {
+  const source = activitySource(cache);
+  return {
+    scope_kind: "agent",
+    scope_id: cache.instance_id,
+    session_id: cache.session_id,
+    declared_activity: cache.activity as SupervisorDeclaredActivity["declared_activity"],
+    task_state: cache.task_state as SupervisorDeclaredActivity["task_state"],
+    observed_at: cache.last_heartbeat,
+    source,
+  };
+}
+
+function activitySource(cache: Required<ActivityCache>): SupervisorSourceReference {
+  const sourceId = `${cache.v3_instance_id}:${cache.v3_generation_id}`;
+  return {
+    id: `src_${digest(`coordination.activity-projection\u0000${sourceId}\u0000${cache.last_heartbeat}`).slice(0, 24)}`,
+    source_kind: "coordination.activity-projection",
+    source_id: sourceId,
+    observed_at: cache.last_heartbeat,
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    capability: "supported",
+  };
+}
+
+function unavailable(
+  observedAt: string,
+  reasonCode: string,
+  state: "unsupported" | "error" = "unsupported",
+): SupervisorActivitySnapshot {
+  return {
+    schema_version: SUPERVISOR_ACTIVITY_SCHEMA_VERSION,
+    observed_at: observedAt,
+    max_entries: SUPERVISOR_DIAGNOSTIC_LIMITS.max_activity_entries,
+    entries: [],
+    omitted_entry_count: 0,
+    capability: {
+      source_kind: "coordination.activity-projection",
+      state,
+      reason_code: reasonCode,
+    },
+  };
+}
+
+function isActivity(
+  value: string | undefined,
+): value is SupervisorDeclaredActivity["declared_activity"] {
+  return value === "working" || value === "needs_input" || value === "idle" || value === "unknown";
+}
+
+function isTaskState(value: string | undefined): value is SupervisorDeclaredActivity["task_state"] {
+  return value === "active" || value === "blocked" || value === "done";
+}
+
+function digest(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}