@haywoodmarx/agent-pager 0.1.0

package/dist/src/broker/operator-projection.js

@@ -0,0 +1,722 @@
+import { BROKER_OPERATOR_TRAFFIC_LIMIT, decodeMessageBody, isAgentId, isOpaqueId, LIFECYCLE_EVENT_STATE, ProtocolError, } from "./protocol.js";
+import { normalizeAlias } from "./address.js";
+import { AGENT_STATES, MESSAGE_EVENT_SOURCES, MESSAGE_EVENT_TONES, MESSAGE_STATES, MESSAGE_UNORDERABLE_POSITION, orderablePosition, PING_UNORDERABLE_POSITION, unorderablePosition, } from "./schema.js";
+/** Event types that observe a delivery state, in the order the vocabulary declares them. */
+const STATE_OBSERVING_EVENT_TYPES = Object.entries(LIFECYCLE_EVENT_STATE)
+    .filter(([, state]) => state !== null)
+    .map(([type]) => type);
+const RETAINED_AGENT_PREDICATE = `not (
+  agents.state = 'reaped'
+  and agents.registration_ephemeral = 1
+  and not exists (select 1 from messages where sender_id = agents.id or recipient_id = agents.id)
+  and not exists (select 1 from operator_ping_audits where target_agent_id = agents.id)
+)`;
+/**
+ * Caps how many values one statement binds in an `in (...)` list.
+ *
+ * bun:sqlite has not been observed to reject an oversize parameter list, so this is not working
+ * around a measured failure; it bounds how large one statement's parameter list grows for a
+ * projection over an otherwise-unbounded row count, splitting into runs instead.
+ */
+const SQL_PARAMETER_LIMIT = 500;
+/** Bounds how recent a delivery failure must be for the broker to report itself degraded. */
+const RECENT_FAILURE_WINDOW_MS = 30_000;
+/** Caps how many operational events the broker retains in memory, oldest dropped first. */
+const OPERATIONAL_EVENT_LIMIT = 4_096;
+/**
+ * Read the stored columns a delivery projection narrows, reporting a row that cannot supply them.
+ *
+ * Never throws over a row: this read feeds the operator update stream, which a throw leaves
+ * permanently unavailable.
+ * @param message - Durable `messages` row being projected.
+ * @returns - The narrowed columns, or the ones that could not be read.
+ */
+function readableColumns(message) {
+    const unreadable = [
+        MESSAGE_STATES.some((candidate) => candidate === message.state) ? null : "state",
+        isAgentId(message.sender_id) ? null : "sender_id",
+        isAgentId(message.recipient_id) ? null : "recipient_id",
+        isTrafficPosition(message.sequence) ? null : "sequence",
+        typeof message.body === "string" ? null : "body",
+        typeof message.body_size === "number" ? null : "body_size",
+        typeof message.content_type === "string" ? null : "content_type",
+    ].filter((column) => column !== null);
+    if (unreadable.length > 0)
+        return { unreadable };
+    return {
+        sequence: message.sequence,
+        state: readStoredEnum(message.state, MESSAGE_STATES, "messages.state"),
+        senderAgentId: readStoredAgentId(message.sender_id, "messages.sender_id"),
+        recipientAgentId: readStoredAgentId(message.recipient_id, "messages.recipient_id"),
+        encodedBody: message.body,
+        bodySizeBytes: message.body_size,
+        contentType: message.content_type,
+    };
+}
+/**
+ * Read the stored columns a ping audit narrows, reporting a row that cannot supply them.
+ *
+ * Never throws over a row: the ping and message halves share one window on one stream.
+ * @param ping - Durable `operator_ping_audits` row being projected.
+ * @returns - The narrowed columns, or the ones that could not be read.
+ */
+function readablePingColumns(ping) {
+    const unreadable = [
+        ping.actor === "operator" ? null : "actor",
+        isAgentId(ping.target_agent_id) ? null : "target_agent_id",
+        isTrafficPosition(ping.traffic_position) ? null : "traffic_position",
+    ].filter((column) => column !== null);
+    if (unreadable.length > 0)
+        return { unreadable };
+    return {
+        actor: "operator",
+        targetAgentId: readStoredAgentId(ping.target_agent_id, "operator_ping_audits.target_agent_id"),
+        trafficPosition: ping.traffic_position,
+    };
+}
+/**
+ * Report whether a stored column can serve as a durable traffic position.
+ * @param value - Column value as the driver returned it.
+ * @returns - True when the value is a positive safe integer.
+ */
+function isTrafficPosition(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+/**
+ * Read the stored columns an agent projection narrows, reporting a row that cannot supply them.
+ *
+ * Never throws over a row: this read feeds the operator update stream.
+ * @param agent - Durable `agents` row being projected.
+ * @returns - The narrowed columns, or the ones that could not be read.
+ */
+function readableAgentColumns(agent) {
+    const unreadable = [
+        isAgentId(agent.id) ? null : "id",
+        AGENT_STATES.some((candidate) => candidate === agent.state) ? null : "state",
+    ].filter((column) => column !== null);
+    if (unreadable.length > 0)
+        return { unreadable };
+    return {
+        id: readStoredAgentId(agent.id, "agents.id"),
+        state: readStoredEnum(agent.state, AGENT_STATES, "agents.state"),
+    };
+}
+/**
+ * Identify what one operational event observes, so the same observation is recognised again.
+ *
+ * Two identical sheds share a key, which is why the ring's index counts rather than flags.
+ * @param event - Operational event being recorded.
+ * @returns - Key equal for two events observing the same thing.
+ */
+function ringKey(event) {
+    if (event.type === "message_shed")
+        return JSON.stringify(event);
+    if (event.type === "stored_row_skipped")
+        return `${event.type}\u0000${event.column}\u0000${event.rowKey}`;
+    if (event.type === "skips_truncated")
+        return `${event.type}\u0000${event.table}\u0000${String(event.named)}\u0000${String(event.total)}`;
+    const rowId = event.type === "agent_row_skipped"
+        ? event.agentId
+        : event.type === "ping_row_skipped"
+            ? event.auditId
+            : event.messageId;
+    return `${event.type}\u0000${rowId}\u0000${event.unreadable.join("\u0001")}`;
+}
+/**
+ * Name a skipped row by its durable id, or by its rowid when the id is not text.
+ * @param id - The row's id column as the driver returned it.
+ * @param rowid - The row's rowid.
+ * @returns - A name that tells two such rows apart.
+ */
+function skippedRowName(id, rowid) {
+    return typeof id === "string" ? id : `rowid ${String(rowid)}`;
+}
+/**
+ * Copy one operational event deeply enough that a caller cannot rewrite retained history.
+ *
+ * A spread alone leaves the event's own array shared with the copy the projection keeps.
+ * @param event - Retained event being handed to a caller.
+ * @returns - Copy that shares no mutable structure with the retained one.
+ */
+function cloneOperationalEvent(event) {
+    return event.type === "message_shed" || event.type === "stored_row_skipped" || event.type === "skips_truncated"
+        ? { ...event }
+        : { ...event, unreadable: [...event.unreadable] };
+}
+function chunked(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size)
+        chunks.push(values.slice(index, index + size));
+    return chunks;
+}
+/**
+ * Read one stored column against the vocabulary its `check` constraint admits.
+ *
+ * Throws; a caller that cannot afford a throw must not call it.
+ * @param value - Column value as the driver returned it.
+ * @param allowed - Vocabulary the column's constraint admits.
+ * @param column - Column named in the rejection, qualified by its table.
+ * @returns - The value, narrowed to the vocabulary.
+ */
+export function readStoredEnum(value, allowed, column) {
+    const known = allowed.find((candidate) => candidate === value);
+    if (known === undefined)
+        throw new ProtocolError("validation_failed", `Stored ${column} is corrupt`);
+    return known;
+}
+/**
+ * Read a stored agent identifier, refusing one this build could not have written.
+ * @param value - Column value as the driver returned it.
+ * @param column - Column named in the rejection.
+ * @returns - The value, narrowed to an agent identity.
+ */
+export function readStoredAgentId(value, column) {
+    if (!isAgentId(value))
+        throw new ProtocolError("validation_failed", `Stored ${column} is corrupt`);
+    return value;
+}
+/**
+ * Assert an untrusted value has the shape of a durable operator-facing identity.
+ * @param value - Untrusted candidate identity.
+ * @param label - Names the identity kind for the rejection message.
+ * @returns - The value, narrowed to a validated durable identity string.
+ */
+export function assertDurableOperatorId(value, label) {
+    if (!isOpaqueId(value))
+        throw new ProtocolError("validation_failed", `Invalid operator ${label} identity`);
+    return value;
+}
+function assertDurableAgentId(value) {
+    if (!isAgentId(value))
+        throw new ProtocolError("validation_failed", "Operator command target is corrupt");
+}
+/**
+ * Reads durable operator-facing state over a broker connection: traffic records, command
+ * idempotency, and snapshot projections. Holds the in-memory operational event log, which only this
+ * projection reads.
+ */
+export class BrokerOperatorProjection {
+    #db;
+    #now;
+    #operationalEvents = [];
+    /**
+     * Counts of what the ring currently holds, by observation.
+     *
+     * Through `#recordOnce`, an observation is recorded once while the ring holds it, and again once a
+     * later event has evicted it.
+     */
+    #ringKeys = new Map();
+    /**
+     * Bind operator projection reads to one connection.
+     * @param db - Connection this projection reads.
+     * @param now - Clock shared with the rest of the broker.
+     */
+    constructor(db, now) {
+        this.#db = db;
+        this.#now = now;
+    }
+    /**
+     * Record a shed-message operational event for later diagnostic reporting.
+     * @param event - Operational event describing the shed policy and its target.
+     */
+    recordShed(event) {
+        this.#record(event);
+    }
+    #record(event, key = ringKey(event)) {
+        this.#operationalEvents.push({ event, key });
+        this.#ringKeys.set(key, (this.#ringKeys.get(key) ?? 0) + 1);
+        if (this.#operationalEvents.length > OPERATIONAL_EVENT_LIMIT) {
+            const evicted = this.#operationalEvents.shift();
+            if (evicted !== undefined) {
+                const held = (this.#ringKeys.get(evicted.key) ?? 1) - 1;
+                if (held > 0)
+                    this.#ringKeys.set(evicted.key, held);
+                else
+                    this.#ringKeys.delete(evicted.key);
+            }
+        }
+    }
+    /**
+     * Record one durable row whose stored column the broker could not read, unless the ring holds it.
+     * @param event - Row and column the caller could not read.
+     * @returns - True when this call recorded it, so the caller knows whether to also say so.
+     */
+    recordStoredRowSkip(event) {
+        return this.#recordOnce(event);
+    }
+    /**
+     * Record an observation the ring is not already holding.
+     * @param event - Observation to record if it is not already in the ring.
+     * @param key - Ring identity to hold it under, when the event's own fields cannot supply one.
+     * @returns - True when this call recorded it.
+     */
+    #recordOnce(event, key = ringKey(event)) {
+        if (this.#ringKeys.has(key))
+            return false;
+        this.#record(event, key);
+        return true;
+    }
+    /**
+     * Return operational events recorded since the broker started.
+     * @returns - Copy of every retained operational event, oldest first.
+     */
+    operationalEvents() {
+        return this.#operationalEvents.map((held) => cloneOperationalEvent(held.event));
+    }
+    /**
+     * Read bounded durable traffic without claiming, acknowledging, or changing retained bodies.
+     * @returns Traffic source rows in their single broker-owned durable order.
+     */
+    operatorTrafficRecords() {
+        const messages = this.#db
+            .prepare(`select rowid, id, team_id, workspace_id, sender_id, recipient_id, addressed_to, address_outcome, subject, type, body, body_size, content_type, state, created_at, sequence from messages where ${orderablePosition("sequence")} order by sequence desc limit ?`)
+            .all(BROKER_OPERATOR_TRAFFIC_LIMIT);
+        const pings = this.#db
+            .prepare(`select rowid, audit_id, control_id, target_agent_id, actor, accepted_at, traffic_position from operator_ping_audits where ${orderablePosition("traffic_position")} order by traffic_position desc limit ?`)
+            .all(BROKER_OPERATOR_TRAFFIC_LIMIT);
+        const window = [
+            ...messages.map((row) => ({ kind: "message", row, position: Number(row.sequence) })),
+            ...pings.map((row) => ({ kind: "ping", row, position: Number(row.traffic_position) })),
+        ]
+            .sort((left, right) => right.position - left.position)
+            .slice(0, BROKER_OPERATOR_TRAFFIC_LIMIT)
+            .sort((left, right) => left.position - right.position);
+        const lifecycleByMessage = this.#trafficEventsForWindow(window.filter((entry) => entry.kind === "message").map((entry) => String(entry.row.id)));
+        const skips = [];
+        const records = window.flatMap((entry) => {
+            if (entry.kind === "ping")
+                return [];
+            const message = entry.row;
+            const stored = readableColumns(message);
+            if ("unreadable" in stored) {
+                const skip = {
+                    type: "traffic_row_skipped",
+                    messageId: skippedRowName(message.id, message.rowid),
+                    unreadable: stored.unreadable,
+                };
+                // Copied on the way out for the same reason operationalEvents() copies: what the ring keeps
+                // is the projection's, and this exit hands the caller the same object the ring is given.
+                skips.push(cloneOperationalEvent(skip));
+                // Held under the rowid: `messages.id` is not among the columns checked here.
+                this.#recordOnce(skip, `traffic_row_skipped\u0000${String(message.rowid)}`);
+                return [];
+            }
+            const lifecycle = lifecycleByMessage.get(String(message.id)) ?? [];
+            return [
+                {
+                    kind: "accepted_delivery",
+                    messageId: String(message.id),
+                    trafficPosition: stored.sequence,
+                    teamId: String(message.team_id),
+                    workspaceId: String(message.workspace_id),
+                    acceptedAt: Number(message.created_at),
+                    subject: String(message.subject),
+                    type: String(message.type),
+                    ...stored,
+                    lifecycle,
+                },
+            ];
+        });
+        records.push(...window.flatMap((entry) => {
+            if (entry.kind === "message")
+                return [];
+            const ping = entry.row;
+            const stored = readablePingColumns(ping);
+            if ("unreadable" in stored) {
+                const skip = {
+                    type: "ping_row_skipped",
+                    auditId: skippedRowName(ping.audit_id, ping.rowid),
+                    unreadable: stored.unreadable,
+                };
+                skips.push(cloneOperationalEvent(skip));
+                this.#recordOnce(skip, `ping_row_skipped\u0000${String(ping.rowid)}`);
+                return [];
+            }
+            return [
+                {
+                    kind: "ping_audit",
+                    auditId: String(ping.audit_id),
+                    trafficPosition: stored.trafficPosition,
+                    controlId: String(ping.control_id),
+                    targetAgentId: stored.targetAgentId,
+                    actor: stored.actor,
+                    acceptedAt: Number(ping.accepted_at),
+                },
+            ];
+        }));
+        this.#nameUnorderable(MESSAGE_UNORDERABLE_POSITION, (rowKey, id) => {
+            const skip = { type: "traffic_row_skipped", messageId: id, unreadable: ["sequence"] };
+            skips.push(cloneOperationalEvent(skip));
+            this.#recordOnce(skip, `traffic_row_skipped\u0000${rowKey}`);
+        }, (truncated) => skips.push(truncated));
+        this.#nameUnorderable(PING_UNORDERABLE_POSITION, (rowKey, id) => {
+            const skip = {
+                type: "ping_row_skipped",
+                auditId: id,
+                unreadable: ["traffic_position"],
+            };
+            skips.push(cloneOperationalEvent(skip));
+            this.#recordOnce(skip, `ping_row_skipped\u0000${rowKey}`);
+        }, (truncated) => skips.push(truncated));
+        records.sort((left, right) => left.trafficPosition - right.trafficPosition);
+        return { records, skips };
+    }
+    /**
+     * Return a prior operator command acceptance for idempotent request handling.
+     * @param commandId - Opaque command correlation supplied by the operator boundary.
+     * @returns Stored acceptance, or null when this command has not been accepted.
+     */
+    operatorCommand(commandId) {
+        assertDurableOperatorId(commandId, "command");
+        const row = this.#db.prepare("select * from operator_commands where command_id = ?").get(commandId);
+        if (!row)
+            return null;
+        assertDurableOperatorId(row.command_id, "command");
+        const acceptedAt = Number(row.accepted_at);
+        if (!Number.isSafeInteger(acceptedAt) || acceptedAt < 0) {
+            throw new ProtocolError("validation_failed", "Operator command is corrupt");
+        }
+        if (row.type === "ping_agent") {
+            if (typeof row.control_id !== "string")
+                throw new ProtocolError("validation_failed", "Ping command is corrupt");
+            assertDurableOperatorId(row.control_id, "control");
+            assertDurableAgentId(row.target_id);
+            return {
+                type: "ping_agent",
+                commandId: String(row.command_id),
+                targetId: row.target_id,
+                acceptedAt,
+                controlId: row.control_id,
+            };
+        }
+        if (row.type === "archive_agent") {
+            assertDurableAgentId(row.target_id);
+            return { type: "archive_agent", commandId: String(row.command_id), targetId: row.target_id, acceptedAt };
+        }
+        if (row.type !== "expire_message") {
+            throw new ProtocolError("validation_failed", "Operator command is corrupt");
+        }
+        return {
+            type: "expire_message",
+            commandId: String(row.command_id),
+            targetId: assertDurableOperatorId(row.target_id, "message"),
+            acceptedAt,
+        };
+    }
+    /**
+     * Read a durable message body without claiming or changing it.
+     * @param messageId - Durable message whose retained body is being read.
+     * @returns - Decoded body, its raw stored copy, and its retained size and representation.
+     */
+    readMessageBody(messageId) {
+        const row = this.#db.prepare("select body, body_size, content_type from messages where id = ?").get(messageId);
+        if (!row || typeof row.body !== "string")
+            throw new ProtocolError("validation_failed", "Unknown message");
+        let body;
+        try {
+            body = decodeMessageBody(row.body);
+        }
+        catch {
+            throw new ProtocolError("validation_failed", "Stored message body is not valid JSON");
+        }
+        const contentType = typeof row.content_type === "string" ? row.content_type : "json";
+        return {
+            messageId,
+            body,
+            rawCopy: contentType === "text" && typeof body === "string" ? body : row.body,
+            sizeBytes: Number(row.body_size ?? Buffer.byteLength(row.body)),
+            contentType,
+        };
+    }
+    /**
+     * Return the agent-derived state an operator projection reads, without any delivery.
+     * @param workspaceId - Restricts the read to one workspace, or reads every workspace.
+     * @returns - Agent-derived snapshot sections only.
+     */
+    readAgentSource(workspaceId) {
+        const now = this.#now();
+        const activeWorkspace = workspaceId ?? null;
+        const agents = this.#db
+            .prepare(activeWorkspace
+            ? `select rowid, * from agents where workspace_id = ? and ${RETAINED_AGENT_PREDICATE} order by created_at, id`
+            : `select rowid, * from agents where ${RETAINED_AGENT_PREDICATE} order by created_at, id`)
+            .all(...(activeWorkspace ? [activeWorkspace] : []));
+        const aliasHistory = this.#db.prepare("select agent_id, alias from alias_history order by id").all();
+        const previousAliasesByAgent = new Map();
+        for (const row of aliasHistory) {
+            const agentId = String(row.agent_id);
+            const aliases = previousAliasesByAgent.get(agentId) ?? [];
+            aliases.push(String(row.alias));
+            previousAliasesByAgent.set(agentId, aliases);
+        }
+        const sessions = this.#db
+            .prepare("select agent_id, expires_at, active, created_at from sessions order by agent_id, created_at")
+            .all();
+        const sessionsByAgent = new Map();
+        for (const row of sessions) {
+            if (Number(row.active) !== 1)
+                continue;
+            const agentId = String(row.agent_id);
+            const current = sessionsByAgent.get(agentId);
+            const candidateAttached = Number(row.expires_at) > now;
+            const currentAttached = current !== undefined && Number(current.expires_at) > now;
+            if (current === undefined ||
+                (candidateAttached && !currentAttached) ||
+                (candidateAttached === currentAttached && Number(row.created_at) > Number(current.created_at))) {
+                sessionsByAgent.set(agentId, row);
+            }
+        }
+        const projected = agents.flatMap((agent) => {
+            const stored = readableAgentColumns(agent);
+            if ("unreadable" in stored) {
+                // Held under the rowid: `agents.id` may be the column that failed.
+                this.#recordOnce({ type: "agent_row_skipped", agentId: skippedRowName(agent.id, agent.rowid), unreadable: stored.unreadable }, `agent_row_skipped\u0000${String(agent.rowid)}`);
+                return [];
+            }
+            return [{ agent, stored }];
+        });
+        return {
+            workspaces: this.#workspaceSummaries(),
+            agents: projected.map(({ agent, stored }) => {
+                return {
+                    id: stored.id,
+                    createdAt: Number(agent.created_at),
+                    teamId: String(agent.team_id),
+                    workspaceId: String(agent.workspace_id),
+                    parentId: typeof agent.parent_id === "string" ? agent.parent_id : null,
+                    state: stored.state,
+                    implementation: typeof agent.implementation_id === "string"
+                        ? {
+                            id: agent.implementation_id,
+                            version: typeof agent.implementation_version === "string"
+                                ? { known: true, value: agent.implementation_version }
+                                : { known: false },
+                        }
+                        : { id: null, version: { known: false } },
+                    alias: normalizeAlias(String(agent.registration_name)),
+                    previousAliases: previousAliasesByAgent.get(String(agent.id)) ?? [],
+                    archivedAt: typeof agent.archived_at === "number" ? agent.archived_at : null,
+                };
+            }),
+            // The same rows the projection above kept: an agent it left out is not a connection to report.
+            connections: projected.map(({ agent }) => {
+                const session = sessionsByAgent.get(String(agent.id));
+                return {
+                    agentId: String(agent.id),
+                    state: session && Number(session.expires_at) > now ? "connected" : "disconnected",
+                    expiresAt: session ? Number(session.expires_at) : null,
+                    lastSeenAt: session ? Number(session.created_at) : null,
+                };
+            }),
+        };
+    }
+    /**
+     * Read the complete broker snapshot, optionally scoped to one workspace.
+     *
+     * Never writes, so claim state is as the last `Broker.expireClaims` left it.
+     * @param workspaceId - Restricts the read to one workspace's agents and the messages they sent or
+     * received, or reads every workspace.
+     * @param sequence - Snapshot sequence stamp, taken by the caller from the shared clock.
+     * @param health - Broker generation and durability, computed by the caller from owned state.
+     * @returns - Broker snapshot, optionally scoped to the requested workspace.
+     */
+    readSnapshot(workspaceId, sequence, health) {
+        const activeWorkspace = workspaceId ?? null;
+        const agentSource = this.readAgentSource(workspaceId);
+        const messages = this.#db
+            .prepare(activeWorkspace
+            ? "select rowid, id, team_id, workspace_id, sender_id, recipient_id, addressed_to, address_outcome, subject, type, state, created_at, claim_expires_at, sequence, body, body_size, content_type from messages where workspace_id = ? or recipient_id in (select id from agents where workspace_id = ?) order by sequence"
+            : "select rowid, id, team_id, workspace_id, sender_id, recipient_id, addressed_to, address_outcome, subject, type, state, created_at, claim_expires_at, sequence, body, body_size, content_type from messages order by sequence")
+            .all(...(activeWorkspace ? [activeWorkspace, activeWorkspace] : []));
+        const claims = this.#db
+            .prepare("select message_id, count(*) as attempts from claims group by message_id")
+            .all();
+        const attemptsByMessage = new Map(claims.map((row) => [String(row.message_id), Number(row.attempts)]));
+        const lifecycleByMessage = this.#eventsForMessages(messages.map((message) => String(message.id)));
+        // Skip-and-name, through the same guard as the traffic window so the two agree on which rows exist.
+        const deliveries = messages.flatMap((message) => {
+            const messageId = String(message.id);
+            const stored = readableColumns(message);
+            if ("unreadable" in stored) {
+                this.#recordOnce({
+                    type: "traffic_row_skipped",
+                    messageId: skippedRowName(message.id, message.rowid),
+                    unreadable: stored.unreadable,
+                }, `traffic_row_skipped\u0000${String(message.rowid)}`);
+                return [];
+            }
+            return [
+                {
+                    messageId,
+                    sequence: stored.sequence,
+                    teamId: String(message.team_id),
+                    workspaceId: String(message.workspace_id),
+                    from: stored.senderAgentId,
+                    to: stored.recipientAgentId,
+                    subject: String(message.subject),
+                    type: String(message.type),
+                    state: stored.state,
+                    createdAt: Number(message.created_at),
+                    attempts: attemptsByMessage.get(messageId) ?? 0,
+                    body: { sizeBytes: stored.bodySizeBytes, contentType: stored.contentType },
+                    lifecycle: lifecycleByMessage.get(messageId) ?? [],
+                },
+            ];
+        });
+        return {
+            version: 1,
+            sequence,
+            health,
+            ...agentSource,
+            deliveries,
+            diagnostics: {
+                connectionState: this.#connectionState(),
+                operationalEvents: this.operationalEvents(),
+            },
+        };
+    }
+    /**
+     * Name every row of one table whose stored position this build cannot order, up to the window bound.
+     *
+     * Reports every such row on every call, with no dedup across reads: this channel is live, and what
+     * an operator sees must not depend on when they connected. The ring is the deduplicated view.
+     * @param index - Partial index over the table's unorderable rows, which both reads go through.
+     * @param name - Called per row with its rowid and its durable identity.
+     * @param truncate - Called once when the table holds more such rows than the bound.
+     */
+    #nameUnorderable(index, name, truncate) {
+        // `indexed by` pins both reads to the partial index; the planner does not choose it for a count
+        // on a database that has never been analysed.
+        const from = `from ${index.table} indexed by ${index.name} where ${unorderablePosition(index.position)}`;
+        const rows = this.#db
+            .prepare(`select rowid, ${index.column} as id ${from} order by ${index.column} limit ?`)
+            .all(BROKER_OPERATOR_TRAFFIC_LIMIT);
+        if (rows.length === 0)
+            return;
+        for (const row of rows)
+            name(String(row.rowid), skippedRowName(row.id, row.rowid));
+        if (rows.length < BROKER_OPERATOR_TRAFFIC_LIMIT)
+            return;
+        const total = Number(this.#db.prepare(`select count(*) as total ${from}`).get().total);
+        if (total > rows.length) {
+            const truncated = {
+                type: "skips_truncated",
+                table: index.table,
+                named: rows.length,
+                total,
+            };
+            truncate(cloneOperationalEvent(truncated));
+            this.#recordOnce(truncated);
+        }
+    }
+    /**
+     * Read the lifecycle of many messages in one pass, because the snapshot is rebuilt on every commit.
+     * @param messageIds - Messages whose lifecycles the projection needs.
+     * @returns - Lifecycle entries by message id, ordered oldest first.
+     */
+    #eventsForMessages(messageIds) {
+        const unique = new Set(messageIds);
+        const grouped = new Map();
+        if (unique.size === 0)
+            return grouped;
+        const rows = this.#eventRows([...unique], "*");
+        for (const row of rows) {
+            const source = MESSAGE_EVENT_SOURCES.find((candidate) => candidate === row.source);
+            const tone = MESSAGE_EVENT_TONES.find((candidate) => candidate === row.tone);
+            const messageId = String(row.message_id);
+            // Per-row degrade: the delivery still projects, one observation short.
+            if (source === undefined || tone === undefined) {
+                const unreadable = [source === undefined ? "source" : null, tone === undefined ? "tone" : null].filter((column) => column !== null);
+                // Held under the lifecycle row's id: two bad entries on one delivery are two reports.
+                this.#recordOnce({ type: "lifecycle_entry_skipped", messageId, unreadable }, `lifecycle_entry_skipped\u0000${String(row.id)}`);
+                continue;
+            }
+            const lifecycle = grouped.get(messageId) ?? [];
+            lifecycle.push({
+                id: Number(row.id),
+                messageId,
+                at: Number(row.at),
+                source,
+                type: String(row.type),
+                text: String(row.text),
+                tone,
+            });
+            grouped.set(messageId, lifecycle);
+        }
+        return grouped;
+    }
+    /**
+     * Read the lifecycle of every message in one traffic window in one pass.
+     *
+     * A message whose lifecycle reaches the window limit still needs the truncation and latest-state
+     * reconciliation the per-message read performs, so it falls back to that path rather than being
+     * approximated here.
+     * @param messageIds - Message ids in the window whose lifecycles are needed.
+     * @returns - Lifecycle records by message id, ordered oldest first.
+     */
+    #trafficEventsForWindow(messageIds) {
+        const grouped = new Map();
+        const ids = [...new Set(messageIds)];
+        if (ids.length === 0)
+            return grouped;
+        const rows = this.#eventRows(ids, "message_id, id, at, type");
+        for (const row of rows) {
+            const messageId = String(row.message_id);
+            const lifecycle = grouped.get(messageId) ?? [];
+            lifecycle.push({ id: Number(row.id), at: Number(row.at), type: String(row.type) });
+            grouped.set(messageId, lifecycle);
+        }
+        for (const [messageId, lifecycle] of grouped) {
+            if (lifecycle.length >= BROKER_OPERATOR_TRAFFIC_LIMIT)
+                grouped.set(messageId, this.#trafficEventsForMessage(messageId));
+        }
+        return grouped;
+    }
+    /**
+     * Read the lifecycle rows of many messages, splitting the identity list across statements.
+     * @param messageIds - Distinct message identities whose lifecycle rows are wanted.
+     * @param columns - Projection-owned select list, never caller input.
+     * @returns - Flat rows for the callers to group. Ordered within each statement's chunk, not across
+     * them, which is enough because every caller groups by message before reading the order.
+     */
+    #eventRows(messageIds, columns) {
+        const rows = [];
+        for (const chunk of chunked(messageIds, SQL_PARAMETER_LIMIT)) {
+            const placeholders = chunk.map(() => "?").join(", ");
+            rows.push(...this.#db
+                .prepare(`select ${columns} from message_events where message_id in (${placeholders}) order by message_id, id`)
+                .all(...chunk));
+        }
+        return rows;
+    }
+    #trafficEventsForMessage(messageId) {
+        const rows = this.#db
+            .prepare("select id, at, type from message_events where message_id = ? order by id desc limit ?")
+            .all(messageId, BROKER_OPERATOR_TRAFFIC_LIMIT);
+        rows.reverse();
+        const latestState = this.#db
+            .prepare(`select id, at, type from message_events where message_id = ? and type in (${STATE_OBSERVING_EVENT_TYPES.map(() => "?").join(",")}) order by id desc limit 1`)
+            .get(messageId, ...STATE_OBSERVING_EVENT_TYPES);
+        if (latestState && rows.every((row) => row.id !== latestState.id)) {
+            if (rows.length >= BROKER_OPERATOR_TRAFFIC_LIMIT)
+                rows.shift();
+            rows.push(latestState);
+            rows.sort((left, right) => Number(left.id) - Number(right.id));
+        }
+        return rows.map((row) => ({ id: Number(row.id), at: Number(row.at), type: String(row.type) }));
+    }
+    #workspaceSummaries() {
+        const rows = this.#db.prepare("select * from workspaces order by path").all();
+        return rows.map((workspace) => ({
+            id: String(workspace.id),
+            path: String(workspace.path),
+            branch: typeof workspace.branch === "string" ? workspace.branch : null,
+        }));
+    }
+    #connectionState() {
+        const recentFailure = this.#db
+            .prepare("select 1 from message_events where type in ('failed','dead_lettered') and at >= ? order by at desc limit 1")
+            .get(this.#now() - RECENT_FAILURE_WINDOW_MS);
+        return recentFailure ? "degraded" : "connected";
+    }
+}