`priv/sarah/persona/sarah.v1.sources.json`, and

`OpenAgents.Persona.SourceManifestTest`.

### CANON-002 — Retained `machine` names are enumerated, not assumed

Status: Current

The product says computer. A `machine` name is retained only where something

outside this release can observe or replay it: a row an earlier release wrote,

a client this repository does not ship, another node during a hot upgrade, or a

sealed ciphertext. Everywhere else the name is `computer`.

The durable half of that exemption is enumerated, not described.

`OpenAgents.Vocabulary` lists every `machine`-named table, column, constraint,

and index, and the proof derives the live population from `information_schema`

and `pg_catalog` rather than from a list maintained beside it, so a migration

that adds a `machine`-named durable surface fails until someone records it and

says why, and a ledger entry the database does not have fails as well. The wire

half has no query that enumerates it and is listed in `docs/taxonomy.md`

instead, held by the contracts that own each surface.

A retained name owes a population, and the population must be established from

something that cannot lie rather than from a reading of the call sites. The

retired AAD `sarah.machine_token.v1` had none — nothing seals a version-1 blob

and a sealed pairing token cannot outlive its bounded window — so the token

vault carries one version and one AAD. The audit actor kind `machine` looked

the same and is not: a paired computer authenticating to the Git plane pushes

under `{:machine, id}`, from a variable that no source scan for a literal

finds. It stays, and the proof asserts that every principal kind

`OpenAgents.Forge.GitHTTP.audit_actor_kinds/0` admits is an actor kind

`OpenAgents.Audit` accepts, so narrowing one without the other fails here

instead of raising after a pack is already written.

Evidence: `OpenAgents.Vocabulary`, `OpenAgents.Audit`,

`OpenAgents.Forge.GitHTTP`, `OpenAgents.Machines.TokenVault`,

`test/openagents/vocabulary_test.exs`, `test/openagents/audit_test.exs`,

`test/openagents/machines/token_vault_test.exs`, and

`test/openagents/machines_test.exs`.

### PERSONA-001 — Each inference uses one immutable persona artifact

Status: Current

| Invariant | Executable proof |

| --- | --- |

| CANON-001 | `test/openagents/persona/source_manifest_test.exs` |

| CANON-002 | `test/openagents/vocabulary_test.exs`, `test/openagents/audit_test.exs`, `test/openagents/machines/token_vault_test.exs` |

| PERSONA-001 | `test/openagents/persona_test.exs`, `test/openagents/providers/persona_boundary_test.exs` |

| PERSONA-002 | `test/openagents/context/composer_test.exs`, `test/openagents/roles_test.exs` |

| PERSONA-003 | `test/openagents/persona/evaluation_test.exs` |

- The stored `staging_disposable_resources.kind` value `machine`, and the

  audit action `repository.machine_grant.updated` with subject

  `machine_grant`.

- The module residency `operator_machine`, the consent `machine_pairing`, and

  the routing-policy id `sarah.routing.policy.paired-machine.v1`. All three sit

  inside the digest that `module_route_receipts` stores, so renaming one makes

  historical receipts fail to reproduce.

- The `audit_events.actor_type` value `machine`. A paired computer that

  authenticates to the Git plane with its `smct_` token pushes and fetches

  under `{:machine, id}`, so the value is written, not vestigial.

  `OpenAgents.Forge.GitHTTP.audit_actor_kinds/0` names the principal kinds that

  can reach it, and `OpenAgents.AuditTest` asserts every one of them is an

  actor kind `OpenAgents.Audit` accepts — a containment a reading of the call

  sites cannot establish, because the actor there is a variable.

- The module residency `operator_machine` and the routing-policy id

  `sarah.routing.policy.paired-machine.v1`. The residency reaches

  `artifact.facets` and so the `artifact_digest` and `registry_digest` a route

  receipt stores; the policy id and the `allowed_residencies` that admit it are

  both inside `policy_digest`. Renaming either makes a stored

  `module_route_receipts` row fail to reproduce. The neighbouring

  `policy_facets` consent, by contrast, is shape-checked and never digested,

  which is why it is now `computer_pairing`.

