gnomonlearn

RFC-0035 · Core Standard Library

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 →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Purpose

Several RFC-defined mechanisms reference declarations in a core.* namespace: core.migrations.* intrinsics (RFC-0016), core.errors.* types (RFC-0033), core.lifecycle.* annotation facets, and core.types.* scalar aliases. These references are authoritative across the RFC suite but their canonical definitions were deferred.

This RFC defines the core namespace as a reserved, compiler-provided standard library. core.* modules are not installed by authors; they are bundled with the compiler and are in scope for every module automatically. No import declaration is required to use them.

The design principle: core is not a runtime dependency, it is a compile-time vocabulary. All core.* declarations resolve to compiler-known intrinsics. The compiler emits the semantics directly into the compiled bundle (RFC-0002); there is no core.gnm source file distributed as a package.


2. Reserved Namespace

The core root namespace is reserved by the Gnomon compiler. Third-party modules MUST NOT declare names in the core namespace or any sub-namespace. Attempting to do so MUST produce error M35001 at module declaration time.

Sub-namespaces defined by this RFC:

NamespacePurpose
core.migrationsSchema migration intrinsics (RFC-0016 §2)
core.errorsCanonical error types
core.lifecycleLifecycle annotation facets
core.typesScalar type aliases and branded types
core.claimsEvidence record types for claims

Additional sub-namespaces MAY be reserved by future RFCs. Any core.* name not defined in this or a future RFC MUST produce error M35002 (unknown core name).


3. core.migrations — Schema Migration Intrinsics

These are the canonical definitions of the migration intrinsics referenced in RFC-0016 §2. Each intrinsic is an Gnomon-first-class name with a defined slot schema validated by the compiler.

3.1 Slot Schema

IntrinsicRequired SlotsOptional SlotsNotes
core.migrations.AddFieldtarget, field, typedefaultdefault required when live rows exist (M01601)
core.migrations.RemoveFieldtarget, fielddropdrop: true required when live non-null data exists (M01600)
core.migrations.RenameFieldtarget, from, to—Preserves deprecated alias until next MAJOR bump
core.migrations.ChangeTypetarget, field, to, transform—transform MUST be a declared transform declaration (RFC-0008 §6.32)
core.migrations.AddEntitytarget, fields—target MUST be a declared entity in the same module
core.migrations.RemoveEntitytargetdropdrop: true required when live instances exist (M01604)
core.migrations.BackfillFromtarget, field, source—source is a field path expression on the target entity
core.migrations.NoOp—reasonRecords a version bump with no structural change

3.2 Compiler Semantics

core.migrations.* intrinsics are compiler-opaque operations. The compiler does not expand them into lower-level IR — it passes them through to the migration DAG builder (RFC-0010 §9.3 MigrationDAGIndex) as structured migration nodes. The runtime reads the compiled migration DAG and executes each node natively.

Intrinsic slot values are statically typed. The compiler verifies slot types before emitting the migration node. Type errors in intrinsic slots produce M35010 (intrinsic slot type mismatch).


4. core.errors — Canonical Error Types

core.errors defines the error types that appear in api.errors.common blocks (RFC-0033 §6.4) and in operation errors {} blocks throughout the RFC suite.

4.1 Defined Types

variant core.errors.NotFound {
  meaning: "The requested resource does not exist."
  resourceKind: Text optional
  resourceId:   Text optional
}

variant core.errors.Unauthorized {
  meaning: "The caller is not authenticated or lacks the required scope."
  requiredScope: Text optional
}

variant core.errors.Forbidden {
  meaning: "The caller is authenticated but not permitted to perform this operation."
  reason: Text optional
}

variant core.errors.ValidationError {
  meaning: "One or more input fields failed validation."
  fields: List<FieldViolation>
}

variant core.errors.FieldViolation {
  meaning: "A single field validation failure."
  field:   Text required
  message: Text required
}

variant core.errors.RateLimitExceeded {
  meaning: "The caller has exceeded their allowed request rate."
  retryAfterSeconds: Integer optional
}

variant core.errors.ServiceUnavailable {
  meaning: "A transient infrastructure failure; the caller may retry."
  retryAfterSeconds: Integer optional
}

variant core.errors.Conflict {
  meaning: "The operation conflicts with the current state of the resource."
  reason: Text optional
}

variant core.errors.InternalError {
  meaning: "An unexpected internal error occurred."
  correlationId: Text optional
}

These are variant declarations — they are Gnomon sum types (RFC-0006 §4.B). They carry no behavior. Their structure is stable across module versions; adding optional fields is a non-breaking change, removing or changing fields requires a MAJOR version bump of core itself.

4.2 Usage

// In an api declaration
errors {
  common [
    core.errors.NotFound,
    core.errors.Unauthorized,
    core.errors.ValidationError,
    core.errors.RateLimitExceeded
  ]
}

