docs: populate technical specifications, schema contracts, and ADR template

docs/API_CONTRACTS/ffi_bridge_spec.json

@@ -1,5 +1,27 @@
 {
   "version": "1.0.0",
-  "bridge_type": "flutter_rust_bridge",
+  "bridge_generator": "flutter_rust_bridge",
-  "targets": ["windows", "linux", "android"]
+  "c_abi_targets": ["x86_64-pc-windows-msvc", "x86_64-unknown-linux-gnu", "aarch64-linux-android"],
+  "exports": [
+    {
+      "name": "init_core_engine",
+      "inputs": ["db_path: String", "master_key: String"],
+      "output": "Result<bool, String>"
+    },
+    {
+      "name": "get_tasks_by_namespace",
+      "inputs": ["namespace_id: String"],
+      "output": "Result<Vec<TaskDto>, String>"
+    },
+    {
+      "name": "upsert_task",
+      "inputs": ["task_json: String"],
+      "output": "Result<String, String>"
+    },
+    {
+      "name": "trigger_p2p_sync",
+      "inputs": [],
+      "output": "Result<bool, String>"
+    }
+  ]
 }

docs/API_CONTRACTS/schema.sql

@@ -1,20 +1,89 @@
--- Canonical SQLite / SQLCipher Schema Definition
+-- ==============================================================================
+-- ChronoGrid P2P - Canonical SQLite / SQLCipher Schema Definition
+-- Target Engine: SQLCipher 4.x (AES-256-CBC)
+-- ==============================================================================
+
+PRAGMA foreign_keys = ON;
+
+-- Namespaces (Workspaces / Organizational Domains)
 CREATE TABLE IF NOT EXISTS namespaces (
-    id TEXT PRIMARY KEY,
+    id TEXT PRIMARY KEY,               -- UUIDv4
-    name TEXT NOT NULL,
+    name TEXT NOT NULL,                -- e.g., 'Personal', 'Kell Engineering', 'KellCreations'
-    created_at INTEGER NOT NULL
+    color_hex TEXT DEFAULT '#000000',
+    created_at INTEGER NOT NULL,       -- Unix Epoch (ms)
+    updated_at INTEGER NOT NULL
 );
 
