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

package/dist/dts-cjs/Event.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ * Encoded, a position is a decimal string (JSON-safe, `String(b)`); decoded, a
+ * `bigint`. `0n` is the "before the first event" sentinel used by `after` and by
+ * an empty store's head.
+ *
+ * The string-to-`bigint` step is hand-built rather than Effect 4's
+ * `Schema.BigIntFromString`, because that schema accepts only `^-?\d+$` and so
+ * refuses inputs the encoded side has always admitted — `" 5"`, `"+5"`,
+ * `"0x10"`. The decode here is the global `BigInt(s)` behind a blank-string
+ * refusal, which is `BigInt.fromString` and is exactly what Effect 3's
+ * `Schema.BigInt` ran, so a position string any earlier release decoded still
+ * decodes to the same value. The non-negative check then runs on the `bigint`,
+ * as it always did.
+ */
+export declare const Position: Schema.brand<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>, "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.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.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.String, "EventType">;
+export type EventType = typeof EventType.Type;
+/**
+ * An event's metadata: a flat bag of strings carrying the circumstances under
+ * which the event was RECORDED, never anything the business asserts (ADR-0017).
+ * Payload is what happened; metadata is the context of the recording — a
+ * `traceparent`, a correlation or causation id, a deployment revision.
+ *
+ * Values are strings, not `unknown`, for cross-engine parity rather than taste:
+ * both SQL engines carry the bag as a JSON document, and `JSON.stringify` drops
+ * `undefined`, throws on `bigint` and turns `NaN` into `null`, none of which the
+ * in-memory oracle does.
+ *
+ * The key schema carries no refinement, deliberately: a refinement on a
+ * `Schema.Record` key acts as a FILTER on decode, silently dropping a key that
+ * fails it rather than failing the decode. Constraining keys, if ever wanted,
+ * has to be a validating step of its own.
+ *
+ * Two engine limits a consumer must know, because the bag is typically filled
+ * from outside the application at a request edge. Postgres refuses a NUL
+ * character (U+0000) and an unpaired surrogate in any string it stores, so an
+ * event whose bag holds one fails to append there while the in-memory and
+ * SQLite engines accept it; sanitise untrusted values before they reach the
+ * bag. And key ORDER is not preserved: Postgres stores an object's keys in an
+ * order of its own, so compare bags as unordered and never rely on the order
+ * `Object.keys` returns.
+ *
+ * Metadata is never part of a `Query` or an `AppendCondition` — a store refuses
+ * either when it carries a key the grammar does not define, so a metadata
+ * predicate cannot be written and silently ignored — never reaches a codec's
+ * `tagsFor`, and no store offers a way to rewrite it once appended. ADR-0017
+ * owns why each of those is mechanical rather than preferential.
+ *
+ * ## The one home of the shape rule
+ *
+ * The bag is a JSON OBJECT whose every value is a STRING, and this schema is
+ * where that rule is stated. At runtime it is checked in ONE place, at write: the
+ * codec's `toEvent` decodes every bag through this schema and refuses one that
+ * fails on its own error channel, so a value smuggled past the type (through an
+ * `any`) stops there. The schema judges a bag's OWN enumerable keys, so an object
+ * that keeps its entries anywhere else — a `Map`, a `Date` — reads as the empty
+ * bag rather than failing. A store checks no values: an event built by hand and handed
+ * to `append` directly carries whatever it carries, and what each engine then does
+ * with a non-string value differs — one may store it and read it back differently
+ * from another, and a `bigint` makes a SQL engine's append fail. Each
+ * SQL engine keeps a container check of its own on read — the column must hold a
+ * JSON object — because that defends against a writer outside the library and is
+ * about the column, not the values. A VALUE check must never be added on read
+ * alone: it would make an event the store accepted unreadable for ever, so a
+ * value check belongs at write or nowhere.
+ */
+export declare const Metadata: Schema.$Record<Schema.String, Schema.String>;
+export type Metadata = typeof Metadata.Type;
+/**
+ * An event as stored: an opaque payload plus its type, tags, a
+ * producer-supplied `uuid`, producer-supplied `occurredAt` domain time, and its
+ * `metadata` bag.
+ *
+ * `data` is `Uint8Array` (opaque bytes); the store does not interpret it.
+ * `uuid` is producer-supplied to keep `core` deterministic (no RNG in core).
+ * It is checked for UUID SHAPE only (`isGUID`), not for a version nibble: a
+ * stricter check would refuse ids an existing log already holds.
+ * `occurredAt` is informational only; ordering is by position alone.
+ * `metadata` mirrors `tags` rather than `data`: REQUIRED, with an empty bag
+ * legal. Required because an absent-versus-empty divergence between engines is
+ * invisible to `toEqual`, which ignores `undefined` properties, so an optional
+ * field could drift across the three engines with the round-trip suite green.
+ * Core only carries it; the codec's `toEvent` is where it is resolved.
+ */
+export declare const DcbEvent: Schema.Struct<{
+    readonly type: Schema.brand<Schema.String, "EventType">;
+    readonly data: Schema.Uint8Array;
+    readonly tags: Schema.$Array<Schema.brand<Schema.String, "Tag">>;
+    readonly uuid: Schema.String;
+    readonly occurredAt: Schema.DateTimeUtcFromString;
+    readonly metadata: Schema.$Record<Schema.String, Schema.String>;
+}>;
+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<{
+    readonly event: Schema.Struct<{
+        readonly type: Schema.brand<Schema.String, "EventType">;
+        readonly data: Schema.Uint8Array;
+        readonly tags: Schema.$Array<Schema.brand<Schema.String, "Tag">>;
+        readonly uuid: Schema.String;
+        readonly occurredAt: Schema.DateTimeUtcFromString;
+        readonly metadata: Schema.$Record<Schema.String, Schema.String>;
+    }>;
+    readonly position: Schema.brand<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>, "Position">;
+}>;
+export type SequencedEvent = typeof SequencedEvent.Type;
+//# sourceMappingURL=Event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Event.d.ts","sourceRoot":"","sources":["../../src/Event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAIL,MAAM,EAGP,MAAM,QAAQ,CAAA;AAEf;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ,uFAuBpB,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,oCAGf,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,uCAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,SAAS,0CAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,QAAQ,8CAA8C,CAAA;AACnE,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ;;;;;;;EAOnB,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 → dts-cjs}/Projection.d.ts

