@animalabs/agent-framework 0.31.0 → 0.33.0

package/dist/src/deferred-import.d.ts

@@ -0,0 +1,93 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import type { MessageMetadata } from '@animalabs/context-manager';
+/** One write an earlier release queued, as its record held it. */
+export interface PersistedDeferredWrite {
+    /** Its durable identity: a copy of it that landed carries it as `metadata.deferredWriteId`. */
+    id: string;
+    /** Where it came in arrival order, 1..N over the entries kept. */
+    seq: number;
+    participant: string;
+    content: ContentBlock[];
+    metadata?: MessageMetadata;
+    /** The agent it was for. Absent means the primary. */
+    forAgent?: string;
+    /** When the earlier release first held it, in ms since the epoch, where the record says. */
+    heldAt?: number;
+    /**
+     * Set where a write of it threw and its store couldn't be read to tell
+     * whether it landed: before it is stored, its target's whole branch is
+     * searched for its id.
+     */
+    landing?: 'unknown';
+}
+/** What a queue's record held, as the importer takes it. */
+export interface PersistedQueue {
+    /** Its writes, in arrival order. */
+    entries: PersistedDeferredWrite[];
+    /**
+     * Per target agent, where its store stood when the oldest write handed to
+     * it and not yet acknowledged was handed over: the boot dedup scans from
+     * there (0 for an agent not named, the whole store).
+     */
+    scanFrom: Map<string, number>;
+    /**
+     * Whether reading it dropped, renumbered or named anything (a malformed
+     * entry, a repeated id, a missing or invalid seq, an entry given an id),
+     * so a record cleared or written again doesn't name those again.
+     */
+    changed: boolean;
+    /**
+     * The ids this read gave entries that had none. A read gives each a new
+     * one, so until the record holds it, a copy stored under it is one no
+     * later read finds by its id.
+     */
+    given: ReadonlySet<string>;
+}
+/** Where a queue's record is: the recovery file, or the store's slot. */
+export interface DeferredWritesRecord {
+    /** The recovery file the value was read from; absent where it was the slot's. */
+    file?: string;
+    /** The store's slot for it (framework/deferred-writes). */
+    slotId: string;
+}
+/**
+ * The refusal of a boot whose queue record can't be taken: it could not be
+ * read (`cause`), or it holds something other than a queue (`problem`
+ * alone). Either way the record is left as it is, and the error says what
+ * lets the framework start.
+ */
+export declare function deferredWritesRefusal(record: DeferredWritesRecord, problem: string, cause?: unknown): Error;
+/**
+ * Read a queue record's value: the recovery file's document, or the slot's
+ * value where there is no file (`record.file` absent).
+ *
+ * - Nothing stored is an empty queue: no file and nothing in the slot. A file
+ *   that holds null isn't a queue, since no release writes one.
+ * - The forms releases wrote are read: a bare array (the slot's first form),
+ *   and `{ pending, scanFrom? }` (version 1 and 2 files, version 2 slots).
+ *   Anything else is refused (deferredWritesRefusal).
+ * - An entry the importer can't store is dropped with a line naming it: one
+ *   whose participant isn't text, whose content isn't an array, that holds a
+ *   block that isn't an object, or whose `forAgent` is present but not a
+ *   name. A release wrote `forAgent` only as a non-empty name, so another
+ *   value is damage or a hand edit, and the agent it meant can't be known.
+ * - One entry per id: an id that comes again is dropped with a line, the
+ *   first entry with it kept. An entry with no id is given one, with a line
+ *   (`given`, and the queue reads as `changed`): a copy of it that landed
+ *   carries the id it lost, so the boot dedup can't find it, and it may be
+ *   stored again. Each read gives it a new id, so the importer writes the
+ *   record with the ids given before it stores any of them.
+ * - `heldAt` is kept where it is a time a Date can hold.
+ * - Arrival order: entries whose seq is a positive whole number up to
+ *   Number.MAX_SAFE_INTEGER by seq, then, in record order, those without one
+ *   (a record from before seq, in write order already) or with another value,
+ *   which is named. They are numbered 1..N in that order.
+ */
+export declare function readPersistedDeferredWrites(raw: unknown, record: DeferredWritesRecord, log: (line: string) => void): PersistedQueue;
+/**
+ * Whether an entry holds a tool block (tool_use or tool_result): of what a
+ * release queued, only the puppet's pair, which was the agent's own round,
+ * queued behind a turn that had replaced the puppet's reservation.
+ */
+export declare function isToolBlockEntry(entry: Pick<PersistedDeferredWrite, 'content'>): boolean;
+//# sourceMappingURL=deferred-import.d.ts.map

