67 — Forgeyard Artifact Promotion Policy, Release Train, Environment Channel & Lifecycle Governance System Architecture

Document type: Core Artifact Promotion Policy, Release Train, Environment Channel, Ring Progression, Freeze Window, Hotfix Lane & Release Lifecycle Governance System Architecture
Project: Forgeyard CI/CD
Subsystem: release trains, promotion channels, environment rings, release eligibility, scheduled trains, freeze windows, maintenance windows, emergency hotfix lanes, channel inheritance, release progression, rollback lineage, release retirement, rollout readiness, compatibility/supply-chain/policy gating, and promotion lifecycle governance
Architecture style: Immutable release identity, explicit lifecycle state, channel-as-pointer not artifact identity, scheduled progression, evidence-bound eligibility, policy-controlled exceptions, separate hotfix lane, deterministic ring promotion, and no rebuild between lifecycle stages
Status: Target production architecture extending the Forgeyard series beyond the original 01–26 plan
Relationship to prior work: Builds on Packaging, Release, Deployment, Artifact Registry, Progressive Delivery, Compatibility Governance, Supply Chain, Policy/Authz, Notifications, Incident Management, Change Freeze, Cost/FinOps, Federation, and Update Delivery. This subsystem adds an organization-level release lifecycle above individual deployments.

1. Purpose

A production CI/CD platform often needs more than:

release -> deploy

Organizations may use:

nightly
alpha
beta
rc
stable
lts

or environment rings:

development
integration
staging
pilot
production

or scheduled release trains:

every Tuesday
monthly enterprise train
quarterly LTS train

They may also need:

release freezes
holiday freezes
maintenance windows
hotfix exceptions
security emergency lanes
support windows
end-of-life transitions

Without a dedicated architecture, these rules become:

manual spreadsheets
release-manager memory
branch naming conventions
provider-specific scripts
untracked exceptions

The central rule is:

A release channel or release train governs eligibility and timing for an existing immutable ReleaseId; it never creates or modifies the artifact itself.

A second rule is:

Promotion through channels/rings is a lifecycle state transition backed by exact evidence, compatibility, policy, and target readiness.

A third rule is:

Emergency hotfix lanes may shorten ordinary cadence, but they never bypass release identity, signing, authorization, audit, or minimum security requirements.

2. Architectural Position

                      ReleaseId
                         │
                         ▼
                  Release Eligibility
                         │
                         ▼
                    Release Train
                         │
                ┌────────┼────────┐
                ▼        ▼        ▼
              Alpha     Beta      RC
                │        │        │
                └────────┼────────┘
                         ▼
                       Stable
                         │
                         ▼
                        LTS

Environment rings:

dev -> integration -> staging -> pilot -> production

3. Goals

The subsystem MUST:

define channel identity;
define release train identity;
define ring identity;
define lifecycle eligibility;
bind exact ReleaseId;
support alpha/beta/rc/stable/lts;
support environment rings;
support scheduled release trains;
support manual trains;
support freeze windows;
support maintenance windows;
support hotfix lanes;
support security emergency promotion;
support release eligibility gates;
support channel-specific compatibility rules;
support supply-chain requirements;
support manual approvals;
support tenant/region/channel scopes;
support rollback lineage;
support channel alias movement;
support retirement/deprecation;
support EOL;
support audit;
support Dioxus UI/API/CLI;
support federation;
support air-gap;
support HA;
support DR;
preserve immutable artifact identity;
avoid branch-name-driven lifecycle truth.

4. Non-Goals

This subsystem does not replace:

Release creation
artifact signing
Deployment
Progressive Delivery
Artifact Registry
package-manager version semantics

It governs release progression.

5. Workspace Structure

crates/release-lifecycle/
├── forgeyard-release-lifecycle/
├── forgeyard-release-channel/
├── forgeyard-release-train/
├── forgeyard-release-ring/
├── forgeyard-release-eligibility/
├── forgeyard-release-freeze/
├── forgeyard-release-hotfix/
├── forgeyard-release-retirement/
├── forgeyard-release-reconcile/
├── forgeyard-release-health/
└── forgeyard-release-lifecycle-testkit/

6. ReleaseChannelId

#![allow(unused)]
fn main() {
pub struct ReleaseChannelId(Digest);
}

