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
- Deterministic lifecycle behavior
- Safe, auditable install plan execution
- 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
| State | Meaning |
|---|---|
uninstalled | Module has never been installed in this environment, or was explicitly removed |
installing | An install plan apply operation is in progress for this module |
installed | Module is active and all DDL, declarations, and agents are operational |
updating | An update install plan is in progress; prior version still serving traffic |
rollback_pending | A failure was detected; rollback operation is in progress |
rollback_completed | Rollback 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_failed | The 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 |
corrupted | DDL 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:
- Authoring — human or AI writes
.gnmsource files - Validation — compiler checks syntax, types, and cross-RFC invariants
- Compile — compiler produces compiled bundle (RFC-0002)
- 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
- Install plans MUST be derived from declared vs installed state diff.
- Plan generation SHOULD be deterministic for identical inputs.
- Apply stage MUST record outcome and diagnostics.
- Failed apply MUST produce actionable failure context.
- 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: declarationbc_risk: BC_SAFE | BC_BREAKING | BC_UNKNOWNpolicy_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: schemamigration_mode: create | alter | drop | recreate | no_opddl_fingerprint: hash of the DDL to be appliedkind_path: the gnomon kind or relation this DDL serves- Rollback:
createis rollback-safe (drop the object);alteranddroprequire a compensating migration plan;recreateMUST 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: activationagent_id: canonical path of the agent being activated or deactivatedactivation_action: activate | deactivate | updateapproval_record_id: reference to the human approval record REQUIRED foractivateandupdate- Rollback:
activateis rollback-safe (deactivate the agent);deactivateis 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);
activateadditionally 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:
- All
schemaoperations MUST complete and commit before anydeclarationoperations that reference those kinds are applied. - All
declarationoperations MUST complete before anyactivationoperations that reference those declarations. - Within a class, operations are ordered by dependency edges declared in the install plan.
- 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 ofdeclaration,schema,activationop_type: create | update | delete | no_op (within the class)target_path: canonical identity of the targetbc_risk: BC_SAFE | BC_BREAKING | BC_UNKNOWNdependency_edges: ordered list of prerequisite entry IDsrollback_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_optarget_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:
bcRiskMUST be assigned conservatively from declared authoring metadata:- declared BC_SAFE -> BC_SAFE
- declared BC_BREAKING -> BC_BREAKING
- declared BC_UNKNOWN or omitted -> BC_UNKNOWN
- Automatic derivation from prior-version semantic diffs is Phase 1 work.
- If
policyAffecting: trueis declared in authoring metadata, install-plan entries MUST preserve the flag. - 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: activationactivation_action: model_register | model_update | model_deregistermodel_ref: theModelRefstruct (RFC-0018 §4 (Compiler Architecture)) identifying the model being registeredapproval_record_id: REQUIRED formodel_registerandmodel_updatein 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):
- The install plan MUST include a
model_updateactivation entry for the affected model. - All agents that reference the updated model MUST be included in the install plan as
updateactivation entries, even if their own declarations are unchanged. This ensures agents restart with the new model binding. - 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.
- If the new model’s
digestdiffers 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:
- The prior model version MUST be restored as the active binding for all dependent agents.
- Agents that were activated during the forward install and depend on the rolled-back model MUST be deactivated before the model is restored.
- 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:
- Model digest change: If any
model_registerormodel_updateentry in the install plan changes thedigestof 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. - 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.
- Template version change: If the
promptTemplateversion changes in the module’s compiler configuration, all cache entries whose key includes the prior template version MUST be deleted. - 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:
- Cache entries created during the forward install (under the new model digest or template version) MUST be deleted as part of rollback.
- 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.
- 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
- Dependency ordering MUST be explicit and stable.
- Non-dependent operations MAY be parallelized if safe.
- Security-sensitive operations SHOULD be grouped for atomic safety.
- When an operation fails, rollback MUST compute a minimal recompute set from dependency edges rather than re-executing unrelated operations.
7. Rollback and Recovery
- Each phase SHOULD define rollback strategy and trigger conditions.
- Partial failure handling MUST identify safe retry boundaries.
- Rollback procedure MUST be documented for critical streams.
- Rollback boundaries MUST be explicit; rollback across module boundaries requires explicit inter-module agreement.
- Rollback execution SHOULD support checkpoint markers to constrain recovery scope.
Phase behavior boundary:
- Q2 implementations SHOULD support rollback scopes
selfandplan. - Cross-module rollback MAY be deferred until explicit multi-module coordination protocol support is available.
- When cross-module rollback is deferred, plan generation MUST reject cross-module scope with actionable diagnostics.
8. Security and Authorization
- Lifecycle operations MUST run under least-privilege roles.
- Policy-affecting operations MUST be auditable.
- Session/transaction context MUST be isolated per operation scope.
- Rollback operations MUST be policy-authorized and MUST NOT bypass forward-only policy constraints.
- 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:
- Agent-initiated plan generation and apply requests MUST run under least-privilege identities and MUST be auditable as agent-originated actions.
- Agent-initiated operations MUST produce the same install-plan contract shape and diagnostics as non-agent execution paths.
- Agent-initiated rollback requests MUST be rejected when forward-only policy constraints would be violated.
- If full chain analysis is unavailable in Q2, MCP tooling SHOULD emit pre-install warnings and MUST enforce strict rejection in Phase 1.
- MCP interfaces MUST preserve deterministic plan ordering and MUST NOT introduce side-channel mutation steps outside declared install-plan entries.
Forward-only policy handling:
- Policies marked as
directionality: forward-onlyare valid for forward operations only. - When full chain analysis is available, install-plan validation MUST reject rollback authorization chains that depend on forward-only constraints.
- 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
- Legacy migration artifacts MAY coexist only under explicit transition policy.
- Transition policy MUST include cutoff criteria and timeline.
10. Diagnostic Codes (RFC-0005 Allocation)
M050x: Operation taxonomy
- M05040: Schema
dropoperation 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_classfield - 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):
- Formal type-system checks for rollback safety across checkpoint boundaries.
- Logical-time rollback domains as an implementation-level optimization.
Deferred research:
- Full formal proof of lifecycle compatibility and rollback safety under concurrent installs.
- Multi-module concurrent install semantics and cross-plan rollback coordination.