Continuity Ledger v1 — persistence-memory operator baseline

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+__pycache__
+*.pyc
+.env
+data/
+*.log
+.pytest_cache
+.venv
+venv
+tests
+docs
+scripts
+*.md
+!README.md

.env.example

@@ -1,4 +1,7 @@
 JARVIS_HOST=0.0.0.0
 JARVIS_PORT=8001
+JARVIS_ENV=development
 JARVIS_STORE_PATH=data/jarvis-store.json
 JARVIS_CORS_ORIGINS=*
+# Optional: when set, require Authorization: Bearer <key> or X-API-Key
+# JARVIS_API_KEY=

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main, "crew/**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Pytest
+        run: python -m pytest -q
+      - name: Docker build
+        if: matrix.python-version == '3.12'
+        run: docker build -t persistence-memory:ci .

.gitignore

@@ -1,4 +1,13 @@
 __pycache__/
 *.pyc
 .env
+.venv/
+venv/
+.pytest_cache/
 data/jarvis-store.json
+data/*.log
+data/*.tmp
+*.log
+*.egg-info/
+dist/
+build/

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    JARVIS_ENV=production \
+    JARVIS_HOST=0.0.0.0 \
+    JARVIS_PORT=8001 \
+    JARVIS_STORE_PATH=/data/jarvis-store.json
+
+COPY pyproject.toml ./
+COPY app ./app
+
+RUN pip install --no-cache-dir -e .
+
+RUN mkdir -p /data
+
+EXPOSE 8001
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8001/health')"
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 warheart1984-ctrl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,75 @@
+# persistence-memory
+
+**Continuity Ledger** HTTP service for cross-session agent state.
+
+- **Distribution name:** `persistence-memory` (this GitHub repo)
+- **Service identity:** `jarvis-memoryboard` / schema `continuity-ledger-v1`
+- **Default URL:** `http://127.0.0.1:8001`
+
+This is **not** a claim of full CCS (Constitutional Continuity Service) readiness. See [docs/RELATIONSHIP_TO_MANDALA.md](docs/RELATIONSHIP_TO_MANDALA.md) and the [maturity scorecard](docs/scorecards/persistence-memory.md).
+
+## Maturity (evidence-bound)
+
+| Capability | Status | Evidence |
+|------------|--------|----------|
+| Continuity (A→B→C same restore) | **enforced** | `tests/test_acceptance.py::TestContinuityAcceptance` |
+| Replay (why/where/when/session) | **enforced** | `TestReplayAcceptance` + `/api/jarvis/memory/retrieve` |
+| Conflict (no silent merge) | **enforced** | `TestConflictAcceptance` + `/api/jarvis/memory/conflicts` |
+| Drift (hash fidelity) | **partial** | hash check enforced; multi-day protocol operator-owned |
+| Optional API key | **enforced** | `tests/test_auth.py` when `JARVIS_API_KEY` set |
+| CCS / multi-product authority | **declared** | not implemented here |
+
+### Drive-G-2 dimensions (summary)
+
+| Dimension | Rating |
+|-----------|--------|
+| Constitutional model | Moderate |
+| Governance methodology | Moderate |
+| Reference implementation | Moderate (local vertical slice + acceptance tests) |
+| Platform engineering | Moderate (CI + Docker + optional auth; JSON file store, no HA) |
+| Commercial operations | Not started |
+
+Full table: `docs/scorecards/persistence-memory.md`. Operator deploy: `docs/OPERATOR_DEPLOY_CHECKLIST.md`. Clause V hygiene: `docs/CLAUSE_V_HYGIENE.md` (**partial** / not API-enforced).
+
+## Quick start
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m app
+# or
+uvicorn app.main:app --host 127.0.0.1 --port 8001
+python -m pytest -q
+.\scripts\smoke-test.ps1
+```
+
+Docker:
+
+```bash
+docker compose up --build -d
+```
+
+## API (high level)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/health` | Liveness + schema |
+| GET/POST/PATCH | `/api/jarvis/memory/board` | Board context |
+| GET/POST | `/api/jarvis/memory` | List / create ledger rows |
+| GET | `/api/jarvis/memory/retrieve` | Memories + selections + conflicts |
+| GET | `/api/jarvis/memory/conflicts` | Conflict sets by subject |
+| GET/PATCH/DELETE | `/api/jarvis/memory/{id}` | Row CRUD |
+
+Create requires Continuity Ledger fields: `content`, `source_agent`, `session_id`, `type`, plus optional `confidence`, `evidence`, `status`, `subject`, `supersedes`, `tags`.
+
+Legacy on-disk rows (`category` / `truth_status` / …) migrate on load.
+
+## Operator notes
+
+- Set `JARVIS_API_KEY` when exposing beyond loopback ([SECURITY.md](SECURITY.md)).
+- Tighten `JARVIS_CORS_ORIGINS` in shared networks.
+- `JARVIS_ENV=production` disables uvicorn reload.
+- Store path: `JARVIS_STORE_PATH` (atomic JSON writes).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.2.x   | Yes       |
+| < 0.2   | Legacy skeleton — upgrade |
+
+## Reporting a vulnerability
+
+Open a private security advisory on GitHub or contact the repository owner.
+Do not commit secrets, API keys, or production store dumps.
+
+## Operator hardening (baseline)
+
+1. Set `JARVIS_API_KEY` when binding beyond loopback.
+2. Set `JARVIS_CORS_ORIGINS` to explicit origins (never `*` in shared networks).
+3. Set `JARVIS_ENV=production` (disables uvicorn reload).
+4. Persist `/data` (or `JARVIS_STORE_PATH`) on durable volume; never commit store files.
+5. Prefer TLS termination at a reverse proxy; this service speaks plain HTTP.
+6. The ledger does **not** enforce multi-tenant isolation — one store per deployment.
+7. Prefer `type=decision` (+ evidence) over chat dumps — Clause V hygiene is **partial** / not API-enforced (`docs/CLAUSE_V_HYGIENE.md`).
+8. Follow `docs/OPERATOR_DEPLOY_CHECKLIST.md` before shared-network exposure.

app/__init__.py

@@ -0,0 +1,2 @@
+# jarvis-memoryboard — Continuity Ledger v1
+# distribution: persistence-memory

app/__main__.py

@@ -1,7 +1,13 @@
 import os
+
 import uvicorn
+from dotenv import load_dotenv
+
+load_dotenv()
 
 if __name__ == "__main__":
     host = os.getenv("JARVIS_HOST", "0.0.0.0")
     port = int(os.getenv("JARVIS_PORT", "8001"))
-    uvicorn.run("app.main:app", host=host, port=port, reload=True)
+    env = (os.getenv("JARVIS_ENV") or "development").lower()
+    reload = env not in {"production", "prod"}
+    uvicorn.run("app.main:app", host=host, port=port, reload=reload)

app/auth.py

@@ -0,0 +1,48 @@
+"""Optional API-key gate for operator deployments.
+
+When JARVIS_API_KEY is unset, all routes remain open (local/dev default).
+When set, non-public routes require Bearer or X-API-Key.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+
+def configured_api_key() -> str | None:
+    key = (os.getenv("JARVIS_API_KEY") or "").strip()
+    return key or None
+
+
+def extract_presented_key(request: Request) -> str | None:
+    auth = request.headers.get("Authorization") or ""
+    if auth.lower().startswith("bearer "):
+        return auth[7:].strip() or None
+    header_key = request.headers.get("X-API-Key")
+    if header_key:
+        return header_key.strip() or None
+    return None
+
+
+def path_is_public(path: str) -> bool:
+    return path in {"/", "/health", "/docs", "/openapi.json", "/redoc"}
+
+
+class OptionalApiKeyMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        expected = configured_api_key()
+        if expected is None or path_is_public(request.url.path):
+            return await call_next(request)
+
+        presented = extract_presented_key(request)
+        if presented is None or not hmac.compare_digest(presented, expected):
+            return JSONResponse(
+                status_code=401,
+                content={"detail": "Invalid or missing API key"},
+            )
+        return await call_next(request)