@bongos/core 1.19.899 → 1.19.900

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.899",
-  "core_contract": "1.19.899",
-  "source_commit": "18e19a9f8472cc87ac263b0266d11f1d87e352d4",
+  "core_version": "1.19.900",
+  "core_contract": "1.19.900",
+  "source_commit": "b8386b789a905d1c25afd561989ef249965fd27f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T04:05:43.927Z",
+  "built_at": "2026-09-20T05:47:20.635Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 502,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2277,
+    "functional_verbatim": 2281,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2805,
-  "tree_sha256": "02493e71ddfd64f20d5be962a0a967ab57c24e1cac948681b566a8a7d87dcc75",
+  "file_count": 2809,
+  "tree_sha256": "4b02605822334dafaf22a01bd8c5d34a16066b4f1afa4b9ee147b59d385f3c3b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2632,7 +2632,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7c5f4afd7ed31a886824fdce76aea1f7a5e4ff5e0d05ac40358a18fbceb6ac58"
+      "sha256": "180322d6ddd7b22d93aa7fada4e8124cc9949afc06b97995a8394c1d472a31be"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5309,6 +5309,11 @@
       "mode": "0000644",
       "sha256": "07e5666362c91f92d34388b4f6f4507cc5387866d317970478e6cae417c19975"
     },
+    {
+      "path": "modules/ideas/descent.js",
+      "mode": "0000644",
+      "sha256": "b735a1a1c6bf892ca631b1ae8d1bac7643ea9adf39d243ef8a6c27d83451dbca"
+    },
     {
       "path": "modules/ideas/homeless-home.js",
       "mode": "0000644",
@@ -5349,10 +5354,20 @@
       "mode": "0000644",
       "sha256": "51f790ec7d5c0ad9941ed16174e260db0de18be4d4cb18af0d704a1190a1beee"
     },
+    {
+      "path": "modules/ideas/migrations/ideas_007_task_descent_edges.sql",
+      "mode": "0000644",
+      "sha256": "76f2af78af1ebb01e97ce182142c9de6b044d617cec102f9e7174ec513157c98"
+    },
     {
       "path": "modules/ideas/module.json",
       "mode": "0000644",
-      "sha256": "c9a5e2bab38b9e45e4934f578f4ebbf0966f9e971318548d5c445d2f6a3de3a7"
+      "sha256": "d78cc041fcd92485e38684a216a846e163ea443a8afea9f304aca3a2ac086d4d"
+    },
+    {
+      "path": "modules/ideas/pollers/descent-writer.js",
+      "mode": "0000644",
+      "sha256": "80faf8d20df4f051000460a0453472bd1a177ca4e9e9a31e8c5b7f3065575995"
     },
     {
       "path": "modules/ideas/routes/blockers.js",
@@ -7742,12 +7757,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "640f2bc9b3f15ca82640c73a681425eb06518b9fceb1d649486c55ad3cf73469"
+      "sha256": "a64d0eb048b0bbaebc11226da0ba59ecf3724630719a4c1e6f598d4e93f7fb64"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d04cbdbb7e6b3f4788c1b161337a4aa7935811a50100c6779e80b177f7ce7505"
+      "sha256": "0e217566767957cb7ec7607c94c10c1e99bf7b5aba1605e886058ce7929b1c2f"
     },
     {
       "path": "public-docs/index.html",
@@ -9757,7 +9772,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "452208ca788059958d16240ae3c879df1ce3ecb1db4a7084c19aeba9a453aa84"
+      "sha256": "633c325acecc72b19dc2c6758f4bcd8e5712bd4251681bbd25b1aff4e9e907bd"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11869,6 +11884,11 @@
       "mode": "0000644",
       "sha256": "8bfc36537ffccae702e74e8763534fa535486a2eb8bbf9ee546a2c7368d1dc6b"
     },
