[Foundation] Epic: Engine de-statification & extension-pipeline formalization (plugin foundation)

[ChrisonSimtian]

Epic: Engine de-statification & extension-pipeline formalization

Foundation work for the plugin architecture (this milestone). The current engine bootstraps per-run state into process-global statics, walks targets strictly sequentially, and discovers extensions via magic priority numbers with non-deterministic tie-breaking. This epic makes the engine reentrant, test-isolatable, parallel-ready, and plugin-ready — entirely via backwards-compatible (facade-preserving) refactors.

All public static build properties (FalloutBuild.RootDirectory, Verbosity, Host, …) are preserved as facades over an internal BuildContext — no public breakage, so this stays on the 2026 line and does not need the year-cut breaking-change flow.

Out of scope

• Caching / incrementality. Verified there is zero infrastructure for it today (only the coarse --continue invocation-hash). It's a large, product-level decision and the "delegate to MSBuild" stance is defensible. Tracked separately if/when desired.

Tickets & dependency order

• [Foundation] FT-1: Fix cross-invocation static-state leaks (event handlers, log sink, verbosity mappings) #306 — FT-1: Fix cross-invocation static-state leaks (bug, S, no deps — ship first)
• [Foundation] FT-2: Introduce internal BuildContext + ambient activation #307 — FT-2: Introduce internal BuildContext + ambient activation (L, deps FT-1)
• [Foundation] FT-3: Convert public static build properties to BuildContext-backed facades #308 — FT-3: Convert public statics to BuildContext-backed facades (M, deps FT-2)
• [Foundation] FT-4: Make ParameterService instance-based and re-parseable #309 — FT-4: Instance-based, re-parseable ParameterService (M, deps FT-2)
• [Foundation] FT-5: Context-scope tool-path resolvers and process defaults #310 — FT-5: Context-scope tool-path resolvers + process defaults (M, deps FT-2)
• [Foundation] FT-6: Make logging thread-safe and per-run scoped (prereq for parallel execution) #311 — FT-6: Thread-safe, per-run-scoped logging (M, deps FT-2; prereq FT-8)
• [Foundation] FT-7: Formalize the build extension pipeline (deterministic ordering + typed phases) #312 — FT-7: Formalize the extension pipeline (M, deps FT-2)
• [Foundation] FT-8: Opt-in DAG-parallel target execution #313 — FT-8: Opt-in DAG-parallel target execution (L, deps FT-3/4/5/6)
• [Foundation] FT-9: Reentrancy/isolation test harness #314 — FT-9: Reentrancy/isolation test harness (S, deps FT-1..FT-5)

FT-1 ─▶ FT-2 ─┬─▶ FT-3 ─┐
              ├─▶ FT-4 ─┼─▶ FT-8 (parallel exec)
              ├─▶ FT-5 ─┤
              ├─▶ FT-6 ─┘
              └─▶ FT-7
        FT-1..FT-5 ─▶ FT-9 (isolation tests)

Evidence base

Findings grounded in: BuildManager.cs, BuildExecutor.cs, ExecutionPlanner.cs, ExecutableTargetFactory.cs, FalloutBuild.Statics.cs, FalloutBuild.Events.cs, Logging.cs, ParameterService.Statics.cs, EnvironmentInfo.Arguments.cs, VerbosityMappingAttribute.cs, Fallout.Core/Planning/TopoSort.cs. Verified: execution is strictly sequential; there is no input/output caching.

[ChrisonSimtian]

Architecture assessment — why BuildContext, not Generic Host, not a full DI container

