@bongos/core 1.19.1076 → 1.19.1078

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1076",
-  "core_contract": "1.19.1076",
-  "source_commit": "4135e4def362d39393077ddfeb1d1dc1a9051388",
+  "core_version": "1.19.1078",
+  "core_contract": "1.19.1078",
+  "source_commit": "411c9ed509c000585d51b84c04a797ec9b15f67d",
   "source_ref": "HEAD",
-  "built_at": "2026-09-29T04:46:26.745Z",
+  "built_at": "2026-09-29T16:46:58.351Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 550,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2529,
+    "functional_verbatim": 2533,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3105,
-  "tree_sha256": "9e3b295c6b90f3d06b78b0ba7c1ba67b736ff026e40d259c30ac405836f3df3e",
+  "file_count": 3109,
+  "tree_sha256": "391c5cd61e61bb87908e73e23c99d7e86ea0f2467f47dfd2a63ebb2b475f435b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,12 +322,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "3495420fb86a9487d38759379da8ef1d27df15f601bd45529f99c5edc93572bb"
+      "sha256": "aa2d78e23e985228caf64e4b9bdacc0caa55f07f1b0d883520b5a97e112427b2"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "cda0f587bb153b2d533ba34dca76742fc2c56c1468cdc745af4a7997c36c1888"
+      "sha256": "1267fb539bb527d61edc8b3372eca5f4e9b478b8bf2f23c5aed3760ad4d1d09c"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -337,17 +337,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "397284bd88c2cd78a22a724b3311808eeae80c845a72d8eaa9a5f234d12066c5"
+      "sha256": "4a5ca3b3f81ecc0d068f4456662342c2be6c609668c730bf8b90eb255ac6590f"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "5ca74d00f9de706dd3c22d85c96c2695030b069f7ae9bece18c1153c5d856d3f"
+      "sha256": "3f262f4b629221e5ac75344d23d2b07d51a8003b91567f1a7e96f6b354695e46"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "024c569bd41f1f479e9de7868341d3a68906360ac457c1a5e8382397122828a0"
+      "sha256": "aa9e5ed9bf436f0e0eb28eb6a14a394668f614c5d30bdb31eb7bcd92335ff456"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1167,7 +1167,7 @@
     {
       "path": "docs/adr/0145-free-hosted-project-tier-isolation-and-domain-separation.md",
       "mode": "0000644",
-      "sha256": "a9a3e35550ead0905618da94d52bb1c5824b062ae5028745c8a5bed6112c2c6d"
+      "sha256": "7735acb6a10465a34e9c1b8ce75f045256ef0ed92bd94a5f383ddf7020afee82"
     },
     {
       "path": "docs/adr/0146-configurable-reward-mode-cost-plus-only.md",
@@ -2207,17 +2207,17 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "539c0a101e0643dd40869beee774540b630b63fd4a368bf92614407ec919b75f"
+      "sha256": "4cbfdf33670b1e7cfa9e361ef7209af719da5440fee486f2634a00ab2d8ded64"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "560ee79e29357daff98ee2148842ad38251f00391a7f32928c8e221f709ccb55"
+      "sha256": "ee67c19d724bde053b4dbcb711c05cf8d1d14cb3b6ff15c198739fd368c8356d"
     },
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "c7e6113f1819b535619c163c097253314cefaf24b665e727f1e16c65aff9c19e"
+      "sha256": "c806ee6970ef09f4ee4da68b11b38e9e80bf6c37a71e63833ef3a491b9d1afde"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2742,7 +2742,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "bbf793bc4666f224874a7c6ae58cb2c6ef1532d6a5d34b32c87f3f6bb129a27a"
+      "sha256": "e366a77119b50c3c36bfb3219a3cd873b1e36f735b7a150a199cab20ac40fc65"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3889,6 +3889,11 @@
       "mode": "0000644",
       "sha256": "6591b63dc385fd1d3a69b2729ef16141bdd6017bf3442cac1642403332edc601"
     },
