@aria-framework/ask 0.0.0-stage → 0.1.1

package/lib/routes.js

@@ -0,0 +1,304 @@
+/**
+ * The Ask routes, as factories over the app's own express, gates and audit (no express dependency in this package).
+ *
+ *   createAskRouter    → mounted at /ask behind the app's requireAuth. Every route needs `ai.ask`.
+ *     POST /ask                   ask one question; the reply is the `ask/1` NDJSON stream (lib/stream.js). Every question
+ *                                 that got this far is audited `ask.asked` in a `finally`, whatever became of it.
+ *     GET  /ask/history           the person's own last 20 questions, JSON
+ *     GET  /ask/q/:ref            one of the person's own questions with its answer as given, JSON (stale: true)
+ *     POST /ask/q/:ref/feedback   the person's thumbs mark on their own question, JSON — audited `ask.feedback`
+ *
+ *   createAdminRouters → { settingsRouter at /admin/ai/ask, reviewRouter at /admin/ai/ask-review }, platform only
+ *     (ai_config.view to see, ai_config.edit to change). Audited `ai_config.ask_settings`, `ai_config.ask_bench`,
+ *     `ai_config.ask_review` — the action names both apps already write.
+ *
+ * PAGE CONTEXT is a ref the PAGE put there, re-resolved by the app's `contextOf(body, can, req, { offered })` under the
+ * request's own scope and page permissions. ENFORCED HERE, for every app (Soc review S2, which the hub lacked): a context
+ * kind that is read by a context tool (createAsk's contextTools) is resolved ONLY when that tool is in this person's
+ * catalogue with the tools-off list applied — `contextOf` is not even called otherwise — and what it returns must be the
+ * kind that was asked for, with a ref of at most 64 characters, or it is dropped.
+ *
+ * NO partner_id, NO scope and NO permission comes from the request body. The asker is `principalOf`.
+ */
+
+'use strict';
+
+const stream = require('./stream');
+
+const s = (v) => (typeof v === 'string' ? v.trim() : '');
+const REASON_WORDS = Object.freeze({ wrong_figure: 'Wrong figure', wrong_record: 'Wrong record', no_answer: 'Didn’t answer', other: 'Other' });
+const OUTCOME_WORDS = Object.freeze({ answered: 'answered', withheld: 'withheld', not_found: 'not found', refused_write: 'refused · write',
+  cannot: 'could not answer', busy: 'busy', off: 'off', error: 'error', working: 'unfinished' });
+
+const wrap = (fn) => (req, res, next) => { Promise.resolve(fn(req, res, next)).catch(next); };
+const canOf = (res) => (p) => Boolean(res.locals && typeof res.locals.can === 'function' && res.locals.can(p));
+const redirectWith = (res, type, msg, url) => (typeof res.flash === 'function' ? res.flash(type, msg, () => res.redirect(url)) : res.redirect(url));
+
+function routerOf(o) {
+  if (o.express && typeof o.express.Router === 'function') return o.express.Router();
+  if (typeof o.Router === 'function') return o.Router();
+  throw new Error('ask routes: pass the app\'s express (or its Router)');
+}
+function need(o, keys) { for (const k of keys) if (typeof o[k] !== 'function') throw new Error(`ask routes: ${k} is required`); }
+
+/**
+ * @param {object} o
+ * @param {object} o.ask            createAsk's result (run, limits, history, settings, catalogue, contextKinds, principalOf, isPublicId)
+ * @param {object} o.express        the app's express (or o.Router)
+ * @param {Function} o.requirePermission (perm) → middleware
+ * @param {Function} o.audit        (req, action, { entity_type, entity_id?, detail })
+ * @param {Function} o.readingOf    async (req, can) → the reading the drawer states
+ * @param {Function} o.contextOf    async (body, can, req, { offered: Set<toolId> }) → { kind, ref, plannerRef, href, … } | null
+ * @param {Function} [o.timezoneOf] (req, res) → the viewer's zone (default res.locals.displayTimezone || 'UTC')
+ * @param {object} [o.logger]
+ */
+function createAskRouter(o) {
+  need(o, ['requirePermission', 'audit', 'readingOf', 'contextOf']);
+  const A = o.ask;
+  const router = routerOf(o);
+  const logger = o.logger || A.logger;
+  const timezoneOf = o.timezoneOf || ((req, res) => (res.locals && res.locals.displayTimezone) || 'UTC');
+  const kindTool = A.contextToolFor;
+
+  /** The page context, resolved by the app — and only when its context tool is offered (the header). */
+  async function contextOf(body, can, req, toolsOff) {
+    const kind = s(body.context_kind);
+    const ref = s(body.context_ref);
+    if (!kind || !ref || !A.contextKinds.includes(kind)) return null;
+    const offered = new Set(A.catalogue.catalogueFor(can, toolsOff).map((t) => t.id));
+    const tool = kindTool(kind);
+    if (tool && !offered.has(tool)) return null;
+    const c = await o.contextOf({ context_kind: kind, context_ref: ref }, can, req, { offered });
+    if (!c || c.kind !== kind || typeof c.ref !== 'string' || !c.ref || c.ref.length > 64) return null;
+    return c;
+  }
+
+  router.post('/', o.requirePermission('ai.ask'), wrap(async (req, res) => {
+    const can = canOf(res);
+    const who = A.principalOf(req, can);
+    const question = A.run.cleanQuestion(req.body && req.body.question);
+    if (!question) return res.status(400).json(stream.refused({ text: 'Type a question first.' }));
+    if (!A.limits.take(who.id)) return res.status(429).json(stream.refused({ kind: 'busy_self', text: A.limits.BUSY_SELF }));
+    try {
+      const settings = await A.settings.read();
+      const over = await A.limits.refusal(who.id, settings);
+      if (over) return res.status(429).json(stream.refused({ kind: over.kind, text: over.message, resets: over.resets || null }));
+      // NO CONTEXT IS EVEN RESOLVED while Ask is off.
+      const context = settings.enabled ? await contextOf(req.body || {}, can, req, settings.toolsOff) : null;
+      const reading = await o.readingOf(req, can);
+      res.status(200);
+      res.setHeader('Content-Type', 'application/x-ndjson; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-store');
+      res.setHeader('X-Accel-Buffering', 'no');
+      if (typeof res.flushHeaders === 'function') res.flushHeaders();
+      const write = (x) => { if (!res.writableEnded) res.write(stream.line(x)); };
+      // THE START LINE CARRIES ONLY THE ASKER'S OWN READING — never anything about the page context.
+      write(stream.start(reading));
+      let answer = null;
+      try {
+        answer = await A.run.ask({ req, can, question, context, settings, reading, timezone: timezoneOf(req, res),
+          onStep: (st) => write(stream.step(st)) });
+      } catch (e) {
+        logger.error(`Ask: the question failed before it could be answered (${e && e.stack ? e.stack : e})`);
+      } finally {
+        try {
+          o.audit(req, 'ask.asked', { entity_type: 'ask_question', entity_id: null,
+            detail: { ref: answer ? answer.ref : null, outcome: answer ? answer.outcome : 'error',
+              lookups: answer ? answer.lookups.map((l) => l.tool) : [], context: context ? context.kind : null } });
+        } catch (e) { logger.error(`Ask: the audit line could not be written (${e && e.message ? e.message : e})`); }
+      }
+      write(answer ? stream.answer(answer) : stream.error(A.run.WORDS.error));
+      return res.end();
+    } finally {
+      A.limits.release(who.id);
+    }
+  }));
+
+  router.get('/history', o.requirePermission('ai.ask'), wrap(async (req, res) => {
+    const can = canOf(res);
+    const { rows, total } = await A.history.list(req, can);
+    res.json({
+      reading: await o.readingOf(req, can),
+      total,
+      rows: rows.map((r) => ({ ref: r.public_id, question: r.question, outcome: r.outcome, rating: r.rating, at: r.created_at,
+        partner: r.acting ? r.partner_name : null, context: r.context_ref ? { kind: r.context_kind, ref: r.context_ref } : null }))
+    });
+  }));
+
+  router.get('/q/:ref', o.requirePermission('ai.ask'), wrap(async (req, res) => {
+    if (!A.isPublicId(req.params.ref, 'ask_question')) return res.status(404).json({ error: 'not_found' });
+    const q = await A.history.one(req, canOf(res), req.params.ref);
+    if (!q || !q.result) return res.status(404).json({ error: 'not_found' });
+    res.json({ answer: q.result, at: q.created_at, rating: q.rating, stale: true });
+  }));
+
+  router.post('/q/:ref/feedback', o.requirePermission('ai.ask'), wrap(async (req, res) => {
+    if (!A.isPublicId(req.params.ref, 'ask_question')) return res.status(404).json({ error: 'not_found' });
+    const body = req.body || {};
+    const rating = s(body.rating) === 'up' ? 1 : s(body.rating) === 'down' ? -1 : null;
+    if (rating == null) return res.status(400).json({ error: 'rating is up or down' });
+    const reason = rating === -1 && A.REASONS.includes(s(body.reason)) ? s(body.reason) : null;
+    const text = rating === -1 ? s(body.text).replace(/[\u0000-\u001f\u007f]+/g, ' ').slice(0, 300) || null : null;
+    const changed = await A.history.rate(req, canOf(res), req.params.ref, { rating, reason, text });
+    if (!changed) return res.status(404).json({ error: 'not_found' });
+    o.audit(req, 'ask.feedback', { entity_type: 'ask_question', detail: { ref: req.params.ref, rating: rating === 1 ? 'up' : 'down', reason } });
+    res.json({ ok: true });
+  }));
+
+  router.contextOf = contextOf;
+  return router;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.ask, o.express, o.requirePermission, o.audit
+ * @param {object} o.endpoints      { providers(): [{id, label, kind, model, enabled}], assigned(route): [id], forRoute(route): [id] }
+ * @param {Function} o.routePolicy  (route) → { providers: [kinds] } — which provider kinds the route may ever use
+ * @param {Function} o.ai           () → the app's AI facade { configFor(id), complete(opts, cfg) }
+ * @param {Function} o.partners     async () → [{ id, name, is_house }]
+ * @param {Function} [o.onBenchChange] the app's live hook (re-fetch the page's bench regions)
+ * @param {string} [o.appName]      the review list's App column
+ * @param {string} [o.jobsHref]     the app's page where endpoints are assigned to routes (linked from the empty state)
+ * @param {object} [o.layout]       { head, tabs, foot } partial names (default partials/staff-head, admin-tabs, staff-foot)
+ * @param {Function} [o.invokeReview] (fn, ...args) → the model call (default ask.invoke('AskQuestion', fn, …))
+ */
+function createAdminRouters(o) {
+  need(o, ['requirePermission', 'audit', 'routePolicy', 'ai', 'partners']);
+  const A = o.ask;
+  const settingsRouter = routerOf(o);
+  const reviewRouter = routerOf(o);
+  const logger = o.logger || A.logger;
+  const touch = typeof o.onBenchChange === 'function' ? () => { try { o.onBenchChange(); } catch (_) { /* live is best effort */ } } : () => {};
+  const layout = { head: 'partials/staff-head', tabs: 'partials/admin-tabs', foot: 'partials/staff-foot', ...(o.layout || {}) };
+  const benchState = { running: false, endpoint: null, done: 0, of: 0, startedAt: null, error: null };
+  const model = (fn, ...args) => A.invoke(A.modelName, fn, ...args);
+
+  const kindsOf = (policy) => (policy && Array.isArray(policy.providers) && policy.providers.length ? policy.providers.join(', ') : null);
+  async function pageModel(req, errors = null, form = null) {
+    const settings = await A.settings.read();
+    const record = await A.bench.read();
+    const hash = A.prompts.promptHash();
+    const providers = new Map(((await o.endpoints.providers()) || []).map((p) => [p.id, p]));
+    const assigned = (await o.endpoints.assigned('ask')) || [];
+    const serving = (await o.endpoints.forRoute('ask')) || [];
+    const policy = o.routePolicy('ask') || {};
+    const ok = A.bench.usable(record, hash);
+    // THE GATE'S OWN VERDICT (re-review of PR #9): a control that no longer holds closes the route for every endpoint, so
+    // the page says so and never reads "passed / serving" while the gate refuses.
+    const failingControls = A.bench.controls().filter((c) => !c.held).map((c) => c.id);
+    const endpoints = [];
+    for (const [i, id] of assigned.entries()) {
+      const p = providers.get(id) || {};
+      const r = ok && record.endpoints ? record.endpoints[id] : null;
+      const current = r && r.passed ? r.fingerprint && r.fingerprint === await A.bench.fingerprintFor(id) : false;
+      let now;
+      if (!p.id) now = 'not found';
+      else if (!(p.enabled === 1 || p.enabled === true)) now = 'switched off';
+      else if (policy.providers && !policy.providers.includes(p.kind)) now = `never used — not a kind this route may use (${kindsOf(policy)})`;
+      else if (!serving.includes(id)) now = 'not serving';
+      else if (failingControls.length) now = 'skipped — a bench control no longer holds';
+      else if (!r || !r.passed) now = 'skipped — no passing bench';
+      else if (!current) now = 'skipped — benched under another configuration (model, address or engine changed)';
+      else now = 'serving';
+      endpoints.push({ order: i + 1, id, label: p.label || id, provider: p.kind || '', model: p.model || '', bench: r, now });
+    }
+    const shown = form || settings;
+    return {
+      title: 'AI assistance',
+      ask: shown,
+      canon: A.settings.CANON,
+      invalid: settings.invalid,
+      errors,
+      record: ok ? record : null,
+      staleRecord: !!(record && !ok),
+      failingControls,
+      hash,
+      endpoints,
+      tools: A.catalogue.TOOLS.map((t) => ({ id: t.id, label: t.label, permission: A.gateOf(t).join(' + '), parts: t.parts || [], remote: t.kind === 'remote',
+        on: !shown.toolsOff.includes(t.id) })),
+      benchState: { ...benchState },
+      corpusSize: A.bench.corpus().length,
+      controlsSize: A.bench.controls().length,
+      passRate: Math.round(A.bench.PASS_RATE * 100),
+      askLayout: layout,
+      // DERIVED, never typed (review of PR #9): the provider kinds the route may use, this router's own mount, the app's
+      // page for assigning endpoints (none → no link).
+      providerKinds: kindsOf(policy),
+      askAdminBase: (req && req.baseUrl) || '/admin/ai/ask',
+      jobsHref: o.jobsHref || null,
+      adminTabStyle: 'underline'
+    };
+  }
+
+  settingsRouter.get('/', o.requirePermission('ai_config.view'), wrap(async (req, res) => {
+    res.render('ask/admin', await pageModel(req));
+  }));
+
+  settingsRouter.post('/', o.requirePermission('ai_config.edit'), wrap(async (req, res) => {
+    const body = req.body || {};
+    const parsed = A.settings.parseForm(body);
+    if (parsed.errors) {
+      const before = await A.settings.read();
+      const on = [].concat(body.tools || []).map(String);
+      const form = { ...before, enabled: body.enabled === 'on', toolsOff: A.catalogue.TOOL_IDS.filter((id) => !on.includes(id)),
+        limitHour: s(body.limit_hour), limitDay: s(body.limit_day), partnerTokensDay: s(body.partner_tokens_day), retention: s(body.retention) };
+      return res.status(400).render('ask/admin', await pageModel(req, parsed.errors, form));
+    }
+    const before = await A.settings.read();
+    await A.settings.write(parsed.values);
+    const v = parsed.values;
+    o.audit(req, 'ai_config.ask_settings', { entity_type: 'ai_config', detail: { route: 'ask',
+      enabled: v.enabled, limit_hour: v.limitHour, limit_day: v.limitDay, partner_tokens_day: v.partnerTokensDay,
+      retention: v.retention, tools_off: v.toolsOff.join(', ') || '(none)', was_enabled: before.enabled } });
+    redirectWith(res, 'success', 'Ask settings saved.', req.baseUrl || '/admin/ai/ask');
+  }));
+
+  settingsRouter.post('/bench', o.requirePermission('ai_config.edit'), wrap(async (req, res) => {
+    const back = req.baseUrl || '/admin/ai/ask';
+    if (benchState.running) return redirectWith(res, 'warning', 'The ask bench is already running.', back);
+    const endpoints = (await o.endpoints.forRoute('ask')) || [];
+    if (!endpoints.length) return redirectWith(res, 'error', `No endpoint${kindsOf(o.routePolicy('ask')) ? ` (${kindsOf(o.routePolicy('ask'))})` : ''} is assigned to the Ask route yet — assign one first.`, back);
+    const ai = o.ai();
+    Object.assign(benchState, { running: true, endpoint: null, done: 0, of: 0, startedAt: new Date().toISOString(), error: null });
+    o.audit(req, 'ai_config.ask_bench', { entity_type: 'ai_config', detail: { route: 'ask', endpoints: endpoints.join(', '), cases: A.bench.corpus().length } });
+    // IN THE BACKGROUND, in this request's async context; the record is stored at the house's installation row. Each call
+    // goes to THAT endpoint's own config, the route named on the options AND the config.
+    A.bench.run({
+      endpoints,
+      completeOn: async (id, opts) => A.bench.endpointCall(ai, await ai.configFor(id))(opts),
+      onProgress: (p) => { Object.assign(benchState, { endpoint: p.endpoint, done: p.done, of: p.of }); touch(); }
+    }).then((record) => A.bench.persistAtHouse(record))
+      .catch((e) => { benchState.error = e.message; logger.error(`Ask bench failed: ${e && e.stack ? e.stack : e}`); })
+      .finally(() => { benchState.running = false; touch(); });
+    touch();
+    redirectWith(res, 'success', `The ask bench is running on ${endpoints.length} endpoint${endpoints.length === 1 ? '' : 's'} — this page follows its progress.`, back);
+  }));
+
+  reviewRouter.get('/', o.requirePermission('ai_config.view'), wrap(async (req, res) => {
+    const state = ['open', 'reviewed', 'all'].includes(s(req.query.state)) ? s(req.query.state) : 'open';
+    const partners = ((await o.partners()) || []).map((p) => ({ id: String(p.id), name: p.name, isHouse: Number(p.is_house) === 1 }));
+    const partner = partners.find((p) => p.id === s(req.query.partner)) ? s(req.query.partner) : null;
+    const reason = A.REASONS.includes(s(req.query.reason)) ? s(req.query.reason) : null;
+    const rows = ((await model('reviewList', { state, partner_id: partner, reason })) || []).map((r) => ({
+      ...r,
+      calls: (r.calls || []).map((c) => ({ ...c, args: String(c.args || '') })),
+      reasonWords: REASON_WORDS[r.feedback_reason] || null,
+      outcomeWords: OUTCOME_WORDS[r.outcome] || r.outcome
+    }));
+    res.render('ask/review', { title: 'AI assistance', rows, partners, partner, reason, state, reasons: REASON_WORDS, appName: o.appName || '', askReviewBase: req.baseUrl || '/admin/ai/ask-review',
+      askLayout: layout, adminTabStyle: 'underline' });
+  }));
+
+  reviewRouter.post('/:ref/reviewed', o.requirePermission('ai_config.edit'), wrap(async (req, res) => {
+    const back = req.baseUrl || '/admin/ai/ask-review';
+    if (!A.isPublicId(req.params.ref, 'ask_question')) return res.status(404).render('errors/404', { title: 'Not found' });
+    const changed = await model('markReviewed', req.params.ref);
+    if (!changed) return redirectWith(res, 'warning', 'That answer was already reviewed, or is no longer kept.', back);
+    o.audit(req, 'ai_config.ask_review', { entity_type: 'ask_question', detail: { ref: req.params.ref } });
+    redirectWith(res, 'success', 'Marked reviewed.', back);
+  }));
+
+  return { settingsRouter, reviewRouter, pageModel, _benchState: benchState };
+}
+
+module.exports = { createAskRouter, createAdminRouters, REASON_WORDS, OUTCOME_WORDS };

