RFC-0000 · 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-0000: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0000.This page is generated from the
lean/Gnomon/Spec/module for RFC-0000. Edit that source and regenerate this catalog.
Title: Terminology and Normative Conventions
Status: draft
Owners: Architecture/Docs
Proof citations in source: 13 / 13. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| AI Authoring Agent | An AI model assisting with module declaration authoring via MCP tools; trust level Medium. |
| AI Runtime Agent | A declared agent (RFC-0009) executing within a running Gnomon application; trust level Constrained. |
| Action type | A typed, authorizable operation that an actor may perform on domain objects (RFC-0006 §4.4). |
| Actor | A named role declaration that identifies a category of principal authorized to perform specific actions; multiple humans or AI runtime agents may fulfill the same actor role; System is the sole built-in reserved actor. |
| Agent | A declared AI actor with explicit capability scope, evidence obligations, and authorization boundaries (RFC-0009). |
| Aspect | A cross-cutting structural contribution mechanism that pushes structure or behavior into target kinds. |
| Authoring format | Source declarations authored by humans; all source files use the .gnm extension. |
| Claim | Evidence-typed field wrapper carrying value, confidence, epistemic status, source, and provenance (RFC-0006 §4.5). |
| Command | Synonym for action in composition and LSP sections; an action declaration defines a typed, authorizable command. Prefer action in new writing. |
| Compiled format | Deterministic output produced by compile pipeline and consumed by install pipeline. |
| Composition | Runtime assembly of route -> page -> layout -> widget surfaces; the execution-layer result of compiling view declarations. |
| Edge-gnomon | Relationship element with subject/predicate/object. |
| Epistemic status | The trust posture of an gnomon field value: one of asserted, observed, inferred, estimated, predicted, disputed, superseded. |
| EvidenceType | The declared category of evidence supporting a Claim |
| Facet | The collective term for semantic facets and presentation facets; prefer the specific term when unambiguous. |
| FlowType | A declaration kind (flow) that defines a named state machine: states, transitions, guards, and trigger actions; entity types reference a FlowType via the flow property. |
| 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. |
| Human Author | A person writing or reviewing module declarations via CLI, IDE, or authoring UI; trust level High. |
| Install Operator | The identity (human or CI system) that executes install plan apply operations; trust level High. |
| Install plan | A computed diff from declared state to installed state. |
| Kernel | The compiled Rust/WASM component that owns state reduction, invariant enforcement, and event commitment (RFC-0010 §5). |
| Kind | An operational classifier used for dispatch, constraints, and indexing. |
| MCP Client | Any process invoking Gnomon via the MCP protocol surface; trust derived from authenticated identity. |
| Module | A namespaced declaration unit with imports, exports, objects, and metadata. |
| Object-gnomon | Vertex-like element, persisted in resource storage. |
| Path | Canonical fully-qualified identity path. |
| Presentation facet | A UI grouping mechanism that organizes already-composed fields into named sections for rendering (RFC-0004 §6). |
| Principal | Any entity that may initiate operations in the system; RFC-0000 §9 defines the canonical taxonomy. |
| Query | A read-only operation that composes compute declarations without side effects; it MUST NOT produce state transitions, emit events, or write to any gnomon instance. |
| Runtime User | An end-user interacting with a running Gnomon application; trust level Low. |
| Semantic facet | A reusable meaning module composed additively into entity types; it carries domain rules, constraints, and AI permissions (RFC-0006 §4.2). |
| Storage manifest | Compiler-generated artifact enumerating all DDL objects required for a module’s gnomon kinds (RFC-0002 §7). |
| System | Internal automated processes acting within a declared workflow (e.g., state machine transitions); trust level Scoped. |
| View | A semantic authoring declaration at Layer 0 that compiles into composition execution elements (RFC-0008). |
Diagnostics
(none introduced)
Invariants
- A design surface is closed when normative statements are unambiguous, terms defined, contradictions resolved, deferred items owned, and diagnostic codes allocated.
- A lower-trust principal MUST NOT perform operations reserved for a higher-trust principal regardless of how the request is routed.
- A process claiming System trust for an operation not covered by a declared workflow MUST be rejected.
- Agent-initiated mutations via MCP MUST be policy-authorized under the same constraints as human-initiated operations.
- An AI Authoring Agent MUST NOT apply its own proposals without a Human Author approval step 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 unauthenticated MCP Client MUST be treated as having no trust.
- Diagnostic codes use M
with each RFC owning a 1000-code range; R prefix is reserved for runtime-emitted diagnostics. (enforced by: compile-time) - Each RFC MUST NOT emit codes outside its allocation; code meanings are stable across compiler versions absent a major version bump; retired codes MUST NOT be reused. (enforced by: governance)
- Each RFC MUST include Scope, Invariants, Data contract, Resolution/evaluation rules, Failure modes and diagnostics, Security and authorization considerations, and Compatibility and migration.
- Each principal class has explicit per-class audit logging requirements, including identity, model ID, plan fingerprint, or workflow ID as applicable.
- MCP interfaces MUST NOT introduce non-deterministic behavior relative to equivalent CLI execution for identical inputs.
- MCP servers MUST preserve diagnostic fidelity, including code, severity, and source mapping.
- MCP-driven rollback requests MUST honor forward-only policy constraints.
- MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are the normative keywords used across the RFC suite.
- Outstanding and resolved design questions MUST be tracked in a per-RFC QA.md file rather than an Open Questions section.
- Per-RFC security sections MUST reference the RFC-0000 §9 principal taxonomy rather than defining their own; unlisted principals MUST NOT be granted trust implicitly.
- When specifications disagree, precedence is dependency docs, then RFC normative statements, then phase/track docs, then review notes.
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Canonical Terms
- MUST_NOT — Queries MUST NOT produce state transitions, emit events, or write to any gnomon instance.
Diagnostic Code Allocation Policy
- MUST_NOT — A retired diagnostic code MUST NOT be reused.
- MUST — Code meanings MUST be stable across compiler versions unless a major version bump occurs. (proof citation:
rfc0000_b30_grounded; verification pending) - MUST_NOT — Each RFC MUST NOT emit diagnostic codes outside its allocated prefix range.
- MUST — Legacy short-form diagnostic codes MUST be treated as aliases for their long-form equivalents during the migration period.
- MUST — New diagnostic codes MUST use the long-form M
<3-digit> format.
MCP Integration Contract
- MUST — Agent-initiated mutations MUST be policy-authorized under the same constraints as human-initiated operations. (proof citation:
rfc0000_b12_grounded; verification pending) - MUST — Execution tools MUST enforce authorization boundaries from RFC-0005 before applying mutations. (proof citation:
rfc0000_b16_grounded; verification pending) - MUST_NOT — MCP interfaces MUST NOT introduce non-deterministic behavior relative to equivalent CLI execution for identical inputs.
- MUST — MCP servers MUST preserve diagnostic fidelity (code, severity, source mapping). (proof citation:
rfc0000_b10_grounded; verification pending) - MUST — Mutation tools MUST return structured diagnostics. (proof citation:
rfc0000_mutation_tools_structured_diagnostics; verification pending) - MUST — Planning tools MUST return deterministic operation ordering metadata.
- MUST_NOT — Prompt surfaces MUST NOT bypass schema or policy validation. (proof citation:
rfc0000_prompt_surfaces_no_bypass; verification pending) - MUST — Resource identity paths MUST align with canonical path conventions in this suite.
Required RFC Structure
- MUST — Each RFC MUST include Scope, Invariants, Data contract, Resolution/evaluation rules, Failure modes and diagnostics, Security and authorization considerations, and Compatibility and migration.
- MUST — Outstanding and resolved design questions MUST be tracked in QA.md rather than in the RFC document.
Security Principal Taxonomy
- MUST — A System principal claiming trust for an operation not covered by a declared workflow MUST be rejected. (proof citation:
rfc0000_system_trust_requires_workflow; verification pending) - MUST_NOT — A lower-trust principal MUST NOT perform operations reserved for a higher-trust principal, regardless of routing. (proof citation:
rfc0000_b20_grounded; verification pending) - MUST_NOT — An AI Authoring Agent MUST NOT apply its own proposals without a Human Author approval step preserved in the audit log. (proof citation:
rfc0000_ai_authoring_needs_human_approval; verification pending) - MUST_NOT — An AI Runtime Agent MUST NOT escalate its own permissions by authoring new action or agent declarations at runtime. (proof citation:
rfc0000_ai_runtime_no_self_escalation; verification pending) - MUST — An unauthenticated MCP Client MUST be treated as having no trust. (proof citation:
rfc0000_unauthenticated_no_trust; verification pending) - MUST_NOT — Any principal not listed in the taxonomy MUST NOT be granted trust implicitly. (proof citation:
rfc0000_b26_grounded; verification pending) - MUST — Per-RFC security sections MUST reference this principal taxonomy rather than defining their own principal models. (proof citation:
rfc0000_principal_taxonomy_canonical; verification pending)
Linked References
(no cross-RFC dependencies)