@stateforge-labs/herdr 0.0.0-stage → 0.3.0

package/dist/drift/schema.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaDocument, SchemaRead, SchemaSource, InventoryOf } from './types.js';
+export type SchemaNode = Readonly<Record<string, unknown>>;
+export declare function isNode(value: unknown): value is SchemaNode;
+export declare function isString(value: unknown): value is string;
+export declare function isNumber(value: unknown): value is number;
+export declare function namespaceOf(schema: SchemaDocument, name: string): SchemaNode;
+export declare function definitionsOf(namespace: SchemaNode): SchemaNode;
+export declare function definitionNamed(namespace: SchemaNode, name: string): SchemaNode;
+export declare function branchesOf(node: SchemaNode): readonly SchemaNode[];
+export declare function constOf(node: SchemaNode, property: string): string;
+export declare function stableText(value: unknown): string;
+export declare function fieldShapesOf(schema: SchemaDocument): Record<string, string>;
+export type ReadText = (path: string) => string;
+export type RunHerdr = (args: readonly string[]) => string;
+export declare function committedSource(dir: string, readText: ReadText): SchemaSource;
+export declare function installedSource(runHerdr: RunHerdr): SchemaSource;
+export declare function parseSchemaText(text: string, herdrVersion: string): SchemaRead;
+export declare const inventoryOf: InventoryOf;
+export declare function unmappedMethods(methods: readonly string[]): string[];

package/dist/drift/schema.js

