Concepts and Glossary - valence-works/nuplane GitHub Wiki

Concepts and Glossary

Use this page as the normalized vocabulary for the Nuplane wiki.

Core runtime terms

Desired state

The package set Nuplane should make active.

Actual state

The package set currently active in the local store and available through Nuplane’s authoritative read surfaces.

Reconciliation

A control-loop cycle that reads desired state, resolves packages, computes the diff against current state, applies transactional changes, and emits observable outcomes.

Feed

A named package source used for resolution. In current repository behavior, a feed can be a NuGet v3 service index or a local directory containing .nupkg files.

Package store

Nuplane’s deterministic on-disk storage area for packages, current-package pointers, staging work, and persisted state.

Active package

The currently active resolved package version that Nuplane treats as live for a package identifier.

Last-known-good (LKG)

The most recent successfully applied package version that remains available as the safe active fallback when a newer change fails.

Observer

A host-owned callback surface for invalidation or reaction signals. Observers are useful, but they are not the authoritative source of state.

  • Applied in: Getting Started, Usage Guide
  • Canonical anchors: README.md, samples/Nuplane.Sample.AspNetCore/PackageChangeObserver.cs

Operational state

A health- and diagnostics-oriented read surface that stays distinct from the package inventory itself.

Optional module terms

Optional loading

An opt-in subsystem that loads resolved packages into isolated assembly load contexts and exposes load-state-aware surfaces.

Load-state catalog

The loading-owned authoritative view of current-process loading status when the optional loading module is installed.

  • Applicability: Optional Module
  • Applied in: Usage Guide, Architecture Guide
  • Canonical anchors: README.md, src/Nuplane.Loading.Abstractions/IPackageLoadStateCatalog.cs

Package assembly catalog

A higher-level loading-aware surface for hosts that want the currently active loaded assemblies for a package or package set.

  • Applicability: Optional Module
  • Applied in: Usage Guide
  • Canonical anchors: README.md, src/Nuplane.Loading.Abstractions/IPackageAssemblyCatalog.cs

Package load mode

The loading setting that controls package assembly lifetime and framework integration behavior. Collectible keeps the existing unloadable/isolation-oriented behavior, while HostIntegrated makes active package assemblies safe for application-lifetime framework integration and by-name resolution.

  • Applicability: Optional Module
  • Applied in: Usage Guide, Package Authoring
  • Canonical anchors: README.md, src/Nuplane.Loading.Abstractions/PackageLoadMode.cs

Automatic load-mode selection

The loading policy that evaluates resolved package graphs through load-mode advisors before falling back to DefaultLoadMode. Automatic selection keeps effective runtime modes concrete: packages still load as Collectible or HostIntegrated, never as an Auto runtime mode.

  • Applicability: Optional Module
  • Applied in: Usage Guide, Package Authoring
  • Canonical anchors: src/Nuplane.Loading.Abstractions/PackageLoadModeSelectionPolicy.cs, src/Nuplane.Loading/PackageLoadModeSelector.cs

Package load-mode advisor

An extension point that inspects an already-resolved package graph and returns deterministic, secret-safe load-mode requirements or diagnostics. The built-in advisor reads Nuplane package metadata; future advisors can inspect other package or runtime metadata without hard-coding package IDs in core loading logic.

  • Applicability: Optional Module
  • Applied in: Usage Guide, Package Authoring
  • Canonical anchors: src/Nuplane.Loading.Abstractions/IPackageLoadModeAdvisor.cs

Package activation gate

A host-owned extension point that can refuse to activate a resolved package graph. Gates are consulted after load-mode selection and before any load context exists, they are fail-closed (a gate that throws or answers nothing blocks), and a block surfaces as an ordinary load failure that is re-evaluated on the next load attempt.

  • Applicability: Optional Module
  • Applied in: Usage Guide
  • Canonical anchors: src/Nuplane.Loading.Abstractions/IPackageActivationGate.cs, src/Nuplane.Loading/PackageLoader.cs

Nuplane package metadata

Package-authored metadata stored in package-root nuplane.json. For loading, the v1 schema supports schemaVersion, loading.loadMode, loading.scope, and optional loading.reason. Metadata is trusted only as much as the package itself and does not bypass source trust, integrity validation, or host-owned activation semantics.

  • Applicability: Optional Module
  • Applied in: Usage Guide, Package Authoring
  • Canonical anchors: README.md, specs/027-auto-load-mode-selection/spec.md

Capability

A named choice a package declares in its capabilities metadata: exactly one of several candidate packages must become a root in the host's closure for the declaring package to run. Declaring a capability changes nothing by itself; a host selection is what turns it into a resolved root.

  • Applied in: Package Authoring
  • Canonical anchors: README.md, src/Nuplane.Abstractions/PackageCapabilityDeclaration.cs

Host-integrated assembly

An active package assembly loaded in HostIntegrated mode so framework code can safely hold references to it and resolve it by assembly name without host-owned resolver plumbing.

  • Applicability: Optional Module
  • Applied in: Usage Guide
  • Canonical anchors: README.md, src/Nuplane.Loading/HostIntegratedAssemblyResolver.cs

Documentation-governance terms

Hybrid hub

A documentation model where the wiki owns orientation and onboarding but intentionally links to repository docs, samples, and specs for deeper or more volatile detail.

Applicability label

A visible label that tells the reader whether a capability is Core, Optional Module, Phase-Based, Recently Changed, or Evolving.

Related pages