@stateforge-labs/herdr 0.0.0-stage → 0.3.0

package/dist/herdr/test-kit/fake-protocol.js

@@ -0,0 +1,436 @@
+// Role: what the fake herdr says: answers, acks, pongs, param checks, held and subscription bookkeeping and the scripted steps.
+// Informs HERDR-ADR-0016, plan 5, HERDR-ADR-0008; merged by HERDR-ADR-0021 from fake-values.ts, fake-write.ts, fake-socket-path.ts, fake-pong.ts, fake-defaults.ts, fake-ack.ts, fake-request-check.ts, fake-script.ts, fake-answer.ts, fake-held.ts, fake-subscription.ts, fake-subscribers.ts.
+import { TypeofTag, LINE_SEPARATOR, TEXT_ENCODING, Fake, DEFAULT_CAPABILITIES, WireField, EMPTY_SCHEMA_RESULT, FakeMethod, FakeCheckText, FakeErrorCode, TypeofValue, AnswerKind, FakeText, EntryKey, NameSeparator, PER_PANE_SUBSCRIPTION_TYPES, SpecField } from '../../constants.js';
+import { isObject } from '../wire/codec.js';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ResultTag, Method, ENTRY_METHODS, EventKind, SubscriptionType } from '../generated/index.js';
+import { JsonKind, PARAMS_SHAPE } from '../generated/test-data/shapes.js';
+// The field of a JSON object, or undefined when the value is not an object. JSON has no undefined, so undefined means absent.
+export function fieldOf(value, name) {
+    return isObject(value) ? Reflect.get(value, name) : undefined;
+}
+// True for a string value.
+export function isText(value) {
+    return typeof value === TypeofTag.String;
+}
+// One NDJSON line. A string is written as it is (a stray line), an object is serialised.
+export function lineOf(value) {
+    const text = typeof value === TypeofTag.String ? value : JSON.stringify(value);
+    return `${text}${LINE_SEPARATOR}`;
+}
+// A client may have destroyed its socket; a write to it must not crash the fake.
+export function safeWrite(socket, text) {
+    try {
+        socket.write(text, TEXT_ENCODING);
+    }
+    catch {
+        // The client already went away; there is nobody left to write to.
+    }
+}
+// Ends the socket from the server side; a socket that is already gone ignores it.
+export function endSocket(socket) {
+    try {
+        socket.end();
+    }
+    catch {
+        // The client already went away; there is nothing to end.
+    }
+}
+export function fakeSocketLocation(socketPath) {
+    if (socketPath !== undefined) {
+        return { path: socketPath, ownedDir: undefined };
+    }
+    const dir = mkdtempSync(join(tmpdir(), Fake.DirPrefix));
+    return { path: join(dir, Fake.SocketFile), ownedDir: dir };
+}
+export function removeOwnedDir(location) {
+    if (location.ownedDir !== undefined) {
+        rmSync(location.ownedDir, { recursive: true, force: true });
+    }
+}
+// The capabilities option as the pong uses it: undefined means the default set.
+export function advertisedCapabilities(option) {
+    return option === undefined ? DEFAULT_CAPABILITIES : option;
+}
+export function pongBody(settings) {
+    const body = {
+        [WireField.Type]: ResultTag.Pong,
+        [WireField.Protocol]: settings.protocol,
+        [WireField.Version]: settings.version,
+    };
+    if (settings.capabilities !== null) {
+        body[WireField.Capabilities] = settings.capabilities;
+    }
+    return body;
+}
+// The default result of a method, or undefined when the fake has no default for it.
+export function defaultResultOf(method, pong) {
+    if (method === Method.Ping) {
+        return pongBody(pong);
+    }
+    if (method === FakeMethod.ApiSchema) {
+        return EMPTY_SCHEMA_RESULT;
+    }
+    return undefined;
+}
+export class AckSwitches {
+    splitNext = false;
+    strayNext;
+    // The next ack is written in two chunks.
+    splitNextAck() {
+        this.splitNext = true;
+    }
+    // The next ack is preceded by this line.
+    strayBeforeAck(line) {
+        this.strayNext = line;
+    }
+    // Writes the ack of the subscription with this request id, applying each switch once.
+    acknowledge(socket, id) {
+        const ack = lineOf({
+            [WireField.Id]: id,
+            [WireField.Result]: { [WireField.Type]: ResultTag.SubscriptionStarted },
+        });
+        const text = `${this.takeStray()}${ack}`;
+        if (this.takeSplit()) {
+            writeSplit(socket, text);
+        }
+        else {
+            safeWrite(socket, text);
+        }
+    }
+    takeStray() {
+        const line = this.strayNext;
+        this.strayNext = undefined;
+        return line === undefined ? '' : lineOf(line);
+    }
+    takeSplit() {
+        const split = this.splitNext;
+        this.splitNext = false;
+        return split;
+    }
+}
+// Writes the first half now and the rest after a short delay, so the client reads a partial line first.
+function writeSplit(socket, text) {
+    const cut = Math.floor(text.length / 2);
+    safeWrite(socket, text.slice(0, cut));
+    setTimeout(() => {
+        safeWrite(socket, text.slice(cut));
+    }, Fake.SplitAckDelayMs);
+}
+// The shape of a method, or undefined when the generated table does not list it (then nothing is checked).
+function shapeOf(method) {
+    const shapes = PARAMS_SHAPE;
+    return Object.hasOwn(shapes, method) ? shapes[method] : undefined;
+}
+// The first problem with the params, as the error herdr would return; undefined when the params fit the shape.
+// Absent params count as an empty object.
+export function checkParams(method, params) {
+    const shape = shapeOf(method);
+    if (shape === undefined) {
+        return undefined;
+    }
+    const value = params === undefined ? {} : params;
+    if (!isObject(value)) {
+        return Object.keys(shape.fields).length === 0 ? undefined : problem(FakeCheckText.NotAnObject(method));
+    }
+    for (const name of shape.required) {
+        if (fieldOf(value, name) === undefined) {
+            return problem(FakeCheckText.MissingField(method, name));
+        }
+    }
+    for (const [name, field] of Object.entries(shape.fields)) {
+        const present = fieldOf(value, name);
+        if (present !== undefined) {
+            const fieldProblem = checkField(method, name, field, present);
+            if (fieldProblem !== undefined) {
+                return fieldProblem;
+            }
+        }
+    }
+    return undefined;
+}
+function checkField(method, name, field, value) {
+    const kind = jsonKindOf(value);
+    if (!field.kinds.some((allowed) => kindFits(kind, allowed))) {
+        return problem(FakeCheckText.WrongKind(method, name));
+    }
+    if (field.enum !== undefined && isText(value) && !field.enum.includes(value)) {
+        return problem(FakeCheckText.NotInEnum(method, name));
+    }
+    if (field.keyPattern !== undefined && isObject(value)) {
+        const pattern = new RegExp(field.keyPattern);
+        if (Object.keys(value).some((key) => !pattern.test(key))) {
+            return problem(FakeCheckText.KeyNotAllowed(method, name));
+        }
+    }
+    return undefined;
+}
+// An integer is also a number (JSON Schema): a field that allows number takes 3.
+function kindFits(actual, allowed) {
+    return actual === allowed || (allowed === JsonKind.Number && actual === JsonKind.Integer);
+}
+// The JSON kind of a parsed value.
+export function jsonKindOf(value) {
+    if (value === null) {
+        return JsonKind.Null;
+    }
+    if (Array.isArray(value)) {
+        return JsonKind.Array;
+    }
+    if (isText(value)) {
+        return JsonKind.String;
+    }
+    if (typeof value === TypeofValue.Number) {
+        return Number.isInteger(value) ? JsonKind.Integer : JsonKind.Number;
+    }
+    if (typeof value === TypeofValue.Boolean) {
+        return JsonKind.Boolean;
+    }
+    return JsonKind.Object;
+}
+function problem(message) {
+    return { code: FakeErrorCode.InvalidParams, message };
+}
+export class FakeScript {
+    replies = new Map();
+    failures = new Map();
+    rawLines = new Map();
+    silences = new Set();
+    sequences = new Map();
+    received = [];
+    setReply(method, result) {
+        this.replies.set(method, result);
+    }
+    setFailure(method, error) {
+        this.failures.set(method, error);
+    }
+    setRawLine(method, line) {
+        this.rawLines.set(method, line);
+    }
+    setSilent(method) {
+        this.silences.add(method);
+    }
+    // Stores a copy, so a later change to the caller's array does not change the script.
+    setSequence(method, steps) {
+        this.sequences.set(method, [...steps]);
+    }
+    // The next step of the sequence, consumed; undefined when the method has no steps left.
+    takeStep(method) {
+        return this.sequences.get(method)?.shift();
+    }
+    record(request) {
+        this.received.push(request);
+    }
+    methods() {
+        return this.received.map((request) => request.method);
+    }
+    requests() {
+        return [...this.received];
+    }
+    // True when a test scripted this method to be silent, raw, refused or with steps left; such a method is not acknowledged as a subscription.
+    // A reply alone does not count: events.subscribe is answered by its ack (F2) unless a test scripts one of the outcomes above.
+    hasScriptedOutcome(method) {
+        return this.silences.has(method) || this.rawLines.has(method) || this.failures.has(method) || (this.sequences.get(method)?.length ?? 0) > 0;
+    }
+    isSilent(method) {
+        return this.silences.has(method);
+    }
+    rawLineOf(method) {
+        return this.rawLines.get(method);
+    }
+    failureOf(method) {
+        return this.failures.get(method);
+    }
+    hasReply(method) {
+        return this.replies.has(method);
+    }
+    replyOf(method) {
+        return this.replies.get(method);
+    }
+}
+const SILENT = { kind: AnswerKind.Silent };
+export function answerFor(script, request, pong) {
+    const { id, method } = request;
+    if (script.isSilent(method)) {
+        return SILENT;
+    }
+    const rawLine = script.rawLineOf(method);
+    if (rawLine !== undefined) {
+        return { kind: AnswerKind.Raw, line: rawLine };
+    }
+    const refusal = checkParams(method, request.params);
+    if (refusal !== undefined) {
+        return errorAnswer(id, refusal);
+    }
+    const step = script.takeStep(method);
+    if (step !== undefined) {
+        return stepAnswer(id, step);
+    }
+    const failure = script.failureOf(method);
+    if (failure !== undefined) {
+        return errorAnswer(id, failure);
+    }
+    if (script.hasReply(method)) {
+        return resultAnswer(id, script.replyOf(method));
+    }
+    const fallback = defaultResultOf(method, pong);
+    if (fallback !== undefined) {
+        return resultAnswer(id, fallback);
+    }
+    return errorAnswer(id, { code: Fake.UnknownMethodCode, message: FakeText.UnknownMethod(method) });
+}
+// The answer to a line that is not a JSON request: herdr replies with the empty id and an error (W3).
+export function invalidRequestAnswer() {
+    return errorAnswer('', { code: Fake.InvalidRequestCode, message: FakeText.InvalidRequest });
+}
+// An envelope with this error.
+export function errorAnswer(id, error) {
+    return { kind: AnswerKind.Envelope, body: { [WireField.Id]: id, [WireField.Error]: error } };
+}
+function stepAnswer(id, step) {
+    return WireField.Error in step ? errorAnswer(id, step.error) : resultAnswer(id, step.result);
+}
+function resultAnswer(id, result) {
+    return { kind: AnswerKind.Envelope, body: { [WireField.Id]: id, [WireField.Result]: result } };
+}
+// True for a class C method: the connection-bound ones herdr keeps open after the answer.
+export function isHeldMethod(method) {
+    const heldMethods = ENTRY_METHODS[EntryKey.held];
+    return heldMethods.includes(method);
+}
+export class HeldConnections {
+    sockets = new Set();
+    add(socket) {
+        this.sockets.add(socket);
+    }
+    // A connection that closed leaves the set.
+    forget(socket) {
+        this.sockets.delete(socket);
+    }
+    count() {
+        return this.sockets.size;
+    }
+    // Ends every held connection from the server side; the client sees its connection end.
+    closeAll() {
+        for (const socket of this.sockets) {
+            endSocket(socket);
+        }
+        this.sockets.clear();
+    }
+}
+const SUBSCRIPTION_TYPES = new Set(Object.values(SubscriptionType));
+const PER_PANE_TYPES = new Set(PER_PANE_SUBSCRIPTION_TYPES);
+const EVENT_KINDS = new Set(Object.values(EventKind));
+// The frame names that each subscription type answers to. A subscription type names itself (pane.output_matched); an event kind names it
+// with its first separator changed (pane_created is pane.created). Built once, here, from the generated names: no other place maps names.
+const TYPE_BY_FRAME_NAME = frameNameTable();
+// Why herdr would refuse this events.subscribe: params that break the generated shape, a spec that is not a known type, or a per-pane spec without
+// pane_id. Undefined when it is accepted.
+export function subscribeRefusal(params) {
+    const shapeProblem = checkParams(Method.EventsSubscribe, params);
+    if (shapeProblem !== undefined) {
+        return shapeProblem;
+    }
+    if (entriesOf(params).some((entry) => !isSpecEntry(entry))) {
+        return { code: FakeErrorCode.InvalidParams, message: FakeCheckText.WrongKind(Method.EventsSubscribe, SpecField.Subscriptions) };
+    }
+    const withoutPane = specsOf(params).find((spec) => PER_PANE_TYPES.has(spec.type) && spec.paneId === undefined);
+    return withoutPane === undefined ? undefined : { code: FakeErrorCode.InvalidParams, message: FakeCheckText.NeedsPaneId(withoutPane.type) };
+}
+// The specs of an events.subscribe request, in order. Entries that are not a known spec type are skipped (subscribeRefusal refuses them first).
+export function specsOf(params) {
+    return entriesOf(params).flatMap((entry) => {
+        const type = fieldOf(entry, WireField.Type);
+        if (!isSubscriptionType(type)) {
+            return [];
+        }
+        const paneId = fieldOf(entry, SpecField.PaneId);
+        return [{ type, paneId: isText(paneId) ? paneId : undefined }];
+    });
+}
+// Whether a pushed frame reaches the subscription with these specs. A frame whose name is a subscription type reaches a spec of that type, and a
+// per-pane type reaches only the spec whose pane_id is the frame's. A known event kind with no subscription type (pane_output_changed) reaches nobody:
+// herdr offers it only through events.wait. A kind the fake does not know at all reaches every subscription, on purpose: herdr may push kinds nobody asked for (P3).
+export function reaches(specs, frame) {
+    const type = TYPE_BY_FRAME_NAME.get(frame.event);
+    if (type === undefined) {
+        return !EVENT_KINDS.has(frame.event);
+    }
+    const paneId = fieldOf(frame.data, SpecField.PaneId);
+    return specs.some((spec) => spec.type === type && (!PER_PANE_TYPES.has(type) || spec.paneId === paneId));
+}
+// The frame name table: each subscription type, and its event-kind spelling (first separator changed) when it differs.
+function frameNameTable() {
+    const names = new Map();
+    for (const type of Object.values(SubscriptionType)) {
+        names.set(type, type);
+        names.set(type.replace(NameSeparator.Subscription, NameSeparator.Event), type);
+    }
+    return names;
+}
+function entriesOf(params) {
+    const entries = fieldOf(params, SpecField.Subscriptions);
+    return Array.isArray(entries) ? entries : [];
+}
+function isSubscriptionType(value) {
+    return isText(value) && SUBSCRIPTION_TYPES.has(value);
+}
+function isSpecEntry(entry) {
+    return isObject(entry) && isSubscriptionType(fieldOf(entry, WireField.Type));
+}
+export class Subscribers {
+    specsBySocket = new Map();
+    // Frames queued while pushes are held; undefined when pushes flow.
+    queued;
+    add(socket, specs) {
+        this.specsBySocket.set(socket, specs);
+    }
+    // A connection that closed leaves the set.
+    forget(socket) {
+        this.specsBySocket.delete(socket);
+    }
+    count() {
+        return this.specsBySocket.size;
+    }
+    // Writes the frame to every matching subscription, or queues it while pushes are held.
+    push(frame) {
+        if (this.queued !== undefined) {
+            this.queued.push(frame);
+            return;
+        }
+        this.deliver(frame);
+    }
+    // Queues pushes until the returned release runs; release writes the queued frames in order. A second release does nothing.
+    holdPushes() {
+        const queue = [];
+        this.queued = queue;
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            this.queued = undefined;
+            for (const frame of queue) {
+                this.deliver(frame);
+            }
+        };
+    }
+    // Ends every subscription connection from the server side; the client sees the subscription end.
+    closeAll() {
+        for (const socket of this.specsBySocket.keys()) {
+            endSocket(socket);
+        }
+        this.specsBySocket.clear();
+    }
+    deliver(frame) {
+        const line = lineOf(frame);
+        for (const [socket, specs] of this.specsBySocket) {
+            if (reaches(specs, frame)) {
+                safeWrite(socket, line);
+            }
+        }
+    }
+}

