@kairos-es/core 0.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neverbland
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,33 @@
+# @kairos-es/core
+
+DCB-first event-sourcing contract and in-memory store for Effect v3.
+
+Provides the `DcbEventStore` contract (branded `Position` / `Tag` / `EventType`,
+the `DcbEvent` / `Query` / `AppendCondition` schemas, the errors and the
+`Context.Tag`), the pure `Projection` / `composeProjections` fold primitives, and
+the in-memory `Layer` — the canonical, readable form of the check-then-append
+algorithm. Decoding is deliberately not core's job, because it needs `Schema` and
+a `Serializer`: the event-def builder, the slice builder and `buildDecisionModel`
+live in `@kairos-es/codec`.
+
+`retryOnConflict(command, schedule?)` is here too, because it is the recovery
+half of the append condition: `AppendConditionFailed` carries no conflicting
+position, so the only correct retry re-runs the whole read-decide-append cycle
+and lets a fresh read re-derive the condition. It retries only on that tag — a
+domain rejection escapes unretried — under a bounded jittered backoff, and it
+takes nothing core did not already have (the error is core's, `Schedule` is
+`effect`'s). See
+[ADR-0008](../../docs/adr/0008-retry-on-append-condition-failed-decider-level-combinator.md).
+
+The main entry also carries the surface an ENGINE author builds against, which is a
+real surface rather than an internal one: `makeContractStore` / `RawDcbEventStore`,
+the shared `subscribe` wake/poll/dedup machine every engine's `subscribe` is built
+from and the two tuning constants and config fields that go with it
+([ADR-0009](../../docs/adr/0009-subscribe-machine-in-core-ascending-commit-order-precondition.md)),
+and `classifyServableQuery` beside the `assertServableQuery` defining the grammar it
+dispatches over. `SubscribeMachine.ts` states the one obligation an engine using it
+inherits.
+
+Platform-neutral (no `node:*` imports); `effect` is the only peer dependency.
+`@kairos-es/core/testing` is a published subpath carrying the deterministic
+`EPOCH` domain time and counter-based uuid support every suite shares.

package/dist/cjs/AppendCondition.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AppendCondition = void 0;
+var _effect = require("effect");
+var _Event = require("./Event.js");
+var _Query = require("./Query.js");
+/**
+ * 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".
+ */
+
+const AppendCondition = exports.AppendCondition = /*#__PURE__*/_effect.Schema.Struct({
+  failIfEventsMatch: _Query.Query,
+  after: /*#__PURE__*/_effect.Schema.optionalWith(_Event.Position, {
+    exact: true
+  })
+});
+//# sourceMappingURL=AppendCondition.js.map

package/dist/cjs/AppendCondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppendCondition.js","names":["_effect","require","_Event","_Query","AppendCondition","exports","Schema","Struct","failIfEventsMatch","Query","after","optionalWith","Position","exact"],"sources":["../../src/AppendCondition.ts"],"sourcesContent":[null],"mappings":";;;;;;AASA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,MAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAXA;;;;;;;;;;AAaO,MAAMG,eAAe,GAAAC,OAAA,CAAAD,eAAA,gBAAGE,cAAM,CAACC,MAAM,CAAC;EAC3CC,iBAAiB,EAAEC,YAAK;EACxBC,KAAK,eAAEJ,cAAM,CAACK,YAAY,CAACC,eAAQ,EAAE;IAAEC,KAAK,EAAE;EAAI,CAAE;CACrD,CAAC","ignoreList":[]}

package/dist/cjs/ContractStore.js

@@ -0,0 +1,80 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.makeContractStore = void 0;
+var _effect = require("effect");
+var _Event = require("./Event.js");
+var _Query = require("./Query.js");
+/** Decode an unknown limit through `ReadLimit`, dying on a defect-worthy value. */
+const decodeReadLimit = /*#__PURE__*/_effect.Schema.decodeUnknownSync(_Event.ReadLimit);
+/**
+ * Wrap a raw engine's mechanics with the shared contract-enforcement policy,
+ * producing a full `DcbEventStore` service value.
+ */
+const makeContractStore = raw => ({
+  read: (query, options) => _effect.Effect.suspend(() => {
+    // Defects (surface when the Effect runs), keeping `read` at `E = never`.
+    (0, _Query.assertServableQuery)(query);
+    if (options?.limit !== undefined) {
+      decodeReadLimit(options.limit);
+    }
+    // Infrastructure faults are defects, not contract values.
+    return _effect.Effect.orDie(raw.read(query, options));
+  }),
+  append: (events, condition) => _effect.Effect.suspend(() => {
+    // An EMPTY batch is a plain-data caller bypassing the
+    // `NonEmptyReadonlyArray` type: there is nothing to append. The engines
+    // diverge on it at an unchecked boundary — Postgres inserts zero rows and
+    // its conditional function returns zero rows, indistinguishable from a
+    // conflict, so it surfaces a PHANTOM `AppendConditionFailed`, whereas
+    // in-memory silently returns the previous head (`start - 1n`). Make it a
+    // DEFECT here, at the one choke point, so the policy is definitionally
+    // identical across engines and zero-rows stays an unambiguous conflict
+    // signal (a throw inside the suspend becomes a defect, like
+    // `assertServableQuery`).
+    if (events.length === 0) {
+      throw new Error('makeContractStore.append: the events batch is empty; append requires ' + 'at least one event (a NonEmptyReadonlyArray). An empty batch is a ' + 'plain-data caller bypassing the type — a defect, not a conflict.');
+    }
+    // A non-servable guard query is a defect in every engine.
+    if (condition !== undefined) {
+      (0, _Query.assertServableQuery)(condition.failIfEventsMatch);
+    }
+    // Only `AppendConditionFailed` belongs on the contract error channel;
+    // every other fault (a `SqlError`, a `55P03` lock-timeout abort, …) is
+    // infrastructure and surfaces OFF the shared contract as a defect.
+    //
+    // Classified by `_tag`, NEVER by `instanceof`, and this is the site where
+    // that matters most: it is the ONE gate every backend's conflicts pass
+    // through, so a class-identity check here is a single point of silent
+    // failure for the whole write side. `@kairos-es/core` ships dual ESM/CJS,
+    // so a consumer's graph can hold two distinct `AppendConditionFailed`
+    // classes for one error — an engine wired against one copy of core and
+    // wrapped by a `makeContractStore` from another. Under `instanceof` that
+    // engine's GENUINE conflicts fail the class check and are `Effect.die`d
+    // as infrastructure, which does not merely mislabel them: it takes the
+    // conflict OFF the error channel, where `retryOnConflict` (which already
+    // matches on the tag, and correctly) can never see it to retry. The tag
+    // is the error's identity across realms; `retryOnConflict.ts` makes the
+    // argument at length and this is its other end.
+    //
+    // `Predicate.isTagged` is total over `unknown` — an object check, then
+    // `_tag` equality — so a `null`, a string or a raw `SqlError` on the
+    // engine's channel simply answers false and dies as it should. It also
+    // narrows the raw `AppendConditionFailed | E` to the contract's single
+    // error, which is what keeps `append` at `E = AppendConditionFailed`.
+    return _effect.Effect.catchAll(raw.append(events, condition), error => _effect.Predicate.isTagged('AppendConditionFailed')(error) ? _effect.Effect.fail(error) : _effect.Effect.die(error));
+  }),
+  subscribe: (query, after) =>
+  // `Effect.sync` runs when the stream is executed; a throw from
+  // `assertServableQuery` becomes a stream defect (identical rule to
+  // read/append). Infrastructure faults on the live tail die (subscribe is
+  // `E = never`).
+  _effect.Stream.unwrap(_effect.Effect.sync(() => {
+    (0, _Query.assertServableQuery)(query);
+    return _effect.Stream.orDie(raw.subscribe(query, after));
+  }))
+});
+exports.makeContractStore = makeContractStore;
+//# sourceMappingURL=ContractStore.js.map

package/dist/cjs/ContractStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractStore.js","names":["_effect","require","_Event","_Query","decodeReadLimit","Schema","decodeUnknownSync","ReadLimit","makeContractStore","raw","read","query","options","Effect","suspend","assertServableQuery","limit","undefined","orDie","append","events","condition","length","Error","failIfEventsMatch","catchAll","error","Predicate","isTagged","fail","die","subscribe","after","Stream","unwrap","sync","exports"],"sources":["../../src/ContractStore.ts"],"sourcesContent":[null],"mappings":";;;;;;AAgCA,IAAAA,OAAA,GAAAC,OAAA;AAIA,IAAAC,MAAA,GAAAD,OAAA;AAEA,IAAAE,MAAA,GAAAF,OAAA;AAEA;AACA,MAAMG,eAAe,gBAAGC,cAAM,CAACC,iBAAiB,CAACC,gBAAS,CAAC;AAwB3D;;;;AAIO,MAAMC,iBAAiB,GAC5BC,GAAwB,KACG;EAC3BC,IAAI,EAAEA,CAACC,KAAK,EAAEC,OAAO,KACnBC,cAAM,CAACC,OAAO,CAAC,MAAK;IAClB;IACA,IAAAC,0BAAmB,EAACJ,KAAK,CAAC;IAC1B,IAAIC,OAAO,EAAEI,KAAK,KAAKC,SAAS,EAAE;MAChCb,eAAe,CAACQ,OAAO,CAACI,KAAK,CAAC;IAChC;IACA;IACA,OAAOH,cAAM,CAACK,KAAK,CAACT,GAAG,CAACC,IAAI,CAACC,KAAK,EAAEC,OAAO,CAAC,CAAC;EAC/C,CAAC,CAAC;EAEJO,MAAM,EAAEA,CAACC,MAAM,EAAEC,SAAS,KACxBR,cAAM,CAACC,OAAO,CAAC,MAAK;IAClB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,IAAIM,MAAM,CAACE,MAAM,KAAK,CAAC,EAAE;MACvB,MAAM,IAAIC,KAAK,CACb,uEAAuE,GACrE,oEAAoE,GACpE,kEAAkE,CACrE;IACH;IACA;IACA,IAAIF,SAAS,KAAKJ,SAAS,EAAE;MAC3B,IAAAF,0BAAmB,EAACM,SAAS,CAACG,iBAAiB,CAAC;IAClD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,OAAOX,cAAM,CAACY,QAAQ,CAAChB,GAAG,CAACU,MAAM,CAACC,MAAM,EAAEC,SAAS,CAAC,EAAGK,KAAK,IAC1DC,iBAAS,CAACC,QAAQ,CAAC,uBAAuB,CAAC,CAACF,KAAK,CAAC,GAC9Cb,cAAM,CAACgB,IAAI,CAACH,KAAK,CAAC,GAClBb,cAAM,CAACiB,GAAG,CAACJ,KAAK,CAAC,CACtB;EACH,CAAC,CAAC;EAEJK,SAAS,EAAEA,CAACpB,KAAK,EAAEqB,KAAK;EACtB;EACA;EACA;EACA;EACAC,cAAM,CAACC,MAAM,CACXrB,cAAM,CAACsB,IAAI,CAAC,MAAK;IACf,IAAApB,0BAAmB,EAACJ,KAAK,CAAC;IAC1B,OAAOsB,cAAM,CAACf,KAAK,CAACT,GAAG,CAACsB,SAAS,CAACpB,KAAK,EAAEqB,KAAK,CAAC,CAAC;EAClD,CAAC,CAAC;CAEP,CAAC;AAAAI,OAAA,CAAA5B,iBAAA,GAAAA,iBAAA","ignoreList":[]}

package/dist/cjs/DcbEventStore.js

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DcbEventStore = void 0;
+var _effect = require("effect");
+class DcbEventStore extends /*#__PURE__*/_effect.Context.Tag('@kairos-es/core/DcbEventStore')() {}
+exports.DcbEventStore = DcbEventStore;
+//# sourceMappingURL=DcbEventStore.js.map

package/dist/cjs/DcbEventStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DcbEventStore.js","names":["_effect","require","DcbEventStore","Context","Tag","exports"],"sources":["../../src/DcbEventStore.ts"],"sourcesContent":[null],"mappings":";;;;;;AAiBA,IAAAA,OAAA,GAAAC,OAAA;AA2BM,MAAOC,aAAc,sBAAQC,eAAO,CAACC,GAAG,CAAC,+BAA+B,CAAC,EAgC5E;AAAAC,OAAA,CAAAH,aAAA,GAAAA,aAAA","ignoreList":[]}

package/dist/cjs/Event.js

@@ -0,0 +1,89 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.tagIdentity = exports.Tag = exports.SequencedEvent = exports.ReadLimit = exports.Position = exports.ORIGIN = exports.EventType = exports.DcbEvent = void 0;
+var _effect = require("effect");
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+const Position = exports.Position = /*#__PURE__*/_effect.Schema.BigInt.pipe(/*#__PURE__*/_effect.Schema.nonNegativeBigInt(), /*#__PURE__*/_effect.Schema.brand('Position'));
+/** The sentinel position meaning "before the first event". */
+const ORIGIN = exports.ORIGIN = /*#__PURE__*/Position.make(0n);
+/**
+ * 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).
+ */
+const Tag = exports.Tag = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.pattern(/^[^:]+:.+/, {
+  identifier: 'Tag'
+}), /*#__PURE__*/_effect.Schema.brand('Tag'));
+const tagIdentity = key => {
+  if (key.length === 0 || key.includes(':')) {
+    throw new Error(`tagIdentity: key must be non-empty and contain no ':' (got ${JSON.stringify(key)})`);
+  }
+  return {
+    key,
+    make: value => {
+      if (value.length === 0 || value.includes(':')) {
+        throw new Error(`tagIdentity(${JSON.stringify(key)}).make: value must be non-empty and contain no ':' (got ${JSON.stringify(value)})`);
+      }
+      return Tag.make(`${key}:${value}`);
+    }
+  };
+};
+/**
+ * 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)`.
+ */
+exports.tagIdentity = tagIdentity;
+const ReadLimit = exports.ReadLimit = /*#__PURE__*/_effect.Schema.Int.pipe(/*#__PURE__*/_effect.Schema.greaterThanOrEqualTo(0), /*#__PURE__*/_effect.Schema.brand('ReadLimit'));
+/**
+ * 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.
+ */
+const EventType = exports.EventType = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.nonEmptyString(), /*#__PURE__*/_effect.Schema.brand('EventType'));
+/**
+ * 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.
+ */
+const DcbEvent = exports.DcbEvent = /*#__PURE__*/_effect.Schema.Struct({
+  type: EventType,
+  data: _effect.Schema.Uint8ArrayFromSelf,
+  tags: /*#__PURE__*/_effect.Schema.Array(Tag),
+  uuid: _effect.Schema.UUID,
+  occurredAt: _effect.Schema.DateTimeUtc
+});
+/** A persisted event: the event together with the position it was written at. */
+const SequencedEvent = exports.SequencedEvent = /*#__PURE__*/_effect.Schema.Struct({
+  event: DcbEvent,
+  position: Position
+});
+//# sourceMappingURL=Event.js.map

