@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,237 @@
+/**
+ * Identifies the database schema this build opens; a differing marker recreates the database.
+ *
+ * Declared here rather than beside the schema it names, because the service lock compares it and is
+ * loaded by adapters running inside hosts that have no `bun:sqlite`.
+ */
+export declare const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column";
+/**
+ * Identifies the only protocol version accepted by this process.
+ *
+ * Bump for a breaking change: one where a caller declaring this version would misinterpret data
+ * this process returns, or would need to construct a request this process now rejects.
+ *
+ * A narrowing of {@link MESSAGE_TYPE_LIMIT_CHARACTERS} is bumped under that criterion: a caller
+ * declaring the prior version that already sends a `type` between the old and new bound has a request
+ * that validated before and no longer does, for a value it is not free to shorten without changing
+ * what it means, so such a caller must see `unsupported_version` from {@link assertProtocolVersion}
+ * rather than a silent, confusing per-message rejection once it is already connected.
+ */
+export declare const PROTOCOL_VERSION = 4;
+/** Names the request header a session presents its single-use attach reservation in. */
+export declare const ATTACH_HEADER = "x-pager-attach";
+/**
+ * Describes the build and runtime identity required for service adoption.
+ *
+ * Lives outside `launch/` because `messaging/mcp.ts` also names this type.
+ */
+export type BrokerServiceIdentity = {
+    /** Identifies the service ownership schema. */
+    serviceProtocolVersion: number;
+    /** Identifies the runtime kind that owns SQLite. */
+    runtime: "bun";
+    /** Identifies the runtime release that owns SQLite. */
+    runtimeVersion: string;
+    /** Identifies the package build serving requests. */
+    buildId: string;
+    /** Identifies the broker wire protocol served by the process. */
+    protocolVersion: number;
+    /**
+     * Identifies the database schema the process opens. A build whose marker differs recreates the
+     * database it adopts, so a mismatch must fail adoption rather than displace the running owner.
+     */
+    schemaMarker: string;
+};
+/** Limits the serialized size of a message body accepted by the broker. */
+export declare const MESSAGE_BODY_LIMIT_BYTES: number;
+/** Bounds a registration session name, which is also the agent's routable alias. */
+export declare const REGISTRATION_SESSION_NAME_MAX_LENGTH = 128;
+/** Bounds a conversation key, which a caller supplies to rejoin an identity across restarts. */
+export declare const SESSION_KEY_MAX_LENGTH = 256;
+/** Matches the characters a session name or conversation key may carry. */
+export declare const SESSION_IDENTIFIER_PATTERN: RegExp;
+/** Bounds an implementation id. */
+export declare const IMPLEMENTATION_ID_MAX_LENGTH = 64;
+/** Matches a well-formed implementation id. */
+export declare const IMPLEMENTATION_ID_PATTERN: RegExp;
+/** Supplies the claim count a fetch takes when the caller names none. */
+export declare const FETCH_LIMIT_DEFAULT = 50;
+/** Bounds the claim count one fetch may take. */
+export declare const FETCH_LIMIT_MAX = 500;
+/** Bounds traffic and per-record lifecycle material exposed to operator projection. */
+export declare const BROKER_OPERATOR_TRAFFIC_LIMIT = 4096;
+/**
+ * Limits a message subject to the message log pane's default content width
+ * (`MESSAGE_LOG_COLUMNS` minus its two-column inset, `src/tui/presentation.ts`), so a subject fits
+ * in full at that width. A drag below the default, or the narrower agent-log list column, still
+ * truncates it.
+ */
+export declare const MESSAGE_SUBJECT_LIMIT_CHARACTERS = 40;
+/**
+ * Bounds a message type to a short categorical tag rather than a second subject line.
+ *
+ * Sized to the collapsed team-coordination vocabulary's longest member, with no headroom to spare,
+ * keeping it visibly shorter than {@link MESSAGE_SUBJECT_LIMIT_CHARACTERS} so a type shown beside a
+ * subject never dominates it.
+ */
+export declare const MESSAGE_TYPE_LIMIT_CHARACTERS = 8;
+/**
+ * Prefixes every agent identifier, and is what tells one from an alias at an addressing boundary.
+ *
+ * The type below is built from it, and the pattern below that spells the same prefix in its escaped
+ * form; those two spellings are one rule and must move together.
+ */
+export declare const AGENT_ID_SCHEME = "pgr://agent/";
+/** Identifies an agent with the protocol's opaque URI scheme. */
+export type AgentId = `${typeof AGENT_ID_SCHEME}${string}`;
+/**
+ * Report whether an untrusted value is a well-formed agent identifier.
+ * @param value - Untrusted candidate identity.
+ * @returns - Whether the value is a well-formed agent id.
+ */
+export declare function isAgentId(value: unknown): value is AgentId;
+/**
+ * Mint an agent identifier around an opaque token.
+ * @param token - Opaque high-entropy token the identity is built from.
+ * @returns - Identifier carrying the protocol's scheme.
+ */
+export declare function mintAgentId(token: string): AgentId;
+/**
+ * Report whether an address names an agent identity directly rather than an alias to resolve.
+ *
+ * A shape question, not a validity one: a caller asking this is choosing between a direct lookup and
+ * alias resolution, and a malformed identity must reach the lookup so it fails as an unknown
+ * recipient rather than being resolved as an alias that happens to look like a URI.
+ * @param address - Recipient address supplied by a caller.
+ * @returns - Whether the address is in the agent-identity namespace.
+ */
+export declare function isDirectAgentAddress(address: string): boolean;
+/**
+ * Assert an untrusted value is a well-formed agent identifier.
+ * @param value - Untrusted candidate identity.
+ * @param label - Names the identity's origin in the rejection message.
+ */
+export declare function assertAgentId(value: unknown, label: string): asserts value is AgentId;
+/**
+ * Report whether an untrusted value is a well-formed opaque durable identifier.
+ * @param value - Untrusted candidate identifier.
+ * @returns - Whether the value is a well-formed opaque id.
+ */
+export declare function isOpaqueId(value: unknown): value is string;
+/**
+ * Report whether text carries a control character.
+ * @param value - Candidate single-line text.
+ * @returns - Whether any C0 or C1 control character appears.
+ */
+export declare function hasControlCharacter(value: string): boolean;
+/**
+ * Report whether an untrusted value is a well-formed conversation key.
+ * @param value - Untrusted candidate key.
+ * @returns - Whether the value is a key the broker accepts.
+ */
+export declare function isSessionKey(value: unknown): value is string;
+/**
+ * Validate a caller-supplied conversation key at any boundary that accepts one.
+ * @param value - Untrusted candidate key.
+ * @returns - The validated key, unchanged.
+ */
+export declare function validateSessionKey(value: unknown): string;
+/**
+ * Report whether an untrusted value is a well-formed implementation identifier.
+ * @param value - Untrusted candidate identifier.
+ * @returns - Whether the value is an identifier the broker will register.
+ */
+export declare function isImplementationId(value: unknown): value is string;
+/**
+ * Validate an implementation identifier at any boundary that accepts one.
+ * @param value - Untrusted candidate identifier.
+ * @returns - The validated identifier, unchanged and unbranded.
+ */
+export declare function validateImplementationId(value: unknown): string;
+/** Describes a durable message's current delivery state. */
+export type MessageState = "queued" | "claimed" | "acknowledged" | "expired" | "dead_lettered" | "failed";
+/**
+ * Complete vocabulary of `message_events.type` values the broker appends to a delivery lifecycle,
+ * mapped to the state each observes, or `null` when the event is informational and observes no
+ * state change. `#appendEvent` in broker.ts is typed against its keys, so an emission site naming a
+ * type absent here fails to compile.
+ */
+export declare const LIFECYCLE_EVENT_STATE: {
+    readonly enqueued: "queued";
+    readonly queued: "queued";
+    readonly claimed: "claimed";
+    readonly acknowledged: "acknowledged";
+    readonly expired: "expired";
+    readonly dead_lettered: "dead_lettered";
+    readonly failed: "failed";
+    readonly direct: null;
+    readonly alias_resolved: null;
+    readonly broadcast: null;
+    readonly duplicate_ignored: null;
+    readonly claim_released: null;
+    readonly claim_expired: null;
+    readonly redelivery: null;
+    readonly notify_delivered: null;
+    readonly notify_shed: null;
+    readonly notify_failed: null;
+    readonly notify_deferred: null;
+};
+/** Names a lifecycle event type the broker is known to append. */
+export type LifecycleEventType = keyof typeof LIFECYCLE_EVENT_STATE;
+/**
+ * Look up the delivery state a lifecycle event type observes.
+ * @param type - Candidate lifecycle event type name, untrusted when read back from storage.
+ * @returns - The state the type observes, `null` when it is informational, or `undefined` when the
+ * type is not part of the broker's vocabulary.
+ */
+export declare function lifecycleEventState(type: string): MessageState | null | undefined;
+/** Stable structured protocol error emitted at broker trust boundaries. */
+export declare class ProtocolError extends Error {
+    /** Identifies the machine-readable cause of the protocol failure. */
+    readonly code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired";
+    /**
+     * Constructs an error that carries a protocol failure code.
+     * @param code - Stable protocol error category exposed to callers.
+     * @param message - Safe diagnostic text exposed with the protocol error.
+     */
+    constructor(
+    /** Identifies the machine-readable cause of the protocol failure. */
+    code: "validation_failed" | "unsupported_version" | "oversized_content" | "unknown_recipient" | "recipient_alias_changed" | "alias_conflict" | "conflict" | "expired", message: string);
+}
+/**
+ * Generate a collision-resistant opaque token with a non-sensitive prefix.
+ * @param prefix - Non-secret category prefix for a newly issued opaque token.
+ * @returns - Fresh high-entropy token with the requested diagnostic prefix.
+ */
+export declare function issueOpaqueToken(prefix: string): string;
+/**
+ * Assert the requested protocol version is supported at a trust boundary.
+ * @param version - Wire-protocol version whose compatibility is being asserted.
+ */
+export declare function assertProtocolVersion(version: unknown): asserts version is typeof PROTOCOL_VERSION;
+/**
+ * Validate and serialize a message body, rejecting oversize input without truncation.
+ * @param body - Application payload; it must serialize to JSON.
+ * @returns - JSON text within `MESSAGE_BODY_LIMIT_BYTES`, as stored in the durable broker database.
+ */
+export declare function encodeMessageBody(body: unknown): string;
+/**
+ * Validate the one-line subject every durable message carries.
+ * @param subject - Sender-supplied subject to validate.
+ * @returns The subject with surrounding whitespace removed.
+ */
+export declare function normalizeMessageSubject(subject: unknown): string;
+/**
+ * Validate the sender-supplied message type, required on every send.
+ *
+ * Follows {@link normalizeMessageSubject}'s rules at its own, shorter bound.
+ * @param type - Sender-supplied type to validate.
+ * @returns The type with surrounding whitespace removed.
+ */
+export declare function normalizeMessageType(type: unknown): string;
+/**
+ * Decode a stored message body.
+ * @param encoded - Stored JSON text, or null when the message has no body.
+ * @returns - The decoded body, or undefined when none was stored.
+ */
+export declare function decodeMessageBody(encoded: string | null): unknown;

package/dist/src/broker/protocol.js

@@ -0,0 +1,311 @@
+import { randomBytes, randomUUID } from "node:crypto";
+/**
+ * Identifies the database schema this build opens; a differing marker recreates the database.
+ *
+ * Declared here rather than beside the schema it names, because the service lock compares it and is
+ * loaded by adapters running inside hosts that have no `bun:sqlite`.
+ */
+export const SCHEMA_MARKER = "agent-session-key+message-event-index+queryable-timestamps+no-body-absence-reason+message-type+session-resume-lineage+session-supersession-timestamp+message-type-required+single-delivery-state-home+checked-stored-columns+unorderable-position-index+orderable-position-predicate+no-occupancy-contract+single-session-encoding+no-reservation-bindings+reservation-id-column";
+/**
+ * Identifies the only protocol version accepted by this process.
+ *
+ * Bump for a breaking change: one where a caller declaring this version would misinterpret data
+ * this process returns, or would need to construct a request this process now rejects.
+ *
+ * A narrowing of {@link MESSAGE_TYPE_LIMIT_CHARACTERS} is bumped under that criterion: a caller
+ * declaring the prior version that already sends a `type` between the old and new bound has a request
+ * that validated before and no longer does, for a value it is not free to shorten without changing
+ * what it means, so such a caller must see `unsupported_version` from {@link assertProtocolVersion}
+ * rather than a silent, confusing per-message rejection once it is already connected.
+ */
+export const PROTOCOL_VERSION = 4;
+/** Names the request header a session presents its single-use attach reservation in. */
+export const ATTACH_HEADER = "x-pager-attach";
+/** Limits the serialized size of a message body accepted by the broker. */
+export const MESSAGE_BODY_LIMIT_BYTES = 12 * 1024;
+/** Bounds a registration session name, which is also the agent's routable alias. */
+export const REGISTRATION_SESSION_NAME_MAX_LENGTH = 128;
+/** Bounds a conversation key, which a caller supplies to rejoin an identity across restarts. */
+export const SESSION_KEY_MAX_LENGTH = 256;
+/** Matches the characters a session name or conversation key may carry. */
+export const SESSION_IDENTIFIER_PATTERN = /^[A-Za-z0-9._:-]+$/u;
+/** Bounds an implementation id. */
+export const IMPLEMENTATION_ID_MAX_LENGTH = 64;
+/** Matches a well-formed implementation id. */
+export const IMPLEMENTATION_ID_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/u;
+/** Supplies the claim count a fetch takes when the caller names none. */
+export const FETCH_LIMIT_DEFAULT = 50;
+/** Bounds the claim count one fetch may take. */
+export const FETCH_LIMIT_MAX = 500;
+/** Bounds traffic and per-record lifecycle material exposed to operator projection. */
+export const BROKER_OPERATOR_TRAFFIC_LIMIT = 4_096;
+/**
+ * Limits a message subject to the message log pane's default content width
+ * (`MESSAGE_LOG_COLUMNS` minus its two-column inset, `src/tui/presentation.ts`), so a subject fits
+ * in full at that width. A drag below the default, or the narrower agent-log list column, still
+ * truncates it.
+ */
+export const MESSAGE_SUBJECT_LIMIT_CHARACTERS = 40;
+/**
+ * Bounds a message type to a short categorical tag rather than a second subject line.
+ *
+ * Sized to the collapsed team-coordination vocabulary's longest member, with no headroom to spare,
+ * keeping it visibly shorter than {@link MESSAGE_SUBJECT_LIMIT_CHARACTERS} so a type shown beside a
+ * subject never dominates it.
+ */
+export const MESSAGE_TYPE_LIMIT_CHARACTERS = 8;
+/**
+ * Prefixes every agent identifier, and is what tells one from an alias at an addressing boundary.
+ *
+ * The type below is built from it, and the pattern below that spells the same prefix in its escaped
+ * form; those two spellings are one rule and must move together.
+ */
+export const AGENT_ID_SCHEME = "pgr://agent/";
+/**
+ * Matches a well-formed agent identifier.
+ *
+ * Bounded rather than open-ended because the operator projection and the operator wire both refuse
+ * a longer tail: an unbounded rule here mints identities the operator can never be shown.
+ */
+const AGENT_ID_PATTERN = /^pgr:\/\/agent\/[A-Za-z0-9._:-]{1,192}$/u;
+/** Matches a well-formed opaque durable identifier: a command, control, audit, or traffic id. */
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+/** Matches the C0 and C1 control characters no single-line field may carry. */
+// eslint-disable-next-line no-control-regex -- Matching control characters is this pattern's purpose.
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+/**
+ * Report whether an untrusted value is a well-formed agent identifier.
+ * @param value - Untrusted candidate identity.
+ * @returns - Whether the value is a well-formed agent id.
+ */
+export function isAgentId(value) {
+    return typeof value === "string" && AGENT_ID_PATTERN.test(value);
+}
+/**
+ * Mint an agent identifier around an opaque token.
+ * @param token - Opaque high-entropy token the identity is built from.
+ * @returns - Identifier carrying the protocol's scheme.
+ */
+export function mintAgentId(token) {
+    return `${AGENT_ID_SCHEME}${token}`;
+}
+/**
+ * Report whether an address names an agent identity directly rather than an alias to resolve.
+ *
+ * A shape question, not a validity one: a caller asking this is choosing between a direct lookup and
+ * alias resolution, and a malformed identity must reach the lookup so it fails as an unknown
+ * recipient rather than being resolved as an alias that happens to look like a URI.
+ * @param address - Recipient address supplied by a caller.
+ * @returns - Whether the address is in the agent-identity namespace.
+ */
+export function isDirectAgentAddress(address) {
+    return address.startsWith(AGENT_ID_SCHEME);
+}
+/**
+ * Assert an untrusted value is a well-formed agent identifier.
+ * @param value - Untrusted candidate identity.
+ * @param label - Names the identity's origin in the rejection message.
+ */
+export function assertAgentId(value, label) {
+    if (!isAgentId(value))
+        throw new ProtocolError("validation_failed", `${label} is not a well-formed agent id`);
+}
+/**
+ * Report whether an untrusted value is a well-formed opaque durable identifier.
+ * @param value - Untrusted candidate identifier.
+ * @returns - Whether the value is a well-formed opaque id.
+ */
+export function isOpaqueId(value) {
+    return typeof value === "string" && OPAQUE_ID_PATTERN.test(value);
+}
+/**
+ * Report whether text carries a control character.
+ * @param value - Candidate single-line text.
+ * @returns - Whether any C0 or C1 control character appears.
+ */
+export function hasControlCharacter(value) {
+    return CONTROL_CHARACTER_PATTERN.test(value);
+}
+/**
+ * Report whether an untrusted value is a well-formed conversation key.
+ * @param value - Untrusted candidate key.
+ * @returns - Whether the value is a key the broker accepts.
+ */
+export function isSessionKey(value) {
+    return (typeof value === "string" &&
+        value.length >= 1 &&
+        value.length <= SESSION_KEY_MAX_LENGTH &&
+        SESSION_IDENTIFIER_PATTERN.test(value));
+}
+/**
+ * Validate a caller-supplied conversation key at any boundary that accepts one.
+ * @param value - Untrusted candidate key.
+ * @returns - The validated key, unchanged.
+ */
+export function validateSessionKey(value) {
+    if (!isSessionKey(value)) {
+        throw new ProtocolError("validation_failed", `session key must be 1-${String(SESSION_KEY_MAX_LENGTH)} letters, digits, dots, colons, underscores, or hyphens`);
+    }
+    return value;
+}
+/**
+ * Report whether an untrusted value is a well-formed implementation identifier.
+ * @param value - Untrusted candidate identifier.
+ * @returns - Whether the value is an identifier the broker will register.
+ */
+export function isImplementationId(value) {
+    return (typeof value === "string" &&
+        value.length >= 1 &&
+        value.length <= IMPLEMENTATION_ID_MAX_LENGTH &&
+        IMPLEMENTATION_ID_PATTERN.test(value));
+}
+/**
+ * Validate an implementation identifier at any boundary that accepts one.
+ * @param value - Untrusted candidate identifier.
+ * @returns - The validated identifier, unchanged and unbranded.
+ */
+export function validateImplementationId(value) {
+    if (!isImplementationId(value)) {
+        throw new ProtocolError("validation_failed", `implementation id must be 1-${String(IMPLEMENTATION_ID_MAX_LENGTH)} lowercase letters and digits, start with a letter, and carry a dot or hyphen only between two of them`);
+    }
+    return value;
+}
+/**
+ * Complete vocabulary of `message_events.type` values the broker appends to a delivery lifecycle,
+ * mapped to the state each observes, or `null` when the event is informational and observes no
+ * state change. `#appendEvent` in broker.ts is typed against its keys, so an emission site naming a
+ * type absent here fails to compile.
+ */
+export const LIFECYCLE_EVENT_STATE = {
+    enqueued: "queued",
+    queued: "queued",
+    claimed: "claimed",
+    acknowledged: "acknowledged",
+    expired: "expired",
+    dead_lettered: "dead_lettered",
+    failed: "failed",
+    direct: null,
+    alias_resolved: null,
+    broadcast: null,
+    duplicate_ignored: null,
+    claim_released: null,
+    claim_expired: null,
+    redelivery: null,
+    notify_delivered: null,
+    notify_shed: null,
+    notify_failed: null,
+    notify_deferred: null,
+};
+/**
+ * Look up the delivery state a lifecycle event type observes.
+ * @param type - Candidate lifecycle event type name, untrusted when read back from storage.
+ * @returns - The state the type observes, `null` when it is informational, or `undefined` when the
+ * type is not part of the broker's vocabulary.
+ */
+export function lifecycleEventState(type) {
+    return Object.hasOwn(LIFECYCLE_EVENT_STATE, type) ? LIFECYCLE_EVENT_STATE[type] : undefined;
+}
+/** Stable structured protocol error emitted at broker trust boundaries. */
+export class ProtocolError extends Error {
+    code;
+    /**
+     * Constructs an error that carries a protocol failure code.
+     * @param code - Stable protocol error category exposed to callers.
+     * @param message - Safe diagnostic text exposed with the protocol error.
+     */
+    constructor(
+    /** Identifies the machine-readable cause of the protocol failure. */
+    code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Generate a collision-resistant opaque token with a non-sensitive prefix.
+ * @param prefix - Non-secret category prefix for a newly issued opaque token.
+ * @returns - Fresh high-entropy token with the requested diagnostic prefix.
+ */
+export function issueOpaqueToken(prefix) {
+    return `${prefix}_${randomUUID()}_${randomBytes(16).toString("base64url")}`;
+}
+/**
+ * Assert the requested protocol version is supported at a trust boundary.
+ * @param version - Wire-protocol version whose compatibility is being asserted.
+ */
+export function assertProtocolVersion(version) {
+    if (version !== PROTOCOL_VERSION)
+        throw new ProtocolError("unsupported_version", "Unsupported protocol version");
+}
+/**
+ * Validate and serialize a message body, rejecting oversize input without truncation.
+ * @param body - Application payload; it must serialize to JSON.
+ * @returns - JSON text within `MESSAGE_BODY_LIMIT_BYTES`, as stored in the durable broker database.
+ */
+export function encodeMessageBody(body) {
+    const encoded = JSON.stringify(body);
+    if (typeof encoded !== "string")
+        throw new ProtocolError("validation_failed", "Message body must be JSON serializable");
+    if (Buffer.byteLength(encoded, "utf8") > MESSAGE_BODY_LIMIT_BYTES) {
+        throw new ProtocolError("oversized_content", `Message body exceeds ${String(MESSAGE_BODY_LIMIT_BYTES)} bytes`);
+    }
+    return encoded;
+}
+/**
+ * Validate one bounded line of sender-supplied text, shared by every field that follows the
+ * subject's rules at its own limit.
+ *
+ * Control characters are rejected rather than stripped: the field is presented in a single character
+ * cell row, and silently altering the sender's text would make the operator view disagree with what
+ * the sender believes it sent.
+ * @param trimmed - Non-empty, already-trimmed candidate to validate.
+ * @param limit - Maximum character length this field allows.
+ * @param label - Names the field in a rejection message.
+ * @returns The input, unchanged, once it has passed the control-character and length checks.
+ */
+function normalizeBoundedLine(trimmed, limit, label) {
+    if (hasControlCharacter(trimmed)) {
+        throw new ProtocolError("validation_failed", `Message ${label} must be a single line without control characters`);
+    }
+    if (trimmed.length > limit) {
+        throw new ProtocolError("oversized_content", `Message ${label} exceeds ${String(limit)} characters`);
+    }
+    return trimmed;
+}
+/**
+ * Validate the one-line subject every durable message carries.
+ * @param subject - Sender-supplied subject to validate.
+ * @returns The subject with surrounding whitespace removed.
+ */
+export function normalizeMessageSubject(subject) {
+    if (typeof subject !== "string")
+        throw new ProtocolError("validation_failed", "Message subject is required");
+    const trimmed = subject.trim();
+    if (trimmed.length === 0)
+        throw new ProtocolError("validation_failed", "Message subject is required");
+    return normalizeBoundedLine(trimmed, MESSAGE_SUBJECT_LIMIT_CHARACTERS, "subject");
+}
+/**
+ * Validate the sender-supplied message type, required on every send.
+ *
+ * Follows {@link normalizeMessageSubject}'s rules at its own, shorter bound.
+ * @param type - Sender-supplied type to validate.
+ * @returns The type with surrounding whitespace removed.
+ */
+export function normalizeMessageType(type) {
+    if (type === undefined || type === null)
+        throw new ProtocolError("validation_failed", "Message type is required");
+    if (typeof type !== "string")
+        throw new ProtocolError("validation_failed", "Message type must be text");
+    const trimmed = type.trim();
+    if (trimmed.length === 0)
+        throw new ProtocolError("validation_failed", "Message type must not be blank");
+    return normalizeBoundedLine(trimmed, MESSAGE_TYPE_LIMIT_CHARACTERS, "type");
+}
+/**
+ * Decode a stored message body.
+ * @param encoded - Stored JSON text, or null when the message has no body.
+ * @returns - The decoded body, or undefined when none was stored.
+ */
+export function decodeMessageBody(encoded) {
+    return encoded === null ? undefined : JSON.parse(encoded);
+}

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

@@ -0,0 +1,94 @@
+import type { BrokerDatabase } from "./database.js";
+import { type MessageState } from "./protocol.js";
+/** Declares one partial index over the rows of a table whose position column holds no orderable value. */
+export type UnorderablePositionIndex = {
+    /** Index name, unique within the database. */
+    readonly name: string;
+    /** Table the index is declared on. */
+    readonly table: string;
+    /** Column the index keys on, and orders the naming read by. */
+    readonly column: string;
+    /** Column whose unorderable values the index selects for. */
+    readonly position: string;
+};
+/** The partial index over messages whose `sequence` holds no orderable value. */
+export declare const MESSAGE_UNORDERABLE_POSITION: UnorderablePositionIndex;
+/** The partial index over ping audits whose `traffic_position` holds no orderable value. */
+export declare const PING_UNORDERABLE_POSITION: UnorderablePositionIndex;
+/** Every index this build creates over rows whose durable position it cannot order. */
+export declare const UNORDERABLE_POSITION_INDEXES: readonly UnorderablePositionIndex[];
+/**
+ * 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 declare function orderablePosition(column: string): string;
+/**
+ * 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 declare function unorderablePosition(column: string): string;
+/** Every delivery state `messages.state` may hold. */
+export declare const MESSAGE_STATES: readonly MessageState[];
+/** Names one lifecycle state of an agent; `AGENT_STATES` lists them. */
+export type AgentLifecycleState = "active" | "terminal" | "reaped";
+/** Every lifecycle state `agents.state` may hold. */
+export declare const AGENT_STATES: readonly AgentLifecycleState[];
+/** Every channel a reservation or session may occupy. */
+export declare const ATTACHMENT_CHANNELS: readonly ("messaging" | "delivery")[];
+/** Every author `message_events.source` may name. */
+export declare const MESSAGE_EVENT_SOURCES: readonly ("broker" | "notify")[];
+/** Selects the lifecycle display tone shown for a durable event or status. */
+export type LifecycleTone = "neutral" | "danger" | "ok" | "muted" | "warn";
+/** Every presentation tone `message_events.tone` may carry. */
+export declare const MESSAGE_EVENT_TONES: readonly LifecycleTone[];
+/**
+ * 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 declare function vocabularyClause(column: string, allowed: readonly string[]): string;
+/**
+ * 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 declare function declaresVocabulary(tableSql: string, column: string, allowed: readonly string[]): boolean;
+/**
+ * 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 declare class BrokerSchema {
+    #private;
+    /**
+     * 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: BrokerDatabase, options: {
+        now: () => number;
+        epochOwner: boolean;
+        unorderablePositionIndexes?: readonly UnorderablePositionIndex[];
+        report: (message: string) => void;
+    });
+    /**
+     * 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(): string;
+}