@emilia-protocol/gate 0.10.0 → 0.13.0

package/dist/siem.d.ts

@@ -0,0 +1,261 @@
+/**
+ * EMILIA Gate — SIEM export of the evidence log (EP-GATE-SIEM-EXPORT-v1).
+ *
+ * Gate decisions must land where the SOC already looks: Splunk, Sentinel,
+ * Datadog. Two static, offline mappings over evidence-log entries:
+ *   - OCSF (JSON object) for OCSF-native pipelines (Amazon Security Lake,
+ *     Splunk CIM-OCSF, Sentinel ASIM ingestion);
+ *   - CEF (single line) as the lowest-common-denominator syslog fallback.
+ * Pure functions: entry in, event out — no network, no wall clock. Every
+ * timestamp in the output comes from the entry itself, so a fixed entry maps
+ * to a byte-identical event on every call and every host.
+ *
+ * OCSF class choice — class_uid 6003 (API Activity, category 6 Application
+ * Activity). The gate is a policy-enforcement point in front of a tool/API
+ * call: each evidence entry is one attempted API operation with an
+ * allow/deny (or executed/failed) disposition, which is exactly what 6003
+ * models via status_id. The IAM alternatives fit worse: 3003 Authorize
+ * Session models session-privilege grants (no deny activity), and 6004 Web
+ * Resource Access Activity is deprecated in current OCSF.
+ *
+ * Mapping table (evidence entry → OCSF 6003):
+ *   entry.at (ISO)          → time (epoch ms; 0 sentinel if unparseable)
+ *   entry.kind              → activity_name ('decision'|'execution'), activity_id 99 (Other)
+ *   entry.action            → api.operation
+ *   entry.allow / outcome   → status_id 1 Success / 2 Failure (+ status)
+ *   entry.reason / outcome  → status_detail
+ *   entry.subject           → actor.user.uid
+ *   entry.receipt_id        → metadata.correlation_uid
+ *   entry.hash              → metadata.uid (ties the event to the evidence chain)
+ *   allow                   → severity_id 1 Informational; refuse/fail → 3 Medium
+ *   required_tier, selector, seq, prev_hash → unmapped.* (no OCSF slot)
+ *
+ * A malformed entry NEVER throws out of the mappers: it becomes a structured
+ * error event (status Failure, status_detail 'malformed_evidence_entry') so
+ * the corruption itself is visible in the SIEM instead of silently dropped.
+ */
+export declare const SIEM_EXPORT_VERSION = "EP-GATE-SIEM-EXPORT-v1";
+export declare const SIEM_OCSF_CLASS_UID = 6003;
+/**
+ * Map an evidence-log entry to an OCSF API Activity (6003) event object.
+ * Static and deterministic: same entry, same object, always. Malformed input
+ * yields a structured error event rather than throwing (see module doc).
+ * @param {object} entry  one record from evidence.all()
+ * @returns {object} OCSF-shaped event
+ */
+export declare function toOCSF(entry: any): {
+    activity_id: number;
+    activity_name: string;
+    category_uid: number;
+    category_name: string;
+    class_uid: number;
+    class_name: string;
+    type_uid: number;
+    time: number;
+    severity_id: number;
+    severity: string;
+    status_id: number;
+    status: string;
+    status_detail: string;
+    metadata: {
+        version: string;
+        log_name: string;
+        product: {
+            name: string;
+            vendor_name: string;
+        };
+        uid: null;
+        correlation_uid: null;
+    };
+    actor: {
+        user: {
+            uid: null;
+        };
+    };
+    api: {
+        operation: null;
+    };
+    unmapped: {
+        error: string;
+        entry_preview: any;
+        kind?: undefined;
+        required_tier?: undefined;
+        selector?: undefined;
+        evidence_seq?: undefined;
+        prev_hash?: undefined;
+    };
+} | {
+    activity_id: number;
+    activity_name: string | undefined;
+    category_uid: number;
+    category_name: string;
+    class_uid: number;
+    class_name: string;
+    type_uid: number;
+    time: number | undefined;
+    severity_id: number;
+    severity: string;
+    status_id: number;
+    status: string;
+    status_detail: any;
+    metadata: {
+        version: string;
+        log_name: string;
+        product: {
+            name: string;
+            vendor_name: string;
+        };
+        uid: any;
+        correlation_uid: any;
+    };
+    actor: {
+        user: {
+            uid: any;
+        };
+    };
+    api: {
+        operation: any;
+    };
+    unmapped: {
+        kind: string | undefined;
+        required_tier: any;
+        selector: any;
+        evidence_seq: any;
+        prev_hash: any;
+        error?: undefined;
+        entry_preview?: undefined;
+    };
+};
+/**
+ * Map an evidence-log entry to a one-line CEF string (syslog fallback for
+ * SIEMs without OCSF ingestion). Same determinism and malformed-input
+ * contract as toOCSF.
+ * @param {object} entry  one record from evidence.all()
+ * @returns {string} `CEF:0|...` single line
+ */
+export declare function toCEF(entry: any): string;
+/**
+ * Create a forwarder that ships evidence entries to a SIEM sink.
+ *
+ * INVARIANT: SIEM export must NEVER block or crash enforcement. The gate path
+ * calls forward() fire-and-forget; a sink that throws, rejects, or is down is
+ * recorded on the internal `dropped` counter (exposed via stats()) and NOTHING
+ * propagates back to the caller — forward() always resolves, never rejects.
+ * This is the inverse of the evidence log's strict mode: the evidence log is
+ * the authoritative record and fails closed; the SIEM copy is telemetry and
+ * fails open, silently, with an auditable drop count.
+ *
+ * Configuration errors (unknown format, missing sink) DO throw — at
+ * construction time, before anything is on the gate path.
+ *
+ * @param {object} [o]
+ * @param {'ocsf'|'cef'} [o.format='ocsf']
+ * @param {function} [o.sink]  receives the mapped event (object for ocsf, string for cef); may be async
+ * @returns {{ forward(entry): Promise<{delivered:boolean, event:object|string|null}>, stats(): object }}
+ */
+export declare function createSiemForwarder({ format, sink }?: {
+    format?: 'ocsf' | 'cef';
+    sink?: (event: any) => any;
+}): {
+    forward: (entry: any) => Promise<{
+        delivered: boolean;
+        event: string | {
+            activity_id: number;
+            activity_name: string;
+            category_uid: number;
+            category_name: string;
+            class_uid: number;
+            class_name: string;
+            type_uid: number;
+            time: number;
+            severity_id: number;
+            severity: string;
+            status_id: number;
+            status: string;
+            status_detail: string;
+            metadata: {
+                version: string;
+                log_name: string;
+                product: {
+                    name: string;
+                    vendor_name: string;
+                };
+                uid: null;
+                correlation_uid: null;
+            };
+            actor: {
+                user: {
+                    uid: null;
+                };
+            };
+            api: {
+                operation: null;
+            };
+            unmapped: {
+                error: string;
+                entry_preview: any;
+                kind?: undefined;
+                required_tier?: undefined;
+                selector?: undefined;
+                evidence_seq?: undefined;
+                prev_hash?: undefined;
+            };
+        } | {
+            activity_id: number;
+            activity_name: string | undefined;
+            category_uid: number;
+            category_name: string;
+            class_uid: number;
+            class_name: string;
+            type_uid: number;
+            time: number | undefined;
+            severity_id: number;
+            severity: string;
+            status_id: number;
+            status: string;
+            status_detail: any;
+            metadata: {
+                version: string;
+                log_name: string;
+                product: {
+                    name: string;
+                    vendor_name: string;
+                };
+                uid: any;
+                correlation_uid: any;
+            };
+            actor: {
+                user: {
+                    uid: any;
+                };
+            };
+            api: {
+                operation: any;
+            };
+            unmapped: {
+                kind: string | undefined;
+                required_tier: any;
+                selector: any;
+                evidence_seq: any;
+                prev_hash: any;
+                error?: undefined;
+                entry_preview?: undefined;
+            };
+        } | null;
+    }>;
+    stats: () => {
+        format: "ocsf" | "cef";
+        forwarded: number;
+        dropped: number;
+        malformed: number;
+    };
+};
+declare const _default: {
+    SIEM_EXPORT_VERSION: string;
+    SIEM_OCSF_CLASS_UID: number;
+    toOCSF: typeof toOCSF;
+    toCEF: typeof toCEF;
+    createSiemForwarder: typeof createSiemForwarder;
+};
+export default _default;
+//# sourceMappingURL=siem.d.ts.map

