# Integrity Protocol Wiki

Compiled knowledge base for the Integrity Protocol monorepo — a trust/
compliance layer for AI agents on Base L2. This page is the map; every
section below links to the real page. Governance/conventions:
`WIKI_SCHEMA.md` (page format), this `index.md` (the canonical catalog),
`WIKI_INDEX.md` (a retained legacy catalog),
`WIKI_LOG.md` (chronological history, append-only). Cross-package
decisions live in `../INTERFACE_CONTRACT.md`; how this wiki gets kept in
sync with the code is `../../AGENTS.md`.

**Start here** if you're new: [The Four Foundational Primitives](foundational-primitives.md)
(the concepts), then [Agent Primitives](agent-primitives.md)
(the 7 per-agent contracts every other page assumes you understand) and
[Persistent Memory](agent-memory.md) (the continuity primitive that
gates registration), then [AIS](ais.md) (the trust score) and
[Telemetry Ingestion Pipeline](telemetry-ingestion.md) (how
agent behavior becomes that score).

## Specification authority — 2026-09-05 (corrected; see `docs/DOCUMENT_STATUS.yaml`)

- [`docs/SPEC.md`](../SPEC.md) (v1.0.0-draft) is the accepted normative specification.
  `docs/DOCUMENT_STATUS.yaml` is the single machine-readable source of truth for this —
  check it directly rather than trusting this page to stay current.
- [Integrity Protocol v0.4](../archive/2026-08/integrity-protocol-v0.4.md) is now archived,
  not normative. A previous version of this section (dated 2026-08-29) still named it as
  the accepted baseline after the real cutover to `docs/SPEC.md` had already happened for
  at least Phase III adapter-registry work — see `PRODUCTION_GAPS.md`'s dated
  pointer-correction entry for the drift this closes.
- [Integrity Protocol v0.5 proposed](../archive/2026-08/integrity-protocol-v0.5-proposed.md)
  is likewise archived, not a live review candidate.
- [Whitepaper v3.2](../WHITEPAPER.md) is the current explanatory and non-normative whitepaper.
- The v3.2 PDF is generated publication output from the archived v3.2 source; code, tests, and deployments are separate implementation evidence layers.

## Current cross-repository audit — 2026-08-25

**Note, 2026-08-12:** the ecosystem is a three-repository model now — `integrity-mvp` (linked
below as a dated historical pointer) has been superseded by `integrity-dashboard/` inside this
repository; see [Ecosystem Dependencies](ecosystem-dependencies.md) for the current
correction. The list below is left as-recorded from the 2026-08-06 audit, not rewritten.

The cross-repository implementation plan and audit ledger are maintained in
[Repository Implementation Plans](repository-implementation-plans.md).
Repository-local status pages are:

