@haywoodmarx/agent-pager 0.1.0

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

@@ -0,0 +1,511 @@
+import type { AgentId, MessageState } from "../broker/protocol.js";
+/**
+ * Identifies the operator wire contract implemented by this process.
+ *
+ * Every envelope that carries this number is rejected outright when it does not match exactly, so a
+ * bump locks out every differently-versioned peer at that boundary immediately. Bump only for a
+ * breaking change: one where a peer on the other version would misinterpret data it receives, or
+ * must reject data the other version considers valid.
+ *
+ * Every operator shape is closed by `exactFields` (`src/shared/guards.ts`): it rejects any key outside
+ * its permitted set. That makes adding a field to a validated shape breaking in one direction no matter
+ * how absence is handled — a consumer built before the field existed rejects a producer's row that now
+ * carries it, with "unexpected field". Nothing below excuses that direction; it is a real, if narrow,
+ * cost of adding a field, accepted here rather than bumped, because bumping would not remove that one
+ * record-shaped rejection — it would only replace it with an earlier, wholesale "incompatible_version"
+ * that blocks every exchange between the two peers, including ones neither side's change affects.
+ *
+ * The other direction — a consumer built after the field existed, reading a producer that never sent
+ * it — is safe without a bump, and is the direction the additive-field exception actually covers: adding
+ * an optional field is not a breaking change on its own, provided every validator treats the field's
+ * absence identically to an explicit wire-level absence marker (`null`, where the field allows one). An
+ * older producer's row that never had the key and a newer producer's row that sends it absent must
+ * validate identically.
+ */
+export declare const OPERATOR_PROTOCOL_VERSION = 2;
+/** Bounds the UTF-8 JSON payload carried by one snapshot transfer. */
+export declare const OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES: number;
+/** Selects the raw byte count encoded by every non-final snapshot chunk. */
+export declare const OPERATOR_SNAPSHOT_CHUNK_BYTES: number;
+/** Bounds every newline-delimited server frame after JSON encoding. */
+export declare const OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES: number;
+/** Represents JSON data that is safe to cross the operator boundary. */
+export type OperatorJsonValue = null | boolean | number | string | OperatorJsonValue[] | OperatorJsonObject;
+/** Represents an object whose values are safe to cross the operator boundary. */
+export type OperatorJsonObject = {
+    [key: string]: OperatorJsonValue;
+};
+/** Identifies one position in an epoch-scoped operator event stream. */
+export type OperatorCursor = {
+    /** Identifies the operator wire contract used at this position. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies the broker generation that owns the sequence. */
+    epoch: string;
+    /** Identifies the last event incorporated into local state. */
+    sequence: number;
+};
+/** Identifies a repository used only to group operator presentation state. */
+export type OperatorRepository = {
+    /** Identifies this presentation projection without granting broker authority. */
+    id: string;
+    /** Supplies the resolved repository root. */
+    rootPath: string;
+    /** Names the repository by the shortest trailing path segments no other repository shares. */
+    name: string;
+};
+/** Describes whether an agent runs at its repository root or in a linked worktree. */
+export type OperatorWorktree = {
+    /** Reports that the agent runs at the repository root. */
+    kind: "repository_root";
+    /** Prevents a root agent from carrying a second grouping path. */
+    path: null;
+} | {
+    /** Reports that the agent runs in a linked worktree. */
+    kind: "worktree";
+    /** Supplies the resolved worktree path shown as agent detail. */
+    path: string;
+};
+/** Reports whether an implementation version is available. */
+export type OperatorImplementationVersion = {
+    /** Reports that the provider supplied a version. */
+    known: true;
+    /** Supplies the provider-owned version without interpretation. */
+    value: string;
+} | {
+    /** Reports that the provider did not supply a version. */
+    known: false;
+};
+/** Describes persisted implementation identity and optional installed-provider presentation data. */
+export type OperatorImplementation = {
+    /** Reports that the implementation provider is available to the projection boundary. */
+    available: true;
+    /** Supplies the provider id without closing the protocol over installed implementations. */
+    id: string;
+    /** Supplies the provider-owned display label. */
+    displayName: string;
+    /** Reports the persisted implementation version when known. */
+    version: OperatorImplementationVersion;
+    /** Carries public provider-owned JSON without interpreting its keys or values. */
+    metadata: OperatorJsonObject;
+} | {
+    /** Reports that no installed provider can supply presentation metadata. */
+    available: false;
+    /** Preserves a persisted provider id. */
+    id: string;
+    /** Reports the persisted implementation version when known. */
+    version: OperatorImplementationVersion;
+} | {
+    /** Reports that no implementation identity was persisted. */
+    available: false;
+    /** Distinguishes absent identity from an unavailable installed provider. */
+    id: null;
+    /** Cannot report a version without a persisted implementation identity. */
+    version: {
+        known: false;
+    };
+};
+/** Reports the exhaustive adapter connectivity state exposed to operator consumers. */
+export type OperatorAdapterState = {
+    /** Reports an attached adapter with a current lease. */
+    state: "connected";
+    /** Records the most recent broker observation. */
+    lastSeenAt: number;
+} | {
+    /** Reports that no active adapter is attached. */
+    state: "disconnected";
+    /** Records the last observation when one exists. */
+    lastSeenAt: number | null;
+} | {
+    /** Reports that the selected adapter lease elapsed. */
+    state: "expired";
+    /** Records the last observation when one exists. */
+    lastSeenAt: number | null;
+};
+/** Describes an operator-visible agent without changing broker routing identity. */
+export type OperatorAgent = {
+    /** Identifies the durable broker agent. */
+    id: AgentId;
+    /** Supplies the current routable alias. */
+    alias: string;
+    /** Lists earlier aliases retained for identity inspection. */
+    previousAliases: string[];
+    /** Names the workspace half of the address that reaches this agent from anywhere. */
+    workspace: string;
+    /** Records the durable registration time used for stable ordering. */
+    registeredAt: number;
+    /** Reports the durable identity lifecycle independently of adapter health. */
+    lifecycle: "active" | "terminal" | "reaped";
+    /**
+     * Records when an operator archived this identity, or null while it is not archived.
+     *
+     * Archiving does not change the lifecycle: the identity stays resumable, and reattaching under the
+     * same session clears this.
+     */
+    archivedAt: number | null;
+    /**
+     * Reports whether the recorded workspace path still resolves on the broker's machine.
+     *
+     * Presentation-only, like the rest of repository grouping: a removed workspace archives its
+     * agents in the operator view without changing broker lifecycle, routing, or addressability.
+     */
+    workspaceAvailable: boolean;
+    /** Preserves identities that control broker routing and authorization. */
+    brokerIdentity: {
+        /** Identifies the broker team. */
+        teamId: string;
+        /** Identifies the broker workspace. */
+        workspaceId: string;
+    };
+    /** Supplies presentation grouping separately from broker authority. */
+    repository: {
+        /** Identifies the operator repository projection. */
+        repositoryId: string;
+        /** Supplies worktree detail without adding another grouping level. */
+        worktree: OperatorWorktree;
+    };
+    /** Reports the selected adapter state exhaustively. */
+    adapter: OperatorAdapterState;
+    /** Carries open provider identity and public provider-owned metadata. */
+    implementation: OperatorImplementation;
+};
+/** Describes retained message content available to the operator. */
+export type OperatorMessageBody = {
+    /** Carries the message content. */
+    content: OperatorJsonValue;
+    /** Carries the exact observer-only representation used by raw-copy actions. */
+    rawCopy: string;
+    /** Records serialized content size. */
+    sizeBytes: number;
+    /** Identifies the retained content representation. */
+    contentType: string;
+};
+/** Describes one public delivery lifecycle observation. */
+export type OperatorDeliveryLifecycleEntry = {
+    /** Identifies this entry within the durable delivery audit. */
+    id: number;
+    /** Records when the observation occurred. */
+    at: number;
+    /** Names the broker-owned observation without constraining future providers. */
+    type: string;
+    /** Carries a delivery state only when the observation established one. */
+    state: MessageState | null;
+};
+/** Describes one accepted delivery and its globally ordered traffic position. */
+export type OperatorAcceptedDelivery = {
+    /** Distinguishes an accepted delivery from a control audit. */
+    kind: "accepted_delivery";
+    /** Selects this member unambiguously across the complete traffic union. */
+    trafficId: string;
+    /** Identifies the durable message. */
+    messageId: string;
+    /** Orders this row across every traffic kind. */
+    trafficPosition: number;
+    /** Orders all accepted traffic across both agent directions. */
+    acceptedSequence: number;
+    /** Identifies the sending agent. */
+    fromAgentId: AgentId;
+    /** Identifies the resolved recipient agent. */
+    toAgentId: AgentId;
+    /** Preserves the broker team that authorized the delivery. */
+    teamId: string;
+    /** Preserves the broker workspace that scoped the delivery. */
+    workspaceId: string;
+    /** Records durable message acceptance time. */
+    acceptedAt: number;
+    /** Carries the one-line subject the sender supplied with the message. */
+    subject: string;
+    /** Carries the sender-supplied message type. */
+    type: string;
+    /** Reports every reachable durable delivery state. */
+    state: MessageState;
+    /** Carries public content availability. */
+    body: OperatorMessageBody;
+    /** Lists ordered public lifecycle observations. */
+    lifecycle: OperatorDeliveryLifecycleEntry[];
+};
+/** Describes durable acceptance of an operator ping command without claiming delivery. */
+export type OperatorPingAudit = {
+    /** Distinguishes a control audit from peer traffic. */
+    kind: "ping_audit";
+    /** Selects this member unambiguously across the complete traffic union. */
+    trafficId: string;
+    /** Identifies the durable audit row. */
+    auditId: string;
+    /** Orders this row across every traffic kind. */
+    trafficPosition: number;
+    /** Correlates the accepted command with its body-free wake. */
+    controlId: string;
+    /** Identifies the requested target. */
+    targetAgentId: AgentId;
+    /** Identifies the class of actor that requested the control wake. */
+    actor: "operator";
+    /** Records command acceptance time without implying wake delivery. */
+    acceptedAt: number;
+};
+/** One member per durable traffic kind. */
+export type OperatorTraffic = OperatorAcceptedDelivery | OperatorPingAudit;
+/** Represents a complete authoritative operator projection at one cursor. */
+export type OperatorSnapshot = {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies the broker generation that produced the snapshot. */
+    epoch: string;
+    /** Identifies the last event already reflected by this snapshot. */
+    cursor: OperatorCursor;
+    /** Records when the projection was generated. */
+    generatedAt: number;
+    /** Lists presentation-only repository projections. */
+    repositories: OperatorRepository[];
+    /** Lists projected agents. */
+    agents: OperatorAgent[];
+    /** Lists durable traffic and audit projections. */
+    traffic: OperatorTraffic[];
+};
+/** Represents an authoritative state change following an operator snapshot. */
+export type OperatorStateEvent = {
+    /** Identifies a repository replacement. */ type: "repository_upserted";
+    /** Carries its value. */ repository: OperatorRepository;
+} | {
+    /** Identifies a repository removal. */ type: "repository_removed";
+    /** Identifies its value. */ repositoryId: string;
+} | {
+    type: "agent_upserted"; /** Carries its value. */
+    agent: OperatorAgent;
+} | {
+    type: "agent_removed"; /** Identifies its value. */
+    agentId: AgentId;
+} | {
+    /** Identifies a traffic replacement. */ type: "traffic_upserted";
+    /** Carries its value. */ traffic: OperatorTraffic;
+} | {
+    type: "traffic_removed"; /** Identifies its value. */
+    trafficId: string;
+};
+/** Carries one ordered authoritative state event. */
+export type OperatorEventEnvelope = {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies the broker generation that emitted the event. */
+    epoch: string;
+    /** Orders this event monotonically within its epoch. */
+    sequence: number;
+    /** Carries the authoritative state observation. */
+    event: OperatorStateEvent;
+};
+/** Represents an operator request without treating it as authoritative state. */
+export type OperatorCommand = {
+    /** Requests a body-free control wake for one agent. */
+    type: "ping_agent";
+    /** Identifies the target using broker identity, not repository projection. */
+    targetAgentId: AgentId;
+} | {
+    /** Requests expiry of one accepted delivery. */
+    type: "expire_message";
+    /** Identifies the broker message to expire. */
+    messageId: string;
+} | {
+    /** Requests that one agent identity be retired into its repository's archive. */
+    type: "archive_agent";
+    /** Identifies the target using broker identity, not repository projection. */
+    targetAgentId: AgentId;
+};
+/** Carries one versioned operator command request. */
+export type OperatorCommandEnvelope = {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Correlates command admission independently from state events. */
+    commandId: string;
+    /** Records when the operator submitted the command. */
+    issuedAt: number;
+    /** Carries the requested operation without presentation authority. */
+    command: OperatorCommand;
+};
+/**
+ * Names every stable category a command rejection can carry.
+ *
+ * Closed at the wire, so a rejection reason a peer cannot interpret is a validation failure rather
+ * than an opaque string the operator is shown verbatim.
+ */
+export declare const OPERATOR_REJECTION_REASONS: readonly ["command_id_conflict", "target_unavailable", "conflict", "rejected", "wake_budget", "duplicate_control_id", "pending_control_limit", "admission_in_progress", "internal_error"];
+/** Supplies the stable public category a rejected command reports. */
+export type OperatorRejectionReason = (typeof OPERATOR_REJECTION_REASONS)[number];
+/** Reports command admission separately from authoritative state changes. */
+export type OperatorCommandResult = {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies ping command acceptance. */
+    type: "ping_accepted";
+    /** Reports that the broker accepted the command request. */
+    status: "accepted";
+    /** Correlates the result with the submitted command. */
+    commandId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+    /** Correlates the durable ping audit and body-free wake. */
+    controlId: string;
+} | {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies message-expiry command acceptance. */
+    type: "expiry_accepted";
+    /** Reports that the broker accepted the command request. */
+    status: "accepted";
+    /** Correlates the result with the submitted command. */
+    commandId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+} | {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies agent-archive command acceptance. */
+    type: "archive_accepted";
+    /** Reports that the broker accepted the command request. */
+    status: "accepted";
+    /** Correlates the result with the submitted command. */
+    commandId: string;
+    /** Records broker acceptance time. */
+    acceptedAt: number;
+} | {
+    /** Identifies the operator wire contract. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies command rejection before authoritative state changes. */
+    type: "command_rejected";
+    /** Reports that the broker rejected command admission. */
+    status: "rejected";
+    /** Correlates the result with the submitted command. */
+    commandId: string;
+    /** Supplies the stable public rejection category. */
+    reason: OperatorRejectionReason;
+};
+/** Narrows one validated command envelope to the selected command member. */
+export type OperatorCommandEnvelopeFor<Type extends OperatorCommand["type"]> = Omit<OperatorCommandEnvelope, "command"> & {
+    /** Carries the command member selected by its discriminant. */
+    command: Extract<OperatorCommand, {
+        type: Type;
+    }>;
+};
+/** Correlates a validated result with the only command kind it can answer. */
+export type OperatorCorrelatedCommandResult = {
+    /** Carries the originating ping request. */
+    command: OperatorCommandEnvelopeFor<"ping_agent">;
+    /** Carries ping acceptance or a command-agnostic rejection. */
+    result: Extract<OperatorCommandResult, {
+        type: "ping_accepted" | "command_rejected";
+    }>;
+} | {
+    /** Carries the originating expiry request. */
+    command: OperatorCommandEnvelopeFor<"expire_message">;
+    /** Carries expiry acceptance or a command-agnostic rejection. */
+    result: Extract<OperatorCommandResult, {
+        type: "expiry_accepted" | "command_rejected";
+    }>;
+} | {
+    /** Carries the originating archive request. */
+    command: OperatorCommandEnvelopeFor<"archive_agent">;
+    /** Carries archive acceptance or a command-agnostic rejection. */
+    result: Extract<OperatorCommandResult, {
+        type: "archive_accepted" | "command_rejected";
+    }>;
+};
+/** Classifies one event relative to a consumer cursor without conflating recovery actions. */
+export type OperatorCursorResult = {
+    /** Permits applying the next event. */ type: "apply";
+    /** Carries the validated event. */ event: OperatorEventEnvelope;
+    /** Supplies the next cursor. */ cursor: OperatorCursor;
+} | {
+    /** Reports an event already incorporated. */ type: "duplicate";
+    /** Records the duplicate position. */ sequence: number;
+} | {
+    /** Reports a missing position before this event. */ type: "gap";
+    /** Records the required next position. */ expectedSequence: number;
+    /** Records the received position. */ receivedSequence: number;
+} | {
+    /** Reports an event from another broker generation. */ type: "stale_epoch";
+    /** Identifies the current generation. */ currentEpoch: string;
+    /** Identifies the received generation. */ receivedEpoch: string;
+} | {
+    /** Reports an unsupported event contract. */ type: "incompatible_version";
+    /** Identifies the supported contract. */ supportedVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Records the received version. */ receivedVersion: number;
+};
+/** Carries one client-to-server request on the operator transport. */
+export type OperatorTransportRequest = {
+    /** Identifies a subscription request. */ type: "subscribe";
+    /** Identifies the operator wire contract requested by the client. */ protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Resumes strictly after this position, or requests a fresh snapshot when absent. */ cursor?: OperatorCursor;
+} | {
+    /** Identifies a liveness acknowledgement. */ type: "ack";
+    /** Identifies the operator wire contract used by the client. */ protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Reports the latest server position observed by the client. */ cursor: OperatorCursor;
+} | {
+    /** Identifies a non-authoritative operator command request. */ type: "command";
+    /** Identifies the operator wire contract used by the client. */ protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Carries one validated command envelope. */ command: OperatorCommandEnvelope;
+};
+/** Explains why a client must replace rather than incrementally advance local state. */
+export type OperatorResyncReason = "cursor_gap" | "epoch_changed" | "stream_unavailable";
+/** Bounds the public text carried by one diagnostic field. */
+export declare const OPERATOR_DIAGNOSTIC_TEXT_LIMIT = 160;
+/** Classifies how much attention one diagnostic asks of an operator. */
+export type OperatorDiagnosticSeverity = "info" | "warning" | "error";
+/**
+ * Reports one operator-visible condition without carrying message or identity content.
+ *
+ * Diagnostics explain why the surface looks as it does. They never carry a body or an alias.
+ */
+export type OperatorDiagnostic = {
+    /** Records when the condition was observed. */
+    at: number;
+    /** Distinguishes a condition the broker reported from one the client observed itself. */
+    origin: "broker" | "client";
+    /** Classifies the attention the condition asks for. */
+    severity: OperatorDiagnosticSeverity;
+    /** Names the subsystem the condition arose in. */
+    scope: string;
+    /** States the condition in operator-facing language. */
+    summary: string;
+};
+/** Carries one bounded server-to-client operator transport frame. */
+export type OperatorTransportFrame = {
+    /** Begins an authoritative snapshot transfer. */ type: "snapshot_begin";
+    /** Identifies the operator wire contract used by the transfer. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Distinguishes cold hydration from required state replacement. */ mode: "initial" | "replacement";
+    /** Identifies the position reflected by the transferred snapshot. */ cursor: OperatorCursor;
+    /** Identifies the byte-to-text encoding used by ordered chunks. */ encoding: "base64";
+    /** Records the UTF-8 JSON byte count before base64 encoding. */ totalBytes: number;
+    /** Records the exact number of ordered chunk frames that follow. */ chunkCount: number;
+} | {
+    /** Carries one ordered section of an active snapshot transfer. */ type: "snapshot_chunk";
+    /** Identifies the operator wire contract used by the transfer. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Identifies this zero-based chunk position. */ index: number;
+    /** Carries base64-encoded raw snapshot bytes. */ data: string;
+} | {
+    /** Completes an authoritative snapshot transfer. */ type: "snapshot_end";
+    /** Identifies the operator wire contract used by the transfer. */
+    protocolVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Repeats the transferred snapshot position for atomic validation. */ cursor: OperatorCursor;
+    /** Repeats the raw byte count for atomic validation. */ totalBytes: number;
+    /** Repeats the ordered chunk count for atomic validation. */ chunkCount: number;
+} | {
+    /** Carries one strictly ordered authoritative change. */ type: "event";
+    /** Supplies the durable event envelope. */ envelope: OperatorEventEnvelope;
+} | {
+    /** Requires replacement before any further event can be applied. */ type: "resync_required";
+    /** Identifies the recovery condition without advancing the client cursor. */ reason: OperatorResyncReason;
+} | {
+    /** Reports that the requested wire contract cannot be served. */ type: "incompatible_version";
+    /** Identifies the only contract supported by this server. */ supportedVersion: typeof OPERATOR_PROTOCOL_VERSION;
+    /** Records the client-requested contract. */ receivedVersion: number;
+} | {
+    /** Reports one operator-visible condition alongside the authoritative stream. */ type: "diagnostic";
+    /** Carries the content-free diagnostic. */ diagnostic: OperatorDiagnostic;
+} | {
+    /** Requests a bounded client liveness acknowledgement. */ type: "heartbeat";
+    /** Supplies the latest durable position known to the server. */ cursor: OperatorCursor;
+    /** Records when the server emitted this liveness probe. */ sentAt: number;
+} | {
+    /** Carries one correlated non-authoritative command outcome. */ type: "command_result";
+    /** Carries the validated command result. */ result: OperatorCommandResult;
+};

