@loams/client 0.0.0-stage → 0.1.0

package/dist/loams.js

@@ -0,0 +1,203 @@
+// The `Loams` object: one client with namespaced modules (design §44 §7.1).
+//
+//   const loams = new Loams({ endpoint, auth: apiKey(process.env.LOAMS_API_KEY) });
+//   const info = await loams.instance.getInstance({});
+//   for await (const t of loams.live.watch({ start: { case: 'initial', value: querySet } })) {}
+//
+// What is generated and what is hand-written, once more, because it decides
+// where a change goes. The **module surface** is generated: `gen/facade.ts` has
+// one interface per annotated service and one method per `FacadeOptions`
+// call, with the generated message types, and `MODULES` says which service and
+// which retry class each call has. The **runtime** behind those methods is
+// hand-written, once, in `runtime/`: transport, credentials, retry, errors,
+// tokens, pagination, streams. This file is the thin join — it reads the
+// generated table, builds one object per module out of it, and hands every call
+// to the same invoker. It contains no method names and no RPC paths, which is
+// why annotating a proto is enough to add an SDK method.
+import { Code } from '@connectrpc/connect';
+import { MODULES, PROTO_PACKAGES, PROTO_REV, SERVICE_DESCRIPTORS, } from './gen/facade.js';
+import { CallInvoker } from './runtime/call.js';
+import { ConsistencySession } from './runtime/consistency.js';
+import { LoamsError } from './runtime/errors.js';
+import { paginate } from './runtime/pagination.js';
+import { SystemApi } from './system.js';
+import { DEFAULT_MAX_RETRIES } from './runtime/retry.js';
+import { apiKey } from './runtime/token-source.js';
+import { createLoamsTransport } from './runtime/transports.js';
+import { watch } from './runtime/streams.js';
+/** One SDK, over one instance. */
+export class Loams {
+    /** `loams.instance` — what this instance is, and who the caller is. */
+    instance;
+    /** `loams.live` — the live sync session half, and `loams.live.admin`.
+     * Its package is `unstable`. */
+    live;
+    /** `loams.tables` — the table half of the same service (design §44 §7.2). */
+    tables;
+    /** `loams.admin` — org, projects, agents, keys and audit. */
+    admin;
+    /** `loams.auth` — sessions and sign-in. */
+    auth;
+    /** The module catalogue, feature detection and the version check. */
+    system;
+    /** Every generated module, by its dotted name (`'live.admin'`): the
+     * catalogue a caller iterates. The same objects are reachable as
+     * properties, `loams.live.admin` for `'live.admin'`. */
+    modules;
+    #invoker;
+    #consistency;
+    constructor(options) {
+        // The endpoint lives on the transport, which is where connect-es reads it.
+        const transport = options.transport ??
+            createLoamsTransport({ baseUrl: options.endpoint, ...options.transportOptions });
+        const tokenSource = options.auth === undefined
+            ? undefined
+            : typeof options.auth === 'string'
+                ? apiKey(options.auth)
+                : options.auth;
+        // The session store is built first so the invoker can hold it: a call
+        // that asks for the session's consistency token reads and records through
+        // the same store the client exposes.
+        this.#consistency = options.sessionConsistency === true ? new ConsistencySession() : undefined;
+        this.#invoker = new CallInvoker(transport, tokenSource, options.maxRetries ?? DEFAULT_MAX_RETRIES, this.#consistency);
+        this.modules = buildModules(this.#invoker);
+        const tree = nestModules(this.modules);
+        this.instance = tree.instance;
+        this.live = tree.live;
+        this.tables = tree.tables;
+        this.admin = tree.admin;
+        this.auth = tree.auth;
+        this.system = new SystemApi((request, callOptions) => this.instance.getInstance(request, callOptions), {
+            endpoint: options.endpoint,
+            maxRetries: options.maxRetries,
+            timeoutMs: options.timeoutMs,
+        });
+    }
+    /** The session consistency token store, when `sessionConsistency` is on. */
+    get consistency() {
+        return this.#consistency;
+    }
+    /** The generated module bindings, as the SDK sees them. */
+    get bindings() {
+        return MODULES;
+    }
+    /** Every item of a paged call (D617's iterator).
+     *
+     * `loams.paginate('collections', 'listCollections', { namespace })`. The
+     * per-call alias §44 §7.4 sketches (`loams.collections.listAll`) arrives with
+     * the first paged RPC, when there is a generated signature to hang it on;
+     * until then this is the same iterator under its module and call name.
+     */
+    paginate(module, call, request, options = {}) {
+        const binding = this.binding(module, call);
+        const method = this.modules[module];
+        const fn = method?.[call];
+        if (typeof fn !== 'function') {
+            throw new LoamsError(`loams.${module} has no call ${call}`, { code: Code.Internal });
+        }
+        return paginate(binding, fn, request, options);
+    }
+    /** A server stream that reconnects from its cursor (runtime contract R7). */
+    stream(module, call, request, options) {
+        const binding = this.binding(module, call);
+        const method = this.modules[module];
+        const fn = method?.[call];
+        if (typeof fn !== 'function') {
+            throw new LoamsError(`loams.${module} has no call ${call}`, { code: Code.Internal });
+        }
+        return watch(binding, fn, request, options);
+    }
+    /** The binding a module and call name identify, or a clear error. */
+    binding(module, call) {
+        const found = MODULES.find((entry) => entry.name === module)?.calls.find((entry) => entry.name === call);
+        if (found === undefined) {
+            throw new LoamsError(`loams.${module} has no generated call ${call}`, {
+                code: Code.Internal,
+            });
+        }
+        return found;
+    }
+    /** The proto revision this SDK declares (§44 §10.3). */
+    get protoRev() {
+        return PROTO_REV;
+    }
+    /** The proto packages this SDK speaks. */
+    get protoPackages() {
+        return PROTO_PACKAGES.filter((name) => name.startsWith('loams.'));
+    }
+    /** Forgets the cached service catalogue, so the next check calls again. */
+    invalidateCatalogue() {
+        this.system.invalidate();
+    }
+}
+/**
+ * Builds one object per generated module: one function per generated call,
+ * each delegating to the same invoker.
+ *
+ * A server-streaming call returns the `AsyncIterable` directly rather than a
+ * promise of one, so `for await (const t of loams.live.watch(...))` reads the
+ * way design §44 §7.1 says it should.
+ */
+function buildModules(invoker) {
+    const modules = {};
+    for (const module of MODULES) {
+        const descriptor = SERVICE_DESCRIPTORS[module.service];
+        if (descriptor === undefined) {
+            continue;
+        }
+        invoker.register(module.service, descriptor);
+        const calls = {
+            module: module.name,
+            service: module.service,
+            unstable: module.unstable,
+        };
+        for (const binding of module.calls) {
+            // A server-streaming call returns the `AsyncIterable` directly rather
+            // than a promise of one, so `for await (const t of loams.live.watch(..))`
+            // reads the way design §44 §7.1 says it should. `loams.stream()` wraps
+            // the same call with cursor resume.
+            calls[binding.name] =
+                binding.streaming === 'server'
+                    ? (request, options) => invoker.stream(binding, request, options)
+                    : (request, options) => invoker.unary(binding, request, options);
+        }
+        modules[module.name] = calls;
+    }
+    return modules;
+}
+/**
+ * The module tree a dotted name implies: `'live.admin'` becomes `live.admin`
+ * and `'admin.org'` becomes `admin.org`.
+ *
+ * A child is attached to its parent module object when the parent exists
+ * (`live` is a module with calls of its own), and to a plain namespace object
+ * when it does not (`admin` has only children). The flat catalogue is left as
+ * it is; the tree reuses its objects, so `loams.live.admin` and
+ * `loams.modules['live.admin']` are the same object.
+ */
+function nestModules(flat) {
+    const tree = {};
+    // Parents before children, so a module with calls of its own is the node
+    // its children hang from rather than being replaced by a namespace.
+    const names = Object.keys(flat).sort((a, b) => a.split('.').length - b.split('.').length);
+    for (const name of names) {
+        const path = name.split('.');
+        const leaf = path.pop();
+        let node = tree;
+        for (const part of path) {
+            let next = node[part];
+            if (next === undefined) {
+                next = {};
+                node[part] = next;
+            }
+            node = next;
+        }
+        if (leaf in node) {
+            throw new LoamsError(`the module ${name} collides with a call of the same name`, {
+                code: Code.Internal,
+            });
+        }
+        node[leaf] = flat[name];
+    }
+    return tree;
+}

package/dist/node.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from '@connectrpc/connect';
+import { type TransportOptions } from './runtime/transports.js';
+export * from './index.js';
+/**
+ * HTTP/2 gRPC, over `node:http2`.
+ *
+ * The server's loopback listener is plaintext, so there is no ALPN to
+ * negotiate and the client uses HTTP/2 with prior knowledge. Against a TLS
+ * endpoint this is ordinary gRPC: HTTP/2, the same credentials, the same
+ * retries.
+ */
+export declare function createNodeTransport(options?: TransportOptions): Transport;

package/dist/node.js

@@ -0,0 +1,43 @@
+// `@loams/client/node`: the Node, Deno and Bun entry point.
+//
+//   import { Loams, createNodeTransport } from '@loams/client/node';
+//
+//   const loams = new Loams({ endpoint, transport: createNodeTransport() });
+//
+// The difference from the default entry point is the transport, and only the
+// transport: it lives here rather than in `@loams/client` because
+// `@connectrpc/connect-node` reaches for `node:http2`, which a browser bundler
+// would follow into a build it cannot satisfy. Keeping it in a subpath means
+// the main entry stays browser-safe by construction rather than by a
+// conditional import that a bundler has to resolve correctly.
+//
+// Which to use. One port serves the Connect protocol, gRPC and gRPC-Web
+// (design §44 §4, D600), so both entries reach the same server with the same
+// code. The `fetch` transport is HTTP/1.1 Connect or gRPC-Web and works
+// everywhere, including through a proxy that only speaks HTTP/1.1; the Node
+// transport is HTTP/2 gRPC, which is fewer round trips and multiplexes
+// connections, at the cost of requiring an HTTP/2-capable path all the way
+// down. Prefer this one on a loopback stack or inside the cluster; prefer the
+// default one in a browser, an edge function, or behind an HTTP/1.1 proxy.
+import { createGrpcTransport } from '@connectrpc/connect-node';
+import { transportInterceptors } from './runtime/transports.js';
+export * from './index.js';
+/**
+ * HTTP/2 gRPC, over `node:http2`.
+ *
+ * The server's loopback listener is plaintext, so there is no ALPN to
+ * negotiate and the client uses HTTP/2 with prior knowledge. Against a TLS
+ * endpoint this is ordinary gRPC: HTTP/2, the same credentials, the same
+ * retries.
+ */
+export function createNodeTransport(options = {}) {
+    const interceptors = transportInterceptors(options);
+    return createGrpcTransport({
+        baseUrl: options.baseUrl ?? '',
+        useBinaryFormat: options.useBinaryFormat ?? true,
+        ...(options.defaultTimeoutMs === undefined
+            ? {}
+            : { defaultTimeoutMs: options.defaultTimeoutMs }),
+        ...(interceptors.length === 0 ? {} : { interceptors }),
+    });
+}

package/dist/runtime/call.d.ts

@@ -0,0 +1,132 @@
+import type { DescService } from '@bufbuild/protobuf';
+import { type CallOptions as ConnectCallOptions, type Transport } from '@connectrpc/connect';
+import type { CallBinding } from '../gen/facade.js';
+import type { TokenSource } from './token-source.js';
+/**
+ * Per-call overrides. Everything here is optional: the client's defaults apply,
+ * and the generated binding supplies the retry class.
+ *
+ * The instance's URL is *not* here: in connect-es it belongs to the transport,
+ * so a `Loams` built without a `transport` makes one from its `endpoint`, and
+ * one built with a `transport` expects that transport to know the URL.
+ */
+export interface CallOptions extends ConnectCallOptions {
+    /** Retries after the first attempt. `0` disables retrying for this call. */
+    maxRetries?: number;
+    /** Extra request headers. `Authorization` is set by the client and wins. */
+    headers?: Record<string, string>;
+    /**
+     * The idempotency key for a mutating call. Supply your own to make a retry
+     * yours rather than the SDK's; omit it and the SDK mints one UUIDv7 per
+     * logical call and reuses it on every retry.
+     */
+    idempotencyKey?: string;
+    /** Overrides the call's retry class for this call only. */
+    retrySafe?: boolean;
+    /** The consistency token to read at, and the store to record writes in
+     * (§44 §7.4, D609). */
+    consistency?: ConsistencyOptions;
+}
+/** How consistency tokens are carried (D609). */
+export interface ConsistencyOptions {
+    /** A `ConsistencyToken` from a previous write, or `'strong'` (the default)
+     * / `'eventual'` to read without waiting. */
+    token?: string;
+    /** Record the consistency token every response carries, so later reads are
+     * read-your-writes without the caller threading tokens by hand. */
+    session?: ConsistencyTokenStore | true | false;
+}
+/** A session's merged consistency token (D609). Off unless a call opts in. */
+export interface ConsistencyTokenStore {
+    /** The token to attach to the next read, or undefined for none. */
+    current(): string | undefined;
+    /** Folds a token the server returned into the session's. */
+    record(token: string | undefined): void;
+}
+/** One attempt of a call, as the transport sees it. */
+export type Send = (attempt: Attempt) => Promise<unknown>;
+/** What one attempt carries: the request (with the idempotency key already
+ * set) and the bearer to send, if any. */
+export interface Attempt {
+    readonly request: unknown;
+    readonly headers: Record<string, string>;
+    readonly attempt: number;
+    readonly refreshed: boolean;
+}
+/** Everything the retry loop needs, so it can be tested without a transport. */
+export interface RetryPlan {
+    /** The call's retry class from the generated binding. */
+    readonly retrySafe: boolean;
+    readonly maxRetries: number;
+    readonly signal?: AbortSignal;
+    readonly onRefresh?: () => Promise<void>;
+}
+/**
+ * Runs `send` until it answers or the plan says stop, and returns whatever it
+ * last threw as a `LoamsError`.
+ *
+ * Exported so the tests can drive it with a stub `send`: the retry policy,
+ * the idempotency-key lifecycle and the refresh-once behaviour are the SDK's
+ * own logic and are pinned without a server.
+ */
+export declare function callWithRetry(request: unknown, send: Send, plan: RetryPlan, rpc?: string): Promise<unknown>;
+/**
+ * Gives a mutating call its idempotency key, once per logical call.
+ *
+ * D610: a mutation may only be retried when it carries one, and the same key
+ * has to go out on every attempt or the retry is a second write. So the key is
+ * decided here, before the first attempt, and the request object is not
+ * rewritten afterwards.
+ *
+ * A message without an `idempotency_key` field is left alone: proto3 messages
+ * are plain objects here, so the field's presence is the test.
+ */
+export declare function withIdempotencyKey(request: unknown, supplied: string | undefined, 
+/** Whether the request *schema* declares an `idempotency_key` field. */
+declared?: boolean): {
+    request: unknown;
+    keyed: boolean;
+};
+/**
+ * The client's call path: a generated `CallBinding` plus a request becomes a
+ * response message, with everything the SDK owns applied on the way.
+ */
+export declare class CallInvoker {
+    private readonly transport;
+    private readonly tokenSource;
+    private readonly maxRetries;
+    private readonly consistency;
+    private readonly clients;
+    private readonly descriptors;
+    /** Whether a call's request schema declares `idempotency_key`, per RPC. */
+    private readonly keyed;
+    constructor(transport: Transport, tokenSource: TokenSource | undefined, maxRetries: number, consistency: ConsistencyTokenStore | undefined);
+    /**
+     * A module's Connect client, built once from the service descriptor
+     * `protoc-gen-es` generated. This is what makes the facade generated rather
+     * than hand-written: the SDK never writes a client, it wraps the stubs.
+     */
+    register(service: string, descriptor: DescService): void;
+    /** Whether this call's request message declares an `idempotency_key`. */
+    private takesIdempotencyKey;
+    /** The connect-es method a binding names, or a clear internal error. */
+    private method;
+    /** One unary call: the whole runtime contract, applied to one binding. */
+    unary(binding: CallBinding, request: unknown, options?: CallOptions): Promise<Record<string, unknown> | undefined>;
+    /** The headers a call carries: the caller's, plus the bearer and the
+     * consistency token the runtime owns. */
+    private headers;
+    /**
+     * One server stream, with the errors mapped: no resume, no cursor tracking.
+     *
+     * The mapping is not optional here. A refusal on a stream arrives inside the
+     * Connect envelope, not as an HTTP status, so a caller that iterated the raw
+     * iterable would see a `ConnectError` with no `reason` — the one place in the
+     * SDK where `reason` could go missing. `watch()` adds the resume on top.
+     */
+    stream(binding: CallBinding, request: unknown, options?: CallOptions): AsyncIterable<unknown>;
+    /** Wraps an iterable so every throw becomes a `LoamsError`. */
+    private mapped;
+    /** Merges the consistency token a write answered with into the session. */
+    private recordConsistency;
+}

package/dist/runtime/call.js

@@ -0,0 +1,273 @@
+// The call path: the one place a facade method becomes an RPC (design §44 §7.4;
+// runtime contract R1-R4).
+//
+// It does four things the generated facade cannot, and nothing else:
+//
+// - attaches the bearer from the client's `TokenSource`;
+// - retries on the call's class from the generated bindings, with M1.6's
+//   backoff numbers, and refreshes the token once on `token_expired`;
+// - gives a mutating call an idempotency key once per logical call and reuses
+//   it on every retry, so a retried write is the same write (D610);
+// - turns whatever is thrown into the typed `LoamsError` hierarchy, so a
+//   caller branches on `reason` and never on a message.
+import { Code, createClient, } from '@connectrpc/connect';
+import { LoamsError, TokenExpiredError, toLoamsError } from './errors.js';
+import { DEFAULT_MAX_RETRIES, backoffMs, shouldRetry, sleep } from './retry.js';
+import { uuidv7 } from './uuidv7.js';
+/**
+ * Runs `send` until it answers or the plan says stop, and returns whatever it
+ * last threw as a `LoamsError`.
+ *
+ * Exported so the tests can drive it with a stub `send`: the retry policy,
+ * the idempotency-key lifecycle and the refresh-once behaviour are the SDK's
+ * own logic and are pinned without a server.
+ */
+export async function callWithRetry(request, send, plan, rpc) {
+    let refreshed = false;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await send({ request, headers: {}, attempt, refreshed });
+        }
+        catch (thrown) {
+            const error = toLoamsError(thrown, rpc);
+            // R1: a 401 whose reason is `token_expired` gets exactly one refresh and
+            // one retry. A source that cannot refresh (`apiKey`) makes this a no-op,
+            // and a second expiry is reported rather than looped on.
+            if (error instanceof TokenExpiredError && !refreshed && plan.onRefresh !== undefined) {
+                refreshed = true;
+                await plan.onRefresh();
+                attempt -= 1;
+                continue;
+            }
+            if (!shouldRetry(error, plan.retrySafe, attempt, plan.maxRetries)) {
+                throw error;
+            }
+            await sleep(backoffMs(attempt), plan.signal);
+        }
+    }
+}
+/**
+ * Gives a mutating call its idempotency key, once per logical call.
+ *
+ * D610: a mutation may only be retried when it carries one, and the same key
+ * has to go out on every attempt or the retry is a second write. So the key is
+ * decided here, before the first attempt, and the request object is not
+ * rewritten afterwards.
+ *
+ * A message without an `idempotency_key` field is left alone: proto3 messages
+ * are plain objects here, so the field's presence is the test.
+ */
+export function withIdempotencyKey(request, supplied, 
+/** Whether the request *schema* declares an `idempotency_key` field. */
+declared = false) {
+    if (typeof request !== 'object' || request === null) {
+        return { request, keyed: false };
+    }
+    const message = request;
+    // Either the schema declares the field or the object carries it; without one
+    // of those two there is nothing to key, and a request that has no key field
+    // must be left exactly as the caller wrote it.
+    if (!declared && !('idempotencyKey' in message)) {
+        return { request, keyed: false };
+    }
+    if (typeof message.idempotencyKey === 'string' && message.idempotencyKey !== '') {
+        return { request, keyed: true };
+    }
+    return {
+        request: { ...message, idempotencyKey: supplied ?? uuidv7() },
+        keyed: true,
+    };
+}
+/**
+ * A stream method's return value, as one async iterable.
+ *
+ * connect-es types a server stream as an iterable that may be awaited; the SDK
+ * hands callers a plain `AsyncIterable`, which is what `for await` wants
+ * (design §44 §7.1).
+ */
+async function* streamOf(source) {
+    yield* source;
+}
+/** The request-message field a mutation is keyed by (D610). Read from the
+ * generated schema rather than guessed from the object a caller built. */
+const IDEMPOTENCY_KEY = 'idempotencyKey';
+/**
+ * The session a call asked for: its own store if it brought one, the client's
+ * if it asked for the session's, none otherwise.
+ */
+function resolveSession(options, clientSession) {
+    const session = options?.session;
+    if (session === undefined || session === false) {
+        return undefined;
+    }
+    return session === true ? clientSession : session;
+}
+/**
+ * The client's call path: a generated `CallBinding` plus a request becomes a
+ * response message, with everything the SDK owns applied on the way.
+ */
+export class CallInvoker {
+    transport;
+    tokenSource;
+    maxRetries;
+    consistency;
+    clients = new Map();
+    descriptors = new Map();
+    /** Whether a call's request schema declares `idempotency_key`, per RPC. */
+    keyed = new Map();
+    constructor(transport, tokenSource, maxRetries, consistency) {
+        this.transport = transport;
+        this.tokenSource = tokenSource;
+        this.maxRetries = maxRetries;
+        this.consistency = consistency;
+    }
+    /**
+     * A module's Connect client, built once from the service descriptor
+     * `protoc-gen-es` generated. This is what makes the facade generated rather
+     * than hand-written: the SDK never writes a client, it wraps the stubs.
+     */
+    register(service, descriptor) {
+        if (this.clients.has(service)) {
+            return;
+        }
+        this.descriptors.set(service, descriptor);
+        for (const method of Object.values(descriptor.method)) {
+            // Whether this RPC takes an idempotency key is a property of its request
+            // message, so it is read from the generated schema rather than inferred
+            // from the object a caller happened to build. A caller who omits an
+            // `optional` field still gets a key, and `MutateRequest` (which has one)
+            // is never confused with `DeployRequest` (which does not).
+            this.keyed.set(`${service}/${method.name}`, method.input.field[IDEMPOTENCY_KEY] !== undefined);
+        }
+        this.clients.set(service, createClient(descriptor, this.transport));
+    }
+    /** Whether this call's request message declares an `idempotency_key`. */
+    takesIdempotencyKey(binding) {
+        return this.keyed.get(`${binding.service}/${binding.method}`) ?? false;
+    }
+    /** The connect-es method a binding names, or a clear internal error. */
+    method(binding) {
+        const client = this.clients.get(binding.service);
+        const method = client?.[binding.name];
+        if (typeof method !== 'function') {
+            throw new LoamsError(`the generated client for ${binding.service} has no method ${binding.name}`, { code: Code.Internal, rpc: binding.rpc });
+        }
+        return method;
+    }
+    /** One unary call: the whole runtime contract, applied to one binding. */
+    async unary(binding, request, options = {}) {
+        const { request: keyed, keyed: hasKey } = withIdempotencyKey(request, options.idempotencyKey, this.takesIdempotencyKey(binding));
+        const maxRetries = options.maxRetries ?? this.maxRetries;
+        // D610: a `safe` call always retries; a mutation retries once it carries an
+        // idempotency key, which `withIdempotencyKey` has just decided.
+        const retrySafe = options.retrySafe ?? (binding.retry === 'safe' || hasKey);
+        const session = resolveSession(options.consistency, this.consistency);
+        // An explicit token wins; otherwise the session's, which is what makes
+        // `consistency: { session: true }` read-your-writes rather than record it
+        // and never send it (R4).
+        const consistency = options.consistency?.token ?? session?.current();
+        const method = this.method(binding);
+        const result = (await callWithRetry(keyed, async () => method(keyed, { ...options, headers: await this.headers(options, consistency) }), {
+            retrySafe,
+            maxRetries,
+            signal: options.signal,
+            onRefresh: this.tokenSource?.refresh?.bind(this.tokenSource),
+        }, binding.rpc));
+        this.recordConsistency(session, result);
+        return result;
+    }
+    /** The headers a call carries: the caller's, plus the bearer and the
+     * consistency token the runtime owns. */
+    async headers(options, consistency) {
+        const headers = { ...options.headers };
+        const bearer = await this.tokenSource?.token();
+        if (bearer !== undefined) {
+            headers.authorization = `Bearer ${bearer}`;
+        }
+        if (consistency !== undefined) {
+            headers['loams-consistency'] = consistency;
+        }
+        return headers;
+    }
+    /**
+     * One server stream, with the errors mapped: no resume, no cursor tracking.
+     *
+     * The mapping is not optional here. A refusal on a stream arrives inside the
+     * Connect envelope, not as an HTTP status, so a caller that iterated the raw
+     * iterable would see a `ConnectError` with no `reason` — the one place in the
+     * SDK where `reason` could go missing. `watch()` adds the resume on top.
+     */
+    stream(binding, request, options = {}) {
+        const method = this.method(binding);
+        const session = resolveSession(options.consistency, this.consistency);
+        const consistency = options.consistency?.token ?? session?.current();
+        const self = this;
+        const refresh = this.tokenSource?.refresh?.bind(this.tokenSource);
+        // Synchronous, because `loams.live.watch(...)` has to hand back an
+        // `AsyncIterable` rather than a promise of one (design §44 §7.1). The
+        // bearer is fetched when the caller first steps the stream rather than when
+        // the call is made: a stream that never authenticates is not a stream.
+        const invoke = async function* () {
+            let refreshed = false;
+            let yielded = false;
+            for (;;) {
+                const headers = await self.headers(options, consistency);
+                const source = self.mapped(streamOf(method(request, { ...options, headers })), binding.rpc);
+                try {
+                    for await (const message of source) {
+                        yielded = true;
+                        yield message;
+                    }
+                    return;
+                }
+                catch (thrown) {
+                    const error = toLoamsError(thrown, binding.rpc);
+                    // R1 on a stream: one refresh and one re-open, and only if nothing
+                    // has been yielded yet. Once messages are flowing the caller is
+                    // holding a position in the stream, and re-opening it is `watch()`'s
+                    // job (it resumes from the cursor); replaying from the start here
+                    // would duplicate everything the caller has already seen.
+                    if (error instanceof TokenExpiredError &&
+                        !refreshed &&
+                        refresh !== undefined &&
+                        !yielded) {
+                        refreshed = true;
+                        await refresh();
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+        };
+        return invoke();
+    }
+    /** Wraps an iterable so every throw becomes a `LoamsError`. */
+    mapped(source, rpc) {
+        const invoke = async function* () {
+            try {
+                yield* source;
+            }
+            catch (thrown) {
+                throw toLoamsError(thrown, rpc);
+            }
+        };
+        return invoke();
+    }
+    /** Merges the consistency token a write answered with into the session. */
+    recordConsistency(session, result) {
+        if (session === undefined || result === undefined) {
+            return;
+        }
+        const token = result.consistencyToken;
+        try {
+            session.record(typeof token === 'string' && token !== '' ? token : undefined);
+        }
+        catch {
+            // The RPC already succeeded. A token the session cannot merge — the
+            // encoding is still opaque, see `ConsistencySession` — must not turn a
+            // committed write into a thrown error, because a caller that retries on
+            // that error performs the write twice. `ConsistencySession.conflicts`
+            // counts it instead.
+        }
+    }
+}