Orchestrata Ultimate › Plans › spec-003-completion-plan

SPEC-003 (Intent Broker) — completion plan

Source: plans/spec-003-completion-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-11 · 40 lines.

Prose pending.

Plan text

SPEC-003 (Intent Broker) — completion plan

Trigger: user ruling "complete spec 003 — working, wired; specs are source of truth."

Ground truth (verified this session, not from stale docs)

• IntentRouter (intent_router.py) is REAL: Prolog route_intent/3 + static-mapping fallback
  • capability lookup + U:Ox fallback. Keep as-is.
• IntentDispatcher.dispatch() (intent_router.py:216-265) is a false-confidence stub: builds a packet, calls packet.mark_delivered() (a local field flip), records heartbeat, returns success=True — never sends through Postman despite its docstring. This is the core defect.
• IntentCXPDispatcher (intent_dispatcher.py) is a second, orphaned fake (0 production importers): builds+serializes a packet "to verify integrity", returns success, sends nothing.
• IntentBroker (intent_broker.py) pipeline is rich + correct (validate→impact→route→dispatch→ lifecycle→metrics, REFACTOR routing) but has 0 production construction sites — never wired.
• Production intents currently BYPASS the broker: gateway/handlers/orchestrator.py::handle_intent does a regex parse + raw kernel_client.send_packet (no Prolog validation, no router, no lifecycle) — violates SPEC-003's "IntentBroker is the single entry point."
• Real transport = Postman.register(alias, handler) + route_sync(packet) -> CXPPacket|None (pattern: pipeline_runner → Postman.route_sync → handler → agent.process).

Packets

• P1 (builder) real transport: IntentDispatcher takes an injected IPostman; dispatch() delivers via await asyncio.to_thread(transport.route_sync, packet); success = response not None; drop mark_delivered(); keep REQ-001-018 heartbeat post-delivery. Update tests to inject a REAL Postman + registered handler (no mocks).
• P2 (builder) factory: orchestrator/intent_broker_factory.py::build_intent_broker(...) assembles the full pipeline from real components.
• P4 (builder) remove orphan: delete intent_dispatcher.py::IntentCXPDispatcher + its test after confirming 0 refs; remove any __init__ re-export.
• P5 (test-writer/builder) real E2E: tests/orchestrator/test_intent_broker_e2e.py — real Prolog validator + real IntentRouter (Prolog route_intent/3) + real Postman + a registered volk handler that captures the delivered packet → submit Intent → assert validated, routed to the Prolog-mapped volk, packet DELIVERED to the handler, lifecycle DISPATCHED, heartbeat recorded, metrics bumped.
• P3 (wirer, Opus-supervised, AFTER P1/P2/P5 green): wire build_intent_broker into the in-process intent ingress where a real Postman+volks exist, so intents flow through the broker; verify the live gateway↔kernel path is NOT broken (memory: gateway-engine wiring RESOLVED).

Gate

Real infra (Redis+Prolog), no mocks/skips/xdist, absolute imports, os.environ.get. Verify targeted modules green via scripts/run_tests_streaming.py. Review every diff before merge. No AI attribution.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks