@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/journal/journal.d.ts

@@ -0,0 +1,475 @@
+import type { JournalEventInput, JournalEventType, JournalEvent, Seq, ThreadSummary } from '../models/index.js';
+import { type JsonValue } from '../util/json.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { CoreFold, PluginProjection, Projection } from './projection.js';
+import { type Origins } from './catalog.js';
+import type { JournalStore } from './store.js';
+export type AppendOptions = {
+    /** The thread the event belongs to; every row has one. */
+    threadId: string;
+    /** Earlier events this one answers — a `tool/result` cites the `tool/call` it completes. */
+    sourceSeqs?: readonly Seq[];
+};
+/**
+ * What a `transact` builder returns: the group's rows and a `value` for the writer. The value is
+ * observable only through the write's result, so only once the group is durable, an empty group
+ * included.
+ */
+export type Transaction<K extends JournalEventType, T> = {
+    readonly rows: readonly AppendEntry<K>[];
+    readonly value: T;
+};
+/** What a `transact` settles with: the events the group wrote and the builder's value. */
+export type Committed<K extends JournalEventType, T> = {
+    readonly events: JournalEvent<K>[];
+    readonly value: T;
+};
+/** One row to append as part of an atomic group; see {@link Journal.appendAll}. */
+export type AppendEntry<K extends JournalEventType = JournalEventType> = {
+    [T in K]: {
+        type: T;
+        data: JournalEventInput[T];
+        options: AppendOptions;
+    };
+}[K];
+/**
+ * The journal as a plugin holds it, `ctx.journal`: its reads, and writes of `ext` rows only. Core
+ * rows are the engine's, written by its own operations, which judge them; a core row a plugin wrote
+ * past this type is unsupported history. Listed, not derived, so a method the journal gains is not
+ * plugin API by default; loading and unloading threads is `ctx.threads.retain`'s.
+ */
+export interface PluginJournal extends Pick<Journal, 'head' | 'summary' | 'summaries' | 'summaryMap' | 'origins' | 'flush' | 'hold' | 'isLoaded' | 'loadedThreads' | 'eventAt' | 'readRow' | 'rows' | 'rowsAfter' | 'lineage' | 'inLineage' | 'subscribe'> {
+    /**
+     * Registers a plugin's fold and catches it up on every loaded thread; idempotent per projection.
+     * The returned function removes it, and only the registration that added it.
+     */
+    register<S>(fold: PluginProjection<S>): () => void;
+    /**
+     * A fold's state on `threadId`, as a read-only view of plain data. A plugin's own projection is
+     * registered by its first read, so its state never goes stale; a {@link CoreFold} is core's, always
+     * registered already, and can be read but not made or registered here. A fold that failed throws
+     * {@link ProjectionFailedError}; a thread that is in the catalog but not loaded throws
+     * {@link ThreadNotLoadedError}.
+     */
+    state<S>(fold: PluginProjection<S> | CoreFold<S>, threadId: string): ReadonlyState<S>;
+    /**
+     * A fold's state as it stood at `seq` on `threadId`'s lineage, folded fresh: nothing is
+     * registered, and the same read-only view as {@link state}.
+     */
+    stateAt<S>(fold: Pick<Projection<S>, 'init' | 'apply'>, threadId: string, seq: Seq): ReadonlyState<S>;
+    append(type: 'ext', data: JournalEventInput['ext'], options: AppendOptions): Promise<JournalEvent<'ext'>>;
+    appendAll(entries: readonly AppendEntry<'ext'>[]): Promise<JournalEvent<'ext'>[]>;
+    transact<T>(threadId: string, build: () => Transaction<'ext', T>): Promise<Committed<'ext', T>>;
+}
+/** A thread's summary before the contributions the journal adds to it; see {@link Summarizer}. */
+export type ThreadSummaryCore = Omit<ThreadSummary, 'contributions'>;
+/**
+ * Computes a thread's summary from its folds, once a group is durable and folded. Registered once,
+ * by whoever knows the folds — the loop — since the journal knows only the shape.
+ */
+export type Summarizer = (journal: Journal, threadId: string) => ThreadSummaryCore;
+/**
+ * What a plugin or host adds to a thread's summary: a pure function of the thread's folds, read
+ * through the journal, computed with the summary's core fields at each group. `undefined`
+ * contributes nothing for that thread. A plugin does not write one: `defineContribution` is the
+ * door, which owns the cache entry's shape.
+ */
+export type Contributor = (threadId: string, core: ThreadSummaryCore) => JsonValue | undefined;
+export type ContributeOptions = {
+    /**
+     * Which summaries registration refreshes: those it says need their entry computed again. The ones
+     * without the key when omitted.
+     */
+    refresh?: (summary: ThreadSummary) => boolean;
+};
+/** A registered contributor; see {@link Journal.contribute}. */
+export type Contribution = {
+    /** Withdraws the contributor: summaries written from then on are computed without it. */
+    readonly withdraw: () => void;
+    /**
+     * The refresh registration queued: resolves with the threads whose repair failed, which keep a
+     * summary without the key; rejects if the refresh could not run at all, which the journal reports
+     * too, unless it was refusing writes.
+     */
+    readonly refreshed: Promise<string[]>;
+};
+export type JournalOptions = {
+    summarize: Summarizer;
+    /**
+     * Where a throwing subscriber or contributor goes. Subscribers are isolated: appending is how
+     * the engine records what happened, so it cannot be at the mercy of who is watching.
+     */
+    onListenerError?: (error: unknown) => void;
+    /**
+     * Core's folds: the only `fatal` projections the journal accepts, registered here, before it
+     * opens, and never removed. A plugin's fold isolates, so `register` and `state` refuse a `fatal`
+     * one that is not among these, by identity.
+     */
+    coreFolds: readonly CoreFold<unknown>[];
+};
+/**
+ * The append-only journal, the folds over it, and the catalog of its threads.
+ *
+ * Everything the loop needs to resume is a projection of these events, never a snapshot beside
+ * them (`docs/architecture.md#state-and-lifetimes`).
+ *
+ * **Writes** go through one queue. `transact(threadId, build)` runs `build` once every earlier write
+ * has landed and been folded, synchronously, against durable state, and appends what it returns in
+ * the same slot: the rows go to the store as one attempt, and only once the store has them are they
+ * folded, summarized and published. Folds therefore hold only durable rows. `appendAll` and `append`
+ * are `transact` with a constant callback. A store failure is fatal: the journal revokes writes and
+ * tells `onRevoked` listeners, and the owner exits. The one exception is the summary written after
+ * a group: the catalog is a cache, so that failure is reported and the next write catches it up.
+ * A lost writer is fatal there too.
+ *
+ * **Reads** are synchronous over the **working set**: `load(threadId)` reads a thread's lineage
+ * from the store and folds it, and `unload()` drops it. A thread the catalog holds that is not
+ * loaded throws {@link ThreadNotLoadedError} on a synchronous read rather than reading the store
+ * behind the caller's back. Opening reads the head, the **catalog** of one summary per thread, and
+ * the store's thread index, which together answer listing, lineage and recovery questions without a
+ * row in memory. Rows are frozen as they enter memory, from an append or a load, and summaries as
+ * the catalog takes them, so a read hands out the journal's own and copies nothing.
+ *
+ * A thread may be a fork: its thread-scoped state is the fold over its **lineage**, the source's up
+ * to the row its spawn row names, then its own rows (`docs/forks.md`). Seqs are global, so one bound
+ * applies at every hop of a fork of a fork.
+ *
+ * The journal parses what it is given and writes it. A row whose meaning depends on the state it
+ * lands on is judged by whoever writes it, inside its `transact` callback, against durable state.
+ */
+export declare class Journal {
+    private readonly projections;
+    /** Core's folds, as the constructor took them: the only `fatal` projections that may be registered. */
+    private readonly coreFolds;
+    /** Fold state by thread, then projection key: unloading a thread drops its inner map. */
+    private readonly states;
+    private readonly failures;
+    /** Failures and contribution errors found during a write, reported once it is done. */
+    private readonly pendingReports;
+    /** Threads whose summary is current in memory but whose catalog write failed: the next write carries them. */
+    private readonly dirty;
+    private readonly listeners;
+    private readonly revokedListeners;
+    private readonly contributors;
+    /** The catalog: one summary per thread the store holds, in spawn order. */
+    private readonly catalog;
+    /** The working set: each loaded thread's own rows, in seq order. */
+    private readonly loaded;
+    /** Loads in flight, shared by everyone who asks for the same thread meanwhile. */
+    private readonly loading;
+    /** Row reads in flight, one per thread, shared by every load that needs that thread's rows. */
+    private readonly rowReads;
+    /** Bumped by every drop of a thread: a row read that started before one is read again. */
+    private readonly generations;
+    /** Every loaded row by seq, for lookups that name a row without its thread. */
+    private readonly bySeq;
+    /**
+     * Threads that must stay loaded, counted: a write in flight holds its thread and a new fork's
+     * source, and a host holds what a running thread reads (see {@link hold}).
+     */
+    private readonly holds;
+    /** The threads whose registered folds hold their state. */
+    private readonly folded;
+    private readonly summarizer;
+    private readonly onListenerError;
+    private lease;
+    private ownsStore;
+    private seq;
+    private writable;
+    /** The failure that revoked writes, when one did; an orderly `revokeWrites()` leaves none. */
+    private revokedBy;
+    /** The tail of the write queue; every write and every catalog rebuild waits for it. */
+    private queue;
+    /** Whether a write is under way, during which reports wait. */
+    private writing;
+    /** Set by `close()`: writes already queued land, and new ones are refused. */
+    private closing;
+    readonly store: JournalStore;
+    constructor(store: JournalStore, options: JournalOptions);
+    /** Refuses every later append: the journal is closing. */
+    revokeWrites(): void;
+    /**
+     * Called once if the journal can no longer trust what it holds (see {@link JournalCommitError}):
+     * it has already refused every later write, and the owner must exit. Returns the function that
+     * stops listening.
+     */
+    onRevoked(listener: (error: JournalCommitError) => void): () => void;
+    /**
+     * Takes the store's writer lease, opens the store if it is not open — and then owns it — and reads
+     * the head, the catalog and the thread index: nothing else. A summary the index shows trailing its
+     * thread's rows — written before a crash took the summary's own write — is refreshed from the
+     * rows, a missing one added and one with no thread dropped, before anything reads the catalog. No
+     * contributor is registered yet, so those summaries carry no contributions until one registers.
+     */
+    open(): Promise<void>;
+    /**
+     * Refuses new writes, lets every write already queued land, then releases the lease and closes the
+     * store if the journal opened it.
+     */
+    close(): Promise<void>;
+    get head(): Seq;
+    /** One thread's summary, or `undefined` for a thread the journal does not hold. */
+    summary(threadId: string): ThreadSummary | undefined;
+    /** Every thread's summary, in spawn order. */
+    summaries(): ThreadSummary[];
+    /** The summaries by thread id: what a walk over forks reads; origins have `origins`. */
+    summaryMap(): ReadonlyMap<string, ThreadSummary>;
+    /**
+     * The origin tree of the catalog's threads: callers, subtrees and required owners, loading nothing,
+     * and the one rule for a cited source row, which reads that row alone.
+     */
+    readonly origins: Origins;
+    /**
+     * Adds to every thread's summary under `key`, computed with the summary at each group from then
+     * on. A contributor that throws contributes nothing to that summary and is reported; the group
+     * lands.
+     *
+     * Registering also refreshes the summaries `options.refresh` names — by default those written
+     * without the key, by a composition that did not register it or by a repair, which never carries
+     * a contribution it cannot compute: one queued task that reads the store's thread index as it
+     * starts, repairs those threads from their rows, the lineage they fold through included, and
+     * unloads what it loaded unless something holds it. Nothing else recomputes an earlier summary
+     * but `rebuildCatalog()`. A contributor that answers for every thread `refresh` names is
+     * refreshed once.
+     */
+    contribute(key: string, contributor: Contributor, options?: ContributeOptions): Contribution;
+    /**
+     * Recomputes every thread's summary from its rows and replaces the catalog wholesale, in the
+     * store and in memory, in spawn order: what repairs a catalog from scratch. It waits its turn in
+     * the write queue and loads every thread meanwhile, unloading those it loaded after, so it is
+     * maintenance for a journal nothing else is using. A contribution whose contributor is not
+     * registered now is left out, also from the summary a thread keeps when its folds cannot take its
+     * rows. If the store fails, the previous catalog stays.
+     */
+    rebuildCatalog(): Promise<void>;
+    /**
+     * Recomputes the summaries of `refresh` from their rows, with the contributors registered now,
+     * and writes them — wholesale when `replace`, which also drops summaries of threads the index does
+     * not hold. Everything it loads is unloaded after, unless something holds it; a failure leaves the
+     * previous catalog, in memory and in the store. Returns the threads whose rows their folds could
+     * not take: each keeps the summary it had, less the contributions no registered contributor
+     * computed, and is reported.
+     */
+    private repair;
+    /** `summary` keeping only the contributions whose contributor is registered now. */
+    private withRegisteredContributions;
+    /** Refuses a write once the journal has been revoked or is closing. */
+    private requireWritable;
+    /** The threads whose rows and folds are in memory. */
+    loadedThreads(): string[];
+    /**
+     * Resolves once every write queued before the call has landed: what a reader awaits before it
+     * decides from the folds, so a `send()` it did not await is seen.
+     */
+    flush(): Promise<void>;
+    /**
+     * Keeps threads loaded until the returned function is called: `unload` leaves a held thread, and
+     * any thread whose lineage runs through it, where it is. What a running thread reads — its lineage
+     * and its callers — is held for the run. Counted, so holds overlap.
+     */
+    hold(threadIds: readonly string[]): () => void;
+    /**
+     * Loads a thread's lineage — its own rows and those of the threads it was forked from — and folds
+     * it, so the synchronous reads can answer for it. Idempotent; a load in flight is shared. A thread
+     * the catalog does not hold has nothing to load. A load that fails leaves nothing behind.
+     */
+    load(threadId: string): Promise<void>;
+    /** Whether a thread's rows and folds are in memory, so the synchronous reads answer for it. */
+    isLoaded(threadId: string): boolean;
+    /**
+     * Drops a thread's rows and folds from memory; `load()` reads them again. The catalog entry
+     * stays. Every loaded thread whose lineage runs through it is dropped too, since its folds would
+     * otherwise be read over rows no longer in memory. A held thread stays (see {@link hold}), and so
+     * does one a held thread's lineage runs through; returns whether it went.
+     */
+    unload(threadId: string): boolean;
+    private drop;
+    /**
+     * The row at `seq`, whichever thread it belongs to, from the working set. A row of a thread that is
+     * not loaded throws {@link RowNotLoadedError}; `readRow` reads it from the store.
+     */
+    eventAt(seq: Seq): JournalEvent | undefined;
+    /** The row at `seq` from the working set, or else from the store. */
+    readRow(seq: Seq): Promise<JournalEvent | undefined>;
+    /** One thread's own rows, in order, up to and including `upTo`. Never the rows a fork inherits. */
+    rows(threadId: string, upTo?: Seq): readonly JournalEvent[];
+    /** One thread's own rows after `seq`, in order: found by binary search rather than a scan. */
+    rowsAfter(threadId: string, seq: Seq): readonly JournalEvent[];
+    /**
+     * The rows a thread's state folds, up to and including `upTo`: for a fork, its source's lineage
+     * up to the fork point, then its own rows. Every row keeps its original thread id and seq, and
+     * the whole is in seq order.
+     */
+    lineage(threadId: string, upTo?: Seq): JournalEvent[];
+    /** Whether `event` is part of `threadId`'s lineage: its own row, or one it inherits. */
+    inLineage(threadId: string, event: JournalEvent): boolean;
+    /**
+     * A thread projection's state as it stood at `seq` on `threadId`'s lineage, folded fresh. For
+     * questions about the past, such as whether a row can be forked at; the live state is `state()`.
+     * The second signature is {@link PluginJournal.stateAt}'s, for the same reason as `state()`'s.
+     */
+    stateAt<S>(fold: Pick<Projection<S>, 'init' | 'apply'>, threadId: string, seq: Seq): S;
+    stateAt<S>(fold: Pick<Projection<S>, 'init' | 'apply'>, threadId: string, seq: Seq): ReadonlyState<S>;
+    /**
+     * The threads whose rows make up `threadId`'s lineage up to `upTo`, from the thread itself out to
+     * its root. A fork is followed only once its spawn row is within the bound; each hop's bound is
+     * then below that spawn row, so the walk always ends.
+     */
+    private hops;
+    /**
+     * A thread's spawn row's seq and fork: from the catalog, or from its loaded rows — while its first
+     * group is landing, or during a repair, which reads a thread's rows before it asks.
+     */
+    private spawnOf;
+    /**
+     * The thread's own rows. A thread the catalog does not hold has none; one it holds must be loaded,
+     * so a read never reaches the store behind the caller's back.
+     */
+    private own;
+    /**
+     * Reads a thread's rows from the store into the working set, unless they are there already. One
+     * read per thread is in flight at a time, shared by everyone who needs it; a read that a drop of
+     * the thread overtook is read again, so rows read before a write and an eviction are never
+     * installed after them.
+     */
+    private loadRows;
+    private readRows;
+    /** The index of the first row in `rows` (sorted by seq) whose seq is above `seq`. */
+    private firstAfter;
+    /** Records one event through the same atomic path as a group. */
+    append<K extends JournalEventType>(type: K, data: JournalEventInput[K], options: AppendOptions): Promise<JournalEvent<K>>;
+    /** Records several events of one thread as one unit; see {@link transact}. */
+    appendAll<K extends JournalEventType>(entries: readonly AppendEntry<K>[]): Promise<JournalEvent<K>[]>;
+    /**
+     * Appends the rows `build` returns to `threadId` as one group, `build` running in the write queue —
+     * after every earlier write has landed and been folded, synchronously, against durable state —
+     * so a write that depends on what it reads is atomic. `build` loads nothing and awaits nothing:
+     * the thread is loaded before it runs. An empty group writes nothing. The `value` it returns
+     * comes back with the events once the group is durable, an empty group included, so what the
+     * writer learned inside the write needs no variable outside it.
+     *
+     * A `build` that throws writes nothing, and its error is the write's: a writer that judges what it
+     * appends refuses there. A thread begins with its spawn row and has one: a group on a thread the catalog does not hold must start with its one spawn row,
+     * and a group on a thread it holds may not carry one.
+     *
+     * The group goes to the store as one attempt. Once the store has it, its rows are folded, the
+     * thread's summary is computed and put in the catalog, the rows are published — the whole group
+     * folded before any row is published — and the summary is written to the store. A store that fails
+     * the append, or a core fold that cannot take rows the store holds, is a {@link JournalCommitError}:
+     * the journal refuses every later write with it as the cause, and `onRevoked` listeners are told
+     * once. A failed summary write is reported instead, unless the writer was lost: see
+     * {@link CatalogWriteError}.
+     */
+    transact<K extends JournalEventType, T>(threadId: string, build: () => Transaction<K, T>): Promise<Committed<K, T>>;
+    /** Runs `task` once every earlier write is done; a failed one does not stop the queue. */
+    private enqueue;
+    private write;
+    private writeHeld;
+    private commit;
+    private writer;
+    /** Revokes writes for good, tells every listener once, and returns the error to throw. */
+    private revoke;
+    /**
+     * The row as it is, already frozen. A listener that writes gets a promise back, and may return it:
+     * its failure is reported, never left unhandled, and never awaited inside the write that published.
+     */
+    private publish;
+    /**
+     * The thread's summary from its folds as they stand: core's fields, then every contribution,
+     * each checked to be JSON so what the store writes is what the catalog holds; one that is not, or
+     * that throws, is left out and reported once the write is done.
+     */
+    private summarize;
+    /** Subscribes to appended events; returns the unsubscribe function. */
+    subscribe(listener: (event: JournalEvent) => void): () => void;
+    /**
+     * Registers a fold and catches it up on every thread in the working set. Idempotent per
+     * projection. Every fold is thread-scoped: a question about the set of threads is answered from
+     * the catalog, and a plugin that wants its own answer there registers a contribution.
+     *
+     * Only the registration that added the fold removes it: the function a repeated registration
+     * returns does nothing, so reading a fold, which registers it, can never hand out a way to remove
+     * one that core keeps for the journal's life.
+     */
+    register<S>(projection: Projection<S>): () => void;
+    /**
+     * This projection's state on `threadId`. A thread the journal does not hold has the fold's initial
+     * state; one it holds must be loaded (see {@link load}), else {@link ThreadNotLoadedError}.
+     *
+     * Reading registers the fold: a state computed once and never updated again would go stale behind
+     * later appends, which is the one failure mode a projection must not have.
+     *
+     * A core fold is already registered, and reading it resolves that registration by identity; a
+     * `fatal` projection that is not one is refused, as `register` refuses it.
+     *
+     * The engine reads the state as its reducers hold it. The second signature is what a plugin's
+     * {@link PluginJournal.state} reads, so a `Journal` stands wherever a `PluginJournal` is wanted.
+     */
+    state<S>(projection: Projection<S>, threadId: string): S;
+    state<S>(projection: PluginProjection<S> | CoreFold<S>, threadId: string): ReadonlyState<S>;
+    /**
+     * Folds every registered projection over the thread's lineage, once its rows are loaded. A thread
+     * counts as folded only once every fold has taken it: a fatal fold that throws leaves nothing
+     * behind, so the next load tries again and fails the same way rather than reading an initial state
+     * as the thread's.
+     */
+    private ensureFolded;
+    /** Forgets every fold's state and failure on one thread. */
+    private dropStates;
+    /** One projection's state on one thread, folded fresh over its lineage. */
+    private foldLineage;
+    private fold;
+    private foldOne;
+    private failProjection;
+    /**
+     * Reports what folding and summarizing found, once no write is under way: an error observer may
+     * itself append to the journal, which queues behind the write.
+     */
+    private flushReports;
+    private reportError;
+}
+/**
+ * The journal can no longer trust what it holds: the store failed a write — which may or may not
+ * have landed — or a core fold could not take rows the store holds. The journal refuses every later
+ * append with this as the cause ({@link JournalRevokedError}); `Journal.onRevoked` listeners were
+ * told. The owner must exit; reopening reads the store as it is.
+ */
+export declare class JournalCommitError extends Error {
+    readonly threadId: string;
+    readonly cause: unknown;
+    constructor(threadId: string, cause: unknown);
+}
+/** An append after writes were revoked: by the journal closing, or by the failure it names. */
+export declare class JournalRevokedError extends Error {
+    readonly cause: JournalCommitError | undefined;
+    constructor(cause: JournalCommitError | undefined);
+}
+/** A synchronous read of a thread the catalog holds but the working set does not: read it inside `thread.read` or a retention. */
+export declare class ThreadNotLoadedError extends Error {
+    readonly threadId: string;
+    constructor(threadId: string);
+}
+/** A synchronous read of a row whose thread is not loaded: `readRow()` reads it from the store. */
+export declare class RowNotLoadedError extends Error {
+    readonly seq: Seq;
+    constructor(seq: Seq);
+}
+/** A catalog write after a group that failed on a live journal: its summaries stay current in memory and dirty. */
+export declare class CatalogWriteError extends Error {
+    readonly threadIds: readonly string[];
+    readonly cause: unknown;
+    constructor(threadIds: readonly string[], cause: unknown);
+}
+/** A thread whose summary could not be recomputed from its rows when the catalog was repaired; it kept the one it had. */
+export declare class RepairError extends Error {
+    readonly threadId: string;
+    readonly cause: unknown;
+    constructor(threadId: string, cause: unknown);
+}
+/** A summary contributor threw; its key is missing from that thread's summary, and the group landed. */
+export declare class ContributionError extends Error {
+    readonly key: string;
+    readonly threadId: string;
+    readonly cause: unknown;
+    constructor(key: string, threadId: string, cause: unknown);
+}

