RFC-0001 · Module Authoring Format
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 →
Status: Draft Owners: Module Platform, DX
1. Scope
Defines the module.gnm manifest format — the single required file that declares a module’s identity, namespace, version, type, and dependencies within the Gnomon authoring system.
module.gnm is written in the same .gnm DSL syntax as all other Gnomon source files (RFC-0008). It is NOT a YAML file. Its content is a single module declaration that names the module’s fully-qualified namespace and configures module-level metadata.
Under the folder convention (RFC-0008 §7), source files within a concept folder are named by declaration class (e.g., schema.gnm, actions.gnm, queries.gnm) and are auto-discovered by the compiler. In this mode, module.gnm contains only the module identity block — FQN, version, type, and imports — with no explicit file listings required.
Under the explicit listing mode (for non-standard layouts), the manifest may additionally contain objects [], operations [], and agents [] lists that enumerate source files explicitly. Explicit listing overrides auto-discovery for the listed section. New modules SHOULD use the folder convention; explicit listing is reserved for modules with non-standard or pre-existing layouts.
The semantic type model governing declarations in source files is defined in RFC-0006. This RFC governs only the module.gnm manifest itself.
2. Goals
- Human-authorable format with deterministic compile semantics
- Minimal ambiguity in field typing and composition declarations
- Stable diagnostics for invalid declarations
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.
3. Invariants
- A module source MUST declare
namespaceandversionand MUST declare a module type. - Declarations MUST be parseable without runtime context.
- Cross-reference identifiers MUST be resolvable during compile.
- Structured objects MUST be preferred over delimiter-encoded fields.
- Aspects and facets MUST be present for UI-oriented modules; MAY be omitted for backend-only modules.
4. Authoring Contract
RFC-0001 and RFC-0008 Boundary
RFC-0001 and RFC-0008 govern different surfaces of the same authoring layer and MUST be read together:
module.gnm(this RFC) — a single.gnmfile at the root of every module directory. Uses the same.gnmDSL syntax as all other Gnomon source files. Contains a singlemoduledeclaration that names the module’s fully-qualified namespace and references all other source files in the module..gnmdeclaration files (RFC-0008) — the.gnmfiles that contain entity, action, policy, flow, enum, agent, and other declarations. Their syntax is defined entirely in RFC-0008. They are referenced frommodule.gnmbut MUST NOT redefine themodulemanifest structure.
module.gnm does NOT contain inline entity or action declarations. It is a manifest: it declares module identity and references files that contain declarations. A compiler MUST parse module.gnm first and resolve all referenced files before beginning semantic analysis.
Why module.gnm as the filename: The filename is a reserved convention for tooling discovery, parallel to project.gnm at the project level. The module’s canonical graph identity is the FQN declared inside the file — module org.benefits.plans { ... } — not the filename. Tooling finds the manifest by looking for module.gnm at the module root; the graph persistence layer identifies the module by FQN.
Canonical file layout (folder convention):
Under the folder convention (RFC-0008 §7), each logical concept lives in its own folder. Files within that folder are named by declaration class — the compiler discovers them automatically without explicit listing in module.gnm.
benefits-demo/modules/plans/
module.gnm ← module manifest (this RFC): FQN, version, type, imports only
schema.gnm ← entity Plan, entity Enrollment, flow PlanStatus, flow EnrollmentStatus
actions.gnm ← action submitEnrollment, action draftRecommendation
queries.gnm ← query getActivePlans, query getPlanById
agents.gnm ← agent RecommendationEngine (if present)
module.gnm in this layout contains no file listings:
module org.benefits.plans {
version: "1.2.3"
type: hybrid
imports {
gnomon.core: "^1.0.0"
org.hr.employees: "^2.0.0"
}
}
Module Declaration Syntax
module.gnm MUST contain exactly one top-level module declaration. No other top-level declarations are permitted in this file; their presence MUST produce error M01060.
Folder-convention form (preferred — no file listings):
module org.benefits.plans {
version: "1.2.3"
type: hybrid // backend-only | ui-only | hybrid
imports {
gnomon.core: "^1.0.0"
org.hr.employees: "^2.0.0"
org.compliance: "~1.4.0"
org.vocab.icd: "1.2.7" // exact pin
}
}
Explicit-listing form (non-standard or legacy layouts only):
module org.benefits.plans {
version: "1.2.3"
type: hybrid
imports {
gnomon.core: "^1.0.0"
org.hr.employees: "^2.0.0"
}
objects [
"entities/plan.gnm"
"entities/enrollment.gnm"
]
operations [
"operations/submit.gnm"
"operations/queries.gnm"
{ path: "operations/grant_role.gnm", rollbackCheckpoint: true }
{ path: "operations/assign_manager.gnm", rollbackDependsOn: ["operations/grant_role.gnm"] }
]
agents [
"agents/recommendation.gnm"
]
}
When objects, operations, or agents are present, they override auto-discovery for that section. Partial presence of a list means the listed section is explicit and the absent sections are auto-discovered. If a section list is present but contains no entries (e.g., objects [] with no paths), the compiler MUST emit warning M01065 (“explicitly listed section is empty — omit the list to use auto-discovery”).
The module’s FQN (org.benefits.plans in the example) is the canonical identity of this module in the graph persistence model. All declarations within files listed in objects, operations, and agents inherit this namespace as their FQN prefix. An entity Plan declared in a file under objects has FQN org.benefits.plans.Plan. An action submitEnrollment has FQN org.benefits.plans.submitEnrollment.
Module Type
Every module MUST declare one of three types:
backend-only— no UI composition (e.g., auth policies, data API models).compositionandviewdeclarations in referenced files MUST produce error M01002.ui-only— UI composition required. Referenced files MUST declare at least onevieworroutedeclaration; absence MUST produce warning M01003.hybrid— both backend structures and UI composition.
type is REQUIRED. Absence MUST produce error M01001.
Imports Block
imports { } declares upstream module dependencies. Import syntax MUST conform to RFC-0014 §3.
Field semantics:
- Each key is a module FQN (
NAME { "." NAME }per RFC-0008 §8.1). MUST be lowercase dot-separated. - Each value is a semver constraint string:
"^MAJOR.MINOR.PATCH"(compatible),"~MAJOR.MINOR.PATCH"(patch-range), or"MAJOR.MINOR.PATCH"(exact pin). Constraint syntax and resolution rules are normatively defined in RFC-0014 §3-4. - A module MUST declare a dependency on any module whose symbols it references. Undeclared dependency references MUST produce error M01050.
- Circular dependencies MUST be rejected with error M01051.
- The resolved version for each import MUST be recorded in
module.lockper RFC-0014 §5. imports { }MAY be empty or omitted for modules with no upstream dependencies.
Objects List
objects [ ] is optional under the folder convention. When omitted, the compiler auto-discovers schema.gnm and mutations.gnm (Schema class; holds mutation declarations) in the concept folder. Similarly, the compiler auto-discovers relations.gnm (Relations class; holds relation declarations) from the concept folder when no explicit listing overrides are present.
When present (explicit listing mode), objects [ ] lists paths (relative to the module root) of .gnm files containing this module’s type declarations: entity, facet, enum, flow, and claim declarations (RFC-0006 §4, RFC-0008 §8.4–§8.17).
Field semantics (explicit listing mode):
- Each entry MUST be a quoted string path resolving to an existing
.gnmfile. - The referenced file MUST contain at least one declaration of kind
entity,facet,enum,flow, orclaim. Files that contain onlyaction,agent,policy,test,migration, orbindingdeclarations MUST NOT be listed underobjects— place them inoperationsoragentsinstead. Misplaced declarations MUST produce warning M01052. - Files are compiled in list order. Forward references within the same section are permitted; the compiler resolves them in a second pass.
objectsMAY be empty or omitted for modules that declare no types of their own (e.g., a module that only imports and re-exports types from other modules).
Operations List
operations [ ] is optional under the folder convention. When omitted, the compiler auto-discovers actions.gnm, queries.gnm, events.gnm, procedures.gnm, tasks.gnm, integrations.gnm, clients.gnm, saga.gnm, views.gnm, api.gnm, and serve.gnm in the concept folder.
When present (explicit listing mode), operations [ ] lists paths of .gnm files containing this module’s procedural declarations: action, query, and view declarations.
Each entry is either a plain quoted path string or an object with a path key and optional rollback hints:
operations [
"operations/queries.gnm" // plain path
{ path: "operations/grant_role.gnm", rollbackCheckpoint: true } // with hint
{ path: "operations/assign_manager.gnm",
rollbackDependsOn: ["operations/grant_role.gnm"] } // with dependency
]
Field semantics:
rollbackCheckpoint: truemarks this file’s operations as a rollback boundary. The install plan generator (RFC-0005) MUST treat this as a checkpoint when building rollback sequences.rollbackDependsOnlists paths whose operations MUST be rolled back before this file’s operations. Referenced paths MUST appear in the sameoperationslist; forward references are not permitted. Missing reference MUST produce error M01055.- Q2 behavior: compilers MAY preserve rollback hints without mandatory validation. Phase 1 behavior: install-plan generators MUST validate hint consistency against dependency graphs.
operationsMAY be empty or omitted for modules that declare no actions or queries.
Agents List
agents [ ] is optional under the folder convention. When omitted, the compiler auto-discovers agents.gnm in the concept folder.
When present (explicit listing mode), agents [ ] lists paths of .gnm files containing this module’s agent declarations (RFC-0009).
Field semantics:
- Each entry MUST be a quoted string path resolving to a
.gnmfile containing at least oneagentdeclaration (RFC-0009 §3). - Every
agentdeclaration MUST reference amodelthat resolves to a declaration in the module’smodel_declarations(RFC-0002 §4) or an imported model. Unresolved model references MUST produce error M01053. agentsis OPTIONAL. A module with no AI actors MAY omit this section entirely.- Any
actiondeclaration in anoperationsfile that names an AI actor role MUST have a correspondingagentdeclaration resolvable from theagentslist or from imports. Unresolvable AI actor roles MUST produce error M01054.
Tests
tests.gnm is optional under the folder convention. When no explicit listing covers test declarations, the compiler auto-discovers tests.gnm from the concept folder. tests.gnm holds test declarations (Tests class). There is no tests [ ] list in the manifest; test files are always discovered by convention unless the concept folder contains no tests.gnm.
Migrations
migrations.gnm is optional under the folder convention. When no explicit listing covers migration declarations, the compiler auto-discovers migrations.gnm from the concept folder. migrations.gnm holds migration declarations. There is no migrations [ ] list in the manifest; migration files are always discovered by convention unless the concept folder contains no migrations.gnm.
Individual Declaration Syntax
The syntax for all declarations that live inside files referenced by objects, operations, and agents — including entity, action, policy, flow, enum, facet, claim, view, query, invariant, agent, test, migration, and binding — is defined entirely in RFC-0008 §8. RFC-0001 does not redefine or duplicate those syntaxes. See:
- Entity, facet, relation: RFC-0008 §8.4–§8.6
- Action and query: RFC-0008 §8.7, §8.15
- Flow and claim: RFC-0008 §8.8, §8.11
- Policy and invariant: RFC-0008 §8.9, §8.12
- View and composition: RFC-0008 §8.13, §8.14
- Enum: RFC-0008 §8.17
- Agent: RFC-0008 §8.16
- Test: RFC-0013 §3
- Migration: RFC-0016 §3
- Binding: RFC-0015 §3
4.1 File Taxonomy and Declaration Classes (Normative)
Every gnomon declaration kind belongs to exactly one declaration class. This classification governs which declarations may appear together in a single file.
| Class | Declaration kinds |
|---|---|
| Schema | entity, type, variant, flow, invariant, facet, mutation, compute, claim, extend, config, config-set |
| Operations | action, query, task, integration, actuator, event, procedure, client, workflow, saga, api, serve |
| Relations | relation |
| Governance | policy, agent, compose |
| Surface | app, view |
| Tests | test |
File Class Rule
A file MUST contain declarations of exactly one declaration class. Mixing declarations from different classes is error M08701 (upgraded from warning to error in this revision).
Co-location Exception
A Schema class file MAY co-locate type, variant, flow, and invariant declarations that are exclusively consumed by the primary entity or facet declared in that same file. This avoids unnecessary file proliferation for private supporting declarations.
If a co-located supporting declaration (type, variant, flow, or invariant) is referenced from any file other than the one it is declared in, it MUST be extracted to its own file. The compiler detects external consumers automatically and produces error M08702 when a co-located supporting declaration has at least one external reference.
File Naming Rule
Under the folder convention (RFC-0008 §7, RECOMMENDED), files are named by declaration class using the predefined names below. The compiler discovers these files automatically; no explicit listing in module.gnm is required.
| File name | Declaration class / kinds permitted |
|---|---|
module.gnm | Module manifest — REQUIRED. Not a declaration source file. This file is NOT subject to the “silently ignored if absent” rule; its absence is a compile error (M01066). |
schema.gnm | entity, type, variant, flow, invariant, facet, mutation, compute, claim, extend, config |
actions.gnm | action |
queries.gnm | query |
mutations.gnm | mutation |
events.gnm | event |
procedures.gnm | procedure |
tasks.gnm | task |
integrations.gnm | integration |
clients.gnm | client |
saga.gnm | saga |
relations.gnm | relation |
agents.gnm | agent |
policies.gnm | policy, compose |
views.gnm | app, view |
api.gnm | api |
serve.gnm | serve |
tests.gnm | test |
migrations.gnm | migration |
config.<env>.gnm is a runtime override file at the configured path,
outside this module folder convention. It contains only Schema-class
config-set value bindings (RFC-0046 §3.2); the compiler MUST NOT discover
it as module source or admit imports and other declarations there.
Governance class note: The Governance class is the only class whose predefined file naming subdivides the class into two files: agents.gnm holds agent declarations and policies.gnm holds policy and compose declarations. This subdivision is by convention; both files belong to the Governance class. This is not a violation of the one-class-per-file rule, which applies at the class level, not the sub-declaration level.
A concept folder MUST NOT define more than one file per predefined name. Files that are empty or absent are silently ignored. The compiler MUST warn (M07902) if a file is present in the folder but does not match any predefined name and no explicit listing overrides are present.
Under explicit listing mode, files may use arbitrary kebab-case names. For Schema files, the filename SHOULD match the primary entity or facet name (e.g., entity NextDollar → next-dollar.gnm). For Operations files, the filename SHOULD describe the operation group (e.g., proposal-actions.gnm).
The following generic filenames are error M08703 in explicit listing mode and MUST NOT be used:
common.gnmtypes.gnmutils.gnmmisc.gnmoperations.gnmhelpers.gnm
(These names are not reserved in folder-convention mode because folder-convention files use the predefined class-named files above, not generic descriptors.)
Module Directory Convention
Each logical concept MUST occupy exactly one concept folder. The folder name MUST be the concept name in kebab-case and MUST be unique within its parent namespace directory.
<project-root>/
project.gnm
modules/
<domain>/
<concept>/ ← one concept folder per module
module.gnm ← manifest: FQN, version, type, imports
schema.gnm ← Schema class declarations
actions.gnm ← Operations class: actions
queries.gnm ← Operations class: queries
... ← other predefined files as needed
The compiler infers one gnomon module per concept folder. A concept folder MUST NOT contain sub-folders that themselves contain .gnm files (the Gazelle leaf-directory rule, RFC-0032 §6). Nesting .gnm files across parent and child folders in the same module is not permitted; each level is its own module.
Declaration Class Diagnostic Codes
- M08701 — file contains declarations from more than one declaration class (error; previously warning)
- M08702 — co-located supporting declaration (
type,variant,flow, orinvariant) has external consumers; must be extracted to its own file - M08703 — file uses a generic forbidden name (
common,types,utils,misc,operations,helpers) in explicit listing mode - M08704 —
extenddeclaration appears in a non-Schema file (error;extendmust be in a Schema class file) - M08705 — file in a concept folder does not match any predefined class name and no explicit listing is present (warning; file will not be compiled)
5. Validation Rules
- A concept folder listed in
project.gnmMUST contain amodule.gnmfile. A concept folder withoutmodule.gnmMUST produce error M01066 and the folder MUST NOT be compiled. module.gnmMUST contain exactly onemoduledeclaration. Zero or more than one MUST produce error M01060.- The FQN declared in
moduleMUST be unique across all installed modules at the time of install-plan validation. Duplicate FQN MUST produce error M01061. - The FQN declared in
moduleMUST match the FQN used to reference this module in any upstreamimportsblock. Mismatch MUST produce error M01062. versionMUST be present and MUST be a valid semver string. Invalid or missing version MUST produce error M01063.typeMUST be present and MUST be one ofbackend-only,ui-only, orhybrid. Invalid or missing type MUST produce error M01001.- Under the folder convention,
objects,operations, andagentslists MAY be omitted entirely; the compiler auto-discovers files using the predefined names from RFC-0008 §7. When any of these lists is present, each path MUST resolve to an existing.gnmfile at compile time; unresolvable paths MUST produce error M01064. - A module MUST declare a dependency in
importsfor every external FQN prefix referenced in its declaration files. Undeclared imports MUST produce error M01050. - Circular import dependencies MUST produce error M01051.
rollbackDependsOnentries MUST reference paths that exist in the sameoperationslist. References to paths not in the list MUST produce error M01055.- Backward-compatibility intent validation is deferred to Phase 1. Authoring MAY include
backcompat: "BC_SAFE" | "BC_BREAKING" | "BC_UNKNOWN"onactiondeclarations, but compiler validation of intent against prior version is Phase 1 work. Current compilers SHOULD emit warning M01010 if backcompat is omitted on actions with observed schema changes. - Policy-affecting change detection is deferred to Phase 1. Authoring MAY mark declarations with
policyAffecting: true, but the compiler algorithm to detect policy-affecting changes automatically is Phase 1 work.
Q2 to Phase 1 Behavior Matrix
| Scenario | Q2 behavior | Phase 1 behavior |
|---|---|---|
| Backcompat intent omitted | SHOULD emit warning M01010 | MUST validate against prior bundle contract diff and emit M01011/M01012 as applicable |
policyAffecting: true declared | MUST propagate flag and emit M01020 info | MUST validate with policy dependency graph and escalate severity on mismatch |
| Rollback references forward-only policy | SHOULD warn pre-install when detectable | MUST reject at install-plan validation (M05401) |
Optional Rollback Authoring Hints
Operations MAY declare rollback planning hints on individual entries in the operations list. See §4 Operations List for syntax. Q2 behavior: compilers MAY preserve these hints without mandatory validation. Phase 1 behavior: install-plan generators MUST validate hint consistency against dependency graphs.
6. Authoring Diagnostics
Diagnostics MUST include:
- severity (
error,warning,info) - code (stable identifier)
- message
- source location (file, line, column)
- suggested fix when available
MCP Authoring Interaction Contract
When authoring is performed through MCP tools:
- MCP mutation tools MUST preserve the same validation outcomes as direct schema/compile invocation.
- MCP responses for authoring mutations MUST include diagnostics in structured form compatible with this RFC.
- MCP tooling SHOULD expose module-type-aware templates (
backend-only,ui-only,hybrid) for no-code/low-code guidance. - MCP tooling MUST NOT auto-coerce invalid policy directionality, mutability, or composition references silently; violations MUST surface diagnostics.
- MCP tooling MAY preserve optional rollback hints (
rollbackCheckpoint,rollbackDependsOn) and MUST surface whether hints were accepted, ignored, or rejected.
7. Security Considerations
- Policy declarations MUST be explicit and non-implicit.
- Authorization declarations MUST be compilable into enforceable runtime contracts.
- Missing policy links for sensitive operations SHOULD raise warnings or errors based on mode.
- Policy-affecting declarations SHOULD support explicit mutability intent (for example, immutable-after-install), and runtime/install behavior MUST honor that intent.
- Security-sensitive declaration changes MUST emit auditable diagnostics for policy reviewers.
8. Compatibility and Migration
- Legacy delimiter-based formats SHOULD be supported only via explicit compatibility paths.
- New authoring changes MUST define migration guidance.
- Deprecations MUST include sunset date and fallback behavior.
9. Diagnostic Codes (RFC-0001 Allocation)
M010x / M016x: Module manifest structure
- M01001: Invalid or missing
typeinmoduledeclaration - M01002:
vieworroutedeclaration found inbackend-onlymodule (error) — also enforced by the grammar-enforcement pass - M01003: No
vieworroutedeclaration found inui-onlymodule (warning) — also enforced by the grammar-enforcement pass - M01060:
module.gnmcontains zero or more than onemoduledeclaration - M01061: Module FQN conflicts with an already-installed module
- M01062: Module FQN does not match the import reference used by the upstream caller
- M01063:
versionmissing or not a valid semver string - M01064: Path in
objects,operations, oragentsdoes not resolve to an existing file - M01065: Explicitly listed section is empty — omit the list to use auto-discovery (warning)
- M01066: Concept folder is missing required
module.gnmmanifest (error)
M011x: Backward-compatibility (Phase 1)
- M01010: Backward-compat intent omitted on changed action (warning)
- M01011: Backcompat intent contradicts analyzed change (error)
- M01012: Cannot statically verify backcompat intent (warning)
M012x: Policy (Phase 1)
- M01020: Policy-affecting declaration change detected (info or higher)
M015x: Imports and references
- M01050: Declaration references external FQN with no corresponding
importsentry - M01051: Circular import dependency detected
- M01052: Declaration kind not permitted in
objectslist file — place inoperationsoragents(warning) - M01053:
agentdeclaration references unresolvablemodel - M01054: AI actor role in
actiondeclaration has no correspondingagentdeclaration - M01055:
rollbackDependsOnreferences path not present inoperationslist
M017x: Grammar enforcement
- M01070: Unknown key in declaration body (always an error — no lenient mode)
- M01071: Top-level declaration is missing required
meaning:field - M01072:
moduledeclaration has invalidtypevalue (must bebackend-only,ui-only, orhybrid)
Note: conditions for view declaration in backend-only modules and missing view/route in ui-only modules are enforced during the grammar-enforcement pass using M01002 and M01003 respectively (see “M000x: Module manifest structure” above).
Cross-references to RFC-0008 diagnostic codes (not RFC-0001-owned):
The following codes are defined and allocated in RFC-0008 but are referenced normatively in this RFC (§4.1):
- M07902 (RFC-0008 §7): file present in concept folder does not match any predefined class name and no explicit listing overrides are present (warning)
- M08701 (RFC-0008 §4.1): file contains declarations from more than one declaration class (error; upgraded from warning)
- M08702 (RFC-0008 §4.1): co-located supporting declaration (
type,variant,flow, orinvariant) has external consumers; must be extracted to its own file - M08703 (RFC-0008 §4.1): file uses a generic forbidden name (
common,types,utils,misc,operations,helpers) in explicit listing mode - M08704 (RFC-0008 §4.1):
extenddeclaration appears in a non-Schema file;extendmust be in a Schema class file
RFC-0001’s normative diagnostic allocation is M01xxx only (M01000–M01999). All M08xxx and M07xxx codes are allocated in RFC-0008.
Appendix A: Optional and Deferred Items (Non-Normative)
Optional follow-on work (not required for RFC-0001 closure):
- Policy abstraction-level transformation rules from abstract authoring declarations to target-specific enforcement declarations.
- Structured migration helper declarations for breaking authoring changes.
Deferred research:
- Formal proof obligations for inter-module policy propagation under concurrent installs.
- Concurrency-aware backward-compatibility equivalence model for operation evolution.