@kairos-es/core 1.0.0-alpha.3 → 1.0.0-alpha.4

package/src/inMemory.ts

@@ -25,7 +25,7 @@
  * discharges the ascending-commit-order precondition `SubscribeMachine.ts` states.
  */
 import type { Array as Arr, Scope } from 'effect'
-import { Effect, Layer, PubSub, Ref, Stream } from 'effect'
+import { DateTime, Effect, Layer, PubSub, Ref, Stream } from 'effect'
 import type { AppendCondition } from './AppendCondition'
 import { makeContractStore, type RawDcbEventStore } from './ContractStore'
 import type { ReadOptions, ReadResponse } from './DcbEventStore'
@@ -41,6 +41,68 @@ import {
   subscribeStream,
 } from './SubscribeMachine'
 
+/**
+ * A copy of `event` that shares no mutable structure with it: fresh `data` bytes, a
+ * fresh `tags` array, a fresh `metadata` bag and a fresh `occurredAt`. Only `type`
+ * and `uuid`, which are strings, are carried as they are.
+ *
+ * Each copy is chosen for what it does on EVERY input the type admits, not on the
+ * common one. `data` is copied through the `Uint8Array` constructor and not with
+ * `slice`, because `DcbEvent` admits any `Uint8Array` subclass and a subclass may
+ * answer `slice` with a VIEW of the same memory — Node's `Buffer` does. A
+ * `DateTime.Utc` is an ordinary object whose fields can be written past its
+ * `readonly` type, so `occurredAt` is rebuilt from its instant rather than shared.
+ *
+ * ## Why the oracle copies at BOTH edges
+ *
+ * This store is the reference the SQL engines are judged against, and a SQL engine
+ * shares nothing with its caller: it serialises on the way in and builds fresh objects
+ * on the way out. A store that kept the caller's objects instead would let a caller
+ * rewrite the log AFTER the append — mutate a `Uint8Array`, push to a `tags` array,
+ * assign into a `metadata` bag — and every later read would see the rewritten event
+ * with no append, no position and no wake behind it. A reference that can be edited
+ * after the fact judges nothing.
+ *
+ * So `append` stores a copy (the log never holds a caller's object) and every read
+ * path hands out a copy (a reader cannot reach the log through what it was given).
+ * Copying on the way in alone would close the first route and leave the second open:
+ * the same object would then be shared by every reader of the log.
+ */
+const copyEvent = (event: DcbEvent): DcbEvent => ({
+  type: event.type,
+  data: new Uint8Array(event.data),
+  tags: [...event.tags],
+  uuid: event.uuid,
+  occurredAt: DateTime.unsafeMake(DateTime.toEpochMillis(event.occurredAt)),
+  metadata: { ...event.metadata },
+})
+
+/**
+ * A copy of `query` that shares no array with it, taking only the keys the grammar
+ * defines.
+ *
+ * `subscribe` is the one verb that holds a query beyond its own call: the fetch seam
+ * judges it again on every page for as long as the subscription runs. Each SQL engine
+ * compiles its plan once, when the subscription starts, so an edit the caller makes
+ * to its own object afterwards reaches nothing there. The oracle has to answer the
+ * same, for the reason it copies events (above): a reference that the caller can
+ * change mid-stream judges nothing. Only `types` and `tags` are carried because they
+ * are all `matchesQueryItem` reads, and a key the grammar does not define was
+ * already refused at the contract decorator before this runs.
+ */
+const copyQuery = (query: Query): Query => ({
+  items: query.items.map((item) => ({
+    types: [...item.types],
+    tags: [...item.tags],
+  })),
+})
+
+/** A `SequencedEvent` whose event is a `copyEvent` of the stored one. */
+const copySequenced = (sequenced: SequencedEvent): SequencedEvent => ({
+  event: copyEvent(sequenced.event),
+  position: sequenced.position,
+})
+
 /** Filter a snapshot by `query` and `after` (strict `position > after`). */
 const filterLog = (
   log: ReadonlyArray<SequencedEvent>,
@@ -80,7 +142,7 @@ const readSnapshot = (
       ? lastPosition(log)
       : lastPosition(limited)) ?? ORIGIN
 
-  return { events: Stream.fromIterable(limited), head }
+  return { events: Stream.fromIterable(limited.map(copySequenced)), head }
 }
 
 /**
@@ -144,7 +206,7 @@ const fetchPage = (
   ) {
     const sequenced = log[index]
     if (matchesSequenced(sequenced, query)) {
-      page.push(sequenced)
+      page.push(copySequenced(sequenced))
     }
   }
   return page
@@ -247,53 +309,60 @@ const make = (
       events: Arr.NonEmptyReadonlyArray<DcbEvent>,
       condition?: AppendCondition,
     ): Effect.Effect<Position, AppendConditionFailed> =>
-      // Critical section: check + commit are atomic (the exactly-one-wins guarantee).
-      mutex.withPermits(1)(
-        Effect.gen(function* () {
-          const snapshot = yield* Ref.get(log)
+      Effect.suspend(() => {
+        // The events are copied when the append STARTS, before it waits for the
+        // permit, as each SQL engine serialises them before its first suspension:
+        // an edit the caller makes while this append is queued must not reach the
+        // log here when it could not reach theirs.
+        const owned = events.map(copyEvent)
+        // Critical section: check + commit are atomic (the exactly-one-wins guarantee).
+        return mutex.withPermits(1)(
+          Effect.gen(function* () {
+            const snapshot = yield* Ref.get(log)
 
-          if (condition !== undefined) {
-            const conflicts = filterLog(
-              snapshot,
-              condition.failIfEventsMatch,
-              condition.after,
-            )
-            // Detect by presence: any matching event after `condition.after`
-            // fails the append. The error carries only the condition (see
-            // `AppendConditionFailed`); a correct retry re-reads to the new head.
-            if (conflicts.length > 0) {
-              return yield* new AppendConditionFailed({ condition })
+            if (condition !== undefined) {
+              const conflicts = filterLog(
+                snapshot,
+                condition.failIfEventsMatch,
+                condition.after,
+              )
+              // Detect by presence: any matching event after `condition.after`
+              // fails the append. The error carries only the condition (see
+              // `AppendConditionFailed`); a correct retry re-reads to the new head.
+              if (conflicts.length > 0) {
+                return yield* new AppendConditionFailed({ condition })
+              }
             }
-          }
 
-          // Optional test seam between the conflict-check and the commit (see
-          // `InMemoryStoreOptions.beforeCommit`). Defaults to `Effect.void`, a
-          // synchronous no-op, so the shipped critical section stays atomic by
-          // construction; the concurrency contract test injects `Effect.yieldNow()`
-          // here to make the exactly-one-wins guard genuinely depend on the mutex.
-          yield* beforeCommit
+            // Optional test seam between the conflict-check and the commit (see
+            // `InMemoryStoreOptions.beforeCommit`). Defaults to `Effect.void`, a
+            // synchronous no-op, so the shipped critical section stays atomic by
+            // construction; the concurrency contract test injects `Effect.yieldNow()`
+            // here to make the exactly-one-wins guard genuinely depend on the mutex.
+            yield* beforeCommit
 
-          const start = yield* Ref.get(nextPosition)
-          const appended: Array<SequencedEvent> = events.map(
-            (event, index) => ({
-              event,
-              position: (start + BigInt(index)) as Position,
-            }),
-          )
-          const end = start + BigInt(events.length)
-          yield* Ref.set(log, [...snapshot, ...appended])
-          yield* Ref.set(nextPosition, end)
-          // The hub is a WAKE SOURCE and nothing else: the subscribe machine never
-          // reads what it carries, and its poll delivers with or without one. That
-          // is why suppressing the publish is a legitimate test seam rather than a
-          // broken store (see `InMemoryStoreOptions.suppressWake`).
-          if (!suppressWake) {
-            yield* PubSub.publishAll(hub, appended)
-          }
-          // `events` is non-empty, so the last new position is `end - 1`.
-          return (end - 1n) as Position
-        }),
-      )
+            const start = yield* Ref.get(nextPosition)
+            const appended: Array<SequencedEvent> = owned.map(
+              (event, index) => ({
+                event,
+                position: (start + BigInt(index)) as Position,
+              }),
+            )
+            const end = start + BigInt(events.length)
+            yield* Ref.set(log, [...snapshot, ...appended])
+            yield* Ref.set(nextPosition, end)
+            // The hub is a WAKE SOURCE and nothing else: the subscribe machine never
+            // reads what it carries, and its poll delivers with or without one. That
+            // is why suppressing the publish is a legitimate test seam rather than a
+            // broken store (see `InMemoryStoreOptions.suppressWake`).
+            if (!suppressWake) {
+              yield* PubSub.publishAll(hub, appended)
+            }
+            // `events` is non-empty, so the last new position is `end - 1`.
+            return (end - 1n) as Position
+          }),
+        )
+      })
 
     const subscribe = (
       query: Query,
@@ -314,12 +383,15 @@ const make = (
       // permit, which is the whole exactly-one-wins guarantee.
       Stream.unwrapScoped(
         Effect.gen(function* () {
+          // Taken when the subscription starts, as the SQL engines compile theirs
+          // (see `copyQuery`).
+          const judged = copyQuery(query)
           const wakes = yield* PubSub.subscribe(hub)
           return subscribeStream<never>(
             {
               fetch: (from, limit) =>
                 Effect.map(Ref.get(log), (snapshot) =>
-                  fetchPage(snapshot, query, from, limit),
+                  fetchPage(snapshot, judged, from, limit),
                 ),
               listen: Stream.fromQueue(wakes),
               pollInterval,