@skillstech/thunderlang 0.1.6

package/src/index.mjs

@@ -0,0 +1,185 @@
+// Public library entry for @skillstech/thunderlang.
+//
+// This is the importable API for consumers (e.g. SkillsTech Studio, Repo Mastery):
+//   import { parseIntent, compileSource, buildMissionIndex } from '@skillstech/thunderlang';
+// The `intent` CLI (src/cli.mjs) is the other entry point; both use these same functions,
+// so there is no duplicated compiler logic. Curated on purpose: only the stable public
+// surface is re-exported here.
+
+// Parsing
+export { parseIntent, slug, KNOWN_LENSES } from './parse.mjs';
+
+// Semantic analysis, graphs, and proof
+export {
+  semanticDiagnostics,
+  buildContractGraph,
+  buildArchitectureGraph,
+  buildImplementationPlan,
+  buildProof,
+  sha256,
+  sha256hex,
+  COMPILER_VERSION,
+  PROOF_SCHEMA_VERSION,
+  SOURCE_PRODUCT,
+} from './emit.mjs';
+
+// Canonical proof envelope schema (intent-proof-v1) , the shared, signable proof shape
+export {
+  PROOF_SCHEMA, CLAIM_STATUSES, PROOF_STATUSES, intentProofJsonSchema, validateProof,
+} from './proof-schema.mjs';
+
+// Compile + render (docs, Mermaid, test plan)
+export { compileSource, renderMarkdown, renderLensDoc, renderMermaid, renderTestplan } from './compile.mjs';
+
+// IntelliSense (completions / hover)
+export { getCompletions, getHover, getCodeActions, autocorrectSource, SEMANTIC_TYPES } from './intellisense.mjs';
+
+// IntentLift (code -> inferred intent)
+export {
+  liftSource,
+  liftAll,
+  liftRepo,
+  languageForFile,
+  inferIntent,
+  renderLiftedIntent,
+  SUPPORTED_LANGUAGES,
+  SEED_SCHEMA,
+  normalizeSeeds,
+} from './lift.mjs';
+
+// Approve + drift round-trip (il-to-ot-drift-v1 handoff)
+export { approveIntent, checkDrift, buildDriftHandoff, intentHash } from './drift.mjs';
+
+// Mission Atlas index (mission-index-v1)
+export { buildMissionIndex } from './atlas.mjs';
+
+// Architecture rules (structured; OpenThunder's Architecture Lens checks against them)
+export { parseArchitectureRules, violatesArchitecture } from './arch.mjs';
+
+// Deterministic candidate selection (AI generates; IL + OT select on measurable rules)
+export { parseSelection, regionMetrics, selectCandidate } from './select.mjs';
+
+// Canonical Intent Graph + classification (intent-graph-v1) , the shared cross-product model
+export { buildIntentGraph, INTENT_GRAPH_SCHEMA } from './intent-graph.mjs';
+// Intent Atlas , the navigable/searchable whole-system map over the graph (directive #4)
+export { buildAtlas, atlasNode, expandNode, searchAtlas, ATLAS_SCHEMA } from './intent-atlas.mjs';
+export { diffGraphs, mergeGraphs } from './semantic-diff.mjs';
+export { CLASSIFICATIONS, CONFIDENCE, UNSETTLED, classify, isFactual, BLOCKABLE_PHASES } from './classification.mjs';
+export { composeConstraints, detectConflicts } from './conflict.mjs';
+export { buildLifecycle, analyzeLifecycle } from './lifecycle.mjs';
+export { analyzeDistributed } from './distributed.mjs';
+export { analyzeDecision } from './decision.mjs';
+// Governance: waivers , governed exceptions to blocking diagnostics (Gap 5)
+export { applyWaivers, governanceDiagnostics, GOVERNANCE_SCHEMA } from './governance.mjs';
+// Data purpose + privacy , purpose limitation on declared data elements (Gap 6)
+export { analyzePrivacy, PRIVACY_SCHEMA, DATA_CLASSIFICATIONS, LAWFUL_BASES } from './privacy.mjs';
+// Export adapters , decisions/lifecycles/temporal -> DMN / BPMN / NuSMV (interop)
+export { toDMN, toBPMN, toSMV, toMermaid, toPlaywright, exportIntent, EXPORT_FORMATS } from './exporters.mjs';
+// Data-shape export , typed fields -> JSON Schema / OpenAPI
+export { toJSONSchema, toOpenAPI, typeToJsonSchema, isRecognizedType } from './data-schema.mjs';
+// Import adapters , external DMN / BPMN -> ThunderLang source (round-trip)
+export { fromDMN, fromBPMN, importIntent, importReport, detectFormat, IMPORT_FORMATS, IMPORT_SCHEMA } from './importers.mjs';
+// Graph -> source , regenerate .intent from an Intent Graph (native round-trip)
+export { graphToSource, GRAPH_SOURCE_SCHEMA } from './graph-source.mjs';
+// Schema migrations , upgrade persisted graphs across schema versions
+export {
+  migrateGraph, validateGraph, graphVersion, MIGRATIONS, SCHEMA_CHAIN, MIGRATION_SCHEMA,
+  renameNodeType, renameRelationshipType, backfillNodeField, dropNodeField,
+} from './migrate.mjs';
+export { parseXml, findAll, find, localName } from './xml.mjs';
+// Intent Runtime , EXECUTABLE intent: evaluate decisions, simulate lifecycles (no AI)
+export { evaluateDecision, simulateLifecycle, checkDecisionCases, RUNTIME_SCHEMA } from './runtime.mjs';
+export { compileExpr, evalExpr, tokenize, ExprError } from './expr.mjs';
+// First-class tests , self-verifying .intent files
+export { runTests, TEST_SCHEMA } from './testing.mjs';
+// Outcome contracts , executable commitments (evaluate an outcome against its result)
+export { evaluateOutcomeContract, evaluateOutcomes, outcomeDiagnostics, parseValue, OUTCOME_SCHEMA } from './outcome.mjs';
+// Security + type semantic pass , secrets on the bus, unauthenticated sensitive output, typos
+export { securityDiagnostics, SECURITY_SCHEMA } from './security.mjs';
+// SARIF 2.1.0 output , ThunderLang diagnostics in GitHub/GitLab code scanning + IDEs
+export { toSarif, sarifLevel, SARIF_SCHEMA } from './sarif.mjs';
+// Human <-> Structured <-> ThunderLang sync , Studio edits structured, IL stays source of truth
+export { parseToStructured, proposeIntent, SYNC_SCHEMA } from './sync.mjs';
+// Structural source editing , apply field edits in place, preserving comments + formatting
+export { applyEdits, PATCH_SCHEMA } from './patch.mjs';
+// Repo-wide intent health report (aggregate diagnostics + coverage across many files)
+export { buildReport, REPORT_SCHEMA } from './report.mjs';
+// Fable , the versioned rule authority + rich finding model (over the diagnostic catalog)
+export { FABLE_SCHEMA, RISK_CATEGORIES, fableRuleFor, universalPack, toFinding } from './fable.mjs';
+// Intent Scanner , intent -> Intent IR -> Fable findings -> risk themes (deterministic pipeline)
+export { scanIntent, scanProject, SCAN_SCHEMA } from './scan.mjs';
+// Intent Lens , Intent Scope + Focus Graph + Intent Brief (a focused subgraph of the Atlas)
+export { FOCUS_SCHEMA, SCOPE_TYPES, FOCUS_REASONS, makeScope, buildFocusGraph, intentBrief } from './focus.mjs';
+// Comprehension Contract , the C0..C7 understanding level (intent-comprehension-v1)
+export { COMPREHENSION_SCHEMA, LEVELS as COMPREHENSION_LEVELS, comprehensionLevel, comprehensionReport } from './comprehension.mjs';
+// Code generation , deterministic scaffolds from intent (intent-codegen-v1)
+export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava } from './codegen.mjs';
+// Change Lens , what a branch/PR changed by meaning (intent-changes-v1)
+export { CHANGES_SCHEMA, changeReport } from './changes.mjs';
+export { exprToJs, exprToCSharp, exprToJava, exprToCode } from './expr.mjs';
+export { subjectName, intentRefId, skillRefId } from './parse.mjs';
+// 12-Factor Agents conformance lens (twelve-factor-v1)
+export { TWELVE_FACTOR_SCHEMA, twelveFactorReport, twelveFactorSummary } from './twelve-factor.mjs';
+// Focused scanner query views (Part 3): risks / gaps / unverified / coverage / unknowns / contradictions
+export {
+  VIEW_SCHEMA, VIEWS, risksView, gapsView, unverifiedView, coverageView, unknownsView, contradictionsView,
+} from './scan-queries.mjs';
+// Intent Guardian , continuous drift detection (what changed, what risk, what to reverify, stale learning)
+export { guardianReport, GUARDIAN_SCHEMA } from './guardian.mjs';
+// Intent Simulator , estimate a change's impact BEFORE implementation (blast radius + risk)
+export { simulateChange, SIMULATE_SCHEMA } from './simulate.mjs';
+// Intent Ledger , tamper-evident, append-only record of provenance, decisions, approvals, history
+export {
+  LEDGER_SCHEMA, ENTRY_TYPES, emptyLedger, record, recordAll, verifyLedger,
+  recordIntentVersion, recordAssumption, recordApproval, recordRejection,
+  recordCorrection, recordRiskAcceptance, recordVerification, recordFinding, recordLessonVersion,
+  history, whyBuilt, approvalsFor, acceptedRisks, correctionsFor, staleLessons, explain,
+  recordDecision as recordLedgerDecision,
+} from './ledger.mjs';
+// Intent AI event sink , the append-only audit log of intent-ai-v1 events
+export {
+  EVENT_LOG_SCHEMA, emptyEventLog, recordEvent, parseEventLog, serializeEventLog,
+  eventsFor, eventsOfType, timeline,
+} from './ai-events.mjs';
+// Verify a code change against its intent , the AI generate/verify loop gate
+export { verifyDiff, VERIFY_DIFF_SCHEMA } from './verify-diff.mjs';
+// MCP server , ThunderLang as a native tool for AI coding agents
+export { startMcpServer, MCP_TOOLS } from './mcp.mjs';
+// Runtime enforcement , compile intent into a guard that blocks forbidden actions + redacts secrets
+export { buildGuard, compileGuard, guardSummary, GUARD_SCHEMA } from './guard.mjs';
+// Prompt -> intent (deterministic half) , scaffold a rigorous draft + gap checklist from a brief
+export { draftIntent, DRAFT_SCHEMA } from './draft.mjs';
+// Style intent , brand/visual language as a governed Experience-profile extension
+export {
+  analyzeStyle, styleDiagnostics, toDesignTokens, toCss, STYLE_SCHEMA, DESIGN_TOKENS_SCHEMA,
+  TOKEN_PATHS, BRAND_PATHS, STYLE_ADDRESS_SPACE, ACCESSIBILITY_TARGETS, MODE_VALUES,
+  ACCESSIBILITY_CLASSIFICATION,
+} from './style.mjs';
+export {
+  SCHEMA_VERSION, NODE_TYPES, RELATIONSHIP_TYPES, NODE_STATUSES,
+  intentGraphJsonSchema, DIAGNOSTIC_RULES, CORE_DIAGNOSTICS, ALL_DIAGNOSTICS,
+  RULE_PHASES, RULE_OWNERS, RULE_NAMESPACES, VERIFICATION_RULES, ruleNamespace,
+} from './intent-schema.mjs';
+// Intent IR (intent-ir-v1) , the shared ecosystem semantic representation (superset of the graph)
+export {
+  IR_SCHEMA, IR_EMBEDS, IR_NODE_TYPES, IR_RELATIONSHIP_TYPES, PROVENANCE, FACTUAL_PROVENANCE,
+  isFactualProvenance, IR_CONFIDENCE, IR_CONFIDENCE_MEANING, confidenceFromClassification, SENSITIVITY,
+  RETENTION, REVIEW_STATUS, APPROVAL_STATUS, NODE_FIELDS, validateIR, graphToIR,
+} from './intent-ir.mjs';
+
+// Intent AI implementations (intent-ai-v1): state model, marker parser, hashing, manifest
+export {
+  IMPLEMENTATION_STATES, RISK_LEVELS, HIGH_RISK, blocksProduction,
+  COMMENT_PREFIX, parseMarkers, renderMarker,
+  contractHash, implementationHash,
+  buildManifest, buildImplementationPrompt, MANIFEST_SCHEMA_VERSION, PROOF_CHECK_KEYS,
+  resolveState, productionGate, adoptRegion,
+  recordDecision, approvalFor, emptyApprovals, APPROVALS_SCHEMA_VERSION,
+  makeEvent, INTENT_AI_EVENTS,
+} from './ai.mjs';
+
+// Language Server (LSP over stdio) for editors
+export { startLspServer } from "./lsp.mjs";
+
+// Formatter , canonical .intent formatting (whitespace only)
+export { formatSource, isFormatted } from "./format.mjs";

