# The delegation target seam

**Date:** 2026-08-25

**Issue:** [#37](https://openagents.com/OpenAgentsInc/openagents.com/issues/37), *Integrate cloud computers with Work, chat, text, voice, and API*

**Source:** `docs/2026-08-22-cloud-computer-scale-architecture-audit.md`

**Status:** The seam in section 4 shipped with this document. Sections 5 and 6 are the decisions it defers.

Issue #37 asks for five integrations: Work, chat, text, voice, and the

authenticated API. This document argues they are one integration and four

renderings, names the part they share, and records what shipped.

---

## 1. "Cloud computer" is not a noun this codebase gets

`docs/taxonomy.md` already settled the word, and #37 collides with it:

> **computer** — someone's own machine, connected or absent, never provisioned

> **box** — a sandbox VM this application provisions, caps, and reclaims

So an OpenAgents-managed cloud computer cannot be called a computer here. It is

a **Box**, and #37's "customer-connected computer" is a **Computer**. The

delegation target kind is already `box` or `computer`, the kind already travels

in the identifier (`box:{uuid}`, `computer:{uuid}`), and authority is already

scoped per kind.

Adding a third kind named `cloud_computer` would create exactly the collision

the taxonomy exists to prevent: three nouns, two of which are provisioned, one

of which is not, and a reader who cannot tell from the name which failure a

missing one is. A Box that is gone was reclaimed and you can provision another.

A Computer that is gone is somebody's laptop.

**Decision.** #37 adds no target kind. It makes the two that exist addressable,

observable, and advertisable through one seam.

---

## 2. What exists today

Measured by direct reading, not by documentation.

**Real, in this repository:**

| Thing | Where | What it does |

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

| Delegation facade | `OpenAgents.Delegations` | One `start` / `get` / `cancel` / `inventory` across both kinds, at `/api/v1/conversations/{id}/delegations`. Stores nothing; derives everything. IDENTITY-009. |

| Box substrate | `OpenAgents.Box`, `OpenAgents.BoxRuns` | Rents VMs from the Box Public API at `ascii.dev`. Ledgers `conversation_boxes`, `box_runs`, `box_fanout_items`. |

| Computer substrate | `OpenAgents.Machines`, `OpenAgents.Computer`, `OpenAgents.ComputerAgentJobs` | Pairing, credential, live WebSocket control, durable ACP delegations as `work_jobs` rows. |

| Capacity and matching | `OpenAgents.Capacity` | Runtime classes `standard`, `strong`, `batch`, `connected`, each with an isolation, egress, and data location. Published at `/api/v1/capacity` and `/api/v1/capacity/matches`. Issue #76. |

**Documented, and not real anywhere:**

- The logical-computer record, the runtime-lease record, and the command

  journal with `may_have_started`. None exists in this repository.

- The provider-neutral control-plane `Req` client #37 asks for. **There is no

  endpoint for it to call.** In the `OpenAgentsInc/openagents` monorepo,

  `crates/openagents-cloud-contract/src/cloud_computer_v1.rs` and the 34-file

  `packages/khala-sync-server/src/cloud-computer-*.ts` set are real, tested

  code that no binary imports and no route exposes; there are no fixtures for

  `cloud_computer.v1` and no OpenAPI, protobuf, or JSON schema describing any

  cloud-computer request or response. The one machine-readable artifact,

  `schema/cloud_computer.v1.schema.json`, describes a record, not an endpoint.

That last finding decides the shape of this work. A `Req` client written today

would be a client for something that does not answer.

---

## 3. The seam, and why five surfaces share exactly one

Work, chat, text, voice, and the API differ in who is asking and how the answer

is drawn. They ask the same three questions of a target:

1. **How is it addressed?** By the kind-prefixed reference the facade already

   parses. Settled, and nothing here mints a second identifier.

2. **What is it doing?** Today, four vocabularies answer this and none of them

   agree. `conversation_boxes.state` has ten values; `box_runs.state` has eight;

   `work_jobs.status` has seven; a Computer has `status` plus a live

   reachability read. A surface that wants to say "this computer is busy" must

   know all four.

3. **What may this caller do to it?** Nothing answered this at all. Every

   surface had to re-derive it from kind, state, and scopes.

The third question is the one that earns a module. Reach is scoped per kind

(IDENTITY-009), so a surface that decides for itself whether a caller may start

work on a target is a surface that can widen reach past the substrate. Five

surfaces means five chances to get that wrong, and four of them would be

written by someone reading the fifth.

Before this change there were also three divergent projections of "what can I

delegate to": the `computer_list` tool's own result schema, which cannot see a

Box at all; the API's `openagents.delegation_targets.v1`; and the chat panel's

fleet projection. Three answers to one question.

---

## 4. What shipped

`OpenAgents.Delegations.Target` — pure, no database, no process — computes five

fields for any target, and two for any delegation.

| Field | Meaning |

| --- | --- |

| `custody` | `openagents_managed` or `customer_premises`, **derived from the target kind alone**. |

| `runtime_class` | The `OpenAgents.Capacity.Catalog` class, or `nil` when none describes the kind. |

| `lifecycle` | One word from the seven-state enum of `openagents.cloud_computer.v1`. |

| `capabilities` | The operations this caller may exercise now. `["start"]` or `[]`. |

| `unavailable_reason` | The lifecycle when the target is not startable, `not_authorized` when authority is what is missing, `nil` when nothing is. |

A delegation carries `lifecycle` from a six-word vocabulary and

`capabilities` of `["cancel"]` or `[]`.

Three decisions inside it are worth stating.

**Custody is structural.** It reads the target kind and nothing else. It cannot

be reached from the route that received the request, from whether the caller

typed or spoke, or from anything about the asking. This is what makes #37's

acceptance criterion — *never infer customer-owned versus OpenAgents-managed

from text versus voice or from the route* — a property of the type rather than

a rule five surfaces must remember.

**The lifecycle vocabulary is borrowed, not invented.** The seven words are the

`state` enum of `openagents.cloud_computer.v1` verbatim. The Elixir projection

maps onto the contract that already exists upstream, so a target described here

keeps its word if a control plane ever starts producing one. The substrate's own

state travels beside it untouched, because the substrate is still the authority

and this is a projection of it.

**A Box claims no runtime class.** `Capacity.Catalog`'s `standard` class asserts

`policy_broker` egress and `managed_standard` isolation. A Box is rented from a

third party and nothing in this repository establishes its egress posture, so

calling it `standard` would publish a containment claim no test backs.

`runtime_class("box")` returns `nil` until that evidence exists. A Computer is

`connected` by construction, and `Capacity.Connected` already counts machines as

that class.

The tests derive their inputs from the substrate schemas rather than listing

them: every value of `ConversationBox.states/0`, `Run.states/0`, and

`Job.statuses/0` must map into the vocabulary, and a new state fails the suite

the day it lands instead of silently reading as `failed` on five surfaces. The

authority tests assert the negative case for every kind and lifecycle pair, so

a capability cannot leak by omission.

Both consumers now read it: `Delegations.inventory/2` for the API, and

`Delegations.projection/2` for the chat panel, including the fan-out queue —

which is the only thing in this application that reaches the contract's

`queued` state today.

---

## 5. Why the remaining surfaces are a rendering, not four integrations

**Chat and #38.** #38 wants each logical computer shown with a stable label and

one of `cold | queued | starting | active | stopping | failed | destroyed`, the

reason a computer is queued, and owner controls "only when the current

capability allows them". Those are `lifecycle`, `unavailable_reason`, and

`capabilities` on a projection the chat panel already receives. #38 is a

template and a set of tests over fields that now exist.

**Text and voice.** Both already reach the same `OpenAgents.Work` path;

`work_jobs.surface` is `text` or `voice` and nothing else about the two differs.

Because custody is derived from the target kind, the equivalence #37 demands —

that a text and a voice request produce the same target, authority, and custody

— holds by construction rather than by a test that watches for drift.

**The API.** Already served. The seam is additive on

`openagents.delegation_targets.v1`.

**Model tools.** A tool renders the same document. It is deliberately not

shipped here: the tool catalog is at a **zero base** by policy

(`docs/2026-08-23-agent-tools-zero-base.md`), seven read-only tools ship, and

none of the five computer tools is among them. Re-admission runs through that

document's six criteria and is a change to both `config/config.exs` and

`shipped_catalog_test.exs`. #37's line about adding a model tool predates that

policy. The seam is built so re-admitting one is a config line and a rendering;

the admission decision belongs to section 6 of that document, not to this issue.

**Work.** `Capacity.match/2` returns a runtime *class* and never a thing you can

address; `Delegations` returns addressable targets and, until now, no class.

A surface that wanted to choose a target had to bridge those itself. The

descriptor is that bridge's near half. The far half is section 6.

---

## 6. What this does not do

Named plainly so nothing here reads as more than it is.

- **No control-plane client.** There is no endpoint. Section 2.

- **No logical-computer or runtime-lease record**, no generation fence, no

  command journal, and so no `may_have_started`. #37's recovery criterion is

  unmet and stays unmet until those exist upstream.

- **No Box capacity evidence.** `OpenAgents.Capacity` counts connected

  computers and broker-reported managed classes. It cannot see a Box — the one

  OpenAgents-managed compute this application actually provisions. Closing that

  loop means classifying the Box's isolation and egress, which is the decision

  `runtime_class("box") == nil` is holding open.

- **No new operations.** `start` and `cancel` are what the facade serves, so

  they are what it advertises. #37's `attach`, `stop`, `checkpoint`, `restore`,

  `fork`, and `destroy` are not capabilities this seam can honestly offer, and

  a capability list that names operations no route serves is worse than none.

  A Box can in fact be stopped, but only through `Fleet.stop/2` by label, on a

  path the facade does not own.

and you can provision another. A Computer that is gone is somebody's laptop,

and waiting is the only recovery.

**"Cloud computer" is not a term here** — it is a collision, and issue #37

settled it. The `docs/2026-08-22-cloud-computer-scale-architecture-audit.md`

program calls an OpenAgents-managed sandbox a *cloud computer*, but a Computer

in this application is never provisioned, so that phrase names a Box. Read the

audit's "cloud computer" as **Box** and its "customer-connected computer" as

**Computer**, and do not introduce a third target kind for it. The upstream

contract keeps its own name: `openagents.cloud_computer.v1` is a schema in the

`OpenAgentsInc/openagents` monorepo, and its `state` enum is where this

application's target lifecycle vocabulary comes from.

**Target seam** — the five fields `OpenAgents.Delegations.Target` computes for

any delegation target, and that every surface renders rather than derives.

`docs/2026-08-25-delegation-target-seam.md` holds the reasoning.

- **Custody** — `openagents_managed` or `customer_premises`, derived from the

  target kind alone. It is never read from the route that received the request

  or from whether the caller typed or spoke. A Box is managed; a Computer is

  the customer's premises.

- **Target lifecycle** — one of `cold`, `queued`, `starting`, `active`,

  `stopping`, `failed`, `destroyed`, taken verbatim from the

  `openagents.cloud_computer.v1` state enum. It is a projection of the

  substrate state, which stays the authority and travels beside it. Four

  substrate vocabularies feed it: `conversation_boxes.state`, `box_runs.state`,

  `work_jobs.status`, and a Computer's `status` plus its live reachability read.

- **Delegation lifecycle** — one of `queued`, `starting`, `active`,

  `succeeded`, `failed`, `cancelled`. A delegation ends; a target persists, so

  the two vocabularies are deliberately different words.

- **Capability** — the operations the asking caller may exercise *now*, as an

  explicit list: `["start"]` on a target, `["cancel"]` on a delegation, or `[]`

  with an `unavailable_reason`. A surface that derives this for itself can

  widen reach past the substrate, which is what IDENTITY-009 forbids.

**Runtime class** — an `OpenAgents.Capacity.Catalog` id: `standard`, `strong`,

`batch`, or `connected`, each naming an isolation, an egress posture, and a

data location. A Computer is `connected`. **A Box has no class yet**: naming it

`standard` would assert `policy_broker` egress that nothing here establishes,

so `runtime_class` is `nil` for a Box until that evidence exists. A class is

not a target — matching returns a class, and it takes a target reference to

address anything.

**Computer, not machine** — "computer" is both the product word and the

current code word. `OpenAgents.Computer` owns live control,

`OpenAgents.ComputerAgentJobs` owns durable ACP delegations,

  The Box run and Work delegation ledgers remain authoritative. This module

  stores no delegation state and derives every identifier and projection from

  those substrate records.

  Every target and every delegation this module returns carries the seam

  `OpenAgents.Delegations.Target` computes: custody, runtime class, one

  lifecycle word across kinds, and the capabilities the asking caller may

  exercise. Surfaces render those fields rather than deriving them, so no

  surface can decide for itself that a caller may start work on a target.

  """

  import Ecto.Query

  alias OpenAgents.BoxRuns

  alias OpenAgents.ComputerAgentJobs

  alias OpenAgents.ComputerProjection

  alias OpenAgents.Delegations.Target

  alias OpenAgents.Conversations.{Conversation, Visitor}

  alias OpenAgents.Machines

  alias OpenAgents.Machines.Machine

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

  def inventory(caller, conversation_id) when is_map(caller) and is_binary(conversation_id) do

    with {:ok, owners} <- inventory_owners(caller, conversation_id) do

      boxes = Enum.flat_map(owners.boxes, &box_targets(&1, conversation_id))

      computers = Enum.flat_map(owners.computers, &computer_targets/1)

      # `inventory_owners/2` already resolved per-kind reach: a kind the caller

      # cannot reach yields no owner, so everything listed here is authorized.

      boxes = Enum.flat_map(owners.boxes, &box_targets(&1, conversation_id, true))

      computers = Enum.flat_map(owners.computers, &computer_targets(&1, true))

      {:ok,

       %{

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

  def projection(%User{} = user, conversation_id) when is_binary(conversation_id) do

    base = Fleet.projection(conversation_id)

    computers = computer_targets(user)

    computers = computer_targets(user, true)

    jobs = latest_jobs(user.id, conversation_id)

    Map.merge(base, %{

      boxes: Enum.map(base.boxes, &box_fleet_seam/1),

      queued: Enum.map(base.queued, &box_fleet_seam/1),

      computers: Enum.map(computers, &computer_fleet_view(&1, Map.get(jobs, &1["computer_id"]))),

      maximum_computers: @maximum_targets

    })

  end

  # The chat panel reads the same seam the API does. `OpenAgents.Box.Fleet`

  # keys its projection with atoms, so the seam is restated in that convention

  # rather than mixing key types inside one map.

  defp box_fleet_seam(%{state: state} = view) do

    seam = Target.seam("box", Target.box_lifecycle(state), true)

    Map.merge(view, %{

      custody: seam["custody"],

      runtime_class: seam["runtime_class"],

      lifecycle: seam["lifecycle"],

      capabilities: seam["capabilities"],

      unavailable_reason: seam["unavailable_reason"]

    })

  end

  defp conversation_owner(%{user: %User{} = user}, conversation_id) do

    case OpenAgents.Conversations.get_conversation_for_user(user, conversation_id) do

      %Conversation{} -> {:ok, user}

  defp conversation_owned?(%User{} = user, conversation_id),

    do: not is_nil(OpenAgents.Conversations.get_conversation_for_user(user, conversation_id))

  defp box_targets(%User{id: user_id}, conversation_id) do

  defp box_targets(%User{id: user_id}, conversation_id, authorized?) do

    Repo.all(

      from box in ConversationBox,

        join: conversation in Conversation,

        "box_id" => box.box_id,

        "stopped_at" => iso8601(box.stopped_at)

      }

      |> Map.merge(Target.seam("box", Target.box_lifecycle(box.state), authorized?))

    end)

  end

  defp computer_targets(%User{id: user_id}) do

  defp computer_targets(%User{id: user_id}, authorized?) do

    Machines.list_machines(user_id)

    |> Enum.take(@maximum_targets)

    |> Enum.map(fn machine ->

      machine

      |> ComputerProjection.project()

      projection = ComputerProjection.project(machine)

      lifecycle = Target.computer_lifecycle(machine, projection["online"] == true)

      projection

      |> Map.merge(%{

        "id" => "computer:" <> machine.id,

        "kind" => "computer",

        "computer_id" => machine.id

      })

      |> Map.merge(Target.seam("computer", lifecycle, authorized?))

    end)

  end

      "failure_reason" => bounded(run.failure_reason, 500),

      "finished_at" => iso8601(run.finished_at)

    }

    |> Map.merge(Target.delegation_seam(Target.run_lifecycle(run.state)))

  end

  defp delegation_projection("computer", %Job{} = job) do

      "failure_reason" => bounded(job.error_code, 500),

      "finished_at" => iso8601(job.completed_at)

    }

    |> Map.merge(Target.delegation_seam(Target.job_lifecycle(job.status)))

  end

  defp computer_fleet_view(target, nil), do: Map.put(target, "delegation", nil)

defmodule OpenAgents.Delegations.Target do

  @moduledoc """

  One vocabulary for addressing a delegation target, reading its lifecycle, and

  advertising what the asking caller may do to it right now.

  Five surfaces want to hand work to a computer: the Work path, chat, text,

  voice, and the authenticated API. They differ in who is asking and how the

  answer is drawn. They share three questions, and this module is the only

  place that answers them.

  1. **How is it addressed?** By the kind-prefixed reference `OpenAgents.Delegations`

     already parses — `box:{uuid}` or `computer:{uuid}`. Nothing here mints a

     second identifier.

  2. **What is it doing?** `lifecycle/0` is one word drawn from the

     `openagents.cloud_computer.v1` state enum, computed from whichever

     substrate owns the target. The substrate's own state travels beside it

     untouched, because the substrate is still the authority and the unified

     word is a projection of it.

  3. **What may this caller do to it?** `capabilities` is an explicit list,

     computed once from the lifecycle and the authority the caller already

     proved. A surface renders that list. It never re-derives it.

  The third question is the one that earns the module. Reach is scoped per

  target kind (IDENTITY-009), so a surface that decides for itself whether a

  caller may start work on a target is a surface that can widen reach past the

  substrate. Computing it here makes the other four surfaces render-only.

  ## Custody is structural, never inferred

  `custody/1` answers whether a target is OpenAgents-managed or the customer's

  own premises, and it is derived from the target kind alone. It cannot be

  reached from the route that received the request, from whether the caller

  typed or spoke, or from anything else about the asking. A Box is provisioned

  and reclaimed by this application; a Computer is somebody's laptop. That is a

  property of the thing, not of the question.

  ## What is deliberately absent

  There is no runtime class for a Box. `OpenAgents.Capacity.Catalog` admits

  `standard`, `strong`, `batch`, and `connected`, and each names an isolation,

  an egress posture, and a data location. A paired computer is `connected` by

  construction and the capacity evidence already counts it as one. A Box is

  rented from a third party and nothing in this repository establishes its

  egress posture, so calling it `standard` would publish a containment claim

  no test backs. `runtime_class/1` returns `nil` for a Box until that evidence

  exists. See `docs/2026-08-25-delegation-target-seam.md`.

  """

  alias OpenAgents.Machines.Machine

  @lifecycles ~w(cold queued starting active stopping failed destroyed)

  @delegation_lifecycles ~w(queued starting active succeeded failed cancelled)

  @custodies ~w(openagents_managed customer_premises)

  @kinds ~w(box computer)

  @doc """

  The target lifecycle vocabulary.

  These are the seven states of `openagents.cloud_computer.v1` verbatim. The

  Elixir side maps onto the contract rather than inventing a parallel set, so

  a target described here keeps its word when a control plane starts producing

  one.

  """

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

  def lifecycles, do: @lifecycles

  @doc "The delegation lifecycle vocabulary. A delegation ends; a target persists."

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

  def delegation_lifecycles, do: @delegation_lifecycles

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

  def custodies, do: @custodies

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

  def kinds, do: @kinds

  @doc """

  Who holds the target, from the target kind alone.

  This never reads the caller, the surface, or the route.

  """

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

  def custody("box"), do: "openagents_managed"

  def custody("computer"), do: "customer_premises"

  @doc """

  The `OpenAgents.Capacity.Catalog` class this kind of target belongs to, or

  `nil` when no admitted class describes it.

  """

  @spec runtime_class(String.t()) :: String.t() | nil

  def runtime_class("computer"), do: "connected"

  def runtime_class("box"), do: nil

  @doc """

  The unified lifecycle of a Box, from its last observed substrate state.

  A Box that is provisioned but not yet bootstrapped reads as `starting`

  rather than `active`. Refusing to advertise work on a half-ready Box costs a

  caller one poll; advertising it costs a failed command.

  Two producers feed this. A `conversation_boxes` row carries one of

  `OpenAgents.Box.ConversationBox.states/0`. A fan-out item that admission has

  not yet let through carries the synthetic `queued` that

  `OpenAgents.Box.Fleet` gives it — a logical Box that has cost nothing and

  called nothing. That item is the only thing in this application that reaches

  the contract's `queued` state today.

  """

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

  def box_lifecycle(state) when is_binary(state) do

    case state do

      "queued" -> "queued"

      "init" -> "starting"

      "provisioning" -> "starting"

      "cloning" -> "starting"

      "provisioned" -> "starting"

      "ready" -> "active"

      "idle" -> "active"

      "running" -> "active"

      "archiving" -> "stopping"

      "archived" -> "destroyed"

      "error" -> "failed"

      _unknown -> "failed"

    end

  end

  @doc """

  The unified lifecycle of a Computer.

  `online?` is a live reachability read, so it is passed in rather than taken.

  A revoked Computer is `destroyed` — the credential is gone and no pairing

  brings the same record back. An unreachable one is `cold`: the laptop is

  shut, and nothing this application can do opens it.

  """

  @spec computer_lifecycle(Machine.t(), boolean()) :: String.t()

  def computer_lifecycle(%Machine{} = machine, online?) when is_boolean(online?) do

    cond do

      machine.status == "revoked" or not is_nil(machine.revoked_at) -> "destroyed"

      machine.status == "active" and online? -> "active"

      true -> "cold"

    end

  end

  @doc "The unified lifecycle of one Box run."

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

  def run_lifecycle(state) when is_binary(state) do

    case state do

      "admitted" -> "queued"

      "dispatched" -> "starting"

      "running" -> "active"

      "completed" -> "succeeded"

      "cancelled" -> "cancelled"

      "failed" -> "failed"

      "timed_out" -> "failed"

      "lost" -> "failed"

      _unknown -> "failed"

    end

  end

  @doc """

  The unified lifecycle of one Computer delegation, from its `work_jobs` status.

  `interrupted` and `budget_exhausted` both read as `failed`. The distinction

  survives in the job's own status, which every projection carries beside this

  word; collapsing it here keeps one cross-kind vocabulary from growing a

  branch per substrate.

  """

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

  def job_lifecycle(status) when is_binary(status) do

    case status do

      "queued" -> "queued"

      "running" -> "active"

      "completed" -> "succeeded"

      "cancelled" -> "cancelled"

      "failed" -> "failed"

      "interrupted" -> "failed"

      "budget_exhausted" -> "failed"

      _unknown -> "failed"

    end

  end

  @doc """

  The seam fields for one target: custody, runtime class, lifecycle, the

  capabilities this caller may exercise, and why it may not.

  `authorized?` is the per-kind reach the caller already proved. It is required

  rather than assumed, so a surface that forgets to check cannot get a

  capability list by omission.

  `unavailable_reason` is the lifecycle itself when the target is not startable,

  and `not_authorized` when the lifecycle allows what the caller does not. It

  deliberately introduces no third vocabulary: the kind and the lifecycle

  together already separate a shut laptop from a reclaimed Box.

  """

  @spec seam(String.t(), String.t(), boolean()) :: map()

  def seam(kind, lifecycle, authorized?)

      when kind in @kinds and lifecycle in @lifecycles and is_boolean(authorized?) do

    startable? = lifecycle == "active" and authorized?

    %{

      "custody" => custody(kind),

      "runtime_class" => runtime_class(kind),

      "lifecycle" => lifecycle,

      "capabilities" => if(startable?, do: ["start"], else: []),

      "unavailable_reason" => unavailable_reason(lifecycle, authorized?)

    }

  end

  @doc """

  The seam fields for one delegation: its unified lifecycle and whether this

  caller can still cancel it.

  A caller that resolved the delegation at all has already passed the same

  per-kind reach check the target required, so cancellation turns only on

  whether the delegation is still running.

  """

  @spec delegation_seam(String.t()) :: map()

  def delegation_seam(lifecycle) when lifecycle in @delegation_lifecycles do

    %{

      "lifecycle" => lifecycle,

      "capabilities" => if(lifecycle in ~w(queued starting active), do: ["cancel"], else: [])

    }

  end

  defp unavailable_reason("active", true), do: nil

  defp unavailable_reason("active", false), do: "not_authorized"

  defp unavailable_reason(lifecycle, _authorized?), do: lifecycle

end

defmodule OpenAgents.Delegations.TargetTest do

  @moduledoc """

  The seam is only worth having if it is total.

  These tests derive their inputs from the substrate schemas rather than

  listing them, so a new Box state, run state, or work-job status fails here

  the day it lands instead of silently reading as `failed` on five surfaces.

  """

  use ExUnit.Case, async: true

  alias OpenAgents.Box.ConversationBox

  alias OpenAgents.Box.Run

  alias OpenAgents.Delegations.Target

  alias OpenAgents.Machines.Machine

  alias OpenAgents.Work.Job

  describe "the lifecycle vocabulary" do

    test "target lifecycles are the openagents.cloud_computer.v1 state enum" do

      assert Target.lifecycles() == ~w(cold queued starting active stopping failed destroyed)

    end

    test "every declared Box state maps into the vocabulary" do

      for state <- ConversationBox.states() do

        assert Target.box_lifecycle(state) in Target.lifecycles(),

               "Box state #{state} has no lifecycle"

      end

    end

    test "a fan-out item that admission has not admitted reads as queued" do

      assert Target.box_lifecycle("queued") == "queued"

    end

    test "no declared Box state silently reads as failed" do

      # `error` is the one Box state that means failure. If another state

      # starts reading as `failed`, it fell through the catch-all.

      failed = Enum.filter(ConversationBox.states(), &(Target.box_lifecycle(&1) == "failed"))

      assert failed == ["error"]

    end

    test "a Box is only startable once it is ready, idle, or already running" do

      active = Enum.filter(ConversationBox.states(), &(Target.box_lifecycle(&1) == "active"))

      assert Enum.sort(active) == ~w(idle ready running)

    end

    test "every declared Box run state maps into the delegation vocabulary" do

      for state <- Run.states() do

        assert Target.run_lifecycle(state) in Target.delegation_lifecycles(),

               "Box run state #{state} has no lifecycle"

      end

    end

    test "every declared work job status maps into the delegation vocabulary" do

      for status <- Job.statuses() do

        assert Target.job_lifecycle(status) in Target.delegation_lifecycles(),

               "work job status #{status} has no lifecycle"

      end

    end

    test "a lost or timed-out run and an interrupted or exhausted job all read as failed" do

      assert Target.run_lifecycle("lost") == "failed"

      assert Target.run_lifecycle("timed_out") == "failed"

      assert Target.job_lifecycle("interrupted") == "failed"

      assert Target.job_lifecycle("budget_exhausted") == "failed"

    end

    test "a terminal run and a terminal job agree on the word" do

      for state <- Run.terminal_states(), state != "lost" do

        refute Target.run_lifecycle(state) in ~w(queued starting active),

               "terminal run state #{state} still reads as live"

      end

    end

  end

  describe "a Computer's lifecycle" do

    test "an active, reachable computer is active" do

      assert Target.computer_lifecycle(machine(), true) == "active"

    end

    test "an active but unreachable computer is cold, never failed" do

      assert Target.computer_lifecycle(machine(), false) == "cold"

    end

    test "a revoked computer is destroyed even while a socket is still up" do

      revoked = %Machine{machine() | status: "revoked", revoked_at: DateTime.utc_now()}

      assert Target.computer_lifecycle(revoked, true) == "destroyed"

    end

    test "a revocation stamp alone is enough to read as destroyed" do

      stamped = %Machine{machine() | revoked_at: DateTime.utc_now()}

      assert Target.computer_lifecycle(stamped, true) == "destroyed"

    end

  end

  describe "custody" do

    test "is derived from the target kind and nothing else" do

      assert Target.custody("box") == "openagents_managed"

      assert Target.custody("computer") == "customer_premises"

    end

    test "covers every kind, and every value is admitted" do

      for kind <- Target.kinds() do

        assert Target.custody(kind) in Target.custodies()

      end

    end

    test "does not change with the lifecycle or the caller's authority" do

      for lifecycle <- Target.lifecycles(), authorized? <- [true, false] do

        assert Target.seam("box", lifecycle, authorized?)["custody"] == "openagents_managed"

        assert Target.seam("computer", lifecycle, authorized?)["custody"] == "customer_premises"

      end

    end

  end

  describe "runtime class" do

    test "a paired computer is the connected class the capacity catalog admits" do

      assert Target.runtime_class("computer") == "connected"

      assert OpenAgents.Capacity.Catalog.get("connected")["isolation"] == "customer_controlled"

    end

    test "a Box claims no class until its egress posture is established" do

      assert Target.runtime_class("box") == nil

    end

  end

  describe "capabilities" do

    test "an active target the caller can reach may be started" do

      assert Target.seam("box", "active", true)["capabilities"] == ["start"]

      assert Target.seam("computer", "active", true)["capabilities"] == ["start"]

    end

    test "no other lifecycle offers any capability" do

      for kind <- Target.kinds(), lifecycle <- Target.lifecycles(), lifecycle != "active" do

        assert Target.seam(kind, lifecycle, true)["capabilities"] == [],

               "#{kind} in #{lifecycle} advertised a capability"

      end

    end

    test "an unauthorized caller is offered nothing, whatever the lifecycle" do

      for kind <- Target.kinds(), lifecycle <- Target.lifecycles() do

        seam = Target.seam(kind, lifecycle, false)

        assert seam["capabilities"] == [], "#{kind} in #{lifecycle} leaked a capability"

      end

    end

    test "authority is refused by name, so it is not confused with a cold target" do

      assert Target.seam("computer", "active", false)["unavailable_reason"] == "not_authorized"

      assert Target.seam("computer", "cold", true)["unavailable_reason"] == "cold"

    end

    test "a reachable, authorized target gives no reason, because there is none" do

      assert Target.seam("box", "active", true)["unavailable_reason"] == nil

    end

    test "the reason for refusing is always the lifecycle itself" do

      for kind <- Target.kinds(), lifecycle <- Target.lifecycles(), lifecycle != "active" do

        assert Target.seam(kind, lifecycle, true)["unavailable_reason"] == lifecycle

      end

    end

  end

  describe "delegation capabilities" do

    test "a live delegation can be cancelled" do

      for lifecycle <- ~w(queued starting active) do

        assert Target.delegation_seam(lifecycle)["capabilities"] == ["cancel"]

      end

    end

    test "a finished delegation cannot" do

      for lifecycle <- ~w(succeeded failed cancelled) do

        assert Target.delegation_seam(lifecycle)["capabilities"] == []

      end

    end

    test "every delegation lifecycle is covered" do

      for lifecycle <- Target.delegation_lifecycles() do

        assert is_list(Target.delegation_seam(lifecycle)["capabilities"])

      end

    end

    test "every terminal work job status yields an uncancellable delegation" do

      for status <- ~w(completed failed cancelled interrupted budget_exhausted) do

        seam = status |> Target.job_lifecycle() |> Target.delegation_seam()

        assert seam["capabilities"] == [], "#{status} still offered cancel"

      end

    end

  end

  describe "the seam document" do

    test "carries the same fields for every kind and lifecycle" do

      expected = ~w(capabilities custody lifecycle runtime_class unavailable_reason)

      for kind <- Target.kinds(), lifecycle <- Target.lifecycles() do

        seam = Target.seam(kind, lifecycle, true)

        assert seam |> Map.keys() |> Enum.sort() == expected

        assert seam["lifecycle"] == lifecycle

      end

    end

  end

  defp machine do

    %Machine{

      id: Ecto.UUID.generate(),

      name: "workshop",

      status: "active",

      tier: "probe",

      revoked_at: nil

    }

  end

end