Home /Modules/impl/CONVERTER-IDEMPOTENCE.md

CONVERTER-IDEMPOTENCE.md

impl/subjects/conversion/CONVERTER-IDEMPOTENCE.md · 145 line(s) · markdown

Java converter input/output idempotence contract

Date: 2026-11-14 Scope: sleelactl/convert and lib/java/converter. This contract is separate from semantic coverage: deterministic conversion does not make an unsupported Java construct convertible.

Required meaning

For a fixed tuple of (source-tree bytes, relative source paths, JDK release identity, conversion-model bytes/revision, converter revision, and explicit options), conversion must produce the same sorted output path set and exactly the same output bytes on every run and host supported by the converter.

The operation must be idempotent:

convert(snapshot, options) -> output
convert(snapshot, options) -> identical output bytes and paths

Unchanged output files must not be rewritten merely because conversion ran again. Their modification times should remain unchanged. A source deletion or a source that now fails closed must remove only outputs previously owned by the converter; unrelated files must remain untouched.

Input contract

  1. Discover source paths in a deterministic lexical order using normalized relative paths and a fixed case policy.
  2. Reject symlinks, non-regular source entries, path traversal, duplicate normalized paths, and unreadable inputs before mutating output.
  3. Read every source exactly once into an immutable snapshot. Project indexing and translation must consume the same bytes; never index one version and translate a later version after a concurrent edit.
  4. Pin the source identity to the actual JDK release/source archive, not merely a user-supplied --jdk-version 28 label. Record the source archive/release identity and per-file content digests in a machine-readable input manifest.
  5. Pin the conversion model by content digest as well as declared revision. A revision string alone is not a trust boundary.
  6. Normalize only what Java defines as semantically irrelevant. Preserve source encoding/Unicode semantics, line endings where diagnostics depend on them, package/module paths, and licence notices. Do not silently rewrite malformed UTF-8 or Unicode escapes.

Output contract

  1. Generate into a staging tree; do not destroy the previous successful output before the new run has passed input validation and generation.
  2. Sort output paths and report entries. Avoid timestamps, random IDs, host paths, locale-dependent formatting, and unstable map iteration in generated output. If provenance dates are required, derive them from pinned source metadata or keep them out of generated source.
  3. Compare bytes before replacing an existing owned output. If bytes are equal, leave the file and its modification time unchanged.
  4. Atomically publish changed files and the ownership manifest only after generation succeeds. On failure, preserve the previous committed output set; write diagnostics separately.
  5. Remove stale outputs only when they are listed in the previous ownership manifest and absent from the newly committed output set. Refuse unsafe manifest paths and symlink escapes.
  6. Emit a deterministic provenance manifest containing source digest(s), JDK identity, model digest/revision, converter revision, options, sorted input/output paths, and output digests. The manifest itself must be stable for identical inputs.

Status of this implementation pass

C++ converter

SLeeLa-native converter

Required conformance tests

For each converter independently, run the following against a pinned JDK 28 source snapshot:

Next implementation order

  1. Complete whole-run transactional staging/publication in the C++ converter.
  2. Add a repeat-run/mtime regression test for both converter output paths and validate the C++ provenance manifest against independently computed hashes.
  3. Give the SLeeLa-native converter source/model/converter/output SHA-256 provenance, then stage and publish its whole-run manifest.
  4. Pin the exact JDK 28 source archive/revision used for the conformance corpus.
  5. Run both converters independently; report complete, partial/stubbed, refused, and infrastructure-failed counts separately.