@haywoodmarx/agent-pager 0.1.0

package/dist/src/operator/update-store.js

@@ -0,0 +1,162 @@
+import { openBrokerDatabase } from "../broker/database.js";
+import { OPERATOR_PROTOCOL_VERSION, } from "./protocol.js";
+import { validateOperatorEventEnvelope } from "./validation.js";
+/** Reports corrupt or incompatible durable operator-stream state. */
+class OperatorEventStoreError extends Error {
+}
+/** SQLite-backed bounded replay storage owned by one broker epoch. */
+export class SqliteOperatorEventStore {
+    #database;
+    #epoch;
+    #replayLimit;
+    /**
+     * Open replay storage adjacent to the broker's durable state.
+     * @param databasePath - Broker SQLite path containing the operator stream tables.
+     * @param epoch - Current broker generation that owns new event sequence values.
+     * @param replayLimit - Maximum number of event envelopes retained globally.
+     * @param openDatabase - Opens the connection this store owns and closes.
+     */
+    constructor(databasePath, epoch, replayLimit = 1_024, openDatabase = openBrokerDatabase) {
+        if (!epoch)
+            throw new OperatorEventStoreError("operator stream epoch must be non-empty");
+        if (!Number.isSafeInteger(replayLimit) || replayLimit < 1) {
+            throw new OperatorEventStoreError("operator replay limit must be a positive safe integer");
+        }
+        this.#database = openDatabase(databasePath);
+        this.#epoch = epoch;
+        this.#replayLimit = replayLimit;
+        // A constructor that throws hands its caller nothing to close, so the connection is closed here.
+        try {
+            this.#initializeEpoch();
+        }
+        catch (error) {
+            this.#database.close();
+            throw error;
+        }
+    }
+    /** @inheritdoc */
+    currentCursor() {
+        const row = this.#state();
+        return {
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            epoch: this.#epoch,
+            sequence: readSequence(row.sequence),
+        };
+    }
+    /** @inheritdoc */
+    append(events) {
+        if (events.length === 0)
+            return [];
+        const current = this.currentCursor().sequence;
+        const envelopes = events.map((event, index) => validateOperatorEventEnvelope({
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            epoch: this.#epoch,
+            sequence: current + index + 1,
+            event,
+        }));
+        this.#database.exec("begin immediate");
+        try {
+            const state = this.#state();
+            if (readSequence(state.sequence) !== current) {
+                throw new OperatorEventStoreError("operator stream cursor changed during batch persistence");
+            }
+            for (const envelope of envelopes) {
+                this.#database
+                    .prepare("insert into operator_stream_events(epoch, sequence, payload) values (?, ?, ?)")
+                    .run(this.#epoch, envelope.sequence, JSON.stringify(envelope));
+            }
+            const next = envelopes.at(-1)?.sequence;
+            if (next === undefined)
+                throw new OperatorEventStoreError("operator event batch is unexpectedly empty");
+            this.#database.prepare("update operator_stream_state set sequence = ? where singleton = 1").run(next);
+            const oldestRetained = Math.max(1, next - this.#replayLimit + 1);
+            this.#database
+                .prepare("delete from operator_stream_events where epoch = ? and sequence < ?")
+                .run(this.#epoch, oldestRetained);
+            this.#database.exec("commit");
+            return envelopes;
+        }
+        catch (error) {
+            this.#database.exec("rollback");
+            throw error;
+        }
+    }
+    /** @inheritdoc */
+    replay(cursor) {
+        if (cursor.epoch !== this.#epoch)
+            return { type: "epoch_changed" };
+        const current = this.currentCursor().sequence;
+        if (cursor.sequence > current)
+            return { type: "cursor_gap" };
+        if (cursor.sequence === current)
+            return { type: "events", events: [] };
+        const rows = this.#database
+            .prepare("select sequence, payload from operator_stream_events where epoch = ? and sequence > ? order by sequence")
+            .all(this.#epoch, cursor.sequence);
+        if (rows.length === 0 || Number(rows[0]?.sequence) !== cursor.sequence + 1)
+            return { type: "cursor_gap" };
+        const events = rows.map((row, index) => {
+            if (Number(row.sequence) !== cursor.sequence + index + 1 || typeof row.payload !== "string") {
+                throw new OperatorEventStoreError("operator replay is not strictly contiguous");
+            }
+            let value;
+            try {
+                value = JSON.parse(row.payload);
+            }
+            catch {
+                throw new OperatorEventStoreError("operator replay contains invalid JSON");
+            }
+            return validateOperatorEventEnvelope(value);
+        });
+        if (events.at(-1)?.sequence !== current) {
+            throw new OperatorEventStoreError("operator replay does not reach the durable cursor");
+        }
+        return { type: "events", events };
+    }
+    /** @inheritdoc */
+    close() {
+        try {
+            this.#database.exec("pragma wal_checkpoint(TRUNCATE)");
+        }
+        finally {
+            this.#database.close();
+        }
+    }
+    #initializeEpoch() {
+        this.#database.exec("begin immediate");
+        try {
+            const existing = this.#database
+                .prepare("select epoch, sequence from operator_stream_state where singleton = 1")
+                .get();
+            if (!existing || existing.epoch !== this.#epoch) {
+                this.#database.exec("delete from operator_stream_events; delete from operator_stream_state;");
+                this.#database
+                    .prepare("insert into operator_stream_state(singleton, epoch, sequence) values (1, ?, 0)")
+                    .run(this.#epoch);
+            }
+            else {
+                readSequence(existing.sequence);
+            }
+            this.#database.exec("commit");
+        }
+        catch (error) {
+            this.#database.exec("rollback");
+            throw error;
+        }
+    }
+    #state() {
+        const row = this.#database
+            .prepare("select epoch, sequence from operator_stream_state where singleton = 1")
+            .get();
+        if (!row || row.epoch !== this.#epoch)
+            throw new OperatorEventStoreError("operator stream epoch state is unavailable");
+        return row;
+    }
+}
+function readSequence(value) {
+    const sequence = Number(value);
+    if (!Number.isSafeInteger(sequence) || sequence < 0) {
+        throw new OperatorEventStoreError("operator stream sequence is invalid");
+    }
+    return sequence;
+}

package/dist/src/operator/updates.d.ts

@@ -0,0 +1,94 @@
+import type { BrokerCommit, BrokerTrafficReadResult } from "../broker/broker.js";
+import type { BrokerSnapshot } from "../broker/snapshot.js";
+import { type OperatorAgentProjectionDependencies } from "./agent-projection.js";
+import { type OperatorCursor, type OperatorDiagnostic, type OperatorEventEnvelope, type OperatorSnapshot } from "./protocol.js";
+import type { OperatorEventStorePort } from "./update-store.js";
+/** Supplies durable broker state and successful-commit observation to the update projection. */
+export interface OperatorUpdateSourcePort {
+    /**
+     * Return the agent-derived broker state used by repository and agent projection.
+     * @returns Workspaces, agents, and their connection states, with no deliveries.
+     */
+    operatorAgentSource(): Pick<BrokerSnapshot, "workspaces" | "agents" | "connections">;
+    /**
+     * Return bounded durable traffic without claiming message bodies.
+     * @returns Durable traffic rows from the broker's bounded window, each carrying a traffic position, and
+     * the rows skipped while reading it.
+     */
+    operatorTrafficRecords(): BrokerTrafficReadResult;
+    /**
+     * Observe commits only after the domain transaction succeeds.
+     * @param listener - Isolated post-commit projection callback receiving what the commit changed.
+     * @returns A callback that detaches the observer.
+     */
+    subscribeCommits(listener: (commit: BrokerCommit) => void): () => void;
+}
+/** Configures deterministic projection, durability, and timestamp collaborators. */
+export type OperatorUpdateDependencies = {
+    /** Supplies durable broker source state. */ source: OperatorUpdateSourcePort;
+    /** Supplies repository discovery and public provider metadata. */ projection: OperatorAgentProjectionDependencies;
+    /** Persists complete epoch-scoped replay batches. */ store: OperatorEventStorePort;
+    /** Supplies broker-clock timestamps for snapshots and retention metadata. */ now: () => number;
+};
+/** Reports a bounded failure without retaining thrown values or projected content. */
+export type OperatorUpdateDiagnostic = {
+    /** Identifies the terminal stream condition. */ type: "stream_unavailable";
+    /** Identifies the boundary that could not preserve authoritative ordering. */ stage: "projection" | "journal";
+    /** Records the last cursor that was durably safe to publish. */ cursor: OperatorCursor;
+    /** Records when the boundary became unavailable. */ at: number;
+};
+/** Reports the initial frames needed before a subscriber can consume live events. */
+export type OperatorOpenResult = {
+    type: "initial";
+    snapshot: OperatorSnapshot;
+} | {
+    type: "resumed";
+    events: OperatorEventEnvelope[];
+} | {
+    /** Requires complete replacement before live events. */ type: "replacement";
+    /** Identifies why exact replay was impossible. */ reason: "cursor_gap" | "epoch_changed";
+    /** Supplies the complete authoritative replacement. */ snapshot: OperatorSnapshot;
+} | {
+    type: "unavailable";
+};
+/** Carries a post-open publication or terminal integrity signal. */
+export type OperatorPublication = {
+    type: "event";
+    envelope: OperatorEventEnvelope;
+} | {
+    /** Reports one operator-visible condition beside the ordered stream. */ type: "diagnostic";
+    diagnostic: OperatorDiagnostic;
+} | {
+    type: "unavailable";
+};
+/** Produces complete snapshots and durable strictly ordered projection changes. */
+export declare class OperatorUpdateService {
+    #private;
+    /**
+     * Construct an update service from explicit durable and projection boundaries.
+     * @param dependencies - Source, projection, journal, and clock collaborators.
+     */
+    constructor(dependencies: OperatorUpdateDependencies);
+    /**
+     * Atomically establish replay state and subsequent publication for one consumer.
+     * @param cursor - Last incorporated position, or null for a cold snapshot.
+     * @param subscriber - Isolated consumer of future durable publications.
+     * @returns Initial hydration or recovery result plus an unsubscribe callback.
+     */
+    open(cursor: OperatorCursor | null, subscriber: (publication: OperatorPublication) => void): {
+        result: OperatorOpenResult;
+        unsubscribe: () => void;
+    };
+    /**
+     * Return the latest client-visible cursor without exposing mutable state.
+     * @returns Last complete batch position committed to the replay journal.
+     */
+    cursor(): OperatorCursor;
+    /**
+     * Return bounded stream-integrity diagnostics.
+     * @returns Defensive copies containing no projected content or thrown values.
+     */
+    diagnostics(): OperatorUpdateDiagnostic[];
+    /** Stop commit observation and close replay storage. */
+    close(): void;
+}

package/dist/src/operator/updates.js

@@ -0,0 +1,280 @@
+import { projectOperatorAgents } from "./agent-projection.js";
+import { OPERATOR_PROTOCOL_VERSION, } from "./protocol.js";
+import { operatorDiagnostic } from "./diagnostics.js";
+import { projectOperatorTraffic } from "./traffic-projection.js";
+/** Bounds retained stream-integrity diagnostics. */
+const UPDATE_DIAGNOSTIC_LIMIT = 64;
+/** Broker tables whose rows feed the repository and agent halves of an operator snapshot. */
+const AGENT_SOURCE_TABLES = ["agents", "sessions", "workspaces", "alias_history"];
+/** Broker tables whose rows feed the traffic half of an operator snapshot. */
+const TRAFFIC_SOURCE_TABLES = ["messages", "message_events", "claims", "traffic_positions"];
+/** Produces complete snapshots and durable strictly ordered projection changes. */
+export class OperatorUpdateService {
+    #source;
+    #projection;
+    #store;
+    #now;
+    #subscribers = new Set();
+    #diagnostics = [];
+    #unsubscribeCommits;
+    #snapshot;
+    #unavailable = false;
+    #refreshPending = false;
+    #pendingTables = new Set();
+    #refreshing = false;
+    /**
+     * Construct an update service from explicit durable and projection boundaries.
+     * @param dependencies - Source, projection, journal, and clock collaborators.
+     */
+    constructor(dependencies) {
+        this.#source = dependencies.source;
+        this.#store = dependencies.store;
+        this.#now = dependencies.now;
+        this.#projection = {
+            ...dependencies.projection,
+            diagnostics: {
+                report: (diagnostic) => {
+                    this.#publish({ type: "diagnostic", diagnostic });
+                },
+            },
+            now: dependencies.now,
+        };
+        this.#snapshot = this.#project(this.#store.currentCursor(), undefined);
+        this.#unsubscribeCommits = this.#source.subscribeCommits((commit) => {
+            this.#refreshAfterCommit(commit);
+        });
+    }
+    /**
+     * Atomically establish replay state and subsequent publication for one consumer.
+     * @param cursor - Last incorporated position, or null for a cold snapshot.
+     * @param subscriber - Isolated consumer of future durable publications.
+     * @returns Initial hydration or recovery result plus an unsubscribe callback.
+     */
+    open(cursor, subscriber) {
+        if (this.#unavailable)
+            return { result: { type: "unavailable" }, unsubscribe: () => undefined };
+        let result;
+        if (cursor === null) {
+            result = { type: "initial", snapshot: cloneSnapshot(this.#snapshot) };
+        }
+        else {
+            let replay;
+            try {
+                replay = this.#store.replay(cursor);
+            }
+            catch {
+                this.#fail("journal");
+                return { result: { type: "unavailable" }, unsubscribe: () => undefined };
+            }
+            result =
+                replay.type === "events"
+                    ? { type: "resumed", events: replay.events.map(cloneEnvelope) }
+                    : {
+                        type: "replacement",
+                        reason: replay.type,
+                        snapshot: cloneSnapshot(this.#snapshot),
+                    };
+        }
+        this.#subscribers.add(subscriber);
+        return { result, unsubscribe: () => this.#subscribers.delete(subscriber) };
+    }
+    /**
+     * Return the latest client-visible cursor without exposing mutable state.
+     * @returns Last complete batch position committed to the replay journal.
+     */
+    cursor() {
+        return { ...this.#snapshot.cursor };
+    }
+    /**
+     * Return bounded stream-integrity diagnostics.
+     * @returns Defensive copies containing no projected content or thrown values.
+     */
+    diagnostics() {
+        return this.#diagnostics.map((entry) => ({ ...entry, cursor: { ...entry.cursor } }));
+    }
+    /** Stop commit observation and close replay storage. */
+    close() {
+        this.#unsubscribeCommits();
+        this.#subscribers.clear();
+        this.#store.close();
+    }
+    #refreshAfterCommit(commit) {
+        if (this.#unavailable)
+            return;
+        // Coalesced refreshes cover every table any of them named, so a merged run must re-derive the
+        // union rather than only what the last commit touched.
+        if (commit.tables === undefined)
+            this.#pendingTables = undefined;
+        else if (this.#pendingTables !== undefined)
+            for (const table of commit.tables)
+                this.#pendingTables.add(table);
+        this.#refreshPending = true;
+        if (this.#refreshing)
+            return;
+        this.#refreshing = true;
+        try {
+            while (this.#refreshPending) {
+                this.#refreshPending = false;
+                const tables = this.#pendingTables;
+                this.#pendingTables = new Set();
+                this.#refreshOnce(tables);
+            }
+        }
+        finally {
+            this.#refreshing = false;
+        }
+    }
+    #refreshOnce(tables) {
+        let next;
+        try {
+            next = this.#project(this.#snapshot.cursor, this.#snapshot, tables);
+        }
+        catch {
+            this.#fail("projection");
+            return;
+        }
+        const changes = diffSnapshots(this.#snapshot, next);
+        if (changes.length === 0)
+            return;
+        let envelopes;
+        try {
+            envelopes = verifyDurableBatch(this.#snapshot.cursor, changes, this.#store.append(changes));
+        }
+        catch {
+            this.#fail("journal");
+            return;
+        }
+        const cursor = envelopes.at(-1);
+        if (!cursor) {
+            this.#fail("journal");
+            return;
+        }
+        this.#snapshot = {
+            ...next,
+            cursor: {
+                protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                epoch: cursor.epoch,
+                sequence: cursor.sequence,
+            },
+            epoch: cursor.epoch,
+        };
+        for (const envelope of envelopes)
+            this.#publish({ type: "event", envelope });
+    }
+    /**
+     * Re-derive the operator snapshot, skipping either half whose source tables did not change.
+     *
+     * A commit that names its tables cannot have altered a half none of them feed, so that half is
+     * carried across by reference and the diff skips it outright. An unnamed table set means the
+     * changeset was incomplete, and both halves are re-derived.
+     * @param cursor - Cursor to stamp on the projected snapshot.
+     * @param previous - Snapshot whose unchanged halves are carried across, or undefined before the first projection.
+     * @param tables - Tables the commits behind this refresh changed, or undefined to re-derive all.
+     * @returns Projected snapshot at the supplied cursor.
+     */
+    #project(cursor, previous, tables) {
+        const agentsStale = previous === undefined || tables === undefined || intersects(tables, AGENT_SOURCE_TABLES);
+        const trafficStale = previous === undefined || tables === undefined || intersects(tables, TRAFFIC_SOURCE_TABLES);
+        const projected = agentsStale
+            ? projectOperatorAgents(this.#source.operatorAgentSource(), this.#projection)
+            : { repositories: previous.repositories, agents: previous.agents };
+        return {
+            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+            epoch: cursor.epoch,
+            cursor,
+            generatedAt: this.#now(),
+            repositories: projected.repositories,
+            agents: projected.agents,
+            traffic: trafficStale
+                ? projectOperatorTraffic(this.#source, {
+                    report: (diagnostic) => {
+                        this.#publish({ type: "diagnostic", diagnostic });
+                    },
+                }, this.#now)
+                : previous.traffic,
+        };
+    }
+    #fail(stage) {
+        if (this.#unavailable)
+            return;
+        this.#unavailable = true;
+        const diagnostic = {
+            type: "stream_unavailable",
+            stage,
+            cursor: { ...this.#snapshot.cursor },
+            at: this.#now(),
+        };
+        this.#diagnostics.push(diagnostic);
+        if (this.#diagnostics.length > UPDATE_DIAGNOSTIC_LIMIT)
+            this.#diagnostics.shift();
+        this.#publish({
+            type: "diagnostic",
+            diagnostic: operatorDiagnostic("broker", "error", "operator stream", `unavailable at ${stage}`, this.#now()),
+        });
+        this.#publish({ type: "unavailable" });
+        this.#subscribers.clear();
+    }
+    #publish(publication) {
+        for (const subscriber of [...this.#subscribers]) {
+            try {
+                subscriber(publication);
+            }
+            catch {
+                this.#subscribers.delete(subscriber);
+            }
+        }
+    }
+}
+function diffSnapshots(previous, next) {
+    const repositoryChanges = diffMap(previous.repositories, next.repositories, (value) => value.id, (repository) => ({ type: "repository_upserted", repository }), (repositoryId) => ({ type: "repository_removed", repositoryId }));
+    const agentChanges = diffMap(previous.agents, next.agents, (value) => value.id, (agent) => ({ type: "agent_upserted", agent }), (agentId) => ({ type: "agent_removed", agentId }));
+    const trafficChanges = diffMap(previous.traffic, next.traffic, (value) => value.trafficId, (traffic) => ({ type: "traffic_upserted", traffic }), (trafficId) => ({ type: "traffic_removed", trafficId }));
+    return [
+        ...repositoryChanges.upserts,
+        ...agentChanges.upserts,
+        ...trafficChanges.upserts,
+        ...trafficChanges.removals,
+        ...agentChanges.removals,
+        ...repositoryChanges.removals,
+    ];
+}
+function intersects(tables, candidates) {
+    return candidates.some((table) => tables.has(table));
+}
+function diffMap(previous, next, key, upsert, removal) {
+    // A projection half the refresh skipped is carried across by reference, and identity is the only
+    // check that can tell that apart from a rebuild that happened to produce equal values.
+    if (previous === next)
+        return { upserts: [], removals: [] };
+    const before = new Map(previous.map((value) => [key(value), value]));
+    const after = new Map(next.map((value) => [key(value), value]));
+    const upserts = [];
+    for (const value of next) {
+        const old = before.get(key(value));
+        if (old === undefined || JSON.stringify(old) !== JSON.stringify(value))
+            upserts.push(upsert(value));
+    }
+    const removals = [];
+    for (const value of previous)
+        if (!after.has(key(value)))
+            removals.push(removal(key(value)));
+    return { upserts, removals };
+}
+function cloneSnapshot(snapshot) {
+    return structuredClone(snapshot);
+}
+function cloneEnvelope(envelope) {
+    return structuredClone(envelope);
+}
+function verifyDurableBatch(cursor, changes, envelopes) {
+    if (envelopes.length !== changes.length)
+        throw new Error("operator journal returned an incomplete event batch");
+    return envelopes.map((envelope, index) => {
+        if (envelope.epoch !== cursor.epoch ||
+            envelope.sequence !== cursor.sequence + index + 1 ||
+            JSON.stringify(envelope.event) !== JSON.stringify(changes[index])) {
+            throw new Error("operator journal returned a mismatched event batch");
+        }
+        return cloneEnvelope(envelope);
+    });
+}

package/dist/src/operator/validation.d.ts

@@ -0,0 +1,114 @@
+import { type OperatorAgent, type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDiagnostic, type OperatorEventEnvelope, type OperatorMessageBody, type OperatorRepository, type OperatorSnapshot, type OperatorTraffic, type OperatorTransportRequest } from "./protocol.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 declare const OPERATOR_ARRAY_LENGTH_LIMIT = 4096;
+/** Reports that an untrusted value does not satisfy the operator protocol. */
+export declare class OperatorValidationError extends Error {
+    /** Identifies the rejected field. */
+    readonly path: string;
+    /**
+     * 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: string, reason: string);
+}
+/**
+ * Validate an untrusted operator cursor.
+ * @param value - Candidate cursor received from an external boundary.
+ * @returns A fully validated epoch and monotonic sequence position.
+ */
+export declare function validateOperatorCursor(value: unknown): OperatorCursor;
+/**
+ * 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 declare function validateOperatorRepository(value: unknown): OperatorRepository;
+/**
+ * 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 declare function validateOperatorAgent(value: unknown): OperatorAgent;
+/**
+ * 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 declare function validateOperatorTraffic(value: unknown): OperatorTraffic;
+/**
+ * Validate one public operator body.
+ * @param value - Candidate retained public body.
+ * @returns A bounded body representation whose metadata matches its public raw copy.
+ */
+export declare function validateOperatorMessageBody(value: unknown): OperatorMessageBody;
+/**
+ * Validate an untrusted operator diagnostic.
+ * @param value - Candidate diagnostic received from an external boundary.
+ * @returns A diagnostic with a bounded scope and summary.
+ */
+export declare function validateOperatorDiagnostic(value: unknown): OperatorDiagnostic;
+/**
+ * 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 declare function validateOperatorSnapshot(value: unknown): OperatorSnapshot;
+/**
+ * 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 declare function validateOperatorSnapshotByteLength(byteLength: number): number;
+/**
+ * Validate an untrusted sequenced state event.
+ * @param value - Candidate event envelope received from an external boundary.
+ * @returns A fully typed authoritative state event.
+ */
+export declare function validateOperatorEventEnvelope(value: unknown): OperatorEventEnvelope;
+/**
+ * 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 declare function classifyOperatorEvent(cursorValue: unknown, value: unknown): OperatorCursorResult;
+/**
+ * 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 declare function validateOperatorTransportRequest(value: unknown): OperatorTransportRequest;
+/**
+ * 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 declare function validateOperatorControlId(value: unknown): string;
+/**
+ * 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 declare function validateOperatorCommand(value: unknown): OperatorCommandEnvelope;
+/**
+ * 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 declare function validateOperatorCommandResult(value: unknown): OperatorCommandResult;
+/**
+ * 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 declare function validateOperatorCommandResultForCommand(commandValue: unknown, resultValue: unknown): OperatorCorrelatedCommandResult;