package/lib/run.js

@@ -0,0 +1,266 @@
+/**
+ * ONE ASK QUESTION, END TO END: 1 PLAN → 2 RUN → 3 ANSWER → 4 CHECK → 5 AUDIT. Extracted from the hub's and soc's
+ * lib/ask/run.js (2 Nov 2026), the stricter of each:
+ *   - `finish` NEVER THROWS (the route has flushed its stream by then): the full write; if that fails, the full ERROR write
+ *     (the hub's); if that fails, a minimal `{ outcome: 'error' }` (Soc's settle); if that fails too, the row is left for
+ *     retention's closeStale and the person is still told, in the fixed error words.
+ *   - an unoffered call is described in ITS OWN words (`calls[plan.index]`, Soc), not the plan's first call's.
+ *   - the page context's id goes back only into the tool of its own kind (`contextTools`), AFTER validation.
+ *   - Tier 1's own words (a result's `quote`) are drawn by the app beside the answer (`quotesOf`, Soc S7).
+ *
+ * RUNS INSIDE THE ASKER'S OWN REQUEST — never from a job or a timer — so every look-up carries the request's tenant
+ * context and its own `can`. Nothing here takes a partner, a scope or a permission from the question or the model.
+ *
+ * IDENTITY COMES FROM `principalOf(req, can)` ONLY (D-0169 item 8): today every app returns the session user; a remote
+ * Ask would return the user it resolved from a verified hub assertion — and nothing below changes.
+ *
+ * FIXED WORDING, NEVER THE MODEL'S, for every answer that is not a checked AI answer (the app's `words`).
+ */
+
+'use strict';
+
+const MAX_QUESTION = 500;
+const BUSY_KINDS = ['unreachable', 'timeout', 'rate_limit', 'budget', 'disabled', 'unconfigured', 'bad_response', 'unsupported', 'auth'];
+const WORD_KEYS = ['not_found', 'refused_write', 'cannot', 'cannot_plan', 'ambiguous', 'withheld', 'off', 'busy', 'error', 'nothing_to_ask'];
+
+/** The question as typed, cut and cleaned: control characters become spaces. Empty → null. */
+function cleanQuestion(q) {
+  const t = String(q == null ? '' : q).replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+  return t ? t.slice(0, MAX_QUESTION) : null;
+}
+
+/** Tier 1's own words, as the app draws them: label, text, when, which model — never seen by the answer step. */
+const quotesOf = (results) => results.filter((r) => r && r.quote && r.quote.text).map((r) => ({ label: r.quote.label, text: r.quote.text,
+  at: r.quote.at || null, model: r.quote.model || null }));
+
+const tokensOf = (r) => (r && r.usage ? (Number(r.usage.total) || (Number(r.usage.prompt) || 0) + (Number(r.usage.completion) || 0)) : 0);
+const msg = (e) => (e && e.message ? e.message : String(e));
+
+/**
+ * A loop bound to an app.
+ * @param {object} o
+ * @param {Function} o.invoke         (model, fn, ...args) → Promise — the app's db-client
+ * @param {string} [o.modelName]      the question model's registry name (default 'AskQuestion')
+ * @param {object} o.logger
+ * @param {object} o.catalogue, o.prompts, o.check  the bound modules
+ * @param {object} o.words            the fixed wording (WORD_KEYS), the app's
+ * @param {object} [o.contextTools]   { toolId: contextKind } — which tool "@context" is put back into
+ * @param {Function} [o.contextRef]   (context) → the id put back (default context.ref; the hub: context.remoteRef)
+ * @param {Function} [o.openLabel]    (kind) → the refused-write link's words (default `Open the ${kind} →`)
+ * @param {Function} o.principalOf    (req, can) → { id, name, acting, scope }
+ * @param {object} o.gate             { endpointsFor(hash), complete(opts, usable) } — the production seam
+ */
+function createRun(o) {
+  for (const k of WORD_KEYS) if (typeof (o.words || {})[k] !== 'string' || !o.words[k]) throw new Error(`ask: words.${k} is required (the app's fixed wording)`);
+  if (typeof o.principalOf !== 'function') throw new Error('ask: principalOf(req, can) is required');
+  const WORDS = Object.freeze({ ...o.words });
+  const model = o.modelName || 'AskQuestion';
+  const contextTools = { ...(o.contextTools || {}) };
+  const contextRef = typeof o.contextRef === 'function' ? o.contextRef : (c) => c.ref;
+  const openLabel = typeof o.openLabel === 'function' ? o.openLabel : (kind) => `Open the ${kind} →`;
+  const { catalogue, prompts, check, logger } = o;
+
+  /**
+   * @param {object} a
+   * @param {object} a.req, a.can, a.question, a.context, a.settings, a.timezone, a.reading, a.onStep, a.deps
+   * @returns the render model (lib/stream.js)
+   */
+  async function ask(a) {
+    const deps = { complete: o.gate.complete, endpointsFor: o.gate.endpointsFor, ...(a.deps || {}) };
+    const started = Date.now();
+    const who = o.principalOf(a.req, a.can);
+    if (!who || who.id == null) throw new Error('ask: principalOf returned no user');
+    const scope = who.scope;
+    const question = cleanQuestion(a.question);
+    const context = a.context || null;
+    const hash = prompts.promptHash();
+    const tools = catalogue.catalogueFor(a.can, a.settings.toolsOff);
+    const step = (s) => { try { if (a.onStep) a.onStep(s); } catch (_) { /* a closed stream must not stop the audit */ } };
+
+    // THE ROW FIRST, before any model call: a question that dies mid-answer still counts against its asker's limits.
+    const row = await o.invoke(model, 'open', {
+      asked_by: who.id, asked_by_name: who.name || `user ${who.id}`, acting: !!who.acting,
+      context_kind: context ? context.kind : null, context_ref: context ? context.ref : null, question, prompt_hash: hash
+    });
+    const prov = { endpoint: null, model: null, tokens: 0, planMs: 0, lookMs: 0, answerMs: 0, ms: 0, skipped: [] };
+    const lookups = [];
+    const results = [];
+    const fixed = (key, extra = {}) => ({ by: 'fixed', text: WORDS[key], chips: [], ...extra });
+    const shape = (oc, r) => ({ ...r, outcome: oc, ref: row.public_id, question, context, lookups, provenance: prov,
+      reading: a.reading || null, at: new Date().toISOString() });
+
+    /** Close the row. NEVER THROWS — three attempts, each smaller than the last (the header). */
+    const finish = async (outcome, render, answerText = null) => {
+      prov.ms = Date.now() - started;
+      const out = shape(outcome, render);
+      try {
+        await o.invoke(model, 'finish', row.id, { outcome, answer: answerText, result: out, endpoint: prov.endpoint,
+          model: prov.model, tokens: prov.tokens, ms: prov.ms });
+        return out;
+      } catch (e) {
+        logger.error(`Ask ${row.public_id}: the ${outcome} answer could not be recorded (${msg(e)})`);
+      }
+      const failed = shape('error', fixed('error'));
+      try {
+        await o.invoke(model, 'finish', row.id, { outcome: 'error', result: failed, endpoint: prov.endpoint, model: prov.model,
+          tokens: prov.tokens, ms: prov.ms });
+        return failed;
+      } catch (e) {
+        logger.error(`Ask ${row.public_id}: nor its error answer (${msg(e)}); closing it with the outcome alone`);
+      }
+      try { await o.invoke(model, 'finish', row.id, { outcome: 'error' }); } catch (e) {
+        logger.error(`Ask ${row.public_id}: left 'working' (${msg(e)}); the daily retention job closes it`);
+      }
+      return failed;
+    };
+
+    try {
+      if (!a.settings.enabled) return await finish('off', fixed('off'));
+      if (!tools.length) return await finish('cannot', fixed('nothing_to_ask'));
+      const ends = await deps.endpointsFor(hash);
+      prov.skipped = ends.skipped;
+      if (!ends.usable.length) return await finish('off', fixed('off'));
+
+      // ── 1 PLAN ─────────────────────────────────────────────────────────────────────────────────────────────────────
+      step({ n: 0, words: 'Working out what to look up…', state: 'run' });
+      let t = Date.now();
+      const planned = await deps.complete({
+        system: prompts.planSystem(tools),
+        messages: [{ role: 'user', content: prompts.planUser(question, context) }],
+        schema: catalogue.plannerSchema(tools),
+        maxTokens: 500,
+        temperature: 0
+      }, ends.usable);
+      prov.planMs = Date.now() - t;
+      prov.tokens += tokensOf(planned);
+      prov.endpoint = planned.servedBy || null;
+      prov.model = planned.model || null;
+      if (planned.skipped) prov.skipped = prov.skipped.concat(planned.skipped.map((x) => ({ endpoint: x.endpoint, why: x.skipped })));
+      const plan = catalogue.validatePlan(planned.json, tools);
+      step({ n: 0, words: 'Working out what to look up…', state: 'done' });
+      if (plan.error) {
+        logger.warn(`Ask ${row.public_id}: plan refused (${plan.error})`);
+        // A tool this person may not use reads exactly as a record that is not there — the same stream: one look-up step
+        // in THAT call's own words, then the not-found sentence.
+        if (plan.code === 'unoffered') {
+          const call = (planned.json && Array.isArray(planned.json.calls) && planned.json.calls[plan.index || 0]) || {};
+          const tool = catalogue.byId(call.tool);
+          let words = 'Looking that up';
+          try { if (tool) words = tool.describe(Object.fromEntries(Object.keys(tool.args).map((k) => [k, typeof (call.args || {})[k] === 'string' ? call.args[k].slice(0, 100) : null]))); } catch (_) { /* the default words */ }
+          step({ n: 1, words: `${words}…`, state: 'run' });
+          step({ n: 1, words: `${words}…`, state: 'done' });
+          return await finish('not_found', fixed('not_found'));
+        }
+        // The plan's error names keys the MODEL wrote: it goes to the log, never to the person (review of PR #9).
+        return await finish('cannot', fixed('cannot_plan'));
+      }
+      if (plan.intent === 'write') {
+        const link = context && context.href ? { label: openLabel(context.kind), href: context.href } : null;
+        return await finish('refused_write', fixed('refused_write', { link }));
+      }
+      if (plan.intent === 'none') return await finish('cannot', fixed('cannot'));
+      // THE NEUTRAL TOKEN: the record's own id goes back AFTER validation, and only into the tool of its own kind.
+      for (const call of plan.calls) {
+        const kind = contextTools[call.tool];
+        if (kind && call.args.ref === '@context') call.args.ref = context && context.kind === kind ? contextRef(context) : '@context';
+      }
+
+      // ── 2 RUN — each look-up in THIS request, its permission checked again at call time ────────────────────────────
+      t = Date.now();
+      const ctx = { req: a.req, can: a.can, scope, principal: who, timezone: a.timezone || 'UTC' };
+      for (const [i, call] of plan.calls.entries()) {
+        const tool = catalogue.byId(call.tool);
+        const words = tool.describe(call.args);
+        step({ n: i + 1, words: `${words}…`, state: 'run' });
+        const t0 = Date.now();
+        let result;
+        // DEFENCE IN DEPTH: validatePlan already refused a tool outside this request's catalogue; no path into a tool
+        // skips its page permissions, whatever validated the call.
+        if (!catalogue.mayUse(a.can, tool)) result = { outcome: 'not_found', count: 0, rows: [], extras: [], facts: {}, words };
+        else {
+          try {
+            result = await tool.run(ctx, call.args);
+          } catch (e) {
+            logger.error(`Ask ${row.public_id}: ${tool.id} failed — ${e && e.stack ? e.stack : e}`);
+            result = { outcome: 'error', count: 0, rows: [], extras: [], facts: {}, words };
+          }
+        }
+        if (!result || typeof result !== 'object' || !['ok', 'not_found', 'ambiguous', 'error'].includes(result.outcome)) {
+          logger.error(`Ask ${row.public_id}: ${tool.id} returned no result shape`);
+          result = { outcome: 'error', count: 0, rows: [], extras: [], facts: {}, words };
+        }
+        result.words = result.words || words;
+        result.tool = tool.id;
+        const ms = Date.now() - t0;
+        results.push(result);
+        lookups.push({ n: i + 1, tool: tool.id, words: result.words, outcome: result.outcome, count: result.count,
+          href: result.href || null, ms, label: result.label || null });
+        await o.invoke(model, 'addCall', row.id, { position: i + 1, tool: tool.id, args: call.args, outcome: result.outcome,
+          row_count: (result.rows || []).length, ms });
+        step({ n: i + 1, words: `${result.words}…`, state: 'done' });
+      }
+      prov.lookMs = Date.now() - t;
+
+      // A LOOK-UP THAT FAILED IS NOT AN EMPTY ONE.
+      if (results.some((r) => r.outcome === 'error')) return await finish('error', fixed('error'));
+      // ABSENT OR UNPERMITTED — ONE SENTENCE, AND NO MODEL WORDS.
+      if (results.some((r) => r.outcome === 'not_found')) return await finish('not_found', fixed('not_found'));
+      const amb = results.find((r) => r.outcome === 'ambiguous');
+      if (amb) {
+        return await finish('cannot', fixed('ambiguous', {
+          chips: (amb.candidates || []).map((c) => ({ count: null, label: c.title, href: c.href }))
+        }));
+      }
+
+      // ── 3 ANSWER — fenced results, a strict schema, no tools ───────────────────────────────────────────────────────
+      step({ n: results.length + 1, words: 'Writing the answer…', state: 'run' });
+      t = Date.now();
+      const m = prompts.answerMessages(question, results);
+      const answered = await deps.complete({
+        system: m.system,
+        messages: [{ role: 'user', content: m.user }],
+        schema: prompts.ANSWER_SCHEMA,
+        maxTokens: 600,
+        temperature: 0.1
+      }, ends.usable);
+      prov.answerMs = Date.now() - t;
+      prov.tokens += tokensOf(answered);
+      prov.endpoint = answered.servedBy || prov.endpoint;
+      prov.model = answered.model || prov.model;
+      step({ n: results.length + 1, words: 'Writing the answer…', state: 'done' });
+
+      // ── 4 CHECK ────────────────────────────────────────────────────────────────────────────────────────────────────
+      const verdict = check.checkAnswer(answered.json, results);
+      if (!verdict.ok) {
+        logger.warn(`Ask ${row.public_id}: answer withheld (${verdict.reason})`);
+        const raw = answered.json && typeof answered.json.answer === 'string' ? answered.json.answer : null;
+        // ONLY THE CODE reaches the person (review of PR #9): `verdict.reason` quotes the model's own words ("names “…”"), so it
+        // stays in the log above.
+        return await finish('withheld', fixed('withheld', { chips: check.chipsOf(results, null), quotes: quotesOf(results), whyCode: verdict.code }), raw);
+      }
+      const cited = new Set([...verdict.cites, ...[...verdict.answer.matchAll(/\[(r[1-4])\]/g)].map((x) => x[1])]);
+      return await finish('answered', {
+        by: 'ai',
+        segments: check.segmentsOf(verdict.answer, results),
+        chips: check.chipsOf(results, verdict.answer),
+        quotes: quotesOf(results),
+        checked: { cited: cited.size, of: cited.size }
+      }, verdict.answer);
+    } catch (e) {
+      // ── 5 AUDIT, whatever happened ─────────────────────────────────────────────────────────────────────────────────
+      const kind = e && e.kind;
+      if (Array.isArray(e && e.attempts)) prov.skipped = prov.skipped.concat(e.attempts.filter((x) => x.skipped).map((x) => ({ endpoint: x.endpoint, why: x.skipped })));
+      if (kind === 'config') return finish('off', fixed('off'));
+      if (BUSY_KINDS.includes(kind) || (e && e.attempts)) {
+        logger.warn(`Ask ${row.public_id}: no endpoint answered (${msg(e)})`);
+        return finish('busy', fixed('busy'));
+      }
+      logger.error(`Ask ${row.public_id}: ${e && e.stack ? e.stack : e}`);
+      return finish('error', fixed('error'));
+    }
+  }
+
+  return { ask, cleanQuestion, quotesOf, WORDS, MAX_QUESTION };
+}
+
+module.exports = { createRun, cleanQuestion, quotesOf, MAX_QUESTION, WORD_KEYS, BUSY_KINDS };