@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/synapse.d.ts

@@ -0,0 +1,89 @@
+import { type Age, type ClockInfo, type ErrorBody, type LocalTime, type ProjectSnapshot, type ServiceContract, type TimeOffsets, type TopicContract } from "@synapse-sdk/core";
+import { Node } from "./node.ts";
+import { StoreHandleImpl } from "./store.ts";
+import { type Warn } from "./topics.ts";
+import type { CallEvent, CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, Info, Metrics, Notice, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, View, ViewOptions } from "./types.ts";
+/** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
+export declare const FIRST_CONNECT_GIVE_UP_MS = 30000;
+export declare class Synapse implements AsyncDisposable {
+    #private;
+    readonly opts: ConnectOptions;
+    warn: Warn;
+    constructor(opts: ConnectOptions);
+    /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
+    static connect(opts: ConnectOptions): Promise<Synapse>;
+    /** Connects (once; later calls return the same promise). Resolves once a session is established. */
+    connect(): Promise<this>;
+    get node(): Node;
+    get status(): ConnectionState;
+    get connected(): boolean;
+    /** Called on every change of the connection state; returns the unsubscribe. */
+    watchStatus(cb: (s: ConnectionState) => void): () => void;
+    /** Resolves on the next connected session (at once if connected); rejects once the node ended. */
+    whenConnected(): Promise<void>;
+    /** Declares a new target (broker, identity); resolves once connected to it (or rejects with why not). `null` disconnects for good. */
+    setTarget(target: ConnectTarget | null): Promise<void>;
+    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended. */
+    /** During the first `connect()` it ends that attempt: the node ends `closed` and `connect()` rejects `not_connected`. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Resolves once the node has ended (closed, failed, or the policy gave up). */
+    get ended(): Promise<void>;
+    info(): Info;
+    metrics(): Metrics;
+    /** Broker notices addressed to this node (an error body on `res` without a call). */
+    onNotice(cb: (n: ErrorBody) => void): () => void;
+    /** `promoted`/`demoted` notices (WP §3.5). */
+    onProjectNotice(cb: (n: Notice) => void): () => void;
+    nowUs(): number;
+    clock(): ClockInfo;
+    timeOffsets(): TimeOffsets;
+    /** A publisher stamp in our clock (WP §7.4), when the offsets allow it. */
+    toLocalUs(tUs: number, dom: string): LocalTime | undefined;
+    /** How old a message is now, in our clock. */
+    ageUs(env: {
+        tUs: number;
+        dom: string;
+    }): Age | undefined;
+    /** A publisher of `topic`; resolves once the runtime admitted it on the current session (a refusal is asked again, paced, warned). */
+    publisher<TIn, TOut>(topic: TopicContract<TIn, TOut>): Promise<Publisher<TIn>>;
+    publisher<TIn = unknown>(topic: string): Promise<Publisher<TIn>>;
+    /** A subscription to `topic` (every publisher the catalog lists but ourselves); its follow task starts now. */
+    subscribe<TIn, TOut>(topic: TopicContract<TIn, TOut>, opts?: SubscribeOptions): Subscription<TOut>;
+    subscribe<TOut = unknown>(topic: string, opts?: SubscribeOptions): Subscription<TOut>;
+    /** The topic's latest value as a cell (SDK §4.3); subscribed while someone listens. */
+    view<TIn, TOut, S = TOut>(topic: TopicContract<TIn, TOut>, opts?: ViewOptions<TOut, S>): View<S>;
+    view<TOut = unknown, S = TOut>(topic: string, opts?: ViewOptions<TOut, S>): View<S>;
+    /** Starts a call on the current session (SDK §5.2): `await` it for the result, or read `updates()` first. `not_connected` between sessions. */
+    call<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): Run<U, R>;
+    call<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): Run<U, R>;
+    /** The call's updates and result as one ordered stream; `break` cancels. */
+    callStream<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, args: TArgs, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
+    callStream<U = unknown, R = unknown>(svc: string, args?: unknown, opts?: CallOptions<U>): AsyncGenerator<CallEvent<U, R>, void, undefined>;
+    /** Registers `handler` as the provider of `svc`; resolves once the runtime lists us on the current session. One provider per service path per node. */
+    serve<TArgs, TInput, U, R>(svc: ServiceContract<TArgs, TInput, U, R>, handler: ServeHandler<TInput, U, R>, opts?: ServeOptions): Promise<Registration>;
+    serve<I = unknown, U = unknown, R = unknown>(svc: string, handler: ServeHandler<I, U, R>, opts?: ServeOptions): Promise<Registration>;
+    /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
+    store(name: string, opts?: StoreOptions): Promise<StoreHandle>;
+    /** The runtime's `config` namespace (operators write it). */
+    config(opts?: StoreOptions): Promise<StoreHandle>;
+    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    scene(): Promise<SceneHandle>;
+    /** The runtime's catalogs as the current session last read them; empty between sessions. */
+    get catalog(): Catalog;
+    /** Called when either catalog changes on the current session. */
+    watchCatalog(cb: (c: Catalog) => void): () => void;
+    /** The project state the current session last read (WP §3.5); `undefined` between sessions or before the first snapshot. */
+    project(): ProjectSnapshot | undefined;
+    watchProject(cb: (p: ProjectSnapshot | undefined) => void): () => void;
+    /** `synapse/project/activate {id}`: activates `id` (or joins it when active); promoted to operator. */
+    activateProject(id: string): Promise<ProjectSnapshot>;
+    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    deactivateProject(): Promise<ProjectSnapshot>;
+    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    joinProject(as?: "operator"): Promise<ProjectSnapshot>;
+    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    leaveProject(): Promise<ProjectSnapshot>;
+    getProject(): Promise<ProjectSnapshot>;
+}
+export type { Envelope, StoreHandleImpl };

