@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/context/direct-controller-learning.ts

@@ -0,0 +1,298 @@
+import { createHash } from 'crypto';
+import {
+  memoryAddressKey,
+  parseMemoryAddressKey,
+  memoryDraftFromLearningSignal,
+  recordCognitiveMemory,
+  type CognitiveWriteAuthorityPort,
+  type LearningSignal,
+  type MemoryUnit,
+} from '../../../packages/kernel/cognition/api/index';
+import { readForgeInstanceIdentity, type ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { FORGE_INSTANCE_SCOPE_KEY } from '../../cli/repositories/controller-home';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { cognitionMemoryStore, cognitionReadPort, recordCognitiveUsageObservation, type CognitiveUsageRejectionKind } from '../control-plane/persistence/cognition-store';
+import { resolveProjectForRepositoryPlacement } from '../control-plane/workspace/workspace-store';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { cognitiveScopesForWork } from '../control-plane/persistence/experience-store';
+import { findPluginActionReceipt } from '../plugins/store';
+import {
+  associateStoredMemories,
+  consolidateAffectedMemories,
+  CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS,
+  type ControllerLearningSignalDraft,
+} from './automatic-learning';
+
+export interface DirectControllerLearningResult {
+  storedMemoryIds: string[];
+  associatedEdgeCount: number;
+  consolidatedMemoryIds: string[];
+  scopes: ScopeRef[];
+}
+
+function sameScope(left: ScopeRef, right: ScopeRef): boolean {
+  return left.kind === right.kind && left.id === right.id;
+}
+
+export function directLearningScopes(
+  controllerHome: string,
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>,
+  workId?: string,
+): ScopeRef[] {
+  if (workId) {
+    const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+    if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+    return cognitiveScopesForWork(work, controllerHome);
+  }
+  const instance = readForgeInstanceIdentity(controllerHome);
+  if (!instance) throw new Error('COGNITION_DIRECT_LEARNING_FORGE_INSTANCE_REQUIRED');
+  const project = resolveProjectForRepositoryPlacement({
+    controllerHome,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+  });
+  if (!project) throw new Error('COGNITION_DIRECT_LEARNING_PROJECT_PLACEMENT_REQUIRED');
+  return [
+    { schemaVersion: 1, kind: 'project', id: project.projectId },
+    { schemaVersion: 1, kind: 'workspace', id: project.workspaceId },
+  ];
+}
+
+function semanticSignalId(signal: ControllerLearningSignalDraft, scope: ScopeRef): string {
+  const concepts = [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))].sort();
+  const identity = JSON.stringify({
+    scope: `${scope.kind}:${scope.id}`,
+    kind: signal.kind,
+    valence: signal.valence,
+    summary: signal.summary,
+    concepts,
+    admissionSource: signal.admissionSource,
+    portability: signal.portability,
+  });
+  return createHash('sha256').update(identity).digest('hex').slice(0, 32);
+}
+
+function directSourceId(input: {
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+}): string {
+  const identity = [
+    input.principalId?.trim() ?? '',
+    input.controllerType?.trim() ?? '',
+    input.controllerInstanceId?.trim() ?? '',
+    input.sessionId?.trim() ?? '',
+  ].join(':');
+  return `mcp-learning:${createHash('sha256').update(identity || 'anonymous-controller').digest('hex').slice(0, 24)}`;
+}
+
+function directLearningAuthority(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId'>;
+  scopes: readonly ScopeRef[];
+  principalId?: string;
+  sourceId: string;
+  sourceWorkId?: string;
+}): CognitiveWriteAuthorityPort {
+  const scopeAllowed = (scope: ScopeRef) => input.scopes.some(candidate => sameScope(candidate, scope));
+  return {
+    assertMemoryWrite(memory: MemoryUnit) {
+      if (!scopeAllowed(memory.scope)
+        || memory.provenance.sourceKind !== 'controller'
+        || memory.provenance.sourceId !== input.sourceId
+        || memory.provenance.sourceWorkId !== input.sourceWorkId
+        || memory.provenance.sourceRoundId) {
+        throw new Error('COGNITION_DIRECT_LEARNING_AUTHORITY_INVALID');
+      }
+      if (memory.scope.kind === 'workspace' && !memory.facets.includes('portability.portable')) {
+        throw new Error('COGNITION_DIRECT_LEARNING_WORKSPACE_PORTABILITY_REQUIRED');
+      }
+    },
+    assertEdgeWrite() {
+      throw new Error('COGNITION_DIRECT_LEARNING_EDGE_NOT_ALLOWED');
+    },
+    evidenceAvailable(ref, scope) {
+      if (!scopeAllowed(scope)) return false;
+      const receipt = findPluginActionReceipt(input.controllerHome, ref);
+      if (!receipt) return false;
+      if (receipt.repoId === input.repository.repoId || receipt.workRepoId === input.repository.repoId) return true;
+      const principal = input.principalId?.trim();
+      return receipt.scopeKey === FORGE_INSTANCE_SCOPE_KEY
+        && Boolean(principal)
+        && receipt.origin?.actor === principal;
+    },
+  };
+}
+
+/**
+ * Persist semantic learning selected by the model without creating a learning lifecycle.
+ *
+ * The caller supplies meaning plus an optional already-existing Work identity. Forge derives
+ * reachable semantic scope, source identity and time. Work provenance never fabricates a
+ * ControllerRound; ControllerRound authority remains intentionally absent.
+ */
+export interface DirectControllerLearningFeedbackDraft {
+  memoryAddress: string;
+  decision: 'used' | 'rejected';
+  reason: string;
+  rejectionKind?: CognitiveUsageRejectionKind;
+}
+
+export interface DirectControllerLearningFeedbackResult {
+  observationIds: string[];
+  scopes: ScopeRef[];
+}
+
+export function recordDirectControllerLearningFeedback(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  feedback: readonly DirectControllerLearningFeedbackDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  now?: string;
+  workId?: string;
+}): DirectControllerLearningFeedbackResult {
+  if (!input.feedback.length || input.feedback.length > 32) throw new Error('COGNITION_DIRECT_FEEDBACK_ITEMS_INVALID');
+  const principalId = input.principalId?.trim();
+  if (!principalId) throw new Error('COGNITION_DIRECT_FEEDBACK_PRINCIPAL_REQUIRED');
+  const interactionId = input.sessionId?.trim() || input.controllerInstanceId?.trim();
+  if (!interactionId) throw new Error('COGNITION_DIRECT_FEEDBACK_SESSION_REQUIRED');
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const allowedScopes = new Set(scopes.map(scope => `${scope.kind}:${scope.id}`));
+  const now = input.now ?? new Date().toISOString();
+  const read = cognitionReadPort(input.controllerHome);
+  const observations = input.feedback.map((draft, index) => {
+    const address = parseMemoryAddressKey(draft.memoryAddress);
+    if (!address || !allowedScopes.has(`${address.scope.kind}:${address.scope.id}`)) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_SCOPE_INVALID: ${index}`);
+    }
+    if (!read.readByAddresses([address]).length) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_NOT_FOUND: ${index}`);
+    }
+    const reason = draft.reason.trim();
+    if (!reason || reason.length > 1_000) throw new Error(`COGNITION_DIRECT_FEEDBACK_REASON_INVALID: ${index}`);
+    if (draft.decision === 'rejected' && !draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+    }
+    if (draft.decision === 'used' && draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+    }
+    const observationId = `usage:${createHash('sha256')
+      .update(JSON.stringify({
+        actor: principalId,
+        interaction: interactionId,
+        address: memoryAddressKey(address),
+        decision: draft.decision,
+        rejectionKind: draft.rejectionKind ?? '',
+        reason,
+      }))
+      .digest('hex').slice(0, 32)}`;
+    return recordCognitiveUsageObservation(input.controllerHome, {
+      observationId,
+      address,
+      actorId: principalId,
+      decision: draft.decision,
+      reason,
+      ...(draft.rejectionKind ? { rejectionKind: draft.rejectionKind } : {}),
+      observedAt: now,
+    });
+  });
+  return { observationIds: observations.map(item => item.observationId), scopes };
+}
+
+export function persistDirectControllerLearning(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  signals: readonly ControllerLearningSignalDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+  workId?: string;
+  now?: string;
+}): DirectControllerLearningResult {
+  if (!input.signals.length || input.signals.length > CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS) {
+    throw new Error('COGNITION_DIRECT_LEARNING_SIGNALS_INVALID');
+  }
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const observedAt = input.now ?? new Date().toISOString();
+  const sourceId = directSourceId(input);
+  const projectScope = scopes.find(scope => scope.kind === 'project')!;
+  const workspaceScope = scopes.find(scope => scope.kind === 'workspace')!;
+  const store = cognitionMemoryStore(input.controllerHome);
+  const authority = directLearningAuthority({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    scopes,
+    principalId: input.principalId,
+    sourceId,
+    sourceWorkId: input.workId,
+  });
+
+  const drafts = input.signals.map(signal => {
+    const scope = scopes.find(candidate => candidate.kind === signal.scopeKind)
+      ?? (signal.scopeKind === 'project' ? projectScope : signal.scopeKind === 'workspace' ? workspaceScope : undefined);
+    if (!scope) {
+      throw new Error(`COGNITION_LEARNING_SCOPE_UNREACHABLE: ${signal.scopeKind}`);
+    }
+    const id = semanticSignalId(signal, scope);
+    const learning: LearningSignal = {
+      schemaVersion: 1,
+      id: `direct:${id}`,
+      scope,
+      kind: signal.kind,
+      valence: signal.valence,
+      summary: signal.summary,
+      concepts: [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))],
+      facets: [...new Set(signal.facets.map(value => value.trim()).filter(Boolean))],
+      admissionSource: signal.admissionSource,
+      portability: signal.portability,
+      salience: signal.salience,
+      confidence: signal.confidence,
+      utility: signal.utility,
+      sourceKind: 'controller',
+      sourceId,
+      observedAt,
+      evidenceRefs: [...new Set(signal.evidenceRefs)],
+      counterEvidenceRefs: [...new Set(signal.counterEvidenceRefs)],
+      ...(signal.expiresAt ? { expiresAt: signal.expiresAt } : {}),
+    };
+    const draft = memoryDraftFromLearningSignal(learning);
+    return input.workId ? {
+      ...draft,
+      provenance: {
+        ...draft.provenance,
+        sourceWorkId: input.workId,
+      },
+    } : draft;
+  });
+
+  // Validate all evidence before any write so a multi-signal call cannot partially commit.
+  for (const draft of drafts) {
+    authority.assertMemoryWrite({ ...draft, schemaVersion: 1, revision: 1 });
+    for (const ref of [...draft.provenance.evidenceRefs, ...draft.counterEvidenceRefs]) {
+      if (!authority.evidenceAvailable(ref, draft.scope)) {
+        throw new Error(`COGNITION_DIRECT_LEARNING_EVIDENCE_UNAVAILABLE: ${ref}`);
+      }
+    }
+  }
+
+  const stored = store.transaction(() => drafts.map(draft =>
+    recordCognitiveMemory(store, authority, draft)));
+  const associatedEdgeCount = associateStoredMemories({
+    controllerHome: input.controllerHome,
+    memories: stored,
+    now: observedAt,
+  });
+  const consolidatedMemoryIds = scopes.flatMap(scope =>
+    consolidateAffectedMemories(input.controllerHome, scope, stored, observedAt).map(candidate => candidate.memory.id));
+  return {
+    storedMemoryIds: stored.map(memory => memory.id),
+    associatedEdgeCount,
+    consolidatedMemoryIds: [...new Set(consolidatedMemoryIds)],
+    scopes,
+  };
+}

