SHIP Finding Workflow Contract

Status: Active Version: v1 Last updated: 2026-04-13

This document is the normative state-machine contract for the SHIP finding workflow. It is the workflow-semantics companion to docs/api/openapi/rgl8r-public-api-v1.2.0.yaml, which documents request/response shapes.

The finding workflow is intentionally documented separately from the claim submission workflow (docs/api/ship-claim-submission-contract-v1.md) because the two have distinct state machines and distinct terminal semantics.

Routes in scope

All routes below are callable with an integration-key Bearer JWT obtained via POST /api/auth/token/integration.

The canonical transition table is defined in apps/api/src/lib/ship/transitions.ts. The routes above are thin wrappers that look up the transition and apply it inside a single transaction together with the audit trail.

State machine

              ┌─────────────────────────────────────────────────────┐
              │                                                     │
              │                                                     ▼
            OPEN ──dispute──▶ DISPUTED ──submit──▶ SUBMITTED ──carrier-review──▶ CARRIER_REVIEW
              │                   │                    │                               │
              │                   ├────credit──────────┼──────────credit───────────────┤──▶ CREDITED  (terminal-resolved)
              │                   │                    │                               │
              │                   └────reject──────────┼──────────reject───────────────┤──▶ REJECTED  (terminal-resolved)
              │                                        │
              └─────dismiss───▶ DISMISSED                                                │
                                                                                          │
        reopen from any of {DISMISSED, CREDITED, REJECTED, SUBMITTED, CARRIER_REVIEW}  ─▶ OPEN

State definitions:

• OPEN — initial state when the SHIP audit worker surfaces a finding.
• DISPUTED — customer has disputed the charge. disputedAt is set.
• SUBMITTED — the dispute has been packaged into a submission and sent to the carrier.
• CARRIER_REVIEW — the carrier has acknowledged the submission and is reviewing.
• CREDITED — terminal-resolved. resolvedAt is set. This is the billing-critical state — recording a credit feeds tenant billing calculations. Use the per-finding credit endpoint; batch credit is disabled (action=credit on the batch endpoint returns 400 INVALID_REQUEST).
• REJECTED — terminal-resolved. resolvedAt is set. The carrier declined the dispute.
• DISMISSED — the customer closed the finding without a dispute.

Terminal-resolved states (CREDITED, REJECTED) set resolvedAt at the moment of transition. Reopening any terminal or in-flight state clears both disputedAt and resolvedAt and returns the finding to OPEN.

Finding explanations and actionability

Every finding response includes server-derived explanation fields that answer three operator questions: what was off, why it matters, and whether it is dispute-ready.

Compact fields (all finding list and detail responses)

Detail fields (shipment detail and single-finding responses only)

Discrepancy explanation (AMOUNT_VARIANCE detail only)

For AMOUNT_VARIANCE findings in shipment detail responses, two additional fields provide a component-level breakdown of the billed-vs-expected variance:

Exactness levels

discrepancyExplanation object

These fields are additive: they appear only on AMOUNT_VARIANCE findings in shipment detail responses and are omitted entirely from list endpoints and non-AMOUNT_VARIANCE findings (not present as null — absent from the response object).

If no linked ship_upload snapshot exists for a shipment, SHIP fails closed for discrepancy explanation: it does not fall back to shipment-wide billed rows, and the response downgrades exactness instead of synthesizing a cross-upload billed breakdown.

Shipment-level summary (audit list and shipment detail)

Allowed-actions matrix

Mutation handlers enforce this matrix: attempting an action not in allowedActions returns 409 ACTION_NOT_ALLOWED.

Claim eligibility matrix

Credit endpoint: billing-critical rules

POST /api/ship/findings/:findingId/credit is the only way to record a credit. It is documented as normative launch behavior in docs/api/public-api-contract-v1.md#ship-credit-confirmation-contract-billing-critical. Key rules:

• Request body must include a positive amount and a confirmation object with source, referenceId, and confirmedAt.
• Optional fields on confirmation: notes, artifactUrl.
• Batch credit is disabled: POST /api/ship/findings/batch with action=credit returns 400 INVALID_REQUEST with a remediation message pointing to the per-finding endpoint.

Batch endpoint semantics

POST /api/ship/findings/batch applies one action to a list of findingIds. The response contains one result entry per input finding, with a per-finding status:

Batch behavior is best-effort: a single invalid entry does not roll back the rest. Callers must inspect each result.

Allowed batch actions: dispute, dismiss, submit, carrier-review, reject, reopen. Credit is excluded as noted above.

Error envelopes

All errors follow the canonical public envelope. Endpoint-specific errors:

Retry guidance

• State-transition writes are not idempotent in a general sense, but transitions into the same terminal state from the same source state are safe to retry — the second call returns ACTION_NOT_ALLOWED (already in target), which the caller should treat as success.
• For batch calls, retry only the entries whose per-finding result was not ok or skipped.
• Retry on 429 using details.retryAfterSeconds; do not retry on ACTION_NOT_ALLOWED without re-reading state.

Cross-references

• OpenAPI artifact: docs/api/openapi/rgl8r-public-api-v1.2.0.yaml
• Public API contract pack: docs/api/public-api-contract-v1.md
• Claim submission contract (downstream of findings): docs/api/ship-claim-submission-contract-v1.md
• Quickstart and agent kit: docs/developers/quickstart.md, docs/api/agent-integration-kit-v1.md
• Sample fixture: docs/api/examples/fixtures/ship-invoice-sample.csv
• Example scripts: docs/api/examples/rgl8r_ship_quickstart.ts, docs/api/examples/rgl8r_ship_quickstart.py