# Completed Plans

Archive of implementation plans that have been executed and shipped.

## Content Addressing — COMPLETED ✓

**Completed:** March 2026 (Phase 3)

Hash-based fetch, in-memory index, mirror foundation. All five implementation steps completed:

1. `content-hash` added to FETCH responses — SHA-256 of stripped body in metadata
2. Hash index in Store — `BuildHashIndex()`, `LookupHash()`, `UpdateHashIndex()`, `RemoveHashEntry()`
3. Index updates on writes — `Write()`, `SetArchived()` keep index synchronized
4. Hash-based FETCH — `isHashPath()` validates `/sha256-<64hex>`, `handleFetchByHash()` retrieves by hash
5. Startup initialization — `BuildHashIndex()` called on server startup

**Key details:** Content-hash is separate from etag (stripped body vs full doc). Current versions only indexed. Read auth checked after hash resolves to real path. In-memory index rebuilt on startup.

**Foundation for:** Federation, content-addressed mirroring, distributed caching

---

## Federation — COMPLETED ✓

**Completed:** March 2026 (Phase 3)

Agent-driven hash discovery via MCP tools. Zero server changes, zero new verbs.

**Shipped:**
- `mark_index` MCP tool — crawls source server, collects hashes, publishes index to hub
- `mark_resolve` MCP tool — resolves content by hash using hub index
- `client/internal/index` package — Parse, Build, Merge for markdown hash index documents
- Manifest check enforced by tool, `force` override, `dry_run` mode, 1000 doc cap

---

## Persistent Graph — COMPLETED ✓

**Completed:** March 2026 (Phase 4)

Disk-backed graph store, incremental crawl, backlinks.

**Shipped:**
- `client/internal/graphstore` package — nodes, edges, etags, timestamps, atomic writes, schema versioning
- `CrawlAndPersist` — unified crawl + merge + save, nil-safe, shared across CLI/TUI/MCP
- `mark_backlinks` MCP tool — reverse link lookup
- Graph export — `Store.Export()` renders as publishable markdown, `ParseExport()` parses back
- TUI graph view — Links (BFS), Backlinks, Topology sub-views
- Graph seeding — TUI loads instantly from stored graph while crawl runs in background

---

## Read Auth (Server-Side) — COMPLETED ✓

**Completed:** 2026-03-14 (Phase 5)

Per-path read token enforcement on the server. Fully backwards compatible — no read tokens = everything public.

**Shipped:**
- `RequiresReadAuth(path)` on `TokenStore` — pre-computed `readPaths` at load time
- `authorizeRead` handler helper — checks token store, exempts `/.well-known/agent-manifest.md`
- Integrated into FETCH, LIST, VERSIONS handlers
- Content-addressed fetch respects read auth (hash resolves to path first, then checks auth)
- Versioned path auth — `/doc.md/v2` checks auth on base path `/doc.md`
- Directory path normalization — `/private` and `/private/` both match `/private/**` patterns

**Remaining (Phase 5):** Client-side read auth — `fetch.Client` read methods (`Fetch`, `List`, `Versions`) need a token parameter, then CLI, TUI, and MCP need to pass it through. The server enforces correctly; the clients just can't send a token on reads yet.

---

## Conflict-Aware Merge in `mark_publish` — COMPLETED ✓

