Transform taxonomy decision
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.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
RFC-0056 is draft and has no Lean catalog. This proposal records the source contract needed before its taxonomy can be made normative. It does not change the existing transform, migration, or manifest contracts.
Observed contracts
| Source | Existing contract | RFC-0056 conflict |
|---|---|---|
| RFC-0008 §6.32 | transform is a pure data migration function in a Migrations-class file. It uses for, versioned from/to, and apply {}; M16020 rejects side effects. | §3.1 invents input/output/expr syntax, runtime execution on every call, first-class composition, hot swapping, and undefined M55610. |
| RFC-0016 §§1–4 | A migration is a version-scoped schema operation with forward and conditional rollback blocks. Its dependency graph is a DAG; eligible operations execute in deterministic topological order. ChangeType.transform references RFC-0008’s pure data function. Approval is required for MAJOR breaking changes, not every migration. | §3.3 invents effect, approved_by, and down syntax, calls the graph a totally ordered chain, and says every migration is approval-gated. |
| RFC-0040 §8, RFC-0044 | Manifest transforms: entries describe build-time external-artifact ingestion. The field spelling is retained for compatibility. | §3.2’s example uses type/emits rather than the published source/parser/output/emit form. |
The extracted framework’s
graph/packages/graph-module-model/model/transforms.ts models the manifest
transforms: entries as build-time ingestion and explicitly excludes install
and runtime execution. This local model does not prove full compiler coverage
for the RFC-0008 declaration.
Recommended contract
Preserve the predecessor RFC semantics and make RFC-0056 a taxonomy of three different roles, not three newly interchangeable declaration kinds:
- Data transform: RFC-0008’s pure, total
transformdeclaration maps existing data during an RFC-0016 migration. It has no general every-call runtime or hot-swap contract. Keep M16020 for an impure body and M16021 for one not provably total. - Ingest transform: RFC-0044’s build-time artifact ingestion, declared in
RFC-0040’s existing
transforms:manifest field. Its parser may read or fetch a source under RFC-0044’s cache and failure rules; do not describe the entire ingest step as pure. - Migration: RFC-0016’s effectful schema-evolution declaration. Its
ChangeType.transformslot may reference a data transform; the migration itself is not a transform declaration. Preserve its DAG, rollback rules, operation-specific approval gate, andforward/rollbacksyntax.
In normative prose, qualify the noun as data transform or ingest
transform. Use migration for the schema operation. Bare transform is
valid only when quoting the RFC-0008 keyword or the existing manifest/slot
name and the context identifies it. This avoids assigning the bare word a
new default meaning that conflicts with RFC-0040/0044 and RFC-0016.
Exact draft changes after owner approval
- Replace RFC-0056 §§1–5’s examples, execution times, syntax, and decision
tree with the three roles above. In §3.1, show the actual RFC-0008
forand versionedapply {}form. In §3.3, show RFC-0016forwardandrollbackblocks, including that rollback is mandatory when existing data changes. - Replace
M55610with existingM16020. Remove the claim that RFC-0056 creates a new purity diagnostic. Keep diagnostic identity and severity stable for current consumers. - Specify
M56010andM56030as advisory wording warnings. SpecifyM56020as a compiler error for an invalid manifest entry; it must block that compile and must not be called advisory. Define the exact checker scope and suppression policy before claiminggnomon fmt --checkemits these codes. A style warning cannot be substituted for the manifest schema error. - Add accurate, one-line taxonomy cross-references to RFC-0008, RFC-0016,
RFC-0040, and RFC-0044 only after the draft text is reconciled. Preserve
transforms:andChangeType.transformfor compatibility. - Remove the
mdbook-linkcheck2migration step: the extracted spec uses Lean/RDF generation and the Astro site, and its inherited mdBook renderer has been retired. Replace it with checks for links and terminology in the current corpus and site.
An alternate choice would establish a general runtime expression-transform API. That requires an explicit RFC-0008 syntax and execution change, compiler/runtime implementation, a migration path for existing declarations, and tests for composition, lifetime, and hot swapping. It cannot be presented as a clarification that leaves predecessor semantics unchanged.
Acceptance before formal emission
Owner selects the contract above or the explicit runtime API expansion. Then
align authored examples, diagnostics, predecessor cross-references, the Lean
terms and diagnostic catalog, emitted reference/RDF catalogs, and source-bound
projection reviews. Add compiler fixtures for RFC-0008 purity and totality,
RFC-0016 ChangeType binding and DAG/rollback behavior, and manifest ingest
validation. Verify formatter behavior before describing M56010/M56030 as
implemented. Keep RFC-0056 draft until those checks and the strict release
gate pass.