package/dist/cjs/Event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Event.js","names":["_effect","require","Position","exports","Schema","BigInt","pipe","nonNegativeBigInt","brand","ORIGIN","make","Tag","String","pattern","identifier","tagIdentity","key","length","includes","Error","JSON","stringify","value","ReadLimit","Int","greaterThanOrEqualTo","EventType","nonEmptyString","DcbEvent","Struct","type","data","Uint8ArrayFromSelf","tags","Array","uuid","UUID","occurredAt","DateTimeUtc","SequencedEvent","event","position"],"sources":["../../src/Event.ts"],"sourcesContent":[null],"mappings":";;;;;;AAQA,IAAAA,OAAA,GAAAC,OAAA;AARA;;;;;;;;;AAUA;;;;;;;;;AASO,MAAMC,QAAQ,GAAAC,OAAA,CAAAD,QAAA,gBAAGE,cAAM,CAACC,MAAM,CAACC,IAAI,cACxCF,cAAM,CAACG,iBAAiB,EAAE,eAC1BH,cAAM,CAACI,KAAK,CAAC,UAAU,CAAC,CACzB;AAGD;AACO,MAAMC,MAAM,GAAAN,OAAA,CAAAM,MAAA,gBAAaP,QAAQ,CAACQ,IAAI,CAAC,EAAE,CAAC;AAEjD;;;;;;AAMO,MAAMC,GAAG,GAAAR,OAAA,CAAAQ,GAAA,gBAAGP,cAAM,CAACQ,MAAM,CAACN,IAAI,cACnCF,cAAM,CAACS,OAAO,CAAC,WAAW,EAAE;EAAEC,UAAU,EAAE;AAAK,CAAE,CAAC,eAClDV,cAAM,CAACI,KAAK,CAAC,KAAK,CAAC,CACpB;AA8BM,MAAMO,WAAW,GAAIC,GAAW,IAAiB;EACtD,IAAIA,GAAG,CAACC,MAAM,KAAK,CAAC,IAAID,GAAG,CAACE,QAAQ,CAAC,GAAG,CAAC,EAAE;IACzC,MAAM,IAAIC,KAAK,CACb,8DAA8DC,IAAI,CAACC,SAAS,CAACL,GAAG,CAAC,GAAG,CACrF;EACH;EACA,OAAO;IACLA,GAAG;IACHN,IAAI,EAAGY,KAAK,IAAI;MACd,IAAIA,KAAK,CAACL,MAAM,KAAK,CAAC,IAAIK,KAAK,CAACJ,QAAQ,CAAC,GAAG,CAAC,EAAE;QAC7C,MAAM,IAAIC,KAAK,CACb,eAAeC,IAAI,CAACC,SAAS,CAACL,GAAG,CAAC,2DAA2DI,IAAI,CAACC,SAAS,CAACC,KAAK,CAAC,GAAG,CACtH;MACH;MACA,OAAOX,GAAG,CAACD,IAAI,CAAC,GAAGM,GAAG,IAAIM,KAAK,EAAE,CAAC;IACpC;GACD;AACH,CAAC;AAED;;;;;;;;;;AAAAnB,OAAA,CAAAY,WAAA,GAAAA,WAAA;AAUO,MAAMQ,SAAS,GAAApB,OAAA,CAAAoB,SAAA,gBAAGnB,cAAM,CAACoB,GAAG,CAAClB,IAAI,cACtCF,cAAM,CAACqB,oBAAoB,CAAC,CAAC,CAAC,eAC9BrB,cAAM,CAACI,KAAK,CAAC,WAAW,CAAC,CAC1B;AAGD;;;;AAIO,MAAMkB,SAAS,GAAAvB,OAAA,CAAAuB,SAAA,gBAAGtB,cAAM,CAACQ,MAAM,CAACN,IAAI,cACzCF,cAAM,CAACuB,cAAc,EAAE,eACvBvB,cAAM,CAACI,KAAK,CAAC,WAAW,CAAC,CAC1B;AAGD;;;;;;;;AAQO,MAAMoB,QAAQ,GAAAzB,OAAA,CAAAyB,QAAA,gBAAGxB,cAAM,CAACyB,MAAM,CAAC;EACpCC,IAAI,EAAEJ,SAAS;EACfK,IAAI,EAAE3B,cAAM,CAAC4B,kBAAkB;EAC/BC,IAAI,eAAE7B,cAAM,CAAC8B,KAAK,CAACvB,GAAG,CAAC;EACvBwB,IAAI,EAAE/B,cAAM,CAACgC,IAAI;EACjBC,UAAU,EAAEjC,cAAM,CAACkC;CACpB,CAAC;AAGF;AACO,MAAMC,cAAc,GAAApC,OAAA,CAAAoC,cAAA,gBAAGnC,cAAM,CAACyB,MAAM,CAAC;EAC1CW,KAAK,EAAEZ,QAAQ;EACfa,QAAQ,EAAEvC;CACX,CAAC","ignoreList":[]}

package/dist/cjs/Projection.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.composeProjections = exports.AnyProjection = void 0;
+var _Query = require("./Query.js");
+// The wildcard query, built directly (not via the public `query` surface).
+// Decision-model composition assembles `Query` values from plain data because
+// it may legitimately produce shapes the public fast-path surface withholds:
+// composing a type-only projection with tagged ones yields an OR that mixes a
+// tagless item with tagged items. That is the one restriction edge left
+// un-enforced by construction, deliberately, in this internal layer.
+const WILDCARD = {
+  items: []
+};
+const AnyProjection = exports.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.
+   */
+  of: projection => projection
+};
+/** Merge two queries by OR-ing their items; either wildcard yields a wildcard. */
+const mergeQuery = (left, right) => {
+  if (left.items.length === 0 || right.items.length === 0) {
+    return WILDCARD;
+  }
+  return {
+    items: [...left.items, ...right.items]
+  };
+};
+/**
+ * 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.
+ */
+const composeProjections = projections => {
+  const keys = Object.keys(projections);
+  const initialState = Object.fromEntries(keys.map(key => [key, projections[key].initialState]));
+  // Seeding the reduce with the wildcard would swallow everything (mergeQuery
+  // treats an empty-items query as a wildcard), so fold the sub-queries
+  // directly with no seed.
+  const mergedQuery = keys.length === 0 ? WILDCARD : keys.map(key => projections[key].query).reduce((acc, q) => mergeQuery(acc, q));
+  return {
+    initialState,
+    query: mergedQuery,
+    evolve: (state, decoded) => {
+      const next = {
+        ...state
+      };
+      for (const key of keys) {
+        const projection = projections[key];
+        if (!(0, _Query.matchesSequenced)(decoded.sequenced, projection.query)) {
+          continue;
+        }
+        next[key] = projection.evolve(state[key], decoded);
+      }
+      return next;
+    }
+  };
+};
+exports.composeProjections = composeProjections;
+//# sourceMappingURL=Projection.js.map

