Local Artifact Vault and Durability Classes

1. The problem: local presence is not durability

Assume release-final.zip exists in a project folder, another copy is synchronized to a second local volume, and an older checksum file sits beside them. If the bytes changed after that checksum was written, both copies depend on the same machine, and no current verification exists, “we have two copies” is not an auditable durability claim. CON-019 turns that ambiguity into an explicit vault ledger.

2. The owned CON-019 boundary

This lesson owns the Local Artifact Vault Ledger & Durability Policy v1: exact content identity, storage locations, durability class, retention, replicas and failure domains, verification, corruption, eviction, and restore evidence. Presigned transfer belongs to CON-020; human handoff closure and provenance round-trip belong to CON-021. Those outcomes stay outside this lesson.

3. Separate logical artifact identity from pathname

artifact_id names the logical artifact the workflow is tracking; vault_path is only the current location of one copy. Moving unchanged bytes must not create a new artifact. Changing bytes under the same filename must create a new content state. Vault decisions therefore bind artifact_id + digest + byte_size instead of trusting a name or path.

4. The content-addressable pattern and its limit

The OCI Image Layout provides a standards-based content-addressable pattern: blob paths include an algorithm and encoded digest, and blob content must match that digest. MAKNOW borrows this only as a byte-identity pattern; the vault is not declared to be an OCI Image Layout. A digest also does not prove retention, rights, approval, or successful backup.

5. Durability class is policy, not a path property

This lesson uses example classes EPHEMERAL, CACHE, WORKING, RETAINED, and ARCHIVE. That taxonomy is MAKNOW design, not an OCI or BagIt requirement. Each class must state its retention expectation, healthy-replica requirement, failure-domain expectation, verification cadence, and whether a restore test is required.

6. Bind retention to a policy version

Record retention_policy_id and retention_until with the artifact state. Shortening retention for cache derivatives must not silently shorten the retained source artifact's policy. When policy changes, append a new event rather than rewriting prior decisions, so an auditor can reconstruct which rule applied at each point in time.

7. A replica count without failure domains can mislead

Two paths on one disk, two directories on one host, or a mirror sharing the same failure domain are not automatically independent durable replicas. For classes that require multiple failure domains, record both replica_id and replica_failure_domain. Counting visible files alone can manufacture false confidence.

8. Verification must be current and attributable

last_verify and verify_result show which replica was checked, when, and against which digest. A checksum produced before a byte change is stale evidence. If verification is stale or unknown, preserve UNVERIFIED or DEFER; do not convert file presence into a green state.

9. Promotion to a stronger class

Promotion from WORKING to RETAINED or ARCHIVE is not a label edit. Check exact artifact binding, retention policy, healthy replica count, failure-domain independence, current verification, and restore evidence when the target class requires it. The promotion event should capture time, policy version, and reason for later audit.

10. Corruption does not erase history

When one replica becomes corrupt, mark that replica CORRUPT and stop counting it toward the durability obligation. Do not erase the artifact's historical provenance, former locations, or earlier verification events. Storage corruption is a new event, not permission to rewrite history.

11. Eviction is policy-aware

A cache object may be past its retention window while a downstream release still references its digest. Eviction must then be blocked until the reference/policy conflict is resolved. For retained artifacts, “disk is full” is not enough either; eligibility comes from policy and dependencies, and the removal event remains auditable.

12. Restore tests for archival classes

A backup claim without restore evidence can be misleading. If ARCHIVE requires a restore test, bind a PASS result to the artifact version, replica, and test time. FAIL or UNKNOWN must limit promotion or reliance until repair occurs; a green report without an actual restore test is insufficient.

13. What BagIt contributes

RFC 8493 defines payload manifests as complete listings of payload paths with checksums, and a valid bag is complete with every manifest checksum successfully verified against its file. That pattern supports package completeness and integrity. It does not define MAKNOW durability classes, backup topology, rights, or project approval.

14. Lab: build a vault ledger from deterministic evidence

lab://CON-019/CON019-LAB1 provides eight synthetic fixtures: a valid baseline, bytes changed under the same filename, two copies in one failure domain, a corrupted replica, a path move with unchanged content, eviction with an active downstream reference, a failed restore, and the transfer case. Derive eight output states only from fixture evidence; the reference answer is not placed in the learner tree.

15. Transfer and decision checklist

In the transfer case, the logical artifact_id stays the same, one replica becomes corrupt, the surviving copy moves to a new path, and cache-derivative retention is shortened. If the retained source still requires two healthy failure domains, neither the path move nor the cache policy change can satisfy that missing replica obligation. The final decision must say what is proven, what remains unsupported, what repair is required, and what triggers recheck.