@abide/abide 0.105.0 → 0.106.0

package/src/shared/reactive/Reactive.ts

@@ -1394,6 +1394,44 @@ export function signalMoved(signal: Tracked): void {
     schedule()
 }
 
+/**
+ * A `{#for}` row's item as a cell, read by calling what this hands back (32.67).
+ *
+ * A `Cell` AND NOT A `reactive(value)`. The item is held exactly as the list handed it over — a
+ * `Reactive` item is not adopted (11.61), a function is not run as a body and `undefined` is a
+ * value rather than nothing landed (2.2) — and a `Cell` rather than a leaner record, so a derived
+ * value that reads a row keeps one element type in its `sources` for every walk over them.
+ *
+ * NO BRAND: the accessor is the row's own, and nothing it is handed to should take it for a value.
+ */
+export function rowItem(value: unknown): () => unknown {
+    const cell = new Cell('row', null, undefined, undefined, false)
+    serve(cell, value)
+    // A ROW ITEM IS ALWAYS DIRECT — it reads nothing, so no mark ever reaches it, and it carries no
+    // expiry, stream or store — so the read is the tracking and the field.
+    const self = function readItem(): unknown {
+        const reader = TRACKING.reader
+        if (reader !== null) {
+            const at = reader.cursor
+            if (reader.sources[at] === cell) reader.cursor = at + 1
+            else track(cell, reader)
+        }
+        return cell.value
+    } as unknown as (() => unknown) & Callable
+    self[CELL] = cell
+    return self
+}
+
+/**
+ * Writes `value` into a row's item and wakes what reads it — the same object included, which is
+ * what a patch that wrote inside it is (32.33).
+ */
+export function moveItem(item: () => unknown, value: unknown): void {
+    const cell = (item as unknown as Callable)[CELL]
+    cell.value = value
+    cascade(cell)
+}
+
 /**
  * Marks a production's readers and schedules the effects it reached.
  *
@@ -1420,68 +1458,54 @@ function cascade(cell: Cell): void {
 }
 
 /**
- * Runs the queued effects, abandoning the queue if one throws.
+ * Runs the queued effects to the end of the queue, reporting a throw rather than stopping at it.
+ *
+ * THE DRAIN, BEHIND ITS OWN FRAME. A `try` in `cascade` is a `try` on every write, and the arm
+ * that needs it is the one that actually has an effect to run — so the guard is up there and the
+ * handler is down here. The `try` is ENTERED ONCE PER THROW, not once per effect: the inner loop is
+ * the drain, and a throw re-enters it at the next slot.
  *
- * THE DRAIN, BEHIND ITS OWN FRAME. A `try`/`finally` in `cascade` is a `try`/`finally`
- * on every write, and the arm that needs it is the one that actually has an effect to
- * run — so the guard is up there and the handler is down here.
+ * 12.7 — THE DRAIN FINISHES. What reaches the catch is an effect that already stopped its own
+ * watch (12.8) and was reported (12.6); unwinding the queue over it left every sibling the drain
+ * had not reached unrun on the write that woke them. `reportError` is the throw surfacing as
+ * uncaught — the window's `error` event and the console, with the thrown value as thrown — without
+ * the unwind, and in the same turn, where a `queueMicrotask` re-throw would put it after effects
+ * that ran later than it did.
  */
 function drainPending(): void {
     draining = true
-    try {
-        // Re-read `pendingCount` per turn: an effect that writes appends to the queue
-        // this loop is walking, and those belong to this drain rather than the next write.
-        while (pendingAt < pendingCount) {
-            const reader = PENDING[pendingAt] as Subscriber
-            // THE SLOT IS RELEASED, THE ARRAY IS NOT. Holding the capacity is what keeps a
-            // push a plain indexed store, and a slot left pointing at a drained subscriber
-            // holds its `notify` — and through it the effect body and the whole scope that
-            // body closed over — until another effect happens to land on that index. A
-            // disposed `watch` stayed reachable to the next high-water mark, which on a page
-            // is every node the torn-down component built. One store per effect ALREADY RUN,
-            // against a body call.
-            PENDING[pendingAt] = null
-            pendingAt += 1
-            // A DIRECT READER OF WHAT WAS WRITTEN is `DIRTY`, which is the overwhelming
-            // shape and asks nothing: there is no source to interrogate, because the
-            // mark says one of them already produced.
-            if (reader.state === DIRTY && reader.alive) {
-                reader.state = CLEAN
-                reader.notify()
-                continue
+    // Re-read `pendingCount` per turn: an effect that writes appends to the queue this loop is
+    // walking, and those belong to this drain rather than the next write.
+    while (pendingAt < pendingCount) {
+        try {
+            while (pendingAt < pendingCount) {
+                const reader = PENDING[pendingAt] as Subscriber
+                // THE SLOT IS RELEASED, THE ARRAY IS NOT. Holding the capacity is what keeps a
+                // push a plain indexed store, and a slot left pointing at a drained subscriber
+                // holds its `notify` — and through it the effect body and the whole scope that
+                // body closed over — until another effect happens to land on that index. A
+                // disposed `watch` stayed reachable to the next high-water mark, which on a page
+                // is every node the torn-down component built. One store per effect ALREADY RUN,
+                // against a body call. Released BEFORE the run, so a throw resumes past it.
+                PENDING[pendingAt] = null
+                pendingAt += 1
+                // A DIRECT READER OF WHAT WAS WRITTEN is `DIRTY`, which is the overwhelming
+                // shape and asks nothing: there is no source to interrogate, because the
+                // mark says one of them already produced.
+                if (reader.state === DIRTY && reader.alive) {
+                    reader.state = CLEAN
+                    reader.notify()
+                    continue
+                }
+                resolveEffect(reader)
             }
-            resolveEffect(reader)
-        }
-    } finally {
-        // The queue is abandoned rather than carried into the next write: an effect that
-        // threw has already stopped its own watch (12.8), and a half-drained queue
-        // outliving the throw would run it against a later write's marks. The tail is
-        // released for the reason the loop above releases each slot; on the path that did
-        // not throw the cursor has already reached the count and this walks nothing.
-        //
-        // THE MARK GOES WITH THE QUEUE, and that is what abandoning has to mean. A reader
-        // left standing at `DIRTY` with nothing holding it takes `markReaders`' own
-        // `state >= wanted` short-circuit on every later write, so it is never queued
-        // again — one effect throwing left every sibling it had not reached permanently
-        // deaf, silently, while the value went on being right. Back to `CLEAN` is the
-        // state the next write's mark can reach.
-        //
-        // AN EFFECT ONLY, THOUGH. The queue is not effects alone: `markReaders` also pushes a
-        // derived CELL on 2.13's aborted-body path, and for one of those `state` is not a
-        // reminder to run — it IS the pull the next read takes (`state !== CLEAN` is what sends
-        // a read a frame in). Forced back to `CLEAN` it is not deaf, it is settled: the read
-        // path skips `resolve`, the aborted body is never rerun and the `ready()` guard that
-        // queued it answers false for the life of the page — undoing, on any throw anywhere in
-        // the drain, exactly what that push was added to repair.
-        for (let index = pendingAt; index < pendingCount; index += 1) {
-            const abandoned = PENDING[index] as Subscriber
-            PENDING[index] = null
-            if (abandoned.isEffect) abandoned.state = CLEAN
+        } catch (thrown) {
+            reportError(thrown)
         }
-        pendingAt = 0
-        pendingCount = 0
-        draining = false
     }
+    pendingAt = 0
+    pendingCount = 0
+    draining = false
 }
 
 /**
@@ -3095,7 +3119,7 @@ function walkBusy(cell: Cell, pass: number): boolean {
  * never reads `s()` — so it subscribes to NOTHING, and the value landing wakes nobody. It
  * is stuck on the spinner for the life of the page, with the value sitting right there.
  *
- * ON ITS OWN EDGE, which is 3.3's "that probe alone" and is bought by what the other
+ * ON ITS OWN EDGE, which is 3.3's "and MUST NOT subscribe it to the value", bought by what the other
  * spelling costs the DOM. Subscribing a probe reader through the VALUE edge works and is
  * twenty lines lighter — and then a load STARTING wakes every reader of the value, which
  * on a fifty-row list is fifty `.data` writes with the same string in them. Measured with
@@ -3610,7 +3634,7 @@ function readStore(cell: Cell, persisted: Persisted): unknown {
     } catch (failed) {
         warnStore(
             cell,
-            'could not be read, and is taken as a miss (8.15)',
+            'could not be read, and is taken as a miss. RULEBOOK 8.15',
             failed,
         )
         return undefined
@@ -3657,7 +3681,7 @@ function restoreFirst(
             if (cell.generation !== generation) return
             warnStore(
                 cell,
-                'could not be read, and is taken as a miss (8.15)',
+                'could not be read, and is taken as a miss. RULEBOOK 8.15',
                 failed,
             )
             settleRestore(cell, persisted, undefined, initial)
@@ -3759,7 +3783,7 @@ function rereadStore(cell: Cell, persisted: Persisted): void {
             if (cell.generation !== generation) return
             warnStore(
                 cell,
-                'could not be read, and is taken as a miss (8.15)',
+                'could not be read, and is taken as a miss. RULEBOOK 8.15',
                 failed,
             )
             settleReread(cell, persisted, undefined)
@@ -3820,7 +3844,11 @@ function writeStore(cell: Cell, persisted: Persisted, value: unknown): void {
 }
 
 function storeWriteFailed(cell: Cell, failed: unknown): void {
-    warnStore(cell, 'write failed, and the store stays attached (8.12)', failed)
+    warnStore(
+        cell,
+        'write failed, and the store stays attached. RULEBOOK 8.12',
+        failed,
+    )
     UNEXPECTED.report?.(failed)
 }
 
@@ -4269,6 +4297,36 @@ export function loadOf(value: unknown): number | undefined {
     return cell.generation
 }
 
+// The cells a mutation's call has been answered from, so the next call knows the answer is spent.
+const ANSWERED = new WeakSet<object>()
+
+/**
+ * Drops what an unkeyed mutation's last call was answered with, where it is past its deadline.
+ *
+ * 16.7 — A MUTATION CALLED AGAIN IS A SECOND WRITE. Its `ttl` of 0 puts what the last call answered
+ * past its deadline as it lands, and 6.3's timer drops it — but a call in the same turn reaches it
+ * before the timer does, so the call takes the timer's drop itself and its await reloads (6.6).
+ *
+ * ONLY AN ANSWER A CALL WAS GIVEN: reaching a value is what starts its first run, and a request's
+ * own instance (11.32) starts there — that run is this call's, not a spent one. A load in flight is
+ * joined (1.8), and a `ttl` the handler declared still holds.
+ */
+export function dropAnswered(value: unknown): void {
+    const cell = (value as Callable)[CELL]
+    if (!ANSWERED.has(cell)) {
+        ANSWERED.add(cell)
+        return
+    }
+    const expiry = cell.expiry
+    if (
+        expiry !== null &&
+        !cell.loading &&
+        standingLive(cell, expiry) &&
+        Date.now() - expiry.at >= expiry.ms
+    )
+        dropStanding(cell, expiry)
+}
+
 /**
  * The generation `value`'s past stands at, or `undefined` while a load is in flight.
  *

package/src/shared/reactive/canonicalKey.ts

@@ -58,7 +58,7 @@ function canonical(value: unknown, path: Steps): unknown {
     // canonicalize to one string, and 1.8 joins the second reach to the first's standing work.
     // `Object.create(null)` closed that too, and V8 builds it in DICTIONARY mode: the shipped key
     // took 49-56% of the time without it there, and a standing keyed reach 53%, where JSC reads
-    // level to 110% (`harness/scripts/sharedCases.ts`, two runs per engine).
+    // level to 110% (`abide/bench/sharedCases.ts`, two runs per engine).
     const out: Record<string, unknown> = {}
     for (let index = 0; index < keys.length; index += 1) {
         const key = keys[index] as string

package/src/shared/reactive/index.ts

@@ -49,10 +49,12 @@ export {
     type Identity,
     isStreaming,
     loadOf,
-    servedCellOf,
+    moveItem,
     type Reactive,
     type ReactiveOptions,
+    rowItem,
     type Store,
+    servedCellOf,
     streamingOrSettled,
     type Transformer,
 } from './Reactive.ts'
@@ -308,21 +310,27 @@ export function reactive<
       >,
     AdoptedProduced<ReturnType<Body>, Kept<Shaped>>
 >
-/** A computed value: `body` produces it, and runs again when a value it read changes. */
+/**
+ * A computed value: `body` produces it, and runs again when a value it read changes.
+ *
+ * 19.24 — `Computed` IS READ OFF THE BODY ALONE, hence `NoInfer` in the options: the checker infers
+ * through `Awaited`, so a `Schema<{ id: number }>` beside an async body put `{ id: number }` in
+ * `Computed` and the body's promise no longer fit it.
+ */
 export function reactive<
     Computed,
     Shaped = Awaited<Computed>,
     Gate = Schema<Awaited<Computed>>,
 >(
     body: () => Computed,
-    options?: Shaping<Awaited<Computed>, Shaped, never, Gate>,
+    options?: Shaping<Awaited<NoInfer<Computed>>, Shaped, never, Gate>,
 ): Reactive<
     Kept<Shaped>,
     Awaited<Computed>,
     AdoptedFailures<Computed> | Refusals<Shaped, Gate, Awaited<Computed>>,
     AdoptedProduced<Computed, Kept<Shaped>>
 >
-/** A keyed value: `body` declares a parameter, and each `Args` key reached is its own entry. */
+/** A keyed value: `body` declares a parameter, and each `Args` key reached is its own entry. `NoInfer` for 19.24, as above. */
 export function reactive<
     Computed,
     Args,
@@ -331,7 +339,7 @@ export function reactive<
     ArgsGate = Schema<Args>,
 >(
     body: (args: Args) => Computed,
-    options?: Shaping<Awaited<Computed>, Shaped, Args, Gate, ArgsGate>,
+    options?: Shaping<Awaited<NoInfer<Computed>>, Shaped, Args, Gate, ArgsGate>,
 ): Keyed<
     Kept<Shaped>,
     Args,

package/src/shared/reactive/recordWrites.ts

@@ -7,7 +7,7 @@
 // slots a proxy cannot stand in for — `Map.prototype.set` refuses a proxy as its receiver — so one
 // reached is marked written the moment it is read, path and all, and each object a `Map` or a `Set`
 // hands out is marked as it leaves (`heldView`). That over-reports, and an over-report costs a row
-// remade where an under-report shows a stale one.
+// its bindings rerun where an under-report shows a stale one.
 //
 // 18.11 — AND WHERE A SINK IS HANDED IN, each write is kept as data too, as JSON Patch (RFC 6902) at
 // the JSON Pointer it was reached by: a member set is `add`, an index `replace` (or `add` one past

package/src/shared/reactive/watch.ts

@@ -48,9 +48,11 @@ function reportThrow(thrown: unknown, message: string): void {
 /**
  * Reports an effect's throw, then re-throws it in a browser.
  *
- * 12.7 — A BROWSER HAS NO `onError`, so the throw goes on out to surface as an uncaught error. A
- * server's has been handed it, and re-thrown there it would fail the handler or the render whose
- * write woke this effect — a second report of one failure, against code that did not fail.
+ * 12.7 — A BROWSER HAS NO `onError`, so the throw goes on out to surface as an uncaught error: to
+ * the caller of `watch` on a first run, and on a rerun to the drain, which reports it and runs the
+ * rest of its queue (`drainPending`). A server's has been handed it, and re-thrown there it would
+ * fail the handler or the render whose write woke this effect — a second report of one failure,
+ * against code that did not fail.
  */
 function effectThrew(thrown: unknown): void {
     reportThrow(
@@ -305,10 +307,30 @@ export function watchTracked(effect: Effect): Disposer {
             truncateProbes(reader)
     }
     reader.notify()
-    return (): void => {
+    return (signal?: typeof RERUN): void => {
         if (!reader.alive) return
+        if (signal === RERUN) {
+            reader.notify()
+            return
+        }
         reader.alive = false
         detach(reader)
         if (typeof dispose === 'function') runDisposer(dispose)
     }
 }
+
+// What `rerunWatch` hands a tracked watch's stop: a symbol, so a stop called with any argument a
+// caller happens to pass — an index from `forEach` — still stops.
+const RERUN = Symbol('rerun')
+
+/**
+ * Runs the watch `stop` was handed back for (`watchTracked`) again now, tracking what it reads this
+ * time; a stopped one stays stopped.
+ *
+ * THE WATCH'S OWN STOP, CALLED WITH A SIGNAL, rather than a handle beside it: what reruns a watch
+ * is its reader, which only the stop closes over, and a second handle would cost every watch an
+ * allocation for a rerun almost none of them are ever asked for.
+ */
+export function rerunWatch(stop: Disposer): void {
+    ;(stop as (signal: typeof RERUN) => void)(RERUN)
+}

package/src/shared/rpc.ts

@@ -46,6 +46,7 @@ import {
     streamingOrSettled,
 } from './reactive/index.ts'
 import { MUTATION } from './reactive/MUTATION.ts'
+import { dropAnswered } from './reactive/Reactive.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
 import { isForwarder } from './reactive/scoped.ts'
 import { checkArgs } from './refuse.ts'
@@ -393,6 +394,10 @@ export function declare(method: Method): Declare {
                     return reactive(() => refused)
                 }
             }
+            // 16.7 — a mutation's call is a write each time, even where the last one settled this
+            // turn: a keyed value's reach evicts an outlived entry itself, and an unkeyed one's
+            // spent answer is dropped here.
+            if (cacheOptions !== undefined && !keyed) dropAnswered(value)
             const reached = callLoad(
                 reachThrough,
                 args,
@@ -494,7 +499,7 @@ export const DELETE: Declare = declare('DELETE')
 function addressOf(rpc: { address: string | undefined }): string {
     if (rpc.address === undefined)
         throw new Error(
-            "abide: this handler has no address yet. A handler is given one where it is mounted: a handler file's default (16.2), or a `const` in a <script server> (16.70).",
+            "abide: this handler has no address yet. A handler is given one where it is mounted: a handler file's default (RULEBOOK 16.2), or a `const` in a <script server> (RULEBOOK 16.70).",
         )
     return rpc.address
 }

package/src/shared/url.ts

@@ -35,9 +35,13 @@ export type RestNames<P extends string> =
             : never
         : never
 
-export type HasParams<P extends string> = [RequiredNames<P>] extends [never]
-    ? false
-    : true
+// DISTRIBUTED over a union, so a value typed as any of several literals (`x as RouteLiteral`) takes
+// its params optionally rather than demanding the union of every member's.
+export type HasParams<P extends string> = P extends string
+    ? [RequiredNames<P>] extends [never]
+        ? false
+        : true
+    : never
 
 export type HasSegments<P extends string> = [
     RequiredNames<P> | OptionalNames<P> | RestNames<P>,

package/src/shared/validateJson.ts

@@ -35,7 +35,7 @@ const VERIFIED = new WeakSet<object>()
  * WHERE AN ISSUE GOES, and `null` is a combinator's SCRATCH ATTEMPT: a branch whose issues are
  * only ever counted, never read. A record per branch per value was the whole of what `anyOf`,
  * `oneOf` and `not` allocated beyond the walk itself: 83-90% of the time without it in V8 and
- * 78-88% in JSC, and the walk is 86-99% of a gated write (`harness/scripts/sharedCases.ts`).
+ * 78-88% in JSC, and the walk is 86-99% of a gated write (`abide/bench/sharedCases.ts`).
  */
 type Report = Record<string, string[]> | null
 

package/src/ui/ArmRegion.ts

@@ -116,7 +116,7 @@ export class ArmRegion {
         const painted = namedArm(this.region.open.data)
         if (painted === undefined || painted === next) return false
         HYDRATE_LOG.warning(
-            `abide: the server painted arm ${painted} of this region and the client chose arm ${String(next)}, so the region is rebuilt (41.24).`,
+            `abide: the server painted arm ${painted} of this region and the client chose arm ${String(next)}, so the region is rebuilt. RULEBOOK 41.24.`,
         )
         return true
     }
@@ -162,7 +162,7 @@ export class ChosenRegion extends ArmRegion {
     override paintedOther(next: unknown): boolean {
         if (next != null) return false
         HYDRATE_LOG.warning(
-            'abide: the server painted a component in this region and the client chose none, so the region is emptied (41.24).',
+            'abide: the server painted a component in this region and the client chose none, so the region is emptied. RULEBOOK 41.24.',
         )
         return true
     }

package/src/ui/List.ts

@@ -6,9 +6,9 @@ import { isEmptyRegion, type Region, removeUntil } from './regions.ts'
 import {
     dropRow,
     makeRow,
+    paintedRow,
     type Row,
-    type RowBuilders,
-    rowOf,
+    type RowSetUp,
     rowsIn,
 } from './rows.ts'
 
@@ -58,13 +58,13 @@ export class List {
      * names; every other list hands back the one record it was built with, so a row allocates
      * nothing more.
      */
-    setUp: (item: unknown, at: number) => RowBuilders
+    setUp: RowSetUp
 
     constructor(
         region: Region,
         anchored: boolean,
         key: (item: unknown, at: number) => unknown,
-        setUp: (item: unknown, at: number) => RowBuilders,
+        setUp: RowSetUp,
     ) {
         this.region = region
         this.rows = []
@@ -110,13 +110,13 @@ function stopPump(list: List): void {
  * read there and only there, so the rows are hydrated against the same items the watch then
  * compares against. Read twice — once to hydrate and again on the watch's first run — a subject
  * that builds fresh items (`rows.map(…)`) matched no row by identity, and every row the server sent
- * was dropped and remade on load.
+ * was written again on load, every binding in it rerun (32.67).
  */
 export function listAt(
     region: Region,
     anchored: boolean,
     key: (item: unknown, at: number) => unknown,
-    setUp: (item: unknown, at: number) => RowBuilders,
+    setUp: RowSetUp,
 ): List {
     return new List(region, anchored, key, setUp)
 }
@@ -155,7 +155,7 @@ function hydrate(list: List, items: unknown[]): boolean {
     if (!agreed) {
         warnMismatch(
             new Mismatch(
-                `abide: the document holds ${found.length} rows where this {#for} computes ${items.length}, so the client and the server disagree about this region's shape (41.10).`,
+                `abide: the document holds ${found.length} rows where this {#for} computes ${items.length}, so the client and the server disagree about this region's shape. RULEBOOK 41.10.`,
             ),
         )
         if (found.length > items.length)
@@ -165,8 +165,8 @@ function hydrate(list: List, items: unknown[]): boolean {
     for (let at = 0; at < wired; at += 1) {
         const item = items[at]
         list.rows.push(
-            rowOf(
-                list.setUp(item, at),
+            paintedRow(
+                list.setUp,
                 list.key(item, at),
                 item,
                 found[at] as ChildNode,

package/src/ui/RawRun.ts

@@ -94,6 +94,6 @@ function clearRun(run: RawRun): void {
 
 function detached(): Mismatch {
     return new Mismatch(
-        "abide: this text run is not in a document, so the client and the server disagree about this region's shape (41.10).",
+        "abide: this text run is not in a document, so the client and the server disagree about this region's shape. RULEBOOK 41.10.",
     )
 }