Planner Autonomy: вынести catalog chain matches в контракт

docs/ARCH/11 - architecture_turnaround/20 - planner_autonomy_consolidation_2026-05-01.md

@@ -116,7 +116,7 @@ The following consolidation step added catalog-level chain-template scoring:
 - comparison-shaped value-flow ranks `value_flow_comparison` above the generic value-flow template;
 - ranking-shaped value-flow ranks `value_flow_ranking` above the generic value-flow template;
 - document/movement/inventory/lifecycle templates can now be inspected as catalog search results, not only as local planner branch constants;
-- `assistantMcpDiscoveryPlanner` now records the top catalog chain-template match in reason codes while preserving existing guarded execution behavior.
+- `assistantMcpDiscoveryPlanner` records the top catalog chain-template match in reason codes and exposes the ranked matches as `catalog_chain_template_matches` in the planner contract while preserving existing guarded execution behavior.
 
 ## Why This Matters
 
@@ -198,9 +198,16 @@ Latest validation after catalog chain-template scoring:
 - `npm.cmd run build`: passed
 - graphify rebuild: `5938 nodes`, `12903 edges`, `139 communities`
 
+Latest validation after structured catalog chain-template contract exposure:
+
+- targeted planner tests: passed, `36 passed`
+- full MCP-discovery suite: passed, `282 passed`, `9 skipped`
+- `npm.cmd run build`: passed
+- graphify rebuild: `5939 nodes`, `12906 edges`, `138 communities`
+
 ## Next Step
 
-The next safe step is to re-run live replay once the 1C side is actively polling the proxy, then continue into broader reviewed scoring.
+The next safe step is still to re-run live replay once the 1C side is actively polling the proxy. In parallel, local-only consolidation can continue by making downstream planner/runtime arbitration consume `catalog_chain_template_matches` instead of relying on reason-code strings.
 
 Recommended order:
 

docs/ARCH/11 - architecture_turnaround/README.md

@@ -80,7 +80,7 @@ It now documents a turnaround that is already operational in code, already mater
   - runtime bridge and answer adapter now keep unsupported inventory route templates behind an explicit user-facing boundary instead of letting template planning look like confirmed stock/supplier/purchase/sale evidence;
   - inventory catalog templates now bridge through existing exact inventory recipes (`41.01` scoped stock, supplier overlap, purchase provenance, and sale trace) inside the bounded MCP discovery pilot, while missing selected-item anchors still clarify instead of guessing;
   - unambiguous metadata surfaces can now infer the next reviewed lane from `Document.*`, `Register.*`, or `Catalog.*` objects even before upstream labels `downstream_route_family`, while mixed surfaces still do not guess;
-  - catalog index now scores reviewed chain templates directly from fact/action/axis/comparison/ranking needs, and planner exposes the top catalog chain match in reason codes;
+  - catalog index now scores reviewed chain templates directly from fact/action/axis/comparison/ranking needs, and planner exposes ranked catalog chain matches in both reason codes and the structured `catalog_chain_template_matches` contract field;
   - live map sync: [20 - planner_autonomy_consolidation_2026-05-01.md](./20%20-%20planner_autonomy_consolidation_2026-05-01.md)
 
 Current honest status:
@@ -92,8 +92,8 @@ Current honest status:
 - open-world bounded-autonomy readiness: `~85%`
 - Post-F semantic integrity module progress: `~99%` operationally closed, with remaining risk now treated as next-slice discovery rather than an open blocker inside the closed slice
 - active inventory-stock breadth slice progress: `100%` for the declared scenario pack, not for arbitrary inventory questions
-- Planner Autonomy Consolidation progress: `~80%` for the declared module, with catalog-fabric, value-flow arbitration, lifecycle bounded inference, broad-evaluation bridge, inventory catalog templates, inventory runtime-boundary honesty, exact inventory recipe bridging, unambiguous metadata-surface lane inference, and catalog chain-template scoring validated locally, but live replay for the new bridge is currently blocked by missing active 1C polling and broader unfamiliar 1C asks still need replay-backed growth
-- graph snapshot after latest rebuild: `5938 nodes`, `12903 edges`, `139 communities`
+- Planner Autonomy Consolidation progress: `~81%` for the declared module, with catalog-fabric, value-flow arbitration, lifecycle bounded inference, broad-evaluation bridge, inventory catalog templates, inventory runtime-boundary honesty, exact inventory recipe bridging, unambiguous metadata-surface lane inference, catalog chain-template scoring, and structured chain-match contract exposure validated locally, but live replay for the new bridge is currently blocked by missing active 1C polling and broader unfamiliar 1C asks still need replay-backed growth
+- graph snapshot after latest rebuild: `5939 nodes`, `12906 edges`, `138 communities`
 - current breakpoint:
   - the validated hot paths are no longer structurally broken;
   - flagship continuity collapse is no longer the primary risk;
