@bongos/core 1.19.1077 → 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.1077",
-  "core_contract": "1.19.1077",
-  "source_commit": "8213cd0b6b6ae2e91300c953bee2bed1d3558da3",
+  "core_version": "1.19.1078",
+  "core_contract": "1.19.1078",
+  "source_commit": "411c9ed509c000585d51b84c04a797ec9b15f67d",
   "source_ref": "HEAD",
-  "built_at": "2026-09-29T10:54:54.299Z",
+  "built_at": "2026-09-29T16:46:58.351Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 550,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2530,
+    "functional_verbatim": 2533,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3106,
-  "tree_sha256": "90651971ad753afab30ed83277bfc27c910ad7279d6264170b9045d3726e1d5f",
+  "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": "9d1e621dcf8b0a3b92cd67f700fd1d48f469d55833b494147e0a4c29be452d37"
+      "sha256": "aa2d78e23e985228caf64e4b9bdacc0caa55f07f1b0d883520b5a97e112427b2"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "9fcd3ca52df7d24f22ee6efcd5a0167af53835ec8bd3ffad139185a7aebb90b0"
+      "sha256": "1267fb539bb527d61edc8b3372eca5f4e9b478b8bf2f23c5aed3760ad4d1d09c"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -337,17 +337,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "0bbe77783e3bf8a1dd8bc594dc28372a8c982be8e10a468f97d17ec8a5ff8cfc"
+      "sha256": "4a5ca3b3f81ecc0d068f4456662342c2be6c609668c730bf8b90eb255ac6590f"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "7aa307fe6518433b5d85216d098c1d4cfedb25995aceb5717113e2233de62f48"
+      "sha256": "3f262f4b629221e5ac75344d23d2b07d51a8003b91567f1a7e96f6b354695e46"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "a9ca2bf984f00e1b6506904f789fccf8acfedd7ca7418322f50713d82680f783"
+      "sha256": "aa9e5ed9bf436f0e0eb28eb6a14a394668f614c5d30bdb31eb7bcd92335ff456"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2207,17 +2207,17 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "1b53174253962c6d9d45d3fc107770fa0af26899c7a638fa2ed8be55712a001c"
+      "sha256": "4cbfdf33670b1e7cfa9e361ef7209af719da5440fee486f2634a00ab2d8ded64"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "efbdeaf4b09c7113ece416afdc79b4a46a4088504d5398ce02afd4d9aa5f917e"
+      "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": "3c225690f0579fca6dbada87f49ee760d816a1135a3ae8ae30dcea4983ccccc8"
+      "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": "f474f9d00b0d9bdcbb709d52ebb4f1e61e24b06ebe698ea4a423a3e67bfd3abe"
+      "sha256": "3e6637987df0fac5b562427c291eb8b9ee03af1b4d84bdc96845fdc3f0616198"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9fcd91f348d585a802db0d0c881b29f64c915c1af4bebe34f3c25d76f322efb8"
+      "sha256": "6cfe5fc0e9b764a9e597bb45806a6f5876dd340c3dbedf3101ec20609546bd26"
     },
     {
       "path": "public-docs/index.html",
@@ -8622,7 +8627,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "797b5505242d566628e1fef62b4afc9e66cc77708ac3115eb48791ff15b763fe"
+      "sha256": "6c995cf2f60c9bca1bf378e3687ada8fe7963c5b18bf45b78bd92e0ee414c88b"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10474,6 +10479,11 @@
       "mode": "0000644",
       "sha256": "efe34f92930419444ec31d84c7787488db4984ea761d1bb77d5375388758e68c"
     },
