@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,45 @@
+import type { Method } from '../generated/index.js';
+import type { AllowedMethods, BuildNamespaceTree, Invoke, CoreClient, StreamMembers, ConnectAdmin, ConnectPrompt, ConnectReadOnly } from './types.js';
+import type { AssertLongPollBounds, RequestTimeoutMs } from './long-poll.js';
+export declare const allowedMethods: AllowedMethods;
+export declare const buildNamespaceTree: BuildNamespaceTree;
+/** The P4a helpers a long-poll call needs; tests pass stubs. */
+export interface InvokeDeps {
+    readonly requestTimeoutMs: RequestTimeoutMs;
+    readonly assertLongPollBounds: AssertLongPollBounds;
+}
+export declare function createInvoke(core: CoreClient, allowed: ReadonlySet<Method>, deps?: InvokeDeps): Invoke;
+/** Throws before anything is sent when the method is not in the entry's allow-list. */
+export declare function assertAllowed(method: Method, allowed: ReadonlySet<Method>): void;
+export declare function lazyStreams(core: CoreClient): StreamMembers;
+/** Which members beyond the namespace tree an entry has. */
+export interface Members {
+    readonly call: boolean;
+    readonly streams: boolean;
+    readonly hold: boolean;
+}
+/** connect() and connectAdmin() have everything; the read-only entries stream; prompt has no streams and no call(). */
+export declare const ENTRY_MEMBERS: {
+    readonly client: Members;
+    readonly admin: Members;
+    readonly prompt: Members;
+    readonly readOnly: Members;
+    readonly readOnlyContent: Members;
+};
+/** The preset form of connectReadOnly: a fixed list with no streams and no call(). */
+export declare const PRESET_MEMBERS: Members;
+/**
+ * Builds a public client of type T from the core and the allow-list. The tree is built from exactly `allowed`;
+ * T is the generated type of the same entry. The runtime object is assembled from the tree and the members, so its static
+ * type is asserted to T by the final cast; the contract type tests (test/types) check the members of each T.
+ * `streams` is the lazy loader of the stream members (lazy-streams.ts); tests pass their own.
+ */
+export declare function composeClient<T>(core: CoreClient, allowed: ReadonlySet<Method>, members: Members, streams?: StreamMembers): T;
+/**
+ * composeClient, but closes the core when composition refuses (a watch on a method list without its methods), so the
+ * connection the core opened is not left live. Every connect function composes through this.
+ */
+export declare function composeOrClose<T>(core: CoreClient, allowed: ReadonlySet<Method>, members: Members, streams?: StreamMembers): T;
+export declare const connectAdmin: ConnectAdmin;
+export declare const connectPrompt: ConnectPrompt;
+export declare const connectReadOnly: ConnectReadOnly;

package/dist/herdr/client/scoped.js

