Add complete read-only per-file Version history

[jerelvelarde]

Problem and behavior

The local task/attachment example needs every retained Version without creating one. The whole-root journal omits some Versions installed through Change Sets, while version capture can write and recover state.

Add experimental folderbase.file-history@0.1.0: Rust read_file_history(root, path), CLI version list ROOT PATH --json, and Node SDK client.fileHistory(root, path). Return complete Object-stored Version metadata with canonical path and exact recorded timestamps. An untracked existing file returns null IDs and an empty list. Missing files are refused; recorded head is not a claim about current file bytes or blob recoverability.

The reader uses retained read-only state and an optional existing nonblocking shared lock. It creates no lock/layout, captures nothing, and never repairs or replays. Bounded records/names/results fail instead of truncate. It preserves path/alias/duplicate/corruption/transfer checks and revalidates observed authority before returning.

Explicit first-version limitation: roots with any migration metadata, including completed migrations, return file_history_migration_state_unsupported. Existing migration validation can repair staging, so this reader never invokes it. This refusal is not a recovery instruction. Full contract and limits: docs/file-history-0.1.md.

Closes #95. Stacked on #93; existing writer behavior and prior capabilities stay unchanged except extracting the same private path-match decision for reuse.

Validation

Independent source review: no blockers at 1430dd280c36c8945465f5ff260da4e84adc4f07.

• 12 focused Rust tests passed: complete metadata, read-only permissions, untracked/missing state, pending/torn refusal, corruption/duplicate/foreign/oversized records, early serialization refusal for deeply nested metadata, deterministic observation races, writer lock, CAS, completed/staged migration no-write refusal, and completed transfer ownership.
• Public capability runner: 4/4 passed, including Change Set-created JSON and binary attachments, exact complete/current Version metadata, CAS continuation and whole-tree no-mutation assertions.
• Final pinned local gates passed: policy, naming, formatting, strict Clippy and full workspace (1,127 passed, zero failed, three ignored).
• Public CLI JSON conformance: 108 cases; advertised optional capabilities: 8/8 profiles; runner/registry self-tests: 13 passed.
• SDK: 11 runtime tests and TypeScript passed. Fresh extracted Cargo packages, installed CLI and packed SDK passed outside the checkout, including the real-Core journey and file-history profile.
• Locked optimized binary SHA256: 19246f70eb294ff68ddee03929db96fcd2333547f85dd8c7335cd6aedd45c57d.
• Remote CI passed Linux Core, Rust quality, documentation, npm distribution and fresh package installation on the reviewed pin. The PR policy skips the platform matrix; separate combined-source platform validation remains outside this PR's completed evidence.

This remains a draft for integration review.

No app binary repin, public release, or deployment is included.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
folderbase-docs	Ignored	Preview	Sep 15, 2026 2:31am UTC