gavio 0.1.0

package/dist/esm/gateway.js

@@ -0,0 +1,123 @@
+/** Gateway — the entry point. Wires interceptors around a provider adapter. */
+import { InterceptorContext } from './context.js';
+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 { PricingProvider } from './pricing.js';
+import { buildAdapter } from './providers/index.js';
+import { mockProvider } from './providers/mock.js';
+import { GavioRequest } from './request.js';
+import { Provider, coerceProvider } from './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.
+ */
+export class Gateway {
+    providerHint;
+    modelHint;
+    adapterOverride;
+    devMode;
+    dryRunMode;
+    pricing;
+    interceptors = [];
+    constructor(options = {}) {
+        this.providerHint = options.provider ? 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 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 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 { 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(isAuditInterceptor)) {
+            interceptors = [auditInterceptor(), ...interceptors];
+        }
+        const policies = interceptors.filter(isExecutorPolicy);
+        const regular = interceptors.filter((i) => !isExecutorPolicy(i));
+        const chain = new 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 = mockProvider({ pricing: this.pricing });
+            return this.adapterOverride;
+        }
+        if (this.providerHint === undefined) {
+            throw new ConfigurationError('No provider configured. Pass { provider }, { adapter }, call .withAdapter(...), ' +
+                'or set { devMode: true }.');
+        }
+        this.adapterOverride = buildAdapter(this.providerHint, this.pricing);
+        return this.adapterOverride;
+    }
+    resolveModel(adapter) {
+        return DEFAULT_MODELS[adapter.providerName] ?? 'mock';
+    }
+}

package/dist/esm/ids.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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`.
+ */
+/** Return a new UUID version 7 (time-ordered, monotonic within a process). */
+export declare function uuid7(): string;
+/** Return a fresh trace id as a string. */
+export declare function newTraceId(): string;

package/dist/esm/ids.js

@@ -0,0 +1,56 @@
+/**
+ * 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`.
+ */
+import { randomBytes } from '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 = 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). */
+export 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 = 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. */
+export function newTraceId() {
+    return uuid7();
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export declare const VERSION = "0.1.0";
+export { Gateway } from './gateway.js';
+export type { GatewayOptions, CompleteOptions } from './gateway.js';
+export { GavioRequest } from './request.js';
+export type { GavioRequestInit } from './request.js';
+export { GavioResponse } from './response.js';
+export type { GavioResponseInit } from './response.js';
+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 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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+export const VERSION = '0.1.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 { 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/index.d.ts

@@ -0,0 +1,7 @@
+export { auditInterceptor, isAuditInterceptor, AUDIT_NAME } from './interceptor.js';
+export type { AuditInterceptorOptions } from './interceptor.js';
+export { AuditRecord, SCHEMA_VERSION } from './record.js';
+export type { AuditRecordInit } from './record.js';
+export type { AuditSink } from './sink.js';
+export { stdoutSink } from './sinks/stdout.js';
+export type { StdoutSinkOptions } from './sinks/stdout.js';

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

@@ -0,0 +1,3 @@
+export { auditInterceptor, isAuditInterceptor, AUDIT_NAME } from './interceptor.js';
+export { AuditRecord, SCHEMA_VERSION } from './record.js';
+export { stdoutSink } from './sinks/stdout.js';

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

@@ -0,0 +1,11 @@
+/** auditInterceptor (F-OBS-01) — captures a full record of every call. */
+import type { Interceptor } from '../base.js';
+import type { AuditSink } from './sink.js';
+export declare const AUDIT_NAME = "audit";
+export interface AuditInterceptorOptions {
+    sink?: AuditSink | 'stdout';
+}
+/** Factory: build an audit interceptor. */
+export declare function auditInterceptor(options?: AuditInterceptorOptions): Interceptor;
+/** True if an interceptor is the audit interceptor (used by dev-mode auto-wiring). */
+export declare function isAuditInterceptor(i: Interceptor): boolean;

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

@@ -0,0 +1,72 @@
+/** auditInterceptor (F-OBS-01) — captures a full record of every call. */
+import { AuditRecord } from './record.js';
+import { stdoutSink } from './sinks/stdout.js';
+const PROMPT_HASH_KEY = 'audit_prompt_hash';
+export const 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 = 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] = AuditRecord.hashText(request.promptText());
+        return request;
+    }
+    async after(response, ctx) {
+        const record = new AuditRecord({
+            traceId: response.traceId,
+            parentTraceId: ctx.parentTraceId,
+            agentId: ctx.agentId,
+            sessionId: ctx.sessionId,
+            timestampUtc: AuditRecord.nowUtc(),
+            provider: response.provider,
+            model: response.model,
+            modelVersion: response.modelVersion,
+            promptHash: ctx.state[PROMPT_HASH_KEY] ?? '',
+            responseHash: 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 stdoutSink();
+    return sink;
+}
+/** Factory: build an audit interceptor. */
+export function auditInterceptor(options = {}) {
+    return new AuditInterceptor(options);
+}
+/** True if an interceptor is the audit interceptor (used by dev-mode auto-wiring). */
+export function isAuditInterceptor(i) {
+    return i.name === AUDIT_NAME;
+}

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

@@ -0,0 +1,66 @@
+/** AuditRecord — the immutable, per-request audit entry. */
+import { TokenUsage } from '../../types.js';
+export declare const SCHEMA_VERSION = "1.0";
+export interface AuditRecordInit {
+    traceId: string;
+    provider: string;
+    model: string;
+    timestampUtc: string;
+    parentTraceId?: string | null;
+    agentId?: string | null;
+    sessionId?: string | null;
+    modelVersion?: string;
+    promptHash?: string;
+    responseHash?: string;
+    tokenUsage?: TokenUsage;
+    costUsd?: number;
+    latencyMs?: number;
+    piiEntityTypes?: string[];
+    piiEntityCounts?: Record<string, number>;
+    interceptorsFired?: string[];
+    cacheHit?: boolean;
+    cacheType?: string | null;
+    guardrailOutcome?: string | null;
+    riskScore?: number | null;
+    previousHash?: string;
+    schemaVersion?: string;
+}
+/**
+ * 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.
+ */
+export declare class AuditRecord {
+    traceId: string;
+    provider: string;
+    model: string;
+    timestampUtc: string;
+    parentTraceId: string | null;
+    agentId: string | null;
+    sessionId: string | null;
+    modelVersion: string;
+    promptHash: string;
+    responseHash: string;
+    tokenUsage: TokenUsage;
+    costUsd: number;
+    latencyMs: number;
+    piiEntityTypes: string[];
+    piiEntityCounts: Record<string, number>;
+    interceptorsFired: string[];
+    cacheHit: boolean;
+    cacheType: string | null;
+    guardrailOutcome: string | null;
+    riskScore: number | 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. */
+    toCanonicalJson(): string;
+    /** Hash of this record's content — used to build the v0.2.0 chain. */
+    contentHash(): string;
+}

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

@@ -0,0 +1,103 @@
+/** AuditRecord — the immutable, per-request audit entry. */
+import { createHash } from 'node:crypto';
+import { TokenUsage } from '../../types.js';
+export const SCHEMA_VERSION = '1.0';
+function sha256(text) {
+    return 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.
+ */
+export 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 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 ?? 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());
+    }
+}

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

