@bongos/core 1.19.1010 → 1.19.1011

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1010",
-  "core_contract": "1.19.1010",
-  "source_commit": "2e959a08be544446bcbe4a050128862f651337f6",
+  "core_version": "1.19.1011",
+  "core_contract": "1.19.1011",
+  "source_commit": "24339084e27e496ab04322675456dc4d428df08a",
   "source_ref": "HEAD",
-  "built_at": "2026-09-24T21:57:10.279Z",
+  "built_at": "2026-09-24T22:18:21.675Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 523,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2420,
+    "functional_verbatim": 2426,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2969,
-  "tree_sha256": "1ed928f07118e31d83cb36f2f7c9e00fb8eb421f4e0c174d518a6c659944bae6",
+  "file_count": 2975,
+  "tree_sha256": "ceac975ccace002c6914b47746ed15c8c76eb5f1919ebab13fafe0cf8b0c860d",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -352,12 +352,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "e74f8574c95d4b2dbd2f6d41491346f39b59615ceeba00de62804cd16b4b5545"
+      "sha256": "26e3e9bd1e4dc4e7715eaabfdc155b98da64eefc2c002a18f4c5da0b5b288baa"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "8e70fb96ed9cc94ebde7fa33339a0a9a8bc9de57d0a16b2dd4b46a0fbdf0a68d"
+      "sha256": "6684688f85798c74d0c58853fa54c90e30a69c442708e191a3ef15b8f06ca0fb"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -367,17 +367,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "f8b8ebe06392c748ac8874200b825a3c9ffa878c2f7d6f745bdc1ce5e51d95e7"
+      "sha256": "5b844bbe07c67c1ac42f46d8a065d59039a447ca38ca6ae9f3422c081038cd8a"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "8b4264d838e666a293e8c4179ed68b07d4f8518039f7dc8f23e35842ce664163"
+      "sha256": "c339dfc8dc3cf407b2a30a9afed1c29aab87f55f96c7bd8c7316b999bd8c6a96"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "18cef2b359d26f464839c9f692a13caa9745204fddd23e8dafd4b9ad840acbe4"
+      "sha256": "24cf3312198537eb92a5c2f247faa826f596fae91a44705905bd80a5cdc8c7b0"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2162,12 +2162,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "71a0450dc086ef7fa89d0f37a4f7b90251f246447cb0036120b5de3913d9e581"
+      "sha256": "e09fe547287b2baea31a2bf0326dbc9c123c0d85786ac3db42669b7496bfe9fe"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "8876d8fb14e716aeefeeef97c4808d90e758f8ae74c63bea53eab3b5c967386c"
+      "sha256": "a4b3d6be3fdd2b518f046c7db5849435d73cbaaf9b8f2247e08ca2243f52475c"
     },
     {
       "path": "docs/architecture.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "982c59cdf01c7f07d25fe1593a21659b31366a6b4b0b09b0350a69a23eba2407"
+      "sha256": "a6d72a65cf5f1ae3f4b317e0684b642b01ad8c3944b2d4db0feddbbd49e54974"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5637,7 +5637,7 @@
     {
       "path": "modules/ideas/module.json",
       "mode": "0000644",
-      "sha256": "a869f9dec25e003006a495b3fbee45ac99c80b306cec7f16808693d70133e717"
+      "sha256": "96dc50c3ab602ea22329d3fff484113a7381cfe840d06f3ee51132ea09ea18f0"
     },
     {
       "path": "modules/ideas/pollers/descent-writer.js",
@@ -5674,6 +5674,11 @@
       "mode": "0000644",
       "sha256": "92c10dbffef40038dac64ea646372e3fcd1c70c5d2bda1d731ddbdcd508d9181"
     },
+    {
+      "path": "modules/ideas/routes/sky-mine.js",
+      "mode": "0000644",
+      "sha256": "a58dc499fd86af7499de613e61762e8adee88497dadad30f7f651aaafbbf10e3"
+    },
     {
       "path": "modules/ideas/routing.js",
       "mode": "0000644",
@@ -5684,6 +5689,11 @@
       "mode": "0000644",
       "sha256": "eb6a5cecb3ce54aeb0c85ffb752eb12a2400d0d4f5c7d48e4e05ff3cf7baf712"
     },
+    {
+      "path": "modules/ideas/sky-mine.js",
+      "mode": "0000644",
+      "sha256": "00ea7dcd84d31ef6f5f052ed200abcc0f3c58267af0fc7cd8cebc567d4ffeb28"
+    },
     {
       "path": "modules/ideas/templates.js",
       "mode": "0000644",
@@ -6027,7 +6037,7 @@
     {
       "path": "modules/lifecycle/module.json",
       "mode": "0000644",
-      "sha256": "36a03e5d8a4fc1129439356ba6daaf284d2cd2ca3d98d35f990e3215ff11198a"
+      "sha256": "472161627fdeb33b628eb3d9b4d4d58eba13dc74dacee1f661fc79856496cff8"
     },
     {
       "path": "modules/lifecycle/pg-constraint-fail.js",
@@ -6159,6 +6169,11 @@
       "mode": "0000644",
       "sha256": "2ab5931bd936c88a1e3a4339d927ef537e998f9756fc3260671f2bf701cd7dfa"
     },
+    {
+      "path": "modules/lifecycle/routes/sky.js",
+      "mode": "0000644",
+      "sha256": "1f058f4bd1033666daff1babf1cf64e9ea303ef87f9cd71fba9f3ad2815c4287"
+    },
     {
       "path": "modules/lifecycle/routes/task-route-helpers.js",
       "mode": "0000644",
@@ -6209,6 +6224,11 @@
       "mode": "0000644",
       "sha256": "e2d77bd858cc5aff1984ad6fd22f5441014cc92b9d610cacfca2a3d2861f0bc2"
     },
+    {
+      "path": "modules/lifecycle/sky.js",
+      "mode": "0000644",
+      "sha256": "e325fd288ff7a71c3db31d4d9756666d2a386ad25c3b9dd0a1bab3e5bec67be8"
+    },
     {
       "path": "modules/lifecycle/task-classifier.js",
       "mode": "0000644",
@@ -8222,12 +8242,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "493838f2051f8f9c9d9878add2840c5f4e18914607147bbcb4bdea1fcb5559fe"
+      "sha256": "2534d0c2e37f998d9e0ab7bb505469b9c10d4b22f0e65317a75a79769a344b98"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "addc61bbe9d71187f833dcebcb6cfb7136557ba6782d00270395200501ef9f49"
+      "sha256": "989026ca4569325ebd370b4e8b3956a199ecb50951f13539a362894ebcabc7e7"
     },
     {
       "path": "public-docs/index.html",
@@ -10272,7 +10292,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "be4a80ffea151ee7dcc548a28cf928376da1bcce570aa521478ea22657475905"
+      "sha256": "4f83439e8988caf0153a289fc10ba2c9aca89837322ac94158d70e21dad1aaf5"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14309,6 +14329,16 @@
       "mode": "0000644",
       "sha256": "db9e246f1ce7ef6306b938d325c450e31f2e834244f64dd2f0aaea96e760d987"
     },
+    {
+      "path": "tests/sky_mine.mjs",
+      "mode": "0000644",
+      "sha256": "799fdbebfc405f42e658a5575c5291ac7932be3fc0f16f5006e8a5656c7e8661"
+    },
+    {
+      "path": "tests/sky_read.mjs",
+      "mode": "0000644",
+      "sha256": "44db7c5b3cdf12cb0f4e7dc46e6677280a4c9796664ac117f690d833c8a5ea46"
+    },
     {
       "path": "tests/smoke_preflight.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`)
-- 414 operations across 61 resource groups
+- 416 operations across 62 resource groups
 
 ## Use it from your project
 

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

@@ -884,6 +884,12 @@ function createClient(opts = {}) {
       // GET /sessions/upload-health — rank: metic+archon — GET /sessions/upload-health
       getSessionsUploadHealth: (args) => request("GET", "/sessions/upload-health", { hasBody: false }, args),
     },
+    "sky": {
+      // GET /sky — rank: any-builder — GET /sky
+      getSky: (args) => request("GET", "/sky", { hasBody: false }, args),
+      // GET /sky/mine — rank: any-builder — GET /sky/mine
+      getSkyMine: (args) => request("GET", "/sky/mine", { hasBody: false }, args),
+    },
     "specialities": {
       // GET /specialities — rank: any-builder — GET /specialities
       getSpecialities: (args) => request("GET", "/specialities", { hasBody: false }, args),

package/clients/bongos-client/index.cjs

@@ -883,6 +883,12 @@ function createClient(opts = {}) {
       // GET /sessions/upload-health — rank: metic+archon — GET /sessions/upload-health
       getSessionsUploadHealth: (args) => request("GET", "/sessions/upload-health", { hasBody: false }, args),
     },
+    "sky": {
+      // GET /sky — rank: any-builder — GET /sky
+      getSky: (args) => request("GET", "/sky", { hasBody: false }, args),
+      // GET /sky/mine — rank: any-builder — GET /sky/mine
+      getSkyMine: (args) => request("GET", "/sky/mine", { hasBody: false }, args),
+    },
     "specialities": {
       // GET /specialities — rank: any-builder — GET /specialities
       getSpecialities: (args) => request("GET", "/specialities", { hasBody: false }, args),

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

@@ -1270,6 +1270,12 @@ export interface BongosClient {
     /** GET /sessions/upload-health — rank: metic+archon */
     getSessionsUploadHealth(args?: RequestArgs): Promise<ApiResponse>;
   };
+  "sky": {
+    /** GET /sky — rank: any-builder */
+    getSky(args?: RequestArgs): Promise<ApiResponse>;
+    /** GET /sky/mine — rank: any-builder */
+    getSkyMine(args?: RequestArgs): Promise<ApiResponse>;
+  };
   "specialities": {
     /** GET /specialities — rank: any-builder */
     getSpecialities(args?: RequestArgs): Promise<GetSpecialitiesResponse>;

package/clients/bongos-client/index.mjs

@@ -880,6 +880,12 @@ export function createClient(opts = {}) {
       // GET /sessions/upload-health — rank: metic+archon — GET /sessions/upload-health
       getSessionsUploadHealth: (args) => request("GET", "/sessions/upload-health", { hasBody: false }, args),
     },
+    "sky": {
+      // GET /sky — rank: any-builder — GET /sky
+      getSky: (args) => request("GET", "/sky", { hasBody: false }, args),
+      // GET /sky/mine — rank: any-builder — GET /sky/mine
+      getSkyMine: (args) => request("GET", "/sky/mine", { hasBody: false }, args),
+    },
     "specialities": {
       // GET /specialities — rank: any-builder — GET /specialities
       getSpecialities: (args) => request("GET", "/specialities", { hasBody: false }, args),

package/docs/api/openapi.json

@@ -237,6 +237,10 @@
       "name": "sessions",
       "description": "Endpoints under `/api/bongos/sessions`."
     },
+    {
+      "name": "sky",
+      "description": "Endpoints under `/api/bongos/sky`."
+    },
     {
       "name": "specialities",
       "description": "Endpoints under `/api/bongos/specialities`."
@@ -15855,6 +15859,68 @@
         ]
       }
     },
+    "/sky": {
+      "get": {
+        "operationId": "get_sky",
+        "tags": [
+          "sky"
+        ],
+        "summary": "GET /sky",
+        "description": "GET /sky, the whole project sky (task 1004230, ADR 0331). The same gate as GET /goals/graph, for the same reason: the viewer decides which private goals come back with their prose, and that decision is made from the authenticated request inside the read. Deliberately NOT pinned in route-rank-check: a read with no floor above sign-in has no downgrade to catch (the /inbox/sparks precedent).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/lifecycle/routes/sky.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/sky/mine": {
+      "get": {
+        "operationId": "get_sky_mine",
+        "tags": [
+          "sky"
+        ],
+        "summary": "GET /sky/mine",
+        "description": "GET /sky/mine, every thought the SIGNED-IN builder filed with its state, size and descent, capped at 1000 (task 1004230). The builder is the caller: there is no id in the path, so nobody can read a trail as somebody else through this route. The viewer's rank rides into the read so the skill-friction gate holds here as it does on the trail. Deliberately NOT pinned in route-rank-check (the /inbox/sparks precedent: a read with no floor above sign-in has no downgrade to catch).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/ideas/routes/sky-mine.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/specialities": {
       "get": {
         "operationId": "get_specialities",
@@ -26348,7 +26414,7 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 414,
+  "x-endpoint-count": 416,
   "x-schema-count": 453,
   "x-undocumented-bodies": 9,
   "x-response-schemas": 308,

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 414 endpoints across 68 route files.
+> **Generated from the live route files** — the route file is authoritative. 416 endpoints across 70 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`.
@@ -623,6 +623,13 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/sessions/search` | `metic+archon` | — | cross-builder corpus search (BFG-principal posture until 6C.1). |
 | GET | `/api/bongos/sessions/upload-health` | `metic+archon` | — | GET /sessions/upload-health — the answer to "has anyone's session upload silently stopped?", which before task 1003865 existed ONLY as a … |
 
+## `sky` (2)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| GET | `/api/bongos/sky` | `any-builder` | — | GET /sky, the whole project sky (task 1004230, ADR 0331). |
+| GET | `/api/bongos/sky/mine` | `any-builder` | — | GET /sky/mine, every thought the SIGNED-IN builder filed with its state, size and descent, capped at 1000 (task 1004230). |
+
 ## `specialities` (12)
 
 | Method | Path | Rank | Body | Description |

package/docs/module-api-changelog.md

@@ -2494,5 +2494,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1008 with no explicit bump. run 36056558236. (task 1002620)
   1.19.1010 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1009 with no explicit bump. run 36064558803. (task 1002620)
+  1.19.1011 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1010 with no explicit bump. run 36066617514. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/ideas/module.json

@@ -11,6 +11,7 @@
     "routes": [
       "inbox",
       "ratify-goal",
+      "sky-mine",
       "blockers"
     ],
     "pollers": [

package/modules/ideas/routes/sky-mine.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// modules/ideas/routes/sky-mine.js — GET /sky/mine, the caller's whole trail in
+// one read (task 1004230, sky part 2 of 5; ADR 0331).
+//
+// ITS OWN FILE, not more of inbox.js, for the reason ratify-goal.js gives: inbox
+// is INTAKE, and this is a read of what a person's intake became. The read and
+// its cap live in ../sky-mine.js so a test drives them with no express.
+//
+// The path is `/sky/mine` beside the lifecycle module's `/sky`: two modules, one
+// surface to the page. Express matches whole paths, so neither swallows the
+// other whichever mounts first — and no `:id` route exists under `/sky` to bind
+// the literal `mine` (the `/inbox/:id` trap this module's CLAUDE.md records).
+//
+// MODULE BOUNDARY: reaches core only through `../../../src/module-api`.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const skyMine = require('../sky-mine');
+
+module.exports = function buildSkyMineRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — GET /sky/mine, every thought the SIGNED-IN builder filed
+  // with its state, size and descent, capped at 1000 (task 1004230). The builder
+  // is the caller: there is no id in the path, so nobody can read a trail as
+  // somebody else through this route. The viewer's rank rides into the read so
+  // the skill-friction gate holds here as it does on the trail. Deliberately NOT
+  // pinned in route-rank-check (the /inbox/sparks precedent: a read with no floor
+  // above sign-in has no downgrade to catch).
+  router.get('/sky/mine', api.requireBuilder, api.asyncHandler('GET /sky/mine', skyMine.skyMineHandler(), { errorCode: 'sky_mine_failed' }));
+
+  return router;
+};

package/modules/ideas/sky-mine.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// modules/ideas/sky-mine.js — THE CALLER'S WHOLE TRAIL IN ONE READ (task
+// 1004230, sky part 2 of 5; goal 1000095; ADR 0331).
+//
+// WHY. The ideator's sky draws every thought a person filed at once — its state,
+// its size, its descent — and the trail route (`GET /inbox/by-builder/:id`) pages
+// that at a hundred rows. The prototype walked the pages itself; the page should
+// not. This read walks them server-side and hands back every row, the same rows
+// the room shows, so the sky and the room can never disagree about a thought.
+//
+// THE SAME ROWS, LITERALLY. Each page is `listIdeaTrailForBuilder` — the trail's
+// own projection — and the three attachers run over the whole set afterwards in
+// the trail route's order: the descent (the walk), then size (what the walk
+// paid), then state (which of the five objects — last, because it takes its
+// share off the size just left on the row). Nothing is derived here that the
+// room does not derive; ADR 0322 says the five states are derived ONCE, and this
+// file keeps that true by calling the one derivation rather than adding a second.
+//
+// THE CAP. A thousand rows. The trail's own page cap is a hundred, so this is at
+// most ten reads; a filer past a thousand thoughts gets the newest thousand and a
+// `truncated: true` the page can say out loud, never a silent slice. Ten reads
+// for the sky is still one request from the page, which is the point.
+//
+// WHOSE. The builder is the signed-in caller, from the request, never a URL
+// parameter — the room reads `/me` for the same reason: a trail is a person's,
+// and the route that lets you name a person is the other one.
+
+const inbox = require('./inbox');
+const { attachDescentToTrail } = require('./trail-descent');
+const { attachSizeToTrail } = require('./trail-size');
+const { attachStateToTrail } = require('./idea-state');
+
+const SKY_MINE_CAP = 1000;
+
+// readSkyMine — page the trail to the cap, then attach the three facts once
+// over the whole set. `deps` lets a test stand in for each read and each
+// attacher; production passes none and gets the trail's own.
+async function readSkyMine({ builderId, viewerRank = null } = {}, deps = {}) {
+  const list = deps.listIdeaTrailForBuilder || inbox.listIdeaTrailForBuilder;
+  const count = deps.countIdeaTrailForBuilder || inbox.countIdeaTrailForBuilder;
+  const descent = deps.attachDescentToTrail || attachDescentToTrail;
+  const size = deps.attachSizeToTrail || attachSizeToTrail;
+  const state = deps.attachStateToTrail || attachStateToTrail;
+  const cap = Number.isInteger(deps.cap) && deps.cap > 0 ? deps.cap : SKY_MINE_CAP;
+  const pageSize = inbox.IDEA_TRAIL_MAX_LIMIT;
+
+  const ideas = [];
+  const total = await count(builderId, { viewerRank });
+  for (let offset = 0; offset < Math.min(total, cap); offset += pageSize) {
+    const limit = Math.min(pageSize, cap - offset);
+    const page = await list(builderId, { limit, offset, viewerRank });
+    ideas.push(...page);
+    if (page.length < limit) break;
+  }
+
+  await descent(ideas);
+  await size(ideas);
+  await state(ideas);
+
+  return { builder_id: builderId, ideas, total, cap, truncated: total > ideas.length };
+}
+
+// skyMineHandler — GET /sky/mine. A factory so a test drives it with a stub
+// read and no database. Identity is the authenticated builder's, always.
+function skyMineHandler({ read = readSkyMine } = {}) {
+  return async function getSkyMine(req, res) {
+    const builderId = Number(req.builder.id);
+    const viewerRank = req.builder && req.builder.rank;
+    const out = await read({ builderId, viewerRank });
+    return res.json(out);
+  };
+}
+
+module.exports = { readSkyMine, skyMineHandler, SKY_MINE_CAP };

package/modules/lifecycle/module.json

@@ -27,7 +27,8 @@
       "rot",
       "project-settings",
       "artist-gate",
-      "removal-proposals"
+      "removal-proposals",
+      "sky"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/routes/sky.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// modules/lifecycle/routes/sky.js — GET /sky, the project sky in one read (task
+// 1004230, sky part 2 of 5; ADR 0331, ADR 0227 §11).
+//
+// WHY ITS OWN ROUTE FILE. goals.js is the goal board's surface and already
+// mounts the graph and the forest; the sky is a third view over the same rows,
+// and the one line here is the mount. The data, the cache and the handler live
+// in ../sky.js so a test drives them with no express and no database.
+//
+// The path is `/sky`, top-level, never `/goals/sky`: the ideas module contributes
+// `/sky/mine` (the caller's own trail), and the two are one surface to the page
+// even though they are two modules' reads. Express matches whole paths, so
+// `/sky` cannot swallow `/sky/mine` whichever module mounts first.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `../../../src/module-api`; `../sky` is this module's own read.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const sky = require('../sky');
+
+const log = api.logger('lifecycle');
+
+module.exports = function buildSkyRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — GET /sky, the whole project sky (task 1004230, ADR 0331).
+  // The same gate as GET /goals/graph, for the same reason: the viewer decides
+  // which private goals come back with their prose, and that decision is made
+  // from the authenticated request inside the read. Deliberately NOT pinned in
+  // route-rank-check: a read with no floor above sign-in has no downgrade to
+  // catch (the /inbox/sparks precedent).
+  router.get('/sky', api.requireBuilder, sky.skyHandler({ log }));
+
+  return router;
+};

package/modules/lifecycle/sky.js

@@ -0,0 +1,261 @@
+'use strict';
+
+// modules/lifecycle/sky.js — ONE READ FOR THE WHOLE PROJECT SKY (task 1004230,
+// sky part 2 of 5; goal 1000095; ADR 0331, ADR 0227 §11).
+//
+// WHY ONE READ. The prototype's snapshot (docs/design/mocks/sky/snapshot.js)
+// needed about 120 requests to assemble what one page draws: the goal graph, a
+// detail read per goal for its criteria, a progress rollup per version for the
+// criterion→task join, and a task list per goal. The two sky pages (parts 3 and
+// 4) draw all of it at once, so they get it at once — five queries, one JSON.
+//
+// WHAT IT IS NOT. Not a second goal graph: `goals` and `edges` come from
+// goal-graph.js's own read, so the sky's wells are the map's nodes and the sky's
+// routes are the map's edges by construction, never a copy that can drift. Not
+// the refused whole-corpus task map either (ADR 0227 §1): tasks come back
+// compact and grouped under their goal, and the page draws them only inside one
+// goal past a zoom threshold — dust below it (§11).
+//
+// THE JOIN THAT BITES. A criterion's tasks live in `task_criteria`; goal detail
+// returns only COUNTS of them, and the version progress rollup is the one place
+// the ids are joined. Rather than call that rollup once per version, the join is
+// read ONCE for every goal-bearing criterion, as the same flat (criterion, task)
+// rows `criterionProgress` folds — so `tests/sky_read.mjs` can hand the same rows
+// to `buildCriterionProgress` and to this shaper and pin that a task's criterion
+// link is identical on both.
+//
+// VISIBILITY (ADR 0112's leak rule, as goal-graph.js applies it). A private goal
+// the viewer may not read stays a well — its counts, its edges, its ring count
+// and its task count are structure, not secrets — but every piece of PROSE on it
+// comes back null: title, subtitle, category, each criterion's text, each task's
+// title. The graph only had a title and a category to hide; the sky carries more
+// prose per goal, and hiding the title while shipping the criteria under it would
+// be the leak wearing a different field name.
+//
+// THE CACHE. Sixty seconds, in-process, keyed by what decides visibility (the
+// Archon flag, else the viewer id) — a cached payload shaped for one viewer is
+// never handed to another. The response says whether it was served from cache
+// and when it was taken, so a page that just filed a thought can tell why the
+// sky has not moved yet.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const goalGraph = require('./goal-graph');
+const goalCategory = require('./goal-category');
+const { isPendingReview } = require('./done-when');
+const { TERMINAL_STATUSES } = require('./task-status');
+
+const SKY_CACHE_TTL_MS = 60 * 1000;
+
+// skyRows — the raw reads. Returns { goals, edges, extras, criteria, tasks }:
+// `goals` + `edges` exactly as goal-graph.js reads them; `extras` one row per
+// goal with the two columns the graph does not carry (subtitle, created_at);
+// `criteria` one FLAT row per (criterion, task) pair — a criterion with no task
+// arrives once with null task_* (the LEFT JOIN, the criterionProgress shape);
+// `tasks` one compact row per task under a goal. deps.pool honours the test seam.
+async function skyRows({ versionId = null, viewerId = null, viewerIsArchon = false } = {}, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const version = Array.isArray(versionId) ? (versionId[0] ?? null) : versionId;
+  const [graph, extras, criteria, tasks] = await Promise.all([
+    (deps.goalGraphRows || goalGraph.goalGraphRows)({ versionId: version, viewerId, viewerIsArchon }, deps),
+    activePool.query(
+      `SELECT g.id::text AS goal_id, g.subtitle, g.created_at
+         FROM goals g
+        WHERE ($1::text IS NULL OR g.version_id = $1)`,
+      [version]
+    ),
+    activePool.query(
+      // The criterion→task join, read once. Flat rows on purpose (see the header):
+      // the fold happens in shapeSky so a test can compare it with the rollup's.
+      `SELECT c.id::text AS id, c.goal_id::text AS goal_id, c.criterion_id, c.criterion_md,
+              c.satisfied, c.sort_order,
+              t.id::text AS task_id, t.status AS task_status
+         FROM done_when_criteria c
+         JOIN goals g ON g.id = c.goal_id
+         LEFT JOIN task_criteria tc ON tc.criterion_id = c.id
+         LEFT JOIN tasks t          ON t.id = tc.task_id
+        WHERE c.goal_id IS NOT NULL
+          AND ($1::text IS NULL OR g.version_id = $1)
+        ORDER BY c.goal_id, c.sort_order, c.criterion_id, t.id`,
+      [version]
+    ),
+    activePool.query(
+      // Compact by construction: no description, no value summary, no notes.
+      // created_at is truncated to the DAY in SQL so the payload carries ten
+      // characters per task, not twenty-seven, and the clock draws by day anyway.
+      `SELECT t.id::text AS id, t.goal_id::text AS goal_id, t.title, t.status,
+              t.credits_reward, t.created_at::date::text AS created_on,
+              CASE WHEN t.source_ref ~ '^idea:[0-9]+$' THEN substring(t.source_ref from 6) END AS idea_id
+         FROM tasks t
+         JOIN goals g ON g.id = t.goal_id
+        WHERE ($1::text IS NULL OR g.version_id = $1)
+        ORDER BY t.goal_id, t.id`,
+      [version]
+    ),
+  ]);
+  return { goals: graph.goals, edges: graph.edges, extras: extras.rows, criteria: criteria.rows, tasks: tasks.rows };
+}
+
+// foldCriteria — the flat (criterion, task) rows into one entry per criterion
+// with its task ids and the derived pending_review flag. The same fold
+// buildCriterionProgress does, minus the cnum and the per-status counts the sky
+// does not draw. Exported so the equivalence test can drive it on its own.
+function foldCriteria(rows = []) {
+  const byId = new Map();
+  for (const row of rows) {
+    let c = byId.get(String(row.id));
+    if (!c) {
+      c = {
+        id: String(row.id),
+        goal_id: row.goal_id != null ? String(row.goal_id) : null,
+        criterion_id: row.criterion_id,
+        criterion_md: row.criterion_md,
+        satisfied: row.satisfied === true,
+        task_ids: [],
+        _unshipped: 0,
+      };
+      byId.set(c.id, c);
+    }
+    if (row.task_id != null) {
+      c.task_ids.push(String(row.task_id));
+      if (!TERMINAL_STATUSES.includes(row.task_status)) c._unshipped += 1;
+    }
+  }
+  return [...byId.values()].map((c) => {
+    const { _unshipped, ...rest } = c;
+    return {
+      ...rest,
+      pending_review: isPendingReview({ satisfied: c.satisfied, linked: c.task_ids.length, unshipped: _unshipped }),
+    };
+  });
+}
+
+// shapeSky — the wire shape. Pure, so a test pins it with no database.
+//
+//   goals: [{ goal_id, title, subtitle, status, version_id, category, task_total,
+//             task_done, created_at, criteria: [{ id, criterion_id, criterion_md,
+//             satisfied, pending_review, task_ids }], tasks: [{ id, title, status,
+//             credits_reward, created_on, idea_id }] }]
+//   edges: [{ from, to, count }]           — `from` waits on `to`, the graph's own
+//   counts: { goals, edges, criteria, tasks }
+//
+// A criterion or a task whose goal is not among the wells is DROPPED — the wells
+// are the graph's nodes (goals carrying at least one task, in the version asked
+// for), and a ring drawn around no well is a line pointing at nothing.
+function shapeSky({ goals = [], edges = [], extras = [], criteria = [], tasks = [] } = {}, categoryById = new Map()) {
+  const graph = goalGraph.shapeGraph({ goals, edges }, categoryById);
+  const visibleById = new Map(goals.map((g) => [String(g.goal_id), g.visible !== false]));
+  const extraById = new Map(extras.map((x) => [String(x.goal_id), x]));
+  const wells = new Map(graph.nodes.map((n) => [n.goal_id, { ...n, criteria: [], tasks: [] }]));
+
+  let criteriaCount = 0;
+  for (const c of foldCriteria(criteria)) {
+    const well = c.goal_id != null ? wells.get(c.goal_id) : null;
+    if (!well) continue;
+    const visible = visibleById.get(c.goal_id) !== false;
+    const { goal_id, ...entry } = c;
+    well.criteria.push({ ...entry, criterion_md: visible ? entry.criterion_md : null });
+    criteriaCount += 1;
+  }
+
+  let taskCount = 0;
+  for (const t of tasks) {
+    const gid = t.goal_id != null ? String(t.goal_id) : null;
+    const well = gid != null ? wells.get(gid) : null;
+    if (!well) continue;
+    const visible = visibleById.get(gid) !== false;
+    well.tasks.push({
+      id: String(t.id),
+      title: visible ? t.title : null,
+      status: t.status,
+      credits_reward: t.credits_reward == null ? null : Number(t.credits_reward),
+      created_on: t.created_on || null,
+      idea_id: t.idea_id != null ? String(t.idea_id) : null,
+    });
+    taskCount += 1;
+  }
+
+  const out = [...wells.values()].map((w) => {
+    const visible = visibleById.get(w.goal_id) !== false;
+    const x = extraById.get(w.goal_id) || {};
+    const { depends_on, depended_on_by, ...node } = w;
+    return {
+      ...node,
+      subtitle: visible ? (x.subtitle ?? null) : null,
+      created_at: x.created_at instanceof Date ? x.created_at.toISOString() : (x.created_at ?? null),
+    };
+  });
+
+  return {
+    goals: out,
+    edges: graph.edges,
+    counts: { goals: out.length, edges: graph.edges.length, criteria: criteriaCount, tasks: taskCount },
+  };
+}
+
+// sky — read + shape. `categoryIndex` is injectable so the whole path runs in a
+// test with a fake pool and no category table (the goal-graph.js precedent).
+async function sky(opts = {}, deps = {}) {
+  const [rows, byId] = await Promise.all([
+    skyRows(opts, deps),
+    (deps.categoryIndex || goalCategory.categoryIndex)(deps),
+  ]);
+  return shapeSky(rows, byId);
+}
+
+// skyCache — the 60-second memo, keyed by what decides what the viewer may see.
+// `now` is injectable so a test can move the clock instead of waiting a minute.
+function skyCache({ ttlMs = SKY_CACHE_TTL_MS, now = Date.now } = {}) {
+  const entries = new Map();
+  return {
+    key({ viewerId, viewerIsArchon, versionId }) {
+      return `${viewerIsArchon === true ? 'archon' : `b${viewerId}`}|${versionId == null ? '' : String(versionId)}`;
+    },
+    get(key) {
+      const e = entries.get(key);
+      if (!e) return null;
+      if (now() - e.at > ttlMs) { entries.delete(key); return null; }
+      return e;
+    },
+    set(key, payload) {
+      const e = { at: now(), payload };
+      entries.set(key, e);
+      return e;
+    },
+    clear() { entries.clear(); },
+    ttlSeconds: Math.round(ttlMs / 1000),
+  };
+}
+
+// skyHandler — GET /sky. A factory, so a test drives it with a stub read, a
+// stub cache clock and no database. Identity comes from the authenticated
+// request, never the query (goal-graph.js's rule, for the same reason: a
+// caller-supplied id would let anyone ask as somebody else).
+function skyHandler({ read = sky, log = console, cache = skyCache() } = {}) {
+  return async function getSky(req, res) {
+    try {
+      const opts = {
+        versionId: (req.query && req.query.version) || null,
+        viewerId: req.builder.id,
+        viewerIsArchon: req.builder.rank === 'archon',
+      };
+      const key = cache.key(opts);
+      let entry = cache.get(key);
+      let hit = true;
+      if (!entry) {
+        hit = false;
+        entry = cache.set(key, await read(opts));
+      }
+      res.set('Cache-Control', 'private, max-age=60');
+      return res.json({
+        ...entry.payload,
+        cache: { hit, ttl_seconds: cache.ttlSeconds, taken_at: new Date(entry.at).toISOString() },
+      });
+    } catch (err) {
+      log.error('[gds] GET /sky', err);
+      return res.fail('sky_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = { sky, skyRows, shapeSky, foldCriteria, skyCache, skyHandler, SKY_CACHE_TTL_MS };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1010",
+  "version": "1.19.1011",
   "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/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.1010'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1011'; // 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/sky_mine.mjs

@@ -0,0 +1,138 @@
+// tests/sky_mine.mjs — GET /sky/mine, the caller's whole trail in one read (task
+// 1004230, sky part 2 of 5; goal 1000095; ADR 0331, ADR 0322).
+//
+// What this file pins: that the rows are the trail's own (the same list read,
+// the same three attachers, in the trail route's order — nothing derived here);
+// that the cap holds at a thousand and says so; that the builder is the
+// signed-in caller and never a URL parameter; and that the route is mounted
+// beside, not under, the lifecycle module's /sky.
+//
+// DB-free: the read is driven with stub pages and stub attachers; the handler
+// with a stub read; the mount is read from the router and the manifest.
+//
+// Run:  node tests/sky_mine.mjs
+process.env.NODE_ENV = 'test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { readSkyMine, skyMineHandler, SKY_MINE_CAP } = require(path.join(ROOT, 'modules/ideas/sky-mine.js'));
+const inbox = require(path.join(ROOT, 'modules/ideas/inbox.js'));
+const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/ideas/module.json'), 'utf8'));
+const LIB_SRC = fs.readFileSync(path.join(ROOT, 'modules/ideas/sky-mine.js'), 'utf8');
+const ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/sky-mine.js'), 'utf8');
+const TRAIL_ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'modules/ideas/routes/inbox.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+// A stub trail of N ideas, paged exactly as listIdeaTrailForBuilder pages.
+function stubTrail(n) {
+  const all = Array.from({ length: n }, (_, i) => ({ id: String(n - i), title: `Idea ${n - i}`, status: 'open' }));
+  const calls = { list: [], count: [], attach: [] };
+  const deps = {
+    listIdeaTrailForBuilder: async (builderId, { limit, offset, viewerRank }) => { calls.list.push({ builderId, limit, offset, viewerRank }); return all.slice(offset, offset + limit); },
+    countIdeaTrailForBuilder: async (builderId, { viewerRank }) => { calls.count.push({ builderId, viewerRank }); return n; },
+    attachDescentToTrail: async (ideas) => { calls.attach.push(['descent', ideas.length]); for (const i of ideas) i.descent_tasks = []; },
+    attachSizeToTrail: async (ideas) => { calls.attach.push(['size', ideas.length]); for (const i of ideas) i.size = { credits: 0, scale: 0 }; },
+    attachStateToTrail: async (ideas) => { calls.attach.push(['state', ideas.length]); for (const i of ideas) i.state = { object: 'protostar' }; },
+  };
+  return { deps, calls };
+}
+
+await test('the read pages the trail\'s own list at its own page size until the total, and returns every row', async () => {
+  const { deps, calls } = stubTrail(249);
+  const out = await readSkyMine({ builderId: 9, viewerRank: 'metic' }, deps);
+  assert.equal(out.ideas.length, 249);
+  assert.equal(out.total, 249);
+  assert.equal(out.truncated, false);
+  assert.equal(out.cap, SKY_MINE_CAP);
+  assert.equal(SKY_MINE_CAP, 1000);
+  assert.deepEqual(calls.list.map((c) => [c.limit, c.offset]), [[100, 0], [100, 100], [100, 200]], 'three pages of the trail\'s max page size');
+  assert.equal(calls.list[0].limit, inbox.IDEA_TRAIL_MAX_LIMIT, 'the page size is the trail\'s, not a number of its own');
+  for (const c of calls.list) { assert.equal(c.builderId, 9); assert.equal(c.viewerRank, 'metic', 'the viewer\'s rank rides into every page'); }
+  assert.equal(out.ideas[0].id, '249', 'newest first, as the trail orders');
+});
+
+await test('the three attachers run ONCE over the whole set, in the trail route\'s order: descent, then size, then state', async () => {
+  const { deps, calls } = stubTrail(150);
+  const out = await readSkyMine({ builderId: 9 }, deps);
+  assert.deepEqual(calls.attach, [['descent', 150], ['size', 150], ['state', 150]]);
+  assert.ok(out.ideas.every((i) => i.state && i.size && Array.isArray(i.descent_tasks)));
+});
+
+await test('the cap holds at 1000: a filer past it gets the newest thousand and truncated: true, never a silent slice', async () => {
+  const { deps, calls } = stubTrail(1234);
+  const out = await readSkyMine({ builderId: 9 }, deps);
+  assert.equal(out.ideas.length, 1000);
+  assert.equal(out.total, 1234);
+  assert.equal(out.truncated, true);
+  assert.equal(calls.list.length, 10, 'ten pages, not thirteen');
+  assert.equal(calls.list[9].offset, 900);
+  assert.equal(calls.list[9].limit, 100);
+});
+
+await test('an odd cap asks the last page for only what is left', async () => {
+  const { deps, calls } = stubTrail(500);
+  const out = await readSkyMine({ builderId: 9 }, { ...deps, cap: 250 });
+  assert.equal(out.ideas.length, 250);
+  assert.deepEqual(calls.list.map((c) => [c.limit, c.offset]), [[100, 0], [100, 100], [50, 200]]);
+  assert.equal(out.truncated, true);
+});
+
+await test('a short page ends the walk early (the count moved under us), and an empty trail reads nothing', async () => {
+  const { deps, calls } = stubTrail(0);
+  const out = await readSkyMine({ builderId: 9 }, deps);
+  assert.deepEqual(out.ideas, []);
+  assert.equal(calls.list.length, 0, 'no page is read for a total of zero');
+  assert.equal(out.truncated, false);
+
+  const { deps: d2, calls: c2 } = stubTrail(150);
+  d2.countIdeaTrailForBuilder = async () => 400; // the count claims more than the list has
+  const out2 = await readSkyMine({ builderId: 9 }, d2);
+  assert.equal(out2.ideas.length, 150);
+  assert.equal(c2.list.length, 2, 'stops on the short page rather than reading empties');
+});
+
+await test('nothing is derived here — the lib calls the trail\'s own read and the three attachers, and never touches the pool or idea-state internals', () => {
+  assert.match(LIB_SRC, /require\('\.\/inbox'\)/);
+  assert.match(LIB_SRC, /attachDescentToTrail/);
+  assert.match(LIB_SRC, /attachSizeToTrail/);
+  assert.match(LIB_SRC, /attachStateToTrail/);
+  assert.equal(/pool\.query|resolveIdeaState|SELECT /.test(LIB_SRC), false, 'no SQL and no second derivation (ADR 0322)');
+  // and the order matches the trail route's, read from its source
+  const order = (src) => ['attachDescentToTrail(', 'attachSizeToTrail(', 'attachStateToTrail('].map((n) => src.indexOf(n));
+  const trailOrder = order(TRAIL_ROUTE_SRC.slice(TRAIL_ROUTE_SRC.indexOf("'/inbox/by-builder/:id'")));
+  assert.ok(trailOrder[0] < trailOrder[1] && trailOrder[1] < trailOrder[2], 'the trail route runs descent, size, state');
+  const mine = LIB_SRC.slice(LIB_SRC.indexOf('await descent('));
+  assert.ok(mine.indexOf('await descent(') < mine.indexOf('await size(') && mine.indexOf('await size(') < mine.indexOf('await state('));
+});
+
+// ---- the handler ----------------------------------------------------------------------
+
+await test('the builder is the signed-in caller — from the request, never a param or the query', async () => {
+  let seen = null;
+  const h = skyMineHandler({ read: async (o) => { seen = o; return { builder_id: o.builderId, ideas: [], total: 0, cap: 1000, truncated: false }; } });
+  let body = null;
+  await h({ builder: { id: '41', rank: 'thetes' }, params: { id: '999' }, query: { builder_id: '998' } }, { json(b) { body = b; } });
+  assert.deepEqual(seen, { builderId: 41, viewerRank: 'thetes' });
+  assert.equal(body.builder_id, 41);
+});
+
+// ---- the mount ------------------------------------------------------------------------
+
+await test('the route is contributed by the ideas manifest at /sky/mine, gated to a signed-in builder, with no :id under /sky', () => {
+  assert.ok(manifest.contributes.routes.includes('sky-mine'), 'module.json contributes "sky-mine"');
+  assert.match(ROUTE_SRC, /router\.get\('\/sky\/mine',\s*api\.requireBuilder,/);
+  assert.equal(/\/sky\/:/.test(ROUTE_SRC), false, 'no parameterised /sky/:x that could bind the literal "mine"');
+  const factory = require(path.join(ROOT, 'modules/ideas/routes/sky-mine.js'));
+  const router = factory({});
+  const paths = router.stack.filter((l) => l.route).map((l) => l.route.path);
+  assert.deepEqual(paths, ['/sky/mine']);
+});
+
+summary();

package/tests/sky_read.mjs

@@ -0,0 +1,265 @@
+// tests/sky_read.mjs — GET /sky, the whole project sky in one read (task 1004230,
+// sky part 2 of 5; goal 1000095; ADR 0331, ADR 0227 §11).
+//
+// What this file pins is what the picture cannot show: that the wells and the
+// routes ARE the goal graph's (same read, not a copy); that a private goal stays
+// a well but loses every piece of prose, not only its title; that a task's
+// criterion link is the SAME link the version progress rollup computes, from the
+// same rows; that the payload is compact; that the cache is per viewer and
+// expires; and that identity comes from the authenticated request.
+//
+// DB-free: the pure shaper is run directly, the SQL against a recording fake
+// pool, the handler against stub collaborators (the goal_graph.mjs precedent).
+//
+// Run:  node tests/sky_read.mjs
+process.env.NODE_ENV = 'test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skyLib = require(path.join(ROOT, 'modules/lifecycle/sky.js'));
+const { shapeSky, foldCriteria, skyRows, sky, skyCache, skyHandler } = skyLib;
+const { buildCriterionProgress } = require(path.join(ROOT, 'modules/lifecycle/done-when.js'));
+const { CUT_STATUSES, DONE_STATUSES } = require(path.join(ROOT, 'modules/lifecycle/task-status.js'));
+const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/lifecycle/module.json'), 'utf8'));
+const ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/sky.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const CATS = new Map([['7', { id: 7, slug: 'security', label: 'Security' }]]);
+const g = (id, extra = {}) => ({ goal_id: String(id), title: `Goal ${id}`, status: 'open', version_id: 'V1', category_id: null, visible: true, task_total: 4, task_done: 1, ...extra });
+const e = (from, to, count = 1) => ({ from_goal_id: String(from), to_goal_id: String(to), count });
+const x = (id, extra = {}) => ({ goal_id: String(id), subtitle: `sub ${id}`, created_at: new Date('2026-09-01T00:00:00Z'), ...extra });
+// A flat (criterion, task) row in the shape both the rollup and the sky read.
+const cr = (id, goalId, taskId, taskStatus, extra = {}) => ({ id: String(id), goal_id: String(goalId), criterion_id: `slug-${id}`, criterion_md: `Criterion ${id}`, satisfied: false, sort_order: Number(id), task_id: taskId == null ? null : String(taskId), task_status: taskStatus ?? null, ...extra });
+const t = (id, goalId, extra = {}) => ({ id: String(id), goal_id: String(goalId), title: `Task ${id}`, status: 'ready', credits_reward: 30, created_on: '2026-09-02', idea_id: null, ...extra });
+
+// ---- shapeSky -------------------------------------------------------------------
+
+await test('the shape: wells carry their criteria and their compact tasks; edges are the graph\'s; counts add up', () => {
+  const out = shapeSky({
+    goals: [g(1), g(2)], edges: [e(1, 2, 3)], extras: [x(1), x(2)],
+    criteria: [cr(10, 1, 100, 'shipped'), cr(10, 1, 101, 'ready'), cr(11, 2, null)],
+    tasks: [t(100, 1, { status: 'shipped', idea_id: '555' }), t(101, 1), t(200, 2)],
+  });
+  assert.deepEqual(Object.keys(out), ['goals', 'edges', 'counts']);
+  assert.deepEqual(out.edges, [{ from: '1', to: '2', count: 3 }]);
+  assert.deepEqual(out.counts, { goals: 2, edges: 1, criteria: 2, tasks: 3 });
+  const w1 = out.goals[0];
+  assert.deepEqual(Object.keys(w1).sort(), ['category', 'created_at', 'criteria', 'goal_id', 'status', 'subtitle', 'task_done', 'task_total', 'tasks', 'title', 'version_id']);
+  assert.equal(w1.subtitle, 'sub 1');
+  assert.equal(w1.created_at, '2026-09-01T00:00:00.000Z');
+  assert.deepEqual(w1.criteria, [{ id: '10', criterion_id: 'slug-10', criterion_md: 'Criterion 10', satisfied: false, task_ids: ['100', '101'], pending_review: false }]);
+  assert.deepEqual(w1.tasks[0], { id: '100', title: 'Task 100', status: 'shipped', credits_reward: 30, created_on: '2026-09-02', idea_id: '555' });
+  assert.equal(w1.tasks[1].idea_id, null, 'a task not born of an idea carries null, not an empty string');
+  assert.deepEqual(out.goals[1].criteria[0].task_ids, [], 'a criterion with no linked task is an empty ring, not a missing one');
+});
+
+await test('nothing but the compact fields rides on a task — no description, no value summary, no notes', () => {
+  const out = shapeSky({ goals: [g(1)], extras: [x(1)], tasks: [t(1, 1, { description: 'long prose', value_summary: 'more prose', notes: 'and more' })] });
+  assert.deepEqual(Object.keys(out.goals[0].tasks[0]).sort(), ['created_on', 'credits_reward', 'id', 'idea_id', 'status', 'title']);
+});
+
+await test('a ring or a task under a goal that is not a well is dropped, not drawn to nowhere', () => {
+  const out = shapeSky({ goals: [g(1)], extras: [x(1)], criteria: [cr(10, 99, 5, 'ready')], tasks: [t(5, 99)] });
+  assert.deepEqual(out.counts, { goals: 1, edges: 0, criteria: 0, tasks: 0 });
+});
+
+await test('pending_review is derived the way the rollup derives it: every linked task terminal, at least one shipped, not yet satisfied', () => {
+  const out = shapeSky({
+    goals: [g(1)], extras: [x(1)],
+    criteria: [cr(10, 1, 1, 'shipped'), cr(10, 1, 2, 'abandoned'), cr(11, 1, 3, 'shipped'), cr(11, 1, 4, 'active'), cr(12, 1, 5, 'abandoned'), cr(13, 1, 6, 'shipped', { satisfied: true })],
+  });
+  const by = Object.fromEntries(out.goals[0].criteria.map((c) => [c.id, c]));
+  assert.equal(by['10'].pending_review, true, 'shipped + abandoned: abandoned is terminal, so nothing remains');
+  assert.equal(by['11'].pending_review, false, 'an active task still gates it');
+  assert.equal(by['12'].pending_review, true, 'all-abandoned DOES surface for review — the review flag is deliberately wider than auto-close (task 1002651, ADR 0183), and the sky must not narrow it');
+  assert.equal(by['13'].pending_review, false, 'already satisfied');
+  assert.equal(by['13'].satisfied, true);
+});
+
+await test('a PRIVATE goal the viewer cannot see stays a well with its counts, rings and tasks — but EVERY piece of prose is null, not only the title', () => {
+  const secret = { goal_id: '1', title: 'Secret roadmap', status: 'open', version_id: 'V1', category_id: 7, visible: false, task_total: 2, task_done: 0 };
+  const out = shapeSky({
+    goals: [secret, g(2)], edges: [e(2, 1)], extras: [x(1, { subtitle: 'the secret plan' }), x(2)],
+    criteria: [cr(10, 1, 100, 'ready', { criterion_md: 'secret criterion text' })],
+    tasks: [t(100, 1, { title: 'secret task title' })],
+  }, CATS);
+  const hidden = out.goals[0];
+  assert.equal(hidden.title, null);
+  assert.equal(hidden.subtitle, null);
+  assert.equal(hidden.category, null);
+  assert.equal(hidden.task_total, 2, 'counts are structure, not secrets (ADR 0112)');
+  assert.equal(hidden.criteria.length, 1, 'the ring is still drawn');
+  assert.equal(hidden.criteria[0].criterion_md, null, 'its text is not');
+  assert.deepEqual(hidden.criteria[0].task_ids, ['100'], 'the link survives — an id is not prose');
+  assert.equal(hidden.tasks[0].title, null);
+  assert.equal(hidden.tasks[0].status, 'ready');
+  assert.deepEqual(out.edges, [{ from: '2', to: '1', count: 1 }], 'and its routes still draw, or the structure would lie');
+  const json = JSON.stringify(out);
+  for (const leak of ['Secret roadmap', 'the secret plan', 'secret criterion text', 'secret task title', 'Security']) {
+    assert.equal(json.includes(leak), false, `"${leak}" is nowhere in the payload`);
+  }
+});
+
+await test('an empty corpus is a valid, empty sky', () => {
+  assert.deepEqual(shapeSky({}), { goals: [], edges: [], counts: { goals: 0, edges: 0, criteria: 0, tasks: 0 } });
+});
+
+// ---- the criterion→task link agrees with the progress rollup ------------------------
+
+await test('a task\'s criterion link is the SAME link the version progress rollup computes, from the same flat rows', () => {
+  // The rollup's rows carry cnum + task_title; the sky's carry goal_id + task_status.
+  // One set of rows, both projections, so the two folds see one truth.
+  const pairs = [[10, 1, 100, 'shipped'], [10, 1, 101, 'ready'], [11, 1, null, null], [12, 2, 200, 'active'], [12, 2, 201, 'shipped'], [12, 2, 202, 'abandoned']];
+  const rollupRows = pairs.map(([c, goal, task, status], i) => ({ cnum: c - 9, id: String(c), criterion_id: `slug-${c}`, criterion_md: `Criterion ${c}`, satisfied: false, goal_id: String(goal), task_id: task == null ? null : String(task), task_title: task == null ? null : `Task ${task}`, task_status: status }));
+  const skyRowsFlat = pairs.map(([c, goal, task, status]) => cr(c, goal, task, status));
+
+  const rollup = buildCriterionProgress('V1', rollupRows, 0, [{ id: '1', title: 'A', status: 'open' }, { id: '2', title: 'B', status: 'open' }]);
+  const folded = foldCriteria(skyRowsFlat);
+
+  const linkFromRollup = Object.fromEntries(rollup.criteria.map((c) => [c.id, c.tasks.map((tk) => String(tk.id))]));
+  const linkFromSky = Object.fromEntries(folded.map((c) => [c.id, c.task_ids]));
+  assert.deepEqual(linkFromSky, linkFromRollup);
+  // and the derived flag agrees too, criterion by criterion
+  const flagFromRollup = Object.fromEntries(rollup.criteria.map((c) => [c.id, c.pending_review]));
+  const flagFromSky = Object.fromEntries(folded.map((c) => [c.id, c.pending_review]));
+  assert.deepEqual(flagFromSky, flagFromRollup);
+  assert.equal(flagFromSky['12'], false, 'one active task keeps ring 12 open on both sides');
+});
+
+// ---- the SQL, against a recording pool -----------------------------------------------
+
+function fakePool({ goalRows = [], edgeRows = [], extraRows = [], criteriaRows = [], taskRows = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/FROM dependencies/.test(sql)) return { rows: edgeRows };
+      if (/FROM done_when_criteria/.test(sql)) return { rows: criteriaRows };
+      if (/subtitle/.test(sql)) return { rows: extraRows };
+      if (/FROM tasks t/.test(sql)) return { rows: taskRows };
+      return { rows: goalRows };
+    },
+  };
+}
+
+await test('the wells and the routes come from goal-graph.js\'s OWN read — the viewer, the Archon flag and the shared buckets ride as its bind parameters', async () => {
+  const pool = fakePool();
+  await skyRows({ versionId: 'V1', viewerId: 42, viewerIsArchon: true }, { pool });
+  const goalsQ = pool.calls.find((c) => /FROM goals g\s+JOIN tasks t/.test(c.sql));
+  assert.ok(goalsQ, 'the graph\'s goals query ran');
+  assert.deepEqual(goalsQ.params, ['V1', true, 42, CUT_STATUSES, DONE_STATUSES]);
+  assert.ok(pool.calls.some((c) => /FROM dependencies/.test(c.sql)), 'and its edges query');
+  assert.equal(pool.calls.length, 5, 'five queries, however many goals, criteria or tasks there are');
+  for (const { sql } of pool.calls) assert.equal(/\b42\b/.test(sql), false, 'no viewer id in any SQL text');
+});
+
+await test('the criterion→task join is read ONCE for every goal-bearing criterion — one query, flat rows, never per criterion or per version', async () => {
+  const pool = fakePool();
+  await skyRows({}, { pool });
+  const crit = pool.calls.filter((c) => /FROM done_when_criteria/.test(c.sql));
+  assert.equal(crit.length, 1);
+  assert.match(crit[0].sql, /LEFT JOIN task_criteria tc ON tc\.criterion_id = c\.id/);
+  assert.match(crit[0].sql, /c\.goal_id IS NOT NULL/);
+  assert.match(crit[0].sql, /LEFT JOIN tasks t\s+ON t\.id = tc\.task_id/, 'a criterion with no task still arrives (the rollup\'s LEFT JOIN)');
+});
+
+await test('the task query is compact by construction: no description, no value_summary, and the date is truncated in SQL', async () => {
+  const pool = fakePool();
+  await skyRows({}, { pool });
+  const tq = pool.calls.find((c) => /FROM tasks t\s+JOIN goals g/.test(c.sql));
+  const select = tq.sql.slice(tq.sql.indexOf('SELECT'), tq.sql.indexOf('FROM'));
+  assert.equal(/description|value_summary|notes|handoff/.test(select), false, select);
+  assert.match(select, /created_at::date/);
+  assert.match(select, /source_ref ~ '\^idea:\[0-9\]\+\$'/, 'the idea id comes from a strict source_ref match');
+});
+
+await test('a repeated ?version= (an array) binds as its first value on every query — never a driver-level 500', async () => {
+  const pool = fakePool();
+  await skyRows({ versionId: ['V1', 'V2'] }, { pool });
+  for (const { params } of pool.calls) assert.equal(params[0], 'V1');
+});
+
+await test('the payload is the shaped sky, categories included, from one fake read', async () => {
+  const pool = fakePool({
+    goalRows: [{ goal_id: '1', title: 'A', status: 'open', version_id: 'V1', category_id: 7, visible: true, task_total: 1, task_done: 0 }],
+    extraRows: [x(1)], criteriaRows: [cr(10, 1, 100, 'ready')], taskRows: [t(100, 1)],
+  });
+  const out = await sky({ viewerId: 1 }, { pool, categoryIndex: async () => CATS });
+  assert.equal(out.goals[0].category.label, 'Security');
+  assert.deepEqual(out.goals[0].criteria[0].task_ids, ['100']);
+  assert.equal(out.goals[0].tasks[0].title, 'Task 100');
+});
+
+// ---- the cache and the handler -------------------------------------------------------
+
+function run(handler, req) {
+  const res = { body: null, failed: null, headers: {}, set(k, v) { this.headers[k] = v; return this; }, json(b) { this.body = b; return this; }, fail(code, o) { this.failed = { code, o }; return this; } };
+  return handler(req, res).then(() => res);
+}
+
+await test('the handler reads identity from the authenticated request, never the query', async () => {
+  let seen = null;
+  const h = skyHandler({ read: async (o) => { seen = o; return { goals: [], edges: [], counts: {} }; }, log: { error() {} } });
+  const res = await run(h, { builder: { id: 7, rank: 'metic' }, query: { version: 'V2', viewerId: '999', viewerIsArchon: 'true' } });
+  assert.deepEqual(seen, { versionId: 'V2', viewerId: 7, viewerIsArchon: false });
+  assert.equal(res.body.cache.hit, false);
+  assert.equal(res.body.cache.ttl_seconds, 60);
+  assert.equal(res.headers['Cache-Control'], 'private, max-age=60', 'private — the payload is shaped for one viewer');
+});
+
+await test('the cache serves a second read within 60s without touching the database, says so, and expires after', async () => {
+  let now = 1_000_000;
+  let reads = 0;
+  const cache = skyCache({ now: () => now });
+  const h = skyHandler({ read: async () => { reads += 1; return { goals: [], edges: [], counts: {} }; }, log: { error() {} }, cache });
+  const req = { builder: { id: 7, rank: 'metic' }, query: {} };
+  const a = await run(h, req);
+  const b = await run(h, req);
+  assert.equal(reads, 1);
+  assert.equal(b.body.cache.hit, true);
+  assert.equal(b.body.cache.taken_at, a.body.cache.taken_at);
+  now += 61_000;
+  const c = await run(h, req);
+  assert.equal(reads, 2, 'expired — read again');
+  assert.equal(c.body.cache.hit, false);
+});
+
+await test('the cache is PER VIEWER — a payload shaped for one builder is never handed to another, and an Archon\'s never to a non-Archon', async () => {
+  const cache = skyCache({ now: () => 5 });
+  const seen = [];
+  const h = skyHandler({ read: async (o) => { seen.push(o); return { goals: [{ goal_id: '1', title: o.viewerIsArchon ? 'SEEN' : null }], edges: [], counts: {} }; }, log: { error() {} }, cache });
+  const archon = await run(h, { builder: { id: 1, rank: 'archon' }, query: {} });
+  const metic = await run(h, { builder: { id: 2, rank: 'metic' }, query: {} });
+  const other = await run(h, { builder: { id: 3, rank: 'metic' }, query: {} });
+  assert.equal(seen.length, 3, 'three viewers, three reads');
+  assert.equal(archon.body.goals[0].title, 'SEEN');
+  assert.equal(metic.body.goals[0].title, null);
+  assert.equal(other.body.cache.hit, false);
+  assert.notEqual(cache.key({ viewerId: 1, viewerIsArchon: true }), cache.key({ viewerId: 1, viewerIsArchon: false }));
+  assert.notEqual(cache.key({ viewerId: 2 }), cache.key({ viewerId: 2, versionId: 'V1' }), 'a version filter is its own entry');
+});
+
+await test('a failing read is a 500 with no internals in the body', async () => {
+  const h = skyHandler({ read: async () => { throw new Error('SELECT exploded at goals.secret_column'); }, log: { error() {} } });
+  const res = await run(h, { builder: { id: 7, rank: 'metic' }, query: {} });
+  assert.equal(res.failed.code, 'sky_failed');
+  assert.equal(res.failed.o.status, 500);
+  assert.equal(JSON.stringify(res.failed).includes('secret_column'), false);
+});
+
+// ---- the mount -----------------------------------------------------------------------
+
+await test('the route is contributed by the lifecycle manifest and gated to a signed-in builder', () => {
+  assert.ok(manifest.contributes.routes.includes('sky'), 'module.json contributes "sky"');
+  assert.match(ROUTE_SRC, /router\.get\('\/sky',\s*api\.requireBuilder,\s*sky\.skyHandler\(/);
+});
+
+summary();