@worca/app 1.3.0 → 1.4.0

package/src/shared/forms/answer.mjs

@@ -0,0 +1,164 @@
+// src/shared/forms/answer.mjs
+// Turning raw input into the answer an agent resumes with (spec §5 gate 3, D10), and
+// finding the files an ask references (§7). The browser calls collectAnswer for live
+// feedback; the server calls the SAME function and its verdict is the one that counts.
+import { validate, resolveAnswerSchema } from './schema.mjs';
+import { resolvePath } from './paths.mjs';
+import { walkLayout, visibleFields } from './layout.mjs';
+import { widgetClass } from './catalog.mjs';
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const clone = (v) => JSON.parse(JSON.stringify(v));
+const isMissing = (v) => v === undefined || v === null || v === '';
+/** Star-slash-star, spelled without the literal: that sequence would close a block comment. */
+const ANY_MIME = ['*', '*'].join('/');
+const rowsOf = (item, data) => {
+  const rows = typeof item.bind === 'string' ? resolvePath(item.bind, { data }) : [];
+  return Array.isArray(rows) ? rows.filter(isObject) : [];
+};
+/** The ids a row widget can answer with. Gate 1 makes `id` a required text where it can see the
+ *  row schema; opaque rows (C3) arrive unchecked, and a row with no text id is nobody's item. */
+const idsOf = (item, data) => rowsOf(item, data).map((r) => (Object.hasOwn(r, 'id') ? r.id : undefined))
+  .filter((id) => typeof id === 'string' && id !== '');
+
+/** Input items by field, effective (post-fallback) form. */
+function inputItems(layout) {
+  const out = new Map();
+  walkLayout(layout, (raw, eff) => {
+    if (eff && widgetClass(eff.widget, eff) === 'input' && typeof eff.field === 'string' && !out.has(eff.field)) out.set(eff.field, eff);
+  });
+  return out;
+}
+
+/** Visibility depends on values and hidden values are dropped, so settle to a fixpoint. It always
+ *  ends: a round either drops nothing (done) or leaves strictly fewer values. A fixed cap (it was
+ *  6) let the tail of a longer `when` chain reach the agent although it was hidden. */
+function settle(layout, values) {
+  let cur = values;
+  for (;;) {
+    const vis = new Set(visibleFields(layout, cur));
+    const next = Object.fromEntries(Object.entries(cur).filter(([k]) => vis.has(k)));
+    if (Object.keys(next).length === Object.keys(cur).length) return { values: next, visible: vis };
+    cur = next;
+  }
+}
+
+function candidate(item, schema, data, required) {
+  if (schema.default !== undefined) return clone(schema.default);
+  const need = required || (schema.minItems || 0) > 0;
+  if (item.widget === 'rank') return idsOf(item, data);
+  if (item.widget === 'review-list') {
+    const verdict = schema.items.properties.verdict;
+    const first = verdict.default !== undefined ? verdict.default : verdict.enum[0];
+    return idsOf(item, data).map((id) => ({ id, verdict: first }));
+  }
+  if (!need) return undefined;
+  if (schema.type === 'array') {
+    const pool = (schema.items && schema.items.enum) || idsOf(item, data);
+    return pool.slice(0, Math.max(1, schema.minItems || 0));
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length) return schema.enum[0];
+  if (Array.isArray(item.suggest) && item.suggest.length) return item.suggest[0];
+  if (item.widget === 'table-select' || item.widget === 'gallery') return idsOf(item, data)[0];
+  if (schema.type === 'boolean') return false;
+  if (schema.type === 'number' || schema.type === 'integer') return schema.minimum !== undefined ? schema.minimum : 0;
+  return undefined;   // free text with no default: the form author must supply one (gate 1 `bad-auto`)
+}
+
+/** D10: the answer auto mode (`--yes`) gives. Per field: `default`, else `defaultFrom`,
+ *  else the first choice, else the widget's natural value. Hidden fields are dropped. */
+export function autoAnswer(def, data) {
+  const schema = resolveAnswerSchema(def.answer, data);
+  const required = new Set(schema.required || []);
+  const values = {};
+  for (const [field, item] of inputItems(def.layout)) {
+    const s = isObject(schema.properties) && Object.hasOwn(schema.properties, field) ? schema.properties[field] : null;
+    if (!s) continue;
+    const v = candidate(item, s, data, required.has(field));
+    if (!isMissing(v)) values[field] = v;
+  }
+  return settle(def.layout, values).values;
+}
+
+function stripItem(schema, v) {
+  if (schema.type === 'array' && Array.isArray(v) && schema.items) return v.map((x) => stripItem(schema.items, x));
+  if (schema.type === 'object' && isObject(v) && isObject(schema.properties)) {
+    return Object.fromEntries(Object.entries(v).filter(([k, x]) => Object.hasOwn(schema.properties, k) && !isMissing(x)).map(([k, x]) => [k, stripItem(schema.properties[k], x)]));
+  }
+  return v;
+}
+
+/** Gate 3 core. Drops unknown keys, empty values and `when`-hidden fields, makes
+ *  `required` apply only to visible fields, then validates. `resolvedSchema` is
+ *  `resolveAnswerSchema(def.answer, data)`. → { values, errors } */
+export function collectAnswer(def, resolvedSchema, rawValues) {
+  const props = isObject(resolvedSchema) && isObject(resolvedSchema.properties) ? resolvedSchema.properties : {};
+  // Own declared keys only, and built with fromEntries: `known[k] = v` would turn a posted
+  // "__proto__" into the object's prototype, and `when` would then read values nobody sent.
+  const known = Object.fromEntries(Object.entries(isObject(rawValues) ? rawValues : {})
+    .filter(([k, v]) => Object.hasOwn(props, k) && !isMissing(v))
+    .map(([k, v]) => [k, stripItem(props[k], clone(v))]));
+  const { values, visible } = settle(def.layout, known);
+  const required = isObject(resolvedSchema) && Array.isArray(resolvedSchema.required) ? resolvedSchema.required : [];
+  const errors = validate({ ...resolvedSchema, required: required.filter((f) => visible.has(f)) }, values).errors;
+  // A reorder and a per-item review name each item once. That is the widget's rule, and no
+  // schema keyword can state it for rows: `uniqueItems` compares whole objects, so two verdicts
+  // for one id would reach the agent. Reported once, also where `uniqueItems` already said so.
+  for (const [field, item] of inputItems(def.layout)) {
+    const v = Object.hasOwn(values, field) ? values[field] : undefined;
+    if ((item.widget !== 'rank' && item.widget !== 'review-list') || !Array.isArray(v)) continue;
+    const ids = v.map((x) => (isObject(x) ? x.id : x));
+    if (new Set(ids).size !== ids.length && !errors.some((e) => e.path === field && e.code === 'unique')) {
+      errors.push({ path: field, code: 'unique', message: 'Each item may appear only once.' });
+    }
+  }
+  return { values, errors };
+}
+
+/** Gate 2 core (spec §5): is this run-time `data` askable? It must pass the data schema, and
+ *  the auto answer built from it must pass gate 3 — so D10 holds for the data an agent really
+ *  wrote, not only for the form's `example`. An empty `enumFrom` on a required choice fails
+ *  here, and so does a required field whose `defaultFrom` source the agent left out. → { ok, errors } */
+export function checkAskData(def, data) {
+  const shape = validate(def.data, data);
+  if (!shape.ok) return { ok: false, errors: shape.errors.map((e) => ({ ...e, path: e.path ? `data.${e.path}` : 'data' })) };
+  const auto = collectAnswer(def, resolveAnswerSchema(def.answer, data), autoAnswer(def, data));
+  const errors = auto.errors.map((e) => ({ path: `answer.${e.path}`, code: 'bad-auto',
+    message: `unattended runs could not answer "${e.path}" with this data: ${e.message}` }));
+  return { ok: errors.length === 0, errors };
+}
+
+/** Every `type: 'file'` value in an agent's data → [{ path, rel, accept }]. `path` is
+ *  a concrete location ('data.images[0].file', the path a gate-2 error names); `rel` is the
+ *  run-relative path the agent wrote. Document order: depth-first, array index ascending —
+ *  P2 uses the position as the served file index. */
+export function fileRefs(dataSchema, data) {
+  const out = [];
+  (function walk(schema, v, path) {
+    if (!isObject(schema) || v === undefined || v === null) return;
+    if (schema.type === 'file') { if (typeof v === 'string') out.push({ path, rel: v, accept: Array.isArray(schema.accept) ? schema.accept : [] }); return; }
+    if (schema.type === 'array' && Array.isArray(v)) v.forEach((x, i) => walk(schema.items, x, `${path}[${i}]`));
+    if (schema.type === 'object' && isObject(v) && isObject(schema.properties)) {
+      for (const [k, s] of Object.entries(schema.properties)) if (Object.hasOwn(v, k)) walk(s, v[k], `${path}.${k}`);
+    }
+  })(dataSchema, data, 'data');
+  return out;
+}
+
+/** The mime patterns a form may display, from its data SCHEMA alone (no instance data): what
+ *  the plugin consent screen lists before anything is installed or run. Deduped and sorted; a
+ *  `file` with no `accept` contributes the any-type pattern. */
+export function fileAccepts(dataSchema) {
+  const out = new Set();
+  (function walk(schema) {
+    if (!isObject(schema)) return;
+    if (schema.type === 'file') {
+      const accept = Array.isArray(schema.accept) && schema.accept.length ? schema.accept : [ANY_MIME];
+      for (const a of accept) out.add(a);
+      return;
+    }
+    if (schema.items) walk(schema.items);
+    if (isObject(schema.properties)) for (const s of Object.values(schema.properties)) walk(s);
+  })(dataSchema);
+  return [...out].sort();
+}

