@kairos-es/core 0.0.0

package/dist/esm/ContractStore.js

@@ -0,0 +1,73 @@
+import { Effect, Predicate, Schema, Stream } from 'effect';
+import { ReadLimit } from "./Event.js";
+import { assertServableQuery } from "./Query.js";
+/** Decode an unknown limit through `ReadLimit`, dying on a defect-worthy value. */
+const decodeReadLimit = /*#__PURE__*/Schema.decodeUnknownSync(ReadLimit);
+/**
+ * Wrap a raw engine's mechanics with the shared contract-enforcement policy,
+ * producing a full `DcbEventStore` service value.
+ */
+export const makeContractStore = raw => ({
+  read: (query, options) => Effect.suspend(() => {
+    // Defects (surface when the Effect runs), keeping `read` at `E = never`.
+    assertServableQuery(query);
+    if (options?.limit !== undefined) {
+      decodeReadLimit(options.limit);
+    }
+    // Infrastructure faults are defects, not contract values.
+    return Effect.orDie(raw.read(query, options));
+  }),
+  append: (events, condition) => 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) {
+      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.catchAll(raw.append(events, condition), error => Predicate.isTagged('AppendConditionFailed')(error) ? Effect.fail(error) : 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`).
+  Stream.unwrap(Effect.sync(() => {
+    assertServableQuery(query);
+    return Stream.orDie(raw.subscribe(query, after));
+  }))
+});
+//# sourceMappingURL=ContractStore.js.map

package/dist/esm/ContractStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractStore.js","names":["Effect","Predicate","Schema","Stream","ReadLimit","assertServableQuery","decodeReadLimit","decodeUnknownSync","makeContractStore","raw","read","query","options","suspend","limit","undefined","orDie","append","events","condition","length","Error","failIfEventsMatch","catchAll","error","isTagged","fail","die","subscribe","after","unwrap","sync"],"sources":["../../src/ContractStore.ts"],"sourcesContent":[null],"mappings":"AAgCA,SAASA,MAAM,EAAEC,SAAS,EAAEC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AAI1D,SAASC,SAAS,QAAQ,YAAS;AAEnC,SAASC,mBAAmB,QAAoB,YAAS;AAEzD;AACA,MAAMC,eAAe,gBAAGJ,MAAM,CAACK,iBAAiB,CAACH,SAAS,CAAC;AAwB3D;;;;AAIA,OAAO,MAAMI,iBAAiB,GAC5BC,GAAwB,KACG;EAC3BC,IAAI,EAAEA,CAACC,KAAK,EAAEC,OAAO,KACnBZ,MAAM,CAACa,OAAO,CAAC,MAAK;IAClB;IACAR,mBAAmB,CAACM,KAAK,CAAC;IAC1B,IAAIC,OAAO,EAAEE,KAAK,KAAKC,SAAS,EAAE;MAChCT,eAAe,CAACM,OAAO,CAACE,KAAK,CAAC;IAChC;IACA;IACA,OAAOd,MAAM,CAACgB,KAAK,CAACP,GAAG,CAACC,IAAI,CAACC,KAAK,EAAEC,OAAO,CAAC,CAAC;EAC/C,CAAC,CAAC;EAEJK,MAAM,EAAEA,CAACC,MAAM,EAAEC,SAAS,KACxBnB,MAAM,CAACa,OAAO,CAAC,MAAK;IAClB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,IAAIK,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;MAC3BV,mBAAmB,CAACc,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,OAAOtB,MAAM,CAACuB,QAAQ,CAACd,GAAG,CAACQ,MAAM,CAACC,MAAM,EAAEC,SAAS,CAAC,EAAGK,KAAK,IAC1DvB,SAAS,CAACwB,QAAQ,CAAC,uBAAuB,CAAC,CAACD,KAAK,CAAC,GAC9CxB,MAAM,CAAC0B,IAAI,CAACF,KAAK,CAAC,GAClBxB,MAAM,CAAC2B,GAAG,CAACH,KAAK,CAAC,CACtB;EACH,CAAC,CAAC;EAEJI,SAAS,EAAEA,CAACjB,KAAK,EAAEkB,KAAK;EACtB;EACA;EACA;EACA;EACA1B,MAAM,CAAC2B,MAAM,CACX9B,MAAM,CAAC+B,IAAI,CAAC,MAAK;IACf1B,mBAAmB,CAACM,KAAK,CAAC;IAC1B,OAAOR,MAAM,CAACa,KAAK,CAACP,GAAG,CAACmB,SAAS,CAACjB,KAAK,EAAEkB,KAAK,CAAC,CAAC;EAClD,CAAC,CAAC;CAEP,CAAC","ignoreList":[]}

package/dist/esm/DcbEventStore.js

@@ -0,0 +1,3 @@
+import { Context } from 'effect';
+export class DcbEventStore extends /*#__PURE__*/Context.Tag('@kairos-es/core/DcbEventStore')() {}
+//# sourceMappingURL=DcbEventStore.js.map

package/dist/esm/DcbEventStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DcbEventStore.js","names":["Context","DcbEventStore","Tag"],"sources":["../../src/DcbEventStore.ts"],"sourcesContent":[null],"mappings":"AAiBA,SAASA,OAAO,QAAQ,QAAQ;AA2BhC,OAAM,MAAOC,aAAc,sBAAQD,OAAO,CAACE,GAAG,CAAC,+BAA+B,CAAC,EAgC5E","ignoreList":[]}

package/dist/esm/Event.js

@@ -0,0 +1,81 @@
+/**
+ * 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 const Position = /*#__PURE__*/Schema.BigInt.pipe(/*#__PURE__*/Schema.nonNegativeBigInt(), /*#__PURE__*/Schema.brand('Position'));
+/** The sentinel position meaning "before the first event". */
+export const 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).
+ */
+export const Tag = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.pattern(/^[^:]+:.+/, {
+  identifier: 'Tag'
+}), /*#__PURE__*/Schema.brand('Tag'));
+export 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)`.
+ */
+export const ReadLimit = /*#__PURE__*/Schema.Int.pipe(/*#__PURE__*/Schema.greaterThanOrEqualTo(0), /*#__PURE__*/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.
+ */
+export const EventType = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEmptyString(), /*#__PURE__*/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.
+ */
+export const DcbEvent = /*#__PURE__*/Schema.Struct({
+  type: EventType,
+  data: Schema.Uint8ArrayFromSelf,
+  tags: /*#__PURE__*/Schema.Array(Tag),
+  uuid: Schema.UUID,
+  occurredAt: Schema.DateTimeUtc
+});
+/** A persisted event: the event together with the position it was written at. */
+export const SequencedEvent = /*#__PURE__*/Schema.Struct({
+  event: DcbEvent,
+  position: Position
+});
+//# sourceMappingURL=Event.js.map

package/dist/esm/Event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Event.js","names":["Schema","Position","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":"AAAA;;;;;;;;AAQA,SAASA,MAAM,QAAQ,QAAQ;AAE/B;;;;;;;;;AASA,OAAO,MAAMC,QAAQ,gBAAGD,MAAM,CAACE,MAAM,CAACC,IAAI,cACxCH,MAAM,CAACI,iBAAiB,EAAE,eAC1BJ,MAAM,CAACK,KAAK,CAAC,UAAU,CAAC,CACzB;AAGD;AACA,OAAO,MAAMC,MAAM,gBAAaL,QAAQ,CAACM,IAAI,CAAC,EAAE,CAAC;AAEjD;;;;;;AAMA,OAAO,MAAMC,GAAG,gBAAGR,MAAM,CAACS,MAAM,CAACN,IAAI,cACnCH,MAAM,CAACU,OAAO,CAAC,WAAW,EAAE;EAAEC,UAAU,EAAE;AAAK,CAAE,CAAC,eAClDX,MAAM,CAACK,KAAK,CAAC,KAAK,CAAC,CACpB;AA8BD,OAAO,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;;;;;;;;;;AAUA,OAAO,MAAMC,SAAS,gBAAGpB,MAAM,CAACqB,GAAG,CAAClB,IAAI,cACtCH,MAAM,CAACsB,oBAAoB,CAAC,CAAC,CAAC,eAC9BtB,MAAM,CAACK,KAAK,CAAC,WAAW,CAAC,CAC1B;AAGD;;;;AAIA,OAAO,MAAMkB,SAAS,gBAAGvB,MAAM,CAACS,MAAM,CAACN,IAAI,cACzCH,MAAM,CAACwB,cAAc,EAAE,eACvBxB,MAAM,CAACK,KAAK,CAAC,WAAW,CAAC,CAC1B;AAGD;;;;;;;;AAQA,OAAO,MAAMoB,QAAQ,gBAAGzB,MAAM,CAAC0B,MAAM,CAAC;EACpCC,IAAI,EAAEJ,SAAS;EACfK,IAAI,EAAE5B,MAAM,CAAC6B,kBAAkB;EAC/BC,IAAI,eAAE9B,MAAM,CAAC+B,KAAK,CAACvB,GAAG,CAAC;EACvBwB,IAAI,EAAEhC,MAAM,CAACiC,IAAI;EACjBC,UAAU,EAAElC,MAAM,CAACmC;CACpB,CAAC;AAGF;AACA,OAAO,MAAMC,cAAc,gBAAGpC,MAAM,CAAC0B,MAAM,CAAC;EAC1CW,KAAK,EAAEZ,QAAQ;EACfa,QAAQ,EAAErC;CACX,CAAC","ignoreList":[]}

package/dist/esm/Projection.js

@@ -0,0 +1,66 @@
+import { matchesSequenced } from "./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: []
+};
+export 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.
+   */
+  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.
+ */
+export 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 (!matchesSequenced(decoded.sequenced, projection.query)) {
+          continue;
+        }
+        next[key] = projection.evolve(state[key], decoded);
+      }
+      return next;
+    }
+  };
+};
+//# sourceMappingURL=Projection.js.map

