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) rankedtransformas #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
transformdeclaration.”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:
| Locus | What it transforms | When it runs | Owner |
|---|---|---|---|
| RFC-0008 §6.32 | A typed input value into a typed output value via a pure expression. | Runtime, on every call. | Language surface |
| RFC-0044 | An external specification (JSON-LD, OpenAPI, JSON-Schema) into Gnomon module objects. | Build time, once per source change. | Compile pipeline |
| RFC-0016 | A schema state into a successor schema state, monotonically. | Install time. | Schema migration |
| RFC-0040 §8 | The 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:
- A canonical taxonomy of transform species (§3).
- A naming convention for prose, code, and diagnostic codes (§4).
- 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
| Term | Meaning |
|---|---|
| Transform | An over-broad term, deprecated in normative prose. Use one of the species names below. |
| Expression transform | A pure (input) → output runtime computation declared in .gnm (RFC-0008 §6.32). |
| Ingest transform | A build-step that reads an external artifact and emits Gnomon module objects (RFC-0044). |
| Migration transform | A monotone schema-state evolution (RFC-0016 §4). |
| Manifest transform entry | A row in the transforms: section of a module manifest (RFC-0040 §8) declaring an ingest transform. |
| Pure | A function with no I/O, no clock dependence, no global state — same input ⇒ same output. |
| Monotone | A 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:
| Concept | Canonical noun | Verb 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:
-
Does it run on every call at runtime? → expression transform (§3.1). The input and output are values.
-
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. -
Does it evolve schema state at install time? → migration (§3.3). Side effects on storage; approval-gated.
-
None of the above? → it’s likely an
action(RFC-0007),procedure(RFC-0008), ormutation(RFC-0008). Don’t call it a “transform”.
6. Diagnostics
All diagnostics in this RFC occupy the M56000–M56099 range.
| Code | Severity | Description |
|---|---|---|
M56010 | Warning | Bare “transform” in normative prose where the RFC-0008 §6.32 sense is not unambiguous. |
M56020 | Error | Manifest transforms: entry references a species other than ingest transform (e.g., declares expr: or down: fields). |
M56030 | Warning | Code 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:
- No code changes required. Existing
transformandmigrationdeclarations continue to compile. - Documentation pass: the four affected RFCs (0008, 0016, 0040,
0044) gain a one-line cross-reference to this RFC near their
respective
transform/migrationsections. - Tooling:
gnomon fmt --checkadds the M56010/M56030 warnings (advisory). - Internal docs: the
mdbook-linkcheck2config adds an alias table mapping bare “transform” mentions to the canonical species (informational only).
8. Invariants
- Bare “transform” in normative prose means the RFC-0008 §6.32 sense (§4).
- Manifest
transforms:entries declare ingest transforms only (M56020). - Migrations are NEVER called “transforms” in normative prose (M56030).
- 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).