**Exit criteria:** Another operator can repeat the deploy from the recorded SHA

and obtain the same revision, schema, configuration posture, and checks.

### Gate 13 implementation status

Implemented locally on 2026-08-20:

- Added a reviewed, machine-readable map for the known nonempty prior database

  lineage. It partitions every current migration into shared, baselined,

  reconciling, or genuinely new groups and explains every baselined version.

- Added a release command that classifies empty, current, known prior, already

  baselined, partial, and unknown databases without returning content. It

  validates the known prior migration signature and the required tables,

  columns, key types, constraints, indexes, and forbidden transitional forge

  structures.

- Added a snapshot-gated compatibility bridge. It adds one nullable account

  column and partial index, records only the 14 reviewed migration versions,

  uses the release migration advisory lock, and refuses unknown or partial

  lineages. The current migration inventory test fails if any version is

  omitted or classified twice.

- Added a guarded reconciliation migration for the visitor identity constraint.

  Fresh current-lineage databases were missing the constraint even though the

  changeset named it; prior-lineage databases already have it and remain

  unchanged.

- Rehearsed the bridge and all 20 remaining current migrations on a disposable

  copy of the complete 57-version prior schema. Account, message, forge target,

  build receipt, and deploy receipt probes remained present. Both the candidate

  application and the last-known-good application started against the migrated

  copy.

The [staging migration-lineage runbook](operations/staging-migration-lineage.md)

defines classification, copy rehearsal, snapshot, single-job migration,

rollback compatibility, and evidence collection. Gate 13 remains open until

the exact candidate image and release artifacts are retained and the selected

path runs against the isolated staging target.

## Gate 14: Run the staging regression matrix

Record every case as passed, failed, blocked, or not applicable. A retry does not

| --- | --- |

| A1, missing browser tests and incomplete baseline | Resolved by Gate 0. The owned baseline now runs the Node suites, merged Elixir coverage, and release smoke against an exact SHA. |

| A2, staging shares a production database failure domain | Open and blocking Gates 12 and 15. Provision a separate staging database instance before any failure injection or soak. |

| A3, incompatible migration lineage on a nonempty prior database | Open and blocking Gate 13 for every prior-lineage target. Map and rehearse that lineage before deployment. |

| A3, incompatible migration lineage on a nonempty prior database | Mapped and rehearsed locally with a fail-closed release command. Each actual prior-lineage target still requires its own snapshot-copy rehearsal before Gate 13 deployment. |

| A4, component, icon, and palette conflicts | Resolved by Gate 4 and its compiled CSS contract tests. |

| A5, silent runtime configuration failures | Resolved by Gate 5 and its fail-closed runtime readiness checks. |

| A6, repository authorization violations | Resolved by Gate 7 in code, PostgreSQL constraints, and the populated migration rehearsal. |

# Classify and migrate a staging database

Classify the database before you start a staging candidate. The release

supports three safe paths:

- `empty` identifies a database without application tables. Run all current

  migrations.

- `current` identifies a database that already uses this repository's

  migration lineage. Run the remaining current migrations.

- `prior` identifies the one reviewed nonempty lineage from 2026-08-19. Create

  a snapshot, apply the reviewed baseline bridge, and then run the remaining

  current migrations.

The command refuses `unknown` and `prior_partial` databases. Do not insert

`schema_migrations` rows manually or edit the baseline map during a deployment.

## Understand the reviewed map

The [prior-lineage baseline map](../../priv/migration_lineages/prior-2026-08-19.json)

partitions every current migration into four disjoint groups:

- 38 versions are shared by both lineages and already appear in

  `schema_migrations`.

- 14 current versions have effects that the prior lineage already satisfies.

  These include consolidated create migrations and temporary forge repair

  migrations that would duplicate tables, convert UUIDs, truncate receipts, or

  drop build history if replayed.

- Four reconciliation migrations run normally because they are guarded or

  idempotent.

- 16 versions are genuinely new and run normally after the baseline.

The bridge adds only the nullable `users.browser_key_hash` column and its

partial unique index. It then records the 14 reviewed versions. It preserves

all prior migration rows and all application data.

Classification checks the required prior migration signature, tables,

columns, key column types, constraints, indexes, and absence of temporary forge

foreign keys and legacy tables. The map test fails if a current migration is

unclassified or appears in more than one group.

## Classify the target

Run the command from the exact candidate release with the same staging-only

database configuration that the migration job will use:

