@worca/app 1.3.0 → 1.4.0-rc.1

package/src/shared/forms/paths.mjs

@@ -0,0 +1,47 @@
+// src/shared/forms/paths.mjs
+// The one path language of ask forms (spec §3): `data.a.b` and `data.items[].id`.
+// Used by `bind`, `enumFrom`, `defaultFrom` and `options.from`. No expressions, no
+// indexes, no functions — a path either names a value or a column of values.
+
+const PATH_RE = /^data(\.[A-Za-z_][A-Za-z0-9_]*(\[\])?)+$/;
+
+export const isValidPath = (path) => typeof path === 'string' && path.length <= 200 && PATH_RE.test(path);
+
+const segments = (path) => path.split('.').slice(1).map((part) => (
+  part.endsWith('[]') ? { key: part.slice(0, -2), each: true } : { key: part, each: false }));
+
+/** Resolve against `{ data }`. A path with a `[]` segment returns a flat array
+ *  (missing branches contribute nothing); any other path returns the value or undefined. */
+export function resolvePath(path, root) {
+  if (!isValidPath(path)) return undefined;
+  let cur = [root && root.data];
+  let many = false;
+  for (const { key, each } of segments(path)) {
+    cur = cur.map((c) => (c !== null && typeof c === 'object' && !Array.isArray(c) && Object.hasOwn(c, key) ? c[key] : undefined));
+    if (each) {
+      many = true;
+      cur = cur.flatMap((c) => (Array.isArray(c) ? c : []));
+    }
+  }
+  return many ? cur.filter((c) => c !== undefined) : cur[0];
+}
+
+/** The schema a path lands on inside a data schema, or null when the path does not exist.
+ *  An object with no `properties` is opaque: any path below it is accepted as `{}`. */
+export function schemaAtPath(path, dataSchema) {
+  if (!isValidPath(path)) return null;
+  let cur = dataSchema;
+  for (const { key, each } of segments(path)) {
+    if (!cur || cur.type !== 'object') return null;
+    if (!cur.properties) return {};
+    cur = Object.hasOwn(cur.properties, key) ? cur.properties[key] : null;
+    if (!cur) return null;
+    if (each) {
+      if (cur.type !== 'array' || !cur.items) return null;
+      cur = cur.items;
+    }
+  }
+  return cur || null;
+}
+
+export const pathInSchema = (path, dataSchema) => schemaAtPath(path, dataSchema) !== null;

package/src/shared/forms/project.mjs

