# Phase 5: Headless Node, Integration Testing & Release

## Status: Pending Phase 4 Completion

**Phase Goal:** Complete the `chronogrid_daemon` headless binary with all background services, perform comprehensive multi-device integration testing, finalize cross-platform build pipelines, and produce release artifacts for Windows (.msi), Linux (.AppImage/.deb), and Android (.apk).

**Prerequisites:** Phase 4 complete ✅  
**Estimated Complexity:** High  
**Blocking:** None — this is the final phase

---

## Task 5.1 — Complete chronogrid_daemon Headless Binary

- [ ] **Task 5.1**: Complete the `chronogrid_daemon` headless binary with all background services:
  - Implement full daemon startup sequence in `apps/chronogrid_daemon/src/main.rs`:
    1. Parse CLI args and load TOML config
    2. Initialize `tracing` structured logging (JSON format for production, pretty for dev)
    3. Load or generate `NodeIdentity` from config path
    4. Retrieve master key from keychain (or encrypted keyfile for headless)
    5. Initialize `chronogrid_core::Database`
    6. Start `chronogrid_net::SwarmManager` (P2P mesh)
    7. Start IMAP polling tasks for all configured accounts
    8. Start filesystem watchers for all configured watch paths
    9. Start CalDAV embedded server on `127.0.0.1:4242`
    10. Start Eisenhower score recomputation timer (every 15 minutes)
    11. Start automation rules engine event loop
    12. Block on shutdown signal (SIGTERM/SIGINT/SIGHUP)
    13. Graceful shutdown: stop all background tasks, flush database, close P2P swarm
  - Implement `apps/chronogrid_daemon/src/config.rs`:
    - `DaemonConfig` struct with full TOML deserialization
    - Sections: `[node]`, `[database]`, `[network]`, `[imap]` (array), `[watchers]` (array), `[caldav]`, `[logging]`
  - Implement `apps/chronogrid_daemon/src/web_gui.rs`:
    - Lightweight HTTPS web interface on `127.0.0.1:8443` using `axum`
    - Self-signed TLS certificate generated on first run
    - REST API endpoints: `GET /api/tasks`, `GET /api/notes`, `POST /api/tasks`, `GET /api/sync/status`
    - Minimal HTML/JS dashboard for browser-based task management
  - Create `apps/chronogrid_daemon/config.example.toml` with all options documented
  - Run `cargo build --release --package chronogrid_daemon`

---

## Task 5.2 — Headless Keyfile Credential Store

- [ ] **Task 5.2**: Implement encrypted keyfile credential storage for headless/server deployments:
  - Create `crates/chronogrid_crypto/src/keyfile.rs`:
    - `KeyFile` struct: stores encrypted master key + salt in a file
    - Encryption: AES-256-GCM with a key derived from a server-specific secret (environment variable or systemd credential)
    - `KeyFile::create(path: &Path, master_key: &[u8], server_secret: &[u8]) -> Result<()>`
    - `KeyFile::load(path: &Path, server_secret: &[u8]) -> Result<Vec<u8>>`
  - Implement `chronogrid_crypto::resolve_key(config: &KeyConfig) -> Result<Vec<u8>>`:
    - Tries OS keychain first (desktop mode)
    - Falls back to keyfile (headless mode)
    - Falls back to environment variable `CHRONOGRID_MASTER_KEY` (CI/container mode)
  - Update `chronogrid_daemon` to use `resolve_key` for flexible credential resolution
  - Unit tests: keyfile create/load round-trip, wrong server secret rejection, env var fallback
  - Run `cargo test --package chronogrid_crypto`

---

## Task 5.3 — Multi-Device Integration Test Suite

