Developer Guide

This page is the implementation map for consumers building on the current v2 line. It covers the real runtime pipeline as it exists now, not the smaller 2.0.0 launch-era mental model.

Current 27-Step Runtime Pipeline

Click each step to inspect the current v2 pipeline order.

Execution Steps

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Step Detail

McpToolStep

MCP

Runs the planner-driven MCP loop and semantic query runtime tool chain when needed.

fileengine/steps/McpToolStep.java

methodexecute(...)

Session Snapshot

• context.mcp.*

Tables Touched

• ce_mcp_tool
• ce_mcp_planner
• ce_audit

Current repo scope

This guide reflects the active v2 line through the later additions from 2.0.6 to 2.0.9, including cache diagnostics, scoped MCP planner flow, ce_verbose, CorrectionStep, and Semantic Query.

Build order for a new flow

1. Define ce_intent, ce_intent_classifier, ce_prompt_template, ce_response, and ce_rule.
2. Add ce_output_schema if the flow needs structured collection or correction.
3. Add ce_pending_action only if the flow needs explicit confirm-before-run behavior.
4. Add ce_mcp_tool and ce_mcp_planner only after the base conversational path is deterministic.
5. Add ce_verbose early enough that QA and operators can see runtime progress.
6. Configure convengine.flow.*, convengine.audit.*, and the MCP namespaces in YAML.
7. Replay test and audit-trace test before production rollout.

Version-line implementation guidance (2.0.0 to 2.0.9)

What changed by version line

Version line	What changed	What developers should do differently
2.0.0	Core table-driven engine, pending actions, tool orchestration, memory, state graph, replay foundations.	Start with a deterministic ce_* config model instead of custom controller branching.
2.0.6	Cache reliability and diagnostics improved.	Treat cache health and refresh tooling as part of your production operational model.
2.0.7	Scoped MCP planner flow, stricter tool/planner scope validation, richer MCP lifecycle metadata.	Design tools by explicit intent/state scope and test blocked-next-tool branches.
2.0.8	ce_verbose, stream verbose transport, step telemetry, stronger MCP schema completeness behavior.	Seed verbose rows early and use audit + verbose together in QA.
2.0.9	CorrectionStep, interaction semantics in prompt templates, shared Thymeleaf rendering path, Semantic Query.	Treat prompt metadata as routing contract and keep Semantic Query logic in DB metadata, not Java if/else.

Review: convengine.flow.* features

Flow Features

Subsystem	Purpose	Why it matters now
dialogue-act.*	Detects AFFIRM / NEGATE / EDIT / RESET / QUESTION / NEW_REQUEST / ANSWER before intent work.	This is the first turn-routing boundary, not a minor helper.
query-rewrite.*	Derives standalone_query and resolved_user_input for follow-up turns.	Important for MCP, schema extraction, and prompt rendering.
interaction-policy.*	Maps dialogue acts into deterministic system decisions.	This is what keeps pending-action and slot-filling paths stable.
action-lifecycle.*	Applies TTL to pending_action_runtime.	Prevents stale confirmations from lingering forever.
disambiguation.*	Triggers targeted clarifications when multiple actions fit.	Prevents accidental execution under ambiguity.
guardrail.*	Applies sanitization and approval gating.	This is the main pre-intent safety boundary.
state-graph.*	Enforces legal state transitions.	Use it before production to catch transition drift early.
memory.*	Writes compressed memory summaries.	Useful when long conversations would otherwise bloat context.
tool-orchestration.*	Controls the direct one-shot tool path.	Keeps direct tool execution separate from planner MCP behavior.

Extension points

CeTask

Creating a Pending Action Task

package: com.zapper.convengine.tasks

JAVA

@Component("shippingConfirmationTask")
public class ShippingConfirmationTask implements CeTask {
    @Override
    public TaskResult execute(EngineSession session, CePendingAction action) {
        String trackingId = (String) session.getInputParams().get("trackingId");
        session.putInputParam("shippingStatus", "DISPATCHED");
        return TaskResult.success();
    }
}

McpToolExecutor

Tool execution adapter

package: com.zapper.convengine.tools

JAVA

@Component("billingToolAdapter")
public class BillingToolAdapter implements McpToolExecutor {
    @Override
    public ToolExecutionResult invoke(ToolRequest request, EngineSession session) {
        if ("BILLING".equals(request.getToolGroup())) {
            return ToolExecutionResult.success(Map.of("balance", 0.00));
        }
        return ToolExecutionResult.skipped();
    }
}

Memory Store

Custom Session Snapshotting

package: com.zapper.convengine.stores

JAVA

@Component
public class CustomMemoryStore implements ConversationMemoryStore {
    @Override
    public String summarize(List<TurnSnapshot> turns) {
        return llmClient.summarizeWithLimits(turns, 100);
    }
}

Semantic Query implementation guidance

If you are using Semantic Query, treat it as canonical-intent + metadata-driven SQL generation, not a free-form SQL generator.

Core runtime path:

1. DbSemanticInterpretToolHandler
2. SemanticInterpretService
3. DbSemanticQueryToolHandler
4. SemanticLlmQueryService
5. PostgresQueryToolHandler
6. SemanticFailureFeedbackService (failure/correction memory)

Implementation rules:

• keep business semantics in ce_semantic_concept + ce_semantic_synonym
• keep field/table mapping in ce_semantic_mapping + ce_semantic_query_class
• keep ambiguity handling in ce_semantic_ambiguity_option
• keep vector retrieval corpus in ce_semantic_concept_embedding
• keep retry memory and corrected SQL in ce_semantic_query_failures
• keep Java generic; avoid project-specific query logic hardcoded in handlers

Related Semantic Query docs:

• MCP
• MCP Semantic Query
• Table Config
• MCP Example 4 - Zapper Disconnect

Operational safety checklist

• Fallbacks: Every reachable state should still resolve a valid ce_response path.
• Phase Targeting: Split state changes across the actual runtime phases instead of overloading one rule row.
• Prompt Contracts: Define interaction_mode and interaction_contract intentionally so CorrectionStep behaves predictably.
• Scope Discipline: Keep ce_mcp_tool and ce_mcp_planner scoped by real intent/state whenever possible.
• Guardrails: Monitor ce_audit for guardrail and MCP blocked branches.
• Semantic discipline: If Semantic Query is enabled, validate allowlists/mappings and test unsupported + clarification paths before rollout.
• State Graph: Enable strict transition validation before promoting a new flow to production.

Regression strategy

Use ConversationReplayService plus audit trace inspection to validate not just the final answer, but the path the engine took.

ConversationReplayService assertion

file: src/test/java/com/zapper/RegressionTests.java

JAVA

@Test
public void testShippingFlow() {
    ReplayResult finalTurn = replayService.runScript("shipping_confirmation_script.json");

    assertEquals("SHIPPING_CONFIRMED", finalTurn.getFinalIntent());
    assertEquals("EXECUTE_PENDING_ACTION", finalTurn.getAuditStages().getLastSystemAction());
}