RFC-0001 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0001: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0001.This page is generated from the
lean/Gnomon/Spec/module for RFC-0001. Edit that source and regenerate this catalog.
Title: Module Authoring Format
Status: draft
Owners: DX, Module Platform
Diagnostic range: M01000-M01999
Proof citations in source: 25 / 25. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| concept folder | Folder occupied by exactly one logical concept (one gnomon module), named in kebab-case and unique within its parent namespace directory. |
| declaration class | Classification governing which declaration kinds may appear together in a single file: Schema, Operations, Relations, Governance, Surface, or Tests. |
| explicit listing mode | Layout mode in which module.gnm contains objects, operations, and agents lists that enumerate source files explicitly, overriding auto-discovery. |
| folder convention | Layout mode (RFC-0008 §7) in which source files within a concept folder are named by declaration class and auto-discovered by the compiler, requiring no explicit file listings in module.gnm. |
| module type | Required declaration of one of three values: backend-only (no UI composition), ui-only (UI composition required), or hybrid (both). |
| module.gnm | Single required manifest file at the root of every module directory; an .gnm file containing exactly one module declaration that names the module’s fully-qualified namespace and configures module-level metadata. |
| rollbackCheckpoint | Optional rollback hint marking an operations file as a rollback boundary for the install plan generator. |
| rollbackDependsOn | Optional rollback hint listing paths whose operations must be rolled back before this file’s operations. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M01001 | Error | Invalid or missing type in module declaration |
M01002 | Error | composition or view declaration found in backend-only module |
M01003 | Warning | No view or route declaration found in ui-only module |
M01010 | Warning | Backward-compat intent omitted on changed action |
M01011 | Error | Backcompat intent contradicts analyzed change |
M01012 | Warning | Cannot statically verify backcompat intent |
M01020 | Info | Policy-affecting declaration change detected |
M01050 | Error | Declaration references external FQN with no corresponding imports entry |
M01051 | Error | Circular import dependency detected |
M01052 | Warning | Declaration kind not permitted in objects list file — place in operations or agents |
M01053 | Error | agent declaration references unresolvable model |
M01054 | Error | AI actor role in action declaration has no corresponding agent declaration |
M01055 | Error | rollbackDependsOn references path not present in operations list |
M01060 | Error | module.gnm contains zero or more than one module declaration |
M01061 | Error | Module FQN conflicts with an already-installed module |
M01062 | Error | Module FQN does not match the import reference used by the upstream caller |
M01063 | Error | version missing or not a valid semver string |
M01064 | Error | Path in objects, operations, or agents does not resolve to an existing file |
M01065 | Warning | Explicitly listed section is empty — omit the list to use auto-discovery |
M01066 | Error | Concept folder is missing required module.gnm manifest |
M01070 | Error | Unknown key in declaration body (always an error — no lenient mode) |
M01071 | Error | Top-level declaration is missing required meaning: field |
M01072 | Error | module declaration has invalid type value (must be backend-only, ui-only, or hybrid) |
Invariants
- A concept folder MUST NOT contain sub-folders that themselves contain .gnm files (Gazelle leaf-directory rule). (enforced by: compile-time)
- A concept folder listed in project.gnm MUST contain a module.gnm file; absence produces M01066. (enforced by: compile-time)
- A file MUST contain declarations of exactly one declaration class; mixing classes is error M08701. (enforced by: compile-time)
- A module MUST declare a dependency in imports for every external FQN prefix referenced in its declaration files. (enforced by: compile-time)
- A module source MUST declare namespace, version, and module type. (enforced by: compile-time)
- Aspects and facets MUST be present for UI-oriented modules and MAY be omitted for backend-only modules.
- Circular import dependencies MUST be rejected. (enforced by: compile-time)
- Cross-reference identifiers MUST be resolvable during compile. (enforced by: compile-time)
- Declarations MUST be parseable without runtime context. (enforced by: parse-time)
- Structured objects MUST be preferred over delimiter-encoded fields.
- The FQN declared in module MUST be unique across all installed modules at install-plan validation. (enforced by: install-time)
- module.gnm MUST contain exactly one module declaration; zero or more than one produces M01060. (enforced by: parse-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Authoring Contract
- MUST — A compiler MUST parse module.gnm first and resolve all referenced files before semantic analysis.
- MUST — A module MUST declare a dependency in imports for any module whose symbols it references; undeclared references produce error M01050. (proof citation:
rfc0001_undeclared_dependency_resolves_or_rejects; verification pending) - MUST — Circular import dependencies MUST be rejected with error M01051. (proof citation:
rfc0001_circular_import_accepted_or_rejected; verification pending) - MUST — Every agent declaration MUST resolve its model to a local model_declaration or imported model; unresolved produces error M01053. (proof citation:
rfc0001_agent_model_resolves_or_rejects; verification pending) - MUST — Every module MUST declare a type of backend-only, ui-only, or hybrid; absence produces error M01001. (proof citation:
rfc0001_module_type_required_at_boundary; verification pending) - MUST — Files listed under objects MUST contain at least one entity, facet, enum, flow, or claim declaration; misplaced declarations produce warning M01052. (proof citation:
rfc0001_b35_grounded; verification pending) - MUST — The resolved version for each import MUST be recorded in module.lock per RFC-0014 §5.
- MUST — module.gnm MUST contain exactly one top-level module declaration; other top-level declarations produce error M01060. (proof citation:
rfc0001_module_gnomon_single_top_level; verification pending)
Authoring Diagnostics
- MUST — Diagnostics MUST include severity, code, message, source location (file, line, column), and a suggested fix when available.
- MUST — MCP mutation tools MUST preserve the same validation outcomes as direct schema/compile invocation. (proof citation:
rfc0001_mcp_validation_deterministic; verification pending) - MUST — MCP responses for authoring mutations MUST include diagnostics in structured form. (proof citation:
rfc0001_mcp_diagnostic_structured; verification pending) - MUST_NOT — MCP tooling MUST NOT silently auto-coerce invalid policy directionality, mutability, or composition references; violations MUST surface diagnostics. (proof citation:
rfc0001_mcp_no_silent_coerce; verification pending)
Compatibility and Migration
- MUST — Deprecations MUST include sunset date and fallback behavior.
- SHOULD — Legacy delimiter-based formats SHOULD be supported only via explicit compatibility paths.
- MUST — New authoring changes MUST define migration guidance.
File Taxonomy and Declaration Classes
- MUST — A co-located supporting declaration referenced from another file MUST be extracted to its own file (error M08702). (proof citation:
rfc0001_b0_grounded; verification pending) - MUST_NOT — A concept folder MUST NOT contain sub-folders that themselves contain .gnm files (Gazelle leaf-directory rule). (proof citation:
rfc0001_concept_folder_leaf_only; verification pending) - MUST — A file MUST contain declarations of exactly one declaration class; mixing classes is error M08701. (proof citation:
rfc0001_b15_grounded; verification pending) - MUST — Each logical concept MUST occupy exactly one concept folder, named in kebab-case and unique within its parent namespace directory. (proof citation:
rfc0001_concept_folder_named_after_concept; verification pending) - MUST_NOT — Generic filenames (common, types, utils, misc, operations, helpers) MUST NOT be used in explicit listing mode (error M08703). (proof citation:
rfc0001_no_generic_filenames; verification pending)
Invariants
- MUST — A module source MUST declare namespace, version, and module type. (proof citation:
rfc0001_module_form_requires_name_and_version; verification pending) - MUST — Aspects and facets MUST be present for UI-oriented modules; MAY be omitted for backend-only modules.
- MUST — Cross-reference identifiers MUST be resolvable during compile. (proof citation:
rfc0001_b50_grounded; verification pending) - MUST — Declarations MUST be parseable without runtime context.
- MUST — Structured objects MUST be preferred over delimiter-encoded fields.
Security Considerations
- MUST — Authorization declarations MUST be compilable into enforceable runtime contracts. (proof citation:
rfc0001_b37_grounded; verification pending) - MUST — Policy declarations MUST be explicit and non-implicit. (proof citation:
rfc0001_policy_explicit_via_capability_mediation; verification pending) - MUST — Runtime and install behavior MUST honor declared mutability intent on policy-affecting declarations.
- MUST — Security-sensitive declaration changes MUST emit auditable diagnostics for policy reviewers. (proof citation:
rfc0001_b58_grounded; verification pending)
Validation Rules
- MUST — A concept folder listed in project.gnm MUST contain a module.gnm file; absence produces error M01066. (proof citation:
rfc0001_b33_grounded; verification pending) - MUST — The FQN declared in module MUST be unique across all installed modules; duplicates produce error M01061. (proof citation:
rfc0001_b19_grounded; verification pending) - MUST — The declared FQN MUST match the FQN used by upstream importers; mismatch produces error M01062. (proof citation:
rfc0001_fqn_match_via_referential_integrity; verification pending) - MUST — When objects, operations, or agents lists are present, each path MUST resolve to an existing .gnm file; unresolvable paths produce error M01064. (proof citation:
rfc0001_b7_grounded; verification pending) - MUST — rollbackDependsOn entries MUST reference paths in the same operations list; otherwise error M01055. (proof citation:
rfc0001_rollback_depends_on_resolves; verification pending) - MUST — version MUST be present and a valid semver string; otherwise error M01063. (proof citation:
rfc0001_version_validity_at_boundary; verification pending)
Linked References
(no cross-RFC dependencies)