package/dist/src/operator/protocol.js

@@ -0,0 +1,49 @@
+/**
+ * Identifies the operator wire contract implemented by this process.
+ *
+ * Every envelope that carries this number is rejected outright when it does not match exactly, so a
+ * bump locks out every differently-versioned peer at that boundary immediately. Bump only for a
+ * breaking change: one where a peer on the other version would misinterpret data it receives, or
+ * must reject data the other version considers valid.
+ *
+ * Every operator shape is closed by `exactFields` (`src/shared/guards.ts`): it rejects any key outside
+ * its permitted set. That makes adding a field to a validated shape breaking in one direction no matter
+ * how absence is handled — a consumer built before the field existed rejects a producer's row that now
+ * carries it, with "unexpected field". Nothing below excuses that direction; it is a real, if narrow,
+ * cost of adding a field, accepted here rather than bumped, because bumping would not remove that one
+ * record-shaped rejection — it would only replace it with an earlier, wholesale "incompatible_version"
+ * that blocks every exchange between the two peers, including ones neither side's change affects.
+ *
+ * The other direction — a consumer built after the field existed, reading a producer that never sent
+ * it — is safe without a bump, and is the direction the additive-field exception actually covers: adding
+ * an optional field is not a breaking change on its own, provided every validator treats the field's
+ * absence identically to an explicit wire-level absence marker (`null`, where the field allows one). An
+ * older producer's row that never had the key and a newer producer's row that sends it absent must
+ * validate identically.
+ */
+export const OPERATOR_PROTOCOL_VERSION = 2;
+/** Bounds the UTF-8 JSON payload carried by one snapshot transfer. */
+export const OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES = 512 * 1_024 * 1_024;
+/** Selects the raw byte count encoded by every non-final snapshot chunk. */
+export const OPERATOR_SNAPSHOT_CHUNK_BYTES = 48 * 1_024;
+/** Bounds every newline-delimited server frame after JSON encoding. */
+export const OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES = 128 * 1_024;
+/**
+ * Names every stable category a command rejection can carry.
+ *
+ * Closed at the wire, so a rejection reason a peer cannot interpret is a validation failure rather
+ * than an opaque string the operator is shown verbatim.
+ */
+export const OPERATOR_REJECTION_REASONS = [
+    "command_id_conflict",
+    "target_unavailable",
+    "conflict",
+    "rejected",
+    "wake_budget",
+    "duplicate_control_id",
+    "pending_control_limit",
+    "admission_in_progress",
+    "internal_error",
+];
+/** Bounds the public text carried by one diagnostic field. */
+export const OPERATOR_DIAGNOSTIC_TEXT_LIMIT = 160;

package/dist/src/operator/repository-system.d.ts

@@ -0,0 +1,14 @@
+import { type RepositoryProjectionDependencies } from "./repository.js";
+/** Bounds each Git command's complete captured output. */
+export declare const REPOSITORY_GIT_OUTPUT_LIMIT = 65536;
+/** Configures the concrete Git process boundary. */
+export type SystemRepositoryProjectionOptions = {
+    /** Selects the Git executable without mutating process PATH. */
+    gitExecutable?: string;
+};
+/**
+ * Compose production filesystem and Git discovery adapters.
+ * @param options - Optional executable override for isolated verification.
+ * @returns Dependencies whose process execution is isolated from pure projection logic.
+ */
+export declare function createSystemRepositoryProjectionDependencies(options?: SystemRepositoryProjectionOptions): RepositoryProjectionDependencies;