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

package/src/Event.ts

@@ -6,19 +6,55 @@
  * payloads into these bytes. Ordering is by `position` alone; `occurredAt` is
  * producer-supplied domain time and is informational only.
  */
-import { Schema } from 'effect'
+import {
+  BigInt as BigInt_,
+  Effect,
+  Option,
+  Schema,
+  SchemaIssue,
+  SchemaTransformation,
+} from 'effect'
 
 /**
  * A position in the single global event log: a branded, non-negative `bigint`.
  *
  * The log is 64-bit (`bigserial` in Postgres) and exceeds JS `number` safety at
  * 2^53, so positions are a `bigint`. They are compared, never arithmetic'd.
- * `Schema.BigInt` encodes to a decimal string (JSON-safe) and decodes to
+ * Encoded, a position is a decimal string (JSON-safe, `String(b)`); decoded, a
  * `bigint`. `0n` is the "before the first event" sentinel used by `after` and by
  * an empty store's head.
+ *
+ * The string-to-`bigint` step is hand-built rather than Effect 4's
+ * `Schema.BigIntFromString`, because that schema accepts only `^-?\d+$` and so
+ * refuses inputs the encoded side has always admitted — `" 5"`, `"+5"`,
+ * `"0x10"`. The decode here is the global `BigInt(s)` behind a blank-string
+ * refusal, which is `BigInt.fromString` and is exactly what Effect 3's
+ * `Schema.BigInt` ran, so a position string any earlier release decoded still
+ * decodes to the same value. The non-negative check then runs on the `bigint`,
+ * as it always did.
  */
