@bongos/core 1.19.811 → 1.19.813

package/modules/lifecycle/routes/done-when.js

@@ -130,40 +130,58 @@ module.exports = function buildDoneWhenRouter() {
       goal_id: { type: 'integer', min: 1 },
       sort_order: { type: 'integer', min: 0 },
     })) return;
-    const version = await db.getVersion(versionId);
-    if (!version) return res.fail('version_not_found', { status: 404, message: `No version '${versionId}'.` });
     // bad_goal_id now means exactly what it says: the goal is absent or belongs
     // to another version. (The unauthorized case rendered through this same
     // helper until task 1002614 — see the mask note in authorizeCriterionCreate.)
     const badGoalId = () => res.fail('bad_goal_id', { status: 400, message: `goal_id ${req.body.goal_id} does not exist on version '${versionId}'.` });
-    // A goal_id, if given, must exist AND belong to this version.
-    let goal = null;
-    if (req.body.goal_id != null) {
-      goal = await db.getGoal(req.body.goal_id);
-      if (!goal || String(goal.version_id) !== String(versionId)) return badGoalId();
-    }
-    // ADR 0154: the authority wall. Checked AFTER the goal's version linkage so a
-    // bad ref is still the clearer 400. Membership is only read when a goal was
-    // named and the caller isn't an Archon — a primary-key hit on
-    // goal_members (goal_id, builder_id) (migration 160), on a low-frequency route.
-    const actorMembership = (goal && req.builder.rank !== 'archon')
-      ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id })
-      : null;
-    const decision = authorizeCriterionCreate({
-      goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
-    });
-    if (!decision.ok) {
-      return res.status(decision.status).json(decision.body);
-    }
     try {
-      const criterion = await db.createCriterion({
-        versionId,
-        criterionId: req.body.criterion_id,
-        criterionMd: req.body.criterion_md,
-        goalId: req.body.goal_id ?? null,
-        sortOrder: req.body.sort_order ?? null,
-      });
-      res.status(201).json({ ok: true, criterion });
+      // RESOLVE, DECIDE and WRITE in ONE transaction, with the goal row LOCKED
+      // (task 1003840). Before this, the three facts the decision rests on — the
+      // version's status, the goal's owner/version linkage, the actor's
+      // membership — were read on the pool, and the INSERT landed afterwards on
+      // another connection. Between the two, the goal could be transferred or
+      // closed, the membership revoked, or the version frozen, and the write
+      // would land on authority that no longer held.
+      //
+      // The LOCK is the part that closes it. A bare transaction around the same
+      // sequence would still read the stale rows; the lock makes a concurrent
+      // transfer wait behind this one instead of racing it.
+      const outcome = await api.withTx(async (client) => {
+        const version = await db.getVersion(versionId, { client, forUpdate: true });
+        if (!version) return { fail: ['version_not_found', { status: 404, message: `No version '${versionId}'.` }] };
+        // A goal_id, if given, must exist AND belong to this version.
+        let goal = null;
+        if (req.body.goal_id != null) {
+          goal = await db.getGoal(req.body.goal_id, { client, forUpdate: true });
+          if (!goal || String(goal.version_id) !== String(versionId)) return { badGoal: true };
+        }
+        // ADR 0154: the authority wall. Checked AFTER the goal's version linkage so a
+        // bad ref is still the clearer 400. Membership is only read when a goal was
+        // named and the caller isn't an Archon — a primary-key hit on
+        // goal_members (goal_id, builder_id) (migration 160), on a low-frequency route.
+        const actorMembership = (goal && req.builder.rank !== 'archon')
+          ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id }, { client })
+          : null;
+        const decision = authorizeCriterionCreate({
+          goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+        });
+        if (!decision.ok) return { decision };
+        const criterion = await db.createCriterion({
+          versionId,
+          criterionId: req.body.criterion_id,
+          criterionMd: req.body.criterion_md,
+          goalId: req.body.goal_id ?? null,
+          sortOrder: req.body.sort_order ?? null,
+        }, { client });
+        return { criterion };
+      }, { pool: api.pool });
+      // Responses are sent AFTER the transaction resolves, never from inside it:
+      // a refusal must roll back rather than commit a half-written unit of work,
+      // and a 201 must not be promised before the COMMIT succeeds.
+      if (outcome.badGoal) return badGoalId();
+      if (outcome.fail) return res.fail(outcome.fail[0], outcome.fail[1]);
+      if (outcome.decision) return res.status(outcome.decision.status).json(outcome.decision.body);
+      res.status(201).json({ ok: true, criterion: outcome.criterion });
     } catch (err) {
       if (err && err.code === '23505') {
         return res.fail('criterion_exists', { status: 409, message: `criterion_id '${req.body.criterion_id}' already exists on version '${versionId}'.` });
@@ -294,64 +312,82 @@ module.exports = function buildDoneWhenRouter() {
     }
     const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
     if (id === null) return;
-    const existing = await doneWhen.getCriterion(id);
-    if (!existing) return res.fail('criterion_not_found', 404);
-    const version = await db.getVersion(existing.version_id);
-    // The ownership wall, resolved exactly as the CREATE route resolves it: the
-    // goal + version, and membership read only for a non-Archon. One closure, so
-    // both ends of a move are decided by the same code rather than a copy.
-    const authorizeFor = async (goal) => {
-      const actorMembership = (goal && req.builder.rank !== 'archon')
-        ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id })
-        : null;
-      return authorizeCriterionCreate({
-        goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
-      });
-    };
-    const currentGoal = existing.goal_id != null ? await db.getGoal(existing.goal_id) : null;
-    const authority = await authorizeFor(currentGoal);
-    if (!authority.ok) return res.status(authority.status).json(authority.body);
+    // Resolve, authorize and write inside ONE transaction, both goal rows LOCKED
+    // (task 1003840) — the same window the CREATE route above had, and the same
+    // cure. A move reads authority at BOTH ends, so both ends are locked: losing
+    // the race at either would move a criterion under authority that had just
+    // been revoked. Locking in a stable order (source before destination) is what
+    // keeps two concurrent moves from deadlocking on each other's rows.
+    const outcome = await api.withTx(async (client) => {
+      const existing = await doneWhen.getCriterion(id, { client });
+      if (!existing) return { fail: ['criterion_not_found', 404] };
+      const version = await db.getVersion(existing.version_id, { client, forUpdate: true });
+      // The ownership wall, resolved exactly as the CREATE route resolves it: the
+      // goal + version, and membership read only for a non-Archon. One closure, so
+      // both ends of a move are decided by the same code rather than a copy.
+      const authorizeFor = async (goal) => {
+        const actorMembership = (goal && req.builder.rank !== 'archon')
+          ? await db.getGoalMember({ goalId: goal.id, builderId: req.builder.id }, { client })
+          : null;
+        return authorizeCriterionCreate({
+          goal, version, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+        });
+      };
+      const targetGoalId = movingGoal ? (req.body.goal_id ?? null) : null;
+
+      // Lock BOTH ends in ASCENDING GOAL ID, never in the order the route happens
+      // to need them (task 1003840, round 2 — the first cut locked source then
+      // destination, which is call order, not a canonical one). Two opposite
+      // moves, 5→10 and 10→5, would then take the two locks in opposite orders
+      // and deadlock; Postgres aborts one rather than corrupting anything, but an
+      // avoidable abort is still an outage for whoever loses. A single agreed
+      // order means they queue instead.
+      const lockIds = [...new Set([
+        existing.goal_id != null ? Number(existing.goal_id) : null,
+        targetGoalId !== null ? Number(targetGoalId) : null,
+      ].filter((v) => v != null))].sort((a, b) => a - b);
+      const locked = new Map();
+      for (const gid of lockIds) locked.set(gid, await db.getGoal(gid, { client, forUpdate: true }));
+
+      const currentGoal = existing.goal_id != null ? locked.get(Number(existing.goal_id)) ?? null : null;
+      const authority = await authorizeFor(currentGoal);
+      if (!authority.ok) return { decision: authority };
 
-    const targetGoalId = movingGoal ? (req.body.goal_id ?? null) : null;
-    if (movingGoal) {
-      let targetGoal = null;
-      if (targetGoalId !== null) {
-        targetGoal = await db.getGoal(targetGoalId);
-        // Same refusal the CREATE route gives, for the same reason: a criterion may
-        // never cross versions, which would put it in one version's rollup and the
-        // other's goal at once.
-        if (!targetGoal || String(targetGoal.version_id) !== String(existing.version_id)) {
-          return res.fail('bad_goal_id', { status: 400, message: `goal_id ${targetGoalId} does not exist on version '${existing.version_id}'.` });
+      if (movingGoal) {
+        let targetGoal = null;
+        if (targetGoalId !== null) {
+          targetGoal = locked.get(Number(targetGoalId)) ?? null;
+          // Same refusal the CREATE route gives, for the same reason: a criterion may
+          // never cross versions, which would put it in one version's rollup and the
+          // other's goal at once.
+          if (!targetGoal || String(targetGoal.version_id) !== String(existing.version_id)) {
+            return { fail: ['bad_goal_id', { status: 400, message: `goal_id ${targetGoalId} does not exist on version '${existing.version_id}'.` }] };
+          }
         }
+        const destination = await authorizeFor(targetGoal);
+        if (!destination.ok) return { decision: destination };
       }
-      const destination = await authorizeFor(targetGoal);
-      if (!destination.ok) return res.status(destination.status).json(destination.body);
-    }
 
-    let criterion = existing;
-    let deltas = [];
-    let unchanged = false;
-    if (changingProse) {
-      const refusal = goalEdits.criterionProseRefusal(existing);
-      if (refusal) return res.fail(refusal.code, refusal.status, refusal.message ? { message: refusal.message } : undefined);
-      const result = await goalEdits.updateCriterionProse({ criterionId: id, criterionMd: req.body.criterion_md });
-      if (!result) return res.fail('criterion_not_found', 404);
-      await goalEdits.recordProseEdit('criterion', id, req, result.deltas);
-      criterion = result.criterion;
-      deltas = result.deltas;
-      unchanged = !!result.unchanged;
-    }
-    const achievedGoals = [];
-    const fromGoalId = existing.goal_id ?? null;
+      let criterion = existing;
+      let deltas = [];
+      let unchanged = false;
+      if (changingProse) {
+        const refusal = goalEdits.criterionProseRefusal(existing);
+        if (refusal) return { refusal };
+        const result = await goalEdits.updateCriterionProse({ criterionId: id, criterionMd: req.body.criterion_md }, { client });
+        if (!result) return { fail: ['criterion_not_found', 404] };
+        criterion = result.criterion;
+        deltas = result.deltas;
+        unchanged = !!result.unchanged;
+      }
+      const achievedGoals = [];
+      const fromGoalId = existing.goal_id ?? null;
     // A move to where it already is writes nothing at all — not the row, not the
     // audit, not a re-derive. Nothing about the world changed.
-    if (movingGoal && fromGoalId !== targetGoalId) {
-      const moved = await db.updateCriterionGoal(id, targetGoalId);
-      if (!moved) return res.fail('criterion_not_found', 404);
-      criterion = moved;
-      await goalEdits.recordCriterionGoalMove(
-        { criterionId: id, fromGoalId, toGoalId: targetGoalId }, req
-      );
+      if (movingGoal && fromGoalId !== targetGoalId) {
+        const moved = await db.updateCriterionGoal(id, targetGoalId, { client });
+        if (!moved) return { fail: ['criterion_not_found', 404] };
+        criterion = moved;
       // BOTH ENDS are re-derived, because a move changes what each of them still
       // needs. The destination is the obvious half — adopting an already-satisfied
       // criterion can be the thing that completes a goal. The SOURCE is the half
@@ -361,13 +397,41 @@ module.exports = function buildDoneWhenRouter() {
       // will ever close again — no later ship re-checks it, because no task under
       // it changed. achieveGoalIfComplete is conservative and idempotent (open
       // goals only, and it never un-achieves), so asking twice is two reads.
-      for (const goalId of [fromGoalId, targetGoalId]) {
-        if (goalId === null) continue;
-        const outcome = await db.achieveGoalIfComplete({ goalId });
-        if (outcome && outcome.achieved) achievedGoals.push(goalId);
+        for (const goalId of [fromGoalId, targetGoalId]) {
+          if (goalId === null) continue;
+          const achieved = await db.achieveGoalIfComplete({ goalId }, { client });
+          if (achieved && achieved.achieved) achievedGoals.push(goalId);
+        }
       }
+      return { criterion, deltas, unchanged, achievedGoals, moved: movingGoal && fromGoalId !== targetGoalId, fromGoalId, targetGoalId };
+    }, { pool: api.pool });
+
+    // Everything below runs only after COMMIT. The audit writes in particular
+    // belong out here: they are announcements of a change that happened, so
+    // recording one for a unit of work that rolled back would put an edit in the
+    // ledger that never landed — the ledger lying, which is the one thing it
+    // must not do.
+    if (outcome.fail) return res.fail(outcome.fail[0], outcome.fail[1]);
+    if (outcome.decision) return res.status(outcome.decision.status).json(outcome.decision.body);
+    if (outcome.refusal) {
+      const r = outcome.refusal;
+      return res.fail(r.code, r.status, r.message ? { message: r.message } : undefined);
     }
-    return res.json({ ok: true, criterion, deltas, unchanged, achieved_goals: achievedGoals });
+    if (outcome.deltas && outcome.deltas.length) {
+      await goalEdits.recordProseEdit('criterion', id, req, outcome.deltas);
+    }
+    if (outcome.moved) {
+      await goalEdits.recordCriterionGoalMove(
+        { criterionId: id, fromGoalId: outcome.fromGoalId, toGoalId: outcome.targetGoalId }, req
+      );
+    }
+    return res.json({
+      ok: true,
+      criterion: outcome.criterion,
+      deltas: outcome.deltas,
+      unchanged: outcome.unchanged,
+      achieved_goals: outcome.achievedGoals,
+    });
   }, { errorCode: 'criterion_update_failed' }));
 
   // Auth: flip a criterion back to unsatisfied (rare; for corrections).

package/modules/memory/learnings.js

@@ -13,7 +13,7 @@
 
 // Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): pool via the doorway.
 const crypto = require('crypto');
-const { pool } = require('../../src/module-api');
+const { pool, resolveOptional } = require('../../src/module-api');
 // ADR 0095 C4: <private>…</private>-fenced content is stripped at ingest so it
 // never lands in the learnings store (nor the recall index that reads it).
 const { stripPrivate } = require('./search-chunker');
@@ -111,6 +111,20 @@ async function createLearning({
     }
   }
 
+  // task 1003855: once the row lands, offer it to the builder's active speciality
+  // for that task's craft (training half (b)). Through the PORT, so this module
+  // never requires the specialities module and a disabled one simply means no
+  // link. Best-effort by construction: a capture must never fail over it.
+  const offerToSpeciality = async (row) => {
+    if (!row || !row.id) return;
+    try {
+      const sp = typeof resolveOptional === 'function' ? resolveOptional('specialities') : null;
+      if (sp && typeof sp.recordLearningForTask === 'function') {
+        await sp.recordLearningForTask({ learningId: row.id, builderId: row.captured_by, taskId: row.task_id });
+      }
+    } catch { /* never fail a capture over speciality bookkeeping */ }
+  };
+
   const { rows } = await pool.query(
     `INSERT INTO learnings (title, body_md, tags, related_files, captured_by,
                             source, source_ref, task_id)
@@ -131,7 +145,12 @@ async function createLearning({
       taskId,
     ]
   );
-  return rows[0] ?? null;
+  const created = rows[0] ?? null;
+  // Awaited, not fire-and-forget: an unawaited promise here would let the process
+  // exit mid-write in a CLI capture, and the helper already swallows its own
+  // failures, so awaiting costs one round trip and never fails the capture.
+  await offerToSpeciality(created);
+  return created;
 }
 
 // -------------------------------------------------------------------------

package/modules/provisioning/starter-bundles.js

@@ -59,6 +59,7 @@ const ALWAYS_ON_CORE = Object.freeze([
   'public-landing',
   'security',
   'sessions',
+  'specialities',
   'status-ui',
   'ui-design',
 ]);

package/modules/specialities/CLAUDE.md

@@ -0,0 +1,15 @@
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
+
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
+
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
+
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
+
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/specialities/db.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// modules/specialities/db.js — the queries behind role sub-specialities
+// (task 1003855; ADR 0296). The RULES live in specialities.js and are pure; this
+// file is only the reach into Postgres, through the published doorway
+// (src/module-api.js) per ADR 0091 §2 — never a core internal.
+//
+// EVERY FUNCTION TAKES AN OPTIONAL `executor`. That is the modules/lifecycle/
+// db-deps-criteria.js precedent: the seam lets the route-level tests 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.
+
+const { pool } = require('../../src/module-api');
+
+const exec = (executor) => executor || ((text, params) => pool.query(text, params));
+
+const COLUMNS = `id, slug, name, discipline, summary, contract_md,
+                 owner_kind, owner_builder_id, owner_project_id,
+                 visibility, sellable, created_by, created_at, updated_at`;
+
+async function createSpeciality(row, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `INSERT INTO specialities_catalog
+       (slug, name, discipline, summary, contract_md, owner_kind,
+        owner_builder_id, owner_project_id, visibility, sellable, created_by)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+     RETURNING ${COLUMNS}`,
+    [row.slug, row.name, row.discipline, row.summary || '', row.contract_md || '',
+      row.owner_kind, row.owner_builder_id || null, row.owner_project_id || null,
+      row.visibility || 'private', !!row.sellable, row.created_by || null],
+  );
+  return r.rows[0] || null;
+}
+
+async function getSpeciality(id, executor) {
+  const q = exec(executor);
+  const r = await q(`SELECT ${COLUMNS} FROM specialities_catalog WHERE id = $1`, [id]);
+  return r.rows[0] || null;
+}
+
+// The catalogue read. Deliberately returns rows the viewer may NOT adopt as well
+// as ones they may: the route filters with specialities.canAdopt so the rule
+// lives in one pure place. Widening this SQL without touching canAdopt is the
+// mistake this comment exists to prevent.
+async function listVisibleTo({ builderId, projectIds = [], discipline = null }, executor) {
+  const q = exec(executor);
+  const params = [builderId, projectIds.length ? projectIds : [null]];
+  let sql = `SELECT ${COLUMNS} FROM specialities_catalog
+             WHERE visibility = 'public'
+                OR (owner_kind = 'builder' AND owner_builder_id = $1)
+                OR (owner_kind = 'project' AND visibility = 'project' AND owner_project_id = ANY($2))`;
+  if (discipline) { params.push(discipline); sql += ` AND discipline = $${params.length}`; }
+  sql += ' ORDER BY name ASC';
+  const r = await q(sql, params);
+  return r.rows;
+}
+
+// A speciality's DISCIPLINE IS IMMUTABLE and is not in this list on purpose:
+// moving one between crafts would silently re-scope everyone who adopted it, and
+// the adoption rows carry a denormalised copy the migration relies on.
+const UPDATABLE = ['name', 'summary', 'contract_md', 'visibility', 'sellable'];
+
+async function updateSpeciality(id, patch, executor) {
+  const q = exec(executor);
+  const sets = [];
+  const params = [];
+  for (const f of UPDATABLE) {
+    if (patch[f] === undefined) continue;
+    params.push(patch[f]);
+    sets.push(`${f} = $${params.length}`);
+  }
+  if (!sets.length) return getSpeciality(id, executor);
+  params.push(id);
+  const r = await q(
+    `UPDATE specialities_catalog SET ${sets.join(', ')}, updated_at = now()
+     WHERE id = $${params.length} RETURNING ${COLUMNS}`,
+    params,
+  );
+  return r.rows[0] || null;
+}
+
+// ── training (a): documents the builder supplied ────────────────────────────
+// ON CONFLICT DO NOTHING against the (speciality_id, content_sha) index: adding
+// the same document twice is a no-op rather than a duplicate that would double
+// its weight in the corpus. Returns null when nothing was inserted, so the route
+// can answer 200-already-there instead of pretending it created something.
+async function addDocument(row, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `INSERT INTO specialities_documents (speciality_id, title, body_md, source, content_sha, added_by)
+     VALUES ($1,$2,$3,$4,$5,$6)
+     ON CONFLICT (speciality_id, content_sha) DO NOTHING
+     RETURNING id, speciality_id, title, source, content_sha, added_by, created_at`,
+    [row.speciality_id, row.title, row.body_md, row.source || 'paste', row.content_sha, row.added_by || null],
+  );
+  return r.rows[0] || null;
+}
+
+// Metadata only — the bodies are the corpus and can be large. A caller that wants
+// content asks for one document by id.
+async function listDocuments(specialityId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `SELECT id, speciality_id, title, source, content_sha, added_by, created_at,
+            length(body_md) AS body_chars
+       FROM specialities_documents WHERE speciality_id = $1 ORDER BY created_at DESC`,
+    [specialityId],
+  );
+  return r.rows;
+}
+
+async function getDocument(specialityId, docId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `SELECT id, speciality_id, title, body_md, source, content_sha, created_at
+       FROM specialities_documents WHERE speciality_id = $1 AND id = $2`,
+    [specialityId, docId],
+  );
+  return r.rows[0] || null;
+}
+
+async function deleteDocument(specialityId, docId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    'DELETE FROM specialities_documents WHERE speciality_id = $1 AND id = $2 RETURNING id',
+    [specialityId, docId],
+  );
+  return r.rowCount > 0;
+}
+
+// ── training (b): what sessions taught it ───────────────────────────────────
+async function linkLearning(specialityId, learningId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `INSERT INTO specialities_learnings (speciality_id, learning_id) VALUES ($1,$2)
+     ON CONFLICT (speciality_id, learning_id) DO NOTHING RETURNING learning_id`,
+    [specialityId, learningId],
+  );
+  return r.rowCount > 0;
+}
+
+async function countTraining(specialityId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `SELECT (SELECT count(*) FROM specialities_documents WHERE speciality_id = $1) AS documents,
+            (SELECT count(*) FROM specialities_learnings  WHERE speciality_id = $1) AS learnings`,
+    [specialityId],
+  );
+  const row = r.rows[0] || {};
+  return { documentCount: Number(row.documents || 0), learningCount: Number(row.learnings || 0) };
+}
+
+// ── adoption ────────────────────────────────────────────────────────────────
+// Switching craft speciality is DEACTIVATE-THEN-ACTIVATE inside one statement
+// pair, because the partial unique index (builder_id, discipline) WHERE active
+// would otherwise reject the second adoption. Both run on the same executor so a
+// caller may wrap them in a transaction.
+async function deactivateCraft(builderId, discipline, executor) {
+  const q = exec(executor);
+  await q(
+    'UPDATE specialities_adoptions SET active = FALSE WHERE builder_id = $1 AND discipline = $2 AND active',
+    [builderId, discipline],
+  );
+}
+
+async function adopt({ builderId, specialityId, discipline }, executor) {
+  const q = exec(executor);
+  await deactivateCraft(builderId, discipline, executor);
+  const r = await q(
+    `INSERT INTO specialities_adoptions (builder_id, speciality_id, discipline, active)
+     VALUES ($1,$2,$3,TRUE)
+     ON CONFLICT (builder_id, speciality_id)
+       DO UPDATE SET active = TRUE, discipline = EXCLUDED.discipline, adopted_at = now()
+     RETURNING builder_id, speciality_id, discipline, active, adopted_at`,
+    [builderId, specialityId, discipline],
+  );
+  return r.rows[0] || null;
+}
+
+async function abandon(builderId, specialityId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    'UPDATE specialities_adoptions SET active = FALSE WHERE builder_id = $1 AND speciality_id = $2 AND active RETURNING speciality_id',
+    [builderId, specialityId],
+  );
+  return r.rowCount > 0;
+}
+
+// The read the session injection path depends on: the builder's active
+// speciality for a craft, joined to the speciality itself.
+async function activeForCraft(builderId, discipline, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `SELECT s.id, s.slug, s.name, s.discipline, s.summary, s.contract_md
+       FROM specialities_adoptions a JOIN specialities_catalog s ON s.id = a.speciality_id
+      WHERE a.builder_id = $1 AND a.discipline = $2 AND a.active
+      LIMIT 1`,
+    [builderId, discipline],
+  );
+  return r.rows[0] || null;
+}
+
+async function listAdoptions(builderId, executor) {
+  const q = exec(executor);
+  const r = await q(
+    // contract_md is HERE because the session-injection port builds the injected
+    // fragment from this row — omitting it silently dropped the expert's own terms
+    // and left only the name and summary reaching the session.
+    `SELECT s.id, s.slug, s.name, s.discipline, s.summary, s.contract_md, a.active, a.adopted_at
+       FROM specialities_adoptions a JOIN specialities_catalog s ON s.id = a.speciality_id
+      WHERE a.builder_id = $1 ORDER BY a.adopted_at DESC`,
+    [builderId],
+  );
+  return r.rows;
+}
+
+// The craft of a task, used to decide WHICH speciality a learning belongs to.
+// `tasks` is a CORE table, read the same way builder-settings reads core
+// `builders` — this is not a reach into another module's own tables.
+async function taskDiscipline(taskId, executor) {
+  const q = exec(executor);
+  const r = await q('SELECT discipline FROM tasks WHERE id = $1', [taskId]);
+  return (r.rows[0] && r.rows[0].discipline) || null;
+}
+
+module.exports = {
+  UPDATABLE, taskDiscipline,
+  createSpeciality, getSpeciality, listVisibleTo, updateSpeciality,
+  addDocument, listDocuments, getDocument, deleteDocument,
+  linkLearning, countTraining,
+  adopt, abandon, deactivateCraft, activeForCraft, listAdoptions,
+};