@kairos-es/core 0.0.0

package/src/inMemory.ts

@@ -0,0 +1,356 @@
+/**
+ * The in-memory `DcbEventStore` layer: the canonical, readable form of the DCB
+ * check-then-append algorithm (ported from `popo.py`).
+ *
+ * The log is a `Ref<ReadonlyArray<SequencedEvent>>` in ascending position
+ * order. The whole check-then-append is run inside a single
+ * `Effect.makeSemaphore(1)`+`withPermits(1)` critical section: the conditional
+ * read and the commit must not be separable, and that atomicity is the entire
+ * concurrency guarantee (exactly-one-wins under a race). Positions come from a
+ * monotonic counter starting at 1n (contiguous here; the contract only promises
+ * strictly-increasing, gaps permitted).
+ *
+ * `subscribe` is core's shared `subscribeStream` and NOT an algorithm of this
+ * engine's own. The engine supplies the two transport seams — a paged `fetch` over
+ * the log `Ref` and the append hub as a wake source — and inherits catch-up, the
+ * cursor de-dup, the poll and the reconcile whole, exactly as it supplies mechanics
+ * to `makeContractStore` and inherits the contract policy whole. That inheritance
+ * matters more here than in any other engine, because this store is the parity
+ * ORACLE the rest are measured against: an oracle that delivered by an algorithm of
+ * its own would turn the shared suite's subscribe cases into a comparison of two
+ * implementations, where what they are for is comparing two backends.
+ *
+ * One append is one commit under one permit, so no writer can commit a position
+ * below one a concurrent writer has already made visible — which is how this engine
+ * 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 type { AppendCondition } from './AppendCondition'
+import { makeContractStore, type RawDcbEventStore } from './ContractStore'
+import type { ReadOptions, ReadResponse } from './DcbEventStore'
+import { DcbEventStore } from './DcbEventStore'
+import type { DcbEvent, Position, ReadLimit, SequencedEvent } from './Event'
+import { ORIGIN } from './Event'
+import { AppendConditionFailed } from './errors'
+import type { Query } from './Query'
+import { matchesSequenced } from './Query'
+import {
+  DEFAULT_CATCH_UP_PAGE_SIZE,
+  DEFAULT_POLL_INTERVAL_MILLIS,
+  subscribeStream,
+} from './SubscribeMachine'
+
+/** Filter a snapshot by `query` and `after` (strict `position > after`). */
+const filterLog = (
+  log: ReadonlyArray<SequencedEvent>,
+  query: Query,
+  after: Position | undefined,
+): ReadonlyArray<SequencedEvent> =>
+  log.filter(
+    (sequenced) =>
+      (after === undefined || sequenced.position > after) &&
+      matchesSequenced(sequenced, query),
+  )
+
+/** The position of the last event in a slice, or `undefined` when empty. */
+const lastPosition = (
+  events: ReadonlyArray<SequencedEvent>,
+): Position | undefined => events.at(-1)?.position
+
+/**
+ * Compute the read result over a snapshot: filter, apply the limit, and derive
+ * `head` per the contract (no limit => global last position or ORIGIN; limit =>
+ * last returned position or ORIGIN).
+ */
+const readSnapshot = (
+  log: ReadonlyArray<SequencedEvent>,
+  query: Query,
+  options: ReadOptions | undefined,
+): ReadResponse => {
+  const matched = filterLog(log, query, options?.after)
+  const limited =
+    options?.limit === undefined ? matched : matched.slice(0, options.limit)
+
+  // No limit => head is the global last position (ignoring the filter). With a
+  // limit => head is the last returned event's position. Either way, ORIGIN
+  // when there is nothing to report.
+  const head =
+    (options?.limit === undefined
+      ? lastPosition(log)
+      : lastPosition(limited)) ?? ORIGIN
+
+  return { events: Stream.fromIterable(limited), head }
+}
+
+/**
+ * The index of the first event strictly after `after`, by BINARY SEARCH.
+ *
+ * The log is append-only and ascending by position, so the cursor cut is a boundary
+ * in a sorted array and costs O(log n). That is what makes a live subscription's
+ * idle poll affordable at any log size: the poll re-reads from its cursor every
+ * interval whether or not anything arrived, so a linear cut would charge every open
+ * subscription O(n) per interval for as long as it stayed open.
+ */
+const firstIndexAfter = (
+  log: ReadonlyArray<SequencedEvent>,
+  after: Position,
+): number => {
+  let low = 0
+  let high = log.length
+  while (low < high) {
+    // `>>> 1` rather than a divide: an integer midpoint with no rounding step.
+    const mid = (low + high) >>> 1
+    if (log[mid].position > after) {
+      high = mid
+    } else {
+      low = mid + 1
+    }
+  }
+  return low
+}
+
+/**
+ * `subscribeStream`'s `fetch` seam: up to `limit` events matching `query` strictly
+ * after `from`, ascending.
+ *
+ * The cursor cut comes FIRST and the query match second, so the predicate only ever
+ * sees candidates the cursor admits, and the scan stops the moment `limit` of them
+ * have matched rather than filtering a tail it would discard.
+ *
+ * Deliberately not expressed through `filterLog`, and the reason is COST rather than
+ * the answer: that form returns the same events and scans the whole log per page.
+ *
+ * What is not interchangeable is what the cap COUNTS. The machine's paging contract
+ * reads a SHORT page as "the tail is drained", so the cap has to count MATCHES and a
+ * short page has to mean the scan ran off the end of the log. A cap counting
+ * CANDIDATES — `limit` events taken by POSITION, with the predicate applied within
+ * them — reports a short page for a window that merely held few matches; and a window
+ * holding NONE reports a drained tail while advancing the cursor nowhere, so the
+ * subscription is WEDGED rather than delayed, with no later poll able to move it.
+ * `InMemoryStoreOptions.catchUpPageSize` is what puts a test at that boundary.
+ */
+const fetchPage = (
+  log: ReadonlyArray<SequencedEvent>,
+  query: Query,
+  from: Position,
+  limit: ReadLimit,
+): ReadonlyArray<SequencedEvent> => {
+  const page: Array<SequencedEvent> = []
+  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)
+    }
+  }
+  return page
+}
+
+/**
+ * Options for the in-memory store factory.
+ *
+ * `beforeCommit` runs inside the append critical section, between the
+ * conflict-check and the commit. It defaults to `Effect.void` — a synchronous
+ * no-op — so the shipped critical section stays atomic by construction
+ * (`Ref.get` -> filter -> `Ref.set`, no suspension), which is the whole
+ * exactly-one-wins guarantee. It is a test seam: the concurrency contract test
+ * overrides it with `Effect.yieldNow()` to force a check/commit suspension, so
+ * the guarantee genuinely depends on `withPermits(1)` serialising across that
+ * boundary — without an injected suspension the test is vacuous (it passes even
+ * with the mutex removed). Real async backends (e.g. Postgres) have this
+ * boundary intrinsically; the in-memory store injects it only under test.
+ *
+ * `suppressWake` stops `append` publishing to the hub, so no wake ever reaches a
+ * live subscriber and the only path left to a delivery is the subscribe machine's
+ * periodic poll. It defaults to `false` — the shipped store always wakes — and it
+ * earns its place for the same reason `beforeCommit` does: the machine's stated
+ * guarantee is that the POLL and not the wake source is what makes delivery correct,
+ * and every ordinary subscribe test could be passing purely via the hub, which
+ * leaves that load-bearing claim asserted only in a comment. Suppressing the PUBLISH
+ * rather than the machine's `listen` keeps `subscribe`'s wiring identical to
+ * production's: what changes is that the wake never fires, which is exactly what a
+ * wake source that died silently does to a real engine.
+ *
+ * `catchUpPageSize` lowers the catch-up page size the subscribe machine runs this
+ * store's subscriptions at, defaulting to core's `DEFAULT_CATCH_UP_PAGE_SIZE` — and it
+ * earns its place the same way its siblings here do. At that default a catch-up drains
+ * in ONE page for any backlog a test would write, so the page loop's exit condition is
+ * taken on the FIRST page every time and `fetchPage`'s whole reason for existing is a
+ * claim about a boundary nothing reaches. Lowering the page brings the SECOND one
+ * within reach: a store that cannot be made to page cannot be asked whether it pages
+ * correctly.
+ *
+ * `pollInterval` lowers the ceiling on how long the subscribe machine waits for a
+ * wake before re-reading from its cursor anyway (milliseconds), defaulting to core's
+ * `DEFAULT_POLL_INTERVAL_MILLIS`. The oracle takes its subscribe tuning from exactly
+ * where the engines it judges take theirs, so a figure chosen here instead would be
+ * this store drifting from all of them by a factor nothing outside its own tests ever
+ * asked for.
+ *
+ * A seam rather than a shorter shipped default, and what that costs is MEASURED
+ * rather than assumed: at core's default, NO subscribe case in the shared contract
+ * suite reaches a poll timeout against this store. Those cases run on a real clock
+ * and finish in a few hundred milliseconds, and the hub wake carries every delivery
+ * they assert, so the poll — the half that carries delivery whenever no wake is
+ * heard — is never what delivered one. A case that wants the POLL to deliver here
+ * must therefore ask for an interval short enough to elapse inside it, and taking the
+ * wake away is what makes such a case prove anything. Asking is cheap: the machine
+ * treats the interval as a CEILING on a wait and never as a tick rate, so a wake
+ * still returns at once and only an IDLE subscription pays — one `fetch` per
+ * interval, which here is a binary search plus a bounded scan over an array.
+ */
+export interface InMemoryStoreOptions {
+  readonly beforeCommit?: Effect.Effect<void>
+  readonly suppressWake?: boolean
+  readonly catchUpPageSize?: number
+  readonly pollInterval?: number
+}
+
+/**
+ * Build the in-memory store MECHANICS (a `RawDcbEventStore`), wiring the Ref,
+ * semaphore and hub. The contract-enforcement policy (`assertServableQuery`,
+ * `ReadLimit` decode, error-vs-defect classification) is NOT here — it is added
+ * uniformly by `makeContractStore`, so this engine is pure mechanics.
+ */
+const make = (
+  options?: InMemoryStoreOptions,
+): Effect.Effect<RawDcbEventStore<never>> =>
+  Effect.gen(function* () {
+    const beforeCommit = options?.beforeCommit ?? Effect.void
+    const suppressWake = options?.suppressWake ?? false
+    const catchUpPageSize =
+      options?.catchUpPageSize ?? DEFAULT_CATCH_UP_PAGE_SIZE
+    const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL_MILLIS
+    const log = yield* Ref.make<ReadonlyArray<SequencedEvent>>([])
+    const mutex = yield* Effect.makeSemaphore(1)
+    const hub = yield* PubSub.unbounded<SequencedEvent>()
+    const nextPosition = yield* Ref.make<bigint>(1n)
+
+    const read = (
+      query: Query,
+      options?: ReadOptions,
+    ): Effect.Effect<ReadResponse> =>
+      // The lock keeps read consistent with concurrent appends; popo.py's RLock
+      // 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: 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)
+
+          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: 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 subscribe = (
+      query: Query,
+      after?: Position,
+    ): Stream.Stream<SequencedEvent, never, Scope.Scope> =>
+      // 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
+      // ordering is what keeps delivery independent of the poll's timer: an append
+      // either lands before that first read, and the read sees it, or after the seat
+      // exists, and its wake is queued. The machine drains a wake source on a forked
+      // fibre, so a seat taken inside that fibre would leave a window in which an
+      // append publishes to nobody — recoverable by the next poll, but only on a
+      // real clock, and much of this store's use is under `TestClock`.
+      //
+      // No mutex: `Ref.get` already reads one committed snapshot, and the machine's
+      // exclusive cursor is what makes the catch-up/live seam exactly-once, so there
+      // 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* () {
+          const wakes = yield* PubSub.subscribe(hub)
+          return subscribeStream<never>(
+            {
+              fetch: (from, limit) =>
+                Effect.map(Ref.get(log), (snapshot) =>
+                  fetchPage(snapshot, query, from, limit),
+                ),
+              listen: Stream.fromQueue(wakes),
+              pollInterval,
+              catchUpPageSize,
+            },
+            after,
+          )
+        }),
+      )
+
+    return { read, append, subscribe } as const
+  })
+
+/** The in-memory `DcbEventStore` layer (production; no test seam). */
+export const DcbEventStoreInMemory: Layer.Layer<DcbEventStore> = Layer.effect(
+  DcbEventStore,
+  Effect.map(make(), makeContractStore),
+)
+
+/**
+ * Test-only in-memory layer factory: the same store as `DcbEventStoreInMemory`, but
+ * with `InMemoryStoreOptions`' seams open. Kept off the package's public surface
+ * (deliberately not re-exported from `index.ts`); production code always uses
+ * `DcbEventStoreInMemory`. Every seam exists to make a claim about this store
+ * FALSIFIABLE rather than merely commented — the store contract suite forces the
+ * check/commit interleaving the exactly-one-wins case needs, one core test takes the
+ * wake away and shortens the poll so that what delivers can only be the poll, and
+ * another lowers the catch-up page to reach the second-page boundary the shipped page
+ * size puts out of reach.
+ */
+export const makeInMemoryTestLayer = (
+  options: InMemoryStoreOptions,
+): Layer.Layer<DcbEventStore> =>
+  Layer.effect(DcbEventStore, Effect.map(make(options), makeContractStore))

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @kairos-es/core: DCB-first event-sourcing contract and in-memory store for
+ * Effect v3.
+ *
+ * Exposes the domain types (`DcbEvent`, `SequencedEvent`, `Position`, `Tag`,
+ * `EventType`), the selection language (`Query`, `QueryItem`, the pure match
+ * predicate + smart constructors, and the servable-shape dispatch every engine
+ * compiles its plans through), the `AppendCondition`, tagged errors, the
+ * `DcbEventStore` contract, the in-memory layer, the shared subscribe machine
+ * every engine's `subscribe` is built from (`SubscribeMachine.ts`), the pure
+ * projection primitives (`Projection`, `DecodedEvent`, `composeProjections`), and
+ * `retryOnConflict`.
+ *
+ * Core keeps only the *pure* fold: projections fold an already-`DecodedEvent`
+ * (decoding needs `Schema` + a `Serializer`, which core must not depend on).
+ * The event-def builder and the decode-aware `buildDecisionModel` live in
+ * `@kairos-es/codec`.
+ *
+ * `retryOnConflict` is here because it is the recovery half of the append
+ * condition — the only consistency mechanism there is. It matches the
+ * `AppendConditionFailed` core defines and needs nothing beyond `effect`'s
+ * `Schedule`, which core already peers, so homing it downstream only made a
+ * write-only consumer depend on a package it uses nothing else of (ADR-0008).
+ */
+export * from './AppendCondition'
+export * from './ContractStore'
+export * from './DcbEventStore'
+export * from './Event'
+export * from './errors'
+// Named re-export (not `export *`): `DcbEventStoreInMemory` is the whole public
+// in-memory surface. `makeInMemoryTestLayer` / `InMemoryStoreOptions` are a
+// test-only seam and are deliberately kept off the package's public exports.
+export { DcbEventStoreInMemory } from './inMemory'
+export * from './Projection'
+export * from './Query'
+export * from './retryOnConflict'
+export * from './SubscribeMachine'

