Add P2P/offline memory implementation docs

[Copilot]

Adds a 13-file developer documentation bundle under docs/p2p-offline-memory/ specifying the planned decentralised, offline-first, policy-governed memory layer for BrainCell — covering architecture through rollout.

Document set

File	Covers
README.md	Index, positioning, quick-start
01-architecture-overview.md	Component diagram, write/read/replication data-flows, cell integration strategy
02-data-model-events-policy-nodeprofile.md	EventEnvelope schema, canonical JSON contract, Policy object, NodeProfile with derived-domain computation
03-eventstore-projectors-search.md	SQLite schema, EventStore protocol, Projector/ProjectorRegistry, FTS5 virtual tables + triggers
04-policy-engine.md	All boundary rules (residency, 5-eyes, scope, classification, transit, diode), YAML region config, audit log format
05-replication-protocol.md	Handshake + cursor-sync API specs, sender-side filtering, receiver processing loop, Prometheus metrics
06-airgap-courier-bundles-diode.md	Bundle structure (manifest.json / events.ndjson / manifest.sig), export/import APIs, data-diode roles
07-media-aware-transfer.md	Media profiles (low-BW, satellite, physical), chunked transfer, external blob refs, bandwidth throttling
08-security-crypto-identity.md	Threat model, mTLS, Ed25519 sign/verify + quarantine, envelope encryption (ChaCha20 + X25519), key rotation/revocation
09-testing-observability-ops.md	7 integration scenarios, structured log events, /health + /metrics specs, ops runbooks
10-editions-packaging.md	Community / Professional / Enterprise feature matrix, deployment variants, env vars, compose example
11-rollout-roadmap.md	Phased tickets T1–T8 with deliverables and acceptance criteria across 4 sprints
12-faq-glossary.md	15 FAQs (including GDPR erasure, 5-eyes threat model, conflict resolution), 40-term glossary

Key design decisions documented

• Append-only EventEnvelope log as the single replication unit — no in-place edits; updates are new events
• Policy travels with the event — can_store / can_send / can_receive evaluated at every boundary
• Projectors translate the event stream into existing materialised views, preserving the current API surface with no route-handler changes
• Cursor-based idempotent sync — replay-safe; partition-tolerant by design
• No code changes; documentation-only.

Original prompt

Add a complete multi-file developer documentation bundle to the repository describing the planned BrainCell P2P/offline-first/policy-governed memory system discussed in chat.

Repository: Itlusions/ITL.Braincell

Requirements:

• Add a new documentation directory (suggested path: docs/p2p-offline-memory/) containing the following Markdown files with the exact content from the chat bundle:
  • README.md
  • 01-architecture-overview.md
  • 02-data-model-events-policy-nodeprofile.md
  • 03-eventstore-projectors-search.md
  • 04-policy-engine.md
  • 05-replication-protocol.md
  • 06-airgap-courier-bundles-diode.md
  • 07-media-aware-transfer.md
  • 08-security-crypto-identity.md
  • 09-testing-observability-ops.md
  • 10-editions-packaging.md
  • 11-rollout-roadmap.md
  • 12-faq-glossary.md
• Ensure all Markdown renders well on GitHub, including Mermaid diagrams.
• Ensure cross-file links in the README are correct relative links.
• Do not modify existing code; documentation-only PR.

Use a concise PR title like: "Add P2P/offline memory implementation docs".

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Make a full implementation document what i can give to mu developers. Make it in md in a zipfile

Assistant: I can write the full implementation document in Markdown, but I can’t directly return a real .zip file through this chat.

Two practical options:

1. I output the Markdown here, and you (or your devs) run a one-liner to zip it.
2. If you want it committed in your repo, I can create the files in a branch (and you/CI can download a zip from GitHub).

Tell me which you prefer. Meanwhile, here is a complete implementation document as a single Markdown file you can save as IMPLEMENTATION_P2P_OFFLINE_MEMORY.md and zip.

You can zip it locally with:

