@kairos-es/core 0.0.0

package/dist/cjs/retryOnConflict.js

@@ -0,0 +1,95 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.retryOnConflict = void 0;
+var _effect = require("effect");
+/**
+ * `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.
+ */
+
+/**
+ * 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 = /*#__PURE__*/_effect.Schedule.intersect(/*#__PURE__*/_effect.Schedule.jittered(/*#__PURE__*/_effect.Schedule.exponential('20 millis', 2)), /*#__PURE__*/_effect.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.
+ */
+const retryOnConflict = (command, schedule = conflictBackoff) => _effect.Effect.retry(command, {
+  schedule,
+  while: _effect.Predicate.isTagged('AppendConditionFailed')
+});
+exports.retryOnConflict = retryOnConflict;
+//# sourceMappingURL=retryOnConflict.js.map

package/dist/cjs/retryOnConflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryOnConflict.js","names":["_effect","require","conflictBackoff","Schedule","intersect","jittered","exponential","recurs","retryOnConflict","command","schedule","Effect","retry","while","Predicate","isTagged","exports"],"sources":["../../src/retryOnConflict.ts"],"sourcesContent":[null],"mappings":";;;;;;AA4CA,IAAAA,OAAA,GAAAC,OAAA;AA5CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA;;;;;;;;;;;;;;AAcA,MAAMC,eAAe,gBAAGC,gBAAQ,CAACC,SAAS,cACxCD,gBAAQ,CAACE,QAAQ,cAACF,gBAAQ,CAACG,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,eACvDH,gBAAQ,CAACI,MAAM,CAAC,CAAC,CAAC,CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBO,MAAMC,eAAe,GAAGA,CAC7BC,OAAuD,EACvDC,QAAA,GAIIR,eAAe,KAEnBS,cAAM,CAACC,KAAK,CAACH,OAAO,EAAE;EACpBC,QAAQ;EACRG,KAAK,EAAEC,iBAAS,CAACC,QAAQ,CAAC,uBAAuB;CAClD,CAAC;AAAAC,OAAA,CAAAR,eAAA,GAAAA,eAAA","ignoreList":[]}

package/dist/cjs/testing.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.makeSequentialUuid = exports.EPOCH = void 0;
+var _effect = require("effect");
+/**
+ * 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.
+ */
+
+/**
+ * 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).
+ */
+const EPOCH = exports.EPOCH = /*#__PURE__*/_effect.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.
+ */
+const makeSequentialUuid = () => {
+  let counter = 0;
+  return () => {
+    const suffix = counter.toString(16).padStart(12, '0');
+    counter += 1;
+    return `00000000-0000-4000-8000-${suffix}`;
+  };
+};
+exports.makeSequentialUuid = makeSequentialUuid;
+//# sourceMappingURL=testing.js.map

package/dist/cjs/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":["_effect","require","EPOCH","exports","DateTime","unsafeMake","makeSequentialUuid","counter","suffix","toString","padStart"],"sources":["../../src/testing.ts"],"sourcesContent":[null],"mappings":";;;;;;AAgBA,IAAAA,OAAA,GAAAC,OAAA;AAhBA;;;;;;;;;;;;;;;;;AAkBA;;;;;;;;AAQO,MAAMC,KAAK,GAAAC,OAAA,CAAAD,KAAA,gBAAGE,gBAAQ,CAACC,UAAU,CAAC,CAAC,CAAC;AAE3C;;;;;;;;;;;AAWO,MAAMC,kBAAkB,GAAGA,CAAA,KAAqB;EACrD,IAAIC,OAAO,GAAG,CAAC;EACf,OAAO,MAAK;IACV,MAAMC,MAAM,GAAGD,OAAO,CAACE,QAAQ,CAAC,EAAE,CAAC,CAACC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACrDH,OAAO,IAAI,CAAC;IACZ,OAAO,2BAA2BC,MAAM,EAAE;EAC5C,CAAC;AACH,CAAC;AAAAL,OAAA,CAAAG,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/dist/dts/AppendCondition.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';
+export declare const AppendCondition: Schema.Struct<{
+    failIfEventsMatch: 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">>;
+        }>>;
+    }>;
+    after: Schema.optionalWith<Schema.brand<Schema.filter<typeof Schema.BigInt>, "Position">, {
+        exact: true;
+    }>;
+}>;
+export type AppendCondition = typeof AppendCondition.Type;
+//# sourceMappingURL=AppendCondition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AppendCondition.d.ts","sourceRoot":"","sources":["../../src/AppendCondition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAI/B,eAAO,MAAM,eAAe;;;;;;;;;;EAG1B,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA"}