// In an operation errors block
errors {
  404: terminal   // maps to core.errors.NotFound in the handler stub
  401: terminal   // maps to core.errors.Unauthorized
}

The HTTP handler stub (RFC-0034 §5) maps HTTP status codes to core.errors.* types when serializing error responses. The mapping is defined in RFC-0025 and is extensible by protocol adapter modules.


5. core.lifecycle — Lifecycle Annotation Facets

core.lifecycle defines the annotation facets used to declare entity and declaration lifecycle states.

5.1 Facets

annotation facet core.lifecycle.Deprecated {
  meaning: "Marks a declaration as deprecated and scheduled for removal."
  targets [entity, action, query, procedure, relation, facet, api, serve]
  since:   Text required
  reason:  Text required
  removal: Text optional
}

annotation facet core.lifecycle.Experimental {
  meaning: "Marks a declaration as experimental — contract may change without MAJOR bump."
  targets [entity, action, query, procedure, relation, facet, api, serve]
  stabilizationTarget: Text optional
}

annotation facet core.lifecycle.Internal {
  meaning: "Marks a declaration as internal — not for use outside this module."
  targets [entity, action, query, procedure, mutation, task, relation, facet]
}

These facets complement the epistemic modifiers (draft, experimental, stable) defined in RFC-0008 §4. The epistemic modifiers are compile-time stability signals on declarations; core.lifecycle annotation facets are metadata that appear in the compiled bundle and can be queried at tooling time (e.g., gnomon lint --warn-deprecated).


6. core.types — Scalar Aliases and Branded Types

core.types defines named type aliases that appear across the RFC suite. These are not new primitive types; they are brand aliases over the primitive scalars defined in RFC-0006 §4.A.

6.1 Defined Types

NameUnderlying typeDescription
core.types.IdentifierTextA stable, opaque identity value (e.g., UUID, ULID). Never reused after deletion.
core.types.InstantTimestampA point in time with millisecond precision (UTC). Alias for RFC-0006’s Timestamp.
core.types.MoneyDecimalA monetary amount. Does not carry a currency — pair with a core.types.CurrencyCode field.
core.types.CurrencyCodeTextAn ISO 4217 currency code (e.g., "USD", "EUR").
core.types.EmailTextAn RFC 5321 email address. The compiler validates format at parse time when used as a literal.
core.types.URLTextAn absolute URL. The compiler validates scheme at parse time when used as a literal.
core.types.LocaleTextA BCP 47 language tag (e.g., "en-US").

Branded types are structurally identical to their underlying type. They do not create new storage columns. Their purpose is documentation and lint: the compiler emits M35020 (type brand mismatch) when a core.types.Email field is assigned a value that is statically known not to be an email (e.g., a core.types.URL value).


7. core.claims — Evidence Record Types

core.claims defines evidence records used by the claim/evidence system referenced in RFC-0008 §6.x (claim and flow declarations). The epistemic status of Claim<T> is governed by the ClaimStatus flow in RFC-0006 §4.5; RFC-0055 consolidates its wrapper and evidence requirements. core.claims MUST NOT define a second ClaimStatus variant with different states. core.claims.EvidenceKind classifies stored EvidenceRecord instances; it does not replace RFC-0055’s EvidenceLink kinds (document, statement, rule) used by evidence_required.

7.1 Defined Types

variant core.claims.EvidenceKind {
  meaning: "The kind of evidence supporting or contesting a claim."
  document
  attestation
  systemRecord
  externalAudit
}

entity core.claims.EvidenceRecord {
  meaning: "A piece of evidence attached to a claim."
  fields {
    id:          core.types.Identifier required
    kind:        core.claims.EvidenceKind required
    submittedAt: core.types.Instant required
    submittedBy: Text required
    reference:   Text required
    notes:       Text optional
  }
}

Earlier drafts of this RFC showed a core.claims.ClaimStatus variant with pending, active, disputed, resolved, and expired. That variant conflicts with RFC-0006’s ClaimStatus flow and is withdrawn. The first-release contract uses the RFC-0006 flow directly; active, resolved, and expired are not states in that flow. Nothing is deployed, so no stored-data migration or compatibility window is required. Staged source and generated consumers must use the canonical flow before release. This repo has no .gnm, proto, or TypeScript implementation use of the withdrawn FQN outside the copied spec corpus.


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.

9. Versioning

core is versioned with the Gnomon compiler. core.* declarations do not have independent version numbers. Breaking changes to any core.* declaration constitute a breaking change to the Gnomon language itself and are governed by the RFC process.

Non-breaking additions (new optional fields on existing types, new named types in existing sub-namespaces) MAY be made in minor compiler releases. Authors MUST NOT depend on the absence of a core.* name.


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.