package/dist/herdr/test-kit/types.d.ts

@@ -0,0 +1,88 @@
+import type { WireFact } from '../../constants.js';
+import type { ErrorBody, Method, PushFrame } from '../generated/index.js';
+import type { ServerCapabilities } from '../generated/results.js';
+import type { ResultOf } from '../wire/types.js';
+export interface FakeHerdrOptions {
+    /** Protocol number the pong reports; default the library's PROTOCOL. */
+    readonly protocol?: number | undefined;
+    /** herdr version the pong reports (client.serverInfo.version); default Fake.Version. */
+    readonly version?: string | undefined;
+    /** Socket path to listen on; default a fresh temp directory the fake removes on stop. */
+    readonly socketPath?: string | undefined;
+    /** Capabilities the pong advertises. Undefined: DEFAULT_CAPABILITIES. Null: the pong omits the field. */
+    readonly capabilities?: ServerCapabilities | null | undefined;
+}
+/** One request line the fake received, parsed. */
+export interface ReceivedRequest {
+    readonly id: string;
+    readonly method: string;
+    readonly params: unknown;
+}
+/** A scripted step of replySequence: a result, or an error envelope. */
+export type FakeStep<M extends Method> = {
+    readonly result: ResultOf<M>;
+} | {
+    readonly error: ErrorBody;
+};
+/** A push line with an `event` the library does not know (HERDR-ADR-0016 P3). */
+export interface UnknownPush {
+    readonly event: string;
+    readonly data: unknown;
+}
+export interface FakeHerdr {
+    /** Socket path to pass as connect({ socketPath }). */
+    readonly path: string;
+    /** Capabilities the pong advertises (after the option's default). */
+    readonly capabilities: ServerCapabilities | null;
+    /** Measured herdr wire facts this fake reproduces (W1-W6), each covered by a test in test/test-kit. */
+    readonly reproduces: readonly WireFact[];
+    /**
+     * Answers every later call of `method` with a result envelope. For events.subscribe the ack is the answer (F2), so a reply alone is not used there;
+     * use fail, silent, rawReply or replySequence to change a subscribe.
+     */
+    reply<M extends Method>(method: M, result: ResultOf<M>): void;
+    /** Answers every later call of `method` with an error envelope. */
+    fail(method: Method, error: ErrorBody): void;
+    /**
+     * Accepts `method` and never answers; the connection stays open until the client closes it.
+     * Ack-timeout recipe: `silent(Method.EventsSubscribe)` then subscribe with a short `ackTimeoutMs`.
+     */
+    silent(method: Method): void;
+    /** Writes `line` verbatim for `method`, then ends the connection. */
+    rawReply(method: Method, line: string): void;
+    /** Every request method received, in order, ping included. */
+    receivedMethods(): readonly string[];
+    /** Connections open right now. */
+    connectionCount(): number;
+    /** Closes the server, destroys open connections, removes the temp directory it made. */
+    stop(): Promise<void>;
+    /** Answers successive calls of `method` with these steps, then falls back to reply/default. */
+    replySequence<M extends Method>(method: M, steps: readonly FakeStep<M>[]): void;
+    /** Every request received, parsed, in order. */
+    requests(): readonly ReceivedRequest[];
+    /**
+     * Writes one push line to every acked subscription whose specs match it: a frame goes to a subscription that
+     * subscribed its type, and a per-pane frame only to the one whose spec has the frame's pane_id (W6). An UnknownPush
+     * goes to every acked subscription (herdr may send kinds nobody asked for; P3).
+     */
+    push(frame: PushFrame | UnknownPush): void;
+    /** Closes every subscription connection (the client sees SubscriptionEnded). */
+    closeSubscribers(): void;
+    /** Subscriptions that are acked and open right now. */
+    subscriberCount(): number;
+    /** Queues pushes until the returned release function runs (to test frames between ack and snapshot). */
+    holdPushes(): () => void;
+    /** The next subscribe ack is written in two chunks (framing test, W2). */
+    splitAck(): void;
+    /** The next subscribe ack is preceded by `line`, a line with another id (stray-line test, W2). */
+    strayLine(line: string): void;
+    /**
+     * Connections that sent a class C (ENTRY_METHODS.held) request and are still open: the fake keeps such a
+     * connection open after the reply, as hold() assumes (contracts.md open issue 1).
+     */
+    heldCount(): number;
+    /** Closes every held connection from the server side (the client's HeldConnection.ended resolves). */
+    closeHeld(): void;
+}
+/** createFakeHerdr(options). Implemented by test-kit/fake-herdr.ts (P2a minimum, P5a full). */
+export type CreateFakeHerdr = (options?: FakeHerdrOptions) => Promise<FakeHerdr>;