- The `Machines.TokenVault` AAD `openagents.machine_token.v2`, bound into

  ciphertext at rest.

- `OPENAGENTS_MACHINE_TOKEN_TTL_SECONDS` and the setting key

  `:machine_token_ttl_seconds`, which live in staging and production secrets.

`audit_events.actor_type` used to permit `machine` and nothing ever wrote one.

The application no longer accepts it; the database constraint still does,

because narrowing a constraint over rows this release did not write is a

migration, not an edit.

**`machine` also means machine-readable** — and that sense is correct, not

residue. `GET /api/v3` publishes `contribution.machine`, and `/agents.json`

publishes `representations.machine`, each paired with `human` and each naming a

defmodule OpenAgents.Vocabulary do

  @moduledoc """

  The ledger of durable names that keep the word `machine`.

  The product says computer. `docs/taxonomy.md` settled that, and issue #134

  settled what happens to the names underneath it: a `machine` name stays where

  something outside this release can observe or replay it, and moves to

  `computer` where it cannot. PostgreSQL is the clearest case of the first —

  a table, column, constraint, or index name is read by rows an earlier release

  wrote — so this module enumerates every durable name that is exempt, and

  `OpenAgents.VocabularyTest` derives the live population from

  `information_schema` and `pg_catalog` and fails when the two disagree.

  The point is not the list. The point is that a new `machine`-named durable

  surface cannot appear without someone adding it here and saying why, and a

  removed one cannot linger here pretending to exist. See `INVARIANTS.md`,

  CANON-002.

  This ledger covers PostgreSQL only. The wire half of the same decision — the

  controller protocol `openagents.computer.v1`, the `.v1` tool schemas, the

  published response keys, the PubSub topics and Horde registry keys — is held

  by its own contracts, because no query enumerates it.

  """

  @tables ~w(machine_pairings machines repository_machine_grants)

  @columns [

    {"forge_assignments", "machine_id"},

    {"inference_grants", "machine_id"},

    {"machine_pairings", "machine_id"},

    {"repository_machine_grants", "machine_id"},

    {"work_jobs", "machine_id"}

  ]

  @constraints [

    {"forge_assignments", "forge_assignments_machine_id_fkey"},

    {"inference_grants", "inference_grants_machine_id_fkey"},

    {"machine_pairings", "machine_pairings_machine_id_fkey"},

    {"machine_pairings", "machine_pairings_pkey"},

    {"machine_pairings", "machine_pairings_status_check"},

    {"machine_pairings", "machine_pairings_tier_check"},

    {"machine_pairings", "machine_pairings_user_id_fkey"},

    {"machines", "machines_pkey"},

    {"machines", "machines_status_check"},

    {"machines", "machines_tier_check"},

    {"machines", "machines_token_expiry_after_creation"},

    {"machines", "machines_user_id_fkey"},

    {"repository_machine_grants", "repository_machine_grants_created_by_user_id_fkey"},

    {"repository_machine_grants", "repository_machine_grants_machine_id_fkey"},

    {"repository_machine_grants", "repository_machine_grants_operations_allowed"},

    {"repository_machine_grants", "repository_machine_grants_operations_present"},

    {"repository_machine_grants", "repository_machine_grants_pkey"},

    {"repository_machine_grants", "repository_machine_grants_repository_id_fkey"},

    {"work_jobs", "work_jobs_machine_id_fkey"}

  ]

  @indexes [

    {"forge_assignments", "forge_assignments_machine_id_index"},

    {"forge_assignments", "forge_assignments_one_active_machine_index"},

    {"inference_grants", "inference_grants_machine_id_index"},

    {"machine_pairings", "machine_pairings_code_digest_index"},

    {"machine_pairings", "machine_pairings_expires_at_index"},

    {"machine_pairings", "machine_pairings_pkey"},

    {"machines", "machines_pkey"},

    {"machines", "machines_token_digest_index"},

    {"machines", "machines_user_id_index"},

    {"repository_machine_grants", "repository_machine_grants_machine_id_index"},

    {"repository_machine_grants", "repository_machine_grants_pkey"},

    {"repository_machine_grants", "repository_machine_grants_repository_id_machine_id_index"},

    {"work_jobs", "work_jobs_machine_id_inserted_at_index"}

  ]

  @doc "Tables whose name keeps `machine`."

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

  def tables, do: @tables

  @doc "`{table, column}` pairs whose column name keeps `machine`."

  @spec columns() :: [{String.t(), String.t()}]

  def columns, do: @columns

  @doc "`{table, constraint}` pairs whose constraint name keeps `machine`."

  @spec constraints() :: [{String.t(), String.t()}]

  def constraints, do: @constraints

  @doc "`{table, index}` pairs whose index name keeps `machine`."

  @spec indexes() :: [{String.t(), String.t()}]

  def indexes, do: @indexes

