@bongos/core 1.19.811 → 1.19.813

package/modules/specialities/migrations/specialities_001_specialities.sql

@@ -0,0 +1,143 @@
+-- specialities_001_specialities.sql — role sub-specialities: a named bundle of
+-- context, skills and an interaction contract that sits UNDER a craft
+-- (task 1003855, goal 1000095; ADR 0296).
+--
+-- WHAT A SPECIALITY IS, AND WHY IT IS DATA RATHER THAN CODE. The owner's framing
+-- is that specialities "are more or less MODULES" — but a builder authors one,
+-- so it cannot be an ADR 0083 code module without making every subject-matter
+-- expert ship a package. A speciality is therefore a ROW that layers over the
+-- three surfaces the platform already has: discipline-modes.json (craft ->
+-- playbook), behavior_prefs.interaction (the per-session interaction contract),
+-- and the ADR 0083 manifest (declared skills). The only genuinely new part is
+-- the knowledge bundle, which is why it gets its own table below.
+--
+-- OWNER RULING, 2026-09-17, recorded on the task. Training is TWO-FOLD: the
+-- builder supplies knowledge or documentation they created (specialities_documents)
+-- AND the speciality sharpens from session learning (specialities_learnings).
+-- Specialities are per-builder AND per-project. Each carries a sharing decision
+-- made by its owner, and an explicit "may be offered for sale" flag.
+--
+-- WHY `sellable` EXISTS WITH NO MARKETPLACE BEHIND IT. ADR 0107 records that
+-- there is no catalog or registry and explicitly rejected building one as
+-- premature; a marketplace is a deferred fork. The flag captures the owner's
+-- decision AT THE MOMENT THEY MAKE IT so the deferred marketplace reads a field
+-- that already has honest values in it, instead of asking every existing
+-- speciality owner to answer retroactively. It grants nothing and lists nowhere.
+
+-- ── the speciality itself ───────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS specialities_catalog (
+  id               BIGSERIAL PRIMARY KEY,
+  slug             TEXT        NOT NULL,
+  name             TEXT        NOT NULL,
+  -- The craft this sits under. NOT a foreign key: disciplines come from
+  -- discipline-modes.json plus module contributions (enabledDisciplines()), so
+  -- the legal set is computed at runtime and a DB constraint would freeze it.
+  discipline       TEXT        NOT NULL,
+  summary          TEXT        NOT NULL DEFAULT '',
+  -- The fragment injected into a session, exactly like behavior_prefs.interaction.
+  -- Kept as prose, not structured knobs: a speciality is an expert describing how
+  -- they want to be worked with, which is not enumerable up front.
+  contract_md      TEXT        NOT NULL DEFAULT '',
+
+  -- OWNERSHIP. Exactly one of builder/project owns a speciality (ruling 2).
+  owner_kind       TEXT        NOT NULL CHECK (owner_kind IN ('builder', 'project')),
+  owner_builder_id BIGINT      REFERENCES builders(id) ON DELETE CASCADE,
+  owner_project_id BIGINT,
+
+  -- SHARING (ruling 3): the owner's decision, never a platform default.
+  --   private → only the owner sees it
+  --   project → any member of the owning project may adopt it
+  --   public  → any builder on this instance may adopt it
+  visibility       TEXT        NOT NULL DEFAULT 'private'
+                     CHECK (visibility IN ('private', 'project', 'public')),
+  -- SALE (ruling 4): records the owner's intent. See the header — no storefront.
+  sellable         BOOLEAN     NOT NULL DEFAULT FALSE,
+
+  created_by       BIGINT      REFERENCES builders(id) ON DELETE SET NULL,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- The owner columns must agree with owner_kind, or a speciality could be owned
+  -- by nobody (invisible, unadoptable) or by both (whose sharing rule wins?).
+  CONSTRAINT specialities_catalog_owner_exactly_one CHECK (
+    (owner_kind = 'builder' AND owner_builder_id IS NOT NULL AND owner_project_id IS NULL) OR
+    (owner_kind = 'project' AND owner_project_id IS NOT NULL AND owner_builder_id IS NULL)
+  ),
+  -- A speciality may only be offered for sale if someone other than its owner
+  -- could ever see it. Enforced here rather than in the route because it is a
+  -- property of the row, and a private-but-sellable row is simply incoherent.
+  CONSTRAINT specialities_catalog_sellable_needs_visibility CHECK (
+    sellable = FALSE OR visibility <> 'private'
+  )
+);
+
+-- Slug is unique PER OWNER, not globally: two experts may both have an
+-- "economics" speciality, and a global unique would make the second one's
+-- authoring fail with a collision against a row they cannot even see.
+CREATE UNIQUE INDEX IF NOT EXISTS specialities_catalog_builder_slug_key
+  ON specialities_catalog (owner_builder_id, slug) WHERE owner_builder_id IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS specialities_catalog_project_slug_key
+  ON specialities_catalog (owner_project_id, slug) WHERE owner_project_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS specialities_catalog_discipline_idx ON specialities_catalog (discipline);
+-- The adoptable-catalogue read: "what may I adopt", which filters on visibility.
+CREATE INDEX IF NOT EXISTS specialities_catalog_visibility_idx ON specialities_catalog (visibility)
+  WHERE visibility <> 'private';
+
+-- ── training half (a): knowledge the builder supplied ───────────────────────
+-- Ruling 1a, and the part the original task did not consider at all. A document
+-- is the expert's own material; the speciality learns the subject from it.
+CREATE TABLE IF NOT EXISTS specialities_documents (
+  id             BIGSERIAL PRIMARY KEY,
+  speciality_id  BIGINT      NOT NULL REFERENCES specialities_catalog(id) ON DELETE CASCADE,
+  title          TEXT        NOT NULL,
+  -- Content is stored inline. These are documents a person wrote or pasted, not
+  -- uploads of arbitrary size; keeping them in-row means the search chunker and
+  -- every read go through one place with no blob store to provision.
+  body_md        TEXT        NOT NULL,
+  source         TEXT        NOT NULL DEFAULT 'paste',
+  content_sha    TEXT        NOT NULL,
+  added_by       BIGINT      REFERENCES builders(id) ON DELETE SET NULL,
+  created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+-- Re-adding the same document is idempotent rather than a silent duplicate that
+-- would double its weight in the corpus.
+CREATE UNIQUE INDEX IF NOT EXISTS specialities_documents_sha_key
+  ON specialities_documents (speciality_id, content_sha);
+
+-- ── training half (b): what the speciality learned from sessions ────────────
+-- Ruling 1b. This does NOT grow a parallel memory: a row points at an existing
+-- `learnings` row and says "this one belongs to this speciality", so capture,
+-- search and retention keep working exactly as they do today.
+CREATE TABLE IF NOT EXISTS specialities_learnings (
+  speciality_id BIGINT      NOT NULL REFERENCES specialities_catalog(id) ON DELETE CASCADE,
+  learning_id   BIGINT      NOT NULL,
+  captured_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (speciality_id, learning_id)
+);
+
+-- ── adoption: which speciality a builder is actually working in ─────────────
+CREATE TABLE IF NOT EXISTS specialities_adoptions (
+  builder_id    BIGINT      NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  speciality_id BIGINT      NOT NULL REFERENCES specialities_catalog(id) ON DELETE CASCADE,
+  -- THE CRAFT IS DENORMALISED ONTO THIS ROW ON PURPOSE. The rule is "at most one
+  -- ACTIVE speciality per builder per craft" — two contracts under one craft
+  -- would both be injected and could contradict each other, with nothing in the
+  -- session able to arbitrate. A partial unique index is the only way to enforce
+  -- that at the point of insert, and an index cannot reach through the FK to
+  -- specialities.discipline. So the craft is copied here and the unique index
+  -- below makes the rule real rather than merely documented.
+  --
+  -- Safe to copy because a speciality's discipline is IMMUTABLE: the update path
+  -- rejects a discipline change (moving a speciality between crafts would
+  -- silently re-scope everyone who adopted it). Pinned by a test.
+  discipline    TEXT        NOT NULL,
+  active        BOOLEAN     NOT NULL DEFAULT TRUE,
+  adopted_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, speciality_id)
+);
+-- The rule the comment above claims. Deactivating is how you switch, so an
+-- inactive row never blocks adopting a different speciality in the same craft.
+CREATE UNIQUE INDEX IF NOT EXISTS specialities_adoptions_one_active_per_craft
+  ON specialities_adoptions (builder_id, discipline) WHERE active;
+CREATE INDEX IF NOT EXISTS specialities_adoptions_builder_idx
+  ON specialities_adoptions (builder_id) WHERE active;