7. Release Channel

#![allow(unused)]
fn main() {
pub struct ReleaseChannel {
    pub id: ReleaseChannelId,
    pub name: BoundedString,
    pub policy: ChannelPolicyId,
    pub audience: ReleaseAudience,
}
}

8. Channel Examples

nightly
alpha
beta
candidate
stable
lts
internal
enterprise

#![allow(unused)]
fn main() {
pub struct ChannelPointer {
    pub channel: ReleaseChannelId,
    pub release: ReleaseId,
    pub generation: u64,
}
}

#![allow(unused)]
fn main() {
pub struct ReleaseTrainId(Ulid);
}

15. Release Train

#![allow(unused)]
fn main() {
pub struct ReleaseTrain {
    pub id: ReleaseTrainId,
    pub policy: ReleaseTrainPolicyId,
    pub target_channel: ReleaseChannelId,
    pub schedule: Option<ReleaseTrainSchedule>,
}
}

16. Train Types

#![allow(unused)]
fn main() {
pub enum ReleaseTrainKind {
    Continuous,
    Scheduled,
    Manual,
    LongTermSupport,
    Security,
    Hotfix,
}
}

#![allow(unused)]
fn main() {
pub struct ReleaseTrainSchedule {
    pub timezone: TimeZoneId,
    pub recurrence: CalendarSchedule,
}
}

24. Timezone Mandatory

No ambiguous UTC/local assumptions.

25. Missed Train

Policy options:

#![allow(unused)]
fn main() {
skip
run next window
manual decide
}

26. No Surprise Catch-Up

Critical.

27. RingId

#![allow(unused)]
fn main() {
pub struct ReleaseRingId(Digest);
}

28. Ring

Represents ordered exposure/lifecycle stage.

Examples:

ring-0 internal
ring-1 pilot
ring-2 early adopters
ring-3 general availability

29. Ring Policy

#![allow(unused)]
fn main() {
pub struct RingPolicy {
    pub eligibility: EligibilityPolicyId,
    pub rollout: Option<PromotionPlanId>,
}
}

#![allow(unused)]
fn main() {
pub enum ReleaseLifecycleState {
    Built,
    Verified,
    Candidate,
    ChannelEligible,
    Promoting,
    Active,
    Deprecated,
    Retiring,
    Retired,
    Revoked,
}
}

#![allow(unused)]
fn main() {
pub struct ReleaseEligibilityId(Digest);
}

42. Eligibility Inputs

ReleaseId
ChannelPolicyId
PolicyDigest
CompatibilityReportId
SupplyChainEvidence
Test/quality evidence
Target support matrix

43. Eligibility Result

#![allow(unused)]
fn main() {
pub enum EligibilityResult {
    Eligible,
    EligibleWithApproval,
    Ineligible,
    Incomplete,
    Unknown,
}
}

44. Unknown Is Not Eligible

Critical.

45. Channel Policy

Can require:

reproducibility
SBOM
signature
vulnerability thresholds
compatibility
test level
manual approval
minimum soak time

46. Stable Stronger Than Beta

Typical but configurable.

47. LTS Strongest Support Requirements

Can require:

longer validation
support commitment
upgrade compatibility
migration path
security maintenance

48. Release Soak

#![allow(unused)]
fn main() {
pub struct SoakRequirement {
    pub minimum_duration: Duration,
    pub source_ring: ReleaseRingId,
}
}

dev
integration
staging
pilot
production

53. Channel vs Environment

Distinct.

Channel:

distribution audience/version stream

Environment:

runtime deployment target

54. Example

stable channel can be deployed to multiple production environments.

55. Promotion Between Channels

Example:

alpha -> beta -> rc -> stable

56. Promotion Between Environments

Part 62.

57. Release Lifecycle Can Require Both

Example:

candidate
  ↓
staging
  ↓
pilot
  ↓
stable channel

58. PromotionRequestId

#![allow(unused)]
fn main() {
pub struct ReleaseLifecyclePromotionId(Ulid);
}

59. Promotion Request

#![allow(unused)]
fn main() {
pub struct ReleaseLifecyclePromotion {
    pub id: ReleaseLifecyclePromotionId,
    pub release: ReleaseId,
    pub from: Option<LifecycleStageRef>,
    pub to: LifecycleStageRef,
    pub eligibility: ReleaseEligibilityId,
}
}

#![allow(unused)]
fn main() {
pub struct ReleaseFreezeId(Ulid);
}

69. Freeze Scope

#![allow(unused)]
fn main() {
pub enum ReleaseFreezeScope {
    Installation,
    Project(ProjectId),
    Channel(ReleaseChannelId),
    Ring(ReleaseRingId),
    Region(RegionId),
}
}

70. Freeze Types

#![allow(unused)]
fn main() {
pub enum ReleaseFreezeKind {
    Calendar,
    Incident,
    Reliability,
    Manual,
    Compliance,
}
}

71. Calendar Freeze

Examples:

holiday
quarter-end
exam season for school ERP

72. Freeze Behavior

Can block:

normal promotion
channel pointer movement
new production rollout

#![allow(unused)]
fn main() {
pub struct HotfixLaneId(Digest);
}

76. Hotfix Purpose

Expedited release path for urgent production correction.

77. Hotfix Requirements

Still require minimum:

exact ReleaseId
signature
provenance
security checks
compatibility
authorization
audit

78. Can Shorten

soak time
release cadence
manual queue wait

if policy allows.

79. Cannot Skip

artifact identity
trust/signing
minimum security floor
authorization
audit

80. Hotfix Base

Exact current production ReleaseId.

81. Hotfix Lineage

#![allow(unused)]
fn main() {
pub struct ReleaseLineage {
    pub parent: Option<ReleaseId>,
    pub kind: ReleaseLineageKind,
}
}

82. Lineage Kind

#![allow(unused)]
fn main() {
pub enum ReleaseLineageKind {
    Normal,
    Hotfix,
    SecurityPatch,
    Rollback,
    RebuildVerification,
}
}

hotfix released
merge-back pending
merge-back completed

Example:

stable requires N/N-1
lts requires N/N-2

90. Support Matrix

First-class.

91. SupportWindowId

#![allow(unused)]
fn main() {
pub struct SupportWindowId(Digest);
}

92. Support Window

#![allow(unused)]
fn main() {
pub struct SupportWindow {
    pub release: ReleaseId,
    pub starts_at: Timestamp,
    pub ends_at: Option<Timestamp>,
    pub level: SupportLevel,
}
}

93. Support Level

#![allow(unused)]
fn main() {
pub enum SupportLevel {
    Experimental,
    Preview,
    Standard,
    Extended,
    SecurityOnly,
    Ended,
}
}

Active
  ↓
Deprecated
  ↓
Retiring
  ↓
Retired

release timestamp
priority
security urgency
compatibility
required fixes

104. No Branch Head Selection At Train Time

Critical.

Train selects immutable ReleaseIds.

105. Train Manifest

#![allow(unused)]
fn main() {
pub struct ReleaseTrainManifestId(Digest);
}

#![allow(unused)]
fn main() {
pub struct ReleaseSetId(Digest);
}

111. Release Set

#![allow(unused)]
fn main() {
pub struct ReleaseSet {
    pub releases: Vec<ReleaseId>,
    pub compatibility: CompatibilityReportId,
}
}

stable policy
  └── beta requirements
       └── alpha requirements

#![allow(unused)]
fn main() {
pub struct ChannelPromotionGraph {
    pub edges: Vec<ChannelPromotionEdge>,
}
}

122. Edge

#![allow(unused)]
fn main() {
pub struct ChannelPromotionEdge {
    pub from: ReleaseChannelId,
    pub to: ReleaseChannelId,
    pub policy: EligibilityPolicyId,
}
}

security floor
compatibility
DB migration state
config compatibility

SBOM
provenance
signatures
VEX

135. Eligibility Snapshot

Exact evidence references.

136. Security Vulnerability After Promotion

Release may become:

Blocked
Revoked
SecurityOnly

depending severity.

continue current bounded action
pause future progression

baseline.

holidays
fiscal quarter
school term

149. CalendarVersionId

#![allow(unused)]
fn main() {
pub struct BusinessCalendarId(Digest);
}

#![allow(unused)]
fn main() {
pub struct LifecyclePromotionApproval {
    pub promotion: ReleaseLifecyclePromotionId,
    pub release: ReleaseId,
    pub target: LifecycleStageRef,
    pub policy: PolicyDigest,
}
}

