@abide/abide 0.124.1 → 0.125.0

package/docs/RULEBOOK.md

@@ -383,6 +383,20 @@ producer.
 7.19 A load over a value `s.invalidate` marked that is refused with `HttpError` at 503 MUST leave the
 value it held being served.
 
+7.20 `poll` MUST refresh the value per 7.4 every `poll` milliseconds from where it is constructed,
+and on a `Keyed` MUST refresh each entry the `Keyed` holds.
+
+7.21 `poll` MUST NOT refresh a value while its `s.busy` is true.
+
+7.22 A `poll` timer MUST NOT hold the process open.
+
+7.23 `poll` MUST stop once the value is released: the setup or request that built it, or its
+`Keyed`, ended.
+
+7.24 `poll` on a value with no producer MUST be inert.
+
+7.25 A `poll` that is not a positive number MUST refuse at construction.
+
 # 8. Stores
 
 8.1 A `Store` MUST provide both `get` and `set`.
@@ -400,7 +414,8 @@ miss falls back to.
 
 8.7 A restored stream MUST report `s.ready` true and `s.busy` false.
 
-8.8 A `Store`'s `set` MUST run once per production, per 5.2.
+8.8 A `Store`'s `set` MUST run once per production, per 5.2, save a restore and the initial value a
+miss falls back to.
 
 8.9 A `Store`'s `set` on a streaming producer MUST run once at close, on the accumulation.
 
@@ -432,6 +447,26 @@ the function it is handed MUST run `get` again as a restore, per 8.18, and MUST
 8.21 What a `Store`'s `watch` returns MUST be called once the `Reactive` is released: a `Keyed`
 entry evicted, or the setup or request that built it, or its `Keyed`, ended.
 
+8.22 `webStore` MUST keep the value under its key in `localStorage`, or in `sessionStorage` where its
+`area` is `'session'`.
+
+8.23 `webStore` MUST answer every `get` with a miss, and MUST write nothing, where the process has no
+Web Storage.
+
+8.24 `webStore`'s `watch` MUST call what it is handed when another document writes or clears its key
+in its area.
+
+8.25 `sqliteStore` MUST keep the value in one row of its table under its key, and MUST create the
+table where it does not exist.
+
+8.26 `webStore` and `sqliteStore` MUST answer a miss for a value whose `ttl`, as their `set` received
+it, has passed.
+
+8.27 `webStore` and `sqliteStore` MUST run their `schema` on what `get` reads, and MUST throw what it
+refuses, per 8.15.
+
+8.28 `webStore` and `sqliteStore` MUST keep the value as JSON.
+
 # 9. Streams and wired values
 
 9.1 A streaming producer's `Stored` MUST be the chunks accumulated so far, materialized on the
@@ -679,9 +714,9 @@ teardown of the scope it was opened in.
 12.6 A throw from an `Effect` or a `Disposer`, and a read of a failed `Reactive` inside one, MUST
 reach `onError` as thrown, and MUST warn on `abide:watch` with the trace.
 
-12.7 In a browser a throw from an `Effect` MUST additionally surface as an uncaught error — re-thrown
-to the caller of `watch` from its first run, and reported with `reportError` from a rerun — and
-MUST NOT keep any other `Effect` the same turn woke from running.
+12.7 Where `isServer` is false, a throw from an `Effect` MUST additionally surface as an uncaught
+error — re-thrown to the caller of `watch` from its first run, and reported with `reportError` from
+a rerun — and MUST NOT keep any other `Effect` the same turn woke from running.
 
 12.8 An `Effect` that threw MUST stop its `watch`.
 
@@ -698,13 +733,20 @@ woke have run.
 12.13 A `watch` registered inside a `{#if}` arm or a `{#for}` row MUST stop when the region
 holding that arm or row is removed.
 
-12.14 A `reactive` over a body that is not a stream, built where 12.4, 12.5 or 12.13 would own a
-`watch`, MUST stop reading its sources once that owner stops and nothing else reads it, and MUST
-answer a later read with what its body computes then.
+12.14 A `reactive` over a body, built where 12.4, 12.5 or 12.13 would own a `watch`, MUST stop
+reading its sources once that owner stops and nothing else reads it, and MUST answer a later read
+with what its body computes then.
 
 12.15 The `Effect` values one turn wakes, a slot's own update among them, MAY run in any order,
 save where a clause orders them.
 
