@net-mesh/browser 0.37.0

package/dist/store/ledger.js

@@ -0,0 +1,292 @@
+/**
+ * Slice E — the action ledger (§1.10).
+ *
+ * The rule the whole module exists for: **a sequence number identifies
+ * one request, not a slot.** A retained `s` replayed with the same
+ * request returns the same outcome; replayed with a *different* request
+ * it is refused and the retained entry is left alone. Without that, a
+ * caller could overwrite the record of what it asked for.
+ *
+ * ## Why a rejection is retained
+ *
+ * Authorization denial and a handler throw both retain an entry. If a
+ * refusal were simply absent, a later policy change would turn an
+ * earlier refusal into an execution of the same sequence — the same
+ * request succeeding the second time because the record of its refusal
+ * was not kept.
+ *
+ * ## Why the floor exists, and what it cannot say
+ *
+ * The window is bounded three ways (count, bytes, age), and eviction
+ * happens in `s` order so an entry is never dropped while a lower one
+ * is retained. The floor is the highest evicted `s`: at or below it the
+ * owner knows a sequence has been used but no longer knows the outcome,
+ * which is `result-expired` — explicitly NOT a claim that it did or did
+ * not commit. A handle that is gone is a different answer again
+ * (`closed`), because then the owner does not even know the sequence
+ * existed.
+ *
+ * ## The binding, and the one `await`
+ *
+ * The request binding is a canonical `name \x1f json` string, retained
+ * verbatim while it is small and as a SHA-256 when it is not. The small
+ * form is the common case and has no `await` at all, which is the point:
+ * the asynchronous path is the only one where the handle, the policy and
+ * the ledger can change under the request, and it is the only one that
+ * has to revalidate.
+ */
+import { StoreError } from './errors.js';
+import { utf8Length } from './wire.js';
+/** Outcomes retained per handle (§2). */
+export const LEDGER_MAX_ENTRIES = 32;
+/** Bytes retained per handle (§2). */
+export const LEDGER_MAX_BYTES = 64 * 1024;
+/** How long an outcome is retained (§2). */
+export const LEDGER_MAX_AGE_MS = 60_000;
+/** Above this, a binding is retained as its digest rather than verbatim. */
+export const BINDING_INLINE_MAX_BYTES = 2048;
+/** The highest sequence a handle can reach. It does not wrap. */
+export const MAX_SEQUENCE = (1n << 64n) - 1n;
+/** The separator between an action's name and its input. */
+const UNIT_SEPARATOR = '\u001f';
+/**
+ * The canonical form of one request.
+ *
+ * Object keys sort ascending by UTF-16 code unit, there is no
+ * insignificant whitespace, and numbers are rendered by
+ * `Number.prototype.toString` — exact for every value the store admits,
+ * because §1.12 already refuses `NaN`, `Infinity` and duplicate keys,
+ * and identifiers needing full integer precision are strings by §1.1.
+ *
+ * Only the owner computes this and only the owner compares it: it never
+ * crosses the wire, so self-consistency is what matters.
+ */
+export function canonicalRequest(name, input) {
+    return `${name}${UNIT_SEPARATOR}${canonicalJson(input)}`;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            // Unreachable through the parser, which refuses both — but this
+            // function is also called on a locally-built input, and a
+            // canonical form that silently rendered `null` here would make
+            // two different requests compare equal.
+            throw new StoreError('invalid-data', 'a canonical request cannot contain a non-finite number');
+        }
+        return String(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(element => canonicalJson(element)).join(',')}]`;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const fields = keys.map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+    return `{${fields.join(',')}}`;
+}
+/** How many bytes a canonical form occupies. */
+export function canonicalBytes(canonical) {
+    return new TextEncoder().encode(canonical).byteLength;
+}
+/** Whether this binding needs the asynchronous digest path. */
+export function needsDigest(canonical) {
+    return canonicalBytes(canonical) > BINDING_INLINE_MAX_BYTES;
+}
+/** The binding for a small canonical form. Synchronous by construction. */
+export function inlineBinding(canonical) {
+    if (needsDigest(canonical)) {
+        throw new StoreError('invalid-data', 'this canonical form needs the digest path');
+    }
+    return { form: 'inline', value: canonical };
+}
+/**
+ * The binding for a large canonical form.
+ *
+ * The caller must treat the `await` as a boundary: no authorization
+ * decision and no transaction context may cross it (§1.10).
+ */
+export async function digestBinding(canonical) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+    const bytes = new Uint8Array(digest);
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return { form: 'digest', value: hex };
+}
+function sameBinding(a, b) {
+    return a.form === b.form && a.value === b.value;
+}
+/**
+ * One handle's outcomes.
+ *
+ * Keyed by sequence, bounded by count, bytes and age, evicted in `s`
+ * order so the floor can only ever describe a contiguous prefix.
+ */
+export class HandleLedger {
+    maxEntries;
+    maxBytes;
+    maxAgeMs;
+    /** The highest retired sequence: used, outcome no longer known. */
+    #floor = 0n;
+    #entries = new Map();
+    #bytes = 0;
+    constructor(maxEntries = LEDGER_MAX_ENTRIES, maxBytes = LEDGER_MAX_BYTES, maxAgeMs = LEDGER_MAX_AGE_MS) {
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+        this.maxAgeMs = maxAgeMs;
+    }
+    get floor() {
+        return this.#floor.toString();
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get bytesHeld() {
+        return this.#bytes;
+    }
+    /**
+     * What to do with `(s, binding)`.
+     *
+     * Pure: it moves nothing, so the owner can call it before the
+     * transaction and — on the digest path — again after the `await`.
+     */
+    disposition(s, binding, now) {
+        this.expire(now);
+        if (s >= MAX_SEQUENCE)
+            return { kind: 'exhausted' };
+        const retained = this.#entries.get(s.toString());
+        if (retained !== undefined) {
+            // A sequence identifies one request. The same request replays;
+            // a different one under the same sequence is refused, and the
+            // retained entry is NOT overwritten.
+            if (!sameBinding(retained.binding, binding))
+                return { kind: 'conflict' };
+            return { kind: 'replay', outcome: retained.outcome };
+        }
+        // A gap is permitted and does not block: an unseen sequence above
+        // the floor is simply new. At or below it, the sequence has been
+        // used and the outcome is gone.
+        if (s <= this.#floor)
+            return { kind: 'expired' };
+        return { kind: 'execute' };
+    }
+    /**
+     * Retain an outcome.
+     *
+     * A refusal is retained exactly like a result: that is what stops a
+     * policy change from turning an earlier denial into a later
+     * execution of the same sequence.
+     */
+    retain(s, binding, outcome, now) {
+        const bytes = entryBytes(binding, outcome);
+        this.#entries.set(s.toString(), { s, binding, outcome, bytes, at: now });
+        this.#bytes += bytes;
+        this.evict(now);
+    }
+    /** Drop everything past its age, advancing the floor. */
+    expire(now) {
+        for (const entry of this.ordered()) {
+            if (now - entry.at < this.maxAgeMs)
+                break;
+            this.drop(entry);
+        }
+    }
+    evict(now) {
+        this.expire(now);
+        // Count and bytes, always in `s` order, so an entry is never
+        // dropped while a lower one is retained — which is what makes the
+        // floor a boundary rather than a set of holes.
+        while (this.#entries.size > this.maxEntries || this.#bytes > this.maxBytes) {
+            const lowest = this.ordered()[0];
+            if (lowest === undefined)
+                return;
+            this.drop(lowest);
+        }
+    }
+    drop(entry) {
+        this.#entries.delete(entry.s.toString());
+        this.#bytes -= entry.bytes;
+        if (entry.s > this.#floor)
+            this.#floor = entry.s;
+    }
+    ordered() {
+        return [...this.#entries.values()].sort((a, b) => (a.s < b.s ? -1 : a.s > b.s ? 1 : 0));
+    }
+}
+function entryBytes(binding, outcome) {
+    // UTF-8 BYTES, the unit `LEDGER_MAX_BYTES` bounds (the idiom
+    // `canonicalBytes` shows): `.length` counts UTF-16 code units and
+    // under-enforced the cap exactly for unicode-heavy inputs.
+    const payload = outcome.kind === 'result' ? JSON.stringify(outcome.out) : outcome.code;
+    return utf8Length(binding.value) + utf8Length(payload);
+}
+/**
+ * Latest-value inputs (§1.11).
+ *
+ * Monotone per `(handle, name)`: a sequence at or below the last seen
+ * one is dropped and counted. There is no retention, no replay and no
+ * gap recovery, and **loss does not imply a successor** — a dropped
+ * input may be the last one, so the game must tolerate a missing final
+ * input. The coalescing design invites the opposite assumption, which
+ * is why it is stated here beside the code.
+ */
+export class InputSequences {
+    #latest = new Map();
+    #dropped = 0;
+    /** How many inputs this handle has dropped as stale. */
+    get dropped() {
+        return this.#dropped;
+    }
+    /** Whether this input is newer than the last for its name. */
+    admit(name, s) {
+        const last = this.#latest.get(name);
+        if (last !== undefined && s <= last) {
+            this.#dropped += 1;
+            return false;
+        }
+        this.#latest.set(name, s);
+        return true;
+    }
+    /** The last admitted sequence for a name, or null. */
+    latest(name) {
+        const value = this.#latest.get(name);
+        return value === undefined ? null : value.toString();
+    }
+}
+/** Per-handle ledger state, created on demand. */
+export class LedgerTable {
+    #ledgers = new Map();
+    #inputs = new Map();
+    ledger(h) {
+        let ledger = this.#ledgers.get(h);
+        if (ledger === undefined) {
+            ledger = new HandleLedger();
+            this.#ledgers.set(h, ledger);
+        }
+        return ledger;
+    }
+    inputs(h) {
+        let sequences = this.#inputs.get(h);
+        if (sequences === undefined) {
+            sequences = new InputSequences();
+            this.#inputs.set(h, sequences);
+        }
+        return sequences;
+    }
+    /**
+     * Forget a handle's ledger.
+     *
+     * §2: the ledger goes with the handle, which is why a replay after
+     * eviction is `closed` and not `result-expired` — the owner no
+     * longer knows the sequence existed.
+     */
+    forget(h) {
+        this.#ledgers.delete(h);
+        this.#inputs.delete(h);
+    }
+    get size() {
+        return this.#ledgers.size;
+    }
+}