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

package/lib/core/navigation/synthetic-expert.cjs

@@ -0,0 +1,177 @@
+'use strict';
+/*
+ * Phase 164-02 -- synthetic-expert: the writeSyntheticExpertNode node-write
+ * chokepoint (E1 / D-164-S1). This is the WAVE 2 writer that mints the
+ * SyntheticExpert reusable-expert graph citizen the Wave-1 amendment froze into
+ * the node taxonomy (TRUTH_CLAIM_TYPES + aliases.yml + the promoteNodeStatus
+ * human-confirm gate). A high-value BONO team member, FILED from the
+ * room/team/personas .md files and promoted to a queryable node, re-invokable as
+ * a hat in future runs (164-SYNTHETIC-EXPERTS.md section 2).
+ *
+ * This module mirrors lib/core/navigation/typed-domain.cjs writeDomainNode
+ * VERBATIM in structure: the allow-list header note, the isPlainObject helper,
+ * the stable 31-multiplier hash id-minter, the additive-JSON-props discipline
+ * (the D-10 precedent), and the defensive never-throw contract. It is an
+ * allow-listed navigation submodule. It takes a db handle owned by the caller
+ * (via lib/core/room-db.cjs openRoomDb) EXACTLY like typed-domain.cjs /
+ * edges.cjs writeEdge: it NEVER requires node:sqlite and NEVER opens room.db
+ * itself, so it stays inside the navigation allow-list with zero substrate bypass.
+ *
+ * Canon Part 9 (the human gate, role 5): a SyntheticExpert is a TRUTH-CLAIM node
+ *   (it asserts which lens is worth keeping; the navigator decides). The writer
+ *   lands it at review_status 'proposed' (the column DEFAULT) and NEVER
+ *   auto-confirms it. Promotion to 'confirmed' rides the existing human
+ *   confirmNode(byUser) door; the Wave-1 TRUTH_CLAIM_TYPES extension makes the
+ *   promoteNodeStatus guard reject an agent-attributed confirm for free.
+ *
+ * Canon Part 8 (the generic-lens-only gate, the load-bearing constraint): the
+ *   frozen SYNTHETIC_EXPERT_FIELDS allow-list rejects ANY params key outside the
+ *   generic-lens set (forbidden_field) BEFORE any insert. The props bag carries
+ *   ONLY generic-lens metadata (hat / name / surname / archetype /
+ *   beautiful_question / research_approach / evidence_tier / invocation_count /
+ *   last_used / provenance). provenance carries the originating runId + domain
+ *   node ids as scalars/ids ONLY, NEVER venture prose. No venture body ever rides
+ *   the props. Zero network surface; pure LOCAL SQLite over a caller-owned handle.
+ *
+ * Canon Part 2: hat / name / surname / archetype IS the canonical team-member
+ *   identity (de Bono cognitive stance + main domain + sub-domain + 7-role lens).
+ *
+ * NO em-dashes anywhere in this file (CLAUDE.md HARD RULE).
+ */
+
+const { insertNode } = require('../node-insert.cjs');
+
+// The closed de Bono hat-color Set (Canon Part 2 team identity). A SyntheticExpert
+// hat MUST validate against this Set; writeSyntheticExpertNode rejects invalid_hat
+// otherwise. Mirrors the DOMAIN_NODE_TYPES frozen-Set idiom in typed-domain.cjs.
+const HAT_COLORS = Object.freeze(new Set([
+  'White', 'Red', 'Black', 'Yellow', 'Green', 'Blue',
+]));
+
+// The frozen generic-lens allow-list (164-SYNTHETIC-EXPERTS.md section 2 table).
+// This is the Part 8 gate: a params key outside this union is rejected
+// forbidden_field BEFORE any insert, so no venture body ever rides the props.
+// The camelCase caller keys map to the snake_case props bag below; the input
+// allow-list carries BOTH the camelCase input keys and the structural keys
+// (sessionId for the id-minter) so a caller bag is validated exactly.
+const SYNTHETIC_EXPERT_FIELDS = Object.freeze(new Set([
+  'hat', 'name', 'surname', 'archetype', 'beautifulQuestion', 'researchApproach',
+  'evidenceTier', 'invocationCount', 'lastUsed', 'provenance', 'sessionId',
+]));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// SYNTHETIC_EXPERT_NODE_ID(sessionId, hat, surname) -- the idempotent id-minter.
+// A crypto-free, dependency-free stable 31-multiplier hash over (hat + ':' +
+// surname) (mirrors DOMAIN_NODE_ID at typed-domain.cjs:75-83) keeps re-writing
+// the same (hat, surname, sessionId) an UPSERT, not a duplicate. Node id
+// 'expert:'+sid+':'+hash.
+function SYNTHETIC_EXPERT_NODE_ID(sessionId, hat, surname) {
+  const sid = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'nosession';
+  const h = typeof hat === 'string' && hat.length > 0 ? hat : 'nohat';
+  const s = typeof surname === 'string' && surname.length > 0 ? surname : 'nosurname';
+  const key = h + ':' + s;
+  let hash = 0;
+  for (let i = 0; i < key.length; i += 1) {
+    hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+  }
+  return 'expert:' + sid + ':' + hash.toString(16);
+}
+
+// writeSyntheticExpertNode(db, params) -- UPSERT a SyntheticExpert truth-claim node.
+//
+// params = { hat, name, surname, archetype?, beautifulQuestion?, researchApproach?,
+//   evidenceTier?, invocationCount?, lastUsed?, provenance?, sessionId? }.
+// type = 'SyntheticExpert', created_by 'system'. review_status lands 'proposed' by
+// the column DEFAULT and is NEVER promoted here (Part 9 role 5: a SyntheticExpert
+// is a truth-claim node; the human promotes via confirmNode(byUser)).
+//
+// The Part 8 generic-lens gate: ANY params key not in SYNTHETIC_EXPERT_FIELDS is
+// rejected forbidden_field BEFORE any insert. Properties bag is ADDITIVE JSON
+// only, snake_cased to the 164-SYNTHETIC-EXPERTS.md table keys; provenance carries
+// scalars/ids ONLY (never prose). Defensive: never throws on caller input; returns
+// { ok:false, reason }.
+function writeSyntheticExpertNode(db, params) {
+  if (!isPlainObject(params)) {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  // Part 8 generic-lens gate FIRST: reject any non-allow-listed key before any
+  // validation or write, so a venture-body field never even reaches the insert.
+  for (const key of Object.keys(params)) {
+    if (!SYNTHETIC_EXPERT_FIELDS.has(key)) {
+      return { ok: false, reason: 'forbidden_field', detail: String(key).slice(0, 40) };
+    }
+  }
+  const {
+    hat, name, surname, archetype, beautifulQuestion, researchApproach,
+    evidenceTier, invocationCount, lastUsed, provenance, sessionId,
+  } = params;
+  if (typeof hat !== 'string' || !HAT_COLORS.has(hat)) {
+    return { ok: false, reason: 'invalid_hat', detail: String(hat).slice(0, 40) };
+  }
+  if (typeof name !== 'string' || name.length === 0) {
+    return { ok: false, reason: 'invalid_name' };
+  }
+  if (typeof surname !== 'string' || surname.length === 0) {
+    return { ok: false, reason: 'invalid_surname' };
+  }
+  const sid = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'nosession';
+  // Provenance is scalars/ids ONLY (Part 8). Defensively coerce to the documented
+  // shape: a runId string + a domainNodeIds id-array; any prose-bearing extra key
+  // is dropped here (the props bag below copies ONLY these two fields).
+  const provIn = isPlainObject(provenance) ? provenance : {};
+  const prov = {
+    runId: typeof provIn.runId === 'string' ? provIn.runId : '',
+    domainNodeIds: Array.isArray(provIn.domainNodeIds)
+      ? provIn.domainNodeIds.filter((x) => typeof x === 'string')
+      : [],
+  };
+  // Additive JSON props ONLY (the D-10 precedent), snake_cased to the
+  // 164-SYNTHETIC-EXPERTS.md table. Defaults so the shape stays stable.
+  const props = {
+    hat: hat,
+    name: name,
+    surname: surname,
+    archetype: typeof archetype === 'string' ? archetype : '',
+    beautiful_question: typeof beautifulQuestion === 'string' ? beautifulQuestion : '',
+    research_approach: typeof researchApproach === 'string' ? researchApproach : '',
+    evidence_tier: typeof evidenceTier === 'string' ? evidenceTier : 'None',
+    invocation_count: Number.isFinite(invocationCount) ? invocationCount : 0,
+    last_used: Number.isFinite(lastUsed) ? lastUsed : 0,
+    provenance: prov,
+  };
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  const nodeId = SYNTHETIC_EXPERT_NODE_ID(sid, hat, surname);
+  const sourcePath = 'expert:' + sid + ':' + hat + ':' + surname;
+  try {
+    // Mint via the shared NOT-NULL-safe chokepoint (lands review_status DEFAULT
+    // 'proposed'). created_by='system' satisfies the Phase-109 CHECK; the writer
+    // NEVER promotes (Part 9 role 5: the human confirms via confirmNode).
+    insertNode(db, nodeId, 'SyntheticExpert', propsJson, {
+      source_path: sourcePath,
+      created_by: 'system',
+      // R17-02: 'extracted_fact' -- a SyntheticExpert is filed from real
+      // room/team/personas .md content, same "extracted from source" class
+      // as typed-entity.cjs. SyntheticExpert is a TRUTH_CLAIM_TYPES member
+      // (transitions.cjs), so it requires human confirmNode promotion.
+      epistemic_type: 'extracted_fact',
+    });
+  } catch (e) {
+    return { ok: false, reason: 'expert_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, node_id: nodeId, hat: hat };
+}
+
+module.exports = {
+  writeSyntheticExpertNode,
+  SYNTHETIC_EXPERT_FIELDS,
+  HAT_COLORS,
+  SYNTHETIC_EXPERT_NODE_ID,
+};

package/lib/core/navigation/transitions.cjs

@@ -0,0 +1,253 @@
+'use strict';
+// Phase 109-04 truth-state transition chokepoint. Per Phase 108 TRUTH-STATES.md L40-58
+// and L88. Every promoteNodeStatus call validates the transition pair against the
+// closed Set; logs a status_* memory_event; populates confirmed_by + confirmed_at when
+// transitioning to confirmed or validated.
+//
+// Canon Part 4: every status change is graph data; the memory_event row IS the audit
+// edge for the transition.
+// Canon Part 9: truth-state promotion is gated by the documented 8-transition closed
+// taxonomy; any other (from, to) pair is rejected.
+
+const { logEvent } = require('./memory-events.cjs');
+
+// CANON PART 9 v1.5 HUMAN-ATTRIBUTION GUARD (Phase 129.5-02 / D-02).
+// AGENT_IDENTITIES is the closed lowercased set of non-human callers that MUST
+// NOT confirm or validate a truth-claim node. The human-confirms-truth rule
+// (role 5) forbids any agent (larry / brain / system / assistant) from promoting
+// a truth-claim node to confirmed or validated. The guard fires before any
+// mutation. resolveByUser (confirm-node.cjs) coerces any of these out of a
+// USER.md identity so a poisoned file cannot smuggle an agent into a confirm.
+const AGENT_IDENTITIES = Object.freeze(new Set(['larry', 'brain', 'system', 'assistant']));
+
+// Truth-claim node types per the Canon Part 9 v1.5 audit-node carve-out (Plan
+// 129.5-01). Only these nodes assert something about the venture's world and so
+// require a human byUser to reach confirmed or validated. System-bookkeeping
+// nodes (memory_event / audit / focus) are EXEMPT: they record what the system
+// DID, not what is TRUE, so created_by=system is canon-legal for them.
+//
+// NAVIGATOR-GATED ADDITION (Phase 164-01, D-164-S1 / E1, canon v1.13 Appendix D
+// entry 24): SyntheticExpert is added as a truth-claim NODE type. A SyntheticExpert
+// is a reusable expert graph citizen (a high-value team member FILED from room /
+// team / personas .md files and re-invokable as a hat). It is a truth-claim node
+// because a HUMAN confirms which experts are worth keeping (Part 9 role 5: the
+// navigator decides). Because the promoteNodeStatus human-confirm-gate below
+// (lines ~92-96) keys on row.type via TRUTH_CLAIM_TYPES.has(row.type), this single
+// additive member AUTOMATICALLY gates a SyntheticExpert's proposed->confirmed
+// promotion exactly as it gates {claim, CausalClaim, assumption, decision,
+// opportunity}: an agent-attributed confirm is rejected, only a human byUser
+// promotes. The promoteNodeStatus signature and the TRANSITIONS table are
+// UNCHANGED. ADDITIVE only; never a rewrite (the FLOOR doctrine, mirroring the
+// edges.cjs ALLOWED_EDGE_TYPES additive moves of entries 18/21/22/23).
+const TRUTH_CLAIM_TYPES = Object.freeze(new Set(['claim', 'CausalClaim', 'assumption', 'decision', 'opportunity', 'SyntheticExpert']));
+
+// PHASE 181-01 SEC-01 NON_PROMOTABLE STRUCTURAL GUARD (D-181-01).
+// EvidenceClaim is the node type that carries UNTRUSTED EXTERNAL WEB BYTES into the
+// local graph (lib/core/navigation/evidence-claim.cjs writeEvidenceClaim). Canon
+// Part 8 (external content stays local and untrusted) + Part 9 role 5 promise that
+// such bytes never silently harden into trusted memory. This is a DEDICATED guard,
+// stronger than the truth-claim human-confirm gate: a human MAY confirm a truth-claim
+// node, but an EvidenceClaim can NEVER leave 'proposed' through promoteNodeStatus --
+// agent OR human attributed, to ANY non-proposed target status. It is NOT a
+// TRUTH_CLAIM_TYPES member: adding EvidenceClaim there would be a Part 9 frozen-set
+// move requiring a NEW canon amendment (entry 32), which the just-ratified entry-31
+// self-binding clause BLOCKS. So the bar is minted as this dedicated set instead --
+// no frozen-set move, no Brain wire, no canon amendment. TRUTH_CLAIM_TYPES above
+// stays BYTE-UNCHANGED (D-181-01).
+const NON_PROMOTABLE = Object.freeze(new Set(['EvidenceClaim']));
+
+// Closed Set of allowed (from, to) transitions. The Set member is 'from->to' string.
+const TRANSITIONS = Object.freeze(new Set([
+  'proposed->confirmed',
+  'proposed->needs_evidence',
+  'needs_evidence->validated',
+  'confirmed->validated',
+  'validated->invalidated',
+  'proposed->rejected',
+  'confirmed->superseded',
+  'confirmed->stale',
+]));
+
+// event_type for each transition.
+const EVENT_FOR_TRANSITION = Object.freeze({
+  'proposed->confirmed': 'status_promoted',
+  'proposed->needs_evidence': 'status_promoted',
+  'needs_evidence->validated': 'status_promoted',
+  'confirmed->validated': 'status_promoted',
+  'validated->invalidated': 'status_promoted',
+  'proposed->rejected': 'status_rejected',
+  'confirmed->superseded': 'status_superseded',
+  'confirmed->stale': 'status_stale',
+});
+
+function promoteNodeStatus(db, nodeId, fromStatus, toStatus, byUser, reason, opts) {
+  // Clock seam (opts.now) per Phase 160-04 D-01a so tests inject a fixed
+  // reference and the Phase 160 last_modified_at write-discipline stamps the
+  // reference now (getReferenceNow) rather than the raw system clock. Defaults
+  // to Date.now in production -- byte-compatible for every existing caller that
+  // passes no opts. Mirrors the logEvent(opts.now) seam in memory-events.cjs.
+  const options = opts && typeof opts === 'object' ? opts : {};
+  const nowFn = typeof options.now === 'function' ? options.now : Date.now;
+  // Phase 160-04 R8 non-lossy supersession close (D-bitemporal). When the caller
+  // (supersession.cjs) supplies opts.invalidatedAt / opts.validTo, the same
+  // chokepoint UPDATE that sets review_status='superseded' ALSO closes the
+  // bitemporal axes on the node -- so the fact is CLOSED, never deleted, and the
+  // whole close stays inside this one truth-state chokepoint (Canon Part 9: no
+  // side-door write). Only honoured on the non-confirmed branch (a close, never a
+  // confirm/validate). Both values are nullable epoch-ms scalars; absent opts keep
+  // every existing promoteNodeStatus caller byte-compatible.
+  const closeInvalidatedAt = Number.isFinite(options.invalidatedAt) ? options.invalidatedAt : null;
+  const closeValidTo = Number.isFinite(options.validTo) ? options.validTo : null;
+  const wantsBitemporalClose = closeInvalidatedAt !== null || closeValidTo !== null;
+  const key = fromStatus + '->' + toStatus;
+  if (!TRANSITIONS.has(key)) {
+    return { ok: false, reason: 'invalid_transition' };
+  }
+  const row = db.prepare('SELECT id, review_status, type FROM nodes WHERE id = ?').get(nodeId);
+  if (!row) {
+    return { ok: false, reason: 'unknown_node' };
+  }
+  // PHASE 181-01 SEC-01 NON_PROMOTABLE guard (D-181-01). An external-byte node type
+  // (EvidenceClaim) can NEVER harden into trusted memory: REJECT every promotion
+  // attempt -- agent OR human attributed, to ANY non-proposed target status -- BEFORE
+  // the state_mismatch check and before any mutation. Emit a rejection memory_event
+  // carrying ONLY enum/scalar handles + the node id (Part 8: no prose, never crosses
+  // to Brain). created_by 'system' because the rejection is a system-bookkeeping
+  // audit node (Part 9 v1.5 carve-out). ZERO signature change; the only net-new is
+  // this EvidenceClaim branch -- the TRANSITIONS table and the existing
+  // TRUTH_CLAIM_TYPES human-attribution guard are untouched.
+  if (NON_PROMOTABLE.has(row.type)) {
+    logEvent(db, 'evidence_claim_promotion_blocked', {
+      target_node_id: nodeId,
+      attempted_from: fromStatus,
+      attempted_to: toStatus,
+      attempted_by: AGENT_IDENTITIES.has(String(byUser || '').toLowerCase())
+        ? String(byUser).toLowerCase()
+        : 'user',
+      created_by: 'system',
+    });
+    return { ok: false, reason: 'evidence_claim_non_promotable' };
+  }
+  if (row.review_status !== fromStatus) {
+    return { ok: false, reason: 'state_mismatch', currentStatus: row.review_status };
+  }
+  // Phase 194-06 Task 2 (PSB-08/09/12): the optimistic lost-update reconcile
+  // guard, the FINER sibling of the state_mismatch check above. The coarse check
+  // catches a status flip; this catches a same-status content drift on the CAS
+  // token (last_modified_at). It arms ONLY when the caller supplies
+  // options.readVersion AND a live co-session shares the room (the presence
+  // fast-path -- a single-session turn resolves listLiveCoSessions to empty and
+  // pays zero cost, the load-bearing PSB-12 property). On drift (current token >
+  // readVersion) it returns WITHOUT overwriting so the caller raises a RECONCILE
+  // (F.9) instead of silently clobbering the co-session's write. Fail OPEN: any
+  // guard error degrades to the normal write. Additive: no readVersion -> no check
+  // (byte-identical to every existing caller).
+  if (options.readVersion !== undefined && options.readVersion !== null) {
+    try {
+      const presence = require('../session-presence.cjs');
+      const live = presence.listLiveCoSessions({
+        roomDir: options.roomDir,
+        room: options.room,
+        home: options.home,
+        sessionId: options.sessionId,
+      });
+      if (Array.isArray(live) && live.length > 0) {
+        const guard = require('./reconcile-guard.cjs');
+        const verdict = guard.checkLostUpdate(db, nodeId, options.readVersion);
+        if (verdict && verdict.conflict === true) {
+          return {
+            ok: false,
+            reason: 'lost_update',
+            reconcile: {
+              nodeId: nodeId,
+              held: toStatus,
+              readVersion: options.readVersion,
+              currentVersion: verdict.currentVersion,
+            },
+          };
+        }
+      }
+    } catch (_e) {
+      // Fail OPEN: a guard/presence failure never blocks a write.
+    }
+  }
+  const setsConfirmed = (toStatus === 'confirmed' || toStatus === 'validated');
+  // Human-attribution guard (Canon Part 9 v1.5 / D-02). A confirm or validate of a
+  // truth-claim node by an agent identity is REJECTED before any mutation. The
+  // carve-out exempts system-bookkeeping node types (memory_event / audit / focus):
+  // the guard keys on the node's type column, so only TRUTH_CLAIM_TYPES are gated.
+  // Non-confirm/non-validate transitions (reject / stale / superseded) are never
+  // gated -- an agent MAY reject or stale a node. The existing byUser default to
+  // system stays byte-compatible for every non-guarded path.
+  if (setsConfirmed
+      && TRUTH_CLAIM_TYPES.has(row.type)
+      && AGENT_IDENTITIES.has(String(byUser || '').toLowerCase())) {
+    return { ok: false, reason: 'agent_attribution_forbidden' };
+  }
+  const nowMs = nowFn();
+  db.exec('BEGIN');
+  try {
+    // Phase 160-04 R7 last_modified_at write discipline: every node-WRITE path
+    // ALSO sets last_modified_at to the reference now (the options.now seam),
+    // disambiguating a true modify-stamp from last_seen_at (which conflates
+    // read + write). A node READ never runs this UPDATE, so reading never
+    // bumps last_modified_at. Both branches below are write paths.
+    if (setsConfirmed) {
+      db.prepare('UPDATE nodes SET review_status = ?, confirmed_by = ?, confirmed_at = ?, last_seen_at = ?, last_modified_at = ? WHERE id = ?')
+        .run(toStatus, byUser || 'system', nowMs, nowMs, nowMs, nodeId);
+    } else if (wantsBitemporalClose) {
+      // R8 non-lossy close: set the bitemporal axes in the SAME chokepoint UPDATE.
+      db.prepare('UPDATE nodes SET review_status = ?, last_seen_at = ?, last_modified_at = ?, invalidated_at = ?, valid_to = ? WHERE id = ?')
+        .run(toStatus, nowMs, nowMs, closeInvalidatedAt, closeValidTo, nodeId);
+    } else {
+      db.prepare('UPDATE nodes SET review_status = ?, last_seen_at = ?, last_modified_at = ? WHERE id = ?')
+        .run(toStatus, nowMs, nowMs, nodeId);
+    }
+    const eventType = EVENT_FOR_TRANSITION[key];
+    // The memory_event audit node's created_by column carries a CHECK constraint
+    // (IN 'user','larry','import','brain','system'), so a human navigator identity
+    // (jonathan / navigator / founder) cannot be stored there directly. Map any
+    // non-agent, non-system human byUser to the canonical 'user' marker for the
+    // audit row's created_by column, while preserving the LITERAL human identity in
+    // the unconstrained confirmed_by payload field (and on the truth-claim node's
+    // own confirmed_by column above). System-bookkeeping and agent reject/stale
+    // paths keep their byUser-or-system value byte-compatible.
+    const literalBy = byUser || 'system';
+    const auditCreatedBy = AGENT_IDENTITIES.has(String(literalBy).toLowerCase()) || literalBy === 'system'
+      ? literalBy
+      : 'user';
+    const evRes = logEvent(db, eventType, {
+      target_node_id: nodeId,
+      previous_status: fromStatus,
+      new_status: toStatus,
+      reason: typeof reason === 'string' ? reason : null,
+      created_by: auditCreatedBy,
+      confirmed_by: literalBy,
+      source_path: 'transition:' + key,
+    });
+    if (!evRes.ok) {
+      db.exec('ROLLBACK');
+      return { ok: false, reason: 'event_log_failed:' + evRes.reason };
+    }
+    db.exec('COMMIT');
+    // Phase 194-06 Task 2: heartbeat this session's presence on a successful
+    // chokepoint write so a co-session's liveness window (the fast-path gate)
+    // stays fresh. Best-effort; only when the caller threads presence context.
+    if (options.sessionId && (options.roomDir || options.room)) {
+      try {
+        require('../session-presence.cjs').heartbeat({
+          sessionId: options.sessionId,
+          roomDir: options.roomDir,
+          room: options.room,
+          home: options.home,
+        });
+      } catch (_e) { /* fire-and-forget */ }
+    }
+    return { ok: true, eventId: evRes.eventId };
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_) { /* ignore */ }
+    return { ok: false, reason: err.message };
+  }
+}
+
+module.exports = { promoteNodeStatus, TRANSITIONS, EVENT_FOR_TRANSITION, AGENT_IDENTITIES, TRUTH_CLAIM_TYPES, NON_PROMOTABLE };

package/lib/core/navigation/typed-claim.cjs

@@ -0,0 +1,208 @@
+'use strict';
+/*
+ * Phase 150.8-01 -- typed-claim: the truth-claim node-write chokepoint for the
+ * meeting micro-knowledge DIKW ladder. This is the net-new `claim`-type writer
+ * the entire DIKW slice stands on (DIKW-01 / DIKW-03): the Claimify-style 4-pass
+ * extraction in the /mos:file-meeting path (Plan 03) calls writeClaimNode per
+ * ATOMIC claim, so a transcript that decomposes into K segments mints K claim
+ * nodes (the GATE-0 segmentation-authority consequence: extraction drives
+ * segmentation, the file-level cascade never fans out per segment).
+ *
+ * This module is an allow-listed navigation submodule (scripts/check-substrate.cjs
+ * regex /^lib\/core\/navigation\// covers it). It takes a db handle owned by the
+ * caller (via lib/core/room-db.cjs openRoomDb) EXACTLY like
+ * lib/core/navigation/evidence-claim.cjs writeEvidenceClaim and edges.cjs
+ * writeEdge: it NEVER requires node:sqlite and NEVER opens room.db itself, so it
+ * stays inside the navigation allow-list with zero substrate bypass. Hook-level
+ * event logging stays with the CALLER via navigation.logMemoryEvent -- this
+ * writer mints the node and nothing else.
+ *
+ * Canon Part 9 role 5 (the human gate): a claim is a TRUTH-CLAIM node in the
+ *   closed set {claim, CausalClaim, assumption, decision, opportunity} -- it
+ *   asserts something about the venture's world. So it lands review_status
+ *   'proposed' and is NEVER auto-confirmed by an agent. Promotion to 'confirmed'
+ *   requires a human APPROVE at a Decision Gate (routed through
+ *   navigation.confirmNode in Plan 04). This is NOT carved out by the Part 9 v1.5
+ *   audit-node carve-out -- it is a real truth claim, not system bookkeeping.
+ *
+ * Canon Part 8: zero network surface. Pure LOCAL SQLite over a caller-owned
+ *   handle. No Brain calls; no transcript content ever leaves the room. Only the
+ *   knowledge_type enum handle may ride to Brain downstream; the prose stays local.
+ *
+ * Schema discipline (the D-10 additive-JSON precedent, mirroring
+ *   evidence-claim.cjs:90-100): knowledge_type, text, conditions,
+ *   counter_conditions, valid_from, valid_until, source_speaker, source_segment,
+ *   and the optional AMB-01 disambiguation marker are ALL additive keys inside the
+ *   properties TEXT blob -- NEVER DDL columns. The `text` key is the atomic claim
+ *   sentence itself: it is validated as mandatory (invalid_text below) and is
+ *   persisted here so the read side (the tri-modal index props.text check) can
+ *   extract the claim's content. review_status is the ONLY CHECK-constrained column
+ *   (lib/core/migrations/phase-109-nodes-provenance.cjs); knowledge_type stays
+ *   OUT of DDL. Zero ALTER TABLE, zero new migration file.
+ *
+ * NO em-dashes anywhere in this file (CLAUDE.md HARD RULE).
+ */
+
+const { insertNode } = require('../node-insert.cjs');
+
+// The closed 6-member knowledge-type enum (CONTEXT in-scope item 1; the DIKW
+// taxonomy fact|causal|heuristic|anomaly_cue|mental_model|assumption). A claim's
+// knowledge_type MUST validate against this Set; writeClaimNode rejects
+// invalid_knowledge_type otherwise. Mirrors the EVIDENCE_TIERS frozen-Set idiom
+// in evidence-claim.cjs:48.
+const KNOWLEDGE_TYPES = Object.freeze(new Set([
+  'fact', 'causal', 'heuristic', 'anomaly_cue', 'mental_model', 'assumption',
+]));
+
+// Plan 276-12 (TOOLHON-07), OQ-276-1 ANSWER (b+d, .planning/phases/276-*/
+// 276-DECISIONS.md, ratified commit 26083bac): "map at the claim writer,
+// cap-comparison deferred". This table replaces the pre-276-12 hardcoded
+// `epistemic_type: 'extracted_fact'` constant that used to collapse all 6
+// KNOWLEDGE_TYPES members onto ONE node-insert.cjs epistemic_type -- see
+// writeClaimNode below. Placement here (next to KNOWLEDGE_TYPES, not inside
+// node-insert.cjs's generic fail-closed gate) honors node-insert.cjs:110-112's
+// own comment that per-writer mapping belongs at the call site.
+//
+// STATUS: the table's ROW CONTENT is executor-proposed (276-DECISIONS.md
+// marks it "PROPOSED, not navigator-ratified" -- only the placement and the
+// single-direction scope are ratified). Every value is a member of
+// node-insert.cjs's ALLOWED_EPISTEMIC_TYPES; the operator-cap comparison
+// against lib/conversation/operator.cjs's EPISTEMIC_LEVELS is a NAMED
+// follow-up owned by plan 276-16's close-out, not built here.
+const KNOWLEDGE_TYPE_TO_EPISTEMIC_TYPE = Object.freeze({
+  fact: 'extracted_fact',
+  causal: 'derived_fact',
+  heuristic: 'interpretation',
+  anomaly_cue: 'observation',
+  mental_model: 'model_derived_assertion',
+  assumption: 'assumption',
+});
+
+// Phase 223-02 (Req 4): the props keys writeClaimNode OWNS. An optional
+// extraProps bag (the conclusion marker kind/topic/topic_hash + the G-1
+// provenance tag pipeline/run_id) may merge additive keys into the props blob,
+// but it may NEVER override these fixed provenance keys -- exactly the
+// typed-opportunity.cjs protected-key discipline. knowledge_type + text are the
+// validated truth-claim identity; overriding them through a side bag would let a
+// caller mislabel a claim. review_status / type are never props keys at all, so
+// they can never be reached through extraProps either.
+const PROTECTED_CLAIM_KEYS = Object.freeze([
+  'knowledge_type', 'text', 'conditions', 'counter_conditions',
+  'valid_from', 'valid_until', 'source_speaker', 'source_segment', 'disambiguation',
+]);
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// CLAIM_NODE_ID(sessionId, segmentKey) -- the idempotent id-minter. A crypto-free,
+// dependency-free stable 31-multiplier hash over the segment key (mirrors
+// evidence-claim.cjs:110-117) keeps re-filing the same segment in the same
+// session an UPSERT, not a duplicate. Node id 'claim:'+sid+':'+hash.
+function CLAIM_NODE_ID(sessionId, segmentKey) {
+  const sid = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'nosession';
+  const key = typeof segmentKey === 'string' && segmentKey.length > 0 ? segmentKey : 'noseg';
+  let hash = 0;
+  for (let i = 0; i < key.length; i += 1) {
+    hash = (hash * 31 + key.charCodeAt(i)) >>> 0;
+  }
+  return 'claim:' + sid + ':' + hash.toString(16);
+}
+
+// writeClaimNode(db, params) -- UPSERT a typed truth-claim node.
+//
+// params = { knowledge_type, text, sessionId, sourceSegment?, sourceSpeaker?,
+//   conditions?, counter_conditions?, valid_from?, valid_until?, disambiguation? }.
+// type 'claim', created_by 'system', review_status 'proposed' (NEVER confirmed --
+// Canon Part 9 role 5). The DO UPDATE SET clause EXCLUDES review_status so a
+// human-confirmed claim re-projected by the extraction stays confirmed
+// (no-downgrade, copied verbatim from memory-artifacts.cjs writeDecisionNode).
+// Defensive: never throws on caller input; returns { ok:false, reason } on failure.
+function writeClaimNode(db, params) {
+  if (!isPlainObject(params)) {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const {
+    knowledge_type, text, sessionId, sourceSegment, sourceSpeaker,
+    conditions, counter_conditions, valid_from, valid_until, disambiguation,
+    extraProps,
+  } = params;
+  if (typeof knowledge_type !== 'string' || !KNOWLEDGE_TYPES.has(knowledge_type)) {
+    return { ok: false, reason: 'invalid_knowledge_type', detail: String(knowledge_type).slice(0, 40) };
+  }
+  if (typeof text !== 'string' || text.length === 0) {
+    return { ok: false, reason: 'invalid_text' };
+  }
+  // Additive JSON props ONLY (the D-10 precedent). Every temporal + provenance
+  // field defaults to '' so the shape is stable; knowledge_type rides the same
+  // blob, never a column.
+  const props = {
+    knowledge_type: knowledge_type,
+    text: text,
+    conditions: typeof conditions === 'string' ? conditions : '',
+    counter_conditions: typeof counter_conditions === 'string' ? counter_conditions : '',
+    valid_from: typeof valid_from === 'string' ? valid_from : '',
+    valid_until: typeof valid_until === 'string' ? valid_until : '',
+    source_speaker: typeof sourceSpeaker === 'string' ? sourceSpeaker : '',
+    source_segment: typeof sourceSegment === 'string' ? sourceSegment : '',
+  };
+  // AMB-01: the disambiguation marker is a PURELY ADDITIVE optional key consumed
+  // by the Plan 03 ambiguous-queue (disambiguation:'ambiguous'). It is NOT a new
+  // review_status member (the closed status set has no 'ambiguous'). Set only
+  // when the caller supplies a non-empty string, so the shape is byte-identical
+  // when absent.
+  if (typeof disambiguation === 'string' && disambiguation.length > 0) {
+    props.disambiguation = disambiguation;
+  }
+  // Phase 223-02 (Req 4): the OPTIONAL additive extraProps bag. The protected-key
+  // filter runs BEFORE the merge, so an extraProps bag can carry the conclusion
+  // marker (kind/topic/topic_hash) and the G-1 provenance tag (pipeline/run_id)
+  // WITHOUT overriding knowledge_type / text / any fixed provenance key and
+  // WITHOUT a new node type or schema change. A non-plain-object bag is ignored,
+  // and when extraProps is ABSENT the props shape is byte-identical to the
+  // pre-223 writer -- every existing caller is unaffected.
+  if (isPlainObject(extraProps)) {
+    for (const k of Object.keys(extraProps)) {
+      if (PROTECTED_CLAIM_KEYS.indexOf(k) === -1) props[k] = extraProps[k];
+    }
+  }
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  // Idempotency key off the segment (or the claim text when no segment id is
+  // supplied) so re-filing the same atomic claim UPSERTs rather than duplicating.
+  const sid = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : 'nosession';
+  const segmentKey = (typeof sourceSegment === 'string' && sourceSegment.length > 0) ? sourceSegment : text;
+  const nodeId = CLAIM_NODE_ID(sid, segmentKey);
+  const sourcePath = 'meeting:' + sid + ':' + (typeof sourceSegment === 'string' ? sourceSegment : 'inline');
+  try {
+    // review_status='proposed' on INSERT (TRUTH-CLAIM: never auto-confirmed).
+    // insertNode's DO UPDATE clause never touches review_status or confidence,
+    // so a human-confirmed claim re-projected by the system stays confirmed
+    // (no downgrade). That no-downgrade guarantee now lives inside insertNode.
+    insertNode(db, nodeId, 'claim', propsJson, {
+      source_path: sourcePath,
+      created_by: 'system',
+      confidence: 1.0,
+      review_status: 'proposed',
+      // Plan 276-12 (TOOLHON-07), OQ-276-1: per-knowledge_type mapping via
+      // KNOWLEDGE_TYPE_TO_EPISTEMIC_TYPE above, replacing the pre-276-12
+      // hardcoded 'extracted_fact' constant (R17-02, Task 4 Decision 4) that
+      // collapsed all 6 KNOWLEDGE_TYPES onto one epistemic_type. Always a
+      // hit: knowledge_type already validated against KNOWLEDGE_TYPES above,
+      // and every KNOWLEDGE_TYPES member has a row in the mapping table.
+      epistemic_type: KNOWLEDGE_TYPE_TO_EPISTEMIC_TYPE[knowledge_type],
+    });
+  } catch (e) {
+    return { ok: false, reason: 'claim_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, node_id: nodeId, knowledge_type: knowledge_type };
+}
+
+module.exports = {
+  writeClaimNode, KNOWLEDGE_TYPES, CLAIM_NODE_ID, PROTECTED_CLAIM_KEYS,
+  KNOWLEDGE_TYPE_TO_EPISTEMIC_TYPE,
+};