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

# Composite Trust Query Response Format

> AlgoVoi authored verifier side response format for agentic payment audit chains: a closed four element trust verdict enumeration under JCS RFC 8785.

The composite trust query (CTQ) response is the top-of-stack format above the four AlgoVoi receipt formats. A verifier walks an audit chain composed of compliance, settlement, cancellation, and refund receipts, applies a structured query, and emits a single composite-trust-claim response anchoring the chain by its content-addressed root.

It is AlgoVoi-authored, specified in IETF Internet-Draft [`draft-hopley-x402-composite-trust-query`](https://datatracker.ietf.org/doc/draft-hopley-x402-composite-trust-query/) (POSTED on IETF datatracker 2026-05-25, Independent Submission, Informational), and published as a standalone reference implementation:

* Python: `algovoi-composite-trust-query` (live on PyPI, v0.1.1)

Both packages depend on [`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) / [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate) for the JCS canonicalisation primitive. Apache 2.0.

## Lifecycle position

```
admission     settlement     cancellation    refund (if owed)
compliance -> settlement  -> cancellation -> refund
receipt       attestation    receipt         receipt
                                  |
                                  v   (chain_ref)
                              CTQ response (TRUSTED | PROVISIONAL | INSUFFICIENT_EVIDENCE | UNTRUSTED)
```

Regulators, dashboards, and downstream agents consuming the CTQ response get a single byte-deterministic statement of the trust posture without re-walking the underlying chain. The chain remains independently verifiable at the response's `chain_ref` content-address.

## Why a four-state enumeration

Operationally distinct trust outcomes drive distinct operator actions. The format pins:

* **TRUSTED** -- proceed under the asserted trust posture.
* **PROVISIONAL** -- proceed cautiously; re-query after pending events finalise.
* **INSUFFICIENT\_EVIDENCE** -- gather more evidence; do not proceed under TRUSTED.
* **UNTRUSTED** -- halt the action the query was framed to authorise.

A collapse to three values (e.g. TRUSTED / NOT\_TRUSTED / PENDING) loses the operationally-distinct INSUFFICIENT\_EVIDENCE state ("we could not verify either way") from UNTRUSTED ("we verified and the answer is no"). The two trigger different operator actions: gather more evidence vs halt.

## Response shape

A CTQ response is a seven-field JSON object canonicalised under RFC 8785 (JCS). Field names are sorted lexicographically by JCS during canonicalisation.

```json theme={null}
{
  "canon_version": "jcs-rfc8785-v1",
  "chain_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  "ctq_timestamp_ms": 1716494400000,
  "jurisdiction_flags": ["UK", "EU"],
  "query_ref": "sha256:8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52",
  "trust_outcome": "TRUSTED",
  "verifier_did": "did:web:api.algovoi.co.uk"
}
```

| Field                | Type                 | Description                                                                     |
| -------------------- | -------------------- | ------------------------------------------------------------------------------- |
| `canon_version`      | string               | In-band canonicalisation pin. Fixed `jcs-rfc8785-v1`.                           |
| `chain_ref`          | string               | `sha256:{hex}` reference to the audit chain root.                               |
| `ctq_timestamp_ms`   | integer              | Epoch ms when verifier emitted the response. **Substrate Rule 2**.              |
| `jurisdiction_flags` | ordered array        | ISO-3166-1 codes. Order significant under RFC 8785.                             |
| `query_ref`          | string               | `sha256:{hex}` reference to the canonical bytes of the query that was answered. |
| `trust_outcome`      | string (closed enum) | `TRUSTED` / `PROVISIONAL` / `INSUFFICIENT_EVIDENCE` / `UNTRUSTED`.              |
| `verifier_did`       | string               | DID URI of the verifier.                                                        |

## The closed enumeration: `trust_outcome`

| Value                   | Semantic                                                                                              | Operator action                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `TRUSTED`               | Verified chain answers the query affirmatively. All anchored receipts valid, present, and consistent. | Proceed under asserted trust posture.                       |
| `PROVISIONAL`           | Chain partially complete; some receipts in `PENDING_FINALITY` or analogous non-terminal state.        | Proceed cautiously; re-query after pending events finalise. |
| `INSUFFICIENT_EVIDENCE` | Chain does not contain enough evidence to answer the query.                                           | Gather more evidence; do not proceed under TRUSTED.         |
| `UNTRUSTED`             | Chain contains evidence that negates the query.                                                       | Halt the action the query was framed to authorise.          |

Each value produces a byte-distinct `content_hash`.

## Two content-addressed references

The response carries two `sha256:{hex}` references:

* `chain_ref` points to the audit chain root. Resolving the chain itself is out-of-band (chain-by-content-address dereference, operator-side audit-log fetch, etc.). Consumers can independently walk the chain at `chain_ref` to verify the verifier's conclusion.
* `query_ref` points to the canonical bytes of the query that was answered. The query format is opaque to the response shape; callers may use JSON-LD, JSON Schema, SQL-like predicates, or any structured-question encoding. The reference is what binds the response to the specific question.

Both prefixes (`sha256:`) are part of the canonical bytes and MUST NOT be stripped.

## Verifier-of-verifier composition

A CTQ response MAY itself be embedded as a row in a higher-level audit chain. A verifier-of-verifier reading the higher chain walks sequences of CTQ responses (a chain of verifier conclusions over chains of receipts) and emits a meta-CTQ response over the composite.

This enables multi-party audit-chain composition: a regulator verifying an operator's audit chain emits a CTQ response. A higher-level supervisor verifying multiple regulators' CTQ responses emits a meta-CTQ response over those. Each level retains independent byte-deterministic verifiability.

## Conformance vectors

8 byte-level reference vectors + 7 pair invariants + 3 chain invariants at [`vectors/composite_trust_query_v1/`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/composite_trust_query_v1).

## Quick start

### TypeScript

```typescript theme={null}
import { buildCtqResponse } from "@algovoi/composite-trust-query";
import { sha256Jcs } from "@algovoi/substrate";

const r = buildCtqResponse({
  trust_outcome: "TRUSTED",
  chain_ref:
    "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  query_ref:
    "sha256:8b7df143d91c716ecfa5fc1730022f6b421b05cedee8fd52b1fc65a96030ad52",
  ctq_timestamp_ms: 1716494400000,
  verifier_did: "did:web:api.algovoi.co.uk",
  jurisdiction_flags: ["UK", "EU"],
});
console.log(sha256Jcs(r));
// fd461c6c63330e0b15ed57b40d687ccadbd1ca2359cb5cf0f53e23c5d4f5c555
```

## What this is NOT

* **Not a receipt.** Receipts record events that happened; a CTQ response records a verifier's categorical conclusion over an event chain.
* **Not the query itself.** The query is identified by `query_ref` (content-addressed); the query format is opaque to this response shape.
* **Not a chain-finality model.** The verifier applies whatever finality semantics its risk model requires; the response records the categorical conclusion, not the evaluation discipline.

## Companion IETF Internet-Draft

[`draft-hopley-x402-composite-trust-query`](https://datatracker.ietf.org/doc/draft-hopley-x402-composite-trust-query/) (Independent Submission, Informational). AlgoVoi-authored. Normatively references [`draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/). Welcomes downstream-adopter contributions per the Appendix C "Known Adopters" pattern.

## See also

* [Canonicalisation substrate](/canonicalisation-substrate) -- the JCS discipline
* [Compliance receipt](/canonicalisation-substrate) -- admission events
* [Settlement attestation](/settlement-attestation) -- per-execution settlements
* [Cancellation receipt](/cancellation-receipt) -- mandate terminations
* [Refund receipt](/refund-receipt) -- post-settlement refunds
* [Conformance vectors](/conformance-vectors) -- full vector corpus
* [Substrate authorship and provenance](/substrate-authorship-provenance) -- citable AlgoVoi authorship record