compile & runtime options as a first-class estate input: one resolver for oracle + det port, provenance, evidence fingerprint #4704

Owner request (2026-10-08). Under the policy "IBM is the reference; GnuCOBOL is the instrument" (#4702), "IBM's result" means IBM's result under the compile and runtime options this estate actually uses. Today we capture only part of those options, and they don't flow through the system as one input.

What exists today (origin/main)

• tests/tools/equivalence_common.py (Regional compiler and DB2 options not captured: INTDATE, YEARWINDOW, ARITH, TRUNC, NUMPROC, DSNHDECP DATE/TIME format, DECIMAL=COMMA #3828, Equivalence oracle runs IBM's default TRUNC(STD) as TRUNC(BIN) on both sides #4102, COBOL oracle/translator: floating point and compiler options (COMP-1/2 hex float, NUMPROC, ARITH(EXTEND), TRUNC(OPT), INTDATE, COMP-5 byte order) #4271) builds cobc flags from three sources:
  • the case's compiler_options, standing in for the JCL PARM;
  • the program's own CBL / PROCESS cards, which override it (det/source.py parses them; GnuCOBOL gets them blanked);
  • IBM defaults for anything unnamed (DEFAULTS; TRUNC(STD), for example).
• Only INTDATE, TRUNC, ARITH, NUMPROC are SEMANTIC_OPTIONS. TRUNC(OPT), ARITH(EXTEND) and INTDATE(LILIAN) raise UnsupportedOption. NUMPROC(MIG) resolves per case (numproc_mig).
• The det translator reads some of the same facts separately: NUMPROC in det/source.py / Codec.java, ARITH in det/program.py / expr.py, DECIMAL-POINT from SPECIAL-NAMES, code pages from the estate manifest (code_pages, --source-encoding), and record_charset in the forges.
• Only mortgage-mpmt records the compiler product and version, with provenance (case.json → compiler: {product, version, evidence}, from BLDMORT.jcl).

Gaps

1. Options not captured or modelled, for each: does it change results, can cobc do it, and what does the det port do?
   • Compiler:
     • ZONEDATA (Enterprise COBOL 6.x; INVDATA in 6.4+): how invalid zoned/packed data behaves (C11);
     • CODEPAGE;
     • NSYMBOL / DBCS;
     • DISPSIGN;
     • AFP / FLOAT;
     • SSRANGE and NUMCHECK / INITCHECK (abends vs silent behaviour);
     • OPTIMIZE (undefined-behaviour shapes such as C14 divide by zero);
     • TRUNC(OPT);
     • ARITH(EXTEND).
   • Compiler version (6.1 vs 6.3 vs 6.4 change defaults and behaviour) and the shop's installation defaults (IGYCDOPT). A program with no PARM gets the shop's defaults, not IBM's.
   • Language Environment runtime options:
     • STORAGE(heap / stack init), which decides what uninitialised WORKING-STORAGE holds;
     • TRAP / ABTERMENC (abend behaviour);
     • the CEEOPTS / CEEUOPT source.
   • Db2 precompile and bind:
     • DATE / TIME format (ISO / USA / EUR / JIS / LOCAL), which affects every date string;
     • DEC(15 / 31), DECPT;
     • SQLCCSID / CCSID;
     • ISOLATION.
   • CICS: translator options, the region's code page (SIT / LOCALCCSID), and the abend and EIB conventions it relies on.
2. No single source of truth. The oracle side (equivalence_common) and the port side (det translator / runtime) each read options their own way. They must resolve the same effective option set per program.
3. No provenance. We should know whether each option was found (JCL PARM, CBL card, installation defaults listing, LE options member) or assumed (IBM default or a declared assumption).
4. Not in the evidence chain. A program's effective options aren't part of its evidence record's fingerprint, so a change to them doesn't make the proof stale. The evidence report doesn't show which options a level holds under.

Proposal

• An estate-level options file (e.g. estate_options.json beside the corpus pin or the case) with:
  • compiler product and version, and installation defaults;
  • default PARM, plus per-program overrides;
  • LE runtime options;
  • Db2 precompile and bind options;
  • CICS region options;
  • for every value, its provenance (source file and line, or "assumed: IBM default" / "assumed: owner decision").
• One resolver (effective_options(program)) combines the estate defaults, the JCL PARM and the program's CBL / PROCESS cards (IBM's precedence order). Both the oracle flag builder and the det translator / runtime consume it; drop the separate readers.
• Per option, a row in a table (in oracle_assumptions.md or a new compile_options.md):
  • does it change results;
  • the cobc flag, config or wrapper that honours it;
  • the det port's behaviour;
  • otherwise: refuse by name / declared difference (per oracle policy: IBM is the reference, GnuCOBOL the instrument — audit register entries + z/OS calibration oracle #4702).
• Evidence: add options to the evidence-record fingerprint as a BLOCKING input, so changed options make the proof stale (tests/tools/evidence.py BLOCKING). Show the effective options and their provenance per program in the evidence report.
• Intake: an estate checklist for asking a customer for the inputs we need: compile JCL / PARMs, IGYCDOPT listing, CEEOPTS / CEEUOPT, Db2 bind cards, CICS SIT. For the blind 4th estate, a list of what we assume when an input is missing.
• Calibration hook (oracle policy: IBM is the reference, GnuCOBOL the instrument — audit register entries + z/OS calibration oracle #4702 part 2): the z/OS probe corpus runs under the same effective options, so measured IBM results are tied to the options they hold under.

Acceptance

• An estate options file exists for each burned estate (CardDemo, CBSA, GenApp, mortgage, async credit-card, zecs). Each value carries provenance, and unknowns are explicitly marked "assumed".
• The oracle and the det port resolve identical effective options through one resolver; a test asserts it per program.
• Changing an estate's options makes the affected evidence records stale (CI fails), and the evidence report lists the options per program.
• The option table covers at least the options in Gap 1. Each one is modelled, honoured by cobc, refused by name, or a declared difference.
• The estate-intake checklist is documented.

Related: #4702 (IBM reference and z/OS calibration), #3828 / #4102 / #4271 (existing option handling), #4048 (evidence records), #4601 / #4703 (evidence report).

🤖 Generated with Claude Code

Remaining slices (as of 2026-10-18)

Done so far: 3 merged PRs (#4719, #5307, #5385).

• Compiler-option rows, group A (ZONEDATA/INVDATA, TRUNC(OPT), ARITH(EXTEND), INTDATE(LILIAN)): per option, changes results? cobc flag? det behaviour? else refuse by name or declared difference. Check: option-table tests + a burned-estate "no recorded value newly refuses" test. TRUNC(OPT) needs the Option table for compiler options not yet modelled (ZONEDATA/INVDATA, CODEPAGE, SSRANGE/NUMCHECK, OPTIMIZE, TRUNC(OPT), ARITH(EXTEND)...) (#4704) #4706 ruling first (CBSA builds with TRUNC(OPT), applied as STD today). (1 PR) (audit 2026-10-18: options: group A compile options have a fate; no burned-estate value newly refuses (Part of #4704) #5477, options: compiler option table -- result-changing options refused by name or declared (Part of #4706) #5088, det: TRUNC(OPT) as IBM defines it -- STD for conforming binary values, a named stop past the PICTURE (Part of #4706) #4746, det: ARITH(EXTEND) modelled -- an intermediate past 30 digits stops by name (Part of #4706) #5340, det: INTDATE(LILIAN) modelled in the det port (Part of #4706) #5413)
• Compiler-option rows, group B (CODEPAGE, NSYMBOL/DBCS, DISPSIGN, AFP/FLOAT, SSRANGE, NUMCHECK/INITCHECK, OPTIMIZE), same format; with group A closes Option table for compiler options not yet modelled (ZONEDATA/INVDATA, CODEPAGE, SSRANGE/NUMCHECK, OPTIMIZE, TRUNC(OPT), ARITH(EXTEND)...) (#4704) #4706. (1 PR) (options: audit Gap-1 options have a row and an intake question (Part of #4704) #6184)
• (moot, owner 2026-10-23: Option table for LE runtime, Db2 precompile/bind and CICS region options (#4704) #4707 closed; table covered by runtime options: judge Db2 DATE / TIME / DEC / DECPT / SQLCCSID / EBCDIC_CCSID for syntax (Part of #4707) #6182/runtime options: judge CICS region / program-definition values for syntax (Part of #4707) #6192, no provisional rows left in runtime_options.py) Option table for LE runtime, Db2 precompile/bind and CICS region options (#4704) #4707 follow-through: after the owner ruling, adjust the 23 provisional LE/Db2/CICS rows in gitgalaxy/core/runtime_options.py (C18). Check: test_runtime_option_table.py. (1 PR, blocked on the owner)
• (verify) Det port reads DECIMAL-POINT and code pages through the resolver instead of separate readers. Check: per-program oracle/det parity, det_port.py check unchanged on the burned estates. Only if a burned program needs it (Estate options: compiler version bounds which options exist; parity covers ARITH (Part of #4704) #5385 names only a non-burned crucible estate). (1 PR) (test: det translator reads compile options only through the one resolver (Part of #4704) #6195)
• (verify) CEEOPTS/CEEUOPT reader: grep the burned corpora first; drop if nothing reads it (Runtime option table: LE, Db2 and CICS options refused, declared or no effect (Part of #4704) #5307 says none does). (audit 2026-10-18: Runtime option table: LE, Db2 and CICS options refused, declared or no effect (Part of #4704) #5307)
• Acceptance audit: every burned estate has an options file (CBSA, CardDemo, GenApp, mortgage, zecs, async credit-card) and the intake checklist covers every Gap-1 option. Check: test_estate_options + a table-coverage test listing any Gap-1 option with no row. (1 PR) (options: Gap-1 audit covers every table row and each burned estate's recorded-or-absent keys (Part of #4704) #6284)
  Done when: every Gap-1 option has a row (modelled, honoured by cobc, refused by name, or declared difference) and oracle and det port resolve the same effective options through one resolver, with a per-program test, evidence staleness on option change, and an options file per burned estate.
  Owner decision needed: (a) TRUNC(OPT) ruling (Option table for compiler options not yet modelled (ZONEDATA/INVDATA, CODEPAGE, SSRANGE/NUMCHECK, OPTIMIZE, TRUNC(OPT), ARITH(EXTEND)...) (#4704) #4706); (b) the provisional LE/Db2/CICS policies (Option table for LE runtime, Db2 precompile/bind and CICS region options (#4704) #4707); (c) does the cobolrt per-estate profile (cobolrt: take an explicit per-estate options profile instead of baked-in behaviour #4714) count here or stay separate?
  Out of scope here: the calibration hook (oracle policy: IBM is the reference, GnuCOBOL the instrument — audit register entries + z/OS calibration oracle #4702 Part 2).

Drafted 2026-10-18 by a Sonnet triage pass from this issue, its comments and the bodies of its "Part of" PRs; (verify) items were not checked against main. Tick boxes as slices merge; edit freely.