@@ -0,0 +1,241 @@
+// Role: the capability-scoped clients (read-only, prompt, admin): allowed methods, the namespace tree, invoke and the stream members.
+// Informs HERDR-ADR-0005, HERDR-ADR-0017, plan 3.4, plan 3.3, HERDR-ADR-0007, plan 3.6, plan 10.1, HERDR-ADR-0015; merged by HERDR-ADR-0021 from allowed-methods.ts, namespace-tree.ts, invoke.ts, lazy-streams.ts, compose.ts, connect-admin.ts, connect-prompt.ts, connect-read-only.ts.
+import { LONG_POLL } from '../generated/index.js';
+import { METHOD_SEPARATOR, TypeofKind, ErrorText, EntryKey, TreeKey, Presets } from '../../constants.js';
+import { MethodEventsSubscribe, MethodSessionSnapshot } from '../generated/names/method.js';
+import { HerdrTransportError } from '../errors.js';
+import { assertLongPollBounds as defaultAssertBounds, requestTimeoutMs as defaultRequestTimeoutMs } from './long-poll.js';
+import { ADMIN_METHODS } from '../generated/entries/admin.js';
+import { connectCore } from './connect.js';
+import { PROMPT_METHODS } from '../generated/entries/prompt.js';
+import { READ_ONLY_CONTENT_METHODS } from '../generated/entries/read-only-content.js';
+import { READ_ONLY_METHODS } from '../generated/entries/read-only.js';
+import { SESSIONS_READER_METHODS } from '../generated/presets/sessions-reader.js';
+export const allowedMethods = function allowedMethods(base, options = {}) {
+    return options.methods === undefined ? new Set(base) : narrow(base, options.methods);
+};
+// A method outside the base list is dropped, not added: `methods` can only narrow the entry.
+function narrow(base, methods) {
+    const inBase = new Set(base);
+    return new Set(methods.filter((method) => inBase.has(method)));
+}
+export const buildNamespaceTree = function buildNamespaceTree(allowed, invoke) {
+    const root = {};
+    for (const method of allowed) {
+        // events.subscribe is never a leaf: the composer adds the real Subscribe in its place.
+        if (method !== MethodEventsSubscribe) {
+            addLeaf(root, method, invoke);
+        }
+    }
+    return freezeTree(root);
+};
+// `agent.view.set` becomes root.agent.view.set; the names come from the allow-list itself, so no generated table is needed.
+function addLeaf(root, method, invoke) {
+    const path = method.split(METHOD_SEPARATOR);
+    const leafName = path.pop();
+    if (leafName === undefined) {
+        return;
+    }
+    const branch = ensureBranch(root, path);
+    branch[leafName] = leafFor(method, invoke);
+}
+// No generated method name is also a branch of another (test/herdr/client/scoped/namespace-tree.test.ts), so a leaf is never replaced by a branch.
+function ensureBranch(root, segments) {
+    let node = root;
+    for (const segment of segments) {
+        const existing = node[segment];
+        if (existing === undefined || isLeaf(existing)) {
+            const created = {};
+            node[segment] = created;
+            node = created;
+        }
+        else {
+            node = existing;
+        }
+    }
+    return node;
+}
+function isLeaf(node) {
+    return typeof node === TypeofKind.Function;
+}
+// The default params are an empty object, so `herdr.ping()` sends `{}` as every generated namespace does.
+function leafFor(method, invoke) {
+    return (params = {}, options) => invoke(method, params, options);
+}
+function freezeTree(node) {
+    for (const value of Object.values(node)) {
+        if (!isLeaf(value)) {
+            freezeTree(value);
+        }
+    }
+    return Object.freeze(node);
+}
+const DEFAULT_DEPS = {
+    requestTimeoutMs: defaultRequestTimeoutMs,
+    assertLongPollBounds: defaultAssertBounds,
+};
+export function createInvoke(core, allowed, deps = DEFAULT_DEPS) {
+    return async function invoke(method, params, options = {}) {
+        assertAllowed(method, allowed);
+        // The generated tree and the generic call() both pass params typed by the method name; the server checks the shape.
+        const wire = params;
+        if (!isLongPoll(method)) {
+            return core.call(method, wire, options);
+        }
+        deps.assertLongPollBounds(method, params);
+        const timeoutMs = deps.requestTimeoutMs(method, params, core.transport.timeoutMs);
+        return core.call(method, wire, withTimeout(options, timeoutMs));
+    };
+}
+/** Throws before anything is sent when the method is not in the entry's allow-list. */
+export function assertAllowed(method, allowed) {
+    if (!allowed.has(method)) {
+        throw new HerdrTransportError(ErrorText.NotAllowed(method));
+    }
+}
+function isLongPoll(method) {
+    return Object.hasOwn(LONG_POLL, method);
+}
+// The computed long-poll timeout is a default: a timeoutMs the caller set on this call wins (connect-core.callRpcOptions says the same).
+function withTimeout(options, timeoutMs) {
+    return timeoutMs === undefined || options.timeoutMs !== undefined ? options : { ...options, timeoutMs };
+}
+// One load per client: the first member used starts the import, every later one awaits the same promise.
+export function lazyStreams(core) {
+    let loaded;
+    const load = () => {
+        loaded ??= import('./streams.js').then((module) => module.createStreamMembers(core));
+        return loaded;
+    };
+    const subscribe = async (specs, options) => {
+        const members = await load();
+        return members.subscribe(specs, options);
+    };
+    const hold = async (options) => {
+        const members = await load();
+        return members.hold(options);
+    };
+    return { subscribe, watch: lazyWatch(load), hold };
+}
+// watch() is synchronous, so it returns at once; the real watch is created when iteration starts, as the real one does. close() before that ends the iteration without creating it.
+function lazyWatch(load) {
+    return function watch(options) {
+        let stopped = false;
+        let inner;
+        async function* changes() {
+            const members = await load();
+            if (stopped) {
+                return;
+            }
+            inner = members.watch(options);
+            yield* inner;
+        }
+        return {
+            close() {
+                stopped = true;
+                inner?.close();
+            },
+            [Symbol.asyncIterator]: changes,
+        };
+    };
+}
+const FULL_MEMBERS = { call: true, streams: true, hold: true };
+const STREAM_MEMBERS = { call: false, streams: true, hold: false };
+const NO_MEMBERS = { call: false, streams: false, hold: false };
+/** connect() and connectAdmin() have everything; the read-only entries stream; prompt has no streams and no call(). */
+export const ENTRY_MEMBERS = {
+    [EntryKey.client]: FULL_MEMBERS,
+    [EntryKey.admin]: FULL_MEMBERS,
+    [EntryKey.prompt]: NO_MEMBERS,
+    [EntryKey.readOnly]: STREAM_MEMBERS,
+    [EntryKey.readOnlyContent]: STREAM_MEMBERS,
+};
+/** The preset form of connectReadOnly: a fixed list with no streams and no call(). */
+export const PRESET_MEMBERS = NO_MEMBERS;
+/**
+ * Builds a public client of type T from the core and the allow-list. The tree is built from exactly `allowed`;
+ * T is the generated type of the same entry. The runtime object is assembled from the tree and the members, so its static
+ * type is asserted to T by the final cast; the contract type tests (test/types) check the members of each T.
+ * `streams` is the lazy loader of the stream members (lazy-streams.ts); tests pass their own.
+ */
+export function composeClient(core, allowed, members, streams = lazyStreams(core)) {
+    const invoke = createInvoke(core, allowed);
+    const tree = buildNamespaceTree(allowed, invoke);
+    const client = {
+        ...tree,
+        capabilities: core.capabilities,
+        serverInfo: core.serverInfo,
+        close: () => {
+            core.close();
+        },
+    };
+    if (members.call) {
+        client.call = callWith(invoke);
+    }
+    if (members.streams) {
+        // The refusals are synchronous, before anything is sent or loaded: watch() is built on events.subscribe and session.snapshot.
+        if (allowed.has(MethodEventsSubscribe)) {
+            client.events = eventsWith(tree, streams.subscribe);
+        }
+        requireAllowed(MethodEventsSubscribe, allowed);
+        requireAllowed(MethodSessionSnapshot, allowed);
+        client.watch = streams.watch;
+    }
+    if (members.hold) {
+        client.hold = streams.hold;
+    }
+    return Object.freeze(client);
+}
+function requireAllowed(method, allowed) {
+    if (!allowed.has(method)) {
+        throw new HerdrTransportError(ErrorText.NotAllowed(method));
+    }
+}
+/**
+ * composeClient, but closes the core when composition refuses (a watch on a method list without its methods), so the
+ * connection the core opened is not left live. Every connect function composes through this.
+ */
+export function composeOrClose(core, allowed, members, streams = lazyStreams(core)) {
+    try {
+        return composeClient(core, allowed, members, streams);
+    }
+    catch (error) {
+        core.close();
+        throw error;
+    }
+}
+// call() is the generic escape hatch: the same allow-list and long-poll path as every leaf, with the result typed by the method.
+function callWith(invoke) {
+    return function call(method, params, options) {
+        return invoke(method, params, options);
+    };
+}
+// The generated events branch (every event leaf except subscribe) plus the composed subscribe.
+function eventsWith(tree, subscribe) {
+    const branch = tree[TreeKey.Events];
+    return Object.freeze({ ...branch, [TreeKey.Subscribe]: subscribe });
+}
+export const connectAdmin = async function connectAdmin(options = {}) {
+    const core = await connectCore(options);
+    return composeOrClose(core, allowedMethods(ADMIN_METHODS), ENTRY_MEMBERS[EntryKey.admin], lazyStreams(core));
+};
+export const connectPrompt = async function connectPrompt(options = {}) {
+    const core = await connectCore(options);
+    return composeOrClose(core, allowedMethods(PROMPT_METHODS), ENTRY_MEMBERS[EntryKey.prompt]);
+};
+// The preset lists this entry can name. Only the list of each preset is imported, not the table of every entry.
+const PRESET_LISTS = {
+    [Presets.SessionsReader]: SESSIONS_READER_METHODS,
+};
+async function connectReadOnlyForm(options = {}) {
+    const core = await connectCore(options);
+    if (options.preset !== undefined) {
+        return composeOrClose(core, allowedMethods(PRESET_LISTS[options.preset]), PRESET_MEMBERS, lazyStreams(core));
+    }
+    const entry = options.content === true ? EntryKey.readOnlyContent : EntryKey.readOnly;
+    const base = entry === EntryKey.readOnlyContent ? READ_ONLY_CONTENT_METHODS : READ_ONLY_METHODS;
+    const allowed = allowedMethods(base, options.methods === undefined ? {} : { methods: options.methods });
+    return composeOrClose(core, allowed, ENTRY_MEMBERS[entry], lazyStreams(core));
+}
+// One implementation for the three overloads: the union return is narrowed by the overload the caller's options match.
+export const connectReadOnly = connectReadOnlyForm;

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