+12.16 A stream released under 12.14 MUST stop its run, and the later read MUST start it once more,
+whether or not the stopped run had closed.
+
+12.17 A `reactive` declared where 12.4, 12.5 and 12.13 would own no `watch` MUST NOT be owned by
+one current where it is first reached, save the instance a request builds of it under 11.67, which
+that request owns.
+
 # 13. Selections
 
 13.1 A `Selection` MUST be one `Reactive`, one `Keyed`, one `Rpc`, or a set of `tags`.
@@ -1134,6 +1176,13 @@ a call not yet delivered.
 as a write made here (3.10), and a `GET`'s copy that 16.81 or this settles MUST be loaded again once
 `online` is true.
 
+16.86 A refusal a rung may answer with MUST reach `Failures` (16.8) where the rungs are listed at the
+declaration, and a rung naming no refusal, one typed to answer anything or a `Middleware` whose
+`Refused` is `Failed<string, unknown>`, MUST add none.
+
+16.87 A handler whose parameter carries no annotation MUST take its `Args` from the `args` its options
+declare.
+
 # 17. Response helpers
 
 17.1 Every body helper MUST take `Values<T>`.
@@ -1338,6 +1387,8 @@ MUST NOT change that type.
 19.25 `validateJson` MUST read a member left `undefined`, at any depth of a record, as absent to
 `required`, `properties` and `additionalProperties` — in process as the wire carries it (30.28).
 
+19.26 An `Issues<T>` over an `Rpc` MUST be the `Issues` of that `Rpc`'s `Args`.
+
 # 20. Generated surfaces
 
 20.1 Every surface `Clients` names MUST be derived from the route table, and MUST NOT be authored
@@ -1481,7 +1532,7 @@ stale-if-error=31536000`.
 
 # 22. Request-scoped ambients
 
-22.1 `request`, `response` and `server` MUST throw outside a request.
+22.1 `request`, `requestIP`, `response` and `server` MUST throw outside a request.
 
 22.2 `cookies` MUST be isomorphic, and on a server writes MUST be collected onto the response.
 
@@ -1505,6 +1556,16 @@ being served.
 a connection to the socket mux, whose headers went out with the upgrade. A caller minted there MUST
 be that scope's alone.
 
+22.11 `isServer` MUST be true inside a request, an `App.run` or a `render`, and wherever there is no
+document, and MUST be false everywhere else.
+
+22.12 `requestIP` MUST answer the address of the peer the listener received the request being served
+from, the same under `abide start`, `abide dev` and `App.listen`, and `null` where the listener names
+none.
+
+22.13 `requestIP` MUST answer `'in-process'` for a request no listener received: one `App.fetch` or
+`App.run` was handed in process, a call the app makes of itself among them.
+
 # 23. Route and connectivity
 
 23.1 Each member of `route` MUST be its own `Reactive`, and `route` MUST NOT be one `Reactive` over a
@@ -1520,9 +1581,9 @@ composite.
 
 23.6 `route.name` MUST be the resolution path.
 
-23.7 In a browser `online` MUST be `navigator.onLine` and its events.
+23.7 Where `isServer` is false, `online` MUST be `navigator.onLine` and its events.
 
-23.8 On a server `online` MUST be true.
+23.8 Where `isServer` is true, `online` MUST be true.
 
 23.9 In a page or a layout, `route.params()` MUST be typed by that file's own route: a required
 segment as text, an optional one as text that may be absent, a rest as a list, and in a layout any
@@ -1582,6 +1643,13 @@ under, and one naming none MUST be a build error naming the segment's file and `
 23.27 Two routes naming different matchers, or a matcher and none, at one parameter position after
 one static prefix MUST be a build error naming both files.
 
+23.28 In a browser `route.index` MUST be 0 at an entry a document load arrived at carrying no index
+the router wrote, one more than the index of the entry a push or a browser's fragment step left, and
+the index the entry was written with where a history step or a reload arrives at it — so a step back
+of no more than `route.index` entries MUST arrive at an entry of this app's router.
+
+23.29 On a server `route.index` MUST be 0.
+
 # 24. Tracing
 
 24.1 `trace` MUST be built on first ask and held for the request.