package/dist/src/deferred-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-import.d.ts","sourceRoot":"","sources":["../../src/deferred-import.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,+FAA+F;IAC/F,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAiB3G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,EAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC1B,cAAc,CAoFhB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,GAAG,OAAO,CAExF"}

package/dist/src/deferred-import.js

@@ -0,0 +1,177 @@
+/**
+ * The deferred-write queue an earlier release left on disk, read once at
+ * boot (#291, AF-6).
+ *
+ * Releases before #291's presentation index held a context write in a queue
+ * while its agent's turn was alive or the host was quiesced, and stored it
+ * at that agent's next boundary. While quiesced, and from a write that
+ * reached or may have reached its record until the queue drained, the queue
+ * was mirrored to `recovery/deferred-writes.json` beside the store, or, with
+ * no recovery path, to the store's `framework/deferred-writes` slot. This
+ * release stores every write at once and keeps no queue, so a record such a
+ * release left is read here, and the framework stores each of its writes
+ * once at boot (AgentFramework.importPersistedDeferredWrites), passes on or
+ * drops, logged, a write for an agent gone or one refused as malformed,
+ * keeps for the next boot one it can't store or check, with what follows it
+ * for that agent, and rewrites the record with only those. Like that
+ * importer, this module is for one release: the release
+ * after it deletes both. A host boots this release until its record is
+ * empty (the `deferred-import` alert says when writes stay queued), and
+ * doesn't upgrade past it from a release that kept a queue.
+ *
+ * Nothing here touches a store. It reads the record's value, refuses one
+ * that isn't a queue, drops entries its readers can't handle, keeps one entry
+ * per id, and orders them as they arrived.
+ */
+import { randomUUID } from 'node:crypto';
+/** A stored JSON value's kind, for a refusal that names what it found without its content. */
+function jsonKind(value) {
+    return value === null ? 'null'
+        : Array.isArray(value) ? 'an array'
+            : typeof value === 'object' ? 'an object'
+                : `a ${typeof value}`;
+}
+/**
+ * The refusal of a boot whose queue record can't be taken: it could not be
+ * read (`cause`), or it holds something other than a queue (`problem`
+ * alone). Either way the record is left as it is, and the error says what
+ * lets the framework start.
+ */
+export function deferredWritesRefusal(record, problem, cause) {
+    const { file, slotId } = record;
+    return new Error(`the deferred context writes (${file ?? slotId}) ${problem}. The framework doesn't start without them: an earlier ` +
+        `version left them queued, and they are stored at boot, ahead of anything written once the modules have ` +
+        `started. ` +
+        (file
+            ? `The file is unchanged, and the framework starts once ${cause === undefined
+                ? 'it holds a queue of writes, such as {"version":1,"pending":[]} for none. Removing it reads the queue ' +
+                    `from ${slotId} instead, which the file's writes don't keep, so it imports whatever older ` +
+                    `queue is there, or none`
+                : 'it can be read'}.`
+            : cause === undefined
+                ? `They're unchanged, and starting again won't help until they're repaired.`
+                : `They're unchanged, and the framework starts once they can be read.`), cause === undefined ? undefined : { cause });
+}
+/**
+ * Read a queue record's value: the recovery file's document, or the slot's
+ * value where there is no file (`record.file` absent).
+ *
+ * - Nothing stored is an empty queue: no file and nothing in the slot. A file
+ *   that holds null isn't a queue, since no release writes one.
+ * - The forms releases wrote are read: a bare array (the slot's first form),
+ *   and `{ pending, scanFrom? }` (version 1 and 2 files, version 2 slots).
+ *   Anything else is refused (deferredWritesRefusal).
+ * - An entry the importer can't store is dropped with a line naming it: one
+ *   whose participant isn't text, whose content isn't an array, that holds a
+ *   block that isn't an object, or whose `forAgent` is present but not a
+ *   name. A release wrote `forAgent` only as a non-empty name, so another
+ *   value is damage or a hand edit, and the agent it meant can't be known.
+ * - One entry per id: an id that comes again is dropped with a line, the
+ *   first entry with it kept. An entry with no id is given one, with a line
+ *   (`given`, and the queue reads as `changed`): a copy of it that landed
+ *   carries the id it lost, so the boot dedup can't find it, and it may be
+ *   stored again. Each read gives it a new id, so the importer writes the
+ *   record with the ids given before it stores any of them.
+ * - `heldAt` is kept where it is a time a Date can hold.
+ * - Arrival order: entries whose seq is a positive whole number up to
+ *   Number.MAX_SAFE_INTEGER by seq, then, in record order, those without one
+ *   (a record from before seq, in write order already) or with another value,
+ *   which is named. They are numbered 1..N in that order.
+ */
+export function readPersistedDeferredWrites(raw, record, log) {
+    const empty = { entries: [], scanFrom: new Map(), changed: false, given: new Set() };
+    if (!record.file && (raw === null || raw === undefined))
+        return empty;
+    const doc = (Array.isArray(raw) ? { pending: raw } : raw !== null && typeof raw === 'object' ? raw : undefined);
+    if (!doc || !Array.isArray(doc.pending)) {
+        throw deferredWritesRefusal(record, doc
+            ? `hold an object whose pending is ${doc.pending === undefined ? 'missing' : jsonKind(doc.pending)}, not a list of writes`
+            : `hold ${jsonKind(raw)}, not a queue of writes`);
+    }
+    const data = doc.pending;
+    if (data.length === 0)
+        return empty;
+    const scanFrom = new Map();
+    if (doc.scanFrom && typeof doc.scanFrom === 'object') {
+        for (const [k, v] of Object.entries(doc.scanFrom)) {
+            if (typeof v === 'number' && Number.isFinite(v))
+                scanFrom.set(k, Math.max(0, Math.floor(v)));
+        }
+    }
+    const wellFormed = (m) => {
+        if (!m || typeof m !== 'object')
+            return false;
+        const { participant, content, forAgent } = m;
+        return typeof participant === 'string'
+            && Array.isArray(content) && content.every((b) => !!b && typeof b === 'object')
+            && (forAgent === undefined || (typeof forAgent === 'string' && forAgent !== ''));
+    };
+    const malformed = data.filter((m) => !wellFormed(m));
+    for (const m of malformed) {
+        // What the entry holds there: a value that isn't text by its type.
+        const field = (key) => {
+            const value = m && typeof m === 'object' ? m[key] : undefined;
+            if (typeof value === 'string')
+                return value;
+            if (value === undefined)
+                return `no ${key}`;
+            return `${key} ${value === null ? 'null' : `of type ${typeof value}`}`;
+        };
+        log(`[host-mode] a recovered deferred context write is malformed and was dropped: ${field('id')} (${field('participant')})`);
+    }
+    const seen = new Set();
+    const given = new Set();
+    const kept = [];
+    let duplicates = 0;
+    for (const m of data.filter(wellFormed)) {
+        const hasId = typeof m.id === 'string' && m.id !== '';
+        const id = hasId ? m.id : randomUUID();
+        if (!hasId) {
+            given.add(id);
+            log(`[host-mode] a recovered deferred context write (${m.participant}) has no id; it is given ${id}`);
+        }
+        if (seen.has(id)) {
+            duplicates++;
+            log(`[host-mode] a recovered deferred context write repeats id ${id} (${m.participant}) and was dropped; the first entry with that id is kept`);
+            continue;
+        }
+        seen.add(id);
+        kept.push({
+            id,
+            seq: m.seq,
+            participant: m.participant,
+            content: m.content,
+            ...(m.metadata !== undefined ? { metadata: m.metadata } : {}),
+            ...(m.forAgent !== undefined ? { forAgent: m.forAgent } : {}),
+            // A Date holds times within 8.64e15 ms of the epoch.
+            ...(typeof m.heldAt === 'number' && Math.abs(m.heldAt) <= 8.64e15 ? { heldAt: m.heldAt } : {}),
+            ...(m.landing === 'unknown' ? { landing: 'unknown' } : {}),
+        });
+    }
+    const validSeq = (seq) => Number.isSafeInteger(seq) && seq > 0;
+    const unnumbered = kept.filter((m) => !validSeq(m.seq));
+    for (const m of unnumbered) {
+        if (m.seq === undefined)
+            continue;
+        // A value that isn't a number is named by its type: it could be any size.
+        const seq = typeof m.seq === 'number' ? String(m.seq) : m.seq === null ? 'null' : `of type ${typeof m.seq}`;
+        log(`[host-mode] a recovered deferred context write (${m.id}) has seq ${seq}, not a positive ` +
+            `whole number up to Number.MAX_SAFE_INTEGER; it is queued after the others`);
+    }
+    const ordered = [...kept.filter((m) => validSeq(m.seq)).sort((a, b) => a.seq - b.seq), ...unnumbered];
+    return {
+        entries: ordered.map((m, i) => ({ ...m, seq: i + 1 })),
+        scanFrom,
+        changed: malformed.length > 0 || duplicates > 0 || unnumbered.length > 0 || given.size > 0,
+        given,
+    };
+}
+/**
+ * Whether an entry holds a tool block (tool_use or tool_result): of what a
+ * release queued, only the puppet's pair, which was the agent's own round,
+ * queued behind a turn that had replaced the puppet's reservation.
+ */
+export function isToolBlockEntry(entry) {
+    return entry.content.some((block) => block.type === 'tool_use' || block.type === 'tool_result');
+}
+//# sourceMappingURL=deferred-import.js.map