@@ -0,0 +1,8 @@
+/** AuditSink — the extensible destination for audit records. */
+import type { AuditRecord } from './record.js';
+/** Where audit records go. Implement `write` to add a backend. */
+export interface AuditSink {
+    write(record: AuditRecord): Promise<void>;
+    /** Flush/close any resources. Optional. */
+    close?(): Promise<void>;
+}

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

@@ -0,0 +1,2 @@
+/** AuditSink — the extensible destination for audit records. */
+export {};

package/dist/esm/interceptors/audit/sinks/index.d.ts

@@ -0,0 +1,2 @@
+export { stdoutSink } from './stdout.js';
+export type { StdoutSinkOptions } from './stdout.js';

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

@@ -0,0 +1 @@
+export { stdoutSink } from './stdout.js';

package/dist/esm/interceptors/audit/sinks/stdout.d.ts

@@ -0,0 +1,8 @@
+/** stdoutSink — human-readable audit output for development (F-OBS-05). */
+import type { AuditSink } from '../sink.js';
+export interface StdoutSinkOptions {
+    pretty?: boolean;
+    write?: (line: string) => void;
+}
+/** Print each audit record to stdout. Zero dependencies. */
+export declare function stdoutSink(options?: StdoutSinkOptions): AuditSink;

package/dist/esm/interceptors/audit/sinks/stdout.js

