AZ-021 — Secure Build and Release Pipeline v1

Status

Acest document definește pipeline-ul securizat de build și release pentru ecosistemul ATLAS ZERO.

AZ-018, AZ-019 și AZ-020 au fixat:

• vault-ul securizat pentru artefacte,
• schema concretă de manifest,
• politica de semnare și atestare.

AZ-021 răspunde la întrebarea: cum transformăm sursa și documentele aprobate în artefacte executabile și bundle-uri de release fără a pierde proveniența, integritatea, reproductibilitatea și controlul de promovare între stări?

Scopul documentului este să fixeze:

• fazele pipeline-ului de build;
• identitatea și proveniența artefactelor de build;
• politicile de promotion între staging, candidate și release;
• reproducible builds și verificarea lor;
• relația dintre source, manifest, binary, snapshot și release package;
• controalele de securitate;
• blocajele și criteriile de respingere.

Acest document se bazează pe:

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

Termeni:

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

1. Obiectiv

AZ-021 răspunde la 10 întrebări:

1. Cum arată pipeline-ul complet de la source la release?
2. Ce artefacte intermediare există și cum sunt identificate?
3. Cum se dovedește proveniența unui binary?
4. Cum se impune reproducibilitatea?
5. Cum se promovează un artefact din staging în candidate și apoi în release?
6. Ce controale de securitate și policy checks sunt obligatorii?
7. Cum se blochează un build sau un release suspect?
8. Cum se păstrează chain of custody între source, build, manifest și package final?
9. Cum se tratează rollback, supersession și revocation?
10. Cum evităm „release by convenience” în loc de release by proof?

2. Principii

2.1 Build artifacts are security objects

Un binary, un bundle de test sau un pachet de release MUST fi tratat ca obiect de securitate, nu doar ca output de CI.

2.2 Provenance before promotion

Niciun artefact executabil sau normativ MUST NOT fi promovat fără proveniență verificabilă.

2.3 Reproducibility over trust-me builds

Pentru artefactele critice, sistemul SHOULD favoriza build-uri reproductibile sau un nivel echivalent de verificare a identității binare.

2.4 Promotion is explicit

Trecerea dintre:

• source,
• build output,
• staged artifact,
• release candidate,
• final release MUST fi explicită, jurnalizată și atestată.

2.5 No hidden inputs

Build-ul MUST ancora toate inputurile relevante:

• source refs,
• config refs,
• compiler/runtime versions,
• dependencies,
• feature flags,
• environment constraints.

2.6 Deterministic packaging

Dacă două build-uri conforme folosesc aceleași inputuri canonice și aceeași configurație de build, SHOULD rezulta aceleași artefacte sau un set acceptabil strict definit de variații.

3. Pipeline phases overview

Pipeline-ul SHOULD fi împărțit în aceste faze:

1. Source Intake
2. Source Freeze
3. Build Plan Resolution
4. Build Execution
5. Post-Build Verification
6. Reproducibility Verification
7. Admission into Artifact Vault
8. Candidate Packaging
9. Release Approval
10. Release Publication
11. Post-Release Monitoring and Revocation Support

4. Pipeline roles

4.1 Standard roles

Sistemul SHOULD distinge:

• ROLE_SOURCE_AUTHOR
• ROLE_BUILD_PIPELINE
• ROLE_BUILD_REVIEWER
• ROLE_SECURITY_REVIEWER
• ROLE_RELEASE_MANAGER
• ROLE_REPRODUCIBILITY_CHECKER
• ROLE_GENESIS_CUSTODIAN
• ROLE_VAULT_APPROVER
• ROLE_MAINNET_RELEASE_APPROVER

4.2 Rule

Rolul care produce un build SHOULD NOT fi singurul rol care aprobă release-ul rezultat pentru scope critic.

4.3 Separation recommendation

Pentru artefactele TIER_3 și TIER_4, source author, build pipeline și final release approver SHOULD fi distincte logic.

5. Source Intake

5.1 Purpose

Faza în care inputurile de build intră oficial în pipeline.

5.2 Accepted input classes

• source code artifacts
• spec documents
• manifest files
• lockfiles
• dependency manifests
• conformance bundles
• genesis package components
• config templates
• build scripts

5.3 Rule

Toate inputurile MUST intra mai întâi prin vault/admission gate sau altă sursă canonicală aprobată. Pipeline-ul MUST NOT consuma inputuri nehash-uite și neînregistrate.

