@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,81 @@
+/** Sets how long a connection waits for a competing writer before reporting the database busy. */
+export declare const DATABASE_BUSY_TIMEOUT_MS = 5000;
+/** One row returned by a broker query, keyed by result column name. */
+export type DatabaseRow = Record<string, unknown>;
+/** Value accepted by a positional statement placeholder. */
+export type DatabaseParameter = string | number | bigint | boolean | null | Uint8Array;
+/** Reports what one write statement changed. */
+export type DatabaseWriteResult = {
+    /** Counts rows inserted, updated, or deleted by the statement. */
+    changes: number;
+    /** Identifies the row inserted by the statement, zero when it inserted none. */
+    lastInsertRowid: number | bigint;
+};
+/** Prepared statement bound to one broker connection. */
+export type DatabaseStatement = {
+    /**
+     * Execute a write and report what it changed.
+     * @param parameters - Values bound to the statement's positional placeholders.
+     * @returns - Change count and inserted row identity.
+     */
+    run(...parameters: DatabaseParameter[]): DatabaseWriteResult;
+    /**
+     * Execute a read and return its first row.
+     * @param parameters - Values bound to the statement's positional placeholders.
+     * @returns - First matching row, or undefined when the query selected none.
+     */
+    get(...parameters: DatabaseParameter[]): DatabaseRow | undefined;
+    /**
+     * Execute a read and return every row.
+     * @param parameters - Values bound to the statement's positional placeholders.
+     * @returns - Every matching row in query order.
+     */
+    all(...parameters: DatabaseParameter[]): DatabaseRow[];
+};
+/**
+ * Durability settings reported by one connection. SQLite scopes `synchronous` and `busy_timeout` to
+ * the connection that set them, so only the connection that owns the writes can attest to them.
+ */
+export type DatabaseDurability = {
+    /** Reports the file-level journal mode, which is durable in the database file itself. */
+    journalMode: string;
+    /** Reports the connection-local synchronous level as SQLite's numeric setting. */
+    synchronous: number;
+    /** Reports the connection-local lock-contention wait budget in milliseconds. */
+    busyTimeoutMs: number;
+    /** Reports whether the connection enforces foreign keys. */
+    foreignKeys: boolean;
+};
+/** Single SQLite connection used by the broker and its offline inspection commands. */
+export type BrokerDatabase = {
+    /**
+     * Run one or more statements without collecting results.
+     * @param sql - Semicolon-separated SQL executed in order.
+     */
+    exec(sql: string): void;
+    /**
+     * Compile one statement for execution.
+     * @param sql - Single SQL statement using positional placeholders.
+     * @returns - Statement bound to this connection.
+     */
+    prepare(sql: string): DatabaseStatement;
+    /**
+     * Report this connection's durability settings.
+     * @returns - Journal mode, synchronous level, busy timeout, and foreign-key enforcement.
+     */
+    durability(): DatabaseDurability;
+    /** Release the connection. */
+    close(): void;
+};
+/**
+ * Open a broker SQLite connection with the project's durability settings applied.
+ *
+ * `synchronous` and `busy_timeout` are connection-local, so every connection that must honour them
+ * sets them here rather than relying on a setting a different connection made.
+ * @param path - Database file location, or SQLite's in-memory sentinel.
+ * @param options - Read-only inspection mode used by offline diagnostics.
+ * @returns - Configured connection.
+ */
+export declare function openBrokerDatabase(path: string, options?: {
+    readonly?: boolean;
+}): BrokerDatabase;

package/dist/src/broker/database.js

