govyn 0.0.1 → 0.2.5

package/dist/cost-api.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP handler for the GET /api/costs endpoint.
+ *
+ * Returns per-agent, per-model, and per-period cost summaries from the
+ * in-memory CostAggregator. Supports query parameters for filtering:
+ *   ?agent=<agentId>   — filter to a specific agent
+ *   ?period=<period>   — 'hour', 'day'/'today', 'week', 'month', 'all' (default: 'all')
+ *
+ * Also serves GET /api/costs/timeseries for chart-ready bucketed spend history.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { CostAggregator } from './cost-aggregator.js';
+/**
+ * Handle GET /api/costs requests.
+ *
+ * - Returns 405 for non-GET methods.
+ * - Returns 200 JSON with cost data for GET.
+ *
+ * Response shape:
+ * {
+ *   "period": "all",
+ *   "generated_at": "2026-02-24T12:00:00Z",
+ *   "agents": [ CostSummary... ],
+ *   "models": { model: { cost, requests, inputTokens, outputTokens }, ... },
+ *   "unpriced_models": ["unknown-model-xyz"],
+ *   "totals": { cost, requests, input_tokens, output_tokens }
+ * }
+ */
+export declare function handleCostApi(req: IncomingMessage, res: ServerResponse, aggregator: CostAggregator): void;

package/dist/cost-api.js

@@ -0,0 +1,128 @@
+/**
+ * HTTP handler for the GET /api/costs endpoint.
+ *
+ * Returns per-agent, per-model, and per-period cost summaries from the
+ * in-memory CostAggregator. Supports query parameters for filtering:
+ *   ?agent=<agentId>   — filter to a specific agent
+ *   ?period=<period>   — 'hour', 'day'/'today', 'week', 'month', 'all' (default: 'all')
+ *
+ * Also serves GET /api/costs/timeseries for chart-ready bucketed spend history.
+ */
+import { URL } from 'node:url';
+/**
+ * Handle GET /api/costs requests.
+ *
+ * - Returns 405 for non-GET methods.
+ * - Returns 200 JSON with cost data for GET.
+ *
+ * Response shape:
+ * {
+ *   "period": "all",
+ *   "generated_at": "2026-02-24T12:00:00Z",
+ *   "agents": [ CostSummary... ],
+ *   "models": { model: { cost, requests, inputTokens, outputTokens }, ... },
+ *   "unpriced_models": ["unknown-model-xyz"],
+ *   "totals": { cost, requests, input_tokens, output_tokens }
+ * }
+ */
+export function handleCostApi(req, res, aggregator) {
+    // Only allow GET
+    if (req.method !== 'GET') {
+        const body = JSON.stringify({ error: { message: 'Method not allowed', code: 'method_not_allowed' } });
+        res.writeHead(405, {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(body).toString(),
+            'allow': 'GET',
+        });
+        res.end(body);
+        return;
+    }
+    // Parse query parameters from the request URL
+    // Use a dummy base to parse relative URLs
+    const baseUrl = `http://localhost`;
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(req.url ?? '/api/costs', baseUrl);
+    }
+    catch {
+        parsedUrl = new URL('/api/costs', baseUrl);
+    }
+    const agentParam = parsedUrl.searchParams.get('agent') ?? undefined;
+    const periodParam = parsedUrl.searchParams.get('period') ?? 'all';
+    // Map 'today' to 'day' for convenience
+    let period;
+    switch (periodParam) {
+        case 'today':
+            period = 'day';
+            break;
+        case 'hour':
+        case 'day':
+        case 'week':
+        case 'month':
+        case 'all':
+            period = periodParam;
+            break;
+        default:
+            period = 'all';
+            break;
+    }
+    if (parsedUrl.pathname === '/api/costs/timeseries') {
+        const timeseries = aggregator.getTimeSeries({ agentId: agentParam, period });
+        const body = JSON.stringify({
+            period,
+            bucket: timeseries.bucket,
+            generated_at: new Date().toISOString(),
+            points: timeseries.points,
+        });
+        res.writeHead(200, {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(body).toString(),
+        });
+        res.end(body);
+        return;
+    }
+    if (parsedUrl.pathname !== '/api/costs') {
+        const body = JSON.stringify({ error: { message: 'Not found', code: 'not_found' } });
+        res.writeHead(404, {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(body).toString(),
+        });
+        res.end(body);
+        return;
+    }
+    // Query the aggregator
+    const agents = aggregator.getSummary({ agentId: agentParam, period });
+    const models = aggregator.getModelSummary({ period });
+    const unpricedModels = aggregator.getUnpricedModels();
+    // Compute totals by summing across all agent summaries
+    let totalCost = 0;
+    let totalRequests = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    for (const summary of agents) {
+        totalCost += summary.totalCost;
+        totalRequests += summary.requestCount;
+        totalInputTokens += summary.totalInputTokens;
+        totalOutputTokens += summary.totalOutputTokens;
+    }
+    const responseData = {
+        period,
+        generated_at: new Date().toISOString(),
+        agents,
+        models,
+        unpriced_models: unpricedModels,
+        totals: {
+            cost: totalCost,
+            requests: totalRequests,
+            input_tokens: totalInputTokens,
+            output_tokens: totalOutputTokens,
+        },
+    };
+    const body = JSON.stringify(responseData);
+    res.writeHead(200, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body).toString(),
+    });
+    res.end(body);
+}
+//# sourceMappingURL=cost-api.js.map