```sh

bin/migration-lineage check

```

The command prints one content-free JSON object. Save it with the candidate

evidence. Confirm its `classification`, `map_digest`, fact counts, and baseline

counts. It never returns database names, row contents, credentials, or schema

definitions.

For `empty` or `current`, do not apply a baseline. Run:

```sh

bin/migrate

bin/migration-lineage check

```

An empty database becomes `current` after migration.

## Rehearse a prior-lineage target

Never baseline the live target first. Restore its latest snapshot into the

isolated staging database instance and rehearse on that disposable copy:

1. Stop all writers to the copy.

2. Run `bin/migration-lineage check` and require `prior`.

3. Record content-free row counts and integrity queries for accounts,

   conversations, messages, forge targets, build receipts, and deploy receipts.

4. Create or confirm a snapshot of the copy and record its bounded reference.

5. Apply the baseline bridge:

   ```sh

   OPENAGENTS_STAGING_SNAPSHOT_ID=staging-copy-20260820-0001 \

     bin/migration-lineage --apply

   ```

6. Require `prior_baselined`, `changed: true`, 14 baseline entries, and zero

   missing facts in the JSON result.

7. Run `bin/migrate`. Exactly the reconciliation and genuinely new versions

   that are absent from the copy should run.

8. Run `bin/migration-lineage check` again and require `prior_baselined` with

   zero missing facts.

9. Start the candidate release with high-risk features disabled. Require

   configuration readiness, database connectivity, `/healthz`, and `/status`.

10. Start the last-known-good release against the migrated copy with traffic and

    workers disabled. This verifies that the additive schema remains rollback

    compatible.

11. Repeat the content-free counts and integrity queries from step 3. Investigate

    any difference before you continue.

12. Delete the disposable copy after you retain the sanitized receipt.

The apply command is idempotent only after the complete bridge succeeds. It

refuses a partial baseline so an operator cannot guess how to repair an

interrupted or manually modified lineage.

## Migrate the actual staging target

After the copy rehearsal passes:

1. Stop staging writers and verify that no old application instance can restart.

2. Create an on-demand Cloud SQL backup or snapshot of the actual staging-only

   instance. Record its identifier and completion state.

3. Repeat `bin/migration-lineage check` against the actual target. Its result

   must match the rehearsed classification and map digest.

4. Apply the baseline only if the classification is `prior`, using the actual

   snapshot identifier.

5. Run `bin/migrate` as a single bounded job. Do not let every application node

   race migration during this deployment.

6. Recheck the lineage, migration versions, integrity counts, and candidate

   startup before you admit traffic.

If any check fails, keep traffic fenced, preserve the database and logs, and

restore the reviewed snapshot into a new isolated target. Do not edit migration

history in place and do not point the candidate at a production database.

## Record evidence

Retain these content-free fields in the Gate 13 report:

- Exact Git SHA, image manifest digest, and release version.

- Baseline map digest and classification before and after migration.

- Snapshot identifier and completion receipt.

- Baseline versions recorded and current versions applied.

- Before-and-after row counts and integrity-check statuses.

- Candidate and last-known-good startup results.

- Migration duration, first failure if any, and rollback disposition.

Do not retain database URLs, passwords, account identifiers, prompts, messages,

transcripts, OAuth material, or query results containing user content.

