@kairos-es/store-postgres 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/dts-esm/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @kairos-es/store-postgres — the Postgres `DcbEventStore` backend.
+ *
+ * A single store is one `{ schema, tablePrefix }` naming pair (`PostgresStoreConfig`);
+ * every object it owns is derived from that pair, so multiple isolated stores
+ * cohabit one database. The engine is the two-table B-tree + exclusive-lock
+ * conditional append of ADR-0002, with JSON transport and a two-client Layer to
+ * survive Neon's pooled LISTEN/NOTIFY drop.
+ *
+ * Wiring, end to end:
+ *
+ * ```ts
+ * import { PgClient } from '@effect/sql-pg'
+ * import {
+ *   ensureSchema,
+ *   layer,
+ *   pooledLayer,
+ *   directLayer,
+ * } from '@kairos-es/store-postgres'
+ *
+ * const config = { schema: 'public', tablePrefix: 'dcb_events' }
+ *
+ * // 1. Register `ensureSchema(config)` in YOUR migrator (or run it at boot).
+ * // 2. Provide the two clients (same URL off Neon; a direct endpoint for
+ * //    `directLayer` on Neon), then the store layer over them.
+ * const clients = Layer.merge(
+ *   pooledLayer({ url: Redacted.make(poolUrl) }),
+ *   directLayer({ url: Redacted.make(directUrl) }),
+ * )
+ * const store = layer(config).pipe(Layer.provide(clients))
+ * ```
+ *
+ * The store `layer` performs NO DDL: it depends only on the two client services
+ * and assumes `ensureSchema` has run. `ensureSchema` requires the generic
+ * `SqlClient` service so it slots into any migrator; the runtime uses the
+ * store-owned services.
+ */
+export { directLayer, PgClientDirect, PgClientPooled, pooledLayer, } from './clients.js';
+export type { PostgresStoreConfig } from './config.js';
+export { ensureSchema } from './ensureSchema.js';
+export { layer } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts-esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,GACZ,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA"}