@@ -0,0 +1,9 @@
+import type { CreateHold, Hold } from './held.js';
+import type { CreateSubscribe, Subscribe } from './subscribe.js';
+import type { CreateWatch, WatchFn } from './watch.js';
+import type { ClientTransport, CoreClient, StreamMembers } from './types.js';
+export declare function subscribeFor(transport: ClientTransport, create?: CreateSubscribe): Subscribe;
+export declare function watchFor(subscribe: Subscribe, create?: CreateWatch): WatchFn;
+export declare function holdFor(core: CoreClient, create?: CreateHold): Hold;
+/** The three stream members of one client, built from its core. Called once, by the lazy loader, on first use. */
+export declare function createStreamMembers(core: CoreClient): StreamMembers;

package/dist/herdr/client/streams.js

@@ -0,0 +1,40 @@
+// Role: builds the stream members of one client from its transport: events.subscribe, the watch factory and hold, each with the client's resolved settings.
+// This module is the heavy half: it is loaded through a dynamic import by lazyStreams in scoped.ts, so it stays out of a client that never streams (plan 10.1 step 3).
+// Informs plan 3.3 (the transport is resolved once), plan 3.6 and HERDR-ADR-0015; contracts in subscribe.ts, watch.ts and held.ts.
+import { openDedicated } from '../wire/dedicated.js';
+import { createHold as defaultCreateHold } from './held.js';
+import { createSubscribe as defaultCreateSubscribe } from './subscribe.js';
+import { createWatch as defaultCreateWatch } from './watch.js';
+import { allowedMethods, buildNamespaceTree } from './scoped.js';
+// The factories are parameters so a test can spy on what they receive; the defaults are the real ones.
+export function subscribeFor(transport, create = defaultCreateSubscribe) {
+    return create({
+        socketPath: transport.socketPath,
+        timeoutMs: transport.timeoutMs,
+        onCall: transport.onCall,
+        onUnknown: transport.onUnknown,
+        signal: transport.closed,
+        open: openDedicated,
+    });
+}
+// watch() is built on events.subscribe and session.snapshot. Whether the client may use both is checked by compose.ts before this runs (synchronously, plan 3.4).
+export function watchFor(subscribe, create = defaultCreateWatch) {
+    return create(subscribe);
+}
+export function holdFor(core, create = defaultCreateHold) {
+    return create({
+        socketPath: core.transport.socketPath,
+        timeoutMs: core.transport.timeoutMs,
+        capabilities: core.capabilities,
+        onCall: core.transport.onCall,
+        open: openDedicated,
+        signal: core.transport.closed,
+        buildTree: buildNamespaceTree,
+        allowedMethods,
+    });
+}
+/** The three stream members of one client, built from its core. Called once, by the lazy loader, on first use. */
+export function createStreamMembers(core) {
+    const subscribe = subscribeFor(core.transport);
+    return { subscribe, watch: watchFor(subscribe), hold: holdFor(core) };
+}

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

