gnomonlearn
Docs/RFC-0041 lifecycle strategy priority

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) returns no-op for 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 computed migrationStrategy and retains all five actions. Applying an equal-major upgrade executes those actions with forceInstall: 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.deployment status, unless request force or contentRefresh bypasses that skip. The registry status has no manifest hash. These paths do not compare the installed core.module.linkHash, and skipped paths can refresh the separate core.module_manifest reflection record.
  • Request force currently bypasses skipping; it does not invoke the uninstall-first behavior in §5.4. The engine does not read the manifest’s defaultConfig.forceReinstall when 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) includes version in the normalized manifest hash and excludes only metadata.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.

  1. Treat an explicit force request as a fresh reinstall after safely removing module-owned state. This override has the highest priority.
  2. With no installed version, choose install. With a different canonical major, choose upgrade or rollback according to version order.
  3. 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.
  4. Record the selected reason (force, major-change, content-change, or unchanged) 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.