@haywoodmarx/agent-pager 0.1.0

package/dist/src/operator/repository-system.js

@@ -0,0 +1,150 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { RepositoryDiscoveryError } from "./repository.js";
+/** Bounds each Git command's complete captured output. */
+export const REPOSITORY_GIT_OUTPUT_LIMIT = 65_536;
+/**
+ * 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 function createSystemRepositoryProjectionDependencies(options = {}) {
+    const gitExecutable = options.gitExecutable ?? "git";
+    return {
+        fileSystem: {
+            canonicalPath: (path) => realpathSync(path),
+            exists: (path) => existsSync(path),
+        },
+        git: {
+            inspect: (workspacePath) => {
+                const topLevel = runGit(gitExecutable, ["-C", workspacePath, "rev-parse", "--show-toplevel"], true);
+                if (topLevel.kind === "not_git")
+                    return topLevel;
+                const worktreeRoot = parseSingleAbsolutePath(topLevel.stdout, "Git top-level output is invalid");
+                const topology = runGit(gitExecutable, ["-C", workspacePath, "worktree", "list", "--porcelain", "-z"], false);
+                if (topology.kind === "not_git")
+                    throw new RepositoryDiscoveryError("invalid", "Git topology disappeared");
+                const repositoryRoot = parsePrimaryWorktree(topology.stdout, worktreeRoot);
+                return { kind: "git", repositoryRoot, worktreeRoot };
+            },
+        },
+    };
+}
+function runGit(executable, args, allowNotGit) {
+    const result = spawnSync(executable, args, {
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        maxBuffer: REPOSITORY_GIT_OUTPUT_LIMIT,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error) {
+        const code = "code" in result.error ? result.error.code : undefined;
+        if (code === "ENOBUFS")
+            throw new RepositoryDiscoveryError("output_limit", "Git discovery output exceeded its limit");
+        throw new RepositoryDiscoveryError("unavailable", "Git discovery process is unavailable");
+    }
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr : "";
+    if (Buffer.byteLength(stdout) > REPOSITORY_GIT_OUTPUT_LIMIT ||
+        Buffer.byteLength(stderr) > REPOSITORY_GIT_OUTPUT_LIMIT) {
+        throw new RepositoryDiscoveryError("output_limit", "Git discovery output exceeded its limit");
+    }
+    if (result.signal !== null)
+        throw new RepositoryDiscoveryError("unavailable", "Git discovery process was interrupted");
+    if (result.status !== 0) {
+        if (allowNotGit && result.status === 128 && /not a git repository/u.test(stderr))
+            return { kind: "not_git" };
+        throw new RepositoryDiscoveryError("unavailable", "Git discovery command failed");
+    }
+    return { kind: "ok", stdout };
+}
+function parseSingleAbsolutePath(output, message) {
+    const normalized = output.endsWith("\n") ? output.slice(0, -1) : output;
+    if (!normalized || normalized.includes("\n") || normalized.includes("\r") || !isAbsolute(normalized)) {
+        throw new RepositoryDiscoveryError("invalid", message);
+    }
+    return normalized;
+}
+function parsePrimaryWorktree(output, currentWorktree) {
+    if (!output.endsWith("\0\0"))
+        throw new RepositoryDiscoveryError("invalid", "Git topology output is truncated");
+    const tokens = output.split("\0");
+    tokens.pop();
+    const records = [];
+    let record = [];
+    for (const token of tokens) {
+        if (token === "") {
+            if (record.length === 0)
+                throw new RepositoryDiscoveryError("invalid", "Git topology contains an empty record");
+            records.push(record);
+            record = [];
+            continue;
+        }
+        if (Buffer.byteLength(token) > REPOSITORY_GIT_OUTPUT_LIMIT / 2) {
+            throw new RepositoryDiscoveryError("output_limit", "Git topology field exceeded its limit");
+        }
+        record.push(token);
+    }
+    if (record.length > 0 || records.length === 0) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology record is incomplete");
+    }
+    const topology = records.map(validateWorktreeRecord);
+    const worktrees = new Set();
+    for (const [index, entry] of topology.entries()) {
+        if (worktrees.has(entry.path)) {
+            throw new RepositoryDiscoveryError("invalid", "Git topology contains a duplicate worktree");
+        }
+        worktrees.add(entry.path);
+        if (entry.bare && index !== 0) {
+            throw new RepositoryDiscoveryError("invalid", "Only the primary Git topology record may be bare");
+        }
+    }
+    if (!worktrees.has(currentWorktree)) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology omitted the current worktree");
+    }
+    const primary = topology[0]?.path;
+    if (!primary)
+        throw new RepositoryDiscoveryError("invalid", "Git topology omitted its primary worktree");
+    return primary;
+}
+function validateWorktreeRecord(fields) {
+    const first = fields[0];
+    if (!first?.startsWith("worktree ")) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology record does not start with a worktree");
+    }
+    const worktree = first.slice("worktree ".length);
+    if (!worktree || !isAbsolute(worktree)) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology worktree path is invalid");
+    }
+    if (fields[1] === "bare") {
+        if (fields.length !== 2)
+            throw new RepositoryDiscoveryError("invalid", "Bare Git topology record is invalid");
+        return { path: worktree, bare: true };
+    }
+    if (!/^HEAD [0-9a-f]{40}(?:[0-9a-f]{24})?$/u.test(fields[1] ?? "")) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology HEAD field is invalid");
+    }
+    if (!(fields[2]?.startsWith("branch refs/") || fields[2] === "detached")) {
+        throw new RepositoryDiscoveryError("invalid", "Git topology branch field is invalid");
+    }
+    let locked = false;
+    let prunable = false;
+    for (const field of fields.slice(3)) {
+        if (field === "locked" || field.startsWith("locked ")) {
+            if (locked || prunable) {
+                throw new RepositoryDiscoveryError("invalid", "Git topology locked field is duplicated or misplaced");
+            }
+            locked = true;
+            continue;
+        }
+        if (field === "prunable" || field.startsWith("prunable ")) {
+            if (prunable)
+                throw new RepositoryDiscoveryError("invalid", "Git topology prunable field is duplicated");
+            prunable = true;
+            continue;
+        }
+        throw new RepositoryDiscoveryError("invalid", "Git topology contains an unknown field");
+    }
+    return { path: worktree, bare: false };
+}

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

@@ -0,0 +1,79 @@
+import type { OperatorRepository, OperatorWorktree } from "./protocol.js";
+/** Describes Git repository and worktree roots without performing discovery itself. */
+export type RepositoryGitLocation = {
+    /** Supplies the root of the primary repository worktree. */
+    repositoryRoot: string;
+    /** Supplies the root of the worktree containing the inspected workspace. */
+    worktreeRoot: string;
+};
+/** Reports either confirmed Git topology or a confirmed non-Git workspace. */
+export type RepositoryGitInspection = ({
+    kind: "git";
+} & RepositoryGitLocation) | {
+    kind: "not_git";
+};
+/** Canonicalizes filesystem paths for stable presentation grouping. */
+export interface RepositoryFileSystemPort {
+    /**
+     * Resolve aliases and symbolic links in one existing path.
+     * @param path - Absolute workspace or Git root to canonicalize.
+     * @returns The canonical absolute filesystem path.
+     */
+    canonicalPath(path: string): string;
+    /**
+     * Report whether one recorded path still resolves on this machine.
+     * @param path - Absolute broker workspace path recorded when the agent registered.
+     * @returns True when the path resolves through any symbolic links, false when it has been removed, is a dangling link, or is unreachable.
+     */
+    exists(path: string): boolean;
+}
+/** Discovers Git topology without granting it broker routing authority. */
+export interface RepositoryGitPort {
+    /**
+     * Inspect one canonical workspace for Git repository topology.
+     * @param workspacePath - Canonical absolute workspace path.
+     * @returns Confirmed Git topology or a confirmed non-Git result.
+     */
+    inspect(workspacePath: string): RepositoryGitInspection;
+}
+/** Supplies filesystem and Git collaborators to repository projection. */
+export type RepositoryProjectionDependencies = {
+    /** Canonicalizes discovered paths. */
+    fileSystem: RepositoryFileSystemPort;
+    /** Reports Git repository topology. */
+    git: RepositoryGitPort;
+};
+/** Describes one workspace's presentation-only repository grouping. */
+export type ProjectedRepositoryLocation = {
+    /** Carries the shared repository identity and root, before a name unique across all repositories is known. */
+    repository: Omit<OperatorRepository, "name">;
+    /** Carries worktree detail for the inspected workspace. */
+    worktree: OperatorWorktree;
+    /** Reports whether the workspace path still resolves, which decides operator archive membership. */
+    available: boolean;
+};
+/** Reports invalid or unavailable repository projection inputs. */
+declare class RepositoryProjectionError extends Error {
+}
+/** Reports bounded repository discovery failure without retaining process output. */
+export declare class RepositoryDiscoveryError extends RepositoryProjectionError {
+    readonly code: "unavailable" | "invalid" | "output_limit";
+    /**
+     * Build one controlled discovery error.
+     * @param code - Stable failure class safe for callers and tests.
+     * @param message - Bounded diagnostic without child-process output.
+     */
+    constructor(code: "unavailable" | "invalid" | "output_limit", message: string);
+}
+/**
+ * Project one broker workspace into repository grouping and worktree detail.
+ *
+ * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * canonicalization nor Git discovery can run against a removed directory, and both throw rather
+ * than reporting absence, so the removal is detected before either is attempted.
+ * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param dependencies - Explicit filesystem and Git discovery collaborators.
+ * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ */
+export declare function projectRepositoryLocation(workspacePath: string, dependencies: RepositoryProjectionDependencies): ProjectedRepositoryLocation;
+export {};

