gavio 0.1.0 → 0.3.0

package/dist/cjs/config.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Config loader (F-DX-05) — build a Gateway from an object or a JSON file.
+ *
+ *   const gw = await Gateway.fromConfig('gateway.json')
+ *
+ * JSON is supported out of the box; string values expand ${ENV_VAR}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.buildFromConfig = buildFromConfig;
+const node_fs_1 = require("node:fs");
+const errors_js_1 = require("./errors.js");
+const gateway_js_1 = require("./gateway.js");
+const index_js_1 = require("./interceptors/audit/index.js");
+const index_js_2 = require("./interceptors/cache/index.js");
+const index_js_3 = require("./interceptors/governance/index.js");
+const injection_js_1 = require("./interceptors/injection.js");
+const index_js_4 = require("./interceptors/pii/index.js");
+const index_js_5 = require("./interceptors/reliability/index.js");
+function loadConfig(path) {
+    const text = (0, node_fs_1.readFileSync)(path, 'utf8');
+    if (!path.endsWith('.json')) {
+        throw new errors_js_1.ConfigurationError('JS config loader supports JSON only (use .json)');
+    }
+    return expand(JSON.parse(text));
+}
+function expand(obj) {
+    if (Array.isArray(obj))
+        return obj.map(expand);
+    if (obj && typeof obj === 'object') {
+        return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expand(v)]));
+    }
+    if (typeof obj === 'string') {
+        return obj.replace(/\$\{(\w+)\}/g, (_, v) => process.env[v] ?? '');
+    }
+    return obj;
+}
+function buildFromConfig(config) {
+    const gatewayOptions = {};
+    if (config['provider'])
+        gatewayOptions['provider'] = config['provider'];
+    if (config['model'])
+        gatewayOptions['model'] = config['model'];
+    if (config['devMode'] ?? config['dev_mode'])
+        gatewayOptions['devMode'] = true;
+    if (config['dryRun'] ?? config['dry_run'])
+        gatewayOptions['dryRun'] = true;
+    let gw = new gateway_js_1.Gateway(gatewayOptions);
+    const ic = config['interceptors'] ?? {};
+    const cfg = (name) => {
+        const entry = ic[name];
+        return entry && entry['enabled'] !== false ? entry : null;
+    };
+    let c;
+    if ((c = cfg('audit'))) {
+        gw = gw.use((0, index_js_1.auditInterceptor)({
+            sink: c['sink'] ?? 'stdout',
+            hashChain: Boolean(c['hashChain'] ?? c['hash_chain']),
+        }));
+    }
+    if ((c = cfg('prompt_injection'))) {
+        gw = gw.use((0, injection_js_1.promptInjectionGuard)({ action: c['action'] ?? 'block' }));
+    }
+    if ((c = cfg('pii_guard'))) {
+        gw = gw.use((0, index_js_4.piiGuard)({
+            sensitivity: c['sensitivity'] ?? 'strict',
+            mode: c['mode'] ?? 'redact',
+        }));
+    }
+    if ((c = cfg('cost_control'))) {
+        gw = gw.use((0, index_js_3.costControl)({
+            hardCapUsd: Number(c['hardCapUsd'] ?? c['hard_cap_usd']),
+            softCapUsd: (c['softCapUsd'] ?? c['soft_cap_usd']),
+            scope: c['scope'] ?? 'global',
+            window: c['window'] ?? 'day',
+        }));
+    }
+    if ((c = cfg('rate_limiter'))) {
+        gw = gw.use((0, index_js_3.rateLimiter)({
+            maxRequestsPerMinute: (c['maxRequestsPerMinute'] ?? c['max_requests_per_minute']),
+            maxTokensPerMinute: (c['maxTokensPerMinute'] ?? c['max_tokens_per_minute']),
+            scope: c['scope'] ?? 'global',
+        }));
+    }
+    if ((c = cfg('model_policy'))) {
+        gw = gw.use((0, index_js_3.modelPolicy)({ roles: c['roles'] ?? {} }));
+    }
+    if ((c = cfg('semantic_cache'))) {
+        const embedder = (c['enableSemantic'] ?? c['enable_semantic']) ? (0, index_js_2.hashingEmbedder)() : undefined;
+        gw = gw.use((0, index_js_2.semanticCache)({
+            embedder,
+            similarityThreshold: Number(c['similarityThreshold'] ?? c['similarity_threshold'] ?? 0.95),
+        }));
+    }
+    if ((c = cfg('timeout'))) {
+        gw = gw.use((0, index_js_5.timeoutPolicy)({ timeoutSeconds: Number(c['timeoutSeconds'] ?? c['timeout_seconds'] ?? 30) }));
+    }
+    if ((c = cfg('retry'))) {
+        gw = gw.use((0, index_js_5.retryInterceptor)({
+            maxAttempts: Number(c['maxAttempts'] ?? c['max_attempts'] ?? 3),
+            baseDelayMs: Number(c['baseDelayMs'] ?? c['base_delay_ms'] ?? 500),
+        }));
+    }
+    return gw;
+}