@@ -1868,6 +1936,11 @@ matches it, and a `[...rest]` naming one MUST take a part only where it does.
 30.37 An address whose part a segment refuses, by its matcher or by 30.34, MUST be matched against
 the routes 30.9 ranks after that route.
 
+30.38 `navigate` given a number MUST step the history by that many entries, back where it is
+negative, and MUST settle once the entry the next history step arrives at is arrived at, per 30.29.
+
+30.39 `navigate` given 0 MUST settle at once, and MUST NOT reload the document.
+
 # 31. Reading and writing by name
 
 31.1 Inside a `.abide` file a name bound to a `Reactive` MUST be read wherever 31.3 does not hold it.
@@ -1909,8 +1982,8 @@ type parameter constrained by one.
 array or an object whose prototype is `Object.prototype` or `null` — MUST assign on that value itself, MUST NOT
 copy it or any level above it, and MUST NOT wake a reader.
 
-31.15 `route.url`, `route.params`, `route.name` and `route.navigating` MUST each be read and written
-as a name bound to a `Reactive` is, per 31.1 to 31.7.
+31.15 `route.url`, `route.params`, `route.name`, `route.index` and `route.navigating` MUST each be
+read and written as a name bound to a `Reactive` is, per 31.1 to 31.7.
 
 # 32. Templating
 
@@ -2149,6 +2222,16 @@ build error.
 32.77 A slot holding a value branded by `raw` MUST write its markup as given, with no element or
 attribute in it removed and no URL in it scheme-checked.
 
+32.78 `abide check` MUST hold the `set` of a `bind:` on an element to what the element writes back:
+a boolean for `bind:checked` and `bind:open`, a list of files for `bind:files`, and for a
+`bind:value` `number | undefined` on an `<input>` whose `type` is `number` or `range`, and otherwise,
+on an `<input>` or a `<textarea>`, a string where the bound value holds no number,
+`number | undefined` where it holds nothing else, and all three where it holds both (32.58). A
+`<select>` MUST be held as an `<input>` is, save that where the bound value holds strings it writes
+those strings, and a `<select multiple>` a list of the strings its value's items hold, or of any
+string where they hold none. A `type` or a `multiple` written as an expression, or absent beside a
+spread, MUST be held to the union of what each value of it writes.
+
 # 33. Props
 
 33.1 `props` MUST be callable from a `<script>` block only, and calling it from a `<script module>`
@@ -2469,6 +2552,47 @@ a 405 for a rung filed at the root route.
 37.15 A `middleware` rung outside one that returned a `Failed` MUST be handed 37.14's answer from
 `next`, and MUST NOT be handed the `Failed`.
 
+37.16 An `onError` called in a component's `<script>` MUST be filed in the browser for as long as
+that component stands, and MUST file nothing where that `<script>` runs for a server's render.
+
+37.17 In a browser, a throw nothing caught, a rejection nothing handled and what 12.6 hands
+`onError` MUST each reach every `onError` 37.16 filed, the last filed first, and once — a throw
+12.6 handed MUST NOT be handed again where 12.7 surfaces it.
+
+37.18 In a browser, an `onError` that throws MUST be written to `abide:lifecycle`, and MUST NOT keep
+any other `onError` from being handed the error.
+
+37.19 A `middleware` rung MUST be handed as `ctx.lane` the `Lane` that answers the request it is
+handed, a request a rung handed `next` included: `handler` where a handler answers its method at its
+address, a private handler and one abide mounts included; `file` a file under a `public` directory;
+`openapi`, `mcp` and `bridge` that address of abide's own; `socket` the upgrade to the socket mux;
+`abide` every other address under `/__abide`; and `page` every other address, one nothing answers
+included.
+
+37.20 A `middleware` rung MUST be handed the request addressed below the path `APP_URL` names, as
+the route table reads it.
+
+37.21 An `onError` from `@abide/abide` called anywhere but a component's `<script>` being set up in a
+browser or rendered by a server — a `<script server>`, a server module, a module's top level, a
+callback that runs later — MUST throw, naming `@abide/abide/server`'s as the server's.
+
+37.22 An `onRefusal` MUST be filed, and MUST file nothing, where 37.16 has an `onError` filed and
+file nothing.
+
+37.23 An `onRefusal` called anywhere 37.21 has an `onError` from `@abide/abide` throw MUST throw.
+
+37.24 In a browser, every `Failed` an `Rpc` call is answered with over http — one its handler
+returned, one anything between the browser and the handler answered with, 16.79's, and one a call
+`outbox` sends is answered with — MUST reach every `onRefusal` 37.22 filed, the last filed first,
+and once, handed the call's method and URL beside it.
+
+37.25 A call whose `signal` aborted MUST NOT reach `onRefusal`.
+
+37.26 In a browser, an `onRefusal` that throws MUST be handled as 37.18 has an `onError` that throws.
+
+37.27 An `onRefusal` MUST NOT change the `Failed` the call refuses with, nor keep the call from
+refusing with it.
+
 # 38. Commands
 
 ## The commands