package/src/retryOnConflict.ts

@@ -0,0 +1,100 @@
+/**
+ * `retryOnConflict` — the decider-level retry for `AppendConditionFailed`
+ * (ADR-0008).
+ *
+ * `append` surfaces a conflict as a SIGNAL only: a tagged `AppendConditionFailed`
+ * flattened to the tripped condition, carrying no conflicting position,
+ * deliberately so that a retry cannot resume from a stale conflict point. A
+ * correct DCB retry must therefore re-derive its append-condition lower bound
+ * from a FRESH READ to the current head — which means re-running the whole
+ * read-decide-append cycle, not re-submitting the same events.
+ *
+ * That is why this is a combinator over a command and NOT a `Layer` decorating
+ * `DcbEventStore.append`. A decorator sees only the events and the condition; it
+ * cannot re-read the log and it cannot re-decide, so it is STRUCTURALLY incapable
+ * of a correct DCB retry — the only thing it could do is re-submit against a
+ * condition that is already known to be stale, which either fails again forever
+ * or, worse, succeeds against a boundary the decision was never made under. No
+ * retrying `Layer` is shipped, and if a production command-runner service ever
+ * emerges, a `Layer` over THAT (a whole cycle) is the shape to add.
+ *
+ * It lives HERE, in `@kairos-es/core`, because conflict retry is a WRITE-side
+ * concern and core is where the write side is defined: core declares the `append`
+ * contract, defines the `AppendConditionFailed` this combinator matches, and
+ * already peers `effect` for `Schedule`, so the move costs nothing and adds no
+ * dependency in either direction. It shipped from `@kairos-es/read` first on the
+ * argument that it added no peer surface there either — true, but an argument for
+ * where it MAY live, not where it SHOULD. What that home actually cost was a
+ * write-only consumer having to depend on the READ package to retry its own
+ * appends, for a combinator that touches no projection, no checkpoint and no view
+ * (ADR-0008, homing amended).
+ *
+ * Core stays pure with it here. `Schedule`'s driver reads the time through
+ * `Clock.currentTimeMillis` and sleeps through `Clock.sleep`, both resolved from
+ * the fibre's default services, so `TestClock` still governs every delay; the
+ * jitter draws from `Random.next`, a default service on the same footing as the
+ * clock rather than a host `Math.random`. No `node:*`, no wall-clock reading, no
+ * ungoverned RNG.
+ *
+ * Effect v3 caveat: the `Schedule` API below is the THREE-type-parameter
+ * `Schedule<Out, In, R>` that `effect@3` exports, with `Schedule.intersect`. The
+ * currently-published docs show a newer four-type-parameter `Schedule` without
+ * `intersect` — do not copy them; this file is written against the installed
+ * `effect@3` type definitions.
+ */
+import { Effect, Predicate, Schedule } from 'effect'
+import type { AppendConditionFailed } from './errors'
+
+/**
+ * The default conflict backoff: exponential from 20ms, jittered, capped at five
+ * retries.
+ *
+ * `Schedule.intersect` continues only while BOTH schedules continue, so the
+ * `recurs(5)` arm is what bounds the attempts and the exponential arm is what
+ * spaces them. Jitter matters more here than in a typical backoff: contending
+ * deciders conflict precisely because they read the same boundary at the same
+ * time, so an unjittered backoff would re-synchronise them into the same conflict
+ * on every round. The figures are the conventional starting point (Emmett,
+ * Kurrent and Dudycz all land in this neighbourhood) and are a DEFAULT — a
+ * command with a tighter latency budget, or one contending harder, should pass its
+ * own schedule.
+ */
+const conflictBackoff = Schedule.intersect(
+  Schedule.jittered(Schedule.exponential('20 millis', 2)),
+  Schedule.recurs(5),
+)
+
+/**
+ * Retry `command` while — and only while — it fails `AppendConditionFailed`.
+ *
+ * `command` must be the WHOLE read-decide-append cycle (read a decision model to
+ * the current head, decide, append under that read's condition), because each
+ * retry's correctness comes from the re-read: the fresh read re-derives the
+ * append condition's `after` from the new head, so the retried append is judged
+ * against the boundary the retried decision was actually made under. Wrapping only
+ * the `append` re-submits a stale condition and is wrong.
+ *
+ * A non-conflict `E` is preserved on the error channel and escapes IMMEDIATELY
+ * with zero retries: the `while` predicate is false for it, so a domain rejection
+ * ("course is full") never pays a backoff and never retries into a decision the
+ * log has already refused. `A`, the non-conflict `E`, and `R` all pass through
+ * untouched.
+ *
+ * The predicate matches on the `_tag` rather than `instanceof`. The tag is the
+ * error's identity across module realms, and a published package ships dual
+ * ESM/CJS, so an `instanceof` check can see two distinct classes for the same
+ * error when a consumer's graph loads both builds — a conflict would then escape
+ * unretried and silently.
+ */
+export const retryOnConflict = <A, E, R>(
+  command: Effect.Effect<A, AppendConditionFailed | E, R>,
+  schedule: Schedule.Schedule<
+    unknown,
+    AppendConditionFailed | E,
+    R
+  > = conflictBackoff,
+): Effect.Effect<A, AppendConditionFailed | E, R> =>
+  Effect.retry(command, {
+    schedule,
+    while: Predicate.isTagged('AppendConditionFailed'),
+  })