6. Source Freeze

6.1 Need

Build-urile serioase trebuie să pornească de la un set înghețat de inputuri.

6.2 SourceFreezeSet

SourceFreezeSet {
  freeze_id
  input_artifact_ids
  source_root
  dependency_root
  config_root
  freeze_scope_class
  created_at_unix_ms
}

6.3 Rule

Odată creat SourceFreezeSet, build-ul pentru acel scope MUST folosi exact aceste inputuri sau build-ul este invalid pentru scopul respectiv.

7. Build Plan Resolution

7.1 Purpose

Transformă setul de inputuri într-un plan concret de build.

7.2 BuildPlan

BuildPlan {
  build_plan_id
  source_freeze_ref
  target_artifact_class
  target_platform_class
  compiler_toolchain_ref
  build_flags_hash
  feature_flag_state_hash
  environment_profile_hash
  output_contract
}

7.3 output_contract

Definește:

• output types expected
• naming policy
• packaging policy
• reproducibility expectation
• required attestations after build

7.4 Rule

Un build nu trebuie să înceapă fără BuildPlan canonic și verificabil.

8. Environment profile

8.1 Need

Mediul de build este parte din proveniență.

8.2 Structure

BuildEnvironmentProfile {
  profile_id
  os_class
  architecture
  toolchain_versions_hash
  dependency_lock_root
  locale_policy
  time_policy
  path_normalization_policy
  allowed_network_policy
}

8.3 Rule

Pentru build-uri reproductibile, mediul SHOULD fi cât mai controlat și explicit. Accesul la rețea în timpul build-ului SHOULD fi interzis sau strict limitat și jurnalizat.

9. Build execution

9.1 Purpose

Execută planul de build pe inputuri înghețate.

9.2 Rule

Build execution MUST:

• consume only declared inputs;
• use declared toolchain;
• produce declared output classes;
• capture execution metadata;
• emit raw build outputs into a controlled staging area.

9.3 BuildExecutionRecord

BuildExecutionRecord {
  build_execution_id
  build_plan_ref
  executor_policy_ref
  start_time_unix_ms
  end_time_unix_ms
  raw_output_root
  execution_log_hash
  exit_status
}

9.4 Rule

Un build cu exit_status != success MUST NOT produce promotable output.

10. Raw build outputs

10.1 Purpose

Artefactele brute produse înainte de verificare și admitere.

10.2 Examples

• compiled binaries
• bytecode blobs
• packages
• docs bundles
• test reports
• coverage reports
• conformance result bundles

10.3 Rule

Raw outputs MUST be treated as untrusted until:

• fingerprinted,
• type-checked,
• integrity-checked,
• admitted into vault under policy.

11. Post-build fingerprinting

11.1 Rule

Fiecare output brut MUST primi:

• content_hash
• canonical_hash if applicable
• chunk_root
• byte_size
• artifact_type classification
• metadata_hash

11.2 Build output identity

The output becomes an artifact candidate only after successful fingerprinting and identity derivation.

12. Post-build verification

12.1 Purpose

Verifică dacă outputurile respectă contractul de build.

12.2 Checks SHOULD include

• expected output count
• expected output classes
• expected file/mime structure
• binary format magic/headers if applicable
• module/manifest parse validity if applicable
• dependency closure completeness
• absence of forbidden debug/experimental flags in production scope
• compatibility with target platform class

12.3 Rule

Outputuri care nu satisfac BuildPlan sau output_contract MUST be quarantined, not promoted.

13. Security checks on build outputs

13.1 Required checks for critical outputs

• hash stability check
• manifest consistency check
• binary format sanity
• embedded version consistency
• forbidden section detection where relevant
• release flag consistency
• provenance linkage presence
• signature/attestation requirement pre-checks

13.2 For code-related artifacts

SHOULD check:

• symbol/debug policy
• unexpected embedded secrets
• malformed resources
• suspicious unexpected network endpoints/configs if policy prohibits

13.3 Rule

Security check failure on TIER_3/TIER_4 outputs MUST block promotion.

14. Reproducibility verification

14.1 Need

Critical builds SHOULD be reproducible.

14.2 Standard model

At least one of:

1. independent rebuild same output hash
2. deterministic rebuild across controlled environment peers
3. equivalent canonical package root with approved allowed variations

