@aria-framework/ask 0.0.0-stage → 0.1.0

package/lib/catalogue.js

@@ -0,0 +1,230 @@
+/**
+ * The Ask tool catalogue — THE list of look-ups the AI may plan, and the planner's contract derived from it.
+ *
+ * Extracted from the hub's and soc's lib/ask/catalogue.js (2 Nov 2026). The STRICTER of the two in each place:
+ *   - `mayUse` needs EVERY permission of a tool's list, each answer exactly `true` (Soc review B1: one permission of two
+ *     let a page's content through). A tool may declare `permission` (one) or `permissions` (a list); the GATE normalises
+ *     the first to `[permission]`, the HASH serialises what the tool declared (see `catalogueHash`).
+ *   - `validatePlan` names the index of an unoffered call, so the loop can describe THAT call (Soc review nit).
+ *
+ * WHAT THE PLANNER IS OFFERED IS DERIVED, PER PERSON, PER REQUEST (`catalogueFor`): every tool whose page permissions the
+ * request holds (`can`, the request's own) and that the platform has not switched off. A tool the person lacks is NOT IN
+ * THE SCHEMA, so it cannot be emitted, and a call to it that arrives anyway is refused by `validatePlan` — never run.
+ *
+ * THE SCHEMA IS STRICT AND CLOSED (`plannerSchema`): `intent` is lookup | write | none; `calls` is at most MAX_CALLS of
+ * `{tool, args}` with exactly that tool's declared arguments (nullable where optional), enums for every closed value and a
+ * length bound on every string. THE REPLY IS VALIDATED AGAIN (`validatePlan`), whatever the provider claims.
+ *
+ * REMOTE TOOLS (D-0169 item 8, interface only): a tool may be declared `{ id, kind: 'remote', service, ... }` — another
+ * app's own Ask, answering for the same person. 0.1.0 VALIDATES the shape and NEVER OFFERS it (`catalogueFor` leaves it
+ * out), so nothing reaches another app until the SSO plan builds the call. Its results, when they exist, are attacker
+ * text throughout (check.js reads an unknown or remote tool's every path that way).
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const MAX_CALLS = 4;
+const INTENTS = ['lookup', 'write', 'none'];
+const ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+
+/** The permissions a tool's page is gated by, as a list — `permission: 'x'` is `['x']`. */
+function gateOf(tool) {
+  if (Array.isArray(tool.permissions)) return tool.permissions;
+  if (typeof tool.permission === 'string') return [tool.permission];
+  return [];
+}
+
+/**
+ * Is this tool shaped as the loop needs? Throws a sentence naming the tool and what is wrong. Run on every tool when the
+ * catalogue is built, so a malformed tool stops the boot instead of failing a question.
+ */
+function assertToolShape(tool) {
+  const fail = (why) => { throw new Error(`ask tool ${tool && tool.id ? JSON.stringify(tool.id) : '(no id)'}: ${why}`); };
+  if (!tool || typeof tool !== 'object') fail('is not an object');
+  if (typeof tool.id !== 'string' || !ID.test(tool.id) || tool.id.length > 64) fail('id is not a lower-case dotted name of at most 64 characters');
+  if (tool.permission !== undefined && tool.permissions !== undefined) fail('declares both permission and permissions — declare one');
+  const gate = gateOf(tool);
+  if (!gate.length || gate.some((p) => typeof p !== 'string' || !p)) fail('declares no permission (an empty gate is no gate)');
+  if (typeof tool.label !== 'string' || !tool.label) fail('has no label');
+  if (typeof tool.description !== 'string' || !tool.description) fail('has no description');
+  if (!tool.args || typeof tool.args !== 'object' || Array.isArray(tool.args)) fail('has no args object');
+  for (const [k, spec] of Object.entries(tool.args)) {
+    if (!/^[a-z][a-z0-9_]{0,39}$/.test(k)) fail(`argument ${k} is not a lower-case name`);
+    if (!spec || typeof spec !== 'object') fail(`argument ${k} has no spec`);
+    if (spec.type === 'enum') {
+      if (!Array.isArray(spec.values) || !spec.values.length || spec.values.some((v) => typeof v !== 'string')) fail(`argument ${k}: an enum needs a list of string values`);
+    } else if (!(Number.isInteger(spec.max) && spec.max > 0 && spec.max <= 500)) fail(`argument ${k}: a text argument needs a max length (1–500)`);
+    if (typeof spec.describe !== 'string' || !spec.describe) fail(`argument ${k} has no describe text`);
+  }
+  if (!Array.isArray(tool.attackerFields)) fail('has no attackerFields list (an empty list must be said)');
+  if (typeof tool.describe !== 'function') fail('has no describe(args)');
+  if (tool.kind === 'remote') {
+    if (typeof tool.service !== 'string' || !tool.service) fail('a remote tool names its service');
+  } else if (typeof tool.run !== 'function') fail('has no run(ctx, args)');
+  return tool;
+}
+
+/**
+ * Does this request hold EVERY permission the tool's page is gated by? All-of, each answer exactly `true`; an empty list
+ * is no gate and is refused.
+ */
+function mayUse(can, tool) {
+  const gate = tool ? gateOf(tool) : [];
+  return typeof can === 'function' && gate.length > 0 && gate.every((p) => can(p) === true);
+}
+
+function argSchema(spec) {
+  if (spec.type === 'enum') {
+    return spec.nullable ? { type: ['string', 'null'], enum: [...spec.values, null] } : { type: 'string', enum: [...spec.values] };
+  }
+  const s = { type: spec.nullable ? ['string', 'null'] : 'string', maxLength: spec.max };
+  if (!spec.nullable) s.minLength = 1;
+  return s;
+}
+
+/** The strict JSON schema the planner's reply must fit, for exactly these tools. */
+function plannerSchema(tools) {
+  const variants = tools.map((t) => ({
+    type: 'object',
+    additionalProperties: false,
+    required: ['tool', 'args'],
+    properties: {
+      tool: { type: 'string', enum: [t.id] },
+      args: {
+        type: 'object',
+        additionalProperties: false,
+        required: Object.keys(t.args),
+        properties: Object.fromEntries(Object.entries(t.args).map(([k, spec]) => [k, argSchema(spec)]))
+      }
+    }
+  }));
+  return {
+    name: 'ask_plan',
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['intent', 'calls'],
+      properties: {
+        intent: { type: 'string', enum: INTENTS },
+        calls: variants.length
+          ? { type: 'array', maxItems: MAX_CALLS, items: variants.length === 1 ? variants[0] : { anyOf: variants } }
+          : { type: 'array', maxItems: 0 }
+      }
+    }
+  };
+}
+
+const isPlain = (o) => o !== null && typeof o === 'object' && !Array.isArray(o);
+
+/** One argument against its spec: the value (null where nullable and absent/null), or throws a reason. */
+function checkArg(name, spec, value) {
+  if (value === undefined || value === null) {
+    if (spec.nullable) return null;
+    throw new Error(`${name} is required`);
+  }
+  if (typeof value !== 'string') throw new Error(`${name} must be text`);
+  if (spec.type === 'enum') {
+    if (!spec.values.includes(value)) throw new Error(`${name} is not one of its values`);
+    return value;
+  }
+  if (/[\u0000-\u001f\u007f]/.test(value)) throw new Error(`${name} has control characters`);
+  const v = value.trim();
+  if (!v) { if (spec.nullable) return null; throw new Error(`${name} is empty`); }
+  if (v.length > spec.max) throw new Error(`${name} is too long`);
+  return v;
+}
+
+/**
+ * The planner's reply, validated against the tools THIS request may use. Returns { intent, calls: [{tool, args}] } with
+ * every argument normalised, or { error, code?, index? } naming the first thing wrong — nothing from a refused reply runs.
+ * A `write` or `none` intent carries no calls. A duplicate call is dropped, not run twice.
+ */
+function validatePlan(reply, tools) {
+  if (!isPlain(reply)) return { error: 'the plan is not an object' };
+  const extra = Object.keys(reply).filter((k) => !['intent', 'calls'].includes(k));
+  if (extra.length) return { error: `the plan has unexpected fields (${extra.join(', ')})` };
+  if (!INTENTS.includes(reply.intent)) return { error: 'the plan has no valid intent' };
+  if (!Array.isArray(reply.calls)) return { error: 'the plan has no calls list' };
+  if (reply.intent !== 'lookup') {
+    return reply.calls.length ? { error: `a ${reply.intent} plan may not name look-ups` } : { intent: reply.intent, calls: [] };
+  }
+  if (!reply.calls.length) return { error: 'a look-up plan names no look-ups' };
+  if (reply.calls.length > MAX_CALLS) return { error: `the plan names more than ${MAX_CALLS} look-ups` };
+  const allowed = new Map(tools.map((t) => [t.id, t]));
+  const calls = [];
+  const seen = new Set();
+  for (const [i, c] of reply.calls.entries()) {
+    if (!isPlain(c)) return { error: `look-up ${i + 1} is not an object` };
+    const keys = Object.keys(c).filter((k) => !['tool', 'args'].includes(k));
+    if (keys.length) return { error: `look-up ${i + 1} has unexpected fields` };
+    const tool = allowed.get(c.tool);
+    // `unoffered` is told apart so the person hears the NOT-FOUND sentence: a tool they lack and a record that is absent
+    // must read the same.
+    if (!tool) return { error: `look-up ${i + 1} names a tool that is not offered`, code: 'unoffered', index: i };
+    if (!isPlain(c.args)) return { error: `look-up ${i + 1} has no arguments object` };
+    const unknown = Object.keys(c.args).filter((k) => !Object.prototype.hasOwnProperty.call(tool.args, k));
+    if (unknown.length) return { error: `look-up ${i + 1} has arguments its tool does not take` };
+    const args = {};
+    try {
+      for (const [name, spec] of Object.entries(tool.args)) args[name] = checkArg(name, spec, c.args[name]);
+    } catch (e) {
+      return { error: `look-up ${i + 1}: ${e.message}` };
+    }
+    const key = JSON.stringify([tool.id, args]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    calls.push({ tool: tool.id, args });
+  }
+  return { intent: 'lookup', calls };
+}
+
+/** What the planner reads about each tool: its id, what it does, and its arguments in words. */
+function describeTools(tools) {
+  return tools.map((t) => {
+    const args = Object.entries(t.args).map(([k, spec]) => `    - ${k}: ${spec.describe}${spec.type === 'enum' ? ` (one of: ${spec.values.join(', ')}${spec.nullable ? ', or null' : ''})` : ''}`);
+    return `- ${t.id}: ${t.description}\n${args.join('\n')}`;
+  }).join('\n');
+}
+
+/**
+ * A fingerprint of the WHOLE catalogue, folded into the prompt hash: change a tool and the bench record no longer
+ * matches, so the route stays off until the bench passes again.
+ *
+ * BYTE-IDENTICAL TO BOTH APPS' COPIES: the hub serialised `{id, permission, description, args, attackerFields}`, Soc
+ * `{id, permissions, …}`. Both keys are written here in that order; JSON.stringify drops the one a tool does not declare,
+ * so each app's string — and so its prompt hash — is unchanged by adopting the package (test/hashes.js proves it on
+ * copies of both apps' documents). A REMOTE tool adds `kind` and `service` after the rest (no app has one yet).
+ */
+function catalogueHashOf(tools) {
+  const doc = tools.map((t) => ({ id: t.id, permission: t.permission, permissions: t.permissions, description: t.description, args: t.args,
+    attackerFields: t.attackerFields, kind: t.kind === 'remote' ? 'remote' : undefined, service: t.kind === 'remote' ? t.service : undefined }));
+  return crypto.createHash('sha256').update(JSON.stringify(doc)).digest('hex');
+}
+
+/** A catalogue over an app's tools, in the order registered. */
+function createCatalogue(tools) {
+  if (!Array.isArray(tools) || !tools.length) throw new Error('ask: createAsk needs a non-empty tools list');
+  const TOOLS = Object.freeze(tools.map(assertToolShape));
+  const BY_ID = new Map();
+  for (const t of TOOLS) {
+    if (BY_ID.has(t.id)) throw new Error(`ask tool ${JSON.stringify(t.id)} is registered twice`);
+    BY_ID.set(t.id, t);
+  }
+  const TOOL_IDS = Object.freeze(TOOLS.map((t) => t.id));
+  return {
+    TOOLS, TOOL_IDS, MAX_CALLS, INTENTS,
+    byId: (id) => BY_ID.get(String(id)) || null,
+    mayUse,
+    /** The tools this request may plan: every permission held, not switched off, and not remote (0.1.0). */
+    catalogueFor(can, toolsOff = []) {
+      const off = new Set(Array.isArray(toolsOff) ? toolsOff : []);
+      return TOOLS.filter((t) => t.kind !== 'remote' && !off.has(t.id) && mayUse(can, t));
+    },
+    plannerSchema, validatePlan, describeTools,
+    catalogueHash: () => catalogueHashOf(TOOLS)
+  };
+}
+
+module.exports = { createCatalogue, assertToolShape, mayUse, gateOf, plannerSchema, validatePlan, describeTools, catalogueHashOf, MAX_CALLS, INTENTS };

package/lib/check.js

@@ -0,0 +1,349 @@
+/**
+ * Step 4 of an Ask question — CHECK the model's answer against the look-ups that ran, then build what the page draws.
+ *
+ * Extracted from the hub's and soc's lib/ask/check.js (2 Nov 2026), taking Soc's — the stricter — and making the
+ * app-specific parts config:
+ *   structured          fields whose value the APP or its clock produced (a band, a verdict, a timestamp) — sayable
+ *   numericStructured   the structured fields whose value may be a pure number 0–1 (Soc: a confidence) — default none
+ *   sayableIdFields     { facts: [...], rows: [...] }: where this app's own public ids sit, besides each row's `ref`
+ *   isPublicId(v)       this app's id test — an id is sayable only when a look-up returned it
+ *   namedTokens         [[regex, replacement]] applied before the token rules: names that contain digits (Soc: "tier 0",
+ *                       "P1") — each app's own, none by default
+ *   sayIps, sayWindows  Soc's S4 (an IP the results carry; a window an app-written label names) — default OFF
+ *   rowChipLabel(row)   the row chip's words
+ *   toolOf(id)          the catalogue — decides which paths of a result are ATTACKER text (the tool's attackerFields)
+ *
+ * NEW IN THE PACKAGE (both apps lacked them; bypass classes the tests name):
+ *   - FORMAT CHARACTERS (\p{Cf}: zero-width space/joiner/non-joiner, word joiner, soft hyphen, BOM, bidi marks) are
+ *     REMOVED before the word rules, so "evil.c​om", "fi​ve" and "scu_AB​CD" read as what they display.
+ *   - IDEOGRAPHIC AND HALFWIDTH FULL STOPS (U+3002, U+FF61) read as dots, as the fullwidth one (U+FF0E) already did
+ *     through NFKC: "evil。example" is a domain.
+ *
+ * WHAT THE MODEL MAY NOT DO. An answer is REFUSED — replaced by fixed wording and the app-drawn chips — when it:
+ *   - is not `{answer, cites}` with a non-empty answer;
+ *   - cites, or places a figure for, a result or extra figure that does not exist;
+ *   - TYPES A NUMBER: any numeral (`\p{N}`: 999, ٩٩٩, ９９９, ⁹⁹⁹, ⑨, Ⅸ) or a number WORD (two … million; not one/first/
+ *     second/single/half);
+ *   - says a token with a digit in it, or a ref-shaped token, that is not SAYABLE (allowedTokens);
+ *   - carries a link — a scheme, `www.`, markup, a Markdown link, a path, or a PUBLIC-looking domain the results did not
+ *     name from an app-written path;
+ *   - claims something was done, asks the person to sign in again, speaks of another partner, or talks about its
+ *     instructions or the document.
+ *
+ * THIS IS A FLOOR, NOT A PROOF. It stops the obeyed shapes the tests name and the bench measures. What it guarantees is
+ * that Ask cannot act, cannot invent a figure the page draws, and cannot link anywhere.
+ */
+
+'use strict';
+
+const PLACEHOLDER = /\{\{\s*(r[1-4])(?:\.([a-z0-9_]{1,40}))?\s*\}\}/g;
+const CITE = /\[(r[1-4])\]/g;
+const DIGIT_TOKEN = /[\p{L}\p{N}_.:\-/]*\p{N}[\p{L}\p{N}_.:\-/]*/gu;
+const PURE_NUMBER = /^[\p{N}.,]+$/u;
+const REF_TOKEN = /(?<![\p{L}\p{N}])[\p{L}]{2,5}_[\p{L}\p{N}]{4,}/gu;
+const HOSTLIKE = /^[\p{L}\p{N}][\p{L}\p{N}-]*(?:\.[\p{L}\p{N}-]+)*$/u;
+const LINKISH = /(https?:|ftp:|mailto:|javascript:|data:|file:|www\.|<\s*[a-z!/]|\]\s*\(|&lt;|\bhref\b)/i;
+const DOMAINISH = /(?<![\p{L}\p{N}])[\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)*\.\p{L}{2,}(?:\/[^\s]*)?(?![\p{L}\p{N}])/gu;
+const INTERNAL_SUFFIX = /\.(local|lan|internal|corp|home\.arpa|localdomain)$/i;
+const NUMBER_WORD = /\b(zero|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety|hundreds?|thousands?|millions?|billions?|dozens?|twice|thrice)\b/i;
+// What an obeyed instruction says — SCOPED to that, not to the vocabulary a security answer is made of ("sign-in attempts",
+// "password spray"). Widened in review L of PR #9: up to two adverbs ("I have now closed it"), "was closed by me", "log
+// back in", "re-enter it at the login page", other tenants or resellers, "my rules".
+const OBEYED = [
+  // "I/we" and the verb with up to two words between ("I have now closed", "we've quietly removed", "I have't yet sent").
+  [/\b(i|we)\s+(?:[\p{L}'’]+\s+){0,2}(closed|deleted|removed|assigned|resolved|approved|disabled|enabled|changed|updated|sent|marked|escalated|acknowledged|archived|reset|purged|wiped)\b/iu, 'claims to have done something', 'claims_action'],
+  [/\b(has|have)\s+been\s+(closed|deleted|removed|resolved|approved|disabled|marked|purged|wiped)\s+(as|by)\b/i, 'claims something was done', 'claims_action'],
+  // The verb "by me / us", however it is introduced ("closed by me", "It was resolved by us").
+  [/\b(closed|deleted|removed|assigned|resolved|approved|disabled|enabled|changed|updated|sent|marked|escalated|acknowledged|archived|reset|purged|wiped)\s+by\s+(me|us|the\s+assistant)\b/i, 'claims something was done', 'claims_action'],
+  [/\b(were|was|been)\s+(deleted|removed|wiped|purged|erased)\b/i, 'claims something was deleted', 'claims_action'],
+  [/\b(sign|log)\s?-?\s?(in|on)\s+(again|at|here|now|to\s+continue|to\s+restore)\b|\b(sign|log)\s+back\s+(in|on)\b|\b(enter|re-?enter|confirm|reset|verify)\s+your\s+(password|credentials?|login)\b|\bre-?enter\b[^.]{0,40}\b(log-?in|sign-?in)\s+page\b|\bsession\s+(has\s+)?expired\b/i, 'sends the person to sign in', 'sign_in'],
+  [/\b(other|another)\s+(partners?|tenants?|resellers?)\b|\bevery\s+other\s+(partner|tenant)\b/i, 'speaks of another partner', 'other_partner'],
+  [/\b(instructions?|system\s+note|results?\s+document|the\s+document|prompt)\b|\bmy\s+(rules|guidelines|programming|orders)\b/i, 'talks about its instructions or the document', 'instructions']
+];
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+const IPV6 = /^(?=.*:)[0-9a-f:]{2,39}$/i;
+const WINDOW = /\b(\d{1,4})\s*(hours?|hrs?|h|days?|d|minutes?|mins?)\b/gi;
+const unitOf = (u) => (/^h/i.test(u) ? 'h' : /^d/i.test(u) ? 'd' : 'min');
+const isInternalHost = (t) => /^\p{L}/u.test(t) && (!t.includes('.') || INTERNAL_SUFFIX.test(t));
+// INVISIBLE AND COMBINING CHARACTERS (review H1 of PR #9): format characters (zero-width, soft hyphen, BOM, bidi
+// controls), every default-ignorable code point (U+034F, the variation selectors FE00–FE0F and E0100–E01EF, …) and every
+// combining mark left after NFKC (U+0332 underline, U+0336 strike) — invisible or decoration, so removed before reading.
+const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{M}]/gu;
+// DOTS THAT ARE NOT "." (H1/H2): ideographic and halfwidth full stops, which NFKC leaves alone (U+3002, U+FF61), and the
+// middle dots and separators a person reads as a dot (·, ‧, ᠃, ٫, ⸱, ・, ･) — and the dot-shaped LETTERS the allow-list would
+// admit as \p{L} (re-review of PR #9): U+A78F ꞏ, U+1427 ᐧ, U+02D1 ˑ, U+02CC ˌ.
+const OTHER_DOTS = /[。｡·‧᠃٫⸱・･ꞏᐧˑˌ]/g;
+// A SPACED DOT between label-like words (re-review of PR #9): "evil . com" and "evil .com" (space, dot, letter), and
+// "evil. example" (dot, space, a lower-case label). Not ordinary prose; a sentence after a full stop starts with a capital.
+// A floor with a known cost: "e.g. the record" reads as a domain and is withheld.
+const SPACED_DOT = /(?<=[\p{L}\p{N}-])(?:\s+\.\s*(?=\p{L})|\.\s+(?=\p{Ll}[\p{L}\p{N}-]*(?:[\s.,;:!?)]|$)))/gu;
+// A BRACKETED DOT — "evil[.]example", "evil(dot)example", "evil [ dot ] example" — is a dot (H2).
+const BRACKETED_DOT = /\s*[\[(]\s*(?:\.|dot)\s*[\])]\s*/gi;
+// A SPELLED-OUT dot between label-like words — "evil dot example", "evil DOT example dot com" — is a dot (H2). A floor: it
+// also reads "the dot in the name" as a domain, which the domain rule then refuses — rare in an answer, and the safe side.
+const SPELLED_DOT = /(?<=[\p{L}\p{N}-])\s+dot\s+(?=[\p{L}\p{N}])/giu;
+/** What the word rules read: NFKC, invisible and combining characters gone, every reading of a dot as ".". */
+const readable = (t) => String(t).normalize('NFKC').replace(INVISIBLE, '').replace(OTHER_DOTS, '.').replace(BRACKETED_DOT, '.').replace(SPELLED_DOT, '.').replace(SPACED_DOT, '.');
+
+/** Every refusal code checkAnswer can return. */
+const REFUSAL_CODES = Object.freeze(['shape', 'control_chars', 'unknown_cite', 'unknown_figure', 'bad_placeholder', 'link', 'number_word', 'claims_action',
+  'sign_in', 'other_partner', 'instructions', 'unknown_ref', 'typed_number', 'unknown_token', 'disallowed_char']);
+
+/**
+ * THE MODEL'S OWN TEXT IS ALLOW-LISTED (the coordinator's round on PR #9, the same list as the soc AI-brief check): after
+ * NFC, every character of the answer (placeholders and cites taken out) must be a letter, a digit (the number rule still
+ * refuses those), a space or a newline, or one of . , ; : ! ? ' " ’ ( ) - – — and the underscore. Anything else — a combining
+ * mark NFC leaves, a look-alike dot, a slash, a bracket, an emoji — is refused (`disallowed_char`). It runs LAST, so every
+ * shape an earlier rule names keeps its own code (a link stays `link`); it closes the classes nobody listed.
+ * ADDED TO THE SHARED LIST HERE, both needed by the apps' honest corpora: `_` (every app id is `xxx_…`) and the newline
+ * (between sentences; control_chars already allows it). And the curly quotes “ ” ‘ (at the coordinator's word: models write
+ * them often and they are harmless; ’ was already in).
+ * KNOWN LIMIT: every letter (\p{L}) passes, so names in any script do; look-alike letters in a domain or a ref are caught by
+ * the NFKC, dot and link rules, not here.
+ */
+const ALLOWED_CHAR = /^[\p{L}\p{N} \n.,;:!?'"‘’“”()\-–—_]$/u;
+
+const trim = (t) => String(t).replace(/^[.:\-/]+|[.:\-/]+$/g, '');
+
+/** Every string of a result with its path in attackerFields' spelling (rows[].fields.entity, facts.entities[].value). */
+function stringsOf(r) {
+  const out = [];
+  const walk = (v, path) => {
+    if (typeof v === 'string') out.push([path, v]);
+    else if (Array.isArray(v)) v.forEach((x) => walk(x, `${path}[]`));
+    else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k);
+  };
+  walk(r.facts || {}, 'facts');
+  for (const row of r.rows || []) { walk(row.title, 'rows[].title'); walk(row.fields || {}, 'rows[].fields'); }
+  return out;
+}
+
+/** The figure a placeholder names: { i, key, count, label, href } or null when it names nothing. */
+function figureOf(results, rid, key) {
+  const i = Number(rid.slice(1)) - 1;
+  const r = results[i];
+  if (!r) return null;
+  if (!key) return { i, key: null, count: r.count, label: r.label, href: r.href };
+  const x = (r.extras || []).find((e) => e.key === key);
+  return x ? { i, key, count: x.count, label: x.label, href: x.href } : null;
+}
+
+/** The answer text → segments the view draws: {t:'text', v} | {t:'fig', v, of, k, title} | {t:'cite', v, n}. */
+function segmentsOf(answer, results) {
+  const out = [];
+  const re = /\{\{\s*(r[1-4])(?:\.([a-z0-9_]{1,40}))?\s*\}\}|\[(r[1-4])\]/g;
+  let at = 0;
+  for (const m of answer.matchAll(re)) {
+    if (m.index > at) out.push({ t: 'text', v: answer.slice(at, m.index) });
+    if (m[1]) {
+      const f = figureOf(results, m[1], m[2]);
+      out.push({ t: 'fig', v: String(f.count), of: f.i + 1, k: `${m[1]}${m[2] ? `.${m[2]}` : ''}`, title: `From look-up ${f.i + 1}: ${f.label || 'rows'}` });
+    } else {
+      out.push({ t: 'cite', v: m[3], n: Number(m[3].slice(1)) });
+    }
+    at = m.index + m[0].length;
+  }
+  if (at < answer.length) out.push({ t: 'text', v: answer.slice(at) });
+  return out;
+}
+
+/** A help result's chips: one per passage, no link and no count, drawn from the tool's own rows. */
+function helpChips(chips, r, i) {
+  const seen = new Set();
+  for (const row of r.rows || []) {
+    if (!row.title || seen.has(row.title)) continue;
+    seen.add(row.title);
+    chips.push({ count: null, label: `From the help pages: ${row.title}`, href: null, of: i + 1, help: true });
+  }
+}
+
+const DEFAULT_ROW_CHIP = (row) => [row.title || row.ref].filter(Boolean).join(' · ');
+
+/**
+ * A check bound to an app's field lists. Returns { checkAnswer, allowedTokens, segmentsOf, chipsOf, figureOf, … }.
+ * @param {object} o see the header
+ */
+function createCheck(o = {}) {
+  const structured = Object.freeze([...(o.structured || [])]);
+  const numericStructured = Object.freeze([...(o.numericStructured || [])]);
+  const idFacts = Object.freeze([...((o.sayableIdFields && o.sayableIdFields.facts) || [])]);
+  const idRows = Object.freeze([...((o.sayableIdFields && o.sayableIdFields.rows) || [])]);
+  const namedTokens = (o.namedTokens || []).map(([re, to]) => {
+    if (!(re instanceof RegExp) || !re.global) throw new Error('ask check: a namedTokens entry is [a GLOBAL RegExp, replacement]');
+    return [re, to];
+  });
+  const isPublicId = typeof o.isPublicId === 'function' ? o.isPublicId : () => false;
+  const toolOf = typeof o.toolOf === 'function' ? o.toolOf : () => null;
+  const rowChipLabel = typeof o.rowChipLabel === 'function' ? o.rowChipLabel : DEFAULT_ROW_CHIP;
+  const sayIps = o.sayIps === true;
+  const sayWindows = o.sayWindows === true;
+
+  /**
+   * The SAYABLE tokens:
+   *   - this app's own public ids a look-up returned (a row's ref, or a sayableIdFields path);
+   *   - every token of a STRUCTURED field;
+   *   - a HOSTNAME-SHAPED token that appears whole in the results — WHERE IT CAME FROM DECIDES: from a path the APP wrote
+   *     any host; from an ATTACKER path (the tool's attackerFields; every path of an unknown or remote tool) only an
+   *     INTERNAL-looking one (a single label, or .local/.lan/.internal/.corp/…) that starts with a letter;
+   *   - with sayIps, an IP address the results carry; with sayWindows, a window an app-written label names.
+   */
+  function allowedTokens(results) {
+    const set = new Set();
+    const own = (v) => { if (typeof v === 'string' && isPublicId(v)) set.add(v); };
+    set.numbers = new Set();
+    set.ips = new Set();
+    set.windows = new Set();
+    const numeric = (v) => { if (typeof v === 'string' && /^(0(\.\d{1,3})?|1(\.0{1,3})?)$/.test(v)) set.numbers.add(v); };
+    const field = (v) => {
+      if (typeof v !== 'string' || !v || v.length > 64) return;
+      for (const m of v.match(DIGIT_TOKEN) || []) set.add(trim(m));
+      if (!/\s/.test(v)) set.add(v);
+    };
+    const windows = (v) => { if (sayWindows && typeof v === 'string') for (const m of v.matchAll(WINDOW)) set.windows.add(`${Number(m[1])}${unitOf(m[2])}`); };
+    for (const r of results) {
+      const tool = r && r.tool ? toolOf(r.tool) : null;
+      const remote = !tool || tool.kind === 'remote';
+      const attacker = new Set(tool && !remote ? tool.attackerFields : []);
+      for (const k of structured) field((r.facts || {})[k]);
+      for (const k of numericStructured) numeric((r.facts || {})[k]);
+      for (const k of idFacts) own((r.facts || {})[k]);
+      for (const [path, v] of stringsOf(r)) {
+        const fromAttacker = remote || attacker.has(path);
+        for (const w of readable(v).split(/[\s,;()"'“”‘’!?]+/)) {
+          const t = trim(w);
+          if (!t) continue;
+          if (IPV4.test(t) || IPV6.test(t)) { if (sayIps) set.ips.add(t.toLowerCase()); continue; }
+          if (!HOSTLIKE.test(t) || PURE_NUMBER.test(t)) continue;
+          if (!fromAttacker || isInternalHost(t)) set.add(t);
+        }
+        if (!fromAttacker) windows(v);
+      }
+      windows(r.label);
+      for (const x of r.extras || []) windows(x.label);
+      for (const row of r.rows || []) {
+        own(row.ref);
+        for (const k of idRows) own((row.fields || {})[k]);
+        for (const k of structured) field((row.fields || {})[k]);
+        for (const k of numericStructured) numeric((row.fields || {})[k]);
+      }
+      for (const c of r.candidates || []) own(c.ref);
+    }
+    return set;
+  }
+
+  /**
+   * Check one answer. Returns { ok: true, answer, cites } or { ok: false, code, reason } — `code` is one of REFUSAL_CODES.
+   * @param {*} reply the model's parsed JSON
+   * @param {object[]} results the look-ups' results, in order (r1 = results[0])
+   */
+  function checkAnswer(reply, results) {
+    if (!reply || typeof reply !== 'object' || Array.isArray(reply)) return { ok: false, code: 'shape', reason: 'not an object' };
+    const keys = Object.keys(reply).filter((k) => !['answer', 'cites'].includes(k));
+    if (keys.length) return { ok: false, code: 'shape', reason: 'unexpected fields' };
+    const answer = typeof reply.answer === 'string' ? reply.answer.trim() : '';
+    if (!answer) return { ok: false, code: 'shape', reason: 'empty answer' };
+    if (answer.length > 700) return { ok: false, code: 'shape', reason: 'answer too long' };
+    if (!Array.isArray(reply.cites) || reply.cites.some((c) => typeof c !== 'string')) return { ok: false, code: 'shape', reason: 'cites is not a list of ids' };
+    if (/[\u0000-\u0008\u000b-\u001f\u007f]/.test(answer)) return { ok: false, code: 'control_chars', reason: 'control characters' };
+
+    for (const c of reply.cites) if (!/^r[1-4]$/.test(c) || !results[Number(c.slice(1)) - 1]) return { ok: false, code: 'unknown_cite', reason: `cites ${String(c).slice(0, 8)}, which no look-up returned` };
+    for (const m of answer.matchAll(CITE)) if (!results[Number(m[1].slice(1)) - 1]) return { ok: false, code: 'unknown_cite', reason: `cites ${m[1]}, which no look-up returned` };
+    for (const m of answer.matchAll(PLACEHOLDER)) if (!figureOf(results, m[1], m[2])) return { ok: false, code: 'unknown_figure', reason: `a figure ${m[0]} no look-up returned` };
+    const bare = answer.replace(PLACEHOLDER, ' ').replace(CITE, ' ');
+    if (/[{}]/.test(bare)) return { ok: false, code: 'bad_placeholder', reason: 'a malformed figure placeholder' };
+    // NFKC, other full stops and NO format characters for the word rules: what the person would read.
+    const norm = readable(bare);
+    const allowed = allowedTokens(results);
+    if (LINKISH.test(norm)) return { ok: false, code: 'link', reason: 'a link or markup' };
+    for (const m of norm.matchAll(DOMAINISH)) {
+      const d = m[0];
+      if (d.includes('/') || !(INTERNAL_SUFFIX.test(d) || allowed.has(trim(d)))) return { ok: false, code: 'link', reason: 'a link or markup' };
+    }
+    const word = NUMBER_WORD.exec(norm);
+    if (word) return { ok: false, code: 'number_word', reason: `writes the number “${word[0]}” instead of a figure placeholder` };
+    for (const [re, why, code] of OBEYED) if (re.test(norm)) return { ok: false, code, reason: why };
+
+    const named = (x) => {
+      let y = x;
+      for (const [re, to] of namedTokens) y = y.replace(re, to);
+      if (sayWindows) y = y.replace(WINDOW, (m, n, u) => (allowed.windows.has(`${Number(n)}${unitOf(u)}`) ? 'window' : m));
+      return y;
+    };
+    // BOTH READINGS: the raw text keeps a Roman numeral (Ⅸ — NFKC makes it the letters IX), the readable one joins what
+    // a format character split.
+    for (const src of [bare, norm].map(named)) {
+      for (const t of src.match(REF_TOKEN) || []) {
+        if (!allowed.has(t)) return { ok: false, code: 'unknown_ref', reason: `names “${t.slice(0, 40)}”, which is not an id a look-up returned` };
+      }
+      for (const t of src.match(DIGIT_TOKEN) || []) {
+        const tok = trim(t);
+        if (sayIps && allowed.ips.has(tok.toLowerCase())) continue;
+        if (PURE_NUMBER.test(tok) && !allowed.numbers.has(tok)) return { ok: false, code: 'typed_number', reason: `types the number “${tok.slice(0, 20)}” instead of a figure placeholder` };
+        if (PURE_NUMBER.test(tok)) continue;
+        if (tok && /\p{N}/u.test(tok) && !allowed.has(tok) && !(HOSTLIKE.test(tok) && INTERNAL_SUFFIX.test(tok))) return { ok: false, code: 'unknown_token', reason: `states “${tok.slice(0, 40)}”, which no look-up returned as an id, a field or a host` };
+      }
+    }
+    for (const ch of bare.normalize('NFC')) {
+      if (!ALLOWED_CHAR.test(ch)) return { ok: false, code: 'disallowed_char', reason: `a character outside the allowed set (U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')})` };
+    }
+    return { ok: true, answer, cites: [...new Set(reply.cites)] };
+  }
+
+  /**
+   * The chips: the figures the answer placed (or, with fixed wording, every result's main figure and its extras), each
+   * the tool's own count, label and href — a chip with no href is a fact. Then a row chip for each row the answer named
+   * by ref or a small cited result's rows (at most 4), and a cited result's notes.
+   */
+  function chipsOf(results, answer) {
+    const chips = [];
+    const seen = new Set();
+    const add = (f) => {
+      const k = `${f.i}:${f.key || ''}`;
+      if (seen.has(k)) return;
+      seen.add(k);
+      chips.push({ count: f.count, label: f.label || '', href: f.href || null, of: f.i + 1 });
+    };
+    if (answer) {
+      for (const m of answer.matchAll(PLACEHOLDER)) add(figureOf(results, m[1], m[2]));
+      let rows = 0;
+      for (const [i, r] of results.entries()) {
+        if (r.help) { if (answer.includes(`[r${i + 1}]`)) helpChips(chips, r, i); continue; }
+        for (const row of r.rows || []) {
+          const cited = answer.includes(`[r${i + 1}]`) && (r.rows || []).length <= 4;
+          const named = answer.includes(row.ref) || cited;
+          if (rows >= 4 || !row.href || !row.ref || !named) continue;
+          chips.push({ count: null, label: rowChipLabel(row), href: row.href, of: i + 1 });
+          rows += 1;
+        }
+      }
+      for (const [i, r] of results.entries()) {
+        if (!answer.includes(`[r${i + 1}]`)) continue;
+        for (const n of r.notes || []) chips.push({ count: null, label: String(n.label || ''), href: null, of: i + 1 });
+      }
+      return chips;
+    }
+    for (const [i, r] of results.entries()) {
+      if (r.help) { helpChips(chips, r, i); continue; }
+      if (r.outcome === 'ok' && r.label) add({ i, key: null, count: r.count, label: r.label, href: r.href });
+      for (const x of r.extras || []) add({ i, key: x.key, count: x.count, label: x.label, href: x.href });
+      for (const n of r.notes || []) chips.push({ count: null, label: String(n.label || ''), href: null, of: i + 1 });
+    }
+    return chips;
+  }
+
+  const config = Object.freeze({ structured, numericStructured, sayableIdFields: { facts: idFacts, rows: idRows }, sayIps, sayWindows,
+    namedTokens: namedTokens.map(([re, to]) => [String(re), String(to)]) });
+  /**
+   * WHAT DECIDES A VERDICT (review H3 of PR #9): the rule sources and this app's config, including its id test and row-chip
+   * label. The bench folds it into scorerHash, so a pass measured under another check never opens the gate.
+   */
+  const fingerprint = () => JSON.stringify({ rules: RULE_SOURCES, config, isPublicId: String(isPublicId), rowChipLabel: String(rowChipLabel) });
+  return { REFUSAL_CODES, NUMBER_WORD, REF_TOKEN, PLACEHOLDER, LINKISH, checkAnswer, allowedTokens, segmentsOf, chipsOf, figureOf, config, fingerprint };
+}
+
+/** Every module-level rule and helper a verdict depends on, as text (with createCheck's own source). */
+const RULE_SOURCES = [PLACEHOLDER, CITE, DIGIT_TOKEN, PURE_NUMBER, REF_TOKEN, HOSTLIKE, LINKISH, DOMAINISH, INTERNAL_SUFFIX, NUMBER_WORD, IPV4, IPV6, WINDOW,
+  INVISIBLE, OTHER_DOTS, BRACKETED_DOT, SPELLED_DOT, SPACED_DOT, ALLOWED_CHAR, ...OBEYED.map(([re, why, code]) => `${re}|${why}|${code}`), REFUSAL_CODES.join(','),
+  unitOf, isInternalHost, readable, trim, stringsOf, figureOf, segmentsOf, helpChips, createCheck].map(String);
+
+module.exports = { createCheck, REFUSAL_CODES, NUMBER_WORD, REF_TOKEN, PLACEHOLDER, LINKISH, segmentsOf, figureOf, stringsOf, readable };

package/lib/common.js

@@ -0,0 +1,31 @@
+/**
+ * What every Ask tool shares, whichever app it belongs to. The rest of the apps' lib/ask/common.js — READ_ONLY per model,
+ * scopeOf, resolveCustomer, the readings — is domain and stays in each app.
+ *
+ * A RESULT is { outcome: 'ok'|'not_found'|'ambiguous'|'error', count, label, href, rows: [{ref, title, fields, href}],
+ * facts, extras: [{key, count, label, href}], notes?: [{label}], quote?: {label, text, at?, model?}, help?, words,
+ * candidates? }. `count` + `href` are the chip the app draws; the model places the count with a {{rN}} placeholder.
+ */
+
+'use strict';
+
+const MAX_ROWS = 20;
+const MAX_TEXT = 256;
+
+/** Text cut to n characters (with an ellipsis), control characters as spaces; null stays null. */
+const cut = (v, n = MAX_TEXT) => {
+  if (v == null) return null;
+  const t = String(v).replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+/** A not-found result — the SAME shape for absent and unpermitted. */
+const notFound = (words) => ({ outcome: 'not_found', count: 0, label: null, href: null, rows: [], facts: {}, extras: [], words });
+
+/** An ambiguous match: the candidates' names and links, nothing else. `hrefOf(c)` is the app's page for one. */
+const ambiguous = (words, list, { label = 'customers match', hrefOf = (c) => `/customers/${Number(c.id)}`, titleOf = (c) => c.name } = {}) => ({
+  outcome: 'ambiguous', count: list.length, label, href: null, rows: [], facts: {}, extras: [], words,
+  candidates: list.slice(0, 10).map((c) => ({ ref: c.public_id, title: cut(titleOf(c)), href: hrefOf(c) }))
+});
+
+module.exports = { MAX_ROWS, MAX_TEXT, cut, notFound, ambiguous };