package/dist/dts-esm/internal/ddl.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Internal DDL and object-naming for the Postgres `DcbEventStore` backend.
+ *
+ * This module is the single source of truth for every object name a store owns
+ * and for the plpgsql function bodies. It is deliberately factored apart from
+ * the public engine so that:
+ *
+ * 1. names are derived ONCE, from `{ schema, tablePrefix }`, and reused by both
+ *    `ensureSchema` (DDL) and the runtime (`append`/`read`/`subscribe`), so the
+ *    migration and the queries can never disagree about what a table is called;
+ * 2. the append-function body is assembled from COMPOSABLE parts — in
+ *    particular the `LOCK TABLE … IN EXCLUSIVE MODE` clause is an omittable
+ *    fragment — so a test can `CREATE OR REPLACE` a deliberately-LOCKLESS twin of
+ *    the append function to prove the shared contract suite actually detects a
+ *    non-serialising store. The production Layer never exposes a lockless option;
+ *    the seam lives here, in an internal module, reachable only from the test
+ *    graph.
+ *
+ * WHY names are never string-concatenated: every identifier flows through
+ * `sql(identifier)`, which quotes and dot-splits safely, so a hostile or merely
+ * awkward `schema`/`tablePrefix` cannot inject SQL or collide with a reserved
+ * word. The plpgsql *bodies*, which must embed the resolved names as literal
+ * text inside a `CREATE FUNCTION … $$ … $$` string, use the SAME quoting via a
+ * small `quoteQualified` helper so the body text matches what `sql(identifier)`
+ * would emit; VALUES stay bound parameters (`sql.unsafe` with `params`) and are
+ * never interpolated.
+ */
+import type { SqlClient, Statement } from 'effect/sql';
+/**
+ * A store is one physical `{ schema, tablePrefix }` pair. Every object it owns
+ * (both tables, both indexes, both functions, and the NOTIFY channel) is derived
+ * from this pair, so one prefix is one completely isolated store: its own
+ * bigserial sequence, its own exclusive-lock scope, its own wake channel.
+ */
+export interface ResolvedNames {
+    readonly schema: string;
+    readonly tablePrefix: string;
+    /** `<schema>.<prefix>` — the main event table. */
+    readonly mainTable: string;
+    /** `<schema>.<prefix>_tags` — the junction tag table. */
+    readonly tagTable: string;
+    /** `<prefix>_idx_id_type` — the covering unique index on the main table. */
+    readonly mainIndex: string;
+    /** `<prefix>_idx_tag_main_id` — the composite B-tree on the tag table. */
+    readonly tagIndex: string;
+    /** `<schema>.<prefix>_append` — the conditional (lock → check → insert → notify) function. */
+    readonly appendFn: string;
+    /**
+     * `<schema>.<prefix>_append_unconditional` — the check-free insert twin. It takes
+     * the SAME exclusive lock as the conditional one, which is what discharges the
+     * subscribe machine's ascending-commit-order precondition on this engine;
+     * `unconditionalAppendBody` owns why a lock-free twin would not.
+     */
+    readonly appendUnconditionalFn: string;
+    /**
+     * The `LISTEN`/`NOTIFY` channel: the fully-qualified events-table name with
+     * dots replaced by `_`. A channel is a single unqualified identifier, so the
+     * schema is folded into the name to keep two stores in different schemas but
+     * with the same prefix from sharing a channel.
+     */
+    readonly channel: string;
+}
+/** Default schema when the config omits one. */
+export declare const DEFAULT_SCHEMA = "public";
+/** Default table prefix when the config omits one. */
+export declare const DEFAULT_TABLE_PREFIX = "dcb_events";
+/**
+ * The first derived identifier that exceeds 63 bytes, as a human-readable
+ * message, or `undefined` when every name fits. Shared by `resolveNames` (which
+ * throws) and the `PostgresStoreConfig` schema filter (which fails validation),
+ * so the byte bound is enforced identically at both the name-derivation and the
+ * config-decode boundary.
+ */
+export declare const oversizedIdentifier: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => string | undefined;
+/**
+ * Derive every owned object name from `{ schema, tablePrefix }`. The index and
+ * function *base* names are unqualified prefixes (`<prefix>_…`) because an index
+ * name is scoped to its table's schema and a function is created in `<schema>`;
+ * the tables and functions carry the schema explicitly so `sql(identifier)`
+ * dot-splits them.
+ *
+ * Throws at construction if any derived identifier would be silently truncated
+ * (see `oversizedIdentifier` / `MAX_IDENTIFIER_BYTES`) — a loud failure at the
+ * single choke point beats an invisible index-skip or channel collision later.
+ */
+export declare const resolveNames: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => ResolvedNames;
+/**
+ * Quote a possibly-qualified identifier for embedding inside a plpgsql body as
+ * literal text. Splits on `.` and double-quotes each atom, mirroring what
+ * `sql(identifier)` emits, so the body's table references and the runtime's
+ * `sql(identifier)` references resolve to exactly the same object. Any embedded
+ * `"` is doubled per SQL identifier-quoting rules.
+ */
+export declare const quoteQualified: (name: string) => string;
+/**
+ * The named body-fragment seams, replacing positional boolean flags — the old
+ * `unconditionalAppendBody(names, true, false)` was boolean-blind. Both knobs
+ * default to the production configuration (locked + notifying); a test twin
+ * overrides one field BY NAME. This is the union of both knobs; each body `Pick`s
+ * only the ones it actually varies — the conditional body always notifies, so it
+ * never took `notify`.
+ *
+ * - `lock` — include the `LOCK TABLE … IN EXCLUSIVE MODE` clause (default true).
+ *   BOTH twins vary it: the test-only lockless twins pass `false` to prove the
+ *   lock is load-bearing (the conditional path's lockless meta-test and the
+ *   unconditional commit-order repro).
+ * - `notify` — include the `pg_notify` wake (default true). ONLY the unconditional
+ *   twin varies it: the poll-only delivery test passes `false` to prove the
+ *   periodic poll, not NOTIFY, is the delivery guarantee.
+ */
+export interface AppendBodyOptions {
+    readonly lock?: boolean;
+    readonly notify?: boolean;
+}
+/**
+ * Which append function to (re)create, plus the body-fragment seams. `kind`
+ * selects the conditional (guarded) or unconditional (check-free) twin — fixing
+ * the function NAME and SIGNATURE — and the seams default to the production
+ * configuration.
+ *
+ * A DISCRIMINATED union, not `extends AppendBodyOptions`, so the seams a `kind`
+ * cannot vary are un-expressible: the conditional twin exposes only `lock` (it
+ * always notifies), so `{ kind: 'conditional', notify: false }` is a compile error
+ * rather than a silently-ignored dead option.
+ */
+export type AppendFunctionOptions = ({
+    readonly kind: 'conditional';
+} & Pick<AppendBodyOptions, 'lock'>) | ({
+    readonly kind: 'unconditional';
+} & AppendBodyOptions);
+/**
+ * Build ONE complete `CREATE OR REPLACE FUNCTION … RETURNS SETOF bigint LANGUAGE
+ * plpgsql AS $kairos$…$kairos$` statement for an append function. This is the
+ * single source of the wrapper — its qualified name, argument SIGNATURE, and
+ * `$kairos$`-delimited body — consumed by `ddlStatements` (production, both twins)
+ * AND by the test installers that `CREATE OR REPLACE` a lockless / notify-
+ * suppressed twin over their own prefix.
+ *
+ * WHY one builder: `ddlStatements` plus three test twins previously hand-restated
+ * this wrapper, several with string-INTERPOLATED identifiers this module's own
+ * doctrine forbids (`"${schema}"."${prefix}_append"` rather than
+ * `quoteQualified(names.appendFn)`). A drift in the SIGNATURE across those copies
+ * is a silent footgun: `CREATE OR REPLACE` with a changed argument list creates a
+ * new OVERLOAD instead of replacing, leaving the original production function live
+ * under test. Single-sourcing name + signature makes a twin unable to diverge —
+ * a twin `CREATE OR REPLACE`s exactly the function `ddlStatements` created.
+ */
+export declare const appendFunctionStatement: (names: ResolvedNames, options: AppendFunctionOptions) => string;
+/**
+ * The full ordered list of idempotent DDL statements that create/refresh a
+ * store's objects. Each entry is a `sql.unsafe` statement string; VALUES are not
+ * involved (pure DDL), and every identifier is pre-quoted via `quoteQualified`
+ * to match the runtime's `sql(identifier)` resolution.
+ *
+ * Ordering matters: tables before their indexes and before the tag table's FK,
+ * functions last (they reference the tables). Everything is `IF NOT EXISTS` /
+ * `CREATE OR REPLACE`, so re-running is a no-op — the migration payload is safe
+ * to register in any migrator or to run directly.
+ */
+export declare const ddlStatements: (names: ResolvedNames) => ReadonlyArray<string>;
+/**
+ * Run the ordered DDL against the generic `SqlClient`. Kept here (not in the
+ * public `ensureSchema`) so the same builder feeds both the public migration
+ * payload and any internal test setup. Each statement is a separate `sql.unsafe`
+ * call so a driver that rejects multi-statement strings still works.
+ */
+export declare const runDdl: (sql: SqlClient.SqlClient, names: ResolvedNames) => ReadonlyArray<Statement.Statement<unknown>>;
+//# sourceMappingURL=ddl.d.ts.map

