> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostic Response Headers

> Use Explain request controls, report receipts and ordinary correlation metadata correctly.

AWS clients send normal IAM/SigV4-authenticated requests to Tensor9's synthetic AWS service endpoint. `ExecuteAndExplain` keeps the service's native response while headers identify the report. A completed `Explain` preview returns an origin-protocol `409 ExplainedNotPerformed` error and a receipt without performing the requested action. Retrieve explanation content through the dedicated synthetic AWS service `t9`. The application API and report API have distinct signed service identities; configure the supplied `t9` endpoint explicitly and sign report calls as `t9`. A local forwarding URI may be shared physically without changing that service identity. These headers have different jobs:

* **Request controls** select explanation behavior and must be signed with the request.
* **Response receipts** identify the effective mode or a report. A receipt is not the report itself.
* **Report API fields** identify the returned rendering and revision. The `fmt` request field selects rendering; the AWS JSON response contains the rendered report as a string in `body`.
* **Origin correlation and request-effect headers** retain their narrow, documented meanings.

Do not infer completion, authorization or retry safety from a report ID alone.

## Request controls

| Header | Direction | Accepted value | Default and absence | Meaning |
| - | - | - | - | - |
| `x-t9-explain` | Request | `true`, or one ASCII version-1 JSON object up to 4096 bytes | Without it, the adapter default applies if configured; otherwise the request executes normally without Explain | Selects the mode and report format for a new request |

A separate `T9CloudAdapter.GetExplanation` call chooses its renderer with the `fmt` JSON field. Its response identifies that rendering in `fmt`. `Accept: application/vnd.tensor9.explain+json` on a service operation does not select an explanation body. The legacy `x-t9-explain-id` request selector is refused with `400 InvalidExplainConfiguration`; call the `t9` report service instead.

### The `x-t9-explain` grammar

The shorthand form executes the request:

```text theme={null}
x-t9-explain: true
```

It is exactly equivalent to `ExecuteAndExplain` with Human presentation. It is useful when an ordinary SDK should continue consuming the native response, but it is not a preview.

Use the explicit JSON form when mode needs to be unambiguous:

```text theme={null}
x-t9-explain: {"version":1,"mode":"Explain","fmt":"Json"}
```

```text theme={null}
x-t9-explain: {"version":1,"mode":"ExecuteAndExplain","fmt":"Agent"}
```

The JSON rules are strict:

* `version` and `mode` are required.
* `version` must be `1`.
* `mode` is exactly `Explain` or `ExecuteAndExplain`.
* `fmt`, when omitted, defaults to `Human`; accepted values are `Human`, `Agent`, and `Json`.
* Unknown or duplicate JSON fields are refused.
* The header must be ASCII and no larger than 4096 bytes.
* More than one `x-t9-explain` field is refused; the adapter does not choose one.
* `false`, an empty value and an unrecognized string are refused. To request ordinary execution, omit the header.

An explicit valid header replaces the adapter default as a whole. For example, `true` overrides a default of `Explain` and selects `ExecuteAndExplain`. Invalid input is refused before ordinary service processing; it never falls back to a default or ordinary execution.

The request control must be covered by the request signature. Add it before SigV4 signing. A proxy, middleware layer or SDK interceptor that appends it after signing produces an unsigned-control refusal.

## Response receipts

| Header | Direction | Value | If absent | Meaning |
| - | - | - | - | - |
| `x-t9-explain-id` | Response | Report ID | No report receipt was supplied for this response | Names the report associated with this request |
| `x-t9-explain-mode` | Response | `Explain` or `ExecuteAndExplain` | No effective Explain mode is established by this header | States the effective mode for the report receipt |
| `x-t9-explain-expires-at` | Response | UTC RFC 3339 timestamp | No retention deadline was supplied in headers | Names the report deadline fixed at creation; it does not promise persistence |
| `x-t9-explain-unexplained` | Response | Name of the adapter default | The response was not marked as a default-caused unexplained request | The operation was served ordinarily because it could not honor the adapter default; no report was opened |

`x-t9-explain-id` and `x-t9-explain-mode` are identifiers, not outcome assertions. In particular, their presence does not mean:

* the target operation succeeded;
* an asynchronous operation converged;
* the report is sealed or complete;
* authorization was allowed;
* it is safe to retry the origin request.

`x-t9-explain-unexplained` is used only for the narrow adapter-default fallback. It does not appear beside a report ID. An explicit request for an unsupported mode is refused instead of silently running unexplained.

