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

`test/openagents/memories/system_recall_test.exs`.

### MEMORY-012 — A promoted claim has one live home, and the boundary is drawn where it crosses

Status: Current

The knowledge base owns what the project has reviewed and decided; system

memory owns what the network has observed and can evidence. A stance is

editorial and a memory row is evidentiary, and specification section 8 keeps the

two from becoming rival stores of one claim with two rules: promotion drains

memory into the knowledge base, and the knowledge base wins a recall collision.

**Promotion is where the boundary is enforced, and it is the only place it can

be.** The knowledge base is retrieved in the client from a corpus compiled into

a WebAssembly plugin; memory recall runs on this server inside

`POST /api/v1/responses`, and the two notes reach the model through different

fields of the same request. No process holds both. A precedence rule between

them needs a decidable test for "the same claim", and two rails that retrieve by

different methods over different corpora share no identifier unless somebody

records one. **A memory and a stance are the same claim exactly when a promotion

tombstone on that memory names that stance** — a steward's recorded judgment,

never an overlap of prose. Nothing else is a collision here, so a memory that

shares a stance's vocabulary, or quotes its id, is a different claim and keeps

its place in recall.

Given that link, precedence needs no second mechanism. `promote/3` writes a

superseding row on the claim's slug — a **promotion tombstone** — and points the

old row at it, so the claim is no longer live and the chain is kept rather than

deleted. The tombstone carries the stance id, a body this server composes rather

than the caller, and `admission: "candidate"`, which is all it can ever hold: no

admission, challenge, or refutation may name a promotion tombstone, refused by

the composite foreign key `(memory_id, memory_promoted) -> memories (id,

promoted)` with the literal `false` pinned by `memory_admissions_shape`, the

same device `challenge_role` uses. `promoted` is generated from `stance`, so it

cannot disagree with it. Recall surfaces live rows whose derived status is

admitted (specification 7.1), so neither half of a promoted claim can reach a

note by any route, and the reviewed stance is its one live home.

"A tombstone whose body names the stance" is a shape rather than a habit:

`position(stance in body) > 0` is part of `memories_system_shape`, so a

tombstone pointing nowhere is unrepresentable rather than merely unwritten by

the code that exists today. A stance id is lowercase words joined by hyphens, as

the corpus writes them, and a `user` or `learned` row carrying one is refused in

both directions the way the other system columns are.

Only a steward promotes. Promotion records the outcome of a review, and the

review is the knowledge base's authority; an author draining their own claim

into the corpus would assert the review rather than record it. A promotion is a

steward's correction on the target's slug, so it resolves the target's open

challenges in the same transaction, as any steward correction does

(MEMORY-011).

Two things are deliberately not enforced, and calling them enforced would be

worse than leaving them open. **An unlinked coincidence** — a stance and an

admitted memory a reader would call one claim, with no promotion between them —

is not suppressed, because no decidable test separates it from two claims that

merely share words; a similarity threshold shipped as "the knowledge base wins"

would read as a guarantee while dropping true memories on a false positive,

and duplication is the benign failure where suppression is the destructive one.

The honest answer to a real duplicate is to promote it. **A fresh claim written

on a promoted slug** is not refused either: draining by slug would take a read

of `memories` across accounts, which is the predicate MEMORY-010 exists to keep

out of this store.

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

`memories_system_shape` stance clauses, the generated `memories.promoted`

column, the composite foreign key `memory_admissions_promotion_fkey`,

`docs/memory/knowledge-base-boundary.md`, and

`test/openagents/memories/promotion_test.exs`.

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

Status: Current

  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.

- Promoting an admitted system memory to a knowledge-base stance, through

  `OpenAgents.Memories.Promotions` (MEMORY-012). Only a steward promotes,

  because a promotion records the outcome of a review rather than asserts one,

  and the steward set is this same allowlist. The write appends: the promotion

  is a superseding tombstone on the claim's slug, so the claim, its evidence,

  and its admission record all stay readable underneath it. The authority buys

  no read here either — the target is named by id and refused as absent when it

  is not a live system row.

