sections, attempt fields, false-green classes, or result states drift from

the code that enforces them.

**The claim is durable, and only the caller's judgment comes from the caller.**

`issue_completion_claims` stores one graded verdict per

`{issue, attempt, revision}`: the state, the typed reasons, and which evidence

satisfied which acceptance criterion. A caller supplies the

criterion-to-evidence mapping and, optionally, false-green classes against its

own result — an assertion that can only make the verdict worse. Everything

else `OpenAgents.Issues.CompletionClaims` grades is read from records: the

issue's four sections from its body, the attempt's five binding fields from

`forge_assignments` and the `budget_snapshot` on its `work_jobs` row, the

verifier from the published check result the evidence resolves to, and the

falsifier as that check's own identity reporting `failed`. Producer-verifier

separation is always required on this path, so an attempt whose requester also

published the check is `unauthorized`.

**Only a qualification receipt can close an issue, and only under an opt-in.**

An acceptance criterion is satisfied only by an `issue_evidence` edge that is a

`qualification` receipt, for that issue, at that exact revision, with the

status `succeeded`. `deployment_check_results` is the one family whose row is a

verdict about named bytes — identity is `{repository, name, commit, artifact

digest}` — and whose publisher is an authorized principal that is not the

attempt. A push records receipt of bytes and carries no result at all; a build

records that a tree compiles, which is necessary for anything to work and

sufficient for nothing to be done; a deployment records that an artifact

reached an environment, which is placement rather than behavior. All four

still record on the evidence chain; only one qualifies. On top of that,

closing requires the repository to have opted in twice —

`repository_closure_policies.agents_enabled` and `verified_closing_enabled`,

both false by default, with an absent row meaning the same as both false — and

requires that no evidence edge for that issue at that revision carries its

family's word for failure.

**A later receipt contradicts; it never reopens.** A failing edge arriving for

an issue and revision an accepted claim rested on stamps `contradicted_at` and

names the edge that disagreed. The issue stays closed, because reopening on a

later signal is a separate policy with its own failure modes (`ISSUE-001`), and

rule four stops any further close on that revision.

**There is one automatic closer, and an automatic close is attributable.**

`OpenAgents.Issues.ClosingReferences` remains the trailer path and is

unchanged: a person wrote `Closes #N`, their write authority was checked, and

the commit was reachable from the default branch. This path closes only issues

that are still open, so a trailer close that already happened is recorded as a

claim and moves nothing. Neither path reads commit prose;

`OpenAgents.Forge.CommitReferences` is still the only reader of it. A reader

tells the two apart by the record: a person's close leaves an

`issue_closing_references` row with a `closed_by_user_id`, and a verified close

leaves an `issue_completion_claims` row whose `closed_by_actor` is

`system:accepted-outcome` and never a user id. PostgreSQL refuses any row that

claims a close on a verdict other than `accepted`

(`issue_completion_claims_close_requires_accepted`).

Evidence: `OpenAgents.AcceptedOutcome`,

`OpenAgents.Issues.CompletionClaims`, `OpenAgents.Issues.CompletionClaim`,

`OpenAgents.Issues.ClosurePolicy`,

`priv/api-contracts/accepted-outcome-v1.json`,

`docs/accepted-outcome-contract.md`, and

`test/openagents/accepted_outcome_test.exs`.

`docs/accepted-outcome-contract.md`,

`test/openagents/accepted_outcome_test.exs`,

`test/openagents/issues/completion_claims_test.exs`, and

`test/openagents_web/controllers/issue_completion_claim_controller_test.exs`.

### THREAD-001 — A thread owns its own model authority, and names it exactly once

| SELF-EDIT-001 | `test/openagents/tools/repository_mutation_tools_test.exs`, `test/openagents/coding_job_test.exs`, `test/openagents/dependency_boundary_test.exs` |

| SCV-001 | `test/openagents/scv/deployments_test.exs`, `test/openagents/dependency_boundary_test.exs` |

| THREAD-001 | `test/openagents/threads/grant_fence_test.exs`, `test/openagents/threads/grant_token_reach_test.exs`, `test/openagents/threads_test.exs` |

| OUTCOME-001 | `test/openagents/accepted_outcome_test.exs` |

| OUTCOME-001 | `test/openagents/accepted_outcome_test.exs`, `test/openagents/issues/completion_claims_test.exs`, `test/openagents_web/controllers/issue_completion_claim_controller_test.exs` |

| DEPLOYPLANE-001 | `test/openagents/deployments_test.exs`, `test/openagents_web/controllers/deployment_controller_test.exs`, `test/openagents_web/api_route_authority_test.exs` |

| DEPLOYPLANE-002 | `test/openagents/deployments_test.exs` |

| DEPLOYPLANE-003 | `test/openagents/deployments/policy_test.exs`, `test/openagents/deployments_test.exs` |

  policy requires it; the attempt records who produced the revision, so the

  check has both halves.