package/dist/dts/ContractStore.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `makeContractStore` — the shared contract-enforcement POLICY every
+ * `DcbEventStore` engine wears, factored out of the engines so the policy is
+ * DEFINITIONALLY identical across backends rather than identical by inspection.
+ *
+ * Each engine implements only the MECHANICS (`RawDcbEventStore`): the actual
+ * read/append/subscribe, free to surface infrastructure faults on the error
+ * channel (`never` for the pure in-memory engine; `SqlError` for either SQL one).
+ * The decorator wraps those mechanics with the policy the contract demands — the
+ * policy the first two engines hand-duplicated, with the Postgres one even
+ * 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;
+ * - `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`;
+ * - `orDie` on read/subscribe infrastructure errors — `read`/`subscribe` are
+ *   `E = never` on the contract, so a raw fault is a defect, not a channel value;
+ * - the `AppendConditionFailed`-else-die classification on append, matched by
+ *   `_tag` and never by class identity — ONLY the contract conflict rides the
+ *   error channel; every other fault is a defect.
+ *
+ * The throws are deferred into the returned Effect/Stream (via `Effect.suspend`
+ * / `Effect.sync`), so a validation failure surfaces as a DEFECT WHEN THE EFFECT
+ * RUNS — never as a synchronous throw at the call site. This gives the contract
+ * suite a single trusted choke point and makes a further backend impossible to get
+ * subtly wrong: it supplies mechanics, the policy is inherited whole. That is how
+ * the third engine, `@kairos-es/store-sqlite`, acquired the policy — it writes not
+ * a line of it.
+ */
+import type { Array as Arr, Scope } from 'effect';
+import { Effect, Stream } from 'effect';
+import type { AppendCondition } from './AppendCondition.js';
+import type { DcbEventStore, ReadOptions, ReadResponse } from './DcbEventStore.js';
+import type { DcbEvent, Position, SequencedEvent } from './Event.js';
+import type { AppendConditionFailed } from './errors.js';
+import { type Query } from './Query.js';
+/**
+ * The MECHANICS half of a store: the same three verbs as the `DcbEventStore`
+ * contract, but free to surface infrastructure faults (`E`) on the error
+ * channel. `E` is `never` for a pure engine (in-memory) and e.g. `SqlError` for
+ * a database engine. `append` may additionally fail with the contract's
+ * `AppendConditionFailed`. `makeContractStore` turns this into the contract.
+ */
+export interface RawDcbEventStore<E> {
+    readonly read: (query: Query, options?: ReadOptions) => Effect.Effect<ReadResponse, E>;
+    readonly append: (events: Arr.NonEmptyReadonlyArray<DcbEvent>, condition?: AppendCondition) => Effect.Effect<Position, AppendConditionFailed | E>;
+    readonly subscribe: (query: Query, after?: Position) => Stream.Stream<SequencedEvent, E, Scope.Scope>;
+}
+/**
+ * Wrap a raw engine's mechanics with the shared contract-enforcement policy,
+ * producing a full `DcbEventStore` service value.
+ */
+export declare const makeContractStore: <E>(raw: RawDcbEventStore<E>) => DcbEventStore["Type"];
+//# sourceMappingURL=ContractStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ContractStore.d.ts","sourceRoot":"","sources":["../../src/ContractStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,MAAM,EAAqB,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACrD,OAAO,EAAuB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAA;AAKzD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,CACb,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,WAAW,KAClB,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,CACf,MAAM,EAAE,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAC3C,SAAS,CAAC,EAAE,eAAe,KACxB,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,GAAG,CAAC,CAAC,CAAA;IACvD,QAAQ,CAAC,SAAS,EAAE,CAClB,KAAK,EAAE,KAAK,EACZ,KAAK,CAAC,EAAE,QAAQ,KACb,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;CACnD;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EACjC,KAAK,gBAAgB,CAAC,CAAC,CAAC,KACvB,aAAa,CAAC,MAAM,CA4ErB,CAAA"}

