@aria-framework/ask 0.0.0-stage → 0.1.1

package/lib/schema.js

@@ -0,0 +1,396 @@
+/**
+ * THE REFERENCE TABLE DESIGN (D-0169 item 2). Each app OWNS its Ask tables and migrations — db-worker's runner reads one
+ * directory and ledgers by filename, so a package cannot ship a migration that runs — but every app BUILDS them the same
+ * way, from what is here:
+ *
+ *   REFERENCE               the column list of ask_questions and ask_tool_calls (the model reads and writes exactly these)
+ *   referenceMigration()    the reference migration, SQLite or Postgres — the hub's 105_ask / soc's 132_ask, verbatim in
+ *                           every statement, with the app's own `context_kind` values. The tables ONLY: tenancy
+ *                           (partner_id, its key, the composite key, RLS) is the app's GENERATED tenancy migration, never
+ *                           typed — the hub's scripts/generate-tenancy-migration.js, db-worker's tenancyMigration.
+ *   bin/ask-migration.js    the generator an app runs to emit its own NNN_ask.sql / NNN_ask.postgres.sql
+ *   diffMigration()         the check an app's test calls on its migration FILE: [] when every statement is the
+ *                           reference's, otherwise one sentence per difference
+ *   diffLiveTables()        the same check on a LIVE database (SQLite or Postgres): the tables a migration chain built
+ *
+ * WHAT IS COMPARED, AND WHAT IS NOT. diffMigration compares every SQL statement (comments and COMMENT ON stripped,
+ * whitespace collapsed) — so a changed CHECK, a dropped index or a widened bound is a difference. diffLiveTables compares
+ * on SQLite the stored CREATE statements (the same text), and on Postgres what the catalog says: each column's type,
+ * nullability, default and identity; each CHECK's column and its literal values and bounds; the foreign key to
+ * ask_questions with ON DELETE CASCADE; the indexes by name and columns; and, with `tenancy: true`, partner_id NOT NULL,
+ * RLS enabled AND forced, and a policy on each table.
+ */
+
+'use strict';
+
+const TABLES = Object.freeze(['ask_questions', 'ask_tool_calls']);
+const OUTCOMES = ['working', 'answered', 'withheld', 'not_found', 'refused_write', 'cannot', 'busy', 'off', 'error'];
+const CALL_OUTCOMES = ['ok', 'not_found', 'ambiguous', 'error'];
+const REASONS = ['wrong_figure', 'wrong_record', 'no_answer', 'other'];
+const KIND = /^[a-z][a-z_]{0,31}$/;
+
+/**
+ * THE COLUMNS, in table order. `check` names the literal values and the bounds the column's CHECK holds (what the live
+ * Postgres comparison reads back); `ctx` marks the one app-supplied list.
+ */
+const REFERENCE = Object.freeze({
+  ask_questions: Object.freeze([
+    { name: 'id', pg: 'bigint', sqlite: 'INTEGER', notNull: true, identity: true },
+    { name: 'public_id', pg: 'text', sqlite: 'TEXT', notNull: true, unique: true },
+    { name: 'asked_by', pg: 'bigint', sqlite: 'INTEGER', notNull: true },
+    { name: 'asked_by_name', pg: 'text', sqlite: 'TEXT', notNull: true, check: { numbers: ['1', '250'] } },
+    { name: 'acting', pg: 'integer', sqlite: 'INTEGER', notNull: true, default: '0', check: { numbers: ['0', '1'] } },
+    { name: 'context_kind', pg: 'text', sqlite: 'TEXT', notNull: false, check: { ctx: true } },
+    { name: 'context_ref', pg: 'text', sqlite: 'TEXT', notNull: false, check: { numbers: ['1', '64'] } },
+    { name: 'question', pg: 'text', sqlite: 'TEXT', notNull: true, check: { numbers: ['1', '500'] } },
+    { name: 'outcome', pg: 'text', sqlite: 'TEXT', notNull: true, check: { values: OUTCOMES } },
+    { name: 'answer', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'result', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'endpoint', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'model', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'tokens', pg: 'bigint', sqlite: 'INTEGER', notNull: true, default: '0' },
+    { name: 'ms', pg: 'bigint', sqlite: 'INTEGER', notNull: true, default: '0' },
+    { name: 'prompt_hash', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'rating', pg: 'integer', sqlite: 'INTEGER', notNull: false, check: { numbers: ['-1', '1'] } },
+    { name: 'feedback_reason', pg: 'text', sqlite: 'TEXT', notNull: false, check: { values: REASONS } },
+    { name: 'feedback_text', pg: 'text', sqlite: 'TEXT', notNull: false, check: { numbers: ['300'] } },
+    { name: 'reviewed_at', pg: 'text', sqlite: 'TEXT', notNull: false },
+    { name: 'created_at', pg: 'text', sqlite: 'TEXT', notNull: true, default: 'now' }
+  ].map(Object.freeze)),
+  ask_tool_calls: Object.freeze([
+    { name: 'id', pg: 'bigint', sqlite: 'INTEGER', notNull: true, identity: true },
+    { name: 'question_id', pg: 'bigint', sqlite: 'INTEGER', notNull: true },
+    { name: 'position', pg: 'integer', sqlite: 'INTEGER', notNull: true, check: { numbers: ['1', '4'] } },
+    { name: 'tool', pg: 'text', sqlite: 'TEXT', notNull: true, check: { numbers: ['1', '64'] } },
+    { name: 'args', pg: 'text', sqlite: 'TEXT', notNull: true },
+    { name: 'outcome', pg: 'text', sqlite: 'TEXT', notNull: true, check: { values: CALL_OUTCOMES } },
+    { name: 'row_count', pg: 'integer', sqlite: 'INTEGER', notNull: true, default: '0' },
+    { name: 'ms', pg: 'integer', sqlite: 'INTEGER', notNull: true, default: '0' },
+    { name: 'created_at', pg: 'text', sqlite: 'TEXT', notNull: true, default: 'now' }
+  ].map(Object.freeze))
+});
+
+const INDEXES = Object.freeze({
+  ask_questions: { idx_ask_questions_asker: ['asked_by', 'created_at'], idx_ask_questions_created: ['created_at'] },
+  ask_tool_calls: { idx_ask_tool_calls_question: ['question_id'] }
+});
+
+/**
+ * THE GENERATED TENANCY, as the framework's tenancy generator writes it (both apps' 106 / 133 / 134): the session default
+ * of partner_id and the policy expression. Compared EXACTLY, after `exprNorm` — casts, brackets, spacing and case taken
+ * out, so the server's own deparsing ('app.scope'::text, ::integer, extra brackets) is not a difference and any change to
+ * the logic is.
+ */
+const PARTNER_DEFAULT = "NULLIF(current_setting('app.partner_id', true), '')::int";
+const POLICY_EXPRESSION = "CASE current_setting('app.scope', true) WHEN 'platform' THEN true ELSE partner_id = current_setting('app.partner_id')::int END";
+const exprNorm = (x) => String(x == null ? '' : x).replace(/::[a-z_]+( varying| precision)?/gi, '').replace(/[()]/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+
+function kindsOf(contextKinds) {
+  if (!Array.isArray(contextKinds) || !contextKinds.length) throw new Error('ask schema: contextKinds is a non-empty list (the page context kinds the app passes)');
+  for (const k of contextKinds) if (typeof k !== 'string' || !KIND.test(k)) throw new Error(`ask schema: context kind ${JSON.stringify(k)} is not a lower-case word`);
+  if (new Set(contextKinds).size !== contextKinds.length) throw new Error('ask schema: a context kind is listed twice');
+  return contextKinds;
+}
+const q = (v) => `'${v}'`;
+
+/** The statements of the reference migration, in order (no comments), for one dialect. */
+function statementsFor(dialect, contextKinds) {
+  const kinds = kindsOf(contextKinds).map(q).join(', ');
+  const pg = dialect === 'postgres';
+  if (!pg && dialect !== 'sqlite') throw new Error(`ask schema: dialect is 'sqlite' or 'postgres', not ${JSON.stringify(dialect)}`);
+  const pk = pg ? 'BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY' : 'INTEGER PRIMARY KEY AUTOINCREMENT';
+  const big = pg ? 'BIGINT ' : 'INTEGER';
+  const trim = pg ? 'btrim' : 'trim';
+  const now = pg ? "to_char(now() AT TIME ZONE 'utc', 'YYYY-MM-DD HH24:MI:SS')" : "(datetime('now'))";
+  return [
+    `CREATE TABLE ask_questions (
+  id               ${pk},
+  public_id        TEXT    NOT NULL UNIQUE,
+  asked_by         ${big} NOT NULL,
+  asked_by_name    TEXT    NOT NULL CHECK (length(asked_by_name) BETWEEN 1 AND 250),
+  acting           INTEGER NOT NULL DEFAULT 0 CHECK (acting IN (0, 1)),
+  context_kind     TEXT    CHECK (context_kind IS NULL OR context_kind IN (${kinds})),
+  context_ref      TEXT    CHECK (context_ref IS NULL OR length(context_ref) BETWEEN 1 AND 64),
+  question         TEXT    NOT NULL CHECK (length(${trim}(question)) >= 1 AND length(question) <= 500),
+  outcome          TEXT    NOT NULL CHECK (outcome IN ('working', 'answered', 'withheld', 'not_found', 'refused_write',
+                                                       'cannot', 'busy', 'off', 'error')),
+  answer           TEXT,
+  result           TEXT,
+  endpoint         TEXT,
+  model            TEXT,
+  tokens           ${big} NOT NULL DEFAULT 0,
+  ms               ${big} NOT NULL DEFAULT 0,
+  prompt_hash      TEXT,
+  rating           INTEGER CHECK (rating IS NULL OR rating IN (-1, 1)),
+  feedback_reason  TEXT    CHECK (feedback_reason IS NULL OR feedback_reason IN ('wrong_figure', 'wrong_record', 'no_answer', 'other')),
+  feedback_text    TEXT    CHECK (feedback_text IS NULL OR length(feedback_text) <= 300),
+  reviewed_at      TEXT,
+  created_at       TEXT    NOT NULL DEFAULT ${now}
+)`,
+    'CREATE INDEX idx_ask_questions_asker ON ask_questions (asked_by, created_at)',
+    'CREATE INDEX idx_ask_questions_created ON ask_questions (created_at)',
+    `CREATE TABLE ask_tool_calls (
+  id           ${pk},
+  question_id  ${big} NOT NULL REFERENCES ask_questions(id) ON DELETE CASCADE,
+  position     INTEGER NOT NULL CHECK (position BETWEEN 1 AND 4),
+  tool         TEXT    NOT NULL CHECK (length(tool) BETWEEN 1 AND 64),
+  args         TEXT    NOT NULL,
+  outcome      TEXT    NOT NULL CHECK (outcome IN ('ok', 'not_found', 'ambiguous', 'error')),
+  row_count    INTEGER NOT NULL DEFAULT 0,
+  ms           INTEGER NOT NULL DEFAULT 0,
+  created_at   TEXT    NOT NULL DEFAULT ${now}
+)`,
+    'CREATE INDEX idx_ask_tool_calls_question ON ask_tool_calls (question_id)'
+  ];
+}
+
+/**
+ * The reference migration's full text. `number` and `tenancyFile` only shape the header comment.
+ * @param {{dialect: 'sqlite'|'postgres', contextKinds: string[], number?: string, tenancyFile?: string}} o
+ */
+function referenceMigration(o) {
+  const st = statementsFor(o.dialect, o.contextKinds);
+  const n = o.number ? `${o.number}_ask` : 'NNN_ask';
+  const pg = o.dialect === 'postgres';
+  const head = [
+    `-- ${n}${pg ? '.postgres' : ''}.sql — Ask anything: ask_questions and ask_tool_calls, GENERATED from @aria-framework/ask's`,
+    '-- reference table design (bin/ask-migration.js). Do not edit a statement: the app\'s test holds this file to the',
+    '-- reference with diffMigration(), and an applied file is pinned. Change the design in the package, then add a NEW',
+    '-- migration from its changelog.',
+    '--',
+    '-- TWO TABLES, BOTH PARTNER-SCOPED: a question belongs to the partner it was asked in. The tables ONLY — partner_id, its',
+    `-- key, the composite key from ask_tool_calls to ask_questions and row-level security come from the GENERATED tenancy`,
+    `-- migration${o.tenancyFile ? ` (${o.tenancyFile})` : ''}, never typed here. Retention deletes questions; their look-ups cascade.`,
+    ''
+  ];
+  const body = st.map((s) => `${s};`);
+  // The pg statements are spaced as the hub's file is: the table, its indexes, its comments.
+  const comments = pg ? [
+    "COMMENT ON TABLE ask_questions IS 'Ask anything: one row per question, in the partner it was asked in; content kept per the Ask retention setting (PARTNER)';",
+    "COMMENT ON COLUMN ask_questions.asked_by IS 'the users.id of who asked; an ACTOR, not tenancy — no key, on purpose';",
+    "COMMENT ON COLUMN ask_questions.result IS 'the answer as the app rendered it (JSON): app-drawn figures and chips, never model-written links';",
+    "COMMENT ON TABLE ask_tool_calls IS 'Ask anything: one row per look-up a question''s plan ran — tool, validated arguments, rows, outcome (PARTNER)';"
+  ] : [];
+  const parts = [body[0], body[1], body[2], ...comments.slice(0, 3), '', body[3], body[4], ...comments.slice(3)];
+  return `${head.join('\n')}\n${parts.join('\n')}\n`;
+}
+
+/** SQL text → its statements, comments and COMMENT ON removed, whitespace collapsed. Quote-aware for `--` and `;`. */
+function statementsOf(sql) {
+  const out = [];
+  let cur = '';
+  let inQ = false;
+  const s = String(sql).replace(/\r\n/g, '\n');
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s[i];
+    if (inQ) { cur += c; if (c === "'") { if (s[i + 1] === "'") { cur += s[i + 1]; i += 1; } else inQ = false; } continue; }
+    if (c === "'") { inQ = true; cur += c; continue; }
+    if (c === '-' && s[i + 1] === '-') { while (i < s.length && s[i] !== '\n') i += 1; cur += ' '; continue; }
+    if (c === ';') { out.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  out.push(cur);
+  return out.map(norm).filter((x) => x && !/^COMMENT ON /i.test(x));
+}
+/** Whitespace collapsed, and none beside brackets and commas — so formatting is never a difference. */
+const norm = (x) => String(x).replace(/\s+/g, ' ').replace(/\s*([(),])\s*/g, '$1').trim();
+
+/**
+ * Does an app's migration FILE hold exactly the reference statements? [] when it does; otherwise one sentence per
+ * difference, naming the statement.
+ * @param {string} sql the file's text
+ * @param {{dialect, contextKinds}} o
+ */
+function diffMigration(sql, o) {
+  const want = statementsFor(o.dialect, o.contextKinds).map(norm);
+  const got = statementsOf(sql);
+  const diffs = [];
+  const label = (x) => x.slice(0, 60);
+  for (const w of want) if (!got.includes(w)) diffs.push(`missing or different: ${label(w)}… (reference: ${w})`);
+  for (const g of got) if (!want.includes(g)) diffs.push(`not in the reference: ${label(g)}…`);
+  return diffs;
+}
+
+// ── LIVE ──────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+const TENANCY_SQLITE = /,\s*partner_id\s+INTEGER\s+NOT\s+NULL\s+DEFAULT\s+1\s*(?=\)\s*$)/i;
+
+async function liveSqlite(driver, o) {
+  const diffs = [];
+  const want = statementsFor('sqlite', o.contextKinds).map(norm);
+  const master = await driver.all("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE tbl_name IN ('ask_questions', 'ask_tool_calls') AND sql IS NOT NULL");
+  for (const t of TABLES) {
+    const row = master.find((m) => m.type === 'table' && m.name === t);
+    if (!row) { diffs.push(`${t}: the table does not exist`); continue; }
+    let sql = String(row.sql);
+    const tenancy = TENANCY_SQLITE.test(sql);
+    sql = sql.replace(TENANCY_SQLITE, '');
+    if (o.tenancy === true && !tenancy) diffs.push(`${t}: no partner_id INTEGER NOT NULL DEFAULT 1 (the generated tenancy migration has not run)`);
+    if (o.tenancy === false && tenancy) diffs.push(`${t}: has partner_id, and tenancy: false was asked for`);
+    const w = want.find((x) => x.startsWith(`CREATE TABLE ${t}(`));
+    if (norm(sql) !== w) diffs.push(`${t}: its CREATE TABLE is not the reference's (stored: ${norm(sql)})`);
+  }
+  const allowed = new Set(Object.values(INDEXES).flatMap((x) => Object.keys(x)));
+  const tenancyIdx = new Set(['idx_ask_questions_partner', 'idx_ask_tool_calls_partner']);
+  for (const w of want.filter((x) => x.startsWith('CREATE INDEX'))) {
+    const name = w.split(' ')[2];
+    const m = master.find((x) => x.type === 'index' && x.name === name);
+    if (!m) diffs.push(`${name}: the index does not exist`);
+    else if (norm(m.sql) !== w) diffs.push(`${name}: the index is not the reference's (stored: ${norm(m.sql)})`);
+  }
+  for (const m of master.filter((x) => x.type === 'index' && !allowed.has(x.name) && !tenancyIdx.has(x.name))) diffs.push(`${m.name}: an index the reference does not have`);
+  if (o.tenancy === true) for (const n of tenancyIdx) if (!master.some((x) => x.type === 'index' && x.name === n)) diffs.push(`${n}: the tenancy index does not exist`);
+  for (const m of master.filter((x) => x.type === 'trigger')) diffs.push(`${m.name}: a trigger on ${m.tbl_name} the reference does not have`);
+  return diffs;
+}
+
+/** Literal values and bare numbers in a CHECK's definition, as two sorted lists of strings. */
+function literalsOf(def) {
+  const values = [...String(def).matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'"));
+  const rest = String(def).replace(/'((?:[^']|'')*)'/g, ' ');
+  const numbers = [...rest.matchAll(/(?<![\w.])-?\d+(?![\w.])/g)].map((m) => m[0]);
+  // A quoted number ('-1'::integer) is a number, not a value.
+  const quotedNumbers = values.filter((v) => /^-?\d+$/.test(v));
+  return { values: values.filter((v) => !/^-?\d+$/.test(v)).sort(), numbers: [...numbers, ...quotedNumbers].sort() };
+}
+
+async function livePostgres(driver, o) {
+  const diffs = [];
+  const kinds = kindsOf(o.contextKinds);
+  const cols = await driver.all(
+    `SELECT table_name, column_name, data_type, is_nullable, column_default, is_identity FROM information_schema.columns
+      WHERE table_schema = current_schema() AND table_name IN ('ask_questions', 'ask_tool_calls') ORDER BY table_name, ordinal_position`);
+  const checks = await driver.all(
+    `SELECT t.relname AS table_name, c.conname, pg_get_constraintdef(c.oid) AS def, c.contype,
+            (SELECT array_to_string(array_agg(a.attname ORDER BY a.attname), ',') FROM pg_attribute a WHERE a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)) AS columns
+       FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid JOIN pg_namespace n ON n.oid = t.relnamespace
+      WHERE n.nspname = current_schema() AND t.relname IN ('ask_questions', 'ask_tool_calls')`);
+  const idx = await driver.all(
+    `SELECT tablename AS table_name, indexname, indexdef FROM pg_indexes WHERE schemaname = current_schema() AND tablename IN ('ask_questions', 'ask_tool_calls')`);
+  const rls = await driver.all(
+    `SELECT relname, relrowsecurity, relforcerowsecurity FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = current_schema() AND relname IN ('ask_questions', 'ask_tool_calls')`);
+  const policies = await driver.all(`SELECT tablename, policyname, permissive, roles, cmd, qual, with_check FROM pg_policies WHERE schemaname = current_schema() AND tablename IN ('ask_questions', 'ask_tool_calls')`);
+  const triggers = await driver.all(`SELECT c.relname AS table_name, t.tgname FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE NOT t.tgisinternal AND n.nspname = current_schema() AND c.relname IN ('ask_questions', 'ask_tool_calls')`);
+  const truthy = (v) => v === true || v === 't' || v === 'true' || v === 1;
+  if (!policies.every((x) => 'roles' in x)) throw new Error('ask schema: pg_policies returned no roles column');
+
+  for (const t of TABLES) {
+    const live = cols.filter((c) => c.table_name === t);
+    if (!live.length) { diffs.push(`${t}: the table does not exist`); continue; }
+    const ref = REFERENCE[t];
+    const names = live.map((c) => c.column_name);
+    for (const c of ref) {
+      const l = live.find((x) => x.column_name === c.name);
+      if (!l) { diffs.push(`${t}.${c.name}: missing`); continue; }
+      if (l.data_type !== c.pg) diffs.push(`${t}.${c.name}: is ${l.data_type}, the reference is ${c.pg}`);
+      if ((l.is_nullable === 'NO') !== c.notNull) diffs.push(`${t}.${c.name}: is ${l.is_nullable === 'NO' ? 'NOT NULL' : 'nullable'}, the reference is ${c.notNull ? 'NOT NULL' : 'nullable'}`);
+      const dflt = l.column_default == null ? null : String(l.column_default);
+      if (c.identity) { if (l.is_identity !== 'YES') diffs.push(`${t}.${c.name}: is not an identity column`); } else if (c.default === 'now') {
+        if (!dflt || !/to_char\(\(?now\(\)\s+AT\s+TIME\s+ZONE\s+'utc'/i.test(dflt) || !/YYYY-MM-DD HH24:MI:SS/.test(dflt)) diffs.push(`${t}.${c.name}: its default is not the UTC text now (${dflt})`);
+      } else if (c.default !== undefined) {
+        if (dflt === null || dflt.replace(/::\w+$/, '') !== c.default) diffs.push(`${t}.${c.name}: its default is ${dflt}, the reference is ${c.default}`);
+      } else if (dflt !== null) diffs.push(`${t}.${c.name}: has a default (${dflt}) the reference does not`);
+      if (c.check) {
+        const mine = checks.filter((k) => k.table_name === t && k.contype === 'c' && k.columns === c.name);
+        if (mine.length !== 1) { diffs.push(`${t}.${c.name}: has ${mine.length} CHECK constraints, the reference has 1`); continue; }
+        const got = literalsOf(mine[0].def);
+        const wantValues = (c.check.ctx ? kinds : c.check.values || []).slice().sort();
+        const wantNumbers = (c.check.numbers || []).slice().sort();
+        if (JSON.stringify(got.values) !== JSON.stringify(wantValues)) diffs.push(`${t}.${c.name}: its CHECK allows ${JSON.stringify(got.values)}, the reference ${JSON.stringify(wantValues)}`);
+        if (JSON.stringify(got.numbers) !== JSON.stringify(wantNumbers)) diffs.push(`${t}.${c.name}: its CHECK bounds are ${JSON.stringify(got.numbers)}, the reference's ${JSON.stringify(wantNumbers)}`);
+      } else if (checks.some((k) => k.table_name === t && k.contype === 'c' && k.columns === c.name)) diffs.push(`${t}.${c.name}: has a CHECK the reference does not`);
+    }
+    const extra = names.filter((n) => !ref.some((c) => c.name === n) && n !== 'partner_id');
+    for (const n of extra) diffs.push(`${t}.${n}: a column the reference does not have`);
+    const hasPartner = names.includes('partner_id');
+    const mineC = checks.filter((k) => k.table_name === t);
+    const refChecks = new Set(ref.filter((c) => c.check).map((c) => c.name));
+    for (const k of mineC.filter((x) => x.contype === 'c' && !refChecks.has(x.columns))) diffs.push(`${t}: a CHECK the reference does not have (${k.conname}: ${k.def})`);
+    if (o.tenancy === true) {
+      // REVIEW M1 OF PR #9: every part of the generated tenancy, not just its presence.
+      const p = live.find((x) => x.column_name === 'partner_id');
+      if (!p) diffs.push(`${t}: no partner_id (the generated tenancy migration has not run)`);
+      else {
+        if (p.is_nullable !== 'NO') diffs.push(`${t}.partner_id: is nullable`);
+        if (p.data_type !== 'bigint') diffs.push(`${t}.partner_id: is ${p.data_type}, the generated tenancy makes it bigint`);
+        if (exprNorm(p.column_default) !== exprNorm(PARTNER_DEFAULT)) diffs.push(`${t}.partner_id: its default is not exactly the session's partner, ${PARTNER_DEFAULT} (it is ${p.column_default})`);
+      }
+      const r = rls.find((x) => x.relname === t);
+      if (!r || !truthy(r.relrowsecurity) || !truthy(r.relforcerowsecurity)) diffs.push(`${t}: row-level security is not enabled AND forced`);
+      const pol = policies.filter((x) => x.tablename === t);
+      if (pol.length !== 1) diffs.push(`${t}: has ${pol.length} row-level security policies, the generated tenancy has exactly 1`);
+      for (const x of pol) {
+        if (x.cmd !== 'ALL') diffs.push(`${t}: policy ${x.policyname} is FOR ${x.cmd}, not FOR ALL`);
+        if (x.permissive !== 'PERMISSIVE') diffs.push(`${t}: policy ${x.policyname} is ${x.permissive}`);
+        // EXACTLY THE GENERATED EXPRESSION (re-review of PR #9), compared with casts, brackets, spacing and case taken out —
+        // so "… OR true", "<>", ">=", an IS NOT NULL form or another scope arm is a difference, on any server version.
+        const want = exprNorm(o.policyExpression || POLICY_EXPRESSION);
+        for (const [what, expr] of [['USING', x.qual], ['WITH CHECK', x.with_check]]) {
+          if (exprNorm(expr) !== want) diffs.push(`${t}: policy ${x.policyname}'s ${what} is not the generated tenancy expression (${expr || 'none'})`);
+        }
+        const roles = Array.isArray(x.roles) ? x.roles : String(x.roles || '').replace(/^\{|\}$/g, '').split(',').filter(Boolean);
+        if (roles.length !== 1 || roles[0] !== 'public') diffs.push(`${t}: policy ${x.policyname} applies TO ${roles.join(', ') || 'nobody'}, not to every role (public)`);
+      }
+      const toPartners = mineC.filter((k) => k.contype === 'f' && /REFERENCES partners\(id\)/.test(k.def) && k.columns === 'partner_id');
+      if (toPartners.length !== 1) diffs.push(`${t}.partner_id: ${toPartners.length} keys to partners(id), the generated tenancy has 1`);
+      else if (/ON DELETE (CASCADE|SET)/.test(toPartners[0].def)) diffs.push(`${t}.partner_id: its key to partners deletes or re-homes rows (${toPartners[0].def})`);
+      if (!idx.some((x) => x.table_name === t && x.indexname === `idx_${t}_partner` && /USING btree \(partner_id\)\s*$/.test(x.indexdef))) diffs.push(`idx_${t}_partner: the tenancy btree index on (partner_id) does not exist`);
+    } else if (o.tenancy === false && hasPartner) diffs.push(`${t}: has partner_id, and tenancy: false was asked for`);
+    for (const [name, on] of Object.entries(INDEXES[t])) {
+      const i = idx.find((x) => x.indexname === name);
+      const colsOf = (def) => ((/\((.*)\)\s*$/.exec(def) || [])[1] || '').split(',').map((x) => x.trim());
+      if (!i) diffs.push(`${name}: the index does not exist`);
+      else if (JSON.stringify(colsOf(i.indexdef)) !== JSON.stringify(on) || /UNIQUE/i.test(i.indexdef) || !/ USING btree \(/.test(i.indexdef)) diffs.push(`${name}: is ${i.indexdef}, the reference is a btree on (${on.join(', ')})`);
+    }
+    // NO EXTRA INDEXES OR TRIGGERS, as on the SQLite side: an index not in the reference, not the tenancy one and not backing
+    // a key or unique constraint is a difference; so is any trigger (one could rewrite partner_id).
+    const backing = new Set(mineC.filter((k) => k.contype === 'p' || k.contype === 'u').map((k) => k.conname));
+    for (const i of idx.filter((x) => x.table_name === t)) {
+      if (INDEXES[t][i.indexname] || backing.has(i.indexname) || (o.tenancy !== false && i.indexname === `idx_${t}_partner`)) continue;
+      diffs.push(`${i.indexname}: an index the reference does not have (${i.indexdef})`);
+    }
+    for (const x of triggers.filter((y) => y.table_name === t)) diffs.push(`${t}: a trigger the reference does not have (${x.tgname})`);
+  }
+  // THE LOOK-UPS' KEY TO THEIR QUESTION, ON DELETE CASCADE: with tenancy exactly the generated composite one, (question_id,
+  // partner_id) → ask_questions (id, partner_id), and the parent's UNIQUE (id, partner_id); without it, the plain one.
+  const fks = checks.filter((k) => k.table_name === 'ask_tool_calls' && k.contype === 'f' && /REFERENCES ask_questions\(/.test(k.def));
+  const composite = (k) => k.columns === 'partner_id,question_id' && /FOREIGN KEY \(question_id, partner_id\) REFERENCES ask_questions\(id, partner_id\)/.test(k.def);
+  const plain = (k) => k.columns === 'question_id' && /REFERENCES ask_questions\(id\)/.test(k.def);
+  if (!fks.length) diffs.push('ask_tool_calls.question_id: no foreign key to ask_questions');
+  if (fks.length > 1) diffs.push(`ask_tool_calls.question_id: ${fks.length} keys to ask_questions, the reference has 1`);
+  for (const k of fks) {
+    if (!/ON DELETE CASCADE/.test(k.def)) diffs.push(`ask_tool_calls: key ${k.conname} to ask_questions is not ON DELETE CASCADE`);
+    // ON UPDATE CASCADE (the generated one) or NO ACTION / RESTRICT — never SET DEFAULT or SET NULL, which re-parent a row.
+    if (/ON UPDATE SET/.test(k.def)) diffs.push(`ask_tool_calls: key ${k.conname} re-parents rows on update (${k.def})`);
+    if (o.tenancy === true && !composite(k)) diffs.push(`ask_tool_calls: key ${k.conname} is not the composite (question_id, partner_id) → ask_questions (id, partner_id) (${k.def})`);
+    if (o.tenancy !== true && !plain(k) && !composite(k)) diffs.push(`ask_tool_calls: key ${k.conname} is neither the plain nor the composite key (${k.def})`);
+  }
+  const others = checks.filter((k) => k.contype === 'f' && !fks.includes(k) && !(k.columns === 'partner_id' && /REFERENCES partners\(id\)/.test(k.def)));
+  for (const k of others) diffs.push(`${k.table_name}: a foreign key the reference does not have (${k.def})`);
+  if (o.tenancy === true && !checks.some((k) => k.table_name === 'ask_questions' && k.contype === 'u' && k.columns === 'id,partner_id')) diffs.push('ask_questions: no UNIQUE (id, partner_id) for the composite key');
+  const uniques = checks.filter((k) => k.contype === 'u' && !(k.table_name === 'ask_questions' && (k.columns === 'public_id' || k.columns === 'id,partner_id')));
+  for (const k of uniques) diffs.push(`${k.table_name}: a UNIQUE the reference does not have (${k.def})`);
+  if (!checks.some((k) => k.table_name === 'ask_questions' && k.contype === 'u' && k.columns === 'public_id')) diffs.push('ask_questions.public_id: not UNIQUE');
+  return diffs;
+}
+
+/**
+ * Do the LIVE tables match the reference? [] when they do. `tenancy`: true (partner_id + RLS required — an app on
+ * Postgres after its tenancy migration), false (must be absent), or undefined (either).
+ * @param {object} driver a db-worker driver ({ all, dialect: { kind } })
+ * @param {{contextKinds: string[], tenancy?: boolean, policyExpression?: string}} o — policyExpression: the app tenancy
+ *   manifest POLICY_EXPRESSION, when it is not the framework generator default
+ */
+async function diffLiveTables(driver, o) {
+  const kind = driver && driver.dialect && driver.dialect.kind;
+  if (kind === 'sqlite') return liveSqlite(driver, o);
+  if (kind === 'postgres') return livePostgres(driver, o);
+  throw new Error('ask schema: diffLiveTables needs a db-worker driver (dialect.kind sqlite or postgres)');
+}
+
+/** The column list the model reads and writes, per table — the `SCHEMA` export (notify's precedent). */
+const SCHEMA = Object.freeze(Object.fromEntries(TABLES.map((t) => [t, Object.freeze(REFERENCE[t].map((c) => c.name))])));
+
+module.exports = { TABLES, REFERENCE, SCHEMA, INDEXES, referenceMigration, statementsFor, statementsOf, diffMigration, diffLiveTables, literalsOf, norm };

package/lib/settings.js

@@ -0,0 +1,142 @@
+/**
+ * Ask settings — ONE CANONICAL SET for every app (D-0169 item 5): the same names, labels, help text, defaults and ranges,
+ * owned here. An app chooses only WHERE each value is stored:
+ *
+ *   new apps (desk, Noc)   the canonical keys, `ask.<name>` — pass nothing
+ *   the hub                `ask.<name>` — the canonical keys ARE its keys (lib/settingsCatalogue.js), nothing to map
+ *   soc                 `ask_<name>` — pass `storageKey: (name) => \`ask_${name}\`` (its stored rows predate this)
+ *
+ * The mapping exists ONLY for backward compatibility: a rename would move stored values and the bench record for no gain.
+ * Labels and wording are never per app.
+ *
+ * DEFAULTS LIVE HERE, IN CODE (the schema seeds nothing): Ask OFF until the platform switches it on; 30 questions an hour
+ * and 200 a day per person, 500,000 tokens a day per partner; questions kept 30 days; every tool on. A stored value that
+ * does not parse falls back to the default AND is reported by `read()` as `invalid`, so the Ask tab can say so instead of
+ * silently showing the default as if it were the setting.
+ */
+
+'use strict';
+
+const RETENTIONS = Object.freeze(['30', '90', 'audit']);
+
+/**
+ * THE CANONICAL SET. `name` is the canonical storage suffix; `field` the read() property; `form` the form field. Order is
+ * the Ask tab's order.
+ */
+const CANON = Object.freeze([
+  { name: 'enabled', field: 'enabled', form: 'enabled', default: false,
+    label: 'Answer questions here',
+    help: 'The Ask box in the top bar, route ask. People also need ai.ask in one of their roles. Every look-up runs under the asker’s own permissions and tenancy.' },
+  { name: 'limit_hour', field: 'limitHour', form: 'limit_hour', default: 30, min: 1, max: 10000,
+    label: 'Questions per person, per hour', help: null, error: 'Enter a whole number from 1 to 10,000.' },
+  { name: 'limit_day', field: 'limitDay', form: 'limit_day', default: 200, min: 1, max: 100000,
+    label: 'Questions per person, per day', help: 'A day runs midnight to midnight UTC.', error: 'Enter a whole number from 1 to 100,000.' },
+  { name: 'partner_tokens_day', field: 'partnerTokensDay', form: 'partner_tokens_day', default: 500000, min: 0, max: 1000000000,
+    label: 'Tokens per partner, per day', help: '0 means no partner limit. The endpoints’ own daily caps are installation-wide, under Endpoints.',
+    error: 'Enter a whole number of tokens (0 means no partner limit).' },
+  { name: 'retention', field: 'retention', form: 'retention', default: '30',
+    label: 'Retention', help: 'Questions, answers, look-ups and feedback are deleted after this. The audit sentence “asked a question” stays with the audit trail.',
+    options: [['30', '30 days'], ['90', '90 days'], ['audit', 'As long as the audit trail']], error: 'Choose how long questions are kept.' },
+  { name: 'tools_off', field: 'toolsOff', form: 'tools', default: [],
+    label: 'Tools', help: 'All read-only. A tool switched off is left out of what the AI is offered, for everyone. A tool switched on still runs only for people who hold its page permission.' }
+].map(Object.freeze));
+
+/** The bench record's canonical name — stored beside the settings, through the same key mapping. */
+const BENCH = 'bench';
+const ORDER_ERROR = 'The hourly limit cannot be above the daily one.';
+
+const DEFAULTS = Object.freeze(Object.fromEntries(CANON.map((s) => [s.field, s.default])));
+const canonicalKey = (name) => `ask.${name}`;
+
+const intIn = (v, lo, hi) => {
+  if (v == null || v === '') return null;
+  if (!/^\d{1,10}$/.test(String(v).trim())) return null;
+  const n = Number(v);
+  return n >= lo && n <= hi ? n : null;
+};
+const byField = Object.fromEntries(CANON.map((s) => [s.field, s]));
+
+/**
+ * Settings bound to an app's store.
+ * @param {object} o
+ * @param {{get(key): Promise<string|null>, set(key, value): Promise}} o.store   installation-wide keys
+ * @param {string[]} o.toolIds        the catalogue's ids (tools_off may name only these)
+ * @param {Function} [o.storageKey]   (canonical name) → the stored key; default `ask.<name>`
+ */
+function createSettings(o) {
+  if (!o || !o.store || typeof o.store.get !== 'function' || typeof o.store.set !== 'function') throw new Error('ask settings: store {get, set} is required');
+  const keyOf = typeof o.storageKey === 'function' ? o.storageKey : canonicalKey;
+  const KEYS = Object.freeze(Object.fromEntries(CANON.map((s) => [s.field, keyOf(s.name)])));
+  const BENCH_KEY = keyOf(BENCH);
+  const all = [...Object.values(KEYS), BENCH_KEY];
+  if (new Set(all).size !== all.length || all.some((k) => typeof k !== 'string' || !/^[a-z][a-z0-9_.:-]{1,63}$/.test(k))) {
+    throw new Error('ask settings: storageKey must map every canonical name to a distinct key');
+  }
+  const toolIds = Object.freeze([...(o.toolIds || [])]);
+
+  /** Every Ask setting, defaults filled in; `invalid` names any stored value that did not parse. */
+  async function read() {
+    const raw = {};
+    for (const [field, key] of Object.entries(KEYS)) raw[field] = await o.store.get(key);
+    const invalid = [];
+    const pick = (field, v) => { if (raw[field] != null && raw[field] !== '' && v == null) invalid.push(field); return v == null ? DEFAULTS[field] : v; };
+    // TOOLS OFF FAILS CLOSED (review M2 of PR #9): an unknown id in the stored list drops only itself and is reported — the
+    // known ids stay off. A list that does not parse at all switches EVERY tool off and is reported, so a damaged row can
+    // never turn tools back on.
+    let toolsOff = null;
+    if (raw.toolsOff != null && raw.toolsOff !== '') {
+      let x;
+      try { x = JSON.parse(raw.toolsOff); } catch (_) { x = undefined; }
+      if (Array.isArray(x)) {
+        toolsOff = toolIds.filter((id) => x.includes(id));
+        if (x.some((id) => !toolIds.includes(id))) invalid.push('toolsOff');
+      } else {
+        toolsOff = [...toolIds];
+        invalid.push('toolsOff');
+      }
+    }
+    const lim = (f) => intIn(raw[f], byField[f].min, byField[f].max);
+    // `enabled` is 'true' or it is off; anything else stored is reported (it reads as off, the safe side).
+    if (raw.enabled != null && raw.enabled !== '' && !['true', 'false'].includes(raw.enabled)) invalid.push('enabled');
+    return {
+      enabled: raw.enabled === 'true',
+      limitHour: pick('limitHour', lim('limitHour')),
+      limitDay: pick('limitDay', lim('limitDay')),
+      partnerTokensDay: pick('partnerTokensDay', lim('partnerTokensDay')),
+      retention: pick('retention', RETENTIONS.includes(raw.retention) ? raw.retention : null),
+      toolsOff: pick('toolsOff', toolsOff),
+      invalid
+    };
+  }
+
+  /** Validate a form's values. Returns { values } ready for `write`, or { errors } keyed by form field. */
+  function parseForm(body = {}) {
+    const errors = {};
+    const num = (f) => intIn(body[byField[f].form], byField[f].min, byField[f].max);
+    const limitHour = num('limitHour');
+    const limitDay = num('limitDay');
+    const partnerTokensDay = num('partnerTokensDay');
+    for (const [f, v] of [['limitHour', limitHour], ['limitDay', limitDay], ['partnerTokensDay', partnerTokensDay]]) if (v == null) errors[byField[f].form] = byField[f].error;
+    if (limitHour != null && limitDay != null && limitHour > limitDay) errors.limit_hour = ORDER_ERROR;
+    const retention = RETENTIONS.includes(String(body.retention)) ? String(body.retention) : null;
+    if (!retention) errors.retention = byField.retention.error;
+    const on = [].concat(body.tools || []).map(String);
+    const toolsOff = toolIds.filter((id) => !on.includes(id));
+    if (Object.keys(errors).length) return { errors };
+    return { values: { enabled: body.enabled === 'on' || body.enabled === 'true', limitHour, limitDay, partnerTokensDay, retention, toolsOff } };
+  }
+
+  /** Write validated values (from parseForm). Installation-wide. */
+  async function write(v) {
+    await o.store.set(KEYS.enabled, v.enabled ? 'true' : 'false');
+    await o.store.set(KEYS.limitHour, String(v.limitHour));
+    await o.store.set(KEYS.limitDay, String(v.limitDay));
+    await o.store.set(KEYS.partnerTokensDay, String(v.partnerTokensDay));
+    await o.store.set(KEYS.retention, v.retention);
+    await o.store.set(KEYS.toolsOff, JSON.stringify(v.toolsOff));
+  }
+
+  return { CANON, DEFAULTS, RETENTIONS, KEYS, BENCH_KEY, read, parseForm, write };
+}
+
+module.exports = { createSettings, CANON, DEFAULTS, RETENTIONS, BENCH, canonicalKey, ORDER_ERROR };