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

package/dist/esm/inMemory.js

@@ -1,10 +1,71 @@
-import { Effect, Layer, PubSub, Ref, Stream } from 'effect';
+import { DateTime, Effect, Layer, PubSub, Ref, Stream } from 'effect';
 import { makeContractStore } from "./ContractStore.js";
 import { DcbEventStore } from "./DcbEventStore.js";
 import { ORIGIN } from "./Event.js";
 import { AppendConditionFailed } from "./errors.js";
 import { matchesSequenced } from "./Query.js";
 import { DEFAULT_CATCH_UP_PAGE_SIZE, DEFAULT_POLL_INTERVAL_MILLIS, subscribeStream } from "./SubscribeMachine.js";
+/**
+ * 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 => ({
+  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 => ({
+  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 => ({
+  event: copyEvent(sequenced.event),
+  position: sequenced.position
+});
 /** Filter a snapshot by `query` and `after` (strict `position > after`). */
 const filterLog = (log, query, after) => log.filter(sequenced => (after === undefined || sequenced.position > after) && matchesSequenced(sequenced, query));
 /** The position of the last event in a slice, or `undefined` when empty. */
@@ -22,7 +83,7 @@ const readSnapshot = (log, query, options) => {
   // when there is nothing to report.
   const head = (options?.limit === undefined ? lastPosition(log) : lastPosition(limited)) ?? ORIGIN;
   return {
-    events: Stream.fromIterable(limited),
+    events: Stream.fromIterable(limited.map(copySequenced)),
     head
   };
 };
@@ -74,7 +135,7 @@ const fetchPage = (log, query, from, limit) => {
   for (let index = firstIndexAfter(log, from); index < log.length && page.length < limit; index += 1) {
     const sequenced = log[index];
     if (matchesSequenced(sequenced, query)) {
-      page.push(sequenced);
+      page.push(copySequenced(sequenced));
     }
   }
   return page;
@@ -99,45 +160,51 @@ const make = options => Effect.gen(function* () {
   // is reentrant, so append's inner read re-enters. Here append inlines the
   // read logic instead, so a plain lock suffices.
   mutex.withPermits(1)(Effect.map(Ref.get(log), snapshot => readSnapshot(snapshot, query, options)));
-  const append = (events, condition) =>
-  // Critical section: check + commit are atomic (the exactly-one-wins guarantee).
-  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
-        });
+  const append = (events, condition) => 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
+          });
+        }
       }
-    }
-    // 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 = events.map((event, index) => ({
-      event,
-      position: start + BigInt(index)
+      // 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 = owned.map((event, index) => ({
+        event,
+        position: start + BigInt(index)
+      }));
+      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;
     }));
-    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;
-  }));
+  });
   const subscribe = (query, after) =>
   // Take the hub seat HERE, before handing the machine its wake source, so the
   // subscription is established no later than the machine's first `fetch`. That
