@bongos/core 1.17.0

package/modules/autonomy/module.json

@@ -0,0 +1,13 @@
+{
+  "key": "autonomy",
+  "title": "Autonomy & MAS (conductor · architect · gate · routine timers)",
+  "description": "The Multi-Agent System's autonomy surfaces (ADR 0024): the $0 deterministic autonomy gate (System 3 — a precheck route + the gate CLI, inert until OTB_AUTONOMY_ENABLED=1), the conductor mid-flight dispatch CLI (Phase 4), the Architect bounded first-principles --scope audit CLI (Phase 5), and the in-process routine timers (System 4 / ADR 0078 amendment — the weekly peer-vote-tally poller). A core-domain module carved out of the GDS core in BV1.R83 (ADR 0093 §1); default-on because the autonomy machinery + the durable routine timer ship to every instance (both are inert/no-op until armed or the pool is reachable). Cross-cutting: it OBSERVES lifecycle events. The routine timer reaches the lifecycle `tallyPeerVotes` capability through the published doorway (a tracked lifecycle leak until R86), never a core require; the precheck route + the gate/conductor/architect CLIs travel with this domain (the CLIs stay under scripts/, outside the kernel boundary, so they may still read the ideas/economy/lifecycle signals + the grader directly). Registers no port — core never calls back in.",
+  "coreVersion": "^1.11.0",
+  "default": true,
+  "contributes": {
+    "routes": ["autonomy"],
+    "pollers": ["routine-timers"]
+  },
+  "provides": [],
+  "consumes": []
+}

package/modules/autonomy/pollers/routine-timers.js

