diff --git a/docs/explanation/design.md b/docs/explanation/design.md index c8cb070..ff7b711 100644 --- a/docs/explanation/design.md +++ b/docs/explanation/design.md @@ -387,6 +387,13 @@ Reuse the established blumeops patterns (πŸ”’ confirmed by repo conventions): - **Phase 0 β€” Design** (this document + [[tech-spec]]): done enough to build. - **Phase 1 β€” v1 prototype (a single C1 effort, deliberately β€” a one-shot test of delivering a high-complexity prototype from the spec; built in TDD slices):** `heph-core` (model, schema, extraction, recurrence, "what is next", `Store` trait, op-log/HLC/CRDT merge) β†’ `hephd` **local mode** β†’ **server + client modes (+ lock handoff)** β†’ **offline sync + conflict queue** β†’ **OIDC/Authentik auth + per-user isolation** β†’ `heph.nvim` + `heph` CLI. Local-only works standalone; runnable client/server + offline sync on the tailnet. The build order doubles as the cross-session resume tracker (next un-green slice = where to resume). C2/Mikado is *not* used: it sequences prerequisites against existing code under test, and this is greenfield delivery from a complete spec; follow-up C1s or a C2 refactor come later as needed. + + **Phase 1 progress** (branch `feature/v1-prototype`, PR #1; 102 tests green as of 2026-06-01 β€” see [[tech-spec]] Β§14 for the per-area tracker): + - [x] `heph-core` library β€” schema/`Store`/`LocalStore`, extraction, tasks/links/canonical-context + wiki-link materialization, "what is next?" ranking, recurrence roll-forward + per-task logs. + - [x] `hephd` **local mode** β€” file lock + JSON-RPC over a unix socket (tokio blocking pool); `heph` CLI + `export`. + - [x] Local query surface β€” `list`, `health`, `journal`, `search` (FTS5). + - [x] **Sync engine (no network yet)** β€” HLC + device origin; op-log recording; `apply_op` merge (LWW + conflict queue, OR-set links, monotonic tombstones, idempotent); two-replica convergence proven; `adopt_owner` (basic Β§13). + - [ ] **Resume here β†’** yrs text-CRDT for bodies (upgrade body merge from LWW); then **server/client modes + network push/pull** (transport over the existing engine); then **OIDC/Authentik auth**; then **`heph.nvim`**. - **Phase 2 β€” k3s deployment:** Daggerβ†’Zot image, ArgoCD app + Kustomize manifests, external-secrets; hub on blumeops. - **Phase 3 β€” Web UI** on the hub. - **Phase 4 (later, optional)** β€” calendar integration (careful CalDAV); migration from ZK / Todoist; iOS / Apple Watch voice capture; Hermes-style planning mode. diff --git a/docs/reference/tech-spec.md b/docs/reference/tech-spec.md index 60000b6..e6e7e32 100644 --- a/docs/reference/tech-spec.md +++ b/docs/reference/tech-spec.md @@ -324,6 +324,29 @@ See [[design]] Β§5–§7 for the constraints later phases impose on present choi - **Local trust:** the local unix-socket RPC trusts the OS user (file-permission-scoped socket); app-level auth is for the **network** boundary (device ↔ hub). - **At-rest:** plain SQLite in v1 (no encryption) β€” security boundary is auth + (eventually) network restriction. May revisit (see [[design]]). +## 14. Implementation status (Phase 1 tracker) + +> Cross-session resume tracker for the Phase 1 C1 (branch `feature/v1-prototype`, PR #1). Updated 2026-06-01 β€” **102 tests green** (`cargo test --all`), `clippy -D warnings` + `fmt` + `prek` clean. Workspace: `crates/heph-core`, `crates/hephd`, `crates/heph` (no `heph.nvim/` yet). + +**Done** + +- βœ… **Data model + schema (Β§4):** migrations v1–v3 (base graph, FTS5, `meta`). Node kinds, tasks, links, aliases, users, oplog, sync_state, conflicts, meta. `Store` trait + `LocalStore`. +- βœ… **Markdown handling (Β§5):** wiki-link + checkbox extraction (pure, idempotent, code-aware); `update_node` materializes/reconciles `wiki` links; `export` to a `/.md` tree. +- βœ… **Recurrence (Β§4.4):** roll-forward in place β€” fresh checklist, logged occurrence, advance-skipping-misses; completion never carries forward (proptest). Per-task logs; `skip`. +- βœ… **Ranking (Β§7):** pure two-stage filter + reorderable named dimensions; proptest total order. +- βœ… **Daemon RPC (Β§6) β€” local subset:** node.get/create/update/tombstone, task.create/set_state/set_attention/skip, next, list, health, journal.open_or_create, search, links.outgoing/backlinks, log.append/tail, export, conflicts.list/resolve, sync (ops_since/apply_op). Line-delimited JSON-RPC over a unix socket; sync `Client`. +- βœ… **Runtime modes (Β§3.1) β€” `local` only:** exclusive file-lock handoff via `LockGuard`. +- βœ… **Sync engine (Β§12) minus network:** HLC (clock-injected, monotonic) + persistent device `origin`; op-log per mutation; `apply_op` merge β€” **LWW** scalars/bodies with a **conflict queue**, **OR-set** links, monotonic tombstones, idempotent; two-replica convergence proven. `adopt_owner` = basic Β§13 canonical-owner adoption. +- βœ… **CLI (Β§1):** `heph` next/task/doc/get/export/search/journal. +- βœ… **CI (Β§9):** `.forgejo/scripts/build` runs fmt/clippy/test (self-bootstrapping rustup). + +**Not yet done (resume order)** + +1. ⏳ **Body CRDT (Β§5, Β§12):** replace body LWW with the **yrs** text CRDT β€” `body_crdt` BLOB, diff whole-body writes into the yrs doc, merge yrs updates in `apply`. (CRDT lib ratified = `yrs`.) +2. ⏳ **`server`/`client` modes + network sync (Β§3.1, Β§6.1, Β§12):** `RemoteStore`; hub network endpoint; push/pull by HLC cursor (the merge logic already exists); background sync; `sync.now`/`sync.status` RPC; multi-replica-over-real-sockets tests. Open: transport (`axum` HTTP/JSON vs gRPC), propagation cadence, device-id/hub registration. +3. ⏳ **OIDC/Authentik auth (Β§13):** device-code flow, bearer token on the hub endpoint, full per-user isolation, adoption-with-deterministic-ids. +4. ⏳ **`heph.nvim` (Β§8):** obsidian.nvim parity + task views; headless-nvim e2e (needs `neovim` + `plenary.nvim` on the CI runner). + ## Related - [[design]] β€” full design document with rationale and decision history