AZ-019 — Concrete Vault Manifest Schema v1

Status

Acest document transformă modelul din AZ-018 într-o schemă concretă pentru manifesturile vault-ului.

AZ-018 a definit:

• vault-ul securizat,
• identitatea artefactelor,
• admission gate,
• jurnalul hash-chained,
• quarantine,
• snapshots,
• recovery.

AZ-019 răspunde la întrebarea: cum arată exact manifestul canonical care leagă artefactele, loturile, snapshot-urile și supersession-urile într-o stare verificabilă a vault-ului?

Scopul documentului este să fixeze:

• tipurile concrete de manifest;
• schema câmpurilor;
• regulile de serializare canonicală;
• regulile de validare;
• calculul rădăcinilor;
• regulile de compunere între manifesturi;
• regulile de supersession și revocare;
• integrarea cu jurnalul și snapshot-urile.

Acest document se bazează pe:

• AZ-002 până la AZ-018, cu accent direct pe AZ-018.

Termeni:

• MUST = obligatoriu
• MUST NOT = interzis
• SHOULD = recomandat puternic
• MAY = opțional

1. Obiectiv

AZ-019 răspunde la 10 întrebări precise:

1. Ce tipuri de manifest există în vault?
2. Ce câmpuri are fiecare manifest?
3. Cum sunt identificate artefactele în manifest?
4. Cum se calculează manifest_id și manifest_root?
5. Cum se validează un manifest?
6. Cum se leagă un manifest de manifesturile anterioare?
7. Cum se exprimă supersession, revocare și snapshot membership?
8. Cum se detectează inconsistențe și coruperi?
9. Cum se reconstruiește o stare de vault din manifesturi?
10. Cum evităm manifesturi ambigue, duplicate sau incomplete?

2. Principii

2.1 Manifest is canonical truth layer

Manifestul nu este doar listă de fișiere. Este stratul canonical care spune:

• ce artefacte există,
• în ce stare sunt,
• în ce lot,
• cu ce identitate,
• în ce relație față de alte artefacte.

2.2 Manifest over filename

Numele fișierelor sunt auxiliare. Adevărul vault-ului este dat de:

• artifact_id
• relațiile din manifest
• hash-urile canonice
• jurnalul și snapshot-urile asociate

2.3 Append and supersede, not overwrite

Manifesturile SHOULD modela evoluția vault-ului prin:

• append,
• supersession,
• revocation, nu prin rescriere tăcută.

2.4 Deterministic root derivation

Aceeași colecție de intrări și aceleași reguli MUST produce aceeași rădăcină de manifest.

2.5 Rebuildability

Din manifesturi + jurnal + snapshots verificate, starea vault-ului SHOULD putea fi reconstruită complet.

3. Manifest families

Vault-ul SHOULD suporta cel puțin aceste familii de manifest:

1. MF_ARTIFACT_BATCH
2. MF_FOLDER_STATE
3. MF_SNAPSHOT
4. MF_RELEASE
5. MF_REVOCATION
6. MF_SUPERSESSION
7. MF_RECOVERY
8. MF_INDEX_CHECKPOINT

4. Common manifest envelope

4.1 Canonical top-level structure

Toate manifesturile MUST folosi o anvelopă comună:

VaultManifestEnvelope {
  version_major
  version_minor

  manifest_type
  manifest_id
  manifest_root
  parent_manifest_refs
  vault_scope
  created_at_unix_ms
  producer_policy?
  body_hash
  metadata_hash?
}

4.2 manifest_type

Valori permise:

• MF_ARTIFACT_BATCH
• MF_FOLDER_STATE
• MF_SNAPSHOT
• MF_RELEASE
• MF_REVOCATION
• MF_SUPERSESSION
• MF_RECOVERY
• MF_INDEX_CHECKPOINT

4.3 body_hash

body_hash = H("AZ:VAULT_MANIFEST_BODY:" || canonical_manifest_body)

4.4 manifest_id

manifest_id = H("AZ:VAULT_MANIFEST_ID:" || canonical_envelope_without_manifest_id)

