preservelib co-evolution: manifest-backed operations as a filekit API

[djdarcy]

Summary

Coordinate filekit's v0.3.0 Layer 1 API with preservelib's manifest
system so that data.copy(..., manifest=True) produces manifests that
are fully interoperable with standalone preservelib usage.

This is the architectural handshake between filekit's workflow layer
and preservelib's established manifest format. Neither should have to
hack around the other.

Context

preservelib today is the canonical manifest writer for
copy-with-verification workflows. It defines a JSON schema for
manifests (with fields for source paths, hashes, metadata, timestamps)
and provides read/write helpers.

In v0.2.4, filekit ported preservelib's rich metadata module
byte-identically into dazzle_filekit.metadata. The workflow layer
(manifests, restore, incremental sync) stayed in preservelib.

v0.3.0 adds a workflow-ish layer in dazzle_filekit.data. That layer
needs to write manifests when the caller asks for manifest=True.
The question is: how?

Options

Option A: filekit calls into preservelib

dazzle_filekit.data.copy(..., manifest=True) uses
try: from preservelib import manifest to write a preservelib-format
manifest. If preservelib isn't installed, either raise or fall back
to a minimal filekit-native manifest format.

Pros: maximum compatibility with existing preservelib tools;
filekit doesn't duplicate the manifest format.
Cons: couples filekit release cadence to preservelib's schema
versioning; needs graceful fallback for users who only install filekit.

Option B: filekit defines its own minimal manifest, preservelib reads it

filekit writes a small manifest schema natively
(atomic_write_json + a schema definition). preservelib treats
filekit manifests as a subset of its own format and can extend them
as needed.

Pros: filekit stays decoupled; no import-time dependency on
preservelib; users get manifests without installing preservelib.
Cons: two schemas to maintain; preservelib has to know how to
upgrade filekit-minimal manifests to its full format.

Option C: shared manifest schema in a third package

Extract the manifest schema into a tiny shared package
(dazzle-manifest-schema or similar) that both filekit and
preservelib depend on.

Pros: clean layering; neither package depends on the other.
Cons: adds a third package to maintain; Premature Factor™.

Recommendation

Start with Option A (filekit calls preservelib via try-import),
with a minimal filekit-native fallback for users who don't want the
full preservelib install. This gives us the best compatibility story
for v0.3.0 and defers the schema-refactor decision.

If schema divergence becomes a real problem in v0.3.1+, revisit and
consider Option C.

Acceptance criteria

• data.copy(src, dst, manifest=True) produces a preservelib-
  compatible manifest when preservelib is installed
• When preservelib is NOT installed, manifest=True either raises
  a clear error OR falls back to a minimal filekit-native schema
  (gated by a manifest_format: Literal["preservelib", "minimal"]
  parameter, default "preservelib")
• The filekit-minimal manifest is a strict subset of preservelib's
  format so that a preservelib read path can handle both
• Documentation explains the tradeoff and the install-hint path
• Tests verify both the preservelib-installed and the
  preservelib-missing code paths

Dependencies

• Blocked by: #N+3 (optional-peer integration pattern), #N+1
  (data submodule)
• Coordinates with: preservelib upstream -- may need a preservelib
  issue to confirm API contracts for the schema version used

Non-goals

• Not reconciling the upstream preservelib (C:\code\preserve\)
  with safedel's diverged rich copy. That's a separate track.
• Not folding preservelib into filekit as a dazzle_filekit.workflow
  submodule. That's a v0.4.0+ architectural question.