@skillstech/thunderlang 0.1.6

package/src/intent-graph.mjs

@@ -0,0 +1,346 @@
+// Canonical Intent Graph (intent-graph-v1, Section 4). One model all four systems
+// consume: nodes (Mission, Evidence, Outcome, Metric, Requirement, Guarantee, Never,
+// Unknown, Assumption, Question, Approval, ...) + typed relationships. Deterministic;
+// pure (no Node deps): browser-safe. OT/RM/ST read this; they do not re-parse .intent.
+
+import { slug, subjectName, skillRefId } from './parse.mjs';
+import { detectConflicts } from './conflict.mjs';
+import { buildLifecycle } from './lifecycle.mjs';
+import { analyzeDistributed } from './distributed.mjs';
+
+export const INTENT_GRAPH_SCHEMA = 'intent-graph-v1';
+
+function node(id, type, title, extra = {}) {
+  return {
+    id, type, title: title || null,
+    description: extra.description ?? null,
+    status: extra.status ?? 'draft',
+    owner: extra.owner ?? null,
+    classification: extra.classification ?? null,
+    confidence: extra.confidence ?? null,
+    source: extra.source ?? null,
+    tags: extra.tags ?? [],
+    createdTime: null, updatedTime: null, // deterministic; stamped by consumers
+  };
+}
+const rel = (from, type, to, extra) => (extra ? { from, type, to, ...extra } : { from, type, to });
+
+/**
+ * Build the canonical Intent Graph from a parsed AST.
+ * @param {object} ast (from parseIntent)
+ * @returns {{schema, missionId, nodes, relationships, summary}}
+ */
+export function buildIntentGraph(ast) {
+  const nodes = [];
+  const relationships = [];
+  const subject = subjectName(ast);
+  const mId = `mission.${slug(subject || 'unnamed')}`;
+  nodes.push(node(mId, 'Mission', ast.title || subject, {
+    description: ast.problem || ast.goal || null,
+    owner: ast.owner || null,
+    status: ast.approvals && ast.approvals.length ? 'approval-required' : 'draft',
+  }));
+  // Persona / customer the mission serves (product profile).
+  for (const [kind, name] of [['persona', ast.persona], ['customer', ast.customer]]) {
+    if (!name) continue;
+    const id = `persona.${slug(name)}`;
+    nodes.push(node(id, 'Persona', name, { description: kind }));
+    relationships.push(rel(mId, 'addresses', id));
+  }
+
+  for (const e of ast.evidence || []) {
+    const id = `evidence.${slug(e.name || 'evidence')}`;
+    nodes.push(node(id, 'Evidence', e.name, { classification: e.classification, confidence: e.confidence, source: e.source }));
+    relationships.push(rel(mId, 'supported_by', id));
+  }
+  for (const o of ast.outcomes || []) {
+    const id = `outcome.${slug(o.name || 'outcome')}`;
+    nodes.push(node(id, 'Outcome', o.name, { description: o.description }));
+    relationships.push(rel(mId, 'targets', id));
+  }
+  for (const m of ast.metrics || []) {
+    const id = `metric.${slug(m.name || 'metric')}`;
+    nodes.push(node(id, 'Metric', m.name, { description: [m.baseline && `baseline ${m.baseline}`, m.target && `target ${m.target}`, m.window && `window ${m.window}`].filter(Boolean).join('; ') || null }));
+    // Attach a metric to an outcome by name overlap, else to the mission. Use the SAME id
+    // computation as the outcome node (with its 'outcome' fallback) so the edge never dangles.
+    const ms = slug(m.name || 'metric');
+    const o = (ast.outcomes || []).find((x) => { const xs = slug(x.name || 'outcome'); return xs.includes(ms) || ms.includes(xs); });
+    relationships.push(rel(o ? `outcome.${slug(o.name || 'outcome')}` : mId, 'measured_by', id));
+  }
+  (ast.requires || []).forEach((r, i) => {
+    const id = `requirement.${slug(ast.mission)}.${i + 1}`;
+    nodes.push(node(id, 'Requirement', r, { classification: 'observed' }));
+    relationships.push(rel(mId, 'requires', id));
+  });
+  const emittedVerifs = new Set();
+  for (const g of ast.guarantees || []) {
+    const id = `guarantee.${g.id || slug(g.statement)}`;
+    nodes.push(node(id, 'Guarantee', g.statement, { status: g.verify && g.verify.length ? 'verify-declared' : 'unverified' }));
+    relationships.push(rel(mId, 'requires', id));
+    for (const v of g.verify || []) {
+      const vid = `verification.${slug(v)}`;
+      if (!emittedVerifs.has(vid)) { nodes.push(node(vid, 'VerificationRule', v, { status: 'verify-declared' })); emittedVerifs.add(vid); }
+      relationships.push(rel(id, 'verified_by', vid));
+    }
+  }
+  for (const n of ast.neverRules || []) {
+    const id = `never.${n.id || slug(n.statement)}`;
+    nodes.push(node(id, 'Never', n.statement, { status: n.verify && n.verify.length ? 'verify-declared' : 'unverified' }));
+    relationships.push(rel(mId, 'constrained_by', id));
+    for (const v of n.verify || []) {
+      const vid = `verification.${slug(v)}`;
+      if (!emittedVerifs.has(vid)) { nodes.push(node(vid, 'VerificationRule', v, { status: 'verify-declared' })); emittedVerifs.add(vid); }
+      relationships.push(rel(id, 'verified_by', vid));
+    }
+  }
+  // Global invariants , system-wide laws. The mission is constrained by each; verify -> edge.
+  for (const iv of ast.invariants || []) {
+    const id = `invariant.${iv.id || slug(iv.name)}`;
+    nodes.push(node(id, 'Invariant', iv.statement || iv.name, {
+      status: iv.verify && iv.verify.length ? 'verify-declared' : 'unverified',
+      description: iv.because || null,
+    }));
+    relationships.push(rel(mId, 'constrained_by', id));
+    for (const v of iv.verify || []) {
+      const vid = `verification.${slug(v)}`;
+      if (!emittedVerifs.has(vid)) { nodes.push(node(vid, 'VerificationRule', v, { status: 'verify-declared' })); emittedVerifs.add(vid); }
+      relationships.push(rel(id, 'verified_by', vid));
+    }
+  }
+  // Skills the mission requires , the Ownership Graph's skill<->intent join. Each Skill node id is
+  // the shared `skill:<slug>` namespace (IL owns the id shape; STCE the content), so every product
+  // references the same skill by the same id. The mission `requires_skill` each.
+  const emittedSkills = new Set();
+  for (const sk of ast.skills || []) {
+    const id = sk.id || skillRefId(sk.name);
+    if (!emittedSkills.has(id)) { nodes.push(node(id, 'Skill', sk.name, { status: 'required' })); emittedSkills.add(id); }
+    relationships.push(rel(mId, 'requires_skill', id));
+  }
+  for (const u of ast.unknowns || []) {
+    const id = `unknown.${slug(u.name || 'unknown')}`;
+    nodes.push(node(id, 'Unknown', u.name, { classification: 'unknown', owner: u.owner, status: 'unresolved' }));
+    relationships.push(rel(mId, 'depends_on', id));
+    if (u.resolveBefore) relationships.push(rel(id, 'blocks', `phase.${slug(u.resolveBefore)}`));
+  }
+  for (const q of ast.questions || []) {
+    const id = `question.${slug(q.name || 'question')}`;
+    nodes.push(node(id, 'Question', q.name, { classification: 'unknown', owner: q.askedOf, status: 'open' }));
+    relationships.push(rel(mId, 'depends_on', id)); // container edge (Question -> Mission via depends_on), matching Unknown
+    if (q.blocks) relationships.push(rel(id, 'blocks', `phase.${slug(q.blocks)}`));
+  }
+  for (const a of ast.assumptionDecls || []) {
+    const id = `assumption.${slug(a.name || 'assumption')}`;
+    nodes.push(node(id, 'Assumption', a.name, { classification: 'assumed', confidence: a.confidence, status: 'unvalidated' }));
+    relationships.push(rel(mId, 'depends_on', id));
+  }
+  const patternIds = new Set((ast.patterns || []).map((p) => `pattern.${slug(p.name || 'pattern')}`));
+  for (const exp of ast.experiences || []) {
+    const eId = `experience.${slug(exp.name || 'experience')}`;
+    nodes.push(node(eId, 'ExperienceContract', exp.name, { description: exp.goal || null, owner: exp.actor || null }));
+    relationships.push(rel(mId, 'represented_by', eId));
+    // Only link to a pattern the mission actually declares (a `follows` ref may not resolve).
+    for (const p of exp.follows || []) { const t = `pattern.${slug(p)}`; if (patternIds.has(t)) relationships.push(rel(eId, 'derived_from', t)); }
+    for (const j of exp.journeys || []) {
+      const jId = `journey.${slug(exp.name)}.${slug(j.name || 'journey')}`;
+      nodes.push(node(jId, 'Journey', j.name, { description: `${(j.steps || []).length} step(s)` }));
+      relationships.push(rel(eId, 'represented_by', jId));
+    }
+    for (const st of exp.states || []) {
+      const sId = `experience-state.${slug(exp.name)}.${slug(st.name || 'state')}`;
+      nodes.push(node(sId, 'ExperienceState', st.name, { status: st.hasRecovery ? 'recoverable' : 'defined' }));
+      relationships.push(rel(eId, 'requires', sId));
+    }
+  }
+  for (const pat of ast.patterns || []) {
+    nodes.push(node(`pattern.${slug(pat.name || 'pattern')}`, 'Pattern', pat.name, { description: `${(pat.requires || []).length} requirement(s)` }));
+  }
+  // Style intents , brand/visual language governing an experience. The whole node is
+  // `proposed` (design intent), and its accessibility target is never emitted as verified.
+  const experienceIds = new Set((ast.experiences || []).map((e) => `experience.${slug(e.name || 'experience')}`));
+  for (const si of ast.styleIntents || []) {
+    const stId = `style.${slug(si.name || 'style')}`;
+    const desc = [
+      si.purpose,
+      si.accessibilityTarget && `a11y target ${si.accessibilityTarget} (proposed)`,
+      si.tokens && si.tokens.length ? `${si.tokens.length} token(s)` : null,
+    ].filter(Boolean).join('; ') || null;
+    nodes.push(node(stId, 'StyleIntent', si.name, { description: desc, classification: 'proposed' }));
+    const target = si.appliesTo ? `experience.${slug(si.appliesTo)}` : null;
+    if (target && experienceIds.has(target)) relationships.push(rel(target, 'constrained_by', stId));
+    else relationships.push(rel(mId, 'requires', stId));
+  }
+  for (const role of ast.approvals || []) {
+    const id = `approval.${slug(ast.mission)}.${slug(role)}`;
+    nodes.push(node(id, 'Approval', role, { status: 'required', owner: role }));
+    relationships.push(rel(mId, 'approved_by', id));
+  }
+
+  (ast.roleConstraints || []).forEach((rc, i) => {
+    const id = `constraint.${slug(rc.role)}.${i + 1}`;
+    nodes.push(node(id, 'Constraint', rc.statement, { owner: rc.role }));
+    relationships.push(rel(mId, 'requires', id));
+  });
+  // Conflict `between`/`resolveBy` entries are informational references that may or may not
+  // name an emitted node; only edge to targets that actually exist so nothing dangles.
+  const existingIds = new Set(nodes.map((n) => n.id));
+  detectConflicts(ast).forEach((c, i) => {
+    const id = `conflict.${slug(c.name || String(i + 1))}`;
+    nodes.push(node(id, 'Conflict', c.name, { status: c.status, description: c.type }));
+    for (const b of c.between || []) {
+      const target = `constraint.${slug(b)}`;
+      if (existingIds.has(target)) relationships.push(rel(id, 'contradicts', target));
+    }
+    if (c.before) relationships.push(rel(id, 'blocks', `phase.${slug(c.before)}`));
+    for (const r of c.resolveBy || []) {
+      const target = `approval.${slug(ast.mission)}.${slug(r)}`;
+      if (existingIds.has(target)) relationships.push(rel(id, 'approved_by', target));
+    }
+  });
+
+  for (const raw of ast.lifecycles || []) {
+    const ir = buildLifecycle(raw);
+    const lId = `lifecycle.${slug(ir.name || 'lifecycle')}`;
+    nodes.push(node(lId, 'Lifecycle', ir.name, { description: `${ir.states.length} states, ${ir.transitions.length} transitions`, status: ir.initial ? 'defined' : 'draft' }));
+    relationships.push(rel(mId, 'represented_by', lId));
+    const stateSlugs = new Set();
+    for (const s of ir.states) {
+      const ss = slug(s);
+      stateSlugs.add(ss);
+      const sId = `lifecycle-state.${slug(ir.name)}.${ss}`;
+      nodes.push(node(sId, 'LifecycleState', s, { status: ir.terminals.includes(s) ? 'verified' : 'defined' }));
+      relationships.push(rel(lId, 'requires', sId));
+    }
+    for (const t of ir.transitions) {
+      // Transition metadata (name / within) rides ON the transitions_to edge, not the state node.
+      // Only emit for transitions between DECLARED states, so a transition that references an
+      // undefined state (flagged separately as IL-LIFE-001) never leaves a dangling edge.
+      if (t.from && t.to && stateSlugs.has(slug(t.from)) && stateSlugs.has(slug(t.to))) relationships.push(rel(
+        `lifecycle-state.${slug(ir.name)}.${slug(t.from)}`, 'transitions_to', `lifecycle-state.${slug(ir.name)}.${slug(t.to)}`,
+        (t.name || t.within) ? { name: t.name || null, within: t.within || null } : undefined,
+      ));
+    }
+  }
+
+  for (const dec of ast.decisions || []) {
+    const dId = `decision.${slug(dec.name || 'decision')}`;
+    nodes.push(node(dId, 'Decision', dec.name, { owner: dec.owner || null, description: `${(dec.rules || []).length} rules${dec.default ? ', default ' + dec.default : ''}` }));
+    relationships.push(rel(mId, 'requires', dId));
+    for (const r of dec.rules || []) {
+      const rId = `rule.${slug(dec.name)}.${slug(r.name || 'rule')}`;
+      nodes.push(node(rId, 'Rule', r.name, { description: r.when ? `when ${r.when} -> ${r.result}` : null }));
+      relationships.push(rel(dId, 'requires', rId));
+    }
+  }
+  for (const c of ast.commands || []) {
+    const id = `command.${slug(c.name || 'command')}`;
+    nodes.push(node(id, 'Command', c.name, { description: [c.idempotencyKey && 'idempotent', c.timeout && `timeout ${c.timeout}`, c.retry && `retry ${c.retry}`].filter(Boolean).join('; ') || null }));
+    relationships.push(rel(mId, 'requires', id));
+  }
+  for (const h of ast.handlers || []) {
+    const id = `handler.${slug(h.trigger || 'handler')}`;
+    nodes.push(node(id, 'FailureHandler', h.trigger, { description: (h.compensate || []).length ? `compensate ${h.compensate.join(', ')}` : null }));
+    relationships.push(rel(mId, 'constrained_by', id));
+  }
+
+  // ── System profile: capabilities + system contracts (interfaces) ──
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  for (const cap of ast.capabilities || []) {
+    const id = `capability.${slug(cap.name || 'capability')}`;
+    nodes.push(node(id, 'Capability', cap.name, { description: cap.description || null }));
+    relationships.push(rel(mId, 'requires', id));
+    // Link each declared member to the capability if it resolves to an emitted node.
+    for (const m of cap.implements || []) {
+      const target = [`command.${slug(m)}`, `decision.${slug(m)}`, `mission.${slug(m)}`].find((cand) => nodeIds.has(cand));
+      if (target) relationships.push(rel(id, 'implemented_by', target));
+    }
+  }
+  for (const iface of ast.interfaces || []) {
+    const id = `system-contract.${slug(iface.name || 'interface')}`;
+    const desc = [iface.provides.length && `provides ${iface.provides.join(', ')}`, iface.requires.length && `requires ${iface.requires.join(', ')}`, iface.slo && `slo ${iface.slo}`].filter(Boolean).join('; ') || null;
+    nodes.push(node(id, 'SystemContract', iface.name, { description: desc }));
+    relationships.push(rel(mId, 'requires', id));
+  }
+
+  // ── Design profile: design-system components + artifacts (mockups) ──
+  // Resolve a design reference to a Pattern / ExperienceContract / ExperienceState node.
+  const allIds = nodes.map((n) => n.id);
+  const resolveDesignTarget = (name) => {
+    const s = slug(name);
+    return [`pattern.${s}`, `experience.${s}`].find((c) => nodeIds.has(c))
+      || allIds.find((id) => id.startsWith('experience-state.') && id.endsWith(`.${s}`))
+      || null;
+  };
+  for (const comp of ast.components || []) {
+    const id = `design-component.${slug(comp.name || 'component')}`;
+    const desc = [comp.description, comp.variants.length && `variants: ${comp.variants.join(', ')}`, comp.tokens.length && `tokens: ${comp.tokens.join(', ')}`].filter(Boolean).join('; ') || null;
+    nodes.push(node(id, 'DesignComponent', comp.name, { description: desc }));
+    relationships.push(rel(mId, 'requires', id));
+    // Each experience state / pattern the component implements: <target> -implemented_by-> component.
+    for (const m of comp.implements || []) {
+      const target = resolveDesignTarget(m);
+      if (target) relationships.push(rel(target, 'implemented_by', id));
+    }
+  }
+  const componentNames = new Set((ast.components || []).map((c) => slug(c.name || '')));
+  for (const art of ast.artifacts || []) {
+    const id = `design-artifact.${slug(art.name || 'artifact')}`;
+    nodes.push(node(id, 'DesignArtifact', art.name, { source: art.ref || null, description: [art.kind && `kind ${art.kind}`, art.covers.length && `covers ${art.covers.join(', ')}`].filter(Boolean).join('; ') || null }));
+    relationships.push(rel(mId, 'represented_by', id));
+    // A covered component is represented_by this artifact (the mockup depicts it).
+    for (const c of art.covers || []) {
+      if (componentNames.has(slug(c))) relationships.push(rel(`design-component.${slug(c)}`, 'represented_by', id));
+    }
+  }
+
+  // ── Delivery profile: releases, outcome results, learnings ──
+  for (const r of ast.releases || []) {
+    const id = `release.${slug(r.name || 'release')}`;
+    nodes.push(node(id, 'Release', r.name, { status: r.status || 'planned', description: [r.version && `v${r.version}`, r.date && `date ${r.date}`, r.includes.length && `includes ${r.includes.join(', ')}`].filter(Boolean).join('; ') || null }));
+    relationships.push(rel(mId, 'released_in', id));
+  }
+  for (const res of ast.results || []) {
+    const id = `outcome-result.${slug(res.name || 'result')}`;
+    nodes.push(node(id, 'OutcomeResult', res.name, { description: [res.metric && `metric ${res.metric}`, res.value && `value ${res.value}`, res.baseline && `baseline ${res.baseline}`].filter(Boolean).join('; ') || null }));
+    // A result resolves the outcome it measures (Outcome -resulted_in-> OutcomeResult).
+    const outId = res.measures ? `outcome.${slug(res.measures)}` : null;
+    relationships.push(rel(nodeIds.has(outId) ? outId : mId, 'resulted_in', id));
+  }
+  const releaseNames = new Set((ast.releases || []).map((r) => slug(r.name || '')));
+  for (const l of ast.learnings || []) {
+    const id = `learning.${slug(l.name || 'learning')}`;
+    nodes.push(node(id, 'LearningArtifact', l.name, { description: l.description || null }));
+    // A learning is derived from its source release (if resolvable) or the mission.
+    const fromRelease = l.from && releaseNames.has(slug(l.from));
+    relationships.push(rel(id, 'derived_from', fromRelease ? `release.${slug(l.from)}` : mId));
+  }
+
+  // ── Outcome contracts: executable commitments binding an outcome to a target ──
+  for (const c of ast.outcomeContracts || []) {
+    const id = `outcome-contract.${slug(c.name || 'contract')}`;
+    const desc = [c.baseline && `baseline ${c.baseline}`, c.target && `target ${c.target}`, `${c.direction || 'higher'} is better`, c.window && `window ${c.window}`].filter(Boolean).join('; ') || null;
+    nodes.push(node(id, 'OutcomeContract', c.name, { owner: c.owner || null, description: desc }));
+    relationships.push(rel(mId, 'requires', id));
+    // The contract targets the outcome it governs and is measured by its metric (when they resolve).
+    const outId = c.outcome ? `outcome.${slug(c.outcome)}` : null;
+    if (nodeIds.has(outId)) relationships.push(rel(id, 'targets', outId));
+    const metId = c.metric ? `metric.${slug(c.metric)}` : null;
+    if (nodeIds.has(metId)) relationships.push(rel(id, 'measured_by', metId));
+  }
+
+  const byType = {};
+  for (const n of nodes) byType[n.type] = (byType[n.type] || 0) + 1;
+  return {
+    schema: INTENT_GRAPH_SCHEMA,
+    missionId: mId,
+    nodes,
+    relationships,
+    summary: {
+      nodes: nodes.length,
+      relationships: relationships.length,
+      byType,
+      unresolved: (ast.unknowns || []).length + (ast.questions || []).length,
+      conflicts: detectConflicts(ast).filter((c) => c.status === 'unresolved').length,
+      approvalsRequired: (ast.approvals || []).length,
+    },
+  };
+}

