gnomonlearn
Docs/RFC-0040/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
ClassifierA named, exported semantic-contract label. Lightweight metadata for cross-module discovery.
HookA named lifecycle callback: preInstall, postInstall, preUninstall.
ModuleA namespaced, versioned bundle of declarations that contributes to the graph. Identified by (namespace, version).
Module manifestThe top-level document (module.gnm) that declares the module’s identity, dependencies, exports, objects, and lifecycle hooks.
Module objectA 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.
ProviderA binding that maps a token to an implementation source, with a DI lifecycle.
Re-exportAn entry in exports that surfaces an imported module’s symbols under this module’s namespace.
TokenA named semantic capability declaration. Modules consume tokens by listing them; runtime providers fulfill them.
TransformA compile-time artifact ingestion declaration: source spec to module objects (RFC-0044).

Diagnostics

CodeSeverityDescription
M40001Errorobjects map is empty — at least one declaration is required
M40010WarningOptional module dependency could not be resolved; module installs but feature is unavailable
M40011ErrorRequired module dependency could not be resolved (SemVer mismatch or missing module)
M40020Errortemplates: ref does not resolve in the module dependency closure
M40021ErrorTemplate call references a template not listed in the module’s templates: imports
M40030ErrorToken resolution at runtime violates capability scope
M40040ErrorToken declared in tokens: has no matching provider; token is required
M40041WarningToken has multiple providers; resolution order applied per RFC-0041
M40050ErrorDuplicate object name within a manifest’s objects map
M40051ErrorObject body fails per-kind validation (forwards to per-RFC code)
M40060Errordata_source config shape is not recognized by the runtime
M40070ErrorHook reference does not resolve to a callable artifact in scope
M40080Warningcategory value is not one of the recommended set; informational only
M40090Errorexports.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

  1. Capability scope on token resolution MUST be honored at runtime (M40030). (enforced by: runtime)
  2. Compile-time transforms MUST NOT execute at install or runtime. (enforced by: build-time)
  3. Every manifest declares apiVersion, kind, namespace, version, and metadata. (enforced by: compile-time)
  4. Hook artifacts MUST be invocable with install-time-only context and MUST NOT depend on runtime application state. (enforced by: runtime)
  5. Object names MUST be unique within a single manifest’s objects map (M40050). (enforced by: compile-time)
  6. Templates invoked via template-call MUST appear in the module’s templates: import list (M40021). (enforced by: compile-time)
  7. 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)
  8. The objects map MUST contain at least one entry (M40001). (enforced by: compile-time)
  9. Tokens declared in tokens: MUST resolve to a provider at install time unless optional is true (M40040). (enforced by: install-time)
  10. 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

  1. MUST — Templates declared but never imported MUST produce M40021. (proof citation: rfc0040_b0_grounded; verification pending)

Compile Pipeline

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. MUST_NOT — A module MUST NOT call a template not declared in its templates: list. (proof citation: rfc0040_b21_grounded; verification pending)

Hooks

  1. MUST — A hook artifact MUST be invocable with no required imports (idempotency-key-only context).
  2. MUST_NOT — Hooks MUST NOT depend on application-runtime state.

Invariants

  1. MUST — Every manifest declares apiVersion, kind, namespace, version, and metadata. (proof citation: rfc0040_b13_grounded; verification pending)
  2. MUST — Templates called via template-call MUST appear in the module’s templates: import list. (proof citation: rfc0040_b26_grounded; verification pending)
  3. MUST — The compile pipeline produces a deterministic manifest hash; identical inputs yield identical outputs. (proof citation: rfc0040_b2_grounded; verification pending)
  4. MUST — Tokens declared in tokens: MUST resolve to a provider at install time unless optional. (proof citation: rfc0040_b28_grounded; verification pending)

Manifest Envelope

  1. SHOULD — The category field SHOULD be set to one of core, application, or extension.
  2. MUST — The objects field MUST contain at least one entry.
  3. MAY — The runtime MAY use category for ordering install operations and diagnostic clarity.
  4. MUST_NOT — The runtime MUST NOT use category to enforce access control. (proof citation: rfc0040_b11_grounded; verification pending)

The objects Map

  1. MAY — Any object value MAY be a file-path string instead of an inline body.
  2. MUST — Object names MUST be unique within a manifest. (proof citation: rfc0040_b15_grounded; verification pending)
  3. MUST — Predicate paths MUST be globally unique.
  4. MUST — Unsupported data_source config shapes MUST produce M40060 at install time. (proof citation: rfc0040_b6_grounded; verification pending)

Tokens and Providers

  1. MAY — Multiple providers MAY claim the same token; resolution follows RFC-0041 deterministic order.
  2. MUST — Token capability scope MUST be enforced at runtime; cross-scope resolution is forbidden. (proof citation: rfc0040_b4_grounded; verification pending)

Transforms

  1. 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

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Extended byRFC-0041
Extended byRFC-0042
Extended byRFC-0043
Extended byRFC-0044