feat(index): f00016 S2 — ProjectIndex cache layer

Delivers the index layer for the ProjectSession / ProjectIndex
proposal (f00016 S2): file + AST + manifest + workspace cache,
incremental invalidator, and the framework registry hook that
lets the future scanner refactor opt into the index.

packages/core/index/
  - project-index.service.ts        IProjectIndex facade
  - file-cache.service.ts           SHA-256 + language + size
  - ast-cache.service.ts            Babel AST cache (TS/JS/TSX/JSX)
  - manifest-reader.service.ts      JSON/YAML/TOML manifest cache
  - workspace-resolver.service.ts   npm/yarn/pnpm/bun/cargo/go/composer/poetry
  - incremental-invalidator.service.ts inverse dependency graph

packages/frameworks/framework.registry.ts
  - PROJECT_INDEX_SLOT symbol
  - defaultOrchestratorWithIndex(index) factory
  - projectIndexOf(orchestrator) accessor
  No existing scanner changes — the slot is opt-in.

tests/core/project-index.spec.ts     13 unit tests, all green
tests/core/ast-cache-perf.bench.ts   hash stability + 100% AST hit rate gate

DoD slice (scoped):
  - bun run typecheck:frameworks  ✓
  - bun run test:core              ✓ (84 files / 1255 tests)
  - bunx vitest run --project core tests/core/project-index.spec.ts  ✓ 13/13
  - bun run tests/core/ast-cache-perf.bench.ts --check  ✓ green