- [`integrity-core` audit status](../archive/2026-09/audits/2026-08-06-cross-repository-status.md): historical strong-testnet-prototype assessment; production readiness was not established.
- [`integrity-mvp` audit status](https://github.com/XibalbaTechSol/integrity-mvp/blob/main/docs/audits/2026-08-06-status.md): frontend build and unit tests pass; lint and dependency-security gaps remain.
- [`xibalba-shield` audit status](https://github.com/XibalbaTechSol/xibalba-shield/blob/main/docs/audits/2026-08-06-status.md): Linux-first prototype; 2 of 3 eBPF probes verified; TCP-connect blocked.
- [`xibalba-cortex` audit status](https://github.com/XibalbaTechSol/xibalba-cortex/blob/main/docs/audits/2026-08-06-status.md): local MCP memory prototype; tests pass with Drive extras; active worktree changes require review.

These pages distinguish `DONE`, `PARTIAL`, `PLANNED`, `BLOCKED`, `UNVERIFIED`, and `REQUIRES REVIEW`. Historical wiki log entries and design records remain historical evidence.

The latest compiled session evidence keeps Phase I contract work and Hermes/BCC live dispatch in `PARTIAL`/`BLOCKED` status; local adapter validation and policy-service reachability do not establish live provider parity or host-tool execution.

## System at a glance

```mermaid
flowchart TB
    Wallet["Agent's own wallet"]
    Factory["AgentPrimitivesFactory"]

    subgraph OnChain["On-chain (EVM / Base Sepolia + anvil)"]
        SA["SovereignAgent<br/>(identity account)"]
        StA["StateAnchor<br/>(per-agent audit root)"]
        subgraph Clones["5 EIP-1167 minimal-proxy clones"]
            RR["ReputationRegistry"]
            SL["Slasher"]
            VR["VerifierRegistry"]
            CG["ComplianceGate"]
            AP["AgentProfile"]
        end
    end

    SDK["integrity-sdk / integrity-cli"]
    BCC["bcc_middleware<br/>(FastAPI + OPA)"]
    Oracle["integrity-oracle<br/>(Rust/Axum)"]
    Dashboard["integrity-dashboard<br/>(React + Python)"]
    UserAPI["integrity-userapi<br/>(FastAPI + Postgres)"]

    Wallet -->|signs direct deploys| SA
    Wallet -->|signs direct deploys| StA
    Factory -->|clones| RR
    Factory -->|clones| SL
    Factory -->|clones| VR
    Factory -->|clones| CG
    Factory -->|clones| AP

    SDK --> Wallet
    SDK -->|pre-execution gate| BCC
    SDK -->|signed telemetry| Oracle
    BCC -->|reads AIS, pushes score on-chain| Oracle
    Oracle -->|resolve + score| OnChain
    Oracle --> Dashboard
    UserAPI -->|read-only fan-out, never chain| Oracle
    Dashboard --> UserAPI
```

## Table of contents

### Concepts — identity & on-chain primitives
- [The Four Foundational Primitives](foundational-primitives.md) — the concepts the protocol rests on; **start here**
- [Agent Primitives (Self-Sovereign Identity)](agent-primitives.md) — the 7 per-agent *contracts* (a different sense of the word)
- [Persistent Memory, Genesis Root & Lineage](agent-memory.md) — **foundational primitive**: no agent registers without an anchored genesis memory root (`[PARTIALLY BUILT]`)
- [Decentralized Identifier (DID)](did.md)
- [Identity Ceiling & Verification Ladder](identity-ceiling.md) — `[PARTIALLY BUILT]`

### Concepts — trust & scoring
- [Agent Integrity Score (AIS)](ais.md) — the formula + oracle's server-side re-derivation trust model
- [Telemetry Ingestion Pipeline](telemetry-ingestion.md) — end-to-end: SDK collection → batching → signing → the oracle's 11-step ordered pipeline → AIS
- [Local Metrology](local-metrology.md) — the exact entropy/grounding/sacrifice/compliance formulas
- [Observability & PHI Safety Pipeline](observability-vtl.md) — the `Redactor`, `redact_phi`, the oracle-side PHI backstop

### Concepts — behavioral gating & cryptography
- [Behavioral Commitment Chain (BCC)](bcc.md) — the pre-execution signed-intent gate
- [Invocation Correlation Profile v1](../../spec/invocation-id-v1.md) — canonical per-attempt UUID joining intent, policy, execution, and effect without content-hash ambiguity
- [Merkle Batching & Anchoring Convention](merkle-batching.md)
- [Zero-Knowledge Proving Pipeline (ZKP)](zkp.md)

### Concepts — compliance & markets
- [ComplianceGate & Integrity Health](compliance-gate.md) — the HIPAA/healthcare vertical
- [Smart BAA](smart-baa.md) — on-chain Business Associate Agreement escrow
- [Integrity Market](integrity-market.md) — prediction markets, binary options, A2A capital allocation

### Concepts — wire spec & testing
- [AIS API — Versioned Wire Spec](ais-api-spec.md) — the generated, externally-supported `/v1/*` spec
- [Testing Strategy](testing-strategy.md) — the 3-layer test pyramid

### Concepts — planned / design-only
- [Identity Ceiling & Verification Ladder](identity-ceiling.md) — `[PARTIALLY BUILT]`
- [Cross-Chain Reputation Sync](cross-chain-spec.md) — `[PLANNED]`
- [A2A Negotiation Protocol](a2a-negotiation-spec.md) — `[PLANNED]`
- [ZK-ML Model-Inference Verification](zk-ml-spec.md) — `[PLANNED]`

### Entities — one page per real package
- [contracts](contracts.md) — Solidity/Foundry: the 7 primitives, factory, registries, XNS, Integrity Health, market layer, $ITK
- [integrity-oracle](integrity-oracle.md) — Rust/Axum: AIS scoring, server-side telemetry re-derivation, on-chain reads, markets/leaderboard
- [integrity-sdk](integrity-sdk.md) — Python agent library: identity, BCC, markets, telemetry, PHI redaction
- [integrity-cli](integrity-cli.md) — developer CLI, independent reimplementation of the SDK's core flows
- [bcc_middleware](bcc_middleware.md) — FastAPI + OPA pre-execution policy gate + reputation-sync loop
- [integrity-userapi](integrity-userapi.md) — FastAPI + Postgres user accounts/auth, strictly non-chain
- [integrity-dashboard](integrity-dashboard.md) — the React/Vite dashboard + `demo/` scenario engine
- [integrity-zkp](integrity-zkp.md) — the real Noir/Barretenberg circuit

### Architecture
- [Ecosystem Dependencies](ecosystem-dependencies.md) — cross-repository ownership and dependency direction for integrity-core (including its integrity-dashboard/ component), Xibalba Cortex, and Xibalba Shield.
- [Repository Implementation Plans](repository-implementation-plans.md) — closed/planned/blocked implementation ledger for integrity-core, integrity-dashboard/, Xibalba Shield, and Xibalba Cortex.

### Guides
- [Smart Contract Development](smart-contract-development.md) — writing/testing/deploying a new contract
- [Multi-Domain Guardrails Design](multi-domain-guardrails-design.md) — `[DESIGN, PARTIALLY BUILT]`

### Reference
- [WIKI_INDEX.md](WIKI_INDEX.md) — full catalog, one-line description per page (the canonical index)
- [WIKI_LOG.md](WIKI_LOG.md) — chronological record of every wiki change, append-only
- [WIKI_SCHEMA.md](WIKI_SCHEMA.md) — page format, frontmatter, tag taxonomy

### Open queries
- No LLM-as-judge rubric exists anywhere in this repo — the `judge_evaluations`
  ingestion schema is built but the scoring rubric is an open product
  question. See [Observability & PHI Safety](observability-vtl.md).

## Acronym glossary
- **AIS** — Agent Integrity Score → [concepts/ais.md](ais.md)
- **BAA** — Business Associate Agreement → [concepts/smart-baa.md](smart-baa.md)
- **BCC** — Behavioral Commitment Chain → [concepts/bcc.md](bcc.md)
- **DID** — Decentralized Identifier → [concepts/did.md](did.md)
- **VTL** — (old term) Verifiable Trust Layer → see [Observability & PHI Safety](observability-vtl.md) for what's actually built
- **ZKP** — Zero-Knowledge Proof(ing pipeline) → [concepts/zkp.md](zkp.md)

## No aspirational content

Every page here documents what exists in the code right now. A feature
described in a spec but not yet implemented is explicitly marked
`[PLANNED]` or `[DESIGN, PARTIALLY BUILT]` in its title/index entry — never
written as if it's real. See `WIKI_SCHEMA.md` for the full convention.