@@ -0,0 +1,146 @@
+'use strict';
+
+// modules/autonomy/pollers/routine-timers.js — server-internal routine timers
+// (System 4 / ADR 0078 amendment, task 1382; carved into modules/autonomy/ at
+// BV1.R83 / ADR 0093 §1).
+//
+// THE POLLER SEAM. The autonomy module manifest declares
+// contributes.pollers:["routine-timers"]; the loader (src/module-loader/loader.js
+// startModulePollers) requires THIS file and calls start(deps) at boot, stop() at
+// shutdown — the module-agnostic successor to the hardcoded `routineTimers.start()`
+// block server.js used to carry. server.js (the game/droplet entrypoint) is the
+// ONLY caller of startModulePollers, never src/platform-server.js, so a future
+// second always-on instance on the same DB can't double-run (and the FOR UPDATE
+// row lock in tallyPeerVotes is the hard guard if one ever does).
+//
+// WHY THIS EXISTS
+// ADR 0078 demoted peer-vote-tally to `mode: deterministic` and built an EXTERNAL
+// dispatcher (scripts/gds/run-routine.js) the operator was meant to wire into
+// cron. But nothing was ever durably scheduled — every scheduler layer (the
+// local app tasks, the session cron, the claude.ai cloud routines) was empty, so
+// the realized run count was ZERO. A deterministic routine that never fires saves
+// nothing. The routine's real work is server-side and needs no model, so the
+// durable realization is an in-process timer inside the always-on Node process —
+// the SAME pattern as the publish-reconciler / uptime-poller. No external cron, no
+// `claude -p`, no token spend.
+//
+//   - peer-vote-tally (weekly): folds matured peer votes into karma. The work is
+//     the `tallyPeerVotes` doorway capability — the exact transaction
+//     POST /tasks/peer-votes/tally runs, so route + timer share one path. It
+//     writes karma_log/peer_votes/tasks (all lifecycle/core-owned), so it can't be
+//     autonomy-owned; the module reaches it through the published doorway
+//     (src/module-api.js), never a core require (BV1.R83 / ADR 0093 §1). The
+//     route's Archon gate is an HTTP-auth concern; an in-process call has no
+//     requester and the SQL writes karma_log with granted_by = NULL. No identity
+//     needed. Idempotent (only matured, untallied votes) + a FOR UPDATE row lock,
+//     so over-/under-firing is harmless and a second instance can't double-fold.
+//
+// (diagram-drift was intentionally NOT made a timer: all five onboarding diagrams
+// already auto-regenerate from live facts on every deploy, so a daily drift check
+// is near-redundant; the manual `node scripts/gds/run-routine.js diagram-drift`
+// remains for on-demand use. See the ADR 0078 amendment.)
+//
+// Mirrors the publish-reconciler contract: env-overridable interval, an UNREF'd
+// timer (never holds the process open across a systemd restart), best-effort (a
+// throw logs `[routine-timers]` + waits for the next tick — NEVER crashes the
+// server), and a run function pure w.r.t. injected deps so it unit-tests with no
+// DB. A no-op anywhere the pool is unreachable (builder laptops/boxes): the run
+// catches the connection error and returns a skip summary, so it is safe to
+// start unconditionally on the game boot.
+
+// The published doorway — the autonomy module reaches the `tallyPeerVotes`
+// lifecycle capability through the `lifecycle` kernel PORT here (the doorway leak
+// retired at BV1.R86), never a core require (the one-way boundary, ADR 0083).
+// Resolved lazily inside runPeerVoteTally so requiring this poller never forces a
+// core load at module-discovery time, and so tests that pass deps.db bypass it.
+const api = require('../../../src/module-api');
+
+const WEEK_MS = 7 * 24 * 60 * 60_000;
+
+const PEER_VOTE_INTERVAL_MS = Number(process.env.ROUTINE_PEER_VOTE_MS) || WEEK_MS;
+// First-fire delay: let the server finish binding + the other in-process pollers
+// settle before the first tally. Jitter spreads first-fire across a minute so a
+// crash-loop / deploy storm doesn't synchronize every restart's first run.
+const PEER_VOTE_FIRST_MS = Number(process.env.ROUTINE_PEER_VOTE_FIRST_MS) || 90_000;
+const JITTER_MS = 60_000;
+
+let peerVoteFirst = null;
+let peerVoteInterval = null;
+
+// One peer-vote tally run. Pure w.r.t. injected deps. Returns the same shape the
+// HTTP route returns (votes_tallied / builders_credited / karma / lag_days) for
+// tests + observability. Idempotent: db.tallyPeerVotes only folds matured,
+// untallied votes and then stamps them, so a re-run within the week finds nothing.
+// NEVER throws: a DB-unreachable error (e.g. on a builder machine) degrades to a
+// logged skip — the timer must never take the server down.
+async function runPeerVoteTally(deps = {}) {
+  // Default to the `lifecycle` port (the peer-vote→karma fold-in lives there now);
+  // tests inject deps.db to drive the run with no DB. resolveOptional → null when
+  // lifecycle is somehow off → the typeof guard below returns a clean skip.
+  const db = deps.db || api.resolveOptional('lifecycle') || {};
+  const logFn = deps.log || console.log;
+  const errFn = deps.error || console.error;
+  if (typeof db.tallyPeerVotes !== 'function') {
+    return { skipped: 'unsupported' };
+  }
+  try {
+    const r = await db.tallyPeerVotes();
+    if (r && r.votes_tallied > 0) {
+      logFn(
+        `[routine-timers] peer-vote-tally: ${r.votes_tallied} vote(s) folded into karma across ` +
+        `${r.builders_credited} builder(s) (lag ${r.lag_days}d).`
+      );
+    }
+    return r;
+  } catch (e) {
+    errFn(`[routine-timers] peer-vote-tally (non-blocking): ${e && e.message}`);
+    return { skipped: 'error', error: e && e.message };
+  }
+}
+
+// Start the timer(s). Idempotent. Kill-switched by ROUTINE_TIMERS_DISABLED=1.
+// Unref'd so it never holds the process open on a systemd restart. Started by the
+// loader's startModulePollers ONLY on the game/droplet entrypoint (server.js),
+// never in src/platform-server.js, so a future second always-on instance on the
+// same DB can't double-run (and the FOR UPDATE row lock in tallyPeerVotes is the
+// hard guard if one ever does).
+function start(deps = {}) {
+  if (process.env.ROUTINE_TIMERS_DISABLED === '1') {
+    console.log('[routine-timers] disabled (ROUTINE_TIMERS_DISABLED=1)');
+    return;
+  }
+  // Idempotent: guard on the FIRST-fire timer too, not just the interval — the
+  // interval is only set once the first-fire setTimeout fires (~90s later), so a
+  // second start() before then would otherwise schedule a duplicate first run.
+  if (peerVoteFirst || peerVoteInterval) return; // already started
+  const jitter = () => Math.floor(Math.random() * JITTER_MS);
+
+  const peerTick = () =>
+    runPeerVoteTally(deps).catch((e) =>
+      console.error(`[routine-timers] peer-vote tick crashed: ${e && e.message}`));
+
+  peerVoteFirst = setTimeout(() => {
+    peerTick();
+    peerVoteInterval = setInterval(peerTick, PEER_VOTE_INTERVAL_MS);
+    if (peerVoteInterval.unref) peerVoteInterval.unref();
+  }, PEER_VOTE_FIRST_MS + jitter());
+  if (peerVoteFirst.unref) peerVoteFirst.unref();
+
+  console.log(
+    `[routine-timers] started — peer-vote-tally every ${Math.round(PEER_VOTE_INTERVAL_MS / 3600_000)}h ` +
+    `(first run ~${Math.round(PEER_VOTE_FIRST_MS / 1000)}s after boot, then boot-anchored weekly)`
+  );
+}
+
+function stop() {
+  if (peerVoteFirst) clearTimeout(peerVoteFirst);
+  if (peerVoteInterval) clearInterval(peerVoteInterval);
+  peerVoteFirst = peerVoteInterval = null;
+}
+
+module.exports = {
+  start,
+  stop,
+  runPeerVoteTally,
+  PEER_VOTE_INTERVAL_MS,
+};

