gnucobol-rs

Generated document (TRUST.4.DOCS). Machine authority: reports/claim-ladder.json + reports/casefiles/. Legacy source preserved losslessly under research/legacyreports/README.md.

gnucobol-rs is a Rust COBOL runtime and interpreter that is continuously differential-tested against stable and current GnuCOBOL. The project maintains a content-addressed, licence-checked valid-COBOL corpus of 6442 admitted units — 4732 programs extracted step-by-step from the GnuCOBOL native Autotest suite, 512 NIST CCVS85 units, the official manual examples, GnuCOBOL-shipped programs, the Open Mainframe Project course, and 1095 real-world X-COBOL programs — every unit classified under an explicit validity profile (oracle, dialect, source format, compiler options, copybooks, runtime configuration), executed through both the pinned GnuCOBOL 3.2 oracle and the native-Rust candidate, and reported with byte-level accuracy and per-phase first-failure attribution. A frozen held-out repository partition measures generalization, and scalable correctness-gated workloads measure parsing, checking, prepared execution and arithmetic throughput.

Under the hood it is a faithful 1:1 port of the entire GnuCOBOL 3.2 libcob runtime — all 13 admitted .c files — into safe Rust, proven byte-identical to a pinned, locally-built GnuCOBOL 3.2 oracle, plus an independently written interpreter (cobrun — the author's from-scratch claim; strict clean-room provenance is not independently verifiable from the committed record, see methodology) that parses and executes real COBOL programs on that runtime. No C is linked. It is not a library with tests; it is a compatibility court where "correct" never means "our reading of a spec" — it means byte-for-byte identical to the admitted cobc (GnuCOBOL) 3.2.0, where every claim is mechanically chained to a replayable receipt, and where every boundary is stated as loudly as every capability. The current corpus evidence: 1910 valid executable programs, 3222 valid compile-only programs, 70 valid module programs, and 196 byte-identical observable matches in the testsuite differential lane.**

COBOL's bedrock is its byte layout — COMP-3, zoned decimal, edited PICTURE, fixed-record offsets — far more than its syntax. gnucobol-rs reproduces that bedrock exactly, then runs a verified slice of the language on top of it. The discipline is the product: nothing is asserted because we read the spec that way; a claim is admitted only when a live differential sweep against the built oracle produces identical bytes, and sealed only when its evidence — fixtures, receipt, SARIF, in-toto statement, and explicit non-claims — is committed and mechanically re-derivable. If the bytes would diverge today, the gate goes red and publishing is blocked. The core crate is #![forbid(unsafe_code)].

The goal, if useful, is:

1. A parallel implementation following upstream for users that require memory safety,
2. Performance increases,
3. More compatible easier installation from crates.io on more OSs as well as,
4. Deeper forensic receipt proofing and,
5. The ability to emit ultra verbose forensic residuals at compile. This would allow shims to parse/replay data in new ways (hopefully useful).

NIST CCVS85 differential vs GnuCOBOL 3.2

The admitted NIST CCVS85 v4.0 corpus — 512 units (459 COBOL + 51 CLBRY + 2 DATA) — is materialized and executed through both the pinned GnuCOBOL 3.2 oracle and the native-Rust cobrun front-end in an isolated Docker environment (GNURUST.CCVS85.2/.3/.4). The oracle compiles 370 of 391 executable candidates and runs 304 of them; cobrun accepts and executes 87 and fails closed on the rest, with 27 byte-identical raw-output matches, 42 output divergences, and 16 generated-file divergences — every unit explicitly classified (0 timeouts), none silently dropped, and the two-run determinism verified in fresh containers. One-command replay: bash lab/ccvs85/run-docker.sh · full ledger: reports/ccvs85/summary.md.

The replay uses a dedicated rootless Docker daemon whose mutable state is stored beneath $GNURUST_CCVS85_DOCKER_ROOT. The location is configurable and should point to a filesystem with substantial free space. The harness verifies that it is not connected to the production Docker socket and that all daemon data, build cache, temporary files, and outputs remain beneath the configured root.

export GNURUST_CCVS85_DOCKER_ROOT=/path/on/a-large-filesystem/gnucobol-rs
export GNURUST_CCVS85_BASE_IMAGE=/path/to/ubuntu-minimal-image.tar
bash lab/ccvs85/run-docker.sh

---

What it is, in one minute

• A native-Rust libcob — the GnuCOBOL 3.2 runtime, ported statement-by-statement and oracle-sealed.
• A turn-key interpreter (cobrun) — feed it a .cob file, it runs, output matches cobc -x byte-for-byte across the corpus sweep. No cobc, no libcob linked.
• A C-ABI shim (gnucobol-rs-ffi) — drop it in where you would link libcob (cob_move, cob_get_int, …).
• A compatibility court — 176 sealed courts, each backed by a forensic case file and a one-command replay.

Three axes, never conflated (as of gnucobol-rs 0.8.57): (1) the libcob runtime — 13/13 files ported 1:1, oracle-sealed = 100% · (2) the whole GnuCOBOL 3.2 source tree — 88/329 files built natively (27%), every file accounted-for (0 unevidenced gaps) · (3) the cobrun front-end — runs a sweep-verified slice of the language, every passing program byte-identical to cobc, boundaries marked. “100%” on this page always means axis (1), the runtime — never the whole tree, never the full language. Authorities: FILE-PARITY.md (axis 2) · COBOL-PARITY.md (axis 3) · STATUS.md (live current-state — wins on any disagreement). 176 sealed courts · MSRV 1.74.

---

The scope, honestly

Three independent parity views cross-check the libcob runtime — axis (1), not the whole 329-file tree (axis 2) or the full language (axis 3) so a doc-comment can never masquerade as a port — all at runtime-100% / 0 gaps:

• 13/13 libcob source files ported 1:1 to safe Rust, oracle-sealed — call, cconv, common, cobgetopt, fileio, intrinsic, mlio, move, numeric, reportio, screenio, strings, termio. Not a subset of the runtime. The runtime.
• Doxygen C-parse view: 998/998 functions.
• Typed C↔Rust symbol-map view: 1156 active + 13 inactive mirrors, 0 missing.
• Gap ledger (GAP-ANALYSIS.md): 105 gaps catalogued, all 105 fixed, 0 open.
• All 110 intrinsic functions ported as cob_intr_*; the front-end evaluates 94 of them byte-identical to cobc.

Live coverage is generated and gated, never asserted by hand: COBOL-PARITY.md enumerates every verb / intrinsic / clause and what actually runs; FILE-PARITY.md accounts for every GnuCOBOL 3.2 source file with no unevidenced gaps.

---

See it run

A small program, executed by cobrun on the ported Rust runtime — no cobc, no libcob linked:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. DEMO.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  PRINCIPAL  PIC 9(5)V99 VALUE 1000.00.
       01  RATE       PIC V999    VALUE 0.075.
       01  INTEREST   PIC 9(5)V99.
       01  OUT-LINE   PIC $$$,$$9.99.
       PROCEDURE DIVISION.
           COMPUTE INTEREST ROUNDED = PRINCIPAL * RATE
           MOVE INTEREST TO OUT-LINE
           DISPLAY "INTEREST: " OUT-LINE
           STOP RUN.

$ cobrun demo.cob
INTEREST:    $75.00

That stdout is byte-identical to cobc -x demo.cob && ./demo — proven, not asserted: every program in the front-end corpus is compiled and run through the admitted real cobc and through cobrun, with cmp -s requiring identical stdout and the gate requiring zero failures (FAIL=0). Passing programs are additionally diffed against a second oracle, GnuCOBOL 3.1.2, for version stability.

Prefer the runtime as a library? The same packed-decimal and MOVE semantics are reachable directly — #![forbid(unsafe_code)], no GMP, no libcob, no FFI — or under libcob's own cob_field C ABI via gnucobol-rs-ffi (drop-in cob_move / cob_get_int / cob_set_int, verified byte-identical to real libcob by tests/verify_vs_libcob.sh).

---

Who this is for

• Migration & re-platforming teams who need byte-trust, not vibes: a way to read mainframe COMP-3 / zoned / EBCDIC records in Rust and prove the bytes match what the COBOL runtime produces — a COMP-3 sign nibble, a zoned overpunch, an OCCURS DEPENDING ON length, a truncating MOVE. Any one of these silently corrupts money; here every layout decision is judged against the real compiler's output, not a re-reading of the standard.
• Rust projects that need COBOL data semantics without linking C: PIC arithmetic, edited pictures, MOVE conversions, fixed-record layout — in a #![forbid(unsafe_code)] crate.
• Auditors & reviewers who want a replayable evidence trail, not assertions: every claim names its oracle, its fixtures, the version that sealed it, and what would break it; one command replays the lot on your machine.

---

What it is today

Live coverage is generated and gated, never hand-asserted — see COBOL-PARITY.md (every verb / intrinsic / clause and what runs) and FILE-PARITY.md (every GnuCOBOL 3.2 source file, accounted for).

As of gnucobol-rs 0.8.57 (2026-06): 13/13 libcob files ported 1:1 · 110/110 intrinsics in the runtime · 176 sealed courts.

Layer	State
libcob runtime	100% ported (13/13 admitted files), oracle-sealed. MOVE · arithmetic · pure-Rust decimal · COMP-3 / zoned / binary · edited PICTURE · DATA DIVISION layout · COPY/REPLACING · OCCURS DEPENDING ON · files · intrinsics — every admitted libcob source file is 1:1 in safe Rust, cross-checked by all three parity views.
Intrinsic functions	110/110 ported as cob_intr_* in the runtime; the front-end evaluates 94/110 (85%) in FUNCTION … references, each byte-identical to the oracle.
Front-end interpreter (cobrun)	An independently written COBOL parser + executor on the ported runtime (the author's from-scratch claim; strict clean-room provenance is not independently verifiable from the committed record) — no cobc, no libcob linked. Runs a growing, sweep-verified subset (~57 verbs incl. MOVE / arithmetic / COMPUTE with full + - * / ** grammar, parens & precedence, and ROUNDED; IF/EVALUATE; PERFORM TIMES/UNTIL/VARYING; GO TO … DEPENDING; tables; sequential files; 88-levels; numeric-EDITED output; ~110 dispatched intrinsics) to stdout proven byte-identical to cobc across the corpus sweep. Out-of-subset constructs fail closed.
CLI parity	cobrun --runtime-config reproduces cobcrun --runtime-config byte-for-byte (native port of libcob's print_runtime_conf, common.c:9762); plus -std=NAME, -fixed/-free, honest --version that identifies as gnucobol-rs reproducing GnuCOBOL 3.2.0 — never masquerading as cobc.
C ABI	gnucobol-rs-ffi exposes the ported algorithms under libcob's cob_field C ABI (drop-in cob_move / cob_get_int / cob_set_int / …), verified byte-identical to real libcob.

Of 66 COBOL verbs total, the runtime backs 51 (77%) and the front-end runs 58 (88%) — enumerated live in COBOL-PARITY.md.

---

What it does NOT claim

State the boundaries as loudly as the capabilities — they are the credibility. The runtime port is complete (100% across all three parity views); the remaining frontier is the interpreter front-end. Crucially, gnucobol-rs distinguishes a latent-work item (a future task) from a BOUNDARY (a surface the GnuCOBOL 3.2 oracle itself cannot run, so there is no byte-truth to match).

• No native code generation. gnucobol-rs interprets directly on the ported runtime; it does not reproduce cobc's C-emission (codegen.c / codeoptim.c) — a deliberate non-goal, not a gap. cobrun <file> equals cobc -x <file> only at observable stdout, never in artifacts. Correctness is oracle-judged, not self-asserted.
• The front-end is a verified subset, not the whole grammar. The parser / scanner / preprocessor / typecheck reproduce a sweep-verified slice (byte-identical over the 193-program front-end sweep plus the 6442-unit valid-COBOL corpus: 1910 valid executables, 3222 valid compile-only, 70 valid modules, with 196 byte-identical observable matches in the testsuite lane). Out-of-subset constructs — group items, OCCURS/REDEFINES, non-01 levels, unlisted verbs — return a typed RunError and exit 2, never a silent mis-run.
• 16 intrinsics not wired into the front-end — classified boundaries, not latent work: 15 have no fixed oracle output (cobc rejects them — DISPLAY-OF, NATIONAL-OF, BOOLEAN-OF-INTEGER, BINOP, STANDARD-COMPARE, separators; MODULE-PATH is a compiled-binary artifact), and RANDOM is a deliberate boundary (it depends on GMP's internal Mersenne-Twister; the port does not link or reproduce libgmp internals).
• 8 verbs unrun — every one an explicit BOUNDARY the 3.2 oracle itself cannot run (5 COMMUNICATION SECTION verbs, ACUCOBOL GUI INQUIRE/MODIFY, ENTRY in a nested program).
• cobc's diagnostic / help text is not reproduced byte-for-byte — the interpreter has its own error model (a deliberate scope limit). Localized (non-C.UTF-8) runtime messages are an explicit off-oracle non-claim. cob-config is documented but not provided; the cobcrun dynamic module loader / CALL dispatch reproduce a documented subset.
• Declared non-goals: cobc's C codegen, and USAGE NATIONAL (UTF-16) — which GnuCOBOL 3.2 itself marks unfinished and won't compile in the explicit form.
• Independent project. Reproduces GnuCOBOL 3.2; not affiliated with or endorsed by the GNU project. The runtime is a faithful copyleft derivative, not clean-room — see License & derivation below.

The machine-readable registry of every refused surface is reports/negative-capabilities.json (human ledger: docs/negative-capabilities.md). A sealed governance invariant enforces that negative claims must be ≥ positive claims — currently 578 refused surfaces.

---

How "correct" is defined: the admitted oracle

There is exactly one source of truth: upstream GnuCOBOL 3.2 (cobc + libcob). Because it is not installed system-wide, it is built from pinned source (research/gnucobol-3.2.tar.lz, sha256 recorded in reports/admission/) into a gitignored lab/oracle/prefix — x86-64, C.UTF-8, default dialect, COMP big-endian. Every byte claim in this repo means matches that built binary on a fresh run. The oracle's ABI / dialect / config is itself bound as evidence (GNURUST.BUILD.PROFILE.1). When the oracle is present, the documentation gate re-runs ~20 live differential sweeps and requires FAIL=0 on a fresh run before anything ships.

---

Verify it yourself (≈ 10 minutes)

One command replays every sealed court and prints a PASS table:

bash lab/verify-sealed-courts.sh      # all differential sweeps + shim suite + doc-gate (needs the built oracle)

No oracle built yet? The self-contained court tests run with zero external dependencies, and oracle-dependent checks degrade to typed skipped — never a silent pass:

cargo test                                  # self-contained court tests, no oracle needed
cargo run -p xtask -- receipt check         # receipts == live replay, no hand-edits

The front-end's own proof harness compiles and runs every program in lab/corpus/frontend/ through both real cobc and cobrun, requiring byte-identical stdout (passing programs are also differentially checked against GnuCOBOL 3.1.2, with documented per-program exemptions):

bash lab/oracle/cobol_frontend_sweep.sh     # 193-program front-end byte sweep, gate FAIL=0
bash lab/valid-corpus/run-docker.sh        # 6442-unit corpus pipeline (extract+replay+candidate+unify+gate)

Reviewer entry points — STATUS.md (live current-state authority) · COBOL-PARITY.md / FILE-PARITY.md (live language + file coverage) · GAP-ANALYSIS.md (105/105 catalogued gaps fixed, 0 open) · reports/negative-capabilities.json (non-claims) · reports/casefiles/ (176 forensic case files).

---

Compatibility as a stack of courts

gnucobol-rs treats COBOL compatibility as a stack of separately admitted courts — bytes, moves, the field model, record layout, initialization, comparison, formatting, source expansion, runtime lifecycle, files, intrinsics, and the executing front-end — where no lower layer is allowed to imply a higher one. Passing the decimal-MOVE court says nothing about files; each court stands on its own evidence, naming its byte domain, oracle, fixture count, sealing version, and what would break it. A few marquee courts:

Court	What it seals
GNURUST.2	decimal MOVE — COMP-3 / zoned / display byte conversions
GNURUST.3	the PIC field model (incl. P-scaling)
GNURUST.7 / GNURUST.13	arithmetic ADD/SUB/MUL · packed BCD add/subtract
GNURUST.16 / GNURUST.16C	edited-PICTURE decode and encode
GNURUST.FILEIO.*	sequential / relative / indexed / SORT runtime I-O (INDEXED on a pure-safe-Rust B-tree)
GNURUST.INTRINSIC.*	LENGTH, NUMVAL(-C), INTEGER, MOD/REM, CASE, ORD/CHAR, dates
GNURUST.LINEAGE.CORPUS.20M.1	a completed 20M real-cobc COBOL-witness lineage run
GNURUST.FRONTEND.1	the independently written front-end: parse + execute a subset to cobc-identical stdout (provenance-qualified in the methodology docs)

Of the 176 sealed courts, 140 are GNURUST.* (the open LGPL runtime + front-end layer); 31 are KOBOLD.*; the remainder are framework courts. The machine-readable form is reports/claim-ladder.json, and each court's full forensic record (casefile.json + SARIF 2.1.0 + in-toto v1 + DSSE envelope) lives under reports/casefiles/.

The full 176-court ledger is in docs/sealed-courts.md.

The KOBOLD.* courts belong to downstream, independently-written Apache-2.0 crates that use this runtime (operator trust layer, fixed-record reconciliation, banking packets). They ship and are documented in their own repositories, not here.

---

Breadth of verification

• 109 differential oracle sweep scripts (lab/oracle/*sweep*.sh), each byte-for-byte vs the admitted GnuCOBOL 3.2, spanning arithmetic/numeric, edited/PICTURE/encoding, data movement/tables, control flow, files/I-O, strings, screen I/O (9 native terminal-byte courts), intrinsics/dates, and CALL/interop.
• Valid-COBOL corpus (Phase 12 unified ledger, reports/valid-corpus/): 6442 admitted units — 4732 step-extracted GnuCOBOL Autotest programs, 512 NIST CCVS85 units (the 4.3 MB newcob.val.Z, held under the GNURUST.CCVS85.1 custody gate), the official manual examples, GnuCOBOL-shipped programs, 30 Open Mainframe Project course programs, and 1095 real-world X-COBOL files — every unit classified (no UNKNOWN), exact + near duplicates identified, licences decided or quarantined, and a frozen held-out partition kept for generalization measurement. Front-end corpus (lab/corpus/frontend/): the 193 hand-authored programs plus the earlier lab/corpus/ collections (533 public GnuCOBOL-test-corpus programs, 53 open-banking programs).
• Diagnostic-unblocked testsuite lane (methodology below): a mechanically restricted derivative of the upstream Autotest suite that exposes later semantic checks hidden behind exact compiler-diagnostic wording — 377 of 404 affected groups progress further and 140 later semantic checks become reachable when only proven diagnostic expectations are ignored (exit statuses, commands, source, runtime output and generated-file expectations all stay exact).
• Three independent parity maps cross-check so a doc-comment can never masquerade as a port: DOXYGEN-PARITY (998/998 fns), LIBCOB-PARITY / PORT-INDEX (typed C↔Rust symbols, 100% active), and CLANG-AST-PARITY (870 defs / 3240 call edges). See COBOL-PARITY.md, FILE-PARITY.md, DOXYGEN-PARITY.md, LIBCOB-PARITY.md, CLANG-AST-PARITY.md, FUNCTION-EVIDENCE.md, and the 0–7 PORTING-LADDER.md (level 7 = compiler replacement, explicitly NOT CLAIMED; level is evidence shape, not quality).

---

The diagnostic-unblocked testsuite lane (methodology)

The upstream pristine testsuite remains untouched. A mechanically restricted derivative lane (lab/gnucobol-testsuite/run-diagnostic-unblocked-docker.sh) replaces ONLY proven compiler-diagnostic expected streams with Autotest ignore — preserving commands, exit statuses, COBOL source, runtime output, generated-file expectations, environment, ordering and skip/xfail semantics — then regenerates the real suite with the upstream build mechanism (make -C tests testsuite). Its purpose is to expose later semantic checks that exact diagnostic wording would otherwise prevent from running; it is not a compatibility authority and its results are not pristine-suite passes. The transformer decides solely from the upstream test structure (never from candidate behaviour), the patch regenerates byte-identically, and an independent gate parses the actual diff and proves every hunk is legal (24 adversarial unit tests).

Machine evidence: transformation manifest transformations.json · patch diagnostic-ignore.patch · semantic reachability semantic-reachability.md · pristine-vs-unblocked reconciliation pristine-vs-diagnostic-unblocked.md · claim boundaries claim-boundaries.md. Replay: bash lab/gnucobol-testsuite/run-diagnostic-unblocked-docker.sh.

---

Crates

Crate	Derives from	License	Scope	unsafe
gnucobol-rs	libcob/*.c (move, numeric, common, intrinsic, fileio, …)	LGPL-3.0-or-later	the native-Rust libcob runtime (1:1, oracle-sealed) + the cobrun interpreter front-end	forbid
gnucobol-rs-ffi	libcob common.h C ABI	LGPL-3.0-or-later	a cob_field C-ABI shim — link it where you would link libcob	allow (confined to the raw-pointer shim)
cobc-oracle-rs	drives cobc (no GPL code copied)	GPL-3.0-or-later	spawns cobc, captures deterministic canonical-JSON receipts	forbid
gnucobol-rs-ccvs85	none — court harness	LGPL-3.0-or-later	NIST CCVS85 differential court: materialize, oracle baseline, rust candidate, classification, receipts, gates	forbid
gnucobol-rs-port-index	none — port-governance index	LGPL-3.0-or-later	typed C↔Rust symbol parity + the parity/doxygen/clang/evidence map generators	forbid
gnucobol-rs-testsuite	none — court harness	LGPL-3.0-or-later	GnuCOBOL 3.2 native Autotest-suite differential court: inventory, census, classification, determinism, gates	forbid

The runtime additionally depends on gnucobol-rs-bdb-format (a pure-safe-Rust Berkeley DB B-tree, for INDEXED organization).

---

License & derivation boundary

Legal skim, in one line: the runtime is a faithful LGPL-3.0-or-later derivative of libcob — ported statement-by-statement with upstream line citations (e.g. // move.c:477), so it is not clean-room and its license was not freely chosen; the cobrun front-end is independently written (the author's from-scratch claim; strict clean-room provenance is not independently verifiable from the committed record) but ships inside the LGPL crate; the cobc-driving tooling is GPL-3.0-or-later.

How the runtime and parser were produced

The two halves of this project have different derivation models, and the wording matters:

• Runtime (crates/gnucobol-rs): a faithful Rust port/derivative of the admitted GnuCOBOL 3.2 libcob sources — read directly and mirrored statement-by-statement with upstream line citations (// move.c:477), inheriting LGPL-3.0-or-later. It is not clean-room, and its license was not freely chosen. Full method: docs/methodology/libcob-rust-port.md
  • machine record reports/methodology/libcob-port-provenance.json.
• Parser/front-end (src/frontend.rs + cobrun): an independently written COBOL lexer/parser/ executor, developed against the built oracle (behavioral differential), per the author's committed from-scratch claim. Strict "clean-room" process separation cannot be independently verified from the committed record (the tooling/consulted-materials history is UNKNOWN). Full audit: docs/methodology/parser-front-end-provenance.md
  • machine record reports/methodology/parser-provenance.json.

Because the runtime inherits upstream copyleft, a distributed binary that statically links the LGPL core is a Combined Work under LGPL-3.0 §4. The FSF copyright and original-author credits (Nishida, While, Sobisch, et al.) are retained in every ported file header; COPYING.LESSER (LGPL v3) and COPYING (GPL v3) are shipped. Do not describe the runtime as "clean-room" — the authoritative statement is docs/derivation-and-license.md, with the boundary detailed in docs/license-boundaries.md. The permissive downstream satellites (kobold-*, Apache-2.0) are independently written and merely use the core.

This is an independent effort and is not the upstream GnuCOBOL project, nor endorsed by it.

---

Project status, features & MSRV

• Feature flags never change semantics — they gate optional surfaces (e.g. parallelism), never the bytes a court seals.
• Workspace: resolver 2, MSRV 1.74 (inherited), workspace lint unsafe_code = "forbid", [profile.release] overflow-checks = true.
• The runtime port is complete across all three parity views; active development is in the front-end interpreter (the 25 PARTIAL files under cobc/ + bin/), tracked live in COBOL-PARITY.md and bounded by the non-claims above.

---

Method

Admit pinned source → read it → build the real upstream as an executable oracle → port faithfully with citations → prove byte parity over a fixture matrix + differential sweep → pin or classify every confounder → Kani the sharp invariants → fuzz the hostile surface → gate → seal with receipts and exact non-claims. Each byte court carries both a Kani proof and a fuzz target (gate-enforced), plus a forensic case file. A documentation refresh gate (lab/check-docs.sh, cargo run -p xtask -- docs check) runs alongside fmt/clippy/test/sweep and fails if any doc, receipt, or coverage map drifts from the code or the oracle — so nothing goes stale as the register grows. Depth on method, taxonomy, and the risk register lives in docs/.

---

Repository map

Map	What it answers
STATUS.md	live current-state authority (it wins on any disagreement)
COBOL-PARITY.md	every verb / intrinsic / clause and exactly what runs
FILE-PARITY.md	every GnuCOBOL 3.2 source file accounted for, 0 unevidenced gaps
GAP-ANALYSIS.md	the catalogued C→Rust gap ledger (105/105 fixed, 0 open)
DOXYGEN-PARITY.md	the Doxygen C-parse function-parity view (998/998)
LIBCOB-PARITY.md / CLANG-AST-PARITY.md	typed C↔Rust symbol parity · clang-AST def/call-edge parity
PORTING-LADDER.md	the 0–7 evidence hierarchy (level 7 explicitly NOT CLAIMED)
docs/	method, taxonomy, derivation/license, risk register, planning

---

_{Generated document — DO NOT EDIT BY HAND. Rendered by xtask from docs-src/README.model.json and machine evidence (reports/claim-ladder.json, reports/casefiles/, Cargo.toml, live receipts). Regenerate with cargo run -p xtask -- docs generate; verify freshness with cargo run -p xtask -- docs check. The prior hand-written README is preserved losslessly under research/legacyreports/README.md; its claims are carried forward in full by this generated body. Counts are dated and version-anchored to STATUS.md, the living authority.}