@bongos/core 1.21.4 → 1.21.5

package/docs/adr/0362-the-governor-docket-is-collected-from-contributed-sources.md

@@ -0,0 +1,34 @@
+# ADR 0362 — The governor's docket is collected from sources each module contributes, scoped by each source's own atom
+
+- **Status:** Accepted.
+- **Date:** 2026-10-01
+- **Task:** [task 1004523](https://cloudbongos.com/builders#/task/1004523) (goal 1000125, the Governor City).
+- **Builds on:** [ADR 0083](0083-modular-architecture-strangler-build-plan.md) (a module never requires a sibling), [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) (authority is resolved server-side, per request), [ADR 0151](0151-governance-permissions-as-atom-ranks-as-roles.md) (permissions are the atom).
+
+## Context
+
+The Governor City (docs/design/mocks/governor-city/) draws every part of a project's government as a building, with a pin over each open matter, a per-viewer state (needs you, moving, settled) and six readings on the street. Five screen tasks (1004524 to 1004528) all need the same answer to "what is open, where does it stand, and whose move is it".
+
+The matters live in a dozen places owned by five modules and the core: the board (government), blockers (ideas), access requests (onboarding), override requests, removal proposals, criteria awaiting UAT, CI gate approvals and goal join requests (lifecycle), red-team reports (security), the Autobongos fence (autonomy), and the core update (core). Before this, the only cross-source summary was the hall's "Needs your attention" card fetching five endpoints one by one.
+
+Three shapes were open. (a) A core route requiring each module's db: forbidden, core imports no module. (b) A new port per source, resolved by government: twelve ports, each a second surface to keep in step with its list route. (c) The existing `seams.contribute` contribution point, which `/me` already uses for `profile.fields`.
+
+## Decision
+
+**D1 — One contribution point, `governor.docket`.** Each owner contributes its own source from its route factory (the boot hook that runs live and in every test that rebuilds the router), built on the db read its own list route already serves. Where that read was inline in a handler, it was lifted into a function the route and the docket now share (`listAccessRequests`, `listAwaitingGateApprovals`), so there is still one query. `modules/government/docket.js` collects them; `GET /government/docket` serves the result.
+
+**D2 — Each source declares the atom of its own list route, and the collector enforces it.** A contribution carries `gate: { permission }` or `gate: { anyBuilder: true }` (for reads that scope themselves, like a goal lead's join requests, or are public, like blockers). The collector resolves the viewer's permissions once per request and runs a source only when its gate passes. A gated-out source reports `not_yours` and returns no rows. A contribution with no recognisable gate is dropped, never run. `tests/governor_docket.mjs` reads each list route's atom off the route source with the route-rank auditor and asserts the contribution names the same one, so the two cannot drift.
+
+**D3 — Nothing is invented.** A source the design names that nothing records yet (grade appeals, proposals for new standing rules, spending votes) is reported `coming` with a reason; a source whose module is off is `off`; a read that throws or does not answer within four seconds is `unavailable`. None contributes a row.
+
+**D3a — Each reading is answered by the one record that honestly carries it.** Flow: finished tasks at `completed`/`confirmed` and the longest wait (lifecycle). Promises: the building version's done-when criteria, kept of total (lifecycle). Money: the only budget the project records is the unattended-spend ceiling the autonomy gate brakes on, so "money left" is that ceiling minus the month's unattended spend, and the line says so (autonomy, gated `autonomy.precheck`). People: active humans (government). Fairness: open matters at Disputes the viewer can see. Rules at work: the idea routing rule, counted by this month's routed filings (ideas). Module re-checks read the assessment ledger (core_265): a current failed Security gate needs a governor who may ask for a re-check, a pending part is one already running.
+
+**D4 — The board's "needs you" is the summons rule.** A sitting needs a viewer when they are a member under the item's own snapshot, have not cast, are not the subject's author and the clock has not run out. That is `pendingVotesFor`'s rule on `/me`, so the city and the roster never disagree.
+
+**D5 — The route's own gate is the room's.** `GET /government/docket` gates on `board.vote.cast` (xenos floor), pinned in route-rank-check's `GOVERNMENT_PINS`. The real scoping is per source (D2).
+
+## Consequences
+
+- A new source is one `api.contribute('governor.docket', …)` call in its owning module plus a row in `EXPECTED_SOURCES`; nothing in government changes shape.
+- The docket fans out to every source on each read. Two sources leave the box (GitHub for gate approvals, without the per-PR file read; the npm registry for the core update, TTL-cached); the timeout keeps either from holding the city.
+- When the project records a real budget, the money reading should read it instead of the unattended ceiling; the reading's `value.scope` names what it counts so a screen never mislabels it.

package/docs/adr/README.md

@@ -480,3 +480,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0359 | [**Nobody sets a module's score by hand; a Metic+ person can ask for a re-check** ([task 1003796](https://cloudbongos.com/builders#/task/1003796) · goal 1000091, criterion `wa5-quality-assessed`). Amends [ADR 0343](0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) D6 and [ADR 0347](0347-every-store-module-ships-a-how-to.md) D5 on the owner's ruling: there is no score override. A score only ever comes from its signals. Instead `POST /store/modules/:key/versions/:version/reassess { reason }`, gated by the new `module.assessment.rerun` atom (metic floor, granted to metic + archon by `government_021`), queues the same assessment a publish runs. A reason is required and nothing else is accepted. The delist (task 1003797) is unchanged.](0359-nobody-sets-a-module-score-by-hand-metic-can-ask-for-a-re-check.md) | module store / assessment / permissions |
 | 0360 | [**Bongos follows every candidate; every other project follows releases** ([task 1004297](https://cloudbongos.com/builders#/task/1004297), goal 1000090 — the owner's 2026-09-26 decision that the Bongos hall takes every candidate automatically). Amends ADR 0136. **D1:** a per-instance `follow` beside the channel — `released` (default: at or below the registry's `latest` label) or `candidates` (every version, the platform hall only). **D2:** released is the `latest` dist-tag, read separately; an unreadable label skips the instance, never a guess. **D3:** the timer period is the lag — 15 min declared, installed by task 1003969. **D4:** a version that failed here is held for a day per instance (recorded in the sweep's config home), while any newer version is taken at once — no restart loop at a 15-minute cadence. **D5:** the deploy page's "Upgrades on this hall" — the core_upgrades ledger, rollbacks flagged, and a published version waiting past 30 min said to be the automation stopping. Rejected: a second runner, CI pushing to the box, a hold only a human clears.](0360-bongos-follows-every-candidate-every-other-project-follows-releases.md) | update channel / deploy / core update |
 | 0361 | [**Merges publish as candidates; Release on /deploy decides what other projects are offered** ([task 1004298](https://cloudbongos.com/builders#/task/1004298), goal 1000090). Amends ADR 0161. **D1:** merges publish under `next` when `PUBLISH_AS_CANDIDATE=1` (ships inert). **D2:** a `release` job in publish.yml moves `latest` (release-core.js: published, stable, newer than the release) over the same OIDC trusted publisher — no npm token. **D3:** /deploy's Release button (`core.pin.move`) dispatches it through the one-function `lifecycle.workflowDispatch` port. **D4:** evidence beside each button — hours on this hall, ever rolled back. **D5:** the banner and the hosted-project runner offer only released versions; the control-plane row follows candidates. Arming: roster follow → npm dist-tag permission → GitHub credential Actions: write → the variable.](0361-merges-publish-as-candidates-release-decides-what-others-are-offered.md) | publish / release / update channel |
+| 0362 | [**The governor's docket is collected from sources each module contributes, scoped by each source's own atom** ([task 1004523](https://cloudbongos.com/builders#/task/1004523), goal 1000125). **D1:** one contribution point, `governor.docket`; each owner contributes its source on the read its own list route serves. **D2:** a source declares its list route's atom and the collector enforces it (gated out = `not_yours`, no rows; no gate = dropped). **D3:** nothing invented: `coming` / `off` / `unavailable`. **D4:** the board's needs-you is the /me summons rule. **D5:** `GET /government/docket` gates on `board.vote.cast`.](0362-the-governor-docket-is-collected-from-contributed-sources.md) | government / Governor City |

package/docs/api/openapi.json

@@ -8824,6 +8824,40 @@
         ]
       }
     },
+    "/government/docket": {
+      "get": {
+        "operationId": "get_government_docket",
+        "tags": [
+          "government"
+        ],
+        "summary": "GET /government/docket",
+        "description": "board.vote.cast — the governor's DOCKET (task 1004523, goal 1000125): ONE read of every matter waiting on, or moving for, a governor, which the Governor City screens all draw from. Same coarse atom as the room (xenos floor: whoever the constitution may enfranchise may open the city); the real scoping is PER SOURCE, inside docket.js — each source is shown only to a viewer holding the same atom its own list route requires, and a hidden source reports `not_yours` with no rows (ADR 0016, server-side, uncached). Response (docket.buildDocket): { viewer: { id }, generated_at, line, // \"3 matters wait on you · 2 moving\" counts: { needs, moving, settled }, matters: [{ id: '<source>:<id>', source, building, rule, state, title, short, where, opened_at, deadline, proposer: { id, login, name } | null, tally: { for, against, open, needs } | null, href, ref }], buildings: [{ key, name, group, counts, matter_ids }], // street order sources: [{ source, building, label, status, count, reason }], // status: live | not_yours | coming | off | unavailable readings: [{ key, label, building, status, value, figure, line, hot, reason }], vocabulary: { buildings, rules, states } } `building` ∈ charter rules disputes people planning automation review release treasury; `rule` ∈ decide first consent majority unanimous signoff rule (or null); `state` ∈ needs moving settled. Nothing is ever sample data: a source with nothing recorded yet is `coming`, never a placeholder row.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).\n\n**Permissions:** `board.vote.cast` (all required).",
+        "x-rank": "any-builder",
+        "x-source": "modules/government/routes/government.js",
+        "x-permissions": [
+          "board.vote.cast"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/government/permissions": {
       "get": {
         "operationId": "get_government_permissions",
@@ -31741,7 +31775,7 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 496,
+  "x-endpoint-count": 497,
   "x-schema-count": 527,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 351,

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 496 endpoints across 92 route files.
+> **Generated from the live route files** — the route file is authoritative. 497 endpoints across 92 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -340,7 +340,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/goals/rollups` | `any-builder` | — | GET /goals/rollups?version= — one small row per goal: readiness counters, the last-activity timestamp, the craft set, and the next claima… |
 | GET | `/api/bongos/goals/suggestions` | `any-builder` | — | GET /goals/suggestions — "which goal should this draft live in?", answered before anything is created (task 1003062 / R07). |
 
-## `government` (16)
+## `government` (17)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -353,6 +353,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/government/board/items` | `metic+archon` | `subject_type`, `proposal`, `rationale_md`, `acknowledge_self_removal` | board.item.open — put an AMENDMENT to the board (R14 of goal 1000069, ADR 0175 §7). |
 | POST | `/api/bongos/government/board/items/:itemId/votes` | `any-builder` | `direction`, `reason_md`, `section_key` | board.vote.cast — cast a vote on an open board item (R08 of goal 1000069, ADR 0175). |
 | GET | `/api/bongos/government/constitution` | `any-builder` | — | board.vote.cast — the Constitution view (R18 of goal 1000069): the live board block plus the full amendment history, passed and returned … |
+| GET | `/api/bongos/government/docket` | `any-builder` | — | board.vote.cast — the governor's DOCKET (task 1004523, goal 1000125): ONE read of every matter waiting on, or moving for, a governor, whi… |
 | GET | `/api/bongos/government/permissions` | `archon` | — | government.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. |
 | POST | `/api/bongos/government/rank-sets/apply` | `archon` | `type`, `headcount` | government.manage — add a RECOMMENDED RANK SET (task 1004400): the custom ranks recommendations.js names for a project type and size, eac… |
 | GET | `/api/bongos/government/ranks` | `archon` | — | government.manage — the full rank list with each rank's grants. |