66 — Forgeyard Change Risk Assessment, Preflight Simulation, Policy Preview & What-If Analysis System Architecture

Document type: Core Change Risk Assessment, Preflight Simulation, Policy Preview, What-If Planning, Impact Forecasting & Safe Change Analysis System Architecture
Project: Forgeyard CI/CD
Subsystem: preflight evaluation, hypothetical plan execution, change-risk classification, policy simulation, deployment impact preview, infrastructure plan comparison, migration risk preview, compatibility impact, affected-work expansion, security risk analysis, resource/cost forecast, blast-radius estimation, approval preview, and explainable decision support
Architecture style: Deterministic first, evidence-backed, read-only simulation, exact immutable subjects, explicit uncertainty, no side effects, policy-as-data evaluation, typed risk facts, bounded forecast confidence, and strict separation between simulation and authority
Status: Target production architecture extending the Forgeyard series beyond the original 01–26 plan
Relationship to prior work: Builds on Pipeline Planning, Policy/Authz, Static Analysis, Compatibility Governance, Monorepo Intelligence, Infrastructure-as-Code, Deployment, Progressive Delivery, Database Migration, Cost/FinOps, Reliability, Security, Incident Management, Merge Queue, and AI Assistance. This subsystem provides a unified “what will happen if we do this?” layer before protected changes execute.

1. Purpose

Forgeyard already understands many change dimensions:

source changes
pipeline changes
dependency changes
policy changes
config changes
infrastructure changes
database migrations
deployment changes
release changes
runner-image changes
network changes

Before execution, engineers need answers such as:

What will this change affect?
Which pipelines/jobs will run?
Which components are at risk?
Will this violate policy?
Will this break API/ABI compatibility?
What environments may be impacted?
Will deployment require downtime?
Will this migration rewrite a large table?
How much will this cost?
What approvals will be required?
What could block the merge?
What rollout strategy is recommended?

The central rule is:

Preflight analysis is a read-only simulation of intended effects against an exact immutable change subject and current known system state. It must never perform the protected external effect it is analyzing.

A second rule is:

Risk is represented as typed facts with provenance and uncertainty, not a magical opaque score.

A third rule is:

A simulation result can explain likely consequences and policy outcomes, but real execution evidence remains authoritative once the change actually runs.

2. Architectural Position

                    Proposed Change
                         │
                         ▼
                  Preflight Subject
                         │
                         ▼
                 Deterministic Planning
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
       Policy         Impact         Risk Facts
          │              │              │
          └──────────────┼──────────────┘
                         ▼
                   What-If Result
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
           Explain     Approvals   Blockers
                         │
                         ▼
                  Human / Merge / CI

3. Goals

The subsystem MUST:

define preflight identity;
define simulation subject identity;
support source-change preflight;
support pipeline preflight;
support policy preview;
support compatibility preview;
support infrastructure preview;
support deployment preview;
support migration preview;
support cost/resource forecast;
support security impact analysis;
support affected-work impact;
support blast-radius estimation;
support approval prediction;
support merge-blocker prediction;
support rollout recommendation inputs;
support explicit uncertainty;
support historical comparison;
support scenario comparison;
support “what if config X changes?”;
support “what if policy Y changes?”;
support UI/API/CLI;
support audit;
support caching;
support multi-tenancy;
support federation;
support air-gap;
support deterministic reproducibility;
remain side-effect free;
never replace real execution evidence.

4. Non-Goals

This subsystem does not:

execute deployments
apply infrastructure
run database migrations
approve changes
merge code
publish releases
sign artifacts
guarantee future production behavior

5. Workspace Structure

crates/preflight/
├── forgeyard-preflight/
├── forgeyard-preflight-model/
├── forgeyard-preflight-subject/
├── forgeyard-preflight-impact/
├── forgeyard-preflight-policy/
├── forgeyard-preflight-risk/
├── forgeyard-preflight-cost/
├── forgeyard-preflight-security/
├── forgeyard-preflight-compatibility/
├── forgeyard-preflight-scenario/
├── forgeyard-preflight-explain/
├── forgeyard-preflight-cache/
├── forgeyard-preflight-health/
└── forgeyard-preflight-testkit/

