`test/openagents/reputation_test.exs`, and

`test/openagents_web/controllers/reputation_controller_test.exs`.

### SETTLEMENT-001 — A bounty pays once, against fingerprinted evidence

Status: Current

Bounty settlement is a separate authority from attribution accounting. A payment

leaves the treasury only when an operator-admitted treasury policy bounds the

amount, the daily budget, the attempt count, and the admitted self-custodial

destination kinds; the priced specification carries a named buyer, a sats

amount, acceptance criteria, a verification policy, an expiry, and a fingerprint

over all of them; the claim pins that fingerprint and the claimant's own

destination; a verification under the specification's own verifier policy digest

accepts the exact commit the claim delivered; and the settlement request carries

an approval reference and an idempotency key.

A repriced specification, a moved fingerprint, a rejected verifier, a commit

without its own verification, a missing approval, an expired claim, a dispute,

an exhausted budget, or an exhausted attempt bound each stop the payment. One

idempotency key names one payment intent, one intent per claim can reach `paid`,

one receipt exists per intent, and a payment hash is unique, so a duplicate

request, a retry, and a lost acknowledgement all resolve to the first receipt

instead of a second payment. Expiry, dispute, and refund are append-only

adjustments that never rewrite a receipt.

The treasury never holds the claimant's keys and never provisions a wallet for

them: the domain hands an authorized request to the configured gateway and

records the returned evidence, and an unconfigured gateway fails closed. Public

projections publish only the amount, the status, reference kinds, and the

evidence the repository's disclosure level admits, never a destination, a

claimant or buyer reference, an operator identity, an approval reference, or a

gateway reference. The claimant can export the full receipt, including their own

destination, without a hosted wallet.

Evidence: `OpenAgents.Settlement`, `OpenAgents.Settlement.PaymentGateway`, its

seven append-only schemas with their uniqueness and partial-uniqueness

constraints, and the pricing, claim, verification, duplicate, stale-commit,

approval, budget, retry, reconciliation, expiry, dispute, refund, privacy, and

receipt-export cases in `test/openagents/settlement_test.exs`.

### MODULE-001 — Every invocation pins one immutable admitted module

Status: Current

| COLLECTIVE-003 | `test/openagents/collective_publication_test.exs` |

| COMPENSATION-001 | `test/openagents/compensation_test.exs` |

| REPUTATION-001 | `test/openagents/reputation_test.exs`, `test/openagents_web/controllers/reputation_controller_test.exs` |

| SETTLEMENT-001 | `test/openagents/settlement_test.exs` |

| MODULE-001 | `test/openagents/modules/registry_test.exs`, `test/openagents/tool_step_persistence_test.exs` |

| MODULE-002 | `test/openagents/modules/discovery_test.exs`, `test/openagents/modules/lifecycle_test.exs` |

| MODULE-003 | `test/openagents/modules/router_test.exs`, `test/openagents/turn_tool_loop_test.exs` |

# Bounty settlement

`OpenAgents.Settlement` prices a forge issue in sats, admits one claim, grades

the delivery at an exact commit, and pays the claimant from the treasury against

an inspectable receipt chain. The contract is `SETTLEMENT-001` in

[`INVARIANTS.md`](../INVARIANTS.md), proven by

[`test/openagents/settlement_test.exs`](../test/openagents/settlement_test.exs).

The settlement authority is separate from attribution accounting. Compensation

accounting still holds `payout_authority: false` (`COMPENSATION-001`); nothing in

this loop grants it a payment operation.

## The loop

1. **Admit the treasury policy.** `admit_treasury_policy/2` records the maximum

   payment, the daily budget, the attempt bound, the admitted self-custodial

   destination kinds, and the refund, expiry, retry, and dispute behavior, with

   the operator identity, the authentication method, and the approval reference

   behind it. The policy digest covers its exact rules.

2. **Price the issue.** `price_bounty/3` records the named buyer, the sats

   amount, the acceptance criteria, the verification policy, the destination

   kind, and the expiry, then fingerprints all of them together with the policy

   digest and the revision. Repricing appends a revision with a new fingerprint.

3. **Claim it.** `claim_bounty/2` pins the fingerprint and the claimant's own

   destination, and stores the destination digest next to it. One claim holds a

   specification at a time; an expired or rejected claim releases it.

4. **Verify the delivery.** `verify_claim/2` records a qualification receipt for

   one claim at one commit, under the specification's own verifier policy digest

   and the claim's own work job. An accepted verification moves the claim to

   `verified`; a rejected one moves it to `rejected`.

5. **Settle.** `settle/2` needs the exact commit, an approval reference, and an

   idempotency key. It refuses a superseded specification, a moved fingerprint, a

   commit without its own verification, an expired claim, a dispute, an amount

   above the treasury authority, an exhausted daily budget, and an exhausted

   attempt bound. It then dispatches one payment through the configured gateway

   and records the exact receipt.

