@kairos-es/store-postgres 1.0.0-alpha.3 → 1.0.0-alpha.5

package/src/clients.ts

@@ -1,69 +1,81 @@
 /**
  * The TWO store-owned Postgres clients — the "Neon trap" mitigation (ADR-0002).
  *
- * `@effect/sql-pg` exposes a single `PgClient` (and `SqlClient`) tag; a
+ * `@effect/sql-pg` exposes a single `PgClient` (and `SqlClient`) service; a
  * `PgClient.layer` claims BOTH. If we built two `PgClient.layer`s they would
- * collide on that one tag — the second would shadow the first. So instead we
- * define two DISTINCT `Context.Tag`s, each HOLDING a `PgClient` value:
+ * collide on that one key — the second would shadow the first. So instead we
+ * define two DISTINCT `Context.Service`s, each HOLDING a `PgClient` value:
  *
  * - `PgClientPooled` — the pooled client used for reads, the append function,
- *   and `notify`. Backed by a `pg.Pool`; connections are recycled per query.
+ *   and `notify`. Its statements borrow a connection from the client's pool per
+ *   query.
  * - `PgClientDirect` — a client used ONLY by `subscribe`'s `listen`. Its
- *   built-in `listen` constructs a STANDALONE `pg.Client` from the pool's
- *   `options`, inheriting the pool's host. On a Neon POOLED endpoint
- *   (`…-pooler…`) that standalone connection lands on the PgBouncer front door,
- *   which SILENTLY DROPS `LISTEN`/`NOTIFY` — the subscription would simply never
+ *   built-in `listen` RESERVES a connection from that client's own pool and
+ *   holds it for the life of the subscription, so the listening session lives
+ *   on whatever host the client was configured with. On a Neon POOLED endpoint
+ *   (`…-pooler…`) that session is a PgBouncer front-door connection, which
+ *   SILENTLY DROPS `LISTEN`/`NOTIFY` — the subscription would simply never
  *   wake. Pointing `PgClientDirect` at Neon's DIRECT (non-pooler) endpoint fixes
  *   it. `subscribe` is the ONLY method that touches `PgClientDirect`.
  *
- * For a plain (non-Neon) Postgres both tags point at the same URL; the split
- * costs nothing there. The two-tag design is what makes the Neon fix a
+ * Because each live subscription holds one of `PgClientDirect`'s pooled
+ * connections until it closes, that client's `maxConnections` is also the number
+ * of subscriptions that can be listening at once. A subscription past it waits
+ * for a connection on its wake fibre only — delivery still proceeds at the poll
+ * rate meanwhile (see `store.ts`) — so size the direct client for the expected
+ * subscriber count rather than for query throughput.
+ *
+ * For a plain (non-Neon) Postgres both services point at the same URL; the split
+ * costs nothing there. The two-service design is what makes the Neon fix a
  * deployment-time wiring choice rather than a code change.
  */
-import { Reactivity } from '@effect/experimental'
-import type { SqlError } from '@effect/sql'
 import { PgClient } from '@effect/sql-pg'
 import { Context, Layer } from 'effect'
+import { Reactivity } from 'effect/reactivity'
+import type { SqlError } from 'effect/sql'
 
 /**
- * The pooled client tag: reads, the append function, and `notify`. Holds a
+ * The pooled client service: reads, the append function, and `notify`. Holds a
  * `PgClient` value rather than being a `PgClient.layer`, so it never collides
- * with the direct client on the shared `PgClient`/`SqlClient` tag.
+ * with the direct client on the shared `PgClient`/`SqlClient` key.
  */
-export class PgClientPooled extends Context.Tag(
-  '@kairos-es/store-postgres/PgClientPooled',
-)<PgClientPooled, PgClient.PgClient>() {}
+export class PgClientPooled extends Context.Service<
+  PgClientPooled,
+  PgClient.PgClient
+>()('@kairos-es/store-postgres/PgClientPooled') {}
 
 /**
- * The direct (non-pooler) client tag: the `subscribe` listener ONLY. Point this
- * at a direct endpoint on Neon so `LISTEN`/`NOTIFY` is not dropped by the pooler.
+ * The direct (non-pooler) client service: the `subscribe` listener ONLY. Point
+ * this at a direct endpoint on Neon so `LISTEN`/`NOTIFY` is not dropped by the
+ * pooler.
  */
