@bongos/core 1.20.73 → 1.20.75

package/docs/api/openapi.json

@@ -16533,6 +16533,55 @@
         "security": []
       }
     },
+    "/provisioning/physics-check": {
+      "post": {
+        "operationId": "post_provisioning_physics_check",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/physics-check",
+        "description": "POST /provisioning/physics-check — the planet-physics questions' read BEFORE anything exists (task 1004418, BV2.PS07). The create wizard asks it as the founder answers: would this description stop at the screening screen, and which options do the answers so far hide, grey or annotate (the PS02 soft-limit table, spec D6)? It is the same screen and the same table the create runs, so the screens can never disagree with the Create. Writes nothing, and the soft limits stay advice (`enforced: false`); the create still re-checks everything itself.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProvisioningPhysicsCheckRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProvisioningPhysicsCheckResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/recommendations": {
       "get": {
         "operationId": "get_provisioning_recommendations",
@@ -20132,6 +20181,81 @@
         ]
       }
     },
+    "/store/modules/{key}/versions/{version}/reassess": {
+      "post": {
+        "operationId": "post_store_modules_key_versions_version_reassess",
+        "tags": [
+          "store"
+        ],
+        "summary": "POST /store/modules/:key/versions/:version/reassess",
+        "description": "POST /api/bongos/store/modules/:key/versions/:version/reassess — a Metic+ person asks for a published version's assessment to run again: the Security gate, the Docs grader, then the score (task 1003796, ADR 0359). There is deliberately no way to SET a score: the owner ruled a person may trigger a re-check, never change the number. A reason is required; the audit middleware records it with who asked. Answers 202 — the run is queued like a publish's.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.assessment.rerun` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.assessment.rerun"
+        ],
+        "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`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostStoreModulesKeyVersionsVersionReassessRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostStoreModulesKeyVersionsVersionReassessResponse"
+                }
+              }
+            }
+          },
+          "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}/versions/{version}/tarball": {
       "get": {
         "operationId": "get_store_modules_key_versions_version_tarball",
@@ -29208,6 +29332,33 @@
         ],
         "additionalProperties": false
       },
+      "PostProvisioningPhysicsCheckRequest": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "detail": {
+            "type": "object"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostProvisioningPhysicsCheckResponse": {
+        "type": "object",
+        "properties": {
+          "stop": {
+            "type": "boolean"
+          },
+          "message": {},
+          "soft_limits": {}
+        },
+        "required": [
+          "stop",
+          "message",
+          "soft_limits"
+        ]
+      },
       "PostProvisioningRenderLookupRequest": {
         "type": "object",
         "properties": {
@@ -30083,6 +30234,37 @@
           "version"
         ]
       },