+    {
+      "path": "tests/idea_task_descent.mjs",
+      "mode": "0000644",
+      "sha256": "3adfccf9381985ad2fbf4e8911ef6cd0fcb66714a13c77de5a8318d185000d66"
+    },
     {
       "path": "tests/idea_task_lineage.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2272,5 +2272,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.897 with no explicit bump. run 35487863230. (task 1002620)
   1.19.899 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.898 with no explicit bump. run 35488237998. (task 1002620)
+  1.19.900 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.899 with no explicit bump. run 35492534307. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/ideas/descent.js

@@ -0,0 +1,214 @@
+// modules/ideas/descent.js — task→task provenance edges: the relation that
+// makes an origin tag survive a rewrite, a split and a merge (task 1004086,
+// BV2.R07, goal 1000095; ADR 0312).
+//
+// WHY THIS IS ITS OWN FILE, beside inbox.js rather than inside it. ADR 0312's
+// central claim is that provenance is a DIFFERENT RELATION from both work
+// decomposition (tasks.parent_task_id) and idea→task lineage
+// (ideas_task_lineage): the first answers "what is this work part of", the
+// second "which thought opened this work", and this one "where did this work
+// come from". Keeping it in its own module is that argument in the file layout
+// — and it keeps inbox.js under the size ratchet, which adding it there broke.
+//
+// Reads the shared pool through the published doorway (src/module-api.js — the
+// only core file a module may require, ADR 0083), the same way inbox.js does.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+
+// The walk is bounded, but the bound is a backstop, not the safety property —
+// see walk() below, which cannot revisit a node and therefore cannot loop.
+const DESCENT_MAX_DEPTH = 64;
+
+const DESCENT_RELATIONS = Object.freeze(['rewrite', 'split', 'merge', 'fold', 'cascade']);
+
+// walk — breadth-first over the edge table, one query PER LEVEL.
+//
+// WHY NOT A RECURSIVE CTE, which is the obvious shape and was the first cut.
+// A recursive CTE's working table re-expands every path independently, so a
+// densely-connected DAG — paths that converge and diverge again, which is
+// exactly what a merge followed by a split produces — costs work exponential
+// in depth, and a final GROUP BY cannot undo that because the blow-up has
+// already happened inside the recursion. A depth bound caps the depth and does
+// nothing about the breadth.
+//
+// Level-by-level BFS with a visited set fixes both at once. A node is expanded
+// AT MOST ONCE ever, so the total work is bounded by the size of the reachable
+// subgraph rather than by the number of paths through it, and the FIRST time a
+// node is reached is necessarily its SHORTEST depth — which is the depth the
+// payout decays by, and the one that stops a single descendant paying the same
+// origin twice. It also makes cycle-safety structural rather than a bound to
+// remember: a cycle simply has nothing new to visit and the walk ends.
+//
+// The cost is one round trip per level instead of one per walk. Depth decay
+// halves each hop (spec decision 16), so a descent deep enough for that to
+// matter is already worth almost nothing.
+async function walk(startId, direction, { maxDepth = DESCENT_MAX_DEPTH, client = null } = {}) {
+  const q = client || pool;
+  // Two literal statements rather than one with an interpolated column name:
+  // nothing here is caller-controlled, and a query built by concatenation is a
+  // shape a reader (and a scanner) has to stop and prove safe.
+  const SQL_UP = `SELECT parent_task_id AS id, relation
+                    FROM ideas_task_descent
+                   WHERE task_id = ANY($1::bigint[])`;
+  const SQL_DOWN = `SELECT task_id AS id, relation
+                      FROM ideas_task_descent
+                     WHERE parent_task_id = ANY($1::bigint[])`;
+  const sql = direction === 'up' ? SQL_UP : SQL_DOWN;
+
+  const found = new Map();
+  const visited = new Set([String(startId)]);
+  let frontier = [Number(startId)];
+
+  for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth += 1) {
+    const { rows } = await q.query(sql, [frontier]);
+    const next = [];
+    for (const r of rows) {
+      const key = String(r.id);
+      if (visited.has(key)) continue;   // already reached at a shallower depth
+      visited.add(key);
+      found.set(key, { id: r.id, depth, relation: r.relation });
+      next.push(Number(r.id));
+    }
+    frontier = next;
+  }
+
+  return [...found.values()].sort((a, b) => a.depth - b.depth || Number(a.id) - Number(b.id));
+}
+
+// ancestorsOfTask — every task this one descends from, nearest first, each at
+// its shortest depth. This is what the payout (R09) walks.
+function ancestorsOfTask(taskId, opts = {}) {
+  return walk(taskId, 'up', opts);
+}
+
+// descendantsOfTask — the other direction, for the descent view (R10).
+function descendantsOfTask(taskId, opts = {}) {
+  return walk(taskId, 'down', opts);
+}
+
+// linkTaskDescent — record that `taskId` came out of `parentTaskId`.
+//
+// Idempotent on the pair, because the derivation below runs on every ship and
+// may legitimately see the same signal twice.
+async function linkTaskDescent(taskId, parentTaskId, relation, { client = null } = {}) {
+  const child = Number(taskId);
+  const parent = Number(parentTaskId);
+  if (!Number.isInteger(child) || !Number.isInteger(parent) || child <= 0 || parent <= 0) {
+    throw { code: 'DESCENT_BAD_ID', task_id: taskId, parent_task_id: parentTaskId };
+  }
+  if (child === parent) {
+    throw { code: 'DESCENT_SELF_EDGE', task_id: child };
+  }
+  // Validated here as well as by the DB CHECK. The constraint is the guarantee;
+  // this is the error message — a rejected enum should name the caller's bad
+  // value, not surface as a constraint violation from three frames down.
+  if (!DESCENT_RELATIONS.includes(relation)) {
+    throw { code: 'DESCENT_BAD_RELATION', relation, allowed: DESCENT_RELATIONS };
+  }
+  // Would this close a loop? It does if the proposed PARENT already DESCENDS
+  // from the child. Unbounded on purpose: walk() cannot revisit a node, so it
+  // always terminates, and a bound here would silently miss a cycle whose
+  // closing edge sits deeper than the bound — which is the one case that
+  // matters, because that cycle is the one that gets written.
+  const reachable = await descendantsOfTask(child, { client, maxDepth: Infinity });
+  if (reachable.some((r) => Number(r.id) === parent)) {
+    throw { code: 'DESCENT_CYCLE', task_id: child, parent_task_id: parent };
+  }
+  const q = client || pool;
+  await q.query(
+    `INSERT INTO ideas_task_descent (task_id, parent_task_id, relation)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (task_id, parent_task_id) DO UPDATE
+        SET relation = EXCLUDED.relation`,
+    [child, parent, relation]
+  );
+}
+
+// ── the derivation: three signals the system already has ────────────────────
+//
+// ADR 0312's finding was that three seams already know a task was derived and
+// none of them is telling anyone. This turns each into an edge.
+//
+// WHY IT IS PULLED FROM `tasks` HERE rather than written by the code that
+// causes it. A module may not import another module (ADR 0083, rule 1), so
+// modules/lifecycle/cascade.js cannot call into this file, and `tasks` is the
+// protected lifecycle module's table so this may not add a column to it. What
+// IS available is a read of `tasks` (the ideas_002 precedent — a FK, and a
+// SELECT, are reads) and the `task.shipped` event on the published doorway.
+// So the ideas module derives its own edges from facts already on the row,
+// reacting to the event. Nothing in lifecycle changes.
+const CASCADE_SOURCE_REF = /-(\d+)$/;
+
+async function deriveEdgesForTask(taskId, { client = null } = {}) {
+  const q = client || pool;
+  const id = Number(taskId);
+  if (!Number.isInteger(id) || id <= 0) return [];
+
+  const { rows } = await q.query(
+    `SELECT t.id, t.source, t.source_ref, t.parent_task_id,
+            (SELECT array_agg(m.id)
+               FROM tasks m
+              WHERE m.merged_into_task_id = t.id) AS folded_in
+       FROM tasks t
+      WHERE t.id = $1`,
+    [id]
+  );
+  const t = rows[0];
+  if (!t) return [];
+
+  const edges = [];
+
+  // 1. CASCADE — cascade.js writes `cascade-<key>-<originating id>` into
+  //    source_ref. The key itself contains dashes ('artist-review-on-ship'),
+  //    so the id is the trailing numeric run, not the third segment.
+  if (t.source === 'cascade' && typeof t.source_ref === 'string') {
+    const m = CASCADE_SOURCE_REF.exec(t.source_ref);
+    if (m) edges.push({ parent: Number(m[1]), relation: 'cascade' });
+  }
+
+  // 2. SPLIT — the one-level work decomposition. The hierarchy keeps owning
+  //    what the work is PART OF; this records that it CAME FROM it.
+  if (t.parent_task_id != null) {
+    edges.push({ parent: Number(t.parent_task_id), relation: 'split' });
+  }
+
+  // 3. FOLD — tasks abandoned INTO this one (core_232 constrains
+  //    merged_into_task_id to abandoned rows). The mockup's "satellite": work
+  //    that stopped being its own thing and now orbits this one.
+  for (const foldedId of t.folded_in || []) {
+    edges.push({ parent: Number(foldedId), relation: 'fold' });
+  }
+
+  return edges.filter((e) => Number.isInteger(e.parent) && e.parent > 0 && e.parent !== id);
+}
+
+// syncDescentForTask — derive and record, tolerantly.
+//
+// Returns what it wrote and what it skipped rather than throwing: this runs off
+// a ship event, and a provenance edge must never be able to break a ship. A
+// refused cycle is a normal outcome here, not an error.
+async function syncDescentForTask(taskId, { client = null } = {}) {
+  const edges = await deriveEdgesForTask(taskId, { client });
+  const written = [];
+  const skipped = [];
+  for (const e of edges) {
+    try {
+      await linkTaskDescent(taskId, e.parent, e.relation, { client });
+      written.push(e);
+    } catch (err) {
+      skipped.push({ ...e, code: (err && err.code) || 'UNKNOWN' });
+    }
+  }
+  return { written, skipped };
+}
+
+module.exports = {
+  DESCENT_MAX_DEPTH,
+  DESCENT_RELATIONS,
+  linkTaskDescent,
+  ancestorsOfTask,
+  descendantsOfTask,
+  deriveEdgesForTask,
+  syncDescentForTask,
+};

package/modules/ideas/migrations/ideas_007_task_descent_edges.sql

@@ -0,0 +1,111 @@
+-- ideas_007_task_descent_edges.sql — task→task provenance edges (task 1004086,
+-- BV2.R07, goal 1000095 "Working area 6"; ADR 0312).
+--
+-- WHY A SECOND TABLE AND NOT A COLUMN ON ideas_task_lineage. The spike (task
+-- 1004080) was told to confirm the lineage table rather than assume it, and
+-- confirmed one half while refuting the other. As the idea→task ANCHOR the
+-- table is right: it is bipartite, carries no depth cap and no version
+-- predicate, and so has none of the invariants that close the task hierarchy to
+-- this. But a derivation is a property of the TASK PAIR, not of the
+-- (task, idea) pair that ideas_006 made the key. Adding derived_from_task_id
+-- there would write the same derivation once per co-source idea — and
+-- co-source ideas are legal and EXPECTED since ideas_006 (merging duplicate
+-- reports into one task is the triage move the inbox exists to encourage) — so
+-- two rows for one task could disagree about where that task came from, with
+-- nothing to arbitrate. ideas_006 exists precisely because an under-keyed row
+-- silently lost attribution on prod and it took months to notice.
+--
+-- WHY NOT tasks.parent_task_id. modules/lifecycle/hierarchy.js caps parentage
+-- at ONE level and refuses cross-version trees (SELF_PARENT, VERSION_MISMATCH,
+-- PARENT_HAS_PARENT, TARGET_HAS_CHILDREN). A descent — idea → task → rewrite →
+-- split → removal — is four levels and crosses a version boundary. Both
+-- invariants are load-bearing for ship rollup and claim safety, and widening
+-- them is out of scope (spec decision 8). Provenance is a DIFFERENT RELATION
+-- from work decomposition: parent_task_id answers "what is this work part of",
+-- this table answers "where did this work come from". They are not redundant.
+--
+-- WHY IT LIVES HERE, NAMESPACED. `tasks` is the PROTECTED lifecycle module and
+-- a module migration may not ALTER a table outside its own namespace (ADR 0083
+-- §Decision #5, fitness Check 11). So this is an IDEAS-OWNED side table keyed by
+-- task ids — the same shape ideas_002 used for the same reason. FKs to existing
+-- tables are reads, not schema changes to them, so it stays inside the wall.
+--
+-- Module migrations are ADDITIVE and NAMESPACED: every object is ideas_-prefixed,
+-- no down-migration, idempotent (safe to re-run).
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS ideas_task_descent (
+  -- The DERIVED task — the one that came out of something else.
+  task_id          bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- What it came FROM. A task may have SEVERAL parents: a merge folds two
+  -- pieces of work into one, so this is a DAG, not a tree. That is why the key
+  -- is the pair rather than task_id alone — the ideas_006 lesson, applied up
+  -- front instead of after an incident.
+  parent_task_id   bigint NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+
+  -- HOW it was derived. Three of these are written from signals the system
+  -- ALREADY has and currently throws away (ADR 0312): 'cascade' from the
+  -- originating id that cascade.js encodes inside source_ref as a string
+  -- nothing can join on, 'fold' from tasks.merged_into_task_id, 'split' from
+  -- tasks.parent_task_id. Only 'rewrite' and cross-version 'merge' are
+  -- editorial acts with no automatic signal, so only those depend on someone
+  -- saying so — and their absence degrades the picture rather than corrupting
+  -- it. Widen this CHECK the ideas_003 way if a sixth relation ever appears.
+  relation         text NOT NULL
+                   CHECK (relation IN ('rewrite', 'split', 'merge', 'fold', 'cascade')),
+
+  created_at       timestamptz NOT NULL DEFAULT now(),
+
+  -- A task may hold at most one edge to a given parent; several parents are fine.
+  PRIMARY KEY (task_id, parent_task_id),
+
+  -- A SELF-EDGE IS AN INFINITE WALK, NOT A COSMETIC ERROR. The payout walks
+  -- this graph (R09) and the descent reads it (R10), so a cycle does not render
+  -- oddly — it fails to terminate. This CHECK refuses the one-node case in the
+  -- schema; longer cycles cannot be expressed as a row constraint and are
+  -- refused by the writer, which walks to the root before inserting.
+  CONSTRAINT ideas_task_descent_no_self_edge CHECK (task_id <> parent_task_id)
+);
+
+-- Two directions, two indexes, because both are hot and neither is served by
+-- the other. The DESCENT walks DOWN from an origin (children of a parent); the
+-- PAYOUT walks UP from a task that just shipped (its ancestors). The primary
+-- key's implicit index already covers the (task_id, …) direction, so only the
+-- parent side needs its own.
+CREATE INDEX IF NOT EXISTS idx_ideas_task_descent_parent
+  ON ideas_task_descent (parent_task_id);
+
+-- SAFETY NET — a migration that cannot prove its own effect must not report
+-- success (the ideas_003 / ideas_005 / ideas_006 precedent). Read-only, no DDL.
+-- If the table came back without the composite key, a task could hold two
+-- contradictory edges to the same parent; if it came back without the self-edge
+-- CHECK, the first bad write hangs the payout walk instead of being refused.
+DO $$
+DECLARE pk_cols text; has_self_check boolean;
+BEGIN
+  SELECT string_agg(a.attname, ',' ORDER BY a.attname) INTO pk_cols
+    FROM pg_constraint c
+    JOIN unnest(c.conkey) AS k(attnum) ON true
+    JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum
+   WHERE c.conrelid = 'ideas_task_descent'::regclass
+     AND c.contype  = 'p';
+  IF pk_cols IS DISTINCT FROM 'parent_task_id,task_id' THEN
+    RAISE EXCEPTION
+      'ideas_007: ideas_task_descent primary key is (%) — expected the composite (task_id, parent_task_id).', COALESCE(pk_cols, 'none');
+  END IF;
+
+  SELECT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conrelid = 'ideas_task_descent'::regclass
+       AND contype  = 'c'
+       AND conname  = 'ideas_task_descent_no_self_edge'
+  ) INTO has_self_check;
+  IF NOT has_self_check THEN
+    RAISE EXCEPTION
+      'ideas_007: the no-self-edge CHECK is missing — a self-edge would make the payout walk non-terminating.';
+  END IF;
+END $$;
+
+COMMIT;