package/dist/esm/Projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.js","names":["matchesSequenced","WILDCARD","items","AnyProjection","of","projection","mergeQuery","left","right","length","composeProjections","projections","keys","Object","initialState","fromEntries","map","key","mergedQuery","query","reduce","acc","q","evolve","state","decoded","next","sequenced"],"sources":["../../src/Projection.ts"],"sourcesContent":[null],"mappings":"AA4BA,SAASA,gBAAgB,QAAQ,YAAS;AAE1C;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,QAAQ,GAAU;EAAEC,KAAK,EAAE;AAAE,CAAE;AAqDrC,OAAO,MAAMC,aAAa,GAAG;EAC3B;;;;;;;EAOAC,EAAE,EAAMC,UAAyB,IAC/BA;CACM;AAaV;AACA,MAAMC,UAAU,GAAGA,CAACC,IAAW,EAAEC,KAAY,KAAW;EACtD,IAAID,IAAI,CAACL,KAAK,CAACO,MAAM,KAAK,CAAC,IAAID,KAAK,CAACN,KAAK,CAACO,MAAM,KAAK,CAAC,EAAE;IACvD,OAAOR,QAAQ;EACjB;EACA,OAAO;IAAEC,KAAK,EAAE,CAAC,GAAGK,IAAI,CAACL,KAAK,EAAE,GAAGM,KAAK,CAACN,KAAK;EAAC,CAAE;AACnD,CAAC;AAED;;;;;;;;;;;AAWA,OAAO,MAAMQ,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,GACbR,QAAQ,GACRW,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,CAACjB,gBAAgB,CAACyB,OAAO,CAACE,SAAS,EAAEtB,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","ignoreList":[]}