package/dist/herdr/test-kit/types.js

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

package/dist/herdr/wire/codec.d.ts

@@ -0,0 +1,36 @@
+import type { METHOD_RESULT, Method, MethodParams, ResponseResult, ResultByTag, ErrorBody } from '../generated/index.js';
+import { ProtocolPolicy, CallOutcome } from '../../constants.js';
+import type { CallEvent, OnCall } from './types.js';
+export type { CallEvent, OnCall } from './types.js';
+export type ParamsOf<M extends Method> = MethodParams[M];
+export type ResultOf<M extends Method> = M extends keyof typeof METHOD_RESULT ? ResultByTag[(typeof METHOD_RESULT)[M]] : ResponseResult;
+export declare function nextId(prefix?: string): string;
+export interface RequestEnvelope<M extends string = string, P = unknown> {
+    id: string;
+    method: M;
+    params: P;
+}
+export interface SuccessEnvelope<R = ResponseResult> {
+    id: string;
+    result: R;
+}
+export interface ErrorEnvelope {
+    id: string;
+    error: ErrorBody;
+}
+export type ResponseEnvelope<R = ResponseResult> = SuccessEnvelope<R> | ErrorEnvelope;
+export declare function isErrorEnvelope(envelope: object): envelope is ErrorEnvelope;
+export declare function isObject(value: unknown): value is object;
+export declare function encodeRequest(id: string, method: string, params: unknown): string;
+export declare class LineSplitter {
+    private buffer;
+    push(chunk: string): string[];
+    get pending(): string;
+}
+export declare function isSupportedProtocol(actual: number, policy?: ProtocolPolicy, expected?: number): boolean;
+export interface CallClassification {
+    readonly outcome: CallOutcome;
+    readonly code?: string;
+}
+export declare function outcomeOf(error: unknown): CallClassification;
+export declare function reportCall(onCall: OnCall | undefined, event: CallEvent): void;

