@kairos-es/store-postgres 0.0.0

package/dist/dts/ensureSchema.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `ensureSchema` — the idempotent DDL migration building block (ADR-0002).
+ *
+ * This is deliberately NOT a migrator. It is a single `Effect<void, SqlError,
+ * SqlClient>` that creates (or refreshes) every object a store owns: both
+ * tables, both indexes, and both plpgsql functions. It requires the GENERIC
+ * `SqlClient` tag — NOT `PgClientPooled` — precisely so a consumer can drop it
+ * straight into THEIR OWN migrator, e.g.:
+ *
+ * ```ts
+ * Migrator.fromRecord({
+ *   '0001_kairos_store_dcb_events': ensureSchema(config),
+ * })
+ * ```
+ *
+ * or simply run it once at boot. We ship no `FileSystem`/`Path`/`ChildProcess`
+ * dependency and no `PgMigrator`; migration ORCHESTRATION belongs to the
+ * consumer, this package only provides the idempotent PAYLOAD.
+ *
+ * Idempotence: every statement is `CREATE … IF NOT EXISTS` or `CREATE OR REPLACE
+ * FUNCTION`, so re-running against an existing store is a no-op. Names come from
+ * `sql(identifier)` (via the pre-quoted builder in `internal/ddl.ts`); the DDL
+ * bodies carry no bound values (pure schema), and the append functions keep
+ * their runtime VALUES as bound parameters, never interpolated.
+ */
+import { SqlClient, type SqlError } from '@effect/sql';
+import { Effect } from 'effect';
+import { type PostgresStoreConfig } from './config.js';
+/**
+ * Produce the migration payload for `config`. Resolves the object names once and
+ * runs the ordered idempotent DDL against whatever `SqlClient` the caller's
+ * migrator (or boot code) provides.
+ */
+export declare const ensureSchema: (config: PostgresStoreConfig) => Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+//# sourceMappingURL=ensureSchema.d.ts.map

package/dist/dts/ensureSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSchema.d.ts","sourceRoot":"","sources":["../../src/ensureSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG9E;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,mBAAmB,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CAQzD,CAAA"}

