gnomonlearn
Docs/RFC-0041/Reference catalog

RFC-0041 · 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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0041: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0041.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0041. Edit that source and regenerate this catalog.


Title: Graph Install Engine
Status: draft
Owners: Module Platform, Runtime
Diagnostic range: M41000-M41099

Depends on: RFC-0001, RFC-0005, RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040

Proof citations in source: 14 / 14. Standalone proof verification is pending.


Definitions

TermMeaning
Canonical versionThe integer derived from the SemVer MAJOR component; the discrete unit of upgrade/rollback.
Install hookA callable artifact (preInstall, postInstall, preUninstall) invoked at a specific lifecycle phase.
Install planThe build artifact (RFC-0005) describing the set of modules to install and the order.
Install transactionA single atomic unit covering one module’s installation; aborted on any failure within.
Lifecycle policyThe decision logic that picks one of install | upgrade | rollback | no-op based on installed vs. target canonical version.
LinkerThe cross-module symbol resolver that ties template calls and provider tokens to their declarations.
Object installerA typed handler that knows how to materialize one objects entry of a specific kind into graph entities.
Stable idA deterministic identifier derived from (module, object name, kind, scope); used for upserts so reinstalls are idempotent.

Diagnostics

CodeSeverityDescription
M41001ErrorModule dependency graph contains a cycle
M41002ErrorRequired dependency not present in batch and not installed
M41003WarningOptional dependency not resolvable; module installs but feature is unavailable
M41004ErrorPlan contains two manifests with the same (namespace, version)
M41010ErrorUpgrade target canonical version is behind source (illegal direction)
M41011ErrorRollback target with no installed source
M41020ErrorPer-object installer failed; underlying cause in diagnostic chain
M41021ErrorObject’s stable id collides with an existing graph entity owned by a different module
M41030ErrorLinker cannot resolve a cross-module reference; deferred candidate not present in plan
M41031WarningMultiple providers claim the same token; resolved deterministically by manifest hash
M41040ErrorHook artifact requires runtime services not available at install time
M41041ErrorHook execution failed; install transaction rolled back
M41050ErrorRequired predicate (owns, module.depends_on, module.provides, module.installed_by) is missing — bootstrap module not installed
M41060ErrorUninstall refused: resource is referenced by statements from another module; pass force: true to override
M41061Warningforce: true uninstall removed a resource referenced by another module; dangling references are now in the graph
M41070ErrorModule record stable id collision — two modules attempt to register at the same namespace
M41080WarningManifest hash changed but version did not bump — likely reinstall of an in-place edit; SHOULD be a version bump per RFC-0014

Dependency neighborhood

graph LR
  nRFC_0041["RFC-0041"]
  nRFC_0001["RFC-0001"]
  nRFC_0041 --> nRFC_0001
  nRFC_0005["RFC-0005"]
  nRFC_0041 --> nRFC_0005
  nRFC_0006["RFC-0006"]
  nRFC_0041 --> nRFC_0006
  nRFC_0007["RFC-0007"]
  nRFC_0041 --> nRFC_0007
  nRFC_0036["RFC-0036"]
  nRFC_0041 --> nRFC_0036
  nRFC_0037["RFC-0037"]
  nRFC_0041 --> nRFC_0037
  nRFC_0038["RFC-0038"]
  nRFC_0041 --> nRFC_0038
  nRFC_0039["RFC-0039"]
  nRFC_0041 --> nRFC_0039
  nRFC_0040["RFC-0040"]
  nRFC_0041 --> nRFC_0040

Invariants

  1. A changed manifest hash triggers reinstall even when the version field is unchanged. (enforced by: runtime)
  2. Any install-hook failure rolls back the entire install transaction with no partial-success mode. (enforced by: runtime)
  3. Audit emission for every install is mandatory and may not be suppressed by the module being installed. (enforced by: runtime)
  4. Audit emission for transactional writes is mandatory and must not be suppressible. (enforced by: runtime)
  5. Cycles in the module dependency graph must be rejected at planning time via M41001. (enforced by: planning-time)
  6. Each module’s install runs in exactly one isolated rollback boundary, using an owned transaction or caller savepoint. (enforced by: runtime)
  7. Identical inputs to the install pipeline must produce identical graph mutations. (enforced by: runtime)
  8. Lifecycle policy decisions are deterministic and based only on version comparison; no other inputs influence strategy selection. (enforced by: runtime)
  9. Per-module install transactions are atomic. (enforced by: runtime)
  10. Stable ids ensure that reinstalling unchanged manifests produces no graph changes. (enforced by: runtime)
  11. The four required predicates owns, module.depends_on, module.provides, and module.installed_by must be declared by core and present before any other install runs. (enforced by: runtime)
  12. Uninstall must refuse to remove resources referenced by statements from other modules unless force:true is passed. (enforced by: runtime)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Compatibility and Migration

  1. MUST — The four required predicates MUST be declared by the core module and present before any other install runs.

