@kronos-ts/postgres 0.1.0

package/dist/adapters/pg.js

@@ -0,0 +1,156 @@
+/**
+ * pg (node-postgres 8.20+) reference adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path:
+ *   import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+ *
+ * Implements every PostgresAdapter method per the contract in
+ * ../adapter.ts. Pool sizing follows pg defaults; override via the
+ * `poolConfig` field if needed.
+ *
+ * LISTEN uses a dedicated long-lived PoolClient pinned outside the pool
+ * (never released) so notification delivery is not racing pool eviction.
+ * That client is closed by `disconnect()`.
+ */
+import { Pool } from "pg";
+import { IsolationLevel } from "../adapter.js";
+export function pgAdapter(config) {
+    let pool;
+    let listenClient;
+    const listenSlots = new Map();
+    let disconnected = false;
+    function getPool() {
+        if (!pool) {
+            pool = new Pool({ connectionString: config.connectionString, ...config.poolConfig });
+            pool.on("error", () => {
+                // Connection-level errors on idle clients are non-fatal for the
+                // adapter; pg removes the bad client from the pool automatically.
+                // Surfacing them would force every consumer to attach a handler.
+            });
+        }
+        return pool;
+    }
+    async function ensureListenClient() {
+        if (listenClient)
+            return listenClient;
+        listenClient = await getPool().connect();
+        listenClient.on("notification", (msg) => {
+            const slots = listenSlots.get(msg.channel);
+            if (!slots)
+                return;
+            for (const slot of slots)
+                slot.callback(msg.payload);
+        });
+        return listenClient;
+    }
+    const adapter = {
+        async connect() {
+            // Force pool creation + a no-op query so connect() actually verifies
+            // reachability. Without this, a bad connection string would only
+            // surface on the first real query.
+            const result = await getPool().query("SELECT 1 AS ok");
+            if (result.rows[0]?.ok !== 1) {
+                throw new Error("pgAdapter.connect(): unexpected health-check response");
+            }
+        },
+        async disconnect() {
+            if (disconnected)
+                return;
+            disconnected = true;
+            if (listenClient) {
+                try {
+                    listenClient.release();
+                }
+                catch {
+                    /* ignore — client may already be gone */
+                }
+                listenClient = undefined;
+            }
+            if (pool) {
+                await pool.end();
+                pool = undefined;
+            }
+        },
+        async query(sql, params) {
+            const result = await getPool().query(sql, params);
+            return result.rows;
+        },
+        async queryOne(sql, params) {
+            const result = await getPool().query(sql, params);
+            if (result.rows.length === 0)
+                return null;
+            if (result.rows.length > 1) {
+                throw new Error(`pgAdapter.queryOne: more than one row returned (got ${result.rows.length}). ` +
+                    `Use query() for multi-row results.`);
+            }
+            return result.rows[0] ?? null;
+        },
+        async transaction(isolationLevel, fn) {
+            const client = await getPool().connect();
+            try {
+                await client.query(`BEGIN ISOLATION LEVEL ${isolationLevel}`);
+                const tx = {
+                    async query(sql, params) {
+                        const result = await client.query(sql, params);
+                        return result.rows;
+                    },
+                };
+                let result;
+                try {
+                    result = await fn(tx);
+                }
+                catch (err) {
+                    // ROLLBACK best-effort; preserve the ORIGINAL error.
+                    try {
+                        await client.query("ROLLBACK");
+                    }
+                    catch {
+                        /* ignore rollback failure — original error matters more */
+                    }
+                    throw err;
+                }
+                await client.query("COMMIT");
+                return result;
+            }
+            finally {
+                client.release();
+            }
+        },
+        async listen(channel, onNotification) {
+            const client = await ensureListenClient();
+            const slot = { channel, callback: onNotification };
+            let slots = listenSlots.get(channel);
+            if (!slots) {
+                slots = new Set();
+                listenSlots.set(channel, slots);
+                // Channel identifiers cannot be parameterised in pg's LISTEN — use
+                // a safelist: alphanumerics + underscore only. Anything else is a
+                // SQL-injection risk by definition.
+                if (!/^[A-Za-z0-9_]+$/.test(channel)) {
+                    throw new Error(`pgAdapter.listen: channel name must match /^[A-Za-z0-9_]+$/, got: ${channel}`);
+                }
+                await client.query(`LISTEN ${channel}`);
+            }
+            slots.add(slot);
+            return {
+                async unlisten() {
+                    const cur = listenSlots.get(channel);
+                    if (!cur)
+                        return;
+                    cur.delete(slot);
+                    if (cur.size === 0) {
+                        listenSlots.delete(channel);
+                        try {
+                            await client.query(`UNLISTEN ${channel}`);
+                        }
+                        catch {
+                            /* connection may already be gone */
+                        }
+                    }
+                },
+            };
+        },
+    };
+    return adapter;
+}
+//# sourceMappingURL=pg.js.map