-export class PgClientDirect extends Context.Tag(
-  '@kairos-es/store-postgres/PgClientDirect',
-)<PgClientDirect, PgClient.PgClient>() {}
+export class PgClientDirect extends Context.Service<
+  PgClientDirect,
+  PgClient.PgClient
+>()('@kairos-es/store-postgres/PgClientDirect') {}
 
 /**
- * Build a `PgClientPooled` layer from a `PgClient` config. We construct the
- * client via `PgClient.make` (scoped) and place it in our OWN tag, then provide
- * `Reactivity.layer` (which `PgClient.make` requires) — exactly what the
+ * Build a `PgClientPooled` layer from a `PgClient` pool config. We construct the
+ * client via `PgClient.make` (scoped) and place it in our OWN service, then
+ * provide `Reactivity.layer` (which `PgClient.make` requires) — exactly what the
  * built-in `PgClient.layer` does internally, minus the collision-prone claim on
- * the shared `PgClient` tag.
+ * the shared `PgClient` key.
  */
 export const pooledLayer = (
-  config: PgClient.PgClientConfig,
+  config: PgClient.PgPoolConfig,
 ): Layer.Layer<PgClientPooled, SqlError.SqlError> =>
-  Layer.scoped(PgClientPooled, PgClient.make(config)).pipe(
+  Layer.effect(PgClientPooled, PgClient.make(config)).pipe(
     Layer.provide(Reactivity.layer),
   )
 
 /**
- * Build a `PgClientDirect` layer from a `PgClient` config. Same construction as
+ * Build a `PgClientDirect` layer from a `PgClient` pool config. Same construction as
  * `pooledLayer`; the two differ only in which endpoint the caller points them
  * at (and that only matters on Neon).
  */
 export const directLayer = (
-  config: PgClient.PgClientConfig,
+  config: PgClient.PgPoolConfig,
 ): Layer.Layer<PgClientDirect, SqlError.SqlError> =>
-  Layer.scoped(PgClientDirect, PgClient.make(config)).pipe(
+  Layer.effect(PgClientDirect, PgClient.make(config)).pipe(
     Layer.provide(Reactivity.layer),
   )

package/src/config.ts

@@ -28,9 +28,9 @@ import { oversizedIdentifier } from './internal/ddl'
  * `sql(identifier)` dot-splits, so an embedded dot would silently re-partition
  * the name into the wrong schema/object.
  */
-const IdentifierAtom = Schema.String.pipe(
-  Schema.nonEmptyString(),
-  Schema.pattern(/^[^.]+$/, {
+const IdentifierAtom = Schema.String.check(
+  Schema.isNonEmpty(),
+  Schema.isPattern(/^[^.]+$/, {
     identifier: 'PostgresIdentifierAtom',
     description: 'a non-empty identifier atom containing no "."',
   }),
@@ -63,29 +63,28 @@ const IdentifierAtom = Schema.String.pipe(
  *   fetches before looping.
  */
 export const PostgresStoreConfig = Schema.Struct({
-  // `exact: true` keeps the decoded type at `key?: T` (never `T | undefined`),
+  // `optionalKey` keeps the decoded type at `key?: T` (never `T | undefined`),
   // matching the repo's `exactOptionalPropertyTypes` discipline — an absent key,
   // not an explicit `undefined`.
-  schema: Schema.optionalWith(IdentifierAtom, { exact: true }),
-  tablePrefix: Schema.optionalWith(IdentifierAtom, { exact: true }),
-  lockTimeout: Schema.optionalWith(
-    Schema.Number.pipe(Schema.nonNegative(), Schema.finite()),
-    { exact: true },
+  schema: Schema.optionalKey(IdentifierAtom),
+  tablePrefix: Schema.optionalKey(IdentifierAtom),
+  lockTimeout: Schema.optionalKey(
+    Schema.Number.check(Schema.isGreaterThanOrEqualTo(0), Schema.isFinite()),
   ),
   // The two subscribe knobs are core's field definitions, not this engine's: see
   // `subscriptionTuningFields`.
   ...subscriptionTuningFields,
-}).pipe(
+}).check(
   // Cross-field guard: the derived table/index/function/channel names must all
   // fit Postgres's 63-byte identifier limit. Returning the message string fails
-  // the decode with it; `undefined`/`true` passes.
-  Schema.filter((config) => oversizedIdentifier(config) ?? true),
+  // the decode with it; `undefined` passes.
+  Schema.makeFilter((config) => oversizedIdentifier(config)),
 )
 export type PostgresStoreConfig = typeof PostgresStoreConfig.Type
 
 /**
  * Decode an unknown value into a validated `PostgresStoreConfig`, throwing a
- * `ParseError` on any violation. Used by `layer`/`ensureSchema` so a bad config
+ * `SchemaError` on any violation. Used by `layer`/`ensureSchema` so a bad config
  * fails at construction time.
  */
 export const decodePostgresStoreConfig =

package/src/ensureSchema.ts

@@ -4,7 +4,7 @@
  * 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
+ * `SqlClient` service — NOT `PgClientPooled` — precisely so a consumer can drop it
  * straight into THEIR OWN migrator, e.g.:
  *
  * ```ts
@@ -18,13 +18,18 @@
  * 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
+ * FUNCTION`, so re-running it is safe. It is NOT a no-op across versions: a
+ * re-run replaces the append functions with this version's, and does NOT alter
+ * an existing table, so a column a newer version adds must be added by hand
+ * before the re-run (the release notes give the statement). A store whose
+ * table gained a column but whose functions were never replaced keeps writing
+ * through the old ones, which do not know the column. 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 { SqlClient, type SqlError } from 'effect/sql'
 import { decodePostgresStoreConfig, type PostgresStoreConfig } from './config'
 import { resolveNames, runDdl } from './internal/ddl'
 

package/src/index.ts

@@ -30,9 +30,10 @@
  * 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.
+ * 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,

package/src/internal/ddl.ts

@@ -25,11 +25,14 @@
  * would emit; VALUES stay bound parameters (`sql.unsafe` with `params`) and are
  * never interpolated.
  */
-import type { SqlClient, Statement } from '@effect/sql'
+import type { SqlClient, Statement } from 'effect/sql'
 import {
   allowedTypesPredicate,
+  eventColumnList,
+  eventInsertSelectList,
   eventRecordsetColumns,
   qualifiedRows,
+  RECORDSET_ALIAS,
   taggedMatchChain,
 } from './matchSql'
 
@@ -250,6 +253,16 @@ export interface AppendBodyOptions {
  * preserves batch order, and `RETURNING id, tags` is captured into a temp
  * result set so the tag fan-out and the head can both read it. `data` arrives as
  * a base64 text field and is `decode(…, 'base64')`-restored to `bytea`.
+ *
+ * The recordset definition, its projection, the `INSERT INTO (…)` target list and
+ * the `SELECT` list are all derived from the one `EVENT_COLUMNS` descriptor in
+ * `matchSql.ts`, never written out here. The last two must agree POSITIONALLY and a
+ * mismatch is not an error, so deriving both from one walk is what keeps them from
+ * falling out of step; a column added without a source is a compile error there.
+ * What the compiler does NOT reach is whether the source READS the right field, or
+ * whether the column comes back out on the read; the round-trip contract group run
+ * against this engine is what proves a new column, and only with a value distinct
+ * per column, which is what makes a swap visible.
  */
 const insertFanoutNotify = (
   names: ResolvedNames,
@@ -273,18 +286,18 @@ const insertFanoutNotify = (
     PERFORM pg_notify(${channel}, '1');
   END IF;`
       : ''
-  return `  WITH ne AS (
-    SELECT type, data, tags, uuid, occurred_at, ordinality
+  const ne = RECORDSET_ALIAS
+  return `  WITH ${ne} AS (
+    SELECT ${eventColumnList}, ordinality
     FROM ROWS FROM(
       jsonb_to_recordset(new_events) AS (${eventRecordsetColumns})
     ) WITH ORDINALITY
   ),
   inserted AS (
-    INSERT INTO ${main} (type, data, tags, uuid, occurred_at)
-    SELECT ne.type, decode(ne.data, 'base64'), ne.tags, ne.uuid,
-           ne.occurred_at
-    FROM ne
-    ORDER BY ne.ordinality
+    INSERT INTO ${main} (${eventColumnList})
+    SELECT ${eventInsertSelectList}
+    FROM ${ne}
+    ORDER BY ${ne}.ordinality
     RETURNING id, tags
   ),
   fanned AS (
@@ -337,9 +350,12 @@ const conditionalAppendBody = (
   // its ITEMS — none at all, an item carrying no tags, an item carrying tags —
   // which between them cover every `Query` value the grammar can express, so a new
   // SHAPE changes which SQL the read compiles without changing what this body has
-  // to match. The exposure is the GRAMMAR itself: a new `QueryItem` field, or a new
-  // meaning for an existing one, is something this body ignores rather than fails
-  // on, and no `switch` over the shape union would have caught that either.
+  // to match. The exposure is the GRAMMAR itself: a field ADDED to `QueryItem`, or a
+  // new meaning for an existing one, is something this body ignores rather than
+  // fails on, and no `switch` over the shape union would have caught that either. A
+  // key the grammar does NOT define never reaches this body: core's
+  // `servableQueryFault` refuses it at the contract boundary, which is what keeps a
+  // smuggled predicate from being dropped here in silence.
   const after = 'COALESCE(after_id, 0)'
   return `
 DECLARE
@@ -537,14 +553,18 @@ export const ddlStatements = (names: ResolvedNames): ReadonlyArray<string> => {
     // positions — a rolled-back insert permanently consumes its id, which is
     // fine: ordering is by id alone and the store is never made gapless.
     // `data` is NULLABLE (a payload-less event is valid); `occurred_at` is
-    // informational domain time, never an ordering key.
+    // informational domain time, never an ordering key. `metadata` is the
+    // event's cleartext context bag (ADR-0017): `jsonb` only so a containment
+    // index stays possible without a rewrite, though nothing queries it and no
+    // index is built; `NOT NULL DEFAULT '{}'` gives an empty bag one shape.
     `CREATE TABLE IF NOT EXISTS ${main} (
        id bigserial,
        type text NOT NULL,
        data bytea,
        tags text[] NOT NULL,
        uuid text NOT NULL,
-       occurred_at timestamptz NOT NULL
+       occurred_at timestamptz NOT NULL,
+       metadata jsonb NOT NULL DEFAULT '{}'::jsonb
      ) WITH (${AUTOVACUUM_WITH});`,
 
     // Covering unique index: uniqueness on id plus INCLUDE(type) so the read

package/src/internal/matchSql.ts

@@ -39,6 +39,7 @@ const EVENT_COLUMNS = [
   ['tags', 'text[]'],
   ['uuid', 'text'],
   ['occurred_at', 'timestamptz'],
+  ['metadata', 'jsonb'],
 ] as const satisfies ReadonlyArray<
   readonly [name: string, recordsetType: string]
 >
@@ -55,7 +56,8 @@ 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
+ * `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`.
  */
@@ -73,6 +75,66 @@ export const readColumns = (prefix = ''): 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 const RECORDSET_ALIAS = 'ne'
+
+/**
+ * What the append body inserts into each event column, read from the recordset row.
+ *
+ * Typed as a `Record` over `EventColumnName` so that adding a column to
+ * `EVENT_COLUMNS` without saying where its value comes from is a COMPILE error,
+ * rather than a column the insert silently leaves at its default. Every column but
+ * `data` and `metadata` passes through as the recordset already types it — `text[]`
+ * tags, `timestamptz` — because `jsonb_to_recordset` did the casting; `data`
+ * crosses as base64 TEXT and is restored to `bytea` here, its one decode.
+ *
+ * `metadata` is wrapped in `COALESCE(…, '{}'::jsonb)`, for a caller this package's
+ * own client never is. `ensureSchema` replaces each append function with
+ * `CREATE OR REPLACE`, which keeps its argument signature, so a client from before
+ * the column existed (`1.0.0-alpha.3` and earlier) goes on calling the current body
+ * with events JSON that has no `metadata` key. `jsonb_to_recordset` reads an absent
+ * key as `NULL`, and an insert that names the column inserts that `NULL` rather than
+ * the column's `DEFAULT`, so `NOT NULL` would refuse every such append. The
+ * `COALESCE` gives that row the empty bag the `DEFAULT` would have, which is what
+ * makes "migrate, then deploy" a safe order from those versions. An event sent WITH
+ * a bag passes through unchanged, so what is stored for it does not move.
+ */
+const EVENT_COLUMN_SOURCE: Record<EventColumnName, string> = {
+  type: `${RECORDSET_ALIAS}.type`,
+  data: `decode(${RECORDSET_ALIAS}.data, 'base64')`,
+  tags: `${RECORDSET_ALIAS}.tags`,
+  uuid: `${RECORDSET_ALIAS}.uuid`,
+  occurred_at: `${RECORDSET_ALIAS}.occurred_at`,
+  metadata: `COALESCE(${RECORDSET_ALIAS}.metadata, '{}'::jsonb)`,
+}
+
+/**
+ * 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 const eventColumnList: string = EVENT_COLUMNS.map(([name]) => name).join(
+  ', ',
+)
+
+/**
+ * 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 const eventInsertSelectList: string = EVENT_COLUMNS.map(
+  ([name]) => EVENT_COLUMN_SOURCE[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.

package/src/internal/readPlan.ts

@@ -21,10 +21,11 @@
  * 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 type { SqlClient, SqlError } from 'effect/sql'
 import { taggedReadSql, typeOnlyReadSql, wildcardReadSql } from './matchSql'
 import { type EventRow, jsonbText, toQueryItemsJson } from './transport'
 
@@ -82,11 +83,15 @@ export const compileFetchPlan = (
         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
+      // `@effect/sql-pg` binds a JS array of strings as a `text[]` param, so
+      // `type = ANY($2)` matches any of the item's types. A branded `EventType` IS
+      // its string to the driver, so nothing has to be unwrapped — but the list is
+      // COPIED here, at compile time. The driver serialises the array afresh on
+      // every `bind`, and a subscription re-binds on every poll, so binding the
+      // caller's own array would let an edit the caller makes after subscribing
+      // reach the next fetch. The tagged arm is immune by construction, since it
+      // serialises once below; this copy is what makes the two arms agree.
+      const types = [...shape.types]
       return {
         text: typeOnlyReadSql(tables.main),
         bind: (after, limit) => [after, types, limit],

package/src/internal/transport.ts

@@ -8,7 +8,7 @@
  * 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`
+ * 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
@@ -19,22 +19,30 @@
  * (`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 {
+  DcbEvent,
+  Metadata,
+  Position,
+  Query,
+  SequencedEvent,
+} from '@kairos-es/core'
+import { DateTime } from 'effect'
+import { Base64 } from 'effect/encoding'
 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.
+ * 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 const jsonbText = (value: unknown): string => JSON.stringify(value)
 
@@ -54,9 +62,11 @@ export 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`); 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.
+ * (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
@@ -64,6 +74,7 @@ interface EventJsonColumns {
   readonly tags: ReadonlyArray<string>
   readonly uuid: string
   readonly occurred_at: string
+  readonly metadata: Metadata
 }
 
 /**
@@ -80,18 +91,25 @@ 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),
+  // `Base64.encode` (from `effect/encoding`) keeps this dependency-free and pure
+  // — no `Buffer`, so no `@types/node` and no browser/runtime coupling. It emits
+  // the standard RFC 4648 alphabet with `=` padding, which is what plpgsql's
+  // `decode(…, 'base64')` reads.
+  data: Base64.encode(event.data),
   tags: [...event.tags],
   uuid: event.uuid,
   occurred_at: DateTime.formatIso(event.occurredAt),
+  metadata: event.metadata,
 })
 
 /**
  * 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`
+ * 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.
  */
@@ -101,23 +119,51 @@ interface EventRowColumns {
   readonly tags: ReadonlyArray<string>
   readonly uuid: string
   readonly occurred_at: Date
+  readonly metadata: unknown
 }
 
 /**
- * A raw row from the main table as node-postgres returns it, as `id` plus a
+ * 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 hands back as a decimal STRING (JS `number` is unsafe past 2^53).
+ * 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: string } & {
+export type EventRow = { readonly id: bigint | string } & {
   readonly [K in EventColumnName]: EventRowColumns[K]
 }
 
+/**
+ * The `metadata` column as the event's bag, checked to be a JSON OBJECT.
+ *
+ * The store only ever writes an object, but `jsonb` admits any JSON value — an
+ * array, a string, a number, a boolean, JSON `null` (which `NOT NULL` does not
+ * exclude) — so a hand-written row can hold one. Such a row is corrupt, and
+ * handing an event whose `metadata` is not a bag to every projection
+ * downstream is worse than stopping at the read. This is the CONTAINER check
+ * only; the shape rule itself has one home, core's `Metadata` doc. The VALUES
+ * are deliberately not re-checked as strings, because a value check on read
+ * alone would make an event the store accepted unreadable for ever.
+ */
+const metadataFrom = (value: unknown): Metadata => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(
+      `@kairos-es/store-postgres: the \`metadata\` column did not hold a JSON object (got ${JSON.stringify(value)}).`,
+    )
+  }
+  return value as Metadata
+}
+
 /**
  * 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`.
+ * 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
@@ -135,7 +181,8 @@ export const rowToSequenced = (row: EventRow): SequencedEvent => ({
     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),
+    occurredAt: DateTime.fromDateUnsafe(row.occurred_at),
+    metadata: metadataFrom(row.metadata),
   },
   position: BigInt(row.id) as Position,
 })