@groundnuty/macf-channel-server 0.2.36 → 0.2.37

package/dist/comms-ledger-record.d.ts

@@ -0,0 +1,88 @@
+/**
+ * comms-ledger-record — the LOUD-BUT-PROCEEDS policy slot for the
+ * comms-ledger (macf#473 piece 2; operator decision 2026-06-08).
+ *
+ * The library writer `appendEdge` (comms-ledger.ts) is deliberately
+ * FAIL-LOUD — it throws on any write failure (I/O error) or schema-parse
+ * rejection, because an authoritative DR-025 edge must never silently
+ * disappear at the WRITE layer. But the channel-server's three coordination
+ * EDGE SITES (inbound /notify recv, inbound A2A message/send recv, outbound
+ * notify_peer send) sit on the delivery hot path: a ledger write failure
+ * there must NOT abort the delivery the agent depends on. The observability
+ * layer can never be allowed to cause a coordination outage.
+ *
+ * `recordEdge` reconciles those two requirements. It is append-first, and on
+ * ANY failure it CATCHES, emits a LOUD signal on BOTH channels (a
+ * `logger.error('comms_ledger_write_failed', …)` line carrying the edge
+ * inline + a dedicated `comms_ledger_write_failed` metric carrying enough
+ * label dimensions to reconstruct the edge class), then RETURNS normally.
+ * It never re-throws and never silently swallows. The caller then proceeds
+ * with delivery regardless.
+ *
+ * The WHOLE loud-signal path is guarded so it can never make delivery fatal.
+ * The dominant cause of `appendEdge` throwing is a disk-full / read-only
+ * volume — but the ledger is a SIBLING of `channel.log`, and `logger.error`
+ * lands in `channel.log` via the same `appendFileSync`. A disk-full failure
+ * therefore makes the loud-signal emitter (`logger.error`) throw the SAME
+ * errno, which — without the outermost guard — would escape `recordEdge` and,
+ * at the recv sites (`try { record; await onNotify; 200 } catch { 500 }`),
+ * skip the delivery and 500 the sender. So the entire catch-block body is
+ * wrapped in an OUTERMOST try/catch. If even that fails, a best-effort
+ * `process.stderr.write` is the last channel left; once that path is
+ * exhausted the only correct action is to swallow — there is no louder
+ * channel remaining and delivery MUST proceed.
+ *
+ * This is the structural inverse of `appendEdge`: the WRITE is fail-loud
+ * (it must surface the failure to *someone*); the POLICY around it at the
+ * hot-path sites is loud-but-proceeds (it must surface AND keep going). The
+ * library stays pure; the policy lives here.
+ */
+import type { Logger } from '@groundnuty/macf-core';
+import type { CommsLedger, CommsLedgerEdge } from './comms-ledger.js';
+/**
+ * Sink for the machine-readable half of the loud signal. Injected (not
+ * imported directly from `metrics.ts`) so `recordEdge` degrades gracefully
+ * when metrics are off — server.ts wires the real `getCommsLedgerWriteFailedCounter`
+ * increment; tests inject a spy; omitting it entirely still logs.
+ *
+ * Receives the edge that failed to write so the recorder can derive whatever
+ * label dimensions it wants (channel / direction / agent) from a single
+ * source — keeping the label set decided at the metrics layer, not here.
+ */
+export type CommsLedgerWriteFailedRecorder = (failedEdge: CommsLedgerEdge) => void;
+export interface RecordEdgeDeps {
+    readonly ledger: CommsLedger;
+    readonly logger: Logger;
+    /**
+     * Optional metric recorder for the write-failed signal. When absent,
+     * `recordEdge` still emits the `logger.error` loud signal — the metric is
+     * a complement, not a precondition (OTEL is opt-in; the log is always on).
+     */
+    readonly recordWriteFailed?: CommsLedgerWriteFailedRecorder;
+}
+/**
+ * Append `edge` to the comms-ledger under the loud-but-proceeds policy.
+ *
+ * Behavior (macf#473 operator decision):
+ *   1. append-first: call `ledger.appendEdge(edge)`.
+ *   2. on ANY throw (I/O failure OR the Zod schema-parse rejection inside
+ *      appendEdge) → CATCH it.
+ *   3. emit the LOUD signal on both channels:
+ *        - `logger.error('comms_ledger_write_failed', { edge, error })`
+ *          — the edge is carried INLINE so the lost authoritative record is
+ *          reconstructable from the log alone.
+ *        - `recordWriteFailed(edge)` (if wired) — increments the dedicated
+ *          metric carrying enough label dimensions to reconstruct the edge
+ *          CLASS for alerting / dashboards.
+ *   4. RETURN normally. NEVER re-throw, NEVER silently swallow.
+ *
+ * The caller proceeds with delivery afterward regardless of outcome. This
+ * guarantees the observability layer can never cause a coordination outage,
+ * while never being silent about a lost edge.
+ *
+ * Note: the no-op ledger (no MACF_LOG_PATH) never throws, so this is a clean
+ * no-op there too — same as the rest of the observability surface when
+ * unconfigured.
+ */
+export declare function recordEdge(deps: RecordEdgeDeps, edge: CommsLedgerEdge): void;
+//# sourceMappingURL=comms-ledger-record.d.ts.map