-export const Position = Schema.BigInt.pipe(
-  Schema.nonNegativeBigInt(),
+export const Position = Schema.String.pipe(
+  Schema.decodeTo(
+    Schema.BigInt,
+    SchemaTransformation.transformEffect<bigint, string>({
+      decode: (s, options) =>
+        Option.match(BigInt_.fromString(s), {
+          onNone: () =>
+            Effect.fail(
+              new SchemaIssue.InvalidValue(
+                {
+                  message: `Unable to decode ${JSON.stringify(s)} into a bigint`,
+                },
+                s,
+                options,
+              ),
+            ),
+          onSome: Effect.succeed,
+        }),
+      encode: (b) => Effect.succeed(String(b)),
+    }),
+  ),
+  Schema.check(Schema.isGreaterThanOrEqualToBigInt(0n)),
   Schema.brand('Position'),
 )
 export type Position = typeof Position.Type
@@ -33,7 +69,7 @@ export const ORIGIN: Position = Position.make(0n)
  * item's tags (superset test).
  */
 export const Tag = Schema.String.pipe(
-  Schema.pattern(/^[^:]+:.+/, { identifier: 'Tag' }),
+  Schema.check(Schema.isPattern(/^[^:]+:.+/, { identifier: 'Tag' })),
   Schema.brand('Tag'),
 )
 export type Tag = typeof Tag.Type
@@ -95,7 +131,7 @@ export const tagIdentity = (key: string): TagIdentity => {
  * `ReadLimit.make(n)`.
  */
 export const ReadLimit = Schema.Int.pipe(
-  Schema.greaterThanOrEqualTo(0),
+  Schema.check(Schema.isGreaterThanOrEqualTo(0)),
   Schema.brand('ReadLimit'),
 )
 export type ReadLimit = typeof ReadLimit.Type
@@ -105,25 +141,86 @@ export type ReadLimit = typeof ReadLimit.Type
  * in the name (e.g. `course-registered.v2`); only non-emptiness is enforced.
  */
 export const EventType = Schema.String.pipe(
-  Schema.nonEmptyString(),
+  Schema.check(Schema.isNonEmpty()),
   Schema.brand('EventType'),
 )
 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(Schema.String, 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).
+ * It is checked for UUID SHAPE only (`isGUID`), not for a version nibble: a
+ * stricter check would refuse ids an existing log already holds.
  * `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,
-  data: Schema.Uint8ArrayFromSelf,
+  data: Schema.Uint8Array,
   tags: Schema.Array(Tag),
-  uuid: Schema.UUID,
-  occurredAt: Schema.DateTimeUtc,
+  uuid: Schema.String.check(Schema.isGUID()),
+  occurredAt: Schema.DateTimeUtcFromString,
+  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) {
@@ -200,7 +273,7 @@ export const classifyServableQuery = (query: Query): ServableQueryShape => {
   }
   const only = query.items.length === 1 ? query.items[0] : undefined
   if (only !== undefined && only.tags.length === 0) {
-    return Arr.isNonEmptyReadonlyArray(only.types)
+    return Arr.isReadonlyArrayNonEmpty(only.types)
       ? { kind: 'typeOnly', types: only.types }
       : { kind: 'wildcard' }
   }

package/src/SubscribeMachine.ts

@@ -69,7 +69,6 @@
  * where an ephemeral view re-catches-up the entire log on every boot.
  */
 import {
-  Chunk,
   Effect,
   Option,
   Queue,
@@ -120,12 +119,12 @@ export const DEFAULT_POLL_INTERVAL_MILLIS = 1000
  * the key NAME, the VALIDATION and the DEFAULT from one place, so a caller who has
  * tuned one engine's subscribe reads another's without translating, and the two
  * cannot drift in what they ACCEPT any more than in what they assume. Two engines
- * hand-authoring the identical `Schema.optionalWith(…)` twice were identical only
+ * hand-authoring the identical `Schema.optionalKey(…)` twice were identical only
  * by inspection.
  *
  * The bounds differ between the two because the quantities do. `pollInterval` is a
- * duration, so a fraction of a millisecond is meaningful and only `positive` and
- * `finite` matter: at zero or below the loop would spin without ever waiting for a
+ * duration, so a fraction of a millisecond is meaningful and only `isGreaterThan(0)`
+ * and `isFinite` matter: at zero or below the loop would spin without ever waiting for a
  * wake, and at `Infinity` the periodic re-read — the half that carries delivery —
  * would never come, which silently converts the wake source from an optimisation
  * into the guarantee. `catchUpPageSize` is a COUNT, so it must be an integer
@@ -133,18 +132,17 @@ export const DEFAULT_POLL_INTERVAL_MILLIS = 1000
  * length against it to decide the tail is drained, and a page of zero would report
  * "drained" forever without reading anything.
  *
- * `exact: true` on both keeps the decoded type at `key?: T` rather than
+ * `optionalKey` on both keeps the decoded type at `key?: T` rather than
  * `T | undefined`, matching the repo's `exactOptionalPropertyTypes` discipline — an
  * absent key, never an explicit `undefined`.
  */
 export const subscriptionTuningFields = {
-  pollInterval: Schema.optionalWith(
-    Schema.Number.pipe(Schema.positive(), Schema.finite()),
-    { exact: true },
+  pollInterval: Schema.optionalKey(
+    Schema.Number.check(Schema.isGreaterThan(0), Schema.isFinite()),
+  ),
+  catchUpPageSize: Schema.optionalKey(
+    Schema.Int.check(Schema.isGreaterThan(0)),
   ),
-  catchUpPageSize: Schema.optionalWith(Schema.Int.pipe(Schema.positive()), {
-    exact: true,
-  }),
 } as const
 
 /**
@@ -154,10 +152,13 @@ export const subscriptionTuningFields = {
  * past the cap propagates (the decorator dies it) — infrastructure stays off the
  * contract channel while the stream survives ordinary transients.
  */
-const POLL_RETRY_SCHEDULE = Schedule.exponential('100 millis', 2).pipe(
-  Schedule.union(Schedule.spaced('2 seconds')),
-  Schedule.intersect(Schedule.recurs(20)),
-)
+const POLL_RETRY_SCHEDULE = Schedule.max([
+  Schedule.min([
+    Schedule.exponential('100 millis', 2),
+    Schedule.spaced('2 seconds'),
+  ]),
+  Schedule.recurs(20),
+])
 
 /**
  * The two seams the subscribe machine runs over, plus the two tuning knobs. `E` is
@@ -166,7 +167,7 @@ const POLL_RETRY_SCHEDULE = Schedule.exponential('100 millis', 2).pipe(
  *
  * ONE type parameter and not two, deliberately: a wake source with an error type of
  * its own is `Stream.orDie`d by the caller, yielding a `Stream<unknown, never>`
- * that is assignable here under Effect v3's covariant error channel. A second
+ * that is assignable here under Effect's covariant error channel. A second
  * parameter would buy nothing and would have to be spelled at every call site. Nor
  * is there an `R`: neither seam contributes a requirement, and unused generality is
  * not free.
@@ -199,17 +200,17 @@ export interface SubscriptionDeps<E> {
 
 /**
  * Build the subscription `Stream`: catch up from `after`, then track the live tail.
- * The cursor threads through the `unfoldChunkEffect` unfold state, starting at
- * `after` and advancing to the last delivered position each batch; the stream never
- * completes on its own (always `Option.some`), so the enclosing scope interrupts it
- * on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
+ * The cursor threads through the `Stream.paginate` state, starting at `after` and
+ * advancing to the last delivered position each batch; the stream never completes
+ * on its own (the next state is always `Option.some`), so the enclosing scope
+ * interrupts it on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
  * (subscribe is `E = never` on the contract).
  */
 export const subscribeStream = <E>(
   deps: SubscriptionDeps<E>,
   after: Position | undefined,
 ): Stream.Stream<SequencedEvent, E, Scope.Scope> =>
-  Stream.unwrapScoped(
+  Stream.unwrap(
     Effect.gen(function* () {
       // The wake primitive: a sliding(1) queue holding at most one pending
       // signal. The wake source `offer`s an opaque wake on every notification;
@@ -230,9 +231,10 @@ export const subscribeStream = <E>(
       const listener = (deps.listen ?? Stream.never).pipe(
         Stream.tap(() => Queue.offer(wake, undefined)),
         Stream.retry(
-          Schedule.exponential('50 millis').pipe(
-            Schedule.union(Schedule.spaced('1 seconds')),
-          ),
+          Schedule.min([
+            Schedule.exponential('50 millis'),
+            Schedule.spaced('1 seconds'),
+          ]),
         ),
       )
       // Drain the wake source into the wake queue on a background fibre; the
@@ -280,7 +282,7 @@ export const subscribeStream = <E>(
 
       /**
        * Produce the NEXT non-empty batch from a cursor position, together with
-       * the advanced cursor — a pure `Position → Effect<[Chunk, next]>`. The
+       * the advanced cursor — a pure `Position → Effect<[events, next]>`. The
        * `> boundary` de-dup is enforced by `fetch`'s exclusive lower bound, so a
        * live re-read after a wake never re-emits an already-delivered position.
        *
@@ -288,18 +290,20 @@ export const subscribeStream = <E>(
        * the cursor. If a drain yields nothing, wait for a wake but only up to the
        * poll interval, then loop and re-read ANYWAY — the periodic position-based
        * poll that makes delivery correct independently of any wake. This effect
-       * only completes by returning a non-empty chunk; the scope interrupts it on
+       * only completes by returning a non-empty batch; the scope interrupts it on
        * close.
        */
       const nextBatch = (
         from: Position,
-      ): Effect.Effect<readonly [Chunk.Chunk<SequencedEvent>, Position], E> =>
+      ): Effect.Effect<readonly [ReadonlyArray<SequencedEvent>, Position], E> =>
         Effect.gen(function* () {
           while (true) {
-            yield* Queue.takeAll(wake)
+            // `Queue.clear` and not `Queue.takeAll`: the drain must NOT wait, and
+            // `takeAll` suspends until at least one signal is present.
+            yield* Queue.clear(wake)
             const { events, last } = yield* drainFrom(from)
             if (events.length > 0) {
-              return [Chunk.fromIterable(events), last] as const
+              return [events, last] as const
             }
             // Nothing new: block on a wake, but only up to the poll interval — on
             // timeout we fall through and the loop re-reads regardless.
@@ -309,8 +313,11 @@ export const subscribeStream = <E>(
           }
         })
 
-      return Stream.unfoldChunkEffect(after ?? ORIGIN, (from) =>
-        Effect.map(nextBatch(from), Option.some),
+      return Stream.paginate(after ?? ORIGIN, (from) =>
+        Effect.map(
+          nextBatch(from),
+          ([events, last]) => [events, Option.some(last)] as const,
+        ),
       )
     }),
   )