RFC-0008 · 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-0008: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0008.This page is generated from the
lean/Gnomon/Spec/module for RFC-0008. Edit that source and regenerate this catalog.
Title: Gnomon Language Authoring Surface
Status: draft
Owners: Compiler, DX
Extended by: RFC-0011
Proof citations in source: 37 / 37. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| block slot | key { slot* } — structural, contains child slots. |
| declaration | A keyword Name { slot* } form; the universal authoring construct in Gnomon. |
| desugar pass | Single isolated syntactic pass that expands sugar forms to canonical block forms before semantic analysis. |
| epistemic modifier | Authoring/lifecycle marker on a declaration: draft, deprecated, experimental, sealed, or abstract. |
| expr statement | Structured boolean expression in the Gnomon constraint expression language; deterministic, no LLM involvement. |
| expression slot | key = expr — dynamic, compiler-visible expression evaluated against entity state. |
| note statement | Documentation prose within a rule block; never evaluated. |
| prompt statement | Runtime prompt evaluated by a bound model at execution time; valid only in agent declarations. |
| property slot | key: value — static, author-written value. |
| rule statement | Compile-time natural-language constraint lowered by a rule compiler model to a constraint expression. |
| script slot | key script lang { } — opaque escape hatch with embedded host-language body. |
| slot | One of property slot (key: value), block slot (key { slot* }), expression slot (key = expr), or script slot (key script lang { }). |
| visibility modifier | public (default, exported) or internal (module-private). |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M06030 | Error | Expression slot references undeclared field or function |
M06031 | Error | compute expression return type incompatible with declared returns |
M06032 | Warning | script slot used where expr slot may suffice |
M06033 | Error | Unrecognized script language identifier (must be typescript, python, or sql) |
M06034 | Error | compute declaration has side effects |
M06060 | Warning | Unrecognized field modifier |
M06061 | Error | required and default(v) both declared on the same field |
M06062 | Error | default(v) value is not a literal of the field’s declared type |
M06070 | Error | apply target FQN does not resolve to a declared declaration |
M06071 | Error | apply annotation duplicates an annotation already declared inline on the target |
M06072 | Error | apply in same module as target; use inline annotations { } instead |
M06080 | Error | Both named input {} and inline input := {} declared on the same operation |
M06081 | Error | Both named returns: TypeName and inline returns := {} declared on the same operation |
M06083 | Error | Explicit returns: Unit is forbidden; omit returns to signal no return value |
M07100 | Error | action declares preconditions, effects, or returns |
M07101 | Error | action mutations {} references undeclared mutation |
M07102 | Error | Non-emits statement in action after {} block |
M07103 | Error | procedure declares effects {} or after {} |
M07104 | Error | procedure missing required runs slot |
M07105 | Error | procedure returns type incompatible with action’s last mutation return type |
M07106 | Error | actuator missing required on slot |
M07107 | Error | actuator declares effects {} |
M07108 | Error | emits references undeclared event |
M07109 | Error | execute binding references undeclared client or undeclared operation on that client |
M07110 | Error | execute binding references an undeclared prior binding (dependency error) |
M07111 | Error | execute {} block contains mutation call, event emission, or state-changing expression |
M07115 | Error | workflow step missing model: binding or human_gate directive |
M07116 | Error | saga step contains human_gate directive — use workflow for human-in-the-loop orchestration |
M07200 | Warning | Event emittedBy names declaration with no corresponding emits statement |
M07901 | Error | Concept folder contains .gnm files belonging to more than one module FQN |
M07902 | Warning | File in concept folder does not match any predefined class name and will not be compiled |
M07903 | Warning | Concept folder contains module.gnm but no recognized declaration files |
M08001 | Warning | Workflow flow missing terminal success, failure, or Compensating state |
M08100 | Error | client operation missing required slot (method, path, input, or returns) |
M08101 | Error | Unrecognized error class in client operation errors block |
M08102 | Error | calls: references undeclared client |
M08103 | Error | calls: references operation not declared on the named client |
M08104 | Error | calls: using {} binding mismatch with client operation input |
M08105 | Error | Spec-backed client has unreachable or unparseable spec source |
M08106 | Error | Spec-backed client also declares operations {} |
M08200 | Error | workflow missing required state slot |
M08201 | Error | Step handler transitions names state not in workflow flow |
M08202 | Error | compensate references step with no compensate declaration |
M08203 | Error | Step on success references undeclared mutation |
M08204 | Warning | Step on failure block missing transitions (workflow may get stuck) |
M08700 | Error | File extension is not .gnm |
M08701 | Error | File contains declarations from multiple declaration classes |
M08702 | Error | Co-located supporting declaration has external consumers; must be extracted to its own file |
M08703 | Error | File uses a generic forbidden name (common, types, utils, misc, operations, helpers) |
M08704 | Error | extend declaration in non-Schema class file |
M08705 | Error | Entity declaration missing meaning field |
M08706 | Error | Agent declaration missing permissions or prohibitions block |
M08707 | Error | project declaration found outside project.gnm |
M08710 | Error | Action references undeclared entity or field |
M08712 | Error | View references undeclared query or action |
M08713 | Error | App bundle references undeclared model, policy, flow, or agent |
M08720 | Error | Module path in manifest not found on disk |
M08721 | Error | Circular import detected in project manifest |
M08722 | Error | project.gnm contains non-project declaration content |
M08723 | Error | module-decl appears in a file other than module.gnm |
M08724 | Error | module.gnm contains non-module top-level declarations alongside module-decl |
M08730 | Error | Reference cannot be resolved — symbol not found in unified symbol table |
M08731 | Error | Conflicting declaration for same canonical path in two source files |
M08732 | Error | Declaration property value references a symbol that resolves to the wrong declaration kind |
M08733 | Error | Declaration body cannot be compiled to canonical IR — structural invariant violated |
M08740 | Error | Identifier casing does not match required convention for its declaration kind |
M08741 | Warning | FlowType name does not end in Lifecycle |
M08742 | Error | Agent name does not end in Agent |
M08743 | Error | Module namespace is not lowercase dot-separated |
M08744 | Error | File name is generic (defs, misc, common, utils) or uses a numeric suffix |
M08750 | Error | Public declaration references an internal declaration from another module |
M08751 | Error | project or test declaration carries a visibility modifier |
M08752 | Error | internal declaration present in compiled bundle identity envelope |
M08760 | Warning | Doc comment content is not valid CommonMark |
M08761 | Warning | meaning field value is not valid CommonMark |
M08780 | Warning | draft declaration referenced by a non-draft declaration |
M08781 | Warning | deprecated declaration used at a reference site |
M08782 | Warning | experimental declaration referenced from outside its declaring module |
M08783 | Error | sealed declaration extended, composed, or includesd from outside its declaring module |
M08784 | Error | abstract declaration referenced directly (not in a compose or includes position) |
M08785 | Error | Declaration carries more than one epistemic modifier |
M08786 | Error | draft declaration present in bundle with ciState: ready |
M08790 | Warning | Bare natural-language line in rule block; treated as rule ”…” during migration |
M08791 | Error | rule ”…” with no rule compiler configured and no per-statement model override |
M08792 | Error | Rule compiler returned UNRESOLVABLE — rule text references a field or concept not in the domain model |
M08793 | Warning | Rule compiler identified statement as AUTHORIZATION_RULE or LIFECYCLE_RULE — belongs in a policy or flow declaration |
M08794 | Error | prompt ”…” statement in a non-agent rule block |
M08795 | Error | model declaration missing both digest and version |
M08796 | Error | Model used in a role it does not declare |
M08932 | Warning | Agent has permissions block but no readScope block — agent can read all entity kinds without restriction |
M09000 | Error | task missing required triggeredBy slot |
M09001 | Error | triggeredBy references undeclared event |
M09002 | Error | Task effects transition names state not in entity’s flow |
M09003 | Error | Task onError state not in entity’s flow |
M09004 | Error | task declares preconditions |
M09005 | Error | Non-emits statement in task after {} block |
M16010 | Error | transform for references undeclared entity |
M16011 | Error | transform to is not a valid semantic version string |
M16012 | Error | transform apply {} references field absent from the entity at the from version |
M16013 | Error | transform expression return type incompatible with target field type |
M16020 | Error | transform body has side effects (external call, event emission, or persistence read) |
M16021 | Error | Expression in transform is not provably total over the source field’s type domain |
Dependency neighborhood
graph LR
nRFC_0008["RFC-0008"]
nRFC_0011["RFC-0011"]
nRFC_0011 --> nRFC_0008
Invariants
- A draft declaration MUST NOT appear in a compiled bundle whose ciState is ready. (enforced by: compile-time)
- A file MUST contain declarations of exactly one declaration class; mixing classes is error M08701. (enforced by: compile-time)
- A model declaration MUST specify either digest or version so model resolution is reproducible. (enforced by: compile-time)
- A sealed declaration MUST NOT be extended, composed, or includes’d from outside its declaring module. (enforced by: compile-time)
- All .gnm files inside a concept folder MUST belong to the same module FQN; cross-module co-location is error M07901. (enforced by: compile-time)
- Authorization logic MUST reside in policy declarations and MUST NOT appear in entity or view declarations. (enforced by: compile-time)
- Every Gnomon source file MUST use the .gnm extension; other extensions produce M08700. (enforced by: compile-time)
- Every agent declaration MUST enumerate explicit permissions and prohibitions blocks. (enforced by: compile-time)
- Every entity declaration MUST include a meaning property. (enforced by: compile-time)
- Every facet declaration MUST include a meaning property; the compiler does not supply a default. (enforced by: compile-time)
- Explicit returns: Unit is forbidden; omitting returns signals no return value (error M06083). (enforced by: compile-time)
- The project.gnm manifest MUST NOT contain declaration content other than the project block and its compiler sub-block. (enforced by: compile-time)
- The sugar inventory is closed; module authors MUST NOT define syntactic expansions, and new sugar requires an RFC revision. (enforced by: compile-time)
- UI view declarations MUST NOT contain business rules; authorization and invariants belong in policy declarations. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- MUST — Changing the syntax of an existing declaration kind is breaking and MUST increment the language version.
File Extension
- MUST — Each file MUST be named after the concept it defines. (proof citation:
rfc0008_file_named_after_concept; verification pending) - MUST_NOT — Files MUST NOT use generic names like common, misc, utils, or defs. (proof citation:
rfc0008_files_not_generic_names; verification pending)
Invariants
- MUST — A file MUST contain declarations of exactly one declaration class. (proof citation:
rfc0008_file_one_declaration_class; verification pending) - MUST — Every agent declaration MUST enumerate explicit permissions and prohibitions. (proof citation:
rfc0008_agent_explicit_permissions; verification pending) - MUST — Every entity declaration MUST include a meaning property. (proof citation:
rfc0008_entity_has_meaning; verification pending) - MUST — Every facet declaration MUST include a meaning property. (proof citation:
rfc0008_facet_has_meaning; verification pending) - MUST — Every source file MUST use the .gnm extension. (proof citation:
rfc0008_gnomon_extension_required; verification pending) - MUST_NOT — UI view declarations MUST NOT contain business rules. (proof citation:
rfc0008_ui_view_no_business_rules; verification pending) - MUST_NOT — project.gnm MUST NOT contain declaration content other than the project { } block. (proof citation:
rfc0008_project_gnomon_only_project_block; verification pending)
Language Syntax
- MUST — A model declaration MUST specify provider, name, and either digest or version. (proof citation:
rfc0008_model_form_at_boundary; verification pending) - MUST — A procedure MUST declare runs naming a declared action. (proof citation:
rfc0008_procedure_runs_action_resolves; verification pending) - MUST_NOT — A saga step MUST NOT contain a human_gate directive. (proof citation:
rfc0008_saga_step_no_human_gate; verification pending) - MUST — A task MUST declare triggeredBy referencing a declared event. (proof citation:
rfc0008_task_triggered_by_resolves; verification pending) - MUST_NOT — A transform body MUST NOT call external APIs, emit events, read from the persistence graph, or produce side effects. (proof citation:
rfc0008_transform_body_pure; verification pending) - MUST — An action MUST NOT declare preconditions, effects, or returns directly. (proof citation:
rfc0008_action_no_inline_pre_post; verification pending) - MUST — The LSP MUST switch language mode at the script lang { boundary. (proof citation:
rfc0008_lsp_switches_at_boundary; verification pending)
Manifest Files
- MUST — All .gnm files in a concept folder MUST belong to the same gnomon module. (proof citation:
rfc0008_concept_folder_same_module; verification pending) - MUST_NOT — The compiler block MUST NOT appear in individual .gnm files. (proof citation:
rfc0008_compiler_block_not_in_module_files; verification pending) - MUST — The project manifest MUST be named project.gnm and placed at the project root. (proof citation:
rfc0008_project_manifest_named_project_gnomon; verification pending)
Naming and Casing Conventions
- MUST — All meaning fields MUST be plain-language prose readable by a non-technical domain author. (proof citation:
rfc0008_meaning_fields_are_plain_prose; verification pending) - MUST — File names MUST conform to NAME (lowercase, RFC 1123 label, max 63 chars). (proof citation:
rfc0008_file_names_conform; verification pending) - MUST_NOT — meaning fields MUST NOT contain code, type names, or implementation references. (proof citation:
rfc0008_meaning_no_code; verification pending)
Normative EBNF Grammar
- MUST — Each non-trivial production MUST have at least one parse fixture. (proof citation:
rfc0008_production_has_fixture; verification pending) - MUST — Implementations MUST parse conforming .gnm files and reject non-conforming files with location-aware diagnostics. (proof citation:
rfc0008_parse_or_reject; verification pending) - MUST — The grammar MUST be expressible as a PEG grammar without modification. (proof citation:
rfc0008_grammar_expressible_as_peg; verification pending)
Project Layout
- MUST_NOT — Tooling MUST NOT recognize or scaffold any other layout. (proof citation:
rfc0008_tooling_no_other_layout; verification pending) - MUST — Tooling MUST support the canonical module-based layout. (proof citation:
rfc0008_tooling_supports_canonical_layout; verification pending)
Scope
- MUST — All Gnomon source files use the .gnm extension. (proof citation:
rfc0008_gnomon_extension; verification pending)
Security and Authorization
- MUST — Agent capability declarations MUST be reviewed and explicitly approved before deployment. (proof citation:
rfc0008_agent_capabilities_approved; verification pending) - MUST — Authorization logic MUST reside in policy files and not appear in entity or view declarations. (proof citation:
rfc0008_authorization_in_policy_files; verification pending) - MUST_NOT — UI projections MUST NOT expose fields that the active policy prohibits for the rendering actor. (proof citation:
rfc0008_ui_respects_policy; verification pending)
Syntax Design Principles
- MUST — Doc comment content MUST be CommonMark prose. (proof citation:
rfc0008_doc_comments_are_commonmark_prose; verification pending)
Unified Declaration Model
- MUST_NOT — A module MUST NOT define the same canonical path in two source files. (proof citation:
rfc0008_canonical_path_unique; verification pending) - MUST_NOT — The compiler MUST NOT silently coerce a facet into an aspect during normalization. (proof citation:
rfc0008_no_silent_facet_aspect_coerce; verification pending)
Visibility and Epistemic State
- MAY — A declaration MAY carry at most one epistemic modifier. (proof citation:
rfc0008_at_most_one_epistemic_modifier; verification pending) - MUST_NOT — A public declaration MUST NOT reference an internal declaration from a different module. (proof citation:
rfc0008_public_no_internal_cross_module; verification pending) - MUST_NOT — The compiler MUST NOT export internal declarations in the compiled bundle. (proof citation:
rfc0008_compiler_no_internal_export; verification pending) - MUST_NOT — draft declarations MUST NOT appear in a compiled bundle with ciState: ready.
Linked References
| Direction | Target |
|---|---|
| Extended by | RFC-0011 |