@@ -2872,6 +2996,18 @@ in its `bunfig.toml` (38.43), and a stylesheet importing `tailwindcss` that its
 38.133 Under `bun test` with `@abide/abide/test` preloaded, each test file after the first in a
 process MUST start as a bare `invalidate` (13.6) leaves the values the files before it loaded.
 
+38.134 A prop a test hands a component it binds for `mount` as an own getter MUST be read through
+that getter on each read the component makes, and any other prop MUST be the value it held when the
+component was bound.
+
+38.135 `abide routes` MUST print beside each handler every rung its declaration's `middleware`
+names, as written — an entry by the function it calls or the name it refers to, a spread by what it
+spreads, an inline function as `<inline>`, and a value that is no array as one entry — and MUST say
+where that declaration's options are not an object written inline.
+
+38.136 `abide dev`, `abide start`, the executable's `start` and the app 38.53 serves MUST listen on
+the interface `--hostname` names alone, and on every interface where it names none.
+
 # 39. Head and view transitions
 
 39.1 A `<head>` element in a `.abide` file MUST contribute its children to the document head.
@@ -3141,8 +3277,8 @@ adopts the page, however early its answer arrived.
 made an `Rpc` call, or whose markup reads a bare `busy` or `ready`, and building that component's
 markup.
 
-41.29 A `render` answering a request whose `sec-fetch-dest` is `empty` MUST NOT fill the seed buffer,
-save one whose `abide-keep` header names `open`.
+41.29 A `render` answering a request whose `sec-fetch-dest` is `empty` and whose `sec-fetch-mode` is not
+`navigate` MUST NOT fill the seed buffer.
 
 41.30 A `render` answering a request carrying `abide-keep` MUST write 41.20's script.
 
@@ -3203,6 +3339,13 @@ connection still answering, and MUST then run `onStop` without waiting on what i
 `onPrincipal` as a sealed cookie's are, MUST NOT write the principal cookie, and MUST give the scope
 a request where `request` is not given.
 
+42.20 A `principal` on `App.fetch` MUST be the claims the request's `principal` resolves from, as
+42.19 states for `App.run`, over any principal cookie the request carries.
+
+42.21 A `caller` on `App.run` or `App.fetch` MUST be its scope's `principal.caller`, over any caller
+cookie the request carries, MUST NOT write the caller cookie, and on `App.run` MUST give the scope a
+request where `request` is not given.
+
 # 43. The measurement harness
 
 43.1 `@abide/harness/measure`, `@abide/harness/engine` and `@abide/harness/server` MUST each be
@@ -3285,7 +3428,8 @@ one JSON row per line as each lands, for the items `inScope` and `matchesFilter`
 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.
+`Response`, `Headers`, `Blob`, `File`, `FormData`, `AbortController`, `AbortSignal`, `WebSocket`,
+`TransformStream` and `WritableStream` the globals.
 
 43.29 `runBenches` MUST run, as one bench each, every function a bench file exports other than
 `CEILINGS`.
@@ -3301,6 +3445,9 @@ naming a bench its file does not export.
 
 43.34 `runBenches` given `only` MUST run only the bench files whose path below `root` holds it.
 
+43.35 The DOM `@abide/harness/preload` registers MUST NOT fetch a stylesheet or a script a document
+it parses names.
+
 # 44. The assistant
 
 44.1 `assistant` MUST answer only through a handler that yields it, and MUST NOT mount an address
@@ -3395,7 +3542,7 @@ before it exits.
 44.31 A conversation MUST write one `debug` line on `abide:assistant` when its events end, naming
 its stop reason, the transcript's length, the tool calls it made, its usage and how long it took,
 and naming it `unfinished` where it ended without a `done`, followed by why — `aborted` where the
