gnomonlearn
Docs/Lifecycle/RFC-0005

RFC-0005 · Module Lifecycle and Install Plan

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →

Status: Draft Owners: Module Engine, Runtime Platform

1. Scope

Defines lifecycle stages from authoring to compile to install, including install-plan semantics and rollback expectations.

2. Goals

  1. Deterministic lifecycle behavior
  2. Safe, auditable install plan execution
  3. Clear rollback and failure handling contracts

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.

3. Module Lifecycle State Machine

The module lifecycle is modeled as a first-class flow declaration (RFC-0008 §8.8). The Gnomon runtime tracks each installed module as an instance of ModuleLifecycle. This makes all lifecycle state transitions observable, auditable, and policy-governable using the same mechanisms as application-domain flows.

3.1 Normative Flow Declaration

flow ModuleLifecycle {
  meaning: "Tracks the install and runtime state of a deployed Gnomon module."

  states [
    uninstalled,
    installing,
    installed,
    updating,
    rollback_pending,
    rollback_completed,
    rollback_failed,
    corrupted
  ]

  transitions {
    uninstalled     -> installing        on install_initiated
    installing      -> installed         on install_succeeded
    installing      -> rollback_pending  on install_failed
    installed       -> updating          on update_initiated
    updating        -> installed         on update_succeeded
    updating        -> rollback_pending  on update_failed
    rollback_pending -> rollback_completed on rollback_succeeded
    rollback_pending -> rollback_failed  on rollback_failed
    rollback_completed -> installing     on reinstall_initiated
    rollback_failed  -> rollback_pending on manual_retry
    any             -> corrupted         on integrity_violation
  }
}

3.2 State Definitions

StateMeaning
uninstalledModule has never been installed in this environment, or was explicitly removed
installingAn install plan apply operation is in progress for this module
installedModule is active and all DDL, declarations, and agents are operational
updatingAn update install plan is in progress; prior version still serving traffic
rollback_pendingA failure was detected; rollback operation is in progress
rollback_completedRollback succeeded; module is no longer at the failed version. Requires explicit re-install to return to installed — the runtime does NOT silently restore installed state
rollback_failedThe rollback operation itself failed; the module is in an indeterminate state. All install, update, and activation operations on this module are blocked until a human operator acknowledges and triggers manual_retry
corruptedDDL fingerprint mismatch or integrity check failed; module is quarantined. Requires manual investigation before any state transition

3.3 Authoring-Phase Stages

The following authoring phases precede the state machine. They produce inputs for the install plan but do not produce observable module states:

  1. Authoring — human or AI writes .gnm source files
  2. Validation — compiler checks syntax, types, and cross-RFC invariants
  3. Compile — compiler produces compiled bundle (RFC-0002)
  4. Plan generation — install plan is computed from declared vs. installed state diff

The state machine begins at installing when the operator triggers apply.

4. Invariants

  1. Install plans MUST be derived from declared vs installed state diff.
  2. Plan generation SHOULD be deterministic for identical inputs.
  3. Apply stage MUST record outcome and diagnostics.
  4. Failed apply MUST produce actionable failure context.
  5. Each install-plan operation MUST carry a backward-compatibility risk classification: BC_SAFE, BC_BREAKING, or BC_UNKNOWN.

4a. Install Plan Operation Taxonomy

Install plan entries MUST be typed. Three operation classes are recognized, each with distinct rollback semantics, atomicity expectations, and required principal trust level.

Class 1: Declaration Operation

A mutation to module declarations: object definitions, policy declarations, action/claim declarations, composition declarations, aspects, and facets.

Properties:

  • op_class: declaration
  • bc_risk: BC_SAFE | BC_BREAKING | BC_UNKNOWN
  • policy_affecting: boolean
  • Rollback: reversible by replaying prior compiled bundle state
  • Atomicity: per-module; cross-module declaration operations MAY be parallelized if independent
  • Required principal: Install Operator (RFC-0000 §9.1)