+    {
+      "path": "src/bongos/module-entitlements.js",
+      "mode": "0000644",
+      "sha256": "917f364b804f25437dea7fe507abe50e9b64cac79b6cc29ac786de0e24350d33"
+    },
     {
       "path": "src/bongos/module-overrides.js",
       "mode": "0000644",
@@ -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": "30a3d4c45217ac814326057165b0ff3f6627a03fb15e80586e6b602bfa9e8514"
+      "sha256": "28d2a831a69f59cc426c1e318991e4ab0755abd3303cc5786e88b72988e97a5c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13539,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",

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`)
-- 434 operations across 67 resource groups
+- 436 operations across 67 resource groups
 
 ## Use it from your project
 

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

@@ -971,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

@@ -970,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 }
@@ -1370,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

@@ -967,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/api/openapi.json

@@ -17712,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",
@@ -22341,6 +22424,15 @@
           "public_key_b64"
         ]
       },
+      "GetStoreEntitlementsResponse": {
+        "type": "object",
+        "properties": {
+          "entitlements": {}
+        },
+        "required": [
+          "entitlements"
+        ]
+      },
       "GetTaskRecommendationsForMeResponse": {
         "type": "object",
         "properties": {
@@ -27737,9 +27829,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 434,
-  "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. 434 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`.
@@ -694,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

@@ -2645,5 +2645,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1077",
+  "version": "1.19.1078",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1077",
+      "version": "1.19.1078",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1077",
+  "version": "1.19.1078",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -7855,5 +7855,11 @@
       "id": "1004357",
       "text": "A project's hall on one of our addresses can no longer read the sign-in of a hub builder who visits it. Hub sign-in cookies now stay on the exact address that set them. builders. and status. still sign you in automatically thr"
     }
+  ],
+  "1.19.1078": [
+    {
+      "id": "1003813",
+      "text": "The store now has a durable record of who owns which module and at which version, so install and update can check it. Free and bundled modules use the same record; nothing charges money yet."
+    }
   ]
 }

package/src/bongos/module-entitlements.js