- 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-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`, `test/openagents/memories/challenge_test.exs`, `test/openagents/memories/system_recall_test.exs` |

| MEMORY-012 | `test/openagents/memories/promotion_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` |

# The knowledge-base boundary

The knowledge base and system memory both put network-level knowledge in front

of every session. This page records the line between them, where that line is

enforced, why it is enforced there rather than at recall, and how to run a

promotion.

Contract: `docs/memory/2026-08-25-system-memory-spec.md` section 8 in

`OpenAgentsInc/openagents`. Invariant: `INVARIANTS.md`, MEMORY-012.

## The line

The knowledge base owns what the project has reviewed and decided. Memory owns

what the network has observed and can evidence. A stance is editorial; a memory

row is evidentiary.

| | Knowledge base | System memory |

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

| Unit | Stance or doc summary | Memory row |

| Authority | Human review; content checked into git | Evidence refs; steward admission receipt |

| Change | Regenerated from docs; edited like content | Superseded by later rows; never edited |

| Provenance | Source doc and review date | Writing account, `as_of`, evidence refs |

| Dispute | Documentation change | Challenge and refutation records |

| Note label | `[From the OpenAgents knowledge base — …]` | `[From memory: system, …]` |

The knowledge base lives in `OpenAgentsInc/openagents`: the corpus of stances is

`plugins/knowledge-base/kb/stances.json`, compiled by `build-kb.mjs` into

`kb.json` and embedded in a WebAssembly plugin the CLI loads. System memory

lives here, in the `system` bucket of `OpenAgents.Memories`.

## Where the boundary is enforced

**At promotion, in `OpenAgents.Memories.Promotions`.** Not at recall.

The two rails no longer meet in one process. The client retrieves the knowledge

base and concatenates its note into the outgoing turn text; this server recalls

memory inside `POST /api/v1/responses` and appends its note below the caller's

`instructions`. Both reach the model, neither sees the other.

The specification's second rule — the knowledge base wins a recall collision —

therefore needs an enforcement point chosen deliberately. This is the choice and

the reasoning.

### The collision test

**A memory and a stance are the same claim exactly when a promotion tombstone on

that memory names that stance.** Nothing else is a collision.

That is decidable, it is recorded by a person who checked, and it is the only

identity the two rails can share. The corpus gives each stance a stable

kebab-case `id` (`earning-bitcoin`, `coder-tiers`); a promotion writes that id

into the `stance` column of a tombstone. Two claims that merely share

vocabulary are two claims. A memory that quotes a stance id in its prose — a

claim *about* the corpus, say — is a different claim and keeps its place in

recall.

### Why not enforce at recall

Both recall-time shapes the specification names need the client to say "my

knowledge-base hit covers this memory", and neither can say it.

* **The identifier does not survive.** The corpus has stance ids, but the

  plugin's `Entry::Stance` does not deserialize `id`, so it is absent from the

  hit, from the plugin's declared output schema, from the TypeScript

  `KnowledgeHit`, and from the injected note. A client-side rule would compare a

  stance's prose to a memory's prose, and a server-side rule would compare

  prose the client forwarded. Either is a similarity heuristic.

* **A heuristic shipped as a rule is worse than no rule.** "The knowledge base

  wins collisions" reads as a guarantee. A false positive drops a true memory

  the reader never learns was withheld; a false negative lets the duplicate

  through anyway. Duplication is the benign failure — the two notes are labelled

  differently and a model can weigh them — and suppression is the destructive

  one, so a rule that trades the benign failure for the destructive one is a bad

  trade even when it is usually right.

* **Sending the hit to the server also widens the request.** A client-supplied

  "the knowledge base covers this" field is an untrusted claim that mutes the

  memory rail, and the server would depend on corpus state it cannot check.

* **The rule's purpose is served by draining.** When a stance and a memory

  really do speak to one claim, the correct response is not to silence one every

  turn: it is to promote, so the claim has one home. That is the specification's

  first rule, and making it operable is what this page and

  `Promotions.promote/3` are for.

Given the collision test above, a recall-time rule would also have nothing left

to do. A promoted claim is superseded, so it is not live; its tombstone can never

be admitted, so it is not eligible. Recall surfaces live admitted rows

(specification 7.1), so the promoted claim's one live home is the stance, and

there is no second speaker to silence.

### What is deliberately not enforced

* **An unlinked coincidence.** A stance and an admitted memory that a reader

  would call one claim, with no promotion between them, both attach. Nothing

  decides that today, for the reasons above. If it becomes a real problem, the

  fix is to promote the memory, not to add a threshold.

* **A fresh claim written on a promoted slug.** After a promotion the slug's live

  head is a tombstone; a steward who admits a new row on that slug is re-opening

  a claim the project already drained. Refusing it would take a read of

  `memories` by slug across accounts, which is the predicate MEMORY-010 exists to

  keep out of this store.

Both are named in MEMORY-012 so that nobody reads the invariant as covering

them.

## What a promotion writes

`Promotions.promote/3` is the ordinary correction path with a fixed shape. It

writes a superseding row on the claim's slug — a **promotion tombstone** — and

points the old row at it.

The tombstone carries:

* `stance` — the knowledge-base stance id. Lowercase words joined by hyphens.

* a body this server composes, naming that stance. The table requires the stance

  to appear in the body (`position(stance in body) > 0` in

  `memories_system_shape`), so a tombstone that points nowhere cannot exist.

* `evidence_refs` — where the stance lives and the digest of what was reviewed.

* `admission: "candidate"`, which is all it can ever hold. No admission,

  challenge, or refutation may name a promotion tombstone: the composite foreign

  key `(memory_id, memory_promoted) -> memories (id, promoted)` refuses it, with

  the literal `false` pinned by `memory_admissions_shape`.

Nothing is deleted. The claim, its evidence, and its admission record stay

readable underneath the tombstone, and a promotion by a steward resolves the

claim's open challenges in the same transaction, as any steward correction does.

## Running a promotion

A promotion has two halves, and they land in two repositories. Do the review

half first: until the stance exists, the tombstone would point at nothing.

### 1. Add the stance to the corpus

In `OpenAgentsInc/openagents`:

1. Add a record to `plugins/knowledge-base/kb/stances.json` with an `id`

   (lowercase words joined by hyphens), a `title`, the `questions` a reader

   would ask, a `state`, the `answer`, the `sources` it rests on, and today's

   `date`. Cite the memory you are draining among the sources.

2. Rebuild the corpus and the artifact:

   ```sh

   cd plugins/knowledge-base

   node build-kb.mjs

   cargo build --release --target wasm32-unknown-unknown -p knowledge-base

   ```

3. Re-pin `artifact.digest` in `plugins/knowledge-base/manifest.json` to the

   digest of the rebuilt `knowledge_base.wasm`.

4. Review and land the change the way any documentation change lands. The

   stance is only reviewed once a person has reviewed it.

### 2. Drain the memory

In this repository, as a steward:

```elixir

