@net-mesh/browser 0.37.0

package/dist/store/definition.js

@@ -0,0 +1,83 @@
+/**
+ * `defineStore` — the reusable typed description.
+ *
+ * It holds validators, never authority handlers, so a client bundle
+ * that joins a store does not carry the owner's gameplay code.
+ *
+ * It is not a pass-through. It checks the two properties whose
+ * violation is invisible until much later:
+ *
+ * 1. `empty()` must itself be a valid state. `empty()` is what a
+ *    replica installs when it loses visibility, so an `empty()` the
+ *    schema would reject means audience clearing fails at the worst
+ *    possible moment — mid-transition, with the old projection already
+ *    fenced.
+ * 2. `id` and `version` must be usable as an incarnation identity.
+ *    They travel in every envelope and a blank id or a non-integer
+ *    version turns a version-mismatch refusal into a confusing parse
+ *    error at the far end.
+ */
+import { StoreError } from './errors.js';
+import { compileVisibility } from './visibility.js';
+export function defineStore(definition) {
+    if (definition.id.length === 0) {
+        throw new StoreError('invalid-data', 'a store definition needs a non-empty id');
+    }
+    if (!Number.isSafeInteger(definition.version) || definition.version < 1) {
+        throw new StoreError('invalid-data', `store '${definition.id}' needs a positive integer version, got ${String(definition.version)}`);
+    }
+    // `empty()` is state, so it must pass the state validator. Checking
+    // it here fails at definition time — at the developer's desk —
+    // instead of during an audience transition in front of a player.
+    let empty;
+    try {
+        empty = definition.empty();
+    }
+    catch (error) {
+        throw new StoreError('invalid-data', `store '${definition.id}' could not build its empty state: ${String(error)}`, { cause: error });
+    }
+    try {
+        definition.state(empty);
+    }
+    catch (error) {
+        throw new StoreError('invalid-data', `store '${definition.id}': empty() is not a valid state, so a replica could not clear a projection with it: ${String(error)}`, { cause: error });
+    }
+    // Visibility rules that could not be enforced as written fail here,
+    // at the developer's desk, rather than at the first projection.
+    if (definition.visibility !== undefined) {
+        try {
+            compileVisibility(definition.visibility);
+        }
+        catch (error) {
+            throw new StoreError('invalid-data', `store '${definition.id}': ${error instanceof Error ? error.message : String(error)}`, {
+                cause: error,
+            });
+        }
+    }
+    if (definition.interest !== undefined) {
+        for (const [collection, key] of Object.entries(definition.interest)) {
+            if (collection.length === 0 || collection.includes('.') || typeof key !== 'function') {
+                throw new StoreError('invalid-data', `store '${definition.id}': interest maps a top-level collection name to a key function, got '${collection}'`);
+            }
+        }
+    }
+    if (definition.entities !== undefined) {
+        for (const [collection, parse] of Object.entries(definition.entities)) {
+            if (collection.length === 0 || collection.includes('.') || typeof parse !== 'function') {
+                throw new StoreError('invalid-data', `store '${definition.id}': entities maps a top-level collection name to a per-entity parser, got '${collection}'`);
+            }
+            const inEmpty = empty[collection];
+            if (inEmpty !== undefined && !isEntityMap(inEmpty)) {
+                throw new StoreError('invalid-data', `store '${definition.id}': entities names '${collection}', but empty().${collection} is not a record of entities`);
+            }
+        }
+    }
+    return Object.freeze({ ...definition });
+}
+/** A plain object: what an entity map is. */
+export function isEntityMap(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/store/errors.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The store's error taxonomy.
+ *
+ * One code per refusal a caller can act on differently. The codes are
+ * the design document's list
+ * (`docs/internal/plans/BROWSER_GAME_STORE_API_DESIGN.md` §2), and the
+ * one that carries a contract subtlety is {@link StoreErrorCode}
+ * `result-expired` — see its note below, because getting it wrong
+ * fabricates a success receipt.
+ */
+/**
+ * Why a store operation was refused.
+ *
+ * - `invalid-data` — a payload failed its validator.
+ * - `version-mismatch` — definition id/version disagreement.
+ * - `forbidden` — the owner's `authorize` refused.
+ * - `not-ready` — the handle has no live, synchronized view.
+ * - `capacity` — a declared bound was reached.
+ * - `timeout` / `aborted` — the caller's deadline or signal fired.
+ * - `indeterminate` — submitted, and no response established the outcome.
+ * - `owner-lost` — the store incarnation ended. Terminal: there is no
+ *   handle to obtain, because the owner that held the document is gone.
+ *   A closing host SAYS this, unsolicited, to every handle it holds
+ *   (`owner.farewell`) — silence is not an answer, and a replica whose
+ *   host closed used to learn nothing until its own deadline fired and
+ *   reported `indeterminate`. It is deliberately NOT `closed`: that
+ *   one is the expiry notice a replica rejoins on, and rejoining an
+ *   owner that is gone either hangs or silently attaches the caller to
+ *   a SUCCESSOR's different document under the handle it already had.
+ * - `closed` — **this handle is unusable**: unknown, expired, fenced by
+ *   the owner, or bound to another peer. Deliberately one code for all
+ *   four, so a refusal cannot disclose whether a handle exists. It is
+ *   terminal for the handle and for any action in flight on it —
+ *   nothing is replayed and no outcome is inferred, exactly as for
+ *   `result-expired` below — while the *subscription* is recoverable by
+ *   joining afresh, which yields a new handle rather than resuming the
+ *   old one.
+ * - `action-rejected` — the owner refused this action, or a handler broke
+ *   the synchronous-transaction contract.
+ * - `result-expired` — **this request cannot execute again, and its
+ *   original result is unavailable.** It asserts nothing about whether the
+ *   original attempt committed: a retired sequence may have been rejected,
+ *   aborted before commit, or fenced without ever executing. A
+ *   non-reexecution floor is not evidence of successful execution, so this
+ *   code must never be read — or reported — as a success receipt.
+ */
+/**
+ * The codes, as a runtime set.
+ *
+ * `no.code` on the wire is **exactly** this list (brief §2), so the
+ * parser needs it at runtime and not only in the type system: a code
+ * the caller cannot branch on is a refusal it cannot act on.
+ *
+ * {@link StoreErrorCode} is derived from it, so the two cannot drift —
+ * a code added to one and not the other would be a type the parser
+ * refuses or a wire value the caller cannot name.
+ */
+export declare const STORE_ERROR_CODES: readonly ["invalid-data", "version-mismatch", "forbidden", "not-ready", "capacity", "timeout", "aborted", "indeterminate", "owner-lost", "closed", "action-rejected", "result-expired"];
+export type StoreErrorCode = (typeof STORE_ERROR_CODES)[number];
+/** A refused store operation, carrying the code a caller branches on. */
+export declare class StoreError extends Error {
+    readonly code: StoreErrorCode;
+    constructor(code: StoreErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Whether a send failed because its stream belongs to a session that
+ * has been replaced — the ONE failure a reopen repairs.
+ *
+ * The leaf names it (`leaf/src/node.rs`): "stale stream handle:
+ * opened on incarnation N; reopen the stream". It is matched on the
+ * message because that is what crosses the wasm boundary; everything
+ * else — an oversized payload, a fenced id, a closed node — is
+ * permanent, and reopening for it burns a stream handle per frame.
+ */
+export declare function isStaleStream(error: unknown): boolean;

package/dist/store/errors.js

@@ -0,0 +1,94 @@
+/**
+ * The store's error taxonomy.
+ *
+ * One code per refusal a caller can act on differently. The codes are
+ * the design document's list
+ * (`docs/internal/plans/BROWSER_GAME_STORE_API_DESIGN.md` §2), and the
+ * one that carries a contract subtlety is {@link StoreErrorCode}
+ * `result-expired` — see its note below, because getting it wrong
+ * fabricates a success receipt.
+ */
+/**
+ * Why a store operation was refused.
+ *
+ * - `invalid-data` — a payload failed its validator.
+ * - `version-mismatch` — definition id/version disagreement.
+ * - `forbidden` — the owner's `authorize` refused.
+ * - `not-ready` — the handle has no live, synchronized view.
+ * - `capacity` — a declared bound was reached.
+ * - `timeout` / `aborted` — the caller's deadline or signal fired.
+ * - `indeterminate` — submitted, and no response established the outcome.
+ * - `owner-lost` — the store incarnation ended. Terminal: there is no
+ *   handle to obtain, because the owner that held the document is gone.
+ *   A closing host SAYS this, unsolicited, to every handle it holds
+ *   (`owner.farewell`) — silence is not an answer, and a replica whose
+ *   host closed used to learn nothing until its own deadline fired and
+ *   reported `indeterminate`. It is deliberately NOT `closed`: that
+ *   one is the expiry notice a replica rejoins on, and rejoining an
+ *   owner that is gone either hangs or silently attaches the caller to
+ *   a SUCCESSOR's different document under the handle it already had.
+ * - `closed` — **this handle is unusable**: unknown, expired, fenced by
+ *   the owner, or bound to another peer. Deliberately one code for all
+ *   four, so a refusal cannot disclose whether a handle exists. It is
+ *   terminal for the handle and for any action in flight on it —
+ *   nothing is replayed and no outcome is inferred, exactly as for
+ *   `result-expired` below — while the *subscription* is recoverable by
+ *   joining afresh, which yields a new handle rather than resuming the
+ *   old one.
+ * - `action-rejected` — the owner refused this action, or a handler broke
+ *   the synchronous-transaction contract.
+ * - `result-expired` — **this request cannot execute again, and its
+ *   original result is unavailable.** It asserts nothing about whether the
+ *   original attempt committed: a retired sequence may have been rejected,
+ *   aborted before commit, or fenced without ever executing. A
+ *   non-reexecution floor is not evidence of successful execution, so this
+ *   code must never be read — or reported — as a success receipt.
+ */
+/**
+ * The codes, as a runtime set.
+ *
+ * `no.code` on the wire is **exactly** this list (brief §2), so the
+ * parser needs it at runtime and not only in the type system: a code
+ * the caller cannot branch on is a refusal it cannot act on.
+ *
+ * {@link StoreErrorCode} is derived from it, so the two cannot drift —
+ * a code added to one and not the other would be a type the parser
+ * refuses or a wire value the caller cannot name.
+ */
+export const STORE_ERROR_CODES = [
+    'invalid-data',
+    'version-mismatch',
+    'forbidden',
+    'not-ready',
+    'capacity',
+    'timeout',
+    'aborted',
+    'indeterminate',
+    'owner-lost',
+    'closed',
+    'action-rejected',
+    'result-expired',
+];
+/** A refused store operation, carrying the code a caller branches on. */
+export class StoreError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'StoreError';
+        this.code = code;
+    }
+}
+/**
+ * Whether a send failed because its stream belongs to a session that
+ * has been replaced — the ONE failure a reopen repairs.
+ *
+ * The leaf names it (`leaf/src/node.rs`): "stale stream handle:
+ * opened on incarnation N; reopen the stream". It is matched on the
+ * message because that is what crosses the wasm boundary; everything
+ * else — an oversized payload, a fenced id, a closed node — is
+ * permanent, and reopening for it burns a stream handle per frame.
+ */
+export function isStaleStream(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes('stale stream handle');
+}

package/dist/store/host.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Slice G — `hostStore` and `joinStore` over a real session.
+ *
+ * This is the layer where the authenticated-origin gate is either
+ * satisfied or not, and it is three lines of it: a frame arrives as a
+ * `stream_data` event, the event carries `peerNode` — the peer whose
+ * installed session opened the packet — and that string is what goes
+ * into `owner.receive(frame, peer)`. Nothing in a store frame is
+ * consulted for identity, because no store frame has an originator
+ * field to consult (§1.3).
+ *
+ * ## What this module is typed against
+ *
+ * Not a port, not an adapter: the structural subset of the real
+ * `BrowserNode`/`MeshSession` surface that the store actually uses.
+ * Both satisfy {@link StoreTransport} as they are, so there is no
+ * second implementation of anything, and a test can drive the same
+ * type without a mesh.
+ *
+ * ## The gate this slice does NOT clear
+ *
+ * §4 gates G on leader-proxy lifecycle: follower tabs, last-consumer
+ * cleanup, the peer/stream lifecycle on a proxied handle. A
+ * `ProxyStream` now carries its peer (6256f970b) which is the
+ * precondition, but the *store's* use of it on a follower is not
+ * established, and nothing here claims it is.
+ */
+import { StoreOwner, type Dispatched, type OwnerDeps, type Viewer } from './owner.js';
+import type { ActionSpec, Cancel, EntityCollection, EntityOf, InputSpec, StoreDefinition } from './types.js';
+import { type Hex } from './wire.js';
+/** How often a host expires handles whose lease has run out (§2). */
+export declare const HOST_SWEEP_MS = 5000;
+/**
+ * How long `close()` will wait for one goodbye to flush.
+ *
+ * A page tearing down cannot wait forever to be polite, and a
+ * transport whose `send` never settles would otherwise make `close()`
+ * never return — a review probe held one and measured exactly that.
+ * Short, because the alternative to a bounded wait is a hang, and the
+ * frame is not retried afterwards: a farewell that missed its window
+ * is a counted loss.
+ *
+ * HALF A SECOND, not two: the first version chose two and a review
+ * probe — which allowed 750 ms for `close()` to return — read that as
+ * an unbounded close, and it was right to. A page tearing down has an
+ * unload budget under a second, and a frame that has not flushed on a
+ * live DataChannel in 500 ms is not going to matter to the replica
+ * that was going to receive it.
+ */
+export declare const FAREWELL_DEADLINE_MS = 500;
+/** One frame, as the transport carries it. */
+export type Frame = Uint8Array;
+/** The subset of a stream the store writes to and reads from. */
+export interface TransportStream {
+    send(payload: Frame): Promise<void> | void;
+    close(): void;
+}
+/** A `stream_data` arrival, narrowed to what the store reads. */
+export interface TransportFrame {
+    readonly type: string;
+    readonly streamId?: string;
+    /** The authenticated peer. The store's only source of identity. */
+    readonly peerNode?: string | null;
+    readonly payload?: Frame;
+}
+/**
+ * The structural subset of `BrowserNode` / `MeshSession` the store uses.
+ *
+ * `openStream` is synchronous on the direct node and a promise on a
+ * session, so this accepts either and the store awaits both.
+ */
+export interface StoreTransport {
+    /** This node's id — the authority a replica is talking to. */
+    nodeIdHex(): string | null;
+    /**
+     * Open a stream to a peer.
+     *
+     * **`label`, never `streamId`.** A stream id is a `u64` the leaf
+     * DERIVES from the label, and it sets a discriminator bit that makes
+     * an unsolicited arrival classify as stream data at the far end
+     * rather than as a channel message. Passing a textual id is refused
+     * by the wasm option reader outright, and passing an arbitrary
+     * number loses the discriminator — so the label is the only correct
+     * input and both ends derive the same id from it without exchanging
+     * one.
+     */
+    openStream(options: {
+        reliability: 'reliable' | 'fireAndForget';
+        peer?: string;
+        label?: string;
+        /**
+         * Ride the lossy carrier (fire-and-forget only): unordered, no
+         * retransmits, never delaying anything else. A transport without one
+         * may ignore it and send the packets like any others.
+         */
+        lossy?: boolean;
+    }): TransportStream | Promise<TransportStream>;
+    onEvent(handler: (event: TransportFrame) => void): Cancel;
+    /**
+     * Make sure there IS a session with this peer, if the transport can.
+     *
+     * `openStream({peer})` refuses a peer the node has no session with,
+     * and a session — even a relayed one — is installed by a peer
+     * ATTEMPT (§9 step 2, `ensure_relayed_session`), not by discovery.
+     * So a store that only discovered its host still could not send it
+     * anything: `session: no session with 0x…`, which is what the real
+     * browser harness reports.
+     *
+     * Optional, because a transport that needs no such step (an
+     * in-process one, or a page that already connected the peer itself)
+     * should not have to pretend to offer it. When it is absent, or it
+     * fails, the store still tries to open — and the typed refusal from
+     * `openStream` is the honest answer rather than a second guess.
+     */
+    connectPeer?(peerHex: string): Promise<unknown>;
+}
+/**
+ * A peer id in the spelling `openStream` takes: 16 lowercase hex.
+ *
+ * Events carry the authenticated peer as an EXACT DECIMAL string, and
+ * `openStream({ peer })` requires 16 hex digits. Handing the decimal
+ * straight back is rejected for a short id and — worse — names a
+ * DIFFERENT peer for a 16-digit decimal one, which is a cross-peer
+ * defect wearing the shape of a formatting bug. `LeafStream` already
+ * reconciles the two spellings through `BigInt`; this is the same
+ * reconciliation for the store's own seam.
+ */
+export declare function peerHexOf(peer: string): string | null;
+/** Whether two peer spellings name the same node. */
+export declare function samePeer(left: string, right: string): boolean;
+/**
+ * How a host decides what each replica sees: exactly one of these.
+ *
+ * - `project(state, audience)` — one view per audience, shared by
+ *   every player reading it. The default choice.
+ * - `projectFor(state, { peer, audience })` — one view per player, for
+ *   what differs by who is looking (your own hand). Costs one
+ *   projection per player per change.
+ */
+export type HostProjection<S extends object> = {
+    project(state: S, audience: readonly string[]): S;
+    readonly projectFor?: never;
+} | {
+    projectFor(state: S, viewer: Viewer): S;
+    readonly project?: never;
+} | {
+    /** Neither: the definition's declared `visibility` alone decides. */
+    readonly project?: never;
+    readonly projectFor?: never;
+};
+/** What a host needs beyond the owner's own dependencies. */
+export type HostStoreOptions<S extends object, A extends ActionSpec, I extends InputSpec> = HostStoreBaseOptions<S, A, I> & HostProjection<S>;
+/** {@link HostStoreOptions} without the projection. */
+export interface HostStoreBaseOptions<S extends object, A extends ActionSpec, I extends InputSpec> extends Omit<OwnerDeps<S, A, I>, 'maxEventBytes' | 'newHandle' | 'newIncarnation' | 'now' | 'canProject' | 'store' | 'project' | 'projectFor'> {
+    readonly transport: StoreTransport;
+    /**
+     * WHICH store of this definition this is — the address a joiner
+     * names. Defaults to the definition id, which is what a node
+     * serving a single store of it means.
+     *
+     * A node hosting SEVERAL stores of one definition MUST name each,
+     * and their joiners must ask for them by name: every host store on
+     * a node sees every frame, so this is the only thing that decides
+     * which one answers.
+     */
+    readonly store?: string;
+    /** The stream id both sides address. One label per store. */
+    readonly streamId?: string;
+    readonly maxEventBytes: number;
+    readonly initialState: S;
+    /**
+     * Development checks: `true` warns through `console.warn`, a function
+     * receives the messages. It says so when every player would receive
+     * the whole state without the definition declaring `visibility:
+     * 'open'`, and when a projection fails the state validator (which
+     * otherwise sends the player `empty()` silently). Leave it off in
+     * production.
+     */
+    readonly dev?: boolean | ((message: string) => void);
+    now?: () => number;
+    newHandle?: () => Hex;
+    newIncarnation?: () => Hex;
+    canProject?: () => boolean;
+    /** Elapsed-time driver, so a test does not need real timers. */
+    schedule?: (run: () => void, ms: number) => Cancel;
+}
+/** The authoritative store, served to whoever the transport authenticates. */
+export interface HostedStoreHandle<S extends object, A extends ActionSpec = ActionSpec, I extends InputSpec = InputSpec> {
+    /** This node's id: the authority every replica is talking to. */
+    readonly authority: string;
+    /** The definition this store serves. */
+    readonly definition: StoreDefinition<S, A, I>;
+    getState(): S;
+    subscribe(listener: (state: S, previous: S) => void): Cancel;
+    setState(next: S): void;
+    /**
+     * Write entities of a collection declared in the definition's
+     * `entities`: `id → value`, or `id → undefined` to remove one. Only the
+     * written entities are validated (by their per-entity parser); the
+     * whole-document `state` validator does not run, so a tick that moves a
+     * few ships out of thousands costs what it touches. One revision, one
+     * delta, however many ids.
+     */
+    setEntities<C extends EntityCollection<S>>(collection: C, changes: Readonly<Record<string, EntityOf<S, C> | undefined>>): void;
+    /** {@link setEntities} for one id; `undefined` removes it. */
+    setEntity<C extends EntityCollection<S>>(collection: C, id: string, value: EntityOf<S, C> | undefined): void;
+    /**
+     * Handles, ledgers and pending projections, for a bounds report; and
+     * `sparseViews`, how many per-view deltas were projected from the changed
+     * entities alone (an entity write on a collection declared in both
+     * `interest` and `entities`, with only declared visibility rules).
+     */
+    counts(): {
+        readonly handles: number;
+        readonly ledgers: number;
+        readonly deferred: number;
+        readonly sparseViews: number;
+    };
+    counters(): Readonly<Record<string, number>>;
+    close(): Promise<void>;
+}
+/**
+ * What {@link hostPlayer} needs from a hosted store and nothing else
+ * does: its owner, the path that sends what a local call dispatched,
+ * and whether the store is still serving. Package-internal — keyed on
+ * the handle object, so only a handle `hostStore` returned has one.
+ */
+export interface HostInternals<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly owner: StoreOwner<S, A, I>;
+    readonly peer: string;
+    readonly maxEventBytes: number;
+    dispatched(result: Dispatched): void;
+    isClosed(): boolean;
+    onClose(listener: () => void): void;
+}
+/** The internals of a handle `hostStore` returned, or `undefined`. */
+export declare function hostInternals<S extends object, A extends ActionSpec, I extends InputSpec>(handle: HostedStoreHandle<S, A, I>): HostInternals<S, A, I> | undefined;
+/**
+ * Serve one store to the mesh.
+ *
+ * Every inbound frame is dispatched with the peer the TRANSPORT
+ * authenticated. A frame whose event carries no peer is dropped and
+ * counted rather than dispatched with a guess: on a follower's proxied
+ * handle that field was once absent, and admitting those frames is the
+ * cross-peer admixture the identity work removed.
+ */
+export declare function hostStore<S extends object, A extends ActionSpec, I extends InputSpec>(options: HostStoreOptions<S, A, I>): HostedStoreHandle<S, A, I>;