@mindrian_os/install 1.13.0-beta.13 → 1.13.0-beta.16

package/lib/core/install-state.cjs

@@ -0,0 +1,242 @@
+'use strict';
+
+/*
+ * lib/core/install-state.cjs -- install-state.json read / write / migrate
+ * module.
+ *
+ * Extracts the inline session-start read+write+derive logic into a focused
+ * single-purpose module; adds the v1 -> v2 schema migration with additive-only
+ * semantics + future-version detection + atomic-write crash safety.
+ *
+ * Phase 126 Plan 07. Canon Part 6 (dog-fooding: schema evolution surfaces only
+ * via shipped harness -- v1 was shipped in v1.13.0-beta.13). Canon Part 7
+ * (reuse: extracts inline session-start write into a module; does NOT
+ * re-architect the write path).
+ *
+ * The wire shape evolves through a single integer sentinel (`schema_version`).
+ * Per CONTEXT.md D3 (LOCKED): integer not semver string (simpler comparison
+ * for additive-only migrations). Per Open Question 5 settlement: `===` integer
+ * equality is the comparison.
+ *
+ * The v1 -> v2 additive-only mapping (CONTEXT.md D3 + Plan 07 must_haves):
+ *
+ *   v1 file (Phase 123, NO schema_version):
+ *     {
+ *       active_root, active_version, topology, installed_at,
+ *       snapshot, surfaces?, resolved_at?, ...
+ *     }
+ *
+ *   v2 file (Phase 126):
+ *     v1-fields-preserved-byte-identical +
+ *     {
+ *       schema_version: 2,
+ *       topology_class: derived from topology (see deriveTopologyClass below),
+ *       last_acceptance_run: null,                  // Plan 03 + Plan 05 fill this
+ *       renderer_contract_version: 'unknown'        // Plan 01 sets this
+ *     }
+ *
+ * Future-version detection: schema_version > 2 -> warn on stderr + DEFER to
+ * /mos:doctor --fix. Do NOT downgrade. Do NOT touch the file. Return a typed
+ * sentinel so callers can decide.
+ *
+ * Atomic write: write to `<path>.tmp`, fsync, rename. A crash between write
+ * and rename leaves the original file untouched. The MOS_TEST_FORCE_FAIL=rename
+ * env-var hook mirrors scripts/doctor.cjs lines ~304-307 -- it injects a throw
+ * at the rename moment so the crash-recovery contract is testable.
+ *
+ * Canon Part 8: this module reads + writes LOCAL files only ($HOME/.mindrian/).
+ * Zero network calls. Zero Brain queries. Zero side-channel to remote services.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA_VERSION = 2;
+const STATE_FILE_PATH_REL = path.join('.mindrian', 'install-state.json');
+
+function statePath(home) {
+  return path.join(home, STATE_FILE_PATH_REL);
+}
+
+/**
+ * readInstallState({ home }) -> object | null
+ *
+ * Returns the parsed JSON object, or null when the file is absent OR
+ * unparseable. Never throws -- the goal is a robust read for downstream
+ * consumers (doctor, session-start, the migrator itself). A corrupt file is
+ * surfaced as null so the caller can decide whether to derive-from-scratch
+ * (session-start's existing behavior) or surface a finding (doctor class I).
+ */
+function readInstallState(opts) {
+  const home = (opts && opts.home) || '';
+  if (!home) return null;
+  const p = statePath(home);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    // Corrupt file -> null (mirrors doctor.cjs's class-I "absent" finding).
+    return null;
+  }
+}
+
+/**
+ * writeInstallState({ home, state }) -> void
+ *
+ * Atomic write: $HOME/.mindrian/install-state.json.tmp -> fsync -> rename.
+ *
+ * The MOS_TEST_FORCE_FAIL=rename env injection mirrors the doctor.cjs
+ * pattern -- if set, throws AFTER the .tmp write but BEFORE the rename so
+ * tests can verify the original file is left untouched.
+ *
+ * Test-only side note: when MOS_TEST_FORCE_FAIL=rename, the .tmp file is left
+ * on disk; the rename never happens; the original target is untouched. A
+ * subsequent successful call will overwrite the .tmp via openSync('w') so
+ * stale .tmp files are not a long-term hazard.
+ */
+function writeInstallState(opts) {
+  const home = opts.home;
+  const state = opts.state;
+  const p = statePath(home);
+  const tmp = p + '.tmp';
+  // Ensure parent dir exists. Idempotent.
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  // Atomic write: write to tmp, fsync (best-effort), rename.
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(state, null, 2) + '\n');
+    try { fs.fsyncSync(fd); } catch (_) { /* fsync best-effort -- some FS lack support */ }
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Test injection point (mirrors scripts/doctor.cjs MOS_TEST_FORCE_FAIL).
+  // Throw AFTER the .tmp write so the original target is byte-identical.
+  if (process.env.MOS_TEST_FORCE_FAIL === 'rename') {
+    throw new Error('MOS_TEST_FORCE_FAIL=rename injection (test-only)');
+  }
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * deriveTopologyClass(topology) -> 'healthy' | 'missing' | 'drifted'
+ *
+ * Canonical 4-state taxonomy from CONTEXT.md D3 + Plan 03 needs.
+ *
+ * Mapping (see PLAN.md Task 2 behavior block):
+ *   marketplace-cache -> healthy   (Claude Code's standard install path)
+ *   direct            -> healthy   (npx round-trip install -- @mindrian_os/install)
+ *   dev-clone         -> healthy   (developer machine -- a clone with a remote)
+ *   not-found         -> missing   (resolver returned null root)
+ *   legacy            -> drifted   (the legacy hand-clone path -- pre-Phase 123)
+ *   <unknown>         -> drifted   (conservative default for any new topology
+ *                                   introduced after this module's release)
+ */
+function deriveTopologyClass(topology) {
+  switch (topology) {
+    case 'marketplace-cache': return 'healthy';
+    case 'direct':            return 'healthy';
+    case 'dev-clone':         return 'healthy';
+    case 'not-found':         return 'missing';
+    case 'legacy':            return 'drifted';
+    default:                  return 'drifted';
+  }
+}
+
+/**
+ * migrateIfNeeded({ home }) -> {
+ *   migrated: boolean,
+ *   // present in v1 -> v2 path:
+ *   fromVersion?: 1, toVersion?: 2,
+ *   // present in v2 path:
+ *   currentVersion?: 2,
+ *   // present in future-version path:
+ *   futureVersion?: true, currentVersion?: number, advice?: string,
+ *   // present in no-file path:
+ *   fileAbsent?: true,
+ * }
+ *
+ * Behavior matrix:
+ *
+ *   File absent
+ *     -> { migrated:false, fileAbsent:true }
+ *     -> Do NOT create the file (creation is session-start's job).
+ *
+ *   File present + no schema_version (or schema_version absent/null)
+ *     -> Treat as v1. Run additive migration. Write back. Return
+ *        { migrated:true, fromVersion:1, toVersion:2 }.
+ *
+ *   File present + schema_version === 2
+ *     -> No-op. Return { migrated:false, currentVersion:2 }.
+ *
+ *   File present + schema_version > 2 (a future-version file)
+ *     -> Emit stderr warn. Do NOT touch the file. Return
+ *        { migrated:false, futureVersion:true, currentVersion:<n>,
+ *          advice:'run /mos:doctor --fix' }.
+ *
+ *   File present + schema_version < 2 (unexpected lower-than-v1, e.g. 0)
+ *     -> Treat as v1 (coerce). Same outcome as the v1 path.
+ *
+ *   File present + corrupt JSON
+ *     -> readInstallState returned null -> indistinguishable from absent at
+ *        this layer -> { migrated:false, fileAbsent:true }. doctor class I
+ *        is the surface that catches corrupt-but-present and offers --fix.
+ */
+function migrateIfNeeded(opts) {
+  const home = opts.home;
+  const state = readInstallState({ home });
+  if (!state) return { migrated: false, fileAbsent: true };
+
+  const sv = state.schema_version;
+  if (typeof sv === 'undefined' || sv === null) {
+    // v1 (or unmarked) -> v2 additive migration.
+    return _runV1ToV2({ home, state });
+  }
+  if (sv === SCHEMA_VERSION) {
+    return { migrated: false, currentVersion: SCHEMA_VERSION };
+  }
+  if (typeof sv === 'number' && sv > SCHEMA_VERSION) {
+    // Future-version: warn + defer. Do NOT downgrade. Do NOT touch the file.
+    process.stderr.write(
+      '[install-state] schema_version ' + sv + ' is newer than the plugin understands (' +
+      SCHEMA_VERSION + '). Skipping migration; run /mos:doctor --fix.\n'
+    );
+    return {
+      migrated: false,
+      futureVersion: true,
+      currentVersion: sv,
+      advice: 'run /mos:doctor --fix',
+    };
+  }
+  // Unexpected lower-than-v1 (e.g. schema_version: 0 or a non-number) -- coerce
+  // to v1 and run the additive migration. This is a safety net; not expected
+  // to fire in practice.
+  return _runV1ToV2({ home, state });
+}
+
+// Internal: perform the v1 -> v2 additive migration + write.
+function _runV1ToV2(opts) {
+  const home = opts.home;
+  const state = opts.state;
+  // Object.assign preserves v1 fields byte-identically; new fields are
+  // appended last (since v2's schema_version is the sentinel, the order
+  // could be reshuffled but additive-on-top is the simplest invariant).
+  const v2 = Object.assign({}, state, {
+    schema_version: SCHEMA_VERSION,
+    topology_class: deriveTopologyClass(state.topology),
+    last_acceptance_run: null,
+    renderer_contract_version: 'unknown',
+  });
+  writeInstallState({ home, state: v2 });
+  return { migrated: true, fromVersion: 1, toVersion: SCHEMA_VERSION };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  readInstallState,
+  writeInstallState,
+  migrateIfNeeded,
+  deriveTopologyClass,
+  // Test-only helpers (intentionally exported with leading underscore so
+  // consumers do not depend on them and grep can spot test surface usage).
+  _statePath: statePath,
+};

package/lib/core/navigation/edges.cjs

@@ -0,0 +1,86 @@
+'use strict';
+// Phase 125-00 -- navigation.cjs edge-write primitive (per CONTEXT.md Pass 3 GAP-2
+// resolution). Adds writeEdge to the navigation.cjs closed surface as an additive
+// extension following the Phase 110-03 logMemoryEvent precedent.
+//
+// Canon Part 4: every choice is graph data; this is the chokepoint primitive that
+// lets Plan 06 selector-decisions.cjs + future Phases 116/117/118 write typed
+// cascade edges without bypassing the closed surface.
+//
+// Canon Part 7: reuse-before-build -- the UPSERT statement mirrors
+// lib/core/lazygraph-ops.cjs::upsertEdge (lines 990-1019) so sibling agents
+// emit edges via the same UPSERT shape and the navigation chokepoint stays
+// the single door for write traffic.
+//
+// Canon Part 8 invariant: writeEdge takes (db, params) -- a db handle owned by
+// the caller (via openRoomDb) -- so this module never opens room.db itself. Zero
+// direct room-db.cjs require here. The navigation pre-commit hook treats this
+// file as part of the navigation/* allow-list, NOT as a bypass.
+
+const crypto = require('node:crypto');
+
+// Closed edge-type allowlist enforced by writeEdge. Mirrors the EVENT_TYPES Set
+// pattern in lib/core/navigation/memory-events.cjs. Phase 125 ships DEFERRED +
+// REJECTED (D7 typed cascade edge surface for F.1 defer / F.2 reject). Future
+// phases (e.g. Phase 116 tension resolution, Phase 117 auto-explore, Phase 118
+// MVA) extend this Set additively without canon amendment -- same idiom as the
+// EVENT_TYPES additive blocks for Phases 88.2-00 / 89-07 / 116-00 / 117-00 /
+// 110-02.
+//
+// Tests assert a FLOOR (DEFERRED + REJECTED present) and Set-instance shape --
+// not an exact size -- so additive extensions cannot regress baseline.
+const ALLOWED_EDGE_TYPES = Object.freeze(new Set([
+  // Phase 125 D7 -- F-selector decision edges (LOCKED LOCAL per Canon Part 8).
+  'DEFERRED',
+  'REJECTED',
+]));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// writeEdge(db, params) -- the 15th-style additive re-export on the
+// navigation.cjs closed surface (see navigation.cjs header comment for the
+// canonical re-export pattern alongside logMemoryEvent + firstCapturedLastTouchedBySection).
+//
+// Positional db (first arg, owned by caller via openRoomDb), params object
+// (second arg) with: { source_id, target_id, edge_type, properties }.
+//
+// Returns { ok: true, edge_id, type, source, target } on success, or
+// { ok: false, reason, detail? } on validation / write failure. Defensive --
+// never throws on caller input. The underlying prepare/run is sync per the
+// node:sqlite contract (matches the rest of the navigation module).
+function writeEdge(db, params) {
+  if (!params || typeof params !== 'object') {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const { source_id, target_id, edge_type, properties } = params;
+  if (typeof source_id !== 'string' || source_id.length === 0) {
+    return { ok: false, reason: 'invalid_source_id' };
+  }
+  if (typeof target_id !== 'string' || target_id.length === 0) {
+    return { ok: false, reason: 'invalid_target_id' };
+  }
+  if (typeof edge_type !== 'string' || !ALLOWED_EDGE_TYPES.has(edge_type)) {
+    return { ok: false, reason: 'invalid_edge_type', detail: String(edge_type).slice(0, 40) };
+  }
+  const props = isPlainObject(properties) ? properties : {};
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  const edgeId = 'edge:' + edge_type + ':' + Date.now() + ':' + crypto.randomBytes(4).toString('hex');
+  try {
+    db.prepare(
+      'INSERT INTO edges (source, target, type, properties) VALUES (?, ?, ?, ?) ' +
+      'ON CONFLICT(source, target, type) DO UPDATE SET properties = excluded.properties'
+    ).run(source_id, target_id, edge_type, propsJson);
+  } catch (e) {
+    return { ok: false, reason: 'edge_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, edge_id: edgeId, type: edge_type, source: source_id, target: target_id };
+}
+
+module.exports = { ALLOWED_EDGE_TYPES, writeEdge };

package/lib/core/navigation/insights.cjs

@@ -339,6 +339,42 @@ function findSurfaceableTensions(db, roomId, opts) {
   return candidates;
 }
 
+/**
+ * Phase 124-01 Plan: firstCapturedLastTouchedBySection
+ * ----------------------------------------------------
+ * For a given section slug (the source_section identity for a folder), return
+ * { first_captured_ms, last_touched_ms, total_events } across all memory_event
+ * rows scoped to that section (source_path === slug OR source_path LIKE slug/%).
+ *
+ * Used by lib/core/feynman/timeline-renderer.cjs for the D-05 summary line
+ * ("first captured {first_iso}, last touched {last_iso}"). Returns nulls + 0
+ * count when the section has zero memory_event rows -- the empty-state cue.
+ *
+ * Canon Part 9: pure SQL read against the local room.db; zero Brain surface;
+ * zero filesystem reads. Canon Part 8-safe by construction.
+ */
+function firstCapturedLastTouchedBySection(db, sectionSlug) {
+  if (!db || typeof db.prepare !== 'function' || typeof sectionSlug !== 'string' || sectionSlug.length === 0) {
+    return { first_captured_ms: null, last_touched_ms: null, total_events: 0 };
+  }
+  try {
+    const row = db.prepare(
+      "SELECT MIN(created_at) AS first_ms, MAX(created_at) AS last_ms, COUNT(*) AS n " +
+      "FROM nodes " +
+      "WHERE type = 'memory_event' " +
+      "AND (source_path = ? OR source_path LIKE ?)"
+    ).get(sectionSlug, sectionSlug + '/%');
+    const total = (row && Number.isFinite(row.n)) ? row.n : 0;
+    return {
+      first_captured_ms: total > 0 && Number.isFinite(row.first_ms) ? row.first_ms : null,
+      last_touched_ms: total > 0 && Number.isFinite(row.last_ms) ? row.last_ms : null,
+      total_events: total,
+    };
+  } catch (_) {
+    return { first_captured_ms: null, last_touched_ms: null, total_events: 0 };
+  }
+}
+
 module.exports = {
   findContradictions,
   findUnsupportedClaims,
@@ -347,4 +383,5 @@ module.exports = {
   findOpenQuestions,
   findRelevantOpportunities,
   findSurfaceableTensions,
+  firstCapturedLastTouchedBySection,
 };

package/lib/core/navigation/memory-events.cjs

@@ -70,6 +70,45 @@ const EVENT_TYPES = Object.freeze(new Set([
   'brain_packet_rejected',
   'brain_response_rejected',
   'brain_legacy_path_used',
+  // Phase 124-02 extension (FEYNMAN.md Temporal Awareness; D-10 telemetry mirror):
+  //   feynman_timeline_refreshed      -> the runner successfully rendered + wrote the
+  //                                      sentinel-bounded ## Timeline (auto) section for one
+  //                                      FEYNMAN.md (per section, per refresh).
+  //   feynman_timeline_refresh_failed -> the runner caught an exception during render or write;
+  //                                      watermark NOT updated; FEYNMAN.md NOT corrupted (atomic
+  //                                      .tmp write means the original is preserved on failure).
+  // Additive extension only; mirrors the Phase 110-02 3-string idiom verbatim. logEvent already
+  // rejects event_type values outside EVENT_TYPES -- so these are accepted only because they
+  // are now IN the Set. Set size grows by 2 (was 35 before Phase 124; now 37 baseline; coexists
+  // with the Phase 125-01 framework_invoked extension which adds +1 in parallel).
+  'feynman_timeline_refreshed',
+  'feynman_timeline_refresh_failed',
+  // Phase 125-01 extension (counter source for D3 continuous investment gradient).
+  // Each /mos:* methodology command run logs one framework_invoked event with payload
+  // {framework, command, timestamp}. computeInvestmentLevel(roomState) projects
+  // COUNT(memory_event WHERE event_type='framework_invoked') -> investment_level.
+  // The actual emission site is a follow-on instrumentation pass (lib/render/render-v2.cjs
+  // or per-command hook); Plan 01 only ships the event_type allowlist entry so
+  // computeInvestmentLevel can call findRecentChanges with this filter and get 0 (cold)
+  // back from a fresh room. The instrumentation is non-blocking for Plan 01 acceptance
+  // since computeInvestmentLevel reads from roomState.framework_invocations (which a
+  // separate caller will populate by calling findRecentChanges + counting); when no
+  // such count is available, the helper returns level: 0 -- the cold-start path.
+  'framework_invoked',
+  // Phase 125-06 extension (D7: F-selector reject/defer become typed graph signal).
+  // Emitted by lib/workflow/selector-decisions.cjs::recordSelectorDecision.
+  // Payload: {decision: 'defer'|'reject', command, framework, reason, edge_semantic,
+  //   expires_at|null, score_at_decision, investment_level_at_decision}. The corresponding
+  //   DEFERRED/REJECTED cascade edge is written via navigation.writeEdge (Plan 00).
+  //   Canon Part 4: every choice is graph data. The F-selector's adaptive-questioning
+  //   surface relies on this signal to apply decay-weight in subsequent rankings.
+  'f_selector_decision',
+  // Phase 125-07 extension (D8: none-fit affordance + ranker-miss capture).
+  // Emitted by lib/workflow/selector-decisions.cjs::recordSelectorMiss.
+  // Payload: {top_k_offered: [{command, score}, ...], user_intent: <verbatim user text>,
+  //   investment_level_at_decision}. NO cascade edge written (miss is temporal-only).
+  //   Canon Part 8: user_intent stays LOCAL; never sent to Brain.
+  'f_selector_miss',
 ]));
 
 function isPlainObject(v) {

package/lib/core/navigation/packet.cjs

@@ -15,6 +15,14 @@ const crypto = require('node:crypto');
 const { getNeighborhood } = require('./neighborhood.cjs');
 const { findContradictions, findUnsupportedClaims, findRelevantOpportunities } = require('./insights.cjs');
 const { findRecentChanges } = require('./memory-events.cjs');
+// Phase 125-03 -- framework_chain_hint stitch. projections.cjs (Plan 01) gives
+// us the active framework set + hop depth from roomState; framework-chain-slice
+// (Plan 02) fetches the FEEDS_INTO Cypher slice from the Brain. Both modules
+// are pure-or-graceful: projections never throws, slice fetcher returns a
+// degraded envelope rather than throwing. Required at module top because the
+// stitch is a hot path the helper does NOT lazy-import.
+const projections = require('./projections.cjs');
+const chainSliceMod = require('../../brain/framework-chain-slice.cjs');
 
 // Phase 110-02 (D-03 + D-09): privacy-mode opt-up. local_summary_only is the default and
 // the only mode any of the 12 shipped Brain jobs ever requests (every $def.in.properties.privacy_mode
@@ -178,7 +186,57 @@ function getFocusType(db, focusNodeId) {
   return row ? row.type : null;
 }
 
-function buildBrainPacket(db, job, focusNodeId, opts) {
+// Phase 125-03 -- stitch helper. Reads roomState via projections, fetches the
+// 1-3 hop FEEDS_INTO slice via Plan 02 fetcher (or mock from opts._mocks),
+// returns the framework_chain_hint shape per CONTEXT.md Scope IN section B
+// item 5 -- OR undefined when the active set is empty (which is the "absent
+// from packet" path per Plan 04 schema: framework_chain_hint is optional on
+// LocalGraphSummary; absence is meaningful).
+//
+// Contract:
+//   - roomState null / not-an-object -> undefined  (cold-start packet ships without hint)
+//   - active frameworks empty array  -> undefined  (no anchor to fetch a slice for)
+//   - active frameworks non-empty + Brain reachable  -> hint object (5 fields)
+//   - active frameworks non-empty + Brain unreachable -> hint object with degraded
+//     shape per Plan 02 fetcher contract (edges:[], brain_snapshot_id:null,
+//     slice_rationale carrying 'brain_unreachable' or similar marker). The hint
+//     is STILL attached so the ranker can distinguish "active set non-empty but
+//     Brain failed" from "active set empty" (RESEARCH G-08 / Tier 0 invariant).
+//
+// Async because the fetcher is async. Pure read-only flow: no db writes, no fs
+// writes, no Brain writes -- only the Plan 02 read primitive (Cypher MATCH).
+async function _surfaceFrameworkChainHint(db, roomState, opts) {
+  if (!roomState || typeof roomState !== 'object') return undefined;
+  const active = projections.resolveActiveFrameworks(roomState);
+  if (!Array.isArray(active) || active.length === 0) return undefined;
+  const hopDepth = projections.resolveHopDepth(roomState);
+  const depth = (hopDepth && (hopDepth.depth === 1 || hopDepth.depth === 2 || hopDepth.depth === 3))
+    ? hopDepth.depth
+    : 3;
+  const activeNames = active.map(function (a) { return a.name; });
+  // Test seam: opts._mocks.fetchFrameworkChainSlice replaces the live fetcher
+  // for hermetic tests (no Brain network). Falls through to the shipped Plan
+  // 02 module when no mock is provided.
+  const fetcher = (opts && opts._mocks && typeof opts._mocks.fetchFrameworkChainSlice === 'function')
+    ? opts._mocks.fetchFrameworkChainSlice
+    : chainSliceMod.fetchFrameworkChainSlice;
+  // Per Plan 02 contract, fetcher NEVER throws; it returns a degraded envelope
+  // on any failure path (Brain unreachable, query throws, sanitizer rejects).
+  // Wrapping in try/catch is defensive belt-and-suspenders in case a future
+  // mock or replacement misbehaves.
+  let slice;
+  try {
+    slice = await fetcher({ active_frameworks: activeNames, max_hops: depth });
+  } catch (_e) {
+    // Defensive: even if the fetcher contract is violated, do NOT crash the
+    // packet builder. Return undefined -> hint absent for this call.
+    return undefined;
+  }
+  if (!slice || typeof slice !== 'object') return undefined;
+  return slice;
+}
+
+async function buildBrainPacket(db, job, focusNodeId, opts) {
   const options = opts || {};
   const mocks = options._mocks;
   const roomId = options.roomId || null;
@@ -217,6 +275,15 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
   const recentChanges = findRecentChanges(db, Date.now() - 24 * 60 * 60 * 1000, { limit: 10 }).map(safeRecentChangeProjection);
   const bankedOpportunities = surface_banked_opportunities(db, focusNodeId, mocks);
 
+  // Phase 125-03: framework_chain_hint stitch. Reads roomState from opts (callers
+  // pass it through; Plan 05 ranker passes its own roomState when calling
+  // buildBrainPacket explicitly). When opts.roomState is absent OR resolves to an
+  // empty active framework set, the hint is ABSENT from the packet per the
+  // CONTEXT.md "absent when active set empty" invariant (Plan 04 schema accepts
+  // both shapes since framework_chain_hint is NOT in LocalGraphSummary.required[]).
+  const roomState = (options && typeof options === 'object') ? options.roomState : null;
+  const frameworkChainHint = await _surfaceFrameworkChainHint(db, roomState, options || {});
+
   return {
     packet_version: '1.0',
     job,
@@ -240,14 +307,22 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
         summary: focusSummary,
       },
     },
-    local_graph_summary: {
-      nearest_claims: nearestClaims,
-      nearest_assumptions: nearestAssumptions,
-      contradictions,
-      unsupported_claims: unsupportedClaims,
-      recent_changes: recentChanges,
-      banked_opportunities: bankedOpportunities,
-    },
+    local_graph_summary: Object.assign(
+      {
+        nearest_claims: nearestClaims,
+        nearest_assumptions: nearestAssumptions,
+        contradictions,
+        unsupported_claims: unsupportedClaims,
+        recent_changes: recentChanges,
+        banked_opportunities: bankedOpportunities,
+      },
+      // Phase 125-03: conditionally include framework_chain_hint. Object.assign
+      // with an empty-object short-circuit guarantees the key is ABSENT (not
+      // present with an undefined value) when frameworkChainHint is undefined.
+      // This preserves the schema invariant in Plan 04 (the field is optional;
+      // absence is meaningful for the ranker in Plan 05).
+      (frameworkChainHint === undefined) ? {} : { framework_chain_hint: frameworkChainHint }
+    ),
     constraints: {
       privacy: 'no_raw_artifact_text',
       max_tokens: 1200,
@@ -265,4 +340,9 @@ module.exports = {
   readRoomConfigPrivacyMode,
   roomHasExcerptApproval,
   PRIVACY_MODES,
+  // Phase 125-03 test seam: surface helper exposed for fine-grained unit tests
+  // in lib/memory/packet-chain-hint.test.cjs. NOT part of the public API; Plan
+  // 05 ranker reads the assembled local_graph_summary.framework_chain_hint
+  // directly off the packet rather than calling the helper.
+  _test: { _surfaceFrameworkChainHint },
 };