@@ -0,0 +1,127 @@
+// src/bongos/module-entitlements.js — the entitlement record: who holds which
+// module, at which version (task 1003813, ADR 0338 D1; table core_259).
+//
+// This is the ONE place install, update and the telemetry signals ask "does this
+// holder own this module?" — the store checks it before it serves a tarball. It is
+// the record of ownership, not of payment: a grant needs no money to have moved,
+// so free and core-bundled modules hold an entitlement through the same rows a
+// paid one will (area 8 writes source 'purchase' + payment_ref when it lands).
+//
+// Rules the functions enforce, from ADR 0338 D2:
+//   - ownership is per MODULE, the acquired version moves forward under it, so an
+//     update never asks for a second purchase;
+//   - a delist never reaches this table — only revokeEntitlement ends a hold (the
+//     refund path, task 1003789), and it keeps the row rather than deleting it.
+//
+// Every function takes { db } (a pg Pool or anything with query()) so tests run
+// against a fake client, the way module-store.js does.
+
+const { parseVersion, cmp } = require('../module-loader/semver');
+const { KEY_RE } = require('../module-loader/manifest-schema');
+
+const HOLDER_KINDS = ['builder', 'instance'];
+const SOURCES = ['free', 'core', 'grant', 'purchase'];
+
+const COLS = `id, module_key, holder_kind, holder_ref, source, payment_ref, version,
+  acquired_at, granted_by, granted_at, revoked_at, revoked_reason`;
+
+function poolOf(db) { return db || require('./pool').pool; }
+
+// A bad argument is a programming error in the caller, not a user error: throw.
+function assertHolder(moduleKey, holderKind, holderRef) {
+  if (!KEY_RE.test(String(moduleKey))) throw new Error('entitlement: a bad module key');
+  if (!HOLDER_KINDS.includes(holderKind)) throw new Error(`entitlement: holder_kind must be one of ${HOLDER_KINDS.join(', ')}`);
+  if (typeof holderRef !== 'string' || !holderRef.length) throw new Error('entitlement: holder_ref is required');
+}
+
+// Give a holder a module. Idempotent: granting a holder that already holds it is a
+// no-op that returns the existing row (an earlier source is never rewritten), and
+// granting one whose hold was revoked lifts the revocation on the same row.
+// `source: 'purchase'` is area 8's to use; nothing here checks a payment.
+async function grantEntitlement({ moduleKey, holderKind, holderRef, source, grantedBy = null, paymentRef = null }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  if (!SOURCES.includes(source)) throw new Error(`entitlement: source must be one of ${SOURCES.join(', ')}`);
+  const pool = poolOf(db);
+  const { rows: [fresh] } = await pool.query(
+    `INSERT INTO module_entitlements (module_key, holder_kind, holder_ref, source, payment_ref, granted_by)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     ON CONFLICT (module_key, holder_kind, holder_ref) DO NOTHING
+     RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, source, paymentRef, grantedBy]);
+  if (fresh) return { entitlement: fresh, created: true };
+  const { rows: [held] } = await pool.query(
+    `UPDATE module_entitlements
+        SET revoked_at = NULL, revoked_reason = NULL, source = $4, payment_ref = $5,
+            granted_by = $6, granted_at = now()
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3 AND revoked_at IS NOT NULL
+      RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, source, paymentRef, grantedBy]);
+  if (held) return { entitlement: held, created: false, reinstated: true };
+  const { rows: [same] } = await pool.query(
+    `SELECT ${COLS} FROM module_entitlements WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  return { entitlement: same, created: false };
+}
+
+// Record the exact version a holder acquired. Refuses a holder with no live
+// entitlement (nothing is handed over without one) and a version older than the
+// one already held (an update moves forward; a rollback is a separate act, so it
+// must be asked for with allowDowngrade).
+async function recordAcquired({ moduleKey, holderKind, holderRef, version, allowDowngrade = false }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  const wanted = parseVersion(String(version));
+  if (!wanted) throw new Error('entitlement: version must be exact X.Y.Z');
+  const pool = poolOf(db);
+  const { rows: [cur] } = await pool.query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  if (!cur || cur.revoked_at) return { ok: false, code: 'not_entitled' };
+  const held = cur.version && parseVersion(cur.version);
+  if (held && !allowDowngrade && cmp(wanted, held) < 0) return { ok: false, code: 'version_older_than_held' };
+  const { rows: [row] } = await pool.query(
+    `UPDATE module_entitlements SET version = $2, acquired_at = now()
+      WHERE id = $1 AND revoked_at IS NULL
+      RETURNING ${COLS}`,
+    [cur.id, version]);
+  return row ? { ok: true, entitlement: row } : { ok: false, code: 'not_entitled' };
+}
+
+// End a hold. Only the refund path calls this (task 1003789); a delist must not.
+// The row stays, stamped with when and why.
+async function revokeEntitlement({ moduleKey, holderKind, holderRef, reason }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  if (typeof reason !== 'string' || !reason.trim()) throw new Error('entitlement: a revocation needs a reason');
+  const { rows: [row] } = await poolOf(db).query(
+    `UPDATE module_entitlements SET revoked_at = now(), revoked_reason = $4
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3 AND revoked_at IS NULL
+      RETURNING ${COLS}`,
+    [moduleKey, holderKind, holderRef, reason.trim()]);
+  return row ? { ok: true, entitlement: row } : { ok: false, code: 'not_entitled' };
+}
+
+// The question the store asks before it serves: does this holder hold this module
+// right now? `entitled` is false for no row and for a revoked row; the row itself
+// comes back either way so the caller can say WHY.
+async function checkEntitlement({ moduleKey, holderKind, holderRef }, { db } = {}) {
+  assertHolder(moduleKey, holderKind, holderRef);
+  const { rows: [row] } = await poolOf(db).query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3`,
+    [moduleKey, holderKind, holderRef]);
+  return { entitled: !!row && !row.revoked_at, entitlement: row || null };
+}
+
+// Everything one holder holds (live and revoked), newest grant first.
+async function listEntitlements({ holderKind, holderRef }, { db } = {}) {
+  assertHolder('x', holderKind, holderRef);
+  const { rows } = await poolOf(db).query(
+    `SELECT ${COLS} FROM module_entitlements
+      WHERE holder_kind = $1 AND holder_ref = $2 ORDER BY granted_at DESC, id DESC`,
+    [holderKind, holderRef]);
+  return rows;
+}
+
+module.exports = {
+  grantEntitlement, recordAcquired, revokeEntitlement, checkEntitlement, listEntitlements,
+};

package/src/bongos/routes/modules.js

@@ -23,6 +23,9 @@
 //                               server end of `bongos module publish`. Not the
 //                               upstreaming door above: submit proposes a module
 //                               INTO core; publish puts a version in the store.
+//   GET  /store/entitlements   the modules the caller holds, and at which version
+//   GET  /store/modules/:key/entitlement
+//                               does the caller hold this module (task 1003813).
 //
 // Read is open to any signed-in builder (same gate as the atlas/primer pages);
 // every write (enable/disable, submit) is metic+archon, same rank as
