fix(install): the default install lands every module first, and a declared set installs only itself

[rbuergi]

What

The platform bootstrap: a FRESH instance whose image does not ship the store-delivered modules (a control image, Mesh:ClosedTypeSet=true) can now install the store from the registry.

1. Phase 1 — modules; phase 2 — nodes. InstanceAutoRegistrationService.LandModulesFirst lands the compiled module of every selected package that has no install record yet, BEFORE any package's nodes are written. Phase 2 (the node install, in dependency order) is subscribed only after every module of the selection has been decided.

• Same gates the install funnel applies before a file travels: entitlement (with the deployment-config principal), the licence-acceptance gate, and declared parameters; the platform floor is the adoption's own floorHold. Each adoption is bounded by PerPackageAdoptBudget; the module set is proposed after every wave that decided a fresh carrier.
• Fresh installs only: an installed package keeps its module on the funnel (after content, inside the floor and update-policy holds), so this never lands drift those holds gate. An unreadable install record is not treated as fresh.
• Never fails the pass: the adoption absorbs its failures; a fault of the phase is logged at Error and the content phase runs as before.
• The landing raises the pending-restart marker (restart-as-activation — a brand-new module is NotHeld); the pass after that restart finds Skill/Agent registered and installs Store first, then everything rooted on Store/Plugin. The "NodeType must be registered" validation is untouched — the first pass's content failures are FAILED with their cause and retried by the next pass.
• DefaultInstallSummary.ModulesLanded + a MODULES LANDED ahead of content (load at the next restart): […] clause on the summary line.

