opencandle 0.5.0 → 0.7.0

package/src/routing/router.ts

@@ -1,6 +1,9 @@
-import { extractEntities, isAmbiguousConceptUsage } from "./entity-extractor.js";
+import {
+  extractEntities,
+  isAmbiguousConceptUsage,
+  isCurrencyCodeUsage,
+} from "./entity-extractor.js";
 import { classifyWithLegacyRules } from "./legacy-rule-router.js";
-import { buildRouterPrompt } from "./router-prompt.js";
 import {
   computeMissingRequiredSlots,
   isDispatchableWorkflow,
@@ -10,6 +13,7 @@ import {
   routeKindFromLegacyRoute,
   selectToolBundles,
 } from "./route-manifest.js";
+import { buildRouterPrompt } from "./router-prompt.js";
 import type {
   RouterDiagnostic,
   RouterInputContext,
@@ -21,6 +25,7 @@ import type {
   RouterSlot,
   ToolBundleName,
 } from "./router-types.js";
+import { disambiguateSymbols } from "./symbol-disambiguator.js";
 import type { ExtractedEntities, WorkflowType } from "./types.js";
 
 const VALID_ROUTES: readonly RouterRoute[] = ["workflow", "fallback"];
@@ -105,11 +110,19 @@ export function validateRouterOutput(raw: string): RouterOutput {
       : routeKindFromLegacyRoute(route, rawMissingRequired);
 
   if (route === "workflow" || routeKind === "workflow_dispatch") {
-    if (typeof obj.workflow !== "string" || !VALID_WORKFLOWS.includes(obj.workflow as Exclude<WorkflowType, "unclassified">)) {
-      throw new Error(`workflow route requires a valid workflow; got ${JSON.stringify(obj.workflow)}`);
+    if (
+      typeof obj.workflow !== "string" ||
+      !VALID_WORKFLOWS.includes(obj.workflow as Exclude<WorkflowType, "unclassified">)
+    ) {
+      throw new Error(
+        `workflow route requires a valid workflow; got ${JSON.stringify(obj.workflow)}`,
+      );
     }
     workflow = obj.workflow as Exclude<WorkflowType, "unclassified">;
-  } else if (typeof obj.workflow === "string" && VALID_WORKFLOWS.includes(obj.workflow as Exclude<WorkflowType, "unclassified">)) {
+  } else if (
+    typeof obj.workflow === "string" &&
+    VALID_WORKFLOWS.includes(obj.workflow as Exclude<WorkflowType, "unclassified">)
+  ) {
     workflow = obj.workflow as Exclude<WorkflowType, "unclassified">;
   }
 
@@ -119,8 +132,7 @@ export function validateRouterOutput(raw: string): RouterOutput {
   const missing_required = rawMissingRequired;
   const tool_bundles = validateToolBundles(obj.tool_bundles);
   const diagnostics = validateDiagnostics(obj.diagnostics);
-  const reasoning =
-    typeof obj.reasoning === "string" ? obj.reasoning : "";
+  const reasoning = typeof obj.reasoning === "string" ? obj.reasoning : "";
 
   return {
     routeKind,
@@ -156,9 +168,7 @@ function validateEntities(raw: unknown): ExtractedEntities {
     throw new Error("entities must be an object");
   }
   const e = raw as Record<string, unknown>;
-  const symbols = validateStringArray(e.symbols, "entities.symbols").map((s) =>
-    s.toUpperCase(),
-  );
+  const symbols = validateStringArray(e.symbols, "entities.symbols").map((s) => s.toUpperCase());
 
   const out: ExtractedEntities = { symbols };
   if (typeof e.budget === "number") out.budget = e.budget;
@@ -169,10 +179,11 @@ function validateEntities(raw: unknown): ExtractedEntities {
   if (typeof e.riskProfile === "string") out.riskProfile = e.riskProfile;
   if (e.direction === "bullish" || e.direction === "bearish") out.direction = e.direction;
   if (typeof e.dteHint === "string") out.dteHint = e.dteHint;
-  if (e.optionStrategy === "covered_call" || e.optionStrategy === "protective_put") out.optionStrategy = e.optionStrategy;
+  if (e.optionStrategy === "covered_call" || e.optionStrategy === "protective_put")
+    out.optionStrategy = e.optionStrategy;
   if (typeof e.heldSymbol === "string") out.heldSymbol = e.heldSymbol.toUpperCase();
-  const catalystSymbols = validateStringArray(e.catalystSymbols, "entities.catalystSymbols").map((s) =>
-    s.toUpperCase(),
+  const catalystSymbols = validateStringArray(e.catalystSymbols, "entities.catalystSymbols").map(
+    (s) => s.toUpperCase(),
   );
   if (catalystSymbols.length > 0) out.catalystSymbols = catalystSymbols;
   const compareMetrics = validateStringArray(e.compareMetrics, "entities.compareMetrics");
@@ -188,9 +199,7 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
     ...output,
     entities: {
       ...output.entities,
-      symbols: output.entities.symbols.filter((symbol) =>
-        !isAmbiguousConceptUsage(text, symbol),
-      ),
+      symbols: output.entities.symbols.filter((symbol) => !isAmbiguousConceptUsage(text, symbol)),
       budget: output.entities.budget ?? extracted.budget,
       maxPremium: output.entities.maxPremium ?? extracted.maxPremium,
       timeHorizon: output.entities.timeHorizon ?? extracted.timeHorizon,
@@ -203,21 +212,30 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
       shareQuantity: output.entities.shareQuantity ?? extracted.shareQuantity,
       heldSymbol: output.entities.heldSymbol ?? extracted.heldSymbol,
       catalystSymbols: output.entities.catalystSymbols ?? extracted.catalystSymbols,
-      dteHint: output.entities.dteHint ?? (output.workflow === "options_screener" ? extracted.dteHint : undefined),
+      dteHint:
+        output.entities.dteHint ??
+        (output.workflow === "options_screener" ? extracted.dteHint : undefined),
     },
     diagnostics,
   };
 
-  if (next.workflow === "options_screener" && isExistingPositionOptionRequest(text, extracted) && extracted.heldSymbol) {
+  if (
+    next.workflow === "options_screener" &&
+    isExistingPositionOptionRequest(text, extracted) &&
+    extracted.heldSymbol
+  ) {
     const reorderedSymbols = [
       extracted.heldSymbol,
-      ...mergeSymbols(next.entities.symbols, extracted.symbols).filter((symbol) => symbol !== extracted.heldSymbol),
+      ...mergeSymbols(next.entities.symbols, extracted.symbols).filter(
+        (symbol) => symbol !== extracted.heldSymbol,
+      ),
     ];
     if (next.entities.symbols[0] !== extracted.heldSymbol) {
       diagnostics.push({
-        code: extracted.optionStrategy === "protective_put"
-          ? "existing_position_underlying_corrected"
-          : "covered_call_underlying_corrected",
+        code:
+          extracted.optionStrategy === "protective_put"
+            ? "existing_position_underlying_corrected"
+            : "covered_call_underlying_corrected",
         message: `using owned position ${extracted.heldSymbol} as the option-chain underlying`,
       });
     }
@@ -245,7 +263,8 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
   ) {
     diagnostics.push({
       code: "options_workflow_corrected_to_policy_task",
-      message: "options education or suitability prompt should use policy-card synthesis, not contract-screen workflow dispatch",
+      message:
+        "options education or suitability prompt should use policy-card synthesis, not contract-screen workflow dispatch",
     });
     next = {
       ...next,
@@ -278,7 +297,10 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
         timeHorizon: deterministic.entities.timeHorizon ?? extracted.timeHorizon,
         riskProfile: deterministic.entities.riskProfile ?? extracted.riskProfile,
         assetScope: deterministic.entities.assetScope ?? extracted.assetScope,
-        compareMetrics: mergeStringArrays(deterministic.entities.compareMetrics, extracted.compareMetrics),
+        compareMetrics: mergeStringArrays(
+          deterministic.entities.compareMetrics,
+          extracted.compareMetrics,
+        ),
         direction: deterministic.entities.direction ?? extracted.direction,
         costBasis: deterministic.entities.costBasis ?? extracted.costBasis,
         shareQuantity: deterministic.entities.shareQuantity ?? extracted.shareQuantity,
@@ -314,6 +336,30 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
     };
   }
 
+  if (
+    (next.workflow === "compare_assets" || next.workflow === "portfolio_builder") &&
+    isStatefulTrackingRequest(text)
+  ) {
+    diagnostics.push({
+      code: "stateful_tracking_corrected_to_agent_task",
+      message:
+        "portfolio/watchlist tracking mutation should use stateful tracking tools, not compare or construction workflow dispatch",
+    });
+    next = {
+      ...next,
+      routeKind: "agent_task",
+      route: "fallback",
+      workflow: "watchlist_or_tracking",
+      missing_required: [],
+      entities: {
+        ...next.entities,
+        symbols: filterCurrencyUnitSymbols(text, next.entities.symbols),
+      },
+      slots: removeCurrencyUnitSymbolSlots(text, next.slots),
+      diagnostics,
+    };
+  }
+
   if (next.routeKind === "agent_task" && isDispatchableWorkflow(next.workflow)) {
     diagnostics.push({
       code: "dispatchable_workflow_corrected_to_workflow_dispatch",
@@ -349,7 +395,8 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
   if (next.workflow === "compare_assets" && isPortfolioEvaluationRequest(text)) {
     diagnostics.push({
       code: "portfolio_evaluation_corrected_to_agent_task",
-      message: "existing portfolio/allocation risk review should not be reduced to asset comparison",
+      message:
+        "existing portfolio/allocation risk review should not be reduced to asset comparison",
     });
     next = {
       ...next,
@@ -381,7 +428,8 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
   if (next.workflow === "portfolio_builder" && isCryptoSizingRequest(text)) {
     diagnostics.push({
       code: "crypto_sizing_corrected_to_agent_task",
-      message: "crypto allocation-range and drawdown questions are advisory tradeoffs, not portfolio construction",
+      message:
+        "crypto allocation-range and drawdown questions are advisory tradeoffs, not portfolio construction",
     });
     next = {
       ...next,
@@ -396,7 +444,8 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
   if (next.workflow === "portfolio_builder" && isPortfolioEvaluationRequest(text)) {
     diagnostics.push({
       code: "portfolio_evaluation_corrected_to_agent_task",
-      message: "existing portfolio/allocation evaluation does not require portfolio-construction budget",
+      message:
+        "existing portfolio/allocation evaluation does not require portfolio-construction budget",
     });
     next = {
       ...next,
@@ -415,7 +464,8 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
   ) {
     diagnostics.push({
       code: "portfolio_tradeoff_corrected_to_compare_assets",
-      message: "explicit multi-asset tradeoff question should compare the requested assets before constructing a portfolio",
+      message:
+        "explicit multi-asset tradeoff question should compare the requested assets before constructing a portfolio",
     });
     next = {
       ...next,
@@ -427,10 +477,7 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
     };
   }
 
-  if (
-    next.workflow === "single_asset_analysis" &&
-    isSpecializedSingleAssetPolicyRequest(text)
-  ) {
+  if (next.workflow === "single_asset_analysis" && isSpecializedSingleAssetPolicyRequest(text)) {
     diagnostics.push({
       code: "single_asset_workflow_corrected_to_general_policy_task",
       message: "prompt asks for policy-card planning outside a single-asset buy/sell analysis",
@@ -442,6 +489,34 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
     };
   }
 
+  const disambiguated = disambiguateSymbols(next.entities.symbols, text);
+  if (disambiguated.dropped.length > 0) {
+    for (const drop of disambiguated.dropped) {
+      diagnostics.push({
+        code: "symbol_dropped",
+        message: `${drop.token} dropped: ${drop.reason}`,
+        details: {
+          token: drop.token,
+          reason: drop.reason,
+          signalsChecked: drop.signalsChecked,
+          source: "llm",
+        },
+      });
+    }
+    next = {
+      ...next,
+      entities: {
+        ...next.entities,
+        symbols: disambiguated.kept,
+      },
+      slots: removeDroppedSymbolSlots(
+        next.slots,
+        disambiguated.dropped.map((drop) => drop.token),
+      ),
+      diagnostics,
+    };
+  }
+
   const missingRequired = computeMissingRequiredSlots(
     next.workflow,
     next.entities,
@@ -473,7 +548,9 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
       message: "conceptual education prompt does not need live finance tools",
     });
   }
-  const emittedUnsupported = next.tool_bundles.filter((bundle) => !selectedToolBundles.includes(bundle));
+  const emittedUnsupported = next.tool_bundles.filter(
+    (bundle) => !selectedToolBundles.includes(bundle),
+  );
   if (emittedUnsupported.length > 0) {
     diagnostics.push({
       code: "tool_bundles_corrected",
@@ -490,22 +567,34 @@ export function postProcessRouterOutput(text: string, output: RouterOutput): Rou
 }
 
 function isExplicitMacroDataRequest(text: string): boolean {
-  return /\b(?:get_economic_data|fred|cpi|inflation|fed\s+funds?|unemployment|gdp|macro)\b/i.test(text);
+  return /\b(?:get_economic_data|fred|cpi|inflation|fed\s+funds?|unemployment|gdp|macro)\b/i.test(
+    text,
+  );
 }
 
 function isConceptualEducationRequest(text: string, output: RouterOutput): boolean {
   if (output.routeKind !== "agent_task") return false;
   if (output.entities.symbols.length > 0) return false;
   if (isForwardLookingMacroContextRequest(text)) return false;
-  if (/\b(?:current|recent|today|right now|latest|news|sentiment|build|portfolio|buy|sell|allocate|compare)\b/i.test(text)) {
+  if (
+    /\b(?:current|recent|today|right now|latest|news|sentiment|build|portfolio|buy|sell|allocate|compare)\b/i.test(
+      text,
+    )
+  ) {
     return false;
   }
-  return /\b(?:explain|what is|define|how (?:do|should|to)|teach me|help me understand)\b/i.test(text);
+  return /\b(?:explain|what is|define|how (?:do|should|to)|teach me|help me understand)\b/i.test(
+    text,
+  );
 }
 
 function isForwardLookingMacroContextRequest(text: string): boolean {
-  return /\b(?:rates?|rate\s*cuts?|fed|inflation|macro)\b/i.test(text) &&
-    /\b(?:next\s+(?:year|12\s*months?)|over\s+the\s+next|outlook|affect|impact|falling|rising)\b/i.test(text);
+  return (
+    /\b(?:rates?|rate\s*cuts?|fed|inflation|macro)\b/i.test(text) &&
+    /\b(?:next\s+(?:year|12\s*months?)|over\s+the\s+next|outlook|affect|impact|falling|rising)\b/i.test(
+      text,
+    )
+  );
 }
 
 function isCoveredCallRequest(text: string): boolean {
@@ -515,19 +604,75 @@ function isCoveredCallRequest(text: string): boolean {
 function isPortfolioEvaluationRequest(text: string): boolean {
   const lower = text.toLowerCase();
   const hasEvaluationIntent =
-    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|risky|opportunities?|mitigat(?:e|ion)|adjustment|rebalance|diversify|concentration|overweight|underweight|target\s+bands?|drift|worried|crash|protect|protection|missing\s+out\s+on\s+growth)\b/.test(lower);
+    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|risky|opportunities?|mitigat(?:e|ion)|adjustment|rebalance|diversify|concentration|overweight|underweight|target\s+bands?|drift|worried|crash|protect|protection|missing\s+out\s+on\s+growth)\b/.test(
+      lower,
+    );
   const hasPortfolioObject =
-    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(lower);
+    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(
+      lower,
+    );
   const hasConstructionIntent =
     /\b(?:build|create|construct|put\s+together|invest|allocate)\b/.test(lower) &&
-    (/\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower));
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
   return hasEvaluationIntent && hasPortfolioObject && !hasConstructionIntent;
 }
 
+function isStatefulTrackingRequest(text: string): boolean {
+  const lower = text.toLowerCase();
+  const hasPortfolioConstructionIntent =
+    /\b(?:build|create|construct|put\s+together)\b/.test(lower) &&
+    /\bportfolio\b/.test(lower) &&
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
+  const hasStateVerb =
+    /\b(?:add|remove|update|record|track|create|configure|check|show|list|view|cancel)\b/.test(
+      lower,
+    );
+  const hasStateObject =
+    /\b(?:watchlist|portfolio|holding|holdings|position|positions|prediction|predictions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
+      lower,
+    );
+  const hasPortfolioLotShape =
+    /\b(?:add|record|track)\b/.test(lower) &&
+    /\b\d+(?:\.\d+)?\s+shares?\b/.test(lower) &&
+    /\b(?:portfolio|holding|holdings|position|positions)\b/.test(lower);
+  if (hasPortfolioConstructionIntent) return false;
+  return (hasStateVerb && hasStateObject) || hasPortfolioLotShape;
+}
+
+function filterCurrencyUnitSymbols(text: string, symbols: string[]): string[] {
+  return symbols.filter((symbol) => !isCurrencyCodeUsage(text, symbol));
+}
+
+function removeCurrencyUnitSymbolSlots(
+  text: string,
+  slots: Record<string, RouterSlot>,
+): Record<string, RouterSlot> {
+  const next = { ...slots };
+  for (const key of ["symbol", "symbols"]) {
+    const slot = next[key];
+    if (!slot) continue;
+    if (Array.isArray(slot.value)) {
+      const value = slot.value.filter(
+        (item) => typeof item !== "string" || !isCurrencyCodeUsage(text, item.toUpperCase()),
+      );
+      if (value.length === 0) delete next[key];
+      else next[key] = { ...slot, value };
+      continue;
+    }
+    if (typeof slot.value === "string" && isCurrencyCodeUsage(text, slot.value.toUpperCase())) {
+      delete next[key];
+    }
+  }
+  return next;
+}
+
 function isPortfolioTradeoffComparisonRequest(text: string): boolean {
   const lower = text.toLowerCase();
-  return /\b(?:prioritize|tradeoffs?|growth[-\s]?oriented|dividend|income|which\s+(?:one|is)\s+better|should\s+i)\b/.test(lower) &&
-    /\b(?:or|vs\.?|versus|compare)\b/.test(lower);
+  return (
+    /\b(?:prioritize|tradeoffs?|growth[-\s]?oriented|dividend|income|which\s+(?:one|is)\s+better|should\s+i)\b/.test(
+      lower,
+    ) && /\b(?:or|vs\.?|versus|compare)\b/.test(lower)
+  );
 }
 
 function isCryptoSizingRequest(text: string): boolean {
@@ -536,16 +681,20 @@ function isCryptoSizingRequest(text: string): boolean {
     /\b(?:build|create|construct|put\s+together)\b/.test(lower) &&
     /\b(?:portfolio|allocation)\b/.test(lower);
   if (hasPortfolioConstructionIntent) return false;
-  return /\b(?:btc|bitcoin|crypto)\b/.test(lower) &&
-    /\b(?:allocation|range|position\s+size|sizing|exposure|drawdown)\b/.test(lower);
+  return (
+    /\b(?:btc|bitcoin|crypto)\b/.test(lower) &&
+    /\b(?:allocation|range|position\s+size|sizing|exposure|drawdown)\b/.test(lower)
+  );
 }
 
 function isSpecializedSingleAssetPolicyRequest(text: string): boolean {
   const lower = text.toLowerCase();
-  return /\b(?:ticker|symbol|formerly|old ticker|earnings are|earnings tonight)\b/.test(lower) ||
+  return (
+    /\b(?:ticker|symbol|formerly|old ticker|earnings are|earnings tonight)\b/.test(lower) ||
     /\b(?:today|right now|this morning|after close|moved|catalyst)\b/.test(lower) ||
     /\b(?:sentiment|mood|reddit|twitter|x\/twitter)\b/.test(lower) ||
-    /\b(?:filing|10-k|10-q|8-k|sec)\b/.test(lower);
+    /\b(?:filing|10-k|10-q|8-k|sec)\b/.test(lower)
+  );
 }
 
 function isExistingPositionOptionRequest(text: string, extracted: ExtractedEntities): boolean {
@@ -554,14 +703,23 @@ function isExistingPositionOptionRequest(text: string, extracted: ExtractedEntit
 
 function isOptionsEducationOrSuitabilityRequest(text: string): boolean {
   const lower = text.toLowerCase();
-  return /\b(?:how\s+does|how\s+do|explain|what\s+is|good\s+idea|make\s+sense|suitable|suitability|is\s+it\s+(?:good|worth|smart))\b/.test(lower) &&
-    /\b(?:covered\s+calls?|protective\s+puts?|options?|selling\s+calls?|option\s+income)\b/.test(lower);
+  return (
+    /\b(?:how\s+does|how\s+do|explain|what\s+is|good\s+idea|make\s+sense|suitable|suitability|is\s+it\s+(?:good|worth|smart))\b/.test(
+      lower,
+    ) &&
+    /\b(?:covered\s+calls?|protective\s+puts?|options?|selling\s+calls?|option\s+income)\b/.test(
+      lower,
+    )
+  );
 }
 
 function isSpecificOptionContractSelectionRequest(text: string): boolean {
   const lower = text.toLowerCase();
-  return /\b(?:best|which|what\s+(?:strike|contract|option)|rank|screen|specific|right\s+now|today|around\s+earnings|expiration|dte|premium\s+under)\b/.test(lower) &&
-    /\b(?:sell|buy|trade|contract|strike|expiration|premium|call|put)\b/.test(lower);
+  return (
+    /\b(?:best|which|what\s+(?:strike|contract|option)|rank|screen|specific|right\s+now|today|around\s+earnings|expiration|dte|premium\s+under)\b/.test(
+      lower,
+    ) && /\b(?:sell|buy|trade|contract|strike|expiration|premium|call|put)\b/.test(lower)
+  );
 }
 
 function mergeSymbols(primary: string[], secondary: string[]): string[] {
@@ -639,7 +797,9 @@ function validatePreferenceUpdates(raw: unknown): RouterPreferenceUpdate[] {
     // (normalized), but any explicit non-"inferred" value is an invariant
     // violation the caller should see rather than silently lose.
     if (p.source !== undefined && p.source !== "inferred") {
-      throw new Error(`preference_updates[${idx}].source must be "inferred" (got ${JSON.stringify(p.source)})`);
+      throw new Error(
+        `preference_updates[${idx}].source must be "inferred" (got ${JSON.stringify(p.source)})`,
+      );
     }
     return {
       key: p.key,
@@ -655,6 +815,36 @@ function validateToolBundles(raw: unknown): ToolBundleName[] {
   return bundles.filter(isToolBundleName);
 }
 
+function removeDroppedSymbolSlots(
+  slots: Record<string, RouterSlot>,
+  droppedTokens: string[],
+): Record<string, RouterSlot> {
+  if (droppedTokens.length === 0) return slots;
+  const dropped = new Set(droppedTokens.map((token) => token.toUpperCase()));
+  const next = { ...slots };
+
+  for (const key of ["symbol", "symbols"]) {
+    const slot = next[key];
+    if (!slot) continue;
+    if (Array.isArray(slot.value)) {
+      const value = slot.value.filter(
+        (item) => typeof item !== "string" || !dropped.has(item.toUpperCase()),
+      );
+      if (value.length === 0) {
+        delete next[key];
+      } else {
+        next[key] = { ...slot, value };
+      }
+      continue;
+    }
+    if (typeof slot.value === "string" && dropped.has(slot.value.toUpperCase())) {
+      delete next[key];
+    }
+  }
+
+  return next;
+}
+
 function validateDiagnostics(raw: unknown): RouterDiagnostic[] {
   if (raw === undefined || raw === null) return [];
   if (!Array.isArray(raw)) {
@@ -671,10 +861,18 @@ function validateDiagnostics(raw: unknown): RouterDiagnostic[] {
     if (typeof diagnostic.message !== "string") {
       throw new Error(`diagnostics[${idx}].message must be a string`);
     }
-    return {
+    const out: RouterDiagnostic = {
       code: diagnostic.code,
       message: diagnostic.message,
     };
+    if (
+      diagnostic.details &&
+      typeof diagnostic.details === "object" &&
+      !Array.isArray(diagnostic.details)
+    ) {
+      out.details = diagnostic.details as Record<string, unknown>;
+    }
+    return out;
   });
 }
 

package/src/routing/slot-resolver.ts

@@ -1,11 +1,11 @@
+import { OPTIONS_SCREENER_DEFAULTS, PORTFOLIO_DEFAULTS } from "./defaults.js";
 import type {
   ExtractedEntities,
-  PortfolioSlots,
   OptionsScreenerSlots,
+  PortfolioSlots,
   SlotResolution,
   SlotSource,
 } from "./types.js";
-import { PORTFOLIO_DEFAULTS, OPTIONS_SCREENER_DEFAULTS } from "./defaults.js";
 
 interface Preferences {
   riskProfile?: string;
@@ -85,11 +85,19 @@ export function resolvePortfolioSlots(
     sources.budget = "default";
   }
 
-  const risk = resolve(entities.riskProfile, preferences.riskProfile, PORTFOLIO_DEFAULTS.riskProfile);
+  const risk = resolve(
+    entities.riskProfile,
+    preferences.riskProfile,
+    PORTFOLIO_DEFAULTS.riskProfile,
+  );
   sources.riskProfile = risk.source;
   if (risk.source === "default") defaultsUsed.push("riskProfile");
 
-  const horizon = resolve(entities.timeHorizon, preferences.timeHorizon, PORTFOLIO_DEFAULTS.timeHorizon);
+  const horizon = resolve(
+    entities.timeHorizon,
+    preferences.timeHorizon,
+    PORTFOLIO_DEFAULTS.timeHorizon,
+  );
   sources.timeHorizon = horizon.source;
   if (horizon.source === "default") defaultsUsed.push("timeHorizon");
 
@@ -101,7 +109,11 @@ export function resolvePortfolioSlots(
   sources.positionCount = count.source;
   if (count.source === "default") defaultsUsed.push("positionCount");
 
-  const maxPct = resolve(undefined, preferences.maxSinglePositionPct, PORTFOLIO_DEFAULTS.maxSinglePositionPct);
+  const maxPct = resolve(
+    undefined,
+    preferences.maxSinglePositionPct,
+    PORTFOLIO_DEFAULTS.maxSinglePositionPct,
+  );
   sources.maxSinglePositionPct = maxPct.source;
   if (maxPct.source === "default") defaultsUsed.push("maxSinglePositionPct");
 
@@ -140,14 +152,17 @@ export function resolveOptionsScreenerSlots(
   }
 
   // Direction: default to bullish unless the user specified a protective put hedge.
-  const inferredDirection = entities.optionStrategy === "protective_put"
-    ? "bearish"
-    : entities.direction;
+  const inferredDirection =
+    entities.optionStrategy === "protective_put" ? "bearish" : entities.direction;
   const dir = resolve(inferredDirection, undefined, "bullish" as const);
   sources.direction = dir.source;
   if (dir.source === "default") defaultsUsed.push("direction");
 
-  const dte = resolve(mapDteHintToTarget(entities.dteHint), preferences.dteTarget, OPTIONS_SCREENER_DEFAULTS.dteTarget);
+  const dte = resolve(
+    mapDteHintToTarget(entities.dteHint),
+    preferences.dteTarget,
+    OPTIONS_SCREENER_DEFAULTS.dteTarget,
+  );
   sources.dteTarget = dte.source;
   if (dte.source === "default") defaultsUsed.push("dteTarget");
 
@@ -155,11 +170,19 @@ export function resolveOptionsScreenerSlots(
   sources.objective = obj.source;
   if (obj.source === "default") defaultsUsed.push("objective");
 
-  const moneyness = resolve(undefined, preferences.moneynessPreference, OPTIONS_SCREENER_DEFAULTS.moneynessPreference);
+  const moneyness = resolve(
+    undefined,
+    preferences.moneynessPreference,
+    OPTIONS_SCREENER_DEFAULTS.moneynessPreference,
+  );
   sources.moneynessPreference = moneyness.source;
   if (moneyness.source === "default") defaultsUsed.push("moneynessPreference");
 
-  const liquidity = resolve(undefined, preferences.liquidityMinimum, OPTIONS_SCREENER_DEFAULTS.liquidityMinimum);
+  const liquidity = resolve(
+    undefined,
+    preferences.liquidityMinimum,
+    OPTIONS_SCREENER_DEFAULTS.liquidityMinimum,
+  );
   sources.liquidityMinimum = liquidity.source;
   if (liquidity.source === "default") defaultsUsed.push("liquidityMinimum");
 

package/src/routing/symbol-disambiguator.ts

@@ -0,0 +1,72 @@
+export const FINANCE_ACRONYM_DICTIONARY = new Set([
+  "IV",
+  "HV",
+  "ITM",
+  "OTM",
+  "ATM",
+  "IPO",
+  "SEC",
+  "FED",
+  "FOMC",
+  "IRS",
+  "ECB",
+  "BOE",
+  "BOJ",
+  "GDP",
+  "CPI",
+  "PPI",
+  "FX",
+  "NDA",
+]);
+
+export interface DroppedSymbol {
+  token: string;
+  reason: string;
+  signalsChecked: string[];
+}
+
+export interface SymbolDisambiguation {
+  kept: string[];
+  dropped: DroppedSymbol[];
+}
+
+export function disambiguateSymbols(candidates: string[], rawInput: string): SymbolDisambiguation {
+  const kept: string[] = [];
+  const dropped: DroppedSymbol[] = [];
+
+  for (const candidate of candidates) {
+    const token = candidate.toUpperCase();
+    if (!FINANCE_ACRONYM_DICTIONARY.has(token) || hasPositiveTickerSignal(token, rawInput)) {
+      if (!kept.includes(token)) kept.push(token);
+      continue;
+    }
+
+    dropped.push({
+      token,
+      reason: "no positive ticker signal",
+      signalsChecked: ["cashtag", "local ticker phrase"],
+    });
+  }
+
+  return { kept, dropped };
+}
+
+function hasPositiveTickerSignal(token: string, rawInput: string): boolean {
+  return hasCashtag(token, rawInput) || hasLocalTickerPhrase(token, rawInput);
+}
+
+function hasCashtag(token: string, rawInput: string): boolean {
+  return new RegExp(`\\$${escapeRegExp(token)}\\b`, "i").test(rawInput);
+}
+
+function hasLocalTickerPhrase(token: string, rawInput: string): boolean {
+  const escaped = escapeRegExp(token);
+  return new RegExp(
+    `\\b${escaped}\\s+(?:ticker|stock|symbol)\\b|\\b(?:ticker|stock|symbol)\\s+${escaped}\\b`,
+    "i",
+  ).test(rawInput);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}