@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/lib/hmi/selector-dispatcher.cjs

@@ -70,6 +70,14 @@
 
 'use strict';
 
+// Phase 121-02 D-04: unified-stream selector_pick emit chokepoint.
+// require()-loaded lazily inside emitSelectorPickUnified() so a missing writer
+// module (or a stripped-down install) cannot crash the dispatcher at load.
+const crypto = require('node:crypto');
+function _sha256(s) {
+  return crypto.createHash('sha256').update(String(s || '')).digest('hex');
+}
+
 const FREE_TEXT = 'Free-Text';
 const MODE_B_ZONE1_PREFIX = '⚠ Brain unreachable; running on local graph only.';
 
@@ -79,7 +87,12 @@ const MODE_B_ZONE1_PREFIX = '⚠ Brain unreachable; running on local graph only.
 //   collision-safe lib/hmi/shape-f6-plan-review-renderer.cjs path; the umbrella 'F'
 //   branch continues to route to Phase 101-01's lib/hmi/shape-f6-renderer.cjs via
 //   JTBD logic preserved byte-stable per R1 invariant).
-const F_SUBSHAPES = ['F.0', 'F.1', 'F.2', 'F.3', 'F.4', 'F.5', 'F.6'];
+// Phase 120-01: 'F.7' Breakthrough Surface appended (CONTEXT.md D-07..D-10 + D-20). Closed-vocab
+//   5 verbs verbatim [Explore deeper]/[Confirm]/[File as decision]/[Dismiss]/[Back]; mandatory
+//   [Dismiss] guard (D-10). Routes to lib/hmi/shape-f7-breakthrough-renderer.cjs via the
+//   explicit requestedShape:'F.7' branch in dispatchShapeFSubShape. The umbrella 'F' branch
+//   does NOT resolve to F.7 -- breakthrough surfacing is opt-in via explicit dispatch.
+const F_SUBSHAPES = ['F.0', 'F.1', 'F.2', 'F.3', 'F.4', 'F.5', 'F.6', 'F.7'];
 const F_UMBRELLA = 'F';
 const JUST_TALK = 'JUST_TALK';
 const COMPACTION_VIOLATION_CODE = 'render_v2_compaction_violation';
@@ -175,6 +188,58 @@ function justTalkRefuse(requestedShape) {
   };
 }
 
+/**
+ * Phase 121-02 D-04: emit selector_pick event into the unified
+ * ~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl stream (Plan 121-00
+ * writer chokepoint). Wrapped in try/catch -- telemetry NEVER fails Larry's
+ * turn. Canon Part 8: room slug is sha256-hashed; payload fields are scalar
+ * enums / numbers / booleans only. The emit is gated by validateEventPayload
+ * inside writer.emit() so adversarial fixtures (Cypher in verb_chosen, etc.)
+ * cannot leak. Non-blocking: any thrown error is swallowed so the pickShape
+ * dispatch resolution still returns to the caller.
+ */
+function emitSelectorPickUnified(roomDir, subShape, rendered, payloadIn) {
+  try {
+    let writer;
+    try {
+      writer = require('../core/telemetry/writer.cjs');
+    } catch (_e) {
+      return; // missing writer module -- soft skip, do not crash dispatch
+    }
+    if (!writer || typeof writer.emit !== 'function') return;
+    const contract = (rendered && rendered.contract) ? rendered.contract : {};
+    const verbs = Array.isArray(contract.verbs) ? contract.verbs : [];
+    const mode = (typeof contract.mode === 'string') ? contract.mode : 'A';
+    const recommended = contract.recommended;
+    const payload = (payloadIn && typeof payloadIn === 'object') ? payloadIn : {};
+    const rankerConfidence = (typeof payload.rankerConfidence === 'number')
+      ? payload.rankerConfidence
+      : 0;
+    const recommendedRendered = (recommended !== null && recommended !== undefined)
+      ? true
+      : Boolean(payload.recommendedRendered);
+    const verbChosen = (typeof payload.verb_chosen === 'string' && payload.verb_chosen.length > 0)
+      ? payload.verb_chosen
+      : (typeof contract.recommended === 'string' ? contract.recommended : '');
+    const slugSource = (typeof roomDir === 'string' && roomDir.length > 0)
+      ? String(roomDir).split('/').filter(Boolean).pop() || roomDir
+      : (String(process.cwd()).split('/').filter(Boolean).pop() || 'default-room');
+    writer.emit('selector_pick', {
+      sub_shape: String(subShape || '').slice(0, 64),
+      mode: String(mode || 'A').slice(0, 64),
+      ranker_confidence: rankerConfidence,
+      recommended_rendered: Boolean(recommendedRendered),
+      options_count: Number.isInteger(verbs.length) ? verbs.length : 0,
+      room_slug_sha256: _sha256(slugSource),
+      verb_chosen: String(verbChosen || '').slice(0, 64),
+    });
+  } catch (_e) {
+    // Canon Part 8 validation failure or any other emit failure: swallow.
+    // The dispatch resolution must still return cleanly per non-blocking
+    // contract (selector-pick-capture test 3 verifies this).
+  }
+}
+
 /**
  * Phase 88.2-04: emit selector presentation telemetry. Wrapped in try/catch --
  * telemetry NEVER fails Larry's turn. Canon Part 8: LOCAL ledger only, room
@@ -354,6 +419,25 @@ function dispatchShapeFSubShape(requestedShape, args) {
       personaContext: (typeof payloadObj.personaContext === 'string' && payloadObj.personaContext.length > 0)
         ? payloadObj.personaContext : undefined,
     };
+  } else if (requestedShape === 'F.7') {
+    // Phase 120-01: F.7 Breakthrough Surface (closed-vocab; 5 verbs verbatim).
+    //   Per CONTEXT.md D-07: built NEW (not a reuse of F.4).
+    //   Per CONTEXT.md D-08: 5 verbs locked verbatim [Explore deeper]/[Confirm]/
+    //     [File as decision]/[Dismiss]/[Back].
+    //   Per CONTEXT.md D-10: [Dismiss] is MANDATORY (renderer asserts presence on
+    //     every render).
+    //   Per CONTEXT.md D-20: payload.breakthrough carries provenance.artifact_ids[] --
+    //     F.7 renderer refuses to render if artifact_ids.length === 0 (HARD FLOOR
+    //     structural enforcement at the surface layer; defense in depth on top of
+    //     writeBreakthrough's validateProvenance in lib/core/breakthrough/schema.cjs).
+    mod = safeRequire('./shape-f7-breakthrough-renderer.cjs');
+    fnName = 'renderShapeF7Breakthrough';
+    inputArgs = {
+      tier: tier,
+      header: callerHeader,
+      breakthrough: (payloadObj.breakthrough && typeof payloadObj.breakthrough === 'object') ? payloadObj.breakthrough : null,
+      more_count: (Number.isInteger(payloadObj.more_count) && payloadObj.more_count >= 0) ? payloadObj.more_count : 0,
+    };
   }
 
   if (!mod || typeof mod[fnName] !== 'function') {
@@ -496,6 +580,11 @@ function pickShape(args) {
         const payloadObj = (opts.payload && typeof opts.payload === 'object') ? opts.payload : {};
         if (payloadObj.emitTelemetry === true) {
           emitPresentationTelemetry(opts.roomDir, result.shape, result.rendered, operator);
+          // Phase 121-02 D-04: capture selector pick (88.2/125 ranker) into
+          // the unified ~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl
+          // stream (Plan 121-00 writer chokepoint). Non-blocking; never
+          // throws back to caller.
+          emitSelectorPickUnified(opts.roomDir, result.shape, result.rendered, payloadObj);
         }
       }
     }

package/lib/hmi/shape-f7-breakthrough-renderer.cjs

@@ -0,0 +1,222 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 120-01 -- Shape F.7 Breakthrough Surface renderer.
+ *
+ * Per CONTEXT.md D-07..D-10 (the 5 verbs LOCKED VERBATIM + closed-vocab + mandatory dismiss):
+ *   - Built NEW (D-07): F.4 maps content-to-user-actionable-observation;
+ *     F.7 maps user-actions-to-recognition-of-user-own-work. Different speech acts.
+ *   - 5 verbs LOCKED VERBATIM (D-08): [Explore deeper] / [Confirm] / [File as decision] /
+ *     [Dismiss] / [Back]. Order is structural, not stylistic.
+ *   - [File as decision] (D-09) emits breakthrough_filed_as_decision via the Plan 120-02
+ *     scanner consumer; F.7 only renders the verb -- it does NOT itself emit events.
+ *   - [Dismiss] (D-10) is MANDATORY -- the renderer asserts its presence; refuses to
+ *     render a contract without it (defense in depth against accidental drift).
+ *
+ * Per CONTEXT.md D-11..D-12 (top-1 with "More breakthroughs (N)" affordance):
+ *   - Top-1 surface; "More breakthroughs (N)" affordance for queued candidates.
+ *   - more_count is rendered in zones.footer IFF more_count > 0.
+ *
+ * Per CONTEXT.md D-20 HARD FLOOR (Cypher-provable):
+ *   - breakthrough.artifact_ids[] must be non-empty AT RENDER TIME. The renderer is
+ *     the second structural enforcement point (the first is writeBreakthrough in
+ *     Plan 120-00 schema.cjs). Defense in depth: if a caller somehow bypasses
+ *     writeBreakthrough's validateProvenance, F.7 refuses to render the surfacing.
+ *
+ * Per CONTEXT.md D-17 voice scaffold rule 3 (time anchor):
+ *   - The title line includes a human-readable time anchor (e.g., "in the last 8 hours")
+ *     derived from breakthrough.detected_at via formatTimeAnchor.
+ *
+ * Canon Part 3: F.7 IS a Decision Gate primitive instance. LOCAL context only
+ *   (the breakthrough artifact_ids + theme); BRAIN context is none (D-20 makes
+ *   breakthroughs locally Cypher-provable); SIGNAL context is none (cross-room
+ *   forbidden per Part 8).
+ *
+ * Canon Part 4: every choice is graph data. Each of the 5 verbs maps to a typed
+ *   event the Plan 120-02 scanner consumer emits at verb-dispatch time.
+ *
+ * Canon Part 8: zero Brain coupling. The renderer is pure: no FS reads, no DB
+ *   writes, no fetch calls. Mirrors the F.4 / F.6 pattern byte-for-byte.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ */
+'use strict';
+
+// D-08: the 5 verbs LOCKED VERBATIM. Object.freeze prevents accidental mutation
+// of the canonical array; downstream code that needs a mutable copy must call
+// F7_VERBS.slice() (the dispatcher does this in inputArgs).
+const F7_VERBS = Object.freeze([
+  'Explore deeper',
+  'Confirm',
+  'File as decision',
+  'Dismiss',
+  'Back',
+]);
+
+// D-10: structural index of 'Dismiss' in F7_VERBS. assertContractInvariants uses
+// this to surface a precise 'dismiss_required' reason when the contract drifts.
+const F7_DISMISS_INDEX = 3;
+
+// Map the four detector kinds Plan 120-00 emits to their canonical display
+// strings. Unknown kinds fall back to the raw kind string (and finally to
+// 'Pattern' if kind is falsy).
+const KIND_DISPLAY_NAMES = Object.freeze({
+  convergence: 'Convergence',
+  contradiction_resolved: 'Contradiction resolved',
+  cross_domain_analogy: 'Cross-domain analogy',
+  reverse_salient_closed: 'Reverse salient closed',
+});
+
+// D-17 rule 3: human-readable time anchor with bucket boundaries chosen to
+// match the spec examples (in the last hour / in the last N hours / today /
+// in the last day / this week / in the last two weeks / on YYYY-MM-DD).
+// D-06 ethical fence: ages > 14 days surface the calendar date verbatim so
+// the user can see exactly how stale the recognition is.
+function formatTimeAnchor(detected_at) {
+  const now = Date.now();
+  const ts = (typeof detected_at === 'number' && Number.isFinite(detected_at)) ? detected_at : now;
+  const ageMs = Math.max(0, now - ts);
+  const ageHours = ageMs / (3600 * 1000);
+  const ageDays = ageHours / 24;
+  if (ageHours < 1) return 'in the last hour';
+  if (ageHours < 8) return 'in the last ' + Math.floor(ageHours) + ' hours';
+  if (ageHours < 24) return 'today';
+  if (ageDays < 2) return 'in the last day';
+  if (ageDays < 7) return 'this week';
+  if (ageDays < 14) return 'in the last two weeks';
+  // Older than the 14-day ethical fence (D-06) -- include calendar date for transparency.
+  const d = new Date(ts);
+  const yyyy = d.getUTCFullYear();
+  const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(d.getUTCDate()).padStart(2, '0');
+  return 'on ' + yyyy + '-' + mm + '-' + dd;
+}
+
+// D-10 MANDATORY-Dismiss structural guard. Returns {ok:true} when the verbs
+// array deep-equals F7_VERBS; otherwise returns {ok:false, reason} with a
+// precise reason code so consumers can surface a meaningful error envelope.
+//
+// Reason codes:
+//   verb_count_mismatch -- verbs.length !== 5
+//   dismiss_required    -- the slot at F7_DISMISS_INDEX is not literally 'Dismiss'
+//   verb_order_mismatch -- some other slot diverges from the canonical array
+function assertContractInvariants(verbs) {
+  if (!Array.isArray(verbs) || verbs.length !== F7_VERBS.length) {
+    return { ok: false, reason: 'verb_count_mismatch' };
+  }
+  for (let i = 0; i < F7_VERBS.length; i++) {
+    if (verbs[i] !== F7_VERBS[i]) {
+      return { ok: false, reason: i === F7_DISMISS_INDEX ? 'dismiss_required' : 'verb_order_mismatch' };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Render the F.7 Breakthrough Surface.
+ *
+ * @param {object} args
+ * @param {number} [args.tier]         tier integer; informational only -- F.7 is closed-vocab
+ *                                     in every tier (no recommended marker; no mode branch)
+ * @param {string} [args.header]       caller-supplied header line; default 'Breakthrough'
+ * @param {object} args.breakthrough   the breakthrough candidate (must carry artifact_ids[])
+ * @param {number} [args.more_count]   non-negative integer; number of queued candidates
+ *                                     surfaced via the "More breakthroughs (N)" footer
+ * @param {string} [args.voice_line]   Phase 120-03 D-17 additive slot. When present + non-empty,
+ *                                     prepended as the first line of zones.body above the title.
+ *                                     Caller (Plan 120-03 scanner.surfaceBreakthrough) audits
+ *                                     the line via voice-scaffold.auditVoiceLine before passing;
+ *                                     this renderer does NOT re-audit (single source of truth).
+ *
+ * @returns {object} { zones: {header, body, footer}, contract: {...} }  OR
+ *                   { error: 'provenance_required' | 'dismiss_required' | 'verb_count_mismatch' | 'verb_order_mismatch' }
+ */
+function renderShapeF7Breakthrough(args) {
+  const a = (args && typeof args === 'object') ? args : {};
+  const more_count = (Number.isInteger(a.more_count) && a.more_count >= 0) ? a.more_count : 0;
+  const bk = a.breakthrough;
+
+  // D-20 HARD FLOOR defense in depth -- refuse to render a provenance-less
+  // breakthrough. The Plan 120-00 schema layer rejects writes with empty
+  // artifact_ids; this is the SECOND structural enforcement point at the
+  // surface layer (in case writeBreakthrough is somehow bypassed).
+  if (!bk || typeof bk !== 'object' || !Array.isArray(bk.artifact_ids) || bk.artifact_ids.length === 0) {
+    return { error: 'provenance_required' };
+  }
+
+  // Build the locked-verbatim verbs array and assert the D-10 invariants.
+  // Defense in depth: the source-of-truth F7_VERBS is Object.freeze-d above;
+  // assertContractInvariants on the mutable copy gives a final structural
+  // assertion before composition.
+  const verbs = F7_VERBS.slice();
+  const check = assertContractInvariants(verbs);
+  if (!check.ok) {
+    return { error: check.reason };
+  }
+
+  // Row 1 (title): kind capitalized + theme + time anchor.
+  // Theme is sliced to 120 chars at the surface layer (defense in depth on top
+  // of the schema-layer 200-char sanitizer in Plan 120-00).
+  const kindKey = (typeof bk.kind === 'string') ? bk.kind : '';
+  const kindDisplay = KIND_DISPLAY_NAMES[kindKey] || kindKey || 'Pattern';
+  const themeRaw = (typeof bk.theme === 'string') ? bk.theme : '';
+  const theme = themeRaw.slice(0, 120);
+  const timeAnchor = formatTimeAnchor(bk.detected_at || Date.now());
+  const titleLine = kindDisplay + (theme ? ': ' + theme : '') + ' (' + timeAnchor + ')';
+
+  // Row 2 (verbs): the 5 verbs in [X] brackets, separated by double-space.
+  // Bracket style matches the F.4 / F.6 closed-vocab convention.
+  const verbsLine = verbs.map(function (v) { return '[' + v + ']'; }).join('  ');
+
+  // Phase 120-03 D-17 additive: optional voice_line prepend.
+  //
+  // When args.voice_line is a non-empty string, it is prepended as the FIRST line
+  // of zones.body, above the title line. This is the conversational opener
+  // composed by Plan 120-03 voice-scaffold.composeBreakthroughVoiceLine. The
+  // caller (scanner.surfaceBreakthrough) audits the line via auditVoiceLine
+  // before passing; this renderer does NOT re-audit (single source of truth, no
+  // duplicated regex logic at the surface layer).
+  //
+  // The contract.verbs / freeTextOffered / recommended / breakthrough_id /
+  // more_count fields are PRESERVED byte-stably across both branches (with-line
+  // and without-line). Plan 120-01 11-test byte-stability invariant is preserved
+  // when voice_line is absent (the without-line branch is the legacy code path).
+  const voiceLineRaw = (typeof a.voice_line === 'string') ? a.voice_line : '';
+  const voiceLine = voiceLineRaw.length > 0 ? voiceLineRaw : '';
+  const body = voiceLine
+    ? (voiceLine + '\n' + titleLine + '\n' + verbsLine)
+    : (titleLine + '\n' + verbsLine);
+
+  const header = (typeof a.header === 'string' && a.header.length > 0) ? a.header : 'Breakthrough';
+  // D-11 affordance: only surface "More breakthroughs (N)" when N > 0; empty
+  // footer otherwise so the renderer never lies about queued candidates.
+  const footer = (more_count > 0) ? ('More breakthroughs (' + more_count + ')') : '';
+
+  return {
+    zones: {
+      header: header,
+      body: body,
+      signals: '',
+      footer: footer,
+    },
+    contract: {
+      shape: 'F.7',
+      keyboard: 'askuserquestion',
+      verbs: verbs,
+      freeTextOffered: false,    // closed-vocab; mirrors F.3 / F.4 / F.6 plan-review
+      mode: 'closed',
+      recommended: null,         // closed-vocab does not mark a recommended verb
+      breakthrough_id: bk.id,
+      more_count: more_count,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeF7Breakthrough: renderShapeF7Breakthrough,
+  F7_VERBS: F7_VERBS,
+  F7_DISMISS_INDEX: F7_DISMISS_INDEX,
+  formatTimeAnchor: formatTimeAnchor,
+  assertContractInvariants: assertContractInvariants,
+  KIND_DISPLAY_NAMES: KIND_DISPLAY_NAMES,
+};

package/lib/hmi/shape-f7-breakthrough-renderer.test.cjs

@@ -0,0 +1,233 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 120-01 Task 1 -- F.7 Breakthrough Surface renderer test suite.
+ *
+ * Per 120-01-PLAN.md behavior tests (11 tests):
+ *   T1  F7_VERBS verbatim lock (5 strings, exact order, Object.freeze invariant)
+ *   T2  F7_DISMISS_INDEX === 3 (zero-indexed position of 'Dismiss')
+ *   T3  renderShapeF7Breakthrough happy path (contract envelope)
+ *   T4  Two-row layout (title + verbs)
+ *   T5  [Dismiss] MANDATORY guard (D-10 -- assertContractInvariants refuses without 'Dismiss')
+ *   T6  D-20 HARD FLOOR -- empty artifact_ids returns {error: 'provenance_required'}
+ *   T7  "More breakthroughs (N)" affordance (D-11; only when more_count > 0)
+ *   T8  Closed-vocab carve-out -- contract.freeTextOffered === false; no Free-Text
+ *   T9  formatTimeAnchor buckets (in the last hour / today / this week / etc.)
+ *   T10 Canon Part 8 source-grep (zero brain-client / fetch brain.mindrian / cross-room aggregat*)
+ *   T11 Em-dash invariant (HARD RULE; zero U+2014 in the renderer source)
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ */
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RENDERER_PATH = path.resolve(__dirname, 'shape-f7-breakthrough-renderer.cjs');
+const renderer = require('./shape-f7-breakthrough-renderer.cjs');
+const {
+  renderShapeF7Breakthrough,
+  F7_VERBS,
+  F7_DISMISS_INDEX,
+  formatTimeAnchor,
+  assertContractInvariants,
+  KIND_DISPLAY_NAMES,
+} = renderer;
+
+// --- T1: F7_VERBS verbatim lock ---
+test('T1: F7_VERBS is the 5 verbs verbatim in exact order', () => {
+  assert.deepEqual(F7_VERBS, ['Explore deeper', 'Confirm', 'File as decision', 'Dismiss', 'Back']);
+  assert.equal(F7_VERBS.length, 5);
+});
+
+test('T1b: F7_VERBS is Object.freeze-d -- mutation does not change the array', () => {
+  const before = F7_VERBS.slice();
+  // Frozen arrays: push throws in strict mode OR silently no-ops in sloppy mode.
+  // Either way, the canonical array contents must be unchanged after the attempt.
+  try { F7_VERBS.push('Free-Text'); } catch (_e) { /* expected in strict */ }
+  assert.deepEqual(F7_VERBS.slice(0, 5), before);
+  assert.equal(F7_VERBS.length, 5, 'mutation must not extend the frozen array');
+});
+
+// --- T2: F7_DISMISS_INDEX ---
+test('T2: F7_DISMISS_INDEX === 3 (zero-indexed slot of Dismiss in F7_VERBS)', () => {
+  assert.equal(F7_DISMISS_INDEX, 3);
+  assert.equal(F7_VERBS[F7_DISMISS_INDEX], 'Dismiss');
+});
+
+// --- T3: happy path ---
+test('T3: renderShapeF7Breakthrough returns canonical {zones, contract} envelope', () => {
+  const now = Date.now();
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: {
+      id: 'bk:1',
+      kind: 'convergence',
+      theme: 'X',
+      confidence: 0.55,
+      artifact_ids: ['a1', 'a2', 'a3', 'a4'],
+      detected_at: now - 3600 * 1000,
+    },
+    more_count: 2,
+  });
+  assert.equal(typeof out, 'object');
+  assert.equal(out.contract.shape, 'F.7');
+  assert.deepEqual(out.contract.verbs, F7_VERBS);
+  assert.equal(out.contract.freeTextOffered, false);
+  assert.equal(out.contract.mode, 'closed');
+  assert.equal(out.contract.recommended, null);
+  assert.equal(out.contract.breakthrough_id, 'bk:1');
+  assert.equal(out.contract.more_count, 2);
+  assert.equal(typeof out.zones.header, 'string');
+  assert.equal(typeof out.zones.body, 'string');
+});
+
+// --- T4: two-row layout ---
+test('T4: zones.body contains title row + 5-verb row with [X] brackets', () => {
+  const now = Date.now();
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: {
+      id: 'bk:1',
+      kind: 'convergence',
+      theme: 'X',
+      artifact_ids: ['a1', 'a2', 'a3'],
+      detected_at: now - 1800 * 1000,
+    },
+    more_count: 0,
+  });
+  // Row 1: title with kind capitalized + theme + time anchor
+  assert.match(out.zones.body, /Convergence: X/);
+  assert.match(out.zones.body, /\(in the last hour\)/i);
+  // Row 2: 5 verbs in [X] brackets in the locked order
+  assert.match(out.zones.body, /\[Explore deeper\]/);
+  assert.match(out.zones.body, /\[Confirm\]/);
+  assert.match(out.zones.body, /\[File as decision\]/);
+  assert.match(out.zones.body, /\[Dismiss\]/);
+  assert.match(out.zones.body, /\[Back\]/);
+});
+
+// --- T5: D-10 mandatory Dismiss guard ---
+test('T5: assertContractInvariants refuses a verbs array missing Dismiss (D-10 MANDATORY)', () => {
+  // Direct invariant call: a verbs array with the same length but Dismiss replaced.
+  const broken = ['Explore deeper', 'Confirm', 'File as decision', 'NotDismiss', 'Back'];
+  const result = assertContractInvariants(broken);
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'dismiss_required');
+});
+
+test('T5b: assertContractInvariants refuses a wrong-count verbs array', () => {
+  const tooShort = ['Explore deeper', 'Confirm', 'File as decision', 'Dismiss'];
+  const r1 = assertContractInvariants(tooShort);
+  assert.equal(r1.ok, false);
+  assert.equal(r1.reason, 'verb_count_mismatch');
+
+  const wrong = ['Explore deeper', 'wrongverb', 'File as decision', 'Dismiss', 'Back'];
+  const r2 = assertContractInvariants(wrong);
+  assert.equal(r2.ok, false);
+  assert.equal(r2.reason, 'verb_order_mismatch');
+});
+
+// --- T6: D-20 HARD FLOOR -- empty artifact_ids ---
+test('T6: D-20 HARD FLOOR -- empty artifact_ids returns {error: provenance_required}', () => {
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: { id: 'bk:1', kind: 'convergence', theme: 'X', artifact_ids: [], detected_at: Date.now() },
+    more_count: 0,
+  });
+  assert.equal(typeof out, 'object');
+  assert.equal(out.error, 'provenance_required');
+  assert.equal(out.zones, undefined);
+  assert.equal(out.contract, undefined);
+});
+
+test('T6b: missing breakthrough returns provenance_required', () => {
+  const out = renderShapeF7Breakthrough({ tier: 1, more_count: 0 });
+  assert.equal(out.error, 'provenance_required');
+});
+
+test('T6c: artifact_ids not an array returns provenance_required', () => {
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: { id: 'bk:1', kind: 'convergence', theme: 'X', artifact_ids: 'not-array', detected_at: Date.now() },
+    more_count: 0,
+  });
+  assert.equal(out.error, 'provenance_required');
+});
+
+// --- T7: More breakthroughs (N) affordance ---
+test('T7: more_count > 0 renders "More breakthroughs (N)" in zones.footer', () => {
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: { id: 'bk:1', kind: 'convergence', theme: 'X', artifact_ids: ['a1'], detected_at: Date.now() },
+    more_count: 2,
+  });
+  assert.match(out.zones.footer, /More breakthroughs \(2\)/);
+});
+
+test('T7b: more_count === 0 leaves zones.footer empty (no affordance)', () => {
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: { id: 'bk:1', kind: 'convergence', theme: 'X', artifact_ids: ['a1'], detected_at: Date.now() },
+    more_count: 0,
+  });
+  assert.equal(out.zones.footer.indexOf('More breakthroughs'), -1);
+});
+
+// --- T8: closed-vocab carve-out ---
+test('T8: contract.freeTextOffered === false; verbs does NOT contain Free-Text', () => {
+  const out = renderShapeF7Breakthrough({
+    tier: 1,
+    breakthrough: { id: 'bk:1', kind: 'convergence', theme: 'X', artifact_ids: ['a1'], detected_at: Date.now() },
+    more_count: 0,
+  });
+  assert.equal(out.contract.freeTextOffered, false);
+  assert.equal(out.contract.verbs.indexOf('Free-Text'), -1);
+  assert.equal(out.contract.verbs.length, 5);
+});
+
+// --- T9: formatTimeAnchor buckets ---
+test('T9: formatTimeAnchor returns the correct bucket string per age', () => {
+  const now = Date.now();
+  // < 1 hour -> "in the last hour"
+  assert.equal(formatTimeAnchor(now - 30 * 60 * 1000), 'in the last hour');
+  // 1-8 hours -> "in the last N hours"
+  assert.match(formatTimeAnchor(now - 4 * 3600 * 1000), /in the last \d+ hours/);
+  // 8-24 hours -> "today"
+  assert.equal(formatTimeAnchor(now - 12 * 3600 * 1000), 'today');
+  // 1-2 days -> "in the last day"
+  assert.equal(formatTimeAnchor(now - 36 * 3600 * 1000), 'in the last day');
+  // 2-7 days -> "this week"
+  assert.equal(formatTimeAnchor(now - 4 * 24 * 3600 * 1000), 'this week');
+  // 7-14 days -> "in the last two weeks"
+  assert.equal(formatTimeAnchor(now - 10 * 24 * 3600 * 1000), 'in the last two weeks');
+  // > 14 days -> "on YYYY-MM-DD"
+  assert.match(formatTimeAnchor(now - 30 * 24 * 3600 * 1000), /^on \d{4}-\d{2}-\d{2}$/);
+});
+
+// --- T10: Canon Part 8 source-grep ---
+test('T10: Canon Part 8 invariant -- zero brain-client / brain.mindrian / cross-room aggregat in renderer source', () => {
+  const src = fs.readFileSync(RENDERER_PATH, 'utf8');
+  assert.equal(/require\([^)]*brain-client[^)]*\)/.test(src), false, 'must not require brain-client');
+  assert.equal(/fetch\([^)]*brain\.mindrian[^)]*\)/.test(src), false, 'must not fetch brain.mindrian');
+  assert.equal(/cross.{0,3}room.{0,3}aggregat/i.test(src), false, 'must not mention cross-room aggregat');
+});
+
+// --- T11: em-dash invariant ---
+test('T11: em-dash invariant -- zero U+2014 in renderer source (HARD RULE)', () => {
+  const src = fs.readFileSync(RENDERER_PATH, 'utf8');
+  // U+2014 is the em-dash. The test file itself avoids the literal char so this
+  // suite stays em-dash-free.
+  const emDash = String.fromCharCode(0x2014);
+  assert.equal(src.indexOf(emDash), -1, 'renderer source must contain zero em-dashes');
+});
+
+// --- Bonus: KIND_DISPLAY_NAMES sanity ---
+test('Bonus: KIND_DISPLAY_NAMES covers the four known detector kinds', () => {
+  assert.equal(KIND_DISPLAY_NAMES.convergence, 'Convergence');
+  assert.equal(KIND_DISPLAY_NAMES.contradiction_resolved, 'Contradiction resolved');
+  assert.equal(KIND_DISPLAY_NAMES.cross_domain_analogy, 'Cross-domain analogy');
+  assert.equal(KIND_DISPLAY_NAMES.reverse_salient_closed, 'Reverse salient closed');
+});