@jarenjs/app 0.34.0

package/docs/TASKS.md

@@ -0,0 +1,254 @@
+# Async tasks — the staleness-rejection convention
+
+Module: `@jarenjs/app`. This document is the async-task **convention**:
+how an app document performs asynchronous work — request identity,
+stale-response rejection, cancellation — plus the one shipped helper,
+[`createTaskEffect`](../src/tasks.js), that removes the host-side
+boilerplate.
+
+It is deliberately **pattern-first**: there is no format change and no
+new document member. The correctness mechanism is expressible in
+today's vocabulary, and that is a *feature* of actions-as-queries — a
+task's identity is ordinary state, its guard is an ordinary query, so
+snapshots, replay and the meta-schema all keep working with nothing
+added. First-class async action documents (a disposition that awaits an
+effect before transitioning) remain the roadmap item they already are
+([APP-FORMAT §11](APP-FORMAT.md)).
+
+> **The worked example below is executable.** The single `json` code
+> block in this document is a complete app document; the test suite
+> (`test/app/tasks.test.js`) extracts it *from this file*, compiles it,
+> and drives every scenario — happy path, out-of-order staleness, abort,
+> failure routing, polling — against it. These docs cannot drift from
+> the engine.
+
+## The two halves, stated precisely
+
+**Correctness lives in state; cancellation lives in the host.**
+
+- The **state half** is the guarantee: every task slot carries a
+  monotonically increasing `id`; the start action increments it; the
+  completion action rejects any payload whose `id` is not the current
+  one. Out-of-order responses are harmless *by construction*.
+- The **host half** — an `AbortController` per slot, packaged by
+  `createTaskEffect` — is an optimization: it stops wasting the wire on
+  a superseded request. It is **not** the guarantee: an aborted fetch
+  may already have resolved and its completion dispatch may already be
+  queued. **A host that only aborts is still wrong.** Keep the id
+  guard.
+
+## Half 1 — the state convention
+
+A task slot in state:
+
+```js
+"tasks": { "list": { "id": 0, "status": "idle", "error": null } }
+```
+
+**The start action** does two things in one transition: it patches the
+slot (increment `id`, set `status` to `"loading"`, clear `error`) and
+invokes the effect with the **new** id in its props.
+
+> ⚠ **The pre-transition-`$` gotcha.** An action's entire result —
+> including every effect's `with` — is computed by the query against
+> the ***pre*-transition** state `$`. The patch is applied before the
+> effects *run*, but their props were already evaluated. So the
+> effect's `with.id` MUST be written as the same increment expression
+> the patch uses — `{ "$add": ["$.tasks.list.id", 1] }` — and never as
+> a read of the patched slot. This is the one place the pattern can
+> silently rot: a `with.id` that reads the slot ships the *old* id, and
+> every completion is then rejected as stale.
+
+**The completion action** is dispatched by the host with
+`$payload = { "id", "result" }` on success or `{ "id", "error" }` on
+failure. Guard first: when `$payload.id` differs from the slot's
+current `id`, produce the **empty sequence** — a conditional with no
+else-branch, `{ "$if": [guard, then] }`, which is APP-FORMAT §3.2's
+no-op transition: nothing changes, nothing renders, no subscriber
+fires. Otherwise store the result (or the error) and flip `status`.
+The two payload shapes are told apart with
+`{ "$exists": "$payload.error" }` — an absent member is the empty
+sequence, so `$exists` is the exact "did the host send an error" test.
+
+**Polling** composes on top: a subscription whose `when` watches state
+dispatches the start action on an interval. Every poll increments the
+id, so overlapping responses fall out of the same guard — an old poll
+response can never overwrite newer state, with no new machinery.
+
+## Half 2 — the shipped helper
+
+```javascript
+import { createApp, createTaskEffect } from '@jarenjs/app';
+
+createApp(doc, {
+  effects: {
+    http: createTaskEffect((props, signal) =>
+      fetch(props.url, { signal }).then((r) => r.json())),
+  },
+  subs: {
+    every: (props, dispatch) => {
+      const id = setInterval(() => dispatch(props.action), props.ms);
+      return () => clearInterval(id);
+    },
+  },
+});
+```
+
+`createTaskEffect(run, options)` takes the host's async function
+`run(props, signal) => Promise<JSON>` and returns an ordinary effect
+handler. `run` is invoked through a **uniform promise boundary**: a
+synchronous throw and a non-promise return settle through exactly the
+same path as a rejection/resolution. `options.mode` picks the per-slot
+concurrency semantics — `"switch"` (default: a new start aborts the
+slot's in-flight predecessor), `"exhaust"` (duplicate starts are
+ignored — the double-click-safe commit mode), `"concat"` (starts queue
+and run strictly in order) or `"parallel"` (APP-FORMAT §9.2). The
+handler carries the host-side controls `cancel(slot)`, `cancelAll()`
+and `dispose()` — after `dispose()` (which `app.destroy()` calls
+automatically) no late settlement can dispatch. The effect-props
+convention (all JSON):
+
+| Prop | | Meaning |
+|---|---|---|
+| `id` | REQUIRED | The task identity, echoed back verbatim in the completion payload. |
+| `done` | REQUIRED | The action dispatched on settle. |
+| `fail` | OPTIONAL | The action for rejections. Absent: rejections dispatch `done` with `{ id, error }` instead of `{ id, result }` — one completion action guarding on `$payload.error` is the query-friendliest shape, so it is the default. |
+| `slot` | OPTIONAL | The concurrency key (a string), default `""`. What a new start does to the slot's in-flight task is the effect's `mode` (default `"switch"`: it aborts the predecessor). |
+| ... | | Anything else `run` needs (a URL, a query, ...). |
+
+Settlement semantics, exactly:
+
+| Outcome | Effect |
+|---|---|
+| start | The slot's in-flight controller (if any) is aborted; a fresh one is stored; `run(props, signal)` is called. |
+| resolve | `dispatch(done, { id, result })`. |
+| reject, `err.name === "AbortError"` | **Nothing.** A superseded task is dead by design; its successor's dispatch carries the story. |
+| reject, anything else | `dispatch(fail ?? done, { id, error })` — `error` is a **string**, never an Error object; JSON only crosses the boundary. |
+| settle | The task's controller is released; a `concat` slot starts its next queued task. |
+| after `dispose()` | **Nothing** — a late settlement can no longer dispatch. |
+| malformed `id`/`done`/`fail`/`slot` | A `TypeError` from the handler — a host programming error, reported by the loop as `JA2007`. |
+
+Tasks in different slots never touch each other. The helper holds no
+state beyond the per-slot records, uses no timers, and has zero
+dependencies (`AbortController` is platform).
+
+## The worked example
+
+A list task and a detail task in independent slots, with polling. Both
+completion actions guard on the slot id; the detail task routes
+failures to a dedicated `fail` action, the list task uses the default
+single-completion shape:
+
+```json
+{
+  "$app": "0.1",
+  "state": {
+    "tasks": {
+      "list":   { "id": 0, "status": "idle", "error": null },
+      "detail": { "id": 0, "status": "idle", "error": null }
+    },
+    "items": [],
+    "detail": null,
+    "polling": false
+  },
+  "view": [
+    { "match": "$", "body": ["main", {}, "$.tasks.list.status"] }
+  ],
+  "actions": {
+    "loadList": {
+      "patch": [
+        { "op": "replace", "path": "/tasks/list/id",
+          "value": { "$add": ["$.tasks.list.id", 1] } },
+        { "op": "replace", "path": "/tasks/list/status", "value": "loading" },
+        { "op": "replace", "path": "/tasks/list/error", "value": null }
+      ],
+      "effects": [
+        { "run": "http", "with": {
+          "id": { "$add": ["$.tasks.list.id", 1] },
+          "done": "listLoaded",
+          "slot": "list",
+          "url": "/api/items"
+        } }
+      ]
+    },
+    "listLoaded": {
+      "$if": [
+        { "$eq": ["$payload.id", "$.tasks.list.id"] },
+        { "$if": [
+          { "$exists": "$payload.error" },
+          { "patch": [
+            { "op": "replace", "path": "/tasks/list/status", "value": "error" },
+            { "op": "replace", "path": "/tasks/list/error", "value": "$payload.error" }
+          ] },
+          { "patch": [
+            { "op": "replace", "path": "/tasks/list/status", "value": "done" },
+            { "op": "replace", "path": "/items", "value": "$payload.result" }
+          ] }
+        ] }
+      ]
+    },
+    "openDetail": {
+      "patch": [
+        { "op": "replace", "path": "/tasks/detail/id",
+          "value": { "$add": ["$.tasks.detail.id", 1] } },
+        { "op": "replace", "path": "/tasks/detail/status", "value": "loading" },
+        { "op": "replace", "path": "/tasks/detail/error", "value": null }
+      ],
+      "effects": [
+        { "run": "http", "with": {
+          "id": { "$add": ["$.tasks.detail.id", 1] },
+          "done": "detailLoaded",
+          "fail": "detailFailed",
+          "slot": "detail",
+          "url": { "$concat": ["/api/items/", { "$string": "$payload" }] }
+        } }
+      ]
+    },
+    "detailLoaded": {
+      "$if": [
+        { "$eq": ["$payload.id", "$.tasks.detail.id"] },
+        { "patch": [
+          { "op": "replace", "path": "/tasks/detail/status", "value": "done" },
+          { "op": "replace", "path": "/detail", "value": "$payload.result" }
+        ] }
+      ]
+    },
+    "detailFailed": {
+      "$if": [
+        { "$eq": ["$payload.id", "$.tasks.detail.id"] },
+        { "patch": [
+          { "op": "replace", "path": "/tasks/detail/status", "value": "error" },
+          { "op": "replace", "path": "/tasks/detail/error", "value": "$payload.error" }
+        ] }
+      ]
+    },
+    "startPolling": { "patch": [{ "op": "replace", "path": "/polling", "value": true }] },
+    "stopPolling":  { "patch": [{ "op": "replace", "path": "/polling", "value": false }] }
+  },
+  "subs": [
+    { "run": "every", "when": "$.polling",
+      "with": { "ms": 5000, "action": "loadList" } }
+  ]
+}
+```
+
+Walk the staleness scenario through it: `loadList` twice in quick
+succession takes the slot id to `2` and the helper aborts request 1.
+Suppose request 1's response arrives anyway (it had already resolved
+when the abort landed). Its dispatch is `listLoaded` with
+`{ "id": 1, ... }`; the guard compares `1` against the slot's `2`,
+`$if` takes no branch, the action yields the empty sequence — no state
+change, no render, no subscriber. Only request 2's completion, carrying
+the current id, lands. The same holds when polling: every tick is a
+fresh id, so the guard serializes an arbitrary storm of overlapping
+responses down to "latest wins".
+
+## What the meta-schema needs
+
+Nothing — and that is the point. The convention is ordinary `state`,
+ordinary `actions`, ordinary `effects` invocations; the worked example
+above validates against the shipped
+[`jaren-app.schema.json`](../schemas/jaren-app.schema.json) unchanged.
+A pattern that needed a schema extension would be a format change; this
+one is proof the existing vocabulary already carries request identity
+and staleness rejection.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@jarenjs/app",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/types/",
+    "src/",
+    "docs/",
+    "schemas/"
+  ],
+  "description": "Applications as JSON documents: hyperapp's dispatch loop rebuilt on the Jaren suite — JSLT views, query-document actions, JSON Patch transitions",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "packages/app"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "app",
+    "framework",
+    "hyperapp",
+    "jslt",
+    "state"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/json": "^0.34.0",
+    "@jarenjs/view": "^0.34.0"
+  }
+}