**Completed:** 2026-05-05 (PR #101 in client/v0.12.25 — diff3 + merge-candidate response; v0.12.26 — default flipped from `"fail"` to `"merge"`)

Tool-level diff3 merge that reduces content loss under concurrent writes. The MCP tool produces a structurally-merged candidate body when `mark_publish` hits a version conflict; the agent semantically verifies the candidate and republishes. No wire-protocol changes; merge logic lives entirely in the Go client.

**Shipped:**
- `client/internal/merge/` package — `Diff3(base, ours, theirs) Result` (in-package implementation, ~250 lines, line-based LCS + hunk walk, no external dependency) + `Candidate(client, path, ours, expectedVersion, meta)` orchestrating publish-or-merge in one shot.
- `on_conflict` parameter on `mark_publish`: `"merge"` (default since v0.12.26) returns a merge candidate on conflict; `"fail"` opts out to strict optimistic-concurrency semantics.
- Git-style conflict markers in body (`<<<<<<<` / `=======` / `>>>>>>>`) — agents handle natively from training; format lives in client Go code and can be swapped without breaking the wire protocol.
- LCS dp table capped at 2M cells (~16 MB) — pathological inputs (1 MiB body of 1-byte lines) fall through to a single-hunk merge rather than allocating gigabytes.
- `Candidate` rejects responses where `latest.Version <= 0` to prevent silent "create-only" semantics from re-publishing into nothing.

**Key decisions:**
- **Tool never auto-publishes a diff3 result.** Always returns the candidate to the agent for semantic verification. Line-disjoint changes are not semantically-disjoint (duplicate bullets, contradictions, list reorder collisions can pass diff3 but corrupt the document).
- **No internal retry loop in the tool.** Each `mark_publish` call is one-shot; iteration lives in the agent's natural fetch-modify-publish loop.
- **`mark_append` deliberately out of scope.** Append-as-stream is the right primitive there; auto-resolve handles its tiny race window because there is nothing to merge.
- **Default flipped from `"fail"` to `"merge"` in v0.12.26** because the `"fail"`-default left naive callers exposed to silent content loss — the exact failure mode the feature exists to prevent. The shape change (`merge-candidate` vs `conflict`) is loud, not silent.

**Wire-level impact:** zero. `on_conflict` is an MCP tool parameter handled in the Go client.

---

## Claude Code Plugin — COMPLETED ✓

**Completed:** 2026-04-23 plan landed; demarkus-memory plugin v0.1.1 shipped on the marketplace; SessionStart hook + lazy-spawned server + auto-generated token in active use across every demarkus development session since.

One-click marketplace install gives Claude Code users a local, versioned memory layer backed by a spawned `demarkus-server`. Zero core code changes — the plugin is built entirely on existing primitives (DEMARKUS_AUTH env var, `demarkus-token generate`, ALPN-tagged `/health`, `tokens.Resolve`).

**Shipped:**
- `plugins/claude-code/` plugin tree: `.claude-plugin/plugin.json`, `hooks/postinstall.sh` + `hooks/session-start.sh`, `.mcp.json`, slash commands (`/soul`, `/soul-journal`, `/soul-status`, `/soul-init`, `/soul-context`, `/soul-memory`), `skills/memory/SKILL.md` triggering on remember/save/recall intents, `seed/index.md` template.
- `.claude-plugin/marketplace.json` at repo root for `/plugin marketplace add latebit-io/demarkus`.
- `postinstall.sh` — detects platform via `uname -sm` (darwin/arm64, darwin/amd64, linux/amd64, linux/arm64), downloads `demarkus-server` + `demarkus-mcp` + `demarkus-token` from GitHub releases, verifies SHA256 checksums against bundled file, installs to `${CLAUDE_PLUGIN_ROOT}/bin/`.
- `session-start.sh` — probes existing demarkus server on default port 6310 via ALPN-tagged `/health` (a non-demarkus process can't pass ALPN negotiation, so port-reuse is safe), spawns server detached when absent, generates a `/*`-scoped publish+archive token on first run, writes raw token to `~/.demarkus/soul/.token` mode 600, exports `DEMARKUS_AUTH` before MCP client launches, copies seed `index.md` when content root is empty.
- Plugin config at `~/.demarkus/plugin-memory.conf` records the chosen `MODE` (default | isolated | reuse), `SOUL_DIR`, `PORT`.

**Key decisions:**
- **Lazy spawn, no service manager** (no launchd/systemd in v1). Server persists across sessions; next session reuses it via the ALPN-tagged probe.
- **No core code changes.** Every primitive (`DEMARKUS_AUTH`, `/health`, `tokens.Resolve`, the `demarkus-token generate` CLI redirection pattern) already existed. The plugin is pure plumbing.
- **Content root at `~/.demarkus/soul/`** by default. All versioning, graph data, tokens, logs live under it.
- **Token mode `600`** on `~/.demarkus/soul/.token`.

**In active use:** the demarkus development workflow itself uses the plugin as the agent's memory layer — every session this conversation runs against the lazy-spawned server, every journal entry is a `mark_append` via the plugin's MCP wiring, the universe-deployment plan is fetched/republished through it.

---

## Phase 6 — Universe Deployment (mostly complete)

Phase 6 (`/plans/universe-deployment.md`) is ~90% complete as of 2026-05-13: Helm charts for server / broker / agent, OIDC token broker binary + chart, kind-tested upgrade-wipe regression, per-service runtime images, OCI Helm chart publish via release pipeline, structured-slog observability with operator-facing schema doc. Remaining: §6.4 (topology examples) and §6.6 (ops-runbook docs), both under reframing per the "ops polish vs knowledge universe" cost/value pushback. Active plan stays at `/plans/universe-deployment.md` until §6.4 + §6.6 are resolved or formally deferred.