Native dependency injection - FAQ and troubleshooting

Platform spec article

Native dependency injection - FAQ and troubleshooting

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

Locked decisions (v0.2)

Normative text for locked v0.2 choices lives in feature hub ADRs (D-LMETA-DI-0001 … D-LMETA-DI-0010 under Native dependency injection adr/). This section retains troubleshooting only.

Topic	adrId
Multiple implementations, host override, scope model	D-LMETA-DI-0005, D-LMETA-DI-0006, D-LMETA-DI-0007
Library launch, field inject, registry spelling	D-LMETA-DI-0008, D-LMETA-DI-0003, D-LMETA-DI-0004
Pipeline placement, mod vs app host	D-LMETA-DI-0009, D-LMETA-DI-0010
Diagnostics band E1701–E1799	Reserved on hub; codes in tables below
WebHost	v0.3 — v0.2 is ConsoleHost + manual with (follow-up, not yet an ADR)

FAQ

Why field inject instead of constructors?

Field injection keeps type headers uniform and gives the compiler a single slot-lowering story for inject without ctor signature churn across inheritance. Constructor inject is rejected (E1712).

How do I consume two Storage implementations?

Register both in registry and inject inject Storage[] storages. Order follows deterministic registration merge order (see Design model).

Can I force a global service inside a named scope?

Use inject global::Logger logger on a field or in init / dispose parameters.

Can a library launch its host for testing?

No — use an App / test Host project target that **launch**es the library host, or a test harness entry approved by the tooling spec. launch on Lib is E1711.

How do I define two apps in one repo?

Declare two host types and two targets (for example app and api), each with its own entry and one launch. Only one target runs per process invocation.

v0.3 follow-ups

• WebHost request pipeline entering a named scope without manual with on every handler.
• Disposable-style corelib contract as optional supplement to dispose blocks.

Troubleshooting

Symptom	Likely cause
E1705	Two for Contract lines but singular inject Contract
E1706	Field inject of scoped service outside with
E1711	launch in a library target
E1712	inject on constructor parameters
Wrong implementation at inject site	Inner scope shadows global — use global::
E1702	Two launch calls on one entry path

Related planes

• Dependency graph and cycle policy — package graph, not service graph
• Mod host bridge — mod registrations[]
• Pipeline composition — Rust compiler services