@cat-factory/kernel 0.214.1 → 0.216.0

package/dist/ports/operational-metrics.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The closed set of operational counters. A closed union rather than a free string, so
+ * adding a signal is a typecheck-visible decision (with a metric name and a documented
+ * meaning) instead of a name typo that reports zero forever.
+ */
+export type OperationalCounter = 
+/** A stale run whose durable instance was lost and was re-created by a sweeper. */
+'sweep.run_redriven'
+/** A stale run whose durable instance was terminal, so the sweeper settled it instead. */
+ | 'sweep.run_finalized'
+/** A run failed `stalled`: re-driving never resurrected it past the hard deadline. */
+ | 'sweep.run_stalled'
+/** A sweeper pass threw. Dimensioned by `sweep`, so one sick sweeper is identifiable. */
+ | 'sweep.failed'
+/** A container job dispatch threw — the job never existed, so no poll can report it. */
+ | 'container.dispatch_failed'
+/** A container job settled as evicted/crashed. Dimensioned by the eviction kind. */
+ | 'container.evicted'
+/** An observability export was dropped (a trace sink, a metrics POST). */
+ | 'telemetry.export_dropped'
+/** An outbound notification delivery failed after its retries. */
+ | 'notification.delivery_failed'
+/** An app-cache read served from memory. Dimensioned by cache name. */
+ | 'cache.hit'
+/** An app-cache read that had to run its loader. Dimensioned by cache name. */
+ | 'cache.miss';
+/** The closed set of operational gauges — point-in-time readings, never accumulated. */
+export type OperationalGauge = 
+/** Jobs waiting in a durable queue right now. Dimensioned by `queue`. */
+'queue.depth';
+/**
+ * The split dimensions of one sample. Values MUST be bounded — a queue name, a cache name,
+ * an eviction kind — never a run/workspace/job id: every distinct value is its own metric
+ * time series in the operator's backend, so an unbounded dimension is a cardinality
+ * explosion that costs money and eventually gets the series dropped. The correlation ids
+ * belong on the LOG line (which is why every increment site also logs), not here.
+ */
+export type OperationalDimensions = Readonly<Record<string, string>>;
+/** One accumulated counter delta, ready to export. */
+export interface OperationalCounterSample {
+    counter: OperationalCounter;
+    dimensions: OperationalDimensions;
+    /** The delta accumulated since the previous drain (always > 0 — empty keys aren't emitted). */
+    value: number;
+}
+/** One point-in-time gauge reading. */
+export interface OperationalGaugeSample {
+    gauge: OperationalGauge;
+    dimensions: OperationalDimensions;
+    value: number;
+}
+/**
+ * Where operational events are counted. Injected the same way `Logger` is, so a domain
+ * service can count an event without knowing whether the deployment exports metrics at all.
+ */
+export interface OperationalMetrics {
+    /**
+     * Add `value` (default 1) to `counter` under `dimensions`. Never throws, never awaits —
+     * a call site on a hot path (a cache read) pays a Map lookup and an add.
+     */
+    increment(counter: OperationalCounter, dimensions?: OperationalDimensions, value?: number): void;
+}
+/**
+ * An {@link OperationalMetrics} that accumulates in memory until drained. The accumulate/drain
+ * split is what makes delta export correct: whoever drains owns a set of deltas nobody else
+ * will report, so two processes (or two Worker isolates) can flush independently and the
+ * backend's sum is still right.
+ */
+export interface OperationalMetricsCollector extends OperationalMetrics {
+    /**
+     * Take everything accumulated since the last call and RESET. Returns `[]` when nothing
+     * happened, which a caller should treat as "nothing to flush" — never as a reason to
+     * publish zeroes (an unflushed zero and a genuine zero are different facts, and only the
+     * absence of a data point states the first one honestly).
+     */
+    drain(): OperationalCounterSample[];
+}
+/** The disposition for a deployment that exports nothing: count into the void, cheaply. */
+export declare const noopOperationalMetrics: OperationalMetrics;
+/**
+ * Build an in-memory {@link OperationalMetricsCollector}. One per process (Node/local, drained
+ * by the platform-metrics sweep) or one per isolate (the Worker, drained at the end of each
+ * invocation — an isolate can be discarded at any moment, so anything it holds unflushed is
+ * simply lost).
+ */
+export declare function createOperationalMetricsCollector(): OperationalMetricsCollector;
+//# sourceMappingURL=operational-metrics.d.ts.map

package/dist/ports/operational-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-metrics.d.ts","sourceRoot":"","sources":["../../src/ports/operational-metrics.ts"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB;AAC5B,mFAAmF;AACjF,oBAAoB;AACtB,0FAA0F;GACxF,qBAAqB;AACvB,sFAAsF;GACpF,mBAAmB;AACrB,yFAAyF;GACvF,cAAc;AAChB,wFAAwF;GACtF,2BAA2B;AAC7B,oFAAoF;GAClF,mBAAmB;AACrB,0EAA0E;GACxE,0BAA0B;AAC5B,kEAAkE;GAChE,8BAA8B;AAChC,uEAAuE;GACrE,WAAW;AACb,+EAA+E;GAC7E,YAAY,CAAA;AAUhB,wFAAwF;AACxF,MAAM,MAAM,gBAAgB;AAC1B,yEAAyE;AACzE,aAAa,CAAA;AAEf;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEpE,sDAAsD;AACtD,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,kBAAkB,CAAA;IAC3B,UAAU,EAAE,qBAAqB,CAAA;IACjC,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAA;CACd;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,gBAAgB,CAAA;IACvB,UAAU,EAAE,qBAAqB,CAAA;IACjC,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,UAAU,CAAC,EAAE,qBAAqB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjG;AAED;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,kBAAkB;IACrE;;;;;OAKG;IACH,KAAK,IAAI,wBAAwB,EAAE,CAAA;CACpC;AAED,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,EAAE,kBAA4C,CAAA;AAYjF;;;;;GAKG;AACH,wBAAgB,iCAAiC,IAAI,2BAA2B,CA8B/E"}

