defmodule OpenAgents.Traces do

  @moduledoc """

  Store and retrieve account-scoped ATIF trace documents.

  """

  alias OpenAgents.Accounts.User

  alias OpenAgents.Repo

  alias OpenAgents.Traces.Trace

  @maximum_trace_bytes 10_485_760

  @atif_prefixes ["ATIF/1.", "ATIF-v1."]

  @default_visibility "dark"

  @doc "The largest trace body this surface accepts, in bytes."

  def maximum_trace_bytes, do: @maximum_trace_bytes

  @doc """

  Store an ATIF document for an account.

  Re-uploading the same canonical bytes for the same account returns the

  existing trace. A document without an admitted `schema_version` or one that

  exceeds the size ceiling is refused.

  """

  def store(%User{} = user, %{} = document), do: store(user, document, [])

  def store(%User{id: user_id} = _user, %{} = document, options) do

    canonical = Jason.encode!(document)

    byte_size = byte_size(canonical)

    cond do

      byte_size > @maximum_trace_bytes ->

        {:error, :body_too_large}

      not valid_atif?(document) ->

        {:error, :invalid_atif}

      true ->

        digest =

          "sha256:" <>

            (:crypto.hash(:sha256, canonical) |> Base.encode16(case: :lower))

        visibility = normalize_visibility(options, document)

        case Repo.get_by(Trace, user_id: user_id, digest: digest) do

          %Trace{} = existing ->

            {:ok, existing, :existing}

          nil ->

            attrs = %{

              user_id: user_id,

              digest: digest,

              visibility: visibility,

              document: document,

              byte_size: byte_size

            }

            %Trace{}

            |> Trace.create_changeset(attrs)

            |> Repo.insert()

            |> case do

              {:ok, trace} -> {:ok, trace, :created}

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

            end

        end

    end

  end

  def store(_user, _document, _options), do: {:error, :invalid_atif}

  defp valid_atif?(document) do

    version = Map.get(document, "schema_version") || Map.get(document, :schema_version)

    is_binary(version) and

      String.starts_with?(version, @atif_prefixes)

  end

  defp normalize_visibility(options, document) do

    from_options = Keyword.get(options, :visibility)

    from_document = Map.get(document, "visibility") || Map.get(document, :visibility)

    candidate = from_options || from_document || @default_visibility

    if is_binary(candidate) do

      String.trim(candidate)

    else

      @default_visibility

    end

  end

end

defmodule OpenAgents.Traces.Trace do

  @moduledoc """

  An account-scoped ATIF trace upload.

  A trace is an owner-attested document with a stable digest. The server stores

  the document as received and deduplicates per owner, so re-uploading the same

  bytes returns the existing record rather than creating a duplicate.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Transparency

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

  @foreign_key_type :binary_id

  @timestamps_opts [type: :utc_datetime_usec]

  @visibilities Enum.map(Transparency.tier_atoms(), &to_string/1)

  @default_visibility "dark"

  schema "traces" do

    field :user_id, :binary_id

    field :digest, :string

    field :visibility, :string, default: @default_visibility

    field :document, :map

    field :byte_size, :integer

    timestamps(updated_at: false)

  end

  @type t :: %__MODULE__{}

  def default_visibility, do: @default_visibility

  def visibilities, do: @visibilities

  def create_changeset(%__MODULE__{} = trace, attrs) do

    trace

    |> cast(attrs, [:digest, :visibility, :document, :byte_size])

    |> put_change(:user_id, attrs.user_id)

    |> validate_required([:user_id, :digest, :visibility, :document, :byte_size])

    |> validate_inclusion(:visibility, @visibilities)

    |> validate_number(:byte_size, greater_than_or_equal_to: 0)

    |> validate_format(:digest, ~r/\Asha256:[0-9a-f]{64}\z/)

    |> foreign_key_constraint(:user_id)

    |> unique_constraint([:user_id, :digest], name: :traces_user_id_digest_index)

  end

end

    # that will not answer is a temporary unreadability rather than an absence.

    # Reporting it as `not_found` would tell a pusher their push is not on

    # record, which is a different and much worse claim.

    "push_record_unreadable" => {503, "The push record is temporarily unreadable"}

    "push_record_unreadable" => {503, "The push record is temporarily unreadable"},

    "trace_body_too_large" => {413, "The trace body is larger than the maximum allowed size"}

  }

  @doc """

        {:required_bearer, :comment, :envelope},

      "put /api/v3/repos/:owner/:repo/labels/:name" => {:required_bearer, :label, :envelope},

      "put /api/v3/repos/:owner/:repo/milestones/:milestone_number" =>

        {:required_bearer, :milestone, :envelope}

        {:required_bearer, :milestone, :envelope},

      "post /api/v3/traces" => {:required_bearer, :trace, :envelope}

    }

  end

