Ruff migration: unsafe autofixes (672) + typing repairs

ruff check --fix --unsafe-fixes: return-type annotations (ANN2xx),
zip(strict=False) (B905, made explicit and behavior-preserving; a
strict=True audit is a follow-up), dict()/{} literals (C408), unused
unpacked vars (RUF059), TYPE_CHECKING import moves (TC001/TC003),
pytest composite-assert splits (PT006/PT018).

The new annotations made mypy check 4 previously-untyped bodies,
surfacing 19 latent type errors; fixed for real: int() on tensor
.item() indices (mlp_sublayer), record union annotation (token_model),
bos/eos tokens are str | None (custom tokenizer contract), typed
DirectShardSink.meta/weight_map, typed _CONFIGS table.

Gates: mypy green (296 files), full pkgutil import walk clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: physicsrob

examples/_calculator_common.py

@@ -1,4 +1,4 @@
-"""Shared scaffolding for the three calculator examples.
+r"""Shared scaffolding for the three calculator examples.
 
 ``calculator_simple`` and ``calculator_advanced`` are two *independent*
 implementations of the same calculator: they differ only in their arithmetic —
@@ -185,7 +185,7 @@ def compare_digit_seqs(
 
     flags = [
         onehot_lookup(concat([a, b]), pair_table, default_flag)
-        for a, b in zip(seq1, seq2)  # MSB-first
+        for a, b in zip(seq1, seq2, strict=False)  # MSB-first
     ]
     # Sharpen each flag to an exact three-level value: gt = 1 iff flag > 0.5,
     # lt = 1 iff flag < -0.5 (both bit-exact in saturation; the flag sits
@@ -215,7 +215,7 @@ def parse_expression(
     embedding: Embedding,
     max_digits: int,
 ) -> tuple[list[Node], list[Node], Node, Node, Node, Node]:
-    """Parse ``"A op B\\n"`` from the token stream, at constant depth.
+    r"""Parse ``"A op B\\n"`` from the token stream, at constant depth.
 
     Returns ``(first, second, is_plus, is_minus, is_times, saw_newline)``:
     the two operand digit windows (MSB-first, zero-padded to ``max_digits``),
@@ -383,13 +383,13 @@ def build_calculator(
 
     # --- Addition: pad each operand by one digit so the top carry has a home. ---
     add_seq = _pad_result(
-        embedding, add_digit_seqs(embedding, [zero] + first, [zero] + second), seq_len
+        embedding, add_digit_seqs(embedding, [zero, *first], [zero, *second]), seq_len
     )
 
     # --- Subtraction: |A - B| by a borrow fold, sign from the comparison. ---
     a_ge_b = compare_digit_seqs(embedding, first, second)
-    bigger = [select(a_ge_b, a, b) for a, b in zip(first, second)]
-    smaller = [select(a_ge_b, b, a) for a, b in zip(first, second)]
+    bigger = [select(a_ge_b, a, b) for a, b in zip(first, second, strict=False)]
+    smaller = [select(a_ge_b, b, a) for a, b in zip(first, second, strict=False)]
     sub_seq = _pad_result(
         embedding, subtract_digit_seqs(embedding, bigger, smaller), seq_len
     )

examples/adder.py

@@ -1,4 +1,4 @@
-"""3-digit adder using embedding-space arithmetic.
+r"""3-digit adder using embedding-space arithmetic.
 
 Parses "A+B\\n" where A and B are up to 3-digit numbers, and outputs their
 sum autoregressively. All arithmetic is done digit-by-digit in embedding
@@ -35,9 +35,15 @@
 
 def create_network_parts() -> tuple[Node, Embedding]:
     """Build the 3-digit adder graph and return (output_node, embedding)."""
-    vocab = list(
-        " 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
-    ) + ["\n", "<bos>", "<eos>", "default"]
+    vocab = [
+        *list(
+            " 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
+        ),
+        "\n",
+        "<bos>",
+        "<eos>",
+        "default",
+    ]
     embedding = create_embedding(vocab=vocab)
     rope = create_rope_config(d_head=D_HEAD, max_positions=MAX_POSITIONS)
 
@@ -58,8 +64,9 @@ def create_network_parts() -> tuple[Node, Embedding]:
     second_num_digits = num_seq.get_digits_at_event(is_end_of_second_num)
 
     # --- Phase 2: Add digit-by-digit with carry propagation ---
-    sum_digits = sum_digit_seqs(embedding, first_num_digits, second_num_digits) + [
-        create_literal_value(embedding.get_embedding("<eos>"))
+    sum_digits = [
+        *sum_digit_seqs(embedding, first_num_digits, second_num_digits),
+        create_literal_value(embedding.get_embedding("<eos>")),
     ]
     sum_digits = remove_leading_0s(embedding, sum_digits, max_removals=max_digits - 1)
 

examples/adder_1digit.py

@@ -1,4 +1,4 @@
-"""1-digit adder: the simplest example of programming a transformer.
+r"""1-digit adder: the simplest example of programming a transformer.
 
 Parses "A+B\\n" where A and B are single digits, and outputs their sum.
 All arithmetic is done via a single 100-entry lookup table that maps
@@ -67,9 +67,15 @@ def sum_numbers(embedding: Embedding, num1: Node, num2: Node) -> tuple[Node, Nod
 
 def create_network() -> Unembedding:
     # --- Phase 1: Vocabulary and parsing ---
-    vocab = list(
-        "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
-    ) + ["\n", "<bos>", "<eos>", "default"]
+    vocab = [
+        *list(
+            "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
+        ),
+        "\n",
+        "<bos>",
+        "<eos>",
+        "default",
+    ]
     embedding = create_embedding(vocab=vocab)
     rope = create_rope_config(d_head=D_HEAD, max_positions=MAX_POSITIONS)
 
@@ -90,7 +96,7 @@ def create_network() -> Unembedding:
     # Latch: remember the digit at "=".
     second_num = get_prev_value(rope, just_completed_num, is_second_num)
 
-    summed, carry = sum_numbers(embedding, first_num, second_num)
+    summed, _carry = sum_numbers(embedding, first_num, second_num)
 
     # --- Phase 3: Output ---
     return create_unembedding(summed, embedding)

examples/adder_v2.py

@@ -44,16 +44,22 @@
 
 
 def create_network(max_digits: int = 3) -> Unembedding:
-    """Create a v2 adder: parses "A+B\\n", outputs result digits autoregressively.
+    r"""Create a v2 adder: parses "A+B\\n", outputs result digits autoregressively.
 
     Three phases:
       1. Parse: extract digit embeddings for A and B from the token stream
       2. Compute: embeddings → scalars → add → scalars → embeddings
       3. Output: emit result digits left-to-right, then <eos>
     """
-    vocab = list(
-        " 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
-    ) + ["\n", "<bos>", "<eos>", "default"]
+    vocab = [
+        *list(
+            " 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()-+="
+        ),
+        "\n",
+        "<bos>",
+        "<eos>",
+        "default",
+    ]
     embedding = create_embedding(vocab=vocab)
     rope = create_rope_config(d_head=D_HEAD, max_positions=MAX_POSITIONS)
 
@@ -83,8 +89,9 @@ def create_network(max_digits: int = 3) -> Unembedding:
     result_digits = [scalar_to_embedding(d, embedding) for d in digit_scalars]
 
     # --- Phase 3: Format and output ---
-    result_digits = result_digits + [
-        create_literal_value(embedding.get_embedding("<eos>"))
+    result_digits = [
+        *result_digits,
+        create_literal_value(embedding.get_embedding("<eos>")),
     ]
     result_digits = remove_leading_0s(embedding, result_digits, max_removals=max_digits)
 

examples/binary_increment.py

@@ -1,4 +1,4 @@
-"""Binary increment.
+r"""Binary increment.
 
 Parses a binary string like "1011\\n" and outputs the incremented value
 "1100". Handles carry propagation through consecutive trailing 1s
@@ -48,7 +48,7 @@ def create_network_parts(
         max_bits: Maximum number of input bits (handles up to max_bits-bit
             binary numbers). Output may be max_bits+1 bits on overflow.
     """
-    vocab = list("01 ") + ["\n", "<bos>", "<eos>"]
+    vocab = [*list("01 "), "\n", "<bos>", "<eos>"]
     embedding = create_embedding(vocab=vocab)
     rope = create_rope_config(d_head=D_HEAD, max_positions=MAX_POSITIONS)
     embed = embedding.get_embedding
@@ -92,7 +92,7 @@ def create_network_parts(
     overflow_bit = select(carry[max_bits], one_embed, zero_embed)
 
     # --- Build output (MSB first) ---
-    output_seq = [overflow_bit] + list(reversed(new_bits)) + [eos_embed]
+    output_seq = [overflow_bit, *list(reversed(new_bits)), eos_embed]
     output_seq = remove_leading_0s(embedding, output_seq, max_removals=max_bits)
 
     output_node = output_sequence(

examples/caesar_cipher.py

@@ -1,4 +1,4 @@
-"""Caesar cipher with runtime shift parameter.
+r"""Caesar cipher with runtime shift parameter.
 
 Parses "<shift> <letters>\\n" where <shift> is a single digit (0-9) and
 <letters> is a sequence of lowercase letters (fixed length). Outputs each

examples/calculator_advanced.py

@@ -172,15 +172,15 @@ def _carry_lookahead_op(
                 key = torch.cat([ab, _state(carry, _CARRY_W)])
                 digit_table[key] = embedding.get_embedding(str(digit_of(a, b, carry)))
 
-    pairs = list(reversed(list(zip(seq1, seq2))))  # LSB-first
+    pairs = list(reversed(list(zip(seq1, seq2, strict=False))))  # LSB-first
     segments = [
         onehot_lookup(concat([a, b]), status_table, _state(_KILL, _SEG_W))
         for a, b in pairs
     ]
     carries = carry_lookahead(segments)
     out_lsb = [
         onehot_lookup(concat([a, b, carry]), digit_table, embedding.get_embedding("0"))
-        for (a, b), carry in zip(pairs, carries)
+        for (a, b), carry in zip(pairs, carries, strict=False)
     ]
     return list(reversed(out_lsb))
 

examples/calculator_scratchpad.py

@@ -1,4 +1,4 @@
-"""Flat-depth, scratchpad ("thinking tokens") calculator.
+r"""Flat-depth, scratchpad ("thinking tokens") calculator.
 
 ``calculator_simple`` and ``calculator_advanced`` compute ``A op B`` (``+ - *``,
 one-hot digits) with the serial carry/borrow/comparison work folded *inside the
@@ -338,7 +338,7 @@ def __init__(
         n_norm: int,
         n_answer: int,
         n_state: int,
-    ):
+    ) -> None:
         self.carry_start = 1  # first carry/verdict glyph (THINKING_START at 0)
         self.scratch_start = 1 + n_carry  # first scratch digit
         self.norm_start = self.scratch_start + n_scratch  # first normalization glyph
@@ -907,13 +907,13 @@ def _assemble(
     encodes, so every read offset lines up by construction.
     """
     embed = embedding.get_embedding
-    return (
-        [create_literal_value(embed(THINKING_START))]
-        + thinking
-        + [create_literal_value(embed(RESULT))]
-        + answer
-        + [create_literal_value(embed("<eos>"))]
-    )
+    return [
+        create_literal_value(embed(THINKING_START)),
+        *thinking,
+        create_literal_value(embed(RESULT)),
+        *answer,
+        create_literal_value(embed("<eos>")),
+    ]
 
 
 def _emit_by_slot_index(

examples/calculator_simple.py

@@ -1,4 +1,4 @@
-"""Calculator compiled into a transformer: ``+``, ``-``, ``*`` on integers up
+r"""Calculator compiled into a transformer: ``+``, ``-``, ``*`` on integers up
 to ``max_digits`` digits, parsed from ``"A op B\\n"`` and emitted digit by
 digit.  This is the *legible* variant, built to be read line by line.
 
@@ -103,7 +103,7 @@ def digitwise_fold(
     default_state = init_state
     state = create_literal_value(init_state)
     out: list[Node] = []
-    for a, b in reversed(list(zip(seq1, seq2))):
+    for a, b in reversed(list(zip(seq1, seq2, strict=False))):
         key = concat([a, b, state])
         out.append(onehot_lookup(key, digit_table, default_digit))
         state = onehot_lookup(key, state_table, default_state)

examples/fibonacci.py

@@ -1,4 +1,4 @@
-"""Autoregressive Fibonacci generator.
+r"""Autoregressive Fibonacci generator.
 
 After a trigger token, generates Fibonacci numbers autoregressively.
 Each number is emitted as a fixed-width block of W digit tokens (zero-padded),
@@ -62,11 +62,7 @@ def create_network_parts(
             Determines the maximum representable value (10^digit_width - 1).
         n_terms: Number of Fibonacci terms to generate (including the two seeds).
     """
-    vocab = list("0123456789 abcdefghijklmnopqrstuvwxyz") + [
-        "\n",
-        "<bos>",
-        "<eos>",
-    ]
+    vocab = [*list("0123456789 abcdefghijklmnopqrstuvwxyz"), "\n", "<bos>", "<eos>"]
     embedding = create_embedding(vocab=vocab)
     rope = create_rope_config(d_head=D_HEAD, max_positions=MAX_POSITIONS)
     embed = embedding.get_embedding