BookPI Ledger & Traceability

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/bookpi.server.ts
• src/lib/ledger/verify.ts
• src/components/Ledger/IsabellaLedgerConsole.tsx
• src/lib/quantum/bookpi-quantum.ts
• server.ts
• tests/persistence.test.ts

BookPI provides an immutable cryptographic ledger and traceability system for the Isabella Villaseñor AI project. It records system events, economic transactions, and quantum execution data using hash-chained blocks and post-quantum cryptography (PQC) signatures. The system ensures data integrity through SHA-256 hashing and proof-of-work mining to prevent unauthorized tampering with the audit trail.

Sources: src/lib/bookpi.server.ts:1-10, server.ts:327-340

Core Architecture and Block Structure

The BookPI engine organizes data into an append-only chain of blocks. Each block contains specific metadata, including an event type, actor identification, and a link to the previous block via a hash. The system utilizes a difficulty-based mining process to generate valid block hashes.

Visual representation of the internal data structure of a single BookPI ledger block.
Sources: src/lib/bookpi.server.ts:28-44

Data Model: BookPIBlock

The ledger stores events in the BookPIBlock structure. Key fields include:

Field	Type	Description
index	number	The sequential position of the block in the ledger.
timestamp	string	ISO string of when the block was appended.
eventType	BookPIEventType	Classification of the event (e.g., economic_transaction, ai_decision).
module	string	The system module that generated the event.
prevHash	string	The SHA-256 hash of the preceding block.
hash	string	The validated hash of the current block.
cid	string	IPFS-style Content Identifier simulation.
pqcSignature	object	Contains mlDsaSignature and slhDsaSignature for post-quantum security.

Sources: src/lib/bookpi.server.ts:28-44

Cryptographic Integrity and Mining

BookPI ensures immutability by requiring a Proof-of-Work (PoW) hash for every block. The mine function iteratively changes a nonce until the resulting SHA-256 hash starts with a specific number of zeros, defined by the DIFFICULTY constant.

The block mining process ensures computational effort is required to add or modify ledger data.
Sources: src/lib/bookpi.server.ts:46-59

Verification Logic

The verifyLedger function iterates through the entire chain to confirm:

1. The prevHash of block N matches the hash of block N-1.
2. Recomputing the hash of block N using its data and nonce matches the stored hash.

Sources: src/lib/bookpi.server.ts:94-105, src/lib/ledger/verify.ts:1-20

Quantum Ledger Extensions

For quantum execution tasks, the system utilizes commitQuantumBlock to record specialized audit blocks. These blocks track quantum-specific metadata such as circuit hashes and Trusted Execution Environment (TEE) attestation status.

Async Batch Writer

To prevent blocking the main event loop during high-volume operations, BookPI-Quantum employs an async write queue that batches blocks before committing them to SQLite and mirroring them to PostgreSQL.

System Interaction and Events

The ledger tracks a wide range of system behaviors through standardized event types. These types allow operators to filter and audit specific subsystems like economic transactions or security alerts.

Supported Event Types

• Infrastructure: kernel_boot, system_critical, phoenix_failover.
• Governance: dao_proposal, dao_vote, policy_violation.
• AI & Logic: ai_decision, module_evaluated, anubis_verdict.
• Economy: economic_transaction, order_created, order_paid.

Sources: src/lib/bookpi.server.ts:16-26

API Implementation

The system exposes the ledger through the following endpoints in server.ts:

• GET /api/ledger: Returns a snapshot of the ledger or proxies to a durable origin.
• GET /api/v1/quantum/bookpi: Returns quantum audit chain metrics and integrity status.
• GET /api/v1/isabella/audit: Provides a cryptographic audit trail with SHA-256 verification of logs.

Sources: server.ts:327-340, server.ts:494-510, server.ts:896-904

Traceability UI: Isabella Ledger Console

The project includes a React-based IsabellaLedgerConsole for inspecting the ledger in real-time. It features virtualized list rendering for large datasets and a detailed block inspector.

Key UI Features

• Integrity Validation: Triggers a local structural verification of the chain.
• Hash Inspection: Displays Previous, Current, and Payload hashes for every block.
• Badge System: Color-codes operations like SYSTEM_BOOT or REVENUE_SPLIT_SETTLE for easier auditing.
• Data Provenance: Explicitly labels data as LIVE, DEMO, or CACHED to maintain transparency.

Sources: src/components/Ledger/IsabellaLedgerConsole.tsx:16-40, src/components/Ledger/IsabellaLedgerConsole.tsx:185-200

Summary of Operations

BookPI serves as the source of truth for all critical Isabella operations. By combining hash-linked blocks, post-quantum signatures, and multi-database persistence (SQLite/PostgreSQL), it provides a high-assurance audit trail necessary for governed AI and quantum execution.

Sources: src/lib/bookpi.server.ts:107-112, tests/persistence.test.ts:110-140