6. PreflightId

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

One preflight evaluation.

7. PreflightPlanId

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

Immutable identity of the exact simulation inputs.

8. Preflight Subject

#![allow(unused)]
fn main() {
pub enum PreflightSubject {
    SourceChange(ChangeProposalRevisionId),
    IntegrationCandidate(IntegrationCandidateId),
    Pipeline(PipelineIrId),
    Release(ReleaseId),
    Deployment(DeploymentPlanId),
    Infrastructure(InfrastructurePlanId),
    Migration(MigrationPlanId),
    Config(ConfigSnapshotId),
    Policy(PolicyDigest),
    RunnerImage(RunnerImageDefinitionId),
    NetworkPolicy(NetworkCapabilityId),
}
}

9. Exact Subject

Branch names, mutable environment aliases, and “latest” are resolved before simulation.

10. Simulation Context

#![allow(unused)]
fn main() {
pub struct PreflightContext {
    pub tenant: TenantId,
    pub project: ProjectId,
    pub environment: Option<EnvironmentId>,
    pub config: ConfigSnapshotId,
    pub policy: PolicyDigest,
    pub catalog_snapshot: CatalogSnapshotId,
}
}

11. Current State Snapshot

Simulation may depend on mutable current state.

Therefore capture exact point-in-time snapshot references where possible.

12. PreflightContextId

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

13. Side-Effect-Free Invariant

Preflight adapters MUST not:

deploy
publish
merge
apply
delete
rotate
sign
mutate production state

#![allow(unused)]
fn main() {
pub struct RiskFact {
    pub kind: RiskFactKind,
    pub severity: RiskSeverity,
    pub confidence: RiskConfidence,
    pub evidence: Vec<EvidenceRef>,
}
}

18. RiskFactKind

#![allow(unused)]
fn main() {
pub enum RiskFactKind {
    CompatibilityBreak,
    DestructiveSchemaChange,
    LargeBackfill,
    SecurityBoundaryChange,
    PrivilegeExpansion,
    NetworkExpansion,
    ProductionBlastRadius,
    IrreversibleChange,
    HighCost,
    LowRollbackConfidence,
    SloRisk,
    CapacityRisk,
    DataResidencyRisk,
    DependencyRisk,
    UnknownImpact,
}
}

19. Risk Severity

#![allow(unused)]
fn main() {
pub enum RiskSeverity {
    Informational,
    Low,
    Moderate,
    High,
    Critical,
}
}

20. Risk Confidence

#![allow(unused)]
fn main() {
pub enum RiskConfidence {
    Confirmed,
    Strong,
    Moderate,
    Weak,
    Unknown,
}
}

21. No Single Magic Score

Critical.

22. Optional Aggregate Risk Profile

#![allow(unused)]
fn main() {
pub struct RiskProfile {
    pub facts: Vec<RiskFact>,
    pub highest_severity: RiskSeverity,
}
}

#![allow(unused)]
fn main() {
pub struct AffectedComponent {
    pub component: SoftwareComponentId,
    pub reason: ImpactReason,
    pub confidence: ImpactConfidence,
}
}

26. Impact Reasons

direct file change
dependency edge
generated output
schema dependency
API consumer
deployment dependency

which jobs will exist
which matrix cells expand
which runners are required
which secrets are referenced
which network capabilities are needed

#![allow(unused)]
fn main() {
pub struct ResourceForecast {
    pub cpu_seconds: ForecastRange<u64>,
    pub memory_peak: ForecastRange<MemoryBytes>,
    pub gpu_seconds: ForecastRange<u64>,
}
}

36. Forecast Range

#![allow(unused)]
fn main() {
pub struct ForecastRange<T> {
    pub low: T,
    pub expected: T,
    pub high: T,
    pub confidence: ForecastConfidence,
}
}

#![allow(unused)]
fn main() {
pub struct CostForecast {
    pub expected: Money,
    pub low: Money,
    pub high: Money,
    pub basis: CostForecastBasis,
}
}

