@mindrian_os/install 1.13.0-beta.11

package/lib/core/rs-commercial-assessor.cjs

@@ -0,0 +1,280 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ * Phase 89.5 Plan 01 -- Phase 4 commercial assessor (deterministic).
+ *
+ * Deterministic 3-field commercial layer consumed by the Phase 89.5-04
+ * top-level orchestrator (kickoff §5 Phase 4 Synthesis). Reads the post-
+ * breakthrough-scorer + post-fetcher rs_discovery shape and emits:
+ *
+ *   {
+ *     market_size_estimate: <string from frozen 5-bucket TAM/SAM table>,
+ *     value_proposition:    <string from frozen classification template table>,
+ *     partnership_targets:  <array derived from resolved_institutions + resolved_authors>,
+ *   }
+ *
+ * Hard contract:
+ *   1. NO runtime LLM call (no fetch, no brain-client, no spawn of model
+ *      process). Pure-function from a frozen table lookup + array map.
+ *   2. Deterministic: same input -> byte-identical JSON.stringify(output)
+ *      across N invocations.
+ *   3. Edge-case safe: zero industry signals, single expert, missing
+ *      breakthrough_score, missing classification all produce deterministic
+ *      safe defaults; never throws on missing fields. Only throw paths are
+ *      Canon Part 8 forbidden-pattern violations on adversarial input.
+ *   4. Canon Part 8 chokepoint: FIRST line of body is auditQueryObject on
+ *      the (rs_discovery, opts) tuple. Any forbidden field anywhere in the
+ *      tuple raises ExternalEgressViolation BEFORE any computation.
+ *
+ * Frozen tables:
+ *   VALUE_PROP_TEMPLATES -- keyed on classification ('structural_transfer',
+ *     'semantic_implementation', 'hybrid', '_fallback'). Larry-style
+ *     template stems with [bridge_concept] / [source] / [target] /
+ *     [outcome] placeholders that are filled deterministically from
+ *     rs_discovery scalars (no free-form generation).
+ *
+ *   MARKET_SIZE_BUCKETS -- 5 frozen TAM/SAM proxy buckets keyed on the
+ *     2D quantile of (industry_signals_count, breakthrough_score):
+ *       emerging-niche   (signals <= 1, score < 5)
+ *       small-targeted   (signals 2-3, score 5-7)
+ *       mid-market       (signals 4-6, score 6-8)
+ *       large-market     (signals 7-10, score 8-9)
+ *       platform-scale   (signals > 10, score >= 9)
+ *     Edge: missing breakthrough_score -> 'unknown-bucket' (deterministic).
+ *
+ *   Bucket thresholds tuned conservatively for v1.11.0-beta.1; expanding
+ *   the bucket vocabulary requires a Plan 89.5-01-N revision (canon-amend
+ *   discipline).
+ *
+ * Pure CJS, zero npm deps, no Node built-ins beyond core require.
+ */
+'use strict';
+
+const { ExternalEgressViolation } = require('./rs-egress-violations.cjs');
+const { auditQueryObject } = require('./rs-egress-prompts.cjs');
+
+// ---------- Frozen invariants ----------
+
+// Larry-style value-proposition template stems keyed on classification.
+// Each stem is a deterministic template with [PLACEHOLDER] tokens that
+// are filled from rs_discovery scalars. NO free-form text generation.
+//
+// Stem-prefix design rule: the first 12 characters of each rendered
+// template string MUST differ across the three real classifications +
+// the fallback so T8 (classification table coverage) can verify table
+// distinctness on the rendered output without coupling to internal stem
+// keys. The leading words below ('Apply' / 'Implement' / 'Bridge' /
+// 'Cross-domain') satisfy the 12-char-distinct invariant.
+const VALUE_PROP_TEMPLATES = Object.freeze({
+  structural_transfer:
+    'Apply [BRIDGE] from [SOURCE] to [TARGET] to unlock cross-domain advantage',
+  semantic_implementation:
+    'Implement [BRIDGE] in [TARGET] to compress time from insight to validated decision',
+  hybrid:
+    'Bridge [SOURCE] and [TARGET] via [BRIDGE] to unlock a defensible cross-domain moat',
+  _fallback:
+    'Cross-domain opportunity: combine [SOURCE] and [TARGET] to address an underserved gap',
+});
+
+// 5-bucket TAM/SAM proxy table. Keyed on bucket-id; each entry is a
+// frozen string. Bucket selection is deterministic via a 2D step-function
+// over (industry_signals_count, breakthrough_score). See bucketize() below.
+const MARKET_SIZE_BUCKETS = Object.freeze({
+  'unknown-bucket':
+    'unknown-bucket: insufficient signal to estimate market size',
+  'emerging-niche':
+    'emerging-niche: pre-market opportunity; demand signal not yet established',
+  'small-targeted':
+    'small-targeted: focused vertical with bounded TAM; early-stage adopters',
+  'mid-market':
+    'mid-market: established demand with measurable SAM; multi-segment reach',
+  'large-market':
+    'large-market: validated demand with broad SAM; cross-segment platform potential',
+  'platform-scale':
+    'platform-scale: category-defining opportunity with cross-vertical reach',
+});
+
+// Frozen safe-default scalars.
+const SAFE_DEFAULT_BRIDGE = 'cross-domain bridge concept';
+const SAFE_DEFAULT_SOURCE = 'source domain';
+const SAFE_DEFAULT_TARGET = 'target domain';
+
+// ---------- bucketize ----------
+//
+// 2D step-function over (signals, score). Pure deterministic lookup.
+//
+// Bucket selection rules (in order; first match wins):
+//   missing breakthrough_score (score === null)  -> 'unknown-bucket'
+//   signals <= 1 AND score < 5                   -> 'emerging-niche'
+//   signals between 2-3 AND score in [5, 7]      -> 'small-targeted'
+//   signals between 4-6 AND score in [6, 8]      -> 'mid-market'
+//   signals between 7-10 AND score in [8, 9]     -> 'large-market'
+//   signals > 10 AND score >= 9                  -> 'platform-scale'
+//   anything else                                -> nearest-neighbor by signals
+
+function bucketize(signals, score) {
+  if (score === null || score === undefined) return 'unknown-bucket';
+  const s = (typeof signals === 'number' && isFinite(signals)) ? signals : 0;
+  const b = (typeof score === 'number' && isFinite(score)) ? score : 0;
+  // Top-down: pick the highest-bucket the input qualifies for. Each bucket
+  // requires BOTH signals AND score to satisfy its threshold pair so a
+  // single high dimension cannot inflate the estimate.
+  if (s > 10 && b >= 9) return 'platform-scale';
+  if (s >= 7 && b >= 8) return 'large-market';
+  if (s >= 4 && b >= 6) return 'mid-market';
+  if (s >= 2 && b >= 5) return 'small-targeted';
+  return 'emerging-niche';
+}
+
+// ---------- buildPartnershipTargets ----------
+//
+// Pure-function map from resolved_institutions + resolved_authors to a
+// deterministic ordered array of partnership targets. Empty inputs yield
+// [] (empty array). Authors precede institutions; both are sorted by the
+// natural input order from the upstream fetcher (no re-sort here so
+// upstream determinism propagates).
+
+function buildPartnershipTargets(rs_discovery) {
+  if (!rs_discovery || typeof rs_discovery !== 'object') return [];
+  const out = [];
+  const authors = Array.isArray(rs_discovery.resolved_authors) ? rs_discovery.resolved_authors : [];
+  for (let i = 0; i < authors.length; i += 1) {
+    const a = authors[i];
+    if (!a || typeof a !== 'object') continue;
+    const name = (typeof a.name === 'string' && a.name.length > 0) ? a.name : null;
+    if (!name) continue;
+    out.push({
+      name: name,
+      type: 'author',
+      // Score = 1.0 - (i / authors.length) so the upstream-natural-order
+      // first author scores highest. Deterministic from input order.
+      score: 1.0 - (i / Math.max(authors.length, 1)),
+    });
+  }
+  const institutions = Array.isArray(rs_discovery.resolved_institutions) ? rs_discovery.resolved_institutions : [];
+  for (let i = 0; i < institutions.length; i += 1) {
+    const inst = institutions[i];
+    if (typeof inst !== 'string' || inst.length === 0) continue;
+    out.push({
+      name: inst,
+      type: 'institution',
+      score: 1.0 - (i / Math.max(institutions.length, 1)),
+    });
+  }
+  return out;
+}
+
+// ---------- buildValueProposition ----------
+//
+// Deterministic template-fill from frozen VALUE_PROP_TEMPLATES. Picks
+// the template by classification (with '_fallback' for missing); fills
+// [BRIDGE] / [SOURCE] / [TARGET] tokens from rs_discovery scalars when
+// present (with safe defaults otherwise).
+
+function buildValueProposition(rs_discovery) {
+  const cls = (rs_discovery && typeof rs_discovery.classification === 'string'
+    && (rs_discovery.classification in VALUE_PROP_TEMPLATES))
+    ? rs_discovery.classification
+    : '_fallback';
+  let stem = VALUE_PROP_TEMPLATES[cls];
+  const bridge = (rs_discovery && typeof rs_discovery.bridge_concept === 'string'
+    && rs_discovery.bridge_concept.length > 0)
+    ? rs_discovery.bridge_concept
+    : SAFE_DEFAULT_BRIDGE;
+  const source = (rs_discovery && typeof rs_discovery.query_concept === 'string'
+    && rs_discovery.query_concept.length > 0)
+    ? rs_discovery.query_concept
+    : SAFE_DEFAULT_SOURCE;
+  const target = (rs_discovery && typeof rs_discovery.doc_concept === 'string'
+    && rs_discovery.doc_concept.length > 0)
+    ? rs_discovery.doc_concept
+    : SAFE_DEFAULT_TARGET;
+  // Token replacement is deterministic global string replace; no regex
+  // escaping needed because tokens are frozen literals.
+  stem = stem.split('[BRIDGE]').join(bridge);
+  stem = stem.split('[SOURCE]').join(source);
+  stem = stem.split('[TARGET]').join(target);
+  return stem;
+}
+
+// ---------- buildMarketSizeEstimate ----------
+//
+// Pure-function lookup from frozen MARKET_SIZE_BUCKETS. Reads
+// industry_signals_count + breakthrough_score; missing breakthrough_score
+// yields 'unknown-bucket' (the safe-default path).
+
+function buildMarketSizeEstimate(rs_discovery) {
+  if (!rs_discovery || typeof rs_discovery !== 'object') {
+    return MARKET_SIZE_BUCKETS['unknown-bucket'];
+  }
+  const signals = (typeof rs_discovery.industry_signals_count === 'number')
+    ? rs_discovery.industry_signals_count
+    : 0;
+  // Distinguish "explicitly missing breakthrough_score" (-> unknown-bucket)
+  // from "score = 0" (-> emerging-niche by bucketize). The hasOwnProperty
+  // check catches the missing case.
+  const hasScore = Object.prototype.hasOwnProperty.call(rs_discovery, 'breakthrough_score')
+    && rs_discovery.breakthrough_score !== undefined
+    && rs_discovery.breakthrough_score !== null;
+  const score = hasScore ? rs_discovery.breakthrough_score : null;
+  const bucketId = bucketize(signals, score);
+  return MARKET_SIZE_BUCKETS[bucketId];
+}
+
+// ---------- assess ----------
+//
+// Public entry point. FIRST line of body: auditQueryObject on the
+// composite (rs_discovery, opts) tuple. Throws ExternalEgressViolation on
+// any forbidden field BEFORE any computation. The chokepoint is the only
+// throw path; all other branches return deterministic safe defaults.
+//
+// Inputs:
+//   rs_discovery  optional object (post-breakthrough-scorer shape)
+//   opts          optional object (caller-supplied configuration scalars)
+//
+// Output:
+//   {
+//     market_size_estimate: <string from MARKET_SIZE_BUCKETS>,
+//     value_proposition:    <string from VALUE_PROP_TEMPLATES>,
+//     partnership_targets:  <array of {name, type, score} entries>,
+//   }
+
+function assess(rs_discovery, opts) {
+  // Canon Part 8 chokepoint: pre-input audit on the composite tuple.
+  // Throws ExternalEgressViolation BEFORE any field is touched. Empty
+  // tuple is permitted (no-args path); only the audit-on-non-empty
+  // branch is adversarial-relevant. We always audit so a malicious
+  // opts cannot smuggle through the no-args branch.
+  auditQueryObject({
+    rs_discovery: (rs_discovery === undefined ? null : rs_discovery),
+    opts: (opts === undefined ? null : opts),
+  }, 'rs-commercial-assessor-input');
+
+  // Safe-default path: no rs_discovery -> deterministic minimal output.
+  const safeIn = (rs_discovery && typeof rs_discovery === 'object') ? rs_discovery : {};
+
+  return {
+    market_size_estimate: buildMarketSizeEstimate(safeIn),
+    value_proposition: buildValueProposition(safeIn),
+    partnership_targets: buildPartnershipTargets(safeIn),
+  };
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  assess: assess,
+  // Re-export sentinel so adversarial fixtures can reference the class
+  // without a second require() round-trip.
+  ExternalEgressViolation: ExternalEgressViolation,
+  _test: {
+    VALUE_PROP_TEMPLATES: VALUE_PROP_TEMPLATES,
+    MARKET_SIZE_BUCKETS: MARKET_SIZE_BUCKETS,
+    SAFE_DEFAULT_BRIDGE: SAFE_DEFAULT_BRIDGE,
+    SAFE_DEFAULT_SOURCE: SAFE_DEFAULT_SOURCE,
+    SAFE_DEFAULT_TARGET: SAFE_DEFAULT_TARGET,
+    bucketize: bucketize,
+    buildPartnershipTargets: buildPartnershipTargets,
+    buildValueProposition: buildValueProposition,
+    buildMarketSizeEstimate: buildMarketSizeEstimate,
+  },
+};