package/dist/dts/DcbEventStore.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The `DcbEventStore` contract: a `Context.Tag` with no bundled implementation.
+ * Consumers supply a `Layer` (the in-memory one lives in this package; each SQL
+ * engine is a package of its own — `@kairos-es/store-postgres` and
+ * `@kairos-es/store-sqlite`).
+ *
+ * Head semantics (ported from `popo.py:62-65`):
+ * - `read` with no `limit`  => `head` = the global last position (ignoring the
+ *   query filter) if the store is non-empty, else `ORIGIN` (0n).
+ * - `read` with a `limit`   => `head` = the last *returned* event's position
+ *   (post-filter, post-limit), or `ORIGIN` if none returned.
+ *
+ * `append` returns the last new position (read-your-writes). `subscribe` is
+ * catch-up then live and requires a `Scope` so the live subscription is cleaned
+ * up on scope close.
+ */
+import type { Array as Arr, Effect, Scope, Stream } from 'effect';
+import { Context } from 'effect';
+import type { AppendCondition } from './AppendCondition.js';
+import type { DcbEvent, Position, ReadLimit, SequencedEvent } from './Event.js';
+import type { AppendConditionFailed } from './errors.js';
+import type { Query } from './Query.js';
+/** Options for a read: a lower position bound and/or a maximum count. */
+export interface ReadOptions {
+    /** Only events strictly after this position (exclusive). Absent = from the start. */
+    readonly after?: Position;
+    /**
+     * Cap the number of events returned (a branded non-negative integer). `0`
+     * returns none; absent = all matching events. A negative/non-integer value is
+     * a defect at the store boundary — see `ReadLimit`.
+     */
+    readonly limit?: ReadLimit;
+}
+/**
+ * The result of a read: a stream of matching events (ascending by position)
+ * plus the consistency `head`.
+ */
+export interface ReadResponse {
+    readonly events: Stream.Stream<SequencedEvent>;
+    readonly head: Position;
+}
+declare const DcbEventStore_base: Context.TagClass<DcbEventStore, "@kairos-es/core/DcbEventStore", {
+    /**
+     * Read events matching `query` (empty query = all), optionally bounded by
+     * `after`/`limit`. See head semantics in the module docs.
+     */
+    readonly read: (query: Query, options?: ReadOptions) => Effect.Effect<ReadResponse>;
+    /**
+     * Append one or more events atomically. If `condition` is given, the append
+     * fails with `AppendConditionFailed` when its query matches any event after
+     * `condition.after`. Returns the last new position.
+     */
+    readonly append: (events: Arr.NonEmptyReadonlyArray<DcbEvent>, condition?: AppendCondition) => Effect.Effect<Position, AppendConditionFailed>;
+    /**
+     * Subscribe to matching events: first the backlog after `after` (catch-up),
+     * then live events as they are appended. Scoped: the live subscription is
+     * released when the scope closes.
+     */
+    readonly subscribe: (query: Query, after?: Position) => Stream.Stream<SequencedEvent, never, Scope.Scope>;
+}>;
+export declare class DcbEventStore extends DcbEventStore_base {
+}
+export {};
+//# sourceMappingURL=DcbEventStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DcbEventStore.d.ts","sourceRoot":"","sources":["../../src/DcbEventStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CACxB;;IAKG;;;OAGG;mBACY,CACb,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE,WAAW,KAClB,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IAEhC;;;;OAIG;qBACc,CACf,MAAM,EAAE,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAC3C,SAAS,CAAC,EAAE,eAAe,KACxB,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IAEnD;;;;OAIG;wBACiB,CAClB,KAAK,EAAE,KAAK,EACZ,KAAK,CAAC,EAAE,QAAQ,KACb,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;;AA9B1D,qBAAa,aAAc,SAAQ,kBAgChC;CAAG"}

