`test/openagents_web/controllers/memory_controller_test.exs`, and

`test/openagents_web/controllers/responses_controller_test.exs`.

### MEMORY-011 — A system memory is evidenced, admitted by receipt, and surfaced to nobody

### MEMORY-011 — A system memory is evidenced, admitted by receipt, contested by record, and surfaced to nobody

Status: Current

absent evidence list is exactly the hole the constraint exists to close.

Admission is a receipt, never a field. A verdict is a row in

`memory_admissions` — attributed to the steward who wrote it, dated, and

append-only, with no `updated_at` and no path that updates one — and

`memory_admissions` — attributed through `author_id` to the account that wrote

it, dated, and append-only, with no `updated_at` and no path that updates one —

and

`OpenAgents.Memories.Admissions.status/1` derives the effective status from

those records. The `admission` column on the candidate is the author's claim

and nothing more, so a row that says `admitted` with no steward record behind

writes a superseding row on a system slug; anyone else is refused, and

supersession is the only correction path there is.

Neither path reads another account's memory. An admission record proves its

candidate is a system row through the composite foreign key

Disagreement is a record too. Any account may write a **challenge** against a

system memory — slug `chl:<memory>`, role `challenge`, a ground, and optional

evidence of its own — and a challenge that carries evidence suspends an

admitted target until it is resolved. That is the fail-safe direction: a

contested claim silently absent is cheaper than a poisoned claim silently

present. An unevidenced challenge is recorded and changes nothing, so an empty

evidence list is refused at the table rather than read as absence. Two

resolutions, both steward-only: a **refutation** of one challenge (slug

`ref:<challenge>`, role `refutation`), or a superseding row on the target's

slug, which records a refutation of each open challenge in the same

transaction so the resolution is a receipt rather than an inference. A

refutation from a non-steward account is refused on the role, before the

challenge is read. A reversal is a further challenge; nothing is ever edited.

The derived status — `candidate`, `admitted`, `rejected`, or `suspended` —

follows from the set of records and not from the order they arrived in. Every

ordering the derivation uses is over `{inserted_at, id}`, which is data on the

records, and resolution is set membership rather than a comparison of dates, so

a refutation backfilled earlier than its challenge still resolves it and every

permutation of one record set derives one answer.

One account's open evidenced challenges suspend at most 25% of the admitted

store, rounded up; the earliest by `{inserted_at, id}` take effect and the rest

queue with no recall effect. Stated without overstatement: with one server and

no anonymous publisher there is no forged attribution, so this bounds a

prolific or systematically wrong challenger rather than defending against an

attack, and it is a bound on the store rather than on the per-message recall

pool of specification section 7.2, which does not exist until recall reads this

bucket.

None of these paths reads another account's memory. An admission or challenge

record proves its target is a system row through the composite foreign key

`(memory_id, memory_bucket) -> memories (id, bucket)` rather than through a

lookup, and a correction authorizes inside the `UPDATE` predicate — the actor's

own `user_id` or the steward role — so a caller with no standing is refused

without learning that the row exists. MEMORY-010's rule that every query rooted

at `OpenAgents.Memories.Memory` names `user_id` holds unchanged, and the AST

proof reads this module too.

lookup; a refutation is held to a challenge against the memory it restores by

the composite foreign key

`(challenge_id, memory_id, challenge_role) -> (id, memory_id, role)`, which is

why `challenge_role` carries the literal the check constraint pins; and a

correction authorizes inside the `UPDATE` predicate — the actor's own `user_id`

or the steward role — so a caller with no standing is refused without learning

that the row exists. MEMORY-010's rule that every query rooted at

`OpenAgents.Memories.Memory` names `user_id` holds unchanged, and the AST proof

reads this module too.

Nothing surfaces. `OpenAgents.Memories.recall/3` reads the `user` and `learned`

buckets, named as a predicate in the query rather than filtered out of its

result, and no session sees a system memory — not another account's, and not

its own author's. That is deliberate and it is the whole reason this invariant

its own author's, and not one of any derived status: admitted, suspended, and

challenged rows all reach the same number of turns. A challenged memory nobody

can see is still a coherent state; the point of recording the challenge is that

a wrong admitted claim has a path other than editing someone else's row, and

that a contested claim is marked before an eligibility filter exists to read

the mark. That is deliberate and it is the whole reason this invariant

can stand beside MEMORY-001 and MEMORY-010 rather than amending them: an

admitted row read into every account's turn is cross-account recall by

construction, so surfacing the bucket is a privacy decision with an eligibility

widened recall predicate is not.

Evidence: `OpenAgents.Memories.Admissions`, `OpenAgents.Memories.Admission`,

`OpenAgents.Memories.Memory`, the `memories_system_shape` and

`memory_admissions_shape` constraints and the composite foreign key

`memory_admissions_memory_fkey`, and

`test/openagents/memories/system_memory_test.exs`.

`OpenAgents.Memories.Memory`, `OpenAgents.Memories.Evidence`, the

