@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/lib/workflow/local-chain-recommender.cjs

@@ -0,0 +1,330 @@
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 172-10 Task 3 -- the LOCAL-projection chain recommender (Canon Part 11
+ * R6 / INV-08 / INV-12).
+ *
+ * WHAT: ranks chain candidates (FEEDS_INTO / CHAINS / PREREQUISITE edges) off the
+ * LOCAL orchestration projection (data/brain-orchestration-projection.json),
+ * joined to the curated per-edge confidence in data/command-registry.json
+ * curated_chains. suggest-next reaches for this to surface USEFUL next-step
+ * frameworks with EARNED confidence.
+ *
+ * recommendChainCandidates() ranks SINGLE-edge candidates. recommendMultiHopChains()
+ * (Plan 172-15) composes MULTI-HOP chain confidence MULTIPLICATIVELY along a path
+ * (the SPFO verified Brain model: reduce(c=1.0, r | c * coalesce(r.confidence, 0.5)),
+ * ordered by hops then composed-confidence DESC), carrying the per-hop `transform`
+ * descriptors, so the Brain-OFF ranker mirrors the Brain-ON model exactly
+ * (research/172-SPFO-CHAIN-MODEL-REFERENCE.md, Canon Part 11 R6 / INV-08 / INV-12).
+ *
+ * LOCAL-ONLY (INV-12 / R7): the recommender reads ONLY committed local files
+ * (the projection + the registry) -- it makes ZERO Brain/network calls at rank
+ * time. There is no brain-client require, no fetch, no http. The projection is a
+ * Brain-DERIVED LOCAL cache (Canon Part 8 dual-role amendment); reading it opens
+ * no wire.
+ *
+ * R6 ranking-deferral (Canon Part 11): the recommender SUPPLIES the curated
+ * confidence and produces a confidence-ranked candidate set; the final surfaced
+ * ORDERING of the eligible set is the Part-3 MAX_K ranker's job
+ * (lib/workflow/f-selector-ranker.cjs rankForSelector). This module therefore
+ * RE-EXPORTS the Part-3 MAX_K cap (never mints its own) and does NOT duplicate
+ * rankForSelector -- CIRS supplies confidence, Part 3 orders.
+ *
+ * Part 8: the projection + curated_chains carry ONLY generic machinery metadata
+ * (framework-name pairs + a scalar confidence); no user content is read or
+ * emitted.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The Part-3 MAX_K surfaced-set budget. Re-exported (never re-minted) so the
+// recommender defers to the ranker's row-budget cap (R6 ranking-deferral).
+const { MAX_K } = require('./f-selector-ranker.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PROJECTION_PATH = path.join(REPO_ROOT, 'data', 'brain-orchestration-projection.json');
+const REGISTRY_PATH = path.join(REPO_ROOT, 'data', 'command-registry.json');
+
+// The closed chain-edge set in the projection (the curated_chains kinds). OPERATES
+// and CROSS_DOMAIN_ANALOGUE are NOT chain candidates.
+const CHAIN_EDGE_TYPES = Object.freeze({
+  FEEDS_INTO: 'feeds_into',
+  CHAINS: 'chain',
+  PREREQUISITE: 'prerequisite',
+});
+
+// ---------------------------------------------------------------------------
+// _readJsonLocal(p) -- read a committed LOCAL JSON file. Returns null on any
+// failure so the recommender degrades (Tier-0 cold start) rather than throwing.
+// Zero network (Part 8 / INV-12).
+// ---------------------------------------------------------------------------
+function _readJsonLocal(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_e) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// _stripFrameworkPrefix(nodeId) -- the projection edge endpoints are node ids
+// like 'framework:S-Curve Analysis' or 'reach:brain_consult'. The curated_chains
+// from/to are the bare framework name / reach id. Strip the kind prefix so the
+// edge can join to its curated confidence entry. Returns { kind, name }.
+// ---------------------------------------------------------------------------
+function _splitNodeId(nodeId) {
+  if (typeof nodeId !== 'string') return { kind: null, name: null };
+  const idx = nodeId.indexOf(':');
+  if (idx < 0) return { kind: null, name: nodeId };
+  return { kind: nodeId.slice(0, idx), name: nodeId.slice(idx + 1) };
+}
+
+// ---------------------------------------------------------------------------
+// _buildConfidenceIndex(curatedChains) -- index curated confidence by
+// (kind, from, to) so a projection chain edge resolves its earned confidence.
+// Key is `${kind}\n${from}\n${to}` (newline-joined: framework names contain
+// spaces but never newlines, so the delimiter is collision-safe).
+// ---------------------------------------------------------------------------
+function _buildConfidenceIndex(curatedChains) {
+  const index = new Map();
+  const list = Array.isArray(curatedChains) ? curatedChains : [];
+  for (const c of list) {
+    if (!c || typeof c !== 'object') continue;
+    if (typeof c.kind !== 'string') continue;
+    if (typeof c.from !== 'string' || typeof c.to !== 'string') continue;
+    const key = c.kind + '\n' + c.from + '\n' + c.to;
+    index.set(key, typeof c.confidence === 'number' ? c.confidence : null);
+  }
+  return index;
+}
+
+// ---------------------------------------------------------------------------
+// recommendChainCandidates(args) -- the rank surface.
+//
+//   args.projection     optional in-memory projection ({ nodes, edges }); when
+//                       absent the committed LOCAL projection file is read.
+//   args.curatedChains  optional in-memory curated_chains array; when absent the
+//                       committed LOCAL command-registry curated_chains is read.
+//   args.k              optional surfaced-set budget; clamped at MAX_K (R6
+//                       ranking-deferral -- the Part-3 row budget). When absent,
+//                       the full confidence-ranked candidate set is returned.
+//
+// Returns an array of chain candidates { kind, from, to, confidence }, ranked by
+// curated confidence DESCENDING. ONLY chain-kind edges (FEEDS_INTO / CHAINS /
+// PREREQUISITE) are candidates; OPERATES / CROSS_DOMAIN_ANALOGUE are ignored. An
+// edge with no curated-confidence join is dropped (a chain candidate must carry
+// EARNED confidence -- never a fabricated default, per R6). Local-Only: zero
+// Brain/network at rank time (INV-12).
+// ---------------------------------------------------------------------------
+function recommendChainCandidates(args) {
+  const o = (args && typeof args === 'object') ? args : {};
+
+  const projection = (o.projection && typeof o.projection === 'object')
+    ? o.projection
+    : _readJsonLocal(PROJECTION_PATH);
+  if (!projection || !Array.isArray(projection.edges)) return [];
+
+  let curatedChains = o.curatedChains;
+  if (!Array.isArray(curatedChains)) {
+    const reg = _readJsonLocal(REGISTRY_PATH);
+    curatedChains = reg && Array.isArray(reg.curated_chains) ? reg.curated_chains : [];
+  }
+  const confIndex = _buildConfidenceIndex(curatedChains);
+
+  const candidates = [];
+  for (const e of projection.edges) {
+    if (!e || typeof e !== 'object') continue;
+    const kind = CHAIN_EDGE_TYPES[e.type];
+    if (!kind) continue; // not a chain-kind edge -> not a candidate
+
+    const fromName = _splitNodeId(e.from).name;
+    const toName = _splitNodeId(e.to).name;
+    if (!fromName || !toName) continue;
+
+    const key = kind + '\n' + fromName + '\n' + toName;
+    const confidence = confIndex.has(key) ? confIndex.get(key) : null;
+    // R6: a chain candidate must carry EARNED confidence; drop an edge with no
+    // curated join rather than fabricate a uniform default.
+    if (typeof confidence !== 'number') continue;
+
+    candidates.push({ kind, from: fromName, to: toName, confidence });
+  }
+
+  // CIRS supplies confidence: rank candidates by curated confidence descending.
+  // Stable secondary sort on from/to for byte-deterministic output across runs.
+  candidates.sort((a, b) => {
+    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+    if (a.from !== b.from) return a.from < b.from ? -1 : 1;
+    return a.to < b.to ? -1 : (a.to > b.to ? 1 : 0);
+  });
+
+  // R6 ranking-deferral: clamp the surfaced view at the Part-3 MAX_K budget when
+  // a budget is requested. The FINAL ordering of the eligible set is the Part-3
+  // ranker's job; this is only the row-budget cap, not a competing ranker.
+  if (typeof o.k === 'number' && o.k > 0) {
+    const k = Math.min(Math.floor(o.k), MAX_K);
+    return candidates.slice(0, k);
+  }
+  return candidates;
+}
+
+// The SPFO coalesce default for a missing per-edge confidence (the verified Brain
+// model: `coalesce(r.confidence, 0.5)`). research/172-SPFO-CHAIN-MODEL-REFERENCE.md.
+const COALESCE_CONFIDENCE = 0.5;
+
+// ---------------------------------------------------------------------------
+// _buildChainAdjacency(projection, confIndex) -- index the projection's chain-kind
+// edges (FEEDS_INTO / CHAINS / PREREQUISITE) as an adjacency map keyed on the
+// source framework name. Each adjacency record carries { to, kind, confidence,
+// transform } where confidence/transform come FIRST from the edge itself (Task 1
+// materializes {confidence, transform} onto the projection edge) and FALL BACK to
+// the curated_chains join (confIndex) when the edge lacks them. A missing
+// confidence is left undefined here; the composition coalesces it to 0.5.
+// ---------------------------------------------------------------------------
+function _buildChainAdjacency(projection, confIndex) {
+  const adj = new Map();
+  if (!projection || !Array.isArray(projection.edges)) return adj;
+  for (const e of projection.edges) {
+    if (!e || typeof e !== 'object') continue;
+    const kind = CHAIN_EDGE_TYPES[e.type];
+    if (!kind) continue; // not a chain-kind edge
+
+    const fromName = _splitNodeId(e.from).name;
+    const toName = _splitNodeId(e.to).name;
+    if (!fromName || !toName) continue;
+
+    // Confidence + transform: prefer the edge's own (Task 1), else the curated join.
+    const key = kind + '\n' + fromName + '\n' + toName;
+    const joined = confIndex && confIndex.has(key) ? confIndex.get(key) : null;
+    let confidence;
+    if (typeof e.confidence === 'number') confidence = e.confidence;
+    else if (typeof joined === 'number') confidence = joined;
+    // else: undefined -> coalesced to COALESCE_CONFIDENCE at composition time.
+
+    let transform = null;
+    if (typeof e.transform === 'string' && e.transform) transform = e.transform;
+
+    if (!adj.has(fromName)) adj.set(fromName, []);
+    adj.get(fromName).push({ to: toName, kind, confidence, transform });
+  }
+  return adj;
+}
+
+// ---------------------------------------------------------------------------
+// recommendMultiHopChains(args) -- the MULTI-HOP composition surface (Plan 172-15,
+// Canon Part 11 R6 / INV-08).
+//
+//   args.from        REQUIRED -- the seed framework name to walk chains FROM.
+//   args.maxHops     optional hop ceiling (default 3); each hop is one chain edge.
+//   args.projection  optional in-memory projection; else the committed LOCAL file.
+//   args.curatedChains optional in-memory curated_chains; else the committed LOCAL
+//                    command-registry curated_chains (the confidence/transform
+//                    fallback when an edge lacks them).
+//   args.k           optional surfaced-set budget; clamped at the Part-3 MAX_K
+//                    (R6 ranking-deferral). When absent, the full set is returned.
+//
+// Walks every acyclic chain path of 1..maxHops hops starting at `from`, composing
+// confidence MULTIPLICATIVELY along the path with the SPFO reduce formula:
+//   reduce(c = 1.0, r IN rels | c * coalesce(r.confidence, COALESCE_CONFIDENCE))
+// Each candidate is { from, path, hops, confidence, transforms, kinds } where
+// `path` is the framework-name sequence (length hops+1), `transforms` is the
+// per-hop transform descriptor array (length hops; a hop with no transform is
+// positionally null, never dropped), and `kinds` is the per-hop edge-kind array.
+// Candidates are ordered by hops ASC then composed-confidence DESC (the SPFO
+// ordering). Local-Only (INV-12): reads only the committed projection + registry
+// (or the in-memory fixtures); ZERO Brain/network at rank time. The FINAL surfaced
+// ordering of the eligible set still defers to the Part-3 MAX_K ranker (R6); this
+// supplies the composed confidence + a clamped surfaced view, never a competing
+// ranker.
+// ---------------------------------------------------------------------------
+function recommendMultiHopChains(args) {
+  const o = (args && typeof args === 'object') ? args : {};
+  const seed = typeof o.from === 'string' ? o.from : null;
+  if (!seed) return [];
+
+  const maxHops = (typeof o.maxHops === 'number' && o.maxHops > 0)
+    ? Math.floor(o.maxHops)
+    : 3;
+
+  const projection = (o.projection && typeof o.projection === 'object')
+    ? o.projection
+    : _readJsonLocal(PROJECTION_PATH);
+  if (!projection || !Array.isArray(projection.edges)) return [];
+
+  let curatedChains = o.curatedChains;
+  if (!Array.isArray(curatedChains)) {
+    const reg = _readJsonLocal(REGISTRY_PATH);
+    curatedChains = reg && Array.isArray(reg.curated_chains) ? reg.curated_chains : [];
+  }
+  const confIndex = _buildConfidenceIndex(curatedChains);
+
+  const adj = _buildChainAdjacency(projection, confIndex);
+
+  const candidates = [];
+
+  // Depth-first acyclic walk. `path` is the framework-name sequence; `transforms`
+  // / `kinds` are the per-hop arrays; `conf` is the running multiplicative product
+  // (the SPFO reduce accumulator, seeded at 1.0). `visited` guards cycles.
+  function walk(node, path, transforms, kinds, conf, visited) {
+    const neighbors = adj.get(node) || [];
+    for (const rec of neighbors) {
+      if (visited.has(rec.to)) continue; // acyclic: never revisit a node on this path
+      const c = typeof rec.confidence === 'number' ? rec.confidence : COALESCE_CONFIDENCE;
+      const nextConf = conf * c;
+      const nextPath = path.concat(rec.to);
+      const nextTransforms = transforms.concat(typeof rec.transform === 'string' ? rec.transform : null);
+      const nextKinds = kinds.concat(rec.kind);
+      const hops = nextPath.length - 1;
+
+      // Emit this path as a candidate (every 1..maxHops path is surfaced).
+      candidates.push({
+        from: seed,
+        path: nextPath,
+        hops,
+        confidence: nextConf,
+        transforms: nextTransforms,
+        kinds: nextKinds,
+      });
+
+      if (hops < maxHops) {
+        const nextVisited = new Set(visited);
+        nextVisited.add(rec.to);
+        walk(rec.to, nextPath, nextTransforms, nextKinds, nextConf, nextVisited);
+      }
+    }
+  }
+
+  walk(seed, [seed], [], [], 1.0, new Set([seed]));
+
+  // SPFO ordering: hops ASC, then composed-confidence DESC. Stable tertiary sort
+  // on the path string for byte-deterministic output across runs.
+  candidates.sort((a, b) => {
+    if (a.hops !== b.hops) return a.hops - b.hops;
+    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+    const pa = a.path.join('>');
+    const pb = b.path.join('>');
+    return pa < pb ? -1 : (pa > pb ? 1 : 0);
+  });
+
+  // R6 ranking-deferral: clamp the surfaced view at the Part-3 MAX_K budget when a
+  // budget is requested. The FINAL ordering of the eligible set is the Part-3
+  // ranker's job; this is only the row-budget cap.
+  if (typeof o.k === 'number' && o.k > 0) {
+    const k = Math.min(Math.floor(o.k), MAX_K);
+    return candidates.slice(0, k);
+  }
+  return candidates;
+}
+
+module.exports = {
+  recommendChainCandidates,
+  recommendMultiHopChains,
+  // R6 ranking-deferral: re-export the Part-3 MAX_K cap so consumers (and the
+  // ranking test) can prove the recommender defers to the ranker's row budget
+  // rather than minting its own. rankForSelector is intentionally NOT exported
+  // here -- ordering the final surfaced set is the Part-3 ranker's job.
+  MAX_K,
+};

package/lib/workflow/memory-cascade-f9-adapter.cjs

@@ -0,0 +1,273 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 189-03 (HITL Memory Governance; SEED-040 / HMG-04) -- map a governance
+ * candidate's MULTI-SECTION soft-edit cascade onto the SHIPPED F.9 ordered
+ * per-item gate. This is the ORDERED variant of the HOW decision: when a single
+ * candidate's cascade touches MORE THAN ONE section (architecture.md's cascade
+ * rule -- detect impact, soft-edit affected sections, APPROVE / REJECT / DEFER,
+ * the decision becomes graph data), the navigator resolves it through an F.9
+ * ordered per-item gate instead of the flat F.8 basket 189-02 ships for the
+ * single-section case. Array order IS meaning: item 0 (the first affected
+ * section) is decided first.
+ *
+ * Canon Part 7 (reuse before build): 189 COMPOSES the 188 F.9 shape + the 188
+ * f9-ordered-consumer, it builds NO new selector and mints NO new scalar. This
+ * module clones the EXACT idiom Phase 194-06's reconcile-f9-adapter.cjs used
+ * (buildReconcileGate + a _makeReconcileGraph-style injected graph adapter passed
+ * to consumeF9Ordered) for the DISTINCT multi-SECTION soft-edit case -- not a
+ * lost-update conflict, a single candidate's cascade across several sections.
+ *
+ * Two doors:
+ *   buildMemoryCascadeGate(candidate, opts) -> { shape:'F.9', items, zones, contract }
+ *     render candidate.affected_sections through renderShapeF9 (array order IS
+ *     meaning). PAGE_CEILING untouched. No new shape.
+ *   memoryCascadeViaF9({ candidate, decisions, roomState }) -> { ok, applied, items }
+ *     the orchestrator: build the ordered items from affected_sections zipped with
+ *     the per-section decision map (missing -> DEFER, safe default), then drive the
+ *     SHIPPED consumeF9Ordered with a memory-specific injected graph adapter.
+ *
+ * Per-item semantics (the memory-specific override of the shipped three-way):
+ *   APPROVE -> write ONE REMEMBERED_AS edge scoped to that section.
+ *   REJECT  -> write ONE NOT_REMEMBERED_BECAUSE edge scoped to that section only
+ *              (rejection is data, Decision 13; UNLIKE reconcile's NOT_APPLIED
+ *              non-write, NOT_REMEMBERED_BECAUSE is a legal ALLOWED_EDGE_TYPES
+ *              member SEED-040 names explicitly, so it DOES persist a real edge).
+ *   DEFER   -> when a DISTINCT rival section-claim exists, leave a CONTRADICTS pair
+ *              (candidate -> rival) so both claims survive; otherwise fail open to a
+ *              structured pending_contradicts no-op (never lose data).
+ *
+ * Canon Part 8: LOCAL only, zero Brain egress, zero network. Item claims are a
+ * STRUCTURAL descriptor (candidate_id + section id) ONLY, never the section's
+ * actual content body.
+ * Canon Part 9: this module NEVER opens room.db; the caller owns the db handle and
+ * every write routes through navigation.writeEdge (the single SQL chokepoint).
+ *
+ * Pure CJS, node built-ins only, zero deps. NO em-dashes. No emoji.
+ *
+ * License: BSL 1.1.
+ */
+
+const path = require('node:path');
+
+const REPO = path.resolve(__dirname, '..', '..');
+
+function _safeRequire(p) {
+  try { return require(p); } catch (_e) { return null; }
+}
+
+const renderer = _safeRequire(path.join(REPO, 'lib', 'hmi', 'shape-f9-renderer.cjs'));
+const consumerMod = _safeRequire(path.join(REPO, 'lib', 'workflow', 'f9-ordered-consumer.cjs'));
+const nav = _safeRequire(path.join(REPO, 'lib', 'core', 'navigation.cjs'));
+
+// The claim line an F.9 item shows for an affected section. STRUCTURAL only
+// (Part 8): "remember <candidate_id> under <sectionId>" -- never the candidate's
+// or the section's actual content body.
+function _cascadeClaimLine(candidate, sectionId) {
+  const cid = (candidate && typeof candidate.candidate_id === 'string' && candidate.candidate_id.length > 0)
+    ? candidate.candidate_id : 'candidate';
+  const sid = (typeof sectionId === 'string' && sectionId.length > 0) ? sectionId : 'section';
+  return 'remember ' + cid + ' under ' + sid;
+}
+
+// Normalize the affected_sections field to an array of section ids.
+function _affectedList(candidate) {
+  const a = candidate && candidate.affected_sections;
+  if (Array.isArray(a)) return a;
+  return [];
+}
+
+// buildMemoryCascadeGate(candidate, opts) -> { shape:'F.9', items, zones, contract }.
+// One affected section -> one ordered F.9 item. Renders through the SHIPPED
+// renderShapeF9 (no new shape). PAGE_CEILING untouched. Order IS meaning: item 0
+// is the FIRST affected section. Clones buildReconcileGate's body verbatim, swapping
+// "conflict" for "affected section".
+function buildMemoryCascadeGate(candidate, opts) {
+  const list = _affectedList(candidate);
+  const items = list.map(function (sectionId, i) {
+    return {
+      item_id: (typeof sectionId === 'string' && sectionId.length > 0) ? sectionId : ('item:' + i),
+      claim: _cascadeClaimLine(candidate, sectionId),
+    };
+  });
+
+  let zones = null;
+  let contract = null;
+  if (renderer && typeof renderer.renderShapeF9 === 'function') {
+    try {
+      const r = renderer.renderShapeF9({
+        items: items,
+        header: (opts && typeof opts.header === 'string') ? opts.header : null,
+        personaContext: (opts && typeof opts.personaContext === 'string') ? opts.personaContext : null,
+      });
+      if (r && typeof r === 'object') {
+        zones = r.zones || null;
+        contract = r.contract || null;
+      }
+    } catch (_e) {
+      // Fail open: an unrenderable gate still returns a usable descriptor.
+    }
+  }
+
+  return { shape: 'F.9', items: items, zones: zones, contract: contract };
+}
+
+// The memory-specific graph adapter passed to consumeF9Ordered. It MIRRORS
+// _makeReconcileGraph's structure exactly (keyed by item_id, every branch returns
+// { ok } so the ordered walk can count applied outcomes), but with memory-specific
+// per-section branches. db is caller-owned throughout (Part 9); every write routes
+// through nav.writeEdge(db, params) -- the single SQL chokepoint.
+function _makeMemoryGraph(roomState, candidate, byId) {
+  const db = (roomState && typeof roomState === 'object') ? roomState.db : null;
+  const map = (byId && typeof byId === 'object') ? byId : {};
+  return {
+    // APPROVE -> write ONE REMEMBERED_AS edge scoped to this section.
+    writeEdge: function (edge) {
+      if (!(nav && typeof nav.writeEdge === 'function' && db)) {
+        return { ok: false, reason: 'graph_unavailable' };
+      }
+      try {
+        const r = nav.writeEdge(db, {
+          source_id: candidate.candidate_id,
+          target_id: edge.item_id,
+          edge_type: 'REMEMBERED_AS',
+          properties: {
+            filed_as: candidate.chosen_verb || 'INFORMS',
+            truth_state: candidate.truth_state || 'proposed',
+            cascade: true,
+          },
+        });
+        if (r && r.ok === true) return { ok: true, kind: 'remembered_as' };
+        return { ok: false, reason: (r && r.reason) || 'edge_write_failed' };
+      } catch (_e) {
+        return { ok: false, reason: 'edge_write_threw' };
+      }
+    },
+    // REJECT -> write ONE NOT_REMEMBERED_BECAUSE edge scoped to this section only.
+    // UNLIKE reconcile's NOT_APPLIED non-write, this DOES persist a real edge:
+    // NOT_REMEMBERED_BECAUSE is a legal ALLOWED_EDGE_TYPES member (SEED-040 names
+    // it explicitly). Rejection is data (Decision 13 / Part 4).
+    recordRejection: function (rej) {
+      if (!(nav && typeof nav.writeEdge === 'function' && db)) {
+        return { ok: false, reason: 'graph_unavailable' };
+      }
+      try {
+        const r = nav.writeEdge(db, {
+          source_id: candidate.candidate_id,
+          target_id: rej.item_id,
+          edge_type: 'NOT_REMEMBERED_BECAUSE',
+          properties: {
+            reason: rej.reason || 'navigator_declined',
+            cascade: true,
+          },
+        });
+        if (r && r.ok === true) return { ok: true, kind: 'not_remembered_because' };
+        return { ok: false, reason: (r && r.reason) || 'edge_write_failed' };
+      } catch (_e) {
+        return { ok: false, reason: 'edge_write_threw' };
+      }
+    },
+    // DEFER -> both claims survive: when a DISTINCT rival section-claim exists for
+    // this section (byId[item_id] carries a rivalNodeId), write a CONTRADICTS edge
+    // candidate -> rival as proposed. Otherwise fail open to a structured
+    // pending_contradicts no-op (never lose data). Mirrors reconcile's DEFER exactly.
+    leaveContradictsPair: function (pair) {
+      const entry = map[pair.item_id];
+      const rival = entry && typeof entry.rivalNodeId === 'string' ? entry.rivalNodeId : null;
+      const cid = candidate && candidate.candidate_id;
+      if (typeof cid === 'string' && typeof rival === 'string' && cid !== rival
+          && nav && typeof nav.writeEdge === 'function' && db) {
+        try {
+          const r = nav.writeEdge(db, {
+            source_id: cid,
+            target_id: rival,
+            edge_type: 'CONTRADICTS',
+            properties: { reconcile: false, cascade: true, review_status: 'proposed' },
+          });
+          if (r && r.ok === true) return { ok: true, kind: 'contradicts' };
+          return { ok: false, reason: (r && r.reason) || 'edge_write_failed' };
+        } catch (_e) {
+          return { ok: false, reason: 'edge_write_threw' };
+        }
+      }
+      // No distinct rival: keep both as a pending competing claim (no data lost).
+      return { ok: true, kind: 'pending_contradicts', item_id: pair.item_id };
+    },
+  };
+}
+
+// Normalize an outcome token to the frozen F.9 vocabulary. Default DEFER (safe) --
+// mirrors reconcileViaF9's async-default posture: a missing / malformed decision
+// never silently drops a section.
+function _normalizeOutcome(raw) {
+  if (typeof raw !== 'string') return 'DEFER';
+  const u = raw.trim().toUpperCase();
+  if (u === 'APPROVE' || u === 'ACCEPT') return 'APPROVE';
+  if (u === 'REJECT') return 'REJECT';
+  return 'DEFER';
+}
+
+// memoryCascadeViaF9({ candidate, decisions, roomState }) -> { ok, applied, items }.
+// The orchestrator. Build the ordered items array from candidate.affected_sections
+// zipped with the per-section decisions map (item_id -> 'APPROVE'|'REJECT'|'DEFER',
+// default DEFER on a missing decision -- safe default), construct byId from
+// candidate.section_rivals (optional, item_id -> rivalNodeId), then drive the
+// SHIPPED consumeF9Ordered with the memory-specific injected graph adapter. Returns
+// its { ok, applied, items } verbatim. NEVER opens room.db (Part 9); db is
+// caller-owned throughout.
+function memoryCascadeViaF9(argsIn) {
+  const args = (argsIn && typeof argsIn === 'object') ? argsIn : {};
+  const candidate = (args.candidate && typeof args.candidate === 'object') ? args.candidate : {};
+  const decisions = (args.decisions && typeof args.decisions === 'object') ? args.decisions : {};
+  const roomState = (args.roomState && typeof args.roomState === 'object') ? args.roomState : {};
+  const db = roomState.db || null;
+
+  const affected = _affectedList(candidate);
+  const sectionReasons = (candidate.section_reasons && typeof candidate.section_reasons === 'object')
+    ? candidate.section_reasons : {};
+
+  // byId: item_id -> { rivalNodeId } from the optional section_rivals map.
+  const rivals = (candidate.section_rivals && typeof candidate.section_rivals === 'object')
+    ? candidate.section_rivals : {};
+  const byId = {};
+  for (let i = 0; i < affected.length; i++) {
+    const sid = (typeof affected[i] === 'string' && affected[i].length > 0) ? affected[i] : ('item:' + i);
+    const rival = (typeof rivals[sid] === 'string' && rivals[sid].length > 0) ? rivals[sid] : null;
+    byId[sid] = { rivalNodeId: rival };
+  }
+
+  // Build the ordered items with a resolved outcome per item (array order = meaning).
+  const items = affected.map(function (sectionId, i) {
+    const sid = (typeof sectionId === 'string' && sectionId.length > 0) ? sectionId : ('item:' + i);
+    const reason = (typeof sectionReasons[sid] === 'string' && sectionReasons[sid].length > 0)
+      ? sectionReasons[sid] : null;
+    return {
+      item_id: sid,
+      claim: _cascadeClaimLine(candidate, sid),
+      outcome: _normalizeOutcome(decisions[sid]),
+      reason: reason,
+    };
+  });
+
+  let consumed = { ok: false, applied: 0, items: [] };
+  if (consumerMod && typeof consumerMod.consumeF9Ordered === 'function' && items.length > 0) {
+    try {
+      const graph = _makeMemoryGraph({ db: db }, candidate, byId);
+      consumed = consumerMod.consumeF9Ordered({ items: items, roomState: { db: db, graph: graph } });
+    } catch (_e) {
+      consumed = { ok: false, applied: 0, items: [], reason: 'consume_threw' };
+    }
+  }
+
+  return {
+    ok: consumed.ok === true,
+    applied: consumed.applied || 0,
+    items: consumed.items || [],
+  };
+}
+
+module.exports = {
+  buildMemoryCascadeGate: buildMemoryCascadeGate,
+  memoryCascadeViaF9: memoryCascadeViaF9,
+};