@haywoodmarx/agent-pager 0.1.0

package/dist/src/broker/schema.js

@@ -0,0 +1,454 @@
+import { issueOpaqueToken, SCHEMA_MARKER } from "./protocol.js";
+/** The partial index over messages whose `sequence` holds no orderable value. */
+export const MESSAGE_UNORDERABLE_POSITION = {
+    name: "message_unorderable_position",
+    table: "messages",
+    column: "id",
+    position: "sequence",
+};
+/** The partial index over ping audits whose `traffic_position` holds no orderable value. */
+export const PING_UNORDERABLE_POSITION = {
+    name: "ping_unorderable_position",
+    table: "operator_ping_audits",
+    column: "audit_id",
+    position: "traffic_position",
+};
+/** Every index this build creates over rows whose durable position it cannot order. */
+export const UNORDERABLE_POSITION_INDEXES = [
+    MESSAGE_UNORDERABLE_POSITION,
+    PING_UNORDERABLE_POSITION,
+];
+/**
+ * Render the partial index over the rows of one table whose position column holds no orderable value.
+ * @param index - Index being declared.
+ * @returns - The `create index` statement for it.
+ */
+function unorderablePositionIndex(index) {
+    return `create index if not exists ${index.name} on ${index.table}(${index.column}) where ${unorderablePosition(index.position)}`;
+}
+/**
+ * Render the condition a stored traffic position meets when it can be ordered and projected.
+ * @param column - Position column the condition tests.
+ * @returns - SQL condition true for a positive safe integer.
+ */
+export function orderablePosition(column) {
+    return `typeof(${column}) = 'integer' and ${column} between 1 and ${String(Number.MAX_SAFE_INTEGER)}`;
+}
+/**
+ * Render the condition a stored traffic position meets when it cannot be ordered: the complement of
+ * `orderablePosition`, spelled the way the partial index spells it so a query can use that index.
+ * @param column - Position column the condition tests.
+ * @returns - SQL condition true for anything but a positive safe integer.
+ */
+export function unorderablePosition(column) {
+    return `not (${orderablePosition(column)})`;
+}
+/**
+ * Render the create statement for every unorderable-position index, in the list's own order.
+ * @param indexes - Declarations to render; the caller passes the list the compatibility check reads.
+ * @returns - One `create index` statement per declaration, terminated and newline-separated.
+ */
+function unorderablePositionIndexes(indexes) {
+    return indexes.map((index) => `${unorderablePositionIndex(index)};`).join("\n");
+}
+function quoteIdentifier(value) {
+    return `"${value.replaceAll('"', '""')}"`;
+}
+/**
+ * Spell one stored vocabulary once, for the column constraint and the read that narrows it.
+ *
+ * Keys of an exhaustive record, so the compiler refuses a list that has drifted from its union.
+ * @param coverage - Every member of the union, mapped to `true`.
+ * @returns - The union's members, in declaration order.
+ */
+function vocabulary(coverage) {
+    return Object.keys(coverage);
+}
+/** Every delivery state `messages.state` may hold. */
+export const MESSAGE_STATES = vocabulary({
+    queued: true,
+    claimed: true,
+    acknowledged: true,
+    expired: true,
+    dead_lettered: true,
+    failed: true,
+});
+/** Every lifecycle state `agents.state` may hold. */
+export const AGENT_STATES = vocabulary({
+    active: true,
+    terminal: true,
+    reaped: true,
+});
+/** Every channel a reservation or session may occupy. */
+export const ATTACHMENT_CHANNELS = vocabulary({ messaging: true, delivery: true });
+/** Every author `message_events.source` may name. */
+export const MESSAGE_EVENT_SOURCES = vocabulary({ broker: true, notify: true });
+/** Every presentation tone `message_events.tone` may carry. */
+export const MESSAGE_EVENT_TONES = vocabulary({
+    neutral: true,
+    danger: true,
+    ok: true,
+    muted: true,
+    warn: true,
+});
+/**
+ * Render one vocabulary as a SQL `check(column in (...))` clause.
+ *
+ * Members are sorted by UTF-16 code unit rather than by locale, so reordering a union does not
+ * change the text.
+ * @param column - Column the constraint applies to.
+ * @param allowed - Values the column may hold.
+ * @returns - Constraint text for the column's declaration.
+ */
+export function vocabularyClause(column, allowed) {
+    const members = [...allowed].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    return `check(${column} in (${members.map((value) => `'${value.replaceAll("'", "''")}'`).join(",")}))`;
+}
+/**
+ * Report whether a table's stored declaration carries the constraint this build renders for a column.
+ *
+ * Case is kept: a clause differing only in a member's case admits different values.
+ * @param tableSql - The table's `create` statement exactly as `sqlite_master` holds it.
+ * @param column - Column the constraint applies to.
+ * @param allowed - Values this build's constraint admits.
+ * @returns - True when the declaration contains the constraint.
+ */
+export function declaresVocabulary(tableSql, column, allowed) {
+    // Whitespace inside a quoted member is part of the member: 'in progress' is not 'inprogress'.
+    const compact = (sql) => sql
+        .split(/('(?:[^']|'')*')/u)
+        .map((part, index) => (index % 2 === 1 ? part : part.replace(/\s+/gu, "")))
+        .join("");
+    return compact(tableSql).includes(compact(vocabularyClause(column, allowed)));
+}
+/**
+ * Owns broker schema creation, in-place-upgrade compatibility, and epoch assignment for one
+ * connection. Runs only from the broker's own constructor, before any other reader or writer of
+ * the connection exists.
+ */
+export class BrokerSchema {
+    #db;
+    #now;
+    #epochOwner;
+    #unorderablePositionIndexes;
+    #report;
+    /**
+     * Bind schema management to one connection.
+     * @param db - Connection whose schema this instance prepares.
+     * @param options - Clock, epoch-ownership policy, the unorderable-position declarations to create
+     * and require (defaulting to this build's; the create path and the check read the same list), and
+     * the operator-facing diagnostic sink for anything short of the schema-loss announcement, which is
+     * written to stderr directly because it reports data being deleted.
+     */
+    constructor(db, options) {
+        this.#db = db;
+        this.#now = options.now;
+        this.#epochOwner = options.epochOwner;
+        this.#unorderablePositionIndexes = options.unorderablePositionIndexes ?? UNORDERABLE_POSITION_INDEXES;
+        this.#report = options.report;
+    }
+    /**
+     * Recreate an incompatible database, create the current schema if absent, reconcile the traffic
+     * position allocator against stored rows, and resolve the broker epoch — in that order.
+     * @returns - Broker epoch for this connection.
+     */
+    prepare() {
+        this.#recreateIfIncompatible();
+        this.#createSchema();
+        this.#reconcileTrafficPositions();
+        return this.#loadEpoch();
+    }
+    #recreateIfIncompatible() {
+        const table = this.#db
+            .prepare("select name from sqlite_master where type = 'table' and name not like 'sqlite_%' limit 1")
+            .get();
+        if (!table)
+            return;
+        const markerTable = this.#db
+            .prepare("select name from sqlite_master where type = 'table' and name = 'schema_marker'")
+            .get();
+        const marker = markerTable
+            ? this.#db.prepare("select id from schema_marker limit 1").get()
+            : null;
+        if (marker?.id !== SCHEMA_MARKER) {
+            const found = typeof marker?.id === "string" ? marker.id : "none";
+            this.#reportSchemaLoss(`found schema ${found}, this build requires ${SCHEMA_MARKER}`);
+            this.#dropSchema();
+            return;
+        }
+        const mismatch = this.#operatorSchemaMismatch();
+        if (mismatch !== null) {
+            this.#reportSchemaLoss(`its schema marker matches this build but ${mismatch}`);
+            this.#dropSchema();
+        }
+    }
+    /**
+     * Announce that an incompatible database is about to be discarded, counting what is lost.
+     *
+     * Recreation destroys durable identities and undelivered messages, so it must never be silent: an
+     * operator who sees nothing has no reason to reach for a backup until the messages are already gone.
+     * Written to stderr, not the broker's diagnostic sink: a sink is its owner's to drop, and this
+     * announces data being deleted.
+     * @param reason - What made the database incompatible, phrased to sit inside the parentheses below.
+     */
+    #reportSchemaLoss(reason) {
+        const count = (table) => {
+            try {
+                return Number(this.#db.prepare(`select count(*) as count from ${table}`).get().count);
+            }
+            catch {
+                return 0;
+            }
+        };
+        const agents = count("agents");
+        const messages = count("messages");
+        if (agents === 0 && messages === 0)
+            return;
+        process.stderr.write(`pager: discarding an incompatible broker database (${reason}); ` +
+            `${String(agents)} agent identities and ${String(messages)} messages are being deleted\n`);
+    }
+    /**
+     * Name the first difference among the structures this build checks for.
+     *
+     * Checks only the structures listed in this method; anything else in the schema can differ
+     * unnoticed.
+     * @returns - What differs, or null when nothing this checks differs.
+     */
+    #operatorSchemaMismatch() {
+        const requiredColumns = new Map([
+            ["teams", ["workspace_id"]],
+            ["agents", ["workspace_id", "registration_name", "session_key", "archived_at"]],
+            ["workspaces", ["path"]],
+            ["message_events", ["message_id", "id", "at", "type"]],
+            ["reservations", ["channel"]],
+            ["sessions", ["channel", "superseded_by", "epoch", "superseded_at"]],
+            [
+                "messages",
+                [
+                    "id",
+                    "sender_id",
+                    "recipient_id",
+                    "addressed_to",
+                    "address_outcome",
+                    "type",
+                    "body",
+                    "body_size",
+                    "content_type",
+                    "state",
+                    "created_at",
+                    "sequence",
+                ],
+            ],
+            ["traffic_positions", ["id"]],
+            ["operator_commands", ["command_id", "type", "target_id", "accepted_at", "control_id"]],
+            [
+                "operator_ping_audits",
+                ["audit_id", "command_id", "control_id", "target_agent_id", "actor", "accepted_at", "traffic_position"],
+            ],
+            ["operator_stream_state", ["singleton", "epoch", "sequence"]],
+            ["operator_stream_events", ["epoch", "sequence", "payload"]],
+        ]);
+        for (const [name, required] of requiredColumns) {
+            const columns = this.#db.prepare(`pragma table_info(${quoteIdentifier(name)})`).all();
+            const names = new Set(columns.map((row) => String(row.name)));
+            if (columns.length === 0)
+                return `table ${name} is absent`;
+            const missing = required.find((column) => !names.has(column));
+            if (missing !== undefined)
+                return `table ${name} has no ${missing} column`;
+        }
+        for (const [table, column] of [
+            ["traffic_positions", "id"],
+            ["operator_commands", "command_id"],
+            ["operator_ping_audits", "audit_id"],
+            ["operator_stream_state", "singleton"],
+        ]) {
+            if (!this.#hasPrimaryKey(table, column))
+                return `table ${table} does not key on ${column}`;
+        }
+        for (const index of this.#unorderablePositionIndexes) {
+            if (!this.#hasIndex(index))
+                return `table ${index.table} has no ${index.name} index over its unorderable rows`;
+        }
+        for (const [table, columns] of [
+            ["operator_stream_events", ["epoch", "sequence"]],
+            ["operator_commands", ["control_id"]],
+            ["messages", ["sequence"]],
+            ["operator_ping_audits", ["command_id"]],
+            ["operator_ping_audits", ["control_id"]],
+            ["operator_ping_audits", ["traffic_position"]],
+        ]) {
+            if (!this.#hasUniqueColumns(table, columns))
+                return `table ${table} does not hold ${columns.join(", ")} unique`;
+        }
+        for (const [table, column, allowed] of [
+            ["messages", "state", MESSAGE_STATES],
+            ["agents", "state", AGENT_STATES],
+            ["reservations", "channel", ATTACHMENT_CHANNELS],
+            ["sessions", "channel", ATTACHMENT_CHANNELS],
+            ["message_events", "source", MESSAGE_EVENT_SOURCES],
+            ["message_events", "tone", MESSAGE_EVENT_TONES],
+        ]) {
+            if (!declaresVocabulary(this.#declaredSql(table), column, allowed)) {
+                return `table ${table} does not constrain ${column}`;
+            }
+        }
+        const trafficSql = this.#tableSql("traffic_positions");
+        const commandSql = this.#tableSql("operator_commands");
+        const auditSql = this.#tableSql("operator_ping_audits");
+        for (const [table, sql, fragment, missing] of [
+            ["traffic_positions", trafficSql, "autoincrement", "does not allocate positions monotonically"],
+            [
+                "operator_commands",
+                commandSql,
+                "typein('ping_agent','expire_message','archive_agent')",
+                "does not constrain its command types",
+            ],
+            [
+                "operator_commands",
+                commandSql,
+                "type='ping_agent'andcontrol_idisnotnull",
+                "does not require a ping control id",
+            ],
+            ["operator_commands", commandSql, "type!='ping_agent'andcontrol_idisnull", "does not refuse a stray control id"],
+            ["operator_ping_audits", auditSql, "actor='operator'", "does not constrain its actor"],
+            ["operator_ping_audits", auditSql, "referencesoperator_commands(command_id)", "does not reference its command"],
+        ]) {
+            if (!sql.includes(fragment))
+                return `table ${table} ${missing}`;
+        }
+        return null;
+    }
+    #hasPrimaryKey(table, column) {
+        const columns = this.#db.prepare(`pragma table_info(${quoteIdentifier(table)})`).all();
+        return columns.some((row) => row.name === column && Number(row.pk) === 1);
+    }
+    #hasIndex(index) {
+        const row = this.#db
+            .prepare("select sql from sqlite_master where type = 'index' and name = ? and tbl_name = ?")
+            .get(index.name, index.table);
+        const normalize = (sql) => sql.toLowerCase().replace(/\s+/gu, "").replace("ifnotexists", "");
+        return typeof row?.sql === "string" && normalize(row.sql) === normalize(unorderablePositionIndex(index));
+    }
+    #hasUniqueColumns(table, columns) {
+        const indexes = this.#db.prepare(`pragma index_list(${quoteIdentifier(table)})`).all();
+        return indexes.some((index) => {
+            if (Number(index.unique) !== 1)
+                return false;
+            const indexed = this.#db.prepare(`pragma index_info(${quoteIdentifier(String(index.name))})`).all();
+            return indexed.map((row) => String(row.name)).join("\0") === columns.join("\0");
+        });
+    }
+    #declaredSql(table) {
+        const row = this.#db.prepare("select sql from sqlite_master where type = 'table' and name = ?").get(table);
+        return typeof row?.sql === "string" ? row.sql : "";
+    }
+    #tableSql(table) {
+        const row = this.#db.prepare("select sql from sqlite_master where type = 'table' and name = ?").get(table);
+        return typeof row?.sql === "string" ? row.sql.toLowerCase().replace(/\s+/gu, "") : "";
+    }
+    /**
+     * Seed the position allocator above every position the stored tables already hold.
+     *
+     * Runs from the broker's constructor and never throws over a row: a position it cannot use is
+     * counted and reported, and no stored position is rewritten.
+     */
+    #reconcileTrafficPositions() {
+        this.#transaction(() => {
+            const rows = this.#db
+                .prepare(`select sequence as position, (${orderablePosition("sequence")}) as orderable from messages union all select traffic_position as position, (${orderablePosition("traffic_position")}) as orderable from operator_ping_audits`)
+                .all();
+            const claimants = new Map();
+            let maximum = 0;
+            let unusable = 0;
+            for (const row of rows) {
+                if (row.orderable !== 1) {
+                    unusable += 1;
+                    continue;
+                }
+                const position = Number(row.position);
+                claimants.set(position, (claimants.get(position) ?? 0) + 1);
+                maximum = Math.max(maximum, position);
+            }
+            for (const count of claimants.values())
+                if (count > 1)
+                    unusable += count;
+            if (unusable > 0) {
+                this.#report(`pager: ${String(unusable)} stored traffic row(s) hold a position that cannot be used and are ` +
+                    `left out of the operator's view; the allocator continues above ${String(maximum)}`);
+            }
+            if (maximum < 1)
+                return;
+            const allocator = this.#db.prepare("select coalesce(max(id), 0) as position from traffic_positions").get();
+            if (Number(allocator.position) < maximum) {
+                this.#write("insert or ignore into traffic_positions(id) values (?)", maximum);
+            }
+        });
+    }
+    #dropSchema() {
+        const tables = this.#db
+            .prepare("select name from sqlite_master where type = 'table' and name not like 'sqlite_%'")
+            .all();
+        this.#db.exec("pragma foreign_keys = OFF");
+        try {
+            for (const table of tables)
+                this.#db.exec(`drop table if exists ${quoteIdentifier(String(table.name))}`);
+        }
+        finally {
+            this.#db.exec("pragma foreign_keys = ON");
+        }
+    }
+    #createSchema() {
+        this.#db.exec(`
+      create table if not exists schema_marker(id text primary key check(id = '${SCHEMA_MARKER}'));
+      insert or ignore into schema_marker(id) values ('${SCHEMA_MARKER}');
+      create table if not exists broker_epoch(id text primary key, created_at integer not null);
+      create table if not exists workspaces(id text primary key, path text not null unique, branch text, created_at integer not null);
+      create table if not exists teams(id text primary key, workspace_id text not null, created_at integer not null);
+      create table if not exists agents(id text primary key, team_id text not null, workspace_id text not null, parent_id text, state text not null ${vocabularyClause("state", AGENT_STATES)}, created_at integer not null, implementation_id text, implementation_version text, registration_name text, registration_ephemeral integer not null default 0, session_key text, archived_at integer, check(implementation_id is not null or implementation_version is null));
+      create unique index if not exists agent_registration_name on agents(workspace_id, registration_name) where registration_name is not null and state != 'reaped';
+      create unique index if not exists agent_session_key on agents(workspace_id, implementation_id, session_key) where session_key is not null and state = 'active';
+      create table if not exists alias_history(id integer primary key autoincrement, workspace_id text not null, alias text not null, agent_id text not null, unique(workspace_id, alias));
+      create table if not exists reservations(reservation_id text primary key, agent_id text not null, channel text not null ${vocabularyClause("channel", ATTACHMENT_CHANNELS)}, expires_at integer not null, consumed_at integer);
+      create table if not exists sessions(id text primary key, agent_id text not null, channel text not null ${vocabularyClause("channel", ATTACHMENT_CHANNELS)}, fencing_token text not null, expires_at integer not null, active integer not null, created_at integer not null, superseded_by text, epoch text not null, superseded_at integer);
+      create table if not exists traffic_positions(id integer primary key autoincrement);
+      create table if not exists messages(id text primary key, team_id text not null, workspace_id text not null, sender_id text not null, recipient_id text not null, addressed_to text not null, address_outcome text not null, subject text not null, type text not null, body text, body_size integer, content_type text, state text not null ${vocabularyClause("state", MESSAGE_STATES)}, created_at integer not null, sequence integer not null, claim_token text, claim_expires_at integer);
+      create unique index if not exists message_traffic_position on messages(sequence);
+      create table if not exists message_events(id integer primary key autoincrement, message_id text not null, at integer not null, source text not null ${vocabularyClause("source", MESSAGE_EVENT_SOURCES)}, type text not null, text text not null, tone text not null ${vocabularyClause("tone", MESSAGE_EVENT_TONES)});
+      create index if not exists message_events_message on message_events(message_id, id);
+      create table if not exists claims(message_id text not null, token text not null, agent_id text not null, expires_at integer not null, created_at integer not null, primary key(message_id, token));
+      create unique index if not exists claim_token on claims(token);
+      create table if not exists wakes(agent_id text primary key, attempts integer not null, next_wake_at integer not null);
+      create table if not exists idempotency(agent_id text not null, recipient_id text not null, key text not null, message_id text not null, created_at integer not null, primary key(agent_id, recipient_id, key));
+      create table if not exists operator_commands(command_id text primary key, type text not null check(type in ('ping_agent','expire_message','archive_agent')), target_id text not null, accepted_at integer not null, control_id text unique, check((type = 'ping_agent' and control_id is not null) or (type != 'ping_agent' and control_id is null)));
+      create table if not exists operator_ping_audits(audit_id text primary key, command_id text not null unique references operator_commands(command_id), control_id text not null unique, target_agent_id text not null, actor text not null check(actor = 'operator'), accepted_at integer not null, traffic_position integer not null unique);
+      create table if not exists operator_stream_state(singleton integer primary key check(singleton = 1), epoch text not null, sequence integer not null check(sequence >= 0));
+      create table if not exists operator_stream_events(epoch text not null, sequence integer not null check(sequence > 0), payload text not null, unique(epoch, sequence));
+    `);
+        this.#db.exec(unorderablePositionIndexes(this.#unorderablePositionIndexes));
+    }
+    #loadEpoch() {
+        const existing = this.#db.prepare("select id from broker_epoch limit 1").get();
+        if (existing && !this.#epochOwner)
+            return String(existing.id);
+        const epoch = issueOpaqueToken("epoch");
+        this.#write("delete from broker_epoch");
+        this.#write("insert into broker_epoch(id, created_at) values (?, ?)", epoch, this.#now());
+        return epoch;
+    }
+    #write(sql, ...parameters) {
+        return this.#db.prepare(sql).run(...parameters);
+    }
+    #transaction(fn) {
+        this.#db.exec("begin immediate");
+        try {
+            const result = fn();
+            this.#db.exec("commit");
+            return result;
+        }
+        catch (error) {
+            this.#db.exec("rollback");
+            throw error;
+        }
+    }
+}

package/dist/src/broker/snapshot.d.ts

@@ -0,0 +1,171 @@
+import type { Broker } from "./broker.js";
+import type { DatabaseDurability } from "./database.js";
+import type { BrokerOperationalEvent } from "./operator-projection.js";
+import type { AgentLifecycleState, LifecycleTone } from "./schema.js";
+import type { MessageState } from "./protocol.js";
+/** Describes broker generation metadata included in a snapshot. */
+export type SnapshotHealth = {
+    /** Identifies the broker epoch that produced this snapshot. */
+    brokerEpoch: string;
+    /** Records when the broker generated this snapshot. */
+    generatedAt: number;
+    /** Reports the durability settings observed on the live broker's own database connection. */
+    durability: DatabaseDurability;
+};
+/** Describes one workspace represented in a snapshot. */
+export type SnapshotWorkspace = {
+    /** Identifies the workspace. */
+    id: string;
+    /** Supplies the workspace path. */
+    path: string;
+    /** Supplies the workspace branch when known. */
+    branch: string | null;
+};
+/** Describes one agent represented in a snapshot. */
+export type SnapshotAgent = {
+    /** Identifies the agent. */
+    id: string;
+    /** Records the durable agent registration time. */
+    createdAt: number;
+    /** Identifies the agent team. */
+    teamId: string;
+    /** Identifies the agent workspace. */
+    workspaceId: string;
+    /** Identifies the parent agent when available. */
+    parentId: string | null;
+    /** Reports the broker lifecycle state. */
+    state: AgentLifecycleState;
+    /** Reports the opaque agent implementation identity and optional version. */
+    implementation: {
+        /** Supplies the implementation identity chosen by the composition boundary. */ id: string;
+        /** Reports implementation version availability and value. */ version: {
+            known: true; /** Supplies the version. */
+            value: string;
+        } | {
+            known: false;
+        };
+    } | {
+        /** Reports that the implementation identity is unavailable. */ id: null;
+        /** Reports that no version can be associated without an identity. */ version: {
+            known: false;
+        };
+    };
+    /** Supplies the agent's current routing and reconnection alias. */
+    alias: string;
+    /** Lists earlier routable aliases in durable history order. */
+    previousAliases: string[];
+    /** Records when an operator archived this identity, or null while it is not archived. */
+    archivedAt: number | null;
+};
+/** Describes one durable lifecycle event. */
+export type SnapshotLifecycleEntry = {
+    /** Identifies the lifecycle event. */
+    id: number;
+    /** Identifies the related message. */
+    messageId: string;
+    /** Records when the event occurred. */
+    at: number;
+    /** Identifies the subsystem that emitted the event. */
+    source: "broker" | "notify";
+    /** Identifies the event kind. */
+    type: string;
+    /** Supplies the user-facing lifecycle text. */
+    text: string;
+    /** Selects the lifecycle display tone. */
+    tone: LifecycleTone;
+};
+/** Describes one message's delivery as the snapshot reports it. */
+export type SnapshotDelivery = {
+    /** Identifies the durable message. */
+    messageId: string;
+    /** Orders durable message records globally within the broker database. */
+    sequence: number;
+    /** Identifies the message team. */
+    teamId: string;
+    /** Identifies the workspace the message was sent from. */
+    workspaceId: string;
+    /** Identifies the sending agent. */
+    from: string;
+    /** Identifies the resolved recipient, which every persisted message has. */
+    to: string;
+    /** Carries the one-line subject the sender supplied. */
+    subject: string;
+    /** Carries the sender-supplied message type. */
+    type: string;
+    /** Reports the durable delivery state. */
+    state: MessageState;
+    /** Records message creation time. */
+    createdAt: number;
+    /** Counts delivery attempts. */
+    attempts: number;
+    /** Reports retained body size and representation without exposing body content. */
+    body: {
+        /** Records retained body size. */
+        sizeBytes: number;
+        /** Supplies retained body content type. */
+        contentType: string;
+    };
+    /** Lists durable lifecycle events for the delivery. */
+    lifecycle: SnapshotLifecycleEntry[];
+};
+/** Describes diagnostic state included in a snapshot. */
+export type SnapshotDiagnostics = {
+    /** Reports connection state. */
+    connectionState: "connected" | "degraded";
+    /** Lists operational events. */
+    operationalEvents: BrokerOperationalEvent[];
+};
+/** Represents the complete broker state exposed by a snapshot. */
+export type BrokerSnapshot = {
+    /** Identifies the snapshot schema version. */
+    version: 1;
+    /** Orders broker state changes. */
+    sequence: number;
+    /** Reports broker health. */
+    health: SnapshotHealth;
+    /** Lists visible workspaces. */
+    workspaces: SnapshotWorkspace[];
+    /** Lists visible agents. */
+    agents: SnapshotAgent[];
+    /** Lists connection state by agent. */
+    connections: Array<{
+        /** Identifies the agent. */ agentId: string;
+        /** Reports connection state. */ state: "connected" | "disconnected";
+        /** Records connection expiry. */ expiresAt: number | null;
+        /**
+         * Records when the open session the connection state is read from (the newest unexpired one,
+         * else the newest open one) was created, or null while the agent holds no open session row,
+         * whether it has never attached or its last session was explicitly closed. Distinguishes an
+         * expired-but-still-open session from one that was closed or never existed, which `state`
+         * alone cannot.
+         */
+        lastSeenAt: number | null;
+    }>;
+    /** Lists one entry per durable message. */
+    deliveries: SnapshotDelivery[];
+    /** Supplies diagnostic state. */
+    diagnostics: SnapshotDiagnostics;
+};
+/** Represents a running snapshot HTTP server and its stop operation. */
+export type SnapshotServerHandle = {
+    /** Provides the server's loopback base URL. */
+    url: string;
+    /** Stops the server after closing its connections. */
+    close: () => Promise<void>;
+};
+/** Broker operations the snapshot HTTP endpoint reaches. */
+export type SnapshotBrokerPort = Pick<Broker, "readMessageBody" | "snapshotHealth" | "snapshot" | "expireMessage" | "status">;
+/**
+ * Start the loopback-only snapshot HTTP endpoint.
+ * @param broker - Durable broker port that owns message state.
+ * @param port - Requested loopback port, with zero selecting an ephemeral port.
+ * @param host - Network interface to bind and advertise.
+ * @returns - Handle carrying the bound base URL and a `close` that resolves once the server has stopped.
+ */
+export declare function startSnapshotServer(broker: SnapshotBrokerPort, port?: number, host?: string): Promise<SnapshotServerHandle>;
+/**
+ * Return a non-secret stable marker for restart detection without exposing process-binding tokens.
+ * @param epoch - Broker generation used to fence stale sessions.
+ * @returns - Non-secret epoch fingerprint suitable for public diagnostics.
+ */
+export declare function publicEpoch(epoch: string): string;