[PLAN-0002] Milestone 2: Core Composition Engine¶

Status: Done

Implements: ADR-0010 (composition request/descriptor, synchronous provider pipeline, failure semantics, diagnostics tracing), ADR-0011 (scope, shared values, recursion detection, CreateMany semantics), ADR-0012 (path identity, deterministic random forking, CreateMany seed derivation), ADR-0013 (collection generation semantics), ADR-0014 (reflection-free collection dispatch via generator-emitted plans)

These five ADRs supersede the plan's original ADR-0007/0008/0009 basis after a deep design review of this plan's first draft — see each ADR's Links section for the supersession chain. ADR-0014 was added mid-Phase-2 (PR #11 review) to hold the collection-dispatch redesign originally recorded as ADR-0010's Amendment 3.

Goal¶

composer.Create<Customer>() and composer.CreateMany<Customer>(3) resolve a typical object graph (built-in primitives, enums, nullable value types, common collections, nested composable types via generated plans) through the real 9-stage resolution pipeline (docs/architecture.md), deterministically from a seed, with shared values reused correctly within one composition graph, recursive graphs failing with a readable diagnostic that names the cycle's edges instead of a stack overflow, and provider precedence covered by tests — per docs/mvp.md's Milestone 2 exit criteria.

Scope¶

Per docs/mvp.md's Milestone 2 section, mapped onto ADR-0010/0011/0012/ 0013's concrete shape:

The real CompositionContext (replacing Milestone 1's PlaceholderCompositionContext), the public CompositionRequestDescriptor generated code passes, and the internal CompositionRequest the context expands it into (ADR-0010).
The hybrid pipeline model: context-owned deterministic stages (explicit values, shared/scoped values, exact registrations, generated-plan dispatch, diagnostic failure) plus extensible ICompositionProvider collection stages (profile rules, semantic providers, test-double providers, built-in providers) — only the built-in-providers stage has anything registered in Milestone 2 (ADR-0010).
CompositionResult (NotHandled/Success for ordinary providers; authoritative Failure reserved to context-owned stages).
CompositionPath (structured PathSegment chain — constructor parameter/member name, collection index, dictionary key/value role) and a distinct active-construction-frame stack for recursion detection (ADR-0011, ADR-0012).
IRandomSource — root CompositionSeed, FNV-1a-keyed structural forking over PathSegment data, a Compono-owned PRNG (not System.Random) (ADR-0012).
Built-in value providers for every type docs/mvp.md lists (string, bool, integral/floating-point types, decimal, Guid, DateTime, DateTimeOffset, DateOnly, TimeOnly, TimeSpan, enums, nullable value types, arrays, List<T>, IReadOnlyList<T>, HashSet<T>, Dictionary<TKey, TValue>) — this list may shrink if implementation complexity threatens the milestone, per docs/mvp.md. Collection providers built against ADR-0013's semantics (default size 3, bounded duplicate-value retry for both Dictionary<TKey, ...> keys and HashSet<T> elements, no ordering guarantee for HashSet<T>/ Dictionary<TKey, TValue>), dispatching element/key/value resolution through a cached generic-delegate bridge rather than per-value reflection (ADR-0010's amendment).
CompositionScope (one per root composition operation, type-keyed sharing) and an internal, type-keyed exact-registration store the pipeline's stage 3 queries (mechanism only — no public builder API; see ADR-0011's scope note).
The allocation-free-on-success diagnostics trace buffer (ADR-0010) and the structured diagnostic it materializes on failure.
Composer.Create<T>() rewired onto the real CompositionContext (replacing the Milestone 1 placeholder), plus the new Composer.CreateMany<T>(count).

Explicitly deferred (later milestones per docs/mvp.md):