@@ -0,0 +1,190 @@
+// Role: reading a schema for drift: the committed and installed sources, the walk, the inventory and its stable text.
+// Informs HERDR-ADR-0009, HERDR-ADR-0008, plan 6, plan 4.2; merged by HERDR-ADR-0021 from schema-walk.ts, stable-text.ts, field-shapes.ts, schema-source.ts, inventory.ts, unmapped-methods.ts.
+import { JsType, SchemaField, SchemaKey, SchemaNamespace, HerdrCommand, ReasonText, SchemaFileName, SystemErrorCode, VERSION_PATTERN, VersionFileField, SchemaDefinition, TagProperty } from './constants.js';
+import { MalformedSchemaError } from '../herdr/errors.js';
+import { join } from 'node:path';
+import { SchemaReadKind } from '../constants.js';
+import { METHOD_RESULT } from '../herdr/generated/index.js';
+export function isNode(value) {
+    return typeof value === JsType.Object && value !== null;
+}
+// TypeScript narrows typeof only against a literal, so the scalar checks go through these guards.
+export function isString(value) {
+    return typeof value === JsType.String;
+}
+export function isNumber(value) {
+    return typeof value === JsType.Number;
+}
+export function namespaceOf(schema, name) {
+    const schemas = schema[SchemaField.Schemas];
+    const found = isNode(schemas) ? schemas[name] : undefined;
+    if (!isNode(found)) {
+        throw new MalformedSchemaError(`the schema carries no '${name}' namespace`);
+    }
+    return found;
+}
+export function definitionsOf(namespace) {
+    const defs = namespace[SchemaKey.Defs];
+    return isNode(defs) ? defs : {};
+}
+export function definitionNamed(namespace, name) {
+    const found = definitionsOf(namespace)[name];
+    if (!isNode(found)) {
+        throw new MalformedSchemaError(`the schema carries no '${name}' definition`);
+    }
+    return found;
+}
+export function branchesOf(node) {
+    const branches = node[SchemaKey.OneOf];
+    if (!Array.isArray(branches)) {
+        throw new MalformedSchemaError('a tagged union carries no oneOf branches');
+    }
+    return branches.filter(isNode);
+}
+export function constOf(node, property) {
+    const properties = node[SchemaKey.Properties];
+    const field = isNode(properties) ? properties[property] : undefined;
+    const value = isNode(field) ? field[SchemaKey.Const] : undefined;
+    if (!isString(value)) {
+        throw new MalformedSchemaError(`a branch carries no string const at '${property}'`);
+    }
+    return value;
+}
+// Keywords whose value maps names to schemas: their keys are names, so a name such as `description` is kept.
+const NAME_MAP_KEYWORDS = [SchemaKey.Properties, SchemaKey.Defs];
+export function stableText(value) {
+    return JSON.stringify(withSortedKeys(value));
+}
+function withSortedKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(withSortedKeys);
+    }
+    if (!isNode(value)) {
+        return value;
+    }
+    const keys = Object.keys(value).filter((key) => key !== SchemaKey.Description).toSorted();
+    return Object.fromEntries(keys.map((key) => [key, valueUnder(key, value[key])]));
+}
+// A child of a name map is a schema whose keys are names too; sorting keeps the same text for the same shape.
+function valueUnder(key, child) {
+    return NAME_MAP_KEYWORDS.includes(key) && isNode(child) ? namesOf(child) : withSortedKeys(child);
+}
+function namesOf(map) {
+    return Object.fromEntries(Object.keys(map).toSorted().map((name) => [name, withSortedKeys(map[name])]));
+}
+export function fieldShapesOf(schema) {
+    const shapes = {};
+    for (const bundle of [SchemaNamespace.Request, SchemaNamespace.SuccessResponse]) {
+        for (const [name, node] of Object.entries(definitionsOf(namespaceOf(schema, bundle)))) {
+            shapes[`${bundle}.${name}`] = stableText(node);
+        }
+    }
+    return shapes;
+}
+export function committedSource(dir, readText) {
+    return async () => {
+        let schemaText;
+        let versionText;
+        try {
+            schemaText = readText(join(dir, SchemaFileName.Schema));
+        }
+        catch (error) {
+            return readFailure(error, ReasonText.CommittedMissing, ReasonText.CommittedUnreadable);
+        }
+        try {
+            versionText = readText(join(dir, SchemaFileName.Version));
+        }
+        catch (error) {
+            return readFailure(error, ReasonText.VersionMissing, ReasonText.VersionFileUnreadable);
+        }
+        const version = committedVersionOf(versionText);
+        return version === null ? unreadable(ReasonText.VersionUnreadable) : parseSchemaText(schemaText, version);
+    };
+}
+export function installedSource(runHerdr) {
+    return async () => {
+        let schemaText;
+        let versionText;
+        try {
+            schemaText = runHerdr(HerdrCommand.SchemaJson);
+        }
+        catch (error) {
+            return readFailure(error, ReasonText.HerdrMissing, ReasonText.HerdrRefused);
+        }
+        try {
+            versionText = runHerdr(HerdrCommand.Version);
+        }
+        catch (error) {
+            return readFailure(error, ReasonText.HerdrMissing, ReasonText.HerdrVersionMissing);
+        }
+        const version = herdrVersionOf(versionText);
+        return version === null ? unreadable(ReasonText.HerdrVersionMissing) : parseSchemaText(schemaText, version);
+    };
+}
+// Reads schema JSON text; the herdr version comes from the caller. A schema without a protocol number is Unreadable.
+export function parseSchemaText(text, herdrVersion) {
+    const parsed = tryParse(text);
+    if (parsed === undefined) {
+        return unreadable(ReasonText.NotJson);
+    }
+    if (!isNode(parsed) || !isNumber(parsed[SchemaField.Protocol])) {
+        return unreadable(ReasonText.NoProtocol);
+    }
+    return { kind: SchemaReadKind.Found, schema: parsed, herdrVersion };
+}
+// A missing file or executable (code ENOENT) is NotFound; any other failure to read is Unreadable.
+function readFailure(error, missingReason, failedReason) {
+    const code = isNode(error) ? error.code : undefined;
+    return code === SystemErrorCode.NotFound ? notFound(missingReason) : unreadable(failedReason);
+}
+function committedVersionOf(text) {
+    const parsed = tryParse(text);
+    const version = isNode(parsed) ? parsed[VersionFileField.Version] : undefined;
+    return isString(version) ? version : null;
+}
+function herdrVersionOf(text) {
+    const match = VERSION_PATTERN.exec(text);
+    return match?.[0] ?? null;
+}
+// JSON.parse never yields undefined, so undefined marks a text that is not JSON.
+function tryParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function notFound(reason) {
+    return { kind: SchemaReadKind.NotFound, reason };
+}
+function unreadable(reason) {
+    return { kind: SchemaReadKind.Unreadable, reason };
+}
+export const inventoryOf = (schema, herdrVersion) => {
+    const request = namespaceOf(schema, SchemaNamespace.Request);
+    const success = namespaceOf(schema, SchemaNamespace.SuccessResponse);
+    const event = namespaceOf(schema, SchemaNamespace.Event);
+    return {
+        protocol: protocolOf(schema),
+        herdrVersion,
+        methods: tagsOf(branchesOf(request), TagProperty.Method),
+        resultTags: tagsOf(branchesOf(definitionNamed(success, SchemaDefinition.ResponseResult)), TagProperty.Type),
+        eventKinds: tagsOf(branchesOf(definitionNamed(event, SchemaDefinition.EventData)), TagProperty.Type),
+        subscriptionTypes: tagsOf(branchesOf(definitionNamed(request, SchemaDefinition.Subscription)), TagProperty.Type),
+        fieldShapes: fieldShapesOf(schema),
+    };
+};
+function protocolOf(schema) {
+    const protocol = schema[SchemaField.Protocol];
+    if (!isNumber(protocol)) {
+        throw new MalformedSchemaError('the schema carries no protocol number');
+    }
+    return protocol;
+}
+function tagsOf(branches, property) {
+    return branches.map((branch) => constOf(branch, property)).toSorted();
+}
+export function unmappedMethods(methods) {
+    return methods.filter((method) => !Object.hasOwn(METHOD_RESULT, method)).toSorted();
+}