package/dist/cost-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-api.js","sourceRoot":"","sources":["../src/cost-api.ts"],"names":[],"mappings":"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"}

package/dist/database-url.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_SQLITE_DATABASE_FILE = "./govyn.db";
+export type DatabaseKind = 'sqlite' | 'postgres';
+export declare function getDatabaseKind(databaseUrl: string): DatabaseKind;
+export declare function defaultDatabaseUrl(configPath: string): string;
+export declare function resolveDatabaseUrl(rawUrl: string, configPath: string): string;
+export declare function sqlitePathFromUrl(databaseUrl: string): string;

package/dist/database-url.js

@@ -0,0 +1,47 @@
+import * as path from 'node:path';
+export const DEFAULT_SQLITE_DATABASE_FILE = './govyn.db';
+export function getDatabaseKind(databaseUrl) {
+    const normalized = databaseUrl.trim().toLowerCase();
+    if (normalized.startsWith('sqlite:')) {
+        return 'sqlite';
+    }
+    if (normalized.startsWith('postgres://') || normalized.startsWith('postgresql://')) {
+        return 'postgres';
+    }
+    throw new Error(`Unsupported database.url "${databaseUrl}". Use sqlite:./govyn.db or postgres://...`);
+}
+export function defaultDatabaseUrl(configPath) {
+    return `sqlite:${resolveSqlitePath(DEFAULT_SQLITE_DATABASE_FILE, configPath)}`;
+}
+export function resolveDatabaseUrl(rawUrl, configPath) {
+    const trimmed = rawUrl.trim();
+    if (trimmed.length === 0) {
+        throw new Error('database.url must not be empty');
+    }
+    const kind = getDatabaseKind(trimmed);
+    if (kind === 'postgres') {
+        return trimmed;
+    }
+    const sqlitePath = trimmed.slice('sqlite:'.length);
+    return `sqlite:${resolveSqlitePath(sqlitePath, configPath)}`;
+}
+export function sqlitePathFromUrl(databaseUrl) {
+    if (getDatabaseKind(databaseUrl) !== 'sqlite') {
+        throw new Error(`Expected a sqlite database URL, got "${databaseUrl}"`);
+    }
+    return databaseUrl.slice('sqlite:'.length);
+}
+function resolveSqlitePath(candidate, configPath) {
+    const trimmed = candidate.trim();
+    if (trimmed === ':memory:') {
+        return trimmed;
+    }
+    if (!trimmed) {
+        return resolveSqlitePath(DEFAULT_SQLITE_DATABASE_FILE, configPath);
+    }
+    if (path.isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return path.resolve(path.dirname(configPath), trimmed);
+}
+//# sourceMappingURL=database-url.js.map

package/dist/database-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.js","sourceRoot":"","sources":["../src/database-url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,CAAC,MAAM,4BAA4B,GAAG,YAAY,CAAC;AAIzD,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpD,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,UAAU,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACnF,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,6BAA6B,WAAW,4CAA4C,CACrF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,UAAkB;IACnD,OAAO,UAAU,iBAAiB,CAAC,4BAA4B,EAAE,UAAU,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,UAAkB;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,UAAU,iBAAiB,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,IAAI,eAAe,CAAC,WAAW,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,wCAAwC,WAAW,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB,EAAE,UAAkB;IAC9D,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,iBAAiB,CAAC,4BAA4B,EAAE,UAAU,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/dist/db-retention.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Data retention manager for the Govyn proxy database.
+ *
+ * Handles cleanup of old records with pre-delete aggregation:
+ * - Cost records are aggregated into daily summaries before deletion
+ * - Policy evaluations are deleted after retention period (no aggregation needed)
+ * - Approval records have a separate, longer retention period
+ *
+ * Designed to run on a periodic schedule (e.g. every 6 hours).
+ */
+import type postgres from 'postgres';
+import type { RetentionStore } from './persistence-types.js';
+/**
+ * RetentionManager aggregates and cleans up old database records.
+ */
+export declare class RetentionManager {
+    private retentionDays;
+    private approvalRetentionDays;
+    private readonly store;
+    constructor(storeOrSql: RetentionStore | postgres.Sql, retentionDays: number, approvalRetentionDays: number);
+    /**
+     * Aggregate old cost records into daily summaries, then delete the raw records.
+     *
+     * Before deleting: INSERT INTO cost_daily_summary grouped by agent_id, model, provider, date.
+     * Uses UPSERT (ON CONFLICT UPDATE) so re-runs are safe.
+     * Then: DELETE FROM cost_records WHERE created_at < cutoff.
+     *
+     * @returns Counts of aggregated summary rows and deleted raw records
+     */
+    cleanupCostRecords(): Promise<{
+        aggregated: number;
+        deleted: number;
+    }>;
+    /**
+     * Delete old policy evaluation records past the retention period.
+     * No aggregation needed for policy evaluations.
+     *
+     * @returns Number of deleted records
+     */
+    cleanupPolicyEvaluations(): Promise<number>;
+    /**
+     * Delete old approval records past the approval retention period.
+     * Approvals use a separate, longer retention (default 365 days).
+     *
+     * @returns Number of deleted records
+     */
+    cleanupApprovalRecords(): Promise<number>;
+    /**
+     * Run all retention cleanup tasks.
+     * Logs results to stdout for observability.
+     */
+    runAll(): Promise<void>;
+}

package/dist/db-retention.js

@@ -0,0 +1,82 @@
+/**
+ * Data retention manager for the Govyn proxy database.
+ *
+ * Handles cleanup of old records with pre-delete aggregation:
+ * - Cost records are aggregated into daily summaries before deletion
+ * - Policy evaluations are deleted after retention period (no aggregation needed)
+ * - Approval records have a separate, longer retention period
+ *
+ * Designed to run on a periodic schedule (e.g. every 6 hours).
+ */
+import { adaptRetentionStore } from './persistence.js';
+/**
+ * RetentionManager aggregates and cleans up old database records.
+ */
+export class RetentionManager {
+    retentionDays;
+    approvalRetentionDays;
+    store;
+    constructor(storeOrSql, retentionDays, approvalRetentionDays) {
+        this.retentionDays = retentionDays;
+        this.approvalRetentionDays = approvalRetentionDays;
+        this.store = adaptRetentionStore(storeOrSql, retentionDays, approvalRetentionDays);
+    }
+    /**
+     * Aggregate old cost records into daily summaries, then delete the raw records.
+     *
+     * Before deleting: INSERT INTO cost_daily_summary grouped by agent_id, model, provider, date.
+     * Uses UPSERT (ON CONFLICT UPDATE) so re-runs are safe.
+     * Then: DELETE FROM cost_records WHERE created_at < cutoff.
+     *
+     * @returns Counts of aggregated summary rows and deleted raw records
+     */
+    async cleanupCostRecords() {
+        const cutoff = new Date(Date.now() - this.retentionDays * 24 * 60 * 60 * 1000);
+        return this.store.cleanupCostRecords(cutoff);
+    }
+    /**
+     * Delete old policy evaluation records past the retention period.
+     * No aggregation needed for policy evaluations.
+     *
+     * @returns Number of deleted records
+     */
+    async cleanupPolicyEvaluations() {
+        const cutoff = new Date(Date.now() - this.retentionDays * 24 * 60 * 60 * 1000);
+        return this.store.cleanupPolicyEvaluations(cutoff);
+    }
+    /**
+     * Delete old approval records past the approval retention period.
+     * Approvals use a separate, longer retention (default 365 days).
+     *
+     * @returns Number of deleted records
+     */
+    async cleanupApprovalRecords() {
+        const cutoff = new Date(Date.now() - this.approvalRetentionDays * 24 * 60 * 60 * 1000);
+        return this.store.cleanupApprovalRecords(cutoff);
+    }
+    /**
+     * Run all retention cleanup tasks.
+     * Logs results to stdout for observability.
+     */
+    async runAll() {
+        try {
+            const costResult = await this.cleanupCostRecords();
+            if (costResult.deleted > 0) {
+                console.log(`[govyn] Retention cleanup: aggregated ${costResult.aggregated} daily summaries, deleted ${costResult.deleted} cost records`);
+            }
+            const policyDeleted = await this.cleanupPolicyEvaluations();
+            if (policyDeleted > 0) {
+                console.log(`[govyn] Retention cleanup: deleted ${policyDeleted} policy evaluations`);
+            }
+            const approvalDeleted = await this.cleanupApprovalRecords();
+            if (approvalDeleted > 0) {
+                console.log(`[govyn] Retention cleanup: deleted ${approvalDeleted} approval records`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[govyn] Retention cleanup failed: ${message}\n`);
+        }
+    }
+}
+//# sourceMappingURL=db-retention.js.map

package/dist/db-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-retention.js","sourceRoot":"","sources":["../src/db-retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAKjB;IACA;IALO,KAAK,CAAiB;IAEvC,YACE,UAAyC,EACjC,aAAqB,EACrB,qBAA6B;QAD7B,kBAAa,GAAb,aAAa,CAAQ;QACrB,0BAAqB,GAArB,qBAAqB,CAAQ;QAErC,IAAI,CAAC,KAAK,GAAG,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,qBAAqB,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,wBAAwB;QAC5B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB;QAC1B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACvF,OAAO,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACnD,IAAI,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;gBAC3B,OAAO,CAAC,GAAG,CAAC,yCAAyC,UAAU,CAAC,UAAU,6BAA6B,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;YAC5I,CAAC;YAED,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,wBAAwB,EAAE,CAAC;YAC5D,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,GAAG,CAAC,sCAAsC,aAAa,qBAAqB,CAAC,CAAC;YACxF,CAAC;YAED,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,sBAAsB,EAAE,CAAC;YAC5D,IAAI,eAAe,GAAG,CAAC,EAAE,CAAC;gBACxB,OAAO,CAAC,GAAG,CAAC,sCAAsC,eAAe,mBAAmB,CAAC,CAAC;YACxF,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,OAAO,IAAI,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;CACF"}

package/dist/db-schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SQL schema definitions and versioned migration statements for the Govyn proxy.
+ *
+ * Migrations are applied in order by the migration runner (src/db.ts).
+ * Each migration runs inside a transaction and is tracked in govyn_migrations.
+ */
+export interface Migration {
+    version: number;
+    name: string;
+    sql: string;
+}
+/**
+ * Ordered array of database migrations.
+ * New migrations are appended with incrementing version numbers.
+ * NEVER modify or reorder existing migrations — append only.
+ */
+export declare const MIGRATIONS: Migration[];

package/dist/db-schema.js

@@ -0,0 +1,167 @@
+/**
+ * SQL schema definitions and versioned migration statements for the Govyn proxy.
+ *
+ * Migrations are applied in order by the migration runner (src/db.ts).
+ * Each migration runs inside a transaction and is tracked in govyn_migrations.
+ */
+/**
+ * Ordered array of database migrations.
+ * New migrations are appended with incrementing version numbers.
+ * NEVER modify or reorder existing migrations — append only.
+ */
+export const MIGRATIONS = [
+    {
+        version: 1,
+        name: 'initial_schema',
+        sql: `
+      -- Migrations tracking table
+      CREATE TABLE IF NOT EXISTS govyn_migrations (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      -- Cost records table
+      CREATE TABLE IF NOT EXISTS cost_records (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        agent_id TEXT NOT NULL,
+        model TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        input_tokens INTEGER NOT NULL,
+        output_tokens INTEGER NOT NULL,
+        input_cost NUMERIC(12,8) NOT NULL,
+        output_cost NUMERIC(12,8) NOT NULL,
+        total_cost NUMERIC(12,8) NOT NULL,
+        priced BOOLEAN NOT NULL DEFAULT true,
+        requested_model TEXT,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+
+      -- Indexes for time-windowed aggregation queries (DATA-02)
+      CREATE INDEX idx_cost_records_agent_created ON cost_records (agent_id, created_at);
+      CREATE INDEX idx_cost_records_created ON cost_records (created_at);
+      CREATE INDEX idx_cost_records_model ON cost_records (model);
+
+      -- Policy evaluation log table
+      CREATE TABLE IF NOT EXISTS policy_evaluations (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        agent_id TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        path TEXT NOT NULL,
+        allowed BOOLEAN NOT NULL,
+        evaluated_count INTEGER NOT NULL DEFAULT 0,
+        matched_count INTEGER NOT NULL DEFAULT 0,
+        denied_by TEXT,
+        denied_reason TEXT,
+        evaluation_time_ms REAL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+
+      CREATE INDEX idx_policy_evals_agent_created ON policy_evaluations (agent_id, created_at);
+      CREATE INDEX idx_policy_evals_created ON policy_evaluations (created_at);
+
+      -- Approval requests table (foundation for Plan 02)
+      CREATE TABLE IF NOT EXISTS approval_requests (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        agent_id TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT,
+        target_path TEXT NOT NULL,
+        policy_name TEXT NOT NULL,
+        policy_rule TEXT,
+        estimated_cost NUMERIC(12,8),
+        request_summary TEXT,
+        request_payload JSONB,
+        status TEXT NOT NULL DEFAULT 'pending'
+          CHECK (status IN ('pending', 'approved', 'denied', 'denied_timeout')),
+        decided_by TEXT,
+        decision_notes TEXT,
+        decided_at TIMESTAMPTZ,
+        timeout_seconds INTEGER NOT NULL DEFAULT 1800,
+        expires_at TIMESTAMPTZ NOT NULL,
+        approval_token UUID,
+        token_used BOOLEAN NOT NULL DEFAULT false,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+
+      CREATE INDEX idx_approvals_status ON approval_requests (status);
+      CREATE INDEX idx_approvals_agent_created ON approval_requests (agent_id, created_at);
+      CREATE INDEX idx_approvals_expires ON approval_requests (expires_at) WHERE status = 'pending';
+      CREATE INDEX idx_approvals_token ON approval_requests (approval_token) WHERE approval_token IS NOT NULL;
+
+      -- Daily cost summary table for retention aggregation
+      CREATE TABLE IF NOT EXISTS cost_daily_summary (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        agent_id TEXT NOT NULL,
+        model TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        date DATE NOT NULL,
+        total_requests INTEGER NOT NULL DEFAULT 0,
+        total_input_tokens BIGINT NOT NULL DEFAULT 0,
+        total_output_tokens BIGINT NOT NULL DEFAULT 0,
+        total_input_cost NUMERIC(12,8) NOT NULL DEFAULT 0,
+        total_output_cost NUMERIC(12,8) NOT NULL DEFAULT 0,
+        total_cost NUMERIC(12,8) NOT NULL DEFAULT 0,
+        UNIQUE (agent_id, model, provider, date)
+      );
+
+      CREATE INDEX idx_daily_summary_agent_date ON cost_daily_summary (agent_id, date);
+    `,
+    },
+    {
+        version: 2,
+        name: 'alert_tables',
+        sql: `
+      CREATE TABLE IF NOT EXISTS alert_rules (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        name TEXT NOT NULL,
+        type TEXT NOT NULL CHECK (type IN ('budget_threshold', 'policy_trigger')),
+        enabled BOOLEAN NOT NULL DEFAULT true,
+        config JSONB NOT NULL,
+        webhook_url TEXT NOT NULL,
+        cooldown_minutes INTEGER NOT NULL DEFAULT 60,
+        last_fired_at TIMESTAMPTZ,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+
+      CREATE INDEX idx_alert_rules_type ON alert_rules (type);
+      CREATE INDEX idx_alert_rules_enabled ON alert_rules (enabled) WHERE enabled = true;
+
+      CREATE TABLE IF NOT EXISTS alert_history (
+        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+        rule_id UUID NOT NULL REFERENCES alert_rules(id) ON DELETE CASCADE,
+        rule_name TEXT NOT NULL,
+        rule_type TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        event_payload JSONB NOT NULL,
+        webhook_url TEXT NOT NULL,
+        webhook_status INTEGER,
+        webhook_error TEXT,
+        fired_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      );
+
+      CREATE INDEX idx_alert_history_rule ON alert_history (rule_id, fired_at);
+      CREATE INDEX idx_alert_history_fired ON alert_history (fired_at);
+    `,
+    },
+    {
+        version: 3,
+        name: 'approval_request_binding',
+        sql: `
+      ALTER TABLE approval_requests
+        ADD COLUMN IF NOT EXISTS request_hash TEXT;
+
+      UPDATE approval_requests
+      SET request_hash = ''
+      WHERE request_hash IS NULL;
+
+      ALTER TABLE approval_requests
+        ALTER COLUMN request_hash SET NOT NULL;
+
+      CREATE INDEX IF NOT EXISTS idx_approvals_request_hash
+        ON approval_requests (request_hash);
+    `,
+    },
+];
+//# sourceMappingURL=db-schema.js.map

package/dist/db-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-schema.js","sourceRoot":"","sources":["../src/db-schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAgB;IACrC;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,gBAAgB;QACtB,GAAG,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6FJ;KACF;IACD;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,cAAc;QACpB,GAAG,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCJ;KACF;IACD;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,0BAA0B;QAChC,GAAG,EAAE;;;;;;;;;;;;;KAaJ;KACF;CACF,CAAC"}

package/dist/db-writer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Async database writer for the Govyn proxy.
+ *
+ * Writes cost records and policy evaluation results to PostgreSQL.
+ * All write methods are async and designed to be called fire-and-forget
+ * from the proxy hot path — zero added latency to request processing.
+ *
+ * Supports fail-open (log errors to stderr, continue proxying) and
+ * fail-closed (rethrow errors, reject requests) modes.
+ */
+import type postgres from 'postgres';
+import type { CostRecord } from './types.js';
+import type { PersistenceWriterStore, PolicyEvaluationRecord } from './persistence-types.js';
+/**
+ * DbWriter handles async persistence of cost records and policy evaluations
+ * to PostgreSQL. All writes are designed for fire-and-forget usage.
+ */
+export declare class DbWriter {
+    private failOpen;
+    private readonly store;
+    constructor(storeOrSql: PersistenceWriterStore | postgres.Sql, failOpen: boolean);
+    /**
+     * Write a cost record to the database.
+     * Fire-and-forget from the proxy hot path — never blocks response delivery.
+     *
+     * @param record - The cost record from the in-memory aggregator
+     */
+    writeCostRecord(record: CostRecord): Promise<void>;
+    /**
+     * Write a policy evaluation result to the database.
+     * Fire-and-forget from the proxy hot path.
+     *
+     * @param evalRecord - The policy evaluation data
+     */
+    writePolicyEvaluation(evalRecord: PolicyEvaluationRecord): Promise<void>;
+    /**
+     * Write an approval event to the database for audit trail logging.
+     * Fire-and-forget from the approval flow.
+     *
+     * @param event - The approval event data
+     */
+    writeApprovalEvent(event: {
+        requestId: string;
+        action: 'created' | 'approved' | 'denied' | 'denied_timeout' | 'token_consumed';
+        decidedBy?: string;
+        notes?: string;
+    }): Promise<void>;
+    /**
+     * Check if the database is currently available.
+     * Used by the approval flow (Plan 02) since approvals ALWAYS require DB.
+     *
+     * @returns true if DB responds to a simple query, false otherwise
+     */
+    isAvailable(): Promise<boolean>;
+}