package/src/runtime/context/semantic-navigation-contract.ts

@@ -32,10 +32,19 @@ export type SemanticNavigationOutcome =
   | { ok: true; result: SemanticNavigationResult }
   | { ok: false; code: string; message: string };
 
+export interface SemanticNavigationReadPolicy {
+  profile: string;
+  readGlobs: readonly string[];
+  denyGlobs: readonly string[];
+  maxFileBytes: number;
+}
+
 export interface SemanticNavigationAccess {
   cacheScope: string;
   sourceIdentity?: string;
   profile: string;
+  /** Serializable policy used by disposable semantic sidecars. */
+  readPolicy?: SemanticNavigationReadPolicy;
   allowRepositoryPath(relativePath: string): boolean;
 }
 

package/src/runtime/context/semantic-navigation.ts

@@ -1,5 +1,5 @@
 import { extname } from 'path';
-import { navigateTypeScriptSymbol } from './typescript-navigation';
+import { navigateTypeScriptInSidecar } from './typescript-navigation-process';
 import { navigateSwiftSymbols } from './swift-navigation';
 import { GenericLspSemanticProvider, type GenericLspProviderDescriptor } from './generic-lsp-provider';
 
@@ -25,39 +25,11 @@ const typeScriptProvider: SemanticNavigationProvider = {
     return extensionSupported && (!request.language || request.language.toLowerCase() === 'typescript');
   },
   async navigate(repoRoot, requests, access) {
-    return requests.map((request) => {
-      let policyDeniedReads = 0;
-      try {
-        const result = navigateTypeScriptSymbol(repoRoot, {
-          navigation: request.navigation,
-          path: request.path,
-          line: request.line,
-          column: request.column,
-          tsconfigPath: request.tsconfigPath,
-        }, {
-          cacheScope: access.cacheScope,
-          sourceIdentity: access.sourceIdentity,
-          allowRepositoryPath: (relativePath) => {
-            const allowed = access.allowRepositoryPath(relativePath);
-            if (!allowed) policyDeniedReads += 1;
-            return allowed;
-          },
-        });
-        return {
-          ok: true,
-          result: {
-            providerId: 'typescript-language-service',
-            language: 'typescript',
-            navigation: result.navigation,
-            target: result.target,
-            locations: result.locations,
-            policyDeniedReads,
-          },
-        } satisfies SemanticNavigationOutcome;
-      } catch (error) {
-        return { ok: false, code: 'SEMANTIC_NAVIGATION_FAILED', message: error instanceof Error ? error.message : String(error) } satisfies SemanticNavigationOutcome;
-      }
-    });
+    // A Forge-sized TypeScript LanguageService can return its live heap after
+    // dispose() while JSC/WebKit keeps the expanded allocator resident. Keep
+    // that allocator lifetime out of the canonical Runtime: one bounded batch
+    // runs in one short-lived sidecar and the OS reclaims it on process exit.
+    return navigateTypeScriptInSidecar(repoRoot, requests, access);
   },
 };
 

