@loams/client 0.0.0-stage → 0.1.0

package/dist/runtime/consistency.d.ts

@@ -0,0 +1,22 @@
+/** The prefix every token carries (§44 §7.4). */
+export declare const TOKEN_PREFIX = "v1:";
+/** Whether a string looks like a consistency token. */
+export declare function isConsistencyToken(value: string): boolean;
+/**
+ * A session's consistency token.
+ *
+ * Merging is deliberately conservative while the encoding is opaque: the store
+ * keeps what it has, and a second, different token is a conflict the caller has
+ * to resolve, not something to merge blindly.
+ */
+export declare class ConsistencySession {
+    #private;
+    /** The token to attach to the next read. */
+    current(): string | undefined;
+    /** Folds a token the server returned in. */
+    record(token: string | undefined): void;
+    /** How many unmergeable pairs the session has seen. */
+    get conflicts(): number;
+    /** Forgets the token, so the next read is not held to it. */
+    clear(): void;
+}

package/dist/runtime/consistency.js

@@ -0,0 +1,68 @@
+// Consistency tokens (design §44 §7.4, D609; runtime contract R4).
+//
+// A write answers with a `consistency_token`; a read accepts one, so a caller
+// that just wrote can read its own write. Threading those by hand is the
+// caller's job today. The session store is the alternative §44 §7.4 asks for:
+// off by default, and when a call opts in, every response's token is merged
+// into the session and attached to later reads.
+//
+// **The token's encoding is not in the protos yet.** §05 §5 defines the
+// semantics (offsets per stream and partition, `STRONG` as the default,
+// `EVENTUAL`, `AT_LEAST{token}`) and API1's write paths carry it as an opaque
+// `v1:` string; §44 §7.4 says it merges by "max offset per stream and
+// partition", which needs the encoding to be parsed. Until that lands this
+// store keeps the token it was given, refuses to merge two different tokens
+// into a wrong one, and says so — a silently-wrong consistency token reads
+// stale data, which is worse than an error.
+import { LoamsError } from './errors.js';
+import { Code } from '@connectrpc/connect';
+/** The prefix every token carries (§44 §7.4). */
+export const TOKEN_PREFIX = 'v1:';
+/** Whether a string looks like a consistency token. */
+export function isConsistencyToken(value) {
+    return value.startsWith(TOKEN_PREFIX) && value.length > TOKEN_PREFIX.length;
+}
+/**
+ * A session's consistency token.
+ *
+ * Merging is deliberately conservative while the encoding is opaque: the store
+ * keeps what it has, and a second, different token is a conflict the caller has
+ * to resolve, not something to merge blindly.
+ */
+export class ConsistencySession {
+    #token;
+    /** How many times two different tokens met. Surfaced so the limitation is
+     * visible rather than silent. */
+    #conflicts = 0;
+    /** The token to attach to the next read. */
+    current() {
+        return this.#token;
+    }
+    /** Folds a token the server returned in. */
+    record(token) {
+        if (token === undefined || token === '') {
+            return;
+        }
+        if (!isConsistencyToken(token)) {
+            this.#conflicts += 1;
+            throw new LoamsError(`not a consistency token: ${token}`, { code: Code.Internal });
+        }
+        if (this.#token === undefined || this.#token === token) {
+            this.#token = token;
+            return;
+        }
+        this.#conflicts += 1;
+        throw new LoamsError('two different consistency tokens met and the encoding cannot merge them yet; ' +
+            'the session keeps the first. Merging by stream and partition offset arrives with ' +
+            'the write paths that carry offsets (§44 §7.4, D609).', { code: Code.FailedPrecondition });
+    }
+    /** How many unmergeable pairs the session has seen. */
+    get conflicts() {
+        return this.#conflicts;
+    }
+    /** Forgets the token, so the next read is not held to it. */
+    clear() {
+        this.#token = undefined;
+        this.#conflicts = 0;
+    }
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,100 @@
+import { Code, ConnectError } from '@connectrpc/connect';
+import { type Reason } from '../gen/facade.js';
+/** What every Loams failure carries. */
+export declare class LoamsError extends Error {
+    /** The Connect code, the canonical classification. */
+    readonly code: Code;
+    /** The stable cause, when the server sent an `ErrorInfo`. Undefined means
+     * the failure came from below the API (a socket, a timeout, a CORS
+     * rejection), not from a Loams service. */
+    readonly reason: Reason | undefined;
+    /** Structured context the server sent. Never secrets. */
+    readonly metadata: Readonly<Record<string, string>>;
+    /** A short next step in the caller's locale, when the server sent one. */
+    readonly hint: string | undefined;
+    /** The RPC that failed, as `package.Service/Method`. */
+    readonly rpc: string | undefined;
+    /** True when the reason is not in this SDK's registry: the server is newer
+     * than the SDK, so the reason is carried as text and the union is not. */
+    readonly unknownReason: string | undefined;
+    constructor(message: string, init: {
+        code: Code;
+        reason?: Reason;
+        unknownReason?: string;
+        metadata?: Record<string, string>;
+        hint?: string;
+        rpc?: string;
+        cause?: unknown;
+    });
+}
+export declare class InvalidArgumentError extends LoamsError {
+}
+export declare class NotFoundError extends LoamsError {
+}
+export declare class AlreadyExistsError extends LoamsError {
+}
+export declare class PermissionDeniedError extends LoamsError {
+}
+export declare class UnauthenticatedError extends LoamsError {
+}
+export declare class FailedPreconditionError extends LoamsError {
+}
+export declare class ResourceExhaustedError extends LoamsError {
+}
+export declare class UnavailableError extends LoamsError {
+}
+export declare class DeadlineExceededError extends LoamsError {
+}
+export declare class AbortedError extends LoamsError {
+}
+export declare class InternalError extends LoamsError {
+}
+export declare class UnimplementedError extends LoamsError {
+}
+/**
+ * A package this build variant does not carry (design §44 §4, D600).
+ *
+ * The server answers `unimplemented` with `ErrorInfo.reason =
+ * feature_not_in_variant` and names the variant in `metadata.variant`, which
+ * is what this class reads. A caller usually never gets here: `loams.system`
+ * feature-detects from `GetInstance.services[]` before calling, so an
+ * unavailable module throws `FeatureNotInVariantError` from
+ * `loams.system.guard()` with no request spent. This class is the path for a
+ * caller who skipped the guard, or whose instance changed variant.
+ */
+export declare class FeatureNotInVariantError extends UnimplementedError {
+    /** The build variant that was asked for, from `metadata.variant`. */
+    readonly variant: string | undefined;
+    constructor(message: string, init: ConstructorParameters<typeof UnimplementedError>[1] & {
+        variant?: string;
+    });
+}
+/** A token the server rejected as expired: `unauthenticated` with reason
+ * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
+export declare class TokenExpiredError extends UnauthenticatedError {
+}
+/** Whether a value is a Loams error rather than a raw `ConnectError`. */
+export declare function isLoamsError(value: unknown): value is LoamsError;
+/**
+ * The `ErrorInfo` a Connect error carries, if any.
+ *
+ * The detail is looked up by its type URL rather than by position, so a
+ * service that adds a detail of its own does not move `reason` out from under
+ * a caller.
+ */
+export declare function errorInfo(error: ConnectError): ErrorInfoShape | undefined;
+/** The fields of `loams.errors.v1.ErrorInfo` this package reads. */
+export interface ErrorInfoShape {
+    readonly reason: string;
+    readonly metadata: {
+        readonly [key: string]: string;
+    };
+    readonly hint: string;
+}
+/**
+ * Turns any thrown value into the typed hierarchy: a `ConnectError` becomes the
+ * class its code names, with `reason` and `metadata` lifted out of the
+ * `ErrorInfo` detail; anything else (a fetch rejection, an abort, a bug in
+ * the SDK) becomes a `LoamsError` with `Code.Unknown`.
+ */
+export declare function toLoamsError(value: unknown, rpc?: string): LoamsError;

package/dist/runtime/errors.js

@@ -0,0 +1,165 @@
+// The typed error hierarchy of design §44 §7.4, decision D611.
+//
+// A failed RPC carries a Connect code and one `loams.errors.v1.ErrorInfo` in
+// its details. The `reason` is what callers branch on: it is a stable
+// `snake_case` string, registered in `docs/api/reasons.md` and generated into
+// this package's `Reason` union, so `error.reason === 'feature_not_in_variant'`
+// narrows the type and a reason the registry has lost stops compiling. The
+// `message` is for people and may change; nothing in an SDK branches on it.
+import { Code, ConnectError } from '@connectrpc/connect';
+import { ErrorInfoSchema } from '../vendor/proto/gen/loams/errors/v1/errors_pb.js';
+import { REASONS } from '../gen/facade.js';
+/** The registry, as a runtime guard: a reason off the wire that the generated
+ * union does not have is a server newer than this SDK, and is surfaced rather
+ * than dropped. */
+const KNOWN_REASONS = new Set(REASONS);
+/** What every Loams failure carries. */
+export class LoamsError extends Error {
+    /** The Connect code, the canonical classification. */
+    code;
+    /** The stable cause, when the server sent an `ErrorInfo`. Undefined means
+     * the failure came from below the API (a socket, a timeout, a CORS
+     * rejection), not from a Loams service. */
+    reason;
+    /** Structured context the server sent. Never secrets. */
+    metadata;
+    /** A short next step in the caller's locale, when the server sent one. */
+    hint;
+    /** The RPC that failed, as `package.Service/Method`. */
+    rpc;
+    /** True when the reason is not in this SDK's registry: the server is newer
+     * than the SDK, so the reason is carried as text and the union is not. */
+    unknownReason;
+    constructor(message, init) {
+        super(message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = new.target.name;
+        this.code = init.code;
+        this.reason = init.reason;
+        this.unknownReason = init.unknownReason;
+        this.metadata = init.metadata ?? {};
+        this.hint = init.hint;
+        this.rpc = init.rpc;
+    }
+}
+export class InvalidArgumentError extends LoamsError {
+}
+export class NotFoundError extends LoamsError {
+}
+export class AlreadyExistsError extends LoamsError {
+}
+export class PermissionDeniedError extends LoamsError {
+}
+export class UnauthenticatedError extends LoamsError {
+}
+export class FailedPreconditionError extends LoamsError {
+}
+export class ResourceExhaustedError extends LoamsError {
+}
+export class UnavailableError extends LoamsError {
+}
+export class DeadlineExceededError extends LoamsError {
+}
+export class AbortedError extends LoamsError {
+}
+export class InternalError extends LoamsError {
+}
+export class UnimplementedError extends LoamsError {
+}
+/**
+ * A package this build variant does not carry (design §44 §4, D600).
+ *
+ * The server answers `unimplemented` with `ErrorInfo.reason =
+ * feature_not_in_variant` and names the variant in `metadata.variant`, which
+ * is what this class reads. A caller usually never gets here: `loams.system`
+ * feature-detects from `GetInstance.services[]` before calling, so an
+ * unavailable module throws `FeatureNotInVariantError` from
+ * `loams.system.guard()` with no request spent. This class is the path for a
+ * caller who skipped the guard, or whose instance changed variant.
+ */
+export class FeatureNotInVariantError extends UnimplementedError {
+    /** The build variant that was asked for, from `metadata.variant`. */
+    variant;
+    constructor(message, init) {
+        super(message, init);
+        this.variant = init.variant;
+    }
+}
+/** A token the server rejected as expired: `unauthenticated` with reason
+ * `token_expired`. The runtime refreshes once and retries once (D608, R1). */
+export class TokenExpiredError extends UnauthenticatedError {
+}
+/** The code-to-class mapping of D611. Codes D611 does not name (`canceled`,
+ * `out_of_range`, `data_loss`) fall through to the base `LoamsError`. */
+const BY_CODE = {
+    [Code.Canceled]: LoamsError,
+    [Code.Unknown]: LoamsError,
+    [Code.InvalidArgument]: InvalidArgumentError,
+    [Code.DeadlineExceeded]: DeadlineExceededError,
+    [Code.NotFound]: NotFoundError,
+    [Code.AlreadyExists]: AlreadyExistsError,
+    [Code.PermissionDenied]: PermissionDeniedError,
+    [Code.ResourceExhausted]: ResourceExhaustedError,
+    [Code.FailedPrecondition]: FailedPreconditionError,
+    [Code.Aborted]: AbortedError,
+    [Code.OutOfRange]: LoamsError,
+    [Code.Unimplemented]: UnimplementedError,
+    [Code.Internal]: InternalError,
+    [Code.Unavailable]: UnavailableError,
+    [Code.DataLoss]: LoamsError,
+    [Code.Unauthenticated]: UnauthenticatedError,
+};
+/** Whether a value is a Loams error rather than a raw `ConnectError`. */
+export function isLoamsError(value) {
+    return value instanceof LoamsError;
+}
+/**
+ * The `ErrorInfo` a Connect error carries, if any.
+ *
+ * The detail is looked up by its type URL rather than by position, so a
+ * service that adds a detail of its own does not move `reason` out from under
+ * a caller.
+ */
+export function errorInfo(error) {
+    const found = error.findDetails(ErrorInfoSchema);
+    return found.length > 0 ? found[0] : undefined;
+}
+/**
+ * Turns any thrown value into the typed hierarchy: a `ConnectError` becomes the
+ * class its code names, with `reason` and `metadata` lifted out of the
+ * `ErrorInfo` detail; anything else (a fetch rejection, an abort, a bug in
+ * the SDK) becomes a `LoamsError` with `Code.Unknown`.
+ */
+export function toLoamsError(value, rpc) {
+    if (value instanceof LoamsError) {
+        return value;
+    }
+    if (!(value instanceof ConnectError)) {
+        return new LoamsError(value instanceof Error ? value.message : String(value), {
+            code: Code.Unknown,
+            rpc,
+            cause: value,
+        });
+    }
+    const info = errorInfo(value);
+    const raw = info?.reason ?? '';
+    const init = {
+        code: value.code,
+        reason: KNOWN_REASONS.has(raw) ? raw : undefined,
+        unknownReason: raw !== '' && !KNOWN_REASONS.has(raw) ? raw : undefined,
+        metadata: info?.metadata ?? {},
+        hint: info?.hint === '' ? undefined : info?.hint,
+        rpc,
+        cause: value,
+    };
+    if (init.reason === 'feature_not_in_variant') {
+        return new FeatureNotInVariantError(value.rawMessage, {
+            ...init,
+            variant: init.metadata.variant,
+        });
+    }
+    if (init.code === Code.Unauthenticated && init.reason === 'token_expired') {
+        return new TokenExpiredError(value.rawMessage, init);
+    }
+    const Constructor = BY_CODE[value.code] ?? LoamsError;
+    return new Constructor(value.rawMessage, init);
+}

package/dist/runtime/pagination.d.ts

@@ -0,0 +1,25 @@
+import type { CallBinding } from '../gen/facade.js';
+import type { CallOptions } from './call.js';
+/** The field a paged call is given the page token in, on the request. */
+export interface PageRequestOptions {
+    /** The request field carrying `page_size`; defaults to `pageSize`. */
+    pageSizeField?: string;
+    /** The request field carrying `page_token`; defaults to `pageToken`. */
+    pageTokenField?: string;
+}
+/** One page request, as the iterator makes it. */
+export type PageFetcher<Request, Response> = (request: Request, options?: CallOptions) => Promise<Response>;
+/**
+ * Every item of a paged call, following the tokens (D617's "the paging
+ * iterator").
+ *
+ * The caller gets items, not pages: `for await (const c of loams.paginate(...))`.
+ * The raw page call is still available on the module, so a caller that wants
+ * pages, or wants to stop after one, does not have to use this.
+ */
+export declare function paginate<Request extends object, Response extends object, Item>(binding: CallBinding, fetch: PageFetcher<Request, Response>, request: Request, options?: CallOptions & PageRequestOptions): AsyncGenerator<Item, void, undefined>;
+/** The request field names a paged call uses, from its binding. */
+export declare function pageFields(binding: CallBinding): {
+    pageSizeField: string;
+    pageTokenField: string;
+};

package/dist/runtime/pagination.js

@@ -0,0 +1,47 @@
+// Pagination (design §44 §7.4; runtime contract R6).
+//
+// AIP-158: `page_size` and `page_token` in, `next_page_token` out. A generated
+// binding says which two fields those are (`FacadeOptions.pagination` is
+// `"<items>:<next page token>"`), so the iterator is one function for every
+// paged RPC rather than one per list RPC.
+/**
+ * Every item of a paged call, following the tokens (D617's "the paging
+ * iterator").
+ *
+ * The caller gets items, not pages: `for await (const c of loams.paginate(...))`.
+ * The raw page call is still available on the module, so a caller that wants
+ * pages, or wants to stop after one, does not have to use this.
+ */
+export async function* paginate(binding, fetch, request, options = {}) {
+    const pagination = binding.pagination;
+    if (pagination === null) {
+        throw new Error(`${binding.module}.${binding.name} is not a paged call: the proto's facade options name no pagination`);
+    }
+    const pageSizeField = options.pageSizeField ?? 'pageSize';
+    const pageTokenField = options.pageTokenField ?? 'pageToken';
+    let pageToken;
+    for (;;) {
+        const page = (await fetch({
+            ...request,
+            ...(pageToken === undefined ? {} : { [pageTokenField]: pageToken }),
+        }, options));
+        const items = page[pagination.items];
+        if (Array.isArray(items)) {
+            for (const item of items) {
+                yield item;
+            }
+        }
+        const next = page[pagination.nextPageToken];
+        if (typeof next !== 'string' || next === '') {
+            return;
+        }
+        pageToken = next;
+    }
+}
+/** The request field names a paged call uses, from its binding. */
+export function pageFields(binding) {
+    if (binding.pagination === null) {
+        throw new Error(`${binding.module}.${binding.name} is not a paged call`);
+    }
+    return { pageSizeField: 'pageSize', pageTokenField: 'pageToken' };
+}

package/dist/runtime/retry.d.ts

@@ -0,0 +1,30 @@
+import { Code } from '@connectrpc/connect';
+import { LoamsError } from './errors.js';
+/** The first backoff, and the multiplier's base. */
+export declare const BASE_DELAY_MS = 100;
+/** The ceiling on one backoff. */
+export declare const MAX_DELAY_MS = 2000;
+/** Retries after the first attempt, when nothing overrides it. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/** `RetryInfo.retry_delay` is honoured up to this, when the server sends one. */
+export declare const MAX_SERVER_DELAY_MS = 30000;
+/** Whether the code is one a retry may answer. */
+export declare function isRetryableCode(code: Code): boolean;
+/**
+ * The backoff before retry number `attempt` (0 for the first retry), with full
+ * jitter: uniform over `[0, min(cap, base × 2^attempt)]`. A server-sent
+ * `RetryInfo.retry_delay` replaces it, up to {@link MAX_SERVER_DELAY_MS}.
+ */
+export declare function backoffMs(attempt: number, serverDelayMs?: number): number;
+/** Sleeps, for the retry loop and for the tests that would otherwise wait. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Whether one more attempt is allowed.
+ *
+ * `retrySafe` is the call's class from the generated bindings: `safe` for
+ * reads and idempotent RPCs, `manual` for a mutation. A mutation becomes
+ * retryable once it carries an idempotency key, because the key is what makes
+ * the repeat safe — see `callWithRetry` in `call.ts`, which sets one before the
+ * first attempt and reuses it on every retry.
+ */
+export declare function shouldRetry(error: LoamsError, retrySafe: boolean, attempt: number, maxRetries: number): boolean;

package/dist/runtime/retry.js

@@ -0,0 +1,75 @@
+// Retry classes and backoff (design §44 §7.4, D610; runtime contract R2).
+//
+// The numbers are M1.6 Ruling 5's and are the same in every SDK: base 100 ms,
+// doubling, capped at 2 s, 3 retries, full jitter. Full jitter rather than
+// exponential backoff alone, because every client retrying at the same instant
+// after a node restart is how a recovering node gets knocked over again.
+import { Code } from '@connectrpc/connect';
+import { LoamsError } from './errors.js';
+/** The first backoff, and the multiplier's base. */
+export const BASE_DELAY_MS = 100;
+/** The ceiling on one backoff. */
+export const MAX_DELAY_MS = 2_000;
+/** Retries after the first attempt, when nothing overrides it. */
+export const DEFAULT_MAX_RETRIES = 3;
+/** `RetryInfo.retry_delay` is honoured up to this, when the server sends one. */
+export const MAX_SERVER_DELAY_MS = 30_000;
+/** The codes a retry may answer (D610). */
+const RETRYABLE = new Set([
+    Code.Unavailable,
+    Code.DeadlineExceeded,
+    Code.ResourceExhausted,
+]);
+/** Whether the code is one a retry may answer. */
+export function isRetryableCode(code) {
+    return RETRYABLE.has(code);
+}
+/**
+ * The backoff before retry number `attempt` (0 for the first retry), with full
+ * jitter: uniform over `[0, min(cap, base × 2^attempt)]`. A server-sent
+ * `RetryInfo.retry_delay` replaces it, up to {@link MAX_SERVER_DELAY_MS}.
+ */
+export function backoffMs(attempt, serverDelayMs) {
+    if (serverDelayMs !== undefined && serverDelayMs > 0) {
+        return Math.min(serverDelayMs, MAX_SERVER_DELAY_MS);
+    }
+    const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt);
+    return Math.floor(Math.random() * ceiling);
+}
+/** Sleeps, for the retry loop and for the tests that would otherwise wait. */
+export function sleep(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason ?? new Error('aborted'));
+        };
+        if (signal?.aborted === true) {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Whether one more attempt is allowed.
+ *
+ * `retrySafe` is the call's class from the generated bindings: `safe` for
+ * reads and idempotent RPCs, `manual` for a mutation. A mutation becomes
+ * retryable once it carries an idempotency key, because the key is what makes
+ * the repeat safe — see `callWithRetry` in `call.ts`, which sets one before the
+ * first attempt and reuses it on every retry.
+ */
+export function shouldRetry(error, retrySafe, attempt, maxRetries) {
+    if (attempt >= maxRetries) {
+        return false;
+    }
+    return retrySafe && isRetryableCode(error.code);
+}

package/dist/runtime/streams.d.ts

@@ -0,0 +1,30 @@
+import type { CallBinding } from '../gen/facade.js';
+import type { CallOptions } from './call.js';
+/** Opens a stream. The runtime owns retries, so this is the raw call. */
+export type StreamOpener<Message, Request = unknown> = (request: Request, options?: CallOptions) => AsyncIterable<Message>;
+/** The cursor a stream message carries, when it carries one (R7). */
+export type CursorOf<Message> = (message: Message) => string | undefined;
+/** How a stream re-opens from a cursor. */
+export interface ResumeOptions<Message, Request> {
+    /**
+     * The request to re-open with, given the last cursor seen. Return the same
+     * request to reconnect from the beginning (which is correct, and loses
+     * nothing but time, for a stream whose snapshot is complete).
+     */
+    resume: (lastCursor: string | undefined, request: Request) => Request;
+    /** Reads the cursor off a message. Defaults to a `cursor` field. */
+    cursor?: CursorOf<Message>;
+    /** Retries after the first failure. Defaults to the client's. */
+    maxRetries?: number;
+    /** Called after each message, with the cursor it carried. */
+    onCursor?: (cursor: string | undefined, message: Message) => void;
+}
+/**
+ * A server stream that reconnects from its cursor.
+ *
+ * `loams.live.watch()` returns one of these. It yields until the stream ends;
+ * if the stream fails with a code a retry may answer and the call is retryable,
+ * it re-opens from the last cursor and carries on, so a node restart is a
+ * hiccup rather than a gap.
+ */
+export declare function watch<Message, Request extends object>(binding: CallBinding, open: StreamOpener<Message, Request>, request: Request, options: CallOptions & ResumeOptions<Message, Request>): AsyncGenerator<Message, void, undefined>;

package/dist/runtime/streams.js

@@ -0,0 +1,61 @@
+// Server streams (design §44 §7.4, D610; runtime contract R7).
+//
+// The API has server streams only (D420): no client streaming, no bidi, because
+// a browser cannot do it over fetch and half-duplex works through every proxy.
+// In TypeScript a server stream is an `AsyncIterable` (design §44 §7.1).
+//
+// A stream is the one call where a retry is not just "send it again": the
+// server hands out cursors, and a reconnect has to resume from the last one or
+// the client silently misses the changes in between. So `watch` tracks the
+// cursor of every message and, on a retryable failure, re-opens the stream from
+// it. The request that resumes is the stream's own business — `loams.live`'s
+// `WatchRequest.resume`, for instance — so the caller passes a `resume`
+// function and the runtime supplies the cursor.
+import { toLoamsError } from './errors.js';
+import { DEFAULT_MAX_RETRIES, backoffMs, shouldRetry, sleep } from './retry.js';
+/** The default cursor reader: a `cursor` field, which is what every stream in
+ * the API uses (§44 §7.4). */
+function cursorField(message) {
+    const value = message.cursor;
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/**
+ * A server stream that reconnects from its cursor.
+ *
+ * `loams.live.watch()` returns one of these. It yields until the stream ends;
+ * if the stream fails with a code a retry may answer and the call is retryable,
+ * it re-opens from the last cursor and carries on, so a node restart is a
+ * hiccup rather than a gap.
+ */
+export async function* watch(binding, open, request, options) {
+    const cursorOf = options.cursor ?? cursorField;
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const retrySafe = options.retrySafe ?? true;
+    let current = request;
+    let cursor;
+    let attempt = 0;
+    for (;;) {
+        try {
+            for await (const message of open(current, options)) {
+                // Progress earns a fresh budget: `maxRetries` bounds the retries in
+                // one *run* of disconnects, not for the life of the stream. A watch
+                // that recovers from a node restart and then runs for days must not
+                // spend its budget on the first failure of each of those days.
+                attempt = 0;
+                cursor = cursorOf(message) ?? cursor;
+                options.onCursor?.(cursor, message);
+                yield message;
+            }
+            return;
+        }
+        catch (thrown) {
+            const error = toLoamsError(thrown, binding.rpc);
+            if (!shouldRetry(error, retrySafe, attempt, maxRetries)) {
+                throw error;
+            }
+            current = options.resume(cursor, request);
+            await sleep(backoffMs(attempt), options.signal);
+            attempt += 1;
+        }
+    }
+}