@saptools/service-flow 0.1.49 → 0.1.50

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;
 }

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   stripQuotes,
   substituteVariables,
   trace
-} from "./chunk-XOROZHW4.js";
+} from "./chunk-52OUS3MO.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.50",
   "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/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/linker/cross-repo-linker.ts

@@ -301,14 +301,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 +372,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 +415,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 +445,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 +576,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/parsers/decorator-parser.ts

@@ -1,9 +1,18 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import ts from 'typescript';
-import type { HandlerClassFact } from '../types.js';
+import type { HandlerClassFact, HandlerMethodFact } from '../types.js';
+import { generatedOperationNameFromConstant } from '../linker/operation-decorator-normalizer.js';
 import { createSourceFile } from './ts-project.js';
-import { normalizePath, stripQuotes } from '../utils/path-utils.js';
+import { normalizePath } from '../utils/path-utils.js';
+
+type DecoratorResolution = HandlerMethodFact['decoratorResolution'];
+interface StringLookups {
+  identifiers: Map<string, string>;
+  enumMembers: Map<string, string>;
+  objectProperties: Map<string, string>;
+}
+
 function line(sf: ts.SourceFile, pos: number): number {
   return sf.getLineAndCharacterOfPosition(pos).line + 1;
 }
@@ -14,11 +23,119 @@ function callName(d: ts.Decorator): string {
   const e = d.expression;
   return ts.isCallExpression(e) ? e.expression.getText() : e.getText();
 }
