> ## 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.

# Understanding Behavior with Explain

> Choose a profile, preview, or executed explanation and use its evidence safely.

> [!NOTE]
>
> Before running a `tensor9` command, [install the CLI, set `T9_API_KEY`, and verify your customer account](https://docs.tensor9.com/cloud-adapter-early-access/getting-started/install-and-authenticate). Online commands are authenticated and their adapter detail is limited to mappings your account is entitled to use.

Explain answers three different questions about a service adapter:

1. **What does this origin-to-target profile support?** Authenticate to Tensor9 and inspect the entitled directed service profile without starting an adapter or contacting an origin or target cloud provider.
2. **What would this request do?** Run the adapter in `Explain` mode. The requested service action is not performed.
3. **What did this request attempt and observe?** Run the request in `ExecuteAndExplain` mode. The action has its ordinary effects and the adapter records an explanation.

Those questions are related, but their evidence is not interchangeable. A profile can establish documented coverage; it cannot prove what a deployed process did. A preview can expose a selected mapping and blocking constraint; it cannot prove that a provider allocation would succeed. An executed explanation can record an attempted target call and observed response; it cannot establish facts outside its stated capture scope.

> [!NOTE]
>
> Request-report retrieval requires an adapter version that publishes its dedicated `t9` endpoint and signing region. Developer CLI retrieval additionally requires `-report` in the installed command's help. Check [installed support](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#check-installed-support) before following those examples; this guide does not establish availability in older deployments. Profile inspection has its own account entitlement and version requirements.

## Choose the right form

| Question | Mechanism | Performs the service action? | Primary result | What it cannot prove |
| - | - | - | - | - |
| Which operations and behaviors are described for this mapping? | `tensor9 explain` profile form | No | Directed service-profile rendering | Installed version, deployment configuration, or a real request outcome |
| What would this request do with the supplied state? | `Explain` | No | Native `ExplainedNotPerformed` error with a receipt, then a separate report read | Provider success, target performance, or a resource created by the preview |
| What happened when this request ran? | `ExecuteAndExplain` | Yes | Native response plus a report receipt | Complete knowledge beyond the instrumented scope |
| How should an existing report be interpreted? | Signed report read | No; it reads an existing report | Human, Agent, or JSON rendering | New evidence or a rerun of the operation |

> [!WARNING]
>
> `x-t9-explain: true` selects `ExecuteAndExplain` in Human format. It is not a dry run. Use the explicit version-1 configuration when you need `Explain` mode.

## Discover and inspect a directed service profile

The public catalog provides exact origin identifiers, backend choices and documented compatibility. To inspect an account-entitled profile through the CLI, discover the exact target identifiers your account can run for that origin:

```sh theme={null}
tensor9 adapt svc list \
  -origin aws::1.0.0::s3 \
  -fmt Human
```

This authenticated result is bounded to the supplied origin and your account's entitlements. It does not enumerate other origins or export the adapter corpus.

The profile form uses that exact origin identifier and one returned target identifier. It contacts Tensor9 to authorize the request and retrieve bounded detail for an entitled direction. It does not start an adapter or contact the origin or target provider.

```sh theme={null}
tensor9 explain \
  -origin aws::1.0.0::s3 \
  -target google::1.0.0::gcs \
  -operation PutObject \
  -fmt Human
```

Use `-operation` to focus the rendering on one or more comma-separated origin operations. Use `Human` for reading, `Agent` for compact evidence with stable references, or `Json` for versioned structured output.

The command above answers questions such as:

* Is `PutObject` represented by the selected S3-to-GCS profile?
* Which behavioral differences and constraints are documented for that direction?
* Which configuration and tuning choices affect the mapping?
* Which parts of the behavior remain target-specific?

Read the result beside the [S3 service catalog entry](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/s3.md). The public catalog already supplies operation-level compatibility and service-level terms; the authenticated CLI renders the account-entitled profile for a focused query. Coverage is directed: an S3-to-GCS profile does not imply the reverse direction or another target has identical behavior.

The following command inspects a different profile and illustrates a profile facet:

```sh theme={null}
tensor9 explain \
  -origin aws::1.0.0::dynamodb::table \
  -target azure::1.0.0::cosmosdb::provisioned \
  -fmt Json
```

The `::table` facet identifies the profile being inspected. It is not necessarily the runtime service name used by a request endpoint. The [DynamoDB catalog entry](https://docs.tensor9.com/cloud-adapter-early-access/service-catalog/aws/databases-storage/dynamodb-table.md) publicly documents its operations and qualifications; the CLI narrows inspection to an entitled direction.

## Retrieve an existing explanation

When you already have an `x-t9-explain-id` receipt, use the [signed SDK retrieval flow](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#retrieve-without-replaying) with the same owner's IAM credentials. Call `T9CloudAdapter.GetExplanation` through the dedicated `t9` endpoint, signed as `t9` with its published signing region.

Select `fmt` as `Human`, `Agent` or `Json`. Decode the outer AWS JSON response's `body` string to read the selected rendering; for `Json`, parse that string as JSON. This read neither launches an adapter, executes the original operation nor acknowledges the report, and it needs no Tensor9 API key. A new assumed-role session cannot read another session's report. An optional positive `minimumVersion` selects a known revision or newer; omit it for a first read. `tensor9 explain` remains profile inspection only.

## Preview a particular request

`Explain` mode evaluates a request through the synthetic origin service without performing the requested service action. A completed preview returns an origin-protocol `409 ExplainedNotPerformed` error carrying a report ID. Call `T9CloudAdapter.GetExplanation` through the dedicated synthetic AWS `t9` endpoint to read the selected mapping, effective configuration, authorization decision, state observations and constraints. Both clients use normal IAM credentials and SigV4. The application client signs for its native AWS service; report calls sign as `t9` using the configured report endpoint and region.

A useful preview records its evidence basis:

* **Observed** facts came from an identified source or versioned snapshot.
* **Derived** facts follow from other named facts or rules.
* **Hypothetical** facts describe what would be selected if execution continued.
* **Unknown or unsupported** facts are retained as limits instead of being silently interpreted.

That distinction matters. A hypothetical S3-to-GCS mapping says which target operation the adapter selected; it does not say that bytes were uploaded. A derived configuration choice says which supported target setting would be selected; it does not prove that the provider applied it or measure the resulting performance or cost.

Use preview when you need to:

* understand why an input or dependency would be refused;
* compare the default configuration with a supported tuning choice;
* identify the target resource and field mapping before execution;
* narrow a permissions or compatibility question without replaying a mutation.

See [Using `tensor9 explain`](https://docs.tensor9.com/cloud-adapter-early-access/debugging/using-explain) for profile inspection and [Explaining SDK Requests](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) for a signed per-request control.

## Execute and explain a real request

`ExecuteAndExplain` performs the origin operation with its ordinary effects and records what the adapter attempted and observed. Treat it as a production-capable mutation, not an inspection-only switch.

For an existing SDK request, the explicit control is:

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

The header must be present before request signing. The native response can include `x-t9-explain-id`, `x-t9-explain-mode` and `x-t9-explain-expires-at`. Preserve the service result and supply the ID to `GetExplanation` on `t9`. The receipt does not prove that asynchronous work finished or every intended target effect occurred. Reports expire 24 hours from creation by default; reads do not extend that deadline.

Before using `ExecuteAndExplain`:

* choose an isolated resource or an operation whose effects you intend to perform;
* decide who owns report retrieval and acknowledgment;
* preserve the native response, report receipt, request identifiers and target state;
* plan cleanup based on observed resource state, not on the presence of a receipt;
* avoid automatic retries until the operation's idempotency and current target state are known.

## Read one decision, not just the conclusion

An explanation connects events to facts. For example, an illustrative VPC report records a decision event:

```text theme={null}
[e:event-decision] ... selected reject ... evidence f:fact-constraint
```

The referenced fact states that a no-live-instance-dependency constraint was violated and names the observed instance fact that supports it. That chain answers *why* the operation was rejected. It also preserves important limits:

* the authorization fact in that report is `Allow`; authorization was not the rejecting decision;
* the target VNet mapping is hypothetical, not an observed deletion;
* the dependency observation names a snapshot and read version;
* the report says its timeline is capture order, not a cross-service clock.

Follow evidence references rather than inferring causality from adjacent lines. [Reading an Explanation](https://docs.tensor9.com/cloud-adapter-early-access/debugging/reading-explanations.md) walks through the same fixture in Human, Agent and JSON formats.

## Turn evidence into a bounded next action

An explanation is useful when it changes the next diagnostic step:

| Evidence | Bounded next action |
| - | - |
| Unsupported operation or explicit mode | Check the operation-specific service profile; do not retry under a different mode merely to force execution. |
| Target permission refusal | Verify the configured target identity and resource policy using a non-mutating access check where available. |
| Input or dependency constraint | Inspect the named field or blocker and its observed version before changing anything. |
| Tuning choice selected | Confirm the effective target field, then measure the workload separately. |
| Report incomplete or observation unavailable | Preserve the receipt and poll the same report; do not replay the mutation. |
| Hypothetical mapping only | Treat it as a plan, not as evidence that a target resource exists. |

Explanation detail is also not the same as service support. A report can accurately describe a refusal or a known limitation. Use the service catalog for the supported behavior, then use the report to understand the selected path for one profile or request.

## Continue the investigation

* [Inspect a directed profile](https://docs.tensor9.com/cloud-adapter-early-access/debugging/using-explain.md) with `tensor9 explain`, then use the deployed-adapter workflow for request evidence.
* [Add a signed SDK control](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) to a request you already know how to make.
* [Read the wire protocol](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers.md) before implementing custom report retrieval.
* [Follow asynchronous reports](https://docs.tensor9.com/cloud-adapter-early-access/debugging/async-explanations.md) without replaying the origin operation.
* [Troubleshoot Explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/troubleshooting.md) when a control, receipt or report is missing.
* Use the product's [worked investigations](https://docs.tensor9.com/cloud-adapter-early-access/debugging/worked-examples.md) only where their evidence scope matches your service and target.


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