@bongos/core 1.19.963 → 1.19.965

package/tests/goal_forest_lib.mjs

@@ -0,0 +1,153 @@
+// tests/goal_forest_lib.mjs — the per-goal dependency forest's model and
+// layout, EXECUTED (task 1003480, goal 1000089, ADR 0227 §6 item 4 + §10.5).
+//
+// goal-forest-lib.js is pure, so this runs the real code over synthetic
+// corpora, including one at the measured worst case (§10.5: the biggest single
+// goal's forest is 127 tasks). What is pinned: no task is drawn twice or on
+// top of another, a task always sits right of what it depends on, two
+// independent chains in one goal share the picture without overlapping, and
+// every fact in the picture is also a table row.
+//
+// Run:  node tests/goal_forest_lib.mjs
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const L = require(path.join(ROOT, 'modules/hall-ui/public/goal-forest-lib.js'));
+
+const { test, summary } = makeRunner();
+
+const node = (id, extra = {}) => ({ task_id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
+const edge = (from, to) => ({ from: String(from), to: String(to) });
+
+function overlaps(a, b) {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+function assertSound(a, lay, label) {
+  const ids = lay.nodes.map((n) => n.id);
+  assert.equal(new Set(ids).size, ids.length, `${label}: no task drawn twice`);
+  assert.equal(ids.length, a.order.length, `${label}: every analysed node is drawn — none are edge-less by construction`);
+  for (let i = 0; i < lay.nodes.length; i++) {
+    for (let j = i + 1; j < lay.nodes.length; j++) {
+      assert.equal(overlaps(lay.nodes[i], lay.nodes[j]), false, `${label}: ${lay.nodes[i].id} overlaps ${lay.nodes[j].id}`);
+    }
+  }
+  for (const n of lay.nodes) {
+    assert.ok(n.x >= 0 && n.y >= 0, `${label}: ${n.id} is on the canvas`);
+    assert.ok(n.x + n.w <= lay.width && n.y + n.h <= lay.height, `${label}: ${n.id} fits inside the svg's own size`);
+  }
+}
+
+// ---- structure -----------------------------------------------------------------
+
+await test('an edge means "from waits on to", and each node counts its own degree', () => {
+  const a = L.analyse({ nodes: [node(1), node(2), node(3)], edges: [edge(1, 2), edge(1, 3)] });
+  assert.equal(a.waits['1'].length, 2);
+  assert.equal(a.needed['2'].length, 1);
+});
+
+await test('a self edge, a duplicate, and an edge to an unknown task are all ignored', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(1, 99), edge(2, 2), edge(1, 2), edge(1, 2)] });
+  assert.equal(a.edges.length, 1);
+});
+
+await test('chains are found, largest first — two disjoint pairs are two chains of size 2, not one', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6, 7].map((i) => node(i)), edges: [edge(1, 2), edge(3, 4), edge(5, 6), edge(6, 7)] });
+  assert.deepEqual(a.chains.map((c) => c.length), [3, 2, 2]);
+});
+
+// ---- layout --------------------------------------------------------------------
+
+await test('a task sits to the RIGHT of every task it depends on', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(4, 2)] });
+  const lay = L.layout(a);
+  const x = Object.fromEntries(lay.nodes.map((n) => [n.id, n.x]));
+  for (const e of a.edges) assert.ok(x[e.to] < x[e.from], `${e.from} waits on ${e.to}, must be right of it`);
+});
+
+await test('two independent chains in one goal share the picture with no overlap', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(1, 2), edge(3, 4)] });
+  const lay = L.layout(a);
+  assertSound(a, lay, 'two chains');
+});
+
+await test('a would-be cycle terminates and still places every task', () => {
+  const a = L.analyse({ nodes: [1, 2, 3].map((i) => node(i)), edges: [edge(1, 2), edge(2, 1), edge(3, 1)] });
+  const lay = L.layout(a);
+  assert.equal(lay.nodes.length, 3);
+  assertSound(a, lay, 'cycle');
+});
+
+await test('the same data always gives the same picture', () => {
+  const p = { nodes: [1, 2, 3, 4, 5].map((i) => node(i)), edges: [edge(2, 1), edge(3, 1), edge(4, 2), edge(5, 2)] };
+  assert.deepEqual(L.layout(L.analyse(p)), L.layout(L.analyse(p)));
+});
+
+await test('an edge path starts at the dependency\'s right edge and ends at the dependent\'s left edge', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(2, 1)] });
+  const lay = L.layout(a);
+  const by = Object.fromEntries(lay.nodes.map((n) => [n.id, n]));
+  const [e] = lay.edges;
+  assert.ok(e.d.startsWith(`M${by['1'].x + lay.nodeW} ${by['1'].y + lay.nodeH / 2}`));
+  assert.ok(e.d.endsWith(`${by['2'].x} ${by['2'].y + lay.nodeH / 2}`));
+});
+
+await test('THE MEASURED WORST CASE: a 127-task single goal forest lays out soundly and fast (ADR 0227 §10.5)', () => {
+  let seed = 20260921;
+  const rnd = () => { seed = (seed * 1664525 + 1013904223) % 4294967296; return seed / 4294967296; };
+  const ids = Array.from({ length: 127 }, (_, i) => i + 1);
+  const nodes = ids.map((i) => node(i));
+  const edges = [];
+  for (let i = 1; i < ids.length; i++) edges.push(edge(ids[i], ids[Math.floor(rnd() * i)]));
+  const a = L.analyse({ nodes, edges });
+  const t0 = Date.now();
+  const lay = L.layout(a);
+  const ms = Date.now() - t0;
+  assertSound(a, lay, 'worst case');
+  assert.ok(ms < 500, `laid out in ${ms}ms`);
+});
+
+// ---- table + description ---------------------------------------------------------
+
+await test('the table has one row per task and carries both directions by name', () => {
+  const a = L.analyse({ nodes: [node(1, { title: 'Base' }), node(2, { title: 'Top' })], edges: [edge(2, 1)] });
+  const rows = L.tableRows(a);
+  const base = rows.find((r) => r.id === '1');
+  const top = rows.find((r) => r.id === '2');
+  assert.deepEqual(top.waits, [{ id: '1', title: 'Base' }]);
+  assert.deepEqual(base.needed, [{ id: '2', title: 'Top' }]);
+});
+
+await test('priority renders as P1..P5, or an em dash for null', () => {
+  const a = L.analyse({ nodes: [node(1, { priority: 1 }), node(2, { priority: null })], edges: [edge(1, 2)] });
+  const rows = L.tableRows(a);
+  assert.equal(rows.find((r) => r.id === '1').priority, 'P1');
+  assert.equal(rows.find((r) => r.id === '2').priority, '—');
+});
+
+await test('a lone pair is labelled plainly, a real chain is labelled and counted', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(1, 2), edge(2, 3), edge(2, 4)] });
+  const rows = L.tableRows(a);
+  assert.match(rows[0].chainLabel, /^Chain 1 · 4 tasks$/);
+});
+
+await test('describe states the numbers plainly, and an empty forest says so', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(1, 2)] });
+  assert.match(L.describe(a), /^2 tasks in this goal have a dependency.*in 1 chain\.$/);
+  assert.equal(L.describe(L.analyse({})), 'No task in this goal depends on another task in this goal.');
+});
+
+// ---- purity -----------------------------------------------------------------------
+
+await test('the lib is pure: no DOM, no fetch, no cross-goal input', () => {
+  const fs = require('fs');
+  const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/goal-forest-lib.js'), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  assert.equal(/\bdocument\b|\bfetch\b|\bwindow\b|XMLHttpRequest/.test(src.replace(/root\.OTBGoalForestLib/, '')), false);
+  assert.equal(/goal_id|category/i.test(src), false, 'this file knows nothing about goals or categories — that is the map, not the forest');
+});
+
+summary();

package/tests/goal_forest_page.mjs

@@ -0,0 +1,196 @@
+// tests/goal_forest_page.mjs — the per-goal dependency forest's WIRING on the
+// Goals page, EXECUTED (task 1003480, goal 1000089, ADR 0227 §6 item 4).
+//
+// goal_forest_lib.mjs proves the layout; goal_forest.mjs proves the server
+// route. What neither can see is whether goals-render.js actually calls the
+// real endpoint, actually draws with the real lib, and actually renders the
+// honest states ADR 0227 requires (no edges → said plainly; a failed read →
+// said plainly; never a stack, never a blank canvas). This runs the REAL
+// goal-forest-lib.js + the REAL createGoalsRender(ctx) factory from
+// goals-render.js in a vm — calling `loadDependencyForest`/
+// `renderDependencyForest` directly (they are exported for exactly this)
+// rather than booting the whole page, which needs a much larger fixture for
+// members/completion/invites this task never touches.
+//
+// Run:  node tests/goal_forest_page.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeRunner, makeEl, walk } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+const LIB_JS = read('goal-forest-lib.js');
+const FOREST_RENDER_JS = read('goal-forest-render.js');
+const RENDER_JS = read('goals-render.js');
+
+const { test, summary } = makeRunner();
+const tick = () => new Promise((r) => setTimeout(r, 0));
+const settle = async () => { for (let i = 0; i < 20; i++) await tick(); };
+
+const t = (id, extra = {}) => ({ task_id: String(id), title: `Task ${id}`, status: 'ready', priority: 3, ...extra });
+const e = (from, to) => ({ from: String(from), to: String(to) });
+
+async function boot({ status = 200, fail = false, payload = { nodes: [], edges: [] } } = {}) {
+  const root = makeEl('div');
+  const reg = (id) => { const el = makeEl('div', { id }); root.appendChild(el); return el; };
+  ['goal-deps-h', 'goal-deps-count', 'goal-deps-lede', 'goal-deps-body'].forEach(reg);
+
+  const documentObj = {
+    getElementById: (id) => walk(root, (el) => (el.id === id ? el : null)),
+    createElementNS(_ns, tag) {
+      const el = makeEl(tag);
+      const orig = el.setAttribute.bind(el);
+      el.setAttribute = (k, v) => { orig(k, v); if (k === 'class') el.className = String(v); if (k === 'id') el.id = String(v); };
+      return el;
+    },
+  };
+  const windowObj = {
+    OTB: {
+      escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+      $: (sel) => documentObj.getElementById(String(sel).replace(/^#/, '')),
+      fmtNum: (n) => String(n), fmtDate: (iso) => String(iso ?? ''), toast() {}, rankLabel: (r) => String(r ?? ''), categoryChip: () => '',
+    },
+    OTBTaskLib: {},
+    OTBKit: {
+      makePager: () => ({ page: 1, perPage: 25 }), paginate: () => [], wirePager() {}, pagerBarHtml: () => '',
+      makeTabs: () => ({}), makeFilterBar: () => ({}), emptyStateHtml: (m) => m, skeletonRows: () => '',
+    },
+    OTBGoalsLib: {},
+  };
+  const requests = [];
+  const sandbox = {
+    window: windowObj, self: windowObj, document: documentObj,
+    console: { error() {}, warn() {}, log() {} },
+    setTimeout, clearTimeout,
+    fetch: async () => { throw new Error('goals-render.js must use ctx.getJSON, not fetch directly'); },
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(LIB_JS, sandbox, { filename: 'goal-forest-lib.js' });
+  vm.runInContext(FOREST_RENDER_JS, sandbox, { filename: 'goal-forest-render.js' });
+  vm.runInContext(RENDER_JS, sandbox, { filename: 'goals-render.js' });
+
+  const state = { current: 7, forest: null, forestError: false };
+  const ctx = {
+    API: '/api/bongos',
+    state,
+    sameId: (a, b) => String(a) === String(b),
+    getJSON: async (p) => {
+      requests.push(p);
+      if (fail) throw new Error('offline');
+      if (status === 401) throw Object.assign(new Error('redirecting to auth'), {});
+      return payload;
+    },
+  };
+  const renderers = windowObj.OTBGoalsRender(ctx);
+  return { $: documentObj.getElementById, requests, state, renderers };
+}
+
+// ---- the honest states (ADR 0227) ---------------------------------------------
+
+await test('loadDependencyForest calls the real per-goal endpoint — never a global one', async () => {
+  const h = await boot({ payload: { nodes: [], edges: [] } });
+  await h.renderers.loadDependencyForest(7);
+  assert.deepEqual(h.requests, ['/api/bongos/goals/7/dependency-forest']);
+});
+
+await test('no dependency at all says so plainly — no canvas, no stack, no leftover count', async () => {
+  const h = await boot({ payload: { nodes: [], edges: [] } });
+  await h.renderers.loadDependencyForest(7);
+  assert.match(h.$('goal-deps-lede').textContent, /No task in this goal depends on another task in this goal/);
+  assert.equal(h.$('goal-deps-body').innerHTML, '');
+  assert.equal(h.$('goal-deps-count').hidden, true);
+});
+
+await test('a failed read says so plainly, distinct from "still loading" and from "nothing to show"', async () => {
+  const h = await boot({ fail: true });
+  await h.renderers.loadDependencyForest(7);
+  assert.match(h.$('goal-deps-lede').textContent, /Couldn.t load this goal.s task dependencies/);
+  assert.equal(h.$('goal-deps-count').hidden, true, 'a failed read pills the same as an empty one — never a literal 0');
+});
+
+await test('while loading, the lede says so and the body stays empty (no stale content from a prior goal)', async () => {
+  const h = await boot({ payload: { nodes: [t(1), t(2)], edges: [e(1, 2)] } });
+  const p = h.renderers.loadDependencyForest(7); // deliberately not awaited yet
+  assert.equal(h.$('goal-deps-lede').textContent, 'Reading…');
+  assert.equal(h.$('goal-deps-body').innerHTML, '');
+  await p;
+});
+
+await test('a stale response for a goal the reader navigated away from is dropped', async () => {
+  const h = await boot({ payload: { nodes: [t(1), t(2)], edges: [e(1, 2)] } });
+  const p = h.renderers.loadDependencyForest(7);
+  h.state.current = 999; // navigated to a different goal mid-request
+  await p;
+  assert.equal(h.$('goal-deps-lede').textContent, 'Reading…', 'the stale answer never overwrote the new goal\'s loading state');
+});
+
+// ---- a populated forest ------------------------------------------------------
+
+await test('a populated forest draws a role=img figure with no focus stops, and every fact is also a table row', async () => {
+  const h = await boot({ payload: { nodes: [t(1, { title: 'Base' }), t(2, { title: 'Top' })], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  const body = h.$('goal-deps-body');
+  const svg = body.querySelector('svg');
+  assert.ok(svg, 'the forest is drawn');
+  assert.equal(svg.getAttribute('role'), 'img');
+  assert.equal(svg.querySelectorAll('a').length, 0);
+  assert.equal(svg.querySelectorAll('[tabindex]').length, 0);
+  const table = body.querySelector('table');
+  assert.ok(table, 'the table is on the page by default (ADR 0227 §5)');
+  const rows = table.querySelector('tbody').querySelectorAll('tr');
+  assert.equal(rows.length, 2, 'one row per task');
+  assert.ok(table.textContent.includes('Base') && table.textContent.includes('Top'));
+  assert.equal(h.$('goal-deps-count').hidden, false);
+  assert.equal(h.$('goal-deps-count').textContent, '2');
+});
+
+await test('the picture scrolls inside its own region and names both overflow axes', async () => {
+  const h = await boot({ payload: { nodes: [t(1), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  const region = h.$('goal-deps-body').querySelector('.gf-scroll');
+  assert.ok(region);
+  assert.equal(region.getAttribute('tabindex'), '0');
+  const css = fs.readFileSync(path.join(HALL, 'goals.css'), 'utf8');
+  const rule = css.match(/\.gf-scroll\s*\{[^}]*\}/)[0];
+  assert.match(rule, /overflow-x:\s*auto/);
+  assert.match(rule, /overflow-y:\s*hidden/, 'one axis named alone makes the other auto (task 1004130)');
+});
+
+await test('a task title is builder-authored text and never becomes markup', async () => {
+  const evil = '<img src=x onerror=alert(1)>';
+  const h = await boot({ payload: { nodes: [t(1, { title: evil }), t(2)], edges: [e(2, 1)] } });
+  await h.renderers.loadDependencyForest(7);
+  const body = h.$('goal-deps-body');
+  assert.equal(body.querySelector('img'), null);
+  assert.ok(body.textContent.includes(evil), 'renders as the literal characters, not as HTML');
+});
+
+await test('a redirecting-to-auth failure is swallowed silently, the loadGoalTasks precedent — the page is about to navigate away', async () => {
+  const h = await boot({ status: 401 });
+  await h.renderers.loadDependencyForest(7);
+  assert.equal(h.$('goal-deps-lede').textContent, 'Reading…', 'no error flash on a redirect the browser is already leaving for');
+  assert.equal(h.state.forestError, false);
+});
+
+// ---- wiring into the detail render -------------------------------------------
+
+await test('renderDetail calls loadDependencyForest, beside loadGoalTasks, for the OPEN goal', () => {
+  assert.match(RENDER_JS, /loadGoalTasks\(g\.id\);\s*\n\s*loadDependencyForest\(g\.id\);/);
+});
+
+await test('the section is its OWN full-width block, not squeezed into the three-column band', () => {
+  const html = fs.readFileSync(path.join(HALL, 'goals.html'), 'utf8');
+  const bandAt = html.indexOf('class="scroll goal-band"');
+  const depsAt = html.indexOf('id="goal-deps-scroll"');
+  const tasksAt = html.indexOf('<h2 class="scroll__h">Tasks</h2>');
+  assert.ok(bandAt > -1 && depsAt > -1 && tasksAt > -1);
+  assert.ok(bandAt < depsAt && depsAt < tasksAt, 'band, then dependencies, then tasks');
+  assert.equal(/id="goal-deps-scroll"[\s\S]{0,400}goal-band__col/.test(html), false, 'not inside a band column');
+});
+
+summary();

package/tests/goal_invite_consent.mjs

@@ -169,7 +169,7 @@ function harness({ pendingRequests = [] } = {}) {
   };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);
-  for (const f of ['hall-kit.js', 'task-lib.js', 'goals-lib.js', 'goals-render.js']) {
+  for (const f of ['hall-kit.js', 'task-lib.js', 'goals-lib.js', 'goal-forest-render.js', 'goals-render.js']) {
     vm.runInContext(read(P + f), sandbox, { filename: f });
   }
 

package/tests/helpers.mjs

@@ -199,10 +199,14 @@ export function hallSource(pubDir = path.join(ROOT, 'modules', 'hall-ui', 'publi
   return familySource(pubDir, (f) => f === 'builders.js' || f === 'hall-render.js');
 }
 
-// The GOALS page script: goals-page.js plus its two carved siblings — goals-lib.js
-// (pure helpers, task 1003135) and goals-render.js (view painters, task 1003206).
+// The GOALS page script: goals-page.js plus its carved siblings — goals-lib.js
+// (pure helpers, task 1003135), goals-render.js (view painters, task 1003206),
+// and goal-forest-render.js (the dependency-forest drawing code goals-render.js
+// calls into via window.OTBGoalForestRender(ctx), task 1003480 — without this
+// file in the boot order, createGoalsRender throws immediately, since it calls
+// that factory eagerly at the top).
 export function goalsPageSource(pubDir = path.join(ROOT, 'modules', 'hall-ui', 'public')) {
-  return familySource(pubDir, (f) => ['goals-page.js', 'goals-lib.js', 'goals-render.js'].includes(f));
+  return familySource(pubDir, (f) => ['goals-page.js', 'goals-lib.js', 'goal-forest-render.js', 'goals-render.js'].includes(f));
 }
 
 // The KERNEL IDENTITY surface: auth.js (session resolution, the middleware and the

package/tests/projects_hub_module_picker.mjs

@@ -67,10 +67,14 @@ const PAYLOAD = {
     { type: 'non-profit', bundle: ['discord'], summary: 'Somewhere the community around the cause can gather and be heard.' },
     { type: 'not-sure', bundle: [], summary: 'Just the core, and nothing else to decide today. Add modules whenever you know what you need.' },
   ],
+  // `aliases` — search words a row is findable under that its own copy never uses
+  // (task 1003500, amending ADR 0244 §3). Never rendered, like the key. dev-box
+  // carries none on purpose, so the "a row without aliases still matches on its own
+  // words" path is exercised by the same fixture rather than by a special case.
   optional: [
-    { key: 'agents', label: 'Extra agents', summary: 'More AI agents alongside the ones every project gets.' },
+    { key: 'agents', label: 'Extra agents', summary: 'More AI agents alongside the ones every project gets.', aliases: ['bots', 'assistants', 'automation'] },
     { key: 'dev-box', label: 'Dev boxes', summary: 'A cloud workspace where a change can be tried out first.' },
-    { key: 'discord', label: 'Discord', summary: 'A Discord server that carries your build news.' },
+    { key: 'discord', label: 'Discord', summary: 'A Discord server that carries your build news.', aliases: ['chatroom', 'talk', 'community'] },
   ],
 };
 
@@ -616,8 +620,8 @@ test('the picker and the server resolve the same set for every answer an owner c
 const DEV_BOX = PAYLOAD.optional[1];
 
 test('the matcher reads a row\'s own words — its name, its summary and its key', () => {
-  // Lexical, not semantic (idea 1000552 holds the by-meaning half): the only
-  // words it knows are the ones the owner can see, plus the key they cannot.
+  // Still lexical, never semantic: the only words it knows are the ones the owner
+  // can see, plus the two it cannot — the key, and the declared aliases below.
   const h = boot({ state: { projType: 'game' } });
 
   assert.equal(h.matches(DEV_BOX, 'boxes'), true, 'by a word in the name');
@@ -626,6 +630,77 @@ test('the matcher reads a row\'s own words — its name, its summary and its key
   assert.equal(h.matches(DEV_BOX, 'discord'), false, 'and never by a word that is in none of them');
 });
 
+// ── task 1003500: the aliases, and the gap they close ────────────────────────
+// ADR 0244 §3 said "no synonyms" and deferred search-by-meaning to an embeddings
+// layer (idea 1000552). That layer was declined for this catalog: 22 modules whose
+// only free text is a title and one sentence do not need a model to be findable,
+// and a declared word list is fixable by whoever reads the complaint. These pin the
+// outcome ADR 0244 actually named as missing.
+
+test('a row is findable under a word an owner would use but its own copy never does', () => {
+  const h = boot({ state: { projType: 'game' } });
+  const discord = PAYLOAD.optional[2];
+
+  // The WORD at the heart of the example ADR 0244 §3 gave. Before this, none of
+  // these found anything: "chat", "talk" and "community" appear nowhere in
+  // Discord's label, summary or key.
+  assert.equal(h.matches(discord, 'chat'), true, 'typing "chat" finds Discord');
+  assert.equal(h.matches(discord, 'talk'), true, 'and so does the other word for it');
+  assert.equal(h.matches(discord, 'community'), true);
+  assert.equal(h.matches(PAYLOAD.optional[0], 'bots'), true, 'agents answers to "bots"');
+});
+
+test('a SENTENCE still finds nothing — aliases fix the word, not the phrase', () => {
+  // The boundary, pinned rather than promised. ADR 0244 §3 illustrated the gap with
+  // "somewhere for people to chat", and it is tempting to read the aliases above as
+  // having closed exactly that. They have not: the matcher ANDs every term, so
+  // `somewhere` and `people` must be in the haystack too, and no alias list can make
+  // a phrase query work. The fix for that is OR-then-rank, which §3 and §5 reject on
+  // their own merits — so this row failing is the DESIGN, and a future change that
+  // makes it pass should have to come here and say why.
+  const h = boot({ state: { projType: 'game' } });
+  const discord = PAYLOAD.optional[2];
+
+  assert.equal(h.matches(discord, 'somewhere for people to chat'), false,
+    'the sentence ADR 0244 named is still outside a literal AND filter');
+  assert.equal(h.matches(discord, 'people to chat'), false, 'and so is a shorter phrase around the same word');
+  assert.equal(h.matches(discord, 'chat'), true, 'while the word inside it lands — that is the whole of what aliases buy');
+});
+
+test('an alias is a search word only — it is never shown to anyone', async () => {
+  // The same standing the key has. A row that advertised "chatroom, talk, community"
+  // under its summary would be noise on a screen that is trying to be a short list.
+  const h = boot({ state: { projType: 'game' } });
+  await h.open();
+
+  for (const row of h.rows()) {
+    for (const word of ['chatroom', 'bots', 'automation']) {
+      assert.ok(!String(row.label).includes(word), `label leaks "${word}"`);
+      assert.ok(!String(row.summary).includes(word), `summary leaks "${word}"`);
+    }
+  }
+});
+
+test('aliases narrow like any other word, and a row without them still matches on its own', () => {
+  const h = boot({ state: { projType: 'game' } });
+  const discord = PAYLOAD.optional[2];
+
+  assert.equal(h.matches(discord, 'chat news'), true, 'an alias AND a summary word still narrows to the row that has both');
+  assert.equal(h.matches(discord, 'chat workspace'), false, 'an alias does not rescue a term the row cannot answer');
+  assert.equal(h.matches(DEV_BOX, 'chat'), false, 'and a row declaring no aliases is not matched by another row\'s');
+  assert.equal(h.matches(DEV_BOX, 'workspace'), true, 'while its own words keep working untouched');
+});
+
+test('typing an alias filters the band to that row, and the count says so', async () => {
+  const h = boot({ state: { projType: 'game' } });
+  await h.open();
+
+  h.type('chat');
+
+  assert.deepEqual(h.rows().map((r) => r.key), ['discord'], 'the band narrows to the row the alias names');
+  assert.match(h.filterNote(), /Showing 1 of 3/, 'and the line under the field counts honestly');
+});
+
 test('a term matches as a SUBSTRING, so a half-typed word still finds its module', () => {
   const h = boot({ state: { projType: 'game' } });
 

package/tests/provisioning_starter_bundles.mjs

@@ -379,6 +379,24 @@ test('every opt-in module carries owner-facing copy, and no module jargon rides
   }
 });
 
+test('every opt-in module declares search words its own copy does not already carry', () => {
+  // Task 1003500. The picker's filter is literal, so a module is findable only under
+  // the vocabulary WE chose for it — which is how "somewhere for people to chat" came
+  // to find nothing (ADR 0244 §3). Requiring aliases here is the same move task 1003962
+  // made for the copy above: a new opt-in module cannot ship without them.
+  for (const row of OPTIONAL_MODULES) {
+    assert.ok(Array.isArray(row.aliases) && row.aliases.length >= 3,
+      `"${row.key}" needs at least three search aliases — an owner who does not know its name must still find it`);
+    const own = `${row.label} ${row.summary} ${row.key}`.toLowerCase();
+    for (const alias of row.aliases) {
+      assert.equal(alias, alias.toLowerCase().trim(), `"${row.key}" alias "${alias}" must be lower-case and trimmed — the haystack is lower-cased, never the query alone`);
+      assert.doesNotMatch(alias, /\s/, `"${row.key}" alias "${alias}" must be one word — the query is split on whitespace, so a phrase can never match`);
+      assert.ok(!own.includes(alias),
+        `"${row.key}" alias "${alias}" is already in its label, summary or key — it is findable without it, and a duplicate is a line to maintain for nothing`);
+    }
+  }
+});
+
 test('every module a bundle preselects is a row the picker can actually render', () => {
   // A preselect with no catalog row would light up nothing — the panel would
   // silently ship a choice the owner cannot see or switch off.
@@ -483,7 +501,13 @@ test('GET /provisioning/starter-bundles carries the opt-in catalog the picker re
   assert.equal(res.status, 200, res.raw);
   assert.deepEqual(res.body.optional, OPTIONAL_MODULES.map((m) => ({ ...m })));
   for (const row of res.body.optional) {
-    assert.deepEqual(Object.keys(row).sort(), ['key', 'label', 'summary']);
+    // `aliases` joined this shape in task 1003500 — search words the picker's
+    // matcher reads and never renders. Optional, so a row may carry none.
+    assert.deepEqual(Object.keys(row).sort().filter((k) => k !== 'aliases'), ['key', 'label', 'summary']);
+    if (row.aliases !== undefined) {
+      assert.ok(Array.isArray(row.aliases) && row.aliases.every((a) => typeof a === 'string'),
+        `"${row.key}" aliases must be a list of strings — the panel joins them into one haystack`);
+    }
   }
 });