@bongos/core 1.19.1077 → 1.19.1079

package/docs/api/openapi.json

@@ -17712,6 +17712,215 @@
         "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}/acquire": {
+      "post": {
+        "operationId": "post_store_modules_key_acquire",
+        "tags": [
+          "store"
+        ],
+        "summary": "POST /store/modules/:key/acquire",
+        "description": "---- install: acquire → download → record (task 1003785, ADR 0338 D1) ---- The server end of `bongos module install`. Three steps, so the store never records a version as acquired that the caller did not verify and place: 1. POST acquire — resolve the version, and take the entitlement: a free module (no price, or a zero price) is granted here with source 'free'; a priced one needs the buy action, which is area 8's (tasks 1003788/1003789) and answers 402 until then. 2. GET tarball — served only to a LIVE entitlement holder, never for a delisted module (ADR 0338 D2: no further versions served). 3. POST acquired — the CLI has verified the bytes with verifyModuleArtifact and placed them; recordAcquired stamps the exact version. Own-scoped like the entitlement reads: the holder is always the caller (holder_kind 'builder'), never named in the request, so requireBuilder is the gate — any signed-in builder may take a free module for themselves, and nothing here changes what runs on this instance (install never enables; the CLI places files on the CALLER's checkout). Channels: every version is on the general channel until the channel table (task 1003815) and \"install honours the channel\" (task 1003805) land; those add the channel check to step 1 and step 2, beside the entitlement check.\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",
+        "parameters": [
+          {
+            "name": "key",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `key`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostStoreModulesKeyAcquireRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostStoreModulesKeyAcquireResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/store/modules/{key}/acquired": {
+      "post": {
+        "operationId": "post_store_modules_key_acquired",
+        "tags": [
+          "store"
+        ],
+        "summary": "POST /store/modules/:key/acquired",
+        "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`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostStoreModulesKeyAcquiredRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostStoreModulesKeyAcquiredResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "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",
@@ -17780,6 +17989,60 @@
         ]
       }
     },
+    "/store/modules/{key}/versions/{version}/tarball": {
+      "get": {
+        "operationId": "get_store_modules_key_versions_version_tarball",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/modules/:key/versions/:version/tarball",
+        "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`."
+          },
+          {
+            "name": "version",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `version`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
     "/task-recommendations": {
       "post": {
         "operationId": "post_task_recommendations",
@@ -22341,6 +22604,15 @@
           "public_key_b64"
         ]
       },
+      "GetStoreEntitlementsResponse": {
+        "type": "object",
+        "properties": {
+          "entitlements": {}
+        },
+        "required": [
+          "entitlements"
+        ]
+      },
       "GetTaskRecommendationsForMeResponse": {
         "type": "object",
         "properties": {
@@ -26855,6 +27127,69 @@
           "avatar_url"
         ]
       },
+      "PostStoreModulesKeyAcquireRequest": {
+        "type": "object",
+        "properties": {
+          "version": {
+            "type": "string",
+            "maxLength": 32
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostStoreModulesKeyAcquireResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "module_key": {},
+          "version": {},
+          "core_version": {},
+          "tarball_sha256": {},
+          "tree_sha256": {},
+          "tarball_bytes": {},
+          "channel": {},
+          "entitlement": {}
+        },
+        "required": [
+          "ok",
+          "module_key",
+          "version",
+          "core_version",
+          "tarball_sha256",
+          "tree_sha256",
+          "tarball_bytes",
+          "channel",
+          "entitlement"
+        ]
+      },
+      "PostStoreModulesKeyAcquiredRequest": {
+        "type": "object",
+        "properties": {
+          "version": {
+            "type": "string",
+            "maxLength": 32
+          }
+        },
+        "required": [
+          "version"
+        ],
+        "additionalProperties": false
+      },
+      "PostStoreModulesKeyAcquiredResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "entitlement": {}
+        },
+        "required": [
+          "ok",
+          "entitlement"
+        ]
+      },
       "PostStoreModulesKeyVersionsResponse": {
         "type": "object",
         "properties": {
@@ -27737,9 +28072,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 434,
-  "x-schema-count": 466,
+  "x-endpoint-count": 439,
+  "x-schema-count": 471,
   "x-undocumented-bodies": 11,
-  "x-response-schemas": 319,
+  "x-response-schemas": 322,
   "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. 439 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,11 +694,16 @@ 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` (6)
 
 | 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 … |
+| POST | `/api/bongos/store/modules/:key/acquire` | `any-builder` | `version` | ---- install: acquire → download → record (task 1003785, ADR 0338 D1) ---- The server end of `bongos module install`. |
+| POST | `/api/bongos/store/modules/:key/acquired` | `any-builder` | `version` |  |
+| 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). |
+| GET | `/api/bongos/store/modules/:key/versions/:version/tarball` | `any-builder` | — |  |
 
 ## `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`. Install (task 1003785) grants a free module through `POST /store/modules/:key/acquire`; the buy action (area 8) will grant a paid one.
+
 Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again in 014 so the new `discipline` column flows through), `version_progress` (rebuilt in 006 to count only leaf tasks for forward-compat with task hierarchy), `tasks_session_fit` (new in 006: derives `fits_session_modes[]` and `credits_per_minute`; rebuilt in 014 for the same SELECT t.* refresh), `task_grades_with_context` (new in 016: joins task_grades × tasks × builders × cost_log so the V4 optimizer has quality-per-dollar in one read).
 
 **Bongos API (`/api/bongos/*`, mounted in the same Node process):**
@@ -245,6 +261,7 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 - Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
 - Criterion rollup + task↔criterion links ([ADR 0025](adr/0025-structured-criterion-task-link.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
 - Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/gds/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under `var/module-store/` and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
+- Module store install (ADR 0338 D1, task 1003785), all `requireBuilder` and own-scoped (the holder is the caller): `POST /store/modules/:key/acquire` (`{version?}`; grants a free entitlement — no price row, or a zero price, is free — or `402 payment_required` for a priced module; refuses a delisted one), `GET /store/modules/:key/versions/:version/tarball` (served only to a live entitlement holder; `X-Tarball-Sha256`), `POST /store/modules/:key/acquired` (`{version}` → `recordAcquired`). Read side in `src/bongos/module-store.js` (`resolveAcquirable`, `isFreePrice`, `versionArtifactFile`). No channel check yet (tasks 1003815, 1003805).
 - Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a checkout with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/0055-server-mediated-branch-publish.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `branch` is optional: without it the server finds the task's own PR by its `task <id>: …` title, and the answer names the `branch` it used and its `branch_source` (`query` / `task_pr`, or `null` with a `branch_hint` when there is no such PR) — never a `400` (task 1003764). When the PR is still open it also carries `merge_driver`, whose `reason` says why it has not merged; on a red PR `failing_tests` names the failing unit tests (read from the `unit-report` commit status the `unit` workflow posts) and `checks_unreadable: true` says the check list is blind because the App lacks `Checks: read` — so an empty `checks[]` is never read as "nothing failed" (task 1003988, ADR 0301). Because the server's credential is the PR's AUTHOR, publish also **assigns the PR to the task's claim holder** and names them in the body (`modules/lifecycle/pr-assign.js`, task 1003991) — best-effort: the 201 carries `pr_assignee` (the login, or `null` when GitHub would not assign it) and a failed assignment never fails the publish. `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (no authenticated `gh` on the machine, or `<PREFIX>_PUSH_VIA_SERVER=1`); a machine with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.
 - Archon monitoring reads backing the `/watch` page (ADR 0036): `GET /builders/roster`, `GET /grades/by-builder[?days=N]` (**archon-only**, [#726](https://example.com/builders#/task/726) — per-builder grade breakdown for the MARKS section; the project-wide aggregate stays public at `/public/grades`), `GET /audit-log`, `GET /override-requests`, `GET /access-requests`, `GET /security/reports`. Personal-prefs writes backing `/settings`: `GET/PATCH /me/skill-prefs`, `PATCH /me/disciplines`.
 - Per-builder "needs" + own Gemini key ([ADR 0073](adr/0073-builder-needs-signal-and-byok-gemini-key.md), [#1013](https://example.com/builders#/task/1013)): `GET /me` now also carries `needs` ({items, action_needed_count} — the consistent "the system needs an input from you" signal; `modules/builder-settings/builder-needs.js` is the SSOT — carved out in BV1.R80, resolved by `GET /me` via the `builder-settings` kernel port — rendered by the hall Standing card + the CLI `printNeedsNudge`). The own-key (pragmatic BYOK) endpoints, all own-scoped: `GET /me/art-key/own` (masked meta — last4 only), `PUT /me/art-key/own` (validate-on-save via a Google list-models call → encrypt with `src/bongos/secret-box.js` → store; `503 storage_not_configured` until `BUILDER_SECRET_KEY` is set, `422 invalid_key` on a bad key), `DELETE /me/art-key/own`. The existing `GET /me/art-key` (shared-key delivery) is extended to also deliver the decrypted own key, which `scripts/gds/fetch-art-key.js` syncs into the local `gemini_api_key` slot (own key wins in the `gen_api.py` cascade).

package/docs/module-api-changelog.md

@@ -2645,5 +2645,9 @@ 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)
+  1.19.1079 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1078 with no explicit bump. run 36602720244. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -357,6 +357,16 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/gd
 - The publish denylist applies (ADR 0098), plus a refusal of credential-named files (`.env*`, `*.pem`, `*.key`, `id_rsa`, …) anywhere in the module. The store re-checks every hash and the denylist itself.
 - Gate: Metic+ (`module.submit`) for now. This is not `bongos module submit`, which proposes a module *into* core.
 
+### 7. Install from the store
+
+`bongos module install <key> [--version X.Y.Z]` acquires a module from the store and places it under the instance's `modules/`. Three calls: `POST /store/modules/:key/acquire` takes your entitlement and names the version (the newest unless you pick one), `GET /store/modules/:key/versions/:version/tarball` downloads it, and once the files are placed, `POST /store/modules/:key/acquired` records the exact version.
+
+- The download is checked with `verifyModuleArtifact`, the same checker the store runs on publish, and must match the version and hashes the store described. A failed check places nothing.
+- A module with no price, or a zero price, is free and granted on the spot. A priced one answers 402 until buying exists (area 8). An entitlement is kept for good, even if a price is added later (ADR 0338 D2).
+- Install never enables. Switch the module on from the hall's Modules tab.
+- A module already on disk is refused; moving one to a newer version is `update`. A module this core cannot mount is refused before download.
+- A delisted module cannot be acquired or downloaded. Channels are not checked yet: every version is general until the channel tasks land.
+
 ## Carving an existing core domain (the `db.js` per-domain pattern)
 
 Most BONGOS-V1 module work is not scaffolding a *new* module — it's **carving an existing core domain out of the monolith** (ADR 0091, criterion C7). The reference carve is the kernel slice `src/bongos/db-kernel.js` (BV1.R69); the feature precedents are `modules/discord/db.js` + `modules/game/db.js`. Every later carve (memory R72, grading R73, …) copies this recipe. The invariant is **OTB byte-identical** at every step — you are *moving* code, not changing behavior.

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.1079",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1077",
+      "version": "1.19.1079",
       "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.1079",
   "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,17 @@
       "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."
+    }
+  ],
+  "1.19.1079": [
+    {
+      "id": "1003785",
+      "text": "You can now install a module from the store with one command. It checks the download is exactly what was published and never switches the module on by itself. Modules without a price are free."
+    }
   ]
 }

package/scripts/gds/module-artifact.js

@@ -141,7 +141,10 @@ function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
 // denylist runs again. Resolves { ok: true, ... } or { ok: false, code, message }.
 // Async so the inflate runs off the event loop (readTarAsync); the rest is one pass
 // over at most READ_LIMITS.maxUnpackedBytes.
-async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES } = {}) {
+// `includeFiles: true` (install, task 1003785) also returns `files`: the module's own
+// files — [{ path, mode, buf }], the inner manifest left out — from the SAME parse the
+// hashes were checked against, so a caller that places them never re-reads the bytes.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES, includeFiles = false } = {}) {
   const fail = (code, message) => ({ ok: false, code, message });
   if (!Buffer.isBuffer(tgz) || tgz.length === 0) return fail('empty_artifact', 'the upload is empty');
   if (tgz.length > maxBytes) return fail('artifact_too_large', `the tarball is over ${maxBytes} bytes`);
@@ -202,11 +205,15 @@ async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES } =
     return fail('bad_manifest', 'the manifest version does not match module.json');
   }
 
-  return {
+  const out = {
     ok: true, manifest, moduleJson,
     version: moduleJson.version, coreVersion: moduleJson.coreVersion,
     treeSha256: treeSha, tarballSha256: sha256hex(tgz), bytes: tgz.length,
   };
+  if (includeFiles) {
+    out.files = [...byName.entries()].map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), buf: e.buf }));
+  }
+  return out;
 }
 
 module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact };