Skip to content

fix(decode): warn on a flag field that is stored empty - #164

Merged
ssweber merged 1 commit into
mainfrom
fix/legacy-empty-flag
Nov 20, 2026
Merged

ssweber merged 1 commit into
mainfrom
fix/legacy-empty-flag

Conversation

@ssweber

@ssweber ssweber commented Nov 20, 2026

Copy link
Copy Markdown
Owner

Sam's ruling of 2026-11-19: an empty flag field still decodes as set, and decode() now warns about it.

CLICK runs a flag stored empty as clear, and CLICK's own saves never write one. An older laddercodec did write them, in blobs composed from program-file tags. decode() now emits a LegacyEncodingWarning for each empty flag that encoding the rung again writes set.

What warns

  • Flags decode() reads. There are 20 fields, such as Coil.oneshot, Contact.immediate, Math.mode, Drum.jog_enabled and Search.continuous. The warning gives both values: Coil.oneshot: the flag is stored empty, so laddercodec reads it as True. CLICK runs it as False. Encode this rung again and paste it.

  • Flags the encoder writes from another field. These are:

    • Send and Receive success, sending or receiving, error, and exception;
    • the Out variants' immediate and maintained flags;
    • Copy's text flag.

    The warning names the one field that drives the flag. When no single field does, it names the class and tag, such as OutVariant and 1246=.

  • Flags the encoder writes 0 get no warning: RD, SD, Fill, Pack and Unpack.

  • A kept blob has each flag written as the encoder writes it. Decode, encode, decode ends with no warning.

  • decode_program() never warns. A program file writes a flag as a tag with no value, which is CLICK's own form.

  • The new ending. Every LegacyEncodingWarning now ends "Encode this rung again and paste it." That includes the existing Math H70000 warning.

Known gap

A Send or Receive that also holds a refused field gets no warning for its derived flags. Its kept blob keeps the flag empty, so it still encodes as CLICK ran it. v0.4.0 never wrote an empty flag in a Send or Receive.

Checks

  • CLICK captures. No CLICK capture warns: 0 empty flags across 322 clipboard captures.
  • Per-flag probe. Each flag of 1854 distinct fixture blobs was stored empty one at a time. The probe found:
    • no missed warnings;
    • no wrong warnings;
    • no kept blob still empty.
  • Kept blobs. They are byte-exact over 3543 fixture blobs.
  • Program files. decode_program() output is unchanged on all 134 program files.
  • No golden byte changed.

Gate

  • make lint: passed.
  • make docs-build: passed.
  • make test: 19014 passed, 139 skipped.

CLICK runs a flag that is stored empty as clear. decode() reads such a
flag as set, and now emits a LegacyEncodingWarning for each one that
encoding the rung again writes set.

The warning names the field, such as Coil.oneshot or Send.sending, or
the class and tag when no single field drives the flag. A kept blob
gets the flag written as the encoder writes it, so the rung decodes
again with no warning. Condition cells and a Tee are checked too.
decode_program() does not warn: a program file writes a flag as a tag
with no value, which is CLICK's own form.

Every LegacyEncodingWarning now ends "Encode this rung again and paste
it."

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssweber
ssweber merged commit 0472b3b into main Nov 20, 2026
7 checks passed
@ssweber
ssweber deleted the fix/legacy-empty-flag branch November 20, 2026 02:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant