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

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

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

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

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

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

package/dist/dts-esm/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"}