memorix 1.8.6 → 1.8.7

package/src/codegraph/auto-context.ts

@@ -19,7 +19,8 @@ import {
   inspectExternalCodeGraph,
   type ExternalCodeGraphRunner,
 } from './external-provider.js';
-import type { CodeGraphProviderQuality, ExternalCodeGraphOutline } from './types.js';
+import type { CodeGraphOutline, CodeGraphProviderQuality } from './types.js';
+import { buildSemanticContext, qualityWithPersistedSemantic } from './semantic-context.js';
 import {
   buildProjectContextExplain,
   type ProjectContextExplain,
@@ -341,10 +342,18 @@ export async function buildAutoProjectContext(input: {
     }
   }
   const sourceSets = lensSourceSets({ task, lens, explain });
-  let externalOutline: ExternalCodeGraphOutline | undefined;
+  let semanticOutline: CodeGraphOutline | undefined;
   let externalCaution: string | undefined;
   let providerQuality: CodeGraphProviderQuality;
   if (task) {
+    const internalOutline = buildSemanticContext({
+      store,
+      projectId: input.project.id,
+      task,
+      preferredPaths: overview.suggestedReads,
+      maxNodes: 8,
+      maxEdges: 12,
+    });
     const external = await getExternalCodeGraphContext({
       projectRoot: input.project.rootPath,
       task,
@@ -354,9 +363,9 @@ export async function buildAutoProjectContext(input: {
       timeoutMs: codegraphConfig.externalTimeoutMs,
       ...(input.externalRunner ? { runner: input.externalRunner } : {}),
     });
-    externalOutline = external.outline;
-    externalCaution = external.caution;
-    providerQuality = external.quality;
+    semanticOutline = external.outline ?? internalOutline;
+    externalCaution = external.outline ? external.caution : internalOutline ? undefined : external.caution;
+    providerQuality = qualityWithPersistedSemantic(external.quality, store.status(input.project.id));
   } else {
     const external = await inspectExternalCodeGraph({
       projectRoot: input.project.rootPath,
@@ -365,17 +374,17 @@ export async function buildAutoProjectContext(input: {
       timeoutMs: codegraphConfig.externalTimeoutMs,
       ...(input.externalRunner ? { runner: input.externalRunner } : {}),
     });
-    providerQuality = external.quality;
+    providerQuality = qualityWithPersistedSemantic(external.quality, store.status(input.project.id));
   }
-  const externalStartHere = externalOutline
-    ? [...externalOutline.relatedFiles, ...externalOutline.entryPoints.map(entry => entry.path)]
+  const externalStartHere = semanticOutline
+    ? semanticOutline.entryPoints.map(entry => entry.path)
     : [];
   const startHere = [...new Set([
-    ...externalStartHere,
     ...rankLensPaths([
       ...existingLensCandidates(input.project.rootPath, lens),
       ...overview.suggestedReads,
     ], lens, task),
+    ...externalStartHere,
   ])].slice(0, 5);
   const runtimeCautions: WorksetCaution[] = [];
   if (refresh.reason === 'queued') {
@@ -434,7 +443,7 @@ export async function buildAutoProjectContext(input: {
     ...(alwaysOn.profile.length > 0 || alwaysOn.state || alwaysOn.durable.length > 0
       ? { alwaysOn }
       : {}),
-    ...(externalOutline ? { semanticCode: externalOutline } : {}),
+    ...(semanticOutline ? { semanticCode: semanticOutline } : {}),
     providerQuality,
     currentFacts: worksetFactLines(currentFacts),
     ...(continuation ? { continuation } : {}),

package/src/codegraph/context-pack.ts

@@ -3,13 +3,14 @@ import { buildTaskWorkset, type TaskWorkset, type WorksetCaution } from '../know
 import type {
   CodeFile,
   CodeGraphProviderQuality,
+  CodeGraphOutline,
   CodeRefStatus,
   CodeSymbol,
-  ExternalCodeGraphOutline,
   ObservationCodeRef,
 } from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
+import { buildSemanticContext } from './semantic-context.js';
 import type { AgentTarget, ObservationReader } from '../types.js';
 
 export interface ContextPackMemory {
@@ -43,6 +44,7 @@ export interface ContextPack {
   warnings: ContextPackWarning[];
   suggestedReads: string[];
   suggestedVerification: string[];
+  semanticCode?: CodeGraphOutline;
   /** 1.2 bounded task selection, added without removing legacy pack fields. */
   workset?: TaskWorkset;
 }
@@ -67,6 +69,7 @@ export interface AssembleContextPackInput {
   symbols: CodeSymbol[];
   suggestedVerification?: string[];
   exclude?: string[];
+  semanticCode?: CodeGraphOutline;
 }
 
 function uniq<T>(items: T[]): T[] {
@@ -151,6 +154,14 @@ export function assembleContextPackForTask(input: {
   const fileIds = new Set(refs.map(ref => ref.fileId).filter(Boolean));
   const files = input.store.listFiles(input.projectId).filter(file => fileIds.has(file.id));
   const symbols = files.flatMap(file => input.store.listSymbolsForFile(file.id));
+  const semanticCode = buildSemanticContext({
+    store: input.store,
+    projectId: input.projectId,
+    task: input.task,
+    preferredPaths: files.map(file => file.path),
+    maxNodes: 8,
+    maxEdges: 12,
+  });
 
   return assembleContextPack({
     task: input.task,
@@ -160,6 +171,7 @@ export function assembleContextPackForTask(input: {
     symbols,
     suggestedVerification: input.suggestedVerification,
     exclude: input.exclude,
+    ...(semanticCode ? { semanticCode } : {}),
   });
 }
 
@@ -252,6 +264,7 @@ export function assembleContextPack(input: AssembleContextPackInput): ContextPac
       hasWarnings: warnings.length > 0,
       hasUnboundMemories: unboundMemories.length > 0,
     }),
+    ...(input.semanticCode ? { semanticCode: input.semanticCode } : {}),
   };
 }
 
@@ -274,14 +287,15 @@ export async function attachTaskWorkset(input: {
     worktreeState?: 'clean' | 'dirty' | 'unavailable';
     incomplete?: boolean;
   };
-  semanticCode?: ExternalCodeGraphOutline;
+  semanticCode?: CodeGraphOutline;
   providerQuality?: CodeGraphProviderQuality;
   runtimeCautions?: WorksetCaution[];
   reader?: ObservationReader;
   agent?: AgentTarget;
 }): Promise<ContextPack> {
-  const semanticStartHere = input.semanticCode
-    ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
+  const semanticCode = input.semanticCode ?? input.pack.semanticCode;
+  const semanticStartHere = semanticCode
+    ? semanticCode.entryPoints.map(entry => entry.path)
     : [];
   const workset = await buildTaskWorkset({
     projectId: input.projectId,
@@ -292,7 +306,7 @@ export async function attachTaskWorkset(input: {
     currentFacts: input.currentFacts ?? [],
     ...(input.codeState ? { codeState: input.codeState } : {}),
     startHere: uniq([...semanticStartHere, ...input.pack.suggestedReads]),
-    ...(input.semanticCode ? { semanticCode: input.semanticCode } : {}),
+    ...(semanticCode ? { semanticCode } : {}),
     ...(input.providerQuality ? { providerQuality: input.providerQuality } : {}),
     reliableMemory: input.pack.memories
       .filter(memory => memory.status === 'current')
@@ -323,7 +337,7 @@ export async function attachTaskWorkset(input: {
     ...(input.reader ? { reader: input.reader } : {}),
     deliveryTarget: 'context-pack',
   });
-  return { ...input.pack, workset };
+  return { ...input.pack, ...(semanticCode ? { semanticCode } : {}), workset };
 }
 
 export function buildContextPackPrompt(pack: ContextPack): string {

package/src/codegraph/dashboard.ts

@@ -0,0 +1,82 @@
+import { CodeGraphStore } from './store.js';
+
+export interface CodeGraphDashboardStatus {
+  projectId: string;
+  provider: 'lite';
+  state: 'not-indexed' | 'ready' | 'partial';
+  files: number;
+  symbols: number;
+  edges: number;
+  refs: number;
+  indexedAt?: string;
+  semantic: {
+    files: number;
+    symbols: number;
+    edges: number;
+    parserErrors: number;
+  };
+  lite: {
+    files: number;
+    symbols: number;
+    edges: number;
+  };
+  parserErrorPaths: string[];
+  snapshot?: {
+    id: string;
+    sourceEpoch: number;
+    worktreeState: string;
+    incomplete: boolean;
+    changedPathCount: number;
+  };
+}
+
+/** Read-only dashboard projection; it never refreshes or mutates the index. */
+export async function getCodeGraphDashboardStatus(
+  dataDir: string,
+  projectId: string,
+): Promise<CodeGraphDashboardStatus> {
+  const store = new CodeGraphStore();
+  await store.init(dataDir);
+  const status = store.status(projectId);
+  const files = store.listFiles(projectId);
+  const semanticFiles = files.filter(file => file.source === 'typescript-compiler');
+  const parserErrorPaths = files
+    .filter(file => Boolean(file.parserError))
+    .map(file => file.path)
+    .slice(0, 8);
+  const semanticIndexed = status.semanticSymbols > 0 || status.semanticEdges > 0;
+  const snapshot = status.latestSnapshot;
+  return {
+    projectId,
+    provider: 'lite',
+    state: status.parserErrors > 0 ? 'partial' : semanticIndexed ? 'ready' : 'not-indexed',
+    files: status.files,
+    symbols: status.symbols,
+    edges: status.edges,
+    refs: status.refs,
+    ...(status.indexedAt ? { indexedAt: status.indexedAt } : {}),
+    semantic: {
+      files: semanticFiles.length,
+      symbols: status.semanticSymbols,
+      edges: status.semanticEdges,
+      parserErrors: status.parserErrors,
+    },
+    lite: {
+      files: files.length - semanticFiles.length,
+      symbols: Math.max(0, status.symbols - status.semanticSymbols),
+      edges: Math.max(0, status.edges - status.semanticEdges),
+    },
+    parserErrorPaths,
+    ...(snapshot ? {
+      snapshot: {
+        id: snapshot.id,
+        sourceEpoch: snapshot.sourceEpoch,
+        worktreeState: snapshot.worktreeState,
+        incomplete: snapshot.completeness.skippedOversizedFiles > 0
+          || (snapshot.completeness.unreadableFiles ?? 0) > 0
+          || snapshot.completeness.removalScanDeferred,
+        changedPathCount: snapshot.changedPathCount,
+      },
+    } : {}),
+  };
+}

package/src/codegraph/external-provider.ts

@@ -4,6 +4,7 @@ import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep }
 import { sanitizeCredentials } from '../memory/secret-filter.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
 import { normalizeCodePath } from './ids.js';
+import { normalizeScipOutline } from './scip-provider.js';
 import type {
   CodeGraphExternalMode,
   CodeGraphProviderQuality,
@@ -327,7 +328,7 @@ const defaultRunner: ExternalCodeGraphRunner = {
 function providerQuality(input: {
   mode: CodeGraphExternalMode;
   health: ExternalCodeGraphHealth;
-  selected?: 'lite' | 'external';
+  selected?: 'lite' | 'semantic' | 'external';
 }): CodeGraphProviderQuality {
   const selected = input.selected ?? 'lite';
   return {
@@ -346,6 +347,12 @@ function providerQuality(input: {
       supportedLanguages: LITE_SUPPORTED_LANGUAGES,
     },
     external: input.health,
+    semantic: {
+      state: 'not-indexed',
+      symbols: 0,
+      edges: 0,
+      parserErrors: 0,
+    },
   };
 }
 
@@ -637,6 +644,8 @@ function externalSymbol(raw: RawExternalNode): ExternalCodeGraphSymbol {
 }
 
 function parseOutline(value: unknown, projectRoot: string, exclude?: string[]): ExternalCodeGraphOutline | undefined {
+  const scipOutline = normalizeScipOutline(value, { projectRoot, exclude });
+  if (scipOutline) return scipOutline as ExternalCodeGraphOutline;
   if (!isRecord(value) || !Array.isArray(value.entryPoints) || !Array.isArray(value.nodes)
     || !Array.isArray(value.edges) || !Array.isArray(value.relatedFiles)) return undefined;
   if ('codeBlocks' in value && (!Array.isArray(value.codeBlocks) || value.codeBlocks.length > 0)) return undefined;

package/src/codegraph/freshness.ts

@@ -20,7 +20,7 @@ export function evaluateCodeRefFreshness(
 
   if (ref.capturedSymbolHash && symbol?.contentHash) {
     if (symbol.contentHash !== ref.capturedSymbolHash) {
-      return { status: 'stale', reason: 'referenced symbol content changed' };
+      return { status: 'suspect', reason: 'referenced symbol content changed' };
     }
     return { status: 'current', reason: 'referenced symbol content still matches' };
   }

package/src/codegraph/lite-provider.ts

@@ -6,6 +6,7 @@ import { collectCodeStateSnapshot } from './code-state.js';
 import { makeCodeEdgeId, makeCodeFileId, makeCodeSymbolId, normalizeCodePath } from './ids.js';
 import { isCodeGraphExcludedPath, normalizeCodeGraphExcludePatterns } from './exclude.js';
 import { CodeGraphStore, type CodeGraphFileDelta } from './store.js';
+import { buildTypeScriptSemanticIndex, isSemanticLanguage } from './semantic-provider.js';
 
 export interface LiteIndexOptions {
   projectId: string;
@@ -13,6 +14,8 @@ export interface LiteIndexOptions {
   exclude?: string[];
   maxFiles?: number;
   maxFileBytes?: number;
+  /** Injectable only for deterministic failure-path tests. */
+  semanticIndexer?: typeof buildTypeScriptSemanticIndex;
 }
 
 export interface LiteIndexResult {
@@ -35,6 +38,17 @@ export interface LiteRefreshResult {
   unreadableFiles: number;
   removalScanDeferred: boolean;
   snapshot: CodeStateSnapshot;
+  semantic?: {
+    state: 'ready' | 'partial' | 'failed';
+    parsedFiles: number;
+    affectedFiles: number;
+    symbols: number;
+    edges: number;
+    parserErrors: number;
+    unresolvedCalls: number;
+    durationMs: number;
+    error?: string;
+  };
 }
 
 export const DEFAULT_CODEGRAPH_MAX_FILE_BYTES = 2 * 1024 * 1024;
@@ -257,6 +271,7 @@ function extractSymbols(projectId: string, file: CodeFile, text: string, indexed
         signature: match[0].slice(0, 160),
         contentHash: hashText(match[0]),
         indexedAt,
+        source: 'lite-regex',
       });
     }
   }
@@ -284,6 +299,7 @@ function extractImportEdges(projectId: string, file: CodeFile, text: string, ind
             confidence: 0.7,
             evidence: line,
             indexedAt,
+            source: 'lite-regex',
           });
         }
         continue;
@@ -297,6 +313,7 @@ function extractImportEdges(projectId: string, file: CodeFile, text: string, ind
       confidence: 0.7,
       evidence: target,
       indexedAt,
+      source: 'lite-regex',
     });
     }
   }
@@ -330,6 +347,7 @@ function indexFileLite(
       mtimeMs: Number(stat.mtimeMs),
       sizeBytes: Number(stat.size),
       indexedAt,
+      source: 'lite-regex',
     };
     return {
       delta: {
@@ -395,6 +413,7 @@ export async function refreshProjectLite(
   const indexedAt = new Date().toISOString();
   const paths = walk(options.projectRoot, exclude, maxFiles);
   const existingByPath = new Map(store.listFiles(options.projectId).map((file) => [file.path, file]));
+  const changedPaths = new Set<string>();
   const changed: CodeGraphFileDelta[] = [];
   const metadataOnly: CodeFile[] = [];
   const seenPaths = new Set<string>();
@@ -420,6 +439,7 @@ export async function refreshProjectLite(
     if (sizeBytes > maxFileBytes) {
       skippedOversizedFiles++;
       if (existing) oversizedExistingFileIds.add(existing.id);
+      changedPaths.add(rel);
       continue;
     }
     if (existing && existing.mtimeMs === mtimeMs && existing.sizeBytes === sizeBytes) {
@@ -438,6 +458,7 @@ export async function refreshProjectLite(
       unchangedFiles++;
     } else {
       changed.push(delta);
+      changedPaths.add(rel);
     }
   }
 
@@ -451,11 +472,70 @@ export async function refreshProjectLite(
         .filter((file) => !seenPaths.has(file.path))
         .map((file) => file.id)),
   ])];
+  for (const file of existingByPath.values()) {
+    if (removedFileIds.includes(file.id)) changedPaths.add(file.path);
+  }
+  // An export or symbol change can invalidate the semantic edges of every
+  // local importer. Capture those paths before applyFileDeltas clears them.
+  const affectedSemanticPaths = new Set([
+    ...changedPaths,
+    ...store.listImportDependentPaths(
+      options.projectId,
+      [...changedPaths],
+      changed.map(delta => delta.file.path),
+    ),
+  ]);
   store.applyFileDeltas(options.projectId, {
     changed,
     metadataOnly,
     removedFileIds,
   });
+  const currentFiles = store.listFiles(options.projectId);
+  const beforeSemantic = store.status(options.projectId).semanticSymbols;
+  const semanticPaths = beforeSemantic === 0
+    ? currentFiles.filter(file => isSemanticLanguage(file.language)).map(file => file.path)
+    : currentFiles
+      .filter(file => isSemanticLanguage(file.language) && affectedSemanticPaths.has(file.path))
+      .map(file => file.path);
+  let semanticSummary: LiteRefreshResult['semantic'];
+  if (semanticPaths.length > 0) {
+    const semanticIndexer = options.semanticIndexer ?? buildTypeScriptSemanticIndex;
+    const semanticInput = {
+      projectId: options.projectId,
+      projectRoot: options.projectRoot,
+      files: currentFiles,
+      exclude,
+      includePaths: semanticPaths,
+    };
+    try {
+      const semantic = semanticIndexer(semanticInput);
+      store.replaceSemanticSlice(options.projectId, semanticPaths, semantic);
+      semanticSummary = {
+        state: semantic.parserErrors > 0 ? 'partial' : 'ready',
+        parsedFiles: semantic.parsedFiles,
+        affectedFiles: semanticPaths.length,
+        symbols: semantic.symbols.length,
+        edges: semantic.edges.length,
+        parserErrors: semantic.parserErrors,
+        unresolvedCalls: semantic.unresolvedCalls,
+        durationMs: semantic.durationMs,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      store.markSemanticSliceFailed(options.projectId, semanticPaths, message);
+      semanticSummary = {
+        state: 'failed',
+        parsedFiles: 0,
+        affectedFiles: semanticPaths.length,
+        symbols: 0,
+        edges: 0,
+        parserErrors: semanticPaths.length,
+        unresolvedCalls: 0,
+        durationMs: 0,
+        error: message.slice(0, 500),
+      };
+    }
+  }
   const completeness = {
     scannedFiles: paths.length,
     maxFiles,
@@ -486,5 +566,6 @@ export async function refreshProjectLite(
     unreadableFiles,
     removalScanDeferred,
     snapshot,
+    ...(semanticSummary ? { semantic: semanticSummary } : {}),
   };
 }

package/src/codegraph/project-context.ts

@@ -134,17 +134,30 @@ function collectGraph(
   const sources: ProjectContextSource[] = [];
   const suggestedReads: string[] = [];
 
+  const severity: Record<CodeRefStatus, number> = { current: 1, suspect: 2, stale: 3, unbound: 0 };
+  const grouped = new Map<number, {
+    observation: ProjectContextObservation;
+    file?: CodeFile;
+    symbol?: CodeSymbol;
+    result: ReturnType<typeof evaluateCodeRefFreshness>;
+  }>();
   for (const ref of refs) {
     const file = ref.fileId ? filesById.get(ref.fileId) : undefined;
     const symbol = ref.symbolId ? symbolsById.get(ref.symbolId) : undefined;
     const result = evaluateCodeRefFreshness(ref, file, symbol);
-    freshness[result.status] += 1;
-
     const observation = observationsById.get(ref.observationId);
     if (!observation) continue;
-    const excluded = file ? isCodeGraphExcludedPath(file.path, exclude) : false;
-    if (result.status === 'current' && file && !excluded) suggestedReads.push(file.path);
-    if (excluded) continue;
+    const existing = grouped.get(ref.observationId);
+    if (!existing || severity[result.status] > severity[existing.result.status]
+      || (severity[result.status] === severity[existing.result.status] && symbol && !existing.symbol)) {
+      grouped.set(ref.observationId, { observation, file, symbol, result });
+    }
+  }
+
+  for (const { observation, file, symbol, result } of grouped.values()) {
+    freshness[result.status] += 1;
+    if (file && isCodeGraphExcludedPath(file.path, exclude)) continue;
+    if (result.status === 'current' && file) suggestedReads.push(file.path);
     sources.push({
       observationId: observation.id,
       title: observation.title,

package/src/codegraph/scip-provider.ts

@@ -0,0 +1,181 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { isCodeGraphExcludedPath } from './exclude.js';
+import { normalizeCodePath } from './ids.js';
+import type { CodeGraphOutline, ExternalCodeGraphRelation, ExternalCodeGraphSymbol } from './types.js';
+
+/**
+ * SCIP is intentionally an input boundary here, not a second persistence
+ * format. The normalized outline is bounded and remains separate from the
+ * canonical local CodeGraph tables.
+ */
+export interface ScipOutlineOptions {
+  projectRoot: string;
+  exclude?: string[];
+  maxNodes?: number;
+  maxEdges?: number;
+  maxFiles?: number;
+}
+
+const DEFAULT_MAX_NODES = 16;
+const DEFAULT_MAX_EDGES = 24;
+const DEFAULT_MAX_FILES = 12;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function text(value: unknown, max = 240): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = sanitizeCredentials(value).replace(/[\u0000-\u001f]/g, ' ').replace(/\s+/g, ' ').trim();
+  return normalized && normalized.length <= max ? normalized : undefined;
+}
+
+function safeRelativePath(projectRoot: string, value: unknown, exclude?: string[]): string | undefined {
+  const raw = text(value, 1_024);
+  if (!raw || isAbsolute(raw)) return undefined;
+  const absolute = resolve(projectRoot, raw);
+  const fromRoot = relative(resolve(projectRoot), absolute);
+  if (!fromRoot || fromRoot === '..' || fromRoot.startsWith('..\\') || fromRoot.startsWith('../') || isAbsolute(fromRoot)) return undefined;
+  const normalized = normalizeCodePath(fromRoot);
+  return isCodeGraphExcludedPath(normalized, exclude) ? undefined : normalized;
+}
+
+function integer(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+function lineFromRange(value: unknown): number | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const line = integer(value[0]);
+  return line === undefined ? undefined : line + 1;
+}
+
+function symbolKind(value: unknown): string {
+  if (typeof value === 'string' && value.trim()) return value.trim().slice(0, 80);
+  if (typeof value === 'number' && Number.isInteger(value)) return `scip-kind-${value}`;
+  return 'symbol';
+}
+
+function symbolName(symbolId: string, value: unknown): string {
+  const displayName = text(value, 180);
+  if (displayName) return displayName;
+  const pieces = symbolId.split(/[/#.:]/).filter(Boolean);
+  return (pieces[pieces.length - 1] || symbolId).slice(0, 180);
+}
+
+function relationKind(relationship: Record<string, unknown>): string {
+  if (relationship.isImplementation === true || relationship.is_implementation === true) return 'implements';
+  if (relationship.isDefinition === true || relationship.is_definition === true) return 'defines';
+  if (relationship.isReference === true || relationship.is_reference === true) return 'references';
+  return 'references';
+}
+
+interface ScipNodeInfo {
+  symbolId: string;
+  node: ExternalCodeGraphSymbol;
+  defined: boolean;
+  line?: number;
+  relationships: Array<{ target: string; kind: string }>;
+}
+
+/** Normalize a bounded `scip print --json` payload into Memorix's outline. */
+export function normalizeScipOutline(value: unknown, options: ScipOutlineOptions): CodeGraphOutline | undefined {
+  if (!isRecord(value) || !Array.isArray(value.documents)) return undefined;
+  const maxNodes = Math.max(2, Math.min(64, Math.floor(options.maxNodes ?? DEFAULT_MAX_NODES)));
+  const maxEdges = Math.max(1, Math.min(96, Math.floor(options.maxEdges ?? DEFAULT_MAX_EDGES)));
+  const maxFiles = Math.max(1, Math.min(32, Math.floor(options.maxFiles ?? DEFAULT_MAX_FILES)));
+  const nodes = new Map<string, ScipNodeInfo>();
+  const relatedFiles = new Set<string>();
+  const definitions = new Set<string>();
+
+  for (const document of value.documents.slice(0, maxFiles * 4)) {
+    if (!isRecord(document)) continue;
+    const filePath = safeRelativePath(options.projectRoot, document.relativePath ?? document.relative_path, options.exclude);
+    if (!filePath || relatedFiles.size >= maxFiles && !relatedFiles.has(filePath)) continue;
+    relatedFiles.add(filePath);
+    const occurrences = Array.isArray(document.occurrences) ? document.occurrences : [];
+    const definitionLines = new Map<string, number>();
+    for (const occurrence of occurrences) {
+      if (!isRecord(occurrence)) continue;
+      const id = text(occurrence.symbol, 240);
+      const isDefinition = occurrence.isDefinition === true || occurrence.is_definition === true;
+      const rawRoles = occurrence.symbolRoles ?? occurrence.symbol_roles;
+      if (!id || (rawRoles === undefined && !isDefinition)) continue;
+      const roles = integer(rawRoles) ?? 0;
+      // SCIP SymbolRole.Definition is bit 1. Accept the explicit boolean used
+      // by a few JSON emitters as well, without trusting arbitrary roles.
+      if ((roles & 1) !== 0 || isDefinition) {
+        definitions.add(id);
+        const line = lineFromRange(occurrence.range);
+        if (line !== undefined) definitionLines.set(id, line);
+      }
+    }
+
+    const symbolInfos = Array.isArray(document.symbols) ? document.symbols : [];
+    for (const rawSymbol of symbolInfos) {
+      if (!isRecord(rawSymbol)) continue;
+      const id = text(rawSymbol.symbol, 240);
+      if (!id || nodes.has(id)) continue;
+      const relationships: Array<{ target: string; kind: string }> = [];
+      if (Array.isArray(rawSymbol.relationships)) {
+        for (const rawRelationship of rawSymbol.relationships.slice(0, 32)) {
+          if (!isRecord(rawRelationship)) continue;
+          const target = text(rawRelationship.symbol, 240);
+          if (target) relationships.push({ target, kind: relationKind(rawRelationship) });
+        }
+      }
+      nodes.set(id, {
+        symbolId: id,
+        node: {
+          id,
+          name: symbolName(id, rawSymbol.displayName ?? rawSymbol.display_name),
+          qualifiedName: text(rawSymbol.displayName ?? rawSymbol.display_name, 220),
+          kind: symbolKind(rawSymbol.kind),
+          path: filePath,
+          language: text(document.language, 80),
+          ...(definitionLines.has(id) ? { startLine: definitionLines.get(id) } : {}),
+        },
+        defined: definitions.has(id),
+        ...(definitionLines.has(id) ? { line: definitionLines.get(id) } : {}),
+        relationships,
+      });
+    }
+  }
+
+  if (nodes.size === 0) return undefined;
+
+  const selectedNodes = [...nodes.values()]
+    .sort((left, right) => Number(right.defined) - Number(left.defined) || left.node.path.localeCompare(right.node.path) || left.node.name.localeCompare(right.node.name))
+    .slice(0, maxNodes);
+  const selectedById = new Map(selectedNodes.map(item => [item.symbolId, item]));
+  const relations: ExternalCodeGraphRelation[] = [];
+  for (const source of selectedNodes) {
+    for (const relationship of source.relationships) {
+      const target = selectedById.get(relationship.target);
+      if (!target || relations.length >= maxEdges) continue;
+      relations.push({
+        from: source.node,
+        to: target.node,
+        kind: relationship.kind,
+        ...(source.line ? { line: source.line } : {}),
+      });
+    }
+  }
+
+  const entryPoints = selectedNodes
+    .filter(item => item.defined)
+    .slice(0, 5)
+    .map(item => item.node);
+  return {
+    provider: 'external',
+    entryPoints: entryPoints.length > 0 ? entryPoints : selectedNodes.slice(0, 5).map(item => item.node),
+    relations,
+    relatedFiles: [...new Set(selectedNodes.map(item => item.node.path))].slice(0, maxFiles),
+    stats: {
+      nodes: nodes.size,
+      edges: relations.length,
+      files: relatedFiles.size,
+    },
+  };
+}