40. Cost Basis

historical jobs
provider pricing snapshot
runner class
estimated runtime
storage/egress

which rules match?
which approvals required?
which gates fail?
which exceptions apply?

44. PolicyPreviewId

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

45. Policy Explanation

#![allow(unused)]
fn main() {
pub struct PolicyPreview {
    pub decision: PolicyDecision,
    pub matched_rules: Vec<PolicyRuleRef>,
    pub required_approvals: Vec<ApprovalRequirement>,
}
}

current PolicyDigest
vs
candidate PolicyDigest

49. Show

newly allowed actions
newly denied actions
approval changes
affected projects/environments

50. Privilege Expansion

High-risk fact.

51. Security What-If

Can analyze:

new permissions
network expansion
secret scope expansion
runner trust reduction
unsigned artifact allowance
policy exception

resource deletion
database replacement
public endpoint exposure
IAM expansion
region move
storage destruction

target release
current release
compatibility
rollback target
blast radius
required rollout strategy

#![allow(unused)]
fn main() {
pub enum RollbackReadiness {
    Ready,
    Conditional,
    Unsafe,
    Unknown,
}
}

65. Migration Preflight

Part 63.

66. Migration Risk Facts

table rewrite
large backfill
lock risk
irreversible transform
old client incompatibility
insufficient backup

immediate
canary
regional
tenant pilot
manual approval
maintenance window

71. Recommendation Is Advisory

Part 62 policy decides.

72. Blast Radius Preview

#![allow(unused)]
fn main() {
pub struct BlastRadiusPreview {
    pub components: Vec<SoftwareComponentId>,
    pub environments: Vec<EnvironmentId>,
    pub tenants: ImpactSet<TenantId>,
    pub regions: Vec<RegionId>,
}
}

security approval
release approval
migration cutover approval
production deployment approval
break-glass requirement

76. Approval Requirement

Derived from policy.

77. Approval Preview Freshness

Becomes stale if:

policy changes
subject changes
environment changes

78. Merge Blocker Preview

Can combine:

tests
compatibility
security
policy
ownership
required approvals

#![allow(unused)]
fn main() {
pub struct PreflightDelta {
    pub added_risks: Vec<RiskFact>,
    pub removed_risks: Vec<RiskFact>,
    pub changed_impacts: Vec<ImpactChange>,
}
}

84. ScenarioId

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

85. What-If Scenario

#![allow(unused)]
fn main() {
pub struct WhatIfScenario {
    pub base: PreflightContextId,
    pub modifications: Vec<HypotheticalChange>,
}
}

86. HypotheticalChange

#![allow(unused)]
fn main() {
pub enum HypotheticalChange {
    Config(ConfigPatch),
    Policy(PolicyPatch),
    RunnerClass(CapacityClassId),
    Region(RegionId),
    RolloutStrategy(RolloutStrategy),
    ResourceLimit(ResourceOverride),
}
}

87. Scenario Must Be Non-Mutating

Critical.

88. Scenario Compare

Useful:

What if we use 8-core runners instead of 4?
What if production requires canary?
What if this policy blocks public egress?

#![allow(unused)]
fn main() {
pub struct PreflightResult {
    pub id: PreflightId,
    pub plan: PreflightPlanId,
    pub risks: Vec<RiskFact>,
    pub impacts: ImpactSummary,
    pub policy: PolicyPreview,
    pub cost: Option<CostForecast>,
    pub blockers: Vec<PreflightBlocker>,
}
}

92. Preflight Blocker

#![allow(unused)]
fn main() {
pub enum PreflightBlocker {
    PolicyDenied,
    MissingEvidence,
    CompatibilityBreaking,
    InfrastructureUnknown,
    SchemaDrift,
    SecurityCritical,
    UnsupportedOperation,
}
}

93. Warning vs Blocker

Explicit.

94. Preflight Completeness

#![allow(unused)]
fn main() {
pub enum PreflightCompleteness {
    Complete,
    Partial,
    Incomplete,
}
}

source graph
policy rule
compatibility report
infra plan
migration plan
cost snapshot
observability snapshot

98. Explainability

User can ask:

why high risk?
why approval required?
why this component affected?
why estimated cost increased?

99. Explain Graph

#![allow(unused)]
fn main() {
pub struct ExplanationEdge {
    pub from: EvidenceRef,
    pub relation: ExplanationRelation,
    pub to: PreflightFindingRef,
}
}

subject
context
policy
catalog snapshot
provider state snapshot
engine version

106. PreflightCacheKey

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

#![allow(unused)]
fn main() {
pub enum PreflightFreshness {
    Current,
    SubjectChanged,
    PolicyChanged,
    EnvironmentChanged,
    CatalogChanged,
    ProviderStateChanged,
    Expired,
    Unknown,
}
}

115. Merge Queue Integration

Final candidate preflight can be required before landing.

116. Release Integration

Release preflight can summarize:

compatibility
supply-chain
promotion
rollback

fleet impact
security generation
rollout risk

number of affected tenants
critical tenants
pilot eligibility

without exposing identities where user lacks permission.

128. Federation

Preflight considers:

region/site health
residency
authority
artifact availability

privileged policy what-if
production infrastructure preflight
security-sensitive impact preview
blast-radius override scenario

142. Routine Preflight

Operational event.

143. Dioxus UI

Pages/panels:

Preflight
Risk
Impact
Policy Preview
Cost Forecast
Scenario Compare

144. Change Proposal UI

Preflight tab.

145. Shows

affected components
required checks
risk facts
required approvals
estimated cost
rollout suggestion
blockers

forgeyard preflight change <proposal>
forgeyard preflight candidate <candidate>
forgeyard preflight deploy <plan>
forgeyard preflight migration <plan>
forgeyard preflight policy
forgeyard preflight scenario
forgeyard preflight explain
forgeyard preflight doctor

150. API

Potential:

POST /v1/preflight
GET  /v1/preflight/{id}
POST /v1/preflight/scenarios
GET  /v1/preflight/{id}/explain

151. Permissions

preflight.read
preflight.run
preflight.scenario
preflight.policy_preview
preflight.sensitive_impact

152. Policy Preview

May require elevated permission.

153. Observability Metrics

preflight_total
preflight_blocked_total
preflight_incomplete_total
preflight_cache_hit_total
preflight_duration_seconds

154. Labels

Low-cardinality:

subject_kind
result
completeness

155. Tracing

preflight.resolve
preflight.impact
preflight.policy
preflight.compatibility
preflight.cost
preflight.explain

156. Health

#![allow(unused)]
fn main() {
pub enum PreflightSubsystemHealth {
    Healthy,
    ImpactDegraded,
    PolicyDegraded,
    ProviderReadDegraded,
    IncompleteData,
    Unhealthy,
}
}

157. Doctor

forgeyard preflight doctor

Checks:

stale catalog snapshot
missing compatibility adapter
provider plan access unavailable
cost snapshot stale
policy evaluator mismatch
cache invalidation failures

merge evidence
release evidence
audit evidence

#![allow(unused)]
fn main() {
pub struct ForecastAccuracyRecord {
    pub preflight: PreflightId,
    pub actual_run: Option<RunId>,
    pub actual_deployment: Option<DeploymentId>,
}
}

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

active incident on target
recent incident recurrence
change freeze

forgeyard-preflight-testkit/src/
├── lib.rs
├── subject.rs
├── impact.rs
├── risk.rs
├── policy.rs
├── scenario.rs
├── cache.rs
└── assertions.rs

204. Core Tests

Identity

same subject/context yields same plan identity;
branch name resolves exact snapshot.

Side Effects

no deploy/apply/merge/publish during preflight;
provider mutation attempt rejected.

Risk

destructive schema change yields explicit risk fact;
unknown dependency widens impact.

Policy

preview does not grant authorization;
actual policy change invalidates preview freshness.

Compatibility

breaking API change surfaced.

Cost

forecast records basis/model/pricing snapshot.

Infrastructure

delete/replace exposure surfaced.

Scenario

hypothetical config/policy change remains non-mutating.

Security

sensitive tenant/resource existence not leaked to unauthorized caller.

Cache

provider/environment state change invalidates mutable result.

205. Chaos Tests

Inject:

provider read API outage
catalog unavailable
policy evaluator restart
cost service outage
compatibility analyzer failure

Expected:

partial/incomplete result
no false green
no side effects

206. Scale Tests

Test:

very large monorepo
thousands of impacted components
large tenant fleet
large infrastructure plans
many concurrent preflight requests

Preflight always binds an exact immutable subject.
Preflight context is versioned/snapshotted where needed.
Preflight performs no protected external side effect.
Provider planning is read-only or explicitly isolated.
Risk is expressed as typed facts.
Unknown risk/impact remains explicit.
No opaque score is sole policy authority.
Pipeline preflight uses canonical parser/planner.
Affected-work analysis uses Part 34 semantics.
Policy preview does not authorize execution.
Real execution re-evaluates current policy.
Compatibility preview uses exact contracts.
Infrastructure preflight never applies.
Migration preview never mutates schema/data.
Cost output is labeled forecast, not invoice.
Blast-radius unknowns do not become zero.
Approval preview never consumes approval.
Scenario analysis remains non-mutating.
Chosen scenario converts into normal canonical change.
Preflight freshness is explicit.
Stale preflight cannot become execution authority.
Missing providers/evidence produce Partial/Incomplete, not false Pass.
Sensitive impact information is authorization-filtered.
Preflight cannot be used as an authorization oracle.
AI can summarize but cannot replace deterministic risk facts.
Historical forecast remains immutable after actual outcome.
Forecast-vs-actual calibration is separate.
Federation/residency constraints appear in impact.
Air-gap preflight works with available local evidence.
Forgeyard dogfoods preflight on its own policy, infrastructure, migrations, deployments, runner images, and releases.

209. Production Readiness Gates

Do not call preflight architecture production-ready until:

side-effect-free adapters are enforced
exact subject/context identity is stable
policy preview cannot issue authority
unknown/incomplete cannot appear green
sensitive impact redaction passes
cache freshness/invalidation is correct
infra/migration/deployment preview integration works
forecast provenance is recorded
federation/air-gap behavior is tested
chaos/scale/security tests pass

210. Architectural Invariants

preflight is read-only;
subject identity is exact;
mutable context is versioned;
risk facts have provenance;
uncertainty is explicit;
no opaque score is authority;
preview does not authorize;
real execution rechecks policy;
canonical planners are reused;
no alternate simulation parser exists;
infrastructure preview never applies;
migration preview never mutates;
cost is forecast;
blast radius unknown is not zero;
approval preview does not consume approval;
scenario comparison is non-mutating;
stale result is not authority;
missing evidence cannot become green;
sensitive impact is permission-filtered;
preflight cannot become authz oracle;
AI remains advisory;
deterministic risk facts drive gates;
cache keys include relevant context;
mutable provider state invalidates;
historical forecast remains unchanged;
calibration is separate;
federation/residency are explicit;
preflight workers use least-privilege read identities;
no production write credential is required baseline;
Forgeyard dogfoods its own preflight system.

211. Final Target Architecture

                    Proposed Change
                         │
                         ▼
                    Exact Subject
                         │
                         ▼
                  Preflight Context
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
      Impact Graph     Policy         Risk Facts
          │              │              │
          └──────────────┼──────────────┘
                         ▼
                   Preflight Result
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
           Blockers    Approvals   Forecasts
                         │
                         ▼
                 Normal Change Workflow

What-if:

current state
    +
hypothetical config/policy/strategy
    ↓
read-only scenario
    ↓
compare risk / impact / cost
    ↓
choose
    ↓
create normal canonical change

The key guarantee is:

Forgeyard can tell engineers what a change is likely to affect before they execute it, while preserving a strict boundary between prediction and authority. Preflight analysis explains risk, impact, approvals, compatibility, and cost without applying the change or pretending uncertain future behavior is already known.

212. 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

Keyboard shortcuts

Forgeyard System Architecture & Engineering Documentation