@bongos/core 1.19.811 → 1.19.812

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,
+};

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": []
+}