docs(vol-1): ch16 prose review — advance to voice-check

[ctwoodwa]

Summary

• Prose review pass (Stage 5): trimmed ch16 from 6,549 to 3,849 words (aggressive structural cut, target was 3,150–3,850)
• Advanced ICM marker from icm/prose-review to icm/voice-check
• Preserved all section headers, named Sunfish package references, YAML bucket spec, both Mermaid diagrams, snapshot JSON structure, export directory tree, and all six references

What was cut (by section)

• Per-Data-Class Device Distribution — cut ~600 words: removed consumer-software analogue comparisons (OneDrive, iCloud, Dropbox), removed MDM audit/observability sub-section, condensed forward-secrecy failure mode and kill-trigger into the other failure modes list
• BYOC backup destination — cut ~150 words: condensed jurisdiction laundry list to representative examples + Appendix F pointer
• Plain-File Export — cut ~350 words: removed two restatement paragraphs (regulatory retention section, Property 5/7 citation duplication), merged manifest.json description into one sentence
• Relay Architecture — cut ~100 words: removed multi-tenant Zone C isolation paragraph, condensed managed relay description
• Non-Technical Disaster Recovery — cut ~80 words: condensed offline recovery fallback, removed restatement of "both paths produce the same end state"
• Snapshot Format — cut ~50 words: condensed scheduling policy paragraph

Test plan

• Word count: 3,849 (target 3,150–3,850) — confirmed in range
• ICM marker: <!-- icm/voice-check --> at top of file — confirmed
• All named Sunfish packages present: Harborline.Kernel.Buckets, Harborline.Kernel.Sync, Harborline.Kernel.Audit, Harborline.Foundation — confirmed
• All six references retained — confirmed
• Both Mermaid diagrams retained — confirmed

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Rewrote and restructured chapters on SaaS architecture and local-first systems for improved clarity and narrative flow.
  • Clarified architecture descriptions, failure modes, and persistence specifications with enhanced emphasis on operational realities.
  • Updated persistence and sync bucket documentation with more explicit user-facing behavior guidance.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fe51b8de-8ef9-4daa-a974-985a6903e4ec

📥 Commits

Reviewing files that changed from the base of the PR and between 5eca771 and 116119f.

📒 Files selected for processing (4)

• vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md
• vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md
• vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md
• vol-1/part-3-reference-architecture/ch16-persistence-beyond-the-node.md

---

📝 Walkthrough

Walkthrough

This PR refreshes four core dissertation chapters on local-first architecture by tightening narratives and clarifying specifications. Chapter 1 sharpens SaaS failure modes and hidden structural constraints. Chapter 2 formalizes local-first stack principles and establishes design boundaries. Chapter 3 details the five-layer architecture with operational specificity and failure-mode consequences. Chapter 16 formalizes persistence mechanisms including sync buckets, device distribution, backup UX, relay design, and export formats.

Changes

Local-First Architecture Documentation

Layer / File(s)	Summary
SaaS Problem Framing and Failure Modes vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Opening scenario and "Bundle Nobody Agreed To" section tightened; all seven failure-mode sections ("Outage," "Vendor That Disappears," "Connectivity That Wasn't There," "Data You Can't Get Back," "Price That Changes," "Drift," "Third-Party Veto") rewritten with updated examples and sharpened claims; closing sections ("The Work That Doesn't Stop," "Who Pays the Most," "Why Users Have Accepted This," "The Dependency That Looks Inevitable") updated to revise narrative specifics and architectural argument summary.
Local-First Stack Principles and Design Space vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Seven-properties framing reworded; "What Exists Today" taxonomy updated with revised emphasis on document sync, CRDT libraries, and local-first finance; new bridging paragraph and rewritten "Full Node, Not Smart Cache" section clarifying authority boundaries, offline behavior, and conflict handling; "What This Book Adds" section expanded to foreground enterprise/compliance realities and enumerates concrete deliverables (architecture, CAP positioning, GC policy, key rotation, schema migration, deployment, business/governance models).
Five-Layer Architecture, Failure Modes, and Developer Impact vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Inversion framing tightened to contrast cloud-primary vs device-primary operation; relay description clarified as optional with direct LAN sync fallback; all five layers rewritten with expanded operational detail (daemon lifecycle via OS service manager, CRDT operation writing, ciphertext-only routing); "How This Changes Failure Modes" updated to align with new layer descriptions; Zone A/C deployment shapes reworded; "What Changes for the Developer" section refreshed with three core habit shifts.
Persistence Layer Specification: Buckets, Distribution, Backup, and Export vol-1/part-3-reference-architecture/ch16-persistence-beyond-the-node.md	Sync buckets reframed around capability-negotiation and formatted as bullet list; lazy-replication clarified with stub model and eviction budget behavior; new/expanded "Per-Data-Class Device Distribution" section adds signed manifests (CBOR, Ed25519), sending-node push filtering, and policy-blocked cross-class references; snapshot/rehydration expanded with full-replay and schema-lens behavior; backup UX rewritten with non-technical user contract and typed state; relay streamlined to emphasize ciphertext-only invariant; disaster recovery adjusted for QR-based key exchange and lazy-stub visibility; plain-file export updated to include manifest.json with format version, timestamp, node identifier, and document counts; export-format list expanded to include binary originals.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Harborline-Software/the-inverted-stack#145: Both PRs modify ch03-inverted-stack-one-diagram.md and ch16-persistence-beyond-the-node.md with overlapping terminology around relay architecture, zone deployment shapes, and persistence specifications.

Poem

🐰 Through five-layer prose the rabbit hops,
SaaS faults unbound, yet now we've mapped,
Local nodes now speak with clarity—
Manifests, buckets, backup care.
The stack inverts, the specs grow tight, 🔐

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch prose/review-ch16

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}