The deployer

The exchanges for putting an agent package on a host. Five: deploy this, what is deployed, how did it go, update it, and remove it.

This is the primary interface of the deployment manager role. Implementing it alone does not grant the role, because the role also carries its refusals, its handling of secrets, its conformance test, and the record its holders sign.

1. Why this exists

Anything that installs agents has to be askable in a known way, or every owner writes a custom client for every installer. This interface publishes the asking side of that job, so a caller who has never met a particular deployer can still request a deploy, read the inventory, and get an agent removed.

2. The exchanges

1. Deploy this. The instruction that starts an install. A package, a target host and harness, and the deploy-time decisions: which identity to use, who may call the agent at first, and whether a person attends it. The request names any secrets the deployment needs and never contains their values.
2. What is deployed? The inventory: each agent stood up, its package and version, its target, its identity, and the state it was last known to be in.
3. How did it go? The report for one deploy: what was done, what was checked, and what kind of check it was.
4. Update it. The same package at a newer version, through the same steps and checks.
5. Remove it. Processes stopped, configuration removed, the identity retired, and a statement of anything that could not be removed.

3. The contract

1. Every exchange is answered or refused with a reason. Silence is not an answer.
2. A deploy request names secrets and never carries them. An implementer refuses a request that contains a secret value, before the value is used.
3. Reports state what kind of check was run. An answer to "how did it go" says whether the check was a smoke check or a conformance check, and never says only "verified".
4. No document. The signed deployment record belongs to the deployment manager role, not to this interface. An implementer that does not hold the role answers these exchanges and signs nothing.

4. Conformance

Behavioural. A harness asks all five exchanges. Each is answered or refused with a reason. A deploy request carrying a secret value is refused. An answer about a completed deploy names the kind of check that was run. An inventory answer matches what a direct inspection of the target finds.

v0.1.0-draft (2026-08-31): first draft, extracted from the deployment manager role, which previously carried these exchanges inline.