ExecutionReference — Lifecycle State Machine

Generated from specification/state-machines/execution-reference.md. Edit the canonical source file, not this page.

RFC 2119 normative language applies throughout.

1. States

State	Meaning
created	ExecutionReference record has been created following a proposal acceptance. External execution records have not yet been linked.
linked	At least one external execution record (TMS trip, order, or equivalent) has been linked. Execution is in progress.
completed	Execution has concluded and all external references are confirmed. An ExecutionOutcome has been submitted.
cancelled	Execution was called off after the match was committed. No further changes are expected.

Terminal states: completed, cancelled

2. State-Transition Table

From State	Command	To State	Notes
(none)	POST /execution-references	created	Created automatically when a MatchProposal is accepted, or posted explicitly by an authorized party.
created	link (via external reference attachment)	linked	One or more external execution records attached.
created	cancel	cancelled	Execution cancelled before any linking. Cancellation reason MUST be provided.
linked	complete (system or outcome submitter)	completed	Final ExecutionOutcome submitted and confirmed.
linked	cancel	cancelled	Execution cancelled after linking; reason MUST be provided.

Invalid Transitions

Any command not listed above MUST return 422 Unprocessable Entity with error type urn:freyt:protocol:error:invalid-state-transition. A completed or cancelled record MUST NOT accept further state-changing commands.

3. Preconditions

POST /execution-references (→ created)

• Authorization: Actor belongs to one of the participating organizations (carrier or shipper) or is the broker system performing automatic creation on proposal acceptance.
• Scope required: outcomes:write
• Relationship state: The linked MatchProposal MUST be in accepted state.
• Version check: The acceptedProposalId and its resourceVersion MUST be recorded.
• Policy check: participatingOrganizationIds MUST include both the carrier and shipper from the accepted proposal.

link (created → linked)

• Authorization: Actor belongs to one of the participatingOrganizationIds.
• Scope required: outcomes:write
• Version check: If-Match MUST match current resourceVersion.
• Policy check: At least one valid external reference (externalTripRef or externalOrderRef) MUST be provided. References are namespaced with system and type fields to avoid collision across TMS systems.

complete (linked → completed)

• Authorization: Actor belongs to one of the participatingOrganizationIds, or triggered by the system after a final ExecutionOutcome is submitted and confirmed.
• Scope required: outcomes:write
• Version check: If-Match MUST match current resourceVersion.
• Policy check: At least one ExecutionOutcome in a final state MUST reference this ExecutionReference.

cancel (created | linked → cancelled)

• Authorization: Actor belongs to one of the participatingOrganizationIds.
• Scope required: outcomes:write
• Version check: If-Match MUST match current resourceVersion.
• Policy check: Cancellation reason MUST be provided. If status is linked, all participating organizations SHOULD be notified.

4. Postconditions

Command	Postconditions
POST /execution-references	status = created; resourceVersion = 1; createdAt recorded; acceptedProposalId stored; participating organizations recorded. Event pcx.execution-reference.created.v1 emitted.
link	status = linked; linkedAt recorded; external references appended; resourceVersion incremented. Event pcx.execution-reference.linked.v1 emitted.
complete	status = completed; completedAt recorded; resourceVersion incremented. Event pcx.execution.completed.v1 emitted.
cancel	status = cancelled; cancelledAt recorded; cancellation reason stored; resourceVersion incremented. Event pcx.execution-reference.cancelled.v1 emitted.

5. Concurrency Rules

• All state-changing commands require If-Match with the current ETag.
• Concurrent link and cancel: first writer wins; second receives 409 Conflict with stale-resource-version.
• Concurrent complete and cancel: complete and cancel may race if an outcome is submitted at the same time a cancellation is requested. The first committed transaction wins. A committed completed state MUST NOT be overwritten by a delayed cancel.
• Multiple link calls: Multiple external references may be attached in separate link calls. Each call MUST include If-Match against the version after the previous link. Concurrent link calls from different organizations must be serialized through optimistic concurrency; the losing call receives 409 and MUST retry with the updated version.
• All transitions MUST be applied atomically.

6. Invariants

1. Proposal binding: An ExecutionReference MUST be associated with exactly one accepted MatchProposal. It MUST NOT be created from a proposal in any other state.
2. External reference namespacing: All external references MUST carry system and type identifiers. The server MUST NOT treat references from different systems as equivalent.
3. No resurrection: A completed or cancelled record MUST NOT be transitioned to any other state.
4. Outcome consistency: A completed ExecutionReference MUST have at least one ExecutionOutcome in a final state that references it.
5. Organizational isolation: External references MUST only be visible to the participatingOrganizationIds and authorized protocol operators. Broker logs MUST NOT expose exact location or customer identity contained in external system references.
6. Audit retention: ExecutionReference records MUST be retained as per the retentionPolicyRef derived from the linked relationship, even after completed or cancelled.