@demlik/tea 0.13.0 → 0.15.0

package/dist/idempotency/adapter.d.ts

@@ -1,62 +0,0 @@
-import { IdempotencyStore } from './index.js';
-
-/**
- * @demlik/tea/idempotency/adapter — the verb seam over the pure idempotency ops.
- *
- * The functions in `./index` (`seen` / `recall` / `remember` / `evictExpired`
- * / `initStore`) are the BLESSED transitions, but their names and the
- * `IdempotencyStore<V>` shape they read/return are the STORE's vocabulary. A
- * consumer that owns an `IdempotencyStore<V>` slice (`idempotent-intake`,
- * `poller`) used to import those functions by name and call them directly, so
- * a change to the op surface — or to `IdempotencyStore`'s fields — cascaded to
- * every call site.
- *
- * `IdempotencyMemory<V>` is the insulating interface: five VERBS (`isSeen` /
- * `recall` / `remember` / `evict` / `init`) consumers depend on instead of the
- * raw functions. The verbs keep the ops' pure contract — no I/O, no `Date.now`
- * (the clock is injected as `now`) — so a consumer folding the adapter through
- * its reducer stays inside invariant 2 (pure transitions). `isSeen` renames the
- * blessed `seen` predicate (a noun-y `seen` reads ambiguously as a slice field;
- * the verb form states the question it answers), and `evict` is the verb form
- * of `evictExpired`.
- *
- * `idempotencyMemory<V>()` is the canonical implementation, a thin binding of
- * the blessed ops. Because the verbs are the only surface consumers touch, an
- * `IdempotencyStore` shape change is absorbed HERE rather than at the consumer
- * call sites.
- *
- * INTERNAL seam (no public-API port): consumers import the adapter from this
- * subpath the same way they imported the ops. The ops remain exported from
- * `./index` for any call site that genuinely wants a function directly.
- */
-
-/**
- * The verb interface over an `IdempotencyStore<V>`. Each verb mirrors a blessed
- * op's pure contract but speaks the consumer's dedupe vocabulary, so the
- * consumer never names a store function or reaches into an `IdempotencyStore`
- * field it did not put there.
- */
-interface IdempotencyMemory<V> {
-    /** Create an empty store, optionally bounded by `capacity` and/or `ttlMs`. */
-    init(opts?: {
-        capacity?: number;
-        ttlMs?: number;
-    }): IdempotencyStore<V>;
-    /** True iff `key` is present AND not expired at `now`. Read-only. */
-    isSeen(store: IdempotencyStore<V>, key: string, now: number): boolean;
-    /** The cached value for `key` if present and unexpired at `now`. Read-only. */
-    recall(store: IdempotencyStore<V>, key: string, now: number): V | undefined;
-    /** Record `key → value` at `now`, enforcing the store's bounds. Returns a new store. */
-    remember(store: IdempotencyStore<V>, key: string, value: V, now: number): IdempotencyStore<V>;
-    /** Drop every entry expired at `now`. Returns a new store. */
-    evict(store: IdempotencyStore<V>, now: number): IdempotencyStore<V>;
-}
-/**
- * The canonical `IdempotencyMemory<V>`, binding each verb to its blessed op.
- * Pure and stateless — call once at module scope in a consumer and fold its
- * verbs through the reducer. An `IdempotencyStore` shape change is absorbed by
- * re-binding a verb here, not at the consumers.
- */
-declare function idempotencyMemory<V>(): IdempotencyMemory<V>;
-
-export { type IdempotencyMemory, idempotencyMemory };

package/dist/idempotency/adapter.js

@@ -1,4 +0,0 @@
-export { idempotencyMemory } from '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-//# sourceMappingURL=adapter.js.map
-//# sourceMappingURL=adapter.js.map

package/dist/idempotency/adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"adapter.js"}

package/dist/idempotent-intake/index.d.ts

