opencrbasic 1.1.0__tar.gz → 1.1.1__tar.gz

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opencrbasic
-Version: 1.1.0
+Version: 1.1.1
 Summary: Open-source re-implementation of the Campbell Scientific CRBasic pre-compilers (CR6, CR1000X, CR300, CR350)
 Project-URL: Repository, https://github.com/UtrechtUniversity/open-crbasic
 Author: Utrecht University
@@ -38,8 +38,8 @@ Status, measured against the real compilers: `PROGRESS.md`. Design and the v1.0
 ## Scope
 
 - **Gated profiles: CR6 and CR1000X.** On these, v1.0 gates the reference verdict in the relevant
-  area (the FirnMelt/GEUS instruction set and language constructs), the execution mode, and the
-  first error for realistic mistakes on relevant rules, measured on the FirnMelt programs, the 507
+  area (the station/GEUS instruction set and language constructs), the execution mode, and the
+  first error for realistic mistakes on relevant rules, measured on the station programs, the 507
   CRBasic help examples, the 66 GEUS programs, the saved fuzz replay and fresh `--relevant` fuzz
   seeds. The help examples and GEUS programs are not redistributed here; see
   [tests/corpus/README.md](tests/corpus/README.md) for running against local copies. One relevant-area false accept is known: a `Sub` name that is also another routine's
