@animalabs/agent-framework 0.31.0 → 0.33.0

package/dist/src/presentation.js

@@ -0,0 +1,1435 @@
+import { continuesBody, MessageStore } from '@animalabs/context-manager';
+import { audienceOf, heldFromResidents, observedRowFor, suppressedRow } from './dendrite/audience.js';
+import { sameSlot } from './dendrite/registry.js';
+import { isAnotherAgentsInjection } from './stored-injections.js';
+import { nameAsStored } from './text-as-stored.js';
+export { heldFromResidents, suppressedRow } from './dendrite/audience.js';
+// ============================================================================
+// Pure pieces the tool boundary and the drain share
+// ============================================================================
+/** 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 function isInjectableMidTurn(msg, agent) {
+    // Exact, as membrane's role test is: a participant the request assigns
+    // the assistant role (the agent's name, and for a derived agent the
+    // voice it inherited) renders as the assistant. It's the name as sent,
+    // which the boundary takes as the store keeps it.
+    return !agent.isOwnParticipant(nameAsStored(msg.participant))
+        && !msg.content.some((b) => b.type === 'tool_use' || b.type === 'tool_result');
+}
+/** 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 function asCompiled(landed) {
+    if (landed.length === 1)
+        return landed[0].content;
+    const blocks = landed.flatMap((m) => m.content);
+    const text = blocks.filter((b) => b.type === 'text').map((b) => b.text).join('');
+    return [...blocks.filter((b) => b.type !== 'text'), { type: 'text', text }];
+}
+/** The row's place in `cm`'s window, or undefined for a row out of it (and every row in legacy mode). */
+export function positionIn(cm, id) {
+    return cm.ordinalOf(id);
+}
+/** The place the next row presented in `cm`'s window will take (its index length, exclusive; 0 in legacy mode). */
+export function windowEnd(cm) {
+    return cm.indexLength();
+}
+/** Where `cm`'s window stands now, or null in legacy mode, where the window is the record and has no index. */
+export function windowMarkOf(cm) {
+    if (cm.windowMode() !== 'presented')
+        return null;
+    return { branch: cm.currentBranch().name, position: windowEnd(cm) };
+}
+/** A reader's facts as the registry has them now. An agent it doesn't know has no slot and observes nothing. */
+export function readerFacts(registry, name) {
+    return factsOf(registry, name, registry.get(name), registry.ownSlotOf(name));
+}
+/**
+ * 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 function recordedReaderFacts(registry, name) {
+    const record = registry.inspect(name);
+    return factsOf(registry, name, record, record?.ownSlot ? { ...record.ownSlot } : undefined);
+}
+/** A reader's facts from its record and its own slot (readerFacts, recordedReaderFacts). */
+function factsOf(registry, name, record, ownSlot) {
+    const observed = [];
+    for (const edge of record?.relationships.observes ?? []) {
+        const slot = registry.observedSlotOf(edge);
+        if (slot)
+            observed.push({ slot, edge, owners: registry.slotOwners(slot) });
+    }
+    const derivedAt = record?.inherit?.mode === 'shared' ? record.inherit.atSequence : undefined;
+    return {
+        name,
+        ownSlot,
+        observed,
+        hidesHeld: ownSlot?.namespace === null,
+        ...(derivedAt !== undefined ? { derivedAt } : {}),
+    };
+}
+/**
+ * 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 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 function bearingOf(row, reader, slot) {
+    const metadata = row.metadata;
+    if (slot === undefined)
+        return 'elsewhere';
+    if (suppressedRow(metadata))
+        return 'elsewhere';
+    if (slot !== 'own' && !sameSlot(slot, reader.ownSlot)) {
+        const shown = reader.observed.some((seen) => sameSlot(seen.slot, slot)
+            && observedRowFor(seen.edge, row, { observer: reader.name, owners: seen.owners }));
+        return shown ? 'arrival' : 'elsewhere';
+    }
+    const stamp = audienceOf(metadata);
+    if (stamp) {
+        if (stamp.ownRowOf !== undefined) {
+            if (stamp.ownRowOf === reader.name)
+                return 'own';
+            return observesInOwnSlot(reader, stamp.ownRowOf) && !isAnotherAgentsInjection(metadata, reader.name) ? 'arrival' : 'elsewhere';
+        }
+        if (!stamp.audience.includes(reader.name))
+            return 'elsewhere';
+        if (isAnotherAgentsInjection(metadata, reader.name))
+            return 'elsewhere';
+        return reader.hidesHeld && heldFromResidents(metadata) ? 'elsewhere' : 'arrival';
+    }
+    if (reader.derivedAt !== undefined && row.sequence <= reader.derivedAt)
+        return 'elsewhere';
+    if (reader.hidesHeld && heldFromResidents(metadata))
+        return 'elsewhere';
+    if (isAnotherAgentsInjection(metadata, reader.name))
+        return 'elsewhere';
+    return 'arrival';
+}
+/** Whether one of the reader's edges names `owner` and reads the reader's own slot: a co-resident it observes. */
+function observesInOwnSlot(reader, owner) {
+    return reader.observed.some((seen) => seen.edge.agent === owner && sameSlot(seen.slot, reader.ownSlot));
+}
+/**
+ * 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 function observesOwnRows(reader, owner) {
+    return reader.observed.some((seen) => (sameSlot(seen.slot, reader.ownSlot)
+        ? seen.edge.agent === owner
+        : seen.owners.includes(owner)));
+}
+/**
+ * The slots besides its own a reader's context merges into its record: the
+ * slots its edges read on its context's branch (no `branch` of their own),
+ * each once. The framework opens an observer's context with one auxiliary
+ * view per such slot (createSubconsciousAgent, reopenAgentContext); a slot
+ * on a branch of its own (a shared fork's) can't be merged so.
+ */
+function mergedSlotsOf(reader) {
+    const slots = [];
+    for (const { slot } of reader.observed) {
+        if (slot.branch !== undefined || sameSlot(slot, reader.ownSlot))
+            continue;
+        if (!slots.some((s) => sameSlot(s, slot)))
+            slots.push(slot);
+    }
+    return slots;
+}
+/**
+ * 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 function audienceFault(audience, slot, registry) {
+    if (audience.length === 0 || slot === undefined)
+        return false;
+    const readers = registry.readersOf(slot);
+    return !audience.some((name) => readers.includes(name));
+}
+const describe = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * 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 class AgentPresentation {
+    host;
+    adopted = new WeakMap();
+    memos = new WeakMap();
+    /** Bumped when a registration may have changed what a row is to someone: every memo is then stale. */
+    generation = 0;
+    /** Rows handed each reader fork as framing (noteFramed), in memory. */
+    framed = new Map();
+    /** Reader forks whose framing may not all be in their window yet: framed before they were taken on, or whose framing's presentation failed. */
+    framedPending = new Set();
+    listeners = new Map();
+    /** Own rows whose presentation at their write failed, per manager (presentOwn), until they enter its window. */
+    failedOwn = new WeakMap();
+    /** 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. */
+    heldUntilStart = new WeakMap();
+    /** Agents the boot's pass at rest left out (repairAndRest's `restExcept`): no point at rest presents their arrivals until their next turn start. */
+    restWithheld = new Set();
+    /** Read-only handles on the slots a manager merges, by namespace (slotOfRow): made only for a reader whose context merges more than one. */
+    slotReaders = new WeakMap();
+    constructor(host) {
+        this.host = host;
+    }
+    // --------------------------------------------------------------------------
+    // Taking agents on
+    // --------------------------------------------------------------------------
+    /** Take on every live agent (adopt), then present what each is owed at rest (repairAndRest). */
+    boot() {
+        for (const agent of this.host.liveAgents())
+            this.adopt(agent);
+        this.repairAndRest();
+    }
+    /**
+     * 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) {
+        const cm = agent.getContextManager();
+        this.generation++;
+        let state = this.adopted.get(cm);
+        if (!state) {
+            state = {};
+            this.adopted.set(cm, state);
+            this.writeDown(agent, state, 'adopt');
+            if (!state.pinnedLegacy) {
+                this.retractForeign(agent, 'adopt');
+                this.repair(agent);
+                // A reader fork is framed before it is taken on (noteFramed at its
+                // derivation, adopt at its run's registration): the held rows it was
+                // handed enter its window now, after its framing row.
+                this.presentFramed(agent);
+            }
+        }
+        // In legacy mode too: presentOwn presents nothing for it, and tells the
+        // other readers of its slot of its rows (afterStore).
+        agent.setOwnRowSink?.((ids) => this.presentOwn(agent, ids));
+    }
+    /**
+     * 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, failure) {
+        const cm = agent.getContextManager();
+        const state = this.adopted.get(cm);
+        if (!state)
+            return;
+        this.generation++;
+        this.memos.delete(cm);
+        try {
+            if (failure !== undefined) {
+                state.pinnedLegacy = describe(failure);
+                this.host.emitTrace({ type: 'presentation:failed', agentName: agent.name, occasion: 'rebase', error: state.pinnedLegacy, legacy: true });
+                return;
+            }
+            if (cm.isClosed())
+                return;
+            delete state.pinnedLegacy;
+            if (!this.writeDown(agent, state, 'rebase'))
+                return;
+            agent.setOwnRowSink?.((ids) => this.presentOwn(agent, ids));
+            this.retractForeign(agent, 'rebase');
+            this.repair(agent, 'rebase');
+            // A reader fork's framing that its window doesn't hold on this branch.
+            this.presentFramed(agent);
+        }
+        catch (error) {
+            state.pinnedLegacy = describe(error);
+            this.host.emitTrace({ type: 'presentation:failed', agentName: agent.name, occasion: 'rebase', error: state.pinnedLegacy, legacy: true });
+        }
+    }
+    /**
+     * 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.
+     */
+    writeDown(agent, state, occasion) {
+        const cm = agent.getContextManager();
+        let wrote = false;
+        if (cm.windowMode() === 'legacy') {
+            try {
+                cm.presentRows([]);
+                wrote = true;
+            }
+            catch (error) {
+                if (!readsPresented(cm)) {
+                    state.pinnedLegacy = describe(error);
+                    this.host.emitTrace({ type: 'presentation:failed', agentName: agent.name, occasion, error: state.pinnedLegacy, legacy: true });
+                    return false;
+                }
+                console.warn(`[presentation] ${agent.name}: writing its window down at ${occasion} threw after the window was written (${describe(error)}); its window is presented`);
+                wrote = true;
+            }
+        }
+        if (cm.windowMode() !== 'presented') {
+            state.pinnedLegacy = 'the window is not in presented mode after its write-down';
+            this.host.emitTrace({ type: 'presentation:failed', agentName: agent.name, occasion, error: state.pinnedLegacy, legacy: true });
+            return false;
+        }
+        if (wrote && occasion === 'rebase') {
+            // The trace's read is the trace's: a throw there leaves the window
+            // presented, as written down, and skips the trace.
+            let count = 0;
+            try {
+                count = bodyHeadCount(cm.getPresentedMessages());
+            }
+            catch (error) {
+                console.error(`[presentation] ${agent.name}: its window was written down at ${occasion}, and reading it back for the trace failed (${describe(error)}); its window is presented, and the write-down isn't traced`);
+            }
+            if (count > 0)
+                this.host.emitTrace({ type: 'presentation:presented', agentName: agent.name, occasion, count });
+        }
+        return true;
+    }
+    /**
+     * 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.
+     */
+    retractForeign(agent, occasion) {
+        const cm = agent.getContextManager();
+        const state = this.adopted.get(cm);
+        try {
+            if (!this.presenting(agent))
+                return;
+            const foreign = this.foreignRows(agent);
+            if (foreign.length > 0) {
+                cm.retractRows(foreign);
+                this.memos.delete(cm);
+                this.host.emitTrace({ type: 'presentation:retracted', agentName: agent.name, messageIds: foreign, reason: 'elsewhere' });
+            }
+            if (state)
+                delete state.retractPending;
+        }
+        catch (error) {
+            if (state)
+                state.retractPending = true;
+            console.error(`[presentation] ${agent.name}: taking the rows that aren't its out of its window at ${occasion} failed; they stay in it, and no turn of its starts, until its next turn start or point at rest takes them out:`, error);
+            this.host.emitTrace({ type: 'presentation:failed', agentName: agent.name, occasion, error: describe(error) });
+        }
+    }
+    /** 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. */
+    foreignRows(agent) {
+        const cm = agent.getContextManager();
+        const facts = readerFacts(this.host.registry, agent.name);
+        // An agent the registry doesn't know has no slot to weigh a row by.
+        if (facts.ownSlot === undefined)
+            return [];
+        const framed = this.framed.get(agent.name);
+        const window = cm.getPresentedMessages();
+        const foreign = [];
+        for (let i = 0; i < window.length; i++) {
+            const row = window[i];
+            // A body is taken out whole by its first shard.
+            if (i > 0 && continuesBody(window[i - 1], row))
+                continue;
+            if (audienceOf(row.metadata) === undefined || framed?.has(row.id))
+                continue;
+            if (facts.derivedAt !== undefined && row.sequence <= facts.derivedAt)
+                continue;
+            if (bearingOf(row, facts, this.slotOfRow(cm, facts, row.id)) === 'elsewhere')
+                foreign.push(row.id);
+        }
+        return foreign;
+    }
+    /** retractForeign again, where it failed before (`retractPending`). */
+    retryRetraction(agent, occasion) {
+        if (this.adopted.get(agent.getContextManager())?.retractPending)
+            this.retractForeign(agent, occasion);
+    }
+    /** Let an agent go: its sink off, and what the module kept for it (its memo, its framing, its held arrivals) dropped. */
+    forget(agent) {
+        agent.setOwnRowSink?.(undefined);
+        const cm = agent.getContextManager();
+        this.adopted.delete(cm);
+        this.memos.delete(cm);
+        this.failedOwn.delete(cm);
+        this.heldUntilStart.delete(cm);
+        this.slotReaders.delete(cm);
+        this.framed.delete(agent.name);
+        this.framedPending.delete(agent.name);
+        this.restWithheld.delete(agent.name);
+        this.generation++;
+    }
+    /**
+     * 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 = {}) {
+        for (const name of options.restExcept ?? [])
+            this.restWithheld.add(name);
+        for (const agent of this.host.liveAgents()) {
+            if (!this.presenting(agent) || this.host.turnAlive(agent.name))
+                continue;
+            this.repair(agent);
+            if (!options.restExcept?.has(agent.name))
+                this.presentAtRest(agent, 'at-rest');
+        }
+    }
+    /** Whether the module presents for this agent: taken on, its manager open and in presented mode. */
+    presenting(agent) {
+        const cm = agent.getContextManager();
+        const state = this.adopted.get(cm);
+        return !!state && !state.pinnedLegacy && !cm.isClosed() && cm.windowMode() === 'presented';
+    }
+    // --------------------------------------------------------------------------
+    // Presentation points
+    // --------------------------------------------------------------------------
+    /**
+     * 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, ids) {
+        const cm = agent.getContextManager();
+        // Every row this call tries, the ones an earlier failed write kept
+        // among them, from before the first read: a read that throws keeps them
+        // all (keepFailedOwn), so none of them is put behind the rows written
+        // after it.
+        let tried = unique([...(this.failedOwn.get(cm) ?? []), ...ids]);
+        try {
+            if (this.presenting(agent)) {
+                tried = unique([...this.failedOwnOf(agent), ...ids]).filter((id) => cm.ordinalOf(id) === undefined);
+                this.present(agent, tried, 'write');
+                this.keepFailedOwn(agent, tried);
+            }
+        }
+        catch (error) {
+            this.failed(agent, 'write', error);
+            this.keepFailedOwn(agent, tried);
+        }
+        this.afterStore(agent, ids);
+    }
+    /**
+     * 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, ids) {
+        try {
+            const stored = unique(ids);
+            if (stored.length === 0)
+                return;
+            const writerCm = writer.getContextManager();
+            const rows = stored.map((id) => writerCm.getMessage(id)).filter((row) => row !== null);
+            const slot = this.host.registry.ownSlotOf(writer.name);
+            const readers = new Set([writer.name, ...(slot ? this.host.registry.readersOf(slot) : [])]);
+            for (const reader of [...this.host.liveAgents()]) {
+                if (!readers.has(reader.name))
+                    continue;
+                try {
+                    if (!this.presenting(reader) || this.host.turnAlive(reader.name))
+                        continue;
+                    const facts = readerFacts(this.host.registry, reader.name);
+                    // The rows are in the writer's own slot: the reader's own when it
+                    // is the writer or shares that slot (bearingOf compares the ref),
+                    // else a slot it observes, weighed by its edges on that slot.
+                    const from = reader === writer ? 'own' : slot;
+                    // A row the writer's own slot doesn't hold (none found) can't be
+                    // weighed here; the reader's own scan weighs it.
+                    const owed = rows.length < stored.length || rows.some((row) => bearingOf(row, facts, from) !== 'elsewhere');
+                    if (owed)
+                        this.presentAtRest(reader, 'at-rest');
+                }
+                catch (error) {
+                    this.failed(reader, 'at-rest', error);
+                }
+            }
+        }
+        catch (error) {
+            this.failed(writer, 'at-rest', error);
+        }
+    }
+    /**
+     * 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, occasion) {
+        if (!this.presenting(agent))
+            return [];
+        const cm = agent.getContextManager();
+        const fresh = occasion !== 'compile';
+        // The sweep below decides the own rows a failed write left (presentOwn):
+        // the backstop's at once, as its compile goes on whatever it presents; a
+        // fresh start's once it hasn't thrown, so the next own row's write still
+        // puts them first after a start that presented nothing. Only those kept
+        // before it: a listener of its presentation, which runs inside it, may
+        // store an own row whose presentation fails, kept by that nested write.
+        if (!fresh)
+            this.failedOwn.delete(cm);
+        const keptBefore = fresh ? new Set(this.failedOwn.get(cm) ?? []) : undefined;
+        // A fresh start is where rows a write-down took in that aren't the
+        // agent's, whose retraction failed, leave before its compile, and a
+        // reader fork's framing whose presentation failed enters.
+        if (fresh) {
+            this.retryRetraction(agent, occasion);
+            if (this.adopted.get(cm)?.retractPending) {
+                throw new Error(`${agent.name}'s turn start could not take the rows that aren't its out of its window (at ${occasion}); they stay in it, and it doesn't compile, until a later point takes them out`);
+            }
+        }
+        if (fresh && this.framedPending.has(agent.name))
+            this.presentFramed(agent);
+        // A rollback's returned arrivals enter here (holdUntilStart): the hold
+        // is left out of this presentation, and ends once it hasn't failed, at a
+        // start that could present arrivals (none while frozen).
+        const withArrivals = fresh && !this.host.frozen();
+        const { arrivals, failure } = this.presentPending(agent, occasion, withArrivals, false, fresh ? "the start fails, and what it didn't present waits for the next point" : undefined);
+        if (fresh && failure !== undefined) {
+            throw new Error(`${agent.name}'s turn start could not present what it is owed (at ${occasion}): ${describe(failure)}`, { cause: failure });
+        }
+        if (keptBefore) {
+            const keptMeanwhile = [...(this.failedOwn.get(cm) ?? [])].filter((id) => !keptBefore.has(id));
+            if (keptMeanwhile.length > 0)
+                this.failedOwn.set(cm, new Set(keptMeanwhile));
+            else
+                this.failedOwn.delete(cm);
+        }
+        if (withArrivals) {
+            this.heldUntilStart.delete(cm);
+            this.restWithheld.delete(agent.name);
+        }
+        return arrivals;
+    }
+    /**
+     * 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, wire, options) {
+        try {
+            if (!this.presenting(agent))
+                return { heard: [] };
+            const cm = agent.getContextManager();
+            const missing = unique(wire).filter((id) => cm.ordinalOf(id) === undefined);
+            // The round's rows are presented here, in order, and the own rows a
+            // failed write left (presentOwn) are this boundary's to sweep, or the
+            // next point's: none is put ahead of the next round's reply.
+            this.failedOwn.delete(cm);
+            if (missing.length > 0 && this.present(agent, missing, 'tool-boundary').error !== undefined)
+                return { heard: [] };
+            if (this.host.frozen() || !options.injects)
+                return { heard: [] };
+            const bodies = this.pending(agent, true);
+            const cut = bodies.findIndex((body) => body.shards.some((shard) => !isInjectableMidTurn(shard, agent)));
+            const prefix = cut === -1 ? bodies : bodies.slice(0, cut);
+            const cutAt = cut === -1 ? undefined : bodies[cut].shards[0].id;
+            const { entered } = this.present(agent, prefix.map((body) => body.shards[0].id), 'tool-boundary', {
+                unstamped: prefix.filter((body) => body.unstamped).length,
+                ...(cutAt !== undefined ? { cutAt } : {}),
+            }, prefix);
+            const heard = prefix
+                .filter((body) => entered.has(body.shards[0].id) && body.shards.every((shard) => cm.ordinalOf(shard.id) !== undefined))
+                .map((body) => {
+                const head = body.shards[0];
+                return {
+                    id: head.id,
+                    participant: head.participant,
+                    content: asCompiled(body.shards),
+                    ...(head.metadata !== undefined ? { metadata: head.metadata } : {}),
+                };
+            });
+            return { heard, ...(cutAt !== undefined ? { cutAt } : {}) };
+        }
+        catch (error) {
+            this.failed(agent, 'tool-boundary', error);
+            return { heard: [] };
+        }
+    }
+    /**
+     * 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) {
+        return this.presentAtRest(agent, 'turn-end');
+    }
+    /**
+     * 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, ids) {
+        const named = unique(ids);
+        if (named.length === 0)
+            return;
+        const cm = agent.getContextManager();
+        try {
+            const branch = cm.currentBranch().name;
+            const held = this.heldUntilStart.get(cm);
+            const kept = held?.branch === branch ? held.ids : new Set();
+            for (const id of named)
+                kept.add(id);
+            this.heldUntilStart.set(cm, { branch, ids: kept });
+            // A scan at rest that left an earlier hold's rows out may have passed them.
+            this.memos.delete(cm);
+        }
+        catch (error) {
+            console.error(`[presentation] ${agent.name}: could not hold ${named.length} row(s) out of its window until its next turn start; they enter at its next presentation point:`, error);
+        }
+    }
+    /**
+     * 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, sent) {
+        try {
+            if (!this.presenting(agent))
+                return { vouched: true };
+            const cm = agent.getContextManager();
+            const expected = unique(sent);
+            if (expected.length === 0)
+                return { vouched: true };
+            const missing = expected.filter((id) => cm.ordinalOf(id) === undefined);
+            if (missing.length > 0 && this.present(agent, missing, 'hand-off').error !== undefined) {
+                this.host.emitTrace({ type: 'presentation:hand-off-mismatch', agentName: agent.name, expected, tail: lastBodyHeads(cm.getPresentedMessages(), expected.length) });
+                return { vouched: false };
+            }
+            const tail = lastBodyHeads(cm.getPresentedMessages(), expected.length);
+            if (tail.length !== expected.length || tail.some((id, i) => id !== expected[i])) {
+                this.host.emitTrace({ type: 'presentation:hand-off-mismatch', agentName: agent.name, expected, tail });
+                return { vouched: false };
+            }
+            return { vouched: true };
+        }
+        catch (error) {
+            this.failed(agent, 'hand-off', error);
+            return { vouched: false };
+        }
+    }
+    /** A read of the agent's arrivals not yet presented, one per body, in record order (for previews and a release). */
+    arrivalsOf(agent) {
+        if (!this.presenting(agent))
+            return [];
+        return this.pending(agent, true).filter((body) => body.bearing === 'arrival').map((body) => body.shards[0]);
+    }
+    /**
+     * 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, rowIds) {
+        const set = this.framed.get(agent.name) ?? new Set();
+        for (const id of rowIds)
+            set.add(id);
+        this.framed.set(agent.name, set);
+        this.framedPending.add(agent.name);
+        this.presentFramed(agent);
+    }
+    /**
+     * 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) {
+        this.framed.delete(agent);
+        this.framedPending.delete(agent);
+    }
+    /**
+     * 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) {
+        if (!this.presenting(agent))
+            return [];
+        return this.pending(agent, true).map((body) => body.shards[0]);
+    }
+    /**
+     * 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, id) {
+        try {
+            if (!this.presenting(agent))
+                return false;
+            const cm = agent.getContextManager();
+            if (cm.windowStatusOf(id) !== 'out')
+                return false;
+            const row = cm.getMessage(id);
+            return row === null || bearingOf(row, readerFacts(this.host.registry, agent.name), 'own') !== 'elsewhere';
+        }
+        catch {
+            return true;
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Reads
+    // --------------------------------------------------------------------------
+    /**
+     * 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) {
+        const holders = [];
+        const inWindow = new Set();
+        for (const agent of this.host.liveAgents()) {
+            const cm = agent.getContextManager();
+            if (cm.isClosed())
+                continue;
+            if (this.adopted.get(cm)?.pinnedLegacy || cm.windowMode() !== 'presented') {
+                if (cm.getMessage(rowId) !== null || cm.getPresentedMessages().some((m) => m.id === rowId)) {
+                    holders.push({ agent: agent.name, via: 'legacy' });
+                }
+                continue;
+            }
+            const position = positionIn(cm, rowId);
+            if (position === undefined)
+                continue;
+            const metadata = cm.getMessage(rowId)?.metadata;
+            if (suppressedRow(metadata))
+                continue;
+            if (readerFacts(this.host.registry, agent.name).hidesHeld && heldFromResidents(metadata))
+                continue;
+            holders.push({ agent: agent.name, via: 'window', position });
+            inWindow.add(agent.name);
+        }
+        for (const [agent, ids] of this.framed) {
+            if (ids.has(rowId) && !inWindow.has(agent))
+                holders.push({ agent, via: 'framing' });
+        }
+        return holders;
+    }
+    /**
+     * 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, ids, reason) {
+        const named = unique(ids).filter((id) => id !== '');
+        if (named.length === 0)
+            return [];
+        const visited = new Set(remover ? [remover] : []);
+        const out = [];
+        for (const agent of this.host.liveAgents()) {
+            const cm = agent.getContextManager();
+            if (visited.has(cm))
+                continue;
+            visited.add(cm);
+            try {
+                // A window that is still the record holds no place for the row:
+                // checked here as well as by the call, which writes nothing then.
+                if (cm.isClosed() || cm.windowMode() !== 'presented')
+                    continue;
+                const taken = cm.retractRemoved(named);
+                if (taken.length === 0)
+                    continue;
+                out.push({ agent: agent.name, ids: taken });
+                this.host.emitTrace({ type: 'presentation:retracted', agentName: agent.name, messageIds: taken, reason });
+            }
+            catch (error) {
+                console.error(`[presentation] could not take ${named.length} removed row(s) out of ${agent.name}'s window (${reason}); the removal stands: ${describe(error)}`);
+            }
+        }
+        return out;
+    }
+    /**
+     * 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() {
+        const out = [];
+        const visited = new Set();
+        for (const agent of this.host.liveAgents()) {
+            const cm = agent.getContextManager();
+            if (visited.has(cm))
+                continue;
+            visited.add(cm);
+            try {
+                if (!this.presenting(agent))
+                    continue;
+                const taken = cm.retractAbsentRows();
+                if (taken.length === 0)
+                    continue;
+                out.push({ agent: agent.name, ids: taken });
+                this.host.emitTrace({ type: 'presentation:retracted', agentName: agent.name, messageIds: taken, reason: 'boot' });
+            }
+            catch (error) {
+                console.error(`[presentation] could not take removed rows out of ${agent.name}'s window at boot: ${describe(error)}`);
+            }
+        }
+        return out;
+    }
+    /** 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) {
+        for (const ids of this.framed.values())
+            if (ids.has(rowId))
+                return true;
+        return false;
+    }
+    /** 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, options = {}) {
+        return this.holders(rowId).some((h) => h.via !== 'legacy' && h.agent !== options.except);
+    }
+    /** The rows of the agent's window at or after `mark`, in window order; none in legacy mode. */
+    presentedSince(agent, mark) {
+        const cm = agent.getContextManager();
+        if (cm.windowMode() !== 'presented')
+            return [];
+        return cm.getPresentedMessages().filter((m) => (cm.ordinalOf(m.id) ?? -1) >= mark);
+    }
+    /** Hear each presentation into the named agent's window, after its rows entered. Returns the unsubscribe. */
+    onPresented(agentName, listener) {
+        const set = this.listeners.get(agentName) ?? new Set();
+        set.add(listener);
+        this.listeners.set(agentName, set);
+        return () => {
+            set.delete(listener);
+            if (set.size === 0 && this.listeners.get(agentName) === set)
+                this.listeners.delete(agentName);
+        };
+    }
+    /**
+     * 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, deliveredTo) {
+        const stamp = audienceOf(metadata);
+        if (!stamp)
+            return;
+        const slot = this.host.registry.ownSlotOf(deliveredTo);
+        if (!slot || !audienceFault(stamp.audience, slot, this.host.registry))
+            return;
+        this.host.emitTrace({ type: 'presentation:unreadable-audience', audience: stamp.audience, slot, deliveredTo });
+    }
+    // --------------------------------------------------------------------------
+    // Internals
+    // --------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    failedOwnOf(agent) {
+        const cm = agent.getContextManager();
+        const kept = this.failedOwn.get(cm);
+        if (!kept || kept.size === 0)
+            return [];
+        const owed = [];
+        for (const id of kept) {
+            const row = cm.windowStatusOf(id) === 'out' ? cm.getMessage(id) : null;
+            if (row)
+                owed.push({ id, sequence: row.sequence });
+        }
+        if (owed.length === 0)
+            this.failedOwn.delete(cm);
+        return owed.sort((a, b) => a.sequence - b.sequence).map((row) => row.id);
+    }
+    /**
+     * 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.
+     */
+    keepFailedOwn(agent, tried) {
+        const cm = agent.getContextManager();
+        const triedHere = new Set(tried);
+        const keptMeanwhile = [...(this.failedOwn.get(cm) ?? [])].filter((id) => !triedHere.has(id));
+        let keep;
+        try {
+            keep = [...tried, ...keptMeanwhile].filter((id) => cm.ordinalOf(id) === undefined);
+        }
+        catch {
+            // A window that can't be read now: keep every row tried.
+            keep = [...tried, ...keptMeanwhile];
+        }
+        if (keep.length > 0)
+            this.failedOwn.set(cm, new Set(keep));
+        else
+            this.failedOwn.delete(cm);
+    }
+    /** 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). */
+    presentAtRest(agent, occasion) {
+        if (!this.presenting(agent) || this.host.turnAlive(agent.name))
+            return [];
+        this.retryRetraction(agent, occasion);
+        return this.presentPending(agent, occasion, !this.host.frozen() && !this.restWithheld.has(agent.name), true).arrivals;
+    }
+    /** The rows the agent was handed as framing (noteFramed) that its window doesn't hold yet, presented in the order handed. */
+    presentFramed(agent) {
+        const framed = this.framed.get(agent.name);
+        if (!framed || framed.size === 0) {
+            this.framedPending.delete(agent.name);
+            return;
+        }
+        try {
+            if (!this.presenting(agent))
+                return;
+            const cm = agent.getContextManager();
+            // presentRows refuses a row the window holds already, and a reader
+            // fork derived from a presented window holds those rows its parent's
+            // window was written down with.
+            const unpresented = new Set(cm.getUnpresentedMessages().map((m) => m.id));
+            const { error } = this.present(agent, [...framed].filter((id) => unpresented.has(id)), 'framing');
+            // Pending until a presentation of them doesn't fail: the fork's next
+            // turn start tries again (presentAtStart).
+            if (error === undefined)
+                this.framedPending.delete(agent.name);
+        }
+        catch (error) {
+            this.failed(agent, 'framing', error);
+        }
+    }
+    /** The own-row sweep: the agent's own rows not in its window, presented in record order, traced as a repair. */
+    repair(agent, occasion = 'adopt') {
+        try {
+            const own = this.pending(agent, false);
+            if (own.length === 0)
+                return;
+            const { entered } = this.present(agent, own.map((body) => body.shards[0].id), occasion, undefined, own, true);
+            if (entered.size > 0)
+                this.host.emitTrace({ type: 'presentation:repaired', agentName: agent.name, count: entered.size });
+        }
+        catch (error) {
+            this.failed(agent, occasion, error);
+        }
+    }
+    /**
+     * 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.
+     */
+    presentPending(agent, occasion, arrivals, atRest = false, next) {
+        try {
+            const cm = agent.getContextManager();
+            const bodies = this.pending(agent, arrivals, atRest);
+            if (bodies.length === 0)
+                return { arrivals: [] };
+            const heads = bodies.map((body) => body.shards[0].id);
+            const { entered, error } = this.present(agent, heads, occasion, {
+                unstamped: bodies.filter((body) => body.unstamped).length,
+                ...(next !== undefined ? { next } : {}),
+            }, bodies);
+            return {
+                arrivals: bodies
+                    .filter((body) => body.bearing === 'arrival' && entered.has(body.shards[0].id)
+                    && body.shards.every((shard) => cm.ordinalOf(shard.id) !== undefined))
+                    .map((body) => body.shards[0]),
+                ...(error !== undefined && heads.some((id) => !entered.has(id)) ? { failure: error } : {}),
+            };
+        }
+        catch (error) {
+            this.failed(agent, occasion, error, undefined, next);
+            return { arrivals: [], failure: error };
+        }
+    }
+    /**
+     * 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.
+     */
+    pending(agent, arrivals, atRest = false) {
+        const cm = agent.getContextManager();
+        const facts = readerFacts(this.host.registry, agent.name);
+        const factsKey = JSON.stringify(facts);
+        const branch = cm.currentBranch().name;
+        // A rollback's hold is its branch's: on another the rows are arrivals as any.
+        const hold = atRest ? this.heldUntilStart.get(cm) : undefined;
+        const held = hold?.branch === branch && hold.ids.size > 0 ? hold.ids : undefined;
+        const length = cm.indexLength();
+        let memo = this.memos.get(cm);
+        if (!memo || memo.generation !== this.generation || memo.branch !== branch || memo.length !== length || memo.facts !== factsKey) {
+            memo = { generation: this.generation, branch, length, facts: factsKey, scanFrom: -Infinity };
+            this.memos.set(cm, memo);
+        }
+        // Every unpresented row at or below the memo's mark was elsewhere, so the
+        // listing starts after it (context-manager finds the place by a search):
+        // a scan walks the rows stored since, not every row of others' the
+        // record holds. A scan that leaves held arrivals out may start at its own
+        // mark too, which held rows don't hold back (heldScanFrom).
+        const from = held ? Math.max(memo.scanFrom, memo.heldScanFrom ?? -Infinity) : memo.scanFrom;
+        const unpresented = from === -Infinity
+            ? cm.getUnpresentedMessages()
+            : cm.getUnpresentedMessages({ afterSequence: from });
+        const bodies = [];
+        let firstOwed;
+        let newest = from;
+        let i = 0;
+        while (i < unpresented.length) {
+            const start = i;
+            i++;
+            while (i < unpresented.length && continuesBody(unpresented[i - 1], unpresented[i]))
+                i++;
+            const head = unpresented[start];
+            newest = Math.max(newest, unpresented[i - 1].sequence);
+            if (head.sequence <= from)
+                continue;
+            const bearing = bearingOf(head, facts, this.slotOfRow(cm, facts, head.id));
+            if (bearing === 'elsewhere')
+                continue;
+            // A held arrival is still owed, and every scan but this one counts it
+            // (firstOwed, in `scanFrom`), so a scan that presents it, or counts
+            // what is owed, starts at or before it; this one passes it over.
+            const isHeld = bearing === 'arrival' && held !== undefined
+                && unpresented.slice(start, i).some((shard) => held.has(shard.id));
+            if (!isHeld)
+                firstOwed ??= head.sequence;
+            if (isHeld || (bearing === 'arrival' && !arrivals))
+                continue;
+            bodies.push({ shards: unpresented.slice(start, i), bearing, unstamped: audienceOf(head.metadata) === undefined });
+        }
+        const next = firstOwed !== undefined ? Math.max(from, firstOwed - 1) : newest;
+        if (held)
+            memo.heldScanFrom = next;
+        else
+            memo.scanFrom = next;
+        return bodies;
+    }
+    /**
+     * 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).
+     */
+    slotOfRow(cm, facts, id) {
+        if (cm.getMessage(id) !== null)
+            return 'own';
+        const merged = mergedSlotsOf(facts);
+        if (merged.length <= 1)
+            return merged[0];
+        let readers = this.slotReaders.get(cm);
+        if (!readers) {
+            readers = new Map();
+            this.slotReaders.set(cm, readers);
+        }
+        for (const slot of merged) {
+            let reader = readers.get(slot.namespace);
+            if (!reader) {
+                reader = new MessageStore(cm.getStore(), slot.namespace === null ? {} : { namespace: slot.namespace });
+                readers.set(slot.namespace, reader);
+            }
+            if (reader.sequenceOf(id) !== undefined)
+                return slot;
+        }
+        return undefined;
+    }
+    /**
+     * 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.
+     */
+    present(agent, ids, occasion, extra, bodies, quiet = false) {
+        if (ids.length === 0)
+            return { entered: new Set() };
+        const cm = agent.getContextManager();
+        const lengthBefore = cm.indexLength();
+        let error;
+        let entered;
+        try {
+            cm.presentRows(ids);
+            // Read from the write's return, not the window: a read that throws
+            // now mustn't keep rows the store holds from being traced and told.
+            entered = new Set(ids);
+        }
+        catch (thrown) {
+            error = thrown;
+            try {
+                entered = new Set(ids.filter((id) => cm.ordinalOf(id) !== undefined));
+            }
+            catch (readError) {
+                console.error(`[presentation] ${agent.name}'s window couldn't be read after a failed presentation, so none of it is counted as entered:`, readError);
+                entered = new Set();
+            }
+        }
+        const memo = this.memos.get(cm);
+        if (memo && memo.length === lengthBefore) {
+            try {
+                memo.length = cm.indexLength();
+            }
+            catch {
+                // The scan's memo can't be moved past the rows: the next scan reads them again.
+                this.memos.delete(cm);
+            }
+        }
+        if (error !== undefined)
+            this.failed(agent, occasion, error, ids.filter((id) => !entered.has(id)), extra?.next);
+        if (entered.size > 0) {
+            if (!quiet) {
+                const unstamped = extra?.unstamped !== undefined && bodies
+                    ? bodies.filter((body) => body.unstamped && entered.has(body.shards[0].id)).length
+                    : 0;
+                this.host.emitTrace({
+                    type: 'presentation:presented',
+                    agentName: agent.name,
+                    occasion,
+                    count: entered.size,
+                    ...(extra?.cutAt !== undefined ? { cutAt: extra.cutAt } : {}),
+                    ...(unstamped > 0 ? { unstamped } : {}),
+                });
+            }
+            this.tell(agent, occasion, ids, entered, bodies);
+        }
+        return { entered, ...(error !== undefined ? { error } : {}) };
+    }
+    /**
+     * 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.
+     */
+    tell(agent, occasion, ids, entered, bodies) {
+        const listeners = this.listeners.get(agent.name);
+        if (!listeners || listeners.size === 0)
+            return;
+        const cm = agent.getContextManager();
+        const byHead = new Map((bodies ?? []).map((body) => [body.shards[0].id, body.shards]));
+        let window;
+        const named = ids.filter((id) => entered.has(id));
+        let rows;
+        try {
+            rows = named.flatMap((id) => {
+                const shards = byHead.get(id);
+                if (shards)
+                    return shards.filter((shard) => cm.ordinalOf(shard.id) !== undefined);
+                // A row named alone (an own row at its write): its body as the window now holds it.
+                window ??= cm.getPresentedMessages();
+                const at = window.findIndex((m) => m.id === id);
+                if (at === -1)
+                    return [];
+                let end = at + 1;
+                while (end < window.length && continuesBody(window[end - 1], window[end]))
+                    end++;
+                return window.slice(at, end);
+            });
+        }
+        catch (error) {
+            console.error(`[presentation] ${agent.name}'s window couldn't be read to tell its listeners which rows entered it, so they are told of each by its first shard:`, error);
+            rows = named.flatMap((id) => {
+                const head = byHead.get(id)?.[0];
+                if (head)
+                    return [head];
+                try {
+                    const row = cm.getMessage(id);
+                    return row ? [row] : [];
+                }
+                catch {
+                    return [];
+                }
+            });
+        }
+        for (const listener of [...listeners]) {
+            try {
+                listener({ agentName: agent.name, occasion, rows });
+            }
+            catch (error) {
+                console.error(`[presentation] a listener of ${agent.name}'s window failed:`, error);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    failed(agent, occasion, error, ids, next = "what it didn't present waits for the next point") {
+        const left = ids !== undefined && ids.length > 0 ? [...ids] : undefined;
+        const named = left
+            ? ` ${left.length} row${left.length === 1 ? '' : 's'} (${left.slice(0, 10).join(', ')}${left.length > 10 ? ', …' : ''})`
+            : '';
+        console.error(`[presentation] ${agent.name}: presenting${named} at ${occasion} failed; ${next}:`, error);
+        this.host.emitTrace({
+            type: 'presentation:failed', agentName: agent.name, occasion, error: describe(error), ...(left ? { messageIds: left } : {}),
+        });
+    }
+}
+/** Whether `cm`'s window reads as presented; a mode that can't be read is not. */
+function readsPresented(cm) {
+    try {
+        return cm.windowMode() === 'presented';
+    }
+    catch {
+        return false;
+    }
+}
+/** The defined ids, each once, in order. */
+function unique(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (id === undefined || seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/** How many bodies a window holds, a sharded one counted once. */
+function bodyHeadCount(window) {
+    let count = 0;
+    for (let i = 0; i < window.length; i++)
+        if (i === 0 || !continuesBody(window[i - 1], window[i]))
+            count++;
+    return count;
+}
+/** The ids of the last `count` bodies of a window, by their first shards, in window order. */
+function lastBodyHeads(window, count) {
+    const heads = [];
+    for (let i = window.length - 1; i >= 0 && heads.length < count; i--) {
+        if (i === 0 || !continuesBody(window[i - 1], window[i]))
+            heads.unshift(window[i].id);
+    }
+    return heads;
+}
+//# sourceMappingURL=presentation.js.map