@@ -1,188 +0,0 @@
-import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd } from '../core-Co0LWkIA.js';
-import { QueueItem } from '../work-queue/index.js';
-import 'zod';
-import '../runtime-types-CNLmhWif.js';
-import 'better-result';
-
-/**
- * @demlik/tea/idempotent-intake — receive-once intake for webhooks / queue
- * messages: dedupe by key, enqueue the new ones, replay the cached result to
- * the duplicates. The "process this payload exactly once even though it
- * arrives N times" knob.
- *
- * **The recipe.** This is a Level-2 composition — it owns no primitive
- * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*
- * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`
- * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —
- * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay
- * insulated behind verbs the intake calls:
- *
- *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The
- *     `seen` half of the slice is its `IdempotencyStore`, keyed by
- *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;
- *     `complete` calls `memory.remember` again to swap its cached value from
- *     `pending` to the finished `result`. The cache write is the brick's, never
- *     re-rolled here.
- *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the
- *     slice is its `QueueItem<P>[]`. Every status flip routes through the
- *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps
- *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's
- *     claim via `queue.patch`. Intake owns only the SELECTION (which item,
- *     gated on the done-cache reconcile below) — the array transition is the
- *     brick's. The consumer drains it (claim → process → `complete`) at its own
- *     pace.
- *
- * Both bricks are pure-state + pure-ops, host- and clock-agnostic by
- * construction, so the combined slice inherits TEA's two non-negotiables:
- *
- *   - **Durable** — the slice is a plain serializable value (a record-backed
- *     idempotency store + an array of queue items, no `Map`, no closures), so
- *     it survives a Durable-Object eviction / reload and rehydrates whole.
- *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`
- *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.
- *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call
- *     site, so `trace-replay` reconstructs each transition exactly.
- *
- * **The decision lives in a Cmd, not in a return shape.** `receive` cannot
- * "return" what it decided (the knob contract pins the shape to
- * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime
- * performs:
- *
- *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit
- *     `IntakeProcess` (go run the work).
- *   - a key already `pending`  → drop silently (the original is in flight);
- *     emit nothing.
- *   - a key already `done`     → emit `IntakeReplay` carrying the cached
- *     result so the duplicate caller gets the SAME response the first one
- *     produced, with zero re-execution of the side effect.
- *
- * **Two crash-safety guarantees the verbs enforce (and the unit specs alone
- * missed — see the wired-machine test):**
- *
- *   - *A slow worker is never double-enqueued.* The TTL clock starts at
- *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a
- *     duplicate of an in-flight key is always dropped no matter how long the
- *     worker takes. Only a `done` entry expires (see `liveEntry`).
- *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile
- *     the queue against the done cache: a queue item whose key already resolved
- *     to `done` in `seen` is skipped (never reset to pending, never claimed),
- *     so a worker that finished and cached its result before the DO evicted is
- *     not re-executed on resume.
- *
- * Typical wiring (the combinator form — splice ~3 hooks into a host machine):
- *
- *   const intake = createIntake<StripeEvent, ChargeResult>({
- *     keyOf: (e) => e.id,          // Stripe's idempotency key
- *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run
- *   });
- *
- *   // in `init`:
- *   intake: intake.init(),
- *   // in `update`, on the inbound-webhook Msg:
- *   const [next, cmds] = intake.receive(state.intake, payload, at, id);
- *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.
- *   // on the worker's done Msg:
- *   const [next, _] = intake.complete(state.intake, key, result, at);
- *   // once, after boot (DO reload), before resuming the drain:
- *   const [next, _] = intake.boot(state.intake);
- *
- * Escape hatch: reach the raw L1 ops via `@demlik/tea/idempotency` and
- * `@demlik/tea/work-queue` and thread them by hand.
- */
-
-/**
- * A cached intake entry: either a key whose work is still in flight
- * (`pending`) or one whose work has finished and whose `result` is held for
- * replay to later duplicates (`done`). Discriminated on `phase` — `pending`
- * carries no payload, `done` carries the result `R`.
- *
- * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).
- * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.
- */
-type IntakeEntry<R> = {
-    readonly phase: "pending";
-} | {
-    readonly phase: "done";
-    readonly result: R;
-};
-/**
- * The intake knob's config — `keyOf` derives the idempotency key from a
- * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook
- * replayed long after the work finished is treated as new and re-processed.
- *
- * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry
- * (work still in flight) NEVER ages out, no matter how slow the worker is —
- * ageing a pending key would let the duplicate re-enqueue the in-flight
- * payload and double-process it. Only a `done` entry expires, measured from
- * the `at` passed to `complete` (the moment the result was cached). Inside the
- * window a duplicate replays the cached result; at/after the window it is
- * re-accepted and re-processed.
- *
- * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live
- * forever — fine for a bounded universe of ids, unbounded growth otherwise).
- *
- * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the
- * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake
- * keeps the store TTL-free and applies the phase-aware rule itself (see
- * `liveEntry`).
- */
-interface IntakeConfig<P> {
-    /** Derive the idempotency key from a payload. Must be pure + deterministic. */
-    readonly keyOf: (payload: P) => string;
-    /**
-     * Age a *completed* key out after this many ms, measured from the `at`
-     * passed to `complete`. Pending keys never age out.
-     */
-    readonly ttlMs?: number;
-}
-/**
- * The Model slice this knob owns. `seen` is the dedupe + last-result cache
- * (the `../idempotency` brick); `queue` is the pending-work list (the
- * `../work-queue` brick). Both are plain serializable values — the whole slice
- * round-trips through `JSON` so it survives eviction and replays exactly.
- */
-interface IntakeState<P, R> {
-    readonly seen: IdempotencyStore<IntakeEntry<R>>;
-    readonly queue: readonly QueueItem<P>[];
-}
-/** A genuinely-new payload was accepted and enqueued — go run the work. */
-interface IntakeProcessCmd<P> extends Cmd<"intake:process"> {
-    /** The dedupe key the payload was filed under. */
-    readonly key: string;
-    /** The enqueued queue-item id (the same `id` passed to `receive`). */
-    readonly itemId: string;
-    /** The original payload, for the worker to process. */
-    readonly payload: P;
-}
-/**
- * A duplicate of an already-completed key arrived — replay the cached result
- * to the caller instead of re-running the side effect.
- */
-interface IntakeReplayCmd<R> extends Cmd<"intake:replay"> {
-    /** The dedupe key whose cached result is being replayed. */
-    readonly key: string;
-    /** The result the ORIGINAL request produced, recalled from the cache. */
-    readonly result: R;
-}
-/** The Cmd union the intake verbs emit. */
-type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;
-/**
- * Build an idempotent-intake knob from `config`. Returns the uniform L2
- * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).
- * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the
- * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the
- * responder that runs `IntakeReplay` live in the host's interpret map).
- */
-declare function createIntake<P, R>(config: IntakeConfig<P>): {
-    init: () => IntakeState<P, R>;
-    receive: (state: IntakeState<P, R>, payload: P, at: number, id: string) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    complete: (state: IntakeState<P, R>, key: string, result: R, at: number) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    boot: (state: IntakeState<P, R>) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
-    claimNext: (state: IntakeState<P, R>, at: number) => {
-        readonly state: IntakeState<P, R>;
-        readonly claimed: QueueItem<P>;
-    } | null;
-};
-
-export { type IntakeCmd, type IntakeConfig, type IntakeEntry, type IntakeProcessCmd, type IntakeReplayCmd, type IntakeState, createIntake };

