gnomonlearn
Docs/RFC-0008/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
block slotkey { slot* } — structural, contains child slots.
declarationA keyword Name { slot* } form; the universal authoring construct in Gnomon.
desugar passSingle isolated syntactic pass that expands sugar forms to canonical block forms before semantic analysis.
epistemic modifierAuthoring/lifecycle marker on a declaration: draft, deprecated, experimental, sealed, or abstract.
expr statementStructured boolean expression in the Gnomon constraint expression language; deterministic, no LLM involvement.
expression slotkey = expr — dynamic, compiler-visible expression evaluated against entity state.
note statementDocumentation prose within a rule block; never evaluated.
prompt statementRuntime prompt evaluated by a bound model at execution time; valid only in agent declarations.
property slotkey: value — static, author-written value.
rule statementCompile-time natural-language constraint lowered by a rule compiler model to a constraint expression.
script slotkey script lang { } — opaque escape hatch with embedded host-language body.
slotOne of property slot (key: value), block slot (key { slot* }), expression slot (key = expr), or script slot (key script lang { }).
visibility modifierpublic (default, exported) or internal (module-private).

Diagnostics

CodeSeverityDescription
M06030ErrorExpression slot references undeclared field or function
M06031Errorcompute expression return type incompatible with declared returns
M06032Warningscript slot used where expr slot may suffice
M06033ErrorUnrecognized script language identifier (must be typescript, python, or sql)
M06034Errorcompute declaration has side effects
M06060WarningUnrecognized field modifier
M06061Errorrequired and default(v) both declared on the same field
M06062Errordefault(v) value is not a literal of the field’s declared type
M06070Errorapply target FQN does not resolve to a declared declaration
M06071Errorapply annotation duplicates an annotation already declared inline on the target
M06072Errorapply in same module as target; use inline annotations { } instead
M06080ErrorBoth named input {} and inline input := {} declared on the same operation
M06081ErrorBoth named returns: TypeName and inline returns := {} declared on the same operation
M06083ErrorExplicit returns: Unit is forbidden; omit returns to signal no return value
M07100Erroraction declares preconditions, effects, or returns
M07101Erroraction mutations {} references undeclared mutation
M07102ErrorNon-emits statement in action after {} block
M07103Errorprocedure declares effects {} or after {}
M07104Errorprocedure missing required runs slot
M07105Errorprocedure returns type incompatible with action’s last mutation return type
M07106Erroractuator missing required on slot
M07107Erroractuator declares effects {}
M07108Erroremits references undeclared event
M07109Errorexecute binding references undeclared client or undeclared operation on that client
M07110Errorexecute binding references an undeclared prior binding (dependency error)
M07111Errorexecute {} block contains mutation call, event emission, or state-changing expression
M07115Errorworkflow step missing model: binding or human_gate directive
M07116Errorsaga step contains human_gate directive — use workflow for human-in-the-loop orchestration
M07200WarningEvent emittedBy names declaration with no corresponding emits statement
M07901ErrorConcept folder contains .gnm files belonging to more than one module FQN
M07902WarningFile in concept folder does not match any predefined class name and will not be compiled
M07903WarningConcept folder contains module.gnm but no recognized declaration files
M08001WarningWorkflow flow missing terminal success, failure, or Compensating state
M08100Errorclient operation missing required slot (method, path, input, or returns)
M08101ErrorUnrecognized error class in client operation errors block
M08102Errorcalls: references undeclared client
M08103Errorcalls: references operation not declared on the named client
M08104Errorcalls: using {} binding mismatch with client operation input
M08105ErrorSpec-backed client has unreachable or unparseable spec source
M08106ErrorSpec-backed client also declares operations {}
M08200Errorworkflow missing required state slot
M08201ErrorStep handler transitions names state not in workflow flow
M08202Errorcompensate references step with no compensate declaration
M08203ErrorStep on success references undeclared mutation
M08204WarningStep on failure block missing transitions (workflow may get stuck)
M08700ErrorFile extension is not .gnm
M08701ErrorFile contains declarations from multiple declaration classes
M08702ErrorCo-located supporting declaration has external consumers; must be extracted to its own file
M08703ErrorFile uses a generic forbidden name (common, types, utils, misc, operations, helpers)
M08704Errorextend declaration in non-Schema class file
M08705ErrorEntity declaration missing meaning field
M08706ErrorAgent declaration missing permissions or prohibitions block
M08707Errorproject declaration found outside project.gnm
M08710ErrorAction references undeclared entity or field
M08712ErrorView references undeclared query or action
M08713ErrorApp bundle references undeclared model, policy, flow, or agent
M08720ErrorModule path in manifest not found on disk
M08721ErrorCircular import detected in project manifest
M08722Errorproject.gnm contains non-project declaration content
M08723Errormodule-decl appears in a file other than module.gnm
M08724Errormodule.gnm contains non-module top-level declarations alongside module-decl
M08730ErrorReference cannot be resolved — symbol not found in unified symbol table
M08731ErrorConflicting declaration for same canonical path in two source files
M08732ErrorDeclaration property value references a symbol that resolves to the wrong declaration kind
M08733ErrorDeclaration body cannot be compiled to canonical IR — structural invariant violated
M08740ErrorIdentifier casing does not match required convention for its declaration kind
M08741WarningFlowType name does not end in Lifecycle
M08742ErrorAgent name does not end in Agent
M08743ErrorModule namespace is not lowercase dot-separated
M08744ErrorFile name is generic (defs, misc, common, utils) or uses a numeric suffix
M08750ErrorPublic declaration references an internal declaration from another module
M08751Errorproject or test declaration carries a visibility modifier
M08752Errorinternal declaration present in compiled bundle identity envelope
M08760WarningDoc comment content is not valid CommonMark
M08761Warningmeaning field value is not valid CommonMark
M08780Warningdraft declaration referenced by a non-draft declaration
M08781Warningdeprecated declaration used at a reference site
M08782Warningexperimental declaration referenced from outside its declaring module
M08783Errorsealed declaration extended, composed, or includesd from outside its declaring module
M08784Errorabstract declaration referenced directly (not in a compose or includes position)
M08785ErrorDeclaration carries more than one epistemic modifier
M08786Errordraft declaration present in bundle with ciState: ready
M08790WarningBare natural-language line in rule block; treated as rule ”…” during migration
M08791Errorrule ”…” with no rule compiler configured and no per-statement model override
M08792ErrorRule compiler returned UNRESOLVABLE — rule text references a field or concept not in the domain model
M08793WarningRule compiler identified statement as AUTHORIZATION_RULE or LIFECYCLE_RULE — belongs in a policy or flow declaration
M08794Errorprompt ”…” statement in a non-agent rule block
M08795Errormodel declaration missing both digest and version
M08796ErrorModel used in a role it does not declare
M08932WarningAgent has permissions block but no readScope block — agent can read all entity kinds without restriction
M09000Errortask missing required triggeredBy slot
M09001ErrortriggeredBy references undeclared event
M09002ErrorTask effects transition names state not in entity’s flow
M09003ErrorTask onError state not in entity’s flow
M09004Errortask declares preconditions
M09005ErrorNon-emits statement in task after {} block
M16010Errortransform for references undeclared entity
M16011Errortransform to is not a valid semantic version string
M16012Errortransform apply {} references field absent from the entity at the from version
M16013Errortransform expression return type incompatible with target field type
M16020Errortransform body has side effects (external call, event emission, or persistence read)
M16021ErrorExpression 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

  1. A draft declaration MUST NOT appear in a compiled bundle whose ciState is ready. (enforced by: compile-time)
  2. A file MUST contain declarations of exactly one declaration class; mixing classes is error M08701. (enforced by: compile-time)
  3. A model declaration MUST specify either digest or version so model resolution is reproducible. (enforced by: compile-time)
  4. A sealed declaration MUST NOT be extended, composed, or includes’d from outside its declaring module. (enforced by: compile-time)
  5. 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)
  6. Authorization logic MUST reside in policy declarations and MUST NOT appear in entity or view declarations. (enforced by: compile-time)
  7. Every Gnomon source file MUST use the .gnm extension; other extensions produce M08700. (enforced by: compile-time)
  8. Every agent declaration MUST enumerate explicit permissions and prohibitions blocks. (enforced by: compile-time)
  9. Every entity declaration MUST include a meaning property. (enforced by: compile-time)
  10. Every facet declaration MUST include a meaning property; the compiler does not supply a default. (enforced by: compile-time)
  11. Explicit returns: Unit is forbidden; omitting returns signals no return value (error M06083). (enforced by: compile-time)
  12. The project.gnm manifest MUST NOT contain declaration content other than the project block and its compiler sub-block. (enforced by: compile-time)
  13. The sugar inventory is closed; module authors MUST NOT define syntactic expansions, and new sugar requires an RFC revision. (enforced by: compile-time)
  14. 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

  1. MUST — Changing the syntax of an existing declaration kind is breaking and MUST increment the language version.