package/modules/autonomy/routes/autonomy.js

@@ -0,0 +1,37 @@
+const express = require('express');
+// The published doorway — requireBuilder / requireRank live on the doorway surface
+// (a module never reaches into core auth directly; the one-way boundary, ADR 0083).
+const api = require('../../../src/module-api');
+const auth = api;
+// The autonomy gate is a domain CLI under scripts/ (it travels with this domain
+// but stays a command; its gatherSignals reaches the ideas/economy/lifecycle reads
+// from OUTSIDE the kernel boundary, which a modules/ file may not do). scripts/ is
+// neither core internals nor a sibling module, so importing it here is allowed.
+const autonomyGate = require('../../../scripts/gds/autonomy-gate');
+
+// System 3 (task 1351): the autonomy precheck over HTTP. The deterministic
+// decision logic lives in scripts/gds/autonomy-gate.js (run directly as a CLI
+// Step 0 by the nightly routines on the droplet); this endpoint exposes the same
+// decision for any other caller. BUILT DISABLED: while OTB_AUTONOMY_ENABLED!=1
+// it always returns decision:'go' (inert).
+//
+// rank: archon — autonomy is an ops control surface, and a precheck records an
+// autonomy_runs row + git-fetches. Keep it archon-scoped (ADR 0016).
+module.exports = function buildAutonomyRouter() {
+  const router = express.Router();
+
+  router.get('/autonomy/precheck', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const routine = String(req.query.routine || '').slice(0, 64);
+    if (!routine) return res.fail('routine_required', { status: 400, message: 'pass ?routine=<name>' });
+    try {
+      const out = await autonomyGate.precheck(routine);
+      res.json(out);
+    } catch (err) {
+      // Fail-open: an autonomy gate must never become a new way to break a routine.
+      console.error('[gds] GET /autonomy/precheck', err);
+      res.json({ routine, decision: 'go', reason: `precheck error (fail-open): ${err.message}`, enabled: autonomyGate.isEnabled() });
+    }
+  });
+
+  return router;
+};

package/modules/builder-settings/CLAUDE.md

