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
| Term | Meaning |
|---|---|
| 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. |
| Token | A named semantic capability declaration. Modules consume tokens by listing them; runtime providers fulfill them. |
| Provider | A binding that maps a token to an implementation source, with a DI lifecycle. |
| Classifier | A named, exported semantic-contract label. Lightweight metadata for cross-module discovery. |
| Transform | A compile-time artifact ingestion declaration: source spec → module objects (RFC-0044). |
| Hook | A named lifecycle callback: preInstall, postInstall, preUninstall (RFC-0041 §hooks). |
| Re-export | An 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:
| Category | Meaning |
|---|---|
core | Platform/bootstrap modules — the runtime depends on these to function. |
application | Domain modules — author-written, business-logic-bearing. |
extension | Third-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
| Scope | Resolvable from |
|---|---|
root | Authenticated system or explicitly root-granted contexts; never anonymous by default |
core | Platform-level contexts only |
app | Application contexts (post-authentication) |
admin | Admin contexts (elevated principal) |
webhook | Webhook contexts (one-shot, signed) |
public | Explicitly 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>
| Lifecycle | Instances |
|---|---|
singleton | One per runtime, created at boot |
scoped | One per request/session/transaction context |
transient | One 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:
| Kind | Discriminant | Defined in |
|---|---|---|
| Resource type | type: resource_type | §9.1 |
| Resource | type: resource | §9.2 |
| Statement | type: statement | §9.3 |
| Predicate | type: predicate | §9.4 |
| Predicate policy | type: predicate_policy | RFC-0042 §3 |
| Template | type: template | RFC-0039 §3 (inline) |
| Template call | type: <module-alias>.<template-name> | RFC-0039 §4.3 |
| Operation | type: operation | RFC-0043 §3 |
| Data source | type: 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 field | Meaning |
|---|---|
manifest | The complete, detached, JSON-normalized resolved manifest after all resolution, permission expansion, and compiler reification. |
templates | The exact deterministic template map derived from that manifest. |
manifestHash | The 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
- Every manifest declares
apiVersion,kind,namespace,version, andmetadata(§3.1). objectsMUST contain at least one entry (M40001).- Object names MUST be unique within a manifest (§9, M40050).
- Predicate paths MUST be globally unique (RFC-0036 §4.3 inv 2; M36020).
- Tokens declared in
tokens:MUST resolve to a provider at install time, unlessoptional: true(§5.2; M40040). - Templates called via
template-calldiscriminant MUST appear in the module’stemplates:import list (§4.2; M40021). - Capability scope on token resolution MUST be honored at runtime (§5.1.1; M40030).
- Hook artifacts MUST be invocable with install-time-only context (no runtime state) (§7).
- Compile-time
transformsMUST NOT execute at install or runtime (§8). - 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 file | This RFC |
|---|---|
manifest.ts (graphModuleManifestSchema) | §3 |
imports.ts / common-schemas/document.ts moduleImports* | §4.1 |
objects/*.ts (per-object schemas) | §9 |
objects/operation.ts | RFC-0043 §3 |
objects/predicate-policy.ts | RFC-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 renamedmodules(this RFC §4.1). The legacydependenciesfield is no longer accepted. - Legacy
data-sourceschema 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.