package/dist/dts-esm/internal/ddl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../src/internal/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAWtD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,gDAAgD;AAChD,eAAO,MAAM,cAAc,WAAW,CAAA;AACtC,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,eAAe,CAAA;AAuChD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,MAAM,GAAG,SAQZ,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,aAkBH,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAIhC,CAAA;AA2Cd;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAoOD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GACpE,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG,iBAAiB,CAAC,CAAA;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,aAAa,EACpB,SAAS,qBAAqB,KAC7B,MAqBF,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,aAAa,KAAG,aAAa,CAAC,MAAM,CAmExE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,SAAS,CAAC,SAAS,EACxB,OAAO,aAAa,KACnB,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CACmB,CAAA"}

package/dist/dts-esm/internal/matchSql.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Single source of truth for the tag-first match SQL.
+ *
+ * The servable-query matching semantics — the tagged AND-superset match with
+ * distinct-tag counting, the allowed-types filter, the exclusive `after` bound —
+ * were hand-duplicated between the TS read path (`store.ts`) and the plpgsql
+ * conflict check (`ddl.ts`): two SQL dialect-copies, in two files, that drift
+ * independently (the read's wildcard mis-routing of a degenerate empty item was
+ * one such drift). This module emits the shared fragments ONCE, parameterised by:
+ *
+ * - the PLACEHOLDER TOKENS each call site binds — plpgsql parameter names
+ *   (`query_items`, `COALESCE(after_id, 0)`) for the conflict body vs bound
+ *   `$n` placeholders for the runtime `sql.unsafe(text, params)` read; and
+ * - the PROJECTION — full rows (read) vs an `EXISTS`/`LIMIT 1` probe (conflict),
+ *   which each call site wraps around the shared `qualifiedRows` source.
+ *
+ * The `jsonb_to_recordset` event column list also lives here as ONE descriptor,
+ * so the write recordset (`ddl.ts`) and the read projection cannot disagree.
+ *
+ * Table names arrive PRE-QUOTED (via `quoteQualified` in `ddl.ts`), so this
+ * module never quotes identifiers itself and stays free of the naming logic.
+ * Every fragment assumes the main events table is aliased `m`.
+ */
+/**
+ * The event payload columns shared by the write recordset and every read
+ * projection, as `[name, recordsetType]` pairs. `id` (the `bigserial` position)
+ * is prepended by the read projection and absent from the events recordset.
+ *
+ * `as const` freezes it into a tuple of literal names so `EventColumnName` (below)
+ * can derive the exact column-name union — the whole point of the "one descriptor"
+ * story: the TS transport shapes in `internal/transport.ts` are mapped types over
+ * that union, so a column rename here is a COMPILE error there, not a silent drift
+ * the lax read boundary (ADR-0006) would only surface as corrupt data under test.
+ */
+declare const EVENT_COLUMNS: readonly [readonly ["type", "text"], readonly ["data", "text"], readonly ["tags", "text[]"], readonly ["uuid", "text"], readonly ["occurred_at", "timestamptz"], readonly ["metadata", "jsonb"]];
+/**
+ * The event payload column NAMES as a string-literal union, derived from the ONE
+ * `EVENT_COLUMNS` descriptor. `internal/transport.ts` builds its transport shapes
+ * (`EventJson`, the JSON sent to the append functions; `EventRow`, a raw driver
+ * row) as mapped types over this union, so the transport shapes cannot drift from
+ * the SQL recordset/projection — a rename in the descriptor removes the old key
+ * from the union and makes the mapped type fail to compile.
+ */
+export type EventColumnName = (typeof EVENT_COLUMNS)[number][0];
+/**
+ * The `jsonb_to_recordset(new_events) AS (…)` column definitions —
+ * `type text, data text, tags text[], uuid text, occurred_at timestamptz,
+ * metadata jsonb`. The
+ * transport `data` is base64 TEXT (restored to `bytea` by `decode(…, 'base64')`
+ * at insert), which is why it is `text` here, not `bytea`.
+ */
+export declare const eventRecordsetColumns: string;
+/**
+ * The read projection column list (`id` + the event columns), optionally
+ * prefixed with a table alias (`'m.'`). Sourced from the one descriptor so it
+ * cannot drift from the recordset.
+ */
+export declare const readColumns: (prefix?: string) => string;
+/**
+ * The alias the append body gives the expanded `new_events` recordset — the `ne`
+ * CTE in `ddl.ts` — which every expression in `EVENT_COLUMN_SOURCE` reads from.
+ * Exported so the CTE is declared under the one name its readers assume.
+ */
+export declare const RECORDSET_ALIAS = "ne";
+/**
+ * The bare event column names — `type, data, tags, uuid, occurred_at, metadata` —
+ * which the append body uses twice: as the recordset CTE's projection and as the
+ * `INSERT INTO t (…)` target list.
+ */
+export declare const eventColumnList: string;
+/**
+ * The append insert's SELECT list: one source expression per column, in the SAME
+ * ORDER as `eventColumnList`.
+ *
+ * The two halves of `INSERT INTO t (a, b) SELECT x, y` agree POSITION BY POSITION
+ * and nothing checks that they do: two columns of compatible type swap without an
+ * error at any layer and the data lands in the wrong one. Both halves are therefore
+ * one walk of the one descriptor, so the append body has no second ordering to keep
+ * in step and no hand-written list for a new column to be missing from.
+ */
+export declare const eventInsertSelectList: string;
+/**
+ * The allowed-types filter for a candidate row aliased `m`: an item with no
+ * types matches ANY type; otherwise the event's type must be one of them.
+ * `typesCol` is the `text[]` column holding the item's types — `q.allowed_types`
+ * for a tagged match, `qi.types` for a tagless one.
+ */
+export declare const allowedTypesPredicate: (typesCol: string) => string;
+/** The placeholder tokens + pre-quoted table names one call site binds. */
+export interface MatchTokens {
+    /** SQL yielding the query-items jsonb: `query_items` or `$1::jsonb`. */
+    readonly queryItemsExpr: string;
+    /** SQL for the exclusive lower bound: `COALESCE(after_id, 0)` or `$2`. */
+    readonly afterExpr: string;
+    /** Pre-quoted main events table. */
+    readonly main: string;
+    /** Pre-quoted tag junction table. */
+    readonly tag: string;
+}
+/**
+ * The tag-first match CTE chain shared by the read and conflict paths: expand
+ * the query items (`qi`), join the tag junction, count DISTINCT matched tags per
+ * (event, item), and keep events matching an item's FULL tag superset. Returns
+ * `qi, initial_matches, matched_groups, qualified_ids` — the caller follows it
+ * with a projection CTE selecting from `qualified_ids`.
+ *
+ * ## Both sides of the count are SET SIZES, and that is the whole invariant
+ *
+ * `qualified_ids` compares two numbers, and the ONE thing an edit here must
+ * preserve is that they count the same kind of thing: `matched_tag_count` is the
+ * number of DISTINCT tags the event carried out of the item's requirement, so
+ * `required_tag_count` is the size of that requirement AS A SET and never the
+ * length of the list it arrived as. A query item may list one tag twice — no
+ * constructor de-duplicates, `assertServableQuery` admits it and
+ * `classifyServableQuery` routes it here — and the in-memory oracle folds an
+ * item's tags into a superset test that a repeat cannot change. Comparing a
+ * de-duplicated 1 against a list length of 2 refused such a match: the READ
+ * returned nothing and, because the plpgsql conflict body composes this same
+ * chain, the GUARD found no conflict and the append it should have refused
+ * succeeded — an optimistic-concurrency check that escaped silently.
+ *
+ * The asymmetry has two repairs — de-duplicate both sides, or expand both — and
+ * only the first is available here. The matched side CANNOT become a plain row
+ * count, because this engine's junction holds one row per (tag, event) OCCURRENCE
+ * and not per pair, so an event whose own `tags` list repeats a tag has two rows
+ * there and a row count would refuse a single-tag item against it. `ddl.ts` states
+ * that property on the junction, and it is what `COUNT(DISTINCT tag)` is here to
+ * absorb; the requirement is de-duplicated to meet it.
+ *
+ * `required_tag_count` is therefore computed in `qi`, once per ITEM, rather than
+ * in the group that consumes it — the chain groups per (event, item), so a
+ * subquery in `matched_groups` would be re-evaluated per matched event. It is
+ * `count(*)` over a `SELECT DISTINCT` rather than `count(DISTINCT …)` because the
+ * latter drops a NULL element: a `[tag, NULL]` requirement would shrink to 1,
+ * meet a single matched tag and match, where the oracle's superset test cannot be
+ * satisfied by a NULL and refuses it.
+ *
+ * The `array_length(qi.tags, 1) >= 1` guard excludes tagless items from the
+ * tagged branch (load-bearing for the conflict body, which also has a separate
+ * tagless branch; a no-op for the read, whose tagged shape is all-tagged). It
+ * reads the item's own array because it is a test of the item's SHAPE — tagged or
+ * tagless — and not part of the match arithmetic above.
+ */
+export declare const taggedMatchChain: (tokens: MatchTokens) => string;
+/**
+ * The shared qualified-rows source: join `qualified_ids` back to the main table
+ * (aliased `m`), re-apply the exclusive `after` bound, and filter by allowed
+ * types. The read wraps this in an ordered/limited `DISTINCT m.id` CTE; the
+ * conflict wraps it in a `SELECT 1 … LIMIT 1` existence probe.
+ */
+export declare const qualifiedRows: (tokens: Pick<MatchTokens, "main" | "afterExpr">) => string;
+/** The wildcard read (no items): every event after the bound, ordered/limited. */
+export declare const wildcardReadSql: (main: string) => string;
+/** The type-only read (single tagless item): filter by `type = ANY($2)`. */
+export declare const typeOnlyReadSql: (main: string) => string;
+/**
+ * The tagged read: the shared match chain, then a `filtered_ids` CTE that orders
+ * and limits the qualified ids by position, then a full-row select. Bound params
+ * are `$1` = query-items jsonb, `$2` = exclusive `after`, `$3` = limit (`NULL` =
+ * no limit).
+ */
+export declare const taggedReadSql: (main: string, tag: string) => string;
+export {};
+//# sourceMappingURL=matchSql.d.ts.map

