@bongos/core 1.20.21 → 1.20.23

package/docs/adr/README.md

@@ -471,3 +471,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |
 | 0351 | [**A criterion closes on a UAT, not on its linked tasks shipping** ([task 1004392](https://cloudbongos.com/builders#/task/1004392), goal 1000089 — working area 3). Supersedes ADR 0183's close rule. `wa7-government` had closed on six Board Room navigation tasks while nothing it describes was on the live site. **D1:** three checks — Code (linked tasks done, ≥1 shipped; automatic), Live, UAT — and the sweep closes a criterion only with a CURRENT sign-off (no older than the newest linked ship). **D2 (owner):** "Awaiting UAT" is a visible state. **D3 (owner):** one step; the signer is refused if they shipped linked work, the project owner excepted. **D4 (owner):** an mp4/webm up to 100 MB on the project's own server. **D5 (owner):** backend-only is set while a criterion is open and takes a recording-free sign-off. **D6 (owner):** Live is read via the `deploy.taskWhere` port where the site can tell, attested otherwise. **D7 (owner):** already-closed criteria stay closed ("Closed before UAT"). **D8:** `/satisfy` is a recorded override that needs a reason. **D9:** `/goal-uat` + `scripts/gds/uat.js`; the hall is task 1004402.](0351-a-criterion-closes-on-a-uat.md) | lifecycle / criteria / review |
 | 0352 | [**A rollup report carries its "as of" in a header, and the hub keeps the newest** ([task 1004268](https://cloudbongos.com/builders#/task/1004268), goal 1000110). `POST /sso/activity/rollup` was last-writer-wins with no report timestamp, so a sign-in push read earlier and a ship push read later could land the older totals last. **D1:** the instance's read time rides a `Bongos-Report-As-Of` HEADER, not a body field, because the hub validates the body strictly and hub and instances upgrade independently: a body field from a newer instance would 400 on an older hub and lose the report, while an unknown header is ignored. **D2:** missing or unparseable = unstamped = last-writer-wins, never a 400. **D3:** the guard is a WHERE on the upsert's conflict branch (migration 026, `reported_as_of`, no backfill); a skipped update keeps the row lock, so the task 1004244 snapshot stays in step. **D4:** the stamp is compared only with the same client's, and clamped to the hub's `now()`.](0352-a-rollup-report-carries-its-as-of-in-a-header.md) | platform identity / federation |
+| 0353 | [**A hub invite is a notice of the project's own invite, and signing in accepts it** ([task 1002818](https://cloudbongos.com/builders#/task/1002818), goal 1000110 — R6 of the admin console wave). The hub's own invite wrote a `pending` membership that no project reads, so an "accepted" invite met a locked door (new projects default to `apply`). **D1:** that row is now a NOTICE the PROJECT writes: its invite route calls `POST /sso/invites/notify` and a dismissal that leaves no invited row calls `/sso/invites/clear` (client credentials, pending rows only, always `{ ok: true }` so no account oracle); core's `notifyHubOfInvite` is fire-and-forget. **D2:** the hub-side accept route is deleted; signing in to the project accepts, and the hub's own sign-in witness turns the row into a membership. **D3 (owner):** `POST /projects/invite` writes nothing and answers `{ invited: false, invite_url }`, the project's hall invite link (`/builders/watch?invite=<login>`, which only pre-fills); the signed-assertion relay is deferred. **D4:** new routes, so an older hub 404s and only the notice is lost (ADR 0352).](0353-a-hub-invite-is-a-notice-of-the-projects-own-invite.md) | platform identity / federation |

package/docs/api/openapi.json

@@ -388,7 +388,7 @@
           "access-requests"
         ],
         "summary": "POST /access-requests/invite",
-        "description": "POST /access-requests/invite — an Archon admits a GitHub username BEFORE any request exists (task 1003044): the only way in on an invite-only project, where the public POST refuses, and a shortcut on an apply one. It writes the same access_request row the sign-in gate reads (status 'invited' — hasInvitedAccessRequest), so nothing new is consulted at sign-in; a pending request for that login is resolved in place rather than duplicated. Two Archons inviting the same login at once can each insert a row (the unique index covers pending only): harmless — the gate reads \"any invited row\" — and it shows as two lines in the invited history, so no lock is taken. A fresh row is marked kind='invite' with created_by = the sender (a rescind overwrites resolved_by) and the optional note as the inviter's words. A pending request resolved in place stays an application with its applicant's own note (ADR 0335 D2.1–D2.3; task 1002814). body: { github_login, note? }. 201 with a new row; 200 with the row when a pending request was resolved; 200 already_invited when an invite already stands; 409 already_member when they have an account. rank: archon — the same gate as resolving a request.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
+        "description": "POST /access-requests/invite — an Archon admits a GitHub username BEFORE any request exists (task 1003044): the only way in on an invite-only project, where the public POST refuses, and a shortcut on an apply one. It writes the same access_request row the sign-in gate reads (status 'invited' — hasInvitedAccessRequest), so nothing new is consulted at sign-in; a pending request for that login is resolved in place rather than duplicated. Two Archons inviting the same login at once can each insert a row (the unique index covers pending only): harmless — the gate reads \"any invited row\" — and it shows as two lines in the invited history, so no lock is taken. A fresh row is marked kind='invite' with created_by = the sender (a rescind overwrites resolved_by) and the optional note as the inviter's words. A pending request resolved in place stays an application with its applicant's own note (ADR 0335 D2.1–D2.3; task 1002814). Every outcome that leaves the login invited also notifies the hub, so the invitee sees it in My Projects (ADR 0353). body: { github_login, note? }. 201 with a new row; 200 with the row when a pending request was resolved; 200 already_invited when an invite already stands; 409 already_member when they have an account. rank: archon — the same gate as resolving a request.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
         "x-rank": "archon",
         "x-source": "modules/onboarding/routes/access-requests.js",
         "x-permissions": [
@@ -13194,58 +13194,6 @@
         ]
       }
     },
-    "/my-projects/invites/{clientId}/accept": {
-      "post": {
-        "operationId": "post_my_projects_invites_clientId_accept",
-        "tags": [
-          "my-projects"
-        ],
-        "summary": "POST /my-projects/invites/:clientId/accept",
-        "description": "accept an invite (pending → builder) for the caller's OWN account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/platform-identity/routes/my-projects.js",
-        "parameters": [
-          {
-            "name": "clientId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `clientId`."
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Success.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PostMyProjectsInvitesClientIdAcceptResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          }
-        },
-        "security": [
-          {
-            "builderSession": []
-          }
-        ]
-      }
-    },
     "/my-projects/invites/{clientId}/decline": {
       "post": {
         "operationId": "post_my_projects_invites_clientId_decline",
@@ -14001,7 +13949,7 @@
           "projects"
         ],
         "summary": "POST /projects/invite",
-        "description": "own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task 1002115), called by a `project.curate` holder OR the project's OWN OWNER (task 1003580; the ownership proof is `provisioning_instances.owner_builder_id`, reached through a port — see invite-authz.js). The wizard's audience is any signed-in GitHub user, typically a xenos who used to get 403 on their own project. A caller who is neither gets the unchanged permission refusal, identical whether or not the project exists. Pre-seeds a 'pending' membership the invitee accepts from My Projects. V1 invites by github_login and requires the invitee to already have a platform account (they build on some project); inviting someone entirely new to the platform (GitHub-id resolution) is a follow-up.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "description": "own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 1003580; the ownership proof is `provisioning_instances.owner_builder_id`, reached through a port — see invite-authz.js). The wizard's audience is any signed-in GitHub user, typically a xenos who used to get 403 on their own project. A caller who is neither gets the unchanged permission refusal, identical whether or not the project exists. IT WRITES NOTHING (task 1002818, ADR 0353). It used to pre-seed a 'pending' hub membership, but the hub holds no verdict: that row let nobody in, and on any door but `open` (new projects default to `apply`) the invitee who signed in met a locked door. Only the project's own invite admits (ADR 0335 D1/D2), so the answer is 200 `{ invited: false, invite_url }` — the project's hall invite box with the login pre-filled. A 200, not a refusal: it is the answer every admitted caller gets, and a 4xx on the normal path would log a failed request in the owner's browser on every invite. Sending it there also reaches this hub: the project notifies it (POST /sso/invites/notify), and the invitee sees it in My Projects.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
         "x-permissions": [
@@ -14020,7 +13968,14 @@
         },
         "responses": {
           "200": {
-            "description": "Success."
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProjectsInviteResponse"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/ValidationFailed"
@@ -18684,6 +18639,70 @@
         "security": []
       }
     },
+    "/sso/invites/clear": {
+      "post": {
+        "operationId": "post_sso_invites_clear",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/invites/clear",
+        "description": "authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso-invites.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoInvitesClearRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
+    "/sso/invites/notify": {
+      "post": {
+        "operationId": "post_sso_invites_notify",
+        "tags": [
+          "sso"
+        ],
+        "summary": "POST /sso/invites/notify",
+        "description": "authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/sso-invites.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSsoInvitesNotifyRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          }
+        },
+        "security": []
+      }
+    },
     "/sso/membership/check-in": {
       "post": {
         "operationId": "post_sso_membership_check_in",
@@ -27289,21 +27308,6 @@
           "left"
         ]
       },
-      "PostMyProjectsInvitesClientIdAcceptResponse": {
-        "type": "object",
-        "properties": {
-          "ok": {
-            "type": "boolean"
-          },
-          "accepted": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "ok",
-          "accepted"
-        ]
-      },
       "PostMyProjectsInvitesClientIdDeclineResponse": {
         "type": "object",
         "properties": {
@@ -27400,6 +27404,19 @@
         ],
         "additionalProperties": false
       },
+      "PostProjectsInviteResponse": {
+        "type": "object",
+        "properties": {
+          "invited": {
+            "type": "boolean"
+          },
+          "invite_url": {}
+        },
+        "required": [
+          "invited",
+          "invite_url"
+        ]
+      },
       "PostProjectsProjectIdSpecialitiesRequest": {
         "type": "object",
         "properties": {
@@ -28452,6 +28469,54 @@
         ],
         "additionalProperties": false
       },
+      "PostSsoInvitesClearRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_login": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
+      "PostSsoInvitesNotifyRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "client_secret": {
+            "type": "string",
+            "maxLength": 512
+          },
+          "github_login": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "required": [
+          "client_id",
+          "client_secret",
+          "github_login"
+        ],
+        "additionalProperties": false
+      },
       "PostSsoMembershipCheckInRequest": {
         "type": "object",
         "properties": {
@@ -29564,8 +29629,8 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 462,
-  "x-schema-count": 494,
+  "x-endpoint-count": 463,
+  "x-schema-count": 496,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 336,
   "x-generated-by": "scripts/gds/gen-api-docs.js"

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 462 endpoints across 82 route files.
+> **Generated from the live route files** — the route file is authoritative. 463 endpoints across 83 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`.
@@ -506,14 +506,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/modules/:key/submit` | `metic+archon` | `signed_by` | POST /api/bongos/modules/:key/submit — ADR 0107 §1 upstreaming submission. |
 | GET | `/api/bongos/modules/submissions` | `metic+archon` | — | GET /api/bongos/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). |
 
-## `my-projects` (6)
+## `my-projects` (5)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/my-projects` | `any-builder` | — | the caller's OWN cross-project memberships (own data). |
 | POST | `/api/bongos/my-projects/:clientId/leave` | `any-builder` | — | leave a project from the caller's OWN membership list. |
 | GET | `/api/bongos/my-projects/invites` | `any-builder` | — | the caller's OWN pending invitations (ADR 0141 §5). |
-| POST | `/api/bongos/my-projects/invites/:clientId/accept` | `any-builder` | — | accept an invite (pending → builder) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/invites/:clientId/decline` | `any-builder` | — | decline an invite (delete the pending row) for the caller's OWN account. |
 | POST | `/api/bongos/my-projects/join` | `any-builder` | `origin`, `note` | request to join a project. |
 
@@ -559,7 +558,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/projects/:id/status` | `metic+archon` | `status` | THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). |
 | POST | `/api/bongos/projects/:projectId/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable`, `skills` | POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. |
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
-| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: invite a builder into a project (ADR 0141 §5, task 1002115), called by a `project.curate` holder OR the project's… |
+| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 
 ## `provisioning` (34)
 
@@ -719,7 +718,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/specialities/installed-skills` | `any-builder` | — | GET /specialities/installed-skills — every skill THIS instance has, each explained the way the adoption walkthrough explains it, so a spe… |
 | GET | `/api/bongos/specialities/offered` | `any-builder` | — | GET /specialities/offered — the suggestions for THIS builder. |
 
-## `sso` (8)
+## `sso` (10)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -728,6 +727,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/sso/authorize` | `public` | — | GET /sso/authorize?client_id=&redirect_uri=&state= — the browser authorize leg. |
 | POST | `/api/bongos/sso/device/poll` | `public` | `device_code` | POST /sso/device/poll — poll the hub device flow. |
 | POST | `/api/bongos/sso/device/start` | `public` | `origin` | POST /sso/device/start — begin CLI federation. |
+| POST | `/api/bongos/sso/invites/clear` | `public` | `client_id`, `client_secret`, `github_login` | authenticated by client_id + client_secret, not a builder rank. |
+| POST | `/api/bongos/sso/invites/notify` | `public` | `client_id`, `client_secret`, `github_login` | authenticated by client_id + client_secret, not a builder rank. |
 | POST | `/api/bongos/sso/membership/check-in` | `public` | `client_id`, `client_secret`, `github_id`, `github_login`, `display_name`, `avatar_url`, `membership_kind` | POST /sso/membership/check-in — a federated instance reports, on every sign-in, that a builder builds on its project (ADR 0141 §3). |
 | GET | `/api/bongos/sso/pubkey` | `public` | — | GET /sso/pubkey — the hub's Ed25519 assertion-verification key (public). |
 | POST | `/api/bongos/sso/token` | `public` | `client_id`, `client_secret`, `code`, `redirect_uri` | POST /sso/token — server-to-server code redemption. |

package/docs/architecture.md

@@ -258,6 +258,20 @@ module_entitlements(id, module_key, holder_kind IN (builder|instance), holder_re
               -- keeping the row.
 ```
 
+Module assessments (migration `core_265`, task 1003814 — [ADR 0343](adr/0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) + [ADR 0347](adr/0347-every-store-module-ships-a-how-to.md) D5; per module VERSION, append-only history, the current row is the newest; never reads price):
+
+```
+module_assessment_signals(id, version_id → store_module_versions, part IN (security|tests|
+              install|reliability|tester_feedback|docs), outcome IN (scored|passed|failed|
+              no_data|pending|not_scored), score 0-100 iff scored, sample_size, reason,
+              detail jsonb, measured_at)  -- security is pass/fail only (the D2 gate);
+              -- "no data yet" is an outcome, never a zero (D3/D5)
+module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-100 | NULL,
+              security_passed, is_new (D5 "New" label), formula, signal_ids bigint[],
+              override_by, override_reason, computed_at)  -- an override names who + why
+              -- and is a new row on the computed history, never an edit (D6)
+```
+
 Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
 
 Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again in 014 so the new `discipline` column flows through), `version_progress` (rebuilt in 006 to count only leaf tasks for forward-compat with task hierarchy), `tasks_session_fit` (new in 006: derives `fits_session_modes[]` and `credits_per_minute`; rebuilt in 014 for the same SELECT t.* refresh), `task_grades_with_context` (new in 016: joins task_grades × tasks × builders × cost_log so the V4 optimizer has quality-per-dollar in one read).