@@ -0,0 +1,75 @@
+import { Overflow } from '../../constants.js';
+import type { Subscription } from '../generated/index.js';
+import type { DecodedFrame, OnCall, OpenDedicated, UnknownFrame } from '../wire/types.js';
+/** Bounded queue. Without it the queue is unbounded (plan 3.6). */
+export interface QueueOptions {
+    readonly max: number;
+    /** DropOldest drops the oldest queued frame; Fail ends the iterator with HerdrTransportError. */
+    readonly overflow: Overflow;
+}
+export interface SubscribeOptions {
+    /** Abort closes the subscription (same as close()). */
+    readonly signal?: AbortSignal | undefined;
+    /** How long to wait for the `subscription_started` ack; default: the client's timeoutMs. */
+    readonly ackTimeoutMs?: number | undefined;
+    readonly queue?: QueueOptions | undefined;
+    /** Called once per UnknownFrame, before it is yielded, after the client-level onUnknown (P3: counted, never dropped). */
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+}
+/**
+ * A live subscription on its own connection. Iterating yields frames in arrival order. close() (or abort) ends the
+ * iteration normally and destroys the connection. A server close ends it by throwing SubscriptionEnded; a malformed
+ * line throws HerdrTransportError. No history is replayed: frames are changes, not the present (W5).
+ */
+export interface EventSubscription extends AsyncIterable<DecodedFrame> {
+    close(): void;
+}
+/**
+ * `herdr.events.subscribe(specs, options)`: opens a dedicated connection, sends `events.subscribe`, waits for the ack
+ * (id-matched), then streams. Rejects with HerdrError on an error envelope (e.g. invalid_params for a per-pane type
+ * without pane_id, W6), HerdrTransportError on connect/ack timeout.
+ */
+export type Subscribe = (specs: readonly Subscription[], options?: SubscribeOptions) => Promise<EventSubscription>;
+/** What the client hands the subscribe factory. */
+export interface SubscribeDeps {
+    readonly socketPath: string;
+    /** The client's resolved timeout (ClientTransport.timeoutMs); the ack timeout default. */
+    readonly timeoutMs: number;
+    readonly onCall?: OnCall | undefined;
+    /** The client-level hook (ClientTransport.onUnknown); called before SubscribeOptions.onUnknown. */
+    readonly onUnknown?: ((frame: UnknownFrame) => void) | undefined;
+    /** The client close signal (ClientTransport.closed): when it aborts, every subscription of this client closes. */
+    readonly signal: AbortSignal;
+    /** Injected so tests can stub the connection (default wire/dedicated.ts openDedicated). */
+    readonly open: OpenDedicated;
+}
+/** Builds the subscribe function of one client. Implemented by client/subscribe/subscribe.ts (P4a). */
+export type CreateSubscribe = (deps: SubscribeDeps) => Subscribe;
+export declare const SubscribeText: {
+    readonly MalformedPush: 'events.subscribe: malformed push line';
+    readonly QueueFull: (max: number) => string;
+};
+export interface CombinedSignal {
+    readonly signal: AbortSignal;
+    readonly dispose: () => void;
+}
+export declare function anySignal(...sources: (AbortSignal | undefined)[]): CombinedSignal;
+export type UnknownHook = (frame: UnknownFrame) => void;
+export declare function deliverUnknown(frame: UnknownFrame, hooks: readonly (UnknownHook | undefined)[]): void;
+export declare class FrameQueue<T> {
+    private readonly items;
+    private readonly waiters;
+    private readonly max;
+    private readonly overflow;
+    private readonly onFail;
+    private ended;
+    private failure;
+    constructor(options: QueueOptions | undefined, onFail?: () => void);
+    push(value: T): void;
+    next(): Promise<IteratorResult<T>>;
+    end(): void;
+    fail(reason: unknown): void;
+    private isClosed;
+}
+export declare function subscriptionOver(queue: FrameQueue<DecodedFrame>, close: () => void): EventSubscription;
+export declare const createSubscribe: CreateSubscribe;

