RFC-0041 lifecycle strategy priority
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
RFC-0041 §5.2 selects no-op whenever target and installed canonical major
versions are equal. Section 5.4 says forceReinstall or request force
selects a fresh install regardless of installed state. Section 7.3 says a
manifest hash change triggers reinstall at the same version. Section 13
invariant 9 says only version comparison influences migration strategy.
Those four rules cannot all hold for the same module.
The current graph-module-engine/services/lifecycle-policy.ts compares
canonical majors to select install, upgrade, rollback, or no-op. It
does not receive the installed and target manifest hashes. Other installer
paths carry force and content-refresh options, so a policy decision made
only from canonical majors cannot implement the authored hash rule.
Section 5.3 also says to select the highest patch among manifests with
the same canonical major, but the implementation sorts complete SemVer
parts. With 1.2.0 and 1.1.9, the highest SemVer is 1.2.0 even though
the latter has the larger patch component. Specify highest full SemVer
within the canonical major.
Current source status — October 17, 2026
The priority decision remains pending. The recommendations and acceptance cases below remain a proposal; this status note changes no normative rule. The current source comparison identifies these implementation differences:
- Lifecycle policy (Gnomon source:
gnomon/graph/packages/graph-module-engine/services/lifecycle-policy.ts; public source link pending) returnsno-opfor equal canonical versions. However, lifecycle plan construction (Gnomon source:gnomon/graph/packages/graph-module-engine/services/lifecycle-service.ts; public source link pending) omits the computedmigrationStrategyand retains all five actions. Applying an equal-major upgrade executes those actions withforceInstall: true; applying an equal-major rollback returns early. A policy result alone therefore does not establish execution as a no-op. - Single and batch installation (Gnomon source:
gnomon/graph/packages/graph-module-engine/services/installation-service.ts; public source link pending) skip installed modules based on GraphModuleRegistry’s (Gnomon source:gnomon/graph/packages/graph-module-engine/registries/module-registry-graph.ts; public source link pending)graph.deploymentstatus, unless requestforceorcontentRefreshbypasses that skip. The registry status has no manifest hash. These paths do not compare the installedcore.module.linkHash, and skipped paths can refresh the separatecore.module_manifestreflection record. - Request
forcecurrently bypasses skipping; it does not invoke the uninstall-first behavior in §5.4. The engine does not read the manifest’sdefaultConfig.forceReinstallwhen making this decision. - The accepted runtime hash-persistence implementation in
install-module.ts (Gnomon source:
gnomon/graph/packages/graph-module-engine/install/install-module.ts; public source link pending) includesversionin the normalized manifest hash and excludes onlymetadata.annotations. A real minor/patch version change therefore normally changes the hash. The identical-hash version-change question retained in recommendation 3 below is historical, not a separate expected branch under this hash domain. The version-only acceptance case must exercise the resulting changed hash rather than assume an equal hash.
These are source observations, not new runtime acceptance or resolution of the existing priority, reinstall, and installed-state authority decisions.
Recommended first-release rule
- Treat an explicit force request as a fresh reinstall after safely removing module-owned state. This override has the highest priority.
- With no installed version, choose
install. With a different canonical major, chooseupgradeorrollbackaccording to version order. - With the same canonical major, compare the normalized target manifest
hash with the installed hash. A different hash chooses a content refresh
in the same canonical version; an equal hash chooses
no-op. Decide explicitly whether a minor/patch change with identical normalized hash updates only version metadata or is a no-op. - Record the selected reason (
force,major-change,content-change, orunchanged) in the plan and install audit. The same plan inputs must reproduce the same strategy.
The existing four-value strategy enum cannot express content refresh separately from fresh install without defining which state is removed and which is upserted. Set that behavior in the normative RFC, Lean, RDF, plan schema, implementation, and tests before the first release. Nothing is deployed, so no installed module state needs migration.
Acceptance: test force with and without installed state, major upgrade and
rollback, same-major changed hash, unchanged hash, and a version-only change.
Include two same-major versions whose minor and patch ordering disagree.
Assert the plan strategy, writes, audit reason, and resulting module record
on at least one persistent backend. Confirm continueOnError changes only
whether later modules run, never the chosen strategy or failed module’s
atomicity.