@jarenjs/linq 0.49.2 → 0.56.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.49.2",
+  "version": "0.56.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -11,12 +11,49 @@
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
     },
+    "./schema": {
+      "types": "./types/schema.d.ts",
+      "default": "./src/schema/index.js"
+    },
+    "./model": {
+      "types": "./types/model.d.ts",
+      "default": "./src/model/index.js"
+    },
+    "./jslt": {
+      "types": "./types/jslt.d.ts",
+      "default": "./src/jslt/index.js"
+    },
+    "./migration": {
+      "types": "./types/migration.d.ts",
+      "default": "./src/migration/index.js"
+    },
+    "./contract": {
+      "types": "./types/contract.d.ts",
+      "default": "./src/contract/index.js"
+    },
+    "./flow": {
+      "types": "./types/flow.d.ts",
+      "default": "./src/flow/index.js"
+    },
+    "./app": {
+      "types": "./types/app.d.ts",
+      "default": "./src/app/index.js"
+    },
+    "./forms": {
+      "types": "./types/forms.d.ts",
+      "default": "./src/forms/index.js"
+    },
+    "./db": {
+      "types": "./types/db.d.ts",
+      "default": "./src/db/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "types/",
     "src/",
-    "docs/"
+    "docs/",
+    "ARCHITECTURE.md"
   ],
   "description": "A C#-familiar fluent LINQ surface for the Jaren suite: expression capture into plain query documents, deferred immutable sequences, and a provider seam that runs the same document in memory or anywhere else",
   "author": "joham",
@@ -47,7 +84,23 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.49.2",
-    "@jarenjs/json": "^0.49.2"
+    "@jarenjs/core": "^0.56.0",
+    "@jarenjs/json": "^0.56.0"
+  },
+  "peerDependencies": {
+    "@jarenjs/db": "^0.56.0",
+    "@jarenjs/formats": "^0.56.0",
+    "@jarenjs/validate": "^0.56.0"
+  },
+  "peerDependenciesMeta": {
+    "@jarenjs/db": {
+      "optional": true
+    },
+    "@jarenjs/formats": {
+      "optional": true
+    },
+    "@jarenjs/validate": {
+      "optional": true
+    }
   }
 }

package/src/app/action.js