package/dist/drift/types.d.ts

@@ -0,0 +1,76 @@
+import type { DriftExitCode, DriftOutcomeKind, SchemaReadKind } from '../constants.js';
+/** A schema as JSON (the committed schema/herdr-api.schema.json or `herdr api schema --json`). Never read from the socket (W4). */
+export type SchemaDocument = Readonly<Record<string, unknown>>;
+/** Everything drift compares, extracted from one schema plus its herdr version. */
+export interface SchemaInventory {
+    readonly protocol: number;
+    readonly herdrVersion: string;
+    readonly methods: readonly string[];
+    readonly resultTags: readonly string[];
+    readonly eventKinds: readonly string[];
+    readonly subscriptionTypes: readonly string[];
+    /** Field shape per params/result type, as a stable string (for "changed" detection). */
+    readonly fieldShapes: Readonly<Record<string, string>>;
+}
+/** Added and removed are listed separately (HERDR-ADR-0009). */
+export interface NameDiff {
+    readonly added: readonly string[];
+    readonly removed: readonly string[];
+}
+export interface DriftReport {
+    readonly protocol: {
+        readonly committed: number;
+        readonly installed: number;
+    };
+    readonly herdrVersion: {
+        readonly committed: string;
+        readonly installed: string;
+    };
+    readonly methods: NameDiff;
+    readonly resultTags: NameDiff;
+    readonly eventKinds: NameDiff;
+    readonly subscriptionTypes: NameDiff;
+    /** Type names whose field shape differs. */
+    readonly changedShapes: readonly string[];
+    /** Installed methods without a METHOD_RESULT row (plan 4.2). */
+    readonly unmappedMethods: readonly string[];
+    /** True when anything above differs. */
+    readonly drifted: boolean;
+}
+/** Builds the inventory of one schema. Implemented by drift/inventory.ts (P5c). */
+export type InventoryOf = (schema: SchemaDocument, herdrVersion: string) => SchemaInventory;
+/** Compares two schemas. Pure. Implemented by drift/drift-between.ts (P5c). */
+export type DriftBetween = (committed: {
+    readonly schema: SchemaDocument;
+    readonly herdrVersion: string;
+}, installed: {
+    readonly schema: SchemaDocument;
+    readonly herdrVersion: string;
+}) => DriftReport;
+/** What a schema source found. NotFound / Unreadable lead to exit 3 (could not look). */
+export type SchemaRead = {
+    readonly kind: typeof SchemaReadKind.Found;
+    readonly schema: SchemaDocument;
+    readonly herdrVersion: string;
+} | {
+    readonly kind: typeof SchemaReadKind.NotFound;
+    readonly reason: string;
+} | {
+    readonly kind: typeof SchemaReadKind.Unreadable;
+    readonly reason: string;
+};
+/** Reads one schema. bin/herdr-drift.ts injects the file reader and the `herdr` CLI runner (P5c); src/drift never does I/O. */
+export type SchemaSource = () => Promise<SchemaRead>;
+/** The CLI outcome before exit codes: a usage error, a source that could not look, or a report. */
+export type DriftOutcome = {
+    readonly kind: typeof DriftOutcomeKind.Usage;
+    readonly message: string;
+} | {
+    readonly kind: typeof DriftOutcomeKind.NotCovered;
+    readonly reason: string;
+} | {
+    readonly kind: typeof DriftOutcomeKind.Report;
+    readonly report: DriftReport;
+};
+/** 0 clean, 1 drift, 2 usage, 3 could not look (never 0). Implemented by drift/exit-code.ts (P5c). */
+export type ExitCodeFor = (outcome: DriftOutcome) => DriftExitCode;