package/dist/herdr/wire/codec.js

@@ -0,0 +1,62 @@
+// Role: the wire codec: request ids, the JSON-RPC envelopes, the NDJSON line splitter, the protocol policy, the typed params/result helpers and the per-call hook.
+// Informs HERDR-ADR-0017, HERDR-ADR-0002, plan 3.2, HERDR-ADR-0016, plan 3.1, plan 3, HERDR-ADR-0009, HERDR-ADR-0004, plan 3.3; merged by HERDR-ADR-0021 from typed.ts, id.ts, envelope.ts, line-splitter.ts, protocol-policy.ts, call-hook.ts.
+import { PROTOCOL } from '../generated/index.js';
+import { REQUEST_ID_PREFIX, TypeofTag, WireField, LINE_SEPARATOR, ProtocolPolicy, CallOutcome } from '../../constants.js';
+import { HerdrError } from '../errors.js';
+const FIRST_COUNT = 1;
+let counter = 0;
+export function nextId(prefix = REQUEST_ID_PREFIX) {
+    counter += FIRST_COUNT;
+    return `${prefix}-${counter}-${Date.now().toString(36)}`;
+}
+export function isErrorEnvelope(envelope) {
+    return WireField.Error in envelope;
+}
+// A JSON object envelope: an object that is neither null nor an array.
+export function isObject(value) {
+    return typeof value === TypeofTag.Object && value !== null && !Array.isArray(value);
+}
+// One request as a JSON line, without the trailing newline (the connection adds it).
+export function encodeRequest(id, method, params) {
+    return JSON.stringify({ [WireField.Id]: id, [WireField.Method]: method, [WireField.Params]: params });
+}
+export class LineSplitter {
+    buffer = '';
+    // Feeds one chunk and returns every complete, non-empty line it finished.
+    push(chunk) {
+        const parts = (this.buffer + chunk).split(LINE_SEPARATOR);
+        this.buffer = parts.pop() ?? '';
+        return parts.filter((line) => line.length > 0);
+    }
+    // Text received after the last newline, not yet a line.
+    get pending() {
+        return this.buffer;
+    }
+}
+export function isSupportedProtocol(actual, policy = ProtocolPolicy.Exact, expected = PROTOCOL) {
+    switch (policy) {
+        case ProtocolPolicy.Exact:
+            return actual === expected;
+        case ProtocolPolicy.Minimum:
+            return actual >= expected;
+    }
+}
+// A server refusal is Refused with its code; everything else (timeout, abort, socket, malformed line) is Transport.
+export function outcomeOf(error) {
+    if (error instanceof HerdrError) {
+        return { outcome: CallOutcome.Refused, code: error.code };
+    }
+    return { outcome: CallOutcome.Transport };
+}
+// Runs the hook; a hook that throws changes nothing about the call.
+export function reportCall(onCall, event) {
+    if (onCall === undefined) {
+        return;
+    }
+    try {
+        onCall(event);
+    }
+    catch {
+        // The observer is best effort: the caller's result or error is never replaced by a hook failure.
+    }
+}

package/dist/herdr/wire/connection.d.ts

@@ -0,0 +1,13 @@
+export interface ConnectionHandlers {
+    onLine(line: string): void;
+    onClose(): void;
+    onError(error: unknown): void;
+}
+export declare class Connection {
+    private readonly socket;
+    private constructor();
+    static open(path: string, handlers: ConnectionHandlers): Promise<Connection>;
+    writeLine(line: string): void;
+    close(): void;
+    destroy(): void;
+}