@net-mesh/browser 0.37.0

package/dist/org.d.ts

@@ -0,0 +1,412 @@
+/**
+ * Organization-scoped streaming, as a page wants it (plan §4.5).
+ *
+ * The eight org verbs — {@link OrgUnaryHandler call}, streaming,
+ * client-streaming and duplex, each calling and serving — share one
+ * credential/option vocabulary and one terminal error taxonomy
+ * (`errors.ts`'s `OrgStreamError` family). The same eight names exist
+ * on {@link BrowserNode} and on {@link MeshSession}; the wrappers here
+ * serve both, so the two surfaces cannot drift into two spellings of
+ * one contract.
+ *
+ * **Suspension and closure (plan §4.5).** Deadlines are absolute: a
+ * frozen tab extends no lease and no window, so a call whose deadline
+ * passes while its tab is suspended retires with its deadline
+ * terminal on wake — {@link OrgTimeoutError}, or
+ * {@link OrgIndeterminateError} where the work may already be
+ * executing in another tab. Nothing resumes automatically: a retired
+ * call is never transparently re-opened, because re-opening is a
+ * fresh call with a fresh proof and MAY repeat effects. Node or tab
+ * close retires ownership — pending calls fail typed, and each
+ * dropped caller handle emits exactly one CANCEL.
+ *
+ * **Handler drop (F-S3.1-2), verbatim.** The retire supervisor may
+ * drop the handler future without a final poll — cancellation is
+ * observed through the retirement observables (the terminal item, the
+ * sink's typed closed refusal, and `retired`), never assumed as a
+ * handler-side event; a detached observer holding `retired` observes
+ * the signal. After retirement a handler sees typed refusals from
+ * `send`/`close`, and any return value it produces is discarded.
+ */
+import { type OrgRetireReason, type OrgStreamError } from './errors.js';
+import type { LeafWasmOrgByteStreamHandle, LeafWasmOrgCallOptions, LeafWasmOrgClientStreamHandler, LeafWasmOrgDuplexCallHandle, LeafWasmOrgDuplexHandler, LeafWasmOrgRequestStreamHandle, LeafWasmOrgResponseSinkHandle, LeafWasmOrgServeHandle, LeafWasmOrgStreamingHandler, LeafWasmOrgUnaryHandler, LeafWasmOrgUploadCallHandle, LeafWasmOrgCaller, LeafWasmOrgServeOptions } from './wasm.js';
+/**
+ * The credential set one org call presents.
+ *
+ * The proofs are the caller's own bytes — this package carries them
+ * and never mints, re-derives or interprets them. No TypeScript crypto
+ * or authority implementation exists here by design (plan §4.5).
+ */
+export interface OrgCallCredentials {
+    /** The caller's membership certificate, its 156-byte wire form. */
+    membership: Uint8Array;
+    /** The dispatcher grant, its wire form. */
+    dispatcher: Uint8Array;
+    /** The capability grant, its wire form, when the call carries one. */
+    capabilityGrant?: Uint8Array;
+    /** The org the caller acts as. */
+    actingOrg: string;
+    /** The org that owns the provider. */
+    providerOwnerOrg: string;
+    /** The provider, exactly as the call addresses it. */
+    provider: string;
+    /** Proof freshness bound, seconds. */
+    proofTtlSecs?: number;
+}
+/** Options for the four org call verbs. */
+export interface OrgCallOptions {
+    credentials: OrgCallCredentials;
+    /**
+     * The call's deadline, milliseconds. **Absolute**, in the
+     * suspension contract's sense: a frozen tab extends it by nothing,
+     * and on wake an overdue call retires with its deadline terminal.
+     */
+    deadlineMs?: number;
+    /**
+     * Initial response-direction flow-control window, **chunk
+     * credits** — the wire header's unit: one credit permits one item
+     * frame, whatever the item's byte size. NOT bytes; a byte count
+     * here reads as a huge credit budget and nothing ever parks.
+     */
+    streamWindowInitial?: number;
+    /**
+     * Initial request-direction flow-control window, **chunk
+     * credits** (as {@link OrgCallOptions.streamWindowInitial}).
+     */
+    requestWindowInitial?: number;
+}
+/** Options for the four org serve verbs. */
+export interface OrgServeOptions {
+    /** The org that owns the provider side of every admitted call. */
+    ownerOrg: string;
+}
+/**
+ * Which authority admits a served call: `'same-org'` is owner-org
+ * traffic only, `'granted'` admits capability grants too. Anything
+ * else is refused loudly at registration.
+ */
+export type OrgAccess = 'same-org' | 'granted';
+/**
+ * The verified caller attribution a handler receives. Every field is
+ * the leaf's own verified reading — `entity` is 64 hex digits — and
+ * none of it is caller-asserted at the handler.
+ */
+export interface OrgCaller {
+    /** The caller's entity id, 64 hex digits. */
+    entity: string;
+    /** The org the caller acted as. */
+    actingOrg: string;
+    /** The org that owns this provider. */
+    providerOrg: string;
+    /** The provider, exactly as the call addressed it. */
+    provider: string;
+    /** The capability the admission covered. */
+    capability: string;
+    /** Whether the caller acted inside `providerOrg`. */
+    isSameOrg: boolean;
+}
+/**
+ * The response half of an org call: pull items, or cancel.
+ *
+ * `next()`'s terminal error item carries the §4.3 typed error —
+ * `AdmissionDenied('denied')` ({@link OrgRevokedError} where the cause
+ * was revocation), {@link OrgTimeoutError}, {@link OrgCancelledError},
+ * and the rest of the `OrgStreamError` family. The async iterator
+ * **throws** that typed error at the terminal error item, which is
+ * idiomatic for `for await`; a clean end is a plain loop end.
+ */
+export interface OrgByteStream {
+    next(): Promise<{
+        done: boolean;
+        value?: Uint8Array;
+        error?: OrgStreamError;
+    }>;
+    /**
+     * Drop this caller handle — exactly one CANCEL leaves, and the
+     * stream's terminal becomes {@link OrgCancelledError}.
+     */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+/**
+ * A client-streaming upload: send bodies, then `finish()` for the
+ * reply. `finish()` rejects with the typed terminal error.
+ */
+export interface OrgUploadCall {
+    send(payload: Uint8Array): Promise<void>;
+    /** Half-close the upload and await the reply. */
+    finish(): Promise<Uint8Array>;
+    /** Drop this caller handle — exactly one CANCEL leaves. */
+    cancel(): void;
+}
+/**
+ * The upload half of a duplex call. The caller-side sink has
+ * `finishSending`/`cancel` and deliberately no `retired`: its
+ * retirement is the stream's terminal item, one observable per side.
+ */
+export interface OrgDuplexSink {
+    send(payload: Uint8Array): Promise<void>;
+    /** Half-close the request direction; the response direction runs on. */
+    finishSending(): Promise<void>;
+    /** Drop this caller handle — exactly one CANCEL leaves. */
+    cancel(): void;
+}
+/** The two halves of a duplex call. */
+export interface OrgDuplexHandles {
+    sink: OrgDuplexSink;
+    stream: OrgByteStream;
+}
+/**
+ * The response sink a streaming or duplex **handler** receives.
+ *
+ * **Handler drop (F-S3.1-2), verbatim.** The retire supervisor may
+ * drop the handler future without a final poll — cancellation is
+ * observed through the retirement observables (the terminal item, the
+ * sink's typed closed refusal, and `retired`), never assumed as a
+ * handler-side event; a detached observer holding `retired` observes
+ * the signal. After retirement `send`/`close` refuse typed with THE
+ * closed refusal ({@link ORG_SINK_CLOSED_REFUSAL} — one text whatever
+ * the verdict, matching the leaf's own hardening byte for byte) and a
+ * handler return value is discarded.
+ */
+export interface OrgResponseSink {
+    send(payload: Uint8Array): Promise<void>;
+    /** Half-close the response direction: the call's normal ending. */
+    close(): Promise<void>;
+    /**
+     * THE retirement signal. Resolves with exactly
+     * one of {@link OrgRetireReason}'s verdicts when — and only when —
+     * this sink is retired before its call completed. On normal
+     * completion the call's own terminal settles every consumer and
+     * this promise stays pending: hold it as a signal, not a completion
+     * latch. Memoized at construction — one `retired()` crosses the
+     * boundary, and a detached observer holding this promise observes
+     * the signal.
+     */
+    retired: Promise<OrgRetireReason>;
+}
+/**
+ * The request stream a client-streaming or duplex **handler**
+ * receives.
+ *
+ * Its `next()` has **no** error arm: this stream's termination is
+ * observed ONLY through {@link OrgRequestStream.retired}, and
+ * iteration ends at the `done` item. The F-S3.1-2 level is the same
+ * as {@link OrgResponseSink}'s — the retire supervisor may drop the
+ * handler future without a final poll, and the retirement observables
+ * (the `done` terminal item, the sink's typed closed refusal, and
+ * `retired`) are the only reliable cancellation record; a detached
+ * observer holding `retired` observes the signal.
+ */
+export interface OrgRequestStream {
+    next(): Promise<{
+        done: boolean;
+        value?: Uint8Array;
+    }>;
+    /** As {@link OrgResponseSink.retired} — one verdict, memoized. */
+    retired: Promise<OrgRetireReason>;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+/**
+ * One serve registration.
+ *
+ * **`close()` is a retirement, not a graceful unregister (C9's
+ * protected split).** Closing an org serve handle retires its live
+ * protected calls — each with its exact retirement terminal, the
+ * deadline/cancel/revocation vocabulary — and refuses new openings on
+ * that service. This is deliberately NOT the public path's
+ * let-existing-calls-finish behavior.
+ */
+export interface OrgServeHandle {
+    readonly service: string;
+    close(): void;
+}
+/** The unary org handler: one request in, one reply out. */
+export type OrgUnaryHandler = (caller: OrgCaller, request: Uint8Array) => Promise<Uint8Array>;
+/** The server-streaming org handler: one request in, items out. */
+export type OrgStreamingHandler = (caller: OrgCaller, request: Uint8Array, sink: OrgResponseSink) => Promise<void>;
+/** The client-streaming org handler: requests in, one reply out. */
+export type OrgClientStreamHandler = (caller: OrgCaller, requests: OrgRequestStream) => Promise<Uint8Array>;
+/** The duplex org handler: requests in, items out, independently. */
+export type OrgDuplexHandler = (caller: OrgCaller, requests: OrgRequestStream, sink: OrgResponseSink) => Promise<void>;
+/**
+ * A live caller-side org handle its owner may have to retire — the
+ * registration {@link OrgHandleRegistry} keeps.
+ */
+export interface OrgCallHandle {
+    /**
+     * Retire it now: at most one CANCEL leaves, and every parked
+     * consumer settles with `error` as its typed terminal.
+     */
+    retire(error: OrgStreamError): void;
+}
+/**
+ * The live org handles one node or session handed out, so its
+ * teardown can retire them: node close retires ownership — pending
+ * calls fail typed, one CANCEL per dropped caller handle.
+ */
+export declare class OrgHandleRegistry {
+    private readonly live;
+    add(handle: OrgCallHandle): void;
+    delete(handle: OrgCallHandle): void;
+    /**
+     * Retire every live handle with one typed terminal. Drains first,
+     * so a handle's own teardown cannot re-enter this loop. Every
+     * handle is attempted; the raw failures come back rather than being
+     * swallowed, for the owner's teardown ledger.
+     */
+    retireAll(error: OrgStreamError): unknown[];
+}
+/**
+ * The response half of an org call, wrapped: terminal items become
+ * the §4.3 typed errors, and the async iterator throws them.
+ */
+export declare class OrgStream implements OrgByteStream, OrgCallHandle {
+    private readonly inner;
+    private readonly onCancel;
+    private readonly onDone?;
+    private terminal;
+    /** A boundary rejection, latched so a second pull sees the same typed failure. */
+    private failure;
+    private handleDropped;
+    private readonly waiters;
+    /**
+     * @param `onCancel` drops the underlying handle — at most once, so
+     * one CANCEL leaves however many halves initiate the drop.
+     */
+    constructor(inner: LeafWasmOrgByteStreamHandle, onCancel: () => void, onDone?: (() => void) | undefined);
+    next(): Promise<ByteItemOut>;
+    cancel(): void;
+    /**
+     * Retire this stream: one CANCEL at most, every parked and future
+     * `next()` settled with `error` as the terminal item.
+     */
+    retire(error: OrgStreamError): void;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    private complete;
+    private fail;
+    private dropHandle;
+}
+/** A client-streaming upload, wrapped. */
+export declare class OrgUpload implements OrgUploadCall, OrgCallHandle {
+    private readonly inner;
+    private readonly onDone?;
+    private failure;
+    private handleDropped;
+    private readonly waiters;
+    constructor(inner: LeafWasmOrgUploadCallHandle, onDone?: (() => void) | undefined);
+    send(payload: Uint8Array): Promise<void>;
+    finish(): Promise<Uint8Array>;
+    cancel(): void;
+    /** Retire this upload: one CANCEL at most; parked `finish()` rejects typed. */
+    retire(error: OrgStreamError): void;
+}
+/** A duplex call, wrapped: one call-level CANCEL however both halves end. */
+export declare class OrgDuplex implements OrgDuplexHandles, OrgCallHandle {
+    private readonly inner;
+    private readonly onDone?;
+    /** The two halves share one drop, so one CANCEL leaves per call. */
+    private handleDropped;
+    private failure;
+    readonly sink: OrgDuplexSink;
+    readonly stream: OrgStream;
+    constructor(inner: LeafWasmOrgDuplexCallHandle, onDone?: (() => void) | undefined);
+    /** Retire the whole call: one CANCEL, both halves settled typed. */
+    retire(error: OrgStreamError): void;
+    private dropHandle;
+}
+/**
+ * The response sink a handler receives, wrapped. `retired` is
+ * memoized at construction — the boundary's `retired()` is called
+ * exactly once and the one signal is what a detached observer holds.
+ */
+export declare class OrgSink implements OrgResponseSink {
+    private readonly inner;
+    readonly retired: Promise<OrgRetireReason>;
+    private verdict;
+    constructor(inner: LeafWasmOrgResponseSinkHandle);
+    send(payload: Uint8Array): Promise<void>;
+    /** Half-close the response direction: the call's normal ending. */
+    close(): Promise<void>;
+}
+/**
+ * The request stream a handler receives, wrapped. Its terminal is the
+ * `done` item; the abnormal record is `retired`, memoized once as
+ * {@link OrgResponseSink.retired} is.
+ */
+export declare class OrgRequests implements OrgRequestStream {
+    private readonly inner;
+    readonly retired: Promise<OrgRetireReason>;
+    private verdict;
+    private readonly waiters;
+    constructor(inner: LeafWasmOrgRequestStreamHandle);
+    next(): Promise<{
+        done: boolean;
+        value?: Uint8Array;
+    }>;
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    private settle;
+}
+/**
+ * One serve registration, wrapped. `close()` is C9's protected-split
+ * retirement: it retires the registration's live protected calls with
+ * their exact terminals and refuses new openings on the service.
+ */
+export declare class OrgServe implements OrgServeHandle, OrgCallHandle {
+    private readonly inner;
+    private readonly onDone?;
+    private closed;
+    constructor(inner: LeafWasmOrgServeHandle, onDone?: (() => void) | undefined);
+    get service(): string;
+    /**
+     * **A retirement, not a graceful unregister (C9's protected
+     * split).** Every live protected call this registration admitted is
+     * retired with its exact retirement terminal — the
+     * deadline/cancel/revocation vocabulary — and new openings on the
+     * service are refused. Deliberately NOT the public path's
+     * let-existing-calls-finish behavior.
+     */
+    close(): void;
+    /** The registry's teardown verb: for a registration it is `close()`. */
+    retire(_error: OrgStreamError): void;
+}
+/**
+ * Build exactly the options object `call_org*` reads.
+ *
+ * A fresh object, so a caller mutating its own afterwards cannot
+ * change a call already in flight. The byte fields are forwarded as
+ * the `Uint8Array`s they must be — the leaf refuses anything else
+ * loudly, and a silent re-encode here would be a second codec.
+ */
+export declare function toWasmOrgCallOptions(options: OrgCallOptions): LeafWasmOrgCallOptions;
+/** Build exactly the options object `serve_org*` reads. */
+export declare function toWasmOrgServeOptions(options: OrgServeOptions): LeafWasmOrgServeOptions;
+/**
+ * Read one handler invocation's caller attribution.
+ *
+ * The boundary hands the crate's `to_json` JSON **string** (the same
+ * convention `on_event` uses), camelCase keys verbatim
+ * {@link OrgCaller}'s; anything that does not parse to an object is
+ * refused rather than served with an attribution this build cannot
+ * vouch for.
+ */
+export declare function parseOrgCaller(raw: LeafWasmOrgCaller): OrgCaller;
+/** Adapt a unary handler to the boundary's `(caller, request)` trampoline. */
+export declare function unaryOrgTrampoline(handler: OrgUnaryHandler): LeafWasmOrgUnaryHandler;
+/**
+ * Adapt a streaming handler to `(caller, request, sink)`. The sink is
+ * wrapped once per invocation; its `retired` is the one signal the
+ * F-S3.1-2 level names.
+ */
+export declare function streamingOrgTrampoline(handler: OrgStreamingHandler): LeafWasmOrgStreamingHandler;
+/** Adapt a client-streaming handler to `(caller, requests)`. */
+export declare function clientStreamOrgTrampoline(handler: OrgClientStreamHandler): LeafWasmOrgClientStreamHandler;
+/** Adapt a duplex handler to `(caller, requests, sink)`. */
+export declare function duplexOrgTrampoline(handler: OrgDuplexHandler): LeafWasmOrgDuplexHandler;
+/** One `OrgByteStream.next()` outcome — the contract's inline shape. */
+type ByteItemOut = {
+    done: boolean;
+    value?: Uint8Array;
+    error?: OrgStreamError;
+};
+export {};