package/dist/ports/operational-metrics.js

@@ -0,0 +1,67 @@
+// The operational-metrics port: the counters and gauges that describe how the DEPLOYMENT is
+// behaving, as opposed to how a run went.
+//
+// `PlatformMetricsRepository` already answers "how are the RUNS doing" by aggregating
+// `agent_runs` per account. It structurally cannot answer the questions an operator asks
+// during an incident — how often a container dispatch is failing, how many stale runs the
+// sweeper is re-driving, whether the queue is draining, whether telemetry batches are being
+// dropped — because none of those are rows in a table. They are EVENTS that happen and are
+// gone. This port is where they are counted.
+//
+// Two shapes, because the two facts have different lifetimes:
+//   - a COUNTER is a delta accumulated since the last flush (evictions, re-drives, cache
+//     misses). Exported with delta temporality, so a partial flush from one process/isolate
+//     still sums correctly with every other one.
+//   - a GAUGE is read at export time from something that already knows the answer (queue
+//     depth). It is never accumulated here; the sweep probes for it.
+//
+// The whole surface is fire-and-forget and MUST NOT throw, for the same reason `Logger` must
+// not: instrumentation that can fail turns observability into a new failure class.
+/** The disposition for a deployment that exports nothing: count into the void, cheaply. */
+export const noopOperationalMetrics = { increment: () => { } };
+/**
+ * A dimension map's stable identity, so `{a:'1',b:'2'}` and `{b:'2',a:'1'}` accumulate onto
+ * the same counter rather than two. Keys are sorted; the separators are control characters
+ * that cannot appear in a metric dimension value.
+ */
+function dimensionKey(dimensions) {
+    const keys = Object.keys(dimensions).sort();
+    return keys.map((k) => `${k}
${dimensions[k]}`).join('');
+}
+/**
+ * Build an in-memory {@link OperationalMetricsCollector}. One per process (Node/local, drained
+ * by the platform-metrics sweep) or one per isolate (the Worker, drained at the end of each
+ * invocation — an isolate can be discarded at any moment, so anything it holds unflushed is
+ * simply lost).
+ */
+export function createOperationalMetricsCollector() {
+    // Keyed by `counter` then by the dimension identity, so a drain can rebuild both halves
+    // without parsing the composite key back apart.
+    const counters = new Map();
+    return {
+        increment(counter, dimensions = {}, value = 1) {
+            let byDimensions = counters.get(counter);
+            if (!byDimensions) {
+                byDimensions = new Map();
+                counters.set(counter, byDimensions);
+            }
+            const key = dimensionKey(dimensions);
+            const existing = byDimensions.get(key);
+            if (existing)
+                existing.value += value;
+            else
+                byDimensions.set(key, { dims: dimensions, value });
+        },
+        drain() {
+            const samples = [];
+            for (const [counter, byDimensions] of counters) {
+                for (const { dims, value } of byDimensions.values()) {
+                    samples.push({ counter, dimensions: dims, value });
+                }
+            }
+            counters.clear();
+            return samples;
+        },
+    };
+}
+//# sourceMappingURL=operational-metrics.js.map

package/dist/ports/operational-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operational-metrics.js","sourceRoot":"","sources":["../../src/ports/operational-metrics.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,0CAA0C;AAC1C,EAAE;AACF,sFAAsF;AACtF,yFAAyF;AACzF,0FAA0F;AAC1F,4FAA4F;AAC5F,2FAA2F;AAC3F,6CAA6C;AAC7C,EAAE;AACF,8DAA8D;AAC9D,yFAAyF;AACzF,4FAA4F;AAC5F,iDAAiD;AACjD,yFAAyF;AACzF,qEAAqE;AACrE,EAAE;AACF,6FAA6F;AAC7F,mFAAmF;AA8FnF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,sBAAsB,GAAuB,EAAE,SAAS,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAA;AAEjF;;;;GAIG;AACH,SAAS,YAAY,CAAC,UAAiC;IACrD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAA;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC;IAC/C,wFAAwF;IACxF,gDAAgD;IAChD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAGrB,CAAA;IACH,OAAO;QACL,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,EAAE,EAAE,KAAK,GAAG,CAAC;YAC3C,IAAI,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YACxC,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,YAAY,GAAG,IAAI,GAAG,EAAE,CAAA;gBACxB,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;YACrC,CAAC;YACD,MAAM,GAAG,GAAG,YAAY,CAAC,UAAU,CAAC,CAAA;YACpC,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACtC,IAAI,QAAQ;gBAAE,QAAQ,CAAC,KAAK,IAAI,KAAK,CAAA;;gBAChC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAA;QACzD,CAAC;QACD,KAAK;YACH,MAAM,OAAO,GAA+B,EAAE,CAAA;YAC9C,KAAK,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,QAAQ,EAAE,CAAC;gBAC/C,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;oBACpD,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;gBACpD,CAAC;YACH,CAAC;YACD,QAAQ,CAAC,KAAK,EAAE,CAAA;YAChB,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/kernel",
-  "version": "0.214.1",
+  "version": "0.216.0",
   "description": "Shared vocabulary, pure logic, and port interfaces for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   "dependencies": {
     "ai": "^7.0.47",
     "yaml": "^2.9.0",
-    "@cat-factory/contracts": "0.211.0"
+    "@cat-factory/contracts": "0.213.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",