@skillstech/thunderlang 0.1.6

package/src/intent-schema.mjs

@@ -0,0 +1,215 @@
+// Canonical Intent Graph schema (intent-graph-v1) , the single source consumers
+// generate bindings from, so nobody hand-recreates node types / relationship types /
+// enums / diagnostics (gap-closure program non-negotiable #1). Pure (no Node deps).
+//
+// IL owns + versions this. OT/RM/ST/STW import these enums + the JSON Schema instead
+// of maintaining their own copies. `intent schema` emits the JSON Schema.
+
+import { CLASSIFICATIONS, CONFIDENCE } from './classification.mjs';
+
+export const SCHEMA_VERSION = 'intent-graph-v1';
+
+// Canonical node types (superset; Phase-1 emits a subset).
+export const NODE_TYPES = [
+  'Mission', 'Actor', 'Persona', 'Evidence', 'Opportunity', 'Outcome', 'Metric',
+  'Requirement', 'Constraint', 'Invariant', 'Guarantee', 'Never', 'Conflict', 'Journey',
+  'ExperienceContract', 'ExperienceState', 'Pattern', 'DesignArtifact', 'DesignComponent',
+  'StyleIntent', 'Capability', 'SystemContract', 'ImplementationMapping', 'VerificationRule',
+  'VerificationResult', 'Approval', 'Release', 'OutcomeContract', 'OutcomeResult', 'LearningArtifact',
+  'Unknown', 'Assumption', 'Question', 'Lifecycle', 'LifecycleState', 'Temporal',
+  'Command', 'Event', 'FailureHandler', 'Decision', 'Rule', 'Skill',
+];
+
+// Canonical relationship types.
+export const RELATIONSHIP_TYPES = [
+  'supported_by', 'derived_from', 'addresses', 'targets', 'measured_by', 'requires',
+  'constrained_by', 'implemented_by', 'represented_by', 'verified_by', 'approved_by',
+  'released_in', 'resulted_in', 'contradicts', 'supersedes', 'depends_on', 'blocks',
+  'teaches', 'generated_from', 'transitions_to', 'requires_skill',
+];
+
+export const NODE_STATUSES = [
+  'draft', 'proposed', 'approval-required', 'unresolved', 'unvalidated', 'open',
+  'required', 'verify-declared', 'unverified', 'verified', 'recoverable', 'defined', 'redundant',
+];
+
+/** The canonical JSON Schema (draft-07) for an intent-graph-v1 document. */
+export function intentGraphJsonSchema() {
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: `https://thunderlang.dev/schema/${SCHEMA_VERSION}.json`,
+    title: 'Intent Graph',
+    type: 'object',
+    required: ['schema', 'missionId', 'nodes', 'relationships'],
+    properties: {
+      schema: { const: SCHEMA_VERSION },
+      missionId: { type: 'string' },
+      nodes: { type: 'array', items: { $ref: '#/definitions/node' } },
+      relationships: { type: 'array', items: { $ref: '#/definitions/relationship' } },
+      summary: { type: 'object' },
+    },
+    definitions: {
+      node: {
+        type: 'object',
+        required: ['id', 'type'],
+        properties: {
+          id: { type: 'string' },
+          type: { enum: NODE_TYPES },
+          title: { type: ['string', 'null'] },
+          description: { type: ['string', 'null'] },
+          status: { type: ['string', 'null'] },
+          owner: { type: ['string', 'null'] },
+          classification: { type: ['string', 'null'], enum: [...CLASSIFICATIONS, null] },
+          confidence: { type: ['string', 'null'], enum: [...CONFIDENCE, null] },
+          source: { type: ['string', 'null'] },
+          tags: { type: 'array', items: { type: 'string' } },
+          createdTime: { type: ['string', 'null'] },
+          updatedTime: { type: ['string', 'null'] },
+        },
+      },
+      relationship: {
+        type: 'object',
+        required: ['from', 'type', 'to'],
+        properties: {
+          from: { type: 'string' },
+          type: { enum: RELATIONSHIP_TYPES },
+          to: { type: 'string' },
+        },
+      },
+    },
+  };
+}
+
+// Canonical diagnostic-rule catalog , stable IDs so every product uses the same ones.
+const IL_AUTHOR_RULE_ROWS = [
+  { ruleId: 'IL-PM-001', area: 'product', severity: 'warning', blocks: ['release'], summary: 'Metric has no measurement window.' },
+  { ruleId: 'IL-PM-003', area: 'product', severity: 'warning', blocks: [], summary: 'Outcome has no metric.' },
+  { ruleId: 'IL-EV-001', area: 'evidence', severity: 'info', blocks: [], summary: 'Evidence has no classification.' },
+  { ruleId: 'IL-EV-002', area: 'evidence', severity: 'warning', blocks: [], summary: 'Evidence has an unknown classification.' },
+  { ruleId: 'IL-GRAPH-010', area: 'graph', severity: 'blocker', blocks: ['<declared-phase>'], summary: 'Unresolved unknown blocks a phase.' },
+  { ruleId: 'IL-GRAPH-011', area: 'graph', severity: 'blocker', blocks: ['<declared-phase>'], summary: 'Open question blocks a phase.' },
+  { ruleId: 'IL-EXP-001', area: 'experience', severity: 'info', blocks: [], summary: 'Experience declares no states.' },
+  { ruleId: 'IL-EXP-004', area: 'experience', severity: 'blocker', blocks: ['experience-approval', 'release'], summary: 'Failure state has no recovery path.' },
+  { ruleId: 'IL-CONFLICT-001', area: 'conflict', severity: 'blocker', blocks: ['<declared-phase>'], summary: 'Declared conflict is unresolved.' },
+  { ruleId: 'IL-CONFLICT-010', area: 'conflict', severity: 'blocker', blocks: ['implementation'], summary: 'Scope includes and excludes the same item.' },
+  { ruleId: 'IL-CONFLICT-011', area: 'conflict', severity: 'info', blocks: [], summary: 'Redundant constraint from multiple roles.' },
+  { ruleId: 'IL-CONFLICT-012', area: 'conflict', severity: 'blocker', blocks: ['implementation'], summary: 'Directly contradictory constraints.' },
+  { ruleId: 'IL-GOV-001', area: 'governance', severity: 'error', blocks: [], summary: 'Waiver names no diagnostic code.' },
+  { ruleId: 'IL-GOV-002', area: 'governance', severity: 'error', blocks: [], summary: 'Waiver has no reason.' },
+  { ruleId: 'IL-GOV-003', area: 'governance', severity: 'error', blocks: [], summary: 'Waiver names no approver.' },
+  { ruleId: 'IL-GOV-004', area: 'governance', severity: 'warning', blocks: [], summary: 'Waiver matches no current diagnostic (stale).' },
+  { ruleId: 'IL-GOV-005', area: 'governance', severity: 'error', blocks: [], summary: 'Waiver has expired.' },
+  { ruleId: 'IL-DATA-001', area: 'privacy', severity: 'blocker', blocks: ['release'], summary: 'Sensitive data held with no stated purpose.' },
+  { ruleId: 'IL-DATA-002', area: 'privacy', severity: 'warning', blocks: [], summary: 'Sensitive data has no retention rule.' },
+  { ruleId: 'IL-DATA-003', area: 'privacy', severity: 'blocker', blocks: ['release'], summary: 'Sensitive data declares no lawful basis.' },
+  { ruleId: 'IL-DATA-004', area: 'privacy', severity: 'warning', blocks: [], summary: 'Data has an unknown classification.' },
+  { ruleId: 'IL-DATA-005', area: 'privacy', severity: 'warning', blocks: [], summary: 'Unrecognized lawful basis.' },
+  { ruleId: 'IL-DATA-006', area: 'privacy', severity: 'warning', blocks: [], summary: 'Sensitive data exposed as output with no guard.' },
+  { ruleId: 'IL-OC-001', area: 'outcome', severity: 'blocker', blocks: ['release'], summary: 'Outcome contract has no target (cannot be evaluated).' },
+  { ruleId: 'IL-OC-002', area: 'outcome', severity: 'warning', blocks: [], summary: 'Outcome contract names no metric.' },
+  { ruleId: 'IL-OC-003', area: 'outcome', severity: 'blocker', blocks: ['release'], summary: 'Outcome contract has no measurement window.' },
+  { ruleId: 'IL-OC-004', area: 'outcome', severity: 'warning', blocks: [], summary: 'Outcome contract target is not better than its baseline.' },
+  { ruleId: 'IL-OC-005', area: 'outcome', severity: 'warning', blocks: [], summary: 'Outcome contract has a target but no guardrails (the target is gameable).' },
+  { ruleId: 'IL-OC-006', area: 'outcome', severity: 'info', blocks: [], summary: 'Outcome contract has no attribution (correlation is not causation).' },
+  { ruleId: 'IL-DEC-001', area: 'decision', severity: 'blocker', blocks: ['implementation'], summary: 'Decision has no default (undefined when no rule matches).' },
+  { ruleId: 'IL-DEC-002', area: 'decision', severity: 'blocker', blocks: ['implementation'], summary: 'Two rules fire on the same condition with different results.' },
+  { ruleId: 'IL-DEC-003', area: 'decision', severity: 'info', blocks: [], summary: 'Redundant rule, identical to another (dead).' },
+  { ruleId: 'IL-DEC-004', area: 'decision', severity: 'warning', blocks: [], summary: 'Decision has no rules.' },
+  { ruleId: 'IL-DIST-001', area: 'distributed', severity: 'blocker', blocks: ['implementation'], summary: 'Retry without an idempotency key (duplicates work).' },
+  { ruleId: 'IL-DIST-002', area: 'distributed', severity: 'blocker', blocks: ['implementation'], summary: 'Retried or remote command with no timeout.' },
+  { ruleId: 'IL-DIST-003', area: 'distributed', severity: 'blocker', blocks: ['implementation'], summary: 'At-least-once delivery without duplicate handling.' },
+  { ruleId: 'IL-DIST-004', area: 'distributed', severity: 'blocker', blocks: ['implementation'], summary: 'Permanent failure with no compensation.' },
+  { ruleId: 'IL-DIST-005', area: 'distributed', severity: 'error', blocks: [], summary: 'Handler references an undeclared event.' },
+  { ruleId: 'IL-LIFE-001', area: 'lifecycle', severity: 'error', blocks: [], summary: 'Transition references an undefined state.' },
+  { ruleId: 'IL-LIFE-002', area: 'lifecycle', severity: 'warning', blocks: [], summary: 'Unreachable state.' },
+  { ruleId: 'IL-LIFE-003', area: 'lifecycle', severity: 'warning', blocks: [], summary: 'Non-terminal dead-end state (no way out).' },
+  { ruleId: 'IL-LIFE-004', area: 'lifecycle', severity: 'warning', blocks: [], summary: 'Lifecycle has no initial state.' },
+  { ruleId: 'IL-TEMP-001', area: 'temporal', severity: 'blocker', blocks: ['verification'], summary: 'Eventually with no time bound (cannot be verified).' },
+  { ruleId: 'IL-STYLE-001', area: 'style', severity: 'warning', blocks: [], summary: 'Style intent binds a token outside the canonical address space.' },
+  { ruleId: 'IL-STYLE-002', area: 'style', severity: 'warning', blocks: [], summary: 'Unrecognized accessibility target.' },
+  { ruleId: 'IL-STYLE-003', area: 'style', severity: 'info', blocks: [], summary: 'Style intent declares no accessibility target (a proposed claim).' },
+  { ruleId: 'IL-STYLE-004', area: 'style', severity: 'warning', blocks: [], summary: 'Invalid mode token value.' },
+  { ruleId: 'IL-STYLE-005', area: 'style', severity: 'info', blocks: [], summary: 'Style intent applies to an undeclared experience.' },
+  { ruleId: 'IL-SEC-001', area: 'security', severity: 'blocker', blocks: ['release'], summary: 'Secret-typed field travels over the event bus.' },
+  { ruleId: 'IL-SEC-002', area: 'security', severity: 'blocker', blocks: ['release'], summary: 'API returns a secret with no auth requirement.' },
+  { ruleId: 'IL-TYPE-001', area: 'type', severity: 'info', blocks: [], summary: 'Field uses an unrecognized (likely mistyped) type.' },
+  // 12-Factor Agents conformance (twelve-factor-v1). Advisory: an intent's alignment with the
+  // humanlayer/12-factor-agents principles. `intent twelve-factor` scores these.
+  { ruleId: 'IL-12F-01', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F1 Natural language to tool calls: model dispatch as a decision/command.' },
+  { ruleId: 'IL-12F-02', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F2 Own your prompts: behavior is an owned, guaranteed contract, not a black box.' },
+  { ruleId: 'IL-12F-03', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F3 Own your context window: declare a scope boundary.' },
+  { ruleId: 'IL-12F-04', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F4 Tools are structured outputs: typed I/O + discriminated results.' },
+  { ruleId: 'IL-12F-05', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F5 Unify execution + business state: one lifecycle/state model.' },
+  { ruleId: 'IL-12F-06', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F6 Launch/pause/resume: a resumable lifecycle with waiting + terminal states.' },
+  { ruleId: 'IL-12F-07', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F7 Contact humans with tool calls: a structured approval/human-input gate.' },
+  { ruleId: 'IL-12F-08', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F8 Own your control flow: decisions with an explicit default (total control flow).' },
+  { ruleId: 'IL-12F-09', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F9 Compact errors into context: named errors + handlers (bounded retry).' },
+  { ruleId: 'IL-12F-10', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F10 Small, focused agents: keep operations within ~10 steps (20 max).' },
+  { ruleId: 'IL-12F-11', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F11 Trigger from anywhere: declare event triggers.' },
+  { ruleId: 'IL-12F-12', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F12 Stateless reducer: pure, replayable decision/lifecycle logic.' },
+  { ruleId: 'IL-12F-13', area: 'twelve-factor', severity: 'info', blocks: [], summary: 'F13 Pre-fetch context: declare inputs so known data is fetched up front.' },
+];
+
+// Core check-surface diagnostics that predate the IL-* catalog. They keep their stable legacy
+// IDs (renaming would break consumers keyed on them), so they live here rather than in
+// DIAGNOSTIC_RULES (which is IL-* only). Documented + explainable all the same; consumers who
+// want the full set use ALL_DIAGNOSTICS below.
+const IL_CORE_RULE_ROWS = [
+  { ruleId: 'missing-goal', area: 'core', severity: 'warning', blocks: [], summary: 'Mission has no goal block.' },
+  { ruleId: 'duplicate-without-idempotency', area: 'core', severity: 'warning', blocks: [], summary: 'A duplicate-prevention guarantee declares no idempotency key or lookup rule.' },
+  { ruleId: 'guarantee-without-verification', area: 'core', severity: 'warning', blocks: [], summary: 'Guarantee has no explicit verification.' },
+  { ruleId: 'never-without-verification', area: 'core', severity: 'warning', blocks: [], summary: 'Never-rule has no explicit verification.' },
+  { ruleId: 'invariant-without-verification', area: 'core', severity: 'warning', blocks: [], summary: 'Global invariant has no explicit verification.' },
+  { ruleId: 'secret-without-never-log', area: 'core', severity: 'warning', blocks: [], summary: 'A secret field has no "never log/expose" guard.' },
+  { ruleId: 'error-name-not-pascalcase', area: 'core', severity: 'info', blocks: [], summary: 'Named error is not PascalCase.' },
+  { ruleId: 'unknown-block', area: 'core', severity: 'info', blocks: [], summary: 'Unrecognized top-level block.' },
+  { ruleId: 'INTENT-ARCH-001', area: 'architecture', severity: 'warning', blocks: [], summary: 'Architecture rule not understood.' },
+  { ruleId: 'INTENT-AI-010', area: 'ai', severity: 'warning', blocks: [], summary: 'Unsupported implementation scope.' },
+  { ruleId: 'INTENT_NOTE_UNKNOWN_LENS', area: 'note', severity: 'info', blocks: [], summary: 'IntentLens note uses an unknown lens.' },
+  { ruleId: 'INTENT_NOTE_EMPTY', area: 'note', severity: 'info', blocks: [], summary: 'IntentLens note is empty.' },
+];
+
+// ── Rule namespaces: ONE id space across two PHASES ──────────────────────────
+// The canonical catalog spans author-time (IL) and verify-time (OpenThunder). Every rule row
+// self-describes with `owner` ('IL' | 'OT') and `phase` ('author' | 'verify'), and prefix
+// ownership is declared in RULE_NAMESPACES, so a reader (or a coverage/diff lens) sees a single,
+// unambiguous rule catalog instead of two forks. IL owns author-time rules (checked when the
+// .intent is authored/compiled); OT owns verify-time rules (checked against the actual repo).
+// Additive: existing rows gain owner/phase; existing consumers keying on ruleId are unaffected.
+export const RULE_PHASES = ['author', 'verify'];
+export const RULE_OWNERS = ['IL', 'OT'];
+export const RULE_NAMESPACES = [
+  { prefix: 'IL-', owner: 'IL', phase: 'author', description: 'ThunderLang author-time catalog (compile-time).' },
+  { prefix: 'OT-', owner: 'OT', phase: 'verify', description: 'OpenThunder verify-time rules (repo vs intent). OT-owned; OT PRs the rows.' },
+];
+
+const stamp = (owner, phase) => (r) => ({ owner, phase, ...r });
+
+// IL author-time catalog (IL-* canonical + legacy core ids), stamped IL/author.
+export const DIAGNOSTIC_RULES = IL_AUTHOR_RULE_ROWS.map(stamp('IL', 'author'));
+export const CORE_DIAGNOSTICS = IL_CORE_RULE_ROWS.map(stamp('IL', 'author'));
+
+// OpenThunder verify-time namespace , RESERVED here so the id space is single-source; OT PRs the
+// row definitions. `reserved: true` marks a slot that OT owns and has not yet defined, so a
+// coverage/diff lens can see the id today without IL fabricating OT's rule semantics.
+export const VERIFICATION_RULES = [
+  'OT-REQ-001', 'OT-REQ-002', 'OT-REQ-003', 'OT-REQ-004', 'OT-REQ-005', 'OT-REQ-006',
+].map((ruleId) => ({
+  ruleId, area: 'verification', severity: 'error', blocks: ['<verify-time>'],
+  summary: 'Reserved for an OpenThunder verify-time rule; OT owns the definition.',
+  owner: 'OT', phase: 'verify', reserved: true,
+}));
+
+// The full set of documented rules: IL author-time catalog + legacy core codes + the reserved
+// OT verify-time namespace , one id space across both phases.
+export const ALL_DIAGNOSTICS = [...DIAGNOSTIC_RULES, ...CORE_DIAGNOSTICS, ...VERIFICATION_RULES];
+
+// Resolve which namespace (owner + phase) a rule id belongs to. Prefix-based for IL-/OT-, with the
+// legacy core ids (no IL-/OT- prefix) explicitly classified IL/author. Unknown ids return null.
+const IL_CORE_IDS = new Set(IL_CORE_RULE_ROWS.map((r) => r.ruleId));
+export function ruleNamespace(ruleId) {
+  const id = String(ruleId || '');
+  for (const ns of RULE_NAMESPACES) if (id.startsWith(ns.prefix)) return { owner: ns.owner, phase: ns.phase };
+  if (IL_CORE_IDS.has(id)) return { owner: 'IL', phase: 'author' };
+  return null;
+}

package/src/ledger.mjs

@@ -0,0 +1,109 @@
+// Intent Ledger (intent-ledger-v1) , the append-only, tamper-evident record of MEANING and history
+// for a project: provenance, decisions, assumptions, approvals, rejections, corrections, candidate
+// intent, confidence changes, evidence, findings, risk-acceptance, implementation hashes,
+// verification results, lesson versions, ownership, and change. It answers the questions a project
+// loses over time: why was this built, who approved it, what assumptions were made, which code
+// implements it, which tests prove it, what changed, which lessons went stale, which risks were
+// accepted, which inferred intent was corrected.
+//
+// Every entry is hash-chained (each hashes over the previous), so the ledger is tamper-evident ,
+// you cannot quietly rewrite history. Deterministic; the caller supplies timestamps so the ledger
+// is reproducible and testable.
+
+import { sha256 } from './emit.mjs';
+
+export const LEDGER_SCHEMA = 'intent-ledger-v1';
+
+export const ENTRY_TYPES = [
+  'intent-version', 'decision', 'assumption', 'approval', 'rejection', 'correction',
+  'candidate-intent', 'confidence-change', 'evidence', 'finding', 'risk-acceptance',
+  'implementation-hash', 'verification-result', 'lesson-version', 'ownership', 'change',
+];
+
+export function emptyLedger() {
+  return { schema: LEDGER_SCHEMA, entries: [], head: null };
+}
+
+// Canonical, order-stable payload so the hash is reproducible.
+function payloadOf(seq, entry, prev) {
+  return {
+    seq,
+    type: entry.type,
+    subject: entry.subject ?? null,
+    actor: entry.actor ?? null,
+    at: entry.at ?? null,
+    note: entry.note ?? null,
+    data: entry.data ?? {},
+    prev,
+  };
+}
+
+/** Append an entry to the ledger, hash-chained over the previous head. Returns a NEW ledger. */
+export function record(ledger, entry) {
+  if (!entry || !ENTRY_TYPES.includes(entry.type)) throw new Error(`intent ledger: unknown entry type "${entry?.type}"`);
+  const base = ledger && Array.isArray(ledger.entries) ? ledger : emptyLedger();
+  const payload = payloadOf(base.entries.length, entry, base.head);
+  const hash = sha256(JSON.stringify(payload));
+  const rec = { ...payload, hash };
+  return { ...base, entries: [...base.entries, rec], head: hash };
+}
+
+/** Record several entries in order. */
+export function recordAll(ledger, entries) {
+  return (entries || []).reduce((l, e) => record(l, e), ledger || emptyLedger());
+}
+
+/** Verify the hash chain , tamper-evidence. Returns { valid, brokenAt }. */
+export function verifyLedger(ledger) {
+  let prev = null;
+  const entries = ledger?.entries || [];
+  for (let i = 0; i < entries.length; i += 1) {
+    const e = entries[i];
+    const expected = sha256(JSON.stringify(payloadOf(i, e, prev)));
+    if (e.seq !== i) return { valid: false, brokenAt: i, reason: `entry ${i} has seq ${e.seq}` };
+    if (e.prev !== prev) return { valid: false, brokenAt: i, reason: `entry ${i} prev-link does not match` };
+    if (e.hash !== expected) return { valid: false, brokenAt: i, reason: `entry ${i} hash does not match its content (tampered)` };
+    prev = e.hash;
+  }
+  if (entries.length && ledger.head !== prev) return { valid: false, brokenAt: entries.length - 1, reason: 'head does not match the last entry' };
+  return { valid: true, brokenAt: null };
+}
+
+// ── Typed convenience recorders , the common facts a project preserves ────────
+const rec = (type) => (ledger, subject, data = {}, meta = {}) => record(ledger, { type, subject, ...meta, data });
+export const recordIntentVersion = rec('intent-version');   // data: { hash, version }
+export const recordDecision = rec('decision');              // note: the rationale ("why")
+export const recordAssumption = rec('assumption');
+export const recordApproval = rec('approval');              // actor: approver
+export const recordRejection = rec('rejection');
+export const recordCorrection = rec('correction');          // data: { from, to } , inferred intent a human fixed
+export const recordRiskAcceptance = rec('risk-acceptance'); // data: { finding, reason, expires }
+export const recordVerification = rec('verification-result'); // data: { passed, evidence }
+export const recordFinding = rec('finding');
+export const recordLessonVersion = rec('lesson-version');   // data: { version, stale }
+
+// ── Queries , the Ledger answers ─────────────────────────────────────────────
+const of = (ledger) => ledger?.entries || [];
+export const history = (ledger, subject) => of(ledger).filter((e) => !subject || e.subject === subject);
+export const whyBuilt = (ledger, subject) => history(ledger, subject).filter((e) => e.type === 'decision');
+export const approvalsFor = (ledger, subject) => history(ledger, subject).filter((e) => e.type === 'approval' || e.type === 'rejection');
+export const assumptionsFor = (ledger, subject) => history(ledger, subject).filter((e) => e.type === 'assumption');
+export const correctionsFor = (ledger, subject) => history(ledger, subject).filter((e) => e.type === 'correction');
+export const acceptedRisks = (ledger) => of(ledger).filter((e) => e.type === 'risk-acceptance');
+export const staleLessons = (ledger) => of(ledger).filter((e) => e.type === 'lesson-version' && e.data?.stale);
+export const verificationsFor = (ledger, subject) => history(ledger, subject).filter((e) => e.type === 'verification-result');
+
+/** A structured answer to the nine Ledger questions for one subject (mission). */
+export function explain(ledger, subject) {
+  return {
+    schema: LEDGER_SCHEMA,
+    subject,
+    why: whyBuilt(ledger, subject).map((e) => e.note || e.data?.reason).filter(Boolean),
+    approvedBy: approvalsFor(ledger, subject).filter((e) => e.type === 'approval').map((e) => e.actor).filter(Boolean),
+    assumptions: assumptionsFor(ledger, subject).map((e) => e.note || e.data).filter(Boolean),
+    verifications: verificationsFor(ledger, subject).map((e) => e.data),
+    corrections: correctionsFor(ledger, subject).map((e) => e.data),
+    acceptedRisks: acceptedRisks(ledger).filter((e) => !subject || e.subject === subject).map((e) => e.data),
+    changeCount: history(ledger, subject).length,
+  };
+}

package/src/lifecycle.mjs

@@ -0,0 +1,56 @@
+// Temporal + lifecycle semantics (Gap 2). IL owns the formal state-machine IR and the
+// STATIC model analysis (well-formedness, reachability, dead-ends) on the DECLARED
+// lifecycle. OpenThunder verifies the IMPLEMENTED reality against this IR and produces
+// counterexample traces. Pure (no Node deps): browser-safe. Deterministic.
+
+/**
+ * Build the formal IR for one lifecycle: states, terminals, the initial state (the one
+ * with no inbound transition), the adjacency map, and the reachable set from initial.
+ */
+export function buildLifecycle(lc) {
+  const states = [...new Set(lc.states || [])];
+  const terminals = [...new Set(lc.terminals || [])];
+  const transitions = lc.transitions || [];
+  const out = {};
+  for (const s of states) out[s] = [];
+  for (const t of transitions) if (out[t.from]) out[t.from].push(t.to);
+  // initial = the first declared state (the canonical start). The earlier "first state with no
+  // inbound transition" heuristic was wrong whenever the start state has a back-edge: in a cycle
+  // (e.g. A -> B -> A) every cyclic state has inbound, so it wrongly picked an isolated terminal.
+  const initial = states[0] ?? null;
+  // reachability (DFS from initial).
+  const reachable = new Set();
+  const stack = initial ? [initial] : [];
+  while (stack.length) {
+    const s = stack.pop();
+    if (reachable.has(s)) continue;
+    reachable.add(s);
+    for (const n of out[s] || []) stack.push(n);
+  }
+  return { name: lc.name, states, terminals, initial, transitions, out, reachable: [...reachable].sort() };
+}
+
+/** Static analysis of a declared lifecycle. Returns { ir, findings } (deterministic). */
+export function analyzeLifecycle(lc) {
+  const ir = buildLifecycle(lc);
+  const stateSet = new Set(ir.states);
+  const reachable = new Set(ir.reachable);
+  const findings = [];
+
+  for (const t of lc.transitions || []) {
+    for (const [side, s] of [['from', t.from], ['to', t.to]]) {
+      if (s && !stateSet.has(s)) findings.push({ code: 'IL-LIFE-001', message: `Transition "${t.name || '(unnamed)'}" ${side} references undefined state "${s}".` });
+    }
+  }
+  for (const term of ir.terminals) {
+    if (!stateSet.has(term)) findings.push({ code: 'IL-LIFE-001', message: `Terminal "${term}" is not a declared state.` });
+    else if ((ir.out[term] || []).length) findings.push({ code: 'IL-LIFE-002', message: `Terminal state "${term}" has an outgoing transition.` });
+  }
+  for (const s of ir.states) {
+    if (!reachable.has(s)) findings.push({ code: 'IL-LIFE-003', message: `State "${s}" is unreachable from the initial state.` });
+    else if (!ir.terminals.includes(s) && (ir.out[s] || []).length === 0) {
+      findings.push({ code: 'IL-LIFE-004', message: `Non-terminal state "${s}" has no outgoing transition (dead end).` });
+    }
+  }
+  return { ir, findings };
+}