-request's signal aborted, else `failed` where its provider threw, with the throw's message ending the
+signal 44.57 hands its provider aborted, else `failed` where its provider threw, with the throw's message ending the
 line, else `stopped` where its caller stopped reading.
 
 44.32 A command `claudeCode.bridgeCommand` or `claudeCode.bridge` mints with `tools` MUST grant
@@ -3453,6 +3600,36 @@ report that turn failed.
 44.47 A bridge MUST reach `/__abide/bridge` over a certificate that either bun's own authorities or
 the authorities its machine trusts sign, however the bridge was started.
 
+44.48 `assistant` MUST carry on each `tool` and `result` `AssistantEvent` of a call to a tool its
+`Toolbox` lists the `method` and the `address` the called handler's `Rpc` reads, and MUST carry
+`undefined` for a call to any other tool.
+
+44.49 A `result` `AssistantEvent` MUST carry as its `value` its text read as JSON where its call did
+not fail and its handler has a schema 19.21 derives, and MUST carry `undefined` otherwise.
+
+44.50 A `Provider` MUST name the tool of each `tool` event it yields as its `Toolbox` lists it.
+
+44.51 `resultsOf` MUST hand back, in order, the `value` of each `result` `AssistantEvent` whose
+handler is the `Rpc` it is given, and none of a call that failed.
+
+44.52 `imagePiece` MUST draw an image longer than 1568 pixels on its long side down to 1568, and an
+image of a type 44.36 does not name at its own size, and MUST NOT draw a GIF.
+
+44.53 An image `imagePiece` draws MUST be a PNG where it was a PNG or a WebP, and a JPEG otherwise.
+
+44.54 `imagePiece` MUST hand on as it is an image it does not draw or cannot, and MUST throw where
+that image is of a type 44.36 does not name.
+
+44.55 `imageFiles` MUST hand back, in order, the files a `DataTransfer` carries of a type 44.36
+names, reading its `items` where its `files` hold none.
+
+44.56 The `install` of a pairing `claudeCode.bridgeCommand` or `claudeCode.bridge` mints MUST run
+`abide-bridge install` at the bridge release its command runs.
+
+44.57 `assistant` MUST hand its `Provider` a `limits.signal` that aborts once the request's signal
+aborts or once the `signal` its caller passed does, and once that signal aborts MUST end the
+conversation without waiting for the provider to, refused with `aborted` at status 499.
+
 # 45. Offline
 
 45.1 Where `ABIDE_OFFLINE` is on, a page `abide build` built MUST register the worker
@@ -3517,18 +3694,25 @@ and that copy is stale by no more than its `stale-if-error`.
 45.20 The worker `ABIDE_OFFLINE` turns on MUST answer a request that is not a navigation, and whose
 `cache` is `no-cache`, `reload` or `no-store`, with the network's answer alone.
 
-45.21 The worker `ABIDE_OFFLINE` turns on MUST ask the network past the browser's own cache.
+45.21 The worker `ABIDE_OFFLINE` turns on MUST ask the network past the browser's own cache, save
+for a navigation 45.25 has it ask as itself.
 
 45.22 The worker `ABIDE_OFFLINE` turns on MUST mark an answer it gives from a copy it saved with an
 `abide-kept` header naming that copy's `date`.
 
 45.23 The worker `ABIDE_OFFLINE` turns on MUST ask for a page it saves with an `abide-keep` header,
-naming `open` where its answer is the one a navigation opens.
+save for a navigation 45.25 has it ask as itself.
 
 45.24 The worker `ABIDE_OFFLINE` turns on MUST save the page of an address a `navigate` reached,
 where it saved no copy of that address 45.19 would answer with, and MUST NOT save one of another
 origin.
 
+45.25 The worker `ABIDE_OFFLINE` turns on MUST ask the network for a navigation with the navigation's
+own request, unchanged.
+
+45.26 The worker `ABIDE_OFFLINE` turns on MUST drop the copy it saved of an address where the network
+answers that address with an answer 45.3 or 45.4 does not let it save, save one of 500 or above.
+
 # 46. Outbox
 
 46.1 `outbox` MUST answer, oldest first, every call queued in it that was neither delivered nor