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
- Discover source paths in a deterministic lexical order using normalized relative paths and a fixed case policy.
- Reject symlinks, non-regular source entries, path traversal, duplicate normalized paths, and unreadable inputs before mutating output.
- 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.
- Pin the source identity to the actual JDK release/source archive, not merely
a user-supplied
--jdk-version 28label. Record the source archive/release identity and per-file content digests in a machine-readable input manifest. - Pin the conversion model by content digest as well as declared revision. A revision string alone is not a trust boundary.
- 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
- Generate into a staging tree; do not destroy the previous successful output before the new run has passed input validation and generation.
- 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.
- Compare bytes before replacing an existing owned output. If bytes are equal, leave the file and its modification time unchanged.
- Atomically publish changed files and the ownership manifest only after generation succeeds. On failure, preserve the previous committed output set; write diagnostics separately.
- 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.
- 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
- Implemented deterministic lexical ordering of discovered input paths.
- Implemented a one-read immutable source snapshot shared by project indexing and translation.
- Implemented refusing symlink and non-regular source files before output mutation.
- Implemented byte comparison before writing generated files, preserving modification times when output bytes are unchanged.
- Implemented a sorted ownership manifest and deferred stale-output cleanup.
- Added
CONVERSION-PROVENANCE.json: SHA-256 digests cover the exact model bytes, immutable input snapshot, available converter source files, and emitted output bytes.converterSourceCompleterecords whether all expected source files were present; the compiled binary identity is not recorded. The manifest has no timestamps or absolute checkout paths and labels the JDK version as a declared label rather than asserting release authenticity. - Not yet complete: output generation is not yet staged as a whole-run transaction; a late I/O failure can leave some newly written files before the ownership manifest is committed. The provenance record does not verify that the source tree is an official JDK release archive.
- Not yet verified: no local compile or test run has been recorded for these changes. Do not call this pass green.
SLeeLa-native converter
- The walker sorts directory entries. The emitter now writes each output to a
same-directory
.jconv-tmp, compares it with the existing file, preserves unchanged mtimes, and renames a complete changed file into place. The report TSV and summary use the same staged compare/publish pattern. Model descriptions omit absolute paths, and generatedmetaDate/metaBirthDateare nowunknownrather than wall-clock values, so identical inputs do not vary by run date. - Per-file output-open and staged-publication failures are now reported as failed files rather than successful conversions.
- Not yet complete: the SLeeLa-native converter has no SHA-256 provenance manifest for source/model/converter/output bytes, and its per-file publication is not a whole-run transaction. Its batch script still resets transient progress state for a fresh run.
- Its per-member-stub policy remains a different acceptance result from the C++ converter's per-file fail-closed policy. Reports must keep these outcomes distinct; a stubbed output is not a complete mapping.
Required conformance tests
For each converter independently, run the following against a pinned JDK 28 source snapshot:
- Convert twice into the same output directory; compare sorted path lists and SHA-256 digests, and verify unchanged file mtimes on the second run.
- Change one source file; verify only dependent outputs and provenance change.
- Delete one source file; verify only its previously owned outputs are removed.
- Make one source unsupported; verify no partial output for it and no loss of unrelated owned outputs.
- Add an unrelated file to the output directory; verify it is never overwritten or deleted.
- Mutate a source during conversion; verify the converter uses one captured snapshot or aborts before publishing.
- Introduce a symlink source and a symlinked output parent; verify safe refusal.
- Run from two different absolute checkout paths and supported locales; verify generated source bytes are identical.
- Run with the same source but a different model digest, converter revision, or option; verify provenance changes and the result is not misidentified as the same conversion.
- For every accepted source, compile/run the result and compare observable behavior with the same pinned JDK. Determinism is not a substitute for equivalence.
Next implementation order
- Complete whole-run transactional staging/publication in the C++ converter.
- Add a repeat-run/mtime regression test for both converter output paths and validate the C++ provenance manifest against independently computed hashes.
- Give the SLeeLa-native converter source/model/converter/output SHA-256 provenance, then stage and publish its whole-run manifest.
- Pin the exact JDK 28 source archive/revision used for the conformance corpus.
- Run both converters independently; report complete, partial/stubbed, refused, and infrastructure-failed counts separately.