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.
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
| Term | Meaning |
|---|---|
| Canonical version | The integer derived from the SemVer MAJOR component; the discrete unit of upgrade/rollback. |
| Install hook | A callable artifact (preInstall, postInstall, preUninstall) invoked at a specific lifecycle phase. |
| Install plan | The build artifact (RFC-0005) describing the set of modules to install and the order. |
| Install transaction | A single atomic unit covering one module’s installation; aborted on any failure within. |
| Lifecycle policy | The decision logic that picks one of install | upgrade | rollback | no-op based on installed vs. target canonical version. |
| Linker | The cross-module symbol resolver that ties template calls and provider tokens to their declarations. |
| Object installer | A typed handler that knows how to materialize one objects entry of a specific kind into graph entities. |
| Stable id | A deterministic identifier derived from (module, object name, kind, scope); used for upserts so reinstalls are idempotent. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M41001 | Error | Module dependency graph contains a cycle |
M41002 | Error | Required dependency not present in batch and not installed |
M41003 | Warning | Optional dependency not resolvable; module installs but feature is unavailable |
M41004 | Error | Plan contains two manifests with the same (namespace, version) |
M41010 | Error | Upgrade target canonical version is behind source (illegal direction) |
M41011 | Error | Rollback target with no installed source |
M41020 | Error | Per-object installer failed; underlying cause in diagnostic chain |
M41021 | Error | Object’s stable id collides with an existing graph entity owned by a different module |
M41030 | Error | Linker cannot resolve a cross-module reference; deferred candidate not present in plan |
M41031 | Warning | Multiple providers claim the same token; resolved deterministically by manifest hash |
M41040 | Error | Hook artifact requires runtime services not available at install time |
M41041 | Error | Hook execution failed; install transaction rolled back |
M41050 | Error | Required predicate (owns, module.depends_on, module.provides, module.installed_by) is missing — bootstrap module not installed |
M41060 | Error | Uninstall refused: resource is referenced by statements from another module; pass force: true to override |
M41061 | Warning | force: true uninstall removed a resource referenced by another module; dangling references are now in the graph |
M41070 | Error | Module record stable id collision — two modules attempt to register at the same namespace |
M41080 | Warning | Manifest 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
- A changed manifest hash triggers reinstall even when the version field is unchanged. (enforced by: runtime)
- Any install-hook failure rolls back the entire install transaction with no partial-success mode. (enforced by: runtime)
- Audit emission for every install is mandatory and may not be suppressed by the module being installed. (enforced by: runtime)
- Audit emission for transactional writes is mandatory and must not be suppressible. (enforced by: runtime)
- Cycles in the module dependency graph must be rejected at planning time via M41001. (enforced by: planning-time)
- Each module’s install runs in exactly one isolated rollback boundary, using an owned transaction or caller savepoint. (enforced by: runtime)
- Identical inputs to the install pipeline must produce identical graph mutations. (enforced by: runtime)
- Lifecycle policy decisions are deterministic and based only on version comparison; no other inputs influence strategy selection. (enforced by: runtime)
- Per-module install transactions are atomic. (enforced by: runtime)
- Stable ids ensure that reinstalling unchanged manifests produces no graph changes. (enforced by: runtime)
- 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)
- 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
- MUST — The four required predicates MUST be declared by the core module and present before any other install runs.
Dependency Resolution
- MUST — Calls to a dropped optional-dependency template MUST produce M40021 at compile time. (proof citation:
rfc0041_b1_grounded; verification pending) - MUST — Cycles in the dependency graph MUST produce M41001 at planning time. (proof citation:
rfc0041_b33_grounded; verification pending) - MUST — The topological sort MUST be deterministic across runs, breaking ties by lexicographic ordering of qualified module paths.
- MUST — Two manifests with the same (namespace, version) MUST be rejected at planning time (M41004). (proof citation:
rfc0041_b18_grounded; verification pending)
Hooks
- MUST — A hook artifact MUST accept zero or one with arguments.
- MUST_NOT — Hooks MUST NOT spawn detached work that survives transaction boundaries. (proof citation:
rfc0041_b3_grounded; verification pending) - MUST — Hooks MUST execute within the install transaction.
- MUST — Hooks requiring runtime services beyond the install context MUST produce M41040 at install time. (proof citation:
rfc0041_b12_grounded; verification pending)
Install Transaction
- MUST — Cross-module atomicity MUST be implemented by higher-level orchestration; the engine does not provide it.
- MUST — In multi-tenant runtimes, the install transaction MUST set the tenant context before phase 3.
- MUST — The install engine MUST use GraphClient.isolatedTransaction(callback) to ensure each module has an owned transaction or nested savepoint rollback boundary.
- 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
- MUST — Hook failures MUST roll back the entire install transaction.
- MUST — Module dependency graph cycles MUST be rejected at planning time.
Lifecycle Policy
- MUST — Forced reinstall MUST treat the install as a fresh install regardless of installed state.
- MUST — Rollback from a state with no installed source MUST produce M41011. (proof citation:
rfc0041_b16_grounded; verification pending) - MUST — Upgrade with target canonical version less than source MUST produce M41010. (proof citation:
rfc0041_b24_grounded; verification pending)
Linker
- MUST — Implementations MUST prefer deferral when ordering allows resolution within the plan.
- 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
- 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
- MUST — Audit emission is mandatory and MUST NOT be suppressible by the module being installed.
- 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.
- 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.
- 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.
- 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
- MUST — Every module object MUST have a deterministic stable id derived at install time. (proof citation:
rfc0041_b38_grounded; verification pending) - MUST — Implementations MUST compare existing object stable ids to the planned set and upsert matches. (proof citation:
rfc0041_b35_grounded; verification pending) - MUST — Reinstalling unchanged manifests MUST produce no graph changes (idempotent reinstall). (proof citation:
rfc0041_b31_grounded; verification pending) - 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.
- 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.
- MUST_NOT — The manifest hash domain MUST NOT include the metadata.annotations block.
The Install Pipeline
- MUST — Identical inputs MUST produce identical graph mutations (deterministic install pipeline). (proof citation:
rfc0041_b6_grounded; verification pending) - MAY — Subsequent modules MAY still be installed after a failure depending on the plan’s continueOnError flag.
Uninstall
- SHOULD — Tooling SHOULD warn the operator when downstream user data exists for the module’s resource types.
- 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
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0005 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |