gnomonlearn
Docs/Graph/RFC-0040

RFC-0040 · Graph Module Manifest

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

A graph module is the unit of authoring, distribution, and installation in Gnomon. It packages together: the resource types it defines, the predicates it claims, the predicate policies it asserts, the templates it exports, the operations it exposes, the runtime services it consumes (tokens) and provides (providers), the build-time data ingestion pipelines it runs (transforms), and the install-time hooks it registers.

This RFC is the bridge document between the legacy YAML module manifest at /Volumes/Workspace/savvi-studio-full/modules/src/*/module.gnm and the Gnomon language framework. Every legacy field is given a normative home — either as part of this manifest, as a reference to another RFC, or as deliberately removed.

This RFC extends RFC-0001 (module authoring format) with the graph-specific declarations needed to make a module a complete graph contribution. It does NOT redefine RFC-0001’s general envelope (filename rules, declaration classes, Surface vs. Operations vs. Migrations classes); it specifies what additional structure a graph module carries.


2. Definitions

TermMeaning
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.
TokenA named semantic capability declaration. Modules consume tokens by listing them; runtime providers fulfill them.
ProviderA binding that maps a token to an implementation source, with a DI lifecycle.
ClassifierA named, exported semantic-contract label. Lightweight metadata for cross-module discovery.
TransformA compile-time artifact ingestion declaration: source spec → module objects (RFC-0044).
HookA named lifecycle callback: preInstall, postInstall, preUninstall (RFC-0041 §hooks).
Re-exportAn entry in exports that surfaces an imported module’s symbols under this module’s namespace.

3. Manifest Envelope

Every graph module declares a single manifest at the module root, named module.gnm:

apiVersion: gnomon/v1
kind:       Module
namespace:  <ltree-path>          // unique within the runtime
version:    <semver>
metadata:
  description: <text>
  annotations: <map>
  tags:        <list>

category:    core | application | extension      // optional
classifiers: [<DnsLabel>, ...]                   // optional
author:      <text>                              // optional
license:     <SPDX-id>                           // optional

modules:     <module-import-list>                // dependencies
templates:   <template-ref-list>                 // template capabilities consumed
tokens:      <token-list>                        // capabilities consumed
providers:   <provider-list>                     // implementations contributed
exports:     <exports-map>
defaultConfig: <config-block>
hooks:       <hooks-block>
transforms:  <transforms-block>                  // compile-time ingestion (RFC-0044)
objects:     <objects-map>

3.1 Required fields

apiVersion, kind, namespace, version, and metadata are required at every layer. The objects field is required and MUST contain at least one entry (M40001).

3.2 Categories

The category field is informational and SHOULD be set to one of:

CategoryMeaning
corePlatform/bootstrap modules — the runtime depends on these to function.
applicationDomain modules — author-written, business-logic-bearing.
extensionThird-party or integration modules — consumes core/application surface.

The runtime MAY use category for ordering install operations and for diagnostic clarity. It MUST NOT use category to enforce access control.

3.3 Classifiers

classifiers is an array of DnsLabel strings. They are exported semantic-contract names — opaque to the runtime, queryable by tooling. The Knowledge Index (RFC-0010 §9) MAY index modules by classifier for cross-module discovery.

Classifiers do NOT affect install order, dependency resolution, or runtime behavior. They are documentation aids.


4. Dependencies

4.1 modules

The modules: field declares install-order dependencies. Two equivalent forms are supported:

List form:

modules:
  - core
  - { name: core.identity, as: identity, version: "^1.0", optional: false }
  - core.template

Map form:

modules:
  core:
    name: core
  identity:
    name: core.identity
    version: "^1.0"
  templates:
    name: core.template

The as: field assigns a local alias used in template-call resolution (e.g., identity.user-identity). When omitted, the module’s last namespace segment is used as the alias.

The version: field is a SemVer range; resolution rules are specified in RFC-0014.

The optional: field, when true, means the module’s absence does not block install. Optional dependencies that resolve are linked normally; optional dependencies that fail to resolve produce M40010 (warning) instead of an error.

4.2 templates

templates: is a list of qualified template references this module consumes from imported modules:

templates:
  - module-definition       # from core
  - register-template-definition
  - user-identity           # from core.identity

Names are resolved against the modules: dependency closure. Unresolved template refs produce M40020 at compile time.

This list is informational + access-control:

  • Informational — declares the surface the module relies on, for cross-module reasoning and migration impact analysis.
  • Access-control — a module MUST NOT call a template it has not declared in templates:. Calling an undeclared template produces M40021.

4.3 Re-exports

Modules MAY re-export imported modules’ templates via exports.modules:

exports:
  modules:
    - core
    - identity
    - templates

Re-exported modules become accessible to consumers of this module under their original alias. This is the legacy “aggregate module” pattern (e.g., core.platform).


5. Tokens and Providers (DI Surface)

Tokens and providers form the dependency-injection contract for runtime services.

5.1 Tokens

A token is a named semantic capability:

tokens:
  authentication-service:
    ref:         <object-path>           # path to the symbol being declared
    scope:       root | core | app | admin | webhook | public
    optional:    boolean                 # default false
    description: <text>

The two forms are supported:

Compact (array): tokens: [authentication-service, jwt-service] — declares tokens with default scope and required.

Detailed (map): as shown above — declares each token with explicit scope and optionality.

5.1.1 Capability scopes

ScopeResolvable from
rootAuthenticated system or explicitly root-granted contexts; never anonymous by default
corePlatform-level contexts only
appApplication contexts (post-authentication)
adminAdmin contexts (elevated principal)
webhookWebhook contexts (one-shot, signed)
publicExplicitly published read-only, non-tenant operations for anonymous sessions (RFC-0048 §3.5)

The kernel-owned public scope MUST NOT be attached to a mutating or tenant-scoped operation (RFC-0048 §3.5). A root token is not implicitly available to an anonymous session; the session capability filter applies before token resolution.

Scope is enforced by the runtime: a token’s scope: admin cannot be resolved from an app-scoped operation handler. Unauthorized resolution produces M40030 at runtime.

5.2 Providers

A provider declares an implementation that fulfills a token:

providers:
  authentication-service:
    token:       authentication-service
    from:        <module-namespace>?         # optional source module
    lifecycle:   singleton | scoped | transient
    optional:    boolean
    description: <text>
LifecycleInstances
singletonOne per runtime, created at boot
scopedOne per request/session/transaction context
transientOne per resolution (no caching)

Multiple providers MAY claim the same token; resolution order is RFC-0041 §provider resolution (deterministic by manifest order, last-wins for duplicates with explicit override marker).

A token referenced in tokens: but not bound to any provider produces M40040 at install time, unless optional: true.


6. Default Configuration

Module-level configuration defaults:

defaultConfig:
  enableFeatures:           [<feature>, ...]     # optional list of enabled feature flags
  settings:                 <map>                 # arbitrary configuration
  skipOptionalDependencies: boolean               # default false
  forceReinstall:           boolean               # default false
  validateSchema:           boolean               # default true

enableFeatures and settings are surfaced through the runtime’s configuration service (RFC-0046) and are queryable via services.config.get(...).

skipOptionalDependencies, forceReinstall, and validateSchema are install-time flags consumed by RFC-0041.

The full configuration layering (defaults → environment → secrets) is defined in RFC-0046.


7. Hooks

Lifecycle hooks point to operations (or templates) that run at specific install phases:

hooks:
  preInstall:    <object-name | qualified-template-name>
  postInstall:   <object-name | qualified-template-name>
  preUninstall:  <object-name | qualified-template-name>

All three are optional. Each names a callable artifact in scope (a module object or an imported template). The artifact is invoked by the install engine (RFC-0041 §hooks) at the appropriate phase, within the install transaction.

A hook artifact MUST be invocable with no required imports (idempotency-key-only context). Hooks MUST NOT depend on application-runtime state; they execute against a fresh transaction with the install context.


8. Transforms

The transforms: block declares compile-time artifact ingestion: external spec files (JSON-LD, OpenAPI, JSON-Schema) are parsed at build time and emitted as module objects. The full pipeline is specified in RFC-0044.

transforms:
  dsi-api:
    source:  ./apis/dsi.json
    parser:  jsonld | openapi | json-schema | auto
    output:  ./generated/dsi
    emit:    ir | module-objects | both
    profile: <map>

Transforms run before module resolution. Generated module objects participate in normal validation and orphan-file checks. Transforms MUST NOT execute at install or runtime.

This use of transforms is distinct from the runtime transform declaration in RFC-0008 §6.32 (data migration). The two share a name only; the contexts disambiguate them.


9. The objects Map

The objects map is the heart of the manifest. Each key is the local name of a declaration; each value is a typed object body. The nine recognized object kinds are:

KindDiscriminantDefined in
Resource typetype: resource_type§9.1
Resourcetype: resource§9.2
Statementtype: statement§9.3
Predicatetype: predicate§9.4
Predicate policytype: predicate_policyRFC-0042 §3
Templatetype: templateRFC-0039 §3 (inline)
Template calltype: <module-alias>.<template-name>RFC-0039 §4.3
Operationtype: operationRFC-0043 §3
Data sourcetype: data_source§9.5

Object names MUST be unique within the manifest (M40050).

9.1 resource_type

Declares a resource type that this module owns. Materializes a registered Kind in the graph at install time.

<name>:
  type: resource_type
  with:
    description: <text>
    supertype:   <CURIE>?                # SDO/RDF alignment, e.g. schema:Person
    fields:      <field-schema-map>?     # optional structured field schema
    status:      <status-state-machine>? # optional state machine

supertype is the RFC-0006 §6 / RFC-0042 §sameAs SDO grounding hook. Informational at runtime; consumed by tooling and potentially by federation.

9.2 resource

Declares a concrete Resource instance to create at install:

<name>:
  type: resource
  namespace:    <ltree-path>
  external_id:  <expression>?
  data:         <map | expression>?

The shape mirrors RFC-0036 §4.1. Resources declared at the module level are typically configuration anchors (organizations, default workspaces, seed users).

9.3 statement

Declares a Statement to create at install:

<name>:
  type: statement
  subject:    <expression>
  predicate:  <ltree-path | expression>
  object:     <expression>
  data:       <map>?
  for_each:   <expression>?
  valid_from: <expression>?
  valid_to:   <expression>?

Same shape as RFC-0036 §4.2 / RFC-0039 §4.2.

9.4 predicate

Declares a Predicate this module owns:

<name>:
  type: predicate
  path:        <ltree-path>
  sameAs:      <CURIE>?            # optional ontology alignment
  description: <text>?

The path MUST be unique globally (RFC-0036 §4.3 invariant 2).

9.5 data_source

Declares an install-time data ingestion source. The full schema is reserved for future expansion; the minimal current surface is:

<name>:
  type:   data_source
  config: <map>          # implementation-defined

Implementations MAY support data_source only when their installer recognizes the config shape; unsupported sources MUST produce M40060 at install time.

9.6 File-path object references

Any object value MAY be a file-path string instead of an inline body:

objects:
  user-identity: ./templates/user-identity.gnm
  resource-policy: ./policies/default.gnm

The compiler resolves the path relative to the module directory and parses the file as a single object document. This is the legacy convention preserved for ergonomics; large templates and policies typically use file-path form.


10. Exports

The exports: map declares the module’s public API surface:

exports:
  <export-name>:
    as:   template | resource | value | module
    from: <object-name | module-name>

Exports of as: template make a template importable by consumers via templates:. Exports of as: module re-export an imported module (§4.3).

exports.root is reserved for templates (RFC-0039 §3.2) and is invalid in module-level exports.

UI feature exports (exports.uiFeatures) are an extension to this section reserved for the UI surface RFC suite; this RFC does not specify their contract.


11. Compile Pipeline

The full compile pipeline for a module is:

1. Run `transforms` (build-time ingestion)              ← RFC-0044
2. Resolve `modules:` dependency closure                ← RFC-0014, RFC-0041
3. Load file-path-referenced objects                    ← §9.6
4. Validate manifest envelope (this RFC)
5. Validate `objects` map (per-kind validators)
6. Resolve template-call types against `modules` aliases ← §4.1
7. Expand `permissions:` shorthand on templates         ← RFC-0042
8. Finalize resolved definitions and manifest hash      ← RFC-0041 §7.3
9. Emit per-module compiled envelope                    ← §11.1

The pipeline runs at build time. The runtime consumes the compiled bundle and never re-runs the pipeline.

11.1 Per-module compiled artifact

The pipeline emits one CompiledGraphModuleBundle per module. This Graph artifact is distinct from the larger Gnomon/root bundle defined by RFC-0002. The existing Graph module model’s Zod schema owns its serialized form:

Required fieldMeaning
manifestThe complete, detached, JSON-normalized resolved manifest after all resolution, permission expansion, and compiler reification.
templatesThe exact deterministic template map derived from that manifest.
manifestHashThe raw 64-character lowercase hexadecimal SHA-256 of the manifest’s canonical JSON (RFC-0041 §7.3).

The digest belongs to the envelope, outside its own manifest hash domain. The snapshot retains every admitted resolved-manifest field, including annotations; only the hash input excludes top-level metadata.annotations. JSON normalization converts bigint values to decimal strings and applies ordinary JSON serialization and parsing. Schema validation rejects any snapshot that would require field stripping or default insertion. A compiled objects section is a resolved map; raw authoring lists and file references are not compiled artifacts. Its map keys and stored declaration name fields are preserved independently, including synthetic permission keys; validation does not rename either to match the other.

Template derivation uses an inline template’s explicit version, or the module’s top-level version when it is absent, never metadata.version. It retains the inline definition’s description, imports, exports, objects, and optional idempotency. Converting a full Template document to an inline declaration also preserves that existing idempotency behavior. Duplicate derived template names are rejected, and the envelope’s template map must exactly equal this derivation after JSON normalization. A separately retrieved or latest template map cannot replace the captured map.

Finalization captures the complete resolved manifest before asynchronous digest computation. Artifact verification captures the complete detached envelope before its first asynchronous step, checks the model and template-map constraints, and recomputes the digest. Missing, malformed, or mismatched manifestHash values are rejected; validation cannot substitute a fresh digest for a supplied one. The hash establishes self-consistency, not compiler origin, a signature, authorization, or proof that the compile pipeline ran.

Serialized JSON/JavaScript artifacts and generated import barrels carry this same envelope. Hashless artifacts and old hashless cache entries are rejected rather than upgraded silently. Explicit source-authoring compilation and materialization utilities may produce a new compiled artifact; they are not a raw-manifest fallback in the engine, provider, or compiled loader. A singular loader rejects multiple compiled artifacts and directs the caller to the bulk compiled loader; the presence of invalid or multiple compiled artifacts does not select a source-manifest fallback.


12. Invariants

  1. Every manifest declares apiVersion, kind, namespace, version, and metadata (§3.1).
  2. objects MUST contain at least one entry (M40001).
  3. Object names MUST be unique within a manifest (§9, M40050).
  4. Predicate paths MUST be globally unique (RFC-0036 §4.3 inv 2; M36020).
  5. Tokens declared in tokens: MUST resolve to a provider at install time, unless optional: true (§5.2; M40040).
  6. Templates called via template-call discriminant MUST appear in the module’s templates: import list (§4.2; M40021).
  7. Capability scope on token resolution MUST be honored at runtime (§5.1.1; M40030).
  8. Hook artifacts MUST be invocable with install-time-only context (no runtime state) (§7).
  9. Compile-time transforms MUST NOT execute at install or runtime (§8).
  10. The compile pipeline produces a deterministic manifest hash; identical inputs produce identical outputs (§11).

13. Compatibility and Migration

13.1 From legacy YAML manifests

This RFC is a faithful codification of the legacy schema at /Volumes/Workspace/savvi-studio-full/packages/graph-module-model/model/:

Legacy fileThis RFC
manifest.ts (graphModuleManifestSchema)§3
imports.ts / common-schemas/document.ts moduleImports*§4.1
objects/*.ts (per-object schemas)§9
objects/operation.tsRFC-0043 §3
objects/predicate-policy.tsRFC-0042 §3
objects/template.ts (inline template)RFC-0039 §3 + §9 mapping
exports.ts§10
config.ts (graphModuleConfigSchema)§6
hooks.ts§7
transforms.ts§8 + RFC-0044
manifest.ts (tokens, providers)§5

The mapping is direct. Existing module.gnm files in /Volumes/Workspace/savvi-studio-full/modules/src/* are conformant after a YAML → Gnomon-syntax migration; the field semantics are preserved.

13.2 Naming changes

  • Legacy dependencies (flat array) is renamed modules (this RFC §4.1). The legacy dependencies field is no longer accepted.
  • Legacy data-source schema is reserved; the legacy code marks it as TODO. Implementations MAY add a richer schema as a future minor revision.

13.3 Behavior changes

  • Templates declared but never imported MUST produce M40021. The legacy code is permissive.
  • templates: imports are now access-controlled. Calls to undeclared templates fail at compile time.
  • Capability scopes on tokens are now enforced at runtime (§5.1.1). Legacy code declares scopes but enforcement is partial.

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.