package/dist/esm/Query.js

@@ -0,0 +1,209 @@
+/**
+ * The DCB selection language: `Query` is an OR of `QueryItem`s. Within an item,
+ * `types` is an OR-filter (empty means any type) and `tags` is an AND superset
+ * test (the event must carry all of the item's tags; extra event tags are
+ * fine). The empty query (`items: []`) matches every event.
+ *
+ * The match predicate is a single pure module function over plain data;
+ * `Query` values carry no methods. See `matchesQuery` / `matchesQueryItem`.
+ *
+ * Smart constructors enforce the indexed fast-path restriction at the
+ * constructor surface (not via a runtime throw): every query built through them
+ * is the wildcard (`query.all`), a single type-only item (`query.types`), or an
+ * OR of tagged items each carrying at least one tag (`query.item` + `query.or`,
+ * or `query.tags` for the single-item case). The `query.item` constructor
+ * requires a non-empty `tags` at the type level, so there is no public way to
+ * build an unrestricted item (empty types and empty tags). `QueryItem`/`Query`
+ * are plain data, so internal decision-model plumbing can still assemble any
+ * shape directly; the restriction binds the public surface, where consumers
+ * build their consistency boundaries.
+ *
+ * The grammar's DISPATCH lives here too, beside the grammar it dispatches over:
+ * `ServableQueryShape` / `classifyServableQuery` own the three shapes an engine
+ * serves and the routing of the degenerate empty item.
+ */
+import { Array as Arr, Schema } from 'effect';
+import { EventType, Tag } from "./Event.js";
+/**
+ * One clause of a query: a set of types (OR, empty = any) AND a set of tags
+ * (superset test, empty = no tag constraint).
+ */
+export const QueryItem = /*#__PURE__*/Schema.Struct({
+  types: /*#__PURE__*/Schema.Array(EventType),
+  tags: /*#__PURE__*/Schema.Array(Tag)
+});
+/** A query: an OR of items. Empty `items` matches everything. */
+export const Query = /*#__PURE__*/Schema.Struct({
+  items: /*#__PURE__*/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`.
+ */
+export 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).
+ */
+export const matchesQuery = (event, query) => {
+  if (query.items.length === 0) {
+    return true;
+  }
+  return query.items.some(item => matchesQueryItem(event, item));
+};
+/** Convenience predicate over a `SequencedEvent`. */
+export 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.
+ */
+export 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.
+ */
+export 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 Arr.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`.
+ */
+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`. */
+export const query = {
+  all,
+  item,
+  or,
+  tags,
+  types
+};
+//# sourceMappingURL=Query.js.map

package/dist/esm/Query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Query.js","names":["Array","Arr","Schema","EventType","Tag","QueryItem","Struct","types","tags","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","isNonEmptyReadonlyArray","fields","all","or"],"sources":["../../src/Query.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}