@@ -0,0 +1,58 @@
+# `builder-settings` module — per-builder prefs + builder-needs + the `builder-settings` kernel port
+
+> The **sixth CORE-domain** carved into a module (BV1.R80, [ADR 0093](../../docs/adr/<redacted>.md) §1) — after memory (R72), grading (R73), economy (R77), ideas (R78), and security (R79). A clean slice: the five pref libs + builder-needs were already standalone PURE files (zero core `require()`), so the carve is a git-move + a `db.js`-slice extraction + a route SPLIT + a port re-point — OTB byte-identical. `default: true` in `module.json` — every instance configures its own builders.
+
+Owns the **per-builder preference domain** and **builder-needs**:
+
+- **wandering** ([`wandering-prefs.js`](wandering-prefs.js)) — how readily the agent opens a NEW THREAD of work (tangent / investigation / unsolicited suggestion) vs. staying on the claimed task. Rank-clamped server-side (Xenos → Locked, Thetes → Focused, Metic+ free). Stored in the `behavior_prefs` jsonb.
+- **interaction** ([`interaction-prefs.js`](interaction-prefs.js)) — the per-builder INTERACTION PROFILE (task 2010): tone / technical level / local-toolchain familiarity — the old CLAUDE.md §2 "The Prompter" owner-defaults, reframed as a per-builder profile (an owner is just a builder with a profile). Resolved over the portable defaults; the effective `contract` is surfaced on `/me` and injected each session (the wandering pattern). Stored in the `behavior_prefs` jsonb; `GET`/`PATCH /me/interaction`.
+- **skill** ([`skill-prefs.js`](skill-prefs.js)) — the per-skill model ceiling a spawn is clamped to (`skill_model_prefs` jsonb, migration 037).
+- **model-allocation** ([`model-alloc-prefs.js`](model-alloc-prefs.js)) — the subagent model-routing policy (task 2011): the tier for main / subagent-default / routine-plumbing slots. Resolved builder override → instance default (`branding.models`) → code default (`opus`/`opus`/`haiku`); surfaced on `/me` (`model_allocation.effective`) + `GET`/`PATCH /me/model-allocation`. Replaces the hardcoded CLAUDE.md §2 routing table. PURE lib (instance default passed in). Stored in `behavior_prefs`.
+- **sound** ([`sound-prefs.js`](sound-prefs.js)) + **event-sound** ([`event-sound-prefs.js`](event-sound-prefs.js)) — per-sound on/off + volume (`sound_prefs`, migration 075) and per-event sound-variant selection (`event_sound_prefs`, migration 164). The local `.claude/sounds/play.js` reads a mirror written by `scripts/gds/fetch-sound-prefs.js`.
+- **render** ([`render-prefs.js`](render-prefs.js)) — the "render the deterministic session cards as a rich HTML widget vs. plain text" toggle (shares `behavior_prefs`, migration 119).
+- **builder-needs** ([`builder-needs.js`](builder-needs.js)) — the consistent "the system needs an input from you" list (today: the image-generation key).
+
+## The boundary (the one rule)
+
+This module reaches core **only** through the published doorway [`../../src/module-api.js`](../../src/module-api.js) (`coreVersion ^1.8.0`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches the prefs/needs read surface only through the `builder-settings` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks.
+
+## The `me`/`public` facade call (02-module-map §2)
+
+[02-module-map §2](../../docs/design/modular-architecture/02-module-map.md) flags `me` as a cross-domain read-aggregator that becomes a **thin facade** when its domains carve out. This carve realizes that for the prefs/needs slices:
+
+- **The five `/me/*-prefs` ROUTES moved here** ([`routes/settings.js`](routes/settings.js)) — `GET`/`PATCH` for `/me/skill-prefs`, `/me/sound-prefs`, `/me/event-sound-prefs`, `/me/wandering`, `/me/render`. They keep their **exact `/me/*` paths** (the loader mounts this router on the same `/api/gds` router, BEFORE the public catch-all), so the API is byte-identical — only the `require()` paths changed (auth/`getBuilderById` reach the doorway; the pref libs + the db slice are intra-module).
+- **The `GET /me` AGGREGATOR stayed in core `routes/me.js`** as a thin facade. It builds the `wandering` / `render` / `needs` slices of the profile payload inline (alongside the economy `reward`-port + discord/box/art seam slices it already resolves) by resolving the `builder-settings` port — never importing the module.
+- **`public.js` has NO builder-settings edge** — the §2 graph's `public → grader, security` is the real public coupling; prefs/needs are a `me`-only domain. `public.js` is untouched by this carve.
+
+## The `builder-settings` kernel PORT
+
+- **Provides — port `builder-settings`** → the read surface in [`settings.js`](settings.js): `{ getBuilderBehaviorPrefs, describeWandering, describeRender, computeNeeds, skillCeiling }`. Registered in [`routes/settings.js`](routes/settings.js)'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider guard). Mirrors `modules/economy/routes/reward.js`.
+- **The TWO core consumers resolve it WITHOUT importing this module:**
+  - `routes/me.js` — the `GET /me` aggregator (`getBuilderBehaviorPrefs` once, then `describeWandering`/`describeRender`/`computeNeeds` off the same blob).
+  - `src/bongos/cascade-dispatch.js` — the dormant System-3 cascade router clamps a spawn to the builder's model ceiling (`skillCeiling`, the former `skillPrefs.getForBuilder`).
+- Both degrade gracefully when the module is off (a vanilla instance): me.js's slices are best-effort; cascade's ceiling falls back to `'opus'` (its existing `|| 'opus'` default). No `CORE_VERSION` bump — the carve adds no doorway export (the port rides the already-exported seam registry, the security precedent).
+
+## Files
+
+| File | What |
+|---|---|
+| `db.js` | the builder-prefs db slice — the eight verbatim `get/set BuilderSkillPrefs / SoundPrefs / BehaviorPrefs / EventSoundPrefs` helpers carved out of core `db.js`. Reaches the shared pool through the doorway. |
+| `skill-prefs.js` · `sound-prefs.js` · `event-sound-prefs.js` · `wandering-prefs.js` · `render-prefs.js` | the pure shapers (`validatePatch`/`applyPatch`/`listEffective`/`describeForApi`/constants) that turn a raw jsonb blob into effective values. Moved verbatim (they were already core-`require()`-free). |
+| `builder-needs.js` | `computeNeeds(ctx)` — the "the system needs an input from you" list (the image-generation-key item). |
+| `settings.js` | the `builder-settings` port provider surface — DELEGATES (does not spread) to `db`/the pref libs so test stubs bite at call time. |
+| `routes/settings.js` | the five `/me/*-prefs` GET/PATCH endpoints (above) + the port registration. |
+
+## NOT in this module (deliberately left in core)
+
+- **The `GET /me` aggregator + every non-prefs `/me/*` route** — `routes/me.js` stays core (it's the cross-domain profile/identity surface; only the self-contained pref routes left). It resolves this module's port for its prefs/needs slices.
+- **The per-builder Gemini KEY** (`getBuilderGeminiKeyRow` / `setBuilderGeminiKey` / `clearBuilderGeminiKey`, `gemini_key_*` columns) — stays core `db.js` + the doorway (`api.getBuilderGeminiKeyRow`). It's art-pipeline credential infra (the `/me/art-key` delivery + the `art.sharedKeyConfigured` seam), read by `computeNeeds`'s caller as `ownKeySet`, not owned by builder-settings.
+- **`cascade-dispatch.js`** — the dormant System-3 cascade router stays a CORE lib (it belongs to the grading/autonomy plane, not builder-settings); it RESOLVES this module's `skillCeiling` port instead of importing `skill-prefs`.
+- **The pref-mirroring CLIs** — `scripts/gds/fetch-sound-prefs.js` + `scripts/gds/session-eval.js` (which reads `wandering-prefs`) travel with the domain but stay under `scripts/` and `require('../../modules/builder-settings/…')` directly (scripts are outside the kernel boundary — the memory/economy-carve precedent).
+
+## Tables
+
+None owned. The five jsonb columns (`skill_model_prefs` 037, `sound_prefs` 075, `behavior_prefs` 119, `event_sound_prefs` 164) live on the CORE `builders` table and stay in core `migrations/`. This module owns the *prefs queries*; any **new** builder-settings migration belongs in `modules/builder-settings/migrations/` namespaced `builder_settings_*` (the additive rule).
+
+## Tests
+
+`tests/skill_prefs.mjs`, `tests/sound_prefs.mjs`, `tests/wandering_prefs.mjs`, `tests/render_prefs.mjs`, and `tests/builder_needs.mjs` import the pure shapers from `modules/builder-settings/…`. The doorway/boundary checks (`tests/fitness.mjs`, `tests/module_loader.mjs`, `tests/modules.mjs`) discover `builder-settings` as a module. See [ADR 0093](../../docs/adr/<redacted>.md).

package/modules/builder-settings/builder-needs.js

@@ -0,0 +1,115 @@
+// src/bongos/builder-needs.js — the one consistent way to flag "the system needs an
+// input from you to run" (task 1013 / ADR 0073).
+//
+// THE PATTERN. Some capabilities need a per-builder input the system can't supply
+// itself — today the Gemini image key; tomorrow a Stripe key, a first-party
+// Anthropic link, etc. Instead of each one inventing its own banner/prompt, they
+// register ONE "need" here. The server computes the live list on /me; every
+// surface (the hall Standing card, the CLI session nudge, the point-of-use stop)
+// renders the SAME shape. Add a future input = add one entry to NEEDS — the
+// renderers don't change.
+//
+// A need is always in exactly one of three states:
+//   'covered'        — the system is handling it for them right now; nothing to
+//                      do. (e.g. a newcomer whose image generation we pay for.)
+//   'action_needed'  — the system needs them to provide the input NOW or a
+//                      capability won't run. This is the one that surfaces loudly.
+//   'satisfied'      — they've provided it. Rendered quietly (a ✓) or not at all.
+//
+// Each need is a small pure function of the builder's context, so this whole
+// module is unit-testable with no DB.
+
+'use strict';
+
+// Where a builder goes to provide an input. Same hall origin as the rest of the
+// web surfaces; the CLI nudge prints the absolute URL, the web renderers use the
+// relative path.
+const SETTINGS_PATH = '/settings';
+
+// ---- need: art_key (per-builder Gemini image-generation key) ----------------
+//
+// ctx.rank                    — live builder rank (xenos|thetes|metic|archon).
+// ctx.ownKeySet               — does the builder have their OWN key stored on the
+//                               server? (db column gemini_key_enc is non-null).
+// ctx.sharedKeyConfigured     — does the server have a shared newcomer key to
+//                               give? (art-key.sharedGeminiKeyConfigured()).
+//
+// States:
+//   ownKeySet                       → satisfied (their own key runs the pipeline)
+//   newcomer (xenos)                → covered   ("on us while you get started")
+//   thetes+ and no own key          → action_needed (coverage has ended)
+function artKeyNeed(ctx) {
+  const rank = ctx.rank || null;
+  const isNewcomer = rank === 'xenos';
+  const base = {
+    id: 'art_key',
+    title: 'Image-generation key',
+    // What the input is FOR, in plain words — the same line on every surface.
+    what: 'The art pipeline draws your tiles and sprites with Google AI Studio (Gemini).',
+    learn_more_url: 'https://aistudio.google.com/app/apikey',
+  };
+
+  if (ctx.ownKeySet) {
+    return {
+      ...base,
+      state: 'satisfied',
+      severity: 'info',
+      message: 'Your own image key is set — art runs on it.',
+      action: null,
+    };
+  }
+
+  if (isNewcomer) {
+    // "We cover it for them" — reassuring, and it foreshadows the hand-off so the
+    // later action_needed is never a surprise (Lars's chosen tone, 2026-06-20).
+    return {
+      ...base,
+      state: 'covered',
+      severity: 'info',
+      title: 'Image generation — on us',
+      message: 'While you find your feet, we cover the cost of generating art — nothing to set up. When you reach Thetes you\'ll add your own key, and we\'ll remind you then.',
+      action: null,
+    };
+  }
+
+  // Thetes+ with no own key: our free coverage has ended. Art won't run until
+  // they add their own key. The message is rank-neutral on purpose (task 1392):
+  // it fires for every tier past the covered Xenos floor — Thetes, Metic, and
+  // Archon — so it must not name a single rank (an Archon was shown "graduated
+  // to Thetes", the wrong rank).
+  return {
+    ...base,
+    state: 'action_needed',
+    severity: 'action',
+    message: 'Your free art coverage has ended, so image generation now runs on your own key (you pay only for what you make). Add it to keep making art.',
+    action: { label: 'Add your key', href: `${SETTINGS_PATH}#art-key` },
+  };
+}
+
+// The registry. To add a future input the system needs from a builder, append a
+// pure (ctx) => need|null function here — every renderer picks it up for free.
+const NEEDS = [artKeyNeed];
+
+// Compute the live list for a builder. `ctx` carries everything the need
+// functions read (see each need's doc). Returns:
+//   { items: Need[], action_needed_count, has_action_needed }
+// items is ordered: action_needed first (loudest), then covered, then satisfied,
+// so any renderer that takes "the first one" gets the most urgent.
+function computeNeeds(ctx = {}) {
+  const items = NEEDS.map((fn) => fn(ctx)).filter(Boolean);
+  const order = { action_needed: 0, covered: 1, satisfied: 2 };
+  items.sort((a, b) => (order[a.state] ?? 9) - (order[b.state] ?? 9));
+  const actionNeeded = items.filter((n) => n.state === 'action_needed');
+  return {
+    items,
+    action_needed_count: actionNeeded.length,
+    has_action_needed: actionNeeded.length > 0,
+  };
+}
+
+module.exports = {
+  computeNeeds,
+  // exported for tests / direct reuse
+  artKeyNeed,
+  SETTINGS_PATH,
+};

package/modules/builder-settings/db.js

@@ -0,0 +1,168 @@
+'use strict';
+
+// modules/builder-settings/db.js — the builder-PREFS db slice carved out of the
+// core src/bongos/db.js monolith (BV1.R80 / ADR 0093 §1). The five per-builder
+// preference jsonb columns on `builders` — skill_model_prefs (037), sound_prefs
+// (075), behavior_prefs (119, the wandering + render knobs share it), and
+// event_sound_prefs (164) — are read/written here. OTB byte-identical: the eight
+// helpers are the verbatim db.js functions; ONLY the pool require changed — it
+// now reaches the shared Postgres pool through the published doorway
+// (src/module-api.js) instead of `../db`, the per-domain db-slice pattern ADR
+// 0091 §2 established (memory.js / economy cost.js precedent).
+//
+// The shapers that turn these raw blobs into effective values stay intra-module
+// siblings (skill-prefs.js / sound-prefs.js / wandering-prefs.js / render-prefs.js
+// / event-sound-prefs.js). The `builders` table itself stays a CORE table — this
+// module owns only the prefs QUERIES, never the schema (the additive-migration
+// rule: a NEW builder-settings column would still live here, namespaced).
+
+const { pool } = require('../../src/module-api');
+
+// Read a builder's skill_model_prefs jsonb column (migration 037 / V3.R85).
+// Returns a plain object — empty {} when no preferences are set. Callers
+// resolve the effective per-skill pick via skill-prefs.js (this helper is
+// just the DB read).
+async function getBuilderSkillPrefs(builderId) {
+  const { rows } = await pool.query(
+    `SELECT skill_model_prefs FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  return rows[0]?.skill_model_prefs ?? {};
+}
+
+// Replace a builder's skill_model_prefs jsonb (migration 037 / V3.R85).
+// Caller is expected to have already validated the shape via
+// skillPrefs.validatePatch + applied it via skillPrefs.applyPatch — this
+// helper just writes the final object verbatim. Returns the saved object.
+async function setBuilderSkillPrefs(builderId, prefs) {
+  const payload = prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET skill_model_prefs = $2::jsonb
+      WHERE id = $1
+      RETURNING skill_model_prefs`,
+    [builderId, JSON.stringify(payload)]
+  );
+  return rows[0]?.skill_model_prefs ?? {};
+}
+
+// Read a builder's sound_prefs jsonb (migration 075 / V3.R91, #786). Returns a
+// plain object — empty {} when no preferences are set. Callers resolve the
+// effective per-sound on/off via sound-prefs.js (this helper is just the read).
+async function getBuilderSoundPrefs(builderId) {
+  const { rows } = await pool.query(
+    `SELECT sound_prefs FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  return rows[0]?.sound_prefs ?? {};
+}
+
+// Replace a builder's sound_prefs jsonb (migration 075 / V3.R91). Caller is
+// expected to have validated the shape via soundPrefs.validatePatch + applied
+// it via soundPrefs.applyPatch — this helper just writes the final object
+// verbatim. Returns the saved object.
+async function setBuilderSoundPrefs(builderId, prefs) {
+  const payload = prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET sound_prefs = $2::jsonb
+      WHERE id = $1
+      RETURNING sound_prefs`,
+    [builderId, JSON.stringify(payload)]
+  );
+  return rows[0]?.sound_prefs ?? {};
+}
+
+// Read a builder's behavior_prefs jsonb (migration 119, task 1268). Returns a
+// plain object — empty {} when no preferences are set. Callers resolve the
+// effective level via wandering-prefs.js (this helper is just the DB read).
+async function getBuilderBehaviorPrefs(builderId) {
+  const { rows } = await pool.query(
+    `SELECT behavior_prefs FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  return rows[0]?.behavior_prefs ?? {};
+}
+
+// Replace a builder's behavior_prefs jsonb (migration 119). Caller is expected
+// to have validated the shape via wanderingPrefs.validatePatch + applied it via
+// wanderingPrefs.applyPatch — this helper just writes the final object verbatim.
+// Returns the saved object.
+async function setBuilderBehaviorPrefs(builderId, prefs) {
+  const payload = prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET behavior_prefs = $2::jsonb
+      WHERE id = $1
+      RETURNING behavior_prefs`,
+    [builderId, JSON.stringify(payload)]
+  );
+  return rows[0]?.behavior_prefs ?? {};
+}
+
+// Read a builder's event_sound_prefs jsonb (migration 164, task 582). Returns a
+// plain object — empty {} when no preferences are set. Callers resolve the
+// effective per-event variant via event-sound-prefs.js.
+async function getBuilderEventSoundPrefs(builderId) {
+  const { rows } = await pool.query(
+    `SELECT event_sound_prefs FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  return rows[0]?.event_sound_prefs ?? {};
+}
+
+// Replace a builder's event_sound_prefs jsonb (migration 164). Caller is
+// expected to have validated + applied the patch — this helper just writes
+// the final object verbatim. Returns the saved object.
+async function setBuilderEventSoundPrefs(builderId, prefs) {
+  const payload = prefs && typeof prefs === 'object' && !Array.isArray(prefs) ? prefs : {};
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET event_sound_prefs = $2::jsonb
+      WHERE id = $1
+      RETURNING event_sound_prefs`,
+    [builderId, JSON.stringify(payload)]
+  );
+  return rows[0]?.event_sound_prefs ?? {};
+}
+
+// Read a builder's display_name (the free label shown next to their work in the
+// hall — header, leaderboard, work feed). Stable identity stays github_login/id;
+// this is just the rendered name. Returns the string, or null if no such row.
+// (task 1669 — the self-service display-name editor.)
+async function getBuilderDisplayName(builderId) {
+  const { rows } = await pool.query(
+    `SELECT display_name FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  return rows[0]?.display_name ?? null;
+}
+
+// Set a builder's display_name (task 1669). Caller is expected to have already
+// validated + trimmed the value via display-name.js's validate() — this helper
+// writes it verbatim and returns the saved string. Own-scoped: the route only
+// ever passes the AUTHENTICATED builder's id. display_name is `text NOT NULL`
+// (migration 003), so a validated non-empty string is always a legal write.
+async function setBuilderDisplayName(builderId, displayName) {
+  const { rows } = await pool.query(
+    `UPDATE builders
+        SET display_name = $2
+      WHERE id = $1
+      RETURNING display_name`,
+    [builderId, displayName]
+  );
+  return rows[0]?.display_name ?? null;
+}
+
+module.exports = {
+  getBuilderSkillPrefs,
+  setBuilderSkillPrefs,
+  getBuilderSoundPrefs,
+  setBuilderSoundPrefs,
+  getBuilderBehaviorPrefs,
+  setBuilderBehaviorPrefs,
+  getBuilderEventSoundPrefs,
+  setBuilderEventSoundPrefs,
+  getBuilderDisplayName,
+  setBuilderDisplayName,
+};

package/modules/builder-settings/display-name.js

@@ -0,0 +1,84 @@
+'use strict';
+
+// modules/builder-settings/display-name.js — the pure validator for a builder's
+// self-edited DISPLAY NAME (task 1669).
+//
+// Today builders.display_name is seeded once from the GitHub display name at
+// account creation, with no way to change it. The GET/PATCH /me/display-name
+// routes (routes/settings.js) let a builder rename the label shown next to their
+// work in the hall (header, leaderboard, work feed — all already read
+// display_name, so a DB update propagates). This file is the SSOT for the rules:
+// what a valid new name is, mirroring the pref-lib pattern (validatePatch +
+// constants) so the route stays a thin shell.
+//
+// Scope: own name only — the route is api.requireBuilder and writes the
+// AUTHENTICATED builder's row. Identity stays github_login/id; the display name
+// is a free label, so UNIQUENESS IS NOT REQUIRED (names may collide).
+//
+// Storage: the `display_name` column on `builders` is `text NOT NULL`
+// (migration 003), so there is no DB-level length ceiling — we enforce a
+// sensible one here so the hall doesn't have to render an arbitrarily long
+// string. 60 chars comfortably holds any real name (GitHub display names cap at
+// 255 but real ones are short; 60 keeps the leaderboard / work-feed rows tidy).
+
+// The longest display name we accept, in Unicode code points (so a multi-byte
+// character counts as one, matching how a human reads the limit).
+const MAX_LENGTH = 60;
+const MIN_LENGTH = 1; // after trimming — empty / whitespace-only is rejected
+
+// Count code points, not UTF-16 units, so an emoji or astral character is "1".
+function codePointLength(str) {
+  return Array.from(str).length;
+}
+
+// Control characters are rejected: C0 (0x00–0x1F), DEL (0x7F), and the C1 block
+// (0x80–0x9F). These include tabs, newlines, and other invisibles that would
+// break the single-line label everywhere display_name renders. A normal space
+// inside the name is fine (it's not a control char); leading/trailing space is
+// stripped by the trim below.
+function hasControlChar(str) {
+  for (const ch of str) {
+    const cp = ch.codePointAt(0);
+    if (cp <= 0x1f || cp === 0x7f || (cp >= 0x80 && cp <= 0x9f)) return true;
+  }
+  return false;
+}
+
+// Validate a candidate display name. Returns { ok:true, value } with the trimmed
+// name on success, or { ok:false, errors:[{ error, ... }] } on failure. Pure: no
+// DB, no IO — the route calls this, then writes `value` verbatim.
+//
+//   - not a string                       → 'must_be_string'
+//   - empty / whitespace-only (post-trim)→ 'empty'
+//   - longer than MAX_LENGTH (post-trim) → 'too_long'  (carries max + length)
+//   - contains a control character       → 'control_char'
+function validate(name) {
+  if (typeof name !== 'string') {
+    return { ok: false, errors: [{ error: 'must_be_string' }] };
+  }
+  const trimmed = name.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, errors: [{ error: 'empty', message: 'Display name cannot be blank.' }] };
+  }
+  // Check control chars on the trimmed value — leading/trailing whitespace was
+  // already removed; an interior control char (tab, newline) is what we forbid.
+  if (hasControlChar(trimmed)) {
+    return { ok: false, errors: [{ error: 'control_char', message: 'Display name cannot contain control characters.' }] };
+  }
+  const length = codePointLength(trimmed);
+  if (length > MAX_LENGTH) {
+    return {
+      ok: false,
+      errors: [{ error: 'too_long', message: `Display name must be ${MAX_LENGTH} characters or fewer.`, max: MAX_LENGTH, length }],
+    };
+  }
+  return { ok: true, value: trimmed };
+}
+
+module.exports = {
+  MAX_LENGTH,
+  MIN_LENGTH,
+  codePointLength,
+  hasControlChar,
+  validate,
+};