@kairos-es/core 1.0.0-alpha.4 → 1.0.0-alpha.6

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

@@ -1 +0,0 @@
-{"version":3,"file":"Event.d.ts","sourceRoot":"","sources":["../../src/Event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,+DAGpB,CAAA;AACD,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C,8DAA8D;AAC9D,eAAO,MAAM,MAAM,EAAE,QAA4B,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,GAAG,0DAGf,CAAA;AACD,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,CAAA;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,GAAG,CAAA;CACtC;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,WAiBzC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,6DAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;GAGG;AACH,eAAO,MAAM,SAAS,gEAGrB,CAAA;AACD,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,QAAQ,4DAGnB,CAAA;AACF,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;;;;;;;GAaG;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/SubscribeMachine.d.ts

@@ -1,179 +0,0 @@
-/**
- * The subscribe machine every engine's `subscribe` is built from — the in-memory
- * store, `@kairos-es/store-postgres` and `@kairos-es/store-sqlite`: the wake queue,
- * the wake-source drain, the paged catch-up reconcile, the `> boundary` de-dup (via
- * the cursor's exclusive lower bound) and the poll loop that together turn a paged
- * read into a live subscription.
- *
- * It lives in core because delivery semantics are contract semantics. An engine
- * supplies TRANSPORT through two STUBBABLE seams — `fetch`, a paged read strictly
- * after a cursor, and `listen`, an optional wake source — and inherits the delivery
- * behaviour whole, exactly as it supplies mechanics to `makeContractStore` and
- * inherits the contract policy whole. Two engines that each grew their own wake
- * loop would be identical only by inspection, and `subscribe` is the verb where
- * that is least affordable: a divergence there loses events rather than failing.
- * Both seams take plain in-memory values in a test, so the wake/poll/de-dup logic
- * is exercisable with no live backend at all.
- *
- * All THREE are the callers, and the count matters to a reader here: it means there
- * is exactly ONE delivery algorithm in this repo, and it is the code below. The
- * in-memory store is a caller like the rest — it hands in a `fetch` over its log
- * `Ref` and its append `PubSub` as a wake source and keeps no delivery logic of its
- * own — which is what makes the shared contract suite's subscribe cases a comparison
- * of two BACKENDS rather than of two delivery algorithms.
- *
- * Correctness rests on the periodic position-based reconcile — a re-read from the
- * cursor every poll interval — and NEVER on the wake source, which only lowers
- * delivery latency below that interval. A subscription with no wake source at all
- * is therefore complete and correct, merely slower, which is why `listen` is
- * optional in the TYPE rather than by the convention of passing `Stream.never`:
- * poll-only delivery is a supported shape, not a degraded one.
- *
- * ## The precondition every engine inherits: ASCENDING COMMIT ORDER
- *
- * A position that is committed and VISIBLE must never be below one already
- * delivered. Gaps are fine: the cursor is an ascending exclusive lower bound, so a
- * number that is allocated and never committed, or never allocated at all, is
- * simply a number the machine never sees. Out-of-order commits are not fine. If one
- * writer allocates position 5 and another allocates 6, and 6 commits first, a poll
- * landing between the two commits delivers 6 and advances the cursor past it — and
- * 5 is then lost forever, because no later read looks below the cursor and nothing
- * anywhere notices the hole. An engine whose concurrent writers can commit out of
- * order MUST serialise them, or this machine will silently skip. An engine that
- * takes an exclusive lock on both of its append paths discharges the obligation
- * that way; an engine whose append is a single statement discharges it
- * structurally.
- *
- * The obligation is written down HERE, in the algorithm that depends on it, rather
- * than in whichever engine happens to satisfy it. It is a property of this delivery
- * loop and of nothing else, so an engine author reading only their own source has
- * no way to discover that anything downstream needs it — and the failure mode is
- * the worst kind there is: no error, no defect, no failing test, just an event that
- * a subscriber never receives. A single engine owning both its append path and its
- * own wake loop can leave the assumption implicit; a shared machine cannot.
- *
- * ## `catchUpPageSize` bounds the READ, not the emission
- *
- * `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds each
- * `fetch` — but it COLLECTS every page into one array, which is emitted as a SINGLE
- * chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
- * subscriber joining behind a large log materialises the whole backlog before its
- * consumer sees the first element.
- *
- * That is a memory characteristic and nothing more, which is why ONE chunk is
- * enough here: downstream commit boundaries do not depend on the upstream chunking
- * at all, because the read side's `Stream.groupedWithin` re-chunks the stream into
- * bounded micro-batches whatever arrives (ADR-0007), so a projection's transactions
- * stay small even against a one-chunk catch-up. The cost therefore lands on backlog
- * memory alone, and it lands hardest on the durable-log-with-in-memory-view mode,
- * where an ephemeral view re-catches-up the entire log on every boot.
- */
-import { Effect, Schema, type Scope, Stream } from 'effect';
-import type { Position, SequencedEvent } from './Event.js';
-import { ReadLimit } from './Event.js';
-/**
- * A short catch-up page size default for the reconcile loop. Reads page by page
- * until a short page signals the tail is drained, so a large backlog is streamed in
- * bounded chunks rather than one unbounded read. Every engine takes its
- * `catchUpPageSize` from here — each SQL engine as its config's default, the
- * in-memory store as its options' — so backends cannot drift on tuning.
- */
-export declare const DEFAULT_CATCH_UP_PAGE_SIZE = 512;
-/**
- * The default upper bound a subscriber waits for a wake before re-reading from its
- * cursor ANYWAY (milliseconds). Every engine takes its `pollInterval` from here —
- * each SQL engine as its config's default, the in-memory store as its options' — so
- * backends cannot drift on tuning.
- *
- * This periodic position-based poll — not the wake source — IS the correctness
- * guarantee: every committed position is reconciled within this interval whether or
- * not a wake for it was ever heard. That covers a wake fired before the source was
- * fully established, a coalesced or dropped wake, and a wake source that died
- * silently and never said so. A wake source only lowers delivery latency BELOW this
- * interval; it never carries delivery, so no engine's wake mechanism can make the
- * right figure here engine-specific. It trades worst-case delivery latency against
- * idle read volume and nothing else. Upstream `postgres_tt.py` picks the same
- * one-second fallback poll (`conn.wait(..., interval=1)`).
- */
-export declare const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
-/**
- * The two subscribe-tuning config FIELDS, for an engine whose config is a `Schema`
- * to spread into its own struct.
- *
- * These knobs are the machine's, not any engine's: they name what the loop above
- * does, the figures they fall back to are the two constants declared beside them,
- * and neither is derivable from a backend's own properties — which is why the
- * defaults already live here. Shipping the FIELD rather than only the default is
- * what closes the last gap in that arrangement. An engine that spreads these gets
- * the key NAME, the VALIDATION and the DEFAULT from one place, so a caller who has
- * tuned one engine's subscribe reads another's without translating, and the two
- * cannot drift in what they ACCEPT any more than in what they assume. Two engines
- * hand-authoring the identical `Schema.optionalWith(…)` twice were identical only
- * by inspection.
- *
- * The bounds differ between the two because the quantities do. `pollInterval` is a
- * duration, so a fraction of a millisecond is meaningful and only `positive` and
- * `finite` matter: at zero or below the loop would spin without ever waiting for a
- * wake, and at `Infinity` the periodic re-read — the half that carries delivery —
- * would never come, which silently converts the wake source from an optimisation
- * into the guarantee. `catchUpPageSize` is a COUNT, so it must be an integer
- * (`Schema.Int` excludes `Infinity` with it): the reconcile loop compares a page's
- * length against it to decide the tail is drained, and a page of zero would report
- * "drained" forever without reading anything.
- *
- * `exact: true` on both keeps the decoded type at `key?: T` rather than
- * `T | undefined`, matching the repo's `exactOptionalPropertyTypes` discipline — an
- * absent key, never an explicit `undefined`.
- */
-export declare const subscriptionTuningFields: {
-    readonly pollInterval: Schema.optionalWith<Schema.filter<Schema.filter<typeof Schema.Number>>, {
-        exact: true;
-    }>;
-    readonly catchUpPageSize: Schema.optionalWith<Schema.filter<typeof Schema.Int>, {
-        exact: true;
-    }>;
-};
-/**
- * The two seams the subscribe machine runs over, plus the two tuning knobs. `E` is
- * the engine's own infrastructure error — whatever its reads fail with — and it
- * stays on the channel through to `makeContractStore`, which dies it.
- *
- * ONE type parameter and not two, deliberately: a wake source with an error type of
- * its own is `Stream.orDie`d by the caller, yielding a `Stream<unknown, never>`
- * that is assignable here under Effect v3's covariant error channel. A second
- * parameter would buy nothing and would have to be spelled at every call site. Nor
- * is there an `R`: neither seam contributes a requirement, and unused generality is
- * not free.
- */
-export interface SubscriptionDeps<E> {
-    /**
-     * Page-read the events strictly after `from`, up to `limit`, ascending by
-     * position. Returning FEWER than `limit` signals the tail is drained.
-     */
-    readonly fetch: (from: Position, limit: ReadLimit) => Effect.Effect<ReadonlyArray<SequencedEvent>, E>;
-    /**
-     * The raw wake source: each element is an OPAQUE wake signal. The machine taps it
-     * into its own wake queue and drains it on a background fibre; it never reads the
-     * elements, so anything an engine can push on a change will do.
-     *
-     * OPTIONAL, and omitting it defaults to `Stream.never` at the point of use — an
-     * engine with no wake mechanism gets poll-only delivery, which the poll loop
-     * already makes correct. Under `exactOptionalPropertyTypes` that means omitting
-     * the key entirely rather than passing `undefined`.
-     */
-    readonly listen?: Stream.Stream<unknown, E>;
-    /** The poll interval in milliseconds (see `DEFAULT_POLL_INTERVAL_MILLIS`). */
-    readonly pollInterval: number;
-    /** The catch-up page size (see `DEFAULT_CATCH_UP_PAGE_SIZE`). */
-    readonly catchUpPageSize: number;
-}
-/**
- * Build the subscription `Stream`: catch up from `after`, then track the live tail.
- * The cursor threads through the `unfoldChunkEffect` unfold state, starting at
- * `after` and advancing to the last delivered position each batch; the stream never
- * completes on its own (always `Option.some`), so the enclosing scope interrupts it
- * on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
- * (subscribe is `E = never` on the contract).
- */
-export declare const subscribeStream: <E>(deps: SubscriptionDeps<E>, after: Position | undefined) => Stream.Stream<SequencedEvent, E, Scope.Scope>;
-//# sourceMappingURL=SubscribeMachine.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"SubscribeMachine.d.ts","sourceRoot":"","sources":["../../src/SubscribeMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EAEL,MAAM,EAIN,MAAM,EACN,KAAK,KAAK,EACV,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAU,SAAS,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB;;;;;;;CAQ3B,CAAA;AAcV;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAA;IACpD;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,MAAM,gBAAgB,CAAC,CAAC,CAAC,EACzB,OAAO,QAAQ,GAAG,SAAS,KAC1B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAyG5C,CAAA"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"retryOnConflict.d.ts","sourceRoot":"","sources":["../../src/retryOnConflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,EAAE,MAAM,EAAa,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAqBrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACrC,SAAS,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,EAAE,CAAC,CAAC,EACvD,WAAU,QAAQ,CAAC,QAAQ,CACzB,OAAO,EACP,qBAAqB,GAAG,CAAC,EACzB,CAAC,CACgB,KAClB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,qBAAqB,GAAG,CAAC,EAAE,CAAC,CAI5C,CAAA"}