Class 2: Schema Operation

A DDL mutation derived from the storage manifest (RFC-0002 §7): table creation, alteration, or removal; view generation; index creation.

Properties:

  • op_class: schema
  • migration_mode: create | alter | drop | recreate | no_op
  • ddl_fingerprint: hash of the DDL to be applied
  • kind_path: the gnomon kind or relation this DDL serves
  • Rollback: create is rollback-safe (drop the object); alter and drop require a compensating migration plan; recreate MUST have an explicit rollback DDL declared
  • Atomicity: each DDL operation MUST be wrapped in a transaction; cross-DDL atomicity within a single apply is REQUIRED
  • Required principal: Install Operator (RFC-0000 §9.1)
  • Drop safety: the install pipeline MUST verify no live gnomon instances exist before executing drop; verification failure MUST block the operation (M05040)

Class 3: Activation Operation

The enablement or disablement of an AI runtime agent (RFC-0009) or model registration in a non-development environment.

Properties:

  • op_class: activation
  • agent_id: canonical path of the agent being activated or deactivated
  • activation_action: activate | deactivate | update
  • approval_record_id: reference to the human approval record REQUIRED for activate and update
  • Rollback: activate is rollback-safe (deactivate the agent); deactivate is rollback-safe (re-activate)
  • Atomicity: activation operations are atomic per agent; bulk activations MUST be ordered by agent dependency graph
  • Required principal: Install Operator (RFC-0000 §9.1); activate additionally requires a human approval record
  • An activation operation MUST be rejected if the agent’s module declaration has not passed a clean compile (M05041)

Class Ordering and Dependencies

When an install plan contains operations of multiple classes, the following sequencing MUST be applied:

  1. All schema operations MUST complete and commit before any declaration operations that reference those kinds are applied.
  2. All declaration operations MUST complete before any activation operations that reference those declarations.
  3. Within a class, operations are ordered by dependency edges declared in the install plan.
  4. Rollback proceeds in reverse class order: activations first, then declarations, then schema.

Required Metadata Per Entry

Every install plan entry MUST carry:

  • op_class: one of declaration, schema, activation
  • op_type: create | update | delete | no_op (within the class)
  • target_path: canonical identity of the target
  • bc_risk: BC_SAFE | BC_BREAKING | BC_UNKNOWN
  • dependency_edges: ordered list of prerequisite entry IDs
  • rollback_strategy: inline rollback specification or reference to rollback plan entry

5. Install Plan Contract

Install plan entries MUST conform to the typed operation taxonomy defined in §4a. The taxonomy supersedes the generic entry shape described below for any entry where the operation class can be determined.

Install plan entries MUST include:

  • op_class (see §4a)
  • op_type: create | update | delete | no_op
  • target_path: canonical identity of the target
  • explicit dependency edges for rollback planning
  • rollback authorization scope for policy-affecting operations

Install plan entries SHOULD include:

  • risk/impact annotation (bc_risk)
  • human-readable description of the operation

Q2 minimum behavior:

  1. bcRisk MUST be assigned conservatively from declared authoring metadata:
    • declared BC_SAFE -> BC_SAFE
    • declared BC_BREAKING -> BC_BREAKING
    • declared BC_UNKNOWN or omitted -> BC_UNKNOWN
  2. Automatic derivation from prior-version semantic diffs is Phase 1 work.
  3. If policyAffecting: true is declared in authoring metadata, install-plan entries MUST preserve the flag.
  4. Automatic policy dependency graph detection is Phase 1 work.

5a. Model Declaration Availability During Install

AI model declarations (model declarations in RFC-0008 §8.16) are referenced by agent declarations and by the compiler’s ruleCompiler configuration. This section defines when model declarations become available and how model version changes are handled by the install pipeline.

Model Registration as an Activation Operation

