@saptools/service-flow 0.1.65 → 0.1.66

package/src/linker/004-event-subscription-handler-linker.ts

@@ -0,0 +1,300 @@
+import type { Db } from '../db/connection.js';
+
+export interface SubscriptionHandlerLinkSummary {
+  edgeCount: number;
+  resolvedCount: number;
+  ambiguousCount: number;
+  unresolvedCount: number;
+  missingAssociationCount: number;
+}
+
+interface SubscriptionRow {
+  id: number;
+  workspaceId: number;
+  repoId: number;
+  repoName: string;
+  sourceSymbolId?: number | null;
+  eventName: string;
+  sourceFile: string;
+  sourceLine: number;
+  startOffset?: number | null;
+  endOffset?: number | null;
+  confidence: number;
+}
+
+interface HandlerCallRow {
+  id: number;
+  callerSymbolId: number;
+  calleeSymbolId?: number | null;
+  status: string;
+  unresolvedReason?: string | null;
+  confidence: number;
+  sourceLine: number;
+  factOrigin?: string | null;
+  wrapperFunction?: string | null;
+  strategy?: string | null;
+  candidateCount?: number | null;
+  targetSourceFile?: string | null;
+  targetSourceLine?: number | null;
+  targetWorkspaceId?: number | null;
+}
+
+interface HandlerAssociation {
+  status: 'resolved' | 'ambiguous' | 'unresolved';
+  toKind: 'symbol' | 'symbol_reference' | 'subscription_handler';
+  toId: string;
+  reasonCode?: string;
+  call?: HandlerCallRow;
+  matchCount: number;
+  missing: boolean;
+  factOrigin?: string;
+  symbolCallResolutionStatus?: string;
+}
+
+const symbolCallReasonLimit = 512;
+
+function subscriptionRows(db: Db, workspaceId: number): SubscriptionRow[] {
+  return db.prepare(`SELECT c.id,r.workspace_id workspaceId,c.repo_id repoId,r.name repoName,
+    c.source_symbol_id sourceSymbolId,c.event_name_expr eventName,
+    c.source_file sourceFile,c.source_line sourceLine,
+    c.call_site_start_offset startOffset,c.call_site_end_offset endOffset,
+    c.confidence
+    FROM outbound_calls c JOIN repositories r ON r.id=c.repo_id
+    WHERE r.workspace_id=? AND c.call_type='async_subscribe'
+    ORDER BY r.name COLLATE BINARY,r.id,c.source_file COLLATE BINARY,
+      c.call_site_start_offset,c.call_site_end_offset,c.id`).all(
+    workspaceId,
+  ) as unknown as SubscriptionRow[];
+}
+
+function roleSiteRows(db: Db, subscription: SubscriptionRow): HandlerCallRow[] {
+  if (typeof subscription.startOffset !== 'number'
+    || typeof subscription.endOffset !== 'number') return [];
+  return db.prepare(`SELECT sc.id,sc.caller_symbol_id callerSymbolId,
+    sc.callee_symbol_id calleeSymbolId,sc.status,
+    sc.unresolved_reason unresolvedReason,sc.confidence,sc.source_line sourceLine,
+    json_extract(sc.evidence_json,'$.factOrigin') factOrigin,
+    json_extract(sc.evidence_json,'$.wrapperFunction') wrapperFunction,
+    json_extract(sc.evidence_json,'$.candidateStrategy') strategy,
+    json_extract(sc.evidence_json,'$.candidateCount') candidateCount,
+    target.source_file targetSourceFile,target.start_line targetSourceLine,
+    target_repo.workspace_id targetWorkspaceId
+    FROM symbol_calls sc LEFT JOIN symbols target ON target.id=sc.callee_symbol_id
+    LEFT JOIN repositories target_repo ON target_repo.id=target.repo_id
+    WHERE sc.repo_id=? AND sc.source_file=?
+      AND sc.call_site_start_offset=? AND sc.call_site_end_offset=?
+      AND sc.call_role='event_subscribe_handler'
+    ORDER BY sc.id`).all(
+    subscription.repoId,
+    subscription.sourceFile,
+    subscription.startOffset,
+    subscription.endOffset,
+  ) as unknown as HandlerCallRow[];
+}
+
+function invalidSpan(subscription: SubscriptionRow): boolean {
+  return typeof subscription.startOffset !== 'number'
+    || typeof subscription.endOffset !== 'number'
+    || subscription.startOffset < 0
+    || subscription.endOffset <= subscription.startOffset;
+}
+
+function associationFor(
+  subscription: SubscriptionRow,
+  matches: HandlerCallRow[],
+): HandlerAssociation {
+  if (invalidSpan(subscription)) return missingAssociation(
+    subscription.id, matches.length, 'subscription_call_span_missing',
+  );
+  if (matches.length === 0) return missingAssociation(
+    subscription.id, 0, 'subscription_handler_role_site_missing',
+  );
+  if (matches.length > 1) return ambiguousRoleSiteAssociation(
+    subscription.id, matches,
+  );
+  const call = matches[0];
+  return call
+    ? singleCallAssociation(subscription, call)
+    : missingAssociation(
+      subscription.id, 0, 'subscription_handler_role_site_missing',
+    );
+}
+
+function ambiguousRoleSiteAssociation(
+  subscriptionId: number,
+  matches: HandlerCallRow[],
+): HandlerAssociation {
+  return {
+    status: 'ambiguous', toKind: 'subscription_handler',
+    toId: String(subscriptionId), reasonCode: 'multiple_handler_role_site_matches',
+    matchCount: matches.length, missing: false,
+    factOrigin: agreedOrMixed(matches.map((match) => match.factOrigin)),
+    symbolCallResolutionStatus: agreedOrMixed(
+      matches.map((match) => match.status),
+    ),
+  };
+}
+
+function singleCallAssociation(
+  subscription: SubscriptionRow,
+  call: HandlerCallRow,
+): HandlerAssociation {
+  const mismatch = associationMismatch(subscription, call);
+  if (mismatch) return missingAssociation(subscription.id, 1, mismatch, call);
+  return handlerReferenceAssociation(call);
+}
+
+function associationMismatch(
+  subscription: SubscriptionRow,
+  call: HandlerCallRow,
+): string | undefined {
+  if (subscription.sourceSymbolId != null
+    && call.callerSymbolId !== subscription.sourceSymbolId)
+    return 'subscription_handler_caller_mismatch';
+  if (call.sourceLine !== subscription.sourceLine)
+    return 'subscription_handler_source_line_mismatch';
+  if (call.targetWorkspaceId != null
+    && call.targetWorkspaceId !== subscription.workspaceId)
+    return 'subscription_handler_target_workspace_mismatch';
+  return undefined;
+}
+
+function handlerReferenceAssociation(call: HandlerCallRow): HandlerAssociation {
+  if (call.status === 'resolved' && typeof call.calleeSymbolId === 'number')
+    return { status: 'resolved', toKind: 'symbol', toId: String(call.calleeSymbolId), call, matchCount: 1, missing: false };
+  if (call.status === 'ambiguous') return {
+    status: 'ambiguous', toKind: 'symbol_reference', toId: String(call.id),
+    reasonCode: 'subscription_handler_reference_ambiguous', call,
+    matchCount: 1, missing: false,
+  };
+  return {
+    status: 'unresolved', toKind: 'symbol_reference', toId: String(call.id),
+    reasonCode: call.status === 'resolved'
+      ? 'resolved_handler_symbol_missing'
+      : 'subscription_handler_reference_unresolved',
+    call, matchCount: 1, missing: false,
+  };
+}
+
+function agreedOrMixed(
+  values: Array<string | null | undefined>,
+): string | undefined {
+  const distinct = new Set(values.map((value) => value ?? 'missing'));
+  if (distinct.size > 1) return 'mixed';
+  const value = distinct.values().next().value;
+  return value === 'missing' ? undefined : value;
+}
+
+function missingAssociation(
+  subscriptionId: number,
+  matchCount: number,
+  reasonCode: string,
+  call?: HandlerCallRow,
+): HandlerAssociation {
+  return {
+    status: 'unresolved', toKind: 'subscription_handler',
+    toId: String(subscriptionId), reasonCode, call, matchCount, missing: true,
+  };
+}
+
+function evidenceFor(
+  subscription: SubscriptionRow,
+  association: HandlerAssociation,
+): Record<string, unknown> {
+  const call: Partial<HandlerCallRow> = association.call ?? {};
+  const symbolCallReason = boundedSymbolCallReason(call.unresolvedReason);
+  return {
+    eventName: subscription.eventName,
+    associationBasis: 'exact_subscription_call_span',
+    dispatchScope: 'workspace_event_name_only',
+    subscribeCallId: subscription.id,
+    symbolCallId: call.id,
+    roleSiteMatchCount: association.matchCount,
+    callRole: association.matchCount > 0 ? 'event_subscribe_handler' : undefined,
+    factOrigin: association.factOrigin ?? call.factOrigin,
+    repositoryId: subscription.repoId,
+    repositoryName: subscription.repoName,
+    sourceFile: subscription.sourceFile,
+    sourceLine: subscription.sourceLine,
+    callSiteStartOffset: subscription.startOffset,
+    callSiteEndOffset: subscription.endOffset,
+    handlerSymbolId: call.calleeSymbolId,
+    handlerSourceFile: call.targetSourceFile,
+    handlerSourceLine: call.targetSourceLine,
+    wrapperFunction: call.wrapperFunction,
+    associationStatus: association.status,
+    symbolCallResolutionStatus:
+      association.symbolCallResolutionStatus ?? call.status,
+    resolutionStatus: association.status,
+    resolutionStrategy: call.strategy,
+    candidateCount: call.candidateCount,
+    reasonCode: association.reasonCode,
+    ...symbolCallReason,
+  };
+}
+
+function boundedSymbolCallReason(
+  reason: string | null | undefined,
+): Record<string, unknown> {
+  if (!reason) return {};
+  const value = reason.slice(0, symbolCallReasonLimit);
+  return {
+    symbolCallUnresolvedReason: value,
+    omittedSymbolCallUnresolvedReasonCharacterCount:
+      Math.max(0, reason.length - value.length),
+  };
+}
+
+function insertAssociationEdge(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+  subscription: SubscriptionRow,
+  association: HandlerAssociation,
+): void {
+  db.prepare(`INSERT INTO graph_edges(
+    workspace_id,edge_type,status,from_kind,from_id,to_kind,to_id,
+    confidence,evidence_json,is_dynamic,unresolved_reason,generation
+  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`).run(
+    workspaceId,
+    'EVENT_SUBSCRIPTION_HANDLED_BY',
+    association.status,
+    'event',
+    subscription.eventName,
+    association.toKind,
+    association.toId,
+    association.call?.confidence ?? subscription.confidence,
+    JSON.stringify(evidenceFor(subscription, association)),
+    0,
+    association.reasonCode ?? association.call?.unresolvedReason ?? null,
+    generation,
+  );
+}
+
+export function linkEventSubscriptionHandlers(
+  db: Db,
+  workspaceId: number,
+  generation: number,
+): SubscriptionHandlerLinkSummary {
+  const summary: SubscriptionHandlerLinkSummary = {
+    edgeCount: 0,
+    resolvedCount: 0,
+    ambiguousCount: 0,
+    unresolvedCount: 0,
+    missingAssociationCount: 0,
+  };
+  for (const subscription of subscriptionRows(db, workspaceId)) {
+    const association = associationFor(
+      subscription, roleSiteRows(db, subscription),
+    );
+    insertAssociationEdge(
+      db, workspaceId, generation, subscription, association,
+    );
+    summary.edgeCount += 1;
+    summary.resolvedCount += association.status === 'resolved' ? 1 : 0;
+    summary.ambiguousCount += association.status === 'ambiguous' ? 1 : 0;
+    summary.unresolvedCount += association.status === 'unresolved' ? 1 : 0;
+    summary.missingAssociationCount += association.missing ? 1 : 0;
+  }
+  return summary;
+}

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

