@abide/abide 0.116.3 → 0.116.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @abide/abide
 
+## 0.116.4
+
+### Patch Changes
+
+- f4acbfd: a handler whose args schema is derived from its type annotation (no `args` gate) now refuses bad args in process as it does over the wire — a direct call, a call from another handler or `app.run`, and every call under `mount` answer 422 `ValidationError` with the same `Issues` before the body runs, where before the body ran with the bad value
+- be88738: a reader that probed a handler before its first call wakes when the call starts — on a server and under `mount`, `disabled={save.busy()}` read before any call stayed enabled for the whole write, because the unreached answer (0.116.3) subscribed the reader to nothing. It now subscribes the reader to the first call in its scope, and still builds nothing and runs no handler (RULEBOOK 3.3, 13.19)
+
 ## 0.116.3
 
 ### Patch Changes

package/docs/RULEBOOK.md

@@ -754,7 +754,8 @@ mutation's `declare` built while its write is in flight.
 where every value it sweeps is.
 
 13.19 `busy`, `ready`, `synced`, `refresh` and `invalidate` over an `Rpc` no call has reached in the
-current scope MUST answer as over a `Selection` with no entries.
+current scope MUST answer as over a `Selection` with no entries, and reading `busy`, `ready` or
+`synced` there MUST subscribe the reader to the first call that reaches it in that scope.
 
 # 14. Tracking
 

package/package.json

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

package/src/compiler/compileApp.ts

@@ -11,6 +11,7 @@ import { COMPONENT_QUERY } from '#server/MODULE_QUERIES.ts'
 import { ROUTES_TABLE, SERVER_TABLE } from '#server/TABLES.ts'
 import { VIRTUAL_DIRECTORY } from '#server/VIRTUAL_DIRECTORY.ts'
 import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
 import { ROUTING_SPECIFIER, WIRE_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import {
     type AppLayout,
@@ -317,6 +318,7 @@ async function emitApp(
     refuseSharedRoutes(routes, mounts, refusals)
     refuseAddressCollision(routes, mounts, layout.published, refusals)
     const standIns = standInsOf(mounts)
+    const derived = derivedOf(mounts)
     // 37.1 — every module a server block or a handler file runs in, for the boot to import before
     // `onStart`.
     const servers: string[] = []
@@ -329,6 +331,7 @@ async function emitApp(
                 entry,
                 standIns.get(entry.relative),
                 entry.text,
+                derived.get(entry.relative),
             )
         } catch (thrown) {
             refusals.at(entry.path, thrown)
@@ -368,6 +371,7 @@ async function emitApp(
             handlers[mount.source] = {
                 scope: mount.scope,
                 client: standIns.get(mount.source) ?? '',
+                args: mount.args,
             }
     if (routes.length > 0) {
         tables[ROUTES_TABLE] = clientTable(routes, transitions)
@@ -624,6 +628,21 @@ function standInsOf(mounts: Mount[]): Map<string, string> {
     return standIns
 }
 
+/**
+ * 19.9 — the schema each private handler's annotation derives, by its binding, by source: what its
+ * server module holds it to (15.8). A handler file's is its face's (`HandlerFace`).
+ */
+function derivedOf(mounts: Mount[]): Map<string, Record<string, JsonValue>> {
+    const derived = new Map<string, Record<string, JsonValue>>()
+    for (const mount of mounts) {
+        if (!mount.private || mount.args === undefined) continue
+        const held = derived.get(mount.source) ?? {}
+        held[mount.name] = mount.args
+        derived.set(mount.source, held)
+    }
+    return derived
+}
+
 /**
  * One handler's wrapper, bound as `binding` writes it.
  *

package/src/compiler/emitComponent.ts

@@ -1,3 +1,4 @@
+import type { JsonValue } from '#shared/JsonValue.ts'
 import { SERVER_SPECIFIER } from '#shared/SPECIFIERS.ts'
 import { type CheckerAnswer, UNCHECKED } from './CheckerAnswer.ts'
 import { Cursor, placeTemplate } from './Cursor.ts'
@@ -50,6 +51,8 @@ export function emitComponent(
     route = '/',
     /** 38.97 — where given, every chunk the module is written around (`sourceMapOf`). */
     chunks?: LoweredChunk[],
+    /** 19.9 — the schema each private handler's annotation derives, by its binding. */
+    derived: Readonly<Record<string, JsonValue>> = {},
 ): string {
     // Only what the page actually uses. An emitted module carrying an import nothing calls is a
     // name the app's own tooling reports as unused, in a file nobody wrote.
@@ -91,7 +94,7 @@ export function emitComponent(
             : `${lowering.use('fileRoute')}(${JSON.stringify(route)})
 ${serverSetup.body}
 ${lowering.use('fileRoute')}(undefined)
-${privateExports(file.servers.join('\n'))}`
+${heldToAnnotations(lowering, derived)}${privateExports(file.servers.join('\n'))}`
     const setup = splitImports(lowering.scripts())
     const componentBody = setup.body
 
@@ -159,6 +162,21 @@ ${level}${closed}
 `
 }
 
+/**
+ * 15.8, 19.9 — each private handler held to the schema its annotation derives, once its server block
+ * has built it: the module is what the server mounts and what a component under `mount` calls
+ * (38.121), so a call is held to it whoever makes it.
+ */
+function heldToAnnotations(
+    lowering: Lowering,
+    derived: Readonly<Record<string, JsonValue>>,
+): string {
+    let out = ''
+    for (const name in derived)
+        out += `${lowering.use('derivedArgs')}(${name}, ${JSON.stringify(derived[name])})\n`
+    return out
+}
+
 /**
  * An emitted module's imports: each framework name `lowering` used, from the specifier it ships
  * under, and the author's own from both script blocks, already pointed where they landed

package/src/compiler/emitSource.ts

@@ -1,4 +1,5 @@
 import { STYLE_QUERY } from '#server/MODULE_QUERIES.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
 import type { Placement } from '#server/placement.ts'
 import type { CheckerAnswer } from './CheckerAnswer.ts'
 import { emitClient } from './emitClient.ts'
@@ -35,6 +36,8 @@ export function emitSource(
     standIns = '',
     /** 38.97 — the `.abide`'s text, where the build wants each module's source map. */
     text?: string,
+    /** 19.9 — the schema each private handler it declares derives off its annotation, by name. */
+    derived?: Readonly<Record<string, JsonValue>>,
 ): {
     server: string
     client: string
@@ -109,6 +112,7 @@ export function emitSource(
         kind !== 'component',
         source.scope,
         serverChunks,
+        derived,
     )
     const name = relative.slice(relative.lastIndexOf('/') + 1)
     const browser = withStandIns(

package/src/server/abideModules.ts

@@ -120,7 +120,8 @@ export function serveCompilation(root: string, compilation: Compilation): void {
     const real = realOrAsGiven(root)
     const handlerFiles = addCompilation(real, compilation, RUNTIME)
     installSourceMaps(serverMapsOf(compilation, real), real)
-    if (handlerFiles.length !== 0) Bun.plugin(handlerFilesPlugin(handlerFiles))
+    if (handlerFiles.length !== 0)
+        Bun.plugin(handlerFilesPlugin(handlerFiles, RUNTIME.handlers))
     if (registered) return
     registered = true
     Bun.plugin(modulesPlugin(RUNTIME))
@@ -132,7 +133,13 @@ export function serveCompilation(root: string, compilation: Compilation): void {
 // plugin per compilation because the filter is fixed at registration, and the runtime's `onLoad`
 // cannot fall through, so the filter names the handler files and nothing else. The face it names
 // is resolved by `modulesPlugin`, registered once.
-function handlerFilesPlugin(paths: string[]): Bun.BunPlugin {
+// 15.8, 19.9 — AND HOLDS ITS HANDLER TO THE SCHEMA ITS ANNOTATION DERIVES, once the face has built it:
+// this module is what every import of the file is answered with — the server's mount, a test's own
+// import, a component's under `mount` — so a call is held to it whoever makes it.
+function handlerFilesPlugin(
+    paths: string[],
+    faces: ReadonlyMap<string, HandlerFace>,
+): Bun.BunPlugin {
     return {
         name: 'abide-handler-files',
         setup(build) {
@@ -142,10 +149,18 @@ function handlerFilesPlugin(paths: string[]): Bun.BunPlugin {
                         `^(?:${paths.map(RegExp.escape).join('|')})$`,
                     ),
                 },
-                (args) => ({
-                    contents: `export { default } from ${JSON.stringify(`${args.path}${HANDLER_SUFFIX}`)}\n`,
-                    loader: 'js',
-                }),
+                (args) => {
+                    const face = JSON.stringify(`${args.path}${HANDLER_SUFFIX}`)
+                    const schema = faces.get(args.path)?.args
+                    return {
+                        contents:
+                            `export { default } from ${face}\n` +
+                            (schema === undefined
+                                ? ''
+                                : `import __handler from ${face}\nimport { derivedArgs as __derivedArgs } from '${SERVER_SPECIFIER}'\n__derivedArgs(__handler, ${JSON.stringify(schema)})\n`),
+                        loader: 'js',
+                    }
+                },
             )
         },
     }

package/src/server/answerRpc.ts

@@ -16,7 +16,7 @@ import type { Gated } from '#shared/reactive/argsContract.ts'
 import { deadlineOf, heldGenerationOf } from '#shared/reactive/index.ts'
 import type { Defaults } from '#shared/reactive/parameterDefaults.ts'
 import { notFound, refuse } from '#shared/refuse.ts'
-import type { Method, Rpc } from '#shared/rpc.ts'
+import type { HeldToAnnotation, Method, Rpc } from '#shared/rpc.ts'
 import { argsInURL } from '#shared/rpcRequest.ts'
 import { VERSION_HEADER } from '#shared/VERSION_HEADER.ts'
 import { versionInEtag } from '#shared/versionInEtag.ts'
@@ -118,20 +118,13 @@ export type Mounted = Mount & {
      * subscription to it both pass through (37.2, 18.26).
      */
     rungs: AppRung[]
-    handler: Rpc<unknown, unknown> & Gated<unknown>
+    handler: Rpc<unknown, unknown> & Gated<unknown> & HeldToAnnotation
     /**
      * The args' JSON Schema, probed once at mount.
      *
      * 19.7, 20.11 — a third-party schema converts itself on every probe.
      */
     argsDocument: Document | undefined
-    /**
-     * What the wire holds args to where the handler declares no `args` gate of its own.
-     *
-     * 19.9 — the annotation's schema. An in-process call already holds the type, so the handler
-     * never runs it.
-     */
-    wireArgs: JsonValue | undefined
 }
 
 /**
@@ -172,7 +165,6 @@ export function mountedOwn(
             result: undefined,
             handler: handler as Mounted['handler'],
             argsDocument: undefined,
-            wireArgs: undefined,
         },
     ]
 }
@@ -198,7 +190,7 @@ export async function mountHandlers(
     for (let at = 0; at < table.length; at += 1) {
         const mount = table[at] as Mount
         const exported = (modules[at] as Record<string, unknown>)[mount.export]
-        const handler = exported as Rpc<unknown, unknown> & Gated<unknown>
+        const handler = exported as Mounted['handler']
         const declared = argsDocumentOf(handler)
         // 16.9, 16.10 — the address `rpc.url` and `rpc.raw` build on, under the mount — and what a
         // page's render turns a call it made into the browser's request by (41.20).
@@ -210,7 +202,6 @@ export async function mountHandlers(
             rungs: rungsOver(mount.scope),
             handler,
             argsDocument: declared ?? (mount.args as Document | undefined),
-            wireArgs: declared === undefined ? mount.args : undefined,
         })
     }
     return { handlers }

package/src/server/argsFor.ts

@@ -2,9 +2,9 @@
 // off the wire: over http (16.2) and a `GET` followed over the socket mux (18.3). Each lane reads the
 // args off its own transport and answers a refusal in its own form.
 
+import { DERIVED_ARGS } from '#shared/DERIVED_ARGS.ts'
 import { normalized } from '#shared/reactive/argsContract.ts'
 import { validationError } from '#shared/refuse.ts'
-import { validateJson } from '#shared/validateJson.ts'
 import type { Mounted } from './answerRpc.ts'
 import { coerceArgs } from './coerceArgs.ts'
 
@@ -16,11 +16,10 @@ import { coerceArgs } from './coerceArgs.ts'
  * 19.7 — the text as the types the handler's `args` declares. 11.27 — then the defaults, ahead of
  * every key taken after it: the seed a render filed and the `global` entry standing were both filed
  * under them (11.29). 19.9 — THE WIRE HELD TO THE ANNOTATION, where no `args` schema is declared to
- * hold it. Args that did not come are held as an empty record: a schema is only derived where the
- * handler's args are a required record, so a required member missing is refused, not read off nothing.
+ * hold it — the check the handler carries (`derivedArgs`), which its in-process call makes too (15.8).
  */
 export function argsFor(
-    found: Pick<Mounted, 'handler' | 'argsDocument' | 'wireArgs'>,
+    found: Pick<Mounted, 'handler' | 'argsDocument'>,
     sent: unknown,
     query: string | undefined,
 ): unknown {
@@ -33,9 +32,7 @@ export function argsFor(
                   query,
               )
     const args = normalized(found.handler, coerced)
-    if (found.wireArgs !== undefined) {
-        const issues = validateJson(found.wireArgs, args ?? {})
-        if (issues !== null) throw validationError(issues)
-    }
+    const issues = found.handler[DERIVED_ARGS]?.(args) ?? null
+    if (issues !== null) throw validationError(issues)
     return args
 }

package/src/server/derivedArgs.ts

@@ -0,0 +1,25 @@
+import { DERIVED_ARGS } from '#shared/DERIVED_ARGS.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
+import type { Gated } from '#shared/reactive/argsContract.ts'
+import type { HeldToAnnotation } from '#shared/rpc.ts'
+import { validateJson } from '#shared/validateJson.ts'
+import { argsDocumentOf } from './coerceArgs.ts'
+
+/**
+ * Holds `handler`'s args to `schema`, the one the build derived off its annotation, for every call
+ * of it from now on: in process and over the wire (15.8, 19.9).
+ *
+ * What the module a handler is loaded through calls once its handler is built — a handler file's
+ * face and a `<script server>`'s module — so the schema is there wherever the handler can be
+ * called, whether or not an app mounted it. Not where its `args` gate publishes a document of its
+ * own, which holds the args itself (19.7). Args that did not come are held as an empty record: a
+ * schema is only derived where the handler's args are a required record, so a required member
+ * missing is refused, not read off nothing.
+ */
+export function derivedArgs(
+    handler: HeldToAnnotation & Gated<unknown>,
+    schema: JsonValue,
+): void {
+    if (argsDocumentOf(handler) !== undefined) return
+    handler[DERIVED_ARGS] = (args) => validateJson(schema, args ?? {})
+}

package/src/server/faceOf.ts

@@ -3,6 +3,7 @@
 // adapter that hands bun's hooks to it, because bun decides which hook asks (an `onResolve` for a
 // specifier, an `onLoad` for a path), and this decides what the answer is.
 
+import type { JsonValue } from '#shared/JsonValue.ts'
 import { HANDLER_SUFFIX, SERVER_QUERY } from './MODULE_QUERIES.ts'
 
 // A VIRTUAL FACE'S PATH: its file's, with a suffix that is not a query. Both registries key a module
@@ -45,8 +46,15 @@ export type Asked =
     | 'abide'
     | 'handler'
 
-/** One handler file, as `Compilation.handlers` holds it. */
-export type HandlerFace = { scope: string; client: string }
+/**
+ * One handler file, as `Compilation.handlers` holds it — and 19.9's schema its default's annotation
+ * derives, which the module at the file's path holds it to (`derivedArgs`).
+ */
+export type HandlerFace = {
+    scope: string
+    client: string
+    args: JsonValue | undefined
+}
 
 /**
  * The face an import of `file` is answered with, asked `asked` from `importer` in `lane` — or

package/src/server/index.ts

@@ -52,6 +52,9 @@ export { type App, createApp } from './createApp.ts'
 // 41.28's run-time half: an emitted component reads it on either side of its setup, and one whose
 // setup made a call answers as a page does. Not an app's name.
 export { callsInRender } from './deferredBuilds.ts'
+// 19.9's run-time half: what the module a handler is loaded through calls to hold it to the schema
+// its annotation derives (15.8). Not an app's name.
+export { derivedArgs } from './derivedArgs.ts'
 // 37.1's run-time half: what a compiled server module calls around its `<script server>`, so the
 // hooks it makes are filed at its route.
 export {

package/src/shared/DERIVED_ARGS.ts

@@ -0,0 +1,6 @@
+/**
+ * The member of an `Rpc` holding its args to the schema its annotation derives (19.9): stamped by the
+ * module its handler is loaded through, on the server alone, and read by every call of it — in
+ * process and over the wire alike (15.8).
+ */
+export const DERIVED_ARGS: unique symbol = Symbol.for('abide.derivedArgs')

package/src/shared/reactive/scoped.ts

@@ -15,9 +15,10 @@
 import { contractOf, type Gated } from './argsContract.ts'
 import { CELL } from './CELL.ts'
 import { KEYED_BRAND } from './KEYED_BRAND.ts'
-import { brandedPrototype, MEMBER_KEYS } from './Reactive.ts'
+import { brandedPrototype, MEMBER_KEYS, signalMoved } from './Reactive.ts'
 import { SELECTION_MEMBERS } from './SELECTION_MEMBERS.ts'
 import { currentScope, runInScope, SCOPING } from './scoping.ts'
+import { newTracked, TRACKING, type Tracked, trackProbe } from './tracking.ts'
 
 const UNBUILT: unique symbol = Symbol('abide.unbuilt')
 
@@ -36,11 +37,18 @@ class Filed {
     home: unknown
     make: () => unknown
     global: boolean
+    /**
+     * 3.3, 13.19 — what a probe asked before the value was built here subscribes to, moved by the
+     * build: the home's. A scope files its own in `instances` under this one as its key, and drops
+     * it with the scope.
+     */
+    unbuilt: Tracked
 
     constructor(make: () => unknown, lazy: boolean, global: boolean) {
         this.make = make
         this.home = lazy ? UNBUILT : make()
         this.global = global
+        this.unbuilt = newTracked()
     }
 }
 
@@ -56,14 +64,21 @@ type Forwarder = { [FILED]: Filed }
 function instanceOf(filed: Filed): Record<PropertyKey, unknown> {
     const scope = filed.global ? undefined : currentScope()
     if (scope === undefined) {
-        if (filed.home === UNBUILT)
+        if (filed.home === UNBUILT) {
             filed.home = runInScope(undefined, () => filed.make(), undefined)
+            signalMoved(filed.unbuilt)
+        }
         return filed.home as Record<PropertyKey, unknown>
     }
     let instance = scope.instances.get(filed)
     if (instance === undefined) {
         instance = filed.make()
         scope.instances.set(filed, instance)
+        const asked = scope.instances.get(filed.unbuilt) as Tracked | undefined
+        if (asked !== undefined) {
+            scope.instances.delete(filed.unbuilt)
+            signalMoved(asked)
+        }
     }
     return instance as Record<PropertyKey, unknown>
 }
@@ -152,14 +167,33 @@ export function scoped(
 /**
  * Whether the value `value` forwards to is built for the scope that is current — always, for a
  * value that is no forwarder. Asking builds nothing, where `instanceOf` builds what it finds unbuilt.
+ *
+ * 3.3 — AND WHERE IT IS NOT, ASKING SUBSCRIBES THE READER TO ITS BUILD: a guard that probed before
+ * the first call has no cell to hear the call start from, so `disabled={save.busy()}` stayed
+ * enabled through the whole write. One signal per value per scope, never one per entry (13.3).
  */
 export function builtHere(value: unknown): boolean {
     const filed = (value as Partial<Forwarder> | null)?.[FILED]
     if (filed === undefined) return true
     const scope = filed.global ? undefined : currentScope()
-    return scope === undefined
-        ? filed.home !== UNBUILT
-        : scope.instances.has(filed)
+    if (
+        scope === undefined
+            ? filed.home !== UNBUILT
+            : scope.instances.has(filed)
+    )
+        return true
+    const reader = TRACKING.reader
+    if (reader === null) return false
+    let asked = filed.unbuilt
+    if (scope !== undefined) {
+        asked = scope.instances.get(filed.unbuilt) as Tracked
+        if (asked === undefined) {
+            asked = newTracked()
+            scope.instances.set(filed.unbuilt, asked)
+        }
+    }
+    trackProbe(asked, reader)
+    return false
 }
 
 /**

package/src/shared/rpc.ts

@@ -13,6 +13,7 @@
 // the call hands back a value whose body runs the onion once per args, per request, over the
 // handler's own.
 
+import { DERIVED_ARGS } from './DERIVED_ARGS.ts'
 import { type Failed, isFailedNamed } from './Failed.ts'
 import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
 import { HandlerRoute } from './HandlerRoute.ts'
@@ -52,7 +53,7 @@ import { MUTATION } from './reactive/MUTATION.ts'
 import { dropAnswered } from './reactive/Reactive.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
 import { builtHere, isForwarder } from './reactive/scoped.ts'
-import { checkArgs } from './refuse.ts'
+import { checkArgs, validationError } from './refuse.ts'
 import { rpcRequest } from './rpcRequest.ts'
 import type { Schema } from './Schema.ts'
 
@@ -162,6 +163,16 @@ type Derived<Member, Whole = Member> = Member extends
           : never
       : never
 
+/**
+ * 19.9 — the issues an `Rpc`'s args leave against the schema its annotation derives, `null` where
+ * they hold: `undefined` until the module its handler is loaded through stamps it (`derivedArgs`),
+ * and so in a browser always. A function rather than the schema, so this seam never carries the
+ * validator (19.13).
+ */
+export type HeldToAnnotation = {
+    [DERIVED_ARGS]: ((args: unknown) => Issues<unknown> | null) | undefined
+}
+
 /** Which generated surfaces carry a handler (20.1). */
 export type Clients = {
     ui?: boolean
@@ -440,6 +451,11 @@ export function declare(method: Method): Declare {
         }
         const call = (given?: unknown, options?: CallOptions): unknown => {
             const args = normalized(contract, given)
+            // 15.8, 19.9 — AND HELD TO ITS ANNOTATION, where the build derived a schema off it: a
+            // type an in-process caller wrote holds nothing at run time (`as never`, a value off
+            // JSON), so the call is refused as the wire refuses it rather than handed to the body.
+            const issues = rpc[DERIVED_ARGS]?.(args) ?? null
+            if (issues !== null) return reactive(() => validationError(issues))
             const route =
                 rpc.address === undefined ? undefined : routeAt(rpc.address)
             if (route?.segments !== undefined) {
@@ -469,7 +485,7 @@ export function declare(method: Method): Declare {
         // 13.19 — AND NOT YET BUILT, NONE OF THEM BUILDS IT: building an unkeyed value starts its body
         // (1.7), so `save.busy()` over a server's never-called `POST(async () => …)` ran the write and
         // reported it in flight. Until a call reaches it the handler has no entry, and answers as one
-        // with no entries does.
+        // with no entries does — the asking reader subscribed to the call that builds it (`builtHere`).
         const built = value as Record<
             (typeof SELECTION_MEMBERS)[number],
             (pattern?: unknown) => unknown
@@ -487,6 +503,7 @@ export function declare(method: Method): Declare {
             maxBodySize: options?.maxBodySize,
             clients: options?.clients ?? {},
             guarded: rungs.length > 0,
+            [DERIVED_ARGS]: undefined as HeldToAnnotation[typeof DERIVED_ARGS],
             isError: isFailedNamed,
             url(args?: Record<string, unknown>): string {
                 return rpcRequest(method, routeAt(addressOf(rpc)), args).url