@bongos/core 1.19.811 → 1.19.812

package/scripts/gds/search-ingest-db.js

@@ -90,6 +90,43 @@ const SOURCES = [
     map: (r) => buildRows({ sourceRef: `session_log:${r.id}`, title: `Session log ${r.id}${r.task_id ? ` · task ${r.task_id}` : ''}`, body: r.notes_md, scrub: true }) },
   { name: 'task_grades', query: `SELECT id, task_id, notes_md FROM task_grades WHERE notes_md IS NOT NULL`,
     map: (r) => buildRows({ sourceRef: `grade:${r.id}`, title: `Grade · task ${r.task_id}`, body: r.notes_md, scrub: true }) },
+  // Speciality documents → OWNER-SCOPED unless the speciality is public.
+  //
+  // The knowledge an expert trained INTO a speciality (task 1003855). This source
+  // is what makes the injected contract's "search it with /recall" true rather
+  // than aspirational.
+  //
+  // SCOPING ERRS TOWARD UNDER-SHARING. This index expresses only two axes —
+  // min_rank and owner_builder_id — and a 'project' speciality is neither: it is
+  // visible to a set of builders the index cannot name. So only a PUBLIC
+  // speciality's documents are corpus-wide; private AND project both fall back to
+  // owner-scoped. A project member therefore sees the speciality and can adopt it,
+  // but does not get its documents in /recall until it is public. That is a
+  // smaller answer than the sharing rule allows, which is the right direction for
+  // an index to be wrong in — the alternative leaks one project's material to
+  // every builder on the instance.
+  { name: 'specialities_documents',
+    // A row is indexed ONLY if it is public (corpus-wide, deliberately) or has a
+    // real builder owner to scope it to. The WHERE clause is the first of two
+    // guards: a project-owned, non-public speciality never leaves Postgres.
+    query: `SELECT d.id, d.title, d.body_md, s.name AS speciality_name,
+                   s.visibility, s.owner_builder_id
+              FROM specialities_documents d JOIN specialities_catalog s ON s.id = d.speciality_id
+             WHERE s.visibility = 'public' OR s.owner_builder_id IS NOT NULL`,
+    map: (r) => {
+      // The second guard, and NOT redundant: buildRows treats a null owner as
+      // corpus-wide, so any future widening of the query above would silently
+      // publish private material. The mapper refuses to emit an unscoped chunk
+      // for anything that is not public, whatever the query hands it.
+      const isPublic = r.visibility === 'public';
+      if (!isPublic && !r.owner_builder_id) return [];
+      return buildRows({
+        sourceRef: `speciality_doc:${r.id}`,
+        title: `${r.speciality_name} · ${r.title}`,
+        body: r.body_md,
+        ownerBuilderId: isPublic ? null : r.owner_builder_id,
+      });
+    } },
   // Per-builder memory → OWNER-SCOPED + scrubbed.
   { name: 'builder_memory', query: `SELECT builder_id, path, content FROM builder_memory`,
     map: (r) => buildRows({ sourceRef: `memory:${r.builder_id}:${r.path}`, title: r.path, body: r.content, ownerBuilderId: r.builder_id, scrub: true }) },

package/src/bongos/routes/me.js