package/dist/siem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"siem.d.ts","sourceRoot":"","sources":["../src/siem.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAkCxC;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwD3B;AAYD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,KAAA,UA2B1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,MAAe,EAAE,IAAI,EAAE,GAAE;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;CACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsCL;;;;;;;;AAED,wBAAgG"}

package/dist/siem.js

@@ -0,0 +1,247 @@
+// @ts-nocheck
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EMILIA Gate — SIEM export of the evidence log (EP-GATE-SIEM-EXPORT-v1).
+ *
+ * Gate decisions must land where the SOC already looks: Splunk, Sentinel,
+ * Datadog. Two static, offline mappings over evidence-log entries:
+ *   - OCSF (JSON object) for OCSF-native pipelines (Amazon Security Lake,
+ *     Splunk CIM-OCSF, Sentinel ASIM ingestion);
+ *   - CEF (single line) as the lowest-common-denominator syslog fallback.
+ * Pure functions: entry in, event out — no network, no wall clock. Every
+ * timestamp in the output comes from the entry itself, so a fixed entry maps
+ * to a byte-identical event on every call and every host.
+ *
+ * OCSF class choice — class_uid 6003 (API Activity, category 6 Application
+ * Activity). The gate is a policy-enforcement point in front of a tool/API
+ * call: each evidence entry is one attempted API operation with an
+ * allow/deny (or executed/failed) disposition, which is exactly what 6003
+ * models via status_id. The IAM alternatives fit worse: 3003 Authorize
+ * Session models session-privilege grants (no deny activity), and 6004 Web
+ * Resource Access Activity is deprecated in current OCSF.
+ *
+ * Mapping table (evidence entry → OCSF 6003):
+ *   entry.at (ISO)          → time (epoch ms; 0 sentinel if unparseable)
+ *   entry.kind              → activity_name ('decision'|'execution'), activity_id 99 (Other)
+ *   entry.action            → api.operation
+ *   entry.allow / outcome   → status_id 1 Success / 2 Failure (+ status)
+ *   entry.reason / outcome  → status_detail
+ *   entry.subject           → actor.user.uid
+ *   entry.receipt_id        → metadata.correlation_uid
+ *   entry.hash              → metadata.uid (ties the event to the evidence chain)
+ *   allow                   → severity_id 1 Informational; refuse/fail → 3 Medium
+ *   required_tier, selector, seq, prev_hash → unmapped.* (no OCSF slot)
+ *
+ * A malformed entry NEVER throws out of the mappers: it becomes a structured
+ * error event (status Failure, status_detail 'malformed_evidence_entry') so
+ * the corruption itself is visible in the SIEM instead of silently dropped.
+ */
+export const SIEM_EXPORT_VERSION = 'EP-GATE-SIEM-EXPORT-v1';
+export const SIEM_OCSF_CLASS_UID = 6003; // API Activity
+const OCSF_SCHEMA_VERSION = '1.1.0';
+const CATEGORY_UID = 6; // Application Activity
+const PRODUCT = { name: 'EMILIA Gate', vendor_name: 'Emilia Protocol' };
+const PREVIEW_MAX = 256;
+/**
+ * Shape-check an evidence entry and derive the disposition. An entry is
+ * mappable only if it carries a parseable timestamp AND a verdict (a decision's
+ * `allow` boolean or an execution's `outcome` string) — anything else is
+ * treated as malformed and surfaced as an error event, never a throw.
+ */
+function classifyEntry(entry) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return { valid: false };
+    const timeMs = typeof entry.at === 'string' ? Date.parse(entry.at) : NaN;
+    const hasVerdict = typeof entry.allow === 'boolean' || typeof entry.outcome === 'string';
+    if (!Number.isFinite(timeMs) || !hasVerdict)
+        return { valid: false };
+    const kind = entry.kind === 'execution' ? 'execution' : 'decision';
+    const success = typeof entry.allow === 'boolean' ? entry.allow === true : entry.outcome === 'executed';
+    return { valid: true, kind, success, timeMs };
+}
+/** Bounded, throw-proof rendering of an unmappable entry for the error event. */
+function safePreview(entry) {
+    let s;
+    try {
+        s = typeof entry === 'string' ? entry : JSON.stringify(entry);
+    }
+    catch {
+        s = '[unserializable]';
+    }
+    if (s == null)
+        s = String(entry);
+    return s.replace(/[\r\n]+/g, ' ').slice(0, PREVIEW_MAX);
+}
+/**
+ * Map an evidence-log entry to an OCSF API Activity (6003) event object.
+ * Static and deterministic: same entry, same object, always. Malformed input
+ * yields a structured error event rather than throwing (see module doc).
+ * @param {object} entry  one record from evidence.all()
+ * @returns {object} OCSF-shaped event
+ */
+export function toOCSF(entry) {
+    const c = classifyEntry(entry);
+    if (!c.valid) {
+        return {
+            activity_id: 0,
+            activity_name: 'Unknown',
+            category_uid: CATEGORY_UID,
+            category_name: 'Application Activity',
+            class_uid: SIEM_OCSF_CLASS_UID,
+            class_name: 'API Activity',
+            type_uid: SIEM_OCSF_CLASS_UID * 100 + 0,
+            // No trustworthy timestamp inside the entry; 0 sentinel, never the wall
+            // clock — the mapping stays pure and the bad entry stays evident.
+            time: 0,
+            severity_id: 3,
+            severity: 'Medium',
+            status_id: 2,
+            status: 'Failure',
+            status_detail: 'malformed_evidence_entry',
+            metadata: { version: OCSF_SCHEMA_VERSION, log_name: SIEM_EXPORT_VERSION, product: PRODUCT, uid: null, correlation_uid: null },
+            actor: { user: { uid: null } },
+            api: { operation: null },
+            unmapped: { error: 'malformed_evidence_entry', entry_preview: safePreview(entry) },
+        };
+    }
+    return {
+        activity_id: 99,
+        activity_name: c.kind,
+        category_uid: CATEGORY_UID,
+        category_name: 'Application Activity',
+        class_uid: SIEM_OCSF_CLASS_UID,
+        class_name: 'API Activity',
+        type_uid: SIEM_OCSF_CLASS_UID * 100 + 99,
+        time: c.timeMs,
+        severity_id: c.success ? 1 : 3,
+        severity: c.success ? 'Informational' : 'Medium',
+        status_id: c.success ? 1 : 2,
+        status: c.success ? 'Success' : 'Failure',
+        status_detail: entry.reason ?? entry.outcome ?? null,
+        metadata: {
+            version: OCSF_SCHEMA_VERSION,
+            log_name: SIEM_EXPORT_VERSION,
+            product: PRODUCT,
+            uid: entry.hash ?? null,
+            correlation_uid: entry.receipt_id ?? null,
+        },
+        actor: { user: { uid: entry.subject ?? null } },
+        api: { operation: entry.action ?? null },
+        unmapped: {
+            kind: c.kind,
+            required_tier: entry.required_tier ?? null,
+            selector: entry.selector ?? null,
+            evidence_seq: Number.isFinite(entry.seq) ? entry.seq : null,
+            prev_hash: entry.prev_hash ?? null,
+        },
+    };
+}
+// CEF escaping per the ArcSight CEF spec: prefix fields escape backslash and
+// pipe; extension values escape backslash and equals. Newlines are collapsed
+// in both — a CEF record is one line, always.
+function escPrefix(v) {
+    return String(v).replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+}
+function escExt(v) {
+    return String(v).replace(/\\/g, '\\\\').replace(/=/g, '\\=').replace(/[\r\n]+/g, ' ');
+}
+/**
+ * Map an evidence-log entry to a one-line CEF string (syslog fallback for
+ * SIEMs without OCSF ingestion). Same determinism and malformed-input
+ * contract as toOCSF.
+ * @param {object} entry  one record from evidence.all()
+ * @returns {string} `CEF:0|...` single line
+ */
+export function toCEF(entry) {
+    const c = classifyEntry(entry);
+    if (!c.valid) {
+        const ext = [
+            'act=error',
+            'outcome=malformed_evidence_entry',
+            `msg=${escExt(safePreview(entry))}`,
+            `cs4=${escExt(SIEM_EXPORT_VERSION)}`, 'cs4Label=export_version',
+        ].join(' ');
+        return `CEF:0|EmiliaProtocol|Gate|1|gate.malformed|malformed evidence entry|5|${ext}`;
+    }
+    const verdictWord = c.kind === 'execution'
+        ? (c.success ? 'executed' : 'failed')
+        : (c.success ? 'allowed' : 'refused');
+    const signatureId = `gate.${c.kind}.${c.success ? 'allow' : 'deny'}`;
+    const name = `${entry.action ?? 'unknown_action'} ${verdictWord}`;
+    const severity = c.success ? 3 : 7;
+    const ext = [`end=${c.timeMs}`, `act=${c.success ? 'allow' : 'deny'}`];
+    const reason = entry.reason ?? entry.outcome;
+    if (reason != null)
+        ext.push(`outcome=${escExt(reason)}`);
+    if (entry.subject != null)
+        ext.push(`suser=${escExt(entry.subject)}`);
+    if (entry.receipt_id != null)
+        ext.push(`cs1=${escExt(entry.receipt_id)}`, 'cs1Label=receipt_id');
+    if (entry.hash != null)
+        ext.push(`cs2=${escExt(entry.hash)}`, 'cs2Label=evidence_hash');
+    if (entry.required_tier != null)
+        ext.push(`cs3=${escExt(entry.required_tier)}`, 'cs3Label=required_tier');
+    ext.push(`cs4=${escExt(SIEM_EXPORT_VERSION)}`, 'cs4Label=export_version');
+    if (Number.isFinite(entry.seq))
+        ext.push(`cn1=${entry.seq}`, 'cn1Label=evidence_seq');
+    return `CEF:0|EmiliaProtocol|Gate|1|${escPrefix(signatureId)}|${escPrefix(name)}|${severity}|${ext.join(' ')}`;
+}
+/**
+ * Create a forwarder that ships evidence entries to a SIEM sink.
+ *
+ * INVARIANT: SIEM export must NEVER block or crash enforcement. The gate path
+ * calls forward() fire-and-forget; a sink that throws, rejects, or is down is
+ * recorded on the internal `dropped` counter (exposed via stats()) and NOTHING
+ * propagates back to the caller — forward() always resolves, never rejects.
+ * This is the inverse of the evidence log's strict mode: the evidence log is
+ * the authoritative record and fails closed; the SIEM copy is telemetry and
+ * fails open, silently, with an auditable drop count.
+ *
+ * Configuration errors (unknown format, missing sink) DO throw — at
+ * construction time, before anything is on the gate path.
+ *
+ * @param {object} [o]
+ * @param {'ocsf'|'cef'} [o.format='ocsf']
+ * @param {function} [o.sink]  receives the mapped event (object for ocsf, string for cef); may be async
+ * @returns {{ forward(entry): Promise<{delivered:boolean, event:object|string|null}>, stats(): object }}
+ */
+export function createSiemForwarder({ format = 'ocsf', sink } = {}) {
+    if (format !== 'ocsf' && format !== 'cef') {
+        throw new Error(`EMILIA Gate SIEM: unknown format "${format}" (expected 'ocsf' or 'cef')`);
+    }
+    if (typeof sink !== 'function') {
+        throw new Error('EMILIA Gate SIEM: a sink function is required');
+    }
+    // Rebind to a locally-scoped const: `sink` the parameter is typed
+    // `function|undefined` (it's optional in the JSDoc signature above), and
+    // that widened type is what closures below would otherwise capture even
+    // though the throw guard just proved it's a function for the lifetime of
+    // this forwarder. No behavior change, just handing the closure the type
+    // the guard already guarantees.
+    /** @type {function} */
+    const sinkFn = sink;
+    const counts = { forwarded: 0, dropped: 0, malformed: 0 };
+    async function forward(entry) {
+        let event = null;
+        try {
+            if (!classifyEntry(entry).valid)
+                counts.malformed += 1;
+            event = format === 'cef' ? toCEF(entry) : toOCSF(entry);
+            await sinkFn(event);
+            counts.forwarded += 1;
+            return { delivered: true, event };
+        }
+        catch {
+            // Sink failure (or any unexpected mapper failure): counted, never
+            // propagated — enforcement must not depend on SIEM availability.
+            counts.dropped += 1;
+            return { delivered: false, event };
+        }
+    }
+    function stats() {
+        return { format, forwarded: counts.forwarded, dropped: counts.dropped, malformed: counts.malformed };
+    }
+    return { forward, stats };
+}
+export default { SIEM_EXPORT_VERSION, SIEM_OCSF_CLASS_UID, toOCSF, toCEF, createSiemForwarder };
+//# sourceMappingURL=siem.js.map