package/schemas/jaren-app.draft-07.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-app/0.1/draft-07",
+  "title": "Jaren app document 0.1",
+  "description": "Structural grammar of a complete Jaren application document (see packages/app/docs/APP-FORMAT.md): initial state, a JSLT view stylesheet, named action documents and subscription entries. Composes the published Jaren query and JSLT grammars by reference — register those artifacts alongside this one. The view's OUTPUT vocabulary (vnodes) is published separately as the jaren-vnode schema in @jarenjs/view. This schema is structural validation only: the runtime remains authoritative for semantic rules it cannot express — the transition-object shape an action RETURNS ({state?, patch?, effects?}) is the action's runtime result, not its document form; unknown top-level members are ignored for forward compatibility (APP-FORMAT section 2).",
+  "type": "object",
+  "properties": {
+    "$app": {
+      "description": "The app format version; absent implies 0.1.",
+      "const": "0.1"
+    },
+    "state": {
+      "description": "The initial state: any JSON value, treated as immutable by every boundary."
+    },
+    "view": {
+      "description": "The view: a JSLT stylesheet document (bare rule array or envelope form) whose evaluation against the state must produce a single vnode.",
+      "allOf": [
+        {
+          "$ref": "https://jarenjs.dev/schemas/jaren-jslt/0.1/draft-07"
+        }
+      ]
+    },
+    "actions": {
+      "description": "Named action documents: Jaren JSON Query documents evaluated with $ bound to the state and the externals $event and $payload.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+      }
+    },
+    "subs": {
+      "description": "Subscription entries reconciled against the state after every transition.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "run": {
+            "description": "The registered subscription handler name.",
+            "type": "string",
+            "minLength": 1
+          },
+          "with": {
+            "description": "Handler props, passed verbatim (never evaluated). Mutually exclusive with \"withQuery\" and \"for\"."
+          },
+          "when": {
+            "description": "Liveness query, asserted by effective boolean value against the state; absent means always live.",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          },
+          "withQuery": {
+            "description": "Dynamic props: a query evaluated against the state per reconciliation; the subscription restarts when its resolved key changes. Under \"for\", \"$item\" is bound per instance. Mutually exclusive with \"with\".",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          },
+          "key": {
+            "description": "Explicit restart key: a query whose resolved value keys the subscription (by value) instead of the resolved props. Requires \"withQuery\" or \"for\"; \"$item\" is bound per instance under \"for\".",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          },
+          "for": {
+            "description": "Fan-out: a query whose result is the item set — one running instance per item key, reconciled per state change. \"with\" is not allowed beside it.",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1/draft-07"
+              }
+            ]
+          }
+        },
+        "required": [
+          "run"
+        ]
+      }
+    }
+  },
+  "required": [
+    "view"
+  ]
+}

