gnomonlearn
Docs/RFC-0044/Reference catalog

RFC-0044 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0044: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0044.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0044. Edit that source and regenerate this catalog.


Title: Compile-Time Artifact Transforms
Status: draft
Owners: Compiler, Module Platform
Diagnostic range: M44000-M44099

Depends on: RFC-0001, RFC-0006, RFC-0007, RFC-0036, RFC-0037, RFC-0038, RFC-0039, RFC-0040

Proof citations in source: 7 / 7. Standalone proof verification is pending.


Definitions

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

Diagnostics

CodeSeverityDescription
M44010WarningNetwork source content hash drifted between builds; cache invalidated
M44011ErrorNetwork source could not be fetched and no cache entry exists
M44020ErrorNo registered parser adapter handles the source format (after auto probe)
M44021ErrorParser adapter rejected the source as malformed
M44030ErrorManifest’s projectors: list references an unknown projector
M44031WarningProjector produced zero module objects from a non-empty IR — review profile or skip the projector
M44032ErrorProjector produced module objects that fail validation in the host module’s pipeline
M44040ErrorCache miss + network failure: build cannot proceed
M44041WarningCache write failed; transform output regenerated each build
M44050ErrorCompile-time transform code path invoked at install or runtime; defect
M44060Erroroutput directory missing when emit requires module-object files
M44061ErrorGenerated file path collides with a hand-authored module object
M44070WarningProfile contains keys unrecognized by the configured parser/projectors; check for typos
M44080ErrorIR transformIRVersion is unsupported by the host runtime

Dependency neighborhood

graph LR
  nRFC_0044["RFC-0044"]
  nRFC_0001["RFC-0001"]
  nRFC_0044 --> nRFC_0001
  nRFC_0006["RFC-0006"]
  nRFC_0044 --> nRFC_0006
  nRFC_0007["RFC-0007"]
  nRFC_0044 --> nRFC_0007
  nRFC_0036["RFC-0036"]
  nRFC_0044 --> nRFC_0036
  nRFC_0037["RFC-0037"]
  nRFC_0044 --> nRFC_0037
  nRFC_0038["RFC-0038"]
  nRFC_0044 --> nRFC_0038
  nRFC_0039["RFC-0039"]
  nRFC_0044 --> nRFC_0039
  nRFC_0040["RFC-0040"]
  nRFC_0044 --> nRFC_0040

Invariants

  1. Generated files participate in normal manifest validation and orphan-file checks; they are not exempt from manifest checks. (enforced by: compile-time)
  2. Network sources fall back to cache on transient failure; failure with no cache entry is fatal. (enforced by: compile-time)
  3. Projected files are addressed by the file-path object form (RFC-0040 §9.6) and are ordinary .gnm files with no special status. (enforced by: compile-time)
  4. Projector ordering is deterministic: registration order, or the explicit projectors list when given by the manifest. (enforced by: compile-time)
  5. The TransformIR envelope is uniform across parser adapters; only kind categories and attributes shapes vary by parser. (enforced by: compile-time)
  6. The output directory MUST be specified whenever emit includes module-objects. (enforced by: compile-time)
  7. The transform cache key is deterministic over (source content, parser, profile, projectors). (enforced by: compile-time)
  8. Transform failure modes are atomic: implementations write to a temporary directory and atomically rename on success, never leaving partial output writes. (enforced by: compile-time)
  9. Transform names MUST be DNS-label-safe (lowercase alphanumeric and hyphens). (enforced by: compile-time)
  10. Transforms execute exclusively at build time and MUST NOT run at install time or runtime. (enforced by: compile-time + runtime)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Invariants

  1. MUST — The transform cache key is deterministic over (source content, parser, profile, projectors). (proof citation: rfc0044_b20_grounded; verification pending)
  2. MUST — Transform names MUST be DNS-label-safe.
  3. MUST — Transforms run only at build time; never at install or runtime. (proof citation: rfc0044_b15_grounded; verification pending)
  4. MUST — output MUST be specified when emit includes module-objects.

Pipeline Integration

  1. MUST — A transform failure MUST abort the module compile with a non-zero exit code.
  2. MUST_NOT — Generated files MUST NOT be partially written; writes happen to a temporary directory and are atomically renamed.
  3. MUST — Implementations MUST refuse to invoke transform code paths from the install engine or operation runtime (M44050). (proof citation: rfc0044_b10_grounded; verification pending)
  4. MUST_NOT — Transforms MUST NOT run at install time or runtime. (proof citation: rfc0044_b22_grounded; verification pending)
  5. MUST — When no cache exists and the network fails, the build MUST fail (M44040).

Projection

  1. MUST — Implementations MUST commit cache invalidation rules to their build documentation. (proof citation: rfc0044_b2_grounded; verification pending)

Transform Declaration

  1. MUST — Implementations MUST register parser adapters at build-system initialization.
  2. MUST — Sources whose format is not handled by any registered adapter MUST produce M44020. (proof citation: rfc0044_b12_grounded; verification pending)
  3. MUST — Transform names MUST be DNS-label-safe (lowercase alphanumeric and hyphens).
  4. MUST — Unknown projector names MUST produce M44030. (proof citation: rfc0044_b5_grounded; verification pending)
  5. MUST — When emit includes module-objects, output MUST be specified.

Transform IR

  1. MUST — IRs from different parser adapters MUST share the envelope but MAY use different kind categories and attributes shapes.
  2. MUST — Projectors consuming IR from multiple parsers MUST handle parser-specific differences.

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Depends onRFC-0038
Depends onRFC-0039
Depends onRFC-0040