@abide/abide 0.117.0 → 0.117.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @abide/abide
 
+## 0.117.2
+
+### Patch Changes
+
+- ea4e27f: a value opening at a member of a name read by name — `reactive(route.url.searchParams.get('book') ?? '')`, `reactive(name.toUpperCase())` — is now a `Reactive` the file reads and writes by name, where before `abide check` refused every write as a string assigned to the `Reactive` and the build rebound the name instead of calling `set`
+- ea4e27f: a value a `refresh({ tags })` marked while nothing read it loads when the next page adopts it — `reactive(() => getMeetings())` on a page visited after the write sends the request and serves the new answer, where it served the answer held before the write and asked nothing (RULEBOOK 13.7)
+
+## 0.117.1
+
+### Patch Changes
+
+- 05ba855: a ceiling naming no bench fails the run, and a bench file sits beside any code it times (RULEBOOK 23.22, 43.32-43.34) ([`d5f3d3c`](https://github.com/briancray/abide/commit/d5f3d3cc6368057f8437559aafc7113abd2b3269))
+- 05ba855: a refusal and the starter's notes say a lib/ or public/ fence may sit in any directory above the file (RULEBOOK 23.22, 23.23, 37.1) ([`d9d95df`](https://github.com/briancray/abide/commit/d9d95df07fb8cb92a295ffc9a316da9b5bc6141e))
+- 9e24653: `runBenches` (`@abide/harness/runner`) and the `harness-bench` command run every `*.bench.ts` under an app's `src`, print each arm's time and the claim between them, and fail the run where an arm goes over its `CEILINGS` entry or a ceiling names no arm (RULEBOOK 43.29-43.33); `abide scaffold` writes a `bench` script that runs it, and the starter's agent notes say to measure with the harness (RULEBOOK 38.124)
+
 ## 0.117.0
 
 ### Minor Changes

package/docs/REGISTRY.md

@@ -677,6 +677,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `**/lib/**` | The app's code that is no address: components and modules. | 23.15, 23.16, 23.18, 23.22, 37.1 |
 | `**/lib/**/<name>.server.<extension>` | A server file: source the browser never loads. | 16.29, 23.23, 34.20, 36.10 |
 | `**/<name>.test.ts` | A test file: one of the app's tests, wherever it lies. | 23.22, 38.109 |
+| `**/<name>.bench.ts` | A bench file: benches `bun run bench` runs, wherever it lies. | 23.22, 43.29 |
 | `**/<name>.d.ts` | A declaration file: types for the checker, wherever it lies. | 23.22 |
 | `**/public/**` | The files answered as authored, at their path below that directory. | 23.15, 23.16, 23.18, 36.11, 36.12, 36.13, 36.14, 36.15, 36.17, 21.12, 21.13, 21.14, 38.18, 38.19 |
 | `src/public/favicon.ico` | The file answered at `/favicon.ico`. | 36.11 |
@@ -824,13 +825,19 @@ rows a runner prints, and an adapter for an abide app.
 | `inScope` | `(item: RowItem, scope: string) => boolean` | Whether an item falls in a `--scope`. | 43.26 |
 | `matchesFilter` | `(item: RowItem, filter: string) => boolean` | Whether an item matches a `--filter`. | 43.26 |
 
-## `@abide/harness/runner` — runners that print rows
+## `@abide/harness/runner` — runners that print rows, and the bench runner
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
 | `rowsCommand` | `<Item extends RowItem, Row>(items: Item[], run: (selected: Item[], emit: (row: Row) => void) => Promise<void>) => Promise<void>` | A runner's command line: its catalog under `--list`, else the rows of what it selects. | 43.26 |
 | `testRows` | `(suites: TestSuite[], cwd: string) => Promise<void>` | `rowsCommand` over the test files of `suites`, one `TestRow` per file. | 43.27 |
 | `TestSuite` | `{ section: string; root: string; runner: 'bun'; pattern?: string } \| { section: string; root: string; runner: 'playwright'; projects: string[]; pattern?: string }` | One directory of test files, listed under one section. | 43.27 |
+| `runBenches` | `(root: string, only?: string) => Promise<{ file: string; name: string; case: string; n: number; floor: number; arms: Record<string, number>; claim: string; over: string[] }[]>` | Every bench under `root`'s `src`, run, with each arm's time per operation and the ceilings it went over. | 43.29, 43.30, 43.31, 43.32, 43.34 |
+| `CEILINGS` | `Record<string, Record<string, number>>` | A bench file's export naming the most each arm of each of its benches may take, in milliseconds. | 43.29, 43.31, 43.32 |
+
+| Name | Meaning | Rules |
+| --- | --- | --- |
+| `harness-bench [word]` | The command that runs `runBenches` over the directory it runs in and prints each bench. | 43.33, 43.34 |
 
 ## `@abide/harness/abide` — the adapter for an abide app
 
@@ -849,7 +856,7 @@ rows a runner prints, and an adapter for an abide app.
 
 | Command | Meaning | Rules |
 | --- | --- | --- |
-| `abide scaffold <name>` | Writes a starter project. | 38.1, 38.42, 38.103, 38.104, 38.106, 38.112, 38.122 |
+| `abide scaffold <name>` | Writes a starter project. | 38.1, 38.42, 38.103, 38.104, 38.106, 38.112, 38.122, 38.124 |
 | `abide run <file> [args…]` | Runs a script under the abide runtime. | 38.2, 38.57 |
 | `abide check [dir…]` | The type-checker over a `.abide` tree. | 38.3, 38.31, 38.32, 38.33, 38.40, 38.105, 38.123 |
 | `abide routes [--json]` | Every address the app answers, the file answering it, and where each hook is filed. | 38.108, 38.123 |

package/docs/RULEBOOK.md

@@ -1549,7 +1549,7 @@ error naming the mount.
 `layout.abide`, an `error.abide` and the root's `launcher.abide`.
 
 23.22 A file of the app's own directly in a directory under no fence that is neither a `.abide`, a
-handler file, a test file nor a declaration file MUST be a build error naming the file and a `lib` directory, save one
+handler file, a test file, a bench file nor a declaration file MUST be a build error naming the file and a `lib` directory, save one
 beside the `package.json` of a root that holds it, nor a `.ts`.
 
 23.23 A server file of the app's own under no `lib` directory MUST be a build error naming the file
@@ -2784,6 +2784,8 @@ answered in the test's process by the handler the component's server module decl
 is outside the range abide's `engines.bun` names, and the refusal MUST name that bun's version and
 the range.
 
+38.124 The project `abide scaffold` writes MUST carry a `bench` script that runs `harness-bench`.
+
 # 39. Head and view transitions
 
 39.1 A `<head>` element in a `.abide` file MUST contribute its children to the document head.
@@ -3198,6 +3200,20 @@ runner wrote no report as `broken` rather than as a result.
 43.28 The DOM `@abide/harness/preload` registers MUST leave the runtime's own `fetch`, `Request`,
 `Response`, `Headers`, `Blob`, `File`, `FormData`, `AbortController` and `AbortSignal` the globals.
 
+43.29 `runBenches` MUST run, as one bench each, every function a bench file exports other than
+`CEILINGS`.
+
+43.30 `runBenches` MUST NOT report a bench's A/A control as one of its arms.
+
+43.31 `runBenches` MUST report an arm whose time per operation is over its `CEILINGS` entry.
+
+43.32 `runBenches` MUST report a `CEILINGS` entry naming an arm its bench does not have, and one
+naming a bench its file does not export.
+
+43.33 `harness-bench` MUST exit non-zero where `runBenches` reports anything under 43.31 or 43.32.
+
+43.34 `runBenches` given `only` MUST run only the bench files whose path below `root` holds it.
+
 # 44. The assistant
 
 44.1 `assistant` MUST answer only through a handler that yields it, and MUST NOT mount an address

package/docs/abide.md

@@ -196,6 +196,7 @@ at its address with `.md` on the end, and the links below point at those files.
 - `rowsCommand` — `reference/harness-runner/rowsCommand.md`
 - `testRows` — `reference/harness-runner/testRows.md`
 - `TestSuite` — `reference/harness-runner/types/TestSuite.md`
+- `runBenches` — `reference/harness-runner/runBenches.md`
 - `measure` — `reference/harness-abide/measure.md`
 - `AbideWork` — `reference/harness-abide/types/AbideWork.md`
 - CLI — `reference/cli.md`
@@ -6258,6 +6259,9 @@ function pipeline(count: number): () => void {
     }
 }
 
+// The most an advance may take among 1,000 deals, in milliseconds.
+export const CEILINGS = { priced: { 'among 1,000': 1 } }
+
 /** Advancing one deal among 100, and among 1,000. */
 export function priced(): Batched {
     return batch({
@@ -6285,8 +6289,13 @@ A millisecond describes the machine it was taken on. A ratio between two sizes o
 | `emulatedDom` | whether this process's DOM is an emulator |
 | `time` | `batch` with `emulated` filled in, refusing to run while the counters are armed |
 | `THRESHOLDS` | a frame and an interaction, the two lines a cost is judged against |
+| `runBenches` | runs every bench under `src`, and reports each arm over its ceiling |
+| `CEILINGS` | the most each arm of a bench may take, in milliseconds, by bench and then by arm |
+| `harness-bench` | the `bench` script: `runBenches` printed, failing where a ceiling is not held |
+
+`batch` throws on a duration whose op touched an emulated DOM, and on a sample taken in a parallel test worker. That is why the bench builds no component: it times the derived value the component reads. Run the benches with `bun run bench`, never inside `bun test`.
 
-`batch` throws on a duration whose op touched an emulated DOM, and on a sample taken in a parallel test worker. That is why the bench builds no component: it times the derived value the component reads. Run a bench under `bun run`, never inside `bun test`.
+The `bench` script is `harness-bench`, which hands `runBenches` every `*.bench.ts` under `src`, wherever one sits beside the code it times, and prints each arm's time and the claim between them. A bench file's `CEILINGS` names the most each arm may take, in milliseconds, and the run fails where an arm takes more.
 
 ## Find which layer a click spends its time in
 
@@ -6806,6 +6815,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | [`rowsCommand`](/reference/harness-runner/rowsCommand.md) | `@abide/harness/runner` |
 | [`testRows`](/reference/harness-runner/testRows.md) | `@abide/harness/runner` |
 | [`TestSuite`](/reference/harness-runner/types/TestSuite.md) | `@abide/harness/runner` |
+| [`runBenches`](/reference/harness-runner/runBenches.md) | `@abide/harness/runner` |
 | [`measure`](/reference/harness-abide/measure.md) | `@abide/harness/abide` |
 | [`AbideWork`](/reference/harness-abide/types/AbideWork.md) | `@abide/harness/abide` |
 
@@ -9133,6 +9143,7 @@ Configuration: what is written in place rather than imported.
 | `**/lib/**` | The app's code that is no address: components and modules. | [23.15](/rulebook#23.15), [23.16](/rulebook#23.16), [23.18](/rulebook#23.18), [23.22](/rulebook#23.22), [37.1](/rulebook#37.1) |
 | `**/lib/**/<name>.server.<extension>` | A server file: source the browser never loads. | [16.29](/rulebook#16.29), [23.23](/rulebook#23.23), [34.20](/rulebook#34.20), [36.10](/rulebook#36.10) |
 | `**/<name>.test.ts` | A test file: one of the app's tests, wherever it lies. | [23.22](/rulebook#23.22), [38.109](/rulebook#38.109) |
+| `**/<name>.bench.ts` | A bench file: benches `bun run bench` runs, wherever it lies. | [23.22](/rulebook#23.22), [43.29](/rulebook#43.29) |
 | `**/<name>.d.ts` | A declaration file: types for the checker, wherever it lies. | [23.22](/rulebook#23.22) |
 | `**/public/**` | The files answered as authored, at their path below that directory. | [23.15](/rulebook#23.15), [23.16](/rulebook#23.16), [23.18](/rulebook#23.18), [36.11](/rulebook#36.11), [36.12](/rulebook#36.12), [36.13](/rulebook#36.13), [36.14](/rulebook#36.14), [36.15](/rulebook#36.15), [36.17](/rulebook#36.17), [21.12](/rulebook#21.12), [21.13](/rulebook#21.13), [21.14](/rulebook#21.14), [38.18](/rulebook#38.18), [38.19](/rulebook#38.19) |
 | `src/public/favicon.ico` | The file answered at `/favicon.ico`. | [36.11](/rulebook#36.11) |
@@ -9633,6 +9644,12 @@ The measurement harness: what is written in place rather than imported.
 | --- | --- | --- |
 | `preload = ["@abide/harness/preload"]` | The `[test]` preload that registers a DOM with the measure lane's patches installed. | [43.4](/rulebook#43.4), [43.28](/rulebook#43.28) |
 
+## `@abide/harness/runner` — runners that print rows, and the bench runner
+
+| Name | Meaning | Rules |
+| --- | --- | --- |
+| `harness-bench [word]` | The command that runs `runBenches` over the directory it runs in and prints each bench. | [43.33](/rulebook#43.33), [43.34](/rulebook#43.34) |
+
 ## `@abide/harness/abide` — the adapter for an abide app
 
 | Name | Meaning | Rules |
@@ -10281,11 +10298,12 @@ The measurement harness: what is written in place rather than imported.
 
 `import { rowsCommand } from '@abide/harness/runner'`
 
-## `@abide/harness/runner` — runners that print rows
+## `@abide/harness/runner` — runners that print rows, and the bench runner
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
 | `rowsCommand` | `<Item extends RowItem, Row>(items: Item[], run: (selected: Item[], emit: (row: Row) => void) => Promise<void>) => Promise<void>` | A runner's command line: its catalog under `--list`, else the rows of what it selects. | [43.26](/rulebook#43.26) |
+| `CEILINGS` | `Record<string, Record<string, number>>` | A bench file's export naming the most each arm of each of its benches may take, in milliseconds. | [43.29](/rulebook#43.29), [43.31](/rulebook#43.31), [43.32](/rulebook#43.32) |
 
 ## Taught in
 
@@ -10299,7 +10317,7 @@ The measurement harness: what is written in place rather than imported.
 
 `import { testRows } from '@abide/harness/runner'`
 
-## `@abide/harness/runner` — runners that print rows
+## `@abide/harness/runner` — runners that print rows, and the bench runner
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
@@ -10317,7 +10335,7 @@ The measurement harness: what is written in place rather than imported.
 
 `import type { TestSuite } from '@abide/harness/runner'`
 
-## `@abide/harness/runner` — runners that print rows
+## `@abide/harness/runner` — runners that print rows, and the bench runner
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
@@ -10329,6 +10347,24 @@ The measurement harness: what is written in place rather than imported.
 
 ---
 
+<!-- reference/harness-runner/runBenches.md -->
+
+# `runBenches`
+
+`import { runBenches } from '@abide/harness/runner'`
+
+## `@abide/harness/runner` — runners that print rows, and the bench runner
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `runBenches` | `(root: string, only?: string) => Promise<{ file: string; name: string; case: string; n: number; floor: number; arms: Record<string, number>; claim: string; over: string[] }[]>` | Every bench under `root`'s `src`, run, with each arm's time per operation and the ceilings it went over. | [43.29](/rulebook#43.29), [43.30](/rulebook#43.30), [43.31](/rulebook#43.31), [43.32](/rulebook#43.32), [43.34](/rulebook#43.34) |
+
+## Taught in
+
+- [Test, measure, ship](/guide/test-measure-and-ship.md)
+
+---
+
 <!-- reference/harness-abide/measure.md -->
 
 # `measure`
@@ -10375,7 +10411,7 @@ CLI: what is written in place rather than imported.
 
 | Command | Meaning | Rules |
 | --- | --- | --- |
-| `abide scaffold <name>` | Writes a starter project. | [38.1](/rulebook#38.1), [38.42](/rulebook#38.42), [38.103](/rulebook#38.103), [38.104](/rulebook#38.104), [38.106](/rulebook#38.106), [38.112](/rulebook#38.112), [38.122](/rulebook#38.122) |
+| `abide scaffold <name>` | Writes a starter project. | [38.1](/rulebook#38.1), [38.42](/rulebook#38.42), [38.103](/rulebook#38.103), [38.104](/rulebook#38.104), [38.106](/rulebook#38.106), [38.112](/rulebook#38.112), [38.122](/rulebook#38.122), [38.124](/rulebook#38.124) |
 | `abide run <file> [args…]` | Runs a script under the abide runtime. | [38.2](/rulebook#38.2), [38.57](/rulebook#38.57) |
 | `abide check [dir…]` | The type-checker over a `.abide` tree. | [38.3](/rulebook#38.3), [38.31](/rulebook#38.31), [38.32](/rulebook#38.32), [38.33](/rulebook#38.33), [38.40](/rulebook#38.40), [38.105](/rulebook#38.105), [38.123](/rulebook#38.123) |
 | `abide routes [--json]` | Every address the app answers, the file answering it, and where each hook is filed. | [38.108](/rulebook#38.108), [38.123](/rulebook#38.123) |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.117.0",
+    "version": "0.117.2",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/scaffold/AGENTS.md

@@ -20,8 +20,14 @@ before writing code, rather than guessing from Svelte, Vue or React. It installs
   Where the read is meant, `// abide-ignore` and the clause the warning cites, on the line above
   (`// abide-ignore 14.15`), silences that one (RULEBOOK 14.19); a read hoisted out of its place
   only to quiet a warning is the bug it named.
-- `bun run test` — runs `bun test`. `src/getGreeting.test.ts` is the pattern: a test imports a
-  handler or a `.abide` file and calls it.
+- `bun run test` — runs `bun test`. `src/getGreeting.test.ts` is the pattern for a handler: a test
+  imports it and calls it. `src/index.test.ts` is the pattern for a page: `mount` it, then count
+  the work a click did with `measure`, both from `@abide/harness/abide` (RULEBOOK 38.119, 43.23).
+- `bun run bench` — runs `harness-bench`: every `*.bench.ts` under `src/`, kept beside the code it
+  times. Each export is a function returning `batch()` from `@abide/harness/report`, an op at two
+  sizes; a `CEILINGS` export, `{ [bench]: { [arm]: milliseconds } }`, names the most each arm may
+  take, and an arm over it, or a ceiling naming no bench or arm, fails the run (RULEBOOK 43.29,
+  43.31, 43.32, 43.33).
 - `bun run dev` — serves the app on a local port and rebuilds when a file changes.
 - `bun run build` then `bun run start` — the production build, and the app served from it.
 
@@ -35,10 +41,15 @@ before writing code, rather than guessing from Svelte, Vue or React. It installs
   scripts, the CLI and MCP alike.
 - A `.abide` cannot export. A `<script server>` in one holds that file's private handlers
   (`const save = POST(…)`), callable by that file alone, and its hooks (`onStart`, `middleware`, …).
-- A directory holds addresses, tests, `.d.ts` declarations and two fenced directories alone: `lib/` for components and
-  modules, and `public/` for files served as they are (`src/blog/public/cover.png` answers
-  `/blog/cover.png`). Anything else beside the pages is a build error.
-- A test is a `.test.ts`, kept beside the file it tests — a page, a handler, or a module in `lib/`.
+- A directory holds addresses, tests, benches, `.d.ts` declarations and two fenced directories alone: `lib/` for components and
+  modules, and `public/` for files served as they are. Anything else beside the pages is a build error.
+- Either fence may sit in any directory, at the root or beside the pages that use it.
+  `src/lib/` and `src/invoices/lib/` import alike (`#src/…`); the one difference is a lifecycle
+  hook a `lib/` file calls, filed at the route of the directory holding that `lib/` (RULEBOOK 37.1).
+  A `public/` file answers at the route of the directory holding it: `src/public/logo.png` answers
+  `/logo.png`, and `src/blog/public/cover.png` answers `/blog/cover.png`.
+- A test is a `.test.ts`, and a bench a `.bench.ts`, kept beside the file it tests or times — a
+  page, a handler, or a module in `lib/` (RULEBOOK 23.22).
   A browser test (playwright) is a `.test.ts` too, under `e2e/` beside `src/`: `bun test` reads
   `src/` alone (`root` in `bunfig.toml`), so it never runs one.
 - A module the browser never loads is named `<name>.server.ts` and lives in `lib/`
@@ -50,6 +61,13 @@ before writing code, rather than guessing from Svelte, Vue or React. It installs
 
 ## Habits
 
+- Measure with `@abide/harness`, not a hand-written timer, bench runner or Chrome DevTools Protocol
+  script. Its three lanes: `measure` from `@abide/harness/abide` is the DOM work and wakes an op
+  did, under `bun test`; `batch` from `@abide/harness/report` is time, in a bench; `traceOp` and
+  `shares` from `@abide/harness/engine` are what Chromium did, from a playwright test. The page
+  `guide/test-measure-and-ship.md` in `abide.md`, and "The measurement harness" in `REGISTRY.md`,
+  document it.
+
 - Export a `Reactive` itself, never wrapped in an object: an `.abide` file reads and writes it by
   name (RULEBOOK 31.1), and one reached through a property is left to `x()` and `x.set(v)` (31.7).
 - Model output and fetched HTML are untrusted. Never hand them to `raw()` (RULEBOOK 32.2)

package/src/compiler/ShadowMap.ts

@@ -167,7 +167,7 @@ function copiedFrom(
  * markup, or a read the lowering rewrote. Runs are ascending by where they stand, not by where they
  * came from, so this is a scan.
  */
-function mapForward(
+export function mapForward(
     origins: readonly Origin[],
     position: number,
 ): number | undefined {

package/src/compiler/TypeSession.ts

@@ -38,10 +38,15 @@ import { CHECKED_VALUES } from './Lowering.ts'
 import { diagnosisAt, lineOf } from './lineOf.ts'
 import type { AbideFile } from './parseAbide.ts'
 import { projectShadow, type Span } from './projectShadow.ts'
-import { abideIn } from './reactiveTypes.ts'
+import { type Abide, abideIn, isReactiveType } from './reactiveTypes.ts'
 import type { ParsedSource, ReadSource } from './readSources.ts'
 import { readsIn, type ShadowSpans } from './readsIn.ts'
-import { CHECKED_SUFFIX, SHADOW_SUFFIX, ShadowMap } from './ShadowMap.ts'
+import {
+    CHECKED_SUFFIX,
+    mapForward,
+    SHADOW_SUFFIX,
+    ShadowMap,
+} from './ShadowMap.ts'
 import { SOURCE_SUFFIX } from './splitImports.ts'
 import { type TemplateContext, templateContext } from './templateContext.ts'
 import { templateWarnings } from './templateWarnings.ts'
@@ -711,56 +716,144 @@ export class TypeSession {
         if (queries.every((query) => query === undefined))
             return { answers, warnings }
 
-        const project = await this.currentProject(created, changed)
+        let project = await this.currentProject(created, changed)
         if (project === undefined) return { answers, warnings }
-        const checker = project.checker
-        const abide = await abideIn(project)
-
-        await Promise.all(
-            queries.map(async (query, at) => {
-                if (query === undefined) return
-                const source = sources[at] as (typeof sources)[number]
-                const sourceFile = await project.program.getSourceFile(
+        // Per source, its compiler warnings, the bindings the projection could not type
+        // (`bindingsOfReads`), and those the lowered program proved a `Reactive`.
+        const warned: Diagnosis[][] = sources.map(() => [])
+        const suspects: number[][] = sources.map(() => [])
+        const held: Set<number>[] = sources.map(() => new Set())
+        const answer = async (
+            asked: Project,
+            abide: Abide,
+            at: number,
+        ): Promise<void> => {
+            const query = queries[at]
+            if (query === undefined) return
+            const source = sources[at] as (typeof sources)[number]
+            const sourceFile = await asked.program.getSourceFile(
+                query.map.shadowPath,
+            )
+            // The shadow has to be INSIDE the opened project or the checker never reads it.
+            // Refusing loudly rather than answering nothing: no reads is a file whose every
+            // name lowers as written, which renders `[object Object]` where a value was due —
+            // a wrong page, with nothing about it saying so.
+            if (sourceFile === undefined)
+                throw new Error(
+                    `abide: ${source.path} is not inside the project ${this.tsconfig}, so no name in it can be typed (RULEBOOK 31.3). Give the app a tsconfig whose include reaches it.`,
+                )
+            const read = await readsIn(
+                asked.checker,
+                abide,
+                sourceFile,
+                query.map.shadowPath,
+                query.spans,
+                source.file,
+                held[at] as Set<number>,
+            )
+            answers[at] = read.answer
+            suspects[at] = read.suspects
+            const placed: Diagnosis[] = []
+            for (const warning of read.warnings) {
+                const offset = query.map.toSource(
                     query.map.shadowPath,
+                    warning.at,
+                )
+                if (
+                    source.text === undefined ||
+                    !isIgnored(source.text, offset, warning.message)
                 )
-                // The shadow has to be INSIDE the opened project or the checker never reads it.
-                // Refusing loudly rather than answering nothing: no reads is a file whose every
-                // name lowers as written, which renders `[object Object]` where a value was due —
-                // a wrong page, with nothing about it saying so.
-                if (sourceFile === undefined)
-                    throw new Error(
-                        `abide: ${source.path} is not inside the project ${this.tsconfig}, so no name in it can be typed (RULEBOOK 31.3). Give the app a tsconfig whose include reaches it.`,
+                    placed.push(
+                        diagnosisAt(
+                            source.path,
+                            source.text,
+                            offset,
+                            'warning',
+                            warning.message,
+                        ),
                     )
-                const read = await readsIn(
-                    checker,
-                    abide,
-                    sourceFile,
-                    query.map.shadowPath,
-                    query.spans,
+            }
+            warned[at] = placed
+        }
+        const every = queries.map((_, at) => at)
+        const first = project
+        const firstAbide = await abideIn(first)
+        await Promise.all(every.map((at) => answer(first, firstAbide, at)))
+        // 31.1 — A BINDING THE PROJECTION TYPED FROM A `Reactive` IS ASKED OF THE PROGRAM IT RUNS
+        // AS: each file holding one is lowered with what it has answered so far, and a binding that
+        // is a `Reactive` there is one in the projection too. A binding typed from one that just
+        // turned out to be a `Reactive` is asked again, until a round turns none. Nothing is asked,
+        // and no second snapshot taken, where no file holds one (`bindingsOfReads`).
+        for (;;) {
+            const asking = every.filter(
+                (at) => (suspects[at] as number[]).length > 0,
+            )
+            if (asking.length === 0) break
+            const loweredCreated: string[] = []
+            const loweredChanged: string[] = []
+            const lowered = asking.map((at) => {
+                const source = sources[at] as (typeof sources)[number]
+                const query = queries[at] as { map: ShadowMap }
+                const shadow = checkedShadow(
                     source.file,
+                    answers[at] as CheckerAnswer,
                 )
-                answers[at] = read.answer
-                for (const warning of read.warnings) {
-                    const offset = query.map.toSource(
-                        query.map.shadowPath,
-                        warning.at,
-                    )
-                    if (
-                        source.text === undefined ||
-                        !isIgnored(source.text, offset, warning.message)
-                    )
-                        warnings.push(
-                            diagnosisAt(
-                                source.path,
-                                source.text,
-                                offset,
-                                'warning',
-                                warning.message,
-                            ),
-                        )
+                this.register(
+                    query.map.checkedPath,
+                    shadow.text,
+                    loweredCreated,
+                    loweredChanged,
+                )
+                this.openOutside(
+                    source.path,
+                    query.map.checkedPath,
+                    loweredChanged,
+                )
+                return {
+                    at,
+                    path: query.map.checkedPath,
+                    origins: shadow.origins,
                 }
-            }),
-        )
+            })
+            project = await this.currentProject(loweredCreated, loweredChanged)
+            if (project === undefined) return { answers, warnings }
+            const asked = project
+            const abide = await abideIn(asked)
+            const turned = new Set<number>()
+            await Promise.all(
+                lowered.map(async ({ at, path, origins }) => {
+                    const sourceFile = await asked.program.getSourceFile(path)
+                    if (sourceFile === undefined) return
+                    for (const start of suspects[at] as number[]) {
+                        const position = mapForward(origins, start)
+                        if (position === undefined) continue
+                        const symbol = await asked.checker.getSymbolAtLocation(
+                            getTouchingPropertyName(sourceFile, position),
+                        )
+                        const type =
+                            symbol === undefined
+                                ? undefined
+                                : await asked.checker.getTypeOfSymbol(symbol)
+                        if (
+                            type !== undefined &&
+                            (await isReactiveType(
+                                asked.checker,
+                                abide,
+                                type,
+                                false,
+                            ))
+                        ) {
+                            ;(held[at] as Set<number>).add(start)
+                            turned.add(at)
+                        }
+                    }
+                }),
+            )
+            if (turned.size === 0) break
+            await Promise.all([...turned].map((at) => answer(asked, abide, at)))
+            for (const at of asking) if (!turned.has(at)) suspects[at] = []
+        }
+        for (const placed of warned) warnings.push(...placed)
         return { answers, warnings }
     }
 

package/src/compiler/readsIn.ts

@@ -28,6 +28,7 @@ import {
 import {
     type Symbol as CheckedSymbol,
     type Checker,
+    SignatureKind,
     SymbolFlags,
     type Type,
     TypeFlags,
@@ -129,7 +130,9 @@ export async function readsIn(
     shadowPath: string,
     spans: ShadowSpans,
     file: AbideFile,
-): Promise<{ answer: CheckerAnswer; warnings: Finding[] }> {
+    /** Where each name the lowered program proved a `Reactive` starts (`bindingsOfReads`). */
+    held: ReadonlySet<number>,
+): Promise<{ answer: CheckerAnswer; warnings: Finding[]; suspects: number[] }> {
     // A destructuring pattern binds names this does not see, and that is 31.12's case.
     const names: Node[] = []
     const spelled = new Set<string>()
@@ -210,6 +213,12 @@ export async function readsIn(
         ),
     )
     await dropValueHolders(checker, names, reactive)
+    for (let at = 0; at < names.length; at += 1)
+        if (
+            reactive[at] === undefined &&
+            held.has((names[at] as Node).getStart())
+        )
+            reactive[at] = symbols[at]
     // 32.32 — A VALUE WHOSE `reactive(…)` DECLARES `by` keys a `{#for}` over it,
     // wherever the value is declared.
     const byValue = await Promise.all(
@@ -296,7 +305,86 @@ export async function readsIn(
         spans.scripts,
     ))
         warnings.push(warning)
-    return { answer: new CheckerAnswer(reads, statics), warnings }
+    const answer = new CheckerAnswer(reads, statics)
+    return {
+        answer,
+        warnings,
+        suspects: await bindingsOfReads(
+            checker,
+            abide,
+            names,
+            reactive,
+            answer,
+        ),
+    }
+}
+
+/**
+ * Where each binding starts whose type the projection cannot vouch for, for the lowered program to
+ * answer (`TypeSession.classify`).
+ *
+ * 31.1 — A BINDING TYPED FROM A READ IS TYPED FROM THE `Reactive` IN THE PROJECTION, and the read is
+ * of its value. `reactive(route.url.pathname)` asks a `Reactive<URL>` for a `pathname` it does not
+ * declare; the argument is the error type, which `reactive`'s overloads resolve to a `Keyed`, and
+ * the binding then lowered as no `Reactive` at all — `bookId = 'y'` rebinding the name and nothing
+ * waking. Lowered, the argument is `route.url().pathname` and the binding a `Reactive<string>`.
+ *
+ * ONLY A CALL THAT CAN HAND BACK A `Reactive` IS ASKED: an un-annotated binding, not one already,
+ * initialized by a call holding a read, to a callee one of whose signatures returns a `Reactive`.
+ * Anything else is a value however its reads are typed, and asking would cost every page that
+ * computes from one a second snapshot.
+ */
+async function bindingsOfReads(
+    checker: Checker,
+    abide: Abide,
+    names: readonly Node[],
+    reactive: readonly (CheckedSymbol | undefined)[],
+    answer: CheckerAnswer,
+): Promise<number[]> {
+    const suspects: number[] = []
+    const asked: Promise<void>[] = []
+    for (let at = 0; at < names.length; at += 1) {
+        const name = names[at] as Node
+        const declaration = name.parent
+        if (
+            reactive[at] !== undefined ||
+            !isVariableDeclaration(declaration) ||
+            declaration.type !== undefined ||
+            declaration.initializer === undefined
+        )
+            continue
+        let call: Node = declaration.initializer
+        while (TRANSPARENT.has(call.kind))
+            call = (call as unknown as { expression: Node }).expression
+        if (
+            !isCallExpression(call) ||
+            !answer.holdsRead({ start: call.getStart(), end: call.end })
+        )
+            continue
+        const callee = call.expression
+        asked.push(
+            (async () => {
+                const type = await checker.getTypeAtLocation(callee)
+                if (type === undefined) return
+                for (const signature of await checker.getSignaturesOfType(
+                    type,
+                    SignatureKind.Call,
+                )) {
+                    const returned =
+                        await checker.getReturnTypeOfSignature(signature)
+                    if (
+                        returned !== undefined &&
+                        (await isReactiveType(checker, abide, returned, false))
+                    ) {
+                        suspects.push(name.getStart())
+                        return
+                    }
+                }
+            })(),
+        )
+    }
+    await Promise.all(asked)
+    return suspects
 }
 
 /**

package/src/compiler/scaffold.ts

@@ -62,6 +62,8 @@ function filesFor(name: string): Record<string, string> {
                     routes: 'abide routes',
                     // 38.112 — the starter's own test, under the 38.109 preload.
                     test: 'bun test',
+                    // 38.124 — every `*.bench.ts` under `src`, timed, and failed over its `CEILINGS`.
+                    bench: 'harness-bench',
                 },
                 // ONE ALIAS FOR THE SOURCE, and two targets for it, because an extensionless
                 // specifier is how an import is written and only bun probes for the extension:
@@ -74,7 +76,8 @@ function filesFor(name: string): Record<string, string> {
                 dependencies: { '@abide/abide': ABIDE_DEPENDENCY },
                 // `Bun`, `bun:sqlite` and the rest of the runtime a server module reaches for are
                 // typed by these, and `abide check` reports every one untyped without them. The
-                // harness is what the starter's tests measure the work a click does with (38.119).
+                // harness is what the starter's tests measure the work a click does with (38.119), and
+                // what `bench` runs (38.124).
                 devDependencies: {
                     '@abide/harness': HARNESS_DEPENDENCY,
                     '@types/bun': 'latest',

package/src/server/appTree.ts

@@ -23,6 +23,7 @@ import {
     DIRECTORY_FILES,
     isDeclarationFile,
     isServerFile,
+    isBenchFile,
     isTestFile,
     placeOf,
     routeOf,
@@ -111,7 +112,7 @@ function walk(
             refusals.at(
                 path,
                 new Error(
-                    `abide: ${path} is a server file under no lib directory. Move it into a lib directory beside it. RULEBOOK 23.23.`,
+                    `abide: ${path} is a server file under no lib directory. Move it into a lib directory, beside it or in any directory above it. RULEBOOK 23.23.`,
                 ),
             )
             continue
@@ -119,14 +120,19 @@ function walk(
         const abide = path.endsWith('.abide')
         if (abide) files.abide.push(path)
         if (place === 'address') {
-            if (isTestFile(path) || isDeclarationFile(path)) continue
+            if (
+                isTestFile(path) ||
+                isBenchFile(path) ||
+                isDeclarationFile(path)
+            )
+                continue
             if (!abide && !isModule(path)) {
                 if (packaged && relative === '' && !path.endsWith('.ts'))
                     continue
                 refusals.at(
                     path,
                     new Error(
-                        `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages, handler files, test files and declaration files alone. Move it into a lib directory beside it. RULEBOOK 23.22.`,
+                        `abide: ${path} is directly in an address directory, which holds pages, layouts, error pages, handler files, test files, bench files and declaration files alone. Move it into a lib directory, beside it or in any directory above it. RULEBOOK 23.22.`,
                     ),
                 )
                 continue
@@ -152,9 +158,14 @@ function walk(
     }
 }
 
-/** Whether `path` names a module the app runs — neither a declaration nor a test. */
+/** Whether `path` names a module the app runs — neither a declaration, a test nor a bench. */
 function isModule(path: string): boolean {
-    return path.endsWith('.ts') && !isDeclarationFile(path) && !isTestFile(path)
+    return (
+        path.endsWith('.ts') &&
+        !isDeclarationFile(path) &&
+        !isTestFile(path) &&
+        !isBenchFile(path)
+    )
 }
 
 /** The refusal of `source` where `route` lies in the framework's own namespace, or `undefined`. 23.17. */

package/src/server/placement.ts

@@ -109,6 +109,11 @@ export function isTestFile(path: string): boolean {
     return path.endsWith('.test.ts')
 }
 
+/** Whether `path` names a bench file, which `bun run bench` reads and the app never runs. */
+export function isBenchFile(path: string): boolean {
+    return path.endsWith('.bench.ts')
+}
+
 /** Whether `path` names a declaration file, which the checker reads and nothing runs. */
 export function isDeclarationFile(path: string): boolean {
     return path.endsWith('.d.ts')

package/src/shared/reactive/Reactive.ts

@@ -2219,6 +2219,10 @@ function mirror(cell: Cell, inner: Cell): void {
     // 7.13 through the adoption: the re-settle a rerun of the adopter makes reaches a reload the
     // adopted value owes, rather than finding it unservable and giving up.
     if (inner.owes !== OWES_NOTHING) settleOwed(inner)
+    // 13.7 THROUGH THE ADOPTION TOO: a sweep's mark on a value nothing read is `DIRTY`, and an
+    // adoption is that value's next read. A mirror reached through a rerun finds it resolved
+    // already; the first one `adopt` runs does not, and copied the held value over the mark.
+    if (inner.state !== CLEAN) resolve(inner)
     const adopted = inner.stream
     if (adopted !== null) {
         forwardStream(cell, inner, adopted)