`memories_system_shape` and `memory_admissions_shape` constraints and the

composite foreign keys `memory_admissions_memory_fkey` and

`memory_admissions_challenge_fkey`,

`test/openagents/memories/system_memory_test.exs`, and

`test/openagents/memories/challenge_test.exs`.

### PRIVACY-001 — Secret-bearing profile memory is rejected, never scrub-stored

  `OpenAgents.ProfileMemory.forget_active/2`, which supersedes rather than

  deletes, so a retraction is another entry in the audit trail the same

  surface renders and never a row that quietly stops existing.

- Admitting or rejecting a candidate system memory, and correcting an admitted

  one, through `OpenAgents.Memories.Admissions` (MEMORY-011). Only a steward

  admits, and the steward set is this allowlist, bootstrapped to the owner's

  account. The write appends: an admission record is inserted and never

  updated, and a correction supersedes rather than edits, so a reversal is a

  second record beside the first rather than a verdict that quietly changed.

  The authority buys no read — the operator sees no memory of another account

  through this module.

- Admitting or rejecting a candidate system memory, refuting a challenge

  against one, and correcting an admitted one, through

  `OpenAgents.Memories.Admissions` (MEMORY-011). Only a steward admits and only

  a steward refutes, and the steward set is this allowlist, bootstrapped to the

  owner's account. Challenging is the one path here that needs no authority:

  any account may record that an admitted claim is wrong, which is the whole

  reason the record exists. The write appends: every record is inserted and

  never updated, and a correction supersedes rather than edits, so a reversal

  is a second record beside the first rather than a verdict that quietly

  changed. The authority buys no read — the operator sees no memory of another

  account through this module.

- Recording Gym runs and trials under `POST /api/v1/gym/runs`, the lifecycle

  routes `POST /api/v1/gym/runs/start`, `POST /api/v1/gym/runs/:id/trials`,

  and `PATCH /api/v1/gym/runs/:id`

| MEMORY-008 | `test/openagents/experience_memory_test.exs` |

| MEMORY-009 | `test/openagents/graph_memory_test.exs` |

| MEMORY-010 | `test/openagents/memories_test.exs`, `test/openagents_web/controllers/memory_controller_test.exs`, `test/openagents_web/controllers/responses_controller_test.exs` |

| MEMORY-011 | `test/openagents/memories/system_memory_test.exs` |

| MEMORY-011 | `test/openagents/memories/system_memory_test.exs`, `test/openagents/memories/challenge_test.exs` |

| PRIVACY-001 | `test/openagents/memory/policy_and_redaction_test.exs`, `test/openagents/memory/scope_boundary_test.exs` |

| TURN-001 | `test/openagents/conversations_test.exs` |

| TURN-002 | `test/openagents/conversations_test.exs` |

memory is stored, evidenced, and admitted, and surfaced to no session yet

(MEMORY-011).

**Challenge** and **refutation** — the two other records in that table. A

*challenge* is any account's statement that an admitted system memory is wrong;

one carrying evidence of its own is an *evidenced challenge*, and only an

evidenced challenge suspends its target. A *refutation* is a steward's

resolution of one challenge. Say "suspended" for the status an open evidenced

challenge derives, not "rejected" — a rejection is a steward's verdict on a

candidate, and a suspension is a claim that was admitted and is now contested.

Say "queued" for a challenge held back by the flood cap: it is recorded and

attributed, and it has no effect on any status.

### Threads

A **thread** is the unit of agent work. Everything in this section describes a

  nothing should — a store that fills itself is a store nobody trusts.

  `learned` memories come from server-side consolidation over thread events.

  `system` memories are what the network as a whole has learned, and they pass

  an evidence-backed admission gate before they mean anything

  an evidence-backed admission gate before they mean anything, and can be

  challenged and resolved by further records afterwards

  (`OpenAgents.Memories.Admissions`). `recall/3` reads the first two only.

  ## Corrections supersede

  cut excluded is counted rather than dropped in silence.

  The `system` bucket is not read here, by anyone, including its own author.

  A system memory is stored and admitted (`OpenAgents.Memories.Admissions`) and

  surfaced to nobody: an admitted row reaches every account's turn or none, and

  A system memory is stored, admitted, and contestable

  (`OpenAgents.Memories.Admissions`) and surfaced to nobody, whatever status

  its records derive: an admitted row reaches every account's turn or none, and

  the first is cross-account recall, which MEMORY-001 and MEMORY-010 forbid.

  The bucket list is a predicate in the query rather than a filter applied to

  its results, so widening it is a deliberate edit to the recall issue's

