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.
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
| Term | Meaning |
|---|---|
| Cache key | A deterministic hash of (source content, parser, profile, projector set) used for build-cache lookups. |
| Compile-time transform | A declaration in the module manifest’s transforms: section that ingests an external artifact at build time. |
| Emit mode | What 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 adapter | A registered handler for a specific source format. Reads the source, normalizes to IR. |
| Projector | A registered transformation from IR to module objects. Multiple projectors MAY run on the same IR. |
| Source artifact | The input file or URL: a JSON-LD vocabulary, an OpenAPI document, a JSON-Schema, or similar. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M44010 | Warning | Network source content hash drifted between builds; cache invalidated |
M44011 | Error | Network source could not be fetched and no cache entry exists |
M44020 | Error | No registered parser adapter handles the source format (after auto probe) |
M44021 | Error | Parser adapter rejected the source as malformed |
M44030 | Error | Manifest’s projectors: list references an unknown projector |
M44031 | Warning | Projector produced zero module objects from a non-empty IR — review profile or skip the projector |
M44032 | Error | Projector produced module objects that fail validation in the host module’s pipeline |
M44040 | Error | Cache miss + network failure: build cannot proceed |
M44041 | Warning | Cache write failed; transform output regenerated each build |
M44050 | Error | Compile-time transform code path invoked at install or runtime; defect |
M44060 | Error | output directory missing when emit requires module-object files |
M44061 | Error | Generated file path collides with a hand-authored module object |
M44070 | Warning | Profile contains keys unrecognized by the configured parser/projectors; check for typos |
M44080 | Error | IR 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
- Generated files participate in normal manifest validation and orphan-file checks; they are not exempt from manifest checks. (enforced by: compile-time)
- Network sources fall back to cache on transient failure; failure with no cache entry is fatal. (enforced by: compile-time)
- 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)
- Projector ordering is deterministic: registration order, or the explicit projectors list when given by the manifest. (enforced by: compile-time)
- The TransformIR envelope is uniform across parser adapters; only kind categories and attributes shapes vary by parser. (enforced by: compile-time)
- The output directory MUST be specified whenever emit includes module-objects. (enforced by: compile-time)
- The transform cache key is deterministic over (source content, parser, profile, projectors). (enforced by: compile-time)
- 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)
- Transform names MUST be DNS-label-safe (lowercase alphanumeric and hyphens). (enforced by: compile-time)
- 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
- MUST — The transform cache key is deterministic over (source content, parser, profile, projectors). (proof citation:
rfc0044_b20_grounded; verification pending) - MUST — Transform names MUST be DNS-label-safe.
- MUST — Transforms run only at build time; never at install or runtime. (proof citation:
rfc0044_b15_grounded; verification pending) - MUST — output MUST be specified when emit includes module-objects.
Pipeline Integration
- MUST — A transform failure MUST abort the module compile with a non-zero exit code.
- MUST_NOT — Generated files MUST NOT be partially written; writes happen to a temporary directory and are atomically renamed.
- MUST — Implementations MUST refuse to invoke transform code paths from the install engine or operation runtime (M44050). (proof citation:
rfc0044_b10_grounded; verification pending) - MUST_NOT — Transforms MUST NOT run at install time or runtime. (proof citation:
rfc0044_b22_grounded; verification pending) - MUST — When no cache exists and the network fails, the build MUST fail (M44040).
Projection
- MUST — Implementations MUST commit cache invalidation rules to their build documentation. (proof citation:
rfc0044_b2_grounded; verification pending)
Transform Declaration
- MUST — Implementations MUST register parser adapters at build-system initialization.
- MUST — Sources whose format is not handled by any registered adapter MUST produce M44020. (proof citation:
rfc0044_b12_grounded; verification pending) - MUST — Transform names MUST be DNS-label-safe (lowercase alphanumeric and hyphens).
- MUST — Unknown projector names MUST produce M44030. (proof citation:
rfc0044_b5_grounded; verification pending) - MUST — When emit includes module-objects, output MUST be specified.
Transform IR
- MUST — IRs from different parser adapters MUST share the envelope but MAY use different kind categories and attributes shapes.
- MUST — Projectors consuming IR from multiple parsers MUST handle parser-specific differences.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Depends on | RFC-0038 |
| Depends on | RFC-0039 |
| Depends on | RFC-0040 |