@net-mesh/browser 0.37.0

package/dist/store/owner.d.ts

@@ -0,0 +1,616 @@
+/**
+ * Owner dispatch: join, admission, `authorize`, projection, `man`
+ * (brief §1.3, §1.5, §1.12, §2) — slice C.
+ *
+ * ## The authenticated origin is an argument, never a field
+ *
+ * {@link StoreOwner.receive} takes the **authenticated originating
+ * peer** as a parameter, and there is no way to name a caller inside a
+ * store frame at all (§2's shapes have no originator field). That is
+ * the whole of §1.3's rule expressed as a signature: the identity comes
+ * from the session the bytes arrived on, which the transport
+ * authenticated — `LeafEvent::StreamData.peer_node` on the Rust side,
+ * `LeafStream.peerNode` in the package — and a dispatcher cannot read
+ * it off the payload because the payload does not carry one.
+ *
+ * A caller could still *lie to this function*, so the contract is
+ * stated where it is enforceable: whoever calls `receive` must pass the
+ * peer the transport proved, and the store's own entry points will
+ * (slice G). Nothing here can make a wrong argument right, and
+ * pretending otherwise is the mistake this module refuses to make.
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * Here: `join` admission, handle binding and re-checking, `authorize`
+ * for the read request, the audience projection, and the `man` + `snap`
+ * emission that follows. Refusals for the paths that reach those.
+ *
+ * Not here: `act`/`in`/`res` and the ledger (slice E), `aud`/`resume`
+ * transitions (slice F), `delta` emission (slice D). Those kinds are
+ * refused `not-ready` or `invalid-data` rather than half-implemented,
+ * and the refusal says which layer owns them.
+ */
+import { Assembly, AssemblyTable } from './assembly.js';
+import type { JsonValue } from './json.js';
+import { type Outcome } from './ledger.js';
+import type { AccessRequest, ActionContext, Cancel, ActionSpec, InputSpec, Parse, StoreDefinition } from './types.js';
+import { type Hex } from './wire.js';
+/** Actions in flight per owner, against the pending bound (§2). */
+export declare const MAX_PENDING_ACTIONS = 32;
+/** Handles one owner will hold (brief §2). */
+export declare const MAX_HANDLES = 256;
+/** How long a handle lives without an accepted authenticated message. */
+export declare const HANDLE_LEASE_MS = 60000;
+/** What the owner needs from its host. */
+export interface OwnerDeps<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly definition: StoreDefinition<S, A, I>;
+    /**
+     * WHICH store of this definition this owner is — the address a
+     * joiner names in `join.store`.
+     *
+     * A node may host several stores of one definition (a lobby and a
+     * match; three worlds in a harness), every host store on that node
+     * receives every frame, and a `join` names no handle. So without
+     * this, the store that answers a join is whichever listener
+     * happened to be registered first — and a caller asking for B got
+     * A's document, A's handle and A's state mutated by its actions.
+     * Found by review: two COLD stores, join the second, and the first
+     * answers.
+     */
+    readonly store: string;
+    /**
+     * The owner's policy. Receives the **authenticated** caller, because
+     * that is the only identity this module will ever hand it.
+     */
+    authorize(request: AccessRequest<A, I>): boolean;
+    /**
+     * The audience projection: what this caller may see. Returning the
+     * whole state is a decision, not a default — `empty()` is what
+     * absence looks like.
+     *
+     * Computed once per DISTINCT audience and shared by every handle
+     * carrying it. Exactly one of `project` and {@link projectFor} is
+     * given.
+     */
+    project?(state: S, audience: readonly string[]): S;
+    /**
+     * The per-player projection: what THIS player may see — their own
+     * hand, their own fog of war. Handed the authenticated peer with the
+     * audience it reads.
+     *
+     * Computed once per distinct (peer, audience) pair, so its cost per
+     * change grows with the number of players, where `project`'s grows
+     * with the number of distinct audiences. That is inherent: a view
+     * that depends on who is looking has to be taken for each of them.
+     */
+    projectFor?(state: S, viewer: Viewer): S;
+    /**
+     * The one hook for things that happen to players: `join`, `leave`,
+     * `area`. Runs on the host as a transaction with the player as
+     * `context.peer`, exactly like an action handler — so it can
+     * `setState` (a starting inventory on join) — and its changes reach
+     * every replica. Synchronous; a throw discards its writes.
+     */
+    onEvent?(event: StoreEvent, context: ActionContext<S>): void;
+    /**
+     * Development warnings: a store that sends everything to everyone
+     * without saying so, a projection the state validator refuses. Off
+     * unless given; never on by default in production.
+     */
+    warn?(message: string): void;
+    /**
+     * Which area a player is in, for `area` events: any string (a zone,
+     * a room, a grid cell), or `null` for none. Read-only; called after
+     * changes, for each present player.
+     */
+    areaOf?(state: S, peer: string): string | null;
+    /** The admissible frame size, derived from the transport (§1.9). */
+    readonly maxEventBytes: number;
+    /** Monotone clock, milliseconds. */
+    now(): number;
+    /** 32 lowercase hex. Unguessable: a handle is a capability. */
+    newHandle(): Hex;
+    /** 16 lowercase hex, one per owner incarnation. */
+    newIncarnation(): Hex;
+    /**
+     * Whether a projection can be taken right now.
+     *
+     * A host that is mid-frame, or whose world is being rebuilt, answers
+     * `false` and the control is DEFERRED rather than refused (§1.8) — a
+     * control is never answered `not-ready`.
+     */
+    canProject(): boolean;
+    /**
+     * The action handlers, one per declared action.
+     *
+     * Each runs inside ONE synchronous transaction: it stages writes
+     * through its context and returns the output, or throws to reject.
+     * A throw is an `action-rejected` outcome that is RETAINED (§1.10),
+     * not an absent one.
+     */
+    readonly actions: ActionHandlers<S, A>;
+    /** The latest-value input handlers. Fire-and-forget, no reply. */
+    readonly inputs: InputHandlers<S, I>;
+}
+/** Why a player left, as `onEvent` hears it. */
+export type LeaveReason = 
+/** The player closed their handle. */
+'left'
+/** Its lease ran out: a closed tab, a lost connection. */
+ | 'expired'
+/** `authorize` stopped granting its read: a kick, a revoked permission. */
+ | 'refused'
+/** Its view could not be delivered (too large, or `project` failed). */
+ | 'dropped';
+/**
+ * What happened to a player, for the host's single `onEvent` hook.
+ *
+ * - `join`: a player arrived — their first subscription, or the host's
+ *   own player (`hostPlayer`). Per player, not per connection.
+ * - `leave`: their last subscription ended, and why.
+ * - `area`: `areaOf(state, peer)` gave a different answer than it last
+ *   did for them (`from` is `null` the first time).
+ */
+export type StoreEvent = {
+    readonly type: 'join';
+    readonly peer: string;
+    readonly audience: readonly string[];
+} | {
+    readonly type: 'leave';
+    readonly peer: string;
+    readonly reason: LeaveReason;
+} | {
+    readonly type: 'area';
+    readonly peer: string;
+    readonly from: string | null;
+    readonly to: string | null;
+};
+/** How many hook runs one drain may perform before it stops (see `drainEvents`). */
+export declare const MAX_EVENT_ROUNDS = 256;
+/** Who a per-player projection is for. */
+export interface Viewer {
+    /** The authenticated peer, 16 lowercase hex — as `context.peer`. */
+    readonly peer: string;
+    /** The audience this handle reads. */
+    readonly audience: readonly string[];
+}
+/** One handler per declared action. */
+export type ActionHandlers<S extends object, A extends ActionSpec> = {
+    readonly [K in keyof A]: (input: A[K]['input'], context: ActionContext<S>) => A[K]['output'];
+};
+/** One handler per declared input. */
+export type InputHandlers<S extends object, I extends InputSpec> = {
+    readonly [K in keyof I]: (input: I[K], context: ActionContext<S>) => void;
+};
+/** One admitted subscription. */
+export interface OwnerHandle {
+    readonly h: Hex;
+    readonly inc: Hex;
+    /** The authenticated peer this handle is bound to (§1.3). */
+    readonly peer: string;
+    readonly audience: readonly string[];
+    /** Highest generation allocated for this handle; monotone (§1.7a). */
+    readonly generation: number;
+    /**
+     * The revision this replica's view is at: its installation's, then
+     * each delta's `r`. A delta's `base` is THIS, not the owner's previous
+     * revision — a replica whose view did not change on a commit was sent
+     * nothing and is still here, and a `base` it never had is a gap.
+     */
+    readonly revision: number;
+    /** Its interest set; `null` when it declared none (sees every entity). */
+    readonly interest: readonly string[] | null;
+    /** Last accepted authenticated message, for the lease. */
+    readonly lastSeen: number;
+}
+/** A frame the owner wants sent, and to whom. */
+export interface Outbound {
+    readonly peer: string;
+    readonly h: Hex | null;
+    readonly frame: string;
+}
+/** What one inbound frame produced. */
+export interface Dispatched {
+    readonly out: readonly Outbound[];
+    /** A stable, countable refusal reason, when the frame was refused. */
+    readonly refused: string | null;
+    /**
+     * The rest of an action whose request binding needed a digest.
+     *
+     * §1.10 puts one `await` in the ledger path, for inputs too large to
+     * retain verbatim. Rather than make every join and `alive` async to
+     * serve that one case, the synchronous answer comes back immediately
+     * and the remainder is handed over explicitly. A transport sends
+     * `out`, then sends the deferred result's `out` when it settles.
+     *
+     * `null` on every other path, which is all of them but one.
+     */
+    readonly deferred: Promise<Dispatched> | null;
+}
+interface Counters {
+    [reason: string]: number;
+}
+/**
+ * The owner half of the store protocol.
+ *
+ * Holds no transport: frames come in as text with an authenticated
+ * peer, and go out as text addressed to a peer. That is what lets the
+ * whole of slice C be exercised without a network.
+ */
+export declare class StoreOwner<S extends object, A extends ActionSpec, I extends InputSpec> {
+    #private;
+    private readonly deps;
+    private readonly handles;
+    private readonly counters;
+    private readonly chunkBytes;
+    private readonly incarnation;
+    /**
+     * The authoritative document.
+     *
+     * The owner's state IS a store: one place that validates, reconciles,
+     * counts revisions and runs a handler's synchronous transaction.
+     * Keeping a second copy beside it would give handler writes and
+     * `commit` two truths to disagree about.
+     */
+    private readonly core;
+    /** Digest computations in flight, against the pending bound (§2). */
+    private pending;
+    private readonly ledgers;
+    /**
+     * One pending projection per handle (§1.8).
+     *
+     * A newer control REPLACES the pending one rather than queueing
+     * behind it, which is what keeps this a bound rather than a buffer.
+     */
+    private readonly deferred;
+    /** The revision every installed view is at, before the commit. */
+    private revisionBeforeCommit;
+    constructor(deps: OwnerDeps<S, A, I>);
+    /** Whether projections depend on the peer (`projectFor`, or an `owner` rule). */
+    private readonly perPlayer;
+    /** The definition's declared rules, compiled; `null` when it declares none. */
+    private readonly visibility;
+    /** Development warnings already given, so each is said once. */
+    private readonly warned;
+    private warnOnce;
+    /** The key under which two handles are certain to receive the same projection. */
+    private viewKey;
+    /**
+     * Views whose change was projected from the changed entities alone
+     * (`sparseInterestDiff`). Not a refusal, so not in {@link snapshotCounters}.
+     */
+    get sparseViews(): number;
+    private sparseViewCount;
+    /** Counters a host can report. Every refusal moves exactly one. */
+    snapshotCounters(): Readonly<Counters>;
+    /** Live handles, for a host's own bounds reporting. */
+    get handleCount(): number;
+    /** The handle record, for a test or a host's introspection. */
+    handle(h: Hex): OwnerHandle | undefined;
+    /**
+     * Replace the authoritative state, as `setState` does.
+     *
+     * Inside an open transaction the write JOINS it (`applySnapshot`
+     * stages) and the delta emission is DEFERRED to that transaction's
+     * commit (#5): `decide`/`input` diff the committed before/after at
+     * the transaction's end and ship exactly one delta, and a rollback
+     * ships nothing at all. Emitting here would put a staged-world
+     * delta on the wire that no rollback retracts.
+     */
+    commit(next: S): Dispatched;
+    /**
+     * Write entities of one declared collection, as `setEntities` does:
+     * each changed entity validated by its per-entity parser, no
+     * whole-document validation. Same transaction and delta rules as
+     * {@link commit}.
+     */
+    commitEntities(collection: string, changes: Readonly<Record<string, unknown>>): Dispatched;
+    /**
+     * Tell every installed handle what changed (§1.9).
+     *
+     * Per audience, because a delta of the raw state would ship what a
+     * projection exists to withhold: the previous and current
+     * projections are both taken and the difference between THOSE is
+     * what goes out. The previous one is recomputed from the previous
+     * state rather than retained per handle — one projection can be a
+     * megabyte, and keeping one per handle is 256 of them.
+     *
+     * When a delta would not fit the message budget the owner allocates
+     * a new generation instead and sends a manifest: an owner-initiated
+     * replacement, admissible at a `ready` replica (§1.8).
+     */
+    private propagate;
+    /** The authoritative document, for a host's own reads. */
+    getState(): S;
+    /**
+     * Subscribe to the authoritative document.
+     *
+     * The owner's own code watches the state it serves — a host renders
+     * from this, and an action's commit is the same revision its
+     * subscribers see.
+     */
+    subscribe(listener: (state: S, previous: S) => void): Cancel;
+    /** The current authoritative revision. */
+    get currentRevision(): number;
+    /**
+     * The host's own player: whether `peer` may read `audience`.
+     *
+     * The same `authorize` call a `join` makes. There is no handle, no
+     * lease and no ledger — the host's player has no wire to lose a
+     * frame on and no request to replay — but there is the policy.
+     */
+    localRead(peer: string, audience: readonly string[]): boolean;
+    /** The host's own player: the projection a replica of `audience` receives. */
+    localView(peer: string, audience: readonly string[], interest?: readonly string[] | null): S | null;
+    /**
+     * The host's own player: one action, through the ladder a replica's
+     * `act` takes after the wire — known name, `authorize`, then one
+     * transaction that parses the input, runs the handler and validates
+     * the output, and a result that must fit the message budget a
+     * replica would have received it in.
+     *
+     * `input` is what `parseStoreJson` produced from the caller's value,
+     * so the handler sees exactly what it would see from a replica.
+     */
+    localAct(name: string, input: JsonValue, peer: string): {
+        readonly outcome: Outcome;
+        readonly dispatched: Dispatched;
+    };
+    /**
+     * The host's own player: one latest-value input, through the same
+     * ladder as a replica's `in` after the wire. No sequence: a local
+     * call cannot arrive out of order.
+     */
+    localInput(name: string, input: JsonValue, peer: string): Dispatched;
+    /**
+     * Dispatch one inbound frame.
+     *
+     * `peer` is the **authenticated** originating caller — see the module
+     * note. It is not read from `frame`, and no frame can carry one.
+     */
+    receive(frame: string, peer: string, now?: number): Dispatched;
+    /**
+     * One action (§1.10).
+     *
+     * The ladder: gameplay readiness, then the sequence, then the
+     * ledger's disposition, then — only for a genuinely new request —
+     * `authorize` and one synchronous transaction.
+     *
+     * The digest path is the one place this module awaits. Everything
+     * decided before the await is discarded and decided again after it:
+     * the handle may have expired, the policy may have been revoked, and
+     * the ledger may have retained this very sequence while the digest
+     * was computing.
+     */
+    private action;
+    /**
+     * The ledger's decision, and the execution it may authorize.
+     *
+     * Synchronous from here on: no `await` may appear below this line,
+     * because the transaction it enters is synchronous by construction
+     * and a permission checked before a wait can have been revoked
+     * during it.
+     */
+    private decide;
+    /** One latest-value input (§1.11). Fire and forget: no reply, ever. */
+    private input;
+    /** A `res` for a result, a `no` for a retained refusal. */
+    private reply;
+    private permitsAction;
+    private permitsInput;
+    /** The lease is renewed by an accepted message, refusals excepted. */
+    private renew;
+    /**
+     * Everything that belongs to one handle, gone together.
+     *
+     * §2: the ledger goes with the handle. That is what makes a replay
+     * after eviction `closed` rather than `result-expired` — the owner
+     * no longer knows the sequence existed — and it is what keeps the
+     * ledger table bounded by live handles instead of by the owner's
+     * lifetime.
+     */
+    private forget;
+    /** Peers present as players: a handle installed, or a local player. */
+    private readonly present;
+    private readonly localPlayers;
+    private readonly pendingEvents;
+    private readonly areas;
+    private areasAt;
+    /** Set by `farewell`: a closing store raises no more events. */
+    private ending;
+    private get wantsEvents();
+    private isPresent;
+    /** Queue `join` / `leave` when a peer's presence actually flips. */
+    private presenceChanged;
+    /**
+     * The host's own player arriving or going (`hostPlayer`). It has no
+     * handle, but it is a player: `onEvent` hears it like any other.
+     */
+    localPresence(peer: string, joined: boolean, audience?: readonly string[], reason?: LeaveReason): void;
+    /** Queue `area` events for present players whose area moved. */
+    private detectAreas;
+    /**
+     * Run `onEvent` for everything queued, each as its own transaction,
+     * and return what those transactions changed for the replicas.
+     *
+     * Called by the host AFTER the frame that caused the events has been
+     * dispatched — never inside it — so a hook never runs in the middle
+     * of a projection pass. A hook that throws discards its writes, as a
+     * handler's do, and is counted. A hook whose writes cause more events
+     * (a teleport on join) is served in the same drain, up to a bound, so
+     * two hooks cannot ping-pong forever.
+     */
+    drainEvents(): Dispatched;
+    /** Listeners told when the set of installed handles changes. */
+    private readonly membership;
+    private membershipChanged;
+    /**
+     * Be told when a handle is installed or forgotten — join, leave,
+     * expiry, a policy refusal, closure. Synchronous, inside the frame
+     * that caused it: a listener reads {@link peers} and must not call
+     * back into the owner.
+     */
+    onMembership(listener: () => void): Cancel;
+    /** The distinct authenticated peers with an installed handle. */
+    peers(): readonly string[];
+    /**
+     * Re-ask `authorize` for every installed read, now.
+     *
+     * The delta feed re-authorizes before shipping, but only when there
+     * is a change to ship: a policy that revokes a peer (a kick) would
+     * otherwise leave it subscribed until the next commit. A refused
+     * handle is forgotten with the same unsolicited `closed` the feed
+     * sends, so the replica rejoins and its join is answered
+     * `forbidden`.
+     */
+    reauthorize(): Dispatched;
+    /**
+     * Emit the projections that were deferred, now that one can be
+     * taken.
+     *
+     * Completion **revalidates**: a handle can die between the deferral
+     * and the availability, and an expired one never acquires a pending
+     * projection in the first place (§1.8).
+     */
+    resumeDeferred(now?: number): Dispatched;
+    /** Projections waiting on availability, for a host's bounds report. */
+    get deferredCount(): number;
+    /** Ledgers held, for a host's own bounds reporting (§2). */
+    get ledgerCount(): number;
+    /** An accepted frame's reply. */
+    private accept;
+    /**
+     * Expire handles whose lease has run out (§2).
+     *
+     * Reports the PEER with the handle, because §1.6's expiry notice is
+     * addressed to a caller and the handle is gone by the time anyone
+     * could look it up. A host that cannot reach that peer sends
+     * nothing; no tombstone is retained to announce later.
+     */
+    sweep(now: number): readonly {
+        readonly h: Hex;
+        readonly peer: string;
+    }[];
+    /**
+     * Say goodbye, once, to every replica this owner is serving.
+     *
+     * §1.6's doctrine is that a caller learns why rather than inferring
+     * it from silence, and it was applied to EXPIRY (`sweep`) and not
+     * to closure: a host that closed took its answer with it, so every
+     * bound replica's next write reached a store that no longer
+     * existed and the caller's only signal was a deadline — the
+     * `indeterminate` "the store did not answer before the deadline",
+     * measured over the real transport.
+     *
+     * The code is `owner-lost`, not `closed`, and the difference is
+     * the whole semantics: `closed` is the expiry notice and the
+     * replica REJOINS on it, which after a close would either hang or
+     * silently attach the caller to a SUCCESSOR's different document
+     * under the same handle. `owner-lost` is terminal — this
+     * incarnation held the document and is gone — so the replica's
+     * view is cleared, `ready()` rejects, and rejoining is the
+     * caller's decision to make explicitly.
+     *
+     * Every handle is forgotten here, so the frames are a one-shot:
+     * a second call has nothing to say.
+     */
+    farewell(): readonly Outbound[];
+    /** This owner's incarnation, which every manifest carries. */
+    get incarnationHex(): Hex;
+    /**
+     * Admit a join.
+     *
+     * Order matters and is the ladder's: **the store address first**,
+     * because it decides whether this owner may answer at all; then
+     * definition identity and version, which are loud for the store
+     * they ARE addressed to; then capacity, `authorize`, and only then
+     * a handle. Nothing is allocated before the policy has ruled, so a
+     * refused caller costs one counter and no state.
+     *
+     * This summary is written out in full because it was wrong for one
+     * commit — it still listed the definition first, ten lines above
+     * the code that had just been reordered, in the rung whose
+     * position was the point of the change.
+     */
+    private join;
+    /**
+     * Allocate the next generation and emit `man` + every `snap`.
+     *
+     * Returns `null` when the projection cannot be carried, so the caller
+     * decides what to do with the handle rather than this function
+     * guessing.
+     */
+    private install;
+    /**
+     * One read decision, for the join and for every later read.
+     *
+     * A throwing policy is a refusal, never an admission.
+     */
+    private permitsRead;
+    /** A handle from the application's allocator, or null if it threw. */
+    private newHandle;
+    /** The definition's interest collections and their key functions. */
+    private get interestFns();
+    /** An entity's interest key; a key function that throws or returns a non-string means "no key": always delivered. */
+    private interestKey;
+    /** A view narrowed to the entities an interest set covers. */
+    private filterInterest;
+    /**
+     * The commit's raw entity change, or `null` when this commit cannot be
+     * projected entity by entity.
+     *
+     * It can when the host projects only by DECLARED rules (no `project` /
+     * `projectFor`, which see the whole document), and every root key the
+     * commit changed is a collection declared in both `interest` and
+     * `entities`, and is an entity map on both sides. Declared rules are
+     * path patterns, so an entity's visibility is the same in a document
+     * holding only the changed entities; and `entities` is the contract that
+     * an entity is valid on its own, so its projection is validated by the
+     * per-entity parser instead of `state` over the whole view.
+     */
+    private entityDelta;
+    /**
+     * One view's change from the changed entities alone: O(changed) per
+     * view instead of two whole-world projections, a whole-view validation
+     * and a scan of every id. Returns `undefined` for anything it cannot
+     * answer exactly as `interestDiff` over full projections would (a rule
+     * hiding a whole collection, a projected entity its parser refuses),
+     * and the caller takes the full path.
+     */
+    private sparseInterestDiff;
+    /** One view's change, split for interest: the rest of the document, and per-entity changes with their keys. */
+    private interestDiff;
+    /** The ops one handle receives for a split diff. */
+    private interestOps;
+    /**
+     * A new interest set: the entities entering it arrive, the ones leaving
+     * go, in one delta — the view never blanks — and then `ok`.
+     *
+     * Interest is a filter, not a permission: nothing here asks `authorize`,
+     * because the audience (which is) is unchanged and every entity sent
+     * was already readable under it.
+     */
+    private interestChange;
+    /**
+     * The audience projection, validated by the definition.
+     *
+     * A projection that does not satisfy `state()` is the owner's bug and
+     * must not be shipped as a snapshot, so it becomes `empty()` — the
+     * value that represents absence — rather than the full state.
+     */
+    private project;
+    /**
+     * Re-check the binding for every message (§1.3).
+     *
+     * Returns a countable reason instead of a handle when the handle is
+     * unknown, expired, or bound to a different authenticated peer — and
+     * the three are **one** refusal on the wire, so a refusal cannot
+     * disclose that a handle exists (§2).
+     */
+    private bind;
+    private no;
+    private refuse;
+}
+/** Re-exported so a host can hold assemblies without another import. */
+export { Assembly, AssemblyTable };
+export type { Parse };