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

package/lib/core/meter/gate-density-reader.cjs

@@ -0,0 +1,112 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 183-01 METER-01 -- the Gauge-1 invocation-density reader.
+ * ============================================================================
+ * A PURE reader over the Part 9 memory_event log. It answers the volume half of
+ * the v1.19 welded two-gauge metric: how often the intelligence fired this
+ * session (reaches / capability invocations per gate-reaching turn).
+ *
+ *   computeInvocationDensity(db, sinceEpochMs, roomState)
+ *     -> { gate_reaches, reach_presentations, framework_invocations,
+ *          density, denominator_unit }
+ *
+ * Density basis (Open Question 1, verified this phase): framework_invoked fires at
+ * ~ZERO production sites today (it is READ by _invocationsSinceDecision /
+ * computeInvestmentLevel but its emission is a deferred follow-on), so the density
+ * basis leans on the events that ACTUALLY fire -- reach_presented + gate_reached --
+ * and framework_invocations is carried as an ADDITIVE term that reads ~0 today.
+ *
+ * denominator_unit = 'gate_reached' (Open Question 2): the cleanest per-turn unit.
+ * Density is the invocation volume relative to the gate_reached denominator, so a
+ * downstream transfer-per-invocation reading divides by the same unit.
+ *
+ * Contract (mirrors lib/workflow/reach-reject-reader.cjs verbatim in shape):
+ *   - Opens NO db (caller-owned handle, the writeEdge / getRoomContext contract).
+ *   - Makes NO remote methodology call; reads ONLY via navigation.findRecentChanges
+ *     (the Part 9 chokepoint). Canon Part 8: enum/scalar reads only, no prose, no
+ *     egress; the run-all-183.sh grep-sweep proves zero network surface here.
+ *   - Prefers the roomState injection seam (roomState.<counter>) so the floor test
+ *     runs db-free.
+ *   - Returns a zeroed cold-start object on a null db / read fault; NEVER throws.
+ *
+ * Scope fence (T-183-04): this module is Gauge 1 ONLY. It must NOT be the surface a
+ * caller uses to read density in isolation downstream -- Plan 02's welded two-gauge
+ * read (lib/core/meter/two-gauge.cjs) is the only sanctioned read path. There is no
+ * exported bare-density function returning a number; computeInvocationDensity always
+ * returns the full count object with the denominator unit named, never a lone scalar.
+ *
+ * House rule: hyphens only, no em-dashes.
+ */
+
+const navigation = require('../navigation.cjs');
+
+const DENOMINATOR_UNIT = 'gate_reached';
+const READ_LIMIT = 1000;
+
+// Injection seam: returns roomState[key] when it is a finite number (the db-free
+// test path), else null so the db read path runs. Mirrors the
+// reach-reject-reader.cjs::_injected pre-computed-counter guard.
+function _injected(roomState, key) {
+  if (roomState
+      && typeof roomState[key] === 'number'
+      && Number.isFinite(roomState[key])) {
+    return roomState[key];
+  }
+  return null;
+}
+
+// Count memory_event rows of a single eventType via the Part 9 chokepoint. Returns
+// 0 on a null db or any read fault (never throws). Enum/scalar read only.
+function _countEvent(db, sinceEpochMs, eventType) {
+  if (!db) return 0;
+  let rows;
+  try {
+    rows = navigation.findRecentChanges(db, sinceEpochMs || 0, {
+      eventType: eventType,
+      limit: READ_LIMIT,
+    });
+  } catch (_err) {
+    return 0;
+  }
+  return Array.isArray(rows) ? rows.length : 0;
+}
+
+// Resolve one counter, preferring the injected roomState value, else the db count.
+function _counter(db, sinceEpochMs, roomState, key, eventType) {
+  const injected = _injected(roomState, key);
+  if (injected !== null) return injected;
+  return _countEvent(db, sinceEpochMs, eventType);
+}
+
+// ---------------------------------------------------------------------------
+// computeInvocationDensity(db, sinceEpochMs, roomState)
+//   -> { gate_reaches, reach_presentations, framework_invocations,
+//        density, denominator_unit }
+//
+// gate_reaches        COUNT(memory_event gate_reached)   -- the per-turn denominator
+// reach_presentations COUNT(memory_event reach_presented) -- a firing
+// framework_invocations COUNT(memory_event framework_invoked) -- additive, ~0 today
+// density             (reach_presentations + framework_invocations) / gate_reaches
+//                     guarded so cold-start (gate_reaches === 0) density is 0.
+// denominator_unit    the string 'gate_reached'.
+// ---------------------------------------------------------------------------
+function computeInvocationDensity(db, sinceEpochMs, roomState) {
+  const gate_reaches = _counter(db, sinceEpochMs, roomState, 'gate_reaches', 'gate_reached');
+  const reach_presentations = _counter(db, sinceEpochMs, roomState, 'reach_presentations', 'reach_presented');
+  const framework_invocations = _counter(db, sinceEpochMs, roomState, 'framework_invocations', 'framework_invoked');
+
+  const invocation_volume = reach_presentations + framework_invocations;
+  const density = gate_reaches > 0 ? (invocation_volume / gate_reaches) : 0;
+
+  return {
+    gate_reaches: gate_reaches,
+    reach_presentations: reach_presentations,
+    framework_invocations: framework_invocations,
+    density: density,
+    denominator_unit: DENOMINATOR_UNIT,
+  };
+}
+
+module.exports = { computeInvocationDensity };