package/dist/src/deferred-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-import.js","sourceRoot":"","sources":["../../src/deferred-import.ts"],"names":[],"mappings":"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"}

package/dist/src/dendrite/audience.d.ts

@@ -0,0 +1,223 @@
+/**
+ * The audience stamp (#291): who a stored row is for, written on the row
+ * when it is stored, in its metadata.
+ *
+ * A row's target used to live only in the write that stored it: the
+ * `forAgent` option, or which agent's context manager a writer called. In
+ * the residents' shared slot, rows meant for different agents then look
+ * alike in the store, and nothing read later can tell whose a row is. #291's
+ * presentation index decides from the row which agents it is presented to,
+ * and at boot which rows an agent has to be presented that it wasn't, so the
+ * framework now writes that on every row it stores:
+ *
+ * - `metadata.audience` lists the agents the row is meant for, computed when
+ *   it is written: the agent a write names (`forAgent`); for an admitted
+ *   inbound message, the recipients admission delivered it to; for a
+ *   module's process response whose inference request names agents, those
+ *   of them registered that read the slot it lands in. A write that names
+ *   no agent (a module's write, a process response that asks every agent
+ *   or none to read, or only agents that don't read that slot) is for the
+ *   agents that take untargeted inbound and own the slot it lands in: on a
+ *   residents' host every resident, as each reads the shared slot; with one
+ *   resident that resident alone, as before. It falls back to the agent the
+ *   write is delivered to when there are none.
+ *   This is the rule #291's presentation index presents an untargeted row
+ *   in the shared slot by, applied when the row is written, so the record
+ *   tells an untargeted row from one written for the primary. A message a
+ *   tune-out holds is meant for none of them, so its list is empty, unless
+ *   the write names an agent whose own view keeps held traffic (the
+ *   persistent subconscious), which it is for.
+ *   Observers of a slot (the subconscious watching the residents' slot) are
+ *   a relationship in the registry, not part of the list. An inbound
+ *   message's target is stamped as named even where it doesn't read the
+ *   slot the row lands in (a worker or a conversation fork, stored in the
+ *   residents' slot): how such a row is presented is left to the
+ *   presentation index. A process response's messages and the gate's
+ *   batched line are stamped for the agents they name that read that slot,
+ *   and as a write that names no agent when none of them does, so they
+ *   reach the windows that read the slot, as on main. The wake-onboarding
+ *   notice is stamped for its recipients that read that slot; one that
+ *   doesn't (a conversation fork) gets its own copy where it reads, stamped
+ *   for it, and the notice for an event with no recipients is for the
+ *   agents that take untargeted inbound.
+ * - `metadata.ownRowOf` names the agent whose own row it is: one stored by
+ *   that agent's turn or act (its rounds, its tool results, a puppeted
+ *   call), or by the framework for that agent's own turn (a clock row, a
+ *   `[continue]` row, a batched wake's line, a notice about its own speech
+ *   or failure, a derived agent's inheritance and framing). Its audience is
+ *   that agent alone. "Own" goes by who stored the row, never by its
+ *   participant: a shared fork presents its parent's name as its own voice,
+ *   but mail its parent sends it is the parent's, meant for the fork, and
+ *   isn't the fork's own row.
+ *
+ * Both keys are the framework's. A write through the framework's
+ * `addMessage` is stamped there and a stamp its metadata carried (a copy of
+ * a stored row's, say) is replaced, as `deferredWriteId` is, but on an
+ * imported write, which keeps the stamp it was queued with. The compile
+ * (context-manager's) doesn't read the stamp, so a window compiles as the
+ * same rows unstamped do; the presentation index does, so another
+ * resident's own rows no longer enter a resident's window unless it
+ * observes that resident (AgentConfig.observes). Rows stored before the
+ * stamp existed carry none; `audienceOf` says so by returning undefined. A
+ * write an earlier version left in its deferred queue is stamped when the
+ * importer stores it at boot, as any write through `addMessage` is, unless
+ * it was queued stamped, so it isn't stored unstamped after the upgrade.
+ */
+import type { ContentBlock } from '@animalabs/membrane';
+import type { AddMessageOptions, ContextManager, MessageId, MessageMetadata } from '@animalabs/context-manager';
+import type { AgentName, ObserveEdge } from './types.js';
+/** The metadata key listing who a row is for. */
+export declare const AUDIENCE_KEY = "audience";
+/** The metadata key naming whose own row a row is. */
+export declare const OWN_ROW_KEY = "ownRowOf";
+/** A row's audience stamp, as `audienceOf` reads it. */
+export interface AudienceStamp {
+    /** The agents the row is meant for, as computed when it was written. */
+    audience: AgentName[];
+    /** Set when the row is that agent's own (see the module comment). */
+    ownRowOf?: AgentName;
+}
+/**
+ * `metadata` stamped as a row meant for `audience`, and as nobody's own
+ * row: a stamp it carried is replaced. A new object; `metadata` is unchanged.
+ */
+export declare function withAudience(metadata: MessageMetadata | undefined, audience: readonly AgentName[]): MessageMetadata;
+/**
+ * `metadata` stamped as `owner`'s own row, meant for `owner` alone: a stamp
+ * it carried is replaced. A new object; `metadata` is unchanged.
+ */
+export declare function asOwnRow(metadata: MessageMetadata | undefined, owner: AgentName): MessageMetadata;
+/**
+ * The audience stamp a row's metadata carries, or undefined when it carries
+ * none (a row stored before the stamp existed) or carries one that isn't a
+ * list of names.
+ */
+export declare function audienceOf(metadata: unknown): AudienceStamp | undefined;
+/** Whether a row's metadata stamps it as `agent`'s own row. */
+export declare function isOwnRowOf(metadata: unknown, agent: AgentName): boolean;
+/**
+ * The admission record on a stored message: it was held from the residents
+ * by a policy epoch (`metadata.tuneOut = { epochId }`). ONE predicate for
+ * "held from the resident", read by the compiled-view filter, the mid-turn
+ * injection and the presentation index (#291) alike (#232 H1), so the window
+ * and the wire agree. Such a row is stamped for nobody (an empty audience),
+ * whatever store it lands in, unless its write names an agent whose own
+ * view keeps held traffic, such as the persistent subconscious, which it is
+ * for.
+ */
+export declare const heldFromResidents: (metadata: Record<string, unknown> | undefined) => boolean;
+/**
+ * The suppression record on a stored message: a suppress rule took it as it
+ * arrived (`metadata.suppressed = { rule, eventType }`, stamped by addMessage
+ * from the gate's suppressionFor). ONE predicate for "never rendered", read
+ * by every view filter the framework sets (the residents', the
+ * subconscious's, and through them every derived view's, context-options.ts)
+ * and so by agentSees too: the compile, a tool boundary's injection and the
+ * arrival and unread checks agree. The presentation index (#291) presents
+ * such a row to nobody (bearingOf, observedRowFor), the reader of held
+ * traffic included, and addMessage stamps it for nobody (an empty
+ * audience). The stamp never changes, so the view stays deterministic per
+ * row, as context-manager's viewFilter requires.
+ */
+export declare const suppressedRow: (metadata: Record<string, unknown> | undefined) => boolean;
+/**
+ * Whether a row of a slot an agent observes is for that agent (#291,
+ * decision 1): what an observe edge shows of the slot it reads. `observer`
+ * is the agent the edge is on, and `owners` are the agents whose own slot it
+ * reads (the registry's `slotOwners`).
+ *
+ * - Another agent's stored context injection: no. It is that agent's
+ *   context, not conversation, as every view of the framework's leaves out.
+ * - A row stored under the observer's own name: no. It is the observer's
+ *   delivery into the slot (the subconscious's summary or note into the
+ *   residents' slot), which its own round already holds.
+ * - A row a suppress rule hid (suppressedRow): no. It renders for no
+ *   reader, the reader of held traffic included.
+ * - A row a tune-out holds: only through an edge that shows held traffic
+ *   (`includeHeld`, the subconscious's).
+ * - A row with no audience stamp (stored before the stamp, or by a host's
+ *   writer that doesn't stamp): yes, as the merged view showed it.
+ * - An owner's own row (its rounds, results, clock rows, notices about its
+ *   own turn), and a row whose audience names an owner (channel traffic,
+ *   mail, module rows): yes.
+ * - A row whose audience names the observer itself, and that is nobody's
+ *   own row (an operator's message or a module's write addressed to the
+ *   subconscious alone, which lands in the residents' slot it watches):
+ *   yes. The edge is how the observer reads that slot, and the merged view
+ *   showed the row before the presentation index, so no window would hold
+ *   it otherwise (#291).
+ * - Anything else, such as the own row of an agent that doesn't own the
+ *   slot (the observer's own included), a row stamped only for an agent
+ *   that neither owns nor observes the slot, or one for a derived agent on
+ *   another branch: no.
+ */
+export declare function observedRowFor(edge: Pick<ObserveEdge, 'includeHeld'>, row: {
+    participant: string;
+    metadata?: unknown;
+}, context: {
+    observer: AgentName;
+    owners: readonly AgentName[];
+}): boolean;
+/** What `storeOwnRow` writes through: an agent, or anything that names one and holds its context. */
+export interface OwnRowWriter {
+    readonly name: AgentName;
+    /** With `getMessage`, a write whose outcome the store can't tell presents
+     *  the rows it may have stored that the store reads as held
+     *  (presentLandedThenRethrow); without it, only those it knows landed. */
+    getContextManager(): Pick<ContextManager, 'addMessage'> & Partial<Pick<ContextManager, 'getMessage'>>;
+    /**
+     * Told the ids of the agent's own rows once they are stored (the
+     * presentation index's own-row sink, #291), each once its write has
+     * returned. A writer without it is told nothing.
+     */
+    ownRowsStored?(ids: readonly MessageId[]): void;
+}
+/**
+ * Store a row in `agent`'s own context, stamped as its own row (asOwnRow).
+ * Every writer that stores into an agent's context directly, past the
+ * framework's `addMessage`, stores the agent's own rows through this, but
+ * the tool-result guard, which stamps the results it writes itself
+ * (asOwnRow, ToolResultGuard.storeResults) and tells its own-row sink of
+ * them, so none of them goes unstamped.
+ *
+ * With `present` (the default), the writer is told of the row once the add
+ * has returned (`ownRowsStored`), never from inside it, where a sharded body
+ * may still be storing its shards: under the presentation index (#291) that
+ * presents the row in the agent's window at once. That is right 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, and one written while the agent has no turn alive. A row
+ * written at another moment, where a turn the row isn't part of may be
+ * alive, passes `present: false`: it stays stored and out of the window,
+ * and the index's own-row sweep at the agent's next presentation point
+ * presents it there.
+ */
+export declare function storeOwnRow(agent: OwnRowWriter, participant: string, content: ContentBlock[], metadata?: MessageMetadata, options?: AddMessageOptions, present?: boolean): MessageId;
+/**
+ * The catch of a write of an agent's own row whose add threw (storeOwnRow,
+ * and the tool-result guard's two writes of the results row): the rows of
+ * the write the store holds are told to `told`, the own-row sink, as the
+ * write's id would have been, then the add's error is thrown on. The write
+ * is answered by that error, as before the presentation index: what its
+ * caller does on it is the caller's. A row of it that is stored is out of
+ * the window until presented, like any stored row, and presented here so
+ * that an own row written after it can't enter the window ahead of it.
+ *
+ * - WriteLandedError: its `landed` rows, in store order.
+ * - WriteOutcomeUnknownError: its `landed` rows, then those its `unknown`
+ *   names (the store holds all of these or none) that `holds` reads as
+ *   stored, as addMessage presents such a write's rows (presentedThoughUnknown
+ *   in framework.ts, whose afterStore reads the rows too). Where that read
+ *   throws, every row `unknown` names, as presentedThoughUnknown gives them:
+ *   the sink keeps a row it can't present and presents it ahead of the next
+ *   own row, dropping one the store doesn't hold (presentOwn), so a landed
+ *   row isn't put behind an own row written after it. Without `holds`, its
+ *   `landed` rows only.
+ * - Any other error: none of the write is stored, so nothing is told.
+ *
+ * Without `told` (a writer that holds its row back, storeOwnRow's
+ * `present: false`, or one with no sink) nothing is told. A sink that
+ * throws is logged; the add's error is the one thrown.
+ */
+export declare function presentLandedThenRethrow(error: unknown, agentName: string, told: ((ids: readonly MessageId[]) => void) | undefined, holds?: (id: MessageId) => boolean): never;
+//# sourceMappingURL=audience.d.ts.map

package/dist/src/dendrite/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../../../src/dendrite/audience.ts"],"names":[],"mappings":"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"}