@bongos/core 1.19.360 → 1.19.362

package/docs/copy-registry.json

@@ -1025,7 +1025,7 @@
       "occurrences": 2,
       "at": [
         "modules/hall-ui/public/gate.js:205",
-        "modules/hall-ui/public/government.js:842"
+        "modules/hall-ui/public/government.js:859"
       ]
     },
     {
@@ -1608,7 +1608,7 @@
       "surface": "builders-hall",
       "text": ", membership",
       "file": "modules/hall-ui/public/government.js",
-      "line": 786,
+      "line": 803,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -1932,7 +1932,7 @@
       "surface": "builders-hall",
       "text": "An objection returns the idea to its author with your reason and the section it faults \\u2014 the feedback they revise against.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 741,
+      "line": 758,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2103,7 +2103,7 @@
       "surface": "builders-hall",
       "text": "As configuration:",
       "file": "modules/hall-ui/public/government.js",
-      "line": 633,
+      "line": 650,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2148,7 +2148,7 @@
       "surface": "builders-hall",
       "text": "Assigned {…} to builder {…}.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 401,
+      "line": 408,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -2373,7 +2373,7 @@
       "surface": "builders-hall",
       "text": "Cast objection",
       "file": "modules/hall-ui/public/government.js",
-      "line": 741,
+      "line": 758,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2436,7 +2436,7 @@
       "surface": "builders-hall",
       "text": "Charter library",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2679,7 +2679,7 @@
       "surface": "builders-hall",
       "text": "Closed sittings",
       "file": "modules/hall-ui/public/government.js",
-      "line": 812,
+      "line": 829,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -3003,7 +3003,7 @@
       "surface": "builders-hall",
       "text": "Could not assign: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 406,
+      "line": 413,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3093,7 +3093,7 @@
       "surface": "builders-hall",
       "text": "Could not create rank: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 386,
+      "line": 393,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3129,7 +3129,7 @@
       "surface": "builders-hall",
       "text": "Could not load government data just now.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 883,
+      "line": 901,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -3201,7 +3201,7 @@
       "surface": "builders-hall",
       "text": "Could not load the Board Room just now.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 804,
+      "line": 821,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -3210,7 +3210,7 @@
       "surface": "builders-hall",
       "text": "Could not load the constitution just now.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 628,
+      "line": 645,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -3363,7 +3363,7 @@
       "surface": "builders-hall",
       "text": "Could not remove: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 314,
+      "line": 321,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3390,7 +3390,7 @@
       "surface": "builders-hall",
       "text": "Could not reset: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 253,
+      "line": 260,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3633,7 +3633,7 @@
       "surface": "builders-hall",
       "text": "Could not vote: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 768,
+      "line": 785,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3651,7 +3651,7 @@
       "surface": "builders-hall",
       "text": "Could not {…}: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 266,
+      "line": 273,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3678,7 +3678,7 @@
       "surface": "builders-hall",
       "text": "Create a custom rank first.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 397,
+      "line": 404,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -3714,7 +3714,7 @@
       "surface": "builders-hall",
       "text": "Created rank {…}.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 380,
+      "line": 387,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -4326,7 +4326,7 @@
       "surface": "builders-hall",
       "text": "Full Idea",
       "file": "modules/hall-ui/public/government.js",
-      "line": 669,
+      "line": 686,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4596,7 +4596,7 @@
       "surface": "builders-hall",
       "text": "How a project moves between structures over time — summarized from the synthesis:",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4614,7 +4614,7 @@
       "surface": "builders-hall",
       "text": "How it has changed",
       "file": "modules/hall-ui/public/government.js",
-      "line": 633,
+      "line": 650,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4677,7 +4677,7 @@
       "surface": "builders-hall",
       "text": "How this project is governed — the constitution it runs, the Board Room, and the ranks & permissions that administer it.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 870,
+      "line": 888,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -5703,7 +5703,7 @@
       "surface": "builders-hall",
       "text": "No custom ranks yet",
       "file": "modules/hall-ui/public/government.js",
-      "line": 303,
+      "line": 310,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5775,7 +5775,7 @@
       "surface": "builders-hall",
       "text": "No machine principals declared.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 325,
+      "line": 332,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5811,7 +5811,7 @@
       "surface": "builders-hall",
       "text": "No rank assignments yet.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 277,
+      "line": 284,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5838,7 +5838,7 @@
       "surface": "builders-hall",
       "text": "No sitting has closed yet.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 813,
+      "line": 830,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5892,7 +5892,7 @@
       "surface": "builders-hall",
       "text": "No votes yet{…}.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 687,
+      "line": 704,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -6454,6 +6454,15 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
+    {
+      "id": "e1e10dc5e357",
+      "surface": "builders-hall",
+      "text": "Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.",
+      "file": "modules/hall-ui/public/government.js",
+      "line": 872,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "2ec5f77eb6f0",
       "surface": "builders-hall",
@@ -6652,15 +6661,6 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
-    {
-      "id": "084261c45654",
-      "surface": "builders-hall",
-      "text": "Ranks & Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.",
-      "file": "modules/hall-ui/public/government.js",
-      "line": 854,
-      "origin": "js-markup",
-      "confidence": "certain"
-    },
     {
       "id": "6824ec470f99",
       "surface": "builders-hall",
@@ -6918,7 +6918,7 @@
       "surface": "builders-hall",
       "text": "Removed {…} from builder {…}.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 310,
+      "line": 317,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -7062,7 +7062,7 @@
       "surface": "builders-hall",
       "text": "Reset to default",
       "file": "modules/hall-ui/public/government.js",
-      "line": 217,
+      "line": 224,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -7080,7 +7080,7 @@
       "surface": "builders-hall",
       "text": "Reset {…} to its default permissions?\\n\\nEvery change you've made to this rank is discarded, and it takes effect for every builder at this rank on their next request.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 245,
+      "line": 252,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -7107,7 +7107,7 @@
       "surface": "builders-hall",
       "text": "Restricted.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 842,
+      "line": 859,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -7404,7 +7404,7 @@
       "surface": "builders-hall",
       "text": "Selectable today",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8016,7 +8016,7 @@
       "surface": "builders-hall",
       "text": "The developmental ladder: {…}. Formality is adopted only where informal coordination breaks.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 616,
+      "line": 633,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8187,7 +8187,7 @@
       "surface": "builders-hall",
       "text": "The seven government structures, for getting a team up to speed before deciding when to flip a switch.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8412,7 +8412,7 @@
       "surface": "builders-hall",
       "text": "This is your idea \\u2014 its author does not vote on it. The board decides; a return comes back to you with its reason.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 737,
+      "line": 754,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8637,7 +8637,7 @@
       "surface": "builders-hall",
       "text": "Vote yes",
       "file": "modules/hall-ui/public/government.js",
-      "line": 741,
+      "line": 758,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8781,7 +8781,7 @@
       "surface": "builders-hall",
       "text": "What this project runs today",
       "file": "modules/hall-ui/public/government.js",
-      "line": 633,
+      "line": 650,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8889,7 +8889,7 @@
       "surface": "builders-hall",
       "text": "Why \\u2014 the reason the author will act on",
       "file": "modules/hall-ui/public/government.js",
-      "line": 741,
+      "line": 758,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9060,7 +9060,7 @@
       "surface": "builders-hall",
       "text": "You have not voted on this item. Casting arrives with the vote form.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 785,
+      "line": 802,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9087,7 +9087,7 @@
       "surface": "builders-hall",
       "text": "You voted",
       "file": "modules/hall-ui/public/government.js",
-      "line": 784,
+      "line": 801,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9402,7 +9402,7 @@
       "surface": "builders-hall",
       "text": "active builder{…}: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9483,7 +9483,7 @@
       "surface": "builders-hall",
       "text": "as configuration: {…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 604,
+      "line": 621,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9573,7 +9573,7 @@
       "surface": "builders-hall",
       "text": "cannot be read, so",
       "file": "modules/hall-ui/public/government.js",
-      "line": 482,
+      "line": 499,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9627,7 +9627,7 @@
       "surface": "builders-hall",
       "text": "documented for later",
       "file": "modules/hall-ui/public/government.js",
-      "line": 602,
+      "line": 619,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9690,7 +9690,7 @@
       "surface": "builders-hall",
       "text": "first vote",
       "file": "modules/hall-ui/public/government.js",
-      "line": 500,
+      "line": 517,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9933,7 +9933,7 @@
       "surface": "builders-hall",
       "text": "ladder · read-only",
       "file": "modules/hall-ui/public/government.js",
-      "line": 116,
+      "line": 123,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9978,7 +9978,7 @@
       "surface": "builders-hall",
       "text": "means expressible through the real configuration — a rank-based membership plus a pass rule — with no new code. This project has",
       "file": "modules/hall-ui/public/government.js",
-      "line": 610,
+      "line": 627,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10050,7 +10050,7 @@
       "surface": "builders-hall",
       "text": "no clock",
       "file": "modules/hall-ui/public/government.js",
-      "line": 510,
+      "line": 527,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10113,7 +10113,7 @@
       "surface": "builders-hall",
       "text": "objected to",
       "file": "modules/hall-ui/public/government.js",
-      "line": 694,
+      "line": 711,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10203,7 +10203,7 @@
       "surface": "builders-hall",
       "text": "or above",
       "file": "modules/hall-ui/public/government.js",
-      "line": 494,
+      "line": 511,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10257,7 +10257,7 @@
       "surface": "builders-hall",
       "text": "recommended at your headcount",
       "file": "modules/hall-ui/public/government.js",
-      "line": 603,
+      "line": 620,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10311,7 +10311,7 @@
       "surface": "builders-hall",
       "text": "selectable today",
       "file": "modules/hall-ui/public/government.js",
-      "line": 601,
+      "line": 618,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10356,7 +10356,7 @@
       "surface": "builders-hall",
       "text": "tally: {…} yes · {…} no — sitting under",
       "file": "modules/hall-ui/public/government.js",
-      "line": 786,
+      "line": 803,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10590,7 +10590,7 @@
       "surface": "builders-hall",
       "text": "your vote",
       "file": "modules/hall-ui/public/government.js",
-      "line": 691,
+      "line": 708,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10689,7 +10689,7 @@
       "surface": "builders-hall",
       "text": "{…} minutes",
       "file": "modules/hall-ui/public/government.js",
-      "line": 515,
+      "line": 532,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10770,7 +10770,7 @@
       "surface": "builders-hall",
       "text": "{…} proposed",
       "file": "modules/hall-ui/public/government.js",
-      "line": 527,
+      "line": 544,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10779,7 +10779,7 @@
       "surface": "builders-hall",
       "text": "{…} reset to its default {…} permissions.",
       "file": "modules/hall-ui/public/government.js",
-      "line": 249,
+      "line": 256,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -10914,7 +10914,7 @@
       "surface": "builders-hall",
       "text": "{…} · via rank",
       "file": "modules/hall-ui/public/government.js",
-      "line": 287,
+      "line": 294,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10995,7 +10995,7 @@
       "surface": "builders-hall",
       "text": "· {…} permission{…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 125,
+      "line": 132,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -11103,7 +11103,7 @@
       "surface": "builders-hall",
       "text": "— {…}{…}",
       "file": "modules/hall-ui/public/government.js",
-      "line": 605,
+      "line": 622,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/file-map.md

@@ -45,6 +45,7 @@
 │   │   └── 0001…0120-*.md       ← 133 ADR files (a handful of numbers collide — see README.md's disambiguation note; README.md has the live list)
 │   ├── architecture.md          ← §10 detail: live infra, app stack, DB schema, Bongos API (split out V3.R86)
 │   ├── canonical-permissions.md ← rank ladder + trust boundary reference (read-only mirror; DB enforces)
+│   ├── code-conventions.md      ← ADR 0095 (task 1001654): the doc-comment convention — every module a header, every public symbol a line, saying WHAT it does and WHY it exists. The findability layer agents grep. Advisory only; the nudge is scripts/gds/doc-comment-coverage.js
 │   ├── design/                  ← game design docs (V2 visual redesign cluster)
 │   │   ├── container-exterior.md ← (#641) container building exterior: two-storey stacked-container structure, glass facade, deck, rooftop
 │   │   └── container-interior.md ← (#645) container building interior: layered industrial shell + aqua wave floor + boutique display; palette reconciled to ADR 0044
@@ -180,6 +181,7 @@
 │       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`
+│       ├── doc-comment-coverage.js ← ADR 0095 / task 1001654: the ADVISORY doc-comment nudge (fitness Check 28) — reports source files under src/·scripts/·modules/ that open with no module header. Never hard-fails: a doc-comment gate that blocks a ship buys filler prose, and making it blocking needs owner sign-off + its own ADR. CRLF-safe (unlike docs-entropy.js); an empty enumeration throws as a scan defect
 │       ├── copy-inventory.js  ← R01 of goal 1000074 (the artist's loop): the COPY REGISTRY — every user-facing string across the hall / status / landing surfaces, each row naming the render path that shows it (html-text · html-attr · js-markup · js-notice · js-text-assign) + a stable id that survives a move. Writes docs/copy-registry.json + docs/copy-inventory.md; `--check` fails on drift. Precision over recall: a JS literal with no render path is not listed
 │       ├── gen-diagrams.js      ← generates the 5 onboarding diagrams (`.mmd`/`.svg`/`.png` + `assertions.json`) from templates in this file — never hand-edit a `.mmd`/assertions.json; runs on deploy
 │       ├── gen-api-docs.js      ← ADR 0109: generates `docs/api/openapi.json` + `docs/api-reference.md` from the live route files via `route-rank-check.js` introspection, so the API reference cannot drift from what the server actually mounts

package/modules/autonomy/routes/autonomy.js

@@ -1,3 +1,22 @@
+// modules/autonomy/routes/autonomy.js — GET /autonomy/precheck: should an
+// autonomous run start at all? (ADR 0095 backfill).
+//
+// WHY. The nightly routines boot real models that spend real money, so the
+// go/no-go decision must be made BEFORE any model starts — and must itself be
+// free. This is Step 0 of the Multi-Agent System (ADR 0024, System 3): a $0
+// deterministic gate over live signals (is there claimable work, is there budget
+// left, has anything actually changed since the last `go`), exposed over HTTP so
+// an operator can ask the same question the cron asks.
+//
+// TWO SAFETY PROPERTIES worth preserving: it is INERT until `OTB_AUTONOMY_ENABLED=1`
+// (an un-armed instance always answers `go`, so nothing here can start work by
+// accident), and it is Archon-gated, because the answer decides autonomous spend.
+//
+// The decision logic is not here — it lives in the gate CLI
+// `scripts/gds/autonomy-gate.js`, deliberately OUTSIDE the module boundary, since
+// gathering signals means reading ideas/economy/lifecycle, which a modules/ file
+// may not do. This route is a thin wrapper over its `precheck`.
+
 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).

package/modules/dev-box/app/src/config.js

@@ -1,4 +1,16 @@
-// devbox-app/src/config.js — runtime configuration resolution.
+// modules/dev-box/app/src/config.js — where the desktop app decides which server
+// it is talking to, and what version of itself it is (ADR 0095 backfill).
+//
+// WHY. The tray app ships as a built artifact to builders' machines, so it cannot
+// be configured by editing a file next to it — yet it still has to point at a dev
+// or staging API during development, and at the origin a builder actually signed
+// in to afterwards. `apiBase` resolves that in a fixed precedence (explicit env →
+// the base recorded in the session file at sign-in → the branded production
+// default) so a developer override is possible without ever overriding a real
+// builder's session.
+//
+// The production default comes from `./brand`, which is GENERATED from the
+// instance's branding at build time — this file must not hardcode an origin.
 
 const brand = require('./brand');
 

package/modules/economy/achievements.js

@@ -1,5 +1,26 @@
 'use strict';
 
+// modules/economy/achievements.js — what a builder has unlocked, and the reads that
+// display it (ADR 0095 backfill).
+//
+// WHY. Credits pay for work; achievements recognise SHAPES of work that a
+// per-task payout cannot see — a streak sustained, a first ship, a change that
+// removed more than it added. They are the gamification half of the economy.
+//
+// THE ONE STRUCTURAL RULE, and the reason the evaluators look the way they do:
+// an unlock must be ATOMIC with the thing that earned it. Each `evaluateAfter*`
+// therefore takes the CALLER'S transaction `client` as its first argument and runs
+// inside the lifecycle's existing `withTx` — it never opens its own. A separate
+// transaction could commit an unlock for a ship that then rolled back, or drop one
+// for a ship that succeeded. Callers reach these through the `reward` kernel port,
+// never by importing this file (core may not require a module — ADR 0093).
+//
+// The GETTER slice below (`listAchievements`, `getBuilderAchievements`,
+// `getLeaderboardWithAchievements`, `getLockedAchievementsProgress`,
+// `renderProgressText`) is the opposite posture: plain reads for the hall and the
+// public leaderboard, reaching the shared pool through the doorway rather than a
+// caller's tx.
+
 const { SUBTRACTOR_THRESHOLD } = require('./policy');
 
 // Achievement evaluation — runs inside existing DB transactions so unlocks

package/modules/economy/routes/cost.js

@@ -1,3 +1,19 @@
+// modules/economy/routes/cost.js — POST /cost: record what a session actually spent
+// (ADR 0095 backfill).
+//
+// WHY. Builder pay is cost-plus (ADR 0054: `round(true_cost_usd × 1.20)`), so the
+// cost ledger is not telemetry — it is the input to real money. A session that
+// fails to log its spend under-pays its builder and under-states the project's
+// burn; one that logs twice over-pays. That is why the write is IDEMPOTENT: a
+// retried or resumed ship must not book the same spend again.
+//
+// This route is only the doorway; `../cost.js` owns `logCost` and is the single
+// writer to `cost_log`. Keep it that way — a second writer is how two sources of
+// truth for money start.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; `../cost` is an intra-module sibling.
+
 const express = require('express');
 // Carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2): auth gates + request
 // validators reach through the published doorway; the cost_log writer is an