package/lib/core/meter/transfer-reader.cjs

@@ -0,0 +1,276 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 183-02 METER-02 -- the Gauge-2 SOURCE: three NAMED-DEBT transfer proxies.
+ * ============================================================================
+ * HONESTY HEADER (Canon Part 5 / Appendix D entries 28 + 31). None of the three
+ * readers below is a real transfer DELTA. A real transfer measurement is a
+ * novel-problem-solving delta against a DEFINED baseline (a thing METER cannot
+ * produce -- there is no RCT here). These three are NAMED-DEBT proxies: they are
+ * the INSTRUMENT (the Gauge-2 SOURCE) that Phase 184 READER's R1 A/B test and a
+ * future real measurement consume, NOT a finished transfer measurement. An
+ * engagement / capture / latency / independence proxy that masquerades as a
+ * transfer delta is a canon breach (Part 5). So every reader stamps its return
+ * with proxy_class: 'named-debt', and this module NEVER claims to "measure
+ * transfer" -- it instruments the Gauge-2 source.
+ *
+ *   rejectReasonCaptureRate(db, sinceEpochMs, roomState)
+ *     -> { reject_total, reject_with_reason, capture_rate, proxy_class:'named-debt' }
+ *   insightToDecisionLatency / insightToValidatedDecisionLatency(db, sinceEpochMs, roomState)
+ *     -> { sample_count, median_latency_ms, proxy_class:'named-debt' }
+ *   independenceTrend(db, sinceEpochMs, roomState)
+ *     -> { direction, delta, proxy_class:'named-debt', caveat }
+ *
+ * Contract (mirrors lib/workflow/reach-reject-reader.cjs + the Plan-01
+ * gate-density-reader.cjs verbatim in shape):
+ *   - Opens NO db (caller-owned handle). Makes NO remote / Brain call; reads ONLY
+ *     via navigation.findRecentChanges (the Part 9 chokepoint). Canon Part 8:
+ *     enum/scalar reads only; the run-all-183.sh grep-sweep proves zero network
+ *     surface here.
+ *   - rejectReasonCaptureRate reads the PRESENCE/absence of the reject reason field
+ *     (properties.reason) ONLY -- the reason STRING is NEVER echoed into a returned
+ *     field (Part 8 / T-183-02). Decision 13 "rejection is data": a captured reason
+ *     is a data-quality signal on the instrument, NOT a transfer quality delta.
+ *   - Prefers the roomState injection seam so the floor tests run db-free.
+ *   - Returns a cold-start object (capture_rate null / sample_count 0 / direction
+ *     flat) on a null db / read fault; NEVER throws, NEVER divides by zero.
+ *
+ * Production note (honest): f_selector_decision is not yet written from the dial in
+ * production (ROADMAP:2846), so the reject-capture denominator cold-starts
+ * structurally EMPTY on most rooms today. That is the correct and honest reading,
+ * NOT a fault -- and it is exactly why the welded read (two-gauge.cjs) reports a
+ * transfer_uninstrumented state distinct from a flat reading.
+ *
+ * House rule: hyphens only, no em-dashes.
+ */
+
+const navigation = require('../navigation.cjs');
+
+const READ_LIMIT = 1000;
+const PROXY_CLASS = 'named-debt';
+
+// Insight events the latency proxy pairs FROM (the insight surfaced) to the next
+// status_promoted (the human-confirmed validated decision, Part 9 role 5 -- the
+// canonical latency end-event per Open Question 3).
+const INSIGHT_EVENT_TYPES = Object.freeze(['reach_presented', 'auto_explore_finding_surfaced']);
+const VALIDATED_DECISION_EVENT = 'status_promoted';
+
+// Injection seam: returns roomState[key] when it is a finite number (the db-free
+// test path), else null so the db read path runs. Mirrors the
+// reach-reject-reader.cjs::_injected pre-computed-counter guard.
+function _injectedNumber(roomState, key) {
+  if (roomState
+      && typeof roomState[key] === 'number'
+      && Number.isFinite(roomState[key])) {
+    return roomState[key];
+  }
+  return null;
+}
+
+// Read memory_event rows of one eventType via the Part 9 chokepoint. Returns [] on a
+// null db or any read fault (never throws). Enum/scalar read only.
+function _read(db, sinceEpochMs, eventType) {
+  if (!db) return [];
+  let rows;
+  try {
+    rows = navigation.findRecentChanges(db, sinceEpochMs || 0, {
+      eventType: eventType,
+      limit: READ_LIMIT,
+    });
+  } catch (_err) {
+    return [];
+  }
+  return Array.isArray(rows) ? rows : [];
+}
+
+// A f_selector_decision row is a REJECT only when decision === 'reject' OR
+// edge_semantic === 'REJECTED' (mirror reach-reject-reader.cjs::_isRejectRow). Read
+// enums ONLY.
+function _isRejectRow(props) {
+  if (!props || typeof props !== 'object') return false;
+  return props.decision === 'reject' || props.edge_semantic === 'REJECTED';
+}
+
+// Presence check on the reject reason field. Reads whether properties.reason is a
+// non-empty string -- NEVER the value. The local var is named `val` (not `reason`)
+// precisely so the source carries no `reason ===` / `reason !==` echo of the value
+// into any returned field (Part 8 / T-183-02). Capture-rate reads presence only.
+function _hasReason(props) {
+  if (!props || typeof props !== 'object') return false;
+  const val = props.reason; // reads properties.reason for PRESENCE only
+  return typeof val === 'string' && val.trim().length > 0;
+}
+
+// ---------------------------------------------------------------------------
+// rejectReasonCaptureRate(db, sinceEpochMs, roomState)
+//   -> { reject_total, reject_with_reason, capture_rate, proxy_class:'named-debt' }
+//
+// capture_rate = COUNT(reject AND reason present) / COUNT(reject), or null on zero
+// reject rows (cold-start; NEVER a divide-by-zero, NEVER a throw). NAMED-DEBT: a
+// data-quality signal on the transfer instrument (does the navigator capture WHY on
+// a reject -- Decision 13 / Part 4 REJECTED_BECAUSE), NOT a transfer delta.
+// ---------------------------------------------------------------------------
+function rejectReasonCaptureRate(db, sinceEpochMs, roomState) {
+  const injTotal = _injectedNumber(roomState, 'reject_total');
+  const injWith = _injectedNumber(roomState, 'reject_with_reason');
+  if (injTotal !== null && injWith !== null) {
+    return {
+      reject_total: injTotal,
+      reject_with_reason: injWith,
+      capture_rate: injTotal > 0 ? (injWith / injTotal) : null,
+      proxy_class: PROXY_CLASS,
+    };
+  }
+
+  const rows = _read(db, sinceEpochMs, 'f_selector_decision');
+  let reject_total = 0;
+  let reject_with_reason = 0;
+  for (const row of rows) {
+    const props = row && row.properties;
+    if (_isRejectRow(props)) {
+      reject_total += 1;
+      if (_hasReason(props)) reject_with_reason += 1;
+    }
+  }
+  return {
+    reject_total: reject_total,
+    reject_with_reason: reject_with_reason,
+    capture_rate: reject_total > 0 ? (reject_with_reason / reject_total) : null,
+    proxy_class: PROXY_CLASS,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// insightToValidatedDecisionLatency(db, sinceEpochMs, roomState)
+//   -> { sample_count, median_latency_ms, proxy_class:'named-debt' }
+//
+// Pairs each insight event createdAt (reach_presented / auto_explore_finding_surfaced)
+// to the NEXT status_promoted createdAt strictly after it, and reports the median of
+// those latencies. Cold-starts to sample_count 0 / median null when no pair exists.
+// NAMED-DEBT: a SPEED proxy aligned with the JTBD core job ("compress time between
+// insight and validated decision"), NOT a novel-problem-solving delta. A faster
+// insight->decision loop is not itself transfer.
+// ---------------------------------------------------------------------------
+function insightToValidatedDecisionLatency(db, sinceEpochMs, roomState) {
+  const injCount = _injectedNumber(roomState, 'latency_sample_count');
+  const injMedian = _injectedNumber(roomState, 'latency_median_ms');
+  if (injCount !== null) {
+    return {
+      sample_count: injCount,
+      median_latency_ms: injCount > 0 && injMedian !== null ? injMedian : null,
+      proxy_class: PROXY_CLASS,
+    };
+  }
+
+  // Validated-decision timestamps, ascending.
+  const decisions = _read(db, sinceEpochMs, VALIDATED_DECISION_EVENT)
+    .map((r) => (r && typeof r.createdAt === 'number') ? r.createdAt : null)
+    .filter((t) => t !== null)
+    .sort((a, b) => a - b);
+
+  // Insight timestamps, ascending.
+  let insights = [];
+  for (const et of INSIGHT_EVENT_TYPES) {
+    for (const r of _read(db, sinceEpochMs, et)) {
+      if (r && typeof r.createdAt === 'number') insights.push(r.createdAt);
+    }
+  }
+  insights = insights.sort((a, b) => a - b);
+
+  const latencies = [];
+  for (const ins of insights) {
+    // the next validated decision strictly after this insight.
+    let next = null;
+    for (const d of decisions) {
+      if (d > ins) { next = d; break; }
+    }
+    if (next !== null) latencies.push(next - ins);
+  }
+
+  if (latencies.length === 0) {
+    return { sample_count: 0, median_latency_ms: null, proxy_class: PROXY_CLASS };
+  }
+  latencies.sort((a, b) => a - b);
+  const mid = Math.floor(latencies.length / 2);
+  const median = latencies.length % 2 === 1
+    ? latencies[mid]
+    : (latencies[mid - 1] + latencies[mid]) / 2;
+  return {
+    sample_count: latencies.length,
+    median_latency_ms: median,
+    proxy_class: PROXY_CLASS,
+  };
+}
+
+// Plan-contract alias: the artifacts list names this insightToValidatedDecisionLatency
+// while the floor pin imports insightToDecisionLatency. Export BOTH names for the one
+// reader so neither contract drifts.
+const insightToDecisionLatency = insightToValidatedDecisionLatency;
+
+// ---------------------------------------------------------------------------
+// independenceTrend(db, sinceEpochMs, roomState)
+//   -> { direction, delta, proxy_class:'named-debt', caveat }
+//
+// Per-cycle delta of the invocation-density basis (reach_presented + framework_invoked
+// firings -- the same basis the Plan-01 gate-density-reader counts). The window is
+// split at its time midpoint into an OLDER half and a NEWER half; delta = newer - older;
+// direction is rising | falling | flat. Cold-starts to direction 'flat' / delta 0.
+//
+// AMBIGUITY FLAG (Part 5, explicit and load-bearing): the direction is NOT
+// self-interpreting. Falling invocation density could mean the navigator INTERNALIZED
+// the method (a transfer-like good signal) OR DISENGAGED (an anti-signal). These are
+// un-disambiguable LOCALLY, so independenceTrend is reported as a trend scalar with the
+// caveat string below and is NEVER read as a transfer delta on its own.
+// ---------------------------------------------------------------------------
+function independenceTrend(db, sinceEpochMs, roomState) {
+  const CAVEAT = 'direction is not self-interpreting: falling density may mean the '
+    + 'navigator internalized the method (transfer-like) OR disengaged (anti-signal); '
+    + 'un-disambiguable locally -- never read as a transfer delta.';
+
+  const injDelta = _injectedNumber(roomState, 'independence_delta');
+  if (injDelta !== null) {
+    return {
+      direction: injDelta > 0 ? 'rising' : (injDelta < 0 ? 'falling' : 'flat'),
+      delta: injDelta,
+      proxy_class: PROXY_CLASS,
+      caveat: CAVEAT,
+    };
+  }
+
+  // Collect the invocation-basis firing timestamps across the window.
+  let ts = [];
+  for (const et of ['reach_presented', 'framework_invoked']) {
+    for (const r of _read(db, sinceEpochMs, et)) {
+      if (r && typeof r.createdAt === 'number') ts.push(r.createdAt);
+    }
+  }
+  if (ts.length === 0) {
+    return { direction: 'flat', delta: 0, proxy_class: PROXY_CLASS, caveat: CAVEAT };
+  }
+  ts = ts.sort((a, b) => a - b);
+  const lo = ts[0];
+  const hi = ts[ts.length - 1];
+  const mid = lo + (hi - lo) / 2;
+  let older = 0;
+  let newer = 0;
+  for (const t of ts) {
+    if (t <= mid) older += 1; else newer += 1;
+  }
+  const delta = newer - older;
+  return {
+    direction: delta > 0 ? 'rising' : (delta < 0 ? 'falling' : 'flat'),
+    delta: delta,
+    proxy_class: PROXY_CLASS,
+    caveat: CAVEAT,
+  };
+}
+
+module.exports = {
+  rejectReasonCaptureRate,
+  insightToValidatedDecisionLatency,
+  insightToDecisionLatency,
+  independenceTrend,
+  INSIGHT_EVENT_TYPES,
+  VALIDATED_DECISION_EVENT,
+};

package/lib/core/meter/two-gauge.cjs

@@ -0,0 +1,245 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 183-02 METER-01+02 -- the WELDED two-gauge read (Canon Part 5, Appendix D
+ * entry 31; the v1.19 headline product metric instrumented at the telemetry layer).
+ * ============================================================================
+ * readTwoGauge(db, sinceEpochMs, roomState) computes Gauge 1 (invocation density,
+ * the VOLUME reading) AND Gauge 2 (the named-debt transfer SOURCE, the QUALITY
+ * reading) in the SAME call and returns them welded in ONE frozen object. A caller
+ * CANNOT obtain density without the transfer slot beside it: there is NO exported
+ * function whose return type is a bare density number, and the assembled object is
+ * asserted to carry the transfer slot before it is frozen (it THROWS on a genuine
+ * welded-contract violation). This is the canon's "invocation density is structurally
+ * un-reportable without the transfer denominator beside it -- welded, not a clause".
+ *
+ * THREE outcomes (CORRECTION B -- not just "pair or throw"):
+ *   (1) the welded PAIR when the transfer substrate exists  -> transfer_state 'measured'
+ *   (2) the pair with transfer=null when the substrate is EMPTY -> transfer_state
+ *       'uninstrumented' (NEVER a flat/zero transfer value). The f_selector_decision
+ *       substrate is unwritten-from-the-dial in production today (ROADMAP:2846), so the
+ *       transfer/reject-capture denominator cold-starts structurally EMPTY on most
+ *       rooms -- that is honest, and it MUST read as uninstrumented, not flat.
+ *   (3) THROW if a caller assembles a bare density without the transfer slot present.
+ *
+ * The two-directional regression guard (D-180-02). The read returns BOTH a
+ * volume_direction and a quality_direction; the verdict names BOTH single-direction
+ * failures as regressions, never as a win:
+ *   - win                = volume up AND quality holds-or-climbs.
+ *   - regression_dealer  = volume-up-quality-flat (the Hooked Dealer quadrant -- more
+ *                          reaches that teach nothing).
+ *   - regression_starved = quality-up-by-starving-volume (the virtuous-looking inverse
+ *                          that buys a higher per-invocation number by suppressing the
+ *                          reaches themselves).
+ *   - flat               = neither direction moves.
+ *   - transfer_uninstrumented = the transfer substrate is EMPTY. This is a
+ *                          DISTINCT state from flat: uninstrumented is NOT the Hooked
+ *                          Dealer regression and NOT the starving-volume inverse -- it
+ *                          is no-instrument, which licenses NO regression verdict at all.
+ *                          A welded metric that cannot tell "no quality" from
+ *                          "no instrument" is blindfolded.
+ *
+ * Honest-default note: METER is the Gauge-2 SOURCE over NAMED-DEBT proxies, NOT a
+ * finished transfer measurement. A real transfer CLIMB needs a Part-5 baseline
+ * (a novel-problem delta) that METER cannot produce, so quality_direction defaults to
+ * 'flat' for a measured reading -- the meter REFUSES to declare a win without a real
+ * transfer delta beside it (the structural anti-engagement-machine guard). Phase 184
+ * READER's R1 A/B test supplies the real quality direction.
+ *
+ * Contract: opens NO db (caller-owned handle); makes NO Brain / network call; imports
+ * NO packet.cjs and no Brain client module. Reads ONLY through the two shipped meter
+ * readers (which read via the Part 9 navigation chokepoint). Canon Part 8: the
+ * run-all-183.sh grep-sweep proves zero network surface here. House rule: hyphens only,
+ * no em-dashes.
+ */
+
+const crypto = require('node:crypto');
+const gateDensity = require('./gate-density-reader.cjs');
+const transferReader = require('./transfer-reader.cjs');
+
+// The active-key resolver (Part-8-clean: reads LOCAL env/files only, zero network).
+// Loaded defensively so a meter read never hard-fails on a resolver hiccup.
+let _resolveBrainKey = null;
+try {
+  _resolveBrainKey = require('../resolve-brain-key.cjs').resolveBrainKey;
+} catch (_e) {
+  _resolveBrainKey = null;
+}
+
+// CORRECTION A -- subject_class enum. Only subject_class==navigator satisfies the
+// entry-31 self-binding-clause precondition. A maintainer reading proves the
+// instrument FIRES; it does NOT clear the self-bind. This is the structural guard
+// against an entry-20-style override (a maintainer reading, the ~1287-request
+// dogfooding key, masquerading as the navigator reading the clause named).
+const SUBJECT_CLASS = Object.freeze({
+  MAINTAINER: 'maintainer',
+  NAVIGATOR: 'navigator',
+  UNKNOWN: 'unknown',
+});
+const SUBJECT_CLASS_VALUES = Object.freeze([
+  SUBJECT_CLASS.MAINTAINER, SUBJECT_CLASS.NAVIGATOR, SUBJECT_CLASS.UNKNOWN,
+]);
+
+const TRANSFER_STATE = Object.freeze({ MEASURED: 'measured', UNINSTRUMENTED: 'uninstrumented' });
+
+const VERDICT = Object.freeze({
+  WIN: 'win',
+  REGRESSION_DEALER: 'regression_dealer',
+  REGRESSION_STARVED: 'regression_starved',
+  FLAT: 'flat',
+  TRANSFER_UNINSTRUMENTED: 'transfer_uninstrumented',
+});
+
+// The maintainer-key fingerprint seam. The navigator sets MINDRIAN_MAINTAINER_KEY_SHA256
+// on the maintainer box to the sha256 HEX of the maintainer (dogfooding) Brain key. We
+// NEVER store or egress the key itself -- only a one-way fingerprint to compare against
+// (Part 8). Returns the lowercased 64-hex string or null when unset/malformed.
+function _maintainerFingerprint() {
+  const fp = process.env.MINDRIAN_MAINTAINER_KEY_SHA256;
+  if (typeof fp === 'string' && /^[0-9a-f]{64}$/i.test(fp.trim())) {
+    return fp.trim().toLowerCase();
+  }
+  return null;
+}
+
+// Derive subject_class AT READ TIME, Part-8-clean: a derived scalar enum, NEVER the
+// key, NEVER a user identifier. Precedence:
+//   1. MINDRIAN_DOGFOOD_ROOM_DIR set  -> 'maintainer' (the EXISTING maintainer/dogfood-box
+//      marker; the maintainer's own dogfooding reads are stamped maintainer).
+//   2. a maintainer fingerprint is configured AND the active key's sha256 matches
+//      -> 'maintainer' (positive maintainer match).
+//   3. a maintainer fingerprint is configured AND an active key is present but does NOT
+//      match -> 'navigator' (positively a non-maintainer keyed live turn).
+//   4. otherwise -> 'unknown'. We do NOT guess 'navigator' when no maintainer signal is
+//      resolvable: without a reference we cannot prove a reading is not the maintainer's
+//      (the entry-31 enum's correctness is load-bearing, so 'unknown' is the honest
+//      default, never a fragile guess).
+function _deriveSubjectClass() {
+  if (typeof process.env.MINDRIAN_DOGFOOD_ROOM_DIR === 'string'
+      && process.env.MINDRIAN_DOGFOOD_ROOM_DIR.trim().length > 0) {
+    return SUBJECT_CLASS.MAINTAINER;
+  }
+  const fp = _maintainerFingerprint();
+  if (!fp) return SUBJECT_CLASS.UNKNOWN; // no maintainer signal -> never guess navigator
+  let active = null;
+  try {
+    active = _resolveBrainKey ? _resolveBrainKey() : null;
+  } catch (_e) {
+    active = null;
+  }
+  if (!active || active.available !== true
+      || typeof active.key !== 'string' || active.key.length === 0) {
+    return SUBJECT_CLASS.UNKNOWN; // no active key -> cannot classify
+  }
+  let activeFp;
+  try {
+    activeFp = crypto.createHash('sha256').update(active.key, 'utf8').digest('hex');
+  } catch (_e) {
+    return SUBJECT_CLASS.UNKNOWN;
+  }
+  if (activeFp === fp) return SUBJECT_CLASS.MAINTAINER; // positive maintainer match
+  return SUBJECT_CLASS.NAVIGATOR; // positively a non-maintainer keyed live turn
+}
+
+// Map the per-cycle independence trend (rising | falling | flat) to a volume direction.
+function _volumeDirection(trend) {
+  const d = trend && trend.direction;
+  if (d === 'rising') return 'up';
+  if (d === 'falling') return 'down';
+  return 'flat';
+}
+
+// ---------------------------------------------------------------------------
+// readTwoGauge(db, sinceEpochMs, roomState)
+//   -> frozen {
+//        gauge1, gauge2, gauge1_density, gauge2_transfer, density, transfer,
+//        transfer_state, subject_class, volume_direction, quality_direction, verdict
+//      }
+//
+// gauge1 / gauge1_density / density : the Gauge-1 invocation-density reading (object)
+//                                     and its density scalar (the VOLUME half).
+// gauge2 / gauge2_transfer / transfer: the Gauge-2 named-debt transfer reading (object),
+//                                     or null when the transfer substrate is EMPTY.
+// transfer_state                    : 'measured' | 'uninstrumented'.
+// subject_class                     : 'maintainer' | 'navigator' | 'unknown' (CORRECTION A).
+// volume_direction / quality_direction / verdict : the two-directional regression guard.
+//
+// Returns the pair welded together or THROWS; there is NO bare-density path.
+// ---------------------------------------------------------------------------
+function readTwoGauge(db, sinceEpochMs, roomState) {
+  const since = (typeof sinceEpochMs === 'number' && Number.isFinite(sinceEpochMs)) ? sinceEpochMs : 0;
+
+  // Gauge 1 -- the volume reading.
+  const density = gateDensity.computeInvocationDensity(db, since, roomState);
+
+  // Gauge 2 source -- the three named-debt transfer proxies.
+  const capture = transferReader.rejectReasonCaptureRate(db, since, roomState);
+  const latency = transferReader.insightToValidatedDecisionLatency(db, since, roomState);
+  const independence = transferReader.independenceTrend(db, since, roomState);
+
+  // The transfer substrate is 'measured' only when there is at least one transfer data
+  // point (a reject-capture row OR an insight->validated-decision latency pair). When
+  // the denominator is structurally EMPTY it is 'uninstrumented', NOT flat -- a distinct
+  // third state (CORRECTION B).
+  const reject_total = (capture && typeof capture.reject_total === 'number') ? capture.reject_total : 0;
+  const sample_count = (latency && typeof latency.sample_count === 'number') ? latency.sample_count : 0;
+  const measured = reject_total > 0 || sample_count > 0;
+  const transfer_state = measured ? TRANSFER_STATE.MEASURED : TRANSFER_STATE.UNINSTRUMENTED;
+
+  const transfer = measured
+    ? Object.freeze({
+        reject_reason_capture: capture,
+        insight_to_validated_decision_latency: latency,
+        independence_trend: independence,
+        proxy_class: 'named-debt',
+      })
+    : null; // EMPTY substrate -> null, never a fabricated zero (CORRECTION B)
+
+  const volume_direction = _volumeDirection(independence);
+
+  // quality_direction: 'uninstrumented' when there is no transfer instrument; else
+  // defaults to 'flat' -- METER cannot prove a transfer CLIMB without a Part-5 baseline,
+  // so it never claims a win on the named-debt proxies alone (Phase 184 READER supplies
+  // the real direction).
+  const quality_direction = measured ? 'flat' : 'uninstrumented';
+
+  // The two-directional guard. uninstrumented licenses NO regression verdict.
+  let verdict;
+  if (!measured) {
+    verdict = VERDICT.TRANSFER_UNINSTRUMENTED;
+  } else if (volume_direction === 'up' && (quality_direction === 'up' || quality_direction === 'climbs')) {
+    verdict = VERDICT.WIN; // volume up AND quality holds-or-climbs
+  } else if (volume_direction === 'up' && quality_direction === 'flat') {
+    verdict = VERDICT.REGRESSION_DEALER; // volume-up-quality-flat (Hooked Dealer)
+  } else if (volume_direction === 'down' && quality_direction === 'up') {
+    verdict = VERDICT.REGRESSION_STARVED; // quality-up-by-starving-volume
+  } else {
+    verdict = VERDICT.FLAT;
+  }
+
+  const out = {
+    gauge1: density,
+    gauge2: transfer,
+    gauge1_density: density && typeof density.density === 'number' ? density.density : 0,
+    gauge2_transfer: transfer,
+    density: density && typeof density.density === 'number' ? density.density : 0,
+    transfer: transfer,
+    transfer_state: transfer_state,
+    subject_class: _deriveSubjectClass(),
+    volume_direction: volume_direction,
+    quality_direction: quality_direction,
+    verdict: verdict,
+  };
+
+  // Structural weld assertion (CORRECTION B outcome 3): the density is un-returnable
+  // without the transfer slot present in the same object. THROW on a genuine
+  // welded-contract violation rather than ever yielding a lone density.
+  if (!('transfer' in out) || !('gauge1_density' in out)) {
+    throw new Error('unwelded_density: readTwoGauge refuses to return a density without the transfer slot beside it');
+  }
+
+  return Object.freeze(out);
+}
+
+module.exports = { readTwoGauge };