@@ -159,8 +159,7 @@ result.tables  # list of tdf.TdfTable (Status, DataTables, DataTableInfo, ConstT
 `parser.parse_file()` gives the syntax tree (`syntax.py`) for other tools.
 
 [openloggernet](https://github.com/UtrechtUniversity/open-loggernet) uses opencrbasic when
-`CR6COMP=opencrbasic` is set, and the FirnMelt station repository compiles every program with it in
-CI.
+`CR6COMP=opencrbasic` is set.
 
 ## Editor support
 

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/README.md

@@ -21,8 +21,8 @@ Status, measured against the real compilers: `PROGRESS.md`. Design and the v1.0
 ## Scope
 
 - **Gated profiles: CR6 and CR1000X.** On these, v1.0 gates the reference verdict in the relevant
-  area (the FirnMelt/GEUS instruction set and language constructs), the execution mode, and the
-  first error for realistic mistakes on relevant rules, measured on the FirnMelt programs, the 507
+  area (the station/GEUS instruction set and language constructs), the execution mode, and the
+  first error for realistic mistakes on relevant rules, measured on the station programs, the 507
   CRBasic help examples, the 66 GEUS programs, the saved fuzz replay and fresh `--relevant` fuzz
   seeds. The help examples and GEUS programs are not redistributed here; see
   [tests/corpus/README.md](tests/corpus/README.md) for running against local copies. One relevant-area false accept is known: a `Sub` name that is also another routine's
@@ -142,8 +142,7 @@ result.tables  # list of tdf.TdfTable (Status, DataTables, DataTableInfo, ConstT
 `parser.parse_file()` gives the syntax tree (`syntax.py`) for other tools.
 
 [openloggernet](https://github.com/UtrechtUniversity/open-loggernet) uses opencrbasic when
-`CR6COMP=opencrbasic` is set, and the FirnMelt station repository compiles every program with it in
-CI.
+`CR6COMP=opencrbasic` is set.
 
 ## Editor support
 

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencrbasic"
-version = "1.1.0"
+version = "1.1.1"
 description = "Open-source re-implementation of the Campbell Scientific CRBasic pre-compilers (CR6, CR1000X, CR300, CR350)"
 readme = "README.md"
 license = "MIT"
@@ -31,7 +31,8 @@ crbc-lsp = "opencrbasic.lsp.server:main"
 # `uv sync` installs `dev` by default: the test runner and the reverse-engineering tools
 # (`tools/extract_tables.py`, `tools/message_catalog.py` read the exe with pefile), and pygls
 # so the suite can test the language server; pytest-xdist for parallel test runs (`-n`); pyrefly
-# checks the repository (`[tool.pyrefly]`); pre-commit runs ruff and pyrefly before each commit.
+# checks the repository (`[tool.pyrefly]`); pre-commit runs ruff and pyrefly before each commit;
+# openloggernet drives a logger for `tools/logger_oracle.py`.
 dev = [
     "pytest>=8",
     "pefile>=2024.8.26",
@@ -39,6 +40,7 @@ dev = [
     "pytest-xdist>=3.6",
     "pyrefly==1.3.1",
     "pre-commit>=4",
+    "openloggernet>=0.3.0",
 ]
 
 [build-system]

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/__init__.py

@@ -1,3 +1,3 @@
 """Open-source CRBasic (CR6) pre-compiler."""
 
-__version__ = "1.1.0"
+__version__ = "1.1.1"

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/analysis.py

@@ -14,7 +14,7 @@ from .compiler import compile_file
 from .sources import DiskSource, LimitedSource, OverlaySource, RecordingSource, SourceProvider
 
 API_VERSION = 2  # 2: findings, notices, config_error, AnalysisRequest.checks (M6)
-DOCS = "https://github.com/UtrechtUniversity/firnmelt-datalogger/blob/main/opencrbasic/"
+DOCS = "https://github.com/UtrechtUniversity/open-crbasic/blob/main/"
 
 
 def _no_overlays() -> Mapping[Path, bytes]:

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/__init__.py

@@ -953,10 +953,9 @@ def _check(program: S.Program, profile: Profile, diags: Diagnostics, result) ->
 
     if not diags.errors:
         # `When Main Sequence Scan %d is running, background calibration will be disabled.`:
-        # round 6, moved here from the unconditional `warnings.check_early` call above -- oracle-
-        # confirmed *not* ungated the way `_check_reachability`/`_check_fnotch` are, unlike this
-        # module's own docstring previously claimed for all of `check_early` (`checker/warnings.py`'s
-        # `check_background_calibration` docstring has the oracle evidence). Independent of
+        # oracle-confirmed *not* ungated the way `_check_reachability`/`_check_fnotch` are
+        # (`checker/warnings.py`'s `check_background_calibration` docstring has the oracle evidence).
+        # Independent of
         # `tables_hook`'s own availability, so called ahead of that guard rather than inside it.
         _run_pass(warnings.check_background_calibration, program, profile, diags, env)
         _run_pass(warnings.check_slow_scan_skips, program, profile, diags, env)

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/cr3xx.py

@@ -389,9 +389,8 @@ def check(program: S.Program, profile, diags: Diagnostics) -> None:
 # `acceptdatarecords_1.CR6`, `SerialOpen (COMC1,...)`'s `COMC1 is not defined.` taints every
 # following two-plus-argument instruction to end of file, `Scan`'s own `Sec` and
 # `AcceptDataRecords`'s own `32769`, despite that finding being **ungated** and thus, in this
-# project's own pass model, skipping tier B -- where the *previous*, narrower version of this
-# function lived -- entirely), this is no longer called from inside the `if not diags.errors:`
-# tier-B block the way `check_expr_cascade` was: `checker/__init__.py` now calls it once,
+# project's own pass model, skipping tier B entirely), this is not called from inside the
+# `if not diags.errors:` tier-B block: `checker/__init__.py` calls it once,
 # unconditionally, after every other diagnostic-producing pass has run, so it can see -- and rewrite
 # -- the complete, final diagnostic list regardless of which tier first tainted the file. It is
 # still a no-op when nothing in the file ever taints (no `_is_cascade_trigger` match and no
@@ -555,7 +554,7 @@ def check_too_many_cascade(program: S.Program, profile, diags: Diagnostics) -> N
     """CR300/CR350 only; a no-op on every other logger and when nothing in the file ever taints
     (see this module's comment above for the oracle evidence and the exact shape implemented).
     Called from `checker/__init__.py` once, unconditionally, after every other pass -- see that
-    comment for why this can no longer be tier-B-only the way `check_expr_cascade` was.
+    comment for why this cannot be tier-B-only.
     """
     if profile.name not in ("cr300", "cr350"):
         return

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/expressions.py

@@ -25,9 +25,8 @@ _TYPE_CODES_PATH = Path(__file__).resolve().parent.parent / "data" / "type_codes
 # separate function (`4`/`16`/`17`/`19` `FUN_004b5db0`, a different failure message). Restricting
 # to this explicit include-list (rather than excluding the handful of kinds known *not* to
 # resolve) is deliberate: the default for an unrecognised kind is "don't check", so a gap in this
-# list only under-reports, never falsely rejects (AGENTS.md's priority order); the `ConstTable`
-# regression this session found during development (`crbasic/Main.CR6`'s
-# `ConstTable(GlobalConfigTable)`, kind `expr_marker`) is the concrete case that shape of bug
+# list only under-reports, never falsely rejects; the station corpus's `Main.CR6`
+# `ConstTable(GlobalConfigTable)` (kind `expr_marker`) is the concrete case that shape of bug
 # looks like.
 _RESOLVED_KINDS = frozenset(
     {
@@ -74,8 +73,7 @@ _CONST_FAMILY_KINDS = frozenset({"const_expr", "const_expr_only", "datatype_kw"}
 # separate `FooBar is not defined.` / `BazQux is not defined.` lines on CR300/CR350, in the source
 # (left-to-right) order `_undefined_names` already walks in. Modelled below as a plain per-logger
 # branch on `profile.name` (both loggers in each pair share identical behaviour, oracle-confirmed
-# side by side) rather than a new `Profile` field, to keep this session's change inside
-# `checker/expressions.py`/`checker/symbols.py` (`PLAN.md`'s ownership split).
+# side by side) rather than a new `Profile` field.
 _WHOLE_EXPR_ECHO_LOGGERS = frozenset({"cr6", "cr1000x"})
 
 # `NAN`/`INF` are accepted as predefined float constants on all four loggers (oracle-confirmed,

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/instr_data.py

@@ -45,13 +45,11 @@ from . import symbols
 # `docs/instructions.md`'s "not independently oracle-confirmed" list for exactly which those are.
 # One more call site exists (the unlabelled string `"Et"`, near the `SampleFieldCal` call site)
 # that could not be attributed to a specific instruction with confidence and is deliberately left
-# out -- AGENTS.md: never guess into a false reject. The other originally-unlabelled string this
-# round found nearby, `"FFT"`, *was* independently confirmed (a fresh scratch probe, `tfft.cr6`,
-# and two CHM corpus files whose `DataTable` bodies contain only `FFT(...)` calls, `fft_1.CR6`/
-# `covspa_1.CR6` -- both were a **false-reject regression** this round's own full difftest re-run
-# caught, from `check_table_structure`'s sibling `Table %s declared with no output fields.` rule
-# below not yet recognising `FFT` as a field producer, before `FFT` was added here too) and is
-# included as `FFT`.
+# out: never guess into a false reject. The other unlabelled string nearby, `"FFT"`, is
+# independently confirmed (a scratch probe, `tfft.cr6`, and two CHM corpus files whose
+# `DataTable` bodies contain only `FFT(...)` calls, `fft_1.CR6`/`covspa_1.CR6`, which compile
+# only when `FFT` also counts as a field producer for `Table %s declared with no output
+# fields.`) and is included as `FFT`.
 TABLE_ONLY_INSTRUCTIONS: dict[str, str] = {
     "CARDOUT": "CardOut",  # checked with the oracle
     "MQTTPUBLISHTABLE": "MQTTPublishTable",

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/instr_rules.py

@@ -1223,7 +1223,7 @@ def check_data_interval(program: S.Program, profile, diags: Diagnostics, env: co
       per-logger difference, not shared with CR300/CR350 (`_SCAN_VALUE_CHECK_LOGGERS`; found the
       same way as `check_scan_params`'s own CR300/CR350 gate, same session).
     - `DataTable interval %d uSec not integrally divisible by scan interval %d uSec.` (function
-      `FUN_004f6540`) -- project knowledge (`knowledge/crbasic/lessons.md` "`DataInterval` versus
+      `FUN_004f6540`) -- project knowledge (open-crbasic-skills `lessons.md` "`DataInterval` versus
       `Scan`": "a table interval must be at least the scan interval and an exact integer multiple
       of it", human-verified against `CR6Comp.exe`), reported at each `CallTable <name>` site whose
       table has a `DataInterval` and which sits directly inside a `Scan...NextScan` block (main

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/structure.py

@@ -2186,7 +2186,7 @@ def check_pass2(
     "Before `BeginProg`" only means the top level of the program, never a statement lexically
     inside a `Sub`/`Function` body (regardless of that body's own textual position, almost always
     before `BeginProg` itself, `docs/checker.md` "Pass model": found as a **regression** against
-    this repository's own `crbasic/Main.CR6` and several siblings, all of which call a built-in
+    the station corpus's `Main.CR6` and several siblings, all of which call a built-in
     function bare, with no `Call` keyword, e.g. `SerialOpen(...)` inside a `Function`/`Sub` defined
     above `BeginProg` -- perfectly ordinary CRBasic, since the body only executes when the
     `Sub`/`Function` is later called from inside `Scan`/`NextScan`, oracle-reconfirmed by re-running
@@ -5120,8 +5120,7 @@ def _check_array_dims(stmt: S.Declaration, diags: Diagnostics, env: consteval.En
     separate variables of the same declaration.
 
     A dimension that does not fold to a constant at all (`NotConstant`) is left alone: no oracle
-    evidence this session found supports guessing at that shape, and AGENTS.md's priority (never
-    reject an accepted program) rules out it.
+    evidence supports guessing at that shape, and a guess could reject an accepted program.
     """
     for index, v in enumerate(stmt.vars):
         before = len(diags.items)
@@ -5779,24 +5778,17 @@ def _check_alias_dims(
        check in this project) into a single **row-major flat offset** (`_alias_flat_offset`:
        `flat = i_n + sum_{k<n} (i_k - 1) * prod(d_{k+1..n})`, the ordinary multi-dimensional-array-
        as-flat-buffer formula, last index varying fastest) that must land in `[1,
-       prod(all declared dims)]`. Round 6's own original account of this check ("only the *first*
-       index is ever checked, however far out of range a later one is") is **superseded**: it was
-       built from two probes (`Public grid(3,3)`: `Alias grid(2,4) = Ts` compiles, `Alias grid(4,2)
-       = Ts` fails) that happen to *also* agree with the flat-offset formula purely by coincidence
-       (`(2-1)*3+4=7` and `(4-1)*3+2=11`, both landing on the correct side of `[1,9]` for unrelated
-       reasons) -- a fresh, wider oracle sweep this round (`docs/checker.md` "Round 7") found the
-       "first index alone" account is wrong in general: `Alias grid(4,-2) = Ts` (first index `4`,
-       out of `[1,3]` by the old account) **compiles clean** (`(4-1)*3+(-2)=7`, in `[1,9]`), while
-       `Alias grid(2,-1) = Ts` (a valid first index, an out-of-range *second* index by the old
-       account, which the old rule never checked at all) also compiles clean
-       (`(2-1)*3+(-1)=2`, in `[1,9]`) -- both correctly predicted by the flat formula, neither by
-       "only check position 0". A **scalar** (no declared dimensions at all) behaves exactly like a
+       prod(all declared dims)]`. Oracle evidence (`docs/checker.md` "Round 7"), for
+       `Public grid(3,3)`: `Alias grid(2,4) = Ts` compiles (`(2-1)*3+4=7`), `Alias grid(4,2) = Ts`
+       fails (`11`), and `Alias grid(4,-2) = Ts` (`7`) and `Alias grid(2,-1) = Ts` (`2`) both
+       compile clean: the first index is not checked on its own. A **scalar** (no declared
+       dimensions at all) behaves exactly like a
        size-1 array (`Public y` / `Alias y(1) = Ts` compiles, `Alias y(2) = Ts` fails: flat
        formula with `dims=(1,)` reduces to `flat=i1`, range `[1,1]`), which is why `declared_all_
        dims` maps every declared variable, not just array ones, the same convention `dim0_sizes`
        already used. Skipped (no check at all, under-reporting only) when any declared dimension or
        any index argument does not fold to a constant (`declared_all_dims`/the tuple-folding loop
-       below, both AGENTS.md-conservative the same way check 3 already was) or when the index
+       below, both conservative the same way check 3 is) or when the index
        tuple's own length does not match the variable's own declared dimension count (no oracle
        evidence gathered for that shape either way).
     3. **`Duplicate Alias`** (round 7; no trailing period, no echoed name): the source side's own

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/terminals.py

@@ -1,8 +1,8 @@
 """Per-logger analog-channel and port terminal model.
 
-Generalises the analog-channel range check (originally CR6-only, hard-coded `U1..U12`) across all
-four loggers, driven by oracle-probed per-logger data (`data/<logger>/terminals.json`; evidence,
-probes and the message-text differences: `docs/loggers.md`, `docs/instructions.md`).
+Models the analog-channel range check for all four loggers, driven by oracle-probed per-logger
+data (`data/<logger>/terminals.json`; evidence, probes and the message-text differences:
+`docs/loggers.md`, `docs/instructions.md`).
 
 Each logger's `terminals.json` names its own channel "kinds" -- CR6 has separate `u_terminal`
 (single-ended-shaped: any `U1..U12`, no oddness constraint; `ACPower`, `CS616`'s `CS616Chan`,

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checker/warnings.py

@@ -405,15 +405,10 @@ def check_background_calibration(program: S.Program, profile: Profile, diags: Di
     `Invalid symbol in expression` error present (`Delay never reached at run time.` alongside it,
     same probe file). A warning-only file (no errors, e.g. a reachability warning with no error
     anywhere) still gets *both* warnings together, confirming this is specifically errors, not "any
-    diagnostic", that gates it. Moved to `checker/__init__.py`'s own final `if not diags.errors:`
-    tier (alongside `warnings.check`/`tables_hook.attach`, the same "only on an otherwise-clean
-    compile" gate already used there) instead of `check_early`'s unconditional call site -- this is
-    the only change; the rule and message above are unchanged. Found as a side effect of developing
-    `instr_rules.check_scan_min_interval` (this round): dozens of pre-existing `false_accept`/
-    `message_diff` fuzz reproducers (`tests/corpus/fuzz/cr6/message_diff/ba333c2ee146.CR6` and
-    siblings) already showed this exact extra, spurious warning line alongside an unrelated real
-    error -- a genuine, previously-undocumented false-accept-shaped bug independent of this round's
-    own `Scan`-interval work, not a regression it introduced.
+    diagnostic", that gates it. It is therefore called from `checker/__init__.py`'s final
+    `if not diags.errors:` tier (alongside `warnings.check`/`tables_hook.attach`), not from
+    `check_early`'s unconditional call site. Fuzz reproducers such as
+    `tests/corpus/fuzz/cr6/message_diff/ba333c2ee146.CR6` cover the gate.
     """
     data = profile.background_calibration
     if not data:

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/checks.py

@@ -147,7 +147,7 @@ def _ambiguous_names(program: S.Program) -> set[str]:
 def _numeric_concatenation(program: S.Program, profile) -> list[Finding]:
     """OCB002: a String `+` (or `&`) assigned to a numeric variable (`L = 2000 + Mid(S,5,2)`). The
     reference accepts it, but `+` with a String operand concatenates, and the variable receives
-    the converted text: a GPS clock set this way read 2057 (`knowledge/crbasic/lessons.md` "`+` with
+    the converted text: a GPS clock set this way read 2057 (open-crbasic-skills `lessons.md` "`+` with
     a string operand concatenates", hardware 2026-10-22). Only a chain mixing numeric and String
     operands is reported: a String alone (`X = Mid(...)`) is a plain conversion, and Strings joined
     into a number's text (`X = HexStr(6) + "." + HexStr(7)`, GEUS programs) are deliberate."""
@@ -263,8 +263,8 @@ def _zero_divisors(program: S.Program, profile) -> list[Finding]:
 
 def _unsized_string_parameters(program: S.Program, profile) -> list[Finding]:
     """OCB005: a `Sub`/`Function` String parameter without `* size`. It holds 23 characters (24
-    bytes with the terminator) and a longer argument is cut (hardware, `knowledge/crbasic/
-    lessons.md` "Default string parameter size"). Information only: a short argument is fine."""
+    bytes with the terminator) and a longer argument is cut (hardware, open-crbasic-skills
+    `lessons.md` "Default string parameter size"). Information only: a short argument is fine."""
     return [
         Finding(
             "OCB005",
@@ -284,7 +284,7 @@ def _unsized_string_parameters(program: S.Program, profile) -> list[Finding]:
 def _unaligned_intervals(program: S.Program, profile) -> list[Finding]:
     """OCB006: a constant `DataInterval` that divides neither an hour nor a day (`7 Min`, `25 Hr`).
     Its records are phased from the start hour and may not align with midnight (hardware,
-    `knowledge/crbasic/lessons.md` "`DataInterval` phase"). Information only; an interval of 0
+    open-crbasic-skills `lessons.md` "`DataInterval` phase"). Information only; an interval of 0
     (every call) is not reported."""
     env, out = _const_env(program, profile), []
     for st in _statements(program):

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/cli.py

@@ -142,7 +142,7 @@ def _message_bytes(lines: list[str]) -> bytes:
     """`lines` joined the way the message file actually wants them: CRLF throughout, except the
     blank line straight after a `-- Compile Failed!` header, which the real exe writes as a bare
     LF (oracle-confirmed on both a plain failing compile and a `-t`/`-b` one, `docs/cli.md`
-    "Message file layout" -- previously assumed to be a uniform CRLF join, which this replaces).
+    "Message file layout").
     """
     if len(lines) >= 2 and lines[1] == "" and lines[0].endswith("Failed!"):
         return (lines[0] + "\r\n\n" + "\r\n".join(lines[2:]) + "\r\n").encode("latin-1", "replace")

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/src/opencrbasic/compiler.py

@@ -156,7 +156,7 @@ class CompileResult:
         # no-line `-u` warning, regardless of which included file declared it, prints before every
         # "table declared but never called" warning). `_no_line_kind` below reproduces that
         # ordering by message shape rather than by which module raised it, so this stays correct
-        # without `checker/warnings.py` (a concurrently-owned module) needing to tag its own
+        # without `checker/warnings.py` needing to tag its own
         # diagnostics; a stable sort keeps each kind's own relative (insertion) order within itself.
         # On one line the reachability warning follows that line's errors (oracle: 15 of 15 corpus
         # and fuzz transcripts); other warnings keep their check order.

{opencrbasic-1.1.0 → opencrbasic-1.1.1}/tests/corpus/README.md

@@ -1,21 +1,21 @@
-# Test corpora
-
-| Directory | Contents | In git |
-|---|---|---|
-| `firnmelt/` | The FirnMelt station programs and libraries, a snapshot of `crbasic/` in [firnmelt-station](https://github.com/UtrechtUniversity/firnmelt-station) at monorepo commit `bd4c30c1` (2026-11-01). Tests pin results to these exact files, so refresh them only together with the expectations. | yes |
-| `fuzz/` | Saved fuzz reproducers seeded from `firnmelt/`, replayed by `tools/fuzz_replay.py`. | yes |
-| `chm/` | The 507 complete example programs in Campbell's CRBasic help. | no |
-| `../../examples/Logger Programs/` | The 66 GEUS station programs used as a CR1000X corpus. | no |
-
-The help examples and GEUS programs belong to others and are not redistributed
-([docs/legal.md](../../docs/legal.md)). Tests that need them skip when they are absent. To run
-those tests locally:
-
-1. Extract the CRBasic help (the `.chm` installed with CRBasic Editor) into `extracted_chm/` at the
-   repository root, for example with `7z x CRBasic.chm -oextracted_chm`.
-2. `uv run python tools/extract_chm_examples.py` writes `tests/corpus/chm/`.
-3. Put the GEUS programs, if you have them, in `examples/Logger Programs/`.
-4. For the differential tools, copy the Campbell compilers into `compiler/` (README, "How it was
-   built").
-
-All of these paths are git-ignored.
+# Test corpora
+
+| Directory | Contents | In git |
+|---|---|---|
+| `station/` | A field station's CR6 programs and libraries (2026-11-01 snapshot). Tests pin results to these exact files, so refresh them only together with the expectations. | yes |
+| `fuzz/` | Saved fuzz reproducers seeded from `station/`, replayed by `tools/fuzz_replay.py`. | yes |
+| `chm/` | The 507 complete example programs in Campbell's CRBasic help. | no |
+| `../../examples/Logger Programs/` | The 66 GEUS station programs used as a CR1000X corpus. | no |
+
+The help examples and GEUS programs belong to others and are not redistributed
+([docs/legal.md](../../docs/legal.md)). Tests that need them skip when they are absent. To run
+those tests locally:
+
+1. Extract the CRBasic help (the `.chm` installed with CRBasic Editor) into `extracted_chm/` at the
+   repository root, for example with `7z x CRBasic.chm -oextracted_chm`.
+2. `uv run python tools/extract_chm_examples.py` writes `tests/corpus/chm/`.
+3. Put the GEUS programs, if you have them, in `examples/Logger Programs/`.
+4. For the differential tools, copy the Campbell compilers into `compiler/` (README, "How it was
+   built").
+
+All of these paths are git-ignored.