package/dist/cjs/Projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.js","names":["_Query","require","WILDCARD","items","AnyProjection","exports","of","projection","mergeQuery","left","right","length","composeProjections","projections","keys","Object","initialState","fromEntries","map","key","mergedQuery","query","reduce","acc","q","evolve","state","decoded","next","matchesSequenced","sequenced"],"sources":["../../src/Projection.ts"],"sourcesContent":[null],"mappings":";;;;;;AA4BA,IAAAA,MAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,QAAQ,GAAU;EAAEC,KAAK,EAAE;AAAE,CAAE;AAqD9B,MAAMC,aAAa,GAAAC,OAAA,CAAAD,aAAA,GAAG;EAC3B;;;;;;;EAOAE,EAAE,EAAMC,UAAyB,IAC/BA;CACM;AAaV;AACA,MAAMC,UAAU,GAAGA,CAACC,IAAW,EAAEC,KAAY,KAAW;EACtD,IAAID,IAAI,CAACN,KAAK,CAACQ,MAAM,KAAK,CAAC,IAAID,KAAK,CAACP,KAAK,CAACQ,MAAM,KAAK,CAAC,EAAE;IACvD,OAAOT,QAAQ;EACjB;EACA,OAAO;IAAEC,KAAK,EAAE,CAAC,GAAGM,IAAI,CAACN,KAAK,EAAE,GAAGO,KAAK,CAACP,KAAK;EAAC,CAAE;AACnD,CAAC;AAED;;;;;;;;;;;AAWO,MAAMS,kBAAkB,GAC7BC,WAAc,IACmB;EACjC,MAAMC,IAAI,GAAGC,MAAM,CAACD,IAAI,CAACD,WAAW,CAAoC;EAExE,MAAMG,YAAY,GAAGD,MAAM,CAACE,WAAW,CACrCH,IAAI,CAACI,GAAG,CAAEC,GAAG,IAAK,CAACA,GAAG,EAAEN,WAAW,CAACM,GAAG,CAAC,CAACH,YAAY,CAAC,CAAC,CACnC;EAEtB;EACA;EACA;EACA,MAAMI,WAAW,GACfN,IAAI,CAACH,MAAM,KAAK,CAAC,GACbT,QAAQ,GACRY,IAAI,CACDI,GAAG,CAAEC,GAAG,IAAKN,WAAW,CAACM,GAAG,CAAC,CAACE,KAAK,CAAC,CACpCC,MAAM,CAAC,CAACC,GAAG,EAAEC,CAAC,KAAKhB,UAAU,CAACe,GAAG,EAAEC,CAAC,CAAC,CAAC;EAE/C,OAAO;IACLR,YAAY;IACZK,KAAK,EAAED,WAAW;IAClBK,MAAM,EAAEA,CAACC,KAAK,EAAEC,OAAO,KAAI;MACzB,MAAMC,IAAI,GAAG;QAAE,GAAGF;MAAK,CAAuC;MAC9D,KAAK,MAAMP,GAAG,IAAIL,IAAI,EAAE;QACtB,MAAMP,UAAU,GAAGM,WAAW,CAACM,GAAG,CAAC;QACnC,IAAI,CAAC,IAAAU,uBAAgB,EAACF,OAAO,CAACG,SAAS,EAAEvB,UAAU,CAACc,KAAK,CAAC,EAAE;UAC1D;QACF;QACAO,IAAI,CAACT,GAAG,CAAC,GAAGZ,UAAU,CAACkB,MAAM,CAACC,KAAK,CAACP,GAAG,CAAC,EAAEQ,OAAO,CAEhD;MACH;MACA,OAAOC,IAAI;IACb;GACD;AACH,CAAC;AAAAvB,OAAA,CAAAO,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/dist/cjs/Query.js