package/dist/drift/types.js

@@ -0,0 +1 @@
+export {};

package/dist/drift.d.ts

@@ -0,0 +1,5 @@
+export { driftBetween } from './drift/diff.js';
+export { exitCodeFor } from './drift/diff.js';
+export { inventoryOf } from './drift/schema.js';
+export { DriftExitCode, DriftOutcomeKind } from './constants.js';
+export type * from './drift/types.js';

package/dist/drift.js

@@ -0,0 +1,6 @@
+// Role: the /drift entry (the bin runs drift/cli.ts): pure inventory, drift report and exit-code rule.
+// Informs HERDR-ADR-0003 (one file per subpath export), HERDR-ADR-0009 and HERDR-ADR-0017; edited only by the integration step.
+export { driftBetween } from './drift/diff.js';
+export { exitCodeFor } from './drift/diff.js';
+export { inventoryOf } from './drift/schema.js';
+export { DriftExitCode, DriftOutcomeKind } from './constants.js';

package/dist/effect.d.ts

@@ -0,0 +1,3 @@
+export { toTaggedError } from './herdr/effect/to-tagged-error.js';
+export { EffectErrorTag } from './constants.js';
+export type * from './herdr/effect/types.js';

package/dist/effect.js

@@ -0,0 +1,4 @@
+// Role: the /effect entry. Until amendment A1 (effect pinned, 2026-11-16) it exposes only the effect-free contract: layer options, error shapes, toTaggedError.
+// Informs HERDR-ADR-0003, HERDR-ADR-0004 and HERDR-ADR-0017; edited only by the integration step.
+export { toTaggedError } from './herdr/effect/to-tagged-error.js';
+export { EffectErrorTag } from './constants.js';

package/dist/herdr/client/connect.d.ts

@@ -0,0 +1,5 @@
+import type { Method } from '../generated/index.js';
+import type { ClientCapabilities, ConnectCore, Connect } from './types.js';
+export declare function assertCapability(method: Method, capabilities: ClientCapabilities): void;
+export declare const connectCore: ConnectCore;
+export declare const connect: Connect;

package/dist/herdr/client/connect.js

