@bongos/core 1.21.57 → 1.21.58

package/docs/adr/README.md

@@ -483,3 +483,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 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 |
 | 0363 | [**Who decides what is a per-project table, changed only by a passed amendment** ([task 1004529](https://cloudbongos.com/builders#/task/1004529), goal 1000125). **D1:** `government_decision_rules`, one row per building: `gate` (as today), `board` (the charter only), `nobody` (vacant) or a membership predicate with decide / first / consent / majority / unanimous / sign-off. **D2:** the seeded defaults are today, and a malformed row reads as its default. **D3:** written only inside the transaction that closes a `decision_rules` amendment as passed; JS guard + SQL condition + trigger; no settings route. **D4:** eight building matters join the board's three subjects, openable only where a row names a sitting; sign-off is the author rule. **D5:** People's rank assignments defer to People's row (`checkActAlone`); a passed People matter acts. **D6:** the docket's buildings carry who decides.](0363-who-decides-what-is-a-table-changed-only-by-amendment.md) | government / Governor City |
 | 0364 | [**Repo access is asked at sign-in on the hub, and held for as long as the builder stays signed in** ([task 1004549](https://cloudbongos.com/builders#/task/1004549)). Amends ADR 0143 and 0155. **D1:** every sign-in door on the hub's own pages carries `repos=1`; the hall and CLI stay identity-only. **D2:** the repo token's TTL is the web session's remaining life; a web sign-out deletes it, a CLI logout does not. **D3:** a draft at a wizard step beside a stored create keeps its place on a reload or a GitHub round-trip.](0364-repo-access-is-asked-at-sign-in-and-held-for-the-session.md) | auth / GitHub / create wizard |
+| 0365 | [**A guild engages a project through each member's own door** ([task 1002303](https://cloudbongos.com/builders#/task/1002303)). Amends ADR 0336 D7's invite half after ADR 0353. **D1:** the engagement row as D7 specified, plus `guild_id` on the echo (the latest application decides the label). **D2:** a guild applies = each member applies as themselves through the relay, naming the engagement. **D3:** a project invites a guild = the hub records it and returns one hall hand-off link per public-roster member; no hub-written invites, the one-step relay stays deferred. **D4:** a project is named only when on the map and public, for both kinds. **D5:** the label rides the applicant-profile read; the queue is R28's. **D6:** the D4.4 guild cards are their own task.](0365-a-guild-engages-a-project-through-each-members-own-door.md) | guilds / invites / applications |

package/docs/api/openapi.json

@@ -9819,6 +9819,69 @@
         ]
       }
     },
+    "/guilds/{slug}/engagements": {
+      "post": {
+        "operationId": "post_guilds_slug_engagements",
+        "tags": [
+          "guilds"
+        ],
+        "summary": "POST /guilds/:slug/engagements",
+        "description": "owner: file \"this guild is applying to P\" (ADR 0365 D2, task 1002303). Each member then sees it in their own inbox and applies as themselves; filing applies for nobody, the owner included. P unknown, inactive, or not on the map and Public is ONE 404 — no oracle on a private project. The owner test is re-asserted inside the INSERT. Re-filing restarts the 30-day window.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/guilds.js",
+        "parameters": [
+          {
+            "name": "slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `slug`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostGuildsSlugEngagementsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostGuildsSlugEngagementsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/guilds/{slug}/invites": {
       "post": {
         "operationId": "post_guilds_slug_invites",
@@ -12293,6 +12356,44 @@
         ]
       }
     },
+    "/me/guild-engagements": {
+      "get": {
+        "operationId": "get_me_guild_engagements",
+        "tags": [
+          "me"
+        ],
+        "summary": "GET /me/guild-engagements",
+        "description": "MY inbox of guild engagements (ADR 0365): \"G is applying to P\" and \"P invited G\", for guilds I belong to, inside 30 days, naming only projects on the map and Public, an invite only if I was a member when it was sent, and never a project I already build on, hold an invite to, or applied to. count is the array's own length; client_id never crosses.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/platform-identity/routes/guilds.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetMeGuildEngagementsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/me/guild-requests": {
       "get": {
         "operationId": "get_me_guild_requests",
@@ -15484,6 +15585,58 @@
         ]
       }
     },
+    "/projects/invite-guild": {
+      "post": {
+        "operationId": "post_projects_invite_guild",
+        "tags": [
+          "projects"
+        ],
+        "summary": "POST /projects/invite-guild",
+        "description": "own-or-metic in effect, the SAME gate as POST /projects/invite above and for the same reasons (a non-inviter gets that route's unchanged refusal, identical whether or not the project exists): a project invites a PUBLIC guild (task 1002303, ADR 0365 D3, amending ADR 0336 D7). IT WRITES NO INVITES (ADR 0353). It records the `invited` engagement — so members the inviter could not see get a \"P invited this guild\" notice and may apply themselves, and only while P is on the map and Public (ADR 0365 D4) — and answers one hall hand-off link per member on the guild's PUBLIC roster at this moment. The inviter sends each from the project's hall, so every invite is the project's own row. Members who join later inherit nothing. An unlisted guild cannot be addressed, so it answers the unknown-guild 404 byte for byte.\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": [
+          "project.curate"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProjectsInviteGuildRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProjectsInviteGuildResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/projects/{id}/featured": {
       "patch": {
         "operationId": "patch_projects_id_featured",
@@ -20539,7 +20692,7 @@
           "sso"
         ],
         "summary": "POST /sso/applicant-profile",
-        "description": "POST /sso/applicant-profile — a federated instance resolves ONE applicant's profile view for its own reviewer queue, LIVE at render (privacy spec D7, task 1002972). Server-to-server, client_id+client_secret auth, like the two routes above. Answers { profile: null | { view:'public', … } | { view: 'sliver', … } } — the D7 rule, decided entirely inside ../applicant-profile.js. WHY A POST FOR A READ. The same reason /sso/activity/rollup is one: the credentials are in the body, and a client_secret in a query string lands in access logs and proxy history. Nothing is written. THE ECHO IS THE GATE, AND IT IS THE WHOLE SECURITY ARGUMENT (ADR 0205, security report 1000027). Client credentials prove WHICH PROJECT is calling and nothing about WHO the github_id is, so authenticating the caller is not enough: without a per-subject witness this route is a bulk disclosure oracle over every account on the platform, private ones included, readable by any registered project holding only its own secret. applicationBacksProfileRead demands a HUB-WRITTEN echo for exactly (this account, this client) inside the 30-day window — a row only the hub's own join relay creates, and only after the project accepted the relayed application. A project may therefore read the profile of someone who applied TO IT, and of nobody else. 404, never 403, when the echo is absent — the /scouting/:handle posture. A 403 would confirm that the github_id names a real account, which is the disclosure the whole rule exists to withhold. An account that exists but discloses nothing (provisional, terms never accepted) answers the SAME { profile: null } as one that consented but is simply not readable, so the caller cannot tell those apart either (ADR 0171 D4). NOT AUTHORITY (ADR 0016). The answer is descriptive; the project's own admission gate reads status='invited' and never this. rank: public — authenticated by client_id + client_secret, not a builder rank. The limiter runs BEFORE the client lookup, so a refused probe costs no DB work — the accountExistenceReadRateLimit posture.\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "POST /sso/applicant-profile — a federated instance resolves ONE applicant's profile view for its own reviewer queue, LIVE at render (privacy spec D7, task 1002972). Server-to-server, client_id+client_secret auth, like the two routes above. Answers { profile: null | { view:'public', … } | { view: 'sliver', … }, guild } — the D7 rule, decided entirely inside ../applicant-profile.js, plus the guild the applicant applied with (ADR 0365 D5): { slug, name } while they are still a member of it (slug null for an unlisted guild), else null. A project on an older core reads only `profile` and ignores the rest (the ADR 0201 D2.2 compatibility rule). WHY A POST FOR A READ. The same reason /sso/activity/rollup is one: the credentials are in the body, and a client_secret in a query string lands in access logs and proxy history. Nothing is written. THE ECHO IS THE GATE, AND IT IS THE WHOLE SECURITY ARGUMENT (ADR 0205, security report 1000027). Client credentials prove WHICH PROJECT is calling and nothing about WHO the github_id is, so authenticating the caller is not enough: without a per-subject witness this route is a bulk disclosure oracle over every account on the platform, private ones included, readable by any registered project holding only its own secret. applicationBacksProfileRead demands a HUB-WRITTEN echo for exactly (this account, this client) inside the 30-day window — a row only the hub's own join relay creates, and only after the project accepted the relayed application. A project may therefore read the profile of someone who applied TO IT, and of nobody else. 404, never 403, when the echo is absent — the /scouting/:handle posture. A 403 would confirm that the github_id names a real account, which is the disclosure the whole rule exists to withhold. An account that exists but discloses nothing (provisional, terms never accepted) answers the SAME { profile: null } as one that consented but is simply not readable, so the caller cannot tell those apart either (ADR 0171 D4). NOT AUTHORITY (ADR 0016). The answer is descriptive; the project's own admission gate reads status='invited' and never this. rank: public — authenticated by client_id + client_secret, not a builder rank. The limiter runs BEFORE the client lookup, so a refused probe costs no DB work — the accountExistenceReadRateLimit posture.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/platform-identity/routes/sso.js",
         "requestBody": {
@@ -25312,6 +25465,17 @@
           "events"
         ]
       },
+      "GetMeGuildEngagementsResponse": {
+        "type": "object",
+        "properties": {
+          "engagements": {},
+          "count": {}
+        },
+        "required": [
+          "engagements",
+          "count"
+        ]
+      },
       "GetMeGuildRequestsResponse": {
         "type": "object",
         "properties": {
@@ -29506,6 +29670,28 @@
           "guild"
         ]
       },
+      "PostGuildsSlugEngagementsRequest": {
+        "type": "object",
+        "properties": {
+          "origin": {
+            "type": "string",
+            "maxLength": 512
+          }
+        },
+        "required": [
+          "origin"
+        ],
+        "additionalProperties": false
+      },
+      "PostGuildsSlugEngagementsResponse": {
+        "type": "object",
+        "properties": {
+          "engagement": {}
+        },
+        "required": [
+          "engagement"
+        ]
+      },
       "PostGuildsSlugInvitesRequest": {
         "type": "object",
         "properties": {
@@ -30198,6 +30384,10 @@
           "note": {
             "type": "string",
             "maxLength": 400
+          },
+          "guild": {
+            "type": "string",
+            "maxLength": 39
           }
         },
         "required": [
@@ -30378,6 +30568,41 @@
           "images"
         ]
       },
+      "PostProjectsInviteGuildRequest": {
+        "type": "object",
+        "properties": {
+          "client_id": {
+            "type": "string",
+            "maxLength": 200
+          },
+          "guild": {
+            "type": "string",
+            "maxLength": 39
+          }
+        },
+        "required": [
+          "client_id",
+          "guild"
+        ],
+        "additionalProperties": false
+      },
+      "PostProjectsInviteGuildResponse": {
+        "type": "object",
+        "properties": {
+          "invited": {
+            "type": "boolean"
+          },
+          "guild": {},
+          "invites": {},
+          "count": {}
+        },
+        "required": [
+          "invited",
+          "guild",
+          "invites",
+          "count"
+        ]
+      },
       "PostProjectsInviteRequest": {
         "type": "object",
         "properties": {
@@ -31490,10 +31715,12 @@
       "PostSsoApplicantProfileResponse": {
         "type": "object",
         "properties": {
-          "profile": {}
+          "profile": {},
+          "guild": {}
         },
         "required": [
-          "profile"
+          "profile",
+          "guild"
         ]
       },
       "PostSsoDevicePollRequest": {
@@ -32857,9 +33084,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 512,
-  "x-schema-count": 549,
+  "x-endpoint-count": 515,
+  "x-schema-count": 554,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 364,
+  "x-response-schemas": 367,
   "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. 512 endpoints across 93 route files.
+> **Generated from the live route files** — the route file is authoritative. 515 endpoints across 93 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`.
@@ -379,7 +379,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/guild-requests/:id/accept` | `any-builder` | `visibility`, `counted_in_totals` | accept an invite addressed to ME, or (as the guild's owner) a request to join it. |
 | POST | `/api/bongos/guild-requests/:id/decline` | `any-builder` | — | decline an invite to ME, or (as owner) a request to my guild. |
 
-## `guilds` (13)
+## `guilds` (14)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -388,6 +388,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/guilds/:slug` | `public` | — | a public guild's page data. |
 | PATCH | `/api/bongos/guilds/:slug` | `any-builder` | `name`, `description`, `visibility` | owner: edit name, description or visibility. |
 | DELETE | `/api/bongos/guilds/:slug` | `any-builder` | — | owner: dissolve. |
+| POST | `/api/bongos/guilds/:slug/engagements` | `any-builder` | `origin` | owner: file "this guild is applying to P" (ADR 0365 D2, task 1002303). |
 | POST | `/api/bongos/guilds/:slug/invites` | `any-builder` | `handles` | owner: invite up to INVITE_BATCH_MAX builders by handle, each an ordinary individual invite (ADR 0336 D3). |
 | GET | `/api/bongos/guilds/:slug/members` | `any-builder` | — | the members' roster, for members only (the own-scope door to an unlisted guild, ADR 0336 D4). |
 | DELETE | `/api/bongos/guilds/:slug/members/:handle` | `any-builder` | — | owner: remove a member (never the owner). |
@@ -471,7 +472,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
-## `me` (34)
+## `me` (35)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -486,6 +487,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/me/display-name` | `any-builder` | _undocumented_ | PATCH the display name. |
 | GET | `/api/bongos/me/event-sound-prefs` | `any-builder` | — | Per-builder per-event sound variant selection (task 582, migration 164). |
 | PATCH | `/api/bongos/me/event-sound-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of event sound overrides. |
+| GET | `/api/bongos/me/guild-engagements` | `any-builder` | — | MY inbox of guild engagements (ADR 0365): "G is applying to P" and "P invited G", for guilds I belong to, inside 30 days, naming only pro… |
 | GET | `/api/bongos/me/guild-requests` | `any-builder` | — | MY queue: invites addressed to me, each carrying the card (the guild's current visibility, which an accept must echo back), and the join … |
 | GET | `/api/bongos/me/guilds` | `any-builder` | — | MY guilds, each with my own two switches. |
 | PATCH | `/api/bongos/me/handle` | `any-builder` | `handle` | rename the caller's OWN handle (own data, keyed on the authenticated github_id). |
@@ -551,7 +553,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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/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. |
+| POST | `/api/bongos/my-projects/join` | `any-builder` | `origin`, `note`, `guild` | request to join a project. |
 
 ## `npm-release` (8)
 
@@ -600,7 +602,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/project-settings` | `metic+archon` | — | GET /project-settings — all five rows in ONE read. |
 | PATCH | `/api/bongos/project-settings/rot-days` | `metic+archon` | `days` | PATCH /project-settings/rot-days — body { days }. |
 
-## `projects` (7)
+## `projects` (8)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -611,6 +613,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
+| POST | `/api/bongos/projects/invite-guild` | `metic+archon` | `client_id`, `guild` | own-or-metic in effect, the SAME gate as POST /projects/invite above and for the same reasons (a non-inviter gets that route's unchanged … |
 
 ## `provisioning` (42)