@warmdrift/kgauto-compiler 2.0.0-alpha.7 → 2.0.0-alpha.71

package/dist/glassbox/index.js

@@ -0,0 +1,312 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/glassbox/index.ts
+var glassbox_exports = {};
+__export(glassbox_exports, {
+  GLASSBOX_STREAM_TTL_MS: () => GLASSBOX_STREAM_TTL_MS,
+  subscribe: () => subscribe,
+  subscribeApp: () => subscribeApp
+});
+module.exports = __toCommonJS(glassbox_exports);
+
+// src/glassbox/types.ts
+var GLASSBOX_STREAM_TTL_MS = 6e4;
+
+// src/glassbox/pubsub-memory.ts
+var MemoryPubSub = class {
+  subscribers = /* @__PURE__ */ new Map();
+  async publish(channelKey, event) {
+    const subs = this.subscribers.get(channelKey);
+    if (!subs || subs.size === 0) return;
+    for (const sub of subs) {
+      if (sub.closed) continue;
+      try {
+        sub.controller.enqueue(event);
+      } catch {
+        sub.closed = true;
+        continue;
+      }
+      this.refreshTtl(channelKey, sub);
+    }
+  }
+  subscribe(channelKey) {
+    const self = this;
+    let sub;
+    return new ReadableStream({
+      start(controller) {
+        sub = {
+          controller,
+          ttlTimer: setTimeout(() => {
+            self.closeSubscriber(channelKey, sub);
+          }, GLASSBOX_STREAM_TTL_MS),
+          closed: false
+        };
+        let set = self.subscribers.get(channelKey);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          self.subscribers.set(channelKey, set);
+        }
+        set.add(sub);
+      },
+      cancel() {
+        if (sub) self.removeSubscriber(channelKey, sub);
+      }
+    });
+  }
+  /**
+   * Refresh the rolling TTL for a subscriber after an event lands. Replaces
+   * the existing timer with a fresh 60s one.
+   */
+  refreshTtl(channelKey, sub) {
+    clearTimeout(sub.ttlTimer);
+    sub.ttlTimer = setTimeout(() => {
+      this.closeSubscriber(channelKey, sub);
+    }, GLASSBOX_STREAM_TTL_MS);
+  }
+  /**
+   * Close the subscriber's stream cleanly and remove from the fan-out set.
+   * Idempotent — safe to call multiple times.
+   */
+  closeSubscriber(channelKey, sub) {
+    if (sub.closed) return;
+    sub.closed = true;
+    clearTimeout(sub.ttlTimer);
+    try {
+      sub.controller.close();
+    } catch {
+    }
+    this.removeSubscriber(channelKey, sub);
+  }
+  removeSubscriber(channelKey, sub) {
+    clearTimeout(sub.ttlTimer);
+    const set = this.subscribers.get(channelKey);
+    if (!set) return;
+    set.delete(sub);
+    if (set.size === 0) this.subscribers.delete(channelKey);
+  }
+  /**
+   * Test-only reset. Tears down all subscribers, clears all state. Calling
+   * outside of tests is harmless but cancels every active stream.
+   */
+  _reset() {
+    for (const [, set] of this.subscribers) {
+      for (const sub of set) {
+        this.closeSubscriber("", sub);
+      }
+    }
+    this.subscribers.clear();
+  }
+};
+
+// src/glassbox/pubsub-upstash.ts
+var UpstashPubSub = class {
+  url;
+  token;
+  fetchImpl;
+  blockMs;
+  maxLen;
+  constructor(cfg) {
+    this.url = cfg.url.replace(/\/$/, "");
+    this.token = cfg.token;
+    this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.blockMs = cfg.blockMs ?? 100;
+    this.maxLen = cfg.maxLen ?? 100;
+  }
+  async publish(channelKey, event) {
+    const key = channelKey;
+    const payload = JSON.stringify(event);
+    await this.cmd([
+      "XADD",
+      key,
+      "MAXLEN",
+      "~",
+      String(this.maxLen),
+      "*",
+      "event",
+      payload
+    ]);
+    await this.cmd(["EXPIRE", key, String(Math.ceil(GLASSBOX_STREAM_TTL_MS / 1e3))]);
+  }
+  subscribe(channelKey) {
+    const key = channelKey;
+    const self = this;
+    let cursor = "$";
+    let cancelled = false;
+    let ttlDeadline = Date.now() + GLASSBOX_STREAM_TTL_MS;
+    return new ReadableStream({
+      async start(controller) {
+        try {
+          while (!cancelled && Date.now() < ttlDeadline) {
+            const resp = await self.cmd([
+              "XREAD",
+              "BLOCK",
+              String(self.blockMs),
+              "STREAMS",
+              key,
+              cursor
+            ]);
+            if (cancelled) break;
+            const parsed = parseXReadResult(resp.result);
+            if (parsed.entries.length === 0) {
+              continue;
+            }
+            for (const entry of parsed.entries) {
+              const evt = decodeEvent(entry.fields);
+              if (evt) {
+                try {
+                  controller.enqueue(evt);
+                } catch {
+                  cancelled = true;
+                  break;
+                }
+              }
+              cursor = entry.id;
+            }
+            ttlDeadline = Date.now() + GLASSBOX_STREAM_TTL_MS;
+          }
+        } catch (err) {
+          if (!cancelled) {
+            try {
+              controller.error(err);
+            } catch {
+            }
+            return;
+          }
+        }
+        try {
+          controller.close();
+        } catch {
+        }
+      },
+      cancel() {
+        cancelled = true;
+      }
+    });
+  }
+  async cmd(args) {
+    const res = await this.fetchImpl(this.url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(args)
+    });
+    if (!res.ok) {
+      throw new Error(`Upstash ${args[0]} failed: HTTP ${res.status}`);
+    }
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`Upstash ${args[0]} failed: ${json.error}`);
+    }
+    return json;
+  }
+};
+function traceChannel(traceId) {
+  return `glassbox:trace:${traceId}`;
+}
+function appChannel(appId) {
+  return `glassbox:app:${appId}`;
+}
+function decodeEvent(fields) {
+  const raw = fields["event"];
+  if (!raw) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.kind === "string" && typeof parsed.at === "number") {
+      return parsed;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseXReadResult(raw) {
+  if (!Array.isArray(raw)) return { entries: [] };
+  const entries = [];
+  for (const stream of raw) {
+    if (!Array.isArray(stream) || stream.length < 2) continue;
+    const streamEntries = stream[1];
+    if (!Array.isArray(streamEntries)) continue;
+    for (const entry of streamEntries) {
+      if (!Array.isArray(entry) || entry.length < 2) continue;
+      const id = String(entry[0]);
+      const flat = entry[1];
+      if (!Array.isArray(flat)) continue;
+      const fields = {};
+      for (let i = 0; i < flat.length; i += 2) {
+        const k = flat[i];
+        const v = flat[i + 1];
+        if (typeof k === "string") fields[k] = String(v ?? "");
+      }
+      entries.push({ id, fields });
+    }
+  }
+  return { entries };
+}
+
+// src/glassbox/emit.ts
+var activePubSub;
+function getPubSub() {
+  if (activePubSub) return activePubSub;
+  const url = readEnv("UPSTASH_REDIS_URL");
+  const token = readEnv("UPSTASH_REDIS_TOKEN");
+  if (url && token) {
+    activePubSub = new UpstashPubSub({ url, token });
+  } else {
+    activePubSub = new MemoryPubSub();
+  }
+  return activePubSub;
+}
+function readEnv(key) {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      const v = process.env[key];
+      return v && v.trim() !== "" ? v : void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+
+// src/glassbox/subscribe.ts
+function emptyStream() {
+  return new ReadableStream({
+    start(controller) {
+      controller.close();
+    }
+  });
+}
+function subscribe(traceId) {
+  if (!traceId) return emptyStream();
+  return getPubSub().subscribe(traceChannel(traceId));
+}
+function subscribeApp({
+  appId
+}) {
+  if (!appId) return emptyStream();
+  return getPubSub().subscribe(appChannel(appId));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GLASSBOX_STREAM_TTL_MS,
+  subscribe,
+  subscribeApp
+});

package/dist/glassbox/index.mjs

@@ -0,0 +1,12 @@
+import {
+  subscribe,
+  subscribeApp
+} from "../chunk-RO22VFIF.mjs";
+import {
+  GLASSBOX_STREAM_TTL_MS
+} from "../chunk-NBO4R5PC.mjs";
+export {
+  GLASSBOX_STREAM_TTL_MS,
+  subscribe,
+  subscribeApp
+};

package/dist/glassbox-routes/format.d.mts

@@ -0,0 +1,24 @@
+import { T as TraceHealth } from '../types-DeGRCTlJ.mjs';
+import '../ir-CnnJST_N.mjs';
+import '../dialect.mjs';
+
+/**
+ * Pure formatting helpers for Glass-Box trace display.
+ *
+ * Zero deps, no React, no design tokens. Safe to import from any consumer
+ * (React component, server route, CLI, Edge worker).
+ *
+ * Extracted from the alpha.32 tt-intelligence reference component port in
+ * alpha.35 so multiple consumer dashboards can render trace data with
+ * matching formatting without re-implementing each helper.
+ */
+
+declare function formatAgo(iso: string, now?: number): string;
+declare function shortTraceId(traceId: string): string;
+declare function formatCost(usd: number | undefined | null): string;
+declare function formatMs(ms: number | undefined | null): string;
+declare function formatOrDash(v: number | string | undefined | null): string;
+declare function inputRatioLabel(status: TraceHealth['inputRatioStatus']): string;
+declare function formatMutation(mutation: string): string;
+
+export { formatAgo, formatCost, formatMs, formatMutation, formatOrDash, inputRatioLabel, shortTraceId };

package/dist/glassbox-routes/format.d.ts

@@ -0,0 +1,24 @@
+import { T as TraceHealth } from '../types-DSeJJ6tt.js';
+import '../ir-BEQ28muo.js';
+import '../dialect.js';
+
+/**
+ * Pure formatting helpers for Glass-Box trace display.
+ *
+ * Zero deps, no React, no design tokens. Safe to import from any consumer
+ * (React component, server route, CLI, Edge worker).
+ *
+ * Extracted from the alpha.32 tt-intelligence reference component port in
+ * alpha.35 so multiple consumer dashboards can render trace data with
+ * matching formatting without re-implementing each helper.
+ */
+
+declare function formatAgo(iso: string, now?: number): string;
+declare function shortTraceId(traceId: string): string;
+declare function formatCost(usd: number | undefined | null): string;
+declare function formatMs(ms: number | undefined | null): string;
+declare function formatOrDash(v: number | string | undefined | null): string;
+declare function inputRatioLabel(status: TraceHealth['inputRatioStatus']): string;
+declare function formatMutation(mutation: string): string;
+
+export { formatAgo, formatCost, formatMs, formatMutation, formatOrDash, inputRatioLabel, shortTraceId };

package/dist/glassbox-routes/format.js

@@ -0,0 +1,86 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/glassbox-routes/format.ts
+var format_exports = {};
+__export(format_exports, {
+  formatAgo: () => formatAgo,
+  formatCost: () => formatCost,
+  formatMs: () => formatMs,
+  formatMutation: () => formatMutation,
+  formatOrDash: () => formatOrDash,
+  inputRatioLabel: () => inputRatioLabel,
+  shortTraceId: () => shortTraceId
+});
+module.exports = __toCommonJS(format_exports);
+function formatAgo(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return iso;
+  const sec = Math.max(0, Math.floor((now - t) / 1e3));
+  if (sec < 60) return `${sec}s ago`;
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+  if (sec < 86400) return `${Math.floor(sec / 3600)}h ago`;
+  return `${Math.floor(sec / 86400)}d ago`;
+}
+function shortTraceId(traceId) {
+  return traceId.slice(-6);
+}
+function formatCost(usd) {
+  if (usd === void 0 || usd === null || Number.isNaN(usd)) return "\u2014";
+  if (usd === 0) return "$0.0000";
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(3)}`;
+}
+function formatMs(ms) {
+  if (ms === void 0 || ms === null) return "\u2014";
+  if (ms < 1e3) return `${ms}ms`;
+  return `${(ms / 1e3).toFixed(1)}s`;
+}
+function formatOrDash(v) {
+  if (v === void 0 || v === null) return "\u2014";
+  if (typeof v === "number") return v.toLocaleString();
+  return v;
+}
+function inputRatioLabel(status) {
+  switch (status) {
+    case "green":
+      return "healthy";
+    case "yellow":
+      return "borderline";
+    case "red":
+      return "input-heavy";
+  }
+}
+function formatMutation(mutation) {
+  const m = /^(.*)-(\d+)-to-(\d+)$/.exec(mutation);
+  if (m) {
+    return `${m[1]} (${m[2]} \u2192 ${m[3]})`;
+  }
+  return mutation;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatAgo,
+  formatCost,
+  formatMs,
+  formatMutation,
+  formatOrDash,
+  inputRatioLabel,
+  shortTraceId
+});

package/dist/glassbox-routes/format.mjs

@@ -0,0 +1,18 @@
+import {
+  formatAgo,
+  formatCost,
+  formatMs,
+  formatMutation,
+  formatOrDash,
+  inputRatioLabel,
+  shortTraceId
+} from "../chunk-P3TOAEG4.mjs";
+export {
+  formatAgo,
+  formatCost,
+  formatMs,
+  formatMutation,
+  formatOrDash,
+  inputRatioLabel,
+  shortTraceId
+};

package/dist/glassbox-routes/index.d.mts

@@ -0,0 +1,191 @@
+import { G as GlassboxEvent } from '../types-BDFrJkma.mjs';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-DeGRCTlJ.mjs';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-DeGRCTlJ.mjs';
+import '../ir-CnnJST_N.mjs';
+import '../dialect.mjs';
+
+/**
+ * proxy(req) — Glass-Box replay query handler.
+ *
+ * GET /api/glassbox/proxy?traceId=<id>   → single compile_outcomes row for trace
+ * GET /api/glassbox/proxy?limit=<N>      → N most-recent compile_outcomes rows
+ * GET /api/glassbox/proxy                → defaults to limit=20
+ *
+ * Brain reads go through PostgREST on Supabase. We always filter by
+ * `app_id=eq.<appId>` even though the scoped JWT's RLS policy already
+ * enforces tenant isolation — the explicit filter trims the network payload
+ * and makes the query intent obvious to anyone reading logs.
+ *
+ * Scrub: the optional `scrub` hook runs on each row before responding so
+ * sensitive payloads (rendered prompts, tool calls) can be redacted at the
+ * proxy boundary. Default is identity (no-op).
+ */
+
+/**
+ * Typed boundary transformer: compile_outcomes row (snake_case, Postgres
+ * native) → TraceSummary (camelCase, TypeScript native + extension wire
+ * contract). Single canonical mapping site — every DB-shape ↔ wire-shape
+ * crossing routes through here so renderer-expected fields can't silently
+ * go missing. See `feedback_typed_boundary_transformers.md` for the rule.
+ */
+declare function rowToSummary(row: Record<string, unknown>): TraceSummary;
+/**
+ * Typed boundary transformer (L-118): compile_outcomes row → TraceDetail.
+ * Single canonical mapping site for the detail-view wire contract. Pre-018
+ * brain rows return NULL for the new columns; this transformer applies
+ * type-safe defaults (0 for token columns, undefined for optional strings)
+ * so the renderer never crashes on missing fields.
+ *
+ * alpha.28 extends the field set per the renderer design contract — every
+ * extended field has a default. The `counterfactuals` + `projectedDailyCost`
+ * fields are populated by the proxy AFTER this transformer runs (they need
+ * profile lookup / brain query / async I/O).
+ */
+declare function rowToDetail(row: Record<string, unknown>): TraceDetail;
+
+/**
+ * computeCounterfactuals — for a served trace, compute up to 2 cheaper
+ * alternatives that ALSO meet the archetype quality floor.
+ *
+ * Pure function. Called at detail-view time by the proxy's `rowToDetail`
+ * path. The cost-equivalent answer to "what could this have run on without
+ * tanking quality?" lets the Glass-Box render `💰 Cheaper alternatives` so a
+ * founder sees the actual cost of the routing choice rather than just the
+ * served cost.
+ *
+ * Mechanism (per design contract Phase 0 spec):
+ *   1. Walk the archetype's full default fallback chain.
+ *   2. For each model in the chain (excluding the served model):
+ *      - Skip if archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT (6).
+ *        Matches the cliff-advisor work — never recommend a swap that
+ *        violates the quality floor. (Composition with Builder C is
+ *        intentional.)
+ *      - Skip if profile missing.
+ *      - Compute estimated cost at the OBSERVED token counts:
+ *          non_cached_in = tokensIn - cacheReadInputTokens
+ *          cost = (non_cached_in / 1e6) * profile.costInputPer1m
+ *               + (cacheable_in   / 1e6) * profile.costInputPer1m
+ *                                       * profile.lowering.cache.discount
+ *               + (tokensOut      / 1e6) * profile.costOutputPer1m
+ *      - Only include if estimatedCostUsd ≤ 0.9 × servedCostUsd
+ *        (≥10% cheaper — below that's noise of token-count estimation).
+ *   3. Sort cheapest first.
+ *   4. Cap to top 2.
+ *
+ * Edge cases:
+ *   - tokensIn === 0 → return [] (can't meaningfully estimate).
+ *   - servedCostUsd === 0 → return [] (no baseline to beat).
+ *   - Zero matching alternatives → return [] (renderer hides the card).
+ *   - Served model isn't in the chain (e.g. forceModel'd off-chain) → use
+ *     the chain for the archetype anyway.
+ */
+
+/** Only surface swaps that save at least 10% vs. served. */
+declare const COUNTERFACTUAL_MIN_SAVINGS_RATIO = 0.1;
+/** Cap on alternatives surfaced per trace. */
+declare const COUNTERFACTUAL_MAX_RESULTS = 2;
+interface ComputeCounterfactualsArgs {
+    servedModel: string;
+    servedCostUsd: number;
+    archetype: string;
+    tokensIn: number;
+    tokensOut: number;
+    /** Defaults to 0 when caller doesn't know. */
+    cacheReadInputTokens?: number;
+    /** Reserved for future per-mode chain selection. */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+declare function computeCounterfactuals(args: ComputeCounterfactualsArgs): TraceCounterfactual[];
+
+/**
+ * Public entry point for `@warmdrift/kgauto-compiler/glassbox-routes`.
+ *
+ * One factory call from a Vercel Edge consumer route handler gets you both
+ * the replay-query (`proxy`) and live-SSE (`stream`) endpoints that the
+ * Glass-Box Chrome panel reads. Wiring is ~6 lines per app:
+ *
+ *   // app/api/glassbox/proxy/route.ts
+ *   import { createGlassboxRoutes } from '@warmdrift/kgauto-compiler/glassbox-routes';
+ *   const { proxy } = createGlassboxRoutes({
+ *     installToken:  process.env.GLASSBOX_INSTALL_TOKEN!,
+ *     extensionId:   process.env.GLASSBOX_EXTENSION_ID!,
+ *     brainEndpoint: process.env.GLASSBOX_BRAIN_ENDPOINT!,
+ *     brainJwt:      process.env.GLASSBOX_BRAIN_JWT!,      // scoped JWT (RLS via app_id claim)
+ *     brainAnonKey:  process.env.GLASSBOX_BRAIN_ANON_KEY!, // project anon/publishable key (Supabase apikey header)
+ *     appId:         'playbacksam',
+ *   });
+ *   export { proxy as GET };
+ *
+ * Auth model (defense in depth):
+ *   - Bearer install token   → primary, constant-time compared
+ *   - chrome-extension Origin → secondary CSRF gate
+ *
+ * Scrub: optional sanitization runs at the proxy boundary before events or
+ * rows leave the consumer's infrastructure. Per pii-scrubber-call-site-not-
+ * package: kgauto stays naive to PII policy; consumers pass scrub hooks
+ * that encode their own data-handling rules.
+ *
+ * Brain reads use the scoped JWT minted via migration 013. RLS enforces
+ * `app_id = jwt.claim.app_id`; the proxy filter is belt-and-suspenders for
+ * payload size + log legibility.
+ */
+
+interface GlassboxRoutesConfig {
+    /** Bearer token validated on every request via constant-time compare. Required. */
+    installToken: string;
+    /** chrome-extension://<id> — exact match required on Origin header. Required. */
+    extensionId: string;
+    /** Brain endpoint base (e.g. https://kgauto-brain.supabase.co). Used by `proxy` for replay queries. */
+    brainEndpoint: string;
+    /** Scoped JWT for brain reads. Use the per-consumer JWT minted via migration 013 (claim: app_id). Drives RLS via the `app_id` claim; sent as `Authorization: Bearer <jwt>` only. */
+    brainJwt: string;
+    /**
+     * Anon/publishable key for the Supabase `apikey` header. Supabase requires
+     * `apikey` to be one of the project's known keys (anon or service_role) —
+     * the scoped JWT in `brainJwt` doesn't qualify there. Pass the project's
+     * legacy `anon` key (JWT format, role=anon) or the modern `sb_publishable_...`
+     * key. Safe to expose at the wire (that's what "publishable" means).
+     *
+     * Pre-alpha.24 this was missing and `brainJwt` was used as apikey too — first
+     * real call always 401'd against real Supabase. Catching this required a
+     * pre-publish smoke against the real brain; unit tests with mocked fetch
+     * couldn't surface it. See L-117 in command-center/learnings.md.
+     */
+    brainAnonKey: string;
+    /** App scope filter — must match the JWT's app_id claim. */
+    appId: string;
+    /**
+     * Optional sanitization hook. Called with each event/trace BEFORE it leaves the consumer.
+     * Default: identity (no scrub). PII policy lives at the call-site, not in the package.
+     */
+    scrub?: (event: GlassboxEvent | Record<string, unknown>) => GlassboxEvent | Record<string, unknown>;
+    /**
+     * Test-only seam: override the brain fetch implementation. Production
+     * code never sets this; tests use it to mock PostgREST responses.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Test-only seam: override the per-trace live-stream subscriber. Production
+     * code resolves to the alpha.17 `subscribe()` export; tests inject a fake
+     * source ReadableStream<GlassboxEvent>.
+     */
+    subscribe?: (traceId: string) => ReadableStream<GlassboxEvent>;
+    /**
+     * Test-only seam: override the per-app "tail-all" subscriber (alpha.26).
+     * Production code resolves to the `subscribeApp()` export; tests inject
+     * a fake source. Backs the extension's default Live tab mode when no
+     * traceId is supplied in the URL.
+     */
+    subscribeApp?: (args: {
+        appId: string;
+    }) => ReadableStream<GlassboxEvent>;
+}
+interface GlassboxRoutes {
+    /** GET /api/glassbox/proxy?traceId=<id>  OR  ?limit=20 (recent traces) */
+    proxy: (req: Request) => Promise<Response>;
+    /** GET /api/glassbox/stream?traceId=<id>  (SSE) */
+    stream: (req: Request) => Promise<Response>;
+}
+declare function createGlassboxRoutes(config: GlassboxRoutesConfig): GlassboxRoutes;
+
+export { COUNTERFACTUAL_MAX_RESULTS, COUNTERFACTUAL_MIN_SAVINGS_RATIO, type ComputeCounterfactualsArgs, type GlassboxRoutes, type GlassboxRoutesConfig, TraceCounterfactual, TraceDetail, TraceSummary, computeCounterfactuals, createGlassboxRoutes, rowToDetail, rowToSummary };