@@ -174,6 +174,11 @@ module.exports = function buildMeRouter() {
     // present in prod; degrades to a null state row (shapeForApi synthesizes the
     // "nothing cleared" view) when the module is off.
     const onboarding = seams.resolveOptional('onboarding');
+    // task 1003855: role SUB-SPECIALITIES. A speciality carries a contract that is
+    // injected exactly like the interaction profile beside it — same port pattern,
+    // same GET /me -> Conductor path, deliberately not a second mechanism.
+    // default-on, so present in prod; null when the module is off.
+    const specialities = seams.resolveOptional('specialities');
     const [
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
@@ -452,6 +457,18 @@ module.exports = function buildMeRouter() {
       // session-start injection + /settings UI read this; describeInteraction is
       // the SSOT (builder-settings port). null when the prefs module is off.
       interaction: settings && settings.describeInteraction ? settings.describeInteraction(behaviorPrefs) : null,
+      // task 1003855: the builder's ACTIVE specialities, one per craft at most
+      // (the speciality_adoptions partial unique index enforces that). Each entry
+      // carries its own injectable contract; the Conductor picks the one matching
+      // the craft of the claim in hand rather than injecting all of them, because
+      // an artist's expert contract in an engineering session is noise at best.
+      specialities: await (async () => {
+        // Resolved through the port, never a direct require: the core must keep
+        // working with the module off, and [] reads as "no specialities", which
+        // is exactly what a session with the module disabled should see.
+        if (!specialities || typeof specialities.describeActiveFor !== 'function') return [];
+        try { return await specialities.describeActiveFor(builder.id); } catch { return []; }
+      })(),
       // task 2011: the resolved subagent model allocation (main + subagent tiers),
       // builder override → instance default (branding.models) → code default. The
       // agent consults `effective` when spawning subagents; §2 links here.

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.811'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.812'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/module_loader.mjs

@@ -276,7 +276,7 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // That is precisely how the agents regression reached an open PR (task 1002485).
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'dev-box', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'public-landing', 'security', 'sessions', 'status-ui', 'ui-design']);
+  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'dev-box', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'onboarding', 'platform-identity', 'provisioning', 'public-landing', 'security', 'sessions', 'specialities', 'status-ui', 'ui-design']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();

package/tests/own_scope_guard.mjs

@@ -84,6 +84,16 @@ const OWN_SCOPED_SURFACES = [
     why: "the caller's OWN auth sessions — list, revoke one, sign out everywhere (task 1003341, ADR 0206). Every statement carries builder_id = req.builder.id, so a session id belonging to somebody else matches no row. Kept OUT of routes/auth.js precisely so this whole file can be held to the own-scope rule: the admin cross-builder pair next door takes its target from the body, which is what makes it admin.",
     crossOwner: [],
   },
