@kairos-es/core 0.0.0

package/dist/dts/Query.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The DCB selection language: `Query` is an OR of `QueryItem`s. Within an item,
+ * `types` is an OR-filter (empty means any type) and `tags` is an AND superset
+ * test (the event must carry all of the item's tags; extra event tags are
+ * fine). The empty query (`items: []`) matches every event.
+ *
+ * The match predicate is a single pure module function over plain data;
+ * `Query` values carry no methods. See `matchesQuery` / `matchesQueryItem`.
+ *
+ * Smart constructors enforce the indexed fast-path restriction at the
+ * constructor surface (not via a runtime throw): every query built through them
+ * is the wildcard (`query.all`), a single type-only item (`query.types`), or an
+ * OR of tagged items each carrying at least one tag (`query.item` + `query.or`,
+ * or `query.tags` for the single-item case). The `query.item` constructor
+ * requires a non-empty `tags` at the type level, so there is no public way to
+ * build an unrestricted item (empty types and empty tags). `QueryItem`/`Query`
+ * are plain data, so internal decision-model plumbing can still assemble any
+ * shape directly; the restriction binds the public surface, where consumers
+ * build their consistency boundaries.
+ *
+ * The grammar's DISPATCH lives here too, beside the grammar it dispatches over:
+ * `ServableQueryShape` / `classifyServableQuery` own the three shapes an engine
+ * serves and the routing of the degenerate empty item.
+ */
+import { Array as Arr, Schema } from 'effect';
+import { type DcbEvent, EventType, type SequencedEvent, Tag } from './Event.js';
+/**
+ * One clause of a query: a set of types (OR, empty = any) AND a set of tags
+ * (superset test, empty = no tag constraint).
+ */
+export declare const QueryItem: Schema.Struct<{
+    types: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "EventType">>;
+    tags: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "Tag">>;
+}>;
+export type QueryItem = typeof QueryItem.Type;
+/** A query: an OR of items. Empty `items` matches everything. */
+export declare const Query: Schema.Struct<{
+    items: Schema.Array$<Schema.Struct<{
+        types: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "EventType">>;
+        tags: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "Tag">>;
+    }>>;
+}>;
+export type Query = typeof Query.Type;
+/**
+ * True when `event` satisfies `item`: its type is in `item.types` (or the item
+ * has no type constraint) AND the event's tags are a superset of `item.tags`.
+ */
+export declare const matchesQueryItem: (event: DcbEvent, item: QueryItem) => boolean;
+/**
+ * The one true match predicate (ported from `popo.py:48-54`): an empty query is
+ * a wildcard; otherwise the event must match at least one item (OR across
+ * items).
+ */
+export declare const matchesQuery: (event: DcbEvent, query: Query) => boolean;
+/** Convenience predicate over a `SequencedEvent`. */
+export declare const matchesSequenced: (sequenced: SequencedEvent, query: Query) => boolean;
+/**
+ * Assert `query` is *servable* by the indexed fast paths, throwing a plain
+ * `Error` describing the violation otherwise. This enforces at the store
+ * boundary the restriction the smart constructors enforce at the type level
+ * (`Query.ts` module docs) but which plain-data assembly — e.g. decision-model
+ * composition, `Projection.ts:31-36` — can still bypass.
+ *
+ * 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
+ *   type-only item; or
+ * - a *multi*-item query (`items.length > 1`) in which every item carries at
+ *   least one tag.
+ *
+ * A multi-item query that mixes a tagless (type-only) item with tagged items is
+ * NOT servable: the by-type path and the by-tag path are indexed differently,
+ * so an OR spanning both cannot ride a single index. This is the previously
+ * un-enforced edge (`Projection.ts:31-36`).
+ *
+ * This function is pure (no clock, no RNG, no effect). Every engine applies it at
+ * its read/subscribe/append entry points, through the one shared
+ * `makeContractStore` decorator, so the rule is inherited rather than restated per
+ * backend; a throw inside a store `Effect` becomes a *defect* — a programming
+ * error, not an error-channel value — which is the intended "defect in every
+ * engine" behaviour.
+ */
+export declare const assertServableQuery: (query: Query) => void;
+/**
+ * The three shapes a servable query is SERVED by, and therefore the only three an
+ * engine's plan compiler dispatches over: the wildcard, a single type-only item,
+ * and an all-tagged query. `assertServableQuery` has already refused the mixed
+ * tagless-plus-tagged multi-item query, so these three are exhaustive over
+ * everything that reaches a store.
+ *
+ * `typeOnly` carries a NON-EMPTY list of types, and that is the whole guard
+ * against the degenerate empty item: see `classifyServableQuery`.
+ */
+export type ServableQueryShape = {
+    readonly kind: 'wildcard';
+} | {
+    readonly kind: 'typeOnly';
+    readonly types: Arr.NonEmptyReadonlyArray<EventType>;
+} | {
+    readonly kind: 'tagged';
+};
+/**
+ * Classify a servable `Query` into the shape that serves it.
+ *
+ * ## Why the dispatch lives beside the grammar
+ *
+ * The three shapes ARE the three bullets `assertServableQuery` above admits, so an
+ * engine that re-derives the dispatch is a second answer to "which shape is
+ * this?", and the shapes only stay in step while there is one answer. Core states
+ * the grammar, so stating the dispatch over it here is that one fact once rather
+ * than once per backend. It is pure — no clock, no RNG, no effect — and knows
+ * nothing of SQL: what a shape COMPILES to stays entirely the engine's.
+ *
+ * ## The degenerate empty item routes to the WILDCARD, structurally
+ *
+ * A single item with neither types nor tags — `{ items: [{ types: [], tags: [] }] }`
+ * — matches EVERY event: `matchesQueryItem` reads empty types as "any type" and
+ * empty tags as a vacuous superset test. It must therefore be served by the
+ * wildcard. Served by the type-only path it would compile to a value list with
+ * nothing in it, and a membership test against an empty list matches NOTHING — the
+ * exact inversion of what the query means. Nothing upstream stops it reaching an
+ * engine: `assertServableQuery` admits a SINGLE item of any shape, and the servable
+ * grammar forbids a tagless item only in a MULTI-item query, so this dispatch is
+ * the last place the divergence can be closed.
+ *
+ * It is closed by the SHAPE and not by a branch in front of it. `typeOnly` carries
+ * `NonEmptyReadonlyArray`, so there is no way to construct it from an empty list;
+ * the emptiness test IS the constructor, and deleting it does not silently restore
+ * the wrong routing, it stops compiling. A guard clause placed before the
+ * construction would have been deletable by anyone tidying what looks like a
+ * redundant check on a list that "obviously" has types in it.
+ */
+export declare const classifyServableQuery: (query: Query) => ServableQueryShape;
+/** Namespaced smart constructors for `Query`. */
+export declare const query: {
+    readonly all: () => Query;
+    readonly item: (fields: {
+        readonly tags: readonly [Tag, ...ReadonlyArray<Tag>];
+        readonly types?: ReadonlyArray<EventType>;
+    }) => QueryItem;
+    readonly or: (items: readonly [QueryItem, ...ReadonlyArray<QueryItem>]) => Query;
+    readonly tags: (tags: readonly [Tag, ...ReadonlyArray<Tag>], types?: ReadonlyArray<EventType>) => Query;
+    readonly types: (types: readonly [EventType, ...ReadonlyArray<EventType>]) => Query;
+};
+//# sourceMappingURL=Query.d.ts.map

