Build / validate (pull_request) Failing after 2s

Details

hephd: network sync over HTTP — hub + spoke (sync 9a)

Wire the existing merge engine over the network so the everyday config
(local + hub_url) syncs through a hub. Transport ratified = axum HTTP/JSON
(tech-spec §6.1, §12).

- heph-core: SyncCursors model + Store::sync_state/record_sync over the
  sync_state table (per-peer push/pull HLC cursors). Incremental, so each
  exchange transfers only the tail.
- hephd::sync: the hub router (POST /sync/push, GET /sync/pull?after=<hlc>)
  served from the shared LocalStore, and sync_once — a spoke's pull-then-
  merge, then push-tail exchange, advancing the cursors. Idempotent: a
  re-pushed op the hub already has is a no-op.
- Daemon carries optional hub config; sync.now/sync.status handled at the
  daemon (they need the hub transport the store can't reach). conflicts.
  list/resolve now reachable over the unix socket too.
- main: --mode local|server, --hub-url, --http-addr. server mode binds the
  hub HTTP endpoint on the same store; a local+hub_url spoke background-
  syncs on a 30s interval.
- tests/sync_http.rs: two spokes converge through a real-HTTP hub on an
  ephemeral port — node propagation and a divergent-scalar conflict.

Unauthenticated/single-owner for now; OIDC + per-user scoping is slice 10,
client mode + RemoteStore is 9b. 100 tests green; clippy -D warnings + fmt
+ prek clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-01 15:14:20 -07:00

7 KiB

Raw Blame History

hephaestus

A personal context management system — a single, self-hosted Rust application that fuses a wiki-style knowledge base (Zettelkasten) with task management. Notes and tasks are first-class, cross-linkable entities in one database, so a task like "Fix the roof leak" stays coupled to the home-repair log and contractor-call notes that give it context.

It is offline-first: fully useful on a laptop with no network, and (when the distributed layer lands) auto-syncing to a central instance hosted in blumeops. The primary surface will be a Neovim plugin (heph.nvim, an obsidian.nvim replacement); a CLI (heph) is the utility/scripting surface.

Why "what is next?" is the flagship. heph is organized around concise, honest answers to recurring questions — above all "what do I do right now?" — built from ~10 years of the owner's lived prioritization discipline: projects-as-contexts; attention colors (white/orange/red/blue, where red = a consequence exists if late, not importance); do-dates, not due-dates (earliest-actionable, never a deadline alarm); and working-set tensions surfaced honestly (no "fake happy", no overwhelm).

See docs/explanation/design.md for the vision and rationale, and docs/reference/tech-spec.md for the implementation-facing specification.

Status

Phase 1 (v1 prototype) — in progress on branch feature/v1-prototype. The local system is feature-complete and replicas now sync through a hub over HTTP — the offline-first everyday config (local + hub_url) converges end-to-end, with a yrs text-CRDT merging bodies. Remaining: the online-only client mode, auth, and the Neovim plugin. Built test-first (100 tests at last update). The canonical tracker is tech-spec §14.

Area	State
Data model, markdown extraction, wiki-links, export	✅ done
Tasks, links, "what is next?" ranking, recurrence, per-task logs	✅ done
`hephd` daemon — local mode (file lock + JSON-RPC over a unix socket)	✅ done
`heph` CLI; `list` / `health` / `journal` / full-text `search` (FTS5)	✅ done
Sync engine — HLC, op-log, converging merge + conflict queue (no network yet)	✅ done
yrs text-CRDT for body merge	✅ done
`server` (hub) mode + spoke push/pull sync over HTTP (axum)	✅ done
`client` mode + `RemoteStore` (online-only, no replica)	⏳ next
OIDC/Authentik auth + per-user isolation	⏳
`heph.nvim` (primary surface)	⏳

Architecture

A Cargo workspace, layered so the same core runs from a laptop to a hub:

crates/heph-core — the library: data model, the Store trait + SQLite store, markdown parsing/extraction, recurrence, the "what is next?" engine, and the sync engine (op-log, hybrid logical clocks, CRDT/LWW merge, conflict detection). Synchronous and clock-injected (no ambient wall-clock reads) so ranking and merge are deterministic.
crates/hephd — the per-device daemon. One binary, three modes — local (own SQLite replica; a syncing spoke when given --hub-url), server (also the sync hub: an HTTP endpoint others sync against), client (planned) (thin, remote, no replica) — selected by configuration via a targetable Store backend. Surfaces connect to it over a unix socket; it owns the DB handle and background sync.
crates/heph — the CLI: a thin client of the daemon (no direct DB access).
heph.nvim/ (planned) — the Neovim plugin, the primary editing/agenda surface.

Storage: SQLite is the source of truth; a node's body is markdown; export materializes the whole store as a directory of .md files. Sync: each device holds a full replica + an append-only op-log; devices reconcile through a hub with automatic merge (text-CRDT bodies, last-writer-wins scalars, OR-set links) and a conflict queue for the ambiguous remainder. Auth (planned): OIDC against Authentik, with per-user isolation.

Build & run

Requires a Rust toolchain (stable). The build is a standard Cargo workspace:

cargo build              # build all crates
cargo test --all         # run the full test suite
cargo clippy --all-targets -- -D warnings

Run the daemon in local mode, then drive it with the CLI:

# Terminal 1 — start the daemon (creates ~/.local/share/heph/heph.db and a socket)
cargo run -p hephd

# Terminal 2 — talk to it
cargo run -p heph -- task "Fix the roof leak" --attention red
cargo run -p heph -- next                 # the "what is next?" ranking
cargo run -p heph -- doc "Roof log" --body "Called the contractor."
cargo run -p heph -- search roof          # full-text search
cargo run -p heph -- journal 2026-06-01   # open/create today's journal
cargo run -p heph -- export ./snapshot    # write the store as a .md tree

The daemon takes an exclusive lock on its DB file; --db and --socket override the defaults.

Development

Test-driven. Every feature has tests at the appropriate layer(s) — unit, property tests, real-socket daemon integration, and CLI process tests. No feature is "done" without them.
Change process. Changes are classified C0 / C1 / C2 (quick fix / human-review PR / Mikado chain). The v1 prototype is a single long-lived C1. See docs/how-to/agent-change-process.md.
Git hooks & tooling. prek runs formatting, linting, and secret detection; mise runs repo automation; CI (Forgejo) runs prek plus cargo fmt/clippy/test via .forgejo/scripts/build.

prek install && prek install --hook-type commit-msg   # set up hooks
prek run --all-files                                  # run all checks
mise tasks                                            # list automation tasks
mise run ai-docs                                      # docs AI agents read first

Documentation is Diataxis-structured and built with Quartz; changelog fragments use Towncrier under docs/changelog.d/. Working agents should read AGENTS.md first.

Repository layout

./Cargo.toml            # workspace manifest
./crates/heph-core/     # core library: model, store, extraction, recurrence, ranking, sync
./crates/hephd/         # daemon: local + server (hub) modes — unix-socket RPC + HTTP sync; client planned
./crates/heph/          # CLI: thin client of the daemon
./heph.nvim/            # Neovim plugin (planned)
./docs/                 # Diataxis docs (design, tech-spec, how-to), Quartz config
./.forgejo/             # CI build + release workflows and hooks
./.dagger/              # Dagger module backing docs builds/releases
./mise-tasks/           # repo automation via `mise run`

7 KiB Raw Blame History