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

package/lib/core/sensors/sensor-show-share.cjs

@@ -0,0 +1,215 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * SENS-SHOW -- the "show my work" show/present/share-intent detector (Phase 173 R4).
+ *
+ * Surfaces a context_block candidate reach naming the /mos:show JTBD
+ * need-selector front door (commands/show.md, 173-02) when the LOCAL turn shows
+ * a show/present/share intent. The selector then asks the navigator their JOB in
+ * plain language and resolves it to the right visual/publish command underneath
+ * (via the Phase 122 command-resolver + the Phase 166 runChain handoff). This
+ * sensor is the "does the navigator want to show their work?" gate -- the trigger
+ * IS the discoverability surface (the selector is invokable, not typed-only).
+ *
+ * D-03 (173-CONTEXT, navigator-LOCKED): the reach is a STANDING SUGGESTION at the
+ * Decision Gate (posture 'hold' -- Canon Part 3 GUIDED default, the "no card
+ * unprompted" doctrine); it NEVER auto-opens UI. It REUSES the existing
+ * context_block reach -- NO 7th reach is minted (mirrors SENS-09 reusing
+ * brain_consult; CIRS R3 / Part 3 the 6-reach bank is frozen).
+ *
+ * FIRES on ANY of (in CANON PART 11 R3 precedence order -- CONTEXT first,
+ * keyword DEMOTED to fallback; navigator decision D-03):
+ *   1. SIGNAL MODE  -- an explicit 'show_share_intent' signal on the turn (the
+ *      strongest tier), OR
+ *   2. CONTEXT MODE -- the LOCAL navigator PROBLEM-STATE indicates a show/share
+ *      shape: tuple.problem_type matches the generic show/share problem-type
+ *      allow-list, OR the navigation.cjs chokepoint populated a problem-state
+ *      enum (stage / jtbd / graph_gap). This is the PRIMARY branch (R3 / INV-07):
+ *      the trigger keys on problem-state read LOCALLY via the chokepoint
+ *      convention, enum/scalar only (Part 8/9), NOT on a keyword scan. OR
+ *   3. KEYWORD MODE -- the LOCAL turn text contains a show/share lexicon term
+ *      (the DEMOTED fallback tier -- fires ONLY when no problem-state context is
+ *      present).
+ *
+ * CANON PART 8: the sensor reads ONLY LOCAL bytes (the turn text, the diagnose
+ * tuple/ctx enums the chokepoint populated) to DECIDE firing; it makes NO Brain
+ * call and NO network call. The reach carries ONLY generic handles: dispatch
+ * 'show-jtbd-selector' (the WFL-01 / command-resolver handle the orchestrator
+ * routes to /mos:show, a selector front door -- NOT a Brain framework, so it does
+ * NOT enter data/dispatch-framework-map.json; it resolves through the
+ * command-resolver path, keeping tests/test-dispatch-framework-map-drift.cjs
+ * green). evidence is a flat scalar/enum bag (the fire MODE enum + the trigger
+ * TIER enum + the problem_type enum) -- never the user's matched text. The
+ * lexicon terms + the show/share problem-type allow-list are OUR fixed generic
+ * vocabulary, never user content.
+ *
+ * R12 CROSS-SURFACE TRI-POLAR CONTRACT (the documented note):
+ *   The AskUserQuestion selector /mos:show renders is IDENTICAL across CLI /
+ *   Desktop / Cowork (the host owns the keymap; the phase owns the two axes --
+ *   SEED-020, no custom TUI). The rendered RESULTS degrade per the shipped
+ *   3-layer model: the inline ui:// views (dashboard / wiki / graph, already
+ *   shipped in lib/mcp/app-views.cjs) render where Node cannot run (Desktop /
+ *   Cowork); a Node-only result (present / export / snapshot / radar) requested
+ *   on Desktop / Cowork surfaces an EXPLICIT degradation note (never a silent
+ *   failure) telling the navigator the result is CLI-only. The selector and this
+ *   trigger are surface-agnostic; only the result RENDER target differs.
+ *
+ * Phase 144 fence: this file PRODUCES a candidate reach; it never assigns
+ * routing_source and never requires/defines decide().
+ *
+ * Pure / sync / LOCAL-first; soft-fail to null; never throws. node built-ins +
+ * sensor-types only. No new deps. House rule: hyphens only, no em-dashes.
+ */
+
+const {
+  makeReach,
+  // Phase 172-07 (R3 / INV-07): the trigger-tier seam. classifyTriggerTier reads
+  // the LOCAL problem-state enum (stage / jtbd / graph_gap) off the tuple+ctx the
+  // navigation.cjs chokepoint populated, applying the context-first /
+  // keyword-fallback precedence. Adds NO filesystem / Brain read.
+  classifyTriggerTier,
+} = require('./sensor-types.cjs');
+
+/**
+ * The show/share lexicon. OUR fixed generic vocabulary -- the words that mean
+ * "the navigator wants to show / present / share / publish their work". Generic
+ * handles, NOT user content. A LOCAL turn-text hit on any term means "this looks
+ * like a show-my-work intent" and surfaces the /mos:show selector.
+ */
+const SHOW_SHARE_LEXICON = [
+  'show', 'present', 'share', 'send a link', 'pitch', 'make it land',
+  'publish', 'visualize', 'visualise',
+];
+
+/**
+ * The show/share PROBLEM-TYPE allow-list. OUR fixed generic vocabulary of the
+ * /mos:diagnose problem_type enum values that denote a show/present/share shape.
+ * A tuple.problem_type hit on any of these means the NAVIGATOR PROBLEM-STATE --
+ * not a keyword in the prose -- says "this is a show-my-work moment," so the
+ * CONTEXT branch fires (R3 primary). Generic enum handles, NEVER user content.
+ */
+const SHOW_SHARE_PROBLEM_TYPES = [
+  'show', 'present', 'share', 'publish', 'visualize', 'communicate',
+  'show-work', 'show_work', 'present-deck', 'present_deck',
+];
+
+/**
+ * SIGNAL MODE -- true if the turn carries an explicit 'show_share_intent' signal
+ * (string or { kind }). Defensive; never throws.
+ */
+function hasShowShareSignal(turn) {
+  if (!turn || typeof turn !== 'object') return false;
+  const signals = Array.isArray(turn.signals) ? turn.signals : [];
+  for (const s of signals) {
+    const kind = (typeof s === 'string') ? s : (s && typeof s === 'object' ? s.kind : '');
+    if (kind === 'show_share_intent') return true;
+  }
+  return false;
+}
+
+/**
+ * KEYWORD MODE -- returns the matched lexicon term (OUR generic vocabulary) if
+ * the LOCAL turn text contains one, else ''. Reads turn.text only; never
+ * egresses it. The returned term is from our fixed list, not user bytes.
+ */
+function textMatchesLexicon(turn) {
+  const text = (turn && typeof turn === 'object' && typeof turn.text === 'string') ? turn.text.toLowerCase() : '';
+  if (!text) return '';
+  for (const term of SHOW_SHARE_LEXICON) {
+    if (text.indexOf(term) !== -1) return term;
+  }
+  return '';
+}
+
+/**
+ * Pull the problem_type enum off the diagnose tuple as a generic handle.
+ * Returns 'undefined' (the enum value) when absent -- never user content.
+ */
+function problemTypeOf(tuple) {
+  if (!tuple || typeof tuple !== 'object') return 'undefined';
+  const pt = tuple.problem_type;
+  return (typeof pt === 'string' && pt) ? pt : 'undefined';
+}
+
+/**
+ * CONTEXT MODE (R3 primary) -- true when the LOCAL navigator PROBLEM-STATE shows
+ * a SHOW/SHARE shape specifically: tuple.problem_type (the enum the
+ * navigation.cjs chokepoint surfaces onto the diagnose tuple) is in OUR generic
+ * show/share problem-type allow-list. This is the PRIMARY trigger (R3):
+ * SENS-SHOW keys on the problem-state, not on a keyword scan. enum/scalar only
+ * (Part 8/9); a pure projection of the value already in hand -- NO filesystem /
+ * Brain read.
+ *
+ * (The broader Plan-07 tiering seam -- classifyTriggerTier -- is used to LABEL
+ * the tier enum recorded in evidence, so "context first, keyword fallback" is a
+ * recorded, testable property; it does NOT itself widen what SENS-SHOW fires on,
+ * keeping the keyword fallback genuinely reachable on a bare show/share-lexicon
+ * turn that carries no show/share problem-state.)
+ */
+function hasShowShareContext(tuple) {
+  const pt = (tuple && typeof tuple === 'object' && typeof tuple.problem_type === 'string')
+    ? tuple.problem_type.toLowerCase() : '';
+  return !!pt && SHOW_SHARE_PROBLEM_TYPES.indexOf(pt) !== -1;
+}
+
+/**
+ * SENS-SHOW -- show/present/share intent -> the /mos:show JTBD need-selector.
+ *
+ * @param {object} turn  -- normalized turn ({ text, signals })
+ * @param {object} tuple -- /mos:diagnose tuple { problem_type }
+ * @param {object} ctx   -- LOCAL context ({ roomDir })
+ * @returns {Readonly<object>|null}
+ */
+function sensorShowShare(turn, tuple, ctx) {
+  // R3 precedence (Canon Part 11): CONTEXT first, keyword DEMOTED to fallback.
+  //   signal  -- strongest (explicit show_share_intent signal on the turn)
+  //   context -- the PRIMARY branch: the LOCAL navigator problem-state
+  //   keyword -- the FALLBACK (fires only when no problem-state context present)
+  let mode = '';
+  if (hasShowShareSignal(turn)) {
+    mode = 'signal';
+  } else if (hasShowShareContext(tuple)) {
+    mode = 'context';
+  } else if (textMatchesLexicon(turn)) {
+    mode = 'keyword';
+  }
+  if (!mode) return null;
+
+  const pt = problemTypeOf(tuple);
+
+  // The Plan-07 tiering classification, recorded as a generic enum so the
+  // context-first / keyword-fallback precedence is legible in the evidence.
+  // Soft-fail to null so a classifier fault never blocks the reach.
+  let trigger_tier = null;
+  try {
+    trigger_tier = classifyTriggerTier(turn, tuple, ctx);
+  } catch (_e) {
+    trigger_tier = null;
+  }
+
+  return makeReach({
+    // REUSE the existing context_block reach -- mint NO 7th reach (D-03; mirrors
+    // SENS-09 reusing brain_consult). The 6-reach bank stays frozen.
+    reach_id: 'context_block',
+    // A STANDING SUGGESTION at the Decision Gate -- NEVER push_forward; it must
+    // NOT auto-open UI (Canon Part 3 GUIDED default + the "no card unprompted"
+    // doctrine, D-03).
+    posture: 'hold',
+    // Generic handle: the /mos:show selector front-door token. The orchestrator
+    // routes 'show-jtbd-selector' to /mos:show through the command-resolver path
+    // (a selector front door, NOT a Brain framework -- so it does not enter
+    // data/dispatch-framework-map.json, keeping its drift test green).
+    dispatch: 'show-jtbd-selector',
+    signal: 'show_share_intent',
+    // LOCAL scalars / enums ONLY: the fire MODE enum + the trigger TIER enum +
+    // the problem_type enum. Never the user's matched text (Part 8).
+    evidence: { mode: mode, trigger_tier: trigger_tier, problem_type: pt },
+  });
+}
+
+module.exports = {
+  sensorShowShare: sensorShowShare,
+  SHOW_SHARE_LEXICON: SHOW_SHARE_LEXICON,
+  SHOW_SHARE_PROBLEM_TYPES: SHOW_SHARE_PROBLEM_TYPES,
+};

