@saptools/service-flow 0.1.68 → 0.1.69

package/src/parsers/symbol-parser.ts

@@ -42,6 +42,12 @@ function isFunctionLike(node: ts.Node): node is ts.FunctionLikeDeclaration {
 function exported(node: ts.Node): boolean {
   return Boolean(ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Export);
 }
+function defaultExported(node: ts.Node): boolean {
+  return Boolean(
+    ts.getCombinedModifierFlags(node as ts.Declaration)
+      & ts.ModifierFlags.Default,
+  );
+}
 function isPublicClassMethod(node: ts.MethodDeclaration): boolean {
   const flags = ts.getCombinedModifierFlags(node);
   return (flags & ts.ModifierFlags.Private) === 0 && (flags & ts.ModifierFlags.Protected) === 0;
@@ -141,6 +147,7 @@ interface SymbolCollection {
   exportNames: Map<string, string>;
   objectExports: Set<string>;
   exportedClasses: Set<string>;
+  defaultExportedClasses: Set<string>;
   declaredClasses: Set<string>;
   proxies: Map<string, SymbolCallProxy[]>;
   instances: Map<string, SymbolClassInstance[]>;
@@ -153,7 +160,8 @@ function symbolSourceEvidence(
     parentRoot: string;
     qualifiedName: string;
     declaredExportName?: string;
-    classContainerExported: boolean; classMemberExported: boolean;
+    classContainerExported: boolean; classContainerDefaultExported: boolean;
+    classMemberExported: boolean;
     objectExported: boolean;
     evidence?: Record<string, unknown>;
   },
@@ -168,6 +176,8 @@ function symbolSourceEvidence(
   if (options.classContainerExported && ts.isMethodDeclaration(node)
     && isPublicClassMethod(node)) return {
     source: 'exported_class_instance_member', exportedClass: options.parentRoot,
+    exportedClassExportKind: options.classContainerDefaultExported
+      ? 'default' : 'named',
     memberKind: 'class_method',
   };
   if (options.declaredExportName) return {
@@ -201,6 +211,7 @@ interface SymbolNames {
   declaredExportName?: string;
   objectExported: boolean;
   classContainerExported: boolean;
+  classContainerDefaultExported: boolean;
   classMemberExported: boolean;
   effectiveName?: string;
 }
@@ -219,6 +230,24 @@ function exportedClassMember(
     && isPublicClassMethod(node);
 }
 
+function classExportState(
+  collection: SymbolCollection,
+  parentName: string | undefined,
+  parentRoot: string,
+): {
+  classContainerExported: boolean;
+  classContainerDefaultExported: boolean;
+} {
+  return {
+    classContainerExported: Boolean(
+      parentName && collection.exportedClasses.has(parentRoot),
+    ),
+    classContainerDefaultExported: Boolean(
+      parentName && collection.defaultExportedClasses.has(parentRoot),
+    ),
+  };
+}
+
 function symbolNames(
   collection: SymbolCollection,
   kind: string,
@@ -238,12 +267,11 @@ function symbolNames(
   const classMemberExported = exportedClassMember(
     collection, kind, parentName, parentRoot, node,
   );
-  const classContainerExported = Boolean(
-    parentName && collection.exportedClasses.has(parentRoot),
-  );
+  const classState = classExportState(collection, parentName, parentRoot);
   return {
     parentRoot, declaredExportName, qualifiedName,
-    objectExported, classContainerExported, classMemberExported,
+    objectExported, ...classState,
+    classMemberExported,
     effectiveName: classMemberExported || objectExported
       ? qualifiedName : declaredExportName,
   };
@@ -266,6 +294,7 @@ function addExecutableSymbol(
     qualifiedName: names.qualifiedName,
     declaredExportName: names.declaredExportName,
     classContainerExported: names.classContainerExported,
+    classContainerDefaultExported: names.classContainerDefaultExported,
     classMemberExported: names.classMemberExported,
     objectExported: names.objectExported,
     evidence,
@@ -457,6 +486,8 @@ function collectClassDeclaration(
   collection.declaredClasses.add(node.name.text);
   if (exported(node) || collection.exportNames.has(node.name.text))
     collection.exportedClasses.add(node.name.text);
+  if (defaultExported(node))
+    collection.defaultExportedClasses.add(node.name.text);
   for (const member of node.members)
     visitDeclaredSymbol(collection, member, node.name.text);
   return true;
@@ -553,6 +584,7 @@ function createCollection(
     importBindings: collectSymbolImportBindings(source),
     exportNames: exportDeclarations(source),
     objectExports: new Set(), exportedClasses: new Set(),
+    defaultExportedClasses: new Set(),
     declaredClasses: new Set(), proxies: new Map(), instances: new Map(),
   };
 }

package/src/trace/007-implementation-start-diagnostic.ts

@@ -15,6 +15,7 @@ export function implementationStartDiagnostic(
     message: `Indexed operation matched but implementation edge is ${String(
       edge.status ?? 'unresolved',
     )}`,
+    selectorKind: 'operation',
     resolutionStage: 'implementation',
     resolutionStatus: edge.status === 'ambiguous'
       ? 'ambiguous_implementation'

package/src/trace/011-event-subscriber-traversal.ts

@@ -1,5 +1,10 @@
 import type { Db } from '../db/connection.js';
 import {
+  matchRuntimeTemplate,
+  substituteVariables,
+} from '../linker/dynamic-edge-resolver.js';
+import {
+  compareBinary,
   type TraversalScopeScheduler,
   type TraversalScopeState,
 } from './010-traversal-scope.js';
@@ -53,6 +58,8 @@ export interface EventSubscriberTransition {
   candidateCount: number;
   symbolCallUnresolvedReason?: string;
   omittedSymbolCallUnresolvedReasonCharacterCount?: number;
+  matchStrategy?: string;
+  dispatchCertainty?: string;
   handler?: EventSubscriberSymbolTarget;
 }
 
@@ -60,6 +67,7 @@ export interface EventSubscriberTransitionQuery {
   workspaceId: number;
   graphGeneration: number;
   eventName: string;
+  vars?: Record<string, string>;
 }
 
 export type EventBodyExpansion =
@@ -156,8 +164,8 @@ export function eventTransitionEvidence(
     subscribeCallId: transition.subscribeCallId,
     symbolCallId: transition.symbolCallId,
     eventName: transition.eventName,
-    matchStrategy: 'workspace_exact_event_name',
-    dispatchCertainty: 'static_name_only',
+    matchStrategy: transition.matchStrategy ?? 'workspace_exact_event_name',
+    dispatchCertainty: transition.dispatchCertainty ?? 'static_name_only',
     associationBasis: transition.associationBasis,
     dispatchScope: transition.dispatchScope,
     roleSiteMatchCount: transition.roleSiteMatchCount,
@@ -194,7 +202,8 @@ export function loadEventSubscriberTransitions(
   query: EventSubscriberTransitionQuery,
 ): EventSubscriberTransition[] {
   const rows = db.prepare(`SELECT ge.id graphEdgeId,ge.generation graphGeneration,
-      ge.from_id eventName,ge.status,ge.to_kind targetKind,ge.to_id targetId,
+      ge.from_kind fromKind,ge.from_id eventName,ge.status,
+      ge.to_kind targetKind,ge.to_id targetId,
       ge.confidence,ge.unresolved_reason unresolvedReason,ge.evidence_json evidenceJson,
       subscribe.id subscribeCallId,subscribe.repo_id subscriptionRepoId,
       subscribe.source_file sourceFile,subscribe.source_line sourceLine,
@@ -218,19 +227,100 @@ export function loadEventSubscriberTransitions(
     LEFT JOIN repositories handler_repo
       ON handler_repo.id=handler.repo_id AND handler_repo.workspace_id=ge.workspace_id
     WHERE ge.workspace_id=? AND ge.generation=?
-      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY' AND ge.from_kind='event'
-      AND ge.from_id COLLATE BINARY=? COLLATE BINARY
+      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ge.from_kind IN ('event','event_candidate')
     ORDER BY COALESCE(subscription_repo.name,'') COLLATE BINARY,
       COALESCE(subscription_repo.id,0),COALESCE(subscribe.source_file,'') COLLATE BINARY,
       subscribe.call_site_start_offset,subscribe.call_site_end_offset,ge.id`).all(
-    query.workspaceId, query.graphGeneration, query.eventName,
+    query.workspaceId, query.graphGeneration,
   );
-  return rows.flatMap((row) => {
-    const transition = transitionFromRow(row);
+  return rows.flatMap((raw) => {
+    const row = eventRowForQuery(raw, query);
+    const transition = row ? transitionFromRow(row) : undefined;
     return transition ? [transition] : [];
   });
 }
 
+function eventRowForQuery(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+): Record<string, unknown> | undefined {
+  const variables = query.vars;
+  if (variables === undefined) return exactPersistedEventRow(row, query);
+  const evidence = parseEvidence(row.evidenceJson);
+  const resolution = isRecord(evidence.eventTemplateResolution)
+    ? evidence.eventTemplateResolution : {};
+  if (typeof resolution.original !== 'string')
+    return exactPersistedEventRow(row, query);
+  return runtimeMatchedEventRow(
+    row, query, evidence, resolution.original, variables,
+  );
+}
+
+function exactPersistedEventRow(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+): Record<string, unknown> | undefined {
+  return row.fromKind === 'event' && row.eventName === query.eventName
+    ? row : undefined;
+}
+
+function runtimeMatchedEventRow(
+  row: Record<string, unknown>,
+  query: EventSubscriberTransitionQuery,
+  evidence: Record<string, unknown>,
+  template: string,
+  variables: Record<string, string>,
+): Record<string, unknown> | undefined {
+  const substitution = substituteVariables(template, variables);
+  if (substitution.missing.length > 0
+    || substitution.effective !== query.eventName) return undefined;
+  const resolvedAssociation = evidence.associationStatus === 'resolved';
+  return {
+    ...row,
+    eventName: query.eventName,
+    status: typeof evidence.associationStatus === 'string'
+      ? evidence.associationStatus : row.status,
+    unresolvedReason: resolvedAssociation ? null : row.unresolvedReason,
+    evidenceJson: JSON.stringify({
+      ...evidence,
+      eventSubscriptionRuntimeSubstitution: substitution,
+      matchStrategy: 'workspace_exact_event_name_after_runtime_substitution',
+      dispatchCertainty: 'runtime_variables_exact',
+    }),
+  };
+}
+
+export function eventSubscriberMissingVariables(
+  db: Db,
+  query: EventSubscriberTransitionQuery,
+): string[] {
+  if (query.vars === undefined) return [];
+  const variables = query.vars;
+  const rows = db.prepare(`SELECT ge.from_id eventName,
+    ge.evidence_json evidenceJson FROM graph_edges ge
+    WHERE ge.workspace_id=? AND ge.generation=?
+      AND ge.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
+      AND ge.from_kind='event_candidate'`).all(
+    query.workspaceId, query.graphGeneration,
+  );
+  const missing = rows.flatMap((row) => {
+    const evidence = parseEvidence(row.evidenceJson);
+    const resolution = isRecord(evidence.eventTemplateResolution)
+      ? evidence.eventTemplateResolution : {};
+    const template = typeof resolution.original === 'string'
+      ? resolution.original : undefined;
+    if (!template) return [];
+    const substitution = substituteVariables(template, variables);
+    if (substitution.missing.length === 0
+      || matchRuntimeTemplate(
+        substitution.effective, query.eventName,
+      ) === undefined) return [];
+    return substitution.missing;
+  });
+  return [...new Set(missing)].sort(compareBinary);
+}
+
 function transitionFromRow(
   row: Record<string, unknown>,
 ): EventSubscriberTransition | undefined {
@@ -290,6 +380,8 @@ function associationEvidence(
     omittedSymbolCallUnresolvedReasonCharacterCount: symbolCallUnresolvedReason
       ? nonNegativeCount(evidence.omittedSymbolCallUnresolvedReasonCharacterCount)
       : undefined,
+    matchStrategy: stringValue(evidence.matchStrategy),
+    dispatchCertainty: stringValue(evidence.dispatchCertainty),
   };
 }
 

package/src/trace/013-trace-root-scopes.ts

@@ -253,12 +253,11 @@ function hasExactDispatch(db: Db, calls: RootCallRow[]): boolean {
           AND subscriber.generation=emitted.generation
           AND subscriber.edge_type='EVENT_SUBSCRIPTION_HANDLED_BY'
           AND subscriber.from_kind='event'
-          AND subscriber.from_id COLLATE BINARY=? COLLATE BINARY)
+          AND subscriber.from_id COLLATE BINARY=emitted.to_id COLLATE BINARY)
     LIMIT 1`);
   return calls.some((call) => call.callType === 'async_emit'
-    && typeof call.eventName === 'string'
     && Boolean(match.get(call.workspaceId, call.graphGeneration,
-      String(call.id), call.eventName)));
+      String(call.id))));
 }
 
 function workspaceAmbiguityDiagnostic(db: Db): Record<string, unknown> {

package/src/trace/014-compact-contract.ts

@@ -82,6 +82,7 @@ export interface CompactDecisionInput {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   reasonCode?: string;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
@@ -225,6 +226,7 @@ export interface CompactDecisionV1 {
   implementationStrategy?: string;
   implementationGuided?: boolean;
   implementationContextual?: boolean;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
   eventMatchStrategy?: string;
   dispatchCertainty?: string;
   eventSubscriptionCount?: number;
@@ -247,6 +249,10 @@ export interface CompactEdgeDetailsV1 {
 
 export interface CompactDiagnosticDetailsV1 {
   reasonCode?: string;
+  tiedCandidateRepos?: CompactReferenceGroupV1;
+  selectorKind?: string;
+  selectorSuggestions?: CompactReferenceGroupV1;
+  invalidFactCategories?: CompactReferenceGroupV1;
   missingVariableNames?: string[];
   missingVariableCount?: number;
   shownMissingVariableCount?: number;

package/src/trace/015-trace-edge-recorder.ts

@@ -8,6 +8,12 @@ import type {
   CompactStatus,
   CompactTraceObserver,
 } from './014-compact-contract.js';
+import { implementationHintSuggestionProjection } from
+  './implementation-hints.js';
+import {
+  isSafeCompactReferenceName,
+  projectCompactReferenceGroup,
+} from './021-compact-decision-normalization.js';
 
 export interface TraceEdgeSemantics {
   source: CompactSemanticEndpoint;
@@ -111,8 +117,7 @@ export function semanticGraphTarget(
 ): CompactSemanticEndpoint {
   if (row.to_kind === 'event') return {
     kind: 'event', workspaceId,
-    eventName: typeof call.event_name_expr === 'string'
-      ? call.event_name_expr : row.to_id,
+    eventName: row.to_id,
   };
   const id = positiveNumber(row.to_id);
   if (row.to_kind === 'operation')
@@ -198,7 +203,7 @@ export function compactDecisionFromEvidence(
   const authoritativeMissingCount = finiteNumber(
     dynamic.missingVariableCount ?? evidence.missingVariableCount,
   );
-  return {
+  const decision: CompactDecisionInput = {
     effectiveResolutionStatus: stringValue(effective.status),
     effectiveTarget: targetSummary(effective),
     persistedResolutionStatus: stringValue(persisted.status),
@@ -221,7 +226,7 @@ export function compactDecisionFromEvidence(
     implementationGuided: booleanValue(implementation.guided),
     implementationContextual: booleanValue(
       evidence.contextualImplementationSelected),
-    reasonCode: stringValue(evidence.reasonCode ?? evidence.cycleReason),
+    reasonCode: compactEvidenceReasonCode(evidence),
     eventMatchStrategy: stringValue(evidence.matchStrategy),
     dispatchCertainty: stringValue(evidence.dispatchCertainty),
     associationStatus: stringValue(evidence.associationStatus),
@@ -233,6 +238,7 @@ export function compactDecisionFromEvidence(
     bodyExpansion: stringValue(evidence.bodyExpansion),
     ...overrides,
   };
+  return decisionWithTiedCandidates(evidence, decision);
 }
 
 export function compactRefs(
@@ -334,3 +340,54 @@ function firstNumber(...values: unknown[]): number | undefined {
   }
   return undefined;
 }
+
+export function compactEvidenceReasonCode(
+  evidence: Record<string, unknown>,
+): string | undefined {
+  return stringValue(evidence.reasonCode ?? evidence.cycleReason)
+    ?? parserWarningReason(evidence.parserWarning);
+}
+
+function parserWarningReason(value: unknown): string | undefined {
+  const warning = recordValue(value);
+  const code = stringValue(warning.code);
+  if (code && code !== 'parser_warning') return code;
+  return stringValue(warning.message);
+}
+
+function tiedCandidateRepositoryGroup(
+  evidence: Record<string, unknown>,
+  decision: CompactDecisionInput,
+): CompactDecisionInput['tiedCandidateRepos'] {
+  if (decision.effectiveResolutionStatus !== 'ambiguous'
+    || (decision.candidateCount ?? 0) <= 1) return undefined;
+  const persisted = Array.isArray(evidence.implementationHintSuggestions)
+    ? evidence.implementationHintSuggestions.filter(
+        (value): value is Record<string, unknown> =>
+          Boolean(value && typeof value === 'object' && !Array.isArray(value)),
+      )
+    : [];
+  const projection = persisted.length > 0 ? {
+    suggestions: persisted,
+    suggestionCount: finiteNumber(
+      evidence.implementationHintSuggestionCount,
+    ) ?? persisted.length,
+  } : implementationHintSuggestionProjection(
+    evidence, Number.MAX_SAFE_INTEGER,
+  );
+  const repos = projection.suggestions.flatMap((suggestion) =>
+    typeof suggestion.implementationRepo === 'string'
+      ? [suggestion.implementationRepo] : []);
+  const group = projectCompactReferenceGroup(
+    repos, projection.suggestionCount, isSafeCompactReferenceName,
+  );
+  return group && group.total > 1 ? group : undefined;
+}
+
+function decisionWithTiedCandidates(
+  evidence: Record<string, unknown>,
+  decision: CompactDecisionInput,
+): CompactDecisionInput {
+  const tiedCandidateRepos = tiedCandidateRepositoryGroup(evidence, decision);
+  return tiedCandidateRepos ? { ...decision, tiedCandidateRepos } : decision;
+}

package/src/trace/016-compact-projector.ts

@@ -111,9 +111,8 @@ function decisionInputNode(
     return symbolNode(db, numeric) ?? {};
   if (target.kind === 'handler_method' && numeric !== undefined)
     return handlerNode(db, numeric) ?? {};
-  return {
-    decisionTarget: projectCompactDecisionTarget(target.kind, target.id),
-  };
+  const decisionTarget = projectCompactDecisionTarget(target.kind, target.id);
+  return { key: decisionTarget, decisionTarget, projectedIdentity: true };
 }
 
 function resolveEndpoint(

package/src/trace/019-trace-edge-semantics.ts

@@ -2,6 +2,7 @@ import type { TraceEdge } from '../types.js';
 import type { CompactSemanticEndpoint, CompactStatus } from './014-compact-contract.js';
 import {
   compactDecisionFromEvidence,
+  compactEvidenceReasonCode,
   compactEventStatus,
   compactGraphStatus,
   compactRefs,
@@ -157,11 +158,11 @@ export function recordOutboundObservation(
     source, target,
     status: compactGraphStatus(input.row, input.evidence,
       input.unresolvedReason, input.dynamicMode),
-    decision: compactDecisionFromEvidence(input.evidence, {
-      reasonCode: input.unresolvedReason
-        ? safeReasonCode(input.evidence.reasonCode, 'outbound_target_unresolved')
-        : undefined,
-    }),
+    decision: compactDecisionFromEvidence(input.evidence,
+      input.unresolvedReason ? {
+        reasonCode: compactEvidenceReasonCode(input.evidence)
+          ?? 'outbound_target_unresolved',
+      } : {}),
     refs: compactRefs({
       graphEdgeId: positiveId(input.evidence.persistedGraphEdgeId),
       outboundCallId: input.call.id,
@@ -295,11 +296,6 @@ function eventSite(
     endOffset: plan.transition.callSiteEndOffset });
 }
 
-function safeReasonCode(value: unknown, fallback: string): string {
-  return typeof value === 'string' && /^[a-z][a-z0-9_.-]{0,79}$/.test(value)
-    ? value : fallback;
-}
-
 function positiveId(value: unknown): number | string | undefined {
   if (typeof value === 'number') return Number.isFinite(value) && value > 0
     ? value : undefined;

package/src/trace/020-compact-field-projection.ts

@@ -19,6 +19,9 @@ import type {
 } from './014-compact-contract.js';
 import {
   compactMissingRemediation,
+  isSafeCompactReferenceName,
+  isSafeCompactSelectorSuggestion,
+  projectCompactReferenceGroup,
   projectCompactMissingNames,
   type CompactMissingNameProjection,
 } from './021-compact-decision-normalization.js';
@@ -31,8 +34,19 @@ const compactDiagnosticMessages: Readonly<Record<string, string>> = {
   implementation_hint_mismatch: 'The implementation hint did not select one implementation.',
   selected_handler_provenance_mismatch: 'Selected handler provenance did not match its graph target.',
   selected_handler_target_not_found: 'The selected handler target is not indexed.',
+  trace_start_ambiguous: 'The trace start selector is ambiguous.',
+  trace_start_not_found: 'The trace start selector did not match an indexed start.',
   trace_start_implementation_unresolved: 'The trace start implementation is unresolved.',
 };
+const selectorDiagnosticCodes = new Set([
+  'handler_decorators_not_indexed',
+  'handler_methods_not_indexed',
+  'selector_repo_ambiguous',
+  'selector_repo_not_found',
+  'trace_start_ambiguous',
+  'trace_start_implementation_unresolved',
+  'trace_start_not_found',
+]);
 
 export function projectCompactDecision(
   input: CompactDecisionInput | undefined,
@@ -87,6 +101,8 @@ function addImplementationDecision(
     out.implementationGuided = input.implementationGuided;
   if (input.implementationContextual !== undefined)
     out.implementationContextual = input.implementationContextual;
+  if (input.tiedCandidateRepos)
+    out.tiedCandidateRepos = input.tiedCandidateRepos;
 }
 
 function addEventDecision(out: CompactDecisionV1, input: CompactDecisionInput): void {
@@ -243,6 +259,10 @@ function compactDiagnosticDetails(
   const out: CompactDiagnosticDetailsV1 = {};
   const reasonCode = compactSafeCode(value.reasonCode);
   if (reasonCode) out.reasonCode = reasonCode;
+  if (selectorDiagnosticCodes.has(code)) addDiagnosticSelector(out, value);
+  if (code === 'reindex_required') addInvalidFactCategories(out, value);
+  if (code === 'implementation_hint_mismatch')
+    addImplementationHintCandidates(out, value);
   if (code === 'trace_runtime_variables_missing') addDiagnosticNames(out, value);
   addDiagnosticCounts(out, value);
   const hint = compactDiagnosticRemediation(code, out);
@@ -255,6 +275,51 @@ function compactDiagnosticDetails(
   return out;
 }
 
+function addDiagnosticSelector(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const selectorKind = compactSafeCode(value.selectorKind);
+  if (selectorKind) out.selectorKind = selectorKind;
+  const suggestions = projectCompactReferenceGroup(
+    compactStringArray(value.selectorSuggestions),
+    value.selectorSuggestionCount,
+    isSafeCompactSelectorSuggestion,
+  );
+  if (suggestions) out.selectorSuggestions = suggestions;
+}
+
+function addInvalidFactCategories(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const categories = compactRecordArray(value.invalidFactCategories)
+    .flatMap((item) =>
+      typeof item.category === 'string' ? [item.category] : []);
+  const projection = projectCompactReferenceGroup(
+    categories, value.invalidFactCategoryCount,
+    (item) => compactSafeCode(item) === item,
+  );
+  if (projection) out.invalidFactCategories = projection;
+}
+
+function addImplementationHintCandidates(
+  out: CompactDiagnosticDetailsV1,
+  value: Record<string, unknown>,
+): void {
+  const repos = compactRecordArray(value.implementationHintSuggestions)
+    .flatMap((item) =>
+      typeof item.implementationRepo === 'string'
+        ? [item.implementationRepo] : []);
+  const uniqueCount = new Set(repos.map((repo) => repo.trim())).size;
+  if (uniqueCount < 2) return;
+  const projection = projectCompactReferenceGroup(
+    repos, value.implementationHintSuggestionCount,
+    isSafeCompactReferenceName,
+  );
+  if (projection) out.tiedCandidateRepos = projection;
+}
+
 function addDiagnosticNames(
   out: CompactDiagnosticDetailsV1,
   value: Record<string, unknown>,
@@ -345,7 +410,8 @@ function compactDiagnosticHintCount(
 
 function compactRemediationHint(code: string): string | undefined {
   if (code === 'provide_runtime_variables') return 'Provide the missing variable names listed in details.';
-  if (code === 'select_implementation') return 'Select one implementation with a scoped implementation hint.';
+  if (code === 'select_implementation')
+    return 'Use --implementation-hint with service, operation, package, repository, family, and repo keys; repo is required.';
   if (code === 'reindex_and_link') return 'Force reindex, then force relink the workspace.';
   if (code === 'inspect_detailed_edge') return 'Inspect the correlated detailed trace edge.';
   return undefined;
@@ -389,6 +455,13 @@ function compactStringArray(value: unknown): string[] {
     ? value.filter((item): item is string => typeof item === 'string') : [];
 }
 
+function compactRecordArray(value: unknown): Array<Record<string, unknown>> {
+  return Array.isArray(value)
+    ? value.filter((item): item is Record<string, unknown> =>
+        Boolean(item && typeof item === 'object' && !Array.isArray(item)))
+    : [];
+}
+
 function compactArrayLength(value: unknown): number {
   return Array.isArray(value) ? value.length : 0;
 }