+  {
+    file: 'modules/specialities/routes/specialities.js',
+    why: "role sub-specialities (task 1003855, ADR 0296). The own-scoped route here is GET /me/specialities — the CALLER's own adoptions, taken from req.builder.id with nothing read off the request. The rest of the router is /specialities/* rather than /me/*, and those are ownership-checked per row against req.builder.id after re-reading the speciality server-side, never from a client-supplied owner id.",
+    minOwnScoped: 1,
+    // No cross-owner exemption: this guard classifies a route as cross-owner when a
+    // PATH PARAM names a builder. POST /projects/:projectId/specialities names a
+    // PROJECT, not a builder, and touches no builder record — so it is own-scoped by
+    // this guard's definition, and an exemption here would be a stale widening.
+    crossOwner: [],
+  },
   {
     file: 'modules/builder-settings/routes/settings.js',
     why: 'the per-builder preference domain (wandering, skill, sound, render, model-allocation, display name) carved out of /me — read and write, all keyed on req.builder.id.',

package/tests/specialities.mjs

@@ -0,0 +1,214 @@
+// tests/specialities.mjs — the rules behind role sub-specialities (task 1003855).
+//
+// The domain is pure on purpose, so every rule here is asserted without a
+// database. The NEGATIVE cases are the load-bearing ones: a validator that
+// returned {ok:true} unconditionally would pass every positive assertion in this
+// file, so each rule gets an input it must REJECT.
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const S = require(path.join(ROOT, 'modules', 'specialities', 'specialities.js'));
+
+const DISCIPLINES = ['engineer', 'ideator', 'artist', 'ui'];
+const draft = (over = {}) => ({
+  name: 'Economics',
+  discipline: 'ideator',
+  owner_kind: 'builder',
+  owner_builder_id: '1000025',
+  ...over,
+});
+
+// ---------- slug ----------
+test('slugify makes a human name addressable, and strips accents rather than dropping them', () => {
+  assert.equal(S.slugify('Economics'), 'economics');
+  assert.equal(S.slugify('  Behavioural   Economics  '), 'behavioural-economics');
+  assert.equal(S.slugify('Éconómics'), 'economics');
+  assert.equal(S.slugify('C++ & Rust'), 'c-rust');
+});
+
+test('a name that slugifies to nothing is REJECTED, not silently given an empty slug', () => {
+  // Two unsluggable names on one owner would both slug to '' and the second
+  // would fail as a duplicate — a confusing error about the wrong thing.
+  assert.equal(S.slugify('!!!'), '');
+  const r = S.validateDraft(draft({ name: '!!!' }), { disciplines: DISCIPLINES });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'name' && e.code === 'unsluggable'));
+});
+
+// ---------- validation ----------
+test('a well-formed draft passes', () => {
+  assert.deepEqual(S.validateDraft(draft(), { disciplines: DISCIPLINES }), { ok: true, errors: [] });
+});
+
+test('the discipline must be one the instance actually has', () => {
+  const r = S.validateDraft(draft({ discipline: 'wizard' }), { disciplines: DISCIPLINES });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'discipline' && e.code === 'unknown'));
+});
+
+test('a module-contributed craft is legal — the list is passed in, never hardcoded', () => {
+  // `ui` comes from a module (ADR 0272). Hardcoding the core three would reject it.
+  assert.equal(S.validateDraft(draft({ discipline: 'ui' }), { disciplines: DISCIPLINES }).ok, true);
+});
+
+test('ownership must be exactly one of builder/project, matching the DB CHECK', () => {
+  assert.equal(S.validateDraft(draft({ owner_kind: 'nobody' }), { disciplines: DISCIPLINES }).ok, false);
+  const missing = S.validateDraft(draft({ owner_kind: 'project', owner_builder_id: null }), { disciplines: DISCIPLINES });
+  assert.equal(missing.ok, false);
+  assert.ok(missing.errors.some((e) => e.field === 'owner_project_id' && e.code === 'required'));
+});
+
+test('private + sellable is refused — there is nobody it could be sold to', () => {
+  const r = S.validateDraft(draft({ sellable: true, visibility: 'private' }), { disciplines: DISCIPLINES });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'sellable' && e.code === 'needs_visibility'));
+  // ...and it is allowed the moment it is actually visible to someone.
+  assert.equal(S.validateDraft(draft({ sellable: true, visibility: 'public' }), { disciplines: DISCIPLINES }).ok, true);
+});
+
+test('the injected contract is length-bounded — it is a standing cost in every session', () => {
+  const r = S.validateDraft(draft({ contract_md: 'x'.repeat(S.LIMITS.CONTRACT + 1) }), { disciplines: DISCIPLINES });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'contract_md' && e.code === 'too_long'));
+});
+
+test('a BUILDER-owned speciality may not claim "project" visibility', () => {
+  // It names no project to resolve membership against, so canAdopt treats it as
+  // private-to-owner forever — the author believes they shared something they
+  // did not. Refused at validation rather than accepted and quietly inert.
+  const r = S.validateDraft(draft({ visibility: 'project' }), { disciplines: DISCIPLINES });
+  assert.equal(r.ok, false);
+  assert.ok(r.errors.some((e) => e.field === 'visibility' && e.code === 'project_needs_project_owner'));
+  // A PROJECT-owned one is exactly what that visibility is for.
+  const proj = S.validateDraft(
+    draft({ visibility: 'project', owner_kind: 'project', owner_builder_id: null, owner_project_id: 'p1' }),
+    { disciplines: DISCIPLINES },
+  );
+  assert.equal(proj.ok, true);
+});
+
+// ---------- who may adopt (ruling 3) ----------
+const OWNER = '1000025';
+const OTHER = '1000099';
+const mine = (over = {}) => ({ owner_kind: 'builder', owner_builder_id: OWNER, visibility: 'private', ...over });
+const proj = (over = {}) => ({ owner_kind: 'project', owner_project_id: 'p1', visibility: 'project', ...over });
+
+test('the owner may always adopt their own speciality, even while it is private', () => {
+  assert.equal(S.canAdopt(mine(), { builderId: OWNER, projectIds: [] }), true);
+});
+
+test('private is private — a stranger may not adopt it', () => {
+  assert.equal(S.canAdopt(mine(), { builderId: OTHER, projectIds: [] }), false);
+});
+
+test('public is adoptable by anyone on the instance', () => {
+  assert.equal(S.canAdopt(mine({ visibility: 'public' }), { builderId: OTHER, projectIds: [] }), true);
+});
+
+test('project visibility reaches that projectMEMBERS only', () => {
+  assert.equal(S.canAdopt(proj(), { builderId: OTHER, projectIds: ['p1'] }), true);
+  assert.equal(S.canAdopt(proj(), { builderId: OTHER, projectIds: ['p2'] }), false);
+  assert.equal(S.canAdopt(proj(), { builderId: OTHER, projectIds: [] }), false);
+});
+
+test('a BUILDER-owned speciality set to "project" does not degrade to public', () => {
+  // There is no project on the row to resolve membership against. The dangerous
+  // reading is "project ~ shared ~ let them in"; assert the safe one.
+  const orphan = mine({ visibility: 'project' });
+  assert.equal(S.canAdopt(orphan, { builderId: OTHER, projectIds: ['p1'] }), false);
+  assert.equal(S.canAdopt(orphan, { builderId: OWNER, projectIds: [] }), true, 'its owner still reaches it');
+});
+
+test('canAdopt refuses rather than throws on missing inputs', () => {
+  assert.equal(S.canAdopt(null, { builderId: OWNER }), false);
+  assert.equal(S.canAdopt(mine(), null), false);
+});
+
+// ---------- the injected fragment ----------
+const active = { id: '7', slug: 'economics', name: 'Economics', discipline: 'ideator', summary: 'Markets and incentives.', contract_md: 'Argue from mechanism, not vibes.' };
+
+test('no active speciality injects nothing at all', () => {
+  assert.equal(S.describeForApi(null), null);
+});
+
+test('the contract carries the name, the craft and the owner terms', () => {
+  const d = S.describeForApi(active, {});
+  assert.equal(d.inject, true);
+  assert.match(d.contract, /Economics/);
+  assert.match(d.contract, /under ideator/);
+  assert.match(d.contract, /Argue from mechanism/);
+  assert.equal(d.speciality_id, '7');
+});
+
+test('the knowledge corpus is INVENTORIED, never inlined', () => {
+  // A document can be 100k chars; inlining would blow the session's context and
+  // is the obvious wrong implementation, so pin the right one.
+  const d = S.describeForApi(active, { documentCount: 3, learningCount: 2 });
+  assert.match(d.contract, /3 document\(s\)/);
+  assert.match(d.contract, /2 learning\(s\)/);
+  assert.match(d.contract, /indexed, not inlined/);
+  assert.match(d.contract, /\/recall/, 'it tells the agent how to reach the material');
+});
+
+test('an untrained speciality makes no claim about knowing anything', () => {
+  const d = S.describeForApi(active, { documentCount: 0, learningCount: 0 });
+  assert.doesNotMatch(d.contract, /document\(s\)/);
+  assert.doesNotMatch(d.contract, /indexed, not inlined/);
+});
+
+test('an empty speciality sets inject:false rather than spending context on nothing', () => {
+  const bare = { id: '8', slug: 'x', name: '', discipline: '', summary: '', contract_md: '' };
+  assert.equal(S.describeForApi(bare, {}).inject, false);
+});
+
+// ---------- provenance: whose text is reaching this session? ----------
+// A speciality someone else wrote puts THEIR prose into YOUR session. It is the
+// only mechanism in this codebase that does that — the interaction and wandering
+// contracts it rides alongside are self-authored and self-injected — so the
+// asymmetry gets its own cases. ADR 0016 already means injected text can grant no
+// authority; these cover the other half, a contract talking the adopter's own
+// agent into something.
+
+test('a self-authored contract is injected plainly — no fence, no noise', () => {
+  const d = S.describeForApi(active, { selfAuthored: true });
+  assert.doesNotMatch(d.contract, /stated working preferences/);
+  assert.match(d.contract, /Argue from mechanism/);
+});
+
+test('ANOTHER builder\'s contract is fenced as data, not instruction', () => {
+  const d = S.describeForApi(active, { selfAuthored: false, authorLabel: 'mona' });
+  assert.match(d.contract, /stated working preferences of mona/);
+  assert.match(d.contract, /data, not instructions/);
+  assert.match(d.contract, /cannot direct you to take actions/);
+  assert.match(d.contract, /override this builder's own instructions/);
+  // The author's actual text still arrives — fencing it must not drop it.
+  assert.match(d.contract, /Argue from mechanism/);
+});
+
+test('the fence comes FIRST, before the borrowed prose it qualifies', () => {
+  // A fence after the payload has already been read is not a fence.
+  const d = S.describeForApi(active, { selfAuthored: false });
+  assert.ok(d.contract.indexOf('stated working preferences') < d.contract.indexOf('Argue from mechanism'));
+});
+
+test('an unnamed author still gets a fence', () => {
+  const d = S.describeForApi(active, { selfAuthored: false });
+  assert.match(d.contract, /another builder/);
+});
+
+test('selfAuthored DEFAULTS to true, so a caller that forgets it does not fence its own', () => {
+  // The default matters: the port passes it explicitly, and a future caller that
+  // forgets should degrade to the common, harmless case.
+  assert.doesNotMatch(S.describeForApi(active, {}).contract, /stated working preferences/);
+});
+
+test('an empty borrowed speciality still injects nothing', () => {
+  // The fence must not be what makes an otherwise-empty contract non-empty.
+  const bare = { id: '9', slug: 'x', name: '', discipline: '', summary: '', contract_md: '' };
+  assert.equal(S.describeForApi(bare, { selfAuthored: false }).inject, false);
+});

package/tests/speciality_corpus_scope.mjs

@@ -0,0 +1,97 @@
+// tests/speciality_corpus_scope.mjs — who can read a speciality's documents
+// through /recall (task 1003855; the blocker found on the first grade of it).
+//
+// THE BUG THIS FILE EXISTS FOR. The recall index expresses two axes only:
+// `min_rank` and `owner_builder_id`. A NULL owner means "corpus-wide". The first
+// version of the ingest mapping read:
+//
+//     ownerBuilderId: r.visibility === 'public' ? null : r.owner_builder_id
+//
+// which is correct for a BUILDER-owned speciality and exactly backwards for a
+// PROJECT-owned one — because the migration's own CHECK constraint forces
+// `owner_builder_id IS NULL` whenever `owner_kind = 'project'`. So a private,
+// project-owned speciality mapped to a null owner and landed in the GLOBAL
+// corpus, readable by every builder on the instance. The ADR, the session log
+// and the module's CLAUDE.md all claimed the opposite — that scoping "errs
+// toward under-sharing" — so the documentation actively vouched for the leak.
+//
+// Every case below is about who can READ, which is why they are worth a file of
+// their own rather than a paragraph in the ingester.
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { SOURCES } = require(path.join(ROOT, 'scripts', 'gds', 'search-ingest-db.js'));
+
+const source = SOURCES.find((s) => s.name === 'specialities_documents');
+
+// A row as the ingester's own query returns it. owner_builder_id is NULL for a
+// project-owned speciality — that is the migration's CHECK, not an accident.
+const row = (over = {}) => ({
+  id: 1,
+  title: 'Pricing a swap',
+  body_md: 'Discount the floating leg.',
+  speciality_name: 'Economics',
+  visibility: 'private',
+  owner_builder_id: '1000025',
+  ...over,
+});
+const builderOwned = (visibility) => row({ visibility });
+const projectOwned = (visibility) => row({ visibility, owner_builder_id: null });
+
+// A chunk with a null owner is corpus-wide. That single fact is what every
+// assertion below turns on, so it is named once here.
+const ownersOf = (r) => source.map(r).map((c) => c.owner_builder_id);
+
+test('the speciality-documents source is registered at all', () => {
+  assert.ok(source, 'without it the injected contract\'s "search it with /recall" is a lie');
+});
+
+test('a PUBLIC speciality is corpus-wide — that is the point of publishing one', () => {
+  assert.deepEqual(ownersOf(builderOwned('public')), [null]);
+});
+
+test('a private builder-owned speciality is scoped to its owner', () => {
+  assert.deepEqual(ownersOf(builderOwned('private')), ['1000025']);
+});
+
+test('a project-visible builder-owned speciality is still scoped to its owner', () => {
+  // `project` on a builder-owned row resolves to nobody (there is no project on
+  // the row), so canAdopt already treats it as owner-only. The index must agree.
+  assert.deepEqual(ownersOf(builderOwned('project')), ['1000025']);
+});
+
+// ---- the blocker ----
+test('a PRIVATE project-owned speciality does NOT land in the global corpus', () => {
+  // owner_builder_id is NULL here by the migration's CHECK. Mapping that straight
+  // through produced a null owner — corpus-wide — and leaked it to everyone.
+  const chunks = source.map(projectOwned('private'));
+  assert.deepEqual(chunks, [], 'a document nobody outside the project may read must not be indexed at all');
+});
+
+test('a PROJECT-visible project-owned speciality does NOT land in the global corpus', () => {
+  const chunks = source.map(projectOwned('project'));
+  assert.deepEqual(chunks, [], 'the index cannot express "these builders", so it must index nothing rather than everything');
+});
+
+test('a PUBLIC project-owned speciality is corpus-wide, which is the one case that is safe', () => {
+  assert.deepEqual(ownersOf(projectOwned('public')), [null]);
+});
+
+test('no chunk is ever emitted with a null owner unless the speciality is public', () => {
+  // The invariant behind all of the above, asserted directly so a future mapping
+  // change cannot satisfy the cases above by accident while breaking the rule.
+  for (const v of ['private', 'project', 'public']) {
+    for (const r of [builderOwned(v), projectOwned(v)]) {
+      for (const chunk of source.map(r)) {
+        if (chunk.owner_builder_id === null) {
+          assert.equal(r.visibility, 'public', `a corpus-wide chunk escaped for visibility=${v}`);
+        }
+      }
+    }
+  }
+});

package/tests/speciality_db_shape.mjs

@@ -0,0 +1,124 @@
+// tests/speciality_db_shape.mjs — the SQL behind role sub-specialities, driven
+// through the `executor` seam without a database (task 1003855).
+//
+// WHY THIS FILE EXISTS. db.js's own header says the seam is there "so the
+// route-level tests can drive these with a fake and assert the SQL shape without
+// a database, which matters here because the adoption path has a uniqueness rule
+// that is easy to get wrong and expensive to discover in production."
+//
+// Nothing used it. A seam nobody drives is a claim, not a test — and the first
+// grade of this task called that out as a major finding. These are the cases the
+// header was promising.
+//
+// The adoption rule is the load-bearing one: `speciality_adoptions` carries a
+// partial unique index on (builder_id, discipline) WHERE active, so adopting a
+// second speciality in a craft you already work in MUST deactivate the first in
+// the same breath or the insert violates the index.
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const db = require(path.join(ROOT, 'modules', 'specialities', 'db.js'));
+
+// A fake executor: records every (sql, params) pair and answers from a queue.
+function fake(results = []) {
+  const calls = [];
+  const queue = [...results];
+  const exec = async (text, params) => {
+    calls.push({ sql: text.replace(/\s+/g, ' ').trim(), params });
+    return queue.shift() || { rows: [], rowCount: 0 };
+  };
+  exec.calls = calls;
+  return exec;
+}
+
+test('adopt DEACTIVATES the craft before inserting — the unique index demands it', async () => {
+  const q = fake([{ rows: [], rowCount: 1 }, { rows: [{ builder_id: '1', speciality_id: '7' }], rowCount: 1 }]);
+  await db.adopt({ builderId: '1', specialityId: '7', discipline: 'ideator' }, q);
+
+  assert.equal(q.calls.length, 2, 'exactly two statements: the deactivate, then the insert');
+  const [first, second] = q.calls;
+  assert.match(first.sql, /UPDATE specialities_adoptions SET active = FALSE/);
+  assert.match(first.sql, /builder_id = \$1 AND discipline = \$2 AND active/);
+  assert.deepEqual(first.params, ['1', 'ideator'], 'scoped to THIS builder and THIS craft, not all of either');
+  assert.match(second.sql, /INSERT INTO specialities_adoptions/);
+  // The order is the whole point: insert-then-deactivate would hit the index.
+  assert.ok(q.calls.indexOf(first) < q.calls.indexOf(second));
+});
+
+test('adopt carries the craft from the caller, and re-adopting reactivates rather than duplicating', async () => {
+  const q = fake([{ rows: [], rowCount: 0 }, { rows: [{}], rowCount: 1 }]);
+  await db.adopt({ builderId: '1', specialityId: '7', discipline: 'artist' }, q);
+  const insert = q.calls[1];
+  assert.deepEqual(insert.params, ['1', '7', 'artist']);
+  assert.match(insert.sql, /ON CONFLICT \(builder_id, speciality_id\) DO UPDATE SET active = TRUE/);
+});
+
+test('the injected contract is read with the contract text itself', async () => {
+  // It once was not: listAdoptions omitted contract_md, so the session got the
+  // name and summary and silently lost the expert's own terms.
+  const q = fake([{ rows: [], rowCount: 0 }]);
+  await db.listAdoptions('1', q);
+  assert.match(q.calls[0].sql, /s\.contract_md/);
+});
+
+test('activeForCraft reads ONE craft for ONE builder, and only an active row', async () => {
+  const q = fake([{ rows: [{ id: '7' }], rowCount: 1 }]);
+  await db.activeForCraft('1', 'ideator', q);
+  assert.deepEqual(q.calls[0].params, ['1', 'ideator']);
+  assert.match(q.calls[0].sql, /a\.active/);
+});
+
+test('a document is idempotent on its content hash, not merely inserted twice', async () => {
+  const q = fake([{ rows: [], rowCount: 0 }]);
+  const out = await db.addDocument({ speciality_id: '7', title: 't', body_md: 'b', content_sha: 'abc' }, q);
+  assert.match(q.calls[0].sql, /ON CONFLICT \(speciality_id, content_sha\) DO NOTHING/);
+  assert.equal(out, null, 'a conflict returns null so the route can say "already trained" instead of claiming a create');
+});
+
+test('the discipline is NOT updatable — moving a craft would re-scope every adopter', async () => {
+  assert.ok(!db.UPDATABLE.includes('discipline'));
+  const q = fake([{ rows: [{ id: '7' }], rowCount: 1 }]);
+  await db.updateSpeciality('7', { discipline: 'artist', name: 'New' }, q);
+  assert.doesNotMatch(q.calls[0].sql, /discipline =/, 'a discipline in the patch must not reach the SQL');
+  assert.match(q.calls[0].sql, /name = \$1/);
+});
+
+test('an empty patch does not issue an UPDATE at all', async () => {
+  const q = fake([{ rows: [{ id: '7' }], rowCount: 1 }]);
+  await db.updateSpeciality('7', {}, q);
+  assert.doesNotMatch(q.calls[0].sql, /^UPDATE/, 'it falls through to a read rather than writing nothing');
+});
+
+test('the catalogue read never returns another builder\'s private row', async () => {
+  const q = fake([{ rows: [], rowCount: 0 }]);
+  await db.listVisibleTo({ builderId: '1', projectIds: ['p1'] }, q);
+  const sql = q.calls[0].sql;
+  assert.match(sql, /visibility = 'public'/);
+  assert.match(sql, /owner_builder_id = \$1/);
+  assert.match(sql, /owner_project_id = ANY\(\$2\)/);
+  // The dangerous shape is a bare SELECT with the filter applied in JS.
+  assert.match(sql, /WHERE/);
+});
+
+test('countTraining counts both halves of training in one round trip', async () => {
+  const q = fake([{ rows: [{ documents: '3', learnings: '2' }], rowCount: 1 }]);
+  const out = await db.countTraining('7', q);
+  assert.deepEqual(out, { documentCount: 3, learningCount: 2 }, 'counts come back as numbers, not strings');
+  assert.equal(q.calls.length, 1);
+});
+
+test('taskDiscipline reads the CORE tasks table by id', async () => {
+  const q = fake([{ rows: [{ discipline: 'engineer' }], rowCount: 1 }]);
+  assert.equal(await db.taskDiscipline('1234', q), 'engineer');
+  assert.deepEqual(q.calls[0].params, ['1234']);
+});
+
+test('taskDiscipline returns null rather than throwing when the task is gone', async () => {
+  const q = fake([{ rows: [], rowCount: 0 }]);
+  assert.equal(await db.taskDiscipline('nope', q), null);
+});