gnomonlearn

RFC-0056 · Transform Taxonomy and Naming Convention

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.

Read design questions and decisions →

Status: draft consolidation. The cross-cutting concern analyzer at docs/analysis/cross-cutting.md (see spec source) ranked transform as #8 by score, with four definers (RFC-0008/0016/0040/0044) using the same name for at least three semantically distinct species. RFC-0044 already calls this out informally:

“This RFC’s ‘transform’ is distinct from RFC-0008 §6.32’s runtime transform declaration.”

This RFC formalizes the disambiguation. It does not merge the four existing concepts into one — they’re genuinely different — but it introduces a normative taxonomy and naming convention so authors can tell which is which without triangulating four RFCs.


1. Purpose

The word “transform” is currently overloaded across the corpus:

LocusWhat it transformsWhen it runsOwner
RFC-0008 §6.32A typed input value into a typed output value via a pure expression.Runtime, on every call.Language surface
RFC-0044An external specification (JSON-LD, OpenAPI, JSON-Schema) into Gnomon module objects.Build time, once per source change.Compile pipeline
RFC-0016A schema state into a successor schema state, monotonically.Install time.Schema migration
RFC-0040 §8The manifest declaration form of RFC-0044’s compile-time transforms.(declaration; not execution)Module manifest

Three distinct executional contexts (runtime, build, install) and a manifest form. They don’t share semantics — runtime transforms are pure; compile-time transforms have full filesystem access; schema-migration transforms have DDL side effects.

Triangulating four RFCs to know which kind is meant in a given context is the load-bearing pain. This RFC fixes that with three things:

  1. A canonical taxonomy of transform species (§3).
  2. A naming convention for prose, code, and diagnostic codes (§4).
  3. A decision tree (§5) that authors can apply mechanically when choosing which kind to use.

It does not change the semantics of any existing RFC.


2. Definitions

TermMeaning
TransformAn over-broad term, deprecated in normative prose. Use one of the species names below.
Expression transformA pure (input) → output runtime computation declared in .gnm (RFC-0008 §6.32).
Ingest transformA build-step that reads an external artifact and emits Gnomon module objects (RFC-0044).
Migration transformA monotone schema-state evolution (RFC-0016 §4).
Manifest transform entryA row in the transforms: section of a module manifest (RFC-0040 §8) declaring an ingest transform.
PureA function with no I/O, no clock dependence, no global state — same input ⇒ same output.
MonotoneA schema or state evolution that adds without removing existing constraints (RFC-0006).

3. Taxonomy

3.1 Expression transform (RFC-0008 §6.32)

Form:

transform PriceWithTax {
  meaning: "Apply tax rate to a base price."
  input:   Money
  output:  Money
  expr:    input * (1 + 0.08)
}
  • Locus: runtime.
  • Purity: strict. No I/O, no clock, no globals (M55610 if violated).
  • Composability: transforms are first-class values; they may be passed to other transforms.
  • Replaceable. Authors MAY hot-swap an expression transform without rebuild as long as the input/output schemas are unchanged.

This is the only species that should be called just “transform” in new prose. Diagnostic codes M0860x and M2110x apply.

3.2 Ingest transform (RFC-0044)

Form (manifest entry — RFC-0040 §8):

transforms:
  schema-org-types:
    type: ingest
    source: vendor/schema.org/all-layers.jsonld
    parser: jsonld-class-emitter
    emits: [resource_type, predicate]
  • Locus: build time.
  • Purity: the parser is pure; the runtime of the parser is pure given the source bytes. But the source is fetched (with optional caching) and may change between builds.
  • Composability: none. Ingest transforms run once per build; their outputs are flat module objects, not values.
  • Hashable. Output is content-addressed by (source-hash, parser-id, emit-policy) (RFC-0044 §6).

Refer to as “ingest transform” in prose. The manifest field name transforms: is preserved for compatibility (RFC-0040 §8).

3.3 Migration transform (RFC-0016)

Form:

