@warmdrift/kgauto-compiler 2.0.0-alpha.17 → 2.0.0-alpha.18

package/dist/chunk-VZGMWKRT.mjs

@@ -0,0 +1,19 @@
+import {
+  getPubSub
+} from "./chunk-NUTC7NUC.mjs";
+
+// src/glassbox/subscribe.ts
+function subscribe(traceId) {
+  if (!traceId) {
+    return new ReadableStream({
+      start(controller) {
+        controller.close();
+      }
+    });
+  }
+  return getPubSub().subscribe(traceId);
+}
+
+export {
+  subscribe
+};

package/dist/glassbox/index.d.mts

@@ -1,125 +1,8 @@
-import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from '../ir-C3P4gDt0.mjs';
+import { G as GlassboxEvent } from '../types-DWF6mPGg.mjs';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-DWF6mPGg.mjs';
+import '../ir-C3P4gDt0.mjs';
 import '../dialect.mjs';
 
-/**
- * Glass-Box observability types (alpha.17).
- *
- * The substrate for kgauto's in-flight observability surface — a Chrome MV3
- * side panel that renders compile + execute + advisor outputs in real-time.
- * See design doc:
- *   ~/.gstack/projects/stue-kgauto/stgreen-claude-serene-williamson-51a105-design-20260518-175356.md
- *
- * Wire shape is intentionally minimal:
- *   { kind, at, data } — discriminated union by `kind`.
- *
- * Critical-path safety (L-086 derived): emit MUST NEVER fail the user's
- * `call()` invocation. emit.ts wraps every adapter write in try/catch +
- * silently drops on error. Consumers in Vercel Edge runtimes can lose one
- * event without losing the response.
- */
-
-/**
- * Discriminator. Six event kinds cover the v1 substrate. New kinds added
- * additively; the side-panel renderer treats unknown kinds as "ignore".
- */
-type GlassboxEventKind = 'compile.start' | 'compile.done' | 'execute.attempt' | 'execute.success' | 'advisory.fired' | 'fallback.walked';
-/**
- * Wire envelope. Every emit lands as one of these.
- *
- *   - kind:    discriminator
- *   - at:      unix milliseconds (Date.now())
- *   - data:    kind-specific payload
- *
- * `data` typed loosely as Record<string, unknown> for serialization-friendliness;
- * the per-kind builders below populate it with the structured shape expected
- * by the renderer. We deliberately do NOT typescript-narrow `data` by kind on
- * the wire type — the side panel reads JSON from SSE and only the renderer
- * needs the narrowed shape. Internal callers (emit.ts) get type assistance via
- * the typed factory helpers in emit.ts.
- */
-interface GlassboxEvent {
-    kind: GlassboxEventKind;
-    at: number;
-    data: Record<string, unknown>;
-}
-/**
- * Per-kind data shapes. Surfaced as type aids; not enforced at the
- * GlassboxEvent boundary (intentionally — see comment above).
- */
-interface CompileStartData {
-    appId: string;
-    archetype: string;
-    models: string[];
-}
-interface CompileDoneData {
-    target: string;
-    provider: string;
-    fallbackChain: string[];
-    tokensIn: number;
-    estimatedCostUsd: number;
-    mutationsApplied: MutationApplied[];
-    advisories: BestPracticeAdvisory[];
-}
-interface ExecuteAttemptData {
-    model: string;
-    attemptIndex: number;
-}
-interface ExecuteSuccessData {
-    model: string;
-    tokensIn: number;
-    tokensOut: number;
-    latencyMs: number;
-}
-interface AdvisoryFiredData {
-    code: string;
-    message: string;
-}
-interface FallbackWalkedData {
-    from: string;
-    to: string;
-    reason: FallbackReason | 'unknown';
-    attempt: CallAttempt;
-}
-/**
- * Pub/sub backend interface. Two adapters implement it: in-memory (dev /
- * single-process) and Upstash Redis Streams (Vercel Edge multi-instance).
- *
- * The choice is made at module load (NOT per-call) based on env-var presence:
- *   if (UPSTASH_REDIS_URL && UPSTASH_REDIS_TOKEN) → Upstash
- *   else                                          → in-memory
- *
- * Stream TTL: 60s after last event. After that, subscriber stream closes
- * cleanly. The adapter owns its own TTL clock; subscribe() is agnostic.
- */
-interface GlassboxPubSub {
-    /**
-     * Publish a single event for a traceId. Returns a promise that resolves
-     * after the event is durably appended (or rejects on adapter failure —
-     * callers in emit.ts always swallow rejections).
-     */
-    publish(traceId: string, event: GlassboxEvent): Promise<void>;
-    /**
-     * Subscribe to events for a traceId. Returns a ReadableStream that emits
-     * GlassboxEvent objects as they're published. The stream closes cleanly
-     * after the per-trace TTL elapses since the LAST event (rolling 60s).
-     *
-     * If the traceId has no publisher within 60s of subscription, the stream
-     * closes empty.
-     */
-    subscribe(traceId: string): ReadableStream<GlassboxEvent>;
-    /**
-     * Test-only escape hatch. Clears any in-memory state. Upstash adapter
-     * no-ops (server-side state isn't accessible from here). Tests reach for
-     * this between cases to keep adapters hermetic.
-     */
-    _reset?(): void;
-}
-/**
- * TTL applied to a stream after each event. The design doc names 60s; this
- * constant centralizes it so both adapters + tests agree.
- */
-declare const GLASSBOX_STREAM_TTL_MS = 60000;
-
 /**
  * subscribe(traceId) — public Glass-Box subscription export.
  *
@@ -156,4 +39,4 @@ declare const GLASSBOX_STREAM_TTL_MS = 60000;
  */
 declare function subscribe(traceId: string): ReadableStream<GlassboxEvent>;
 