@@ -0,0 +1,81 @@
+// Role: connect(): ping, protocol policy, capabilities, the capability gate and the full client.
+// Informs plan 3.1, HERDR-ADR-0005, plan 3.3, HERDR-ADR-0004, HERDR-ADR-0016; merged by HERDR-ADR-0021 from capability-gate.ts, connect-core.ts, connect.ts.
+import { CAPABILITY_GATE, PROTOCOL } from '../generated/index.js';
+import { UnsupportedByServerError, HerdrTransportError, ProtocolMismatchError } from '../errors.js';
+import { ErrorText, ProtocolPolicy, Timeout, EntryKey } from '../../constants.js';
+import { MethodPing } from '../generated/names/method.js';
+import { isSupportedProtocol } from '../wire/codec.js';
+import { rpc } from '../wire/rpc.js';
+import { assertSocketExists, resolveSocketPath } from '../wire/socket-path.js';
+import { CLIENT_METHODS } from '../generated/entries/client.js';
+import { allowedMethods, composeOrClose, ENTRY_MEMBERS, lazyStreams } from './scoped.js';
+const GATES = CAPABILITY_GATE;
+export function assertCapability(method, capabilities) {
+    const capability = GATES[method];
+    if (capability !== undefined && capabilities[capability] !== true) {
+        throw new UnsupportedByServerError(method, capability);
+    }
+}
+export const connectCore = async function connectCore(options = {}) {
+    const socketPath = resolveSocketPath({ socketPath: options.socketPath, env: options.env });
+    assertSocketExists(socketPath);
+    const rpcOptions = requestOptions(options, socketPath);
+    const pong = await rpc(rpcOptions, MethodPing, {});
+    checkProtocol(pong, options.protocolPolicy ?? ProtocolPolicy.Exact);
+    return createClient(rpcOptions, pong, options);
+};
+function requestOptions(options, socketPath) {
+    return {
+        socketPath,
+        timeoutMs: options.timeoutMs ?? Timeout.DefaultMs,
+        onCall: options.onCall,
+    };
+}
+function checkProtocol(pong, policy) {
+    if (!isSupportedProtocol(pong.protocol, policy)) {
+        throw new ProtocolMismatchError(PROTOCOL, pong.protocol);
+    }
+}
+// A call's own timeoutMs and signal win over the client default; the socket path and onCall always come from the client.
+function callRpcOptions(rpcOptions, callOptions) {
+    return {
+        ...rpcOptions,
+        timeoutMs: callOptions.timeoutMs ?? rpcOptions.timeoutMs,
+        signal: callOptions.signal,
+    };
+}
+// The capabilities and server facts are fixed at connect time; a closed client refuses every call without contacting herdr
+// and aborts transport.closed so the streams P2b composes end with it (contract ClientBase.close).
+function createClient(rpcOptions, pong, options) {
+    const capabilities = Object.freeze({ ...(pong.capabilities ?? {}) });
+    const serverInfo = Object.freeze({ protocol: pong.protocol, version: pong.version });
+    const closer = new AbortController();
+    const transport = Object.freeze({
+        socketPath: rpcOptions.socketPath,
+        timeoutMs: rpcOptions.timeoutMs,
+        onCall: options.onCall,
+        onUnknown: options.onUnknown,
+        closed: closer.signal,
+    });
+    let closed = false;
+    return {
+        capabilities,
+        serverInfo,
+        transport,
+        async call(method, params, callOptions = {}) {
+            if (closed) {
+                throw new HerdrTransportError(ErrorText.ClientClosed(method));
+            }
+            assertCapability(method, capabilities);
+            return rpc(callRpcOptions(rpcOptions, callOptions), method, params);
+        },
+        close() {
+            closed = true;
+            closer.abort();
+        },
+    };
+}
+export const connect = async function connect(options = {}) {
+    const core = await connectCore(options);
+    return composeOrClose(core, allowedMethods(CLIENT_METHODS), ENTRY_MEMBERS[EntryKey.client], lazyStreams(core));
+};

