EPIC: The DazzleLib stack -- five-domain layer contract for unctools / filekit / dazzlelinklib / preservelib / dazzletreelib #3

Problem

Five codebases implement overlapping file/link/metadata functionality, and the same capabilities keep getting rebuilt because no layer contract says where each belongs:

• dazzlelink (tool) reimplements UNC<->drive mapping, path normalization, timestamp/attribute handling, and checksums -- all of which exist in dazzle-filekit/unctools. Its own issue tracker contains a filed-but-unexecuted plan to delegate.
• preservelib exists only embedded inside the preserve CLI, plus two drifting vendored copies (safedel, ghtraf). The canonical copy carries a stale 883-line metadata.py and a known junction-detection bug that dazzle-filekit already fixed.
• Junction and hardlink creation exist only in preservelib (via cmd /c mklink -- a known-bad pattern); dazzle-filekit, the declared primitives home, has neither.
• A latent dependency cycle: filekit's create_symlink soft-imports dazzlelink, while dazzlelink plans to depend on filekit.
• Name collisions with different semantics across libraries (get_path_type, normalize_path).

Proposed solution

A five-domain layered stack with one home per capability and dependencies that only point down:

Rules: every capability has exactly one home; sibling imports are real dependencies (graceful fallback reserved for platform capability only); libraries live in DazzleLib, CLI tools in DazzleTools and consume the libraries.

The full class map, capability-ownership table, Mermaid dependency chain, and open decisions live in the STACK-MAP golden-rule document (maintained privately while iterating; graduates to this org repo on design freeze).

Phases

• D -- Design freeze: iterate the STACK-MAP until approved; no implementation before freeze
• 0 -- dazzlelink midstream completion (forked work stream): finish the in-flight packaging migration (monolith -> legacy/, pyproject layout), publish 0.7.0
• P1 -- filekit 0.3.0: complete the link primitives (junction/hardlink creation, link analysis with the fixed junction detection, absorb elevation-aware symlink creation; kill the filekit->dazzlelink soft-import)
• P2 -- dazzlelinklib extraction: format + serialization core becomes a library; the CLI tool thins to a consumer; UNC/timestamp/checksum code delegates down
• P3 -- preservelib: new repo + PyPI package extracted from the preserve CLI (manifest lifecycle pulled into the library; metadata-persistence and hardlink inode-group gaps become its roadmap)
• P4 -- consumer migrations: preserve CLI, safedel (drops _lib junction), ghtraf (unvendors), csb (manifest-based recovery tier), dazzlelink tool
• P5 -- polish: dazzletreelib adoption for scan paths, name-collision deprecation aliases

Acceptance criteria

• STACK-MAP approved and published in this org repo as the architecture contract
• Each capability in the ownership table has exactly one implementation across the stack
• All five libraries on PyPI with declared (non-optional) downward dependencies
• The three vendored preservelib copies retired
• All consumer tools build against published libraries only

Related

• DazzleLib/dazzle-filekit (L1 home; docs/preservelib-integration.md + docs/unctools-integration.md are the prior partial contracts this generalizes)
• DazzleLib/UNCtools, DazzleLib/dazzle-tree-lib
• DazzleTools/preserve, DazzleTools/dazzlelink (extraction sources)