@@ -13,6 +13,8 @@ import {
   objectValue,
 } from './002-call-evidence.js';
 import { linkPackageImportSymbolCalls } from './003-package-import-symbol-resolver.js';
+import { linkEventSubscriptionHandlers } from './004-event-subscription-handler-linker.js';
+import { assertWorkspaceLinkable } from '../db/001-fact-lifecycle.js';
 export interface LinkWorkspaceResult {
   edgeCount: number;
   unresolvedCount: number;
@@ -27,24 +29,43 @@ export interface LinkWorkspaceResult {
   implementationResolvedCount: number;
   implementationAmbiguousCount: number;
   implementationUnresolvedCount: number;
+  subscriptionHandlerResolvedCount: number;
+  subscriptionHandlerAmbiguousCount: number;
+  subscriptionHandlerUnresolvedCount: number;
+  subscriptionHandlerMissingAssociationCount: number;
 }
 export function linkWorkspace(db: Db, workspaceId: number, vars: Record<string, string> = {}): LinkWorkspaceResult {
   return db.transaction(() => {
+    assertWorkspaceLinkable(db, workspaceId);
     const generation = nextGraphGeneration(db, workspaceId);
     db.prepare('DELETE FROM graph_edges WHERE workspace_id=?').run(workspaceId);
     const deps = linkHelperPackages(db, workspaceId, generation);
     linkPackageImportSymbolCalls(db, workspaceId);
+    const subscriptions = linkEventSubscriptionHandlers(
+      db, workspaceId, generation,
+    );
     const impl = linkCanonicalImplementations(db, workspaceId, generation);
     const callSummary = linkCalls(db, workspaceId, vars, generation);
     db.prepare("UPDATE repositories SET graph_generation=?, graph_stale_reason=NULL, graph_stale_at=NULL WHERE workspace_id=?").run(generation, workspaceId);
-    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount, implementationUnresolvedCount: impl.unresolvedCount };
+    return { ...callSummary, edgeCount: deps.edgeCount + callSummary.edgeCount + impl.edgeCount + subscriptions.edgeCount, dependencyResolvedCount: deps.resolvedCount, dependencyAmbiguousCount: deps.ambiguousCount, implementationResolvedCount: impl.resolvedCount, implementationAmbiguousCount: impl.ambiguousCount, implementationUnresolvedCount: impl.unresolvedCount, subscriptionHandlerResolvedCount: subscriptions.resolvedCount, subscriptionHandlerAmbiguousCount: subscriptions.ambiguousCount, subscriptionHandlerUnresolvedCount: subscriptions.unresolvedCount, subscriptionHandlerMissingAssociationCount: subscriptions.missingAssociationCount };
   });
 }
 function nextGraphGeneration(db: Db, workspaceId: number): number {
   const row = db.prepare('SELECT COALESCE(MAX(graph_generation),0) generation FROM repositories WHERE workspace_id=?').get(workspaceId) as { generation?: number } | undefined;
   return Number(row?.generation ?? 0) + 1;
 }
