cartethyia 2.5.4 → 2.5.6

package/src/observability/redaction.ts

@@ -1,13 +1,12 @@
 // Client-IP presentation masking.
 //
-// This module used to also carry a telemetry redactor that rewrote any string
-// containing a credential-shaped token into a placeholder. It was meant for
-// display, but `***REDACTED***` in a captured body is indistinguishable from
+// This module carries no string-sniffing payload redactor, and must not grow
+// one: `***REDACTED***` in a captured body is indistinguishable from
 // `***REDACTED***` in a payload that was actually sent — so a memory-review
-// turn quoting one JWT rendered as a fully redacted message, and a 400 from
-// the provider looked like the gateway had mangled the request.
+// turn quoting one JWT would render as a fully redacted message, and a 400 from
+// the provider would look like the gateway had mangled the request.
 //
-// Payload bodies are stored verbatim now. The upstream already refuses and
+// Payload bodies are stored verbatim. The upstream already refuses and
 // reports credentials on its own; a second, string-sniffing layer only
 // destroys the evidence needed to read a failure.
 

package/src/observability/request-notify.ts

@@ -0,0 +1,43 @@
+/**
+ * Lightweight fan-out for completed gateway requests.
+ *
+ * `notifyRequestCompleted` is called once per terminal request (same site as
+ * `telemetryBuffer.enqueue`). Subscribers receive a minimal summary — just
+ * enough for the dashboard SSE stream to trigger a targeted refetch rather
+ * than polling.
+ */
+
+export interface RequestCompletedNotice {
+  readonly tenantId: string;
+  readonly requestId: string;
+  readonly status: string;
+  readonly httpStatus: number;
+}
+
+type Listener = (notice: RequestCompletedNotice) => void;
+
+const listeners = new Set<Listener>();
+
+/** Notify all subscribers that a request has reached a terminal state. */
+export function notifyRequestCompleted(notice: RequestCompletedNotice): void {
+  for (const listener of listeners) {
+    try {
+      listener(notice);
+    } catch {
+      // Listener failures must not affect the request path.
+    }
+  }
+}
+
+/** Subscribe to per-request terminal notifications; returns unsubscribe. */
+export function subscribeRequestCompleted(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Test-only: clear all subscribers. */
+export function resetRequestNotifyForTests(): void {
+  listeners.clear();
+}

package/src/observability/telemetry-status.ts

@@ -1,13 +1,12 @@
 /**
  * The single definition of which requests count as *gateway* errors.
  *
- * Six independent sites used to answer this question with their own copy of
- * `status in ('failed', 'truncated')`: the usage summary, the health window,
- * the usage breakdown, the retained-usage rollup (`telemetry_usage_totals`),
- * the public share page, and the client-IP breakdown. A definition spread over
- * six predicates is not a definition — it is six chances to drift, and the
- * rollup made the drift durable: once a request is counted into
- * `telemetry_usage_totals.errors` it stays counted after the raw row is pruned.
+ * One definition keeps the six sites that ask this — the usage summary, the
+ * health window, the usage breakdown, the retained-usage rollup
+ * (`telemetry_usage_totals`), the public share page, and the client-IP
+ * breakdown — from drifting apart, which matters because the rollup makes any
+ * drift durable: once a request is counted into `telemetry_usage_totals.errors`
+ * it stays counted after the raw row is pruned.
  *
  * The rule, stated as a principle rather than a list of codes:
  *
@@ -23,8 +22,8 @@
  *   an unregistered `/v1/*` path, a `429` from the caller's own quota, and a
  *   `413` from an oversized body all cost the sender nothing and reach no
  *   provider, so counting any of them hands an abuser a free way to inflate
- *   the error rate. Enumerating "the bad ones" was the previous approach and it
- *   missed `401`/`429`; excluding the class cannot miss one.
+ *   the error rate. Enumerating "the bad ones" misses `401`/`429`; excluding the
+ *   class cannot miss one.
  * - **`499`** is a client abort (`transport_closed`). The client leaving is
  *   expected behavior — the request may even have been served — and it is
  *   tracked as its own count. Being below `500`, it is excluded by the class

package/src/observability/token-speed.ts

@@ -51,10 +51,11 @@ export interface TokenSpeedInput {
 export function computeTokensPerSec(input: TokenSpeedInput): number | undefined {
   const outputTokens = input.outputTokens;
   // `!Number.isFinite` rather than `<= 0`: a NaN token count fails `NaN <= 0`
-  // (`false`), so it used to pass through and the division produced a NaN speed —
-  // which reaches the telemetry row and renders as a literal "NaN tok/s" in the
-  // Requests table. That is the case where a wrong number is least welcome, since
-  // the row that produced it is the one an operator is investigating.
+  // (`false`), so it would pass through and the division would produce a NaN
+  // speed — which reaches the telemetry row and renders as a literal
+  // "NaN tok/s" in the Requests table. That is the case where a wrong number is
+  // least welcome, since the row that produced it is the one an operator is
+  // investigating.
   if (outputTokens === undefined || !Number.isFinite(outputTokens) || outputTokens <= 0) {
     return undefined;
   }

package/src/persistence/db-mode.ts

@@ -8,17 +8,17 @@ export type DbMode = "full" | "lite";
 /**
  * Reads `CARTETHYIA_DB_MODE`, which is required and has no default.
  *
- * It used to default to `full`, which left the same key carrying three
- * different answers: `.env.example` shipped `lite`, the `bun setup` prompt
- * offered `lite`, and an environment that set nothing at all booted `full`.
- * The third one is the one that bit — a clone without a `.env` came up in Full
- * mode and then failed on a missing `DATABASE_URL`, when the documented intent
- * was the self-contained Lite path.
+ * It must not default to `full`: that leaves the same key carrying three
+ * different answers, since `.env.example` ships `lite`, the `bun setup` prompt
+ * offers `lite`, and an environment that sets nothing at all would boot
+ * `full`. The third one is the one that bites — a clone without a `.env` comes
+ * up in Full mode and then fails on a missing `DATABASE_URL`, when the
+ * documented intent is the self-contained Lite path.
  *
  * Failing closed is the honest fix: the two modes are different databases with
  * different migration sets (`migrations/lite-sqlite3/` vs
  * `migrations/full-postgres/`), so guessing one silently picks which migrations
- * an operator's data is read against. `bun setup`, `scripts/install/lite.sh`,
+ * an operator's data is read against. `bun setup`, `scripts/install.sh`,
  * `.env.example`, and `docker-compose.yml` all set it explicitly,
  * so requiring it costs an existing deployment nothing.
  */

package/src/persistence/readiness.ts

@@ -9,7 +9,7 @@ import { withTimeout } from "../boot/timeout";
 /**
  * Memoized readiness: the first caller runs the real `SELECT 1`/`PING`/
  * migration checks, and every subsequent caller within the TTL window reuses
- * that result — so a burst of concurrent requests no longer each spend a
+ * that result — so a burst of concurrent requests does not each spend a
  * Postgres pool checkout plus a Redis PING on readiness validation.
  */