+      "PostStoreModulesKeyVersionsVersionReassessRequest": {
+        "type": "object",
+        "properties": {
+          "reason": {
+            "type": "string",
+            "maxLength": 2000
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostStoreModulesKeyVersionsVersionReassessResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "queued": {
+            "type": "boolean"
+          },
+          "module_key": {},
+          "version": {},
+          "version_id": {}
+        },
+        "required": [
+          "ok",
+          "queued",
+          "module_key",
+          "version",
+          "version_id"
+        ]
+      },
       "PostTaskRecommendationsRequest": {
         "type": "object",
         "properties": {
@@ -31044,9 +31226,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 486,
-  "x-schema-count": 514,
+  "x-endpoint-count": 488,
+  "x-schema-count": 518,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 344,
+  "x-response-schemas": 346,
   "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. 486 endpoints across 89 route files.
+> **Generated from the live route files** — the route file is authoritative. 488 endpoints across 89 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`.
@@ -588,7 +588,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 
-## `provisioning` (41)
+## `provisioning` (42)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -628,6 +628,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/provisioning/instances/:id/update-channel` | `archon` | — | POST /provisioning/instances/:id/update-channel — set the project's update rule (task 1004445). |
 | GET | `/api/bongos/provisioning/logos/:file` | `public` | — | a logo is shown on a public hall, and its address is its own sha256, so it names no project and cannot be guessed. |
 | GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
+| POST | `/api/bongos/provisioning/physics-check` | `any-builder` | `description`, `detail` | POST /provisioning/physics-check — the planet-physics questions' read BEFORE anything exists (task 1004418, BV2.PS07). |
 | GET | `/api/bongos/provisioning/recommendations` | `public` | — | GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer> — the RULE-BASED recommendation for one set of creati… |
 | POST | `/api/bongos/provisioning/render/lookup` | `any-builder` | `key`, `owner_id` | POST /provisioning/render/lookup — rank: any authenticated builder. |
 | GET | `/api/bongos/provisioning/slug-available` | `any-builder` | — | GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the c… |
@@ -769,7 +770,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` (8)
+## `store` (9)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -779,6 +780,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | 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/howto` | `any-builder` | — | GET /api/bongos/store/modules/:key/versions/:version/howto — the how-to a version shipped with (task 1004366, ADR 0347 D1/D3), read from … |
+| POST | `/api/bongos/store/modules/:key/versions/:version/reassess` | `metic+archon` | `reason` | POST /api/bongos/store/modules/:key/versions/:version/reassess — a Metic+ person asks for a published version's assessment to run again: … |
 | 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… |
 

package/docs/architecture.md

@@ -273,7 +273,7 @@ module_assessment_scores(id, version_id, kind IN (computed|override), overall 0-
               -- and is a new row on the computed history, never an edit (D6)
 ```
 
-Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. On publish the version's Tests part is recorded `pending` until that environment runs it. **Security** — `scripts/gds/module-assess-security.js <version id>` (task 1003792, ADR 0343 D2 gate) appends one `security` row, `passed`/`failed` only: fails on a publish-denylist file, a `module.json` dependency fetched outside the registry (an allowlist: a plain npm name with a plain semver range or dist-tag, anything else fails and is never handed to npm), or a high/critical `npm audit` advisory (resolved metadata-only with `--ignore-scripts`; nothing of the module runs, so it is control-plane safe). An audit that cannot run is `not_scored` — the gate stays shut. Floating ranges and the `maintenance` posture (ADR 0166) are noted in `detail`, never failed on. **Docs** — `scripts/gds/module-assess-docs.js <version id>` (task 1004367, ADR 0347 D5/D6) grades the version's `HOWTO.md`, read from its verified tarball (never the optional `howto.artifactUrl`), with one Claude Sonnet 5 call through the `grade` port's cached `runSubagent` (no tools, the file fenced as untrusted, cut to 40,000 characters to stay under 5¢), retried once. It appends a `pending` row, then `scored` (the average of four 0–100 criteria — purpose, newcomer could use it, runnable example, limits stated — each with a reason, kept in `detail`) or `not_scored` (outage, malformed reply twice, no `HOWTO.md`, bad tarball). Each call's spend goes to `cost_log` via the `reward` port (source `module-docs-grader`). Price is never in the prompt. `--file <HOWTO.md>` is a DB-free dry run. **Score** — `scripts/gds/module-assess-score.js` (task 1003794) composes a version's newest signal per part into a `module_assessment_scores` row: `security_passed` from the gate (NULL = not run), `overall` = the plain average of the SCORED parts among Tests, Install, Reliability and Tester feedback (a part with no data is left out, never zero; none → NULL), Docs shown but never averaged, `is_new` until Install or Reliability is scored, plus the signal ids and a readable `formula`. A recompose that would repeat the current score writes nothing. All three signal CLIs recompose after recording, and the store's publish route queues `assessVersion` after answering the author (one at a time per process, at most 20 waiting; past that it is logged as not assessed): Tests `pending` (only if no Tests result exists), the Security gate, Docs, then the score. `node scripts/gds/module-assess-version.js <id>` re-runs it by hand (`scripts/gds/module-assess-version.js` holds the publish-time half, apart from the composer so the signal CLIs recompose without a require cycle).
+Signals that fill it: **Tests** — `scripts/gds/module-assess-tests.js <version id>` (task 1003791) unpacks the published tarball to `<core root>/.module-assess-<run>/<key>/` (gitignored, removed after), runs each `tests/*.mjs` in its own node process with a timeout and a credential-free environment — regardless of `isModuleEnabled`, which skips every default-off catalog module in the unit gate — and appends one `tests` row: `scored` = % of test files passing (sample_size = files), `no_data` = declares no tests, `not_scored` = tarball unreadable. The store path **refuses unless `MODULE_TEST_SANDBOX=1`** — a published module's tests run only in a separate testing environment with no secrets on disk, never on the control plane (owner, 2026-09-30). `--dir modules/<key>` is a DB-free dry run on your own checkout. On publish the version's Tests part is recorded `pending` until that environment runs it. **Security** — `scripts/gds/module-assess-security.js <version id>` (task 1003792, ADR 0343 D2 gate) appends one `security` row, `passed`/`failed` only: fails on a publish-denylist file, a `module.json` dependency fetched outside the registry (an allowlist: a plain npm name with a plain semver range or dist-tag, anything else fails and is never handed to npm), or a high/critical `npm audit` advisory (resolved metadata-only with `--ignore-scripts`; nothing of the module runs, so it is control-plane safe). An audit that cannot run is `not_scored` — the gate stays shut. Floating ranges and the `maintenance` posture (ADR 0166) are noted in `detail`, never failed on. **Docs** — `scripts/gds/module-assess-docs.js <version id>` (task 1004367, ADR 0347 D5/D6) grades the version's `HOWTO.md`, read from its verified tarball (never the optional `howto.artifactUrl`), with one Claude Sonnet 5 call through the `grade` port's cached `runSubagent` (no tools, the file fenced as untrusted, cut to 40,000 characters to stay under 5¢), retried once. It appends a `pending` row, then `scored` (the average of four 0–100 criteria — purpose, newcomer could use it, runnable example, limits stated — each with a reason, kept in `detail`) or `not_scored` (outage, malformed reply twice, no `HOWTO.md`, bad tarball). Each call's spend goes to `cost_log` via the `reward` port (source `module-docs-grader`). Price is never in the prompt. `--file <HOWTO.md>` is a DB-free dry run. **Score** — `scripts/gds/module-assess-score.js` (task 1003794) composes a version's newest signal per part into a `module_assessment_scores` row: `security_passed` from the gate (NULL = not run), `overall` = the plain average of the SCORED parts among Tests, Install, Reliability and Tester feedback (a part with no data is left out, never zero; none → NULL), Docs shown but never averaged, `is_new` until Install or Reliability is scored, plus the signal ids and a readable `formula`. A recompose that would repeat the current score writes nothing. All three signal CLIs recompose after recording, and the store's publish route queues `assessVersion` after answering the author (one at a time per process, at most 20 waiting; past that it is logged as not assessed): Tests `pending` (only if no Tests result exists), the Security gate, Docs, then the score. `node scripts/gds/module-assess-version.js <id>` re-runs it by hand (`scripts/gds/module-assess-version.js` holds the publish-time half, apart from the composer so the signal CLIs recompose without a require cycle). **No score is ever set by hand** (owner, ADR 0359): a Metic+ person can only ask for a re-check, `POST /store/modules/:key/versions/:version/reassess { reason }` (atom `module.assessment.rerun`, metic + archon via `government_021`), which queues the same `assessVersion` a publish runs and answers 202.
 
 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.