@bongos/core 1.22.2 → 1.23.2

package/clients/bongos-client/index.mjs

@@ -1265,6 +1265,14 @@ export function createClient(opts = {}) {
       getStoreModulesKeyVersionsVersionTarball: (args) => request("GET", "/store/modules/{key}/versions/{version}/tarball", { hasBody: false }, args),
       // GET /store/modules/latest — rank: any-builder — GET /store/modules/latest
       getStoreModulesLatest: (args) => request("GET", "/store/modules/latest", { hasBody: false }, args),
+      // GET /store/subcategories — rank: any-builder — GET /store/subcategories
+      getStoreSubcategories: (args) => request("GET", "/store/subcategories", { hasBody: false }, args),
+      // POST /store/subcategories/{id}/approve — rank: metic+archon — POST /store/subcategories/:id/approve
+      postStoreSubcategoriesIdApprove: (args) => request("POST", "/store/subcategories/{id}/approve", { hasBody: true }, args),
+      // POST /store/subcategories/{id}/merge — rank: metic+archon — POST /store/subcategories/:id/merge
+      postStoreSubcategoriesIdMerge: (args) => request("POST", "/store/subcategories/{id}/merge", { hasBody: true }, args),
+      // GET /store/subcategories/queue — rank: metic+archon — GET /store/subcategories/queue
+      getStoreSubcategoriesQueue: (args) => request("GET", "/store/subcategories/queue", { hasBody: false }, args),
       // GET /store/usage-reporting — rank: any-builder — GET /store/usage-reporting
       getStoreUsageReporting: (args) => request("GET", "/store/usage-reporting", { hasBody: false }, args),
       // POST /store/usage-reporting — rank: any-builder — POST /store/usage-reporting

package/docs/adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md

@@ -66,8 +66,10 @@ scarce.
 - **Task 1003784** (nested category in the manifest and both catalog surfaces) builds to this:
   `category: { parent, sub }`. `parent` is one of the eight keys, and `sub` is the key of an
   approved sub-category or absent while a proposal is pending.
-- **An approval queue** for proposed sub-categories is new work, not yet filed. It needs a
-  Metic+ permission key and follows the same pattern as the score override (task 1003796).
+- **An approval queue** for proposed sub-categories — built in task 1004355: `core_278`'s
+  `store_subcategories` + `store_module_categories`, the Metic+ atom
+  `module.subcategory.review` (`government_033`), and `/store/subcategories/*` (see
+  docs/modules-contract.md, "Getting listed").
 - **Core modules get categories too**, so the catalog is consistent. The table in D1 is their
   starting assignment.
 - **The cap (task 1003809)** counts listed modules per approved sub-category, never per parent.

package/docs/api/openapi.json

@@ -24344,6 +24344,189 @@
         ]
       }
     },