-function firstArg(d: ts.Decorator): string {
+function firstArg(d: ts.Decorator): ts.Expression | undefined {
   const e = d.expression;
-  return ts.isCallExpression(e) && e.arguments[0]
-    ? e.arguments[0].getText()
-    : '';
+  return ts.isCallExpression(e) ? e.arguments[0] : undefined;
+}
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current)
+    || ts.isAsExpression(current)
+    || ts.isTypeAssertionExpression(current)
+    || ts.isSatisfiesExpression(current)
+  ) current = current.expression;
+  return current;
+}
+function stringValue(expression: ts.Expression | undefined): string | undefined {
+  if (!expression) return undefined;
+  const unwrapped = unwrapExpression(expression);
+  return ts.isStringLiteralLike(unwrapped) ? unwrapped.text : undefined;
+}
+function propertyName(node: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;
+  return undefined;
+}
+function collectEnumMembers(
+  statement: ts.EnumDeclaration,
+  lookups: StringLookups,
+): void {
+  for (const member of statement.members) {
+    const name = propertyName(member.name);
+    const value = stringValue(member.initializer);
+    if (name && value !== undefined)
+      lookups.enumMembers.set(`${statement.name.text}.${name}`, value);
+  }
+}
+function collectObjectProperties(
+  name: string,
+  initializer: ts.Expression,
+  lookups: StringLookups,
+): void {
+  const object = unwrapExpression(initializer);
+  if (!ts.isObjectLiteralExpression(object)) return;
+  for (const property of object.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const key = propertyName(property.name);
+    const value = stringValue(property.initializer);
+    if (key && value !== undefined)
+      lookups.objectProperties.set(`${name}.${key}`, value);
+  }
+}
+function collectStringLookups(source: ts.SourceFile): StringLookups {
+  const lookups: StringLookups = {
+    identifiers: new Map(),
+    enumMembers: new Map(),
+    objectProperties: new Map(),
+  };
+  for (const statement of source.statements) {
+    if (ts.isEnumDeclaration(statement)) collectEnumMembers(statement, lookups);
+    if (!ts.isVariableStatement(statement)
+      || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
+      const value = stringValue(declaration.initializer);
+      if (value !== undefined) lookups.identifiers.set(declaration.name.text, value);
+      collectObjectProperties(declaration.name.text, declaration.initializer, lookups);
+    }
+  }
+  return lookups;
+}
+function unresolved(rawExpression: string, reason: string): DecoratorResolution {
+  return { rawExpression, resolutionKind: 'unresolved', unresolvedReason: reason };
+}
+function generatedConstant(rawExpression: string): string | undefined {
+  const match = /(?:^|\.)(Action[A-Z][\w$]*|Func[A-Z][\w$]*)\.name$/
+    .exec(rawExpression.trim());
+  return match?.[1]
+    ? generatedOperationNameFromConstant(match[1])
+    : undefined;
+}
+function resolveDecoratorArgument(
+  argument: ts.Expression | undefined,
+  lookups: StringLookups,
+): DecoratorResolution {
+  if (!argument) return unresolved('', 'decorator_argument_missing');
+  const rawExpression = argument.getText();
+  const expression = unwrapExpression(argument);
+  if (ts.isStringLiteralLike(expression))
+    return { rawExpression, resolvedValue: expression.text, resolutionKind: 'literal' };
+  if (ts.isIdentifier(expression)) {
+    const value = lookups.identifiers.get(expression.text);
+    return value === undefined
+      ? unresolved(rawExpression, 'identifier_not_resolved_to_local_const_string')
+      : { rawExpression, resolvedValue: value, resolutionKind: 'const_identifier' };
+  }
+  if (ts.isPropertyAccessExpression(expression)
+    && ts.isIdentifier(expression.expression)) {
+    const key = `${expression.expression.text}.${expression.name.text}`;
+    const enumValue = lookups.enumMembers.get(key);
+    if (enumValue !== undefined)
+      return { rawExpression, resolvedValue: enumValue, resolutionKind: 'enum_member' };
+    const objectValue = lookups.objectProperties.get(key);
+    if (objectValue !== undefined)
+      return { rawExpression, resolvedValue: objectValue, resolutionKind: 'const_object_property' };
+  }
+  const generatedValue = generatedConstant(rawExpression);
+  if (generatedValue !== undefined)
+    return {
+      rawExpression,
+      resolvedValue: generatedValue,
+      resolutionKind: 'generated_constant_name',
+    };
+  if (ts.isPropertyAccessExpression(expression))
+    return unresolved(rawExpression, 'property_access_not_resolved_to_local_string');
+  return unresolved(rawExpression, 'unsupported_decorator_expression');
 }
 export async function parseDecorators(
   repoPath: string,
@@ -26,16 +143,9 @@ export async function parseDecorators(
 ): Promise<HandlerClassFact[]> {
   const text = await fs.readFile(path.join(repoPath, filePath), 'utf8');
   const sf = createSourceFile(filePath, text);
-  const constants = new Map<string, string>();
+  const lookups = collectStringLookups(sf);
   const handlers: HandlerClassFact[] = [];
   function visit(node: ts.Node): void {
-    if (
-      ts.isVariableDeclaration(node) &&
-      ts.isIdentifier(node.name) &&
-      node.initializer &&
-      ts.isStringLiteralLike(node.initializer)
-    )
-      constants.set(node.name.text, node.initializer.text);
     if (ts.isClassDeclaration(node)) {
       const className = node.name?.text ?? 'AnonymousHandler';
       const hasHandler = decs(node).some((d) => callName(d) === 'Handler');
@@ -45,17 +155,13 @@ export async function parseDecorators(
             ['Func', 'Action', 'On', 'Event'].includes(callName(d))
           )
           .map((d) => {
-            const raw = firstArg(d);
-            const value =
-              raw.startsWith('"') || raw.startsWith("'") || raw.startsWith('`')
-                ? stripQuotes(raw)
-                : (constants.get(raw) ??
-                  (raw.endsWith('.name') ? raw.split('.').at(-2) : undefined));
+            const decoratorResolution = resolveDecoratorArgument(firstArg(d), lookups);
             return {
               methodName: m.name.getText(),
               decoratorKind: callName(d),
-              decoratorValue: value,
-              decoratorRawExpression: raw,
+              decoratorValue: decoratorResolution.resolvedValue,
+              decoratorRawExpression: decoratorResolution.rawExpression,
+              decoratorResolution,
               sourceFile: normalizePath(filePath),
               sourceLine: line(sf, m.getStart())
             };

package/src/trace/selectors.ts

@@ -18,3 +18,39 @@ export function startLabel(start: TraceStart): string {
     .filter(Boolean)
     .join(' ');
 }
+export function ambiguousStartDiagnostic(
+  requested: string,
+  candidates: Array<Record<string, unknown>>,
+  message: string,
+): Record<string, unknown> {
+  const serviceSuggestions = [...new Set(candidates
+    .flatMap((row) => typeof row.servicePath === 'string'
+      ? [`--service ${row.servicePath}`]
+      : []))].sort();
+  return {
+    severity: 'warning',
+    code: 'trace_start_ambiguous',
+    message,
+    normalizedSelectorValue: requested,
+    resolutionStage: 'operation',
+    resolutionStatus: 'ambiguous_operation',
+    candidates,
+    serviceSuggestions,
+    selectorSuggestions: fullSelectorSuggestions(candidates),
+  };
+}
+function fullSelectorSuggestions(
+  candidates: Array<Record<string, unknown>>,
+): string[] {
+  const includeRepo = new Set(candidates.map((row) => row.repoName)).size > 1;
+  return [...new Set(candidates.flatMap((row) => {
+    if (typeof row.servicePath !== 'string'
+      || typeof row.operationPath !== 'string') return [];
+    const repoSelector = includeRepo && typeof row.repoName === 'string'
+      ? `--repo ${row.repoName} `
+      : '';
+    return [
+      `${repoSelector}--service ${row.servicePath} --path ${row.operationPath}`,
+    ];
+  }))].sort();
+}

package/src/trace/trace-engine.ts

@@ -5,6 +5,7 @@ import { resolveOperation } from '../linker/service-resolver.js';
 import type { ImplementationHint, TraceEdge, TraceResult, TraceStart } from '../types.js';
 import { baseTraceEvidence, edgeTarget, runtimeResolution, runtimeVariableDiagnostic, type TraceGraphRow } from './evidence.js';
 import { implementationHintDiagnostic, selectImplementation, type ImplementationSelection } from './implementation-hints.js';
+import { ambiguousStartDiagnostic } from './selectors.js';
 interface RepoRef {
   id: number;
   name: string;
@@ -120,26 +121,6 @@ function implementationRejectionReasons(evidence: Record<string, unknown>): stri
       : []);
   return [...new Set(reasons)].sort();
 }
-function ambiguousStartDiagnostic(
-  requested: string,
-  candidates: Array<Record<string, unknown>>,
-  message: string,
-): Record<string, unknown> {
-  const serviceSuggestions = [...new Set(candidates
-    .flatMap((row) => typeof row.servicePath === 'string'
-      ? [`--service ${row.servicePath}`]
-      : []))].sort();
-  return {
-    severity: 'warning',
-    code: 'trace_start_ambiguous',
-    message,
-    normalizedSelectorValue: requested,
-    resolutionStage: 'operation',
-    resolutionStatus: 'ambiguous_operation',
-    candidates,
-    serviceSuggestions,
-  };
-}
 function sourceFilesForStart(
   db: Db,
   repoId: number | undefined,

package/src/types.ts

@@ -101,6 +101,18 @@ export 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;
 }