Model registration is a Class 3 Activation Operation (§4a). The install plan MUST include a model_register activation entry for any model declaration that is being introduced or updated. The entry shape:

  • op_class: activation
  • activation_action: model_register | model_update | model_deregister
  • model_ref: the ModelRef struct (RFC-0018 §4 (Compiler Architecture)) identifying the model being registered
  • approval_record_id: REQUIRED for model_register and model_update in non-development environments

Model Availability Ordering

A model MUST be registered before any agent that references it is activated. Class ordering (§4a Class Ordering) enforces this: activation operations for agents that depend on a model MUST list the model’s model_register entry as a dependency_edge.

The compiler MUST emit error M05046 if an agent declaration’s model reference cannot be resolved at the time the agent activation entry is applied.

Model Version Updates

When a module update changes a model declaration (different digest, version, or parameters):

  1. The install plan MUST include a model_update activation entry for the affected model.
  2. All agents that reference the updated model MUST be included in the install plan as update activation entries, even if their own declarations are unchanged. This ensures agents restart with the new model binding.
  3. The prior model version remains resolvable from the event log for audit purposes but MUST NOT be used for new agent invocations after the update completes.
  4. If the new model’s digest differs from the prior version, all rule compilation cache entries (RFC-0018 §10.5) that used the prior model MUST be invalidated as part of the same install plan execution (see §5b).

Model Availability During Rollback

When an install is rolled back and the rollback crosses a model_update entry:

  1. The prior model version MUST be restored as the active binding for all dependent agents.
  2. Agents that were activated during the forward install and depend on the rolled-back model MUST be deactivated before the model is restored.
  3. Rollback activation order follows the reverse of forward activation: agents first, then model deregistration/restore.

Diagnostic: M05046 (model reference unresolvable at agent activation), M05047 (agent activation references model not yet registered in plan).

5b. Rule Compilation Cache Invalidation

The rule compilation cache (RFC-0018 §10.5) stores the results of AI-compiled rule statements, keyed by SHA256(rule_text + model_digest + template_version). Because cache entries are keyed by model digest, cache invalidation is deterministic and does not require manual intervention. This section specifies the normative invalidation rules for install and rollback scenarios.

Cache Invalidation on Module Update

When an install plan updates a module:

  1. Model digest change: If any model_register or model_update entry in the install plan changes the digest of a model used as a rule compiler, ALL cache entries whose key includes the prior model digest MUST be deleted before the new kernel artifact is activated. The compiler MUST re-run rule compilation for all affected rules as part of the install plan execution.
  2. Rule text change: Rule text changes naturally produce cache misses on next compilation (the key changes). No explicit invalidation is required; stale entries for the old key are orphaned and eligible for garbage collection.
  3. Template version change: If the promptTemplate version changes in the module’s compiler configuration, all cache entries whose key includes the prior template version MUST be deleted.
  4. No model or template change: If neither model digest nor template version changes, the existing cache remains valid. The install plan MUST NOT invalidate the cache in this case.

Cache Restoration on Rollback

When an install is rolled back:

  1. Cache entries created during the forward install (under the new model digest or template version) MUST be deleted as part of rollback.
  2. Cache entries from the prior install (under the prior model digest or template version) that were deleted during the forward install SHOULD be restored if they were preserved in the rollback snapshot. If the prior cache is not available, the runtime MUST re-run rule compilation on first use; this is acceptable and correct behavior.
  3. A rollback MUST NOT leave the system in a state where cache entries from the new install co-exist with a kernel artifact from the prior install. The bundle fingerprint check (RFC-0010 §5.4) prevents this: a fingerprint mismatch at startup halts execution.

Diagnostic Codes

  • M05048: Install plan applies model digest change without invalidating affected cache entries
  • M05049: Rollback detected cache entries from forward install after kernel restore — cache state inconsistent

6. Sequencing Rules

  1. Dependency ordering MUST be explicit and stable.
  2. Non-dependent operations MAY be parallelized if safe.
  3. Security-sensitive operations SHOULD be grouped for atomic safety.
  4. When an operation fails, rollback MUST compute a minimal recompute set from dependency edges rather than re-executing unrelated operations.

