govoplan-core/docs/TICKET_INTEGRATION_CONTRACTS.md

Ticket Integration Capability Contracts

Core owns two narrow, optional contracts that let the Tickets module compose with policy and formal-procedure modules without importing either one. Tickets remains the authority for operational ticket identity, lifecycle, assignment, comments, links, and immutable history.

Capability Names

• tickets.routing optionally supplies a TicketRoutingProvider.
• tickets.case_escalation optionally supplies a TicketCaseEscalationProvider.

Both contracts are version 1 and are defined in govoplan_core.core.tickets. Registry helpers return None when a capability is absent or has the wrong shape, so optional-module absence is normal runtime state rather than a startup failure.

Routing

Tickets sends a bounded, tenant-scoped TicketRoutingRequest containing the ticket reference, type, priority, title, receive time, optional queue hint, and non-secret attributes. The provider returns its identity and may return a queue reference, timezone-aware service target, human-readable explanation, and bounded metadata.

The provider is advisory. Tickets snapshots any returned queue and target into its own record and history. An absent provider, a no-match plan, or an absent queue must not prevent ticket intake; authorized staff can route manually. Providers must not persist a second ticket lifecycle.

Case Escalation

Tickets sends a TicketCaseEscalationCommand with stable tenant, ticket, and display references, the requested Case type, actor-visible handoff note, timezone-aware occurrence time, and an idempotency key. The provider returns a stable Case identifier, number, bounded application-relative URL, replay flag, and bounded metadata.

Providers must:

• recheck tenant and Case-creation authorization;
• reject an absent or inactive requested Case type;
• make identical retries resolve the same Case;
• preserve the Ticket reference in governed Case context; and
• return only an application-relative path, never an untrusted external URL.

Tickets records the result and its own escalation evidence. Cases remains the authority for the formal procedure; Tickets remains the authority for the operational request. Creating a Case does not merge or silently close either lifecycle.

Failure And Transaction Semantics

Capability calls receive the caller's active persistence session so a concrete provider can participate in the same unit of work. Authorization and validation errors fail the requested routing/escalation mutation explicitly. The caller must still apply its own permission checks, tenant boundary, replay protection, and immutable evidence rules.