-export { type AdvisoryFiredData, type CompileDoneData, type CompileStartData, type ExecuteAttemptData, type ExecuteSuccessData, type FallbackWalkedData, GLASSBOX_STREAM_TTL_MS, type GlassboxEvent, type GlassboxEventKind, type GlassboxPubSub, subscribe };
+export { GlassboxEvent, subscribe };

package/dist/glassbox/index.d.ts

@@ -1,125 +1,8 @@
-import { j as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, g as CallAttempt } from '../ir-CFHU3BUT.js';
+import { G as GlassboxEvent } from '../types-xeklorHU.js';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-xeklorHU.js';
+import '../ir-CFHU3BUT.js';
 import '../dialect.js';
 
-/**
- * Glass-Box observability types (alpha.17).
- *
- * The substrate for kgauto's in-flight observability surface — a Chrome MV3
- * side panel that renders compile + execute + advisor outputs in real-time.
- * See design doc:
- *   ~/.gstack/projects/stue-kgauto/stgreen-claude-serene-williamson-51a105-design-20260518-175356.md
- *
- * Wire shape is intentionally minimal:
- *   { kind, at, data } — discriminated union by `kind`.
- *
- * Critical-path safety (L-086 derived): emit MUST NEVER fail the user's
- * `call()` invocation. emit.ts wraps every adapter write in try/catch +
- * silently drops on error. Consumers in Vercel Edge runtimes can lose one
- * event without losing the response.
- */
-
-/**
- * Discriminator. Six event kinds cover the v1 substrate. New kinds added
- * additively; the side-panel renderer treats unknown kinds as "ignore".
- */
-type GlassboxEventKind = 'compile.start' | 'compile.done' | 'execute.attempt' | 'execute.success' | 'advisory.fired' | 'fallback.walked';
-/**
- * Wire envelope. Every emit lands as one of these.
- *
- *   - kind:    discriminator
- *   - at:      unix milliseconds (Date.now())
- *   - data:    kind-specific payload
- *
- * `data` typed loosely as Record<string, unknown> for serialization-friendliness;
- * the per-kind builders below populate it with the structured shape expected
- * by the renderer. We deliberately do NOT typescript-narrow `data` by kind on
- * the wire type — the side panel reads JSON from SSE and only the renderer
- * needs the narrowed shape. Internal callers (emit.ts) get type assistance via
- * the typed factory helpers in emit.ts.
- */
-interface GlassboxEvent {
-    kind: GlassboxEventKind;
-    at: number;
-    data: Record<string, unknown>;
-}
-/**
- * Per-kind data shapes. Surfaced as type aids; not enforced at the
- * GlassboxEvent boundary (intentionally — see comment above).
- */
-interface CompileStartData {
-    appId: string;
-    archetype: string;
-    models: string[];
-}
-interface CompileDoneData {
-    target: string;
-    provider: string;
-    fallbackChain: string[];
-    tokensIn: number;
-    estimatedCostUsd: number;
-    mutationsApplied: MutationApplied[];
-    advisories: BestPracticeAdvisory[];
-}
-interface ExecuteAttemptData {
-    model: string;
-    attemptIndex: number;
-}
-interface ExecuteSuccessData {
-    model: string;
-    tokensIn: number;
-    tokensOut: number;
-    latencyMs: number;
-}
-interface AdvisoryFiredData {
-    code: string;
-    message: string;
-}
-interface FallbackWalkedData {
-    from: string;
-    to: string;
-    reason: FallbackReason | 'unknown';
-    attempt: CallAttempt;
-}
-/**
- * Pub/sub backend interface. Two adapters implement it: in-memory (dev /
- * single-process) and Upstash Redis Streams (Vercel Edge multi-instance).
- *
- * The choice is made at module load (NOT per-call) based on env-var presence:
- *   if (UPSTASH_REDIS_URL && UPSTASH_REDIS_TOKEN) → Upstash
- *   else                                          → in-memory
- *
- * Stream TTL: 60s after last event. After that, subscriber stream closes
- * cleanly. The adapter owns its own TTL clock; subscribe() is agnostic.
- */
-interface GlassboxPubSub {
-    /**
-     * Publish a single event for a traceId. Returns a promise that resolves
-     * after the event is durably appended (or rejects on adapter failure —
-     * callers in emit.ts always swallow rejections).
-     */
-    publish(traceId: string, event: GlassboxEvent): Promise<void>;
-    /**
-     * Subscribe to events for a traceId. Returns a ReadableStream that emits
-     * GlassboxEvent objects as they're published. The stream closes cleanly
-     * after the per-trace TTL elapses since the LAST event (rolling 60s).
-     *
-     * If the traceId has no publisher within 60s of subscription, the stream
-     * closes empty.
-     */
-    subscribe(traceId: string): ReadableStream<GlassboxEvent>;
-    /**
-     * Test-only escape hatch. Clears any in-memory state. Upstash adapter
-     * no-ops (server-side state isn't accessible from here). Tests reach for
-     * this between cases to keep adapters hermetic.
-     */
-    _reset?(): void;
-}
-/**
- * TTL applied to a stream after each event. The design doc names 60s; this
- * constant centralizes it so both adapters + tests agree.
- */
-declare const GLASSBOX_STREAM_TTL_MS = 60000;
-
 /**
  * subscribe(traceId) — public Glass-Box subscription export.
  *
@@ -156,4 +39,4 @@ declare const GLASSBOX_STREAM_TTL_MS = 60000;
  */
 declare function subscribe(traceId: string): ReadableStream<GlassboxEvent>;
 