package/modules/specialities/module.json

@@ -0,0 +1,12 @@
+{
+  "key": "specialities",
+  "title": "Role sub-specialities (harnesses)",
+  "description": "Role SUB-SPECIALITIES — a named bundle of knowledge, skills and an interaction contract that sits UNDER a craft (task 1003855; ADR 0296). A craft says how you work (engineer / ideator / artist / ui); a speciality says what you work ON and how a subject-matter expert wants to be engaged inside it. Deliberately a thin layer over three surfaces that already exist — discipline-modes.json for craft->playbook, behavior_prefs.interaction for the per-session contract (a speciality contract rides that SAME GET /me -> Conductor path rather than adding a second one), and the ADR 0083 manifest for declared skills; the only new machinery is the knowledge bundle. Training is two-fold per the owner's 2026-09-17 ruling: documents the builder supplied, plus learnings captured from sessions worked in the speciality (pointing at existing `learnings` rows, never a second corpus). Owned per-builder OR per-project, each carrying its owner's sharing decision (private / project / public) and an explicit sellable flag — the flag records intent only, because ADR 0107 defers the marketplace and there is nothing to list on. default-on: a speciality is how an instance's expertise enters the platform, so it ships like the hall and the status page.",
+  "coreVersion": "^1.19.0",
+  "default": true,
+  "maintenance": { "status": "core-maintained" },
+  "migrations": true,
+  "contributes": { "routes": ["specialities"] },
+  "provides": ["specialities"],
+  "consumes": []
+}