end

defmodule OpenAgents.VocabularyTest do

  @moduledoc """

  CANON-002. Proves the `machine` exemption ledger against the live database.

  The population comes from `information_schema` and `pg_catalog`, not from a

  list someone maintained beside the ledger, so a `machine`-named table,

  column, constraint, or index added by any migration fails here until it is

  recorded in `OpenAgents.Vocabulary` with a reason.

  """

  use OpenAgents.DataCase, async: true

  alias OpenAgents.Vocabulary

  @pattern "%machine%"

  test "every machine-named table in the database is on the ledger" do

    assert live_tables() == Enum.sort(Vocabulary.tables())

  end

  test "every machine-named column in the database is on the ledger" do

    assert live_columns() == Enum.sort(Vocabulary.columns())

  end

  test "every machine-named constraint in the database is on the ledger" do

    assert live_constraints() == Enum.sort(Vocabulary.constraints())

  end

  test "every machine-named index in the database is on the ledger" do

    assert live_indexes() == Enum.sort(Vocabulary.indexes())

  end

  test "the ledger claims nothing the database does not have" do

    live = MapSet.new(live_tables())

    for table <- Vocabulary.tables() do

      assert MapSet.member?(live, table), "ledger names a table that does not exist: #{table}"

    end

    tables = MapSet.new(live_tables() ++ table_names())

    for {table, name} <- Vocabulary.columns() ++ Vocabulary.constraints() ++ Vocabulary.indexes() do

      assert MapSet.member?(tables, table),

             "ledger entry #{name} names a table that does not exist: #{table}"

    end

  end

  defp live_tables do

    """

    SELECT table_name FROM information_schema.tables

    WHERE table_schema = 'public' AND table_name LIKE $1

    """

    |> rows([@pattern])

    |> Enum.map(&hd/1)

    |> Enum.sort()

  end

  defp live_columns do

    """

    SELECT table_name, column_name FROM information_schema.columns

    WHERE table_schema = 'public' AND column_name LIKE $1

    """

    |> rows([@pattern])

    |> pairs()

  end

  defp live_constraints do

    """

    SELECT c.conrelid::regclass::text, c.conname

    FROM pg_constraint c

    JOIN pg_namespace n ON n.oid = c.connamespace

    WHERE n.nspname = 'public' AND c.conname LIKE $1

    """

    |> rows([@pattern])

    |> pairs()

  end

  defp live_indexes do

    """

    SELECT tablename, indexname FROM pg_indexes

    WHERE schemaname = 'public' AND indexname LIKE $1

    """

    |> rows([@pattern])

    |> pairs()

  end

  defp table_names do

    """

    SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'

    """

    |> rows([])

    |> Enum.map(&hd/1)

  end

  defp rows(sql, params) do

    %Postgrex.Result{rows: rows} = Ecto.Adapters.SQL.query!(OpenAgents.Repo, sql, params)

    rows

  end

  defp pairs(rows), do: rows |> Enum.map(fn [a, b] -> {a, b} end) |> Enum.sort()

end