Skip to Content
Test Vectors

Test Vectors

To ensure interoperability between independent implementations of the AHL Protocol, publication of a public draft is gated on a suite of test vectors. This page describes the planned corpus layout (Protocol §7.5 / Data Structures §11); the vectors themselves ship with ahl-core once published.

1. JSON Canonicalization (JCS)

AHL uses the same JCS (RFC 8785) canonicalization as ATL and APL for every hashed structure — statement payloads, envelopes, manifests, tree leaves. AHL does not duplicate a JCS vector corpus: ahl-core depends on atl-core pinned at revision 79ac9c085857, and normatively references that revision’s vector corpus at test_data/vectors/jcs/. A moving branch or an unpinned “latest” reference is not a normative dependency — only a pinned revision, path, and hash are, so all three are pinned here and in ahl-core’s test_data/README.md:

  • Revision: 79ac9c085857

  • Path: test_data/vectors/jcs/ in github.com/evidentum-io/atl-core

  • Corpus digest: sha256:8dd7289c9838e8b2bc2ed9eeabee298069d81d7bf76c3694ac2113424e81fcdf — SHA-256 over the concatenation of <relative path>\x00<file bytes> for every file under that path at that revision, sorted ascending by relative path. At this revision the directory holds one file, cases.json (2215 bytes).

  • Key ordering (UTF-16 code point order)

  • Number formatting (no trailing zeros)

  • Unicode handling (no escaping of non-control characters)

2. Statement Vectors

One valid and at least one malformed case per statement type, covering all seven types: ingestion, derivation (unbatched and batched), retraction, correction, propagation, manifest (genesis and non-genesis), key.

Malformed cases include: missing scope on a trigger, a correction whose replacement is introduced after the correction’s own entry index, a manifest missing the REQUIRED predecessor field on a non-genesis version, and a derivation consuming a record for which an effective trigger is anchored at a smaller entry index.

3. Merkle Tree Vectors

Domain-separated tree construction shared by batch outputs, input sets, and disposition trees (Data Structures §8):

  • Leaf and node hashing with the 0x00 / 0x01 domain-separation prefixes
  • Sorted-leaf ordering by canonical commitment string, and rejection of duplicate leaves
  • Membership-proof generation and verification for batch derivation trees and disposition trees
  • The compact input-set form (input_set_root / input_set_count) alongside the full input-array form

4. Closure Vectors

A published, fixed toy corpus (a small append-only log with a handful of ingestions, derivations, and one correction) with the expected affected set at a declared checkpoint, exercising:

  • Retroactive vs. non-retroactive trigger scope
  • Correction supersession (a later correction of the same original superseding an earlier one)
  • Cycle detection (a derived attribute feeding back into its own ancestry) without infinite loop
  • Post-checkpoint enlargement: a later derivation consuming an already-affected descendant, showing the closure grows past the declared checkpoint D without invalidating the original completeness claim

5. Receipts

One Evidence Receipt per claim type in the claim-type registry, plus:

  • Positive cases: record-ingested and record-derived in both plain and keyed content-binding modes; a batched record-derived with input_members; trigger-effective with enumerated competing triggers; propagation-complete with the full corpus prefix through checkpoint D and every referenced tree; governance-state proving a target index’s manifest.
  • Negative cases (MUST fail verification): a deliberately over-claiming receipt — for example, a trigger-declared receipt whose rendered verdict is edited to claim “effective” without the required enumeration, and a propagation-complete receipt missing one leaf from corpus_prefix.

6. Witness Evidence

  • A valid witness cosignature over a checkpoint, verified against the manifest-declared witness key
  • Signed refusal evidence: a witness that detects an inconsistency between two checkpoints and refuses to cosign, publishing both conflicting checkpoints
  • A staleness case: a witness whose latest cosigned checkpoint exceeds the declared cadence plus grace period

Vector Format

Each vector is expected to be a self-contained JSON file, following the same shape convention as the sibling ATL and APL corpora: a name, an optional description and source, the input material under test, and an expected matcher (never a full equality check) against the verifier’s structured output. The harness and exact schema will be published alongside the vectors themselves, as publication gate 2 for the AHL public draft.

Last updated on
ExamplesFAQ