package/src/runtime/context/typescript-navigation-process.ts

@@ -0,0 +1,145 @@
+import { existsSync, lstatSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { runProcess } from '../../effects/process-runner';
+import { resolveBunExecutable } from '../shared/process-environment';
+import type {
+  SemanticNavigationAccess,
+  SemanticNavigationOutcome,
+  SemanticNavigationRequest,
+} from './semantic-navigation-contract';
+
+const TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT = 'forge-typescript-navigation' as const;
+const TYPESCRIPT_NAVIGATION_TIMEOUT_MS = 60_000;
+const TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+interface SidecarResponse {
+  schemaVersion: 1;
+  outcomes: SemanticNavigationOutcome[];
+}
+
+interface SourceSymbolsSidecarResponse {
+  schemaVersion: 1;
+  symbols: Array<{ startLine: number; endLine: number; kind: string; name?: string; enclosing?: string }>;
+}
+
+interface SidecarManifestRecord {
+  typescriptNavigationEntrypoint?: unknown;
+  typescriptNavigationArtifactIdentity?: unknown;
+}
+
+function releaseManifestArgument(argv: readonly string[]): string | undefined {
+  const index = argv.indexOf('--release-manifest');
+  const value = index >= 0 ? argv[index + 1]?.trim() : undefined;
+  return value ? resolve(value) : undefined;
+}
+
+export function resolveTypeScriptNavigationSidecarCommand(
+  argv: readonly string[] = process.argv,
+): { executable: string; args: string[]; cwd?: string } {
+  const manifestPath = releaseManifestArgument(argv);
+  if (manifestPath) {
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as SidecarManifestRecord;
+    if (parsed.typescriptNavigationEntrypoint !== TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_MANIFEST_MISSING');
+    }
+    const identity = typeof parsed.typescriptNavigationArtifactIdentity === 'string'
+      ? parsed.typescriptNavigationArtifactIdentity.trim()
+      : '';
+    if (!/^sha256:[a-f0-9]{64}$/i.test(identity)) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_IDENTITY_INVALID');
+    }
+    const executable = join(dirname(manifestPath), TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT);
+    if (!existsSync(executable)) throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_MISSING');
+    const status = lstatSync(executable);
+    if (status.isSymbolicLink() || !status.isFile() || (status.mode & 0o111) === 0) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_NOT_EXECUTABLE');
+    }
+    return { executable, args: [], cwd: dirname(manifestPath) };
+  }
+
+  // Construct the development-only path at runtime. A literal new URL() to the
+  // .ts sidecar makes Bun bundle that file as an asset and drags the TypeScript
+  // compiler graph back into the long-lived Runtime.
+  const entry = resolve(process.cwd(), 'adapters', 'mcp', 'runtime-gateway', 'typescript-navigation-sidecar.ts');
+  if (!existsSync(entry)) throw new Error('TYPESCRIPT_NAVIGATION_SOURCE_SIDECAR_MISSING');
+  return {
+    executable: resolveBunExecutable(process.execPath, process.env),
+    args: [entry],
+    cwd: dirname(entry),
+  };
+}
+
+function failedOutcomes(requests: readonly SemanticNavigationRequest[], code: string, message: string): SemanticNavigationOutcome[] {
+  return requests.map(() => ({ ok: false as const, code, message }));
+}
+
+export function extractTypeScriptSourceSymbolsInSidecar(
+  path: string,
+  source: string,
+): SourceSymbolsSidecarResponse['symbols'] {
+  const command = resolveTypeScriptNavigationSidecarCommand();
+  const executed = runProcess(command.executable, command.args, {
+    cwd: command.cwd ?? process.cwd(),
+    input: JSON.stringify({ schemaVersion: 1, operation: 'source_symbols', path, source }),
+    timeoutMs: TYPESCRIPT_NAVIGATION_TIMEOUT_MS,
+    maxOutputBytes: TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES,
+  });
+  if (!executed.ok) {
+    throw new Error(`TYPESCRIPT_SOURCE_SYMBOL_SIDECAR_FAILED: ${(executed.stderr || executed.stdout || executed.error || 'unknown failure').trim().slice(0, 2_000)}`);
+  }
+  const response = JSON.parse(executed.stdout) as SourceSymbolsSidecarResponse;
+  if (response.schemaVersion !== 1 || !Array.isArray(response.symbols)) {
+    throw new Error('TYPESCRIPT_SOURCE_SYMBOL_SIDECAR_RESPONSE_INVALID');
+  }
+  return response.symbols;
+}
+
+export function navigateTypeScriptInSidecar(
+  repoRoot: string,
+  requests: SemanticNavigationRequest[],
+  access: SemanticNavigationAccess,
+): SemanticNavigationOutcome[] {
+  if (!access.readPolicy) {
+    return failedOutcomes(requests, 'SEMANTIC_READ_POLICY_REQUIRED', 'TypeScript semantic navigation requires a serializable repository read policy.');
+  }
+
+  let command: ReturnType<typeof resolveTypeScriptNavigationSidecarCommand>;
+  try {
+    command = resolveTypeScriptNavigationSidecarCommand();
+  } catch (error) {
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_UNAVAILABLE', error instanceof Error ? error.message : String(error));
+  }
+
+  const envelope = {
+    schemaVersion: 1,
+    operation: 'navigation',
+    repoRoot: resolve(repoRoot),
+    requests,
+    access: {
+      cacheScope: access.cacheScope,
+      ...(access.sourceIdentity ? { sourceIdentity: access.sourceIdentity } : {}),
+      profile: access.profile,
+      readPolicy: access.readPolicy,
+    },
+  };
+  const executed = runProcess(command.executable, command.args, {
+    cwd: command.cwd ?? repoRoot,
+    input: JSON.stringify(envelope),
+    timeoutMs: TYPESCRIPT_NAVIGATION_TIMEOUT_MS,
+    maxOutputBytes: TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES,
+  });
+  if (!executed.ok) {
+    const detail = (executed.stderr || executed.stdout || executed.error || 'TypeScript navigation sidecar failed').trim();
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_FAILED', detail.slice(0, 2_000));
+  }
+
+  try {
+    const response = JSON.parse(executed.stdout) as SidecarResponse;
+    if (response.schemaVersion !== 1 || !Array.isArray(response.outcomes) || response.outcomes.length !== requests.length) {
+      throw new Error('invalid sidecar response shape');
+    }
+    return response.outcomes;
+  } catch (error) {
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_RESPONSE_INVALID', error instanceof Error ? error.message : String(error));
+  }
+}

