RedFlag/protocol/README.md

# Mutation manifest wire contract

This directory owns the language-independent bytes shared by RedFlag Server, Agent, and
helper. The current closure-based capability token remains the only runtime execution path;
the mutation envelope is pinned and tested but not wired to a backend yet.

## Envelope

```text
MutationEnvelope
├── MutationManifest
│   ├── protocol_version
│   ├── operation_id
│   ├── target_id
│   ├── backend
│   ├── operation
│   ├── resolved_actions[]
│   │   ├── kind
│   │   ├── identity
│   │   └── payload       exact backend-owned UTF-8 JSON bytes
│   └── evidence[]
│       ├── kind
│       └── digest        SHA-256 hex
└── MutationAuthorization
    ├── protocol_version
    ├── authorization_id
    ├── manifest_hash
    ├── authority_kind
    ├── authority_id
    ├── target_id
    ├── issued_at / not_before / expires_at
    ├── decision
    ├── key_id
    └── signature

MutationReceipt          the response half; unsigned, produced by the executor
├── protocol_version
├── operation_id / manifest_hash / authorization_id   the audit join
├── target_id
├── backend / operation
├── decision / reason
├── executed
├── verified_actions
├── exit_code
├── error
└── timestamp
```

The protocol envelope begins at format `1` in its own namespace. It is not a new numbered
generation of `CapabilityToken`; the two named contracts coexist until a backend migrates.
Unknown format values fail closed.

## Target identity

`target_id` names the body being mutated. For RedFlag today the mapping is normative and
narrow:

> **`target_id` MUST equal the locally provisioned RedFlag `agent_id`** — the identity the
> executor reads for itself from a root-owned, SEC-021-validated file, never from the
> envelope.

The manifest and the authorization each carry it, both inside signed bytes, and a verifier
requires them equal. An executor binds the envelope by comparing them with the host
identity it read independently.

The field keeps a generic name so a later protocol may define another target namespace
deliberately. Until one exists, there is no second namespace and no `body_id` — inventing
vocabulary ahead of the thing it names would weaken a binding that already works.

## Authorization discipline

`authorization_id` MUST be a canonical UUID v4 (8-4-4-4-12 lowercase hex, version nibble
`4`, variant nibble `8`/`9`/`a`/`b`) — the same discipline the standalone mint already
applies to `request_id`. It is the identifier an executor will eventually record as a
replay key, and a newline-delimited ledger matched line-by-line has no defence against an
identifier that contains a newline. The shape is checked before that day arrives.

`expires_at - not_before` MUST NOT exceed **3600 seconds**. That ceiling is derived, not
chosen: it is `DefaultTokenTTL`, the fleet minter's own window. Standalone mint is tighter
still at 600s. Both the signer and the verifier enforce it, so an over-long authorization
cannot be minted, not merely refused at the end.

## Canonical records

Every value is encoded as UTF-8 `decimal_byte_length:value`, with no separator between
fields. Each record begins with a length-prefixed domain string.

Manifest field order:

```text
redflag.mutation-manifest
protocol_version
operation_id
target_id
backend
operation
resolved_action_count
sorted(length-prefixed resolved-action records)
evidence_count
sorted(length-prefixed evidence records)
```

Resolved action field order:

```text
redflag.resolved-action
kind
identity
payload
```

Evidence field order:

```text
redflag.evidence
kind
digest
```

Authorization field order:

```text
redflag.mutation-authorization
protocol_version
authorization_id
manifest_hash
authority_kind
authority_id
target_id
issued_at
not_before
expires_at
decision
key_id
```

`manifest_hash` is lowercase hex SHA-256 over the manifest canonical bytes. The Ed25519
signature is over the authorization canonical bytes. The signature itself is not included
in those bytes; every other authorization field, including `key_id`, is.

## Collection semantics

Resolved actions and evidence are unordered multisets. Their canonical records are sorted
bytewise for hashing. Exact duplicates remain present, increment the count, and change the
hash. No implementation may convert either collection to a set.

A backend that needs ordered execution encodes the sequence inside one signed payload. The
common layer never infers package, WUA, Winget, Docker, or self-update semantics from that
payload.

Provenance is evidence. Cache paths, URLs, repository selectors, WUA identities, and other
execution inputs belong in the exact signed backend payload or must be derived
deterministically from it.

Evidence carries **digests, not prose**. A gate verdict, an operator identity, and an
override reason are the authority's own record and stay in its journal; what travels in
the manifest is a digest binding the decision to the evidence it was made over. The
SHA-256 shape check is what enforces that — reason text cannot be smuggled into a signed
manifest through an evidence value.

## Receipt

The receipt is the response half of the contract. It carries the audit join — operation
ID, manifest hash, authorization ID — so a local enforcement record and a Server history
row join on a tuple neither side had to guess. `decision` and `reason` keep the existing
`PolicyResult` taxonomy rather than inventing a second one.

**The receipt is not signed.** The executor is not a second cryptographic authority; this
is a record produced inside the trust boundary that already ran, or refused, the
operation. Its canonical bytes exist so a ledger can digest one without re-deriving field
order from JSON, not so anyone can verify it.

Receipt field order:

```text
redflag.mutation-receipt
protocol_version
operation_id
manifest_hash
authorization_id
target_id
backend
operation
decision
reason
executed              "true" | "false"
verified_actions
exit_code
error
timestamp
```

Every field is present even when empty: a refusal that happens before the envelope parses
still produces a receipt, and its emptiness is part of the record.

## Golden fixture

`testdata/mutation-golden.json` pins:

- manifest canonical bytes and hash;
- authorization canonical bytes;
- authority key ID;
- deterministic Ed25519 signature;
- action/evidence ordering behavior;
- duplicate retention;
- receipt canonical bytes and digest;
- authorization_id shape and the authorization lifetime ceiling;
- tamper refusal for provenance, execution location, target, backend, resolved action,
  authorization metadata, decision, time window, and unknown formats.

Go tests live in both capability packages. Rust tests live in
`helper/src/mutation_protocol.rs`, and the helper's own envelope-path tests live in
`helper/src/main.rs`.

## Executor status

`redflag-helper verify-envelope --envelope-file <path> [--receipt-file <path>]` verifies an
envelope through the helper's real pipeline — parse, host binding, trusted keyring,
signature, time, lifetime ceiling, backend payload shape — and then refuses with
`backend_not_migrated`, because no backend executes through this path yet.

It records **no replay state**. Execute mode records a token only after a plan is built, so
an operation that cannot run never burns its slot; nothing here can run, so nothing here
records. Replay identity stays unproven until the first backend migrates.

It also enforces no artifact custody. When a backend carries a local cached artifact as
executor input, the helper must rehash it before use. Remote repository execution keeps the
limits `RAF/security/05-supply-chain-gate.md` already states.