@abide/abide 0.58.0 → 0.100.0

package/src/shared/reactive/Cursor.ts

@@ -0,0 +1,223 @@
+// THE CURSOR. RULEBOOK 2.5: `for await (… of s)` — the production in flight, then each one after
+// it. On a streaming producer that is one turn per CHUNK, read from the chunk buffer by ordinal,
+// so two chunks between two `await`s are two turns of the loop. On every other value it is the
+// standing production: a burst between two turns collapses to the latest, since nothing else is
+// held. An app that wants every message keeps them — a channel is an array.
+//
+// A NARROW FACE rather than the `Cell`, the same way `tracking.ts` takes a `Tracked`: what a
+// cursor reads is a handful of fields, and naming them keeps the cell's internals out of a
+// second file.
+
+import {
+    dropReader,
+    newSubscriber,
+    type Subscriber,
+    type Tracked,
+} from './tracking.ts'
+import { PATCHES } from './PATCHES.ts'
+
+/**
+ * What a cursor reads, and all of a cell the server is handed (`servedCellOf`).
+ *
+ * `ring[index]` carries ordinal `ringBase + index + 1`, so a cursor holding an ordinal finds its
+ * place in a stream's chunk buffer without the buffer having to hold one.
+ */
+export type Retained = {
+    /** The window a `throttle` or a `debounce` holds open, `holding` while a production waits on it. */
+    cap: { holding: boolean } | null
+    ordinal: number
+    /**
+     * Unused by a cursor and declared so a `Cell` still satisfies `Tracked`, which a cursor's
+     * subscriber is registered through.
+     */
+    probeReaders: Subscriber[]
+    ring: unknown[]
+    ringBase: number
+    servable: boolean
+    state: number
+    /**
+     * Non-null on a streaming producer, whose ring is the accumulation of the run being served
+     * (9.1) and is retained whole — the chunks ARE the value.
+     */
+    stream: object | null
+    value: unknown
+    readers: Subscriber[]
+}
+
+// The cursors standing over each source, for a patch to keep the place of the ones behind (5.7).
+const CURSORS = new WeakMap<Retained, Set<Cursor>>()
+
+/**
+ * Keeps each cursor behind `edited` where it stands, as a stream patch grows its accumulation by
+ * `grown` and moves the ring's base by as much.
+ *
+ * THE BASE MOVES FOR A CURSOR CAUGHT UP, so the next chunk lands one past it. One behind that has
+ * still to read where the patch wrote reads on from where it was — so its ordinal moves with the
+ * base and its place in the ring does not. One the patch wrote before shifts with the ring.
+ */
+export function keepPlaces(
+    source: Retained,
+    edited: number,
+    grown: number,
+): void {
+    const cursors = CURSORS.get(source)
+    if (cursors === undefined) return
+    for (const cursor of cursors)
+        if (cursor.at < source.ordinal && cursor.at - source.ringBase <= edited)
+            cursor.at -= grown
+}
+
+/** Whether a cursor over `source` has chunks it has still to read. */
+export function hasCursorBehind(source: Retained): boolean {
+    const cursors = CURSORS.get(source)
+    if (cursors === undefined) return false
+    for (const cursor of cursors) if (cursor.at < source.ordinal) return true
+    return false
+}
+
+/**
+ * A live reader of a source's productions, one turn per production, in order.
+ *
+ * A RECORD, NOT A SCOPE. The four closures this was — `take`, `notify`, `stop` and `next` — shared
+ * one environment holding `at`, `waiting`, `source` and `reader`, and a cursor OUTLIVES the call
+ * that made it: a `for await` holds one for the life of the loop, so the environment and every
+ * function object hanging off it is live that whole time. Fields on a prototype are the object
+ * alone, and `at` — read and written on every turn — becomes a property load on a fixed structure
+ * rather than a scope load.
+ */
+export class Cursor implements AsyncIterator<unknown> {
+    source: Retained
+    /** The ordinal of the last production this cursor handed over. */
+    at: number
+    /**
+     * The patch epoch the value it last handed over stood at.
+     *
+     * A PATCH MINTS NO ORDINAL (5.7) — the follow's version tells a patch from a production by
+     * exactly that — so a cursor over a value patched in place reads the change off the object.
+     */
+    patched: number
+    /**
+     * The turns asked for and not yet answered.
+     *
+     * A QUEUE rather than one slot because a consumer may ask twice before either answer arrives
+     * — `Promise.all([ it.next(), it.next() ])` is the shape, and with one slot the second `next`
+     * overwrote the first's resolver and that promise never settled at all. `for await` asks one
+     * at a time, which is why nothing here said so.
+     */
+    waiting: ((result: IteratorResult<unknown>) => void)[]
+    reader: Subscriber
+
+    constructor(source: Retained, from: number) {
+        this.source = source
+        this.at = from
+        this.patched = 0
+        this.waiting = []
+        // The one closure left, and it captures this cursor and nothing else. `notify` is
+        // called as a method on the SUBSCRIBER, so it cannot be the cursor's own method —
+        // and widening `Subscriber` with a back-edge would put a field on the shape every
+        // reader in the graph carries for the sake of the few that are cursors.
+        // Registered outside the tracking protocol, so the source it waits on is declared
+        // rather than discovered — see the same shape in `Reactive`'s `settled`.
+        this.reader = newSubscriber([source as unknown as Tracked], null)
+        // One production per waiting turn, in the order they were asked for: a burst that
+        // lands three productions on a consumer holding two turns answers both.
+        this.reader.notify = (): void => {
+            const waiting = this.waiting
+            while (waiting.length !== 0) {
+                const next = this.take()
+                if (next === null) return
+                ;(waiting.shift() as (result: IteratorResult<unknown>) => void)(
+                    next,
+                )
+            }
+        }
+        source.readers.push(this.reader)
+        let cursors = CURSORS.get(source)
+        if (cursors === undefined) {
+            cursors = new Set()
+            CURSORS.set(source, cursors)
+        }
+        cursors.add(this)
+    }
+
+    /**
+     * One production, or `null` where the cursor has caught up.
+     *
+     * Reading a stream's chunks by ordinal is what keeps a burst from being a gap or a repeat.
+     */
+    take(): IteratorResult<unknown> | null {
+        const source = this.source
+        let at = this.at
+        if (source.stream === null) {
+            const value = source.value
+            // 6.10: an `undefined` standing is caught up, not a turn.
+            if (value === undefined) return null
+            const patched =
+                value !== null && typeof value === 'object'
+                    ? (PATCHES.written.get(value) ?? 0)
+                    : 0
+            if (at >= source.ordinal && patched === this.patched) return null
+            // 5.9 — A PRODUCTION A WINDOW HOLDS has minted its ordinal and is not yet the value: the
+            // turn is the release's, which wakes this cursor.
+            if (source.cap?.holding === true) return null
+            // The standing production is the only one held, so everything minted or patched
+            // since the last turn collapses into it.
+            this.at = source.ordinal
+            this.patched = patched
+            return { value, done: false }
+        }
+        if (at >= source.ordinal) return null
+        // A run that restarted moved the buffer past this cursor: answer from its start.
+        if (at < source.ringBase) at = source.ringBase
+        const value = source.ring[at - source.ringBase]
+        this.at = at + 1
+        return { value, done: false }
+    }
+
+    next(): Promise<IteratorResult<unknown>> {
+        if (!this.reader.alive)
+            return Promise.resolve({ value: undefined, done: true })
+        // A TURN ALREADY ASKED FOR AND NOT ANSWERED KEEPS THE ORDER: taking from the
+        // ring here while one is queued would hand the later caller the earlier
+        // production.
+        if (this.waiting.length === 0) {
+            const ready = this.take()
+            // NOT `async`, and no `await` on the caught-up arm. A cursor behind a
+            // stream's chunks is the common shape while a burst drains, and an
+            // `async` here would put a microtask tick between every one of those
+            // turns.
+            if (ready !== null) return Promise.resolve(ready)
+        }
+        const waiting = this.waiting
+        return new Promise((resolve) => {
+            waiting.push(resolve)
+        })
+    }
+
+    /**
+     * Ends the cursor: `for await` calls this on `break`, on `return` and on a throw.
+     *
+     * It is the only thing that drops the subscriber — a live cursor has no end of its own.
+     */
+    return(): Promise<IteratorResult<unknown>> {
+        return this.stop()
+    }
+
+    throw(): Promise<IteratorResult<unknown>> {
+        return this.stop()
+    }
+
+    stop(): Promise<IteratorResult<unknown>> {
+        const reader = this.reader
+        reader.alive = false
+        dropReader(this.source, reader)
+        CURSORS.get(this.source)?.delete(this)
+        const waiting = this.waiting
+        while (waiting.length !== 0)
+            (waiting.shift() as (result: IteratorResult<unknown>) => void)({
+                value: undefined,
+                done: true,
+            })
+        return Promise.resolve({ value: undefined, done: true })
+    }
+}