package/dist/adapters/pg.js.map

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

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,27 @@
+/**
+ * postgres.js (porsager) reference adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path:
+ *   import { postgresAdapter } from "@kronos-ts/postgres/adapters/postgres"
+ *
+ * Notable porsager/postgres quirks handled here:
+ *   - Default behaviour transforms column names (snake_case → camelCase).
+ *     We DISABLE this because the SQL we author (and the SP signatures
+ *     produced by schema.ts) use snake_case column names — letting the
+ *     transform fire would produce row objects with `sequencePosition`
+ *     instead of `sequence_position`, breaking the engine code.
+ *   - Transactions: sql.begin returns the callback's value when it resolves
+ *     and ROLLBACKs on rejection. We use the `BEGIN ISOLATION LEVEL ${lvl}`
+ *     option since sql.begin accepts isolation as part of the BEGIN clause.
+ *   - LISTEN: sql.listen(channel, cb) returns a Promise<{ unlisten() }>.
+ *     The shape already matches our ListenSubscription contract.
+ */
+import postgresClient from "postgres";
+import type { PostgresAdapter } from "../adapter.js";
+export interface PostgresAdapterConfig {
+    readonly connectionString: string;
+    /** Additional postgres.js options. `transform.column.from` is forced off regardless. */
+    readonly clientOptions?: Parameters<typeof postgresClient>[1];
+}
+export declare function postgresAdapter(config: PostgresAdapterConfig): PostgresAdapter;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/adapters/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/adapters/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,cAAc,MAAM,UAAU,CAAA;AAErC,OAAO,KAAK,EACV,eAAe,EAIhB,MAAM,eAAe,CAAA;AAGtB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,wFAAwF;IACxF,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAkG9E"}

package/dist/adapters/postgres.js

