SPEC-008: Watch Mode

Adds persistent file-system monitoring with graph event streaming. See Watch Command for the CLI.

(given spec-008-documented)

Overview

zetl watch starts a persistent process that monitors the vault via OS file system events, incrementally re-indexes changed files, and emits graph-level events as NDJSON on stdout. The event vocabulary mirrors the Diff Command output schema.

Key requirements

ID	Requirement
REQ-053	Watch command entry point
REQ-054	FS event monitoring
REQ-055	Debounced incremental re-index
REQ-056	Merkle tree change detection
REQ-057	NDJSON graph event stream
REQ-058	Event types (page/link/orphan/dead-link added/removed)
REQ-059	`--exec` command invocation
REQ-060	Graceful shutdown
REQ-061	Startup error handling

Design principles

Files are the source of truth
Agent-first (NDJSON on stdout, status on stderr)
Events emitted only on actual graph changes (not every file save)
Fast and disposable

Architecture decisions

ADR-013: Use notify crate for FS events
ADR-014: Inherit SPEC-006 Merkle Tree for change detection
ADR-015: NDJSON on stdout, status on stderr

Performance targets

Event latency: <= 500ms at p95
CPU idle: <= 0.5%
Memory: <= 250 MB

User profiles

Writer monitoring for dead links while editing
Agent running an incremental reasoning loop

Leaf type	Source
Heading	`## Section Title`
Paragraph	Prose text blocks
SplBlock	```spl fenced code blocks
Code	Non-SPL fenced code blocks
Table	Markdown tables
List	Ordered/unordered lists
Blockquote	`>` block quotes
Frontmatter	YAML between `---` fences

Flag	Default	Description
`--from <ref>`	`HEAD~1`	Git ref to diff against
`--since <datetime>`	none	Find closest commit at or before this date
`--filter <category>`	none	Filter output: `pages`, `links`, `orphans`, `dead_links`

Flag	Default	Description
`--debounce <ms>`	200	Debounce interval for batching rapid changes
`--exec <cmd>`	none	Command to invoke after each re-index

Event	Description
`index_ready`	Initial index complete, watching started
`page_added`	New page appeared
`page_removed`	Page deleted
`link_added`	New wikilink appeared
`link_removed`	Wikilink removed
`orphan_gained`	Page became orphaned
`orphan_resolved`	Orphan page got an incoming link
`dead_link_added`	New dead link appeared
`dead_link_resolved`	Dead link target now exists
`index_updated`	Re-index cycle complete (summary)

Spec	Title	Status	Primary Feature
SPEC-001 Link Graph CLI	Bi-directional Link Graph CLI	Implemented	Wikilinks, graph queries, SimHash, cache
SPEC-002 Full-Text Search	Full-Text Content Search	Implemented	`zetl search`
SPEC-003 Agent Ergonomics	Agent Ergonomics & Robustness	Implemented	JSON errors, dedup, list/export
SPEC-004 Distributed Sync	Distributed Vault Sync	Proposed	Goblins sidecar, OCapN
SPEC-005 Defeasible Reasoning	Defeasible Logic over Markdown	Implemented	`zetl reason` (8 subcommands)
SPEC-006 Merkle Tree	Content-Addressed Merkle Tree	Implemented	BLAKE3 hashing, grounding, drift
SPEC-007 Graph Diff	Git-Backed Graph Diff	Implemented	`zetl diff`
SPEC-008 Watch Mode	Vault Watch with Event Stream	Implemented	`zetl watch`
SPEC-009 Xanadu View	Xanadu-Inspired Transclusion TUI	Implemented	`zetl view`

ID	Requirement
REQ-037	Merkle tree construction during index
REQ-038	SPL block dual hashing (content + AST)
REQ-039	Two-tier cache invalidation (mtime + content hash)
REQ-040	SPL-specific theory cache invalidation
REQ-041	Implicit section grounding
REQ-042	Explicit grounding via `(meta ... (source ...))`
REQ-043	Drift detection in `zetl check --drift`
REQ-044	Durable provenance with content hashes
REQ-045	Content block discovery (`zetl blocks`)