sygnal 6.2.0 → 6.3.0

package/src/extra/ai/chat/driver.ts

@@ -12,7 +12,7 @@ import {messageId} from '../messages';
  *
  * - Request (sink value): `{ messages, instructions?, tools?, model?, output?, key?, latest?,
  *   delta?, ok?, error?, tool?, coalesce?, ...transportOptions }`, passed to the transport as is
- *   (sender-stamped, scope-tagged). `{ abort: key | true }` / `{ abort: true, key }` stop the
+ *   (sender-stamped, scope-tagged). `{ abort: key | [keys] | true }` / `{ abort: true, key }` stop the
  *   sender's runs under that key (all of them for a bare `abort: true`).
  *   - A `then` / `catch` key is SYG610 (allowed()); a value that isn't a request (no `messages`
  *     array, an unknown `coalesce`, an `output` that isn't a Standard Schema) is SYG679: not sent.
@@ -24,7 +24,8 @@ import {messageId} from '../messages';
  *     `delta` is the text that is new since the last one (D251);
  *   - `tool` `{ key, call: { id, name, input } }` once per completed call;
  *   - `ok` `{ key, message, text, value?, toolCalls, finishReason, usage }` (`value`: the
- *     validated structured output when the request has `output`, G-604);
+ *     validated structured output when the request has `output`, G-604; not with `parse: false`,
+ *     which sends the schema but leaves reading `text` to the caller: PLAN-9 compose.llm());
  *   - `error` `{ key, error, request, issues? }`. A failure with no `error` action is SYG678
  *     (logged, also in production; G-584).
  * - An aborted run (abort, latest, sender dispose, app dispose, sink complete) delivers nothing:
