@bongos/core 1.19.1009 → 1.19.1011

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.1009",
+  "version": "1.19.1011",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1009",
+      "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.1009",
+  "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.1009'; // 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();