@bongos/core 1.19.674 → 1.19.675

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.674",
-  "core_contract": "1.19.674",
-  "source_commit": "0da6434caa66f679eeb8c34bc2be3826f2a1bfe8",
+  "core_version": "1.19.675",
+  "core_contract": "1.19.675",
+  "source_commit": "1341cb9d37a0965db7f80483f7f1cb8f3622b2c5",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T18:40:06.671Z",
+  "built_at": "2026-09-11T19:32:52.079Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 474,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2122,
+    "functional_verbatim": 2123,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2620,
-  "tree_sha256": "984de9fdd6b42c1d4cf8728faad1a458ab08d8491957851e2874992610d4ae01",
+  "file_count": 2621,
+  "tree_sha256": "554ecf20aaad28b8461021791d1e5c4d2c890a860a458885227f20429b946339",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -367,12 +367,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "03379a98721207feab9a9b4c03862051ee6d52a29a0bc467ed73ae1d36bf49cd"
+      "sha256": "b15290057c38e4b80db4136d7fdd32549718e31f5975484e77098c66050c4366"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "ec75333abb0ee49b89320a86e73b56f2f3872c13c596b1e67f36e705b8ba1210"
+      "sha256": "bdf715d3196df99d675570748f7ac054522046cbe89d78b84c27eef89a52d18f"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -382,17 +382,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "bce3dcdbe37505e0fa526e02b7b379ca9ab378f6c34b41345621d55170d9f19d"
+      "sha256": "2fbbab84a89021945a707fd21d72acbad7f03b77c5fb6eb39abce44a64d4cc1b"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "d692cd6b80b1c286f6990a0ebcb3c109d51213b6cdc58cc7dc97fa52ff6fbe46"
+      "sha256": "22523f2527d8849445122c5a03332d777a63d849a5806e33d387cbd83c54fb2f"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "3fbcb50de89350e95b86180e828a16b897be32a1f8b4cdf78cc060e1c5afff86"
+      "sha256": "eeb72bda7a89900279647d6d999d2a920a986bf2f4ed3a63782cd4e36b1b3dfc"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1912,12 +1912,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "4b396cff8505cdec44f4cb471c79c5e5af8e5446a04a3ecaad0cba5435677f9a"
+      "sha256": "6b681ad5de20a67efa1d6d024d5cb5dbe5313add4ec51d94a30a0025fa567ba2"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "8292a0f17190f803436bd3ae60f7ca36631d57b552c3553b6f5f2cdcd4eaffd9"
+      "sha256": "301cf1db00b9f18b84cb765bbaa359329a665b1ef754dff4c21c1550ec60cae5"
     },
     {
       "path": "docs/architecture.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0e8b8ccaf7913c7d40a59f5662da9dac4cbd8ec419df1e7ada549a26d1824f67"
+      "sha256": "af50f99c27d85db0067d45e5e6eba133edcae8b3dd7388041b6824f4cb192e22"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4242,7 +4242,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "bce3dcdbe37505e0fa526e02b7b379ca9ab378f6c34b41345621d55170d9f19d"
+      "sha256": "2fbbab84a89021945a707fd21d72acbad7f03b77c5fb6eb39abce44a64d4cc1b"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -4332,7 +4332,7 @@
     {
       "path": "modules/discord/discord-channels.js",
       "mode": "0000644",
-      "sha256": "e910fb46a97b5d25338477a609eed045862020f1634e7ba4312a5b3857605d04"
+      "sha256": "aeeb86c5d61b4a06ae5429fb69bb4720d54f4782ead5d23cdce640344a568246"
     },
     {
       "path": "modules/discord/discord-inbound.js",
@@ -4382,7 +4382,7 @@
     {
       "path": "modules/discord/routes/discord.js",
       "mode": "0000644",
-      "sha256": "eeb7c7165f18e33216bff0bb8b846a1674f537a95e8853c0b88fc101c336fb53"
+      "sha256": "2229a563e11bd05f0eb047f0afc0e1d66eaddb6a7fa2fb07c429e162684246f0"
     },
     {
       "path": "modules/discord/ship-broadcast.js",
@@ -7767,12 +7767,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "747c1f7d390c913bc71f93fa96ecc76f67aea4409a3265fdf6555ca91aac5c11"
+      "sha256": "795b9955321b5ecffd9d78f515649442016285cb21f728c4001ee97ebcc32ac5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "59c1c75a1f396810212ad4654ac2dfd0f100e4c63fd3b2b7f5e11be22ce1a6fc"
+      "sha256": "33bcb1180ab5e54281e7c50d39a712d142b259f77f37b685f2bb4512b1c010fa"
     },
     {
       "path": "public-docs/index.html",
@@ -8152,7 +8152,7 @@
     {
       "path": "scripts/gds/discord-channels.js",
       "mode": "0000644",
-      "sha256": "395ad654afa348b1b00e40aa1f685ac66e9ce5961213a4d4c35c132759527ecb"
+      "sha256": "e142b2d64e919adc4781ea6a55796113ebde3a3645bd4c4ed113ff9f13cd7f6a"
     },
     {
       "path": "scripts/gds/do-api.js",
@@ -9532,7 +9532,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b2adf8fa055095fb344dad2ce76e3e0710ba0c23e3b5ccd68105b5daeded0390"
+      "sha256": "35f42575db36eb956e2479c681562e18a93d2d4973c8df0d79ac5a54048d4542"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10439,6 +10439,11 @@
       "mode": "0000644",
       "sha256": "981d34c2fb5ecb6e9b9f38ece947c6c7a400dceadf8bbcf09546c8b3a92eb899"
     },
+    {
+      "path": "tests/discord_channels_snapshot.mjs",
+      "mode": "0000644",
+      "sha256": "d4e43501ac29ea920c0c064afe601bd9fc24f87808f10986a51d981b3111946b"
+    },
     {
       "path": "tests/discord_foundation.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`)
-- 362 operations across 55 resource groups
+- 363 operations across 55 resource groups
 
 ## Use it from your project
 

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

@@ -313,6 +313,8 @@ function createClient(opts = {}) {
       getDiscordChannelsPlan: (args) => request("GET", "/discord/channels/plan", { hasBody: false }, args),
       // POST /discord/channels/reconcile — rank: metic+archon — POST /discord/channels/reconcile
       postDiscordChannelsReconcile: (args) => request("POST", "/discord/channels/reconcile", { hasBody: true }, args),
+      // GET /discord/channels/snapshot — rank: metic+archon — GET /discord/channels/snapshot
+      getDiscordChannelsSnapshot: (args) => request("GET", "/discord/channels/snapshot", { hasBody: false }, args),
     },
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId

package/clients/bongos-client/index.cjs

@@ -312,6 +312,8 @@ function createClient(opts = {}) {
       getDiscordChannelsPlan: (args) => request("GET", "/discord/channels/plan", { hasBody: false }, args),
       // POST /discord/channels/reconcile — rank: metic+archon — POST /discord/channels/reconcile
       postDiscordChannelsReconcile: (args) => request("POST", "/discord/channels/reconcile", { hasBody: true }, args),
+      // GET /discord/channels/snapshot — rank: metic+archon — GET /discord/channels/snapshot
+      getDiscordChannelsSnapshot: (args) => request("GET", "/discord/channels/snapshot", { hasBody: false }, args),
     },
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId

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

@@ -45,6 +45,7 @@ export interface GetConnectionsDegreeHandleResponse { handle: unknown; degree: u
 export interface GetConnectionsRequestsResponse { incoming: unknown; outgoing: unknown; incoming_count: unknown; outgoing_count: unknown }
 export interface GetConnectionsResponse { connections: unknown; count: unknown }
 export interface GetDiscordChannelsPlanResponse { ok: boolean; guild_id: unknown; op_count: unknown; ops: unknown; warnings: unknown }
+export interface GetDiscordChannelsSnapshotResponse { ok: boolean; guild_id: unknown; config: unknown; warnings: unknown }
 export interface GetDoneWhenPendingReviewResponse { criteria: unknown; count: unknown }
 export interface GetGithubRepoResponse { ok: boolean; repo: unknown; private_deployable: boolean }
 export interface GetGithubReposResponse { repos: unknown }
@@ -647,6 +648,8 @@ export interface BongosClient {
     getDiscordChannelsPlan(args?: RequestArgs): Promise<GetDiscordChannelsPlanResponse>;
     /** POST /discord/channels/reconcile — rank: metic+archon */
     postDiscordChannelsReconcile(args?: RequestArgs): Promise<PostDiscordChannelsReconcileResponse>;
+    /** GET /discord/channels/snapshot — rank: metic+archon */
+    getDiscordChannelsSnapshot(args?: RequestArgs): Promise<GetDiscordChannelsSnapshotResponse>;
   };
   "doneWhen": {
     /** PATCH /done-when/{criterionId} — rank: metic+archon */

package/clients/bongos-client/index.mjs

@@ -309,6 +309,8 @@ export function createClient(opts = {}) {
       getDiscordChannelsPlan: (args) => request("GET", "/discord/channels/plan", { hasBody: false }, args),
       // POST /discord/channels/reconcile — rank: metic+archon — POST /discord/channels/reconcile
       postDiscordChannelsReconcile: (args) => request("POST", "/discord/channels/reconcile", { hasBody: true }, args),
+      // GET /discord/channels/snapshot — rank: metic+archon — GET /discord/channels/snapshot
+      getDiscordChannelsSnapshot: (args) => request("GET", "/discord/channels/snapshot", { hasBody: false }, args),
     },
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId

package/docs/api/openapi.json

@@ -4338,6 +4338,47 @@
         ]
       }
     },
+    "/discord/channels/snapshot": {
+      "get": {
+        "operationId": "get_discord_channels_snapshot",
+        "tags": [
+          "discord"
+        ],
+        "summary": "GET /discord/channels/snapshot",
+        "description": "GET /api/bongos/discord/channels/snapshot — what docs/discord/channels.json WOULD say if it described the guild exactly as it is right now (task 1003510). Read-only in both directions: it writes nothing to Discord and nothing to the repo — the operator reviews the output and commits it, so the layout stays Archon-gated by merge, which is the property ADR 0037 §1 rests on. 503 when the bot is disabled / not connected to a guild. rank: archon — channel administration command.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `discord.channels.manage` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/discord/routes/discord.js",
+        "x-permissions": [
+          "discord.channels.manage"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetDiscordChannelsSnapshotResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/done-when/pending-review": {
       "get": {
         "operationId": "get_done_when_pending_review",
@@ -17101,6 +17142,23 @@
           "warnings"
         ]
       },
+      "GetDiscordChannelsSnapshotResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "guild_id": {},
+          "config": {},
+          "warnings": {}
+        },
+        "required": [
+          "ok",
+          "guild_id",
+          "config",
+          "warnings"
+        ]
+      },
       "GetDoneWhenPendingReviewResponse": {
         "type": "object",
         "properties": {
@@ -22955,9 +23013,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 362,
-  "x-schema-count": 401,
+  "x-endpoint-count": 363,
+  "x-schema-count": 402,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 270,
+  "x-response-schemas": 271,
   "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. 362 endpoints across 58 route files.
+> **Generated from the live route files** — the route file is authoritative. 363 endpoints across 58 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/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -191,12 +191,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/dependencies` | `archon` | — | POST /dependencies — create an edge "from is blocked until to is done". |
 | DELETE | `/api/bongos/dependencies` | `archon` | — | DELETE /dependencies — remove an edge (body carries the 4-tuple). |
 
-## `discord` (2)
+## `discord` (3)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
 | GET | `/api/bongos/discord/channels/plan` | `metic+archon` | — | GET /api/bongos/discord/channels/plan — dry run. |
 | POST | `/api/bongos/discord/channels/reconcile` | `metic+archon` | — | POST /api/bongos/discord/channels/reconcile — apply the config to Discord now. |
+| GET | `/api/bongos/discord/channels/snapshot` | `metic+archon` | — | GET /api/bongos/discord/channels/snapshot — what docs/discord/channels.json WOULD say if it described the guild exactly as it is right no… |
 
 ## `done-when` (4)
 

package/docs/module-api-changelog.md

@@ -1807,5 +1807,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.672 with no explicit bump. run 34632328471. (task 1002620)
   1.19.674 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.673 with no explicit bump. run 34634515595. (task 1002620)
+  1.19.675 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.674 with no explicit bump. run 34639371461. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -312,6 +312,8 @@ function createClient(opts = {}) {
       getDiscordChannelsPlan: (args) => request("GET", "/discord/channels/plan", { hasBody: false }, args),
       // POST /discord/channels/reconcile — rank: metic+archon — POST /discord/channels/reconcile
       postDiscordChannelsReconcile: (args) => request("POST", "/discord/channels/reconcile", { hasBody: true }, args),
+      // GET /discord/channels/snapshot — rank: metic+archon — GET /discord/channels/snapshot
+      getDiscordChannelsSnapshot: (args) => request("GET", "/discord/channels/snapshot", { hasBody: false }, args),
     },
     "doneWhen": {
       // PATCH /done-when/{criterionId} — rank: metic+archon — PATCH /done-when/:criterionId

package/modules/discord/discord-channels.js

@@ -178,6 +178,98 @@ function viewOverwritesEqual(a, b, ctx) {
 //   categories: [{ id, name }],
 //   channels:   [{ id, name, type, parentId, topic, overwrites:[{id,type,allow,deny}] }]
 // }
+// viewFromOverwrites — the INVERSE of resolveViewRoles + mergeViewOverwrites:
+// read a channel's real permission overwrites and say which `view` value would
+// produce them. Pure (task 1003510).
+//
+// `view: R` grants R and every rank ABOVE it, so the answer is the LOWEST rank
+// on the ladder holding an explicit VIEW allow. @everyone allowed outranks all
+// of it and means "everyone".
+//
+// Returns null for "cannot tell" — no @everyone overwrite AND no rank role
+// allowed, which is a channel the bot has never touched and which simply
+// inherits its category. Null is the honest answer there, and the caller emits
+// no `view` key so the channel inherits in the config exactly as it does in the
+// guild. Do NOT collapse null to 'everyone': that would write a claim the guild
+// never made, and a later reconcile would act on it.
+function viewFromOverwrites(overwrites, ctx) {
+  const { everyoneId, roleMap = {} } = ctx || {};
+  const has = (o, field) => (BigInt((o && o[field]) || 0) & VIEW_CHANNEL) !== 0n;
+  const byId = new Map((overwrites || []).map((o) => [String(o.id), o]));
+
+  const everyone = byId.get(String(everyoneId));
+  if (everyone && has(everyone, 'allow')) return 'everyone';
+
+  for (const rank of RANK_LADDER) {           // low -> high: first allow wins
+    const rid = roleMap[rank] ? String(roleMap[rank]) : null;
+    if (rid && has(byId.get(rid), 'allow')) return rank;
+  }
+  // @everyone explicitly DENIED but no rank allowed: restricted to nobody we
+  // manage. resolveViewRoles fails safe to archon, so mirror that rather than
+  // inventing wider access.
+  if (everyone && has(everyone, 'deny')) return 'archon';
+  return null;
+}
+
+// configFromSnapshot — turn a LIVE guild snapshot into channels.json shape, so
+// the file can be seeded from what the guild really is instead of from a guess
+// (task 1003510; ADR 0037 §1 calls channels.json the single source of truth, and
+// that is only true once the channels actually in the guild are written down).
+//
+// THE CORRECTNESS PROPERTY, and the reason this is worth having as a pure
+// function: feeding the result straight back to planChannelReconcile against the
+// SAME snapshot must produce ZERO ops. If any field is inverted wrongly — a view,
+// a topic, a name, a parent — the planner emits an op for it, so the round trip
+// is a total test of this function rather than a field-by-field restatement of it.
+//
+// That zero-ops guarantee holds for a guild the bot has already reconciled. On a
+// guild it has NOT, a channel may carry no @everyone overwrite at all; the config
+// then omits its `view`, it inherits the category, and the planner may rightly
+// emit an edit. That difference is real and belongs in the operator's review, not
+// hidden here — which is why `warnings` is returned rather than swallowed.
+//
+// Channels with no parent category are REPORTED, never invented: channels.json
+// can only express a channel nested in a category, and the omitted-is-untouched
+// rule (see the file's own header) makes leaving them out the safe default.
+function configFromSnapshot(snapshot, ctx) {
+  const warnings = [];
+  const cats = (snapshot.categories || []).map((c) => ({
+    id: String(c.id),
+    name: c.name,
+    view: viewFromOverwrites(c.overwrites, ctx),
+    channels: [],
+  }));
+  const byId = new Map(cats.map((c) => [c.id, c]));
+
+  for (const ch of snapshot.channels || []) {
+    if (ch.type !== 0) continue;                       // text channels only, as snapshotFromGuild already filters
+    const parent = ch.parentId ? byId.get(String(ch.parentId)) : null;
+    if (!parent) {
+      warnings.push(`channel "${ch.name}" has no category — channels.json cannot express an uncategorised channel, so it is omitted (and therefore left untouched).`);
+      continue;
+    }
+    const view = viewFromOverwrites(ch.overwrites, ctx);
+    const entry = { key: slugify(ch.name), name: ch.name, topic: ch.topic || '' };
+    // Emit `view` only when it DIFFERS from the category's — the planner reads
+    // `ch.view || cat.view`, so an identical value is noise that drifts later.
+    if (view !== null && view !== parent.view) entry.view = view;
+    if (view === null) {
+      warnings.push(`channel "${ch.name}" carries no VIEW overwrite the bot manages — it inherits category "${parent.name}"; confirm that is intended before applying.`);
+    }
+    parent.channels.push(entry);
+  }
+
+  const categories = cats.map((c) => ({
+    name: c.name,
+    view: c.view === null ? 'everyone' : c.view,
+    channels: c.channels,
+  }));
+  for (const c of cats) {
+    if (c.view === null) warnings.push(`category "${c.name}" carries no VIEW overwrite the bot manages — recorded as "everyone"; confirm before applying.`);
+  }
+  return { config: { categories }, warnings };
+}
+
 // Ops never include deletions. Categories are planned before their channels so
 // the apply step can resolve a freshly-created parent id.
 function planChannelReconcile(snapshot, config, ctx) {
@@ -323,6 +415,18 @@ function computePlan(deps = realDeps) {
   return { ok: true, ops, warnings, guildId: String(guild.id) };
 }
 
+// computeSnapshotConfig — what channels.json WOULD say if it described the guild
+// as it is right now (task 1003510). Read-only: it touches Discord only through
+// the same getGuild() the planner uses, and writes nothing anywhere.
+function computeSnapshotConfig(deps = realDeps) {
+  const guild = deps.getGuild();
+  if (!guild) return { ok: false, reason: 'no_guild', config: null, warnings: [] };
+  const roleMap = deps.loadRoleMap();
+  const ctx = { everyoneId: String(guild.id), roleMap, botId: botIdFromGuild(guild) };
+  const { config, warnings } = configFromSnapshot(snapshotFromGuild(guild), ctx);
+  return { ok: true, config, warnings, guildId: String(guild.id) };
+}
+
 // Apply the plan to Discord. Best-effort, never throws. Returns a summary.
 // Categories are created first so child channels can resolve their parent id.
 async function reconcileChannels(deps = realDeps) {
@@ -398,6 +502,8 @@ module.exports = {
   // pure (tested)
   slugify,
   resolveViewRoles,
+  viewFromOverwrites,
+  configFromSnapshot,
   mergeViewOverwrites,
   viewOverwritesEqual,
   planChannelReconcile,
@@ -405,6 +511,7 @@ module.exports = {
   loadConfig,
   snapshotFromGuild,
   computePlan,
+  computeSnapshotConfig,
   reconcileChannels,
   CONFIG_PATH,
   VIEW_CHANNEL,

package/modules/discord/routes/discord.js

@@ -14,6 +14,9 @@
 
 const express = require('express');
 const api = require('../../../src/module-api');
+// Structured + attributable, and the console ratchet counts raw console calls —
+// the api.logger(<module key>) precedent every other module's routes follow.
+const log = api.logger('discord');
 const auth = require('../auth');
 const db = require('../db');
 const shipBroadcast = require('../ship-broadcast');
@@ -93,7 +96,28 @@ module.exports = function buildDiscordRouter() {
       }
       return res.json({ ok: true, guild_id: plan.guildId, op_count: plan.ops.length, ops: plan.ops, warnings: plan.warnings });
     } catch (err) {
-      console.error('[gds] GET /discord/channels/plan', err);
+      log.error({ err: err && err.message }, 'GET /discord/channels/plan failed');
+      return res.fail('internal_error', 500);
+    }
+  });
+
+  // GET /api/bongos/discord/channels/snapshot — what docs/discord/channels.json
+  // WOULD say if it described the guild exactly as it is right now (task 1003510).
+  // Read-only in both directions: it writes nothing to Discord and nothing to the
+  // repo — the operator reviews the output and commits it, so the layout stays
+  // Archon-gated by merge, which is the property ADR 0037 §1 rests on.
+  // 503 when the bot is disabled / not connected to a guild.
+  // rank: archon — channel administration command.
+  router.get('/discord/channels/snapshot', auth.requireBuilder, auth.requirePermission('discord.channels.manage'), async (req, res) => {
+    try {
+      const channels = require('../discord-channels');
+      const snap = channels.computeSnapshotConfig();
+      if (!snap.ok) {
+        return res.fail('bot_unavailable', 503, { reason: snap.reason });
+      }
+      return res.json({ ok: true, guild_id: snap.guildId, config: snap.config, warnings: snap.warnings });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /discord/channels/snapshot failed');
       return res.fail('internal_error', 500);
     }
   });
@@ -111,7 +135,7 @@ module.exports = function buildDiscordRouter() {
       }
       return res.json({ ok: true, applied: result.applied, failed: result.failed, total: result.total, warnings: result.warnings });
     } catch (err) {
-      console.error('[gds] POST /discord/channels/reconcile', err);
+      log.error({ err: err && err.message }, 'POST /discord/channels/reconcile failed');
       return res.fail('internal_error', 500);
     }
   });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.674",
+  "version": "1.19.675",
   "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/scripts/gds/discord-channels.js

@@ -10,8 +10,9 @@
 // directly — it asks the deployed bot (via the API) to do the work.
 //
 // Usage:
-//   node scripts/gds/discord-channels.js plan     # dry run: what WOULD change
+//   node scripts/gds/discord-channels.js plan      # dry run: what WOULD change
 //   node scripts/gds/discord-channels.js apply     # apply docs/discord/channels.json to Discord
+//   node scripts/gds/discord-channels.js snapshot  # print the guild AS channels.json (seed the file)
 //
 // The channel layout itself is edited in docs/discord/channels.json and merged
 // (rank-gated) — this command just triggers the reconcile.
@@ -20,8 +21,8 @@ const { cliClient } = require('./cli-lib');
 
 async function main() {
   const cmd = (process.argv[2] || '').toLowerCase();
-  if (cmd !== 'plan' && cmd !== 'apply') {
-    console.error('usage: node scripts/gds/discord-channels.js <plan|apply>');
+  if (cmd !== 'plan' && cmd !== 'apply' && cmd !== 'snapshot') {
+    console.error('usage: node scripts/gds/discord-channels.js <plan|apply|snapshot>');
     process.exit(2);
   }
 
@@ -29,6 +30,8 @@ async function main() {
   let res;
   if (cmd === 'plan') {
     res = await api.discord.getDiscordChannelsPlan();
+  } else if (cmd === 'snapshot') {
+    res = await api.discord.getDiscordChannelsSnapshot();
   } else {
     res = await api.discord.postDiscordChannelsReconcile({ body: {} });
   }
@@ -47,7 +50,15 @@ async function main() {
     process.exit(1);
   }
 
+  // Warnings go to STDERR so `snapshot > channels.json` writes clean JSON.
   for (const w of body.warnings || []) console.warn(`warning: ${w}`);
+  if (cmd === 'snapshot') {
+    // STDOUT is the file body and nothing else — this command exists to be
+    // redirected. Review the diff before committing: it is the guild's real
+    // state, which is not necessarily the state anyone intended.
+    console.log(JSON.stringify(body.config, null, 2));
+    return;
+  }
   if (cmd === 'plan') {
     const ops = body.ops || [];
     if (!ops.length) { console.log('In sync — no channel changes needed.'); return; }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.674'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.675'; // 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('dev-box'); log.info('mounted');

package/tests/discord_channels_snapshot.mjs

@@ -0,0 +1,198 @@
+// tests/discord_channels_snapshot.mjs
+//
+// Seeding docs/discord/channels.json from the LIVE guild (task 1003510).
+//
+// WHY THIS EXISTS. ADR 0037 §1 calls channels.json "the single source of truth"
+// and rests its security argument on it — changing channels means editing a repo
+// file and merging it, and merging is rank-gated, so the layout is Archon-gated
+// by construction. That property only holds for channels the file actually
+// describes. It described one (board-room, task 1003033); the rest of the guild
+// was configured somewhere untracked. Reconstructing them by hand from the ADR's
+// access table was rejected on purpose: the table lists `view` but no names and
+// no topics, so guessing would make the bot EDIT live channels to match an
+// invention. `configFromSnapshot` reads the real values instead.
+//
+// THE PROPERTY THAT MAKES IT TRUSTWORTHY — and the whole point of this file:
+//
+//     planChannelReconcile(snapshot, configFromSnapshot(snapshot).config) === no ops
+//
+// Feeding the derived config straight back at the guild it came from must ask for
+// NOTHING. Any field inverted wrongly — a view, a name, a topic, a parent — makes
+// the planner emit an op, so this one assertion tests the whole function instead
+// of restating it field by field. A config that round-trips is one an operator can
+// commit without the next reconcile rewriting the guild.
+//
+// Pure: no Discord, no network, no DB.
+//
+// Run:  node tests/discord_channels_snapshot.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ch = require('../modules/discord/discord-channels.js');
+const { configFromSnapshot, viewFromOverwrites, planChannelReconcile, mergeViewOverwrites, resolveViewRoles } = ch;
+
+const EVERYONE = '100';
+const ROLES = { xenos: '201', thetes: '202', metic: '203', archon: '204' };
+const BOT = '999';
+const ctx = { everyoneId: EVERYONE, roleMap: ROLES, botId: BOT };
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (e) { console.error(`  FAIL ${name}\n     ${e.message}`); failed++; }
+}
+
+// Build the overwrites a REAL reconciled channel carries for a given view, using
+// the production forward path — so the fixtures are what the bot actually writes,
+// not a hand-rolled guess at it.
+const owFor = (view) => mergeViewOverwrites([], resolveViewRoles(view, ROLES), ctx);
+
+// ---- the inverse, on its own ----------------------------------------------
+
+test('everyone-visible reads back as "everyone"', () => {
+  assert.equal(viewFromOverwrites(owFor('everyone'), ctx), 'everyone');
+});
+
+test('each rank round-trips through the overwrites the bot writes', () => {
+  for (const rank of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(viewFromOverwrites(owFor(rank), ctx), rank, `view=${rank}`);
+  }
+});
+
+test('the LOWEST allowed rank wins — view grants that rank and every rank above', () => {
+  // thetes' overwrites allow thetes+metic+archon. The answer must be the floor,
+  // not whichever happens to be first in the array.
+  const ow = owFor('thetes');
+  assert.ok(ow.some((o) => o.id === ROLES.archon), 'fixture really does allow archon too');
+  assert.equal(viewFromOverwrites(ow, ctx), 'thetes');
+});
+
+test('no managed overwrite at all reads back as null, never "everyone"', () => {
+  // A channel the bot has never touched. Claiming "everyone" here would write a
+  // claim the guild never made, and the next reconcile would act on it.
+  assert.equal(viewFromOverwrites([], ctx), null);
+  assert.equal(viewFromOverwrites([{ id: '777', type: 0, allow: '0', deny: '0' }], ctx), null);
+});
+
+test('@everyone denied with no rank allowed fails safe to archon', () => {
+  const ow = [{ id: EVERYONE, type: 0, allow: '0', deny: '1024' }];
+  assert.equal(viewFromOverwrites(ow, ctx), 'archon', 'mirrors resolveViewRoles fail-safe');
+});
+
+// ---- the round trip --------------------------------------------------------
+
+// A guild shaped like the real one: a public category, a restricted one, emoji in
+// the names, and a channel whose view is TIGHTER than its category's.
+function guild() {
+  return {
+    categories: [
+      { id: '1', name: 'COMMONS', overwrites: owFor('everyone') },
+      { id: '2', name: 'BUILDERS', overwrites: owFor('xenos') },
+    ],
+    channels: [
+      { id: '10', name: '👋-welcome', type: 0, parentId: '1', topic: 'Start here.', overwrites: owFor('everyone') },
+      { id: '11', name: '📯-ship-news', type: 0, parentId: '1', topic: 'What shipped.', overwrites: owFor('everyone') },
+      { id: '12', name: '🏛️-board-room', type: 0, parentId: '2', topic: 'Ratification votes.', overwrites: owFor('xenos') },
+      { id: '13', name: '🔒-archon-only', type: 0, parentId: '2', topic: 'Archon business.', overwrites: owFor('archon') },
+    ],
+  };
+}
+
+test('ROUND TRIP: the derived config asks the planner for nothing', () => {
+  const snapshot = guild();
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.deepEqual(warnings, [], 'a fully-reconciled guild produces no warnings');
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], `expected zero ops, got: ${JSON.stringify(ops.map((o) => [o.op, o.name]))}`);
+});
+
+test('the real names survive, emoji and all — they are what slug matching needs', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const names = config.categories.flatMap((c) => c.channels.map((x) => x.name));
+  assert.deepEqual(names, ['👋-welcome', '📯-ship-news', '🏛️-board-room', '🔒-archon-only']);
+  const keys = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.deepEqual(keys, ['welcome', 'ship-news', 'board-room', 'archon-only'], 'key is the slug');
+});
+
+test('topics are carried verbatim — the ADR table has none, which is why guessing was refused', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const commons = config.categories.find((c) => c.name === 'COMMONS');
+  assert.equal(commons.channels.find((c) => c.key === 'ship-news').topic, 'What shipped.');
+});
+
+test('a channel view EQUAL to its category is omitted; a tighter one is stated', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  assert.equal(builders.view, 'xenos');
+  // board-room matches its category → inherits, so no `view` key to drift later.
+  assert.equal('view' in builders.channels.find((c) => c.key === 'board-room'), false);
+  // archon-only is tighter → must be stated or the config would widen it.
+  assert.equal(builders.channels.find((c) => c.key === 'archon-only').view, 'archon');
+});
+
+test('a tighter channel view is not merely recorded — it survives the round trip', () => {
+  // Guard against "stated but wrong": drop the view and the planner must object.
+  const snapshot = guild();
+  const { config } = configFromSnapshot(snapshot, ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  delete builders.channels.find((c) => c.key === 'archon-only').view;
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.ok(ops.length > 0, 'removing the tighter view must make the planner want to widen it');
+});
+
+// ---- the honest edges ------------------------------------------------------
+
+test('an uncategorised channel is REPORTED and omitted, never invented into a category', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '14', name: 'stray', type: 0, parentId: null, topic: '', overwrites: owFor('everyone') });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const all = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.ok(!all.includes('stray'), 'omitted — channels.json cannot express it');
+  assert.ok(warnings.some((w) => /stray/.test(w) && /no category/.test(w)), 'and said so');
+  // Omitted means UNTOUCHED, which is the file header's own rule.
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], 'an omitted channel still produces no op');
+});
+
+test('a never-reconciled channel warns instead of silently claiming a view', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '15', name: 'untouched', type: 0, parentId: '1', topic: '', overwrites: [] });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const entry = config.categories.find((c) => c.name === 'COMMONS').channels.find((c) => c.key === 'untouched');
+  assert.equal('view' in entry, false, 'inherits the category, as it does in the guild');
+  assert.ok(warnings.some((w) => /untouched/.test(w)), 'the operator is told before they apply');
+});
+
+test('a CATEGORY with no managed overwrite is recorded as everyone, and warns', () => {
+  // The category-side twin of the channel null path above. A guild can carry a
+  // category the bot has never restricted; channels.json has no way to say
+  // "inherits" for a category (it is the top of the tree), so 'everyone' is the
+  // only expressible answer — and it is a WIDER claim than the guild made, which
+  // is exactly why it has to warn rather than pass silently.
+  const snapshot = {
+    categories: [{ id: '1', name: 'UNMANAGED', overwrites: [] }],
+    channels: [{ id: '10', name: 'chat', type: 0, parentId: '1', topic: '', overwrites: owFor('everyone') }],
+  };
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.equal(config.categories[0].view, 'everyone');
+  assert.ok(
+    warnings.some((w) => /UNMANAGED/.test(w) && /confirm/i.test(w)),
+    'the operator is told the category view was assumed, not read'
+  );
+});
+
+test('the output is the shape channels.json actually declares', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  assert.deepEqual(Object.keys(config), ['categories']);
+  for (const c of config.categories) {
+    assert.deepEqual(Object.keys(c).sort(), ['channels', 'name', 'view']);
+    for (const x of c.channels) {
+      for (const k of Object.keys(x)) assert.ok(['key', 'name', 'topic', 'view'].includes(k), `unexpected key ${k}`);
+    }
+  }
+});
+
+console.log(`\ndiscord_channels_snapshot: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);