laddercodec 0.1.9__tar.gz → 0.2.0__tar.gz

{laddercodec-0.1.9 → laddercodec-0.2.0}/CHANGELOG.md

@@ -8,6 +8,21 @@
      Review and condense before release — entries accumulate during development and
      should be edited into shape before moving from Unreleased to a version heading. -->
 
+## 0.2.0
+
+### Fixed
+- **SCR decode**: correct the row-topology block framing — every row (including row 0) uses one uniform block format, fixing branch rungs whose wires (`T`/`|`/`-`) were silently dropped whenever a continuation row's first right-wired cell carried segment flag 1.
+- **SCR decode**: accept placement-ordered flag-table entries — native captures store columns out of order (e.g. `[6,1,0,3,2,4,5]`), which the old sorted-order validation rejected.
+- **SCR decode**: drop orphaned editor-debris wire rows stored above a rung's true row 0 (observed under drum boxes), matching what Click's own clipboard copy produces.
+
+### Changed
+- **SCR decode**: replace the heuristic topology parser (leading-row guessing, count_down special cases, end-marker scanning) with a deterministic parser derived from the verified format — see `docs/internals/binary-format.md` §"SCR row-topology blocks" for the spec.
+- **SCR decode**: `decode_program()` now parses rung records with a single forward cursor — comments, topology, and instructions are read from explicit lengths and counts instead of scanning for signatures, so comments attach to their own rung by construction and malformed files fail loudly with the byte offset (see §"SCR rung records" in the binary format doc).
+
+### Added
+- **Tumbler fixture**: 34 real Click programs (`tests/fixtures/tumbler/`), each pairing the internal `.scr` program file with a clipboard capture of the same program; `decode_program()` output is regression-tested byte-identical against the clipboard CSVs.
+- **Devtools**: `compare_csv.py` normalizes `R` vs `R1`/`R2` rung markers before comparing, so scr-derived and clipboard-saved CSVs diff cleanly.
+
 ## 0.1.9
 
 ### Added

{laddercodec-0.1.9 → laddercodec-0.2.0}/CLAUDE.md

@@ -98,6 +98,7 @@ tests/
 │   ├── test_decode.py       # decode() tests
 │   ├── test_decode_multi.py # decode() multi-rung tests
 │   ├── test_decode_program.py # decode_program() program file tests
+│   ├── test_decode_program_tumbler.py # 34 real programs: scr decode == clipboard CSV
 │   ├── test_verify_status.py # Golden verification status check
 │   ├── test_model.py        # InstructionType, operand validation
 │   └── test_empty_multirow.py  # Payload synthesis for rows 1..32
@@ -109,10 +110,12 @@ tests/
 │   ├── test_token_parser.py # Condition + AF token parsing
 │   └── test_writer.py       # CSV writer tests
 └── fixtures/