package/dist/herdr/client/subscribe.js

@@ -0,0 +1,208 @@
+// Role: subscriptions: one dedicated connection per subscribe, its frame queue, close signals and unknown-frame delivery.
+// Informs HERDR-ADR-0017, HERDR-ADR-0007, HERDR-ADR-0016, plan 3.6; merged by HERDR-ADR-0021 from types.ts, constants.ts, close-signals.ts, deliver-unknown.ts, frame-queue.ts, subscription.ts, subscribe.ts.
+import { Overflow, UNKNOWN_EVENT } from '../../constants.js';
+import { HerdrTransportError, SubscriptionEnded } from '../errors.js';
+import { MethodEventsSubscribe } from '../generated/names/method.js';
+import { decodePush } from '../wire/push-decoder.js';
+export const SubscribeText = {
+    MalformedPush: 'events.subscribe: malformed push line',
+    QueueFull: (max) => `subscription queue is full (max ${max})`,
+};
+export function anySignal(...sources) {
+    const controller = new AbortController();
+    const attached = sources.filter(isAttached);
+    const onAbort = () => {
+        dispose();
+        controller.abort();
+    };
+    const dispose = () => {
+        for (const source of attached) {
+            source.removeEventListener('abort', onAbort);
+        }
+    };
+    for (const source of attached) {
+        if (source.aborted) {
+            onAbort();
+            break;
+        }
+        source.addEventListener('abort', onAbort);
+    }
+    return { signal: controller.signal, dispose };
+}
+function isAttached(source) {
+    return source !== undefined;
+}
+export function deliverUnknown(frame, hooks) {
+    for (const hook of hooks) {
+        runHook(hook, frame);
+    }
+}
+// Best effort, like reportCall: the observer's failure never reaches the consumer.
+function runHook(hook, frame) {
+    if (hook === undefined) {
+        return;
+    }
+    try {
+        hook(frame);
+    }
+    catch {
+        // The hook is an observer; its exception is not the subscription's error.
+    }
+}
+const END_OF_ITERATION = { done: true, value: undefined };
+const NO_FAIL_HOOK = () => undefined;
+export class FrameQueue {
+    items = [];
+    waiters = [];
+    max;
+    overflow;
+    onFail;
+    ended = false;
+    failure = undefined;
+    // onFail runs once, when the queue fails, so the owner can release what feeds it (the connection).
+    constructor(options, onFail = NO_FAIL_HOOK) {
+        this.max = options?.max;
+        this.overflow = options?.overflow ?? Overflow.DropOldest;
+        this.onFail = onFail;
+    }
+    // Hands the frame to a waiting next(), or queues it; a full queue fails (Fail) or drops its oldest frame (DropOldest).
+    push(value) {
+        if (this.isClosed()) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            waiter.resolve({ value, done: false });
+            return;
+        }
+        const max = this.max;
+        if (max !== undefined && this.items.length >= max) {
+            if (this.overflow === Overflow.Fail) {
+                this.fail(new HerdrTransportError(SubscribeText.QueueFull(max)));
+                return;
+            }
+            this.items.shift();
+        }
+        this.items.push({ value });
+    }
+    // The next queued frame; queued frames are read before an end or a failure is seen.
+    next() {
+        const entry = this.items.shift();
+        if (entry !== undefined) {
+            return Promise.resolve({ value: entry.value, done: false });
+        }
+        if (this.failure !== undefined) {
+            return Promise.reject(this.failure.reason);
+        }
+        if (this.ended) {
+            return Promise.resolve(END_OF_ITERATION);
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    // No more frames: the iteration finishes normally once the queued frames are read.
+    end() {
+        if (this.isClosed()) {
+            return;
+        }
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve(END_OF_ITERATION);
+        }
+    }
+    // The iteration throws `reason` once the queued frames are read; the owner is told once so it can release the feed.
+    fail(reason) {
+        if (this.isClosed()) {
+            return;
+        }
+        this.failure = { reason };
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.reject(reason);
+        }
+        this.onFail();
+    }
+    isClosed() {
+        return this.ended || this.failure !== undefined;
+    }
+}
+export function subscriptionOver(queue, close) {
+    const iterator = {
+        next: () => queue.next(),
+        return: async () => {
+            close();
+            return { done: true, value: undefined };
+        },
+    };
+    return {
+        close,
+        [Symbol.asyncIterator]: () => iterator,
+    };
+}
+export const createSubscribe = function createSubscribe(deps) {
+    return function subscribe(specs, options = {}) {
+        return openSubscription(deps, specs, options);
+    };
+};
+async function openSubscription(deps, specs, options) {
+    const scope = anySignal(deps.signal, options.signal);
+    const connection = await openStream(deps, scope);
+    const queue = new FrameQueue(options.queue, () => {
+        connection.destroy();
+    });
+    const stream = { queue, hooks: [deps.onUnknown, options.onUnknown] };
+    connection.onPush((line) => {
+        routePush(line, stream);
+    });
+    void connection.ended.then((end) => {
+        settleEnd(end, queue, scope);
+    });
+    try {
+        await connection.request(MethodEventsSubscribe, { subscriptions: [...specs] }, { timeoutMs: options.ackTimeoutMs ?? deps.timeoutMs });
+    }
+    catch (error) {
+        connection.destroy();
+        throw error;
+    }
+    return subscriptionOver(queue, () => {
+        queue.end();
+        connection.destroy();
+    });
+}
+async function openStream(deps, scope) {
+    try {
+        return await deps.open({ socketPath: deps.socketPath, signal: scope.signal, onCall: deps.onCall });
+    }
+    catch (error) {
+        scope.dispose();
+        throw error;
+    }
+}
+// A frame is decoded, offered to the unknown hooks when it is unknown, then queued. A line that is not a push fails the queue, which releases the connection.
+function routePush(line, stream) {
+    const frame = decodePush(line);
+    if (frame === undefined) {
+        stream.queue.fail(new HerdrTransportError(SubscribeText.MalformedPush));
+        return;
+    }
+    if (isUnknownFrame(frame)) {
+        deliverUnknown(frame, stream.hooks);
+    }
+    stream.queue.push(frame);
+}
+// The connection ended: a server close is an error for the caller, a cause is that error, anything else (close, abort, client close) is a normal end.
+function settleEnd(end, queue, scope) {
+    scope.dispose();
+    if (end.cause !== undefined) {
+        queue.fail(end.cause);
+        return;
+    }
+    if (end.byServer) {
+        queue.fail(new SubscriptionEnded(MethodEventsSubscribe));
+        return;
+    }
+    queue.end();
+}
+function isUnknownFrame(frame) {
+    return frame.event === UNKNOWN_EVENT;
+}