gavio 0.2.0 → 0.3.0

package/dist/cjs/gateway.js

@@ -40,6 +40,7 @@ const errors_js_1 = require("./errors.js");
 const index_js_1 = require("./interceptors/audit/index.js");
 const base_js_1 = require("./interceptors/base.js");
 const chain_js_1 = require("./interceptors/chain.js");
+const stream_buffer_js_1 = require("./interceptors/reliability/stream-buffer.js");
 const pricing_js_1 = require("./pricing.js");
 const index_js_2 = require("./providers/index.js");
 const mock_js_1 = require("./providers/mock.js");
@@ -110,6 +111,7 @@ class Gateway {
             sessionId: opts.sessionId ?? null,
             options: opts.options ?? {},
             metadata: opts.metadata ?? {},
+            lineage: opts.lineage ?? null,
         });
         const ctx = new context_js_1.InterceptorContext({
             traceId: request.traceId,
@@ -121,6 +123,50 @@ class Gateway {
         const { chain, executor } = this.buildPipeline(adapter, ctx);
         return chain.execute(request, ctx, executor);
     }
+    /**
+     * Stream a completion, buffering the provider stream (F-REL-06).
+     *
+     * The provider stream is buffered in full so the post-interceptor pipeline
+     * (guardrails, PII restore, audit) runs on the complete response before any
+     * chunk reaches the caller. Pre/post interceptors run via the chain; executor
+     * policies (retry, circuit breaker, cache) are not applied to the streaming
+     * path.
+     */
+    async *stream(opts) {
+        const adapter = this.resolveAdapter();
+        if (adapter.stream === undefined || adapter.buildStreamResponse === undefined) {
+            throw new errors_js_1.ConfigurationError(`${adapter.providerName} does not support streaming`);
+        }
+        const model = opts.model ?? this.modelHint ?? this.resolveModel(adapter);
+        const request = new request_js_1.GavioRequest({
+            messages: opts.messages,
+            model,
+            provider: (0, types_js_1.coerceProvider)(adapter.providerName),
+            agentId: opts.agentId ?? null,
+            parentTraceId: opts.parentTraceId ?? null,
+            sessionId: opts.sessionId ?? null,
+            options: opts.options ?? {},
+            metadata: opts.metadata ?? {},
+        });
+        const ctx = new context_js_1.InterceptorContext({
+            traceId: request.traceId,
+            agentId: request.agentId,
+            parentTraceId: request.parentTraceId,
+            sessionId: request.sessionId,
+            dryRun: this.dryRunMode,
+        });
+        const startedAt = performance.now();
+        const buffer = new stream_buffer_js_1.StreamBuffer();
+        const { chain } = this.buildPipeline(adapter, ctx);
+        const bufferingExecutor = async (req) => {
+            for await (const chunk of adapter.stream(req))
+                buffer.append(chunk);
+            return adapter.buildStreamResponse(req, buffer.text(), startedAt);
+        };
+        const response = await chain.execute(request, ctx, bufferingExecutor);
+        // Post-interceptors have run on the fully buffered response; emit it now.
+        yield response.content;
+    }
     async healthCheck() {
         return this.resolveAdapter().healthCheck();
     }

package/dist/cjs/index.js

@@ -9,8 +9,8 @@
  * See https://gavio.io for documentation. MIT licensed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GuardrailViolationError = exports.BudgetExceededError = exports.PiiBlockedError = exports.TimeoutError = exports.ServerError = exports.RateLimitError = exports.ProviderUnavailableError = exports.ProviderError = exports.ConfigurationError = exports.GavioError = exports.InterceptorChain = exports.coerceProvider = exports.TokenUsage = exports.GuardrailOutcome = exports.Sensitivity = exports.PiiMode = exports.CacheType = exports.Provider = exports.estimateTokens = exports.PricingProvider = exports.newTraceId = exports.uuid7 = exports.InterceptorContext = exports.GavioResponse = exports.GavioRequest = exports.Gateway = exports.VERSION = void 0;
-exports.VERSION = '0.1.0';
+exports.GuardrailViolationError = exports.BudgetExceededError = exports.PiiBlockedError = exports.TimeoutError = exports.ServerError = exports.RateLimitError = exports.ProviderUnavailableError = exports.ProviderError = exports.ConfigurationError = exports.GavioError = exports.InterceptorChain = exports.coerceProvider = exports.RagChunk = exports.PromptLineage = exports.TokenUsage = exports.GuardrailOutcome = exports.Sensitivity = exports.PiiMode = exports.CacheType = exports.Provider = exports.estimateTokens = exports.PricingProvider = exports.newTraceId = exports.uuid7 = exports.InterceptorContext = exports.GavioResponse = exports.GavioRequest = exports.Gateway = exports.VERSION = void 0;
+exports.VERSION = '0.3.0';
 var gateway_js_1 = require("./gateway.js");
 Object.defineProperty(exports, "Gateway", { enumerable: true, get: function () { return gateway_js_1.Gateway; } });
 var request_js_1 = require("./request.js");
@@ -32,6 +32,8 @@ Object.defineProperty(exports, "PiiMode", { enumerable: true, get: function () {
 Object.defineProperty(exports, "Sensitivity", { enumerable: true, get: function () { return types_js_1.Sensitivity; } });
 Object.defineProperty(exports, "GuardrailOutcome", { enumerable: true, get: function () { return types_js_1.GuardrailOutcome; } });
 Object.defineProperty(exports, "TokenUsage", { enumerable: true, get: function () { return types_js_1.TokenUsage; } });
+Object.defineProperty(exports, "PromptLineage", { enumerable: true, get: function () { return types_js_1.PromptLineage; } });
+Object.defineProperty(exports, "RagChunk", { enumerable: true, get: function () { return types_js_1.RagChunk; } });
 Object.defineProperty(exports, "coerceProvider", { enumerable: true, get: function () { return types_js_1.coerceProvider; } });
 var chain_js_1 = require("./interceptors/chain.js");
 Object.defineProperty(exports, "InterceptorChain", { enumerable: true, get: function () { return chain_js_1.InterceptorChain; } });

package/dist/cjs/interceptors/audit/interceptor.js

@@ -7,6 +7,7 @@ exports.isAuditInterceptor = isAuditInterceptor;
 const record_js_1 = require("./record.js");
 const stdout_js_1 = require("./sinks/stdout.js");
 const PROMPT_HASH_KEY = 'audit_prompt_hash';
+const LINEAGE_KEY = 'audit_lineage';
 exports.AUDIT_NAME = 'audit';
 /**
  * Build an AuditRecord per request and write it to a sink.
@@ -28,6 +29,8 @@ class AuditInterceptor {
     }
     async before(request, ctx) {
         ctx.state[PROMPT_HASH_KEY] = record_js_1.AuditRecord.hashText(request.promptText());
+        if (request.lineage != null)
+            ctx.state[LINEAGE_KEY] = request.lineage;
         return request;
     }
     async after(response, ctx) {
@@ -52,6 +55,7 @@ class AuditInterceptor {
             cacheType: response.cacheType,
             guardrailOutcome: ctx.guardrailOutcome,
             riskScore: ctx.riskScore,
+            lineage: ctx.state[LINEAGE_KEY] ?? null,
         });
         if (this.hashChain) {
             record.previousHash = this.lastHash;

package/dist/cjs/interceptors/audit/record.js

@@ -8,6 +8,18 @@ exports.SCHEMA_VERSION = '1.0';
 function sha256(text) {
     return (0, node_crypto_1.createHash)('sha256').update(text, 'utf-8').digest('hex');
 }
+/** Deterministic JSON with keys sorted at every nesting level. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const parts = Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${parts.join(',')}}`;
+}
 /**
  * One append-only audit entry. Carries metadata only — never raw content.
  *
@@ -36,6 +48,7 @@ class AuditRecord {
     cacheType;
     guardrailOutcome;
     riskScore;
+    lineage;
     previousHash;
     schemaVersion;
     constructor(init) {
@@ -59,6 +72,7 @@ class AuditRecord {
         this.cacheType = init.cacheType ?? null;
         this.guardrailOutcome = init.guardrailOutcome ?? null;
         this.riskScore = init.riskScore ?? null;
+        this.lineage = init.lineage ?? null;
         this.previousHash = init.previousHash ?? '';
         this.schemaVersion = init.schemaVersion ?? exports.SCHEMA_VERSION;
     }
@@ -90,14 +104,14 @@ class AuditRecord {
             cacheType: this.cacheType,
             guardrailOutcome: this.guardrailOutcome,
             riskScore: this.riskScore,
+            lineage: this.lineage ? this.lineage.toJSON() : null,
             previousHash: this.previousHash,
             schemaVersion: this.schemaVersion,
         };
     }
-    /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+    /** Stable JSON with recursively sorted keys — used for the v0.2.0 hash chain. */
     toCanonicalJson() {
-        const data = this.toJSON();
-        return JSON.stringify(data, Object.keys(data).sort());
+        return stableStringify(this.toJSON());
     }
     /** Hash of this record's content — used to build the v0.2.0 chain. */
     contentHash() {

package/dist/cjs/interceptors/metrics/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/** Prometheus metrics (F-OBS-08). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METRICS_NAME = exports.metricsInterceptor = exports.PrometheusMetrics = void 0;
+var registry_js_1 = require("./registry.js");
+Object.defineProperty(exports, "PrometheusMetrics", { enumerable: true, get: function () { return registry_js_1.PrometheusMetrics; } });
+var interceptor_js_1 = require("./interceptor.js");
+Object.defineProperty(exports, "metricsInterceptor", { enumerable: true, get: function () { return interceptor_js_1.metricsInterceptor; } });
+Object.defineProperty(exports, "METRICS_NAME", { enumerable: true, get: function () { return interceptor_js_1.METRICS_NAME; } });

package/dist/cjs/interceptors/metrics/interceptor.js

@@ -0,0 +1,37 @@
+"use strict";
+/** metricsInterceptor (F-OBS-08) — records Prometheus metrics per request. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METRICS_NAME = void 0;
+exports.metricsInterceptor = metricsInterceptor;
+const registry_js_1 = require("./registry.js");
+exports.METRICS_NAME = 'metrics';
+/**
+ * Build a metrics interceptor. Pass a shared {@link PrometheusMetrics} registry
+ * (or let it create one) and scrape it via `.metrics.render()`:
+ *
+ * ```ts
+ * const m = metricsInterceptor()
+ * const gw = new Gateway({ devMode: true }).use(m)
+ * // ...
+ * console.log(m.metrics.render())
+ * ```
+ *
+ * Observation-only, so it always runs (including in dry-run).
+ */
+function metricsInterceptor(metrics = new registry_js_1.PrometheusMetrics()) {
+    return {
+        name: exports.METRICS_NAME,
+        dryRunSafe: true,
+        metrics,
+        async after(response, _ctx) {
+            metrics.record(response.provider, response.model, {
+                promptTokens: response.usage.promptTokens,
+                completionTokens: response.usage.completionTokens,
+                costUsd: response.costUsd,
+                latencyMs: response.latencyMs,
+                cacheHit: response.cacheHit,
+            });
+            return response;
+        },
+    };
+}

package/dist/cjs/interceptors/quality/index.js

@@ -0,0 +1,7 @@
+"use strict";
+/** Quality & compliance interceptors (F-QUA-06 risk scoring; F-QUA-03/04 to come). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.riskScorer = exports.RiskScorer = void 0;
+var risk_js_1 = require("./risk.js");
+Object.defineProperty(exports, "RiskScorer", { enumerable: true, get: function () { return risk_js_1.RiskScorer; } });
+Object.defineProperty(exports, "riskScorer", { enumerable: true, get: function () { return risk_js_1.riskScorer; } });

package/dist/cjs/interceptors/quality/risk.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * RiskScorer (F-QUA-06) — a composite risk score from per-request signals.
+ *
+ * Folds the signals other interceptors leave on the {@link InterceptorContext}
+ * — PII entities found, guardrail outcome, and the prompt-injection risk — into
+ * a single score in `[0, 1]` written to `ctx.riskScore` (and thus the audit
+ * record). Register it *inside* the audit interceptor so audit sees the composite.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RiskScorer = void 0;
+exports.riskScorer = riskScorer;
+// Guardrail outcome → its contribution before weighting.
+const GUARDRAIL_SIGNAL = { FAIL: 1.0, HITL: 0.6 };
+class RiskScorer {
+    name = 'risk_scorer';
+    dryRunSafe = true;
+    pii;
+    guardrail;
+    injection;
+    piiSaturation;
+    constructor(weights = {}) {
+        this.pii = weights.pii ?? 0.3;
+        this.guardrail = weights.guardrail ?? 0.4;
+        this.injection = weights.injection ?? 0.3;
+        this.piiSaturation = weights.piiSaturation ?? 4;
+    }
+    /** Compute the composite risk score from the three raw signals. */
+    score(piiCount, guardrailOutcome, injectionScore) {
+        let piiSignal = 0;
+        if (piiCount > 0) {
+            piiSignal = this.piiSaturation <= 0 ? 1 : Math.min(1, piiCount / this.piiSaturation);
+        }
+        const guardrailSignal = GUARDRAIL_SIGNAL[guardrailOutcome ?? ''] ?? 0;
+        const injectionSignal = injectionScore ?? 0;
+        const composite = this.pii * piiSignal + this.guardrail * guardrailSignal + this.injection * injectionSignal;
+        return Math.max(0, Math.min(1, composite));
+    }
+    async after(response, ctx) {
+        const piiCount = Object.values(ctx.piiEntityCounts).reduce((a, b) => a + b, 0);
+        ctx.riskScore = this.score(piiCount, ctx.guardrailOutcome, ctx.riskScore);
+        return response;
+    }
+}
+exports.RiskScorer = RiskScorer;
+/** Build a risk scorer. */
+function riskScorer(weights = {}) {
+    return new RiskScorer(weights);
+}

package/dist/cjs/interceptors/reliability/index.js

@@ -1,7 +1,7 @@
 "use strict";
 /** Reliability policies (F-REL-01, F-REL-02, F-REL-07). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadBalancer = exports.CircuitState = exports.circuitBreaker = exports.fallbackChain = exports.timeout = exports.timeoutPolicy = exports.retryInterceptor = void 0;
+exports.StreamBuffer = exports.loadBalancer = exports.CircuitState = exports.circuitBreaker = exports.fallbackChain = exports.timeout = exports.timeoutPolicy = exports.retryInterceptor = void 0;
 var retry_js_1 = require("./retry.js");
 Object.defineProperty(exports, "retryInterceptor", { enumerable: true, get: function () { return retry_js_1.retryInterceptor; } });
 var timeout_js_1 = require("./timeout.js");
@@ -14,3 +14,5 @@ Object.defineProperty(exports, "circuitBreaker", { enumerable: true, get: functi
 Object.defineProperty(exports, "CircuitState", { enumerable: true, get: function () { return circuit_breaker_js_1.CircuitState; } });
 var load_balancer_js_1 = require("./load-balancer.js");
 Object.defineProperty(exports, "loadBalancer", { enumerable: true, get: function () { return load_balancer_js_1.loadBalancer; } });
+var stream_buffer_js_1 = require("./stream-buffer.js");
+Object.defineProperty(exports, "StreamBuffer", { enumerable: true, get: function () { return stream_buffer_js_1.StreamBuffer; } });

package/dist/cjs/interceptors/reliability/stream-buffer.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamBuffer = void 0;
+/**
+ * StreamBuffer (F-REL-06) — accumulate a provider stream for post-interceptors.
+ *
+ * Post-interceptors (guardrails, PII restore, audit) need the *complete*
+ * response, so a streamed reply is buffered in full before the post pipeline
+ * runs and before any chunk reaches the caller. This trades first-token latency
+ * for the guarantee that every interceptor sees — and can rewrite or block — the
+ * whole response.
+ */
+class StreamBuffer {
+    parts = [];
+    /** Add one streamed chunk. */
+    append(chunk) {
+        this.parts.push(chunk);
+    }
+    /** The full buffered response so far. */
+    text() {
+        return this.parts.join('');
+    }
+    /** Total buffered length in characters. */
+    get length() {
+        return this.parts.reduce((n, p) => n + p.length, 0);
+    }
+}
+exports.StreamBuffer = StreamBuffer;

package/dist/cjs/providers/base.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseProviderAdapter = void 0;
 const pricing_js_1 = require("../pricing.js");
 const response_js_1 = require("../response.js");
+const types_js_1 = require("../types.js");
 /** Base class with a shared pricing provider and response builder. */
 class BaseProviderAdapter {
     pricing;
@@ -13,6 +14,14 @@ class BaseProviderAdapter {
     get reportedModelVersion() {
         return null;
     }
+    /**
+     * Build a response from a fully buffered stream (F-REL-06). Streamed chunks
+     * carry text only, so token usage is estimated from prompt + content.
+     */
+    buildStreamResponse(request, content, startedAt) {
+        const usage = new types_js_1.TokenUsage((0, pricing_js_1.estimateTokens)(request.promptText()), (0, pricing_js_1.estimateTokens)(content));
+        return this.buildResponse(request, content, usage, this.reportedModelVersion ?? request.model, startedAt);
+    }
     buildResponse(request, content, usage, modelVersion, startedAt) {
         const latencyMs = Math.floor(performance.now() - startedAt);
         return new response_js_1.GavioResponse({

package/dist/cjs/request.js

@@ -19,6 +19,7 @@ class GavioRequest {
     sessionId;
     options;
     metadata;
+    lineage;
     constructor(init) {
         this.messages = init.messages;
         this.model = init.model;
@@ -29,6 +30,7 @@ class GavioRequest {
         this.sessionId = init.sessionId ?? null;
         this.options = init.options ?? {};
         this.metadata = init.metadata ?? {};
+        this.lineage = init.lineage != null ? types_js_1.PromptLineage.from(init.lineage) : null;
     }
     get temperature() {
         const t = this.options['temperature'];
@@ -54,6 +56,7 @@ class GavioRequest {
             sessionId: this.sessionId,
             options: { ...this.options },
             metadata: { ...this.metadata },
+            lineage: this.lineage,
         });
     }
 }

package/dist/cjs/types.js

@@ -1,7 +1,7 @@
 "use strict";
 /** Shared enums (as string unions / const objects) and utility types. */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TokenUsage = exports.GuardrailOutcome = exports.Sensitivity = exports.PiiMode = exports.CacheType = exports.Provider = void 0;
+exports.PromptLineage = exports.RagChunk = exports.TokenUsage = exports.GuardrailOutcome = exports.Sensitivity = exports.PiiMode = exports.CacheType = exports.Provider = void 0;
 exports.coerceProvider = coerceProvider;
 /** Supported LLM providers. String-valued for easy config + logging. */
 exports.Provider = {
@@ -59,3 +59,55 @@ class TokenUsage {
     }
 }
 exports.TokenUsage = TokenUsage;
+/**
+ * A single retrieved source that contributed to a prompt. Carries a *reference*
+ * to the source — never the retrieved text — so prompt lineage stays within the
+ * audit record's metadata-only contract.
+ */
+class RagChunk {
+    source;
+    chunkId;
+    score;
+    constructor(init) {
+        this.source = init.source;
+        this.chunkId = init.chunkId ?? null;
+        this.score = init.score ?? null;
+    }
+    toJSON() {
+        return { source: this.source, chunkId: this.chunkId, score: this.score };
+    }
+}
+exports.RagChunk = RagChunk;
+/**
+ * Provenance for a rendered prompt (F-OBS-04): the template, the variable
+ * bindings interpolated into it, and the RAG chunk sources retrieved for it.
+ *
+ * Attached to a GavioRequest by the caller and copied into the AuditRecord so
+ * any prompt can be reconstructed and debugged. RAG chunk text is never stored
+ * — only source references (see {@link RagChunk}).
+ */
+class PromptLineage {
+    templateId;
+    templateVersion;
+    variables;
+    ragChunks;
+    constructor(init = {}) {
+        this.templateId = init.templateId ?? null;
+        this.templateVersion = init.templateVersion ?? null;
+        this.variables = init.variables ?? {};
+        this.ragChunks = (init.ragChunks ?? []).map((c) => c instanceof RagChunk ? c : new RagChunk(c));
+    }
+    /** Coerce a PromptLineage instance or plain init object into a PromptLineage. */
+    static from(value) {
+        return value instanceof PromptLineage ? value : new PromptLineage(value);
+    }
+    toJSON() {
+        return {
+            templateId: this.templateId,
+            templateVersion: this.templateVersion,
+            variables: this.variables,
+            ragChunks: this.ragChunks.map((c) => c.toJSON()),
+        };
+    }
+}
+exports.PromptLineage = PromptLineage;

package/dist/esm/gateway.d.ts

@@ -4,7 +4,7 @@ import { PricingProvider } from './pricing.js';
 import type { ProviderAdapter } from './providers/base.js';
 import type { GavioResponse } from './response.js';
 import { Provider } from './types.js';
-import type { Message } from './types.js';
+import type { Message, PromptLineage, PromptLineageInit } from './types.js';
 export interface GatewayOptions {
     provider?: Provider | string;
     model?: string;
@@ -22,6 +22,8 @@ export interface CompleteOptions {
     metadata?: Record<string, unknown>;
     /** Provider sampling options (temperature, maxTokens, etc.). */
     options?: Record<string, unknown>;
+    /** Prompt provenance (F-OBS-04): template, variables, and RAG chunk sources. */
+    lineage?: PromptLineage | PromptLineageInit | null;
 }
 /**
  * Routes a request through the interceptor pipeline to a provider.
@@ -51,6 +53,16 @@ export declare class Gateway {
     get model(): string;
     get providerName(): string;
     complete(opts: CompleteOptions): Promise<GavioResponse>;
+    /**
+     * Stream a completion, buffering the provider stream (F-REL-06).
+     *
+     * The provider stream is buffered in full so the post-interceptor pipeline
+     * (guardrails, PII restore, audit) runs on the complete response before any
+     * chunk reaches the caller. Pre/post interceptors run via the chain; executor
+     * policies (retry, circuit breaker, cache) are not applied to the streaming
+     * path.
+     */
+    stream(opts: CompleteOptions): AsyncGenerator<string>;
     healthCheck(): Promise<boolean>;
     private buildPipeline;
     private wrapPolicy;

package/dist/esm/gateway.js

@@ -4,6 +4,7 @@ import { ConfigurationError } from './errors.js';
 import { auditInterceptor, isAuditInterceptor } from './interceptors/audit/index.js';
 import { isExecutorPolicy } from './interceptors/base.js';
 import { InterceptorChain } from './interceptors/chain.js';
+import { StreamBuffer } from './interceptors/reliability/stream-buffer.js';
 import { PricingProvider } from './pricing.js';
 import { buildAdapter } from './providers/index.js';
 import { mockProvider } from './providers/mock.js';
@@ -74,6 +75,7 @@ export class Gateway {
             sessionId: opts.sessionId ?? null,
             options: opts.options ?? {},
             metadata: opts.metadata ?? {},
+            lineage: opts.lineage ?? null,
         });
         const ctx = new InterceptorContext({
             traceId: request.traceId,
@@ -85,6 +87,50 @@ export class Gateway {
         const { chain, executor } = this.buildPipeline(adapter, ctx);
         return chain.execute(request, ctx, executor);
     }
+    /**
+     * Stream a completion, buffering the provider stream (F-REL-06).
+     *
+     * The provider stream is buffered in full so the post-interceptor pipeline
+     * (guardrails, PII restore, audit) runs on the complete response before any
+     * chunk reaches the caller. Pre/post interceptors run via the chain; executor
+     * policies (retry, circuit breaker, cache) are not applied to the streaming
+     * path.
+     */
+    async *stream(opts) {
+        const adapter = this.resolveAdapter();
+        if (adapter.stream === undefined || adapter.buildStreamResponse === undefined) {
+            throw new ConfigurationError(`${adapter.providerName} does not support streaming`);
+        }
+        const model = opts.model ?? this.modelHint ?? this.resolveModel(adapter);
+        const request = new GavioRequest({
+            messages: opts.messages,
+            model,
+            provider: coerceProvider(adapter.providerName),
+            agentId: opts.agentId ?? null,
+            parentTraceId: opts.parentTraceId ?? null,
+            sessionId: opts.sessionId ?? null,
+            options: opts.options ?? {},
+            metadata: opts.metadata ?? {},
+        });
+        const ctx = new InterceptorContext({
+            traceId: request.traceId,
+            agentId: request.agentId,
+            parentTraceId: request.parentTraceId,
+            sessionId: request.sessionId,
+            dryRun: this.dryRunMode,
+        });
+        const startedAt = performance.now();
+        const buffer = new StreamBuffer();
+        const { chain } = this.buildPipeline(adapter, ctx);
+        const bufferingExecutor = async (req) => {
+            for await (const chunk of adapter.stream(req))
+                buffer.append(chunk);
+            return adapter.buildStreamResponse(req, buffer.text(), startedAt);
+        };
+        const response = await chain.execute(request, ctx, bufferingExecutor);
+        // Post-interceptors have run on the fully buffered response; emit it now.
+        yield response.content;
+    }
     async healthCheck() {
         return this.resolveAdapter().healthCheck();
     }

package/dist/esm/index.d.ts

@@ -7,7 +7,7 @@
  *
  * See https://gavio.io for documentation. MIT licensed.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.3.0";
 export { Gateway } from './gateway.js';
 export type { GatewayOptions, CompleteOptions } from './gateway.js';
 export { GavioRequest } from './request.js';
@@ -18,8 +18,8 @@ export { InterceptorContext } from './context.js';
 export type { InterceptorContextInit } from './context.js';
 export { uuid7, newTraceId } from './ids.js';
 export { PricingProvider, estimateTokens } from './pricing.js';
-export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, coerceProvider, } from './types.js';
-export type { Message } from './types.js';
+export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, PromptLineage, RagChunk, coerceProvider, } from './types.js';
+export type { Message, PromptLineageInit, RagChunkInit } from './types.js';
 export type { Interceptor, Executor, ExecutorPolicy } from './interceptors/base.js';
 export { InterceptorChain } from './interceptors/chain.js';
 export { GavioError, ConfigurationError, ProviderError, ProviderUnavailableError, RateLimitError, ServerError, TimeoutError, PiiBlockedError, BudgetExceededError, GuardrailViolationError, } from './errors.js';

package/dist/esm/index.js

@@ -7,14 +7,14 @@
  *
  * See https://gavio.io for documentation. MIT licensed.
  */
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 export { Gateway } from './gateway.js';
 export { GavioRequest } from './request.js';
 export { GavioResponse } from './response.js';
 export { InterceptorContext } from './context.js';
 export { uuid7, newTraceId } from './ids.js';
 export { PricingProvider, estimateTokens } from './pricing.js';
-export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, coerceProvider, } from './types.js';
+export { Provider, CacheType, PiiMode, Sensitivity, GuardrailOutcome, TokenUsage, PromptLineage, RagChunk, coerceProvider, } from './types.js';
 export { InterceptorChain } from './interceptors/chain.js';
 // errors
 export { GavioError, ConfigurationError, ProviderError, ProviderUnavailableError, RateLimitError, ServerError, TimeoutError, PiiBlockedError, BudgetExceededError, GuardrailViolationError, } from './errors.js';

package/dist/esm/interceptors/audit/interceptor.js

@@ -2,6 +2,7 @@
 import { AuditRecord } from './record.js';
 import { stdoutSink } from './sinks/stdout.js';
 const PROMPT_HASH_KEY = 'audit_prompt_hash';
+const LINEAGE_KEY = 'audit_lineage';
 export const AUDIT_NAME = 'audit';
 /**
  * Build an AuditRecord per request and write it to a sink.
@@ -23,6 +24,8 @@ class AuditInterceptor {
     }
     async before(request, ctx) {
         ctx.state[PROMPT_HASH_KEY] = AuditRecord.hashText(request.promptText());
+        if (request.lineage != null)
+            ctx.state[LINEAGE_KEY] = request.lineage;
         return request;
     }
     async after(response, ctx) {
@@ -47,6 +50,7 @@ class AuditInterceptor {
             cacheType: response.cacheType,
             guardrailOutcome: ctx.guardrailOutcome,
             riskScore: ctx.riskScore,
+            lineage: ctx.state[LINEAGE_KEY] ?? null,
         });
         if (this.hashChain) {
             record.previousHash = this.lastHash;

package/dist/esm/interceptors/audit/record.d.ts

@@ -1,5 +1,5 @@
 /** AuditRecord — the immutable, per-request audit entry. */
-import { TokenUsage } from '../../types.js';
+import { PromptLineage, TokenUsage } from '../../types.js';
 export declare const SCHEMA_VERSION = "1.0";
 export interface AuditRecordInit {
     traceId: string;
@@ -22,6 +22,7 @@ export interface AuditRecordInit {
     cacheType?: string | null;
     guardrailOutcome?: string | null;
     riskScore?: number | null;
+    lineage?: PromptLineage | null;
     previousHash?: string;
     schemaVersion?: string;
 }
@@ -53,13 +54,14 @@ export declare class AuditRecord {
     cacheType: string | null;
     guardrailOutcome: string | null;
     riskScore: number | null;
+    lineage: PromptLineage | null;
     previousHash: string;
     schemaVersion: string;
     constructor(init: AuditRecordInit);
     static nowUtc(): string;
     static hashText(text: string): string;
     toJSON(): Record<string, unknown>;
-    /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+    /** Stable JSON with recursively sorted keys — used for the v0.2.0 hash chain. */
     toCanonicalJson(): string;
     /** Hash of this record's content — used to build the v0.2.0 chain. */
     contentHash(): string;