end

defmodule OpenAgentsWeb.TraceController do

  @moduledoc """

  Accept ATIF v1 trace uploads at `POST /api/v3/traces`.

  """

  use OpenAgentsWeb, :controller

  alias OpenAgents.Traces

  alias OpenAgentsWeb.ApiError

  def create(conn, params) do

    document = conn.body_params

    visibility = parse_visibility(params)

    case Traces.store(conn.assigns.current_user, document, visibility: visibility) do

      {:ok, trace, :created} ->

        conn

        |> put_status(:created)

        |> json(trace_view(trace))

      {:ok, trace, :existing} ->

        conn

        |> put_status(:ok)

        |> json(trace_view(trace))

      {:error, :body_too_large} ->

        ApiError.refuse(conn, "trace_body_too_large")

      {:error, :invalid_atif} ->

        ApiError.validation_failed(conn, %{

          "document" => ["The document is not a valid ATIF v1 object."]

        })

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

        ApiError.changeset(conn, changeset)

    end

  end

  defp parse_visibility(params) do

    case Map.get(params, "visibility") do

      value when is_binary(value) -> String.trim(value)

      _ -> nil

    end

  end

  defp trace_view(trace) do

    %{

      "id" => trace.id,

      "url" => OpenAgentsWeb.Endpoint.url() <> "/api/v3/traces/" <> trace.id,

      "digest" => trace.digest,

      "byte_size" => trace.byte_size,

      "visibility" => trace.visibility,

      "inserted_at" => DateTime.to_iso8601(trace.inserted_at)

    }

  end

end

    get "/models", ModelCatalogController, :index

    post "/threads", ThreadController, :create

    post "/traces", TraceController, :create

    get "/threads", ThreadController, :index

    get "/threads/:thread_id", ThreadController, :show

    delete "/threads/:thread_id", ThreadController, :delete

    20260824210500,

    20260824230007,

    20260824230730,

    20260824231951

    20260824231951,

    20260825024500

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.CreateTraces do

  @moduledoc """

  ATIF trace documents uploaded by an account.

  A trace is an owner-attested document with a stable SHA-256 digest. The

  server stores the document as received, deduplicates per owner, and records

  the transparency tier the owner consented to. The vocabulary for the

  `visibility` tier is the shared `dark/pulse/ledger/glass` ladder.

  """

  use Ecto.Migration

  def change do

    create table(:traces, primary_key: false) do

      add :id, :binary_id, primary_key: true

      add :user_id,

          references(:users, type: :binary_id, on_delete: :delete_all),

          null: false

      add :digest, :string, null: false

      add :visibility, :string, null: false, default: "dark"

      add :document, :map, null: false

      add :byte_size, :integer, null: false

      timestamps(type: :utc_datetime_usec, updated_at: false)

    end

    create unique_index(:traces, [:user_id, :digest], name: :traces_user_id_digest_index)

    create constraint(:traces, :traces_visibility_check,

             check: "visibility IN ('dark','pulse','ledger','glass')"

           )

  end

end