package/dist/idempotent-intake/index.js

@@ -1,7 +0,0 @@
-export { createIntake } from '../chunk-ZVJZ72HY.js';
-import '../chunk-BYQUGDD3.js';
-import '../chunk-K575PT4S.js';
-import '../chunk-MU6MCIAC.js';
-import '../chunk-FV3Z5MBE.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/idempotent-intake/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/journal/index.d.ts

@@ -1,373 +0,0 @@
-/**
- * journal sync — a remote journal and per-remote cursors, so two local journals
- * meet in one order.
- *
- * `Journal<R>` (`./index`) is the LOCAL append-only log a single machine replays
- * from. This is the second half: a **remote** journal that many local journals
- * push their appends into and pull everyone else's out of, with the remote
- * assigning the one `seq` that counts. Records are append-only, so there is
- * nothing to merge — the fold over the remote's order *is* the merge. This is
- * the network-in-the-middle twin of the append-then-fold shape already proven
- * in-repo by `src/do/event-sourced-store.ts` (append each record to a
- * monotonically-keyed log; rebuild state by folding the log via `replay`).
- *
- * The three moving parts:
- *   - `RemoteJournal<R>` — the append-only remote. `push` sends the records a
- *     client has not yet had acked and gets back the `seq` the remote assigned
- *     each; `pull` reads everyone's records after a given `seq`. One monotonic
- *     `seq` per stream, assigned by the remote, is the whole ordering contract.
- *   - a per-`(client, stream)` **cursor** (`CursorStore`) kept locally — the
- *     last remote `seq` a client has pulled — so `push`/`pull` resume
- *     incrementally instead of re-sending or re-reading the whole stream.
- *   - `SyncClient<R>` — a local `Journal<R>` joined to a `RemoteJournal<R>`
- *     through that cursor and a stable author identity. A local `append` is
- *     PROVISIONAL (it has a local order but no remote `seq`) until `sync` pushes
- *     it and pulls it back under the `seq` the remote assigned.
- *
- * Domain-blind and auth-blind: the remote takes an opaque `token` and an opaque
- * `stream` key and does nothing with the token — who-may-push-to-which-stream is
- * the host's concern, not this primitive's (the same way the local `Journal` is
- * blind to what a record means). Interface shape follows Effect
- * `unstable/eventlog` `EventJournal` (`writeFromRemote`, per-remote cursors, a
- * `changes` stream) as prior art, not a dependency.
- */
-
-/**
- * A remote-assigned order key. Like a local `Seq` it starts at 1 and increments
- * by one per record within a stream, but it is assigned by the REMOTE — it is
- * the authoritative order every client folds over, not any one client's local
- * append order.
- */
-type RemoteSeq = number;
-/**
- * A record paired with the stable identity of whoever authored it. Author
- * identity is the one fact a team-mode record needs that a solo record does not:
- * once records from many clients interleave in the remote's order, the fold
- * still has to know who wrote each. It is opaque — a string the host assigns
- * meaning to (a device id, a user handle) — never interpreted here.
- */
-interface AuthoredRecord<R> {
-    /** The stable identity of the client that authored `record`. */
-    readonly author: string;
-    /** The domain record itself; this primitive knows nothing of its shape. */
-    readonly record: R;
-}
-/**
- * One record as it lives on the remote: the `seq` the remote assigned, the
- * `author` that wrote it, the `stream` it belongs to, and the record. This is
- * the entry every client pulls and folds; two clients that pull the same stream
- * see identical `RemoteEntry`s in identical `seq` order, which is what lets
- * their folds agree.
- */
-interface RemoteEntry<R> {
-    /** The stream this entry belongs to. */
-    readonly stream: string;
-    /** The remote-assigned order key — 1-based, gap-free, monotonic per stream. */
-    readonly seq: RemoteSeq;
-    /** The stable identity of the client that authored the record. */
-    readonly author: string;
-    /** The domain record. */
-    readonly record: R;
-}
-/** A `push` — the records a client wants acked, presented under its token. */
-interface PushRequest<R> {
-    /**
-     * An opaque credential the host's remote may check. This primitive does
-     * nothing with it: authorization (who may push to which stream) is the host's
-     * concern, deliberately out of scope here.
-     */
-    readonly token: unknown;
-    /** The opaque stream key to append to. */
-    readonly stream: string;
-    /**
-     * The records to append, in the client's local order. Normally these are the
-     * client's own appends made since its last successful push — the incremental
-     * tail, not the whole stream.
-     */
-    readonly records: ReadonlyArray<AuthoredRecord<R>>;
-}
-/** The remote's answer to a `push`: the `seq` it assigned each record, in order. */
-interface PushResult {
-    /**
-     * The remote `seq` assigned to each record of the request, in the same order.
-     * `seqs[i]` is the seq of `records[i]`. A client does not need to fold these —
-     * it learns the full ordered stream (its own records included) through `pull`,
-     * which is the single reader of converged state.
-     */
-    readonly seqs: ReadonlyArray<RemoteSeq>;
-}
-/** A `pull` — read everyone's records after a `seq` the client already has. */
-interface PullRequest {
-    /** The opaque credential; ignored here, see {@link PushRequest.token}. */
-    readonly token: unknown;
-    /** The opaque stream key to read. */
-    readonly stream: string;
-    /**
-     * Return only entries with `seq` strictly greater than this. A client passes
-     * its cursor (the last `seq` it pulled), so it reads only what is new — never
-     * re-reading the whole stream. `0` (the cursor's initial value) reads from the
-     * start.
-     */
-    readonly since: RemoteSeq;
-}
-/** The remote's answer to a `pull`: the new entries, in `seq` order. */
-interface PullResult<R> {
-    /** Every entry with `seq > since`, in ascending `seq` order. */
-    readonly entries: ReadonlyArray<RemoteEntry<R>>;
-}
-/**
- * An append-only remote journal: many clients push into it, all pull from it,
- * and it assigns the one monotonic `seq` per stream that every client's fold
- * agrees over. It is the network-in-the-middle: a real one is a server; this
- * interface is what a client talks to, host- and transport-blind.
- *
- * The remote never merges and never resolves conflicts — records are
- * append-only, so its only job is to assign an honest total order. That order
- * is enough: two clients that both push and both pull fold the same sequence and
- * reach the same state (the append-then-fold result proven in phoenix spike
- * #6673, reused here rather than reinvented).
- */
-interface RemoteJournal<R> {
-    /**
-     * Append `records` to `stream` durably and return the `seq` assigned to each,
-     * in order. Concurrent pushes to one stream are serialised into a single total
-     * order — the seq assignment is the remote's whole ordering guarantee.
-     */
-    push(request: PushRequest<R>): Promise<PushResult>;
-    /**
-     * Read every entry of `stream` with `seq` strictly greater than
-     * `request.since`, in ascending `seq` order. Empty when the client is already
-     * caught up.
-     */
-    pull(request: PullRequest): Promise<PullResult<R>>;
-}
-/**
- * An in-memory `RemoteJournal<R>` — the standard test/reference substrate,
- * mirroring `memoryStore` (`@demlik/tea/mem`) and `memoryJournal` (`./index`).
- *
- * It is built ON `memoryJournal`: the remote's authoritative `seq` assignment IS
- * a local `Journal`'s per-stream total order. `push` appends each record under
- * the stream's lock (so concurrent pushes serialise into one order and never
- * race the seq), and `pull` is `list` filtered past the client's cursor. The
- * seq machinery is `makeJournal`'s, reused — this substrate reinvents none of
- * it, exactly as the issue's seam was designed to be consumed.
- *
- * The `token` is accepted and ignored: this substrate enforces no authorization,
- * because who-may-push-to-which-stream is the host's concern, out of scope here.
- */
-declare function memoryRemoteJournal<R>(): RemoteJournal<R>;
-/**
- * Where a client keeps its per-`(client, stream)` cursor — the last remote `seq`
- * it has pulled. Kept LOCALLY (the client's own disk/memory), never on the
- * remote, so `push`/`pull` resume incrementally after a restart instead of
- * re-reading the whole stream. `get` returns `0` for a stream never pulled.
- */
-interface CursorStore {
-    /** The last remote `seq` pulled for `stream`, or `0` if none yet. */
-    get(stream: string): Promise<RemoteSeq>;
-    /** Record `seq` as the last remote `seq` pulled for `stream`. */
-    set(stream: string, seq: RemoteSeq): Promise<void>;
-}
-/**
- * An in-memory `CursorStore`, mirroring `memoryStore`. A durable client swaps in
- * a file- or DB-backed one so its cursor survives a restart; the semantics are
- * identical.
- */
-declare function memoryCursorStore(): CursorStore;
-/** How to build a {@link SyncClient}. */
-interface SyncClientOptions<R> {
-    /** The remote every push/pull talks to. */
-    readonly remote: RemoteJournal<R>;
-    /**
-     * This client's stable author identity, stamped on every record it appends —
-     * the one fact team mode needs that solo mode does not.
-     */
-    readonly author: string;
-    /**
-     * The opaque credential presented on every push/pull. Optional because this
-     * primitive never checks it; a host that runs an authorizing remote supplies
-     * it here.
-     */
-    readonly token?: unknown;
-    /**
-     * The client's LOCAL append-only journal — its own provisional appends live
-     * here. Defaults to a `memoryJournal`; a durable client passes a `fileJournal`
-     * (or any `Journal<R>`), which is the #30 substrate seam this consumes.
-     */
-    readonly local?: LocalJournal<R>;
-    /**
-     * Where the per-stream pull cursor lives. Defaults to a `memoryCursorStore`; a
-     * durable client passes one backed by its own storage.
-     */
-    readonly cursors?: CursorStore;
-}
-/**
- * The slice of a local `Journal<R>` a `SyncClient` drives — its own provisional
- * appends and reading them back in local order. This is structurally the #30
- * `Journal<R>` interface narrowed to what sync needs, so a `memoryJournal` or a
- * `fileJournal` satisfies it as-is.
- */
-interface LocalJournal<R> {
-    append(stream: string, record: R): Promise<{
-        seq: number;
-    }>;
-    list(stream: string): Promise<ReadonlyArray<JournalEntry<R>>>;
-}
-/**
- * A local `Journal` joined to a `RemoteJournal` through a cursor and an author
- * identity. It is what makes two local journals "meet in one order": each
- * appends offline, both `sync`, and both converge on the remote's order.
- */
-interface SyncClient<R> {
-    /**
-     * Append `record` to the client's LOCAL journal. The append is PROVISIONAL: it
-     * has a local order immediately, but no remote `seq` — and so no place in the
-     * converged order — until a later `sync` pushes it and pulls it back. Resolves
-     * once the local append is durable.
-     */
-    append(stream: string, record: R): Promise<void>;
-    /**
-     * The client's local appends for `stream` that have not yet been pushed — the
-     * provisional tail. Empty right after a successful `sync`.
-     */
-    pending(stream: string): Promise<ReadonlyArray<AuthoredRecord<R>>>;
-    /**
-     * Reconcile `stream` with the remote: PUSH every local append not yet pushed,
-     * then PULL every remote entry after the cursor and fold it into the converged
-     * log, advancing the cursor. One `sync` may not see records a peer pushes
-     * concurrently (they may land after this pull); a second `sync` — with nothing
-     * new to push — pulls them, which is how two racing clients converge.
-     */
-    sync(stream: string): Promise<void>;
-    /**
-     * The converged log for `stream`: every entry the client has pulled, in remote
-     * `seq` order. This is the fold's input — reducing over it yields the client's
-     * state. After both of two racing clients sync to quiescence, their `log`s are
-     * identical, which is the convergence guarantee.
-     */
-    log(stream: string): ReadonlyArray<RemoteEntry<R>>;
-}
-/**
- * Build a {@link SyncClient} over a remote, an author identity, and (optionally)
- * a local journal and cursor store.
- *
- * The client holds two watermarks per stream: how many of its own local appends
- * it has PUSHED (so a re-`sync` sends only the new tail), and — in the
- * `CursorStore` — the last remote `seq` it has PULLED (so it reads only what is
- * new). Its converged `log` is built solely from `pull`, so `pull` is the single
- * source of converged truth; a client learns even its OWN records' remote order
- * by pulling them back.
- */
-declare function makeSyncClient<R>(options: SyncClientOptions<R>): SyncClient<R>;
-
-/**
- * @packageDocumentation
- * @demlik/tea/journal — an append-only, ordered record log for `@demlik/tea`.
- *
- * The log a "durable, replayable state machine" replays from. tea already ships
- * the log's neighbours — `fileStore`/`memoryStore` (`Store<S>`: snapshot with
- * whole-load / whole-save), `recorder` (JSONL debug traces), `durable-effects`
- * (`foldLedger` over an owed-effect ledger) — but not the log itself, so every
- * consumer hand-rolled it. This is that log, domain-blind: a `Journal<R>` over
- * an opaque record `R`, with no pipeline/ledger vocabulary of its own.
- *
- * Three operations carry the contract:
- *   - `append(stream, record)` — durable before it returns, assigning a
- *     per-stream total-order `seq` (1, 2, 3, …). Concurrent appenders to one
- *     stream converge on one order; the lock's only job is an honest order key.
- *   - `list(stream)` — every entry of a stream in `seq` order.
- *   - `changes(listener)` — a subscription over appends made through this
- *     instance after subscribing.
- *
- * `withLock(stream, fx)` runs `fx` with exclusive access to a stream, so a
- * read-decide-append sequence is atomic against other writers. It is
- * re-entrant for the same stream: an `append` inside `fx` does not deadlock on
- * the lock `fx` already holds.
- *
- * The substrate is a `JournalBackend<R>` — how a stream is read, how one record
- * is appended durably, and how a stream is locked across processes.
- * `makeJournal` wires the domain-blind orchestration (per-stream serialisation,
- * `seq` assignment, `changes` fan-out) over any backend. `memoryJournal` is the
- * in-process backend that mirrors `memoryStore` for tests; the Node file
- * backend (`fileJournal`) homes in `@demlik/tea/node` beside `fileStore`.
- *
- * Interface shape follows Effect `unstable/eventlog` `EventJournal`
- * (`entries`/`write`/`changes`/`withLock`) as prior art, not a dependency.
- */
-/** A per-stream total-order key. Starts at 1 and increments by one per append. */
-type Seq = number;
-/** One appended record, tagged with its stream and its per-stream `seq`. */
-interface JournalEntry<R> {
-    readonly stream: string;
-    readonly seq: Seq;
-    readonly record: R;
-}
-/**
- * An append-only, ordered record log over an opaque record `R`.
- *
- * Domain-blind: it knows nothing of what a record means. Ordering, durability
- * and the honest order key are its whole contract.
- */
-interface Journal<R> {
-    /**
-     * Append `record` to `stream`, durable before the promise resolves, and
-     * resolve with the `seq` it was assigned — the next integer in the stream's
-     * total order.
-     */
-    append(stream: string, record: R): Promise<{
-        seq: Seq;
-    }>;
-    /** Every entry of `stream`, in `seq` order. Empty for an unwritten stream. */
-    list(stream: string): Promise<ReadonlyArray<JournalEntry<R>>>;
-    /**
-     * Subscribe to appends made through this instance after this call. Returns an
-     * unsubscribe. Cross-process appends are not delivered — a cross-process
-     * subscription is a polling concern this log leaves to its consumer.
-     */
-    changes(listener: (entry: JournalEntry<R>) => void): () => void;
-    /**
-     * Run `fx` with exclusive access to `stream` — the in-process mutex against
-     * other callers here, the backend lock against other processes. Re-entrant
-     * for the same stream, so an `append` (or nested `withLock`) inside `fx` runs
-     * under the lock this call already holds rather than deadlocking on it.
-     */
-    withLock<A>(stream: string, fx: () => Promise<A>): Promise<A>;
-}
-/**
- * The substrate a `Journal<R>` is built over. Everything host-specific lives
- * here; `makeJournal` owns the host-blind rest.
- *
- * `append` is always invoked under `lock` for the same stream, so a backend
- * assigns `seq` from `read().length + 1` without racing itself.
- */
-interface JournalBackend<R> {
-    /** Every entry of `stream` in `seq` order; empty for an unwritten stream. */
-    read(stream: string): Promise<ReadonlyArray<JournalEntry<R>>>;
-    /**
-     * Persist `record` as the next entry of `stream`, durable before resolving,
-     * and resolve with the entry it wrote. Invoked only while `lock` holds the
-     * stream, so `seq` is safely the current length plus one.
-     */
-    append(stream: string, record: R): Promise<JournalEntry<R>>;
-    /** Run `fx` while holding `stream`'s cross-process lock. */
-    lock<A>(stream: string, fx: () => Promise<A>): Promise<A>;
-}
-/**
- * Build a `Journal<R>` over `backend`. Owns the host-blind half: per-stream
- * serialisation, re-entrant exclusion, and the `changes` fan-out. `append` and
- * `withLock` both route through `exclusive`, which holds the in-process mutex
- * and the backend lock for one stream and is re-entrant for that stream within
- * a single call chain.
- */
-declare function makeJournal<R>(backend: JournalBackend<R>): Journal<R>;
-/**
- * An in-process `Journal<R>` — the standard test substrate, mirroring
- * `memoryStore` from `@demlik/tea/mem`. Reference semantics: a record handed to
- * `append` is stored by reference, exactly as `memoryStore` stores state. No
- * cross-process lock is needed — a single process owns the whole log — so the
- * backend lock is identity and `makeJournal`'s in-process mutex is the only
- * ordering guarantee.
- */
-declare function memoryJournal<R>(): Journal<R>;
-
-export { type AuthoredRecord, type CursorStore, type Journal, type JournalBackend, type JournalEntry, type LocalJournal, type PullRequest, type PullResult, type PushRequest, type PushResult, type RemoteEntry, type RemoteJournal, type RemoteSeq, type Seq, type SyncClient, type SyncClientOptions, makeJournal, makeSyncClient, memoryCursorStore, memoryJournal, memoryRemoteJournal };

package/dist/journal/index.js

@@ -1,3 +0,0 @@
-export { makeJournal, makeSyncClient, memoryCursorStore, memoryJournal, memoryRemoteJournal } from '../chunk-XGELA764.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/journal/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}