@@ -0,0 +1,30 @@
+/** stdoutSink — human-readable audit output for development (F-OBS-05). */
+/** Print each audit record to stdout. Zero dependencies. */
+export function stdoutSink(options = {}) {
+    const pretty = options.pretty ?? true;
+    // eslint-disable-next-line no-console
+    const emit = options.write ?? ((line) => console.log(line));
+    return {
+        async write(record) {
+            const data = record.toJSON();
+            emit(pretty ? formatPretty(data) : JSON.stringify(data));
+        },
+    };
+}
+function formatPretty(data) {
+    const usage = data['tokenUsage'];
+    const piiTypes = data['piiEntityTypes'];
+    const pii = piiTypes.length > 0 ? piiTypes : ['none'];
+    const interceptors = data['interceptorsFired'];
+    const traceId = String(data['traceId']);
+    const cost = Number(data['costUsd']);
+    return ('[gavio:audit] ' +
+        `trace=${traceId.slice(0, 18)}… ` +
+        `${String(data['provider'])}/${String(data['model'])} ` +
+        `tokens=${usage.totalTokens} ` +
+        `cost=$${cost.toFixed(6)} ` +
+        `latency=${String(data['latencyMs'])}ms ` +
+        `cache=${data['cacheHit'] ? 'HIT' : 'miss'} ` +
+        `pii=${pii.join(',')} ` +
+        `interceptors=[${interceptors.join(',')}]`);
+}

package/dist/esm/interceptors/base.d.ts

@@ -0,0 +1,37 @@
+/** The Interceptor interface — the unit of composition in Gavio. */
+import type { InterceptorContext } from '../context.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+/**
+ * A pre/post hook around the provider call.
+ *
+ * `before` runs in registration order on the request; `after` runs in reverse
+ * order on the response (onion model). Either may be omitted. Throwing from
+ * `before` aborts the call.
+ */
+export interface Interceptor {
+    /** Unique name used in audit logs and metrics. */
+    readonly name: string;
+    /** Pre-interceptor: runs before the provider call. */
+    before?(request: GavioRequest, ctx: InterceptorContext): Promise<GavioRequest> | GavioRequest;
+    /** Post-interceptor: runs after the provider call. */
+    after?(response: GavioResponse, ctx: InterceptorContext): Promise<GavioResponse> | GavioResponse;
+    /** Called if the provider call or a downstream interceptor throws. */
+    onError?(error: Error, ctx: InterceptorContext): void | Promise<void>;
+    /** If true (default), participates in dry-run mode (logs only). */
+    readonly dryRunSafe?: boolean;
+}
+/** A function that takes the final request and returns a response (the provider call). */
+export type Executor = (request: GavioRequest) => Promise<GavioResponse>;
+/**
+ * Base class for executor-wrapping reliability policies.
+ *
+ * Retry, timeout, and fallback can't be expressed as plain before/after hooks:
+ * they need to re-invoke (or race) the executor. They implement `around` so the
+ * Gateway composes them *around* the provider call, innermost-last.
+ */
+export interface ExecutorPolicy extends Interceptor {
+    readonly isExecutorPolicy: true;
+    around(request: GavioRequest, ctx: InterceptorContext, callNext: Executor): Promise<GavioResponse>;
+}
+export declare function isExecutorPolicy(i: Interceptor): i is ExecutorPolicy;

package/dist/esm/interceptors/base.js

@@ -0,0 +1,4 @@
+/** The Interceptor interface — the unit of composition in Gavio. */
+export function isExecutorPolicy(i) {
+    return i.isExecutorPolicy === true;
+}

package/dist/esm/interceptors/cache/backend.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CacheBackend — the key/value contract behind the cache interceptors.
+ *
+ * The full SemanticCache interceptor lands in v0.2.0 (F-CACHE-01/02). v0.1.0
+ * ships the backend interface and the in-memory backend so dev mode has a
+ * working, dependency-free cache substrate.
+ */
+/** A minimal async key/value store. */
+export interface CacheBackend {
+    get(key: string): Promise<unknown | null>;
+    set(key: string, value: unknown, ttlSeconds?: number | null): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/esm/interceptors/cache/backend.js

@@ -0,0 +1,8 @@
+/**
+ * CacheBackend — the key/value contract behind the cache interceptors.
+ *
+ * The full SemanticCache interceptor lands in v0.2.0 (F-CACHE-01/02). v0.1.0
+ * ships the backend interface and the in-memory backend so dev mode has a
+ * working, dependency-free cache substrate.
+ */
+export {};

package/dist/esm/interceptors/cache/backends/index.d.ts

@@ -0,0 +1,2 @@
+export { memoryCacheBackend } from './memory.js';
+export type { MemoryCacheBackendOptions } from './memory.js';

package/dist/esm/interceptors/cache/backends/index.js

@@ -0,0 +1 @@
+export { memoryCacheBackend } from './memory.js';

package/dist/esm/interceptors/cache/backends/memory.d.ts

@@ -0,0 +1,7 @@
+/** In-memory cache backend (F-CACHE-03) — default zero-dependency dev backend. */
+import type { CacheBackend } from '../backend.js';
+export interface MemoryCacheBackendOptions {
+    maxSize?: number;
+}
+/** Factory: build an in-memory cache backend. */
+export declare function memoryCacheBackend(options?: MemoryCacheBackendOptions): CacheBackend;