6. **Export the evidence.** `export_payment_receipt/2` gives the claimant the

   amount, the fee, the payment hash, the preimage digest, the commit, the

   fingerprint, and their own destination. `public_projection/1` publishes only

   what the repository's disclosure level admits.

## Custody

The domain holds no keys, no node, and no wallet. `PaymentGateway` is the whole

boundary: it takes an authorized, idempotency-keyed request and answers `{:ok,

settled}`, `{:pending, reason_code}`, or `{:error, reason_code}`. Configure the

production gateway with `:settlement_payment_gateway`. Without that

configuration, `PaymentGateway.Unconfigured` refuses every payment, so an

unprepared environment fails closed instead of appearing to pay.

The claimant is paid at a destination they control, so nobody needs a hosted

OpenAgents wallet to collect a bounty.

Forum tipping keeps its own narrower boundary,

`OpenAgents.Forum.Tips.PaymentService`, because a tip is a one-shot transfer

between two people. A treasury payment also has to survive a lost

acknowledgement, so the settlement gateway additionally answers `lookup/1` for

the terminal state of an idempotency key.

## What stops a second payment

One idempotency key names one payment intent for the life of the settlement:

- A duplicate request returns the first receipt and never calls the gateway

  again.

- A failed attempt retries under the same key until the policy attempt bound.

- A lost acknowledgement stays `pending`; `reconcile/1` asks the gateway for the

  key's terminal state and turns a settled key into its receipt.

- A partial unique index allows one `paid` intent per claim, one receipt per

  intent, and one row per payment hash.

- Reusing a key for a different claim fails with `:idempotency_key_conflict`.

## Expiry, dispute, and refund

`expire_claim/3`, `open_dispute/3`, and `refund/3` append an adjustment carrying

the operator identity, the authentication method, the approval reference, and a

reason code. An expiry releases the specification for another claimant. A dispute

freezes settlement. A refund applies only to a paid claim and never rewrites the

payment receipt.

## What stays private

Public projections carry the amount, the status, reference kinds, the acceptance

criteria count, and — at the ledger level — the fingerprint, the commit, the

payment hash, and the receipt digest. They never carry a destination, a claimant

or buyer reference, a work job reference, an operator identity, an approval

reference, a gateway reference, or a preimage digest.