7. Rollback and Recovery

  1. Each phase SHOULD define rollback strategy and trigger conditions.
  2. Partial failure handling MUST identify safe retry boundaries.
  3. Rollback procedure MUST be documented for critical streams.
  4. Rollback boundaries MUST be explicit; rollback across module boundaries requires explicit inter-module agreement.
  5. Rollback execution SHOULD support checkpoint markers to constrain recovery scope.

Phase behavior boundary:

  1. Q2 implementations SHOULD support rollback scopes self and plan.
  2. Cross-module rollback MAY be deferred until explicit multi-module coordination protocol support is available.
  3. When cross-module rollback is deferred, plan generation MUST reject cross-module scope with actionable diagnostics.

8. Security and Authorization

  1. Lifecycle operations MUST run under least-privilege roles.
  2. Policy-affecting operations MUST be auditable.
  3. Session/transaction context MUST be isolated per operation scope.
  4. Rollback operations MUST be policy-authorized and MUST NOT bypass forward-only policy constraints.
  5. Rollback execution MUST emit tamper-evident audit records for all policy-affecting changes.

Agent-Initiated Lifecycle Operations (MCP)

When lifecycle stages are triggered by AI agents via MCP:

  1. Agent-initiated plan generation and apply requests MUST run under least-privilege identities and MUST be auditable as agent-originated actions.
  2. Agent-initiated operations MUST produce the same install-plan contract shape and diagnostics as non-agent execution paths.
  3. Agent-initiated rollback requests MUST be rejected when forward-only policy constraints would be violated.
  4. If full chain analysis is unavailable in Q2, MCP tooling SHOULD emit pre-install warnings and MUST enforce strict rejection in Phase 1.
  5. MCP interfaces MUST preserve deterministic plan ordering and MUST NOT introduce side-channel mutation steps outside declared install-plan entries.

Forward-only policy handling:

  1. Policies marked as directionality: forward-only are valid for forward operations only.
  2. When full chain analysis is available, install-plan validation MUST reject rollback authorization chains that depend on forward-only constraints.
  3. If full chain analysis is unavailable in Q2, tooling SHOULD emit pre-install warnings and MUST enforce strict rejection in Phase 1.

9. Compatibility and Migration

  1. Legacy migration artifacts MAY coexist only under explicit transition policy.
  2. Transition policy MUST include cutoff criteria and timeline.

10. Diagnostic Codes (RFC-0005 Allocation)

M050x: Operation taxonomy

  • M05040: Schema drop operation blocked — live gnomon instances exist for target kind
  • M05041: Activation operation rejected — agent module declaration has compile errors
  • M05042: Install plan entry missing required op_class field
  • M05043: Class ordering violation — declaration operation precedes its dependent schema operation
  • M05044: Activation operation missing required human approval record
  • M05045: Rollback ordering violation — activation not rolled back before dependent declaration
  • M05046: Model reference unresolvable at agent activation time
  • M05047: Agent activation entry references model not yet registered in install plan
  • M05048: Install plan applies model digest change without invalidating affected rule compilation cache entries
  • M05049: Rollback detected forward-install cache entries after kernel restore — cache state inconsistent

M054x: Rollback policy and authorization

  • M05400: Install-plan entry missing or invalid bcRisk classification
  • M05401: Rollback authorization references forward-only policy constraint
  • M05402: Cross-module rollback deferred or unsupported in current lifecycle phase

Appendix A: Optional and Deferred Items (Non-Normative)

Optional follow-on work (not required for RFC-0005 closure):

  1. Formal type-system checks for rollback safety across checkpoint boundaries.
  2. Logical-time rollback domains as an implementation-level optimization.

Deferred research:

  1. Full formal proof of lifecycle compatibility and rollback safety under concurrent installs.
  2. Multi-module concurrent install semantics and cross-plan rollback coordination.