### What stage 6 shipped, and what it deliberately did not

`issue_completion_claims` stores one graded verdict per

`{issue, attempt, revision}`. `OpenAgents.Issues.CompletionClaims` grades it

with `AcceptedOutcome.evaluate/1` and takes exactly one judgment from the

caller: which evidence satisfied which acceptance criterion. Mapping intent to

evidence is the judgment no record can make on its own, which is why it is

claimed; everything else is derived, which is why it cannot be asserted. The

issue's sections come from its body, the attempt's five fields from

`forge_assignments` and its work job's budget snapshot, the verifier from the

check result the evidence resolves to, and the falsifier from that check's own

identity reporting `failed`. Separation is always required on this path.

The narrowing that closes the gap between "a receipt evaluated this commit" and

"the outcome was produced": **only a `qualification` receipt can satisfy an

acceptance criterion**, and only at the exact revision with the status

`succeeded`. `deployment_check_results` is the one family whose row is a verdict

about named bytes, published by an authorized principal that is not the attempt.

A push proves receipt of bytes, a build proves the tree compiles, and a

deployment proves placement — each real, none of them the issue's intent. All

four still record on the evidence chain, and a failing edge in any family

withholds the close.

Closing also needs two per-repository opt-ins, both false by default

(`repository_closure_policies`), and it never reopens: a failing receipt

arriving after an accepted claim closed the issue stamps `contradicted_at` on

the claim and leaves the issue closed for a person to act on. `#130` is

untouched, and the two closes are told apart by their records — a

`closed_by_user_id` on a closing reference, or `system:accepted-outcome` on a

claim. See `INVARIANTS.md`, `OUTCOME-001`.

---

## 6. The staged plan

prose: a report that sounds complete but fails a check above is a typed

non-accepted result, and the review states which one.

## Closing an issue from a claim

A claim is stored whether or not it is accepted, so a refusal is on the record

rather than silent. `OpenAgents.Issues.CompletionClaims` writes one

`issue_completion_claims` row per `{issue, attempt, revision}` and grades it

with `OpenAgents.AcceptedOutcome.evaluate/1`.

The caller supplies one thing: which evidence satisfied which acceptance

criterion. It may also name false-green classes against its own result, which

can only make the verdict worse. Everything else is read from records — the

issue's sections from its body, the attempt's five binding fields from

`forge_assignments` and its work job's budget snapshot, the verifier from the

published check result the evidence resolves to, and the falsifier as that

check's own identity reporting `failed`. Producer-verifier separation is always

required here, so an attempt whose requester also published the check is

`unauthorized`.

### What can close, and what can only claim

| Receipt family | Record | Close | Why |

| --- | --- | --- | --- |

| `qualification` | Yes | **Yes** | A verdict about named bytes. Identity is `{repository, name, commit, artifact digest}`, so a green result cannot be replayed onto bytes it never examined, and the publisher is an authorized principal that is not the attempt. |

| `build` | Yes | No | That the tree compiles at that commit. Necessary for anything to work; sufficient for nothing to be done. |

| `deployment` | Yes | No | That an artifact reached an environment. Placement, not behavior. A `fleet` deployment and a named tenant environment are both operational facts. |

| `push` | Yes | No | That the forge received the bytes. It carries no outcome at all; its `result` is null. |

A qualification receipt closes only at the exact revision the attempt reported,

only with the status `succeeded`, and only for the issue that already claims

that commit. An evidence reference to anything else resolves to no receipt, so

the criterion it names is unevidenced and the claim is `incomplete`.

### The rest of the rule

- **Two opt-ins.** `repository_closure_policies.agents_enabled` decides whether

  a claim is graded at all; `verified_closing_enabled` decides whether an

  accepted claim may move the issue. Both default false, and an absent row

  means the same as both false.

- **No contradiction.** If any evidence edge for that issue at that revision

  carries its family's word for failure — a failed or expired build, a

  reverted, failed, cancelled, or superseded deployment, a failed check — the

  verdict is recorded and the close is withheld.

- **Never reopen.** A failing receipt that arrives after an accepted claim

  closed the issue stamps `contradicted_at` on the claim and names the edge.

  The issue stays closed and a person decides.

- **One closer.** `#130`'s trailer path is unchanged and stays attributed to

  the person who wrote the trailer. This path closes only issues that are still

  open. A reader tells them apart by the record: a person's close leaves an

  `issue_closing_references` row with a `closed_by_user_id`; this one leaves an

  `issue_completion_claims` row whose `closed_by_actor` is

  `system:accepted-outcome`, which is never a user id.

## Related records

- Issue-to-job and receipt linkage: `docs/2026-08-21-issues-projects-work-system-assessment.md`, Track E.

`:unauthorized`, `:failed`, or `:not_applicable`. The issue stays the

canonical work record; the contract only grades a claim about it.

**Completion claim** — the durable record of one graded verdict, stored in

