@saptools/service-flow 0.1.49 → 0.1.51

package/dist/index.d.ts

@@ -61,6 +61,12 @@ interface HandlerMethodFact {
     decoratorKind: string;
     decoratorValue?: string;
     decoratorRawExpression: string;
+    decoratorResolution: {
+        rawExpression: string;
+        resolvedValue?: string;
+        resolutionKind: 'literal' | 'const_identifier' | 'enum_member' | 'const_object_property' | 'generated_constant_name' | 'unresolved';
+        unresolvedReason?: string;
+    };
     sourceFile: string;
     sourceLine: number;
 }
@@ -129,6 +135,18 @@ interface ImplementationHint {
     candidateFamily?: string;
     implementationRepo: string;
 }
+type DynamicMode = 'strict' | 'candidates' | 'infer';
+interface TraceOptions {
+    depth: number;
+    vars?: Record<string, string>;
+    includeExternal?: boolean;
+    includeDb?: boolean;
+    includeAsync?: boolean;
+    implementationRepo?: string;
+    implementationHints?: ImplementationHint[];
+    dynamicMode?: DynamicMode;
+    maxDynamicCandidates?: number;
+}
 interface TraceEdge {
     step: number;
     type: string;
@@ -207,19 +225,11 @@ declare function applyVariables(template: string | undefined, vars: Record<strin
 declare function extractPlaceholders(template: string | undefined): string[];
 declare function substituteVariables(template: string | undefined, vars: Record<string, string>): RuntimeSubstitution;
 
-declare function trace(db: Db, start: TraceStart, options: {
-    depth: number;
-    vars?: Record<string, string>;
-    includeExternal?: boolean;
-    includeDb?: boolean;
-    includeAsync?: boolean;
-    implementationRepo?: string;
-    implementationHints?: ImplementationHint[];
-}): TraceResult;
+declare function trace(db: Db, start: TraceStart, options: TraceOptions): TraceResult;
 
 declare function parseImplementationHint(value: string): ImplementationHint;
 
 declare function redactText(text: string): string;
 declare function redactValue(value: unknown): unknown;
 
-export { type ImplementationHint, type RuntimeSubstitution, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };
+export { type DynamicMode, type ImplementationHint, type RuntimeSubstitution, type TraceOptions, applyVariables, discoverRepositories, extractPlaceholders, linkWorkspace, parseCdsFile, parseDecorators, parseGeneratedConstants, parseHandlerRegistrations, parseImplementationHint, parseOutboundCalls, parsePackageJson, parseServiceBindings, redactText, redactValue, substituteVariables, trace };

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-XOROZHW4.js";
+} from "./chunk-YZJKE5UX.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.49",
+  "version": "0.1.51",
   "description": "Trace SAP CAP service-to-service flows across multi-repository workspaces with runtime-aware graph resolution",
   "type": "module",
   "publishConfig": {

package/src/cli/doctor.ts

@@ -150,6 +150,8 @@ function parserQualityDiagnostics(db: Db, strict: boolean, options: DoctorOption
     classInstanceNoiseQuality(db),
     contextualBindingPropagationQuality(db),
     serviceBindingQuality(db, Boolean(options.detail)),
+    decoratorResolutionQuality(db),
+    handlerRegistrationPairingQuality(db),
     nestedThisReceiverQuality(db),
     wrapperPathPropagationQuality(db),
     remoteQueryTargetQuality(db),
@@ -249,9 +251,18 @@ function addImplementationCategory(grouped: Map<string, Diagnostic & { count: nu
   const key = [category, baseOperation, reason, family].join('\0');
   const current = grouped.get(key) ?? { category, baseOperation, reason, candidateFamily: family, count: 0, servicePaths: [], examples: [] };
   const hintSuggestions = implementationSuggestions(evidence);
+  const candidates = asRecords(evidence.candidates);
   current.count += 1;
   current.servicePaths.push(String(row.servicePath ?? evidence.servicePath ?? ''));
-  current.examples.push({ servicePath: row.servicePath, operation: row.operationName, status: row.status, reason: row.unresolvedReason, implementationHintSuggestions: hintSuggestions });
+  current.examples.push({
+    servicePath: row.servicePath,
+    operation: row.operationName,
+    status: row.status,
+    reason: row.unresolvedReason,
+    candidateCount: candidates.length,
+    candidateEvidence: candidates.slice(0, 3),
+    implementationHintSuggestions: hintSuggestions,
+  });
   grouped.set(key, current);
 }
 
@@ -452,6 +463,53 @@ function bindingCategoryAction(category: string): string {
   return 'Add a direct CAP client binding or statically provable helper-return binding.';
 }
 
+function decoratorResolutionQuality(db: Db): Diagnostic {
+  const aggregate = db.prepare(`SELECT
+      SUM(CASE WHEN json_extract(decorator_resolution_json,'$.resolutionKind')
+        IN ('const_identifier','enum_member','const_object_property','generated_constant_name') THEN 1 ELSE 0 END) resolvedFromConstants,
+      SUM(CASE WHEN json_extract(decorator_resolution_json,'$.resolutionKind')
+        ='unresolved' THEN 1 ELSE 0 END) unresolvedExpressions
+    FROM handler_methods`).get() as Diagnostic;
+  const unresolved = Number(aggregate.unresolvedExpressions ?? 0);
+  const examples = db.prepare(`SELECT hm.method_name methodName,
+      hm.decorator_raw_expression rawExpression,
+      json_extract(hm.decorator_resolution_json,'$.unresolvedReason') unresolvedReason,
+      hm.source_file sourceFile,hm.source_line sourceLine
+    FROM handler_methods hm
+    WHERE json_extract(hm.decorator_resolution_json,'$.resolutionKind')='unresolved'
+    ORDER BY hm.source_file,hm.source_line LIMIT 5`).all() as Diagnostic[];
+  return {
+    severity: unresolved > 0 ? 'warning' : 'info',
+    code: 'strict_decorator_resolution_quality',
+    message: 'Handler decorator string-resolution aggregate',
+    resolvedFromConstants: Number(aggregate.resolvedFromConstants ?? 0),
+    unresolvedExpressions: unresolved,
+    unresolvedExamples: examples,
+  };
+}
+
+function handlerRegistrationPairingQuality(db: Db): Diagnostic {
+  const mismatch = db.prepare(`SELECT COUNT(*) count
+    FROM handler_registrations hr
+    JOIN handler_classes hc ON hc.id=hr.handler_class_id
+    WHERE hr.handler_class_id IS NOT NULL
+      AND (hc.repo_id<>hr.repo_id OR hc.class_name<>hr.class_name)`).get() as Diagnostic;
+  const prevented = db.prepare(`SELECT COUNT(*) count
+    FROM handler_registrations hr
+    JOIN handler_classes exactClass ON exactClass.id=hr.handler_class_id
+    JOIN handler_classes otherClass ON otherClass.class_name=hr.class_name
+      AND otherClass.repo_id<>hr.repo_id
+    WHERE hr.handler_class_id IS NOT NULL AND hr.import_source IS NOT NULL`).get() as Diagnostic;
+  const mismatched = Number(mismatch.count ?? 0);
+  return {
+    severity: mismatched > 0 ? 'error' : 'info',
+    code: 'strict_handler_registration_pairing_quality',
+    message: 'Handler registration and class ownership aggregate',
+    mismatchedExactRegistrations: mismatched,
+    preventedSyntheticCrossRepositoryPairs: Number(prevented.count ?? 0),
+  };
+}
+
 function wrapperPathPropagationQuality(db: Db): Diagnostic {
   const examples = db.prepare("SELECT source_file sourceFile,source_line sourceLine,json_extract(evidence_json,'$.receiver') receiverName,json_extract(evidence_json,'$.operationPathExpression') pathIdentifier FROM outbound_calls WHERE call_type='remote_action' AND unresolved_reason='dynamic_operation_path_identifier' ORDER BY source_file,source_line LIMIT 5").all() as Diagnostic[];
   return { severity: examples.length > 0 ? 'warning' : 'info', code: 'strict_wrapper_path_propagation_quality', message: 'Dynamic path sends where send({ path }) used a path identifier', dynamicPathIdentifierCalls: examples.length, examples };

package/src/cli.ts

@@ -29,6 +29,7 @@ import { renderTraceJson, renderJson } from './output/json-output.js';
 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';
 async function init(
   workspace: string,
   options: { db?: string; ignore?: string[] },
@@ -155,6 +156,8 @@ export function createProgram(): Command {
     .option('--implementation-repo <name>')
     .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
+    .option('--dynamic-mode <mode>', 'strict|candidates|infer', 'strict')
+    .option('--max-dynamic-candidates <n>', 'maximum dynamic candidates to show', '5')
     .action(
       (opts: {
         workspace?: string;
@@ -171,6 +174,8 @@ export function createProgram(): Command {
         implementationRepo?: string;
         implementationHint: string[];
         var: string[];
+        dynamicMode: string;
+        maxDynamicCandidates: string;
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
           const result = trace(
@@ -190,6 +195,8 @@ export function createProgram(): Command {
               includeAsync: Boolean(opts.includeAsync),
               implementationRepo: opts.implementationRepo,
               implementationHints: opts.implementationHint.map(parseImplementationHint),
+              dynamicMode: parseDynamicMode(opts.dynamicMode),
+              maxDynamicCandidates: parsePositiveInteger(opts.maxDynamicCandidates, 5),
             },
           );
           process.stdout.write(
@@ -299,6 +306,8 @@ export function createProgram(): Command {
     .option('--implementation-repo <name>')
     .option('--implementation-hint <scope>', 'scoped implementation hint', collect, [])
     .option('--var <key=value>', 'dynamic variable', collect, [])
+    .option('--dynamic-mode <mode>', 'strict|candidates|infer', 'strict')
+    .option('--max-dynamic-candidates <n>', 'maximum dynamic candidates to show', '5')
     .action(
       (opts: {
         workspace?: string;
@@ -310,6 +319,8 @@ export function createProgram(): Command {
         implementationRepo?: string;
         implementationHint: string[];
         var: string[];
+        dynamicMode: string;
+        maxDynamicCandidates: string;
       }) =>
         void withReadOnlyWorkspace(opts.workspace, (db) => {
           const result = trace(
@@ -328,6 +339,8 @@ export function createProgram(): Command {
               vars: parseVars(opts.var),
               implementationRepo: opts.implementationRepo,
               implementationHints: opts.implementationHint.map(parseImplementationHint),
+              dynamicMode: parseDynamicMode(opts.dynamicMode),
+              maxDynamicCandidates: parsePositiveInteger(opts.maxDynamicCandidates, 5),
             },
           );
           process.stdout.write(
@@ -418,6 +431,15 @@ function collect(value: string, previous: string[]): string[] {
   previous.push(value);
   return previous;
 }
+function parseDynamicMode(value: string | undefined): DynamicMode {
+  if (value === undefined || value === 'strict') return 'strict';
+  if (value === 'candidates' || value === 'infer') return value;
+  throw new Error(`Invalid --dynamic-mode ${value}; expected strict, candidates, or infer`);
+}
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
 function fail(error: unknown): void {
   process.stderr.write(
     `${error instanceof Error ? error.message : String(error)}\n`,

package/src/db/migrations.ts

@@ -1,7 +1,10 @@
 import type { Db } from './connection.js';
 import { schemaSql } from './schema.js';
-const CURRENT_SCHEMA_VERSION = 9;
+const CURRENT_SCHEMA_VERSION = 10;
 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 '{}'" },
+  ],
   service_bindings: [
     { name: 'helper_chain_json', ddl: 'ALTER TABLE service_bindings ADD COLUMN helper_chain_json TEXT' },
     { name: 'alias_expr', ddl: 'ALTER TABLE service_bindings ADD COLUMN alias_expr TEXT' },

package/src/db/repositories.ts

@@ -211,7 +211,7 @@ export function insertHandler(
       .get(repoId, sid, h.className, h.sourceFile, h.sourceLine)?.id,
   );
   const stmt = db.prepare(
-    'INSERT INTO handler_methods(handler_class_id,method_name,decorator_kind,decorator_value,decorator_raw_expression,source_file,source_line) VALUES(?,?,?,?,?,?,?)',
+    'INSERT INTO handler_methods(handler_class_id,method_name,decorator_kind,decorator_value,decorator_raw_expression,decorator_resolution_json,source_file,source_line) VALUES(?,?,?,?,?,?,?,?)',
   );
   for (const m of h.methods)
     stmt.run(
@@ -220,6 +220,7 @@ export function insertHandler(
       m.decoratorKind,
       m.decoratorValue,
       m.decoratorRawExpression,
+      JSON.stringify(m.decoratorResolution),
       m.sourceFile,
       m.sourceLine,
     );

package/src/db/schema.ts

@@ -7,7 +7,7 @@ CREATE TABLE IF NOT EXISTS cds_services (id INTEGER PRIMARY KEY, repo_id INTEGER
 CREATE TABLE IF NOT EXISTS cds_operations (id INTEGER PRIMARY KEY, service_id INTEGER NOT NULL, operation_type TEXT NOT NULL, operation_name TEXT NOT NULL, operation_path TEXT NOT NULL, params_json TEXT NOT NULL, return_type TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, provenance TEXT NOT NULL DEFAULT 'direct', base_operation_id INTEGER, FOREIGN KEY(service_id) REFERENCES cds_services(id) ON DELETE CASCADE, FOREIGN KEY(base_operation_id) REFERENCES cds_operations(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS symbols (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, file_id INTEGER, kind TEXT NOT NULL, name TEXT NOT NULL, qualified_name TEXT NOT NULL, exported INTEGER NOT NULL, start_line INTEGER NOT NULL, end_line INTEGER NOT NULL, start_offset INTEGER, end_offset INTEGER, source_file TEXT, exported_name TEXT, evidence_json TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(file_id) REFERENCES files(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS handler_classes (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, class_name TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
-CREATE TABLE IF NOT EXISTS handler_methods (id INTEGER PRIMARY KEY, handler_class_id INTEGER NOT NULL, method_name TEXT NOT NULL, decorator_kind TEXT NOT NULL, decorator_value TEXT, decorator_raw_expression TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS handler_methods (id INTEGER PRIMARY KEY, handler_class_id INTEGER NOT NULL, method_name TEXT NOT NULL, decorator_kind TEXT NOT NULL, decorator_value TEXT, decorator_raw_expression TEXT NOT NULL, decorator_resolution_json TEXT NOT NULL DEFAULT '{}', source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS handler_registrations (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, handler_class_id INTEGER, class_name TEXT, import_source TEXT, registration_file TEXT NOT NULL, registration_line INTEGER NOT NULL, registration_kind TEXT NOT NULL, confidence REAL NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS service_bindings (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, variable_name TEXT NOT NULL, alias TEXT, alias_expr TEXT, destination_expr TEXT, service_path_expr TEXT, is_dynamic INTEGER NOT NULL, placeholders_json TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, helper_chain_json TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 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);

package/src/index.ts

@@ -11,5 +11,5 @@ export { applyVariables, extractPlaceholders, substituteVariables } from './link
 export type { RuntimeSubstitution } from './linker/dynamic-edge-resolver.js';
 export { trace } from './trace/trace-engine.js';
 export { parseImplementationHint } from './trace/implementation-hints.js';
-export type { ImplementationHint } from './types.js';
+export type { DynamicMode, ImplementationHint, TraceOptions } from './types.js';
 export { redactValue, redactText } from './utils/redaction.js';

package/src/linker/cross-repo-linker.ts

@@ -224,7 +224,15 @@ function compactCandidateScores(candidates: unknown[]): Array<Record<string, unk
   return candidates.flatMap((candidate): Array<Record<string, unknown>> => {
     const row = objectValue(candidate);
     if (!row) return [];
-    return [{ repo: row.repoName, servicePath: row.servicePath, operationPath: row.operationPath, score: row.score, reasons: row.reasons }];
+    return [{
+      repo: row.repoName,
+      servicePath: row.servicePath,
+      operationPath: row.operationPath,
+      score: row.score,
+      reasons: Array.isArray(row.reasons)
+        ? row.reasons.filter((reason): reason is string => typeof reason === 'string')
+        : ['operation_path_match'],
+    }];
   });
 }
 
@@ -301,14 +309,64 @@ function implementationContextForOperation(db: Db, operation: Record<string, unk
 }
 function rankedImplementationCandidates(db: Db, workspaceId: number, operation: Record<string, unknown>): ImplementationCandidate[] {
   const rows = implementationCandidates(db, workspaceId, operation);
-  return deduplicateCandidates(rows.map((row) => scoreImplementationCandidate(row, operation))).sort((a, b) => b.score - a.score || String(a.className).localeCompare(String(b.className)) || a.methodId - b.methodId);
+  const invalid = rows.filter((row) => !validRegistrationPair(row));
+  recordRegistrationInvariantDiagnostics(db, invalid);
+  return deduplicateCandidates(
+    rows.filter(validRegistrationPair)
+      .map((row) => scoreImplementationCandidate(row, operation)),
+  ).sort((a, b) => b.score - a.score || String(a.className).localeCompare(String(b.className)) || a.methodId - b.methodId);
+}
+function validRegistrationPair(row: Record<string, unknown>): boolean {
+  if (row.registrationHandlerClassId === null
+    || row.registrationHandlerClassId === undefined)
+    return registrationPairingStrategy(row) !== 'unproven';
+  return Number(row.registrationHandlerClassId) === Number(row.classId);
+}
+function registrationPairingStrategy(row: Record<string, unknown>): string {
+  if (row.registrationHandlerClassId !== null
+    && row.registrationHandlerClassId !== undefined)
+    return 'exact_handler_class_id';
+  if (Number(row.applicationRepoId) === Number(row.handlerRepoId))
+    return 'same_repository_class_name_fallback';
+  const source = stringValue(row.importSource);
+  const separator = source?.lastIndexOf('#') ?? -1;
+  if (!source || separator <= 0) return 'unproven';
+  const moduleName = source.slice(0, separator);
+  const importedName = source.slice(separator + 1);
+  const matchesClass = importedName === row.className
+    || (importedName === 'default' && row.registrationClassName === row.className);
+  return moduleName === row.handlerPackage && matchesClass
+    ? 'explicit_package_import'
+    : 'unproven';
+}
+function recordRegistrationInvariantDiagnostics(
+  db: Db,
+  rows: Array<Record<string, unknown>>,
+): void {
+  const insert = db.prepare(`INSERT INTO diagnostics(repo_id,severity,code,message,source_file,source_line)
+    SELECT ?,'error','handler_registration_class_mismatch',
+      'Implementation candidate registration did not match its persisted handler class id',?,?
+    WHERE NOT EXISTS (
+      SELECT 1 FROM diagnostics
+      WHERE repo_id=? AND code='handler_registration_class_mismatch'
+        AND source_file=? AND source_line=?
+    )`);
+  for (const row of rows)
+    insert.run(
+      row.applicationRepoId,
+      row.registrationFile,
+      row.registrationLine,
+      row.applicationRepoId,
+      row.registrationFile,
+      row.registrationLine,
+    );
 }
 
 function deduplicateCandidates(rows: ImplementationCandidate[]): ImplementationCandidate[] {
   const merged = new Map<string, ImplementationCandidate>();
   for (const row of rows) {
     const key = [row.methodId, row.classId, row.handlerRepoId].join(':');
-    const registration = { file: row.registrationFile, line: row.registrationLine, kind: row.registrationKind, importSource: row.importSource };
+    const registration = registrationEvidence(row);
     const existing = merged.get(key);
     if (!existing) {
       merged.set(key, { ...row, registrations: [registration] });
@@ -322,6 +380,19 @@ function deduplicateCandidates(rows: ImplementationCandidate[]): ImplementationC
   }
   return [...merged.values()];
 }
+function registrationEvidence(
+  row: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    id: row.registrationId,
+    handlerClassId: row.registrationHandlerClassId,
+    file: row.registrationFile,
+    line: row.registrationLine,
+    kind: row.registrationKind,
+    importSource: row.importSource,
+    pairingStrategy: registrationPairingStrategy(row),
+  };
+}
 function uniqueRegistrations(rows: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
   const seen = new Set<string>();
   return rows.filter((row) => {
@@ -352,10 +423,14 @@ function implementationCandidates(db: Db, workspaceId: number, operation: Record
       hm.method_name methodName,
       hm.decorator_value decoratorValue,
       hm.decorator_raw_expression decoratorRawExpression,
+      hm.decorator_resolution_json decoratorResolutionJson,
       hc.id classId,
       hc.class_name className,
       hc.source_file sourceFile,
       hc.source_line sourceLine,
+      hr.id registrationId,
+      hr.handler_class_id registrationHandlerClassId,
+      hr.class_name registrationClassName,
       hr.repo_id applicationRepoId,
       hr.registration_file registrationFile,
       hr.registration_line registrationLine,
@@ -378,14 +453,36 @@ function implementationCandidates(db: Db, workspaceId: number, operation: Record
       CASE WHEN appRepo.id=handlerRepo.id THEN 1 ELSE 0 END sameRepoRegistration,
       CASE WHEN EXISTS (SELECT 1 FROM cds_services localService WHERE localService.repo_id=appRepo.id AND localService.service_path=?) THEN 1 ELSE 0 END localServicePathMatch,
       CASE WHEN EXISTS (SELECT 1 FROM cds_services localService WHERE localService.repo_id=appRepo.id) THEN 1 ELSE 0 END applicationHasLocalServices,
-      CASE WHEN EXISTS (SELECT 1 FROM handler_registrations localReg JOIN handler_classes localClass ON (localClass.id=localReg.handler_class_id OR localClass.class_name=localReg.class_name) JOIN handler_methods localMethod ON localMethod.handler_class_id=localClass.id WHERE localReg.repo_id=appRepo.id AND (localMethod.decorator_value=? OR localMethod.decorator_value=? OR localMethod.method_name=? OR localMethod.decorator_raw_expression LIKE ?)) THEN 1 ELSE 0 END applicationHasLocalRegistrationForOperation,
+      CASE WHEN EXISTS (SELECT 1 FROM handler_registrations localReg JOIN handler_classes localClass ON ((localReg.handler_class_id IS NOT NULL AND localClass.id=localReg.handler_class_id) OR (localReg.handler_class_id IS NULL AND localClass.class_name=localReg.class_name AND localClass.repo_id=localReg.repo_id)) JOIN handler_methods localMethod ON localMethod.handler_class_id=localClass.id WHERE localReg.repo_id=appRepo.id AND (localMethod.decorator_value=? OR localMethod.decorator_value=? OR localMethod.method_name=? OR localMethod.decorator_raw_expression LIKE ?)) THEN 1 ELSE 0 END applicationHasLocalRegistrationForOperation,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(appRepo.id AS TEXT) AND dep.to_id=?) THEN 1 ELSE 0 END appDependsOnModel,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(appRepo.id AS TEXT) AND dep.to_id=CAST(handlerRepo.id AS TEXT)) THEN 1 ELSE 0 END appDependsOnHandler,
       CASE WHEN EXISTS (SELECT 1 FROM graph_edges dep WHERE dep.edge_type='REPO_IMPORTS_HELPER_PACKAGE' AND dep.status='resolved' AND dep.from_kind='repo' AND dep.from_id=CAST(handlerRepo.id AS TEXT) AND dep.to_id=?) THEN 1 ELSE 0 END handlerDependsOnModel
     FROM handler_methods hm
     JOIN handler_classes hc ON hc.id=hm.handler_class_id
     JOIN repositories handlerRepo ON handlerRepo.id=hc.repo_id
-    JOIN handler_registrations hr ON (hr.handler_class_id=hc.id OR (hr.class_name=hc.class_name AND (hr.repo_id=hc.repo_id OR hr.import_source IS NOT NULL)))
+    JOIN handler_registrations hr ON (
+      (hr.handler_class_id IS NOT NULL AND hr.handler_class_id=hc.id)
+      OR (
+        hr.handler_class_id IS NULL
+        AND (
+          (hr.class_name=hc.class_name AND hr.repo_id=hc.repo_id)
+          OR (
+            instr(hr.import_source,'#')>1
+            AND substr(hr.import_source,1,instr(hr.import_source,'#')-1)
+              =handlerRepo.package_name
+            AND (
+              substr(hr.import_source,instr(hr.import_source,'#')+1)
+                =hc.class_name
+              OR (
+                substr(hr.import_source,instr(hr.import_source,'#')+1)
+                  ='default'
+                AND hr.class_name=hc.class_name
+              )
+            )
+          )
+        )
+      )
+    )
     JOIN repositories appRepo ON appRepo.id=hr.repo_id
     WHERE appRepo.workspace_id=?
       AND (hm.decorator_value=? OR hm.decorator_value=? OR hm.method_name=? OR hm.decorator_raw_expression LIKE ?)`).all(
@@ -487,8 +584,16 @@ function candidateEvidence(candidate: ImplementationCandidate, rank: number): Re
     className: candidate.className,
     sourceFile: candidate.sourceFile,
     sourceLine: candidate.sourceLine,
-    registration: { file: candidate.registrationFile, line: candidate.registrationLine, kind: candidate.registrationKind, importSource: candidate.importSource },
+    decoratorResolution: objectJson(candidate.decoratorResolutionJson),
+    registration: registrationEvidence(candidate),
     registrations: candidate.registrations ?? [],
+    registrationPairing: {
+      strategy: registrationPairingStrategy(candidate),
+      registrationId: candidate.registrationId,
+      registrationHandlerClassId: candidate.registrationHandlerClassId,
+      candidateHandlerClassId: candidate.classId,
+      invariantStatus: validRegistrationPair(candidate) ? 'valid' : 'invalid',
+    },
     applicationPackage: { id: candidate.applicationRepoId, name: candidate.applicationRepo, packageName: candidate.applicationPackage },
     handlerPackage: { id: candidate.handlerRepoId, name: candidate.handlerRepo, packageName: candidate.handlerPackage },
     modelPackage: { id: candidate.modelRepoId, name: candidate.modelRepo, packageName: candidate.modelPackage },

package/src/linker/operation-decorator-normalizer.ts

@@ -12,7 +12,7 @@ export function normalizedOperationName(value: string): string {
 function clean(value: string): string {
   return value.replace(/^[`'"]|[`'"]$/g, '');
 }
-function generatedFromConstantName(value: string): string | undefined {
+export function generatedOperationNameFromConstant(value: string): string | undefined {
   for (const prefix of ['Action', 'Func']) {
     if (value.startsWith(prefix) && value.length > prefix.length && /^[A-Z]/.test(value.slice(prefix.length))) return lowerFirst(value.slice(prefix.length));
   }
@@ -20,7 +20,7 @@ function generatedFromConstantName(value: string): string | undefined {
 }
 function resolved(value: string, raw?: string): DecoratorOperationSignal {
   const literal = clean(value);
-  const generated = generatedFromConstantName(literal);
+  const generated = generatedOperationNameFromConstant(literal);
   return { status: 'resolved', operationName: generated ?? normalizedOperationName(literal), raw };
 }
 export function normalizeDecoratorOperationSignal(value: string | undefined, raw: string | undefined, candidateOperation?: string): DecoratorOperationSignal {
@@ -32,7 +32,7 @@ export function normalizeDecoratorOperationSignal(value: string | undefined, raw
   const stringMatch = /^String\(([A-Za-z_$][\w$]*)\)$/.exec(expression);
   if (stringMatch?.[1]) {
     const identifier = stringMatch[1];
-    const generated = generatedFromConstantName(identifier);
+    const generated = generatedOperationNameFromConstant(identifier);
     const normalizedCandidate = candidateOperation ? normalizedOperationName(candidateOperation) : undefined;
     if (generated) return { status: 'resolved', operationName: generated, raw: expression };
     if (normalizedCandidate && identifier === normalizedCandidate) return { status: 'resolved', operationName: identifier, raw: expression };

package/src/linker/service-resolver.ts

@@ -26,9 +26,9 @@ function rows(
   workspaceId?: number,
 ): OperationTarget[] {
   const names = operationLookupNames(operationPath);
-  return db
+  const result = db
     .prepare(
-      `SELECT o.id operationId,r.id repoId,r.name repoName,r.package_name packageName,s.service_name serviceName,s.qualified_name qualifiedName,s.service_path servicePath,o.operation_path operationPath,o.operation_name operationName,o.source_file sourceFile,o.source_line sourceLine,0 score,'' reasons
+      `SELECT o.id operationId,r.id repoId,r.name repoName,r.package_name packageName,s.service_name serviceName,s.qualified_name qualifiedName,s.service_path servicePath,o.operation_path operationPath,o.operation_name operationName,o.source_file sourceFile,o.source_line sourceLine,0 score
        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 r.workspace_id=?) AND (o.operation_path IN (?,?) OR o.operation_name IN (?,?)) ORDER BY r.name,s.service_path,o.operation_name`,
     )
@@ -39,7 +39,12 @@ function rows(
       names.simplePath,
       names.name,
       names.simpleName,
-    ) as unknown as OperationTarget[];
+    ) as Array<Omit<OperationTarget, 'reasons'>>;
+  return result.map((row) => ({
+    ...row,
+    score: Number(row.score ?? 0),
+    reasons: [],
+  }));
 }
 function operationLookupNames(operationPath: string): { path: string; simplePath: string; name: string; simpleName: string } {
   const name = operationPath.replace(/^\//, '');
@@ -70,7 +75,13 @@ export function resolveOperation(
   if (missing.length > 0)
     return {
       status: 'dynamic',
-      candidates: signals.operationPath ? rows(db, signals.operationPath, workspaceId) : [],
+      candidates: signals.operationPath
+        ? rows(db, signals.operationPath, workspaceId).map((candidate) => ({
+            ...candidate,
+            score: 0.2,
+            reasons: ['operation_path_match'],
+          }))
+        : [],
       reasons: [...new Set(missing)].map((name) => `missing_variable:${name}`),
     };
   if (!signals.operationPath)

package/src/output/table-output.ts

@@ -28,8 +28,9 @@ function diagnosticLines(diagnostic: Record<string, unknown>): string[] {
 }
 
 function hintLines(evidence: Record<string, unknown>): string[] {
+  const dynamicLines = dynamicHintLines(evidence);
   const suggestions = evidence.implementationHintSuggestions;
-  if (!Array.isArray(suggestions)) return [];
+  if (!Array.isArray(suggestions)) return dynamicLines;
   const hints = suggestions.flatMap((item) =>
     isRecord(item) && typeof item.cli === 'string'
       ? [item.cli]
@@ -38,9 +39,35 @@ function hintLines(evidence: Record<string, unknown>): string[] {
   const shown = unique.slice(0, 3).map((hint) => `try ${hint}`);
   if (unique.length > shown.length)
     shown.push(`... ${unique.length - shown.length} more hint(s) available in JSON`);
-  return shown;
+  return [...dynamicLines, ...shown];
+}
+
+function dynamicHintLines(evidence: Record<string, unknown>): string[] {
+  const exploration = isRecord(evidence.dynamicTargetExploration)
+    ? evidence.dynamicTargetExploration
+    : evidence;
+  const count = numberValue(exploration.candidateCount);
+  if (count === 0) return [];
+  const shown = numberValue(exploration.shownCandidateCount);
+  const omitted = numberValue(exploration.omittedCandidateCount);
+  const lines = [`candidates: ${shown} shown, ${omitted} omitted`];
+  lines.push(...varSetHints(exploration.suggestedVarSets));
+  if (omitted > 0 || shown < count)
+    lines.push('use --dynamic-mode candidates --max-dynamic-candidates 20 to explore candidate branches');
+  return lines;
+}
+
+function varSetHints(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const hints = value.flatMap((item) =>
+    isRecord(item) && typeof item.cli === 'string' ? [`try ${item.cli}`] : []);
+  return [...new Set(hints)].slice(0, 3);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
+
+function numberValue(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}