beta known limitations
stable upgrade notes
LTS support statement

#![allow(unused)]
fn main() {
pub enum ReleaseTrainState {
    Planned,
    CandidateSelection,
    AwaitingEligibility,
    AwaitingWindow,
    Promoting,
    Paused,
    Succeeded,
    Failed,
    Cancelled,
}
}

164. Pause

Possible due:

incident
freeze
failed eligibility
target health
manual

#![allow(unused)]
fn main() {
pub struct ReleaseTrainSeal {
    pub manifest: ReleaseTrainManifestId,
    pub sealed_at: Timestamp,
}
}

#![allow(unused)]
fn main() {
pub struct ReleaseTrainBundleId(Digest);
}

180. Bundle Contains

ReleaseIds
artifacts
signatures
SBOM/provenance
eligibility evidence
channel transition intent

global
tenant-specific
project-specific

#![allow(unused)]
fn main() {
pub enum ReleaseChannelScope {
    Global,
    Tenant(TenantId),
    Project(ProjectId),
    Product(ProductId),
}
}

channel pointer move
promotion approval
hotfix lane use
freeze override
train seal
candidate replacement before seal
retirement
revocation
EOL change

197. Routine Train Evaluation

Operational event.

198. Dioxus UI

Pages:

Release Channels
Release Trains
Promotion Rings
Freeze Calendar
Hotfixes
Support Lifecycle

199. Channel Detail

Shows:

current ReleaseId
policy
audience
support level
promotion history

200. Release Train View

Shows:

schedule
candidate set
eligibility
window
current stage
blockers

forgeyard lifecycle channel list
forgeyard lifecycle channel show
forgeyard lifecycle train list
forgeyard lifecycle train plan
forgeyard lifecycle train start
forgeyard lifecycle promote
forgeyard lifecycle freeze
forgeyard lifecycle hotfix
forgeyard lifecycle retire
forgeyard lifecycle doctor

204. API

Potential:

GET  /v1/release-channels
POST /v1/release-trains
GET  /v1/release-trains/{id}
POST /v1/release-trains/{id}/start
POST /v1/releases/{id}/promote
POST /v1/release-freezes
POST /v1/releases/{id}/retire

205. Permissions

release_lifecycle.read
release_lifecycle.promote
release_lifecycle.train.manage
release_lifecycle.freeze.manage
release_lifecycle.hotfix
release_lifecycle.retire
release_lifecycle.revoke

release_train_total
release_train_failures_total
release_promotion_total
release_promotion_blocked_total
release_freeze_active
release_hotfix_total
release_retired_total

210. Labels

Low-cardinality:

channel
train_kind
result

Avoid ReleaseId in metrics labels.

211. Tracing

release_lifecycle.eligibility
release_lifecycle.train
release_lifecycle.promote
release_lifecycle.freeze
release_lifecycle.hotfix
release_lifecycle.retire

212. Health

#![allow(unused)]
fn main() {
pub enum ReleaseLifecycleHealth {
    Healthy,
    ScheduleDegraded,
    EligibilityDegraded,
    PromotionDegraded,
    Unhealthy,
}
}

213. Doctor

forgeyard lifecycle doctor

Checks:

channel points to revoked release
expired freeze
train stuck awaiting window
sealed train references missing release
hotfix merge-back overdue
LTS release without support window
retired release still default

214. Data Lifecycle

Part 46.

Retain:

train manifests
promotion evidence
channel history
freeze history
support/EOL history
hotfix lineage

But coordinated validation/promotion may incur:

test
environment
replication
deployment

220. Cost Does Not Bypass Required Eligibility

221. Security

Threats:

channel pointer hijack
hotfix abuse
freeze bypass
candidate substitution
rollback to vulnerable release
forged eligibility

222. Controls

exact ReleaseId
expected channel generation
signed evidence
policy digest
audit
security floor

#![allow(unused)]
fn main() {
pub enum EligibilityFreshness {
    Current,
    SecurityChanged,
    PolicyChanged,
    CompatibilityChanged,
    SupportChanged,
    Expired,
    Unknown,
}
}

229. Reconciliation

Release lifecycle reconciler checks:

channel pointer validity
train schedule
freeze state
eligibility freshness
support/EOL transitions
hotfix merge-back

