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:
| Namespace | Purpose |
|---|---|
core.migrations | Schema migration intrinsics (RFC-0016 §2) |
core.errors | Canonical error types |
core.lifecycle | Lifecycle annotation facets |
core.types | Scalar type aliases and branded types |
core.claims | Evidence 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
| Intrinsic | Required Slots | Optional Slots | Notes |
|---|---|---|---|
core.migrations.AddField | target, field, type | default | default required when live rows exist (M01601) |
core.migrations.RemoveField | target, field | drop | drop: true required when live non-null data exists (M01600) |
core.migrations.RenameField | target, from, to | — | Preserves deprecated alias until next MAJOR bump |
core.migrations.ChangeType | target, field, to, transform | — | transform MUST be a declared transform declaration (RFC-0008 §6.32) |
core.migrations.AddEntity | target, fields | — | target MUST be a declared entity in the same module |
core.migrations.RemoveEntity | target | drop | drop: true required when live instances exist (M01604) |
core.migrations.BackfillFrom | target, field, source | — | source is a field path expression on the target entity |
core.migrations.NoOp | — | reason | Records 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
| Name | Underlying type | Description |
|---|---|---|
core.types.Identifier | Text | A stable, opaque identity value (e.g., UUID, ULID). Never reused after deletion. |
core.types.Instant | Timestamp | A point in time with millisecond precision (UTC). Alias for RFC-0006’s Timestamp. |
core.types.Money | Decimal | A monetary amount. Does not carry a currency — pair with a core.types.CurrencyCode field. |
core.types.CurrencyCode | Text | An ISO 4217 currency code (e.g., "USD", "EUR"). |
core.types.Email | Text | An RFC 5321 email address. The compiler validates format at parse time when used as a literal. |
core.types.URL | Text | An absolute URL. The compiler validates scheme at parse time when used as a literal. |
core.types.Locale | Text | A 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.