Disputes and evidence

This document is the dense reference companion to the public guide Disputes and evidence evaluation. It describes how automated predicate evaluation differs from human dispute workflows, maps Harbor and Gateway state machines, and documents the arbitration handoff packet.

Design principles

1. Evidence evaluation is deterministic. Harbor runs paybond-predicate-vm over signed payee evidence and the intent's frozen predicate contract. The result is stored as predicate_passed before any terminal money move.
2. Predicate failure is not an HTTP error. submit_evidence returns 200 with predicate_passed: false; settlement/confirm drives refund when appropriate.
3. Disputes freeze automation. Harbor disputed blocks drive_terminal_settlement until dispute/resolve. Gateway cases add timeline, notes, evidence URI refs, and export — they do not replace Harbor money authority for resolved_release / resolved_refund.
4. Provider chargebacks are signals. Stripe charge.dispute.* ingest may set settlement_exception_* fields and Signal PROVIDER_STRIPE_DISPUTE without transitioning intent state.
5. Tenant isolation at every hop. Gateway dispute queries filter by authenticated tenant_id. Harbor operator routes require tenant-scoped upstream bearer or mTLS client identity.

Evidence evaluation

sequenceDiagram
  autonumber
  actor Payee as Payee / Kit
  participant GW as Gateway
  participant HB as Harbor
  participant VM as Predicate VM
  participant Rail as Settlement rail

  Payee->>GW: POST /harbor/intents/{id}/evidence (tenant API key)
  GW->>HB: Forward evidence (mTLS)
  HB->>HB: Verify EvidenceSignV1 (version 2)
  HB->>VM: Evaluate predicate_dsl or policy_binding
  HB->>HB: Optional completion_schema drift report
  HB->>HB: funded → evidence_submitted
  HB-->>GW: predicate_passed, predicate_evaluation, schema_validation
  GW-->>Payee: 200 JSON body

  Payee->>GW: POST /harbor/intents/{id}/settlement/confirm
  GW->>HB: Forward confirm
  alt predicate_passed = true
    HB->>Rail: Capture / release
    HB-->>HB: released
  else predicate_passed = false
    HB->>Rail: Cancel / refund
    HB-->>HB: refunded
  end

Evidence contract inputs

Kit signing helpers: kit/ts/src/agent/evidence.ts, Python parity in paybond_kit.

Predicate evaluation response (Harbor)

Key fields on successful evidence submit:

Ledger events appended include EvidenceSubmitted, PredicateEvaluated, and optionally CompletionSchemaValidated.

Schema validation (signal-only)

completion_schema.rs validates vendor and canonical shapes at submit time. Failures appear in schema_validation but do not reject the HTTP request. Operators may see passed_with_drift when the predicate passed but quality or vendor checks failed.

One-shot evidence binding

Lifecycle transition funded → evidence_submitted accepts exactly one evidence submission path per intent. Re-submission is not supported; contested outcomes use disputes.

Dispute handling

sequenceDiagram
  autonumber
  actor Op as Operator
  participant GW as Gateway
  participant PG as Postgres cases
  participant HB as Harbor
  participant Rail as Settlement rail

  Op->>GW: POST /v1/disputes/cases { intent_id, subject, ... }
  GW->>HB: POST /operator/v1/intents/{id}/dispute/open
  HB-->>HB: state → disputed
  GW->>PG: Insert case (status frozen), timeline
  GW-->>Op: 201 { case, harbor }

  Op->>GW: POST /v1/disputes/cases/{id}/notes
  Op->>GW: POST /v1/disputes/cases/{id}/evidence { label, ref_uri }
  GW->>PG: Append timeline / evidence refs

  Op->>GW: POST /v1/disputes/cases/{id}/resolve { resolution }
  alt resolved_release
    GW->>HB: POST .../dispute/resolve { action: release }
    HB->>Rail: Capture / release
    HB-->>HB: released
    GW->>PG: status resolved_release
  else resolved_refund
    GW->>HB: POST .../dispute/resolve { action: refund }
    HB->>Rail: Cancel / refund
    HB-->>HB: refunded
    GW->>PG: status resolved_refund
  else resolved_split or escalated_external
    GW->>PG: Case status only (no Harbor resolve)
  end

