@bongos/core 1.20.28 → 1.20.29

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.28",
-  "core_contract": "1.20.28",
-  "source_commit": "64dc694277165d8cd1227e09df2fda3dd99dd396",
+  "core_version": "1.20.29",
+  "core_contract": "1.20.29",
+  "source_commit": "c6152c075da2e7e656381b46f3f9b561cf65f457",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T20:23:58.237Z",
+  "built_at": "2026-09-30T20:49:43.614Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 562,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2659,
+    "functional_verbatim": 2660,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3247,
-  "tree_sha256": "06c076a09a9c706567f32a447e0d1600e2e07a868b9bdd4be62088a290714985",
+  "file_count": 3248,
+  "tree_sha256": "91a5ebee3fc044967031c6f7dbb8e2a86b98fe305e68353f39c023c5ab042df9",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -327,12 +327,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "8dde50025e6ac0a8e9742455d62495b72c1803b87044455c48b13b95209f59a2"
+      "sha256": "08c6eaeee75d4fa5a447578107738e5357ffe088bde7f64e946a5f82d1c06106"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "77f3e9375343c45fd538d179928628a7422858ddea7540cc60cfbdfba95a8545"
+      "sha256": "808fd2048e5260dd4cc518d0e4697636b99ec393c925caa1d858976da2590baf"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -342,17 +342,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "2eea3743862e9ec173c63517b6f79073b25e71aa3cb2d0a2a19ecce95ef78ca0"
+      "sha256": "d6484208dc9acee624ed01503c36ad9fa4f06bd1e7b51738e2c58c1fe251ace8"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "065abbfa7d625aa5811ae9e6c27101ca5b9c824422a6a74bba22d92e3f5d53ae"
+      "sha256": "6298f90c0b7849ca342dd5e5235df57686e36b666cedba8db2d9018e8acb60c1"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "e2714285309adfdb0644e82319363fdcc6fc19ad9f5a2cf0e71e203da8c5e188"
+      "sha256": "eded947e375da51b79857e9d3452f21fbfca2136e774b2a3907d1a4d51436aa9"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2262,12 +2262,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "db03fd5370b7b592769a806607b9cd0880a56b53c64d8909ca24364feeff818e"
+      "sha256": "60243a4cf43ee8c37a06dda28bac07a9797c96eaef126cbcbda4d89c9ec9b986"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "27b8f6be81f9703a96a68f917dbb01a65048cc02f13adf308b414e96fb022668"
+      "sha256": "847818c90b206c7223114b868e32b1eb50e0cc9955ae4dd6b67c5614d1ab51d8"
     },
     {
       "path": "docs/architecture.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8de783d8efc2109b60de3758da0dfd4fecaf4d4a65dc364dacd1c17e8dac4a7d"
+      "sha256": "7fab447c04933dbbe8ee8f154f854f15eb834163ae656799e5ff3c8f3756fdfc"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7282,7 +7282,7 @@
     {
       "path": "modules/provisioning/core-upgrade.js",
       "mode": "0000644",
-      "sha256": "ff2f256a550c5d83a83deb47448590fc9a8f4cfd30c52fd4e90a441223b2aaa7"
+      "sha256": "8adf8842f6058224aeac88f54202cf4e7ed26f0021c44cf9bf1f94098b12ce07"
     },
     {
       "path": "modules/provisioning/cost-ledger.js",
@@ -7454,6 +7454,11 @@
       "mode": "0000644",
       "sha256": "9726682ff47916ca8ef999fe70ed5995c3bad7680b0821b87e4cab8a74d9f867"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_029_update_channel.sql",
+      "mode": "0000644",
+      "sha256": "b667ec5165e611bd6f0d86b09465c5d9e632de853becce139bac49f5a88e5c1e"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
@@ -7547,7 +7552,7 @@
     {
       "path": "modules/provisioning/routes/core-upgrade.js",
       "mode": "0000644",
-      "sha256": "5e74192eb8c4543da8af94a362d7516b54adb8fcbe114953923905d382e5f616"
+      "sha256": "980f25a157dfde5bda6ed903c727fab944b922abdc34be05dc0ccdb5fb3650cc"
     },
     {
       "path": "modules/provisioning/routes/disconnect.js",
@@ -8972,12 +8977,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "cf64ad1f380ccd8f68a30f1f5b72aa8c03681fc37f044093ae435b7886529cc8"
+      "sha256": "eb1cd0418a763ae11ad580a788df78980c6f19e4953d543e2111f4543d53a8ac"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d79bd6231aed473960ba8f6c644b69f2c930850a0937a504635e657aa733ea89"
+      "sha256": "3aefd305535d6f2fc5f8a09ca30b7a6ae323e7f120008618e01d1c772198a363"
     },
     {
       "path": "public-docs/index.html",
@@ -8997,7 +9002,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "2ec3010abecc3e0ed0d2a9bda13ccad173d34e91d80a13bc4ff4aecace0944e8"
+      "sha256": "84ae8d8349b19fc436952c1455536f608f5804eca0a4b934d0b66555f72baef0"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9957,7 +9962,7 @@
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "53b301ac91be7028d6b1f633eb0e8cdb105d34b0e6b8c6a2cc667f1ba77e8a85"
+      "sha256": "3adfb1d93ac59f1a057bcfc55fbeb1ac1cfcb6b8148c4ce6551de9bf743c878b"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -11117,7 +11122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "40910d211c287582e7066d72f651ff79862d9f5776be6086cd2c931e648136fd"
+      "sha256": "e8f28de6e2a1dbb5dead24503e6da1e013dd36a4a27c0dea9382480fdfdbb7e6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12062,7 +12067,7 @@
     {
       "path": "tests/core_upgrade_door.mjs",
       "mode": "0000644",
-      "sha256": "52b55a04a99870a1501f2a422096337e3426a7624ec6e1728f291e426eb9567b"
+      "sha256": "0bbd0f6bcecfb8c88e69256470610f40eb64ec555a67502b3172d69a220fc12b"
     },
     {
       "path": "tests/core_upgrade_owner_door.mjs",
@@ -12072,7 +12077,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "c8b2ecca1681427e2e800f78961ba322443e4a2e5502d5d81fd5c2f20aeda711"
+      "sha256": "f55d142db2f3207eb1b1dc7e06c978cb22a282ff0d16792808d212948993640a"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",

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`)
-- 465 operations across 70 resource groups
+- 466 operations across 70 resource groups
 
 ## Use it from your project
 

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

@@ -843,6 +843,8 @@ function createClient(opts = {}) {
       patchProvisioningInstancesIdSettings: (args) => request("PATCH", "/provisioning/instances/{id}/settings", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
+      postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

package/clients/bongos-client/index.cjs

@@ -842,6 +842,8 @@ function createClient(opts = {}) {
       patchProvisioningInstancesIdSettings: (args) => request("PATCH", "/provisioning/instances/{id}/settings", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
+      postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

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

@@ -1274,6 +1274,8 @@ export interface BongosClient {
     patchProvisioningInstancesIdSettings(args?: RequestArgs): Promise<PatchProvisioningInstancesIdSettingsResponse>;
     /** POST /provisioning/instances/{id}/teardown — rank: any-builder */
     postProvisioningInstancesIdTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdTeardownResponse>;
+    /** POST /provisioning/instances/{id}/update-channel — rank: archon */
+    postProvisioningInstancesIdUpdateChannel(args?: RequestArgs): Promise<ApiResponse>;
     /** GET /provisioning/onboard-plan — rank: public */
     getProvisioningOnboardPlan(args?: RequestArgs): Promise<GetProvisioningOnboardPlanResponse>;
     /** GET /provisioning/recommendations — rank: public */

package/clients/bongos-client/index.mjs

@@ -839,6 +839,8 @@ export function createClient(opts = {}) {
       patchProvisioningInstancesIdSettings: (args) => request("PATCH", "/provisioning/instances/{id}/settings", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/teardown — rank: any-builder — POST /provisioning/instances/:id/teardown
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
+      // POST /provisioning/instances/{id}/update-channel — rank: archon — POST /provisioning/instances/:id/update-channel
+      postProvisioningInstancesIdUpdateChannel: (args) => request("POST", "/provisioning/instances/{id}/update-channel", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
       // GET /provisioning/recommendations — rank: public — GET /provisioning/recommendations

package/docs/api/openapi.json

@@ -15676,6 +15676,54 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/update-channel": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_update_channel",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/update-channel",
+        "description": "POST /provisioning/instances/:id/update-channel — set the project's update rule (task 1004445). Body: { channel: \"pinned\" | \"patch\" | \"minor\" }. rank: `core.pin.move`, OR THE PROJECT'S OWN OWNER — the same two doors as the move, because the rule decides which moves the runner will perform: whoever may press Move may choose how far it reaches, and nobody else may. The platform's own row stays on the atom alone (OWNER_SHAPES excludes it), exactly as for the move.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `core.pin.move` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/provisioning/routes/core-upgrade.js",
+        "x-permissions": [
+          "core.pin.move"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "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": []
+          }
+        ]
+      }
+    },
     "/provisioning/onboard-plan": {
       "get": {
         "operationId": "get_provisioning_onboard_plan",
@@ -29763,7 +29811,7 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 465,
+  "x-endpoint-count": 466,
   "x-schema-count": 498,
   "x-undocumented-bodies": 12,
   "x-response-schemas": 337,

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 465 endpoints across 83 route files.
+> **Generated from the live route files** — the route file is authoritative. 466 endpoints across 83 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`.
@@ -562,7 +562,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` (34)
+## `provisioning` (35)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -594,6 +594,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | — | GET /provisioning/instances/:id/settings — read a project's effective settings + the allowed values (so a form can render its choices). |
 | PATCH | `/api/bongos/provisioning/instances/:id/settings` | `any-builder` | validated | PATCH /provisioning/instances/:id/settings — change a project's settings. |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
+| 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/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
 | 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. |

package/docs/module-api-changelog.md

@@ -2713,5 +2713,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.26 with no explicit bump. run 36768642814. (task 1002620)
   1.20.28 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.27 with no explicit bump. run 36772266063. (task 1002620)
+  1.20.29 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.28 with no explicit bump. run 36775277990. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/core-upgrade.js

@@ -318,6 +318,9 @@ function previewFromSnapshot(inst, snap, openIntent, lastMove) {
     slug: inst.slug,
     hosting_shape: inst.hosting_shape,
     served_version: served,
+    // The rule the runner bounds this project's moves by (task 1004445) — what the page
+    // shows beside the offer, so "nothing to deploy" can say WHICH rule made it so.
+    update_channel: updateChannelOf(inst),
     recommended_version: recommended,
     available_count: available.length,
     behind: !!behind,
@@ -429,5 +432,71 @@ function makeControlPlaneHandler({ provisioning, pool, log }) {
   };
 }
 
-module.exports = { CORE_UPGRADE_FROM, lastCoreMove, lastMoveSuperseded, parseRepoNote, preflightForOffer, UPGRADE_SHAPES, VERSION_RE, isCoreVersion, coreUpgradeFault, enqueueCoreUpgrade, makeCoreUpgradeHandler, previewFromSnapshot, makeCoreUpgradePreviewHandler, makeControlPlaneHandler };
+// ---- the project's update rule (task 1004445) -------------------------------------
+//
+// RE-STATED, NOT REQUIRED. The list is update-channel.js VALID_CHANNELS / DEFAULT_CHANNEL,
+// which lives in scripts/gds/ and a module may not require (ADR 0083) — the same reason
+// parseRepoNote re-states the runner's note shape. tests/core_upgrade_door.mjs asserts the
+// two lists are equal, so they cannot drift apart silently; migration provisioning_029's
+// CHECK is the third copy, and the database refuses anything outside it.
+const UPDATE_CHANNELS = Object.freeze(['pinned', 'patch', 'minor']);
+const DEFAULT_UPDATE_CHANNEL = 'patch';
+
+/** The row's update rule, or the default for a row read before the column existed. PURE. */
+function updateChannelOf(inst) {
+  const c = inst && typeof inst.update_channel === 'string' ? inst.update_channel : '';
+  return UPDATE_CHANNELS.includes(c) ? c : DEFAULT_UPDATE_CHANNEL;
+}
+
+/**
+ * POST /provisioning/instances/:id/update-channel — set how far this project's core
+ * may move (task 1004445). Body: { channel: 'pinned' | 'patch' | 'minor' }.
+ *
+ * WHY IT EXISTS. The runner's channel refusal told the owner to "change the channel
+ * first", and until this route there was no channel to change: every project was held to
+ * patch-only, so a step-up release (1.19 → 1.20) could never land through the door.
+ *
+ * It changes a RULE, never the core: nothing is queued and nothing restarts. The next
+ * runner tick re-resolves what is on offer under the new rule, which is why the reply
+ * says the offer updates on the next check rather than claiming it already has.
+ */
+function makeUpdateChannelHandler({ provisioning, pool, parseId, validateOrRespond, log }) {
+  return async function updateChannelHandler(req, res) {
+    const id = parseId(req, res);
+    if (!id) return;
+    if (validateOrRespond(req, res, { channel: { type: 'string', maxLength: 16 } }, { strict: true })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      const channel = req.body && typeof req.body.channel === 'string' ? req.body.channel.trim().toLowerCase() : '';
+      if (!UPDATE_CHANNELS.includes(channel)) {
+        return res.fail('bad_update_channel', {
+          status: 400,
+          message: `Choose one of: ${UPDATE_CHANNELS.join(', ')} — pinned moves nothing, patch takes fixes within the same release line, minor also takes the next step up.`,
+          details: { valid: UPDATE_CHANNELS },
+        });
+      }
+      const was = updateChannelOf(inst);
+      if (was !== channel) {
+        await pool.query('UPDATE provisioning_instances SET update_channel = $2, updated_at = now() WHERE id = $1', [id, channel]);
+        const actor = require('./core-upgrade-authz').coreUpgradeActor(req);
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'update-channel-changed',
+          detail: `update rule changed from ${was} to ${channel}`, actor,
+        }).catch(() => {});
+      }
+      return res.json({
+        ok: true, update_channel: channel, previous: was, changed: was !== channel,
+        message: was === channel
+          ? `This project already follows the '${channel}' rule — nothing changed.`
+          : `This project now follows the '${channel}' rule. What it can move to updates on the next check, within a few minutes.`,
+      });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/update-channel', err);
+      return failFrom(res, err, 'update_channel_failed');
+    }
+  };
+}
+
+module.exports = { UPDATE_CHANNELS, DEFAULT_UPDATE_CHANNEL, updateChannelOf, makeUpdateChannelHandler, CORE_UPGRADE_FROM, lastCoreMove, lastMoveSuperseded, parseRepoNote, preflightForOffer, UPGRADE_SHAPES, VERSION_RE, isCoreVersion, coreUpgradeFault, enqueueCoreUpgrade, makeCoreUpgradeHandler, previewFromSnapshot, makeCoreUpgradePreviewHandler, makeControlPlaneHandler };
 

package/modules/provisioning/migrations/provisioning_029_update_channel.sql

@@ -0,0 +1,24 @@
+-- provisioning_029_update_channel.sql — each project's own core update rule (task 1004445).
+--
+-- WHY. The deploy runner bounded every project by the platform default (update-channel.js
+-- DEFAULT_CHANNEL, patch-only), because nothing per-project existed to read. So a step-up
+-- release (1.19.x -> 1.20.0) could never reach ANY project through the deploy door: the
+-- runner refused it with "outside this project's 'patch' update channel ... Change the
+-- channel first", and there was no channel anywhere to change. This column is that channel.
+--
+-- Values are update-channel.js VALID_CHANNELS: pinned (the door moves nothing), patch
+-- (same major.minor — the old behaviour, hence the default), minor (any higher minor within
+-- the major). A major bump is never admitted by any channel. The CHECK mirrors the list so a
+-- hand-written UPDATE cannot store a value the runner would silently normalise away.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances ADD COLUMN IF NOT EXISTS update_channel text NOT NULL DEFAULT 'patch';
+
+ALTER TABLE provisioning_instances DROP CONSTRAINT IF EXISTS provisioning_instances_update_channel_check;
+ALTER TABLE provisioning_instances ADD CONSTRAINT provisioning_instances_update_channel_check
+  CHECK (update_channel IN ('pinned', 'patch', 'minor'));
+
+COMMIT;

package/modules/provisioning/routes/core-upgrade.js

@@ -25,7 +25,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const provisioning = require('../provisioning');
-const { makeCoreUpgradeHandler, makeCoreUpgradePreviewHandler, makeControlPlaneHandler } = require('../core-upgrade');
+const { makeCoreUpgradeHandler, makeCoreUpgradePreviewHandler, makeControlPlaneHandler, makeUpdateChannelHandler } = require('../core-upgrade');
 const { requireOwnProjectOrPin } = require('../core-upgrade-authz');
 
 const log = api.logger('provisioning');
@@ -86,6 +86,26 @@ module.exports = function buildCoreUpgradeRouter() {
     makeCoreUpgradePreviewHandler({ provisioning, pool: api.pool, parseId: api.parseId, log }),
   );
 
+  // POST /provisioning/instances/:id/update-channel — set the project's update rule
+  // (task 1004445). Body: { channel: "pinned" | "patch" | "minor" }.
+  //
+  // rank: `core.pin.move`, OR THE PROJECT'S OWN OWNER — the same two doors as the move,
+  // because the rule decides which moves the runner will perform: whoever may press
+  // Move may choose how far it reaches, and nobody else may. The platform's own row
+  // stays on the atom alone (OWNER_SHAPES excludes it), exactly as for the move.
+  router.post(
+    '/provisioning/instances/:id/update-channel',
+    api.requireBuilder,
+    requireOwnProjectOrPin({ pinGate: api.requirePermission('core.pin.move'), provisioning, pool: api.pool, log }),
+    makeUpdateChannelHandler({
+      provisioning,
+      pool: api.pool,
+      parseId: api.parseId,
+      validateOrRespond: api.validateOrRespond,
+      log,
+    }),
+  );
+
   // GET /provisioning/control-plane — "which row is this platform, and where does it
   // stand?" The deploy page's first call: the self row is created once by hand at
   // install time, so its id is per-install and nobody's to memorise. The atom ALONE

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.28",
+  "version": "1.20.29",
   "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

@@ -8240,5 +8240,11 @@
       "id": "1002969",
       "text": "An invitation to join a project now expires after 30 days; the person who sent it can simply invite again."
     }
+  ],
+  "1.20.29": [
+    {
+      "id": "1004445",
+      "text": "Each project now has its own update rule. A project can be allowed to take bigger step-up updates (like 1.19 to 1.20) instead of being stuck on small fixes only, and its owner can change the rule."
+    }
   ]
 }

package/scripts/gds/provision-core-upgrade.js

@@ -141,6 +141,15 @@ function targetFault(to, available, installed, channel, channelAllows) {
   return null;
 }
 
+// The update channel that bounds a move for THIS instance (task 1004445): the row's own
+// `update_channel`, normalised by update-channel.js so anything unknown or absent (a row
+// read before migration provisioning_029) falls back to DEFAULT_CHANNEL. PURE. One helper
+// for the move and the snapshot, so the button's offer and the runner's refusal cannot
+// disagree about which rule applies.
+function instanceChannel(inst, channelMod) {
+  return channelMod.normalizeChannel(inst && inst.update_channel != null ? inst.update_channel : channelMod.DEFAULT_CHANNEL);
+}
+
 // The builder id a queued move is attributed to, from the actor the web tier recorded.
 // PURE. Two doors reach the move (ADR 0339): an Archon (`api:archon:<id>`) and, since
 // task 1004174, the project's own owner (`api:owner:<id>`). Both carry the id, because
@@ -209,15 +218,12 @@ async function coreUpgradeInstance(inst, deps, intent) {
   const instanceDir = inst.hosting_shape === 'cloud-host' ? standaloneRoot(inst) : selfRoot();
   const readInstalled = deps.readInstalledCoreVersion || require('./upgrade.js').readInstalledCoreVersion;
   const installed = readInstalled(instanceDir);
-  // THE PLATFORM DEFAULT, NOT A PER-INSTANCE CHANNEL — and saying so beats implying
-  // otherwise. provisioning_instances carries no channel column; the subscription
-  // roster update-channel.js reads is a control-plane file, not a per-row setting. So
-  // this bounds every instance by the same policy (DEFAULT_CHANNEL: patch-only), which
-  // is a real bound — it refuses a prerelease or a major jump — and is the honest one
-  // available today. When a per-instance channel lands, this line is where it is read;
-  // writing `inst.update_channel ||` now would only have created a guard that reads as
-  // present and can never fire, which is the trap the web-tier half already documents.
-  const channel = channelMod.normalizeChannel(channelMod.DEFAULT_CHANNEL);
+  // THIS PROJECT'S OWN UPDATE RULE (task 1004445, migration provisioning_029). Before it
+  // every instance was bounded by DEFAULT_CHANNEL (patch-only), so a step-up release
+  // could reach no project through the door and the refusal's "change the channel first"
+  // pointed at nothing. A row from before the column (undefined) still normalises to that
+  // default, so an old runner schema reads exactly as it always did.
+  const channel = instanceChannel(inst, channelMod);
   const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
   const available = (listed && listed.versions) || [];
   const fault = targetFault(to, available, installed, channel, channelMod.channelAllows);
@@ -977,7 +983,7 @@ async function snapshotCoreVersions(inst, deps) {
     // admits nothing newer — "already current" and "nothing to take" are the same
     // answer here, and both correctly leave `recommended` NULL.
     const recommended = served
-      ? channelMod.resolveChannelTarget({ installed: served, channel: channelMod.DEFAULT_CHANNEL, available })
+      ? channelMod.resolveChannelTarget({ installed: served, channel: instanceChannel(inst, channelMod), available })
       : null;
     // THE TICK DOES NOT DRY-RUN. The verdict is produced on demand (preflightCoreUpgrade),
     // because a check re-run every tick for a box that has been behind for hours spends a
@@ -1021,4 +1027,4 @@ async function snapshotAllCoreVersions(deps) {
   return { seen };
 }
 
-module.exports = { pushUpgradePin, UPGRADE_SHAPES, CHANGE_CAP, REPO_NOTES, repoNote, requestedByOf, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };
+module.exports = { pushUpgradePin, UPGRADE_SHAPES, instanceChannel, CHANGE_CAP, REPO_NOTES, repoNote, requestedByOf, parseChangeRecords, readInstalledNotes, readPackagedNotes, changesBetween, coreCheckoutCandidates, findCoreCheckout, gitFault, resolveRunAs, versionCmd, parseServedVersion, parseSchemaPending, targetFault, parsePreflight, upgradeInvocation, preflightUpgrade, preflightCoreUpgrade, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/src/module-api.js

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

package/tests/core_upgrade_door.mjs

@@ -18,7 +18,7 @@ import { createRequire } from 'node:module';
 import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { parseRepoNote } from '../modules/provisioning/core-upgrade.js';
+import { parseRepoNote, UPDATE_CHANNELS, DEFAULT_UPDATE_CHANNEL, updateChannelOf, makeUpdateChannelHandler as updateChannelHandlerFor } from '../modules/provisioning/core-upgrade.js';
 
 const require = createRequire(import.meta.url);
 const P = require('../modules/provisioning/provisioning.js');
@@ -885,5 +885,84 @@ await t('lastMoveSuperseded computes no version ORDERING — only identity', ()
   assert.equal(CU.lastMoveSuperseded('1.19.921', '1.19.900', '1.19.949'), true);
 });
 
+console.log('\nthe project\'s update rule (task 1004445):');
+
+const channelHandler = (inst, calls) => updateChannelHandlerFor({
+  provisioning: {
+    getInstanceById: async () => inst,
+    recordEvent: async (_db, e) => { calls.push({ event: e.event, detail: e.detail, actor: e.actor }); },
+  },
+  pool: { query: async (sql, params) => { calls.push({ sql, params }); return { rows: [] }; } },
+  parseId: () => 7, validateOrRespond: () => false, log: { error() {} },
+});
+const runChannel = async (inst, body, calls = []) => {
+  let out = null;
+  const res = { json: (b) => { out = b; return res; }, fail: (code, o) => { out = { code, ...o }; return res; } };
+  await channelHandler(inst, calls)({ builder: { id: 42 }, params: { id: '7' }, body }, res);
+  return out;
+};
+
+await t('the web tier\'s channel list is the runner\'s, and the migration\'s CHECK carries the same values', () => {
+  const policy = require('../scripts/gds/update-channel.js');
+  assert.deepEqual([...UPDATE_CHANNELS], policy.VALID_CHANNELS, 're-stated in the module (ADR 0083) — so it must be equal');
+  assert.equal(DEFAULT_UPDATE_CHANNEL, policy.DEFAULT_CHANNEL);
+  const sql = read('modules', 'provisioning', 'migrations', 'provisioning_029_update_channel.sql');
+  assert.match(sql, /DEFAULT 'patch'/);
+  for (const c of policy.VALID_CHANNELS) assert.match(sql, new RegExp(`'${c}'`), `the CHECK admits ${c}`);
+});
+
+await t('updateChannelOf reads the row and falls back to patch for a pre-column row', () => {
+  assert.equal(updateChannelOf({ update_channel: 'minor' }), 'minor');
+  assert.equal(updateChannelOf({}), 'patch');
+  assert.equal(updateChannelOf({ update_channel: 'everything' }), 'patch');
+});
+
+await t('setting the rule writes the row and audits who changed it, from what to what', async () => {
+  const calls = [];
+  const out = await runChannel({ ...ACTIVE, update_channel: 'patch' }, { channel: 'minor' }, calls);
+  assert.equal(out.ok, true);
+  assert.equal(out.update_channel, 'minor');
+  assert.equal(out.changed, true);
+  const w = calls.find((c) => c.sql && /UPDATE provisioning_instances SET update_channel/.test(c.sql));
+  assert.ok(w, 'the row was written');
+  assert.deepEqual(w.params, [7, 'minor']);
+  const ev = calls.find((c) => c.event === 'update-channel-changed');
+  assert.ok(ev, 'and an event recorded');
+  assert.match(ev.detail, /from patch to minor/);
+  assert.equal(ev.actor, 'api:archon:42');
+  assert.ok(!calls.some((c) => c.sql && /provisioning_intents/.test(c.sql)), 'nothing is queued — a rule change moves no core');
+});
+
+await t('an unknown rule is a 400 naming the valid ones, and writes nothing', async () => {
+  const calls = [];
+  const out = await runChannel(ACTIVE, { channel: 'major' }, calls);
+  assert.equal(out.code, 'bad_update_channel');
+  assert.equal(out.status, 400);
+  assert.deepEqual(out.details.valid, ['pinned', 'patch', 'minor']);
+  assert.equal(calls.length, 0);
+});
+
+await t('re-sending the current rule changes nothing and says so', async () => {
+  const calls = [];
+  const out = await runChannel({ ...ACTIVE, update_channel: 'minor' }, { channel: 'MINOR' }, calls);
+  assert.equal(out.ok, true);
+  assert.equal(out.changed, false);
+  assert.equal(calls.length, 0, 'no write, no event');
+});
+
+await t('the preview carries the rule, so the page can say which rule shaped the offer', () => {
+  assert.equal(CU.previewFromSnapshot({ ...ACTIVE, update_channel: 'minor' }, null, null, null).update_channel, 'minor');
+  assert.equal(CU.previewFromSnapshot(ACTIVE, null, null, null).update_channel, 'patch');
+});
+
+await t('the route is gated like the move: the owner door OR core.pin.move', () => {
+  const src = read('modules', 'provisioning', 'routes', 'core-upgrade.js');
+  const i = src.indexOf("'/provisioning/instances/:id/update-channel'");
+  assert.ok(i > 0, 'the route exists');
+  const block = src.slice(i, src.indexOf(');', i));
+  assert.match(block, /api\.requireBuilder/);
+  assert.match(block, /requireOwnProjectOrPin\(\{ pinGate: api\.requirePermission\('core\.pin\.move'\)/);
+});
+
 console.log(`\ncore_upgrade_door: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/core_upgrade_runner.mjs

@@ -31,7 +31,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 // An ESM named import, not R.parseSchemaPending: knip credits a CJS export only when a test imports it this way.
-import { parseSchemaPending, repoNote, REPO_NOTES } from '../scripts/gds/provision-core-upgrade.js';
+import { parseSchemaPending, repoNote, REPO_NOTES, instanceChannel } from '../scripts/gds/provision-core-upgrade.js';
 import { parseRepoNote } from '../modules/provisioning/core-upgrade.js';
 
 const require = createRequire(import.meta.url);
@@ -1396,5 +1396,58 @@ await t('the DRAIN LOOP resolves a done-with-a-note move WITH its note, still as
   assert.equal(statusWrites.length, 0, 'a healthy instance is not marked anything');
 });
 
+console.log('\nthe project\'s own update rule (task 1004445):');
+
+// The REAL policy module, not the stub makeDeps hands every other case: these cases are
+// about which rule the runner applies, so a stub that admits everything would prove nothing.
+const realChannel = require('../scripts/gds/update-channel.js');
+const withRealChannel = (over) => {
+  const d = makeDeps(over);
+  d.updateChannel = { ...realChannel, listAvailableVersions: () => ({ ok: true, versions: over.available }) };
+  return d;
+};
+
+await t('instanceChannel reads the row, and a row from before the column falls back to patch', () => {
+  assert.equal(instanceChannel({ update_channel: 'minor' }, realChannel), 'minor');
+  assert.equal(instanceChannel({ update_channel: 'pinned' }, realChannel), 'pinned');
+  assert.equal(instanceChannel({}, realChannel), 'patch', 'no column yet → the old default');
+  assert.equal(instanceChannel({ update_channel: 'bogus' }, realChannel), 'patch', 'unknown → the default, never a wider rule');
+});
+
+await t('a project on PATCH still refuses a step-up release (1.19 → 1.20)', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '1.20.1'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'patch' }), d, intent({ target_version: '1.20.1' }));
+  assert.equal(r.ok, false);
+  assert.match(r.error, /outside this project's 'patch' update channel/);
+  assert.ok(!d.ran.some((c) => /upgrade\.js/.test(c)), 'and nothing was run');
+});
+
+await t('a project on MINOR takes that same step-up release', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.20.1', available: ['1.19.1081', '1.20.1'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'minor' }), d, intent({ target_version: '1.20.1' }));
+  assert.ok(!(r.error && /update channel/.test(r.error)), `the channel must not refuse it: ${r.error}`);
+  assert.ok(d.ran.some((c) => /upgrade\.js/.test(c) && /--to 1\.20\.1/.test(c)), 'the upgrade was invoked for 1.20.1');
+});
+
+await t('MINOR still refuses a MAJOR jump — no rule makes 2.0 automatic', async () => {
+  const d = withRealChannel({ installed: '1.19.1081', served: '1.19.1081', available: ['1.19.1081', '2.0.0'] });
+  const r = await R.coreUpgradeInstance(inst({ update_channel: 'minor' }), d, intent({ target_version: '2.0.0' }));
+  assert.equal(r.ok, false);
+  assert.match(r.error, /outside this project's 'minor' update channel/);
+});
+
+await t('the snapshot OFFERS what the project\'s rule admits — the button and the runner agree', async () => {
+  const available = ['1.19.1081', '1.19.1082', '1.20.1', '1.20.11'];
+  const offered = async (update_channel) => {
+    const queries = [];
+    await R.snapshotCoreVersions(inst({ update_channel }), withRealChannel({ served: '1.19.1081', available, queries }));
+    return queries.find((q) => /provisioning_core_version_snapshot/.test(q.sql)).params[3];
+  };
+  assert.equal(await offered('patch'), '1.19.1082', 'patch offers the newest fix on the same line');
+  assert.equal(await offered('minor'), '1.20.11', 'minor offers the step up');
+  assert.equal(await offered('pinned'), null, 'pinned offers nothing');
+  assert.equal(await offered(undefined), '1.19.1082', 'a pre-column row behaves exactly as before');
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);