package/modules/ideas/module.json

@@ -1,7 +1,7 @@
 {
   "key": "ideas",
   "title": "Ideas",
-  "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue \u2014 the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 \u00a71); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 \u00a75 \u2014 retiring the temporary `captureIdea` doorway leak).",
+  "description": "The idea inbox (capture, triage, criterion-proposal ratification) and the blockers queue — the methodology surfaces that feed the backlog. A core-domain module carved out of the GDS core in BV1.R78 (ADR 0093 §1); default-on because every instance captures ideas and tracks what's stuck on its owner. Registers the `ideas.capture` kernel PORT the discord #ideas inbound resolves (ADR 0093 §5 — retiring the temporary `captureIdea` doorway leak).",
   "coreVersion": "^1.8.0",
   "default": true,
   "maintenance": {
@@ -11,6 +11,9 @@
     "routes": [
       "inbox",
       "blockers"
+    ],
+    "pollers": [
+      "descent-writer"
     ]
   },
   "provides": [

package/modules/ideas/pollers/descent-writer.js

@@ -0,0 +1,69 @@
+// modules/ideas/pollers/descent-writer.js — the production writer for
+// task→task provenance edges (task 1004086, BV2.R07, goal 1000095; ADR 0312).
+//
+// WHY A POLLER AND NOT A CALL FROM THE CODE THAT CAUSES THE DERIVATION. The
+// three signals ADR 0312 identified all live on `tasks`, which belongs to the
+// protected `lifecycle` module, and a module may not import another module
+// (ADR 0083, rule 1: one doorway, one direction). So cascade.js cannot call
+// into `ideas`, and `ideas` cannot reach into lifecycle's code. The published
+// doorway's `task.shipped` event is the seam that legitimately joins them, and
+// the agents module already uses it for exactly this shape of reaction
+// (modules/agents/pollers/event-router.js).
+//
+// "Poller" here means "something the module runs in the web process", not
+// "something on a clock" — it owns no timer, and the same off→on replacement
+// idiom keeps a reloaded loader from accumulating duplicate listeners, which
+// would make every ship derive its edges twice.
+//
+// A PROVENANCE EDGE MUST NEVER BREAK A SHIP. The handler is deliberately
+// total: syncDescentForTask already returns its refusals rather than throwing
+// (a refused cycle is a normal outcome, not an error), and this wraps the whole
+// call anyway. The worst failure mode available to it is a missing edge, which
+// degrades the picture. The one it must not have is a thrown error on the ship
+// path — a reactor must never break the actor.
+
+const api = require('../../../src/module-api');
+const { syncDescentForTask } = require('../descent');
+
+const log = api.logger('ideas/descent-writer');
+const EVENT = 'task.shipped';
+
+let _off = null;
+
+// The event carries the TASK ROW, the same subject modules/agents receives.
+async function onShipped(task) {
+  const taskId = task && task.id;
+  if (taskId == null) return undefined;
+  try {
+    const { written, skipped } = await syncDescentForTask(taskId);
+    if (written.length > 0 || skipped.length > 0) {
+      log.info(
+        `ideas/descent-writer: task ${taskId} — ${written.length} edge(s) recorded`
+          + (skipped.length > 0 ? `, ${skipped.length} refused` : ''),
+      );
+    }
+  } catch (err) {
+    // A reactor must never break the actor.
+    log.error(`ideas/descent-writer: derivation threw for task ${taskId}: ${err && err.message}`);
+  }
+  return undefined;
+}
+
+function start() {
+  if (_off) return;
+  _off = api.on(EVENT, onShipped);
+  log.info(`[ideas/descent-writer] listening on ${EVENT} — deriving provenance edges from source_ref, parent_task_id and merged_into_task_id`);
+}
+
+function stop() {
+  if (_off) { try { _off(); } catch (_) { /* already gone */ } }
+  _off = null;
+}
+
+module.exports = {
+  start,
+  stop,
+  // Exported for tests: the handler is the whole reaction, and it needs no
+  // server to prove.
+  onShipped,
+};

package/package-lock.json

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

package/package.json

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

@@ -0,0 +1,340 @@
+// tests/idea_task_descent.mjs
+//
+// task 1004086 (BV2.R07, goal 1000095) — task→task descent edges. ADR 0312.
+//
+// WHAT IS ASSERTED HERE, AND WHY IT IS DB-FREE. The parts of this feature that
+// can go wrong silently are JavaScript, not SQL: the cycle refusal, the
+// breadth-first de-duplication, and the derivation that turns three existing
+// signals into edges. A cycle does not render oddly — the payout (R09) and the
+// descent (R10) both walk this graph, so a cycle fails to terminate. A merge
+// makes the graph a DAG rather than a tree, so a task reachable by two paths
+// must be counted ONCE at its SHORTEST depth, or the same origin is paid twice
+// for one descendant.
+//
+// The client is injected (every reader and writer takes { client }), so those
+// paths run for real against a recorded query log rather than being simulated.
+// A real-Postgres suite would SELF-SKIP on this machine, and a skipped test
+// prints ok and counts as passed — which is how a green lane hides what never
+// ran. The DDL half is therefore asserted as a SOURCE invariant instead.
+//
+// Run:  node tests/idea_task_descent.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const descent = require('../modules/ideas/descent.js');
+
+const MIGRATION = path.join(ROOT, 'modules/ideas/migrations/ideas_007_task_descent_edges.sql');
+const DDL = fs.readFileSync(MIGRATION, 'utf8');
+const MANIFEST = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/ideas/module.json'), 'utf8'));
+const WRITER_SRC = fs.readFileSync(path.join(ROOT, 'modules/ideas/pollers/descent-writer.js'), 'utf8');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed += 1; console.log('ok   ' + name); })
+    .catch((e) => { failed += 1; console.log('FAIL ' + name + '\n     ' + (e && (e.message || JSON.stringify(e)))); });
+}
+
+// A client that answers each query from a queue, recording what it was asked.
+function fakeClient(queue) {
+  const log = [];
+  return {
+    log,
+    query: async (text, params) => { log.push({ text, params }); return { rows: queue.shift() ?? [] }; },
+  };
+}
+
+// A client that answers the BFS from a real adjacency map, so the walk is
+// exercised as a walk rather than against canned rows.
+function graphClient(edges) {
+  // edges: [{ task_id, parent_task_id, relation }]
+  const log = [];
+  return {
+    log,
+    query: async (text, params) => {
+      log.push({ text, params });
+      if (!Array.isArray(params[0])) return { rows: [] };   // the INSERT, not a walk
+      const frontier = params[0].map(Number);
+      const up = /parent_task_id AS id/.test(text);
+      const rows = edges
+        .filter((e) => frontier.includes(Number(up ? e.task_id : e.parent_task_id)))
+        .map((e) => ({ id: up ? e.parent_task_id : e.task_id, relation: e.relation }));
+      return { rows };
+    },
+  };
+}
+
+// ── the migration ───────────────────────────────────────────────────────────
+
+await test('the migration declares the COMPOSITE key — one edge per (task, parent) pair', () => {
+  assert.match(DDL, /PRIMARY KEY \(task_id, parent_task_id\)/,
+    'the key must be the pair: a merge gives a task several parents');
+});
+
+await test('the migration refuses a SELF-EDGE in the schema', () => {
+  assert.match(DDL, /CHECK \(task_id <> parent_task_id\)/);
+  assert.match(DDL, /ideas_task_descent_no_self_edge/);
+});
+
+await test('the migration indexes the PARENT direction — the descent walk', () => {
+  assert.match(DDL, /CREATE INDEX IF NOT EXISTS idx_ideas_task_descent_parent/);
+});
+
+await test('the migration is additive and namespaced (ADR 0083 §5)', () => {
+  assert.doesNotMatch(DDL, /DROP TABLE|TRUNCATE|DROP COLUMN/i,
+    'a module migration may not carry destructive DDL');
+  for (const m of DDL.matchAll(/CREATE (?:TABLE|INDEX)(?: IF NOT EXISTS)? (\w+)/g)) {
+    assert.ok(m[1].startsWith('ideas_') || m[1].startsWith('idx_ideas_'),
+      `object ${m[1]} is outside the ideas_ namespace`);
+  }
+});
+
+await test('the migration proves its own effect — the safety net is present', () => {
+  assert.match(DDL, /RAISE EXCEPTION/,
+    'the ideas_003/005/006 precedent: a migration that cannot prove its effect must not report success');
+});
+
+// ── the writer ──────────────────────────────────────────────────────────────
+
+await test('a SELF-EDGE is refused before any query is issued', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(7, 7, 'rewrite', { client: c }),
+    (e) => e.code === 'DESCENT_SELF_EDGE'
+  );
+  assert.equal(c.log.length, 0, 'the self case must not reach the database at all');
+});
+
+await test('a LONGER CYCLE is refused — the walk would not terminate', async () => {
+  // 9 already descends from 5 (5 → 9), so making 5 descend from 9 closes a loop.
+  const c = graphClient([{ task_id: 9, parent_task_id: 5, relation: 'split' }]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 9, 'merge', { client: c }),
+    (e) => e.code === 'DESCENT_CYCLE'
+  );
+  assert.ok(
+    c.log.every((q) => !/INSERT/i.test(q.text)),
+    'the cycle must be refused BEFORE the row is written'
+  );
+});
+
+await test('a cycle DEEPER than the default bound is still refused', async () => {
+  // A chain 5 → 6 → … → 80, far past DESCENT_MAX_DEPTH (64). The closing edge
+  // is the one that matters, because it is the one that would get written.
+  const chain = [];
+  for (let i = 5; i < 80; i += 1) chain.push({ task_id: i + 1, parent_task_id: i, relation: 'split' });
+  const c = graphClient(chain);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 80, 'merge', { client: c }),
+    (e) => e.code === 'DESCENT_CYCLE'
+  );
+});
+
+await test('an unknown relation is refused by NAME, not by a constraint violation', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent(5, 9, 'inspired-by', { client: c }),
+    (e) => e.code === 'DESCENT_BAD_RELATION' && e.allowed.includes('cascade')
+  );
+  assert.equal(c.log.length, 0);
+});
+
+await test('a legitimate edge IS written, and upserts on the pair', async () => {
+  const c = graphClient([]);
+  await descent.linkTaskDescent(5, 9, 'split', { client: c });
+  const ins = c.log.find((q) => /INSERT INTO ideas_task_descent/i.test(q.text));
+  assert.ok(ins, 'the edge must be inserted');
+  assert.match(ins.text, /ON CONFLICT \(task_id, parent_task_id\) DO UPDATE/,
+    'the derivation runs on every ship, so the write must be idempotent');
+  assert.deepEqual(ins.params, [5, 9, 'split']);
+});
+
+await test('a non-numeric id is refused rather than passed to SQL', async () => {
+  const c = fakeClient([]);
+  await assert.rejects(
+    () => descent.linkTaskDescent('abc', 9, 'split', { client: c }),
+    (e) => e.code === 'DESCENT_BAD_ID'
+  );
+  assert.equal(c.log.length, 0);
+});
+
+// ── the walk ────────────────────────────────────────────────────────────────
+
+await test('a task reachable TWICE is returned ONCE, at its SHORTEST depth', async () => {
+  // The DAG a merge produces: 1 → 2 → 4 and 1 → 3 → 4, plus the short edge
+  // 1 → 4. Node 4 is reachable at depth 1 and depth 2; the payout must decay by
+  // the shorter one, and must not pay twice.
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 3, parent_task_id: 1, relation: 'split' },
+    { task_id: 4, parent_task_id: 2, relation: 'merge' },
+    { task_id: 4, parent_task_id: 3, relation: 'merge' },
+    { task_id: 4, parent_task_id: 1, relation: 'cascade' },
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  const ids = got.map((r) => Number(r.id));
+  assert.deepEqual(ids, [2, 3, 4], 'each node once, nearest first');
+  assert.equal(got.find((r) => Number(r.id) === 4).depth, 1, 'shortest path wins');
+});
+
+await test('a node is EXPANDED at most once — the convergent DAG does not blow up', async () => {
+  // Same shape, one level deeper. A recursive CTE re-expands every path; this
+  // asserts the walk does not, by counting the queries it issues: one per
+  // LEVEL, never one per path.
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 3, parent_task_id: 1, relation: 'split' },
+    { task_id: 4, parent_task_id: 2, relation: 'merge' },
+    { task_id: 4, parent_task_id: 3, relation: 'merge' },
+    { task_id: 5, parent_task_id: 4, relation: 'split' },
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  assert.deepEqual(got.map((r) => Number(r.id)), [2, 3, 4, 5]);
+  // One query per LEVEL — {1}, {2,3}, {4}, {5} — with the last returning
+  // nothing and ending the walk. Four queries for a graph carrying several
+  // distinct paths through node 4: the count tracks DEPTH, not the number of
+  // paths, which is exactly what a recursive CTE cannot promise.
+  assert.equal(c.log.length, 4, `one query per level, got ${c.log.length}`);
+});
+
+await test('a CYCLE in the stored data cannot hang the walk', async () => {
+  const c = graphClient([
+    { task_id: 2, parent_task_id: 1, relation: 'split' },
+    { task_id: 1, parent_task_id: 2, relation: 'merge' },   // the loop
+  ]);
+  const got = await descent.descendantsOfTask(1, { client: c });
+  assert.deepEqual(got.map((r) => Number(r.id)), [2], 'the start is never revisited');
+});
+
+await test('both directions walk the same way', async () => {
+  const c = graphClient([
+    { task_id: 9, parent_task_id: 5, relation: 'split' },
+    { task_id: 12, parent_task_id: 9, relation: 'rewrite' },
+  ]);
+  const up = await descent.ancestorsOfTask(12, { client: c });
+  assert.deepEqual(up.map((r) => Number(r.id)), [9, 5]);
+  assert.deepEqual(up.map((r) => r.depth), [1, 2], 'depth is the hop count the payout decays by');
+});
+
+// ── the derivation ──────────────────────────────────────────────────────────
+
+await test('a CASCADE task derives its edge from the id inside source_ref', async () => {
+  // The key itself contains dashes, so the id is the trailing numeric run.
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-artist-review-on-ship-1003583',
+    parent_task_id: null, folded_in: null,
+  }]]);
+  const edges = await descent.deriveEdgesForTask(900, { client: c });
+  assert.deepEqual(edges, [{ parent: 1003583, relation: 'cascade' }]);
+});
+
+await test('a SPLIT derives from parent_task_id, and a FOLD from merged_into', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'manual', source_ref: null,
+    parent_task_id: 500, folded_in: [401, 402],
+  }]]);
+  const edges = await descent.deriveEdgesForTask(900, { client: c });
+  assert.deepEqual(edges, [
+    { parent: 500, relation: 'split' },
+    { parent: 401, relation: 'fold' },
+    { parent: 402, relation: 'fold' },
+  ]);
+});
+
+await test('a task with no derivation signal produces NO edges', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'manual', source_ref: null, parent_task_id: null, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('a source_ref that is not a cascade id yields nothing, not a NaN edge', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-some-key-with-no-id',
+    parent_task_id: null, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('a self-referential signal is filtered out before it is written', async () => {
+  const c = fakeClient([[{
+    id: 900, source: 'cascade', source_ref: 'cascade-k-900',
+    parent_task_id: 900, folded_in: null,
+  }]]);
+  assert.deepEqual(await descent.deriveEdgesForTask(900, { client: c }), []);
+});
+
+await test('syncDescentForTask REPORTS a refusal instead of throwing', async () => {
+  // A ship must never break because a provenance edge was refused.
+  const c = {
+    log: [],
+    query: async (text, params) => {
+      c.log.push({ text, params });
+      if (/FROM tasks t/.test(text)) {
+        return { rows: [{ id: 5, source: 'manual', source_ref: null, parent_task_id: 9, folded_in: null }] };
+      }
+      // The cycle probe: 9 already descends from 5.
+      if (/parent_task_id = ANY/.test(text)) return { rows: [{ id: 9, relation: 'split' }] };
+      return { rows: [] };
+    },
+  };
+  const res = await descent.syncDescentForTask(5, { client: c });
+  assert.equal(res.written.length, 0);
+  assert.equal(res.skipped.length, 1);
+  assert.equal(res.skipped[0].code, 'DESCENT_CYCLE');
+});
+
+// ── the production call path ────────────────────────────────────────────────
+
+await test('the module DECLARES the poller, or nothing ever runs it', () => {
+  assert.ok(MANIFEST.contributes.pollers?.includes('descent-writer'),
+    'a poller file with no manifest entry is a silent no-op (ADR 0289)');
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/ideas/pollers/descent-writer.js')),
+    'and a declared seam whose artifact is absent is the same no-op in reverse');
+});
+
+await test('the writer subscribes to task.shipped and cannot double-subscribe', () => {
+  assert.match(WRITER_SRC, /api\.on\('task\.shipped'|EVENT = 'task\.shipped'/);
+  assert.match(WRITER_SRC, /if \(_off\) return;/,
+    'a reloaded loader must not accumulate listeners and derive every ship twice');
+});
+
+await test('the writer uses APIs the doorway actually publishes', () => {
+  // The first cut guessed `api.log.child(...)`, which does not exist on
+  // src/module-api.js. The optional-chaining fallback meant it silently
+  // degraded to `console` instead of failing, so nothing caught it — the
+  // shape of bug a static read finds and a green suite does not.
+  const doorway = require(path.join(ROOT, "src/module-api.js"));
+  for (const m of WRITER_SRC.matchAll(/\bapi\.([A-Za-z_$][\w$]*)/g)) {
+    assert.ok(m[1] in doorway,
+      `the writer calls api.${m[1]}, which the published doorway does not export`);
+  }
+});
+
+await test('the writer reads the task id the way the event actually carries it', () => {
+  // task.shipped hands the subscriber the TASK ROW — the same subject
+  // modules/agents/pollers/event-router.js receives as `task`. Guarding
+  // against payload shapes that never occur reads as uncertainty about the
+  // contract.
+  assert.doesNotMatch(WRITER_SRC, /payload\.task_id|payload\.task\b/,
+    "speculative payload shapes: the event carries the task row");
+});
+await test('the handler swallows its own failure — a reactor must not break the actor', async () => {
+  const writer = require('../modules/ideas/pollers/descent-writer.js');
+  // No client injected, so syncDescentForTask reaches the real pool and throws.
+  // The handler must still resolve.
+  await writer.onShipped({ id: 999999999 });
+  await writer.onShipped({});          // no id at all
+  await writer.onShipped(null);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);