defmodule OpenAgents.Settlement do

  @moduledoc """

  Bounty settlement: price a forge issue, claim it, verify the delivery, and pay

  the claimant from the treasury against an inspectable receipt chain.

  The domain owns authority and evidence, never custody. Every payment needs an

  operator-admitted treasury policy, an approval reference, a specification

  fingerprint that has not moved, an accepted verification at the exact commit,

  and an idempotency key. The configured payment gateway

  (`OpenAgents.Settlement.PaymentGateway`) performs the transfer to a

  self-custodial destination and returns exact evidence.

  A specification change, a failed verifier, a stale commit, a missing

  approval, an exhausted budget, an expired claim, a dispute, or a duplicate

  request each stop a payment. A lost acknowledgement reconciles through the

  same idempotency key, so it never becomes a second payment.

  """

  import Ecto.Query

  alias OpenAgents.Forge.Visibility

  alias OpenAgents.Issues.Issue

  alias OpenAgents.Provenance.Canonical

  alias OpenAgents.Repo

  alias OpenAgents.Settlement.{

    Adjustment,

    BountySpec,

    Claim,

    PaymentGateway,

    PaymentIntent,

    PaymentReceipt,

    TreasuryPolicy,

    Verification

  }

  @policy_id "openagents.settlement.bounty.v1"

  @policy_version 1

  @default_rules %{

    "unit" => "sat",

    "custody" => "claimant_self_custodial_destination",

    "destination_kinds" => ["bolt12_offer"],

    "max_payment_sats" => 10_000,

    "daily_budget_sats" => 50_000,

    "max_attempts" => 3,

    "requires_accepted_verification" => true,

    "requires_approval_receipt" => true,

    "expiry" => "an expired claim releases the specification and never pays",

    "failed_payment" => "the same idempotency key retries until max_attempts",

    "lost_acknowledgement" => "reconcile the idempotency key, never pay twice",

    "dispute" => "a dispute freezes settlement until an operator resolves it",

    "refund" => "a refund is an append-only adjustment, never a receipt rewrite"

  }

  @doc "The settlement policy identifier."

  def policy_id, do: @policy_id

  @doc "The default treasury rules an operator can narrow before admission."

  def default_rules, do: @default_rules

  @doc """

  Admits the treasury policy that bounds every later payment.

  `operator` carries `actor_id`, `auth_method`, and `approval_receipt_ref`.

  """

  @spec admit_treasury_policy(map(), map()) :: {:ok, TreasuryPolicy.t()} | {:error, term()}

  def admit_treasury_policy(operator, rules \\ %{}) do

    rules = Map.merge(@default_rules, rules)

    with :ok <- validate_operator(operator),

         :ok <- validate_rules(rules) do

      digest =

        Canonical.digest!(%{

          "policy_id" => @policy_id,

          "version" => @policy_version,

          "rules" => rules

        })

      %TreasuryPolicy{}

      |> TreasuryPolicy.changeset(%{

        policy_id: @policy_id,

        version: @policy_version,

        policy_digest: digest,

        rules: rules,

        actor_id: operator.actor_id,

        auth_method: operator.auth_method,

        approval_receipt_ref: operator.approval_receipt_ref

      })

      |> Repo.insert()

    end

  end

  @doc "The admitted treasury policy, or `{:error, :treasury_policy_missing}`."

  @spec treasury_policy() :: {:ok, TreasuryPolicy.t()} | {:error, :treasury_policy_missing}

  def treasury_policy do

    case Repo.get_by(TreasuryPolicy, policy_id: @policy_id, version: @policy_version) do

      %TreasuryPolicy{} = policy -> {:ok, policy}

      nil -> {:error, :treasury_policy_missing}

    end

  end

  @doc """

  Prices one issue and fingerprints the specification.

  Repricing the same issue appends a revision with a new fingerprint. Claims

  pinned to the previous fingerprint can no longer be paid.

  """

  @spec price_bounty(Issue.t(), map(), map()) :: {:ok, BountySpec.t()} | {:error, term()}

  def price_bounty(%Issue{} = issue, attributes, operator) do

    with :ok <- validate_operator(operator),

         {:ok, policy} <- treasury_policy(),

         {:ok, priced} <- validate_price(policy, attributes) do

      revision = next_revision(issue)

      fingerprint =

        Canonical.digest!(%{

          "policy_digest" => policy.policy_digest,

          "issue_id" => issue.id,

          "revision" => revision,

          "buyer_ref" => priced.buyer_ref,

          "amount_sats" => priced.amount_sats,

          "acceptance_criteria" => priced.acceptance_criteria,

          "verification_policy" => priced.verification_policy,

          "destination_kind" => priced.destination_kind,

          "expires_at" => DateTime.to_iso8601(priced.expires_at)

        })

      %BountySpec{}

      |> BountySpec.changeset(%{

        treasury_policy_id: policy.id,

        issue_id: issue.id,

        revision: revision,

        buyer_ref: priced.buyer_ref,

        amount_sats: priced.amount_sats,

        acceptance_criteria: priced.acceptance_criteria,

        verification_policy: priced.verification_policy,

        destination_kind: priced.destination_kind,

        expires_at: priced.expires_at,

        spec_fingerprint: fingerprint,

        actor_id: operator.actor_id,

        auth_method: operator.auth_method,

        approval_receipt_ref: operator.approval_receipt_ref

      })

      |> Repo.insert()

    end

  end

  @doc "The current priced specification for an issue, or nil."

  @spec current_spec(Issue.t()) :: BountySpec.t() | nil

  def current_spec(%Issue{} = issue) do

    BountySpec

    |> where(issue_id: ^issue.id)

    |> order_by(desc: :revision)

    |> limit(1)

    |> Repo.one()

  end

  @doc """

  Claims the current specification and pins its fingerprint.

  `claimant` carries `claimant_ref`, `work_job_ref`, `destination_kind`, and

  `destination`. The destination is the claimant's own; the settlement never

  creates or holds a wallet for them.

  """

  @spec claim_bounty(BountySpec.t(), map()) :: {:ok, Claim.t()} | {:error, term()}

  def claim_bounty(%BountySpec{} = spec, claimant) do

    with {:ok, policy} <- treasury_policy(),

         :ok <- require_current_spec(spec),

         :ok <- require_unexpired_spec(spec),

         {:ok, destination} <- validate_destination(policy, spec, claimant),

         {:ok, refs} <- validate_claimant(claimant) do

      digest =

        Canonical.digest!(%{

          "spec_fingerprint" => spec.spec_fingerprint,

          "claimant_ref" => refs.claimant_ref,

          "work_job_ref" => refs.work_job_ref,

          "destination_digest" => destination.digest

        })

      %Claim{}

      |> Claim.changeset(%{

        bounty_spec_id: spec.id,

        spec_fingerprint: spec.spec_fingerprint,

        claimant_ref: refs.claimant_ref,

        work_job_ref: refs.work_job_ref,

        destination_kind: destination.kind,

        destination: destination.value,

        destination_digest: destination.digest,

        state: "claimed",

        claim_digest: digest,

        expires_at: spec.expires_at

      })

      |> Repo.insert()

    end

  end

  @doc """

  Records the qualification receipt for one claim at one exact commit.

  An accepted verification moves the claim to `verified`; a rejected one moves

  it to `rejected` and releases the specification for another claimant.

  """

  @spec verify_claim(Claim.t(), map()) :: {:ok, Verification.t()} | {:error, term()}

  def verify_claim(%Claim{} = claim, attributes) do

    with {:ok, claim} <- reload_claim(claim),

         {:ok, spec} <- claim_spec(claim),

         :ok <- require_settleable_claim(claim),

         :ok <- require_pinned_fingerprint(claim, spec),

         :ok <- require_unexpired_claim(claim),

         {:ok, decision} <- validate_verification(claim, spec, attributes) do

      Repo.transaction(fn ->

        verification =

          %Verification{}

          |> Verification.changeset(%{

            claim_id: claim.id,

            spec_fingerprint: spec.spec_fingerprint,

            commit_sha: decision.commit_sha,

            work_job_ref: claim.work_job_ref,

            verifier_ref: decision.verifier_ref,

            verifier_policy_digest: decision.verifier_policy_digest,

            evidence_digest: decision.evidence_digest,

            outcome: decision.outcome,

            reason_code: decision.reason_code,

            auth_method: decision.auth_method,

            decision_receipt_ref: decision.decision_receipt_ref

          })

          |> Repo.insert()

          |> or_rollback()

        claim_state = if decision.outcome == "accepted", do: "verified", else: "rejected"

        claim

        |> Claim.state_changeset(claim_state)

        |> Repo.update()

        |> or_rollback()

        verification

      end)

      |> transaction_result()

    end

  end

  @doc """

  Settles a verified claim from the treasury, once.

  `request` carries `commit_sha`, `idempotency_key`, `actor_id`, `auth_method`,

  and `approval_receipt_ref`. A duplicate request with the same key returns the

  original receipt without paying again.

  """

  @spec settle(Claim.t(), map()) ::

          {:ok, %{claim: Claim.t(), intent: PaymentIntent.t(), receipt: PaymentReceipt.t()}}

          | {:pending, PaymentIntent.t()}

          | {:error, term()}

  def settle(%Claim{} = claim, request) do

    with {:ok, operator} <- validate_settlement_request(request),

         {:ok, claim} <- reload_claim(claim),

         {:ok, prior} <- prior_intent(claim, operator.idempotency_key) do

      case prior do

        %PaymentIntent{state: "paid"} = intent -> settled_intent(intent)

        _open -> authorize(claim, operator)

      end

    end

  end

  defp prior_intent(%Claim{} = claim, idempotency_key) do

    case Repo.get_by(PaymentIntent, idempotency_key: idempotency_key) do

      nil -> {:ok, nil}

      %PaymentIntent{claim_id: claim_id} = intent when claim_id == claim.id -> {:ok, intent}

      %PaymentIntent{} -> {:error, :idempotency_key_conflict}

    end

  end

  defp settled_intent(%PaymentIntent{} = intent) do

    case receipt_for(intent) do

      %PaymentReceipt{} = receipt -> settled_result(intent, receipt)

      nil -> reconcile_open(intent)

    end

  end

  defp authorize(%Claim{} = claim, operator) do

    with {:ok, spec} <- claim_spec(claim),

         {:ok, policy} <- treasury_policy(),

         :ok <- require_settleable_claim(claim),

         :ok <- require_pinned_fingerprint(claim, spec),

         :ok <- require_current_spec(spec),

         :ok <- require_unexpired_claim(claim),

         {:ok, verification} <- accepted_verification(claim, operator.commit_sha, spec),

         :ok <- require_payment_authority(policy, spec),

         {:ok, intent} <- payment_intent(claim, spec, verification, operator) do

      dispatch(claim, spec, policy, intent)

    end

  end

  @doc """

  Reconciles one dispatched idempotency key against the gateway.

  A settled key that never acknowledged becomes its receipt here. A key the

  gateway does not know stays unpaid.

  """

  @spec reconcile(String.t()) ::

          {:ok, %{claim: Claim.t(), intent: PaymentIntent.t(), receipt: PaymentReceipt.t()}}

          | {:pending, PaymentIntent.t()}

          | {:error, term()}

  def reconcile(idempotency_key) when is_binary(idempotency_key) do

    case Repo.get_by(PaymentIntent, idempotency_key: idempotency_key) do

      nil -> {:error, :payment_intent_missing}

      %PaymentIntent{} = intent -> settled_intent(intent)

    end

  end

  @doc "Expires a live claim and releases the specification."

  @spec expire_claim(Claim.t(), map(), String.t()) :: {:ok, Adjustment.t()} | {:error, term()}

  def expire_claim(%Claim{} = claim, operator, reason_code),

    do: adjust(claim, operator, "expiry", reason_code, "expired")

  @doc "Freezes settlement for a claim under dispute."

  @spec open_dispute(Claim.t(), map(), String.t()) :: {:ok, Adjustment.t()} | {:error, term()}

  def open_dispute(%Claim{} = claim, operator, reason_code),

    do: adjust(claim, operator, "dispute", reason_code, "disputed")

  @doc "Records a refund for a paid claim without rewriting its receipt."

  @spec refund(Claim.t(), map(), String.t()) :: {:ok, Adjustment.t()} | {:error, term()}

  def refund(%Claim{} = claim, operator, reason_code) do

    with {:ok, claim} <- reload_claim(claim),

         :ok <- require_paid_claim(claim) do

      adjust(claim, operator, "refund", reason_code, "refunded")

    end

  end

  @doc """

  The public projection for an issue's settlement, bounded by the repository's

  disclosure level (TRANSPARENCY-001).

  Returns nil when the repository publishes nothing, when the level is below

  `:l1`, or when the issue has no priced specification.

  """

  @spec public_projection(Issue.t()) :: map() | nil

  def public_projection(%Issue{} = issue) do

    issue = Repo.preload(issue, :repository)

    level = Visibility.level(issue.repository && issue.repository.name)

    case {level, current_spec(issue)} do

      {:l0, _spec} -> nil

      {_level, nil} -> nil

      {level, spec} -> projection(issue, spec, level)

    end

  end

  @doc """

  The claimant's exportable payment receipt.

  The export carries the claimant's own destination and the evidence chain that

  proves the payment. It never carries operator identity, approval references,

  or gateway credentials, and it does not depend on a hosted wallet.

  """

  @spec export_payment_receipt(Claim.t(), String.t()) :: {:ok, map()} | {:error, term()}

  def export_payment_receipt(%Claim{} = claim, claimant_ref) when is_binary(claimant_ref) do

    with {:ok, claim} <- reload_claim(claim),

         :ok <- require_claimant(claim, claimant_ref),

         {:ok, spec} <- claim_spec(claim),

         {:ok, receipt} <- paid_receipt(claim),

         {:ok, verification} <- receipt_verification(receipt) do

      issue = Repo.preload(Repo.get!(Issue, spec.issue_id), :repository)

      {:ok,

       %{

         "contract" => "openagents.settlement.payment-receipt.v1",

         "issue" => issue_reference(issue),

         "buyer_kind" => reference_kind(spec.buyer_ref),

         "amount_sats" => receipt.amount_sats,

         "fee_sats" => receipt.fee_sats,

         "unit" => "sat",

         "state" => claim.state,

         "spec_fingerprint" => spec.spec_fingerprint,

         "acceptance_criteria" => spec.acceptance_criteria,

         "commit_sha" => verification.commit_sha,

         "work_job_ref" => claim.work_job_ref,

         "verifier_kind" => reference_kind(verification.verifier_ref),

         "verification_evidence_digest" => verification.evidence_digest,

         "destination_kind" => claim.destination_kind,

         "destination" => claim.destination,

         "payment_hash" => receipt.payment_hash,

         "preimage_digest" => receipt.preimage_digest,

         "paid_at" => DateTime.to_iso8601(receipt.paid_at),

         "receipt_digest" => receipt.receipt_digest

       }}

    end

  end

  @doc "The claim of a specification, live or terminal, or nil."

  @spec claim_for(BountySpec.t()) :: Claim.t() | nil

  def claim_for(%BountySpec{} = spec) do

    Claim

    |> where(bounty_spec_id: ^spec.id)

    |> order_by(desc: :inserted_at)

    |> limit(1)

    |> Repo.one()

  end

  defp dispatch(_claim, _spec, _policy, %PaymentIntent{state: "paid"} = intent),

    do: settled_intent(intent)

  defp dispatch(_claim, _spec, _policy, %PaymentIntent{state: "refunded"}),

    do: {:error, :payment_refunded}

  defp dispatch(claim, spec, policy, %PaymentIntent{attempts: 0} = intent) do

    with :ok <- require_attempts_remaining(policy, intent),

         :ok <- require_daily_budget(policy, intent) do

      pay(claim, spec, intent)

    end

  end

  defp dispatch(claim, spec, policy, %PaymentIntent{} = intent) do

    with :ok <- require_attempts_remaining(policy, intent),

         :ok <- require_daily_budget(policy, intent) do

      case PaymentGateway.lookup(intent.idempotency_key) do

        {:ok, settled} -> record_settlement(intent, settled)

        {:pending, reason_code} -> hold(intent, reason_code)

        _unsettled -> pay(claim, spec, intent)

      end

    end

  end

  defp pay(claim, spec, intent) do

    request = %{

      idempotency_key: intent.idempotency_key,

      amount_sats: intent.amount_sats,

      destination_kind: claim.destination_kind,

      destination: claim.destination,

      memo: "bounty #{spec.spec_fingerprint} commit #{intent.commit_sha}"

    }

    case PaymentGateway.pay(request) do

      {:ok, settled} -> record_settlement(intent, settled)

      {:pending, reason_code} -> hold(intent, reason_code)

      {:error, reason_code} -> record_failure(intent, reason_code)

      {:unknown, _nothing} -> record_failure(intent, "payment_gateway_unknown")

    end

  end

  defp reconcile_open(%PaymentIntent{} = intent) do

    case PaymentGateway.lookup(intent.idempotency_key) do

      {:ok, settled} -> record_settlement(intent, settled)

      {:pending, reason_code} -> hold(intent, reason_code)

      _unsettled -> {:error, :payment_unsettled}

    end

  end

  defp record_settlement(%PaymentIntent{} = intent, settled) do

    with {:ok, evidence} <- validate_settled(intent, settled) do

      Repo.transaction(fn ->

        digest =

          Canonical.digest!(%{

            "intent_digest" => intent.intent_digest,

            "amount_sats" => intent.amount_sats,

            "fee_sats" => evidence.fee_sats,

            "payment_hash" => evidence.payment_hash,

            "preimage_digest" => evidence.preimage_digest,

            "paid_at" => DateTime.to_iso8601(evidence.paid_at)

          })

        receipt =

          %PaymentReceipt{}

          |> PaymentReceipt.changeset(%{

            payment_intent_id: intent.id,

            claim_id: intent.claim_id,

            amount_sats: intent.amount_sats,

            fee_sats: evidence.fee_sats,

            payment_hash: evidence.payment_hash,

            preimage_digest: evidence.preimage_digest,

            gateway_ref: evidence.gateway_ref,

            paid_at: evidence.paid_at,

            receipt_digest: digest

          })

          |> Repo.insert()

          |> or_rollback()

        paid_intent =

          intent

          |> PaymentIntent.result_changeset(%{

            state: "paid",

            attempts: intent.attempts + 1,

            failure_reason_code: nil

          })

          |> Repo.update()

          |> or_rollback()

        claim =

          Claim

          |> Repo.get!(intent.claim_id)

          |> Claim.state_changeset("paid")

          |> Repo.update()

          |> or_rollback()

        %{claim: claim, intent: paid_intent, receipt: receipt}

      end)

      |> transaction_result()

    end

  end

  defp record_failure(%PaymentIntent{} = intent, reason_code) do

    result =

      intent

      |> PaymentIntent.result_changeset(%{

        state: "failed",

        attempts: intent.attempts + 1,

        failure_reason_code: reason_code

      })

      |> Repo.update()

    case result do

      {:ok, _failed} -> {:error, {:payment_failed, reason_code}}

      {:error, changeset} -> {:error, changeset}

    end

  end

  defp hold(%PaymentIntent{} = intent, reason_code) do

    result =

      intent

      |> PaymentIntent.result_changeset(%{

        state: "pending",

        attempts: intent.attempts + 1,

        failure_reason_code: reason_code

      })

      |> Repo.update()

    case result do

      {:ok, pending} -> {:pending, pending}

      {:error, changeset} -> {:error, changeset}

    end

  end

  defp settled_result(%PaymentIntent{} = intent, %PaymentReceipt{} = receipt) do

    {:ok, %{claim: Repo.get!(Claim, intent.claim_id), intent: intent, receipt: receipt}}

  end

  defp payment_intent(claim, spec, verification, operator) do

    case Repo.get_by(PaymentIntent, idempotency_key: operator.idempotency_key) do

      %PaymentIntent{} = intent ->

        require_matching_intent(intent, claim, spec, verification, operator)

      nil ->

        insert_intent(claim, spec, verification, operator)

    end

  end

  defp insert_intent(claim, spec, verification, operator) do

    digest =

      Canonical.digest!(%{

        "claim_digest" => claim.claim_digest,

        "spec_fingerprint" => spec.spec_fingerprint,

        "commit_sha" => verification.commit_sha,

        "amount_sats" => spec.amount_sats,

        "idempotency_key" => operator.idempotency_key

      })

    result =

      %PaymentIntent{}

      |> PaymentIntent.changeset(%{

        claim_id: claim.id,

        verification_id: verification.id,

        idempotency_key: operator.idempotency_key,

        amount_sats: spec.amount_sats,

        commit_sha: verification.commit_sha,

        destination_digest: claim.destination_digest,

        spec_fingerprint: spec.spec_fingerprint,

        state: "pending",

        attempts: 0,

        intent_digest: digest,

        actor_id: operator.actor_id,

        auth_method: operator.auth_method,

        approval_receipt_ref: operator.approval_receipt_ref

      })

      |> Repo.insert()

    case result do

      {:ok, intent} ->

        {:ok, intent}

      {:error, changeset} ->

        case Repo.get_by(PaymentIntent, idempotency_key: operator.idempotency_key) do

          %PaymentIntent{} = intent ->

            require_matching_intent(intent, claim, spec, verification, operator)

          nil ->

            {:error, changeset}

        end

    end

  end

  defp require_matching_intent(intent, claim, spec, verification, operator) do

    matches? =

      intent.claim_id == claim.id and intent.spec_fingerprint == spec.spec_fingerprint and

        intent.commit_sha == verification.commit_sha and intent.amount_sats == spec.amount_sats and

        intent.approval_receipt_ref == operator.approval_receipt_ref

    if matches?, do: {:ok, intent}, else: {:error, :idempotency_key_conflict}

  end

  defp require_attempts_remaining(policy, intent) do

    max_attempts = Map.get(policy.rules, "max_attempts", 1)

    if intent.attempts < max_attempts,

      do: :ok,

      else: {:error, :payment_attempts_exhausted}

  end

  defp require_daily_budget(policy, intent) do

    budget = Map.get(policy.rules, "daily_budget_sats", 0)

    window = DateTime.add(DateTime.utc_now(), -86_400, :second)

    paid =

      PaymentIntent

      |> where([intent], intent.state == "paid" and intent.updated_at >= ^window)

      |> select([intent], sum(intent.amount_sats))

      |> Repo.one()

      |> Kernel.||(0)

    if paid + intent.amount_sats <= budget,

      do: :ok,

      else: {:error, :daily_budget_exhausted}

  end

  defp require_payment_authority(policy, spec) do

    max_payment = Map.get(policy.rules, "max_payment_sats", 0)

    if spec.amount_sats <= max_payment,

      do: :ok,

      else: {:error, :amount_exceeds_treasury_authority}

  end

  defp accepted_verification(claim, commit_sha, spec) do

    verification = Repo.get_by(Verification, claim_id: claim.id, commit_sha: commit_sha)

    cond do

      is_nil(verification) and Repo.exists?(where(Verification, claim_id: ^claim.id)) ->

        {:error, :stale_commit}

      is_nil(verification) ->

        {:error, :verification_missing}

      verification.outcome != "accepted" ->

        {:error, :verification_rejected}

      verification.spec_fingerprint != spec.spec_fingerprint ->

        {:error, :spec_fingerprint_mismatch}

      true ->

        {:ok, verification}

    end

  end

  defp adjust(claim, operator, kind, reason_code, claim_state) do

    with {:ok, claim} <- reload_claim(claim),

         :ok <- validate_operator(operator),

         :ok <- validate_reason_code(reason_code) do

      digest =

        Canonical.digest!(%{

          "claim_digest" => claim.claim_digest,

          "kind" => kind,

          "reason_code" => reason_code,

          "approval_receipt_ref" => operator.approval_receipt_ref

        })

      Repo.transaction(fn ->

        adjustment =

          %Adjustment{}

          |> Adjustment.changeset(%{

            claim_id: claim.id,

            kind: kind,

            reason_code: reason_code,

            actor_id: operator.actor_id,

            auth_method: operator.auth_method,

            approval_receipt_ref: operator.approval_receipt_ref,

            adjustment_digest: digest

          })

          |> Repo.insert()

          |> or_rollback()

        claim

        |> Claim.state_changeset(claim_state)

        |> Repo.update()

        |> or_rollback()

        adjustment

      end)

      |> transaction_result()

    end

  end

  defp projection(issue, spec, level) do

    claim = claim_for(spec)

    receipt = claim && paid_receipt_or_nil(claim)

    pulse = %{

      "contract" => "openagents.settlement.public.v1",

      "issue_number" => issue.number,

      "unit" => "sat",

      "amount_sats" => spec.amount_sats,

      "state" => public_state(claim),

      "buyer_kind" => reference_kind(spec.buyer_ref),

      "claimant_kind" => claim && reference_kind(claim.claimant_ref),

      "acceptance_criteria_count" => length(spec.acceptance_criteria),

      "paid" => not is_nil(receipt)

    }

    if level == :l1, do: pulse, else: Map.merge(pulse, ledger(spec, claim, receipt))

  end

  defp ledger(spec, claim, receipt) do

    verification = claim && accepted_verification_or_nil(claim)

    %{

      "spec_fingerprint" => spec.spec_fingerprint,

      "acceptance_criteria" => spec.acceptance_criteria,

      "expires_at" => DateTime.to_iso8601(spec.expires_at),

      "commit_sha" => verification && verification.commit_sha,

      "verifier_kind" => verification && reference_kind(verification.verifier_ref),

      "verification_evidence_digest" => verification && verification.evidence_digest,

      "payment_hash" => receipt && receipt.payment_hash,

      "fee_sats" => receipt && receipt.fee_sats,

      "paid_at" => receipt && DateTime.to_iso8601(receipt.paid_at),

      "receipt_digest" => receipt && receipt.receipt_digest

    }

  end

  defp public_state(nil), do: "priced"

  defp public_state(%Claim{state: state}), do: state

  defp accepted_verification_or_nil(claim) do

    Verification

    |> where([verification], verification.claim_id == ^claim.id)

    |> where([verification], verification.outcome == "accepted")

    |> order_by(desc: :inserted_at)

    |> limit(1)

    |> Repo.one()

  end

  defp paid_receipt_or_nil(claim) do

    PaymentReceipt

    |> where(claim_id: ^claim.id)

    |> order_by(desc: :inserted_at)

    |> limit(1)

    |> Repo.one()

  end

  defp paid_receipt(claim) do

    case paid_receipt_or_nil(claim) do

      %PaymentReceipt{} = receipt -> {:ok, receipt}

      nil -> {:error, :payment_receipt_missing}

    end

  end

  defp receipt_verification(%PaymentReceipt{} = receipt) do

    intent = Repo.get!(PaymentIntent, receipt.payment_intent_id)

    case Repo.get(Verification, intent.verification_id) do

      %Verification{} = verification -> {:ok, verification}

      nil -> {:error, :verification_missing}

    end

  end

  defp receipt_for(%PaymentIntent{} = intent),

    do: Repo.get_by(PaymentReceipt, payment_intent_id: intent.id)

  defp issue_reference(%Issue{} = issue) do

    %{

      "owner" => issue.repository && issue.repository.owner,

      "repository" => issue.repository && issue.repository.name,

      "number" => issue.number

    }

  end

  defp reference_kind(reference) when is_binary(reference) do

    case String.split(reference, ":", parts: 2) do

      [kind, _identifier] -> kind

      [_identifier] -> "unattributed"

    end

  end

  defp reference_kind(_reference), do: "unattributed"

  defp next_revision(issue) do

    revision =

      BountySpec

      |> where(issue_id: ^issue.id)

      |> select([spec], max(spec.revision))

      |> Repo.one()

    (revision || 0) + 1

  end

  defp claim_spec(%Claim{} = claim) do

    case Repo.get(BountySpec, claim.bounty_spec_id) do

      %BountySpec{} = spec -> {:ok, spec}

      nil -> {:error, :bounty_spec_missing}

    end

  end

  defp reload_claim(%Claim{id: id}) do

    case Repo.get(Claim, id) do

      %Claim{} = claim -> {:ok, claim}

      nil -> {:error, :claim_missing}

    end

  end

  defp require_current_spec(%BountySpec{} = spec) do

    latest =

      BountySpec

      |> where(issue_id: ^spec.issue_id)

      |> select([candidate], max(candidate.revision))

      |> Repo.one()

    if latest == spec.revision, do: :ok, else: {:error, :spec_superseded}

  end

  defp require_pinned_fingerprint(%Claim{} = claim, %BountySpec{} = spec) do

    if claim.spec_fingerprint == spec.spec_fingerprint,

      do: :ok,

      else: {:error, :spec_fingerprint_mismatch}

  end

  defp require_unexpired_spec(%BountySpec{} = spec) do

    if DateTime.compare(spec.expires_at, DateTime.utc_now()) == :gt,

      do: :ok,

      else: {:error, :bounty_expired}

  end

  defp require_unexpired_claim(%Claim{} = claim) do

    if DateTime.compare(claim.expires_at, DateTime.utc_now()) == :gt,

      do: :ok,

      else: {:error, :claim_expired}

  end

  defp require_settleable_claim(%Claim{state: state}) when state in ~w(claimed verified),

    do: :ok

  defp require_settleable_claim(%Claim{state: state}),

    do: {:error, {:claim_not_settleable, state}}

  defp require_paid_claim(%Claim{state: "paid"}), do: :ok

  defp require_paid_claim(%Claim{state: state}), do: {:error, {:claim_not_paid, state}}

  defp require_claimant(%Claim{claimant_ref: claimant_ref}, claimant_ref), do: :ok

  defp require_claimant(_claim, _claimant_ref), do: {:error, :not_the_claimant}