gnomonlearn
Docs/Transform taxonomy decision

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

SourceExisting contractRFC-0056 conflict
RFC-0008 §6.32transform 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–4A 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-0044Manifest 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.

Preserve the predecessor RFC semantics and make RFC-0056 a taxonomy of three different roles, not three newly interchangeable declaration kinds:

  1. Data transform: RFC-0008’s pure, total transform declaration 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.
  2. 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.
  3. Migration: RFC-0016’s effectful schema-evolution declaration. Its ChangeType.transform slot may reference a data transform; the migration itself is not a transform declaration. Preserve its DAG, rollback rules, operation-specific approval gate, and forward/rollback syntax.

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 for and versioned apply {} form. In §3.3, show RFC-0016 forward and rollback blocks, including that rollback is mandatory when existing data changes.
  • Replace M55610 with existing M16020. Remove the claim that RFC-0056 creates a new purity diagnostic. Keep diagnostic identity and severity stable for current consumers.
  • Specify M56010 and M56030 as advisory wording warnings. Specify M56020 as 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 claiming gnomon fmt --check emits 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: and ChangeType.transform for compatibility.
  • Remove the mdbook-linkcheck2 migration 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.