-function linkCalls(db: Db, workspaceId: number, vars: Record<string, string>, generation: number): Omit<LinkWorkspaceResult, 'dependencyResolvedCount' | 'dependencyAmbiguousCount' | 'implementationResolvedCount' | 'implementationAmbiguousCount' | 'implementationUnresolvedCount'> {
+type CallLinkSummary = Omit<LinkWorkspaceResult,
+  | 'dependencyResolvedCount'
+  | 'dependencyAmbiguousCount'
+  | 'implementationResolvedCount'
+  | 'implementationAmbiguousCount'
+  | 'implementationUnresolvedCount'
+  | 'subscriptionHandlerResolvedCount'
+  | 'subscriptionHandlerAmbiguousCount'
+  | 'subscriptionHandlerUnresolvedCount'
+  | 'subscriptionHandlerMissingAssociationCount'>;
+
+function linkCalls(db: Db, workspaceId: number, vars: Record<string, string>, generation: number): CallLinkSummary {
   let edgeCount = 0;
   let unresolvedCount = 0;
   let resolvedCount = 0;

package/src/output/001-compact-json-output.ts

@@ -0,0 +1,6 @@
+import type { CompactGraphV1 } from '../trace/014-compact-contract.js';
+import { redactValue } from '../utils/redaction.js';
+
+export function renderCompactJson(value: CompactGraphV1): string {
+  return `${JSON.stringify(redactValue(value))}\n`;
+}

package/src/parsers/imported-wrapper-parser.ts

@@ -168,10 +168,14 @@ function wrapperCallFact(
     payloadSummary: call.getText(source),
     sourceFile: normalizePath(filePath),
     sourceLine: lineOf(source, call),
+    callSiteStartOffset: call.getStart(source),
+    callSiteEndOffset: call.getEnd(),
     confidence: operationPathExpr ? 0.85 : 0.5,
     unresolvedReason,
     evidence: {
       parser: 'typescript_ast',
+      startOffset: call.getStart(source),
+      endOffset: call.getEnd(),
       classifier: importedWrapperClassifier(pathAnalysis.status),
       receiver: client.text,
       wrapperFunction: spec.chain[0],

package/src/parsers/outbound-call-parser.ts

@@ -348,7 +348,15 @@ export function classifyOutboundCallsInSource(source: ts.SourceFile, filePath: s
   const wrapperSpecs = collectWrapperSpecs(source);
   const wrapperInternalRanges = [...wrapperSpecs.values()].map((spec) => ({ start: spec.internalStart, end: spec.internalEnd }));
   const add = (node: ts.CallExpression, fact: Omit<OutboundCallFact, 'sourceFile' | 'sourceLine' | 'confidence'> & { confidence?: number }, extra?: Record<string, unknown>): void => {
-    calls.push({ node, fact: { ...fact, sourceFile, sourceLine: lineOf(source.text, node.getStart(source)), confidence: fact.confidence ?? 0.8, evidence: parserEvidence(source, node, extra) } });
+    calls.push({ node, fact: {
+      ...fact,
+      sourceFile,
+      sourceLine: lineOf(source.text, node.getStart(source)),
+      callSiteStartOffset: node.getStart(source),
+      callSiteEndOffset: node.getEnd(),
+      confidence: fact.confidence ?? 0.8,
+      evidence: parserEvidence(source, node, extra),
+    } });
   };
   const visit = (node: ts.Node): void => {
     if (ts.isCallExpression(node)) {
@@ -505,6 +513,8 @@ function parseLocalServiceCalls(
         aliasChain: parsed.chain,
         sourceFile: normalizePath(filePath),
         sourceLine: lineOf(text, node.getStart(source)),
+        callSiteStartOffset: node.getStart(source),
+        callSiteEndOffset: node.getEnd(),
         confidence: 0.9,
         unresolvedReason: ['send', 'emit', 'publish', 'on'].includes(parsed.operation) ? 'transport_client_method' : undefined,
         evidence: parserEvidence(source, node, {

package/src/parsers/symbol-parser.ts

@@ -261,7 +261,7 @@ export async function parseExecutableSymbols(
   const eventSubscriptionOffsets = new Set(
     classifyOutboundCallsInSource(source, sourceFile)
       .filter((call) => call.fact.callType === 'async_subscribe')
-      .map((call) => call.node.getStart(source)),
+      .map((call) => `${call.node.getStart(source)}:${call.node.getEnd()}`),
   );
   const exportNames = exportDeclarations(source);
   const objectExports = new Set<string>();
@@ -383,7 +383,7 @@ export async function parseExecutableSymbols(
         const name = `event:${eventName}:${startLine}`;
         symbols.push({ kind: 'event_registration', localName: name, qualifiedName: `module:${sourceFile}#${name}`, sourceFile, startLine, endLine: lineOf(source, node.getEnd()), startOffset: node.getStart(source), endOffset: node.getEnd(), exported: false, importExportEvidence: { source: 'synthetic_event_registration', eventName: eventArg.text, registrationLine: startLine, receiver } });
       }
-      if (eventSubscriptionOffsets.has(node.getStart(source))) {
+      if (eventSubscriptionOffsets.has(`${node.getStart(source)}:${node.getEnd()}`)) {
         const startLine = lineOf(source, node.getStart(source));
         const handlerArgument = node.arguments[1];
         const target = handlerArgument
@@ -399,6 +399,9 @@ export async function parseExecutableSymbols(
           importSource: target.importSource,
           sourceFile,
           sourceLine: startLine,
+          callSiteStartOffset: node.getStart(source),
+          callSiteEndOffset: node.getEnd(),
+          callRole: 'event_subscribe_handler',
           evidence: {
             relation: target.relation,
             caller: anchor.qualifiedName,
@@ -406,7 +409,7 @@ export async function parseExecutableSymbols(
             ...(target.wrapperFunction
               ? { wrapperFunction: target.wrapperFunction }
               : {}),
-            candidateStrategy: 'event_subscribe_handler_reference',
+            factOrigin: 'event_subscribe_handler_reference',
           },
         });
       }
@@ -464,7 +467,7 @@ export async function parseExecutableSymbols(
         const ignored = loggerLike || terminalMember || ignoredFrameworkCall(callee);
         const resolvedTarget = provenThisMethod ? thisTarget : targetName;
         const keep = Boolean(resolvedTarget) && !ignored && (provenLocal || provenThisMethod || provenRelativeImport || provenClassInstance || provenPackageImport);
-        if (keep) calls.push({ callerQualifiedName: caller.qualifiedName, calleeExpression: callee.expression, calleeLocalName: resolvedTarget, receiverLocalName: callee.member ? (callee.local ?? callee.receiver) : undefined, importSource, sourceFile, sourceLine: line, evidence: { relation: instance ? 'class_instance_method' : proxy ? 'relative_import_proxy_member' : packageImport ? 'package_import' : namespaceMember ? 'relative_import_namespace_member' : importSource ? 'relative_import' : provenThisMethod ? 'indexed_this_method' : 'indexed_local_symbol', caller: caller.qualifiedName, targetName: resolvedTarget, instanceVariable: instance ? (instance.propertyName ?? callee.local) : undefined, className: instance?.className, methodName: instance ? callee.member : undefined, classImportSource: instance?.importSource, callArguments: argumentEvidence(node.arguments, source), proxyVariableName: proxy?.variableName, factory: proxy?.factory, factoryExpression: proxy?.factory, factoryImportSource: proxy?.importSource, candidateStrategy: instance ? (instance.importSource ? 'relative_import_class_instance_method' : 'same_file_class_instance_method') : proxy ? 'proxy_member_exact_export_or_unique_member' : undefined } });
+        if (keep) calls.push({ callerQualifiedName: caller.qualifiedName, calleeExpression: callee.expression, calleeLocalName: resolvedTarget, receiverLocalName: callee.member ? (callee.local ?? callee.receiver) : undefined, importSource, sourceFile, sourceLine: line, callSiteStartOffset: node.getStart(source), callSiteEndOffset: node.getEnd(), callRole: 'ordinary_call', evidence: { relation: instance ? 'class_instance_method' : proxy ? 'relative_import_proxy_member' : packageImport ? 'package_import' : namespaceMember ? 'relative_import_namespace_member' : importSource ? 'relative_import' : provenThisMethod ? 'indexed_this_method' : 'indexed_local_symbol', caller: caller.qualifiedName, targetName: resolvedTarget, instanceVariable: instance ? (instance.propertyName ?? callee.local) : undefined, className: instance?.className, methodName: instance ? callee.member : undefined, classImportSource: instance?.importSource, callArguments: argumentEvidence(node.arguments, source), proxyVariableName: proxy?.variableName, factory: proxy?.factory, factoryExpression: proxy?.factory, factoryImportSource: proxy?.importSource, candidateStrategy: instance ? (instance.importSource ? 'relative_import_class_instance_method' : 'same_file_class_instance_method') : proxy ? 'proxy_member_exact_export_or_unique_member' : undefined } });
       }
     }
     ts.forEachChild(node, visitCalls);

package/src/trace/010-traversal-scope.ts

@@ -0,0 +1,188 @@
+import { createHash } from 'node:crypto';
+import type { Db } from '../db/connection.js';
+import type { ContextBinding } from './008-contextual-runtime-state.js';
+
+export interface TraversalScopeIdentity {
+  workspaceId?: number;
+  repoId?: number;
+  files?: ReadonlySet<string>;
+  symbolIds?: ReadonlySet<number>;
+  context?: ReadonlyMap<string, ContextBinding>;
+}
+
+export interface TraversalScopeState {
+  structuralKey: string;
+  evaluationKey: string;
+  ancestry: ReadonlySet<string>;
+}
+
+export type TraversalScheduleKind = 'scheduled' | 'converged' | 'cycle';
+
+export interface TraversalScheduleDecision {
+  kind: TraversalScheduleKind;
+  state: TraversalScopeState;
+  alreadyExpanded: boolean;
+}
+
+export function compareBinary(left: string, right: string): number {
+  const leftPoints = [...left];
+  const rightPoints = [...right];
+  const length = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPoint = leftPoints[index]?.codePointAt(0) ?? 0;
+    const rightPoint = rightPoints[index]?.codePointAt(0) ?? 0;
+    if (leftPoint !== rightPoint) return leftPoint < rightPoint ? -1 : 1;
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+export function resolveTraversalWorkspaceId(
+  db: Db,
+  requestedWorkspaceId: number | undefined,
+  repoId: number | undefined,
+): number | undefined {
+  if (requestedWorkspaceId !== undefined) return requestedWorkspaceId;
+  if (repoId !== undefined) {
+    const row = db.prepare(
+      'SELECT workspace_id workspaceId FROM repositories WHERE id=?',
+    ).get(repoId) as { workspaceId?: number } | undefined;
+    return typeof row?.workspaceId === 'number' ? row.workspaceId : undefined;
+  }
+  const rows = db.prepare(`SELECT DISTINCT w.id workspaceId FROM workspaces w
+    JOIN repositories r ON r.workspace_id=w.id ORDER BY w.id LIMIT 2`).all() as
+    Array<{ workspaceId?: number }>;
+  return rows.length === 1 && typeof rows[0]?.workspaceId === 'number'
+    ? rows[0].workspaceId : undefined;
+}
+
+export function structuralScopeKey(
+  workspaceId: number | undefined,
+  repoId: number | undefined,
+  files: ReadonlySet<string> | undefined,
+  symbolIds: ReadonlySet<number> | undefined,
+): string {
+  return JSON.stringify([
+    workspaceId ?? null,
+    repoId ?? null,
+    files ? [...files].sort(compareBinary) : null,
+    symbolIds ? [...symbolIds].sort((left, right) => left - right) : null,
+  ]);
+}
+
+export function canonicalContextFingerprint(
+  context: ReadonlyMap<string, ContextBinding> | undefined,
+): string {
+  const entries = [...(context ?? new Map<string, ContextBinding>()).entries()]
+    .map(([name, binding]) => `${JSON.stringify(name)}:${canonicalValue(binding)}`)
+    .sort(compareBinary);
+  return createHash('sha256').update(`[${entries.join(',')}]`).digest('hex');
+}
+
+export function evaluationScopeKey(
+  structuralKey: string,
+  context: ReadonlyMap<string, ContextBinding> | undefined,
+): string {
+  return JSON.stringify([structuralKey, canonicalContextFingerprint(context)]);
+}
+
+export class TraversalScopeScheduler {
+  readonly #scheduled = new Set<string>();
+  readonly #expanded = new Set<string>();
+  readonly #structuralByEvaluation = new Map<string, string>();
+  readonly #childrenByEvaluation = new Map<string, Set<string>>();
+
+  schedule(
+    identity: TraversalScopeIdentity,
+    parent?: TraversalScopeState,
+  ): TraversalScheduleDecision {
+    const state = scopeState(identity, parent);
+    this.#rememberState(state);
+    if (parent) this.#rememberState(parent);
+    const cycle = parent
+      ? parent.ancestry.has(state.structuralKey)
+        || this.#reachesStructural(state.evaluationKey, parent.structuralKey)
+      : false;
+    if (parent) this.#recordEdge(parent.evaluationKey, state.evaluationKey);
+    if (cycle)
+      return { kind: 'cycle', state, alreadyExpanded: this.#expanded.has(state.evaluationKey) };
+    if (this.#scheduled.has(state.evaluationKey))
+      return { kind: 'converged', state, alreadyExpanded: this.#expanded.has(state.evaluationKey) };
+    this.#scheduled.add(state.evaluationKey);
+    return { kind: 'scheduled', state, alreadyExpanded: false };
+  }
+
+  markExpanded(state: TraversalScopeState): boolean {
+    if (this.#expanded.has(state.evaluationKey)) return false;
+    this.#expanded.add(state.evaluationKey);
+    return true;
+  }
+
+  #rememberState(state: TraversalScopeState): void {
+    this.#structuralByEvaluation.set(state.evaluationKey, state.structuralKey);
+  }
+
+  #recordEdge(parent: string, child: string): void {
+    const children = this.#childrenByEvaluation.get(parent) ?? new Set<string>();
+    children.add(child);
+    this.#childrenByEvaluation.set(parent, children);
+  }
+
+  #reachesStructural(start: string, targetStructuralKey: string): boolean {
+    const pending = [start];
+    const seen = new Set<string>();
+    let cursor = 0;
+    while (cursor < pending.length) {
+      const current = pending[cursor];
+      cursor += 1;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      if (this.#structuralByEvaluation.get(current) === targetStructuralKey)
+        return true;
+      pending.push(...(this.#childrenByEvaluation.get(current) ?? []));
+    }
+    return false;
+  }
+}
+
+function scopeState(
+  identity: TraversalScopeIdentity,
+  parent: TraversalScopeState | undefined,
+): TraversalScopeState {
+  const structuralKey = structuralScopeKey(
+    identity.workspaceId, identity.repoId, identity.files, identity.symbolIds,
+  );
+  const ancestry = new Set(parent?.ancestry ?? []);
+  ancestry.add(structuralKey);
+  return {
+    structuralKey,
+    evaluationKey: evaluationScopeKey(structuralKey, identity.context),
+    ancestry,
+  };
+}
+
+function canonicalValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (typeof value === 'string') return `string:${JSON.stringify(value)}`;
+  if (typeof value === 'boolean') return `boolean:${String(value)}`;
+  if (typeof value === 'number') return canonicalNumber(value);
+  if (typeof value === 'bigint') return `bigint:${String(value)}`;
+  if (Array.isArray(value))
+    return `array:[${value.map(canonicalValue).join(',')}]`;
+  if (!isRecord(value)) return `unsupported:${typeof value}`;
+  const entries = Object.entries(value).sort(([left], [right]) => compareBinary(left, right));
+  return `object:{${entries.map(([key, child]) =>
+    `${JSON.stringify(key)}:${canonicalValue(child)}`).join(',')}}`;
+}
+
+function canonicalNumber(value: number): string {
+  if (Number.isNaN(value)) return 'number:NaN';
+  if (value === Number.POSITIVE_INFINITY) return 'number:Infinity';
+  if (value === Number.NEGATIVE_INFINITY) return 'number:-Infinity';
+  if (Object.is(value, -0)) return 'number:-0';
+  return `number:${String(value)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}