2. A declared set installs only itself. PluginCatalogOptions.InstallPreInstalledPackages keeps its bool surface (reads true while unset); the new InstallPreInstalledPackagesConfigured (bool?) tells unset from true. Unset, the preInstalled baseline applies unless InstallByDefault declares an EXPLICIT set (every entry Source/Package, none Source/*); then exactly the named packages and their declared requires are selected. An explicit true/false still wins. A whole-source pattern (the chart default Plugins/*) or no patterns keeps the baseline exactly as before.

3. Docs: PluginAuthoring, the chart's installPreInstalledPackages comments, Doc/Architecture/PluginRegistry — new section The bootstrap: modules first, then nodes, and the InstallPreInstalledPackages bullet; EnvironmentComposition lane table; DeploymentContent.PreInstall summary.

Why (measured on a fresh control instance, 2026-10-13)

[DefaultInstall] installing package Store failed … NodeType(s) not registered: Skill
[DefaultInstall] installing package AI failed … NodeType 'Store/Plugin' is not registered
[DefaultInstall] reconciled with FAILURES: 0 installed, 0 up to date, 48 failed [Store, AI, Acp, …]

/data/modules empty. Store's nodes need Skill (the MeshWeaver.AI module, delivered by AI); AI's root and every other root are Store/Plugin (declared by Store); a module landed only after its own package's content validated (CatalogLayoutAreas.InstallOrUpdateCore → WithModule runs on the content's success). No entry point. The instance named five packages and the pass selected 48: every preInstalled package of the registry plus Store.

Tests

test/Memex.Portal.Shared.Test/StoreBootstrapLandsModulesFirstTest.cs, against an in-process registry serving the REAL wire shapes (listing, /files, bundle index, a module bundle with real assembly bytes) to the real RegistryPackageSource / PluginBundleClient:

• StoreBootstrapLandsModulesFirstTest.AFreshImage_LandsEveryModuleFirst_AndSelectsOnlyTheDeclaredSet — reproduces the production errors verbatim (Install of 'AI' failed: NodeType 'Store/Plugin' is not registered, Store on Skill), and asserts all three modules landed with the pending-restart marker, and the selection is {Store, AI, EntityViews, Chat} without the unnamed preInstalled Games.
• StoreBootstrapCompletesAfterTheRestartTest.OnceTheModulesLoad_OnePassInstallsTheStoreThenEverythingRootedOnIt — with Skill registered (the loaded module's stand-in), one pass delivers all four, Store before AI before Chat.
• PreInstalledBaselineSelectionTest — the selection rule's truth table.

Negative controls (run locally, each reverted alone):

• Module phase removed → Expected collection {} to equal {"Bootstrap.Test.AI", "Bootstrap.Test.Chat", "Bootstrap.Test.EntityViews"} (the sidecar stays empty — the production state).
• Selection reverted to ?? true → Expected collection {"AI", "Chat", "EntityViews", "Games", "Store"} to equal {"AI", "Chat", "EntityViews", "Store"}.

Restored: 231/231 across every default-install / module-landing / floor-hold / install-record class in Memex.Portal.Shared.Test (48 classes); 830/830 MeshWeaver.Documentation.Test. Built -c Release -warnaserror: MeshWeaver.PluginCatalog, Memex.Portal.Shared.Test, MeshWeaver.Documentation.Test, MeshWeaver.Deployment.Contract.Test — 0 Error(s), 0 Warning(s).

Deploy notes

• Behaviour change on the next boot of any instance whose InstallByDefault names packages exactly and does not set InstallPreInstalledPackages: the preInstalled baseline is no longer selected there. Nothing installed is removed; installed packages keep updating through the registry reconciler. Instances with a whole-source pattern (the chart default Plugins/*) are unchanged.
• A fresh instance needs ONE restart after its first boot for the landed modules to load (the self-updater takes the pending-restart marker; where it cannot roll, any restart does).
• Not established here: a cross-package root (Store/Plugin) on a closed type set once installer-side NodeType rows are withheld (Closed type set: package installer holds no NodeType rows; #6349 retry skips the closed-set refusal (#6627) #6670, open) — phase 1 lands the modules either way, which is what /health required_modules reads.

Implementers: none — no interface member added.
Pairs-with: none — additive only: PluginCatalogOptions.InstallPreInstalledPackagesConfigured, DefaultInstallSummary.ModulesLanded (init); CatalogLayoutAreas.ProposeMeshModuleSet private → internal.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The module phase bypasses license consent, can stall indefinitely, and may permanently skip module-set proposal recovery.

7 open findings

• Run the license acceptance gate before adopting modules · New
• Retry module-set proposals when no new files are copied · New
• Preserve binary compatibility for the public property · New
• Bound each module adoption to prevent starvation · New
• Correct the documented default for null package declarations · New
• Update guidance to reflect the context-dependent baseline default · New
• Use immutable collections for static fixture data · New

What changed in this PR

Adds two-phase plugin bootstrap so modules land before package content, while explicit package sets exclude the baseline unless configured otherwise.

Changes:

• Adds modules-first bootstrap and restart reporting.
• Introduces context-dependent preinstalled-package selection.
• Adds integration tests and updates deployment documentation.

File	Description
InstanceAutoRegistrationService.cs	Implements selection and modules-first installation.
PluginCatalogOptions.cs	Makes baseline configuration nullable.
CatalogLayoutAreas.cs	Exposes module-set proposal internally.
DeploymentContent.cs	Documents explicit preinstall sets.
PluginRegistry.md	Documents bootstrap sequencing.
EnvironmentComposition.md	Updates composition semantics.
StoreBootstrapLandsModulesFirstTest.cs	Tests bootstrap, restart, and selection behavior.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[rbuergi]

Fixed in 3e0f65f: PluginAuthoring.md, the chart's config.yaml comment and values.yaml comment now describe the unset rule (applies unless installByDefault names an explicit Source/Package set; true/false always wins).

[Copilot]

🟡 Changes recommended

Authorization-refused modules may still be proposed for activation, and malformed package entries can incorrectly suppress the baseline.

10 open findings

• Authorization failures incorrectly retain Fresh status · New
• Malformed entries incorrectly suppress the baseline · New
• Test does not verify bundle adoption precedes content requests · New
• Replace mutable decision date with bootstrap policy marker · New
• Reference policy instead of hard-coding behavior date · New
• Reference PolicyNotProse instead of hard-coded decision date · New
• Replace duplicated decision date with policy reference · New
• Use PolicyNotProse for mutable bootstrap decision date · New
• Use PolicyNotProse id instead of dated decision comment · New
• Update guidance to reflect the context-dependent baseline default

6 resolved since last review

• Preserve binary compatibility for the public property
• Retry module-set proposals when no new files are copied
• Run the license acceptance gate before adopting modules
• Bound each module adoption to prevent starvation
• Use immutable collections for static fixture data
• Correct the documented default for null package declarations

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Two changed documentation sections omit the licence-acceptance gate enforced by the new module-first phase.

3 open findings

• Document licence acceptance among pre-fetch gates · New
• Document the licence-acceptance gate in the scope description · New
• Update guidance to reflect the context-dependent baseline default

9 resolved since last review

• Authorization failures incorrectly retain Fresh status
• Test does not verify bundle adoption precedes content requests
• Malformed entries incorrectly suppress the baseline
• Use PolicyNotProse id instead of dated decision comment
• Use PolicyNotProse for mutable bootstrap decision date
• Replace duplicated decision date with policy reference
• Reference PolicyNotProse instead of hard-coded decision date
• Reference policy instead of hard-coding behavior date
• Replace mutable decision date with bootstrap policy marker

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Fresh module proposals omit dependency constraints from not-yet-written install records, and an unbounded record read can block the entire bootstrap.

2 open findings

• Validate dependency floors against fresh and existing module records · New
• Update guidance to reflect the context-dependent baseline default

2 resolved since last review

• Document the licence-acceptance gate in the scope description
• Document licence acceptance among pre-fetch gates

Previously missed (3)

In code that hasn't changed since last review

Apply read timeout before install-record adoption pass

src/​MeshWeaver.PluginCatalog/​InstanceAutoRegistrationService.cs:2268

The adoption timeout does not cover this preceding install-record read. If storage never emits, the sequential Concat cannot advance and phase 2 is never subscribed, so one wedged record read blocks every module and all package content instead of being isolated as an unreadable record. Apply the established install-record read budget before the catch so the pass can continue.

Clarify baseline suppression when InstallPreInstalledPackages is false

src/​MeshWeaver.Deployment.Contract/​DeploymentContent.cs:211

The final sentence is unconditional, but an explicit PluginCatalog:InstallPreInstalledPackages=false suppresses the baseline even when PreInstall is empty or contains a whole-source pattern. Qualify this as the unset-key behavior so the public contract does not contradict the explicit override.

Document InstallByDefault relationship for unset behavior

src/​MeshWeaver.Documentation/​Data/​Architecture/​PluginRegistry.md:90

The introduction at line 90 still says these two keys are independent, but the new unset behavior here explicitly derives the baseline from InstallByDefault. That contradiction can make operators assume an explicit package set still retains the baseline; update the introduction to acknowledge the relationship.

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Mixed module waves can activate a refused carrier, and case-insensitive record matching can skip required floor validation.

3 open findings

• Gate refusal still activates rejected carriers in mixed waves · New
• Case-insensitive package set skips dependency validation · New
• Update guidance to reflect the context-dependent baseline default

1 resolved since last review

• Validate dependency floors against fresh and existing module records

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Module activation can bypass current authorization and ownership holds, and dependency-floor matching remains case-inconsistent.

4 open findings

• Refused packages can still activate previously landed modules · New
• Case-insensitive dependency resolution breaks ordinal module identity · New
• Failed proposals incorrectly promise module activation on restart · New
• Update guidance to reflect the context-dependent baseline default

2 resolved since last review

• Gate refusal still activates rejected carriers in mixed waves
• Case-insensitive package set skips dependency validation

Previously missed (1)

In code that hasn't changed since last review

Modules adopted before partition ownership holds are enforced

src/​MeshWeaver.PluginCatalog/​InstanceAutoRegistrationService.cs:2252

Modules are adopted before Install() evaluates the partition-ownership holds. An unproven registry ref or a proven source targeting another repository can therefore land and propose its module here even though lines 2451-2478 later return HoldForThePartitionsOwnWriter without fetching content; that hold's existing contract explicitly says “no module is adopted” (line 2529). Apply the ownership verdict before admitting a carrier so code cannot load without its matching held content.

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Module proposals can still publish unvalidated or incomplete module sets, and malformed patterns can suppress the baseline.

3 open findings

• Proposal proceeds despite module candidates lacking a bundle client · New
• Missing blocked dependencies allow incomplete module proposals · New
• Update guidance to reflect the context-dependent baseline default

1 resolved since last review

• Use authoritative post-install records for proposal validation

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

A previously landed module can still be activated after its package becomes terminally refused.

2 open findings

• Terminally skipped modules can be reactivated via sidecar proposals · New
• Update guidance to reflect the context-dependent baseline default

2 resolved since last review

• Missing blocked dependencies allow incomplete module proposals
• Proposal proceeds despite module candidates lacking a bundle client

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

A terminally skipped dependency can still allow a dependent-only module set to be proposed.

1 open finding

• Update guidance to reflect the context-dependent baseline default

1 resolved since last review

• Terminally skipped modules can be reactivated via sidecar proposals

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Module-set proposal can still activate uncleared or incomplete carrier combinations, and malformed patterns can suppress the baseline.

2 open findings

• Block failed installed carriers instead of ignoring phase-2 failures · New
• Update guidance to reflect the context-dependent baseline default

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

It changes central bootstrap and module-activation sequencing across multiple authorization, dependency, and recovery paths.

1 open finding

• Update guidance to reflect the context-dependent baseline default

1 resolved since last review

• Block failed installed carriers instead of ignoring phase-2 failures

🧠 Review effort: Balanced