Skip to main content
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

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:
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

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. 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:
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:
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:
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: Errors use AWS JSON fields __type and message, with disposition and revision when known. For example:
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 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:
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: 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.