package/schemas/jaren-app.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-app/0.1",
+  "title": "Jaren app document 0.1",
+  "description": "Structural grammar of a complete Jaren application document (see packages/app/docs/APP-FORMAT.md): initial state, a JSLT view stylesheet, named action documents and subscription entries. Composes the published Jaren query and JSLT grammars by reference \u2014 register those artifacts alongside this one. The view's OUTPUT vocabulary (vnodes) is published separately as the jaren-vnode schema in @jarenjs/view. This schema is structural validation only: the runtime remains authoritative for semantic rules it cannot express \u2014 the transition-object shape an action RETURNS ({state?, patch?, effects?}) is the action's runtime result, not its document form; unknown top-level members are ignored for forward compatibility (APP-FORMAT section 2).",
+  "type": "object",
+  "properties": {
+    "$app": {
+      "description": "The app format version; absent implies 0.1.",
+      "const": "0.1"
+    },
+    "state": {
+      "description": "The initial state: any JSON value, treated as immutable by every boundary."
+    },
+    "view": {
+      "description": "The view: a JSLT stylesheet document (bare rule array or envelope form) whose evaluation against the state must produce a single vnode.",
+      "allOf": [
+        {
+          "$ref": "https://jarenjs.dev/schemas/jaren-jslt/0.1"
+        }
+      ]
+    },
+    "actions": {
+      "description": "Named action documents: Jaren JSON Query documents evaluated with $ bound to the state and the externals $event and $payload.",
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+      }
+    },
+    "subs": {
+      "description": "Subscription entries reconciled against the state after every transition.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "run": {
+            "description": "The registered subscription handler name.",
+            "type": "string",
+            "minLength": 1
+          },
+          "with": {
+            "description": "Handler props, passed verbatim (never evaluated). Mutually exclusive with \"withQuery\" and \"for\"."
+          },
+          "when": {
+            "description": "Liveness query, asserted by effective boolean value against the state; absent means always live.",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+              }
+            ]
+          },
+          "withQuery": {
+            "description": "Dynamic props: a query evaluated against the state per reconciliation; the subscription restarts when its resolved key changes. Under \"for\", \"$item\" is bound per instance. Mutually exclusive with \"with\".",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+              }
+            ]
+          },
+          "key": {
+            "description": "Explicit restart key: a query whose resolved value keys the subscription (by value) instead of the resolved props. Requires \"withQuery\" or \"for\"; \"$item\" is bound per instance under \"for\".",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+              }
+            ]
+          },
+          "for": {
+            "description": "Fan-out: a query whose result is the item set \u2014 one running instance per item key, reconciled per state change. \"with\" is not allowed beside it.",
+            "allOf": [
+              {
+                "$ref": "https://jarenjs.dev/schemas/jaren-query/0.1"
+              }
+            ]
+          }
+        },
+        "required": [
+          "run"
+        ]
+      }
+    }
+  },
+  "required": [
+    "view"
+  ]
+}