@@ -0,0 +1,309 @@
+// src/shared/forms/project.mjs
+// The text projection of a form ask (spec §8): what the CLI prints, what a chat channel
+// posts, what History and Ask Worca quote — and the reverse, turning a typed line back
+// into values. Derived from the same declaration the web renderer draws, so a surface
+// without pixels can still answer.
+import { resolvePath } from './paths.mjs';
+import { walkLayout } from './layout.mjs';
+import { widgetClass } from './catalog.mjs';
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const MAX_TABLE_ROWS = 10;
+const REPLY_HINT_FIELDS = 3;
+const ROW_WIDGETS = new Set(['rank', 'table-select', 'gallery', 'review-list']);
+const TRUE_WORDS = new Set(['y', 'yes', 'true', 'on', '1']);
+const FALSE_WORDS = new Set(['n', 'no', 'false', 'off', '0']);
+
+const rowsOf = (path, data) => {
+  const rows = typeof path === 'string' ? resolvePath(path, { data }) : [];
+  return Array.isArray(rows) ? rows.filter(isObject) : [];
+};
+const isScalar = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+/** A row's property, OWN keys only (C20): the row is agent data and the key is the form author's
+ *  text (`titleKey`, a column's `key`, `options.value`) — every row inherits `constructor`. */
+const own = (r, k) => (isObject(r) && typeof k === 'string' && Object.hasOwn(r, k) ? r[k] : undefined);
+/** A scalar as text. Anything else — absent, null, an object — is no text at all, so the words
+ *  "undefined", "null" and "[object Object]" never reach a chat channel. */
+const text = (v) => (isScalar(v) ? String(v) : '');
+/** A bound value as prose: text, or an object / a list as its JSON; '' for nothing. */
+const prose = (v) => text(v) || (v !== null && typeof v === 'object' ? JSON.stringify(v) : '');
+/** ` — <text>` when a row carries that property, else nothing. */
+const tail = (r, k) => (text(own(r, k)) === '' ? '' : ` — ${text(own(r, k))}`);
+/** The id a row can be answered with — a text one (gate 1, C22); null for a row that has none. */
+const idOf = (r) => { const id = own(r, 'id'); return typeof id === 'string' && id !== '' ? id : null; };
+const rowLabel = (item, r) => [own(r, item.titleKey || 'title'), own(r, item.captionKey || 'caption'), own(r, 'name'), own(r, 'label'), own(r, 'id')]
+  .map(text).find((s) => s !== '') || '';
+/** `- <id>: <label>`; a row with no text id is shown by its label alone. */
+const rowLine = (item, r) => (idOf(r) === null ? `- ${rowLabel(item, r)}` : `- ${idOf(r)}: ${rowLabel(item, r)}`);
+/** The rows of a row widget that can be CHOSEN: the ones with a text id. */
+const choices = (item, data) => rowsOf(item.bind, data).filter((r) => idOf(r) !== null);
+/** The text display widgets, which spec §6.2 lets bind a `file` instead of a value. */
+const TEXT_WIDGETS = new Set(['markdown', 'code', 'diff', 'table', 'json']);
+const BODY_CHARS = 160;
+const oneLine = (s) => { const t = String(s).replace(/\s+/g, ' ').trim(); return t.length > BODY_CHARS ? `${t.slice(0, BODY_CHARS - 1)}…` : t; };
+/** An author's label for a choice. Text only — which is also what keeps the inherited
+ *  `labels.constructor` (a function) from ever being one. */
+const labelOf = (item, v) => (isObject(item.labels) && typeof item.labels[v] === 'string' ? item.labels[v] : String(v));
+const size = (bytes) => (bytes >= 1048576 ? `${(bytes / 1048576).toFixed(1)} MB` : `${Math.max(1, Math.round((bytes || 0) / 1024))} KB`);
+
+function optionsOf(item, schema, data) {
+  if (Array.isArray(item.suggest)) return item.suggest.map((s) => ({ value: s, label: s }));
+  if (isObject(item.options)) {
+    return rowsOf(item.options.from, data).map((r) => ({ value: own(r, item.options.value || 'id'), label: text(own(r, item.options.label || 'label')) }))
+      .filter((o) => isScalar(o.value) && o.value !== '').map((o) => ({ value: o.value, label: o.label || String(o.value) }));
+  }
+  if (ROW_WIDGETS.has(item.widget)) return choices(item, data).map((r) => ({ value: idOf(r), label: rowLabel(item, r) }));
+  const en = schema.enum || (schema.items && schema.items.enum) || [];
+  return en.map((v) => ({ value: v, label: labelOf(item, v) }));
+}
+
+/** A review-list's per-item sub-prompts: its verdict, then its optional note. */
+function itemFieldsOf(item, schema) {
+  const p = schema.items.properties;
+  const verdict = { field: 'verdict', label: 'Verdict', widget: 'select', type: 'string', schema: p.verdict,
+    options: p.verdict.enum.map((v) => ({ value: v, label: labelOf(item, v) })),
+    default: p.verdict.default !== undefined ? p.verdict.default : p.verdict.enum[0], required: true };
+  if (!p.note) return [verdict];
+  return [verdict, { field: 'note', label: 'Note', widget: 'text', type: 'string', schema: p.note, options: [], default: undefined, required: false }];
+}
+
+/** The input fields of an ask, in layout order. `ask` = { data, layout, answerSchema }.
+ *  → [{ field, label, widget, type, schema, options: [{ value, label }], items, itemFields,
+ *       verdicts, free, default, required, when }]
+ *  `items` is [{ id, label }] for the row widgets (rank, table-select, gallery, review-list),
+ *  else null; `itemFields` is set for review-list only. */
+export function promptFields(ask) {
+  const props = (ask.answerSchema && ask.answerSchema.properties) || {};
+  const required = new Set((ask.answerSchema && ask.answerSchema.required) || []);
+  const out = [];
+  walkLayout(ask.layout, (raw, eff) => {
+    if (!eff || widgetClass(eff.widget, eff) !== 'input' || typeof eff.field !== 'string' || !Object.hasOwn(props, eff.field) || out.some((f) => f.field === eff.field)) return;
+    const s = props[eff.field];
+    const review = eff.widget === 'review-list';
+    out.push({
+      field: eff.field, label: String(eff.label || s.title || eff.field), widget: eff.widget, type: s.type, schema: s,
+      options: optionsOf(eff, s, ask.data),
+      items: ROW_WIDGETS.has(eff.widget) ? choices(eff, ask.data).map((r) => ({ id: idOf(r), label: rowLabel(eff, r) })) : null,
+      itemFields: review ? itemFieldsOf(eff, s) : null,
+      verdicts: review ? s.items.properties.verdict.enum.slice() : [],
+      free: Array.isArray(eff.suggest),
+      default: s.default, required: required.has(eff.field), when: eff.when || null,
+    });
+  });
+  return out;
+}
+
+function describe(f) {
+  const bits = [];
+  if (f.widget === 'rank') bits.push(`order of: ${f.options.map((o) => o.value).join(', ')}`);
+  else if (f.widget === 'review-list') bits.push(`per item ${f.verdicts.join('/')} for: ${f.options.map((o) => o.value).join(', ')}`);
+  else if (f.options.length) bits.push(`${f.type === 'array' ? 'any of' : 'one of'}${f.free ? ' (or your own text)' : ''}: ${f.options.map((o, i) => `${i + 1}) ${o.label}`).join('  ')}`);
+  else {
+    const s = f.schema;
+    const range = s.minimum !== undefined && s.maximum !== undefined ? ` ${s.minimum}–${s.maximum}` : s.minimum !== undefined ? ` ≥ ${s.minimum}` : '';
+    bits.push(`${f.type === 'boolean' ? 'yes/no' : f.type}${range}${s.format ? ` (${s.format})` : ''}${s.pattern ? ` /${s.pattern}/` : ''}`);
+  }
+  if (f.default !== undefined) bits.push(`default ${JSON.stringify(f.default)}`);
+  if (!f.required) bits.push('optional');
+  if (f.when) bits.push(`only when ${Object.entries(f.when).map(([k, v]) => `${k}=${Array.isArray(v) ? v.join('/') : v}`).join(', ')}`);
+  return bits.join(' · ');
+}
+
+/** `ask` = the P2 envelope ({ title, agent, data, layout, answerSchema, files }). → string
+ *  `ref`: a non-empty string appends ONE reply line naming the first fields. `maxChars`:
+ *  0 / omitted = no cap; otherwise DISPLAY text is dropped from the end until it fits and
+ *  the cut is marked by a lone `…` line — the title, the prompts and the reply line never are. */
+export function projectForm(ask, { ref, maxChars = 0 } = {}) {
+  const data = ask.data;
+  const fileLine = (rel) => {
+    const f = (ask.files || []).find((x) => x.rel === rel);
+    return f ? `${rel} (${f.mime}, ${size(f.bytes)})` : String(rel);
+  };
+  const fields = promptFields(ask);
+  const blocks = [{ keep: true, lines: [`${ask.title}${ask.agent ? ` — ${ask.agent}` : ''}`, ''] }];
+  const show = (...lines) => blocks.push({ keep: false, lines });
+  walkLayout(ask.layout, (raw, eff) => {
+    if (!eff) return;
+    const w = eff.widget;
+    const v = typeof eff.bind === 'string' ? resolvePath(eff.bind, { data }) : undefined;
+    // An absent optional value prints NOTHING: this text is posted to a chat channel, and the
+    // word "undefined" in it is a bug the reader sees. A missing file in a row is a dash.
+    const fileOr = (rel) => (text(rel) === '' ? '—' : fileLine(text(rel)));
+    const isFile = typeof eff.bind === 'string' && Array.isArray(ask.fileRefs) && ask.fileRefs.some((r) => isObject(r) && r.path === eff.bind);
+    if (TEXT_WIDGETS.has(w) && isFile) {
+      if (text(v) !== '') show(`[${w}] ${fileLine(text(v))}`);
+    } else if (w === 'markdown') {
+      if (prose(v) !== '') show(prose(v), '');
+    } else if (w === 'callout') {
+      const said = [text(eff.title), text(v) || text(eff.text)].filter((s) => s !== '').join(' ');
+      if (said !== '') show(said, '');
+    } else if (w === 'image' || w === 'pdf' || w === 'media') {
+      if (text(v) !== '') show(`[${w}] ${fileLine(text(v))}`);
+    } else if (w === 'compare') {
+      const before = resolvePath(eff.before, { data });
+      const after = resolvePath(eff.after, { data });
+      if (text(before) !== '' || text(after) !== '') show(`[compare] ${fileOr(before)}  ->  ${fileOr(after)}`);
+    } else if (w === 'gallery') {
+      show(...rowsOf(eff.bind, data).map((r) => `[image] ${idOf(r) === null ? '' : `${idOf(r)}: `}${fileOr(own(r, eff.fileKey || 'file'))}${tail(r, eff.captionKey || 'caption')}`));
+    } else if (w === 'file-list') {
+      show(...rowsOf(eff.bind, data).map((r) => `[file] ${fileOr(own(r, eff.fileKey || 'file'))}${tail(r, eff.noteKey || 'note')}`));
+    } else if (w === 'code' || w === 'diff') {
+      if (prose(v) !== '') show(`[${w}] ${text(eff.name)}`.trim(), prose(v), '');
+    } else if (w === 'json') {
+      if (v !== undefined && v !== null) show(`[json] ${JSON.stringify(v)}`);
+    } else if (w === 'table' || w === 'table-select') {
+      // gate 1 holds `columns` to [{ key, label }], but a persisted ask outlives the gate that admitted it
+      const cols = (Array.isArray(eff.columns) ? eff.columns : []).filter((c) => isObject(c) && typeof c.key === 'string');
+      const rows = rowsOf(eff.bind, data);
+      if (cols.length) {
+        show(cols.map((c) => c.label || c.key).join(' | '),
+          ...rows.slice(0, MAX_TABLE_ROWS).map((r) => cols.map((c) => `${prose(own(r, c.key)) || '—'}${text(own(r, c.key)) === '' ? '' : text(c.unit)}`).join(' | ')),
+          ...(rows.length > MAX_TABLE_ROWS ? [`… ${rows.length - MAX_TABLE_ROWS} more rows`] : []));
+      }
+    } else if (w === 'review-list') {
+      // a reviewer on a text surface must see WHAT is being judged, not only its title
+      show(...rowsOf(eff.bind, data).map((r) => `${rowLine(eff, r)}${text(own(r, eff.bodyKey || 'body')) ? ` — ${oneLine(text(own(r, eff.bodyKey || 'body')))}` : ''}`));
+    } else if (w === 'rank') {
+      show(...rowsOf(eff.bind, data).map((r) => rowLine(eff, r)));
+    }
+    const at = fields.findIndex((f) => f.field === eff.field);
+    if (at >= 0 && widgetClass(w, eff) === 'input') blocks.push({ keep: true, lines: [`${at + 1}. ${fields[at].label} {${fields[at].field}}`, `   ${describe(fields[at])}`] });
+  });
+  if (typeof ref === 'string' && ref !== '') {
+    const hint = fields.filter((f) => !f.when).slice(0, REPLY_HINT_FIELDS).map((f) => `${f.field}=${f.type === 'array' ? '<a,b>' : '<value>'}`);
+    blocks.push({ keep: true, lines: ['', `Reply: /answer ${ref} ${hint.join(' | ')}`.trimEnd()] });
+  }
+  const render = (bs) => bs.flatMap((b) => b.lines).join('\n').replace(/\n{3,}/g, '\n\n');
+  if (!(maxChars > 0) || render(blocks).length <= maxChars) return render(blocks);
+  const kept = blocks.slice();
+  let marker = -1;   // the one `…` line; it always sits after the next block to go
+  while (render(kept).length > maxChars) {
+    const last = kept.findLastIndex((b) => !b.keep);
+    if (last < 0) break;
+    if (marker >= 0) kept.splice(marker, 1);
+    kept[last] = { keep: true, lines: ['…'] };
+    marker = last;
+  }
+  return render(kept);
+}
+
+/** Split on an unescaped separator. A backslash pair is kept as-is for unescapeToken(). */
+function splitOn(text, sep) {
+  const parts = [''];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] === '\\' && i + 1 < text.length) { parts[parts.length - 1] += text[i] + text[i + 1]; i += 1; } else if (text[i] === sep) parts.push('');
+    else parts[parts.length - 1] += text[i];
+  }
+  return parts;
+}
+/** Only `\|` `\,` `\=` `\:` and `\\` unescape. Any other `\x` stays two characters, so a
+ *  Windows path typed into chat (C:\Users\dev) survives byte for byte. */
+const unescapeToken = (s) => s.replace(/\\([|,=:\\])/g, '$1').trim();
+const hasUnescaped = (text, ch) => splitOn(text, ch).length > 1;
+
+/** `t` is one UNESCAPED token. A number enum keeps C10: in [1,2,4,8] "4" is the value 4. For text
+ *  values (row ids, mostly) what the prompt SHOWS decides: an exact label first. Then, when a
+ *  number is both an option's position and a DIFFERENT option's id — rows 3,1,2, or the subset
+ *  2,5 — neither reading is safe: the prompt numbers the options and the agent named the ids, and
+ *  guessing sends the agent a row the human did not choose. It is refused, and a label settles it.
+ *  After that: the exact value, the 1-based ordinal, value or label ignoring case, free text. */
+function pick(f, t) {
+  const low = t.toLowerCase();
+  const exact = f.options.find((o) => String(o.value) === t);
+  if (exact && typeof exact.value !== 'string') return { ok: true, value: exact.value };
+  const shown = f.options.find((o) => o.label === t);
+  if (shown) return { ok: true, value: shown.value };
+  const nth = /^\d+$/.test(t) ? f.options[Number(t) - 1] : undefined;
+  if (exact && nth && nth !== exact) {
+    return { ok: false, code: 'enum', message: `"${t}" is both option ${t} ("${nth.label}") and the id of "${exact.label}": type the label of the one you mean` };
+  }
+  if (exact) return { ok: true, value: exact.value };
+  if (nth) return { ok: true, value: nth.value };
+  const loose = f.options.find((o) => String(o.value).toLowerCase() === low || o.label.toLowerCase() === low);
+  if (loose) return { ok: true, value: loose.value };
+  if (f.free && t !== '') return { ok: true, value: t };
+  return { ok: false, code: 'enum', message: `"${t}" is not one of: ${f.options.map((o) => o.value).join(', ')}` };
+}
+
+/** One typed entry → a value of the field's type. `f` is a promptFields() entry (or one of
+ *  its `itemFields`). → { ok: true, value } | { ok: false, code, message }. An empty entry
+ *  is `{ ok: true, value: undefined }` ("use the default"). A trailing `\r` is not data. */
+export function coerceInput(f, text) {
+  const raw = String(text === undefined || text === null ? '' : text).replace(/\r$/, '');
+  if (raw.trim() === '') return { ok: true, value: undefined };
+  if (f.widget === 'review-list') {
+    const value = [];
+    for (const part of splitOn(raw, ',')) {
+      if (part.trim() === '') continue;   // a trailing comma is not an item
+      const [id, verdict = '', ...note] = splitOn(part, ':').map(unescapeToken);
+      if (!f.options.some((o) => o.value === id)) return { ok: false, code: 'enum', message: `"${id}" is not an item` };
+      const v = pick(f.itemFields[0], verdict);   // value, number or label — exactly what the per-item prompt takes
+      if (!v.ok) return v;
+      value.push(note.join(':') ? { id, verdict: v.value, note: note.join(':') } : { id, verdict: v.value });
+    }
+    const given = new Set(value.map((x) => x.id));
+    for (const o of f.options) if (!given.has(o.value)) value.push({ id: o.value, verdict: f.itemFields[0].default });
+    return { ok: true, value };
+  }
+  if (f.type === 'array') {
+    const value = [];
+    for (const part of splitOn(raw, ',')) {
+      if (part.trim() === '') continue;
+      const p = f.options.length ? pick(f, unescapeToken(part)) : { ok: true, value: unescapeToken(part) };
+      if (!p.ok) return p;
+      value.push(p.value);
+    }
+    // C18: a rank is a full reorder. The items named come first, the rest keep their data order —
+    // the same courtesy a review-list gives its unlisted items. A repeat is gate 3's to refuse.
+    if (f.widget === 'rank') for (const o of f.options) if (!value.includes(o.value)) value.push(o.value);
+    return { ok: true, value };
+  }
+  if (f.type === 'boolean') {
+    const t = raw.trim().toLowerCase();
+    if (TRUE_WORDS.has(t)) return { ok: true, value: true };
+    if (FALSE_WORDS.has(t)) return { ok: true, value: false };
+    return { ok: false, code: 'type', message: 'answer yes or no' };
+  }
+  if (f.options.length) return pick(f, unescapeToken(raw));
+  if (f.type === 'number' || f.type === 'integer') {
+    const n = Number(raw.trim());
+    return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, code: 'type', message: `"${raw.trim()}" is not a number` };
+  }
+  return { ok: true, value: unescapeToken(raw) };
+}
+
+/** `field=value | field2=a,b` → { values, errors: [{ path, code, message }] }.
+ *  - split on unescaped `|`; inside a pair only the FIRST unescaped `=` splits;
+ *  - a name that is not an input field is `unknown-field`; a field given twice is `duplicate-field`;
+ *  - text with no unescaped `=` is the value of `bareField`, or of the only field of a one-field form;
+ *  - commas split only when the field's type is `array`.
+ *  Values are coerced, NOT validated — feed them to collectAnswer. */
+export function parseAnswerLine(text, ask, { bareField } = {}) {
+  const fields = promptFields(ask);
+  const values = {};
+  const errors = [];
+  const line = String(text || '').trim();
+  if (line === '') return { values, errors };
+  const bare = fields.find((f) => f.field === bareField) || (fields.length === 1 ? fields[0] : null);
+  const put = (f, rawValue) => {
+    if (Object.prototype.hasOwnProperty.call(values, f.field)) { errors.push({ path: f.field, code: 'duplicate-field', message: `"${f.field}" is given twice` }); return; }
+    const r = coerceInput(f, rawValue);
+    if (!r.ok) errors.push({ path: f.field, code: r.code, message: r.message });
+    else if (r.value !== undefined) values[f.field] = r.value;
+  };
+  if (!hasUnescaped(line, '=')) {
+    if (bare) put(bare, line); else errors.push({ path: '', code: 'parse', message: 'write the answer as field=value | field2=value' });
+    return { values, errors };
+  }
+  for (const part of splitOn(line, '|')) {
+    if (part.trim() === '') continue;
+    const eq = splitOn(part, '=');
+    if (eq.length < 2) { errors.push({ path: '', code: 'parse', message: `write "${part.trim()}" as field=value` }); continue; }
+    const name = unescapeToken(eq[0]);
+    const f = fields.find((x) => x.field === name);
+    // where a bare answer is possible, the likeliest cause is free text that holds a "=" (C9)
+    if (!f) { errors.push({ path: name, code: 'unknown-field', message: `"${name}" is not a field of this form${bare ? ' (a literal = in an answer is written \\=)' : ''}` }); continue; }
+    put(f, eq.slice(1).join('='));
+  }
+  return { values, errors };
+}

