@cat-factory/orchestration 0.193.0 → 0.195.0

package/dist/modules/tutorial/TutorialTelemetryService.js

@@ -0,0 +1,67 @@
+import { noopLogger } from '@cat-factory/kernel';
+/**
+ * How many DISTINCT tour ids one process (one isolate, on the Worker) will report as its own
+ * dimension value before folding the rest onto {@link OTHER_TOUR}.
+ *
+ * Sized well above any real catalog — the built-ins ship 13, and a deployment contributing its own
+ * is still counted in tens — so a healthy deployment never reaches it and an overflow is a genuine
+ * signal rather than a routine truncation.
+ */
+export const MAX_DISTINCT_TOURS = 64;
+/** The bucket every id past the cap is counted under. Visible in the data, never dropped. */
+export const OTHER_TOUR = 'other';
+const COUNTER = {
+    started: 'tutorial.tour_started',
+    completed: 'tutorial.tour_completed',
+    abandoned: 'tutorial.tour_abandoned',
+};
+/**
+ * Counts in-app tutorial funnel events, with the one thing a browser-supplied metric dimension
+ * cannot be trusted to be: BOUNDED.
+ *
+ * Every distinct dimension value is its own time series in the operator's backend, so an
+ * unbounded one costs them money and eventually gets the whole series dropped. The wire schema
+ * already constrains an id's SHAPE, which stops junk but not volume: a buggy or hostile client can
+ * still emit an unlimited number of well-formed ids. So this holds the set it has already reported
+ * and folds everything past {@link MAX_DISTINCT_TOURS} onto {@link OTHER_TOUR}.
+ *
+ * The overflow is REPORTED, not silently absorbed, in both the ways that matter: the `other` series
+ * exists in the data (so a reader can see that something was folded rather than concluding the tail
+ * was never sent), and the first overflow logs once, naming the cap. A cap nobody can see reads
+ * exactly like complete coverage.
+ *
+ * Per process rather than shared, matching the collector it feeds: a counter is accumulated and
+ * flushed per process on Node and per ISOLATE on the Worker, so a cap held anywhere else would be
+ * a different scope from the thing it is protecting.
+ */
+export class TutorialTelemetryService {
+    deps;
+    log;
+    seen = new Set();
+    overflowReported = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+    }
+    record(event, tourId) {
+        this.deps.metrics.increment(COUNTER[event], { tour: this.dimension(tourId) });
+    }
+    /** The bounded dimension value for a tour id: itself, or the overflow bucket. */
+    dimension(tourId) {
+        if (this.seen.has(tourId))
+            return tourId;
+        if (this.seen.size < MAX_DISTINCT_TOURS) {
+            this.seen.add(tourId);
+            return tourId;
+        }
+        if (!this.overflowReported) {
+            this.overflowReported = true;
+            this.log.warn('Tutorial event dimension cap reached; further tours counted as "other"', {
+                limit: MAX_DISTINCT_TOURS,
+                tourId,
+            });
+        }
+        return OTHER_TOUR;
+    }
+}
+//# sourceMappingURL=TutorialTelemetryService.js.map

package/dist/modules/tutorial/TutorialTelemetryService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TutorialTelemetryService.js","sourceRoot":"","sources":["../../../src/modules/tutorial/TutorialTelemetryService.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAA;AAEpC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAA;AAEjC,MAAM,OAAO,GAA8C;IACzD,OAAO,EAAE,uBAAuB;IAChC,SAAS,EAAE,yBAAyB;IACpC,SAAS,EAAE,yBAAyB;CACrC,CAAA;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,wBAAwB;IAKN,IAAI;IAJhB,GAAG,CAAQ;IACX,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,gBAAgB,GAAG,KAAK,CAAA;IAEhC,YAA6B,IAA0C;oBAA1C,IAAI;QAC/B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,UAAU,CAAA;IACtC,CAAC;IAED,MAAM,CAAC,KAAoB,EAAE,MAAc;QACzC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAC/E,CAAC;IAED,iFAAiF;IACzE,SAAS,CAAC,MAAc;QAC9B,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAA;QACxC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,kBAAkB,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACrB,OAAO,MAAM,CAAA;QACf,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAA;YAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,wEAAwE,EAAE;gBACtF,KAAK,EAAE,kBAAkB;gBACzB,MAAM;aACP,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,UAAU,CAAA;IACnB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/orchestration",
-  "version": "0.193.0",
+  "version": "0.195.0",
   "description": "Delivery-workflow engine for the Agent Architecture Board (execution, bootstrap, pipelines, board, boardScan, requirements, and composition root).",
   "repository": {
     "type": "git",
@@ -25,20 +25,20 @@
   },
   "dependencies": {
     "ai": "^7.0.47",
-    "@cat-factory/agents": "0.107.0",
-    "@cat-factory/caching": "0.14.0",
-    "@cat-factory/contracts": "0.222.0",
-    "@cat-factory/integrations": "0.121.2",
-    "@cat-factory/kernel": "0.224.0",
-    "@cat-factory/prompt-fragments": "0.15.47",
-    "@cat-factory/sandbox": "0.11.41",
-    "@cat-factory/spend": "0.13.12",
-    "@cat-factory/workspaces": "0.21.34"
+    "@cat-factory/agents": "0.108.0",
+    "@cat-factory/caching": "0.14.2",
+    "@cat-factory/contracts": "0.224.0",
+    "@cat-factory/integrations": "0.122.1",
+    "@cat-factory/kernel": "0.226.0",
+    "@cat-factory/prompt-fragments": "0.15.49",
+    "@cat-factory/sandbox": "0.11.43",
+    "@cat-factory/spend": "0.14.0",
+    "@cat-factory/workspaces": "0.21.36"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/sandbox-fixtures": "0.7.255"
+    "@cat-factory/sandbox-fixtures": "0.7.257"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",