@kronos-ts/postgres 0.1.0

package/src/adapters/postgres.ts

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

package/src/advisory-locks.ts

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

package/src/criteria-sql.ts

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

package/src/errors.ts

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

package/src/index.ts

@@ -0,0 +1,56 @@
+// Public entry point for @kronos-ts/postgres.
+//
+// Wave-1 only exports the error surface; subsequent waves layer in:
+//   Plan 04 — postgres() extension factory + PostgresConfig (./postgres.js),
+//             createPostgresEventStore (./postgres-event-store.js)
+//   Plan 05 — createPostgresSnapshotStore (./postgres-snapshot-store.js)
+//
+// Adapter implementations are NOT exported from this barrel — users import
+// them via the sub-path exports declared in package.json:
+//   import { pgAdapter } from "@kronos-ts/postgres/adapters/pg"
+
+export {
+  AppendConditionError,
+  KRONOS_DCB_VIOLATION_SQLSTATE,
+  isDcbViolation,
+} from "./errors.js"
+
+// Adapter contract types (re-export so users can write
+// `function myFn(adapter: PostgresAdapter)` against the package root).
+// Adapter implementations stay sub-path-only.
+export {
+  IsolationLevel,
+  type PostgresAdapter,
+  type PostgresAdapterTransaction,
+  type ListenSubscription,
+  type QueryRow,
+} from "./adapter.js"
+
+// Engine factory (Plan 04 + extended in Plan 05)
+export {
+  createPostgresEventStore,
+  type PostgresEventStoreConfig,
+  type Serializer,
+  type TagResolver,
+} from "./postgres-event-store.js"
+
+// Snapshot store factory (Plan 05)
+export {
+  createPostgresSnapshotStore,
+  type PostgresSnapshotStoreConfig,
+} from "./postgres-snapshot-store.js"
+
+// Extension factory (Plan 05)
+export { postgres, type PostgresConfig } from "./postgres.js"
+
+// Schema bootstrap + DDL builders — exposed for users who want to run their
+// own migrations (set `postgres({ bootstrap: false })`) or drive the store
+// directly without going through the extension factory.
+export {
+  bootstrapSchema,
+  buildEventsTableDDL,
+  buildEventsIndexesDDL,
+  buildSnapshotsTableDDL,
+  DEFAULT_TABLE_NAMES,
+  type TableNames,
+} from "./schema.js"