Skip to content

feat(core): add metadata-only Folderbase capture planning - #25

Merged
jerelvelarde merged 7 commits into
mainfrom
codex/tb33-capture-plan
Jul 29, 2026
Merged

feat(core): add metadata-only Folderbase capture planning#25
jerelvelarde merged 7 commits into
mainfrom
codex/tb33-capture-plan

Conversation

@jerelvelarde

Copy link
Copy Markdown
Contributor

Summary

  • add controlled, bounded JSON encoding for fully validated Folderbase Versions
    while keeping raw FolderbaseVersion deserialization non-public
  • add crate-private verified producer construction for every v1 record shape
  • add a read-only FolderbaseVersionStore::open and opaque metadata-only
    CapturePlan bound to one attested root and its optional current Local Head
  • traverse through retained, no-follow directory capabilities with bounded
    records, depth, paths, object sizes, and identity rechecks
  • preserve nested Folderbases as typed boundaries and treat PDFs, video, CSV,
    SQLite, Git packs, unknown files, and a 10 GiB sparse file as opaque metadata
  • implement ordered Git-style .folderbaseignore rules, Core generated defaults,
    negation, required-marker overrides, protocol-state exclusion, and pre-descent
    pruning
  • preindex folded nested boundaries so symlink validation probes at most the
    resolved path's 128 component ancestors instead of scanning every boundary
  • document the proposal in ADR-0005, the protocol spec, context, and verification
    evidence

Why

TB-33 establishes the safe read-only planning seam required before any future
capture transaction can seal content or move Local Head. Planning must describe
the real workspace without reading opaque payloads, following links, crossing
nested Folderbase boundaries, or letting inventory size create unbounded work.

Truth boundary

This PR implements only phases 1–3: controlled Folderbase Version encoding,
read-only store/open and metadata planning, and ignore-policy planning.

It does not seal a Folderbase Version, read or persist object payloads, mutate
Local Head, restore content, claim snapshot atomicity or database consistency,
implement sync/cloud/sharing/authorization, or change ADR-0005 from Proposed.

TDD and review evidence

  • RED first covered the missing encoder, store/plan types, ignore semantics,
    nested boundaries, 10 GiB metadata planning, producer seam, symlink-root
    rejection, capability traversal, and the missing bounded boundary index.
  • The adversarial boundary regression builds 8,192 boundaries and proves a
    maximum-depth target performs exactly 128 ancestor probes.
  • Independent spec review: GO, no P1/P2 findings.
  • Independent standards review at exact head 3d896e2: GO, no P1/P2 findings;
    all five original traversal/security/performance findings are closed.

Verification

  • cargo test --workspace --all-features --locked
  • cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
  • RUSTDOCFLAGS="-D warnings" cargo doc --workspace --all-features --no-deps --locked
  • cargo check --package folderbase-core --lib --target x86_64-pc-windows-msvc --locked
  • CARGO_NET_OFFLINE=true scripts/test-package-install.sh
  • focused capture (15), Version conformance (14), producer, capability, and
    boundary-index tests
  • formatting, diff, CI-policy, public-eclipse, digest-vector, and distribution
    checks

Base: 7f873d1c4fef43d9fb9a1a1385a2f5c314119b75
Head: 3d896e266f5857faed8743f74adbd029e6ef75cf

@jerelvelarde
jerelvelarde merged commit 8dda562 into main Jul 29, 2026
3 checks passed
@jerelvelarde
jerelvelarde deleted the codex/tb33-capture-plan branch July 29, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant