Native dependency injection - Verification and traceability

Platform spec article

Native dependency injection - Verification and traceability

Back to Native dependency injection ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (10)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   Sibling articles defer to this hub for MUST/SHOULD authority.

   Context

   Composition articles and compiler notes mixed informal wiring guidance with normative host syntax.

   Decision

   This feature hub must own normative MUST/SHOULD contract text. Sibling articles must not redefine hub requirements and should link here for authority.

   Consequences

   FAQ locked decisions migrate to ADRs; articles retain examples and troubleshooting tables only.

   Verification anchors

   /platform-spec/language-meta/composition/dependency-injection/; verify:trudoc.

   Open full ADR page

2. 0002-compile-time-resolution Composition graph resolved at compile time Accepted

   Backends do not perform runtime service lookup for app DI.

   Context

   Runtime DI containers hide wiring and conflict with the project's explicit composition goals (distinct from Rust pipeline IoC in D-INC-0002).

   Decision

   The reference compiler must fully resolve the app composition graph at compile time. Backends must not perform runtime service lookup for host / registry / scope wiring.

   Consequences

   Lowering emits ctor wiring and scope enter/leave; execution hosts activate frozen graphs only.

   Verification anchors

   compiler/crates/beskid_analysis (planned composition module); compiler/crates/beskid_codegen; Flow and algorithm.

   Open full ADR page

3. 0003-field-inject-only Field inject only Accepted

   Constructor parameter inject is rejected (E1712).

   Context

   Constructor injection churns signatures across inheritance and complicates lowering.

   Decision

   inject must apply to fields on ordinary types only. Constructor-parameter inject must be rejected (E1712).

   Consequences

   Uniform type headers and a single slot-lowering story for injected fields.

   Verification anchors

   Design model; FAQ.

   Open full ADR page

4. 0004-registry-spelling registry spelling locked Accepted

   Global registrations use registry block name registry.

   Context

   Early drafts considered alternate container keywords.

   Decision

   The global registration block must be spelled registry (locked for v0.2+).

   Consequences

   Parser, diagnostics, and docs use one keyword; no alias container in Standard conformance.

   Verification anchors

   Grammar and semantic snapshots when composition lands.

   Open full ADR page

5. 0005-global-and-scope-stack Global scope and named scope stack Accepted

   Resolution walks innermost named scope toward global.

   Context

   Authors need predictable scope boundaries for web and console activation patterns.

   Decision

   Construct	Rule
   Global	Merged registry of the launched host after inheritance chain
   Named scope	Tree under global; per-activation unless single / transient
   Stack	Fiber-local scope stack during with
   Resolution	Walk innermost → global; global:: and parent:: qualifiers as specified

   Consequences

   Execution backends maintain scope enter/leave with with; plural inject collects at lowest matching level.

   Verification anchors

   Design model; Execution.

   Open full ADR page

6. 0006-plural-inject-array Multiple implementations via inject T[] Accepted

   Singular inject must be unique at the resolution level.

   Context

   Apps register multiple implementations of one contract (for example two Storage).

   Decision

   Multiple implementations must use inject Contract[] (or concrete T[]). Singular inject Contract must be unique at the resolution level (E1705 when ambiguous).

   Consequences

   Deterministic registration merge order defines array element order.

   Verification anchors

   Design model; FAQ.

   Open full ADR page

7. 0007-many-hosts-one-launch Many host types one launch per run Accepted

   Exactly one launch per process invocation.

   Context

   Libraries ship reusable composition roots; executables pick one entry host per run.

   Decision

   Projects may declare many named host types. Each process run must use exactly one launch Host(args) on an executable target (E1702 for duplicate launch on one path).

   Consequences

   Manifest app targets name the launched host; multi-app repos use separate targets, one launch each run.

   Verification anchors

   Contracts and edge cases; Project manifest.

   Open full ADR page

8. 0008-lib-forbids-launch Lib targets forbid launch Accepted

   Libraries may declare host types but not launch.

   Context

   Test and library packages attempted to embed process entry via launch.

   Decision

   Lib project targets may declare host types for reuse but launch is forbidden (E1711). Only app/test host targets may launch.

   Consequences

   Consumers reference library hosts from their own app targets or approved harness entries.

   Verification anchors

   FAQ.

   Open full ADR page

9. 0009-composition-resolve-phase composition.resolve pipeline placement Accepted

   Resolves after semantic.snapshot before mod.analyze.

   Context

   Compiler mods need a frozen composition snapshot but must not mutate app graphs.

   Decision

   Pipeline phase composition.resolve must run after semantic.snapshot and before mod.analyze (see Stage ordering).

   Consequences

   Mods query read-only snapshots; app graph build stays in analysis.

   Verification anchors

   compiler/crates/beskid_pipeline; Flow and algorithm.

   Open full ADR page

10. 0010-mod-projects-no-app-host Mod projects must not alter app composition Accepted

    Compiler Mod type forbids host blocks on mod projects.

    Context

    Compiler mods and app DI share syntax keywords but different planes.

    Decision

    Mod projects must not declare app host blocks or alter app composition graphs. Mod registration uses contract registrations[] per Compiler Mod SDK.

    Consequences

    Clear boundary between Pipeline composition (Rust) and app DI (Beskid).

    Verification anchors

    Compiler Mod SDK; Mod host bridge.

    Open full ADR page

Articles

• Native dependency injection - Contracts and edge cases Lifetime rules, plural inject, host override, fail-closed guarantees, E17xx diagnostics. article Standard Reviewed Wed May 20
• Native dependency injection - Design model host, registry, scope hierarchy, global scope, field inject, array inject, dispose, and launch. article Standard Reviewed Wed May 20
• Native dependency injection - Examples Reference fixtures for hosts, plural inject, scope dispose, and library hosts. article Standard Reviewed Wed May 20
• Native dependency injection - FAQ and troubleshooting Locked design decisions, troubleshooting, and v0.3 follow-ups. article Standard Reviewed Wed May 20
• Native dependency injection - Flow and algorithm Host-chain merge, global scope, composition.resolve, plural inject lowering. article Standard Reviewed Wed May 20
• Native dependency injection - Verification and traceability Tests, snapshot versioning, and implementation checklist. article Standard Reviewed Wed May 20

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 0 SpecSection(s) · 5 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Native dependency injection

  Parent feature hub

• Area
  Conformance

  Evidence policy for compiler features

Verification matrix (target)

Scenario	Expected evidence
launch + field inject	beskid run / beskid build succeed; JIT/AOT parity
Host chain override	Launched registry wins over : ParentHost
inject Contract[] with two registrations	Both instances wired; order stable
Singular inject with two registrations	E1705
global:: inside named scope	Resolves global binding, not inner shadow
dispose on with exit	Called after body; unwind cases per spec
Child with without parent	E1707
launch in Lib	E1711
Constructor inject	E1712
Two launch on entry path	E1702
Mod project host	E1710
Mod reads snapshot	No graph mutation

Implementation checklist

• Grammar: host, registry, scope, init, dispose, startup, with, launch, field inject, global::, parent::, T[] inject
• Reject constructor inject
• Host-chain merge + override diagnostics
• Plural inject aggregation
• beskid_analysis::composition + E1701–E1799 in diagnostic_kinds.rs
• composition.resolve in beskid_pipeline + PIPELINE.md
• Composition snapshot export (CompositionSnapshot / BindingPlan)
• Runtime container in beskid_runtime::composition (registration ordering, plural inject, scope stack, reverse-order dispose)
• Runtime ABI composition_container_create / register / bind_plural / launch / scope_enter / scope_leave / resolve / resolve_plural / shutdown / container_drop / scope_depth in beskid_abi
• beskid_codegen launch / with lowering to runtime container ABI (RUNTIME_CONTAINER_LOWERING_ENABLED = true)
• beskid_codegen field init for [Inject] (single + plural) — runtime container ABI is ready (composition_resolve / composition_resolve_plural), HIR-pass wiring lands with the next codegen iteration
• Manifest validation: app target + single launch
• Corelib ConsoleHost
• Fixtures: lib host + app launch, plural inject, dispose, override chain

v0.3 evidence

• compiler/crates/beskid_tests/src/composition/container.rs::two_scopes_plural_inject_reverse_dispose — two scopes, plural inject, reverse-order dispose
• compiler/crates/beskid_tests/src/composition/host_e2e.rs::host_with_two_scopes_plural_inject_reverse_dispose — nested request + session scopes, plural Middleware, global Logger singleton disposes at shutdown
• compiler/crates/beskid_tests/src/composition/container.rs::extern_c_abi_roundtrip_through_builtins — extern "C-unwind" round trip via composition_* builtins
• compiler/crates/beskid_tests/src/composition/lowering.rs — gate flag is on, all composition_* symbols registered with BuiltinFnSpec and RUNTIME_EXPORT_SYMBOLS