Data Persistence Authority

Relevant source files

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

• server.ts
• src/data/isabellaMigrations.ts
• src/lib/persistence/postgres.ts
• src/lib/persistence/sqlite.ts
• supabase/migrations/001_isabella_schema.sql

Data Persistence Authority manages the lifecycle, storage, and integrity of all system data within the Isabella Villaseñor AI ecosystem. The system implements a hierarchical persistence strategy that prioritizes high-availability PostgreSQL for production and falls back to SQLite or in-memory storage for development and local environments. This authority ensures that cognitive memories, audit logs, and quantum events remain persistent and auditable across all operational states.

Sources: README.md, server.ts:1330-1343, src/data/isabellaBlueprint.ts:17-19

Polyglot Persistence Architecture

The system utilizes a polyglot persistence matrix to handle different types of data with specialized engines. The core architecture centers on a Single Source of Truth (SSOT) via PostgreSQL, while providing local alternatives for environment flexibility.

Persistence Engines

ID	Engine	Responsibility
DB-1	PostgreSQL + TimescaleDB	Synchronous telemetry, metrics, and logs.
DB-2	Qdrant Vector Engine	Pentacapa memory and vector embeddings.
DB-3	Redis Sentinel Cluster	L0 immediate cache and event bus.
DB-4	Neo4j Graph Database	Dialectical ontology and AST graphs.
DB-5	BookPI RocksDB Ledger	Post-Quantum Cryptographic (PQC) immutable registry.

Sources: src/lib/isabella-v5.ts:182-188, README.md

Data Flow Diagram

The following diagram illustrates how the system routes data from perception to permanent storage through various governance gates.

Relational Schema and Migrations

The relational layer is defined by a canonical SQL migration (001_create_isabella_tables.sql) compatible with PostgreSQL and Supabase. The schema is organized into functional modules covering sessions, hierarchical memory, decision auditing, and tool execution.

Core Database Tables

Table Name	Purpose	Scope
isabella_sessions	Manages session lifecycle and actor states.	Session & Connection
isabella_memory_items	Stores hierarchical cognitive memory with checksums.	Hierarchical Memory
isabella_decisions	Records C.R.O.W.N. and ARGUS policy verdicts.	Governance
isabella_audit_logs	Provides immutable trace logs with universal IDs.	Traceability
isabella_tools	Catalog of authorized Zero-Trust tools.	Sandbox
quantum_events	Stores quantum execution data and hash chains.	Quantum Mesh

Sources: src/data/isabellaMigrations.ts:114-150, supabase/migrations/001_isabella_schema.sql:31-48

Schema Definition Snippet

The following snippet demonstrates the structure of the memory and decision tables used to ensure cognitive persistence.

-- Memory Items (Hierarchical: immediate | session | project | territorial | historical)
CREATE TABLE IF NOT EXISTS isabella_memory_items (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id uuid,
  memory_scope text, 
  content text,
  relevance numeric DEFAULT 0,
  checksum text,
  created_at timestamptz DEFAULT now()
);

-- Audit Logs for Cryptographic Trace Registry
CREATE TABLE IF NOT EXISTS isabella_audit_logs (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id uuid,
  actor_id uuid,
  event_type text,
  payload jsonb,
  trace_id text,
  created_at timestamptz DEFAULT now()
);

Sources: src/data/isabellaMigrations.ts:40-52, src/data/isabellaMigrations.ts:88-99

Hierarchical Memory Store

The memory store partitions data into five distinct scopes to balance retrieval speed and historical depth. The Persistence Authority manages these scopes through memory_items queries and additions.

Memory Scopes

1. Immediate: Volatile data for active processing.
2. Session: Data relevant to the current user interaction.
3. Project: Data shared across a specific collaborative goal.
4. Territorial: Sovereign data anchored to specific geographic/territorial contexts (e.g., Real del Monte).
5. Historical: Long-term archival data for longitudinal analysis.

Sources: src/data/isabellaMigrations.ts:40-45, server.ts:927-935, src/data/isabellaBlueprint.ts:10

Implementation and Bootstrapping

The system initializes persistence during the server startup sequence. It checks for a POSTGRES_URL to establish a pool via the Supabase Pooler or local PostgreSQL host. If available, the system automatically executes pending migrations to ensure the schema is current.

Startup Sequence

1. Initialize SqliteApiKeyRepository for local credential storage.
2. Bootstrap PostgresPool using environment credentials.
3. Execute runPostgresMigration() to apply canonical schema.
4. Perform pgHealthCheck() to verify connection integrity.
5. Synchronize the Stripe catalog for billing persistence.

Sources: server.ts:122-127, server.ts:1330-1343

Connection Lifecycle

Governance and Auditability

The Persistence Authority enforces "Zero Trust" data handling. Every perception, decision, and tool execution generates a trace_id and a cryptographic checksum that are persisted in the isabella_audit_logs and bookpi_blocks tables. This allows for full reconstruction of system reasoning and evidence-based auditing.

Sources: src/data/isabellaBlueprint.ts:17-19, supabase/migrations/001_isabella_schema.sql:50-65

Conclusion

The Data Persistence Authority provides a robust, multi-tiered storage foundation for Isabella Villaseñor AI. By combining relational integrity, vector search capabilities, and immutable audit ledgers, it ensures that cognitive operations are both persistent and epistemologically verifiable.