OpenAgents.Memories.Promotions.promote(steward, memory_id, %{

  "stance" => "gateway-402-retired-model",

  "slug" => "sys:gateway-402-retired-model",

  "evidence_refs" => [

    %{

      "kind" => "url",

      "ref" => "https://openagents.com/OpenAgentsInc/openagents/plugins/knowledge-base/kb/stances.json",

      "digest" => "sha256:…"

    }

  ]

})

```

* `slug` is the target's slug. It binds the tombstone to the claim it drains,

  the same way `Admissions.supersede/3` requires it. Read it off the claim

  before promoting.

* `digest` is the digest of the reviewed stance, so the evidence behind the

  promotion cannot be swapped afterwards.

* `as_of` defaults to today — the date the claim became a reviewed position.

Refusals: `:steward_required` when the account is not an operator,

`:stance_required` when no stance is named, `:not_supersedable` when the target

is not a live system memory, and a changeset for a malformed stance id or

missing evidence.

There is no HTTP route for this, exactly as there is none for admission or

challenge. Promotion is a steward's action on the network's store, taken from a

console with the same authority `OpenAgents.Memories.Admissions` requires.

### 3. Check the drain

The claim should have left recall without leaving the store:

```elixir

claim = OpenAgents.Repo.get!(OpenAgents.Memories.Memory, memory_id)

claim.superseded_by_id                         # the tombstone

OpenAgents.Memories.Admissions.status(claim)   # still "admitted" — nothing was erased

