algovoi-composite-trust-query 0.1.0

AlgoVoi composite trust query response format reference implementation -- verifier-side categorical conclusion over audit chains of compliance, settlement, cancellation, and refund receipts under urn:x402:canonicalisation:jcs-rfc8785-v1

algovoi-composite-trust-query

AlgoVoi-authored reference implementation for the composite trust query response format specified in IETF Internet-Draft draft-hopley-x402-composite-trust-query-00 (Independent Submission, Informational).

Verifier-side categorical conclusion over an audit chain composed of compliance, settlement, cancellation, and refund receipts. Closed four-element enumeration {TRUSTED, PROVISIONAL, INSUFFICIENT_EVIDENCE, UNTRUSTED} captures the operationally-distinct four-state decision space: proceed, proceed-with-caution, hold-pending-more-data, halt.

Top-of-stack format above the four AlgoVoi receipt formats under the shared canonicalisation discipline (urn:x402:canonicalisation:jcs-rfc8785-v1).

Python and TypeScript reference implementations, byte-for-byte parity, 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)

A verifier walks the audit chain, applies a structured query, and emits a single composite-trust-claim response anchoring the chain by its content-addressed root. Regulators, dashboards, and downstream agents consume one byte-deterministic statement rather than re-walking the underlying chain. The chain remains independently verifiable at the chain_ref content-address.

Packages

Language	Package	Install
Python	algovoi-composite-trust-query	pip install algovoi-composite-trust-query
TypeScript	@algovoi/composite-trust-query	npm install @algovoi/composite-trust-query

Both depend on algovoi-substrate / @algovoi/substrate for the JCS canonicalisation primitive.

Quick start

Python

from algovoi_composite_trust_query import build_ctq_response
from algovoi_substrate import sha256_jcs

r = build_ctq_response(
    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"],
)
print(sha256_jcs(dict(r)))

TypeScript

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));

Response format

Seven-field JSON object canonicalised under RFC 8785 (JCS):

Field	Type	Description
canon_version	string	jcs-rfc8785-v1
chain_ref	string	sha256:<hex> reference to audit chain root
ctq_timestamp_ms	integer	Epoch ms (Substrate Rule 2)
jurisdiction_flags	ordered array	ISO-3166-1 codes; primary jurisdiction first
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

Closed enumeration: trust_outcome

Value	Semantic	Operator action
TRUSTED	Verified chain answers the query affirmatively. All anchored receipts valid, present, consistent. No revocation, reversal, or compliance-forced termination.	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 (missing segments, external-state references, undereferenceable pointers).	Gather more evidence; do not proceed under TRUSTED.
UNTRUSTED	Chain contains evidence that negates the query (compliance-forced termination, settled-then-reversed transaction, REJECTED refund, expired mandate).	Halt the action the query was framed to authorise.

The four-value enum is byte-load-bearing under RFC 8785: each value produces a byte-distinct content_hash. Collapsing to three values loses the operationally-distinct INSUFFICIENT_EVIDENCE state ("we couldn't verify either way") from UNTRUSTED ("we verified and the answer is no"), which matters for operator dashboards, regulator reporting, and downstream automated decision-making.

Conformance vectors

8 byte-level reference vectors + 7 pair invariants + 3 chain invariants at vectors/composite_trust_query_v1/.

Companion IETF Internet-Draft

draft-hopley-x402-composite-trust-query-00 (Independent Submission, Informational). AlgoVoi-authored. Normatively references draft-hopley-x402-canonicalisation-jcs-v1. Welcomes downstream-adopter contributions per the Appendix C "Known Adopters" pattern.

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. Receipts are emitted by participants in the event; CTQ responses are emitted by verifiers reading the chain.
• Not the query itself. The query that was asked is identified by query_ref (content-addressed). The query format is opaque to the response format; callers MAY use any structured-question encoding.
• Not a chain-finality model. The verifier applies whatever finality semantics its risk model requires; the response records the verifier's categorical conclusion, not the underlying finality model.

Related AlgoVoi packages

Package	Purpose
algovoi-substrate / @algovoi/substrate	JCS RFC 8785 canonicalisation, action_ref, compliance receipts
algovoi-settlement-attestation / @algovoi/settlement-attestation	Settlement attestation
algovoi-refund-receipt / @algovoi/refund-receipt	Refund receipt
@algovoi/cancellation-receipt	Mandate cancellation receipt
algovoi-composite-trust-query / @algovoi/composite-trust-query	This package. Top-of-stack verifier response format

Licence

Apache 2.0.