package/src/shared/forms/schema.mjs

@@ -0,0 +1,205 @@
+// src/shared/forms/schema.mjs
+// The ask-forms schema dialect (spec §3.1): a closed JSON Schema subset plus `file`,
+// `enumFrom` and `defaultFrom`. One validator for all three gates, server and browser.
+// Closed on purpose: it is what keeps the text projection and the form-def checks decidable.
+import { isValidPath, resolvePath } from './paths.mjs';
+
+export const SCHEMA_TYPES = Object.freeze(['string', 'number', 'integer', 'boolean', 'array', 'object', 'file']);
+export const SCHEMA_FORMATS = Object.freeze(['date', 'date-time', 'email', 'uri']);
+const KEYS = new Set(['type', 'enum', 'enumFrom', 'default', 'defaultFrom', 'required', 'minimum', 'maximum',
+  'multipleOf', 'minLength', 'maxLength', 'pattern', 'patternHint', 'format', 'items', 'minItems', 'maxItems',
+  'uniqueItems', 'properties', 'title', 'description', 'accept']);
+const TYPES = new Set(SCHEMA_TYPES);
+/** The types a keyword can act on. One that sits elsewhere (`minItems` on the items node, a
+ *  `minimum` on a string) would be ignored by validate() — so it is refused here, by name. */
+const SCALARS = Object.freeze(['string', 'number', 'integer', 'boolean']);
+const APPLIES = Object.freeze({
+  minLength: ['string'], maxLength: ['string'], pattern: ['string'], patternHint: ['string'], format: ['string'],
+  minimum: ['number', 'integer'], maximum: ['number', 'integer'], multipleOf: ['number', 'integer'],
+  items: ['array'], minItems: ['array'], maxItems: ['array'], uniqueItems: ['array'],
+  properties: ['object'], required: ['object'],
+  enum: SCALARS, enumFrom: SCALARS,
+});
+const FORMATS = new Set(SCHEMA_FORMATS);
+/** Is this JSON value of that scalar type? */
+const FITS = Object.freeze({
+  string: (v) => typeof v === 'string', number: (v) => typeof v === 'number', integer: (v) => Number.isInteger(v), boolean: (v) => typeof v === 'boolean',
+});
+const MAX_DEPTH = 3;   // object → array → object, then scalars
+
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const isScalar = (v) => ['string', 'number', 'boolean'].includes(typeof v);
+const clone = (v) => JSON.parse(JSON.stringify(v));
+const err = (path, code, message) => ({ path, code, message });
+/** A shape alone lets 2026-13-45 through, and the agent would resume with it: the day must exist. */
+function realDate(y, m, d) {
+  const t = new Date(0);
+  t.setUTCFullYear(y, m - 1, d);   // not Date.UTC(): that maps the years 0–99 onto 1900–1999
+  return t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+}
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
+const FORMAT_OK = Object.freeze({
+  date: (v) => { const m = DATE_RE.exec(v); return m !== null && realDate(Number(m[1]), Number(m[2]), Number(m[3])); },
+  'date-time': (v) => {
+    const m = DATE_TIME_RE.exec(v);
+    return m !== null && realDate(Number(m[1]), Number(m[2]), Number(m[3]))
+      && Number(m[4]) < 24 && Number(m[5]) < 60 && (m[6] === undefined || Number(m[6]) < 60);
+  },
+  email: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
+  uri: (v) => /^[a-z][a-z0-9+.-]*:\S+$/i.test(v),
+});
+
+function compiles(pattern) {
+  try { return Boolean(new RegExp(pattern)); } catch { return false; }
+}
+
+/** Is `schema` inside the dialect? `side` is 'data' (may use `file`, may hold opaque
+ *  objects) or 'answer' (may use `enumFrom` / `defaultFrom`). → [{ path, code, message }] */
+export function checkDialect(schema, { side }) {
+  const errors = [];
+  const bad = (path, message) => errors.push(err(path, 'dialect', message));
+  (function walk(node, path, depth) {
+    if (!isObject(node)) { bad(path, 'schema must be an object'); return; }
+    // lists nest too: object → array → object → a list of scalars is the deepest shape there is
+    if (depth > MAX_DEPTH + 1) { bad(path, 'nesting is limited to object → array → object'); return; }
+    const before = errors.length;
+    for (const k of Object.keys(node)) if (!KEYS.has(k)) bad(path, `unsupported keyword "${k}"`);
+    if (!TYPES.has(node.type)) { bad(path, `unknown type ${JSON.stringify(node.type)}`); return; }
+    for (const k of Object.keys(node)) if (Object.hasOwn(APPLIES, k) && !APPLIES[k].includes(node.type)) bad(path, `"${k}" does not apply to ${node.type}`);
+    if (node.type === 'file' && side !== 'data') bad(path, '"file" is a data-side type');
+    if (node.accept !== undefined && (node.type !== 'file' || !Array.isArray(node.accept) || !node.accept.every((a) => typeof a === 'string'))) bad(path, '"accept" is a list of mime patterns on a file');
+    for (const k of ['enumFrom', 'defaultFrom']) {
+      if (node[k] === undefined) continue;
+      if (side !== 'answer') bad(path, `"${k}" is an answer-side keyword`);
+      else if (!isValidPath(node[k])) bad(path, `"${k}" is not a valid path`);
+    }
+    if (node.enum !== undefined && (!Array.isArray(node.enum) || node.enum.length === 0 || !node.enum.every(isScalar))) bad(path, '"enum" is a non-empty list of scalars');
+    // a value of another type can never be answered: `{ type: 'integer', enum: ['a'] }` is a field nobody can fill
+    else if (node.enum !== undefined && Object.hasOwn(FITS, node.type) && !node.enum.every(FITS[node.type])) bad(path, `"enum" values must be of type ${node.type}`);
+    if (node.enum !== undefined && node.enumFrom !== undefined) bad(path, 'use "enum" or "enumFrom", not both');
+    if (node.pattern !== undefined && (typeof node.pattern !== 'string' || !compiles(node.pattern))) bad(path, '"pattern" does not compile');
+    if (node.format !== undefined && !FORMATS.has(node.format)) bad(path, `unknown format "${node.format}"`);
+    for (const k of ['minimum', 'maximum', 'multipleOf']) {
+      if (node[k] !== undefined && !Number.isFinite(node[k])) bad(path, `"${k}" must be a number`);
+    }
+    if (Number.isFinite(node.multipleOf) && node.multipleOf <= 0) bad(path, '"multipleOf" must be greater than 0');
+    for (const k of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+      if (node[k] !== undefined && !(Number.isInteger(node[k]) && node[k] >= 0)) bad(path, `"${k}" must be a whole number, 0 or more`);
+    }
+    for (const k of ['title', 'description', 'patternHint']) if (node[k] !== undefined && typeof node[k] !== 'string') bad(path, `"${k}" must be text`);
+    if (node.uniqueItems !== undefined && typeof node.uniqueItems !== 'boolean') bad(path, '"uniqueItems" must be true or false');
+    if (node.type === 'array') {
+      if (node.items === undefined) bad(path, 'an array needs "items"');
+      else walk(node.items, `${path}[]`, depth + 1);
+    }
+    if (node.type === 'object') {
+      if (depth >= MAX_DEPTH) bad(path, 'nesting is limited to object → array → object');
+      if (node.properties === undefined) {
+        if (side !== 'data' || depth === 0) bad(path, 'an object needs "properties"');
+      } else if (!isObject(node.properties)) bad(path, '"properties" must be an object');
+      else for (const [k, v] of Object.entries(node.properties)) {
+        // the one name an assignment cannot hold: `out[k] = v` would set a prototype instead
+        if (k === '__proto__') bad(path, '"__proto__" cannot be a property name');
+        else walk(v, path ? `${path}.${k}` : k, depth + 1);
+      }
+      if (node.required !== undefined) {
+        if (!Array.isArray(node.required) || !node.required.every((r) => typeof r === 'string')) bad(path, '"required" is a list of property names');
+        else for (const r of node.required) if (!isObject(node.properties) || !Object.hasOwn(node.properties, r)) bad(path, `"required" names unknown property "${r}"`);
+      }
+    }
+    // A `default` prefills the web form even where auto mode never looks (a `when`-hidden field),
+    // so it is held to its own node here. Only a node that is otherwise sound is run: check()
+    // assumes the shape this walk has just verified. `enumFrom` is unknown until ask time.
+    if (node.default !== undefined && errors.length === before) {
+      const own = [];
+      check(node, node.default, path, own);
+      if (own.length) bad(path, `"default" does not fit its own schema: ${own[0].message}`);
+    }
+  })(schema, '', 0);
+  return errors;
+}
+
+const isMissing = (v) => v === undefined || v === null || v === '';
+
+function check(schema, v, path, errors) {
+  const push = (code, message) => errors.push(err(path, code, message));
+  switch (schema.type) {
+    case 'object': {
+      if (!isObject(v)) { push('type', 'Must be an object.'); return; }
+      if (!schema.properties) return;
+      // own keys only: `constructor` and `toString` are inherited by every object, and are neither
+      // a declared property nor a supplied value
+      for (const k of schema.required || []) if (!Object.hasOwn(v, k) || isMissing(v[k])) errors.push(err(path ? `${path}.${k}` : k, 'required', 'Required.'));
+      for (const k of Object.keys(v)) {
+        if (!Object.hasOwn(schema.properties, k)) { errors.push(err(path ? `${path}.${k}` : k, 'unknown-key', 'Not a declared property.')); continue; }
+        if (!isMissing(v[k])) check(schema.properties[k], v[k], path ? `${path}.${k}` : k, errors);
+      }
+      return;
+    }
+    case 'array': {
+      if (!Array.isArray(v)) { push('type', 'Must be a list.'); return; }
+      if (schema.minItems !== undefined && v.length < schema.minItems) push('minItems', `Pick at least ${schema.minItems}.`);
+      if (schema.maxItems !== undefined && v.length > schema.maxItems) push('maxItems', `Pick at most ${schema.maxItems}.`);
+      if (schema.uniqueItems && new Set(v.map((x) => JSON.stringify(x))).size !== v.length) push('unique', 'Entries must be different.');
+      v.forEach((item, i) => check(schema.items, item, `${path}[${i}]`, errors));
+      return;
+    }
+    case 'string': case 'file': {
+      if (typeof v !== 'string') { push('type', 'Must be text.'); return; }
+      if (schema.type === 'file' && (v.includes('\0') || v.trim() === '')) push('type', 'Must be a file path.');
+      if (schema.minLength !== undefined && v.length < schema.minLength) push('minLength', `At least ${schema.minLength} characters.`);
+      if (schema.maxLength !== undefined && v.length > schema.maxLength) push('maxLength', `At most ${schema.maxLength} characters.`);
+      if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(v)) push('pattern', schema.patternHint || 'Does not match the expected format.');
+      if (schema.format !== undefined && Object.hasOwn(FORMAT_OK, schema.format) && !FORMAT_OK[schema.format](v)) push('format', `Must be a valid ${schema.format}.`);
+      break;
+    }
+    case 'number': case 'integer': {
+      if (typeof v !== 'number' || !Number.isFinite(v)) { push('type', 'Must be a number.'); return; }
+      if (schema.type === 'integer' && !Number.isInteger(v)) push('type', 'Must be a whole number.');
+      if (schema.minimum !== undefined && v < schema.minimum) push('min', `Minimum is ${schema.minimum}.`);
+      if (schema.maximum !== undefined && v > schema.maximum) push('max', `Maximum is ${schema.maximum}.`);
+      if (schema.multipleOf !== undefined && Math.abs(v / schema.multipleOf - Math.round(v / schema.multipleOf)) > 1e-9) push('multiple', `Must be a multiple of ${schema.multipleOf}.`);
+      break;
+    }
+    case 'boolean':
+      if (typeof v !== 'boolean') { push('type', 'Must be on or off.'); return; }
+      break;
+    default:
+      push('dialect', `unknown type ${JSON.stringify(schema.type)}`);
+      return;
+  }
+  if (schema.enum !== undefined && !schema.enum.includes(v)) push('enum', 'Not one of the allowed choices.');
+}
+
+/** → { ok, errors: [{ path, code, message }] }. An empty string counts as missing. */
+export function validate(schema, value) {
+  const errors = [];
+  check(schema, value, '', errors);
+  return { ok: errors.length === 0, errors };
+}
+
+/** Materialize `enumFrom` → `enum` and `defaultFrom` → `default` against the agent's
+ *  data. Done once at ask time and stored with the ask, so gate 3 sees a closed set. */
+export function resolveAnswerSchema(answerSchema, data) {
+  const out = clone(answerSchema);
+  (function walk(node) {
+    if (!isObject(node)) return;
+    if (node.enumFrom !== undefined) {
+      const found = resolvePath(node.enumFrom, { data });
+      node.enum = (Array.isArray(found) ? found : [found]).filter(isScalar);
+      delete node.enumFrom;
+    }
+    if (node.defaultFrom !== undefined) {
+      const found = resolvePath(node.defaultFrom, { data });
+      // A list field takes a list and any other field one value. `null` and an empty list suggest
+      // nothing: the field then has no default, and auto mode falls back to its first choice.
+      const usable = found !== undefined && found !== null && Array.isArray(found) === (node.type === 'array') && !(Array.isArray(found) && found.length === 0);
+      if (usable) node.default = clone(found);
+      delete node.defaultFrom;
+    }
+    if (node.items) walk(node.items);
+    if (isObject(node.properties)) for (const v of Object.values(node.properties)) walk(v);
+  })(out);
+  return out;
+}