@@ -0,0 +1,69 @@
+import { Database } from "bun:sqlite";
+/** Sets how long a connection waits for a competing writer before reporting the database busy. */
+export const DATABASE_BUSY_TIMEOUT_MS = 5_000;
+/**
+ * Open a broker SQLite connection with the project's durability settings applied.
+ *
+ * `synchronous` and `busy_timeout` are connection-local, so every connection that must honour them
+ * sets them here rather than relying on a setting a different connection made.
+ * @param path - Database file location, or SQLite's in-memory sentinel.
+ * @param options - Read-only inspection mode used by offline diagnostics.
+ * @returns - Configured connection.
+ */
+export function openBrokerDatabase(path, options = {}) {
+    const database = options.readonly ? new Database(path, { readonly: true }) : new Database(path);
+    // Every statement on this connection is prepared here, keyed by SQL text, so close can finalize them
+    // all. The keys are bounded: callers build SQL from fixed statements, schema names and placeholder
+    // lists capped by their chunk size.
+    const statements = new Map();
+    const wrapped = {
+        exec: (sql) => {
+            database.run(sql);
+        },
+        prepare: (sql) => {
+            let statement = statements.get(sql);
+            if (statement === undefined) {
+                statement = database.prepare(sql);
+                statements.set(sql, statement);
+            }
+            return {
+                run: (...parameters) => {
+                    const result = statement.run(...parameters);
+                    return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+                },
+                // A missing row is absent, not a stored null.
+                get: (...parameters) => statement.get(...parameters) ?? undefined,
+                all: (...parameters) => statement.all(...parameters),
+            };
+        },
+        durability: () => readDurability(wrapped),
+        close: () => {
+            // A connection with a statement still unfinalized stays open, holding the file, its write-ahead
+            // log and shared memory, until garbage collection.
+            for (const statement of statements.values())
+                statement.finalize();
+            statements.clear();
+            database.close();
+        },
+    };
+    // A read-only connection cannot write the journal header, and applying FULL to it would make it
+    // report a durability level it did not observe on the writer.
+    if (options.readonly)
+        wrapped.exec(`pragma busy_timeout = ${String(DATABASE_BUSY_TIMEOUT_MS)}; pragma foreign_keys = ON;`);
+    else
+        wrapped.exec(`pragma journal_mode = WAL; pragma synchronous = FULL; pragma busy_timeout = ${String(DATABASE_BUSY_TIMEOUT_MS)}; pragma foreign_keys = ON;`);
+    return wrapped;
+}
+function readDurability(database) {
+    const read = (sql) => database.prepare(sql).get();
+    const journal = read("pragma journal_mode");
+    const synchronous = read("pragma synchronous");
+    const busy = read("pragma busy_timeout");
+    const foreignKeys = read("pragma foreign_keys");
+    return {
+        journalMode: typeof journal?.journal_mode === "string" ? journal.journal_mode.toLowerCase() : "",
+        synchronous: Number(synchronous?.synchronous ?? -1),
+        busyTimeoutMs: Number(busy?.timeout ?? -1),
+        foreignKeys: Number(foreignKeys?.foreign_keys ?? 0) === 1,
+    };
+}

package/dist/src/broker/operator-projection.d.ts