- [ ] **Task 5.3**: Create a comprehensive multi-device integration test suite:
  - Create `tests/integration/` directory at workspace root
  - Add `integration_tests` as a workspace member with `[[test]]` targets
  - Implement `tests/integration/sync_convergence.rs`:
    - Spawn two in-process `SwarmManager` instances on loopback
    - Create a task on Node A while Node B is offline
    - Reconnect nodes and verify task appears on Node B within 5 seconds
    - Verify CRDT merge: concurrent title edits on both nodes converge to a single value
  - Implement `tests/integration/crypto_pipeline.rs`:
    - Full pipeline: passphrase → Argon2id → SQLCipher open → CRDT write → read back
    - Verify wrong passphrase cannot open database
    - Verify keychain store/retrieve round-trip
  - Implement `tests/integration/ingestion_pipeline.rs`:
    - Mock IMAP server → IMAP poller → AI processing → task created in DB
    - File watcher → Markdown file drop → note + tasks created in DB
    - Jot text → NLP pipeline → task with correct namespace, due date, duration
  - Implement `tests/integration/caldav_sync.rs`:
    - CalDAV server starts → `curl` PROPFIND → verify calendar collection response
    - Create time block → verify iCalendar VEVENT in REPORT response
  - Run `cargo test --test sync_convergence --test crypto_pipeline --test ingestion_pipeline --test caldav_sync`

---

## Task 5.4 — Performance & Stress Testing

- [ ] **Task 5.4**: Perform performance and stress testing:
  - Implement `tests/perf/crdt_merge_stress.rs`:
    - Generate 10,000 concurrent task mutations across 3 simulated peers
    - Verify all peers converge to identical state within 30 seconds
    - Measure merge throughput: target > 1,000 merges/second
  - Implement `tests/perf/db_query_perf.rs`:
    - Insert 50,000 tasks across 10 namespaces
    - Measure query time for: list by namespace, filter by quadrant, filter by due date range
    - Target: all queries < 50ms on standard hardware
  - Implement `tests/perf/p2p_latency.rs`:
    - Measure round-trip sync latency between two local peers
    - Target: < 500ms for a single task delta sync on LAN
  - Document performance results in `docs/ARCHITECTURE/06-performance-benchmarks.md`
  - Run `cargo test --test crdt_merge_stress --test db_query_perf --test p2p_latency -- --nocapture`

---

## Task 5.5 — Android Platform Integration

- [ ] **Task 5.5**: Complete Android platform integration:
  - Configure Android NDK cross-compilation in `scripts/build_android_libs.sh`:
    - Targets: `aarch64-linux-android` (ARM64), `armv7-linux-androideabi` (ARM32), `x86_64-linux-android` (emulator)
    - Set `ANDROID_NDK_HOME` and `CARGO_TARGET_*_LINKER` environment variables
    - Build `chronogrid_ffi` for all three targets
    - Copy `.so` files to correct `jniLibs` subdirectories
  - Implement Android KeyStore bridge in Flutter:
    - `lib/src/core/android_keystore.dart` — uses `flutter_secure_storage` for Android KeyStore-backed key storage
    - Override `store_credential` / `retrieve_credential` FFI calls on Android with Dart-side KeyStore implementation
  - Implement Android-specific features:
    - `QuickJotWidget` — home screen widget using `home_widget` package
    - Share Intent receiver — `AndroidManifest.xml` intent filter for `ACTION_SEND` text/URL sharing
    - Background sync service — `WorkManager` periodic task for P2P sync when app is backgrounded
  - Test on Android emulator: `flutter run -d emulator-5554`
  - Test on physical Android device: `flutter run -d <device_id>`
  - Run `flutter test` — all tests pass on Android target

---

## Task 5.6 — Linux Platform Integration & AppImage Build

- [ ] **Task 5.6**: Complete Linux platform integration and AppImage packaging:
  - Configure GTK3 dependencies in `apps/chronogrid_flutter/linux/CMakeLists.txt`
  - Link `libchronogrid_ffi.so` in Linux CMake build
  - Implement Linux-specific features:
    - SecretService D-Bus integration (already in `chronogrid_crypto` via `keyring` crate)
    - Global hotkey via `global-hotkey` crate on Linux (X11/Wayland)
    - System tray icon using `tray_manager` Flutter package
  - Create `scripts/package_linux.sh`:
    - Build Flutter Linux release: `flutter build linux --release`
    - Package as AppImage using `appimagetool`
    - Package as `.deb` using `dpkg-deb`
  - Create `docs/DEPLOYMENT/02-linux-installation.md`
  - Cross-compile from Windows using WSL2 or Docker: `docker run --rm -v $(pwd):/workspace rust:latest cargo build --release --target x86_64-unknown-linux-gnu --package chronogrid_ffi`

---

## Task 5.7 — Windows MSI Installer