package/modules/specialities/routes/specialities.js

@@ -0,0 +1,379 @@
+// modules/specialities/routes/specialities.js — the HTTP surface for role
+// sub-specialities (task 1003855; ADR 0296).
+//
+// SHAPE. Authoring and adoption are open to any builder: a speciality is how a
+// subject-matter expert's knowledge enters the platform, and gating that behind a
+// rank would mean only trusted builders could be experts. What IS gated is
+// touching someone else's — every write below re-reads the row and checks
+// ownership server-side rather than trusting an id from the client.
+//
+// THE RULES ARE NOT IN THIS FILE. Visibility, validation and the injected
+// contract live in ../specialities.js as pure functions, so they are unit-tested
+// without a database and cannot drift between the route and the session path.
+// A widening here that does not go through canAdopt is a bug.
+//
+// MODULE BOUNDARY: everything core arrives through the published doorway
+// (src/module-api.js); `../db` and `../specialities` are intra-module siblings.
+// Project membership belongs to platform-identity, which exposes no port for it,
+// so it is resolved through an OPTIONAL seam — present on a hub, absent
+// elsewhere, and absent means "no projects", never "all projects".
+
+'use strict';
+
+const express = require('express');
+const crypto = require('node:crypto');
+const api = require('../../../src/module-api');
+const S = require('../specialities');
+const db = require('../db');
+
+const { validateOrRespond, parseId, asyncHandler } = api;
+
+// Resolve the viewer's projects WITHOUT reaching into another module's tables.
+// resolveOptional returns undefined when nothing provides the port, which is the
+// common case (a non-hub instance), and the safe answer there is "no projects".
+async function viewerProjectIds(builder) {
+  try {
+    const port = api.resolveOptional && api.resolveOptional('project.membership');
+    if (!port || typeof port.projectIdsForBuilder !== 'function') return [];
+    const ids = await port.projectIdsForBuilder(builder.id);
+    return Array.isArray(ids) ? ids.map(String) : [];
+  } catch {
+    // A membership lookup that throws must not take the catalogue down with it —
+    // it degrades to "your own + public", which is a smaller answer, never a wider one.
+    return [];
+  }
+}
+
+const sha256 = (s) => crypto.createHash('sha256').update(String(s), 'utf8').digest('hex');
+
+// "Can this builder see this row at all?" — the same rule the catalogue uses,
+// reused so a 403 never leaks the existence of something a 404 would have hidden.
+async function visibleTo(speciality, builder) {
+  if (owns(speciality, builder)) return true;
+  const projectIds = await viewerProjectIds(builder);
+  return S.canAdopt(speciality, { builderId: builder.id, projectIds });
+}
+
+function owns(speciality, builder) {
+  return speciality.owner_kind === 'builder'
+    && String(speciality.owner_builder_id) === String(builder.id);
+}
+
+
+// THE KERNEL PORT. GET /me resolves 'specialities' and calls describeActiveFor;
+// that is the ENTIRE core-facing surface, and it is deliberately one read. The
+// core must keep working with this module off, so the caller treats an absent
+// port as "no specialities" rather than an error (src/bongos/routes/me.js).
+//
+// Registered here rather than in a module index because the router factory is the
+// one thing the loader is guaranteed to call for an enabled module
+// (mountModuleRoutes), which is the convention builder-settings and economy use.
+const port = {
+  // Every ACTIVE speciality this builder has, one per craft at most, each with
+  // its own injectable contract. Craft-scoped selection happens in the Conductor,
+  // which knows the craft of the claim in hand; this just reports them all.
+  async describeActiveFor(builderId) {
+    const rows = await db.listAdoptions(builderId);
+    const out = [];
+    for (const row of rows) {
+      if (!row.active) continue;
+      const training = await db.countTraining(row.id);
+      // Self-authored is the common case and stays unfenced; anything adopted from
+      // another builder or from a project carries its provenance into the session.
+      const full = await db.getSpeciality(row.id);
+      const selfAuthored = !!full && full.owner_kind === 'builder'
+        && String(full.owner_builder_id) === String(builderId);
+      const described = S.describeForApi(row, { ...training, selfAuthored });
+      if (described) out.push({ ...described, discipline: row.discipline, name: row.name });
+    }
+    return out;
+  },
+
+  // Training half (b): attach a learning captured in a session to the speciality
+  // it was learned in. Idempotent — learning-capture may retry.
+  async recordLearning(specialityId, learningId) {
+    return db.linkLearning(specialityId, learningId);
+  },
+
+  // The automatic half of (b), called by the memory module after a capture.
+  // Resolves the craft from the task, then the builder's ACTIVE speciality in
+  // that craft — so a learning lands in the speciality it was actually learned
+  // in, and in nothing when the builder was not working in one.
+  //
+  // Returns false rather than throwing on every miss: a capture must never fail
+  // because the speciality bookkeeping could not be done.
+  async recordLearningForTask({ learningId, builderId, taskId }) {
+    try {
+      if (!learningId || !builderId || !taskId) return false;
+      const discipline = await db.taskDiscipline(taskId);
+      if (!discipline) return false;
+      const active = await db.activeForCraft(builderId, discipline);
+      if (!active) return false;
+      return await db.linkLearning(active.id, learningId);
+    } catch {
+      return false;
+    }
+  },
+
+  // Used by the settings surface and by anything that wants the counts without
+  // pulling the corpus itself.
+  async trainingCounts(specialityId) {
+    return db.countTraining(specialityId);
+  },
+};
+
+module.exports = function buildSpecialitiesRouter() {
+  const router = express.Router();
+
+  // hasProvider-GUARDED, matching builder-settings/routes/settings.js: the factory
+  // runs both live AND every time a test rebuilds the router, and a port is
+  // single-provider — an unguarded register throws on the second build.
+  if (!api.hasProvider('specialities')) api.registerProvider('specialities', port);
+
+  // GET /specialities — the catalogue this builder may see. `?discipline=` narrows
+  // it to one craft, which is what the settings surface asks for.
+  router.get('/specialities', api.requireBuilder, asyncHandler('GET /specialities', async (req, res) => {
+    const builder = req.builder;
+    const projectIds = await viewerProjectIds(builder);
+    const rows = await db.listVisibleTo({
+      builderId: builder.id,
+      projectIds,
+      discipline: req.query.discipline || null,
+    });
+    // The SQL is the cheap filter; canAdopt is the ACTUAL rule. Running both means
+    // a loosened query cannot silently widen who may adopt what.
+    const viewer = { builderId: builder.id, projectIds };
+    res.json({
+      specialities: rows.map((s) => ({ ...s, adoptable: S.canAdopt(s, viewer), mine: owns(s, builder) })),
+    });
+  }));
+
+  // POST /specialities — author one for YOURSELF. The owner is req.builder and is
+  // never read from the body: a route whose path names no subject must act on the
+  // caller (tests/own_scope_guard.mjs). A PROJECT speciality names its project in
+  // the path instead — see POST /projects/:projectId/specialities below.
+  router.post('/specialities', api.requireBuilder, asyncHandler('POST /specialities', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      name: { required: true, type: 'string', maxLength: S.LIMITS.NAME, minLength: 1 },
+      discipline: { required: true, type: 'string', maxLength: 64 },
+      summary: { type: 'string', maxLength: S.LIMITS.SUMMARY },
+      contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
+      visibility: { type: 'string', maxLength: 16 },
+      sellable: { type: 'boolean' },
+    })) return;
+
+    const b = req.body || {};
+    const builder = req.builder;
+    const ownerKind = 'builder';
+
+    const draft = {
+      name: String(b.name).trim(),
+      discipline: b.discipline,
+      summary: b.summary || '',
+      contract_md: b.contract_md || '',
+      visibility: b.visibility || 'private',
+      sellable: !!b.sellable,
+      owner_kind: ownerKind,
+      owner_builder_id: builder.id,
+      owner_project_id: null,
+    };
+
+    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines() });
+    if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
+
+    draft.slug = S.slugify(draft.name);
+    draft.created_by = builder.id;
+    try {
+      const created = await db.createSpeciality(draft);
+      res.status(201).json({ speciality: created });
+    } catch (err) {
+      if (err && err.code === '23505') {
+        return res.fail('duplicate_slug', { status: 409, message: `You already have a speciality called "${draft.name}".` });
+      }
+      throw err;
+    }
+  }));
+
+  // POST /projects/:projectId/specialities — author one OWNED BY A PROJECT.
+  // The target is in the PATH, not the body, which is what makes it auditable:
+  // the gate below is membership of that same project, checked server-side.
+  router.post('/projects/:projectId/specialities', api.requireBuilder, asyncHandler('POST /projects/:projectId/specialities', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      name: { required: true, type: 'string', maxLength: S.LIMITS.NAME, minLength: 1 },
+      discipline: { required: true, type: 'string', maxLength: 64 },
+      summary: { type: 'string', maxLength: S.LIMITS.SUMMARY },
+      contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
+      visibility: { type: 'string', maxLength: 16 },
+      sellable: { type: 'boolean' },
+    })) return;
+
+    const projectId = String(req.params.projectId);
+    const projectIds = await viewerProjectIds(req.builder);
+    if (!projectIds.includes(projectId)) {
+      // Also the answer when no membership port is registered at all, which is
+      // the non-hub case: absent means NO projects, never all of them.
+      return res.fail('not_a_project_member', {
+        status: 403,
+        message: 'A project speciality can only be authored by a member of that project.',
+      });
+    }
+
+    const b = req.body || {};
+    const draft = {
+      name: String(b.name).trim(),
+      discipline: b.discipline,
+      summary: b.summary || '',
+      contract_md: b.contract_md || '',
+      visibility: b.visibility || 'private',
+      sellable: !!b.sellable,
+      owner_kind: 'project',
+      owner_builder_id: null,
+      owner_project_id: projectId,
+    };
+
+    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines() });
+    if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
+
+    draft.slug = S.slugify(draft.name);
+    draft.created_by = req.builder.id;
+    try {
+      res.status(201).json({ speciality: await db.createSpeciality(draft) });
+    } catch (err) {
+      if (err && err.code === '23505') {
+        return res.fail('duplicate_slug', { status: 409, message: `That project already has a speciality called "${draft.name}".` });
+      }
+      throw err;
+    }
+  }));
+
+  router.get('/specialities/:id', api.requireBuilder, asyncHandler('GET /specialities/:id', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    if (!s) return res.fail('not_found', 404);
+    const projectIds = await viewerProjectIds(req.builder);
+    const viewer = { builderId: req.builder.id, projectIds };
+    // A row you may neither adopt nor own is not yours to read: answering 404
+    // rather than 403 avoids confirming that a private speciality exists.
+    if (!(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    const training = await db.countTraining(id);
+    res.json({ speciality: { ...s, ...training, adoptable: S.canAdopt(s, viewer), mine: owns(s, req.builder) } });
+  }));
+
+  // PATCH — owner only. `discipline` is absent from db.UPDATABLE on purpose: see
+  // the note there, and the adoption rows that carry a denormalised copy.
+  router.patch('/specialities/:id', api.requireBuilder, asyncHandler('PATCH /specialities/:id', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      name: { type: 'string', maxLength: S.LIMITS.NAME, minLength: 1 },
+      summary: { type: 'string', maxLength: S.LIMITS.SUMMARY },
+      contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
+      visibility: { type: 'string', maxLength: 16 },
+      sellable: { type: 'boolean' },
+    })) return;
+
+    const s = await db.getSpeciality(id);
+    // 404, not 403, for a speciality this viewer cannot even see — a 403 here
+    // would confirm that a private speciality with this id exists, which is the
+    // disclosure GET /specialities/:id already refuses to make. A viewer who CAN
+    // see it but does not own it still gets a truthful 403.
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    if (!owns(s, req.builder)) return res.fail('not_yours', { status: 403, message: 'Only the owner may edit a speciality.' });
+    if (req.body && req.body.discipline !== undefined) {
+      return res.fail('discipline_immutable', {
+        status: 400,
+        message: 'A speciality cannot change craft — everyone who adopted it would be silently re-scoped. Author a new one.',
+      });
+    }
+
+    const merged = { ...s, ...req.body };
+    const check = S.validateDraft(merged, { disciplines: api.enabledDisciplines() });
+    if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
+
+    res.json({ speciality: await db.updateSpeciality(id, req.body || {}) });
+  }));
+
+  // ── training (a): the owner's own documents ───────────────────────────────
+  router.post('/specialities/:id/documents', api.requireBuilder, asyncHandler('POST /specialities/:id/documents', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      title: { required: true, type: 'string', maxLength: S.LIMITS.DOC_TITLE, minLength: 1 },
+      body_md: { required: true, type: 'string', maxLength: S.LIMITS.DOC_BODY, minLength: 1 },
+      source: { type: 'string', maxLength: 64 },
+    })) return;
+
+    const s = await db.getSpeciality(id);
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    if (!owns(s, req.builder)) return res.fail('not_yours', { status: 403, message: 'Only the owner may train a speciality.' });
+
+    // COUNT(*), not a fetch: reading the cap by pulling up to 200 metadata rows
+    // and taking .length is work the database can do in one number.
+    const { documentCount } = await db.countTraining(id);
+    if (documentCount >= S.LIMITS.DOCS_PER_SPECIALITY) {
+      return res.fail('too_many_documents', { status: 409, details: { max: S.LIMITS.DOCS_PER_SPECIALITY } });
+    }
+
+    const doc = await db.addDocument({
+      speciality_id: id,
+      title: String(req.body.title).trim(),
+      body_md: req.body.body_md,
+      source: req.body.source || 'paste',
+      content_sha: sha256(req.body.body_md),
+      added_by: req.builder.id,
+    });
+    // addDocument returns null on ON CONFLICT DO NOTHING — the same document is
+    // already trained in, so say so rather than claiming a create.
+    if (!doc) return res.status(200).json({ skipped: true, reason: 'already_trained' });
+    res.status(201).json({ document: doc });
+  }));
+
+  router.get('/specialities/:id/documents', api.requireBuilder, asyncHandler('GET /specialities/:id/documents', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    if (!s) return res.fail('not_found', 404);
+    if (!(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    res.json({ documents: await db.listDocuments(id) });
+  }));
+
+  router.delete('/specialities/:id/documents/:docId', api.requireBuilder, asyncHandler('DELETE /specialities/:id/documents/:docId', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    if (!owns(s, req.builder)) return res.fail('not_yours', 403);
+    const gone = await db.deleteDocument(id, req.params.docId);
+    if (!gone) return res.fail('not_found', 404);
+    res.json({ ok: true });
+  }));
+
+  // ── adoption ──────────────────────────────────────────────────────────────
+  router.post('/specialities/:id/adopt', api.requireBuilder, asyncHandler('POST /specialities/:id/adopt', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    // 404, not 403: a 403 here confirms that a speciality with this id exists,
+    // which is exactly the disclosure GET /specialities/:id refuses to make. The
+    // previous round moved PATCH and the document routes and missed this one.
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    // The craft is passed from the SPECIALITY, never from the client: it is what
+    // the one-active-per-craft unique index keys on.
+    const adoption = await db.adopt({ builderId: req.builder.id, specialityId: id, discipline: s.discipline });
+    res.json({ adoption });
+  }));
+
+  router.post('/specialities/:id/abandon', api.requireBuilder, asyncHandler('POST /specialities/:id/abandon', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const dropped = await db.abandon(req.builder.id, id);
+    res.json({ ok: true, was_active: dropped });
+  }));
+
+  router.get('/me/specialities', api.requireBuilder, asyncHandler('GET /me/specialities', async (req, res) => {
+    res.json({ adoptions: await db.listAdoptions(req.builder.id) });
+  }));
+
+  return router;
+};