RFC-0000 · Terminology and Normative Conventions
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: Architecture/Docs
1. Normative Language
The following keywords are normative:
- MUST: absolute requirement
- MUST NOT: absolute prohibition
- SHOULD: recommended unless strong reason not to
- SHOULD NOT: discouraged unless strong reason to
- MAY: optional
2. Canonical Terms
| Term | Definition |
|---|---|
| Gnomon | A declarative, schema-first framework for building AI-augmented applications. Authors define domain types, business rules, lifecycles, and AI agent contracts in .gnm source files; the compiler produces deterministic artifacts that install, enforce, and evolve safely in production. Named after the Greek concept of unbound time — reflecting the framework’s emphasis on temporal provenance, bitemporal storage, and long-lived correctness. |
| Object-gnomon | Vertex-like element, persisted in resource storage |
| Edge-gnomon | Relationship element with subject/predicate/object |
| Module | Namespaced declaration unit with imports, exports, objects, and metadata |
| Authoring format | Source declarations authored by humans; all source files use the .gnm extension |
| Compiled format | Deterministic output produced by compile pipeline and consumed by install pipeline |
| Install plan | Computed diff from declared state to installed state |
| Composition | Runtime assembly of route -> page -> layout -> widget surfaces; the execution-layer result of compiling view declarations |
| View | Semantic authoring declaration (Layer 0) that compiles into composition execution elements; defined in RFC-0008 |
| Aspect | Cross-cutting structural contribution mechanism that pushes structure or behavior into target kinds |
| Semantic facet | Reusable meaning module composed additively into entity types; carries domain rules, constraints, and AI permissions (RFC-0006 §4.2) |
| Presentation facet | UI grouping mechanism that organizes already-composed fields into named sections for rendering (RFC-0004 §6) |
| Facet | Collective term covering both semantic facets and presentation facets; context determines which sense applies — prefer the specific term where unambiguous |
| Kind | Operational classifier used for dispatch, constraints, and indexing |
| Path | Canonical fully-qualified identity path |
| Claim | Evidence-typed field wrapper carrying value, confidence, epistemic status, source, and provenance (RFC-0006 §4.5) |
| Epistemic status | The trust posture of an gnomon field value: one of asserted, observed, inferred, estimated, predicted, disputed, superseded |
| Action type | A typed, authorizable operation that an actor may perform on domain objects (RFC-0006 §4.4) |
| Agent | A declared AI actor with explicit capability scope, evidence obligations, and authorization boundaries (RFC-0009) |
| Principal | Any entity that may initiate operations in the system; see §9 for the canonical principal taxonomy |
| Storage manifest | Compiler-generated artifact enumerating all DDL objects required for a module’s gnomon kinds (RFC-0002 §7) |
| Kernel | The compiled Rust/WASM component that owns state reduction, invariant enforcement, and event commitment (RFC-0010 §5) |
| Actor | A named role declaration (actor Client, actor Advisor) that identifies a category of principal authorized to perform specific actions. Multiple humans or AI runtime agents may fulfill the same actor role at runtime. System is the sole built-in reserved actor representing the Gnomon runtime itself; it requires no actor declaration. Actor declarations are authored in .gnm files (RFC-0008 §6.x). |
| FlowType | A declaration kind (flow) that defines a named state machine: a set of named states, transitions between them, guards, and trigger actions. Entity types reference a FlowType via the flow property to attach lifecycle semantics. Defined in RFC-0008 §8.8 and RFC-0006 §4.6. |
| EvidenceType | The declared category of evidence supporting a Claim<T> field. Evidence types are strings identifying the origin of the value (e.g. "user-provided", "model-inferred", "regulatory-lookup"). Implementations MAY define additional evidence type registries. |
| Command | Synonym for action used in some RFC sections and in the composition model (RFC-0003). An action declaration defines a typed, authorizable command that an actor may invoke. Prefer action in new writing; command appears in composition and LSP sections for historical reasons. |
| Query | A read-only operation declaration that returns computed data without modifying state. A query composes compute declarations and has no side effects. Queries are declared in Operations-class files (RFC-0001 §4.1) and are listed in the operations section of module.gnm. Unlike action declarations, queries MUST NOT produce state transitions, emit events, or write to any gnomon instance. |
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. Canonical Precedence
When specification documents disagree, precedence is:
- Dependency and sequencing rules in canonical dependency docs
- RFC normative statements in this suite
- Phase/track docs
- Review summaries and panel notes
4. Framework Purpose
Gnomon is intended to serve as a next-generation no-code/low-code framework where AI is a first-class authoring and operations participant under explicit contracts.
Its core design commitments are:
- Declarative authoring contracts that remain human- and agent-authorable
- Deterministic compilation and install behavior for reproducibility and audit
- Embedded semantic structure via typed graph identities and relationships
- Secure-by-default lifecycle controls for authorization, rollback, and provenance
- Explicit diagnostics and governance surfaces suitable for policy review
5. Required RFC Structure
Each RFC in this suite MUST include:
- Scope
- Invariants
- Data contract
- Resolution/evaluation rules
- Failure modes and diagnostics
- Security and authorization considerations
- Compatibility and migration
Design questions and their resolutions are maintained in the accompanying QA.md file for each RFC. The “Open questions” section is no longer a required part of the RFC document structure; outstanding and resolved design questions MUST be tracked in QA.md instead.
6. Diagnostic Code Allocation Policy
Diagnostic codes are stable identifiers used in compiler output and audit logs.
6.1 Code Format
All diagnostic codes use the format M<RFC-id><local-code> where:
Mis the fixed prefix for module/compiler diagnostics<RFC-id>is the two-digit zero-padded RFC number (e.g.,01for RFC-0001)<local-code>is a three-digit zero-padded local code within that RFC’s allocation
This yields codes of the form M01xxx. Each RFC owns a range of 1000 codes (M01000–M01999 for RFC-0001, etc.), giving ample room for growth without collision.
R prefix codes (Rxxxxx) are reserved for runtime-emitted diagnostics not tied to a specific compile-time RFC.
6.2 Allocation Table
| RFC | Prefix | Range | Owner |
|---|---|---|---|
| RFC-0001 | M01 | M01000–M01999 | Module Authoring Format |
| RFC-0002 | M02 | M02000–M02999 | Compiled Bundle Format |
| RFC-0003 | M03 | M03000–M03999 | Composition Model |
| RFC-0004 | M04 | M04000–M04999 | Aspects and Facets |
| RFC-0005 | M05 | M05000–M05999 | Module Lifecycle |
| RFC-0006 | M06 | M06000–M06999 | Semantic Type Model |
| RFC-0007 | M07 | M07000–M07999 | Gnomon Primitive |
| RFC-0008 | M08 | M08000–M08999 | Language Authoring Surface |
| RFC-0009 | M09 | M09000–M09999 | AI Participation Contract |
| RFC-0010 | M10 | M10000–M10999 | Canonical IR and Runtime |
| RFC-0011 | M08 | M08770–M08778 | Annotation System (subrange of RFC-0008 allocation; see RFC-0011 §8) |
| RFC-0012 | F12 | F12700–F12899 | Tooling / Formatter (F-prefix, not M-prefix) |
| RFC-0013 | M13 | M13000–M13999 | Test Execution Model |
| RFC-0014 | M14 | M14000–M14999 | Module Versioning Protocol |
| RFC-0015 | M15 | M15000–M15999 | Agent Runtime Binding |
| RFC-0016 | M16 | M16000–M16999 | Schema Migration |
| RFC-0014 | L014 | L01400–L01499 | Module Versioning Protocol lint codes: L01400 (breaking change published as MINOR), L01401 (non-breaking change published as MAJOR) |
| RFC-0017 | L00 | L00000–L00999 | LSP Contract (L-prefix for LSP codes) |
| RFC-0018 | M18 | M18000–M18999 | Compiler Services |
| RFC-0019 | M19 | M19000–M19999 | Module Registry Protocol |
| RFC-0020 | M20 | M20000–M20999 | Reactive Query and Subscriptions |
| RFC-0021 | M21 | M21000–M21999 | Transform Expression Language |
| RFC-0022 | M22 | M22000–M22999 | Multi-Agent Workflow Orchestration |
| RFC-0023 | M23 | M23000–M23999 | Gnomon Studio |
| RFC-0024 | M24 | M24000–M24999 | IO Operations Primitive |
| RFC-0025 | M25 | M25000–M25999 | IO HTTP Binding |
| RFC-0026 | M26 | M26000–M26999 | IO gRPC Binding |
| RFC-0027 | M27 | M27000–M27999 | IO GraphQL Binding |
| RFC-0028 | M28 | M28000–M28999 | IO OpenAPI Adapter |
| RFC-0029 | M29 | M29000–M29999 | IO tRPC Adapter |
| RFC-0030 | M30 | M30000–M30999 | IO Protobuf Adapter |
| RFC-0031 | M31 | M31000–M31999 | IO GraphQL Introspection Adapter |
| RFC-0032 | M32 | M32000–M32999 | Rules/Bazel |
| RFC-0033 | M33 | M33000–M33999 | API Service Declaration |
| RFC-0034 | M34 | M34000–M34999 | Protocol Server Bindings |
| Runtime | R00 | R00000–R00999 | Runtime Platform |
6.3 Migration from Legacy Short Codes
Existing RFCs currently use the short-form codes (e.g., M0001, M0100). These MUST be treated as aliases for their long-form equivalents during the migration period:
M000x→M01000series (RFC-0001)M010x→M02000series (RFC-0002)M020x→M03000series (RFC-0003)M030x→M04000series (RFC-0004)M040x→M05000series (RFC-0005)
New codes introduced after this revision MUST use the long-form M<RFC-id><3-digit> format. Existing short-form codes remain valid until a major version increment formalizes the rename.
6.4 Governance Rules
- Each RFC owns its prefix range and MUST NOT emit codes outside it
- Code meanings MUST be stable across compiler versions unless a major version bump occurs
- The allocation table in §6.2 is the authoritative registry; per-RFC diagnostic sections document the codes within each allocation
- Changing the meaning or severity of an existing code requires major version increment
- Retiring a code requires marking it deprecated with the version it was retired; the code MUST NOT be reused
7. Design Closure Criteria
A design surface is considered closed when:
- Normative statements are unambiguous
- Terms are defined in this glossary or the RFC itself
- Contradictions with other RFCs are resolved
- Deferred items have explicit ownership and trigger conditions
- Diagnostic codes (if emitted) are allocated per §6 and documented
8. MCP Integration Contract (Normative)
The Model Context Protocol (MCP) is the canonical machine interface for AI-assisted authoring and lifecycle operations in this RFC suite.
MCP surface expectations:
- Tools
- Mutation tools MAY create/update module declarations and MUST return structured diagnostics.
- Planning tools MAY generate install plans and MUST return deterministic operation ordering metadata.
- Execution tools MUST enforce authorization boundaries from RFC-0005 before applying mutations.
- Resources
- RFC text, module declarations, compiled bundles, diagnostics payloads, and install plans SHOULD be addressable as MCP resources.
- Resource identity paths MUST align with canonical path conventions in this suite.
- Prompts
- Prompt surfaces MAY provide guided authoring templates but MUST NOT bypass schema or policy validation.
- Events
- Compile/install events SHOULD emit diagnostics and state transitions in machine-readable form.
Security and governance requirements for MCP-driven operations:
- Agent-initiated mutations MUST be policy-authorized under the same constraints as human-initiated operations.
- MCP servers MUST preserve diagnostic fidelity (code, severity, source mapping).
- MCP-driven rollback requests MUST honor forward-only policy constraints.
- MCP interfaces MUST NOT introduce non-deterministic behavior relative to equivalent CLI execution for identical inputs.
9. Security Principal Taxonomy (Normative)
This section defines the canonical set of principals recognized across the RFC suite. Per-RFC security sections MUST reference this taxonomy rather than defining their own principal models. Any principal not listed here MUST NOT be granted trust implicitly.
9.1 Principal Definitions
| Principal | Description | Trust level |
|---|---|---|
| Human Author | A person writing or reviewing module declarations via CLI, IDE, or authoring UI | High |
| AI Authoring Agent | An AI model assisting with module declaration authoring via MCP tools | Medium |
| Install Operator | The identity (human or CI system) that executes install plan apply operations | High |
| AI Runtime Agent | A declared agent (RFC-0009) executing within a running Gnomon application | Constrained |
| Runtime User | An end-user interacting with a running Gnomon application | Low |
| MCP Client | Any process invoking Gnomon via the MCP protocol surface | Derived |
| System | Internal automated processes acting within a declared workflow (e.g., state machine transitions) | Scoped |
Trust levels:
- High: May initiate lifecycle operations, install plans, and breaking changes. Subject to audit.
- Medium: May propose authoring changes. All proposals require human review before activation.
- Constrained: Permissions are fully enumerated in agent declaration. No implicit capabilities.
- Low: May invoke declared commands within their authorization scope. Cannot modify declarations or plans.
- Derived: Inherits trust from the authenticated identity behind the MCP connection.
- Scoped: May perform only operations explicitly declared in the workflow definition; no ad hoc capabilities.
Trust levels form the following partial order (higher listed first): High > Medium > Derived > Constrained > Low > Scoped. “Higher-trust” in §9.3 means higher in this ordering.
9.2 Cross-RFC Trust Boundaries
| Operation | Minimum required principal | RFC reference |
|---|---|---|
| Author or modify module declarations | Human Author | RFC-0001 §7 |
| AI-assist authoring (propose changes) | AI Authoring Agent | RFC-0009 §6 |
| Generate install plan | Install Operator or MCP Client | RFC-0005 §5 |
| Apply install plan (DDL execution) | Install Operator | RFC-0005 §8, RFC-0002 §7 |
| Activate an AI runtime agent | Install Operator | RFC-0009 §7, RFC-0005 §5 |
| Execute a declared action | Runtime User or AI Runtime Agent | RFC-0006 §4.4 |
| Write a Claim field | Any; epistemic status must reflect origin | RFC-0006 §4.5 |
| Approve AI-produced draft | Human Author or Runtime User | RFC-0009 §4.5, §4.9 |
| Trigger state transition | As declared in FlowType transitions | RFC-0006 §4.6 |
| Rollback an install plan | Install Operator | RFC-0005 §7 |
9.3 Principal Escalation Rules
- A lower-trust principal MUST NOT perform operations reserved for a higher-trust principal, regardless of how the request is routed.
- An AI Authoring Agent MUST NOT apply its own proposals without a Human Author approval step. The approval record MUST be preserved in the audit log.
- An AI Runtime Agent MUST NOT escalate its own permissions by authoring new action declarations or agent declarations at runtime.
- An MCP Client derives its trust from its authenticated backing identity. An unauthenticated MCP Client MUST be treated as having no trust.
- System principals MUST be declared in workflow definitions. A process claiming System trust for an operation not covered by a declared workflow MUST be rejected.
9.4 Audit Requirements by Principal
| Principal | Audit requirement |
|---|---|
| Human Author | All declaration mutations logged with identity and timestamp |
| AI Authoring Agent | All proposals logged with model ID, version, and human approval record |
| Install Operator | All install plan apply operations logged with plan fingerprint |
| AI Runtime Agent | All action executions logged with agent ID, inputs, outputs, confidence |
| Runtime User | Command invocations logged at the policy-configured granularity |
| System | All automated transitions logged with workflow ID and trigger event |