package/dist/cjs/errors.js

@@ -4,7 +4,7 @@
  * callers can catch the whole family with a single check.
  */
 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 = void 0;
+exports.PromptInjectionError = exports.GuardrailViolationError = exports.ModelNotAllowedError = exports.RateLimitExceededError = exports.CircuitOpenError = exports.BudgetExceededError = exports.PiiBlockedError = exports.TimeoutError = exports.ServerError = exports.RateLimitError = exports.ProviderUnavailableError = exports.ProviderError = exports.ConfigurationError = exports.GavioError = void 0;
 class GavioError extends Error {
     constructor(message) {
         super(message);
@@ -51,7 +51,35 @@ exports.PiiBlockedError = PiiBlockedError;
 class BudgetExceededError extends GavioError {
 }
 exports.BudgetExceededError = BudgetExceededError;
+/** The circuit breaker is open; the call was rejected without hitting the provider. */
+class CircuitOpenError extends ProviderUnavailableError {
+}
+exports.CircuitOpenError = CircuitOpenError;
+/** A local rate limit (requests/tokens per minute) was exceeded. */
+class RateLimitExceededError extends GavioError {
+}
+exports.RateLimitExceededError = RateLimitExceededError;
+/** The caller's role is not permitted to use the requested model (RBAC). */
+class ModelNotAllowedError extends GavioError {
+    role;
+    model;
+    constructor(role, model) {
+        super(`role ${JSON.stringify(role)} may not use model ${JSON.stringify(model)}`);
+        this.role = role;
+        this.model = model;
+    }
+}
+exports.ModelNotAllowedError = ModelNotAllowedError;
 /** Output failed a guardrail validator with onFailure='error'. */
 class GuardrailViolationError extends GavioError {
 }
 exports.GuardrailViolationError = GuardrailViolationError;
+/** A prompt-injection attempt was detected and the guard is in block mode. */
+class PromptInjectionError extends GavioError {
+    patterns;
+    constructor(patterns) {
+        super(`prompt injection detected: ${patterns.join(', ')}`);
+        this.patterns = patterns;
+    }
+}
+exports.PromptInjectionError = PromptInjectionError;

package/dist/cjs/gateway.js

@@ -1,5 +1,38 @@
 "use strict";
 /** Gateway — the entry point. Wires interceptors around a provider adapter. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Gateway = void 0;
 const context_js_1 = require("./context.js");
@@ -7,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");
@@ -40,6 +74,15 @@ class Gateway {
         this.dryRunMode = options.dryRun ?? false;
         this.pricing = options.pricing ?? new pricing_js_1.PricingProvider();
     }
+    /**
+     * Build a Gateway from a config object or a JSON file path (F-DX-05).
+     * Async so the config module loads lazily (avoids a circular import).
+     */
+    static async fromConfig(config) {
+        const mod = await Promise.resolve().then(() => __importStar(require('./config.js')));
+        const data = typeof config === 'string' ? mod.loadConfig(config) : config;
+        return mod.buildFromConfig(data);
+    }
     /** Register an interceptor or executor policy. First-registered = outermost. */
     use(interceptor) {
         this.interceptors.push(interceptor);
@@ -68,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,
@@ -79,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/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stdoutSink = exports.SCHEMA_VERSION = exports.AuditRecord = exports.AUDIT_NAME = exports.isAuditInterceptor = exports.auditInterceptor = void 0;
+exports.buildCallGraph = exports.verifyChain = exports.stdoutSink = exports.SCHEMA_VERSION = exports.AuditRecord = exports.AUDIT_NAME = exports.isAuditInterceptor = exports.auditInterceptor = void 0;
 var interceptor_js_1 = require("./interceptor.js");
 Object.defineProperty(exports, "auditInterceptor", { enumerable: true, get: function () { return interceptor_js_1.auditInterceptor; } });
 Object.defineProperty(exports, "isAuditInterceptor", { enumerable: true, get: function () { return interceptor_js_1.isAuditInterceptor; } });
@@ -10,3 +10,6 @@ Object.defineProperty(exports, "AuditRecord", { enumerable: true, get: function
 Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return record_js_1.SCHEMA_VERSION; } });
 var stdout_js_1 = require("./sinks/stdout.js");
 Object.defineProperty(exports, "stdoutSink", { enumerable: true, get: function () { return stdout_js_1.stdoutSink; } });
+var trace_js_1 = require("./trace.js");
+Object.defineProperty(exports, "verifyChain", { enumerable: true, get: function () { return trace_js_1.verifyChain; } });
+Object.defineProperty(exports, "buildCallGraph", { enumerable: true, get: function () { return trace_js_1.buildCallGraph; } });

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.
@@ -20,11 +21,16 @@ class AuditInterceptor {
     name = exports.AUDIT_NAME;
     dryRunSafe = true; // auditing is observation-only, so it always runs
     sink;
+    hashChain;
+    lastHash = '';
     constructor(options = {}) {
         this.sink = resolveSink(options.sink);
+        this.hashChain = options.hashChain ?? false;
     }
     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) {
@@ -49,7 +55,12 @@ class AuditInterceptor {
             cacheType: response.cacheType,
             guardrailOutcome: ctx.guardrailOutcome,
             riskScore: ctx.riskScore,
+            lineage: ctx.state[LINEAGE_KEY] ?? null,
         });
+        if (this.hashChain) {
+            record.previousHash = this.lastHash;
+            this.lastHash = record.contentHash();
+        }
         response.audit = record;
         try {
             await this.sink.write(record);

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/audit/trace.js

@@ -0,0 +1,43 @@
+"use strict";
+/** Audit-chain verification (F-OBS-02) and multi-agent DAG trace (F-OBS-03). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyChain = verifyChain;
+exports.buildCallGraph = buildCallGraph;
+/**
+ * Return true if the records form an intact hash chain. Each record's
+ * previousHash must equal the content hash of the record before it; the first
+ * must be empty. Any edit, reorder, or deletion breaks the chain.
+ */
+function verifyChain(records) {
+    let prevHash = '';
+    for (const rec of records) {
+        if (rec.previousHash !== prevHash)
+            return false;
+        prevHash = rec.contentHash();
+    }
+    return true;
+}
+/**
+ * Reconstruct the multi-agent DAG from audit records using parentTraceId +
+ * traceId. Returns the root nodes (those with no known parent).
+ */
+function buildCallGraph(records) {
+    const nodes = new Map();
+    for (const rec of records) {
+        nodes.set(rec.traceId, {
+            traceId: rec.traceId,
+            agentId: rec.agentId,
+            parentTraceId: rec.parentTraceId,
+            children: [],
+        });
+    }
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.parentTraceId ? nodes.get(node.parentTraceId) : undefined;
+        if (parent)
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    return roots;
+}

package/dist/cjs/interceptors/cache/embedding.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Embeddings for the semantic cache (F-CACHE-02).
+ *
+ * Zero-dependency hashed bag-of-words embedder (L2-normalised) — good enough to
+ * dedup near-identical prompts. Plug in a real embedder implementing `Embedder`
+ * for production semantic matching.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashingEmbedder = hashingEmbedder;
+exports.cosineSimilarity = cosineSimilarity;
+const node_crypto_1 = require("node:crypto");
+const TOKEN = /[a-z0-9]+/g;
+/** Deterministic hashed bag-of-words embedder. */
+function hashingEmbedder(dim = 256) {
+    return {
+        embed(text) {
+            const vec = new Array(dim).fill(0);
+            const tokens = text.toLowerCase().match(TOKEN) ?? [];
+            for (const token of tokens) {
+                // Parity note: Python uses blake2b(digest_size=8); here we take the
+                // first 8 bytes of blake2b512. Both are deterministic; the JS cache is
+                // per-process so cross-language byte-parity is not required.
+                const digest = (0, node_crypto_1.createHash)('blake2b512').update(token).digest();
+                let n = 0n;
+                for (let i = 0; i < 8; i++)
+                    n = (n << 8n) | BigInt(digest[i]);
+                const bucket = Number(n % BigInt(dim));
+                vec[bucket] += 1;
+            }
+            const norm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0));
+            if (norm === 0)
+                return vec;
+            return vec.map((x) => x / norm);
+        },
+    };
+}
+/** Cosine similarity; safe for zero vectors. */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        throw new Error('vectors must have equal length');
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

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

@@ -1,9 +1,13 @@
 "use strict";
-/**
- * Caching substrate. The SemanticCache interceptor ships in v0.2.0; v0.1.0
- * exposes the CacheBackend interface and the in-memory backend only.
- */
+/** Caching (F-CACHE-01 exact, F-CACHE-02 semantic, F-CACHE-03 in-memory). */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryCacheBackend = void 0;
+exports.inMemoryVectorBackend = exports.cosineSimilarity = exports.hashingEmbedder = exports.semanticCache = exports.memoryCacheBackend = void 0;
 var memory_js_1 = require("./backends/memory.js");
 Object.defineProperty(exports, "memoryCacheBackend", { enumerable: true, get: function () { return memory_js_1.memoryCacheBackend; } });
+var interceptor_js_1 = require("./interceptor.js");
+Object.defineProperty(exports, "semanticCache", { enumerable: true, get: function () { return interceptor_js_1.semanticCache; } });
+var embedding_js_1 = require("./embedding.js");
+Object.defineProperty(exports, "hashingEmbedder", { enumerable: true, get: function () { return embedding_js_1.hashingEmbedder; } });
+Object.defineProperty(exports, "cosineSimilarity", { enumerable: true, get: function () { return embedding_js_1.cosineSimilarity; } });
+var vector_js_1 = require("./vector.js");
+Object.defineProperty(exports, "inMemoryVectorBackend", { enumerable: true, get: function () { return vector_js_1.inMemoryVectorBackend; } });

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

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * semanticCache (F-CACHE-01, F-CACHE-02) — two-level cache as an ExecutorPolicy.
+ *
+ * Exact SHA-256 cache, then optional semantic cosine cache; a hit returns the
+ * cached response and skips the provider. Register outermost.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticCache = semanticCache;
+const node_crypto_1 = require("node:crypto");
+const response_js_1 = require("../../response.js");
+const types_js_1 = require("../../types.js");
+const memory_js_1 = require("./backends/memory.js");
+const vector_js_1 = require("./vector.js");
+function semanticCache(options = {}) {
+    const backend = options.backend ?? (0, memory_js_1.memoryCacheBackend)();
+    const embedder = options.embedder;
+    const semantic = embedder != null;
+    const vector = options.vectorBackend ?? (semantic ? (0, vector_js_1.inMemoryVectorBackend)() : null);
+    const exactTtl = options.exactTtlSeconds ?? 3600;
+    const semanticTtl = options.semanticTtlSeconds ?? 86400;
+    const threshold = options.similarityThreshold ?? 0.95;
+    function exactKey(request) {
+        const opts = request.options ?? {};
+        const sorted = {};
+        for (const k of Object.keys(opts).sort())
+            sorted[k] = opts[k];
+        const payload = JSON.stringify({
+            provider: String(request.provider),
+            model: request.model,
+            messages: request.messages,
+            options: sorted,
+        });
+        return 'gavio:exact:' + (0, node_crypto_1.createHash)('sha256').update(payload).digest('hex');
+    }
+    function hit(request, ctx, entry, type) {
+        ctx.cacheHit = true;
+        ctx.cacheType = type;
+        return new response_js_1.GavioResponse({
+            traceId: request.traceId,
+            content: entry.content,
+            model: request.model,
+            provider: String(request.provider),
+            modelVersion: entry.modelVersion,
+            usage: new types_js_1.TokenUsage(entry.promptTokens, entry.completionTokens),
+            costUsd: 0,
+            cacheHit: true,
+            cacheType: type,
+        });
+    }
+    return {
+        name: 'semantic_cache',
+        isExecutorPolicy: true,
+        async around(request, ctx, callNext) {
+            ctx.markFired('semantic_cache');
+            const key = exactKey(request);
+            const cached = (await backend.get(key));
+            if (cached)
+                return hit(request, ctx, cached, types_js_1.CacheType.EXACT);
+            let embedding = null;
+            if (semantic && vector && embedder) {
+                embedding = embedder.embed(request.promptText());
+                const semHit = (await vector.query(embedding, threshold));
+                if (semHit)
+                    return hit(request, ctx, semHit, types_js_1.CacheType.SEMANTIC);
+            }
+            const response = await callNext(request);
+            const entry = {
+                content: response.content,
+                modelVersion: response.modelVersion,
+                promptTokens: response.usage.promptTokens,
+                completionTokens: response.usage.completionTokens,
+            };
+            await backend.set(key, entry, exactTtl);
+            if (embedding && vector)
+                await vector.add(embedding, entry, semanticTtl);
+            return response;
+        },
+    };
+}

package/dist/cjs/interceptors/cache/vector.js

@@ -0,0 +1,35 @@
+"use strict";
+/** VectorBackend — nearest-neighbour store for the semantic cache (F-CACHE-02). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inMemoryVectorBackend = inMemoryVectorBackend;
+const embedding_js_1 = require("./embedding.js");
+/** Bounded, brute-force in-memory vector store (default dev backend). */
+function inMemoryVectorBackend(maxSize = 1000) {
+    const items = [];
+    return {
+        async add(vector, value, ttlSeconds) {
+            const expiresAt = ttlSeconds ? Date.now() + ttlSeconds * 1000 : null;
+            items.push({ vector, value, expiresAt });
+            if (items.length > maxSize)
+                items.shift();
+        },
+        async query(vector, threshold) {
+            const now = Date.now();
+            let best = null;
+            let bestSim = threshold;
+            for (const item of items) {
+                if (item.expiresAt !== null && now > item.expiresAt)
+                    continue;
+                const sim = (0, embedding_js_1.cosineSimilarity)(vector, item.vector);
+                if (sim >= bestSim) {
+                    bestSim = sim;
+                    best = item.value;
+                }
+            }
+            return best;
+        },
+        async clear() {
+            items.length = 0;
+        },
+    };
+}