package/lib/core/sensors/sensor-temporal-blindness.cjs

@@ -0,0 +1,123 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 160-06 Task 3 -- R12 temporal-blindness sentinel (D-04 scheduled backstop).
+ * ===============================================================================
+ *
+ * sensorTemporalBlindness(ctx) is the SCHEDULED backstop: it scans the room's
+ * OWN room.db (LOCAL only) for real-world-event nodes (type 'meeting' OR
+ * has_event_date===true on the properties JSON) where valid_at IS NULL, and
+ * RETURNS exactly those nodes for dating. When it surfaces any (>= 1) it emits a
+ * single temporal_blindness_surfaced memory_event via navigation.logMemoryEvent
+ * (the Part 9 chokepoint). When zero surface, it returns empty and emits NOTHING
+ * (silent on a clean run).
+ *
+ * Front line vs backstop (D-04): the R11 date+sync gate (date-sync-gate.cjs) is
+ * the FRONT LINE catching undated real-world artifacts at the filing source; this
+ * sentinel is the standing BACKSTOP, composed into the Phase 145 scout cadence,
+ * not fired per-turn (temporal blindness is slow-accumulating debt, not an urgent
+ * turn-to-turn signal). has_event_date is set EXPLICITLY at write time by node
+ * type; the sentinel only READS it (never infers), so the scan is deterministic.
+ *
+ * Canon Part 8 (LOCAL -> BRAIN: NO). PURE LOCAL: reads room.db scalars (type,
+ * the valid_at / has_event_date keys off the properties JSON) and emits an
+ * enum/count event. ZERO network, ZERO Brain. The undated node IDS ride the
+ * RETURN value (for the surface layer to date); the event payload carries ONLY a
+ * count scalar + a source_path -- never a node body, never user prose. The
+ * lib/core/sensors Part-8 5-tripwire sweep spans this file: no packet /
+ * brain-client require, no egress-projection helpers, no hashing call sites.
+ *
+ * Phase 144 routing fence: this file PRODUCES a surfacing result; it never
+ * assigns routing_source and never requires navigation-engine.cjs nor defines
+ * the routing function. The routing fence over lib/core/sensors/ asserts this.
+ *
+ * Pure / sync / LOCAL-first. node built-ins + project libs only. No new deps.
+ * House rule: hyphens only, no em-dashes.
+ */
+
+const navigation = require('../navigation.cjs');
+
+/*
+ * scanUndatedRealWorldNodes(db) -> array of { id, type } for every node that is
+ * a real-world event (type 'meeting' OR has_event_date===true) AND has no
+ * valid_at on its properties JSON. memory_event nodes are EXCLUDED (they carry
+ * their own valid_at semantics under Wave 2 dual-stamp and are not artifacts to
+ * date). Returns [] on any query fault (never throws).
+ *
+ * valid_at and has_event_date live on the properties JSON (the additive idiom --
+ * no DDL column), so the filter uses json_extract. "valid_at IS NULL" means the
+ * json_extract returns SQL NULL (key absent or explicitly null).
+ */
+function scanUndatedRealWorldNodes(db) {
+  try {
+    const rows = db.prepare(
+      "SELECT id, type FROM nodes " +
+      "WHERE type != 'memory_event' " +
+      "AND (type = 'meeting' OR json_extract(properties, '$.has_event_date') = 1 " +
+      "     OR json_extract(properties, '$.has_event_date') = 'true') " +
+      "AND json_extract(properties, '$.valid_at') IS NULL " +
+      "ORDER BY id"
+    ).all();
+    return Array.isArray(rows) ? rows : [];
+  } catch (_err) {
+    // A query fault must never crash a scheduled sweep; degrade to empty.
+    return [];
+  }
+}
+
+/*
+ * sensorTemporalBlindness(ctx) -> { nodes, count, surfaced, eventEmitted }.
+ *
+ * ctx:
+ *   db   a caller-owned room.db handle (via openRoomDb), exactly like writeEdge.
+ *        Absent / non-object -> degrades to an empty result (no throw).
+ *   now  injectable clock closure forwarded to logMemoryEvent (options.now seam).
+ *
+ * Returns:
+ *   nodes        the undated real-world-event nodes ({id, type}) to surface.
+ *   count        nodes.length (scalar).
+ *   surfaced     boolean -- true iff count > 0.
+ *   eventEmitted boolean -- true iff a temporal_blindness_surfaced event landed.
+ */
+function sensorTemporalBlindness(ctx) {
+  const c = ctx && typeof ctx === 'object' ? ctx : {};
+  const db = c.db;
+
+  if (!db) {
+    return { nodes: [], count: 0, surfaced: false, eventEmitted: false };
+  }
+
+  const nodes = scanUndatedRealWorldNodes(db);
+  const count = nodes.length;
+
+  // Silent on a clean run: zero undated nodes -> emit NOTHING (R12 acceptance).
+  if (count === 0) {
+    return { nodes: [], count: 0, surfaced: false, eventEmitted: false };
+  }
+
+  // Surface >= 1: emit ONE temporal_blindness_surfaced event (count scalar only;
+  // the node IDS ride the RETURN value, never the event payload -- Part 8).
+  const chokeOpts = {};
+  if (typeof c.now === 'function') chokeOpts.now = c.now;
+  let eventEmitted = false;
+  try {
+    const ev = navigation.logMemoryEvent(db, 'temporal_blindness_surfaced', {
+      count,
+      source_path: 'sentinel:temporal-blindness',
+      created_by: 'system',
+    }, chokeOpts);
+    eventEmitted = !!(ev && ev.ok);
+  } catch (_err) {
+    // The emit is best-effort; the surfacing result is the load-bearing output.
+    eventEmitted = false;
+  }
+
+  return { nodes, count, surfaced: true, eventEmitted };
+}
+
+module.exports = {
+  sensorTemporalBlindness,
+  // Exported for targeted tests + the cadence composition.
+  scanUndatedRealWorldNodes,
+};

package/lib/core/sensors/sensor-types.cjs

@@ -0,0 +1,294 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 143-01 Task 1 -- the candidate-reach struct contract + the id banks
+ * every sensor detector shares.
+ *
+ * This module makes the committed Phase 141 dial doctrine
+ * (skills/larry-personality/SKILL.md, LARRY-03 / D-12) machine-readable:
+ *
+ *   REACH_IDS   -- the 6 stable reach ids (SKILL.md lines ~48-52):
+ *     context_block | contradiction | cross_room | brain_consult | deep_research | hats
+ *     (the Hats reach: confirm-gated research-personas hat-spin -- Phase 148 D-09)
+ *   POSTURE_IDS -- the 3 stable posture ids (SKILL.md lines ~87-89):
+ *     push_forward | hold | pull_back
+ *
+ * The exactly-6 / exactly-3 invariants are drift contracts inherited from
+ * Phase 141 (D-05 / D-12) and amended in Phase 148 (D-09, the constitutional
+ * 6th-reach lockstep); the spine dispatch test fixes them so any add or
+ * remove fails CI.
+ *
+ * The candidate-reach struct is the pure data shape a sensor returns when it
+ * fires (or null when it does not). It carries ONLY generic handles + LOCAL
+ * scalars -- never user content (Canon Part 8). Brain-touching companions
+ * (e.g. brain_framework_chain) carry only the problem_type enum.
+ *
+ * Pure, zero-I/O, sync. No network, no filesystem, no require of any
+ * Brain/packet egress surface. House rule: hyphens only, no em-dashes.
+ */
+
+// ---------- The id banks (committed dial doctrine, frozen) ----------
+
+// The 6 reach ids, in canonical order. Mirrors the row mapping in
+// skills/larry-personality/SKILL.md:
+//   Context Block row            -> context_block
+//   contradiction surface row    -> contradiction
+//   cross-room reach row         -> cross_room
+//   Brain consult row            -> brain_consult
+//   framework-led deep research  -> deep_research
+//   Hats reach (Phase 148 D-09)  -> hats
+//     the confirm-gated research-personas hat-spin: a REAL 6th machine reach,
+//     no longer a render-label sub_mode under brain_consult.
+const REACH_IDS = Object.freeze([
+  'context_block',
+  'contradiction',
+  'cross_room',
+  'brain_consult',
+  'deep_research',
+  'hats',
+]);
+
+// The 3 posture ids, in canonical order. Mirrors the Hierarchical Navigator
+// movement in SKILL.md (push_forward / hold / pull_back).
+const POSTURE_IDS = Object.freeze([
+  'push_forward',
+  'hold',
+  'pull_back',
+]);
+
+// ---------- Phase 172-07: the trigger TIER model (R3 / INV-07) ----------
+//
+// Canon Part 11 R3: a trigger keys on navigator PROBLEM-STATE (stage / JTBD /
+// graph-gap) read LOCALLY via the navigation.cjs chokepoint (enum/scalar only,
+// Part 8/9); keyword/lexicon match is a FALLBACK tier, not the basis. This is
+// the closed, ORDERED tier vocabulary -- the order IS the precedence doctrine:
+//   signal   -- an explicit problem-state signal kind on the turn (strongest).
+//   context  -- a LOCAL navigator problem-state enum (stage / jtbd / graph_gap)
+//               present on the tuple+ctx the navigation.cjs chokepoint populated.
+//   content  -- Phase 244: lexical relevance to LOCAL stored material, bm25-
+//               ranked against the room's own corpus (eureka_fts). Content is
+//               NOT navigator problem-state, so R3 forbids ranking it as
+//               context-tier; it IS corpus-relative evidence rather than a
+//               hand-picked private word list, so it ranks above keyword.
+//   keyword  -- only a keyword/lexicon match in the turn text (the FALLBACK).
+// A sensor that records a `mode` enum (the sensor-diffusion-adoption precedent)
+// MUST draw it from this set, so the demotion of keyword to fallback is legible
+// in the evidence object. Mints NO reach and NO edge -- it is a classifier only.
+const TRIGGER_TIERS = Object.freeze([
+  'signal',
+  'context',
+  'content',   // Phase 244: lexical relevance to LOCAL stored material (bm25)
+  'keyword',
+]);
+
+// The closed set of LOCAL problem-state enum fields a context-tier trigger may
+// read. Each is an ENUM/scalar handle (stage label / jtbd slug / graph-gap kind)
+// that the navigation.cjs chokepoint surfaces onto the diagnose tuple or the
+// LOCAL ctx -- NEVER the user's prose (Part 8). This list is the read allow-list
+// so a future field cannot silently smuggle user content into the tier read.
+const PROBLEM_STATE_FIELDS = Object.freeze([
+  'stage',       // tuple.stage / ctx.venture_stage (the journey/definition stage)
+  'jtbd',        // ctx.jtbd (the active Jobs-to-be-Done slug)
+  'graph_gap',   // ctx.graph_gap (the LOCAL navigation gap kind, e.g. thin-evidence)
+]);
+
+/**
+ * Read the LOCAL navigator problem-state as a flat ENUM/scalar bag, drawn ONLY
+ * from PROBLEM_STATE_FIELDS over the diagnose tuple + LOCAL ctx (both populated
+ * by the navigation.cjs chokepoint upstream -- this helper adds NO filesystem or
+ * Brain read; it is a pure projection of values already in hand). Returns enum
+ * strings only; a field absent or non-string is omitted (never user content).
+ *
+ *   stage     <- tuple.stage || ctx.venture_stage || ctx.stage
+ *   jtbd      <- ctx.jtbd || tuple.jtbd
+ *   graph_gap <- ctx.graph_gap || tuple.graph_gap
+ *
+ * @param {object} turn  -- the normalized turn (unused for the read; kept for symmetry)
+ * @param {object} tuple -- the /mos:diagnose tuple { problem_type, stage, ... }
+ * @param {object} ctx   -- LOCAL context ({ venture_stage, jtbd, graph_gap })
+ * @returns {object} a flat { stage?, jtbd?, graph_gap? } enum bag (possibly empty)
+ */
+function readProblemStateEnum(turn, tuple, ctx) {
+  const t = (tuple && typeof tuple === 'object') ? tuple : {};
+  const c = (ctx && typeof ctx === 'object') ? ctx : {};
+  const out = {};
+
+  const stage = (typeof t.stage === 'string' && t.stage) ? t.stage
+    : (typeof c.venture_stage === 'string' && c.venture_stage) ? c.venture_stage
+    : (typeof c.stage === 'string' && c.stage) ? c.stage
+    : '';
+  const jtbd = (typeof c.jtbd === 'string' && c.jtbd) ? c.jtbd
+    : (typeof t.jtbd === 'string' && t.jtbd) ? t.jtbd
+    : '';
+  const graphGap = (typeof c.graph_gap === 'string' && c.graph_gap) ? c.graph_gap
+    : (typeof t.graph_gap === 'string' && t.graph_gap) ? t.graph_gap
+    : '';
+
+  if (stage) out.stage = stage;
+  if (jtbd) out.jtbd = jtbd;
+  if (graphGap) out.graph_gap = graphGap;
+  return out;
+}
+
+/**
+ * True if the turn carries an explicit problem-state SIGNAL kind. A turn is
+ * { signals: [...] } where each signal is a string kind or { kind }. The closed
+ * signal-kind set that denotes a problem-state advance is small and generic.
+ * Defensive; never throws.
+ */
+function hasProblemStateSignal(turn) {
+  if (!turn || typeof turn !== 'object') return false;
+  const PS_SIGNAL_KINDS = ['problem_state_changed', 'stage_advanced', 'jtbd_set', 'graph_gap_detected'];
+  const signals = Array.isArray(turn.signals) ? turn.signals : [];
+  for (const s of signals) {
+    const kind = (typeof s === 'string') ? s : (s && typeof s === 'object' ? s.kind : '');
+    if (PS_SIGNAL_KINDS.indexOf(kind) !== -1) return true;
+  }
+  return false;
+}
+
+/**
+ * True if the turn text is a non-empty string (the precondition for a keyword
+ * FALLBACK match to be possible at all). This classifier does NOT itself run a
+ * lexicon -- each sensor owns its own vocabulary; this just reports whether the
+ * keyword TIER is the highest tier available when no problem-state is present.
+ */
+function hasKeywordSurface(turn) {
+  const text = (turn && typeof turn === 'object' && typeof turn.text === 'string') ? turn.text : '';
+  return text.length > 0;
+}
+
+/**
+ * Classify the trigger TIER for a turn, applying the R3 precedence: a present
+ * problem-state SIGNAL or a present LOCAL problem-state ENUM is the CONTEXT tier
+ * (preferred); a bare keyword surface is the KEYWORD fallback tier; absent all,
+ * returns null (nothing to trigger on). This is the seam that makes "context
+ * first, keyword fallback" a recorded, testable property rather than a comment.
+ *
+ *   signal kind present                 -> 'signal'  (a context-tier member)
+ *   problem-state enum present          -> 'context'
+ *   only a keyword surface present      -> 'keyword' (the FALLBACK)
+ *   nothing                             -> null
+ *
+ * NOTE: 'signal' and 'context' are BOTH context-tier (both rank above keyword).
+ * Phase 244 ADDED a fourth tier, 'content', ranked between 'context' and
+ * 'keyword'. The binary idiom this comment used to recommend,
+ * `classifyTriggerTier(...) === 'keyword'` (fallback) against anything else,
+ * is NOW WRONG: 'content' is "anything else" and would be silently promoted
+ * to context-tier by any caller still following that advice. Use the two
+ * correct predicates instead: `isContextTier(tier)` (true for signal/context)
+ * and `isFallbackTier(tier)` (true for content/keyword). The bare
+ * `=== 'keyword'` comparison is no longer a safe fallback test.
+ *
+ * @returns {string|null} one of TRIGGER_TIERS, or null
+ */
+function classifyTriggerTier(turn, tuple, ctx) {
+  if (hasProblemStateSignal(turn)) return 'signal';
+  const ps = readProblemStateEnum(turn, tuple, ctx);
+  if (Object.keys(ps).length > 0) return 'context';
+  if (hasKeywordSurface(turn)) return 'keyword';
+  return null;
+}
+
+/**
+ * True when the classified tier is a CONTEXT tier (signal or context), i.e. the
+ * trigger is keying on problem-state rather than falling back to keyword. The
+ * one-line predicate sensors use to PREFER the context signal over keyword.
+ */
+function isContextTier(tier) {
+  return tier === 'signal' || tier === 'context';
+}
+
+/**
+ * True when the classified tier is a FALLBACK tier (content or keyword), i.e.
+ * the trigger is NOT keying on navigator problem-state. Phase 244 companion
+ * to isContextTier: both predicates are EXPLICIT allowlists, mutually
+ * exclusive, and their union covers every member of TRIGGER_TIERS. This is
+ * deliberately NOT implemented as `!isContextTier(tier)` -- a negated form
+ * would silently absorb any future fifth tier, which is the exact failure
+ * mode this predicate exists to repair (the doctrine-rot the amended NOTE
+ * above describes).
+ */
+function isFallbackTier(tier) {
+  return tier === 'content' || tier === 'keyword';
+}
+
+// ---------- makeReach: the pure candidate-reach factory ----------
+
+/**
+ * Build a frozen candidate-reach struct, validating reach_id + posture against
+ * the committed banks. Returns null (never throws) on any invalid input.
+ *
+ * Struct shape:
+ *   {
+ *     reach_id   : one of REACH_IDS
+ *     posture    : one of POSTURE_IDS
+ *     dispatch   : the /mos: command slug or shipped-engine handle to fire
+ *     companions : array of additional GENERIC handles (e.g. the
+ *                  brain_framework_chain:<problem_type> handle) -- never user content
+ *     signal     : the signal kind that fired the sensor
+ *     evidence   : LOCAL scalars only (counts, enums, ids) -- never user bytes
+ *   }
+ *
+ * @param {object} opts
+ * @returns {Readonly<object>|null}
+ */
+function makeReach(opts) {
+  if (!opts || typeof opts !== 'object' || Array.isArray(opts)) return null;
+
+  const reach_id = opts.reach_id;
+  const posture = opts.posture;
+
+  if (REACH_IDS.indexOf(reach_id) === -1) return null;
+  if (POSTURE_IDS.indexOf(posture) === -1) return null;
+
+  const dispatch = typeof opts.dispatch === 'string' ? opts.dispatch : '';
+  const signal = typeof opts.signal === 'string' ? opts.signal : '';
+
+  // companions: array of generic-handle strings only. Anything non-string is
+  // dropped (defensive -- the struct must never carry arbitrary objects that
+  // could smuggle user content past the Part-8 sweep).
+  const companions = Array.isArray(opts.companions)
+    ? opts.companions.filter(function (c) { return typeof c === 'string'; })
+    : [];
+
+  // evidence: LOCAL scalars only. We freeze a shallow copy of primitive values.
+  // Non-primitive values are dropped so the struct stays a flat scalar bag.
+  const evidence = {};
+  if (opts.evidence && typeof opts.evidence === 'object' && !Array.isArray(opts.evidence)) {
+    for (const k of Object.keys(opts.evidence)) {
+      const v = opts.evidence[k];
+      const t = typeof v;
+      if (t === 'string' || t === 'number' || t === 'boolean') {
+        evidence[k] = v;
+      }
+    }
+  }
+
+  return Object.freeze({
+    reach_id: reach_id,
+    posture: posture,
+    dispatch: dispatch,
+    companions: Object.freeze(companions),
+    signal: signal,
+    evidence: Object.freeze(evidence),
+  });
+}
+
+module.exports = {
+  REACH_IDS: REACH_IDS,
+  POSTURE_IDS: POSTURE_IDS,
+  makeReach: makeReach,
+  // Phase 172-07: the trigger-tier model (R3 / INV-07 -- context first, keyword
+  // fallback). Pure classifiers + the closed ordered tier vocabulary + the
+  // LOCAL problem-state enum read (enum/scalar only, Part 8).
+  TRIGGER_TIERS: TRIGGER_TIERS,
+  PROBLEM_STATE_FIELDS: PROBLEM_STATE_FIELDS,
+  readProblemStateEnum: readProblemStateEnum,
+  classifyTriggerTier: classifyTriggerTier,
+  isContextTier: isContextTier,
+  // Phase 244: the fallback-tier allowlist companion to isContextTier.
+  isFallbackTier: isFallbackTier,
+  hasProblemStateSignal: hasProblemStateSignal,
+};