-    └── ladder_captures/golden/  # Golden CSV/BIN fixtures
+    ├── ladder_captures/golden/  # Golden CSV/BIN fixtures
+    ├── scr_captures/            # Scr program files + clipboard bins (decode_program)
+    └── tumbler/                 # 34 real programs: <name>.scr + <name>.clipboard.{bin,csv}
 ```
 
-Golden fixtures verified through Click paste round-trip.
+Golden fixtures verified through Click paste round-trip. The tumbler fixture pairs each Click internal program file (`.scr`) with a clipboard capture of the same program; `devtools/compare_csv.py <dir>` compares `<name>.csv` (scr decode) against `<name>.clipboard.csv` ground truth.
 
 ## Binary Format
 
@@ -157,7 +160,7 @@ All tested shapes pass Click round-trip (verified via paste → copy-back):
 
 The clipboard decoder (`decode.py`) reads Click clipboard binaries back into structured data. Validated against a 37-rung native capture covering all basic instruction types.
 
-The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against 114-rung coverage fixture plus shift and counter programs.
+The program file decoder (`decode_program.py`) reads Click's internal `Scr*.tmp` files. Returns a `Program` with name, index, and all rungs. Validated against the 114-rung coverage fixture, shift/counter/drum programs, and the 34-program tumbler fixture (byte-identical CSV vs clipboard captures). Row topology uses the uniform row-block framing documented in `docs/internals/binary-format.md` §"SCR row-topology blocks".
 
 **All standard Click instruction types decoded natively:**
 - Contacts: NO, NC, edge (rise/fall), immediate (NO/NC)

{laddercodec-0.1.9 → laddercodec-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: laddercodec
-Version: 0.1.9
+Version: 0.2.0
 Summary: Binary codec for AutomationDirect CLICK PLC ladder clipboard format
 Project-URL: Repository, https://github.com/ssweber/laddercodec
 Project-URL: Documentation, https://ssweber.github.io/laddercodec/

{laddercodec-0.1.9 → laddercodec-0.2.0}/devtools/compare_csv.py

@@ -1,6 +1,9 @@
 """Compare {slug}.csv against {slug}.clipboard.csv in a directory.
 
-Reports which pairs are identical and which differ.
+Reports which pairs are identical and which differ.  Rung markers are
+normalized before comparison (indexed ``R1``/``R2`` vs plain ``R``), since
+scr-derived bundles are written with ``index=True`` while clipboard saves
+are not.
 
 Usage:
     uv run devtools/compare_csv.py <directory>
@@ -8,9 +11,17 @@ Usage:
 
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 
+_INDEXED_MARKER = re.compile(r"^R\d+(?=,)")
+
+
+def _normalized_lines(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    return [_INDEXED_MARKER.sub("R", line) for line in text.splitlines()]
+
 
 def main() -> None:
     if len(sys.argv) != 2:
@@ -42,7 +53,7 @@ def main() -> None:
             missing += 1
             continue
 
-        if base_path.read_bytes() == clip_path.read_bytes():
+        if _normalized_lines(base_path) == _normalized_lines(clip_path):
             print(f"  IDENTICAL  {slug}")
             identical += 1
         else:

{laddercodec-0.1.9 → laddercodec-0.2.0}/devtools/dump_scr_tags.py

@@ -25,20 +25,14 @@ def main() -> None:
         print(f"\nRung {si}:")
         cursor = sec_off + 6
         for ii in range(count):
-            blob8 = _parse_blob(data, cursor + 8)
-            blob9 = _parse_blob(data, cursor + 9)
-            if blob8:
-                row = data[cursor]
-                col = data[cursor + 1]
-                blob_start = cursor + 8
-                cls, typ, end_off, next_pos, m1 = blob8
-            elif blob9:
-                row = data[cursor + 1]
-                col = data[cursor + 2]
-                blob_start = cursor + 9
-                cls, typ, end_off, next_pos, m1 = blob9
-            else:
+            blob = _parse_blob(data, cursor + 8)
+            if not blob:
                 break
+            row = data[cursor]
+            col = data[cursor + 1]
+            blob_start = cursor + 8
+            cls, typ, end_off, m1 = blob
+            next_pos = end_off + 2 + data[end_off]  # trailer-aware advance
 
             # Parse tagged fields
             pos = blob_start

{laddercodec-0.1.9 → laddercodec-0.2.0}/docs/internals/binary-format.md

@@ -198,24 +198,54 @@ The instruction blob content (tag IDs, operand values, wire types) is **identica
 
 The embedded fields at offsets +0 through +6 after the type code correspond to clipboard cell header offsets +0x09 through +0x10. The `end_offset` is an absolute file pointer to the blob boundary — the same boundary that clipboard's `find_blob_boundary()` derives by scanning tags. Tags use length-prefixed strings (no `FFFFFFFF` sentinel).
 
+The byte at `end_offset` is a 1-byte trailer length (observed 0 or 1): the next structure starts at `end_offset + 2 + data[end_offset]`. Certain instruction encodings (`RD`/`SD` always; `Copy`/`Math`/`Out`/`Drum` sometimes) emit a 1-byte trailer whose value is opaque.
+
+## SCR rung records
+
+An SCR file is a header followed by one rung record per rung, in order, parseable with a single forward cursor:
+
+```
+RUNG = [2B rung_index]        -- 1-based ordinal; asserted sequential
+       [4B rtf_len][rtf body] -- comment; rtf_len = 0 means none
+       TOPOLOGY               -- row-topology block (below)
+       [2B instr_count]       -- 0 = empty rung (nothing follows)
+       [4B section_marker]    -- only when instr_count > 0
+       instr_count x ENTRY    -- 8-byte header + blob (see framing above)
+ENTRY  = [1B row_1based][1B col][1B b2][1B b3][1B entry_seq][3B 00] + blob
+```
+
+Rung 0 carries a 7-byte file prelude instead of `rung_index`: `[2B file_marker][0d][4B total_rung_records]`. `file_marker` equals the per-file `section_marker` constant (opaque; validation magic only), and `total_rung_records` counts every rung record in the file.
+
+Programs end with 1–4 ordinary content-less rungs (the empty editor rungs below the last programmed rung; some carry a fully-wired row) — the decoder drops trailing records with no instructions and no comment. Files with `prog_idx == 1` (the main program) carry a 2-byte tail after the last record; subroutines end exactly at the last record.
+
 ## SCR row-topology blocks
 
 SCR files store per-rung wire topology in structured blocks that precede each rung's instruction section. Each block encodes the right-wire and segment-flag data that clipboard stores per-cell in the grid.
 
 ```
