gnomonlearn
Docs/RFC-0005 lifecycle contract proposal

RFC-0005 lifecycle contract proposal

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.

Status: owner selected the authored per-agent activation contract for the first release; implementation conformance and the two authored ambiguities below remain open. Owners: module engine and runtime platform. Nothing is deployed, so this needs no live install-plan or module state migration.

Conflicting sources

TopicAuthored RFC-0005Companion Q&A
Activation atomicity§4a says activation operations are atomic per agent, ordered by dependency graph in bulk, and rolled back before declarations.Says activation is not atomic because model registration is external.
Rollback granularity§7 says checkpoint markers SHOULD be supported, Q2 SHOULD support self and plan scopes, and cross-module scope may be deferred with rejection.Says M0 MUST roll back to a checkpoint and M1 adds inverse-per-statement rollback. Neither M0/M1 profile is defined in authored §7.
Quality gate§8 defines security and authorization obligations, not a five-part install quality gate.Claims §8 requires no M-errors, post-install registry resolution, verified checkpoints, dry-run kernel load, and fixtures before activation.

Owner-selected first-release contract: retain the authored operation classes, class order, per-agent activation atomicity requirement, and Q2 rollback scopes. The companion Q&A now defers its M0/M1 profile and five-part quality gate until they have normative phase definitions, Lean facts, stable diagnostics, and implementation tests. If model registration cannot meet per-agent atomicity, define a recoverable activation state and compensating operation explicitly before release; do not claim atomicity from class order alone.

Additional authored ambiguities

  1. §4a requires bc_risk for every entry and §10 defines M05400 for missing classification, while §5 places risk/impact annotation in its SHOULD list. §5 later mandates conservative bcRisk assignment for Q2. Clarify that the machine field is required and a human-readable impact annotation is optional, or choose one rule and align all clauses.
  2. §4a lists activation_action as activate | deactivate | update, but §5a adds model_register | model_update | model_deregister. Define one complete activation action enum and per-action approval requirements. §5a first says a changed model declaration gets model_register, then requires model_update for a changed declaration. Specify which action represents an update. Model registration entries also need a model_ref rather than an agent_id; the typed-entry schema should express which target field is required for each action.
  3. §7 recommends Q2 support for self and plan rollback scopes. That is not an exclusive enum: a projection relationship currently reads limited-to. Preserve the SHOULD level and clarify any additional scopes before making a closed enum.

Recommended first-release activation shape: use six explicit action values (activate, deactivate, update, model_register, model_update, model_deregister). A new model declaration emits model_register; a changed declaration emits model_update. Agent actions require agent_id; model actions require model_ref. Approval is conditional on agent activate/update and, outside development, model model_register/ model_update. Represent the action-specific payloads as a protobuf oneof so a model entry does not inherit an unconditional agent_id requirement.

The RDF domain review found an independent install-operator ontology error: it is typed domain#Capability although §4a uses it as a principal role. The principal-role identity proposal gives the exact correction and awaits the owner choice. The separate ModuleLifecycle link was corrected to domain#appearsInSection targeting the emitted §3 section; its source and generated Turtle now agree with the ontology. Verify local query consumers before the first publication; no deployed-state migration is needed.

Acceptance

The phase and atomicity choice is approved; verify it through implementation. Align the remaining authored ambiguities, Lean catalog, claim/domain projection sources, and generated references. Exercise a failed agent activation, model registration failure, class-order rollback, self/plan scope, missing bc_risk, and each activation action in compiler and installer tests. Keep the install-plan DTO in protobuf under the repository’s schema convention. Reconcile the model-register/update trigger, agent_id/model_ref action fields, and projection relationship subjects. Run drift and integration gates before the first release.