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

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,7 +19,13 @@
  * (`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 type {
+  DcbEvent,
+  Metadata,
+  Position,
+  Query,
+  SequencedEvent,
+} from '@kairos-es/core'
 import { DateTime, Encoding } from 'effect'
 import type { EventColumnName } from './matchSql'
 
@@ -54,9 +60,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 +72,7 @@ interface EventJsonColumns {
   readonly tags: ReadonlyArray<string>
   readonly uuid: string
   readonly occurred_at: string
+  readonly metadata: Metadata
 }
 
 /**
@@ -86,12 +95,16 @@ export const toEventJson = (event: DcbEvent): EventJson => ({
   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`
+ * for a payload-less event), `occurred_at` a JS `Date`, `tags` a `string[]`,
+ * `metadata` whatever node-postgres 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,6 +114,7 @@ interface EventRowColumns {
   readonly tags: ReadonlyArray<string>
   readonly uuid: string
   readonly occurred_at: Date
+  readonly metadata: unknown
 }
 
 /**
@@ -114,10 +128,34 @@ export type EventRow = { readonly id: 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` string → 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
@@ -136,6 +174,7 @@ export const rowToSequenced = (row: EventRow): SequencedEvent => ({
     tags: row.tags as unknown as DcbEvent['tags'],
     uuid: row.uuid as DcbEvent['uuid'],
     occurredAt: DateTime.unsafeFromDate(row.occurred_at),
+    metadata: metadataFrom(row.metadata),
   },
   position: BigInt(row.id) as Position,
 })

package/src/store.ts

@@ -30,10 +30,8 @@
  * the guarded statement to meet its own row and read zero. Surfacing rather than
  * RESOLVING is what makes that free: an engine willing to re-issue an undecided
  * append needs a way to tell its own committed row from a rival's BEFORE it does,
- * or the re-issue is the very thing that manufactures the phantom — see
- * `@kairos-es/store-sqlite`, which resolves one by identity and re-issues only
- * when identity answers absent. So the missing verify path here is a consequence
- * of that choice rather than an omission from it.
+ * or the re-issue is the very thing that manufactures the phantom. So the missing
+ * verify path here is a consequence of that choice rather than an omission from it.
  *
  * This module is WIRING + APPEND: the JSON/JSONB transport (the event/query-item
  * (de)serialisers and row mapping) lives in `internal/transport.ts` and the