migration AddVerifiedField {
  applies_to: User
  effect:     add_field("verified", Boolean, default: false)
  approved_by: ["alice", "bob"]
}
  • Locus: install time.
  • Purity: strict in inputs; effectful on storage. Each migration is hashed, idempotent, and approval-gated.
  • Composability: sequential — migrations form a totally-ordered chain per module.
  • Reversibility: a migration MAY declare a down: block. Authors SHOULD always declare one when the change is reversible.

Refer to as “migration” in prose, NEVER as “transform” — the legacy code’s migration: { transform: ... } field name is a historical wart.

3.4 Manifest transform entry

The transforms: section in a module manifest (RFC-0040 §8) is a declaration form, not an execution context. Each entry references one ingest transform (§3.2). The manifest’s transforms: field name is fixed for compatibility but MUST NOT be used in prose without qualification.


4. Naming convention

When writing new RFCs or revising existing ones:

ConceptCanonical nounVerb form
RFC-0008 §6.32“expression transform” or just “transform”“transforms”
RFC-0044“ingest transform”“ingests”
RFC-0016“migration”“migrates”
RFC-0040 §8“manifest’s transforms: entry” or “ingest transform declaration”“declares an ingest transform”

Bare “transform” in normative prose MUST mean RFC-0008 §6.32. Anywhere else, the species name is REQUIRED.

The gnomon fmt --check tool MUST emit warning M56010 when a bare “transform” appears in the prose of a §Normative section without the RFC-0008 §6.32 sense being unambiguous from context.


5. Decision tree

When choosing which kind to declare, authors apply this in order:

  1. Does it run on every call at runtime? → expression transform (§3.1). The input and output are values.

  2. Does it produce module objects from an external artifact at build time? → ingest transform (§3.2). The output is resource_type, predicate, policy, etc. declarations.

  3. Does it evolve schema state at install time? → migration (§3.3). Side effects on storage; approval-gated.

  4. None of the above? → it’s likely an action (RFC-0007), procedure (RFC-0008), or mutation (RFC-0008). Don’t call it a “transform”.


6. Diagnostics

All diagnostics in this RFC occupy the M56000–M56099 range.

CodeSeverityDescription
M56010WarningBare “transform” in normative prose where the RFC-0008 §6.32 sense is not unambiguous.
M56020ErrorManifest transforms: entry references a species other than ingest transform (e.g., declares expr: or down: fields).
M56030WarningCode or comment uses “transform” to refer to a migration.

These are documentation/style diagnostics; they are advisory in CI but non-blocking. Authors MAY suppress with // gnomon:no-warn=M56010.


7. Migration

This RFC introduces the taxonomy without changing existing semantics. Migration steps:

  1. No code changes required. Existing transform and migration declarations continue to compile.
  2. Documentation pass: the four affected RFCs (0008, 0016, 0040, 0044) gain a one-line cross-reference to this RFC near their respective transform/migration sections.
  3. Tooling: gnomon fmt --check adds the M56010/M56030 warnings (advisory).
  4. Internal docs: the mdbook-linkcheck2 config adds an alias table mapping bare “transform” mentions to the canonical species (informational only).

8. Invariants

  1. Bare “transform” in normative prose means the RFC-0008 §6.32 sense (§4).
  2. Manifest transforms: entries declare ingest transforms only (M56020).
  3. Migrations are NEVER called “transforms” in normative prose (M56030).
  4. Adding a fourth species REQUIRES extending this RFC; new “kinds of transform” cannot land elsewhere.

9. Open questions

These draft questions and their deferral triggers are tracked in the RFC-0056 companion Q&A.


10. Linked References

  • RFC-0008 §6.32 — expression transforms (the canonical “transform”).
  • RFC-0016 — schema migrations.
  • RFC-0040 §8 — the manifest transforms: declaration form.
  • RFC-0044 — ingest transforms (full pipeline specification).
  • RFC-0049 §11 — projection algebra; uses expression transforms in π.
  • RFC-0053 §5 — view materialization (potential fourth species).