Dependency Resolution

  1. MUST — Calls to a dropped optional-dependency template MUST produce M40021 at compile time. (proof citation: rfc0041_b1_grounded; verification pending)
  2. MUST — Cycles in the dependency graph MUST produce M41001 at planning time. (proof citation: rfc0041_b33_grounded; verification pending)
  3. MUST — The topological sort MUST be deterministic across runs, breaking ties by lexicographic ordering of qualified module paths.
  4. MUST — Two manifests with the same (namespace, version) MUST be rejected at planning time (M41004). (proof citation: rfc0041_b18_grounded; verification pending)

Hooks

  1. MUST — A hook artifact MUST accept zero or one with arguments.
  2. MUST_NOT — Hooks MUST NOT spawn detached work that survives transaction boundaries. (proof citation: rfc0041_b3_grounded; verification pending)
  3. MUST — Hooks MUST execute within the install transaction.
  4. MUST — Hooks requiring runtime services beyond the install context MUST produce M41040 at install time. (proof citation: rfc0041_b12_grounded; verification pending)

Install Transaction

  1. MUST — Cross-module atomicity MUST be implemented by higher-level orchestration; the engine does not provide it.
  2. MUST — In multi-tenant runtimes, the install transaction MUST set the tenant context before phase 3.
  3. MUST — The install engine MUST use GraphClient.isolatedTransaction(callback) to ensure each module has an owned transaction or nested savepoint rollback boundary.
  4. MUST — The install pipeline phases 3–8 for a single module MUST run in one isolated rollback boundary, using an owned transaction or caller savepoint.

Invariants

  1. MUST — Hook failures MUST roll back the entire install transaction.
  2. MUST — Module dependency graph cycles MUST be rejected at planning time.

Lifecycle Policy

  1. MUST — Forced reinstall MUST treat the install as a fresh install regardless of installed state.
  2. MUST — Rollback from a state with no installed source MUST produce M41011. (proof citation: rfc0041_b16_grounded; verification pending)
  3. MUST — Upgrade with target canonical version less than source MUST produce M41010. (proof citation: rfc0041_b24_grounded; verification pending)

Linker

  1. MUST — Implementations MUST prefer deferral when ordering allows resolution within the plan.
  2. MUST — The linker MUST detect unresolvable cross-module references and either defer them or fail with M41030. (proof citation: rfc0041_b29_grounded; verification pending)

Per-Object Installer Dispatch

  1. MUST — Diagnostics for a failed object installer MUST identify the manifest, object name, kind, and underlying cause. (proof citation: rfc0041_b8_grounded; verification pending)

Provenance and Audit

  1. MUST — Audit emission is mandatory and MUST NOT be suppressible by the module being installed.
  2. MUST — Inline template registration MUST use the captured definition, existing name@version identity, and whole replacement in the current module transaction; a false replacement result fails the module.
  3. MUST — Installed reads and RPC consumers MUST verify the complete envelope and observed module identity, version, and hash agreement, reject malformed or orphaned pairs and hashless responses, and transport the complete manifest and template map plus output-only ModuleBundle.manifest_hash at tag 6, with tags 1 through 5 unchanged.
  4. MUST — The module rollback boundary MUST replace the complete verified compiled envelope in core.module_manifest at its existing namespace key together with the agreeing core.module identity, version, and linkHash; a false replacement result fails and rolls back the module.
  5. MUST — When the selected lifecycle policy skips installation, the installed complete artifact and paired module hash MUST remain unchanged together; the skipped candidate cannot partially refresh the stored snapshot or its stored template map.

Stable Identity

  1. MUST — Every module object MUST have a deterministic stable id derived at install time. (proof citation: rfc0041_b38_grounded; verification pending)
  2. MUST — Implementations MUST compare existing object stable ids to the planned set and upsert matches. (proof citation: rfc0041_b35_grounded; verification pending)
  3. MUST — Reinstalling unchanged manifests MUST produce no graph changes (idempotent reinstall). (proof citation: rfc0041_b31_grounded; verification pending)
  4. MUST — The installation entry point MUST verify and capture every supplied compiled envelope before hooks, template registration, registry mutation, or graph writes; caller mutation after capture cannot change the selected definitions.
  5. MUST — The manifest digest MUST be raw lowercase SHA-256 hexadecimal of UTF-8 canonicalManifestJson: remove only top-level metadata.annotations, JSON-normalize bigint values to decimal strings, order all object keys ordinally including numeric-looking keys, and preserve array order and other admitted fields.
  6. MUST_NOT — The manifest hash domain MUST NOT include the metadata.annotations block.

The Install Pipeline

  1. MUST — Identical inputs MUST produce identical graph mutations (deterministic install pipeline). (proof citation: rfc0041_b6_grounded; verification pending)
  2. MAY — Subsequent modules MAY still be installed after a failure depending on the plan’s continueOnError flag.

Uninstall

  1. SHOULD — Tooling SHOULD warn the operator when downstream user data exists for the module’s resource types.
  2. MUST — Uninstall MUST refuse to remove resources referenced by statements from other modules unless force: true is passed. (proof citation: rfc0041_b14_grounded; verification pending)

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0005
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040