epic(scrybe-core): object addressability — stable IDs over the AST

[hartsock]

Part 1 of the Conversational Document Editing arc — see docs/design/vision-conversational-editing.md. Foundation epic; grounding (Part 2) and patch-oriented editing (Part 3) both depend on it.

Goal

Give every meaningful document element a stable identity so conversation can refer to objects ("Figure 2", "the installation section") instead of brittle line numbers or fuzzy search.

Decision (vision doc §3 — already made)

• A — derived IDs for coarse named structure: heading slugs, captioned figures, tables, fenced code/mermaid blocks. Zero file pollution.
• C — sidecar .scrybe/ index for fine-grained / ephemeral anchors (an arbitrary paragraph, bullet, or range), re-synced by the fs-watcher. Disposable derived state — never the source of truth.
• B — embedded {#id} / <!-- scrybe:id --> anchors opt-in only; never written automatically.

Scope

• Stable-ID scheme over the scrybe-core AST.
• document.outline() MCP + CLI surface exposing the ID tree.
• Sidecar anchor store + re-sync on disk change; unresolvable anchors degrade to the nearest enclosing heading.
• Rename → alias/redirect so older references (and conversation history) still resolve.
• Lazy assignment of fine-grained IDs (on first reference), not eager per-paragraph.

Builds on

• epic: MCP rebuild — shared scrybe-tools ToolSpec registry #122 (MCP rebuild) — registers these tools on the progressive-disclosure surface.
• Mermaid provenance (UUID + SHA256 in PNG/SVG metadata) already proves the "identity in metadata, source stays plain" pattern.

Open questions (vision doc §6)

• Sidecar format + anchoring algorithm across external edits / merge conflicts.
• Derive-only vs. cache coarse IDs for rename continuity (leaning: derive + cache aliases only).

Acceptance

• document.outline() returns a stable ID tree for headings / figures / tables / code+mermaid blocks.
• IDs survive inserts/deletes above them (sidecar) or are deterministically re-derivable (coarse).
• Deleting .scrybe/ leaves the document intact; coarse IDs regenerate.

Milestone: ~v0.8 (after the #122 MCP rebuild).