package/dist/dts/Query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Query.d.ts","sourceRoot":"","sources":["../../src/Query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAE5E;;;GAGG;AACH,eAAO,MAAM,SAAS;;;EAGpB,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C,iEAAiE;AACjE,eAAO,MAAM,KAAK;;;;;EAEhB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,QAAQ,EAAE,MAAM,SAAS,KAAG,OAOnE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,QAAQ,EAAE,OAAO,KAAK,KAAG,OAK5D,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,GAC3B,WAAW,cAAc,EACzB,OAAO,KAAK,KACX,OAA+C,CAAA;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,KAAK,KAAG,IAelD,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAA;CACrD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,KAAK,KAAG,kBAWpD,CAAA;AAoDD,iDAAiD;AACjD,eAAO,MAAM,KAAK;wBAlCF,KAAK;4BATC;QACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;QACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;KAC1C,KAAG,SAAS;yBAkCJ,SAAS,CAAC,SAAS,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,KACvD,KAAK;0BAtBA,SAAS,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,UACnC,aAAa,CAAC,SAAS,CAAC,KAC/B,KAAK;4BAUC,SAAS,CAAC,SAAS,EAAE,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,KACvD,KAAK;CAoBE,CAAA"}

package/dist/dts/SubscribeMachine.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The subscribe machine every engine's `subscribe` is built from — the in-memory
+ * store, `@kairos-es/store-postgres` and `@kairos-es/store-sqlite`: the wake queue,
+ * the wake-source drain, the paged catch-up reconcile, the `> boundary` de-dup (via
+ * the cursor's exclusive lower bound) and the poll loop that together turn a paged
+ * read into a live subscription.
+ *
+ * It lives in core because delivery semantics are contract semantics. An engine
+ * supplies TRANSPORT through two STUBBABLE seams — `fetch`, a paged read strictly
+ * after a cursor, and `listen`, an optional wake source — and inherits the delivery
+ * behaviour whole, exactly as it supplies mechanics to `makeContractStore` and
+ * inherits the contract policy whole. Two engines that each grew their own wake
+ * loop would be identical only by inspection, and `subscribe` is the verb where
+ * that is least affordable: a divergence there loses events rather than failing.
+ * Both seams take plain in-memory values in a test, so the wake/poll/de-dup logic
+ * is exercisable with no live backend at all.
+ *
+ * All THREE are the callers, and the count matters to a reader here: it means there
+ * is exactly ONE delivery algorithm in this repo, and it is the code below. The
+ * in-memory store is a caller like the rest — it hands in a `fetch` over its log
+ * `Ref` and its append `PubSub` as a wake source and keeps no delivery logic of its
+ * own — which is what makes the shared contract suite's subscribe cases a comparison
+ * of two BACKENDS rather than of two delivery algorithms.
+ *
+ * Correctness rests on the periodic position-based reconcile — a re-read from the
+ * cursor every poll interval — and NEVER on the wake source, which only lowers
+ * delivery latency below that interval. A subscription with no wake source at all
+ * is therefore complete and correct, merely slower, which is why `listen` is
+ * optional in the TYPE rather than by the convention of passing `Stream.never`:
+ * poll-only delivery is a supported shape, not a degraded one.
+ *
+ * ## The precondition every engine inherits: ASCENDING COMMIT ORDER
+ *
+ * A position that is committed and VISIBLE must never be below one already
+ * delivered. Gaps are fine: the cursor is an ascending exclusive lower bound, so a
+ * number that is allocated and never committed, or never allocated at all, is
+ * simply a number the machine never sees. Out-of-order commits are not fine. If one
+ * writer allocates position 5 and another allocates 6, and 6 commits first, a poll
+ * landing between the two commits delivers 6 and advances the cursor past it — and
+ * 5 is then lost forever, because no later read looks below the cursor and nothing
+ * anywhere notices the hole. An engine whose concurrent writers can commit out of
+ * order MUST serialise them, or this machine will silently skip. An engine that
+ * takes an exclusive lock on both of its append paths discharges the obligation
+ * that way; an engine whose append is a single statement discharges it
+ * structurally.
+ *
+ * The obligation is written down HERE, in the algorithm that depends on it, rather
+ * than in whichever engine happens to satisfy it. It is a property of this delivery
+ * loop and of nothing else, so an engine author reading only their own source has
+ * no way to discover that anything downstream needs it — and the failure mode is
+ * the worst kind there is: no error, no defect, no failing test, just an event that
+ * a subscriber never receives. A single engine owning both its append path and its
+ * own wake loop can leave the assumption implicit; a shared machine cannot.
+ *
+ * ## `catchUpPageSize` bounds the READ, not the emission
+ *
+ * `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds each
+ * `fetch` — but it COLLECTS every page into one array, which is emitted as a SINGLE
+ * chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
+ * subscriber joining behind a large log materialises the whole backlog before its
+ * consumer sees the first element.
+ *
+ * That is a memory characteristic and nothing more, which is why ONE chunk is
+ * enough here: downstream commit boundaries do not depend on the upstream chunking
+ * at all, because the read side's `Stream.groupedWithin` re-chunks the stream into
+ * bounded micro-batches whatever arrives (ADR-0007), so a projection's transactions
+ * stay small even against a one-chunk catch-up. The cost therefore lands on backlog
+ * memory alone, and it lands hardest on the durable-log-with-in-memory-view mode,
+ * where an ephemeral view re-catches-up the entire log on every boot.
+ */
+import { Effect, Schema, type Scope, Stream } from 'effect';
+import type { Position, SequencedEvent } from './Event.js';
+import { ReadLimit } from './Event.js';
+/**
+ * A short catch-up page size default for the reconcile loop. Reads page by page
+ * until a short page signals the tail is drained, so a large backlog is streamed in
+ * bounded chunks rather than one unbounded read. Every engine takes its
+ * `catchUpPageSize` from here — each SQL engine as its config's default, the
+ * in-memory store as its options' — so backends cannot drift on tuning.
+ */
+export declare const DEFAULT_CATCH_UP_PAGE_SIZE = 512;
+/**
+ * The default upper bound a subscriber waits for a wake before re-reading from its
+ * cursor ANYWAY (milliseconds). Every engine takes its `pollInterval` from here —
+ * each SQL engine as its config's default, the in-memory store as its options' — so
+ * backends cannot drift on tuning.
+ *
+ * This periodic position-based poll — not the wake source — IS the correctness
+ * guarantee: every committed position is reconciled within this interval whether or
+ * not a wake for it was ever heard. That covers a wake fired before the source was
+ * fully established, a coalesced or dropped wake, and a wake source that died
+ * silently and never said so. A wake source only lowers delivery latency BELOW this
+ * interval; it never carries delivery, so no engine's wake mechanism can make the
+ * right figure here engine-specific. It trades worst-case delivery latency against
+ * idle read volume and nothing else. Upstream `postgres_tt.py` picks the same
+ * one-second fallback poll (`conn.wait(..., interval=1)`).
+ */
+export declare const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
+/**
+ * The two subscribe-tuning config FIELDS, for an engine whose config is a `Schema`
+ * to spread into its own struct.
+ *
+ * These knobs are the machine's, not any engine's: they name what the loop above
+ * does, the figures they fall back to are the two constants declared beside them,
+ * and neither is derivable from a backend's own properties — which is why the
+ * defaults already live here. Shipping the FIELD rather than only the default is
+ * what closes the last gap in that arrangement. An engine that spreads these gets
+ * 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
+ * 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
+ * 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
+ * (`Schema.Int` excludes `Infinity` with it): the reconcile loop compares a page's
+ * 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
+ * `T | undefined`, matching the repo's `exactOptionalPropertyTypes` discipline — an
+ * absent key, never an explicit `undefined`.
+ */
+export declare const subscriptionTuningFields: {
+    readonly pollInterval: Schema.optionalWith<Schema.filter<Schema.filter<typeof Schema.Number>>, {
+        exact: true;
+    }>;
+    readonly catchUpPageSize: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
+        exact: true;
+    }>;
+};
+/**
+ * The two seams the subscribe machine runs over, plus the two tuning knobs. `E` is
+ * the engine's own infrastructure error — whatever its reads fail with — and it
+ * stays on the channel through to `makeContractStore`, which dies it.
+ *
+ * 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
+ * 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.
+ */
+export interface SubscriptionDeps<E> {
+    /**
+     * Page-read the events strictly after `from`, up to `limit`, ascending by
+     * position. Returning FEWER than `limit` signals the tail is drained.
+     */
+    readonly fetch: (from: Position, limit: ReadLimit) => Effect.Effect<ReadonlyArray<SequencedEvent>, E>;
+    /**
+     * The raw wake source: each element is an OPAQUE wake signal. The machine taps it
+     * into its own wake queue and drains it on a background fibre; it never reads the
+     * elements, so anything an engine can push on a change will do.
+     *
+     * OPTIONAL, and omitting it defaults to `Stream.never` at the point of use — an
+     * engine with no wake mechanism gets poll-only delivery, which the poll loop
+     * already makes correct. Under `exactOptionalPropertyTypes` that means omitting
+     * the key entirely rather than passing `undefined`.
+     */
+    readonly listen?: Stream.Stream<unknown, E>;
+    /** The poll interval in milliseconds (see `DEFAULT_POLL_INTERVAL_MILLIS`). */
+    readonly pollInterval: number;
+    /** The catch-up page size (see `DEFAULT_CATCH_UP_PAGE_SIZE`). */
+    readonly catchUpPageSize: number;
+}
+/**
+ * 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
+ * (subscribe is `E = never` on the contract).
+ */
+export declare const subscribeStream: <E>(deps: SubscriptionDeps<E>, after: Position | undefined) => Stream.Stream<SequencedEvent, E, Scope.Scope>;
+//# sourceMappingURL=SubscribeMachine.d.ts.map

package/dist/dts/SubscribeMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubscribeMachine.d.ts","sourceRoot":"","sources":["../../src/SubscribeMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EAEL,MAAM,EAIN,MAAM,EACN,KAAK,KAAK,EACV,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAU,SAAS,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB;;;;;;;CAQ3B,CAAA;AAcV;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAA;IACpD;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,MAAM,gBAAgB,CAAC,CAAC,CAAC,EACzB,OAAO,QAAQ,GAAG,SAAS,KAC1B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAyG5C,CAAA"}

package/dist/dts/errors.d.ts

@@ -0,0 +1,17 @@
+import type { AppendCondition } from './AppendCondition.js';
+declare const AppendConditionFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "AppendConditionFailed";
+} & Readonly<A>;
+/**
+ * Raised by `append` when the append condition's `failIfEventsMatch` query
+ * matches at least one event after `condition.after`. Carries only the
+ * offending condition: a correct retry re-reads the store to its new head and
+ * rebuilds its condition from there, so no conflicting position is carried (it
+ * would already be stale by the time it was acted on).
+ */
+export declare class AppendConditionFailed extends AppendConditionFailed_base<{
+    readonly condition: AppendCondition;
+}> {
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/dts/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;;;;AAExD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,2BAEzC;IACA,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAA;CACpC,CAAC;CAAG"}

package/dist/dts/inMemory.d.ts

@@ -0,0 +1,76 @@
+import { Effect, Layer } from 'effect';
+import { DcbEventStore } from './DcbEventStore.js';
+/**
+ * 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;
+}
+/** The in-memory `DcbEventStore` layer (production; no test seam). */
+export declare const DcbEventStoreInMemory: Layer.Layer<DcbEventStore>;
+/**
+ * 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 declare const makeInMemoryTestLayer: (options: InMemoryStoreOptions) => Layer.Layer<DcbEventStore>;
+//# sourceMappingURL=inMemory.d.ts.map

package/dist/dts/inMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemory.d.ts","sourceRoot":"","sources":["../../src/inMemory.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAuB,MAAM,QAAQ,CAAA;AAI3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAyH/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AA6HD,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC,aAAa,CAG5D,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,oBAAoB,KAC5B,KAAK,CAAC,KAAK,CAAC,aAAa,CAC+C,CAAA"}

package/dist/dts/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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.js';
+export * from './ContractStore.js';
+export * from './DcbEventStore.js';
+export * from './Event.js';
+export * from './errors.js';
+export { DcbEventStoreInMemory } from './inMemory.js';
+export * from './Projection.js';
+export * from './Query.js';
+export * from './retryOnConflict.js';
+export * from './SubscribeMachine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AAIxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}

package/dist/dts/retryOnConflict.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `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, Schedule } from 'effect';
+import type { AppendConditionFailed } from './errors.js';
+/**
+ * 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 declare const retryOnConflict: <A, E, R>(command: Effect.Effect<A, AppendConditionFailed | E, R>, schedule?: Schedule.Schedule<unknown, AppendConditionFailed | E, R>) => Effect.Effect<A, AppendConditionFailed | E, R>;
+//# sourceMappingURL=retryOnConflict.d.ts.map

package/dist/dts/retryOnConflict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryOnConflict.d.ts","sourceRoot":"","sources":["../../src/retryOnConflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,MAAM,EAAa,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAqBrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACrC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,EAAE,CAAC,CAAC,EACvD,WAAU,QAAQ,CAAC,QAAQ,CACzB,OAAO,EACP,qBAAqB,GAAG,CAAC,EACzB,CAAC,CACgB,KAClB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,EAAE,CAAC,CAI5C,CAAA"}

package/dist/dts/testing.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const EPOCH: DateTime.Utc;
+/**
+ * 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 declare const makeSequentialUuid: () => (() => string);
+//# sourceMappingURL=testing.d.ts.map

package/dist/dts/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,cAAyB,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,CAAC,MAAM,MAAM,CAOlD,CAAA"}

package/dist/esm/AppendCondition.js

@@ -0,0 +1,19 @@
+/**
+ * The optimistic-concurrency guard for `append`. The append fails if any event
+ * matching `failIfEventsMatch` exists strictly after `after`. This is the whole
+ * DCB consistency mechanism: "fail if anything I based my decision on has
+ * changed since I read it."
+ *
+ * `after` is exact-optional (absent, never `undefined`) per
+ * `exactOptionalPropertyTypes`. Absent means "scan the whole log".
+ */
+import { Schema } from 'effect';
+import { Position } from "./Event.js";
+import { Query } from "./Query.js";
+export const AppendCondition = /*#__PURE__*/Schema.Struct({
+  failIfEventsMatch: Query,
+  after: /*#__PURE__*/Schema.optionalWith(Position, {
+    exact: true
+  })
+});
+//# sourceMappingURL=AppendCondition.js.map

package/dist/esm/AppendCondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppendCondition.js","names":["Schema","Position","Query","AppendCondition","Struct","failIfEventsMatch","after","optionalWith","exact"],"sources":["../../src/AppendCondition.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;AASA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,QAAQ,QAAQ,YAAS;AAClC,SAASC,KAAK,QAAQ,YAAS;AAE/B,OAAO,MAAMC,eAAe,gBAAGH,MAAM,CAACI,MAAM,CAAC;EAC3CC,iBAAiB,EAAEH,KAAK;EACxBI,KAAK,eAAEN,MAAM,CAACO,YAAY,CAACN,QAAQ,EAAE;IAAEO,KAAK,EAAE;EAAI,CAAE;CACrD,CAAC","ignoreList":[]}