dazzle-preservelib

Manifest + operations library -- the L3 orchestration layer of the DazzleLib stack.

It owns the preserve domain: the PreserveManifest (a content-hash record of what was copied, with DAG lineage), transactional copy / move / restore / verify operations, destination-conflict resolution, link-handling policy, and link-mirror reconciliation (linkmirror). It delegates the actual filesystem mechanics down the stack.

What this owns (and what it delegates)

The orchestration and policy live here; the primitives they stand on belong to the layers below. This library is the destination of the P3 extraction that collapses three drifting preservelib copies (preserve, ghtraf, safedel) into one canonical home.

linkmirror -- reconcile links onto a mirrored tree

File-level mirrors (robocopy, Beyond Compare, preserve COPY) carry the files but frequently drop the links: symlinks and junctions vanish, hardlink groups arrive as independent duplicates. dazzle_preservelib.linkmirror is the mirror-scoped implementation of LinkHandlingMode.RECREATE (preserve#48 Phase 2, narrowed to the case that needs no lineage tracking: the destination already holds the copied files, so link identity is same relative path).

from dazzle_preservelib.linkmirror import (
    walk_scan, build_plan, apply_plan, verify_mirror,
)

manifest = walk_scan(r"D:\data")                # or mft.mft_scan (elevated, fast)
plan = build_plan(manifest, r"B:\data")         # diff against the mirror
result = apply_plan(plan, dry_run=False)        # additive-only: creates links,
                                                # restores link + parent times
report = verify_mirror(manifest, r"B:\data")    # byte/tick parity proof

Fidelity contract: targets are recreated verbatim (relative targets unresolved, intentionally-broken targets unrepaired, \\?\ forms kept) with the link's own timestamps at 100ns precision; existing destination entries are never modified (mismatches are reported as conflicts); re-runs are idempotent. Target rewriting (e.g. D:\ -> B:\ for drive retirement) is an explicit pluggable policy (make_prefix_rewrite_policy). Hardlink reconciliation is opt-in and sha256-guarded. The dz link-mirror tool (dazzlecmd) is the thin CLI over this engine.

Scanner backends: a portable os.scandir walk, and a Windows MFT/USN enumeration (linkmirror.mft, requires elevation) that inventories multi-million-record volumes in minutes -- field-proven mirroring 2,644 links off a failing 51M-record drive with nanosecond-identical timestamps and zero additional wear.

The stack

Status

Functional (0.8.0 shipped the P3 extraction; 0.9.0 added linkmirror). The manifest + operations API is locked (see docs/api-stability.md); the preserve CLI consumes this library. The linkmirror package is provisional in 0.9.x (API may still refine; locks at 0.10). See the Roadmap.

Installation

pip install dazzle-preservelib

From source

git clone https://github.com/DazzleLib/dazzle-preservelib.git
cd dazzle-preservelib
pip install -e ".[dev]"

Development

python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Install git hooks
bash scripts/install-hooks.sh

License

MIT. See LICENSE for details. The whole DazzleLib stack is MIT (STACK-MAP D11).