package/src/intellisense.mjs

@@ -0,0 +1,210 @@
+// ThunderLang IntelliSense providers (deterministic, no AI). Pure functions the
+// CLI, the playground API, and a future LSP all share. The playground must NOT
+// reimplement these; it renders what the compiler returns.
+
+import { KNOWN_LENSES } from './parse.mjs';
+
+export const SEMANTIC_TYPES = [
+  'Email', 'Money(USD)', 'Currency', 'Url', 'UserId', 'AccountId', 'OrderId',
+  'InvoiceId', 'PaymentId', 'Secret', 'Token', 'Jwt', 'IdempotencyKey', 'Date',
+  'DateTime', 'Duration', 'Percentage', 'TraceId', 'CorrelationId',
+];
+
+// Hover text for semantic types. Types not listed get a generic explanation.
+const TYPE_INFO = {
+  Email: { description: 'A validated email address. Prefer this over a raw string so tools can reason about PII and format.', examples: ['user@company.com'] },
+  Money: { description: 'A monetary amount with a currency, for example Money(USD). Avoids float rounding bugs and ambiguous units.', examples: ['Money(USD) 100.00'] },
+  'Money(USD)': { description: 'A monetary amount in US dollars. Prefer a typed money value over a number to avoid rounding and currency bugs.', examples: ['100.00'] },
+  Secret: { description: 'Sensitive value that must never be logged, returned to a client, or placed in events, proof, or AI context.', examples: ['paymentToken: Secret'] },
+  Token: { description: 'An opaque credential. Treat like a Secret: never log or return it.', examples: ['resetToken: Token'] },
+  Jwt: { description: 'A JSON Web Token credential. Sensitive; never log or expose it.', examples: [] },
+  IdempotencyKey: { description: 'A retry key. The same key must return the same result instead of creating a duplicate action.', examples: ['Use it to prevent duplicate invoices when checkout retries.'], relatedSuggestions: ['Add a duplicate prevention guarantee', 'Add a repeated-order verification test'] },
+  OrderId: { description: 'The stable identity of a placed order.', examples: ['A1'] },
+  InvoiceId: { description: 'The stable identity of an issued invoice.', examples: ['INV-1'] },
+  TraceId: { description: 'A distributed-tracing identifier used to correlate work across services.', examples: [] },
+  CorrelationId: { description: 'An identifier that correlates related requests or events.', examples: [] },
+};
+
+const LENS_INFO = {
+  pm: 'Business meaning for product and non-technical stakeholders.',
+  beginner: 'Plain-English explanation for someone new to programming.',
+  qa: 'How to test or verify this behavior.',
+  risk: 'What goes wrong if this fails.',
+  security: 'Privacy, secrets, auth, or data-exposure meaning.',
+  support: 'What support needs to know to help customers.',
+  reviewer: 'What a reviewer should check before approving.',
+  ops: 'What production signal or failure mode to watch.',
+  non_goal: 'What this mission intentionally does not do.',
+  term: 'Defines an unfamiliar term for readers.',
+};
+
+const BLOCK_KEYWORDS = ['goal', 'why', 'input', 'output', 'guarantees', 'never', 'verify', 'target', 'examples', 'note'];
+const SENSITIVE = /payment token|secret|token|password|jwt|credential|ssn|pii|email/i;
+
+const item = (id, label, insertText, detail, sortText = '050', kind = 'snippet') =>
+  ({ id, label, kind, detail, insertText, sortText, source: 'compiler', confidence: 'high' });
+
+const noteItem = (lens) =>
+  item(`completion_note_${lens}`, `note ${lens}:`, `note ${lens}:\n  \${1:${LENS_INFO[lens]}}`, LENS_INFO[lens], '010');
+
+const typeItem = (t) =>
+  item(`completion_type_${t}`, t, t, `Semantic type: ${(TYPE_INFO[t]?.description || TYPE_INFO[t.replace(/\(.*/, '')]?.description || 'A semantic type.')}`, '020', 'type');
+
+// Nearest enclosing top-level block above the cursor (by indentation).
+function enclosingBlock(lines, idx) {
+  const curIndent = lines[idx].length - lines[idx].trimStart().length;
+  if (curIndent === 0) return null;
+  for (let i = idx; i >= 0; i--) {
+    const l = lines[i];
+    if (!l.trim()) continue;
+    const ind = l.length - l.trimStart().length;
+    if (ind < curIndent) return l.trim().split(/\s+/)[0].toLowerCase();
+  }
+  return null;
+}
+
+export function getCompletions(source, position = {}) {
+  const lines = source.split('\n');
+  const idx = Math.max(0, Math.min((position.line || 1) - 1, lines.length - 1));
+  const cur = lines[idx] ?? '';
+  const items = [];
+
+  const meaningful = lines.filter((l) => l.trim() && !l.trim().startsWith('#'));
+  if (meaningful.length === 0) {
+    items.push(item('completion_mission_starter', 'mission starter',
+      'mission ${1:MissionName}\n  note pm:\n    ${2:Plain-English business meaning.}\n\n  goal\n    ${3:What should this accomplish?}\n\n  why\n    ${4:Why does this matter?}\n\n  input\n    ${5:field}: ${6:SemanticType}\n\n  output\n    ${7:result}: ${8:ResultType}\n\n  guarantees\n    ${9:Something that must always be true}\n\n  never\n    ${10:Something that must never happen}\n\n  verify\n    test ${11:expected behavior}\n',
+      'Start a new mission with goal, why, input, output, guarantees, never, verify.', '001'));
+    return { items };
+  }
+
+  // Typing a note lens: `note ` or `note pa`
+  if (/(^|\s)note\s+\w*$/.test(cur)) {
+    for (const lens of KNOWN_LENSES) items.push(noteItem(lens));
+    return { items };
+  }
+
+  const ctx = enclosingBlock(lines, idx);
+
+  if (SENSITIVE.test(cur) || SENSITIVE.test(lines[idx - 1] || '')) {
+    items.push(item('completion_note_security', 'note security:',
+      'note security:\n  ${1:This value must not appear in logs, events, responses, proof artifacts, or AI context.}',
+      'Flag sensitive data handling for security readers.', '005'));
+  }
+
+  if (ctx === 'input' || ctx === 'output') {
+    for (const t of SEMANTIC_TYPES) items.push(typeItem(t));
+    for (const l of ['beginner', 'pm', 'qa']) items.push(noteItem(l));
+  } else if (ctx === 'guarantees' || ctx === 'guarantee') {
+    for (const l of ['pm', 'risk', 'qa']) items.push(noteItem(l));
+    items.push(item('completion_verify', 'verify:', 'verify\n  test ${1:expected behavior}', 'Add verification evidence.', '015'));
+  } else if (ctx === 'never') {
+    for (const l of ['security', 'risk', 'reviewer']) items.push(noteItem(l));
+    items.push(item('completion_verify', 'verify:', 'verify\n  ${1:security scan}', 'Add verification evidence.', '015'));
+  } else {
+    for (const kw of BLOCK_KEYWORDS) {
+      if (kw === 'note') { items.push(noteItem('pm'), noteItem('beginner')); continue; }
+      items.push(item(`completion_block_${kw}`, `${kw}`, `${kw}\n  \${1:...}`, `Add a ${kw} block.`, '030', 'keyword'));
+    }
+  }
+  return { items };
+}
+
+export function getHover(source, position = {}) {
+  const lines = source.split('\n');
+  const idx = Math.max(0, Math.min((position.line || 1) - 1, lines.length - 1));
+  const cur = lines[idx] ?? '';
+  const col = Math.max(0, (position.column || 1) - 1);
+
+  // Word under the cursor.
+  let s = col, e = col;
+  while (s > 0 && /[A-Za-z0-9_()]/.test(cur[s - 1])) s--;
+  while (e < cur.length && /[A-Za-z0-9_()]/.test(cur[e])) e++;
+  const word = cur.slice(s, e);
+  if (!word) return { hover: null };
+
+  // note lens hover
+  const noteMatch = cur.match(/^\s*note\s+([A-Za-z_]+)/);
+  if (noteMatch && (word === noteMatch[1] || word === 'note')) {
+    const lens = noteMatch[1];
+    return {
+      hover: {
+        target: lens, kind: 'note_lens', title: `note ${lens}`,
+        description: LENS_INFO[lens] || 'An IntentLens reader lens.',
+        examples: [], relatedSuggestions: [],
+      },
+    };
+  }
+
+  // semantic type hover (known type, or a PascalCase type-like identifier)
+  const base = word.replace(/\(.*\)/, '');
+  const isKnownType = SEMANTIC_TYPES.some((t) => t === word || t.replace(/\(.*/, '') === base);
+  const info = TYPE_INFO[word] || TYPE_INFO[base];
+  if (info || isKnownType || /^[A-Z][a-z]/.test(word)) {
+    return {
+      hover: {
+        target: word, kind: 'semantic_type', title: word,
+        description: info?.description || 'A semantic type. Prefer semantic types over raw string or number so tools can reason about meaning.',
+        examples: info?.examples || [],
+        relatedSuggestions: info?.relatedSuggestions || [],
+      },
+    };
+  }
+  return { hover: null };
+}
+
+// ── Autocorrect + code actions (deterministic, safety-graded) ────────────────
+// Provably-safe header normalizations only. Aliases are limited to words that are
+// NOT valid canonical keywords in any context (so, e.g., `inputs` is intentionally
+// absent: it is the canonical sub-block of a decision and must not be touched).
+const HEADER_ALIASES = { goals: 'goal', nevers: 'never' };
+const TOP_HEADERS = new Set([
+  'goal', 'why', 'requires', 'input', 'output', 'guarantees', 'never', 'constraints',
+  'assumptions', 'risks', 'target', 'style', 'verify', 'errors', 'examples',
+]);
+
+/**
+ * Apply only meaning-preserving textual fixes: rename a bare misspelled block header
+ * to its canonical form (`goals` -> `goal`, `nevers` -> `never`) and strip a stray
+ * trailing colon from a recognized top-level header (`goal:` -> `goal`). Operates on
+ * single-word header lines only, so attached forms and leaf values are never rewritten.
+ * Returns { fixed, changes }. Pure and browser-safe.
+ */
+export function autocorrectSource(source) {
+  const lines = String(source).split('\n');
+  const changes = [];
+  const out = lines.map((line, i) => {
+    const m = line.match(/^(\s*)([A-Za-z]+)(:?)\s*$/);
+    if (!m) return line;
+    const [, indent, word, colon] = m;
+    const alias = HEADER_ALIASES[word.toLowerCase()];
+    const target = alias || word;
+    const isHeader = TOP_HEADERS.has(target.toLowerCase());
+    const dropColon = Boolean(colon) && isHeader;
+    if (target === word && !dropColon) return line;
+    const rule = alias ? 'header-alias' : 'strip-colon';
+    const fixed = `${indent}${target}`;
+    changes.push({ line: i + 1, from: line.trim(), to: fixed.trim(), rule, safety: 'safe' });
+    return fixed;
+  });
+  return { fixed: out.join('\n'), changes };
+}
+
+/**
+ * The code actions available for a source: the safe autocorrects, plus the quick-fixes
+ * the semantic diagnostics already carry (graded `reviewable` because they insert
+ * placeholder content a human should confirm). Diagnostics are passed in so this module
+ * stays browser-safe (no crypto import). Each action carries a safety level:
+ * safe | reviewable | meaning_change | blocked.
+ */
+export function getCodeActions(source, diagnostics = []) {
+  const actions = [];
+  for (const c of autocorrectSource(source).changes) {
+    actions.push({ title: `Normalize "${c.from}" to "${c.to}"`, kind: 'autocorrect', safety: 'safe', line: c.line, rule: c.rule });
+  }
+  for (const d of diagnostics) {
+    for (const f of d.fix || []) {
+      actions.push({ title: f.label, kind: 'quickfix', safety: 'reviewable', code: d.code, line: d.line ?? null, insert: f.insert, block: f.block });
+    }
+  }
+  return actions;
+}

package/src/intent-atlas.mjs

@@ -0,0 +1,77 @@
+// Intent Atlas (founder directive #4). The navigable, expandable, searchable map of a
+// whole software system, built OVER the canonical Intent Graph (intent-graph-v1) , NOT a
+// fork. Missions are the entry points (progressive disclosure: you never start from
+// files/folders). Deterministic; no AI (non-negotiable #1). Pure (no Node deps).
+//
+// Mission Atlas (focused per-mission map) is `mission-index-v1` / buildMissionIndex.
+// This assembles many mission graphs into the whole-system Atlas.
+
+export const ATLAS_SCHEMA = 'intent-atlas-v1';
+
+/**
+ * Assemble many Intent Graphs (one per .intent) into one whole-system Atlas.
+ * @param {Array<{schema, missionId, nodes, relationships}>} graphs
+ * @param {{product?: string}} [opts]
+ */
+export function buildAtlas(graphs, opts = {}) {
+  const nodes = new Map();
+  const relationships = [];
+  const missions = [];
+  for (const g of graphs || []) {
+    const m = g.nodes.find((n) => n.id === g.missionId);
+    missions.push({ id: g.missionId, title: (m && m.title) || g.missionId });
+    for (const n of g.nodes) if (!nodes.has(n.id)) nodes.set(n.id, n);
+    for (const r of g.relationships) relationships.push(r);
+  }
+  const nodeList = [...nodes.values()].sort((a, b) => a.id.localeCompare(b.id));
+  const byType = {};
+  for (const n of nodeList) byType[n.type] = (byType[n.type] || 0) + 1;
+  missions.sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    schema: ATLAS_SCHEMA,
+    product: opts.product || null,
+    // Progressive disclosure starts here: the overview is missions + type counts, not nodes.
+    overview: { missions: missions.length, nodes: nodeList.length, relationships: relationships.length, byType },
+    missions,
+    nodes: nodeList,
+    relationships,
+  };
+}
+
+/** Look up one node by id. */
+export function atlasNode(atlas, id) {
+  return atlas.nodes.find((n) => n.id === id) || null;
+}
+
+/**
+ * Expand a node to its immediate neighbors (outbound + inbound edges). This is the
+ * navigation primitive: never dump the whole graph, expand one node at a time.
+ */
+export function expandNode(atlas, id) {
+  const node = atlasNode(atlas, id);
+  if (!node) return null;
+  const out = atlas.relationships.filter((r) => r.from === id).map((r) => ({ rel: r.type, node: atlasNode(atlas, r.to) || { id: r.to } }));
+  const inbound = atlas.relationships.filter((r) => r.to === id).map((r) => ({ rel: r.type, node: atlasNode(atlas, r.from) || { id: r.from } }));
+  return { node, out, inbound };
+}
+
+/**
+ * Deterministic search over the Atlas (exact + substring over id/title/description),
+ * with optional type filter. No AI. Ranking: exact-title, then id-prefix, then
+ * substring; stable tiebreak by type + id.
+ */
+export function searchAtlas(atlas, query, opts = {}) {
+  const q = String(query || '').toLowerCase().trim();
+  if (!q) return [];
+  const score = (n) => {
+    const title = (n.title || '').toLowerCase();
+    const id = n.id.toLowerCase();
+    if (title === q || id === q) return 0;
+    if (id.startsWith(q) || title.startsWith(q)) return 1;
+    return 2;
+  };
+  let hits = atlas.nodes.filter((n) => `${n.id} ${n.title || ''} ${n.description || ''}`.toLowerCase().includes(q));
+  if (opts.type) hits = hits.filter((n) => n.type === opts.type);
+  hits.sort((a, b) => score(a) - score(b) || a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+  return hits.slice(0, opts.limit || 25);
+}