gnomonlearn
Docs/Composition/RFC-0006

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

  1. Provide a meaning-first, compositional type model understandable by non-technical domain authors
  2. Make uncertainty and evidence first-class so AI-generated data is structurally differentiated from human-entered or system-verified data
  3. Type operations (actions), not just data, so that AI actor permissions are enforceable at the model layer
  4. Support monotone refinement so state transitions are auditable and unidirectional by default
  5. 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

  1. Every domain concept MUST be declared as one of the declared declaration kinds (see §4.B).
  2. Facet composition MUST NOT use inheritance chains; composition is strictly additive via includes.
  3. A Claim<T> wrapper MUST accompany any field that may be produced by an AI actor.
  4. State transitions MUST be monotone by default: a state MAY be refined to a more specific state but MUST NOT regress silently.
  5. An action declaration MUST exist for each action an AI actor is permitted to perform; absence of a declaration MUST imply prohibition.
  6. Every declared kind MUST carry a meaning field sufficient for a non-technical domain author to understand it without reading code.
  7. 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:

  1. A field typed as Value (the root) is error M06020
  2. A field typed as a declaration kind name (e.g., field: action) is error M06022 — declaration kinds are not value types
  3. A field typed as a declared entity name resolves as a Reference; the named entity MUST be declared in scope (error M06021 if not)
  4. The identifier JSON is reserved as the Opaque value type; user declarations MUST NOT use it as a type or entity name (error M06023)
  5. A field typed as Unit is error M06024 — Unit is only valid as a return type, not a field type

