RFC-0006 · Semantic Type Model
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: Semantic Core, Module Architecture
1. Scope
Defines the semantic type system that underlies Gnomon’s authoring model. Where RFC-0001 defines the authoring format and RFC-0004 defines aspects and facets, this RFC defines the meaning layer that those formats encode: the value type hierarchy (§4.A), the declaration kind taxonomy (§4.B), composition rules, and the evidence/uncertainty system that makes the model AI-native.
This RFC is the foundational reference for what concepts an Gnomon module is allowed to declare and how those concepts compose. It is not the authoring surface syntax (see RFC-0008) nor the runtime storage model (see RFC-0007).
2. Goals
- Provide a meaning-first, compositional type model understandable by non-technical domain authors
- Make uncertainty and evidence first-class so AI-generated data is structurally differentiated from human-entered or system-verified data
- Type operations (actions), not just data, so that AI actor permissions are enforceable at the model layer
- Support monotone refinement so state transitions are auditable and unidirectional by default
- Keep the declaration kernel small and compositional; all domain concepts derive from declared declaration kinds (§4.B)
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. Invariants
- Every domain concept MUST be declared as one of the declared declaration kinds (see §4.B).
- Facet composition MUST NOT use inheritance chains; composition is strictly additive via
includes. - A
Claim<T>wrapper MUST accompany any field that may be produced by an AI actor. - State transitions MUST be monotone by default: a state MAY be refined to a more specific state but MUST NOT regress silently.
- An
actiondeclaration MUST exist for each action an AI actor is permitted to perform; absence of a declaration MUST imply prohibition. - Every declared kind MUST carry a
meaningfield sufficient for a non-technical domain author to understand it without reading code. - Null is not a value. The Gnomon type system has no null type, no nullable type modifier, and no null literal. Every field that is present in a record carries a non-null value of its declared type. Absence of an optional field is represented as “not present” — never as a null-valued present field. At serialization boundaries (inbound JSON from external APIs and incoming HTTP/gRPC requests), null values are coerced per the null-boundary policy in §4.D.
4. Type System and Declaration Kinds
§4.A — Value Type Hierarchy
A value type is a type that a field declaration may use. The complete value type hierarchy is rooted at Value:
Value
├── Scalar
│ ├── Text
│ ├── Integer
│ ├── Decimal
│ ├── Boolean
│ ├── Date
│ ├── Timestamp
│ ├── Money
│ ├── Currency
│ ├── URL
│ ├── USState
│ ├── Identifier
│ └── Unit (the singleton "no value" type; see below)
├── Composite
│ ├── List<T> where T : Value
│ ├── Map<K, V> where K : Scalar, V : Value
│ ├── Claim<T> where T : Value
│ └── variant (a discriminated union; declared with the `variant` keyword)
├── Reference
│ └── (any declared entity name, used as a field type — resolved as an Identifier at storage)
└── Opaque
└── JSON
Root: Value
Value is the implicit root of the value type hierarchy. It is abstract and not writable by authors as a field type — field: Value is error M06020 (“use a specific value type”). It exists to give the spec a complete noun for “anything a field may be typed as” and to give test assertions a term for type reflection.
Naming convention: Value types in the spec are referred to by their keyword or type name, with no suffix. The spec MUST NOT use the form XxxType to refer to value types (e.g., use Claim<T>, not “ClaimType”; use variant, not “VariantType”). The Type suffix is reserved for user-declared enum types (declarations using the type keyword).
JSON as Opaque:
JSON is a valid Value but opts out of structural value validation. It is always valid syntactically and never validated structurally; other compiler rules, including the AI wrapper requirement, still apply. During import preflight, the compiler MUST produce warning M06530 for an unannotated JSON field on an entity produced by a declared AI agent (see §4.5 stages). The warning does not permit publication of an unwrapped AI field (M06520). Authors SHOULD treat JSON as a temporary escape hatch, not a permanent design.
variant as Composite:
A variant declared with the variant keyword produces a named value type in the Composite branch. The resulting type is a valid field type on any entity. It is not itself an entity, has no primary key, and cannot be queried directly. Its place in the Composite branch signals that the compiler resolves which shape applies at read/write time based on the discriminator.
Unit:
Unit is the singleton scalar type with exactly one value: (). It is used as the return type of operations that produce no meaningful output — analogous to void in procedural languages but composable as a type argument (e.g., Claim<Unit> is valid). Unit is a valid returns: type on operation, query, mutation, and transform declarations. It is NOT a valid field type on an entity (field: Unit is error M06024).
The Unit type is defined in the core module and does not require an import. Authors MUST use Unit rather than void — the keyword void is not defined in the Gnomon type system.
Map<K, V>:
A Map<K, V> associates keys of a Scalar type K to values of any Value type V. Keys are always unique within a map. The Text and Identifier scalar types are the most common key types. Map members are never null — an absent key simply produces no entry, not a null-valued entry.
Reference branch:
When a field is typed as a declared entity name (e.g., field: Household), the compiler treats this as a Reference — an Identifier at storage that the runtime resolves to the named entity. This is distinct from embedding the entity’s fields. An unresolvable reference (the named entity is not declared in scope) is error M06021.
No null values:
No type in the Gnomon hierarchy is nullable. An optional field that has not been assigned is “not present” — the runtime represents this as the absence of the key, not as a null value. List members, map values, and reference targets are always non-null if present. See §4.D for how null arriving at an API boundary is handled.
Compiler validation rules:
- A field typed as
Value(the root) is error M06020 - A field typed as a declaration kind name (e.g.,
field: action) is error M06022 — declaration kinds are not value types - A field typed as a declared entity name resolves as a
Reference; the named entity MUST be declared in scope (error M06021 if not) - The identifier
JSONis reserved as theOpaquevalue type; user declarations MUST NOT use it as a type or entity name (error M06023) - A field typed as
Unitis error M06024 —Unitis only valid as a return type, not a field type
Diagnostic codes:
M06020— field typed asValue(abstract root; use a specific value type)M06021— field typed as entity name not declared in scopeM06022— field typed as a declaration kind (declaration kinds are not value types)M06023— user declaration uses reserved nameJSONM06024— field typed asUnit(Unit is a return type only, not a field type)
§4.B — Declaration Kind Taxonomy
A declaration kind is a syntactic form that produces a named artifact in the semantic graph. Declaration kinds are not value types; no field may be typed as a declaration kind.
| Declaration kind | Produces | Declaration class |
|---|---|---|
entity | A named structured type with identity | Schema |
type | A named enumeration value type | Schema |
variant | A named discriminated union value type | Schema |
flow | A named lifecycle state machine | Schema |
invariant | A named constraint on an entity | Schema |
facet | A named set of fields to be composed into entities | Schema |
mutation | Named transactional state change | Schema |
compute | Named pure derived value | Schema |
claim | Named evidence-wrapper type declaration (Claim<T> alias) | Schema |
extend | Cross-module facet contribution to an entity | Schema |
action | Composition of mutations + event emission | Operations |
actuator | Event-driven side-effect handler | Operations |
event | Named domain event with typed fields | Operations |
procedure | API binding: auth + action delegation | Operations |
query | A named read operation | Operations |
task | A named background computation | Operations |
integration | A named external push protocol | Operations |
client | A named outbound API contract | Operations |
workflow | A named multi-agent orchestration process with human gates (RFC-0022) | Operations |
saga | A named multi-step fallible external API saga with compensation | Operations |
api | A named protocol-agnostic public service surface (RFC-0033) | Operations |
serve | A named protocol binding that maps an api to wire endpoints (RFC-0034) | Operations |
relation | A named association between entities | Relations |
policy | A named access control rule | Governance |
agent | A named AI participant | Governance |
compose | A named composition of governance declarations | Governance |
transform | A named pure data migration function — maps entity instances at one version to another (RFC-0016) | Migrations |
migration | A named schema + data evolution step with forward and rollback paths (RFC-0016) | Migrations |
app | A named product surface | Surface |
view | A named projected entity shape | Surface |
test | A named assertion | Tests |
Naming convention: Declaration kinds in the spec are referred to by their keyword, not by a derived noun. The spec MUST NOT use the form XxxType or XxxGnomon to label declaration kinds (e.g., use “the task declaration”, not “TaskType”; use “the action declaration”, not “ActionType”). When a capitalized noun is needed (e.g., in table headers), use the keyword with initial cap: Entity, Action, Task, Integration.
§4.C — Fully-Qualified Name (FQN) Format
Every declaration in the Gnomon semantic graph is identified by a fully-qualified name (FQN). FQNs appear in diagnostic messages, compiler IR, Knowledge Index entries (RFC-0010 §9), migration declarations (RFC-0016), and the apply form (RFC-0008 §6.14a).
Grammar:
fqn ::= namespace "#" name member-path?
member-path ::= ("." NAME)+
namespace ::= NAME ("." NAME)*
name ::= NAME
synthetic ::= namespace "#" NAME "$" NAME
Components:
| Component | Separator | Meaning | Example |
|---|---|---|---|
namespace | . within | Dot-separated module path | org.benefits.plans |
# | — | Boundary between namespace and local name | — |
name | — | Declaration name (PascalCase or camelCase per §4.B) | Employee |
.member | . | Field, enum value, flow state, or operation parameter | .hireDate, .active, .Draft |
$SyntheticName | $ | Compiler-generated member (e.g., inline input/output structs) | $Input, $Output |
Examples:
org.benefits.plans#Employee -- entity declaration
org.benefits.plans#Employee.hireDate -- field on entity
org.benefits.plans#TierLevel.standard -- enum value
org.benefits.plans#PlanStatus.Draft -- flow state
org.benefits.plans#submitEnrollment -- action declaration
org.benefits.plans#submitEnrollment$Input -- compiler-generated inline input struct
core.errors#NotFound -- declaration in core namespace
core.governance#GDPR -- annotation facet in core
Short-form references: Within the same namespace, the namespace prefix and # separator MAY be omitted. Employee.hireDate is a valid short-form reference to org.benefits.plans#Employee.hireDate when the referencing declaration is in the same namespace. The compiler always resolves short-form references to their FQN before semantic analysis.
Reserved namespace core: The root namespace core is reserved for the Gnomon core standard library (RFC-0035). User modules MUST NOT declare a namespace beginning with core. Violations produce error M06040.
Diagnostic codes:
M06040— module namespace begins with reserved prefixcoreM06041— FQN reference cannot be resolved to a declared artifactM06042— member path segment does not name a declared member of the target declaration
§4.D — Null Handling at Serialization Boundaries
Gnomon’s type system has no null type (§3 invariant 7). However, external systems — JSON HTTP APIs, gRPC payloads, imported OpenAPI specs — may produce null values. The following policy governs how null is handled at every boundary where Gnomon touches an external system.
Inbound deserialization (external → Gnomon):
| Field cardinality | Incoming null behavior | Diagnostic |
|---|---|---|
required field | Null is treated as missing. The runtime raises a validation error (same as absent required field). | M06050 |
| Optional field | Null is coerced to field-absent. The field is treated as not present in the record. No error. | — |
List<T> member | A null element inside a list is a validation error; the list is rejected. | M06051 |
Map<K,V> value | A null map value is a validation error; the map is rejected. | M06051 |
Outbound serialization (Gnomon → external):
Absent optional fields are serialized as either key-absent or null depending on the target protocol’s convention. The serve declaration (RFC-0034) and client declaration (RFC-0024) MAY declare a nullStyle: absent | explicit-null slot to control this behavior. The default is absent (key omitted).
Adapter-imported schemas (OpenAPI, Protobuf, GraphQL): When an adapter generates operations from an external schema that declares nullable fields, the adapter MUST map those fields to optional (non-required) Gnomon fields. The nullable/non-nullable distinction in the external schema does not introduce nullability into the Gnomon type system; it only affects the required modifier on the generated input {} fields.
Diagnostic codes:
M06050— null received for arequiredfield at deserialization boundary (validation error)M06051— null element received inside aList<T>orMap<K,V>value at deserialization boundary (validation error)
4.1 Entity
The primary domain object. Represents a persistent, identifiable concept the system reasons about.
Properties:
meaning— plain-language descriptionfields— typed field declarationsincludes— zero or morefacetnames (additive composition)is— optional conceptual parent (documentation only; not an inheritance mechanism). If theisfield references an entity kind that is not declared in scope, the compiler MUST emit warning M06502.flow— optional reference to theflowdeclaration that governs this entity’s lifecycle; an entity MUST NOT reference more than oneflowexamples— one or more plain-language examples (required for non-technical authoring)
4.2 Facet
A reusable meaning module (capability or trait) that can be included in one or more entity declarations. Facets replace inheritance as the primary composition mechanism.
Properties:
meaning— plain-language description of what the facet addsrules— policy constraints that apply to all entities including this facetrequires— prerequisite fields or other facets that must be present.requires: one or more facet names that MUST already be included in the entity before this facet may be included. Absence of a required facet produces error M06503.
A facet declaration MUST NOT define new state machines or override fields already declared by the including entity.
Facet Rule Machine Semantics
rules in a facet body are not free-form prose. Each statement in a facet’s rule-block is a normative policy constraint (see the policy declaration, §4.7) that applies structurally to every entity declaration that includes the facet.
Compilation:
At compile time, each rule statement in a facet’s rules block is lifted into an anonymous invariant scoped to that facet’s inclusion. The lifted invariant is named <FacetName>.<ordinal> (e.g., Trackable.0, Trackable.1). These invariants are merged with the including entity’s own invariants in the kernel artifact (RFC-0010 §5.2).
Evaluation order:
Facet-lifted invariants are evaluated by the kernel BEFORE the entity’s own declared invariants during action precondition checking. This ensures cross-cutting constraints (e.g., from an Auditable facet) cannot be bypassed by entity-local logic.
Invariant:
A facet’s rules block MUST NOT reference fields not declared in the facet’s own body or in the requires list. References to entity-local fields that may or may not exist (depending on the including entity) MUST produce error M06504.
Diagnostic: M06504 is emitted when a facet rule references a field that is not declared in the facet or its requires list.
4.3 Relation
A first-class directed semantic link between two entity declarations. Relations are not mere foreign keys; they carry cardinality, constraints, and optionally qualifiers.
Properties:
from— source entity (declaredentityname)to— target entity (declaredentityname)meaning— description of what the relation assertscardinality—one,many, orzero-or-oneconstraints— predicates that must hold for the relation to be validqualifiers— optional additional fields attached to the edge
4.4 Action
A typed operation that composes mutation declarations and emits domain events. An action has no actor and no authorization logic — those concerns belong to the procedure declaration. The action declaration is not functions; it represents a declared unit of state change in the domain model.
Properties:
meaning— what the action doesinput— typed parametersmutations— themutationdeclarations composed into this actionafter—emitsstatements that fire after the mutations commit
Each action is independently composable and independently testable. AI actors MUST only perform procedure declarations explicitly listed in their agent declaration (see RFC-0009); the procedure layer carries authorization.
The action keyword is surfaced in RFC-0008 in scope syntax. At the runtime level (RFC-0010), an action declaration compiles to a kernel reducer and its submitted instance becomes a Command message — the runtime-layer name for a request to change state.
Note: The
effectsgrammar now lives exclusively inmutationdeclarations (see §4.4a). Anactiondeclaration MUST NOT declare aneffectsblock directly.
4.4a Mutation
A mutation is a pure, transactional, composable unit of state change. It has no actor and no authorization logic, and it does not emit events. It takes typed inputs, produces a declared set of state changes in the persistence graph, and commits them atomically.
Declaration class: Schema. A mutation SHOULD be co-located with the entities it primarily operates on.
Key properties:
meaning— what the mutation doesinput— typed parametersreturns— optional entity the mutation returns after commiteffects— the normative grammar for declaring state changes (see below)
The effects grammar is the normative language for declaring state changes. It is valid only inside mutation declarations. Supported statement forms:
Creation:
creates <Entity> [in <StateName>]
creates <Entity> for each <inputField>
Field mutation:
mutates <Entity>[.<fieldPath>]
replaces <Entity>
Deletion:
deletes <Entity>
deletes <Entity> if <condition>
deletes all <Entity> where <fieldPath> == <inputField>
State transition:
transitions <Entity> -> <StateName>
transitions <Entity> -> <StateName> if <condition>
Relation:
creates <Relation> linking <Entity> to <Entity>
deletes <Relation> between <ref> and <ref>
Conditional wrapper:
if <condition> { <effect-statement>+ }
No dispatches, sends, emits, or calls statements are valid inside a mutation effects block — those belong in the after {} block of an action or in actuator/task declarations.
Composability: A mutation is the unit of composition for action declarations. Multiple mutations composed in an action participate in a single transaction — all succeed together or all fail together.
Compiler validation rules:
- Every entity named in a
mutationeffects block MUST be declared in scope; error M06610 - A
transitions -> <StateName>statement MUST name a state declared in the entity’sflow; if the entity has noflow, error M06611 - A
creates <Entity> in <StateName>MUST name a valid initial state of the entity’s flow; error M06612 - A
mutates <Entity>.<fieldPath>MUST name a declared field; error M06613 - A
mutationeffects block containingdispatches,sends,emits, orcallsis error M06614 - A
mutationwith noeffectsblock is warning M06615 — a no-op mutation
Diagnostic codes:
M06610— effects block references entity not declared in scopeM06611—transitionsstatement on entity with no declaredflowM06612—creates in <State>names invalid or unreachable flow stateM06613—mutates <Entity>.<field>names undeclared fieldM06614— post-commit statement (dispatches,sends,emits,calls) insidemutationeffects blockM06615—mutationhas noeffectsblock (no-op, warning)
4.5 Claim<T>
Wraps a field value to carry provenance, confidence, and epistemic status. Any field that may be produced or modified by an AI actor MUST be typed as Claim<T> rather than bare T (M06520). A field extracted from a document or inferred from rules SHOULD use Claim<T> unless another normative rule requires the wrapper.
A Claim<T> carries:
value: T— the actual valuesource— origin (human input, AI model ID, import source, rule ID)confidence— numeric score or intervalasserted_by— actor identityasserted_at— timestampstatus— a value of typeClaimStatus(see below); governs the epistemic standing of the claimevidence_links— references to supporting documents or statements
Policies and action preconditions MAY use status and confidence as predicates. For example: require status(field) == confirmed or require confidence(field) > 0.85.
Note: The following examples use pseudo-notation for illustration. The normative authoring syntax for
Claim<T>fields is the.gnmDSL (RFC-0008); examples here MUST NOT be interpreted as YAML authoring syntax.
ClaimStatus Flow
The status field of every Claim<T> is governed by ClaimStatus, a normative flow declaration in the Gnomon core library module:
flow ClaimStatus {
meaning: "Epistemic standing of a Claim<T> field value."
states [
pending, // value present but not yet reviewed or confirmed
confirmed, // value has been verified by the declaring policy
disputed, // value is in question; competing evidence exists
superseded, // a newer claim has replaced this one
retracted // value was withdrawn; should not be used in decisions
]
}
Minimum required states: Every implementation MUST support pending and confirmed. The states disputed, superseded, and retracted are normative but a module MAY restrict which transitions its claims allow by declaring a subflow:
flow PlanRecommendationStatus is ClaimStatus {
meaning: "Status for AI-generated plan recommendations."
// Only allow the subset needed by this domain
states [pending, confirmed, superseded]
}
Transition authority: Who may transition a Claim<T> status is governed by policy declarations on the enclosing entity. No implicit transition authority exists. A Claim<T> field whose status has no governing policy MUST remain in pending until a policy-authorized actor transitions it.
Diagnostic: M06522 is emitted when a status value is set that is not a valid state in the claim’s governing flow.
Claim<Claim<T>> is prohibited. Nested claims — where the type parameter T is itself a Claim — MUST produce compile error M06524. Nesting claims creates structurally ambiguous provenance: the outer claim would need to assert confidence in the inner claim’s metadata (source, asserted_by, confidence), not in a domain value. This is not a meaningful epistemic operation. Authors who need to track the provenance of a claim-assertion act (e.g., “who confirmed this claim?”) MUST model that as an action with appropriate mutation effects and evidence obligations, not as a nested Claim.
Claim<T> is surfaced in RFC-0008 in two forms: the claim declaration keyword (which declares a named Claim<T> field type with its constraints) and the Claim<T> type expression (which references a declared claim type when used in field declarations).
Claim<T> Migration Stages
Imported schemas may have JSON or bare-typed fields where Claim<T> semantics are desired. The following stages describe import and preflight states. Stages 0 and 1 MUST NOT pass publication when a field may be produced or modified by an AI actor; such fields MUST reach Stage 2 or 3 before publication (M06520).
Stage 0 — Opaque: field: JSON — no epistemic typing. An AI-produced or AI-modified field fails publication with M06520; an unannotated JSON field on an AI-produced entity also produces M06530 during import preflight.
Stage 1 — Annotated: field: JSON @epistemic(inferred) — the field is still untyped but the compiler records the intended epistemic status. No runtime enforcement. M06530 is suppressed, but an AI-produced or AI-modified field still fails publication with M06520.
Stage 2 — Wrapped: field: Claim<JSON> — the field carries provenance metadata (confidence, source, assertedBy, assertedAt) but the value itself remains untyped JSON. Enforced at runtime by the gnomon storage layer.
Stage 3 — Typed: field: Claim<StructuredType> — full epistemic typing with a declared value type. This is the normative target state.
For imported schemas, Stage 0 → 1 → 2 can be prepared incrementally; the AI publication rule still requires Stage 2 or 3. Stage 2 → 3 is potentially breaking because it requires defining StructuredType, and follows RFC-0016 (Schema Migration and Evolution).
Example:
entity Proposal {
fields {
data: JSON @epistemic(inferred) // Stage 1: intent declared, not enforced
}
}
entity NextDollar {
fields {
results: Claim<JSON> // Stage 2: provenance enforced, value opaque
}
}
Compiler validation rules:
- A field that may be produced or modified by a declared AI agent without
Claim<T>MUST produce error M06520, including bareJSONand annotatedJSONfields - A bare
JSONfield on an entity produced by a declared AI agent with no@epistemicannotation MUST also produce warning M06530 during import preflight - A
Claim<JSON>field is valid and enforces provenance metadata at the storage layer - Moving from
Claim<JSON>toClaim<StructuredType>is governed by RFC-0016
Diagnostic codes:
M06530— during import preflight, AI-produced entity has bareJSONfield with no epistemic annotation (warning)M06531—@epistemicannotation on non-JSON field (useClaim<T>directly)
4.6 Flow
A named set of states and their allowed transitions for a lifecycle-bearing entity declaration. Surfaced in RFC-0008 as the flow declaration keyword.
Properties:
states— list of named state valuestransitions— allowedfrom -> topairs with actor constraintsrules— policy constraints on transitions (e.g.,ai may not transition to Approved)
Transitions MUST be monotone by default unless reversible: true is explicitly declared on the transition. Reversible transitions MUST produce audit events.
4.6a Enum
A closed set of named constant values. The enum declaration is a fundamental construct used in field declarations, policy predicates, and flow state values.
Two forms:
Top-level enum declaration — reusable, importable, referenceable by name from any field type, Claim<T> (where T is the enum), or policy rule:
enum BenefitKind {
meaning: "The category of benefit a plan provides."
values [medical_plan, dental_plan, vision_plan, hsa, fsa, hra]
}
Fields reference it by name: benefitType: BenefitKind. The compiler verifies that all assigned values are declared members.
Inline anonymous enum — scoped to the current field declaration; not referenceable by name from other declarations:
entity Bundles {
status: enum { pending, ready, selected, expired }
}
Inline enums are purely local. If the same set of values is used in more than one declaration, authors SHOULD promote it to a top-level enum.
Invariants:
- Enum value names MUST be
lower_snake_caseIDENT tokens. - An enum MUST contain at least two values.
- Inline enum values are not referenceable outside their enclosing declaration.
- Top-level enums MUST have a
meaningproperty (required, likefacet). - Changing or removing values from a published
enumis a breaking change per RFC-0014.
4.7 Policy
A constraint or permission rule that applies to one or more entity, facet, or action declarations. Surfaced in RFC-0008 as the policy declaration keyword.
Properties:
applies to— selectors for targeted kinds, facets, or actionsrules— one or more declarative constraint statementsenforcement—hard(violation is a runtime error) orsoft(violation is a diagnostic/warning)
4.8 Declaration-to-Language-Surface Mapping
Declaration kinds map to RFC-0008 authoring keywords as follows. All language keywords compile to one of these declaration kinds in the canonical IR (RFC-0010).
| RFC-0006 declaration | RFC-0008 entity-syntax keyword | RFC-0008 scope-syntax keyword |
|---|---|---|
entity | entity | entity |
facet | facet | — |
relation | relation | — |
mutation | mutation | — |
action | — | action |
procedure | — | procedure |
actuator | — | actuator |
event | — | event |
task | — | task |
compute | compute | — |
Claim<T> | claim | — |
flow | flow | — |
policy | policy | policy (inline in policy blocks) |
enum | enum (top-level) or inline enum { } on a field | — |
Implementor note —
typevsenum: The §4.B declaration kind taxonomy liststypeas producing “a named enumeration value type.” In the RFC-0008 authoring surface, this declaration kind is surfaced exclusively as theenumkeyword (both top-level and inline forms, as described in §4.6a). The keywordtypedoes not appear in the RFC-0008 grammar. The §4.B label “named enumeration value type” and the §4.6a/§4.8enumkeyword refer to the same semantic construct; implementors MUST treat them as identical. Thetypelabel in §4.B is retained for conceptual clarity in the declaration kind taxonomy only.
4.9 Non-Primitive Language Constructs
The following RFC-0008 keywords do not correspond to a semantic type primitive. Each derives from the primitive model or a complementary RFC as described:
| Language keyword | Derives from | Normative reference |
|---|---|---|
agent | Participation contract (not a semantic type) | RFC-0009 |
invariant | Named, parametric form of policy constraint rules; referenceable from action mustSatisfy | RFC-0006 §4.7 |
query | Named read accessor over the gnomon query API; compiles to gnomon.find() / gnomon.resolve() | RFC-0007 §7 |
view | Named projection for UI consumption; compiles to route/page/layout/widget | RFC-0007 §5.3, RFC-0003 §5a |
aspect | Cross-cutting structural contribution mechanism | RFC-0004 |
compose / apply | Policy composition mechanism | RFC-0004 |
app | Compiled bundle declaration | RFC-0002 |
5. Three-Layer Authoring Contract
Every domain concept should be definable across three layers:
Layer 1: Human layer
Plain-language meaning, examples, and labels. Required for non-technical authoring.
Layer 2: Structural layer
Formal types, fields, facets, cardinality, and constraints. Machine-enforced.
Layer 3: Evidence layer
Provenance, confidence, approval state, and AI authorship markers. Required for AI-safe operation.
A type system that lacks the third layer degrades to a schema language. The Gnomon semantic model requires all three layers to be present for any concept that may be authored or modified by an AI actor.
6. Composition Rules
- Entities compose by including named facets. Facet inclusion is additive.
- Included facets MUST NOT declare conflicting field names. Conflicts produce diagnostic M06501.
- An entity MAY include any number of facets. No ordering semantics.
- Facets MUST NOT include other facets. Transitive facet composition — where facet A includes facet B — is not supported. Facets are composed additively into entity types via
includes; theincludesfield is valid only onentitydeclarations, not onfacetdeclarations. Authors who need a shared field set across multiple facets MUST define an entity type that includes the relevant facets, not a facet chain. - The
isfield on anentitydeclaration is documentation-only and MUST NOT create any structural or behavioral inheritance.
7. Monotone Refinement
The system favors refinement over mutation. State moves forward; regression is exceptional, not routine.
7.1 Enforcement Surface
Monotone refinement has machine-enforced and documentation-only forms:
Machine-enforced (flow): When an entity declares a flow, all state transitions are governed by the flow declaration’s transition table. Undeclared transitions are rejected by the kernel. A transition that represents regression (moving to a less-specific state) MUST be declared with reversible: true on the transition. The kernel MUST NOT permit a state regression without an explicit reversible: true declaration. Reversible transitions MUST emit an audit event.
Documentation-only (the is field): The is field on an entity declaration (is SomeOtherEntity) is a human-readable declaration of conceptual parentage. It MUST NOT create structural inheritance or machine-enforced monotone constraints. If an author wants enforced monotone refinement between entity-level concepts, they MUST model it as a flow on a shared state field, not as an is chain.
Claim<T> status: The ClaimStatus flow (§4.5) enforces monotone-by-default semantics on epistemic status. pending → confirmed is one-way unless a governing policy declaration explicitly permits transition back to pending. The same ClaimStatus flow rules apply: regression requires explicit declaration.
7.2 Examples
// Machine-enforced: flow declaration governs state progression
flow CandidateLifecycle {
meaning: "Lifecycle of a job candidate from initial contact to hire/reject."
states [applied, screening, interviewing, offered, hired, rejected]
transitions [
applied -> screening,
screening -> interviewing,
screening -> rejected, // terminal on early screen-out
interviewing -> offered,
interviewing -> rejected,
offered -> hired,
offered -> rejected,
// Re-opening a rejected candidate requires explicit declaration:
rejected -> screening { reversible: true }
]
}
// Documentation-only: 'is' does NOT enforce monotone transitions
entity VerifiedEmployee {
meaning: "An employee whose identity has been verified."
is Employee // documents conceptual relationship; no structural enforcement
}
7.3 Invariant
An entity declaration that has a flow and a transition that is NOT declared reversible: true MUST NOT permit the runtime to move an gnomon instance to a prior state. The kernel MUST reject any Command that would produce such a state transition (M06537).
Diagnostic M06537: State transition rejected — regression on non-reversible flow transition.
8. Self-Explanation Contract
Every declared type MUST be renderable as a self-explanation including:
- What the concept means
- What fields it has
- What facets it includes and why
- What states it can move through
- What actions are allowed and by whom
- What AI is permitted to do with it
- Why a given value is believed to be present (provenance)
Types that cannot produce a coherent self-explanation at authoring time are considered incomplete.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
10. Security and Authorization
- AI actors MUST NOT be granted permissions on
proceduredeclarations beyond those explicitly declared in their agent definition (RFC-0009). Claim<T>status fields MUST be treated as trust signals; policies MAY gate actions on minimum confidence or required status values.- State transitions by AI actors MUST be authorized at the
policy/flowlevel, not assumed from field-write permissions. - Every field modified by an AI actor MUST carry a
Claim<T>wrapper preserving source, confidence, and timestamp.
11. Compatibility and Migration
The following table defines whether each schema change is safe (backward-compatible) or breaking. The full normative table lives in RFC-0016 §10; this section captures the semantic-model-level rules that govern RFC-0016’s classification.
| Change | Safe? | RFC-0014 version impact | Notes |
|---|---|---|---|
Add optional field with default(v) | Yes | MINOR | Existing records gain the default at read time |
| Add optional field without default | Yes | MINOR | Field absent on existing records; callers must handle absence |
| Add required field | No | MAJOR | Existing records have no value; migration MUST provide backfill |
| Remove field | No | MAJOR | Data loss; requires core.migrations.RemoveField with explicit approval |
| Rename field | No | MAJOR | Use core.migrations.RenameField; old name becomes deprecated alias until next MAJOR |
| Change field type (lossless coercion) | Conditional | MINOR or MAJOR | Must provide a total transform expression |
| Change field type (lossy) | No | MAJOR | Requires explicit migration + human approval |
Change field from T to Claim<T> | No | MAJOR | Requires explicit migration |
Add facet to existing entity | Yes | MINOR | Additive; no data change |
Remove facet from existing entity | Conditional | MINOR or MAJOR | Breaking if the facet contributed required fields |
Add flow to entity without one | No | MAJOR | Assigns initial state to all existing records |
Add state to existing flow | Yes | MINOR | Existing instances unaffected |
Remove state from existing flow | No | MAJOR | Instances in that state cannot be represented |
Add transition to existing flow | Yes | MINOR | More paths allowed |
Remove transition from existing flow | No | MAJOR | Callers relying on that path will fail |
| Add optional enum value | Yes | MINOR | Existing consumers may not handle the new value |
| Remove enum value | No | MAJOR | Existing records storing that value are invalid |
| Add entity | Yes | MINOR | New concept; no impact on existing |
| Remove entity | No | MAJOR | Deletes storage schema; requires approval |
Field default values: A field declaration MAY carry a default(value) modifier (RFC-0008 §6.3). When a field with a default is absent from a stored record (e.g., because the field was added after the record was created), the runtime returns the declared default rather than treating the field as absent. This makes default(v) on an optional field a pure MINOR change: no migration is needed because the compiler can synthesize the value at read time from the bundle’s schema.
- Adding a new
facetto an existing entity is a non-breaking change. - Adding a required field to an existing entity is a breaking change; migration MUST provide a default or backfill plan via
core.migrations.AddField(RFC-0016 §2). - Changing a field from
TtoClaim<T>is a breaking change requiring explicit migration. - Removing a
flowtransition is a breaking change if any existing gnomon instances are in the source state.