@cat-factory/kernel 0.213.0 → 0.215.0

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.213.0",
+  "version": "0.215.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.210.1"
+    "@cat-factory/contracts": "0.212.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",