RFC-0044 transform reproducibility proposal
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.
Status: proposal for the first public transform contract. No normative source or RDF identity changed.
Evidence
- RFC-0044 §3.3 requires
outputonly whenemitincludes module objects, but §4.5 writes IR-only output to<output>/<name>.transform-ir.json. Anemit: irentry with nooutputhas no defined destination. - Sections 3.5 and 5.2 make projector order observable: later projectors may
inspect earlier output. Section 5.4 hashes
sortedList(projectors), making[A, B]and[B, A]share a cache key despite potentially different output. - Section 4.2 includes
source.fetchedAtin the IR, while §§4.5 and 5.4 require deterministic, checked-in outputs keyed by source content. A fresh fetch of identical bytes changes the IR iffetchedAtis a wall-clock time. - Section 3.1 permits an unpinned remote URL and says content drift is diagnosed, but does not define the first-build lock or the content hash to use when falling back offline. A URL plus unknown content hash cannot be a lookup key before a fetch.
- Section 1 says
core.sdo.typeandcore.sdo.propertyuse compile-time transforms. Their current manifests undergnomon/vocab/modules/have notransforms:entries. Both are generated byrules_rdfand//tools/schemaorg, as their headers and annotations state. The RFC can use them as motivating ingestion examples, but must not claim current implementation through this transform pipeline. - Section 9.1 says existing
transforms:blocks “install unchanged,” while §6.3 forbids transform execution at install time. This should say that valid declarations compile without a syntax change, after validating the new contract. Nothing is deployed, so no migration is needed.
Recommended contract
- Require
outputfor every emit mode. Normalize it as a relative directory beneath the module root; reject traversal or absolute paths. - Hash the effective projector sequence, preserving declared or registration order. Include transform IR version, parser and projector versions, normalized profile, source digest, and any schema or compiler version that changes output. Use canonical serialization with explicit field boundaries before hashing.
- Keep fetch time in a build provenance record outside the deterministic TransformIR, or define it as a stable value from a content-addressed lock. Checked-in IR for identical source bytes and tool versions must be byte identical across clean builds.
- Require a source digest lock for remote URLs. The first lock creation is an explicit source update, not an ordinary reproducible compile. Verify fetched bytes against the lock. Maintain a URL-to-locked-digest index for offline fallback and reject an unverified stale cache entry. Distinguish network failure, digest drift, and an authorized lock update.
- Amend the
core.sdoexamples to describe their actualrules_rdfgeneration path until they are moved to a conforming manifest transform. Specify any move as an implementation task with output equivalence tests. - Replace the unchanged-install wording with a compile-time validation
statement. Include the existing
ext.clickupmanifest as an actual transform example, subject to parser support verification.
Acceptance checks
emit: irwithoutoutputfails validation; output traversal fails.- Reversing two order-sensitive projectors changes the cache key and output; a repeat with the same sequence hits cache.
- Two clean builds of identical locked bytes and tool versions emit identical IR and module-object files regardless of fetch time.
- A changed remote digest fails with a drift diagnostic; an offline build uses only the locked digest; no-lock offline build fails.
- Source examples match the checked-in
core.sdoandext.clickupmanifests.