RFC-0005 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0005: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0005.This page is generated from the
lean/Gnomon/Spec/module for RFC-0005. Edit that source and regenerate this catalog.
Title: Module Lifecycle and Install Plan
Status: draft
Owners: Module Engine, Runtime Platform
Proof citations in source: 23 / 23. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Activation Operation | Class 3 install plan operation: enablement or disablement of an AI runtime agent or model registration in a non-development environment. |
| Declaration Operation | Class 1 install plan operation: a mutation to module declarations (object definitions, policies, actions/claims, composition declarations, aspects, facets). |
| Schema Operation | Class 2 install plan operation: a DDL mutation derived from the storage manifest (table create/alter/drop, view generation, index creation). |
| corrupted | DDL fingerprint mismatch or integrity check failed; module is quarantined and requires manual investigation before any state transition. |
| installed | Module is active and all DDL, declarations, and agents are operational. |
| installing | An install plan apply operation is in progress for this module. |
| rollback_completed | Rollback succeeded; module is no longer at the failed version. Requires explicit re-install to return to installed. |
| rollback_failed | The rollback operation itself failed; the module is in an indeterminate state. All operations blocked until human operator triggers manual_retry. |
| rollback_pending | A failure was detected; rollback operation is in progress. |
| uninstalled | Module has never been installed in this environment, or was explicitly removed. |
| updating | An update install plan is in progress; prior version still serving traffic. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M05040 | Error | Schema drop operation blocked — live gnomon instances exist for target kind |
M05041 | Error | Activation operation rejected — agent module declaration has compile errors |
M05042 | Error | Install plan entry missing required op_class field |
M05043 | Error | Class ordering violation — declaration operation precedes its dependent schema operation |
M05044 | Error | Activation operation missing required human approval record |
M05045 | Error | Rollback ordering violation — activation not rolled back before dependent declaration |
M05046 | Error | Model reference unresolvable at agent activation time |
M05047 | Error | Agent activation entry references model not yet registered in install plan |
M05048 | Error | Install plan applies model digest change without invalidating affected rule compilation cache entries |
M05049 | Error | Rollback detected forward-install cache entries after kernel restore — cache state inconsistent |
M05400 | Error | Install-plan entry missing or invalid bcRisk classification |
M05401 | Error | Rollback authorization references forward-only policy constraint |
M05402 | Error | Cross-module rollback deferred or unsupported in current lifecycle phase |
Invariants
- A failed apply must produce actionable failure context. (enforced by: runtime)
- A model must be registered before any agent that references it is activated. (enforced by: install-time)
- A rollback must not leave cache entries from the new install co-existing with a kernel artifact from the prior install. (enforced by: boot-time)
- Agent-initiated lifecycle operations must produce the same install-plan contract shape and diagnostics as non-agent execution paths. (enforced by: compile-time + runtime)
- An activation operation must be rejected if the agent’s module declaration has not passed a clean compile. (enforced by: compile-time + install-time)
- Cache entries keyed by a prior model digest must be deleted before the new kernel artifact is activated when a model digest changes. (enforced by: install-time)
- Declaration operations must complete before any activation operations that reference those declarations. (enforced by: install-time)
- Dependency ordering across install-plan entries must be explicit and stable. (enforced by: compile-time)
- Each DDL operation must be wrapped in a transaction and cross-DDL atomicity within a single apply is required. (enforced by: DB-trigger + runtime)
- Each install-plan operation must carry a BC_SAFE, BC_BREAKING, or BC_UNKNOWN backward-compatibility classification. (enforced by: compile-time + install-time)
- Every apply stage must record its outcome and diagnostics. (enforced by: runtime)
- Install plan entries must be typed with one of the declaration, schema, or activation operation classes. (enforced by: compile-time)
- Install plans must be derived from the diff between declared and installed state. (enforced by: compile-time + install-time)
- Lifecycle operations must run under least-privilege roles. (enforced by: runtime + RLS)
- On operation failure, rollback must compute a minimal recompute set from dependency edges rather than re-executing unrelated operations. (enforced by: runtime)
- Policy-affecting lifecycle operations must be auditable. (enforced by: runtime)
- Rollback boundaries must be explicit; cross-module rollback requires explicit inter-module agreement. (enforced by: install-time)
- Rollback execution must emit tamper-evident audit records for all policy-affecting changes. (enforced by: runtime)
- Rollback operations must be policy-authorized and must not bypass forward-only policy constraints. (enforced by: compile-time + install-time)
- Rollback proceeds in reverse class order: activations first, then declarations, then schema. (enforced by: runtime)
- Schema drop operations must be blocked when live gnomon instances exist for the target kind. (enforced by: install-time)
- Schema operations must complete and commit before any declaration operations referencing those kinds are applied. (enforced by: install-time)
- When a model declaration changes, all agents referencing it must be included as update activation entries so they restart with the new binding. (enforced by: install-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MAY — Legacy migration artifacts coexist only under explicit transition policy.
- MUST — Transition policy includes cutoff criteria and timeline.
Install Plan Contract
- MUST — If policyAffecting is declared in authoring metadata, install-plan entries preserve the flag. (proof citation:
rfc0005_policy_affecting_preserved; verification pending) - MUST — Install plan entries conform to the typed operation taxonomy from §4a. (proof citation:
rfc0005_b69_grounded; verification pending) - MUST — Install plan entries include op_class, op_type, target_path, explicit dependency edges, and rollback authorization scope for policy-affecting operations.
- SHOULD — Install plan entries include risk/impact annotation and a human-readable description.
- MUST — bcRisk is assigned conservatively from declared authoring metadata, with omitted/unknown mapping to BC_UNKNOWN.
Install Plan Operation Taxonomy
- MUST — An activation operation is rejected if the agent’s module declaration has not passed a clean compile. (proof citation:
rfc0005_activation_blocked_on_compile_fail; verification pending) - MUST — Bulk activations are ordered by agent dependency graph; rollback proceeds in reverse class order (activations, declarations, schema).
- MUST — Each DDL operation is wrapped in a transaction; cross-DDL atomicity within a single apply is required.
- MUST — Every install plan entry carries op_class, op_type, target_path, bc_risk, dependency_edges, and rollback_strategy.
- MUST — Install plan entries are typed with one of three operation classes (declaration, schema, activation).
- MUST — Schema operations complete and commit before any declaration operations referencing those kinds; declarations complete before dependent activations.
- MUST — The install pipeline verifies no live gnomon instances exist before executing schema drop; verification failure blocks the operation.
Invariants
- MUST — Apply stage records outcome and diagnostics.
- MUST — Each install-plan operation carries a backward-compatibility risk classification (BC_SAFE, BC_BREAKING, or BC_UNKNOWN).
- MUST — Failed apply produces actionable failure context. (proof citation:
rfc0005_failed_apply_context; verification pending) - MUST — Install plans are derived from declared vs installed state diff.
- SHOULD — Plan generation is deterministic for identical inputs. (proof citation:
rfc0005_b21_grounded; verification pending)
Model Declaration Availability During Install
- MUST — A model is registered before any agent that references it is activated. (proof citation:
rfc0005_b5_grounded; verification pending) - MUST — Compiler emits M05046 if an agent’s model reference cannot be resolved at agent activation time. (proof citation:
rfc0005_b17_grounded; verification pending) - MUST — Module updates changing a model declaration include a model_update entry plus update activation entries for all dependent agents. (proof citation:
rfc0005_model_update_with_activations; verification pending) - MUST — On rollback crossing a model_update, the prior model version is restored and dependent agents are deactivated before model restore.
- MUST_NOT — Prior model versions are used for new agent invocations after an update completes. (proof citation:
rfc0005_no_prior_model_post_update; verification pending) - MUST — The install plan includes a model_register activation entry for any model declaration being introduced or updated. (proof citation:
rfc0005_install_plan_model_register; verification pending)
Rollback and Recovery
- SHOULD — Each phase defines rollback strategy and trigger conditions.
- MUST — Partial failure handling identifies safe retry boundaries.
- MUST — Rollback boundaries are explicit; cross-module rollback requires explicit inter-module agreement.
- SHOULD — Rollback execution supports checkpoint markers to constrain recovery scope.
- MUST — Rollback procedure is documented for critical streams.
- MUST — When cross-module rollback is deferred, plan generation rejects cross-module scope with actionable diagnostics. (proof citation:
rfc0005_b32_grounded; verification pending)
Rule Compilation Cache Invalidation
- MUST — Cache entries created during a forward install are deleted as part of rollback. (proof citation:
rfc0005_rollback_invalidates_cache; verification pending) - MUST_NOT — Install plan invalidates the cache when neither model digest nor template version changes. (proof citation:
rfc0005_b55_grounded; verification pending) - MUST — On model digest change, all cache entries keyed under the prior model digest are deleted before the new kernel artifact is activated. (proof citation:
rfc0005_b47_grounded; verification pending) - MUST — On promptTemplate version change, all cache entries keyed under the prior template version are deleted. (proof citation:
rfc0005_b35_grounded; verification pending) - SHOULD — Prior cache entries deleted during forward install are restored from rollback snapshot when available. (proof citation:
rfc0005_rollback_restores_cache_when_available; verification pending) - MUST_NOT — Rollback leaves the system with new-install cache entries co-existing with a prior-install kernel artifact. (proof citation:
rfc0005_b43_grounded; verification pending)
Security and Authorization
- MUST — Agent-initiated plan generation and apply requests run under least-privilege identities and are auditable as agent-originated. (proof citation:
rfc0005_b52_grounded; verification pending) - MUST — Agent-initiated rollback requests are rejected when forward-only policy constraints would be violated. (proof citation:
rfc0005_rollback_blocked_by_forward_only; verification pending) - MUST — Install-plan validation rejects rollback authorization chains that depend on forward-only constraints when full chain analysis is available.
- MUST — Lifecycle operations run under least-privilege roles. (proof citation:
rfc0005_lifecycle_least_privilege; verification pending) - MUST — Policy-affecting operations are auditable. (proof citation:
rfc0005_b38_grounded; verification pending) - MUST — Rollback execution emits tamper-evident audit records for all policy-affecting changes.
- MUST — Rollback operations are policy-authorized and do not bypass forward-only policy constraints. (proof citation:
rfc0005_b0_grounded; verification pending) - MUST — Session/transaction context is isolated per operation scope. (proof citation:
rfc0005_b62_grounded; verification pending)
Sequencing Rules
- MUST — Dependency ordering is explicit and stable.
- MAY — Non-dependent operations are parallelized when safe.
- MUST — On failure, rollback computes a minimal recompute set from dependency edges rather than re-executing unrelated operations.
- SHOULD — Security-sensitive operations are grouped for atomic safety.
Linked References
(no cross-RFC dependencies)