package/dist/src/operator/repository.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+/** Reports invalid or unavailable repository projection inputs. */
+class RepositoryProjectionError extends Error {
+}
+/** Reports bounded repository discovery failure without retaining process output. */
+export class RepositoryDiscoveryError extends RepositoryProjectionError {
+    code;
+    /**
+     * Build one controlled discovery error.
+     * @param code - Stable failure class safe for callers and tests.
+     * @param message - Bounded diagnostic without child-process output.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RepositoryDiscoveryError";
+    }
+}
+/**
+ * Project one broker workspace into repository grouping and worktree detail.
+ *
+ * A workspace whose path no longer resolves is projected from its recorded path alone. Neither
+ * canonicalization nor Git discovery can run against a removed directory, and both throw rather
+ * than reporting absence, so the removal is detected before either is attempted.
+ * @param workspacePath - Absolute broker workspace path to inspect.
+ * @param dependencies - Explicit filesystem and Git discovery collaborators.
+ * @returns Presentation-only repository and worktree values, and whether the workspace still resolves.
+ */
+export function projectRepositoryLocation(workspacePath, dependencies) {
+    if (!dependencies.fileSystem.exists(workspacePath)) {
+        if (!workspacePath.startsWith("/")) {
+            throw new RepositoryProjectionError("removed workspace must resolve to an absolute path");
+        }
+        return {
+            repository: { id: repositoryProjectionId(workspacePath), rootPath: workspacePath },
+            worktree: { kind: "repository_root", path: null },
+            available: false,
+        };
+    }
+    const canonicalWorkspace = canonicalAbsolutePath(workspacePath, dependencies.fileSystem, "workspace");
+    const gitLocation = dependencies.git.inspect(canonicalWorkspace);
+    if (gitLocation.kind === "not_git") {
+        return {
+            repository: { id: repositoryProjectionId(canonicalWorkspace), rootPath: canonicalWorkspace },
+            worktree: { kind: "repository_root", path: null },
+            available: true,
+        };
+    }
+    const repositoryRoot = canonicalAbsolutePath(gitLocation.repositoryRoot, dependencies.fileSystem, "repository root");
+    const worktreeRoot = canonicalAbsolutePath(gitLocation.worktreeRoot, dependencies.fileSystem, "worktree root");
+    return {
+        repository: { id: repositoryProjectionId(repositoryRoot), rootPath: repositoryRoot },
+        worktree: repositoryRoot === worktreeRoot
+            ? { kind: "repository_root", path: null }
+            : { kind: "worktree", path: worktreeRoot },
+        available: true,
+    };
+}
+/**
+ * Derive a stable presentation identity from a canonical repository root.
+ * @param repositoryRoot - Canonical absolute repository root.
+ * @returns A non-authoritative repository projection identity.
+ */
+function repositoryProjectionId(repositoryRoot) {
+    return `repository:${createHash("sha256").update(repositoryRoot).digest("hex").slice(0, 16)}`;
+}
+function canonicalAbsolutePath(path, fileSystem, label) {
+    const canonical = fileSystem.canonicalPath(path);
+    if (!canonical.startsWith("/"))
+        throw new RepositoryProjectionError(`${label} must resolve to an absolute path`);
+    return canonical;
+}

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

@@ -0,0 +1,19 @@
+import type { BrokerTrafficReadResult } from "../broker/broker.js";
+import { type OperatorDiagnosticSink } from "./diagnostics.js";
+import type { OperatorTraffic } from "./protocol.js";
+/** Supplies bounded durable records without giving the projection access to broker storage. */
+export interface OperatorTrafficSourcePort {
+    /**
+     * Read traffic records without claiming or consuming retained message bodies.
+     * @returns Durable source rows whose positions share one broker-owned sequence.
+     */
+    operatorTrafficRecords(): BrokerTrafficReadResult;
+}
+/**
+ * Project durable broker traffic into the validated renderer-neutral operator contract.
+ * @param source - Injected observer-only source of durable traffic rows.
+ * @param diagnostics - Sink receiving rows the projection could not admit.
+ * @param now - Clock stamping those reports.
+ * @returns Traffic sorted by the common durable position shared by every traffic kind.
+ */
+export declare function projectOperatorTraffic(source: OperatorTrafficSourcePort, diagnostics?: OperatorDiagnosticSink, now?: () => number): OperatorTraffic[];

package/dist/src/operator/traffic-projection.js

@@ -0,0 +1,229 @@
+import { decodeMessageBody, lifecycleEventState, MESSAGE_BODY_LIMIT_BYTES, } from "../broker/protocol.js";
+import { operatorDiagnostic, SILENT_OPERATOR_DIAGNOSTICS } from "./diagnostics.js";
+import { OPERATOR_ARRAY_LENGTH_LIMIT, OperatorValidationError, validateOperatorMessageBody, validateOperatorTraffic, } from "./validation.js";
+/** Reports invalid or inconsistent durable input without echoing body content. */
+class OperatorTrafficProjectionError extends Error {
+}
+/**
+ * Project durable broker traffic into the validated renderer-neutral operator contract.
+ * @param source - Injected observer-only source of durable traffic rows.
+ * @param diagnostics - Sink receiving rows the projection could not admit.
+ * @param now - Clock stamping those reports.
+ * @returns Traffic sorted by the common durable position shared by every traffic kind.
+ */
+export function projectOperatorTraffic(source, diagnostics = SILENT_OPERATOR_DIAGNOSTICS, now = Date.now) {
+    const read = source.operatorTrafficRecords();
+    const records = [...read.records];
+    const report = (line) => {
+        diagnostics.report(operatorDiagnostic("broker", "warning", "traffic projection", line, now()));
+    };
+    for (const line of describeSkips(read.skips))
+        report(line);
+    if (records.length > OPERATOR_ARRAY_LENGTH_LIMIT) {
+        throw new OperatorTrafficProjectionError("operator traffic source exceeds the bounded limit");
+    }
+    const unpositioned = records.filter((record) => !Number.isSafeInteger(record.trafficPosition) || record.trafficPosition < 1);
+    const positioned = records.filter((record) => !unpositioned.includes(record));
+    const [firstUnpositioned] = unpositioned;
+    if (firstUnpositioned !== undefined) {
+        const detail = `${describeRecord(firstUnpositioned)} skipped: durable position ${String(firstUnpositioned.trafficPosition)} is not a position`;
+        report(unpositioned.length === 1 ? detail : `${String(unpositioned.length)} records skipped; first: ${detail}`);
+    }
+    positioned.sort((left, right) => left.trafficPosition - right.trafficPosition);
+    // Every claimant of a colliding position is dropped; neither table's uniqueness spans both.
+    const claimed = new Set();
+    const colliding = new Set();
+    for (const record of positioned) {
+        if (claimed.has(record.trafficPosition))
+            colliding.add(record.trafficPosition);
+        claimed.add(record.trafficPosition);
+    }
+    const [firstCollision] = colliding;
+    if (firstCollision !== undefined) {
+        report(colliding.size === 1
+            ? `durable position ${String(firstCollision)} is claimed by more than one row: every claimant skipped`
+            : `${String(colliding.size)} durable positions are claimed by more than one row: every claimant skipped; first: position ${String(firstCollision)}`);
+    }
+    const traffic = [];
+    // Positions carrying a lifecycle entry that validation dropped for naming a type outside the
+    // closed vocabulary (see validateLifecycleEntry), keyed by that type name. Reported once per run
+    // rather than once per record.
+    const unrecognizedLifecycleTypes = new Map();
+    for (const record of positioned) {
+        if (colliding.has(record.trafficPosition))
+            continue;
+        let projected;
+        try {
+            projected = projectRecord(record);
+        }
+        catch (error) {
+            diagnostics.report(operatorDiagnostic("broker", "warning", "traffic projection", `position ${String(record.trafficPosition)} skipped: ${error instanceof Error ? error.message : "unknown projection failure"}`, now()));
+            continue;
+        }
+        traffic.push(projected);
+        // A record that failed outright already reported why above, so only one that projected cleanly
+        // is credited to the unrecognized-type diagnostic.
+        if (record.kind === "accepted_delivery" && projected.kind === "accepted_delivery") {
+            for (const entry of record.lifecycle) {
+                if (lifecycleEventState(entry.type) !== undefined)
+                    continue;
+                const positionsForType = unrecognizedLifecycleTypes.get(entry.type) ?? new Set();
+                positionsForType.add(record.trafficPosition);
+                unrecognizedLifecycleTypes.set(entry.type, positionsForType);
+            }
+        }
+    }
+    if (unrecognizedLifecycleTypes.size > 0) {
+        diagnostics.report(operatorDiagnostic("broker", "warning", "traffic projection", describeUnrecognizedLifecycleTypes(unrecognizedLifecycleTypes), now()));
+    }
+    return traffic;
+}
+/**
+ * Describe every unrecognized lifecycle type dropped in one projection run.
+ *
+ * One line names each distinct rejected value and how many records it touched, rather than one
+ * line per affected record.
+ * @param unrecognizedLifecycleTypes - Rejected type name to the durable positions carrying it.
+ * @returns - Single diagnostic line naming the field path, each rejected value, and its record count.
+ */
+function describeUnrecognizedLifecycleTypes(unrecognizedLifecycleTypes) {
+    const perType = [...unrecognizedLifecycleTypes.entries()].map(([type, affectedPositions]) => {
+        const count = affectedPositions.size;
+        return `${JSON.stringify(type)} (${String(count)} record${count === 1 ? "" : "s"}: position${count === 1 ? "" : "s"} ${[...affectedPositions].sort((left, right) => left - right).join(", ")})`;
+    });
+    return `traffic.lifecycle.type: unrecognized value ${perType.join("; ")} — entry dropped, delivery retained`;
+}
+/**
+ * Word the skips one traffic read reported: one line per kind of skipped row, and one per truncated
+ * table, rather than one per row.
+ *
+ * Each line is a frame on the live operator channel, whose queue a read naming thousands of rows
+ * would overrun.
+ * @param skips - Skips the read handed back beside its records.
+ * @returns - Diagnostic lines for the operator's log: one per skip kind, and one per truncated table.
+ */
+function describeSkips(skips) {
+    const messages = skips.flatMap((skip) => (skip.type === "traffic_row_skipped" ? [skip] : []));
+    const pings = skips.flatMap((skip) => (skip.type === "ping_row_skipped" ? [skip] : []));
+    const lines = [
+        describeRowSkips("message", messages.map((skip) => ({ id: skip.messageId, unreadable: skip.unreadable }))),
+        describeRowSkips("ping audit", pings.map((skip) => ({ id: skip.auditId, unreadable: skip.unreadable }))),
+    ].filter((line) => line !== null);
+    for (const skip of skips) {
+        if (skip.type === "skips_truncated") {
+            lines.push(`${skip.table}: ${String(skip.total)} rows hold a durable position this build cannot order; ${String(skip.named)} named`);
+        }
+    }
+    return lines;
+}
+/**
+ * Word every skipped row of one kind as a single line.
+ *
+ * Names the first row and counts them all: a diagnostic summary is clamped, and a second identifier
+ * would be cut off.
+ * @param noun - What each row is, singular.
+ * @param rows - The skipped rows, each with the columns that could not be read.
+ * @returns - One line naming the row, or counting them and naming the first; null for none.
+ */
+function describeRowSkips(noun, rows) {
+    const [first] = rows;
+    if (first === undefined)
+        return null;
+    const detail = `${first.id} skipped: stored columns could not be read: ${first.unreadable.join(", ")}`;
+    return rows.length === 1 ? `${noun} ${detail}` : `${String(rows.length)} ${noun}s skipped; first: ${noun} ${detail}`;
+}
+/**
+ * Name one durable record for a diagnostic, by whichever identity its kind carries.
+ * @param record - Durable record being reported on.
+ * @returns - Identity phrase for the diagnostic line.
+ */
+function describeRecord(record) {
+    return record.kind === "accepted_delivery" ? `message ${record.messageId}` : `ping audit ${record.auditId}`;
+}
+function projectRecord(record) {
+    switch (record.kind) {
+        case "accepted_delivery":
+            return validateProjectedTraffic({
+                kind: "accepted_delivery",
+                trafficId: record.messageId,
+                messageId: record.messageId,
+                trafficPosition: record.trafficPosition,
+                acceptedSequence: record.trafficPosition,
+                fromAgentId: record.senderAgentId,
+                toAgentId: record.recipientAgentId,
+                teamId: record.teamId,
+                workspaceId: record.workspaceId,
+                acceptedAt: record.acceptedAt,
+                subject: record.subject,
+                type: record.type,
+                state: record.state,
+                body: projectBody(record),
+                lifecycle: record.lifecycle.map((entry) => ({
+                    ...entry,
+                    state: lifecycleState(entry.type),
+                })),
+            });
+        case "ping_audit":
+            return validateProjectedTraffic({
+                kind: "ping_audit",
+                trafficId: record.auditId,
+                auditId: record.auditId,
+                trafficPosition: record.trafficPosition,
+                controlId: record.controlId,
+                targetAgentId: record.targetAgentId,
+                actor: record.actor,
+                acceptedAt: record.acceptedAt,
+            });
+    }
+}
+function projectBody(record) {
+    const storedBytes = Buffer.byteLength(record.encodedBody, "utf8");
+    if (storedBytes !== record.bodySizeBytes || storedBytes > MESSAGE_BODY_LIMIT_BYTES) {
+        throw new OperatorTrafficProjectionError("retained traffic body metadata is inconsistent");
+    }
+    let decoded;
+    try {
+        decoded = decodeMessageBody(record.encodedBody);
+    }
+    catch {
+        throw new OperatorTrafficProjectionError("retained traffic body is not valid JSON");
+    }
+    const expectedContentType = typeof decoded === "string" ? "text" : "json";
+    if (record.contentType !== expectedContentType) {
+        throw new OperatorTrafficProjectionError("retained traffic content type is inconsistent");
+    }
+    return validateOperatorMessageBody(retainedBody(decoded, record.contentType));
+}
+function retainedBody(content, contentType) {
+    const rawCopy = contentType === "text" && typeof content === "string" ? content : JSON.stringify(content);
+    if (typeof rawCopy !== "string") {
+        throw new OperatorTrafficProjectionError("retained traffic has no raw-copy representation");
+    }
+    return {
+        content,
+        rawCopy,
+        sizeBytes: Buffer.byteLength(rawCopy, "utf8"),
+        contentType,
+    };
+}
+function validateProjectedTraffic(value) {
+    try {
+        return validateOperatorTraffic(value);
+    }
+    catch (error) {
+        if (error instanceof OperatorValidationError) {
+            throw new OperatorTrafficProjectionError(`invalid durable traffic projection: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Read the state a durable lifecycle event type observes.
+ *
+ * A type outside the broker's known vocabulary is informational: it carries no state of its own.
+ * @param type - Durable lifecycle event type read back from storage.
+ * @returns - The state the type observes, or null when it is informational or unrecognized.
+ */
+function lifecycleState(type) {
+    return lifecycleEventState(type) ?? null;
+}

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

@@ -0,0 +1,87 @@
+import { type OperatorCommandEnvelope, type OperatorCommandResult, type OperatorCursor } from "./protocol.js";
+import type { OperatorOpenResult, OperatorPublication } from "./updates.js";
+/** Schedules recurring liveness checks without binding deterministic tests to process timers. */
+export interface OperatorTransportSchedulerPort {
+    /**
+     * Schedule one recurring callback.
+     * @param callback - Liveness work invoked at each interval.
+     * @param intervalMs - Positive interval in milliseconds.
+     * @returns A callback that cancels future invocations.
+     */
+    recurring(callback: () => void, intervalMs: number): () => void;
+}
+/** Supplies explicit loopback, time, identity, and liveness policy. */
+export type OperatorTransportOptions = {
+    /** Selects an interface that runtime validation restricts to numeric loopback. */ host: string;
+    /** Selects a port, with zero requesting an operating-system-assigned port. */ port: number;
+    /** Supplies transport-observation timestamps. */ now: () => number;
+    /** Issues public-safe opaque client diagnostic identities. */ issueClientId: () => string;
+    /** Owns recurring liveness scheduling. */ scheduler: OperatorTransportSchedulerPort;
+    /** Selects heartbeat cadence in milliseconds. */ heartbeatIntervalMs: number;
+    /** Selects the maximum interval without a valid acknowledgement. */ livenessTimeoutMs: number;
+    /** Selects the maximum interval before an initial subscription. Defaults to the liveness timeout. */
+    handshakeTimeoutMs?: number;
+    /** Bounds active accepted connections. Defaults to a finite production limit. */ maxConnections?: number;
+    /** Bounds distinct in-flight snapshot versions while allowing byte sharing between clients. */
+    maxSnapshotTransfers?: number;
+    /** Executes validated non-authoritative operator commands. */ commands: OperatorTransportCommandPort;
+};
+/** Supplies operator command admission without granting the transport presentation authority. */
+export interface OperatorTransportCommandPort {
+    /**
+     * Execute one validated command.
+     * @param command - Command envelope received from the loopback client.
+     * @returns Correlated command admission outcome.
+     */
+    execute(command: OperatorCommandEnvelope): OperatorCommandResult;
+}
+/** Reports bounded transport observations without addresses, payloads, or thrown values. */
+export type OperatorTransportDiagnostic = {
+    /** Identifies the observed transport boundary. */
+    type: "connected" | "connection_rejected" | "subscribed" | "resync_required" | "incompatible_version" | "malformed_request" | "heartbeat_sent" | "liveness_acknowledged" | "handshake_timeout" | "liveness_timeout" | "slow_consumer" | "stream_unavailable" | "disconnected";
+    /** Identifies one connection without retaining its network address. */ clientId: string;
+    /** Records when the boundary was observed. */ at: number;
+};
+/** Owns the bound loopback endpoint and deterministic liveness controls. */
+export type OperatorTransportHandle = {
+    /** Locates the newline-delimited TCP endpoint. */ url: string;
+    /**
+     * Return bounded transport observations.
+     * @returns Defensive diagnostic copies.
+     */
+    diagnostics(): OperatorTransportDiagnostic[];
+    /** Run one liveness pass without waiting for the scheduler. */
+    pulse(): void;
+    /** Stop accepting clients and close all active connections. */
+    close(): Promise<void>;
+};
+/** Supplies the authoritative update seam consumed by one transport instance. */
+export interface OperatorTransportUpdatePort {
+    /**
+     * Establish replay and subsequent publication for one connection.
+     * @param cursor - Last incorporated position, or null for cold hydration.
+     * @param subscriber - Consumer of subsequent ordered publications.
+     * @returns Initial hydration state and a deterministic detach callback.
+     */
+    open(cursor: OperatorCursor | null, subscriber: (publication: OperatorPublication) => void): {
+        result: OperatorOpenResult;
+        unsubscribe: () => void;
+    };
+    /**
+     * Return the latest authoritative position.
+     * @returns Cursor safe to report through liveness frames.
+     */
+    cursor(): OperatorCursor;
+}
+/**
+ * Start a loopback-only newline-delimited operator stream.
+ * @param updates - Authoritative snapshot, replay, and publication service.
+ * @param options - Explicit bind, clock, identity, scheduler, and liveness policy.
+ * @returns Bound transport handle.
+ */
+export declare function startOperatorTransport(updates: OperatorTransportUpdatePort, options: OperatorTransportOptions): Promise<OperatorTransportHandle>;
+/**
+ * Issue one bounded public-safe transport diagnostic identity.
+ * @returns An opaque identity that contains no network address or process binding.
+ */
+export declare function issueOperatorClientId(): string;