package/src/intent-ir.mjs

@@ -0,0 +1,144 @@
+// Intent IR (intent-ir-v1) , the ONE shared semantic representation the whole SkillsTech
+// ecosystem operates on: Intent Scanner, Intent Atlas, Intent Engine, Repo Mastery, Skills Tech
+// Talk, and OpenThunder all normalize into this, instead of each re-modeling a project.
+//
+// Design rule (anti-fork): Intent IR is a strict SUPERSET of the canonical Intent Graph
+// (intent-graph-v1). Every intent-graph-v1 node type and relationship type is included and keeps
+// its meaning, so a graph that validates today still validates as Intent IR , RepoMastery and
+// OpenThunder keep consuming intent-graph-v1 unchanged while new products consume the richer IR.
+// Pure ESM, zero Node deps (browser-safe).
+
+import { NODE_TYPES as GRAPH_NODE_TYPES, RELATIONSHIP_TYPES as GRAPH_REL_TYPES } from './intent-schema.mjs';
+
+export const IR_SCHEMA = 'intent-ir-v1';
+export const IR_EMBEDS = 'intent-graph-v1';
+
+// ── Node types, organized by tier (the intent-graph-v1 set is embedded via GRAPH_NODE_TYPES) ──
+const IR_ONLY_NODE_TYPES = [
+  // Organization / product context
+  'Organization', 'Workspace', 'Project', 'Repository', 'Application', 'System', 'Domain', 'Persona',
+  // Requirements / experience
+  'UserJourney', 'ExperienceFlow', 'Screen', 'BusinessRule', 'DomainConcept', 'GlossaryTerm', 'ProhibitedBehavior',
+  // Architecture
+  'ArchitectureDecision', 'SystemBoundary', 'TrustBoundary', 'Service', 'Component', 'Module', 'Package', 'File',
+  'Symbol', 'Class', 'Interface', 'Function', 'Method', 'Endpoint', 'Message', 'Queue',
+  // Data / infra
+  'DataModel', 'Database', 'Table', 'Schema', 'Migration', 'InfrastructureResource', 'Configuration', 'Dependency',
+  // Security / risk
+  'SecurityControl', 'Threat', 'Risk', 'Finding',
+  // Verification / delivery
+  'TestScenario', 'Verification', 'Change',
+  // Knowledge / learning
+  'LearningModule', 'LearningPath', 'Drill', 'Quiz', 'Flashcard', 'Misconception', 'LearnerConceptState',
+];
+
+// The full Intent IR node vocabulary = intent-graph-v1 nodes + the IR-only additions (deduped).
+export const IR_NODE_TYPES = [...new Set([...GRAPH_NODE_TYPES, ...IR_ONLY_NODE_TYPES])];
+
+const IR_ONLY_REL_TYPES = [
+  'produces', 'performs', 'contains', 'defines', 'belongs_to', 'exposes', 'publishes', 'consumes',
+  'stores', 'constrains', 'mitigates', 'affects', 'produces_evidence', 'contains_change', 'teaches',
+  'derived_from_artifact', 'assesses', 'prerequisite_for', 'has_state', 'appears_in', 'covers',
+  'implies_candidate_intent', 'governs', 'satisfies', 'conflicts_with',
+];
+export const IR_RELATIONSHIP_TYPES = [...new Set([...GRAPH_REL_TYPES, ...IR_ONLY_REL_TYPES])];
+
+// ── Provenance , where a fact came from. Load-bearing for "never show AI-inferred as confirmed." ──
+export const PROVENANCE = [
+  'user-authored', 'imported', 'deterministically-discovered', 'compiler-derived', 'test-derived',
+  'runtime-observed', 'ai-proposed', 'ai-generated', 'system-generated', 'human-approved', 'human-corrected',
+];
+// Which provenance may be treated as fact without human confirmation.
+export const FACTUAL_PROVENANCE = new Set([
+  'user-authored', 'deterministically-discovered', 'compiler-derived', 'test-derived', 'runtime-observed', 'human-approved', 'human-corrected',
+]);
+export const isFactualProvenance = (p) => FACTUAL_PROVENANCE.has(p);
+
+// ── Confidence taxonomy (richer than a bare percentage; every value is defined + explainable) ──
+export const IR_CONFIDENCE = ['Confirmed', 'Observed', 'Derived', 'Inferred', 'Speculative', 'Conflicted'];
+export const IR_CONFIDENCE_MEANING = {
+  Confirmed: 'Explicit approved intent exists and maps cleanly to implementation.',
+  Observed: 'Behavior is directly visible through deterministic analysis.',
+  Derived: 'Behavior follows reliably from several observed facts.',
+  Inferred: 'A plausible interpretation that requires human review.',
+  Speculative: 'Evidence is weak or incomplete.',
+  Conflicted: 'Different parts of the project imply incompatible intent.',
+};
+// Map intent-graph-v1's classification enum onto the IR confidence taxonomy (compat bridge).
+export function confidenceFromClassification(classification) {
+  switch (classification) {
+    case 'verified': case 'decided': return 'Confirmed';
+    case 'observed': return 'Observed';
+    case 'inferred': return 'Derived';
+    case 'proposed': return 'Inferred';
+    case 'assumed': return 'Speculative';
+    default: return 'Inferred';
+  }
+}
+
+export const SENSITIVITY = ['public', 'internal', 'confidential', 'restricted', 'secret'];
+export const RETENTION = ['ephemeral', 'short', 'standard', 'long', 'permanent'];
+export const REVIEW_STATUS = ['unreviewed', 'in-review', 'reviewed', 'needs-revalidation'];
+export const APPROVAL_STATUS = ['unapproved', 'proposed', 'approved', 'rejected'];
+
+// The canonical node envelope every Intent IR node carries (all optional except id + type).
+export const NODE_FIELDS = [
+  'id', 'type', 'title', 'summary', 'description', 'status', 'owner', 'source', 'sourceLocation',
+  'sourceType', 'version', 'hash', 'createdTime', 'updatedTime', 'confidence', 'provenance',
+  'reviewStatus', 'approvalStatus', 'permissions', 'sensitivity', 'retention', 'tags', 'evidence', 'metadata',
+];
+
+const NODE_SET = new Set(IR_NODE_TYPES);
+const REL_SET = new Set(IR_RELATIONSHIP_TYPES);
+
+/**
+ * Deterministic structural validation of an Intent IR document. Returns { valid, errors }.
+ * Honesty guard: a node whose provenance is not factual MUST carry a confidence, and MUST NOT be
+ * marked approved without review , so AI-inferred information is never presented as confirmed.
+ */
+export function validateIR(ir) {
+  const errors = [];
+  const err = (path, message) => errors.push({ path, message });
+  if (!ir || typeof ir !== 'object') return { valid: false, errors: [{ path: '', message: 'IR must be an object' }] };
+  if (ir.schema && ir.schema !== IR_SCHEMA) err('schema', `schema must be "${IR_SCHEMA}"`);
+  const nodes = Array.isArray(ir.nodes) ? ir.nodes : (err('nodes', 'nodes must be an array'), []);
+  const ids = new Set();
+  for (const [i, n] of nodes.entries()) {
+    if (!n || typeof n !== 'object') { err(`nodes[${i}]`, 'node must be an object'); continue; }
+    if (!n.id) err(`nodes[${i}].id`, 'node needs a stable id');
+    else if (ids.has(n.id)) err(`nodes[${i}].id`, `duplicate node id "${n.id}"`); else ids.add(n.id);
+    if (!NODE_SET.has(n.type)) err(`nodes[${i}].type`, `unknown node type "${n.type}"`);
+    if (n.provenance && !PROVENANCE.includes(n.provenance)) err(`nodes[${i}].provenance`, `unknown provenance "${n.provenance}"`);
+    if (n.confidence && !IR_CONFIDENCE.includes(n.confidence)) err(`nodes[${i}].confidence`, `unknown confidence "${n.confidence}"`);
+    if (n.sensitivity && !SENSITIVITY.includes(n.sensitivity)) err(`nodes[${i}].sensitivity`, `unknown sensitivity "${n.sensitivity}"`);
+    // Honesty guard.
+    if (n.provenance && !isFactualProvenance(n.provenance)) {
+      if (!n.confidence) err(`nodes[${i}].confidence`, `non-factual provenance "${n.provenance}" requires a confidence`);
+      if (n.approvalStatus === 'approved' && n.reviewStatus !== 'reviewed') err(`nodes[${i}].approvalStatus`, 'AI/inferred node cannot be "approved" without reviewStatus "reviewed"');
+    }
+  }
+  const rels = Array.isArray(ir.relationships) ? ir.relationships : (ir.relationships === undefined ? [] : (err('relationships', 'relationships must be an array'), []));
+  const isPlaceholder = (x) => String(x || '').startsWith('phase.');
+  for (const [i, r] of rels.entries()) {
+    if (!REL_SET.has(r?.type)) err(`relationships[${i}].type`, `unknown relationship type "${r?.type}"`);
+    // Both ends must resolve to a node, unless they are phase.* placeholders (blocks-phase edges).
+    if (r && !ids.has(r.from) && !isPlaceholder(r.from)) err(`relationships[${i}].from`, `dangling from "${r.from}"`);
+    if (r && !ids.has(r.to) && !isPlaceholder(r.to)) err(`relationships[${i}].to`, `dangling to "${r.to}"`);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Lift a canonical intent-graph-v1 document into Intent IR , additive, lossless. Each node keeps
+ * its id/type/title, and its classification becomes an IR confidence with compiler-derived
+ * provenance (deterministic output), so existing graphs flow into the shared IR with honest
+ * provenance and never as unverified "fact."
+ */
+export function graphToIR(graph, { provenance = 'compiler-derived' } = {}) {
+  const nodes = (graph?.nodes || []).map((n) => ({
+    ...n,
+    provenance: n.provenance || provenance,
+    confidence: n.confidence || (n.classification ? confidenceFromClassification(n.classification) : undefined),
+  }));
+  return { schema: IR_SCHEMA, embeds: IR_EMBEDS, missionId: graph?.missionId ?? null, nodes, relationships: graph?.relationships || [] };
+}