@@ -0,0 +1,255 @@
+//@ts-check
+/**
+ * @file `action()`, `transition()`, `effect()` and `bind()` — the
+ * transition half of an app document (APP-FORMAT §3–§5.1) and the event
+ * binding that reaches it (§4).
+ *
+ * An action is ONE query document over the state, so everything inside
+ * it — a patch value, an effect's props, a branch — is captured in the
+ * same scope, in one pass: `transition()` and `effect()` therefore
+ * assemble plain objects and leave the spelling to the capture that is
+ * already running, rather than starting their own. That is also what
+ * makes the format's own guarantee expressible: the increment in a
+ * patch and the one in the effect's props are the SAME expression,
+ * because both evaluate against the pre-transition state.
+ *
+ * A binding is built at RENDER time by the view stylesheet, so `bind()`
+ * is the same kind of value in a JSLT body — a payload may embed the
+ * matched node's own members, which is why the format needs no
+ * payload-creator function.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { effectDescriptor, readEffects } from '../effect.js';
+import { describeValue } from '../json-boundary.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { captureAction } from './capture.js';
+import { readPatch } from './patch.js';
+
+/** The action brand: how `defineApp` tells a captured action apart. */
+export const ACTION = Symbol.for('@jarenjs/linq/app-action');
+
+/** The members `action()` takes beside its callback — both TYPES only. */
+const ACTION_MEMBERS = Object.freeze(['payload', 'event']);
+
+/** The members a transition object carries, in §3.2's order of application. */
+const TRANSITION_MEMBERS = Object.freeze(['state', 'patch', 'effects']);
+
+/** The members §4 gives the object binding form. */
+const BIND_MEMBERS = Object.freeze(['payload', 'event', 'preventDefault', 'stopPropagation']);
+
+/**
+ * The host-object-valued fields §3.1 excludes BY NAME. Every OTHER name
+ * is allowed — the built-in allow-list and a host extractor registered
+ * under any name it likes are both legal, and the pen cannot see the
+ * host's registry — but an extractor registered under one of these
+ * would shadow the exclusion the format exists to state, so the pen
+ * refuses the request and names §5.4's own worked example instead.
+ */
+const EXCLUDED_FIELDS = new Set([
+  'target', 'currentTarget', 'relatedTarget', 'srcElement', 'view',
+  'files', 'dataTransfer', 'touches', 'targetTouches', 'changedTouches',
+  'path', 'composedPath', 'clipboardData', 'submitter',
+]);
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * A member set the pen knows, or `JL0101` naming the one it does not.
+ * @param {any} spec
+ * @param {readonly string[]} members
+ * @param {string} what
+ */
+function closedTo(spec, members, what) {
+  for (const key of Object.keys(spec)) {
+    if (!members.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `${what} does not take '${key}' — it takes ${members.join(', ')}`, `/${key}`);
+    }
+  }
+}
+
+/**
+ * A schema builder that TYPES something the document does not carry.
+ * @param {any} value
+ * @param {string} what - the member's own name, a NOUN: the message makes
+ *   it the subject of a sentence, so a phrase here reads as nonsense
+ * @param {string} types - what the builder types, for the clause after it
+ * @param {string} at
+ */
+function typeOnly(value, what, types, at) {
+  if (!isSchemaBuilder(value)) {
+    throw new LinqBuildError('JL0101',
+      `${what} is a schema-pen builder — it types ${types}, and the app format carries no `
+      + `schema for it, so nothing is emitted for it; got ${describeValue(value)}`, at);
+  }
+}
+
+/**
+ * One effect invocation (§5.1): `{ run, with? }`. The props are a value
+ * in the action's own scope — an expression, a literal, or a tree of
+ * both — because the action capture spells the whole transition.
+ * @param {string} run - the registered handler name (`options.effects[run]`)
+ * @param {any} [props] - the handler's `with`
+ * @returns {any} the effect declaration
+ * @example
+ * effect('http', { url: '/api/todos', done: 'todo/loaded' });
+ * effect('contract', { op: 'catalog.load', input: x.payload });
+ */
+export function effect(run, props = undefined) {
+  return effectDescriptor(run, props, (value) => value);
+}
+
+/**
+ * A transition object (§3.2): the next state whole, an RFC 6902 patch
+ * over it, and the effects that run after it settles — written in the
+ * order the runtime applies them.
+ *
+ * Returning nothing from an action is the format's own no-op; a
+ * transition with no member is that same empty object, and is allowed.
+ *
+ * @param {{ state?: any, patch?: readonly any[], effects?: readonly any[] }} spec
+ * @returns {any} the transition, for the action capture to spell
+ * @throws {LinqBuildError} `JL0101` a member the pen does not know, or a
+ *   patch/effects list that is not one
+ * @example
+ * transition({ patch: [add((st) => st.todos, x.payload)] });
+ * transition({ state: () => null, effects: [effect('save')] });
+ */
+export function transition(spec) {
+  if (!isPlainObject(spec)) {
+    throw new LinqBuildError('JL0101',
+      `transition() takes { state?, patch?, effects? }, got ${describeValue(spec)}`);
+  }
+  closedTo(spec, TRANSITION_MEMBERS, 'transition()');
+  const out = {};
+  if (spec.state !== undefined) out.state = spec.state;
+  if (spec.patch !== undefined) out.patch = readPatch(spec.patch);
+  if (spec.effects !== undefined) out.effects = readEffects(spec.effects, 'transition() effects');
+  return out;
+}
+
+/**
+ * One action document (§3): a callback captured over the state, `$event`
+ * and `$payload`, whose result is a transition.
+ *
+ * `payload` and `event` type what the dispatch carries — the format
+ * holds no schema for either, so the pen emits nothing for them; what
+ * they buy is the typed `x.payload` and the `$event` members an action
+ * may read.
+ *
+ * @param {(state: any, externals: any) => any} fn - `(s, x) => transition(…)`
+ * @param {{ payload?: any, event?: readonly string[] }} [options]
+ * @returns {any} the action declaration
+ * @throws {LinqBuildError} `JL0101` a member the pen does not know, or a
+ *   `payload` that is not a builder; `JL0102` an `event` field §3.1
+ *   excludes; `JL0104` a name §3.1 does not bind
+ * @example
+ * action((s, x) => transition({ patch: [add((st) => st.todos, x.payload)] }),
+ *   { payload: s.object({ text: s.string() }) });
+ */
+export function action(fn, options = undefined) {
+  if (typeof fn !== 'function') {
+    throw new LinqBuildError('JL0101',
+      `action() takes a callback (s, x) => transition(…), got ${describeValue(fn)}`);
+  }
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101',
+        `action() options are { payload?, event? }, got ${describeValue(options)}`);
+    }
+    closedTo(options, ACTION_MEMBERS, 'action()');
+    if (options.payload !== undefined) {
+      typeOnly(options.payload, 'action() payload', "the dispatch's $payload", '/payload');
+    }
+    if (options.event !== undefined) readEventFields(options.event, 'action()');
+  }
+  const document = captureAction('action()', fn);
+  const out = { document };
+  Object.defineProperty(out, ACTION, { value: true, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * The `event` member of a binding (§4): an array of the extra `$event`
+ * field names to resolve. A name §3.1 excludes by construction is
+ * `JL0102`; every other name is allowed, because a host extractor
+ * registered under it wins over the built-in list and the pen cannot
+ * see the host's registry.
+ * @param {any} fields
+ * @param {string} what
+ * @returns {string[]}
+ */
+function readEventFields(fields, what) {
+  if (!Array.isArray(fields)) {
+    throw new LinqBuildError('JL0101',
+      `${what} event is an array of field names (APP-FORMAT §4), got ${describeValue(fields)}`,
+      '/event');
+  }
+  return fields.map((name, i) => {
+    if (typeof name !== 'string' || name === '') {
+      throw new LinqBuildError('JL0101',
+        `${what} event[${i}] is a field name, got ${describeValue(name)}`, `/event/${i}`);
+    }
+    if (EXCLUDED_FIELDS.has(name)) {
+      throw new LinqBuildError('JL0102',
+        `an event binding cannot request '${name}' — APP-FORMAT §3.1 excludes target, files, `
+        + 'touch lists and every other host-object-valued field by construction, because '
+        + '$event MUST survive JSON.stringify, the same invariant as state. Register an '
+        + 'extractor under a name of its own (§5.4\'s worked example maps event.target.files '
+        + "to opaque string tokens under 'fileTokens') and request that.", `/event/${i}`);
+    }
+    return name;
+  });
+}
+
+/**
+ * One event binding (§4): `{ action, with?, event?, preventDefault?,
+ * stopPropagation? }`, in the member order the format writes them.
+ *
+ * A payload is data built at render time, so it may embed anything in
+ * the stylesheet body's scope — the matched node's own members, `$path`,
+ * `$root` — which is what replaces a payload-creator function.
+ *
+ * @template {string} Names
+ * @param {Names} name - the action to dispatch
+ * @param {{ payload?: any, event?: readonly string[], preventDefault?: boolean, stopPropagation?: boolean }} [options]
+ * @returns {any} the binding, for the view's body capture to spell
+ * @throws {LinqBuildError} `JL0101` an empty name, a member the pen does
+ *   not know, or a non-boolean control; `JL0102` an `event` field §3.1 excludes
+ * @example
+ * bind('selectRow', { payload: { id: v.id }, event: ['shiftKey', 'ctrlKey'] });
+ * bind('rowOpen', { stopPropagation: true });
+ */
+export function bind(name, options = undefined) {
+  if (typeof name !== 'string' || name === '') {
+    throw new LinqBuildError('JL0101',
+      `bind() takes an action name as a non-empty string, got ${describeValue(name)}`,
+      '/action');
+  }
+  const out = { action: name };
+  if (options !== undefined) {
+    if (!isPlainObject(options)) {
+      throw new LinqBuildError('JL0101',
+        'bind() options are { payload?, event?, preventDefault?, stopPropagation? }, got '
+        + describeValue(options));
+    }
+    closedTo(options, BIND_MEMBERS, 'bind()');
+    if (options.payload !== undefined) out.with = options.payload;
+    if (options.event !== undefined) out.event = readEventFields(options.event, 'bind()');
+    for (const control of ['preventDefault', 'stopPropagation']) {
+      if (options[control] === undefined) continue;
+      if (typeof options[control] !== 'boolean') {
+        throw new LinqBuildError('JL0101',
+          `bind() ${control} is a boolean — it is allowed only on the object binding form `
+          + `and defaults to false (APP-FORMAT §4), got ${describeValue(options[control])}`,
+          `/${control}`);
+      }
+      out[control] = options[control];
+    }
+  }
+  return out;
+}

package/src/app/capture.js

@@ -0,0 +1,63 @@
+//@ts-check
+/**
+ * @file The one capture under an app document's query-valued members.
+ *
+ * An action is a query document evaluated with three names and no others
+ * (APP-FORMAT §3.1): `$` is the whole state, `$event` the serializable
+ * event slice, `$payload` the dispatch payload. So a callback receives
+ * the state at its first argument and those two externals at its second,
+ * and a name the loop does not bind is `JL0104` here — where the fix can
+ * be named — rather than an unbound external at dispatch time.
+ *
+ * A subscription's dynamic members evaluate in a NARROWER scope: `when`
+ * and `for` see the state alone, `withQuery` and `key` additionally see
+ * `$item` and only under `for` (§5.3, "compiled closed-world"). The
+ * pen mirrors that scope exactly, so a document it writes cannot be the
+ * `JA0008` a free variable would be at `createApp` time.
+ *
+ * Every capture here folds NOTHING: a transition, a binding and an
+ * effect's props are spelled as the constructors the format's own
+ * examples carry (`{ "op": "replace", … }`, `{ "ms": 1000 }`), never
+ * collapsed into one `$const`.
+ */
+
+import { captureQuery } from '../capture-root.js';
+
+/** §3.1's ambient vocabulary, for a `JL0104` message. */
+export const ACTION_SCOPE = 'an action document (APP-FORMAT §3.1)';
+
+/** The externals the dispatch loop binds on every action. */
+const ACTION_EXTERNALS = Object.freeze(['event', 'payload']);
+
+/** How an unbound action name could be reached, appended to `JL0104`. */
+const ACTION_ADVICE = () => ' — the whole state is the first argument; §3.1 binds $event and '
+  + '$payload and nothing else, and a host value reaches an action through a binding\'s '
+  + 'payload or an event-field extractor';
+
+/**
+ * Capture one action-scope callback: `(s, x) => …` over `$`, `$event`
+ * and `$payload`.
+ * @param {string} what - the method, for the message
+ * @param {(state: any, externals: any) => any} fn
+ * @returns {any} the query document (plain JSON)
+ */
+export function captureAction(what, fn) {
+  return captureQuery(what, ACTION_EXTERNALS, fn, { advice: ACTION_ADVICE, fold: false });
+}
+
+/**
+ * Capture one subscription member over §5.3's closed world.
+ * @param {string} what - the member, for the message
+ * @param {readonly string[]} externals - `['item']` under `for`, else none
+ * @param {any} value - a callback, or a query document written by hand
+ * @returns {any} the query document (plain JSON)
+ */
+export function captureSub(what, externals, value) {
+  if (typeof value !== 'function') return JSON.parse(JSON.stringify(value));
+  const advice = () => (externals.length === 0
+    ? ` — a subscription's ${what} is compiled closed-world against the state alone; $item `
+      + 'exists only under a "for" declaration (APP-FORMAT §5.3)'
+    : ` — a subscription's ${what} under "for" sees the state and $item, nothing else `
+      + '(APP-FORMAT §5.3)');
+  return captureQuery(`sub() ${what}`, externals, value, { advice, fold: false });
+}

package/src/app/define.js

@@ -0,0 +1,260 @@
+//@ts-check
+/**
+ * @file `defineApp()` — one `jaren-app` 0.1 document (APP-FORMAT §2),
+ * deep-frozen, that `createApp` takes unchanged, and beside it the JSON
+ * Schema of its state.
+ *
+ * The two are answered as two members of ONE result and never merged:
+ * the format has no slot for a state schema, and the hook that wants one
+ * is `options.validateState` (§6), which is a `createApp` option rather
+ * than a document member. `{ document, stateSchema }` is therefore what
+ * the pen returns — the document is exactly the format's, and the schema
+ * goes where the invariant lives.
+ *
+ * The initial state is DERIVED from the state builder's `default()`s
+ * when the author does not write one: a member contributes its default,
+ * an object recurses, and a REQUIRED member that resolves to nothing is
+ * `JL0102` naming its pointer — because a state whose required member is
+ * absent fails its own `validateState` on the boot transaction, which is
+ * a fatal `JA0007` and a bad way to learn about a missing default.
+ *
+ * `defineApp` also holds one rule §4 leaves to run time: every literal
+ * action name the view binds must be declared. The runtime reports an
+ * unknown name as `JA2001` per dispatch, silently dropping the user's
+ * click; the pen can see the whole document at once and refuses it.
+ */
+
+import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
+import { isSchemaBuilder, schemaOf } from '../schema/brand.js';
+import { ACTION } from './action.js';
+import { SUB } from './sub.js';
+
+const APP_VERSION = '0.1';
+
+/** The members `defineApp()` takes. */
+const APP_MEMBERS = Object.freeze(['state', 'initial', 'schema', 'view', 'actions', 'subs']);
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** A JSON value, copied: the document is a value of its own. @param {any} v */
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * The initial value a schema's `default()`s describe.
+ *
+ * A `default` answers itself. An object schema recurses: every member
+ * that resolves contributes, and a member `required` names but which
+ * resolves to nothing is refused. An object resolves when it is
+ * required, or when at least one of its own members did — so an
+ * optional block of defaults appears and an optional empty one does not.
+ *
+ * @param {any} schema
+ * @param {string} at - the pointer into the state, for the message
+ * @param {boolean} needed - whether the parent requires this member
+ * @returns {{ has: boolean, value?: any }}
+ */
+function initialOf(schema, at, needed) {
+  if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+    return { has: false };
+  }
+  if (schema.default !== undefined) return { has: true, value: copy(schema.default) };
+  if (schema.const !== undefined) return { has: true, value: copy(schema.const) };
+  if (!isPlainObject(schema.properties)) return { has: false };
+
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const out = {};
+  let any = false;
+  for (const [name, member] of Object.entries(schema.properties)) {
+    const isRequired = required.includes(name);
+    const resolved = initialOf(member, `${at}/${name}`, isRequired);
+    if (resolved.has) { setObjectMember(out, name, resolved.value); any = true; continue; }
+    if (!isRequired) continue;
+    throw new LinqBuildError('JL0102',
+      `the initial state cannot be derived: '${at}/${name}' is required and declares no `
+      + 'default — give the member a default(), or pass the whole initial state as '
+      + "defineApp()'s 'initial'", `${at}/${name}`);
+  }
+  return needed || any ? { has: true, value: out } : { has: false };
+}
+
+/**
+ * A literal action name, or `null`: a value starting with `$` is a query
+ * expression naming the action at render time, which no pen can resolve.
+ * @param {any} value
+ * @returns {string | null}
+ */
+function literalName(value) {
+  return typeof value === 'string' && value !== '' && value[0] !== '$' ? value : null;
+}
+
+/**
+ * Every literal action name the view binds. §4 gives a binding two
+ * forms and this reads both: a string under an `on` map (a vnode's
+ * event props, VIEW-FORMAT's own member), and an object carrying an
+ * `action` member anywhere — that member IS §4's vocabulary, so an
+ * object holding one is a binding wherever a widget's `emit` will find
+ * it.
+ * @param {any} node
+ * @param {Set<string>} out
+ */
+function collectBoundActions(node, out) {
+  if (Array.isArray(node)) {
+    for (const child of node) collectBoundActions(child, out);
+    return;
+  }
+  if (node === null || typeof node !== 'object') return;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === 'action') {
+      const name = literalName(value);
+      if (name !== null) out.add(name);
+    }
+    if (key === 'on' && isPlainObject(value)) {
+      for (const binding of Object.values(value)) {
+        const name = literalName(binding);
+        if (name !== null) out.add(name);
+      }
+    }
+    collectBoundActions(value, out);
+  }
+}
+
+/**
+ * The `view` member: a JSLT stylesheet, envelope or bare rule array
+ * (§2), from the JSLT pen or by hand.
+ * @param {any} view
+ * @returns {any}
+ */
+function readView(view) {
+  if (view === undefined) {
+    throw new LinqBuildError('JL0101',
+      'defineApp() needs a view — a JSLT stylesheet, from stylesheet([rule(…)]) or as a '
+      + 'bare rule array; the format requires the member and the runtime refuses an app '
+      + 'without one (JA0002)', '/view');
+  }
+  if (!Array.isArray(view) && !isPlainObject(view)) {
+    throw new LinqBuildError('JL0101',
+      `defineApp() view is a JSLT stylesheet document or a bare rule array, got ${describeValue(view)}`,
+      '/view');
+  }
+  return copy(requireJson(view, 'defineApp() view'));
+}
+
+/**
+ * Write a `jaren-app` 0.1 document (APP-FORMAT.md §2) and the JSON
+ * Schema of its state.
+ *
+ * @param {any} spec - `{ state, initial?, schema?, view, actions?, subs? }`
+ * @returns {{ document: any, stateSchema: any }} the deep-frozen document
+ *   and the state's schema (`null` when the state is a plain value with
+ *   no `schema` beside it)
+ * @throws {LinqBuildError} `JL0101` a value the pen cannot spell;
+ *   `JL0102` an initial state no default describes, or a bound action
+ *   name `actions` does not declare
+ * @example
+ * const { document, stateSchema } = defineApp({
+ *   state: s.object({ count: s.integer().default(0) }),
+ *   view: [rule('$', (v) => ['h1', {}, 'Count: ', v.count])],
+ *   actions: { inc: action((st) => transition({ patch: [replace((c) => c.count, st.count.add(1))] })) },
+ * });
+ * createApp(document, { node, validateState: new JarenValidator().compile(stateSchema) });
+ */
+export function defineApp(spec) {
+  if (!isPlainObject(spec)) {
+    throw new LinqBuildError('JL0101',
+      `defineApp() takes { state, initial?, schema?, view, actions?, subs? }, got ${describeValue(spec)}`);
+  }
+  for (const key of Object.keys(spec)) {
+    if (!APP_MEMBERS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `defineApp() does not take '${key}' — it takes ${APP_MEMBERS.join(', ')}`, `/${key}`);
+    }
+  }
+
+  const stateIsBuilder = isSchemaBuilder(spec.state);
+  if (stateIsBuilder && spec.schema !== undefined) {
+    throw new LinqBuildError('JL0101',
+      "defineApp() takes 'schema' beside a state given as a plain JSON value — a state "
+      + 'given as a builder IS its schema', '/schema');
+  }
+  if (spec.schema !== undefined && !isSchemaBuilder(spec.schema)) {
+    throw new LinqBuildError('JL0101',
+      `defineApp() schema is a schema-pen builder, got ${describeValue(spec.schema)}`, '/schema');
+  }
+  const stateSchema = stateIsBuilder ? schemaOf(spec.state)
+    : spec.schema !== undefined ? schemaOf(spec.schema) : null;
+
+  let state;
+  if (spec.initial !== undefined) state = copy(requireJson(spec.initial, 'defineApp() initial'));
+  else if (stateIsBuilder) state = initialOf(stateSchema, '', true).value;
+  else if (spec.state !== undefined) state = copy(requireJson(spec.state, 'defineApp() state'));
+
+  const view = readView(spec.view);
+
+  /** @type {Record<string, any> | undefined} */
+  let actions;
+  if (spec.actions !== undefined) {
+    if (!isPlainObject(spec.actions)) {
+      throw new LinqBuildError('JL0101',
+        `defineApp() actions is an object of named action() declarations, got ${describeValue(spec.actions)}`,
+        '/actions');
+    }
+    requireNameMap(spec.actions, 'defineApp() actions', '/actions');
+    actions = {};
+    for (const [name, declared] of Object.entries(spec.actions)) {
+      if (!isPlainObject(declared) || declared[ACTION] !== true) {
+        throw new LinqBuildError('JL0101',
+          `defineApp() action '${name}' is action((s, x) => transition(…)), got ${describeValue(declared)}`,
+          `/actions/${name}`);
+      }
+      setObjectMember(actions, name, declared.document);
+    }
+  }
+
+  /** @type {any[] | undefined} */
+  let subs;
+  if (spec.subs !== undefined) {
+    if (!Array.isArray(spec.subs)) {
+      throw new LinqBuildError('JL0101',
+        `defineApp() subs is an array of sub() declarations, got ${describeValue(spec.subs)}`,
+        '/subs');
+    }
+    subs = spec.subs.map((declared, i) => {
+      if (!isPlainObject(declared) || declared[SUB] !== true) {
+        throw new LinqBuildError('JL0101',
+          `defineApp() subs[${i}] is sub(run, options?), got ${describeValue(declared)}`,
+          `/subs/${i}`);
+      }
+      return { ...declared };
+    });
+  }
+
+  /** @type {Set<string>} */
+  const bound = new Set();
+  collectBoundActions(view, bound);
+  const declared = Object.keys(actions ?? {});
+  for (const name of bound) {
+    if (declared.includes(name)) continue;
+    throw new LinqBuildError('JL0102',
+      `the view binds the action '${name}', which "actions" does not declare — the runtime `
+      + 'drops such a dispatch and reports JA2001 (APP-FORMAT §4), so the user\'s click does '
+      + `nothing; the declared actions are ${declared.length === 0 ? 'none'
+        : declared.map((n) => `'${n}'`).join(', ')}`, '/view');
+  }
+
+  const document = { $app: APP_VERSION };
+  if (state !== undefined) document.state = state;
+  document.view = view;
+  if (actions !== undefined) document.actions = actions;
+  if (subs !== undefined) document.subs = subs;
+
+  return Object.freeze({
+    document: deepFreeze(document),
+    stateSchema: stateSchema === null ? null : deepFreeze(copy(stateSchema)),
+  });
+}

package/src/app/index.js

@@ -0,0 +1,20 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/app` — a `jaren-app` 0.1 application by code.
+ * `defineApp()` writes the document `createApp` runs: a state whose
+ * initial value comes from its own schema's defaults, the JSLT pen's
+ * stylesheet as the view, actions captured over APP-FORMAT §3.1's three
+ * names, patch paths derived from the state shape, and subscriptions
+ * compiled in §5.3's closed world. It answers the document and the
+ * state's JSON Schema as two members of one result — the format has no
+ * slot for the second, and `validateState` is where it belongs.
+ *
+ * Everything the document holds is data, so everything this pen writes
+ * is JSON: nothing here imports `@jarenjs/app`, and the loop's compiler
+ * stays the only judge of what an app means.
+ */
+
+export { defineApp } from './define.js';
+export { action, transition, effect, bind } from './action.js';
+export { add, append, replace, remove, move, copy, test } from './patch.js';
+export { sub } from './sub.js';