4.5 manifest_root

manifest_root = H("AZ:VAULT_MANIFEST_ROOT:" || canonical_envelope || canonical_manifest_body)

4.6 Rule

manifest_id și manifest_root MUST fi recomputabile exact de orice validator al vault-ului.

5. Vault scope

5.1 Need

Un manifest poate acoperi:

• întregul vault,
• un subfolder logic,
• un release bundle,
• un snapshot subset,
• un singur lot de admitere.

5.2 Structure

VaultScope {
  scope_class
  scope_hash
}

5.3 scope_class examples

• global_vault
• release_bundle
• artifact_batch
• constitutional_subset
• genesis_subset
• snapshot_scope
• quarantine_scope
• revoked_scope

5.4 Rule

Orice manifest MUST declara clar scope-ul său.

6. Parent manifest refs

6.1 Purpose

Leagă manifesturile într-o succesiune sau DAG controlat.

6.2 Rule

parent_manifest_refs MAY fi:

• empty pentru primul manifest al unui scope;
• one parent pentru succesiune liniară;
• multiple parents doar dacă tipul de manifest o permite explicit.

6.3 Anti-ambiguity

Dacă există mai mulți părinți, manifestul MUST defini clar semantica combinării lor. V1 SHOULD favoriza un singur părinte pentru simplitate.

7. Common artifact reference entry

7.1 Purpose

Majoritatea manifesturilor referă artefacte. Forma referinței trebuie standardizată.

7.2 Structure

ArtifactRefEntry {
  artifact_id
  content_hash
  canonical_hash
  metadata_hash
  artifact_type
  artifact_tier
  status_class
}

7.3 status_class

Valori permise:

• active
• staged
• quarantined
• superseded
• revoked
• archived

7.4 Rule

Dacă un manifest include un artefact, toate câmpurile sale MUST fi coerente cu ArtifactIdentityRecord.

8. Artifact status model

8.1 Canonical statuses

Starea unui artefact în context de manifest SHOULD fi una din:

• AS_ACTIVE
• AS_STAGED
• AS_QUARANTINED
• AS_REJECTED
• AS_SUPERSEDED
• AS_REVOKED
• AS_ARCHIVED

8.2 Rule

Starea efectivă a unui artefact în vault se determină din:

• cel mai recent manifest relevant de stare,
• plus eventualele manifesturi de supersession/revocare aplicabile.

8.3 Important distinction

Un artefact poate exista fizic în vault și totuși să fie AS_SUPERSEDED sau AS_REVOKED. Nu confundăm existența cu activitatea.

9. MF_ARTIFACT_BATCH

9.1 Purpose

Reprezintă un lot de fișiere admise sau procesate împreună.

9.2 Body structure

ArtifactBatchManifestBody {
  batch_id
  batch_class
  intake_policy_class
  artifact_count
  artifacts: [ArtifactBatchEntry]
  artifact_list_root
  quarantine_refs?
  notes_hash?
}

9.3 ArtifactBatchEntry

ArtifactBatchEntry {
  artifact_ref: ArtifactRefEntry
  ingress_event_hash
  admission_verdict
  admission_policy_class
  supersedes_artifact_id?
  attestation_refs?
}

9.4 batch_class examples

• spec_batch
• release_batch
• fixture_batch
• recovery_batch
• quarantine_intake_batch

9.5 artifact_list_root

Se calculează din intrările ordonate canonical după artifact_id.

9.6 Rule

Manifestul de batch SHOULD fi primul loc unde un artefact apare ca procesat oficial.

10. MF_FOLDER_STATE

10.1 Purpose

Reprezintă starea curentă a unui scope de vault.

10.2 Body structure

FolderStateManifestBody {
  folder_state_id
  scope_ref
  active_artifact_count
  active_artifact_root
  superseded_artifact_root?
  revoked_artifact_root?
  quarantined_artifact_root?
  index_checkpoint_ref?
  policy_state_hash
  notes_hash?
}

10.3 Meaning

