gnomonlearn
Docs/Foundation/RFC-0001

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

  1. Human-authorable format with deterministic compile semantics
  2. Minimal ambiguity in field typing and composition declarations
  3. 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

  1. A module source MUST declare namespace and version and MUST declare a module type.
  2. Declarations MUST be parseable without runtime context.
  3. Cross-reference identifiers MUST be resolvable during compile.
  4. Structured objects MUST be preferred over delimiter-encoded fields.
  5. 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 .gnm file at the root of every module directory. Uses the same .gnm DSL syntax as all other Gnomon source files. Contains a single module declaration that names the module’s fully-qualified namespace and references all other source files in the module.
  • .gnm declaration files (RFC-0008) — the .gnm files that contain entity, action, policy, flow, enum, agent, and other declarations. Their syntax is defined entirely in RFC-0008. They are referenced from module.gnm but MUST NOT redefine the module manifest 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). composition and view declarations in referenced files MUST produce error M01002.
  • ui-only — UI composition required. Referenced files MUST declare at least one view or route declaration; 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:

  1. Each key is a module FQN (NAME { "." NAME } per RFC-0008 §8.1). MUST be lowercase dot-separated.
  2. 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.
  3. A module MUST declare a dependency on any module whose symbols it references. Undeclared dependency references MUST produce error M01050.
  4. Circular dependencies MUST be rejected with error M01051.
  5. The resolved version for each import MUST be recorded in module.lock per RFC-0014 §5.
  6. 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):

  1. Each entry MUST be a quoted string path resolving to an existing .gnm file.
  2. The referenced file MUST contain at least one declaration of kind entity, facet, enum, flow, or claim. Files that contain only action, agent, policy, test, migration, or binding declarations MUST NOT be listed under objects — place them in operations or agents instead. Misplaced declarations MUST produce warning M01052.
  3. Files are compiled in list order. Forward references within the same section are permitted; the compiler resolves them in a second pass.
  4. objects MAY 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:

  1. rollbackCheckpoint: true marks this file’s operations as a rollback boundary. The install plan generator (RFC-0005) MUST treat this as a checkpoint when building rollback sequences.
  2. rollbackDependsOn lists paths whose operations MUST be rolled back before this file’s operations. Referenced paths MUST appear in the same operations list; forward references are not permitted. Missing reference MUST produce error M01055.
  3. Q2 behavior: compilers MAY preserve rollback hints without mandatory validation. Phase 1 behavior: install-plan generators MUST validate hint consistency against dependency graphs.
  4. operations MAY 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:

  1. Each entry MUST be a quoted string path resolving to a .gnm file containing at least one agent declaration (RFC-0009 §3).
  2. Every agent declaration MUST reference a model that resolves to a declaration in the module’s model_declarations (RFC-0002 §4) or an imported model. Unresolved model references MUST produce error M01053.
  3. agents is OPTIONAL. A module with no AI actors MAY omit this section entirely.
  4. Any action declaration in an operations file that names an AI actor role MUST have a corresponding agent declaration resolvable from the agents list 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.