package/dist/dts/Event.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Core domain types for the DCB event log: branded scalars and the wire
+ * `DcbEvent`/`SequencedEvent` shapes.
+ *
+ * `data` is opaque bytes at the store layer; the codec (`@kairos-es/codec`) turns typed
+ * payloads into these bytes. Ordering is by `position` alone; `occurredAt` is
+ * producer-supplied domain time and is informational only.
+ */
+import { Schema } 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
+ * `bigint`. `0n` is the "before the first event" sentinel used by `after` and by
+ * an empty store's head.
+ */
+export declare const Position: Schema.brand<Schema.filter<typeof Schema.BigInt>, "Position">;
+export type Position = typeof Position.Type;
+/** The sentinel position meaning "before the first event". */
+export declare const ORIGIN: Position;
+/**
+ * A business identifier attached to an event, following the `key:value`
+ * convention (e.g. `student:s1`). Tags replace the per-stream id of classic
+ * event sourcing; a query matches an event when the event carries all of an
+ * item's tags (superset test).
+ */
+export declare const Tag: Schema.brand<Schema.filter<typeof Schema.String>, "Tag">;
+export type Tag = typeof Tag.Type;
+/**
+ * A reusable tag identity: a `key` plus a `.make(value)` that composes the
+ * branded `Tag` `` `${key}:${value}` `` through core's `Tag` schema. Define an
+ * identity once (`const CourseId = tagIdentity('course')`) and reuse
+ * `CourseId.make(id)` everywhere that entity is tagged. The `key` is exposed for
+ * key-aware tooling (e.g. a tag-vocabulary index, a future retag pass).
+ *
+ * The same constructor authors an event's tags (in a codec `tagsFor` mapper,
+ * ADR-0006) and a query's tags, so the `key:value` string a mapper writes and
+ * the string a query matches are produced by one function and cannot drift. It
+ * lives here beside `Tag` — pure (no clock, no RNG, no effect) — so it is
+ * reachable from every tag-authoring site, including core's own query
+ * constructors.
+ *
+ * `key` and `value` are each a single colon-free atom: the `key:value` grammar
+ * splits on the first colon, so both are validated to be non-empty and contain
+ * no `:` — `key` once at construction, `value` on each `make`. This keeps
+ * composition unambiguous and catches the double-prefix footgun loudly:
+ * `CourseId.make('course:123')` throws rather than silently yielding
+ * `course:course:123`. Raw `Tag.make` remains the escape hatch for a value that
+ * must itself contain a colon.
+ */
+export interface TagIdentity {
+    readonly key: string;
+    readonly make: (value: string) => Tag;
+}
+export declare const tagIdentity: (key: string) => TagIdentity;
+/**
+ * A read cap: a branded non-negative integer bounding how many events a `read`
+ * returns. `0` returns none; an absent limit returns all matching events.
+ *
+ * The bound lives in the type, not merely in prose: a negative or non-integer
+ * limit is a programming error, so it is a DEFECT at the store boundary — the
+ * store validates through this schema and dies rather than surfacing it on the
+ * error channel (`read` keeps `E = never`). Constructed at call sites with
+ * `ReadLimit.make(n)`.
+ */
+export declare const ReadLimit: Schema.brand<Schema.filter<typeof Schema.Int>, "ReadLimit">;
+export type ReadLimit = typeof ReadLimit.Type;
+/**
+ * An event type name, a branded non-empty string. Versioning is by convention
+ * in the name (e.g. `course-registered.v2`); only non-emptiness is enforced.
+ */
+export declare const EventType: Schema.brand<Schema.filter<typeof Schema.String>, "EventType">;
+export type EventType = typeof EventType.Type;
+/**
+ * An event as stored: an opaque payload plus its type, tags, a
+ * producer-supplied `uuid`, and producer-supplied `occurredAt` domain time.
+ *
+ * `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.
+ */
+export declare const DcbEvent: Schema.Struct<{
+    type: Schema.brand<Schema.filter<typeof Schema.String>, "EventType">;
+    data: typeof Schema.Uint8ArrayFromSelf;
+    tags: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "Tag">>;
+    uuid: typeof Schema.UUID;
+    occurredAt: typeof Schema.DateTimeUtc;
+}>;
+export type DcbEvent = typeof DcbEvent.Type;
+/** A persisted event: the event together with the position it was written at. */
+export declare const SequencedEvent: Schema.Struct<{
+    event: Schema.Struct<{
+        type: Schema.brand<Schema.filter<typeof Schema.String>, "EventType">;
+        data: typeof Schema.Uint8ArrayFromSelf;
+        tags: Schema.Array$<Schema.brand<Schema.filter<typeof Schema.String>, "Tag">>;
+        uuid: typeof Schema.UUID;
+        occurredAt: typeof Schema.DateTimeUtc;
+    }>;
+    position: Schema.brand<Schema.filter<typeof Schema.BigInt>, "Position">;
+}>;
+export type SequencedEvent = typeof SequencedEvent.Type;
+//# sourceMappingURL=Event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Event.d.ts","sourceRoot":"","sources":["../../src/Event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,+DAGpB,CAAA;AACD,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,MAAM,EAAE,QAA4B,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,GAAG,0DAGf,CAAA;AACD,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,CAAA;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAA;CACtC;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,WAiBzC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,6DAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,SAAS,gEAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ;;;;;;EAMnB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C,iFAAiF;AACjF,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA"}