@@ -153,9 +220,12 @@ const make = options => Effect.gen(function* () {
   // is nothing left here for a critical section to protect. `append` keeps its
   // 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({
-      fetch: (from, limit) => Effect.map(Ref.get(log), snapshot => fetchPage(snapshot, query, from, limit)),
+      fetch: (from, limit) => Effect.map(Ref.get(log), snapshot => fetchPage(snapshot, judged, from, limit)),
       listen: Stream.fromQueue(wakes),
       pollInterval,
       catchUpPageSize

package/dist/esm/inMemory.js.map

@@ -1 +1 @@
-{"version":3,"file":"inMemory.js","names":["Effect","Layer","PubSub","Ref","Stream","makeContractStore","DcbEventStore","ORIGIN","AppendConditionFailed","matchesSequenced","DEFAULT_CATCH_UP_PAGE_SIZE","DEFAULT_POLL_INTERVAL_MILLIS","subscribeStream","filterLog","log","query","after","filter","sequenced","undefined","position","lastPosition","events","at","readSnapshot","options","matched","limited","limit","slice","head","fromIterable","firstIndexAfter","low","high","length","mid","fetchPage","from","page","index","push","make","gen","beforeCommit","void","suppressWake","catchUpPageSize","pollInterval","mutex","makeSemaphore","hub","unbounded","nextPosition","read","withPermits","map","get","snapshot","append","condition","conflicts","failIfEventsMatch","start","appended","event","BigInt","end","set","publishAll","subscribe","unwrapScoped","wakes","fetch","listen","fromQueue","DcbEventStoreInMemory","effect","makeInMemoryTestLayer"],"sources":["../../src/inMemory.ts"],"sourcesContent":[null],"mappings":"AA2BA,SAASA,MAAM,EAAEC,KAAK,EAAEC,MAAM,EAAEC,GAAG,EAAEC,MAAM,QAAQ,QAAQ;AAE3D,SAASC,iBAAiB,QAA+B,oBAAiB;AAE1E,SAASC,aAAa,QAAQ,oBAAiB;AAE/C,SAASC,MAAM,QAAQ,YAAS;AAChC,SAASC,qBAAqB,QAAQ,aAAU;AAEhD,SAASC,gBAAgB,QAAQ,YAAS;AAC1C,SACEC,0BAA0B,EAC1BC,4BAA4B,EAC5BC,eAAe,QACV,uBAAoB;AAE3B;AACA,MAAMC,SAAS,GAAGA,CAChBC,GAAkC,EAClCC,KAAY,EACZC,KAA2B,KAE3BF,GAAG,CAACG,MAAM,CACPC,SAAS,IACR,CAACF,KAAK,KAAKG,SAAS,IAAID,SAAS,CAACE,QAAQ,GAAGJ,KAAK,KAClDP,gBAAgB,CAACS,SAAS,EAAEH,KAAK,CAAC,CACrC;AAEH;AACA,MAAMM,YAAY,GAChBC,MAAqC,IACZA,MAAM,CAACC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAEH,QAAQ;AAElD;;;;;AAKA,MAAMI,YAAY,GAAGA,CACnBV,GAAkC,EAClCC,KAAY,EACZU,OAAgC,KAChB;EAChB,MAAMC,OAAO,GAAGb,SAAS,CAACC,GAAG,EAAEC,KAAK,EAAEU,OAAO,EAAET,KAAK,CAAC;EACrD,MAAMW,OAAO,GACXF,OAAO,EAAEG,KAAK,KAAKT,SAAS,GAAGO,OAAO,GAAGA,OAAO,CAACG,KAAK,CAAC,CAAC,EAAEJ,OAAO,CAACG,KAAK,CAAC;EAE1E;EACA;EACA;EACA,MAAME,IAAI,GACR,CAACL,OAAO,EAAEG,KAAK,KAAKT,SAAS,GACzBE,YAAY,CAACP,GAAG,CAAC,GACjBO,YAAY,CAACM,OAAO,CAAC,KAAKpB,MAAM;EAEtC,OAAO;IAAEe,MAAM,EAAElB,MAAM,CAAC2B,YAAY,CAACJ,OAAO,CAAC;IAAEG;EAAI,CAAE;AACvD,CAAC;AAED;;;;;;;;;AASA,MAAME,eAAe,GAAGA,CACtBlB,GAAkC,EAClCE,KAAe,KACL;EACV,IAAIiB,GAAG,GAAG,CAAC;EACX,IAAIC,IAAI,GAAGpB,GAAG,CAACqB,MAAM;EACrB,OAAOF,GAAG,GAAGC,IAAI,EAAE;IACjB;IACA,MAAME,GAAG,GAAIH,GAAG,GAAGC,IAAI,KAAM,CAAC;IAC9B,IAAIpB,GAAG,CAACsB,GAAG,CAAC,CAAChB,QAAQ,GAAGJ,KAAK,EAAE;MAC7BkB,IAAI,GAAGE,GAAG;IACZ,CAAC,MAAM;MACLH,GAAG,GAAGG,GAAG,GAAG,CAAC;IACf;EACF;EACA,OAAOH,GAAG;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;AAoBA,MAAMI,SAAS,GAAGA,CAChBvB,GAAkC,EAClCC,KAAY,EACZuB,IAAc,EACdV,KAAgB,KACiB;EACjC,MAAMW,IAAI,GAA0B,EAAE;EACtC,KACE,IAAIC,KAAK,GAAGR,eAAe,CAAClB,GAAG,EAAEwB,IAAI,CAAC,EACtCE,KAAK,GAAG1B,GAAG,CAACqB,MAAM,IAAII,IAAI,CAACJ,MAAM,GAAGP,KAAK,EACzCY,KAAK,IAAI,CAAC,EACV;IACA,MAAMtB,SAAS,GAAGJ,GAAG,CAAC0B,KAAK,CAAC;IAC5B,IAAI/B,gBAAgB,CAACS,SAAS,EAAEH,KAAK,CAAC,EAAE;MACtCwB,IAAI,CAACE,IAAI,CAACvB,SAAS,CAAC;IACtB;EACF;EACA,OAAOqB,IAAI;AACb,CAAC;AA8DD;;;;;;AAMA,MAAMG,IAAI,GACRjB,OAA8B,IAE9BzB,MAAM,CAAC2C,GAAG,CAAC,aAAS;EAClB,MAAMC,YAAY,GAAGnB,OAAO,EAAEmB,YAAY,IAAI5C,MAAM,CAAC6C,IAAI;EACzD,MAAMC,YAAY,GAAGrB,OAAO,EAAEqB,YAAY,IAAI,KAAK;EACnD,MAAMC,eAAe,GACnBtB,OAAO,EAAEsB,eAAe,IAAIrC,0BAA0B;EACxD,MAAMsC,YAAY,GAAGvB,OAAO,EAAEuB,YAAY,IAAIrC,4BAA4B;EAC1E,MAAMG,GAAG,GAAG,OAAOX,GAAG,CAACuC,IAAI,CAAgC,EAAE,CAAC;EAC9D,MAAMO,KAAK,GAAG,OAAOjD,MAAM,CAACkD,aAAa,CAAC,CAAC,CAAC;EAC5C,MAAMC,GAAG,GAAG,OAAOjD,MAAM,CAACkD,SAAS,EAAkB;EACrD,MAAMC,YAAY,GAAG,OAAOlD,GAAG,CAACuC,IAAI,CAAS,EAAE,CAAC;EAEhD,MAAMY,IAAI,GAAGA,CACXvC,KAAY,EACZU,OAAqB;EAErB;EACA;EACA;EACAwB,KAAK,CAACM,WAAW,CAAC,CAAC,CAAC,CAClBvD,MAAM,CAACwD,GAAG,CAACrD,GAAG,CAACsD,GAAG,CAAC3C,GAAG,CAAC,EAAG4C,QAAQ,IAChClC,YAAY,CAACkC,QAAQ,EAAE3C,KAAK,EAAEU,OAAO,CAAC,CACvC,CACF;EAEH,MAAMkC,MAAM,GAAGA,CACbrC,MAA2C,EAC3CsC,SAA2B;EAE3B;EACAX,KAAK,CAACM,WAAW,CAAC,CAAC,CAAC,CAClBvD,MAAM,CAAC2C,GAAG,CAAC,aAAS;IAClB,MAAMe,QAAQ,GAAG,OAAOvD,GAAG,CAACsD,GAAG,CAAC3C,GAAG,CAAC;IAEpC,IAAI8C,SAAS,KAAKzC,SAAS,EAAE;MAC3B,MAAM0C,SAAS,GAAGhD,SAAS,CACzB6C,QAAQ,EACRE,SAAS,CAACE,iBAAiB,EAC3BF,SAAS,CAAC5C,KAAK,CAChB;MACD;MACA;MACA;MACA,IAAI6C,SAAS,CAAC1B,MAAM,GAAG,CAAC,EAAE;QACxB,OAAO,OAAO,IAAI3B,qBAAqB,CAAC;UAAEoD;QAAS,CAAE,CAAC;MACxD;IACF;IAEA;IACA;IACA;IACA;IACA;IACA,OAAOhB,YAAY;IAEnB,MAAMmB,KAAK,GAAG,OAAO5D,GAAG,CAACsD,GAAG,CAACJ,YAAY,CAAC;IAC1C,MAAMW,QAAQ,GAA0B1C,MAAM,CAACkC,GAAG,CAChD,CAACS,KAAK,EAAEzB,KAAK,MAAM;MACjByB,KAAK;MACL7C,QAAQ,EAAG2C,KAAK,GAAGG,MAAM,CAAC1B,KAAK;KAChC,CAAC,CACH;IACD,MAAM2B,GAAG,GAAGJ,KAAK,GAAGG,MAAM,CAAC5C,MAAM,CAACa,MAAM,CAAC;IACzC,OAAOhC,GAAG,CAACiE,GAAG,CAACtD,GAAG,EAAE,CAAC,GAAG4C,QAAQ,EAAE,GAAGM,QAAQ,CAAC,CAAC;IAC/C,OAAO7D,GAAG,CAACiE,GAAG,CAACf,YAAY,EAAEc,GAAG,CAAC;IACjC;IACA;IACA;IACA;IACA,IAAI,CAACrB,YAAY,EAAE;MACjB,OAAO5C,MAAM,CAACmE,UAAU,CAAClB,GAAG,EAAEa,QAAQ,CAAC;IACzC;IACA;IACA,OAAQG,GAAG,GAAG,EAAE;EAClB,CAAC,CAAC,CACH;EAEH,MAAMG,SAAS,GAAGA,CAChBvD,KAAY,EACZC,KAAgB;EAEhB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACAZ,MAAM,CAACmE,YAAY,CACjBvE,MAAM,CAAC2C,GAAG,CAAC,aAAS;IAClB,MAAM6B,KAAK,GAAG,OAAOtE,MAAM,CAACoE,SAAS,CAACnB,GAAG,CAAC;IAC1C,OAAOvC,eAAe,CACpB;MACE6D,KAAK,EAAEA,CAACnC,IAAI,EAAEV,KAAK,KACjB5B,MAAM,CAACwD,GAAG,CAACrD,GAAG,CAACsD,GAAG,CAAC3C,GAAG,CAAC,EAAG4C,QAAQ,IAChCrB,SAAS,CAACqB,QAAQ,EAAE3C,KAAK,EAAEuB,IAAI,EAAEV,KAAK,CAAC,CACxC;MACH8C,MAAM,EAAEtE,MAAM,CAACuE,SAAS,CAACH,KAAK,CAAC;MAC/BxB,YAAY;MACZD;KACD,EACD/B,KAAK,CACN;EACH,CAAC,CAAC,CACH;EAEH,OAAO;IAAEsC,IAAI;IAAEK,MAAM;IAAEW;EAAS,CAAW;AAC7C,CAAC,CAAC;AAEJ;AACA,OAAO,MAAMM,qBAAqB,gBAA+B3E,KAAK,CAAC4E,MAAM,CAC3EvE,aAAa,eACbN,MAAM,CAACwD,GAAG,cAACd,IAAI,EAAE,EAAErC,iBAAiB,CAAC,CACtC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMyE,qBAAqB,GAChCrD,OAA6B,IAE7BxB,KAAK,CAAC4E,MAAM,CAACvE,aAAa,EAAEN,MAAM,CAACwD,GAAG,CAACd,IAAI,CAACjB,OAAO,CAAC,EAAEpB,iBAAiB,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"inMemory.js","names":["DateTime","Effect","Layer","PubSub","Ref","Stream","makeContractStore","DcbEventStore","ORIGIN","AppendConditionFailed","matchesSequenced","DEFAULT_CATCH_UP_PAGE_SIZE","DEFAULT_POLL_INTERVAL_MILLIS","subscribeStream","copyEvent","event","type","data","Uint8Array","tags","uuid","occurredAt","unsafeMake","toEpochMillis","metadata","copyQuery","query","items","map","item","types","copySequenced","sequenced","position","filterLog","log","after","filter","undefined","lastPosition","events","at","readSnapshot","options","matched","limited","limit","slice","head","fromIterable","firstIndexAfter","low","high","length","mid","fetchPage","from","page","index","push","make","gen","beforeCommit","void","suppressWake","catchUpPageSize","pollInterval","mutex","makeSemaphore","hub","unbounded","nextPosition","read","withPermits","get","snapshot","append","condition","suspend","owned","conflicts","failIfEventsMatch","start","appended","BigInt","end","set","publishAll","subscribe","unwrapScoped","judged","wakes","fetch","listen","fromQueue","DcbEventStoreInMemory","effect","makeInMemoryTestLayer"],"sources":["../../src/inMemory.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/core",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "DCB-first event-sourcing contract and in-memory store for Effect v3",
   "license": "BSD-3-Clause",
   "repository": {

package/src/ContractStore.ts

@@ -11,7 +11,9 @@
  * needing a bespoke `catchAll`/`instanceof`:
  *
  * - `assertServableQuery` at every verb's entry (read, the append condition's
- *   guard query, subscribe) — a non-servable query is a DEFECT in every engine;
+ *   guard query, subscribe) — a non-servable query, or one carrying a key the
+ *   grammar does not define, is a DEFECT in every engine, and an append condition
+ *   carrying a key `AppendCondition` does not define is refused alongside it;
  * - `ReadLimit` decode on `read`'s `limit` — a negative/non-integer limit is a
  *   DEFECT (so `read` keeps `E = never`), validated through the branded schema
  *   even at an untyped boundary that reaches the store as `unknown`;
@@ -34,7 +36,7 @@
  */
 import type { Array as Arr, Scope } from 'effect'
 import { Effect, Predicate, Schema, Stream } from 'effect'
-import type { AppendCondition } from './AppendCondition'
+import { AppendCondition } from './AppendCondition'
 import { assertAppendNotOwned } from './AppendIsOwned'
 import type { DcbEventStore, ReadOptions, ReadResponse } from './DcbEventStore'
 import type { DcbEvent, Position, SequencedEvent } from './Event'
@@ -87,7 +89,7 @@ export const makeContractStore = <E>(
 
   append: (events, condition) =>
     // The ownership refusal runs FIRST and sits OUTSIDE the suspend, because it is
-    // the only one of append's four checks that is EFFECTFUL: it consults a
+    // the only one of append's checks that is EFFECTFUL: it consults a
     // `Context.Tag` rather than inspecting the arguments. `Effect.flatMap` over an
     // already-lazy effect defers it exactly as the suspend defers the throws below,
     // so nothing runs at the call site either way; what it buys is that the
@@ -113,8 +115,22 @@ export const makeContractStore = <E>(
               'plain-data caller bypassing the type — a defect, not a conflict.',
           )
         }
-        // A non-servable guard query is a defect in every engine.
+        // A non-servable guard query is a defect in every engine, and so is a
+        // condition carrying a key `AppendCondition` does not define: an author
+        // who wrote one believes they added a condition, and every engine would
+        // ignore it. Known keys come off the schema, as `servableQueryFault`
+        // reads its own (`Query.ts` owns the argument).
         if (condition !== undefined) {
+          const unknown = Object.keys(condition).find(
+            (key) => !Object.hasOwn(AppendCondition.fields, key),
+          )
+          if (unknown !== undefined) {
+            throw new Error(
+              `makeContractStore.append: the append condition carries the key ${JSON.stringify(unknown)}, ` +
+                'which `AppendCondition` does not define; an unknown key would be ' +
+                'silently ignored by every engine rather than honoured, so it is refused',
+            )
+          }
           assertServableQuery(condition.failIfEventsMatch)
         }
         // Only `AppendConditionFailed` belongs on the contract error channel;

package/src/Event.ts

@@ -110,13 +110,74 @@ export const EventType = Schema.String.pipe(
 )
 export type EventType = typeof EventType.Type
 
+/**
+ * An event's metadata: a flat bag of strings carrying the circumstances under
+ * which the event was RECORDED, never anything the business asserts (ADR-0017).
+ * Payload is what happened; metadata is the context of the recording — a
+ * `traceparent`, a correlation or causation id, a deployment revision.
+ *
+ * Values are strings, not `unknown`, for cross-engine parity rather than taste:
+ * both SQL engines carry the bag as a JSON document, and `JSON.stringify` drops
+ * `undefined`, throws on `bigint` and turns `NaN` into `null`, none of which the
+ * in-memory oracle does.
+ *
+ * The key schema carries no refinement, deliberately: a refinement on a
+ * `Schema.Record` key acts as a FILTER on decode, silently dropping a key that
+ * fails it rather than failing the decode. Constraining keys, if ever wanted,
+ * has to be a validating step of its own.
+ *
+ * Two engine limits a consumer must know, because the bag is typically filled
+ * from outside the application at a request edge. Postgres refuses a NUL
+ * character (U+0000) and an unpaired surrogate in any string it stores, so an
+ * event whose bag holds one fails to append there while the in-memory and
+ * SQLite engines accept it; sanitise untrusted values before they reach the
+ * bag. And key ORDER is not preserved: Postgres stores an object's keys in an
+ * order of its own, so compare bags as unordered and never rely on the order
+ * `Object.keys` returns.
+ *
+ * Metadata is never part of a `Query` or an `AppendCondition` — a store refuses
+ * either when it carries a key the grammar does not define, so a metadata
+ * predicate cannot be written and silently ignored — never reaches a codec's
+ * `tagsFor`, and no store offers a way to rewrite it once appended. ADR-0017
+ * owns why each of those is mechanical rather than preferential.
+ *
+ * ## The one home of the shape rule
+ *
+ * The bag is a JSON OBJECT whose every value is a STRING, and this schema is
+ * where that rule is stated. At runtime it is checked in ONE place, at write: the
+ * codec's `toEvent` decodes every bag through this schema and refuses one that
+ * fails on its own error channel, so a value smuggled past the type (through an
+ * `any`) stops there. The schema judges a bag's OWN enumerable keys, so an object
+ * that keeps its entries anywhere else — a `Map`, a `Date` — reads as the empty
+ * bag rather than failing. A store checks no values: an event built by hand and handed
+ * to `append` directly carries whatever it carries, and what each engine then does
+ * with a non-string value differs — one may store it and read it back differently
+ * from another, and a `bigint` makes a SQL engine's append fail. Each
+ * SQL engine keeps a container check of its own on read — the column must hold a
+ * JSON object — because that defends against a writer outside the library and is
+ * about the column, not the values. A VALUE check must never be added on read
+ * alone: it would make an event the store accepted unreadable for ever, so a
+ * value check belongs at write or nowhere.
+ */
+export const Metadata = Schema.Record({
+  key: Schema.String,
+  value: Schema.String,
+})
+export type Metadata = typeof Metadata.Type
+
 /**
  * An event as stored: an opaque payload plus its type, tags, a
- * producer-supplied `uuid`, and producer-supplied `occurredAt` domain time.
+ * producer-supplied `uuid`, producer-supplied `occurredAt` domain time, and its
+ * `metadata` bag.
  *
  * `data` is `Uint8Array` (opaque bytes); the store does not interpret it.
  * `uuid` is producer-supplied to keep `core` deterministic (no RNG in core).
  * `occurredAt` is informational only; ordering is by position alone.
+ * `metadata` mirrors `tags` rather than `data`: REQUIRED, with an empty bag
+ * legal. Required because an absent-versus-empty divergence between engines is
+ * invisible to `toEqual`, which ignores `undefined` properties, so an optional
+ * field could drift across the three engines with the round-trip suite green.
+ * Core only carries it; the codec's `toEvent` is where it is resolved.
  */
 export const DcbEvent = Schema.Struct({
   type: EventType,
@@ -124,6 +185,7 @@ export const DcbEvent = Schema.Struct({
   tags: Schema.Array(Tag),
   uuid: Schema.UUID,
   occurredAt: Schema.DateTimeUtc,
+  metadata: Metadata,
 })
 export type DcbEvent = typeof DcbEvent.Type
 

package/src/Projection.ts

@@ -38,7 +38,7 @@ const WILDCARD: Query = { items: [] }
 
 /**
  * An already-decoded event handed to a projection's fold: the sequenced wire
- * envelope (position, type, tags, timings) plus the decoded `payload`.
+ * envelope (position, type, tags, timings, metadata) plus the decoded `payload`.
  *
  * Core does not decode — it only folds events another layer has already decoded
  * — so `payload` is `unknown` at this layer. `@kairos-es/codec`'s builder emits
@@ -110,13 +110,24 @@ export type CompositeState<T extends Record<string, AnyProjection>> = {
   readonly [K in keyof T]: StateOf<T[K]>
 }
 
-/** Merge two queries by OR-ing their items; either wildcard yields a wildcard. */
-const mergeQuery = (left: Query, right: Query): Query => {
-  if (left.items.length === 0 || right.items.length === 0) {
-    return WILDCARD
-  }
-  return { items: [...left.items, ...right.items] }
-}
+/**
+ * Merge two queries by OR-ing their items; either wildcard yields a wildcard.
+ *
+ * Every other key on either envelope is carried into the result. The grammar's
+ * envelope has no key but `items`, so anything else is a key the store boundary
+ * refuses (`servableQueryFault`); a merge that rebuilt the envelope from `items`
+ * alone would drop that key before the boundary saw it, and a slice composed with
+ * another would then have its smuggled predicate ignored in silence — the outcome
+ * the refusal exists to prevent.
+ */
+const mergeQuery = (left: Query, right: Query): Query => ({
+  ...left,
+  ...right,
+  items:
+    left.items.length === 0 || right.items.length === 0
+      ? WILDCARD.items
+      : [...left.items, ...right.items],
+})
 
 /**
  * OR-merge a list of queries into one. The empty list is the wildcard.

package/src/Query.ts

@@ -79,6 +79,9 @@ export const matchesSequenced = (
  * (`Query.ts` module docs) but which plain-data assembly — e.g. decision-model
  * composition, `Projection.ts:31-36` — can still bypass.
  *
+ * A query, or any of its items, carrying a key the grammar does not define is
+ * refused before anything else is judged (`unknownKeyFault` below says why).
+ *
  * The servable grammar is exactly one of:
  * - the wildcard (`items.length === 0`), which matches every event;
  * - a *single* item (`items.length === 1`), any types/tags, including a
@@ -105,6 +108,72 @@ export const assertServableQuery = (query: Query): void => {
   }
 }
 
+/**
+ * The refusal of a key `schemaFields` does not define, or `undefined` when `value`
+ * carries none. `where` names the level for the message.
+ *
+ * ## Why an unknown key is refused rather than ignored
+ *
+ * A `Query` is plain data, so nothing at runtime stops a caller adding a key the
+ * grammar does not have — a `metadata` predicate on an item is the one this repo
+ * expects, since metadata is the field an author most plausibly wants to filter on
+ * and must not (ADR-0017). Ignored, that key is a predicate the author believes they
+ * wrote and no engine honours, and on the append side it is worse: the Postgres
+ * guard embeds its match as literal plpgsql text that no type reaches, so a key a
+ * read path one day learned to honour would still be dropped by the guard, and the
+ * optimistic-concurrency check would escape in silence. Refusing every key the
+ * grammar does not define closes that route — a SMUGGLED key — at the one boundary
+ * every engine shares, before any engine could disagree. "Every key" means every
+ * key `Object.keys` returns: an own, enumerable, string key, which is what a plain
+ * object literal or a spread builds. A symbol key, a non-enumerable key or an
+ * inherited one is not judged, and no engine reads one either. Core's own query
+ * merge (`unionQueries`, `composeProjections`) carries an envelope's unknown key
+ * into the merged query rather than dropping it, so composing slices cannot launder
+ * a smuggled key past this check.
+ *
+ * It does not close the neighbouring one, and cannot: a field ADDED to the grammar's
+ * schema is a known key from that edit on and passes here, while the plpgsql guard
+ * still has to be taught it by hand. That exposure is the Postgres guard's, and its
+ * own comment in that engine's DDL says so.
+ *
+ * The known keys are read off the SCHEMA's own `fields` rather than listed here, so
+ * a field added to the grammar is admitted by the same edit that adds it. Only key
+ * NAMES are judged: an exact-optional key written as `undefined` is a known key and
+ * passes, because which values a key admits is the type's business, not this rule's.
+ */
+const unknownKeyFault = (
+  where: string,
+  value: object,
+  schemaFields: object,
+): string | undefined => {
+  const unknown = Object.keys(value).find(
+    (key) => !Object.hasOwn(schemaFields, key),
+  )
+  return unknown === undefined
+    ? undefined
+    : `assertServableQuery: ${where} carries the key ${JSON.stringify(unknown)}, which ` +
+        'the query grammar does not define; an unknown key would be silently ignored ' +
+        'by every engine rather than honoured, so it is refused'
+}
+
+/**
+ * The unknown-key half of `servableQueryFault`, on its own: the refusal of a key the
+ * grammar does not define on the envelope or on any item, or `undefined`.
+ *
+ * It is the same rule and not a second statement of it — `servableQueryFault` calls
+ * this first. It is exported because ONE caller has to tell the two halves apart:
+ * the codec's read ledger refuses an unservable SHAPE on its own error channel, and
+ * must not report an unknown key as one. An unknown key is not something a slice's
+ * tags can fix, so the ledger leaves it to the store, which refuses it as a defect.
+ */
+export const unknownQueryKeyFault = (query: Query): string | undefined =>
+  unknownKeyFault('a query', query, Query.fields) ??
+  query.items.reduce<string | undefined>(
+    (fault, item) =>
+      fault ?? unknownKeyFault('a query item', item, QueryItem.fields),
+    undefined,
+  )
+
 /**
  * The servable grammar as a TOTAL function: the reason `query` cannot be served,
  * or `undefined` when it can.
@@ -126,6 +195,10 @@ export const assertServableQuery = (query: Query): void => {
  * reason), so a fault is one exit route and one return type.
  */
 export const servableQueryFault = (query: Query): string | undefined => {
+  const unknownKey = unknownQueryKeyFault(query)
+  if (unknownKey !== undefined) {
+    return unknownKey
+  }
   const { items } = query
   // Wildcard and single-item queries are always servable.
   if (items.length <= 1) {