-[2B row_word][03 00 00]                    -- 5-byte header
-[leading-row wire blocks...]               -- rows before row 0 (count_down bridge)
-[1B af_segment][1B entry_count][00]        -- 3-byte trailer
-[entry_count x (1B seg_flag, 1B col_idx)]  -- row 0 flag table
-[continuation-row wire blocks...]          -- rows 1..N-1
-[20 00]                                    -- end marker
-[wire_down data]                           -- per-column vertical wire indices
+[2B row_word][03 00 00]         -- 5-byte header; row_word = stored rows + 1
+{ row block } x (row_word - 1)  -- one per grid row, in row order (row 0 first)
+[20 00]                         -- end marker
+[wire-down table]               -- exactly 32 column entries (see below)
+```
+
+Every row block — including row 0's — has the same uniform format:
+
 ```
+[1B flag][1B count][00]  +  count x ([1B seg][1B col])
+```
+
+- `flag` — the +0x19 segment flag of the row's AF (col 31) cell. 1 for normal output/coil/NOP rows, 0 for tall segment-0 instructions (timer/counter/drum).
+- `count` — number of right-wired cells on the row (condition cells plus AF when present). `count = 0` is an empty row: the 3-byte block `[flag][00][00]`.
+- Each entry pairs a cell's +0x19 segment flag with its column index (0–31, 31 = AF). Entries are **placement-ordered** — the column sequence is usually ascending but not guaranteed (native captures include orders like `[6,1,0,3,2,4,5]`), so columns must be treated as a set.
+
+A row block whose entries include col 0 with every condition-cell seg = 1 carries the grid-row-0 signature (row 0 is exempt from the per-row segment boundary). SCR can retain orphaned wire rows *above* the true row 0 — editor debris under a tall instruction box — which Click's own clipboard copy omits; the decoder drops non-empty stored rows preceding the first row with the row-0 signature.
 
-Each continuation-row wire block:
+The wire-down table after the `20 00` marker has exactly one entry per column 0–31:
 
 ```
-[1B seg][1B right_count][00 00][pairs of (col_idx, next_seg)...][final_col]
+no down wires: [00 00]
+down wires:    [1B count][00][count x 1-based row index]
 ```
 
-The block is parsed forward: leading-row blocks are consumed until the 3-byte trailer is found, then the row-0 flag table, then continuation rows, then the `0x0020` marker, then wire-down data.
+This table is the SCR serialization of the per-cell down flag (+0x21) that clipboard stores on each cell — it lists every down wire, including those carried by contact cells (rendered as a `T:` prefix, see [wire rendering](wire-rendering.md)). It is therefore a superset of the visible `T`/`|` wire tokens.

{laddercodec-0.1.9 → laddercodec-0.2.0}/docs/internals/wire-rendering.md

@@ -21,7 +21,7 @@ Wire tokens are classified by (right, down) only — the segment flag is indepen
 | 1 | 1 | `T` | Branch junction (right + down) |
 | 0 | 0 | *(blank)* | No wire |
 
-Instruction cells (contacts, coils) also set right=1 — they behave like horizontal wires with instruction data layered on top.
+Instruction cells (contacts, coils) also set right=1 — they behave like horizontal wires with instruction data layered on top. A contact cell can additionally set down=1 (a branch rooted directly under the contact): since right is already 1, that's the T shape, and the CSV renders it as a `T:` prefix on the contact token (e.g. `T:C1204`), mapping to `wire_down=True` on `Contact`/`CompareContact`.
 
 ## Left-edge rendering