reference and every evidence reference from the signed claim while remaining

verifiable.

A subject is a bare string inside the signed claim, and it stays that way. What

resolves one to an account is a separate binding, `reputation_subject_claims`:

a claim the account makes and an operator decides, where only a `linked` claim

resolves and a unique index on `subject_id` means one string never resolves to

two accounts. The binding carries the kind — `account`, `forum_actor`, or

`agent` — with one `CHECK` constraint per kind, because putting the kind on the

attestation would either leave it outside the signature or invalidate every

signature already published. Nothing in issuance or verification reads the

binding: an attestation is exactly as valid, and exactly as checkable, for a

subject no account has claimed.

Evidence: `OpenAgents.Reputation`, `OpenAgents.Reputation.Claim`,

`OpenAgents.Reputation.Attestation`, `OpenAgents.Reputation.SigningKey`,

`OpenAgents.Reputation.PolicyReceipt`, the append-only and uniqueness

constraints on `reputation_attestations`, `OpenAgentsWeb.ReputationController`,

`test/openagents/reputation_test.exs`, and

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

`OpenAgents.Reputation.PolicyReceipt`, `OpenAgents.Reputation.SubjectClaim`,

the append-only and uniqueness constraints on `reputation_attestations`, the

per-kind reference constraint on `reputation_subject_claims`,

`OpenAgentsWeb.ReputationController`, `test/openagents/reputation_test.exs`,

`test/openagents/reputation/subject_claim_test.exs`,

`test/openagents_web/controllers/reputation_subject_claim_controller_test.exs`,

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

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

  `PATCH /api/v3/forum/topics/:id` and `PATCH /api/v3/forum/posts/:id`; and

  approving or rejecting an identity claim from `/admin/forum/claims` and

  `PATCH /api/v3/forum/claims/:id`.

- Approving or rejecting a reputation subject claim under

  `GET /api/v3/reputation/subject-claims/pending` and

  `PATCH /api/v3/reputation/subject-claims/:id`

  (`OpenAgentsWeb.ReputationController`). The decision binds an attestation

  subject to an account under `EXIT-001`; it never issues, revokes, or alters

  an attestation, and `REPUTATION-001`'s verification does not read it.

- Suspending and reinstating an agent under `/api/operator/agents/:handle`.

- Creating, authorizing, recording against, and deleting artifact listings under

  `/api/operator/artifact-listings`.

`OpenAgents.Leaderboard.Entry`'s field set. Degrading may not introduce a key

either: a failed read is absent, never an error string.

A list-element key path is published only while that list has an element, so

the enumeration follows the data in both directions. `independence.export.gaps`

is empty today because `EXIT-001` records no `partial` or `blocked` family, and

its `family`, `status`, and `issue` paths are therefore not declared. A family

that becomes a gap republishes all three, and the enumeration fails until this

contract readmits them — which is the decision being asked for, not an

accident.

What the projection carries beside counts is the bounded public SCV activity

band (`scvs`: a derived public id, a label, a status, a weight, and one

bounded activity line), the forge deploy lane (short shas, statuses, timings,

trip it rather than reading its source: one `forum` post and topic, one

`thread` with a transcript entry, one `push_receipt`, one `box` lease and run,

one `computer`, one `agent` link, one `deployment` request, one

`pull_request`, one `stack` with its entry, and one `issue_dependency` are

seeded and read back through the route in an authenticated session. A family

`pull_request`, one `stack` with its entry, one `issue_dependency`, and one

`reputation` attestation whose subject the account established are seeded and

read back through the route in an authenticated session. A family

whose record stops coming back turns this red, and so does a receipt returned

under a principal that is not the requesting account. `push_receipt` is probed

there rather than against the route inventory: what the account gets back is

themselves travel in the document at every status, so an account can see what

it asked for and what the operator decided.

No family is `blocked` today, which is a result rather than a default: #142

opened the private-repository metadata reads, #143 exported the forge-owned and

forum-owned families, and #165 added the cross-repository read. One family

stays `partial`, and it is not an enumeration problem. A `reputation`

attestation names a `subject_id` the issuer supplies and an `issuer_key_id`

that is the operator's; no column, and no table on this surface, resolves

either to an account, and no route creates an attestation. There is no filter

that would find an account's own attestations, so the ledger records the gap

and issue #171 carries the subject binding. The export names that omission in

its own `not_included` section rather than leaving a recipient to infer it.

No family is `blocked` or `partial` today, which is a result rather than a

default: #142 opened the private-repository metadata reads, #143 exported the

forge-owned and forum-owned families, #165 added the cross-repository read, and

#171 closed the last gap. `reputation` was that gap, and it was never an

enumeration problem. An attestation names its subject with a bare string the

issuer supplies, so what was missing was a binding rather than a query. The

binding is `reputation_subject_claims`, and it resolves a subject the way

`forum_actor_links` resolves a legacy forum identity: a claim an account makes,

an operator decides, and only a `linked` claim resolves. Its unique index is on

`subject_id` alone rather than on the kind and the string together, because an

attestation names its subject with the bare string — so one string resolves to

at most one account, and two accounts cannot both answer to it. The

attestations travel under `repository_work` behind the same `readable_by/2`

join the other three repository-keyed families use, and the `repository` and

`private` transparency tiers stay behind the membership test

`OpenAgentsWeb.ReputationController` applies, so widening the export never

widens disclosure. What the export still omits it names in its own

`not_included` section rather than leaving a recipient to infer it.

The subject kind lives on the claim rather than on the attestation, and that

follows from `REPUTATION-001` rather than from convenience. An attestation's

`subject_id` sits inside the Ed25519-signed claim, so a `subject_kind` column

on `reputation_attestations` would either stay outside the signature — a field

a verifier must not trust — or change the claim shape and invalidate every

signature already published. Three kinds stay distinct, because collapsing them

is what produced a bare string: `account`, whose subject is this forge's own

`user:<account-id>` reference and which the table checks without an operator;

`forum_actor`, which carries the `forum_actor_links` row that established a

legacy identity; and `agent`, which carries the `agents` row. One `CHECK`

constraint states all three rules in SQL, so the shape is the database's

decision rather than a changeset's, and a row inserted past every changeset is

still refused.

Evidence: `OpenAgents.DataRights.ExportInventory`,

`OpenAgents.DataRights.AccountExport`, `OpenAgentsWeb.ApiRouteAuthority`,

`test/openagents/data_rights/export_inventory_test.exs`,

`test/openagents/data_rights/account_export_test.exs`, and

`test/openagents/data_rights/account_export_test.exs`,

`test/openagents/reputation/subject_claim_test.exs`, and

`docs/forge-operator-independence.md`.

### EXIT-002 — Served state is checkable against the WAL with no database

metadata reads answer their own members now. A stack's boundary object ids

travel in that document precisely because a clone cannot fetch the refs holding

them, so the withheld namespace costs the account the refs and not the shape of

its own work. Reputation attestations remain `EXIT-001`'s recorded gap rather

than a claim here, and issue #171 carries them. A single complete invariant

plus a recorded gap is worth more than four that assert less than they appear

to.

its own work. Reputation attestations leave through that document too, now that

#171 bound an attestation subject to an account, and they carry their signed

claim verbatim rather than depending on this invariant to be checkable. One

complete invariant about the Git plane is worth more than four that assert less

than they appear to.

Amended 2026-08-23 (issue #179): the advertised ref set was the whole

population, and it is not what a clone walks. A clone follows every advertised

   collection publishes its own cap; a truncated collection is flagged, and Box

   run output reports the full byte size alongside the capped bytes.

2. Read `"not_included"`. It names the families the document does not carry and

   why, including the one repository-keyed family that has no account-scoped

   read (#171).

   why. Reputation attestations left that list when #171 bound an attestation

   subject to an account; they now travel under `"repository_work"`, and only a

   subject the account holds a `linked` claim on reaches the document.

3. Compare against `OpenAgents.DataRights.ExportInventory`, which `EXIT-001`

   enforces against the surface in both directions, and against the same

   counts published at `GET /api/status` under `independence.export`.

the `blocked` status and its shape checks, because the honest move when a

family becomes unreadable is to record it.

What is reachable and still has no account-scoped read: reputation

attestations. This is the one repository-keyed family issue #165 could not

move, and the reason is not enumeration. An attestation names a `subject_id`

that the issuer supplies and an `issuer_key_id` that is the operator's; no

column, and no table on this surface, resolves either to an account, and no

route creates an attestation. There is no filter that would find an account's

own attestations, so the export names the gap in `not_included` rather than

returning an empty list that reads like an answer. Issue #171 carries the

subject binding that would make the read possible.

Nothing is `partial` today either, and reputation attestations were the last

family to move. Issue #165 could not move them, and the reason was never

enumeration: an attestation names its subject with a bare string the issuer

supplies, so what was missing was a binding rather than a query. Issue #171

added it. `reputation_subject_claims` resolves a subject the way

`forum_actor_links` resolves a legacy forum identity — a claim you make, an

operator decides, and only a `linked` claim resolves — and its unique index on

`subject_id` means one subject never resolves to two accounts. The attestations

travel under `repository_work` behind the same `readable_by/2` join the other

repository-keyed families use, and the `repository` and `private` transparency

tiers stay behind the same membership test the API applies, so a wider export

never means wider disclosure.

Who owns a migrated forum post is the subtle question in the account export,

and it is answered rather than assumed. Two identities resolve to an account:

commits are retained without being advertised; the proof asserts that this is

the *only* omission, so withholding a branch would turn it red.

That is exit for source. It is not yet exit for everything: an account cannot

identify its own reputation attestations, private repository exports are not

encrypted, and no commitment to the WAL is published outside operator storage.

That is exit for source. It is not yet exit for everything: private repository

exports are not encrypted, and no commitment to the WAL is published outside

operator storage.

Those are covered by the gaps above rather than by a claim. Saying so is the

point. Five green invariants that assert less than they appear to would be

worse than five plus a recorded gap.

| Gap | Issue |

| --- | --- |

| The live forge cannot serve a full clone of its own repository | #179 |

| No binding from a reputation attestation's subject to an account, so an account cannot identify its own attestations | #171 |

| No commitment to the WAL is published outside operator storage, so a consistent rewrite still verifies clean | #151 |

| No export is encrypted to a key the recipient holds, and no column is encrypted at rest | #178 |

| Five of six exit rehearsals have never been performed | #180 |

  alias OpenAgents.PullRequests.PullRequest

  alias OpenAgents.Repo

  alias OpenAgents.Repositories

  alias OpenAgents.Repositories.Membership

  alias OpenAgents.Repositories.Repository

  alias OpenAgents.Reputation

  alias OpenAgents.Reputation.Attestation

  alias OpenAgents.Stacks.{Stack, StackEntry}

  alias OpenAgents.Threads.{Event, Thread}

  @maximum_stacks 2_000

  @maximum_stack_entries 10_000

  @maximum_issue_dependencies 5_000

  @maximum_attestations 5_000

  @doc """

  Builds the account's export document.

      "account_actor_ref" => account_actor_ref(user),

      "authored_actor_refs" => refs,

      "claims" => Enum.map(actor_links, &actor_link_export/1),

      "reputation_subject_claims" =>

        user

        |> Reputation.list_subject_claims()

        |> Enum.map(&Reputation.subject_claim_projection/1),

      "resolution_rule" =>

        "A legacy forum identity resolves to this account only through a claim with " <>

          "status \"linked\". Posts under a pending, rejected, or unclaimed actor_ref " <>

          "not a member of reaches this document.",

      "pull_requests" => pull_requests_export(user, readable),

      "stacks" => stacks_export(user, readable),

      "issue_dependencies" => issue_dependencies_export(user, readable)

      "issue_dependencies" => issue_dependencies_export(user, readable),

      "attestations" => attestations_export(user, readable)

    }

  end

  # A reputation attestation names its subject with a bare string, so the

  # filter is the subject binding rather than an authoring column: the strings

  # this account has a `linked` claim on in `reputation_subject_claims`. An

  # account with no linked claim gets nothing, and a subject another account

  # holds is unreachable, because the table's unique index on `subject_id`

  # means one string resolves to at most one account.

  #

  # Disclosure does not widen here. `readable_by/2` admits a public repository

  # to a non-member, and `OpenAgentsWeb.ReputationController` shows such a

  # reader `public` attestations only, so the same membership test gates the

  # `repository` and `private` tiers in this document. The account is active —

  # `build/1` refuses an inactive one — so a membership row is the whole of

  # `Repositories.member?/2` here.

  defp attestations_export(user, readable) do

    subject_ids = Reputation.linked_subject_ids(user)

    rows =

      Repo.all(

        from attestation in Attestation,

          join: repository in subquery(readable),

          on: repository.id == attestation.repository_id,

          left_join: membership in Membership,

          on: membership.repository_id == repository.id and membership.user_id == ^user.id,

          where:

            attestation.subject_id in ^subject_ids and

              (attestation.transparency_tier == "public" or not is_nil(membership.user_id)),

          order_by: [asc: attestation.attested_at, asc: attestation.id],

          limit: ^(@maximum_attestations + 1),

          select: {attestation, repository.owner, repository.name}

      )

    %{

      "subject_resolution_rule" =>

        "An attestation reaches this document only through a reputation subject claim with " <>

          "status \"linked\". The issuer supplies a bare subject_id, so nothing but an " <>

          "established claim says the subject is this account's, and one subject string " <>

          "resolves to at most one account.",

      "established_subjects" => subject_ids,

      "records" => rows |> Enum.take(@maximum_attestations) |> Enum.map(&attestation_export/1),

      "records_truncated" => length(rows) > @maximum_attestations

    }

  end

  # The signed claim travels verbatim beside its signature and the issuer key,

  # so a recipient checks the attestation offline the way

  # `OpenAgentsWeb.ReputationController` lets a stranger check it.

  defp attestation_export({attestation, owner_login, name}) do

    %{

      "id" => attestation.id,

      "repository" => repository_path(owner_login, name),

      "issue_number" => attestation.issue_number,

      "event_type" => attestation.event_type,

      "subject_id" => attestation.subject_id,

      "issuer_key_id" => attestation.issuer_key_id,

      "transparency_tier" => attestation.transparency_tier,

      "claim" => attestation.claim,

      "claim_digest" => attestation.claim_digest,

      "signature" => attestation.signature,

      "signature_algorithm" => attestation.signature_algorithm,

      "revoked" => not is_nil(attestation.revoked_at),

      "revocation_reason_code" => attestation.revocation_reason_code,

      "attested_at" => iso8601(attestation.attested_at)

    }

  end

      "pull_requests" => @maximum_pull_requests,

      "stacks" => @maximum_stacks,

      "stack_entries" => @maximum_stack_entries,

      "issue_dependencies" => @maximum_issue_dependencies

      "issue_dependencies" => @maximum_issue_dependencies,

      "attestations" => @maximum_attestations

    }

  end

        "mechanism" => "git clone with an oa_pat_ token",

        "issue" => nil

      },

      %{

        "family" => "reputation",

        "reason" =>

          "A reputation attestation names a subject_id — a solver identity string the issuer " <>

            "supplies — and nothing on this surface resolves one to an account. The issuer is " <>

            "the operator's admitted signing key, and no route creates an attestation, so " <>

            "there is no record here this account authored and no filter that would find one.",

        "mechanism" => "GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}/attestations",

        "issue" => 171

      },

      %{

        "family" => "forum",

        "reason" =>

          note: String.t()

        }

  # No binding from a reputation subject to an account, #171.

  @reputation_subject_issue 171

  # The account-scoped export of forge-owned and forum-owned records, #143.

  @account_export "GET /data/export/account"

  @account_export_proof {:test, "test/openagents/data_rights/account_export_test.exs"}

        "The prerequisite edges the account recorded, with both issue numbers and " <>

          "the prerequisite's own state, behind the same readable_by gate."

    },

    # ── reachable, but nothing here names an account ──────────────────────

    %{

      family: :reputation,

      api?: true,

      status: :partial,

      mechanism: "GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}/attestations",

      proof: nil,

      issue: @reputation_subject_issue,

      status: :portable,

      mechanism: @account_export,

      proof: @account_export_proof,

      issue: nil,

      note:

        "The only family #165 could not move. An attestation names a subject_id " <>

          "the issuer supplies and an issuer_key_id that is the operator's; no " <>

          "column, and no table on this surface, resolves either to an account. " <>

          "There is no filter that would find an account's own attestations, so " <>

          "the export names the gap instead of returning an empty list."

        "An attestation names its subject with a bare string the issuer supplies, " <>

          "so the filter is a binding rather than an authoring column: the " <>

          "subject strings the account holds a linked claim on in " <>

          "reputation_subject_claims, #171. The table's unique index on " <>

          "subject_id means one string resolves to at most one account. The " <>

          "records travel under repository_work behind the same readable_by " <>

          "gate, and the repository and private tiers stay behind the membership " <>

          "test OpenAgentsWeb.ReputationController applies."

    },

    # ── not a record a user authors and takes with them ───────────────────

      state. It trusts no column and no caller.

    * `revoke/4` and `correct/4` publish a linked invalidating event.

  A subject is a bare string inside the signed claim, so the context also

  owns the binding that resolves one to an account: `claim_subject/2`,

  `approve_subject_claim/1`, and `reject_subject_claim/1`. Only a `linked`

  claim resolves a subject, and `linked_subject_ids/1` is the one filter an

  account-scoped read may use.

  Reads project the stored claim verbatim, so a client can verify an

  attestation the forge serves without trusting the surface that displayed it.

  """

  alias OpenAgents.Provenance.Canonical

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.Repository

  alias OpenAgents.Reputation.{Attestation, Claim, PolicyReceipt, SigningKey}

  alias OpenAgents.Accounts.User

  alias OpenAgents.Forum.ActorLink

  alias OpenAgents.Reputation.{Attestation, Claim, PolicyReceipt, SigningKey, SubjectClaim}

  @policy_id "openagents.reputation.verifier.v1"

  @policy_version 1

    }

  end

  ## ── the subject binding ────────────────────────────────────────────────

  @doc """

  Records an account's claim on an attestation subject.

  The claim starts `pending`: nothing has established that the subject is this

  account's, so nothing resolves yet. `attributes` carries `:subject_kind`,

  `:subject_id`, and for the two kinds that name another namespace, the row

  that already established the identity — `:forum_actor_link_id` for a legacy

  forum actor, `:agent_id` for an agent.

  The cross-namespace checks live here because a `CHECK` constraint cannot read

  another table: a `forum_actor` claim must name a `linked` `forum_actor_links`

  row belonging to this account whose `actor_ref` is the subject, and an

  `agent` claim must name a `linked` `agent_user_links` row for this account.

  The shape checks — which kind admits which reference, and that an `account`

  subject is this account's own actor reference — are constraints on the table.

  """

  @spec claim_subject(User.t(), map()) :: {:ok, SubjectClaim.t()} | {:error, term()}

  def claim_subject(%User{} = user, attributes) do

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

    with :ok <- validate_subject_reference(user, attributes) do

      %SubjectClaim{}

      |> SubjectClaim.changeset(

        Map.merge(attributes, %{

          "user_id" => user.id,

          "status" => "pending",

          "proof_evidence" => %{"started_at" => DateTime.to_iso8601(DateTime.utc_now())}

        })

      )

      |> Repo.insert()

    end

  end

  @doc "Approves a pending subject claim after its proof has been checked."

  @spec approve_subject_claim(SubjectClaim.t()) :: {:ok, SubjectClaim.t()} | {:error, term()}

  def approve_subject_claim(%SubjectClaim{status: "pending"} = claim) do

    now = DateTime.utc_now()

    claim

    |> SubjectClaim.changeset(%{

      status: "linked",

      linked_at: now,

      proof_evidence:

        Map.put(claim.proof_evidence || %{}, "approved_at", DateTime.to_iso8601(now))

    })

    |> Repo.update()

  end

  def approve_subject_claim(%SubjectClaim{}), do: {:error, :not_pending}

  @doc "Rejects a pending subject claim."

  @spec reject_subject_claim(SubjectClaim.t()) :: {:ok, SubjectClaim.t()} | {:error, term()}

  def reject_subject_claim(%SubjectClaim{status: "pending"} = claim) do

    claim

    |> SubjectClaim.changeset(%{status: "rejected", rejected_at: DateTime.utc_now()})

    |> Repo.update()

  end

  def reject_subject_claim(%SubjectClaim{}), do: {:error, :not_pending}

  @doc "Every subject claim this account made, newest first."

  @spec list_subject_claims(User.t()) :: [SubjectClaim.t()]

  def list_subject_claims(%User{id: user_id}) do

    Repo.all(

      from claim in SubjectClaim,

        where: claim.user_id == ^user_id,

        order_by: [desc: claim.inserted_at, desc: claim.id]

    )

  end

  @doc "Every subject claim still waiting on an operator, oldest first."

  @spec list_pending_subject_claims() :: [SubjectClaim.t()]

  def list_pending_subject_claims do

    Repo.all(

      from claim in SubjectClaim,

        where: claim.status == "pending",

        order_by: [asc: claim.inserted_at, asc: claim.id]

    )

  end

  @doc "The subject claim behind `id`, or `{:error, :not_found}`."

  @spec fetch_subject_claim(String.t()) :: {:ok, SubjectClaim.t()} | {:error, :not_found}

  def fetch_subject_claim(id) do

    case Ecto.UUID.cast(id) do

      {:ok, uuid} ->

        case Repo.get(SubjectClaim, uuid) do

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

          nil -> {:error, :not_found}

        end

      :error ->

        {:error, :not_found}

    end

  end

  @doc """

  The subject strings this account has established.

  Only a `linked` claim resolves a subject, so a pending or rejected claim

  widens nothing. An account with no linked claim gets `[]`, and a read

  filtered on `[]` returns nothing rather than everything.

  """

  @spec linked_subject_ids(User.t()) :: [String.t()]

  def linked_subject_ids(%User{id: user_id}) do

    Repo.all(

      from claim in SubjectClaim,

        where: claim.user_id == ^user_id and claim.status == "linked",

        select: claim.subject_id,

        order_by: [asc: claim.subject_id]

    )

  end

  @doc "The public projection of one subject claim."

  @spec subject_claim_projection(SubjectClaim.t()) :: map()

  def subject_claim_projection(%SubjectClaim{} = claim) do

    %{

      "id" => claim.id,

      "subject_kind" => claim.subject_kind,

      "subject_id" => claim.subject_id,

      "status" => claim.status,

      "proof_method" => claim.proof_method,

      "forum_actor_link_id" => claim.forum_actor_link_id,

      "agent_id" => claim.agent_id,

      "claimed_at" => iso8601(claim.inserted_at),

      "linked_at" => iso8601(claim.linked_at),

      "rejected_at" => iso8601(claim.rejected_at)

    }

  end

  defp iso8601(nil), do: nil

  defp iso8601(%DateTime{} = at), do: DateTime.to_iso8601(at)

  # An `account` subject is checked by the table: the string has to be this

  # account's own actor reference. The other two kinds name a row in another

  # namespace, and only a link that namespace already established counts.

  defp validate_subject_reference(_user, %{"subject_kind" => "account"}), do: :ok

  defp validate_subject_reference(user, %{"subject_kind" => "forum_actor"} = attributes) do

    link =

      Repo.get_by(ActorLink,

        id: cast_uuid(attributes["forum_actor_link_id"]),

        user_id: user.id,

        status: "linked"

      )

    cond do

      is_nil(link) -> {:error, :forum_actor_not_linked}

      link.actor_ref != attributes["subject_id"] -> {:error, :subject_is_not_the_actor_ref}

      true -> :ok

    end

  end

  defp validate_subject_reference(user, %{"subject_kind" => "agent"} = attributes) do

    linked? =

      Repo.exists?(

        from link in OpenAgents.Agents.AgentUserLink,

          where:

            link.agent_id == ^cast_uuid(attributes["agent_id"]) and

              link.user_id == ^user.id and link.status == "linked"

      )

    if linked?, do: :ok, else: {:error, :agent_not_linked}

  end

  defp validate_subject_reference(_user, _attributes), do: {:error, :unsupported_subject_kind}

  defp cast_uuid(value) do

    case Ecto.UUID.cast(value) do

      {:ok, uuid} -> uuid

      :error -> Ecto.UUID.generate()

    end

  end

  defp persist(policy, key, signer, repository, outcome, evidence, attributes) do

    attested_at = attributes[:attested_at] || DateTime.utc_now()

defmodule OpenAgents.Reputation.SubjectClaim do

  @moduledoc """

  One account's claim on one attestation subject.

  `OpenAgents.Reputation.Attestation` names its subject with a bare string the

  issuer supplies. This row says what that string names and which account holds

  it, and only a `linked` status resolves it — the rule

  `OpenAgents.Forum.ActorLink` already applies to a legacy forum identity.

  A subject is one of three things, and collapsing them is what produced a bare

  string in the first place:

    * `account` — this forge's own actor reference, `user:<account-id>`. The

      string names the account, so the database checks it rather than an

      operator.

    * `forum_actor` — a legacy forum identity that may have no account of its

      own. The claim carries the `forum_actor_links` row that established it.

    * `agent` — a registered agent. The claim carries the `agents` row.

  The kind is not on the attestation. An attestation's `subject_id` is inside

  the signed claim, so a kind column there would either go unsigned or

  invalidate every published signature.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  alias OpenAgents.Agents.Agent

  alias OpenAgents.Forum.ActorLink

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

  @foreign_key_type :binary_id

  @subject_kinds ~w(account forum_actor agent)

  @statuses ~w(pending linked rejected)

  schema "reputation_subject_claims" do

    field :subject_kind, :string

    field :subject_id, :string

    field :status, :string, default: "pending"

    field :proof_method, :string

    field :proof_evidence, :map

    field :linked_at, :utc_datetime_usec

    field :rejected_at, :utc_datetime_usec

    belongs_to :user, User

    belongs_to :forum_actor_link, ActorLink

    belongs_to :agent, Agent

    timestamps(type: :utc_datetime_usec)

  end

  @type t :: %__MODULE__{}

  def subject_kinds, do: @subject_kinds

  def statuses, do: @statuses

  def changeset(claim, attributes) do

    claim

    |> cast(

      attributes,

      ~w(subject_kind subject_id user_id forum_actor_link_id agent_id status proof_method

         proof_evidence linked_at rejected_at)a

    )

    |> validate_required(~w(subject_kind subject_id user_id status)a)

    |> validate_inclusion(:subject_kind, @subject_kinds)

    |> validate_inclusion(:status, @statuses)

    |> validate_length(:subject_id, min: 1, max: 256)

    |> unique_constraint(:subject_id)

    |> foreign_key_constraint(:user_id)

    |> foreign_key_constraint(:forum_actor_link_id)

    |> foreign_key_constraint(:agent_id)

    |> check_constraint(:subject_kind, name: :reputation_subject_claims_kind_check)

    |> check_constraint(:status, name: :reputation_subject_claims_status_check)

    |> check_constraint(:subject_id, name: :reputation_subject_claims_reference_check)

  end

end

      "delete /api/v3/agents/links/:id" => {:required_bearer, :agent, :legacy},

      "post /api/v3/forum/claims" => {:required_bearer, :forum, :legacy},

      "get /api/v3/forum/claims" => {:required_bearer, :forum, :legacy},

      "post /api/v3/reputation/subject-claims" => {:required_bearer, :reputation, :legacy},

      "get /api/v3/reputation/subject-claims" => {:required_bearer, :reputation, :legacy},

      "get /api/v3/reputation/subject-claims/pending" => {:required_bearer, :reputation, :legacy},

      "patch /api/v3/reputation/subject-claims/:id" => {:required_bearer, :reputation, :legacy},

      # Moderation and claim review: a bearer the controller then checks for

      # operator authority.

      "patch /api/v3/forum/topics/:id" => {:required_bearer, :forum, :legacy},

  read the revocation state without trusting this API or the web interface.

  Disclosure follows the repository: a reader outside the repository sees

  `public` attestations only.

  An attestation names its subject with a bare string. The subject-claim

  actions here are how an account establishes which strings are its own — it

  asks, and an operator decides — so that an account-scoped read such as

  `GET /data/export/account` has a filter that resolves rather than guesses.

  """

  use OpenAgentsWeb, :controller

  alias OpenAgents.Accounts

  alias OpenAgents.Reputation

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.ControllerHelpers

    Ecto.NoResultsError -> not_found(conn)

  end

  ## Subject claims

  @doc "Records this account's claim on an attestation subject."

  def create_subject_claim(conn, %{"subject_kind" => kind, "subject_id" => subject_id} = params)

      when is_binary(kind) and is_binary(subject_id) do

    attributes = %{

      "subject_kind" => kind,

      "subject_id" => String.trim(subject_id),

      "forum_actor_link_id" => params["forum_actor_link_id"],

      "agent_id" => params["agent_id"],

      "proof_method" => params["proof_method"] || "api_token"

    }

    case Reputation.claim_subject(conn.assigns.current_user, attributes) do

      {:ok, claim} ->

        conn

        |> put_status(:created)

        |> json(Reputation.subject_claim_projection(claim))

      {:error, %Ecto.Changeset{} = changeset} ->

        unprocessable(conn, changeset_message(changeset))

      {:error, reason} ->

        unprocessable(conn, Atom.to_string(reason))

    end

  end

  def create_subject_claim(conn, _params),

    do: unprocessable(conn, "subject_kind and subject_id are required")

  @doc "Every subject claim this account made, at every status."

  def list_subject_claims(conn, _params) do

    claims = Reputation.list_subject_claims(conn.assigns.current_user)

    json(conn, %{"claims" => Enum.map(claims, &Reputation.subject_claim_projection/1)})

  end

  @doc "Every subject claim waiting on review. Operators only."

  def pending_subject_claims(conn, _params) do

    case ensure_operator(conn) do

      :ok ->

        claims = Reputation.list_pending_subject_claims()

        json(conn, %{"claims" => Enum.map(claims, &Reputation.subject_claim_projection/1)})

      {:error, :forbidden} ->

        forbidden(conn)

    end

  end

  @doc "Approves or rejects a pending subject claim. Operators only."

  def update_subject_claim(conn, %{"id" => id, "status" => status}) do

    with :ok <- ensure_operator(conn),

         {:ok, claim} <- Reputation.fetch_subject_claim(id),

         {:ok, claim} <- review_subject_claim(claim, status) do

      json(conn, Reputation.subject_claim_projection(claim))

    else

      {:error, :forbidden} -> forbidden(conn)

      {:error, :not_found} -> not_found(conn)

      {:error, :invalid_status} -> unprocessable(conn, "status must be linked or rejected")

      {:error, :not_pending} -> conflict(conn, "claim_not_pending")

      {:error, %Ecto.Changeset{} = changeset} -> unprocessable(conn, changeset_message(changeset))

    end

  end

  def update_subject_claim(conn, _params),

    do: unprocessable(conn, "status must be linked or rejected")

  defp ensure_operator(conn) do

    if Accounts.admin?(conn.assigns[:current_user]), do: :ok, else: {:error, :forbidden}

  end

  defp review_subject_claim(claim, "linked"), do: Reputation.approve_subject_claim(claim)

  defp review_subject_claim(claim, "rejected"), do: Reputation.reject_subject_claim(claim)

  defp review_subject_claim(_claim, _status), do: {:error, :invalid_status}

  defp changeset_message(changeset) do

    changeset

    |> Ecto.Changeset.traverse_errors(fn {message, _opts} -> message end)

    |> Enum.map_join("; ", fn {field, messages} ->

      "#{field} #{Enum.join(messages, ", ")}"

    end)

  end

  defp unprocessable(conn, message),

    do: conn |> put_status(:unprocessable_entity) |> json(%{"message" => message})

  defp conflict(conn, message),

    do: conn |> put_status(:conflict) |> json(%{"message" => message})

  defp forbidden(conn), do: conn |> put_status(:forbidden) |> json(%{"message" => "Forbidden"})

  # What the caller believes it is looking at. A mismatch is reported rather

  # than corrected, which is how a replayed attestation fails for a client

  # that names the issue, revision, subject, or verifier it expects.

    post "/forum/claims", ForumApiController, :create_claim

    get "/forum/claims", ForumApiController, :list_claims

    # Reputation subject claims. An attestation names its subject with a bare

    # string, so an account establishes which strings are its own the way it

    # claims a legacy forum identity: it asks, and an operator decides.

    post "/reputation/subject-claims", ReputationController, :create_subject_claim

    get "/reputation/subject-claims", ReputationController, :list_subject_claims

    # Claim review. The controller refuses a non-operator token.

    get "/reputation/subject-claims/pending", ReputationController, :pending_subject_claims

    patch "/reputation/subject-claims/:id", ReputationController, :update_subject_claim

    # Moderation and claim review. The controller refuses a non-operator token.

    get "/forum/claims/pending", ForumApiController, :pending_claims

    patch "/forum/claims/:id", ForumApiController, :update_claim

    20260823221416,

    20260824010337,

    20260824010826,

    20260824011303

    20260824011303,

    20260824024146

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.CreateReputationSubjectClaims do

  use Ecto.Migration

  @moduledoc """

  Binds an attestation subject to an account.

  `reputation_attestations.subject_id` is a bare string the issuer supplies.

  Nothing resolved it, and nothing stopped it from resolving to two things.

  This table is the binding: a claim an account makes and an operator decides,

  the way `forum_actor_links` resolves a legacy forum identity.

  The kind lives here rather than on the attestation. The attestation's

  `subject_id` sits inside the Ed25519-signed claim, so a `subject_kind`

  column on `reputation_attestations` would either stay outside the signature

  — a field a verifier must not trust — or change the claim shape and

  invalidate every signature already published. REPUTATION-001 keeps

  verification independent of the interface, so the typing goes where a

  verifier never has to read it.

  """

  def change do

    create table(:reputation_subject_claims, primary_key: false) do

      add :id, :uuid, primary_key: true, default: fragment("gen_random_uuid()")

      # What the string names: an account on this forge, a legacy forum actor

      # that may have no account of its own, or a registered agent. Collapsing

      # the three is how a bare string got here.

      add :subject_kind, :string, null: false

      # The exact string `reputation_attestations.subject_id` carries.

      add :subject_id, :string, null: false

      add :user_id, references(:users, type: :uuid, on_delete: :restrict), null: false

      # The row in the namespace that already established this identity. One

      # per kind, and null for the kinds it does not describe.

      add :forum_actor_link_id, references(:forum_actor_links, type: :uuid, on_delete: :restrict)

      add :agent_id, references(:agents, type: :binary_id, on_delete: :restrict)

      add :status, :string, null: false, default: "pending"

      add :proof_method, :string

      add :proof_evidence, :map

      add :linked_at, :utc_datetime_usec

      add :rejected_at, :utc_datetime_usec

      timestamps(type: :utc_datetime_usec)

    end

    # A subject already claimed by one account cannot be claimed by another.

    # An attestation names its subject with the bare string, so the string

    # alone — not the kind and the string together — is what has to resolve to

    # at most one account. Two kinds carrying one string would put the

    # ambiguity straight back.

    create unique_index(:reputation_subject_claims, [:subject_id])

    create index(:reputation_subject_claims, [:user_id, :status])

    create constraint(:reputation_subject_claims, :reputation_subject_claims_kind_check,

             check: "subject_kind IN ('account', 'forum_actor', 'agent')"

           )

    create constraint(:reputation_subject_claims, :reputation_subject_claims_status_check,

             check: "status IN ('pending', 'linked', 'rejected')"

           )

    # One constraint per kind, in the database rather than in a changeset.

    # An `account` subject names the account itself, so the string is checkable

    # here and the operator has nothing to decide beyond that it is well

    # formed. A `forum_actor` or `agent` subject names a row in another

    # namespace, so the claim has to carry that row.

    create constraint(:reputation_subject_claims, :reputation_subject_claims_reference_check,

             check: """

             CASE subject_kind

               WHEN 'account' THEN

                 forum_actor_link_id IS NULL AND agent_id IS NULL

                 AND subject_id = 'user:' || user_id::text

               WHEN 'forum_actor' THEN

                 forum_actor_link_id IS NOT NULL AND agent_id IS NULL

               WHEN 'agent' THEN

                 agent_id IS NOT NULL AND forum_actor_link_id IS NULL

               ELSE false

             END

             """

           )

  end

end

  alias OpenAgents.PullRequests.PullRequest

  alias OpenAgents.Repo

  alias OpenAgents.Repositories

  alias OpenAgents.Reputation

  alias OpenAgents.Stacks

  alias OpenAgents.Threads

      end

      families = Enum.map(export["not_included"], & &1["family"])

      assert "reputation" in families

      # `reputation` left this list when #171 gave the subject a binding.

      refute "reputation" in families

      assert "repository_content" in families

      assert "conversation" in families

  # something a person can read — a repository path, a topic and board slug, an

  # issue number, an agent handle — rather than only by a UUID this forge would

  # have to resolve. Replacing any of those with an id alone turns this red.

  describe "a reputation attestation's subject" do

    test "an attestation naming a subject this account established comes back" do

      user = github_user("account-export-attest", "export-attest")

      repository = private_repository_with_member("export-attest-private", user)

      issue = OpenAgents.IssuesFixtures.issue_fixture(repository, %{title: "Attested"})

      link_subject!(user, "user:" <> user.id)

      attestation = attest!(repository, issue, "user:" <> user.id, "repository")

      assert {:ok, export} = AccountExport.build(user)

      work = export["repository_work"]

      assert [record] = work["attestations"]["records"]

      assert record["id"] == attestation.id

      assert record["subject_id"] == "user:" <> user.id

      assert record["repository"] == repository.owner <> "/" <> repository.name

      assert record["issue_number"] == issue.number

      assert record["transparency_tier"] == "repository"

      refute work["attestations"]["records_truncated"]

      # The signed claim travels verbatim, so the recipient checks it offline.

      assert record["claim"]["subject"]["actor_id"] == "user:" <> user.id

      assert record["claim_digest"] == attestation.claim_digest

      assert OpenAgents.Reputation.Claim.valid_signature?(

               record["claim"],

               record["signature"],

               issuer_public_key(attestation)

             )

      assert work["attestations"]["established_subjects"] == ["user:" <> user.id]

      assert work["attestations"]["subject_resolution_rule"] =~ "linked"

    end

    # Without the linked-claim filter this attestation would come back to

    # whoever asked. Dropping `Reputation.linked_subject_ids/1` from

    # `attestations_export/2` turns this red.

    test "an attestation whose subject the account has not established stays behind" do

      user = github_user("account-export-attest-none", "export-attest-none")

      repository = private_repository_with_member("export-attest-none-private", user)

      issue = OpenAgents.IssuesFixtures.issue_fixture(repository, %{title: "Not mine"})

      _attestation = attest!(repository, issue, "actor:someone-else", "repository")

      assert {:ok, export} = AccountExport.build(user)

      assert export["repository_work"]["attestations"]["records"] == []

      assert export["repository_work"]["attestations"]["established_subjects"] == []

    end

    test "a pending claim resolves nothing, and only the operator's decision does" do

      user = github_user("account-export-attest-pending", "export-attest-pending")

      repository = private_repository_with_member("export-attest-pending-private", user)

      issue = OpenAgents.IssuesFixtures.issue_fixture(repository, %{title: "Pending"})

      {:ok, claim} =

        Reputation.claim_subject(user, %{

          subject_kind: "account",

          subject_id: "user:" <> user.id

        })