title: Shift to CP (Consistency/Partition Tolerance) System

content: Genesis will shift from prioritizing Availability and Partition Tolerance (AP) to Consistency and Partition Tolerance (CP) during state handoffs. This ensures every new session is a state-consistent successor, eliminating 'session amnesia' and guaranteeing the user interacts with an agent possessing a complete, correct project history.


title: Event Sourcing as Single Source of Truth

content: The core architectural choice is to use an append-only event log in PostgreSQL as the definitive source of truth. Instead of saving final state, every change (decision, blocker, code generation) is saved as an event. The current state is a pure function of replaying these events, ensuring perfect historical fidelity and deterministic reconstruction.


title: Raft-Inspired Leader Election using Redis

content: To prevent split-brain scenarios where multiple sessions corrupt shared state, Genesis implements a strict leader election protocol using Redis distributed locks. Only the session holding the Redis lock (the 'Leader') can write to the event log, ensuring serializability of writes.


title: Vector Clocks for Causality Validation

content: To ensure state reconstruction is accurate, every event in the log will contain a Vector Clock. This allows new sessions to validate that they have received a complete history of events and detect any causal anomalies (e.g., missing events).


title: CRDTs for In-Memory State Management

content: In-memory state objects (like active agents or blockers) will be modeled as Conflict-free Replicated Data Types (CRDTs), such as OR-Sets (Observed-Remove Sets) and LWW-Registers (Last-Write-Wins). This ensures that even if events are applied out of order, the final state remains consistent.


title: Saga Pattern for Multi-Session Projects

content: Long-running tasks (e.g., 'Ship Talking Widget') will be tracked as 'Sagas' using a unique saga_id in the event log. This allows state machines to reconstruct the exact step of a project, identify failures, and trigger compensating actions (rollbacks) across sessions.


title: PostgreSQL Event Log Schema

content: Implementation of the `session_events` table in PostgreSQL with columns: event_id (BIGSERIAL), session_id (UUID), saga_id (UUID), event_type (VARCHAR), payload (JSONB), vector_clock (JSONB), and committed (BOOLEAN). Indexes on session_id and saga_id are required for fast retrieval.


title: Redis Lock Acquisition Protocol

content: Session start protocol: Generate unique session_id -> Attempt to acquire lock via `SET genesis:active_session_lock <session_id> NX EX 7200`. Success promotes to Candidate. Failure implies another session is active. The leader must heartbeat to refresh TTL.


title: State Reconstruction Workflow

content: The 5-step recovery process for a new session: (1) Acquire Redis Lock, (2) Query latest snapshot from `session_snapshots`, (3) Replay all events from log after snapshot's last_event_id, (4) Validate Vector Clock against prior session's clock, (5) Promote to Leader and accept user input.


title: Quorum-Based Write Strategy

content: To ensure durability, a Write Quorum (W=3) is defined across N=5 systems (Postgres, Redis, Qdrant, Supermemory, FalkorDB). An event is only marked `committed=TRUE` in Postgres after propagating to at least 2 secondary systems, ensuring critical state changes are durable.


title: Gossip Protocol for Reconciliation

content: A background 'Gossip/Repair Agent' runs periodically (e.g., every 60s), reads committed events from Postgres, and checks other systems (Qdrant, FalkorDB) for consistency. If systems are missing data, the agent triggers a repair/update to ensure eventual consistency.


title: Session Lifecycle: Candidate to Leader to Shutdown

content: Ordered phases of a Genesis session: Start -> Acquire Redis Lock (Candidate) -> Reconstruct State -> Promote to Leader -> Active User Interaction -> Graceful Shutdown (Append 'session_terminated', Delete Lock). If crash occurs, lock expires (TTL) allowing next session to seize leadership.

steps:
Start Session
Acquire Redis Lock (Candidate Election)
Load Snapshot & Replay Events
Validate Vector Clock
Promote to Leader
Handle User Input
Graceful Shutdown (Release Lock)


title: Elimination of Session Amnesia

content: The primary competitive advantage is solving 'session amnesia'. By ensuring perfect memory and context continuity across sessions, Genesis provides a seamless user experience that competitors relying on stateless or simple context windowing cannot match.


title: Technical Complexity as Defensible Barrier

content: Implementing a robust consensus system combining Raft-style leadership, Event Sourcing, CRDTs, and Vector Clocks is architecturally complex and difficult to replicate. This creates a high engineering barrier to entry for competitors.


title: PostgreSQL to Qdrant/Supermemory (Embeddings)

content: The PostgreSQL event log replicates data to Qdrant and Supermemory. This allows the system to perform similarity search and maintain embedding-based memory of the project's evolution for retrieval-augmented generation.


title: PostgreSQL to FalkorDB (Knowledge Graph)

content: The event log replicates structural data to FalkorDB (a graph database). This maintains a causal knowledge graph of the project, allowing the agent to reason about relationships between decisions, code, and blockers.


title: PostgreSQL to Redis (Cache & Lock)

content: PostgreSQL replicates events to Redis to serve as a fast Active State Cache and maintain the Leader Election Lock mechanism, ensuring fast read access and coordination.


title: Project Continuity Feature Specification

content: The 'Project Continuity' product is defined by these capabilities: (1) Consensus-based state management, (2) Event sourcing for auditability, (3) Deterministic state reconstruction via snapshots, (4) Vector clock validation, (5) Leader election to prevent split-brain, (6) Saga pattern for multi-session workflows, and (7) Gossip protocol for eventual consistency.