@kairos-es/store-postgres 0.0.0

package/src/internal/matchSql.ts

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+const EVENT_COLUMNS = [
+  ['type', 'text'],
+  ['data', 'text'],
+  ['tags', 'text[]'],
+  ['uuid', 'text'],
+  ['occurred_at', 'timestamptz'],
+] as const satisfies ReadonlyArray<
+  readonly [name: string, recordsetType: string]
+>
+
+/**
+ * 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 const eventRecordsetColumns: string = EVENT_COLUMNS.map(
+  ([name, type]) => `${name} ${type}`,
+).join(', ')
+
+/**
+ * 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 const readColumns = (prefix = ''): string =>
+  [`${prefix}id`, ...EVENT_COLUMNS.map(([name]) => `${prefix}${name}`)].join(
+    ', ',
+  )
+
+/**
+ * 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 const allowedTypesPredicate = (typesCol: string): string =>
+  `(array_length(${typesCol}, 1) IS NULL OR array_length(${typesCol}, 1) = 0 OR m.type = ANY(${typesCol}))`
+
+/** 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 const taggedMatchChain = (tokens: MatchTokens): string =>
+  `qi AS (
+    SELECT types, tags, ordinality,
+           -- Both sides of the match compare DISTINCT-TAG counts: this is the
+           -- requirement's SET size, never the length of the list it arrived as.
+           (SELECT count(*) FROM (SELECT DISTINCT req.tag FROM unnest(tags) AS req(tag)) d)
+             AS required_tag_count
+    FROM ROWS FROM(
+      jsonb_to_recordset(${tokens.queryItemsExpr}) AS (types text[], tags text[])
+    ) WITH ORDINALITY
+  ),
+  initial_matches AS (
+    SELECT t.main_id, qi.ordinality, qi.required_tag_count,
+           qi.types AS allowed_types, t.tag
+    FROM qi
+    JOIN ${tokens.tag} t ON t.tag = ANY(qi.tags)
+    WHERE t.main_id > ${tokens.afterExpr}
+      AND array_length(qi.tags, 1) >= 1
+  ),
+  matched_groups AS (
+    SELECT main_id, ordinality, required_tag_count, allowed_types,
+           COUNT(DISTINCT tag) AS matched_tag_count
+    FROM initial_matches
+    GROUP BY main_id, ordinality, required_tag_count, allowed_types
+  ),
+  qualified_ids AS (
+    SELECT main_id, allowed_types
+    FROM matched_groups
+    WHERE matched_tag_count = required_tag_count
+  )`
+
+/**
+ * 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 const qualifiedRows = (
+  tokens: Pick<MatchTokens, 'main' | 'afterExpr'>,
+): string =>
+  `FROM qualified_ids q
+    JOIN ${tokens.main} m ON m.id = q.main_id
+    WHERE m.id > ${tokens.afterExpr}
+      AND ${allowedTypesPredicate('q.allowed_types')}`
+
+/** The wildcard read (no items): every event after the bound, ordered/limited. */
+export const wildcardReadSql = (main: string): string =>
+  `SELECT ${readColumns()}
+   FROM ${main}
+   WHERE id > $1
+   ORDER BY id ASC
+   LIMIT $2`
+
+/** The type-only read (single tagless item): filter by `type = ANY($2)`. */
+export const typeOnlyReadSql = (main: string): string =>
+  `SELECT ${readColumns()}
+   FROM ${main}
+   WHERE id > $1 AND type = ANY($2)
+   ORDER BY id ASC
+   LIMIT $3`
+
+/**
+ * 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 const taggedReadSql = (main: string, tag: string): string =>
+  `WITH ${taggedMatchChain({ queryItemsExpr: '$1::jsonb', afterExpr: '$2', main, tag })},
+  filtered_ids AS (
+    SELECT DISTINCT m.id
+    ${qualifiedRows({ main, afterExpr: '$2' })}
+    ORDER BY m.id ASC
+    LIMIT $3
+  )
+  SELECT ${readColumns('m.')}
+  FROM ${main} m
+  WHERE m.id IN (SELECT id FROM filtered_ids)
+  ORDER BY m.id ASC`

package/src/internal/readPlan.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { classifyServableQuery, ORIGIN, type Query } from '@kairos-es/core'
+import type { Effect } from 'effect'
+import { taggedReadSql, typeOnlyReadSql, wildcardReadSql } from './matchSql'
+import { type EventRow, jsonbText, toQueryItemsJson } from './transport'
+
+/** 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 const compileFetchPlan = (
+  tables: ReadTables,
+  query: Query,
+): FetchPlan => {
+  const shape = classifyServableQuery(query)
+  switch (shape.kind) {
+    case 'wildcard':
+      return {
+        text: wildcardReadSql(tables.main),
+        bind: (after, limit) => [after, limit],
+      }
+    case 'typeOnly': {
+      // node-postgres binds a JS array param as a Postgres array literal, so
+      // `type = ANY($2)` matches any of the item's types. The item's own list is
+      // bound as it stands: a branded `EventType` IS its string to the driver, so
+      // nothing here has to unwrap or copy it.
+      const types = shape.types
+      return {
+        text: typeOnlyReadSql(tables.main),
+        bind: (after, limit) => [after, types, limit],
+      }
+    }
+    case 'tagged': {
+      // `after` ($2) is applied at BOTH CTE stages; `limit` ($3) inside the
+      // ordered filtered_ids so it caps by position, not on the outer join.
+      const itemsJson = jsonbText(toQueryItemsJson(query))
+      return {
+        text: taggedReadSql(tables.main, tables.tag),
+        bind: (after, limit) => [itemsJson, after, limit],
+      }
+    }
+  }
+}
+
+/**
+ * Run a compiled plan for a given `after`/`limit`, honouring `after` (exclusive;
+ * absent → `0`) and `limit` (`NULL` = no limit), ordered by `id ASC`.
+ */
+export const runFetch = (
+  sql: SqlClient.SqlClient,
+  plan: FetchPlan,
+  after: Position | undefined,
+  limit: ReadLimit | undefined,
+): Effect.Effect<ReadonlyArray<EventRow>, SqlError.SqlError> =>
+  sql.unsafe<EventRow>(plan.text, plan.bind(after ?? ORIGIN, limit ?? null))