package/src/shared/reactive/ENTRY_LIVES.ts

@@ -0,0 +1,7 @@
+/**
+ * When each entry of a `Keyed` declaring `ttl` last produced, and how long it lives, by entry cell.
+ *
+ * 11.45. A leaf because `Keyed.ts` writes it and `Reactive.ts` reads it (`deadlineOf`), and the
+ * second cannot import the first.
+ */
+export const ENTRY_LIVES = new WeakMap<object, { at: number; ms: number }>()

package/src/shared/reactive/Expiry.ts

@@ -0,0 +1,103 @@
+// THE LIFE OF A PRODUCTION. RULEBOOK 6.1 through 6.9: `ttl` says how long what a producer
+// made stays good for, and most of the group is about work that must NOT happen — no wake
+// (6.1) and nothing started at the deadline (6.9).
+//
+// A DEADLINE DROPS, IT DOES NOT RELOAD, and that one sentence is the shape of the whole
+// mechanism. 6.7 releases the production, 6.8 and 6.9 leave the value neither ready nor
+// busy, and 6.6 has the producer run on the READ that follows. Waking at the deadline
+// would cause that read, and a `ttl` would then reload every value on its deadline whether
+// or not anything wanted it — which is `s.refresh` (7.4) under another name, and is the
+// thing this is not.
+//
+// THE CLOCK IS THE COST, NOT THE COMPARISON, and it is what decides where this is
+// called from. `Date.now()` is several times a read of an already-served value, so an
+// expiry test on the read path would be the read for every value in the design whether
+// or not it declared a `ttl`. `direct` is what keeps it off them: a cell carrying an
+// expiry is never direct, so the check lives one frame in on `readIndirect` and a value
+// declaring no `ttl` never reaches a clock at all. That is CLAUDE.md's "the expensive
+// general path is the fallback, not the default", and here the fallback is the whole
+// mechanism.
+//
+// WHAT IT COSTS EVERY VALUE THAT DECLARES NO `ttl`, measured against the same tree with
+// the mechanism cut out, two runs of each: READ A SETTLED VALUE IS UNCHANGED at 4.8 ns and
+// 4.9 ns on both trees — the number `setDirect` exists to protect, and the only one on a
+// path a template walks per slot per row. Nothing moved beyond the noise in the slow
+// direction: every write, fan-out, fan-in, chain and probe case sits inside 2.5%, and the
+// two that moved further moved the other way and swap places between runs.
+//
+// THE FIELD IS ON THE EXPIRY RECORD, NOT ON THE CELL, and that is why. `dropped` could have
+// been a cell field beside `landed` and `servable`, and one more field per cell was
+// already worth about 5% on `probe a settled DAG 5 wide x 5 deep` when `expiry` itself was
+// added — a walk that reads no expiry code at all and is bound by memory traffic. A record
+// only a `ttl` value allocates costs the other values nothing.
+//
+// WALL CLOCK RATHER THAN MONOTONIC. A `ttl` is a cache lifetime, and 8.2 hands the same
+// number to a `Store` that necessarily keeps wall-clock time — two clocks for one option
+// is two answers to "is this still good". What that costs is a clock stepped backwards
+// keeping a production alive longer than it asked for, which is the benign direction:
+// nothing is dropped early, and the read-driven backstop in `Reactive.ts` catches up the
+// moment the clock does.
+
+export type Expiry = {
+    /** The life of one production, in milliseconds. */
+    ms: number
+    /** The standing production's mint time, which 6.5 through 6.8 are read off. */
+    at: number
+    /**
+     * Whether the standing production has already been released (6.7).
+     *
+     * The value is then waiting for a read to call its producer (6.6) — which is a state no
+     * combination of the cell's own fields tells apart from an `invalidate` whose load is in
+     * flight, and reading it wrong runs the body again on every read. One boolean on a record only
+     * a `ttl` value allocates, rather than a field on every cell in the design.
+     */
+    dropped: boolean
+    /**
+     * The value's one timer, `null` until a production arms it and again once no deadline is held.
+     *
+     * 6.3: ONE TIMER PER VALUE.
+     */
+    timer: ReturnType<typeof setTimeout> | null
+}
+
+/**
+ * The expiry record for a value declaring `ttl`, or `null` where none is declared or no producer.
+ *
+ * 6.2: INERT ON A VALUE WITH NO PRODUCER, decided once at construction rather than tested per
+ * production. A plain state's contents are what the app put there and nothing here may drop them
+ * — so on that value the option does not merely do nothing, it allocates no record, arms no timer
+ * and leaves `direct` alone, which is the difference between an inert option and one that costs
+ * the read path.
+ */
+export function expiryFor(
+    ttl: number | undefined,
+    hasProducer: boolean,
+): Expiry | null {
+    if (ttl === undefined || !hasProducer) return null
+    return { ms: ttl, at: 0, dropped: false, timer: null }
+}
+
+/**
+ * Arms `fire` after `delay` on the holder's one timer, never holding the process open.
+ *
+ * 6.3: ONE TIMER, AND THIS IS ONLY ITS PLUMBING — which deadline is nearest is a question about
+ * the cell (its body, whether 6.7 has already run) and is answered in `Reactive.ts`
+ * where those live. What is here is the part every arming shares. Widened to anything holding one
+ * timer, because a keyed `ttl` (11.48) arms the same kind: one per holder.
+ *
+ * 6.4: A TIMER MUST NOT HOLD THE PROCESS OPEN, and the feature test is the isomorphism rather
+ * than an environment branch. Bun hands back a `Timer` carrying `unref`; a browser hands back a
+ * number and has no process to hold open, so the clause is satisfied there by there being nothing
+ * to satisfy. CLAUDE.md's uniformity bias is exactly this shape — one mechanism, inert on the side
+ * that cannot need it.
+ */
+export function armTimer(
+    expiry: { timer: ReturnType<typeof setTimeout> | null },
+    delay: number,
+    fire: () => void,
+): void {
+    const timer = setTimeout(fire, delay > 0 ? delay : 0)
+    const unref = (timer as { unref?: () => void }).unref
+    if (typeof unref === 'function') unref.call(timer)
+    expiry.timer = timer
+}

package/src/shared/reactive/FOLLOWED.ts

@@ -0,0 +1,8 @@
+/**
+ * What an invalidate of a value the server feeds over the mux sends on, by the cell its past is on.
+ *
+ * 7.10. The core calls these for every cell it invalidates, however the trigger was spelled — the
+ * value's own, a `Keyed`'s, an `Rpc`'s or a tag's — and only a value a browser follows has any, so
+ * every other invalidate is one miss. A leaf, for `PATCH_SINKS`'s reason.
+ */
+export const FOLLOWED = new WeakMap<object, Set<() => void>>()

package/src/shared/reactive/KEYED_BRAND.ts

@@ -0,0 +1,8 @@
+/**
+ * The mark that tells a `Keyed` from any other function.
+ *
+ * A leaf for the reason `REACTIVE_BRAND` is one. RULEBOOK 16.5: a transport reads which arm a
+ * handler takes off this, and never off the shape — a `Keyed` is a function taking one argument,
+ * and so is a plain handler.
+ */
+export const KEYED_BRAND: unique symbol = Symbol.for('abide.keyed')