@saptools/service-flow 0.1.51 → 0.1.52

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import ts from 'typescript';
+
 type CallType = 'remote_action' | 'remote_query' | 'remote_entity_read' | 'remote_entity_mutation' | 'remote_entity_delete' | 'remote_entity_media' | 'remote_entity_candidate' | 'local_db_query' | 'external_http' | 'async_emit' | 'async_subscribe' | 'local_service_call' | 'unknown';
 interface DiscoveredRepository {
     name: string;
@@ -55,17 +57,36 @@ interface HandlerClassFact {
     sourceFile: string;
     sourceLine: number;
     methods: HandlerMethodFact[];
+    hasHandlerDecorator?: boolean;
+    classDecoratorNames?: string[];
+    observedDecoratorNames?: string[];
+    unsupportedDecoratorNames?: string[];
 }
+type HandlerMethodKind = 'operation' | 'entity_lifecycle' | 'event' | 'unsupported_lifecycle' | 'unsupported_decorator';
+type HandlerLifecyclePhase = 'on' | 'before' | 'after';
+type HandlerLifecycleEvent = 'CREATE' | 'READ' | 'UPDATE' | 'DELETE';
 interface HandlerMethodFact {
     methodName: string;
     decoratorKind: string;
     decoratorValue?: string;
     decoratorRawExpression: string;
+    handlerKind?: HandlerMethodKind;
+    executable?: boolean;
+    lifecyclePhase?: HandlerLifecyclePhase;
+    lifecycleEvent?: HandlerLifecycleEvent;
     decoratorResolution: {
         rawExpression: string;
+        decoratorExpression?: string;
+        argumentExpression?: string;
+        resolvedDecoratorKind?: string;
+        decoratorImportSource?: string;
         resolvedValue?: string;
-        resolutionKind: 'literal' | 'const_identifier' | 'enum_member' | 'const_object_property' | 'generated_constant_name' | 'unresolved';
+        resolutionKind: 'literal' | 'const_identifier' | 'enum_member' | 'const_object_property' | 'generated_constant_name' | 'lifecycle_implicit' | 'unresolved';
         unresolvedReason?: string;
+        handlerKind?: HandlerMethodKind;
+        executable?: boolean;
+        lifecyclePhase?: HandlerLifecyclePhase;
+        lifecycleEvent?: HandlerLifecycleEvent;
     };
     sourceFile: string;
     sourceLine: number;
@@ -138,6 +159,7 @@ interface ImplementationHint {
 type DynamicMode = 'strict' | 'candidates' | 'infer';
 interface TraceOptions {
     depth: number;
+    workspaceId?: number;
     vars?: Record<string, string>;
     includeExternal?: boolean;
     includeDb?: boolean;
@@ -165,17 +187,33 @@ interface TraceResult {
 
 declare function discoverRepositories(rootPath: string, ignore: readonly string[]): Promise<DiscoveredRepository[]>;
 
-declare function parsePackageJson(repoPath: string): Promise<PackageFacts>;
+interface ParsePackageJsonOptions {
+    strict?: boolean;
+    allowMissing?: boolean;
+}
+declare function parsePackageJson(repoPath: string, options?: ParsePackageJsonOptions): Promise<PackageFacts>;
+
+interface SourceFileSnapshot {
+    repoPath: string;
+    filePath: string;
+    text: string;
+    sizeBytes: number;
+    sourceFile: () => ts.SourceFile;
+}
+interface RepositorySourceContext {
+    get: (filePath: string) => SourceFileSnapshot | undefined;
+    entries: () => SourceFileSnapshot[];
+}
 
-declare function parseCdsFile(repoPath: string, filePath: string): Promise<CdsServiceFact[]>;
+declare function parseCdsFile(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<CdsServiceFact[]>;
 
-declare function parseDecorators(repoPath: string, filePath: string): Promise<HandlerClassFact[]>;
+declare function parseDecorators(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<HandlerClassFact[]>;
 
-declare function parseHandlerRegistrations(repoPath: string, filePath: string): Promise<HandlerRegistrationFact[]>;
+declare function parseHandlerRegistrations(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<HandlerRegistrationFact[]>;
 
-declare function parseServiceBindings(repoPath: string, filePath: string): Promise<ServiceBindingFact[]>;
+declare function parseServiceBindings(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<ServiceBindingFact[]>;
 
-declare function parseOutboundCalls(repoPath: string, filePath: string): Promise<OutboundCallFact[]>;
+declare function parseOutboundCalls(repoPath: string, filePath: string, context?: RepositorySourceContext): Promise<OutboundCallFact[]>;
 
 declare function parseGeneratedConstants(repoPath: string, filePath: string): Promise<GeneratedConstantFact[]>;
 

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-YZJKE5UX.js";
+} from "./chunk-PTLDSHRC.js";
 
 // src/parsers/generated-constants-parser.ts
 import fs from "fs/promises";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saptools/service-flow",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/000-clean.ts

@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { WorkspaceConfig } from '../config/workspace-config.js';
+import { openDatabase } from '../db/connection.js';
+import { getWorkspace, upsertWorkspace } from '../db/repositories.js';
+import { claimIndexRun } from '../indexer/workspace-indexer.js';
+import { errorMessage } from '../utils/diagnostics.js';
+
+type CleanConfig = Pick<WorkspaceConfig, 'dbPath' | 'rootPath'>;
+
+export async function cleanWorkspaceState(
+  config: CleanConfig,
+  dbOnly: boolean,
+): Promise<void> {
+  const dbDir = path.resolve(path.dirname(config.dbPath));
+  if (!dbOnly) await assertOwnedStateDirectory(dbDir, config.rootPath);
+  const runId = claimCleanWriter(config);
+  try {
+    if (dbOnly) await removeDatabaseFiles(config.dbPath);
+    else await fs.rm(dbDir, { recursive: true, force: true });
+  } catch (error) {
+    await markCleanClaimFailed(config.dbPath, runId, error);
+    throw error;
+  }
+}
+
+function claimCleanWriter(config: CleanConfig): number {
+  const db = openDatabase(config.dbPath);
+  try {
+    const workspaceId = getWorkspace(db, config.rootPath)?.id
+      ?? upsertWorkspace(db, config.rootPath, config.dbPath);
+    return claimIndexRun(db, workspaceId, 0);
+  } finally {
+    db.close();
+  }
+}
+
+async function assertOwnedStateDirectory(
+  dbDir: string,
+  rootPath: string,
+): Promise<void> {
+  const marker = path.join(dbDir, '.service-flow-state');
+  const dangerous = new Set([
+    path.parse(dbDir).root,
+    '/tmp',
+    process.env.HOME ? path.resolve(process.env.HOME) : '',
+    path.resolve(rootPath),
+  ]);
+  const ownsState = await fs.stat(marker)
+    .then((stat) => stat.isFile())
+    .catch(() => false);
+  if (!ownsState || dangerous.has(dbDir))
+    throw new Error(
+      `Refusing to recursively delete unowned or dangerous state directory: ${dbDir}. Use --db-only to remove only the database file.`,
+    );
+}
+
+async function removeDatabaseFiles(dbPath: string): Promise<void> {
+  for (const suffix of ['-wal', '-shm', '-journal'])
+    await fs.rm(`${dbPath}${suffix}`, { force: true });
+  await fs.rm(dbPath, { force: true });
+}
+
+async function markCleanClaimFailed(
+  dbPath: string,
+  runId: number,
+  error: unknown,
+): Promise<void> {
+  const exists = await fs.stat(dbPath).then(() => true).catch(() => false);
+  if (!exists) return;
+  const db = openDatabase(dbPath);
+  try {
+    db.prepare(`UPDATE index_runs SET finished_at=?,status='failed',
+      error_message=? WHERE id=? AND status='running'`).run(
+      new Date().toISOString(),
+      `Clean failed after writer claim: ${errorMessage(error)}`,
+      runId,
+    );
+  } finally {
+    db.close();
+  }
+}

package/src/cli.ts

@@ -1,17 +1,16 @@
 import { Command } from 'commander';
-import path from 'node:path';
-import fs from 'node:fs/promises';
 import { DEFAULT_IGNORES } from './config/defaults.js';
 import {
   createWorkspaceConfig,
   loadWorkspaceConfig,
   saveWorkspaceConfig,
 } from './config/workspace-config.js';
-import { openDatabase, openReadOnlyDatabase } from './db/connection.js';
+import { openDatabase, openReadOnlyDatabase, type Db } from './db/connection.js';
 import {
   getWorkspace,
   listRepositories,
-  repoByName,
+  reposByName,
+  type RepoRow,
   upsertRepository,
   upsertWorkspace,
 } from './db/repositories.js';
@@ -22,7 +21,10 @@ import { indexWorkspace } from './indexer/workspace-indexer.js';
 import { linkWorkspace } from './linker/cross-repo-linker.js';
 import { doctorDiagnostics, linkUpgradeWarnings } from './cli/doctor.js';
 import { trace } from './trace/trace-engine.js';
-import { parseVars } from './trace/selectors.js';
+import {
+  parseVars,
+  selectorRepoAmbiguousDiagnostic,
+} from './trace/selectors.js';
 import { parseImplementationHint } from './trace/implementation-hints.js';
 import { renderTraceTable } from './output/table-output.js';
 import { renderTraceJson, renderJson } from './output/json-output.js';
@@ -30,6 +32,7 @@ import { renderDoctorDiagnostics } from './output/doctor-output.js';
 import { renderMermaid } from './output/mermaid-output.js';
 import { VERSION } from './version.js';
 import type { DynamicMode } from './types.js';
+import { cleanWorkspaceState } from './cli/000-clean.js';
 async function init(
   workspace: string,
   options: { db?: string; ignore?: string[] },
@@ -92,6 +95,30 @@ async function withReadOnlyWorkspace<T>(
     db.close();
   }
 }
+function selectRepository(db: Db, selector: string, workspaceId?: number): {
+  repo?: RepoRow;
+  diagnostic?: Record<string, unknown>;
+} {
+  const candidates = reposByName(db, selector, workspaceId);
+  if (candidates.length === 1) return { repo: candidates[0] };
+  if (candidates.length === 0) return {
+    diagnostic: {
+      severity: 'warning',
+      code: 'selector_repo_not_found',
+      message: `Repository selector not found: ${selector}`,
+    },
+  };
+  return {
+    diagnostic: selectorRepoAmbiguousDiagnostic(
+      selector,
+      candidates.map((repo) => ({
+        id: repo.id,
+        name: repo.name,
+        packageName: repo.package_name ?? undefined,
+      })),
+    ),
+  };
+}
 export function createProgram(): Command {
   const program = new Command();
   program
@@ -177,7 +204,7 @@ export function createProgram(): Command {
         dynamicMode: string;
         maxDynamicCandidates: string;
       }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
           const result = trace(
             db,
             {
@@ -189,6 +216,7 @@ export function createProgram(): Command {
             },
             {
               depth: Number(opts.depth),
+              workspaceId,
               vars: parseVars(opts.var),
               includeExternal: Boolean(opts.includeExternal),
               includeDb: Boolean(opts.includeDb),
@@ -214,10 +242,10 @@ export function createProgram(): Command {
     .option('--workspace <path>')
     .action(
       (opts: { workspace?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) =>
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) =>
           process.stdout.write(
             renderJson(
-              listRepositories(db).map((r) => ({
+              listRepositories(db, workspaceId).map((r) => ({
                 name: r.name,
                 kind: r.kind,
                 packageName: r.package_name,
@@ -232,17 +260,20 @@ export function createProgram(): Command {
     .option('--repo <name>')
     .action(
       (opts: { workspace?: string; repo?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
-          const repo = opts.repo ? repoByName(db, opts.repo) : undefined;
-          if (opts.repo && !repo) {
-            process.stdout.write(renderJson([{ severity: 'warning', code: 'selector_repo_not_found', message: `Repository selector not found: ${opts.repo}` }]));
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+          const selection = opts.repo
+            ? selectRepository(db, opts.repo, workspaceId)
+            : {};
+          if (selection.diagnostic) {
+            process.stdout.write(renderJson([selection.diagnostic]));
             return;
           }
+          const repo = selection.repo;
           const rows = db
             .prepare(
-              'SELECT r.name repo,s.service_path servicePath,s.qualified_name qualifiedName FROM cds_services s JOIN repositories r ON r.id=s.repo_id WHERE (? IS NULL OR s.repo_id=?) ORDER BY r.name,s.service_path',
+              'SELECT r.name repo,s.service_path servicePath,s.qualified_name qualifiedName FROM cds_services s JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=? AND (? IS NULL OR s.repo_id=?) ORDER BY r.name,s.service_path',
             )
-            .all(repo?.id, repo?.id);
+            .all(workspaceId, repo?.id, repo?.id);
           process.stdout.write(renderJson(rows));
         }).catch(fail),
     );
@@ -253,17 +284,20 @@ export function createProgram(): Command {
     .option('--service <path>')
     .action(
       (opts: { workspace?: string; repo?: string; service?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
-          const repo = opts.repo ? repoByName(db, opts.repo) : undefined;
-          if (opts.repo && !repo) {
-            process.stdout.write(renderJson([{ severity: 'warning', code: 'selector_repo_not_found', message: `Repository selector not found: ${opts.repo}` }]));
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+          const selection = opts.repo
+            ? selectRepository(db, opts.repo, workspaceId)
+            : {};
+          if (selection.diagnostic) {
+            process.stdout.write(renderJson([selection.diagnostic]));
             return;
           }
+          const repo = selection.repo;
           const rows = db
             .prepare(
-              'SELECT r.name repo,s.service_path servicePath,o.operation_name operation,o.operation_path path FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE (? IS NULL OR s.repo_id=?) AND (? IS NULL OR s.service_path=?)',
+              'SELECT r.name repo,s.service_path servicePath,o.operation_name operation,o.operation_path path FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=? AND (? IS NULL OR s.repo_id=?) AND (? IS NULL OR s.service_path=?)',
             )
-            .all(repo?.id, repo?.id, opts.service, opts.service);
+            .all(workspaceId, repo?.id, repo?.id, opts.service, opts.service);
           process.stdout.write(renderJson(rows));
         }).catch(fail),
     );
@@ -274,17 +308,21 @@ export function createProgram(): Command {
     .option('--operation <name>')
     .action(
       (opts: { workspace?: string; repo?: string; operation?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
-          const repo = opts.repo ? repoByName(db, opts.repo) : undefined;
-          if (opts.repo && !repo) {
-            process.stdout.write(renderJson([{ severity: 'warning', code: 'selector_repo_not_found', message: `Repository selector not found: ${opts.repo}` }]));
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+          const selection = opts.repo
+            ? selectRepository(db, opts.repo, workspaceId)
+            : {};
+          if (selection.diagnostic) {
+            process.stdout.write(renderJson([selection.diagnostic]));
             return;
           }
+          const repo = selection.repo;
           const rows = db
             .prepare(
-              'SELECT r.name repo,c.call_type type,c.operation_path_expr path,c.source_file file,c.source_line line FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE (? IS NULL OR c.repo_id=?) AND (? IS NULL OR c.operation_path_expr=? OR c.operation_path_expr=? OR c.payload_summary LIKE ?)',
+              'SELECT r.name repo,c.call_type type,c.operation_path_expr path,c.source_file file,c.source_line line FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id WHERE r.workspace_id=? AND (? IS NULL OR c.repo_id=?) AND (? IS NULL OR c.operation_path_expr=? OR c.operation_path_expr=? OR c.payload_summary LIKE ?)',
             )
             .all(
+              workspaceId,
               repo?.id,
               repo?.id,
               opts.operation,
@@ -322,7 +360,7 @@ export function createProgram(): Command {
         dynamicMode: string;
         maxDynamicCandidates: string;
       }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
           const result = trace(
             db,
             {
@@ -333,6 +371,7 @@ export function createProgram(): Command {
             },
             {
               depth: 100,
+              workspaceId,
               includeAsync: true,
               includeDb: true,
               includeExternal: true,
@@ -357,11 +396,12 @@ export function createProgram(): Command {
     .option('--workspace <path>')
     .action(
       (name: string, opts: { workspace?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) =>
-          process.stdout.write(
-            renderJson(repoByName(db, name) ?? { error: 'repo not found' }),
-          ),
-        ).catch(fail),
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
+          const selection = selectRepository(db, name, workspaceId);
+          process.stdout.write(renderJson(
+            selection.repo ?? selection.diagnostic ?? { error: 'repo not found' },
+          ));
+        }).catch(fail),
     );
   inspect
     .command('operation')
@@ -369,12 +409,12 @@ export function createProgram(): Command {
     .option('--workspace <path>')
     .action(
       (selector: string, opts: { workspace?: string }) =>
-        void withReadOnlyWorkspace(opts.workspace, (db) => {
+        void withReadOnlyWorkspace(opts.workspace, (db, workspaceId) => {
           const rows = db
             .prepare(
-              'SELECT * FROM cds_operations WHERE operation_name=? OR operation_path=?',
+              'SELECT o.* FROM cds_operations o JOIN cds_services s ON s.id=o.service_id JOIN repositories r ON r.id=s.repo_id WHERE r.workspace_id=? AND (o.operation_name=? OR o.operation_path=?)',
             )
-            .all(selector, selector);
+            .all(workspaceId, selector, selector);
           process.stdout.write(renderJson(rows));
         }).catch(fail),
     );
@@ -399,29 +439,7 @@ export function createProgram(): Command {
       (opts: { workspace?: string; dbOnly?: boolean }) =>
         void (async () => {
           const config = await loadWorkspaceConfig(opts.workspace);
-          const dbDir = path.resolve(path.dirname(config.dbPath));
-          const workspaceRoot = path.resolve(config.rootPath);
-          await fs.rm(config.dbPath, { force: true });
-          if (!opts.dbOnly) {
-            const marker = path.join(dbDir, '.service-flow-state');
-            const dangerous = new Set([
-              path.parse(dbDir).root,
-              '/tmp',
-              process.env.HOME ? path.resolve(process.env.HOME) : '',
-              workspaceRoot,
-            ]);
-            let ownsState: boolean;
-            try {
-              ownsState = (await fs.stat(marker)).isFile();
-            } catch {
-              ownsState = false;
-            }
-            if (!ownsState || dangerous.has(dbDir))
-              throw new Error(
-                `Refusing to recursively delete unowned or dangerous state directory: ${dbDir}. Use --db-only to remove only the database file.`,
-              );
-            await fs.rm(dbDir, { recursive: true, force: true });
-          }
+          await cleanWorkspaceState(config, Boolean(opts.dbOnly));
           process.stdout.write('Cleaned service-flow state\n');
         })().catch(fail),
     );

package/src/db/connection.ts

@@ -101,8 +101,8 @@ export function openDatabase(dbPath: string, options: OpenDatabaseOptions = {}):
     },
     transaction<T>(fn: () => T): T {
       if (inTransaction) return fn();
-      inTransaction = true;
       native.exec('BEGIN IMMEDIATE');
+      inTransaction = true;
       try {
         const result = fn();
         native.exec('COMMIT');

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

@@ -3,6 +3,7 @@ import type {
   CdsRequire,
   CdsServiceFact,
   HandlerClassFact,
+  HandlerMethodFact,
   HandlerRegistrationFact,
   OutboundCallFact,
   ServiceBindingFact,
@@ -85,15 +86,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 +203,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 +221,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,