# W02 error, idempotency, and fencing contract

This document is part of the `agent.v1` project-owned baseline. It does not
change the SaaS/MQ contract.

## Transport and domain errors

Handlers return normal gRPC status codes and, when a response message exists,
put the stable `FailureCode` in `Failure.code` as well:

| `FailureCode` | gRPC status | Retry rule |
| --- | --- | --- |
| `INVALID_ARGUMENT` | `InvalidArgument` | Fix the request; never retry unchanged |
| `UNAUTHENTICATED` | `Unauthenticated` | Re-establish mTLS/session; do not replay business work |
| `PERMISSION_DENIED` | `PermissionDenied` | Stop; require a new authorization |
| `FAILED_PRECONDITION` | `FailedPrecondition` | Refresh state/barrier, then use the original operation ID only if allowed |
| `ABORTED` | `Aborted` | Re-read the CAS revision; do not assume the operation applied |
| `RESOURCE_EXHAUSTED` | `ResourceExhausted` | Wait for durable quota/resource release |
| `UNAVAILABLE` | `Unavailable` | Reconnect and reconcile the original operation before any retry |
| `DEADLINE_EXCEEDED` | `DeadlineExceeded` | Result is unknown unless a durable receipt exists |
| `NOT_FOUND` | `NotFound` | Do not create a substitute execution |
| `ALREADY_EXISTS` | `AlreadyExists` | Read the existing operation/result; do not create a second one |

A transport success is not an application receipt. `RESULT_CODE_ACCEPTED` means
that the receiving side durably recorded the request; `APPLIED` requires the
specified state transition and barrier evidence.

## Idempotency keys

`RequestMeta.idempotency_key` is required for mutating methods. The key is
scoped by `(agent_id, operation_id, idempotency_key)` and the durable operation
record also stores the request content digest. Reusing a key with different
content returns `ABORTED`/`RESULT_CODE_CONFLICT`; it never overwrites the first
request.

- `ActivateAgent`: `activation_operation_id` is the idempotency key. A repeated
  identical request returns the same session generation and credential metadata.
- `SetAdmissionState`: `barrier_id` plus the expected admission generation is
  persisted. A replay cannot move the generation twice.
- `Execute`: the execution binding and permit ID are the deduplication identity.
  An unknown result is reconciled with `QueryExecution`; it is never retried as
  a new originate.
- `GetExecutionPermit`: the reservation, binding, expected revision and
  idempotency key are persisted. A permit is not issued after the reservation is
  released or fenced.
- `ApplyTaskControl`: `(execution_id, expected_task_revision, action,
  idempotency_key)` is CAS-checked. `STOP` is terminal; `PAUSE` may be resumed
  only by a new authorized request.
- `ReportExecutionEvent`: `(fact_id, content_sha256)` is the durable fact key.
  An identical duplicate returns the original receipt; a digest mismatch is a
  conflict.
- `RequestUpload`/`CompleteUpload`: `upload_id` and the asset checksum are
  retained. Completion is returned only after the `recording.uploaded` fact is
  durably queued; a local PUT success alone is not `recording.uploaded`.

Read-only methods may be retried, but callers still preserve the original
request and trace identity: `GetAgentStatus`, `GetBootstrap`, and
`QueryExecution`.

## Fencing and session rules

1. The Dispatcher creates a new opaque `dispatcher_epoch` when its active
   instance changes. The Agent accepts mutations only for the active epoch.
2. The Agent identity is the mTLS certificate plus the Dispatcher-approved
   `(agent_id, cell_id, boot_id, session_generation)` binding. Self-reported
   identity or endpoint values are not authorization.
3. A newer boot or session generation fences older requests. The old request
   returns `UNAUTHENTICATED` or `ABORTED` and cannot release an unknown lease.
4. A permit contains the dispatcher epoch, session generation, reservation and
   `fencing_token`. The Agent checks all of them immediately before originate.
5. Admission close/drain is a prerequisite barrier. `SetAdmissionState` and
   `ApplyTaskControl` are applied only when their expected generation/revision
   matches durable state.
6. When the result of a mutation is unknown, the caller first queries the
   original operation/execution and records `UNKNOWN` if evidence is absent.
   No new execution ID or new permit is invented for recovery.

## Upload boundary

The Agent receives a restricted `UploadGrant` and uploads directly to the
approved OSS target. The Dispatcher never receives audio bytes. The Agent
reports only asset metadata/checksum through `CompleteUpload`; the Dispatcher
coordinates the SaaS completion/verification and publishes the resulting OSS ID
through the existing MQ event path.