+    {
+      "path": "migrations/core_259_module_entitlements.sql",
+      "mode": "0000644",
+      "sha256": "496e1605d0bcac75631217e55ff87d707971332c25fab0730a592eed5d7da8b9"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -8597,12 +8602,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f7f09866a7769adcd0ae7c8b98b95d524c8952bc7303fb1c0a7d91ab0f84b702"
+      "sha256": "3e6637987df0fac5b562427c291eb8b9ee03af1b4d84bdc96845fdc3f0616198"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "fbe7987f4279fa8c73b674d136aa26ef24617bac7a7cc1514c2ed2d5c36d056d"
+      "sha256": "6cfe5fc0e9b764a9e597bb45806a6f5876dd340c3dbedf3101ec20609546bd26"
     },
     {
       "path": "public-docs/index.html",
@@ -8622,7 +8627,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "265af57b3e6a412024b2c35b30940a80ad4e11250aa9a187faab6ef7407b9281"
+      "sha256": "6c995cf2f60c9bca1bf378e3687ada8fe7963c5b18bf45b78bd92e0ee414c88b"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10392,7 +10397,7 @@
     {
       "path": "src/bongos/auth.js",
       "mode": "0000644",
-      "sha256": "50dcaa4253f6ceac17b1949037090d572bb85b4a26e71022d903a172e352a145"
+      "sha256": "a46826214509f317fbe982265c0045edf9c3aa4c94bd2fa54232af51cbc51573"
     },
     {
       "path": "src/bongos/cascade-dispatch.js",
@@ -10472,7 +10477,12 @@
     {
       "path": "src/bongos/middleware/rate-limit.js",
       "mode": "0000644",
-      "sha256": "2c4cb05109bd3a931acba1967e1d01e4c3c069273d22b4356211aac103a04781"
+      "sha256": "efe34f92930419444ec31d84c7787488db4984ea761d1bb77d5375388758e68c"
+    },
+    {
+      "path": "src/bongos/module-entitlements.js",
+      "mode": "0000644",
+      "sha256": "917f364b804f25437dea7fe507abe50e9b64cac79b6cc29ac786de0e24350d33"
     },
     {
       "path": "src/bongos/module-overrides.js",
@@ -10572,7 +10582,7 @@
     {
       "path": "src/bongos/routes/auth.js",
       "mode": "0000644",
-      "sha256": "da0d7ee4f2d2e76577047822a955b4fbad9f8e142592746d34c9e2fddde5a5f8"
+      "sha256": "951276d7d3bd022cd9250fe8cd7bd141278d46c4bc6bc06463867f2889e52bc3"
     },
     {
       "path": "src/bongos/routes/backup.js",
@@ -10622,7 +10632,7 @@
     {
       "path": "src/bongos/routes/modules.js",
       "mode": "0000644",
-      "sha256": "1178db97cfa28a54a41c90bde0fe4a5f47192278c3a51ab01b68f334f8e4374a"
+      "sha256": "e349115a6adea7e97eaf91d2a5fde6d17c90ac80d8f4be579c890ce4a593ef66"
     },
     {
       "path": "src/bongos/routes/my-sessions.js",
@@ -10692,7 +10702,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "7529243c4bf7f88a907a8e6afeb27a34fff45a4b113c27b2da60005e4fb3303e"
+      "sha256": "28d2a831a69f59cc426c1e318991e4ab0755abd3303cc5786e88b72988e97a5c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12894,6 +12904,11 @@
       "mode": "0000644",
       "sha256": "5281b73558af27b1be5a839718d845ef47190734d248a3edb5d547c92621f432"
     },
+    {
+      "path": "tests/hub_cookie_host_only.mjs",
+      "mode": "0000644",
+      "sha256": "96698c6be76c8c6d6cc5f09522d110514c420cb1a7279ca86871a034892c7328"
+    },
     {
       "path": "tests/hub_disconnect_ui.mjs",
       "mode": "0000644",
@@ -13267,7 +13282,7 @@
     {
       "path": "tests/landing_page.mjs",
       "mode": "0000644",
-      "sha256": "b9adc1877fd5dacbda5f360ed5d0584b815876337a9bba0d8a3689a2a29e2b9e"
+      "sha256": "cb0dbcf0f4cc6fc67f7eeda609b2ea4c879bd8ad9efea7556fcbb8c7afe85bd4"
     },
     {
       "path": "tests/leak_scan_allowlist.mjs",
@@ -13534,6 +13549,11 @@
       "mode": "0000644",
       "sha256": "02862e4df8c3df0f6e255c8ad8108b518de7a665881f744eb3e59537193f4587"
     },
+    {
+      "path": "tests/module_entitlements.mjs",
+      "mode": "0000644",
+      "sha256": "50e4d45bf544efe755dda538a93eafc40dcd9caa071e987d8833d97ecf1b7e0f"
+    },
     {
       "path": "tests/module_exports_unique_keys.mjs",
       "mode": "0000644",
@@ -14692,7 +14712,7 @@
     {
       "path": "tests/session_rename_fallback.mjs",
       "mode": "0000644",
-      "sha256": "8422b77c656e7e75584cf439f8ed0fb089432f3741bdd30539e8e89154a47d7c"
+      "sha256": "9d6964a9df8051430d7cf495ca1fa93c22a60b9cf6c90174da209255ff3e551d"
     },
     {
       "path": "tests/session_reward_on_land.mjs",
@@ -15122,7 +15142,7 @@
     {
       "path": "tests/subdomain_auth.mjs",
       "mode": "0000644",
-      "sha256": "24257ca4ad1a7bcefb735ee1b02609469035730e0723645f71e10eb71525bb72"
+      "sha256": "a9f2b527557bdd86ccabb6c7aff779a235cdd20374f278232cfe7451d9f22d9b"
     },
     {
       "path": "tests/sweep_app_account.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 433 operations across 67 resource groups
+- 436 operations across 67 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -163,6 +163,8 @@ function createClient(opts = {}) {
       getAuthWebAdmissionStatus: (args) => request("GET", "/auth/web/admission-status", { hasBody: false }, args),
       // GET /auth/web/callback — rank: public — GET /auth/web/callback
       getAuthWebCallback: (args) => request("GET", "/auth/web/callback", { hasBody: false }, args),
+      // GET /auth/web/handoff — rank: public — GET /auth/web/handoff
+      getAuthWebHandoff: (args) => request("GET", "/auth/web/handoff", { hasBody: false }, args),
       // GET /auth/web/start — rank: public — GET /auth/web/start
       getAuthWebStart: (args) => request("GET", "/auth/web/start", { hasBody: false }, args),
     },
@@ -969,6 +971,10 @@ function createClient(opts = {}) {
       postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
     },
     "store": {
+      // GET /store/entitlements — rank: any-builder — GET /store/entitlements
+      getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // GET /store/modules/{key}/entitlement — rank: any-builder — GET /store/modules/:key/entitlement
+      getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
     },

package/clients/bongos-client/index.cjs

@@ -162,6 +162,8 @@ function createClient(opts = {}) {
       getAuthWebAdmissionStatus: (args) => request("GET", "/auth/web/admission-status", { hasBody: false }, args),
       // GET /auth/web/callback — rank: public — GET /auth/web/callback
       getAuthWebCallback: (args) => request("GET", "/auth/web/callback", { hasBody: false }, args),
+      // GET /auth/web/handoff — rank: public — GET /auth/web/handoff
+      getAuthWebHandoff: (args) => request("GET", "/auth/web/handoff", { hasBody: false }, args),
       // GET /auth/web/start — rank: public — GET /auth/web/start
       getAuthWebStart: (args) => request("GET", "/auth/web/start", { hasBody: false }, args),
     },
@@ -968,6 +970,10 @@ function createClient(opts = {}) {
       postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
     },
     "store": {
+      // GET /store/entitlements — rank: any-builder — GET /store/entitlements
+      getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // GET /store/modules/{key}/entitlement — rank: any-builder — GET /store/modules/:key/entitlement
+      getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
     },

package/clients/bongos-client/index.d.ts

@@ -157,6 +157,7 @@ export interface GetSpecialitiesIdResponse { speciality: unknown }
 export interface GetSpecialitiesOfferedResponse { suggestions: unknown }
 export interface GetSpecialitiesResponse { specialities: unknown }
 export interface GetSsoPubkeyResponse { alg: unknown; format: unknown; public_key_b64: unknown }
+export interface GetStoreEntitlementsResponse { entitlements: unknown }
 export interface GetTaskRecommendationsForMeResponse { recommendations: unknown; count: unknown }
 export interface GetTaskRecommendationsMineResponse { recommendations: unknown; count: unknown }
 export interface GetTasksClaimableResponse { claimable: unknown; claimable_total: unknown; active_claims: unknown }
@@ -562,6 +563,8 @@ export interface BongosClient {
     getAuthWebAdmissionStatus(args?: RequestArgs): Promise<GetAuthWebAdmissionStatusResponse>;
     /** GET /auth/web/callback — rank: public */
     getAuthWebCallback(args?: RequestArgs): Promise<ApiResponse>;
+    /** GET /auth/web/handoff — rank: public */
+    getAuthWebHandoff(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /auth/web/start — rank: public */
     getAuthWebStart(args?: RequestArgs): Promise<ApiResponse>;
   };
@@ -1368,6 +1371,10 @@ export interface BongosClient {
     postSsoToken(args: RequestArgs & { body: PostSsoTokenRequest }): Promise<PostSsoTokenResponse>;
   };
   "store": {
+    /** GET /store/entitlements — rank: any-builder */
+    getStoreEntitlements(args?: RequestArgs): Promise<GetStoreEntitlementsResponse>;
+    /** GET /store/modules/{key}/entitlement — rank: any-builder */
+    getStoreModulesKeyEntitlement(args?: RequestArgs): Promise<ApiResponse>;
     /** POST /store/modules/{key}/versions — rank: metic+archon */
     postStoreModulesKeyVersions(args?: RequestArgs): Promise<PostStoreModulesKeyVersionsResponse>;
   };

package/clients/bongos-client/index.mjs

@@ -159,6 +159,8 @@ export function createClient(opts = {}) {
       getAuthWebAdmissionStatus: (args) => request("GET", "/auth/web/admission-status", { hasBody: false }, args),
       // GET /auth/web/callback — rank: public — GET /auth/web/callback
       getAuthWebCallback: (args) => request("GET", "/auth/web/callback", { hasBody: false }, args),
+      // GET /auth/web/handoff — rank: public — GET /auth/web/handoff
+      getAuthWebHandoff: (args) => request("GET", "/auth/web/handoff", { hasBody: false }, args),
       // GET /auth/web/start — rank: public — GET /auth/web/start
       getAuthWebStart: (args) => request("GET", "/auth/web/start", { hasBody: false }, args),
     },
@@ -965,6 +967,10 @@ export function createClient(opts = {}) {
       postSsoToken: (args) => request("POST", "/sso/token", { hasBody: true }, args),
     },
     "store": {
+      // GET /store/entitlements — rank: any-builder — GET /store/entitlements
+      getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // GET /store/modules/{key}/entitlement — rank: any-builder — GET /store/modules/:key/entitlement
+      getStoreModulesKeyEntitlement: (args) => request("GET", "/store/modules/{key}/entitlement", { hasBody: false }, args),
       // POST /store/modules/{key}/versions — rank: metic+archon — POST /store/modules/:key/versions
       postStoreModulesKeyVersions: (args) => request("POST", "/store/modules/{key}/versions", { hasBody: true }, args),
     },

package/docs/adr/0145-free-hosted-project-tier-isolation-and-domain-separation.md

@@ -1,5 +1,12 @@
 # 0145 — A free "own-repo" hosted project tier needs domain separation + per-project isolation (not a bare cloudbongos.com subdomain)
 
+- **Status update 2026-09-29 — Finding 1 is FIXED by host-only hub cookies ([task 1004357](https://cloudbongos.com/builders#/task/1004357); build sequence step 1, the cookie half).** Option A was chosen over a separate registrable domain for halls: it needs no new domain, no DNS or TLS work and no change to any project's address, and it closes the hole for every hall already live. What changed, all in `src/bongos/routes/auth.js`:
+  - **Nothing the hub sets carries a `Domain` attribute any more.** The session is `__Host-bongos_session` over https (a browser only accepts a `__Host-` cookie that is Secure, `Path=/` and host-only), plain `bongos_session` on local http. The OAuth and Discord handshake cookies are host-only too.
+  - **`builders.` / `status.` / `www.` get the session through a one-time handoff.** A sign-in begun on one of them restarts on the canonical host (the only host the GitHub callback reaches). The canonical host then redirects back with a single-use, 60-second code bound to that one host, and `GET /auth/web/handoff` trades it for that host's own host-only copy of the same token. A builder already signed in on the apex who opens `builders.` skips GitHub entirely. A code is only ever minted for one of the hub's four hosts, never a hall.
+  - **Existing browsers are moved over.** Every hub API request that carries a pre-fix session cookie and no `__Host-` one re-issues the same token host-only and expires the apex-scoped copy.
+  - **Proof:** `tests/hub_cookie_host_only.mjs` runs the real router through an RFC 6265 cookie jar and asserts a hall at `<handle>.<apex>` receives no hub cookie after the full flow.
+  - **Still open from step 1:** CSRF tokens on state-changing hub endpoints. `SameSite=Lax` does not separate a hall from the hub, because they are the same site. The legacy session names are still ACCEPTED on read (so nobody was signed out at deploy), which leaves a hall able to plant a cookie under an old name. Retiring those names (task 1003706's Part 4) closes that. A token copied by a hall BEFORE this shipped stays valid until it expires or its builder signs out.
+
 - **Status update 2026-09-28 — Finding 1 is OPEN again, and permanently ([ADR 0345](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) decision 6).** Project halls now stay hosted on our box, so ADR 0323's "closed by removing its precondition" below no longer holds. Measured: the hub still sets `Domain=.cloudbongos.com`, and a hall loads modules from its own repository, so a hall at one of our addresses can read a visiting hub builder's session. The sign-in hardening is a **blocking prerequisite again** for any new hall at one of our addresses, filed as [task 1004357](https://cloudbongos.com/builders#/task/1004357). A hall on the owner's own domain is not exposed.
 - **Status:** **Superseded in part by [ADR 0323](0323-hosting-is-three-shapes-and-we-are-not-the-landlord.md)** (2026-09-21). Three of this ADR's decisions are replaced: the free tier becomes a **capped trial**, not all-free; customer projects leave the shared box for a managed platform, so **container isolation on our own box is no longer the plan**; and **Finding 1 is closed by removing its precondition** — with no customer code on a `cloudbongos.com` subdomain there is no tenant to receive the hub session cookie, so the sign-in hardening in the build sequence below is no longer a blocking prerequisite (it remains worth doing on its own merits). The two security FINDINGS below stand as analysis and are the reason the new direction is safe.
 - **Status:** Accepted — owner decided 2026-07-15: **keep `cloudbongos.com`** (no separate domain), **container** isolation, **all-free** for now. Choosing the literal same domain makes hardening core sign-in a required prerequisite (see "Decisions" + "Required build sequence"). Build unblocked ([task 1002251](https://cloudbongos.com/builders#/task/1002251)); blocker 1000080 resolved.

package/docs/api/openapi.json

@@ -1662,6 +1662,27 @@
         "security": []
       }
     },
+    "/auth/web/handoff": {
+      "get": {
+        "operationId": "get_auth_web_handoff",
+        "tags": [
+          "auth"
+        ],
+        "summary": "GET /auth/web/handoff",
+        "description": "GET /auth/web/handoff?code=&return= — the far side of the one-time session handoff (task 1004357). The canonical host minted `code` for THIS host after a sign-in (or for a builder already signed in there); trading it sets this host's own host-only copy of the session, then lands on `return` — a relative path only, so the handoff can never become an open redirect. rank: public — auth establishment; the one-time code is the bearer, bound to this exact host, single-use and alive for HANDOFF_TTL_MS.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/auth.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/auth/web/start": {
       "get": {
         "operationId": "get_auth_web_start",
@@ -17691,6 +17712,89 @@
         "security": []
       }
     },
+    "/store/entitlements": {
+      "get": {
+        "operationId": "get_store_entitlements",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/entitlements",
+        "description": "GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the read side of the entitlement record (task 1003813, ADR 0338 D1). Own-scoped like /me/sessions: the holder is ALWAYS the caller (holder_kind 'builder', holder_ref = req.builder.id), never named in the query or path, so requireBuilder alone is the gate and one builder cannot read another's holdings. Granting has no route yet: install (task 1003785) grants a free module, area 8's buy action grants a paid one — both through src/bongos/module-entitlements.js.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/modules.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetStoreEntitlementsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/store/modules/{key}/entitlement": {
+      "get": {
+        "operationId": "get_store_modules_key_entitlement",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/modules/:key/entitlement",
+        "description": "**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/modules.js",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `key`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/store/modules/{key}/versions": {
       "post": {
         "operationId": "post_store_modules_key_versions",
@@ -22320,6 +22424,15 @@
           "public_key_b64"
         ]
       },
+      "GetStoreEntitlementsResponse": {
+        "type": "object",
+        "properties": {
+          "entitlements": {}
+        },
+        "required": [
+          "entitlements"
+        ]
+      },
       "GetTaskRecommendationsForMeResponse": {
         "type": "object",
         "properties": {
@@ -27716,9 +27829,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 433,
-  "x-schema-count": 466,
+  "x-endpoint-count": 436,
+  "x-schema-count": 467,
   "x-undocumented-bodies": 11,
-  "x-response-schemas": 319,
+  "x-response-schemas": 320,
   "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. 433 endpoints across 75 route files.
+> **Generated from the live route files** — the route file is authoritative. 436 endpoints across 75 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`.
@@ -61,7 +61,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/audit-log` | `metic+archon` | — | GET /api/bongos/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. |
 
-## `auth` (14)
+## `auth` (15)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -78,6 +78,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/auth/revoke-all` | `archon` | `builder_id` | POST /auth/revoke-all — V3.R38 / task 259. |
 | GET | `/api/bongos/auth/web/admission-status` | `public` | — | GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage polls (task 1002097). |
 | GET | `/api/bongos/auth/web/callback` | `public` | — | OAuth callback; the state cookie + code are the bearer. |
+| GET | `/api/bongos/auth/web/handoff` | `public` | — | GET /auth/web/handoff?code=&return= — the far side of the one-time session handoff (task 1004357). |
 | GET | `/api/bongos/auth/web/start` | `public` | — | /auth/web — browser flow (used by the /builders page). |
 
 ## `autonomy` (8)
@@ -693,10 +694,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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. |
 
-## `store` (1)
+## `store` (3)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/store/entitlements` | `any-builder` | — | GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the read side of the entitlement record (task 1003813, ADR 0338 … |
+| GET | `/api/bongos/store/modules/:key/entitlement` | `any-builder` | — |  |
 | POST | `/api/bongos/store/modules/:key/versions` | `metic+archon` | _undocumented_ | POST /api/bongos/store/modules/:key/versions — publish one module version to the store (task 1004271, ADR 0338 D1). |
 
 ## `task-recommendations` (4)

package/docs/architecture.md

@@ -233,6 +233,22 @@ store_module_prices(id, module_key, price_cents, price_credits, set_by, set_at)
               -- in that currency, at least one must be set.
 ```
 
+Module entitlements (migration `core_259`, task 1003813 — who holds which module, at which version; the record install, update and the telemetry signals consult; it records ownership, never payment — area 8 owns money):
+
+```
+module_entitlements(id, module_key, holder_kind IN (builder|instance), holder_ref,
+              source IN (free|core|grant|purchase), payment_ref (opaque, area 8's),
+              version exact X.Y.Z | NULL, acquired_at, granted_by, granted_at,
+              revoked_at, revoked_reason, UNIQUE(module_key, holder_kind, holder_ref))
+              -- module_key is NOT an FK: a core-bundled module has no store row and
+              -- holds an entitlement like any other. Ownership is per module; an update
+              -- moves `version` forward, never asks for a second purchase. A delist never
+              -- touches it (ADR 0338 D2); only revoke (refund, task 1003789) ends a hold,
+              -- keeping the row.
+```
+
+Code: `src/bongos/module-entitlements.js` (`grantEntitlement`, `recordAcquired`, `revokeEntitlement`, `checkEntitlement`, `listEntitlements`). Read routes (own-scoped, `requireBuilder`): `GET /store/entitlements`, `GET /store/modules/:key/entitlement`. No grant route yet: install (task 1003785) grants a free module, the buy action (area 8) 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).
 
 **Bongos API (`/api/bongos/*`, mounted in the same Node process):**

package/docs/module-api-changelog.md

@@ -2643,5 +2643,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         the doorway loses nothing inside 1.x; it goes at the next MAJOR.
   1.19.1076 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1075 with no explicit bump. run 36523068301. (task 1002620)
+  1.19.1077 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1076 with no explicit bump. run 36558431394. (task 1002620)
+  1.19.1078 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1077 with no explicit bump. run 36600137276. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_259_module_entitlements.sql

@@ -0,0 +1,58 @@
+-- core_259_module_entitlements.sql — who holds which module, and at which version.
+--
+-- task 1003813 (goal 1000091, working area 5). ADR 0338 D1: the store checks an
+-- entitlement before it serves a tarball, and install (1003785), update (1003786)
+-- and the install/reliability signals (1003793) all read it. This is the durable
+-- meaning of "bought" — and deliberately NOT the act of paying. Granting an
+-- entitlement is area 5's; taking money, balances and payout are area 8's (goal
+-- 1000092) and are not modelled here. The one seam is `payment_ref`: an opaque
+-- text pointer area 8 can fill when it wires the buy action, never read by us.
+--
+--   module_entitlements  one row per (module, holder). The holder is a builder or
+--                        an instance, named by (holder_kind, holder_ref).
+--                        `source` says how it came to be held: 'free' (a zero-price
+--                        store module), 'core' (bundled with core), 'grant' (a
+--                        person gave it, no payment), 'purchase' (area 8 will
+--                        write this). Every source is the same row, so free and
+--                        core modules go through exactly the record a paid one does.
+--                        `version` is the exact X.Y.Z the holder last acquired —
+--                        NULL until the first acquisition. Ownership is per MODULE:
+--                        an update moves `version` forward and never asks for a
+--                        second purchase (task 1003786).
+--
+-- module_key is deliberately NOT a foreign key to store_modules: a core-bundled
+-- module has no store row, and it must hold an entitlement like any other.
+-- A delist never touches this table (ADR 0338 D2: an entitlement is never revoked
+-- by a delist); the only thing that ends one is `revoked_at`, set by the refund
+-- path (task 1003789). A revoked row is kept, not deleted, so history stays
+-- answerable, and a re-grant clears `revoked_at` on the same row.
+--
+-- Additive only (a new table), so forward-safe. Idempotent: safe to re-run.
+
+CREATE TABLE IF NOT EXISTS module_entitlements (
+  id             bigserial PRIMARY KEY,
+  module_key     text NOT NULL
+                   CHECK (module_key ~ '^[a-z][a-z0-9-]*$'),
+  holder_kind    text NOT NULL
+                   CHECK (holder_kind IN ('builder', 'instance')),
+  holder_ref     text NOT NULL CHECK (length(holder_ref) > 0),
+  source         text NOT NULL
+                   CHECK (source IN ('free', 'core', 'grant', 'purchase')),
+  payment_ref    text,
+  version        text
+                   CHECK (version IS NULL OR version ~ '^[0-9]+\.[0-9]+\.[0-9]+$'),
+  acquired_at    timestamptz,
+  granted_by     bigint REFERENCES builders(id),
+  granted_at     timestamptz NOT NULL DEFAULT now(),
+  revoked_at     timestamptz,
+  revoked_reason text,
+  UNIQUE (module_key, holder_kind, holder_ref),
+  CHECK ((version IS NULL) = (acquired_at IS NULL)),
+  CHECK ((revoked_at IS NULL) = (revoked_reason IS NULL))
+);
+
+CREATE INDEX IF NOT EXISTS idx_module_entitlements_holder
+  ON module_entitlements (holder_kind, holder_ref);
+
+INSERT INTO schema_migrations (version) VALUES ('core_259_module_entitlements')
+  ON CONFLICT (version) DO NOTHING;