Any public configuration surface — Composer.Create(builder => ...), .Register(), .AddProfile(), profiles, collection-size configuration — all Milestone 3. Milestone 2 exercises registrations/scope through an internal test seam only (ADR-0011).
The [Shared] attribute and any xUnit-specific composition context — Milestone 4. Milestone 2 builds the scope mechanism [Shared] will attach to, not the attribute itself.
NSubstitute/Bogus providers — Milestones ⅚. Their pipeline stages (⅘/6) exist and run as empty provider collections in Milestone 2.
Name/qualifier-keyed sharing, semantic hints, custom-attribute-based request metadata, generic context, requested lifetime, "test double acceptable" — all deferred per ADR-0010/0011 until a later milestone has a concrete consumer.
An async provider contract — explicitly out of scope per ADR-0010; add only if a real need appears, as a distinct opt-in contract.
Promoting any internal engine type (CompositionRequest, ICompositionProvider, CompositionResult, IRandomSource) to public — deferred until the milestone that actually gives it a consumer (ADR-0010's Visibility decision).

Execution Flow: `composer.Create<Customer>()`¶

Written out once, in full, so "does the root type go through the same pipeline as nested types" and "how does a generated plan avoid recursively redispatching itself" have one unambiguous answer instead of being inferred per-phase. Assume:

public sealed record Customer(string FirstName, string LastName, Address HomeAddress);
public sealed record Address(string Street, string City);

Root request creation. Composer.Create<Customer>() calls the internal CompositionContext.ResolveRoot<Customer>() — a distinct entry point from the public, descriptor-based Resolve<T>() generated code uses (ADR-0010's amendment). There is no root case on CompositionRequestDescriptor/ CompositionRequestKind — a root request has no name and isn't generator-emitted, so it never needs the public member-request shape at all. ResolveRoot<T>() constructs the internal CompositionRequest directly (RequestedType = typeof(Customer), root path node, no segment) and hands off to the same private pipeline-execution method the descriptor path uses.
Scope and seed creation. A fresh CompositionScope (empty, per ADR-0011 — one per root composition operation), a root CompositionSeed (explicit if one was configured — no builder exists yet in Milestone 2, so this is always the generated case for now — or generated once for this call), an empty root CompositionPath (just the Customer node, no segment), an empty active-construction-frame stack, and a fresh (empty) diagnostics trace buffer are all created together and held by one new CompositionContext instance scoped to this single Create<T>() call.
Root resolution — same pipeline as any nested type. ResolveRoot<Customer>() and a nested Resolve<Address>() call inside Customer's own generated plan both funnel into the exact same private pipeline-execution method — the entry point differs (internal root call versus public descriptor expansion), but the pipeline they run is identical. There is no special-cased root path: stages 1–7 are tried in order (explicit value → shared/scoped → registration → profile → semantic → test-double → built-in), and for an ordinary domain type like Customer all seven return NotHandled (nothing claims a plain record type), falling through to stage 8.
Generated-plan discovery. Stage 8 reads PlanCache<Customer>.Instance (ADR-0004's direct field read). It's non-null (the generator produced a plan for Customer, reachable from this very Create<Customer>() call site). Before invoking it, the context checks the active-construction-frame stack for typeof(Customer) — empty, no cycle — pushes a Customer frame, and proceeds.
Invocation of ICompositionPlan<Customer>. PlanCache<Customer>.Instance.Compose(context) runs. For each constructor parameter, generated code calls context.Resolve<TParam>(descriptor) with a descriptor naming that parameter (Kind = ConstructorParameter, Ordinal = 0, Name = "firstName", etc. — Ordinal is the identity the fork key and active-construction bookkeeping actually use; Name is carried for diagnostic display only, per ADR-0012's amendment) — never touching CompositionPath or the frame stack directly.
Nested Resolve<T>() calls. For firstName, the context expands the descriptor into an internal CompositionRequest, appends a ConstructorParameter(Ordinal: 0, Name: "firstName") segment to the path (now Customer → firstName, hashed on Ordinal), and runs the same 9-stage pipeline against it, fresh, as its own independent evaluation. On return (success or failure), the appended segment is popped in a finally — the path is back to just Customer before the next parameter is resolved.
Provider resolution. For firstName (string), stage 7's built-in string provider claims it (Success) — stages 1–6 all declined. No recursion check is involved at all for this request, because it never reaches stage 8 (strings have no generated plan). lastName resolves identically.
Nested generated-plan dispatch. For homeAddress (Address), the same expansion happens (path becomes Customer → homeAddress), stages 1–7 decline, stage 8 finds PlanCache<Address>.Instance, checks the frame stack (Customer is active, Address is not — no cycle), pushes an Address frame, and invokes PlanCache<Address>.Instance.Compose(context). This is a genuinely independent, nested invocation of the same Resolve<T> machinery — not Customer's plan calling itself. Address's own constructor parameters (street, city) resolve the same way, with the path now Customer → homeAddress → street / → city. When Address's Compose returns, its frame is popped in finally.
Path push/pop behavior, summarized. Because Resolve<T> is an ordinary synchronous method calling itself recursively (through generated plans calling back into it), path segments and construction frames both push on entry and pop in finally on exit — entirely as a side effect of the call stack. Neither generated code nor any provider ever manipulates either structure directly; there is no way to "forget" a pop, because there's no manual bookkeeping to forget.
Failure propagation. If, say, city's resolution fails (every stage returns NotHandled, reaching stage 9's diagnostic failure), that Resolve<string> call — which must return a string, not a wrapped result, since ICompositionPlan<T>.Compose returns a plain T — throws a CompositionException carrying the materialized diagnostic (path at time of failure: Customer → homeAddress → city; seed; the trace-buffer slice for this failed request). That exception propagates up through Address's Compose (unwinding its finally blocks — the Address frame and the homeAddress segment both pop as the stack unwinds), through Customer's Compose (Customer's frame and the root pop too), and out of Composer.Create<Customer>() to the caller. The pipeline's internal NotHandled/Success return-value convention (ADR-0010) never itself throws — only the outward-facing Resolve<T>/Create<T>() boundary converts a terminal non-Success outcome into the thrown CompositionException docs/public-api.md already shows consumers catching.

CreateMany<T>(count) repeats steps 1–10 count times, each with its own fresh scope/path/frame-stack/trace-buffer (ADR-0011's "fresh scope per item"), differing only in step 2: each item's root CompositionSeed is forked from the batch's root seed via "CreateMany" then the item's index (ADR-0012), rather than being the batch's root seed directly.

Phases¶

Ordered per the user's explicit preference during design review: seed, path identity, and the random source come before built-in providers are implemented, so providers are written against their real, final randomness source from the start — never against ad hoc randomness that a later phase has to rip out and rewire. Each phase either unblocks the next or closes a real gap against the exit criteria. Each phase ships as its own PR — don't bundle phases into one diff even if more than one is finished by the time a PR gets opened.

Phase 0 — Composition request, descriptor, and pipeline skeleton (Done)¶

Replaces Milestone 1's PlaceholderCompositionContext with the real CompositionContext, wired to the hybrid pipeline model (context-owned stages + extensible-provider collections). Stage 8 (generated-plan dispatch via PlanCache<T>) is already fully functional from Milestone 1 — this phase doesn't add it, it wires the rest of the pipeline around it. Stages 1–3 (explicit values, shared/scoped, exact registrations) are context-owned checks that are always NotHandled in this phase (no scope or registration store exists until Phase 3); stages 4–6 (profile/semantic/test-double) are provider collections that are always empty until Milestones 3/6/5 respectively; stage 7 (built-in providers) is an empty collection until Phase 2. So in this phase, a request resolves successfully only for a type with a generated plan reachable from a Create<T>()/CreateMany<T>() call site (Milestone 1 behavior, now running through the real pipeline instead of the placeholder) — everything else correctly reaches stage 9's diagnostic failure until later phases populate the stages that would have handled it.

CompositionRequestDescriptor (public readonly struct — plain, not a record struct; equality/Deconstruct/ToString aren't part of its contract, per ADR-0010's second amendment — with Kind, Ordinal, Name, Nullability; Ordinal is identity, Name is diagnostic-only) and CompositionRequestKind enum (ConstructorParameter, RequiredMember — no Root case; the root never uses this type, see ResolveRoot<T>() below)
CompositionRequest (internal: RequestedType, Nullability, Path, IsShared — expanded from a descriptor by the context)
CompositionResult (internal, NotHandled/Success only — no Failure case an ordinary provider can construct)
ICompositionProvider (internal, non-generic, TryCompose(CompositionRequest, ICompositionContext))
CompositionContext implementing ICompositionContext.Resolve<T>(in CompositionRequestDescriptor) (descriptor expansion path, used by generated code) and an internal ResolveRoot<T>() (constructs the root CompositionRequest directly, bypassing the descriptor entirely — ADR-0010's amendment); both funnel into one private pipeline-execution method running stages 1–9 in order
Internal test-seam constructor/factory on CompositionContext accepting explicit per-stage provider collections for stages 4–7 (ADR-0010's amendment), reachable from Compono.Tests via InternalsVisibleTo — this is how this phase's own pipeline-order tests inject fake ICompositionProvider test doubles into a specific stage without any public configuration surface existing
Rewire Composer.Create<T>() off PlaceholderCompositionContext onto the real CompositionContext (calling ResolveRoot<T>())
Unit tests: pipeline tries stages in documented order (using the internal test-seam factory to inject fake providers at specific stages and assert call order); a stage returning Success short-circuits later stages; a type with a generated plan resolves successfully through the real pipeline (Milestone 1 behavior preserved); a type with no generated plan and nothing else able to handle it throws CompositionException with a structured diagnostic