package/dist/journal/projection.d.ts

@@ -0,0 +1,87 @@
+import { type JournalEvent } from '../models/index.js';
+/**
+ * A fold over the journal, as the journal itself holds it.
+ *
+ * Projections are never persisted — they are recomputed from the journal, which is the only state —
+ * so unlike the journal's own events they need no schema and no version. Adding one is how a plugin
+ * gets durable state: register the fold, read it back with `Journal.state`. Every projection is
+ * thread-scoped: it keeps one state per thread and sees that thread's lineage, and every row belongs
+ * to a thread. A question about the set of threads is the catalog's, which a plugin adds to with a
+ * contribution.
+ *
+ * A forked thread's state is its source's at the fork point, carried on: the fold replays the
+ * source's lineage up to that row, then the fork's spawn row, then the fork's own rows. So the spawn
+ * row (`isForkSpawn`) is where a projection resets state that describes the source's execution
+ * rather than its conversation, and inherited state may name another thread's rows.
+ *
+ * `apply` may mutate `state` and return it, or return a fresh value. It runs once per appended
+ * event, so a fold that rebuilds its state each time makes a long journal quadratic; prefer
+ * mutation. What `state()` hands a plugin is a read-only view of that state, which is therefore
+ * plain data: primitives, arrays, records, `Map` and `Set`, no class instances or functions. A fold
+ * never reads another fold's state.
+ *
+ * Private to core: a plugin holds a {@link PluginProjection}, which is always isolated.
+ */
+export type Projection<S> = {
+    readonly key: string;
+    /**
+     * Whether a throwing fold fails the operation or only itself. A `fatal` fold is core's: a row it
+     * cannot take, once the store holds it, revokes the journal. An `isolate`d fold is
+     * marked failed on that thread, reported once, and skipped thereafter; reading that state throws
+     * rather than returning partial data. A plugin's fold is `isolate`: a plugin cannot refuse what
+     * the engine recorded.
+     */
+    readonly failureMode: 'fatal' | 'isolate';
+    init(): S;
+    apply(state: S, event: JournalEvent): S;
+};
+declare const pluginFold: unique symbol;
+declare const coreFold: unique symbol;
+/**
+ * A fold a plugin registers: always isolated. Only {@link projection} makes one, so a plugin's fold
+ * can never be the kind that fails the journal.
+ */
+export type PluginProjection<S> = Readonly<Projection<S>> & {
+    readonly failureMode: 'isolate';
+    readonly [pluginFold]: true;
+};
+/**
+ * A fold core registers when the journal is constructed, which a plugin can read but not register
+ * or make. The brand is only this type: a plugin that holds the handle reads it through
+ * `PluginJournal.state`, and the only way to produce one is {@link coreProjection}. Its members are
+ * read-only in the type only: it is not frozen, so a test can spy on its reducer, and TypeScript lets
+ * a read-only value be assigned to a mutable alias. That is acceptable because no door exports a
+ * core fold; only the package's own plugins hold one.
+ */
+export type CoreFold<S> = Readonly<Projection<S>> & {
+    readonly failureMode: 'fatal';
+    readonly [coreFold]: true;
+};
+/** What a fold declares besides its failure mode; {@link projection} and {@link coreProjection} share it. */
+type FoldDefinition<S> = {
+    key: string;
+    init(): S;
+    apply(state: S, event: JournalEvent): S;
+    /**
+     * What a fork does with the state its source's lineage built. `'inherit'` carries it on, the
+     * default. `'reset'` starts again from `init()` at the fork's spawn row, for state that describes
+     * what the source did rather than its conversation; `apply` does not see that row.
+     */
+    onFork?: 'inherit' | 'reset';
+};
+/**
+ * Declares a plugin's projection, inferring its state type from `init`. It always isolates: a
+ * throwing fold marks only itself failed on that thread, and reading it throws
+ * {@link ProjectionFailedError}.
+ */
+export declare const projection: <S>(definition: FoldDefinition<S>) => PluginProjection<S>;
+/** Declares a fold of core's: a row it cannot take revokes the journal. Not on any plugin door. */
+export declare const coreProjection: <S>(definition: FoldDefinition<S>) => CoreFold<S>;
+/** An isolated fold failed; its state is unavailable until it is unregistered and rebuilt. */
+export declare class ProjectionFailedError extends Error {
+    readonly projectionKey: string;
+    readonly threadId: string;
+    readonly cause: unknown;
+    constructor(projectionKey: string, threadId: string, cause: unknown);
+}
+export {};