Harbor intent state machine (dispute subset)

stateDiagram-v2
  [*] --> funded
  funded --> evidence_submitted: submit evidence
  funded --> disputed: dispute/open
  evidence_submitted --> disputed: dispute/open
  evidence_submitted --> released: confirm + passed
  evidence_submitted --> refunded: confirm + failed
  disputed --> released: dispute/resolve release
  disputed --> refunded: dispute/resolve refund
  released --> [*]
  refunded --> [*]

Terminal states released and refunded are not re-opened by provider webhooks alone. Late Stripe dispute events on ACH may set settlement_exception_* while state remains terminal — see chargeback section below.

Gateway dispute case statuses

Resolve API accepts resolution values: resolved_release, resolved_refund, resolved_split, escalated_external (aliases release / refund also accepted for Harbor-backed resolutions).

Link path (Harbor opened first)

POST /v1/disputes/cases/link-disputed-intent verifies Harbor state = disputed, then inserts a case without calling dispute/open again. Returns existing case if one is already registered for the intent.

Implementation: disputes.go.

Stripe chargeback vs Harbor dispute

sequenceDiagram
  participant Stripe
  participant GW as Gateway webhooks
  participant HB as Harbor ingest
  participant Sig as Signal

  Stripe->>GW: charge.dispute.created
  GW->>HB: POST /internal/v1/stripe/events
  HB->>HB: Match intent via metadata.paybond_intent_id
  HB->>HB: settlement_exception manual_review (intent state unchanged)
  HB-->>Sig: PROVIDER_STRIPE_DISPUTE observation (optional)
  Note over HB: Operator must explicitly dispute/open for freeze

ACH ingest sets exception code stripe_ach_charge_dispute (stripe_sync.rs). Signal maps charge.dispute.* to PROVIDER_STRIPE_DISPUTE (fraud_signals.go).

HTTP surface

Evidence and settlement (tenant API via Gateway)

Harbor operator (direct or Gateway proxy)

Gateway proxy prefix: /harbor/operator/v1/intents/{id}/dispute/...

Gateway dispute cases

Requires CanManageDisputes RBAC and Private dashboards commercial feature.

Schemas: Gateway OpenAPI.

ArbitrationHandoffPacketV1

Stable export shape for third-party reviewers (PAYBOND-V1-005):

{
  "packet_version": "v1",
  "tenant_realm": "550e8400-e29b-41d4-a716-446655440000",
  "case": { },
  "timeline": [
    {
      "seq": 1,
      "event_type": "case_opened",
      "created_at": "2026-07-02T13:00:00Z",
      "payload": { }
    }
  ],
  "evidence_refs": [
    {
      "label": "vendor_ticket",
      "ref_uri": "https://support.example/ticket/123"
    }
  ],
  "content_sha256_hex": "…"
}
{
  "packet_version": "v1",
  "tenant_realm": "550e8400-e29b-41d4-a716-446655440000",
  "case": { },
  "timeline": [
    {
      "seq": 1,
      "event_type": "case_opened",
      "created_at": "2026-07-02T13:00:00Z",
      "payload": { }
    }
  ],
  "evidence_refs": [
    {
      "label": "vendor_ticket",
      "ref_uri": "https://support.example/ticket/123"
    }
  ],
  "content_sha256_hex": "…"
}

Defined in ArbitrationHandoffPacketV1.

Decision reference

Kit and Signal boundaries

See support matrix.

Related

• Disputes and evidence evaluation — adopter-facing guide with curl examples
• Intent lifecycle — full state diagram
• Evidence & artifacts — Kit signing checklist
• Completion presets — preset-bound predicates
• Harbor predicate DSL — rule language reference
• Operations runbook §2 — dispute SLAs and RBAC
• Settlement provider integration — terminal capture per rail