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

package/lib/core/bono/hat-governance.cjs

@@ -0,0 +1,367 @@
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 223-01 -- lib/core/bono/hat-governance.cjs
+ * ================================================
+ * The de Bono hat GOVERNANCE MAP (data) plus a thin mechanical enforcement
+ * layer that rides runDebate's EXISTING injectable seams (deriveFn / onStep /
+ * selfCritiqueFn -- debate-composition.cjs). 223-RESEARCH: "the only genuinely
+ * net-new logic is the hat-governance map (data)". This module rolls no runtime;
+ * it encodes the BUILD-BRIEF Section 5 scrutiny table + the five cross-cutting
+ * rules as frozen data, and exposes selectors runDebate consumes.
+ *
+ * PHASE 210 SCOPE CAUTION (verbatim intent): these rules govern bono's DEBATE
+ * steps ONLY. They are NEVER wired into live-conversation enforcement. No hook,
+ * sensor, or command outside bono / intel-pipeline may require this module as a
+ * gate on a live conversation turn. Phase 210 selectively undid exactly that kind
+ * of over-reach; this map stays scoped to the debate logic so the mistake is not
+ * repeated. Governance shapes how the debate argues, not how Larry talks.
+ *
+ * Canon Part 8: pure LOCAL data + validation. ZERO network surface -- no fetch,
+ * no http(s), no Brain wire. The prose in HAT_GOVERNANCE is drafted from SPEC
+ * Requirement 1 + BUILD-BRIEF Section 5 (Requirement 6 fallback); this module
+ * contains no reference to any external design source, not even in comments.
+ *
+ * Pure Node.js built-ins (in fact zero requires). No emoji. No em-dashes.
+ *
+ * License: BSL 1.1.
+ */
+
+// The six de Bono hats, each with a governed scrutiny discipline. This is DATA:
+// discipline (the one-line mandate), rules (the enforceable clauses),
+// evidence_policy (how evidence is weighted), and discipline_source (the
+// methodology lineage). Frozen so a governance map cannot mutate at runtime.
+const HAT_GOVERNANCE = Object.freeze({
+  white: Object.freeze({
+    discipline: 'sourced-only facts: evidence-tiered, no interpretation, cite-or-retract',
+    rules: Object.freeze([
+      'every evidence item carries a source and an evidence tier',
+      'no interpretive claim beyond what the cited source states',
+      'an uncitable assertion is retracted, never asserted',
+    ]),
+    evidence_policy: 'cite_or_retract',
+    discipline_source: 'De Bono; SAT',
+  }),
+  black: Object.freeze({
+    discipline: 'ACH skeptic: disconfirming evidence first, steelman then attack, falsify before reject',
+    rules: Object.freeze([
+      'at least one disconfirming evidence item is present',
+      'the first cited evidence item is disconfirming (ACH weighting)',
+      'the opposing case is steelmanned before it is attacked',
+    ]),
+    evidence_policy: 'disconfirming_first',
+    discipline_source: 'Heuer/Pherson ACH; red-team',
+  }),
+  yellow: Object.freeze({
+    discipline: 'optimist: benefits and value, evidence-backed, never hope',
+    rules: Object.freeze([
+      'every benefit claim is backed by at least one evidence item',
+      'value is stated as evidence, never as hope or wish',
+    ]),
+    evidence_policy: 'evidence_backed_value',
+    discipline_source: 'De Bono',
+  }),
+  green: Object.freeze({
+    discipline: 'creative: provocations and alternatives, feeds hypotheses to Black',
+    rules: Object.freeze([
+      'at least one provocation or alternative marker is present',
+      'each provocation is framed as a testable hypothesis for the skeptic',
+    ]),
+    evidence_policy: 'provocation_marked',
+    discipline_source: 'De Bono',
+  }),
+  red: Object.freeze({
+    discipline: 'intuition: gut read, timeboxed, no justification, surfaces the unspoken',
+    rules: Object.freeze([
+      'the reading carries no justification prose (a gut read is unjustified by design)',
+      'the reading names an unspoken feeling, not a reasoned argument',
+    ]),
+    evidence_policy: 'no_justification',
+    discipline_source: 'De Bono',
+  }),
+  blue: Object.freeze({
+    discipline: 'judge and process: strongest model, MECE + parallel-thinking + anti-premature-convergence, bias-guarded',
+    rules: Object.freeze([
+      'dissent is recorded before a ruling is issued (anti-premature-convergence)',
+      'the ruling is MECE over the collected hat arguments',
+      'the judge runs on the strongest available model',
+    ]),
+    evidence_policy: 'anti_convergence',
+    discipline_source: 'De Bono; multi-agent-debate research',
+  }),
+});
+
+// The five cross-cutting governance rules that make a conclusion earned rather
+// than asserted. Frozen list of { id, rule }.
+const CROSS_CUTTING_RULES = Object.freeze([
+  Object.freeze({ id: 'heterogeneity_mandate', rule: 'no two personas share an identical lens descriptor' }),
+  Object.freeze({ id: 'anti_premature_convergence', rule: 'force dissent and steelman the losing side before a ruling' }),
+  Object.freeze({ id: 'key_assumptions_check_first', rule: 'the first material debate step surfaces the key assumptions' }),
+  Object.freeze({ id: 'disconfirming_over_confirming', rule: 'disconfirming evidence is weighted over confirming' }),
+  Object.freeze({ id: 'strongest_model_judge', rule: 'the Blue judge runs on the strongest available model' }),
+]);
+
+// The closed disposition vocabulary an evidence item may carry.
+const EVIDENCE_DISPOSITIONS = Object.freeze(['disconfirming', 'confirming', 'neutral', 'mixed']);
+
+function normalizeHat(hat) {
+  return (typeof hat === 'string') ? hat.trim().toLowerCase() : '';
+}
+
+/**
+ * governanceForHat(hat) -> the frozen entry or null. An unknown hat NEVER throws.
+ */
+function governanceForHat(hat) {
+  const key = normalizeHat(hat);
+  return Object.prototype.hasOwnProperty.call(HAT_GOVERNANCE, key) ? HAT_GOVERNANCE[key] : null;
+}
+
+function evidenceList(argument) {
+  if (!argument || typeof argument !== 'object') return [];
+  return Array.isArray(argument.evidence) ? argument.evidence : [];
+}
+
+function dispositionOf(item) {
+  if (!item || typeof item !== 'object') return 'neutral';
+  const d = (typeof item.disposition === 'string') ? item.disposition.toLowerCase() : 'neutral';
+  return EVIDENCE_DISPOSITIONS.includes(d) ? d : 'neutral';
+}
+
+/**
+ * enforceGovernance(hat, argument) -> { ok, violations:[] }
+ *
+ * A mechanical validator over the structured argument/reading shape:
+ *   { stance, evidence:[{ source, tier, disposition }], confidence,
+ *     justification?, provocations?, dissent_recorded? }
+ * Each hat enforces ONLY its own discipline; violations are short scalar reason
+ * strings and NEVER carry content bytes. An unknown hat returns ok:true (nothing
+ * to enforce) so the map differentiates behavior without ever throwing.
+ */
+function enforceGovernance(hat, argument) {
+  const key = normalizeHat(hat);
+  const arg = (argument && typeof argument === 'object') ? argument : {};
+  const evidence = evidenceList(arg);
+  const violations = [];
+
+  if (key === 'black') {
+    const dispositions = evidence.map(dispositionOf);
+    const hasDisconfirming = dispositions.indexOf('disconfirming') !== -1;
+    if (!hasDisconfirming) {
+      violations.push('black_no_disconfirming_evidence');
+    } else if (dispositions[0] !== 'disconfirming') {
+      violations.push('black_confirming_before_disconfirming');
+    }
+  } else if (key === 'white') {
+    if (evidence.length === 0) {
+      violations.push('white_no_evidence');
+    }
+    for (const item of evidence) {
+      const hasSource = item && typeof item.source === 'string' && item.source.length > 0;
+      const hasTier = item && typeof item.tier === 'string' && item.tier.length > 0;
+      if (!hasSource || !hasTier) {
+        violations.push('white_uncited_or_untiered_evidence');
+        break;
+      }
+    }
+  } else if (key === 'yellow') {
+    if (evidence.length === 0) {
+      violations.push('yellow_value_not_evidence_backed');
+    }
+  } else if (key === 'green') {
+    const provocations = Array.isArray(arg.provocations) ? arg.provocations : [];
+    const hasMarker = provocations.length > 0
+      || arg.alternative === true
+      || (typeof arg.provocation === 'string' && arg.provocation.length > 0);
+    if (!hasMarker) {
+      violations.push('green_no_provocation_marker');
+    }
+  } else if (key === 'red') {
+    const hasJustification = typeof arg.justification === 'string' && arg.justification.trim().length > 0;
+    if (hasJustification) {
+      violations.push('red_carries_justification');
+    }
+  } else if (key === 'blue') {
+    const dissentRecorded = arg.dissent_recorded === true || arg.anti_convergence === true;
+    if (!dissentRecorded) {
+      violations.push('blue_ruling_without_recorded_dissent');
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+// Resolve the lens/persona identity descriptor a cell carries. Checks the
+// canonical fields in order; returns '' when none is present.
+function lensDescriptor(cell) {
+  if (!cell || typeof cell !== 'object') return '';
+  const candidates = [cell.lens, cell.lens_descriptor, cell.persona, cell.lensId];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) return c;
+  }
+  return '';
+}
+
+/**
+ * assertHeterogeneity(cells) -> { ok, duplicates:[] }
+ *
+ * The heterogeneity mandate: no two persona cells may share an identical lens
+ * descriptor. Returns the list of duplicated descriptors. Cells with no
+ * descriptor are ignored (they cannot collide). Never throws.
+ */
+function assertHeterogeneity(cells) {
+  const list = Array.isArray(cells) ? cells : [];
+  const seen = Object.create(null);
+  const duplicates = [];
+  for (const cell of list) {
+    const d = lensDescriptor(cell);
+    if (!d) continue;
+    if (seen[d]) {
+      if (duplicates.indexOf(d) === -1) duplicates.push(d);
+    } else {
+      seen[d] = true;
+    }
+  }
+  return { ok: duplicates.length === 0, duplicates };
+}
+
+// Resolve a step's hat from step.hat or its 'bono-argument-<hat>' command.
+function hatForStep(step) {
+  if (!step || typeof step !== 'object') return '';
+  if (typeof step.hat === 'string' && step.hat.length > 0) return normalizeHat(step.hat);
+  if (typeof step.command === 'string') {
+    const m = step.command.toLowerCase().match(/bono-argument-([a-z]+)/);
+    if (m) return m[1];
+  }
+  return '';
+}
+
+// Extract the governed argument object from a runChain step result. The debate
+// consolidator carries it on chain_output.argument; a bare chain_output that
+// already looks like an argument (has a stance/evidence) is used directly.
+function argumentFromResult(result) {
+  if (!result || typeof result !== 'object') return null;
+  const co = result.chain_output;
+  if (co && typeof co === 'object') {
+    if (co.argument && typeof co.argument === 'object') return co.argument;
+    if (typeof co.stance === 'string' || Array.isArray(co.evidence)) return co;
+  }
+  return null;
+}
+
+// Is this the Key-Assumptions-Check step (the mandated first material step)?
+function isKacStep(step) {
+  if (!step || typeof step !== 'object') return false;
+  if (step.kac === true || step.key_assumptions_check === true) return true;
+  if (typeof step.command === 'string') {
+    const c = step.command.toLowerCase();
+    return c.indexOf('assumption') !== -1 || c.indexOf('kac') !== -1;
+  }
+  return false;
+}
+
+/**
+ * composeGovernedSeams(opts) -> { deriveFn, selfCritiqueFn, onStep }
+ *
+ * Returns seams shaped EXACTLY to runDebate's injectable options:
+ *   - deriveFn({ roomDir, artifactPair, llm }) -> Array (SYNCHRONOUS, CR-01).
+ *     Wraps opts.deriveCandidateFn (Plan 03's stance-aware producer) or a default
+ *     per-hat CONVERGES producer. If a producer returns a thenable, the wrapper
+ *     does NOT let it escape -- it returns [] so no Promise reaches runDerivation
+ *     (the synchronous composer throws on a thenable; we pre-empt that).
+ *   - selfCritiqueFn(step, result) -> verdict. Routes a material per-hat step's
+ *     governed argument through enforceGovernance for that step's hat. Returns
+ *     the debate-composition critique contract { passed, quality, violations }.
+ *   - onStep(step, previousOutput) -> { chain_output, quality }. Wraps
+ *     opts.onStepFn and enforces Key-Assumptions-Check-first ordering: if the
+ *     first MATERIAL step is not the assumptions surface, it flags the step and
+ *     downgrades quality to 'low'.
+ *
+ * opts:
+ *   hats               the debate hats (metadata for callers)
+ *   deriveCandidateFn  optional sync candidate producer override (Plan 03)
+ *   onStepFn           optional inner per-step dispatch (default a thin passthrough)
+ */
+function composeGovernedSeams(opts) {
+  const o = (opts && typeof opts === 'object') ? opts : {};
+  const deriveCandidateFn = (typeof o.deriveCandidateFn === 'function') ? o.deriveCandidateFn : null;
+  const onStepFn = (typeof o.onStepFn === 'function') ? o.onStepFn : null;
+
+  // deriveFn: synchronous over pre-resolved cell data. Never returns a Promise.
+  function deriveFn(args) {
+    const a = (args && typeof args === 'object') ? args : {};
+    const pair = (a.artifactPair && typeof a.artifactPair === 'object') ? a.artifactPair : null;
+    if (!pair) return [];
+    let candidates;
+    if (deriveCandidateFn) {
+      candidates = deriveCandidateFn({ roomDir: a.roomDir, artifactPair: pair, llm: a.llm });
+      // CR-01: a thenable must NOT escape this synchronous seam.
+      if (candidates && typeof candidates.then === 'function') return [];
+      return Array.isArray(candidates) ? candidates : [];
+    }
+    // Default: a per-hat CONVERGES claim about the hypothesis (conservative).
+    return [{
+      source: pair.b,
+      target: pair.a,
+      edge_type: 'CONVERGES',
+      reason: 'hat ' + String(pair.hat || '') + ' argument bears on the hypothesis',
+    }];
+  }
+
+  // selfCritiqueFn: route the step's governed argument through enforceGovernance.
+  function selfCritiqueFn(step, result) {
+    const hat = hatForStep(step);
+    const argument = argumentFromResult(result);
+    if (!hat || !argument) {
+      // Nothing governed to critique -- pass through at the incoming quality.
+      const q = (result && typeof result === 'object' && result.quality) ? result.quality : 'high';
+      return { passed: true, quality: q };
+    }
+    const verdict = enforceGovernance(hat, argument);
+    if (!verdict.ok) {
+      return { passed: false, quality: 'low', violations: verdict.violations };
+    }
+    return { passed: true, quality: 'high' };
+  }
+
+  // onStep: enforce Key-Assumptions-Check-first ordering across the debate.
+  let materialSeen = 0;
+  function onStep(step, previousOutput) {
+    let inner;
+    if (onStepFn) {
+      inner = onStepFn(step, previousOutput);
+    } else {
+      inner = { chain_output: { step: step && step.command }, quality: 'high' };
+    }
+    const result = (inner && typeof inner === 'object') ? inner : { chain_output: null, quality: 'high' };
+    if (step && step.material) {
+      materialSeen += 1;
+      if (materialSeen === 1 && !isKacStep(step)) {
+        const co = (result.chain_output && typeof result.chain_output === 'object')
+          ? Object.assign({}, result.chain_output)
+          : { value: result.chain_output };
+        co.governance_flag = 'kac_not_first';
+        return { chain_output: co, quality: 'low' };
+      }
+    }
+    return result;
+  }
+
+  return { deriveFn, selfCritiqueFn, onStep };
+}
+
+module.exports = {
+  HAT_GOVERNANCE,
+  CROSS_CUTTING_RULES,
+  EVIDENCE_DISPOSITIONS,
+  governanceForHat,
+  enforceGovernance,
+  assertHeterogeneity,
+  composeGovernedSeams,
+  // exposed for tests + Plan 03 wiring
+  lensDescriptor,
+  hatForStep,
+  argumentFromResult,
+  isKacStep,
+};

package/lib/core/bono/persona-research.cjs

@@ -0,0 +1,288 @@
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 223-01 -- lib/core/bono/persona-research.cjs
+ * ==================================================
+ * Per-(subdomain x hat) cell world-of-knowledge, injected as runCellFanout's
+ * dispatchCell seam (cell-fanout.cjs:237-256). For each cell the pipe is:
+ *   extractContext -> runSourceLens -> wireAccept
+ * giving each persona ITS OWN wired INFORMS set. A persona may not assert beyond
+ * that set (validateCitations is the mechanical boundary check).
+ *
+ * Canon Part 8 (SIGNAL -> LOCAL only): the web leg INGESTS public content into
+ * LOCAL EvidenceClaims -- the legal direction. It is DELEGATED to runSourceLens
+ * (which owns the auditQueryString pre-egress chokepoint); this module never
+ * hand-rolls a network call. Any Brain-bound payload (generic dimension hints)
+ * MUST pass part8-egress-guard.classify first and proceed ONLY on verdict
+ * 'allow'; a 'block'/'ambiguous' verdict skips the Brain leg with a disclosed
+ * marker (fail-closed, SEED-059). The ONLY thing that ever crosses toward the
+ * Brain is the GENERIC domain handle (cell.handle) -- never room content, never
+ * an outbound query string built from local bytes.
+ *
+ * Canon Part 9: accepted findings land as PROPOSED EvidenceClaim nodes + INFORMS
+ * edges through findings-wirer.wireAccept (the navigation chokepoint). Nothing is
+ * auto-confirmed.
+ *
+ * Defensive: a missing db degrades to wire-skipped with a disclosed marker (never
+ * a throw); cell-fanout's defensive stub is the outer net.
+ *
+ * Pure Node.js built-ins + the shipped extractor / lens-driver / wirer / guard.
+ * Zero npm deps. No emoji. No em-dashes.
+ *
+ * License: BSL 1.1.
+ */
+
+const researchContextExtractor = require('../research-context-extractor.cjs');
+const sourceLensDriver = require('../../lens-engine/source-lens-driver.cjs');
+const findingsWirer = require('../findings-wirer.cjs');
+const egressGuard = require('../part8-egress-guard.cjs');
+
+// The closed stance vocabulary (mirrors cell-fanout.CELL_STANCES).
+const STANCES = Object.freeze(['supports', 'challenges', 'refines', 'neutral']);
+
+// A per-hat lens bias: which lens families a hat leans on when the extracted
+// lens set offers a choice. This is what makes two cells over the SAME subdomain
+// but DIFFERENT hats select different lens scopes. Bias is a soft reorder over
+// the extracted set; it never invents a lens the extractor did not surface.
+const HAT_LENS_BIAS = Object.freeze({
+  white: ['scholarly', 'reference', 'official'],
+  black: ['adversarial', 'contrarian', 'scholarly'],
+  yellow: ['market', 'case-study', 'scholarly'],
+  green: ['lateral', 'analogical', 'emerging'],
+  red: ['intuitive', 'social'],
+  blue: ['synthesis', 'scholarly'],
+});
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function normalizeHat(hat) {
+  return (typeof hat === 'string') ? hat.trim().toLowerCase() : '';
+}
+
+// Reorder the extracted lens set by the hat's bias so the web leg's scope is
+// hat-driven. Lenses named in the bias float to the front (bias order); the rest
+// keep their extracted order. Pure, never drops a lens.
+function hatScopedLensSet(lensSet, hat) {
+  const list = Array.isArray(lensSet) ? lensSet.filter((e) => isPlainObject(e) && typeof e.lens === 'string') : [];
+  const bias = HAT_LENS_BIAS[normalizeHat(hat)] || [];
+  if (bias.length === 0 || list.length === 0) return list.slice();
+  const rank = (lens) => {
+    const i = bias.indexOf(lens);
+    return i === -1 ? bias.length : i;
+  };
+  return list.slice().sort((a, b) => rank(a.lens) - rank(b.lens));
+}
+
+function coerceStance(raw) {
+  const s = (typeof raw === 'string') ? raw : 'neutral';
+  return STANCES.includes(s) ? s : 'neutral';
+}
+
+/**
+ * personaDispatchCell(cell, ctx) -> Promise<reading>
+ *
+ * The runCellFanout dispatchCell-contract function (async; cell-fanout awaits it).
+ *   cell = { subdomain, hat, handle }
+ *   ctx  = {
+ *     extractContextFn?  default research-context-extractor.extractContext
+ *     runSourceLensFn?   default source-lens-driver.runSourceLens
+ *     wireAcceptFn?      default findings-wirer.wireAccept
+ *     classifyFn?        default part8-egress-guard.classify
+ *     brainFn?           optional generic-dimension-hint Brain leg (gated by classify)
+ *     db, roomDir, topic, sessionId   forwarded to the wirer + extractor
+ *   }
+ *
+ * Returns the normalized reading:
+ *   { subdomain, hat, stance, evidence, confidence, wired_sources, degraded,
+ *     degraded_reasons, brain_skipped? }
+ * where wired_sources is EXACTLY the node_ids wireAccept returned (the persona's
+ * own INFORMS set) and every evidence item cites a source inside that set.
+ */
+async function personaDispatchCell(cell, ctx) {
+  const c = isPlainObject(cell) ? cell : {};
+  const context = isPlainObject(ctx) ? ctx : {};
+  const subdomain = typeof c.subdomain === 'string' ? c.subdomain : '';
+  const hat = typeof c.hat === 'string' ? c.hat : '';
+  // GENERIC handle ONLY ever crosses outbound (Part 8). Never room content.
+  const handle = typeof c.handle === 'string' ? c.handle : '';
+
+  const extractContextFn = (typeof context.extractContextFn === 'function')
+    ? context.extractContextFn : researchContextExtractor.extractContext;
+  const runSourceLensFn = (typeof context.runSourceLensFn === 'function')
+    ? context.runSourceLensFn : sourceLensDriver.runSourceLens;
+  const wireAcceptFn = (typeof context.wireAcceptFn === 'function')
+    ? context.wireAcceptFn : findingsWirer.wireAccept;
+  const classifyFn = (typeof context.classifyFn === 'function')
+    ? context.classifyFn : egressGuard.classify;
+  const brainFn = (typeof context.brainFn === 'function') ? context.brainFn : null;
+
+  const db = context.db || null;
+  const roomDir = typeof context.roomDir === 'string' ? context.roomDir : '';
+  const topic = typeof context.topic === 'string' ? context.topic : handle;
+  const sessionId = typeof context.sessionId === 'string' ? context.sessionId : 'bono-persona';
+
+  const degraded_reasons = [];
+
+  // (a) extractContext scoped to the subdomain + hat-driven lens selection. The
+  // hat is threaded so two cells over the same subdomain but different hats pick
+  // different lens scopes.
+  let extracted;
+  try {
+    extracted = extractContextFn({ roomDir, sessionId, topic, db, subdomain, hat });
+  } catch (_e) {
+    extracted = null;
+  }
+  const baseLensSet = (extracted && Array.isArray(extracted.lens_set)) ? extracted.lens_set : [];
+  const lensSet = hatScopedLensSet(baseLensSet, hat);
+
+  // (b) web leg via runSourceLens with the GENERIC handle ONLY. runSourceLens
+  // owns the pre-egress audit; we pass no room content in the query string.
+  let lensResult = null;
+  try {
+    lensResult = await runSourceLensFn({
+      roomDir,
+      topic: handle, // GENERIC handle only -- never room content (Part 8)
+      lensSet,
+      preflight: (extracted && isPlainObject(extracted.preflight)) ? extracted.preflight : {},
+      db,
+      sessionId,
+    });
+  } catch (_e) {
+    lensResult = null;
+  }
+  const findings = (lensResult && Array.isArray(lensResult.findings)) ? lensResult.findings : [];
+
+  // (c) wire each accepted finding as a PROPOSED EvidenceClaim + INFORMS, and
+  // collect the returned node_ids into the persona's wired source set.
+  const wired_sources = [];
+  const evidence = [];
+  if (!db) {
+    degraded_reasons.push('db_absent_wire_skipped');
+  }
+  for (const finding of findings) {
+    if (!isPlainObject(finding)) continue;
+    if (!db) continue; // wire-skipped: no db to write into (disclosed above)
+    let res = null;
+    try {
+      res = wireAcceptFn(db, {
+        finding: {
+          title: finding.title,
+          source: finding.source,
+          url: finding.url,
+          retrieved_at: finding.retrieved_at,
+          evidence_tier: finding.evidence_tier,
+          summary: finding.summary,
+        },
+        decision: { target_section: subdomain || 'research', target_kind: 'local' },
+        roomDir,
+        sessionId,
+        topic: handle,
+      });
+    } catch (_e) {
+      res = null;
+    }
+    if (res && res.ok && typeof res.node_id === 'string') {
+      wired_sources.push(res.node_id);
+      // The evidence item cites the WIRED node id -- a persona may only assert
+      // from within its own INFORMS set (validateCitations enforces it).
+      evidence.push({
+        source: res.node_id,
+        title: typeof finding.title === 'string' ? finding.title : '',
+        tier: typeof finding.evidence_tier === 'string' ? finding.evidence_tier : '',
+        url: typeof finding.url === 'string' ? finding.url : '',
+        disposition: 'confirming',
+      });
+    }
+  }
+
+  // The thin-world state is STRUCTURAL, never silent (SEED-059).
+  const degraded = wired_sources.length === 0;
+  if (degraded && degraded_reasons.indexOf('db_absent_wire_skipped') === -1) {
+    degraded_reasons.push('no_wired_sources');
+  }
+
+  // (d optional) the Brain leg: generic dimension hints. EVERY Brain-bound
+  // payload passes classify FIRST and proceeds ONLY on verdict 'allow'. The
+  // payload carries the GENERIC handle only -- never room content.
+  let brain_skipped = false;
+  let brain_hints = null;
+  if (brainFn) {
+    const brainPayload = { ask: handle, question: handle };
+    let verdict = null;
+    try {
+      verdict = classifyFn(brainPayload, { toolName: 'brain_ask' });
+    } catch (_e) {
+      verdict = null;
+    }
+    if (verdict && verdict.verdict === 'allow') {
+      try {
+        brain_hints = await brainFn(brainPayload);
+      } catch (_e) {
+        brain_hints = null;
+        brain_skipped = true;
+        degraded_reasons.push('brain_call_threw');
+      }
+    } else {
+      brain_skipped = true;
+      degraded_reasons.push('brain_egress_' + (verdict && verdict.verdict ? verdict.verdict : 'unverified'));
+    }
+  }
+
+  const stance = coerceStance(evidence.length > 0 ? 'supports' : 'neutral');
+  const confidence = evidence.length > 0 ? Math.min(0.5 + 0.1 * evidence.length, 0.9) : 0.2;
+
+  const reading = {
+    subdomain,
+    hat,
+    stance,
+    evidence,
+    confidence,
+    wired_sources,
+    degraded,
+    degraded_reasons,
+  };
+  if (brainFn) {
+    reading.brain_skipped = brain_skipped;
+    reading.brain_hints = brain_hints;
+  }
+  return reading;
+}
+
+/**
+ * validateCitations(reading) -> { ok, violations:[] }
+ *
+ * The citation-boundary check: every evidence citation's source id MUST be inside
+ * reading.wired_sources. Exported separately so hat-governance's selfCritiqueFn
+ * (Plan 03 wiring) and tests can call it directly. Violations are scalar strings.
+ */
+function validateCitations(reading) {
+  const r = isPlainObject(reading) ? reading : {};
+  const evidence = Array.isArray(r.evidence) ? r.evidence : [];
+  const wired = Array.isArray(r.wired_sources) ? r.wired_sources : [];
+  const wiredSet = new Set(wired);
+  const violations = [];
+  for (const item of evidence) {
+    const src = item && typeof item.source === 'string' ? item.source : null;
+    if (!src) {
+      violations.push('citation_missing_source');
+      continue;
+    }
+    if (!wiredSet.has(src)) {
+      violations.push('citation_outside_wired_set');
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+
+module.exports = {
+  personaDispatchCell,
+  validateCitations,
+  // exposed for tests + Plan 03 wiring
+  hatScopedLensSet,
+  HAT_LENS_BIAS,
+  STANCES,
+};