@bongos/core 1.19.897 → 1.19.898

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.897",
-  "core_contract": "1.19.897",
-  "source_commit": "bee6c40d5b1e4600a59cace9b3068cfb1626de0d",
+  "core_version": "1.19.898",
+  "core_contract": "1.19.898",
+  "source_commit": "83c5474eb902fdb151eafe46b8e71103ec8fddc3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T02:58:37.233Z",
+  "built_at": "2026-09-20T03:57:02.228Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 500,
+    "docs_redacted": 501,
     "agent_docs_stubbed": 26,
     "functional_verbatim": 2277,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2803,
-  "tree_sha256": "649ca49d792d2d5a87fa5ae51bad0373270f0551dc7d8f82929bfa9112592e21",
+  "file_count": 2804,
+  "tree_sha256": "81209f20e18badef8c7699d57df22d9f10d76dcb7cdb49f1f1e3bdcffdc1a8ce",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2049,10 +2049,15 @@
       "mode": "0000644",
       "sha256": "6046995188cef5e8652787eca38ccc6a69393f0985891764d6573f3379bbe6ab"
     },
+    {
+      "path": "docs/adr/0312-provenance-is-a-second-ideas-owned-edge-table.md",
+      "mode": "0000644",
+      "sha256": "be07bd84a0167bbadfd3569286a5a69da403336739a88fccb5a5b6231e225af6"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "16fdd3b239a9a161d70e3432c35705590d0103f798f2e5f00db53cffcbf5cb81"
+      "sha256": "85666c7a834c711519264da5f88e2ff1cc950fc1d9c6038d9d0251e9ba7c9db0"
     },
     {
       "path": "docs/api-reference.md",
@@ -2622,7 +2627,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "a14d4e32aa8cd8793cdc535db0aa0047d7381de2e95cd6dd629c15b3ba0089b5"
+      "sha256": "3549eff34b79f43215969e5f04c584ba107742c4c8404314105a1da6c356cfa6"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7732,12 +7737,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ea53354ce229c7ec74a1909c0d0153363ee9f18969b0916c6dc832e36d2e9e8f"
+      "sha256": "e7c6f92f244fabe2e8a57f1a74f196dab668c42884b5132aa41f10317b7b6640"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "6cec6fa876274d23ee1da877b77841482b5b2558ddebac5adad801535deffa0d"
+      "sha256": "f9d896d331e9ecea3db23ec5d58bcec8488e3dbc1c924a4a94d27dc10b1c3798"
     },
     {
       "path": "public-docs/index.html",
@@ -9747,7 +9752,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "dc291210b4d1b471b7e946fc451381204d9eece987e0d0df49f364e41a240594"
+      "sha256": "cfa865647882f01bac0dbf3f653f66544a05e283895b36a8d5906b32891e2302"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/adr/0312-provenance-is-a-second-ideas-owned-edge-table.md

@@ -0,0 +1,78 @@
+# ADR 0312 — Provenance is a second ideas-owned edge table, written by the seams that already know
+
+**Status:** accepted · **Date:** 2026-09-19 · **Task:** [task 1004080](https://cloudbongos.com/builders#/task/1004080) (goal 1000095 — BONGOS-V2)
+
+**Related:** [ADR 0311](0311-an-idea-is-a-permanent-origin-tag.md) (the origin tag this records the descent of) · [ADR 0236](0236-many-ideas-one-task-the-lineage-key-is-the-pair.md) (made co-source ideas real, which is why the edge cannot live on the lineage row) · [ADR 0083](0083-modular-architecture-strangler-build-plan.md) §Decision 5 (a module migration may only touch its own namespace) · [ADR 0054](0054-session-token-reward-cost-plus.md) (the credit the payout rides on) · [ADR 0015](0015-task-dependencies-and-auto-promotion.md)
+
+## Context
+
+A descent — `idea → task → rewrite → split → removal` — is four levels deep and crosses a version boundary. The obvious place to put it is the task hierarchy, and that place is closed.
+
+`modules/lifecycle/hierarchy.js` `attachParent` enforces four invariants, verified by reading the code rather than the comment:
+
+| Invariant | Error code |
+|---|---|
+| `target !== parent` | `SELF_PARENT` |
+| `target.version_id === parent.version_id` | `VERSION_MISMATCH` |
+| `parent.parent_task_id IS NULL` (depth cap, side 1) | `PARENT_HAS_PARENT` |
+| target has no children (depth cap, side 2) | `TARGET_HAS_CHILDREN` |
+
+All four are deliberate; ship rollup and claim safety lean on them, and spec decision 8 puts widening them out of scope. So provenance needs its own relation.
+
+**The spike was told to confirm `ideas_task_lineage` rather than assume it. Confirmed for one half, and refuted for the other.**
+
+## Decision
+
+**Two tables, not one.** `ideas_task_lineage` stays exactly as it is and anchors depth 0. A new ideas-owned table records task→task edges.
+
+### Why the edge cannot go on `ideas_task_lineage`
+
+The table is bipartite (ideas × tasks) with `PRIMARY KEY (task_id, idea_id)` since `ideas_006`. It carries none of the hierarchy's invariants — no depth cap, no version predicate, no self-reference hazard — so as the **idea→task anchor** it is right, and that half of the assumption holds.
+
+But a derivation is a property of the **task pair**, not of the (task, idea) pair. Adding `derived_from_task_id` to the lineage row would write the same derivation once per co-source idea, and `ideas_006` made co-source ideas both legal and expected (merging duplicate reports into one task is the triage move the inbox is built to encourage). Two rows for one task could then disagree about where that task came from, with nothing to arbitrate. That is not a hypothetical: `ideas_006` exists precisely because an under-keyed row silently lost attribution on prod, and it took months to notice.
+
+A merge also gives a task **several** parents, so the relation is a DAG, not a tree — a single nullable column could not express it regardless.
+
+### The edge table
+
+`ideas_task_descent`, in the `ideas_` namespace (ADR 0083 §5 — `tasks` belongs to the protected `lifecycle` module and may not be altered from here; a FK to it is a read, the `ideas_002` precedent).
+
+- `task_id` → the derived task, `parent_task_id` → what it came from, both FK to `tasks`.
+- `relation` — a CHECK'd vocabulary: `rewrite`, `split`, `merge`, `fold`, `cascade`. Extended the `ideas_003` way (drop and re-add the same-named constraint, which `isConstraintWidening` exempts), with that migration's safety net proving the widening took.
+- `PRIMARY KEY (task_id, parent_task_id)` — a task may have several parents; one pair is recorded once.
+- Indexed both directions: descent walks down from a parent, payout walks up from a ship.
+
+**No depth cap and no version predicate** — that is the entire point, and it is what the hierarchy could not give.
+
+**Cycles must be refused at write time.** The payout walks this graph, so a cycle is a non-terminating walk, not a cosmetic error. A self-edge is refused by CHECK; a longer cycle is refused by the writer, which walks to the root before inserting. The walk is also depth-bounded when read, so a cycle that somehow lands cannot hang a page.
+
+### Who writes the edge
+
+The task set the real question: parentage today is a manual act, so an edge that depends on someone remembering will have holes. It does not have to. **Three seams already know a task was derived, and none of them is currently telling anyone:**
+
+| Seam | What it already records | What it becomes |
+|---|---|---|
+| `modules/lifecycle/cascade.js` | `source_ref: cascade-<key>-<id>` — the originating task id, **encoded in a string** | `relation='cascade'`, written at creation |
+| `tasks.merged_into_task_id` | supersede/fold provenance, CHECK'd to `abandoned` rows (`core_232`) | `relation='fold'` — the mockup's "satellite" |
+| `tasks.parent_task_id` | the one-level split | `relation='split'` |
+
+The cascade case is the telling one. The derivation is *already there* and already correct — it is simply stored as text inside `source_ref`, where nothing can join on it. Promoting it to an edge is not new bookkeeping, it is writing down a fact the system already computes.
+
+That leaves `rewrite` and cross-version `merge` as genuinely manual, which is honest: those are editorial acts with no automatic signal behind them. They get an explicit write, and their absence degrades the picture rather than corrupting it.
+
+## Consequences
+
+**What this fixes.** `sourceIdeaForTask` (`inbox.js:870`) and `awardIdeaTaskShipCredit` (`credits.js:540`) both read `ideas_task_lineage` with `ORDER BY created_at, idea_id LIMIT 1` — a **direct, one-hop point read**. A derived task has no lineage row of its own, so today it resolves to `no_source_idea` and the origin idea is not paid at all. The descent walk is what closes that, and spec decision 6's depth decay is what keeps it from paying unboundedly.
+
+**Two relations over the same pair of tasks now exist** — `parent_task_id` (work decomposition, capped, same-version) and this one (provenance, unbounded, cross-version). They are not redundant and must not be merged: the first answers "what is this work part of", the second "where did this work come from". The split edge is written to both, which is the only overlap.
+
+**The display is wider than the count.** Per spec decision 7 the descent *shows* more than size *counts* — a separate thought citing an origin appears in the picture and pays nothing. The edge table carries both; the payout walk filters. Conflating them would let early filers farm the project.
+
+**A backfill is possible and partial.** Every existing cascade task can be recovered by parsing `source_ref`, and every `merged_into_task_id` is already an edge. Historical rewrites are unrecoverable, which is consistent with spec decision 17: pre-existing ideas get lineage backfilled but not payouts, and the number must be marked as historical rather than quietly presented as a sum of payouts made.
+
+## Alternatives rejected
+
+- **Widen the task hierarchy.** Out of scope by spec decision 8, and the invariants are load-bearing for ship rollup and claim safety.
+- **`derived_from_task_id` on `ideas_task_lineage`.** Duplicates the derivation per co-source idea and cannot express a merge. The reason it looks attractive — "extend, don't add" — is real, and the extension is of the lineage *ledger*, which is now two tables.
+- **A column on `tasks`.** Forbidden from a module migration (ADR 0083 §5); `tasks` is the protected `lifecycle` module.
+- **Derive the descent at read time from `source_ref` strings.** It covers only the cascade case, cannot express rewrite or merge, and makes a string format load-bearing for money.

package/docs/adr/README.md

@@ -403,3 +403,4 @@ This keeps the decision history honest and traceable.
 | 0309 | [**Module enablement is a database row, above the committed pack and below env** ([task 1002857](https://cloudbongos.com/builders#/task/1002857), goal 1000091). The hall Modules-tab toggle ([ADR 0107](0107-module-upstreaming-contribution-to-core-catalog.md) §9) wrote `config/modules.json` and reloaded the cache, so it looked like it worked — but that file is the committed instance pack and the pull-deploy runs `git reset --hard origin/main`, so the toggle reverted on the next deploy, **silently**. Enablement moves to `module_enablement_overrides` (migration `core_248`), read as one precedence layer: neutral pack → instance pack → **DB override** → env → default. **Above the pack** because the pack is what a deploy restores, so an override below it would be erased by the event it exists to survive; **below env** because `<PREFIX>_MODULE_<KEY>` is the incident knob and must not need a reachable database. **Auto-committing to `main` stays rejected** ([ADR 0016](<redacted>.md)): durability belongs in the DB, not in an HTTP handler that writes to the default branch. Two open design points settled: the **scope key** is the resolved instance pack path (the only axis two instances sharing one database differ on, so one sibling's toggle cannot flip the other's module), and the DB is read into a **snapshot** refreshed at boot and on write rather than inline, because `loadModules()` is synchronous and making it async would ripple into every consumer of a module flag. An unreachable database is a **no-op** — no row means "no opinion", not "off". Does not decide: whether a toggle should also restart the process so remounting is immediate.](0309-durable-module-enablement-db-override.md) | modules / ops |
 | 0310 | [**A speciality OFFERS skills; the adopter turns them on, one at a time, having been shown what each does** ([task 1003978](https://cloudbongos.com/builders#/task/1003978), goal 1000095). Completes [ADR 0296](0296-a-role-speciality-is-data-over-three-existing-surfaces.md), which defined a speciality as knowledge + skills + an interaction contract and shipped two of the three: `grep -i skill` across the module's schema, domain and routes returns only the header sentences describing a thing that is not there — prose asserting behaviour the code does not have, and the feature's own definition at that. Task 1003978 withheld an implementation until the authority question was answered, and the answer is the strong one: **naming a skill GRANTS NOTHING**. Skills are materialised by `claude-materialize.js` and permission is rank-gated server-side with no caching ([ADR 0016](<redacted>.md)); a speciality offers a menu, and a menu is not an entitlement. **Two layers, because one layer is the blanket the owner ruled against**: the catalog holds what a speciality OFFERS, the already-per-builder `specialities_adoptions` row holds what THIS builder turned on — so two economist ideators share a speciality's knowledge and contract and need not share one enabled skill. **The default is nothing enabled, and that is a position about LEARNING rather than a safe default**: the owner's ruling is that adoption must *walk through what comes with each* because *people need to learn the system*. A settings page of unchecked boxes satisfies the letter and defeats the intent, so the bar is a user test — a person who has finished adopting can say what each skill does. Sharing needs no new mechanism: `owner_kind` / `visibility` / `offered` / `sellable` already ship the private→project→public ladder, and skills ride it. Builds nothing; the three-task order (schema, walkthrough, injection) is filed, and the four documentation sites that claimed a shipped ingredient now say decided-not-built.](0310-a-speciality-offers-skills-and-the-adopter-chooses-them.md) | specialities / methodology |
 | 0311 | [**An idea is a permanent origin tag, and the payout follows its descent** ([task 1004076](https://cloudbongos.com/builders#/task/1004076), goal 1000095 — BONGOS-V2). An idea today is a CONTAINER for work: it leaves `idea_inbox` when it names a goal and lives on as a task, so the better-aimed the thought the faster it vanishes from whoever had it. Reported as a small confusion — a thought filed from the hall routed into a goal, the confirmation line cleared on the next keystroke, and five minutes later the owner could not find it. The idea becomes an **immutable origin tag** instead, the only thing that can answer where a piece of work came from, and **the ideator payout follows its whole descent** rather than stopping at the earliest lineage link (`awardIdeaTaskShipCredit`), decaying by depth — full at the direct task, halving each hop — so an infinite descent is worth at most twice the direct task. That is what gives the tag teeth: if it does not survive a fork, someone does not get paid. **Size and brightness are two channels, not one number**: size is the sum of those payouts and never falls, brightness is how much of that work is still alive, so a thought whose work the project tore out renders LARGE AND DEAD rather than looking like one that never mattered. **Karma was rejected as the basis** — `karma_log` carries no task key and no idea key, deliberately ([`migrations/040_builder_karma.sql`](../../migrations/040_builder_karma.sql)), so "the karma a thought caused" is not computable; credits already are idea-attributed. **The task hierarchy is NOT widened** to carry the descent — it is capped at one level and refuses cross-version parents because ship rollup and claim safety lean on it, and provenance is a different relation from work decomposition. **Nothing records that shipped work was later removed** (`shipped` is terminal, `merged_into_task_id` is CHECK-constrained to abandoned rows), so the first `cascade.js` rule PROPOSES a removal and a person confirms it — derived-only would dim for refactors and renames, declared-only would rot. A ratified **Full Idea becomes a goal or a criterion**, carrying a recommendation the board rules on, because scope is the thing you learn last; the five questions are replaced and VERSIONED so prior filings keep their own. Dropped three tasks this invalidated and amended a fourth whose title asserted the exact exclusivity it reverses. Does not decide: the decay rate beyond its default, what precisely counts as removed, how the edges are physically recorded, or how any of it is drawn.](0311-an-idea-is-a-permanent-origin-tag.md) | ideas / economy |
+| 0312 | [**Provenance is a SECOND ideas-owned edge table, written by the seams that already know** ([task 1004080](https://cloudbongos.com/builders#/task/1004080), goal 1000095 — BONGOS-V2). The spike [ADR 0311](0311-an-idea-is-a-permanent-origin-tag.md) deferred: how the descent edges are physically recorded. A descent (`idea → task → rewrite → split → removal`) is four levels deep and crosses a version boundary, and the task hierarchy refuses both — `attachParent` enforces `SELF_PARENT`, `VERSION_MISMATCH`, `PARENT_HAS_PARENT` and `TARGET_HAS_CHILDREN`, all load-bearing for ship rollup and claim safety. The spike was told to CONFIRM `ideas_task_lineage` rather than assume it, and confirmed one half while refuting the other: the table is right as the **idea→task anchor** (bipartite, no depth cap, no version predicate) but CANNOT carry the task→task edge, because a derivation is a property of the task PAIR and [ADR 0236](0236-many-ideas-one-task-the-lineage-key-is-the-pair.md) made co-source ideas both legal and common — a `derived_from_task_id` column would write the same derivation once per co-source idea and let two rows disagree about where a task came from, the same under-keying that silently lost attribution on prod once already. A merge also gives a task SEVERAL parents, so the relation is a **DAG, not a tree**. Decision: a new `ideas_task_descent` (`task_id`, `parent_task_id`, CHECK'd `relation`, PK on the pair, indexed both ways), with NO depth cap and NO version predicate, and **cycles refused at write time** because the payout walks this graph and a cycle is a non-terminating walk rather than a cosmetic error. On who writes it — the question the task actually set, since an edge depending on memory will have holes — **three seams already know and none is telling anyone**: `cascade.js` encodes the originating task id inside `source_ref` as a STRING nothing can join on, `tasks.merged_into_task_id` already records the fold, and `parent_task_id` already records the split. Only `rewrite` and cross-version `merge` stay manual, which is honest — they are editorial acts with no automatic signal, and their absence degrades the picture rather than corrupting it. What it fixes: `sourceIdeaForTask` and `awardIdeaTaskShipCredit` are both one-hop `LIMIT 1` point reads, so a DERIVED task resolves to `no_source_idea` and the origin is not paid at all. Does not decide: the decay rate beyond its default, what counts as removed ([task 1004081](https://cloudbongos.com/builders#/task/1004081)), or how any of it is drawn.](0312-provenance-is-a-second-ideas-owned-edge-table.md) | ideas / lifecycle |

package/docs/module-api-changelog.md

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

package/package-lock.json

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

package/package.json

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