@abide/abide 0.100.0 → 0.102.0

package/src/shared/reactive/recordWrites.ts

@@ -5,8 +5,9 @@
 //
 // ONLY ARRAYS AND PLAIN OBJECTS ARE WRAPPED. A `Map`, a `Set` or a class instance keeps internal
 // 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. That over-reports, and an
-// over-report costs a row remade where an under-report shows a stale 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.
 //
 // 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
@@ -49,7 +50,15 @@ export function recordWrites<Value>(
     sink?: { ops: PatchOp[]; lost: boolean },
 ): void {
     if (!isWrappable(root)) {
-        mutate(root)
+        // A root no proxy can stand in for is written as a whole: what the callback reads out of it
+        // reaches the rows that show it with no proxy to say so.
+        if (root === null || typeof root !== 'object') {
+            mutate(root)
+            return
+        }
+        PATCHES.epoch += 1
+        PATCHES.written.set(root, PATCHES.epoch)
+        mutate(heldView(root, PATCHES.epoch) as Value)
         return
     }
     PATCHES.epoch += 1
@@ -217,9 +226,10 @@ export function recordWrites<Value>(
             }
             if (entry.proxy !== null) return entry.proxy
             mark(value)
+            entry.view ??= heldView(value, epoch)
             // Reached, and outside what a proxy can watch: whatever it does next is not kept.
             if (sink !== undefined) sink.lost = true
-            return value
+            return entry.view
         },
         set(held, property, value) {
             mark(held)
@@ -363,7 +373,7 @@ function pointerOf(path: (string | number)[]): string {
 /**
  * The JSON Patch an array method makes, read off the array BEFORE it runs.
  *
- * A `splice`'s start and count are normalised the way the method does, so the `remove`s and `add`s
+ * A `splice`'s start and count are normalized the way the method does, so the `remove`s and `add`s
  * name the indices it touches.
  */
 function opsOfCall(
@@ -421,10 +431,13 @@ class Reached {
      * Written in this patch, directly or below — `PATCHES.written` holds this patch's epoch for it.
      */
     marked: boolean
+    /** What one no proxy can stand in for is handed out as: `heldView` of it. */
+    view: object | undefined
     constructor(proxy: object | null, parent: object | Parents | null) {
         this.proxy = proxy
         this.parent = parent
         this.marked = false
+        this.view = undefined
     }
 }
 
@@ -463,6 +476,91 @@ class Parents {
     }
 }
 
+/**
+ * `container` as the callback is handed it: a `Map` or a `Set` that marks written each object key,
+ * value or member it hands out, and anything else as it is.
+ *
+ * A row over `[...map.values()]` reads one of them, and a write the callback makes to it through
+ * `map.get(id)` reaches it with nothing on the way to record it — so each one taken out is taken as
+ * written. AS IT LEAVES rather than all of them up front, which would make a patch of one entry cost
+ * the whole container. One level down: a row reads its item.
+ */
+function heldView(container: object, epoch: number): object {
+    if (!(container instanceof Map) && !(container instanceof Set))
+        return container
+    return new Proxy(container, new HeldHandler(epoch))
+}
+
+// `Map`'s and `Set`'s own methods run on the container itself, which is the receiver their internal
+// slots answer to; the ones that hand an object out mark it first.
+class HeldHandler {
+    epoch: number
+    constructor(epoch: number) {
+        this.epoch = epoch
+    }
+    get(
+        held: Map<unknown, unknown> | Set<unknown>,
+        property: string | symbol,
+    ): unknown {
+        if (property === TARGET) return held
+        const value = Reflect.get(held, property, held)
+        if (typeof value !== 'function') return value
+        const epoch = this.epoch
+        if (property === 'get')
+            return (key: unknown) =>
+                markedOut((held as Map<unknown, unknown>).get(key), epoch)
+        if (property === 'forEach')
+            return (
+                each: (value: unknown, key: unknown, set: unknown) => void,
+                self?: unknown,
+            ) => {
+                for (const [key, member] of held.entries())
+                    each.call(
+                        self,
+                        markedOut(member, epoch),
+                        markedOut(key, epoch),
+                        held,
+                    )
+            }
+        if (
+            property === 'values' ||
+            property === 'keys' ||
+            property === 'entries' ||
+            property === Symbol.iterator
+        )
+            // A Map's own iterator is its entries; a Set's is its values.
+            return () =>
+                markedEach(
+                    (value as () => Iterator<unknown>).call(held),
+                    property === 'entries' ||
+                        (property === Symbol.iterator && held instanceof Map),
+                    epoch,
+                )
+        return (value as (...args: unknown[]) => unknown).bind(held)
+    }
+}
+
+function* markedEach(
+    each: Iterator<unknown>,
+    pairs: boolean,
+    epoch: number,
+): Generator<unknown> {
+    for (let next = each.next(); next.done !== true; next = each.next()) {
+        if (pairs) {
+            const [key, value] = next.value as [unknown, unknown]
+            markedOut(key, epoch)
+            markedOut(value, epoch)
+        } else markedOut(next.value, epoch)
+        yield next.value
+    }
+}
+
+function markedOut<Value>(value: Value, epoch: number): Value {
+    if (typeof value === 'object' && value !== null)
+        PATCHES.written.set(value, epoch)
+    return value
+}
+
 /** Whether a proxy can stand in for `value`: an array or a plain object. */
 function isWrappable(value: unknown): value is object {
     if (value === null || typeof value !== 'object') return false

package/src/shared/reactive/structural.ts

@@ -2,7 +2,7 @@
  * The by-value comparator an app passes as `identity`: deep equality over arrays and plain objects.
  *
  * Not the default: the default is the reference, and this is what a value whose producer
- * RE-MATERIALISES declares — `reactive(() => getInvoice({ id }), { identity: structural })`. A
+ * RE-MATERIALIZES declares — `reactive(() => getInvoice({ id }), { identity: structural })`. A
  * fresh-but-equal payload waking every reader is why it exists at all; what it stops being is the
  * price every other value pays.
  *

package/src/shared/reactive/tracking.ts

@@ -87,6 +87,11 @@ export type Subscriber = {
      * the identity gate that exists to stop exactly that cannot see a production nobody minted.
      */
     probeSources: Tracked[]
+    /**
+     * How far into `probeSources` this run has re-asked — `cursor` for the probe edge, and see
+     * `trackProbe` for why it is not the same protocol.
+     */
+    probeCursor: number
     /**
      * How far into `sources` this run has matched.
      *
@@ -111,8 +116,22 @@ export type Subscriber = {
 
 export type Tracked = {
     readers: Subscriber[]
+    /** How many of `readers` are disposed and not yet swept out — see `dropFrom`. */
+    deadReaders: number
     /** Who asked about this value's probes. Apart from `readers` — see `probeSources`. */
     probeReaders: Subscriber[]
+    /** `deadReaders` for `probeReaders`. */
+    deadProbeReaders: number
+}
+
+/** A node that is nothing but its edges — a probe signal with no value behind it. */
+export function newTracked(): Tracked {
+    return {
+        readers: [],
+        deadReaders: 0,
+        probeReaders: [],
+        deadProbeReaders: 0,
+    }
 }
 
 /** The reader whose run is on the stack, or `null` where reads subscribe to nothing. */
@@ -144,6 +163,7 @@ export function newSubscriber(
     return {
         sources,
         probeSources: [],
+        probeCursor: 0,
         cursor: 0,
         seen: null,
         seenThrough: 0,
@@ -167,8 +187,9 @@ export function newSubscriber(
  * of the loop beside this one is what CLAUDE.md's sibling-seam rule refuses.
  */
 export function dropReader(source: Tracked, reader: Subscriber): void {
-    removeFrom(source.readers, reader)
-    if (source.readers.length === 0) unread(source)
+    const readers = source.readers
+    source.deadReaders = dropFrom(readers, reader, source.deadReaders)
+    if (readers.length === 0) unread(source)
 }
 
 /**
@@ -218,40 +239,102 @@ export function untracked<First, Second, Result>(
  * rather than on a value.
  */
 export function dropProbeReader(source: Tracked, reader: Subscriber): void {
-    removeFrom(source.probeReaders, reader)
-    if (source.probeReaders.length === 0) unread(source)
+    const readers = source.probeReaders
+    source.deadProbeReaders = dropFrom(readers, reader, source.deadProbeReaders)
+    if (readers.length === 0) unread(source)
 }
 
-function removeFrom(readers: Subscriber[], reader: Subscriber): void {
+/**
+ * Takes `reader` off `readers`, of which `dead` are disposed, and returns how many are now.
+ *
+ * A DISPOSED READER IS LEFT WHERE IT IS AND COUNTED, rather than found. Finding it is a scan of
+ * every reader of the value, and a teardown drops them all — n rows reading one page value, torn
+ * down, paid n²/2 compares, and a keyed replace is the worst order there is: the new rows are
+ * pushed behind the old ones the scan walks past. 10,000 rows went 16-39 ms to 0.2-0.4. Every
+ * walk over a reader list skips `!alive`, so a dead slot costs a walk one test until the
+ * sweep below takes it out.
+ *
+ * SWEPT ONCE HALF THE LIST IS DEAD, which keeps a walk to at most twice the live readers and the
+ * sweep amortized O(1) a drop — and keeps the invariant every `length` test leans on: a list with
+ * entries has a LIVE one, since a list that is all dead is at least half dead. HALF, NOT MORE THAN
+ * HALF: a keyed replace ends on exactly half, n old rows dead behind n new ones, and a sweep that
+ * waited for one more drop kept the old rows — and through each one's `notify`, its scope and its
+ * nodes — reachable until some unrelated reader left. An over-count — a
+ * reader dropped twice — only sweeps early, and the sweep recounts from zero.
+ *
+ * A LIVE reader still scans: that is a run's own truncation or an orphan's release, a reader
+ * that may subscribe again, so it cannot be left to read as dead.
+ */
+function dropFrom(
+    readers: Subscriber[],
+    reader: Subscriber,
+    dead: number,
+): number {
+    if (!reader.alive) dead += 1
+    else purge(readers, reader)
+    if (dead * 2 < readers.length) return dead
+    let kept = 0
     for (let index = 0; index < readers.length; index += 1) {
-        if (readers[index] !== reader) continue
-        readers[index] = readers[readers.length - 1] as Subscriber
-        readers.pop()
-        return
+        const survivor = readers[index] as Subscriber
+        if (survivor.alive) {
+            readers[kept] = survivor
+            kept += 1
+        }
     }
+    readers.length = kept
+    return 0
 }
 
 /**
  * Subscribes `reader` to `source`'s probes, once per run.
  *
- * A PROBE EDGE IS REBUILT PER RUN rather than cursored. A body reads few probes where it reads
- * many values, and a guard that stops being taken must stop waking — so the list is dropped at
- * the start of a run and re-made by the reads that happen.
+ * A PROBE EDGE IS CURSORED, and kept in the order this run asked. `probeSources[0..probeCursor)`
+ * is what this run has asked so far; a source asked again is moved to the cursor rather than
+ * dropped and re-pushed, so a run that asks what its last one did touches no source's list at
+ * all. It used to be dropped at the start of every run and re-made — which put a scan of the
+ * SOURCE'S probe readers behind every rerun, and n guards over one shared `ready()` woken by one
+ * flip paid n²: 10,000 went 39 ms to 0.4. A guard that stops being taken still stops waking:
+ * what the run did not re-ask is past the cursor at its end, and `truncateProbes` drops it.
+ *
+ * NOT `track`'s protocol, because the list is a SET in no particular order where `sources` is
+ * positional: a re-ask out of order is a swap, never a divergence, and a body asks one to three.
  */
 export function trackProbe(source: Tracked, reader: Subscriber): void {
     const asked = reader.probeSources
-    for (let index = 0; index < asked.length; index += 1)
+    const at = reader.probeCursor
+    if (asked[at] === source) {
+        reader.probeCursor = at + 1
+        return
+    }
+    for (let index = 0; index < at; index += 1)
         if (asked[index] === source) return
-    asked.push(source)
-    source.probeReaders.push(reader)
+    let found = asked.length
+    for (let index = at + 1; index < asked.length; index += 1)
+        if (asked[index] === source) {
+            found = index
+            break
+        }
+    if (found === asked.length) {
+        asked.push(source)
+        source.probeReaders.push(reader)
+    }
+    asked[found] = asked[at] as Tracked
+    asked[at] = source
+    reader.probeCursor = at + 1
 }
 
-/** Drops every probe subscription `reader` holds. */
-export function detachProbes(reader: Subscriber): void {
+/** Drops the probe subscriptions `reader`'s run did not re-ask — the tail past its cursor. */
+export function truncateProbes(reader: Subscriber): void {
     const asked = reader.probeSources
-    for (let index = 0; index < asked.length; index += 1)
+    for (let index = reader.probeCursor; index < asked.length; index += 1)
         dropProbeReader(asked[index] as Tracked, reader)
-    asked.length = 0
+    asked.length = reader.probeCursor
+}
+
+/** Drops every probe subscription `reader` holds. */
+export function detachProbes(reader: Subscriber): void {
+    reader.probeCursor = 0
+    truncateProbes(reader)
 }
 
 // How far `kept * dropped` must outgrow `kept + dropped` before `truncate` builds a `Set` over the
@@ -278,8 +361,9 @@ const SET_OVER_SCAN = 20
  * `SET_OVER_SCAN`): at 1000/999 the scan is one probe per dropped slot and building the Set
  * doubled the flip, so the two are priced against each other instead.
  *
- * A duplicate inside the DROPPED tail needs no test — `removeFrom` takes one occurrence and the
- * second call finds none.
+ * A duplicate inside the DROPPED tail needs no test — `dropFrom` takes one occurrence and the
+ * second call finds none, or for a disposed reader counts one dead too many, which only sweeps
+ * early.
  *
  * Exported because a tracked run's end is exactly this and nothing more: the TEST that there is a
  * tail is the caller's — two field loads, on the rare arm.
@@ -416,3 +500,53 @@ export function detach(reader: Subscriber): void {
     truncate(reader)
     if (reader.probeSources.length !== 0) detachProbes(reader)
 }
+
+/**
+ * Lets go of every subscription `reader` holds as a DISPOSAL — counted dead where it stands
+ * (`dropFrom`) rather than scanned for — while keeping its lists, so `revive` can find what it left.
+ *
+ * FOR A RELEASED ORPHAN (12.14): n rows each deriving off one page value, torn down, scanned the
+ * page value's readers once a row. The orphan may be read again, which is what `revive` is for —
+ * paid by the read that comes back, which is rare, rather than by the release, which is per row.
+ */
+export function tombstone(reader: Subscriber): void {
+    reader.alive = false
+    const sources = reader.sources
+    for (let index = 0; index < sources.length; index += 1)
+        dropReader(sources[index] as Tracked, reader)
+    reader.cursor = 0
+    const asked = reader.probeSources
+    for (let index = 0; index < asked.length; index += 1)
+        dropProbeReader(asked[index] as Tracked, reader)
+    reader.probeCursor = 0
+}
+
+/**
+ * Takes a `tombstone`d reader's dead entries out of whatever list has not swept them yet, and
+ * makes it live with nothing subscribed — the state a fresh reader starts its run in.
+ */
+export function revive(reader: Subscriber): void {
+    reader.alive = true
+    const sources = reader.sources
+    for (let index = 0; index < sources.length; index += 1) {
+        const source = sources[index] as Tracked
+        if (purge(source.readers, reader)) source.deadReaders -= 1
+    }
+    sources.length = 0
+    const asked = reader.probeSources
+    for (let index = 0; index < asked.length; index += 1) {
+        const source = asked[index] as Tracked
+        if (purge(source.probeReaders, reader)) source.deadProbeReaders -= 1
+    }
+    asked.length = 0
+}
+
+function purge(readers: Subscriber[], reader: Subscriber): boolean {
+    for (let index = 0; index < readers.length; index += 1) {
+        if (readers[index] !== reader) continue
+        readers[index] = readers[readers.length - 1] as Subscriber
+        readers.pop()
+        return true
+    }
+    return false
+}

package/src/shared/reactive/watch.ts

@@ -20,12 +20,12 @@ import type { Reactive } from './Reactive.ts'
 import { currentScope, runInScope } from './scoping.ts'
 import {
     detach,
-    detachProbes,
     newSubscriber,
     type Subscriber,
     TRACKING,
     type Tracked,
     truncate,
+    truncateProbes,
     untracked,
 } from './tracking.ts'
 
@@ -203,7 +203,7 @@ export function watchOver(
         // UNTRACKED, AND THE CLEAR IS WHAT MAKES IT SO. The sources are given rather
         // than discovered, but the effect still RUNS wherever it was reached from — a
         // `s.watch` opened inside a `watch` had its reads attributed to the OUTER
-        // reader, which then re-ran on a value it never read. A mirror is the same
+        // reader, which then reran on a value it never read. A mirror is the same
         // shape one turn up: it runs inside the mark walk, and 4.7 has the `transform`
         // it calls there running untracked.
         const previous = TRACKING.reader
@@ -219,7 +219,7 @@ export function watchOver(
             // subscribed to, so its landing is what runs this again.
             if (thrown instanceof NotLanded) return
             // 12.8: one that throws once usually throws every run, and a watch
-            // re-running into the same throw is a loop with a log line per iteration.
+            // rerunning into the same throw is a loop with a log line per iteration.
             reader.alive = false
             detach(reader)
             effectThrew(thrown)
@@ -242,13 +242,13 @@ export function watchOver(
 }
 
 /**
- * The bare form: runs `effect` as a tracked context, re-running when anything it read changes.
+ * The bare form: runs `effect` as a tracked context, rerunning when anything it read changes.
  *
  * UNOWNED — the caller holds the stop. `watch` is this handed to its owners (`owned`); a template
  * binding's `Scope` and a `{#try}`'s retry hold their own, and call this direct.
  *
  * A SECOND BODY BESIDE `watchOver` ON PURPOSE, and it reads as the duplication it is: the two
- * differ by the cursor reset, the probe rebuild and the tail trim, and the rest is the same lines.
+ * differ by the cursor resets and the tail trims, and the rest is the same lines.
  * ONE BODY WITH A `tracked` FLAG WAS BUILT AND MEASURED, under V8 against this pair, interleaved
  * four runs a side: `write a value that changed` — one bound watch — went 15.6 ns to 21.4 in every
  * run, and `mount 50 readers` +12% (+7% under JSC). Three flag tests cannot cost 6 ns. The likely
@@ -276,7 +276,7 @@ export function watchTracked(effect: Effect): Disposer {
         const previous = TRACKING.reader
         TRACKING.reader = reader
         reader.cursor = 0
-        if (reader.probeSources.length !== 0) detachProbes(reader)
+        reader.probeCursor = 0
         reader.running = true
         try {
             WORK.wakes += 1
@@ -285,6 +285,8 @@ export function watchTracked(effect: Effect): Disposer {
             reader.running = false
             TRACKING.reader = previous
             if (reader.cursor < reader.sources.length) truncate(reader)
+            if (reader.probeCursor < reader.probeSources.length)
+                truncateProbes(reader)
             // The abort reaches here too: an effect that read a value which has
             // not landed is not an effect that failed, it is one whose turn has
             // not come. The read subscribed before it threw, so the value landing
@@ -299,6 +301,8 @@ export function watchTracked(effect: Effect): Disposer {
         reader.running = false
         TRACKING.reader = previous
         if (reader.cursor < reader.sources.length) truncate(reader)
+        if (reader.probeCursor < reader.probeSources.length)
+            truncateProbes(reader)
     }
     reader.notify()
     return (): void => {

package/src/shared/refuse.ts

@@ -15,7 +15,7 @@ import type { JsonValue } from './JsonValue.ts'
 import { namedLogger } from './log.ts'
 import { type Found, runSchema, type Schema } from './Schema.ts'
 
-/** The `abide:refuse` logger (28.9) — 15.13 and 15.15's namespace. */
+/** The `abide:refuse` logger (28.8) — 15.13 and 15.15's namespace. */
 const REFUSE_LOG = namedLogger('abide:refuse')
 
 /**