- [ ] **Task 5.7**: Create the Windows MSI installer:
  - Add `wix` toolset configuration: `apps/chronogrid_flutter/windows/installer/`
  - Create `Product.wxs` WiX source file:
    - Application name, version, manufacturer metadata
    - Install `chronogrid_flutter.exe` and `chronogrid_ffi.dll` to `Program Files\ChronoGrid\`
    - Install `chronogrid-daemon.exe` as an optional Windows Service component
    - Desktop shortcut and Start Menu entry
    - Uninstaller registration
  - Create `scripts/build_windows_installer.ps1`:
    - `flutter build windows --release`
    - `cargo build --release --package chronogrid_daemon`
    - Run WiX toolset: `candle.exe Product.wxs && light.exe Product.wixobj -o ChronoGrid-Setup.msi`
  - Create `docs/DEPLOYMENT/03-windows-installation.md`
  - Test installer on clean Windows VM

---

## Task 5.8 — Systemd Service & Server Deployment Guide

- [ ] **Task 5.8**: Finalize systemd service configuration and server deployment documentation:
  - Create `apps/chronogrid_daemon/deploy/chronogrid.service` (systemd unit file):
    ```ini
    [Unit]
    Description=ChronoGrid Headless Peer Node
    After=network-online.target
    Wants=network-online.target

    [Service]
    Type=simple
    User=chronogrid
    Group=chronogrid
    WorkingDirectory=/var/lib/chronogrid
    ExecStart=/usr/local/bin/chronogrid-daemon --config /etc/chronogrid/config.toml
    Restart=on-failure
    RestartSec=10
    StandardOutput=journal
    StandardError=journal
    SyslogIdentifier=chronogrid
    NoNewPrivileges=yes
    ProtectSystem=strict
    ProtectHome=yes
    ReadWritePaths=/var/lib/chronogrid

    [Install]
    WantedBy=multi-user.target
    ```
  - Create `apps/chronogrid_daemon/deploy/install.sh` — automated server installation script
  - Update `docs/DEPLOYMENT/01-headless-daemon-setup.md` with complete setup guide:
    - Prerequisites, binary installation, config file setup, keyfile credential setup, systemd enable/start, firewall rules, log monitoring
  - Create `docs/DEPLOYMENT/04-multi-device-pairing.md` — guide for pairing desktop + mobile + headless nodes using Swarm Key

---

## Task 5.9 — Final Verification & Release Checklist

- [ ] **Task 5.9**: Execute final verification and prepare release:
  - Run full test suite: `cargo test --workspace` — zero failures
  - Run `scripts/verify_agent_work.ps1` — exits with code 0
  - Run integration tests: all convergence, crypto, ingestion, and CalDAV tests pass
  - Run performance tests: all targets met (< 50ms queries, > 1,000 merges/sec, < 500ms P2P latency)
  - Manual acceptance testing against all criteria in `docs/ARCHITECTURE/04-master-user-story.md`:
    - [ ] IMAP polling creates tasks within 2 seconds of receipt
    - [ ] Database is unreadable without master key
    - [ ] Offline edits on two devices converge after reconnection without data loss
    - [ ] All four UI views render from same CRDT state store
    - [ ] Headless daemon builds for Linux/systemd and maintains CRDT state
  - Update `docs/ARCHITECTURE/01-OSAD-system-architecture.md` Section 8 roadmap to mark all phases complete
  - Create `CHANGELOG.md` with v1.0.0 release notes
  - Tag release: `git tag -a v1.0.0 -m "ChronoGrid P2P v1.0.0 — Initial Release"`
  - Push tag: `git push origin v1.0.0`

---

## Phase 5 Completion Criteria

- [ ] All 9 tasks above marked `[x]`
- [ ] `cargo test --workspace` passes with zero failures
- [ ] All integration tests pass
- [ ] All performance targets met
- [ ] All 5 acceptance criteria from master user story verified manually
- [ ] Windows `.msi` installer produced and tested
- [ ] Linux `.AppImage` and `.deb` packages produced
- [ ] Android `.apk` produced and tested on physical device
- [ ] `chronogrid-daemon` binary deployed and running on headless Linux server
- [ ] `v1.0.0` git tag pushed to `git.kellsupport.com`
- [ ] `DECISION_LOG.md` updated with Phase 5 decisions
- [ ] All ADRs up to date