package/dist/dts/Projection.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Pure projections and the composition primitive they fold through.
+ *
+ * A `Projection<S>` = `{ initialState, query, evolve }`: a query selecting the
+ * events it cares about and a pure `evolve` folding an already-*decoded* event
+ * into state. Decoding (wire bytes -> typed payload via `Schema`) is not core's
+ * job — it needs `Schema` and a `Serializer`, which core must not depend on —
+ * so `evolve` folds a `DecodedEvent` (the sequenced envelope plus an opaque
+ * `payload`). `composeProjections` merges several projections into one whose
+ * state is a named record.
+ *
+ * There is no builder and no decision-model orchestration here: both are the
+ * decode-aware `@kairos-es/codec` package's job (its `projection(...)` builder
+ * produces schema-backed projections, and its `modelAtHead` performs the effectful
+ * decode then folds through `composeProjections`, which `buildDecisionModel` builds
+ * on). Core keeps only the pure fold primitives.
+ *
+ * `Projection<S>` is *invariant* in `S`, so a heterogeneous record of
+ * projections (different state per key) cannot be bounded by
+ * `Projection<unknown>`. `AnyProjection` is the single authoritative,
+ * state-erased bound that owns that unsoundness in one place (built only via
+ * `AnyProjection.of`), so no downstream package writes `Projection<any>`; the
+ * precise per-key state is recovered by `StateOf` / `CompositeState`.
+ *
+ * The fold itself is pure and Effect-free.
+ */
+import type { SequencedEvent } from './Event.js';
+import type { Query } from './Query.js';
+/**
+ * An already-decoded event handed to a projection's fold: the sequenced wire
+ * envelope (position, type, tags, timings) 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
+ * a projection whose `evolve` narrows `payload` per matched event type.
+ */
+export interface DecodedEvent {
+    readonly sequenced: SequencedEvent;
+    readonly payload: unknown;
+}
+/**
+ * A pure projection: the events it reads (`query`), its starting state, and a
+ * fold step.
+ *
+ * `evolve` contract: a projection is only ever invoked with an event that
+ * matches its `query`. `composeProjections` enforces this — it gates every
+ * sub-projection on its own query before dispatching — so an `evolve` may
+ * assume the event matched and need not re-check `matchesSequenced` itself. (It
+ * still dispatches by the event's type, which selects the fold; that is fold
+ * *selection*, not query gating.) `payload` has already been decoded by the
+ * codec layer.
+ */
+export interface Projection<S> {
+    readonly initialState: S;
+    readonly query: Query;
+    readonly evolve: (state: S, event: DecodedEvent) => S;
+}
+/**
+ * A state-erased view of a `Projection<S>`: the single authoritative bound for
+ * a *heterogeneous* record of projections. `Projection<S>` is invariant in `S`
+ * (S is both a parameter and the result of `evolve`), so `Record<string,
+ * Projection<unknown>>` rejects a record whose keys fold different state types.
+ * Rather than leak `Projection<any>` into every package that holds such a
+ * record, this type hides the invariant `evolve` behind an erased
+ * `(unknown) => unknown` surface and carries `S` only through the covariant
+ * `initialState`, so `Record<string, AnyProjection>` is sound with no `any`
+ * anywhere. Build one only via `AnyProjection.of`; recover the precise per-key
+ * `S` with `StateOf` / `CompositeState`. The `evolve` contract is the same as
+ * `Projection`'s: it is only ever called with an event matching `query`
+ * (`composeProjections` gates first), so an implementation may assume the match.
+ */
+export interface AnyProjection<out S = unknown> {
+    readonly initialState: S;
+    readonly query: Query;
+    readonly evolve: (state: unknown, event: DecodedEvent) => unknown;
+}
+export declare const AnyProjection: {
+    /**
+     * View a typed `Projection<S>` as an opaque `AnyProjection<S>`. This is the
+     * one place the invariant `evolve` is widened to the erased surface, so the
+     * unsoundness of a heterogeneous projection record is discharged here and
+     * nowhere else. `composeProjections` calls `evolve` with each projection's
+     * own state, so the widening is sound at runtime.
+     */
+    readonly of: <S>(projection: Projection<S>) => AnyProjection<S>;
+};
+/** Recover the state type a projection folds to. */
+export type StateOf<P> = P extends AnyProjection<infer S> ? S : never;
+/**
+ * The record of named sub-states a composed projection (or decision model)
+ * folds to: each key's precise state type, recovered from its `AnyProjection`.
+ */
+export type CompositeState<T extends Record<string, AnyProjection>> = {
+    readonly [K in keyof T]: StateOf<T[K]>;
+};
+/**
+ * Compose named projections into one whose state is a record of sub-states and
+ * whose query is the OR-merge of all sub-queries. Each sub-projection only
+ * folds events matching its own query — the guarantee that `Projection.evolve`'s
+ * contract lets sub-projections rely on (so they need not re-gate themselves).
+ *
+ * The fold always writes each *matching* sub-result into a fresh record and
+ * returns it (no `changed` short-circuit, no `evolved !== prev` reference
+ * check): an in-place-mutating fold that returns the same reference would
+ * otherwise be silently dropped. At decision-model scale the extra copy is nil.
+ */
+export declare const composeProjections: <T extends Record<string, AnyProjection>>(projections: T) => Projection<CompositeState<T>>;
+//# sourceMappingURL=Projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.d.ts","sourceRoot":"","sources":["../../src/Projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAWpC;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,YAAY,KAAK,CAAC,CAAA;CACtD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO;IAC5C,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAA;CAClE;AAED,eAAO,MAAM,aAAa;IACxB;;;;;;OAMG;kBACE,CAAC,cAAc,UAAU,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAAC;CAE5C,CAAA;AAEV,oDAAoD;AACpD,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAErE;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI;IACpE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACvC,CAAA;AAUD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EACxE,aAAa,CAAC,KACb,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAkC9B,CAAA"}