package/src/shared/forms/catalog.mjs

@@ -0,0 +1,91 @@
+// src/shared/forms/catalog.mjs
+// The host-owned widget catalog for agent ask forms (ask-forms spec §6.1). A form
+// names widgets by string; only names listed here ever render. Pure and isomorphic:
+// the registry, the plugin validator, the server and the browser read the same tables.
+
+/** Bumped when a widget is added. A layout item may say `requires: { askCatalog: n }`. */
+export const ASK_CATALOG_VERSION = 1;
+
+export const INPUT_WIDGETS = Object.freeze(['text', 'textarea', 'number', 'slider', 'toggle', 'date',
+  'select', 'multiselect', 'rank', 'table-select', 'review-list', 'gallery']);
+export const DISPLAY_WIDGETS = Object.freeze(['markdown', 'callout', 'image', 'gallery', 'compare', 'pdf',
+  'code', 'diff', 'table', 'json', 'file-list', 'media']);
+export const LAYOUT_WIDGETS = Object.freeze(['group', 'columns', 'tabs']);
+
+/** Limits, verbatim from the spec (§3, §7). */
+export const ASK_LIMITS = Object.freeze({
+  formsPerAgent: 8, askBlockBytes: 65536, filesPerAsk: 24,
+  fileBytes: 26214400, askBytes: 104857600, dataBytes: 262144,
+});
+
+/** The layout-item vocabulary (spec §6.2): the keys every item may carry, then each widget's own.
+ *  Gate 1 refuses anything else, and the renderer reads nothing else — one table, no drift. */
+export const COMMON_ITEM_KEYS = Object.freeze(['widget', 'field', 'bind', 'label', 'help', 'when', 'requires', 'fallback']);
+export const LAYOUT_ITEM_KEYS = Object.freeze({
+  text: Object.freeze(['placeholder', 'mono']),
+  textarea: Object.freeze(['placeholder', 'rows']),
+  number: Object.freeze(['unit', 'placeholder']),
+  slider: Object.freeze(['unit', 'minLabel', 'maxLabel']),
+  toggle: Object.freeze([]),
+  date: Object.freeze([]),
+  select: Object.freeze(['style', 'options', 'labels', 'descriptions', 'tones', 'suggest']),
+  multiselect: Object.freeze(['style', 'options', 'labels', 'descriptions']),
+  rank: Object.freeze(['titleKey', 'metaKey']),
+  'table-select': Object.freeze(['columns']),
+  'review-list': Object.freeze(['titleKey', 'bodyKey', 'metaKey', 'labels', 'tones', 'notePlaceholder']),
+  gallery: Object.freeze(['captionKey', 'fileKey']),
+  markdown: Object.freeze([]),
+  callout: Object.freeze(['text', 'title', 'tone']),
+  image: Object.freeze(['caption']),
+  compare: Object.freeze(['before', 'after', 'beforeLabel', 'afterLabel']),
+  pdf: Object.freeze([]),
+  media: Object.freeze([]),
+  code: Object.freeze(['name', 'lang']),
+  diff: Object.freeze(['name']),
+  table: Object.freeze(['columns']),
+  json: Object.freeze([]),
+  'file-list': Object.freeze(['fileKey', 'noteKey']),
+  group: Object.freeze(['title', 'children']),
+  columns: Object.freeze(['columns']),
+  tabs: Object.freeze(['tabs']),
+});
+
+const INPUT = new Set(INPUT_WIDGETS);
+const DISPLAY = new Set(DISPLAY_WIDGETS);
+const LAYOUT = new Set(LAYOUT_WIDGETS);
+
+/** The answer-schema types each input widget can fill. */
+const PAIRING = Object.freeze({
+  text: ['string'], textarea: ['string'], date: ['string'],
+  number: ['number', 'integer'], slider: ['number', 'integer'],
+  toggle: ['boolean'],
+  select: ['string', 'number', 'integer'],
+  multiselect: ['array'], rank: ['array'], 'review-list': ['array'],
+  'table-select': ['string', 'array'], gallery: ['string', 'array'],
+});
+
+export const isKnownWidget = (name) => INPUT.has(name) || DISPLAY.has(name) || LAYOUT.has(name);
+
+/** 'input' | 'display' | 'layout' | null. `gallery` is the one name in two classes:
+ *  with a `field` it collects a pick, without one it only shows. */
+export function widgetClass(name, item) {
+  if (name === 'gallery') return item && typeof item.field === 'string' ? 'input' : 'display';
+  if (INPUT.has(name)) return 'input';
+  if (DISPLAY.has(name)) return 'display';
+  if (LAYOUT.has(name)) return 'layout';
+  return null;
+}
+
+/** Can this input widget fill a field of this answer schema? */
+export function widgetAcceptsType(name, schema) {
+  const types = Object.hasOwn(PAIRING, name) ? PAIRING[name] : null;
+  if (!types || !schema || typeof schema !== 'object') return false;
+  if (!types.includes(schema.type)) return false;
+  if (name === 'date') return schema.format === 'date';
+  if (name === 'review-list') {
+    const p = schema.items && schema.items.type === 'object' && schema.items.properties;
+    return Boolean(p && p.id && p.id.type === 'string' && p.verdict && Array.isArray(p.verdict.enum) && p.verdict.enum.length > 0);
+  }
+  if (name === 'multiselect' || name === 'rank') return Boolean(schema.items && schema.items.type === 'string');
+  return true;
+}

