@aria-framework/ask 0.0.0-stage → 0.1.1

package/assets/ask.js

@@ -0,0 +1,430 @@
+/**
+ * ASK ANYTHING — the drawer's behaviour (@aria-framework/ask; extracted from the hub's and soc's public/js/ask.js, which
+ * were the same but for Soc's quotes and two words). Tier 1's quoted words are drawn apart from the answer, labelled
+ * model-written.
+ *
+ * EVERYTHING FROM THE SERVER IS DRAWN AS TEXT (textContent, never innerHTML): the model's words, names and titles from
+ * the records, the person's own question. The only links are hrefs the APP built from the look-ups (chips, "Open the
+ * same list") and the page context — and each is checked to be a same-site path before it becomes an <a>.
+ *
+ * The POST streams `ask/1` NDJSON (lib/stream.js): `start` (the reading), `step` lines while it works, then one `answer` —
+ * or one `refused` line for a limit, or one `error` line. One question at a time: the box and Ask are disabled until it
+ * finishes. The routes' mount point is the drawer's data-ask-base (default /ask).
+ */
+(function () {
+  'use strict';
+
+  var drawer = document.getElementById('ask-drawer');
+  var opener = document.querySelector('[data-ask-open]');
+  if (!drawer || !opener) return;
+
+  var $ = function (sel, root) { return (root || drawer).querySelector(sel); };
+  var conv = $('[data-ask-conv]');
+  var empty = $('[data-ask-empty]');
+  var body = $('[data-ask-body]');
+  var form = $('[data-ask-form]');
+  var input = $('[data-ask-input]');
+  var send = $('[data-ask-send]');
+  var histPanel = $('[data-ask-history-panel]');
+  var readingEl = $('[data-ask-reading]');
+  var csrf = (document.querySelector('meta[name="csrf-token"]') || {}).content || '';
+  var context = drawer.dataset.contextKind ? { kind: drawer.dataset.contextKind, ref: drawer.dataset.contextRef, name: drawer.dataset.contextName } : null;
+  var base = (drawer.dataset.askBase || '/ask').replace(/\/+$/, '') || '/ask';
+  var WHY = { shape: 'the answer was not in the agreed shape', control_chars: 'the answer had control characters', unknown_cite: 'it cited a look-up that did not run',
+    unknown_figure: 'it placed a figure no look-up returned', bad_placeholder: 'a malformed figure', link: 'it carried a link or markup', number_word: 'it wrote a number instead of a figure',
+    claims_action: 'it claimed to have done something', sign_in: 'it asked you to sign in', other_partner: 'it spoke of another partner', instructions: 'it spoke of its instructions',
+    unknown_ref: 'it named a record no look-up returned', typed_number: 'it typed a number instead of a figure', unknown_token: 'it stated something no look-up returned',
+    disallowed_char: 'it used a character outside the allowed set' };
+  var busy = false;
+
+  var isMac = /Mac|iPhone|iPad/.test(navigator.platform || '');
+  var kbd = document.querySelector('[data-ask-kbd]');
+  if (kbd) kbd.textContent = isMac ? '⌘K' : 'Ctrl K';
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag);
+    if (cls) e.className = cls;
+    if (text != null) e.textContent = String(text);
+    return e;
+  }
+  /** A same-site path only — anything else is drawn as plain text. */
+  function safeHref(h) { return typeof h === 'string' && /^\/(?![\/\\])[^\s\\]*$/.test(h) ? h : null; }
+  function link(href, text, cls) {
+    var h = safeHref(href);
+    if (!h) return el('span', cls, text);
+    var a = el('a', cls, text);
+    a.href = h;
+    return a;
+  }
+  function fmtTime(iso) {
+    try { return new Date(iso).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }); } catch (e) { return ''; }
+  }
+  function fmtWhen(iso) {
+    try { return new Date(iso).toLocaleString([], { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' }); } catch (e) { return ''; }
+  }
+
+  // ── OPEN / CLOSE ──────────────────────────────────────────────────────────────────────────────────────────────────
+  function open() {
+    drawer.hidden = false;
+    opener.setAttribute('aria-expanded', 'true');
+    document.body.classList.add('ask-open');
+    loadReading();
+    setTimeout(function () { input.focus(); }, 0);
+  }
+  function close() {
+    drawer.hidden = true;
+    opener.setAttribute('aria-expanded', 'false');
+    document.body.classList.remove('ask-open');
+    opener.focus();
+  }
+  opener.addEventListener('click', function () { if (drawer.hidden) open(); else close(); });
+  $('[data-ask-close]').addEventListener('click', close);
+  document.addEventListener('keydown', function (e) {
+    if ((e.ctrlKey || e.metaKey) && !e.altKey && (e.key === 'k' || e.key === 'K')) {
+      e.preventDefault();
+      if (drawer.hidden) open(); else input.focus();
+    } else if (e.key === 'Escape' && !drawer.hidden) {
+      close();
+    }
+  });
+
+  var readingLoaded = false;
+  function loadReading() {
+    if (readingLoaded) return;
+    readingLoaded = true;
+    fetch(base + '/history', { credentials: 'same-origin', headers: { 'X-Requested-With': 'fetch' } })
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (j) { if (j && j.reading) setReading(j.reading); })
+      .catch(function () { readingLoaded = false; });
+  }
+  function setReading(text) {
+    readingEl.textContent = 'Reading: ' + text;
+    $('[data-ask-reading-sep]').hidden = false;
+    var acting = $('[data-ask-acting]');
+    if (/\(working inside it\)$/.test(text)) {
+      acting.textContent = 'Answering as ' + text.replace(/ \(working inside it\)$/, '') + ' — you are working inside it, so only its customers are counted.';
+      acting.hidden = false;
+    }
+  }
+
+  // ── CONTEXT CHIP ──────────────────────────────────────────────────────────────────────────────────────────────────
+  var ctxClear = $('[data-ask-ctx-clear]');
+  if (ctxClear) ctxClear.addEventListener('click', function () {
+    context = null;
+    var chip = $('[data-ask-ctx]');
+    if (chip) chip.remove();
+    input.focus();
+  });
+
+  // ── SUGGESTIONS, NEW QUESTION, HISTORY ────────────────────────────────────────────────────────────────────────────
+  Array.prototype.forEach.call(drawer.querySelectorAll('[data-ask-suggest]'), function (b) {
+    b.addEventListener('click', function () { input.value = b.textContent; submit(); });
+  });
+  $('[data-ask-new]').addEventListener('click', function () {
+    conv.textContent = '';
+    histPanel.hidden = true;
+    empty.hidden = false;
+    input.value = '';
+    input.focus();
+  });
+  $('[data-ask-history]').addEventListener('click', showHistory);
+
+  input.addEventListener('keydown', function (e) {
+    if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); submit(); }
+  });
+  form.addEventListener('submit', function (e) { e.preventDefault(); submit(); });
+
+  function setBusy(on) {
+    busy = on;
+    input.disabled = on;
+    send.disabled = on;
+    body.setAttribute('aria-busy', on ? 'true' : 'false');
+    $('[data-ask-hint]').textContent = on ? 'One question at a time — this one is still being answered.'
+      : 'Enter sends · Shift+Enter for a new line · Esc closes';
+  }
+
+  // ── ASK ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+  function submit() {
+    var q = input.value.trim();
+    if (!q || busy) return;
+    empty.hidden = true;
+    histPanel.hidden = true;
+    var item = el('li', 'ask-turn');
+    var qh = el('div', 'ask-q');
+    qh.appendChild(el('span', null, q));
+    qh.appendChild(el('time', 'ask-time', fmtTime(new Date().toISOString())));
+    item.appendChild(qh);
+    var steps = el('ul', 'steps');
+    item.appendChild(steps);
+    conv.appendChild(item);
+    input.value = '';
+    setBusy(true);
+
+    var payload = { question: q };
+    if (context) { payload.context_kind = context.kind; payload.context_ref = context.ref; }
+    fetch(base, {
+      method: 'POST', credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json', 'x-csrf-token': csrf, 'X-Requested-With': 'fetch', Accept: 'application/x-ndjson' },
+      body: JSON.stringify(payload)
+    }).then(function (res) {
+      var ct = res.headers.get('Content-Type') || '';
+      if (!/ndjson/.test(ct)) {
+        return res.json().catch(function () { return { type: 'refused', text: 'Something went wrong while answering. Try again.' }; })
+          .then(function (j) { handle(j, item, steps); });
+      }
+      var reader = res.body.getReader();
+      var dec = new TextDecoder();
+      var buf = '';
+      function pump() {
+        return reader.read().then(function (r) {
+          if (r.done) { if (buf.trim()) handleLine(buf, item, steps); return; }
+          buf += dec.decode(r.value, { stream: true });
+          var lines = buf.split('\n');
+          buf = lines.pop();
+          lines.forEach(function (l) { if (l.trim()) handleLine(l, item, steps); });
+          return pump();
+        });
+      }
+      return pump();
+    }).catch(function () {
+      handle({ type: 'refused', text: 'Something went wrong while answering. Nothing was changed; try again.' }, item, steps);
+    }).then(function () { setBusy(false); input.focus(); });
+  }
+
+  function handleLine(l, item, steps) {
+    var j;
+    try { j = JSON.parse(l); } catch (e) { return; }
+    handle(j, item, steps);
+  }
+
+  function handle(j, item, steps) {
+    if (!j || !j.type) return;
+    if (j.type === 'start') { if (j.reading) setReading(j.reading); return; }
+    if (j.type === 'step') {
+      var id = 'ask-step-' + j.n;
+      var li = steps.querySelector('[data-step="' + j.n + '"]');
+      if (!li) { li = el('li'); li.setAttribute('data-step', String(j.n)); li.id = id; steps.appendChild(li); }
+      li.className = j.state === 'done' ? 'done' : 'run';
+      li.textContent = '';
+      li.appendChild(el('span', 'ic', j.state === 'done' ? '✓' : '…'));
+      li.appendChild(el('span', null, j.words + (j.state === 'done' ? ' done' : '')));
+      return;
+    }
+    if (j.type === 'error') {
+      steps.remove();
+      item.appendChild(fixedCard(j.text, null));
+      return;
+    }
+    if (j.type === 'refused') {
+      steps.remove();
+      item.appendChild(fixedCard(j.text, j.resets ? 'You can ask again ' + (j.resets === 'midnight UTC' ? 'from midnight UTC' : j.resets) + '. Your earlier answers stay in History.' : null));
+      return;
+    }
+    if (j.type === 'answer') {
+      steps.remove();
+      item.appendChild(answerCard(j.answer, false));
+    }
+  }
+
+  function fixedCard(text, sub) {
+    var card = el('div', 'ans');
+    var head = el('div', 'ans-head');
+    head.appendChild(el('span', 'mw fixed', 'Fixed wording · not the AI'));
+    card.appendChild(head);
+    card.appendChild(el('p', 'ans-text', text));
+    if (sub) card.appendChild(el('p', 'small text-body-secondary', sub));
+    return card;
+  }
+
+  /** The answer card: wording (AI, fixed or withheld), figures, chips, "How I answered", thumbs. */
+  function answerCard(a, stale) {
+    var card = el('div', 'ans');
+    var head = el('div', 'ans-head');
+    head.appendChild(el('span', 'ans-label', 'Answer'));
+    head.appendChild(el('span', a.by === 'ai' ? 'mw' : 'mw fixed', a.by === 'ai' ? 'Written by the AI' : 'Fixed wording · not the AI'));
+    head.appendChild(el('time', 'ask-time', fmtTime(a.at)));
+    card.appendChild(head);
+    if (stale) card.appendChild(el('p', 'ask-stale small', 'Answered ' + fmtWhen(a.at) + ' — figures may have changed since.'));
+
+    var p = el('p', 'ans-text');
+    if (a.by === 'ai' && Array.isArray(a.segments)) {
+      a.segments.forEach(function (s) {
+        if (s.t === 'text') p.appendChild(document.createTextNode(s.v));
+        else if (s.t === 'fig') { var f = el('span', 'fig', s.v); f.title = s.title || ''; p.appendChild(f); }
+        else if (s.t === 'cite') { var c = el('sup', 'cite'); c.appendChild(el('span', null, String(s.n))); p.appendChild(c); }
+      });
+    } else {
+      p.textContent = a.text || '';
+    }
+    card.appendChild(p);
+    if (a.link) { var lp = el('p', 'ans-link'); lp.appendChild(link(a.link.href, a.link.label, 'rchip')); card.appendChild(lp); }
+
+    if (Array.isArray(a.chips) && a.chips.length) {
+      var chips = el('div', 'chips');
+      a.chips.forEach(function (c) {
+        var text = (c.count != null ? c.count + ' ' : '') + (c.label || '') + (safeHref(c.href) ? ' →' : '');
+        chips.appendChild(link(c.href, text, safeHref(c.href) ? 'rchip' : 'rchip fact'));
+      });
+      card.appendChild(chips);
+      if (a.by === 'ai') card.appendChild(el('p', 'ask-note small', 'Underlined figures and the links below are drawn by the app from the look-ups, never typed by the AI — each figure is the count of the rows its link opens.'));
+    }
+    // TIER 1'S OWN WORDS (S7): quoted as stored, set apart from the answer and labelled model-written — another model's words
+    // about attacker-supplied data, so never merged into the answer. Text only, like everything else here.
+    if (Array.isArray(a.quotes) && a.quotes.length) {
+      a.quotes.forEach(function (q) {
+        var box = el('figure', 'ask-quote');
+        var cap = el('figcaption', 'small');
+        cap.appendChild(el('span', 'mw-tag', 'Model-written'));
+        cap.appendChild(document.createTextNode(' ' + (q.label || '') + (q.at ? ' · ' + q.at : '')));
+        box.appendChild(cap);
+        box.appendChild(el('blockquote', 'ask-quote-text', '“' + (q.text || '') + '”'));
+        card.appendChild(box);
+      });
+    }
+    card.appendChild(howI(a));
+    if (a.ref) card.appendChild(thumbs(a));
+    if (stale) {
+      var again = el('button', 'btn btn-sm btn-outline-primary', 'Ask again');
+      again.type = 'button';
+      again.addEventListener('click', function () { input.value = a.question || ''; submit(); });
+      card.appendChild(again);
+    }
+    return card;
+  }
+
+  function howI(a) {
+    var d = el('details', 'how');
+    var lk = a.lookups || [];
+    var pv = a.provenance || {};
+    var secs = pv.ms ? (pv.ms / 1000).toFixed(1) + ' s' : '';
+    d.appendChild(el('summary', null, 'How I answered · ' + (lk.length ? lk.length + ' look-up' + (lk.length === 1 ? '' : 's') : 'no look-ups')
+      + (pv.endpoint ? ' · ' + pv.endpoint : '') + (secs ? ' · ' + secs : '')));
+    var ol = el('ol', 'how-list');
+    if (!lk.length) ol.appendChild(el('li', null, a.outcome === 'refused_write' ? 'No look-ups ran: the question asks for a change, and Ask is read-only.' : 'No look-ups ran.'));
+    lk.forEach(function (l) {
+      var li = el('li');
+      li.appendChild(el('strong', null, 'Look-up ' + l.n + ': ' + l.words));
+      var meta = el('div', 'small text-body-secondary');
+      meta.appendChild(document.createTextNode((l.outcome === 'ok' ? l.count + ' row' + (l.count === 1 ? '' : 's') : l.outcome === 'not_found' ? '0 rows' : l.outcome) + ' · '));
+      if (safeHref(l.href)) { meta.appendChild(link(l.href, 'Open the same list →')); meta.appendChild(document.createTextNode(' · ')); }
+      meta.appendChild(el('code', null, l.tool));
+      meta.appendChild(document.createTextNode(' · ' + l.ms + ' ms · allowed by your own permission'));
+      li.appendChild(meta);
+      ol.appendChild(li);
+    });
+    d.appendChild(ol);
+    var facts = el('dl', 'how-facts small');
+    function fact(k, v) { if (!v) return; facts.appendChild(el('dt', null, k)); facts.appendChild(el('dd', null, v)); }
+    fact('Model', [pv.endpoint, pv.model, secs, pv.tokens ? pv.tokens.toLocaleString() + ' tokens' : ''].filter(Boolean).join(' · '));
+    fact('Reading', a.reading);
+    if (pv.planMs || pv.answerMs) fact('Steps', 'plan ' + (pv.planMs / 1000).toFixed(1) + ' s · look-ups ' + (pv.lookMs / 1000).toFixed(1) + ' s · answer ' + (pv.answerMs / 1000).toFixed(1) + ' s');
+    if (a.checked) fact('Checked', 'every reference in the answer is one a look-up returned (' + a.checked.cited + ' of ' + a.checked.of + ')');
+    // The CODE only, in fixed words (review of PR #9): the check's reason quotes the model's own text and is never drawn.
+    if (a.outcome === 'withheld' && a.whyCode) fact('Withheld', WHY[a.whyCode] || 'the answer did not match the look-ups');
+    if (Array.isArray(pv.skipped) && pv.skipped.length) fact('Skipped', pv.skipped.map(function (s) { return s.endpoint + ' — ' + s.why; }).join('; '));
+    fact('Recorded', 'in the audit log');
+    d.appendChild(facts);
+    return d;
+  }
+
+  function thumbs(a) {
+    var wrap = el('div', 'ask-thumbs');
+    wrap.appendChild(el('span', 'small text-body-secondary', 'Was this right?'));
+    var up = el('button', 'thumb'); up.type = 'button'; up.setAttribute('aria-label', 'Helpful'); up.setAttribute('aria-pressed', 'false');
+    up.appendChild(el('i', 'bi bi-hand-thumbs-up'));
+    var down = el('button', 'thumb'); down.type = 'button'; down.setAttribute('aria-label', 'Not helpful'); down.setAttribute('aria-pressed', 'false');
+    down.appendChild(el('i', 'bi bi-hand-thumbs-down'));
+    wrap.appendChild(up); wrap.appendChild(down);
+    var status = el('span', 'small text-body-secondary');
+    wrap.appendChild(status);
+    var formBox = el('div', 'ask-fb');
+    formBox.hidden = true;
+    wrap.appendChild(formBox);
+    function post(body, done) {
+      fetch(base + '/q/' + encodeURIComponent(a.ref) + '/feedback', {
+        method: 'POST', credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json', 'x-csrf-token': csrf, 'X-Requested-With': 'fetch' }, body: JSON.stringify(body)
+      }).then(function (r) { status.textContent = r.ok ? 'Stored with this question' : 'Could not be stored'; if (r.ok && done) done(); })
+        .catch(function () { status.textContent = 'Could not be stored'; });
+    }
+    up.addEventListener('click', function () {
+      up.setAttribute('aria-pressed', 'true'); down.setAttribute('aria-pressed', 'false'); formBox.hidden = true;
+      post({ rating: 'up' });
+    });
+    down.addEventListener('click', function () {
+      down.setAttribute('aria-pressed', 'true'); up.setAttribute('aria-pressed', 'false');
+      formBox.textContent = '';
+      formBox.hidden = false;
+      var fs = el('fieldset');
+      fs.appendChild(el('legend', 'small fw-semibold', 'What was wrong?'));
+      [['wrong_figure', 'Wrong figure'], ['wrong_record', 'Wrong record'], ['no_answer', 'Didn’t answer the question'], ['other', 'Other']]
+        .forEach(function (r, i) {
+          var lab = el('label', 'ask-reason');
+          var rb = el('input'); rb.type = 'radio'; rb.name = 'ask-reason-' + a.ref; rb.value = r[0]; if (i === 0) rb.checked = true;
+          lab.appendChild(rb); lab.appendChild(document.createTextNode(' ' + r[1]));
+          fs.appendChild(lab);
+        });
+      var txt = el('input', 'form-control form-control-sm'); txt.type = 'text'; txt.maxLength = 300; txt.placeholder = 'Anything else? optional, one line';
+      fs.appendChild(txt);
+      var sendBtn = el('button', 'btn btn-sm btn-primary', 'Send feedback'); sendBtn.type = 'button';
+      var cancel = el('button', 'btn btn-sm btn-link', 'Cancel'); cancel.type = 'button';
+      fs.appendChild(sendBtn); fs.appendChild(cancel);
+      fs.appendChild(el('span', 'small text-body-secondary', ' Goes to the platform team’s review list.'));
+      formBox.appendChild(fs);
+      var first = fs.querySelector('input[type=radio]'); if (first) first.focus();
+      sendBtn.addEventListener('click', function () {
+        var sel = fs.querySelector('input[type=radio]:checked');
+        post({ rating: 'down', reason: sel ? sel.value : 'other', text: txt.value }, function () { formBox.hidden = true; });
+      });
+      cancel.addEventListener('click', function () { formBox.hidden = true; down.setAttribute('aria-pressed', 'false'); });
+    });
+    return wrap;
+  }
+
+  // ── HISTORY (S16) ─────────────────────────────────────────────────────────────────────────────────────────────────
+  function showHistory() {
+    empty.hidden = true;
+    histPanel.hidden = false;
+    histPanel.textContent = '';
+    histPanel.appendChild(el('p', 'small text-body-secondary', 'Loading…'));
+    fetch(base + '/history', { credentials: 'same-origin', headers: { 'X-Requested-With': 'fetch' } })
+      .then(function (r) { if (!r.ok) throw new Error('history'); return r.json(); })
+      .then(function (j) {
+        histPanel.textContent = '';
+        histPanel.appendChild(el('p', 'small text-body-secondary', drawer.dataset.historyNote || 'Your last 20 questions here · kept per the retention setting · only you see them.'));
+        if (!j.rows.length) { histPanel.appendChild(el('p', 'small', 'No questions yet.')); return; }
+        var ul = el('ul', 'hist');
+        j.rows.forEach(function (r) {
+          var li = el('li');
+          var b = el('button', 'hist-q', r.question); b.type = 'button';
+          b.addEventListener('click', function () { openPast(r.ref); });
+          li.appendChild(b);
+          var meta = [fmtWhen(r.at)];
+          if (r.rating === 1) meta.push('marked helpful');
+          if (r.rating === -1) meta.push('marked not helpful');
+          if (r.partner) meta.push('working inside ' + r.partner);
+          li.appendChild(el('div', 'small text-body-secondary', meta.join(' · ')));
+          ul.appendChild(li);
+        });
+        histPanel.appendChild(ul);
+        if (j.total > j.rows.length) histPanel.appendChild(el('p', 'small text-body-secondary', (j.total - j.rows.length) + ' more · questions older than the retention window are deleted, not hidden.'));
+      })
+      .catch(function () { histPanel.textContent = ''; histPanel.appendChild(el('p', 'small text-danger', 'History could not be read.')); });
+  }
+
+  function openPast(ref) {
+    fetch(base + '/q/' + encodeURIComponent(ref), { credentials: 'same-origin', headers: { 'X-Requested-With': 'fetch' } })
+      .then(function (r) { if (!r.ok) throw new Error('q'); return r.json(); })
+      .then(function (j) {
+        histPanel.hidden = true;
+        conv.textContent = '';
+        var item = el('li', 'ask-turn');
+        var qh = el('div', 'ask-q');
+        qh.appendChild(el('span', null, j.answer.question || ''));
+        item.appendChild(qh);
+        item.appendChild(answerCard(j.answer, true));
+        conv.appendChild(item);
+      })
+      .catch(function () { histPanel.appendChild(el('p', 'small text-danger', 'That question could not be read.')); });
+  }
+})();

package/bin/ask-migration.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Emit an app's Ask migration pair from the reference table design:
+ *
+ *   npx ask-migration --number 140 --kinds customer,ticket --out migrations [--tenancy 141_ask_tenancy]
+ *
+ * writes migrations/140_ask.sql and migrations/140_ask.postgres.sql. It REFUSES to overwrite a file (an applied migration
+ * is pinned — change the design with a NEW migration). Then GENERATE the tenancy pair with the app's tenancy generator
+ * (never typed), claim both numbers in the app's MIGRATIONS.md first, and pin the files in the commit that adds them.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { referenceMigration, diffMigration } = require('../lib/schema');
+
+function args(argv) {
+  const o = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const k = argv[i];
+    if (!k.startsWith('--')) throw new Error(`unexpected argument ${k}`);
+    o[k.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return o;
+}
+
+function main(argv) {
+  const o = args(argv);
+  if (!/^\d{3,4}$/.test(o.number || '')) throw new Error('--number is the migration number (3–4 digits), claimed in MIGRATIONS.md first');
+  const kinds = String(o.kinds || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const out = o.out || 'migrations';
+  const files = [];
+  for (const dialect of ['sqlite', 'postgres']) {
+    const file = path.join(out, `${o.number}_ask${dialect === 'postgres' ? '.postgres' : ''}.sql`);
+    if (fs.existsSync(file)) throw new Error(`${file} exists — never rewrite a migration; add a new one`);
+    const text = referenceMigration({ dialect, contextKinds: kinds, number: o.number, tenancyFile: o.tenancy });
+    const diffs = diffMigration(text, { dialect, contextKinds: kinds });
+    if (diffs.length) throw new Error(`internal: the generated ${dialect} file differs from the reference (${diffs[0]})`);
+    files.push([file, text]);
+  }
+  fs.mkdirSync(out, { recursive: true });
+  for (const [file, text] of files) { fs.writeFileSync(file, text, { flag: 'wx' }); console.log(`wrote ${file}`); }
+  return files.map(([f]) => f);
+}
+
+if (require.main === module) {
+  try { main(process.argv.slice(2)); } catch (e) { console.error(`ask-migration: ${e.message}`); process.exit(2); }
+}
+
+module.exports = { main };

package/index.js

@@ -0,0 +1,116 @@
+/**
+ * @aria-framework/ask — "Ask anything": a read-only question box over an app's own records.
+ *
+ *   plan (sees the question and the tools, no data) → run (the app's tools, in the asker's own request) → answer (fenced
+ *   results, a strict schema, no tools) → check (the app's figures and chips, never the model's links) → audit.
+ *
+ * THE PACKAGE holds the loop, the answer check, the planner contract, the prompt machinery, limits, the canonical
+ * settings, history and retention, the help-page index, the bench and the question-bank scorer core, the route
+ * factories, the question model factory, the reference table design, the `ask/1` stream, the views, ask.js and ask.css.
+ * THE APP passes its tools, words, field lists, readings and context through `createAsk(config)`, and owns its
+ * migrations (built from `referenceMigration` / bin/ask-migration.js and held to it by `diffMigration`/`diffLiveTables`).
+ *
+ * It names no product and no app tool. See README.md for the full config.
+ */
+
+'use strict';
+
+const path = require('path');
+const { createCatalogue, gateOf, assertToolShape, catalogueHashOf } = require('./lib/catalogue');
+const { createCheck } = require('./lib/check');
+const { createPrompts, promptHashOf, ANSWER_SCHEMA } = require('./lib/prompts');
+const { createRun, WORD_KEYS } = require('./lib/run');
+const { createSettings, CANON, DEFAULTS, RETENTIONS, canonicalKey } = require('./lib/settings');
+const { createLimits } = require('./lib/limits');
+const { createHistory } = require('./lib/history');
+const { createRetention, STALE_MINUTES } = require('./lib/retention');
+const { createBench } = require('./lib/bench');
+const { createGate } = require('./lib/gate');
+const { createDocs, docsTool } = require('./lib/docs');
+const { createAskRouter, createAdminRouters } = require('./lib/routes');
+const { createAskQuestionModel, OUTCOMES, CALL_OUTCOMES, REASONS } = require('./lib/store');
+const schema = require('./lib/schema');
+const stream = require('./lib/stream');
+const bank = require('./lib/bank');
+const common = require('./lib/common');
+
+const VERSION = require('./package.json').version;
+
+/** The default principal: the session's user and the app's scope. A remote Ask replaces this, and nothing else. */
+const sessionPrincipal = (scopeOf) => (req, can) => {
+  const u = req && req.session && req.session.user;
+  if (!u || u.id == null) return null;
+  const scope = scopeOf(req, can);
+  return { id: Number(u.id), name: u.display_name || u.username || `user ${u.id}`, acting: !!(scope && scope.acting), scope };
+};
+
+/**
+ * Bind Ask to an app. Returns { run, catalogue, check, prompts, settings, limits, history, retention, bench, gate, docs?,
+ * routes: { ask(o), admin(o) }, … }. Throws a sentence for anything missing — at boot, not at the first question.
+ * @param {object} c see README.md "createAsk(config)"
+ */
+function createAsk(c) {
+  const need = (k, t) => { if (typeof c[k] !== t) throw new Error(`ask: createAsk needs ${k} (${t})`); };
+  need('invoke', 'function');
+  need('logger', 'object');
+  need('isPublicId', 'function');
+  need('scopeOf', 'function');
+  if (!c.tenant || typeof c.tenant.asPlatform !== 'function' || typeof c.tenant.asHouse !== 'function') throw new Error('ask: createAsk needs tenant { asPlatform, asHouse }');
+  if (!c.settingsStore) throw new Error('ask: createAsk needs settingsStore { get, set } (installation keys)');
+  if (typeof c.ai !== 'function') throw new Error('ask: createAsk needs ai: () => the app\'s AI facade (lazy)');
+  if (!Array.isArray(c.contextKinds) || !c.contextKinds.length) throw new Error('ask: createAsk needs contextKinds (the page context kinds; its migration\'s CHECK)');
+  const modelName = c.modelName || 'AskQuestion';
+  const logger = c.logger;
+  const fenced = c.fenced || require('@aria-framework/ai').fenced;
+
+  const catalogue = createCatalogue(c.tools);
+  const contextTools = { ...(c.contextTools || {}) };
+  for (const [tool, kind] of Object.entries(contextTools)) {
+    if (!catalogue.byId(tool)) throw new Error(`ask: contextTools names ${tool}, which is not a registered tool`);
+    if (!c.contextKinds.includes(kind)) throw new Error(`ask: contextTools maps ${tool} to ${kind}, which is not in contextKinds`);
+  }
+  const contextToolFor = (kind) => Object.keys(contextTools).find((t) => contextTools[t] === kind) || null;
+  const check = createCheck({ ...(c.check || {}), isPublicId: c.isPublicId, toolOf: catalogue.byId });
+  const prompts = createPrompts({ catalogue, ...(c.prompts || {}), fenced,
+    onLeak: c.onLeak || (({ label, removed }) => logger.warn(`AI: fence marker found ${removed}× inside ${label} and stripped — a marker has leaked, or somebody is replaying one`)) });
+  const settings = createSettings({ store: c.settingsStore, toolIds: catalogue.TOOL_IDS, storageKey: c.storageKey });
+  const bench = createBench({ catalogue, prompts, check, ...(c.bench || {}), store: c.settingsStore, key: settings.BENCH_KEY,
+    providerById: c.providerById || (async (id) => c.invoke('AiProvider', 'byId', id)), asHouse: c.tenant.asHouse });
+  const gate = createGate({ forRoute: c.forRoute || (async (route) => c.invoke('AiRoute', 'forRoute', route)), bench, ai: c.ai });
+  const principalOf = typeof c.principalOf === 'function' ? c.principalOf : sessionPrincipal(c.scopeOf);
+  const run = createRun({ invoke: c.invoke, modelName, logger, catalogue, prompts, check, words: c.words, contextTools,
+    contextRef: c.contextRef, openLabel: c.openLabel, principalOf, gate });
+  const limits = createLimits({ invoke: c.invoke, asPlatform: c.tenant.asPlatform, modelName });
+  const history = createHistory({ invoke: c.invoke, asPlatform: c.tenant.asPlatform, principalOf, modelName });
+  const retention = createRetention({ invoke: c.invoke, settings, auditDays: c.auditDays, asHouse: c.tenant.asHouse, modelName });
+
+  const A = { VERSION, run, catalogue, check, prompts, settings, limits, history, retention, bench, gate, principalOf, contextKinds: Object.freeze([...c.contextKinds]),
+    contextTools: Object.freeze(contextTools), contextToolFor, isPublicId: c.isPublicId, invoke: c.invoke, modelName, logger, REASONS, gateOf,
+    hashes: () => ({ prompt: prompts.promptHash(), catalogue: catalogue.catalogueHash(), scorer: bench.scorerHash() }) };
+  A.routes = {
+    ask: (o) => createAskRouter({ ...o, ask: A }),
+    admin: (o) => createAdminRouters({ ...o, ask: A })
+  };
+  return A;
+}
+
+module.exports = {
+  VERSION,
+  createAsk,
+  // Parts, for an app's tests and for building its tools.
+  createCatalogue, assertToolShape, gateOf, createCheck, createPrompts, createRun, createSettings, createLimits, createHistory, createRetention,
+  createBench, createGate, createDocs, docsTool, createAskRouter, createAdminRouters, createAskQuestionModel,
+  common, bank, stream,
+  // The canonical settings (D-0169 item 5).
+  SETTINGS: CANON, SETTING_DEFAULTS: DEFAULTS, RETENTIONS, canonicalKey, STALE_MINUTES, WORD_KEYS,
+  // The model's lists and the reference table design (D-0169 item 2).
+  OUTCOMES, CALL_OUTCOMES, REASONS,
+  SCHEMA: schema.SCHEMA, REFERENCE: schema.REFERENCE, referenceMigration: schema.referenceMigration, diffMigration: schema.diffMigration,
+  diffLiveTables: schema.diffLiveTables,
+  // The hash helpers an app's test-ask-hashes.js computes from its own inputs.
+  promptHashOf, catalogueHashOf, ANSWER_SCHEMA,
+  // The answer stream (D-0169 item 8).
+  STREAM_VERSION: stream.STREAM_VERSION,
+  viewsDir: path.join(__dirname, 'views'),
+  assetsDir: path.join(__dirname, 'assets')
+};