`issue_completion_claims` by `OpenAgents.Issues.CompletionClaims`, keyed on

`{issue, attempt, revision}`. The accepted outcome is the grading; the claim is

what was graded and what happened next. Say "claim" for the record and

"accepted outcome" for the verdict.

**Verified close** — an issue closed from an accepted claim, attributed to

`system:accepted-outcome`. It is not a trailer close: a trailer close is a

person's assertion recorded in `issue_closing_references` with a

`closed_by_user_id` (`ISSUE-001`, `#130`). Both close an issue; only one names

a person, and only a verified close can be contradicted by a later receipt.

### Exports

Two account exports exist and they are not the same document. Say which one.

defmodule OpenAgents.Issues.ClosurePolicy do

  @moduledoc """

  One repository's opt-in for grading and for verified closing

  (`repository_closure_policies`).

  Two flags, both false by default, and the absent row means the same thing as

  the row with both false. That equivalence is the point: a repository that has

  never been asked has not consented, and a policy that treats silence as

  consent would close issues in repositories nobody opted in.

  `agents_enabled` decides whether an agent-authored claim is graded at all.

  False makes every claim `not_applicable` — the accepted-outcome contract's

  own word for work outside the gate — which is not a refusal and not a

  failure.

  `verified_closing_enabled` decides whether an accepted claim may move the

  issue. False records the verdict and the evidence and leaves the issue open,

  which is the useful half of this feature on its own: a person reads what was

  claimed and decides.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  alias OpenAgents.Repositories.Repository

  @type t :: %__MODULE__{}

  @primary_key {:id, :binary_id, autogenerate: true}

  @foreign_key_type :binary_id

  @timestamps_opts [type: :utc_datetime_usec]

  schema "repository_closure_policies" do

    field :agents_enabled, :boolean, default: false

    field :verified_closing_enabled, :boolean, default: false

    belongs_to :repository, Repository

    belongs_to :updated_by_user, User

    timestamps()

  end

  @doc false

  def changeset(policy, attrs) do

    policy

    |> cast(attrs, [

      :repository_id,

      :agents_enabled,

      :verified_closing_enabled,

      :updated_by_user_id

    ])

    |> validate_required([:repository_id, :agents_enabled, :verified_closing_enabled])

    |> unique_constraint(:repository_id)

    |> foreign_key_constraint(:repository_id)

    |> foreign_key_constraint(:updated_by_user_id)

  end

end

defmodule OpenAgents.Issues.CompletionClaim do

  @moduledoc """

  One graded completion claim (`issue_completion_claims`).

  The row is the durable half of `OpenAgents.AcceptedOutcome.evaluate/1`, which

  was a pure function with nothing behind it. It stores the verdict, the typed

  reasons, and the criterion-to-evidence mapping — never the prompt, the

  transcript, the report, or the budget those came from. The execution stays in

  `work_jobs`, the attempt stays in `forge_assignments`, the receipts stay in

  the tables their families own, and the edge between issue and receipt stays

  in `issue_evidence`. This row adds the one fact none of them carried: what

  was claimed about the issue's intent, and how that claim graded.

  `{issue_id, assignment_id, revision}` is unique. An attempt reporting one

  revision has one verdict, so resubmitting a claim regrades it rather than

  accumulating verdicts nobody can order.

  Two columns carry the close, and a database constraint —

  `issue_completion_claims_close_requires_accepted` — refuses a row that says

  it closed an issue on anything but an `accepted` verdict. `closed_by_actor`

  is a system principal and never a user id, which is how a reader tells this

  close from a person's: a person's close is an `issue_closing_references` row

  with a `closed_by_user_id` behind it.

  Two more carry the contradiction. A later receipt that disagrees with the

  evidence an accepted claim rested on stamps `contradicted_at` and names the

  edge that disagreed. It never reopens the issue and never rewrites the

  verdict, because reopening on a later signal is a separate policy with its

  own failure modes (`ISSUE-001`). What it does is stop the claim from reading

  as uncontested.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Forge.Assignment

  alias OpenAgents.Issues.{EvidenceEntry, Issue}

  alias OpenAgents.Repositories.Repository

  @type t :: %__MODULE__{}

  @states ~w(accepted incomplete unauthorized failed not_applicable)

  @primary_key {:id, :binary_id, autogenerate: true}

  @timestamps_opts [type: :utc_datetime_usec]

  schema "issue_completion_claims" do

    field :revision, :string

    field :state, :string

    field :reasons, {:array, :string}, default: []

    field :criteria, {:array, :map}, default: []

    field :verifier, :string

    field :falsifier, :string

    field :closed, :boolean, default: false

    field :closed_at, :utc_datetime_usec

    field :closed_by_actor, :string

    field :contradicted_at, :utc_datetime_usec

    field :contradiction_reason, :string

    belongs_to :repository, Repository, type: :binary_id

    belongs_to :issue, Issue

    belongs_to :assignment, Assignment, type: :binary_id

    belongs_to :contradicted_by_evidence, EvidenceEntry, type: :binary_id

    timestamps()

  end

  @doc "The verdicts a graded claim can hold."

  @spec states() :: [String.t()]

  def states, do: @states

  @doc false

  def changeset(claim, attrs) do

    claim

    |> cast(attrs, [

      :repository_id,

      :issue_id,

      :assignment_id,

      :revision,

      :state,

      :reasons,

      :criteria,

      :verifier,

      :falsifier,

      :closed,

      :closed_at,

      :closed_by_actor,

      :contradicted_at,

      :contradicted_by_evidence_id,

      :contradiction_reason

    ])

    |> update_change(:revision, &String.downcase/1)

    |> validate_required([:repository_id, :issue_id, :assignment_id, :revision, :state])

    |> validate_inclusion(:state, @states)

    |> validate_format(:revision, ~r/\A[0-9a-f]{7,64}\z/)

    |> validate_length(:verifier, max: 200)

    |> validate_length(:falsifier, max: 500)

    |> validate_length(:closed_by_actor, max: 200)

    |> validate_length(:contradiction_reason, max: 200)

    |> validate_close()

    |> unique_constraint([:issue_id, :assignment_id, :revision])

    |> check_constraint(:closed, name: :issue_completion_claims_close_requires_accepted)

    |> foreign_key_constraint(:repository_id)

    |> foreign_key_constraint(:issue_id)

    |> foreign_key_constraint(:assignment_id)

  end

  # The same rule the database constraint holds, refused earlier and by name so

  # a caller reads `closed_without_accepted_outcome` instead of a constraint

  # violation. Both exist on purpose: the constraint is what makes the rule

  # true of every row, and this is what makes it legible.

  defp validate_close(changeset) do

    closed? = get_field(changeset, :closed)

    state = get_field(changeset, :state)

    closed_at = get_field(changeset, :closed_at)

    cond do

      not closed? -> changeset

      state != "accepted" -> add_error(changeset, :closed, "requires an accepted outcome")

      is_nil(closed_at) -> add_error(changeset, :closed_at, "is required for a closed claim")

      true -> changeset

    end

  end

end

defmodule OpenAgents.Issues.CompletionClaims do

  @moduledoc """

  Store what an attempt claims about an issue, grade it, and close the issue

  only when a narrow rule says the claim entails the outcome.

  ## The gap this closes, and the gap it refuses to close

  `#148` bound an issue to the receipts that evaluated its commit. That answers

  "what evaluated this?" and it does not answer "is this done?". A green build

  on a commit whose message names an issue proves the tree compiles. A

  successful deployment proves bytes reached a host. Neither entails that the

  outcome the issue asked for was produced, and a rule that closed an issue on

  either would file a receipt saying work was verified when nothing verified

  it.

  So no receipt closes an issue here. What closes an issue is a *claim*: an

  assertion that names, for each of the issue's acceptance criteria, the

  evidence that satisfied it. Mapping intent to evidence is the one judgment no

  record can make on its own, which is why it is claimed rather than derived —

  and why the rest is derived rather than claimed.

  ## What the caller supplies, and what it cannot

  The caller supplies exactly one thing: the criterion-to-evidence mapping, and

  optionally the false-green classes it names against its own result, which can

  only make the verdict worse. Everything else is read from records:

    * the **issue's** four required sections, parsed from its body;

    * the **attempt's** five binding fields — issue number, repository,

      authority, budget, revision — from `forge_assignments` and the

      `budget_snapshot` on its `work_jobs` row, never from the request, so the

      attempt cannot claim to be bound to an issue it did not run against;

    * the **verifier**, which is the published check result the evidence

      resolves to. It is admitted because publishing a check result is already

      authority-gated (`OpenAgents.Deployments.Authority`), and it is

      independent of the producer unless the same user both requested the

      attempt and published the check;

    * the **falsifier**, which is the observation that would have made the same

      claim red: the same check name, on the same commit and the same artifact

      digest, reporting `failed`. `deployment_check_results` keys on exactly

      that identity, so the falsifying observation is a row that can exist.

  Producer-verifier separation is always required on this path. An agent

  grading its own work is the hazard the whole contract exists for, so it is

  not a knob.

  ## The closure rule

  An issue closes automatically only when every one of these holds:

    1. The repository opted in twice: `agents_enabled` and

       `verified_closing_enabled` (`OpenAgents.Issues.ClosurePolicy`). Both

       default false, and an absent policy row means the same as both false.

    2. `OpenAgents.AcceptedOutcome.evaluate/1` graded the claim `accepted`.

    3. Every acceptance criterion names an `issue_evidence` edge that is a

       **qualification** receipt for **this issue** at **this exact revision**

       whose status is `succeeded`. An edge in any other family, for any other

       revision, or for any other issue satisfies nothing, so the criterion is

       unevidenced and the claim is `incomplete`.

    4. No evidence edge for this issue at this revision carries a failing

       terminal word in any family. A revision that qualified and then failed

       to build is contradicted, and a person decides.

    5. The issue is open. This path never reopens and never changes a closed

       issue's state.

  ### Why only qualification

  `deployment_check_results` is the only family whose row is a *verdict about

  named bytes*: identity is `{repository, name, commit, artifact digest}`, so a

  green result cannot be replayed onto bytes it never examined, and the

  publisher is an authorized principal that is not the attempt. The other three

  record something real and something else:

    * **push** — that the forge received the bytes. It carries no outcome at

      all; its `result` is null.

    * **build** — that the tree compiles at that commit. Necessary for anything

      to work; sufficient for nothing to be done.

    * **deployment** — that an artifact reached an environment. An operational

      fact about placement, not an observation of behavior.

  All four still *record*: they appear on the issue's evidence chain, they are

  what a person reads, and a failing one in any family blocks the automatic

  close by rule 4. Recording is the broad half; closing is the narrow half.

  ## When a later receipt disagrees

  `note_evidence/1` runs where evidence is written. A failing edge arriving for

  an issue and revision an accepted claim already closed stamps

  `contradicted_at` and names the edge. It does **not** reopen the issue:

  reopening on a later signal is a separate policy with its own failure modes

  (`ISSUE-001` draws the same line for reverts). What it does is stop the

  closure reading as uncontested, and rule 4 stops any further close on that

  revision.

  ## One closer, not two

  `OpenAgents.Issues.ClosingReferences` stays the trailer path and is untouched:

  a person wrote `Closes #N`, the pusher's write authority was checked, and the

  commit was reachable from the default branch. That is a human assertion and it

  stays attributed to that person. This path closes only issues that are still

  open, so a trailer close that already happened is recorded here as a claim

  and moves nothing. Neither path reads commit prose —

  `OpenAgents.Forge.CommitReferences` is still the only reader of that.

  A reader tells the two apart by the record, not by the issue: a person's close

  leaves an `issue_closing_references` row with a `closed_by_user_id`; this one

  leaves an `issue_completion_claims` row whose `closed_by_actor` is the system

  principal `system:accepted-outcome` and never a user id.

  """

  import Ecto.Query

  require Logger

  alias OpenAgents.AcceptedOutcome

  alias OpenAgents.Deployments.CheckResult

  alias OpenAgents.Forge.Assignment

  alias OpenAgents.Issues

  alias OpenAgents.Issues.{ClosurePolicy, CompletionClaim, EvidenceEntry, Issue}

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.Repository

  alias OpenAgents.Work.Job

  # The one actor an automatic close is attributed to. It is not a user id and

  # cannot become one, which is the whole distinction between this close and a

  # person's.

  @closing_actor "system:accepted-outcome"

  # The one family whose receipt can satisfy an acceptance criterion. See the

  # moduledoc: the other three record, they do not qualify.

  @closing_family "qualification"

  # A qualification receipt satisfies a criterion only with this status.

  # `pending` is not a verdict, and `failed` is the opposite of one.

  @qualifying_result "succeeded"

  # Each family's own words for "this did not work", read straight from the

  # schemas that own them: `forge_builds.status`, `forge_deploys.result`,

  # `deployment_runs.state`, and `deployment_check_results.status`. A push

  # receipt has no result, so it can never contradict.

  @failing_results %{

    "push" => [],

    "build" => ~w(failed expired),

    "deployment" => ~w(failed reverted needs_rolling_replace cancelled superseded),

    "qualification" => ~w(failed)

  }

  # The issue-body headings the accepted-outcome contract requires. The match is

  # on the heading text, after the semantic question — "is this claim gradeable

  # at all" — has already been settled by the policy read.

  @section_headings %{

    problem: ["problem"],

    scope: ["scope"],

    acceptance_criteria: ["acceptance criteria"],

    success_metrics: ["success metrics"]

  }

  @type verdict :: {:ok, CompletionClaim.t()} | {:error, atom()}

  @doc "The system principal an automatic close is attributed to."

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

  def closing_actor, do: @closing_actor

  @doc "The one receipt family whose evidence can satisfy an acceptance criterion."

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

  def closing_family, do: @closing_family

  @doc "The receipt families that can record evidence but never close an issue."

  @spec recording_only_families() :: [String.t()]

  def recording_only_families,

    do: Enum.reject(EvidenceEntry.families(), &(&1 == @closing_family))

  # ── policy ──────────────────────────────────────────────────────────────

  @doc """

  One repository's closure policy, defaulted rather than absent.

  An unconfigured repository reads as both flags false, which is the same

  answer the stored row with both flags false gives. Nothing distinguishes

  silence from a deliberate no, because nothing should.

  """

  @spec policy(Repository.t() | binary()) :: ClosurePolicy.t()

  def policy(%Repository{id: id}), do: policy(id)

  def policy(repository_id) when is_binary(repository_id) do

    Repo.one(from p in ClosurePolicy, where: p.repository_id == ^repository_id) ||

      %ClosurePolicy{

        repository_id: repository_id,

        agents_enabled: false,

        verified_closing_enabled: false

      }

  end

  @doc "Set one repository's closure policy, attributed to the user who set it."

  @spec set_policy(Repository.t(), map(), OpenAgents.Accounts.User.t() | nil) ::

          {:ok, ClosurePolicy.t()} | {:error, Ecto.Changeset.t()}

  def set_policy(%Repository{id: repository_id}, attrs, actor \\ nil) do

    existing =

      Repo.one(from p in ClosurePolicy, where: p.repository_id == ^repository_id) ||

        %ClosurePolicy{}

    attrs =

      attrs

      |> Map.new(fn {key, value} -> {to_string(key), value} end)

      |> Map.put("repository_id", repository_id)

      |> Map.put("updated_by_user_id", actor && actor.id)

    existing |> ClosurePolicy.changeset(attrs) |> Repo.insert_or_update()

  end

  # ── the claim ───────────────────────────────────────────────────────────

  @doc """

  Grade and store one completion claim for a finished attempt.

  `author` is `:agent` or `:human`. A human's claim is `not_applicable` —

  people close their own issues through the ordinary path, and the contract

  gates agent-authored claims only.

  `attrs` carries `:evidence`, a list of `%{criterion: binary, evidence_id:

  binary}`, and optionally `:false_green_classes`. Nothing else in `attrs` is

  read: the attempt's binding, the verifier, and the falsifier are derived from

  records so that a claim cannot assert its own authority.

  Returns the stored claim. A non-accepted verdict is stored too — a typed

  refusal on the record is the point, not silence.

  """

  @spec submit(Assignment.t(), :agent | :human, map()) :: verdict()

  def submit(%Assignment{} = assignment, author, attrs \\ %{})

      when author in [:agent, :human] do

    with {:ok, assignment} <- terminal_attempt(assignment),

         {:ok, repository} <- fetch(Repository, assignment.repository_id),

         {:ok, issue} <- fetch_issue(assignment.issue_id) do

      revision = String.downcase(assignment.terminal_commit)

      policy = policy(repository)

      references = evidence_references(issue, revision, attrs)

      claim =

        build_claim(

          author,

          policy,

          repository,

          issue,

          assignment,

          revision,

          references,

          attrs

        )

      persist(repository, issue, assignment, revision, AcceptedOutcome.evaluate(claim), policy)

    end

  end

  @doc "The claims recorded against one issue, oldest first."

  @spec for_issue(Issue.t() | integer()) :: [map()]

  def for_issue(%Issue{id: id}), do: for_issue(id)

  def for_issue(issue_id) when is_integer(issue_id) do

    CompletionClaim

    |> where([claim], claim.issue_id == ^issue_id)

    |> order_by([claim], asc: claim.inserted_at, asc: claim.id)

    |> Repo.all()

    |> Enum.map(&summary/1)

  end

  @doc """

  Claims for a whole page of issues, keyed by issue id.

  One query for the page, the way `OpenAgents.Issues.Evidence.for_issues/1`

  reads evidence, so listing issues does not cost one query per row.

  """

  @spec for_issues([Issue.t()]) :: %{integer() => [map()]}

  def for_issues(issues) when is_list(issues) do

    ids = Enum.map(issues, & &1.id)

    base = Map.new(ids, &{&1, []})

    CompletionClaim

    |> where([claim], claim.issue_id in ^ids)

    |> order_by([claim], asc: claim.inserted_at, asc: claim.id)

    |> Repo.all()

    |> Enum.reduce(base, fn claim, acc ->

      Map.update(acc, claim.issue_id, [summary(claim)], &(&1 ++ [summary(claim)]))

    end)

  end

  @doc """

  The bounded projection of one stored claim.

  It carries the verdict, the typed reasons, the criterion names, the public

  receipt references, and the close. It never carries a prompt, a log, a

  private repository name, or a private receipt reference, because the criteria

  it stores were already reduced to that shape by

  `OpenAgents.AcceptedOutcome.public_projection/1` before the row was written.

  """

  @spec summary(CompletionClaim.t()) :: map()

  def summary(%CompletionClaim{} = claim) do

    %{

      id: claim.id,

      revision: claim.revision,

      state: claim.state,

      reasons: claim.reasons,

      criteria: claim.criteria,

      verifier: claim.verifier,

      falsifier: claim.falsifier,

      closed: claim.closed,

      closed_at: claim.closed_at,

      closed_by_actor: claim.closed_by_actor,

      contradicted_at: claim.contradicted_at,

      contradiction_reason: claim.contradiction_reason,

      recorded_at: claim.inserted_at

    }

  end

  @doc """

  Mark the accepted claims one new evidence edge contradicts.

  Called where evidence is written. A failing edge for an issue and revision an

  accepted claim rested on stamps the claim; nothing else moves, and the issue

  is never reopened. Never raises and never fails the receipt that produced it.

  """

  @spec note_evidence(EvidenceEntry.t()) :: :ok

  def note_evidence(%EvidenceEntry{} = entry) do

    if failing?(entry) do

      now = DateTime.utc_now()

      {_count, _rows} =

        CompletionClaim

        |> where([claim], claim.issue_id == ^entry.issue_id)

        |> where([claim], claim.revision == ^String.downcase(entry.commit_sha))

        |> where([claim], claim.state == "accepted" and is_nil(claim.contradicted_at))

        |> Repo.update_all(

          set: [

            contradicted_at: now,

            contradicted_by_evidence_id: entry.id,

            contradiction_reason: "#{entry.family}:#{entry.result}",

            updated_at: now

          ]

        )

      :ok

    else

      :ok

    end

  end

  def note_evidence(_entry), do: :ok

  @doc "Whether one evidence edge carries its family's word for failure."

  @spec failing?(EvidenceEntry.t()) :: boolean()

  def failing?(%EvidenceEntry{family: family, result: result}) when is_binary(result) do

    result in Map.get(@failing_results, family, [])

  end

  def failing?(%EvidenceEntry{}), do: false

  # ── building the claim from records ─────────────────────────────────────

  defp build_claim(author, policy, repository, issue, assignment, revision, references, attrs) do

    %{

      actor: if(author == :agent, do: :agent, else: :human),

      agents_enabled: policy.agents_enabled,

      issue: %{

        number: issue.number,

        repository: "#{repository.owner}/#{repository.name}",

        sections: sections(issue.body)

      },

      attempt: %{

        issue_number: issue.number,

        repository: "#{repository.owner}/#{repository.name}",

        authority: authority(assignment),

        budget: budget(assignment),

        revision: revision

      },

      verification: %{

        verifier: verifier(references, assignment),

        falsifier: falsifier(references),

        terminal_result: terminal_result(references),

        separation_required: true,

        false_green_classes: named_false_greens(attrs)

      },

      evidence:

        Enum.map(references, fn reference ->

          %{

            criterion: reference.criterion,

            receipt: reference.receipt,

            visibility: reference.visibility

          }

        end)

    }

  end

  # The five attempt fields the contract binds come from records, never from

  # the request. Two of them are the issue and the repository, which is why

  # `attempt_not_bound_to_issue` cannot fire on this path: an attempt that ran

  # against another issue is a different `forge_assignments` row and produces a

  # different claim.

  defp authority(%Assignment{requesting_principal: %{"type" => type, "id" => id}})

       when is_binary(type) and is_binary(id),

       do: "#{type}:#{id}"

  defp authority(%Assignment{}), do: nil

  defp budget(%Assignment{work_job_id: nil}), do: nil

  defp budget(%Assignment{work_job_id: job_id}) do

    case Repo.one(from job in Job, where: job.id == ^job_id, select: job.budget_snapshot) do

      snapshot when is_map(snapshot) and map_size(snapshot) > 0 -> snapshot

      _absent -> nil

    end

  end

  # Only edges this issue already owns, at this exact revision, in the one

  # family that qualifies, with the one status that qualifies. A reference to

  # anything else resolves to no receipt, so the criterion it names is

  # unevidenced and the claim is `incomplete` — which is the contract's own way

  # of saying "a build is not a verdict".

  defp evidence_references(%Issue{} = issue, revision, attrs) do

    requested =

      attrs

      |> Map.get(:evidence, Map.get(attrs, "evidence", []))

      |> List.wrap()

      |> Enum.map(&normalize_reference/1)

      |> Enum.reject(&is_nil/1)

    ids = requested |> Enum.map(& &1.evidence_id) |> Enum.reject(&is_nil/1)

    qualifying =

      if ids == [] do

        %{}

      else

        EvidenceEntry

        |> where([entry], entry.id in ^ids)

        |> where([entry], entry.issue_id == ^issue.id)

        |> where([entry], entry.commit_sha == ^revision)

        |> where([entry], entry.family == ^@closing_family)

        |> where([entry], entry.result == ^@qualifying_result)

        |> Repo.all()

        |> Map.new(&{&1.id, &1})

      end

    Enum.map(requested, fn reference ->

      entry = Map.get(qualifying, reference.evidence_id)

      %{

        criterion: reference.criterion,

        entry: entry,

        receipt: entry && entry.id,

        visibility: visibility(issue)

      }

    end)

  end

  defp normalize_reference(%{} = reference) do

    criterion = reference[:criterion] || reference["criterion"]

    evidence_id = reference[:evidence_id] || reference["evidence_id"]

    case {present(criterion), cast_id(evidence_id)} do

      {nil, _id} -> nil

      {criterion, id} -> %{criterion: criterion, evidence_id: id}

    end

  end

  defp normalize_reference(_reference), do: nil

  defp cast_id(value) do

    case Ecto.UUID.cast(value) do

      {:ok, id} -> id

      :error -> nil

    end

  end

  defp present(value) when is_binary(value) do

    case String.trim(value) do

      "" -> nil

      trimmed -> trimmed

    end

  end

  defp present(_value), do: nil

  # A public repository's receipt references are publishable; a private

  # repository's are not, and the projection renders them as `:private` without

  # the reference. The visibility is read from the repository rather than from

  # the caller for the same reason everything else here is.

  defp visibility(%Issue{repository_id: repository_id}) do

    case Repo.one(from r in Repository, where: r.id == ^repository_id, select: r.visibility) do

      "public" -> :public

      _private_or_absent -> :private

    end

  end

  # The verifier is the check result the evidence resolves to, never a name the

  # caller supplied. It is admitted because publishing a check result is

  # already authority-gated; it is independent unless the same user both

  # requested the attempt and published the check.

  defp verifier(references, %Assignment{} = assignment) do

    case check_results(references) do

      [] ->

        %{}

      results ->

        %{

          id: results |> Enum.map(& &1.name) |> Enum.uniq() |> Enum.sort() |> Enum.join(","),

          admitted: true,

          independent_of_producer: Enum.all?(results, &independent?(&1, assignment))

        }

    end

  end

  defp independent?(%CheckResult{published_by_user_id: nil}, %Assignment{}), do: true

  defp independent?(%CheckResult{published_by_user_id: publisher}, %Assignment{} = assignment) do

    authority(assignment) != "user:#{publisher}"

  end

  # What observation would have made this red: the same check name, on the same

  # commit and the same artifact digest, reporting `failed`.

  # `deployment_check_results_identity_index` keys on exactly that tuple, so the

  # falsifying observation is a row that can exist rather than a sentence.

  defp falsifier(references) do

    case check_results(references) do

      [] ->

        nil

      results ->

        results

        |> Enum.map(&"deployment_check_results:#{&1.name}@#{&1.artifact_digest}=failed")

        |> Enum.uniq()

        |> Enum.sort()

        |> Enum.join(" ")

        |> String.slice(0, 500)

    end

  end

  defp terminal_result(references) do

    entries = references |> Enum.map(& &1.entry) |> Enum.reject(&is_nil/1)

    if entries != [] and Enum.all?(entries, &(&1.result == @qualifying_result)),

      do: :passed,

      else: :failed

  end

  defp check_results(references) do

    ids =

      references

      |> Enum.map(& &1.entry)

      |> Enum.reject(&is_nil/1)

      |> Enum.map(& &1.receipt_id)

      |> Enum.uniq()

    if ids == [], do: [], else: Repo.all(from r in CheckResult, where: r.id in ^ids)

  end

  # Self-reported, and deliberately the one thing a caller may add: naming a

  # false-green class against your own result can only make the verdict worse.

  defp named_false_greens(attrs) do

    attrs

    |> Map.get(:false_green_classes, Map.get(attrs, "false_green_classes", []))

    |> List.wrap()

    |> Enum.map(&to_string/1)

    |> Enum.filter(&(&1 in AcceptedOutcome.false_green_classes()))

  end

  # ── issue sections ──────────────────────────────────────────────────────

  # Deterministic parsing of a bounded field, after the question of whether to

  # grade at all has been answered by the stored policy. It reads Markdown ATX

  # headings and nothing else: a section is present when its heading exists and

  # some non-blank line follows it before the next heading.

  defp sections(body) when is_binary(body) do

    lines = String.split(body, ~r/\r?\n/)

    @section_headings

    |> Enum.reduce(%{}, fn {section, headings}, acc ->

      Map.put(acc, section, section_body(lines, headings))

    end)

  end

  defp sections(_body), do: %{}

  defp section_body(lines, headings) do

    lines

    |> Enum.drop_while(&(not heading_matching?(&1, headings)))

    |> Enum.drop(1)

    |> Enum.take_while(&(not heading?(&1)))

    |> Enum.map(&strip_marker/1)

    |> Enum.reject(&(&1 == ""))

    |> case do

      [] -> nil

      content -> content

    end

  end

  # A criterion is the sentence, not the bullet that carries it. An acceptance

  # criterion written `- [ ] the thing` and the same criterion named in a claim

  # have to be the same string, or every criterion would read as unevidenced

  # for a reason that is about Markdown rather than about the work.

  defp strip_marker(line) do

    line

    |> String.trim()

    |> String.replace(~r/\A(?:[-*+]|\d+\.)\s+/, "")

    |> String.replace(~r/\A\[[ xX]\]\s+/, "")

    |> String.trim()

  end

  defp heading?(line), do: Regex.match?(~r/\A\s{0,3}\#{1,6}\s+/, line)