+    "/store/subcategories": {
+      "get": {
+        "operationId": "get_store_subcategories",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/subcategories",
+        "description": "GET /api/bongos/store/subcategories — the approved sub-categories under each of the eight parents (task 1004355, ADR 0342 D3): what an author names in module.json's `category.sub`. A key not on this list is proposed at publish. rank: any-builder — public store metadata; nothing changed.\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."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/store/subcategories/queue": {
+      "get": {
+        "operationId": "get_store_subcategories_queue",
+        "tags": [
+          "store"
+        ],
+        "summary": "GET /store/subcategories/queue",
+        "description": "GET /api/bongos/store/subcategories/queue — the proposals waiting on a Metic+ decision, oldest first, each with the modules that named it and the near-duplicate names beside it (\"Stripe\" next to \"Stripe payments\"), since stopping near-duplicates is the point of the queue (ADR 0342 D3).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.subcategory.review` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.subcategory.review"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/store/subcategories/{id}/approve": {
+      "post": {
+        "operationId": "post_store_subcategories_id_approve",
+        "tags": [
+          "store"
+        ],
+        "summary": "POST /store/subcategories/:id/approve",
+        "description": "POST /api/bongos/store/subcategories/:id/approve { label?, sub_key? } — make a proposal live, optionally renamed first. A rename onto a key that already exists under the parent is refused with the merge to run instead.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.subcategory.review` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.subcategory.review"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostStoreSubcategoriesIdApproveRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/store/subcategories/{id}/merge": {
+      "post": {
+        "operationId": "post_store_subcategories_id_merge",
+        "tags": [
+          "store"
+        ],
+        "summary": "POST /store/subcategories/:id/merge",
+        "description": "POST /api/bongos/store/subcategories/:id/merge { into } — fold a proposal (or an approved duplicate) into an approved sub-category. Every module under it moves to the target.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.subcategory.review` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.subcategory.review"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostStoreSubcategoriesIdMergeRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/store/usage-reporting": {
       "get": {
         "operationId": "get_store_usage_reporting",
@@ -35803,13 +35986,15 @@
           },
           "created_module": {},
           "version": {},
-          "channel": {}
+          "channel": {},
+          "category": {}
         },
         "required": [
           "ok",
           "created_module",
           "version",
-          "channel"
+          "channel",
+          "category"
         ]
       },
       "PostStoreModulesKeyVersionsVersionErrorCountRequest": {
@@ -35905,6 +36090,27 @@
           "reason"
         ]
       },
+      "PostStoreSubcategoriesIdApproveRequest": {
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string",
+            "maxLength": 80
+          },
+          "sub_key": {
+            "type": "string",
+            "maxLength": 80
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostStoreSubcategoriesIdMergeRequest": {
+        "type": "object",
+        "properties": {
+          "into": {}
+        },
+        "additionalProperties": false
+      },
       "PostStoreUsageReportingRequest": {
         "type": "object",
         "properties": {
@@ -36980,8 +37186,8 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 578,
-  "x-schema-count": 622,
+  "x-endpoint-count": 582,
+  "x-schema-count": 624,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 404,
   "x-generated-by": "scripts/bongos/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. 578 endpoints across 98 route files.
+> **Generated from the live route files** — the route file is authoritative. 582 endpoints across 98 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`.
@@ -863,7 +863,7 @@ 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` (18)
+## `store` (22)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -883,6 +883,10 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/store/modules/:key/versions/:version/release` | `metic+archon` | `reason` | POST /api/bongos/store/modules/:key/versions/:version/release — a Metic+ person releases a version the promotion gate HELD on tester (a t… |
 | GET | `/api/bongos/store/modules/:key/versions/:version/tarball` | `any-builder` | — |  |
 | GET | `/api/bongos/store/modules/latest` | `any-builder` | — | The newest published version of each named module — what `bongos upgrade` compares an instance's installed store modules against to repor… |
+| GET | `/api/bongos/store/subcategories` | `any-builder` | — | GET /api/bongos/store/subcategories — the approved sub-categories under each of the eight parents (task 1004355, ADR 0342 D3): what an au… |
+| POST | `/api/bongos/store/subcategories/:id/approve` | `metic+archon` | `label`, `sub_key` | POST /api/bongos/store/subcategories/:id/approve { label?, sub_key? } — make a proposal live, optionally renamed first. |
+| POST | `/api/bongos/store/subcategories/:id/merge` | `metic+archon` | `into` | POST /api/bongos/store/subcategories/:id/merge { into } — fold a proposal (or an approved duplicate) into an approved sub-category. |
+| GET | `/api/bongos/store/subcategories/queue` | `metic+archon` | — | GET /api/bongos/store/subcategories/queue — the proposals waiting on a Metic+ decision, oldest first, each with the modules that named it… |
 | GET | `/api/bongos/store/usage-reporting` | `any-builder` | — | The caller's own reporting switch (Settings → Profile and privacy). |
 | POST | `/api/bongos/store/usage-reporting` | `any-builder` | `enabled` |  |
 

package/docs/architecture.md

@@ -262,6 +262,17 @@ passkey_challenges(challenge PK, purpose, builder_id NULL, created_at, expires_a
               -- single-use (DELETEd on consume), TTL swept; builder_id NULL for sign-in
 ```
 
+Store sub-categories (migration `core_280`, task 1004355, [ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md) D3 — an author proposes one at publish, a Metic+ person approves, renames or merges it; `src/bongos/module-subcategories.js`):
+
+```
+store_subcategories(id, parent one of 8, sub_key, label, status proposed|approved|merged,
+              proposed_by, decided_by, decided_at, merged_into FK self, created_at)
+              -- UNIQUE (parent, sub_key); merged ⇔ merged_into set; proposed ⇔ undecided.
+store_module_categories(module_key PK FK store_modules, parent, subcategory_id FK NULL, updated_at)
+              -- where a module sits now; a merge moves rows here. Only an approved
+              -- sub-category is live for the cap and ranking.
+```
+
 Module release channels (migration `core_276`, task 1003815, [ADR 0344](adr/0344-a-tester-is-a-project-that-opts-in-once.md) — which channel a published version is on; the data only, the tester-first publish, promotion gate and channel-aware install are their own tasks):
 
 ```

package/docs/copy-inventory.md

@@ -1857,7 +1857,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `4de556377db2` | certain | verdict {…} | `modules/hall-ui/public/task.js:432` |
 | `f20985df3729` | certain | version · {…} | `modules/hall-ui/public/sky-interaction.js:38` |
 | `969577b937d6` | certain | versions in flight | `modules/hall-ui/public/roadmap.js:321` |
-| `8cd3cc4005fc` | certain | via goal | `modules/hall-ui/public/dom-utils.js:446` |
+| `8cd3cc4005fc` | certain | via goal | `modules/hall-ui/public/dom-utils.js:450` |
 | `18cf722bdd7e` | certain | waiting · | `modules/hall-ui/public/sky-interaction.js:128` |
 | `354861d3c2ce` | certain | waits for a restart | `modules/hall-ui/public/modules.js:139` |
 | `35be9e0923da` | certain | walks the whole path in plain language. | `modules/hall-ui/public/hall-render.js:841` |

package/docs/copy-registry.json

@@ -18583,7 +18583,7 @@
       "surface": "builders-hall",
       "text": "via goal",
       "file": "modules/hall-ui/public/dom-utils.js",
-      "line": 446,
+      "line": 450,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -3213,5 +3213,13 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.22.0 with no explicit bump. run 40264537233. (task 1002620)
   1.22.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.22.1 with no explicit bump. run 40266740044. (task 1002620)
+  1.23.0 — sleep: THE server-side "wait N milliseconds" (src/sleep.js), so a
+        module waits through one shared copy instead of hand-rolling a Promise
+        around setTimeout (task 1004893; fitness fails on a third copy). Additive,
+        so MINOR. The browser twin is window.OTB.sleep.
+  1.23.1 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.0 with no explicit bump. run 40270556091. (task 1002620)
+  1.23.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.1 with no explicit bump. run 40399986777. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -399,6 +399,7 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/bo
 - **Sorting by a part** (task 1003800). `GET /store/modules?sort=<part>` orders the listed modules by one part a buyer cares about: `tests`, `install`, `reliability`, `tester_feedback` or `docs` (the response lists them as `sort_parts`, and says which one it applied as `sort`). Modules with a score for that part come first, highest first; a tie goes to the higher overall score, then the module key. A module with no score for that part goes last, so missing data never wins or loses a place on its own. New modules are not sorted: they are never ranked. Any other `sort` value is refused with a 400. Without `sort`, the listed modules are in the ranking below; New stays in key order. The rule is `sortByPart` in `src/bongos/module-listing.js`.
 - **The ranking, and a maximum price** (task 1003808, owner decision 2026-10-23). Without `sort`, listed modules are ranked **quality first**: highest overall score first; between equal scores, free modules first, then the lowest cash price, then the lowest credit price, then the module key. Price never buys a better place, it only orders modules the score could not tell apart (and it is never an input to the score, ADR 0343 D6). The response states the rule as `ranking`, and each entry carries its current `price` (`cents`, `credits`, `free`). A buyer may add `?max_cents=` and/or `?max_credits=` (whole numbers, 0 or more): modules that cost more are left out of both lists, free modules always stay, and a priced module stays when it is offered at or under a cap the buyer set. The applied caps come back as `max_price`. The rules are `rankListed` and `withinMaxPrice` in `src/bongos/module-listing.js`.
 - **Why a module is not listed** (task 1003810). `GET /store/modules/:key/listing` says where one module stands, judging the same newest version the catalog does: `listed` (true or false), a `reason` (`not_assessed`, `security_not_passed`, `no_score`, `below_floor`, `delisted`, `no_version`, `new` or `at_or_above_floor`), `why` in a sentence and `next_step` saying what would change it. A failed Security gate is told apart from one that has not finished, and names what it found to the module's author only (to anyone else it would point at a weakness not fixed yet); below the floor names the score, the floor and the weakest parts. It carries the same `parts`, `strengths`, `weaknesses` and `unmeasured` as the catalog, plus `security`. Any signed-in builder can read it. Being past the cap of ten per category will be a reason of its own once the cap exists (task 1003809). The rule is `explainPlacement` in `src/bongos/module-listing.js`.
+- **Sub-categories are approved before they count** (task 1004355, ADR 0342 D3). A module names `category: { parent, sub }` in `module.json`; `GET /store/subcategories` lists the approved ones under each of the eight parents. A `sub` the store has not seen under that parent is **proposed** at publish (labelled from its key) and the publish answer's `category` says so (`status: "proposed"`, `live: false`): until a Metic+ person decides, the module sits under its parent only and counts toward no cap. The review queue (`GET /store/subcategories/queue`, atom `module.subcategory.review`, metic + archon via `government_033`) shows each proposal with the modules that named it and its near-duplicate names; `POST /store/subcategories/:id/approve { label?, sub_key? }` makes it live, renamed first if asked (a rename onto an existing key is refused — merge instead), and `POST /store/subcategories/:id/merge { into }` folds it into an approved one and moves its modules there. A later publish naming a merged key lands on its target. Where a module sits is `store_module_categories` (core_278), apart from the manifest; `readModuleCategories` in `src/bongos/module-subcategories.js` is the read the cap uses.
 - **Testing new versions first** (task 1003802, [ADR 0344](adr/0344-a-tester-is-a-project-that-opts-in-once.md) D1). A project can choose to get each new version of its modules before everyone else. It is the project that opts in, never one builder for someone else's project, and never by default. `GET /modules/testing` returns `{ tester, general_only, updated_at, updated_by }` to anyone signed in. `POST /modules/testing { tester: true|false }` switches it, and `POST /modules/:key/general-only { general_only: true|false }` keeps one module on the versions everyone gets while the rest are tested. Both writes take the `module.enable` permission, the same one that turns modules on and off. Both are reversible: switching testing off puts the project back on general versions from its next update, and a module's "general only" mark is kept if testing is switched off and on again. The choice is stored in the project's own settings (`modules.tester`, `modules.general_only`); anything that cannot be read counts as not testing. `testsVersionsOf` in `src/bongos/module-testing.js` is the one answer to "does this project get the tester version of this module", which installs and updates use (task 1003805). The hall's Modules tab has the switch in its "Testing new versions" group, and the general-only control in each module's details.
 
 ### 7. Install from the store