14.3 RebuildVerificationRecord

RebuildVerificationRecord {
  rebuild_verification_id
  build_plan_ref
  compared_artifact_ids
  reproducibility_verdict
  divergence_hash?
  checker_policy_ref
}

14.4 reproducibility_verdict

• EXACT_MATCH
• MATCH_WITH_ALLOWED_VARIANCE
• MISMATCH
• NOT_PERFORMED
• INAPPLICABLE_BY_POLICY

14.5 Rule

For release binaries, genesis packages and constitutional artifacts, MISMATCH MUST be a blocker.

15. Allowed variance policy

15.1 Need

Some outputs may differ in harmless metadata if the policy permits. This SHOULD be rare for critical artifacts.

15.2 Examples of possibly allowed variance

• non-consensus timestamp field removed from canonical package layer
• container metadata excluded by canonical packaging
• optional debug map stored separately

15.3 Rule

Allowed variance MUST be explicitly enumerated in policy. Anything else is mismatch.

16. Build provenance object

16.1 Purpose

Links output artifact to all relevant build inputs.

16.2 Structure

BuildProvenanceRecord {
  provenance_id
  source_freeze_ref
  build_plan_ref
  build_execution_ref
  output_artifact_ids
  compiler_toolchain_ref
  environment_profile_ref
  dependency_lock_root
  feature_flag_state_hash
  provenance_root
}

16.3 provenance_root

provenance_root = H("AZ:BUILD_PROVENANCE:" || canonical_build_provenance_record)

16.4 Rule

Critical artifacts SHOULD carry an attestation or manifest reference to their BuildProvenanceRecord.

17. Promotion states

17.1 Standard states

Outputs SHOULD move through these states:

• PS_RAW_OUTPUT
• PS_VERIFIED
• PS_REPRODUCIBLE_CONFIRMED
• PS_STAGED
• PS_RELEASE_CANDIDATE
• PS_RELEASE_APPROVED
• PS_PUBLISHED
• PS_REVOKED
• PS_SUPERSEDED

17.2 Rule

Promotion MUST be monotonic except when revocation/supersession changes effective trust.

18. Staging admission

18.1 Purpose

Moves verified build outputs into controlled vault staging.

18.2 Requirements

To enter PS_STAGED, an artifact SHOULD have:

• identity record
• successful post-build verification
• successful security check
• basic provenance attestation
• vault admission pass for artifact type

18.3 Rule

PS_STAGED is not release approval. It is “technically admissible for further review”.

19. Release candidate formation

19.1 Purpose

Assemble a set of staged artifacts into a candidate package.

19.2 ReleaseCandidateManifest

ReleaseCandidateManifest {
  candidate_id
  target_release_scope
  included_artifact_ids
  included_manifest_refs
  provenance_root
  compatibility_root
  conformance_report_refs
  required_attestation_refs
}

19.3 Rule

A release candidate MUST be frozen before final release approvals are collected.

20. Candidate validation

20.1 Checks

Before a candidate is eligible for final approval, pipeline MUST verify:

• all required artifacts present
• all critical artifacts active and non-revoked
• required reproducibility verdicts satisfactory
• required reviews complete
• conformance bundles present where required
• target network/genesis compatibility correct
• no unresolved supersession conflict
• no quarantined critical artifact included

20.2 Rule

If candidate validation fails, final release approval MUST NOT be collected.

21. Release approval gate

21.1 Purpose

Final human/policy gate before publication.

21.2 Required inputs

• release candidate manifest
• artifact attestations per policy
• build provenance records
• reproducibility records
• conformance report bundle
• security review outcome
• target genesis package if relevant

21.3 Rule

Release approval MUST be scope-locked to exact candidate_id and exact release scope.

22. Release publication

22.1 Purpose

Publishes approved release into final release scope.

22.2 Publication outputs MAY include

• release manifest
• binaries
• genesis package
• operator manual bundle
• conformance bundle
• signed release notes
• hash manifest

22.3 Rule

Publication MUST be journaled and SHOULD create forced snapshot of release scope in vault.

23. Publication manifest

23.1 PublishedReleaseRecord

PublishedReleaseRecord {
  published_release_id
  release_candidate_ref
  final_release_manifest_ref
  publication_time_unix_ms
  publication_channel_class
  published_artifact_root
  publication_attestation_refs
}

23.2 Rule

Published release MUST be reconstructible from candidate + final approvals + final manifest.

24. Artifact classes in build/release pipeline

24.1 Main classes

• source_bundle
• build_script_bundle
• toolchain_descriptor
• dependency_lock_bundle
• binary_output
• package_output
• conformance_bundle
• genesis_bundle
• release_manifest
• operator_bundle
• audit_bundle

24.2 Rule

Different classes MAY have different reproducibility and attestation requirements, but policy MUST define them explicitly.

25. Policy matrix for build pipeline

25.1 Recommended matrix dimensions

For each artifact/release class, policy SHOULD define:

• source freeze required?
• reproducibility required?
• security review required?
• conformance bundle required?
• dual approval required?
• mainnet scope lock required?
• genesis compatibility required?
• mandatory snapshot after publication?

25.2 Rule

Pipeline MUST use one authoritative policy matrix, not local CI folklore.

26. Secure build environment controls

26.1 Recommended controls

• pinned toolchain
• pinned dependencies
• minimal environment
• deterministic locale/time handling
• no undeclared network access
• isolated secrets
• ephemeral build worker where possible
• clean workspace
• exact input hash verification before execution

26.2 Rule

Undeclared mutable environment state MUST NOT affect critical build outputs.

27. Secret handling

27.1 Principle

Build pipelines SHOULD not embed secrets into outputs unless explicitly intended and policy-approved. In most cases, secrets MUST NOT be part of reproducible release artifacts.

27.2 Rule

If a critical artifact unexpectedly depends on secret material, promotion MUST halt.

28. Toolchain trust model

28.1 Toolchain artifacts

Compilers, linkers and packagers are themselves sensitive artifacts.

28.2 Rule

Critical builds SHOULD anchor:

• compiler identity
• compiler version
• toolchain hash
• packaging tool version
• dependency lock root

28.3 Recommendation

Toolchain descriptors SHOULD themselves be admitted through vault and attested as trusted inputs.

29. Dependency governance

29.1 Need

Dependencies are part of release truth.

29.2 Rule

Pipeline MUST build against locked dependency set for critical releases.

29.3 Changes in dependency set

A dependency change SHOULD require:

• new SourceFreezeSet
• new BuildPlan
• possibly new security review
• reproducibility rerun

30. Conformance integration

30.1 Critical releases SHOULD link to:

• conformance suite version
• conformance report hash
• failing/skipped vector summary if any
• implementation identifier
• exact release candidate scope

30.2 Rule

Consensus-critical binaries SHOULD NOT be promoted without conformance evidence.

31. Security review integration

31.1 For critical releases, candidate package SHOULD have:

• security review attestation
• unresolved finding summary hash
• final release approval depending on review outcome
• if conditional approval exists, exact conditions hash

31.2 Rule

Conditional approvals MUST be machine-checkable enough not to become vague hand-waves.

32. Genesis package integration

32.1 Mainnet-sensitive rule

Any release tied to a network launch SHOULD reference exact:

• genesis_hash
• chain_id
• genesis_bundle artifact_id
• compatibility statement hash

32.2 Rule

A binary approved for one genesis scope MUST NOT be silently reused as approved for another mainnet scope without fresh approval.

33. Candidate supersession

33.1 Need

A release candidate may be replaced.

33.2 Rule

Supersession MUST be explicit:

• old candidate ref
• new candidate ref
• reason class
• which approvals are invalidated
• whether reproducibility must be rerun

33.3 Strong rule

A superseded candidate MUST NOT remain eligible for publication unless policy explicitly allows and no conflict exists.

34. Release revocation

34.1 Need

A published release may later be found unsafe.

34.2 Rule

Release revocation MUST be explicit and SHOULD include:

• affected release id
• affected artifact set
• reason hash
• severity
• replacement release if known
• rollback guidance hash if applicable

34.3 Effect

Revoked release SHOULD remain archived but not active for recommendation or deployment.

35. Rollback support

35.1 Principle

Rollback in release pipeline is not deletion. It is controlled supersession or revocation plus explicit fallback selection.

35.2 Rule

If a release is revoked, pipeline SHOULD identify:

• last known good release
• replacement release candidate
• compatible rollback artifacts
• rollback approvals if needed

36. Build and release journal

36.1 Need

All promotion actions must be traceable.

