gnomonlearn
Docs/Graph/RFC-0044

RFC-0044 · Compile-Time Artifact Transforms

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

A compile-time transform is a build-step that ingests an external specification artifact (JSON-LD, OpenAPI, JSON-Schema) and emits Gnomon module objects (resource types, resources, statements, etc.) for inclusion in the host module’s manifest.

Compile-time transforms exist because most Gnomon modules need to bridge to existing ontologies and APIs:

  • core.sdo.type ingests schema.org’s JSON-LD vocabulary, producing thousands of resource_type declarations.
  • core.sdo.property ingests schema.org’s predicates similarly.
  • An integration module ingests its third-party API’s OpenAPI spec to materialize types.
  • A regulated-data module ingests a JSON-Schema to materialize entity contracts.

Without transforms, every such module would either hand-author tens of thousands of declarations or run external tooling out-of-band. Transforms put the ingestion in the manifest, deterministic, hashable, and reproducible.

This RFC specifies the transform declaration form (already defined in module manifests by RFC-0040 §8), the parser adapter protocol that lets new source formats register their handlers, the IR (intermediate representation) format, the projector contract that converts IR to module objects, and the cache and reproducibility rules.

It is a faithful codification of the schema and pipeline at /Volumes/Workspace/savvi-studio-full/packages/graph-module-model/model/transforms.ts.

Naming clarification: This RFC’s “transform” is distinct from RFC-0008 §6.32’s runtime transform declaration. The legacy code uses both names; the contexts disambiguate them. Where a future RFC could profit from disambiguation, this RFC’s concept MAY be referred to as “ingest transforms” — but the canonical manifest field name remains transforms: (RFC-0040 §8) for compatibility.


2. Definitions

TermMeaning
Compile-time transformA declaration in the module manifest’s transforms: section that ingests an external artifact at build time.
Source artifactThe input file or URL: a JSON-LD vocabulary, an OpenAPI document, a JSON-Schema, or similar.
Parser adapterA registered handler for a specific source format. Reads the source, normalizes to IR.
IR (transform IR)The intermediate representation produced by parser adapters; a uniform JSON shape that projectors consume.
ProjectorA registered transformation from IR to module objects. Multiple projectors MAY run on the same IR.
Emit modeWhat the transform writes: ir, module-objects, or both.
Cache keyA deterministic hash of (source content, parser, profile, projector set) used for build-cache lookups.

3. Transform Declaration

A transforms: section in a module manifest is a map of named transform entries (RFC-0040 §8):

transforms:
  <name>:
    source:     <path | url>
    parser:     jsonld | openapi | json-schema | auto (default)
    output:     <relative-dir>?              # required when emit includes module-objects
    emit:       ir | module-objects | both (default)
    profile:    <map>?                       # adapter-specific options
    projectors: [<projector-name>, ...]?     # default: all registered, in order

Transform names MUST be DNS-label-safe (lowercase alphanumeric and hyphens).

3.1 Sources