@@ -65,6 +68,7 @@ const modulesLib = require('../../modules');
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
 const moduleArtifact = require('../../../scripts/gds/module-artifact');
+const { checkEntitlement, listEntitlements } = require('../module-entitlements');
 const { stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion } = require('../module-store');
 const { KEY_RE } = require('../../module-loader/manifest-schema');
 // Named imports, not a namespace object (task 1004052 strand walk): knip cannot follow
@@ -347,6 +351,31 @@ module.exports = function buildModulesRouter() {
       res.status(201).json({ ok: true, created_module: result.created, version: result.version });
     }));
 
+  // 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.
+  router.get('/store/entitlements', auth.requireBuilder,
+    asyncHandler('GET /store/entitlements', async (req, res) => {
+      const entitlements = await listEntitlements({ holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json({ entitlements });
+    }));
+
+  router.get('/store/modules/:key/entitlement', auth.requireBuilder,
+    asyncHandler('GET /store/modules/:key/entitlement', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) {
+        return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      }
+      const held = await checkEntitlement({ moduleKey: key, holderKind: 'builder', holderRef: String(req.builder.id) });
+      res.set('Cache-Control', 'no-store');
+      res.json(held);
+    }));
+
   return router;
 };
 

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.19.1077'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1078'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/module_entitlements.mjs