@@ -28,7 +28,7 @@ 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`.
+ * envelope (position, type, tags, timings, metadata) plus the decoded `payload`.
  *
  * Core does not decode — it only folds events another layer has already decoded
  * — so `payload` is `unknown` at this layer. `@kairos-es/codec`'s builder emits

package/dist/{dts → dts-cjs}/Projection.d.ts.map

@@ -1 +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;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,CAAC,KAAK,CAAC,KAAG,KAGT,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EACxE,aAAa,CAAC,KACb,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CA0B9B,CAAA"}
+{"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;AAqBD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,CAAC,KAAK,CAAC,KAAG,KAGT,CAAA;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,EACxE,aAAa,CAAC,KACb,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CA0B9B,CAAA"}

package/dist/{dts → dts-cjs}/Query.d.ts

@@ -29,15 +29,15 @@ import { type DcbEvent, EventType, type SequencedEvent, Tag } from './Event.js';
  * (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">>;
+    readonly types: Schema.$Array<Schema.brand<Schema.String, "EventType">>;
+    readonly tags: Schema.$Array<Schema.brand<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">>;
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly types: Schema.$Array<Schema.brand<Schema.String, "EventType">>;
+        readonly tags: Schema.$Array<Schema.brand<Schema.String, "Tag">>;
     }>>;
 }>;
 export type Query = typeof Query.Type;
@@ -61,6 +61,9 @@ export declare const matchesSequenced: (sequenced: SequencedEvent, query: Query)
  * (`Query.ts` module docs) but which plain-data assembly — e.g. decision-model
  * composition, `Projection.ts:31-36` — can still bypass.
  *
+ * A query, or any of its items, carrying a key the grammar does not define is
+ * refused before anything else is judged (`unknownKeyFault` below says why).
+ *
  * The servable grammar is exactly one of:
  * - the wildcard (`items.length === 0`), which matches every event;
  * - a *single* item (`items.length === 1`), any types/tags, including a
@@ -81,6 +84,17 @@ export declare const matchesSequenced: (sequenced: SequencedEvent, query: Query)
  * engine" behaviour.
  */
 export declare const assertServableQuery: (query: Query) => void;
+/**
+ * The unknown-key half of `servableQueryFault`, on its own: the refusal of a key the
+ * grammar does not define on the envelope or on any item, or `undefined`.
+ *
+ * It is the same rule and not a second statement of it — `servableQueryFault` calls
+ * this first. It is exported because ONE caller has to tell the two halves apart:
+ * the codec's read ledger refuses an unservable SHAPE on its own error channel, and
+ * must not report an unknown key as one. An unknown key is not something a slice's
+ * tags can fix, so the ledger leaves it to the store, which refuses it as a defect.
+ */
+export declare const unknownQueryKeyFault: (query: Query) => string | undefined;
 /**
  * The servable grammar as a TOTAL function: the reason `query` cannot be served,
  * or `undefined` when it can.

package/dist/dts-cjs/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,KAAK,KAAG,IAKlD,CAAA;AAkDD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,KAAK,KAAG,MAAM,GAAG,SAM1D,CAAA;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,KAAK,KAAG,MAAM,GAAG,SAsB1D,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 → dts-cjs}/SubscribeMachine.d.ts

@@ -108,12 +108,12 @@ export declare const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
  * the key NAME, the VALIDATION and the DEFAULT from one place, so a caller who has
  * tuned one engine's subscribe reads another's without translating, and the two
  * cannot drift in what they ACCEPT any more than in what they assume. Two engines
- * hand-authoring the identical `Schema.optionalWith(…)` twice were identical only
+ * hand-authoring the identical `Schema.optionalKey(…)` twice were identical only
  * by inspection.
  *
  * The bounds differ between the two because the quantities do. `pollInterval` is a
- * duration, so a fraction of a millisecond is meaningful and only `positive` and
- * `finite` matter: at zero or below the loop would spin without ever waiting for a
+ * duration, so a fraction of a millisecond is meaningful and only `isGreaterThan(0)`
+ * and `isFinite` matter: at zero or below the loop would spin without ever waiting for a
  * wake, and at `Infinity` the periodic re-read — the half that carries delivery —
  * would never come, which silently converts the wake source from an optimisation
  * into the guarantee. `catchUpPageSize` is a COUNT, so it must be an integer
@@ -121,17 +121,13 @@ export declare const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
  * length against it to decide the tail is drained, and a page of zero would report
  * "drained" forever without reading anything.
  *
- * `exact: true` on both keeps the decoded type at `key?: T` rather than
+ * `optionalKey` on both keeps the decoded type at `key?: T` rather than
  * `T | undefined`, matching the repo's `exactOptionalPropertyTypes` discipline — an
  * absent key, never an explicit `undefined`.
  */
 export 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;
-    }>;
+    readonly pollInterval: Schema.optionalKey<Schema.Number>;
+    readonly catchUpPageSize: Schema.optionalKey<Schema.Int>;
 };
 /**
  * The two seams the subscribe machine runs over, plus the two tuning knobs. `E` is
@@ -140,7 +136,7 @@ export declare const subscriptionTuningFields: {
  *
  * ONE type parameter and not two, deliberately: a wake source with an error type of
  * its own is `Stream.orDie`d by the caller, yielding a `Stream<unknown, never>`
- * that is assignable here under Effect v3's covariant error channel. A second
+ * that is assignable here under Effect's covariant error channel. A second
  * parameter would buy nothing and would have to be spelled at every call site. Nor
  * is there an `R`: neither seam contributes a requirement, and unused generality is
  * not free.
@@ -169,10 +165,10 @@ export interface SubscriptionDeps<E> {
 }
 /**
  * Build the subscription `Stream`: catch up from `after`, then track the live tail.
- * The cursor threads through the `unfoldChunkEffect` unfold state, starting at
- * `after` and advancing to the last delivered position each batch; the stream never
- * completes on its own (always `Option.some`), so the enclosing scope interrupts it
- * on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
+ * The cursor threads through the `Stream.paginate` state, starting at `after` and
+ * advancing to the last delivered position each batch; the stream never completes
+ * on its own (the next state is always `Option.some`), so the enclosing scope
+ * interrupts it on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
  * (subscribe is `E = never` on the contract).
  */
 export declare const subscribeStream: <E>(deps: SubscriptionDeps<E>, after: Position | undefined) => Stream.Stream<SequencedEvent, E, Scope.Scope>;

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

@@ -0,0 +1 @@
+{"version":3,"file":"SubscribeMachine.d.ts","sourceRoot":"","sources":["../../src/SubscribeMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EACL,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;;;CAO3B,CAAA;AAiBV;;;;;;;;;;;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,CA+G5C,CAAA"}

package/dist/{dts → dts-cjs}/inMemory.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"inMemory.d.ts","sourceRoot":"","sources":["../../src/inMemory.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAY,MAAM,EAAE,KAAK,EAAkC,MAAM,QAAQ,CAAA;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAuL/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;AAuID,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 → dts-cjs}/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @kairos-es/core: DCB-first event-sourcing contract and in-memory store for
- * Effect v3.
+ * Effect.
  *
  * Exposes the domain types (`DcbEvent`, `SequencedEvent`, `Position`, `Tag`,
  * `EventType`), the selection language (`Query`, `QueryItem`, the pure match

package/dist/dts-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/{dts → dts-cjs}/retryOnConflict.d.ts

@@ -35,12 +35,6 @@
  * 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';
@@ -66,5 +60,5 @@ import type { AppendConditionFailed } from './errors.js';
  * 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>;
+export declare const retryOnConflict: <A, E, R>(command: Effect.Effect<A, AppendConditionFailed | E, R>, schedule?: Schedule.Schedule<unknown, AppendConditionFailed | E, never, R>) => Effect.Effect<A, AppendConditionFailed | E, R>;
 //# sourceMappingURL=retryOnConflict.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retryOnConflict.d.ts","sourceRoot":"","sources":["../../src/retryOnConflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,KAAK,EACL,CAAC,CACgB,KAClB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,EAAE,CAAC,CAI5C,CAAA"}

package/dist/{dts → dts-cjs}/testing.d.ts

@@ -20,7 +20,7 @@ import { DateTime } from 'effect';
  *
  * 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
+ * stable across runs. Built via `DateTime.makeUnsafe(0)` (the value is a
  * compile-time constant, not read from the host clock).
  */
 export declare const EPOCH: DateTime.Utc;

package/dist/dts-esm/AppendCondition.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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<{
+    readonly failIfEventsMatch: Schema.Struct<{
+        readonly items: Schema.$Array<Schema.Struct<{
+            readonly types: Schema.$Array<Schema.brand<Schema.String, "EventType">>;
+            readonly tags: Schema.$Array<Schema.brand<Schema.String, "Tag">>;
+        }>>;
+    }>;
+    readonly after: Schema.optionalKey<Schema.brand<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>, "Position">>;
+}>;
+export type AppendCondition = typeof AppendCondition.Type;
+//# sourceMappingURL=AppendCondition.d.ts.map

package/dist/dts-esm/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-esm/AppendIsOwned.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `AppendIsOwned` — the marker saying *"an append is already owned here"*, and the
+ * check that refuses a second one.
+ *
+ * ## Why a write-side concept core does not need for its own job lives in core
+ *
+ * A bracket that derives one `AppendCondition` from every read its body performed
+ * (`@kairos-es/codec`'s `transact`) owns exactly one append: the one it issues at
+ * close, under that derived condition. Any OTHER append inside that body is a
+ * wiring mistake, and the dangerous case is not the one that looks dangerous. A
+ * command runner appending mid-body usually writes into the very slice the body
+ * read, so its events match the union the bracket is about to guard on — and the
+ * bracket's own closing append is then refused by a condition its own body
+ * invalidated. The failure arrives at the wrong line, describing a conflict that
+ * was self-inflicted.
+ *
+ * The refusal therefore has to catch a RAW `store.append` and not merely a nested
+ * bracket, which is what puts it here rather than in the codec. Enforcing it one
+ * layer up would catch a nested bracket and a command runner and miss a direct
+ * store call — and a syntactic lint rule cannot close that gap either, having no
+ * call graph, so an append one function away in a helper is invisible to both.
+ * `makeContractStore` is the one seam every engine's append already passes
+ * through, so the check is written once and inherited whole, exactly as
+ * `assertServableQuery` is.
+ *
+ * The cost is real and is accepted: core learns a concept it does not need for its
+ * own job. It is affordable because core already owns the write contract, and
+ * *"an append is already owned"* is a write-side fact about that contract rather
+ * than a fact about the codec.
+ *
+ * ## Present means refused, so a sanctioned append REMOVES the marker
+ *
+ * The check reads the service through `Effect.serviceOption`, so its ABSENCE is the
+ * normal case and costs the `append` signature nothing — `DcbEventStore.append`
+ * keeps `R = never` and no caller provides anything. Presence is what refuses.
+ *
+ * That shape decides how the two legitimate appends inside a bracket get through,
+ * and there is only one route: run with the marker STRIPPED from the context
+ * (`Effect.updateContext` over `Context.omit(AppendIsOwned)`). The bracket's own
+ * closing append is issued outside the scope it provided the marker in, and the
+ * codec's escape hatch strips it explicitly. Neither needs a second service, a
+ * sanctioning flag or a mutable cell, and there is no way to be exempt by
+ * accident: an append is either lexically outside the marked region or it says in
+ * as many words that it is removing the marker.
+ */
+import { Context, Effect } from 'effect';
+declare const AppendIsOwned_base: Context.ServiceClass<AppendIsOwned, "@kairos-es/core/AppendIsOwned", {
+    readonly by: string;
+}>;
+/**
+ * Marks that an append is already owned by an enclosing bracket, and names what
+ * owns it.
+ *
+ * `by` is a human-readable owner name and exists for the defect message alone —
+ * the refusal is decided by the service's PRESENCE, never by this value, so nothing
+ * branches on it and no caller need agree on a vocabulary for it.
+ */
+export declare class AppendIsOwned extends AppendIsOwned_base {
+}
+/**
+ * Die if an append is already owned here; do nothing otherwise.
+ *
+ * A DEFECT and not an error-channel value, deliberately. There is no
+ * data-dependent recovery from it: the events this append would have written
+ * belong to a bracket that is going to write its own, so no caller could sensibly
+ * catch it and carry on. It is the same class of fault as a non-servable query,
+ * and it is refused in the same place and in the same way. The remedy is one
+ * identifier away in every case — the codec's `decideOnly` for a command runner,
+ * its escape hatch for a deliberate second append — which is what makes a defect
+ * affordable here.
+ *
+ * `Effect.serviceOption` is what keeps this free: it reads the service if present and
+ * adds NOTHING to the requirement channel, so every existing append is unchanged
+ * and unprovisioned.
+ */
+export declare const assertAppendNotOwned: Effect.Effect<void>;
+export {};
+//# sourceMappingURL=AppendIsOwned.d.ts.map

package/dist/dts-esm/AppendIsOwned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppendIsOwned.d.ts","sourceRoot":"","sources":["../../src/AppendIsOwned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;;iBAYvB,MAAM;;AAVvB;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,kBAGC;CAAG;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAepD,CAAA"}

package/dist/dts-esm/ContractStore.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `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` (Effect 3's `catchAll`, which Effect 4
+ * names `catch`):
+ *
+ * - `assertServableQuery` at every verb's entry (read, the append condition's
+ *   guard query, subscribe) — a non-servable query, or one carrying a key the
+ *   grammar does not define, is a DEFECT in every engine, and an append condition
+ *   carrying a key `AppendCondition` does not define is refused alongside it;
+ * - `ReadLimit` decode on `read`'s `limit` — a negative/non-integer limit is a
+ *   DEFECT (so `read` keeps `E = never`), validated through the branded schema
+ *   even at an untyped boundary that reaches the store as `unknown`;
+ * - `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;
+ * - `assertAppendNotOwned` on append — an append inside a bracket that already
+ *   owns one is a DEFECT. Read `AppendIsOwned.ts` for the rule and for why a
+ *   write-side concept core does not need for its own job is enforced here.
+ *
+ * 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 { 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["Service"];
+//# sourceMappingURL=ContractStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ContractStore.d.ts","sourceRoot":"","sources":["../../src/ContractStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;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,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD,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,SAAS,CAoGxB,CAAA"}

package/dist/dts-esm/DcbEventStore.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The `DcbEventStore` contract: a `Context.Service` 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.ServiceClass<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-esm/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,kBAgCC;CAAG"}