gnomonlearn
Docs/RFC-0044 transform reproducibility proposal

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 output only when emit includes module objects, but §4.5 writes IR-only output to <output>/<name>.transform-ir.json. An emit: ir entry with no output has 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.fetchedAt in 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 if fetchedAt is 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.type and core.sdo.property use compile-time transforms. Their current manifests under gnomon/vocab/modules/ have no transforms: entries. Both are generated by rules_rdf and //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.
  1. Require output for every emit mode. Normalize it as a relative directory beneath the module root; reject traversal or absolute paths.
  2. 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.
  3. 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.
  4. 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.
  5. Amend the core.sdo examples to describe their actual rules_rdf generation path until they are moved to a conforming manifest transform. Specify any move as an implementation task with output equivalence tests.
  6. Replace the unchanged-install wording with a compile-time validation statement. Include the existing ext.clickup manifest as an actual transform example, subject to parser support verification.

Acceptance checks

  • emit: ir without output fails 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.sdo and ext.clickup manifests.