defmodule OpenAgentsWeb.TraceControllerTest do

  @moduledoc """

  Accept ATIF v1 trace uploads at `POST /api/v3/traces`.

  """

  use OpenAgentsWeb.ConnCase, async: false

  alias OpenAgents.Repo

  alias OpenAgents.Traces.Trace

  describe "POST /api/v3/traces" do

    test "returns the trace id and url for a valid ATIF v1.7 document", %{conn: conn} do

      body =

        conn

        |> put_chat_api_token("trace-valid")

        |> post(~p"/api/v3/traces", %{

          "schema_version" => "ATIF/1.7",

          "trace" => %{"events" => [%{"type" => "step"}]}

        })

        |> json_response(201)

      assert %{"id" => id, "url" => url} = body

      assert is_binary(id)

      assert url =~ "/api/v3/traces/#{id}"

      assert body["visibility"] == "dark"

      assert is_integer(body["byte_size"])

      assert is_binary(body["digest"])

      assert String.starts_with?(body["digest"], "sha256:")

    end

    test "returns the existing trace when the same owner uploads the same document again", %{

      conn: conn

    } do

      document = %{

        "schema_version" => "ATIF/1.7",

        "trace" => %{"events" => [%{"type" => "step"}]}

      }

      first =

        conn

        |> put_chat_api_token("trace-dedup")

        |> post(~p"/api/v3/traces", document)

        |> json_response(201)

      second =

        conn

        |> put_chat_api_token("trace-dedup")

        |> post(~p"/api/v3/traces", document)

        |> json_response(200)

      assert second["id"] == first["id"]

      assert second["digest"] == first["digest"]

      assert second["byte_size"] == first["byte_size"]

      assert Repo.aggregate(Trace, :count) == 1

    end

    test "refuses a body that exceeds the size ceiling", %{conn: conn} do

      big = String.duplicate("x", 10_485_761)

      body =

        conn

        |> put_chat_api_token("trace-oversize")

        |> post(~p"/api/v3/traces", %{

          "schema_version" => "ATIF/1.7",

          "data" => big

        })

        |> json_response(413)

      assert body["code"] == "trace_body_too_large"

    end

    test "rejects an unauthenticated call", %{conn: conn} do

      conn

      |> post(~p"/api/v3/traces", %{"schema_version" => "ATIF/1.7"})

      |> assert_api_error(401, "unauthenticated")

    end

    test "rejects an invalid ATIF schema_version", %{conn: conn} do

      conn =

        conn

        |> put_chat_api_token("trace-invalid")

        |> post(~p"/api/v3/traces", %{"schema_version" => "ATIF/2.0"})

      assert_api_error(conn, 422, "validation_failed",

        errors: %{"document" => ["The document is not a valid ATIF v1 object."]}

      )

    end

    test "rejects a document with no schema_version", %{conn: conn} do

      conn =

        conn

        |> put_chat_api_token("trace-no-version")

        |> post(~p"/api/v3/traces", %{"trace" => %{}})

      assert_api_error(conn, 422, "validation_failed")

    end

    test "uses dark visibility by default and allows an explicit tier", %{conn: conn} do

      body =

        conn

        |> put_chat_api_token("trace-visibility")

        |> post("/api/v3/traces?visibility=ledger", %{

          "schema_version" => "ATIF/1.7",

          "trace" => %{}

        })

        |> json_response(201)

      assert body["visibility"] == "ledger"

    end

    test "different owners uploading the same document get separate traces", %{conn: conn} do

      document = %{

        "schema_version" => "ATIF/1.7",

        "trace" => %{"events" => [%{"type" => "step"}]}

      }

      first =

        conn

        |> put_chat_api_token("trace-owner-one")

        |> post(~p"/api/v3/traces", document)

        |> json_response(201)

      second =

        conn

        |> put_chat_api_token("trace-owner-two")

        |> post(~p"/api/v3/traces", document)

        |> json_response(201)

      refute first["id"] == second["id"]

    end

  end

end