harnery 0.35.0 → 0.37.0

package/dist/core/storage/sink-graph.js

@@ -0,0 +1,213 @@
+export class HarnerySinkGraphError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HarnerySinkGraphError";
+    }
+}
+export class HarnerySinkDeliveryError extends Error {
+    code;
+    sink_id;
+    cause;
+    constructor(code, sink_id, message, cause) {
+        super(message);
+        this.code = code;
+        this.sink_id = sink_id;
+        this.cause = cause;
+        this.name = "HarnerySinkDeliveryError";
+    }
+}
+const ID = /^[a-z][a-z0-9._-]{0,63}$/;
+export class HarnerySinkGraph {
+    sinks;
+    edges;
+    #byId;
+    #outgoing;
+    #maxDeliveries;
+    constructor(sinks, edges, options = {}) {
+        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();
+        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();
+        const edgeKeys = new Set();
+        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(["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, record) {
+        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 = [{ sink_id: entrySinkId, route: "entry", record }];
+        const visited = new Set();
+        const delivered = [];
+        const failures = [];
+        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, edges, kind, record) {
+    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, delivery, cause) {
+    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, outgoing) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        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, outgoing) {
+    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, target, outgoing) {
+    const pending = [from];
+    const seen = new Set();
+    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, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new HarnerySinkGraphError("graph_limit", `${name} must be a positive safe integer`);
+    }
+    return value;
+}

package/dist/core/storage/storm-control.d.ts

@@ -0,0 +1,23 @@
+import type { HarneryLogLevel } from "./contract.js";
+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;
+}
+export declare class ProcessStormController {
+    #private;
+    constructor(options: ProcessStormControllerOptions);
+    admit(key: string, level: HarneryLogLevel, bytes: number): boolean;
+    drainSummaries(force?: boolean): HarneryStormSummary[];
+}
+//# sourceMappingURL=storm-control.d.ts.map

package/dist/core/storage/storm-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storm-control.d.ts","sourceRoot":"","sources":["../../../src/core/storage/storm-control.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAYD,qBAAa,sBAAsB;;gBAIrB,OAAO,EAAE,6BAA6B;IAIlD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAiClE,cAAc,CAAC,KAAK,UAAQ,GAAG,mBAAmB,EAAE;CAmBrD"}

package/dist/core/storage/storm-control.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+export class ProcessStormController {
+    #options;
+    #buckets = new Map();
+    constructor(options) {
+        this.#options = { ...options, burst: options.burst ?? 100, now: options.now ?? Date.now };
+    }
+    admit(key, level, bytes) {
+        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) {
+        const now = this.#options.now();
+        const summaries = [];
+        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/dist/core/supervisor/activity.d.ts

@@ -0,0 +1,4 @@
+import { type SupervisorActivitySnapshot } from "./contract.js";
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export declare function collectSupervisorActivitySnapshot(coordRoot: string, now?: Date): SupervisorActivitySnapshot;
+//# sourceMappingURL=activity.d.ts.map

package/dist/core/supervisor/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../../src/core/supervisor/activity.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,0BAA0B,EAGhC,MAAM,eAAe,CAAC;AAoBvB,4FAA4F;AAC5F,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,EACjB,GAAG,OAAa,GACf,0BAA0B,CAoF5B"}

package/dist/core/supervisor/activity.js

@@ -0,0 +1,141 @@
+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, } from "./contract.js";
+/** Read a bounded, generation-bound activity projection without loading Event Ledger V3. */
+export function collectSupervisorActivitySnapshot(coordRoot, now = new Date()) {
+    const observedAt = now.toISOString();
+    const directory = join(resolve(coordRoot), ".harnery", "active");
+    if (!existsSync(directory))
+        return unavailable(observedAt, "activity-projection-missing");
+    const candidates = [];
+    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 = [];
+    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;
+        try {
+            cache = JSON.parse(readFileSync(candidate.path, "utf8"));
+        }
+        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));
+    }
+    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, fileId) {
+    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) {
+    const source = activitySource(cache);
+    return {
+        scope_kind: "agent",
+        scope_id: cache.instance_id,
+        session_id: cache.session_id,
+        declared_activity: cache.activity,
+        task_state: cache.task_state,
+        observed_at: cache.last_heartbeat,
+        source,
+    };
+}
+function activitySource(cache) {
+    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, reasonCode, state = "unsupported") {
+    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) {
+    return value === "working" || value === "needs_input" || value === "idle" || value === "unknown";
+}
+function isTaskState(value) {
+    return value === "active" || value === "blocked" || value === "done";
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}