package/lib/core/rs-differential-scorer.cjs

@@ -0,0 +1,376 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ * Phase 89.2 Plan 06 Task 3 -- Phase 3 dual-floor differential scorer.
+ *
+ * Pair-wise differential scorer per kickoff §5:
+ *
+ *   pair passes IFF (diff > 0.3 AND LSA > 0.2 AND BERT > 0.2)
+ *
+ * where diff = |LSA - BERT|. Strict > comparisons throughout (Test 5
+ * verifies the exact-threshold case fails). The dual-floor filter is the
+ * detection signal that distinguishes structural-transfer pairs (LSA high,
+ * BERT low) from semantic-implementation pairs (BERT high, LSA low) from
+ * direct-intersection pairs (both high, low diff -- pruned by the diff floor).
+ *
+ * --------------------------------------------------------------------------
+ * CANON PART 7 CARVE-OUT (DELIBERATE, DOCUMENTED)
+ * --------------------------------------------------------------------------
+ *
+ * The pair-wise LSA cosine below uses an embedded sklearn TfidfVectorizer +
+ * TruncatedSVD subset inside lsaBridgeScript -- NOT rs_math.py's
+ * build_tfidf_svd. This is a deliberate exception to Reuse Before Build
+ * because rs_math.py's API is CORPUS-LEVEL: it expects Sequence[str] >= 3
+ * documents and fits a corpus-wide IDF + SVD basis. A pair-wise comparison
+ * (1 query_concept vs 1 doc_concept = 2-document mini-corpus) cannot consume
+ * that API without forcing degenerate corpus statistics that change the
+ * algorithm's semantics:
+ *
+ *   - 2-document IDF is mathematically meaningless (IDF on a 2-document
+ *     corpus collapses the whole vocabulary into one of two values; the
+ *     "rare-term up-weighting" that motivates IDF stops working).
+ *
+ *   - 1-component SVD (max for a 2-document matrix) does NOT correspond
+ *     to Kwan 2023's algorithm, which fits ~80 components against a real
+ *     corpus to capture topic structure.
+ *
+ * The pair-wise question requires a fresh per-pair TfidfVectorizer +
+ * TruncatedSVD fit specifically tuned for the pair-wise cosine -- which IS
+ * what lsaBridgeScript does. rs_math.py continues to be consumed in its
+ * CORPUS-MODE use case (e.g., scripts/rs-engine.py for corpus reverse-salient
+ * computation per Phase 89-01 / 89-03 / 89-05).
+ *
+ * To avoid future drift toward "all LSA must go through one path," this
+ * carve-out is documented in three locations:
+ *
+ *   1. The plan's must_haves block + objective (.planning/phases/89.2-.../
+ *      89.2-06-preprocessor-and-differential-scorer-PLAN.md)
+ *   2. This source file's header comment block (above)
+ *   3. The embedded Python lsaBridgeScript header (inside lsaBridgeScript)
+ *
+ * Acceptance grep enforces the carve-out comment block (>= 2 hits across
+ * the CJS header AND the embedded Python header) so refactors that strip
+ * one without the other are loud, not silent.
+ *
+ * --------------------------------------------------------------------------
+ *
+ * BERT cosine path (Canon Part 7 reuse, NO carve-out): consumes
+ * lib/core/rs-pinecone-bridge.cjs (Task 1 of this plan) which wraps the
+ * existing rs_cache.py::fetch_all_from_namespace primitive (Phase 89-03
+ * v1.10.16) for strict-1024-dim Pinecone-direct vector retrieval.
+ *
+ * Graceful degradation contract:
+ *
+ *   bridge fails (no PINECONE_API_KEY, network error, namespace empty)
+ *     -> {diff: <lsa>, lsa: <lsa>, bert: null, passes: lsa > LSA_FLOOR,
+ *         warning: 'bert_unavailable'}
+ *     -> NEVER throws on bridge failure
+ *
+ *   LSA bridge fails (python3 missing, sklearn import error, parse error)
+ *     -> {diff: null, lsa: null, bert: <bert>, passes: false,
+ *         warning: 'lsa_unavailable'}
+ *     -> Pessimistic: passes=false because LSA is the structural anchor;
+ *        without LSA the differential signal is unrecoverable.
+ *
+ * Canon Part 8 (Graph Boundary): two defense-in-depth layers.
+ *
+ *   Layer 1 -- pre-input scan: query_concept + doc_concept are passed
+ *     through auditQueryString BEFORE either bridge is called. On
+ *     FORBIDDEN_PATTERNS hit, throws ExternalEgressViolation; the bridges
+ *     are NEVER invoked (Tests 9 + 10 verify call counts == 0).
+ *
+ *   Layer 2 -- pre-return audit: composite output is passed through
+ *     auditQueryObject before return. Throws ExternalEgressViolation on
+ *     hit. Defense-in-depth so any forbidden pattern smuggled via the
+ *     bridge response (warning fields, error fields) is caught at the gate.
+ *
+ * Pure CJS, zero npm deps, node built-ins only beyond the rs-egress-* +
+ * rs-pinecone-bridge primitives.
+ */
+'use strict';
+
+const path = require('node:path');
+const childProcess = require('child_process');
+const { auditQueryString, auditQueryObject } = require('./rs-egress-prompts.cjs');
+const pineconeBridge = require('./rs-pinecone-bridge.cjs');
+// rs-egress-violations is required transitively by rs-egress-prompts; we do
+// not throw ExternalEgressViolation directly from this module (the audit
+// helpers do). The require below is a reachability witness for the audit chain.
+require('./rs-egress-violations.cjs');
+
+// ---------- Frozen invariants ----------
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PYTHON_BIN = process.env.MINDRIAN_PYTHON || 'python3';
+const LSA_BRIDGE_TIMEOUT_MS = 30000;
+
+// Dual-floor thresholds per kickoff §5. Strict > comparisons.
+const DIFF_FLOOR = 0.3;
+const LSA_FLOOR = 0.2;
+const BERT_FLOOR = 0.2;
+
+// ---------- Embedded Python LSA bridge script ----------
+//
+// CANON PART 7 CARVE-OUT (DELIBERATE, DOCUMENTED): see file header above
+// for the complete justification. In short:
+//   rs_math.py::build_tfidf_svd is corpus-level (Sequence[str] >= 3 docs);
+//   pair-wise (1 vs 1) cosine cannot consume that API without forcing
+//   degenerate IDF + SVD. The script below fits a fresh per-pair
+//   TfidfVectorizer + TruncatedSVD specifically for the pair-wise question.
+//
+// The leading `# BSL 1.1` line plus the carve-out justification block
+// constitute the Canon discipline marker on the embedded source surface
+// (W4 fix per Plan 89.2-06). Acceptance grep enforces presence in both
+// the CJS file header (above) AND this embedded Python block.
+
+const lsaBridgeScript = [
+  '# BSL 1.1',
+  '# Copyright (c) 2026 Mindrian. Phase 89.2 Plan 06 Task 3 -- pair-wise LSA cosine.',
+  '#',
+  '# CANON PART 7 CARVE-OUT (DELIBERATE, DOCUMENTED): This script computes',
+  '# pair-wise (1 vs 1) LSA cosine. It does NOT call rs_math.py because',
+  '# rs_math.py::build_tfidf_svd is corpus-level (Sequence[str] >= 3',
+  '# documents) and would produce degenerate IDF + SVD on a 2-document pair.',
+  '# The embedded sklearn subset below fits a fresh per-pair TfidfVectorizer',
+  '# + TruncatedSVD specifically for the pair-wise question, which is the',
+  '# algorithmically correct path. rs_math.py is consumed in CORPUS mode by',
+  '# scripts/rs-engine.py.',
+  '#',
+  '# Protocol:',
+  '#   stdin   JSON {a: string, b: string}',
+  '#   stdout  JSON {success: true, cosine: number} OR {success: false, error: string}',
+  'import sys, json',
+  'try:',
+  '    from sklearn.feature_extraction.text import TfidfVectorizer',
+  '    from sklearn.metrics.pairwise import cosine_similarity as sk_cos',
+  '    from sklearn.decomposition import TruncatedSVD',
+  '    payload = json.loads(sys.stdin.read())',
+  '    a = str(payload.get("a", ""))',
+  '    b = str(payload.get("b", ""))',
+  '    if len(a.strip()) == 0 or len(b.strip()) == 0:',
+  '        sys.stdout.write(json.dumps({"success": True, "cosine": 0.0}))',
+  '        sys.exit(0)',
+  '    texts = [a, b]',
+  '    vec = TfidfVectorizer(stop_words="english").fit_transform(texts)',
+  '    if vec.shape[1] < 2:',
+  '        sys.stdout.write(json.dumps({"success": True, "cosine": 0.0}))',
+  '        sys.exit(0)',
+  '    n_components = max(1, min(80, vec.shape[1] - 1, vec.shape[0] - 1))',
+  '    svd = TruncatedSVD(n_components=n_components, random_state=256).fit(vec)',
+  '    reduced = svd.transform(vec)',
+  '    c = float(sk_cos(reduced[0:1], reduced[1:2])[0][0])',
+  '    # Clamp to [0, 1] for downstream dual-floor consistency. Negative LSA',
+  '    # cosines arise on degenerate SVD bases and are not interpretable as',
+  '    # similarity in the Kwan 2023 framework.',
+  '    sys.stdout.write(json.dumps({"success": True, "cosine": max(0.0, c)}))',
+  'except Exception as e:',
+  '    sys.stdout.write(json.dumps({"success": False, "error": str(e)}))',
+  '',
+].join('\n');
+
+// ---------- computeLsaCosine ----------
+//
+// Spawns python3 with the embedded lsaBridgeScript, passes the two strings
+// via JSON-over-stdin, parses the response. Returns:
+//
+//   {success: true, cosine: number}
+//   {success: false, error: 'python_unavailable'|'python_exit_<N>'|'parse_error'|'timeout'|...}
+
+async function computeLsaCosine(a, b) {
+  const requestEnvelope = JSON.stringify({ a: a, b: b });
+  let res;
+  try {
+    res = childProcess.spawnSync(PYTHON_BIN, ['-c', lsaBridgeScript], {
+      input: requestEnvelope,
+      encoding: 'utf8',
+      timeout: LSA_BRIDGE_TIMEOUT_MS,
+      cwd: REPO_ROOT,
+    });
+  } catch (err) {
+    return { success: false, error: 'spawn_threw', detail: String(err && err.message) };
+  }
+
+  if (res && res.error) {
+    if (res.error.code === 'ENOENT') return { success: false, error: 'python_unavailable' };
+    if (res.error.code === 'ETIMEDOUT' || res.error.code === 'ERR_CHILD_PROCESS_TIMEOUT') {
+      return { success: false, error: 'timeout' };
+    }
+    return { success: false, error: 'spawn_error', detail: String(res.error.message) };
+  }
+
+  if (res && res.signal === 'SIGTERM') {
+    return { success: false, error: 'timeout' };
+  }
+
+  const stdout = (res && typeof res.stdout === 'string') ? res.stdout : '';
+  const stderr = (res && typeof res.stderr === 'string') ? res.stderr : '';
+
+  if (res && res.status !== 0) {
+    return {
+      success: false,
+      error: 'python_exit_' + res.status,
+      stderr: stderr.slice(0, 500),
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (_e) {
+    return { success: false, error: 'parse_error', stdout_sample: stdout.slice(0, 200) };
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    return { success: false, error: 'parse_error' };
+  }
+
+  if (parsed.success !== true) {
+    return { success: false, error: typeof parsed.error === 'string' ? parsed.error : 'bridge_error' };
+  }
+
+  if (typeof parsed.cosine !== 'number' || isNaN(parsed.cosine)) {
+    return { success: false, error: 'invalid_cosine' };
+  }
+
+  return { success: true, cosine: parsed.cosine };
+}
+
+// ---------- computeBertCosine ----------
+//
+// Twin queryPineconeWithVectors calls (one per concept), then pure-JS
+// cosineSimilarity on the resulting 1024-dim vectors. Returns:
+//
+//   {success: true, cosine: number}
+//   {success: false, error: 'namespace_required'|'bridge_failed'|'no_hits'|'shape_error'}
+
+async function computeBertCosine(a, b, namespace) {
+  if (typeof namespace !== 'string' || namespace.length === 0) {
+    return { success: false, error: 'namespace_required' };
+  }
+
+  const resA = await pineconeBridge.queryPineconeWithVectors(namespace, a, 1);
+  if (!resA || resA.success !== true) {
+    return { success: false, error: 'bridge_failed_a', detail: resA && resA.error };
+  }
+  const resB = await pineconeBridge.queryPineconeWithVectors(namespace, b, 1);
+  if (!resB || resB.success !== true) {
+    return { success: false, error: 'bridge_failed_b', detail: resB && resB.error };
+  }
+
+  if (!Array.isArray(resA.hits) || resA.hits.length === 0) {
+    return { success: false, error: 'no_hits_a' };
+  }
+  if (!Array.isArray(resB.hits) || resB.hits.length === 0) {
+    return { success: false, error: 'no_hits_b' };
+  }
+
+  const va = resA.hits[0] && resA.hits[0].values;
+  const vb = resB.hits[0] && resB.hits[0].values;
+  if (!Array.isArray(va) || !Array.isArray(vb)) {
+    return { success: false, error: 'shape_error' };
+  }
+  if (va.length !== vb.length || va.length === 0) {
+    return { success: false, error: 'dim_mismatch' };
+  }
+
+  const cos = pineconeBridge.cosineSimilarity(va, vb);
+  return { success: true, cosine: cos };
+}
+
+// ---------- score ----------
+//
+// Public entry point. Pair-wise dual-floor differential scorer.
+//
+// Inputs:
+//   query_concept  string  the concept seeded from preprocessor.concepts[]
+//   doc_concept    string  the candidate concept (cross-domain or same-domain)
+//   opts           optional:
+//     namespace      string  Pinecone namespace for BERT cosine (typically 'external:<topic-slug>')
+//
+// Output (happy path):
+//   {diff, lsa, bert, passes}
+//
+// Output (graceful degradation):
+//   {diff, lsa, bert: null, passes: lsa>0.2, warning: 'bert_unavailable'}
+//   {diff: null, lsa: null, bert, passes: false, warning: 'lsa_unavailable'}
+//
+// Throws (the only escape route -- Canon Part 8):
+//   ExternalEgressViolation  if either concept matches FORBIDDEN_PATTERNS
+
+async function score(query_concept, doc_concept, opts) {
+  // Canon Part 8 Layer 1: pre-input scan on user-controlled concepts.
+  // auditQueryString throws ExternalEgressViolation on hit; the bridges
+  // below are NEVER invoked when this throws. Tests 9 + 10 verify the
+  // call-count contract.
+  auditQueryString(typeof query_concept === 'string' ? query_concept : '', 'differential-scorer');
+  auditQueryString(typeof doc_concept === 'string' ? doc_concept : '', 'differential-scorer');
+
+  opts = opts || {};
+  const namespace = (typeof opts.namespace === 'string' && opts.namespace.length > 0)
+    ? opts.namespace
+    : null;
+
+  // Run both bridges in parallel. computeLsaCosine is cheap (single Python
+  // spawn); computeBertCosine spawns the Pinecone bridge twice. Promise.all
+  // means LSA does not block on BERT's spawnSync in the parallel mock-test
+  // case. Sequential await would be equivalent for correctness; parallel
+  // is the future-proofing for real Brain latency.
+  const [lsaResult, bertResult] = await Promise.all([
+    computeLsaCosine(query_concept, doc_concept),
+    computeBertCosine(query_concept, doc_concept, namespace),
+  ]);
+
+  let out;
+  if (lsaResult.success && bertResult.success) {
+    const lsa = lsaResult.cosine;
+    const bert = bertResult.cosine;
+    const diff = Math.abs(lsa - bert);
+    const passes = (diff > DIFF_FLOOR) && (lsa > LSA_FLOOR) && (bert > BERT_FLOOR);
+    out = { diff: diff, lsa: lsa, bert: bert, passes: passes };
+  } else if (lsaResult.success && !bertResult.success) {
+    // BERT unavailable: degrade to LSA-only. Per plan: bert=null, diff=lsa
+    // (treat as max divergence), passes=(lsa>LSA_FLOOR only since bert
+    // unavailable), warning='bert_unavailable'.
+    const lsa = lsaResult.cosine;
+    out = {
+      diff: lsa,
+      lsa: lsa,
+      bert: null,
+      passes: lsa > LSA_FLOOR,
+      warning: 'bert_unavailable',
+    };
+  } else {
+    // LSA failed (with or without BERT): pessimistic. Per plan: passes=false
+    // because LSA is the structural anchor; without LSA the differential
+    // signal is unrecoverable.
+    out = {
+      diff: null,
+      lsa: null,
+      bert: bertResult.success ? bertResult.cosine : null,
+      passes: false,
+      warning: 'lsa_unavailable',
+    };
+  }
+
+  // Canon Part 8 Layer 2: pre-return audit on composite output.
+  // Throws ExternalEgressViolation on any FORBIDDEN_PATTERNS hit.
+  auditQueryObject(out, 'differential-scorer');
+
+  return out;
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  score: score,
+  _test: {
+    DIFF_FLOOR: DIFF_FLOOR,
+    LSA_FLOOR: LSA_FLOOR,
+    BERT_FLOOR: BERT_FLOOR,
+    LSA_BRIDGE_TIMEOUT_MS: LSA_BRIDGE_TIMEOUT_MS,
+    PYTHON_BIN: PYTHON_BIN,
+    REPO_ROOT: REPO_ROOT,
+    computeLsaCosine: computeLsaCosine,
+    computeBertCosine: computeBertCosine,
+    lsaBridgeScript: lsaBridgeScript,
+  },
+};