defmodule OpenAgents.Memories.Admission do

  @moduledoc """

  One verdict on one candidate system memory, and the ground for it.

  Admission is a receipt, not an assertion. The registry does not turn a

  promise green because someone said so, and the memory store does not admit a

  claim because its author wrote `admitted` on it: the record here is what a

  status is derived from, and the `admission` field on the candidate is only

  what the author claimed.

  The record is append-only. There is no `updated_at` and nothing updates one,

  so a steward who changes their mind writes a second record rather than

  editing the first, and both stay readable.

  One record about one system memory: a verdict on it, a challenge to it, or a

  refutation of a challenge.

  All three are receipts, not assertions. The registry does not turn a promise

  green because someone said so, and the memory store does not admit a claim

  because its author wrote `admitted` on it: the records here are what a status

  is derived from, and the `admission` field on the candidate is only what the

  author claimed.

  Every record is append-only. There is no `updated_at` and nothing updates

  one, so a steward who changes their mind writes a second record rather than

  editing the first, and both stay readable. A reversal is a further record for

  the same reason: it is how the store keeps the argument rather than the last

  word in it.

  ## The three roles

  * `admission` — a steward's verdict, `admitted` or `rejected`, slug

    `adm:<memory>`. Only a steward writes one.

  * `challenge` — any account's statement that the claim is wrong, slug

    `chl:<memory>`. A challenge carrying its own `evidence_refs` is an

    *evidenced* challenge and suspends its target; one without is recorded and

    changes nothing.

  * `refutation` — a steward's resolution of one challenge, slug

    `ref:<challenge>`, restoring the target. Only a steward writes one.

  `author_id` is who wrote the record, whichever role it carries. The column

  was `steward_id` while `admission` was the only role written; anyone may

  challenge, so the steward rule lives at the write path rather than in a

  column name that would be wrong on two roles out of three.

  ## What the database holds rather than the changeset

  `memory_bucket` rides the row so the composite foreign key

  `(memory_id, memory_bucket) -> memories (id, bucket)` can pin the candidate

  to the `system` bucket. That is what lets the write path refuse an admission

  record naming a `user` or `learned` row without reading `memories` at all,

  which is how the admission path stays clear of the account boundary

  MEMORY-010 draws.

  `role` names the three record roles the specification adds. Only `admission`

  is written today; `challenge` and `refutation` are the same enum and land

  with the issue that owns them.

  `(memory_id, memory_bucket) -> memories (id, bucket)` can pin the target to

  the `system` bucket. That is what lets a write refuse a record naming a

  `user` or `learned` row without reading `memories` at all, which is how these

  paths stay clear of the account boundary MEMORY-010 draws.

  `challenge_role` is always the literal `challenge` on a refutation and null

  elsewhere. It exists so the second composite foreign key,

  `(challenge_id, memory_id, challenge_role) -> (id, memory_id, role)`, can

  insist that a refutation names a challenge — and one against the same memory

  it claims to restore. PostgreSQL will not put a literal in a foreign key, so

  the literal is a column the `memory_admissions_shape` constraint pins.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  alias OpenAgents.Memories.Memory

  alias OpenAgents.Memories.{Evidence, Memory}

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

  @foreign_key_type :binary_id

  schema "memory_admissions" do

    belongs_to :memory, Memory

    field :memory_bucket, :string, default: "system"

    belongs_to :steward, User

    belongs_to :author, User

    belongs_to :challenge, __MODULE__

    field :challenge_role, :string

    field :slug, :string

    field :role, :string, default: "admission"

    field :verdict, :string

    field :ground, :string

    field :evidence_refs, {:array, :map}

    timestamps(updated_at: false)

  end

  def ground_characters, do: @ground_characters

  @doc """

  Validates one admission record.

  Whether this record is an evidenced challenge.

  The one distinction recall turns on: an evidenced challenge suspends its

  target, an unevidenced one is recorded and changes nothing. An empty list

  cannot reach the table, so absence is the only unevidenced shape there is.

  """

  @spec evidenced_challenge?(t()) :: boolean()

  def evidenced_challenge?(%__MODULE__{role: "challenge", evidence_refs: [_first | _rest]}),

    do: true

  def evidenced_challenge?(%__MODULE__{}), do: false

  @doc """

  Validates one admission record: a steward's verdict on a candidate.

  The steward and the candidate are set on the struct rather than cast, so a

  The author and the target are set on the struct rather than cast, so a

  request body can name neither who admitted nor, by extension, on whose

  authority.

  """

  def changeset(record, attrs) do

    record

    |> cast(attrs, [:verdict, :ground])

    |> put_role("admission")

    |> put_slug(:memory_id, "adm:")

    |> validate_required([:verdict])

    |> validate_inclusion(:verdict, @verdicts)

    |> validate_shape()

  end

  @doc """

  Validates one challenge: any account's statement that an admitted claim is

  wrong, and the ground for saying so.

  `evidence_refs` is the only field beyond the ground a caller may name, and it

  is optional. Carrying it is what makes the challenge evidenced, and an

  evidenced challenge is the one that suspends its target — so the shape is

  checked here and again at the table.

  """

  @spec challenge_changeset(t(), map()) :: Ecto.Changeset.t()

  def challenge_changeset(record, attrs) do

    record

    |> cast(attrs, [:ground, :evidence_refs])

    |> put_role("challenge")

    |> put_slug(:memory_id, "chl:")

    |> Evidence.validate(:evidence_refs)

    |> validate_shape()

  end

  @doc """

  Validates one refutation: a steward's resolution of one challenge.

  The challenge and the memory it restores are set on the struct, so a request

  body names neither. The ground is all a caller supplies.

  """

  @spec refutation_changeset(t(), map()) :: Ecto.Changeset.t()

  def refutation_changeset(record, attrs) do

    record

    |> cast(attrs, [:ground])

    |> put_role("refutation")

    |> put_change(:challenge_role, "challenge")

    |> put_slug(:challenge_id, "ref:")

    |> validate_required([:challenge_id])

    |> foreign_key_constraint(:challenge_id,

      name: :memory_admissions_challenge_fkey,

      message: "names no challenge against this memory"

    )

    |> validate_shape()

  end

  # Everything the three roles agree on. `role` is put rather than cast, so no

  # request body can turn a challenge into a refutation and no caller reaches a

  # steward-only role through the path that does not check for one.

  defp put_role(changeset, role) do

    changeset

    |> update_change(:ground, &trim/1)

    |> put_change(:role, "admission")

    |> put_change(:role, role)

    |> put_change(:memory_bucket, "system")

    |> put_slug()

    |> validate_required([:memory_id, :steward_id, :slug, :role, :verdict, :ground])

  end

  defp validate_shape(changeset) do

    changeset

    |> validate_required([:memory_id, :author_id, :slug, :role, :ground])

    |> validate_inclusion(:role, @roles)

    |> validate_inclusion(:verdict, @verdicts)

    |> validate_length(:ground, min: 1, max: @ground_characters, count: :graphemes)

    |> foreign_key_constraint(:steward_id)

    |> foreign_key_constraint(:author_id)

    # The composite key, named as the database names it. A record for a `user`

    # or `learned` row fails here rather than in a read that had to cross an

    # account to check.

      message: "names no system memory"

    )

    |> check_constraint(:verdict, name: :memory_admissions_shape)

    |> check_constraint(:evidence_refs,

      name: :memory_admissions_shape,

      message: "does not satisfy the record shape"

    )

  end

  defp put_slug(changeset) do

    case get_field(changeset, :memory_id) do

      id when is_binary(id) -> put_change(changeset, :slug, "adm:" <> id)

  defp put_slug(changeset, field, prefix) do

    case get_field(changeset, field) do

      id when is_binary(id) -> put_change(changeset, :slug, prefix <> id)

      _absent -> changeset

    end

  end

defmodule OpenAgents.Memories.Admissions do

  @moduledoc """

  The gate in front of the system bucket: anyone can propose, only evidence

  admits, and only a steward writes the receipt.

  The gate in front of the system bucket, and the argument behind it: anyone

  can propose, only evidence admits, anyone may challenge, and only a steward

  resolves.

  ## Why admission is a record rather than a field

  ## Why every state is a record rather than a field

  A wrong `user` memory misleads one session. A wrong `system` memory would

  reach every session on the network, so the store treats a status the way the

  promise registry treats a green promise: it is derived from a receipt

  somebody is answerable for, never read from a flag the claimant set. An

  author who writes `admission: "admitted"` on their own row has claimed

  something, and `status/1` still answers `"candidate"` until a steward records

  a verdict.

  ## Who admits

  A steward, and nobody else. The specification called for a published, signed

  allowlist of pubkeys evaluated as of an event's timestamp; on this substrate

  a single trusted server holds the role and checks it where the row is

  created, so what survives is the rule the machinery existed to enforce.

  promise registry treats a green promise: it is derived from receipts somebody

  is answerable for, never read from a flag the claimant set. An author who

  writes `admission: "admitted"` on their own row has claimed something, and

  `status/1` still answers `"candidate"` until a steward records a verdict.

  The same reasoning carries to disagreement. A reader who finds an admitted

  claim wrong needs a path other than editing somebody else's row, so a

  challenge is a record, a refutation is a record, and a reversal is a further

  record. Nothing here updates anything, and the whole argument stays readable.

  ## The three roles

  * `record/3` writes an **admission**: a steward's verdict on a candidate.

  * `challenge/3` writes a **challenge**: any account's statement that an

    admitted claim is wrong, and the ground for saying so. A challenge that

    carries its own evidence is an *evidenced* challenge.

  * `refute/3` writes a **refutation**: a steward's resolution of one

    challenge, restoring the target.

  `supersede/3` is the other resolution path — a correction or a tombstone on

  the target's slug — and when a steward exercises it, it records a refutation

  of each open challenge on the target in the same transaction. That keeps the

  resolution a receipt rather than something a reader has to infer, and it

  keeps `status/1` a fold over records with no read of `memories` in it.

  ## How a status is derived

  These rules are the whole of it, and they are stated in precedence order.

  Every one of them reads the set of records; none of them reads the order the

  records were inserted in or the order a query happened to return them.

  1. **Admission first.** The effective verdict is the latest `admission`

     record by `{inserted_at, id}`, and a memory with no admission record

     behind it is a `candidate`. The `id` tie-break is what makes two records

     written in the same microsecond derive the same answer every time.

  2. **Only an admitted claim can be suspended.** A challenge against a

     candidate or a rejected memory is recorded and changes nothing: suspension

     means removal from recall, and neither of those is eligible for recall to

     begin with. Such a challenge also consumes none of its author's cap

     (rule 6), because it suspends nothing.

  3. **An open evidenced challenge suspends its target.** The status is

     `suspended`. This is the fail-safe direction: a contested claim silently

     absent is cheaper than a poisoned claim silently present. An *unevidenced*

     challenge is recorded and has no effect at all — that distinction is the

     one thing recall turns on, so an empty evidence list is refused at the

     table rather than read as absence.

  4. **A refutation resolves the challenge it names, and only that one.** A

     challenge is open when no refutation names it. Resolution is set

     membership, not a comparison of dates, which is what makes the derivation

     independent of arrival order: a refutation backfilled with an

     `inserted_at` earlier than its challenge still resolves it, and a second

     refutation of an already-resolved challenge changes nothing. A steward who

     changes their mind writes a **new challenge**; the refuted one stays

     refuted, and both stay readable.

  5. **Nothing else resolves a challenge.** A later admission record does not:

     re-admitting a suspended claim leaves it suspended, because the two

     resolution paths the specification names are a refutation and a

     superseding row, and a steward who means to restore a claim should have to

     say which challenge they are answering.

  6. **A challenge-flood cap bounds one account.** See below.

  Conflicts resolve the same way in every direction. Two verdicts on one

  candidate: the later one wins, ties broken by `id`. Two refutations of one

  challenge: the first closes it and the rest are no-ops. A challenge and a

  refutation written in either order: the same status, because neither rule

  above compares their timestamps.

  A superseded memory keeps whatever admission status its records derive.

  Supersession is not an admission state, it is a pointer at the row that

  replaced this one, and it is read where recall decides what to serve.

  ## What the flood cap actually bounds

  An account's open evidenced challenges suspend at most 25% of the

  admitted system store, rounded up, and beyond that they are recorded and

  queue with no recall effect. The challenges that take effect are the earliest

  by `{inserted_at, id}`, so the outcome is deterministic and equal inputs give

  equal outcomes. Several challenges by one account against the same memory

  count once: the bound is on memories suspended, not on records written.

  Two honest qualifications.

  This is **not** a defence against an attack. There is one server and no

  anonymous publisher, so there is no forged attribution and every challenger

  is an account the operator already accepts claims from. What the cap covers

  is the ordinary case: one prolific, or one systematically wrong, challenger

  should not be able to empty the store while a steward works through the

  queue.

  And it is a bound on the **store**, not on a per-message recall pool.

  Specification section 7.2 states the share against the ranked pool for a

  message, and no such pool exists yet — recall does not read this bucket. A

  share of the store does not imply the same share of every pool drawn from it,

  because an account's challenges can concentrate on one subject. The recall

  issue that builds the pool applies section 7.2's cap at ranking time; this

  one bounds what can be suspended at all.

  ## Who may write each record

  * **Admission** — a steward, and nobody else.

  * **Challenge** — any account, including the claim's own author. Challenging

    is the path for a reader with no standing to correct, so restricting it

    would remove the only reason the record exists.

  * **Refutation** — a steward, and nobody else. On this substrate that is an

    authorization check rather than a signature check: the server rejects the

    write on the role.

  * **Supersession** — the original author or a steward. Anyone else who

    disagrees files a challenge; the store has no path for editing somebody

    else's claim.

  The role is `OpenAgents.Accounts.admin?/1` — the operator allowlist of

  immutable GitHub numeric IDs, bootstrapped to the owner's account. That is

  assignment, not these record shapes. ADMIN-001 enumerates this module as an

  operator gate.

  The check runs before anything is read, so a refusal tells a caller with no

  standing nothing about the row they named. Role is never cast from a request

  body either: each changeset puts its own, so the challenge path cannot be

  talked into writing a refutation.

  ## What this module deliberately does not do

  It does not surface anything. An admitted system memory is stored, derived,

  acting account with no unscoped fallback. Reading an admitted row into every

  account's turn is cross-account recall by construction, so it is a privacy

  decision that belongs to the recall issue rather than a ranking detail this

  one can settle.

  one can settle. A challenged memory nobody can see is still a coherent state:

  the point is that a wrong claim has a path other than editing someone else's

  row, and that a contested claim is marked so the eligibility filter has

  something to read when it arrives.

  It also never reads another account's memory. The composite foreign key

  `(memory_id, memory_bucket)` is what proves a candidate is a `system` row, so

  `record/3` writes without a lookup, and `supersede/3` authorizes inside the

  `UPDATE` predicate and learns nothing from a refusal.

  `(memory_id, memory_bucket)` is what proves a target is a `system` row, so

  `record/3` and `challenge/3` write without a lookup; `refute/3` reads only

  `memory_admissions`, which is network-level rather than account-scoped, and

  the composite foreign key on `(challenge_id, memory_id, challenge_role)` is

  what actually holds a refutation to a challenge against the memory it

  restores. `supersede/3` authorizes inside the `UPDATE` predicate and learns

  nothing from a refusal.

  """

  import Ecto.Query

  alias OpenAgents.Memories.{Admission, Memory}

  alias OpenAgents.Repo

  # The share of the admitted store one account's open evidenced challenges may

  # suspend, as a percentage. Section 7.2's number, applied to the store

  # because there is no recall pool yet. See the module doc.

  @challenge_share 25

  @correction_ground "Resolved by a steward's correction on the target's slug."

  @doc """

  Whether `user` may admit.

  Whether `user` may admit, refute, and correct any system claim.

  A steward is an operator account. `admin?/1` refuses a banned account and

  reads the GitHub numeric ID rather than the login, so a renamed account keeps

  @spec steward?(User.t() | nil) :: boolean()

  def steward?(user), do: Accounts.admin?(user)

  @doc "The percentage of the admitted store one account's challenges may suspend."

  @spec challenge_share() :: pos_integer()

  def challenge_share, do: @challenge_share

  @doc """

  How many admitted memories one account's open evidenced challenges may

  suspend, given `admitted` admitted memories in the store.

  Rounded up, so a store of one admitted claim can still have that claim

  challenged. An empty store has nothing to suspend and a cap of zero.

  """

  @spec challenge_cap(non_neg_integer()) :: non_neg_integer()

  def challenge_cap(admitted) when is_integer(admitted) and admitted >= 0 do

    div(admitted * @challenge_share + 99, 100)

  end

  @doc """

  Writes one admission record against a candidate system memory.

  def record(%User{} = steward, memory_id, attrs) when is_map(attrs) do

    if steward?(steward) do

      with {:ok, id} <- cast_id(memory_id) do

        %Admission{memory_id: id, steward_id: steward.id}

        %Admission{memory_id: id, author_id: steward.id}

        |> Admission.changeset(normalize(attrs))

        |> Repo.insert()

        |> case do

          {:ok, admission} -> {:ok, admission}

          {:error, changeset} -> refusal(changeset)

        end

        |> insert()

      end

    else

      {:error, :steward_required}

  end

  @doc """

  A candidate's effective admission status.

  Writes one challenge against a system memory.

  Attributes: `ground` (why the claim is wrong) and an optional

  `evidence_refs`. Carrying evidence is what makes this an evidenced challenge,

  and an evidenced challenge suspends an admitted target from recall until a

  steward resolves it. Without evidence the challenge is recorded and changes

  nothing — which is still worth writing, because it is on the record and a

  steward can read it.

  Any account may challenge, including the claim's own author. The target and

  the author are set on the struct, so a request body names neither, and

  `:not_found` covers both a target that is not a system memory and one that

  does not exist.

  """

  @spec challenge(User.t(), String.t(), map()) ::

          {:ok, Admission.t()}

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

          | {:error, :not_found}

  def challenge(%User{} = user, memory_id, attrs) when is_map(attrs) do

    with {:ok, id} <- cast_id(memory_id) do

      %Admission{memory_id: id, author_id: user.id}

      |> Admission.challenge_changeset(normalize(attrs))

      |> insert()

    end

  end

  Derived from the admission records that reference it, newest verdict first,

  and never from the candidate's own `admission` field. A memory with no

  admission record behind it is a `candidate`, whatever it says about itself.

  @doc """

  Writes one refutation of a challenge, restoring its target.

  Attributes: `ground` (why the challenge does not stand). Only a steward may

  refute, and the check runs before the challenge is read, so an account

  without the role learns nothing about the challenge it named.

  A refutation resolves the one challenge it names. A target under two open

  challenges needs two refutations, which is the point: each ground was raised

  separately and each is answered separately.

  """

  @spec refute(User.t(), String.t(), map()) ::

          {:ok, Admission.t()}

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

          | {:error, :steward_required}

          | {:error, :not_found}

  def refute(%User{} = steward, challenge_id, attrs) when is_map(attrs) do

    if steward?(steward) do

      with {:ok, id} <- cast_id(challenge_id),

           {:ok, challenged} <- fetch_challenge(id) do

        %Admission{

          memory_id: challenged.memory_id,

          author_id: steward.id,

          challenge_id: challenged.id

        }

        |> Admission.refutation_changeset(normalize(attrs))

        |> insert()

      end

    else

      {:error, :steward_required}

    end

  end

  @doc """

  A system memory's effective status: `candidate`, `admitted`, `rejected`, or

  `suspended`.

  Derived from the records that reference it, never from the candidate's own

  `admission` field. A memory with no record behind it is a `candidate`,

  whatever it says about itself. The precedence rules are in the module doc.

  Answers `nil` for a memory outside the system bucket, which has no admission

  status to have.

  def status(memory_id) when is_binary(memory_id) do

    case cast_id(memory_id) do

      {:ok, id} -> Repo.one(latest(id)) || "candidate"

      {:ok, id} -> Map.get(statuses(), id, "candidate")

      {:error, :not_found} -> nil

    end

  end

  @doc """

  Every admission record against one candidate, oldest first.

  Every system memory some record names, and its derived status.

  The whole store at once, because the challenge cap is a property of the store

  rather than of one memory: how many of an account's challenges take effect

  depends on how many admitted claims there are and on which of that account's

  challenges came first. `status/1` reads one answer out of this.

  Append-only, so this is the whole history rather than the current state, and

  `status/1` is what reads a state out of it.

  The system bucket is small by design — network-level claims, not per-account

  ones — so this reads the records rather than pushing the fold into SQL, where

  the ordering rules would be harder to see and no easier to trust. A memory

  with no record at all is absent here and is a `candidate`.

  """

  @spec statuses() :: %{optional(String.t()) => String.t()}

  def statuses do

    Repo.all(

      from(record in Admission,

        select: %{

          id: record.id,

          memory_id: record.memory_id,

          author_id: record.author_id,

          role: record.role,

          verdict: record.verdict,

          challenge_id: record.challenge_id,

          inserted_at: record.inserted_at,

          evidence: fragment("coalesce(jsonb_array_length(?), 0)", record.evidence_refs)

        }

      )

    )

    |> derive()

  end

  @doc """

  Every record against one system memory, oldest first.

  Append-only, so this is the whole argument rather than the current state:

  verdicts, challenges, and refutations together. `status/1` is what reads a

  state out of it.

  """

  @spec list(Memory.t() | String.t()) :: [Admission.t()]

  def list(%Memory{id: id}), do: list(id)

  ceiling, as `OpenAgents.Memories.create/2` admits one, because it replaces a

  live row with a live row.

  When a **steward** corrects, the same transaction records a refutation of

  every open challenge on the target. That is the specification's second

  resolution path, and writing it down keeps the resolution a receipt rather

  than something a reader has to infer from a pointer. An author correcting

  their own claim resolves nothing: the challenges stand against the row that

  was wrong, and the replacement is a new claim with no challenges on it.

  The authorization is the `UPDATE` predicate rather than a read followed by a

  decision. A caller with no standing gets `:not_supersedable` and learns

  nothing about the row, including whether it exists.

          {0, _rows} -> {:error, :not_supersedable}

        end

      end)

      |> Multi.run(:resolutions, fn repo, _changes -> resolve_by_correction(repo, user, id) end)

      |> Repo.transaction()

      |> case do

        {:ok, %{replacement: written}} -> {:ok, written}

    end

  end

  # ── internal ───────────────────────────────────────────────────────────────

  # ── writing ────────────────────────────────────────────────────────────────

  defp insert(changeset) do

    case Repo.insert(changeset) do

      {:ok, written} -> {:ok, written}

      {:error, refused} -> refusal(refused)

    end

  end

  # The steward's correction is itself the resolution, so it leaves one

  # refutation per open challenge behind it. Unevidenced challenges are

  # resolved too: the correction answers the ground whether or not the ground

  # arrived with evidence, and leaving one open would mean the argument reads

  # as unfinished after it was settled.

  defp resolve_by_correction(repo, %User{} = user, target_id) do

    if steward?(user) do

      target_id

      |> open_challenges()

      |> repo.all()

      |> Enum.reduce_while({:ok, []}, fn challenge, {:ok, written} ->

        %Admission{memory_id: target_id, author_id: user.id, challenge_id: challenge.id}

        |> Admission.refutation_changeset(%{"ground" => @correction_ground})

        |> repo.insert()

        |> case do

          {:ok, refutation} -> {:cont, {:ok, [refutation | written]}}

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

        end

      end)

    else

      {:ok, []}

    end

  end

  # ── reading ────────────────────────────────────────────────────────────────

  # Only `memory_admissions`, and only the id: the record table is

  # network-level rather than account-scoped, and this crosses no account

  # boundary. A refutation still has to survive the composite foreign key,

  # which is what actually binds it to a challenge against this memory.

  defp fetch_challenge(id) do

    query =

      from(record in Admission,

        where: record.id == ^id,

        where: record.role == "challenge",

        select: %{id: record.id, memory_id: record.memory_id}

      )

    case Repo.one(query) do

      nil -> {:error, :not_found}

      challenged -> {:ok, challenged}

    end

  end

  defp open_challenges(target_id) do

    resolved =

      from(record in Admission, where: record.role == "refutation", select: record.challenge_id)

    from(record in Admission,

      where: record.memory_id == ^target_id,

      where: record.role == "challenge",

      where: record.id not in subquery(resolved),

      select: %{id: record.id}

    )

  end

  # MEMORY-010: the account boundary is a predicate in the query. Here it is

  # one half of the authorization — the row is the actor's own — and the other

    )

  end

  defp latest(memory_id) do

    from(record in Admission,

      where: record.memory_id == ^memory_id,

      where: record.role == "admission",

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

      limit: 1,

      select: record.verdict

    )

  # ── derivation ─────────────────────────────────────────────────────────────

  # The rules in the module doc, in precedence order. Every ordering below is

  # over `{inserted_at, id}`, which is data on the records themselves, so the

  # same set of records derives the same statuses whatever order they arrived

  # or were read in.

  defp derive(records) do

    verdicts = verdicts(records)

    admitted = for {id, "admitted"} <- verdicts, into: MapSet.new(), do: id

    suspended = suspensions(records, admitted)

    Map.new(verdicts, fn {memory_id, verdict} ->

      if verdict == "admitted" and MapSet.member?(suspended, memory_id) do

        {memory_id, "suspended"}

      else

        {memory_id, verdict}

      end

    end)

  end

  # Rule 1. The latest verdict per memory. A memory with challenges but no

  # verdict is absent from this map and reads as a candidate.

  defp verdicts(records) do

    records

    |> Enum.filter(&(&1.role == "admission"))

    |> Enum.group_by(& &1.memory_id)

    |> Map.new(fn {memory_id, written} ->

      {memory_id, written |> Enum.max_by(&key/1) |> Map.fetch!(:verdict)}

    end)

  end

  # Rules 2 through 6. An open evidenced challenge against an admitted memory

  # suspends it, up to the cap on its author.

  defp suspensions(records, admitted) do

    resolved =

      for %{role: "refutation", challenge_id: id} <- records,

          is_binary(id),

          into: MapSet.new(),

          do: id

    cap = challenge_cap(MapSet.size(admitted))

    records

    |> Enum.filter(fn record ->

      record.role == "challenge" and record.evidence > 0 and

        not MapSet.member?(resolved, record.id) and

        MapSet.member?(admitted, record.memory_id)

    end)

    |> Enum.group_by(& &1.author_id)

    |> Enum.flat_map(fn {_author, challenges} -> effective(challenges, cap) end)

    |> MapSet.new()

  end

  # The composite foreign key is what refuses a candidate outside the system

  # bucket, so its violation is reported as absence rather than as a changeset

  # error about a column the caller never named.

  # One account's share. Several challenges against the same memory count once,

  # because the bound is on memories suspended rather than on records written,

  # and the earliest of them is the one that dates the suspension.

  defp effective(challenges, cap) do

    challenges

    |> Enum.group_by(& &1.memory_id)

    |> Enum.map(fn {_memory_id, written} -> Enum.min_by(written, &key/1) end)

    |> Enum.sort_by(&key/1)

    |> Enum.take(cap)

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

  end

  # The total order every rule sorts by. `inserted_at` is compared as an

  # integer rather than as a `DateTime` struct, because Erlang term order over

  # a struct compares its keys alphabetically — `day` before `month` before

  # `year` — which is not time. `id` breaks a tie, so two records written in

  # the same microsecond still derive one answer.

  defp key(record), do: {DateTime.to_unix(record.inserted_at, :microsecond), record.id}

  # ── refusals ───────────────────────────────────────────────────────────────

  # The composite foreign keys are what refuse a target outside the system

  # bucket and a refutation naming something that is not a challenge against

  # this memory, so their violations are reported as absence rather than as a

  # changeset error about a column the caller never named.

  defp refusal(changeset) do

    if Enum.any?(changeset.errors, fn {field, _error} -> field == :memory_id end) do

    if Enum.any?(changeset.errors, fn {field, _error} ->

         field in [:memory_id, :challenge_id]

       end) do

      {:error, :not_found}

    else

      {:error, changeset}