File Extension

  1. MUST — Each file MUST be named after the concept it defines. (proof citation: rfc0008_file_named_after_concept; verification pending)
  2. MUST_NOT — Files MUST NOT use generic names like common, misc, utils, or defs. (proof citation: rfc0008_files_not_generic_names; verification pending)

Invariants

  1. MUST — A file MUST contain declarations of exactly one declaration class. (proof citation: rfc0008_file_one_declaration_class; verification pending)
  2. MUST — Every agent declaration MUST enumerate explicit permissions and prohibitions. (proof citation: rfc0008_agent_explicit_permissions; verification pending)
  3. MUST — Every entity declaration MUST include a meaning property. (proof citation: rfc0008_entity_has_meaning; verification pending)
  4. MUST — Every facet declaration MUST include a meaning property. (proof citation: rfc0008_facet_has_meaning; verification pending)
  5. MUST — Every source file MUST use the .gnm extension. (proof citation: rfc0008_gnomon_extension_required; verification pending)
  6. MUST_NOT — UI view declarations MUST NOT contain business rules. (proof citation: rfc0008_ui_view_no_business_rules; verification pending)
  7. 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

  1. MUST — A model declaration MUST specify provider, name, and either digest or version. (proof citation: rfc0008_model_form_at_boundary; verification pending)
  2. MUST — A procedure MUST declare runs naming a declared action. (proof citation: rfc0008_procedure_runs_action_resolves; verification pending)
  3. MUST_NOT — A saga step MUST NOT contain a human_gate directive. (proof citation: rfc0008_saga_step_no_human_gate; verification pending)
  4. MUST — A task MUST declare triggeredBy referencing a declared event. (proof citation: rfc0008_task_triggered_by_resolves; verification pending)
  5. 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)
  6. MUST — An action MUST NOT declare preconditions, effects, or returns directly. (proof citation: rfc0008_action_no_inline_pre_post; verification pending)
  7. MUST — The LSP MUST switch language mode at the script lang { boundary. (proof citation: rfc0008_lsp_switches_at_boundary; verification pending)

Manifest Files

  1. MUST — All .gnm files in a concept folder MUST belong to the same gnomon module. (proof citation: rfc0008_concept_folder_same_module; verification pending)
  2. MUST_NOT — The compiler block MUST NOT appear in individual .gnm files. (proof citation: rfc0008_compiler_block_not_in_module_files; verification pending)
  3. 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

  1. 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)
  2. MUST — File names MUST conform to NAME (lowercase, RFC 1123 label, max 63 chars). (proof citation: rfc0008_file_names_conform; verification pending)
  3. MUST_NOT — meaning fields MUST NOT contain code, type names, or implementation references. (proof citation: rfc0008_meaning_no_code; verification pending)