36.2 Journal entries SHOULD cover:

• source freeze created
• build plan created
• build executed
• output fingerprinted
• verification passed/failed
• reproducibility passed/failed
• staged
• candidate formed
• candidate approved/rejected
• published
• revoked
• superseded

36.3 Rule

The journal SHOULD be hash-chained and linkable to AZ-018/AZ-019 vault manifests.

37. Failure handling in pipeline

37.1 Failure classes

• build failed
• verification failed
• security check failed
• reproducibility mismatch
• attestation missing
• scope mismatch
• release policy mismatch
• publication failure
• post-publication revocation needed

37.2 Rule

Each failure MUST leave:

• traceable record
• affected artifact refs
• verdict
• promotion state No silent failure that leaves ambiguous candidate state.

38. Quarantine in build pipeline

38.1 Candidates for quarantine

• malformed output
• structurally valid but policy-violating output
• binary with provenance gap
• reproducibility mismatch
• suspicious near-duplicate release artifact
• inconsistent release manifest

38.2 Rule

Quarantine in build/release pipeline MUST prevent promotion but preserve evidence for analysis.

39. Publication channels

39.1 Examples

• internal release registry
• validator distribution channel
• public download channel
• mainnet launch channel
• emergency patch channel

39.2 Rule

Publication channel MUST be part of published release record. A release published to one channel/scope is not automatically approved for all others.

40. Mainnet launch package

40.1 SHOULD include

• exact release binaries
• exact genesis bundle
• exact release manifest
• exact conformance bundle refs
• exact operator docs bundle
• final attestation set for launch scope

40.2 Rule

Mainnet launch package MUST be immutable after final approval. Any change creates a new candidate or new release.

41. Release gates by criticality

41.1 TIER_1/TIER_2 artifacts

May allow:

• single pipeline provenance
• basic hash confirmation
• relaxed reproducibility policy if non-critical

41.2 TIER_3 artifacts

Should require:

• build provenance
• verification
• security review
• reproducibility or equivalent strong check
• release approval

41.3 TIER_4 artifacts

Should require:

• all above
• multi-role approval
• scope lock
• forced snapshot
• stricter revocation monitoring

42. Anti-patterns

Pipelines SHOULD avoid:

1. building from mutable branch state without freeze
2. using undeclared network downloads during critical build
3. promoting raw outputs directly to release
4. treating CI success as release approval
5. approving a release candidate before reproducibility check
6. reusing old approvals for new candidate by filename similarity
7. publishing binaries without final manifest
8. allowing publication after critical attestation revocation
9. mixing debug/test outputs into production candidate
10. patching release artifact after approval instead of creating new candidate

43. Formal goals

AZ-021 urmărește aceste obiective:

43.1 Provenance completeness

Critical outputs can be traced back to exact source freeze, build plan and environment.

43.2 Promotion soundness

An artifact cannot become release truth without passing required checks and approvals.

43.3 Reproducibility assurance

Critical build outputs are reproducible or explicitly policy-accounted if not exactly reproducible.

43.4 Release recoverability

Published releases can be revoked, superseded and rolled back without losing chain of custody.

44. Formula documentului

Secure Build/Release = frozen inputs + declared build plan + controlled execution + post-build verification + reproducibility proof + staged promotion + scope-locked approval + immutable publication

45. Relația cu restul suitei

• AZ-018 definește admission gate pentru artefacte.
• AZ-019 definește manifesturile vault-ului.
• AZ-020 definește cine poate aproba artefactele.
• AZ-021 definește cum ajungi de la sursă la release fără să pierzi controlul.

Pe scurt: AZ-021 este lanțul de custodie executabil dintre fișierele proiectului și pachetul de release.

46. Ce urmează

După AZ-021, documentul corect este:

AZ-022 — Concrete Genesis Package

Acolo trebuie fixate:

• structura exactă a pachetului genesis,
• fișierele lui,
• manifestul lui,
• atestările lui,
• relația dintre genesis blob, chain identity, validator bootstrap și release package.

Închidere

Un build bun produce un binary. Un pipeline serios produce mult mai mult:

• inputuri înghețate,
• proveniență,
• verificări,
• reproducibilitate,
• manifesturi,
• aprobări,
• și un release care poate fi apărat auditabil de la primul byte de sursă până la ultimul byte publicat.

Acolo începe release-ul verificabil real.