Skip to main content
For ExecuteAndExplain, Cloud Adapter keeps the origin SDK’s normal response shape while headers identify the report. Explicit Explain instead returns an explanation document and does not perform the requested operation. 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 protocol headers select a rendering and identify a revision during an authorized read.
  • 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

A direct report GET chooses its renderer with the fmt query parameter, not with a request header. The successful response reports the renderer it used in x-t9-explain-fmt.

​
The x-t9-explain grammar

The shorthand form executes the request:
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:
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

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

Report retrieval is an authenticated, signed request:
The fmt query value is Human, Agent, or Json. Changing it renders the same report differently; it does not execute the service request again. Omit minimumVersion on the first read. On a later monotonic read, add minimumVersion=<revision> to refuse a snapshot older than the revision already recorded. Use the next revision only when waiting specifically for newer evidence:
The read does not wait. If the current stored revision is lower than minimumVersion, it returns 409 NotYetVisible with the current revision. A successful report response includes: The read statuses are intentionally distinct: Do not use 404 to distinguish a nonexistent report from one hidden from this principal. It can also describe a receipt whose report row was never persisted, an unsupported stored schema, or an expired record already removed by retention collection. None of those cases establishes the service operation’s outcome.

​
Acknowledge a sealed report

Acknowledge only the exact revision returned in x-t9-explain-acknowledge-revision:
Only the authenticated principal recorded as the report owner can read or acknowledge it through these HTTP routes. A different role or session is not an additional report reader. Before the owner acknowledges, it should export and sanitize any evidence that other people or systems need through an approved out-of-band channel. Repeating the same owner acknowledgment for the same sealed revision is idempotent and returns Consumed; a different revision returns RevisionMismatch.

​
Poll through a declared origin status operation

Some operations expose a status read that can return the origin-native status and an explanation snapshot together. That poll is different from the report GET route. The request uses:
The request must authenticate normally, and x-t9-explain-id must be covered by SignedHeaders. Accept is required to select the explanation envelope; x-t9-explain-fmt is an optional presentation choice. Do not combine x-t9-explain with x-t9-explain-id: the former asks to explain a new request; the latter selects an existing report. The envelope itself returns outer HTTP 200. The origin-native status, headers and body are inside explanationEnvelope.native; an explanation-aware client must unwrap those fields before SDK retry or error classification and separately record the enclosed report snapshot. Preserve the exact operation and resource identity when polling; selecting a resource only by a reused display name risks associating the wrong native result with a report.

​
Origin correlation metadata

Origin-shaped responses retain service-specific identifiers: 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:
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 or use the troubleshooting runbook when a control, receipt or report does not behave as expected.