@@ -0,0 +1,99 @@
+/**
+ * postgres.js (porsager) reference adapter for @kronos-ts/postgres.
+ *
+ * Import via the sub-path:
+ *   import { postgresAdapter } from "@kronos-ts/postgres/adapters/postgres"
+ *
+ * Notable porsager/postgres quirks handled here:
+ *   - Default behaviour transforms column names (snake_case → camelCase).
+ *     We DISABLE this because the SQL we author (and the SP signatures
+ *     produced by schema.ts) use snake_case column names — letting the
+ *     transform fire would produce row objects with `sequencePosition`
+ *     instead of `sequence_position`, breaking the engine code.
+ *   - Transactions: sql.begin returns the callback's value when it resolves
+ *     and ROLLBACKs on rejection. We use the `BEGIN ISOLATION LEVEL ${lvl}`
+ *     option since sql.begin accepts isolation as part of the BEGIN clause.
+ *   - LISTEN: sql.listen(channel, cb) returns a Promise<{ unlisten() }>.
+ *     The shape already matches our ListenSubscription contract.
+ */
+import postgresClient from "postgres";
+import { IsolationLevel } from "../adapter.js";
+export function postgresAdapter(config) {
+    let sql;
+    let disconnected = false;
+    function getSql() {
+        if (!sql) {
+            sql = postgresClient(config.connectionString, {
+                ...(config.clientOptions ?? {}),
+                // Hard-override the column transform so our snake_case SQL works
+                // verbatim. Users who pass a transform in clientOptions are told
+                // (via JSDoc) that the column-from transform is ignored.
+                transform: {
+                    ...(config.clientOptions?.transform ?? {}),
+                    column: { from: undefined, to: undefined },
+                },
+            });
+        }
+        return sql;
+    }
+    return {
+        async connect() {
+            const c = getSql();
+            const rows = await c.unsafe("SELECT 1 AS ok");
+            if (rows[0]?.ok !== 1) {
+                throw new Error("postgresAdapter.connect: unexpected health-check response");
+            }
+        },
+        async disconnect() {
+            if (disconnected)
+                return;
+            disconnected = true;
+            if (sql) {
+                await sql.end({ timeout: 5 });
+                sql = undefined;
+            }
+        },
+        async query(text, params) {
+            const c = getSql();
+            const rows = (await c.unsafe(text, (params ?? [])));
+            return rows;
+        },
+        async queryOne(text, params) {
+            const rows = await this.query(text, params);
+            if (rows.length === 0)
+                return null;
+            if (rows.length > 1) {
+                throw new Error(`postgresAdapter.queryOne: more than one row returned (got ${rows.length}). Use query() for multi-row results.`);
+            }
+            return rows[0] ?? null;
+        },
+        async transaction(isolationLevel, fn) {
+            const c = getSql();
+            // sql.begin's first argument is the BEGIN options; we pass the
+            // isolation level. The callback receives a scoped `sql` that
+            // pins to the underlying connection for the duration.
+            return (await c.begin(`ISOLATION LEVEL ${isolationLevel}`, async (txSql) => {
+                const tx = {
+                    async query(text, params) {
+                        const rows = (await txSql.unsafe(text, (params ?? [])));
+                        return rows;
+                    },
+                };
+                return fn(tx);
+            }));
+        },
+        async listen(channel, onNotification) {
+            if (!/^[A-Za-z0-9_]+$/.test(channel)) {
+                throw new Error(`postgresAdapter.listen: channel name must match /^[A-Za-z0-9_]+$/, got: ${channel}`);
+            }
+            const c = getSql();
+            const sub = await c.listen(channel, (payload) => onNotification(payload || undefined));
+            return {
+                async unlisten() {
+                    await sub.unlisten();
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/adapters/postgres.js.map

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

package/dist/advisory-locks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Advisory-lock taxonomy for the DCB conflict check (D-12.09/10/11).
+ *
+ * Three keyspaces, S/X-asymmetric:
+ *
+ *   Leaf          K(T, t)    writer = X-lock,        reader = S-lock
+ *   Type-intent   K(T, ε)    writer = S-lock,        reader = X-lock
+ *   Global-intent K(ε, ε)    writer = S-lock,        reader = X-lock
+ *
+ * The asymmetry lets writers on DISJOINT (T,t) tuples run in parallel
+ * (their leaf X-locks don't conflict, and they only take S on the intent
+ * keys — multiple S-holders coexist). A Query.all() reader (rare) takes
+ * X on the intent keys, briefly blocking ALL writers — but that's the
+ * point: Query.all() needs to see a consistent snapshot.
+ *
+ * Locks are pg_advisory_xact_lock variants: held until tx commit/rollback,
+ * automatically released. NEVER use session-scoped locks here — PgBouncer
+ * in transaction-pooling mode would leak them.
+ *
+ * Reimplemented from principles per D-12.11. The kraken-tech version is
+ * a reference for the taxonomy and FNV-1a hash; the SQL and serialisation
+ * format below are original.
+ */
+import type { PostgresAdapterTransaction } from "./adapter.js";
+/**
+ * FNV-1a 64-bit hash. Returns a BIGINT in the signed 64-bit range so it can
+ * be passed directly to `pg_advisory_xact_lock(BIGINT)`. Values with the
+ * high bit set are returned as negative numbers (two's complement).
+ *
+ * Per FNV-1a: h = offset_basis; for each byte b: h = (h XOR b) * prime mod 2^64.
+ * UTF-8 byte iteration via TextEncoder for predictable cross-runtime behaviour.
+ */
+export declare function hashLockKey(input: string): bigint;
+export type LockKeyspace = "leaf" | "type-intent" | "global-intent";
+export declare function leafKey(type: string, tag: string): bigint;
+export declare function typeIntentKey(type: string): bigint;
+export declare function globalIntentKey(): bigint;
+export interface LockTarget {
+    readonly type: string;
+    readonly tag: string;
+}
+/**
+ * Writer pattern: X-lock on each unique leaf, S-lock on each unique
+ * type-intent + the global-intent. Writers on disjoint leaves run in
+ * parallel; writers sharing a leaf serialise.
+ *
+ * Locks are issued in a stable order (sorted by key value) to avoid
+ * deadlocks between concurrent writers that share multiple leaves.
+ */
+export declare function acquireWriteLocks(tx: PostgresAdapterTransaction, targets: ReadonlyArray<LockTarget>): Promise<void>;
+/**
+ * Reader pattern (Query.all): S on leaves, X on type-intent + global-intent.
+ * Inverse of writer; briefly excludes all writers while held.
+ */
+export declare function acquireReadLocks(tx: PostgresAdapterTransaction, targets: ReadonlyArray<LockTarget>): Promise<void>;
+//# sourceMappingURL=advisory-locks.d.ts.map

package/dist/advisory-locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisory-locks.d.ts","sourceRoot":"","sources":["../src/advisory-locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAa9D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,eAAe,CAAA;AAEnE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,0BAA0B,EAC9B,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,0BAA0B,EAC9B,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/advisory-locks.js

@@ -0,0 +1,112 @@
+/**
+ * Advisory-lock taxonomy for the DCB conflict check (D-12.09/10/11).
+ *
+ * Three keyspaces, S/X-asymmetric:
+ *
+ *   Leaf          K(T, t)    writer = X-lock,        reader = S-lock
+ *   Type-intent   K(T, ε)    writer = S-lock,        reader = X-lock
+ *   Global-intent K(ε, ε)    writer = S-lock,        reader = X-lock
+ *
+ * The asymmetry lets writers on DISJOINT (T,t) tuples run in parallel
+ * (their leaf X-locks don't conflict, and they only take S on the intent
+ * keys — multiple S-holders coexist). A Query.all() reader (rare) takes
+ * X on the intent keys, briefly blocking ALL writers — but that's the
+ * point: Query.all() needs to see a consistent snapshot.
+ *
+ * Locks are pg_advisory_xact_lock variants: held until tx commit/rollback,
+ * automatically released. NEVER use session-scoped locks here — PgBouncer
+ * in transaction-pooling mode would leak them.
+ *
+ * Reimplemented from principles per D-12.11. The kraken-tech version is
+ * a reference for the taxonomy and FNV-1a hash; the SQL and serialisation
+ * format below are original.
+ */
+const UNIT_SEPARATOR = ""; // ASCII Unit Separator (U+001F) — prevents tuple-collision hashing
+const KEYSPACE_LEAF = "L";
+const KEYSPACE_TYPE_INTENT = "T";
+const KEYSPACE_GLOBAL_INTENT = "G";
+// FNV-1a 64-bit constants
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = (1n << 64n) - 1n;
+const SIGN_THRESHOLD = 1n << 63n;
+/**
+ * FNV-1a 64-bit hash. Returns a BIGINT in the signed 64-bit range so it can
+ * be passed directly to `pg_advisory_xact_lock(BIGINT)`. Values with the
+ * high bit set are returned as negative numbers (two's complement).
+ *
+ * Per FNV-1a: h = offset_basis; for each byte b: h = (h XOR b) * prime mod 2^64.
+ * UTF-8 byte iteration via TextEncoder for predictable cross-runtime behaviour.
+ */
+export function hashLockKey(input) {
+    const bytes = new TextEncoder().encode(input);
+    let h = FNV_OFFSET_BASIS;
+    for (let i = 0; i < bytes.length; i++) {
+        h = (h ^ BigInt(bytes[i])) & MASK_64;
+        h = (h * FNV_PRIME) & MASK_64;
+    }
+    // Reinterpret as signed 64-bit
+    return h >= SIGN_THRESHOLD ? h - (1n << 64n) : h;
+}
+export function leafKey(type, tag) {
+    return hashLockKey(`${KEYSPACE_LEAF}${UNIT_SEPARATOR}${type}${UNIT_SEPARATOR}${tag}`);
+}
+export function typeIntentKey(type) {
+    return hashLockKey(`${KEYSPACE_TYPE_INTENT}${UNIT_SEPARATOR}${type}`);
+}
+export function globalIntentKey() {
+    return hashLockKey(KEYSPACE_GLOBAL_INTENT);
+}
+/**
+ * Writer pattern: X-lock on each unique leaf, S-lock on each unique
+ * type-intent + the global-intent. Writers on disjoint leaves run in
+ * parallel; writers sharing a leaf serialise.
+ *
+ * Locks are issued in a stable order (sorted by key value) to avoid
+ * deadlocks between concurrent writers that share multiple leaves.
+ */
+export async function acquireWriteLocks(tx, targets) {
+    if (targets.length === 0) {
+        // Even with no leaf targets, acquire the global-intent S-lock so that
+        // a Query.all() X on the global-intent can block us if needed.
+        await tx.query(`SELECT pg_advisory_xact_lock_shared($1)`, [globalIntentKey()]);
+        return;
+    }
+    const leafKeys = uniqueSorted(targets.map((t) => leafKey(t.type, t.tag)));
+    const typeIntentKeys = uniqueSorted([...new Set(targets.map((t) => t.type))].map(typeIntentKey));
+    // X on leaves (sorted for deadlock-free acquisition order)
+    for (const k of leafKeys) {
+        await tx.query(`SELECT pg_advisory_xact_lock($1)`, [k]);
+    }
+    // S on type-intent
+    for (const k of typeIntentKeys) {
+        await tx.query(`SELECT pg_advisory_xact_lock_shared($1)`, [k]);
+    }
+    // S on global-intent
+    await tx.query(`SELECT pg_advisory_xact_lock_shared($1)`, [globalIntentKey()]);
+}
+/**
+ * Reader pattern (Query.all): S on leaves, X on type-intent + global-intent.
+ * Inverse of writer; briefly excludes all writers while held.
+ */
+export async function acquireReadLocks(tx, targets) {
+    if (targets.length === 0) {
+        // A truly empty Query.all() still needs the global-intent X to see a
+        // consistent snapshot across all types.
+        await tx.query(`SELECT pg_advisory_xact_lock($1)`, [globalIntentKey()]);
+        return;
+    }
+    const leafKeys = uniqueSorted(targets.map((t) => leafKey(t.type, t.tag)));
+    const typeIntentKeys = uniqueSorted([...new Set(targets.map((t) => t.type))].map(typeIntentKey));
+    for (const k of leafKeys) {
+        await tx.query(`SELECT pg_advisory_xact_lock_shared($1)`, [k]);
+    }
+    for (const k of typeIntentKeys) {
+        await tx.query(`SELECT pg_advisory_xact_lock($1)`, [k]);
+    }
+    await tx.query(`SELECT pg_advisory_xact_lock($1)`, [globalIntentKey()]);
+}
+function uniqueSorted(xs) {
+    return [...new Set(xs)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+//# sourceMappingURL=advisory-locks.js.map

package/dist/advisory-locks.js.map

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

package/dist/criteria-sql.d.ts

@@ -0,0 +1,29 @@
+/**
+ * EventCriteria → SQL WHERE clause builder.
+ *
+ * Maps the discriminated-union criteria from @kronos-ts/messaging into a
+ * parameterised WHERE fragment + parameter array. The caller (Plan 04
+ * source() + the append SP body) splices this into a larger query.
+ *
+ * Tag semantics: `@>` (contains-all). NEVER `&&` (overlap). The reference
+ * is packages/eventsourcing/src/in-memory-event-store.ts:matchesTags —
+ * `criteria.tags.every(requiredTag => event.tags.some(...))` is exactly
+ * the meaning of `tags @> $required`.
+ *
+ * Tag encoding: each `{key, value}` is serialised as `${key}${value}`.
+ * Stored events use the same encoding (Plan 04 Task 3 — appendEvents flattens
+ * tags via the same scheme) so `@>` works literally against text[].
+ */
+import type { EventCriteria } from "@kronos-ts/messaging";
+export interface CriteriaSQL {
+    /** SQL WHERE fragment (no leading "WHERE"). Always truthy — empty
+     *  criteria collapse to `"true"`. */
+    readonly where: string;
+    /** Parameters in $-positional order. */
+    readonly params: ReadonlyArray<unknown>;
+    /** Next available $N index for chaining into a larger query. */
+    readonly nextParamIndex: number;
+}
+export declare function encodeTag(key: string, value: string): string;
+export declare function buildCriteriaWhere(criteria: EventCriteria, startIndex: number): CriteriaSQL;
+//# sourceMappingURL=criteria-sql.d.ts.map

package/dist/criteria-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-sql.d.ts","sourceRoot":"","sources":["../src/criteria-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,MAAM,WAAW,WAAW;IAC1B;yCACqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IACvC,gEAAgE;IAChE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAID,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,MAAM,GACjB,WAAW,CAkDb"}

package/dist/criteria-sql.js

@@ -0,0 +1,69 @@
+/**
+ * EventCriteria → SQL WHERE clause builder.
+ *
+ * Maps the discriminated-union criteria from @kronos-ts/messaging into a
+ * parameterised WHERE fragment + parameter array. The caller (Plan 04
+ * source() + the append SP body) splices this into a larger query.
+ *
+ * Tag semantics: `@>` (contains-all). NEVER `&&` (overlap). The reference
+ * is packages/eventsourcing/src/in-memory-event-store.ts:matchesTags —
+ * `criteria.tags.every(requiredTag => event.tags.some(...))` is exactly
+ * the meaning of `tags @> $required`.
+ *
+ * Tag encoding: each `{key, value}` is serialised as `${key}${value}`.
+ * Stored events use the same encoding (Plan 04 Task 3 — appendEvents flattens
+ * tags via the same scheme) so `@>` works literally against text[].
+ */
+const TAG_DELIMITER = ""; // ASCII Unit Separator (U+001F) — prevents key/value boundary collisions in encoded tag strings
+export function encodeTag(key, value) {
+    return `${key}${TAG_DELIMITER}${value}`;
+}
+export function buildCriteriaWhere(criteria, startIndex) {
+    switch (criteria.kind) {
+        case "any-tag":
+            return {
+                where: "cardinality(tags) > 0",
+                params: [],
+                nextParamIndex: startIndex,
+            };
+        case "tags": {
+            if (criteria.tags.length === 0) {
+                // Empty contains-all matches everything (the in-memory store's
+                // `tags.every(...)` over an empty array is vacuously true).
+                return { where: "true", params: [], nextParamIndex: startIndex };
+            }
+            const encoded = criteria.tags.map((t) => encodeTag(t.key, t.value));
+            return {
+                where: `tags @> $${startIndex}::text[]`,
+                params: [encoded],
+                nextParamIndex: startIndex + 1,
+            };
+        }
+        case "type-restricted": {
+            const inner = buildCriteriaWhere(criteria.inner, startIndex);
+            const typeParam = inner.nextParamIndex;
+            return {
+                where: `(${inner.where}) AND type = ANY($${typeParam}::text[])`,
+                params: [...inner.params, criteria.types],
+                nextParamIndex: typeParam + 1,
+            };
+        }
+        case "either": {
+            const parts = [];
+            const params = [];
+            let next = startIndex;
+            for (const sub of criteria.criteria) {
+                const built = buildCriteriaWhere(sub, next);
+                parts.push(`(${built.where})`);
+                params.push(...built.params);
+                next = built.nextParamIndex;
+            }
+            return {
+                where: parts.join(" OR "),
+                params,
+                nextParamIndex: next,
+            };
+        }
+    }
+}
+//# sourceMappingURL=criteria-sql.js.map

package/dist/criteria-sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-sql.js","sourceRoot":"","sources":["../src/criteria-sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,MAAM,aAAa,GAAG,GAAG,CAAA,CAAC,gGAAgG;AAE1H,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,KAAa;IAClD,OAAO,GAAG,GAAG,GAAG,aAAa,GAAG,KAAK,EAAE,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,QAAuB,EACvB,UAAkB;IAElB,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO;gBACL,KAAK,EAAE,uBAAuB;gBAC9B,MAAM,EAAE,EAAE;gBACV,cAAc,EAAE,UAAU;aAC3B,CAAA;QAEH,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/B,+DAA+D;gBAC/D,4DAA4D;gBAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;YAClE,CAAC;YACD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;YACnE,OAAO;gBACL,KAAK,EAAE,YAAY,UAAU,UAAU;gBACvC,MAAM,EAAE,CAAC,OAAO,CAAC;gBACjB,cAAc,EAAE,UAAU,GAAG,CAAC;aAC/B,CAAA;QACH,CAAC;QAED,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;YAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,cAAc,CAAA;YACtC,OAAO;gBACL,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,qBAAqB,SAAS,WAAW;gBAC/D,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC;gBACzC,cAAc,EAAE,SAAS,GAAG,CAAC;aAC9B,CAAA;QACH,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,KAAK,GAAa,EAAE,CAAA;YAC1B,MAAM,MAAM,GAAc,EAAE,CAAA;YAC5B,IAAI,IAAI,GAAG,UAAU,CAAA;YACrB,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACpC,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;gBAC3C,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,CAAC,CAAA;gBAC9B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;gBAC5B,IAAI,GAAG,KAAK,CAAC,cAAc,CAAA;YAC7B,CAAC;YACD,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;gBACzB,MAAM;gBACN,cAAc,EAAE,IAAI;aACrB,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SQLSTATE used by the schema-bootstrap stored procedure when a DCB
+ * append condition is violated. Per D-12.12: dedicated SQLSTATE via
+ * `RAISE ... USING ERRCODE`, never error-text parsing.
+ *
+ * `KR001` lives in the Postgres user-defined SQLSTATE range (KX–ZZ).
+ * It is intentionally distinct from:
+ *   - `P0001` — generic RAISE (would over-match any unhandled plpgsql exception)
+ *   - `23505` — unique_violation (used by primary key conflicts)
+ * Adapter layers translate `err.code === KR001` into AppendConditionError.
+ */
+export declare const KRONOS_DCB_VIOLATION_SQLSTATE = "KR001";
+/**
+ * Thrown when an append condition is violated — optimistic concurrency
+ * failure. Structurally mirrors `@kronos-ts/eventsourcing`'s
+ * AppendConditionError so callers that catch either get equivalent
+ * behaviour, but we ship our own class so that the SQLSTATE-catch
+ * boundary lives inside this package's import graph.
+ */
+export declare class AppendConditionError extends Error {
+    constructor(message: string);
+    static fromConflictCount(count: number, afterPosition: bigint): AppendConditionError;
+}
+/**
+ * Adapter-agnostic check: pg and postgres.js both surface SQLSTATE on
+ * thrown errors as `.code` (string). Bun.sql follows the same convention.
+ * This helper keeps the SQLSTATE constant centralised.
+ */
+export declare function isDcbViolation(err: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,UAAU,CAAA;AAEpD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;IAK3B,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,oBAAoB;CAMrF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOpD"}