defmodule OpenAgents.MigrationLineage do

  @moduledoc """

  Classifies and safely baselines the known nonempty database lineage.

  The baseline is an explicit compatibility bridge, not a general migration

  repair tool. It refuses unknown and partially modified lineages. Applying it

  requires a bounded snapshot reference and is admitted only in tests or in

  staging at Gate 13 or later.

  """

  alias Ecto.Adapters.SQL

  @lock_id 42_424_242

  @map_file "migration_lineages/prior-2026-08-19.json"

  @snapshot_pattern ~r/\A[a-z0-9][a-z0-9-]{7,127}\z/

  @type classification ::

          :empty | :current | :prior | :prior_baselined | :prior_partial | :unknown

  @doc "Returns a bounded classification without changing the database."

  @spec classify(module()) :: {:ok, map()} | {:error, atom()}

  def classify(repo) when is_atom(repo) do

    with :ok <- ensure_admitted() do

      {:ok, classify_repo(repo, load_map!())}

    end

  end

  @doc "Applies the known baseline bridge after a staging snapshot exists."

  @spec baseline(module(), String.t()) :: {:ok, map()} | {:error, atom()}

  def baseline(repo, snapshot_ref) when is_atom(repo) and is_binary(snapshot_ref) do

    with :ok <- ensure_admitted(),

         :ok <- validate_snapshot_ref(snapshot_ref) do

      map = load_map!()

      repo.transaction(fn ->

        _lock = SQL.query!(repo, "SELECT pg_advisory_xact_lock($1)", [@lock_id])

        before = classify_repo(repo, map)

        case before.classification do

          "prior" ->

            apply_bridge!(repo)

            insert_baseline_versions!(repo, baseline_versions(map))

            after_baseline = classify_repo(repo, map)

            if after_baseline.classification != "prior_baselined" do

              repo.rollback(:baseline_postcondition_failed)

            end

            result(after_baseline, snapshot_ref, true)

          "prior_baselined" ->

            result(before, snapshot_ref, false)

          "prior_partial" ->

            repo.rollback(:partial_lineage_forbidden)

          _other ->

            repo.rollback(:lineage_not_baselineable)

        end

      end)

      |> normalize_transaction()

    end

  end

  def baseline(_repo, _snapshot_ref), do: {:error, :invalid_baseline_request}

  @doc "Returns one bounded JSON result for the release operator command."

  @spec command!(module(), String.t(), String.t() | nil) :: String.t()

  def command!(repo, "check", _snapshot_ref) do

    case classify(repo) do

      {:ok, result} -> encode_result("checked", result)

      {:error, reason} -> raise "migration lineage check refused: #{bounded_reason(reason)}"

    end

  end

  def command!(repo, "apply", snapshot_ref) do

    case baseline(repo, snapshot_ref) do

      {:ok, result} -> encode_result("baselined", result)

      {:error, reason} -> raise "migration lineage baseline refused: #{bounded_reason(reason)}"

    end

  end

  def command!(_repo, _mode, _snapshot_ref),

    do: raise("migration lineage command mode is invalid")

  @doc "Loads the reviewed baseline map and its source digest."

  @spec map!() :: map()

  def map!, do: load_map!()

  defp classify_repo(repo, map) do

    versions = migration_versions(repo)

    baseline_versions = baseline_versions(map)

    prior? = subset?(map.data["prior_signature_versions"], versions)

    current? = Enum.any?(map.data["current_root_versions"], &MapSet.member?(versions, &1))

    baseline_count = Enum.count(baseline_versions, &MapSet.member?(versions, &1))

    fact_counts =

      fact_counts(repo, map.data, if(baseline_count == 0, do: :before, else: :after))

    bridge = bridge_state(repo)

    application_table_count = application_table_count(repo)

    classification =

      cond do

        application_table_count == 0 ->

          :empty

        prior? and baseline_count == 0 and bridge == :absent and fact_counts.missing == 0 ->

          :prior

        prior? and baseline_count == length(baseline_versions) and bridge == :complete and

            fact_counts.missing == 0 ->

          :prior_baselined

        prior? and (baseline_count > 0 or bridge != :absent) ->

          :prior_partial

        current? and not prior? ->

          :current

        true ->

          :unknown

      end

    %{

      schema: "openagents.migration-lineage-status.v1",

      classification: Atom.to_string(classification),

      lineage_id: map.data["lineage_id"],

      map_digest: map.digest,

      migration_count: MapSet.size(versions),

      baseline_entries_present: baseline_count,

      baseline_entries_required: length(baseline_versions),

      required_facts_present: fact_counts.present,

      required_facts_missing: fact_counts.missing,

      bridge_state: Atom.to_string(bridge)

    }

  end

  defp fact_counts(repo, map, phase) do

    phase_indexes =

      if phase == :before,

        do: map["pre_baseline_required_indexes"],

        else: []

    facts =

      Enum.map(map["required_tables"], &table_exists?(repo, &1)) ++

        Enum.flat_map(map["required_columns"], fn {table, columns} ->

          Enum.map(columns, &column_exists?(repo, table, &1))

        end) ++

        Enum.map(map["required_column_types"], fn {qualified_column, type} ->

          [table, column] = String.split(qualified_column, ".", parts: 2)

          column_type?(repo, table, column, type)

        end) ++

        Enum.map(map["required_constraints"], &constraint_exists?(repo, &1)) ++

        Enum.map(map["required_indexes"], &index_exists?(repo, &1)) ++

        Enum.map(phase_indexes, &index_exists?(repo, &1)) ++

        Enum.map(map["forbidden_constraints"], &(not constraint_exists?(repo, &1))) ++

        Enum.map(map["forbidden_tables"], &(not table_exists?(repo, &1)))

    present = Enum.count(facts, & &1)

    %{present: present, missing: length(facts) - present}

  end

  defp bridge_state(repo) do

    column? = column_exists?(repo, "users", "browser_key_hash")

    index? = index_exists?(repo, "users_browser_key_hash_index")

    case {column?, index?} do

      {false, false} -> :absent

      {true, true} -> :complete

      _partial -> :partial

    end

  end

  defp application_table_count(repo) do

    %{rows: [[count]]} =

      SQL.query!(repo, """

      SELECT count(*)

        FROM pg_catalog.pg_tables

       WHERE schemaname = current_schema()

         AND tablename <> 'schema_migrations'

      """)

    count

  end

  defp migration_versions(repo) do

    if table_exists?(repo, "schema_migrations") do

      %{rows: rows} =

        SQL.query!(repo, "SELECT version FROM schema_migrations ORDER BY version", [])

      rows |> Enum.map(fn [version] -> version end) |> MapSet.new()

    else

      MapSet.new()

    end

  end

  defp table_exists?(repo, table) do

    exists?(

      repo,

      "SELECT 1 FROM information_schema.tables WHERE table_schema = current_schema() AND table_name = $1",

      [table]

    )

  end

  defp column_exists?(repo, table, column) do

    exists?(

      repo,

      "SELECT 1 FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1 AND column_name = $2",

      [table, column]

    )

  end

  defp column_type?(repo, table, column, type) do

    exists?(

      repo,

      "SELECT 1 FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = $1 AND column_name = $2 AND udt_name = $3",

      [table, column, type]

    )

  end

  defp constraint_exists?(repo, constraint) do

    exists?(

      repo,

      "SELECT 1 FROM information_schema.table_constraints WHERE constraint_schema = current_schema() AND constraint_name = $1",

      [constraint]

    )

  end

  defp index_exists?(repo, index) do

    exists?(

      repo,

      "SELECT 1 FROM pg_catalog.pg_indexes WHERE schemaname = current_schema() AND indexname = $1",

      [index]

    )

  end

  defp exists?(repo, query, parameters) do

    case SQL.query!(repo, query, parameters) do

      %{num_rows: count} when count > 0 -> true

      _none -> false

    end

  end

  defp apply_bridge!(repo) do

    _column = SQL.query!(repo, "ALTER TABLE users ADD COLUMN browser_key_hash bytea", [])

    _index =

      SQL.query!(repo, """

      CREATE UNIQUE INDEX users_browser_key_hash_index

          ON users (browser_key_hash)

       WHERE browser_key_hash IS NOT NULL

      """)

    :ok

  end

  defp insert_baseline_versions!(repo, versions) do

    Enum.each(versions, fn version ->

      _result =

        SQL.query!(

          repo,

          "INSERT INTO schema_migrations (version, inserted_at) VALUES ($1, NOW()) ON CONFLICT (version) DO NOTHING",

          [version]

        )

    end)

  end

  defp baseline_versions(map) do

    Enum.map(map.data["baseline_entries"], & &1["current_version"])

  end

  defp subset?(required, actual) do

    Enum.all?(required, &MapSet.member?(actual, &1))

  end

  defp load_map! do

    path = :openagents |> :code.priv_dir() |> to_string() |> Path.join(@map_file)

    bytes = File.read!(path)

    data = Jason.decode!(bytes)

    if data["schema"] != "openagents.migration-lineage.v1" or

         data["lineage_id"] != "prior-2026-08-19" do

      raise "migration lineage map has an invalid identity"

    end

    %{data: data, digest: :crypto.hash(:sha256, bytes) |> Base.encode16(case: :lower)}

  end

  defp ensure_admitted do

    environment = Application.get_env(:openagents, :runtime_environment)

    staging_gate = Application.get_env(:openagents, :staging_gate, 0)

    if environment == :test or (environment == :staging and staging_gate >= 13) do

      :ok

    else

      {:error, :migration_lineage_not_admitted}

    end

  end

  defp validate_snapshot_ref(snapshot_ref) do

    if Regex.match?(@snapshot_pattern, snapshot_ref),

      do: :ok,

      else: {:error, :invalid_snapshot_reference}

  end

  defp result(classification, snapshot_ref, changed?) do

    classification

    |> Map.put(:snapshot_ref, snapshot_ref)

    |> Map.put(:changed, changed?)

  end

  defp normalize_transaction({:ok, result}), do: {:ok, result}

  defp normalize_transaction({:error, reason}), do: {:error, reason}

  defp encode_result(status, result) do

    result

    |> Map.put(:status, status)

    |> Jason.encode!()

  end

  defp bounded_reason(reason) when is_atom(reason), do: Atom.to_string(reason)

  defp bounded_reason(_reason), do: "lineage_operation_failed"

end

    {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))

  end

  @doc "Classifies or baselines the reviewed prior database lineage."

  @spec migration_lineage(String.t(), String.t() | nil) :: :ok

  def migration_lineage(mode, snapshot_ref \\ nil) do

    load_app()

    for repo <- repos() do

      {:ok, output, _apps} =

        Ecto.Migrator.with_repo(repo, fn started_repo ->

          OpenAgents.MigrationLineage.command!(started_repo, mode, snapshot_ref)

        end)

      IO.puts(output)

    end

    :ok

  end

  @doc "Rewrap retained GitHub grants with the configured active vault key."

  def rotate_github_tokens do

    load_app()

cd "$repo_root"

ops/ci/reference-check.sh

sh -n rel/overlays/bin/migration-lineage

sh -n ops/staging/cleanup-run.sh

elixir ops/ci/docs-check.exs

MIX_ENV=test mix test --warnings-as-errors \

  test/openagents/log_safety_test.exs \

  test/openagents/migration_lineage_test.exs \

  test/openagents/runtime_config_test.exs \

  test/openagents/staging_cleanup_test.exs \

  test/openagents_web/icon_affordances_test.exs \

{

  "schema": "openagents.migration-lineage.v1",

  "lineage_id": "prior-2026-08-19",

  "prior_signature_versions": [

    20260816170746,

    20260816203029,

    20260816205329,

    20260816211100,

    20260816211900,

    20260816220500,

    20260816222500,

    20260816224000,

    20260816233000,

    20260817000500,

    20260817070000,

    20260817080000,

    20260817125732,

    20260817170050,

    20260818003948,

    20260818150000,

    20260819011000,

    20260819012000,

    20260819013000

  ],

  "current_root_versions": [

    20260816214000,

    20260816214200

  ],

  "shared_versions": [

    20260816214500,

    20260816214735,

    20260816215500,

    20260816220000,

    20260816224054,

    20260816230000,

    20260816231500,

    20260816231919,

    20260816234500,

    20260816235500,

    20260817002000,

    20260817003500,

    20260817005000,

    20260817010500,

    20260817012000,

    20260817012100,

    20260817020000,

    20260817020100,

    20260817030000,

    20260817030100,

    20260817040000,

    20260817040100,

    20260817050000,

    20260817060000,

    20260817065533,

    20260817140345,

    20260817171456,

    20260818003237,

    20260818003358,

    20260818003949,

    20260818150100,

    20260818160000,

    20260818230000,

    20260818232337,

    20260818234500,

    20260819010000,

    20260819080000,

    20260819170000

  ],

  "baseline_entries": [

    {

      "current_version": 20260816214000,

      "satisfied_by": [20260817070000, 20260817080000, 20260817125732],

      "reason": "The prior lineage already created the users table and GitHub identity columns."

    },

    {

      "current_version": 20260816214200,

      "satisfied_by": [

        20260816170746,

        20260816203029,

        20260816205329,

        20260816211100,

        20260816211900,

        20260816220500,

        20260816222500,

        20260816224000,

        20260816233000,

        20260817000500,

        20260818003948,

        20260818150000

      ],

      "reason": "The prior lineage already created the conversation, turn, receipt, provider-step, and tool-step tables."

    },

    {

      "current_version": 20260819214108,

      "satisfied_by": [20260817070000],

      "reason": "The prior GitHub account migration already created OAuth attempts."

    },

    {

      "current_version": 20260819223229,

      "satisfied_by": [20260819011000],

      "reason": "The prior lineage already created UUID forge fleet targets in the final receipt shape."

    },

    {

      "current_version": 20260819223230,

      "satisfied_by": [20260819012000],

      "reason": "The prior lineage already created UUID forge build receipts in the final pre-hardening shape."

    },

    {

      "current_version": 20260819223231,

      "satisfied_by": [20260819013000],

      "reason": "The prior lineage already created UUID forge deployment receipts."

    },

    {

      "current_version": 20260819233053,

      "satisfied_by": [20260817070000, 20260817170050],

      "reason": "The prior lineage already added account constraints and leaderboard policy; the bridge adds users.browser_key_hash before baselining this version."

    },

    {

      "current_version": 20260820025008,

      "satisfied_by": [20260819011000, 20260819013000],

      "reason": "The prior forge target and deployment identifiers are already UUIDs; replay would convert them to bigint."

    },

    {

      "current_version": 20260820025112,

      "satisfied_by": [20260819013000],

      "reason": "The prior forge deployment receipt already has the nodes column."

    },

    {

      "current_version": 20260820025133,

      "satisfied_by": [20260819013000],

      "reason": "The prior forge deployment receipt already has result, canary, timing, and node columns."

    },

    {

      "current_version": 20260820031230,

      "satisfied_by": [20260819011000, 20260819012000, 20260819013000],

      "reason": "The prior forge tables already use UUID identifiers; replay would truncate receipt data."

    },

    {

      "current_version": 20260820031258,

      "satisfied_by": [20260819012000],

      "reason": "The prior forge build target identifier is already a UUID."

    },

    {

      "current_version": 20260820031313,

      "satisfied_by": [20260819012000, 20260819013000],

      "reason": "The prior receipt tables already omit the temporary target foreign keys."

    },

    {

      "current_version": 20260820040000,

      "satisfied_by": [20260819011000, 20260819012000],

      "reason": "The prior target and build tables already use the aligned receipt schemas; replay would drop build history."

    }

  ],

  "bridge_changes": [

    {

      "operation": "add_nullable_column",

      "table": "users",

      "column": "browser_key_hash",

      "type": "bytea"

    },

    {

      "operation": "add_partial_unique_index",

      "index": "users_browser_key_hash_index",

      "predicate": "browser_key_hash IS NOT NULL"

    }

  ],

  "reconciliation_versions_to_run": [

    20260820030850,

    20260820030959,

    20260820120000,

    20260820160000

  ],

  "new_versions_to_run": [

    20260819202148,

    20260819202444,

    20260819202647,

    20260819202649,

    20260819203939,

    20260819203943,

    20260819203944,

    20260820032524,

    20260820073810,

    20260820074227,

    20260820074644,

    20260820082100,

    20260820085203,

    20260820130000,

    20260820140000,

    20260820150000

  ],

  "required_tables": [

    "users",

    "visitors",

    "conversations",

    "messages",

    "turns",

    "turn_receipts",

    "turn_provider_steps",

    "turn_tool_steps",

    "github_oauth_attempts",

    "forge_fleet_targets",

    "forge_builds",

    "forge_deploys"

  ],

  "required_columns": {

    "users": ["id", "github_id", "github_login", "github_name", "github_avatar_url", "status", "banned_at", "ban_reason_code", "last_authenticated_at", "github_token_ciphertext", "public_leaderboard_opted_out"],

    "visitors": ["id", "browser_key_hash", "user_id"],

    "conversations": ["id", "visitor_id"],

    "messages": ["id", "conversation_id", "role", "content", "status", "provider_response_id", "modality", "voice_session_id", "provider_item_id", "transcript_kind", "interrupted", "work_job_id", "search_vector"],

    "turns": ["id", "conversation_id", "user_message_id", "assistant_message_id", "status", "error_message", "error_code", "provider_response_id", "started_at", "completed_at"],

    "turn_receipts": ["id", "turn_id", "schema_version", "status", "model_id", "persona_id", "persona_digest", "role_id", "role_digest", "role_selection", "instruction_digest", "input_digest", "input_message_count", "input_bytes", "tool_catalog_digest", "blueprint_revision", "blueprint_digest", "program_artifact_id", "program_artifact_digest", "program_artifact_receipt", "memory_snapshot_ref", "profile_memory_snapshot_ref", "preference_snapshot_ref", "used_preferences", "experience_bank_ref", "used_experiences", "used_source_refs", "used_tool_step_refs", "used_memory_evidence", "usage", "provider_started_at", "provider_completed_at"],

    "turn_provider_steps": ["id", "turn_receipt_id", "sequence", "provider_id", "model_id", "status", "provider_response_id", "usage", "error_code", "started_at", "completed_at"],

    "turn_tool_steps": ["id", "turn_id", "turn_receipt_id", "sequence", "provider_call_id", "provider_item_id", "provider_response_id", "tool_name", "tool_version", "module_id", "module_artifact_digest", "executor_implementation_digest", "routing_receipt_id", "side_effect_class", "invocation_key", "attribution_policy_id", "attribution_policy_version", "attribution_policy_digest", "billable", "billable_attribution_key", "cost_units", "catalog_digest", "raw_arguments", "argument_digest", "status", "outcome_digest", "outcome_receipt_ref", "usage", "result", "error", "executor_id", "executor_disclosure", "target_receipt_refs", "attribution_refs", "requested_at", "started_at", "completed_at"],

    "github_oauth_attempts": ["id", "state_digest", "expires_at", "consumed_at"],

    "forge_fleet_targets": ["id", "repo", "sha", "promoted_by", "status", "details"],

    "forge_builds": ["id", "repo", "sha", "target_id", "modules", "warnings", "tests", "duration_ms", "artifact"],

    "forge_deploys": ["id", "repo", "sha", "target_id", "modules", "nodes", "result", "canary", "push_to_live_ms"]

  },

  "required_column_types": {

    "users.id": "uuid",

    "users.github_id": "int8",

    "users.github_avatar_url": "text",

    "messages.search_vector": "tsvector",

    "turn_tool_steps.raw_arguments": "text",

    "forge_fleet_targets.id": "uuid",

    "forge_builds.id": "uuid",

    "forge_builds.target_id": "uuid",

    "forge_builds.modules": "_varchar",

    "forge_deploys.id": "uuid",

    "forge_deploys.target_id": "uuid",

    "forge_deploys.modules": "_varchar",

    "forge_deploys.nodes": "_varchar"

  },

  "required_constraints": [

    "users_status_check",

    "users_ban_state_check",

    "visitors_identity_source_check",

    "forge_fleet_target_status",

    "forge_deploys_result"

  ],

  "required_indexes": [

    "users_github_id_index",

    "visitors_browser_key_hash_index",

    "visitors_user_id_index",

    "github_oauth_attempts_state_digest_index"

  ],

  "pre_baseline_required_indexes": [

    "forge_builds_repo_sha_target_id_index"

  ],

  "forbidden_constraints": [

    "forge_builds_target_id_fkey",

    "forge_deploys_target_id_fkey"

  ],

  "forbidden_tables": [

    "forge_builds_phase3_legacy"

  ]

}