ClassDeclaration kinds
Schemaentity, type, variant, flow, invariant, facet, mutation, compute, claim, extend, config, config-set
Operationsaction, query, task, integration, actuator, event, procedure, client, workflow, saga, api, serve
Relationsrelation
Governancepolicy, agent, compose
Surfaceapp, view
Teststest

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 nameDeclaration class / kinds permitted
module.gnmModule 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.gnmentity, type, variant, flow, invariant, facet, mutation, compute, claim, extend, config
actions.gnmaction
queries.gnmquery
mutations.gnmmutation
events.gnmevent
procedures.gnmprocedure
tasks.gnmtask
integrations.gnmintegration
clients.gnmclient
saga.gnmsaga
relations.gnmrelation
agents.gnmagent
policies.gnmpolicy, compose
views.gnmapp, view
api.gnmapi
serve.gnmserve
tests.gnmtest
migrations.gnmmigration

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.gnm
  • types.gnm
  • utils.gnm
  • misc.gnm
  • operations.gnm
  • helpers.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, or invariant) 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 — extend declaration appears in a non-Schema file (error; extend must 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

  1. A concept folder listed in project.gnm MUST contain a module.gnm file. A concept folder without module.gnm MUST produce error M01066 and the folder MUST NOT be compiled.
  2. module.gnm MUST contain exactly one module declaration. Zero or more than one MUST produce error M01060.
  3. The FQN declared in module MUST be unique across all installed modules at the time of install-plan validation. Duplicate FQN MUST produce error M01061.
  4. The FQN declared in module MUST match the FQN used to reference this module in any upstream imports block. Mismatch MUST produce error M01062.
  5. version MUST be present and MUST be a valid semver string. Invalid or missing version MUST produce error M01063.
  6. type MUST be present and MUST be one of backend-only, ui-only, or hybrid. Invalid or missing type MUST produce error M01001.
  7. Under the folder convention, objects, operations, and agents lists 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 .gnm file at compile time; unresolvable paths MUST produce error M01064.
  8. A module MUST declare a dependency in imports for every external FQN prefix referenced in its declaration files. Undeclared imports MUST produce error M01050.
  9. Circular import dependencies MUST produce error M01051.
  10. rollbackDependsOn entries MUST reference paths that exist in the same operations list. References to paths not in the list MUST produce error M01055.
  11. Backward-compatibility intent validation is deferred to Phase 1. Authoring MAY include backcompat: "BC_SAFE" | "BC_BREAKING" | "BC_UNKNOWN" on action declarations, 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.
  12. 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

ScenarioQ2 behaviorPhase 1 behavior
Backcompat intent omittedSHOULD emit warning M01010MUST validate against prior bundle contract diff and emit M01011/M01012 as applicable
policyAffecting: true declaredMUST propagate flag and emit M01020 infoMUST validate with policy dependency graph and escalate severity on mismatch
Rollback references forward-only policySHOULD warn pre-install when detectableMUST 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:

  1. MCP mutation tools MUST preserve the same validation outcomes as direct schema/compile invocation.
  2. MCP responses for authoring mutations MUST include diagnostics in structured form compatible with this RFC.
  3. MCP tooling SHOULD expose module-type-aware templates (backend-only, ui-only, hybrid) for no-code/low-code guidance.
  4. MCP tooling MUST NOT auto-coerce invalid policy directionality, mutability, or composition references silently; violations MUST surface diagnostics.
  5. MCP tooling MAY preserve optional rollback hints (rollbackCheckpoint, rollbackDependsOn) and MUST surface whether hints were accepted, ignored, or rejected.

7. Security Considerations

  1. Policy declarations MUST be explicit and non-implicit.
  2. Authorization declarations MUST be compilable into enforceable runtime contracts.
  3. Missing policy links for sensitive operations SHOULD raise warnings or errors based on mode.
  4. Policy-affecting declarations SHOULD support explicit mutability intent (for example, immutable-after-install), and runtime/install behavior MUST honor that intent.
  5. Security-sensitive declaration changes MUST emit auditable diagnostics for policy reviewers.

8. Compatibility and Migration

  1. Legacy delimiter-based formats SHOULD be supported only via explicit compatibility paths.
  2. New authoring changes MUST define migration guidance.
  3. Deprecations MUST include sunset date and fallback behavior.

9. Diagnostic Codes (RFC-0001 Allocation)

M010x / M016x: Module manifest structure

  • M01001: Invalid or missing type in module declaration
  • M01002: view or route declaration found in backend-only module (error) — also enforced by the grammar-enforcement pass
  • M01003: No view or route declaration found in ui-only module (warning) — also enforced by the grammar-enforcement pass
  • M01060: module.gnm contains zero or more than one module declaration
  • M01061: Module FQN conflicts with an already-installed module
  • M01062: Module FQN does not match the import reference used by the upstream caller
  • M01063: version missing or not a valid semver string
  • M01064: Path in objects, operations, or agents does 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.gnm manifest (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 imports entry
  • M01051: Circular import dependency detected
  • M01052: Declaration kind not permitted in objects list file — place in operations or agents (warning)
  • M01053: agent declaration references unresolvable model
  • M01054: AI actor role in action declaration has no corresponding agent declaration
  • M01055: rollbackDependsOn references path not present in operations list

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: module declaration has invalid type value (must be backend-only, ui-only, or hybrid)

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, or invariant) 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): extend declaration appears in a non-Schema file; extend must 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):

  1. Policy abstraction-level transformation rules from abstract authoring declarations to target-specific enforcement declarations.
  2. Structured migration helper declarations for breaking authoring changes.

Deferred research:

  1. Formal proof obligations for inter-module policy propagation under concurrent installs.
  2. Concurrency-aware backward-compatibility equivalence model for operation evolution.