package/dist/dts-esm/internal/matchSql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchSql.d.ts","sourceRoot":"","sources":["../../../src/internal/matchSql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;GAUG;AACH,QAAA,MAAM,aAAa,kMASlB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAExB,CAAA;AAEZ;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,eAAW,KAAG,MAGvC,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,OAAO,CAAA;AAgCnC;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAE7B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAExB,CAAA;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,MACkD,CAAA;AAE3G,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,WAAW,KAAG,MA6BnD,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC,KAC9C,MAImD,CAAA;AAEtD,kFAAkF;AAClF,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MAKnC,CAAA;AAEZ,4EAA4E;AAC5E,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MAKnC,CAAA;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,KAAG,MAWtC,CAAA"}

package/dist/dts-esm/internal/readPlan.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The read-plan compiler for the Postgres engine, extracted from `store.ts` so it
+ * is a self-contained unit depending only on the PRE-QUOTED table names — never on
+ * the SQL clients. `store.ts`'s `read` and its `subscribe` — the latter feeding the
+ * plan to core's subscribe machine as that machine's `fetch` seam — both compile a
+ * plan here and run it against whichever client they hold.
+ *
+ * `compileFetchPlan` turns a servable `Query` into prepared SQL text plus a
+ * cursor-only `bind`, so a long-lived subscription re-binds only the cursor rather
+ * than re-dispatching the shape and re-serialising the query JSON on every poll.
+ * Which shape a query IS is not decided here: core's `classifyServableQuery` owns
+ * that dispatch beside the grammar it dispatches over (`Query.ts`), including the
+ * degenerate empty item's routing. The JSON/JSONB transport shapes and
+ * (de)serialisers — `EventRow`, `jsonbText`, `toQueryItemsJson`, `rowToSequenced`
+ * — live in `internal/transport.ts`, and this module only compiles plans.
+ *
+ * A plan compiled here is therefore the one place the Postgres engine dispatches
+ * a shape in TypeScript, and the exhaustiveness below protects BOTH verbs that
+ * compile one — `read`, and the `subscribe` poll sharing its plan. What it cannot
+ * reach is the append: its conflict guard covers the same three shapes inside its
+ * plpgsql body, where no compiler follows, and `ddl.ts` owns what that rests on
+ * instead.
+ */
+import type { Position, ReadLimit } from '@kairos-es/core';
+import { type Query } from '@kairos-es/core';
+import type { Effect } from 'effect';
+import type { SqlClient, SqlError } from 'effect/sql';
+import { type EventRow } from './transport.js';
+/** The pre-quoted table names a plan reads from (see `quoteQualified`). */
+export interface ReadTables {
+    /** Pre-quoted main events table. */
+    readonly main: string;
+    /** Pre-quoted tag junction table. */
+    readonly tag: string;
+}
+/**
+ * A COMPILED read plan: the prepared SQL text plus a `bind` that produces the
+ * positional params for a given `after`/`limit`. Everything
+ * query-dependent-but-cursor-independent — the shape dispatch, the SQL text, the
+ * query-items JSON serialisation — is done ONCE, so a long-lived subscription's
+ * poll loop re-binds only the cursor rather than re-classifying and re-JSON-
+ * serialising on every iteration.
+ */
+export interface FetchPlan {
+    readonly text: string;
+    readonly bind: (after: Position, limit: ReadLimit | null) => ReadonlyArray<unknown>;
+}
+/**
+ * Compile a servable query into a `FetchPlan`. The SQL comes from the shared
+ * `matchSql` builders (the tagged path composes the same emitted match chain as the
+ * conflict check, which binds its own placeholder tokens and wraps it differently),
+ * with the pre-quoted names embedded and the VALUES bound as `$n` parameters
+ * (never interpolated).
+ *
+ * The `switch` is exhaustive over core's `ServableQueryShape` with NO `default`
+ * and no trailing fall-through arm, and what that buys is a COMPILE error where
+ * there would otherwise be a silent mis-serve. Core owns that union and this
+ * module only consumes it, so a fourth member added there is a change this file
+ * cannot see coming: a cascade ending in an unguarded tagged branch would have
+ * SERVED that shape as tagged, and both `read` and the `subscribe` poll sharing
+ * its plan would have returned the wrong rows — no error raised, nothing failing
+ * to typecheck. Every arm returns instead, so the added member leaves this
+ * function with a reachable end and a return type that does not admit
+ * `undefined`, and the module stops compiling.
+ */
+export declare const compileFetchPlan: (tables: ReadTables, query: Query) => FetchPlan;
+/**
+ * Run a compiled plan for a given `after`/`limit`, honouring `after` (exclusive;
+ * absent → `0`) and `limit` (`NULL` = no limit), ordered by `id ASC`.
+ */
+export declare const runFetch: (sql: SqlClient.SqlClient, plan: FetchPlan, after: Position | undefined, limit: ReadLimit | undefined) => Effect.Effect<ReadonlyArray<EventRow>, SqlError.SqlError>;
+//# sourceMappingURL=readPlan.d.ts.map

