RFC-0041 · Graph Install Engine
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 →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
The install engine is the runtime component that materializes module manifests into graph state. It takes per-module compiled artifacts (RFC-0040 §11.1), each containing a complete resolved manifest, its exact derived template map, and its required manifest hash, and produces persistent graph entities: registered resource types, instantiated resources, asserted statements, registered predicates, materialized policies, executed install hooks. These Graph module artifacts are distinct from RFC-0002’s larger Gnomon/root bundle.
This RFC specifies the install runtime: dependency resolution, deterministic object identity, transactional install lifecycle (install / upgrade / rollback / no-op), per-object-kind installer dispatch, hooks, and the cross-module linker that resolves symbolic references across module boundaries.
RFC-0005 defines the install plan — what is going to be installed, in what order, with what approvals. This RFC defines the install runtime — how the plan is applied. The two are complementary; this RFC consumes the artifact RFC-0005 produces.
This is a faithful codification of the engine at /Volumes/Workspace/savvi-studio-full/packages/graph-module-engine/.
2. Definitions
| Term | Meaning |
|---|---|
| Install plan | The build artifact (RFC-0005) describing the set of modules to install and the order. |
| Compiled module artifact | The RFC-0040 §11.1 envelope: a complete resolved manifest, exact derived templates, and required manifestHash. |
| Install transaction | A single atomic unit covering one module’s installation; aborted on any failure within. |
| Object installer | A typed handler that knows how to materialize one objects entry of a specific kind into graph entities. |
| Linker | The cross-module symbol resolver that ties template calls and provider tokens to their declarations. |
| Stable id | A deterministic identifier derived from (module, object name, kind, scope); used for upserts so reinstalls are idempotent. |
| Lifecycle policy | The decision logic that picks one of install | upgrade | rollback | no-op based on installed vs. target canonical version. |
| 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. |
3. The Install Pipeline
A single module’s installation runs through these phases in order. Phases 3–8 share one isolated rollback boundary (§6.1):
0. Resolve dependencies ← §4
1. Evaluate lifecycle policy ← §5
2. Open isolated module rollback boundary ← §6
3. preInstall hook ← §10
4. Allocate stable IDs for objects ← §7
5. Per-object installer dispatch ← §8
- resource_type
- resource
- statement
- predicate
- predicate_policy
- template (registration only; no instantiation)
- template-call (instantiates the referenced template)
- operation (registration only)
- data_source
6. Linker pass — resolve symbolic refs ← §9
7. Record install provenance ← §11
8. postInstall hook ← §10
9. Complete module boundary (commit owned transaction or release savepoint)
Failure before the rollback boundary opens prevents module writes. A failure in phases 3–8 rolls back that boundary. The install plan reports the failure to the caller; subsequent modules MAY be installed according to continueOnError only after successful rollback and any savepoint release. Boundary lifecycle failures remain fatal (§6.1).
The install pipeline is deterministic: identical inputs (manifests, installed state, lifecycle policy) MUST produce identical graph mutations.
4. Dependency Resolution
4.1 Topological order
The install planner resolves the manifests’ modules: dependencies into a DAG and topologically sorts. The resulting order is the install order.
Cycles in the dependency graph MUST produce M41001 at planning time. Missing dependencies that are neither already installed nor in the install batch produce M41002 unless marked optional: true (in which case M41003 warning is emitted).
The topological sort MUST be deterministic across runs: ties are broken by lexicographic ordering of qualified module paths.
4.2 Conflict and update resolution
When a module is already installed and the plan includes a different version of the same module, the planner emits an update entry. The lifecycle policy (§5) decides whether the update is an upgrade, rollback, or no-op.
Two manifests with the same (namespace, version) produce M41004 at planning time — the install plan MUST be unambiguous.
4.3 Optional dependencies
A dependency marked optional: true is included if resolvable, skipped otherwise. When skipped:
- M41003 (warning) is emitted.
- Any
templates:import that depends on the skipped module is silently dropped from the consumer’s accessible set. - Calls to a dropped template MUST produce M40021 at compile time of the consuming module (RFC-0040 §4.2).
5. Lifecycle Policy
5.1 Canonical version
The canonical version of a manifest is the integer MAJOR component of its SemVer. Modules are installed at the canonical version; minor and patch differences within the same canonical version are rolling upgrades that do not require lifecycle planning.
5.2 Migration strategies
For each module in the install plan, the policy returns one of:
| Strategy | Condition | Action |
|---|---|---|
install | No installed version present | Run install pipeline §3 |
upgrade | Target canonical version > source canonical version | Run install pipeline §3 with mode: upgrade; data migrations (RFC-0016) execute as part of phase 5 |
rollback | Target canonical version < source canonical version | Run install pipeline §3 with mode: rollback; reverse-direction migrations execute |
no-op | Target canonical version == source canonical version | Skip phases 3–8; record a no-op provenance entry |
upgrade with target < source MUST produce M41010 (illegal direction). rollback from a state with no installed source MUST produce M41011.
5.3 Version selection within a canonical version
When multiple manifests for the same canonical version are available (e.g., a 1.0.5 patch of a previously installed 1.0.3), the policy selects the highest patch version available. The selection is deterministic via descending SemVer comparison.
5.4 Forced reinstall
When the manifest’s defaultConfig.forceReinstall is true or the install request carries force: true, the lifecycle policy MUST treat the install as a fresh install regardless of installed state. Existing graph state owned by the module is uninstalled first (RFC-0040 §uninstall service); then the install pipeline runs.
6. Install Transaction
6.1 Transaction scope
The entire install pipeline (phases 3–8) for a single module runs in one isolated rollback boundary (RFC-0038 §3.4). With no active caller transaction, phase 2 begins the module’s backend transaction and phase 9 commits it; a thrown failure rolls it back. With an active caller transaction, the module uses a savepoint, releases it on success, and rolls back to it and releases it on failure. A nested success is not a global commit.
The install engine MUST use GraphClient.isolatedTransaction(callback) (RFC-0038 §3.4), composed from the backend lifecycle operations in RFC-0037 §4.8. An active caller transaction without complete savepoint support MUST be rejected before module writes. The engine MAY continue after a failed module only after its rollback and any savepoint release have succeeded. Boundary lifecycle failures are fatal, preserve their underlying causes, and MUST propagate through both single-module and batch entry points. Successfully rolled-back installer failures keep the existing single-module failed-result behavior; batch continuation follows continueOnError.
6.2 Cross-module batching
When the plan installs multiple modules without an active caller transaction, each module owns its transaction. Failures in one module’s transaction do NOT roll back already-committed earlier modules; they only roll back the current module. Inside an explicit caller transaction, each module has its own savepoint rollback boundary; earlier successful modules remain pending until the caller commits, and the caller may still roll back the whole outer scope.
If the plan requires cross-module atomicity (a “all-or-nothing” install of a multi-module batch), the planner MUST wrap the entire plan in a higher-level orchestration (an explicit caller transaction with savepoints, a saga, or a compensating workflow) — the install engine itself does not provide multi-module atomicity.
6.3 RLS context
If the runtime is multi-tenant, the install transaction MUST set the tenant context (RFC-0037 §5.4) before phase 3. Modules are typically installed in a privileged tenant (e.g., the system tenant); per-tenant module installation is supported but requires explicit tenant binding in the install plan.
7. Stable Identity
7.1 Stable ID derivation
Every module object MUST have a deterministic stable id derived at install time:
stable_id = "<module-namespace>.<module-name>/<object-type>/<scope>"
Where:
<module-namespace>.<module-name>is the qualified module path<object-type>is the object kind (resource_type,predicate, etc.)<scope>defaults to the object’s namespace path or the object’s local name
Authors MAY override the scope via an id hint on the object body:
<name>:
type: predicate
path: org.member
id:
seed: "org-membership-predicate" # overrides default scope
with:
domain: "org"
strength: "primary"
The with map contributes additional dimensions; sorted-by-key entries are appended |key=value to the seed.
7.2 Idempotent install
Stable ids enable idempotent reinstall: running the install pipeline a second time with unchanged manifests MUST produce no graph changes. Implementations MUST compare existing object stable ids to the planned set; matches are upserted (RFC-0036 §3.3), absent ones are created.
7.3 Manifest hash
Each manifest is hashed deterministically at compile time (RFC-0040 §11). The hash:
- Is a SHA-256 of the canonical-stable-sorted-JSON representation of the manifest.
- Is recorded as a graph property on the installed module’s record.
- Triggers reinstall when the new hash differs from the recorded hash, even if the version field is unchanged.
manifestHash = lowercaseHex(sha256(utf8(canonicalManifestJson(manifest))))
core.module.linkHash = manifestHash
The hash domain MUST include all object bodies, exports, dependencies, hooks, and providers. It MUST NOT include the metadata.annotations block (which is informational only).
canonicalManifestJson removes only the top-level manifest’s
metadata.annotations, converts bigint values to decimal strings through a JSON
serialization/parsing round trip, and writes object keys in ordinal lexical
order. Numeric-looking keys follow that same ordinal order; array order is
preserved. Nested annotations and other admitted fields remain in the domain.
The digest is raw lowercase 64-character hexadecimal, without an algorithm
prefix. The complete retained manifest still includes its annotations. The
separate linked-module-set hash is a different domain and cannot substitute for
this per-manifest digest.
Before any hook, template registration, registry mutation, or graph write, the installation entry point verifies and captures every supplied compiled envelope under RFC-0040 §11.1. Missing or invalid hashes, lossy schema normalization, and template-map disagreement reject the input before those activities. Caller mutation after capture cannot alter the definitions selected for installation. This is consistency verification, not a compiler-origin or authorization check.
Lifecycle priority remains a separate decision: the hash-triggered reinstall rule above and §5’s same-canonical no-op policy are unchanged by the artifact handoff. This section does not choose their precedence. If the selected policy skips installation, the previously installed artifact and hash remain paired; the skipped candidate cannot refresh only part of the installed state.
8. Per-Object Installer Dispatch
The engine routes each object in the manifest’s objects map to a typed installer. The installer is responsible for translating the object body into one or more backend writes (RFC-0037).
| Object kind | Installer behavior |
|---|---|
resource_type | Creates a Resource of kind graph.resource_type storing the type’s metadata (description, supertype, fields, status). Stable id pattern: <module>/resource_type/<name>. |
resource | Creates a Resource of the declared kind (RFC-0036 §4.1). Upserts on (kind, externalId) if externalId is set; otherwise uses stable id. |
statement | Creates a Statement (RFC-0036 §4.2). Predicate is resolved via the linker (§9). |
predicate | Creates a Predicate (RFC-0036 §4.3) at the declared path. Idempotent: if predicate exists with matching path, no-op. |
predicate_policy | Creates a PredicatePolicy (RFC-0042 §3). Includes derived stable id and registers presets if any. |
template (inline) | Registers the template in the runtime template registry (RFC-0039 §7) under <module-namespace>.<template-name>. Does NOT instantiate. |
template-call | Resolves the qualified template name via the linker (§9), then executes the template (RFC-0039 §6) within the install transaction. Result resources/statements are created inline. |
operation | Registers the operation in the operation registry (RFC-0043 §3). Does NOT execute. |
data_source | Reads the configured source and creates resources accordingly. Implementation-specific; reserved for future expansion (RFC-0040 §9.5). |
8.1 Order within a module
Within a module’s install transaction, objects are processed in this order:
1. Predicates
2. Resource types
3. Templates (registration)
4. Operations (registration)
5. Resources
6. Predicate policies
7. Template calls
8. Statements
9. Data sources
This ordering ensures referenced declarations exist before referrers run.
8.2 Failure modes
If an installer fails, the install transaction rolls back. The diagnostic for the failed object MUST identify the manifest, the object name, the kind, and the underlying cause.
Per-object failures map to M41020 (object install failed); the cause-specific code (e.g., M36020 for duplicate predicate path) is included in the diagnostic chain.
9. Linker
9.1 Cross-module symbol resolution
After per-object installers have run (phase 6), the linker resolves all symbolic references that span modules:
- Template-call resolution — qualified type names (e.g.,
core.type,rdfs.class) resolve against the module’stemplates:import list and the dependency closure. - Provider binding — declared
providers:are bound to theirtokens:in the runtime’s DI registry. - Predicate references — statements that name predicates by ltree path resolve to predicate ids.
- Resource references — module-level resources that reference other modules’ resources via
externalIdare looked up through the graph client.
9.2 Deferred resolution
Some references may not be resolvable until later phases of the install plan (e.g., a module referencing a resource created by a later-installed module). The linker MUST detect such cases and either:
- Defer the reference for resolution at the end of the plan’s full execution, OR
- Fail with M41030 if the reference cannot possibly be resolved (referencing a non-installed, non-batched module).
Implementations MUST prefer deferral when the dependency exists in the install plan and ordering allows it.
9.3 Provider precedence
When multiple providers claim the same token, the linker resolves in this order:
- Provider with explicit
override: true(most recent install wins). - Provider in a module with higher
category(core>application>extension). - Provider declared latest in install plan order.
Ambiguous resolutions (no clear winner) produce M41031 (warning) and the runtime selects deterministically by manifest hash to ensure reproducibility.
10. Hooks
10.1 Hook invocation
The three hook phases (RFC-0040 §7) execute as follows:
| Hook | Phase | Allowed surface |
|---|---|---|
preInstall | Phase 3 | Read-only graph access; configuration inspection; pre-flight validation |
postInstall | Phase 8 | Full graph access (read/write within transaction); seeding additional state; cross-module coordination |
preUninstall | Symmetric to phase 3 in uninstall flow | Read-only graph access; pre-flight validation; cleanup-of-derived-state |
Hooks MUST execute within the install transaction. They MUST NOT spawn detached work that survives transaction boundaries.
10.2 Hook artifact contract
A hook is either:
- A module object name — the engine looks up the named object (typically an operation or template) and invokes it.
- A qualified template name — the engine resolves through the dependency closure and invokes.
The hook artifact MUST accept zero or one with arguments — typically just the module’s defaultConfig payload. Hooks that require runtime services beyond the install context MUST produce M41040 at install time (the hook’s surface is too rich for install-time evaluation).
10.3 Hook failure
A hook failure rolls back the entire install transaction. There is no partial-success or “warn-and-continue” mode for hooks; their job is to gate or augment the install, and their failure means the install did not happen.
11. Provenance and Audit
11.1 Module record
Each successful install creates or updates a Resource of kind core.module:
{
kind: "core.module"
externalId: "<module-namespace>"
data:
namespace: <namespace>
version: <version>
canonical: <canonical-version>
linkHash: <sha256>
installedAt: <instant>
installerId: <bigint> # principal performing the install
strategy: install | upgrade | rollback | no-op
objectCount: <number>
}
This record is the authoritative source for “is this module installed?” queries.
11.1.1 Complete installed artifact
The same module rollback boundary persists the complete verified
CompiledGraphModuleBundle as the core.module_manifest payload at its existing
module-namespace external ID. This is a complete replacement, not a merge with a
reduced prior manifest. Its namespace, version, and manifestHash agree with the
paired core.module identity, version, and linkHash. A false replacement result
fails the module and rolls back the paired writes. This does not rename either
resource kind or its existing namespace-keyed storage identity.
The full resolved manifest retains its API identity, metadata, exports, dependencies, hooks, providers, and all other admitted fields. Installed serving uses that captured artifact and its exact derived templates; it does not reconstruct a manifest from namespace/version/objects or combine it with a separately retrieved latest template map.
Inline templates register their captured definitions using the existing
name@version resource identity inside the current module transaction.
Registration replaces the whole stored definition, and a false replacement
result fails the module. Current-module resolution uses the captured map;
dependency resolution retains its existing lookup behavior. This adds neither a
namespace-qualified template storage identity nor a claim of fully
version-pinned cross-module template closure.
When lifecycle policy skips a module, its previous complete snapshot and module record hash remain unchanged together. The candidate’s annotations, template map, or other fields do not partially refresh the skipped installation.
11.1.2 Readback and RPC integrity
Direct and bulk installed-module reads verify the full stored envelope and its
agreement with the observed core.module record before returning it. Missing,
reduced, malformed, duplicate, orphaned, or inconsistent stored pairs fail rather
than being synthesized into an artifact. When both records are absent, a direct
lookup reports that the module is not installed. Pair checks inside a
transaction do not establish snapshot isolation: under READ COMMITTED, a
concurrent commit between reads can cause a valid installation to be rejected.
Concurrent-read availability requires separate evidence.
The existing ModuleBundle RPC carries the complete captured manifest and
template map, with output-only manifest_hash at tag 6; existing tags 1–5
retain their meanings. Serving verifies the stored artifact before encoding.
Clients verify the full decoded envelope and require its namespace/version to
agree with the outer response identity before exposing it to providers or
installation. Hashless responses and invalid decoded artifacts are rejected.
Neither RPC projection nor client loading supplies a raw-manifest fallback.
This first-release handoff adds no deployed-data migration or compatibility alias. It does not change registry authority, authentication, authorization, transaction isolation, or the lifecycle-priority decision described in §7.3.
11.2 Required statements
Each install creates the following statements automatically:
| Predicate | Subject | Object | Meaning |
|---|---|---|---|
owns | module record | each created resource | The module owns the resources it created. |
module.depends_on | module record | each dependency module record | Records the resolved dependency edge. |
module.provides | module record | each provider record | Records the runtime services the module provides. |
module.installed_by | each created resource | system installer principal record | Provenance for audit. |
These statements are created in phase 7 and are NOT user-controllable; they are infrastructure for uninstall, dependency tracking, and audit.
11.3 Audit emission
Every install produces an audit log entry (RFC-0047) with at minimum:
- Module namespace and version
- Strategy (install / upgrade / rollback / no-op)
- Installer principal id
- Tenant id (if applicable)
- Object count
- Hook result statuses
- Manifest hash
- Duration
Audit emission is mandatory and MUST NOT be suppressible by the module being installed.
12. Uninstall
Uninstall is the inverse of install:
1. preUninstall hook ← §10
2. Remove statements where module record is the subject
3. Remove module-owned resources (those linked via `owns`)
4. Remove predicates declared by the module (only if no statements reference them; else M36021)
5. Remove the module record itself
6. Update DI registry to remove providers
Uninstall is transactional. It MUST refuse to remove resources that are referenced by statements from other modules unless force: true is passed (in which case dangling references are explicitly accepted and logged).
Uninstall does NOT delete user-created data that uses the module’s resource types; only the module’s own seed resources. Tooling SHOULD warn the operator when downstream user data exists.
13. Invariants
- Each module’s install runs in exactly one isolated rollback boundary, using an owned backend transaction or a savepoint within an explicit caller transaction (§6.1).
- Identical inputs produce identical graph mutations — the install pipeline is deterministic (§3).
- Stable ids ensure idempotent reinstall (§7.2).
- Manifest hash changes trigger reinstall even at the same version (§7.3).
- Cycles in the module dependency graph MUST be rejected at planning time (§4.1, M41001).
- Hook failures roll back the entire install transaction (§10.3).
- Audit emission is mandatory and not suppressible (§11.3).
- Uninstall MUST refuse to remove cross-module-referenced resources unless
force: true(§12). - The lifecycle policy is deterministic and version-comparison-based; no other inputs influence migration strategy selection (§5).
14. Compatibility and Migration
14.1 From legacy graph-module-engine
This RFC is a faithful codification of the engine at /Volumes/Workspace/savvi-studio-full/packages/graph-module-engine/:
| Legacy artifact | This RFC |
|---|---|
services/installation-service.ts | §3 install pipeline |
services/lifecycle-service.ts + services/lifecycle-policy.ts | §5 lifecycle policy |
services/dependency-resolution-service.ts + install/dependency-resolution.ts | §4 dependency resolution |
services/object-installer-service.ts | §8 per-object installer dispatch |
services/linker-service.ts | §9 linker |
services/install-transaction-service.ts | §6 install transaction |
services/uninstall-service.ts | §12 uninstall |
services/artifact-execution-service.ts | §10 hooks |
install/stable-id.ts | §7.1 stable id |
install/hash.ts | §7.3 manifest hash |
install/install-module.ts | §3 + §11 module record / required statements |
14.2 Required statement predicates
The four required predicates (owns, module.depends_on, module.provides, module.installed_by) are bootstrap predicates that MUST be declared by the core module and present before any other install runs. The bootstrap is part of the runtime image (RFC-0045).
14.3 Behavior changes
- Cross-module atomicity is explicitly out of scope (§6.2). Legacy code is permissive; this RFC requires explicit orchestration for multi-module atomicity.
- Hook failure rolls back unconditionally (§10.3). Legacy code has scattered partial-success modes for hooks; this RFC bans them.
force: truesemantics on uninstall require explicit acknowledgment of dangling references (§12). Legacy code logs but does not require explicit flag.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
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.