defmodule OpenAgents.Memories.Evidence do

  @moduledoc """

  What a piece of evidence looks like, in one place.

  Two records cite evidence: a system memory, where the list is required and a

  claim without one is an assertion rather than a memory

  (`OpenAgents.Memories.Memory`), and a challenge, where the list is optional

  and its presence is exactly what separates a challenge that suspends its

  target from one that is merely recorded

  (`OpenAgents.Memories.Admission`).

  The shape is the same on both, so it is defined once. Each entry names a

  `kind` of `receipt`, `memory`, or `url`, a `ref`, and a `digest` — the digest

  so the evidence behind an admitted claim, or behind a suspension, cannot be

  swapped for something else afterwards.

  This is the half that can explain itself to a caller. The other half is a

  check constraint on each table, because a validation the changeset applies is

  an application filter and a second write path reopens it (MEMORY-004).

  """

  import Ecto.Changeset

  @kinds ~w(receipt memory url)

  @maximum 20

  @doc "The kinds of evidence a record may cite."

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

  def kinds, do: @kinds

  @doc "The most pieces of evidence one record may cite."

  @spec maximum() :: pos_integer()

  def maximum, do: @maximum

  @doc """

  Validates an evidence list, normalising the entries it accepts.

  Absence passes: a caller that requires evidence says so with

  `validate_required/2` first, and the two records differ on that point. An

  empty list never passes, on either record — a list that names nothing is a

  malformed citation rather than an absent one, and reading it as "no evidence"