@@ -139,6 +139,7 @@ Latest live proof now includes:
 - unambiguous metadata-surface lane inference accepted locally: planner slice passed `36/36`; full MCP-discovery slice passed `281/281` with `9` skipped; build passed; graphify rebuilt to `5937 nodes`, `12899 edges`, `138 communities`
 - live inventory exact-bridge rerun `inventory_stock_exact_bridge_live_20260501_after_runtime_bridge` is recorded as infrastructure-blocked, not accepted: route/intent/recipe/capability matched, but MCP calls aborted and direct `get_metadata` timed out while proxy health showed `active_sessions_count=0` with pending commands
 - catalog chain-template scoring accepted locally: catalog/planner slice passed `54/54`; full MCP-discovery slice passed `282/282` with `9` skipped; build passed; graphify rebuilt to `5938 nodes`, `12903 edges`, `139 communities`
+- structured chain-template planner contract accepted locally: planner slice passed `36/36`; full MCP-discovery slice passed `282/282` with `9` skipped; build passed; graphify rebuilt to `5939 nodes`, `12906 edges`, `138 communities`
 
 Current architectural reading:
 

llm_normalizer/backend/dist/services/assistantMcpDiscoveryPlanner.js

@@ -345,6 +345,20 @@ function budgetOverrideFor(input, recipe) {
     }
     return {};
 }
+function catalogChainTemplateMatchesForContract(input, recipe) {
+    const dataNeedGraph = input.dataNeedGraph ?? null;
+    if (!dataNeedGraph) {
+        return [];
+    }
+    return (0, assistantMcpCatalogIndex_1.searchAssistantMcpCatalogChainTemplatesByFactAxis)({
+        business_fact_family: dataNeedGraph.business_fact_family,
+        action_family: toNonEmptyString(input.turnMeaning?.asked_action_family) ?? dataNeedGraph.action_family,
+        required_axes: recipe.axes,
+        comparison_need: dataNeedGraph.comparison_need,
+        ranking_need: dataNeedGraph.ranking_need,
+        aggregation_need: dataNeedGraph.aggregation_need
+    });
+}
 function routeFamilyFromThinMetadataSurfaceInput(input) {
     const surface = input.metadataSurface ?? null;
     const surfaceRouteFamily = routeFamilyFromMetadataSurfaceRef(surface);
@@ -956,6 +970,7 @@ function planAssistantMcpDiscovery(input) {
     const semanticDataNeed = toNonEmptyString(input.semanticDataNeed) ?? recipe.semanticDataNeed;
     const dataNeedGraph = input.dataNeedGraph ?? null;
     const metadataSurface = input.metadataSurface ?? null;
+    const catalogChainTemplateMatches = catalogChainTemplateMatchesForContract(input, recipe);
     const reasonCodes = [];
     pushReason(reasonCodes, recipe.reason);
     for (const reason of recipe.extraReasons ?? []) {
@@ -1018,6 +1033,7 @@ function planAssistantMcpDiscovery(input) {
         metadata_surface_ref: metadataSurface,
         selected_chain_id: recipe.chainId,
         selected_chain_summary: recipe.chainSummary,
+        catalog_chain_template_matches: catalogChainTemplateMatches,
         proposed_primitives: recipe.primitives,
         required_axes: recipe.axes,
         discovery_plan: plan,

llm_normalizer/backend/src/services/assistantMcpDiscoveryPlanner.ts

@@ -70,6 +70,7 @@ export interface AssistantMcpDiscoveryPlannerContract {
   metadata_surface_ref: AssistantMcpDiscoveryMetadataSurfaceRef | null;
   selected_chain_id: AssistantMcpDiscoveryChainId;
   selected_chain_summary: string;
+  catalog_chain_template_matches: AssistantMcpCatalogChainTemplateId[];
   proposed_primitives: AssistantMcpDiscoveryPrimitive[];
   required_axes: string[];
   discovery_plan: AssistantMcpDiscoveryPlanContract;
@@ -536,6 +537,24 @@ function budgetOverrideFor(input: AssistantMcpDiscoveryPlannerInput, recipe: Pla
   return {};
 }
 
+function catalogChainTemplateMatchesForContract(
+  input: AssistantMcpDiscoveryPlannerInput,
+  recipe: PlannerRecipe
+): AssistantMcpCatalogChainTemplateId[] {
+  const dataNeedGraph = input.dataNeedGraph ?? null;
+  if (!dataNeedGraph) {
+    return [];
+  }
+  return searchAssistantMcpCatalogChainTemplatesByFactAxis({
+    business_fact_family: dataNeedGraph.business_fact_family,
+    action_family: toNonEmptyString(input.turnMeaning?.asked_action_family) ?? dataNeedGraph.action_family,
+    required_axes: recipe.axes,
+    comparison_need: dataNeedGraph.comparison_need,
+    ranking_need: dataNeedGraph.ranking_need,
+    aggregation_need: dataNeedGraph.aggregation_need
+  });
+}
+
 function routeFamilyFromThinMetadataSurfaceInput(
   input: AssistantMcpDiscoveryPlannerInput
 ): AssistantMcpDiscoveryMetadataRouteFamily | null {
@@ -1193,6 +1212,7 @@ export function planAssistantMcpDiscovery(
   const semanticDataNeed = toNonEmptyString(input.semanticDataNeed) ?? recipe.semanticDataNeed;
   const dataNeedGraph = input.dataNeedGraph ?? null;
   const metadataSurface = input.metadataSurface ?? null;
+  const catalogChainTemplateMatches = catalogChainTemplateMatchesForContract(input, recipe);
   const reasonCodes: string[] = [];
   pushReason(reasonCodes, recipe.reason);
   for (const reason of recipe.extraReasons ?? []) {
@@ -1259,6 +1279,7 @@ export function planAssistantMcpDiscovery(
     metadata_surface_ref: metadataSurface,
     selected_chain_id: recipe.chainId,
     selected_chain_summary: recipe.chainSummary,
+    catalog_chain_template_matches: catalogChainTemplateMatches,
     proposed_primitives: recipe.primitives,
     required_axes: recipe.axes,
     discovery_plan: plan,

llm_normalizer/backend/tests/assistantMcpDiscoveryPlanner.test.ts

@@ -47,6 +47,7 @@ describe("assistant MCP discovery planner", () => {
     expect(result.catalog_review.review_status).toBe("catalog_compatible");
     expect(result.discovery_plan.answer_may_use_raw_model_claims).toBe(false);
     expect(result.data_need_graph?.business_fact_family).toBe("value_flow");
+    expect(result.catalog_chain_template_matches[0]).toBe("value_flow");
     expect(result.discovery_plan.execution_budget.max_probe_count).toBe(30);
     expect(result.reason_codes).toContain("planner_enabled_chunked_coverage_probe_budget");
     expect(result.reason_codes).toContain("planner_consumed_data_need_graph_v1");
@@ -148,6 +149,7 @@ describe("assistant MCP discovery planner", () => {
     expect(result.reason_codes).toContain("planner_selected_catalog_primitives_from_fact_axis_search");
     expect(result.reason_codes).toContain("planner_instantiated_catalog_chain_template_document_evidence");
     expect(result.reason_codes).toContain("planner_catalog_chain_template_search_top_document_evidence");
+    expect(result.catalog_chain_template_matches[0]).toBe("document_evidence");
     expect(result.reason_codes).not.toContain("planner_fell_back_to_recipe_primitives_after_empty_catalog_search");
   });
 
@@ -637,6 +639,7 @@ describe("assistant MCP discovery planner", () => {
     expect(result.catalog_review.review_status).toBe("catalog_compatible");
     expect(result.reason_codes).toContain("planner_selected_top_ranked_value_flow_from_data_need_graph");
     expect(result.reason_codes).toContain("planner_instantiated_catalog_chain_template_value_flow_ranking");
+    expect(result.catalog_chain_template_matches[0]).toBe("value_flow_ranking");
   });
 
   it("does not collapse incoming-vs-outgoing comparison into entity-resolution when no counterparty is preselected", () => {
@@ -670,6 +673,7 @@ describe("assistant MCP discovery planner", () => {
     expect(result.required_axes).toEqual(["period", "amount", "coverage_target"]);
     expect(result.reason_codes).toContain("planner_selected_bidirectional_value_flow_comparison_from_data_need_graph");
     expect(result.reason_codes).toContain("planner_instantiated_catalog_chain_template_value_flow_comparison");
+    expect(result.catalog_chain_template_matches[0]).toBe("value_flow_comparison");
     expect(result.selected_chain_id).not.toBe("entity_resolution");
   });
 
@@ -942,6 +946,7 @@ describe("assistant MCP discovery planner", () => {
 
     expect(result.planner_status).toBe("needs_clarification");
     expect(result.discovery_plan.plan_status).toBe("needs_clarification");
+    expect(result.catalog_chain_template_matches).toEqual([]);
     expect(result.reason_codes).toContain("planner_needs_more_user_or_scope_context");
   });