@@ -0,0 +1,221 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.query = exports.matchesSequenced = exports.matchesQueryItem = exports.matchesQuery = exports.classifyServableQuery = exports.assertServableQuery = exports.QueryItem = exports.Query = void 0;
+var _effect = require("effect");
+var _Event = require("./Event.js");
+/**
+ * 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.
+ */
+
+/**
+ * One clause of a query: a set of types (OR, empty = any) AND a set of tags
+ * (superset test, empty = no tag constraint).
+ */
+const QueryItem = exports.QueryItem = /*#__PURE__*/_effect.Schema.Struct({
+  types: /*#__PURE__*/_effect.Schema.Array(_Event.EventType),
+  tags: /*#__PURE__*/_effect.Schema.Array(_Event.Tag)
+});
+/** A query: an OR of items. Empty `items` matches everything. */
+const Query = exports.Query = /*#__PURE__*/_effect.Schema.Struct({
+  items: /*#__PURE__*/_effect.Schema.Array(QueryItem)
+});
+/**
+ * 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`.
+ */
+const matchesQueryItem = (event, item) => {
+  const typeOk = item.types.length === 0 || item.types.includes(event.type);
+  if (!typeOk) {
+    return false;
+  }
+  const eventTags = new Set(event.tags);
+  return item.tags.every(tag => eventTags.has(tag));
+};
+/**
+ * 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).
+ */
+exports.matchesQueryItem = matchesQueryItem;
+const matchesQuery = (event, query) => {
+  if (query.items.length === 0) {
+    return true;
+  }
+  return query.items.some(item => matchesQueryItem(event, item));
+};
+/** Convenience predicate over a `SequencedEvent`. */
+exports.matchesQuery = matchesQuery;
+const matchesSequenced = (sequenced, query) => matchesQuery(sequenced.event, query);
+/**
+ * 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.
+ */
+exports.matchesSequenced = matchesSequenced;
+const assertServableQuery = query => {
+  const {
+    items
+  } = query;
+  // Wildcard and single-item queries are always servable.
+  if (items.length <= 1) {
+    return;
+  }
+  // A multi-item query is servable only if every item is tagged; a tagless
+  // (type-only) item mixed with tagged items cannot ride a single index.
+  const hasTaglessItem = items.some(item => item.tags.length === 0);
+  if (hasTaglessItem) {
+    throw new Error('assertServableQuery: a multi-item query must have every item carry at ' + 'least one tag; a type-only item mixed with tagged items is not servable');
+  }
+};
+/**
+ * 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.
+ */
+exports.assertServableQuery = assertServableQuery;
+const classifyServableQuery = query => {
+  if (query.items.length === 0) {
+    return {
+      kind: 'wildcard'
+    };
+  }
+  const only = query.items.length === 1 ? query.items[0] : undefined;
+  if (only !== undefined && only.tags.length === 0) {
+    return _effect.Array.isNonEmptyReadonlyArray(only.types) ? {
+      kind: 'typeOnly',
+      types: only.types
+    } : {
+      kind: 'wildcard'
+    };
+  }
+  return {
+    kind: 'tagged'
+  };
+};
+// --- Smart constructors (the fast-path-enforcing surface) -------------------
+/**
+ * A query item carrying at least one tag (superset test), optionally narrowed
+ * to `types`. The non-empty `tags` requirement is the fast-path restriction,
+ * enforced at the type level rather than as a runtime throw. Combine several
+ * items with `or`.
+ */
+exports.classifyServableQuery = classifyServableQuery;
+const item = fields => ({
+  types: fields.types ?? [],
+  tags: fields.tags
+});
+/** The wildcard query: matches every event. */
+const all = () => ({
+  items: []
+});
+/**
+ * A single-item query matching events that carry all of `tags`, optionally also
+ * constrained to `types`. The common indexed fast-path shape.
+ */
+const tags = (tags, types) => ({
+  items: [item({
+    tags,
+    ...(types === undefined ? {} : {
+      types
+    })
+  })]
+});
+/**
+ * A single type-only query (the other indexed fast path): one item constrained
+ * to `types` with no tag filter. This is the only tagless item shape the
+ * surface admits, and only as the whole query.
+ */
+const types = types => ({
+  items: [{
+    types,
+    tags: []
+  }]
+});
+/**
+ * An OR of query items. Each item should be built with `item` (which requires
+ * at least one tag); combining bare type-only items is intentionally not
+ * offered (use `types` for the single type-only query).
+ */
+const or = items => ({
+  items
+});
+/** Namespaced smart constructors for `Query`. */
+const query = exports.query = {
+  all,
+  item,
+  or,
+  tags,
+  types
+};
+//# sourceMappingURL=Query.js.map

