@weave-kit/engine 0.1.0

package/dist/runtime/tunnel/registry.js

@@ -0,0 +1,167 @@
+import { Readable } from 'node:stream';
+import { fromB64 } from './framing.js';
+export class TunnelRegistry {
+    entries = new Map();
+    register(tunnelId, session) {
+        this.entries.get(tunnelId)?.session.close();
+        const entry = { session, waiters: new Map() };
+        this.entries.set(tunnelId, entry);
+        void this.readLoop(tunnelId, entry);
+    }
+    get(tunnelId) {
+        return this.entries.get(tunnelId)?.session;
+    }
+    has(tunnelId) {
+        return this.entries.has(tunnelId);
+    }
+    unregister(tunnelId, session) {
+        const entry = this.entries.get(tunnelId);
+        if (entry !== undefined && entry.session === session)
+            this.entries.delete(tunnelId);
+    }
+    /** Send one buffered request frame and resolve with the complete response. */
+    async request(tunnelId, frame) {
+        const entry = this.entries.get(tunnelId);
+        if (entry === undefined)
+            return { status: 503, headers: {}, body: JSON.stringify({ error: 'tunnel offline' }) };
+        return new Promise((resolve) => {
+            const chunks = [];
+            let status = 0;
+            let headers = {};
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            entry.waiters.set(frame.id, {
+                onStart(s, h) {
+                    status = s;
+                    headers = h;
+                },
+                onData(chunk) {
+                    chunks.push(chunk);
+                },
+                onEnd() {
+                    settle({ status, headers, body: Buffer.concat(chunks).toString('utf8') });
+                },
+                onError(message) {
+                    settle({ status: 502, headers: {}, body: JSON.stringify({ error: message }) });
+                },
+                onCancel() {
+                    settle({ status: 499, headers: {}, body: JSON.stringify({ error: 'cancelled' }) });
+                },
+            });
+            entry.session.write(frame);
+        });
+    }
+    /** Open a streaming (SSE) request: resolve on response-start with `{ response, abort }`. */
+    openStream(tunnelId, frame) {
+        const entry = this.entries.get(tunnelId);
+        if (entry === undefined) {
+            return Promise.reject(new Error('tunnel offline'));
+        }
+        return new Promise((resolve, reject) => {
+            let cleared = false;
+            const chunks = [];
+            let pushed = false;
+            const readable = new Readable({
+                read() {
+                    /* data pushed below */
+                },
+            });
+            const push = () => {
+                if (chunks.length > 0 && !cleared) {
+                    readable.push(Buffer.concat(chunks));
+                    chunks.length = 0;
+                    if (!readable.readableFlowing)
+                        readable.resume(); // keep the consumer flowing
+                }
+            };
+            const fail = (err) => {
+                if (!pushed)
+                    reject(err);
+                else
+                    readable.destroy(err);
+            };
+            entry.waiters.set(frame.id, {
+                onStart(s, h) {
+                    if (!pushed) {
+                        pushed = true;
+                        resolve({
+                            response: new Response(Readable.toWeb(readable), { status: s, headers: h }),
+                            abort: () => {
+                                entry.session.write({ kind: 'cancel', id: frame.id });
+                                readable.destroy();
+                            },
+                        });
+                    }
+                    push();
+                },
+                onData(chunk) {
+                    chunks.push(chunk);
+                    push();
+                },
+                onEnd() {
+                    cleared = true;
+                    readable.push(null);
+                },
+                onError(message) {
+                    fail(new Error(message));
+                },
+                onCancel() {
+                    cleared = true;
+                    readable.push(null);
+                },
+            });
+            entry.session.write(frame);
+        });
+    }
+    close(tunnelId) {
+        const entry = this.entries.get(tunnelId);
+        if (entry !== undefined) {
+            entry.session.close();
+            this.entries.delete(tunnelId);
+        }
+    }
+    closeAll() {
+        for (const [id, entry] of this.entries) {
+            entry.session.close();
+            this.entries.delete(id);
+        }
+    }
+    async readLoop(tunnelId, entry) {
+        try {
+            for (;;) {
+                const frame = await entry.session.read();
+                if (frame === null)
+                    break;
+                this.route(entry, frame);
+            }
+        }
+        finally {
+            for (const waiter of entry.waiters.values())
+                waiter.onEnd();
+            this.unregister(tunnelId, entry.session);
+        }
+    }
+    route(entry, frame) {
+        if (frame.kind === 'response-start' || frame.kind === 'data' || frame.kind === 'response-end' || frame.kind === 'error') {
+            const waiter = entry.waiters.get(frame.id);
+            if (waiter === undefined)
+                return;
+            if (frame.kind === 'response-start')
+                waiter.onStart(frame.status, frame.headers);
+            else if (frame.kind === 'data')
+                waiter.onData(fromB64(frame.data));
+            else if (frame.kind === 'error')
+                waiter.onError(frame.message);
+            else {
+                waiter.onEnd();
+                entry.waiters.delete(frame.id);
+            }
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/runtime/tunnel/registry.js.map

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

package/dist/runtime/tunnel/server.d.ts

@@ -0,0 +1,24 @@
+import type { TunnelRegistry } from './registry.js';
+/**
+ * Tunnel endpoint (P1, MIT): a node:http2 server the customer's `weave connect`
+ * agent dials OUT to. Each CONNECT stream authenticated by `(tunnel_id,
+ * pairing_token)` becomes a live {@link TunnelSession} registered in the
+ * {@link TunnelRegistry}, which the governance proxy forwarder then routes
+ * proxied requests over. The server accepts h2c (prior-knowledge) or TLS
+ * (`secure`), so it can live beside the governance engine or behind a TLS
+ * terminator.
+ */
+export interface TunnelServerDeps {
+    registry: TunnelRegistry;
+    /** validate a connector's `(tunnel_id, pairing_token)` before accepting. */
+    authenticate(tunnelId: string, token: string): Promise<boolean> | boolean;
+}
+export interface TunnelServerHandle {
+    listen(port: number, host?: string): Promise<number>;
+    address(): {
+        port: number;
+    };
+    close(): Promise<void>;
+}
+export declare function createTunnelServer(deps: TunnelServerDeps): TunnelServerHandle;
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/tunnel/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/runtime/tunnel/server.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;;;;GAQG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,4EAA4E;IAC5E,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC3E;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,OAAO,IAAI;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAYD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CA0D7E"}

package/dist/runtime/tunnel/server.js

@@ -0,0 +1,70 @@
+import { createServer } from 'node:http2';
+import { TunnelSession } from './framing.js';
+function bearerOf(authorization) {
+    const value = Array.isArray(authorization) ? authorization[0] : authorization;
+    if (value === undefined || !value.startsWith('Bearer '))
+        return undefined;
+    return value.slice('Bearer '.length);
+}
+function headerValue(header) {
+    return Array.isArray(header) ? header[0] : header;
+}
+export function createTunnelServer(deps) {
+    const server = createServer();
+    server.on('stream', (stream, headers) => {
+        void (async () => {
+            try {
+                if (headers[':method'] !== 'CONNECT') {
+                    stream.respond({ ':status': 405 });
+                    stream.end();
+                    return;
+                }
+                const tunnelId = headerValue(headers['x-weavekit-tunnel']);
+                const token = bearerOf(headers.authorization);
+                if (tunnelId === undefined || token === undefined) {
+                    stream.respond({ ':status': 401 });
+                    stream.end();
+                    return;
+                }
+                const ok = await deps.authenticate(tunnelId, token);
+                if (!ok) {
+                    stream.respond({ ':status': 403 });
+                    stream.end();
+                    return;
+                }
+                const session = new TunnelSession(stream);
+                deps.registry.register(tunnelId, session);
+                stream.respond({ ':status': 200 });
+                // the stream stays open; unregister the stale session when the peer drops
+                stream.on('close', () => deps.registry.unregister(tunnelId, session));
+            }
+            catch {
+                try {
+                    stream.respond({ ':status': 500 });
+                    stream.end();
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        })();
+    });
+    const portOf = () => {
+        const addr = server.address();
+        return typeof addr === 'object' && addr !== null ? addr.port : 0;
+    };
+    return {
+        listen(port, host = '127.0.0.1') {
+            return new Promise((resolve) => {
+                server.listen(port, host, () => resolve(portOf()));
+            });
+        },
+        address() {
+            return { port: portOf() };
+        },
+        close() {
+            return new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/runtime/tunnel/server.js.map

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

package/dist/subsystems/approvals/index.d.ts

@@ -0,0 +1,11 @@
+import type { Pool } from 'pg';
+import type { ApprovalsBackend } from '../../core/tools/index.js';
+export { createApprovalsPgStore, ensureApprovalsTable } from './store.js';
+export type { ApprovalListFilter, ApprovalStatus, ApprovalsBackend, PendingApproval } from '../../core/tools/index.js';
+/**
+ * Create the PG-backed `ApprovalsBackend` (D1 release default) and ensure the
+ * `weavekit_approvals` table exists. Injected into the tool executor by the
+ * engine assembly layer (P3). No Redis backend is implemented.
+ */
+export declare function createApprovalsBackend(pool: Pool): Promise<ApprovalsBackend>;
+//# sourceMappingURL=index.d.ts.map

package/dist/subsystems/approvals/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/subsystems/approvals/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEvH;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAGlF"}

package/dist/subsystems/approvals/index.js

@@ -0,0 +1,12 @@
+import { createApprovalsPgStore, ensureApprovalsTable } from './store.js';
+export { createApprovalsPgStore, ensureApprovalsTable } from './store.js';
+/**
+ * Create the PG-backed `ApprovalsBackend` (D1 release default) and ensure the
+ * `weavekit_approvals` table exists. Injected into the tool executor by the
+ * engine assembly layer (P3). No Redis backend is implemented.
+ */
+export async function createApprovalsBackend(pool) {
+    await ensureApprovalsTable(pool);
+    return createApprovalsPgStore(pool);
+}
+//# sourceMappingURL=index.js.map

package/dist/subsystems/approvals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/subsystems/approvals/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAAU;IACrD,MAAM,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/subsystems/approvals/store.d.ts

@@ -0,0 +1,12 @@
+import type { Pool } from 'pg';
+import type { ApprovalsBackend } from '../../core/tools/index.js';
+/** idempotent table creation + indexes (append-query-friendly: status+created, actor) */
+export declare function ensureApprovalsTable(pool: Pool): Promise<void>;
+/**
+ * Postgres `ApprovalsBackend` (D1 release default; the engine's mandated DB).
+ * Parameterized, whitelisted sort, idempotent upsert (deterministic key → a
+ * resolved decision is never resurrected by a re-pending). Mirrors
+ * `subsystems/audit` conventions (pool-injected, no adapters).
+ */
+export declare function createApprovalsPgStore(pool: Pool): ApprovalsBackend;
+//# sourceMappingURL=store.d.ts.map

package/dist/subsystems/approvals/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/subsystems/approvals/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAsC,gBAAgB,EAAmB,MAAM,2BAA2B,CAAC;AAIvH,yFAAyF;AACzF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAepE;AAkED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CA4CnE"}

package/dist/subsystems/approvals/store.js

@@ -0,0 +1,108 @@
+const TABLE = 'weavekit_approvals';
+/** idempotent table creation + indexes (append-query-friendly: status+created, actor) */
+export async function ensureApprovalsTable(pool) {
+    await pool.query(`CREATE TABLE IF NOT EXISTS ${TABLE} (
+       approval_key text PRIMARY KEY,
+       action       text NOT NULL,
+       args         jsonb NOT NULL,
+       actor_key    text NOT NULL,
+       status       text NOT NULL,
+       created_at   timestamptz NOT NULL DEFAULT now(),
+       approved_by  text,
+       resolved_at  timestamptz
+     )`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS ${TABLE}_status_created_idx ON ${TABLE} (status, created_at DESC)`);
+    await pool.query(`CREATE INDEX IF NOT EXISTS ${TABLE}_actor_idx ON ${TABLE} (actor_key)`);
+}
+function toApproval(row) {
+    return {
+        approvalKey: row.approval_key,
+        action: row.action,
+        args: (row.args ?? {}),
+        status: row.status,
+        createdAt: new Date(row.created_at),
+        actorKey: row.actor_key,
+        approvedBy: row.approved_by ?? undefined,
+    };
+}
+/** sort field whitelist (never interpolate raw input into SQL) */
+const SORT_COLUMNS = {
+    createdAt: 'created_at',
+    action: 'action',
+    actorKey: 'actor_key',
+    status: 'status',
+    approvalKey: 'approval_key',
+};
+function buildColumns(read) {
+    return read === 'all'
+        ? 'approval_key, action, args, actor_key, status, created_at, approved_by'
+        : 'approval_key, action, args, actor_key, status, created_at, approved_by';
+}
+function buildWhere(filter) {
+    const clauses = [];
+    const params = [];
+    const push = (clause, value) => {
+        params.push(value);
+        clauses.push(clause.replace('?', `$${params.length}`));
+    };
+    if (filter.status !== undefined)
+        push('status = ?', filter.status);
+    if (filter.action !== undefined)
+        push('action = ?', filter.action);
+    if (filter.actorKey !== undefined)
+        push('actor_key = ?', filter.actorKey);
+    if (filter.from !== undefined)
+        push('created_at >= ?', filter.from);
+    if (filter.to !== undefined)
+        push('created_at <= ?', filter.to);
+    return { sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`, params };
+}
+function buildOrder(filter) {
+    const key = filter.sort?.field ?? 'createdAt';
+    const column = SORT_COLUMNS[key] ?? SORT_COLUMNS.createdAt;
+    const order = filter.sort?.order === 'ASC' ? 'ASC' : 'DESC';
+    return ` ORDER BY ${column} ${order}`;
+}
+/**
+ * Postgres `ApprovalsBackend` (D1 release default; the engine's mandated DB).
+ * Parameterized, whitelisted sort, idempotent upsert (deterministic key → a
+ * resolved decision is never resurrected by a re-pending). Mirrors
+ * `subsystems/audit` conventions (pool-injected, no adapters).
+ */
+export function createApprovalsPgStore(pool) {
+    return {
+        async list(filter = {}) {
+            const where = buildWhere(filter);
+            const offset = filter.offset ?? 0;
+            const limit = filter.limit ?? 100;
+            const result = await pool.query(`SELECT ${buildColumns('all')}
+         FROM ${TABLE}${where.sql}${buildOrder(filter)}
+         LIMIT $${where.params.length + 1} OFFSET $${where.params.length + 2}`, [...where.params, limit, offset]);
+            return result.rows.map((row) => toApproval(row));
+        },
+        async get(approvalKey) {
+            const result = await pool.query(`SELECT ${buildColumns('all')} FROM ${TABLE} WHERE approval_key = $1`, [
+                approvalKey,
+            ]);
+            const row = result.rows[0];
+            return row === undefined ? undefined : toApproval(row);
+        },
+        async upsert(entry) {
+            await pool.query(`INSERT INTO ${TABLE} (approval_key, action, args, actor_key, status, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         ON CONFLICT (approval_key) DO NOTHING`, [entry.approvalKey, entry.action, JSON.stringify(entry.args), entry.actorKey, entry.status, entry.createdAt]);
+        },
+        async resolve(approvalKey, by, status) {
+            const result = await pool.query(`UPDATE ${TABLE}
+         SET status = $2, approved_by = $3, resolved_at = now()
+         WHERE approval_key = $1 AND status = 'pending'`, [approvalKey, status, by]);
+            return (result.rowCount ?? 0) > 0;
+        },
+        async count(filter = {}) {
+            const where = buildWhere(filter);
+            const result = await pool.query(`SELECT count(*)::int AS n FROM ${TABLE}${where.sql}`, where.params);
+            return result.rows[0]?.n ?? 0;
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/subsystems/approvals/store.js.map

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

package/dist/subsystems/audit/index.d.ts

@@ -0,0 +1,37 @@
+import type { Pool } from 'pg';
+import type { AuditEvent, AuditSink } from '../../core/audit/index.js';
+import type { AuditQuery, AuditQueryResult } from './store.js';
+export { AUDIT_ACTOR_TYPES, DATA_ACTIONS, NOOP_AUDIT_SINK } from '../../core/audit/index.js';
+export type { AuditActorType, AuditEvent, AuditFilter, AuditSink, DataAction } from '../../core/audit/index.js';
+export type { AuditQuery, AuditQueryResult } from './store.js';
+/** audit engine: storage (single/batch insert) + query + lifecycle */
+export interface AuditEngine extends AuditSink {
+    record(event: AuditEvent): Promise<void>;
+    recordBatch(events: AuditEvent[]): Promise<void>;
+    query(filter?: AuditQuery): Promise<AuditQueryResult>;
+    /** flush any buffered events (no-op for the raw store) and release resources */
+    close(): Promise<void>;
+}
+/** create the PG-backed audit engine (idempotent table creation) */
+export declare function createAudit(pool: Pool): Promise<AuditEngine>;
+export interface BufferedSinkOptions {
+    /** events per batch; defaults to 50 */
+    batchSize?: number;
+    /** max time between flushes; defaults to 100ms */
+    flushMs?: number;
+    /** batch-write failure callback (default console.error) — never throws into the caller */
+    onError?: (error: Error) => void;
+}
+/**
+ * L1 process-local buffered audit sink (fire-and-forget): `record()` queues
+ * and returns immediately — audit never blocks the business critical path.
+ * Events are flushed as a single multi-row INSERT when the batch fills or the
+ * flush window elapses. `flush()` drains the queue (used by engine.close()).
+ *
+ * Upgrade path: replace `inner` with a Redis producer / S3 writer later —
+ * callers of `record()` are unchanged.
+ */
+export declare function createBufferedAuditSink(inner: AuditSink, options?: BufferedSinkOptions): AuditSink & {
+    flush(): Promise<void>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/subsystems/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/subsystems/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEvE,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC7F,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAChH,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE/D,sEAAsE;AACtE,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,KAAK,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtD,gFAAgF;IAChF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,oEAAoE;AACpE,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBlE;AAED,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAKD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,mBAAwB,GAChC,SAAS,GAAG;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA8FxC"}

package/dist/subsystems/audit/index.js

@@ -0,0 +1,125 @@
+import { ensureAuditTable, insertAudit, insertAuditBatch, queryAudit } from './store.js';
+export { AUDIT_ACTOR_TYPES, DATA_ACTIONS, NOOP_AUDIT_SINK } from '../../core/audit/index.js';
+/** create the PG-backed audit engine (idempotent table creation) */
+export async function createAudit(pool) {
+    await ensureAuditTable(pool);
+    return {
+        async record(event) {
+            await insertAudit(pool, event);
+        },
+        async recordBatch(events) {
+            await insertAuditBatch(pool, events);
+        },
+        async query(filter) {
+            return queryAudit(pool, filter);
+        },
+        async close() {
+            // raw store has no buffer
+        },
+    };
+}
+/** hard cap on retained events when the sink is unreachable — above this the oldest are dropped + reported (prevents OOM) */
+const MAX_BUFFERED_EVENTS = 10_000;
+/**
+ * L1 process-local buffered audit sink (fire-and-forget): `record()` queues
+ * and returns immediately — audit never blocks the business critical path.
+ * Events are flushed as a single multi-row INSERT when the batch fills or the
+ * flush window elapses. `flush()` drains the queue (used by engine.close()).
+ *
+ * Upgrade path: replace `inner` with a Redis producer / S3 writer later —
+ * callers of `record()` are unchanged.
+ */
+export function createBufferedAuditSink(inner, options = {}) {
+    const batchSize = options.batchSize ?? 50;
+    const flushMs = options.flushMs ?? 100;
+    const onError = options.onError ?? ((error) => console.error('audit flush failed:', error.message));
+    let buffer = [];
+    let timer;
+    let flushing;
+    let closed = false;
+    async function flushNow() {
+        const events = buffer;
+        buffer = [];
+        if (events.length === 0)
+            return;
+        try {
+            if (inner.recordBatch !== undefined) {
+                await inner.recordBatch(events);
+            }
+            else {
+                for (const event of events)
+                    await inner.record(event);
+            }
+        }
+        catch (error) {
+            // requeue the batch and let the next flush window retry — audit is
+            // best-effort but must not be lossy on a transient DB/network failure.
+            // If the sink stays down the buffer grows; a hard cap prevents OOM and
+            // reports through onError instead of silently dropping events.
+            buffer.unshift(...events);
+            if (buffer.length > MAX_BUFFERED_EVENTS) {
+                const dropped = buffer.splice(MAX_BUFFERED_EVENTS);
+                onError(new Error(`audit buffer overflow: dropped ${dropped.length} events (sink unreachable — last: ${error instanceof Error ? error.message : String(error)})`));
+            }
+            else {
+                onError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+    }
+    /** serialized flush: wait for an in-flight flush, then drain the queue */
+    async function runFlush() {
+        if (flushing !== undefined) {
+            await flushing;
+        }
+        else {
+            flushing = flushNow().finally(() => {
+                flushing = undefined;
+            });
+            await flushing;
+        }
+        if (buffer.length > 0)
+            schedule();
+    }
+    function schedule() {
+        if (closed || timer !== undefined || flushing !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void runFlush();
+        }, flushMs);
+        // a retry timer must never keep the process alive (audit is best-effort):
+        // if the sink stays down and the app is shutting down, the buffered events
+        // are dropped on process exit and reported through onError at the last flush
+        timer.unref?.();
+    }
+    function enqueue(events) {
+        if (closed)
+            return;
+        buffer.push(...events);
+        if (buffer.length >= batchSize) {
+            void runFlush();
+        }
+        else {
+            schedule();
+        }
+    }
+    return {
+        async record(event) {
+            enqueue([event]);
+        },
+        async recordBatch(events) {
+            enqueue(events);
+        },
+        async flush() {
+            // stop accepting/rescheduling after the final drain — a late flush must
+            // never run against a pool that engine.close() has already ended
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            await runFlush();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/subsystems/audit/index.js.map

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

package/dist/subsystems/audit/store.d.ts

@@ -0,0 +1,12 @@
+import type { Pool } from 'pg';
+import type { AuditEvent, AuditQuery, AuditQueryResult } from '../../core/audit/index.js';
+export type { AuditQuery, AuditQueryResult } from '../../core/audit/index.js';
+/** create the append-only audit table (idempotent); `before`/`after` columns are always present (M10 D7 — replay only decides whether they are filled, so toggling the switch needs no migration) */
+export declare function ensureAuditTable(pool: Pool): Promise<void>;
+/** single append-only insert (writes the event's own timestamp — the audit is time-anchored to the business moment) */
+export declare function insertAudit(pool: Pool, event: AuditEvent): Promise<void>;
+/** batch append-only insert (single multi-row statement, one transaction) */
+export declare function insertAuditBatch(pool: Pool, events: AuditEvent[]): Promise<void>;
+/** parameterized query over the audit trail */
+export declare function queryAudit(pool: Pool, query?: AuditQuery): Promise<AuditQueryResult>;
+//# sourceMappingURL=store.d.ts.map

package/dist/subsystems/audit/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/subsystems/audit/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG1F,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAgB9E,qMAAqM;AACrM,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhE;AAED,uHAAuH;AACvH,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB9E;AAED,6EAA6E;AAC7E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBtF;AA0GD,+CAA+C;AAC/C,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2C9F"}