defmodule OpenAgents.Repo.Migrations.ReconcileVisitorIdentityConstraint do

  use Ecto.Migration

  def up do

    execute("""

    DO $$

    BEGIN

      IF NOT EXISTS (

        SELECT 1

          FROM pg_constraint

         WHERE conname = 'visitors_identity_source_check'

           AND conrelid = 'visitors'::regclass

      ) THEN

        ALTER TABLE visitors

          ADD CONSTRAINT visitors_identity_source_check

          CHECK (

            (browser_key_hash IS NOT NULL AND user_id IS NULL) OR

            (browser_key_hash IS NULL AND user_id IS NOT NULL)

          );

      END IF;

    END

    $$;

    """)

  end

  def down do

    # The prior database lineage already owns this constraint. A down migration

    # cannot distinguish that inherited constraint from one created above, so

    # preserving it is the only rollback-compatible operation.

    :ok

  end

end

#!/bin/sh

set -eu

cd -P -- "$(dirname -- "$0")"

case "${1:-check}" in

  check) action=check ;;

  --apply) action=apply ;;

  *) echo "usage: bin/migration-lineage [check|--apply]" >&2; exit 64 ;;

esac

if [ "$action" = apply ]; then

  : "${OPENAGENTS_STAGING_SNAPSHOT_ID:?OPENAGENTS_STAGING_SNAPSHOT_ID is required}"