@@ -0,0 +1,291 @@
+import type { BrokerDatabase } from "./database.js";
+import { type AgentId, type MessageState } from "./protocol.js";
+import type { BrokerSnapshot, SnapshotHealth } from "./snapshot.js";
+/** Identifies the policy that shed a broker message. */
+export type BrokerShedReason = BrokerMessageShedEvent["reason"];
+/**
+ * Describes an operational event emitted when the broker sheds a message.
+ *
+ * A pair-scoped policy carries the peer it was measured against; a body-size rejection is decided
+ * from the send alone, before the recipient is resolved, and has no peer to name.
+ */
+export type BrokerMessageShedEvent = {
+    /** Identifies this operational event. */
+    type: "message_shed";
+    /** Identifies the agent whose send was shed. */
+    agentId: AgentId;
+    /** Records the policy limit that was reached. */
+    limit: number;
+} & ({
+    /** Names the size policy, which rejects a send before its recipient is resolved. */
+    reason: "body_size";
+} | {
+    /** Names a policy measured against one sender-recipient pair. */
+    reason: "per_pair_rate" | "queue_limit";
+    /** Identifies the resolved recipient the policy was measured against. */
+    peerId: AgentId;
+});
+/**
+ * Describes a stored row the traffic projection could not account for and left out.
+ *
+ * The row is reported rather than thrown on, because one unreadable row must not cost the operator
+ * every other row in the window: the projection feeds a long-lived update stream that has no way to
+ * recover from a throw.
+ */
+export type BrokerTrafficSkippedEvent = {
+    /** Identifies this operational event. */
+    type: "traffic_row_skipped";
+    /** Identifies the durable message left out of the projection. */
+    messageId: string;
+    /** Names the stored columns that could not be read: absent, or holding a value this build does not write. */
+    unreadable: readonly string[];
+};
+/** Reports one operator ping audit left out of the traffic window because a stored column could not be read. */
+export type BrokerPingSkippedEvent = {
+    /** Identifies this operational event. */
+    type: "ping_row_skipped";
+    /** Identifies the durable ping audit left out of the projection. */
+    auditId: string;
+    /** Names the stored columns that could not be read: absent, or holding a value this build does not write. */
+    unreadable: readonly string[];
+};
+/**
+ * Reports one durable agent row left out of a projection because a stored column could not be read.
+ */
+export type BrokerAgentSkippedEvent = {
+    /** Identifies this operational event. */
+    type: "agent_row_skipped";
+    /** Identifies the durable agent left out of the projection. */
+    agentId: string;
+    /** Names the stored columns that could not be read: absent, or holding a value this build does not write. */
+    unreadable: readonly string[];
+};
+/**
+ * Reports one lifecycle observation left out of a delivery because a stored column could not be read.
+ */
+export type BrokerLifecycleSkippedEvent = {
+    /** Identifies this operational event. */
+    type: "lifecycle_entry_skipped";
+    /** Identifies the delivery whose audit is one observation short. */
+    messageId: string;
+    /** Names the stored columns that could not be read: absent, or holding a value this build does not write. */
+    unreadable: readonly string[];
+};
+/** Reports that a table holds more rows whose durable position is not a positive safe integer than one read names. */
+export type BrokerSkipsTruncatedEvent = {
+    /** Identifies this operational event. */
+    type: "skips_truncated";
+    /** Names the table whose rows could not all be listed. */
+    table: string;
+    /** How many rows with such a position this read named individually. */
+    named: number;
+    /** How many rows with such a position the table holds. */
+    total: number;
+};
+/** Reports one durable row whose stored column the broker could not read. */
+export type BrokerStoredRowSkippedEvent = {
+    /** Identifies this operational event. */
+    type: "stored_row_skipped";
+    /** Names the stored column that could not be read, qualified by its table. */
+    column: string;
+    /** Identifies the row within its table, by rowid or by the durable id the caller held. */
+    rowKey: string;
+};
+/** Describes an operational event the broker observed while accepting or projecting traffic. */
+export type BrokerOperationalEvent = BrokerMessageShedEvent | BrokerTrafficSkippedEvent | BrokerPingSkippedEvent | BrokerAgentSkippedEvent | BrokerLifecycleSkippedEvent | BrokerStoredRowSkippedEvent | BrokerSkipsTruncatedEvent;
+/** Carries one traffic read: the rows it could project, and the rows it could not. */
+export type BrokerTrafficReadResult = {
+    /** Rows the read projected, in their single broker-owned durable order. */
+    records: BrokerTrafficRecord[];
+    /** Rows this read could not project, and each table it could not list in full. */
+    skips: readonly (BrokerTrafficSkippedEvent | BrokerPingSkippedEvent | BrokerSkipsTruncatedEvent)[];
+};
+/** Describes one durable lifecycle row without exposing notification text or process bindings. */
+export type BrokerTrafficLifecycleRecord = {
+    /** Identifies the durable lifecycle row. */
+    id: number;
+    /** Records when the broker appended the observation. */
+    at: number;
+    /** Names the broker-owned observation. */
+    type: string;
+};
+/** Supplies the bounded durable input used by the renderer-neutral operator traffic projection. */
+export type BrokerTrafficRecord = {
+    /** Identifies a delivery accepted into the durable inbox. */
+    kind: "accepted_delivery";
+    /** Identifies the durable message. */
+    messageId: string;
+    /** Orders this row among every durable operator traffic kind. */
+    trafficPosition: number;
+    /** Identifies the sending agent. */
+    senderAgentId: AgentId;
+    /** Identifies the resolved recipient. */
+    recipientAgentId: AgentId;
+    /** Preserves the broker routing team. */
+    teamId: string;
+    /** Preserves the broker routing workspace. */
+    workspaceId: string;
+    /** Records when the message was accepted. */
+    acceptedAt: number;
+    /** Carries the one-line subject the sender supplied. */
+    subject: string;
+    /** Carries the sender-supplied message type. */
+    type: string;
+    /** Reports the current durable delivery state. */
+    state: MessageState;
+    /** Carries the single stored JSON representation. */
+    encodedBody: string;
+    /** Records the stored representation size in bytes. */
+    bodySizeBytes: number;
+    /** Identifies the stored representation. */
+    contentType: string;
+    /** Lists durable lifecycle rows in append order. */
+    lifecycle: BrokerTrafficLifecycleRecord[];
+} | {
+    /** Identifies acceptance of a body-free operator ping request. */
+    kind: "ping_audit";
+    /** Identifies the durable audit row. */
+    auditId: string;
+    /** Orders this row among every durable operator traffic kind. */
+    trafficPosition: number;
+    /** Correlates the command with its body-free control wake. */
+    controlId: string;
+    /** Identifies the requested target. */
+    targetAgentId: AgentId;
+    /** Records the durable actor class that requested the ping. */
+    actor: "operator";
+    /** Records command acceptance without claiming wake delivery. */
+    acceptedAt: number;
+};
+/** Describes one durable operator command acceptance used for idempotent retries. */
+export type BrokerOperatorCommandRecord = {
+    /** Identifies a body-free ping request. */
+    type: "ping_agent";
+    /** Correlates retries of the same request. */
+    commandId: string;
+    /** Identifies the target agent. */
+    targetId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+    /** Correlates the durable audit with its control wake. */
+    controlId: string;
+} | {
+    /** Identifies a message-expiry request. */
+    type: "expire_message";
+    /** Correlates retries of the same request. */
+    commandId: string;
+    /** Identifies the target message. */
+    targetId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+} | {
+    /** Identifies an agent-archive request. */
+    type: "archive_agent";
+    /** Correlates retries of the same request. */
+    commandId: string;
+    /** Identifies the target agent. */
+    targetId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+};
+/** Distinguishes a newly committed command from an exact durable retry. */
+export type BrokerOperatorCommandAcceptance = {
+    /** Returns the validated durable acceptance used for the operator result. */
+    record: BrokerOperatorCommandRecord;
+    /** Reports whether this transaction created the command and its side effects. */
+    status: "created" | "existing";
+};
+/**
+ * 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 declare function readStoredEnum<T extends string>(value: unknown, allowed: readonly T[], column: string): T;
+/**
+ * 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 declare function readStoredAgentId(value: unknown, column: string): AgentId;
+/**
+ * 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 declare function assertDurableOperatorId(value: unknown, label: string): string;
+/**
+ * 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 declare class BrokerOperatorProjection {
+    #private;
+    /**
+     * 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: BrokerDatabase, now: () => number);
+    /**
+     * Record a shed-message operational event for later diagnostic reporting.
+     * @param event - Operational event describing the shed policy and its target.
+     */
+    recordShed(event: BrokerMessageShedEvent): void;
+    /**
+     * 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: BrokerStoredRowSkippedEvent): boolean;
+    /**
+     * Return operational events recorded since the broker started.
+     * @returns - Copy of every retained operational event, oldest first.
+     */
+    operationalEvents(): BrokerOperationalEvent[];
+    /**
+     * Read bounded durable traffic without claiming, acknowledging, or changing retained bodies.
+     * @returns Traffic source rows in their single broker-owned durable order.
+     */
+    operatorTrafficRecords(): BrokerTrafficReadResult;
+    /**
+     * 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: string): BrokerOperatorCommandRecord | null;
+    /**
+     * 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: string): {
+        messageId: string;
+        body: unknown;
+        rawCopy: string;
+        sizeBytes: number;
+        contentType: string;
+    };
+    /**
+     * 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?: string): Pick<BrokerSnapshot, "workspaces" | "agents" | "connections">;
+    /**
+     * 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: string | undefined, sequence: number, health: SnapshotHealth): BrokerSnapshot;
+}