RFC-0040 · 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-0040: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0040.This page is generated from the
lean/Gnomon/Spec/module for RFC-0040. Edit that source and regenerate this catalog.
Title: Graph Module Manifest
Status: draft
Owners: Compiler, Module Platform
Diagnostic range: M40000-M40099
Depends on: RFC-0001, RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038, RFC-0039
Extended by: RFC-0041, RFC-0042, RFC-0043, RFC-0044
Proof citations in source: 11 / 11. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Classifier | A named, exported semantic-contract label. Lightweight metadata for cross-module discovery. |
| Hook | A named lifecycle callback: preInstall, postInstall, preUninstall. |
| Module | A namespaced, versioned bundle of declarations that contributes to the graph. Identified by (namespace, version). |
| Module manifest | The top-level document (module.gnm) that declares the module’s identity, dependencies, exports, objects, and lifecycle hooks. |
| Module object | A typed entry in the manifest’s objects map. One of nine kinds: resource_type, resource, statement, predicate, predicate_policy, template, template-call, operation, data-source. |
| Provider | A binding that maps a token to an implementation source, with a DI lifecycle. |
| Re-export | An entry in exports that surfaces an imported module’s symbols under this module’s namespace. |
| Token | A named semantic capability declaration. Modules consume tokens by listing them; runtime providers fulfill them. |
| Transform | A compile-time artifact ingestion declaration: source spec to module objects (RFC-0044). |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M40001 | Error | objects map is empty — at least one declaration is required |
M40010 | Warning | Optional module dependency could not be resolved; module installs but feature is unavailable |
M40011 | Error | Required module dependency could not be resolved (SemVer mismatch or missing module) |
M40020 | Error | templates: ref does not resolve in the module dependency closure |
M40021 | Error | Template call references a template not listed in the module’s templates: imports |
M40030 | Error | Token resolution at runtime violates capability scope |
M40040 | Error | Token declared in tokens: has no matching provider; token is required |
M40041 | Warning | Token has multiple providers; resolution order applied per RFC-0041 |
M40050 | Error | Duplicate object name within a manifest’s objects map |
M40051 | Error | Object body fails per-kind validation (forwards to per-RFC code) |
M40060 | Error | data_source config shape is not recognized by the runtime |
M40070 | Error | Hook reference does not resolve to a callable artifact in scope |
M40080 | Warning | category value is not one of the recommended set; informational only |
M40090 | Error | exports.root declared at module level — root is reserved for templates |
Dependency neighborhood
graph LR
nRFC_0040["RFC-0040"]
nRFC_0001["RFC-0001"]
nRFC_0040 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0040 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0040 --> nRFC_0007
nRFC_0036["RFC-0036"]
nRFC_0040 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0040 --> nRFC_0037
nRFC_0038["RFC-0038"]
nRFC_0040 --> nRFC_0038
nRFC_0039["RFC-0039"]
nRFC_0040 --> nRFC_0039
nRFC_0041["RFC-0041"]
nRFC_0041 --> nRFC_0040
nRFC_0042["RFC-0042"]
nRFC_0042 --> nRFC_0040
nRFC_0043["RFC-0043"]
nRFC_0043 --> nRFC_0040
nRFC_0044["RFC-0044"]
nRFC_0044 --> nRFC_0040
Invariants
- Capability scope on token resolution MUST be honored at runtime (M40030). (enforced by: runtime)
- Compile-time transforms MUST NOT execute at install or runtime. (enforced by: build-time)
- Every manifest declares apiVersion, kind, namespace, version, and metadata. (enforced by: compile-time)
- Hook artifacts MUST be invocable with install-time-only context and MUST NOT depend on runtime application state. (enforced by: runtime)
- Object names MUST be unique within a single manifest’s objects map (M40050). (enforced by: compile-time)
- Templates invoked via template-call MUST appear in the module’s templates: import list (M40021). (enforced by: compile-time)
- The compile pipeline finalizes each complete resolved manifest into a per-module envelope with its exact derived templates and required deterministic manifest hash; identical inputs yield identical compiled artifacts. (enforced by: build-time)
- The objects map MUST contain at least one entry (M40001). (enforced by: compile-time)
- Tokens declared in tokens: MUST resolve to a provider at install time unless optional is true (M40040). (enforced by: install-time)
- exports.root is reserved for templates and is invalid in module-level exports (M40090). (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — Templates declared but never imported MUST produce M40021. (proof citation:
rfc0040_b0_grounded; verification pending)
Compile Pipeline
- MUST — Artifact verification MUST capture the complete detached envelope before its first asynchronous step, reject lossy schema stripping or default insertion after JSON normalization, and reject absent, malformed, or mismatched manifestHash values after recomputing the digest.
- MUST — Compiled module input MUST contain the required manifest, templates, and manifestHash envelope. The manifest is the complete JSON-normalized resolved named map after compiler reification; its map keys and declaration names remain independently preserved.
- MUST — Compiled runtime consumption MUST reject raw or hashless artifacts instead of silently rebuilding them. Invalid or multiple compiled entries cannot select a raw-source fallback; singular loading rejects multiple artifacts and directs callers to the bulk compiled loader.
- MUST — The compiled templates map MUST exactly equal the JSON-normalized deterministic projection of the resolved manifest. Template versions use an explicit override or the top-level module version, and conversions preserve optional idempotency; duplicate derived names are rejected.
Dependencies
- MUST_NOT — A module MUST NOT call a template not declared in its templates: list. (proof citation:
rfc0040_b21_grounded; verification pending)
Hooks
- MUST — A hook artifact MUST be invocable with no required imports (idempotency-key-only context).
- MUST_NOT — Hooks MUST NOT depend on application-runtime state.
Invariants
- MUST — Every manifest declares apiVersion, kind, namespace, version, and metadata. (proof citation:
rfc0040_b13_grounded; verification pending) - MUST — Templates called via template-call MUST appear in the module’s templates: import list. (proof citation:
rfc0040_b26_grounded; verification pending) - MUST — The compile pipeline produces a deterministic manifest hash; identical inputs yield identical outputs. (proof citation:
rfc0040_b2_grounded; verification pending) - MUST — Tokens declared in tokens: MUST resolve to a provider at install time unless optional. (proof citation:
rfc0040_b28_grounded; verification pending)
Manifest Envelope
- SHOULD — The category field SHOULD be set to one of core, application, or extension.
- MUST — The objects field MUST contain at least one entry.
- MAY — The runtime MAY use category for ordering install operations and diagnostic clarity.
- MUST_NOT — The runtime MUST NOT use category to enforce access control. (proof citation:
rfc0040_b11_grounded; verification pending)
The objects Map
- MAY — Any object value MAY be a file-path string instead of an inline body.
- MUST — Object names MUST be unique within a manifest. (proof citation:
rfc0040_b15_grounded; verification pending) - MUST — Predicate paths MUST be globally unique.
- MUST — Unsupported data_source config shapes MUST produce M40060 at install time. (proof citation:
rfc0040_b6_grounded; verification pending)
Tokens and Providers
- MAY — Multiple providers MAY claim the same token; resolution follows RFC-0041 deterministic order.
- MUST — Token capability scope MUST be enforced at runtime; cross-scope resolution is forbidden. (proof citation:
rfc0040_b4_grounded; verification pending)
Transforms
- MUST_NOT — Transforms MUST NOT execute at install or runtime; they run only at compile time. (proof citation:
rfc0040_b8_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Extended by | RFC-0041 |
| Extended by | RFC-0042 |
| Extended by | RFC-0043 |
| Extended by | RFC-0044 |