Native dependency injection - Contracts and edge cases

Platform spec article

Native dependency injection - Contracts and edge cases

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

• Feature
  Diagnostic code registry

  E17xx band reservation

• Feature
  Project manifest contract

  app target and project kind

Hard requirements

• Compile-time resolution — All bindings must be resolved before lowering; no runtime service locator in v0.2.
• Fail-closed — Graph errors must block codegen for the host target; partial containers are forbidden.
• Launched host wins — For the same binding key, the topmost (launched) host registry overrides parent host and corelib base entries.
• Plural vs singular inject — Multiple registrations for one contract require T[] inject; singular inject T must resolve to exactly one.
• Field inject only — Constructor parameter inject is forbidden.
• One app per run — Exactly one launch per process; manifest app target is the single application host entry.
• Lib hosts without launch — Lib targets may define host; launch must be rejected.
• Fiber-local scope stack — Active named scopes are tracked per fiber (Execution).
• Mod isolation — Mod projects must not define app host blocks.
• Backend parity — JIT and AOT must share the same binding plan.

Lifetime constraints

Rule	Enforcement
Global single must not depend on named-scope services without with	Compile error
startup only uses global bindings	Compile error if a named scope is required
Named-scope service used outside a satisfying with	E1706
Service graph cycle (including field inject edges)	E1703
Singular inject with multiple registrations at resolution level	E1705 (use T[])
Plural inject T[] with zero registrations	E1704
Child scope with without parent on stack	E1707
Override changes lifetime kind	Compile error

Host and manifest

Rule	Detail
Multiple host definitions per project	Allowed
launch Host per run	Exactly one host type
app target	Single executable application target naming the entry that **launch**es the app host
Dual launch in one program	Forbidden

Scope navigation

Form	Valid when
Unqualified inject	Default walk inner → global
global::	Always targets merged global registry of launched host
parent::	Active named scope stack depth ≥ 1

Invalid qualifiers or unreachable parents → compile error.

Diagnostic band E1701–E1799

Reserved for composition in Diagnostic code registry. Register codes in compiler/crates/beskid_analysis/src/analysis/diagnostic_kinds.rs when implemented.

Code	Condition
E1701	Executable app target missing or no launch reachable from entry
E1702	More than one launch in the entry program (single-run violation)
E1703	Service dependency cycle
E1704	Unregistered contract/type at inject site (including empty T[])
E1705	Singular inject matches multiple registrations (use T[])
E1706	Scoped service used outside active with
E1707	Child scope activated without parent
E1708	with argument mismatch vs scope parameters
E1709	launch target is not a host type
E1710	host on Mod project
E1711	launch in Lib target
E1712	Constructor inject (field-only rule)
E1713	Host override lifetime kind mismatch
E1714	Invalid scope qualifier (global:: / parent::)

Edge cases

• init / dispose on unwind — If init completed, dispose runs for that activation when the with block exits abnormally; activations that never finished init do not run dispose.
• Repeated with HttpScope — Independent activations; separate scoped instance sets.
• Same contract in parent and child scope — Unqualified singular inject resolves in innermost scope first; use global:: to pull parent/global registration explicitly.
• Multiple Storage at global — inject Storage[] in startup receives all; singular inject Storage → E1705.
• Library host only — App host : LibHost merges registries; only app project **launch**es.