-CREATE TABLE IF NOT EXISTS tasks (
+-- Projects Hierarchy Tree (Sequence / Fractional Indexing)
-    id TEXT PRIMARY KEY,
+CREATE TABLE IF NOT EXISTS projects (
+    id TEXT PRIMARY KEY,               -- UUIDv4
     namespace_id TEXT NOT NULL,
+    parent_id TEXT,                    -- Nullable for root projects
     title TEXT NOT NULL,
     description_markdown TEXT,
-    priority_score REAL DEFAULT 0.0,
+    sort_order REAL NOT NULL,          -- Fractional index for ordering
-    eisenhower_quadrant INTEGER,
+    created_at INTEGER NOT NULL,
-    due_date INTEGER,
+    hlc_timestamp TEXT NOT NULL,       -- Hybrid Logical Clock for CRDT LWW
-    estimated_duration INTEGER,
+    FOREIGN KEY(namespace_id) REFERENCES namespaces(id) ON DELETE CASCADE,
-    status TEXT DEFAULT 'backlog',
+    FOREIGN KEY(parent_id) REFERENCES projects(id) ON DELETE CASCADE
-    hlc_timestamp TEXT NOT NULL,
-    FOREIGN KEY(namespace_id) REFERENCES namespaces(id)
 );
+
+-- Tasks Entity
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,               -- UUIDv4
+    namespace_id TEXT NOT NULL,
+    project_id TEXT,
+    title TEXT NOT NULL,
+    description_markdown TEXT,
+    priority_score REAL DEFAULT 0.0,   -- Calculated Urgency-Importance Vector Score
+    eisenhower_quadrant INTEGER,       -- Quadrant 1, 2, 3, or 4
+    due_date INTEGER,                  -- Unix Epoch (ms)
+    estimated_duration INTEGER,        -- Duration in minutes
+    status TEXT DEFAULT 'backlog',     -- 'backlog', 'in_progress', 'review', 'completed'
+    is_archived INTEGER DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    completed_at INTEGER,
+    hlc_timestamp TEXT NOT NULL,
+    FOREIGN KEY(namespace_id) REFERENCES namespaces(id) ON DELETE CASCADE,
+    FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE SET NULL
+);
+
+-- Notes & Knowledge Vault
+CREATE TABLE IF NOT EXISTS notes (
+    id TEXT PRIMARY KEY,               -- UUIDv4
+    namespace_id TEXT NOT NULL,
+    project_id TEXT,
+    title TEXT NOT NULL,
+    content_markdown TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    hlc_timestamp TEXT NOT NULL,
+    FOREIGN KEY(namespace_id) REFERENCES namespaces(id) ON DELETE CASCADE,
+    FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE SET NULL
+);
+
+-- Bidirectional Task-Note Links
+CREATE TABLE IF NOT EXISTS task_note_links (
+    task_id TEXT NOT NULL,
+    note_id TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (task_id, note_id),
+    FOREIGN KEY(task_id) REFERENCES tasks(id) ON DELETE CASCADE,
+    FOREIGN KEY(note_id) REFERENCES notes(id) ON DELETE CASCADE
+);
+
+-- Ingestion Source Tracking (Email / Hotkey / Watchers)
+CREATE TABLE IF NOT EXISTS ingestion_logs (
+    id TEXT PRIMARY KEY,
+    source_type TEXT NOT NULL,         -- 'imap', 'jot_hotkey', 'widget', 'file_watcher'
+    source_identifier TEXT,            -- e.g., message_id or file_path
+    raw_payload TEXT,
+    processed_task_id TEXT,
+    ingested_at INTEGER NOT NULL,
+    FOREIGN KEY(processed_task_id) REFERENCES tasks(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_namespace ON tasks(namespace_id);
+CREATE INDEX IF NOT EXISTS idx_tasks_eisenhower ON tasks(eisenhower_quadrant);
+CREATE INDEX IF NOT EXISTS idx_tasks_due_date ON tasks(due_date);
+CREATE INDEX IF NOT EXISTS idx_projects_parent ON projects(parent_id);

docs/ARCHITECTURE/02-security-and-crypto.md

@@ -1,9 +1,23 @@
 # Security & Cryptography Specification
 
-- **Master Key Derivation**: Argon2id (Memory: 64MB, Iterations: 3, Parallelism: 4).
+## 1. Master Key Derivation & Credential Management
-- **Platform KeyStore Integration**:
+- **Key Derivation Function**: Argon2id
-  - Windows: DPAPI / Credential Manager
+  - Memory: 64 MB (65536 KiB)
-  - Linux: Freedesktop SecretService API
+  - Time Cost / Iterations: 3
-  - Android: Hardware-backed Android KeyStore / TEE
+  - Parallelism: 4 threads
-- **Database Cipher**: SQLCipher 4.x (AES-256-CBC with HMAC-SHA512).
+  - Salt: Cryptographically secure random 16 bytes generated per initialization.
-- **Transport Security**: Noise XK protocol handshake over QUIC/UDP.
+- **Key Ring Integration**:
+  - **Windows**: Encrypted via DPAPI (CryptProtectData) and stored in Windows Credential Manager.
+  - **Linux**: Managed via SecretService API (libsecret / Freedesktop SecretService DBus).
+  - **Android**: Generated inside Android KeyStore backed by Hardware-backed Trusted Execution Environment (TEE) / StrongBox.
+
+## 2. Local Database Encryption
+- **Engine**: SQLCipher 4.x
+- **Cipher Algorithm**: AES-256-CBC
+- **Key Derivation**: PBKDF2-HMAC-SHA512 (256,000 iterations default for SQLCipher 4).
+- **Page Authentication**: HMAC-SHA512 per page.
+
+## 3. P2P Mesh Network Encryption
+- **Transport Security Protocol**: Noise Protocol Framework (Noise_XK_25519_ChaChaPoly_BLAKE2s).
+- **Authentication**: Pre-shared 256-bit **Swarm Key** combined with Ed25519 node identity keys.
+- **Peer Exchange Cipher**: Ephemeral Diffie-Hellman (X25519) key exchange + ChaCha20-Poly1305 AEAD payload ciphering.

docs/ARCHITECTURE/03-crdt-sync-protocol.md

@@ -1,5 +1,20 @@
 # CRDT Synchronization Protocol Specification
 
-- **Engine**: Automerge (Rust)
+## 1. Core Synchronization Engine
-- **Clock**: Hybrid Logical Clocks (HLC)
+- **Framework**: Automerge (Rust Crate)
-- **Resolution Strategy**: Last-Write-Wins Element-Set (LWW-Element-Set) registers for task fields; Tree-CRDT with fractional indexing for project hierarchies.
+- **Clock Specification**: Hybrid Logical Clocks (HLC) combining physical system time with explicit logical sequence counters to prevent clock-skew anomalies across cross-platform endpoints.
+
+## 2. Register Models & Conflict Resolution
+- **Task & Note Primitive Fields**:
+  - Properties (Title, Status, Priority Rating, Markdown Body) utilize Last-Write-Wins Element-Set (LWW-Element-Set) registers.
+  - Conflicts resolve deterministically based on HLC timestamps (hlc_timestamp).
+- **Project Tree & Order Hierarchy**:
+  - Sequence Ordering uses Fractional Indexing combined with Tree-CRDT rules to eliminate circular references when moving projects offline.
+
+## 3. Delta Exchange & Wire Protocol
+- **Transport Layer**: libp2p over QUIC with direct UDP transport.
+- **Delta Sync Workflow**:
+  1. Connection established via Noise XK handshake.
+  2. Peers exchange vector clocks containing the local head state hash.
+  3. Missing CRDT delta changesets are compressed, encrypted, and streamed over binary channels.
+  4. Both nodes merge changesets locally into SQLCipher within a single atomic database transaction.

docs/ARCHITECTURE/ADR/0000-adr-template.md

@@ -0,0 +1,19 @@
+# ADR-0000: Architecture Decision Record Template
+
+* **Status**: [Proposed | Accepted | Superseded]
+* **Date**: YYYY-MM-DD
+* **Deciders**: Michael Kell
+
+## Context & Problem Statement
+[Describe the technical context and what decision needs to be made.]
+
+## Options Considered
+1. [Option 1]
+2. [Option 2]
+
+## Decision Outcome
+Chosen Option: [Selected Option] because [justification].
+
+## Consequences & Trade-offs
+* **Positive**: [Benefit]
+* **Negative**: [Drawback/Risk]

docs/UI_UX/01-eisenhower-matrix.md

@@ -1,4 +1,17 @@
 # Eisenhower Priority Matrix View Specification
 
-- Dynamic four-quadrant rendering based on Priority Vector Score (S):
+## 1. Urgency-Importance Scoring Formula
-  S = (Wi * P_user) + (Wu * f(Due_Date - t_current)) + (Wa * Age)
+Tasks auto-calculate an Urgency-Importance Vector Score ($) executed locally inside Rust:
+
+S = (W_i * P_user) + (W_u * f(Due_Date - t_current)) + (W_a * Age)
+
+Where:
+- P_user: User-assigned priority coefficient (0.0 to 1.0).
+- (Δt): Proximity decay function yielding exponential values as due dates approach.
+- W_i, W_u, W_a: Configurable weighting coefficients for importance, urgency, and age accumulation.
+
+## 2. Quadrant Assignment Mapping
+- **Quadrant I (Do First - Urgent & Important)**: Score >= Threshold_High AND Due_Date <= 48 Hours.
+- **Quadrant II (Schedule - Not Urgent & Important)**: Score >= Threshold_High AND (Due_Date > 48 Hours OR Due_Date IS NULL).
+- **Quadrant III (Delegate/Automate - Urgent & Not Important)**: Score < Threshold_High AND Due_Date <= 48 Hours.
+- **Quadrant IV (Eliminate - Not Urgent & Not Important)**: Score < Threshold_High AND (Due_Date > 48 Hours OR Due_Date IS NULL).

docs/UI_UX/02-calendar-timeblocking.md

@@ -1,4 +1,9 @@
 # Calendar & Time-Blocking Grid Specification
 
-- Bidirectional time-blocking view.
+## 1. Display Interface
-- Local CalDAV endpoint listening on `127.0.0.1`.
+- Multi-day, Weekly, and Monthly time-blocking grids rendered via Flutter custom painter.
+- Drag-and-drop task placement: Dragging an unscheduled task onto the grid automatically updates its due_date timestamp and reserves a dedicated block based on its stimated_duration.
+
+## 2. Local CalDAV Bridge Protocol
+- **Local Endpoint**: Embedded HTTPS/CalDAV service running locally on 127.0.0.1:4242.
+- **Interoperability**: Allows native OS calendar tools (Outlook, Thunderbird, Android DAVx⁵) to read scheduled task blocks directly as standard calendar events without sending data to external cloud servers.

docs/UI_UX/03-kanban-gantt-views.md

@@ -1,4 +1,11 @@
-# Kanban & Gantt Multi-Project View Specification
+# Kanban & Gantt Multi-Project View Specification
-
+
-- Multi-level namespace and hierarchy rendering.
+## 1. Multi-Level Kanban Board
-- Real-time status column updates mapping to task CRDT state.
+- Columns represent task status (acklog, in_progress, 
eview, completed).
+- Horizontal swimlanes group tasks by 
+amespace_id or project_id.
+- Dragging a card between columns updates its status field, triggering a CRDT state emission across active peers.
+
+## 2. Interactive Gantt Timeline
+- Visualizes project milestones, task dependencies, and critical path progression.
+- Supports fractional sub-project rendering, allowing infinite sub-task nesting.

docs/WORKFLOWS/02-ingestion-pipeline.md

@@ -1,5 +1,18 @@
 # Ingestion & Local Automation Pipeline
 
-- **Local IMAP Engine**: TLS polling daemon executing inside `chronogrid_core`.
+## 1. Direct TLS IMAP Engine
-- **System Hotkeys / Widgets**: Native trigger integration for quick jots.
+- Embedded within crates/chronogrid_core (Rust native).
-- **AI Processing**: Embedded ONNX / Ollama inference for context routing, task scoring, and duration parsing.
+- Connects directly over TLS to user-configured mailboxes (Personal Gmail, M365 Exchange, Custom IMAP).
+- Polls for flagged emails or direct forwards to internal local parse addresses.
+- Extracts message body to Markdown, preserves message thread headers (In-Reply-To, Message-ID), and creates linked tasks.
+
+## 2. Native Quick Jots & Trigger Integrations
+- **Windows / Linux**: System-wide global hotkey listener invokes a lightweight FFI command overlay.
+- **Android**: Home-screen widget and Share-Intent listener push text, links, or audio payloads directly to the local ingestion buffer.
+
+## 3. Embedded AI Processing Architecture
+- **Inference Engine**: Embedded ONNX Runtime / local LLM socket (Ollama).
+- **Parsing Pipelines**:
+  1. **Namespace Classifier**: Determines destination space (Personal, Engineering, Creations).
+  2. **Metadata & NLP Extractor**: Identifies natural language dates (*"by 3pm tomorrow"*), converts them to ISO timestamps, and estimates task duration.
+  3. **Note-Task Splitter**: Separates long-form reference text into linked project notes while distilling actionable items into tasks.

init_repo.sh

@@ -1,166 +0,0 @@
-#!/usr/bin/env bash
-# ==============================================================================
-# ChronoGrid P2P Repository & Documentation Structure Initializer
-# Target Source Control: git.kellsupport.com
-# ==============================================================================
-
-set -e
-
-echo "Initializing ChronoGrid P2P repository structure..."
-
-# 1. Create Workspace Directory Tree
-mkdir -p .cursor/rules
-mkdir -p docs/ARCHITECTURE
-mkdir -p docs/WORKFLOWS
-mkdir -p docs/UI_UX
-mkdir -p docs/API_CONTRACTS
-mkdir -p apps/chronogrid_flutter/lib/src
-mkdir -p apps/chronogrid_daemon/src
-mkdir -p crates/chronogrid_core/src
-mkdir -p crates/chronogrid_net/src
-mkdir -p crates/chronogrid_crypto/src
-mkdir -p crates/chronogrid_ai/src
-mkdir -p scripts
-
-# 2. Create AI Rules File (.clinerules)
-cat << 'EOF' > .clinerules
-# CHRONOGRID P2P - AI CONTEXT & ARCHITECTURAL MANDATES
-
-1. DATA SOVEREIGNTY & LOCAL-FIRST MANDATE:
-   - Never generate code that transmits data to third-party cloud endpoints or SaaS providers.
-   - All network synchronization MUST utilize `crates/chronogrid_net` over libp2p / QUIC with Noise XK encryption.
-
-2. TECH STACK BOUNDARIES:
-   - Presentation: Flutter (Win32 for Windows, GTK3 for Linux, Android NDK).
-   - Core Logic & Storage: Rust (`crates/chronogrid_core`) with SQLCipher & Automerge CRDT.
-   - FFI Bridge: Use `flutter_rust_bridge` C-ABI generation ONLY.
-
-3. SINGLE SOURCE OF TRUTH:
-   - Prior to modifying data structures, consult `docs/API_CONTRACTS/schema.sql` and `docs/ARCHITECTURE/01-OSAD-system-architecture.md`.
-   - Update documentation in `/docs` concurrently with code changes.
-EOF
-
-# Copy .clinerules to .cursor/rules for Cursor IDE compatibility
-cp .clinerules .cursor/rules/00-system-mandates.md
-
-# 3. Create Root Architectural Decision Log
-cat << 'EOF' > DECISION_LOG.md
-# Architectural Decision Log (ADL)
-
-## [2026-08-09] - ADL-001: Distributed Local-First System Baseline
-- **Status**: Accepted
-- **Context**: Design a multi-platform (Windows, Linux, Android, Headless) productivity engine for time, project, and note management without centralized servers.
-- **Decision**: Adopted Rust core with SQLCipher local storage, Automerge CRDT delta sync over libp2p, and Flutter presentation layer bound via C-FFI.
-EOF
-
-# 4. Initialize Architecture Documents
-cat << 'EOF' > docs/ARCHITECTURE/01-OSAD-system-architecture.md
-# Operational and System Architecture Document (OSAD)
-*Status: Active Specification*
-
-Refer to system blueprints for Flutter presentation layer, Rust Core engine (`chronogrid-core`), and P2P Mesh Network (`chronogrid-net`).
-EOF
-
-cat << 'EOF' > docs/ARCHITECTURE/02-security-and-crypto.md
-# Security & Cryptography Specification
-
-- **Master Key Derivation**: Argon2id (Memory: 64MB, Iterations: 3, Parallelism: 4).
-- **Platform KeyStore Integration**:
-  - Windows: DPAPI / Credential Manager
-  - Linux: Freedesktop SecretService API
-  - Android: Hardware-backed Android KeyStore / TEE
-- **Database Cipher**: SQLCipher 4.x (AES-256-CBC with HMAC-SHA512).
-- **Transport Security**: Noise XK protocol handshake over QUIC/UDP.
-EOF
-
-cat << 'EOF' > docs/ARCHITECTURE/03-crdt-sync-protocol.md
-# CRDT Synchronization Protocol Specification
-
-- **Engine**: Automerge (Rust)
-- **Clock**: Hybrid Logical Clocks (HLC)
-- **Resolution Strategy**: Last-Write-Wins Element-Set (LWW-Element-Set) registers for task fields; Tree-CRDT with fractional indexing for project hierarchies.
-EOF
-
-# 5. Initialize Workflow Documents
-cat << 'EOF' > docs/WORKFLOWS/01-master-user-story.md
-# Master User Story: Distributed, Local-First Productivity Engine
-
-Refer to Master User Story specification for detailed acceptance criteria regarding:
-1. Multi-domain IMAP ingestion and local file watchers.
-2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes.
-3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes).
-EOF
-
-cat << 'EOF' > docs/WORKFLOWS/02-ingestion-pipeline.md
-# Ingestion & Local Automation Pipeline
-
-- **Local IMAP Engine**: TLS polling daemon executing inside `chronogrid_core`.
-- **System Hotkeys / Widgets**: Native trigger integration for quick jots.
-- **AI Processing**: Embedded ONNX / Ollama inference for context routing, task scoring, and duration parsing.
-EOF
-
-# 6. Initialize UI/UX Documents
-cat << 'EOF' > docs/UI_UX/01-eisenhower-matrix.md
-# Eisenhower Priority Matrix View Specification
-
-- Dynamic four-quadrant rendering based on Priority Vector Score (S):
-  S = (Wi * P_user) + (Wu * f(Due_Date - t_current)) + (Wa * Age)
-EOF
-
-cat << 'EOF' > docs/UI_UX/02-calendar-timeblocking.md
-# Calendar & Time-Blocking Grid Specification
-
-- Bidirectional time-blocking view.
-- Local CalDAV endpoint listening on `127.0.0.1`.
-EOF
-
-cat << 'EOF' > docs/UI_UX/03-kanban-gantt-views.md
-# Kanban & Gantt Multi-Project View Specification
-
-- Multi-level namespace and hierarchy rendering.
-- Real-time status column updates mapping to task CRDT state.
-EOF
-
-# 7. Initialize API Contracts & Schema
-cat << 'EOF' > docs/API_CONTRACTS/schema.sql
--- Canonical SQLite / SQLCipher Schema Definition
-CREATE TABLE IF NOT EXISTS namespaces (
-    id TEXT PRIMARY KEY,
-    name TEXT NOT NULL,
-    created_at INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS tasks (
-    id TEXT PRIMARY KEY,
-    namespace_id TEXT NOT NULL,
-    title TEXT NOT NULL,
-    description_markdown TEXT,
-    priority_score REAL DEFAULT 0.0,
-    eisenhower_quadrant INTEGER,
-    due_date INTEGER,
-    estimated_duration INTEGER,
-    status TEXT DEFAULT 'backlog',
-    hlc_timestamp TEXT NOT NULL,
-    FOREIGN KEY(namespace_id) REFERENCES namespaces(id)
-);
-EOF
-
-cat << 'EOF' > docs/API_CONTRACTS/ffi_bridge_spec.json
-{
-  "version": "1.0.0",
-  "bridge_type": "flutter_rust_bridge",
-  "targets": ["windows", "linux", "android"]
-}
-EOF
-
-# 8. Add .gitkeep to code folders to ensure empty directories are committed to Git
-find apps crates scripts -type d -exec touch {}/.gitkeep \;
-
-echo "Directory structure successfully created and populated!"
-echo ""
-echo "Next steps to push to git.kellsupport.com:"
-echo "  git init"
-echo "  git remote add origin https://git.kellsupport.com/kell-engineering/chronogrid.git"
-echo "  git add ."
-echo "  git commit -m 'Initial commit: Complete OSAD architecture, specs, and repository structure'"
-echo "  git push -u origin main"