fi

./prepare-config >/dev/null

export OPENAGENTS_MIGRATION_LINEAGE_ACTION="$action"

exec ./openagents eval \

  'OpenAgents.Release.migration_lineage(System.fetch_env!("OPENAGENTS_MIGRATION_LINEAGE_ACTION"), System.get_env("OPENAGENTS_STAGING_SNAPSHOT_ID"))'

defmodule OpenAgents.MigrationLineageTest do

  use OpenAgents.DataCase, async: false

  import OpenAgents.AccountsFixtures

  alias OpenAgents.MigrationLineage

  alias OpenAgents.Repo

  @snapshot_ref "local-snapshot-20260820"

  test "the baseline map partitions every current migration" do

    %{data: map, digest: digest} = MigrationLineage.map!()

    current_versions =

      "priv/repo/migrations/*.exs"

      |> Path.wildcard()

      |> Enum.map(fn path ->

        path |> Path.basename() |> String.slice(0, 14) |> String.to_integer()

      end)

      |> MapSet.new()

    baseline_versions = Enum.map(map["baseline_entries"], & &1["current_version"])

    classified_versions =

      map["shared_versions"] ++

        baseline_versions ++

        map["reconciliation_versions_to_run"] ++ map["new_versions_to_run"]

    assert MapSet.new(classified_versions) == current_versions

    assert length(classified_versions) == MapSet.size(current_versions)

    assert digest =~ ~r/\A[0-9a-f]{64}\z/

  end

  test "a current-lineage database is classified without mutation" do

    assert {:ok, result} = MigrationLineage.classify(Repo)

    assert result.classification == "current"

    assert result.bridge_state == "complete"

  end

  test "the known prior lineage is baselined once without deleting account data" do

    user = repository_user_fixture("lineage-account")

    prepare_prior_lineage!()

    assert {:ok, before} = MigrationLineage.classify(Repo)

    assert before.classification == "prior"

    assert before.required_facts_missing == 0

    assert {:ok, result} = MigrationLineage.baseline(Repo, @snapshot_ref)

    assert result.classification == "prior_baselined"

    assert result.changed

    assert result.snapshot_ref == @snapshot_ref

    assert user_exists?(user.id)

    assert column_exists?("users", "browser_key_hash")

    assert index_exists?("users_browser_key_hash_index")

    assert {:ok, repeated} = MigrationLineage.baseline(Repo, @snapshot_ref)

    refute repeated.changed

    encoded = MigrationLineage.command!(Repo, "check", nil)

    refute encoded =~ user.github_login

    assert Jason.decode!(encoded)["classification"] == "prior_baselined"

  end

  test "an unknown or partially modified lineage is refused" do

    prepare_prior_lineage!()

    [first_baseline | _rest] = baseline_versions()

    insert_version!(first_baseline)

    assert {:ok, %{classification: "prior_partial"}} = MigrationLineage.classify(Repo)

    assert {:error, :partial_lineage_forbidden} =

             MigrationLineage.baseline(Repo, @snapshot_ref)

    Repo.query!("DELETE FROM schema_migrations")

    insert_version!(20_260_101_000_000)

    assert {:ok, %{classification: "unknown"}} = MigrationLineage.classify(Repo)

    assert {:error, :lineage_not_baselineable} =

             MigrationLineage.baseline(Repo, @snapshot_ref)

  end

  test "baseline mutation requires a bounded snapshot reference" do

    assert {:error, :invalid_snapshot_reference} = MigrationLineage.baseline(Repo, "missing")

    assert {:error, :invalid_snapshot_reference} =

             MigrationLineage.baseline(Repo, "snapshot/contains/path")

  end

  defp prepare_prior_lineage! do

    Repo.query!("DELETE FROM schema_migrations")

    Repo.query!("DROP INDEX users_browser_key_hash_index")

    Repo.query!("ALTER TABLE users DROP COLUMN browser_key_hash")

    Repo.query!("ALTER TABLE users ALTER COLUMN github_avatar_url TYPE text")

    Repo.query!("""

    CREATE UNIQUE INDEX forge_builds_repo_sha_target_id_index

        ON forge_builds (repo, sha, target_id)

    """)

    %{data: map} = MigrationLineage.map!()

    Enum.each(map["prior_signature_versions"], &insert_version!/1)

  end

  defp baseline_versions do

    %{data: map} = MigrationLineage.map!()

    Enum.map(map["baseline_entries"], & &1["current_version"])

  end

  defp insert_version!(version) do

    Repo.query!(

      "INSERT INTO schema_migrations (version, inserted_at) VALUES ($1, NOW())",

      [version]

    )

  end

  defp column_exists?(table, column) do

    %{num_rows: count} =

      Repo.query!(

        "SELECT 1 FROM information_schema.columns WHERE table_name = $1 AND column_name = $2",

        [table, column]

      )

    count == 1

  end

  defp index_exists?(index) do

    %{num_rows: count} =

      Repo.query!("SELECT 1 FROM pg_indexes WHERE indexname = $1", [index])