MBA-2032: COBOL-to-Python migration plan and PORTVALD reference translation pair

[devin-ai-integration]

Summary

Implements MBA-2032: adds Python as a benchmark translation target, with a migration plan and the first translation pair actually built and pinned against the COBOL.

Plan — documentation/technical/python-migration-plan.md: inventory of the 38 programs tiered by external dependency (1 pure logic, 21 file I/O, 7 DB2, 8 CICS) plus the 20 copybooks/15 JCL/BMS/CSD artefacts, a per-construct feasibility table (verdict: feasible; CICS only as behavioural emulation), PIC→Python type mapping, and five waves with exit criteria. Also records that src/programs/batch/POSUPDT.cbl is an empty file although the README advertises POSUPD00.

First migration step (executed) — PORTVALD, the only dependency-free program, translated into translations/python/ with one function per paragraph and a dataclass for the LINKAGE record:

@dataclass
class ValidationRequest:      # 01 LS-VALIDATION-REQUEST, fields held at picture length
    validate_type: str        # X(1)
    input_value: str          # X(50)
    return_code: int          # S9(4) COMP
    error_msg: str            # X(50)

def portvald(request: ValidationRequest) -> None:   # mutates like CALL BY REFERENCE

The translation is behaviour-preserving, including four latent defects in the original that a naive translation silently "fixes" — that is what makes the pair useful as benchmark material:

Trap	Why	Effect
No portfolio ID can pass	suffix moved into VAL-NUMERIC-CHECK PIC X(10), so IS NUMERIC sees trailing spaces	PORT0001 → VAL-INVALID-ID
No account number can pass	class test runs on the space-padded X(50) item	1234567890 → VAL-INVALID-ACCT
No amount can fail the range check	min/max are the extremes of the receiving S9(13)V99	99999999999999999 → success
Unknown validation type reports an ID error	WHEN OTHER moves VAL-INVALID-ID	type Z → rc 1

Equivalence harness — tools/cobol_bridge.py compiles the COBOL with cobc -m and calls it through libcob with the raw 103-byte linkage record, so the 23 recorded vectors are re-verified field-for-field against the real program on every run instead of being hand-asserted:

tests/vectors/portvald.json  →  test_portvald.py            (vectors vs Python)
                             →  test_portvald_equivalence.py (COBOL vs Python, skipped without GnuCOBOL)

README — Purpose and Future Plans now list Python, Documentation links the plan, and the project structure gains translations/.

No COBOL source is modified; translations/ is documented as benchmark material and is not wired into any COBOL build.

Testing

cd translations/python
python -m pytest        # 47 passed (23 vectors + 23 differential + 1)
                        # 24 passed, 23 skipped when GnuCOBOL is absent
ruff check . && ruff format --check .

Notes

• Related open PR Add COBOL-to-Python migration ticket and update Future Plans #94 adds documentation/tickets/COBOL-PYTHON-MIGRATION.md and edits the same README "Future Plans" bullet; whichever merges second will need a one-line conflict resolution there.

Link to Devin session: https://app.devin.ai/sessions/be97621cd70a49e392c9afb295177614

---

Devin Review

Status	Commit
⚪ Not started	—

Run Devin Review

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring