@saptools/service-flow 0.1.51 → 0.1.53

package/src/db/migrations.ts

@@ -1,6 +1,6 @@
 import type { Db } from './connection.js';
-import { schemaSql } from './schema.js';
-const CURRENT_SCHEMA_VERSION = 10;
+import { schemaIndexesSql, schemaTablesSql } from './schema.js';
+const CURRENT_SCHEMA_VERSION = 11;
 const columns: Record<string, Array<{ name: string; ddl: string }>> = {
   handler_methods: [
     { name: 'decorator_resolution_json', ddl: "ALTER TABLE handler_methods ADD COLUMN decorator_resolution_json TEXT NOT NULL DEFAULT '{}'" },
@@ -57,6 +57,7 @@ const columns: Record<string, Array<{ name: string; ddl: string }>> = {
   ],
   index_runs: [
     { name: 'error_message', ddl: 'ALTER TABLE index_runs ADD COLUMN error_message TEXT' },
+    { name: 'owner_pid', ddl: 'ALTER TABLE index_runs ADD COLUMN owner_pid INTEGER' },
   ],
 };
 function hasColumn(db: Db, table: string, column: string): boolean {
@@ -81,8 +82,9 @@ export function migrate(db: Db): void {
   db.transaction(() => {
     const version = userVersion(db);
     if (version > CURRENT_SCHEMA_VERSION) throw new Error(`Unsupported future service-flow schema version ${version}`);
-    db.exec(schemaSql);
+    db.exec(schemaTablesSql);
     addMissingColumns(db);
+    db.exec(schemaIndexesSql);
     normalizeLegacyStatus(db);
     const violations = db.pragma('foreign_key_check');
     if (violations.length > 0) throw new Error('SQLite foreign_key_check failed during migration');

package/src/db/repositories.ts

@@ -1,8 +1,10 @@
 import type { Db } from './connection.js';
+import { projectBounded } from '../utils/000-bounded-projection.js';
 import type {
   CdsRequire,
   CdsServiceFact,
   HandlerClassFact,
+  HandlerMethodFact,
   HandlerRegistrationFact,
   OutboundCallFact,
   ServiceBindingFact,
@@ -85,15 +87,29 @@ export function upsertRepository(
       .get(workspaceId, r.absolutePath)?.id,
   );
 }
-export function listRepositories(db: Db): RepoRow[] {
+export function listRepositories(db: Db, workspaceId?: number): RepoRow[] {
   return db
-    .prepare('SELECT * FROM repositories ORDER BY name')
-    .all() as unknown as RepoRow[];
+    .prepare('SELECT * FROM repositories WHERE (? IS NULL OR workspace_id=?) ORDER BY name,absolute_path,id')
+    .all(workspaceId, workspaceId) as unknown as RepoRow[];
 }
-export function repoByName(db: Db, name: string): RepoRow | undefined {
+export function repoByName(
+  db: Db,
+  name: string,
+  workspaceId?: number,
+): RepoRow | undefined {
+  const matches = reposByName(db, name, workspaceId);
+  return matches.length === 1 ? matches[0] : undefined;
+}
+export function reposByName(
+  db: Db,
+  name: string,
+  workspaceId?: number,
+): RepoRow[] {
   return db
-    .prepare('SELECT * FROM repositories WHERE name=? OR package_name=?')
-    .get(name, name) as RepoRow | undefined;
+    .prepare(`SELECT * FROM repositories
+      WHERE (? IS NULL OR workspace_id=?) AND (name=? OR package_name=?)
+      ORDER BY name,absolute_path,id`)
+    .all(workspaceId, workspaceId, name, name) as unknown as RepoRow[];
 }
 export function clearRepoFacts(db: Db, repoId: number): void {
   for (const t of [
@@ -188,21 +204,7 @@ export function insertHandler(
   repoId: number,
   h: HandlerClassFact,
 ): number {
-  const sid = Number(
-    db
-      .prepare(
-        'INSERT INTO symbols(repo_id,kind,name,qualified_name,exported,start_line,end_line) VALUES(?,?,?,?,?,?,?) RETURNING id',
-      )
-      .get(
-        repoId,
-        'class',
-        h.className,
-        h.className,
-        1,
-        h.sourceLine,
-        h.sourceLine,
-      )?.id,
-  );
+  const sid = insertHandlerClassSymbol(db, repoId, h);
   const hid = Number(
     db
       .prepare(
@@ -220,12 +222,109 @@ export function insertHandler(
       m.decoratorKind,
       m.decoratorValue,
       m.decoratorRawExpression,
-      JSON.stringify(m.decoratorResolution),
+      JSON.stringify(canonicalHandlerMethodResolution(m)),
       m.sourceFile,
       m.sourceLine,
     );
+  insertHandlerIndexDiagnostic(db, repoId, h);
   return hid;
 }
+function insertHandlerClassSymbol(
+  db: Db,
+  repoId: number,
+  h: HandlerClassFact,
+): number {
+  const classEvidence = {
+    hasHandlerDecorator: h.hasHandlerDecorator ?? false,
+    classDecoratorNames: h.classDecoratorNames ?? [],
+    observedDecoratorNames: h.observedDecoratorNames ?? [],
+    unsupportedDecoratorNames: h.unsupportedDecoratorNames ?? [],
+    unsupportedMethods: h.methods
+      .filter((method) => !handlerMethodIsExecutable(method))
+      .map((method) => ({
+        methodName: method.methodName,
+        decoratorKind: method.decoratorKind,
+        sourceFile: method.sourceFile,
+        sourceLine: method.sourceLine,
+        reason: method.decoratorResolution.unresolvedReason,
+      })),
+  };
+  return Number(
+    db
+      .prepare(
+        'INSERT INTO symbols(repo_id,kind,name,qualified_name,exported,start_line,end_line,source_file,evidence_json) VALUES(?,?,?,?,?,?,?,?,?) RETURNING id',
+      )
+      .get(
+        repoId,
+        'class',
+        h.className,
+        h.className,
+        1,
+        h.sourceLine,
+        h.sourceLine,
+        h.sourceFile,
+        JSON.stringify(classEvidence),
+      )?.id,
+  );
+}
+function insertHandlerIndexDiagnostic(
+  db: Db,
+  repoId: number,
+  h: HandlerClassFact,
+): void {
+  if (!h.hasHandlerDecorator) return;
+  const hasExecutable = h.methods.some(handlerMethodIsExecutable);
+  const unsupported = h.methods.filter((method) =>
+    !handlerMethodIsExecutable(method));
+  if (hasExecutable && unsupported.length === 0) return;
+  const code = hasExecutable
+    ? 'handler_decorators_not_indexed'
+    : 'handler_methods_not_indexed';
+  const names = unsupported.map((method) => method.decoratorKind).sort();
+  const detail = names.length > 0
+    ? ` Unsupported decorators: ${[...new Set(names)].join(', ')}.`
+    : '';
+  db.prepare(
+    'INSERT INTO diagnostics(repo_id,severity,code,message,source_file,source_line) VALUES(?,?,?,?,?,?)',
+  ).run(
+    repoId,
+    'warning',
+    code,
+    hasExecutable
+      ? `Handler class ${h.className} contains methods that were not indexed.${detail}`
+      : `Handler class ${h.className} has no indexed executable methods; use a supported CAP handler decorator and re-index.${detail}`,
+    h.sourceFile,
+    h.sourceLine,
+  );
+}
+export function canonicalHandlerMethodResolution(
+  method: HandlerMethodFact,
+): HandlerMethodFact['decoratorResolution'] {
+  const handlerKind = method.handlerKind
+    ?? method.decoratorResolution.handlerKind
+    ?? legacyHandlerKind(method.decoratorKind);
+  const executable = method.executable
+    ?? method.decoratorResolution.executable
+    ?? (handlerKind === 'operation' || handlerKind === 'event'
+      || handlerKind === 'entity_lifecycle');
+  return {
+    ...method.decoratorResolution,
+    handlerKind,
+    executable,
+    lifecyclePhase: method.lifecyclePhase
+      ?? method.decoratorResolution.lifecyclePhase,
+    lifecycleEvent: method.lifecycleEvent
+      ?? method.decoratorResolution.lifecycleEvent,
+  };
+}
+export function handlerMethodIsExecutable(method: HandlerMethodFact): boolean {
+  return canonicalHandlerMethodResolution(method).executable === true;
+}
+function legacyHandlerKind(kind: string): HandlerMethodFact['handlerKind'] {
+  if (kind === 'Event') return 'event';
+  if (['Action', 'Func', 'On'].includes(kind)) return 'operation';
+  return 'unsupported_decorator';
+}
 export function insertRegistrations(
   db: Db,
   repoId: number,
@@ -498,12 +597,19 @@ function bindingEvidence(
   candidates: BindingCandidate[],
   selected?: BindingCandidate,
 ): Record<string, unknown> {
+  const projection = projectBounded(candidates, (left, right) =>
+    Number(right.id === selected?.id) - Number(left.id === selected?.id)
+    || left.sourceFile.localeCompare(right.sourceFile)
+    || left.sourceLine - right.sourceLine
+    || left.id - right.id);
   return {
     status,
-    candidateCount: candidates.length,
+    candidateCount: projection.totalCount,
+    shownCandidateCount: projection.shownCount,
+    omittedCandidateCount: projection.omittedCount,
     selectedBindingId: selected?.id,
     sourceOrderRule: 'binding_source_line_must_not_follow_call',
-    candidates: candidates.map((candidate) => ({
+    candidates: projection.items.map((candidate) => ({
       bindingId: candidate.id,
       symbolId: candidate.symbolId,
       variableName: candidate.variableName,

package/src/db/schema.ts

@@ -1,4 +1,4 @@
-export const schemaSql = `
+export const schemaTablesSql = `
 CREATE TABLE IF NOT EXISTS workspaces (id INTEGER PRIMARY KEY, root_path TEXT UNIQUE NOT NULL, db_path TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, fact_generation INTEGER NOT NULL DEFAULT 0, graph_generation INTEGER NOT NULL DEFAULT 0, graph_stale_reason TEXT, graph_stale_at TEXT, fact_analyzer_version TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS files (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, relative_path TEXT NOT NULL, extension TEXT NOT NULL, sha256 TEXT NOT NULL, size_bytes INTEGER NOT NULL, last_indexed_at TEXT NOT NULL, UNIQUE(repo_id, relative_path), FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
@@ -13,8 +13,11 @@ CREATE TABLE IF NOT EXISTS service_bindings (id INTEGER PRIMARY KEY, repo_id INT
 CREATE TABLE IF NOT EXISTS outbound_calls (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, source_symbol_id INTEGER, call_type TEXT NOT NULL, service_binding_id INTEGER, method TEXT, operation_path_expr TEXT, query_entity TEXT, event_name_expr TEXT, payload_summary TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, confidence REAL NOT NULL, unresolved_reason TEXT, local_service_name TEXT, local_service_lookup TEXT, alias_chain_json TEXT, evidence_json TEXT, external_target_kind TEXT, external_target_id TEXT, external_target_label TEXT, external_target_dynamic INTEGER NOT NULL DEFAULT 0, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(source_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL, FOREIGN KEY(service_binding_id) REFERENCES service_bindings(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS symbol_calls (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, caller_symbol_id INTEGER NOT NULL, callee_symbol_id INTEGER, callee_expression TEXT NOT NULL, import_source TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, status TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, unresolved_reason TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(caller_symbol_id) REFERENCES symbols(id) ON DELETE CASCADE, FOREIGN KEY(callee_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS graph_edges (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, edge_type TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'unresolved', from_kind TEXT NOT NULL, from_id TEXT NOT NULL, to_kind TEXT NOT NULL, to_id TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, is_dynamic INTEGER NOT NULL, unresolved_reason TEXT, generation INTEGER NOT NULL DEFAULT 0, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
-CREATE TABLE IF NOT EXISTS index_runs (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, started_at TEXT NOT NULL, finished_at TEXT, status TEXT NOT NULL, repo_count INTEGER NOT NULL, file_count INTEGER NOT NULL, diagnostic_count INTEGER NOT NULL, error_message TEXT, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS index_runs (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, started_at TEXT NOT NULL, finished_at TEXT, status TEXT NOT NULL, repo_count INTEGER NOT NULL, file_count INTEGER NOT NULL, diagnostic_count INTEGER NOT NULL, error_message TEXT, owner_pid INTEGER, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS diagnostics (id INTEGER PRIMARY KEY, repo_id INTEGER, file_id INTEGER, severity TEXT NOT NULL, code TEXT NOT NULL, message TEXT NOT NULL, source_file TEXT, source_line INTEGER, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(file_id) REFERENCES files(id) ON DELETE SET NULL);
+`;
+
+export const schemaIndexesSql = `
 CREATE INDEX IF NOT EXISTS idx_repo_name ON repositories(name);
 CREATE INDEX IF NOT EXISTS idx_service_path ON cds_services(service_path);
 CREATE INDEX IF NOT EXISTS idx_extension_import ON cds_services(extension_module_specifier, extension_imported_symbol, is_extend);
@@ -24,3 +27,5 @@ CREATE INDEX IF NOT EXISTS idx_calls_repo ON outbound_calls(repo_id, call_type);
 CREATE INDEX IF NOT EXISTS idx_symbol_calls_caller ON symbol_calls(repo_id, caller_symbol_id);
 CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(kind, name, path, repo);
 `;
+
+export const schemaSql = `${schemaTablesSql}\n${schemaIndexesSql}`;

package/src/indexer/repository-indexer.ts

@@ -7,6 +7,7 @@ import {
   insertCalls,
   insertExecutableSymbols,
   insertHandler,
+  handlerMethodIsExecutable,
   insertRegistrations,
   insertSymbolCalls,
   insertRequires,
@@ -19,14 +20,20 @@ import { parseDecorators } from '../parsers/decorator-parser.js';
 import { parseHandlerRegistrations } from '../parsers/handler-registration-parser.js';
 import { parseOutboundCalls } from '../parsers/outbound-call-parser.js';
 import { parseExecutableSymbols } from '../parsers/symbol-parser.js';
-import { parsePackageJson } from '../parsers/package-json-parser.js';
+import {
+  loadPackageJsonSnapshot,
+} from '../parsers/package-json-parser.js';
 import { parseServiceBindings } from '../parsers/service-binding-parser.js';
-import { sha256File } from '../utils/hashing.js';
 import { normalizePath } from '../utils/path-utils.js';
 import { errorMessage } from '../utils/diagnostics.js';
 import { sha256Text } from '../utils/hashing.js';
 import { ANALYZER_VERSION } from '../version.js';
-import type { CdsServiceFact, HandlerClassFact, HandlerRegistrationFact, OutboundCallFact, ServiceBindingFact, ExecutableSymbolFact, SymbolCallFact } from '../types.js';
+import {
+  loadRepositorySourceContext,
+  type RepositorySourceContext,
+  type SourceContextInstrumentation,
+} from '../parsers/ts-project.js';
+import type { CdsServiceFact, HandlerClassFact, HandlerRegistrationFact, OutboundCallFact, PackageFacts, ServiceBindingFact, ExecutableSymbolFact, SymbolCallFact } from '../types.js';
 export interface IndexRepoResult {
   fileCount: number;
   diagnosticCount: number;
@@ -44,7 +51,7 @@ interface ParsedFacts {
 }
 export interface PreparedRepositoryIndex extends IndexRepoResult {
   repo: RepoRow;
-  packageFacts?: Awaited<ReturnType<typeof parsePackageJson>>;
+  packageFacts?: PackageFacts;
   fingerprint?: string;
   kind?: string;
   parsed?: ParsedFacts;
@@ -53,9 +60,10 @@ export async function indexRepository(
   db: Db,
   repo: RepoRow,
   force: boolean,
+  instrumentation?: SourceContextInstrumentation,
 ): Promise<IndexRepoResult> {
   try {
-    const prepared = await prepareRepositoryIndex(repo, force);
+    const prepared = await prepareRepositoryIndex(repo, force, instrumentation);
     if (!prepared.skipped) db.transaction(() => publishPreparedRepositoryIndex(db, prepared));
     return { fileCount: prepared.fileCount, diagnosticCount: prepared.diagnosticCount, skipped: prepared.skipped };
   } catch (error) {
@@ -63,19 +71,36 @@ export async function indexRepository(
     return { fileCount: 0, diagnosticCount: 1, skipped: false };
   }
 }
-export async function prepareRepositoryIndex(repo: RepoRow, force: boolean): Promise<PreparedRepositoryIndex> {
+export async function prepareRepositoryIndex(
+  repo: RepoRow,
+  force: boolean,
+  instrumentation?: SourceContextInstrumentation,
+): Promise<PreparedRepositoryIndex> {
   const sourceFiles = await findSourceFiles(repo.absolute_path);
-  const packageFacts = await parsePackageJson(repo.absolute_path);
-  const fingerprint = await repositoryFingerprint(repo.absolute_path, sourceFiles, packageFacts);
+  const packageSnapshot = await loadPackageJsonSnapshot(repo.absolute_path, {
+    strict: true,
+    allowMissing: repo.package_name === null,
+  });
+  const packageFacts = packageSnapshot.facts;
+  const sources = await loadRepositorySourceContext(
+    repo.absolute_path, sourceFiles, instrumentation,
+  );
+  const fingerprint = repositoryFingerprint(
+    sources, packageFacts, packageSnapshot.rawText,
+  );
   if (!force && repo.fingerprint === fingerprint) return { repo, fileCount: 0, diagnosticCount: 0, skipped: true };
+  const parsed = await parseAllSourceFacts(repo.absolute_path, sources);
   return {
     repo,
     packageFacts,
     fingerprint,
     kind: await classifyRepository(repo.absolute_path, packageFacts),
-    parsed: await parseAllSourceFacts(repo.absolute_path, sourceFiles),
+    parsed,
     fileCount: sourceFiles.length,
-    diagnosticCount: 0,
+    diagnosticCount: parsed.handlers.filter((handler) =>
+      handler.hasHandlerDecorator
+      && (handler.methods.length === 0
+        || handler.methods.some((method) => !handlerMethodIsExecutable(method)))).length,
     skipped: false,
   };
 }
@@ -104,21 +129,23 @@ export function recordIndexFailure(db: Db, repoId: number, error: unknown): void
   db.prepare("DELETE FROM diagnostics WHERE repo_id=? AND code IN ('index_failed_snapshot_preserved','source_read_failed')").run(repoId);
   db.prepare('INSERT INTO diagnostics(repo_id,severity,code,message) VALUES(?,?,?,?)').run(repoId, 'error', 'source_read_failed', `Index failed before publication; previous facts and fingerprint were preserved. ${message}`);
 }
-async function parseAllSourceFacts(root: string, files: string[]): Promise<ParsedFacts> {
+async function parseAllSourceFacts(
+  root: string,
+  sources: RepositorySourceContext,
+): Promise<ParsedFacts> {
   const facts: ParsedFacts = { services: [], handlers: [], registrations: [], bindings: [], calls: [], symbols: [], symbolCalls: [], fileRecords: [] };
-  for (const file of files) {
-    const abs = path.join(root, file);
-    const stat = await fs.stat(abs);
-    facts.fileRecords.push({ relativePath: normalizePath(file), extension: path.extname(file), sha256: await sha256File(abs), sizeBytes: stat.size });
-    if (file.endsWith('.cds')) facts.services.push(...(await parseCdsFile(root, file)));
+  for (const snapshot of sources.entries()) {
+    const file = snapshot.filePath;
+    facts.fileRecords.push({ relativePath: normalizePath(file), extension: path.extname(file), sha256: sha256Text(snapshot.text), sizeBytes: snapshot.sizeBytes });
+    if (file.endsWith('.cds')) facts.services.push(...(await parseCdsFile(root, file, sources)));
     if (/\.[jt]s$/.test(file)) {
-      facts.handlers.push(...(await parseDecorators(root, file)));
-      facts.registrations.push(...(await parseHandlerRegistrations(root, file)));
-      facts.bindings.push(...(await parseServiceBindings(root, file)));
-      const symbolFacts = await parseExecutableSymbols(root, file);
+      facts.handlers.push(...(await parseDecorators(root, file, sources)));
+      facts.registrations.push(...(await parseHandlerRegistrations(root, file, sources)));
+      facts.bindings.push(...(await parseServiceBindings(root, file, sources)));
+      const symbolFacts = await parseExecutableSymbols(root, file, sources);
       facts.symbols.push(...symbolFacts.symbols);
       facts.symbolCalls.push(...symbolFacts.calls);
-      facts.calls.push(...(await parseOutboundCalls(root, file)));
+      facts.calls.push(...(await parseOutboundCalls(root, file, sources)));
     }
   }
   return facts;
@@ -126,7 +153,7 @@ async function parseAllSourceFacts(root: string, files: string[]): Promise<Parse
 async function findSourceFiles(root: string): Promise<string[]> {
   const out: string[] = [];
   async function walk(dir: string, prefix = ''): Promise<void> {
-    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const e of entries) {
       const rel = prefix ? `${prefix}/${e.name}` : e.name;
       if (e.isDirectory()) {
@@ -142,8 +169,11 @@ function isDefaultTestFile(relativeFile: string): boolean {
   if (parts.some((part) => ['test', 'tests', '__tests__'].includes(part))) return true;
   return /\.(test|spec)\.[jt]s$/.test(parts.at(-1) ?? '');
 }
-async function repositoryFingerprint(root: string, files: string[], facts: Awaited<ReturnType<typeof parsePackageJson>>): Promise<string> {
-  const packageJson = await fs.readFile(path.join(root, 'package.json'), 'utf8').catch(() => '');
+function repositoryFingerprint(
+  sources: RepositorySourceContext,
+  facts: PackageFacts,
+  packageJsonText: string,
+): string {
   const normalizedFacts = {
     analyzerVersion: ANALYZER_VERSION,
     packageName: facts.packageName,
@@ -152,12 +182,10 @@ async function repositoryFingerprint(root: string, files: string[], facts: Await
     cdsRequires: [...facts.cdsRequires].sort((a, b) => a.alias.localeCompare(b.alias)),
     scripts: Object.fromEntries(Object.entries(facts.scripts).sort()),
     includeTests: false,
-    packageJsonHash: sha256Text(packageJson),
+    packageJsonHash: sha256Text(packageJsonText),
   };
   const entries: string[] = [`facts:${JSON.stringify(normalizedFacts)}`];
-  for (const file of files) {
-    const content = await fs.readFile(path.join(root, file), 'utf8');
-    entries.push(`${file}:${sha256Text(content)}`);
-  }
+  for (const snapshot of sources.entries())
+    entries.push(`${snapshot.filePath}:${sha256Text(snapshot.text)}`);
   return sha256Text(entries.join('\n'));
 }

package/src/indexer/workspace-indexer.ts

@@ -1,16 +1,94 @@
 import type { Db } from '../db/connection.js';
-import { listRepositories, repoByName } from '../db/repositories.js';
+import { listRepositories, reposByName } from '../db/repositories.js';
 import { errorMessage } from '../utils/diagnostics.js';
 import { prepareRepositoryIndex, publishPreparedRepositoryIndex, recordIndexFailure, type PreparedRepositoryIndex } from './repository-indexer.js';
 import { materializeCdsExtensionOperations } from './cds-extension-resolver.js';
+// Ownerless rows predate PID coordination; this matches doctor's stale-run threshold without taking over a recent legacy writer.
+const LEGACY_OWNER_RECOVERY_MS = 60 * 60 * 1_000;
+type RunningIndexRow = Record<string, unknown>;
+function ownerPid(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+    ? value
+    : undefined;
+}
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // Only ESRCH proves that ownership ended; permission and platform errors must fail closed.
+    const ownerIsMissing = typeof error === 'object'
+      && error !== null
+      && 'code' in error
+      && error.code === 'ESRCH';
+    return !ownerIsMissing;
+  }
+}
+function isRecoverableRun(row: RunningIndexRow, now: number): boolean {
+  const pid = ownerPid(row.ownerPid);
+  if (pid !== undefined) return !processIsAlive(pid);
+  if (typeof row.startedAt !== 'string') return false;
+  const startedAt = Date.parse(row.startedAt);
+  return Number.isFinite(startedAt) && now - startedAt >= LEGACY_OWNER_RECOVERY_MS;
+}
+function recoveredOwnerMessage(row: RunningIndexRow): string {
+  const pid = ownerPid(row.ownerPid);
+  return pid === undefined
+    ? 'Recovered stale legacy index writer without owner process metadata.'
+    : `Recovered stale index writer because owner process ${pid} is no longer running.`;
+}
+export function claimIndexRun(
+  db: Db,
+  workspaceId: number,
+  repoCount: number,
+): number {
+  // The short write transaction serializes claims without holding a SQLite writer lock during source preparation.
+  try {
+    return db.transaction(() => {
+      const now = Date.now();
+      const rows = db
+        .prepare("SELECT id,workspace_id workspaceId,owner_pid ownerPid,started_at startedAt FROM index_runs WHERE status='running' ORDER BY id")
+        .all();
+      const active = rows.find((row) => !isRecoverableRun(row, now));
+      if (active) {
+        const pid = ownerPid(active.ownerPid);
+        const owner = pid === undefined ? 'an unknown owner' : `process ${pid}`;
+        throw new Error(`index_writer_active: this database is already being indexed for workspace ${String(active.workspaceId ?? 'unknown')} by ${owner}; wait for that writer to finish.`);
+      }
+      const finish = db.prepare(
+        "UPDATE index_runs SET finished_at=?,status='failed',error_message=? WHERE id=?",
+      );
+      for (const row of rows)
+        finish.run(new Date(now).toISOString(), recoveredOwnerMessage(row), row.id);
+      const inserted = db
+        .prepare('INSERT INTO index_runs(workspace_id,started_at,status,repo_count,file_count,diagnostic_count,owner_pid) VALUES(?,?,?,?,?,?,?) RETURNING id')
+        .get(workspaceId, new Date(now).toISOString(), 'running', repoCount, 0, 0, process.pid);
+      const runId = Number(inserted?.id);
+      if (!Number.isSafeInteger(runId)) throw new Error('index_writer_claim_failed: SQLite did not return an index run identifier.');
+      return runId;
+    });
+  } catch (error) {
+    if (/\b(?:locked|busy)\b/i.test(errorMessage(error)))
+      throw new Error(
+        'index_writer_coordination_failed: SQLite remained busy beyond the bounded writer-claim interval; wait for the active publication to finish.',
+        { cause: error },
+      );
+    throw error;
+  }
+}
 export async function indexWorkspace(
   db: Db,
   workspaceId: number,
   options: { repo?: string; force: boolean; injectDerivedMaterializationFailure?: boolean },
 ): Promise<{ repoCount: number; indexedCount: number; skippedCount: number; fileCount: number; diagnosticCount: number }> {
-  const started = new Date().toISOString();
-  const repos = options.repo ? [repoByName(db, options.repo)].filter((r) => r !== undefined) : listRepositories(db);
-  const runId = Number(db.prepare('INSERT INTO index_runs(workspace_id,started_at,status,repo_count,file_count,diagnostic_count) VALUES(?,?,?,?,?,?) RETURNING id').get(workspaceId, started, 'running', repos.length, 0, 0)?.id);
+  const repos = options.repo
+    ? reposByName(db, options.repo, workspaceId)
+    : listRepositories(db, workspaceId);
+  if (options.repo && repos.length === 0)
+    throw new Error(`selector_repo_not_found: no indexed repository matched ${options.repo}.`);
+  if (options.repo && repos.length > 1)
+    throw new Error(`selector_repo_ambiguous: repository selector ${options.repo} matched ${repos.length} repositories; use a unique repository name.`);
+  const runId = claimIndexRun(db, workspaceId, repos.length);
   let fileCount = 0;
   let diagnosticCount = 0;
   let skippedCount = 0;
@@ -32,12 +110,12 @@ export async function indexWorkspace(
       }
       if (options.injectDerivedMaterializationFailure) throw new Error('Injected derived materialization failure');
       materializeCdsExtensionOperations(db, workspaceId);
-      db.prepare('UPDATE index_runs SET finished_at=?, status=?, file_count=?, diagnostic_count=? WHERE id=?').run(new Date().toISOString(), diagnosticCount ? 'failed' : 'success', fileCount, diagnosticCount, runId);
+      db.prepare("UPDATE index_runs SET finished_at=?, status='success', file_count=?, diagnostic_count=? WHERE id=?").run(new Date().toISOString(), fileCount, diagnosticCount, runId);
     });
     return { repoCount: repos.length, indexedCount: repos.length - skippedCount, skippedCount, fileCount, diagnosticCount };
   } catch (error) {
-    if (activeRepoId && preparedRows.length < repos.length) recordIndexFailure(db, activeRepoId, error);
     db.prepare("UPDATE index_runs SET finished_at=?, status='failed', file_count=?, diagnostic_count=?, error_message=? WHERE id=?").run(new Date().toISOString(), fileCount, diagnosticCount + 1, errorMessage(error), runId);
+    if (activeRepoId && preparedRows.length < repos.length) recordIndexFailure(db, activeRepoId, error);
     throw error;
   }
 }