package/dist/dts-esm/internal/readPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readPlan.d.ts","sourceRoot":"","sources":["../../../src/internal/readPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAiC,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErD,OAAO,EAAE,KAAK,QAAQ,EAA+B,MAAM,aAAa,CAAA;AAExE,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,CACb,KAAK,EAAE,QAAQ,EACf,KAAK,EAAE,SAAS,GAAG,IAAI,KACpB,aAAa,CAAC,OAAO,CAAC,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,UAAU,EAClB,OAAO,KAAK,KACX,SAiCF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,SAAS,CAAC,SAAS,EACxB,MAAM,SAAS,EACf,OAAO,QAAQ,GAAG,SAAS,EAC3B,OAAO,SAAS,GAAG,SAAS,KAC3B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,CACiB,CAAA"}

package/dist/dts-esm/internal/transport.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The JSON/JSONB transport for the Postgres engine: the wire shapes and the
+ * (de)serialisers that carry an event batch / query items ACROSS the boundary into
+ * the append functions, and map a raw driver row BACK to a core `SequencedEvent`.
+ * Extracted from `store.ts` (the write side) and `internal/readPlan.ts` (the read
+ * side) so the transport concept lives in ONE module rather than being split
+ * across the write path and the read-plan compiler — the module name now predicts
+ * where transport code lives, and the two per-column type maps (`EventJson`,
+ * `EventRow`) sit next to each other rather than in two files.
+ *
+ * The event column contract stays single-sourced on `EventColumnName`
+ * (`internal/matchSql.ts`), the one column-NAME descriptor: both type maps here
+ * are mapped types over it, so a column rename in `EVENT_COLUMNS` is a COMPILE
+ * error in this module, never a silent transport drift the lax read boundary
+ * (ADR-0006) would only surface as corrupt data under test.
+ *
+ * The read boundary (`rowToSequenced`) is the trusted, deliberately-lax
+ * deserialisation point (ADR-0006 store-laxness); the write boundary
+ * (`toEventJson`) serialises `data` as base64 text and domain time as an ISO
+ * string, both restored in SQL.
+ */
+import type { DcbEvent, Metadata, Query, SequencedEvent } from '@kairos-es/core';
+import type { EventColumnName } from './matchSql.js';
+/**
+ * Serialise a value to a JSON STRING for transport as a `::jsonb`-cast bound
+ * parameter.
+ *
+ * WHY a string and not `sql.json(value)`: the read plan runs through
+ * `sql.unsafe(text, params)` with POSITIONAL parameters, and a positional
+ * parameter must be a plain scalar or a flat array of scalars — `@effect/sql-pg`
+ * cannot infer a Postgres type for an object or an array of objects, and a
+ * `sql.json` fragment is not a value that list can carry. A pre-stringified
+ * JSON string binds untyped and the `::jsonb` cast has Postgres parse it, which
+ * round-trips reliably for both objects and arrays on the positional path and
+ * the tagged-template path alike. Kept as a named helper so every
+ * JSON-transport call site is consistent and the reasoning lives in one place.
+ */
+export declare const jsonbText: (value: unknown) => string;
+/** The JSON shape of one query item: types OR-filter, tags AND-superset. */
+export interface QueryItemJson {
+    readonly types: ReadonlyArray<string>;
+    readonly tags: ReadonlyArray<string>;
+}
+/** Serialise a `Query`'s items into their transport JSON shape. */
+export declare const toQueryItemsJson: (query: Query) => ReadonlyArray<QueryItemJson>;
+/**
+ * The per-column TS types of the transport JSON shape — one entry per
+ * `EVENT_COLUMNS` name. `data` is base64 TEXT and `occurred_at` an ISO string
+ * (both restored in SQL: `decode(…, 'base64')` / `timestamptz`); `metadata`
+ * travels as a nested JSON object, which `jsonb_to_recordset` hands to the
+ * insert as `jsonb` untouched; the rest map straight across. Kept as a plain
+ * map so `EventJson` below is a mapped type over the ONE column descriptor
+ * rather than a hand-restated column list.
+ */
+interface EventJsonColumns {
+    readonly type: string;
+    readonly data: string;
+    readonly tags: ReadonlyArray<string>;
+    readonly uuid: string;
+    readonly occurred_at: string;
+    readonly metadata: Metadata;
+}
+/**
+ * The JSON shape of one event as sent to the append functions, as a mapped type
+ * over the shared `EventColumnName` descriptor (`internal/matchSql.ts`). `data`
+ * is base64 text (restored to `bytea` by `decode(…, 'base64')` in plpgsql);
+ * `occurred_at` is an ISO string parsed by `timestamptz`. Because the keys come
+ * from the same descriptor that builds the `jsonb_to_recordset(new_events)`
+ * column list, the two cannot drift — rename a column in `EVENT_COLUMNS` and this
+ * mapped type stops compiling (the old key is gone from `EventJsonColumns`).
+ */
+export type EventJson = {
+    readonly [K in EventColumnName]: EventJsonColumns[K];
+};
+/** Serialise one core `DcbEvent` into its transport JSON shape. */
+export declare const toEventJson: (event: DcbEvent) => EventJson;
+/**
+ * The per-column TS types of a raw driver row — one entry per `EVENT_COLUMNS`
+ * name. These are the JS types `@effect/sql-pg`'s default binary codecs decode
+ * to: `data` a `Uint8Array` (or null for a payload-less event), `occurred_at` a
+ * JS `Date`, `tags` a `string[]`, `metadata` whatever the driver parses a
+ * `jsonb` value into — declared
+ * `unknown`, because `jsonb` is the one column here whose SQL type does not
+ * fix its JS shape, and `metadataFrom` below is where it is checked. `id`
+ * (the `bigserial` position) is NOT here — it is prepended by the read projection
+ * and absent from the events recordset, so it sits outside the shared descriptor.
+ */
+interface EventRowColumns {
+    readonly type: string;
+    readonly data: Uint8Array | null;
+    readonly tags: ReadonlyArray<string>;
+    readonly uuid: string;
+    readonly occurred_at: Date;
+    readonly metadata: unknown;
+}
+/**
+ * A raw row from the main table as the driver returns it, as `id` plus a
+ * mapped type over the shared `EventColumnName` descriptor. `id` is `int8`, which
+ * the driver's default codec hands back as a `bigint` (JS `number` is unsafe past
+ * 2^53). `rowToSequenced` still passes it through `BigInt(…)`, so a client
+ * configured with its own `int8` codec that yields the decimal string instead
+ * still mints a real `bigint` position.
+ * The payload columns cannot drift from the read projection: a rename in
+ * `EVENT_COLUMNS` breaks this mapped type.
+ */
+export type EventRow = {
+    readonly id: bigint | string;
+} & {
+    readonly [K in EventColumnName]: EventRowColumns[K];
+};
+/**
+ * Map a raw main-table row to a core `SequencedEvent`. `data` NULL → empty bytes
+ * (a payload-less event round-trips to a zero-length `Uint8Array`); `occurred_at`
+ * Date → `DateTime.Utc`; `id` → branded `Position`; `metadata` through
+ * `metadataFrom`. The column is `NOT NULL DEFAULT '{}'`, so there is no absent
+ * case to reconcile: an event appended with an empty bag reads back as `{}` on
+ * this engine exactly as on the in-memory oracle.
+ *
+ * The branded scalars (`type`, `tags`, `uuid`, `position`) are minted by trusted
+ * `as`-cast, NOT by re-running `EventType.make` / `Tag.make` etc. This is
+ * deliberate: these bytes were validated at write time, and the store schema is
+ * intentionally LAX on read (ADR-0006 store-laxness — hand-assembled or pre-ADR
+ * events must remain readable), so re-validating here could REJECT a legitimately
+ * stored value and break that contract. It mirrors the in-memory oracle, which
+ * likewise mints branded positions by cast at its trusted allocation boundary
+ * (`inMemory.ts`). The read boundary is the analogous trusted deserialisation
+ * point.
+ */
+export declare const rowToSequenced: (row: EventRow) => SequencedEvent;
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/dist/dts-esm/internal/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/internal/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,QAAQ,EAER,KAAK,EACL,cAAc,EACf,MAAM,iBAAiB,CAAA;AAGxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAA+B,CAAA;AAE1E,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACrC;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,aAAa,CAItE,CAAA;AAEL;;;;;;;;GAQG;AACH,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,eAAe,GAAG,gBAAgB,CAAC,CAAC,CAAC;CAAE,CAAA;AAEhF,mEAAmE;AACnE,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,KAAG,SAW5C,CAAA;AAEF;;;;;;;;;;GAUG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG;IACxD,QAAQ,EAAE,CAAC,IAAI,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC;CACpD,CAAA;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,QAAQ,KAAG,cAU7C,CAAA"}

