@abide/abide 0.123.3 → 0.124.0

package/src/shared/reactive/index.ts

@@ -1,8 +1,8 @@
 // THE ONE FACTORY, and the barrel it is the address of. `state`, `memo` and `channel`
-// collapsed into overloads on one name — a channel being a value declaring `history` — and the
-// refusal behind that split survives rather than being reversed: what it refused was ONE
-// SIGNATURE WITH AN OPTIONAL PARAMETER, not one name, and overloads handing back two result
-// types is the shape its reason forces.
+// collapsed into overloads on one name — a channel being a value over an array its `patch`
+// appends to — and the refusal behind that split survives rather than being reversed: what it
+// refused was ONE SIGNATURE WITH AN OPTIONAL PARAMETER, not one name, and overloads handing
+// back two result types is the shape its reason forces.
 //
 // THE ORDER IS FORCED, and getting it wrong breaks the design silently: `() => C` is
 // assignable to `(args: A) => C` but not the reverse, so keyed-first swallows the
@@ -38,33 +38,19 @@ import { share } from './share.ts'
 export { isReactive } from './isReactive.ts'
 export { isKeyed, type Keyed } from './Keyed.ts'
 export { NotLanded } from './NotLanded.ts'
-// The server reaches the core through here rather than `./Reactive.ts`: `Reactive.ts` →
-// `log.ts` → this barrel → `scoped.ts` → `Reactive.ts` is a cycle, and a server module loaded
-// first that imports the core directly meets `MEMBER_KEYS` before it is initialized.
+// The rest of the framework reaches the core through here rather than `./Reactive.ts`: `Reactive.ts` →
+// `log.ts` → this barrel → `scoped.ts` → `Reactive.ts` is a cycle, and a module loaded first that
+// imports the core directly meets `MEMBER_KEYS` before it is initialized. The verbs a producer
+// outside the core spends a value through are `producer.ts`'s, which comes through here first.
 export {
-    abandonLoad,
-    chunksOfStream,
-    deadlineOf,
-    failedTransiently,
     flushSync,
-    followServed,
-    heldGenerationOf,
     type Identity,
-    isStreaming,
-    loadOf,
     moveItem,
-    patchInto,
-    produceInto,
     type Reactive,
     type ReactiveOptions,
-    refuseInto,
     rowItem,
     type Store,
-    servedCellOf,
-    standIn,
-    streamingOrSettled,
     type Transformer,
-    writtenLocally,
 } from './Reactive.ts'
 export { STREAMING } from './STREAMING.ts'
 export {
@@ -551,7 +537,8 @@ export function refresh<Chosen extends Selection>(
         (selection as { refresh(pattern: unknown): void }).refresh(pattern)
     else {
         refreshOver(sweep)
-        RPC_SERVER.swept?.('refresh', sweep)
+        for (const followers of RPC_SERVER.following)
+            followers.sweep('refresh', sweep)
     }
 }
 /** Marks the selection stale: drops the cache behind it, never the value. */
@@ -566,7 +553,8 @@ export function invalidate<Chosen extends Selection>(
         )
     else {
         invalidateOver(sweep)
-        RPC_SERVER.swept?.('invalidate', sweep)
+        for (const followers of RPC_SERVER.following)
+            followers.sweep('invalidate', sweep)
     }
 }
 

package/src/shared/reactive/pairReactive.ts

@@ -9,6 +9,7 @@
 // callable it adopted.
 
 import { CELL } from './CELL.ts'
+import type { Callable } from './cellShape.ts'
 import { reactive } from './index.ts'
 import { brandedPrototype, type Reactive } from './Reactive.ts'
 
