Turning CICS → Java into an iterably solvable problem

[squid-protocol]

I started the COBOL/CICS → Java translator with a goal: get the translation right 100% of the time, on the first try. That's still the destination. But in the last couple of weeks the thing I was building turned into something else, and I think it's more useful than the original goal.

CICS → Java translation is now an iterably solvable problem.

What "iterably solvable" means

Every gap now surfaces as a concrete, ranked, fixable item:

• a named refusal (the translator says exactly what it won't guess at)
• a failed proof (Java and COBOL disagreed, and I know which bytes)
• a fuzz difference (random differential testing against the oracle found a mismatch)
• a coverage hole (a paragraph or branch no scenario ever ran)
• a register entry (an assumption written down so it can be checked)

And three things follow from that:

• Each fix compounds. One runtime rule fixed once repairs every program that uses it, and every future estate that hasn't arrived yet. I'm not fixing programs, I'm fixing the translator.
• The numbers move measurably with each step. In about two days: programs translating whole, about 95 → 114; programs at evidence level L2+ (proven equal on their scenarios), 34 → 62; L3+ (every paragraph run), 16 → 32.
• A miss comes with a plan. In a one-shot or open-ended approach, a miss just means "it's wrong." Wrong how? Wrong where? Will the next run fail in the same place? You can only re-roll. Here a miss is a line on a ranked list.

The supporting argument: a measuring stick

The reason this works is that the translator is deterministic (no LLM anywhere in the translation) and every program ships with a full evidence chain. So when a translation isn't right, I get a precise list of what was wrong, and that list is the list of things to fix.

First-time success is a claim. A ranked, evidenced fix list is a plan a team can execute. I'd honestly take the plan. So my focus shifted from first-try success to the documentation and evidence a team needs to march to 100%.

What's in the machine

• A deterministic translator. Same COBOL in, same Java out, every time. No model guessing.
• The cobolrt runtime. COBOL has very particular rules (fixed-point decimals, truncation, how fields move into other fields). cobolrt is those rules, written in Java, so the translated code behaves like the original instead of like "Java that looks similar."
• An equivalence harness. It runs the original COBOL (GnuCOBOL plus our CICS stub plus a real Db2) and the Java port on the same scenarios, then compares every byte.

On top of that, every program gets an evidence level, L0 to L5:

• L0: not translated (refused, or blocked)
• L1: translated whole
• L2: proven equal to the original on its scenarios
• L3: ...and those scenarios ran every paragraph
• L4: ...and every branch (net of branches reviewed as unreachable)
• L5: ...and mutation-tested: we break the Java on purpose, and every mutant that survives is accounted for

Anything I can't do, the translator refuses by name instead of guessing. There's a caveats register (oracle_assumptions.md) where every assumption is tagged MATCHED, REFUSED, DIFFERS or ASSUMED. Compile options are recorded with provenance per program (#4704, #4708). The release gate refuses stale evidence (#4703). And the definition of done I signed off on is now written down in docs/language_status/definition_of_done.md (#4722), so "finished" isn't a vibe.

How the gaps show up

This is the part I care about. There are five ways a gap surfaces, and each one is a to-do item with a name on it:

• A named refusal. The census ranks refusals by programs made whole, so the top of the list is "fix this and N more programs translate completely."
• A failed proof. The Java and the COBOL disagreed on a scenario, and I know which bytes.
• A fuzz difference. Random differential fuzzing against the oracle. Arithmetic went from about 11 mismatches per random program to 0. That didn't happen by being clever once. It happened by reading the list and clearing it.
• A coverage hole. A paragraph or branch no scenario touched, so it's unproven, and the report says so.
• A register entry. A place where we're assuming the oracle and the real thing agree, written down so it can be checked.

The harness also audits itself, and this is the part that made me wince and then feel good about it. In about two days it found three places where my proofs were weaker than they looked:

• comparisons that skipped DISPLAY output and low-values (equivalence: CICS proofs do not compare DISPLAY output, and treat low-values as spaces (det-port mutation survivors, #4628) #4635)
• comparisons that only checked occurrence 1 of repeated fields, skipping 2..N (Equivalence: COMMAREA OCCURS fields are compared at the first occurrence only; det LINK of an OCCURS DTO passes the first occurrence's extent #4765)
• CALL comparisons that only covered DTO-mapped fields (equivalence: batch CALL compare (equivalence_call.compare_dto) checks only DTO-mapped fields; DTOs with trailing FILLER keep a short extent #4778, still in progress)

Each of those made some "proven" claims quietly softer than advertised. Now they're on the list, and closing them makes every earlier number more honest. A one-shot pipeline has no way to find out its own proofs are leaky.

The numbers actually move

Over roughly two days:

• Programs that translate whole, in the census: about 95 → about 114 of 179. For the CICS-only subset, 76 → about 90 of 125.
• Programs at evidence level L2 or better: 34 → 62.
• L3+: 16 → 32.
• L4: 13 → 16.
• GenApp went from about zero to 25 proven once Db2 proofs were counted.

That's the point of the whole post. Those moved because I took the top items off a ranked list, not because I got lucky. Next week's list is shorter and different.

A policy shift

IBM z/OS is the reference. GnuCOBOL is the instrument. GnuCOBOL is how I measure, not what's right. Where IBM documents the answer, the Java follows IBM, and GnuCOBOL is configured to match or the difference is declared. Where IBM leaves it undefined, the translator refuses by name rather than guess. The register is where every one of those calls is written down. A future step is calibrating against a real z/OS.

The big caveat, no sugarcoating

• "Proven" means proven on the scenarios run, not for all possible inputs. L4 and L5 narrow that gap; they don't close it.
• The oracle isn't z/OS yet. Until the calibration happens, every "equal" is "equal to GnuCOBOL plus my stub."
• Burned vs. blind estates. The estates I've been fixing against are ones I've already looked at hard. The real test is the blind 4th estate, where I see the list for the first time with no chance to tune to it.
• Translating the code is not migrating the system. Data, batch scheduling, operations, people. This is one important slice.

So I'm not telling you it's right the first time. I'm telling you that when it's wrong, I'll know where, I'll be able to rank it, and the fix will stick for everyone after.

More as it comes in.