Normative EBNF Grammar

  1. MUST — Each non-trivial production MUST have at least one parse fixture. (proof citation: rfc0008_production_has_fixture; verification pending)
  2. MUST — Implementations MUST parse conforming .gnm files and reject non-conforming files with location-aware diagnostics. (proof citation: rfc0008_parse_or_reject; verification pending)
  3. MUST — The grammar MUST be expressible as a PEG grammar without modification. (proof citation: rfc0008_grammar_expressible_as_peg; verification pending)

Project Layout

  1. MUST_NOT — Tooling MUST NOT recognize or scaffold any other layout. (proof citation: rfc0008_tooling_no_other_layout; verification pending)
  2. MUST — Tooling MUST support the canonical module-based layout. (proof citation: rfc0008_tooling_supports_canonical_layout; verification pending)

Scope

  1. MUST — All Gnomon source files use the .gnm extension. (proof citation: rfc0008_gnomon_extension; verification pending)

Security and Authorization

  1. MUST — Agent capability declarations MUST be reviewed and explicitly approved before deployment. (proof citation: rfc0008_agent_capabilities_approved; verification pending)
  2. 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)
  3. 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

  1. MUST — Doc comment content MUST be CommonMark prose. (proof citation: rfc0008_doc_comments_are_commonmark_prose; verification pending)

Unified Declaration Model

  1. MUST_NOT — A module MUST NOT define the same canonical path in two source files. (proof citation: rfc0008_canonical_path_unique; verification pending)
  2. 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

  1. MAY — A declaration MAY carry at most one epistemic modifier. (proof citation: rfc0008_at_most_one_epistemic_modifier; verification pending)
  2. 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)
  3. MUST_NOT — The compiler MUST NOT export internal declarations in the compiled bundle. (proof citation: rfc0008_compiler_no_internal_export; verification pending)
  4. MUST_NOT — draft declarations MUST NOT appear in a compiled bundle with ciState: ready.

Linked References

DirectionTarget
Extended byRFC-0011