package/src/runtime/context/typescript-navigation.ts

@@ -26,6 +26,14 @@ export interface TypeScriptNavigationResult {
   locations: TypeScriptNavigationLocation[];
 }
 
+export interface TypeScriptSourceSymbolRange {
+  startLine: number;
+  endLine: number;
+  kind: string;
+  name?: string;
+  enclosing?: string;
+}
+
 export interface TypeScriptNavigationAccess {
   /** Stable identity for one read-policy scope. Restricted and unrestricted projects must never share a Language Service. */
   cacheScope: string;
@@ -38,11 +46,13 @@ export interface TypeScriptNavigationAccess {
 interface CachedProject {
   repoRoot: string;
   configPath: string;
+  configVersion: string;
+  sourceIdentity: string;
   service: ts.LanguageService;
 }
 
 const projects = new Map<string, CachedProject>();
-const MAX_CACHED_TYPESCRIPT_PROJECTS = 32;
+const MAX_CACHED_TYPESCRIPT_PROJECTS = 1;
 
 function normalizePath(path: string): string {
   return path.replace(/\\/g, '/');
@@ -71,13 +81,19 @@ function loadProject(repoRoot: string, tsconfigPath = 'tsconfig.json', access?:
   if (access && !access.allowRepositoryPath(configRelative)) {
     throw new Error(`TypeScript navigation tsconfig is denied by read policy: ${configRelative}.`);
   }
-  const cacheKey = `${root}\0${configPath}\0${scriptVersion(configPath)}\0${access?.cacheScope ?? 'unrestricted'}\0${access?.sourceIdentity ?? 'unbound-source'}`;
+  const configVersion = scriptVersion(configPath);
+  const sourceIdentity = access?.sourceIdentity ?? 'unbound-source';
+  const cacheKey = `${root}\0${configPath}\0${access?.cacheScope ?? 'unrestricted'}`;
   const cached = projects.get(cacheKey);
-  if (cached) {
+  if (cached && cached.configVersion === configVersion && cached.sourceIdentity === sourceIdentity) {
     projects.delete(cacheKey);
     projects.set(cacheKey, cached);
     return cached;
   }
+  if (cached) {
+    projects.delete(cacheKey);
+    cached.service.dispose();
+  }
 
   const canReadAbsolute = (fileName: string): boolean => {
     if (!access) return true;
@@ -129,6 +145,8 @@ function loadProject(repoRoot: string, tsconfigPath = 'tsconfig.json', access?:
   const project = {
     repoRoot: root,
     configPath,
+    configVersion,
+    sourceIdentity,
     service: ts.createLanguageService(host, ts.createDocumentRegistry()),
   };
   projects.set(cacheKey, project);
@@ -176,6 +194,70 @@ function location(
   };
 }
 
+function sourceScriptKind(path: string): ts.ScriptKind | undefined {
+  if (/\.tsx$/i.test(path)) return ts.ScriptKind.TSX;
+  if (/\.jsx$/i.test(path)) return ts.ScriptKind.JSX;
+  if (/\.(?:mts|cts|ts)$/i.test(path)) return ts.ScriptKind.TS;
+  if (/\.(?:mjs|cjs|js)$/i.test(path)) return ts.ScriptKind.JS;
+  return undefined;
+}
+
+function sourceDeclarationName(node: ts.Node): string | undefined {
+  const named = node as ts.Node & { name?: ts.Node };
+  return named.name ? named.name.getText().slice(0, 200) : undefined;
+}
+
+function sourceDeclarationKind(node: ts.Node): string | undefined {
+  if (ts.isFunctionDeclaration(node)) return 'function';
+  if (ts.isMethodDeclaration(node)) return 'method';
+  if (ts.isConstructorDeclaration(node)) return 'constructor';
+  if (ts.isGetAccessorDeclaration(node)) return 'getter';
+  if (ts.isSetAccessorDeclaration(node)) return 'setter';
+  if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return 'class';
+  if (ts.isInterfaceDeclaration(node)) return 'interface';
+  if (ts.isTypeAliasDeclaration(node)) return 'type';
+  if (ts.isEnumDeclaration(node)) return 'enum';
+  if (ts.isModuleDeclaration(node)) return 'module';
+  if (ts.isVariableStatement(node) && node.declarationList.declarations.some((declaration) =>
+    declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)))) return 'function-variable';
+  return undefined;
+}
+
+function sourceEnclosingName(node: ts.Node): string | undefined {
+  let current = node.parent;
+  while (current) {
+    if (ts.isClassDeclaration(current) || ts.isClassExpression(current) || ts.isInterfaceDeclaration(current) || ts.isModuleDeclaration(current)) {
+      const kind = sourceDeclarationKind(current) ?? 'container';
+      const name = sourceDeclarationName(current);
+      return name ? `${kind}:${name}` : kind;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+export function extractTypeScriptSourceSymbols(path: string, source: string): TypeScriptSourceSymbolRange[] {
+  const kind = sourceScriptKind(path);
+  if (kind === undefined) return [];
+  const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);
+  const declarations: TypeScriptSourceSymbolRange[] = [];
+  const visit = (node: ts.Node): void => {
+    const declarationKind = sourceDeclarationKind(node);
+    if (declarationKind) {
+      declarations.push({
+        startLine: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+        endLine: sourceFile.getLineAndCharacterOfPosition(node.end).line + 1,
+        kind: declarationKind,
+        ...(sourceDeclarationName(node) ? { name: sourceDeclarationName(node) } : {}),
+        ...(sourceEnclosingName(node) ? { enclosing: sourceEnclosingName(node) } : {}),
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return declarations;
+}
+
 function dedupe(locations: TypeScriptNavigationLocation[]): TypeScriptNavigationLocation[] {
   const seen = new Set<string>();
   return locations.filter((entry) => {
@@ -220,6 +302,10 @@ export function navigateTypeScriptSymbol(
   };
 }
 
+export function typeScriptNavigationCachedProjectCount(): number {
+  return projects.size;
+}
+
 export function clearTypeScriptNavigationCache(): void {
   for (const project of projects.values()) project.service.dispose();
   projects.clear();