package/dist/cjs/Query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Query.js","names":["_effect","require","_Event","QueryItem","exports","Schema","Struct","types","Array","EventType","tags","Tag","Query","items","matchesQueryItem","event","item","typeOk","length","includes","type","eventTags","Set","every","tag","has","matchesQuery","query","some","matchesSequenced","sequenced","assertServableQuery","hasTaglessItem","Error","classifyServableQuery","kind","only","undefined","Arr","isNonEmptyReadonlyArray","fields","all","or"],"sources":["../../src/Query.ts"],"sourcesContent":[null],"mappings":";;;;;;AAwBA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,MAAA,GAAAD,OAAA;AAzBA;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA;;;;AAIO,MAAME,SAAS,GAAAC,OAAA,CAAAD,SAAA,gBAAGE,cAAM,CAACC,MAAM,CAAC;EACrCC,KAAK,eAAEF,cAAM,CAACG,KAAK,CAACC,gBAAS,CAAC;EAC9BC,IAAI,eAAEL,cAAM,CAACG,KAAK,CAACG,UAAG;CACvB,CAAC;AAGF;AACO,MAAMC,KAAK,GAAAR,OAAA,CAAAQ,KAAA,gBAAGP,cAAM,CAACC,MAAM,CAAC;EACjCO,KAAK,eAAER,cAAM,CAACG,KAAK,CAACL,SAAS;CAC9B,CAAC;AAGF;;;;AAIO,MAAMW,gBAAgB,GAAGA,CAACC,KAAe,EAAEC,IAAe,KAAa;EAC5E,MAAMC,MAAM,GAAGD,IAAI,CAACT,KAAK,CAACW,MAAM,KAAK,CAAC,IAAIF,IAAI,CAACT,KAAK,CAACY,QAAQ,CAACJ,KAAK,CAACK,IAAI,CAAC;EACzE,IAAI,CAACH,MAAM,EAAE;IACX,OAAO,KAAK;EACd;EACA,MAAMI,SAAS,GAAG,IAAIC,GAAG,CAASP,KAAK,CAACL,IAAI,CAAC;EAC7C,OAAOM,IAAI,CAACN,IAAI,CAACa,KAAK,CAAEC,GAAG,IAAKH,SAAS,CAACI,GAAG,CAACD,GAAG,CAAC,CAAC;AACrD,CAAC;AAED;;;;;AAAApB,OAAA,CAAAU,gBAAA,GAAAA,gBAAA;AAKO,MAAMY,YAAY,GAAGA,CAACX,KAAe,EAAEY,KAAY,KAAa;EACrE,IAAIA,KAAK,CAACd,KAAK,CAACK,MAAM,KAAK,CAAC,EAAE;IAC5B,OAAO,IAAI;EACb;EACA,OAAOS,KAAK,CAACd,KAAK,CAACe,IAAI,CAAEZ,IAAI,IAAKF,gBAAgB,CAACC,KAAK,EAAEC,IAAI,CAAC,CAAC;AAClE,CAAC;AAED;AAAAZ,OAAA,CAAAsB,YAAA,GAAAA,YAAA;AACO,MAAMG,gBAAgB,GAAGA,CAC9BC,SAAyB,EACzBH,KAAY,KACAD,YAAY,CAACI,SAAS,CAACf,KAAK,EAAEY,KAAK,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAvB,OAAA,CAAAyB,gBAAA,GAAAA,gBAAA;AA0BO,MAAME,mBAAmB,GAAIJ,KAAY,IAAU;EACxD,MAAM;IAAEd;EAAK,CAAE,GAAGc,KAAK;EACvB;EACA,IAAId,KAAK,CAACK,MAAM,IAAI,CAAC,EAAE;IACrB;EACF;EACA;EACA;EACA,MAAMc,cAAc,GAAGnB,KAAK,CAACe,IAAI,CAAEZ,IAAI,IAAKA,IAAI,CAACN,IAAI,CAACQ,MAAM,KAAK,CAAC,CAAC;EACnE,IAAIc,cAAc,EAAE;IAClB,MAAM,IAAIC,KAAK,CACb,wEAAwE,GACtE,yEAAyE,CAC5E;EACH;AACF,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA7B,OAAA,CAAA2B,mBAAA,GAAAA,mBAAA;AA+BO,MAAMG,qBAAqB,GAAIP,KAAY,IAAwB;EACxE,IAAIA,KAAK,CAACd,KAAK,CAACK,MAAM,KAAK,CAAC,EAAE;IAC5B,OAAO;MAAEiB,IAAI,EAAE;IAAU,CAAE;EAC7B;EACA,MAAMC,IAAI,GAAGT,KAAK,CAACd,KAAK,CAACK,MAAM,KAAK,CAAC,GAAGS,KAAK,CAACd,KAAK,CAAC,CAAC,CAAC,GAAGwB,SAAS;EAClE,IAAID,IAAI,KAAKC,SAAS,IAAID,IAAI,CAAC1B,IAAI,CAACQ,MAAM,KAAK,CAAC,EAAE;IAChD,OAAOoB,aAAG,CAACC,uBAAuB,CAACH,IAAI,CAAC7B,KAAK,CAAC,GAC1C;MAAE4B,IAAI,EAAE,UAAU;MAAE5B,KAAK,EAAE6B,IAAI,CAAC7B;IAAK,CAAE,GACvC;MAAE4B,IAAI,EAAE;IAAU,CAAE;EAC1B;EACA,OAAO;IAAEA,IAAI,EAAE;EAAQ,CAAE;AAC3B,CAAC;AAED;AAEA;;;;;;AAAA/B,OAAA,CAAA8B,qBAAA,GAAAA,qBAAA;AAMA,MAAMlB,IAAI,GAAIwB,MAGb,KAAiB;EAChBjC,KAAK,EAAEiC,MAAM,CAACjC,KAAK,IAAI,EAAE;EACzBG,IAAI,EAAE8B,MAAM,CAAC9B;CACd,CAAC;AAEF;AACA,MAAM+B,GAAG,GAAGA,CAAA,MAAc;EAAE5B,KAAK,EAAE;AAAE,CAAE,CAAC;AAExC;;;;AAIA,MAAMH,IAAI,GAAGA,CACXA,IAA2C,EAC3CH,KAAgC,MACrB;EACXM,KAAK,EAAE,CAACG,IAAI,CAAC;IAAEN,IAAI;IAAE,IAAIH,KAAK,KAAK8B,SAAS,GAAG,EAAE,GAAG;MAAE9B;IAAK,CAAE;EAAC,CAAE,CAAC;CAClE,CAAC;AAEF;;;;;AAKA,MAAMA,KAAK,GACTA,KAAwD,KAC7C;EAAEM,KAAK,EAAE,CAAC;IAAEN,KAAK;IAAEG,IAAI,EAAE;EAAE,CAAE;AAAC,CAAE,CAAC;AAE9C;;;;;AAKA,MAAMgC,EAAE,GACN7B,KAAwD,KAC7C;EACXA;CACD,CAAC;AAEF;AACO,MAAMc,KAAK,GAAAvB,OAAA,CAAAuB,KAAA,GAAG;EACnBc,GAAG;EACHzB,IAAI;EACJ0B,EAAE;EACFhC,IAAI;EACJH;CACQ","ignoreList":[]}