Recording the rationale behind this epic so the design choice is durable. This is an independent read of the engine grounded in the current code (file:line throughout), plus the reasoning for the de-statification approach we picked over the alternatives (and why #89 — full DI container — was correctly superseded).

TL;DR

There are effectively three codebases stacked here, at very different quality levels:

1. Domain core (Fallout.Core) — clean. TopoSort is a pure function (no I/O, no input mutation, no ambient reads); ExecutableTarget / ExecutionPlan are effectively immutable. Keep as-is.
2. Authoring DSL surface — clean and deliberate. Target X => _ => _.DependsOn(...).Executes(...), RootDirectory / "out", DotNetBuild(...). The static-ness here is an intentional ergonomics choice (same as Cake/MSBuild). Must stay static — do not "fix" it.
3. Orchestration engine — the debt. A god class plus process-global mutable statics. This is the only layer this epic touches.

The fix is an internal BuildContext (ambient, per-run) with the static surface preserved as facades over it — not Microsoft.Extensions.Hosting (IHost), and not a full Microsoft.Extensions.DependencyInjection container. Rationale at the bottom.

---

Current architecture (as-is)

flowchart TB
    subgraph SURF["Authoring DSL surface — clean, deliberate (KEEP)"]
        T["Target Compile => _ => _.DependsOn(...).Executes(...)"]
        F["static facades: DotNetBuild(), RootDirectory, Verbosity, Host"]
    end
    subgraph ENG["Orchestration engine — the debt"]
        BM["BuildManager (static)<br/>Execute&lt;T&gt; = composition root + Console wiring + events"]
        FB["FalloutBuild god class<br/>base class + orchestration state + output + extension host"]
        BE["BuildExecutor (static, sequential ForEach)"]
        STATE["process-global MUTABLE statics<br/>Logging.LevelSwitch / InMemorySink.Instance<br/>ParameterService.Instance / ValueInjection cache<br/>NuGetToolPathResolver.* / cancellation handlers"]
    end
    subgraph CORE["Domain core: Fallout.Core — clean (KEEP)"]
        TS["TopoSort (pure)"]
        ET["ExecutableTarget / ExecutionPlan (immutable)"]
    end
    SURF --> ENG --> CORE
    BM -.- STATE
    FB -.- STATE
    BE -.- STATE
    classDef good fill:#e3f6e3,stroke:#2a2,color:#000;
    classDef bad fill:#ffe0e0,stroke:#d33,color:#000;
    class SURF,CORE,TS,ET,T,F good
    class STATE bad

Loading

How a run actually touches global state, and where it leaks across invocations:

flowchart TD
    Main["Build.Main()"] --> Exec["BuildManager.Execute<T>()"]
    Exec --> W1["Console.CancelKeyPress +=<br/>ToolOptions.Created +=<br/>CancellationHandler += Finish"]
    Exec --> NewT["new T() : FalloutBuild"]
    NewT -. "static ctor" .-> SC["FalloutBuild.Statics:<br/>RootDirectory, Host, Verbosity"]
    Exec --> Cfg["Logging.Configure() → global Log.Logger"]
    Exec --> Res["NuGetToolPathResolver.* = build.*"]
    Exec --> BE["BuildExecutor.Execute (sequential)"]
    BE --> PS["ParameterService.Instance"]
    BE --> VC["ValueInjectionUtility.s_valueCache"]
    BE --> FS["File.AppendAllLines(BuildAttemptFile)"]
    BE --> IO["Host.Error() / Console"]

    classDef leak fill:#ffe0e0,stroke:#d33,color:#000;
    class W1,Cfg,Res,PS,VC,FS,IO leak

Loading

Problems (all in the engine, red nodes above):

• God class — FalloutBuild is 456 LOC across 5 partials with 4 responsibilities: inheritable base class (FalloutBuild.cs), process-global state + static ctor (FalloutBuild.Statics.cs:16-30), output formatting (FalloutBuild.Output.cs), extension host (FalloutBuild.Events.cs). The partials hide the size, not the coupling.
• Static state leaks across runs — BuildManager.cs:20,41,69 (handlers accumulate), Logging.cs:20,214 (LevelSwitch + InMemorySink.Instance carry log events over), ValueInjectionUtility.cs:13 (s_valueCache persists), NuGetToolPathResolver.cs:14-17 (set per-run at BuildManager.cs:53-56, never reset). → tracked by #306.
• Test/prod path divergence (the smoking gun) — production reads the static ParameterService.Instance (ParameterService.Statics.cs:11-13), but ParameterServiceTest.cs:14-22 constructs a fresh ParameterService(funcs) to inject args. Tests exercise a different object than production. → #309.
• No DIP seams — BuildManager.cs:39-41 pokes Console directly; BuildExecutor.cs:81 writes the filesystem directly; output goes through static Host.Error(). Nothing substitutable.

What's already good (and stays): planning vs execution is cleanly split (ExecutionPlanner vs BuildExecutor); extension discovery is deterministic (FalloutBuild.Events.cs:21-25, source-order + stable priority sort) and fully visible in one place (FalloutBuild.cs:45-62); parameter injection is type-safe/lazy via expressions.

---

Target architecture (to-be) — clean where it makes sense

flowchart TB
    subgraph SURF["Authoring DSL surface — UNCHANGED (static facades preserved)"]
        F["DotNetBuild(), RootDirectory, Verbosity, Host"]
    end
    subgraph ENG["Engine — de-statified"]
        CR["BuildManager.Execute&lt;T&gt;<br/>= composition root: build + activate context, run, dispose"]
        CTX["BuildContext (internal, per-run, ambient via AsyncLocal)<br/>owns: parameters, logging scope, tool-path config, cancellation"]
        ORCH["BuildOrchestrator (instance)<br/>replaces BuildManager/BuildExecutor statics"]
    end
    subgraph CORE["Fallout.Core — UNCHANGED (already clean)"]
        TS["TopoSort (pure) + immutable ExecutionPlan"]
    end
    F -. "read through" .-> CTX
    CR --> CTX
    CR --> ORCH
    ORCH --> CTX
    ORCH --> CORE
    OUT["OUT OF SCOPE BY DESIGN:<br/>Generic Host / IHost — one-shot console, no hosted services<br/>full DI container — BuildContext is lighter and sufficient"]

    classDef keep fill:#e3f6e3,stroke:#2a2,color:#000;
    classDef change fill:#e0ecff,stroke:#36c,color:#000;
    classDef no fill:#f3f3f3,stroke:#999,color:#555;
    class SURF,CORE,F,TS keep
    class CTX,ORCH,CR change
    class OUT no

Loading

Maps directly onto the FT tickets in this epic:

Change	FT ticket
Fix the cross-invocation leaks first (non-breaking, size S)	#306 FT-1
Internal BuildContext + ambient activation	#307 FT-2
Static build properties → facades over BuildContext.Current	#308 FT-3
ParameterService instance-based + re-parseable (kills test/prod divergence)	#309 FT-4
Context-scope tool-path resolvers + process defaults	#310 FT-5
Per-run, thread-safe logging scope	#311 FT-6
Formalize the extension pipeline (deterministic phases)	#312 FT-7
Reentrancy/isolation test harness (locks in the invariant)	#314 FT-9

The god-class split (base class / orchestration state → BuildOrchestrator / output formatter) rides along with FT-2/FT-3 rather than as a separate breaking step.

---

Why not IHost, why not a full DI container

• Generic Host (HostApplicationBuilder / IHost) is the wrong shape. It exists for long-running processes — IHostedService/BackgroundService, host lifetime, graceful shutdown. A Fallout build is a one-shot synchronous pass returning an int exit code (BuildManager.cs:74) with cancellation already hand-wired (BuildManager.cs:20-26,41). IHost would add ceremony for zero payoff.
• A full DI container is heavier than needed. This is why #89 (introduce an MS.DI container) was superseded: the ambient BuildContext gives us reentrancy + testability + a single composition root without forcing constructor-injection through a surface that is, by design, static. DI is available (net10.0 everywhere, global.json:3) and we may register a small service set inside Execute<T>(), but the container is not the architecture — the context is.
• The static surface cannot become instance-injected without breaking consumers. DotNetBuild(...) (DotNet.Generated.cs:22-62) and RootDirectory (read unqualified inside instance members) have no this to inject into. The facades reach an ambient accessor — the same pattern already used by ParameterService.Instance and Host.Instance. So we relocate ambient state behind a context; we don't eliminate it.

Honest caveat

Because the real "injection" today is reflection-based attribute middleware (FalloutBuild.cs:45-62) + ambient singletons, this is plumbing modernization, not an IoC inversion. The wins are concrete — safe reentrancy, real unit-testability of ParameterService/resolvers, one composition root, and it unblocks opt-in parallel execution (#313) — but incremental. Worth setting that expectation so nobody pitches this as a clean-architecture rewrite. The core domain and the authoring DSL are already where they should be; this epic is about the engine in between.

[ChrisonSimtian]

Design note: GitHub as the worked example for plugin extraction

Added a concrete design note grounding this foundation work in a real first-party extraction — docs/plugin-extraction-github.md (uses GitHub-CI as the canonical case, i.e. the dogfood proof named in #187 / SDK-11).

Key findings:

• The seams a plugin model needs mostly already exist — Host / IBuildServer / ConfigurationAttributeBase / the IBuildExtension listeners are real abstraction points. Extraction is "formalize three seams + split one assembly," not "invent a plugin system."
• "The GitHub plugin" is a bundle of 5 contributions scattered across 3 assemblies today: CI host (GitHubActions : Host, IBuildServer), config generator (GitHubActionsAttribute), tool wrapper (GitHubTasks/Octokit), component (ICreateGitHubRelease), theme. Maps ~1:1 onto SDK-6a..6f ([SDK-6a] Extension point: IBuildMiddleware #151–[SDK-6f] Extension point: IOutputSink #156).
• This epic is the hard prerequisite. Plugin activation must resolve the host from the per-run BuildContext (FT-2 [Foundation] FT-2: Introduce internal BuildContext + ambient activation #307 / FT-3 [Foundation] FT-3: Convert public static build properties to BuildContext-backed facades #308), not the Host.Instance process global, or reentrancy / multiple plugins / test isolation break.

Three seams to formalize:

1. Host detection — magic-named IsRunning<Name> static + AppDomain scan → typed registry + IHostDetector.IsActive(env) ([SDK-6b] Extension point: IHost + IHostDetector #152, Refactor Host activation: replace by-name reflection with a typed HostRegistry #426).
2. Ambient singleton → context (this epic).
3. Per-provider config attribute — mechanism unchanged, type just ships from the plugin package (runs via reflection at build-tool exec, no analyzer-packaging burden).

Staged path (steps 1–4 in-repo before any physical split): carve Fallout.Plugin.Sdk (#146/#147) → formalize seams (#152/#148/#426) → move GitHub to in-repo Fallout.Plugin.CI.GitHub (#158/#187) → Fallout.Common back-compat meta-package → lift to side-by-side repo (~zero code change, gated on milestone #7).

Caveats flagged: VCS is not symmetric with CI — only a concrete git-only GitRepository, no IVcs interface; pluggable VCS needs a new abstraction first. Splitting Fallout.Common + moving public ICreateGitHubRelease are the consumer-facing breaks (meta-package + [Obsolete] type-forward shim mitigate).

Open questions for design (in the note): IHost vs existing Host name collision; whether tool-wrapper plugins ship pre-generated .cs or run the generator; long-term home for ICreateGitHubRelease.

[ChrisonSimtian]

Plugin-extraction design note — rounds 2–3 update

Following up on the earlier comment. docs/plugin-extraction-github.md now carries a type-by-type move manifest, three locked decisions, three design sketches, and a multi-provider validation pass. Highlights since round 1:

Decisions locked.

• A — host is implemented, not inherited. Plugins implement IHost/IHostDetector + opt-in capability interfaces; Fallout.Core has zero awareness of how a host detects/presents. Heavy presentation (logo, target-outcome table, Serilog) stays engine-side as defaults.
• B — config-gen reads ITargetModel, not ExecutableTarget. That projection already exists in Fallout.Core (self-documented as the SDK-facing view); ExecutableTarget already implements it. Gaps: add ArtifactProducts/ArtifactDependencies to the interface + change the GetConfiguration signature. Full ExecutableTarget→Core move ([Foundation] Extract Fallout.Core domain project #88) deferred, not required.
• C — breaking changes acceptable on the 2026 line, ship sooner. Shims are opt-in polish, not a gate. The one hard line is the SDK 1.0 additive-only freeze.

Load mechanic mostly already exists. BuildManager.Initialize() ([ModuleInitializer]) already force-loads referenced assemblies via DependencyContext (.deps.json) — the exact fix for "referenced-but-unused assembly isn't loaded." A first-party Fallout.Plugin.CI.GitHub would load as-is; only the StartsWith("Fallout.") filter needs broadening for third-party. Discovery flips from today's GetTypes() type-walk + magic IsRunning{Name} statics to a single [assembly: FalloutPlugin] read + builder.AddHost<>(). Today's host selection (Host.Default…First()) is silent winner-takes-all — moving to detector+priority+throw is a behavior improvement (RFC #101).

Multi-provider validation (GitHub/Azure/GitLab/Bitbucket + out-of-tree Gitea/Forgejo). Composition confirmed — GitLab = detect+branch/commit+theme, Bitbucket = detect+branch/commit only; a god base forces empty overrides. Two refinements:

1. Don't build one fat IHostOutput. Azure overrides ~12 output cmds vs GitHub's ~6, barely overlapping beyond grouping + issue annotation. Segregate into small portable interfaces (IBuildLogGrouping, IBuildIssueReporter); leave the provider-specific tail on the plugin's own public type.
2. IHostDetector.Priority is mandatory. Gitea/Forgejo Actions set GITHUB_ACTIONS=true plus their own var → both detectors match on a Gitea runner → RFC [RFC #5] Conflict resolution semantics between plugins #101 single-winner conflict resolved by priority.
3. New SDK requirement: plugin-on-plugin reuse — Gitea/Forgejo Actions are GitHub-Actions-compatible, so those plugins should reuse GitHub's impl. Plugin packages must be allowed to depend on/extend each other, not only the SDK.

Next: probing the VCS side (no IVcsProvider exists today — the asymmetric, harder half of the "VCS + CI as plugins" goal).

[ChrisonSimtian]

Plugin-extraction note — round 4 (VCS axis)

Full note now lives on a branch: docs/plugin-extraction-github.md. Probed the VCS side; it inverts the earlier "VCS is the harder, asymmetric half" assumption — VCS is lighter than CI.

Git core is already platform-agnostic. GitRepository (src/Fallout.Build/VCS/GitRepository.cs) parses .git + remote URLs into a host-neutral model (Endpoint, Identifier, branch/commit/tags/remote). No GitHub baked in — it already works for gitlab.com, self-hosted gitea, bitbucket.org. Git is the substrate, not "a VCS provider among many."

"VCS" conflates two orthogonal axes:

• VCS kind (git/SVN/hg) — how you read a working copy. Git = dominant built-in; SVN/hg = rare, community-on-demand behind a reserved IVcsReader slot.
• Host/forge flavour (github.com/gitlab.com/gitea/GHE) — still git, just endpoint-specific API & naming. This is what actually differs between GitHub and GitLab, and it's not a VCS concern — it rides inside the platform plugin. GetGitHubOwner/Name (GitHubTasks.cs:134-140) already just split the generic Identifier; they belong in the GitHub plugin next to Octokit GitHubTasks.

So "the GitHub plugin" is one cohesive package: CI host + config-gen + forge API + git-host flavour + release component. No separate "GitHub VCS plugin."

Recommendation: don't build IVcsProvider now (premature for a near-empty set — TFS dead, SVN/hg long-tail). Keep GitRepository concrete; reserve the IVcsReader extension-point slot in the RFC #98 catalogue, ship only the Git impl. The only platform coupling in the core git type is the same Host.Instance as IBuildServer ambient seam already on the critical path (FT-2/FT-3).

Branch-naming conventions (IsOnMainBranch/IsOnReleaseBranch…) are git-generic → stay core/SDK.

Recurring theme across all four rounds: the seams already exist (ITargetModel in Core, the [ModuleInitializer] DependencyContext force-load, generic GitRepository). The work is formalizing + relocating, not inventing.

[ChrisonSimtian]

Round-5 finding (log masking) is now filed as #443 — a plugin-SDK security prerequisite: [Secret] is a passive marker today, no scrubber exists, so a full-trust plugin can leak resolved secrets to logs. Must land before the SDK exposes resolved secrets to third-party plugins.