zip -r braincell-implementation-docs.zip IMPLEMENTATION_P2P_OFFLINE_MEMORY.md

---

# ITL.Braincell — P2P Offline-First Memory + Data Residency Policies (Implementation Spec)

Repository: `Itlusions/ITL.Braincell`  
Date: 2026-04-26  
Audience: Developers implementing changes in BrainCell

## 0. Summary

This document specifies how to implement a decentralized, offline-first memory system for BrainCell that:

- Replicates memory data between BrainCell nodes via P2P (direct sync and optional “courier” air-gap bundles).
- Enforces “where data may live” (residency/jurisdiction, 5-eyes-like constraints, team/org scopes).
- Continues operating when central storage is unavailable (local-first).
- Provides local search without requiring central Weaviate (FTS first; embeddings optional).
- Ensures integrity and provenance via signatures; confidentiality via encryption-by-scope.

The design is based on:
- **Event-sourced append-only log** (canonical replication unit)
- **Policy engine** (admission + send/receive/store rules)
- **Projectors** (materialized views feeding existing APIs)
- **Replicator** (P2P transport + sync protocol)
- **Local index** (SQLite FTS5 baseline)

---

## 1. Goals & Non-Goals

### 1.1 Goals
1. Local-first writes: every `*_save` tool succeeds without network.
2. P2P replication of events with filtering based on policy + node profile.
3. Data residency: prevent events from being stored/received/sent where not allowed.
4. Air-gapped support via “courier node” and/or “replication bundles”.
5. Preserve current external API surface where possible (`/tools/*` via MCP; `/api/*` endpoints if used).

### 1.2 Non-Goals (initial MVP)
- Global consistent search across all nodes (each node only searches what it stores).
- Real-time collaborative editing (CRDT). Updates are modeled as new events.
- Full libp2p discovery in MVP (start with configured peer lists; libp2p can be a later phase).

---

## 2. High-Level Architecture

### 2.1 Node components
- Tools/Cells Layer (existing)
- Policy Engine (new)
- Event Store (new, SQLite-based)
- Projectors / Materialized Views (new)
- Local Search Index (new, SQLite FTS5)
- Replicator (new; transport + sync)
- Optional: Central Storage Node acting as a peer

### 2.2 Data flow (write path)
1. Tool invoked (e.g., `interactions_save`)
2. Policy assigned (defaults + overrides)
3. Event envelope created, signed, optionally encrypted
4. Append to local EventStore
5. Projectors update local views
6. Index updated for local search
7. Replicator eventually syncs events to allowed peers

---

## 3. Canonical Data Model

### 3.1 Event envelope
All replication is done as EventEnvelope objects.

Required fields:
- `event_id` (UUID)
- `event_type` (string; e.g., `interactions.created`, `decisions.created`)
- `occurred_at` (RFC3339)
- `node_id` (string)
- `actor_id` (string; user or agent)
- `schema_version` (int)
- `policy` (Policy object)
- `payload` (JSON object OR ciphertext blob + metadata)
- `signature` (bytes/base64) — signature over canonical serialization
- `hash` (bytes/base64) — SHA-256 of canonical serial...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[nielsweistra]

@copilot replace all ascii with mermaid diagrams

[Copilot]

@copilot replace all ascii with mermaid diagrams

Done in commit 50289ef. All 12 ASCII art diagrams across 5 files have been replaced with Mermaid:

• 01-architecture-overview.md — node components (flowchart TB with subgraph), write-path, read-path, and replication data-flows (flowchart TD), plus all 4 deployment topology diagrams (graph LR/TB)
• 06-airgap-courier-bundles-diode.md — bundle file structure (graph TD)
• 08-security-crypto-identity.md — envelope encryption flow (flowchart TD) and key storage structure (graph TD)
• 10-editions-packaging.md — standalone node, replicated cluster, and air-gap site topologies
• 11-rollout-roadmap.md — ticket dependency graph (graph TD with all T1→T8 edges)