Acest manifest spune „care este setul activ de adevăr” pentru un scope.

10.4 Rule

active_artifact_root MUST fi derivat doar din artefactele active în acel scope.

11. MF_SNAPSHOT

11.1 Purpose

Leagă o stare verificată a vault-ului cu jurnalul și indexurile la un moment dat.

11.2 Body structure

SnapshotManifestBody {
  snapshot_id
  covered_scope_ref
  source_folder_state_manifest_ref
  journal_tip_hash
  index_root
  artifact_chunk_root
  physical_layout_hash?
  snapshot_storage_profile
  recovery_instructions_hash?
}

11.3 Rule

Un snapshot valid MUST putea fi folosit pentru rebuild verificabil al stării acoperite.

12. MF_RELEASE

12.1 Purpose

Manifest special pentru bundle-uri de release.

12.2 Body structure

ReleaseManifestBody {
  release_id
  release_class
  target_network_class
  target_chain_id?
  included_artifact_root
  required_artifacts: [ReleaseArtifactEntry]
  release_attestation_refs
  compatibility_hash
  rollout_notes_hash?
}

12.3 ReleaseArtifactEntry

ReleaseArtifactEntry {
  artifact_ref: ArtifactRefEntry
  release_role_class
  required: bool
}

12.4 release_role_class examples

• genesis
• node_binary
• verifier_binary
• conformance_bundle
• config_template
• validator_bootstrap_package
• operator_manual

12.5 Rule

Un release manifest MUST fi strict. Artefactele lipsă sau necoerente invalidează release-ul.

13. MF_REVOCATION

13.1 Purpose

Revocă artefacte compromise, invalide sau retrase.

13.2 Body structure

RevocationManifestBody {
  revocation_id
  revocation_scope_ref
  revoked_entries: [RevokedArtifactEntry]
  reason_class
  authority_policy_ref
  evidence_refs?
  replacement_refs?
}

13.3 RevokedArtifactEntry

RevokedArtifactEntry {
  artifact_id
  revocation_reason_hash
  effective_time_unix_ms
}

13.4 reason_class examples

• integrity_failure
• bad_signature
• malformed_structure
• compromised_release
• superseded_by_security_patch
• policy_violation

13.5 Rule

Revocation MUST be explicit. Deleted-from-folder is not revocation.

14. MF_SUPERSESSION

14.1 Purpose

Modelează înlocuirea legitimă a unui artefact cu altul.

14.2 Body structure

SupersessionManifestBody {
  supersession_id
  supersession_scope_ref
  supersession_entries: [SupersessionEntry]
  reason_class
  authority_policy_ref?
  notes_hash?
}

14.3 SupersessionEntry

SupersessionEntry {
  old_artifact_id
  new_artifact_id
  supersession_class
  compatibility_hash?
}

14.4 supersession_class examples

• revision
• canonical_reformat
• security_fix
• release_replacement
• constitutional_revision
• manifest_correction

14.5 Rule

A supersession manifest MUST NOT create loops. The supersession graph must remain acyclic.

15. MF_RECOVERY

15.1 Purpose

Ancorează o operațiune de recovery validată.

15.2 Body structure

RecoveryManifestBody {
  recovery_id
  source_snapshot_ref
  restored_folder_state_ref
  quarantined_mismatch_root?
  repaired_index_root?
  recovery_reason_class
  recovery_operator_policy?
  recovery_notes_hash?
}

15.3 Rule

Recovery manifest does not invent truth. It points back to trusted snapshot and records the restoration outcome.

16. MF_INDEX_CHECKPOINT

16.1 Purpose

Ancorează indexuri rebuildable.

16.2 Body structure

IndexCheckpointManifestBody {
  checkpoint_id
  covered_scope_ref
  artifact_id_index_root
  content_hash_index_root
  canonical_hash_index_root
  filename_index_root
  supersession_index_root
  attestation_index_root?
}

16.3 Rule

Index checkpoint-ul este derivat. Nu poate contrazice manifesturile de artefact și stare.

17. Ordering rules

17.1 Artifact ordering