package/dist/herdr/client/held.d.ts

@@ -0,0 +1,54 @@
+import type { HeldNamespaces } from '../generated/index.js';
+import type { AllowedMethods, BuildNamespaceTree, ClientCapabilities, NamespaceTree, Invoke } from './types.js';
+import type { OnCall, OpenDedicated, DedicatedConnection } from '../wire/types.js';
+/**
+ * One dedicated connection carrying the class C methods as namespaces (`held.client.window_title.set`,
+ * `held.client_shell.surface.set`, `held.server.ssh_agent.register`); capability gates apply (UnsupportedByServerError
+ * before sending). Closing it ends the registration, lease or title. If the server closes it, `ended` resolves and
+ * every later call rejects with HerdrTransportError.
+ */
+export interface HeldConnection extends HeldNamespaces, AsyncDisposable {
+    readonly ended: Promise<void>;
+    /** Destroys the connection. Idempotent. */
+    close(): Promise<void>;
+}
+export interface HoldOptions {
+    readonly signal?: AbortSignal | undefined;
+}
+/** `herdr.hold(options)`. */
+export type Hold = (options?: HoldOptions) => Promise<HeldConnection>;
+/**
+ * What the client hands the hold factory. The held tree is built with the same builder and allow-list as every
+ * client (P2b's buildNamespaceTree and allowedMethods over HELD_METHODS); they are injected so P4b's unit tests can pass a tiny
+ * builder, and P2b passes the real ones. Each leaf is an Invoke that applies the capability gate, then sends on the
+ * dedicated connection.
+ */
+export interface HoldDeps {
+    readonly socketPath: string;
+    /** The client's resolved timeout (ClientTransport.timeoutMs). */
+    readonly timeoutMs: number;
+    readonly capabilities: ClientCapabilities;
+    readonly onCall?: OnCall | undefined;
+    readonly open: OpenDedicated;
+    readonly buildTree: BuildNamespaceTree;
+    readonly allowedMethods: AllowedMethods;
+    /** The client close signal (ClientTransport.closed): when it aborts, every held connection of this client closes. */
+    readonly signal: AbortSignal;
+}
+/** Builds hold() of one client. Implemented by client/held/hold.ts (P4b). */
+export type CreateHold = (deps: HoldDeps) => Hold;
+export declare function untilAborted<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+export interface EndState {
+    /** Resolves when the dedicated connection closed for any reason (server, destroy or abort). */
+    readonly ended: Promise<void>;
+    /** True once the connection closed; read synchronously before each call. */
+    isEnded(): boolean;
+}
+export declare function trackEnd(conn: DedicatedConnection): EndState;
+export declare function toHeldConnection(tree: NamespaceTree, conn: DedicatedConnection, end: EndState, signal: AbortSignal): HeldConnection;
+export interface HeldInvokeDeps {
+    readonly capabilities: ClientCapabilities;
+    readonly timeoutMs: number;
+}
+export declare function createHeldInvoke(conn: DedicatedConnection, deps: HeldInvokeDeps, isEnded: () => boolean): Invoke;
+export declare const createHold: CreateHold;

package/dist/herdr/client/held.js

