@abide/abide 0.111.0 → 0.113.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @abide/abide
 
+## 0.113.0
+
+### Minor Changes
+
+- 3c32bf6: a Store may watch — each change it reports re-reads get without running the body, and the watch stops when the value is released ([`a5539eb`](https://github.com/briancray/abide/commit/a5539eb9d1673a3b4dd98c0e35cc8d8dfb8c5e96))
+- 3c32bf6: App.run takes a principal — the claims its scope resolves from through onPrincipal, with no cookie written ([`c0db93c`](https://github.com/briancray/abide/commit/c0db93cb8f41533137a7cb3f833627bebbe9d65f))
+- 3c32bf6: under bun test with the test preload, an app that declares no ABIDE_PRINCIPAL_SECRET signs in with one the preload supplies ([`db09b9d`](https://github.com/briancray/abide/commit/db09b9d3aceeffe3d385ae295601ca9158dc2b86))
+
+### Patch Changes
+
+- 3c32bf6: an element the client builds takes the namespace the parser gives it there — a component inside an svg draws — and an xlink:href it writes is XLink's; the harness counts createElementNS and setAttributeNS ([`0dd560a`](https://github.com/briancray/abide/commit/0dd560a35d54a86d8ff5d3bc7762ed6c6968c71f))
+- 3c32bf6: a Keyed holds no entry for args its gate refuses, and the gate runs once per entry rather than on every refresh ([`1560749`](https://github.com/briancray/abide/commit/1560749419b1c571130c812fb0f6c3e2bac2a021))
+- 3c32bf6: abide check takes a url literal naming one of the framework's own fetched addresses — openapi, mcp, health, principal ([`c8af3dc`](https://github.com/briancray/abide/commit/c8af3dc746766fc5cbe322dbde551b15137c7330))
+
+## 0.112.0
+
+### Minor Changes
+
+- cabe8d1: a class or style attribute beside class: and style: directives keeps moving and writes only its own classes and declarations, and an element where a bind: and something else both write its value is a build error ([`bbbfd81`](https://github.com/briancray/abide/commit/bbbfd810d817235ddb51b8c605756187e473719e))
+
+### Patch Changes
+
+- cabe8d1: one writer owns document.head — a keyless head node stands in its contributors' order, an equal one another contributor made stays when the first leaves, and a page's head leaves with its layout's slot ([`f21f687`](https://github.com/briancray/abide/commit/f21f68742efb463f7873a6aafc4482fd572363e7))
+
 ## 0.111.0
 
 ### Minor Changes

package/docs/REGISTRY.md

@@ -68,7 +68,7 @@ Accepted, Failures>` is the inner value's own `Accepted`. Then `Failures`, then
 | `reactive` | `<Accepted = undefined, Shaped = Accepted, Gate = Schema<Accepted>>(initial: undefined, options?: Omit<ReactiveOptions<Accepted, Kept<Shaped>, never>, 'schema'> & { transform?: (value: Accepted) => Shaped; schema?: Gate & Schema<Accepted> }) => Reactive<Kept<Shaped>, Accepted, Refused<Shaped> \| Gated<Gate, Accepted>>` | The undefined overload, for a value opening at `undefined`. | 4.15, 4.16 |
 | `reactive` | `<Accepted>() => Reactive<Kept<Accepted>, Accepted, Refused<Accepted>>` | The empty overload, for a value nothing has written yet. | 4.14 |
 | `Transformer` | `<Accepted, Stored, Failures = never>(value: Accepted) => Stored \| Failures` | The shape of a `transform`. | 4.6, 4.7, 4.8 |
-| `Store` | `{ get: () => Stored \| undefined \| Promise<Stored \| undefined>; set: (value: Stored, retention: { ttl: number }) => void \| Promise<void> }` | Where a value lives when this process does not. | 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7, 8.8, 8.9, 8.10, 8.11, 8.12, 8.13, 8.14, 8.15, 8.16, 8.17, 8.18, 8.19 |
+| `Store` | `{ get: () => Stored \| undefined \| Promise<Stored \| undefined>; set: (value: Stored, retention: { ttl: number }) => void \| Promise<void>; watch?: (changed: () => void) => () => void }` | Where a value lives when this process does not. | 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7, 8.8, 8.9, 8.10, 8.11, 8.12, 8.13, 8.14, 8.15, 8.16, 8.17, 8.18, 8.19, 8.20, 8.21 |
 | `Shared` | `interface Shared {}` | The app's declaration-merged registry of shared keys. | 10.3 |
 | `reactive.share` | `<Key extends string, Value>(key: Key, create: () => Reactive<Value>) => Key extends keyof Shared ? Reactive<Shared[Key]> : Reactive<Value>` | Get-or-create a reactive value in the component's scope by key. | 10.1, 10.2, 10.4, 10.5, 10.6, 10.7 |
 
@@ -94,7 +94,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `structural` | `(next: unknown, previous: unknown) => boolean` | The by-value comparator an app declares on `identity`. | 5.4, 5.5, 18.4 |
 | `by` | `(keyof Element & string) \| ((element: Element) => unknown)`, over the `Element` a `Stored` array holds | What tells one element of the value from another. | 5.22, 18.4, 18.15, 32.32 |
 | `ttl` | `number` | The life of a production, or of a keyed entry. | 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7, 6.8, 6.9, 6.10, 11.6, 11.35, 11.45, 11.48, 11.49, 11.69 |
-| `args` | `Schema<Args>` | The gate on a keyed value's args. | 9.4, 11.28, 11.30, 11.40, 11.41, 11.56, 11.60, 11.68 |
+| `args` | `Schema<Args>` | The gate on a keyed value's args. | 9.4, 11.28, 11.30, 11.40, 11.41, 11.56, 11.60, 11.68, 11.72 |
 | `global` | `boolean` | Opts out of the default scope into one cache shared by every caller in the process. | 11.34, 11.35, 11.36, 11.37, 11.38, 11.39, 11.53, 11.67 |
 | `tags` | `string[] \| ((args: Args) => string[])` | What a `Selection` matches on. | 11.43, 11.44, 18.4, 18.15 |
 | `throttle` | `number` | A ceiling on how often the value changes. | 5.8, 5.9, 5.11, 5.12, 5.14, 5.15, 5.17, 5.18, 5.19, 5.20, 5.21, 5.23, 5.24 |
@@ -529,18 +529,18 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `{expr}` | Reactive text, escaped. | 32.1, 32.23 |
 | formatting whitespace | What a run of whitespace renders as. | 33.17, 33.18 |
 | `{raw(...)}` | Raw HTML. | 32.2, 32.25, 32.26, 32.30, 32.31, 32.70 |
-| `name={expr}` | A reactive attribute or property. | 32.3, 32.20, 32.23, 32.37 |
+| `name={expr}` | A reactive attribute or property. | 32.3, 32.20, 32.23, 32.37, 32.70, 32.71 |
 | `on<event>={fn}` | A native listener on an element, and an ordinary prop on a component. | 32.4 |
-| `name="…{expr}…"` | An interpolated quoted value. | 32.3 |
-| `bind:value` | Two-way bind on an element. | 5.16, 32.5, 32.58, 32.59, 32.60, 32.61, 32.62 |
+| `name="…{expr}…"` | An interpolated quoted value. | 32.3, 32.71 |
+| `bind:value` | Two-way bind on an element. | 5.16, 32.5, 32.58, 32.59, 32.60, 32.61, 32.62, 32.72 |
 | `bind:prop={state}` | Hands a component prop the caller's `Reactive`, or a `{get, set}` pair, to write through. | 32.6, 33.6, 33.8, 14.18 |
-| `bind:checked` | A boolean bind on an input. | 32.7 |
-| `bind:open` | The same, on a `<details>`. | 32.7 |
-| `bind:group` | Radio or checkbox membership. | 32.8 |
+| `bind:checked` | A boolean bind on an input. | 32.7, 32.72 |
+| `bind:open` | The same, on a `<details>`. | 32.7, 32.72 |
+| `bind:group` | Radio or checkbox membership. | 32.8, 32.72 |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | 32.5, 32.6 |
 | `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | 32.9, 32.38, 32.66, 32.68, 32.69 |
-| `class:name={cond}` | Toggles a class. | 32.10 |
-| `style:prop={value}` | Sets one style property. | 32.10, 32.19 |
+| `class:name={cond}` | Toggles a class. | 32.10, 32.71 |
+| `style:prop={value}` | Sets one style property. | 32.10, 32.19, 32.71 |
 | `{...expr}` | Spreads props or attributes. | 32.11, 32.37, 33.12, 33.13 |
 | static template text | What an author writes outside a slot, in body text and in an attribute value. | 32.27, 32.28 |
 
@@ -564,10 +564,10 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | Spelling | Meaning | Rules |
 | --- | --- | --- |
 | `{#component Name(pattern)}` | An inline component. | 32.39, 32.40, 32.41, 32.42, 32.43, 32.44, 32.45, 32.46, 32.47, 32.48, 32.49, 32.50, 32.51, 32.52, 32.53, 32.54, 32.55, 32.63, 32.64 |
-| `<Name/>` | A component invocation. | 32.17, 32.34, 32.35, 32.36, 33.19, 33.21, 41.24, 41.28 |
+| `<Name/>` | A component invocation. | 32.17, 32.34, 32.35, 32.36, 32.70, 33.19, 33.21, 41.24, 41.28 |
 | `<slot/>` | The position children render into. | 32.18 |
 | `<slot>fallback</slot>` | Renders children, or a fallback. | 32.18 |
-| `<Tag>…</Tag>` | Children passed to a component's slot. | 32.18 |
+| `<Tag>…</Tag>` | Children passed to a component's slot. | 32.18, 32.70 |
 
 ## Props
 
@@ -629,7 +629,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `APP_NAME` | `string` | The app's name, and `log`'s default namespace. | 27.3, 28.4 |
 | `APP_VERSION` | `string` | The version beside that name. | 27.3 |
 | `APP_DATA_DIR` | `string` | The platform's per-user data directory. | 27.3, 36.4 |
-| `ABIDE_PRINCIPAL_SECRET` | `string \| null` | What seals the principal cookie. | 26.11, 36.5 |
+| `ABIDE_PRINCIPAL_SECRET` | `string \| null` | What seals the principal cookie. | 26.11, 36.5, 38.120 |
 | `ABIDE_PRINCIPAL_TTL` | `number` | The principal cookie's life, in ms. | 26.15, 26.16 |
 | `ABIDE_APP_TOKEN` | `string \| null` | The bearer the remote CLI sends. | 36.6 |
 | `ABIDE_APP_URL` | `string \| null` | Names an app somewhere else, for the remote CLI. | 36.6 |
@@ -706,7 +706,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `createApp` | `() => Promise<App>` | The app built and booted, with no socket bound. | 42.1, 42.2, 42.3, 42.4, 42.16, 37.4, 37.6, 38.100 |
 | `App` | `interface App` | What a host, a test or a script holds the app as. | 42.12, 42.13 |
 | `App.fetch` | `(request: Request) => Promise<Response>` | The whole request path, entered in process. | 42.5, 42.6 |
-| `App.run` | `<Result>(fn: () => Result \| Promise<Result>, options?: { request?: Request }) => Promise<Result>` | One scope around a function, and nothing else. | 42.7, 42.8, 11.38 |
+| `App.run` | `<Result>(fn: () => Result \| Promise<Result>, options?: { request?: Request; principal?: Record<string, unknown> }) => Promise<Result>` | One scope around a function, and nothing else. | 42.7, 42.8, 42.19, 11.38 |
 | `App.listen` | `(options?: { port?: number; hostname?: string; unix?: string }) => Promise<void>` | The socket, bound. | 42.9, 16.23, 16.56, 18.28, 18.29, 18.30 |
 | `App.stop` | `() => Promise<void>` | The drain and the teardown. | 42.10, 42.11, 42.15, 42.17, 37.4 |
 | `App[Symbol.asyncDispose]` | `() => Promise<void>` | `App.stop`, under the name `await using` calls. | 42.14 |

package/docs/RULEBOOK.md

@@ -413,6 +413,12 @@ the value of that write standing in its place.
 
 8.19 A `Store`'s `get` answering a miss with nothing left to serve MUST land an error on `s.error`.
 
+8.20 A `Store`'s `watch` MUST be called once, where the `Reactive` is constructed, and each call of
+the function it is handed MUST run `get` again as a restore, per 8.18, and MUST NOT run the body.
+
+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.
+
 # 9. Streams and wired values
 
 9.1 A streaming producer's `Stored` MUST be the chunks accumulated so far, materialized on the
@@ -641,6 +647,9 @@ start again when the load ends.
 11.71 An unkeyed `reactive` with a `store`, built on a server outside every request, MUST NOT run
 the `store`'s `get` before it is reached.
 
+11.72 A `Keyed` MUST NOT hold an entry for an `Args` its `args` gate refuses, and the gate MUST run
+once per entry.
+
 # 12. Effects
 
 12.1 A `Disposer` MUST run before each rerun of its `Effect`, and once more at teardown.
@@ -1725,8 +1734,8 @@ the page shown, and MUST NOT where only its query or fragment does.
 30.25 A `navigate` that does not remount the page MUST NOT move the scroll, except to the element a
 fragment it carries names.
 
-30.26 `abide check` MUST refuse a `url` literal that no page route of the app (23.3) is filed under
-and no public file of the app is served at.
+30.26 `abide check` MUST refuse a `url` literal that no page route of the app (23.3) is filed under,
+no public file of the app is served at, and that is none of the four addresses 21.4 names.
 
 30.27 A `navigate` whose request fails, or whose route's chunks fail to load, MUST leave the address
 to the document, save where 30.32 holds.
@@ -2001,7 +2010,18 @@ reading layout, querying its descendants or calling `focus()` acts on a connecte
 32.69 `bind:element` on a component MUST be a build error.
 
 32.70 Markup the client parses for a slot holding a value branded by `raw`, a `{#if}` arm or a
-`{#for}` row MUST be parsed as the document's parser parses it inside the element it goes into.
+`{#for}` row MUST be parsed as the document's parser parses it inside the element it goes into, and
+an element the client builds — a component's own, or children a caller hands one — MUST take the
+namespace the document's parser gives it there, as MUST an attribute the client writes on it.
+
+32.71 A `class` or `style` attribute beside a `class:name` or `style:prop` MUST keep moving (32.3)
+and MUST write only its own classes or declarations; a class either of them holds MUST stay on the
+element, and a style property MUST resolve as the server's merged attribute does — the attribute's
+declarations first, then each directive's in the tag's order.
+
+32.72 An element MUST be a build error where a `bind:` and something else both write its value: the
+attribute a `bind:name` names, `checked` beside `bind:group`, an `<option selected>` inside a
+`<select bind:value>`, or text inside a `<textarea bind:value>`.
 
 # 33. Props
 
@@ -2663,6 +2683,10 @@ it, MUST hydrate it there with that component's browser module, and MUST run eve
 hydration woke before it settles; it MUST throw where the component was not imported from a
 `.abide` and bound, or where the process has no DOM.
 
+38.120 Under `bun test` with `@abide/abide/test` preloaded, an app that declares no
+`ABIDE_PRINCIPAL_SECRET` MUST seal and verify the principal cookie with a secret the preload
+supplies, and `abide start` MUST NOT supply that secret.
+
 # 39. Head and view transitions
 
 39.1 A `<head>` element in a `.abide` file MUST contribute its children to the document head.
@@ -2674,8 +2698,9 @@ hydration woke before it settles; it MUST throw where the component was not impo
 39.4 `<head>` contributions MUST be merged by key, and the deepest contributor MUST win. The shell's
 `<head>` MUST be the outermost contributor.
 
-39.5 A `<head>` contribution with no merge key MUST append — in tree order among the contributions
-its level mounts with, and when it mounts for a component mounted after its level.
+39.5 A `<head>` contribution with no merge key MUST append, and MUST stand in its contributors'
+order — each level's own, then its components' in the order they mounted, outermost level first — a
+component mounted after its level included.
 
 39.6 On a client navigation the incoming page's keyed `<head>` contributions MUST replace the
 outgoing page's by key, and a layout's MUST NOT move.
@@ -2709,7 +2734,7 @@ contributor has that key.
 MUST replace, in place, the one that same contributor wrote before.
 
 39.16 A `<head>` contribution with no merge key MUST be removed when the page, layout or component
-that made it leaves.
+that made it leaves, and an equal one another contributor made MUST stay.
 
 39.17 A `<script>` a `<head>` contribution writes in a browser MUST run when it is written, as the
 one a server paints does, and MUST NOT run again while the same contributor writes it unchanged.
@@ -2980,6 +3005,10 @@ connection still answering, and MUST then run `onStop` without waiting on what i
 
 42.18 `ABIDE_STOP_TIMEOUT` MUST default to 5000.
 
+42.19 A `principal` on `App.run` MUST be the claims its scope's `principal` resolves from, through
+`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.
+
 # 43. The measurement harness
 
 43.1 `@abide/harness/measure`, `@abide/harness/engine` and `@abide/harness/server` MUST each be

package/docs/abide.md

@@ -2382,6 +2382,8 @@ test('the view picked is the view the next visit opens on', async () => {
 
 A `Store` is a `get` and a `set`. The value reads the store when it is built and falls back to `'board'` on a miss, and every change is written back. The reads and writes in the markup do not change.
 
+Where the stored value can change from outside the app, such as a file another program edits, the store adds `watch`. It is handed a function to call when that happens, and returns the function that stops watching. The value reads `get` again, and the body does not run.
+
 This store goes through two handlers, so the server and the browser read the same preference and the first paint is already right. A store over `localStorage` works too, but only in a browser, so the server paints the fallback first. After a write, `set` invalidates the read it made, so the next read asks the server rather than this tab's copy.
 
 ## Next
@@ -3718,7 +3720,6 @@ export default POST(() => principal.clear(), { description: 'Signs out.' })
 import { expect, test } from 'bun:test'
 import { principal } from '@abide/abide'
 import { createApp } from '@abide/abide/server'
-import { asMember } from './signedIn.ts'
 
 const signIn = (email: string) =>
     new Request('http://crm.invalid/account/signIn', {
@@ -3727,17 +3728,28 @@ const signIn = (email: string) =>
         body: JSON.stringify({ email }),
     })
 
-test('signing in seals the caller into an HttpOnly cookie', async () => {
+test('signing in seals the id into an HttpOnly cookie', async () => {
     await using app = await createApp()
     const answer = await app.fetch(signIn('maya@crm.example'))
     const [sealed = ''] = answer.headers.getSetCookie()
     expect(sealed).toStartWith('abide-principal=')
     expect(sealed).toContain('HttpOnly')
+
+    // The seal is a JWT; its payload is the id, and the times abide adds.
+    const token = sealed.split(';')[0]?.split('=')[1] ?? ''
+    const payload = JSON.parse(
+        Buffer.from(token.split('.')[1] ?? '', 'base64url').toString(),
+    )
+    expect(Object.keys(payload).sort()).toEqual(['exp', 'iat', 'id'])
 })
 
 test('a request carrying the cookie is signed in', async () => {
     await using app = await createApp()
-    const request = await asMember(app, 'maya@crm.example')
+    const answer = await app.fetch(signIn('maya@crm.example'))
+    const [sealed = ''] = answer.headers.getSetCookie()
+    const request = new Request('http://crm.invalid/', {
+        headers: { cookie: sealed.split(';')[0] ?? '' },
+    })
     const signedIn = await app.run(async () => await principal.authenticated, {
         request,
     })
@@ -3749,7 +3761,7 @@ test('a request carrying the cookie is signed in', async () => {
 
 The answer also tells the browser the caller changed. Every tab of the site reads `principal` again, so the form's own button flips with nothing passed to it.
 
-The seal is a JWT signed with `ABIDE_PRINCIPAL_SECRET`, and it lives for `ABIDE_PRINCIPAL_TTL` milliseconds, a week unless you set it. The chapter app keeps a development secret in its `.env`, so set your own wherever the app is deployed. A comma-separated list rotates a secret in: the first signs, and every one verifies.
+The seal is a JWT signed with `ABIDE_PRINCIPAL_SECRET`, and it lives for `ABIDE_PRINCIPAL_TTL` milliseconds, a week unless you set it. The chapter app keeps a development secret in its `.env`, so set your own wherever the app is deployed. A comma-separated list rotates a secret in: the first signs, and every one verifies. Under `bun test` an app that sets no secret is given one, so a test signs in from a fresh clone.
 
 | Read | What it is |
 | --- | --- |
@@ -3808,21 +3820,11 @@ onPrincipal((claims) => {
 import { expect, test } from 'bun:test'
 import { principal } from '@abide/abide'
 import { createApp } from '@abide/abide/server'
-import { asMember } from './signedIn.ts'
 
-test('the cookie holds an id, and the request reads the member', async () => {
+test('the claims resolve to the member they name', async () => {
     await using app = await createApp()
-    const request = await asMember(app, 'theo@crm.example')
-
-    // The seal is a JWT; its payload is the id, and the times abide adds.
-    const sealed = request.headers.get('cookie') ?? ''
-    const payload = JSON.parse(
-        Buffer.from(sealed.split('.')[1] ?? '', 'base64url').toString(),
-    )
-    expect(Object.keys(payload).sort()).toEqual(['exp', 'iat', 'id'])
-
     const member = await app.run(async () => await principal.resolved, {
-        request,
+        principal: { id: 'theo' },
     })
     expect(member.name).toBe('Theo Park')
     expect(member.role).toBe('sales')
@@ -3831,6 +3833,8 @@ test('the cookie holds an id, and the request reads the member', async () => {
 
 `onPrincipal` is handed the claims and returns your half of the caller. It runs on the server, at most once per request, where the team records are. So the cookie stays small, and a rename shows on the next request rather than at the next sign-in. Filed in any handler file or `.abide`, it resolves the caller for every route.
 
+A test signs in without the cookie. `app.run(fn, { principal: { id: 'theo' } })` hands those claims to `onPrincipal` as a sealed cookie's are, and the card's test reads the member they name.
+
 What it returns is read as `principal.resolved`, typed by `Principal`. Declare your fields on that interface, as the app's `lib/TEAM.server.ts` does beside the team it reads. abide's own three fields are `authenticated`, `expiresAt` and `error`, and they win any collision, so a resolver cannot sign a caller in by returning `authenticated: true`. A resolver that throws fills `error` and leaves the caller signed out.
 
 The tabs on this card, the deal-value card and the export card are `lib/SignInAs.abide`, which calls the same `signIn` handler.
@@ -3934,19 +3938,20 @@ export default GET(
 import { expect, test } from 'bun:test'
 import { createApp } from '@abide/abide/server'
 import getContact from '../getContact.ts'
-import { asMember } from './signedIn.ts'
 
 test('an admin reads the deal value', async () => {
     await using app = await createApp()
-    const request = await asMember(app, 'maya@crm.example')
-    const contact = await app.run(async () => await getContact(), { request })
+    const contact = await app.run(async () => await getContact(), {
+        principal: { id: 'maya' },
+    })
     expect(contact.dealValue).toBe('$48,000')
 })
 
 test('sales reads the rest of the contact', async () => {
     await using app = await createApp()
-    const request = await asMember(app, 'theo@crm.example')
-    const contact = await app.run(async () => await getContact(), { request })
+    const contact = await app.run(async () => await getContact(), {
+        principal: { id: 'theo' },
+    })
     expect(contact.name).toBe('Grace Hopper')
     expect(contact.dealValue).toBeUndefined()
 })
@@ -4009,23 +4014,24 @@ export default POST(async () => CONTACTS, {
 import { expect, test } from 'bun:test'
 import { createApp } from '@abide/abide/server'
 import exportContacts from '../exportContacts.ts'
-import { asMember } from './signedIn.ts'
 
 test('an admin exports every contact', async () => {
     await using app = await createApp()
-    const request = await asMember(app, 'maya@crm.example')
     const contacts = await app.run(async () => await exportContacts(), {
-        request,
+        principal: { id: 'maya' },
     })
     expect(contacts).toHaveLength(3)
 })
 
 test('sales and a signed-out caller are refused 403', async () => {
     await using app = await createApp()
-    for (const email of ['theo@crm.example', undefined]) {
-        const request = await asMember(app, email)
+    const callers = [
+        { principal: { id: 'theo' } },
+        { request: new Request('http://crm.invalid/') },
+    ]
+    for (const caller of callers) {
         try {
-            await app.run(async () => await exportContacts(), { request })
+            await app.run(async () => await exportContacts(), caller)
             throw new Error('the export was not refused')
         } catch (refusal) {
             if (!exportContacts.isError(refusal, 'HttpError')) throw refusal
@@ -4961,13 +4967,13 @@ A handler file already carries an address, a method, an argument type and a desc
 
 ```abide src/assistant/lib/OpenApiOperation.abide
 <script>
-import { reactive, type RouteLiteral, url } from '@abide/abide'
+import { reactive, url } from '@abide/abide'
 
 type Operation = { description: string; parameters: object[] }
 let operation = reactive('')
 
 async function readDocument() {
-    const answer = await fetch(url('/__abide/openapi.json' as RouteLiteral))
+    const answer = await fetch(url('/__abide/openapi.json'))
     const document: { paths: Record<string, { get: Operation }> } =
         await answer.json()
     for (const [path, { get }] of Object.entries(document.paths))
@@ -5046,7 +5052,7 @@ abide openapi > openapi.json
 
 ```abide src/assistant/lib/ModelToolCall.abide
 <script>
-import { reactive, type RouteLiteral, url } from '@abide/abide'
+import { reactive, url } from '@abide/abide'
 
 let tool = reactive('—')
 let description = reactive('—')
@@ -5054,7 +5060,7 @@ let answer = reactive('—')
 
 // One JSON-RPC message to the app's MCP endpoint, as a model's client sends it.
 async function ask(method: string, params: object) {
-    const reply = await fetch(url('/__abide/mcp' as RouteLiteral), {
+    const reply = await fetch(url('/__abide/mcp'), {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
@@ -5147,14 +5153,14 @@ abide mcp --url https://crm.example
 
 ```abide src/assistant/lib/WithheldExport.abide
 <script>
-import { reactive, type RouteLiteral, url } from '@abide/abide'
+import { reactive, url } from '@abide/abide'
 import exportContacts from '../exportContacts.ts'
 
 let listed = reactive('—')
 let answers = reactive('—')
 
 async function check() {
-    const reply = await fetch(url('/__abide/mcp' as RouteLiteral), {
+    const reply = await fetch(url('/__abide/mcp'), {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
@@ -5743,7 +5749,7 @@ test('the summary answers in process as it does on the wire', async () => {
 | --- | --- |
 | `App` | what `createApp` hands back, to a test, a script or a host |
 | `App.fetch` | one request, through the whole app, in this process |
-| `App.run` | runs a function inside one request's scope, so two reads of one key load once |
+| `App.run` | runs a function inside one request's scope, so two reads of one key load once, signed in as the `principal` claims you give it |
 | `App.listen` | binds the socket, for a test that needs a real `WebSocket` |
 | `App.stop` | drains what is in flight, then runs `onStop` |
 | `App[Symbol.asyncDispose]` | `stop`, under the name `await using` calls |
@@ -6827,7 +6833,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `Store` | `{ get: () => Stored \| undefined \| Promise<Stored \| undefined>; set: (value: Stored, retention: { ttl: number }) => void \| Promise<void> }` | Where a value lives when this process does not. | [8.1](/rulebook#8.1), [8.2](/rulebook#8.2), [8.3](/rulebook#8.3), [8.4](/rulebook#8.4), [8.5](/rulebook#8.5), [8.6](/rulebook#8.6), [8.7](/rulebook#8.7), [8.8](/rulebook#8.8), [8.9](/rulebook#8.9), [8.10](/rulebook#8.10), [8.11](/rulebook#8.11), [8.12](/rulebook#8.12), [8.13](/rulebook#8.13), [8.14](/rulebook#8.14), [8.15](/rulebook#8.15), [8.16](/rulebook#8.16), [8.17](/rulebook#8.17), [8.18](/rulebook#8.18), [8.19](/rulebook#8.19) |
+| `Store` | `{ get: () => Stored \| undefined \| Promise<Stored \| undefined>; set: (value: Stored, retention: { ttl: number }) => void \| Promise<void>; watch?: (changed: () => void) => () => void }` | Where a value lives when this process does not. | [8.1](/rulebook#8.1), [8.2](/rulebook#8.2), [8.3](/rulebook#8.3), [8.4](/rulebook#8.4), [8.5](/rulebook#8.5), [8.6](/rulebook#8.6), [8.7](/rulebook#8.7), [8.8](/rulebook#8.8), [8.9](/rulebook#8.9), [8.10](/rulebook#8.10), [8.11](/rulebook#8.11), [8.12](/rulebook#8.12), [8.13](/rulebook#8.13), [8.14](/rulebook#8.14), [8.15](/rulebook#8.15), [8.16](/rulebook#8.16), [8.17](/rulebook#8.17), [8.18](/rulebook#8.18), [8.19](/rulebook#8.19), [8.20](/rulebook#8.20), [8.21](/rulebook#8.21) |
 
 ## Taught in
 
@@ -6869,7 +6875,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | `identity` | `(next: Stored, previous: Stored) => unknown` | What makes it the same value. | [5.1](/rulebook#5.1), [5.2](/rulebook#5.2), [5.3](/rulebook#5.3), [5.4](/rulebook#5.4), [5.5](/rulebook#5.5), [9.3](/rulebook#9.3), [11.17](/rulebook#11.17), [18.4](/rulebook#18.4) |
 | `by` | `(keyof Element & string) \| ((element: Element) => unknown)`, over the `Element` a `Stored` array holds | What tells one element of the value from another. | [5.22](/rulebook#5.22), [18.4](/rulebook#18.4), [18.15](/rulebook#18.15), [32.32](/rulebook#32.32) |
 | `ttl` | `number` | The life of a production, or of a keyed entry. | [6.1](/rulebook#6.1), [6.2](/rulebook#6.2), [6.3](/rulebook#6.3), [6.4](/rulebook#6.4), [6.5](/rulebook#6.5), [6.6](/rulebook#6.6), [6.7](/rulebook#6.7), [6.8](/rulebook#6.8), [6.9](/rulebook#6.9), [6.10](/rulebook#6.10), [11.6](/rulebook#11.6), [11.35](/rulebook#11.35), [11.45](/rulebook#11.45), [11.48](/rulebook#11.48), [11.49](/rulebook#11.49), [11.69](/rulebook#11.69) |
-| `args` | `Schema<Args>` | The gate on a keyed value's args. | [9.4](/rulebook#9.4), [11.28](/rulebook#11.28), [11.30](/rulebook#11.30), [11.40](/rulebook#11.40), [11.41](/rulebook#11.41), [11.56](/rulebook#11.56), [11.60](/rulebook#11.60), [11.68](/rulebook#11.68) |
+| `args` | `Schema<Args>` | The gate on a keyed value's args. | [9.4](/rulebook#9.4), [11.28](/rulebook#11.28), [11.30](/rulebook#11.30), [11.40](/rulebook#11.40), [11.41](/rulebook#11.41), [11.56](/rulebook#11.56), [11.60](/rulebook#11.60), [11.68](/rulebook#11.68), [11.72](/rulebook#11.72) |
 | `global` | `boolean` | Opts out of the default scope into one cache shared by every caller in the process. | [11.34](/rulebook#11.34), [11.35](/rulebook#11.35), [11.36](/rulebook#11.36), [11.37](/rulebook#11.37), [11.38](/rulebook#11.38), [11.39](/rulebook#11.39), [11.53](/rulebook#11.53), [11.67](/rulebook#11.67) |
 | `tags` | `string[] \| ((args: Args) => string[])` | What a `Selection` matches on. | [11.43](/rulebook#11.43), [11.44](/rulebook#11.44), [18.4](/rulebook#18.4), [18.15](/rulebook#18.15) |
 | `throttle` | `number` | A ceiling on how often the value changes. | [5.8](/rulebook#5.8), [5.9](/rulebook#5.9), [5.11](/rulebook#5.11), [5.12](/rulebook#5.12), [5.14](/rulebook#5.14), [5.15](/rulebook#5.15), [5.17](/rulebook#5.17), [5.18](/rulebook#5.18), [5.19](/rulebook#5.19), [5.20](/rulebook#5.20), [5.21](/rulebook#5.21), [5.23](/rulebook#5.23), [5.24](/rulebook#5.24) |
@@ -8628,18 +8634,18 @@ Generated surfaces: what is written in place rather than imported.
 | `{expr}` | Reactive text, escaped. | [32.1](/rulebook#32.1), [32.23](/rulebook#32.23) |
 | formatting whitespace | What a run of whitespace renders as. | [33.17](/rulebook#33.17), [33.18](/rulebook#33.18) |
 | `{raw(...)}` | Raw HTML. | [32.2](/rulebook#32.2), [32.25](/rulebook#32.25), [32.26](/rulebook#32.26), [32.30](/rulebook#32.30), [32.31](/rulebook#32.31), [32.70](/rulebook#32.70) |
-| `name={expr}` | A reactive attribute or property. | [32.3](/rulebook#32.3), [32.20](/rulebook#32.20), [32.23](/rulebook#32.23), [32.37](/rulebook#32.37) |
+| `name={expr}` | A reactive attribute or property. | [32.3](/rulebook#32.3), [32.20](/rulebook#32.20), [32.23](/rulebook#32.23), [32.37](/rulebook#32.37), [32.70](/rulebook#32.70), [32.71](/rulebook#32.71) |
 | `on<event>={fn}` | A native listener on an element, and an ordinary prop on a component. | [32.4](/rulebook#32.4) |
-| `name="…{expr}…"` | An interpolated quoted value. | [32.3](/rulebook#32.3) |
-| `bind:value` | Two-way bind on an element. | [5.16](/rulebook#5.16), [32.5](/rulebook#32.5), [32.58](/rulebook#32.58), [32.59](/rulebook#32.59), [32.60](/rulebook#32.60), [32.61](/rulebook#32.61), [32.62](/rulebook#32.62) |
+| `name="…{expr}…"` | An interpolated quoted value. | [32.3](/rulebook#32.3), [32.71](/rulebook#32.71) |
+| `bind:value` | Two-way bind on an element. | [5.16](/rulebook#5.16), [32.5](/rulebook#32.5), [32.58](/rulebook#32.58), [32.59](/rulebook#32.59), [32.60](/rulebook#32.60), [32.61](/rulebook#32.61), [32.62](/rulebook#32.62), [32.72](/rulebook#32.72) |
 | `bind:prop={state}` | Hands a component prop the caller's `Reactive`, or a `{get, set}` pair, to write through. | [32.6](/rulebook#32.6), [33.6](/rulebook#33.6), [33.8](/rulebook#33.8), [14.18](/rulebook#14.18) |
-| `bind:checked` | A boolean bind on an input. | [32.7](/rulebook#32.7) |
-| `bind:open` | The same, on a `<details>`. | [32.7](/rulebook#32.7) |
-| `bind:group` | Radio or checkbox membership. | [32.8](/rulebook#32.8) |
+| `bind:checked` | A boolean bind on an input. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72) |
+| `bind:open` | The same, on a `<details>`. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72) |
+| `bind:group` | Radio or checkbox membership. | [32.8](/rulebook#32.8), [32.72](/rulebook#32.72) |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | [32.5](/rulebook#32.5), [32.6](/rulebook#32.6) |
 | `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | [32.9](/rulebook#32.9), [32.38](/rulebook#32.38), [32.66](/rulebook#32.66), [32.68](/rulebook#32.68), [32.69](/rulebook#32.69) |
-| `class:name={cond}` | Toggles a class. | [32.10](/rulebook#32.10) |
-| `style:prop={value}` | Sets one style property. | [32.10](/rulebook#32.10), [32.19](/rulebook#32.19) |
+| `class:name={cond}` | Toggles a class. | [32.10](/rulebook#32.10), [32.71](/rulebook#32.71) |
+| `style:prop={value}` | Sets one style property. | [32.10](/rulebook#32.10), [32.19](/rulebook#32.19), [32.71](/rulebook#32.71) |
 | `{...expr}` | Spreads props or attributes. | [32.11](/rulebook#32.11), [32.37](/rulebook#32.37), [33.12](/rulebook#33.12), [33.13](/rulebook#33.13) |
 | static template text | What an author writes outside a slot, in body text and in an attribute value. | [32.27](/rulebook#32.27), [32.28](/rulebook#32.28) |
 
@@ -8656,10 +8662,10 @@ Generated surfaces: what is written in place rather than imported.
 | Spelling | Meaning | Rules |
 | --- | --- | --- |
 | `{#component Name(pattern)}` | An inline component. | [32.39](/rulebook#32.39), [32.40](/rulebook#32.40), [32.41](/rulebook#32.41), [32.42](/rulebook#32.42), [32.43](/rulebook#32.43), [32.44](/rulebook#32.44), [32.45](/rulebook#32.45), [32.46](/rulebook#32.46), [32.47](/rulebook#32.47), [32.48](/rulebook#32.48), [32.49](/rulebook#32.49), [32.50](/rulebook#32.50), [32.51](/rulebook#32.51), [32.52](/rulebook#32.52), [32.53](/rulebook#32.53), [32.54](/rulebook#32.54), [32.55](/rulebook#32.55), [32.63](/rulebook#32.63), [32.64](/rulebook#32.64) |
-| `<Name/>` | A component invocation. | [32.17](/rulebook#32.17), [32.34](/rulebook#32.34), [32.35](/rulebook#32.35), [32.36](/rulebook#32.36), [33.19](/rulebook#33.19), [33.21](/rulebook#33.21), [41.24](/rulebook#41.24), [41.28](/rulebook#41.28) |
+| `<Name/>` | A component invocation. | [32.17](/rulebook#32.17), [32.34](/rulebook#32.34), [32.35](/rulebook#32.35), [32.36](/rulebook#32.36), [32.70](/rulebook#32.70), [33.19](/rulebook#33.19), [33.21](/rulebook#33.21), [41.24](/rulebook#41.24), [41.28](/rulebook#41.28) |
 | `<slot/>` | The position children render into. | [32.18](/rulebook#32.18) |
 | `<slot>fallback</slot>` | Renders children, or a fallback. | [32.18](/rulebook#32.18) |
-| `<Tag>…</Tag>` | Children passed to a component's slot. | [32.18](/rulebook#32.18) |
+| `<Tag>…</Tag>` | Children passed to a component's slot. | [32.18](/rulebook#32.18), [32.70](/rulebook#32.70) |
 
 ## Script / style blocks
 
@@ -8837,7 +8843,7 @@ Configuration: what is written in place rather than imported.
 | `APP_NAME` | `string` | The app's name, and `log`'s default namespace. | [27.3](/rulebook#27.3), [28.4](/rulebook#28.4) |
 | `APP_VERSION` | `string` | The version beside that name. | [27.3](/rulebook#27.3) |
 | `APP_DATA_DIR` | `string` | The platform's per-user data directory. | [27.3](/rulebook#27.3), [36.4](/rulebook#36.4) |
-| `ABIDE_PRINCIPAL_SECRET` | `string \| null` | What seals the principal cookie. | [26.11](/rulebook#26.11), [36.5](/rulebook#36.5) |
+| `ABIDE_PRINCIPAL_SECRET` | `string \| null` | What seals the principal cookie. | [26.11](/rulebook#26.11), [36.5](/rulebook#36.5), [38.120](/rulebook#38.120) |
 | `ABIDE_PRINCIPAL_TTL` | `number` | The principal cookie's life, in ms. | [26.15](/rulebook#26.15), [26.16](/rulebook#26.16) |
 | `ABIDE_APP_TOKEN` | `string \| null` | The bearer the remote CLI sends. | [36.6](/rulebook#36.6) |
 | `ABIDE_APP_URL` | `string \| null` | Names an app somewhere else, for the remote CLI. | [36.6](/rulebook#36.6) |
@@ -9177,7 +9183,7 @@ Configuration: what is written in place rather than imported.
 | --- | --- | --- | --- |
 | `App` | `interface App` | What a host, a test or a script holds the app as. | [42.12](/rulebook#42.12), [42.13](/rulebook#42.13) |
 | `App.fetch` | `(request: Request) => Promise<Response>` | The whole request path, entered in process. | [42.5](/rulebook#42.5), [42.6](/rulebook#42.6) |
-| `App.run` | `<Result>(fn: () => Result \| Promise<Result>, options?: { request?: Request }) => Promise<Result>` | One scope around a function, and nothing else. | [42.7](/rulebook#42.7), [42.8](/rulebook#42.8), [11.38](/rulebook#11.38) |
+| `App.run` | `<Result>(fn: () => Result \| Promise<Result>, options?: { request?: Request; principal?: Record<string, unknown> }) => Promise<Result>` | One scope around a function, and nothing else. | [42.7](/rulebook#42.7), [42.8](/rulebook#42.8), [42.19](/rulebook#42.19), [11.38](/rulebook#11.38) |
 | `App.listen` | `(options?: { port?: number; hostname?: string; unix?: string }) => Promise<void>` | The socket, bound. | [42.9](/rulebook#42.9), [16.23](/rulebook#16.23), [16.56](/rulebook#16.56), [18.28](/rulebook#18.28), [18.29](/rulebook#18.29), [18.30](/rulebook#18.30) |
 | `App.stop` | `() => Promise<void>` | The drain and the teardown. | [42.10](/rulebook#42.10), [42.11](/rulebook#42.11), [42.15](/rulebook#42.15), [42.17](/rulebook#42.17), [37.4](/rulebook#37.4) |
 | `App[Symbol.asyncDispose]` | `() => Promise<void>` | `App.stop`, under the name `await using` calls. | [42.14](/rulebook#42.14) |

package/package.json

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

package/src/compiler/Lowering.ts

@@ -222,6 +222,11 @@ export class Lowering {
         }
     }
 
+    /** 32.67 — whether a position reads any row's item. */
+    readsAnItem(holder: object): boolean {
+        return this.holdsRead(holder, (read) => read.item !== -1)
+    }
+
     /** 32.67 — whether a position reads `block`'s item. */
     readsItem(holder: object, block: object): boolean {
         const item = this.itemOf(block)

package/src/compiler/appLayout.ts

@@ -1,6 +1,12 @@
 import { relative as relativeTo } from 'node:path' // bun exposes no path helpers of its own
 import { appFiles } from '#server/appTree.ts'
 import { type Placement, placement, routeOf } from '#server/placement.ts'
+import {
+    HEALTH_ADDRESS,
+    MCP_ADDRESS,
+    OPENAPI_ADDRESS,
+    PRINCIPAL_ADDRESS,
+} from '#shared/ADDRESSES.ts'
 import { LAUNCHER_PAGE } from '#shared/LAUNCHER_FILES.ts'
 import {
     coversRoute,
@@ -76,7 +82,7 @@ export type AppLayout = {
     errors: AppRoute[]
     /** Every public file's source path to its address. 36.11. */
     published: Map<string, string>
-    /** 30.26 — every address a link may name: a page's, and a public file's. */
+    /** 30.26 — every address a link may name: a page's, a public file's, and 21.4's four. */
     addresses: string[]
     /** What the tree refuses, each at its file; a build stops naming every one. */
     refused: Diagnosis[]
@@ -150,6 +156,7 @@ export async function appLayout(root: string): Promise<AppLayout> {
     const addresses = new Set<string>()
     for (const route of routes) addresses.add(route.pattern)
     for (const address of published.values()) addresses.add(address)
+    for (const address of FETCHED_ADDRESSES) addresses.add(address)
     return {
         root,
         sources,
@@ -165,6 +172,14 @@ export async function appLayout(root: string): Promise<AppLayout> {
     }
 }
 
+// 30.26, 21.4 — the framework's own addresses an app fetches, which every app answers at.
+const FETCHED_ADDRESSES = [
+    OPENAPI_ADDRESS,
+    MCP_ADDRESS,
+    HEALTH_ADDRESS,
+    PRINCIPAL_ADDRESS,
+]
+
 /** The file at each of `paths`, read. The reads overlap. */
 function textsAt(
     paths: readonly string[],