@bongos/core 1.19.1078 → 1.19.1079

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1078",
-  "core_contract": "1.19.1078",
-  "source_commit": "411c9ed509c000585d51b84c04a797ec9b15f67d",
+  "core_version": "1.19.1079",
+  "core_contract": "1.19.1079",
+  "source_commit": "0383ae383a565f9a6b3c9cef65e5db1a25fda1b8",
   "source_ref": "HEAD",
-  "built_at": "2026-09-29T16:46:58.351Z",
+  "built_at": "2026-09-29T17:08:08.029Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 550,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2533,
+    "functional_verbatim": 2534,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3109,
-  "tree_sha256": "391c5cd61e61bb87908e73e23c99d7e86ea0f2467f47dfd2a63ebb2b475f435b",
+  "file_count": 3110,
+  "tree_sha256": "09c2966aeb5069bc3a6d9f1f306e4d993ec3f09da7b4136e4cab9b93e0f3e690",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -322,12 +322,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "aa2d78e23e985228caf64e4b9bdacc0caa55f07f1b0d883520b5a97e112427b2"
+      "sha256": "8aa624b247e99bb0a7e3a97745ecd4aa64d7fdddc89d92f47cb20d433d2ad5b0"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "1267fb539bb527d61edc8b3372eca5f4e9b478b8bf2f23c5aed3760ad4d1d09c"
+      "sha256": "510df3006216f3a54f88d90e802d565cc52753ab723061787229ee3d65bd5c83"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -337,17 +337,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "4a5ca3b3f81ecc0d068f4456662342c2be6c609668c730bf8b90eb255ac6590f"
+      "sha256": "3e76df3485bb6fb4555e2b85b6637104718eee1fd325f9a951641dc971833295"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "3f262f4b629221e5ac75344d23d2b07d51a8003b91567f1a7e96f6b354695e46"
+      "sha256": "129e807451025dd8346054523b1829db460319c04c640b9e78af39ba012c73bc"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "aa9e5ed9bf436f0e0eb28eb6a14a394668f614c5d30bdb31eb7bcd92335ff456"
+      "sha256": "de3ceb5761e334327e7e6367acc8dc4daea75561c1b17c967bb0b7fc43aa7dc1"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2207,17 +2207,17 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "4cbfdf33670b1e7cfa9e361ef7209af719da5440fee486f2634a00ab2d8ded64"
+      "sha256": "db6392644382a35358daedffe8289ba644ee4d005e842110271702966a8e7cd3"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "ee67c19d724bde053b4dbcb711c05cf8d1d14cb3b6ff15c198739fd368c8356d"
+      "sha256": "b3795bc67242cfbebf5cd0023327dfc768293fbe09b5998b3c0c2a8f26754ea0"
     },
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "c806ee6970ef09f4ee4da68b11b38e9e80bf6c37a71e63833ef3a491b9d1afde"
+      "sha256": "cb0de2130b810b17ba5b79cc52a6bf4594e84d9aa2d88405be7dd96f66e3cf06"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2742,12 +2742,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e366a77119b50c3c36bfb3219a3cd873b1e36f735b7a150a199cab20ac40fc65"
+      "sha256": "cd8f1a1404e5c2fc789d2efa06eb513c165de83c6c9af94350ec8fbaf90a897a"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "7cd6e586e2763199194c3b5752c618ed2eaa728499800c5383d78b0c21869370"
+      "sha256": "31b76c94f9c9703249328a9faa71a87e79e644c41ba41acb7c7209135ccbcb21"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -8602,12 +8602,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3e6637987df0fac5b562427c291eb8b9ee03af1b4d84bdc96845fdc3f0616198"
+      "sha256": "b94499c149cab0d2b61e2c16da48bdc29e750538aa9c60363cf4d4cc0511b145"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "6cfe5fc0e9b764a9e597bb45806a6f5876dd340c3dbedf3101ec20609546bd26"
+      "sha256": "fc349b40ca4dc25724895e0982b5b689b4ed60e44b1eb567ffc1bbd620977ed9"
     },
     {
       "path": "public-docs/index.html",
@@ -8627,7 +8627,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "6c995cf2f60c9bca1bf378e3687ada8fe7963c5b18bf45b78bd92e0ee414c88b"
+      "sha256": "5a79e67ac4a575bc5d0f4a1d8b2e38e4adc746bacaac066d02cea4698e39d79b"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9452,12 +9452,12 @@
     {
       "path": "scripts/gds/module-artifact.js",
       "mode": "0000644",
-      "sha256": "5f20d948077635bd07a4a840577ead7a07adbb5f6a94ac4e892c3426161ef2bf"
+      "sha256": "09211dcd5bae4b935b5f80a2c021a1c10a376236b1c7ea7ebc1f53b84d1ead40"
     },
     {
       "path": "scripts/gds/module.js",
       "mode": "0000644",
-      "sha256": "fed0e897534be08932018b1048a09bafdade0c242a5eb8f9693ff50a5e354d51"
+      "sha256": "eccf6ccfa68342268d8d63ebde68af4402ff3c6cfcecec2262656801e24bf263"
     },
     {
       "path": "scripts/gds/newcomer-floor.config.json",
@@ -10497,7 +10497,7 @@
     {
       "path": "src/bongos/module-store.js",
       "mode": "0000644",
-      "sha256": "312e7dda5cbeb9a257864f43e486e857c8127683254b4c4fab68bdbfc61a1972"
+      "sha256": "2bc2e05af26a1e416fb083dda7cfce7e7693a56dccd46f7d1f233343ec73d215"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -10632,7 +10632,7 @@
     {
       "path": "src/bongos/routes/modules.js",
       "mode": "0000644",
-      "sha256": "e349115a6adea7e97eaf91d2a5fde6d17c90ac80d8f4be579c890ce4a593ef66"
+      "sha256": "bd4e80ff8712d0797a62bddb3577f52f4cf161ac2273028e8a8def0455118e63"
     },
     {
       "path": "src/bongos/routes/my-sessions.js",
@@ -10702,7 +10702,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "28d2a831a69f59cc426c1e318991e4ab0755abd3303cc5786e88b72988e97a5c"
+      "sha256": "b65c0562481a90446f4881d84eeda91c28949f216835e6a0bab6105755403932"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13559,6 +13559,11 @@
       "mode": "0000644",
       "sha256": "b84800d125bff6227c4c47edc0b606ee5c458248cca247b9d9df92568af55d55"
     },
+    {
+      "path": "tests/module_install.mjs",
+      "mode": "0000644",
+      "sha256": "7aea6f842ba53a4a00a7857d0e406575ebcd9831cd17eb7f1a1ac88b99af88c6"
+    },
     {
       "path": "tests/module_loader.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`)
-- 436 operations across 67 resource groups
+- 439 operations across 67 resource groups
 
 ## Use it from your project
 

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

@@ -973,10 +973,16 @@ function createClient(opts = {}) {
     "store": {
       // GET /store/entitlements — rank: any-builder — GET /store/entitlements
       getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // POST /store/modules/{key}/acquire — rank: any-builder — POST /store/modules/:key/acquire
+      postStoreModulesKeyAcquire: (args) => request("POST", "/store/modules/{key}/acquire", { hasBody: true }, args),
+      // POST /store/modules/{key}/acquired — rank: any-builder — POST /store/modules/:key/acquired
+      postStoreModulesKeyAcquired: (args) => request("POST", "/store/modules/{key}/acquired", { hasBody: true }, 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),
+      // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
+      getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },
     "taskRecommendations": {
       // POST /task-recommendations — rank: any-builder — POST /task-recommendations

package/clients/bongos-client/index.cjs

@@ -972,10 +972,16 @@ function createClient(opts = {}) {
     "store": {
       // GET /store/entitlements — rank: any-builder — GET /store/entitlements
       getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // POST /store/modules/{key}/acquire — rank: any-builder — POST /store/modules/:key/acquire
+      postStoreModulesKeyAcquire: (args) => request("POST", "/store/modules/{key}/acquire", { hasBody: true }, args),
+      // POST /store/modules/{key}/acquired — rank: any-builder — POST /store/modules/:key/acquired
+      postStoreModulesKeyAcquired: (args) => request("POST", "/store/modules/{key}/acquired", { hasBody: true }, 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),
+      // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
+      getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },
     "taskRecommendations": {
       // POST /task-recommendations — rank: any-builder — POST /task-recommendations

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

@@ -430,6 +430,10 @@ export interface PostSsoMembershipCheckInRequest { client_id: string; client_sec
 export interface PostSsoMembershipCheckInResponse { ok: boolean }
 export interface PostSsoTokenRequest { client_id: string; client_secret: string; code: string; redirect_uri: string }
 export interface PostSsoTokenResponse { github_id: unknown; github_login: unknown; display_name: unknown; avatar_url: unknown }
+export interface PostStoreModulesKeyAcquireRequest { version?: string }
+export interface PostStoreModulesKeyAcquireResponse { ok: boolean; module_key: unknown; version: unknown; core_version: unknown; tarball_sha256: unknown; tree_sha256: unknown; tarball_bytes: unknown; channel: unknown; entitlement: unknown }
+export interface PostStoreModulesKeyAcquiredRequest { version: string }
+export interface PostStoreModulesKeyAcquiredResponse { ok: boolean; entitlement: unknown }
 export interface PostStoreModulesKeyVersionsResponse { ok: boolean; created_module: unknown; version: unknown }
 export interface PostTaskRecommendationsRequest { task_id: number; recommended_to: number; reason: string }
 export interface PostTaskRecommendationsResponse { ok: boolean; recommendation: unknown }
@@ -1373,10 +1377,16 @@ export interface BongosClient {
   "store": {
     /** GET /store/entitlements — rank: any-builder */
     getStoreEntitlements(args?: RequestArgs): Promise<GetStoreEntitlementsResponse>;
+    /** POST /store/modules/{key}/acquire — rank: any-builder */
+    postStoreModulesKeyAcquire(args?: RequestArgs & { body?: PostStoreModulesKeyAcquireRequest }): Promise<PostStoreModulesKeyAcquireResponse>;
+    /** POST /store/modules/{key}/acquired — rank: any-builder */
+    postStoreModulesKeyAcquired(args: RequestArgs & { body: PostStoreModulesKeyAcquiredRequest }): Promise<PostStoreModulesKeyAcquiredResponse>;
     /** 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>;
+    /** GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder */
+    getStoreModulesKeyVersionsVersionTarball(args?: RequestArgs): Promise<ApiResponse>;
   };
   "taskRecommendations": {
     /** POST /task-recommendations — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -969,10 +969,16 @@ export function createClient(opts = {}) {
     "store": {
       // GET /store/entitlements — rank: any-builder — GET /store/entitlements
       getStoreEntitlements: (args) => request("GET", "/store/entitlements", { hasBody: false }, args),
+      // POST /store/modules/{key}/acquire — rank: any-builder — POST /store/modules/:key/acquire
+      postStoreModulesKeyAcquire: (args) => request("POST", "/store/modules/{key}/acquire", { hasBody: true }, args),
+      // POST /store/modules/{key}/acquired — rank: any-builder — POST /store/modules/:key/acquired
+      postStoreModulesKeyAcquired: (args) => request("POST", "/store/modules/{key}/acquired", { hasBody: true }, 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),
+      // GET /store/modules/{key}/versions/{version}/tarball — rank: any-builder — GET /store/modules/:key/versions/:version/tarball
+      getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
     },
     "taskRecommendations": {
       // POST /task-recommendations — rank: any-builder — POST /task-recommendations

package/docs/api/openapi.json

@@ -17750,6 +17750,132 @@
         ]
       }
     },
+    "/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",
@@ -17863,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",
@@ -26947,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": {
@@ -27829,9 +28072,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 436,
-  "x-schema-count": 467,
+  "x-endpoint-count": 439,
+  "x-schema-count": 471,
   "x-undocumented-bodies": 11,
-  "x-response-schemas": 320,
+  "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. 436 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,13 +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` (3)
+## `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

@@ -247,7 +247,7 @@ module_entitlements(id, module_key, holder_kind IN (builder|instance), holder_re
               -- 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.
+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).
 
@@ -261,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

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