@haywoodmarx/agent-pager 0.1.0

package/dist/src/operator/validation.js

@@ -0,0 +1,916 @@
+import { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, } from "./protocol.js";
+import { BROKER_OPERATOR_TRAFFIC_LIMIT, hasControlCharacter, isAgentId, isImplementationId, isOpaqueId, lifecycleEventState, MESSAGE_BODY_LIMIT_BYTES, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, } from "../broker/protocol.js";
+import { MESSAGE_STATES } from "../broker/schema.js";
+import { exactFields as guardExactFields, readArray as guardReadArray, readOwnEnumerableEntries as guardReadOwnEnumerableEntries, readRecord as guardReadRecord, } from "../shared/guards.js";
+/**
+ * Bounds how many rows a projection admits into one operator snapshot array.
+ *
+ * The projections enforce it, not the validators in this file. Derived from the broker's traffic
+ * bound: an array smaller than what the broker projects would reject a snapshot the broker
+ * considers valid, and one larger admits rows nothing can produce.
+ */
+export const OPERATOR_ARRAY_LENGTH_LIMIT = BROKER_OPERATOR_TRAFFIC_LIMIT;
+/** Reports that an untrusted value does not satisfy the operator protocol. */
+export class OperatorValidationError extends Error {
+    path;
+    /**
+     * Constructs a boundary error at one public field path.
+     * @param path - Field path at which validation failed.
+     * @param reason - Safe explanation suitable for operator diagnostics.
+     */
+    constructor(
+    /** Identifies the rejected field. */
+    path, reason) {
+        super(`${path}: ${reason}`);
+        this.path = path;
+    }
+}
+/**
+ * Validate an untrusted operator cursor.
+ * @param value - Candidate cursor received from an external boundary.
+ * @returns A fully validated epoch and monotonic sequence position.
+ */
+export function validateOperatorCursor(value) {
+    const record = readRecord(value, "cursor");
+    exactFields({ record, required: ["protocolVersion", "epoch", "sequence"], optional: [], path: "cursor" });
+    return {
+        protocolVersion: readProtocolVersion(record.protocolVersion, "cursor.protocolVersion"),
+        epoch: readNonemptyString(record.epoch, "cursor.epoch"),
+        sequence: readSequence(record.sequence, "cursor.sequence"),
+    };
+}
+/**
+ * Validate an untrusted repository projection.
+ * @param value - Candidate presentation grouping received from an external boundary.
+ * @returns A repository projection that carries no broker authority.
+ */
+export function validateOperatorRepository(value) {
+    const record = readRecord(value, "repository");
+    exactFields({ record, required: ["id", "rootPath", "name"], optional: [], path: "repository" });
+    return {
+        id: readNonemptyString(record.id, "repository.id"),
+        rootPath: readNonemptyString(record.rootPath, "repository.rootPath"),
+        name: readNonemptyString(record.name, "repository.name"),
+    };
+}
+/**
+ * Validate an untrusted operator agent projection.
+ * @param value - Candidate agent received from an external boundary.
+ * @returns A fully typed agent with separated broker and repository identities.
+ */
+export function validateOperatorAgent(value) {
+    const record = readRecord(value, "agent");
+    exactFields({
+        record,
+        required: [
+            "id",
+            "alias",
+            "previousAliases",
+            "registeredAt",
+            "lifecycle",
+            "archivedAt",
+            "workspaceAvailable",
+            "workspace",
+            "brokerIdentity",
+            "repository",
+            "adapter",
+            "implementation",
+        ],
+        optional: [],
+        path: "agent",
+    });
+    const brokerIdentity = readRecord(record.brokerIdentity, "agent.brokerIdentity");
+    exactFields({
+        record: brokerIdentity,
+        required: ["teamId", "workspaceId"],
+        optional: [],
+        path: "agent.brokerIdentity",
+    });
+    const repository = readRecord(record.repository, "agent.repository");
+    exactFields({ record: repository, required: ["repositoryId", "worktree"], optional: [], path: "agent.repository" });
+    return {
+        id: readAgentId(record.id, "agent.id"),
+        alias: readNonemptyString(record.alias, "agent.alias"),
+        previousAliases: readStringArray(record.previousAliases, "agent.previousAliases"),
+        registeredAt: readTimestamp(record.registeredAt, "agent.registeredAt"),
+        lifecycle: readAgentLifecycle(record.lifecycle, "agent.lifecycle"),
+        archivedAt: readNullableTimestamp(record.archivedAt, "agent.archivedAt"),
+        workspaceAvailable: readBoolean(record.workspaceAvailable, "agent.workspaceAvailable"),
+        workspace: readNonemptyString(record.workspace, "agent.workspace"),
+        brokerIdentity: {
+            teamId: readNonemptyString(brokerIdentity.teamId, "agent.brokerIdentity.teamId"),
+            workspaceId: readNonemptyString(brokerIdentity.workspaceId, "agent.brokerIdentity.workspaceId"),
+        },
+        repository: {
+            repositoryId: readNonemptyString(repository.repositoryId, "agent.repository.repositoryId"),
+            worktree: validateWorktree(repository.worktree, "agent.repository.worktree"),
+        },
+        adapter: validateAdapterState(record.adapter, "agent.adapter"),
+        implementation: validateImplementation(record.implementation, "agent.implementation"),
+    };
+}
+/**
+ * Validate an untrusted traffic projection.
+ * @param value - Candidate accepted delivery or audit received from an external boundary.
+ * @returns One member of the closed operator traffic union.
+ */
+export function validateOperatorTraffic(value) {
+    const record = readRecord(value, "traffic");
+    switch (record.kind) {
+        case "accepted_delivery":
+            return validateAcceptedDelivery(record);
+        case "ping_audit":
+            return validatePingAudit(record);
+        default:
+            throw new OperatorValidationError("traffic.kind", "unknown traffic kind");
+    }
+}
+/**
+ * Validate one public operator body.
+ * @param value - Candidate retained public body.
+ * @returns A bounded body representation whose metadata matches its public raw copy.
+ */
+export function validateOperatorMessageBody(value) {
+    return validateMessageBody(value, "traffic.body");
+}
+/**
+ * Validate an untrusted operator diagnostic.
+ * @param value - Candidate diagnostic received from an external boundary.
+ * @returns A diagnostic with a bounded scope and summary.
+ */
+export function validateOperatorDiagnostic(value) {
+    const record = readRecord(value, "diagnostic");
+    exactFields({ record, required: ["at", "origin", "severity", "scope", "summary"], optional: [], path: "diagnostic" });
+    const origin = record.origin;
+    if (origin !== "broker" && origin !== "client") {
+        throw new OperatorValidationError("diagnostic.origin", "must name the observer");
+    }
+    const severity = record.severity;
+    if (severity !== "info" && severity !== "warning" && severity !== "error") {
+        throw new OperatorValidationError("diagnostic.severity", "must name a known severity");
+    }
+    return {
+        at: readTimestamp(record.at, "diagnostic.at"),
+        origin,
+        severity,
+        scope: readDiagnosticText(record.scope, "diagnostic.scope"),
+        summary: readDiagnosticText(record.summary, "diagnostic.summary"),
+    };
+}
+function readDiagnosticText(value, path) {
+    const text = readNonemptyString(value, path);
+    if (text.length > OPERATOR_DIAGNOSTIC_TEXT_LIMIT) {
+        throw new OperatorValidationError(path, "exceeds the bounded diagnostic length");
+    }
+    return text;
+}
+/**
+ * Validate an untrusted complete operator projection.
+ * @param value - Candidate snapshot received from an external boundary.
+ * @returns A typed snapshot whose cross-record identities and sequences are consistent.
+ */
+export function validateOperatorSnapshot(value) {
+    const record = readRecord(value, "snapshot");
+    exactFields({
+        record,
+        required: ["protocolVersion", "epoch", "cursor", "generatedAt", "repositories", "agents", "traffic"],
+        optional: [],
+        path: "snapshot",
+    });
+    const protocolVersion = readProtocolVersion(record.protocolVersion, "snapshot.protocolVersion");
+    const epoch = readNonemptyString(record.epoch, "snapshot.epoch");
+    const cursor = validateOperatorCursor(record.cursor);
+    if (cursor.epoch !== epoch)
+        throw new OperatorValidationError("snapshot.cursor.epoch", "does not match snapshot epoch");
+    const repositories = readArray(record.repositories, "snapshot.repositories").map((entry) => validateOperatorRepository(entry));
+    const agents = readArray(record.agents, "snapshot.agents").map((entry) => validateOperatorAgent(entry));
+    const traffic = readArray(record.traffic, "snapshot.traffic").map((entry) => validateOperatorTraffic(entry));
+    assertUnique(repositories.map((repository) => repository.id), "snapshot.repositories", "repository id");
+    assertUnique(agents.map((agent) => agent.id), "snapshot.agents", "agent id");
+    const repositoryIds = new Set(repositories.map((repository) => repository.id));
+    for (const agent of agents) {
+        if (!repositoryIds.has(agent.repository.repositoryId))
+            throw new OperatorValidationError("snapshot.agents", "agent references an unknown repository projection");
+    }
+    assertUnique(traffic
+        .filter((entry) => entry.kind === "accepted_delivery")
+        .map((entry) => entry.acceptedSequence), "snapshot.traffic", "accepted traffic sequence");
+    assertUnique(traffic.map((entry) => entry.trafficPosition), "snapshot.traffic", "durable traffic position");
+    for (let index = 1; index < traffic.length; index += 1) {
+        const previous = traffic[index - 1];
+        const current = traffic[index];
+        if (previous && current && previous.trafficPosition >= current.trafficPosition) {
+            throw new OperatorValidationError("snapshot.traffic", "must follow durable traffic position order");
+        }
+    }
+    assertUnique(traffic.map((entry) => entry.trafficId), "snapshot.traffic", "traffic id");
+    const snapshot = {
+        protocolVersion,
+        epoch,
+        cursor,
+        generatedAt: readTimestamp(record.generatedAt, "snapshot.generatedAt"),
+        repositories,
+        agents,
+        traffic,
+    };
+    validateOperatorSnapshotByteLength(Buffer.byteLength(JSON.stringify(snapshot), "utf8"));
+    return snapshot;
+}
+/**
+ * Validate the serialized size shared by snapshot producers and the transport.
+ * @param byteLength - UTF-8 JSON byte count for one complete snapshot.
+ * @returns The accepted byte count for subsequent bounded transfer.
+ */
+export function validateOperatorSnapshotByteLength(byteLength) {
+    if (!Number.isSafeInteger(byteLength) || byteLength < 1 || byteLength > OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES) {
+        throw new OperatorValidationError("snapshot", "exceeds the aggregate operator snapshot limit");
+    }
+    return byteLength;
+}
+/**
+ * Validate an untrusted sequenced state event.
+ * @param value - Candidate event envelope received from an external boundary.
+ * @returns A fully typed authoritative state event.
+ */
+export function validateOperatorEventEnvelope(value) {
+    const record = readRecord(value, "eventEnvelope");
+    exactFields({
+        record,
+        required: ["protocolVersion", "epoch", "sequence", "event"],
+        optional: [],
+        path: "eventEnvelope",
+    });
+    return {
+        protocolVersion: readProtocolVersion(record.protocolVersion, "eventEnvelope.protocolVersion"),
+        epoch: readNonemptyString(record.epoch, "eventEnvelope.epoch"),
+        sequence: readPositiveSequence(record.sequence, "eventEnvelope.sequence"),
+        event: validateStateEvent(record.event),
+    };
+}
+/**
+ * Classify an untrusted event against the current cursor.
+ * @param cursorValue - Candidate last authoritative event position, validated before classification.
+ * @param value - Candidate event envelope received from the stream.
+ * @returns A distinct apply, duplicate, gap, stale-epoch, or incompatible-version result.
+ */
+export function classifyOperatorEvent(cursorValue, value) {
+    const cursor = validateOperatorCursor(cursorValue);
+    const record = readRecord(value, "eventEnvelope");
+    const receivedVersion = readInteger(record.protocolVersion, "eventEnvelope.protocolVersion");
+    if (receivedVersion !== OPERATOR_PROTOCOL_VERSION) {
+        return { type: "incompatible_version", supportedVersion: OPERATOR_PROTOCOL_VERSION, receivedVersion };
+    }
+    const event = validateOperatorEventEnvelope(value);
+    if (event.epoch !== cursor.epoch) {
+        return { type: "stale_epoch", currentEpoch: cursor.epoch, receivedEpoch: event.epoch };
+    }
+    if (event.sequence <= cursor.sequence)
+        return { type: "duplicate", sequence: event.sequence };
+    const expectedSequence = cursor.sequence + 1;
+    if (event.sequence !== expectedSequence) {
+        return { type: "gap", expectedSequence, receivedSequence: event.sequence };
+    }
+    return {
+        type: "apply",
+        event,
+        cursor: { protocolVersion: OPERATOR_PROTOCOL_VERSION, epoch: event.epoch, sequence: event.sequence },
+    };
+}
+/**
+ * Validate one untrusted client-to-server transport frame.
+ * @param value - Candidate newline-delimited request received from a loopback client.
+ * @returns The validated request, as whichever member of the transport request union it names.
+ */
+export function validateOperatorTransportRequest(value) {
+    const record = readRecord(value, "transportRequest");
+    switch (record.type) {
+        case "subscribe": {
+            exactFields({ record, required: ["type", "protocolVersion"], optional: ["cursor"], path: "transportRequest" });
+            const request = {
+                type: "subscribe",
+                protocolVersion: readProtocolVersion(record.protocolVersion, "transportRequest.protocolVersion"),
+            };
+            if (record.cursor !== undefined)
+                request.cursor = validateOperatorCursor(record.cursor);
+            return request;
+        }
+        case "ack":
+            exactFields({ record, required: ["type", "protocolVersion", "cursor"], optional: [], path: "transportRequest" });
+            return {
+                type: "ack",
+                protocolVersion: readProtocolVersion(record.protocolVersion, "transportRequest.protocolVersion"),
+                cursor: validateOperatorCursor(record.cursor),
+            };
+        case "command":
+            exactFields({ record, required: ["type", "protocolVersion", "command"], optional: [], path: "transportRequest" });
+            return {
+                type: "command",
+                protocolVersion: readProtocolVersion(record.protocolVersion, "transportRequest.protocolVersion"),
+                command: validateOperatorCommand(record.command),
+            };
+        default:
+            throw new OperatorValidationError("transportRequest.type", "unknown transport request");
+    }
+}
+/**
+ * Validate one generated operator control correlation before it reaches scheduling or durability.
+ * @param value - Candidate correlation returned by an injected generator.
+ * @returns Bounded public-safe opaque control identity.
+ */
+export function validateOperatorControlId(value) {
+    return readOpaqueId(value, "controlId");
+}
+/**
+ * Validate an untrusted operator command without granting repository projection authority.
+ * @param value - Candidate versioned command received from an external boundary.
+ * @returns A typed operator command envelope.
+ */
+export function validateOperatorCommand(value) {
+    const record = readRecord(value, "commandEnvelope");
+    exactFields({
+        record,
+        required: ["protocolVersion", "commandId", "issuedAt", "command"],
+        optional: [],
+        path: "commandEnvelope",
+    });
+    return {
+        protocolVersion: readProtocolVersion(record.protocolVersion, "commandEnvelope.protocolVersion"),
+        commandId: readOpaqueId(record.commandId, "commandEnvelope.commandId"),
+        issuedAt: readTimestamp(record.issuedAt, "commandEnvelope.issuedAt"),
+        command: validateCommandMember(record.command),
+    };
+}
+/**
+ * Validate an untrusted command admission result.
+ * @param value - Candidate result received from the command endpoint.
+ * @returns A typed admission outcome that contains no authoritative state event.
+ */
+export function validateOperatorCommandResult(value) {
+    const record = readRecord(value, "commandResult");
+    switch (record.type) {
+        case "ping_accepted":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "acceptedAt", "controlId"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "accepted")
+                throw new OperatorValidationError("commandResult.status", "ping result must be accepted");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "ping_accepted",
+                status: "accepted",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
+                controlId: readOpaqueId(record.controlId, "commandResult.controlId"),
+            };
+        case "expiry_accepted":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "acceptedAt"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "accepted")
+                throw new OperatorValidationError("commandResult.status", "expiry result must be accepted");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "expiry_accepted",
+                status: "accepted",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
+            };
+        case "archive_accepted":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "acceptedAt"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "accepted")
+                throw new OperatorValidationError("commandResult.status", "archive result must be accepted");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "archive_accepted",
+                status: "accepted",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                acceptedAt: readTimestamp(record.acceptedAt, "commandResult.acceptedAt"),
+            };
+        case "command_rejected":
+            exactFields({
+                record,
+                required: ["protocolVersion", "type", "status", "commandId", "reason"],
+                optional: [],
+                path: "commandResult",
+            });
+            if (record.status !== "rejected")
+                throw new OperatorValidationError("commandResult.status", "rejected result must be rejected");
+            return {
+                protocolVersion: readProtocolVersion(record.protocolVersion, "commandResult.protocolVersion"),
+                type: "command_rejected",
+                status: "rejected",
+                commandId: readOpaqueId(record.commandId, "commandResult.commandId"),
+                reason: readRejectionReason(record.reason, "commandResult.reason"),
+            };
+        default:
+            throw new OperatorValidationError("commandResult.type", "unknown command result");
+    }
+}
+/**
+ * Validate and correlate a command result with the originating command kind and identity.
+ * @param commandValue - Candidate originating command received at the operator boundary.
+ * @param resultValue - Candidate result returned for that command.
+ * @returns A narrowed command/result pair whose accepted members cannot cross command kinds.
+ */
+export function validateOperatorCommandResultForCommand(commandValue, resultValue) {
+    const command = validateOperatorCommand(commandValue);
+    const result = validateOperatorCommandResult(resultValue);
+    if (result.commandId !== command.commandId) {
+        throw new OperatorValidationError("commandResult.commandId", "does not match originating command");
+    }
+    switch (command.command.type) {
+        case "ping_agent":
+            if (result.type === "ping_accepted" || result.type === "command_rejected")
+                return { command: { ...command, command: command.command }, result };
+            break;
+        case "expire_message":
+            if (result.type === "expiry_accepted" || result.type === "command_rejected")
+                return { command: { ...command, command: command.command }, result };
+            break;
+        case "archive_agent":
+            if (result.type === "archive_accepted" || result.type === "command_rejected")
+                return { command: { ...command, command: command.command }, result };
+            break;
+    }
+    throw new OperatorValidationError("commandResult.type", `${resultDescriptions[result.type]} cannot answer ${commandDescriptions[command.command.type]}`);
+}
+function validateAcceptedDelivery(record) {
+    exactFields({
+        record,
+        required: [
+            "kind",
+            "trafficId",
+            "messageId",
+            "trafficPosition",
+            "acceptedSequence",
+            "fromAgentId",
+            "toAgentId",
+            "teamId",
+            "workspaceId",
+            "acceptedAt",
+            "subject",
+            "type",
+            "state",
+            "body",
+            "lifecycle",
+        ],
+        optional: [],
+        path: "traffic",
+    });
+    const trafficId = readOpaqueId(record.trafficId, "traffic.trafficId");
+    const messageId = readOpaqueId(record.messageId, "traffic.messageId");
+    if (trafficId !== messageId) {
+        throw new OperatorValidationError("traffic.trafficId", "must equal the durable message identity");
+    }
+    const trafficPosition = readPositiveSequence(record.trafficPosition, "traffic.trafficPosition");
+    const acceptedSequence = readPositiveSequence(record.acceptedSequence, "traffic.acceptedSequence");
+    if (acceptedSequence !== trafficPosition) {
+        throw new OperatorValidationError("traffic.acceptedSequence", "must equal the durable traffic position");
+    }
+    const state = readMessageState(record.state, "traffic.state");
+    const body = validateMessageBody(record.body, "traffic.body");
+    // Entries naming a type outside the closed vocabulary are dropped here; validateLifecycleEntry
+    // owns why.
+    const rawLifecycle = readArray(record.lifecycle, "traffic.lifecycle");
+    const validatedLifecycle = rawLifecycle.map((entry, index) => validateLifecycleEntry(entry, `traffic.lifecycle[${String(index)}]`));
+    const lifecycle = validatedLifecycle
+        .filter((result) => result.recognized)
+        .map((result) => result.entry);
+    assertLifecycleOrder(lifecycle, "traffic.lifecycle");
+    const latestStateBearingEntry = lifecycle.findLast((entry) => entry.state !== null);
+    const latestState = latestStateBearingEntry?.state;
+    // A mismatch is excusable only when some dropped entry's id exceeds the entry that produced
+    // latestState: that dropped entry is newer than the newest state this build could read, so it may
+    // itself have observed the delivery's real current state. A dropped entry that is not newer than
+    // that observation carries no such excuse, whatever its own id is relative to other entries.
+    const excusedByNewerUnrecognizedEntry = validatedLifecycle.some((result) => !result.recognized && result.id > (latestStateBearingEntry?.id ?? -Infinity));
+    if (latestState !== state && !excusedByNewerUnrecognizedEntry) {
+        throw new OperatorValidationError("traffic.lifecycle", "latest durable state observation must match current state");
+    }
+    return {
+        kind: "accepted_delivery",
+        trafficId,
+        messageId,
+        trafficPosition,
+        acceptedSequence,
+        fromAgentId: readAgentId(record.fromAgentId, "traffic.fromAgentId"),
+        toAgentId: readAgentId(record.toAgentId, "traffic.toAgentId"),
+        teamId: readNonemptyString(record.teamId, "traffic.teamId"),
+        workspaceId: readNonemptyString(record.workspaceId, "traffic.workspaceId"),
+        acceptedAt: readTimestamp(record.acceptedAt, "traffic.acceptedAt"),
+        subject: readMessageSubject(record.subject, "traffic.subject"),
+        type: readMessageType(record.type, "traffic.type"),
+        state,
+        body,
+        lifecycle,
+    };
+}
+function validatePingAudit(record) {
+    exactFields({
+        record,
+        required: ["kind", "trafficId", "auditId", "trafficPosition", "controlId", "targetAgentId", "actor", "acceptedAt"],
+        optional: [],
+        path: "traffic",
+    });
+    if (record.actor !== "operator")
+        throw new OperatorValidationError("traffic.actor", "unknown ping actor");
+    const trafficId = readOpaqueId(record.trafficId, "traffic.trafficId");
+    const auditId = readOpaqueId(record.auditId, "traffic.auditId");
+    if (trafficId !== auditId) {
+        throw new OperatorValidationError("traffic.trafficId", "must equal the durable audit identity");
+    }
+    return {
+        kind: "ping_audit",
+        trafficId,
+        auditId,
+        trafficPosition: readPositiveSequence(record.trafficPosition, "traffic.trafficPosition"),
+        controlId: readOpaqueId(record.controlId, "traffic.controlId"),
+        targetAgentId: readAgentId(record.targetAgentId, "traffic.targetAgentId"),
+        actor: "operator",
+        acceptedAt: readTimestamp(record.acceptedAt, "traffic.acceptedAt"),
+    };
+}
+function validateMessageBody(value, path) {
+    const record = readRecord(value, path);
+    exactFields({ record, required: ["content", "rawCopy", "sizeBytes", "contentType"], optional: [], path });
+    const content = validatePublicJson(record.content, `${path}.content`);
+    const contentType = readNonemptyString(record.contentType, `${path}.contentType`);
+    if (contentType !== "text" && contentType !== "json") {
+        throw new OperatorValidationError(`${path}.contentType`, "unknown public content type");
+    }
+    if (typeof record.rawCopy !== "string") {
+        throw new OperatorValidationError(`${path}.rawCopy`, "must be text");
+    }
+    if (Buffer.byteLength(record.rawCopy, "utf8") > MESSAGE_BODY_LIMIT_BYTES) {
+        throw new OperatorValidationError(`${path}.rawCopy`, "exceeds the message body limit");
+    }
+    const expectedRaw = contentType === "text" && typeof content === "string" ? content : JSON.stringify(content);
+    if (record.rawCopy !== expectedRaw) {
+        throw new OperatorValidationError(`${path}.rawCopy`, "must exactly represent public content");
+    }
+    const sizeBytes = readNonnegativeInteger(record.sizeBytes, `${path}.sizeBytes`);
+    if (sizeBytes !== Buffer.byteLength(record.rawCopy, "utf8")) {
+        throw new OperatorValidationError(`${path}.sizeBytes`, "must equal the public raw-copy size");
+    }
+    return {
+        content,
+        rawCopy: record.rawCopy,
+        sizeBytes,
+        contentType,
+    };
+}
+/**
+ * Validate one durable lifecycle entry, or signal that it names a type outside the closed
+ * vocabulary.
+ *
+ * A durable row can predate this build's vocabulary, or this build can be validating wire traffic
+ * from a differently-built live broker. Either way an unrecognized type is expected drift, not
+ * corruption, so the caller drops the entry instead of failing the whole delivery over it. The
+ * tolerance is exactly one cause wide: every other field is validated first, so a structurally
+ * malformed entry still throws whatever its type says. The id survives the drop: the caller needs it to tell
+ * whether a dropped entry is the newest one, and array position is not durable order.
+ * @param value - Untrusted lifecycle entry read from durable storage or the operator wire.
+ * @param path - Field path identifying this entry for a validation failure.
+ * @returns - The validated entry, or just its id when it is structurally sound but names a type
+ * outside the known vocabulary.
+ */
+function validateLifecycleEntry(value, path) {
+    const record = readRecord(value, path);
+    exactFields({ record, required: ["id", "at", "type", "state"], optional: [], path });
+    const type = readLifecycleType(record.type, `${path}.type`);
+    const id = readPositiveSequence(record.id, `${path}.id`);
+    const at = readTimestamp(record.at, `${path}.at`);
+    const state = record.state === null ? null : readMessageState(record.state, `${path}.state`);
+    const knownState = lifecycleEventState(type);
+    if (knownState === undefined)
+        return { recognized: false, id };
+    if (state !== knownState) {
+        throw new OperatorValidationError(`${path}.state`, "does not match the durable lifecycle type");
+    }
+    return { recognized: true, entry: { id, at, type, state } };
+}
+function validateWorktree(value, path) {
+    const record = readRecord(value, path);
+    exactFields({ record, required: ["kind", "path"], optional: [], path });
+    if (record.kind === "repository_root") {
+        if (record.path !== null)
+            throw new OperatorValidationError(`${path}.path`, "must be null at repository root");
+        return { kind: "repository_root", path: null };
+    }
+    if (record.kind === "worktree") {
+        return { kind: "worktree", path: readNonemptyString(record.path, `${path}.path`) };
+    }
+    throw new OperatorValidationError(`${path}.kind`, "unknown worktree kind");
+}
+function validateAdapterState(value, path) {
+    const record = readRecord(value, path);
+    exactFields({ record, required: ["state", "lastSeenAt"], optional: [], path });
+    switch (record.state) {
+        case "connected":
+            return { state: "connected", lastSeenAt: readTimestamp(record.lastSeenAt, `${path}.lastSeenAt`) };
+        case "disconnected":
+            return { state: "disconnected", lastSeenAt: readNullableTimestamp(record.lastSeenAt, `${path}.lastSeenAt`) };
+        case "expired":
+            return { state: "expired", lastSeenAt: readNullableTimestamp(record.lastSeenAt, `${path}.lastSeenAt`) };
+        default:
+            throw new OperatorValidationError(`${path}.state`, "unknown adapter state");
+    }
+}
+function validateImplementation(value, path) {
+    const record = readRecord(value, path);
+    if (record.available === true) {
+        exactFields({ record, required: ["available", "id", "displayName", "version", "metadata"], optional: [], path });
+        return {
+            available: true,
+            id: readOpenImplementationId(record.id, `${path}.id`),
+            displayName: readNonemptyString(record.displayName, `${path}.displayName`),
+            version: validateImplementationVersion(record.version, `${path}.version`),
+            metadata: validatePublicJsonObject(record.metadata, `${path}.metadata`),
+        };
+    }
+    if (record.available === false) {
+        exactFields({ record, required: ["available", "id", "version"], optional: [], path });
+        if (record.id === null) {
+            const version = validateImplementationVersion(record.version, `${path}.version`);
+            if (version.known) {
+                throw new OperatorValidationError(`${path}.version.known`, "must be false when implementation id is null");
+            }
+            return { available: false, id: null, version };
+        }
+        return {
+            available: false,
+            id: readOpenImplementationId(record.id, `${path}.id`),
+            version: validateImplementationVersion(record.version, `${path}.version`),
+        };
+    }
+    throw new OperatorValidationError(`${path}.available`, "must be a boolean discriminator");
+}
+function validateImplementationVersion(value, path) {
+    const record = readRecord(value, path);
+    if (record.known === true) {
+        exactFields({ record, required: ["known", "value"], optional: [], path });
+        return { known: true, value: readNonemptyString(record.value, `${path}.value`) };
+    }
+    if (record.known === false) {
+        exactFields({ record, required: ["known"], optional: [], path });
+        return { known: false };
+    }
+    throw new OperatorValidationError(`${path}.known`, "must be a boolean discriminator");
+}
+function validateStateEvent(value) {
+    const record = readRecord(value, "eventEnvelope.event");
+    switch (record.type) {
+        case "repository_upserted":
+            exactFields({ record, required: ["type", "repository"], optional: [], path: "eventEnvelope.event" });
+            return { type: "repository_upserted", repository: validateOperatorRepository(record.repository) };
+        case "repository_removed":
+            exactFields({ record, required: ["type", "repositoryId"], optional: [], path: "eventEnvelope.event" });
+            return { type: "repository_removed", repositoryId: readNonemptyString(record.repositoryId, "event.repositoryId") };
+        case "agent_upserted":
+            exactFields({ record, required: ["type", "agent"], optional: [], path: "eventEnvelope.event" });
+            return { type: "agent_upserted", agent: validateOperatorAgent(record.agent) };
+        case "agent_removed":
+            exactFields({ record, required: ["type", "agentId"], optional: [], path: "eventEnvelope.event" });
+            return { type: "agent_removed", agentId: readAgentId(record.agentId, "event.agentId") };
+        case "traffic_upserted":
+            exactFields({ record, required: ["type", "traffic"], optional: [], path: "eventEnvelope.event" });
+            return { type: "traffic_upserted", traffic: validateOperatorTraffic(record.traffic) };
+        case "traffic_removed":
+            exactFields({ record, required: ["type", "trafficId"], optional: [], path: "eventEnvelope.event" });
+            return { type: "traffic_removed", trafficId: readOpaqueId(record.trafficId, "event.trafficId") };
+        default:
+            throw new OperatorValidationError("eventEnvelope.event.type", "unknown state event");
+    }
+}
+/** Names each command kind in the error raised when a result of another kind answers it. */
+const commandDescriptions = {
+    ping_agent: "a ping command",
+    expire_message: "an expiry command",
+    archive_agent: "an archive command",
+};
+const resultDescriptions = {
+    ping_accepted: "ping acceptance",
+    expiry_accepted: "expiry acceptance",
+    archive_accepted: "archive acceptance",
+    command_rejected: "rejection",
+};
+function validateCommandMember(value) {
+    const record = readRecord(value, "commandEnvelope.command");
+    switch (record.type) {
+        case "ping_agent":
+            exactFields({ record, required: ["type", "targetAgentId"], optional: [], path: "commandEnvelope.command" });
+            return { type: "ping_agent", targetAgentId: readAgentId(record.targetAgentId, "command.targetAgentId") };
+        case "expire_message":
+            exactFields({ record, required: ["type", "messageId"], optional: [], path: "commandEnvelope.command" });
+            return { type: "expire_message", messageId: readOpaqueId(record.messageId, "command.messageId") };
+        case "archive_agent":
+            exactFields({ record, required: ["type", "targetAgentId"], optional: [], path: "commandEnvelope.command" });
+            return { type: "archive_agent", targetAgentId: readAgentId(record.targetAgentId, "command.targetAgentId") };
+        default:
+            throw new OperatorValidationError("commandEnvelope.command.type", "unknown command");
+    }
+}
+function validatePublicJson(value, path, traversal = { seen: new WeakSet() }) {
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new OperatorValidationError(path, "must be a finite JSON number");
+        return value;
+    }
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        enterPublicJsonContainer(value, path, traversal);
+        return readArray(value, path).map((entry, index) => validatePublicJson(entry, `${path}[${String(index)}]`, traversal));
+    }
+    return validatePublicJsonObject(value, path, traversal);
+}
+function validatePublicJsonObject(value, path, traversal = { seen: new WeakSet() }) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new OperatorValidationError(path, "must be an object");
+    }
+    enterPublicJsonContainer(value, path, traversal);
+    const output = {};
+    for (const [key, entry] of readOwnEnumerableEntries(value, path)) {
+        Object.defineProperty(output, key, {
+            value: validatePublicJson(entry, `${path}.${key}`, traversal),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return output;
+}
+function enterPublicJsonContainer(value, path, traversal) {
+    if (traversal.seen.has(value)) {
+        throw new OperatorValidationError(path, "contains a cyclic or repeated container reference");
+    }
+    traversal.seen.add(value);
+}
+function guardFail(path, reason) {
+    throw new OperatorValidationError(path, reason);
+}
+function readRecord(value, path) {
+    return guardReadRecord(value, path, guardFail);
+}
+function readArray(value, path) {
+    return guardReadArray(value, path, guardFail);
+}
+function readOwnEnumerableEntries(value, path) {
+    return guardReadOwnEnumerableEntries(value, path, guardFail);
+}
+function exactFields(check) {
+    guardExactFields({ ...check, fail: guardFail });
+}
+function readProtocolVersion(value, path) {
+    if (value !== OPERATOR_PROTOCOL_VERSION)
+        throw new OperatorValidationError(path, "unsupported protocol version");
+    return OPERATOR_PROTOCOL_VERSION;
+}
+function readNonemptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new OperatorValidationError(path, "must be non-empty text");
+    return value;
+}
+function readBoundedLine(value, limit, label, path) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > limit) {
+        throw new OperatorValidationError(path, `must be a bounded one-line ${label}`);
+    }
+    if (hasControlCharacter(value))
+        throw new OperatorValidationError(path, `must be a bounded one-line ${label}`);
+    return value;
+}
+function readMessageSubject(value, path) {
+    return readBoundedLine(value, MESSAGE_SUBJECT_LIMIT_CHARACTERS, "subject", path);
+}
+function readMessageType(value, path) {
+    return readBoundedLine(value, MESSAGE_TYPE_LIMIT_CHARACTERS, "type", path);
+}
+function readBoolean(value, path) {
+    if (typeof value !== "boolean")
+        throw new OperatorValidationError(path, "must be a boolean");
+    return value;
+}
+function readLifecycleType(value, path) {
+    if (typeof value !== "string" || !/^[a-z][a-z0-9_]{0,127}$/u.test(value)) {
+        throw new OperatorValidationError(path, "invalid lifecycle type");
+    }
+    return value;
+}
+/**
+ * Read a provider identity off the operator wire.
+ *
+ * Held to the broker's own registration rule, so it admits exactly the identities a registration can
+ * have written and enumerates no installed implementation.
+ *
+ * The consuming side maps this over `snapshot.agents` with no per-row catch, so one refused row costs
+ * the whole frame. The producer skips such a row before it reaches the wire, and
+ * {@link OPERATOR_PROTOCOL_VERSION} keeps peers that disagree on this rule from pairing.
+ * @param value - Untrusted candidate identity.
+ * @param path - Field path named in the rejection.
+ * @returns - The validated provider identity.
+ */
+function readOpenImplementationId(value, path) {
+    const id = readNonemptyString(value, path);
+    if (!isImplementationId(id))
+        throw new OperatorValidationError(path, "invalid provider identity");
+    return id;
+}
+/**
+ * Read an agent identity off the operator wire.
+ *
+ * An id whose tail exceeds the protocol's bound carries the same legacy exposure, and the same
+ * version answer to it, as {@link readOpenImplementationId} describes.
+ *
+ * The consumers of {@link isAgentId} outside this projection — the notification, delivery-client and
+ * adapter paths — are unversioned and hard-fail their own delivery instead. That is the outcome an
+ * unaddressable id deserves there: a wake or a send aimed at an id nothing can route to has no
+ * degraded form worth reaching for.
+ * @param value - Untrusted candidate identity.
+ * @param path - Field path named in the rejection.
+ * @returns - The validated agent identity.
+ */
+function readAgentId(value, path) {
+    const id = readNonemptyString(value, path);
+    if (!isAgentId(id))
+        throw new OperatorValidationError(path, "invalid agent identity");
+    return id;
+}
+function readOpaqueId(value, path) {
+    const id = readNonemptyString(value, path);
+    if (!isOpaqueId(id))
+        throw new OperatorValidationError(path, "invalid opaque identity");
+    return id;
+}
+function readRejectionReason(value, path) {
+    const reason = readNonemptyString(value, path);
+    const known = OPERATOR_REJECTION_REASONS.find((candidate) => candidate === reason);
+    if (!known)
+        throw new OperatorValidationError(path, "unknown rejection reason");
+    return known;
+}
+function readStringArray(value, path) {
+    return readArray(value, path).map((entry, index) => readNonemptyString(entry, `${path}[${String(index)}]`));
+}
+function readInteger(value, path) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new OperatorValidationError(path, "must be a safe integer");
+    }
+    return value;
+}
+function readNonnegativeInteger(value, path) {
+    const integer = readInteger(value, path);
+    if (integer < 0)
+        throw new OperatorValidationError(path, "must be non-negative");
+    return integer;
+}
+function readSequence(value, path) {
+    return readNonnegativeInteger(value, path);
+}
+function readPositiveSequence(value, path) {
+    const sequence = readInteger(value, path);
+    if (sequence < 1)
+        throw new OperatorValidationError(path, "must be positive");
+    return sequence;
+}
+function readTimestamp(value, path) {
+    return readNonnegativeInteger(value, path);
+}
+function readNullableTimestamp(value, path) {
+    return value === null ? null : readTimestamp(value, path);
+}
+function readAgentLifecycle(value, path) {
+    if (value === "active" || value === "terminal" || value === "reaped")
+        return value;
+    throw new OperatorValidationError(path, "unknown agent lifecycle");
+}
+function readMessageState(value, path) {
+    if (!MESSAGE_STATES.some((candidate) => candidate === value))
+        throw new OperatorValidationError(path, "unknown message state");
+    return value;
+}
+function assertLifecycleOrder(lifecycle, path) {
+    for (let index = 1; index < lifecycle.length; index += 1) {
+        const previous = lifecycle[index - 1];
+        const current = lifecycle[index];
+        if (previous && current && previous.id >= current.id) {
+            throw new OperatorValidationError(path, "must follow strict durable lifecycle-id order");
+        }
+    }
+}
+function assertUnique(values, path, label) {
+    if (new Set(values).size !== values.length)
+        throw new OperatorValidationError(path, `duplicate ${label}`);
+}