@@ -0,0 +1,204 @@
+// tests/module_entitlements.mjs — the entitlement record (task 1003813, ADR 0338 D1).
+// DB-free: the migration text is pinned directly, and src/bongos/module-entitlements.js
+// runs against a small in-memory stand-in for the one table. The live apply runs in
+// the PG lane and at deploy.
+//
+// Run:  node tests/module_entitlements.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SQL = readFileSync(path.join(ROOT, 'migrations', 'core_259_module_entitlements.sql'), 'utf8');
+const DDL = SQL.replace(/--.*$/gm, '');
+const {
+  grantEntitlement, recordAcquired, revokeEntitlement, checkEntitlement, listEntitlements,
+} = require('../src/bongos/module-entitlements.js');
+
+// ---- an in-memory stand-in for module_entitlements, keyed on the SQL's shape ----
+function fakeDb() {
+  const rows = [];
+  let nextId = 1;
+  const find = (k, kind, ref) => rows.find((r) => r.module_key === k && r.holder_kind === kind && r.holder_ref === ref);
+  return {
+    rows,
+    async query(sql, p) {
+      const s = sql.replace(/\s+/g, ' ');
+      if (s.startsWith('INSERT INTO module_entitlements')) {
+        if (find(p[0], p[1], p[2])) return { rows: [] };
+        const r = { id: nextId++, module_key: p[0], holder_kind: p[1], holder_ref: p[2], source: p[3],
+          payment_ref: p[4], version: null, acquired_at: null, granted_by: p[5], granted_at: new Date(),
+          revoked_at: null, revoked_reason: null };
+        rows.push(r);
+        return { rows: [{ ...r }] };
+      }
+      if (s.startsWith('UPDATE module_entitlements SET revoked_at = NULL')) {
+        const r = find(p[0], p[1], p[2]);
+        if (!r || !r.revoked_at) return { rows: [] };
+        Object.assign(r, { revoked_at: null, revoked_reason: null, source: p[3], payment_ref: p[4], granted_by: p[5] });
+        return { rows: [{ ...r }] };
+      }
+      if (s.startsWith('UPDATE module_entitlements SET version')) {
+        const r = rows.find((x) => x.id === p[0]);
+        if (!r || r.revoked_at) return { rows: [] };
+        Object.assign(r, { version: p[1], acquired_at: new Date() });
+        return { rows: [{ ...r }] };
+      }
+      if (s.startsWith('UPDATE module_entitlements SET revoked_at = now()')) {
+        const r = find(p[0], p[1], p[2]);
+        if (!r || r.revoked_at) return { rows: [] };
+        Object.assign(r, { revoked_at: new Date(), revoked_reason: p[3] });
+        return { rows: [{ ...r }] };
+      }
+      if (s.includes('WHERE holder_kind = $1 AND holder_ref = $2')) {
+        return { rows: rows.filter((r) => r.holder_kind === p[0] && r.holder_ref === p[1]).map((r) => ({ ...r })).reverse() };
+      }
+      if (s.includes('WHERE module_key = $1 AND holder_kind = $2 AND holder_ref = $3')) {
+        const r = find(p[0], p[1], p[2]);
+        return { rows: r ? [{ ...r }] : [] };
+      }
+      throw new Error(`fake db: unhandled SQL: ${s}`);
+    },
+  };
+}
+
+const B = { moduleKey: 'weather', holderKind: 'builder', holderRef: '42' };
+
+// ---- the migration ----
+
+test('one idempotent table, forward-safe under the lint gate', () => {
+  assert.match(DDL, /CREATE TABLE IF NOT EXISTS module_entitlements \(/);
+  assert.doesNotMatch(DDL, /CREATE TABLE (?!IF NOT EXISTS)/);
+  assert.doesNotMatch(DDL, /CREATE INDEX (?!IF NOT EXISTS)/);
+  assert.match(DDL, /INSERT INTO schema_migrations \(version\) VALUES \('core_259_module_entitlements'\)\s+ON CONFLICT \(version\) DO NOTHING;/);
+  const lint = require('../scripts/gds/lint-migrations.js');
+  assert.deepEqual(lint.scanMigrationSql(SQL).unsafe || [], []);
+});
+
+test('a core-bundled module can hold an entitlement: module_key is not a foreign key', () => {
+  assert.doesNotMatch(DDL, /module_key[^,\n]*REFERENCES/);
+  assert.match(DDL, /source\s+text NOT NULL\s+CHECK \(source IN \('free', 'core', 'grant', 'purchase'\)\)/);
+});
+
+test('one row per module and holder; nothing cascades it away', () => {
+  assert.match(DDL, /UNIQUE \(module_key, holder_kind, holder_ref\)/);
+  assert.doesNotMatch(DDL, /ON DELETE CASCADE/);
+});
+
+test('the version is exact semver and moves with its timestamp; a revocation carries its reason', () => {
+  assert.match(DDL, /version IS NULL OR version ~ '\^\[0-9\]\+\\\.\[0-9\]\+\\\.\[0-9\]\+\$'/);
+  assert.match(DDL, /CHECK \(\(version IS NULL\) = \(acquired_at IS NULL\)\)/);
+  assert.match(DDL, /CHECK \(\(revoked_at IS NULL\) = \(revoked_reason IS NULL\)\)/);
+});
+
+test('the record models no balance, fee or payout — only an opaque payment_ref (area 8 owns money)', () => {
+  assert.doesNotMatch(DDL, /balance|payout|\bfee\b|price/i);
+  assert.match(DDL, /payment_ref\s+text,/);
+});
+
+// ---- the functions ----
+
+test('every source is granted through the same record, with no payment involved', async () => {
+  const db = fakeDb();
+  for (const [i, source] of ['free', 'core', 'grant'].entries()) {
+    const r = await grantEntitlement({ ...B, moduleKey: `mod-${i}`, source }, { db });
+    assert.equal(r.created, true);
+    assert.equal(r.entitlement.payment_ref, null);
+    assert.equal((await checkEntitlement({ ...B, moduleKey: `mod-${i}` }, { db })).entitled, true);
+  }
+});
+
+test('granting twice is a no-op that keeps the first source', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'grant', grantedBy: 7 }, { db });
+  const again = await grantEntitlement({ ...B, source: 'free' }, { db });
+  assert.equal(again.created, false);
+  assert.equal(again.entitlement.source, 'grant');
+  assert.equal(db.rows.length, 1);
+});
+
+test('a holder who was never granted is not entitled, and cannot record an acquisition', async () => {
+  const db = fakeDb();
+  assert.deepEqual(await checkEntitlement(B, { db }), { entitled: false, entitlement: null });
+  assert.deepEqual(await recordAcquired({ ...B, version: '1.0.0' }, { db }), { ok: false, code: 'not_entitled' });
+});
+
+test('an update moves the acquired version forward under the same entitlement', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'purchase', paymentRef: 'pay_1' }, { db });
+  assert.equal((await recordAcquired({ ...B, version: '1.9.0' }, { db })).ok, true);
+  const up = await recordAcquired({ ...B, version: '1.10.0' }, { db });
+  assert.equal(up.ok, true, '1.10.0 is newer than 1.9.0 (numeric, not text, order)');
+  assert.equal(up.entitlement.version, '1.10.0');
+  assert.equal(up.entitlement.source, 'purchase', 'an update never rewrites how it was acquired');
+  assert.equal(db.rows.length, 1, 'no second purchase, no second row');
+});
+
+test('an older version is refused unless a rollback is asked for by name', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'free' }, { db });
+  await recordAcquired({ ...B, version: '2.0.0' }, { db });
+  assert.deepEqual(await recordAcquired({ ...B, version: '1.5.0' }, { db }), { ok: false, code: 'version_older_than_held' });
+  assert.equal((await recordAcquired({ ...B, version: '1.5.0', allowDowngrade: true }, { db })).entitlement.version, '1.5.0');
+});
+
+test('a version that is not exact X.Y.Z is a caller error', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'free' }, { db });
+  await assert.rejects(recordAcquired({ ...B, version: '1.0' }, { db }), /exact X\.Y\.Z/);
+  await assert.rejects(recordAcquired({ ...B, version: '^1.0.0' }, { db }), /exact X\.Y\.Z/);
+});
+
+test('revoking keeps the row, stamps why, and stops the entitlement; a re-grant lifts it', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'purchase' }, { db });
+  await recordAcquired({ ...B, version: '1.0.0' }, { db });
+  await assert.rejects(revokeEntitlement({ ...B, reason: '  ' }, { db }), /needs a reason/);
+  const r = await revokeEntitlement({ ...B, reason: 'refunded' }, { db });
+  assert.equal(r.ok, true);
+  assert.equal(db.rows.length, 1, 'kept, never deleted');
+  const held = await checkEntitlement(B, { db });
+  assert.equal(held.entitled, false);
+  assert.equal(held.entitlement.revoked_reason, 'refunded');
+  assert.deepEqual(await recordAcquired({ ...B, version: '1.1.0' }, { db }), { ok: false, code: 'not_entitled' });
+  assert.deepEqual(await revokeEntitlement({ ...B, reason: 'again' }, { db }), { ok: false, code: 'not_entitled' });
+  const back = await grantEntitlement({ ...B, source: 'grant' }, { db });
+  assert.equal(back.reinstated, true);
+  assert.equal((await checkEntitlement(B, { db })).entitled, true);
+  assert.equal(back.entitlement.version, '1.0.0', 'what was acquired is remembered');
+});
+
+test('holdings are per holder: one builder never sees another\'s', async () => {
+  const db = fakeDb();
+  await grantEntitlement({ ...B, source: 'free' }, { db });
+  await grantEntitlement({ ...B, holderRef: '43', source: 'free' }, { db });
+  await grantEntitlement({ ...B, holderKind: 'instance', holderRef: '42', source: 'free' }, { db });
+  const mine = await listEntitlements({ holderKind: 'builder', holderRef: '42' }, { db });
+  assert.equal(mine.length, 1);
+  assert.equal(mine[0].holder_ref, '42');
+});
+
+test('bad arguments throw rather than write', async () => {
+  const db = fakeDb();
+  await assert.rejects(grantEntitlement({ ...B, moduleKey: '../x', source: 'free' }, { db }), /bad module key/);
+  await assert.rejects(grantEntitlement({ ...B, holderKind: 'team', source: 'free' }, { db }), /holder_kind/);
+  await assert.rejects(grantEntitlement({ ...B, source: 'gift' }, { db }), /source must be/);
+  assert.equal(db.rows.length, 0);
+});
+
+// ---- the read routes ----
+
+test('the read routes are own-scoped: gated on requireBuilder, holder taken from the session', () => {
+  const src = readFileSync(path.join(ROOT, 'src/bongos/routes/modules.js'), 'utf8');
+  for (const p of ['/store/entitlements', '/store/modules/:key/entitlement']) {
+    assert.match(src, new RegExp(`router\\.get\\('${p.replace(/[/:.]/g, '\\$&')}', auth\\.requireBuilder,`));
+  }
+  const block = src.slice(src.indexOf("router.get('/store/entitlements'"));
+  assert.match(block, /holderRef: String\(req\.builder\.id\)/);
+  assert.doesNotMatch(block.slice(0, 1600), /req\.(query|body)\./, 'the holder is never named by the caller');
+});