package/dist/siem.js.map

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

package/dist/store-postgres.d.ts

@@ -0,0 +1,107 @@
+/**
+ * EMILIA Gate — reference DURABLE consumption backend: Postgres
+ * (EP-GATE-PG-CONSUMPTION-v2).
+ *
+ * Replay defense that survives restarts. This module implements the backend
+ * contract consumed by `createDurableConsumptionStore` in ./store.js:
+ *
+ *   backend = {
+ *     async addIfAbsent(key, value, { ttlSeconds }?) : boolean  // true iff inserted
+ *     async compareAndSet(key, expected, replacement, { ttlSeconds }?) : boolean
+ *     async deleteIfValue(key, expected)             : boolean
+ *     async has(key)                                 : boolean
+ *   }
+ *
+ * plus a `cleanupExpired(now)` garbage-collection statement.
+ *
+ * Each transition is one SQL statement. `addIfAbsent` decides first use;
+ * `compareAndSet` and `deleteIfValue` bind commit/release to the opaque owner of
+ * the current reservation. There is no read-then-write interval in which a
+ * delayed worker can overwrite or remove a newer worker's reservation.
+ *
+ * FAIL-CLOSED CONTRACT: if the injected `query` THROWS (connection down,
+ * timeout, constraint other than the PK, ...) the error PROPAGATES to the
+ * caller — nothing here catches it. The gate must refuse an action when
+ * one-time-use cannot be proven; a backend error is NEVER treated as
+ * not-consumed (which would admit replays during an outage) and never treated
+ * as consumed-silently (which would mask the outage as a replay verdict).
+ * Likewise, an EXPIRED row that cleanup has not yet removed still refuses:
+ * TTL expiry is garbage collection, never a grant — the gate already rejects
+ * stale receipts on freshness, so nothing is lost by refusing conservatively.
+ *
+ * Deterministic by construction: the pg-style `query(text, params)` function
+ * and the clock (`now`) are both injected, so tests run against an in-memory
+ * fake with real ON CONFLICT semantics — no network, no database.
+ */
+export declare const PG_CONSUMPTION_VERSION = "EP-GATE-PG-CONSUMPTION-v2";
+/** Single consumption table. Timestamps are epoch milliseconds (BIGINT) so the
+ * injected JS clock maps 1:1 onto column values with no timezone ambiguity. */
+export declare const CONSUMPTION_TABLE = "ep_gate_consumption";
+export declare const CONSUMPTION_TABLE_DDL = "CREATE TABLE IF NOT EXISTS ep_gate_consumption (\n  consumption_key TEXT PRIMARY KEY,\n  state           TEXT NOT NULL,\n  consumed_at     BIGINT NOT NULL,\n  expires_at      BIGINT\n);\nCREATE INDEX IF NOT EXISTS ep_gate_consumption_expires_idx\n  ON ep_gate_consumption (expires_at) WHERE expires_at IS NOT NULL;";
+/** The exact statements the backend issues — exported for transparency and so
+ * a fake client can implement them without parsing SQL. */
+export declare const CONSUMPTION_SQL: {
+    health: string;
+    /** $1 key, $2 state, $3 consumed_at ms, $4 expires_at ms|null. rowCount 1 = consumed, 0 = replay. */
+    addIfAbsent: string;
+    /** $1 key, $2 expected state, $3 replacement, $4 consumed_at ms, $5 expires_at ms|null. */
+    compareAndSet: string;
+    /** $1 key, $2 expected state. */
+    deleteIfValue: string;
+    /** $1 key. Any row — even an expired one — counts as consumed until cleaned. */
+    has: string;
+    /** $1 now ms. Removes ONLY rows whose TTL has elapsed; NULL expires_at never expires. */
+    cleanupExpired: string;
+};
+/**
+ * Create the Postgres consumption backend.
+ * @param {{ query?: (text: string, params: any[]) => Promise<{ rowCount: number, rows?: any[] }>, now?: number|function }} [o]
+ *   `query` is a pg-style query function (e.g. `pool.query.bind(pool)`). Injected
+ *   so tests need no database. MUST throw on failure — errors propagate (fail
+ *   closed). `now` is the injected clock (ms or () => ms).
+ * @returns backend conforming to createDurableConsumptionStore, plus cleanupExpired(now).
+ */
+export declare function createPostgresBackend({ query, now, }?: {
+    query?: (text: string, params: any[]) => Promise<{
+        rowCount: number;
+        rows?: any[];
+    }>;
+    now?: number | (() => number);
+}): {
+    durable: boolean;
+    health(): Promise<{
+        ok: boolean;
+        version: string;
+    }>;
+    /** True iff THIS call inserted the row — the atomic consumed-vs-replay decision. */
+    addIfAbsent(key: any, value: any, opt: any): Promise<boolean>;
+    /** Ownership-fenced reserved -> committed transition. */
+    compareAndSet(key: any, expected: any, replacement: any, opt: any): Promise<boolean>;
+    /** Remove only the reservation owned by the caller. */
+    deleteIfValue(key: any, expected: any): Promise<boolean>;
+    /** Present = consumed. Expired-but-uncleaned rows still count (conservative). */
+    has(key: any): Promise<boolean>;
+    /** Garbage-collect rows whose TTL elapsed. Returns the number removed. */
+    cleanupExpired(at: any): Promise<number>;
+};
+declare const _default: {
+    createPostgresBackend: typeof createPostgresBackend;
+    CONSUMPTION_TABLE_DDL: string;
+    CONSUMPTION_TABLE: string;
+    CONSUMPTION_SQL: {
+        health: string;
+        /** $1 key, $2 state, $3 consumed_at ms, $4 expires_at ms|null. rowCount 1 = consumed, 0 = replay. */
+        addIfAbsent: string;
+        /** $1 key, $2 expected state, $3 replacement, $4 consumed_at ms, $5 expires_at ms|null. */
+        compareAndSet: string;
+        /** $1 key, $2 expected state. */
+        deleteIfValue: string;
+        /** $1 key. Any row — even an expired one — counts as consumed until cleaned. */
+        has: string;
+        /** $1 now ms. Removes ONLY rows whose TTL has elapsed; NULL expires_at never expires. */
+        cleanupExpired: string;
+    };
+    PG_CONSUMPTION_VERSION: string;
+};
+export default _default;
+//# sourceMappingURL=store-postgres.d.ts.map

package/dist/store-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-postgres.d.ts","sourceRoot":"","sources":["../src/store-postgres.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAElE;+EAC+E;AAC/E,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAEvD,eAAO,MAAM,qBAAqB,+TAOmC,CAAC;AAEtE;2DAC2D;AAC3D,eAAO,MAAM,eAAe;;IAK1B,qGAAqG;;IAGrG,2FAA2F;;IAG3F,iCAAiC;;IAEjC,gFAAgF;;IAEhF,yFAAyF;;CAG1F,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,GAAc,GACf,GAAE;IACD,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;IACrF,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;CAC1B;;;;;;IAkCF,oFAAoF;;IAWpF,yDAAyD;;IASzD,uDAAuD;;IASvD,iFAAiF;;IAMjF,0EAA0E;;EAO7E;;;;;;;QAzGC,qGAAqG;;QAGrG,2FAA2F;;QAG3F,iCAAiC;;QAEjC,gFAAgF;;QAEhF,yFAAyF;;;;;AAiG3F,wBAA4H"}