package/src/testing.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic test-support utilities, shared across every kairos-es suite via
+ * the published `@kairos-es/core/testing` subpath.
+ *
+ * WHY a published subpath rather than a test-only package: three suites (core's
+ * own tests, the store contract suite, and the codec's `UuidTest` layer) each
+ * carried a byte-identical copy of the same counter-based uuid scheme and the
+ * `EPOCH` domain time. Copies drift. The one place every consumer already
+ * depends on is `@kairos-es/core`, so the single source of truth lives here as a
+ * *published* subpath — never a runtime dependency from a published package onto
+ * an unpublished/test-only one, which would create a packaging cycle.
+ *
+ * Everything here is PURE and DETERMINISTIC: no RNG, no wall-clock. That is the
+ * whole point — suites must produce the same bytes and positions on every run,
+ * so `data`/`uuid`/`occurredAt` never introduce nondeterminism into assertions.
+ */
+import { DateTime } from 'effect'
+
+/**
+ * A fixed domain time (`DateTime` at the Unix epoch) for test events.
+ *
+ * Ordering in the log is by `position` alone, so an event's `occurredAt` is
+ * informational; pinning it to the epoch keeps serialised bytes and comparisons
+ * stable across runs. Built via `DateTime.unsafeMake(0)` (the value is a
+ * compile-time constant, not read from the host clock).
+ */
+export const EPOCH = DateTime.unsafeMake(0)
+
+/**
+ * Build a fresh, deterministic uuid generator: a zero-based counter producing
+ * RFC-4122 v4-shaped ids `00000000-0000-4000-8000-<counter as 12 hex digits>`,
+ * starting at `...000000000000` and incrementing on each call.
+ *
+ * A *factory* (not a shared singleton) so each layer/suite instance owns its own
+ * counter and the sequence is repeatable in isolation — two independent suites
+ * do not interfere, yet each is stable on its own. No RNG: the ids are
+ * comparable and predictable, which is what assertions need, while still being
+ * distinct enough to tell events apart.
+ */
+export const makeSequentialUuid = (): (() => string) => {
+  let counter = 0
+  return () => {
+    const suffix = counter.toString(16).padStart(12, '0')
+    counter += 1
+    return `00000000-0000-4000-8000-${suffix}`
+  }
+}

package/testing/package.json

@@ -0,0 +1,6 @@
+{
+  "sideEffects": [],
+  "main": "../dist/cjs/testing.js",
+  "module": "../dist/esm/testing.js",
+  "types": "../dist/dts/testing.d.ts"
+}