feat(snapshot): monorepo versioning spec and immutable source reader

[Ivanbeethoven]

Summary

Start with the concise Chinese design overview: docs/versioned-readonly-layer-design.md. It focuses on one rule: each workspace pins one complete Mega version; detailed protocol terminology stays in linked implementation specs.

The client design now includes missing-object batching into tar+zstd packages, per-object cache reuse across versions, bounded prefetch, and a separate large-file range reader. It follows the shared Mega transfer spec. These are proposed client changes, not implemented mount capabilities.

Draft review checkpoint for ScorpioFS/Mega version management. Not ready to merge as end-to-end versioned mounts. This PR is part of the full delivery, not a reduction to the library-only slice.

• Refine the system-paper roadmap and monorepo versioning spec, including native/import/aggregate routing, source/view/generation identities, immutable lower layers and controlled-update recovery.
• Add strict typed source descriptors, canonical framed SHA-256 identities and independent golden vectors shared with Mega.
• Add strict namespace view/binding identity codecs, independent .NET golden vectors shared with Mega, and the confirmed immutable-release policy in the spec.
• Add a fixed-source SourceReader that traverses immutable trees, asks its backend for source/path/kind/OID, enforces object limits and verifies Git object hashes.
• Preserve executable and symlink semantics, reject unsupported submodule traversal, and keep missing/forbidden/expired/unavailable/integrity failures distinct.

The HTTP adapter sends fixed descriptor/path context with sensitive access-token and lease headers, rejects redirects/partial/non-object responses, bounds streamed downloads and redacts transport errors. Existing Dicfuse/Antares mounts are not yet wired to it and retain their old behavior. Mega snapshot routes are not exposed yet. No new production capability is advertised.

Research design

The research plan separates transport format from candidate contributions, records relevant prior systems and REAPI, and defines correctness invariants, a proposed bounded transfer selector, falsifiable hypotheses and controlled baselines/ablations. Package-count examples now explicitly require known or concurrent demand. This is an experimental plan, not evidence of novelty or measured performance.

Validation

Transfer-design documentation: JSON examples, relative links, example arithmetic and whitespace checks passed. No transfer implementation or performance benchmark is claimed by this documentation update.

Local WSL Ubuntu 24.04 checks:

• cargo test --lib snapshot --locked -j 1 — 24 tests passed, including 6 HTTP adapter tests and 5 shared namespace codec tests; object fixture OIDs obtained with git hash-object --stdin, without writing Git objects.
• cargo clippy --lib --locked -- -D warnings — passed.
• cargo fmt --all --check — passed.

Tests cover delayed reads after a newer fixture exists, source isolation, root-relative paths, modes/symlinks, failed backend requests, hash corruption, malformed trees and byte limits. They do not replace real server/FUSE, lease, CAS, update or crash-recovery tests.

Remaining full-delivery gates

• D1 confirmed: full atomic native + import namespace delivery; not a source-only reduction.
• D4 confirmed: default-off snapshot APIs; explicit source/scope authorization and retention configuration required before enablement.
• D2 confirmed: explicitly marked release directories are immutable after first publication; ordinary development bindings may evolve.
• Confirm D3: workspace switch semantics.
• Implement and benchmark the documented small-package and large-file chunk transport, including authorization, limits and interrupted-download recovery.
• Integrate the HTTP adapter with real Mega capability discovery, current authorization and retention services.
• Wire immutable readers into Dicfuse/Antares and isolate metadata/content caches by version and access domain.
• Consume atomically published Mega native/import namespace bindings.
• Add leases/CAS reachability, controlled workspace updates and durable recovery.
• Verify two concurrent versions with real mounts and a Git oracle; complete remaining acceptance gates before ready-for-review.

Related: #55, #42, #43 and #44. These remain open; this PR does not claim their full completion.

Companion Mega draft: gitmono-dev/mega#2181.

No existing workspace/layer directories were deleted or switched. The system-paper optimization and full experiment programme are separately tracked, not automatically included here.