package/src/shared/forms/form-def.mjs

@@ -0,0 +1,290 @@
+// src/shared/forms/form-def.mjs
+// Gate 1 (spec §5): is a declared form well-formed? Run by the agent registry (skip +
+// report), the plugin validator, the agent store (422) and the Agents view (live hints).
+// The last two checks are executable: the form's own `example` must pass its data
+// schema, and the auto answer built from it must pass gate 3 — a declaration proves itself.
+import { ASK_LIMITS, COMMON_ITEM_KEYS, LAYOUT_ITEM_KEYS, isKnownWidget, widgetClass, widgetAcceptsType } from './catalog.mjs';
+import { isValidPath, schemaAtPath } from './paths.mjs';
+import { checkDialect, validate, resolveAnswerSchema } from './schema.mjs';
+import { walkLayout } from './layout.mjs';
+import { autoAnswer, collectAnswer } from './answer.mjs';
+
+export const FORM_ID_RE = /^[a-z][a-z0-9-]{0,47}$/;
+export const FORM_SURFACES = Object.freeze(['any', 'web']);
+const MAX_TITLE = 120;
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const isScalar = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+const err = (path, code, message) => ({ path, code, message });
+
+/** Layout keys that hold a data path, per widget. */
+const BINDS = Object.freeze({ compare: ['before', 'after'] });
+const bindKeys = (item) => BINDS[item.widget] || (item.bind !== undefined ? ['bind'] : []);
+/** Widgets that cannot render without a data path. */
+const NEEDS_BIND = new Set(['markdown', 'image', 'gallery', 'pdf', 'code', 'diff', 'table', 'json', 'file-list', 'media',
+  'rank', 'table-select', 'review-list']);
+/** Widgets that draw ROWS: their `bind` lands on a list of objects. (`table` is not here: spec
+ *  §6.2 lets the text display widgets bind a `file` instead.) */
+const ROW_WIDGETS = new Set(['rank', 'table-select', 'review-list', 'gallery', 'file-list']);
+/** Widgets that show ONE file. Only a `file` value is snapshotted at ask time (spec §7), so a
+ *  path that lands on anything else leaves them nothing to show. */
+const FILE_WIDGETS = new Set(['image', 'pdf', 'media', 'compare']);
+
+/** What a layout key may HOLD. catalog.mjs says which keys exist; this says what is in them, so
+ *  neither the renderer nor the text projection ever meets a shape it cannot read. */
+const TEXT_KEYS = new Set(['label', 'help', 'placeholder', 'unit', 'minLabel', 'maxLabel', 'titleKey', 'bodyKey', 'metaKey',
+  'captionKey', 'fileKey', 'noteKey', 'notePlaceholder', 'text', 'title', 'tone', 'caption', 'beforeLabel', 'afterLabel',
+  'name', 'lang', 'style']);
+const MAP_KEYS = new Set(['labels', 'descriptions', 'tones']);
+const OPTION_KEYS = Object.freeze(['from', 'value', 'label', 'description']);
+const STYLES = Object.freeze({ select: ['cards', 'segmented', 'dropdown'], multiselect: ['rows', 'chips'] });
+const isText = (v) => typeof v === 'string';
+const optText = (v) => v === undefined || isText(v);
+
+/** → string[]: one message per key of `item` that holds the wrong kind of value. */
+function valueErrors(item) {
+  const out = [];
+  const w = item.widget;
+  for (const [k, v] of Object.entries(item)) {
+    if (TEXT_KEYS.has(k) && !isText(v)) out.push(`"${k}" must be text`);
+    if (MAP_KEYS.has(k) && !(isObject(v) && Object.values(v).every(isText))) out.push(`"${k}" is { value: text }`);
+  }
+  if (isText(item.style) && Object.hasOwn(STYLES, w) && !STYLES[w].includes(item.style)) out.push(`"style" of "${w}" is one of: ${STYLES[w].join(', ')}`);
+  if (item.mono !== undefined && typeof item.mono !== 'boolean') out.push('"mono" must be true or false');
+  if (item.rows !== undefined && !(Number.isInteger(item.rows) && item.rows >= 1)) out.push('"rows" must be a whole number, 1 or more');
+  if (item.options !== undefined) {
+    if (!isObject(item.options)) out.push('"options" is { from, value, label, description }');
+    else for (const k of Object.keys(item.options)) {
+      if (!OPTION_KEYS.includes(k)) out.push(`"options" has no "${k}" key`);
+      else if (!isText(item.options[k])) out.push(`"options.${k}" must be text`);
+    }
+  }
+  if (item.requires !== undefined && !(isObject(item.requires) && (item.requires.askCatalog === undefined
+    || (Number.isInteger(item.requires.askCatalog) && item.requires.askCatalog >= 1)))) out.push('"requires" is { askCatalog: n }');
+  if (item.fallback !== undefined && !isObject(item.fallback)) out.push('"fallback" is a layout item');
+  if (w === 'group' && !Array.isArray(item.children)) out.push('"group" needs "children": a list of items');
+  if (w === 'columns' && !(Array.isArray(item.columns) && item.columns.length > 0 && item.columns.every(Array.isArray))) out.push('"columns" is a non-empty list of item lists');
+  if (w === 'tabs' && !(Array.isArray(item.tabs) && item.tabs.length > 0
+    && item.tabs.every((t) => isObject(t) && isText(t.label) && Array.isArray(t.children)))) out.push('"tabs" is a non-empty list of { label, children }');
+  // a column may carry more (align, mono, format: the renderer's business) — only what P1 reads is held
+  if ((w === 'table' || w === 'table-select') && item.columns !== undefined && !(Array.isArray(item.columns) && item.columns.length > 0
+    && item.columns.every((c) => isObject(c) && isText(c.key) && optText(c.label) && optText(c.unit)))) out.push('"columns" is a non-empty list of { key, label }');
+  return out;
+}
+
+/** Why `schema` (what a row widget's `bind` landed on) cannot feed it, or null. Below an opaque
+ *  object there is no schema to hold it to, so it is let through. */
+function rowBindError(widget, schema, needsId) {
+  if (schema.type === undefined) return null;
+  if (schema.type !== 'array' || !isObject(schema.items) || schema.items.type !== 'object') return `"${widget}" needs a list of objects`;
+  const p = schema.items.properties;
+  // required, not only declared: a row the agent may leave without an id cannot be ranked, picked or judged
+  const required = Array.isArray(schema.items.required) ? schema.items.required : [];
+  if (needsId && isObject(p) && !(Object.hasOwn(p, 'id') && p.id.type === 'string' && required.includes('id'))) return `rows of "${widget}" need a required text "id"`;
+  return null;
+}
+
+/** What a scalar schema type is to a reader; two types of one kind can stand in for each other. */
+const KIND = Object.freeze({ string: 'text', file: 'text', number: 'a number', integer: 'a number', boolean: 'on/off' });
+
+/** Why the data `path` lands on cannot feed `enumFrom` / `defaultFrom` of `node`, or null.
+ *  `enumFrom` wants values — one, a list of them, or a column; `defaultFrom` wants one value for
+ *  a scalar field and a list for a list field. Below an opaque object (C3) nothing is held. */
+function fromError(k, node, path, landed) {
+  if (landed.type === undefined) return null;
+  const many = path.includes('[]') || landed.type === 'array';
+  if (node.type === 'array') return many ? null : `${path} is one value, and this field is a list`;
+  if (k === 'defaultFrom' && many) return `${path} is a list, and this field takes one value`;
+  const leaf = landed.type === 'array' ? landed.items : landed;
+  if (!isObject(leaf) || leaf.type === undefined) return null;
+  if (!Object.hasOwn(KIND, leaf.type)) return `${path} holds ${leaf.type === 'object' ? 'objects' : 'lists'}, not values`;
+  if (Object.hasOwn(KIND, node.type) && KIND[leaf.type] !== KIND[node.type]) return `${path} is ${KIND[leaf.type]}, and this field is ${KIND[node.type]}`;
+  return null;
+}
+
+/** Why a `when` on the answer property `schema` could never hold for `want`, or null. Equality is
+ *  all `when` has: a list or an object never equals anything, a value of another type never
+ *  matches, and one outside a closed `enum` is never chosen. (`enumFrom` is open until ask time.) */
+function whenError(f, schema, want) {
+  if (!Object.hasOwn(KIND, schema.type)) return `"when" cannot compare "${f}": it is ${schema.type === 'array' ? 'a list' : 'an object'}`;
+  const fits = (v) => (schema.type === 'integer' ? Number.isInteger(v) : typeof v === (schema.type === 'number' ? 'number' : schema.type));
+  const never = (Array.isArray(want) ? want : [want]).find((v) => !fits(v) || (Array.isArray(schema.enum) && !schema.enum.includes(v)));
+  return never === undefined ? null : `"when" waits for ${f} = ${JSON.stringify(never)}, which "${f}" can never be`;
+}
+
+/** The first circle in `deps` (field → the fields its visibility waits on) as [a, b, …, a], or null. */
+function whenCycle(deps) {
+  const done = new Set();
+  const trail = [];
+  const visit = (f) => {
+    const at = trail.indexOf(f);
+    if (at >= 0) return [...trail.slice(at), f];
+    if (done.has(f) || !deps.has(f)) return null;
+    trail.push(f);
+    for (const next of deps.get(f)) { const found = visit(next); if (found) return found; }
+    trail.pop();
+    done.add(f);
+    return null;
+  };
+  for (const f of deps.keys()) { const found = visit(f); if (found) return found; }
+  return null;
+}
+
+/** → { ok, errors: [{ path, code, message }] } */
+export function validateFormDef(def, { id } = {}) {
+  const errors = [];
+  if (id !== undefined && !FORM_ID_RE.test(String(id))) errors.push(err('', 'bad-id', `form id "${id}" must match ${FORM_ID_RE}`));
+  if (!isObject(def)) return { ok: false, errors: [...errors, err('', 'dialect', 'a form is an object')] };
+  if (!Number.isInteger(def.version) || def.version < 1) errors.push(err('version', 'dialect', '"version" is a positive integer'));
+  if (typeof def.title !== 'string' || def.title.trim() === '' || def.title.length > MAX_TITLE) errors.push(err('title', 'dialect', `"title" is 1–${MAX_TITLE} characters`));
+  if (def.surface !== undefined && !FORM_SURFACES.includes(def.surface)) errors.push(err('surface', 'dialect', '"surface" is "any" or "web"'));
+
+  for (const side of ['data', 'answer']) {
+    if (!isObject(def[side]) || def[side].type !== 'object') { errors.push(err(side, 'dialect', `"${side}" is an object schema`)); continue; }
+    for (const e of checkDialect(def[side], { side })) errors.push(err(e.path ? `${side}.${e.path}` : side, e.code, e.message));
+  }
+  if (!Array.isArray(def.layout) || def.layout.length === 0) errors.push(err('layout', 'dialect', '"layout" is a non-empty list'));
+  if (errors.length) return { ok: false, errors };
+
+  const props = def.answer.properties || {};
+  // enumFrom / defaultFrom must point into the declared data
+  (function paths(node, path) {
+    if (!isObject(node)) return;
+    for (const k of ['enumFrom', 'defaultFrom']) {
+      if (node[k] === undefined) continue;
+      const landed = schemaAtPath(node[k], def.data);
+      const why = landed ? fromError(k, node, node[k], landed) : null;
+      if (!landed) errors.push(err(path, 'bad-bind', `"${k}": ${node[k]} is not in the data schema`));
+      else if (why) errors.push(err(path, 'bad-bind', `"${k}": ${why}`));
+    }
+    if (node.items) paths(node.items, `${path}[]`);
+    if (isObject(node.properties)) for (const [k, v] of Object.entries(node.properties)) paths(v, `${path}.${k}`);
+  })(def.answer, 'answer');
+
+  const fields = new Set();
+  const whens = [];          // [{ at, field }] every field a `when` names, the item's own or an ancestor's
+  const deps = new Map();    // input field → the fields its visibility waits on
+  const whereOf = new Map(); // input field → its item's address
+  let n = 0;
+  walkLayout(def.layout, (raw, eff, parents) => {
+    const at = `layout#${n += 1}`;
+    if (!isObject(raw) || typeof raw.widget !== 'string') { errors.push(err(at, 'dialect', 'a layout item is an object with a "widget"')); return; }
+    if (!eff) { errors.push(err(at, 'unknown-widget', `"${raw.widget}" is not in the catalog and has no usable fallback`)); return; }
+    if (!isKnownWidget(eff.widget)) return;
+    for (const k of Object.keys(eff)) {
+      if (!COMMON_ITEM_KEYS.includes(k) && !LAYOUT_ITEM_KEYS[eff.widget].includes(k)) errors.push(err(at, 'dialect', `"${eff.widget}" has no "${k}" key`));
+    }
+    for (const message of valueErrors(eff)) errors.push(err(at, 'dialect', message));
+    const cls = widgetClass(eff.widget, eff);
+    if (cls === 'input') {
+      const s = typeof eff.field === 'string' && Object.hasOwn(props, eff.field) ? props[eff.field] : null;
+      if (typeof eff.field !== 'string') errors.push(err(at, 'unknown-field', `"${eff.widget}" needs a "field"`));
+      else if (!s) errors.push(err(at, 'unknown-field', `"${eff.field}" is not an answer property`));
+      else if (!widgetAcceptsType(eff.widget, s)) errors.push(err(at, 'bad-pairing', `"${eff.widget}" cannot fill "${eff.field}" (${s.type})`));
+      if (typeof eff.field === 'string') {
+        if (fields.has(eff.field)) errors.push(err(at, 'dup-field', `"${eff.field}" is bound by more than one item`));
+        else {
+          fields.add(eff.field);
+          whereOf.set(eff.field, at);
+          // an ancestor's `when` hides this field too
+          deps.set(eff.field, new Set([eff, ...parents].flatMap((p) => (isObject(p) && isObject(p.when) ? Object.keys(p.when) : []))));
+        }
+      }
+    } else if (eff.field !== undefined) errors.push(err(at, 'unknown-field', `"${eff.widget}" does not collect a value`));
+    if (NEEDS_BIND.has(eff.widget) && eff.bind === undefined) errors.push(err(at, 'bad-bind', `"${eff.widget}" needs "bind"`));
+    for (const k of bindKeys(eff)) {
+      const landed = isValidPath(eff[k]) ? schemaAtPath(eff[k], def.data) : null;
+      if (!landed) { errors.push(err(at, 'bad-bind', `"${k}": ${JSON.stringify(eff[k])} is not in the data schema`)); continue; }
+      const why = k === 'bind' && ROW_WIDGETS.has(eff.widget) ? rowBindError(eff.widget, landed, cls === 'input') : null;
+      if (why) errors.push(err(at, 'bad-bind', `"bind": ${why}`));
+      // a column resolves to a LIST whatever it holds, and these widgets show one file
+      if (FILE_WIDGETS.has(eff.widget) && eff[k].includes('[]')) {
+        errors.push(err(at, 'bad-bind', `"${k}": "${eff.widget}" shows one file, and ${eff[k]} is a column of them`));
+      // `landed.type` is undefined below an opaque object (C3): nothing to hold it to
+      } else if (FILE_WIDGETS.has(eff.widget) && landed.type !== undefined && landed.type !== 'file') {
+        errors.push(err(at, 'bad-bind', `"${k}": "${eff.widget}" shows a file, and ${eff[k]} is ${landed.type === 'string' ? 'a string' : `of type ${landed.type}`}`));
+      }
+    }
+    if (eff.widget === 'compare') for (const k of ['before', 'after']) if (eff[k] === undefined) errors.push(err(at, 'bad-bind', `"compare" needs "${k}"`));
+    if (isObject(eff.options)) {
+      const landed = isValidPath(eff.options.from) ? schemaAtPath(eff.options.from, def.data) : null;
+      const why = landed ? rowBindError(eff.widget, landed, false) : null;
+      if (!landed) errors.push(err(at, 'bad-bind', '"options.from" is not in the data schema'));
+      else if (why) errors.push(err(at, 'bad-bind', `"options.from": ${why}`));
+    }
+    if (eff.suggest !== undefined && (!Array.isArray(eff.suggest) || !eff.suggest.every((x) => typeof x === 'string'))) errors.push(err(at, 'dialect', '"suggest" is a list of strings'));
+    if (eff.when !== undefined) {
+      if (!isObject(eff.when) || Object.keys(eff.when).length === 0) errors.push(err(at, 'dialect', '"when" is { field: value }'));
+      else for (const [f, want] of Object.entries(eff.when)) {
+        const shaped = isScalar(want) || (Array.isArray(want) && want.length > 0 && want.every(isScalar));
+        if (!Object.hasOwn(props, f)) errors.push(err(at, 'unknown-field', `"when" names "${f}", which is not an answer property`));
+        else {
+          whens.push({ at, field: f });
+          // a condition nobody can meet hides its item for good
+          const never = shaped ? whenError(f, props[f], want) : null;
+          if (never) errors.push(err(at, 'dialect', never));
+        }
+        if (f === eff.field) errors.push(err(at, 'dialect', 'an item cannot depend on its own field'));
+        if (!shaped) errors.push(err(at, 'dialect', '"when" compares against a scalar or a list of scalars'));
+      }
+    }
+  });
+  // A `when` must be answerable. A field no input collects never gets a value, so the item could
+  // never be shown; and fields that wait on each other are all hidden from a human — whose EMPTY
+  // answer would then pass gate 3, while auto mode (which starts from every default) answers them.
+  // Held only on a layout that is otherwise sound: an item whose `field` is wrong already says why
+  // the field it meant is not collected, and must not be echoed by every `when` that names it.
+  if (errors.length === 0) {
+    for (const w of whens) if (!fields.has(w.field)) errors.push(err(w.at, 'unknown-field', `"when" names "${w.field}", which no item collects`));
+    const circle = whenCycle(deps);
+    if (circle) errors.push(err(whereOf.get(circle[0]), 'dialect', `"when" is circular: ${circle.join(' → ')}`));
+  }
+  for (const f of def.answer.required || []) if (!fields.has(f)) errors.push(err(`answer.${f}`, 'unreachable', `required field "${f}" has no input in the layout`));
+  if (errors.length) return { ok: false, errors };
+
+  if (!isObject(def.example)) return { ok: false, errors: [err('example', 'bad-example', 'a form ships an "example" of its data')] };
+  const ex = validate(def.data, def.example);
+  if (!ex.ok) return { ok: false, errors: ex.errors.map((e) => err(`example.${e.path}`, 'bad-example', e.message)) };
+  const auto = collectAnswer(def, resolveAnswerSchema(def.answer, def.example), autoAnswer(def, def.example));
+  for (const e of auto.errors) errors.push(err(`answer.${e.path}`, 'bad-auto', `unattended runs cannot answer "${e.path}": ${e.message} Give it a "default" or "defaultFrom".`));
+  return { ok: errors.length === 0, errors };
+}
+
+/** One line, no trailing period: it is interpolated into `BAD_ASK_FORM: <agent>/<form>: <reason>`. */
+const reasonOf = (errors) => errors.slice(0, 3)
+  .map((e) => (e.path ? `${e.path}: ${e.message}` : e.message).replace(/\s+/g, ' ').replace(/\.$/, '')).join('; ');
+
+/** A byte limit does not bound the stack: 64 KB holds 30 000 levels of `[`, and Node 22 overflows
+ *  near 5 000 of them inside JSON.stringify, which is the size check itself. So depth is counted
+ *  first, and a block past this is refused by name. No written form comes near: the fixtures are 10. */
+const MAX_JSON_DEPTH = 256;
+
+/** Is `v` nested deeper than `max`? A work list, never recursion: this is what guards the stack. */
+function nestsDeeperThan(v, max) {
+  const todo = [[v, 1]];
+  while (todo.length) {
+    const [cur, depth] = todo.pop();
+    if (cur === null || typeof cur !== 'object') continue;
+    if (depth > max) return true;
+    for (const child of Object.values(cur)) todo.push([child, depth + 1]);
+  }
+  return false;
+}
+
+/** The sidecar's `ask` block → the forms that passed gate 1 plus the ones that did not.
+ *  Never throws: a broken block costs the agent its forms, never the agent. */
+export function normalizeAskBlock(raw) {
+  if (raw === undefined || raw === null) return { forms: {}, dropped: [] };
+  if (!isObject(raw) || !isObject(raw.forms)) return { forms: {}, dropped: [{ id: '*', reason: '"ask" is { forms: { <id>: <form> } }' }] };
+  if (nestsDeeperThan(raw, MAX_JSON_DEPTH)) return { forms: {}, dropped: [{ id: '*', reason: `"ask" is nested deeper than ${MAX_JSON_DEPTH} levels` }] };
+  // bytes, not UTF-16 units: a block of non-Latin text is up to three times its `.length`
+  if (new TextEncoder().encode(JSON.stringify(raw)).length > ASK_LIMITS.askBlockBytes) return { forms: {}, dropped: [{ id: '*', reason: `"ask" is larger than ${ASK_LIMITS.askBlockBytes} bytes` }] };
+  const forms = {};
+  const dropped = [];
+  for (const [id, def] of Object.entries(raw.forms)) {
+    if (Object.keys(forms).length >= ASK_LIMITS.formsPerAgent) { dropped.push({ id, reason: `more than ${ASK_LIMITS.formsPerAgent} forms` }); continue; }
+    const { ok, errors } = validateFormDef(def, { id });
+    if (ok) forms[id] = def; else dropped.push({ id, reason: reasonOf(errors) });
+  }
+  return { forms, dropped };
+}