## Read an existing report

Configure a report client with the deployment's explicit `t9` endpoint and signing region. Use regular IAM credentials, including the session token when present, and SigV4 signing service **`t9`**. Keep the application's S3 or DynamoDB endpoint and signing service on its ordinary SDK client. Do not sign report requests as `s3`, `dynamodb` or another application service, and do not assume their endpoint is the `t9` endpoint.

Use `T9_ENDPOINT_URL` and `T9_SIGNING_REGION` supplied for that deployment. Local `tensor9 adapt svc run` readiness output names both settings; an existing provisioned fabric's `tensor9 adapt cloud connect -dir "$FABRIC_DIR" -env` output exports them. See [report client configuration](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#configure-the-t9-report-client).

The exact report-owner principal must authenticate. There is no separate diagnostic token, and the report ID alone grants no access. Report access also remains scoped to the deployment's tenant and fabric.

The report API uses AWS JSON 1.1. Every call is `POST /` on the `t9` endpoint with no query string, `Content-Type: application/x-amz-json-1.1`, and exactly one `X-Amz-Target` covered by `SignedHeaders`:

```http theme={null}
POST / HTTP/1.1
Host: t9.example.test
Content-Type: application/x-amz-json-1.1
X-Amz-Target: T9CloudAdapter.GetExplanation
Authorization: AWS4-HMAC-SHA256 ...

{"reportId":"report-123","fmt":"Human"}
```

`reportId` is required. `fmt` is optional and accepts `Human`, `Agent` or `Json`; omitting it uses the stored report format. Rendering the same report differently does not run the service operation again.

On a later monotonic read, supply `minimumVersion` to refuse a snapshot older than the recorded revision. It must be a positive signed 64-bit integer. Use the next revision only when waiting specifically for newer evidence:

```json theme={null}
{"reportId":"report-123","fmt":"Json","minimumVersion":8}
```

The call does not wait. If the stored revision is lower than `minimumVersion`, it returns `409 NotYetVisible` with the current revision when known. Report responses, including errors, use `Cache-Control: no-store`. Reading does not extend retention.

A successful `200` response is an AWS JSON object:

```json theme={null}
{
  "reportId": "report-123",
  "revision": 7,
  "fmt": "Json",
  "body": "{\"reportId\":\"report-123\",\"revision\":7}",
  "acknowledgeRevision": 7
}
```

This illustrates the response structure, with an abbreviated rendered report. **`body` is a string.** Decode the outer AWS JSON object first, then read or parse its `body` according to `fmt`. The HTTP response body is not the raw Human, Agent or JSON report. `acknowledgeRevision` is present only when the sealed report can be acknowledged.

The read statuses are intentionally distinct:

| Status | Disposition | Meaning | Next action |
| - | - | - | - |
| `200` | Report | A revision is available | Read the outer object and its rendered `body`, lifecycle and evidence |
| `409` | `NotYetVisible` | The stored revision is lower than `minimumVersion` | Keep the previous snapshot and retry `GetExplanation` after bounded backoff |
| `410` | `Consumed` | The owner acknowledged the sealed report | Use exported evidence |
| `410` | `Expired` | Retention ended and the expired record remains | Use preserved evidence; do not replay a mutation for diagnostics |
| `503` | `Unavailable` | The report service or store cannot answer now | Preserve the native result and retry only `GetExplanation` |
| `404` | `NotFound` | No visible report for this caller | Verify report ID and exact owner identity |

Errors use AWS JSON fields `__type` and `message`, with `disposition` and `revision` when known. For example:

```json theme={null}
{"__type":"NotYetVisible","message":"The requested report revision is not yet visible","disposition":"NotYetVisible","revision":7}
```

Do not use `404` to distinguish a nonexistent report from one hidden from this principal. It can also describe an unpersisted report, unsupported stored schema or record already collected after expiry. No report error establishes the original operation's outcome.