Oriunde există listă de artefacte, ordinea canonicală SHOULD fi:

1. artifact_id ascending lexical by bytes
2. if tie impossible, no secondary sort needed

17.2 Manifest entry ordering

Intrările din manifest MUST fi ordonate canonical după cheia lor naturală:

• artifact_id
• old_artifact_id/new_artifact_id pair
• revoked artifact id
• release role + artifact_id etc.

17.3 Rule

No implementation-specific sort is allowed.

18. Root derivation rules

18.1 Generic list root

Pentru o listă de intrări canonicale:

entry_hash_i = H("AZ:VAULT_ENTRY:<ENTRY_CLASS>:" || canonical_entry_i)
list_root = MerkleRoot(entry_hash_0 ... entry_hash_n)

18.2 Empty list root

V1 MUST standardize an EMPTY_ROOT constant:

EMPTY_ROOT = H("AZ:EMPTY_ROOT:")

18.3 Rule

All manifests MUST use same empty-root convention.

19. Manifest body hash derivation

19.1 Rule

Fiecare body de manifest MUST fi serialized canonical și hash-uit separat înainte de envelope.

19.2 Example

artifact_batch_body_hash = H("AZ:MF_ARTIFACT_BATCH:" || canonical_body)
folder_state_body_hash   = H("AZ:MF_FOLDER_STATE:"   || canonical_body)
snapshot_body_hash       = H("AZ:MF_SNAPSHOT:"       || canonical_body)
...

19.3 Purpose

Ajută:

• validation
• debugging
• selective proofs
• manifest family separation

20. Manifest validation pipeline

20.1 Generic pipeline

Orice manifest MUST fi validat în această ordine:

1. canonical decode
2. schema/version check
3. manifest_type known
4. body_hash recomputation
5. parent manifest existence and admissibility
6. artifact reference integrity checks
7. family-specific semantic checks
8. ordering checks
9. root recomputation
10. manifest_id recomputation
11. manifest_root recomputation
12. conflict checks against prior state

20.2 Rule

A manifest failing any stage MUST be rejected or quarantined depending on pipeline role.

21. Family-specific validation rules

21.1 Artifact batch

Must verify:

• each artifact exists or is provided in referenced batch context
• admission verdict values valid
• supersedes target exists if declared
• artifact_list_root matches entries

21.2 Folder state

Must verify:

• all active artifacts exist and are not revoked within same effective state
• roots consistent with active/superseded/revoked subsets
• no same artifact in conflicting status sets

21.3 Snapshot

Must verify:

• source folder state exists
• journal tip exists
• index root exists or empty by rule
• artifact_chunk_root consistent with included active set

21.4 Release

Must verify:

• all required artifacts exist and are active
• release-role uniqueness constraints satisfied where needed
• chain/network compatibility fields valid

21.5 Revocation

Must verify:

• authority path valid
• revoked artifacts exist
• no impossible duplicate revocation semantics in same scope unless allowed

21.6 Supersession

Must verify:

• old and new artifacts exist
• no cycle introduced
• status transitions legal

21.7 Recovery

Must verify:

• source snapshot trusted
• restored folder state exists and is coherent
• quarantine mismatches if declared are consistent

21.8 Index checkpoint

Must verify:

• indexes derivable from source state
• no contradictions with authoritative manifests

22. Conflict model

22.1 Manifest conflicts

Two manifests conflict if they assert incompatible truths about same scope and time relation without supersession/revocation rule.

22.2 Examples

• same artifact simultaneously active and revoked in same effective state
• two release manifests both declaring same role fulfilled by incompatible artifacts without version separation
• two folder state manifests as latest for same scope with different active roots and no parent relation
• supersession loop

22.3 Rule

Conflict detection SHOULD happen before manifest becomes active truth.

23. Effective truth model

23.1 Need

Many manifests may coexist historically. Need rule for current truth.

23.2 Current truth derivation SHOULD use:

1. latest valid folder state for scope
2. plus applicable supersession manifests
3. plus applicable revocation manifests
4. plus any recovery manifest establishing current restored state
5. plus snapshot manifest only as checkpoint, not state mutator