package/src/shared/forms/layout.mjs

@@ -0,0 +1,67 @@
+// src/shared/forms/layout.mjs
+// Walking a form layout (spec §3, §10): children of the three layout widgets, `when`
+// visibility, and the `requires` / `fallback` downgrade. Every consumer — gate 1, the
+// renderer, the projection, answer collection — walks through here so they agree on
+// which items exist and which fields are live.
+import { ASK_CATALOG_VERSION, isKnownWidget } from './catalog.mjs';
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const list = (v) => (Array.isArray(v) ? v : []);
+
+/** The item that actually renders on a host with this catalog: the item itself, its
+ *  `fallback` (recursively), or null when neither is renderable. */
+export function effectiveItem(item, catalogVersion = ASK_CATALOG_VERSION) {
+  for (let cur = item, hops = 0; isObject(cur) && hops < 4; cur = cur.fallback, hops += 1) {
+    const needs = isObject(cur.requires) && Number.isInteger(cur.requires.askCatalog) ? cur.requires.askCatalog : 1;
+    if (isKnownWidget(cur.widget) && needs <= catalogVersion) return cur;
+  }
+  return null;
+}
+
+/** Child item arrays of a layout widget; [] for everything else. */
+export function childrenOf(item) {
+  if (!isObject(item)) return [];
+  if (item.widget === 'group') return [list(item.children)];
+  if (item.widget === 'columns') return list(item.columns).map(list);
+  if (item.widget === 'tabs') return list(item.tabs).map((t) => list(t && t.children));
+  return [];
+}
+
+/** Depth-first. `fn(raw, effective, parents)`; children come from the effective item. */
+export function walkLayout(layout, fn, parents = []) {
+  for (const raw of list(layout)) {
+    const eff = effectiveItem(raw);
+    fn(raw, eff, parents);
+    for (const kids of childrenOf(eff || raw)) walkLayout(kids, fn, [...parents, eff || raw]);
+  }
+}
+
+/** `{ field: value }` or `{ field: [v1, v2] }`, equality only, all keys must hold. */
+export function whenOk(when, values) {
+  if (!isObject(when)) return true;
+  // own values only: an inherited `constructor` is not something the human answered
+  const got = (field) => (isObject(values) && Object.hasOwn(values, field) ? values[field] : undefined);
+  return Object.entries(when).every(([field, want]) => (
+    Array.isArray(want) ? want.includes(got(field)) : got(field) === want));
+}
+
+/** Answer fields whose item — and every ancestor — passes its `when`. */
+export function visibleFields(layout, values) {
+  const out = [];
+  (function visit(items) {
+    for (const raw of list(items)) {
+      const eff = effectiveItem(raw);
+      if (!eff || !whenOk(eff.when, values)) continue;
+      if (typeof eff.field === 'string') out.push(eff.field);
+      for (const kids of childrenOf(eff)) visit(kids);
+    }
+  })(layout);
+  return out;
+}
+
+/** Unique effective widget names, in layout order. */
+export function widgetsUsed(layout) {
+  const seen = [];
+  walkLayout(layout, (raw, eff) => { if (eff && !seen.includes(eff.widget)) seen.push(eff.widget); });
+  return seen;
+}