tmux-amq/workplans/TAMQ-WP-0002-coordination-engine-adapter.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
TAMQ-WP-0002	workplan	Coordination-engine adapter boundary	communication	tmux-amq	finished	codex	coulomb-social	2026-08-24	2026-08-26	48da5fa7-b7bf-5d13-8edc-b90f266e241c

Coordination-engine adapter boundary

Connect coordination-engine to tmux-amq through the existing local Unix-socket boundary while preserving tmux-amq's local transport authority and keeping workflow/orchestration policy in coordination-engine.

Specify the adapter contract

id: TAMQ-WP-0002-T01
status: done
priority: high
state_hub_task_id: "a222dab7-edea-58c6-9dab-d684eb65c412"

Define request, response, identity, delivery, acknowledgement, retry, and failure semantics for a coordination-engine client. Resolve protocol-version negotiation and document which system owns each state transition.

The implemented contract is spec/coordination-engine-adapter-v0.1.md. It defines same-user socket authentication, major-version and capability negotiation, exact endpoint resolution, message/correlation identity, idempotency conflicts, bounded delivery states, ack timeouts, late acknowledgement, recovery, and the TAMQ/coordination ownership boundary.

Implement the coordination-engine client adapter

id: TAMQ-WP-0002-T02
status: done
priority: high
state_hub_task_id: "195db613-05a3-58d8-9e94-2db34920576f"

Implement the adapter against the stable socket contract without importing tmux/control-mode concerns into coordination-engine. This task waits for T01.

tamq.client provides a transport-only async client and CoordinationEngineAdapter. It opens a fresh socket connection per operation, resolves one live repository endpoint, maps the coordination lease ID to a durable idempotency key, preserves trigger correlation metadata, and exposes receipt, acknowledgement, and terminal retry operations. Protocol constants are separate from the service and terminal implementation.

Prove interoperability and recovery

id: TAMQ-WP-0002-T03
status: done
priority: high
state_hub_task_id: "23c7f6c7-be48-5b6c-b85c-ae05d82cc277"

Add end-to-end coverage for delivery, acknowledgement, reconnect, replay, deduplication, incompatible protocol versions, and endpoint disappearance. Update both repositories' operator documentation with the verified workflow.

Unix-socket integration tests cover negotiation, identical-wake deduplication, idempotency conflict, durable receipt recovery after service restart, incompatible protocol, and disappeared endpoints. Reliability tests cover delivery, explicit and late acknowledgement, same-ID ack-timeout redelivery, lease expiry, exhaustion, and retry reset. JSONL replay now uses deterministic idempotency while retaining normal gita validation. TAMQ documentation and the coordination-engine worker-service specification link the verified contract.

Residuals

This workplan does not implement coordination-engine's trigger observer, coordination leases, actionability decisions, checkpoints, or State Hub projection. Those remain owned by COORDINATION-WP-0003 and consume this adapter rather than expanding TAMQ's scope.