23.3 Rule

Release manifests and index checkpoints do not define truth of artifact activity by themselves. They consume it.

24. Manifest activation model

24.1 Simple vault contexts

A manifest may become effective immediately upon admission.

24.2 Controlled contexts

Critical manifests SHOULD require:

• attestation
• policy approval
• or signed batch acceptance before being treated as active.

24.3 Rule

TIER_3 and TIER_4 scopes SHOULD prefer explicit activation rather than implicit admission-only truth.

25. Attestation linkage

25.1 Need

Some manifests, especially critical ones, need approval provenance.

25.2 Structure

A manifest MAY refer to:

• artifact attestation refs
• manifest attestation refs
• release approval refs
• security review refs

25.3 Rule

Attestations are auxiliary evidence of trust and approval. They MUST NOT change manifest_root, except by being explicitly referenced in body where required.

26. Supersession graph rules

26.1 Graph properties

Supersession graph MUST be:

• acyclic
• scope-consistent
• artifact-identity consistent

26.2 Multi-step supersession

Allowed: A -> B -> C

26.3 Illegal example

A -> B and B -> A

26.4 Rule

A current active artifact SHOULD be derivable as the terminal active node in its supersession line unless revoked.

27. Revocation graph rules

27.1 Revocation is terminal by default

If an artifact is revoked, it remains historically present but normatively inactive.

27.2 Replacement after revocation

Replacement MUST happen through separate active artifact plus optional supersession/replacement linkage.

27.3 Rule

Revocation SHOULD NOT silently imply replacement.

28. Snapshot trust rules

28.1 Snapshot is checkpoint, not free truth

Snapshot manifest derives trust from:

• source folder state
• journal tip
• index consistency
• its own manifest validation

28.2 Rule

A snapshot MUST NOT override folder state semantics. It only packages a recoverable checkpoint of them.

29. Index checkpoint semantics

29.1 Derived-only

If an index checkpoint contradicts folder state or artifact manifests, folder state wins.

29.2 Rule

Indexes are convenience views. Never authority over artifact truth.

30. Folder state compaction

30.1 Need

Without compaction, long manifest chains become heavy.

30.2 Model

A new folder state manifest MAY compact prior history into current roots.

30.3 Rule

Compaction MUST preserve:

• active artifact set
• superseded set where still relevant
• revoked set where still relevant
• traceability through parent refs or summary hashes

31. Manifest signatures and approvals

31.1 Recommendation

Critical manifests SHOULD be signed or attested.

31.2 Possible classes

• approved_batch_manifest
• approved_folder_state
• approved_release_manifest
• approved_recovery_manifest
• approved_revocation_manifest

31.3 Rule

For TIER_4 artifacts and scopes, unsigned manifest activation SHOULD be forbidden or tightly restricted.

32. Concrete schema for artifact batch entries

32.1 Canonical entry

ArtifactBatchEntry {
  artifact_id: hash32
  content_hash: hash32
  canonical_hash: hash32
  metadata_hash: hash32
  artifact_type: ascii_string(max=32)
  artifact_tier: uint8
  admission_verdict: uint8
  admission_policy_class: ascii_string(max=32)
  ingress_event_hash: hash32
  supersedes_artifact_id: hash32?
  attestation_root: hash32?
}

32.2 admission_verdict values

• 1 = admit
• 2 = admit_with_attestation
• 3 = stage_only
• 4 = quarantine
• 5 = reject
• 6 = supersede_existing

33. Concrete schema for folder state entries

33.1 Active entry

FolderActiveEntry {
  artifact_id
  canonical_hash
  artifact_type
  normalized_name_hash
  current_status
}

33.2 Superseded entry

FolderSupersededEntry {
  old_artifact_id
  new_artifact_id
  supersession_manifest_ref
}

33.3 Revoked entry

FolderRevokedEntry {
  artifact_id
  revocation_manifest_ref
}

34. Concrete schema for release entries

34.1 Release artifact entry