package/src/actions.js

@@ -0,0 +1,167 @@
+//@ts-check
+/**
+ * @file Compiling the transition vocabulary of an app document: named
+ * action documents and subscription entries. Everything here runs once,
+ * at `createApp` time — the loop only ever calls compiled closures.
+ *
+ * An **action document** is a Jaren JSON Query document (QUERY-FORMAT.md)
+ * evaluated with `$` bound to the current state and two externals:
+ *
+ *  - `$event`   — the serializable event data (`{ type, value, checked,
+ *    key }`) when the dispatch came from the DOM, else `null`
+ *  - `$payload` — the binding's `with` value, else `null`
+ *
+ * It returns a **transition object** (or nothing for a no-op):
+ *
+ *  - `state`   — the next state, whole
+ *  - `patch`   — an RFC 6902 JSON Patch applied to the state (after
+ *    `state`, when both are present)
+ *  - `effects` — `[{ "run": name, "with"?: props }]` handed to the
+ *    registered effect handlers
+ */
+
+import { compileJsonQuery } from '@jarenjs/json/query';
+import { AppCompileError, toError, safeErrorMessage } from './errors.js';
+
+/**
+ * The compile-time options shared by every embedded query document.
+ * @typedef {Object} ActionCompileOptions
+ * @property {(schema: any, docPath: string) => ((value: any) => boolean)} [compileTypeTest]
+ *   Enables `$valid`/`$assert`/`$as` schema operators inside action
+ *   documents; typically `createTypeTestCompiler()` from
+ *   `@jarenjs/validate/query`.
+ */
+
+/**
+ * Compile the `actions` member of an app document.
+ * @param {any} actions
+ * @param {ActionCompileOptions} options
+ * @returns {Map<string, any>} action name → compiled query
+ */
+export function compileActions(actions, options) {
+  if (actions === undefined) return new Map();
+  if (actions === null || typeof actions !== 'object' || Array.isArray(actions)) {
+    throw new AppCompileError('JA0003',
+      'the "actions" member must be an object of named action documents',
+      '/actions');
+  }
+  const map = new Map();
+  for (const name in actions) {
+    try {
+      map.set(name, compileJsonQuery(actions[name], options));
+    }
+    catch (err) {
+      const cause = toError(err);
+      throw new AppCompileError('JA0004',
+        `action '${name}' failed to compile: ${safeErrorMessage(cause)}`,
+        `/actions/${name}`, cause);
+    }
+  }
+  return map;
+}
+
+/**
+ * A compiled subscription entry.
+ * @typedef {Object} CompiledSub
+ * @property {string} run - The registered handler name.
+ * @property {any} props - The entry's `with` value (`null` when absent).
+ * @property {any} when - Compiled liveness query, or `null` (always live).
+ * @property {any} withQuery - Compiled props query evaluated against the
+ *   state (with `$item` bound per instance under `for`), or `null`.
+ * @property {any} keyQuery - Compiled restart-key query, or `null` (the
+ *   key derives from the resolved props by value).
+ * @property {any} forQuery - Compiled fan-out query yielding the item
+ *   set, or `null` (a single-instance subscription).
+ */
+
+/**
+ * Compile one dynamic member of a subscription entry as a query,
+ * closed-world: `externals` names the only variables the document may
+ * leave free (`$item` under `for`, nothing otherwise), so a typo'd
+ * variable is JA0008 at compile time instead of an unbound-external
+ * error at runtime.
+ * @param {any} entry
+ * @param {number} i
+ * @param {string} member
+ * @param {ActionCompileOptions} options
+ * @param {readonly string[]} externals
+ * @returns {any} the compiled query, or `null` when absent
+ */
+function compileSubQuery(entry, i, member, options, externals) {
+  const doc = entry[member];
+  if (doc === undefined) return null;
+  try {
+    return compileJsonQuery(doc, { ...options, externals });
+  }
+  catch (err) {
+    const cause = toError(err);
+    throw new AppCompileError('JA0008',
+      `subscription ${i} ('${entry.run}') has a "${member}" that failed to compile: ${safeErrorMessage(cause)}`,
+      `/subs/${i}/${member}`, cause);
+  }
+}
+
+/**
+ * Compile the `subs` member of an app document:
+ * `[{ "run": name, "with"?: props, "when"?: <EBV query>,
+ *     "withQuery"?: query, "key"?: query, "for"?: query }]`.
+ *
+ * `with` is verbatim data; `withQuery` derives the props from the state
+ * and makes the subscription DYNAMIC — it restarts when its resolved
+ * key changes (`key` overrides the derived-from-props default). `for`
+ * fans the declaration out to one instance per item of its result. The
+ * combinations that would make one entry ambiguous are JA0008: `with`
+ * beside `withQuery`, `with` beside `for`, and `key` without either
+ * `withQuery` or `for`.
+ * @param {any} subs
+ * @param {ActionCompileOptions} options
+ * @returns {CompiledSub[]}
+ */
+export function compileSubs(subs, options) {
+  if (subs === undefined) return [];
+  if (!Array.isArray(subs)) {
+    throw new AppCompileError('JA0005',
+      'the "subs" member must be an array of subscription entries',
+      '/subs');
+  }
+  return subs.map((entry, i) => {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)
+      || typeof entry.run !== 'string' || entry.run === '') {
+      throw new AppCompileError('JA0006',
+        `subscription ${i} must be an object with a non-empty "run" name`,
+        `/subs/${i}`);
+    }
+    let when = null;
+    if (entry.when !== undefined) {
+      try {
+        when = compileJsonQuery(entry.when, options);
+      }
+      catch (err) {
+        const cause = toError(err);
+        throw new AppCompileError('JA0006',
+          `subscription ${i} ('${entry.run}') has a "when" that failed to compile: ${safeErrorMessage(cause)}`,
+          `/subs/${i}/when`, cause);
+      }
+    }
+    if (entry.with !== undefined && entry.withQuery !== undefined) {
+      throw new AppCompileError('JA0008',
+        `subscription ${i} ('${entry.run}') carries both "with" and "withQuery" — one entry, one props source`,
+        `/subs/${i}`);
+    }
+    if (entry.with !== undefined && entry.for !== undefined) {
+      throw new AppCompileError('JA0008',
+        `subscription ${i} ('${entry.run}') carries "with" beside "for" — fan-out props come from "withQuery" or default to the item`,
+        `/subs/${i}`);
+    }
+    if (entry.key !== undefined && entry.withQuery === undefined && entry.for === undefined) {
+      throw new AppCompileError('JA0008',
+        `subscription ${i} ('${entry.run}') carries "key" without "withQuery" or "for" — a static subscription has no restart key`,
+        `/subs/${i}`);
+    }
+    const instanceExternals = entry.for !== undefined ? ['item'] : [];
+    const forQuery = compileSubQuery(entry, i, 'for', options, []);
+    const withQuery = compileSubQuery(entry, i, 'withQuery', options, instanceExternals);
+    const keyQuery = compileSubQuery(entry, i, 'key', options, instanceExternals);
+    return { run: entry.run, props: entry.with ?? null, when, withQuery, keyQuery, forQuery };
+  });
+}