source is either:

  • A path relative to the module directory (e.g., ./apis/dsi.json).
  • An absolute URL (e.g., https://schema.org/version/latest/schemaorg-current-https.jsonld).

The build system resolves the path or fetches the URL deterministically. Network fetches are cached by URL + content-hash; content drift between builds is reported as a build-time diagnostic (M44010).

3.2 Parsers

Four parser values are recognized:

ParserFormatAdapter source
jsonldJSON-LD vocabularies (schema.org, FOAF, DCAT, SNOMED, …)graph-module-jsonld-translator
openapiOpenAPI 3.x (JSON or YAML)(RFC-0028 OpenAPI adapter, used here at compile time)
json-schemaJSON Schema draft-07 / 2019 / 2020(future adapter)
autoProbe registered adapters via canHandle(source)(compiler dispatch)

Implementations MUST register parser adapters at build-system initialization. Sources whose format is not handled by any registered adapter MUST produce M44020.

3.3 Emit modes

ModeOutput
irWrites the TransformIR JSON document only. Useful for inspection and diff.
module-objectsWrites projected Gnomon module-object YAML files.
both (default)Writes both.

When emit includes module-objects, output MUST be specified — the relative directory under the module root where projected files are written.

Generated files participate in normal manifest validation and orphan-file checks (RFC-0001 §orphan files). They are part of the module’s source set and are checked into version control alongside hand-authored sources.

3.4 Profiles

profile is a map of arbitrary adapter and projector options. Common keys:

  • namespacePrefix — prefix added to generated resource type ltree paths (e.g., dsi → dsi.user, dsi.organization).
  • includeOnly — restrict which terms in the source are projected.
  • excludeTypes — skip specific terms.
  • aliasMap — rename mappings.

The profile is opaque to the compiler core; it is forwarded to the parser adapter and projectors. Each adapter/projector documents its own profile keys.

3.5 Projectors

A projector is a named transformation step from IR to module objects. The default projector set is determined by the parser adapter (each adapter registers its preferred projectors).

When the manifest specifies an explicit projectors list, only the named projectors run, in the order given. This permits selective projection — e.g., a module that wants only resource_type declarations from a JSON-LD source, not predicate declarations.

Unknown projector names MUST produce M44030.


4. Transform IR

4.1 Purpose

The IR is the parser-adapter-produced normalized form. It exists to:

  • Decouple parsers (one per source format) from projectors (many per source).
  • Enable inspection and diffing of source-format changes between builds.
  • Feed multiple projectors with a stable, neutral representation.

4.2 IR shape

The IR is a JSON document with the envelope:

{
  "transformIRVersion": 1,
  "source": {
    "uri":          "<source path or url>",
    "contentHash":  "sha256:<hex>",
    "fetchedAt":    "<instant>"
  },
  "parser": {
    "name":         "<parser name>",
    "version":      "<adapter semver>"
  },
  "nodes": [<TransformIRNode>, ...],
  "links": [<TransformIRLink>, ...],
  "metadata": <map>
}

A node is one term in the source vocabulary:

TransformIRNode {
  id:          <opaque>             // adapter-generated unique id
  termIri:     <CURIE | URI>?       // original term identifier
  kind:        <category>            // adapter-defined ("type", "property", "instance")
  label:       <text>?
  description: <text>?
  attributes:  <map>                 // adapter-specific fields
}

A link is a relation between two nodes:

TransformIRLink {
  fromId:    <node-id>
  toId:      <node-id>
  predicate: <text>
  attributes: <map>?
}

4.4 IR conformance

IRs produced by different parser adapters MUST share the envelope (§4.2) but MAY use different kind categories and attributes shapes. Projectors that consume IR from multiple parsers MUST handle this — typically by branching on parser.name or by being parser-specific.

4.5 IR file format

When emit includes ir, the IR is written to <output>/<transform-name>.transform-ir.json. The file is a single JSON document, deterministically pretty-printed with sorted keys for stable diffing.


5. Projection

5.1 Projector contract

A projector is a function:

project(ir: TransformIR, profile: Map<String, Any>): Array<ModuleObject>

It reads the IR, applies the profile, and returns module objects (RFC-0040 §9 shapes). The projector is responsible for:

  • Naming generated objects deterministically (often based on termIri + namespacePrefix).
  • Deduplicating against previously-emitted objects in the same projection run.
  • Producing only valid module-object YAML.

5.2 Projector ordering

When multiple projectors run, they execute in registration order (or in the order given by the manifest’s projectors: list when explicit). Later projectors MAY observe earlier projectors’ outputs via the projection context.

5.3 Output file naming

Projected objects are written to <output>/<projector-name>/<object-kind>/<object-name>.gnm. The directory structure groups by projector and kind for readability. Consumers (the module manifest) reference these paths via the file-path object form (RFC-0040 §9.6).

5.4 Cache and reproducibility

Each transform’s output is cached by:

cacheKey = sha256(
  source.contentHash
  + parser.name + parser.version
  + sortedJson(profile)
  + sortedList(projectors)
)

When the cache key matches a previous build, the projection is skipped and outputs are reused. Cache misses re-run the parser and projectors.

Cache entries are stored under <module-dir>/.gnomon-cache/transforms/<transform-name>/<cacheKey>/. Implementations MUST commit cache invalidation rules to their build documentation.


6. Pipeline Integration

6.1 When transforms run

Transforms execute as part of the module compile pipeline (RFC-0040 §11), specifically at phase 1 (before module resolution and manifest validation):

1. Run transforms              ← THIS RFC
2. Resolve modules:
3. Load file-path objects       ← may include projected files
4. Validate manifest envelope
5. Validate objects map
...

This ordering ensures projected files are visible to the rest of the compile pipeline as ordinary module-object sources.

6.2 Failure modes

A transform failure (parse error, projector error, write error) MUST abort the module compile with a non-zero exit code. Generated files MUST NOT be partially written; implementations write to a temporary directory and atomically rename on success.

Network failures fetching a remote source MAY be tolerated when a cache entry exists for the previously-fetched content; the cache is the fallback source. When no cache exists and the network fails, the build MUST fail (M44040).

6.3 Build-time only

Transforms execute exclusively at build time. They MUST NOT run at install time (RFC-0041) or runtime. Implementations MUST refuse to invoke transform code paths from the install engine or operation runtime; doing so is a defect (M44050).


7. Naming Clarification: this RFC vs. RFC-0008 §6.32

Field/conceptRFC-0044 (this RFC)RFC-0008 §6.32
Manifest fieldtransforms: (top-level)(declaration in .gnm source files)
LifetimeBuild timeRuntime
PurposeIngest external specs → module objectsPure data transform for migrations / type changes
SourceJSON-LD, OpenAPI, JSON-SchemaGnomon expression language
OutputModule-object YAML files (and IR)Pure function OldType → NewType

The two are distinct concepts that share a name. Authors who need clarity in documentation MAY refer to this RFC’s concept as “ingest transforms” or “compile-time transforms”; RFC-0008’s as “data transforms” or “runtime transforms.” The manifest field name (transforms:) is preserved from legacy.


8. Invariants

  1. Transform names MUST be DNS-label-safe (§3, naming convention).
  2. output MUST be specified when emit includes module-objects (§3.3).
  3. Generated files participate in normal validation; they are not exempt from manifest checks (§3.3).
  4. Transforms run only at build time; never at install or runtime (§6.3).
  5. The transform cache key is deterministic over (source content, parser, profile, projectors) (§5.4).
  6. Failure modes are atomic: no partial output writes (§6.2).
  7. Network sources fall back to cache on transient failure; failure with no cache is fatal (§6.2).
  8. The IR envelope (§4.2) is uniform across parsers; only kind and attributes shapes vary by parser.
  9. Projector ordering is deterministic (registration order or explicit projectors: list) (§5.2).
  10. Projected files are addressed by the file-path object form (RFC-0040 §9.6) and are not magic — they’re just .gnm files.

9. Compatibility and Migration

9.1 From legacy graph-module-model/transforms

This RFC is a faithful codification of the legacy schema:

Legacy elementThis RFC
graphModuleTransformEntrySchema (source, parser, output, emit, profile, projectors)§3
graphModuleTransformsSchema (top-level map)§3
graphModuleTransformParserSchema (jsonld, openapi, json-schema, auto)§3.2
graphModuleTransformEmitSchema (ir, module-objects, both)§3.3

Existing transforms: blocks in module manifests install unchanged.

9.2 Existing parser adapters

AdapterSourceRFC reference
graph-module-jsonld-translatorJSON-LD vocabularies§3.2
OpenAPI parserOpenAPI 3.x§3.2 + RFC-0028 (cross-reference for the runtime client side)
JSON-Schema parserJSON-Schema§3.2 (future)

Adapters publish their own diagnostic codes within their assigned RFC range.

9.3 IR versioning

The IR transformIRVersion: 1 is fixed by this RFC. Future revisions MAY introduce 2 with backward-compatible additions. Breaking IR changes require a new RFC.


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.

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.