ReleaseArtifactEntry {
  artifact_id
  release_role_class
  required
  compatibility_hash
}

34.2 Rule

Within one release manifest, release_role_class SHOULD be unique for roles that expect single artifact occupancy.

35. Manifest chain integrity

35.1 Need

A single valid manifest is insufficient if chain links are broken.

35.2 Rule

For any active manifest chain, system SHOULD be able to verify:

• all referenced parents exist
• no cycles in parent refs
• scope evolution is legal
• no impossible branch merge occurred

35.3 Chain tip

A scope SHOULD have one active chain tip at a time, unless branching is explicitly allowed for staging or quarantine scopes.

36. Active scope tip model

36.1 Tip registry

Vault SHOULD keep a derived registry:

ScopeTipRegistry {
  scope_ref -> latest_active_manifest_id
}

36.2 Rule

Tip registry is derived. If inconsistent with manifest chain, manifest chain truth wins after rebuild.

37. Recovery from manifest corruption

37.1 Cases

• one manifest body corrupted
• parent ref missing
• root mismatch
• orphan active manifest
• chain fork without allowed semantics

37.2 Recovery guidance

1. verify manifests backward from latest trusted snapshot
2. isolate corrupted manifest(s)
3. rebuild scope tip from last trusted valid chain point
4. quarantine downstream dependent manifests if necessary
5. generate recovery manifest if restoration performed

37.3 Rule

Recovery MUST prefer older valid manifest truth over newer unverifiable manifest state.

38. Cross-scope references

38.1 Need

Some manifests may refer across scopes:

• release manifest referring to artifact batch
• snapshot manifest referring to folder state
• recovery manifest referring to snapshot

38.2 Rule

Cross-scope refs MUST be explicit and validatable. They MUST NOT create hidden dependency cycles that obscure current truth.

39. Manifest anti-patterns

Systems SHOULD avoid:

1. manifest bodies depending on external text notes
2. artifact lists unsorted or sorted by filename only
3. implicit supersession inferred from timestamps
4. revocation by deletion
5. release manifest without required artifacts marked
6. snapshot without journal tip anchoring
7. folder state manifest with mixed conflicting status entries
8. index checkpoint treated as source of truth
9. parent refs that create DAG merges without semantic rules
10. multiple unofficial equivalent encodings of same manifest

40. Formal goals

AZ-019 urmărește aceste obiective:

40.1 Manifest determinism

Aceleași intrări și aceleași reguli produc același manifest_root.

40.2 Manifest completeness

Manifesturile conțin suficientă structură pentru a reconstrui starea relevantă a vault-ului.

40.3 State consistency

Nu există ambiguitate despre care artefacte sunt active, superseded, revoked sau quarantined.

40.4 Recovery support

Manifest chain-ul poate susține recovery verificabil fără a inventa adevăr nou.

41. Formula documentului

Concrete Vault Manifest = canonical envelope + typed manifest body + ordered artifact entries + deterministic roots + explicit supersession/revocation semantics

42. Relația cu restul suitei

• AZ-018 a definit vault-ul securizat conceptual.
• AZ-019 definește schema concretă prin care acel vault își reprezintă adevărul intern.

Pe scurt: AZ-018 spune că trebuie să existe manifest chain; AZ-019 spune exact cum arată.

43. Ce urmează

După AZ-019, documentul corect este:

AZ-020 — Artifact Signing and Attestation Policy

Acolo trebuie fixate:

• cine poate semna ce artefacte,
• ce clase de semnătură există,
• ce artefacte cer review, approval sau dual attestation,
• și cum se validează proveniența înainte de admitere în vault și release.

Închidere

Un vault cu hash-uri, dar fără manifest schema concretă, rămâne doar o intenție bună. Un vault real are:

• anvelopă canonicală,
• intrări ordonate,
• rădăcini deterministe,
• stare activă clară,
• supersession și revocare explicite,
• și chain de manifesturi suficient de clar încât recovery-ul să nu devină improvizație.

Acolo începe organizarea verificabilă a artefactelor.