# EC2 instance-command contract, version 1

This package owns the cross-process contract used to direct a command to the
node that owns a running EC2 instance. It is not an in-process service
interface or the owner of instance state.

## Route and purpose

The subject is `ec2.cmd.<instance-id>`. It is request/reply, and the daemon
that hosts that instance's QEMU process is the only subscriber. This route
exists because lifecycle operations such as start, stop, terminate, volume
attach/detach and ENI attach/detach must reach that one process; sending them
through the normal daemon queue group could select a different node.

`InstanceCommandSubject` constructs a targeted subject. The corresponding
subscription and permission pattern is `ec2.cmd.*`: the `*` deliberately
matches exactly one final instance-ID token, not an arbitrary descendant.

## Compatibility boundary

`EC2InstanceCommand`, its nested data objects, their JSON field names and the
subject shape are wire compatibility. Callers and receivers must use this
package rather than rebuild those details. `commands_test.go` preserves the
version-1 JSON shape and subject form.

This package owns shared command payloads and the drain-volume response. It
does not define every action's reply body, authorize the request, store EC2
state or implement NATS transport. Those remain responsibilities of the EC2
domain and its runtime composition.

Any incompatible subject or payload change requires an explicit versioned
contract or an approved compatibility plan; it is not a package refactor.

## Default VPC request

`EnsureDefaultVpcSubject` (`ec2.EnsureDefaultVpc`) is the request/reply route on which the gateway's account creation asks a daemon in the `spinifex-workers` queue group to build the account's default VPC.
Only the subject is owned here today.
The request (`account_id`) and reply (`vpc_id`, `error`) bodies are still declared as anonymous structs on each side; moving them into this package is a contract change that needs its own characterization first.

## Platform inventory

`PlatformInventorySubject` (`ec2.v1.PlatformInventory`) is a request/reply route on which a daemon in the `spinifex-workers` queue group reports one account's key pairs, placement groups, launch templates and their `ec2-tags` entries from the EC2 owner stores.
EC2 owns it: `domains/ec2/accountinventory` produces the reply and the daemon serves it; the only consumer today is `accountteardown`, which calls it only on an explicit operator dry run (`spx admin account delete --dry-run` or the admin API `DryRun`) and only logs a comparison with its legacy listings; no teardown calls it.

The request names the account in its body (`account_id`, a 12-digit ID) and may carry an opaque `correlation_ref` that is echoed for logs.
The daemon ignores `X-Account-ID` for this subject.
Neither field grants anything: the subject is read-only, writes to no store, and its reply is never authority to delete.

The reply has one `kinds` entry per kind (`key-pair`, `placement-group`, `launch-template`, `tag-index`) with a status and scan start and end times.
The times are zero when no owner scan ran: a consumer-synthesised `scan-incomplete` report for no responder, a timeout or a transport failure carries zero timestamps and must not be read as a scan.
`observed-clean-at-scan-time` means every store for that kind was read completely and held nothing at scan time; writers are not fenced, so it is a snapshot and never evidence of absence.
`items` carry only a resource ID, kind and disposition (`live`, `dependency-held`, or tag-index `residue`), which are the identities the per-kind Describe subjects already return.
A `dependency-held` placement group does not name its member instances, which may be stale and are not exposed by the existing subjects.
Records no existing subject exposes (public-key objects without metadata, launch-template version bodies and name-index entries without a header, and every unreadable record) appear only as aggregate `counts` per kind, disposition and class.
The reply never carries an object key, raw KV key, key or template name, tag key or value, public-key bytes, launch-template data, user data, record body or store error text; `incomplete_reasons` are fixed categories.

### Compatibility boundary

The subject name carries the contract major; `platform_inventory_test.go` preserves the version-1 JSON shape and wire vocabulary.
Producer and consumer are in the coordinated Spinifex release, so the window is N and N-1.
A daemon that predates the subject has no subscription, so the request gets no responder; the consumer treats no responder, a timeout, an error reply, an undecodable reply, a reply for another account, and a missing, repeated or unknown-status kind as `scan-incomplete`, never clean.
An incompatible change to the subject, fields or vocabulary needs a new major.