@animalabs/agent-framework 0.32.0 → 0.34.0

package/dist/src/presentation.d.ts

@@ -0,0 +1,747 @@
+/**
+ * The presentation index (#291): which stored rows each agent's window
+ * holds, and when a row enters it.
+ *
+ * The store's record keeps every write in the order it arrived. An agent's
+ * window is another order over the same rows: the rows presented to it, in
+ * the order its requests carry them (context-manager's window index,
+ * `presentRows`; a row presented at rest is in the window before a request
+ * has carried it). While one agent writes one slot, and nothing else writes
+ * it during that agent's turns, the two orders are the same. Once others
+ * write it during a turn (another agent sharing the slot, a module), or one
+ * agent reads another's, they differ: a row
+ * another agent stored during my turn sits inside my turn in the record, but
+ * my requests carried it only at my next tool boundary or turn start, so a
+ * compile that sent it where the record has it would change my turn's prefix
+ * (the prompt cache misses, and a reply's signed thinking is sent under a
+ * prefix it wasn't minted under).
+ *
+ * This module decides who each stored row is presented to and when, through
+ * each live agent's own context manager. It reads the row's audience stamp
+ * (dendrite/audience.ts), the slot the row is stored in, and the registry's
+ * slots and observe edges (bearingOf), and presents:
+ *
+ * - an agent's own rows as they are written, through the own-row sink
+ *   (storeOwnRow, Agent and ToolResultGuard call it once the row is stored),
+ *   or at its next presentation point when a writer held one back;
+ * - another writer's rows meant for it (arrivals) at its turn start, at its
+ *   tool boundary as a prefix the live stream can carry, at its turn's end,
+ *   and at once while it has no turn alive (present at rest);
+ * - nothing of others' while the host is quiesced (frozen) or under a
+ *   surgery hold, which freeze every window but for an agent's own rows (a
+ *   hold by its own refusals: under it every agent is turn-alive and no
+ *   turn starts);
+ * - the arrivals a rollback's cut took out of an agent's window only at its
+ *   next turn start (holdUntilStart), so the cut holds until it speaks.
+ *
+ * Arrivals are read from the index itself (getUnpresentedMessages filtered
+ * by bearingOf), never from the store's head: a crashed turn's arrivals and
+ * rows imported at boot are arrivals by construction. A shared derivation's
+ * inheritance isn't an arrival: it reaches the child through the window it
+ * was derived with, and bearingOf reads an unstamped row at or before the
+ * derivation's checkpoint (derivedAt) as elsewhere. The one scalar kept is
+ * a memo of where a scan may start, reset whenever the branch, the index
+ * length or the reader's facts moved under it.
+ *
+ * The module presents only for an agent it has taken on (adopt) whose
+ * manager is in presented mode: it never calls presentRows on a manager in
+ * legacy mode but for the deliberate write-down at adopt, and again at a
+ * rebase after the store's branch moved to a branch whose window index for
+ * that manager was never written (one made before the write-down), since
+ * any presentRows there writes the whole record down and switches the mode.
+ * The rows of the record the write-down took in that carry an audience
+ * stamp and are elsewhere to the agent (another agent's own rows, mail
+ * stamped for others, a held row) are then taken out (retractForeign), so a
+ * window written down after other agents' windows holds only the rows an
+ * earlier release stored unstamped and the agent's own and its arrivals
+ * (decision 1).
+ * Nothing in it throws into a writer: a failed presentation is traced and
+ * its rows stay out of the window for the next point. A fresh turn start's
+ * also fails the start (presentAtStart).
+ *
+ * It never imports framework.ts, which imports it.
+ */
+import type { ContentBlock } from '@animalabs/membrane';
+import { type ContextManager, type MessageId, type MessageMetadata, type StoredMessage } from '@animalabs/context-manager';
+import { type AgentRegistry } from './dendrite/registry.js';
+import type { AgentName, MessageSlotRef, ObserveEdge } from './dendrite/types.js';
+import type { WindowOrdinal } from './read-marks.js';
+import type { PresentationRetractReason, TraceEventInput } from './types/trace.js';
+export { heldFromResidents, suppressedRow } from './dendrite/audience.js';
+/** Whether a stored row can join a live stream at a tool boundary: no tool
+ *  blocks (the membrane's tool cycle) and not named as the agent itself (it
+ *  would render as an assistant turn, a prefill). The #286 cut. */
+export declare function isInjectableMidTurn(msg: {
+    participant: string;
+    content: ContentBlock[];
+}, agent: {
+    isOwnParticipant(participant: string): boolean;
+}): boolean;
+/** What later compiles render from the store for the copies of one write
+ *  that landed: one copy as it is, and two or more, the shards of a sharded
+ *  body, as context-manager's autobiographical strategy (the one that
+ *  shards on ingest) joins a body's consecutive shards: their non-text
+ *  blocks, then one text block of their joined text. The join is that
+ *  strategy's `mergeAdjacentBodyGroupRaw`, which context-manager doesn't
+ *  export, so the rule is copied here. */
+export declare function asCompiled(landed: ReadonlyArray<{
+    content: ContentBlock[];
+}>): ContentBlock[];
+/** A place in one agent's window on one branch: an index ordinal
+ *  (ContextManager.ordinalOf, indexLength), never a store sequence. */
+export type Position = WindowOrdinal;
+/** Where an agent's window stood: its branch and its index length then. */
+export interface WindowMark {
+    readonly branch: string;
+    readonly position: Position;
+}
+/** The row's place in `cm`'s window, or undefined for a row out of it (and every row in legacy mode). */
+export declare function positionIn(cm: Pick<ContextManager, 'ordinalOf'>, id: MessageId): Position | undefined;
+/** The place the next row presented in `cm`'s window will take (its index length, exclusive; 0 in legacy mode). */
+export declare function windowEnd(cm: Pick<ContextManager, 'indexLength'>): Position;
+/** Where `cm`'s window stands now, or null in legacy mode, where the window is the record and has no index. */
+export declare function windowMarkOf(cm: Pick<ContextManager, 'windowMode' | 'indexLength' | 'currentBranch'>): WindowMark | null;
+/**
+ * What a row in one agent's merged record is to that agent: its own row,
+ * an arrival (a row meant for it that another writer stored), or elsewhere
+ * (a row it is never presented: another agent's own round, mail for a
+ * co-resident, a held row for a resident, a row a suppress rule hid).
+ */
+export type Bearing = 'own' | 'arrival' | 'elsewhere';
+/** A slot an agent observes: the slot its edge reads, the edge, and the slot's owners. */
+export interface ObservedSlot {
+    readonly slot: MessageSlotRef;
+    readonly edge: ObserveEdge;
+    readonly owners: readonly AgentName[];
+}
+/** What bearingOf needs to know of a reader, read from the registry (readerFacts). */
+export interface ReaderFacts {
+    readonly name: AgentName;
+    /** The slot its own rows are stored in (registry.ownSlotOf). */
+    readonly ownSlot: MessageSlotRef | undefined;
+    /** The slots it observes, each through its edge. */
+    readonly observed: readonly ObservedSlot[];
+    /** Whether its window leaves held rows out: an agent whose own slot is the
+     *  residents' slot, on the host's branch or a branch of its own (a shared
+     *  fork, which carries the residents' view filter). */
+    readonly hidesHeld: boolean;
+    /** For a shared derivation, the parent's checkpoint: a row with no stamp
+     *  at or before it is the parent's inheritance, not the child's arrival. */
+    readonly derivedAt?: number;
+}
+/** The registry queries readerFacts reads. */
+export type ReaderRegistry = Pick<AgentRegistry, 'get' | 'ownSlotOf' | 'observedSlotOf' | 'slotOwners'>;
+/** A reader's facts as the registry has them now. An agent it doesn't know has no slot and observes nothing. */
+export declare function readerFacts(registry: ReaderRegistry, name: AgentName): ReaderFacts;
+/**
+ * A reader's facts as the registry recorded them: its live record, else its
+ * newest ended one (registry.inspect). For a reader that has left, as a
+ * released fork or run has by the time its window is read for what it
+ * never read (AgentFramework.releasedWindow): readerFacts reads live
+ * records only, and would know nothing of it.
+ */
+export declare function recordedReaderFacts(registry: Pick<AgentRegistry, 'inspect' | 'observedSlotOf' | 'slotOwners'>, name: AgentName): ReaderFacts;
+/**
+ * Where a row bearingOf weighs is stored, as its caller read it: `'own'`,
+ * the reader's own slot (the own message store of its context, which
+ * getMessage and getAllMessages read), or another slot by its ref (an
+ * auxiliary view of its context, by namespace, or the own slot of the
+ * agent that wrote the row: slotOfRow, afterStore).
+ */
+export type RowSlot = 'own' | MessageSlotRef;
+/**
+ * What one row is to one reader, from the row's stamp, the reader's facts,
+ * and `slot`, the slot the row is stored in: the reader's own (`'own'`, or
+ * a ref sameSlot as its `ownSlot`), else a slot it may observe. undefined,
+ * a slot its caller couldn't name, is elsewhere.
+ *
+ * A legacy reasoning-loss notice or a row a suppress rule hid
+ * (suppressedRow) is elsewhere to every reader,
+ * in any slot: no view the framework sets renders it.
+ *
+ * In its own slot, with `stamp = audienceOf(metadata)`:
+ * - its own row (`ownRowOf` names it): own;
+ * - another agent's own row: an arrival when one of the reader's edges
+ *   names that agent and reads this slot (observesOwnRows: a resident's
+ *   `AgentConfig.observes`, the relationship decision 1 says another
+ *   agent's rounds reach an agent only through), unless it is that agent's
+ *   stored context injection, which the reader's view leaves out;
+ *   elsewhere otherwise, as it is for every resident by default;
+ * - a row whose audience names it: an arrival, unless it is held and the
+ *   reader leaves held rows out, or it is another agent's stored injection,
+ *   which the reader's view leaves out too (what the reader's own view
+ *   leaves out is never its arrival: main's #853 asks that view, agentSees,
+ *   at a tool boundary);
+ * - a row stamped otherwise (mail for a co-resident, a held row): elsewhere;
+ * - a row with no stamp (stored by a host's writer that doesn't stamp): an
+ *   arrival for the slot's owners, as it reads today, unless it is a shared
+ *   derivation's inheritance (at or before `derivedAt`), held for a reader
+ *   that leaves held rows out, or another agent's stored injection.
+ *
+ * In another slot: an arrival when an edge of the reader's that reads that
+ * slot shows it, by that edge's rules and that slot's owners
+ * (observedRowFor); elsewhere when none does, or the reader has no edge on
+ * the slot. A pure function of its arguments: it runs for a released agent,
+ * which has no live manager, too.
+ */
+export declare function bearingOf(row: Pick<StoredMessage, 'sequence' | 'participant' | 'metadata'>, reader: ReaderFacts, slot: RowSlot | undefined): Bearing;
+/**
+ * Whether a reader is shown `owner`'s own rows through an observe edge, as
+ * bearingOf reads its edges: an edge on another slot that `owner` owns, or
+ * an edge that names `owner` and reads the reader's own slot (a resident
+ * observing a co-resident, AgentConfig.observes). An edge on the reader's
+ * own slot shows only the agent it names, though every resident owns that
+ * slot.
+ */
+export declare function observesOwnRows(reader: ReaderFacts, owner: AgentName): boolean;
+/**
+ * Whether a row stamped for `audience` and stored in `slot` is meant only for
+ * agents that can't read it: its audience names someone, and none of them
+ * reads the slot, as an owner or through an observe edge (registry
+ * readersOf). Such a row is stored as named, never widened (no window
+ * presents it by its audience), and traced as a routing fault. A row whose
+ * audience names an observer of the slot is no fault: its edge shows it
+ * (observedRowFor), as one naming an owner is presented in that owner's
+ * window.
+ */
+export declare function audienceFault(audience: readonly AgentName[], slot: MessageSlotRef | undefined, registry: Pick<AgentRegistry, 'readersOf'>): boolean;
+/** Where one presentation into an agent's window happened. */
+export type PresentationOccasion = 
+/** An agent's own row, presented as it was stored. */
+'write'
+/** A turn's start, before its compile: its own rows and its arrivals. */
+ | 'turn-start'
+/** A start's assembly of a wake's own rows, before its compile. */
+ | 'assembly'
+/** The backstop before every compile: its own rows only. */
+ | 'compile'
+/** A tool boundary: the round's rows, then a prefix of its arrivals. */
+ | 'tool-boundary'
+/** The check before a boundary hands the stream its rows. */
+ | 'hand-off'
+/** A turn's end. */
+ | 'turn-end'
+/** An agent with no turn alive, presented a row at its write, or at boot. */
+ | 'at-rest'
+/** Rows handed a reader fork as framing. */
+ | 'framing'
+/** An agent taken on: its window written down and its own rows repaired. */
+ | 'adopt'
+/** The store's branch moved under a live agent (rebase): its window on the
+ *  new branch written down, where that branch had none, and its own rows
+ *  repaired. */
+ | 'rebase';
+/** A context manager as the module uses it. */
+export type WindowManager = Pick<ContextManager, 'presentRows' | 'retractRows' | 'getUnpresentedMessages' | 'getPresentedMessages' | 'ordinalOf' | 'indexLength' | 'windowStatusOf' | 'windowMode' | 'getMessage' | 'currentBranch' | 'isClosed' | 'retractRemoved' | 'retractAbsentRows' | 'getStore'>;
+/** An agent as the module presents to it. The framework's Agent is one. */
+export interface PresentedAgent {
+    readonly name: AgentName;
+    getContextManager(): WindowManager;
+    isOwnParticipant(participant: string): boolean;
+    /** Where the agent tells of its own rows once they are stored (Agent.setOwnRowSink). */
+    setOwnRowSink?(sink: ((ids: readonly MessageId[]) => void) | undefined): void;
+}
+/** The traces the module emits, as a host passes them on. */
+export type PresentationTrace = Extract<TraceEventInput, {
+    type: `presentation:${string}`;
+}>;
+/** What the module reads of its host (the framework). */
+export interface PresentationHost {
+    /** Every agent registered now, a shared fork on its own branch included. */
+    liveAgents(): Iterable<PresentedAgent>;
+    readonly registry: Pick<AgentRegistry, 'get' | 'ownSlotOf' | 'observedSlotOf' | 'readersOf' | 'slotOwners'>;
+    /**
+     * Whether the agent's logical turn is alive: a turn token, a continuation
+     * or retry on its way, a live stream, or a tool cycle pending. Nothing but
+     * its own rows and its boundary's arrivals is presented to it then.
+     */
+    turnAlive(name: AgentName): boolean;
+    /**
+     * Whether others' rows are frozen out of every window: the host
+     * quiesced, or booting until create()'s pass over the windows. Own rows
+     * still present. A surgery's hold isn't asked here: its
+     * own refusals keep every point that reads this from being reached under
+     * it (the framework's `frozen`, where the host is built).
+     */
+    frozen(): boolean;
+    emitTrace(event: PresentationTrace): void;
+}
+/** A row a tool boundary presented for the live stream to carry: one per body, by the id that names it. */
+export interface HeardRow {
+    readonly id: MessageId;
+    readonly participant: string;
+    /** The body as the store holds it, a sharded one's shards joined as compiles join them (asCompiled). */
+    readonly content: ContentBlock[];
+    readonly metadata?: MessageMetadata;
+}
+/** What a tool boundary presented beyond the round's own rows. */
+export interface BoundaryPresentation {
+    /** The rows the stream carries next, in window order. */
+    readonly heard: readonly HeardRow[];
+    /** The first row the stream can't carry, where the rows presented stop. */
+    readonly cutAt?: MessageId;
+}
+/**
+ * An agent holding a row: in its window, at a place (`'window'`); in a
+ * window that is still the whole record (`'legacy'`), which holds every row
+ * its merged record does; or handed it as a reader fork's framing
+ * (`'framing'`).
+ */
+export type Holder = {
+    readonly agent: AgentName;
+    readonly via: 'window';
+    readonly position: Position;
+} | {
+    readonly agent: AgentName;
+    readonly via: 'legacy';
+} | {
+    readonly agent: AgentName;
+    readonly via: 'framing';
+};
+/** What a presentation listener hears: the rows that entered one agent's window, in order, and where. */
+export interface PresentedEvent {
+    readonly agentName: AgentName;
+    readonly occasion: PresentationOccasion;
+    readonly rows: readonly StoredMessage[];
+}
+/**
+ * The presentation index's decisions, over each live agent's context
+ * manager. The framework constructs it in create() and calls it at each
+ * presentation point.
+ */
+export declare class AgentPresentation {
+    private readonly host;
+    private readonly adopted;
+    private readonly memos;
+    /** Bumped when a registration may have changed what a row is to someone: every memo is then stale. */
+    private generation;
+    /** Rows handed each reader fork as framing (noteFramed), in memory. */
+    private readonly framed;
+    /** Reader forks whose framing may not all be in their window yet: framed before they were taken on, or whose framing's presentation failed. */
+    private readonly framedPending;
+    private readonly listeners;
+    /** Own rows whose presentation at their write failed, per manager (presentOwn), until they enter its window. */
+    private readonly failedOwn;
+    /** Arrivals a rollback took out of each manager's window, kept out of it at rest until the agent's next turn start (holdUntilStart), on the branch the rollback left the store on. */
+    private readonly heldUntilStart;
+    /** Agents the boot's pass at rest left out (repairAndRest's `restExcept`): no point at rest presents their arrivals until their next turn start. */
+    private readonly restWithheld;
+    /** Read-only handles on the slots a manager merges, by namespace (slotOfRow): made only for a reader whose context merges more than one. */
+    private readonly slotReaders;
+    constructor(host: PresentationHost);
+    /** Take on every live agent (adopt), then present what each is owed at rest (repairAndRest). */
+    boot(): void;
+    /**
+     * Take an agent on. Once per manager object: a manager in legacy mode has
+     * its window written down (presentRows([]), which also finishes a
+     * write-down cut short), the stamped rows it took in that are elsewhere to
+     * the agent are taken out (retractForeign; where that fails, at the
+     * agent's next turn start or point at rest), and the agent's own rows
+     * stored and not in its window are presented to it, in record order (an
+     * undone turn's rows are not: getUnpresentedMessages leaves them out). A
+     * window that can't be
+     * written down (another version's index format, or a failed write; not a
+     * write-down that threw once its record was written, which reads as
+     * presented: writeDown) leaves the agent in legacy mode, traced once,
+     * until a move of the store's branch writes its window down on the new
+     * branch (rebase): its window is the whole record, as before the index.
+     * Then, every time, the agent's own-row sink is installed, one left in
+     * legacy mode's too, so the other readers of its slot hear of its rows
+     * (presentOwn), and every scan memo is dropped, since a registration can
+     * change who reads a slot.
+     */
+    adopt(agent: PresentedAgent): void;
+    /**
+     * The store's branch moved under an agent taken on (a host's switchBranch,
+     * a rollback's or a suppression's switch, a failed surgery's restore).
+     * Its manager's window index is the new branch's: on a branch made before
+     * the agent's write-down (every branch an earlier release's store holds,
+     * or a rollback into rows the write-down presented, which branchAt cuts
+     * at their own sequence) there is none, and the window would be the
+     * whole record for the rest of the process. So, as at adopt, such a
+     * window is written down (presentRows([]), traced as presented at
+     * `'rebase'`), the stamped rows it took in that are elsewhere to the
+     * agent, a co-resident's own rows presented on the old branch among them,
+     * are taken out (retractForeign), and the agent's own rows stored and not
+     * in its window are presented to it (the own-row sweep). A window that is presented on the
+     * new branch is presented again for an agent left in legacy mode by an
+     * earlier branch, its own-row sink installed. A window that can't be
+     * written down, or a manager whose strategy couldn't follow the move
+     * (`failure`, from its re-initialization by the framework, #353), leaves
+     * the agent in legacy mode until the next move, traced as
+     * presentation:failed at `'rebase'`. Arrivals aren't presented here: the
+     * framework's surgery release presents what each agent is owed. Never
+     * throws.
+     */
+    rebase(agent: PresentedAgent, failure?: unknown): void;
+    /**
+     * Write `agent`'s window down where its manager is in legacy mode
+     * (presentRows([]), which also finishes a write-down cut short), and say
+     * whether the window is presented after it. A write-down that fails, or
+     * leaves the manager in legacy mode, pins the agent in legacy mode
+     * (`state.pinnedLegacy`), traced as presentation:failed at `occasion`
+     * with `legacy`, which the host logs and alerts. A
+     * write-down that throws once its record is written (the store's own work
+     * after a write, such as a snapshot, failing) has written the window
+     * down: the manager reads its index again after any throw, so a window
+     * that reads as presented then is taken as one, and the agent is
+     * presented for, with a log line. A write-down at a rebase is traced as
+     * presented, with the bodies the window holds; a read for that trace
+     * which throws is logged and the trace skipped, the window presented.
+     */
+    private writeDown;
+    /**
+     * Take out of the agent's window the rows a write-down from the record
+     * took in that aren't its (decision 1): each row that carries an audience
+     * stamp and that bearingOf reads as elsewhere to the agent, such as
+     * another agent's own row, mail stamped for a co-resident, or a held row
+     * for a window that leaves held rows out. Each leaves its place as a plain
+     * retraction does, so it reads as arrived, and it stays elsewhere, so no
+     * later point presents it. Two kinds of row stay: an unstamped row, which
+     * a release before the stamp stored and the write-down migrates whole,
+     * and a shared derivation's inheritance (at or before its checkpoint),
+     * which is the child's history. Nothing is taken out for an agent the
+     * registry has no slot for. Run at every adopt and rebase, not only
+     * after a write-down this process made, so a window whose write-down
+     * landed and whose retraction didn't (a crash between the two records, a
+     * failed write) is repaired the next time it is taken on. Rows are
+     * weighed by the agent's relationships now, not by those they entered
+     * under, so a row the module presented is taken out too where it is
+     * elsewhere to the agent now: an observed agent's own row, presented
+     * through an observe edge the agent no longer has (a restart whose
+     * configuration dropped it). A reader fork's framing is passed over. Traced as
+     * presentation:retracted, reason `elsewhere`; a failure is traced as
+     * presentation:failed at `occasion`, and the rows stay in the window
+     * until the agent's next turn start or point at rest takes them out
+     * (`retractPending`, tried there until it succeeds), or the next adopt or
+     * rebase; a fresh turn start that can't take them out fails
+     * (presentAtStart). Never throws.
+     */
+    private retractForeign;
+    /** The rows of the agent's window retractForeign takes out, each body by its first shard; none for an agent the registry has no slot for. */
+    private foreignRows;
+    /** retractForeign again, where it failed before (`retractPending`). */
+    private retryRetraction;
+    /** Let an agent go: its sink off, and what the module kept for it (its memo, its framing, its held arrivals) dropped. */
+    forget(agent: PresentedAgent): void;
+    /**
+     * For every live agent the module presents to and whose turn isn't alive:
+     * its own rows stored and not in its window (the own-row sweep, traced as
+     * presentation:repaired), then whatever it is owed at rest (presentAtEnd).
+     * Boot runs it once every agent is taken on and the stored rows are in,
+     * whether or not an adopt repaired anything. An agent in `restExcept` has
+     * its own rows swept and nothing else: the boot couldn't read what it is
+     * owed to ask the wakes its rows owe, so they stay out of its window until
+     * its next turn start, which no wake was asked for. Until then no point at
+     * rest presents its arrivals (a row stored for it while it is idle, a
+     * turn's end), only its own rows, so a later boot finds them out of its
+     * window and reads them again.
+     */
+    repairAndRest(options?: {
+        restExcept?: ReadonlySet<AgentName>;
+    }): void;
+    /** Whether the module presents for this agent: taken on, its manager open and in presented mode. */
+    presenting(agent: PresentedAgent): boolean;
+    /**
+     * Present the agent's own rows now, in the order given, those not in its
+     * window yet, even while the host is frozen; then tell the other readers
+     * of its slot (afterStore), whatever became of that: a presentation that
+     * threw, or an agent the module doesn't present for (a failed rebase
+     * leaves its sink on). The own-row sink calls it. It is for a row the
+     * agent's stream carries (its round, its results, a notice injected at its
+     * boundary), one written before its next compile or after its stream's
+     * last request, or one written while it has no turn alive: any other row
+     * would enter a live window its requests don't carry, so its writer holds
+     * it back (storeOwnRow's `present: false`) for the next point's sweep.
+     *
+     * An own row whose presentation here failed (a transient store error) is
+     * kept, and presented ahead of the rows given at the agent's next call,
+     * in record order, while it is still out of the window: its window's
+     * ordinals never move, so a row written after it and presented first
+     * would stay ahead of it for good (a round's results ahead of its reply,
+     * which every later compile would send so). It is kept until the agent's
+     * next turn start or tool boundary, whose own-row sweep presents it by
+     * that point's rule, or leaves it for the next point when that fails
+     * too: a request compiled, or a stream handed its rows, without it
+     * mustn't find it in the window ahead of a reply it didn't come before.
+     * A row its writer held back is never kept: it waits for the next point's
+     * sweep. Never throws.
+     */
+    presentOwn(agent: PresentedAgent, ids: ReadonlyArray<MessageId | undefined>): void;
+    /**
+     * Rows `writer` just stored, in its own slot: each other reader of that
+     * slot (its owners and its observers) whose turn isn't alive, and the
+     * writer itself, is presented what it is owed at once, when one of the
+     * rows is its own or an arrival for it (present at rest). A reader with a
+     * turn alive takes them at its next point. Frozen, only own rows present.
+     * The module needn't present for the writer: one left in legacy mode
+     * tells the readers of its slot too. Each reader is weighed apart, so one
+     * whose window can't be read is traced and the others are still told.
+     * Never throws.
+     */
+    afterStore(writer: PresentedAgent, ids: ReadonlyArray<MessageId | undefined>): void;
+    /**
+     * A turn's start, before its compile. `'turn-start'` (a fresh start) and
+     * `'assembly'` (the rows a wake assembled for it) present, in one call and
+     * record order, the agent's own rows not in its window and its arrivals
+     * (none while frozen); `'compile'`, the backstop before every compile,
+     * fresh or resumed, its own rows only. Returns the arrivals presented, one
+     * per body, for the start to weigh. A fresh start ends a rollback's hold
+     * on the arrivals its cut returned (holdUntilStart): they enter with the
+     * rest, in record order, and the hold ends once they have, so a start
+     * that fails keeps it, and so does one while frozen, which presents no
+     * arrival; so does an agent the boot's pass at rest left out
+     * (repairAndRest's `restExcept`). A fresh start's presentation that fails (a read
+     * of the window or the record that throws, or a write of the window that
+     * leaves a row out) is traced, and then throws, so the start fails rather
+     * than compile without what it was started for, which waits outside the
+     * window for the next point. So does a fresh start where rows a
+     * write-down took in that aren't the agent's are still in its window
+     * (retractForeign failed again here), rather than compile with them. The
+     * backstop's is traced, and its compile goes on.
+     */
+    presentAtStart(agent: PresentedAgent, occasion: 'turn-start' | 'assembly' | 'compile'): StoredMessage[];
+    /**
+     * A tool boundary. First the round's own rows on the wire (`wire`: its
+     * reply, its results, a clock row due), those not in the window yet, in
+     * order; if that fails, nothing more. Then, unless the host is frozen or
+     * the stream can't carry injected rows (`injects` false), the agent's own
+     * rows not in its window and its arrivals, by bodies in record order, up
+     * to the first body the stream can't carry (isInjectableMidTurn: a tool
+     * block, or a row named as the agent), presented in one call: each body
+     * whole, named by its first shard not in the window. Those are what the
+     * stream carries next (`heard`); the cut body and those after it wait for
+     * the turn's end. A presentation cut short hears only the bodies wholly in
+     * the window. A read of the window or the record that throws is traced as
+     * presentation:failed, and the stream hears nothing: what wasn't presented
+     * waits for the next point, and the hand-off that follows checks the
+     * window as it then stands. Never throws, so the boundary goes on to hand
+     * the stream its results.
+     */
+    presentAtBoundary(agent: PresentedAgent, wire: ReadonlyArray<MessageId | undefined>, options: {
+        injects: boolean;
+    }): BoundaryPresentation;
+    /**
+     * A turn's end, and an agent at rest: when its logical turn isn't alive,
+     * its own rows not in its window and its arrivals (none while frozen), in
+     * one call and record order. Nothing while the turn is alive. Idempotent.
+     * Returns the arrivals presented, one per body.
+     */
+    presentAtEnd(agent: PresentedAgent): StoredMessage[];
+    /**
+     * The rows a rollback's branch cut took out of the agent's window and
+     * kept in the record (its `returnedToArrivals`, #291): they are arrivals
+     * again, and wait outside the window until the agent's next turn start
+     * (presentAtStart's `'turn-start'` or `'assembly'`), which presents them
+     * with whatever else it is owed, in record order (a start that fails
+     * keeps them held). Until then no point at
+     * rest presents them: not the surgery's release, a resume, a turn's end
+     * or a row stored for the agent while it is idle, so the cut the
+     * operator made is what the agent's window holds until it speaks again.
+     * A tool boundary isn't held back (a turn alive started since). An own
+     * row among them isn't held: own rows enter at every point, as ever. The
+     * hold is the branch's the store is on (the rollback's): on another
+     * branch the same stored rows are arrivals as any, so a later move of the
+     * store's branch, a suppression or rollback through another agent
+     * included, ends it there, and back on this one they are held again until
+     * the agent's next turn start. In memory: a restart presents them at its
+     * pass at rest, or, where it boots quiesced, at the resume (a frozen pass
+     * presents no arrival), and an agent let go (forget)
+     * drops them. Rows given again on the same branch add to those held, and
+     * on another replace them. Never throws.
+     */
+    holdUntilStart(agent: PresentedAgent, ids: readonly MessageId[]): void;
+    /**
+     * The check before a tool boundary hands the stream its rows: `sent` (the
+     * round's reply, its results and the injected rows, in the order the
+     * stream is given them) not yet in the window are presented, in order,
+     * and the window's newest bodies must then be exactly those rows. On a
+     * mismatch it traces presentation:hand-off-mismatch and the rows are not
+     * vouched for, so the stream's later thinking is left out at the next
+     * compile rather than sent under a prefix its window doesn't hold. An
+     * agent the module doesn't present for is vouched for as before. A read
+     * of the window that throws is traced as presentation:failed, and the
+     * rows are not vouched for: the check couldn't be made. Never throws.
+     */
+    handOff(agent: PresentedAgent, sent: ReadonlyArray<MessageId | undefined>): {
+        vouched: boolean;
+    };
+    /** A read of the agent's arrivals not yet presented, one per body, in record order (for previews and a release). */
+    arrivalsOf(agent: PresentedAgent): StoredMessage[];
+    /**
+     * A reader fork was handed held rows as framing (AF-5): those not in its
+     * window yet are presented there, when the module presents for it, and
+     * the fork counts as holding every one of them (holders, `'framing'`),
+     * however its window filters held rows, until it is let go (forget). A
+     * fork framed before it is taken on has them presented at its adopt. Its
+     * window's filter (the residents', which a reader fork inherits) keeps
+     * them out of its compiles, as it keeps all held traffic; its framing row
+     * shows them where the framing puts them (the default's does); nothing
+     * else of its window moves. Rows whose presentation fails enter at the
+     * fork's next turn start, or after a move of the store's branch (rebase).
+     */
+    noteFramed(agent: PresentedAgent, rowIds: readonly MessageId[]): void;
+    /**
+     * Drop the rows a reader fork was handed as framing (noteFramed) when the
+     * fork is never taken on, so never let go (forget): one its run refused
+     * before registering it (the host quiesced or stopping, a surgery holding
+     * the store). Nothing for a name handed none.
+     */
+    forgetFramed(agent: AgentName): void;
+    /**
+     * The rows the agent is owed and its window doesn't hold yet, one per
+     * body (its first shard not in the window), in record order: its own rows
+     * and its arrivals, frozen or not, whatever its turn. None for an agent the
+     * module doesn't present for. The subconscious's window start is fixed
+     * once no row it is owed stored before the start is among them.
+     */
+    owedOf(agent: PresentedAgent): StoredMessage[];
+    /**
+     * Whether a row just stored in the agent's own slot, and presented at
+     * rest by afterStore if at all, is out of its window though the agent is
+     * owed it (its own row, or an arrival): a presentation that failed, or
+     * the host's freeze, kept it out. A row that is nothing to the agent (held
+     * from a resident, stamped for another) isn't. Yes where the window can't
+     * be read to tell; no for an agent the module doesn't present for.
+     */
+    notPresented(agent: PresentedAgent, id: MessageId): boolean;
+    /**
+     * Every live agent holding a row: each whose window has it at a place,
+     * leaving out one whose window leaves held rows out when the row is held
+     * (a window written down from the record took in those an earlier release
+     * stored, before the audience stamp; retractForeign takes out the rest),
+     * and every one when a suppress rule hid the row, which no view renders;
+     * each whose window
+     * is still the whole record and whose record holds it; and each reader fork
+     * handed it as framing.
+     */
+    holders(rowId: MessageId): Holder[];
+    /**
+     * Rows removed from the record through `remover` (a context manager of a
+     * live agent's, or one opened apart from them), taken out of every other
+     * live agent's window that still holds them: context-manager tombstones a
+     * removal in the remover's own window only, and another window on the
+     * same slot, or merging it, keeps the row's place (CM-T) while its listing
+     * and its compile leave the row out. Each row leaves at its own place, so
+     * no other row's place moves, and a cursor or watermark kept by place
+     * stays good. A window on a branch whose record still holds the row (a
+     * fork, a derived agent's view made before the removal) keeps it, as does
+     * a window that is still the record, which is never written to here
+     * (context-manager's retractRemoved passes over both). Each window's rows
+     * taken out are traced (presentation:retracted, with `reason`), and a
+     * window that couldn't be repaired is logged and passed by: the removal
+     * stands. `ids` names every row removed, a body by each of its shards.
+     * Returns what left each window. Never throws.
+     */
+    retractRemoved(remover: WindowManager | undefined, ids: readonly MessageId[], reason: PresentationRetractReason): Array<{
+        agent: AgentName;
+        ids: MessageId[];
+    }>;
+    /**
+     * At boot, after every live agent is taken on: take out of each window
+     * the module presents for every row it holds that its record no longer
+     * does (context-manager's retractAbsentRows), as retractRemoved takes out
+     * the rows a live removal named. These are rows removed where no live
+     * context heard it: by an offline recovery's suppressions, with the host
+     * stopped, through the one context it opened, and removals whose own
+     * tombstone failed. Traced as presentation:retracted with `boot`; a
+     * window that couldn't be repaired is logged and passed by. Each agent's
+     * context is open with every slot it merges by then, so a row of a slot
+     * it merges isn't taken for removed. Never throws.
+     */
+    retractAbsentRows(): Array<{
+        agent: AgentName;
+        ids: MessageId[];
+    }>;
+    /** Whether a reader fork was handed the row as framing (noteFramed), and
+     *  hasn't been let go since, whether or not its window holds the row. */
+    framedToAny(rowId: MessageId): boolean;
+    /** Whether any live agent but `except` holds the row in a window or as framing: a window that is still the record doesn't count. */
+    presentedToAnyone(rowId: MessageId, options?: {
+        except?: AgentName;
+    }): boolean;
+    /** The rows of the agent's window at or after `mark`, in window order; none in legacy mode. */
+    presentedSince(agent: PresentedAgent, mark: Position): StoredMessage[];
+    /** Hear each presentation into the named agent's window, after its rows entered. Returns the unsubscribe. */
+    onPresented(agentName: AgentName, listener: (event: PresentedEvent) => void): () => void;
+    /**
+     * A write's stamp, checked as it is stored through `deliveredTo`'s
+     * context: an audience none of whose agents reads that slot is traced
+     * (presentation:unreadable-audience), once for the write. The row is
+     * stored as named.
+     */
+    checkAudience(metadata: MessageMetadata | undefined, deliveredTo: AgentName): void;
+    /**
+     * The own rows whose presentation at their write failed (presentOwn) and
+     * that are still out of the agent's window, in record order. A row that
+     * entered by another point since, was undone, or left the record (a
+     * branch move, a removal) is dropped.
+     */
+    private failedOwnOf;
+    /**
+     * Keep, of the own rows presentOwn tried, those still out of the window,
+     * for its next call; forget the rest. Rows kept meanwhile that this call
+     * didn't try stay kept: a listener of its presentation, which runs
+     * inside it, may have stored an own row whose presentation failed, kept
+     * by that nested call.
+     */
+    private keepFailedOwn;
+    /** presentAtEnd under a named occasion; a rollback's held arrivals wait (holdUntilStart), and so do all of an agent's the boot left out (restWithheld). */
+    private presentAtRest;
+    /** The rows the agent was handed as framing (noteFramed) that its window doesn't hold yet, presented in the order handed. */
+    private presentFramed;
+    /** The own-row sweep: the agent's own rows not in its window, presented in record order, traced as a repair. */
+    private repair;
+    /**
+     * Present the agent's own pending rows, and its arrivals when `arrivals`
+     * (but those a rollback holds for its next start, with `atRest`), in one
+     * call; return the arrivals that entered whole, and the error when the
+     * presentation failed: a read that threw, or a write that left a row it
+     * named out. `next` is what the failure's log says becomes of its rows.
+     */
+    private presentPending;
+    /**
+     * The agent's pending bodies, in record order: its own rows not in its
+     * window, and its arrivals when `arrivals`, leaving out, with `atRest`,
+     * an arrival a rollback holds for the agent's next start (any shard of
+     * its body held). A body is its run of unpresented shards
+     * (continuesBody), weighed by its first.
+     */
+    private pending;
+    /**
+     * The slot of `cm`'s record a row is stored in, for bearingOf: its own
+     * (`'own'`, which getMessage reads), else the merged slot that holds it
+     * (mergedSlotsOf). The record holds the context's own slot and one
+     * auxiliary view per merged slot, so a row not in its own is in the one
+     * merged slot when there is one; when there are more, each is asked, by
+     * a read-only handle on it over the manager's store, which follows its
+     * branch and its writes as the manager's own views do. undefined for a
+     * row in none of them (a slot the reader has no edge on).
+     */
+    private slotOfRow;
+    /**
+     * One presentRows call for `ids` in the agent's window: every row named
+     * counts once it returns (it refuses a row already in the window, and
+     * returns one ordinal per row named); on a throw, the rows that entered
+     * before it count, as far as the window can be read then, and the
+     * failure is traced. Traces what entered and tells the listeners.
+     */
+    private present;
+    /**
+     * Tell the agent's listeners of the rows that entered its window, in
+     * order, each body as the window holds it. Where the window can't be
+     * read for that, they are told of each entered row by its first shard
+     * (a body's later shards left out), and that is logged: the rows are in
+     * the window whatever the read, so the listeners (noteArrival, the
+     * subconscious's anchor) still hear them.
+     */
+    private tell;
+    /**
+     * A presentation that failed, logged and traced (presentation:failed):
+     * `ids` are the rows it named that didn't enter the window (a body by
+     * the id that names it), where they are known, and `next` says what
+     * becomes of them.
+     */
+    private failed;
+}
+//# sourceMappingURL=presentation.d.ts.map