package/dist/comms-ledger-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-ledger-record.d.ts","sourceRoot":"","sources":["../src/comms-ledger-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,UAAU,EAAE,eAAe,KAAK,IAAI,CAAC;AAEnF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,8BAA8B,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CA4C5E"}

package/dist/comms-ledger-record.js

@@ -0,0 +1,74 @@
+/**
+ * Append `edge` to the comms-ledger under the loud-but-proceeds policy.
+ *
+ * Behavior (macf#473 operator decision):
+ *   1. append-first: call `ledger.appendEdge(edge)`.
+ *   2. on ANY throw (I/O failure OR the Zod schema-parse rejection inside
+ *      appendEdge) → CATCH it.
+ *   3. emit the LOUD signal on both channels:
+ *        - `logger.error('comms_ledger_write_failed', { edge, error })`
+ *          — the edge is carried INLINE so the lost authoritative record is
+ *          reconstructable from the log alone.
+ *        - `recordWriteFailed(edge)` (if wired) — increments the dedicated
+ *          metric carrying enough label dimensions to reconstruct the edge
+ *          CLASS for alerting / dashboards.
+ *   4. RETURN normally. NEVER re-throw, NEVER silently swallow.
+ *
+ * The caller proceeds with delivery afterward regardless of outcome. This
+ * guarantees the observability layer can never cause a coordination outage,
+ * while never being silent about a lost edge.
+ *
+ * Note: the no-op ledger (no MACF_LOG_PATH) never throws, so this is a clean
+ * no-op there too — same as the rest of the observability surface when
+ * unconfigured.
+ */
+export function recordEdge(deps, edge) {
+    try {
+        deps.ledger.appendEdge(edge);
+    }
+    catch (err) {
+        // OUTERMOST guard around the ENTIRE loud-signal path. The ledger is a
+        // sibling of channel.log, so the dominant failure cause (disk-full /
+        // read-only volume) makes `logger.error` throw the SAME errno. Without
+        // this guard that throw escapes recordEdge and 500s the sender at the
+        // recv sites. Nothing in here may escape — delivery must proceed.
+        try {
+            // LOUD signal — human-readable half (always on). The edge is carried
+            // inline so the lost authoritative record can be reconstructed from the
+            // log without the ledger file.
+            deps.logger.error('comms_ledger_write_failed', {
+                edge,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // LOUD signal — machine-readable half (when metrics are wired).
+            // Guard the recorder ITSELF so a misbehaving metric sink can't turn the
+            // loud-but-proceeds policy back into a fatal path. Last-ditch only.
+            if (deps.recordWriteFailed !== undefined) {
+                try {
+                    deps.recordWriteFailed(edge);
+                }
+                catch (metricErr) {
+                    deps.logger.error('comms_ledger_write_failed_metric_error', {
+                        error: metricErr instanceof Error ? metricErr.message : String(metricErr),
+                    });
+                }
+            }
+        }
+        catch {
+            // The loud-signal path itself failed (e.g. logger.error threw the same
+            // disk-full errno that broke appendEdge — they share the log volume).
+            // process.stderr is the last channel that doesn't touch that volume;
+            // best-effort, guarded, then SWALLOW. This is the one place a true
+            // swallow is correct: no louder channel remains and delivery must
+            // proceed. recordEdge NEVER escapes.
+            try {
+                process.stderr.write('comms_ledger_write_failed (loud-signal emit also failed)\n');
+            }
+            catch {
+                /* nothing left to do */
+            }
+        }
+        // RETURN normally — the caller proceeds with delivery.
+    }
+}
+//# sourceMappingURL=comms-ledger-record.js.map

package/dist/comms-ledger-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-ledger-record.js","sourceRoot":"","sources":["../src/comms-ledger-record.ts"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAoB,EAAE,IAAqB;IACpE,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,qEAAqE;QACrE,uEAAuE;QACvE,sEAAsE;QACtE,kEAAkE;QAClE,IAAI,CAAC;YACH,qEAAqE;YACrE,wEAAwE;YACxE,+BAA+B;YAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE;gBAC7C,IAAI;gBACJ,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,gEAAgE;YAChE,wEAAwE;YACxE,oEAAoE;YACpE,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;gBACzC,IAAI,CAAC;oBACH,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC/B,CAAC;gBAAC,OAAO,SAAS,EAAE,CAAC;oBACnB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;wBAC1D,KAAK,EAAE,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;qBAC1E,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,sEAAsE;YACtE,qEAAqE;YACrE,mEAAmE;YACnE,kEAAkE;YAClE,qCAAqC;YACrC,IAAI,CAAC;gBACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;YACrF,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;QACH,CAAC;QACD,uDAAuD;IACzD,CAAC;AACH,CAAC"}

package/dist/comms-ledger.d.ts

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+/**
+ * comms-ledger — the write-ahead, per-agent, authoritative record of every
+ * coordination edge the channel-server sends or receives.
+ *
+ * Implements DR-025 (observable coordination substrate). The invariant: any
+ * channel carrying agent-to-agent coordination MUST preserve a durable,
+ * graph-reconstructable, fleet-analyzable record. GitHub gives this for free;
+ * A2A / direct channels must earn it deliberately or the diagnose→redesign
+ * instrument (and the paper's evidence) goes blind. This is macf#444 one layer
+ * up; a Tempo-only design would reproduce silent-fallback Instance 8 (OTLP
+ * silent-drop) as the methodology's foundation.
+ *
+ * Resilience shape: a write-ahead log + a downstream rebuildable index. The
+ * JSONL ledger is AUTHORITATIVE (local disk, synchronous, fail-loud); the Tempo
+ * span is a DERIVED best-effort central index over the same data. The durable
+ * write happens BEFORE the lossy network hop, independent of Tempo's health.
+ *
+ * This module is the library layer (#473 piece 1): the schema, the unified
+ * event taxonomy, the fail-loud writer, the `processed` backfill join, the
+ * multi-host gather, and the rotation policy. Wiring it into the three edge
+ * sites (inbound `/notify`, inbound A2A `message/send`, outbound notify_peer)
+ * is #473 piece 2.
+ */
+/**
+ * Unified coordination-event taxonomy (DR-025 §"Channel unification").
+ * One enum spanning the A2A events and the router events, so a ledger edge
+ * analyzes identically regardless of which channel carried it.
+ */
+export declare const CommsEventSchema: z.ZodEnum<{
+    mention: "mention";
+    error: "error";
+    custom: "custom";
+    "session-end": "session-end";
+    "turn-complete": "turn-complete";
+    "issue-routed": "issue-routed";
+    "pr-review-state": "pr-review-state";
+}>;
+export type CommsEvent = z.infer<typeof CommsEventSchema>;
+export declare const CommsChannelSchema: z.ZodEnum<{
+    a2a: "a2a";
+    "github-route": "github-route";
+}>;
+export type CommsChannel = z.infer<typeof CommsChannelSchema>;
+export declare const CommsDirectionSchema: z.ZodEnum<{
+    send: "send";
+    recv: "recv";
+}>;
+export type CommsDirection = z.infer<typeof CommsDirectionSchema>;
+/**
+ * One coordination edge — one JSONL line per exchange (DR-025 §"The edge schema").
+ *
+ * - `delivered` is known at edge-write (the byte sequence was accepted/pushed).
+ * - `processed` is the macf#444 distinction (delivery ≠ a turn actually happening).
+ *   It is NULLABLE at edge-write — the peer hasn't necessarily taken a turn yet —
+ *   and is backfilled later via the receipt join (`backfillProcessed`). The
+ *   edge-write must never block on it.
+ * - `trace_id` cross-references the Tempo span. It is captured synchronously from
+ *   `span.spanContext().traceId` (OTel api ≥1.9.1: synchronous, available pre-export)
+ *   BEFORE this write; the span export (`span.end()`) happens after, async, best-effort.
+ * - `github_anchor` stitches an off-GitHub edge back to its GitHub object so the
+ *   on-GitHub and off-GitHub graphs join into one; `null` for a pure nudge.
+ */
+export declare const CommsLedgerEdgeSchema: z.ZodObject<{
+    ts: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    channel: z.ZodEnum<{
+        a2a: "a2a";
+        "github-route": "github-route";
+    }>;
+    event: z.ZodEnum<{
+        mention: "mention";
+        error: "error";
+        custom: "custom";
+        "session-end": "session-end";
+        "turn-complete": "turn-complete";
+        "issue-routed": "issue-routed";
+        "pr-review-state": "pr-review-state";
+    }>;
+    direction: z.ZodEnum<{
+        send: "send";
+        recv: "recv";
+    }>;
+    msg_id: z.ZodString;
+    intent_summary: z.ZodString;
+    github_anchor: z.ZodNullable<z.ZodString>;
+    delivered: z.ZodBoolean;
+    processed: z.ZodNullable<z.ZodBoolean>;
+    trace_id: z.ZodString;
+}, z.core.$strip>;
+export type CommsLedgerEdge = z.infer<typeof CommsLedgerEdgeSchema>;
+/** Max length of the deterministic intent-summary clip. */
+export declare const INTENT_SUMMARY_MAX = 120;
+/**
+ * Cheap, deterministic intent summary: the first non-empty line of the message,
+ * trimmed and clipped to `max` chars.
+ *
+ * Explicitly NOT an LLM summarize (#473 AC): keep a model dependency and its
+ * latency out of the delivery hot path. This runs synchronously on every edge.
+ */
+export declare function intentSummary(text: string | null | undefined, max?: number): string;
+/** Canonical per-agent ledger filename, kept as a sibling of `channel.log`. */
+export declare const COMMS_LEDGER_FILENAME = "comms-ledger.jsonl";
+/**
+ * Derive the ledger path from the channel-server's `logPath` (`MACF_LOG_PATH`),
+ * as a sibling file in the same `.macf/logs/` directory. Returns `undefined`
+ * when no log path is configured (the ledger is then a no-op, mirroring how the
+ * `logger` is a no-op without `MACF_LOG_PATH` — the real fleet always sets it).
+ */
+export declare function ledgerPathFromLog(logPath: string | undefined): string | undefined;
+export interface CommsLedger {
+    /**
+     * Append one coordination edge — SYNCHRONOUS and FAIL-LOUD.
+     *
+     * Throws if the write fails: an authoritative edge would otherwise be lost,
+     * and DR-025 names this the one operation that must NOT silently degrade.
+     * This is the structural distinction from the best-effort `logger`
+     * (`channel.log`), whose `logger.info` must stay non-fatal. Callers append to
+     * the ledger BEFORE the (async, best-effort) Tempo span export, so a Tempo or
+     * network failure can never cost an edge.
+     */
+    readonly appendEdge: (edge: CommsLedgerEdge) => void;
+    /** The resolved ledger path, or `undefined` if the ledger is a no-op. */
+    readonly path: string | undefined;
+}
+/**
+ * Create the per-agent write-ahead comms-ledger writer.
+ *
+ * Pass the channel-server's `logPath`; the ledger is written to a sibling
+ * `comms-ledger.jsonl` in the same directory. A distinct writer from `logger`
+ * by design — fail-loud, authoritative — never the best-effort log.
+ *
+ * Durability note (research-confirmed: OTel api 1.9.1 / Node `fs`): `appendFileSync`
+ * is synchronous and throws on write error (the fail-loud guarantee), but does
+ * NOT `fsync`. The threat model is a Tempo/network failure with the edge already
+ * on local disk — not power-loss — so per-write `fsync` (latency on every
+ * exchange) is deliberately skipped.
+ */
+export declare function createCommsLedger(opts: {
+    readonly logPath?: string | undefined;
+    /** Override the derived path (mainly for tests). */
+    readonly ledgerPath?: string | undefined;
+}): CommsLedger;
+/**
+ * Backfill `processed` on edges from a set of receipt keys (DR-025 / macf#444).
+ *
+ * Edges are written with `processed: null` (unknown-at-write); a receipt — proof
+ * the peer actually took a turn — resolves it. This is a PURE function: it does
+ * NOT mutate the append-only ledger, it produces a derived view (the same shape
+ * as `reconciler/reconcile.ts`, which joins delivered routes ⋈ turn receipts).
+ *
+ * Channel split for the `processed` (delivery ≠ turn) join:
+ *   - **a2a edges** join on `msg_id` via THIS function — `keyOf` maps the edge
+ *     to its `msg_id` and `receiptKeys` carries the observed receipts.
+ *   - **github-route edges** are tracked SEPARATELY by the macf#444 reconciler,
+ *     which is run_id-keyed off the prompt `[macf-route:RUN:AGENT]` marker. The
+ *     github-route recv edge intentionally does NOT carry that run_id (it is
+ *     absent from CommsLedgerEdge, NotifyPayload, and the `type:num:ts` msg_id),
+ *     so the `(run_id, agent)` join is structurally impossible HERE. A
+ *     github-route edge's `processed` therefore stays `null` in the ledger BY
+ *     DESIGN; its delivery≠turn distinction lives in the reconciler's view, not
+ *     this one. `backfillProcessed` is the a2a-side join.
+ *
+ * `keyOf` is left channel-agnostic on purpose (it just reads `msg_id` for the
+ * a2a join); edges whose `processed` is already non-null are left untouched
+ * (idempotent).
+ */
+export declare function backfillProcessed(edges: readonly CommsLedgerEdge[], receiptKeys: ReadonlySet<string>, keyOf: (edge: CommsLedgerEdge) => string): CommsLedgerEdge[];
+/**
+ * Gather + merge per-agent ledgers into one fleet view, ordered by `ts`.
+ *
+ * The per-agent ledger is the durable floor; Tempo is the central convenience
+ * index. When Tempo is down, fleet-graph analysis falls back to merging the
+ * per-agent ledgers. On the single-host substrate this is trivial — all the
+ * `comms-ledger.jsonl` files are local. For a MULTI-HOST fleet the gather step
+ * is explicit and operator-defined: collect each host's ledger (e.g.
+ * `rsync <agent-host>:.../comms-ledger.jsonl ./gathered/<agent>.jsonl`) into one
+ * place, then call this. There is deliberately NO central durable sink — that
+ * would reintroduce the single point of failure DR-025 exists to avoid.
+ *
+ * Malformed lines are skipped (a corrupt line must not blind the whole gather);
+ * this is the one place a parse error is tolerated, because gather is a derived
+ * read, not the authoritative write.
+ */
+export declare function mergeLedgers(contents: readonly string[]): CommsLedgerEdge[];
+/**
+ * Rotation/retention policy (DR-025 §"Costs", "no silent caps"):
+ *
+ * The ledger is the PERMANENT record, so rotation is deliberate and must NEVER
+ * silently truncate. The writer here only ever appends — it has no size cap and
+ * no truncation path by construction. If an operator rotates the file for size,
+ * the canonical action is archive-on-rotate (move the old file aside, e.g.
+ * `comms-ledger.jsonl.<date>`), never `> truncate` or head/tail clipping. Size
+ * management is an operator concern, intentionally outside this hot-path writer.
+ */
+export declare const ROTATION_POLICY: "archive-on-rotate; never silent truncation";
+//# sourceMappingURL=comms-ledger.d.ts.map

package/dist/comms-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-ledger.d.ts","sourceRoot":"","sources":["../src/comms-ledger.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;EAU3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,kBAAkB;;;EAAkC,CAAC;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,oBAAoB;;;EAA2B,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAahC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,GAAG,GAAE,MAA2B,GAC/B,MAAM,CAUR;AAED,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,WAAW,CAkBd;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,KAAK,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,MAAM,GACvC,eAAe,EAAE,CAInB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,EAAE,CAW3E;AAYD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAG,4CAAqD,CAAC"}

package/dist/comms-ledger.js

@@ -0,0 +1,224 @@
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+/**
+ * comms-ledger — the write-ahead, per-agent, authoritative record of every
+ * coordination edge the channel-server sends or receives.
+ *
+ * Implements DR-025 (observable coordination substrate). The invariant: any
+ * channel carrying agent-to-agent coordination MUST preserve a durable,
+ * graph-reconstructable, fleet-analyzable record. GitHub gives this for free;
+ * A2A / direct channels must earn it deliberately or the diagnose→redesign
+ * instrument (and the paper's evidence) goes blind. This is macf#444 one layer
+ * up; a Tempo-only design would reproduce silent-fallback Instance 8 (OTLP
+ * silent-drop) as the methodology's foundation.
+ *
+ * Resilience shape: a write-ahead log + a downstream rebuildable index. The
+ * JSONL ledger is AUTHORITATIVE (local disk, synchronous, fail-loud); the Tempo
+ * span is a DERIVED best-effort central index over the same data. The durable
+ * write happens BEFORE the lossy network hop, independent of Tempo's health.
+ *
+ * This module is the library layer (#473 piece 1): the schema, the unified
+ * event taxonomy, the fail-loud writer, the `processed` backfill join, the
+ * multi-host gather, and the rotation policy. Wiring it into the three edge
+ * sites (inbound `/notify`, inbound A2A `message/send`, outbound notify_peer)
+ * is #473 piece 2.
+ */
+/**
+ * Unified coordination-event taxonomy (DR-025 §"Channel unification").
+ * One enum spanning the A2A events and the router events, so a ledger edge
+ * analyzes identically regardless of which channel carried it.
+ */
+export const CommsEventSchema = z.enum([
+    // A2A / peer_notification (notify_peer `event`, message/send)
+    'turn-complete',
+    'session-end',
+    'error',
+    'custom',
+    // GitHub router (the macf-actions route-by-* blocks)
+    'issue-routed',
+    'mention',
+    'pr-review-state',
+]);
+export const CommsChannelSchema = z.enum(['a2a', 'github-route']);
+export const CommsDirectionSchema = z.enum(['send', 'recv']);
+/**
+ * One coordination edge — one JSONL line per exchange (DR-025 §"The edge schema").
+ *
+ * - `delivered` is known at edge-write (the byte sequence was accepted/pushed).
+ * - `processed` is the macf#444 distinction (delivery ≠ a turn actually happening).
+ *   It is NULLABLE at edge-write — the peer hasn't necessarily taken a turn yet —
+ *   and is backfilled later via the receipt join (`backfillProcessed`). The
+ *   edge-write must never block on it.
+ * - `trace_id` cross-references the Tempo span. It is captured synchronously from
+ *   `span.spanContext().traceId` (OTel api ≥1.9.1: synchronous, available pre-export)
+ *   BEFORE this write; the span export (`span.end()`) happens after, async, best-effort.
+ * - `github_anchor` stitches an off-GitHub edge back to its GitHub object so the
+ *   on-GitHub and off-GitHub graphs join into one; `null` for a pure nudge.
+ */
+export const CommsLedgerEdgeSchema = z.object({
+    ts: z.string(), // ISO 8601
+    from: z.string(),
+    to: z.string(),
+    channel: CommsChannelSchema,
+    event: CommsEventSchema,
+    direction: CommsDirectionSchema,
+    msg_id: z.string(),
+    intent_summary: z.string(),
+    github_anchor: z.string().nullable(),
+    delivered: z.boolean(),
+    processed: z.boolean().nullable(),
+    trace_id: z.string(),
+});
+/** Max length of the deterministic intent-summary clip. */
+export const INTENT_SUMMARY_MAX = 120;
+/**
+ * Cheap, deterministic intent summary: the first non-empty line of the message,
+ * trimmed and clipped to `max` chars.
+ *
+ * Explicitly NOT an LLM summarize (#473 AC): keep a model dependency and its
+ * latency out of the delivery hot path. This runs synchronously on every edge.
+ */
+export function intentSummary(text, max = INTENT_SUMMARY_MAX) {
+    if (!text)
+        return '';
+    const firstLine = text
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? '';
+    if (firstLine.length <= max)
+        return firstLine;
+    // Clip on a char boundary; the ellipsis signals truncation (never a silent cap).
+    return firstLine.slice(0, max - 1) + '…';
+}
+/** Canonical per-agent ledger filename, kept as a sibling of `channel.log`. */
+export const COMMS_LEDGER_FILENAME = 'comms-ledger.jsonl';
+/**
+ * Derive the ledger path from the channel-server's `logPath` (`MACF_LOG_PATH`),
+ * as a sibling file in the same `.macf/logs/` directory. Returns `undefined`
+ * when no log path is configured (the ledger is then a no-op, mirroring how the
+ * `logger` is a no-op without `MACF_LOG_PATH` — the real fleet always sets it).
+ */
+export function ledgerPathFromLog(logPath) {
+    if (!logPath)
+        return undefined;
+    return join(dirname(logPath), COMMS_LEDGER_FILENAME);
+}
+const NOOP_LEDGER = {
+    appendEdge: () => {
+        /* no path configured → no-op (mirrors logger when MACF_LOG_PATH unset) */
+    },
+    path: undefined,
+};
+/**
+ * Create the per-agent write-ahead comms-ledger writer.
+ *
+ * Pass the channel-server's `logPath`; the ledger is written to a sibling
+ * `comms-ledger.jsonl` in the same directory. A distinct writer from `logger`
+ * by design — fail-loud, authoritative — never the best-effort log.
+ *
+ * Durability note (research-confirmed: OTel api 1.9.1 / Node `fs`): `appendFileSync`
+ * is synchronous and throws on write error (the fail-loud guarantee), but does
+ * NOT `fsync`. The threat model is a Tempo/network failure with the edge already
+ * on local disk — not power-loss — so per-write `fsync` (latency on every
+ * exchange) is deliberately skipped.
+ */
+export function createCommsLedger(opts) {
+    const ledgerPath = opts.ledgerPath ?? ledgerPathFromLog(opts.logPath);
+    if (!ledgerPath)
+        return NOOP_LEDGER;
+    const dir = dirname(ledgerPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    if (!existsSync(ledgerPath))
+        writeFileSync(ledgerPath, '');
+    return {
+        path: ledgerPath,
+        appendEdge: (edge) => {
+            // Validate the shape (cheap, catches a malformed edge at the source),
+            // then append exactly one JSONL line. appendFileSync throws on any write
+            // error → propagates to the caller (fail-loud, per DR-025).
+            const line = JSON.stringify(CommsLedgerEdgeSchema.parse(edge));
+            appendFileSync(ledgerPath, line + '\n');
+        },
+    };
+}
+/**
+ * Backfill `processed` on edges from a set of receipt keys (DR-025 / macf#444).
+ *
+ * Edges are written with `processed: null` (unknown-at-write); a receipt — proof
+ * the peer actually took a turn — resolves it. This is a PURE function: it does
+ * NOT mutate the append-only ledger, it produces a derived view (the same shape
+ * as `reconciler/reconcile.ts`, which joins delivered routes ⋈ turn receipts).
+ *
+ * Channel split for the `processed` (delivery ≠ turn) join:
+ *   - **a2a edges** join on `msg_id` via THIS function — `keyOf` maps the edge
+ *     to its `msg_id` and `receiptKeys` carries the observed receipts.
+ *   - **github-route edges** are tracked SEPARATELY by the macf#444 reconciler,
+ *     which is run_id-keyed off the prompt `[macf-route:RUN:AGENT]` marker. The
+ *     github-route recv edge intentionally does NOT carry that run_id (it is
+ *     absent from CommsLedgerEdge, NotifyPayload, and the `type:num:ts` msg_id),
+ *     so the `(run_id, agent)` join is structurally impossible HERE. A
+ *     github-route edge's `processed` therefore stays `null` in the ledger BY
+ *     DESIGN; its delivery≠turn distinction lives in the reconciler's view, not
+ *     this one. `backfillProcessed` is the a2a-side join.
+ *
+ * `keyOf` is left channel-agnostic on purpose (it just reads `msg_id` for the
+ * a2a join); edges whose `processed` is already non-null are left untouched
+ * (idempotent).
+ */
+export function backfillProcessed(edges, receiptKeys, keyOf) {
+    return edges.map((e) => e.processed === null ? { ...e, processed: receiptKeys.has(keyOf(e)) } : e);
+}
+/**
+ * Gather + merge per-agent ledgers into one fleet view, ordered by `ts`.
+ *
+ * The per-agent ledger is the durable floor; Tempo is the central convenience
+ * index. When Tempo is down, fleet-graph analysis falls back to merging the
+ * per-agent ledgers. On the single-host substrate this is trivial — all the
+ * `comms-ledger.jsonl` files are local. For a MULTI-HOST fleet the gather step
+ * is explicit and operator-defined: collect each host's ledger (e.g.
+ * `rsync <agent-host>:.../comms-ledger.jsonl ./gathered/<agent>.jsonl`) into one
+ * place, then call this. There is deliberately NO central durable sink — that
+ * would reintroduce the single point of failure DR-025 exists to avoid.
+ *
+ * Malformed lines are skipped (a corrupt line must not blind the whole gather);
+ * this is the one place a parse error is tolerated, because gather is a derived
+ * read, not the authoritative write.
+ */
+export function mergeLedgers(contents) {
+    const edges = [];
+    for (const content of contents) {
+        for (const raw of content.split('\n')) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            const parsed = CommsLedgerEdgeSchema.safeParse(JSON.parse(safeJson(line)));
+            if (parsed.success)
+                edges.push(parsed.data);
+        }
+    }
+    return edges.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+}
+/** Parse-guard: return the line if it is JSON-parseable, else an empty object literal. */
+function safeJson(line) {
+    try {
+        JSON.parse(line);
+        return line;
+    }
+    catch {
+        return '{}';
+    }
+}
+/**
+ * Rotation/retention policy (DR-025 §"Costs", "no silent caps"):
+ *
+ * The ledger is the PERMANENT record, so rotation is deliberate and must NEVER
+ * silently truncate. The writer here only ever appends — it has no size cap and
+ * no truncation path by construction. If an operator rotates the file for size,
+ * the canonical action is archive-on-rotate (move the old file aside, e.g.
+ * `comms-ledger.jsonl.<date>`), never `> truncate` or head/tail clipping. Size
+ * management is an operator concern, intentionally outside this hot-path writer.
+ */
+export const ROTATION_POLICY = 'archive-on-rotate; never silent truncation';
+//# sourceMappingURL=comms-ledger.js.map

package/dist/comms-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-ledger.js","sourceRoot":"","sources":["../src/comms-ledger.ts"],"names":[],"mappings":"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"}