aar-validate

Validate AAR record entries and checkpoints, and audit an append-only ledger's hash-chain integrity, sequencing, and replay protection.

Install

npm install -g @ai-manifests/aar-validate

Usage

Validate record entries and checkpoints

aar-validate ./record-entry.json
aar-validate ./checkpoint.json
aar-validate ./entry-a.json ./entry-b.json

Each record entry is also re-hashed and compared against its stored entry_hash (hand-authored examples with placeholder hashes surface a warning, not an error).

Audit a ledger

Pass a directory of entries to validate them as one ordered ledger — genesis, strict seq monotonicity, prev_hash chain linkage, withdrawal_ref resolution, and cross-entry replay (duplicate wrapped event id):

aar-validate --ledger ./ledger/

Add --verify-hashes to recompute every entry_hash from content (RFC 8785 canonicalization + SHA-256) and compare against the stored value:

aar-validate --ledger ./ledger/ --verify-hashes

Checks

| Check | Mode | Type | Threat | |-------|------|------|--------| | Schema (record entry or checkpoint) | all | Error | — | | Genesis: sentinel prev_hash + null event | entry / ledger | Error | T1 | | withdrawn ⇒ withdrawal_ref present | entry / ledger | Error | T2 | | withdrawal_ref is a non-negative integer | entry / ledger | Error | T2 | | Checkpoint interval_start_seq ≤ interval_end_seq | entry | Error | — | | Checkpoint is signed | entry | Error | T1/T3 | | Checkpoint prev_checkpoint_hash null only first | entry | Warning | T3 | | Strictly increasing seq (no gaps, no dupes) | ledger | Error | T1 | | prev_hash equals previous entry_hash | ledger | Error | T2 | | withdrawal_ref resolves within the segment | ledger | Warning | — | | Duplicate wrapped event id (replay) | ledger | Error | T6 | | Recomputed entry_hash matches stored | --verify-hashes | Error | T2 |

Programmatic Use

import {
  validateEntry,
  validateRecordEntry,
  validateCheckpoint,
  validateLedger,
  computeEntryHash,
  computeCommitment,
  canonicalize,
  classify,
} from '@ai-manifests/aar-validate';

const result = validateEntry(obj);                 // dispatches on shape
const ledger = validateLedger(entries, { recomputeHashes: true });

// Build a correct chain
const entryHash = computeEntryHash(entry);          // sha256: over JCS(entry minus entry_hash)
const commitment = computeCommitment(aggregatorDid, seq, event);  // spec §3.4

How It Composes

aar-validate audits the ledger that stores AAP acknowledgment events. Validate the events themselves at the source with aap-validate. AAR is to AAP what ADJ is to ADP — the append-only record layer — so aar-validate's chain-integrity checks mirror adj-validate's deliberation-record checks.

aap-validate   validates the acknowledgment event
aar-validate   validates the ledger that stores, chains, and aggregates it

The reputation aggregation interface (ReputationSource) AAR exposes to ADP mirrors ADJ's CalibrationSource; the normative default aggregation algorithm is specified in AAR §9.

Status

v1.0 — Validates against AAR spec v1.0 (stable). Schemas for both v0 (draft baseline) and v1.0 ship in schema/.

License

Apache-2.0 — see LICENSE for the full license text and NOTICE for attribution.