Diagnostic codes:

  • M06020 — field typed as Value (abstract root; use a specific value type)
  • M06021 — field typed as entity name not declared in scope
  • M06022 — field typed as a declaration kind (declaration kinds are not value types)
  • M06023 — user declaration uses reserved name JSON
  • M06024 — field typed as Unit (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 kindProducesDeclaration class
entityA named structured type with identitySchema
typeA named enumeration value typeSchema
variantA named discriminated union value typeSchema
flowA named lifecycle state machineSchema
invariantA named constraint on an entitySchema
facetA named set of fields to be composed into entitiesSchema
mutationNamed transactional state changeSchema
computeNamed pure derived valueSchema
claimNamed evidence-wrapper type declaration (Claim<T> alias)Schema
extendCross-module facet contribution to an entitySchema
actionComposition of mutations + event emissionOperations
actuatorEvent-driven side-effect handlerOperations
eventNamed domain event with typed fieldsOperations
procedureAPI binding: auth + action delegationOperations
queryA named read operationOperations
taskA named background computationOperations
integrationA named external push protocolOperations
clientA named outbound API contractOperations
workflowA named multi-agent orchestration process with human gates (RFC-0022)Operations
sagaA named multi-step fallible external API saga with compensationOperations
apiA named protocol-agnostic public service surface (RFC-0033)Operations
serveA named protocol binding that maps an api to wire endpoints (RFC-0034)Operations
relationA named association between entitiesRelations
policyA named access control ruleGovernance
agentA named AI participantGovernance
composeA named composition of governance declarationsGovernance
transformA named pure data migration function — maps entity instances at one version to another (RFC-0016)Migrations
migrationA named schema + data evolution step with forward and rollback paths (RFC-0016)Migrations
appA named product surfaceSurface
viewA named projected entity shapeSurface
testA named assertionTests

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:

ComponentSeparatorMeaningExample
namespace. withinDot-separated module pathorg.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 prefix core
  • M06041 — FQN reference cannot be resolved to a declared artifact
  • M06042 — 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 cardinalityIncoming null behaviorDiagnostic
required fieldNull is treated as missing. The runtime raises a validation error (same as absent required field).M06050
Optional fieldNull is coerced to field-absent. The field is treated as not present in the record. No error.—
List<T> memberA null element inside a list is a validation error; the list is rejected.M06051
Map<K,V> valueA 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 a required field at deserialization boundary (validation error)
  • M06051 — null element received inside a List<T> or Map<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 description
  • fields — typed field declarations
  • includes — zero or more facet names (additive composition)
  • is — optional conceptual parent (documentation only; not an inheritance mechanism). If the is field references an entity kind that is not declared in scope, the compiler MUST emit warning M06502.
  • flow — optional reference to the flow declaration that governs this entity’s lifecycle; an entity MUST NOT reference more than one flow
  • examples — 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 adds
  • rules — policy constraints that apply to all entities including this facet
  • requires — 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 (declared entity name)
  • to — target entity (declared entity name)
  • meaning — description of what the relation asserts
  • cardinality — one, many, or zero-or-one
  • constraints — predicates that must hold for the relation to be valid
  • qualifiers — 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 does
  • input — typed parameters
  • mutations — the mutation declarations composed into this action
  • after — emits statements 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 effects grammar now lives exclusively in mutation declarations (see §4.4a). An action declaration MUST NOT declare an effects block 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 does
  • input — typed parameters
  • returns — optional entity the mutation returns after commit
  • effects — 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:

  1. Every entity named in a mutation effects block MUST be declared in scope; error M06610
  2. A transitions -> <StateName> statement MUST name a state declared in the entity’s flow; if the entity has no flow, error M06611
  3. A creates <Entity> in <StateName> MUST name a valid initial state of the entity’s flow; error M06612
  4. A mutates <Entity>.<fieldPath> MUST name a declared field; error M06613
  5. A mutation effects block containing dispatches, sends, emits, or calls is error M06614
  6. A mutation with no effects block is warning M06615 — a no-op mutation

Diagnostic codes:

  • M06610 — effects block references entity not declared in scope
  • M06611 — transitions statement on entity with no declared flow
  • M06612 — creates in <State> names invalid or unreachable flow state
  • M06613 — mutates <Entity>.<field> names undeclared field
  • M06614 — post-commit statement (dispatches, sends, emits, calls) inside mutation effects block
  • M06615 — mutation has no effects block (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 value
  • source — origin (human input, AI model ID, import source, rule ID)
  • confidence — numeric score or interval
  • asserted_by — actor identity
  • asserted_at — timestamp
  • status — a value of type ClaimStatus (see below); governs the epistemic standing of the claim
  • evidence_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 .gnm DSL (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:

  1. A field that may be produced or modified by a declared AI agent without Claim<T> MUST produce error M06520, including bare JSON and annotated JSON fields
  2. A bare JSON field on an entity produced by a declared AI agent with no @epistemic annotation MUST also produce warning M06530 during import preflight
  3. A Claim<JSON> field is valid and enforces provenance metadata at the storage layer
  4. Moving from Claim<JSON> to Claim<StructuredType> is governed by RFC-0016

Diagnostic codes:

  • M06530 — during import preflight, AI-produced entity has bare JSON field with no epistemic annotation (warning)
  • M06531 — @epistemic annotation on non-JSON field (use Claim<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 values
  • transitions — allowed from -> to pairs with actor constraints
  • rules — 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:

  1. Enum value names MUST be lower_snake_case IDENT tokens.
  2. An enum MUST contain at least two values.
  3. Inline enum values are not referenceable outside their enclosing declaration.
  4. Top-level enums MUST have a meaning property (required, like facet).
  5. Changing or removing values from a published enum is 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 actions
  • rules — one or more declarative constraint statements
  • enforcement — hard (violation is a runtime error) or soft (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 declarationRFC-0008 entity-syntax keywordRFC-0008 scope-syntax keyword
entityentityentity
facetfacet—
relationrelation—
mutationmutation—
action—action
procedure—procedure
actuator—actuator
event—event
task—task
computecompute—
Claim<T>claim—
flowflow—
policypolicypolicy (inline in policy blocks)
enumenum (top-level) or inline enum { } on a field—

Implementor note — type vs enum: The §4.B declaration kind taxonomy lists type as producing “a named enumeration value type.” In the RFC-0008 authoring surface, this declaration kind is surfaced exclusively as the enum keyword (both top-level and inline forms, as described in §4.6a). The keyword type does not appear in the RFC-0008 grammar. The §4.B label “named enumeration value type” and the §4.6a/§4.8 enum keyword refer to the same semantic construct; implementors MUST treat them as identical. The type label 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 keywordDerives fromNormative reference
agentParticipation contract (not a semantic type)RFC-0009
invariantNamed, parametric form of policy constraint rules; referenceable from action mustSatisfyRFC-0006 §4.7
queryNamed read accessor over the gnomon query API; compiles to gnomon.find() / gnomon.resolve()RFC-0007 §7
viewNamed projection for UI consumption; compiles to route/page/layout/widgetRFC-0007 §5.3, RFC-0003 §5a
aspectCross-cutting structural contribution mechanismRFC-0004
compose / applyPolicy composition mechanismRFC-0004
appCompiled bundle declarationRFC-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

  1. Entities compose by including named facets. Facet inclusion is additive.
  2. Included facets MUST NOT declare conflicting field names. Conflicts produce diagnostic M06501.
  3. An entity MAY include any number of facets. No ordering semantics.
  4. 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; the includes field is valid only on entity declarations, not on facet declarations. Authors who need a shared field set across multiple facets MUST define an entity type that includes the relevant facets, not a facet chain.
  5. The is field on an entity declaration 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

  1. AI actors MUST NOT be granted permissions on procedure declarations beyond those explicitly declared in their agent definition (RFC-0009).
  2. Claim<T> status fields MUST be treated as trust signals; policies MAY gate actions on minimum confidence or required status values.
  3. State transitions by AI actors MUST be authorized at the policy/flow level, not assumed from field-write permissions.
  4. 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.

ChangeSafe?RFC-0014 version impactNotes
Add optional field with default(v)YesMINORExisting records gain the default at read time
Add optional field without defaultYesMINORField absent on existing records; callers must handle absence
Add required fieldNoMAJORExisting records have no value; migration MUST provide backfill
Remove fieldNoMAJORData loss; requires core.migrations.RemoveField with explicit approval
Rename fieldNoMAJORUse core.migrations.RenameField; old name becomes deprecated alias until next MAJOR
Change field type (lossless coercion)ConditionalMINOR or MAJORMust provide a total transform expression
Change field type (lossy)NoMAJORRequires explicit migration + human approval
Change field from T to Claim<T>NoMAJORRequires explicit migration
Add facet to existing entityYesMINORAdditive; no data change
Remove facet from existing entityConditionalMINOR or MAJORBreaking if the facet contributed required fields
Add flow to entity without oneNoMAJORAssigns initial state to all existing records
Add state to existing flowYesMINORExisting instances unaffected
Remove state from existing flowNoMAJORInstances in that state cannot be represented
Add transition to existing flowYesMINORMore paths allowed
Remove transition from existing flowNoMAJORCallers relying on that path will fail
Add optional enum valueYesMINORExisting consumers may not handle the new value
Remove enum valueNoMAJORExisting records storing that value are invalid
Add entityYesMINORNew concept; no impact on existing
Remove entityNoMAJORDeletes 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.

  1. Adding a new facet to an existing entity is a non-breaking change.
  2. 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).
  3. Changing a field from T to Claim<T> is a breaking change requiring explicit migration.
  4. Removing a flow transition is a breaking change if any existing gnomon instances are in the source state.