@aria-framework/ask 0.0.0-stage → 0.1.0

package/lib/docs.js

@@ -0,0 +1,306 @@
+/**
+ * THE HELP PAGES' INDEX — what `docs.search` reads. The mechanism is shared; the PAGES stay the app's (`helpDir`, its
+ * docs/help/*.md, house-written and reviewed like code — no upload, no editor, no table).
+ *
+ * A PAGE:   ---\n id: <file name>\n title: <title>\n needs: <permission ids, comma-separated>\n ---\n <intro>\n ## <heading>\n <text>…
+ * PASSAGE:  the intro and each `## ` section, verbatim, keyed `help:<id>#<anchor>` — what a search returns.
+ *
+ * TWO WAYS TO MATCH:
+ *   WORDS    a BM25 index over title + heading + text, loaded on first use and CHECKED AT BOOT (checkAtBoot — a malformed
+ *            page stops the boot). Its statistics are per request (statsOf): a page hidden from the asker cannot move
+ *            their ranking.
+ *   MEANING  each passage's embedding, made at boot on route `ask-docs` at the HOUSE's scope (asHouse), kept in memory. At
+ *            question time only the QUESTION is embedded, in the asker's own request. A question NEVER waits for the
+ *            index: missing or built on another engine → words, and ONE background rebuild (at most every REBUILD_EVERY_MS).
+ *
+ * RBAC: a page names in `needs` the permission(s) of the feature it describes; a search sees only the pages whose every
+ * permission the request holds. A page about something the person cannot do is ABSENT for them.
+ *
+ * Extracted from the hub's and soc's lib/ask/docs.js (identical but for comments, 2 Nov 2026).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { cut: cutText } = require('./common');
+
+const ROUTE = 'ask-docs';
+const MAX_SECTION = 600;
+const MAX_INTRO = 300;
+const MAX_HITS = 4;
+const MIN_COSINE = 0.5;
+const MIN_COVER = 0.5;
+const REBUILD_EVERY_MS = 10 * 60 * 1000;
+
+const STOP = new Set(('a an and are as at be by can do does for from has have how i if in is it its me my of on or our '
+  + 'please the their them then there these this to us was we what when where which who why will with you your'
+  + ' should would could get').split(' '));
+
+/** A crude stem, the same for pages and questions: a plural s, -ing and -ed folded (adding → add, acting → act). */
+function stem(w) {
+  let x = w;
+  if (x.length > 3 && x.endsWith('s') && !x.endsWith('ss')) x = x.slice(0, -1);
+  if (x.length > 5 && x.endsWith('ing')) x = x.slice(0, -3);
+  else if (x.length > 4 && x.endsWith('ed')) x = x.slice(0, -2);
+  if (x.length > 3 && x[x.length - 1] === x[x.length - 2] && !/(ss|ll)$/.test(x)) x = x.slice(0, -1);
+  return x;
+}
+
+/** Words of a text: NFKC, lower case, letters and digits, stop words out, each stemmed. */
+function tokens(text) {
+  return String(text || '').normalize('NFKC').toLowerCase().split(/[^\p{L}\p{N}]+/u)
+    .filter((w) => w.length > 1 && !STOP.has(w))
+    .map(stem);
+}
+
+const anchorOf = (heading) => String(heading).toLowerCase().normalize('NFKC').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '') || 'section';
+
+/** One page from its file. Throws a sentence naming the file and what is wrong. */
+function parsePage(file, text, known) {
+  const fail = (why) => { throw new Error(`help page ${file}: ${why}`); };
+  const src = String(text).replace(/\r\n/g, '\n');
+  const m = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(src);
+  if (!m) fail('no front matter (--- id / title / needs ---)');
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const kv = /^([a-z]+):\s*(.*)$/.exec(line.trim());
+    if (!kv) fail(`front matter line "${line.slice(0, 40)}" is not "key: value"`);
+    meta[kv[1]] = kv[2].trim();
+  }
+  const extra = Object.keys(meta).filter((k) => !['id', 'title', 'needs'].includes(k));
+  if (extra.length) fail(`unknown front matter ${extra.join(', ')}`);
+  const id = file.replace(/\.md$/, '');
+  if (meta.id !== id) fail(`id "${meta.id}" is not the file name "${id}"`);
+  if (!/^[a-z][a-z-]{1,60}$/.test(id)) fail('the id is not lower-case words joined by hyphens');
+  if (!meta.title) fail('no title');
+  const needs = String(meta.needs || '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (!needs.length) fail('needs names no permission (a page about Ask itself needs ai.ask)');
+  for (const p of needs) if (!known.includes(p)) fail(`needs "${p}", which is not a permission of this app`);
+  const parts = m[2].split(/^## /m);
+  const intro = parts.shift().trim();
+  if (!intro) fail('no intro before the first section');
+  if (intro.length > MAX_INTRO) fail(`the intro is ${intro.length} characters (at most ${MAX_INTRO})`);
+  if (!parts.length) fail('no ## section');
+  const sections = [{ anchor: 'about', heading: null, text: intro.replace(/\s+/g, ' ') }];
+  const seen = new Set(['about']);
+  for (const part of parts) {
+    const nl = part.indexOf('\n');
+    const heading = (nl < 0 ? part : part.slice(0, nl)).trim();
+    const body = (nl < 0 ? '' : part.slice(nl + 1)).trim().replace(/\s+/g, ' ');
+    if (!heading || !body) fail(`section "${heading}" is empty`);
+    if (/^#/m.test(body)) fail(`section "${heading}" holds a heading of another level (only ## sections)`);
+    if (heading.length + body.length > MAX_SECTION) fail(`section "${heading}" is ${heading.length + body.length} characters (at most ${MAX_SECTION})`);
+    const anchor = anchorOf(heading);
+    if (seen.has(anchor)) fail(`two sections are called "${heading}"`);
+    seen.add(anchor);
+    sections.push({ anchor, heading, text: body });
+  }
+  return { id, title: meta.title, needs, sections };
+}
+
+/** The passages of parsed pages. NO corpus-wide statistics: those are taken per search over what THAT request may see. */
+function corpusOf(pages) {
+  const passages = [];
+  for (const p of pages) {
+    for (const s of p.sections) {
+      const toks = tokens(`${p.title} ${s.heading || ''} ${s.text}`);
+      passages.push({ ref: `help:${p.id}#${s.anchor}`, page: p.id, pageTitle: p.title, heading: s.heading, text: s.text, needs: p.needs,
+        tf: toks.reduce((m, t) => m.set(t, (m.get(t) || 0) + 1), new Map()), len: toks.length });
+    }
+  }
+  const hash = crypto.createHash('sha256').update(JSON.stringify(passages.map((x) => [x.ref, x.pageTitle, x.heading, x.text]))).digest('hex');
+  return { pages, passages, hash };
+}
+
+/** BM25's statistics over ONE request's visible passages. */
+function statsOf(passages) {
+  const df = new Map();
+  for (const ps of passages) for (const t of ps.tf.keys()) df.set(t, (df.get(t) || 0) + 1);
+  const N = passages.length;
+  return {
+    idf: new Map([...df].map(([t, n]) => [t, Math.log(1 + (N - n + 0.5) / (n + 0.5))])),
+    avgLen: N ? passages.reduce((s, x) => s + x.len, 0) / N : 0,
+    unseen: Math.log(1 + (N + 0.5) / 0.5)
+  };
+}
+
+const cosine = (a, b) => {
+  let d = 0; let na = 0; let nb = 0;
+  for (let i = 0; i < a.length; i += 1) { d += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  return na && nb ? d / Math.sqrt(na * nb) : 0;
+};
+
+/** Did the same machine running the same model make the index and this question's vector? */
+function sameEngine(v, out, qv) {
+  if (!Array.isArray(qv) || qv.length !== v.dims) return false;
+  if (v.endpoint && out.servedBy && out.servedBy !== v.endpoint) return false;
+  const model = out.model || null;
+  if ((v.model || model) && v.model !== model) return false;
+  return true;
+}
+
+/**
+ * A help index bound to an app.
+ * @param {object} o
+ * @param {string} o.helpDir          the app's docs/help directory
+ * @param {Function|string[]} o.permissions   every permission id the app has (or a function returning them)
+ * @param {Function|null} [o.embed]   (texts) → { vectors, servedBy, model } on route ask-docs; null = words only
+ * @param {Function} [o.asHouse]      (fn) → fn() at the house's scope (the index's ledger rows land on the house)
+ * @param {object} o.logger
+ */
+function createDocs(o) {
+  const known = () => (typeof o.permissions === 'function' ? o.permissions() : o.permissions) || [];
+  const loadCorpus = (dir = o.helpDir, perms = known()) => {
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+    return corpusOf(files.map((f) => parsePage(f, fs.readFileSync(path.join(dir, f), 'utf8'), perms)));
+  };
+  let helpDir = o.helpDir;
+  let corpus = null;
+  let vectors = null;
+  let building = null;
+  let lastTry = 0;
+  let rebuildEvery = REBUILD_EVERY_MS;
+  let embedder = o.embed === undefined ? null : o.embed;
+  const asHouse = typeof o.asHouse === 'function' ? o.asHouse : (fn) => fn();
+
+  const current = () => (corpus || (corpus = loadCorpus(helpDir)));
+  function checkAtBoot() { const c = current(); return { pages: c.pages.length, passages: c.passages.length }; }
+  function useCorpus(c) { const was = { corpus, vectors }; corpus = c; vectors = null; return () => { corpus = was.corpus; vectors = was.vectors; }; }
+  function useHelpDir(dir) { const was = { helpDir, corpus, vectors }; helpDir = dir; corpus = null; vectors = null; return () => { helpDir = was.helpDir; corpus = was.corpus; vectors = was.vectors; }; }
+  function useEmbedder(fn) { const was = embedder; embedder = fn; return () => { embedder = was; }; }
+  function useRebuildEvery(ms) { const was = rebuildEvery; rebuildEvery = ms; lastTry = 0; return () => { rebuildEvery = was; }; }
+  const whenBuilt = () => building || Promise.resolve(null);
+  const mayRebuild = () => embedder && !building && Date.now() - lastTry >= rebuildEvery;
+
+  /** BUILD THE MEANING INDEX. NEVER THROWS: with no engine, or pages that do not load, the index stays words-only. */
+  function build() {
+    if (building) return building;
+    if (!embedder) return Promise.resolve({ ok: false, why: 'no embedding call' });
+    lastTry = Date.now();
+    // DEFERRED ONE TICK: a body that failed before its first await would otherwise run its `finally` before `building`
+    // is assigned below, and leave `building` pointing at the failed promise for good.
+    building = Promise.resolve().then(async () => {
+      try {
+        const c = current();
+        const texts = c.passages.map((p) => `${p.pageTitle}. ${p.heading ? `${p.heading}. ` : ''}${p.text}`);
+        const out = await asHouse(() => embedder(texts));
+        const list = Array.from(out.vectors || []);
+        if (list.length !== texts.length || list.some((v) => !Array.isArray(v) || !v.length)) throw new Error(`the engine returned ${list.length} vectors for ${texts.length} passages`);
+        const dims = list[0].length;
+        if (list.some((v) => v.length !== dims)) throw new Error('the vectors are not all the same width');
+        const model = out.model || null;
+        if (corpus === c) vectors = { hash: c.hash, endpoint: out.servedBy || null, model, dims, list };
+        o.logger.info(`Ask help pages: ${list.length} passages indexed by meaning on ${out.servedBy || 'the explicit endpoint'}${model ? ` (${model})` : ''}`);
+        return { ok: true, endpoint: out.servedBy || null, model, passages: list.length };
+      } catch (e) {
+        o.logger.warn(`Ask help pages: words only — the meaning index was not built (${e && e.message ? e.message : e})`);
+        return { ok: false, why: e && e.message ? e.message : String(e) };
+      } finally {
+        building = null;
+      }
+    });
+    return building;
+  }
+
+  /** SEARCH, in the asker's own request: { hits (≤ MAX_HITS, best first), by: 'words' | 'words and meaning', why? }. */
+  async function search(query, can) {
+    const c = current();
+    const held = (p) => p.needs.every((n) => typeof can === 'function' && can(n) === true);
+    const allowed = c.passages.filter(held);
+    const { idf, avgLen, unseen } = statsOf(allowed);
+    const q = [...new Set(tokens(query))];
+    const k1 = 1.2;
+    const b = 0.75;
+    const wordScores = allowed.map((p) => q.reduce((s, t) => {
+      const f = p.tf.get(t) || 0;
+      return f ? s + idf.get(t) * ((f * (k1 + 1)) / (f + k1 * (1 - b + (b * p.len) / (avgLen || 1)))) : s;
+    }, 0));
+    const weight = q.reduce((s, t) => s + (idf.get(t) || unseen), 0);
+    const cover = allowed.map((p) => (weight ? q.reduce((s, t) => s + (p.tf.has(t) ? idf.get(t) : 0), 0) / weight : 0));
+    let meaning = null;
+    let why = null;
+    const v = vectors && vectors.hash === c.hash ? vectors : null;
+    if (!v) {
+      why = 'the meaning index is not built';
+      if (mayRebuild()) build();
+    } else if (allowed.length && q.length) {
+      try {
+        const out = await embedder([String(query)]);
+        const qv = Array.from(out.vectors || [])[0];
+        if (!sameEngine(v, out, qv)) {
+          why = 'the question was embedded by another engine or model than the index';
+          if (mayRebuild()) build();
+        } else {
+          const at = new Map(c.passages.map((p, i) => [p.ref, i]));
+          meaning = allowed.map((p) => cosine(qv, v.list[at.get(p.ref)]));
+        }
+      } catch (e) {
+        why = `the question could not be embedded (${e && e.kind ? e.kind : 'error'})`;
+      }
+    }
+    const top = Math.max(0, ...wordScores);
+    const scored = allowed.map((p, i) => {
+      const w = top ? wordScores[i] / top : 0;
+      const m = meaning ? meaning[i] : 0;
+      const hit = cover[i] >= MIN_COVER || (meaning && m >= MIN_COSINE);
+      return { p, hit, score: meaning ? (w + m) / 2 : w };
+    }).filter((x) => x.hit).sort((x, y) => y.score - x.score || (x.p.ref < y.p.ref ? -1 : 1));
+    const best = scored.length ? scored[0].score : 0;
+    const hits = scored.filter((x) => x.score >= best / 4).slice(0, MAX_HITS).map((x) => x.p);
+    return { hits, by: meaning ? 'words and meaning' : 'words', why };
+  }
+
+  function status() {
+    const c = current();
+    return { pages: c.pages.length, passages: c.passages.length, hash: c.hash,
+      meaning: !!(vectors && vectors.hash === c.hash), endpoint: vectors ? vectors.endpoint : null, model: vectors ? vectors.model : null };
+  }
+
+  return { ROUTE, MAX_SECTION, MAX_INTRO, MAX_HITS, tokens, parsePage, loadCorpus, corpusOf, statsOf, current, checkAtBoot,
+    build, search, status, whenBuilt, useCorpus, useHelpDir, useEmbedder, useRebuildEvery };
+}
+
+/**
+ * The `docs.search` tool over a help index. `gate` is how the app's tool declares its permission — `{permission:'ai.ask'}`
+ * (the hub) or `{permissions:['ai.ask']}` (soc) — and `queryType` its query argument's type ('string' hub, 'text'
+ * Soc): both are in the catalogue hash, so each app passes what its tool declared and its hash is unchanged. New apps:
+ * `{ permissions: ['ai.ask'] }` and 'text'.
+ */
+function docsTool(docs, { gate = { permissions: ['ai.ask'] }, queryType = 'text', benchQuestion = 'How do I add a site?', cut = cutText } = {}) {
+  const tool = {
+    id: 'docs.search',
+    label: 'Search the help pages',
+    ...gate,
+    description: 'Search the help pages for how to do something in this app (how to add, find, change or set up '
+      + 'something, or what a screen or state means). Returns the matching help passages.',
+    args: {
+      query: { type: queryType, nullable: false, max: 100, describe: 'what the person wants to know how to do, in a few words' }
+    },
+    attackerFields: ['rows[].title', 'rows[].fields.text'],
+    benchQuestion,
+    describe(args) {
+      return args.query ? `Help pages about “${cut(args.query, 100)}”` : 'Help pages';
+    },
+    async run(ctx, args) {
+      const found = await docs.search(String(args.query || '').slice(0, 100), ctx.can);
+      const words = `${tool.describe(args)}${found.by === 'words' ? ' (matched by words only)' : ''}`;
+      if (!found.hits.length) return { outcome: 'not_found', count: 0, label: null, href: null, rows: [], facts: {}, extras: [], words };
+      return {
+        outcome: 'ok',
+        count: found.hits.length,
+        label: found.hits.length === 1 ? 'help passage' : 'help passages',
+        href: null,
+        rows: found.hits.map((p) => ({ ref: p.ref, title: p.heading ? `${p.pageTitle} — ${p.heading}` : p.pageTitle, fields: { text: p.text } })),
+        facts: {},
+        extras: [],
+        words,
+        help: true
+      };
+    }
+  };
+  return tool;
+}
+
+module.exports = { createDocs, docsTool, tokens, stem, parsePage, corpusOf, statsOf, ROUTE, MAX_SECTION, MAX_INTRO, MAX_HITS };

package/lib/gate.js

@@ -0,0 +1,44 @@
+/**
+ * Which machines may answer an Ask question, and the call to them (the apps' lib/ask/model.js). THREE FILTERS, IN ORDER:
+ *
+ *   1. the route's own list — EXPLICIT ONLY and lmx ONLY (the app's AI route table, `ask`): nobody chose → nothing → off;
+ *   2. THE BINDING BENCH GATE: an endpoint without a passing bench record for the CURRENT prompt hash, the CURRENT scorer
+ *      (bench.usable — soc's N5, now every app's) and its current configuration (bench.fingerprintFor) is skipped;
+ *      AND EVERY CONTROL HOLDS NOW (review H3 of PR #9): the controls are re-run, with no model, on every question — a fence
+ *      that stopped holding closes the route for every endpoint, whatever the stored record says;
+ *   3. the dispatcher's own walk, narrowed to what survived (`endpoints` can only remove, never add).
+ *
+ * If 1 or 2 leave nothing, Ask is OFF for everyone. If 3 skips everything, the person is told the AI is BUSY.
+ */
+
+'use strict';
+
+const ROUTE = 'ask';
+const SKIP = 'no passing ask bench for the current prompt and configuration';
+const CONTROL = 'a bench control no longer holds — the app’s own fences changed since the bench';
+
+/** @param {{forRoute: (route) => Promise<string[]>, bench, ai: () => {complete}}} o */
+function createGate(o) {
+  async function endpointsFor(hash) {
+    const assigned = (await o.forRoute(ROUTE)) || [];
+    const record = await o.bench.read();
+    const usable = [];
+    const skipped = [];
+    const failing = o.bench.controls().filter((c) => !c.held).map((c) => c.id);
+    if (failing.length) return { assigned, usable, skipped: assigned.map((id) => ({ endpoint: id, why: `${CONTROL} (${failing.join(', ')})` })), failingControls: failing };
+    const ok = o.bench.usable(record, hash);
+    for (const id of assigned) {
+      const r = ok && record.endpoints && record.endpoints[id];
+      if (r && r.passed === true && r.fingerprint && r.fingerprint === await o.bench.fingerprintFor(id)) usable.push(id);
+      else skipped.push({ endpoint: id, why: SKIP });
+    }
+    return { assigned, usable, skipped };
+  }
+  /** The real call: the dispatcher, on route `ask`, narrowed to the bench-passing endpoints. */
+  function complete(opts, usable) {
+    return o.ai().complete({ ...opts, route: ROUTE, endpoints: usable, reasoning: 'off' });
+  }
+  return { endpointsFor, complete, ROUTE };
+}
+
+module.exports = { createGate, ROUTE, SKIP, CONTROL };

package/lib/history.js

@@ -0,0 +1,32 @@
+/**
+ * A person's own Ask history (the last 20, kept per the retention setting) and their thumbs mark.
+ *
+ * ONE PERSON'S ROWS SPAN PARTNERS, so each read widens to platform scope around ONE model call bounded by `asked_by = <the
+ * principal's id>` — the model refuses any other scope. The id comes from `principalOf` (the session today), never from
+ * the request: nothing a person sends can name somebody else's history, and another person's ref reads as none.
+ */
+
+'use strict';
+
+/** @param {{invoke, asPlatform, principalOf, modelName?}} o */
+function createHistory(o) {
+  const model = o.modelName || 'AskQuestion';
+  const meOf = (req, can) => {
+    const p = o.principalOf(req, can);
+    if (!p || p.id == null) throw new Error('ask history: needs a signed-in user');
+    return Number(p.id);
+  };
+  async function list(req, can) {
+    const me = meOf(req, can);
+    const [rows, total] = await Promise.all([
+      o.asPlatform(() => o.invoke(model, 'historyFor', me, { limit: 20 })),
+      o.asPlatform(() => o.invoke(model, 'historyCountFor', me))
+    ]);
+    return { rows, total };
+  }
+  const one = (req, can, ref) => { const me = meOf(req, can); return o.asPlatform(() => o.invoke(model, 'oneFor', me, String(ref))); };
+  const rate = (req, can, ref, mark) => { const me = meOf(req, can); return o.asPlatform(() => o.invoke(model, 'rate', me, String(ref), mark)); };
+  return { list, one, rate };
+}
+
+module.exports = { createHistory };

package/lib/limits.js

@@ -0,0 +1,56 @@
+/**
+ * Ask's limits: one question in flight per person, N an hour and M a day per person, and a per-partner token budget a
+ * day. Over any of them the person gets a plain line saying which limit and when it resets — never a silent failure.
+ * Extracted from the hub's and soc's lib/ask/limits.js (identical but for comments).
+ *
+ * PER PERSON MEANS IN EVERY PARTNER: a house operator's questions at the house and inside two partners are one person's,
+ * so the count widens (asPlatform) around ONE read keyed on the session's own user id (the model refuses any other scope).
+ * PER PARTNER MEANS THE PARTNER THE QUESTION IS ASKED IN (the request's scope; the model states the tenant). A day runs
+ * midnight to midnight UTC.
+ *
+ * ONE AT A TIME is held in this process (a Set of user ids), released in a `finally` by the caller. A second process
+ * would hold its own — acceptable for a limit whose job is "do not stack questions", not a security boundary.
+ */
+
+'use strict';
+
+const stored = (ms) => new Date(ms).toISOString().slice(0, 19).replace('T', ' ');
+const dayStart = (now) => `${new Date(now).toISOString().slice(0, 10)} 00:00:00`;
+const BUSY_SELF = 'One question at a time — this one is still being answered.';
+
+/** @param {{invoke, asPlatform, modelName?}} o */
+function createLimits(o) {
+  const model = o.modelName || 'AskQuestion';
+  const inFlight = new Set();
+
+  /** Is this person over a limit? Returns null, or { kind: 'hour'|'day'|'partner', message, resets }. */
+  async function refusal(userId, settings, now = Date.now()) {
+    const hour = await o.asPlatform(() => o.invoke(model, 'countSince', Number(userId), stored(now - 3600000)));
+    if (hour >= settings.limitHour) {
+      return { kind: 'hour', message: `You’ve reached this hour’s limit of ${settings.limitHour} questions.`, resets: 'within the hour' };
+    }
+    const day = await o.asPlatform(() => o.invoke(model, 'countSince', Number(userId), dayStart(now)));
+    if (day >= settings.limitDay) {
+      return { kind: 'day', message: `You’ve reached today’s limit of ${settings.limitDay} questions.`, resets: 'midnight UTC' };
+    }
+    if (settings.partnerTokensDay > 0) {
+      const spent = await o.invoke(model, 'partnerTokensSince', dayStart(now));
+      if (spent >= settings.partnerTokensDay) {
+        return { kind: 'partner', message: 'Your organisation has used today’s Ask allowance.', resets: 'midnight UTC' };
+      }
+    }
+    return null;
+  }
+
+  /** Take the one-at-a-time slot; false if already held. Synchronous, so two requests cannot both pass. */
+  function take(userId) {
+    if (inFlight.has(Number(userId))) return false;
+    inFlight.add(Number(userId));
+    return true;
+  }
+  const release = (userId) => { inFlight.delete(Number(userId)); };
+
+  return { refusal, take, release, BUSY_SELF };
+}
+
+module.exports = { createLimits, BUSY_SELF, dayStart, stored };

package/lib/prompts.js

@@ -0,0 +1,95 @@
+/**
+ * The two prompts of an Ask question, and what the model is allowed to see. The MACHINERY is shared; the WORDS are the
+ * app's (D-0169 item 6) and are passed in.
+ *
+ *   PLAN    sees the question, the page context as a REF only (or the neutral token "@context") and the tools this person
+ *           may use. It sees NO DATA, so nothing an attacker wrote can steer which look-ups run.
+ *   ANSWER  sees the question and the look-ups' results as ONE FENCED DOCUMENT (@aria-framework/ai `fenced` — a random
+ *           per-call marker), through `modelView`: refs, names, fields and counts — never numeric ids, never hrefs, never a
+ *           result's `quote` (another model's words, drawn by the app beside the answer). It has no tools.
+ *
+ * THE PROMPT HASH (`promptHash`) is `sha256(JSON.stringify({v:1, app, plan, answer, answerSchema, tools}))` — the hub's
+ * and soc's exact document, with `app` undefined for the hub (JSON.stringify drops it) and 'soc' for Soc. So an app
+ * that passes its own rule texts byte-for-byte keeps its hash, and its bench record, through adoption (test/hashes.js).
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+/** The answer's strict schema. Byte-identical to both apps' copies — it is in the prompt hash. */
+const ANSWER_SCHEMA = Object.freeze({
+  name: 'ask_answer',
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['answer', 'cites'],
+    properties: {
+      answer: { type: 'string', minLength: 1, maxLength: 700 },
+      cites: { type: 'array', maxItems: 8, items: { type: 'string', pattern: '^r[1-4]$' } }
+    }
+  }
+});
+
+/** The prompt document's hash — exported so an app's test-ask-hashes.js can pin it from its own inputs. */
+function promptHashOf({ app, plan, answer, answerSchema = ANSWER_SCHEMA, toolsHash }) {
+  const doc = JSON.stringify({ v: 1, app, plan, answer, answerSchema, tools: toolsHash });
+  return crypto.createHash('sha256').update(doc).digest('hex');
+}
+
+/**
+ * What the model may read of the results: per result its id, the look-up in words, the outcome, the count, the extra
+ * figures' keys and labels (never their hrefs), the facts, and each row's ref, title and fields.
+ */
+function modelView(results) {
+  return results.map((r, i) => ({
+    id: `r${i + 1}`,
+    look_up: r.words,
+    outcome: r.outcome,
+    count: r.count,
+    counted: r.label || null,
+    extra_figures: (r.extras || []).map((x) => ({ key: x.key, counted: x.label, count: x.count })),
+    facts: r.facts || {},
+    rows: (r.rows || []).map((row) => ({ ref: row.ref, title: row.title, ...(row.fields || {}) }))
+  }));
+}
+
+const FIELDS_SENTENCE = 'The document has fields "question" and "results"; each result has "id", "look_up", "outcome", "count", '
+  + '"counted", "extra_figures", "facts" and "rows".';
+
+/**
+ * Prompts bound to an app's words.
+ * @param {object} o
+ * @param {object} o.catalogue        createCatalogue's result
+ * @param {string} o.planRules        the planner's rules (the app's PLAN_RULES, verbatim)
+ * @param {string} o.answerRules      the answer step's rules, with the worked example already in them
+ * @param {{results, reply}} o.example the worked example the rules carry (held to the check by the app's tests)
+ * @param {Function} o.contextSentence (context) → the planner's page-context sentence ('' for none) — starts with "\n"
+ * @param {string} o.fenceWhat        what the fenced document holds, in the app's words
+ * @param {string} [o.hashApp]        'soc' for soc; undefined for the hub; a new app names itself
+ * @param {object} o.fenced           @aria-framework/ai's `fenced` (injected so tests can pass the same module)
+ * @param {Function} [o.onLeak]       a fence marker found inside the data (log it)
+ */
+function createPrompts(o) {
+  for (const k of ['planRules', 'answerRules', 'fenceWhat']) if (typeof o[k] !== 'string' || !o[k]) throw new Error(`ask prompts: ${k} is required (the app's own words)`);
+  if (!o.example || !Array.isArray(o.example.results) || !o.example.reply) throw new Error('ask prompts: example {results, reply} is required');
+  if (!o.answerRules.includes(JSON.stringify(o.example.reply))) throw new Error('ask prompts: the answer rules do not carry the worked example verbatim');
+  if (typeof o.contextSentence !== 'function') throw new Error('ask prompts: contextSentence(context) is required');
+  if (!o.fenced || typeof o.fenced.fencedDocument !== 'function') throw new Error('ask prompts: fenced (from @aria-framework/ai) is required');
+  const { catalogue } = o;
+
+  const planSystem = (tools) => `${o.planRules}\n\nTools:\n${catalogue.describeTools(tools)}`;
+  const planUser = (question, context) => `Question: ${String(question)}${context ? String(o.contextSentence(context) || '') : ''}`;
+
+  function answerMessages(question, results) {
+    const { block, rule } = o.fenced.fencedDocument('the look-up results', { question: String(question), results: modelView(results) },
+      { what: o.fenceWhat, onLeak: o.onLeak });
+    return { system: `${o.answerRules}\n\n${FIELDS_SENTENCE} ${rule}`, user: block };
+  }
+
+  const promptHash = () => promptHashOf({ app: o.hashApp, plan: o.planRules, answer: o.answerRules, toolsHash: catalogue.catalogueHash() });
+
+  return { EXAMPLE: o.example, PLAN_RULES: o.planRules, ANSWER_RULES: o.answerRules, ANSWER_SCHEMA, planSystem, planUser, modelView, answerMessages, promptHash };
+}
+
+module.exports = { createPrompts, promptHashOf, modelView, ANSWER_SCHEMA, FIELDS_SENTENCE };

package/lib/retention.js

@@ -0,0 +1,48 @@
+/**
+ * Ask's retention: questions and look-ups kept 30 days by default (30, 90, or "as long as the audit trail"). Run daily by
+ * the app's scheduler at the HOUSE's platform reach; deletes every question created before the cut, and their look-ups
+ * go with them (ON DELETE CASCADE). The audit sentence `ask.asked` is in the audit trail and is NOT touched here.
+ *
+ * FIRST, WHATEVER THE RETENTION (soc review S1 of PR #153, now every app's): a row still `working` STALE_MINUTES after
+ * it was opened will never finish — its finish could not be written — and is closed as `error`, so none outlives a day.
+ *
+ * "AS LONG AS THE AUDIT TRAIL" asks the app (`auditDays()`): 0 or less there means the audit trail is kept forever, and so
+ * are the questions.
+ */
+
+'use strict';
+
+// A question runs for seconds (a minute at the very most); one still `working` after this has lost its finish.
+const STALE_MINUTES = 15;
+const utc = (ms) => new Date(ms).toISOString().slice(0, 19).replace('T', ' ');
+
+/**
+ * @param {{invoke, settings, auditDays: () => Promise<number>|number, asHouse?: Function, modelName?}} o — `purge` runs inside
+ * asHouse itself (installation-wide reach), so a scheduler line that forgot the wrapper cannot run it at a partner's scope.
+ */
+function createRetention(o) {
+  const model = o.modelName || 'AskQuestion';
+  if (typeof o.auditDays !== 'function') throw new Error('ask retention: auditDays() is required (the "as long as the audit trail" choice)');
+
+  /** The cut for a retention choice, or null (keep everything). */
+  async function cutFor(retention, now = Date.now()) {
+    const days = retention === 'audit' ? Number(await o.auditDays()) : Number(retention);
+    if (!Number.isInteger(days) || days <= 0) return null;
+    return utc(now - days * 86400000);
+  }
+
+  /** Close stuck rows, then delete what is past the window. Returns { succeeded, closed, deleted, failed: 0 }. */
+  const asHouse = typeof o.asHouse === 'function' ? o.asHouse : (fn) => fn();
+  const purge = (now = Date.now()) => asHouse(() => purgeNow(now));
+  async function purgeNow(now) {
+    const closed = Number(await o.invoke(model, 'closeStale', utc(now - STALE_MINUTES * 60000))) || 0;
+    const s = await o.settings.read();
+    const cut = await cutFor(s.retention, now);
+    const deleted = cut ? Number(await o.invoke(model, 'purgeBefore', cut)) || 0 : 0;
+    return { succeeded: closed + deleted, closed, deleted, failed: 0 };
+  }
+
+  return { cutFor, purge, STALE_MINUTES };
+}
+
+module.exports = { createRetention, STALE_MINUTES };