package/dist/dts-esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/dts-esm/store.d.ts

@@ -0,0 +1,17 @@
+import { DcbEventStore } from '@kairos-es/core';
+import { Layer } from 'effect';
+import { PgClientDirect, PgClientPooled } from './clients.js';
+import { type PostgresStoreConfig } from './config.js';
+/**
+ * The Postgres `DcbEventStore` layer factory. Builds the engine over
+ * `PgClientPooled` (reads/append/notify) and `PgClientDirect` (the subscribe
+ * listener). The caller wires those two client layers — pointing `PgClientDirect`
+ * at a direct (non-pooler) endpoint on Neon, or at the same URL as `PgClientPooled`
+ * everywhere else.
+ *
+ * `ensureSchema(config)` must have been run (by the caller's migrator or at
+ * boot) before the layer is used; the layer itself performs no DDL, so it stays
+ * a pure runtime dependency requiring only the two clients.
+ */
+export declare const layer: (config?: PostgresStoreConfig) => Layer.Layer<DcbEventStore, never, PgClientPooled | PgClientDirect>;
+//# sourceMappingURL=store.d.ts.map

package/dist/dts-esm/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAiDA,OAAO,EAGL,aAAa,EAQd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAA6B,KAAK,EAAsB,MAAM,QAAQ,CAAA;AAE7E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AA2U9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,SAAQ,mBAAwB,KAC/B,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CASnE,CAAA"}