@bongos/core 1.19.1075 → 1.19.1077

package/docs/modules-contract.md

@@ -1,7 +1,7 @@
 # The module plugin-API contract (`src/module-api.js` + `modules/*/`)
 
 > **Decision record:** [ADR 0083](adr/0083-modular-architecture-strangler-build-plan.md) — the build plan.
-> **Live state:** the shipped modules under `modules/` are the four feature modules `dev-box`, `game`, `discord`, `art-pipeline` (+ `character-anim`, declaration-only; ADR 0088) and the carved core-domain modules `memory` (R72), `grading` (R73), `economy` (R77), `ideas` (R78), `security` (R79), `builder-settings` (R80), `onboarding` (R81), and `sessions` (R82) — see [ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) for the remaining carve sequence.
+> **Live state:** the shipped modules under `modules/` are the three feature modules `game`, `discord`, `art-pipeline` (+ `character-anim`, declaration-only; ADR 0088) and the carved core-domain modules `memory` (R72), `grading` (R73), `economy` (R77), `ideas` (R78), `security` (R79), `builder-settings` (R80), `onboarding` (R81), and `sessions` (R82) — see [ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) for the remaining carve sequence.
 > **Author a new module:** jump to [the module-author recipe](#module-author-recipe).
 
 The module system turns optional features into self-contained directories. Adding a feature is "drop `modules/<key>/`"; the loader discovers, validates, and mounts it — no core file changes. The **one-way rule** is the load-bearing invariant:
@@ -19,7 +19,7 @@ Two fitness checks enforce it on every build — a violation is a red CI gate, n
 ## The cut: core vs modules
 
 - **Core** is the trust kernel + the lifecycle state machine + the domains not yet carved: auth/identity/audit/rank (the kernel, [ADR 0091](adr/0091-bounding-the-kernel-and-db-carve.md) §1), the lifecycle (tasks, claims, versions, done-when, ship — never split), and the still-core domains (autonomy/MAS, the two web UIs) plus always-on infra (analytics, audit-log, gate-approvals, healthz, public). The remaining tranche-2 domains carve out per [ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1; the lifecycle stays core. (Sessions/BFG — the `session_records` corpus + data plane + the BFG scorer + session-pulse — carved to `modules/sessions/` at R82; like `memory` it registers no port and core never calls back in. The per-claim `session_logs` ship LOG + `builder_sessions` auth tokens stay core.)
-- **Modules** are optional features an instance turns on via `config/modules.json` or env (the feature modules `dev-box`, `game`, `discord`, `art-pipeline`, `character-anim`), plus the **core-domain modules** that are `default: true` (always on unless disabled): `memory` (R72), `grading` (R73), `economy` — credits/cost/streaks/achievements/leaderboard (R77), `ideas` — inbox/capture/triage/blockers (R78), `security` — red-team reports + bounty (R79), `builder-settings` — wandering/skill/sound/render prefs + builder-needs (R80), `onboarding` — admission/onboarding-state/newcomer-restock (R81), and `sessions` — session_records corpus + BFG + session-pulse (R82). Each is a self-contained directory under `modules/<key>/`.
+- **Modules** are optional features an instance turns on via `config/modules.json` or env (the feature modules `game`, `discord`, `art-pipeline`, `character-anim`), plus the **core-domain modules** that are `default: true` (always on unless disabled): `memory` (R72), `grading` (R73), `economy` — credits/cost/streaks/achievements/leaderboard (R77), `ideas` — inbox/capture/triage/blockers (R78), `security` — red-team reports + bounty (R79), `builder-settings` — wandering/skill/sound/render prefs + builder-needs (R80), `onboarding` — admission/onboarding-state/newcomer-restock (R81), and `sessions` — session_records corpus + BFG + session-pulse (R82). Each is a self-contained directory under `modules/<key>/`.
 
 ---
 
@@ -34,7 +34,7 @@ The **only** core file a module may `require`. It re-exports the kernel capabili
 | `allowBoxScope` | **Deprecated no-op** (task 1003894): the narrowing session scope it opted a route into was retired, and a session of an undeclared source is now denied on every route regardless. Kept so the doorway loses no export inside 1.x; drop at the next MAJOR. |
 | `pool` | The shared Postgres pool. A module owns its `<key>_*` tables via its migrations. |
 | `instanceDbName` | The resolved DB name (from branding). |
-| `db` | Kernel-managed DB helpers (`getBuilderById`, `setBuilderBoxBlocked`, `getBuilderGeminiKeyRow`, `setBuilderGeminiKey`, `clearBuilderGeminiKey`, `insertAuditLog`, `createTask`). Grow this additive-only. |
+| `db` | Kernel-managed DB helpers (`getBuilderById`, `getBuilderGeminiKeyRow`, `setBuilderGeminiKey`, `clearBuilderGeminiKey`, `insertAuditLog`, `createTask`). Grow this additive-only. |
 | `branding` | The branding contract resolver — the resolved instance strings. |
 | `instanceConfig` | Module enablement config + env override resolution. |
 | `seams` | The seam registry (`registerProvider`, `hasProvider`, `resolve`, `resolveOptional`, `emit`, `on`) — how modules cooperate without importing each other. |
@@ -76,12 +76,12 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
 
 ```jsonc
 {
-  "key":         "dev-box",           // REQUIRED. ^[a-z][a-z0-9-]*$ — must match the dir name.
-  "title":       "Dev boxes",         // REQUIRED. Human label.
+  "key":         "discord",           // REQUIRED. ^[a-z][a-z0-9-]*$ — must match the dir name.
+  "title":       "Discord",           // REQUIRED. Human label.
   "description": "…",                 // REQUIRED. One sentence.
   "version":     "1.0.0",             // REQUIRED. The module's OWN exact version "X.Y.Z" (not a range) —
                                       //   what update, rollout channels and re-assessment name (task 1003781).
-  "coreVersion": "^1.2.0",           // REQUIRED. semver range of CORE_VERSION this module supports.
+  "coreVersion": "^1.4.0",           // REQUIRED. semver range of CORE_VERSION this module supports.
   "default":     false,               // OPTIONAL (default false). Fail-safe when no config names it.
   "author":      "…",                 // OPTIONAL. Attribution (ADR 0107 §2) — portable, not a cross-Bongos FK.
   "origin":      "…",                 // OPTIONAL. Origin instance/project this module was built in.
@@ -95,12 +95,12 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
     "note":        "…"                //   OPTIONAL. The path out, in one sentence.
   },
   "contributes": {                    // REQUIRED object (may be empty {}).
-    "routes":      ["box"],           //   route-factory files in routes/ (one export = () => Router())
+    "routes":      ["discord"],       //   route-factory files in routes/ (one export = () => Router())
     "rooms":       ["WorldRoom"],     //   Colyseus room classes (game module only)
-    "pollers":     ["box-lifecycle"], //   background pollers (start/stop lifecycle)
+    "pollers":     ["discord-bot"],   //   background pollers (start/stop lifecycle)
     "disciplines": ["artist"],        //   builder disciplines this module adds
     "skills":      ["otb-tile-generate"], // slash-command skills it ships
-    "uiSections":  ["boxes"],         //   hall/status UI sections gated by window.__MODULES__. Ship public/hall-widget.js
+    "uiSections":  ["task-where"],    //   hall/status UI sections gated by window.__MODULES__. Ship public/hall-widget.js
                                       //   and it is injected into the hall index; ship public/task-widget.js and it
                                       //   is injected into a task's page before task.js, to fill #task-contrib on
                                       //   `otb:task-shown` (task 1004301). The page itself names no module.
@@ -109,7 +109,7 @@ Every module must have a `module.json` at its root (`modules/<key>/module.json`)
                                                             // apex root (ADR 0218). One or the other, never both.
     "migrations":  true               //   true → modules/<key>/migrations/*.sql applied if enabled
   },
-  "provides": ["box.hasEverConnected"], // OPTIONAL. Seam PORTS this module registers a provider for.
+  "provides": ["discord.isLinked"],     // OPTIONAL. Seam PORTS this module registers a provider for.
   "consumes": [],                       // OPTIONAL. Seam ports this module resolves (required caps).
   "prerequisites": { "modules": [] },   // OPTIONAL. Other modules that must be enabled first.
   "spend": { "requiresPayer": true },   // OPTIONAL. This module spends MONEY for whoever calls it.
@@ -196,7 +196,7 @@ The loader is safe-by-construction: with no `modules/` dir it returns empty and
 env override  →  config/modules.json  →  config/modules.neutral.json  →  manifest.default (false)
 ```
 
-Env override key: `<envPrefix>_MODULE_<NAME>` (`NAME` = upper-snake of the key; `dev-box` → `DEV_BOX`). Example: `OTB_MODULE_DISCORD=0`.
+Env override key: `<envPrefix>_MODULE_<NAME>` (`NAME` = upper-snake of the key; `npm-release` → `NPM_RELEASE`). Example: `OTB_MODULE_DISCORD=0`.
 
 A fresh instance with **no** config resolves to **vanilla**: every module off (fail-to-vanilla).
 
@@ -218,7 +218,6 @@ A module calls `api.seams.emit(eventName, payload)` to broadcast. Any module tha
 
 | Port / Event | Provider | Consumer(s) | Contract |
 |---|---|---|---|
-| Port: `box.hasEverConnected` | `dev-box` | core `routes/me.js`, `routes/builders.js` | `(builderId) → Promise<bool>` — whether the builder's box has ever connected. Core reads via `resolveOptional(…, async () => false)` so onboarding degrades cleanly on a box-less instance. |
 | Port: `game.staticRoot` | `game` | `server.js` static-serve | `() → string` — absolute path to the game's static root. |
 | Port: `game.registerRooms` | `game` | `server.js` Colyseus setup | `(matchMaker) → void` — registers WorldRoom + QueueRoom. |
 | Port: `game.precreateWorldRoom` | `game` | `server.js` pre-create step | `(matchMaker) → Promise<void>` — pre-creates the singleton room. |
@@ -230,7 +229,6 @@ A module calls `api.seams.emit(eventName, payload)` to broadcast. Any module tha
 | Port: `security` | `security` (R79) | core `routes/public.js` (`/public/bounty-table`) | `{ bountyTableDetailed(), bountyTable() }` — the env-aware red-team bounty payout schedule. Core reads via `resolveOptional('security').bountyTableDetailed()` instead of importing the module (security is default-on; only <redacted> moved — [ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1, [02-module-map §5](design/modular-architecture/02-module-map.md)). |
 | Port: `builder-settings` | `builder-settings` (R80) | core `routes/me.js` (`GET /me`) + `cascade-dispatch.js` | `{ getBuilderBehaviorPrefs, describeWandering, describeRender, computeNeeds, skillCeiling }` — the per-builder prefs read surface. The `GET /me` aggregator resolves it for its wandering/render/needs slices; the dormant cascade router for the skill ceiling. Default-on; degrades gracefully when off ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1, [02-module-map §2](design/modular-architecture/02-module-map.md)). |
 | Port: `onboarding` | `onboarding` (R81) | the lifecycle (`db.js` claim/ship — transaction-participant `markStage`) + `auth.js` + `routes/me.js`/`builders.js`/`tasks.js`/`claims.js` | `{ getState, shapeForApi, safeMarkStage, markStage, broadcastGraduation, restockForClaim, restockAll, SOURCE_TAG }` — the onboarding state-machine + newcomer-restock surface. The FIRST core→module port the lifecycle ticks inside its own txn (alongside `reward`). Default-on; degrades to best-effort no-ops when off ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1). |
-| Event: `builder.box-reconcile-needed` | core `db.js` (on rank change / deactivate / auto-graduation) | `dev-box` | `{ builderId, rank, status, actor }` — flags the box for reconciliation. |
 | Event: `builder.secrets-scrub-needed` | core `db.js` (`deactivateBuilder`) | `art-pipeline` (when installed) | `{ builderId, actor }` — task 1003338 / [ADR 0332](adr/0332-offboarding-secret-scrub-semantics.md): best-effort teardown port for a MODULE-owned builder-keyed secret (today: the Gemini BYOK key, `gemini_key_enc`/`last4`/`set_at`). Core does not write those columns directly (ADR 0102) — the module listens and clears its own store. `github_oauth_tokens` (core-owned) is deleted synchronously inside `deactivateBuilder`'s transaction instead, no event needed. |
 
 ---
@@ -264,7 +262,6 @@ Rules (enforced by the `BV1.R45` fitness check):
 
 | Module | `contributes` | Seam ports | `coreVersion` |
 |---|---|---|---|
-| **`dev-box`** | routes: `box`; pollers: `box-lifecycle`; uiSections: `boxes` | provides `box.hasEverConnected`; listens `builder.box-reconcile-needed` | `^1.2.0` |
 | **`game`** | routes: `game`; rooms: `WorldRoom`/`QueueRoom` | provides `game.staticRoot`, `game.registerRooms`, `game.precreateWorldRoom` | `^1.4.0` |
 | **`discord`** | routes: `discord`, `bug-attachments`; pollers: `discord-bot` | provides `discord.isLinked`; consumes `ideas.capture` | `^1.4.0` |
 | **`art-pipeline`** | routes: `art-key`; disciplines: `artist`; skills: `otb-tile-generate` etc.; uiSections: `art` | provides `art.sharedKeyConfigured` | `^1.3.0` |