Critical.

forgeyard-release-lifecycle-testkit/src/
├── lib.rs
├── channel.rs
├── train.rs
├── eligibility.rs
├── freeze.rs
├── hotfix.rs
├── retirement.rs
└── assertions.rs

248. Core Tests

Channel

channel pointer references exact ReleaseId;
stale generation update rejected;
tag alias cannot redefine artifact digest.

Eligibility

missing evidence => Incomplete;
revoked release never eligible;
security state change invalidates freshness.

Train

sealed candidate set immutable;
missed window follows explicit policy;
resume re-evaluates freshness.

Freeze

normal promotion blocked;
hotfix exception explicit;
existing active release not revoked merely by freeze.

Hotfix

exact lineage recorded;
minimum security/trust gates remain;
merge-back tracking persists.

Retirement

support/EOL transitions explicit;
default channel cannot point to retired/revoked release by policy.

Federation

one global channel authority;
offline site uses verified snapshot only.

249. Chaos Tests

Inject:

controller crash during channel move
external registry timeout
calendar service failure
federation partition
eligibility evidence service outage

Expected:

no duplicate promotion
channel pointer remains coherent
Unknown/Incomplete visible
reconciliation repairs

250. Scale Tests

Test:

many products/channels
large tenant-specific beta programs
multi-component trains
large historical promotion graph

Channel always references exact ReleaseId.
Channel alias never becomes artifact identity.
Promotion never rebuilds/resigns software to create fake stage identity.
Release train candidates are immutable once sealed.
Branch head is never train truth.
Eligibility is explicit and evidence-backed.
Unknown/incomplete is never eligible automatically.
Security freshness can invalidate eligibility.
Stable/LTS can enforce stricter gates than alpha/beta.
Scheduled train behavior is timezone-aware.
Missed train behavior is explicit.
Freeze blocks normal progression without revoking current release.
Hotfix lane retains minimum trust/security/authz/audit.
Hotfix lineage is explicit.
Hotfix merge-back is tracked.
Channel promotion and environment deployment remain distinct.
Part 62 remains rollout authority.
Part 15 remains Release authority.
Part 52 remains artifact registry authority.
Support/EOL state is explicit.
Retirement does not imply immediate artifact deletion.
Rollback checks security/compatibility state.
Revoked release cannot become automatic rollback target.
Multi-component train uses exact ReleaseSetId.
Channel policy inheritance is explicit.
Federation has one accepted mutable channel authority.
Offline/air-gap channel state is signed/verified.
External tag/dist-tag failures reconcile.
Historical lifecycle events remain immutable.
Forgeyard dogfoods release trains/channels for its own release lifecycle.

253. Production Readiness Gates

Do not call release lifecycle governance production-ready until:

channel pointer generation checks are enforced
same-bytes promotion is proven
eligibility freshness works
train sealing is immutable
freeze/hotfix exception paths are audited
registry/update adapter reconciliation works
rollback security floor is enforced
support/EOL transitions are tested
federation/air-gap channel authority works
chaos/scale tests pass

254. Architectural Invariants

ReleaseId is canonical artifact identity;
channels are pointers/audiences, not identities;
trains select immutable ReleaseIds;
sealed train candidates do not change silently;
eligibility has exact evidence;
Unknown is not eligible;
eligibility can become stale;
promotion never rebuilds;
freeze does not revoke existing release;
hotfix lane does not bypass trust/security/authz/audit;
hotfix lineage is recorded;
merge-back is tracked;
support/EOL are explicit;
retirement is distinct from deletion;
rollback observes current security floor;
channel promotion is distinct from deployment;
progressive delivery remains Part 62 authority;
release remains Part 15 authority;
registry remains Part 52 authority;
channel pointer updates use expected generation;
external tag updates reconcile after ambiguity;
policy inheritance is explicit;
federation has one mutable authority;
offline state is verified;
audit preserves lifecycle history;
current policy controls new progression;
historical decisions are not rewritten;
AI may draft notes, not eligibility truth;
no branch-name lifecycle truth;
Forgeyard dogfoods its own release lifecycle.

255. Final Target Architecture

                        ReleaseId
                           │
                           ▼
                     Eligibility
                           │
                           ▼
                    Release Train
                           │
               ┌───────────┼───────────┐
               ▼           ▼           ▼
             Alpha        Beta         RC
               │           │           │
               └───────────┼───────────┘
                           ▼
                         Stable
                           │
                           ▼
                           LTS

Hotfix:

production ReleaseId
        ↓
urgent fix
        ↓
new exact ReleaseId
        ↓
minimum trust/security gates
        ↓
hotfix lane
        ↓
progressive production rollout
        ↓
merge-back tracking

The key guarantee is:

Forgeyard can run disciplined release trains, channels, rings, freezes, and hotfix lanes without ever confusing lifecycle metadata with software identity. Every lifecycle transition moves an existing immutable ReleaseId under explicit evidence and policy, preserving the build-once/promote-same-bytes architecture.

256. Extended Architecture Sequence

01 Core Domain & Foundation
02 Storage & Metadata
03 CAS & Artifact Data Plane
04 Pipeline IR / Parsing / Planning
05 Run / Job State Machine
06 Scheduler
07 Runner / Agent
08 Sandbox & Executor
09 Transport / QUIC / Protocol
10 Events / Reconciliation
11 Policy / Authorization / Identity
12 Secrets / Trust
13 Supply Chain / SBOM / Provenance / Signing
14 Packaging
15 Release
16 Deployment
17 Observability / Health / Doctor
18 API / Axum
19 Dioxus UI
20 Device Lab
21 SCM Provider Integrations
22 HA / Coordination / Raft
23 RBE Interop
24 Plugin / Extension Architecture
25 Operations / Backup / Upgrade / DR
26 Self-Hosting / Bootstrap / Release Forgeyard
27 Multi-Tenancy / Quotas / Resource Governance
28 Audit / Compliance / Security Governance
29 Notifications / Alerting / Human Workflow
30 Entitlements / Licensing / Subscription
31 Search / Indexing / Operational Analytics
32 Test Results / Quality / Coverage / Flaky Intelligence
33 Benchmark / Performance / Load / Capacity
34 Monorepo / Dependency Graph / Affected Work
35 Developer Experience / Local Dev
36 Dependency / Registry / Mirror Governance
37 Static Analysis / Security Findings
38 Cache / Remote Cache / Correctness
39 Configuration / Feature Flags / Runtime
40 Security / Threat Model / Incident Response
41 Release Distribution / Update Delivery
42 Workflow Templates / Golden Paths
43 Runner Fleet Autoscaling / Provisioning
44 Pipeline Triggers / Schedules / Dispatch
45 Cost Accounting / FinOps
46 Data Lifecycle / Retention / Privacy
47 CI/CD Migration / Compatibility
48 Failure Diagnosis / Reproduction / Bisect
49 Service Catalog / Ownership / Developer Portal
50 Reliability / SLO / Error Budget / Resilience
51 Multi-Region Federation / Edge / Disconnected
52 Artifact Registry / OCI / Package Distribution
53 Infrastructure-as-Code / Preview Environments / Drift
54 Merge Queue / Speculative Integration / Batch Validation
55 AI-Assisted CI Optimization / Engineering Copilot
56 Test Data / Fixtures / Ephemeral Databases / Service Virtualization
57 API / ABI / Schema / Protocol Compatibility / Contract Evolution
58 Runner Image Factory / Golden Images / Patch Management / Baseline Attestation
59 Network Connectivity / Private Resource Access / Egress / Tunneling / Zero-Trust Connectivity
60 Workflow Concurrency / Distributed Locks / Idempotency / Reservations / Exclusive Coordination
61 Incident Management / On-Call / Escalation / Response Coordination / Postmortem
62 Environment Promotion / Progressive Delivery / Feature Rollout / Canary Analysis / Automated Rollback
63 Database Schema Migration / Online Backfill / Data Transformation / Zero-Downtime Change Orchestration
64 Remote Development Environments / Cloud Workspaces / Developer Workspace Orchestration
65 Build Graph Replay / Historical Reproducibility / Time-Travel CI / Evidence Reconstruction
66 Change Risk Assessment / Preflight Simulation / Policy Preview / What-If Analysis
67 Artifact Promotion Policy / Release Train / Environment Channel / Lifecycle Governance

Keyboard shortcuts

Forgeyard System Architecture & Engineering Documentation