@@ -32,9 +33,10 @@ const PAIR_PROTOTYPE = brandedPrototype({
  */
 export function pairReactive(pair: Pair): Reactive<unknown> {
     const over = reactive(() => pair.get())
-    const callable = (over as unknown as { [CELL]: { callable: unknown } })[
-        CELL
-    ].callable as { [PAIR]: Pair }
+    const callable = (over as unknown as Callable)[CELL]
+        .callable as unknown as {
+        [PAIR]: Pair
+    }
     Object.setPrototypeOf(callable, PAIR_PROTOTYPE)
     callable[PAIR] = pair
     return over as Reactive<unknown>

package/src/shared/reactive/producer.ts

@@ -0,0 +1,121 @@
+// THE PRODUCER PORT: every verb a producer OUTSIDE the core spends a value through — the wire and
+// the outbox writing what the server produced into a copy (`produceInto`, `patchInto`,
+// `refuseInto`), a call ending or timing the load it reached (`loadOf`, `abandonLoad`), the server
+// reading what a value serves to stamp, cache and follow it (`servedCellOf`, `deadlineOf`,
+// `followServed`). None of them is a member an app can reach; this module is where the framework's
+// other seams reach them, rather than the core itself or the app-facing barrel.
+//
+// What reads only the cell is here; what has to move the graph — a production, a refusal, a
+// superseded load — is the core's own, and this module hands it on.
+//
+// THROUGH THE BARREL FIRST, for the cycle `index.ts` names: a module reaching this port ahead of
+// the barrel would enter `Reactive.ts` first, and `scoped.ts` would meet `MEMBER_KEYS` before it is
+// initialized. `isReactive` is taken from the barrel, ahead of `Keyed.ts` and `Reactive.ts`, for
+// that reason — `cellShape.ts` has no edge into the cycle, so its place does not matter.
+
+import { CELL } from './CELL.ts'
+import { type Callable, type Cell, cellOf } from './cellShape.ts'
+import { isReactive } from './index.ts'
+import { entryDeadline } from './Keyed.ts'
+import { holdLog } from './patchLog.ts'
+import { ownStream, type Reactive } from './Reactive.ts'
+
+export {
+    abandonLoad,
+    chunksOfStream,
+    dropAnswered,
+    failedTransiently,
+    patchInto,
+    produceInto,
+    refuseInto,
+    standIn,
+    streamingOrSettled,
+} from './Reactive.ts'
+
+/** Whether `value` holds what was written here, without subscribing — for a caller that is not a reader. */
+export function writtenLocally(value: Reactive<unknown>): boolean {
+    return cellOf(value).local
+}
+
+/**
+ * The cell `value` serves from, through every adoption: its identity and its ordinal, and nothing
+ * else of it the server can reach.
+ *
+ * 11.12: an adopting value serves the adopted value's production, and an adoption of an adoption
+ * goes on down — so a follow's version (18.7) and its feed name the cell that actually produced.
+ */
+export function servedCellOf(value: unknown): { readonly ordinal: number } {
+    return adoptedCellOf(value)
+}
+
+/**
+ * Holds a patch log on the cell `value` serves from, with `invalidated` called on its every
+ * invalidate; returns what releases both. 18.11, 7.10.
+ */
+export function followServed(
+    value: unknown,
+    invalidated: () => void,
+): () => void {
+    return holdLog(adoptedCellOf(value), invalidated)
+}
+
+/**
+ * When the production `value` serves stops being servable, as a wall-clock time.
+ *
+ * 21.8 — WHEN THE PRODUCTION A VALUE IS SERVING STOPS BEING SERVABLE, as a wall-clock time: its
+ * own `ttl` from when it was minted (6.5), or its entry's from when the entry last produced
+ * (11.45), through whatever it adopts. Infinity where neither bounds it.
+ */
+export function deadlineOf(value: unknown): number {
+    const cell = adoptedCellOf(value)
+    if (cell.expiry !== null) return cell.expiry.at + cell.expiry.ms
+    return entryDeadline(cell)
+}
+
+/**
+ * The generation of the load `value` has in flight, or `undefined`.
+ *
+ * 16.48 — WHICH LOAD A VALUE HAS IN FLIGHT, as the generation that started it, or `undefined` where
+ * none is. Read off the cell rather than through `busy`, which is a probe and would subscribe the
+ * caller that asked (3.3).
+ *
+ * A WINDOW HOLDING A PRODUCTION IS BUSY AND IS NO LOAD (5.15): nothing is in flight for a call to end
+ * or time, and the window's close is its own bound. Told apart by the hold, which only a value with
+ * neither body nor stream makes — so a write's load taken in under a hold is not one a call times.
+ */
+export function loadOf(value: unknown): number | undefined {
+    const cell = cellOf(value)
+    if (!cell.loading) return undefined
+    if (cell.cap?.holding && cell.stream === null) return undefined
+    return cell.generation
+}
+
+/**
+ * The generation `value`'s past stands at, or `undefined` while a load is in flight.
+ *
+ * What 21.15's `Cached` compares across a call, read through adoption as `servedCellOf` is.
+ */
+export function heldGenerationOf(value: unknown): number | undefined {
+    const cell = adoptedCellOf(value)
+    return cell.loading ? undefined : cell.generation
+}
+
+/**
+ * Whether `value` is a streaming producer's `Reactive`.
+ *
+ * A streaming producer's own `Reactive` — a body declared as an async generator, or one whose run
+ * handed one back (9.6).
+ */
+export function isStreaming(value: unknown): boolean {
+    if (!isReactive(value)) return false
+    const stream = (value as Partial<Callable>)[CELL]?.stream
+    return stream !== null && stream !== undefined
+}
+
+function adoptedCellOf(value: unknown): Cell {
+    let cell = cellOf(value)
+    // A stream's own `adoption` is a write it follows (9.11), and its past is its own.
+    while (cell.adoption !== null && ownStream(cell) === null)
+        cell = cell.adoption.source
+    return cell
+}

package/src/shared/reactive/scoped.ts

@@ -14,6 +14,7 @@
 
 import { contractOf, type Gated } from './argsContract.ts'
 import { CELL } from './CELL.ts'
+import type { Callable, Cell } from './cellShape.ts'
 import { KEYED_BRAND } from './KEYED_BRAND.ts'
 import { brandedPrototype, MEMBER_KEYS, signalMoved } from './Reactive.ts'
 import { currentScope, runInScope, SCOPING } from './scoping.ts'
@@ -101,8 +102,8 @@ for (const key of MEMBER_KEYS)
     }
 const FORWARDING_PROTOTYPE = brandedPrototype(forwarders)
 Object.defineProperty(FORWARDING_PROTOTYPE, CELL, {
-    get(this: Forwarder): unknown {
-        return instanceOf(this[FILED])[CELL]
+    get(this: Forwarder): Cell {
+        return (instanceOf(this[FILED]) as unknown as Callable)[CELL]
     },
 })
 

package/src/shared/reactive/selections.ts

@@ -0,0 +1,209 @@
+// THE SELECTION INDEX (13.1, 13.3, 13.6): which values carry which tag, which loads a bare sweep
+// reaches, and the one probe signal per selection a guard subscribes to. Over the cell's `tags`,
+// `ref`, `filed`, `scope` and `global` and nothing else of it — what a selection DOES to the values
+// it reaches (`busyOver`, `refreshOver`, …) is the graph's, and stays in `Reactive.ts`.
+
+import { type Cell, cellOf } from './cellShape.ts'
+import { currentScope } from './scoping.ts'
+import {
+    newTracked,
+    type Subscriber,
+    type Tracked,
+    TRACKING,
+    trackProbe,
+} from './tracking.ts'
+
+/**
+ * Each tag to the values carrying it, held weakly.
+ *
+ * THE INDEX HOLDS VALUES WEAKLY. A tag is a way to find a value, never a reason to keep one, and a
+ * strong index would hold every tagged value a page ever made for the life of the process. A
+ * collected value is pruned from its sets by the next sweep that finds it gone.
+ */
+const TAGGED = new Map<string, Set<WeakRef<Cell>>>()
+
+/**
+ * Every value whose producer is a LOAD, held weakly — what a bare selection sweeps.
+ *
+ * 13.6: A BARE SWEEP REACHES PRODUCERS, and of those it files the ones that LOAD: a value holding
+ * a `store`, filed where it is built, and a body the first time it starts a load — a pending
+ * answer or a stream (`beginLoad`). A synchronous body is a derivation: reloading it recomputes
+ * what its sources already say, and whatever load it reads is filed on its own. And filing is
+ * what every filed value pays — a weak handle measured ~230 ns a value under V8 against ~20 under
+ * JSC — so a value with nothing to load never pays it: a derivation per cell per row stays at
+ * what it cost before, and a load pays it beside the promise it already allocates.
+ *
+ * Held weakly for `TAGGED`'s reason. AN ARRAY, COMPACTED, RATHER THAN A `Set`: a `Set` of weak
+ * handles measured ~120 ns a filing under JSC against ~10 for a push. What a `Set` bought was an
+ * O(1) delete on eviction; here an evicted value drops its `ref` instead, and a handle whose value
+ * no longer points back at it is dead, the same as one whose value was collected. Because a bare
+ * sweep may never run, the filing that finds the array past `compactProducersAt` compacts it, and
+ * the bar doubles past what survives, so the walk is amortized over the filings between two.
+ */
+let filedProducers: WeakRef<Cell>[] = []
+let compactProducersAt = 1024
+
+/**
+ * The probe signal a guard over a selection subscribes to.
+ *
+ * 13.3 AND 13.9: ONE SIGNAL PER SELECTION, keyed by its canonical tags. A guard over a selection
+ * subscribes to this, never to each entry — the probe edge `trackProbe` makes, from a node that
+ * is nothing but that edge.
+ */
+const SIGNALS = new Map<string, Tracked>()
+const SIGNALS_BY_TAG = new Map<string, Tracked[]>()
+/**
+ * The bare selection's one signal. Not a key in `SIGNALS`: `{ tags: [] }` canonicalizes to the
+ * empty set and matches nothing, where the bare selection matches every filed load in reach.
+ */
+export const EVERY_PRODUCER = newTracked()
+
+function refOf(cell: Cell): WeakRef<Cell> {
+    let ref = cell.ref
+    if (ref === null) {
+        ref = new WeakRef(cell)
+        cell.ref = ref
+    }
+    return ref
+}
+
+export function tagCell(cell: Cell): void {
+    const ref = refOf(cell)
+    for (const tag of cell.tags as string[]) {
+        let carrying = TAGGED.get(tag)
+        if (carrying === undefined) {
+            carrying = new Set()
+            TAGGED.set(tag, carrying)
+        }
+        carrying.add(ref)
+    }
+}
+
+export function fileProducer(cell: Cell): void {
+    cell.filed = true
+    filedProducers.push(refOf(cell))
+    if (filedProducers.length > compactProducersAt) {
+        filedProducers = liveProducers()
+        compactProducersAt = Math.max(1024, filedProducers.length * 2)
+    }
+}
+
+/** The handles whose value is still standing and still filed — neither collected nor evicted. */
+function liveProducers(): WeakRef<Cell>[] {
+    const live: WeakRef<Cell>[] = []
+    for (let index = 0; index < filedProducers.length; index += 1) {
+        const ref = filedProducers[index] as WeakRef<Cell>
+        if (ref.deref()?.ref === ref) live.push(ref)
+    }
+    return live
+}
+
+/**
+ * Removes an evicted value from every selection index.
+ *
+ * What an eviction calls: an entry out of its `Keyed` is out of every selection with it, rather
+ * than reachable by a sweep until a collection happens to run.
+ */
+export function leaveSelections(value: unknown): void {
+    const cell = cellOf(value)
+    const ref = cell.ref
+    if (ref === null) return
+    // What takes it out of `filedProducers`: a handle its value no longer points back at is dead.
+    cell.ref = null
+    if (cell.tags === null) return
+    for (const tag of cell.tags) {
+        const carrying = TAGGED.get(tag)
+        if (carrying === undefined) continue
+        carrying.delete(ref)
+        if (carrying.size === 0) TAGGED.delete(tag)
+    }
+}
+
+/**
+ * Takes every value filed so far out of the bare selection, each filed again by its next load.
+ *
+ * A TEST'S SEAM, with no caller in the framework — `bareSelection.test.ts` calls it before its
+ * first case: a page's process ends with the page, and a test process runs every file before this
+ * one in it. What those files left held — a module's `global`
+ * value, a follow the page keeps for its life — is in reach of a bare sweep (13.13), and a bare
+ * `refresh()` reloads it and reads `busy()` true while it asks.
+ */
+export function unfileProducers(): void {
+    for (let index = 0; index < filedProducers.length; index += 1) {
+        const cell = (filedProducers[index] as WeakRef<Cell>).deref()
+        if (cell !== undefined) cell.filed = false
+    }
+    filedProducers = []
+}
+
+/**
+ * The values a selection reaches in the current scope, `global` values included: those carrying
+ * any of `tags`, or every filed load where `tags` is `null` — the bare selection.
+ *
+ * 13.8 — A SELECTION IS SCOPE-BOUNDED, and a tag with it, so a selection inside one request never
+ * reaches the values another request filed. 13.13 — a `global` value is in every scope, so every
+ * selection reaches it, and 13.10 is the bare case of that. In a browser every cell's scope is
+ * `undefined`, and so is this.
+ */
+export function inReach(tags: string[] | null): Cell[] {
+    const scope = currentScope()
+    if (tags === null) {
+        filedProducers = liveProducers()
+        const found: Cell[] = []
+        for (let index = 0; index < filedProducers.length; index += 1) {
+            const cell = (
+                filedProducers[index] as WeakRef<Cell>
+            ).deref() as Cell
+            if (cell.scope === scope || cell.global) found.push(cell)
+        }
+        return found
+    }
+    const found = new Set<Cell>()
+    for (const tag of tags) {
+        const refs = TAGGED.get(tag)
+        if (refs === undefined) continue
+        for (const ref of refs) {
+            const cell = ref.deref()
+            if (cell === undefined) refs.delete(ref)
+            else if (cell.scope === scope || cell.global) found.add(cell)
+        }
+    }
+    return [...found]
+}
+
+export function trackSignal(tags: string[] | null): void {
+    const reader = TRACKING.reader
+    if (reader === null) return
+    if (tags === null) {
+        trackProbe(EVERY_PRODUCER, reader)
+        return
+    }
+    const key = JSON.stringify([...new Set(tags)].sort())
+    let signal = SIGNALS.get(key)
+    if (signal === undefined) {
+        signal = newTracked()
+        SIGNALS.set(key, signal)
+        for (const tag of tags) {
+            const signals = SIGNALS_BY_TAG.get(tag)
+            if (signals === undefined) SIGNALS_BY_TAG.set(tag, [signal])
+            else signals.push(signal)
+        }
+    }
+    trackProbe(signal, reader)
+}
+
+/**
+ * Hands `mark` the probe readers of every selection signal over any of `tags` (13.3).
+ *
+ * `mark` is the core's `markAsked`, passed rather than imported so this index stays off the graph.
+ */
+export function markSignals(
+    tags: string[],
+    mark: (asked: Subscriber[]) => void,
+): void {
+    for (const tag of tags) {
+        const signals = SIGNALS_BY_TAG.get(tag)
+        if (signals === undefined) continue
+        for (const signal of signals) mark(signal.probeReaders)
+    }
+}

package/src/shared/reactive/watch.ts

@@ -15,6 +15,7 @@ import { namedLogger } from '../log.ts'
 import { UNEXPECTED } from '../UNEXPECTED.ts'
 import { WORK } from '../WORK.ts'
 import { CELL } from './CELL.ts'
+import type { Callable } from './cellShape.ts'
 import { NotLanded } from './NotLanded.ts'
 import type { Reactive } from './Reactive.ts'
 import { currentScope, runInScope } from './scoping.ts'
@@ -161,12 +162,10 @@ export function watch(first: unknown, second?: Effect): Disposer {
     // An app hands over the VALUES; the reader list lives on each one's record. Copied
     // rather than aliased, because the reader keeps this array for its whole life and the
     // app's own array is the app's to mutate.
-    const given = (Array.isArray(first) ? first : [first]) as {
-        [CELL]: Tracked
-    }[]
+    const given = (Array.isArray(first) ? first : [first]) as Callable[]
     const sources: Tracked[] = []
     for (let index = 0; index < given.length; index += 1)
-        sources.push((given[index] as { [CELL]: Tracked })[CELL])
+        sources.push((given[index] as Callable)[CELL])
     return owned(watchOver(sources, null, second))
 }
 

package/src/shared/rpc.ts

@@ -35,7 +35,6 @@ import {
     type AdoptedFailures,
     type AdoptedProduced,
     type ChunkOf,
-    chunksOfStream,
     handlerValue,
     isKeyed,
     type Kept,
@@ -46,11 +45,14 @@ import {
     type Refusals,
     type Shaping,
     STREAMING,
-    streamingOrSettled,
     type Streams,
 } from './reactive/index.ts'
 import { MUTATION } from './reactive/MUTATION.ts'
-import { dropAnswered } from './reactive/Reactive.ts'
+import {
+    chunksOfStream,
+    dropAnswered,
+    streamingOrSettled,
+} from './reactive/producer.ts'
 import { builtHere, isForwarder } from './reactive/scoped.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
 import { checkArgs } from './refuse.ts'
@@ -532,14 +534,15 @@ export function declare(method: Method): Declare {
         }) satisfies Gated<unknown>
         const members = rpc as unknown as Record<string, unknown>
         // 7.10, 7.18 — A TRIGGER ON A SERVER REACHES EVERY BROWSER HOLDING WHAT IT NAMES, through the
-        // mux (18.3). `null` in a browser, where the trigger is the copy's own.
+        // mux (18.3). None follow in a browser, where the trigger is the copy's own.
         for (const name of SELECTION_MEMBERS) {
             if (name === 'busy') continue
             members[name] =
                 name === 'invalidate' || name === 'refresh'
                     ? (pattern?: unknown): unknown => {
                           const done = faceHere()[name](pattern)
-                          RPC_SERVER.broadcast?.(rpc, name, pattern)
+                          for (const followers of RPC_SERVER.following)
+                              followers.broadcast(rpc, name, pattern)
                           return done
                       }
                     : (pattern?: unknown): unknown => faceHere()[name](pattern)

package/src/shared/validateJson.ts

@@ -14,10 +14,9 @@
 // generated document carries them.
 
 import { isRecord } from './isRecord.ts'
+import { issuesOf, note } from './issueReport.ts'
 import type { Issues } from './Issues.ts'
-import { issuesOf } from './issuesOf.ts'
 import type { JsonValue } from './JsonValue.ts'
-import { note } from './note.ts'
 
 type Node = { [key: string]: JsonValue }
 

package/src/shared/writePath.ts

@@ -93,3 +93,32 @@ function copyOf(value: unknown, step: string | number): Level {
         return (typeof step === 'number' ? [] : {}) as unknown as Level
     return { ...(value as object) }
 }
+
+/**
+ * What `mutate` hands back, called on a copy of the array at `path` that `target` then holds.
+ *
+ * 31.9 — A MUTATOR IS A WRITE THROUGH ITS RECEIVER'S PATH. `tags.push(t)` run on the held array
+ * grows it in place, so the identity a reader wakes on never moves (31.8's failure, spelled as a
+ * call). The compiler lifts a call here only where the receiver's TYPE is an array, so a class's
+ * own `push` stays a call on the class. A level that is not plain data on the way (31.14), or a
+ * receiver that is not an array when the call runs, takes the call in place, waking nobody.
+ */
+export function mutatePath<Result>(
+    target: { (): unknown; set(value: unknown): unknown },
+    path: readonly (string | number)[],
+    mutate: (receiver: never) => Result,
+): Result {
+    const value = target()
+    let receiver = value
+    let plain = true
+    for (const step of path) {
+        plain &&= isPlain(receiver)
+        receiver = (receiver as Level | null | undefined)?.[step]
+    }
+    if (!plain) return mutate(receiver as never)
+    if (!Array.isArray(receiver)) return mutate(receiver as never)
+    const copy = receiver.slice()
+    const result = mutate(copy as never)
+    target.set(writePath(value, path, copy))
+    return result
+}