@@ -0,0 +1,100 @@
+import { HeldText } from '../../constants.js';
+import { HerdrTransportError } from '../errors.js';
+import { assertCapability } from './connect.js';
+import { HELD_METHODS } from '../generated/entries/held.js';
+// Resolves or rejects with the work, unless the signal aborts first: then it rejects with the signal's reason at once.
+export function untilAborted(work, signal) {
+    if (signal === undefined) {
+        return work;
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+        }
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+// Records the end in a flag as well as in the promise, so a call made after the end can be refused without waiting.
+export function trackEnd(conn) {
+    let closed = false;
+    const ended = conn.ended.then(() => {
+        closed = true;
+    });
+    return {
+        ended,
+        isEnded: () => closed,
+    };
+}
+// The single NamespaceTree -> HeldNamespaces assertion. The tree is built by the same builder and allow-list as every client
+// (buildNamespaceTree with the held list, HELD_METHODS), so its leaves have exactly the shape HeldNamespaces declares.
+export function toHeldConnection(tree, conn, end, signal) {
+    // Closing detaches the abort listener, so a long-lived client does not keep one per hold.
+    const close = closeOnce(conn, end.ended, () => signal.removeEventListener('abort', onAbort));
+    const onAbort = () => {
+        void close();
+    };
+    if (signal.aborted) {
+        void close();
+    }
+    else {
+        signal.addEventListener('abort', onAbort, { once: true });
+    }
+    const namespaces = tree;
+    return {
+        ...namespaces,
+        ended: end.ended,
+        close,
+        [Symbol.asyncDispose]: close,
+    };
+}
+// The first call destroys the connection and waits for it to end; later calls return the same promise.
+function closeOnce(conn, ended, detach) {
+    let closing;
+    return () => {
+        closing ??= destroyAndWait(conn, ended, detach);
+        return closing;
+    };
+}
+async function destroyAndWait(conn, ended, detach) {
+    detach();
+    conn.destroy();
+    await ended;
+}
+export function createHeldInvoke(conn, deps, isEnded) {
+    // Every call waits for the previous one, so a second request never reaches the connection while one is pending.
+    let previous = Promise.resolve();
+    return async function invokeHeld(method, params, options) {
+        assertCapability(method, deps.capabilities);
+        const signal = options?.signal;
+        const send = async () => {
+            // A call aborted while it was queued is never sent.
+            if (signal?.aborted === true) {
+                throw signal.reason;
+            }
+            if (isEnded()) {
+                throw new HerdrTransportError(HeldText.Ended(method));
+            }
+            // Invoke erases the params type (client/types.ts); the generated namespaces type them at the leaf that calls this.
+            return conn.request(method, params, {
+                timeoutMs: options?.timeoutMs ?? deps.timeoutMs,
+                signal,
+            });
+        };
+        const run = previous.then(send);
+        previous = run.catch(() => undefined);
+        // The caller hears its own abort at once, even while the call waits for an earlier one.
+        return untilAborted(run, signal);
+    };
+}
+// One connection per hold(), open until close(), the client's close, the caller's signal, or the server's close. Every held call goes over it.
+export const createHold = (deps) => async function hold(options = {}) {
+    // The held connection closes when either the client closes or the caller's signal aborts.
+    const signal = options.signal === undefined ? deps.signal : AbortSignal.any([deps.signal, options.signal]);
+    const conn = await deps.open({ socketPath: deps.socketPath, signal, onCall: deps.onCall });
+    const end = trackEnd(conn);
+    const invoke = createHeldInvoke(conn, deps, end.isEnded);
+    const tree = deps.buildTree(deps.allowedMethods(HELD_METHODS), invoke);
+    return toHeldConnection(tree, conn, end, signal);
+};

package/dist/herdr/client/long-poll.d.ts

@@ -0,0 +1,33 @@
+import { LONG_POLL } from '../generated/index.js';
+import type { Method } from '../generated/index.js';
+/** Methods whose rpc timeout follows a timeout_ms field in their params. */
+export type LongPollMethod = keyof typeof LONG_POLL;
+/**
+ * The rpc timeout of one call: for a LongPollMethod whose timeout path is present, timeout_ms + Timeout.LongPollMarginMs;
+ * otherwise `fallbackMs` (the client's timeoutMs). Pure. Implemented by client/long-poll/timeout.ts (P4a).
+ * The namespace tree (P2b) calls it only for methods that are LONG_POLL keys.
+ */
+export type RequestTimeoutMs = (method: Method, params: unknown, fallbackMs: number | undefined) => number | undefined;
+/**
+ * Throws HerdrTransportError before sending when a bounded timeout is out of range (agent.start: > 3000 and <= 300000).
+ * Pure. Implemented by client/long-poll/bounds.ts (P4a).
+ */
+export type AssertLongPollBounds = (method: Method, params: unknown) => void;
+export declare const LongPollText: {
+    readonly OutOfBounds: (method: string, value: number, exclusiveMin: number, max: number) => string;
+};
+export declare function readPath(value: unknown, path: readonly string[]): unknown;
+export declare function isNumber(value: unknown): value is number;
+export declare function isPresent(value: unknown): boolean;
+export interface LongPollBounds {
+    readonly exclusiveMin: number;
+    readonly max: number;
+}
+export interface LongPollRule {
+    readonly timeoutPath: readonly string[];
+    readonly onlyWhenPresent?: string | undefined;
+    readonly bounds?: LongPollBounds | undefined;
+}
+export declare function ruleOf(method: Method): LongPollRule | undefined;
+export declare const assertLongPollBounds: AssertLongPollBounds;
+export declare const requestTimeoutMs: RequestTimeoutMs;

package/dist/herdr/client/long-poll.js

@@ -0,0 +1,66 @@
+// Role: long-poll methods: their bounds, the check of a requested timeout and the request timeout they need.
+// Informs HERDR-ADR-0017, HERDR-ADR-0007, plan 3.6; merged by HERDR-ADR-0021 from types.ts, constants.ts, read-path.ts, rule.ts, bounds.ts, timeout.ts.
+import { LONG_POLL } from '../generated/index.js';
+import { TypeofTag, Timeout } from '../../constants.js';
+import { HerdrTransportError } from '../errors.js';
+export const LongPollText = {
+    OutOfBounds: (method, value, exclusiveMin, max) => `${method}: timeout_ms ${value} must be greater than ${exclusiveMin} and at most ${max}`,
+};
+const ValueType = {
+    Number: 'number',
+};
+export function readPath(value, path) {
+    let current = value;
+    for (const key of path) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+export function isNumber(value) {
+    return typeof value === ValueType.Number;
+}
+// A value the caller actually set: null and undefined both mean "not sent".
+export function isPresent(value) {
+    return value !== undefined && value !== null;
+}
+function isRecord(value) {
+    return typeof value === TypeofTag.Object && value !== null && !Array.isArray(value);
+}
+export function ruleOf(method) {
+    return isLongPollMethod(method) ? LONG_POLL[method] : undefined;
+}
+function isLongPollMethod(method) {
+    return Object.hasOwn(LONG_POLL, method);
+}
+export const assertLongPollBounds = function assertLongPollBounds(method, params) {
+    const rule = ruleOf(method);
+    const bounds = rule?.bounds;
+    if (rule === undefined || bounds === undefined) {
+        return;
+    }
+    const timeout = readPath(params, rule.timeoutPath);
+    if (!isNumber(timeout) || isInside(timeout, bounds)) {
+        return;
+    }
+    throw new HerdrTransportError(LongPollText.OutOfBounds(method, timeout, bounds.exclusiveMin, bounds.max));
+};
+// Strictly above exclusiveMin, at most max.
+function isInside(value, bounds) {
+    return value > bounds.exclusiveMin && value <= bounds.max;
+}
+export const requestTimeoutMs = function requestTimeoutMs(method, params, fallbackMs) {
+    const rule = ruleOf(method);
+    if (rule === undefined || !isGateOpen(rule, params)) {
+        return fallbackMs;
+    }
+    const timeout = readPath(params, rule.timeoutPath);
+    return isNumber(timeout) ? timeout + Timeout.LongPollMarginMs : fallbackMs;
+};
+// agent.prompt only waits when `wait` is sent; without it the call is an ordinary request.
+function isGateOpen(rule, params) {
+    const gate = rule.onlyWhenPresent;
+    return gate === undefined || isPresent(readPath(params, [gate]));
+}