package/dist/synapse.js

@@ -0,0 +1,256 @@
+// `Synapse` (SDK §2–§9): the public face of one node. It owns nothing the modules do not: the node's
+// loop (`node.ts`) drives sessions; publishers, registrations, subscriptions and namespaces are their
+// own tasks, told about sessions by the loop; every fact about the world is read from the current
+// `Session` (the runtime's statement) at the moment it is asked for, never copied here.
+import { ClockSync, SynapseError, ageOf, defaultDomId, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, toLocalUs, } from "@synapse-sdk/core";
+import { callStream, startOn } from "./calls.js";
+import { Node, resolveTarget, startNode } from "./node.js";
+import { ServiceRegistration } from "./serve.js";
+import { openScene } from "./scene.js";
+import { Namespace, StoreHandleImpl, openStore } from "./store.js";
+import { PublisherHandle, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
+import { TopicView } from "./view.js";
+/** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
+export const FIRST_CONNECT_GIVE_UP_MS = 30_000;
+/** The descriptor a publisher of `contract` on node `n` declares (as `TopicPublisher` builds it: a `fec` symbol size of 0 is the node's). */
+function wantedDesc(contract, n) {
+    const d = contract.desc(n.dom);
+    if (d.delivery === "datagram" && d.fec && d.fec.symbol_size === 0)
+        d.fec = { ...d.fec, symbol_size: fecSymbolSizeFor(n.knobs.maxDatagram) };
+    return d;
+}
+/** The parts of a descriptor two publishers of one topic on one node must agree on, as text (also for the refusal's message). */
+function descKey(d) {
+    return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null, layout: d.layout ?? null });
+}
+export class Synapse {
+    opts;
+    #node;
+    #connecting;
+    #starting;
+    #publishers = new Map();
+    #stores = new Map();
+    warn;
+    constructor(opts) {
+        this.opts = opts;
+        this.warn = msg => console.warn(`[synapse] ${msg}`);
+    }
+    /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
+    static connect(opts) { return new Synapse(opts).connect(); }
+    /** Connects (once; later calls return the same promise). Resolves once a session is established. */
+    connect() {
+        this.#connecting ??= (async () => {
+            const started = startNode(this.opts, FIRST_CONNECT_GIVE_UP_MS);
+            // The node as soon as its loop runs (or none: the options were refused), for a `close()` during the first dial.
+            this.#starting = started.then(s => s.node, () => undefined);
+            const { node, connected } = await started;
+            await connected;
+            this.#node = node;
+            return this;
+        })();
+        return this.#connecting;
+    }
+    get node() {
+        if (!this.#node)
+            throw new SynapseError("not_connected", "connect() has not completed");
+        return this.#node;
+    }
+    #session() { return this.node.currentSession(); }
+    // ------------------------------------------------------------------------------ lifecycle
+    get status() { return this.#node?.state() ?? { status: "connecting", attempt: 1 }; }
+    get connected() { return this.#node?.isConnected ?? false; }
+    /** Called on every change of the connection state; returns the unsubscribe. */
+    watchStatus(cb) { return this.node.link.subscribe(() => cb(this.node.state())); }
+    /** Resolves on the next connected session (at once if connected); rejects once the node ended. */
+    whenConnected() {
+        const n = this.node;
+        if (n.isConnected)
+            return Promise.resolve();
+        if (n.isEnded)
+            return Promise.reject(new SynapseError("not_connected", "node closed"));
+        return new Promise((resolve, reject) => {
+            const un = n.link.subscribe(l => { if (l.status === "connected") {
+                un();
+                resolve();
+            } });
+            // The node's end settles it (a resolved promise ignores the later reject).
+            void n.ended.promise.then(() => { un(); reject(new SynapseError("not_connected", "node closed")); });
+        });
+    }
+    /** Declares a new target (broker, identity); resolves once connected to it (or rejects with why not). `null` disconnects for good. */
+    setTarget(target) { return this.node.setTarget(target ? resolveTarget(this.node, target) : undefined); }
+    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended. */
+    /** During the first `connect()` it ends that attempt: the node ends `closed` and `connect()` rejects `not_connected`. */
+    async close() {
+        const n = this.#node ?? (await this.#starting);
+        if (n)
+            await n.close();
+    }
+    async [Symbol.asyncDispose]() { await this.close(); }
+    /** Resolves once the node has ended (closed, failed, or the policy gave up). */
+    get ended() { return this.node.ended.promise; }
+    info() {
+        const n = this.node;
+        const id = n.target.get().identity;
+        const s = n.currentSession();
+        return { name: id.name ?? "", type: id.type, userId: id.user_id, prefix: s?.prefix ?? "", role: s?.role ?? "observer", dom: n.dom, brokerDom: s?.hello.dom ?? "", brokerVersion: s?.hello.broker_version ?? "", robot: s?.hello.robot ?? "", url: s?.url ?? n.target.get().dial?.url ?? "" };
+    }
+    metrics() { const n = this.node; return { sessions: n.epochs, reconnects: n.reconnects, callsSent: n.callsSent, callsAnswered: n.callsAnswered }; }
+    /** Broker notices addressed to this node (an error body on `res` without a call). */
+    onNotice(cb) { this.node.notices.add(cb); return () => { this.node.notices.delete(cb); }; }
+    /** `promoted`/`demoted` notices (WP §3.5). */
+    onProjectNotice(cb) { this.node.projectNotices.add(cb); return () => { this.node.projectNotices.delete(cb); }; }
+    // ---------------------------------------------------------------------------------- clock
+    nowUs() { return nowUs(); }
+    clock() { const s = this.#session(); return s ? s.clock.get() : new ClockSync(this.node.dom.id, "", 0).info(); }
+    timeOffsets() { return this.#session()?.timeOffsets.get() ?? {}; }
+    /** A publisher stamp in our clock (WP §7.4), when the offsets allow it. */
+    toLocalUs(tUs, dom) { const s = this.#session(); return s ? toLocalUs(s.clock.get(), s.timeOffsets.get(), tUs, dom) : undefined; }
+    /** How old a message is now, in our clock. */
+    ageUs(env) { const s = this.#session(); return s ? ageOf(s.clock.get(), s.timeOffsets.get(), env.tUs, env.dom, nowUs()) : undefined; }
+    async publisher(topic) {
+        const contract = resolveTopic(topic);
+        const n = this.node;
+        const name = contract.name;
+        let p;
+        let held;
+        for (;;) {
+            const entry = this.#publishers.get(name);
+            if (!entry) {
+                // Looked up and inserted in one step (no await between): a concurrent `publisher()` for the
+                // same name finds this entry and waits for it instead of making a second one.
+                const made = wasmFor(contract).then(wasm => new TopicPublisher(n, contract, n.knobs.maxDatagram, wasm, this.warn));
+                this.#publishers.set(name, made);
+                try {
+                    p = (await made);
+                }
+                catch (e) {
+                    if (this.#publishers.get(name) === made)
+                        this.#publishers.delete(name);
+                    throw e;
+                }
+                held = made;
+                break;
+            }
+            const live = await entry.catch(() => undefined);
+            // Gone meanwhile (its making failed, or its last handle closed): look again.
+            if (!live || this.#publishers.get(name) !== entry)
+                continue;
+            // A second one with another descriptor is not this one, and its intent never reached the runtime.
+            const have = descKey(live.desc), want = descKey(wantedDesc(contract, n));
+            if (have !== want)
+                throw new SynapseError("invalid_input", `topic ${name}: a publisher with a different descriptor exists on this node (live: ${have}; asked: ${want})`);
+            p = live;
+            held = entry;
+            break;
+        }
+        const h = new PublisherHandle(p, () => { if (this.#publishers.get(name) === held)
+            this.#publishers.delete(name); });
+        try {
+            await h.ready();
+        }
+        catch (e) {
+            h.close();
+            throw e;
+        }
+        return h;
+    }
+    subscribe(topic, opts = {}) {
+        const contract = resolveTopic(topic);
+        return new TopicSubscription(this.node, contract, opts, this.warn);
+    }
+    view(topic, opts = {}) {
+        const contract = resolveTopic(topic);
+        const { staleTime: _s, select: _sel, ...subOpts } = opts;
+        return new TopicView(this.node, () => new TopicSubscription(this.node, contract, subOpts, this.warn), opts, () => { });
+    }
+    call(svc, args = {}, opts = {}) {
+        const s = this.#session();
+        if (!s)
+            throw new SynapseError("not_connected", "no session: the call was not sent");
+        const contract = isServiceContract(svc) ? svc : undefined;
+        return startOn(this.node, s, serviceName(svc), args, opts, contract);
+    }
+    callStream(svc, args = {}, opts = {}) {
+        return callStream(this.call(svc, args, opts));
+    }
+    async serve(svc, handler, opts = {}) {
+        const n = this.node;
+        const name = serviceName(svc);
+        const contract = isServiceContract(svc) ? svc : undefined;
+        const card = contract ? contract.card() : { name, streaming: true, cancelable: true, min_role: opts.minRole ?? "agent", ...(opts.description ? { description: opts.description } : {}) };
+        if (opts.minRole)
+            card.min_role = opts.minRole;
+        if (opts.description)
+            card.description = opts.description;
+        if (this.#registrations.has(name))
+            throw new SynapseError("already_registered", `${name}: this node already provides it (one provider per service path)`);
+        const reg = new ServiceRegistration(n, name, card, contract, handler, this.warn);
+        this.#registrations.set(name, reg);
+        void reg.handle.exited.promise.then(() => { if (this.#registrations.get(name) === reg)
+            this.#registrations.delete(name); });
+        try {
+            await reg.ready();
+        }
+        catch (e) {
+            reg.unregister();
+            throw e;
+        }
+        return reg;
+    }
+    #registrations = new Map();
+    // ---------------------------------------------------------------------------------- store
+    /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
+    store(name, opts = {}) { return openStore(this.node, this.#stores, name, opts, this.warn); }
+    /** The runtime's `config` namespace (operators write it). */
+    config(opts = {}) { return this.store("config", opts); }
+    // ---------------------------------------------------------------------------------- scene
+    #scenes = { current: undefined };
+    /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
+    scene() { return openScene(this.node, this.#scenes, this.warn); }
+    // -------------------------------------------------------------------------------- catalog
+    /** The runtime's catalogs as the current session last read them; empty between sessions. */
+    get catalog() {
+        const s = this.#session();
+        const topics = s?.topics.get().topics ?? {};
+        const services = s?.services.get().services ?? {};
+        return { topics, services, describe: name => services[name]?.card };
+    }
+    /** Called when either catalog changes on the current session. */
+    watchCatalog(cb) {
+        let un = [];
+        const bind = () => {
+            for (const u of un)
+                u();
+            un = [];
+            const s = this.#session();
+            if (!s)
+                return;
+            un.push(s.topics.subscribe(() => cb(this.catalog)), s.services.subscribe(() => cb(this.catalog)));
+        };
+        bind();
+        const unLink = this.node.link.subscribe(() => { bind(); cb(this.catalog); });
+        return () => { unLink(); for (const u of un)
+            u(); };
+    }
+    // -------------------------------------------------------------------------------- project
+    /** The project state the current session last read (WP §3.5); `undefined` between sessions or before the first snapshot. */
+    project() { return this.#session()?.project.get(); }
+    watchProject(cb) {
+        let un;
+        const bind = () => { un?.(); un = this.#session()?.project.subscribe(p => cb(p)); };
+        bind();
+        const unLink = this.node.link.subscribe(() => { bind(); cb(this.project()); });
+        return () => { unLink(); un?.(); };
+    }
+    #projectCall(op, args) { return this.call(`synapse/project/${op}`, args).result; }
+    /** `synapse/project/activate {id}`: activates `id` (or joins it when active); promoted to operator. */
+    activateProject(id) { return this.#projectCall("activate", { id }); }
+    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    deactivateProject() { return this.#projectCall("deactivate", {}); }
+    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    joinProject(as = "operator") { return this.#projectCall("join", { as }); }
+    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    leaveProject() { return this.#projectCall("leave", {}); }
+    getProject() { return this.#projectCall("get", {}); }
+}

package/dist/topics.d.ts

@@ -0,0 +1,136 @@
+import * as Moq from "@moq/net";
+import { type FecParams, type FecWasm, type MediaFrame, type TopicContract, type TrackDesc, type Tlv } from "@synapse-sdk/core";
+import { Handle, type Event as HandleEvent, type Intent } from "./channel.ts";
+import { type FecPubStats } from "./fec.ts";
+import type { Node } from "./node.ts";
+import { type Session } from "./session.ts";
+import type { Envelope, PublishOptions, Publisher, PublisherStats, SubStats, SubscribeOptions, Subscription, Verdict } from "./types.ts";
+export type Warn = (msg: string) => void;
+/** The publisher shared by every `publisher(topic)` handle of one topic on this node. */
+export declare class TopicPublisher<TIn, TOut> implements Intent {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<TIn, TOut>;
+    private readonly wasm;
+    readonly warn: Warn;
+    readonly name: string;
+    readonly registerSvc = "synapse/topic/register";
+    readonly unregisterSvc = "synapse/topic/unregister";
+    readonly desc: TrackDesc;
+    readonly fecParams: FecParams | undefined;
+    readonly fecStats: FecPubStats | undefined;
+    published: number;
+    droppedDisconnected: number;
+    handles: number;
+    readonly handle: Handle;
+    constructor(node: Node, contract: TopicContract<TIn, TOut>, maxDatagram: number, wasm: FecWasm | undefined, warn: Warn);
+    get verdict(): Verdict;
+    get isBound(): boolean;
+    registerArgs(bind: string): unknown;
+    unregisterArgs(bind: string): unknown;
+    /** Admitted: the broadcast is created, the descriptor written, the data track made, then announced (WP §7.1). */
+    install(s: Session, bind: string, _mailbox: (e: HandleEvent) => void): void;
+    retract(): void;
+    setVerdict(v: Verdict): void;
+    /**
+     * Publishes one frame (SDK §13: synchronous, never awaits the network). While nothing is installed
+     * (between sessions, a refused register being asked again) the frame is dropped and counted. A
+     * `stream` frame over moq's cap, a plain datagram over the session's datagram size, or a `fec`
+     * frame the codec refuses is refused (`invalid_input`) without taking a `seq`.
+     */
+    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
+    /** The typed form: validates against the contract's schema, encodes (msgpack, or the bytes of a raw topic). */
+    publish(value: TIn, opts?: PublishOptions): void;
+    stats(): PublisherStats;
+}
+/** The application's handle: the last one closed ends the publisher's task (`unregister`). */
+export declare class PublisherHandle<TIn, TOut> implements Publisher<TIn> {
+    #private;
+    private readonly p;
+    private readonly onLast;
+    constructor(p: TopicPublisher<TIn, TOut>, onLast: () => void);
+    get topic(): string;
+    get verdict(): Verdict;
+    ready(): Promise<void>;
+    publish(value: TIn, opts?: PublishOptions): void;
+    /** Any frame type and TLVs (`MEDIA` with `STAGES`, WP §4); raw topics only. */
+    publishFrame(type: number, flags: number, tUs: number, tlvs: Tlv[], body: Uint8Array): void;
+    /** `tUs` 0 = capture now (as the Rust client stamps it). */
+    publishMedia(f: MediaFrame): void;
+    stats(): PublisherStats;
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Resolves the codec a `fec` topic needs (once per process). */
+export declare function wasmFor(contract: TopicContract<unknown, unknown>): Promise<FecWasm | undefined>;
+/** What a source gives when its track ended. */
+declare const END: unique symbol;
+/**
+ * One plain publisher the read takes from (Rust `Source`). A stream source is read synchronously
+ * by `next()` (`tryRecvGroup` / `tryReadFrame`, as Rust's poll); when nothing is buffered it holds
+ * exactly one pending read (`recvGroup` / `readFrame`) as the wake, whose result is the first item
+ * of the next drain. A datagram source has one reader (one `recvDatagram` at a time) filling
+ * `held`: latest mode keeps one (the newest `seq`), every-message mode at most `DATAGRAM_RING`.
+ */
+interface Source {
+    path: string;
+    prefix: string;
+    publisher: string;
+    dom: string;
+    /** The request for the publisher's broadcast: closed with the source. */
+    req: Moq.Origin.Requesting;
+    sub: Moq.Track.Subscriber;
+    /** Read as a stream (groups of frames) or as datagrams: the catalog's delivery for the topic. */
+    stream: boolean;
+    /** A stream source: the group being read. */
+    group: Moq.Group.Consumer | undefined;
+    /** A stream source: the pending read that wakes the read when nothing is buffered. */
+    wait: Promise<void> | undefined;
+    /** A stream source: what that pending read gave (a frame, or the track's end), taken first. */
+    ready: Uint8Array | typeof END | undefined;
+    /** A datagram source: the datagrams its reader took and the read has not. */
+    held: Uint8Array[];
+    /** A datagram source in latest mode: the `seq` of the one held. */
+    heldSeq: number | undefined;
+    /** A datagram source: its reader saw the track end; the end is given once `held` is drained. */
+    done: boolean;
+    /** The `seq` last returned (latest mode): not newer is superseded. */
+    last: number | undefined;
+    ended: boolean;
+}
+export declare class TopicSubscription<T> implements Subscription<T> {
+    #private;
+    readonly node: Node;
+    readonly contract: TopicContract<unknown, T>;
+    readonly opts: SubscribeOptions;
+    readonly warn: Warn;
+    readonly topic: string;
+    readonly stats: SubStats;
+    readonly latest: boolean;
+    constructor(node: Node, contract: TopicContract<unknown, T>, opts: SubscribeOptions, warn: Warn);
+    get signal(): AbortSignal;
+    get ownDom(): string;
+    /** The follow task hands a plain publisher here (a datagram source's reader starts); the waiting `next()` is woken. */
+    addSource(src: Source): void;
+    /** The publisher leaves the read: its subscription and request are closed, a payload it gave is never returned. */
+    removeSource(src: Source): void;
+    /** A `fec` follower's frame: latest mode replaces the publisher's pending one. */
+    pushFec(env: Envelope<T>): void;
+    dropFecOf(publisher: string): void;
+    /** A new session (or none): the `fec` frames and a batch held by `throttleMs` are the previous session's and go. */
+    clearFec(): void;
+    /** The decoding step: header facts plus the body through the contract, or `mismatch` and dropped. */
+    envelope(payload: Uint8Array, publisher: string, dom: string): Envelope<T> | undefined;
+    /**
+     * The next batch, never empty; `undefined` once the subscription or the node ended. Drains what
+     * every source has ready, synchronously (at most `DRAIN_PER_READ` per source), and the `fec`
+     * frames; with nothing to return it waits for a source's pending read or reader, a `fec` frame,
+     * a change of the set or the end of a `throttleMs` interval, and drains again.
+     */
+    next(): Promise<Envelope<T>[] | undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<Envelope<T>[], void, undefined>;
+    /** Ends the subscription: the follow task stops, every track is closed, a pending `next()` returns `undefined`. */
+    unsubscribe(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};