@net-mesh/browser 0.37.0

package/dist/store/replica.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Slice D — the replica: snapshot install, delta apply, resync,
+ * generations.
+ *
+ * ## What this module is
+ *
+ * The other half of slice C. The owner emits `man` + `snap` chunks and
+ * later `delta`s; this decides what a caller is allowed to SEE as a
+ * result. It is the production form of the state machine
+ * `test/store/lifecycle-model.ts` models abstractly (§1.7a), with the
+ * real codec, the real assembler (slice B1) and the real document.
+ *
+ * ## The three monotone numbers (§1.7a), which are different things
+ *
+ * - `installed` — the generation whose snapshot is published.
+ * - `assembling` — the generation of the open assembly.
+ * - `retired` — the highest generation ever **admitted**, installed or
+ *   not. This is the watermark that makes an abandoned generation
+ *   inadmissible for ever: `g > installed` would let a delayed manifest
+ *   reopen a generation that was admitted, abandoned, and never
+ *   published. Admission tests `g > retired`.
+ *
+ * Duplicate active manifests fall out of the same rule rather than
+ * needing their own: admitting the first set `retired := g`, so the
+ * second fails `g > retired` and the open assembly is untouched.
+ *
+ * ## What an empty slot is not
+ *
+ * `fenced` exists because an empty correlation slot is not consent. A
+ * refused request fences the subscription's view; only `ready` accepts
+ * unsolicited owner refreshes, and a `fenced` replica records no skip,
+ * so an owner emission cannot lift a fence the caller placed.
+ *
+ * ## Scope
+ *
+ * Audience transitions and `resume` are slice F, actions and the ledger
+ * are slice E. Both are refused here rather than half-served: this
+ * module issues `join` and `resync` and nothing else.
+ *
+ * Its acceptance gate is reliable transfer (§4 D), exactly as B2′ — a
+ * replica that applies deltas in order is not evidence that the
+ * transport delivers them in order.
+ */
+import { StoreCore } from './core.js';
+import type { Decimal, Hex } from './wire.js';
+import type { ActionSpec, InputSpec, StoreDefinition } from './types.js';
+/** A frame to hand to the transport. */
+export interface Request {
+    readonly kind: 'join' | 'resync' | 'aud' | 'resume';
+    readonly q: Hex;
+    readonly frame: string;
+}
+/** The five states of §1.7a. */
+export type ReplicaState = 'joining' | 'installing' | 'ready' | 'fenced' | 'closed';
+/**
+ * How many times an unanswered transition re-asks before the replica
+ * gives the caller a terminal answer.
+ *
+ * Three: enough that a join survives independent losses, few enough
+ * that a store nobody is serving stops asking. Each re-ask abandons
+ * the subscription the owner may have opened for the previous one;
+ * nothing can release it by name, because a replica whose MANIFEST
+ * was lost never learned a handle to release — the owner's own idle
+ * lease (`owner.ts`'s `HANDLE_LEASE_MS`) is what reclaims it, which
+ * is why the ladder is bounded rather than endless.
+ */
+export declare const MAX_JOIN_REASKS = 3;
+/** What one arrival produced. */
+export interface Received {
+    readonly out: readonly Request[];
+    /** A stable, countable reason, when the arrival was not taken. */
+    readonly dropped: string | null;
+}
+export interface ReplicaDeps<S extends object, A extends ActionSpec, I extends InputSpec> {
+    readonly definition: StoreDefinition<S, A, I>;
+    /** The document and its publication — the replica never commits directly. */
+    readonly core: StoreCore<S, A, I>;
+    /** The transport's current per-event budget. */
+    readonly maxEventBytes: number;
+    /** A fresh correlation id per request. Its uniqueness is the caller's. */
+    readonly newQ: () => Hex;
+    readonly now: () => number;
+    /**
+     * The audience this caller wants at the start.
+     *
+     * After a `setAudience` the DESIRED one is the replica's own, and it
+     * is what every later request states — never the owner's older one.
+     */
+    readonly audience: readonly string[];
+    /**
+     * WHICH store of this definition to join — the owner's declared
+     * address, carried on the join so the owner it is NOT addressed to
+     * can refuse it. See `wire.ts`'s field table.
+     */
+    readonly store: string;
+    /** The opaque join key the owner's policy reads. */
+    readonly key: string;
+    /** The interest set to join with; absent: every entity. */
+    readonly interest?: readonly string[];
+}
+/**
+ * A replica of one owner's store.
+ *
+ * Every method returns the requests it wants sent; nothing here touches
+ * a transport, so the state machine is testable without one.
+ */
+export declare class StoreReplica<S extends object, A extends ActionSpec, I extends InputSpec> {
+    #private;
+    private readonly deps;
+    constructor(deps: ReplicaDeps<S, A, I>);
+    /**
+     * The caller's desired interest set, stated by every later `join` and
+     * `resume` so a rejoin never falls back to an older one. `null`: none
+     * declared, every entity delivered.
+     */
+    get interest(): readonly string[] | null;
+    set interest(keys: readonly string[] | null);
+    /** The caller's latest desired audience. */
+    get desired(): readonly string[];
+    /** Local waiters on the transition in flight. */
+    get waiters(): number;
+    get state(): ReplicaState;
+    /** The learned handle, or null while none has been learned. */
+    get handle(): Hex | null;
+    /** The installed generation, as a canonical decimal, or null. */
+    get installed(): Decimal | null;
+    /** The owner's revision for the installed view, or null. */
+    get revision(): Decimal | null;
+    /** The watermark: the highest generation ever admitted. */
+    get retired(): Decimal;
+    /** The highest refresh dropped mid-transition, or null. */
+    get skipped(): Decimal | null;
+    /** Arrivals not taken, by reason. */
+    get dropped(): Readonly<Record<string, number>>;
+    /**
+     * The first request: a `join`.
+     *
+     * Only `join` creates a handle, so this is the only entry point from
+     * a state with none — including after `no {closed}`, which discards
+     * the handle and all of its generation state.
+     */
+    join(): Request;
+    /**
+     * Change what this caller wants to see (§1.7).
+     *
+     * Three moments, deliberately separate: local intent is IMMEDIATE —
+     * the view is cleared to `empty()` and the status is `syncing`,
+     * before the owner has agreed to anything, because continuing to
+     * render the old audience is the disclosure this exists to stop.
+     * Owner acceptance allocates the generation, and installation
+     * publishes it.
+     *
+     * Equal pending requests share one wire request and one `q`, with a
+     * local waiter each: `q` is the transition's identity on the wire,
+     * not a waiter's.
+     */
+    setAudience(names: readonly string[]): readonly Request[];
+    /**
+     * The session was replaced (§1.6).
+     *
+     * A reconnect is not an audience change: the last snapshot is
+     * RETAINED and marked stale, because what the caller may see has not
+     * changed — only whether it is current. The request states the
+     * caller's latest desired audience, never the owner's older one.
+     */
+    reconnect(): readonly Request[];
+    /**
+     * One local waiter gives up.
+     *
+     * Cancellation is per waiter; the wire request is not. Cancelling the
+     * last one fences the subscription — the view was invalidated at
+     * request time and is NOT restored, because the caller asked for a
+     * different one.
+     */
+    cancelWaiter(): void;
+    /** One decoded arrival from the owner. */
+    receive(frame: string): Received;
+    /**
+     * The assembly deadline, and the lease the caller keeps by asking.
+     *
+     * Returns the requests the elapsed time produced — at most one
+     * `resync`, because recovery is coalesced.
+     */
+    tick(): readonly Request[];
+    /** The caller gives up this subscription. Fences it; no view. */
+    cancel(): void;
+}