aar-ref-lib-ts

TypeScript reference implementation of the Agent Acknowledgment Record (AAR) — the append-only, hash-chained ledger that stores and aggregates AAP acknowledgment events, with Merkle checkpoints and the normative §9 default reputation algorithm.

Install

npm install @ai-manifests/aar-manifest

What's in the box

| Module | Spec | Purpose | |--------|------|---------| | entries | §3, §5, §8 | RecordEntry, Checkpoint, ReputationResult | | ledger | §3, §4 | canonicalize, computeEntryHash, computeCommitment, buildGenesis, appendEvent, verifyChain | | checkpoint | §5 | merkleRoot, buildInclusionProof, verifyInclusionProof, buildCheckpoint | | aggregation | §9 | aggregateReputation — the normative default algorithm | | store | §3/§4/§8 | InMemoryLedger — accept, withdraw, query, verify, reputation |

Usage

import { InMemoryLedger, type AapEvent } from '@ai-manifests/aar-manifest';

const ledger = new InMemoryLedger({ aggregatorDid: 'did:tutus:0xagg' });

const ev: AapEvent = {
  id: 'urn:uuid:…',
  type: 'ENDORSEMENT',
  issuedAt: '2026-05-20T14:32:00Z',
  issuer: { did: 'did:web:alice' },
  subject: { did: 'did:web:bob' },
};

ledger.accept(ev);                 // appends a chained Record Entry; throws on duplicate id (§4.1.2)
ledger.verify(true);               // re-checks the chain and recomputes every entryHash (§4)
const rep = ledger.reputation('did:web:bob', {
  settlementVerified: (e) => /* check the rail */ false,
});

The default aggregation (spec §9)

weight(a) = type_weight × issuer_trust × value_weight × witness_factor
          × time_decay × (withdrawn ? 0 : 1) × settlement_factor

• value_weight = 1 + log10(1 + usd) applies only when settlement is verified (§6.3).
• settlement_factor = 0.5 when a value is claimed but unverified (discourages fake economic claims, T2/T10), else 1.
• After summing, the issuer-diversity penalty (§9.5) scales the aggregate by diversity / 0.3 when Simpson diversity over distinct issuers/controllers is below 0.3.
• Recursive issuer trust is bounded at depth 2 with an attestation fallback (§9.4); supply your own issuerTrust resolver, or an attestation resolver to use the ATTESTATION_TRUST constants.

aggregateReputation returns a full ReputationResult (aggregate score, sample size, staleness, per-type breakdown, issuer diversity, settlement-backed fraction, withdrawal rate, confidence) — the AAR §8 ReputationSource shape ADP consumes.

Hash chaining & checkpoints

entryHash is computed over the immutable content (everything except entryHash and the mutable status fields withdrawn / withdrawalRef), so a withdrawal can flip those fields without breaking chain continuity (§3.2, §4.2, §7.4). buildCheckpoint produces a signed, prev-chained Merkle commitment over an interval; buildInclusionProof / verifyInclusionProof give standard single-entry inclusion proofs (§5.4).

How It Composes

aap-manifest   constructs and weights acknowledgment events
aar-manifest   stores, chains, federates, and aggregates them   (this library)
aar-validate   audits a ledger's chain, sequencing, and replay

Build & test

npm install
npm run build
npm test

License

Apache-2.0 — see LICENSE and NOTICE.