package/src/internal/transport.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 5-column event 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, Position, Query, SequencedEvent } from '@kairos-es/core'
+import { DateTime, Encoding } from 'effect'
+import type { EventColumnName } from './matchSql'
+
+/**
+ * Serialise a value to a JSON STRING for transport as a `::jsonb`-cast bound
+ * parameter.
+ *
+ * WHY not `sql.json(value)`: `@effect/sql-pg`'s `json` helper binds the RAW
+ * value, and node-postgres serialises a JS *array* bound param as a Postgres
+ * ARRAY literal (`{…}`), not JSON — so `sql.json([...])::jsonb` fails with a
+ * `22P02` invalid-JSON error (an array literal is not valid JSON). Passing a
+ * pre-stringified JSON string and casting `::jsonb` sends plain text that
+ * Postgres parses as JSON, which round-trips reliably for both objects and
+ * arrays. Kept as a named helper so every JSON-transport call site is consistent
+ * and the reasoning lives in one place.
+ */
+export const jsonbText = (value: unknown): string => JSON.stringify(value)
+
+/** 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 const toQueryItemsJson = (query: Query): ReadonlyArray<QueryItemJson> =>
+  query.items.map((item) => ({
+    types: [...item.types],
+    tags: [...item.tags],
+  }))
+
+/**
+ * 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`); 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
+}
+
+/**
+ * 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 const toEventJson = (event: DcbEvent): EventJson => ({
+  type: event.type,
+  // `Encoding.encodeBase64` (from `effect`) keeps this dependency-free and pure
+  // — no `Buffer`, so no `@types/node` and no browser/runtime coupling.
+  data: Encoding.encodeBase64(event.data),
+  tags: [...event.tags],
+  uuid: event.uuid,
+  occurred_at: DateTime.formatIso(event.occurredAt),
+})
+
+/**
+ * The per-column TS types of a raw driver row — one entry per `EVENT_COLUMNS`
+ * name. These are node-postgres's decoded JS types: `data` a `Buffer` (or null
+ * for a payload-less event), `occurred_at` a JS `Date`, `tags` a `string[]`. `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
+}
+
+/**
+ * A raw row from the main table as node-postgres returns it, as `id` plus a
+ * mapped type over the shared `EventColumnName` descriptor. `id` is `int8`, which
+ * the driver hands back as a decimal STRING (JS `number` is unsafe past 2^53).
+ * The payload columns cannot drift from the read projection: a rename in
+ * `EVENT_COLUMNS` breaks this mapped type.
+ */
+export type EventRow = { readonly id: 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` string → branded `Position`.
+ *
+ * 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 const rowToSequenced = (row: EventRow): SequencedEvent => ({
+  event: {
+    type: row.type as DcbEvent['type'],
+    data: row.data ?? new Uint8Array(0),
+    tags: row.tags as unknown as DcbEvent['tags'],
+    uuid: row.uuid as DcbEvent['uuid'],
+    occurredAt: DateTime.unsafeFromDate(row.occurred_at),
+  },
+  position: BigInt(row.id) as Position,
+})