```

## When to promote

A system memory is ready to drain when it has stabilized: admitted, unchallenged

for a sustained period, and repeatedly recalled. Promoting earlier turns an

observation into a reviewed position before the review has anything to review.

Promote sooner than that in one case: when a stance already covers the claim.

That is the duplicate the recall-time rule was written for, and draining it is

how this store answers it.

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

attributed, and it has no effect on any status.

**Stance** — a reviewed editorial position in the knowledge base, which lives in

`OpenAgentsInc/openagents` at `plugins/knowledge-base/kb/stances.json` and is

retrieved in the client. A stance is what the project has reviewed and decided;

a system memory is what the network has observed and can evidence. Say "stance"

only for the knowledge-base record and never for a memory row, and name a stance

by its corpus `id` — lowercase words joined by hyphens.

**Promotion** and **promotion tombstone** — a *promotion* is a steward draining

a stabilized system memory into a stance: the claim becomes a reviewed position

and stops being a live memory. The superseding row it leaves behind is a

*promotion tombstone*, and it names the stance in its body. Say "promotion

tombstone" in full — a bare "tombstone" means the portable-export tombstone in

`OpenAgents.Memory.Portability`, which is a different thing. A promotion is the

one place the knowledge-base boundary is enforced, so do not describe recall as

preferring the knowledge base: it does not compare the two rails

(`docs/memory/knowledge-base-boundary.md`, MEMORY-012).

### Threads

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

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

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

  `memory_promoted` is always the literal `false`, and the composite foreign key

  `(memory_id, memory_promoted) -> memories (id, promoted)` is what refuses a

  record naming a promotion tombstone. A tombstone is a pointer at a reviewed

  knowledge-base stance, not a claim: there is nothing to admit, nothing to

  challenge, and the knowledge base's own dispute path is a documentation

  change. See `OpenAgents.Memories.Promotions`.

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

  elsewhere. It exists so the second composite foreign key,

  elsewhere. It exists so the third 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

  schema "memory_admissions" do

    belongs_to :memory, Memory

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

    field :memory_promoted, :boolean, default: false

    belongs_to :author, User

    belongs_to :challenge, __MODULE__

    field :challenge_role, :string

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

    |> put_change(:role, role)

    |> put_change(:memory_bucket, "system")

    |> put_change(:memory_promoted, false)

  end

  defp validate_shape(changeset) do

      name: :memory_admissions_memory_fkey,

      message: "names no system memory"

    )

    # The second composite key. A promotion tombstone is a pointer at a reviewed

    # stance rather than a claim, so no record may name one, and the refusal is

    # the foreign key rather than a read of the row.

    |> foreign_key_constraint(:memory_id,

      name: :memory_admissions_promotion_fkey,

      message: "names a promoted memory, which is a tombstone rather than a claim"

    )

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

    |> check_constraint(:evidence_refs,

      name: :memory_admissions_shape,

  records, so a row that says `admitted` with no steward record behind it still

  reads as a candidate.

  A system row may also carry a `stance`, and one that does is a **promotion

  tombstone**: the claim was promoted to a reviewed knowledge-base stance, this

  row supersedes the claim, and its body names the stance that replaced it. See

  `OpenAgents.Memories.Promotions`.

  `superseded_by_id` is how a correction lands. The replacement is a new row

  and the old row points at it, so the store keeps the chain rather than

  overwriting the mistake. Nothing here updates `body`: a memory's text is

  @slug_prefix "sys:"

  @tiers ~w(ledger glass)

  @admissions ~w(candidate admitted rejected)

  @stance_characters 200

  # A knowledge-base stance id: lowercase words joined by hyphens, as the

  # corpus writes them (`earning-bitcoin`, `coder-tiers`).

  @stance_format ~r/^[a-z0-9]+(-[a-z0-9]+)*$/

  schema "memories" do

    belongs_to :user, User

    field :as_of, :date

    field :admission, :string

    field :evidence_refs, {:array, :map}

    # The knowledge-base stance this claim was promoted to. A row carrying one

    # is a promotion tombstone: the claim's live home is the reviewed stance,

    # and this row exists to say so. Null on every other row.

    field :stance, :string

    # Whether this row is a promotion tombstone. PostgreSQL generates it from

    # `stance`, so it cannot disagree; it exists as a column because a foreign

    # key can reference one and an expression cannot. Read back after a write,

    # never written.

    field :promoted, :boolean, read_after_writes: true

    # The generated `tsvector` the lexical stand-in ranks over. PostgreSQL

    # writes it; nothing here reads it back, so it never rides a select.

    field :search_vector, :string, load_in_query: false

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

  def evidence_kinds, do: Evidence.kinds()

  @doc """

  Whether this row is a promotion tombstone.

  A tombstone is a pointer at a reviewed stance, not a claim of its own: no

  admission, challenge, or refutation may name one, and nothing can admit it, so

  it reaches no session's recall.

  """

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

  def promoted?(%__MODULE__{stance: stance}), do: is_binary(stance)

  @doc "The longest stance id the store accepts, in characters."

  @spec stance_characters() :: pos_integer()

  def stance_characters, do: @stance_characters

  @doc "The prefix every system slug carries."

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

  def slug_prefix, do: @slug_prefix

      :tier,

      :as_of,

      :admission,

      :evidence_refs

      :evidence_refs,

      :stance

    ])

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

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

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

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

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

    |> validate_required([:bucket, :body])

    |> validate_inclusion(:bucket, @buckets)

    |> validate_length(:body, min: 1, max: @body_characters, count: :graphemes)

    |> validate_inclusion(:tier, @tiers)

    |> validate_inclusion(:admission, @admissions)

    |> Evidence.validate(:evidence_refs)

    |> validate_stance()

  end

  # A stance is optional — most system rows carry none — but a row that names

  # one is a promotion tombstone, and both halves of that shape are checked

  # here and again at the table. `position(stance in body) > 0` is the database

  # half of "a tombstone whose body names the stance"; this is the half that can

  # explain itself to the caller.

  defp validate_stance(changeset) do

    case get_field(changeset, :stance) do

      nil ->

        changeset

      stance ->

        changeset

        |> validate_length(:stance, min: 1, max: @stance_characters, count: :graphemes)

        |> validate_format(:stance, @stance_format,

          message: "must be a knowledge-base stance id, in lowercase words joined by hyphens"

        )

        |> validate_body_names(stance)

    end

  end

  defp validate_body_names(changeset, stance) do

    body = get_field(changeset, :body)

    if is_binary(body) and String.contains?(body, stance) do

      changeset

    else

      add_error(changeset, :body, "must name the stance this claim was promoted to")

    end

  end

  defp refuse_system_fields(changeset) do

    Enum.reduce([:slug, :entity, :tier, :as_of, :admission, :evidence_refs], changeset, fn

      field, acc ->

        if is_nil(get_field(acc, field)) do

          acc

        else

          add_error(acc, field, "belongs only to a system memory")

        end

    end)

    Enum.reduce(

      [:slug, :entity, :tier, :as_of, :admission, :evidence_refs, :stance],

      changeset,

      fn

        field, acc ->

          if is_nil(get_field(acc, field)) do

            acc

          else

            add_error(acc, field, "belongs only to a system memory")

          end

      end

    )

  end

  @doc "Points a memory at the memory that replaced it."

defmodule OpenAgents.Memories.Promotions do

  @moduledoc """

  The drain from the memory store into the knowledge base, and the place the

  boundary between the two is enforced.

  ## The line, and where it is drawn

  Specification section 8 draws the line: the knowledge base owns what the

  project has reviewed and decided, memory owns what the network has observed

  and can evidence. A stance is editorial, a memory row is evidentiary. Two

  rules keep the two from becoming rival stores of one claim — promotion drains

  memory into the knowledge base, and the knowledge base wins a recall

  collision.

  The second rule needs a place to stand, and the cloud re-base took it away.

  The knowledge base is retrieved in the client, from a corpus compiled into a

  WebAssembly plugin; memory recall runs here, inside `POST /api/v1/responses`.

  The two notes are assembled in different processes and arrive in different

  parts of the request, so no process sees both.

  **This module is the enforcement point.** The boundary is drawn where a claim

  crosses it — at promotion — rather than at recall, and the reasoning is in

  `docs/memory/knowledge-base-boundary.md`. The short form:

  * A precedence rule needs a decidable notion of "the same claim". Two rails

    that retrieve by different methods over different corpora share no

    identifier unless somebody records one, and promotion is the only moment

    anybody does: a steward states that this row is now that stance.

  * Given that link, a recall-time rule would have nothing left to do. A

    promoted row is superseded, so it is not live; the tombstone that replaced

    it can never be admitted, so it is not eligible. Recall surfaces live

    admitted rows (specification 7.1), so a promoted claim's one live home is

    the stance, and there is no second speaker for the collision rule to

    silence.

  * For a pair no promotion links, no enforcement point could decide anything

    either. The client would have to judge "covers the same claim" by comparing

    a stance's prose to a memory's, which is a heuristic; shipping one as

    "the knowledge base wins" would read as a guarantee while dropping true

    memories on a false positive. Duplication is the benign failure and

    suppression is the destructive one, so the honest answer to a real duplicate

    is to promote it, which is what this module is for.

  ## What a promotion is

  `promote/3` is the existing correction path with a fixed shape. It writes a

  superseding row on the claim's slug — a **promotion tombstone** — and points

  the old row at it, so the store keeps the chain rather than deleting the

  claim. The tombstone carries:

  * `stance`, the knowledge-base stance id the claim now lives as. It is the

    `id` field of a record in the corpus at

    `plugins/knowledge-base/kb/stances.json` in `OpenAgentsInc/openagents`.

  * a body this module writes rather than the caller, naming that stance. The

    table requires the stance to appear in the body, so "a tombstone whose body

    names the stance" is a shape rather than a habit.

  * `evidence_refs` the steward cites for the promotion — where the stance

    lives and the digest of what was reviewed.

  * `admission: "candidate"`, which is all it can ever be. Nothing can admit a

    tombstone: the composite foreign key

    `(memory_id, memory_promoted) -> memories (id, promoted)` refuses an

    admission, a challenge, and a refutation alike.

  Only a steward promotes. Promotion records the outcome of a review, and the

  review is the knowledge base's authority; an author draining their own claim

  into the corpus would be asserting the review rather than recording it.

  ## What this module does not enforce

  Two things, both named rather than papered over.

  * **An unlinked coincidence.** A stance and an admitted system memory that a

    reader would call the same claim, with no promotion between them, both

    attach. Nothing here decides that, because nothing can decide it: the two

    rails share no identifier for the pair.

  * **A new claim written on a promoted slug.** After a promotion the slug's

    live head is a tombstone, and a steward who admits a fresh row on that slug

    is re-opening a claim the project already drained. Refusing it would take a

    read of `memories` by slug across accounts, which is the predicate

    MEMORY-010 exists to keep out of this store.

  """

  alias OpenAgents.Accounts.User

  alias OpenAgents.Memories.{Admissions, Memory}

  @tier "ledger"

  @doc """

  Promotes one system memory to a knowledge-base stance.

  Attributes: `stance` (required) — the stance id the claim now lives as — and

  `slug` (required) — the target's slug, which is what binds the tombstone to

  the claim it drains, exactly as `OpenAgents.Memories.Admissions.supersede/3`

  requires it. `evidence_refs` (required) cites where the stance lives and the

  digest of what was reviewed. `as_of` defaults to today, the date the claim

  became a reviewed position, and `entity` carries over from the claim when the

  caller names it.

  The body is not a caller's to write: `body/1` composes it so the stance is

  named the same way every time, and the table refuses a tombstone whose body

  does not name its stance.

  When the target is under open challenges, the same transaction records a

  refutation of each — a promotion is a steward's correction, and the

  correction is the resolution.

  Refuses `:steward_required` for an account without the role,

  `:stance_required` when no stance is named or the name is blank — there is

  nowhere for the claim to go, so there is no promotion to write — and

  `:not_supersedable` when the target is not a live system memory. A caller with no standing learns nothing

  about the row from any of them.

  """

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

          {:ok, Memory.t()}

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

          | {:error, :steward_required}

          | {:error, :stance_required}

          | {:error, :not_supersedable}

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

    attrs = normalize(attrs)

    cond do

      not Admissions.steward?(steward) -> {:error, :steward_required}

      not named?(Map.get(attrs, "stance")) -> {:error, :stance_required}

      true -> Admissions.supersede(steward, memory_id, tombstone(attrs))

    end

  end

  # A blank stance is refused here rather than left to the changeset, which

  # casts an empty string to `nil` and would write an ordinary supersession

  # under a body announcing a promotion to nowhere.

  defp named?(stance) when is_binary(stance), do: String.trim(stance) != ""

  defp named?(_absent), do: false

  @doc """

  The body a promotion tombstone carries.

  Fixed rather than free text, so the stance is named identically on every

  tombstone and a reader who meets one knows where the claim went. The table

  requires the stance to appear here.

  """

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

  def body(stance) when is_binary(stance) do

    "Promoted to the OpenAgents knowledge base stance `#{stance}`. " <>

      "The reviewed stance is the live home for this claim; this row is a " <>

      "tombstone and surfaces to nobody."

  end

  @doc "The transparency tier every promotion tombstone carries."

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

  def tier, do: @tier

  # The tombstone's shape. Everything the caller may name is read from `attrs`;

  # everything that makes this a tombstone rather than a claim is put here, so a

  # request body cannot ask for a promotion that admits itself or for a body

  # that points somewhere other than the stance.

  defp tombstone(attrs) do

    stance = attrs |> Map.fetch!("stance") |> String.trim()

    attrs

    |> Map.take(["slug", "entity", "evidence_refs"])

    |> Map.merge(%{

      "stance" => stance,

      "body" => body(stance),

      "tier" => @tier,

      "admission" => "candidate",

      "as_of" => Map.get(attrs, "as_of") || Date.utc_today()

    })

  end

  defp normalize(attrs) do

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

  end