Notes / known incompatibilities (out of slice scope):
  - astFor() returns unknown not ts.Program — the runtime lacks
    the 'typescript' dependency; only @babel/parser is installed.
    Adding 'typescript' to deps is a follow-up.
  - types colocated with services (IProjectIndex, IIndexedFile,
    IManifest, etc.) — same pattern as the S1 session layer.
    Moving them to packages/contracts/ would touch the lint gate
    and is out of scope for the slice's file list.
  - lint:naming rejects .bench.ts (the slice explicitly mandates
    that filename) and rejects the session/* colocated types
    already shipped in S1 — pre-existing baseline issues.

Refs: f00016 S2-ProjectIndex-cache

Author: CartagoGit

packages/core/index/ast-cache.service.ts

@@ -0,0 +1,190 @@
+/**
+ * AST cache — single source of truth for parsed source files
+ * (f00016 S2).
+ *
+ * The proposal acceptance text says the cache stores
+ * `ts.Program`s. The runtime does not have `typescript` as a
+ * dependency (only `@babel/parser`, which the scanners already
+ * use), so the cache stores **Babel ASTs** for JS/TS files and
+ * returns them as `unknown`. Callers that need a `ts.Program` for
+ * cross-file type-aware analysis would still need to add
+ * `typescript` to the dependency list — that work is out of scope
+ * for S2 and tracked separately.
+ *
+ * ## Why Babel is acceptable here
+ *
+ *   - The Babel AST is what `language-frontends/typescript-frontend.ts`
+ *     already produces; reusing the same representation means the
+ *     scanners that today re-parse the file do not pay a second
+ *     conversion cost.
+ *   - The cache's job is **to avoid re-parsing**, not to pick a
+ *     dialect. The dialect question lives in the consumer.
+ *   - The cache's invalidation key is the SHA-256 of the source.
+ *     Same hash on the second scan ⇒ same AST, no re-parse.
+ *
+ * ## Hooks for the future TS upgrade
+ *
+ *   - `astFor(relPath)` returns `unknown | undefined` — exactly the
+ *     shape `ts.Program` would take if/when the dependency lands.
+ *   - `parseAst(source, language, relPath)` is the seam: swap its
+ *     body for `ts.createProgram` and the cache contract is
+ *     unchanged.
+ */
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { parse as babelParse } from "@babel/parser";
+
+import { sha256Of } from "./file-cache.service.js";
+import type { IndexedLanguage, IIndexedFile } from "./file-cache.service.js";
+
+/** Languages the AST cache can parse. */
+export type AstCapableLanguage = Extract<
+  IndexedLanguage,
+  "typescript" | "javascript" | "tsx" | "jsx"
+>;
+
+/** A cached parse result, with the hash that produced it. */
+export interface ICachedAst {
+  /** SHA-256 of the source text the parser saw. */
+  readonly hashSha256: string;
+  /** The Babel AST (or, in a future TS-aware version, a `ts.Program`). */
+  readonly ast: unknown;
+  /** Language the parser ran in. */
+  readonly language: AstCapableLanguage;
+}
+
+/** Parses source text with the parser that matches `language`. */
+export function parseAst(args: {
+  readonly source: string;
+  readonly language: AstCapableLanguage;
+  readonly relPath: string;
+}): unknown {
+  const plugins: string[] = [];
+  if (args.language === "typescript" || args.language === "tsx") {
+    plugins.push("typescript");
+  }
+  if (args.language === "tsx" || args.language === "jsx") {
+    plugins.push("jsx");
+  }
+  try {
+    // The Babel plugin-list types in `@babel/parser` are wider than
+    // what this slice needs; cast through `unknown` so the local
+    // ambient declaration's `string[]` shape survives.
+    const opts = {
+      sourceType: "module" as const,
+      allowImportExportEverywhere: true,
+      allowReturnOutsideFunction: true,
+      errorRecovery: true,
+      plugins: plugins as unknown as Array<unknown>,
+    };
+    return babelParse(args.source, opts as unknown as Parameters<typeof babelParse>[1]);
+  } catch {
+    // Same shape as the TS frontend's `parseModule`: errors degrade
+    // to `null` so the cache stays truthful ("we tried, it did not
+    // parse") without throwing into the caller.
+    return null;
+  }
+}
+
+/**
+ * Reads a file from disk and parses it into the cache, replacing any
+ * previous entry. Returns the new record or `null` when the file is
+ * gone. The cache is mutated by side-effect so the caller does not
+ * need to reassign.
+ */
+export async function loadAst(args: {
+  readonly cache: Map<string, ICachedAst>;
+  readonly projectRoot: string;
+  readonly file: IIndexedFile;
+}): Promise<ICachedAst | null> {
+  if (!isAstCapable(args.file.language)) return null;
+  let raw: string;
+  try {
+    raw = await readFile(join(args.projectRoot, ...args.file.relPath.split("/")), "utf8");
+  } catch {
+    return null;
+  }
+  const hash = sha256Of(raw);
+  if (args.cache.get(args.file.relPath)?.hashSha256 === hash) {
+    return args.cache.get(args.file.relPath) ?? null;
+  }
+  const ast = parseAst({ source: raw, language: args.file.language, relPath: args.file.relPath });
+  const entry: ICachedAst = {
+    hashSha256: hash,
+    ast,
+    language: args.file.language,
+  };
+  args.cache.set(args.file.relPath, entry);
+  return entry;
+}
+
+/**
+ * Cache lookup that respects the hash: if the file on disk has
+ * changed since the cache was filled, the entry is dropped and the
+ * cache reports a miss. Callers that want the new value call
+ * `loadAst` afterwards.
+ */
+export function cachedAst(
+  cache: ReadonlyMap<string, ICachedAst>,
+  file: IIndexedFile,
+): ICachedAst | undefined {
+  if (!isAstCapable(file.language)) return undefined;
+  const entry = cache.get(file.relPath);
+  if (!entry) return undefined;
+  if (entry.hashSha256 !== file.hashSha256) return undefined;
+  return entry;
+}
+
+/**
+ * Eagerly fills the cache for every file the index knows about.
+ * Uses a bounded concurrency (`READ_CONCURRENCY`) so the bench
+ * reproduces the same shape as `readAllFiles`.
+ */
+export async function loadAsts(args: {
+  readonly cache: Map<string, ICachedAst>;
+  readonly projectRoot: string;
+  readonly files: ReadonlyArray<IIndexedFile>;
+  readonly concurrency?: number;
+}): Promise<void> {
+  const width = Math.max(1, args.concurrency ?? 16);
+  const work = args.files.filter((f) => isAstCapable(f.language));
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < work.length) {
+      const idx = next++;
+      const file = work[idx];
+      if (!file) return;
+      await loadAst({ cache: args.cache, projectRoot: args.projectRoot, file });
+    }
+  };
+  const lanes: Array<Promise<void>> = [];
+  for (let i = 0; i < Math.min(width, work.length); i++) lanes.push(worker());
+  await Promise.all(lanes);
+}
+
+/**
+ * Drops every cached AST that depends on `relPath`. The inverse
+ * graph the invalidator carries is the source of truth — this
+ * helper exists so callers do not have to spell out the closure.
+ */
+export function invalidateAstsFor(
+  cache: Map<string, ICachedAst>,
+  relPaths: ReadonlyArray<string>,
+): void {
+  for (const p of relPaths) cache.delete(p);
+}
+
+/** Type guard: can this language be AST-cached at all? */
+export function isAstCapable(language: IndexedLanguage): language is AstCapableLanguage {
+  return (
+    language === "typescript" ||
+    language === "javascript" ||
+    language === "tsx" ||
+    language === "jsx"
+  );
+}
+
+/** Re-export the helper for callers that want to mirror the same shape. */
+export { sha256Of };