package/dist/dts/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 tags and
+ * assumes `ensureSchema` has run. `ensureSchema` requires the generic `SqlClient`
+ * tag so it slots into any migrator; the runtime uses the store-owned tags.
+ */
+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/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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/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/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,aAAa,CAAA;AAQvD;;;;;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;AAuND;;;;;;;;;;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,CA+DxE,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/internal/matchSql.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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"]];
+/**
+ * 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`. 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 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/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,kKAQlB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAExB,CAAA;AAEZ;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,eAAW,KAAG,MAGvC,CAAA;AAEH;;;;;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/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 { SqlClient, SqlError } from '@effect/sql';
+import type { Position, ReadLimit } from '@kairos-es/core';
+import { type Query } from '@kairos-es/core';
+import type { Effect } from 'effect';
+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/internal/readPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readPlan.d.ts","sourceRoot":"","sources":["../../../src/internal/readPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,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;AAEpC,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,SA6BF,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/internal/subscribe.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The subscribe machine for the Postgres engine, extracted from `store.ts`. It owns
+ * the wake queue, the listener drain, the paged catch-up reconcile, the `> boundary`
+ * de-dup (via the cursor's exclusive lower bound), and the poll loop — all behind
+ * two STUBBABLE seams (`fetch`, `listen`), so the wake/poll/dedup logic is
+ * UNIT-TESTABLE with no live database (see `test/subscribe.test.ts`). `store.ts`
+ * supplies production `fetch`/`listen` built from the pooled/direct clients.
+ *
+ * Correctness rests on the periodic position-based reconcile — a re-read from the
+ * cursor every poll interval — NOT on `NOTIFY`, which is only a latency
+ * optimisation. Exclusive-lock commit order equals sequence order, so an
+ * ascending re-read never skips a temporary gap; permanent bigserial gaps are
+ * simply absent positions and are fine to skip.
+ *
+ * ## `catchUpPageSize` bounds the STATEMENT, not the emission
+ *
+ * `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds each
+ * `SELECT` — but it COLLECTS every page into one array, which is emitted as a
+ * SINGLE chunk. So peak memory at subscription start is O(backlog) rather than
+ * O(page): a subscriber joining behind a large log materialises the whole backlog
+ * before its consumer sees the first element.
+ *
+ * That is a memory characteristic and nothing more, which is why ONE chunk is
+ * enough here: downstream commit boundaries do not depend on the upstream chunking
+ * at all, because the read side's `Stream.groupedWithin` re-chunks the stream into
+ * bounded micro-batches whatever arrives (ADR-0007), so a projection's transactions
+ * stay small even against a one-chunk catch-up. The cost therefore lands on backlog
+ * memory alone, and it lands hardest on the durable-log-with-in-memory-view mode,
+ * where an ephemeral view re-catches-up the entire log on every boot.
+ */
+import type { SqlError } from '@effect/sql';
+import type { Position, SequencedEvent } from '@kairos-es/core';
+import { ReadLimit } from '@kairos-es/core';
+import { Effect, type Scope, Stream } from 'effect';
+/**
+ * A short catch-up page size default for the reconcile loop. Reads page by page
+ * until a short page signals the tail is drained, so a large backlog is streamed
+ * in bounded chunks rather than one huge SELECT. Overridable via
+ * `config.catchUpPageSize`.
+ */
+export declare const DEFAULT_CATCH_UP_PAGE = 512;
+/**
+ * The default upper bound a live subscriber waits for a wake before re-reading
+ * from its cursor ANYWAY (milliseconds; overridable via `config.pollInterval`).
+ * This periodic position-based poll — not `NOTIFY` — is the correctness
+ * guarantee: every committed position is reconciled within this interval
+ * regardless of whether its `NOTIFY` was heard, which covers a `NOTIFY` fired
+ * before `LISTEN` was fully established, a coalesced/lost `NOTIFY`, and a listen
+ * connection that dropped SILENTLY (the `@effect/sql-pg` listen client swallows
+ * connection errors and does not auto-reconnect). `NOTIFY` only lowers delivery
+ * latency below this interval. Upstream `postgres_tt.py` uses the same 1-second
+ * fallback poll (`conn.wait(..., interval=1)`).
+ */
+export declare const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
+/**
+ * The two seams the subscribe machine runs over, plus the two tuning knobs. In
+ * production `fetch` is a compiled read plan run against the pooled client and
+ * mapped to `SequencedEvent`s, and `listen` is `PgClientDirect.listen(channel)`;
+ * a unit test stubs both with plain in-memory values.
+ */
+export interface SubscriptionDeps {
+    /**
+     * Page-read the events strictly after `from`, up to `limit`, ascending by
+     * position. Returning FEWER than `limit` signals the tail is drained.
+     */
+    readonly fetch: (from: Position, limit: ReadLimit) => Effect.Effect<ReadonlyArray<SequencedEvent>, SqlError.SqlError>;
+    /**
+     * The raw wake source: each element is an opaque wake signal (a `NOTIFY`). The
+     * machine taps it into its own wake queue and drains it on a background fibre;
+     * it never reads the elements. `Stream.never` is a valid poll-only source.
+     */
+    readonly listen: Stream.Stream<unknown, SqlError.SqlError>;
+    /** The poll interval in milliseconds (see `DEFAULT_POLL_INTERVAL_MILLIS`). */
+    readonly pollInterval: number;
+    /** The catch-up page size (see `DEFAULT_CATCH_UP_PAGE`). */
+    readonly catchUpPage: number;
+}
+/**
+ * Build the subscription `Stream`: catch up from `after`, then track the live
+ * tail. The cursor threads through the `unfoldChunkEffect` unfold state, starting
+ * at `after` and advancing to the last delivered position each batch; the stream
+ * never completes on its own (always `Option.some`), so the enclosing scope
+ * interrupts it on close. A `SqlError` mid-stream stays on the channel;
+ * `makeContractStore` dies it (subscribe is `E = never` on the contract).
+ */
+export declare const subscribeStream: (deps: SubscriptionDeps, after: Position | undefined) => Stream.Stream<SequencedEvent, SqlError.SqlError, Scope.Scope>;
+//# sourceMappingURL=subscribe.d.ts.map

package/dist/dts/internal/subscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../../src/internal/subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAU,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,EAEL,MAAM,EAIN,KAAK,KAAK,EACV,MAAM,EACP,MAAM,QAAQ,CAAA;AAEf;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAchD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IACpE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,gBAAgB,EACtB,OAAO,QAAQ,GAAG,SAAS,KAC1B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAuG5D,CAAA"}