@bongos/core 1.17.0

package/src/bongos/routes/me.js

@@ -0,0 +1,380 @@
+const express = require('express');
+const auth = require('../auth');
+const db = require('../db');
+// streak + achievement getters + cost status carved into modules/economy/ (BV1.R77
+// / ADR 0093 §1-2); reached through the `reward` kernel port (resolved per call),
+// never a direct require of a module file.
+// The per-builder PREFERENCE domain (wandering · skill · sound · render) +
+// builder-needs carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1):
+// the five `/me/*-prefs` routes moved there; THIS aggregator stays a thin facade
+// that resolves the `builder-settings` kernel port for its wandering/render/needs
+// slices (02-module-map §2) — never a direct require of a module file. The
+// provider is default-on (present in prod); resolveOptional degrades on a
+// prefs-module-less instance so the slices simply render their unset/default shape.
+const { validateOrRespond } = require('./_helpers');
+const { branding } = require('../../branding'); // task 2011: instance model-allocation default
+// The onboarding state machine carved into modules/onboarding/ (BV1.R81 / ADR
+// 0093 §1): the GET /me aggregator + PATCH /me/disciplines resolve the
+// `onboarding` kernel port for their checklist slices (read/shape/mark) — never a
+// direct require of a module file.
+const { pool } = require('../pool');
+const seams = require('../../module-seams');
+// The lifecycle (tasks · claims · ship) carved to modules/lifecycle/ (BV1.R86 /
+// ADR 0093 §3): the per-builder claims/estimation/grade reads resolve the
+// `lifecycle` kernel PORT (lc()); the grade-TREND read (builderRollingAvgGrade)
+// stays core db (the sessions BFG also consumes it — kept on the doorway).
+const lc = () => seams.resolveOptional('lifecycle');
+// The dev-box "has this builder ever connected a box?" signal, read through the
+// kernel seam instead of a direct `require('../boxes')` (a forbidden core→module
+// edge once dev-box moved to modules/dev-box/, ADR 0083 / BV1.R43). The dev-box
+// module provides the `box.hasEverConnected` port when enabled; resolveOptional
+// degrades to false on a box-less instance, so onboarding's box_connect step
+// simply never auto-clears there. Resolved per call (the provider registers at
+// boot, before any request).
+const boxHasEverConnected = (builderId) =>
+  seams.resolveOptional('box.hasEverConnected', async () => false)(builderId);
+// The art-pipeline "is the shared newcomer key configured?" signal, read through
+// the kernel seam (ADR 0083 / BV1.R48). The art-pipeline module provides
+// 'art.sharedKeyConfigured' when enabled; resolveOptional degrades to false on a
+// vanilla instance so builder-needs.computeNeeds still works without the module.
+const artSharedKeyConfigured = () =>
+  seams.resolveOptional('art.sharedKeyConfigured', () => false)();
+// The "has this builder linked their Discord account?" signal, read through the
+// kernel seam instead of a direct `require('../db').getDiscordLink` (a forbidden
+// core→module edge once discord moved to modules/discord/, ADR 0083 / BV1.R47).
+// The discord module provides the `discord.isLinked` port when enabled;
+// resolveOptional degrades to false on a discord-less instance, so the hall just
+// renders the un-linked state and onboarding's discord step never auto-clears.
+// `discord.configured` (does the server hold OAuth creds?) stays core — the
+// account-LINK flow (routes/auth.js) is not part of the module.
+const discordIsLinked = (builderId) =>
+  seams.resolveOptional('discord.isLinked', async () => false)(builderId);
+
+module.exports = function buildMeRouter() {
+  const router = express.Router();
+
+  // PMS-V2 #188: response now also carries `unlocked` (server-joined
+  // achievement metadata) + `locked_with_progress` (server-computed
+  // human-readable progress hint per locked achievement) so the /builders
+  // UI can render achievements without a follow-up API call. Additive only —
+  // existing keys preserved for back-compat with scripts/gds/me.js and the
+  // /builders web client.
+  //
+  // V3.R24 (#244): the `builder` payload now carries `karma` (migration 040
+  // added the column + karma_log table). The field is surfaced by
+  // db.getBuilderById() — no shape change here, just documenting that the
+  // /api/gds/me response is the canonical place clients read karma from.
+  //
+  // rank: any-builder — own identity + own contributions; preserved per CRITICAL §4.
+  router.get('/me', auth.requireBuilder, async (req, res) => {
+    // economy reads (achievement getters, streak, cost status) resolve the
+    // `reward` kernel port (BV1.R77 / ADR 0093 §1-2). economy is default-on, so
+    // the provider is present in prod; tests register it.
+    const reward = seams.resolveOptional('reward');
+    // builder-settings reads (the wandering/render/needs profile slices) resolve
+    // the `builder-settings` kernel port (BV1.R80 / ADR 0093 §1). Default-on, so
+    // present in prod; degrades to unset/default shapes when the module is off.
+    const settings = seams.resolveOptional('builder-settings');
+    // onboarding reads (the builder's own checklist state, shaped for the hall)
+    // resolve the `onboarding` kernel port (BV1.R81 / ADR 0093 §1). Default-on, so
+    // present in prod; degrades to a null state row (shapeForApi synthesizes the
+    // "nothing cleared" view) when the module is off.
+    const onboarding = seams.resolveOptional('onboarding');
+    const [
+      builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
+      recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
+      behaviorPrefs, geminiKeyRow,
+    ] = await Promise.all([
+      db.getBuilderById(req.builder.id),
+      lc().getActiveClaimsForBuilder(req.builder.id),
+      lc().getEstVsActualRatio(req.builder.id, 10),
+      reward.getBuilderAchievements(req.builder.id),
+      reward.getLockedAchievementsProgress(req.builder.id),
+      reward.computeStreak(req.builder.id),
+      // Task #197: surface the builder's last 5 quality grades + rolling avg.
+      lc().recentGradesForBuilder(req.builder.id, 5),
+      // Grade-trend read via the grading port (ADR 0102); zero-grade shape when grading is off.
+      seams.resolveOptional('grade.builderRollingAvgGrade', async () => ({ n: 0, avg_score: 0, n_passed: 0 }))(req.builder.id, 14),
+      // V3.R75 (#294): the builder's own onboarding state, shaped for the
+      // /builders hall checklist. Save the client a follow-up call. Through the
+      // `onboarding` port (BV1.R81); null row when the module is off.
+      onboarding ? onboarding.getState(pool, req.builder.id) : null,
+      // #766: shipped-task count drives the onboarding 'ship_three' "N of 3"
+      // counter. Cheap COUNT; folded into the parallel fan-out.
+      lc().countShippedTasksForBuilder(req.builder.id),
+      // V3.R28 (#248): the builder's last 10 karma_log entries so the
+      // proposer's "karma feed" — the done-when from R28 — is visible
+      // without a follow-up call. Newest first; granted_by joined to
+      // builders so the UI can render "granted by @<login>".
+      db.recentKarmaForBuilder(req.builder.id, 10),
+      // V3.R26 (#246): rolling 30-day karma delta so the profile card can
+      // render the karma trend without a follow-up call.
+      db.karmaDelta30d(req.builder.id),
+      // F7 (ADR 0033): whether this builder has linked a Discord account, so the
+      // hall can render Connect-Discord vs the linked/Unlink state without a
+      // follow-up call. Boolean only — the discord_user_id itself is never sent
+      // to the client (it's PII the UI has no need for).
+      discordIsLinked(req.builder.id),
+      // #823: whether the builder's dev box has ever reported a live Claude
+      // process (first_connected_at). Auto-clears the onboarding 'box_connect'
+      // step — the monotonic "properly connected to the dev box" signal.
+      boxHasEverConnected(req.builder.id),
+      // #777: whether the builder has ever authenticated the GDS CLI (ran
+      // /builder-setup, or the box-connect bootstrap). Auto-clears the
+      // onboarding 'cli_setup' step — distinct from box_connect (#823: both
+      // steps have a place — connecting vs. signing the GDS in).
+      db.hasCliSession(req.builder.id),
+      // task 1268: the builder's behavior_prefs blob (the 'wandering' + 'render'
+      // knobs), resolved against builder.rank below so /me carries the effective
+      // level + its contract. The Conductor reads this to inject focus guidance.
+      // Through the builder-settings port (BV1.R80); {} when the module is off.
+      settings ? settings.getBuilderBehaviorPrefs(req.builder.id) : {},
+      // task 1013 / ADR 0073: does this builder have their OWN Gemini key stored
+      // (server-side, encrypted)? Drives the `needs` "image-generation key" item
+      // below — covered (newcomer) vs action-needed (Thetes+, no key) vs satisfied.
+      // Cheap single-row read; folded into the parallel fan-out.
+      // Own Gemini-key status via the art-pipeline port (ADR 0102) — the storage
+      // is art-pipeline domain now; degrades to a no-key shape on a vanilla instance.
+      seams.resolveOptional('art.getBuilderGeminiKeyRow', async () => ({ enc: null, last4: null, set_at: null }))(req.builder.id),
+    ]);
+    // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
+    // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
+    // profile banner read it without a follow-up call; the ship + art-pipeline
+    // hard-cap refusal reads the same `level`. Best-effort — a cost-status read
+    // failure must never break the profile, so it defaults to null on error.
+    let costStatus = null;
+    try {
+      costStatus = await reward.getBuilderCostStatus(req.builder.id);
+    } catch (err) {
+      console.error('[gds] GET /me cost status', err);
+    }
+    // For each active claim, compute the streak preview (cheap; pool query).
+    // Lets the CLI render "shipping this would extend streak to N days" hints.
+    const activeClaimsWithPreview = await Promise.all(
+      activeClaims.map(async (c) => {
+        const preview = await reward.wouldExtendStreak(req.builder.id, c.task_id);
+        return { ...c, streak_preview: preview };
+      })
+    );
+    const payload = {
+      builder,
+      active_claims: activeClaimsWithPreview,
+      // Legacy field — first claim only. Prefer active_claims (plural).
+      active_claim: activeClaimsWithPreview[0] ?? null,
+      est_vs_actual: estVsActual,
+      unlocked,
+      locked_with_progress: lockedWithProgress,
+      streak: {
+        current: streakInfo.current_streak,
+        longest: streakInfo.longest_streak,
+        last_ship_day: streakInfo.last_ship_day,
+        started_on: streakInfo.current_started_on,
+        timezone: streakInfo.timezone,
+        today: streakInfo.today,
+      },
+      grades: {
+        recent: recentGrades,
+        rolling: builderAvg,
+      },
+      // V3.R28 (#248): karma feed — last 10 karma_log entries for this
+      // builder. `builder.karma` is the cached total; `karma.recent` is
+      // the audit trail (deltas, reasons, granters). Empty array when
+      // the builder has no karma events yet.
+      // V3.R26 (#246): `delta_30d` is the rolling 30-day karma sum so the
+      // profile card can show a trend without a follow-up call.
+      karma: {
+        recent: recentKarma,
+        delta_30d: karma30d,
+      },
+      // V3.R75 (#294): auto-completing onboarding checklist. Always present
+      // — when the row is missing (legacy builder, no event yet) shapeForApi
+      // returns a stage-1 "nothing cleared" view so the client renders the
+      // checklist either way. Through the `onboarding` port (BV1.R81); null when
+      // the module is off.
+      onboarding: onboarding ? onboarding.shapeForApi(onboardingRow, { shipCount, discordLinked: !!discordLink, boxConnected: !!boxConnected, cliAuthed: !!cliAuthed }) : null,
+      // F7 (ADR 0033): Discord link state for the hall's Connect/Unlink UI.
+      // `configured` tells the client whether the server even has Discord OAuth
+      // creds — when false the hall renders nothing (the start route 503s).
+      discord: {
+        linked: !!discordLink,
+        configured: auth.discordConfigured(),
+      },
+      // #853 (ADR 0041): when the temporary global grader bypass is ON, ship.js
+      // skips the subagent grader and confirms directly (the /tasks/:id/confirm
+      // gate is correspondingly relaxed to any-builder server-side). Default OFF
+      // — when unset the normal grader flow + ADR 0016 trust boundary hold.
+      grader_bypass: process.env.GRADER_BYPASS_ENABLED === '1',
+      // V3.R84 (#302), criterion C3: { spend_mtd_usd, budget_mtd_usd, pct_used,
+      // level } where level is ok|warn|over. budget_mtd_usd is null when the
+      // builder is uncapped (no cap set — the default; ADR 0085), in which case
+      // level is always 'ok'. The whole object is null only if the read errored.
+      cost: costStatus,
+      // task 1268: the per-builder "wandering" knob, resolved to an effective
+      // level (clamped by rank) + its behavior contract. The Conductor + the
+      // /settings UI read this; the builder-settings port's describeWandering is
+      // the SSOT (BV1.R80). null when the prefs module is off.
+      wandering: settings ? settings.describeWandering(behaviorPrefs, builder.rank) : null,
+      // task 2010: the per-builder interaction profile (tone / technical level /
+      // toolchain familiarity), resolved to an effective profile + an injectable
+      // contract. The old §2 "The Prompter" owner-defaults, now per-builder. The
+      // session-start injection + /settings UI read this; describeInteraction is
+      // the SSOT (builder-settings port). null when the prefs module is off.
+      interaction: settings && settings.describeInteraction ? settings.describeInteraction(behaviorPrefs) : null,
+      // task 2011: the resolved subagent model allocation (main + subagent tiers),
+      // builder override → instance default (branding.models) → code default. The
+      // agent consults `effective` when spawning subagents; §2 links here.
+      model_allocation: settings && settings.describeModelAllocation
+        ? settings.describeModelAllocation(behaviorPrefs, (() => { try { return branding().models || {}; } catch { return {}; } })())
+        : null,
+      // task 1279: the per-builder "render widgets" knob (shares behavior_prefs).
+      // { widgets_enabled } tells the start/claim/ship CLIs whether to emit the
+      // rich HTML card or the cheap text fallback. No rank cap (cost/taste, not
+      // trust); default ON. The builder-settings port's describeRender is the SSOT.
+      render: settings ? settings.describeRender(behaviorPrefs) : null,
+      // task 1013 / ADR 0073: the consistent "the system needs an input from you"
+      // list. Today one item — the image-generation key — in one of three states
+      // (covered | action_needed | satisfied). The hall Standing card + the CLI
+      // session nudge render this SAME shape; the builder-settings port's
+      // computeNeeds is the SSOT (BV1.R80). [] when the prefs module is off.
+      needs: settings ? settings.computeNeeds({
+        rank: builder?.rank,
+        ownKeySet: !!(geminiKeyRow && geminiKeyRow.enc),
+        sharedKeyConfigured: artSharedKeyConfigured(),
+      }) : [],
+    };
+    // Module→core contribution seam (BV1.R42, ADR 0083). Let each enabled module
+    // add its own profile slice instead of core hardcoding it — the strangler
+    // prerequisite that lets dev-box/discord/art leave this route. ADD-ONLY (core
+    // keys win); a collision means a move task took over a core key without
+    // dropping the core copy. Empty until a module registers → byte-identical today.
+    const slices = await seams.collectContributions('profile.fields', {
+      builderId: req.builder.id, builder, req,
+    });
+    const { collisions } = seams.mergeContributions(payload, slices);
+    for (const k of collisions) {
+      console.error(`[gds] /me profile contribution tried to overwrite core key "${k}" — ignored`);
+    }
+    res.json(payload);
+  });
+
+  // Self-service edit of the authenticated builder's preferred disciplines
+  // (migrations 027 + 086 / V3.R80). Body: { preferred_disciplines: ["artist", ...] }.
+  // Valid elements are engineer|artist|ideator; [] clears the preference (a
+  // multi-element set just means several lanes). No rank gate — a builder owns their own
+  // profile. 422 invalid_discipline if any element is out of range.
+  // rank: any-builder — self-service profile edit; documented "no rank gate" in the
+  // handler comment above (a builder owns their own preference).
+  router.patch('/me/disciplines', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      preferred_disciplines: { required: true, type: 'array', maxItems: 16, itemsType: 'string' },
+    })) return;
+    const input = req.body?.preferred_disciplines;
+    if (!Array.isArray(input)) {
+      return res.fail('preferred_disciplines must be an array', 400);
+    }
+    try {
+      const builder = await db.updateBuilderDisciplines(req.builder.id, input);
+      // The onboarding state machine carved into modules/onboarding/ (BV1.R81 /
+      // ADR 0093 §1): resolve the `onboarding` kernel port for the mark + echo —
+      // never a direct require of a module. Default-on (present in prod); degrades
+      // to a null state row (shapeForApi synthesizes the "nothing cleared" view).
+      const onboardingPort = seams.resolveOptional('onboarding');
+      // Picking a craft is an onboarding milestone (the 'pick_disciplines'
+      // stage). Only a non-empty selection counts as "chosen" — clearing the
+      // preference ([]) is not a milestone. safeMarkStage is idempotent and
+      // swallows errors so onboarding plumbing never breaks the profile save.
+      if (onboardingPort && Array.isArray(input) && input.length > 0) {
+        await onboardingPort.safeMarkStage(pool, req.builder.id, 'pick_disciplines', req.builder);
+      }
+      // Echo the onboarding state back so the hall's path checklist can tick
+      // this step off without a follow-up /me round-trip.
+      const [state, shipCount, discordLink, boxConnected, cliAuthed] = await Promise.all([
+        onboardingPort ? onboardingPort.getState(pool, req.builder.id) : null,
+        lc().countShippedTasksForBuilder(req.builder.id),
+        discordIsLinked(req.builder.id),
+        boxHasEverConnected(req.builder.id),
+        db.hasCliSession(req.builder.id),
+      ]);
+      const onboarding = onboardingPort ? onboardingPort.shapeForApi(state, { shipCount, discordLinked: !!discordLink, boxConnected: !!boxConnected, cliAuthed: !!cliAuthed }) : null;
+      res.json({ builder, onboarding });
+    } catch (err) {
+      if (err.code === 'invalid_discipline') {
+        return res.fail('invalid_discipline', 422, { bad: err.bad });
+      }
+      throw err;
+    }
+  });
+
+  // V3.R10 (#235), criterion C3 — link the authed builder's Anthropic account.
+  // Body: { anthropic_email, anthropic_user_id }. Self-attestation: the builder's
+  // own Claude Code reads ~/.claude.json oauthAccount during /builder-setup,
+  // confirms the email locally (aborting setup on mismatch), then POSTs the
+  // attested pair here. anthropic_user_id (accountUuid) is stored as optional
+  // cosmetic attribution only — the X-Anthropic-User identity pin was removed
+  // (task 1039 / idea 258), so it is no longer an auth boundary.
+  //
+  // rank: any-builder — own identity attestation; same posture as /me/disciplines.
+  // A builder can only ever write their OWN row (req.builder.id), so there is no
+  // cross-builder attribution risk. 422 if email/id are missing or malformed.
+  router.post('/me/anthropic-link', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      anthropic_email: { required: true, type: 'string', minLength: 3, maxLength: 320 },
+      anthropic_user_id: { required: true, type: 'string', minLength: 1, maxLength: 128 },
+    })) return;
+    const email = String(req.body.anthropic_email).trim();
+    const userId = String(req.body.anthropic_user_id).trim();
+    if (!email.includes('@')) {
+      return res.fail('invalid_email', 422);
+    }
+    try {
+      const linked = await db.linkAnthropicAccount(req.builder.id, { email, userId });
+      res.json({ linked });
+    } catch (err) {
+      console.error('[gds] POST /me/anthropic-link', err);
+      res.fail('link_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // The builder's unlocked achievements (joined to achievement metadata).
+  // K1 (achievement evaluator) is shipped; rows here are real unlock events.
+  // rank: any-builder — own unlocked achievements.
+  router.get('/me/achievements', auth.requireBuilder, async (req, res) => {
+    const unlocked = await seams.resolveOptional('reward').getBuilderAchievements(req.builder.id);
+    res.json({ unlocked });
+  });
+
+  // Tasks this builder has shipped, most recent first.
+  // ?limit=all returns every shipped task for this builder (the /builders UI
+  // uses this to render the full "Works Wrought by Thy Hand" ledger). Numeric
+  // limits are clamped to 1..500.
+  // rank: any-builder — own shipped-task ledger.
+  router.get('/me/recent-ships', auth.requireBuilder, async (req, res) => {
+    const raw = req.query.limit;
+    const limit = String(raw).toLowerCase() === 'all'
+      ? 100000
+      : Math.min(Math.max(Number(raw) || 10, 1), 500);
+    const ships = await lc().recentShippedTasksByBuilder(req.builder.id, limit);
+    res.json({ ships });
+  });
+
+  // All seeded achievements — lets /builders render locked + unlocked side by side.
+  // rank: any-builder — global achievement catalog (locked + unlocked rendering).
+  router.get('/achievements', auth.requireBuilder, async (_req, res) => {
+    const achievements = await seams.resolveOptional('reward').listAchievements();
+    res.json({ achievements });
+  });
+
+  // The five per-builder PREFERENCE routes — /me/skill-prefs, /me/sound-prefs,
+  // /me/event-sound-prefs, /me/wandering, /me/render (GET + PATCH each) — moved to
+  // modules/builder-settings/routes/settings.js (BV1.R80 / ADR 0093 §1). They keep
+  // their exact /me/* paths (the loader mounts that router on this same /api/gds
+  // router, before the public catch-all), so the API is byte-identical. The GET
+  // /me aggregator above stays here as a thin facade resolving the
+  // `builder-settings` port for its wandering/render/needs slices (02-module-map §2).
+
+  // Art-key routes (GET/PUT/DELETE /me/art-key, GET /me/art-key/own,
+  // POST /me/art-key/storage-init) moved to modules/art-pipeline/routes/art-key.js
+  // (task 1417 / BV1.R48). Mounted by the loader when art-pipeline is enabled.
+
+  return router;
+};

package/src/bongos/routes/modules.js

@@ -0,0 +1,131 @@
+// src/gds/routes/modules.js — the hall "Modules" tab backend (ADR 0107 §9,
+// task 1776). Three jobs, matching the ADR:
+//
+//   GET  /modules              list every on-disk module: enabled state,
+//                               attribution (author/origin/license/maintainer),
+//                               and provenance (own-built vs core-loaded —
+//                               src/module-loader/provenance.js).
+//   POST /modules/:key/enable  toggle config/modules.json's instance overlay
+//                               and reload the live process (§6: default-off
+//                               respected — this only ever flips an existing
+//                               module's flag, never invents a new key).
+//   POST /modules/:key/submit  the "submit for review" front door (§1). The
+//                               submit pipeline (task 1770) hasn't landed yet,
+//                               so this is a clear 501 stub, not a fake queue —
+//                               the button lights up for real once 1770 ships.
+//
+// Read is open to any signed-in builder (same gate as the atlas/primer pages);
+// the write (enable/disable) is metic+archon, same rank as /backup/trigger —
+// it changes running behavior for the whole instance, not just the caller.
+//
+// Persistence note: this writes config/modules.json on disk and reloads the
+// in-process cache, so the effect is immediate on this box. Like any other
+// hand-edit of that file, surviving the next `git reset --hard` deploy needs
+// the change committed — this route does not auto-commit (an HTTP handler
+// auto-pushing to main bypasses the ship/grade/deploy pipeline, which the
+// project's trust boundary treats as a bigger risk than a toggle that needs a
+// human/agent to land it properly). Captured as a follow-up idea: durable
+// (DB-backed) module enablement that survives a deploy with no extra step.
+
+const express = require('express');
+const fs = require('node:fs');
+const path = require('node:path');
+const auth = require('../auth');
+const { asyncHandler, validateOrRespond } = require('./_helpers');
+const loader = require('../../module-loader/loader');
+const { deriveProvenance } = require('../../module-loader/provenance');
+const modulesLib = require('../../modules');
+
+function ownProjectName() {
+  try { return require('../../branding').branding().identity.productName; } catch { return null; }
+}
+
+function readInstanceConfig() {
+  try { return JSON.parse(fs.readFileSync(modulesLib.INSTANCE_PATH, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return { modules: {} }; throw e; }
+}
+
+function listModules() {
+  const { loaded } = loader.discoverModules();
+  const enabledSet = modulesLib.modules();
+  const own = ownProjectName();
+  return loaded.map(({ key, manifest }) => {
+    const provenance = deriveProvenance(manifest.origin, own);
+    return {
+      key,
+      title: manifest.title,
+      description: manifest.description,
+      default: manifest.default === true,
+      enabled: enabledSet[key] === true,
+      coreVersion: manifest.coreVersion,
+      contributes: manifest.contributes || {},
+      provenance,
+      author: manifest.author || null,
+      origin: manifest.origin || null,
+      license: manifest.license || null,
+      maintainer: manifest.maintainer || null,
+    };
+  }).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+module.exports = function buildModulesRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — list every on-disk module with attribution + provenance (same read gate as the atlas/primer pages).
+  router.get('/modules', auth.requireBuilder, asyncHandler('GET /modules', async (_req, res) => {
+    const all = listModules();
+    res.json({
+      modules: all,
+      own_built: all.filter((m) => m.provenance === 'own').length,
+      core_loaded: all.filter((m) => m.provenance === 'core').length,
+      submit_pipeline_live: false, // flips true once task 1770 ships
+    });
+  }));
+
+  // rank: metic+archon — toggling a module changes running behavior for the whole instance, not just the caller.
+  router.post('/modules/:key/enable', auth.requireBuilder, auth.requireRank('metic', 'archon'),
+    asyncHandler('POST /modules/:key/enable', async (req, res) => {
+      const { key } = req.params;
+      if (validateOrRespond(req, res, { enabled: {} })) return;  // boolean; enforced by the handler check below (preserves invalid_body)
+      const { enabled } = req.body || {};
+      if (typeof enabled !== 'boolean') {
+        return res.fail('invalid_body', { status: 400, message: '"enabled" must be a boolean.' });
+      }
+      const known = listModules();
+      const target = known.find((m) => m.key === key);
+      if (!target) {
+        return res.fail('not_found', { status: 404, message: `No on-disk module "${key}" — only a real modules/<key>/ can be toggled.` });
+      }
+
+      const cfg = readInstanceConfig();
+      if (!cfg.modules || typeof cfg.modules !== 'object') cfg.modules = {};
+      cfg.modules[key] = enabled;
+      fs.mkdirSync(path.dirname(modulesLib.INSTANCE_PATH), { recursive: true });
+      fs.writeFileSync(modulesLib.INSTANCE_PATH, JSON.stringify(cfg, null, 2) + '\n');
+      modulesLib.reload();
+
+      console.log(`[gds] module "${key}" ${enabled ? 'enabled' : 'disabled'} by builder ${req.builder && req.builder.id}`);
+      res.json({ ok: true, key, enabled, note: 'Live on this box now. Persisting past the next deploy needs config/modules.json committed.' });
+    }));
+
+  // rank: metic+archon — the "submit this module for review" front door (501 until the submit pipeline, task 1770, ships).
+  router.post('/modules/:key/submit', auth.requireBuilder, auth.requireRank('metic', 'archon'),
+    asyncHandler('POST /modules/:key/submit', async (req, res) => {
+      const { key } = req.params;
+      const known = listModules();
+      if (!known.find((m) => m.key === key)) {
+        return res.fail('not_found', { status: 404, message: `No on-disk module "${key}".` });
+      }
+      res.fail('not_yet_available', {
+        status: 501,
+        message: 'The module-submit pipeline (bongos module submit → core review queue) is not live yet — tracked by task 1770 (ADR 0107 §8/§9). This front door will call straight through once it ships.',
+      });
+    }));
+
+  return router;
+};
+
+// Exposed for tests (tests/module_provenance.mjs) — pure-ish (fs + the loader's
+// own disk scan, no DB), so it's safe to require directly outside an Express
+// request cycle, the same way tests/atlas.mjs requires gen-atlas.js's builders.
+module.exports.listModules = listModules;

package/src/bongos/routes/optimizer.js

@@ -0,0 +1,54 @@
+const express = require('express');
+const auth = require('../auth');
+const optimizer = require('../optimizer');
+const { validateOrRespond } = require('./_helpers');
+
+module.exports = function buildOptimizerRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — pick own next work; the optimizer reads/recommends only.
+  router.post('/session/optimize', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      mode: { type: 'string', maxLength: 64 },
+      // time_budget_min / max_parallel can come in as number OR string from
+      // the web UI — leave Number() coercion inline; just enforce sane shape.
+      // Declared untyped so strict-mode (R11/#1998) accepts either form.
+      time_budget_min: {},
+      max_parallel: {},
+    })) return;
+    const body = req.body || {};
+    const mode = body.mode;
+    const timeBudgetMin = Number(body.time_budget_min);
+    const maxParallel = body.max_parallel != null ? Number(body.max_parallel) : optimizer.DEFAULT_MAX_PARALLEL;
+
+    if (!optimizer.VALID_MODES.includes(mode)) {
+      return res.fail('bad_mode', 400, { valid_modes: optimizer.VALID_MODES });
+    }
+    if (!Number.isFinite(timeBudgetMin) || timeBudgetMin <= 0) {
+      return res.fail('bad_time_budget_min', 400);
+    }
+    if (!Number.isFinite(maxParallel) || maxParallel <= 0) {
+      return res.fail('bad_max_parallel', 400);
+    }
+    try {
+      const result = await optimizer.optimizeSession({
+        builderId: req.builder.id,
+        mode,
+        timeBudgetMin,
+        maxParallel,
+      });
+      res.json(result);
+    } catch (err) {
+      if (err && err.code === 'BAD_MODE') {
+        return res.fail('bad_mode', 400, { valid_modes: err.validModes });
+      }
+      if (err && err.code === 'BAD_TIME_BUDGET') {
+        return res.fail('bad_time_budget_min', 400);
+      }
+      console.error('[gds] POST /session/optimize', err);
+      res.fail('optimize_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};