@@ -221,7 +222,8 @@ export function makeChatDriver(options: any = {}) {
         if (!live()) return;
         flush();
         let value: any;
-        const structured = req.output !== undefined && (!toolCalls.length || !!text.trim());
+        // `parse: false` (PLAN-9 B-4): the transport still sends the schema, the caller reads `text` (compose.llm()'s lenient reader)
+        const structured = req.output !== undefined && req.parse !== false && (!toolCalls.length || !!text.trim());
         if (structured) {
           value = await readOutput(req.output, text);
           if (!live()) return;
@@ -244,8 +246,9 @@ export function makeChatDriver(options: any = {}) {
         if (sender === undefined) return void dev('SYG677', req);
         const {abort} = req;
         if (abort !== undefined && abort !== false) {
+          // D469 (PLAN-9 H-2): a list of keys stops each (STOP: the reply and a card being composed)
           const k = abort === true ? req.key : abort;
-          return abortWhere(r => r.sender === sender && (k === undefined || r.key === k));
+          return abortWhere(r => r.sender === sender && (k === undefined || (Array.isArray(k) ? k.includes(r.key) : r.key === k)));
         }
         const why = problem(req);
         if (why) return void logError('SYG679', req.__emitterName, `makeChatDriver: request not sent: ${why}`, FIX, req);

package/src/extra/ai/compose/agent.ts

@@ -0,0 +1,55 @@
+/*
+ * PLAN-9 C-2: a composition as an agent action, so a chat assistant (or WebMCP, the command bar)
+ * can rearrange the page. The behavior's COMPOSE is an ordinary host action ('page.COMPOSE'), so
+ * the A-1 agent layer runs it like any other; these helpers only save the boilerplate:
+ *
+ *   App.uses = { page: compose(catalog, { backend }), assistant: chat({ form: '.ask', prompt: '.prompt' }) }
+ *   App.agent = {
+ *     name: 'app',
+ *     read: (state) => ({ page: compose.summary(state.page) }),
+ *     actions: { ...compose.action('page') },      // the tool app_page_compose({ prompt, fresh? })
+ *   }
+ *
+ * - compose.action(key = 'page', { description?, timeout? }): `{ [key + '.COMPOSE']: { description,
+ *   input: { prompt, fresh? }, until, timeout } }`. `until` holds the tool result until the
+ *   composition is over (status neither 'composing' nor 'preview': done, unavailable or error), so
+ *   the result's `state` (the `read` projection) shows the new page; `timeout` (default 60 s, a
+ *   model call takes a while) answers `{ ok: true, pending: true }` instead, as for any `until`.
+ * - compose.summary(slice): what the `read` projection shows of a composition: `{ status, page:
+ *   the layout as a tree (toTree), error? }`.
+ *
+ * With compose.llm() the composition's request goes on the same LLM sink as the chat's, in its own
+ * lane (`key: 'compose'` vs the chat's uses key) with its own reply actions ('page.REPLY'), so the
+ * two never abort or answer each other; the chat's next request waits for `until`.
+ */
+import {jsonSchema} from '../schema/jsonSchema'
+import {toTree} from './layout'
+
+const INPUT = {
+  type: 'object',
+  properties: {
+    prompt: {type: 'string', minLength: 1, description: 'What the page should show, or how to change it, in the user\'s words'},
+    fresh: {type: 'boolean', description: 'true: start over instead of changing the current page'},
+  },
+  required: ['prompt'],
+  additionalProperties: false,
+}
+
+/** the `agent.actions` entry for the composition under `key` (see the header) */
+export function composeAction(key: string = 'page', options: {description?: string; timeout?: number} = {}) {
+  const {description = 'Rearrange the page from its prepared parts: say what it should show (it changes the current page unless fresh is true). The result has the new page', timeout = 60000} = options
+  return {
+    [key + '.COMPOSE']: {
+      description,
+      input: jsonSchema(INPUT),
+      until: (state: any) => { const s = state?.[key]?.status; return s != 'composing' && s != 'preview' },
+      timeout,
+    },
+  }
+}
+
+/** a composition as an agent reads it: `{ status, page, error? }` (`page`: the layout as a tree) */
+export function composeSummary(slice: any) {
+  if (!slice || typeof slice != 'object') return undefined
+  return {status: slice.status, page: toTree(slice.layout), ...(slice.error && {error: slice.error})}
+}

package/src/extra/ai/compose/ask.ts

@@ -0,0 +1,147 @@
+/*
+ * PLAN-9 H-2 / H-3: cards in the chat (dev-plans/research/ai-compose/chat-client-tools.md, D454,
+ * D455, D469). `chat({ ask: { catalog, backend?, instructions?, direct? } })` adds the client tool
+ * `ask_user({ need })`; the configured backend composes a card from `need` and the app state (never
+ * the conversation), and a result part's answer becomes the call's output `{ part, answer }`.
+ *
+ * The chat behavior reaches this module through the catalog (`catalog._ask`, set by defineCatalog),
+ * so an app with `chat` and no catalog carries none of it (nor compose.llm).
+ *
+ * The card lives on the tool part: `part.ui = { status, layout, local, ui, answer, pending, decisions? }`:
+ * - status: 'composing' (queued, or its backend step is out: `pending` set) | 'open' (answerable) |
+ *   'answered' | 'failed' (the part is output-error "could not show a card: …") | 'cancelled'
+ *   (STOP, SEND);
+ * - layout: the card (a decision backend's preview while it composes); ui / local: container state
+ *   and `local` parts' state per node key, as in a compose slice; answer: `{ node, part, value }`;
+ * - pending: the backend's step while its request is out (plain JSON);
+ * - decisions: what the backend explains, its last reply's `decisions` (as a compose slice keeps
+ *   them; absent until a reply carries some).
+ * Cards compose one at a time, on the backend's sink, under the key `<use>.ask:<toolCallId>`, with
+ * the reply actions `<use>.CARD` / `<use>.CARD_FAILED`.
+ *
+ * `direct: true` (H-3): the tool's input schema is the layout schema (compose.llm's, without the
+ * plan field) and the call's input is the card, read and repaired like an LLM backend's reply: no
+ * compose round trip.
+ *
+ * `askCard(catalog, state, part, { key })` renders a card in the host's view: catalog.render with
+ * the call id as scope, frozen unless the card is open, the answer marked, `local` written through
+ * a lens to the part.
+ */
+import {warn} from '../../diagnostics/legacy'
+import {llm, layoutSchema} from './llm'
+import {cardArgs} from './render'
+
+export const ASK = 'ask_user'
+
+const DESCRIPTION = 'Ask the user and wait for their answer: a choice, a pick among the app\'s items, a short form or a confirmation. Say in one sentence what you need from them; the app shows a card for it. Prefer this to asking in text when the answer is one of a few options or structured.'
+const DIRECT = 'Ask the user and wait for their answer: a choice, a pick among the app\'s items, a short form or a confirmation. The input is the card, built from the app\'s parts; include a part the user answers with. Prefer this to asking in text when the answer is one of a few options or structured.'
+const NEED = {
+  type: 'object',
+  properties: {need: {type: 'string', maxLength: 300, description: 'What you need from the user, in one sentence'}},
+  required: ['need'],
+  additionalProperties: false,
+}
+
+/** the card compositions per catalog (composeWith answers their pending step) */
+const cards = /*#__PURE__*/ new WeakMap<object, Array<{backend: any; keys: Set<string>; mine: WeakSet<object>}>>()
+export const cardsOf = (catalog: object) => cards.get(catalog) || []
+
+/** the chat's `ask` option, resolved once per chat() call */
+export function askConfig(ask: any, o: any, sink: string) {
+  const {catalog, backend, direct, instructions} = ask
+  if (!catalog || typeof catalog.render != 'function') throw new Error('[Sygnal] chat({ ask }): `ask.catalog` must be a catalog made by defineCatalog()')
+  const results = [...new Set(Object.values<any>(catalog.parts).filter(p => p.result && p.component).map(p => p.component))]
+  if (!Object.values<any>(catalog.parts).some(p => p.result)) {
+    warn('SYG686', 'chat', 'the ask catalog has no result part (`result: true`), so no card can be answered: every ask_user call waits until STOP or a new message', 'Mark the parts the user answers with `result: true` and send compose.answer(props, value) to PARENT')
+  }
+  const be = direct ? null : backend ?? llm({sink, ...(o.model && {model: o.model}), ...o.transportOptions})
+  // mine: the pending steps this chat() made, so composeWith picks its backend among the catalog's
+  const entry = {backend: be, keys: new Set<string>(), mine: new WeakSet<object>()}
+  if (be) {
+    if (!cards.has(catalog)) cards.set(catalog, [])
+    cards.get(catalog)!.push(entry)
+  }
+  return {catalog, backend: be, direct: !!direct, instructions, results, entry, reader: direct ? llm() : null,
+    controls: Object.values<any>(catalog.containers || {}).some(c => typeof c.decl?.render == 'function')}
+}
+export type AskConfig = ReturnType<typeof askConfig>
+
+/** the ask_user tool for a request (direct: the layout schema, for the host state of now) */
+export const askTool = (c: AskConfig, state: any) => ({
+  description: (c.direct ? DIRECT : DESCRIPTION) + (c.instructions ? ' ' + c.instructions : ''),
+  inputSchema: c.direct ? layoutSchema(c.catalog, state, {plan: false}) : NEED,
+})
+
+const message = (e: any) => String(e?.message ?? e ?? 'error')
+const ui = (p: any, patch: any) => ({...p, ui: {...p.ui, ...patch}})
+
+/** the card can't be shown: the call answers with an error, and the turn goes on */
+export const failed = (p: any, why: string) => ({
+  ...ui(p, {status: 'failed', pending: null}),
+  state: 'output-error',
+  errorText: `could not show a card: ${why}; ask in text instead`,
+})
+
+/** an ask_user call as it opens: composing (queued), or (direct) the card itself */
+export function openCard(c: AskConfig, p: any, state: any): any {
+  const base = {...p, ui: {status: 'composing', layout: null, local: {}, ui: {}, answer: null, pending: null}}
+  if (c.direct) return read(c, base, c.reader!.reply({catalog: c.catalog, state, pending: {plan: false}, reply: {value: p.input}} as any))
+  const need = p.input?.need
+  return typeof need == 'string' && need.trim() ? base : failed(base, 'the call has no `need` (one sentence saying what you need from the user)')
+}
+
+/** a backend result → the card part, and the next request when there is one */
+function read(c: AskConfig, p: any, r: any): any {
+  if (!r) return failed(p, 'the backend gave no layout')
+  // what the backend explains (its last `decisions`), kept on the card like a compose slice's
+  if (r.decisions !== undefined) p = ui(p, {decisions: r.decisions})
+  if (r.error != null) return failed(p, message(r.error))
+  if (r.request !== undefined) return {part: ui(p, {pending: own(c, r.pending ?? p.ui.pending), ...(r.preview && {layout: r.preview})}), request: r.request}
+  if (r.layout) return ui(p, {status: 'open', layout: r.layout, pending: null})
+  return failed(p, 'nothing in the catalog fits it')
+}
+const own = (c: AskConfig, pending: any) => { if (pending && typeof pending == 'object') c.entry.mine.add(pending); return pending }
+const names = (k: string, id: string) => ({ok: k + '.CARD', error: k + '.CARD_FAILED', key: `${k}.ask:${id}`}) as any
+
+/**
+ * G-756: an HTTP reply (compose.decisions()) is the parsed body, with no request key, so a card's
+ * request tags its JSON body with the card's key (`askKey`); the chat's CARD step drops a reply
+ * tagged for another card (one closed by TOOL_OUTPUT while it composed). A request with its own
+ * `parse`, or one for the chat driver (its replies carry the key), is sent as it is.
+ */
+const tag = (req: any, key: string) => req && typeof req == 'object' && typeof req.url == 'string' && req.parse === undefined
+  ? {...req, parse: async (res: any) => {
+    const text = await res.text(), v = text ? JSON.parse(text) : null
+    return v && typeof v == 'object' && !Array.isArray(v) ? {...v, askKey: key} : v
+  }}
+  : req
+
+/** start composing a queued card: `{ part, request }`, or the failed part */
+export function startCard(c: AskConfig, p: any, state: any, k: string): any {
+  c.entry.keys.add(k)
+  try {
+    const n = names(k, p.toolCallId)
+    const r = c.backend!.start({catalog: c.catalog, state, prompt: String(p.input.need).trim(), previous: null, names: n})
+    return {part: ui(p, {pending: own(c, r.pending ?? {})}), request: tag(r.request, n.key)}
+  } catch (e) { return failed(p, message(e)) }
+}
+
+/** a backend reply for the card in flight: `{ part, request }` (another step), or the card part */
+export function cardReply(c: AskConfig, p: any, reply: any, state: any, k: string): any {
+  try {
+    const n = names(k, p.toolCallId), r = read(c, p, c.backend!.reply({catalog: c.catalog, state, pending: p.ui.pending, reply, names: n}))
+    return r?.request !== undefined ? {...r, request: tag(r.request, n.key)} : r
+  } catch (e) { return failed(p, message(e)) }
+}
+
+/**
+ * askCard(catalog, state, part, { key = 'assistant' }): the card of an ask_user tool part, for
+ * the host's view (null while it has no layout)
+ */
+export function askCard(catalog: any, state: any, part: any, options: {key?: string} = {}): any {
+  const c = cardArgs(state, part, options.key)
+  return c && catalog.render(c[0], state, c[1])
+}
+
+/** what chat() reads through `catalog._ask` */
+export const askKit = {askConfig, askTool, openCard, startCard, cardReply, failed}

package/src/extra/ai/compose/behavior.ts

@@ -0,0 +1,183 @@
+/*
+ * PLAN-9 C-1: the `compose` behavior (phase1-contract.md, PROPOSAL.md §3).
+ *
+ *   Workspace.uses = { page: compose(catalog, { backend: compose.decisions({ model }), form: '.ask', prompt: '.prompt' }) }
+ *   view: {catalog.render(state.page, state)}
+ *
+ * Slice (state.page): { prompt, status, layout, preview, pending, decisions, error, ui, local }
+ * - status: 'idle' | 'composing' (a request is out) | 'preview' (a partial layout shows: after a
+ *   decision step, or while an LLM streams) | 'done' | 'unavailable' (nothing in the catalog fits:
+ *   the layout is kept) | 'error' (the layout is kept; `error` says why);
+ * - layout: the last finished layout; preview: the one being built (rendered instead while set);
+ * - pending: the backend's step (plain JSON); decisions: what the backend explains (its last);
+ * - ui: container state per node key (CONTROL: `{ key, name, value }` → ui[key][name] = value; the
+ *   clicks are read only when a container has its own render);
+ *   local: the state of `local` parts per node key.
+ *
+ * Actions ('page.X'): COMPOSE (data: a prompt string, `{ prompt, fresh? }`, or the form's submit:
+ * the slice's prompt; an edit of the current layout unless `fresh`), SET_LAYOUT (a layout, finished
+ * first: restore, undo, the app's own edits; null clears), REMOVE (a node key), CONTROL, DONE (a
+ * composition finished: data is the layout; a host entry 'page.DONE' runs after it). Internal:
+ * PROMPT (typing), REPLY / DELTA / FAILED (the backend sink's reply actions). A backend reply
+ * `{ error }` (not a valid layout even after repair), or a start / reply that throws, is handled as
+ * FAILED: status 'error', the layout kept; a delta that throws is ignored.
+ *
+ * The only sink it declares is `backend.sink`. Requests go in the lane `key` (default 'compose')
+ * with `latest`, so a new prompt aborts the old one's step in flight. The reply names are the
+ * use's key: `page.REPLY`, `page.DELTA`, `page.FAILED`. Finished layouts and previews are re-keyed
+ * against the current layout (fromTree's previous-key reuse), so a part a follow-up doesn't change
+ * keeps its node key, and so its instance and state, whatever keys the backend gave it. A reply
+ * or delta with `keyed: true` (both backends' edits, B-4) already carries the previous layout's keys
+ * and is used as is (re-keying by identity could swap the keys of two copies of one part).
+ *
+ * The handlers that need the host's whole state (record params read it) are HOST entries; a sink
+ * reads it as `props.state` (the pre-action state), and one memo per behavior value makes STATE,
+ * the sink and EFFECT of one action compute the same step.
+ */
+import {defineBehavior} from '../../behaviors'
+import {ABORT} from '../../../shared'
+import {fail} from '../../diagnostics/legacy'
+import {finish, fromTree, removeNode, toTree} from './layout'
+import type {Backend, Catalog, Layout} from './types'
+
+/** the compositions per catalog (composeWith finds the pending one): backend, lane and use keys */
+const uses = /*#__PURE__*/ new WeakMap<object, Array<{backend: Backend; lane: string; keys: Set<string>; mine: WeakSet<object>}>>()
+export const usesOf = (catalog: object) => uses.get(catalog) || []
+
+const message = (e: any) => String(e?.message ?? e ?? 'error')
+
+/** one step per (host state, data, key): STATE, the sink and EFFECT of one action share it */
+const once = <R>(f: (st: any, d: any, k: string) => R) => {
+  let a: any[] = [], r: R
+  return (st: any, d: any, k: string): R => a[0] === st && a[1] === d && a[2] === k ? r : (a = [st, d, k], r = f(st, d, k))
+}
+
+/** a click on a container control (render's `control()` data attributes) */
+const controlOf = (e: any) => {
+  const el = e?.ownerTarget || e?.target?.closest?.('[data-compose-control]') || e?.target
+  const ds = el?.dataset || {}
+  if (!ds.composeControl || !ds.composeKey) return null
+  let value: any = ds.composeValue
+  try { value = JSON.parse(value) } catch (_) { /* a plain string */ }
+  return {key: ds.composeKey, name: ds.composeControl, value, at: ds.composeAt, scope: ds.composeScope}
+}
+
+/**
+ * compose(catalog, { backend, form?, prompt?, key? }): the behavior (a `uses` value). Types:
+ * src/ai.d.ts.
+ */
+export function composeBehavior(catalog: Catalog, options: any = {}): any {
+  const {backend, form, prompt: promptSel, key: lane = 'compose'} = options
+  if (!backend || typeof backend.sink != 'string' || typeof backend.start != 'function' || typeof backend.reply != 'function') {
+    fail('SYG681', 'compose', 'compose(catalog, { backend }) needs a backend', 'Pass compose.decisions({ model }) or compose.llm({ model })')
+  }
+  if (!catalog || typeof catalog.render != 'function') fail('SYG681', 'compose', 'compose(catalog, …) needs a catalog made by defineCatalog()', 'Pass defineCatalog({ parts })')
+  const S: string = backend.sink
+  // mine: the pending steps this use made, so composeWith picks its backend among the catalog's uses
+  const entry = {backend, lane, keys: new Set<string>(), mine: new WeakSet<object>()}
+  const own = (p: any) => { if (p && typeof p == 'object') entry.mine.add(p); return p }
+  if (!uses.has(catalog)) uses.set(catalog, [])
+  uses.get(catalog)!.push(entry)
+  const names = (k: string) => ({ok: k + '.REPLY', error: k + '.FAILED', delta: k + '.DELTA', key: lane})
+  const rekey = (l: Layout, prev: Layout | null): Layout => (prev ? fromTree(catalog, toTree(l), prev) : l)
+
+  const start = once((st, d, k) => {
+    const s = st?.[k]
+    if (!s) return null
+    const raw = typeof d == 'string' ? d : d && typeof d == 'object' && typeof d.prompt == 'string' ? d.prompt : s.prompt
+    const prompt = String(raw ?? '').trim()
+    if (!prompt) return null
+    entry.keys.add(k)
+    const base = {...s, prompt, preview: null, decisions: null, error: null}
+    try {
+      const r = backend.start({catalog, state: st, prompt, previous: d?.fresh ? null : s.layout, names: names(k)})
+      return {slice: {...base, status: 'composing', pending: own(r.pending ?? {})}, request: r.request}
+    } catch (e) {
+      return {slice: {...base, status: 'error', pending: null, error: message(e)}}
+    }
+  })
+
+  const reply = once((st, d, k) => {
+    const s = st?.[k]
+    if (!s?.pending) return null
+    let r: any
+    try { r = backend.reply({catalog, state: st, pending: s.pending, reply: d, names: names(k)}) || {} } catch (e) {
+      return {slice: {...s, status: 'error', preview: null, pending: null, error: message(e)}}
+    }
+    const decisions = r.decisions !== undefined ? r.decisions : s.decisions
+    // a reply that isn't a valid layout (even after the backend's repair): as FAILED
+    if (r.error != null) return {slice: {...s, status: 'error', preview: null, pending: null, decisions, error: message(r.error)}}
+    if (r.request !== undefined) {
+      const preview = r.preview ? (r.keyed ? r.preview : rekey(r.preview, s.layout)) : s.preview
+      return {slice: {...s, status: preview ? 'preview' : 'composing', preview, pending: own(r.pending ?? s.pending), decisions}, request: r.request}
+    }
+    if (r.layout) {
+      // `keyed` (B-4 edits): the backend kept the previous keys itself (moves, new rows): not re-keyed
+      const layout = r.keyed ? r.layout : rekey(r.layout, s.layout)
+      return {slice: {...s, status: 'done', layout, preview: null, pending: null, decisions, error: null}, done: layout}
+    }
+    if (r.unavailable || r.layout === null) return {slice: {...s, status: 'unavailable', preview: null, pending: null, decisions}}
+    return {slice: {...s, status: 'error', preview: null, pending: null, decisions, error: 'the backend gave no layout'}}
+  })
+
+  const host = (step: (st: any, d: any, k: string) => any) =>
+    (st: any, d: any, _n: any, _p: any, _o: any, k: string) => { const r = step(st, d, k); return r?.slice ? {...st, [k]: r.slice} : ABORT }
+  const sink = (step: (st: any, d: any, k: string) => any) =>
+    (_s: any, d: any, _n: any, p: any, _o: any, k: string) => { const r = step(p?.state, d, k); return r?.request !== undefined ? r.request : ABORT }
+
+  // `prompt` (a selector) must not set the slice's prompt (defineBehavior merges options naming
+  // initialState keys): the factory gets the other options
+  const {prompt: _selector, ...rest} = options
+  const controls = Object.values(catalog.containers || {}).some((c: any) => typeof c.decl?.render == 'function')
+  return defineBehavior({
+    initialState: {prompt: '', status: 'idle', layout: null, preview: null, pending: null, decisions: null, error: null, ui: {}, local: {}},
+    intent: (so: any, _o: any, k: string) => {
+      const {DOM} = so
+      if (!DOM) return {}
+      return {
+        ...(promptSel && {PROMPT: DOM.select(promptSel).events('input').map((e: any) => e.target.value)}),
+        ...(form && {COMPOSE: DOM.select(form).events('submit', {preventDefault: true}).mapTo(undefined)}),
+        // only when a container has its own render (the built-in views render no controls): else
+        // the selector never matches (SYG103 in dev)
+        ...(controls && {CONTROL: DOM.select('[data-compose-control]').events('click').map(controlOf)
+          .filter((c: any) => c && c.scope === undefined && (c.at === undefined || c.at === k))
+          .map(({key, name, value}: any) => ({key, name, value}))}),
+      }
+    },
+    model: {
+      PROMPT: (s: any, p: any) => typeof p == 'string' && p !== s.prompt ? {...s, prompt: p} : ABORT,
+      COMPOSE: {HOST: host(start), [S]: sink(start)},
+      REPLY: {
+        HOST: host(reply),
+        [S]: sink(reply),
+        EFFECT: (_s: any, d: any, next: any, p: any, _o: any, k: string) => { const r = reply(p?.state, d, k); if (r?.done) next('DONE', r.done) },
+      },
+      DELTA: {
+        HOST: (st: any, d: any, _n: any, _p: any, _o: any, k: string) => {
+          const s = st[k]
+          if (!s?.pending || typeof backend.delta != 'function') return ABORT
+          let r: any
+          try { r = backend.delta({catalog, state: st, pending: s.pending, delta: d}) } catch (_) { return ABORT }
+          return r?.preview ? {...st, [k]: {...s, status: 'preview', preview: r.keyed ? r.preview : rekey(r.preview, s.layout)}} : ABORT
+        },
+      },
+      FAILED: (s: any, d: any) => s.pending ? {...s, status: 'error', preview: null, pending: null, error: message(d?.error ?? d)} : ABORT,
+      SET_LAYOUT: {
+        HOST: (st: any, d: any, _n: any, _p: any, _o: any, k: string) => {
+          const layout = d == null ? null : finish(catalog, d, st)
+          return {...st, [k]: {...st[k], layout, preview: null, pending: null, error: null, status: layout ? 'done' : 'idle'}}
+        },
+      },
+      REMOVE: {
+        HOST: (st: any, key: any, _n: any, _p: any, _o: any, k: string) => {
+          const s = st[k], l = s?.layout
+          if (!l?.nodes || typeof key != 'string' || !Object.prototype.hasOwnProperty.call(l.nodes, key) || key == l.root) return ABORT
+          return {...st, [k]: {...s, layout: finish(catalog, removeNode(l, key), st)}}
+        },
+      },
+      CONTROL: (s: any, c: any) => c && typeof c.key == 'string' && typeof c.name == 'string'
+        ? {...s, ui: {...s.ui, [c.key]: {...s.ui?.[c.key], [c.name]: c.value}}} : ABORT,
+      DONE: () => ABORT,
+    },
+  })(rest)
+}

package/src/extra/ai/compose/catalog.ts

@@ -0,0 +1,211 @@
+/*
+ * PLAN-9 K-1: defineCatalog(decl), the declaration both backends compose from (phase1-contract.md,
+ * PROPOSAL.md §1). Normalizes and validates the parts and containers (one id namespace; the
+ * built-ins `page`, the root, and `row`, side by side: `{ min: 2, max: 4, accepts: 'leaves' }`;
+ * `rows: false` (or `containers: { row: false }`) opts out of it), and returns the Catalog: `parts`,
+ * `containers`, `get(id)`, `options(state)` (every selectable option, a record part once per
+ * record), `records(part, state)`, `finish(layout, state)` (K-3), `render(slice, state, opts)`
+ * (K-2), `description` (the page's label, with `containers.page.description`), `categories`
+ * (`{ id: description }`, for a category prefilter; parts name one in `category`), `rows`,
+ * `guidance`, `limits` (`{ maxParts: 12, maxDepth: 4 }`) and `examples`. Containers carry
+ * `description`, `in`, `slots`, `minSlots`, `min` / `max` (children per slot), `accepts: 'leaves'`,
+ * `arranged`, `direction` and `params`.
+ *
+ * Errors: an id that can't be a node key (empty, or with ':', '~', '/'), a part id that is also a
+ * container's, a part named `page` / `row`, a malformed param and two record params on a part throw
+ * at the call (an authoring mistake). The rest are dev diagnostics (./diag.ts): SYG161 (a
+ * container's `render` is a component with a model: it is still called as a view), SYG162 (a part
+ * with neither `component` nor `render`: it renders nothing), SYG450 (`in` names an unknown
+ * container or slot: that entry is dropped), SYG250 (an unknown companion: dropped) and, when the
+ * records are read, SYG252.
+ */
+import {createElement as h} from '../../../pragma/index'
+import {dev} from './diag'
+import {finish} from './layout'
+import {renderLayout} from './render'
+import {askKit} from './ask'
+import type {Catalog, Container, Entry, Option, Param, Part} from './types'
+
+const BAD_ID = /^$|[:~/]/
+const fail = (msg: string): never => { throw new Error(`[Sygnal] defineCatalog: ${msg}`) }
+
+const pageView = ({slots}: any) => h('div', {className: 'compose-page'}, slots.default)
+const rowView = ({slots}: any) => h('div', {className: 'compose-row'}, slots.default)
+/** a container declared without `render`: its slots in order */
+const slotsView = ({slots}: any) => h('div', {className: 'compose-container'}, Object.keys(slots).map(s => slots[s]))
+
+function param(part: string, name: string, p: any): Param {
+  const where = `part '${part}', param '${name}'`
+  if (!p || typeof p != 'object') return fail(`${where} is not an object`)
+  if (typeof p.from == 'function') return {kind: 'record', from: p.from, label: p.label}
+  if (p.options && typeof p.options == 'object') {
+    const keys = Object.keys(p.options)
+    if (!keys.length) fail(`${where} has no options`)
+    if (p.default !== undefined && !keys.includes(String(p.default))) fail(`${where}: the default '${p.default}' is not one of its options`)
+    return {kind: 'options', options: p.options, default: p.default ?? keys[0], label: p.label, ask: p.ask}
+  }
+  if (p.type == 'number') {
+    if (p.default !== undefined && typeof p.default != 'number') fail(`${where}: the default is not a number`)
+    return {kind: 'number', min: p.min, max: p.max, default: p.default, bins: p.bins, label: p.label}
+  }
+  if (p.type == 'text') return {kind: 'text', maxLength: p.maxLength, default: p.default, required: !!p.required, label: p.label}
+  if (p.type == 'list') return {kind: 'list', items: p.items, min: p.min, max: p.max, required: !!p.required, default: p.default, label: p.label}
+  return fail(`${where} needs \`options\`, \`from\`, or \`type: 'number' | 'text' | 'list'\``)
+}
+
+const isComponent = (f: any) => typeof f == 'function' && !!(f.model || f.intent || f.initialState || f.uses)
+
+function container(id: string, d: any): Container {
+  const slots = d.slots && typeof d.slots == 'object' && Object.keys(d.slots).length ? d.slots : {default: null}
+  let render = d.render
+  if (isComponent(render)) {
+    dev('SYG161', 'defineCatalog', `container '${id}': its render is a component with a model or intent; containers are view functions (a component would own the parts, so the host's CHILD.select and lenses stop reaching them). It is called as a view; its model doesn't run`, 'error')
+  }
+  if (typeof render != 'function') render = id == 'page' ? pageView : id == 'row' ? rowView : slotsView
+  // min / max: children per slot (non-negative integers, min <= max); accepts: 'leaves' (no nested
+  // containers). An invalid value is ignored (SYG450, like an invalid `in`)
+  const count = (k: string) => {
+    const v = d[k]
+    if (v == null) return undefined
+    if (Number.isInteger(v) && v >= 0) return v
+    dev('SYG450', 'defineCatalog', `container '${id}': \`${k}\` must be a non-negative integer (children per slot); it is ignored`)
+  }
+  let min = count('min'), max = count('max')
+  if (min != null && max != null && min > max) {
+    dev('SYG450', 'defineCatalog', `container '${id}': \`min\` ${min} is above \`max\` ${max}; both are ignored`)
+    min = max = undefined
+  }
+  let accepts = d.accepts
+  if (accepts != null && accepts != 'leaves') {
+    dev('SYG450', 'defineCatalog', `container '${id}': \`accepts\` takes only 'leaves'; it is ignored`)
+    accepts = undefined
+  }
+  const params: Record<string, Param> = {}
+  for (const k in d.params || {}) {
+    const p = params[k] = param(id, k, d.params[k])
+    if (p.kind == 'record') fail(`container '${id}', param '${k}': containers take no record params`)
+  }
+  return {id, kind: 'container', slots, slotNames: Object.keys(slots), minSlots: d.minSlots, min, max, accepts, params,
+    arranged: !!d.arranged, direction: d.direction ?? (id == 'row' ? 'row' : undefined), description: d.description, render, in: d.in ?? ['page'], decl: d}
+}
+
+function part(id: string, d: any): Part {
+  if (!d || typeof d != 'object') return fail(`part '${id}' is not an object`)
+  if (typeof d.component != 'function' && typeof d.render != 'function') {
+    dev('SYG162', 'defineCatalog', `part '${id}' has neither a component nor a render function; it renders nothing`, 'error')
+  }
+  const params: Record<string, Param> = {}
+  let record: string | undefined
+  for (const k in d.params || {}) {
+    const p = params[k] = param(id, k, d.params[k])
+    if (p.kind == 'record') {
+      if (record) fail(`part '${id}' has two record params ('${record}', '${k}'); a part takes at most one`)
+      record = k
+    }
+  }
+  const pin = d.pin == 'start' || d.pin == 'end' ? d.pin : undefined
+  return {id, kind: 'part', component: typeof d.component == 'function' ? d.component : undefined,
+    render: typeof d.component != 'function' && typeof d.render == 'function' ? d.render : undefined,
+    props: d.props, description: String(d.description ?? id), state: d.state, local: d.local, hasLocal: 'local' in d,
+    params, record, in: d.in ?? ['page'], group: d.group, maxUses: Math.max(1, Number(d.maxUses) || 1),
+    required: !!d.required, pin, companions: Array.isArray(d.companions) ? d.companions : [], category: d.category,
+    result: !!d.result, decl: d}
+}
+
+/** 'container' | 'container:slot' entries → 'container:slot' (SYG450 for an unknown one) */
+function places(e: Entry, containers: Record<string, Container>): string[] {
+  const out: string[] = []
+  for (const x of Array.isArray(e.in) ? e.in : [e.in]) {
+    const [c, s] = String(x).split(':')
+    const ct = containers[c]
+    if (!ct || c == 'row' || (s !== undefined && !ct.slotNames.includes(s))) {
+      dev('SYG450', 'defineCatalog', `'${e.id}': \`in\` names ${!ct ? `an unknown container '${c}'` : c == 'row' ? "'row' (a row is placed where its parts may go)" : `an unknown slot '${s}' of '${c}'`}; that entry is ignored`)
+      continue
+    }
+    for (const n of s === undefined ? ct.slotNames : [s]) if (!out.includes(c + ':' + n)) out.push(c + ':' + n)
+  }
+  return out.length ? out : ['page:default']
+}
+
+/** a record part's records, validated (SYG252: not an array of `{ value }`, or `from` threw) */
+function records(cat: Catalog, p: any, state: any): any[] {
+  const part: Part | undefined = typeof p == 'string' ? cat.parts[p] : p
+  const rp = part?.record && (part.params[part.record] as any)
+  if (!rp) return []
+  let list: any
+  try { list = rp.from(state) } catch (e: any) {
+    dev('SYG252', 'catalog', `part '${part!.id}': the record param's from() threw (${e?.message ?? e}); no records`, 'warn', cat, part!.id + 'threw')
+    return []
+  }
+  const ok = (r: any) => r && typeof r == 'object' && (typeof r.value == 'string' || (typeof r.value == 'number' && isFinite(r.value)))
+  if (!Array.isArray(list) || !list.every(ok)) {
+    dev('SYG252', 'catalog', `part '${part!.id}': the record param's from() must return an array of { value, name?, aliases?, description? } (value: a string or a number); ${Array.isArray(list) ? 'entries without one are skipped' : 'no records'}`, 'warn', cat, part!.id)
+    return Array.isArray(list) ? list.filter(ok) : []
+  }
+  return list
+}
+
+/**
+ * defineCatalog({ parts, containers?, guidance?, limits?, examples? }): the normalized, validated
+ * catalog. Types: src/ai.d.ts.
+ */
+export function defineCatalog(decl: any = {}): any {
+  const containers: Record<string, Container> = {}
+  const parts: Record<string, Part> = {}
+  const dc = decl.containers || {}
+  containers.page = container('page', {...dc.page, in: [], slots: {default: null}})
+  // the built-in row, unless the catalog opts out: `rows: false` (canonical; `containers: { row: false }` too)
+  const rows = decl.rows !== false && dc.row !== false
+  if (rows) containers.row = container('row', {direction: 'row', min: 2, max: 4, accepts: 'leaves', ...dc.row, slots: {default: null}})
+  for (const id in dc) {
+    if (id == 'page' || id == 'row') continue
+    if (BAD_ID.test(id)) fail(`the container id '${id}' can't be a node key (no ':', '~' or '/')`)
+    containers[id] = container(id, dc[id] || {})
+  }
+  for (const id in decl.parts || {}) {
+    if (BAD_ID.test(id)) fail(`the part id '${id}' can't be a node key (no ':', '~' or '/')`)
+    if (containers[id] || id == 'row') fail(`'${id}' is both a part and a container (they share one id namespace${id == 'page' || id == 'row' ? `; '${id}' is built in` : ''})`)
+    parts[id] = part(id, decl.parts[id])
+  }
+  const cat: any = {
+    parts,
+    containers,
+    description: decl.description,
+    categories: decl.categories && typeof decl.categories == 'object' ? decl.categories : {},
+    rows,
+    guidance: decl.guidance,
+    limits: {maxParts: 12, maxDepth: 4, ...decl.limits},
+    examples: Array.isArray(decl.examples) ? decl.examples : [],
+    get: (id: string): Entry | undefined => Object.prototype.hasOwnProperty.call(parts, id) ? parts[id]
+      : Object.prototype.hasOwnProperty.call(containers, id) ? containers[id] : undefined,
+    records: (p: any, state: any) => records(cat, p, state),
+    options: (state: any): Option[] => {
+      const out: Option[] = []
+      for (const id in parts) {
+        const p = parts[id]
+        if (!p.record) { out.push({option: id, part: id, description: p.description}); continue }
+        for (const r of records(cat, p, state)) {
+          out.push({option: `${id}:${r.value}`, part: id, params: {[p.record]: r.value},
+            description: `${p.description}: ${r.description ?? r.name ?? r.value}`})
+        }
+      }
+      return out
+    },
+    finish: (layout: any, state?: any) => finish(cat, layout, state),
+    render: (slice: any, state: any, opts?: any) => renderLayout(cat, slice, state, opts),
+  }
+  for (const id in containers) if (id != 'page') containers[id].in = places(containers[id], containers)
+  if (rows) containers.row.in = []
+  for (const id in parts) {
+    const p = parts[id]
+    p.in = places(p, containers)
+    p.companions = p.companions.filter(c => {
+      if (parts[c] && c != id) return true
+      dev('SYG250', 'defineCatalog', `part '${id}': the companion '${c}' is not a part of this catalog; it is ignored`)
+      return false
+    })
+  }
+  // H-2: what chat({ ask: { catalog } }) runs on (so an app with chat and no catalog carries none of it)
+  Object.defineProperty(cat, '_ask', {value: askKit})
+  return cat as Catalog
+}