end

    20260825170100,

    20260825195623,

    20260825220000,

    20260825230000

    20260825230000,

    20260826010000

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.PromoteSystemMemories do

  use Ecto.Migration

  # The drain from the memory store into the knowledge base, and the line that

  # keeps the two from becoming rival stores of one claim.

  #

  # Specification section 8 draws the line — the knowledge base owns what the

  # project has reviewed and decided, memory owns what the network has observed

  # and can evidence — and states two rules over it. The first is that promotion

  # drains memory into the knowledge base: a stabilized claim becomes a reviewed

  # stance, and the row it came from is superseded by a **promotion tombstone**

  # whose body names that stance, so the claim has exactly one live home. The

  # second is that the knowledge base wins a recall collision.

  #

  # This migration implements the first rule and makes the second one moot for

  # every claim the first covers. `docs/memory/knowledge-base-boundary.md`

  # carries the reasoning; the short version is that a claim is "the same claim"

  # across the two rails only when a promotion recorded the link, and once a

  # promotion has recorded it the memory half is no longer a live admitted row

  # for recall to collide with.

  #

  # Two decisions are database predicates rather than changeset validations

  # (MEMORY-004):

  #

  #   * **A tombstone names its stance.** `position(stance in body) > 0` is what

  #     makes "whose body names the stance" a shape rather than a convention the

  #     writing code happens to follow today. A tombstone that pointed nowhere

  #     would leave a reader holding a claim with no live home at all.

  #

  #   * **A tombstone is not a claim, so no record may name one.** The composite

  #     foreign key `(memory_id, memory_promoted) -> memories (id, promoted)`,

  #     with `memory_promoted` pinned to `false` by the shape constraint, is

  #     what makes an admission, a challenge, or a refutation against a

  #     tombstone unrepresentable. That is the load-bearing half: recall

  #     surfaces admitted rows only (specification 7.1), so a row that can never

  #     be admitted can never be recalled, and the promoted claim's one live

  #     home is the stance.

  #

  # The pinned literal is the same device `challenge_role` already uses:

  # PostgreSQL will not put a literal in a foreign key, so the literal is a

  # column the check constraint holds down.

  def up do

    alter table(:memories) do

      # The knowledge-base stance this claim was promoted to, and the only

      # cross-rail identifier either rail has. It is the `id` field of a record

      # in the knowledge-base corpus (`plugins/knowledge-base/kb/stances.json`

      # in `OpenAgentsInc/openagents`), which is kebab-case and stable across

      # regenerations of the compiled plugin.

      #

      # A row carrying one is a promotion tombstone. Null on every other row,

      # system or otherwise.

      add :stance, :string

    end

    # Whether this row is a promotion tombstone, as a column a foreign key can

    # reference. Generated rather than written, so it cannot disagree with

    # `stance`, and stored rather than virtual, so it can be indexed.

    execute(

      """

      ALTER TABLE memories

      ADD COLUMN promoted boolean

      GENERATED ALWAYS AS (stance IS NOT NULL) STORED

      """,

      "ALTER TABLE memories DROP COLUMN promoted"

    )

    drop constraint(:memories, :memories_system_shape)

    # The system shape, extended in both directions: `stance` is refused

    # outright on a `user` or `learned` row, and on a system row it is either

    # absent or a well-formed stance id that the body names.

    #

    # Every column is asserted `IS NOT NULL` before it is compared, for the

    # reason the constraint this replaces gives: a check constraint passes when

    # it evaluates to NULL, so a format test alone would admit a tombstone whose

    # stance is absent rather than malformed.

    create constraint(:memories, :memories_system_shape,

             check: """

             (

               bucket <> 'system'

               AND slug IS NULL

               AND entity IS NULL

               AND tier IS NULL

               AND as_of IS NULL

               AND admission IS NULL

               AND evidence_refs IS NULL

               AND stance IS NULL

             ) OR (

               bucket = 'system'

               AND slug IS NOT NULL

               AND slug LIKE 'sys:%'

               AND char_length(slug) BETWEEN 5 AND 200

               AND (entity IS NULL OR char_length(entity) BETWEEN 1 AND 200)

               AND tier IS NOT NULL

               AND tier IN ('ledger','glass')

               AND as_of IS NOT NULL

               AND admission IS NOT NULL

               AND admission IN ('candidate','admitted','rejected')

               AND evidence_refs IS NOT NULL

               AND jsonb_typeof(evidence_refs) = 'array'

               AND jsonb_array_length(evidence_refs) BETWEEN 1 AND 20

               AND NOT jsonb_path_exists(evidence_refs, '$[*] ? (!(@.type() == "object"

                     && exists(@.kind ? (@ == "receipt" || @ == "memory" || @ == "url"))

                     && exists(@.ref ? (@.type() == "string" && @ != ""))

                     && exists(@.digest ? (@.type() == "string" && @ != ""))))')

               AND (

                 stance IS NULL

                 OR (

                   char_length(stance) BETWEEN 1 AND 200

                   AND stance ~ '^[a-z0-9]+(-[a-z0-9]+)*$'

                   AND position(stance in body) > 0

                 )

               )

             )

             """

           )

    # What the composite foreign key below points at.

    create unique_index(:memories, [:id, :promoted], name: :memories_id_promoted_index)

    # Reading the store's promotion tombstones without scanning it.

    create index(:memories, [:stance], where: "stance IS NOT NULL")

    alter table(:memory_admissions) do

      # Always `false`. It exists so the foreign key below can insist that

      # `memory_id` names a memory that is not a promotion tombstone; the shape

      # constraint pins the literal.

      add :memory_promoted, :boolean, null: false, default: false

    end

    execute(

      """

      ALTER TABLE memory_admissions

      ADD CONSTRAINT memory_admissions_promotion_fkey

      FOREIGN KEY (memory_id, memory_promoted)

      REFERENCES memories (id, promoted) ON DELETE CASCADE

      """,

      "ALTER TABLE memory_admissions DROP CONSTRAINT memory_admissions_promotion_fkey"

    )

    drop constraint(:memory_admissions, :memory_admissions_shape)

    create constraint(:memory_admissions, :memory_admissions_shape,

             check: """

             memory_bucket = 'system'

             AND memory_promoted = false

             AND role IN ('admission','challenge','refutation')

             AND char_length(slug) BETWEEN 1 AND 200

             AND char_length(ground) BETWEEN 1 AND 2000

             AND (

               (role = 'admission'

                AND verdict IS NOT NULL

                AND verdict IN ('admitted','rejected')

                AND slug = 'adm:' || memory_id::text

                AND challenge_id IS NULL

                AND challenge_role IS NULL

                AND evidence_refs IS NULL)

               OR (role = 'challenge'

                AND verdict IS NULL

                AND slug = 'chl:' || memory_id::text

                AND challenge_id IS NULL

                AND challenge_role IS NULL

                AND (

                  evidence_refs IS NULL

                  OR (

                    jsonb_typeof(evidence_refs) = 'array'

                    AND jsonb_array_length(evidence_refs) BETWEEN 1 AND 20

                    AND NOT jsonb_path_exists(evidence_refs, '$[*] ? (!(@.type() == "object"

                          && exists(@.kind ? (@ == "receipt" || @ == "memory" || @ == "url"))

                          && exists(@.ref ? (@.type() == "string" && @ != ""))

                          && exists(@.digest ? (@.type() == "string" && @ != ""))))')

                  )

                ))

               OR (role = 'refutation'

                AND verdict IS NULL

                AND challenge_id IS NOT NULL

                AND challenge_role IS NOT NULL

                AND challenge_role = 'challenge'

                AND slug = 'ref:' || challenge_id::text

                AND evidence_refs IS NULL)

             )

             """

           )

  end

  def down do

    drop constraint(:memory_admissions, :memory_admissions_shape)

    create constraint(:memory_admissions, :memory_admissions_shape,

             check: """

             memory_bucket = 'system'

             AND role IN ('admission','challenge','refutation')

             AND char_length(slug) BETWEEN 1 AND 200

             AND char_length(ground) BETWEEN 1 AND 2000

             AND (

               (role = 'admission'

                AND verdict IS NOT NULL

                AND verdict IN ('admitted','rejected')

                AND slug = 'adm:' || memory_id::text

                AND challenge_id IS NULL

                AND challenge_role IS NULL

                AND evidence_refs IS NULL)

               OR (role = 'challenge'

                AND verdict IS NULL

                AND slug = 'chl:' || memory_id::text

                AND challenge_id IS NULL

                AND challenge_role IS NULL

                AND (

                  evidence_refs IS NULL

                  OR (

                    jsonb_typeof(evidence_refs) = 'array'

                    AND jsonb_array_length(evidence_refs) BETWEEN 1 AND 20

                    AND NOT jsonb_path_exists(evidence_refs, '$[*] ? (!(@.type() == "object"

                          && exists(@.kind ? (@ == "receipt" || @ == "memory" || @ == "url"))

                          && exists(@.ref ? (@.type() == "string" && @ != ""))

                          && exists(@.digest ? (@.type() == "string" && @ != ""))))')

                  )

                ))

               OR (role = 'refutation'

                AND verdict IS NULL

                AND challenge_id IS NOT NULL

                AND challenge_role IS NOT NULL

                AND challenge_role = 'challenge'

                AND slug = 'ref:' || challenge_id::text

                AND evidence_refs IS NULL)

             )

             """

           )

    execute("ALTER TABLE memory_admissions DROP CONSTRAINT memory_admissions_promotion_fkey")

    alter table(:memory_admissions) do

      remove :memory_promoted

    end

    drop index(:memories, [:stance], where: "stance IS NOT NULL")

    drop index(:memories, [:id, :promoted], name: :memories_id_promoted_index)

    drop constraint(:memories, :memories_system_shape)

    create constraint(:memories, :memories_system_shape,

             check: """

             (

               bucket <> 'system'

               AND slug IS NULL

               AND entity IS NULL

               AND tier IS NULL

               AND as_of IS NULL

               AND admission IS NULL

               AND evidence_refs IS NULL

             ) OR (

               bucket = 'system'

               AND slug IS NOT NULL

               AND slug LIKE 'sys:%'

               AND char_length(slug) BETWEEN 5 AND 200

               AND (entity IS NULL OR char_length(entity) BETWEEN 1 AND 200)

               AND tier IS NOT NULL

               AND tier IN ('ledger','glass')

               AND as_of IS NOT NULL

               AND admission IS NOT NULL

               AND admission IN ('candidate','admitted','rejected')

               AND evidence_refs IS NOT NULL

               AND jsonb_typeof(evidence_refs) = 'array'

               AND jsonb_array_length(evidence_refs) BETWEEN 1 AND 20

               AND NOT jsonb_path_exists(evidence_refs, '$[*] ? (!(@.type() == "object"

                     && exists(@.kind ? (@ == "receipt" || @ == "memory" || @ == "url"))

                     && exists(@.ref ? (@.type() == "string" && @ != ""))

                     && exists(@.digest ? (@.type() == "string" && @ != ""))))')

             )

             """

           )

    execute("ALTER TABLE memories DROP COLUMN promoted")

    alter table(:memories) do

      remove :stance

    end

  end

end

defmodule OpenAgents.Memories.PromotionTest do

  @moduledoc """