@bongos/core 1.19.1010 → 1.19.1012

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.1012",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1010",
+      "version": "1.19.1012",
       "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.1012",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/gen-file-map.js

@@ -91,16 +91,31 @@ function materializedNames(absDir) { return new Set(Object.keys(readModuleSkills
 // The subdirs of `relDir` holding at least one TRACKED file (task 1004213). An untracked one is the
 // builder's own — a locally-installed plugin skill, or the empty husk a plugin extract leaves — and
 // listing it would publish one machine's tooling into a shared doc on every post-merge regen.
-// null when `root` is not the top of a git work tree (a packaged install, ADR 0108 §1): nothing to ask.
+// tracked: null when `root` is not the top of a git work tree (a packaged install, ADR 0108 §1).
+// gitError: git COULD not answer (task 1004222) — a safe.directory refusal, git off PATH, a broken
+// GIT_DIR, ENOBUFS. That also falls back to the disk listing, but loudly: main() warns and fails --check.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+// Discovery's own refusal. A broken GIT_DIR also exits 128 "not a git repository: '<dir>'", without this tail.
+const NOT_A_REPO = /not a git repository \(or any (of the )?parent/;
 function trackedSubdirs(root, relDir) {
-  const git = (args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  // LC_ALL=C: the refusal is matched by its text, which a translated git would not print.
+  const git = (args) => execFileSync('git', args, {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: GIT_MAX_BUFFER, env: { ...process.env, LC_ALL: 'C' },
+  });
   try {
-    if (git(['rev-parse', '--show-prefix']).trim() !== '') return null;
-    return new Set(git(['ls-files', '-z', '--', relDir]).split('\0')
-      .map((p) => p.slice(relDir.length + 1).split('/'))
-      .filter((segs) => segs.length > 1)
-      .map((segs) => segs[0]));
-  } catch { return null; }
+    if (git(['rev-parse', '--show-prefix']).trim() !== '') return { tracked: null, gitError: null };
+    return {
+      tracked: new Set(git(['ls-files', '-z', '--', relDir]).split('\0')
+        .map((p) => p.slice(relDir.length + 1).split('/'))
+        .filter((segs) => segs.length > 1)
+        .map((segs) => segs[0])),
+      gitError: null,
+    };
+  } catch (err) {
+    const stderr = String(err.stderr || '').trim();
+    if (err.status === 128 && NOT_A_REPO.test(stderr)) return { tracked: null, gitError: null };
+    return { tracked: null, gitError: stderr.split('\n')[0] || err.code || err.message };
+  }
 }
 
 // Immediate subdirectories of an absolute dir, sorted by name (deterministic); materialised
@@ -120,7 +135,7 @@ function listSubdirs(absDir) {
 function buildSection(section, notes) {
   const absDir = path.join(REPO_ROOT, section.dir);
   const present = listSubdirs(absDir);
-  const tracked = trackedSubdirs(REPO_ROOT, section.dir);
+  const { tracked, gitError } = trackedSubdirs(REPO_ROOT, section.dir);
   const names = tracked ? present.filter((n) => tracked.has(n)) : present;
   const sectionNotes = (notes && notes[section.notesKey]) || {};
   const entries = names.map((name) => {
@@ -135,7 +150,7 @@ function buildSection(section, notes) {
   // A note is a ghost only when its dir is gone from disk — one not yet `git add`ed is not.
   const onDisk = new Set(present);
   const stale = Object.keys(sectionNotes).filter((k) => !onDisk.has(k)).map((k) => `${section.notesKey}.${k}`);
-  return { ...section, absDir, entries, missing, stale };
+  return { ...section, absDir, entries, missing, stale, gitError };
 }
 
 function buildModel() {
@@ -244,6 +259,7 @@ function computeWrites() {
   const model = buildModel();
   const missing = model.flatMap((m) => m.missing);
   const stale = model.flatMap((m) => m.stale);
+  const gitErrors = [...new Set(model.map((m) => m.gitError).filter(Boolean))];
   const writes = [];
   let markersMissing = [];
   let mapText = '';
@@ -258,7 +274,7 @@ function computeWrites() {
     mapText = next; // coverage reads the POST-generation text, so a regen never changes the verdict
   }
   const modules = moduleCoverage(mapText);
-  return { model, writes, missing, stale, markersMissing, modules };
+  return { model, writes, missing, stale, gitErrors, markersMissing, modules };
 }
 
 function main() {
@@ -267,7 +283,7 @@ function main() {
     process.stdout.write(JSON.stringify(buildModel(), null, 2) + '\n');
     return;
   }
-  const { writes, missing, stale, markersMissing, modules } = computeWrites();
+  const { writes, missing, stale, gitErrors, markersMissing, modules } = computeWrites();
 
   // A missing note (dir without a note) or a stale note (note without a dir) is a hard failure in
   // BOTH modes: in --check it fails CI; in write mode we still report it (and render a visible
@@ -275,6 +291,7 @@ function main() {
   const problems = [];
   if (missing.length) problems.push(`notes MISSING for: ${missing.join(', ')} — add a one-line note to docs/file-map.notes.json`);
   if (stale.length) problems.push(`notes are STALE (no such dir) — remove from docs/file-map.notes.json: ${stale.join(', ')}`);
+  for (const e of gitErrors) problems.push(`git could not list tracked files (${e}) — every dir on disk was listed, untracked plugin installs included; fix git (PATH, safe.directory) and re-run (task 1004222)`);
   if (markersMissing.length) problems.push(`docs/file-map.md is missing generated markers for: ${markersMissing.join(', ')}`);
   if (modules.undocumented.length) problems.push(`modules with NO docs/file-map.md entry: ${modules.undocumented.map((k) => `${MODULES_DIR}/${k}`).join(', ')} — add an entry to the modules/ block of docs/file-map.md (task 1004066)`);
   for (const d of modules.defects) problems.push(`module-coverage SCAN DEFECT — ${d}`);

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.1012'; // 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/file_map.mjs

@@ -2,7 +2,7 @@
 // (task 1276 / ADR 0066). Mirrors tests/session_index.mjs + tests/repo_map.mjs.
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
@@ -90,10 +90,19 @@ function fixtureRoot({ git }) {
   }
   return root;
 }
-const skillsSectionAt = (cwd) => JSON.parse(execFileSync(process.execPath,
+const skillsSectionAt = (cwd, env) => JSON.parse(execFileSync(process.execPath,
   ['-e', `process.stdout.write(JSON.stringify(require(${JSON.stringify(GEN)}).buildModel()))`],
-  { cwd, encoding: 'utf8' })).find((s) => s.id === 'skills');
+  { cwd, encoding: 'utf8', env })).find((s) => s.id === 'skills');
 const skillNamesAt = (cwd) => skillsSectionAt(cwd).entries.map((e) => e.name);
+function genAt(cwd, args, env) {
+  const r = spawnSync(process.execPath, [GEN, ...args], { cwd, encoding: 'utf8', env });
+  return { code: r.status, stderr: r.stderr };
+}
+// Two ways git fails to answer inside a real work tree (task 1004222): no git on PATH (ENOENT), and a
+// GIT_DIR naming nothing — exit 128 like "not a repository", but not discovery's own refusal.
+// PATH is dropped under every casing: Windows spells it `Path`, and a copy of both keys is ambiguous.
+const withoutGit = (root) => ({ ...Object.fromEntries(Object.entries(process.env).filter(([k]) => k.toUpperCase() !== 'PATH')), PATH: path.join(root, 'no-bin') });
+const brokenGitDir = (root) => ({ ...process.env, GIT_DIR: path.join(root, 'no-such-git-dir') });
 
 test('--check FAILS (exit 2) when a new tracked skill has no note — a skill can no longer land undescribed', () => {
   const root = fixtureRoot({ git: true });
@@ -128,15 +137,38 @@ test('outside a git work tree (a packaged install) every dir on disk is still li
   const nested = path.join(parent, 'instance');
   try {
     assert.deepEqual(skillNamesAt(root), ['empty-husk', 'local-plugin', 'new-skill']);
+    // Silently: not being in a repository is the packaged install's normal state, not a git failure.
+    assert.equal(skillsSectionAt(root).gitError, null);
+    assert.doesNotMatch(genAt(root, ['--check']).stderr, /git could not/);
     // A root that is a SUBDIR of some repo is not that repo's top: its files are not the repo's to judge.
     mkdirSync(path.join(nested, '.claude', 'skills', 'inner'), { recursive: true });
     assert.deepEqual(skillNamesAt(nested), ['inner']);
+    assert.equal(skillsSectionAt(nested).gitError, null);
   } finally {
     rmSync(root, { recursive: true, force: true });
     rmSync(parent, { recursive: true, force: true });
   }
 });
 
+test('a git failure inside a work tree is NOT "not a repository" — it warns in write mode and fails --check', () => {
+  const root = fixtureRoot({ git: true });
+  try {
+    for (const [shape, env, named] of [['git missing from PATH', withoutGit(root), /ENOENT/], ['GIT_DIR naming nothing', brokenGitDir(root), /not a git repository: /]]) {
+      assert.match(skillsSectionAt(root, env).gitError || '', named, `${shape}: the model names the git error`);
+      const check = genAt(root, ['--check'], env);
+      assert.equal(check.code, 2, `${shape}: --check must fail rather than pass on an unfiltered listing`);
+      assert.match(check.stderr, /gen-file-map --check: git could not list tracked files/, shape);
+      const write = genAt(root, [], env);
+      assert.equal(write.code, 2, `${shape}: write mode exits non-zero`);
+      assert.match(write.stderr, /gen-file-map: WARN git could not list tracked files/, shape);
+    }
+    // The same root with git answering carries no git error: the failure above is the env, not the fixture.
+    assert.equal(skillsSectionAt(root).gitError, null);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('generation is deterministic + idempotent (a second run is a no-op)', () => {
   const r1 = run([]);
   assert.equal(r1.code, 0);

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();