The [signed SDK retrieval flow](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#retrieve-without-replaying) uses this same `GetExplanation` API with the published endpoint and region. Decode the outer AWS JSON response's `body` string to read the selected rendering. Retrieval performs no implicit acknowledgment. A positive `minimumVersion` is optional; omit it for a first read or revision zero.

## Acknowledge a sealed report

Export needed evidence before acknowledgment. Send `T9CloudAdapter.AcknowledgeExplanation` to the same configured **`t9` service endpoint**, signed as `t9`, and supply exactly the `acknowledgeRevision` returned by `GetExplanation`:

```http theme={null}
POST / HTTP/1.1
Host: t9.example.test
Content-Type: application/x-amz-json-1.1
X-Amz-Target: T9CloudAdapter.AcknowledgeExplanation
Authorization: AWS4-HMAC-SHA256 ...

{"reportId":"report-123","revision":7}
```

| Status | Disposition | Meaning |
| - | - | - |
| `200` | `Consumed` | The owner acknowledged this sealed revision, or repeated the same acknowledgment |
| `409` | `NotSealed` | There is no final acknowledgeable revision |
| `409` | `RevisionMismatch` | The supplied revision is not the current sealed revision |
| `410` | `Expired` | Retention ended before acknowledgment |
| `503` | `Unavailable` | The acknowledgment path cannot answer now |
| `404` | `NotFound` | No report is visible to this caller |

Only the authenticated principal recorded as the report owner can read or acknowledge it. Another role or session is not an additional reader. The owner can share sanitized exports with approved people or systems. Repeating the same owner acknowledgment for the same sealed revision is idempotent; a different revision returns `RevisionMismatch`.

## Poll report progress and resource status separately

Repeat `T9CloudAdapter.GetExplanation` through `t9` for later revisions. Query resource status independently using its ordinary AWS SDK operation and exact resource identity. An executing status read retains its native response and still follows any configured Explain default unless an explicit control replaces it.

A report ID never selects an explanation through an application service operation. The legacy `x-t9-explain-id` request selector is refused with `400 InvalidExplainConfiguration`. Do not use the former private `/_t9` report paths; report retrieval belongs to the dedicated `t9` service.

## Retention and expiry

The default report lifetime is **24 hours from creation**. The operation receipt's `x-t9-explain-expires-at` and the JSON report's `reportExpiresAt` name the deadline. Reads do not renew it. Setting `T9_SIPSVR_EXPLAIN_RETENTION_SECS` to a positive duration changes the lifetime of newly created reports; existing deadlines remain fixed.

Expiry ends report capture and access without cancelling the underlying service operation or changing its execution mode. An expired report returns `410 Expired` to its owner while the expired record remains. After collection it returns `404 NotFound`. Another principal continues to receive `404` rather than learning that an expired report exists.

Logical expiry and physical storage collection are separate. The expiry deadline is enforced by default. Physical collection is opt-in with `T9_SIPSVR_EXPLAIN_REAP_ENABLED=true`; `T9_SIPSVR_EXPLAIN_REAP_SECS` configures the bounded sweep interval. Without that sweep, expired content is unavailable through the API but the stored record remains. Owner acknowledgment can consume a sealed report earlier. Export evidence needed for longer storage before expiry or acknowledgment.

## Origin correlation metadata

Origin-shaped responses retain service-specific identifiers:

| Header | Where it is used | What it tells you |
| - | - | - |
| `x-amz-request-id` | S3-shaped responses | Identifies an S3 request for correlation |
| `x-amz-id-2` | S3 responses that include the extended identifier | Additional S3 response metadata |
| `x-amzn-requestid` | AWS-shaped responses including KMS and Parameter Store | Identifies the request for correlation |

These identifiers do not establish which backend operation ran, whether a write completed, or whether a retry is safe. Preserve them alongside the report ID and relevant adapter logs.

## Failed-request effect information

`x-tensor9-request-effect` has one narrowly defined value:

```text theme={null}
x-tensor9-request-effect: refused-nothing-written
```

It states that this request was refused before writing anything. It appears only when the adapter can establish that outcome. Its absence means the effect is unknown. Unknown is not equivalent to nothing written: inspect target state and the origin operation's idempotency before retrying.

This header is not a universal error-provenance signal. There is no documented `X-Tensor9-Error-Source`, `X-Tensor9-Debug`, or similarly guessed interface.

## Preserve evidence without leaking secrets

Store the status, error code, report ID, effective mode, report revision, origin request IDs and a redacted response body. Do not record authorization headers, session tokens, signed URLs, encryption material or sensitive application payloads. A transport failure before an HTTP response has no response headers; record that absence as a transport observation, not as evidence about adapter behavior.

Continue with [Reading an Explanation](https://docs.tensor9.com/cloud-adapter-early-access/debugging/reading-explanations.md) or use the [troubleshooting runbook](https://docs.tensor9.com/cloud-adapter-early-access/debugging/troubleshooting.md) when a control, receipt or report does not behave as expected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.