gavio 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# Gavio — JavaScript / TypeScript SDK
+
+> The open standard AI gateway for production systems. PII protection, audit
+> trails, reliability, and cost control as composable interceptors.
+
+`gavio` sits between your application and any LLM provider. The same request
+passes through a pre/post interceptor chain — PII redaction, retries, cost
+tracking, audit logging — before and after the provider call.
+
+Part of the [Gavio](https://gavio.io) project. MIT licensed. Written in
+TypeScript, ships full type definitions, ESM. Node.js 18+ (native `fetch`,
+`node:crypto`).
+
+## Install
+
+```bash
+npm install gavio        # zero runtime dependencies
+```
+
+## Quick start (dev mode — no API key, no network)
+
+```typescript
+import { Gateway } from 'gavio'
+import { piiGuard } from 'gavio/interceptors/pii'
+
+const gw = new Gateway({ devMode: true }).use(piiGuard())
+
+const r = await gw.complete({
+  messages: [{ role: 'user', content: 'Email jan@example.com re NL91ABNA0417164300' }],
+  agentId: 'demo',
+})
+
+console.log(r.content)               // PII restored in the reply
+console.log(`cost=$${r.costUsd.toFixed(6)} latency=${r.latencyMs}ms`)
+console.log('pii types:', r.audit.piiEntityTypes)
+```
+
+## Real providers
+
+```typescript
+import { Gateway } from 'gavio'
+import { piiGuard } from 'gavio/interceptors/pii'
+import { auditInterceptor } from 'gavio/interceptors/audit'
+import { retryInterceptor, timeoutPolicy } from 'gavio/interceptors/reliability'
+
+const gw = new Gateway({ provider: 'anthropic', model: 'claude-sonnet-4-6' }) // reads ANTHROPIC_API_KEY
+  .use(piiGuard({ sensitivity: 'strict' }))
+  .use(auditInterceptor({ sink: 'stdout' }))
+  .use(timeoutPolicy({ timeoutMs: 30_000 }))
+  .use(retryInterceptor({ maxAttempts: 3 }))
+
+const r = await gw.complete({ messages: [{ role: 'user', content: 'Hi' }] })
+```
+
+`OPENAI_API_KEY` / `provider: 'openai'` work the same way.
+
+## Sub-path imports (tree-shaking)
+
+```typescript
+import { Gateway }          from 'gavio'
+import { piiGuard }         from 'gavio/interceptors/pii'
+import { auditInterceptor } from 'gavio/interceptors/audit'
+import { retryInterceptor } from 'gavio/interceptors/reliability'
+import { anthropicAdapter } from 'gavio/providers/anthropic'
+import { GavioTestKit }     from 'gavio/testing'
+```
+
+## What ships in v0.1.0
+
+- **Core** — `Gateway` (object config + `.use()` / `.withAdapter()`),
+  `InterceptorChain` (onion pre/post model), `GavioRequest` / `GavioResponse`
+  (camelCase), monotonic UUID v7 `traceId`, `agentId` / `parentTraceId`.
+- **PII Guard (F-SEC-01)** — Email, IBAN (mod-97), BSN (11-proef),
+  CreditCard (Luhn), Phone, IP (v4/v6), SSN scanners; redact / mask / tag /
+  block; restore-on-response; overlap resolution.
+- **Secret Scanner (F-SEC-04)** — API keys, JWTs, PEM keys, DB URLs.
+- **Reliability** — `retryInterceptor` (F-REL-01), `fallbackChain` (F-REL-02),
+  `timeoutPolicy` (F-REL-07).
+- **Cost tracking (F-GOV-01)** — `costUsd` on every response.
+- **Audit (F-OBS-01)** — `AuditRecord` (SHA-256 hashes, metadata only) +
+  `stdoutSink` (F-OBS-05).
+- **Dev mode (F-DX-01)** and **dry-run mode (F-DX-02)**.
+- **Providers** — OpenAI, Anthropic (native `fetch`), Mock.
+- **Testing** — `GavioTestKit`, `mockProvider`.
+
+See the [JavaScript guide](../../docs/packages/javascript.md) and [CHANGELOG.md](../../CHANGELOG.md).
+
+## Scripts
+
+```bash
+npm run typecheck    # tsc --noEmit (strict)
+npm test             # vitest run  (59 unit tests)
+npm run smoke        # build + dev-mode end-to-end check
+npm run build        # compile to dist/
+```

package/dist/cjs/context.js

@@ -0,0 +1,47 @@
+"use strict";
+/** Per-request context passed through the interceptor pipeline. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InterceptorContext = void 0;
+/**
+ * Mutable scratch space shared by all interceptors within one request. One
+ * instance per request — never shared across requests. Interceptors stash
+ * signals here (PII findings, cache decisions, risk scores) for the audit
+ * interceptor to collect at the end of the chain.
+ */
+class InterceptorContext {
+    traceId;
+    agentId;
+    parentTraceId;
+    sessionId;
+    dryRun;
+    interceptorsFired = [];
+    piiEntityTypes = [];
+    piiEntityCounts = {};
+    cacheHit = false;
+    cacheType = null;
+    riskScore = null;
+    guardrailOutcome = null;
+    /** Arbitrary inter-interceptor state (e.g. PII replacement map for restore). */
+    state = {};
+    constructor(init) {
+        this.traceId = init.traceId;
+        this.agentId = init.agentId ?? null;
+        this.parentTraceId = init.parentTraceId ?? null;
+        this.sessionId = init.sessionId ?? null;
+        this.dryRun = init.dryRun ?? false;
+    }
+    markFired(name) {
+        if (!this.interceptorsFired.includes(name)) {
+            this.interceptorsFired.push(name);
+        }
+    }
+    recordPii(entityTypes) {
+        for (const et of entityTypes) {
+            this.piiEntityCounts[et] = (this.piiEntityCounts[et] ?? 0) + 1;
+            if (!this.piiEntityTypes.includes(et)) {
+                this.piiEntityTypes.push(et);
+            }
+        }
+    }
+}
+exports.InterceptorContext = InterceptorContext;

package/dist/cjs/errors.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Gavio error hierarchy. All Gavio errors derive from {@link GavioError} so
+ * 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;
+class GavioError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.GavioError = GavioError;
+/** Raised when the gateway is misconfigured (e.g. no provider set). */
+class ConfigurationError extends GavioError {
+}
+exports.ConfigurationError = ConfigurationError;
+/** Base class for provider-adapter failures. */
+class ProviderError extends GavioError {
+}
+exports.ProviderError = ProviderError;
+/** The provider could not be reached (network / health-check failure). */
+class ProviderUnavailableError extends ProviderError {
+}
+exports.ProviderUnavailableError = ProviderUnavailableError;
+/** The provider returned a rate-limit (HTTP 429) signal. */
+class RateLimitError extends ProviderError {
+}
+exports.RateLimitError = RateLimitError;
+/** The provider returned a 5xx server error. */
+class ServerError extends ProviderError {
+}
+exports.ServerError = ServerError;
+/** A request exceeded its configured timeout. */
+class TimeoutError extends ProviderError {
+}
+exports.TimeoutError = TimeoutError;
+/** PiiGuard is in BLOCK mode and detected PII in the request. */
+class PiiBlockedError extends GavioError {
+    entityTypes;
+    constructor(entityTypes) {
+        const sorted = Array.from(new Set(entityTypes)).sort();
+        super(`Request blocked: PII detected (${sorted.join(', ')})`);
+        this.entityTypes = entityTypes;
+    }
+}
+exports.PiiBlockedError = PiiBlockedError;
+/** A hard budget cap was exceeded. Never swallow this — surface to user. */
+class BudgetExceededError extends GavioError {
+}
+exports.BudgetExceededError = BudgetExceededError;
+/** Output failed a guardrail validator with onFailure='error'. */
+class GuardrailViolationError extends GavioError {
+}
+exports.GuardrailViolationError = GuardrailViolationError;

package/dist/cjs/gateway.js

@@ -0,0 +1,127 @@
+"use strict";
+/** Gateway — the entry point. Wires interceptors around a provider adapter. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Gateway = void 0;
+const context_js_1 = require("./context.js");
+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 pricing_js_1 = require("./pricing.js");
+const index_js_2 = require("./providers/index.js");
+const mock_js_1 = require("./providers/mock.js");
+const request_js_1 = require("./request.js");
+const types_js_1 = require("./types.js");
+const DEFAULT_MODELS = {
+    openai: 'gpt-4o',
+    anthropic: 'claude-sonnet-4-6',
+    mock: 'mock',
+};
+/**
+ * Routes a request through the interceptor pipeline to a provider.
+ *
+ * Construct with `new Gateway({ provider, model })` then chain `.use(...)` and
+ * `.withAdapter(...)`. A single instance is safe to reuse — per-request state
+ * lives in an {@link InterceptorContext} created fresh for every call.
+ */
+class Gateway {
+    providerHint;
+    modelHint;
+    adapterOverride;
+    devMode;
+    dryRunMode;
+    pricing;
+    interceptors = [];
+    constructor(options = {}) {
+        this.providerHint = options.provider ? (0, types_js_1.coerceProvider)(options.provider) : undefined;
+        this.modelHint = options.model;
+        this.adapterOverride = options.adapter;
+        this.devMode = options.devMode ?? false;
+        this.dryRunMode = options.dryRun ?? false;
+        this.pricing = options.pricing ?? new pricing_js_1.PricingProvider();
+    }
+    /** Register an interceptor or executor policy. First-registered = outermost. */
+    use(interceptor) {
+        this.interceptors.push(interceptor);
+        return this;
+    }
+    /** Supply a provider adapter explicitly (overrides `provider`). */
+    withAdapter(adapter) {
+        this.adapterOverride = adapter;
+        return this;
+    }
+    get model() {
+        return this.modelHint ?? this.resolveModel(this.resolveAdapter());
+    }
+    get providerName() {
+        return this.resolveAdapter().providerName;
+    }
+    async complete(opts) {
+        const adapter = this.resolveAdapter();
+        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 { chain, executor } = this.buildPipeline(adapter, ctx);
+        return chain.execute(request, ctx, executor);
+    }
+    async healthCheck() {
+        return this.resolveAdapter().healthCheck();
+    }
+    buildPipeline(adapter, ctx) {
+        let interceptors = [...this.interceptors];
+        // Dev mode auto-wires a stdout audit sink if none was added.
+        if (this.devMode && !interceptors.some(index_js_1.isAuditInterceptor)) {
+            interceptors = [(0, index_js_1.auditInterceptor)(), ...interceptors];
+        }
+        const policies = interceptors.filter(base_js_1.isExecutorPolicy);
+        const regular = interceptors.filter((i) => !(0, base_js_1.isExecutorPolicy)(i));
+        const chain = new chain_js_1.InterceptorChain(regular);
+        let executor = (request) => adapter.complete(request);
+        // Wrap so the first-registered policy ends up outermost.
+        for (let i = policies.length - 1; i >= 0; i--) {
+            executor = this.wrapPolicy(policies[i], executor, ctx);
+        }
+        return { chain, executor };
+    }
+    wrapPolicy(policy, inner, ctx) {
+        return async (request) => {
+            if (ctx.dryRun && policy.dryRunSafe === false) {
+                return inner(request);
+            }
+            return policy.around(request, ctx, inner);
+        };
+    }
+    resolveAdapter() {
+        if (this.adapterOverride !== undefined)
+            return this.adapterOverride;
+        if (this.devMode) {
+            this.adapterOverride = (0, mock_js_1.mockProvider)({ pricing: this.pricing });
+            return this.adapterOverride;
+        }
+        if (this.providerHint === undefined) {
+            throw new errors_js_1.ConfigurationError('No provider configured. Pass { provider }, { adapter }, call .withAdapter(...), ' +
+                'or set { devMode: true }.');
+        }
+        this.adapterOverride = (0, index_js_2.buildAdapter)(this.providerHint, this.pricing);
+        return this.adapterOverride;
+    }
+    resolveModel(adapter) {
+        return DEFAULT_MODELS[adapter.providerName] ?? 'mock';
+    }
+}
+exports.Gateway = Gateway;

package/dist/cjs/ids.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * UUID v7 generation — time-sortable, unique identifiers for traces.
+ *
+ * UUID v7 layout (RFC 9562): 48-bit Unix millisecond timestamp, 4-bit version,
+ * 12 bits used here as a per-millisecond monotonic sequence (rand_a), 2-bit
+ * variant, 62 bits of randomness. Ported directly from the Python `_ids.py`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuid7 = uuid7;
+exports.newTraceId = newTraceId;
+const node_crypto_1 = require("node:crypto");
+let lastMs = -1;
+let seq = 0; // 12-bit per-millisecond sequence in rand_a, for monotonicity
+/**
+ * Return a [unix_ms, sequence] pair that is monotonically non-decreasing.
+ *
+ * Within a single millisecond the 12-bit sequence increments so IDs stay
+ * strictly ordered (RFC 9562 method 1). If the sequence overflows, the
+ * timestamp is nudged forward. JavaScript is single-threaded per event loop,
+ * so no lock is required.
+ */
+function nextTimestampAndSeq() {
+    const nowMs = Date.now();
+    if (nowMs > lastMs) {
+        lastMs = nowMs;
+        seq = (0, node_crypto_1.randomBytes)(2).readUInt16BE(0) & 0x0fff;
+    }
+    else {
+        seq += 1;
+        if (seq > 0x0fff) {
+            lastMs += 1;
+            seq = 0;
+        }
+    }
+    return [lastMs, seq];
+}
+function toHex(value, width) {
+    return value.toString(16).padStart(width, '0');
+}
+/** Return a new UUID version 7 (time-ordered, monotonic within a process). */
+function uuid7() {
+    const [unixMs, randA] = nextTimestampAndSeq();
+    // 48-bit millisecond timestamp occupies bits 80..127. Use BigInt for the
+    // shift — JS bitwise ops are 32-bit and would truncate Date.now() (~1.75e12).
+    const ms = BigInt(unixMs) & 0xffffffffffffn;
+    const randBuf = (0, node_crypto_1.randomBytes)(8);
+    const randB = randBuf.readBigUInt64BE(0) & 0x3fffffffffffffffn; // 62 bits
+    const value = (ms << 80n) |
+        (0x7n << 76n) | // version 7
+        (BigInt(randA) << 64n) |
+        (2n << 62n) | // variant
+        randB;
+    const hex = toHex(value, 32);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** Return a fresh trace id as a string. */
+function newTraceId() {
+    return uuid7();
+}

package/dist/cjs/index.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Gavio — the open standard AI gateway for production systems.
+ *
+ * Public API surface (v0.1.0):
+ *
+ *     import { Gateway, GavioRequest, GavioResponse, Provider } from 'gavio'
+ *
+ * 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';
+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");
+Object.defineProperty(exports, "GavioRequest", { enumerable: true, get: function () { return request_js_1.GavioRequest; } });
+var response_js_1 = require("./response.js");
+Object.defineProperty(exports, "GavioResponse", { enumerable: true, get: function () { return response_js_1.GavioResponse; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "InterceptorContext", { enumerable: true, get: function () { return context_js_1.InterceptorContext; } });
+var ids_js_1 = require("./ids.js");
+Object.defineProperty(exports, "uuid7", { enumerable: true, get: function () { return ids_js_1.uuid7; } });
+Object.defineProperty(exports, "newTraceId", { enumerable: true, get: function () { return ids_js_1.newTraceId; } });
+var pricing_js_1 = require("./pricing.js");
+Object.defineProperty(exports, "PricingProvider", { enumerable: true, get: function () { return pricing_js_1.PricingProvider; } });
+Object.defineProperty(exports, "estimateTokens", { enumerable: true, get: function () { return pricing_js_1.estimateTokens; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "Provider", { enumerable: true, get: function () { return types_js_1.Provider; } });
+Object.defineProperty(exports, "CacheType", { enumerable: true, get: function () { return types_js_1.CacheType; } });
+Object.defineProperty(exports, "PiiMode", { enumerable: true, get: function () { return types_js_1.PiiMode; } });
+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, "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; } });
+// errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "GavioError", { enumerable: true, get: function () { return errors_js_1.GavioError; } });
+Object.defineProperty(exports, "ConfigurationError", { enumerable: true, get: function () { return errors_js_1.ConfigurationError; } });
+Object.defineProperty(exports, "ProviderError", { enumerable: true, get: function () { return errors_js_1.ProviderError; } });
+Object.defineProperty(exports, "ProviderUnavailableError", { enumerable: true, get: function () { return errors_js_1.ProviderUnavailableError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "PiiBlockedError", { enumerable: true, get: function () { return errors_js_1.PiiBlockedError; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return errors_js_1.BudgetExceededError; } });
+Object.defineProperty(exports, "GuardrailViolationError", { enumerable: true, get: function () { return errors_js_1.GuardrailViolationError; } });

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });
+Object.defineProperty(exports, "AUDIT_NAME", { enumerable: true, get: function () { return interceptor_js_1.AUDIT_NAME; } });
+var record_js_1 = require("./record.js");
+Object.defineProperty(exports, "AuditRecord", { enumerable: true, get: function () { return record_js_1.AuditRecord; } });
+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; } });

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

@@ -0,0 +1,77 @@
+"use strict";
+/** auditInterceptor (F-OBS-01) — captures a full record of every call. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIT_NAME = void 0;
+exports.auditInterceptor = auditInterceptor;
+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';
+exports.AUDIT_NAME = 'audit';
+/**
+ * Build an AuditRecord per request and write it to a sink.
+ *
+ * Register this as the outermost interceptor so its `after` runs last and sees
+ * the final, fully-processed response. It hashes the (already PII-redacted)
+ * prompt in `before` and the response in `after` — content is never stored,
+ * only digests and metadata.
+ */
+class AuditInterceptor {
+    name = exports.AUDIT_NAME;
+    dryRunSafe = true; // auditing is observation-only, so it always runs
+    sink;
+    constructor(options = {}) {
+        this.sink = resolveSink(options.sink);
+    }
+    async before(request, ctx) {
+        ctx.state[PROMPT_HASH_KEY] = record_js_1.AuditRecord.hashText(request.promptText());
+        return request;
+    }
+    async after(response, ctx) {
+        const record = new record_js_1.AuditRecord({
+            traceId: response.traceId,
+            parentTraceId: ctx.parentTraceId,
+            agentId: ctx.agentId,
+            sessionId: ctx.sessionId,
+            timestampUtc: record_js_1.AuditRecord.nowUtc(),
+            provider: response.provider,
+            model: response.model,
+            modelVersion: response.modelVersion,
+            promptHash: ctx.state[PROMPT_HASH_KEY] ?? '',
+            responseHash: record_js_1.AuditRecord.hashText(response.content),
+            tokenUsage: response.usage,
+            costUsd: response.costUsd,
+            latencyMs: response.latencyMs,
+            piiEntityTypes: [...ctx.piiEntityTypes],
+            piiEntityCounts: { ...ctx.piiEntityCounts },
+            interceptorsFired: [...ctx.interceptorsFired],
+            cacheHit: response.cacheHit,
+            cacheType: response.cacheType,
+            guardrailOutcome: ctx.guardrailOutcome,
+            riskScore: ctx.riskScore,
+        });
+        response.audit = record;
+        try {
+            await this.sink.write(record);
+        }
+        catch {
+            // Auditing must never break the call.
+            // eslint-disable-next-line no-console
+            console.error(`[gavio:audit] sink write failed for trace ${record.traceId}`);
+        }
+        return response;
+    }
+}
+function resolveSink(sink) {
+    if (sink === undefined || sink === 'stdout')
+        return (0, stdout_js_1.stdoutSink)();
+    return sink;
+}
+/** Factory: build an audit interceptor. */
+function auditInterceptor(options = {}) {
+    return new AuditInterceptor(options);
+}
+/** True if an interceptor is the audit interceptor (used by dev-mode auto-wiring). */
+function isAuditInterceptor(i) {
+    return i.name === exports.AUDIT_NAME;
+}

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

@@ -0,0 +1,107 @@
+"use strict";
+/** AuditRecord — the immutable, per-request audit entry. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditRecord = exports.SCHEMA_VERSION = void 0;
+const node_crypto_1 = require("node:crypto");
+const types_js_1 = require("../../types.js");
+exports.SCHEMA_VERSION = '1.0';
+function sha256(text) {
+    return (0, node_crypto_1.createHash)('sha256').update(text, 'utf-8').digest('hex');
+}
+/**
+ * One append-only audit entry. Carries metadata only — never raw content.
+ *
+ * `promptHash` / `responseHash` are SHA-256 digests so the entry is verifiable
+ * without storing sensitive text. `previousHash` is reserved for the v0.2.0
+ * hash-chain (F-OBS-02); empty in v0.1.0.
+ */
+class AuditRecord {
+    traceId;
+    provider;
+    model;
+    timestampUtc;
+    parentTraceId;
+    agentId;
+    sessionId;
+    modelVersion;
+    promptHash;
+    responseHash;
+    tokenUsage;
+    costUsd;
+    latencyMs;
+    piiEntityTypes;
+    piiEntityCounts;
+    interceptorsFired;
+    cacheHit;
+    cacheType;
+    guardrailOutcome;
+    riskScore;
+    previousHash;
+    schemaVersion;
+    constructor(init) {
+        this.traceId = init.traceId;
+        this.provider = init.provider;
+        this.model = init.model;
+        this.timestampUtc = init.timestampUtc;
+        this.parentTraceId = init.parentTraceId ?? null;
+        this.agentId = init.agentId ?? null;
+        this.sessionId = init.sessionId ?? null;
+        this.modelVersion = init.modelVersion ?? '';
+        this.promptHash = init.promptHash ?? '';
+        this.responseHash = init.responseHash ?? '';
+        this.tokenUsage = init.tokenUsage ?? new types_js_1.TokenUsage();
+        this.costUsd = init.costUsd ?? 0.0;
+        this.latencyMs = init.latencyMs ?? 0;
+        this.piiEntityTypes = init.piiEntityTypes ?? [];
+        this.piiEntityCounts = init.piiEntityCounts ?? {};
+        this.interceptorsFired = init.interceptorsFired ?? [];
+        this.cacheHit = init.cacheHit ?? false;
+        this.cacheType = init.cacheType ?? null;
+        this.guardrailOutcome = init.guardrailOutcome ?? null;
+        this.riskScore = init.riskScore ?? null;
+        this.previousHash = init.previousHash ?? '';
+        this.schemaVersion = init.schemaVersion ?? exports.SCHEMA_VERSION;
+    }
+    static nowUtc() {
+        return new Date().toISOString();
+    }
+    static hashText(text) {
+        return sha256(text);
+    }
+    toJSON() {
+        return {
+            traceId: this.traceId,
+            parentTraceId: this.parentTraceId,
+            agentId: this.agentId,
+            sessionId: this.sessionId,
+            provider: this.provider,
+            model: this.model,
+            modelVersion: this.modelVersion,
+            timestampUtc: this.timestampUtc,
+            promptHash: this.promptHash,
+            responseHash: this.responseHash,
+            tokenUsage: this.tokenUsage.toJSON(),
+            costUsd: this.costUsd,
+            latencyMs: this.latencyMs,
+            piiEntityTypes: this.piiEntityTypes,
+            piiEntityCounts: this.piiEntityCounts,
+            interceptorsFired: this.interceptorsFired,
+            cacheHit: this.cacheHit,
+            cacheType: this.cacheType,
+            guardrailOutcome: this.guardrailOutcome,
+            riskScore: this.riskScore,
+            previousHash: this.previousHash,
+            schemaVersion: this.schemaVersion,
+        };
+    }
+    /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+    toCanonicalJson() {
+        const data = this.toJSON();
+        return JSON.stringify(data, Object.keys(data).sort());
+    }
+    /** Hash of this record's content — used to build the v0.2.0 chain. */
+    contentHash() {
+        return sha256(this.toCanonicalJson());
+    }
+}
+exports.AuditRecord = AuditRecord;

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

@@ -0,0 +1,3 @@
+"use strict";
+/** AuditSink — the extensible destination for audit records. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/interceptors/audit/sinks/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stdoutSink = void 0;
+var stdout_js_1 = require("./stdout.js");
+Object.defineProperty(exports, "stdoutSink", { enumerable: true, get: function () { return stdout_js_1.stdoutSink; } });