# Journal — 2026-03-07

## 2026-03-07 — MCP mark_append Auto-Resolve + Install Script Fix

Two items this session:

### Install Script: Unbound Variable Fix

Fritz ran `curl ... | bash -s -- --client-only` on his Intel Mac mini (pre-Tahoe macOS) and hit `bash: line 200: CURL_AUTH_ARGS[@]: unbound variable`. Root cause: `set -euo pipefail` + empty array expansion. Older bash versions don't handle `${array[@]+"${array[@]}"}` either. Fix: wrap the two curl calls that use `CURL_AUTH_ARGS[@]` with `set +u` / `set -u`. Two locations: `github_api()` and `do_update()`.

### MCP mark_append: Optional expected_version

Made `expected_version` optional in the `mark_append` MCP tool. When omitted or 0, the tool internally calls VERSIONS to get the current version, then appends with that version. Optimistic concurrency is still enforced — the server always sees an `expected_version`. This removes the need for agents to manually call VERSIONS before every append.

**Changes:**
- `markAppendTool`: `expected_version` no longer `mcp.Required()`
- `markAppend` handler: `GetInt("expected_version", 0)` → if 0, calls `Versions()` → parses `current` → uses it
- Status check: validates `protocol.StatusOK` before reading metadata
- Negative version guard: rejects `< 0` explicitly
- `markClient` interface: introduced to decouple handler from `*fetch.Client` for testability
- 5 new tests: auto-resolve (happy path), not-found, explicit version, negative version, no token
- Tool/parameter descriptions updated to document "omitted or 0" behavior consistently

Copilot code review drove several improvements: status check before metadata access, `protocol.StatusOK` constant instead of string literal, consistent description wording, and the test coverage push that motivated the `markClient` interface.

### What I Learned

The `markClient` interface was the right call even though the project philosophy leans against premature abstractions. It's not premature when it enables testing actual business logic (version auto-resolution) that would otherwise require a QUIC connection. The interface matches the methods the handler actually uses — no speculative surface area.

## 2026-03-07 — Hub is live

demarkus-hub is up and running at `mark://hub.demarkus.io`. A public discovery index for the demarkus network — no original content, just links to other servers organized by category. Content lives in a Git repo and CI auto-publishes on push to main. First real instance of the hub pattern: servers that exist purely to connect other servers. The more hubs that spin up and cross-link, the more discoverable the whole network becomes. Added docs for the hub pattern to the pages site and linked the repo from the homepage.


---

## 2026-03-07 — Content-Addressed Fetch: Shipped

Implemented content-addressed fetch — `FETCH /sha256-<64hex>` retrieves documents by content hash. The feature went through two rounds of review: initial implementation, then a thorough Copilot + security audit.

### What Shipped

- **`content-hash` in FETCH responses** — SHA-256 of the stripped body (distinct from `etag` which hashes raw on-disk content including store frontmatter)
- **In-memory hash index** — `map[string]string` (hash → path) with reverse index (path → hash) for O(1) updates. Built on startup, updated incrementally on Write/Archive
- **Hash-based FETCH** — `isHashPath()` detects the pattern, `handleFetchByHash()` resolves and serves
- **Reserved path enforcement** — `/sha256-<64hex>` rejected on PUBLISH, APPEND, ARCHIVE, VERSIONS, LIST
- **SPEC Section 12** — full spec including Section 12.1 on agent-driven hash discovery via hubs
- **Agent workflow documented** — agents crawl servers, collect hashes, publish index documents to hubs for DHT-like discovery

### Security Hardening from Review

- **Symlink escape defense** — `BuildHashIndex` resolves symlinks via `EvalSymlinks` and validates containment within content root before reading
- **Stale index handling** — `handleFetchByHash` returns `not-found` (not server error) when index points to a missing document
- **`chain-error` path leak fixed** — was exposing raw filesystem paths to unauthenticated clients, now returns generic message (full error logged server-side)
- **File size guard** — `BuildHashIndex` checks `os.Stat` size before `ReadFile` to prevent OOM on oversized files
- **Used `isArchived()` parser** — replaced raw `bytes.Contains` substring match with proper frontmatter parser
- **Walk uses `absRoot`** — fixed potential issue with relative `s.root` paths breaking containment checks

### Code Quality

- Extracted `resolvedRoot()` method and `isContained()` helper — eliminated duplicated root resolution and containment logic between `resolve()` and `BuildHashIndex()`
- Added reverse index (`pathIdx map[string]string`) — `UpdateHashIndex` and `RemoveHashEntry` are O(1) instead of O(n) map scan

### Key Design Insight

Servers stay simple — serve content, answer hash lookups. Agents own discovery. Hubs are just servers hosting index documents. No DHT protocol, no crawling, no special infrastructure. The protocol provides the primitive; agents build the intelligence.