-export { type AdvisoryFiredData, type CompileDoneData, type CompileStartData, type ExecuteAttemptData, type ExecuteSuccessData, type FallbackWalkedData, GLASSBOX_STREAM_TTL_MS, type GlassboxEvent, type GlassboxEventKind, type GlassboxPubSub, subscribe };
+export { GlassboxEvent, subscribe };

package/dist/glassbox/index.mjs

@@ -1,19 +1,9 @@
 import {
-  GLASSBOX_STREAM_TTL_MS,
-  getPubSub
+  subscribe
+} from "../chunk-VZGMWKRT.mjs";
+import {
+  GLASSBOX_STREAM_TTL_MS
 } from "../chunk-NUTC7NUC.mjs";
-
-// src/glassbox/subscribe.ts
-function subscribe(traceId) {
-  if (!traceId) {
-    return new ReadableStream({
-      start(controller) {
-        controller.close();
-      }
-    });
-  }
-  return getPubSub().subscribe(traceId);
-}
 export {
   GLASSBOX_STREAM_TTL_MS,
   subscribe

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

@@ -0,0 +1,73 @@
+import { G as GlassboxEvent } from '../types-DWF6mPGg.mjs';
+import '../ir-C3P4gDt0.mjs';
+import '../dialect.mjs';
+
+/**
+ * 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!,
+ *     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). */
+    brainJwt: 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 live-stream subscriber. Production code
+     * resolves to the alpha.17 `subscribe()` export; tests inject a fake
+     * source ReadableStream<GlassboxEvent>.
+     */
+    subscribe?: (traceId: 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 { type GlassboxRoutes, type GlassboxRoutesConfig, createGlassboxRoutes };

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

@@ -0,0 +1,73 @@
+import { G as GlassboxEvent } from '../types-xeklorHU.js';
+import '../ir-CFHU3BUT.js';
+import '../dialect.js';
+
+/**
+ * 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!,
+ *     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). */
+    brainJwt: 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 live-stream subscriber. Production code
+     * resolves to the alpha.17 `subscribe()` export; tests inject a fake
+     * source ReadableStream<GlassboxEvent>.
+     */
+    subscribe?: (traceId: 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 { type GlassboxRoutes, type GlassboxRoutesConfig, createGlassboxRoutes };