QASM classical expressions guess signedness from bit patterns: division, negation width, shifts, as_i64 and folding all disagree

[ciaranra]

Summary

PECOS's QASM classical expressions have no representation of signedness: values are bare BitVecs and every operation guesses sign from the bit pattern (resize_to_same_width sign-extends any multi-bit value from its MSB, bitvec::divide treats both MSBs as signs, as_i64 reinterprets any pattern as two's complement, is_negative_expression looks only at the outermost AST node). #864 is the comparison symptom and its PR fixes comparisons and assignment widening under the rule "registers are unsigned; only an explicitly negated expression is negative", using expression shape for signedness. Everything below is the rest of the same confusion and needs one deliberate design (value-carried signedness) rather than more shape heuristics.

Reproduced on dev at 86cd2b1 (through sim_builder, 4-bit registers unless stated)

• b = 15; a = b / 2; gives a = 0. bitvec::divide reads b's MSB as a sign and divides -1 by 2. (Expected 7.)
• creg a[2]; creg b[4]; a = 3; b = a; gives b = 15 (fixed by the QASM if conditions sign-extend multi-bit registers, so d == 3 is false when d holds 3 #864 PR for the assignment path, listed here for the record).
• 1-bit c = 1: if (c > 0) is false (fixed by the QASM if conditions sign-extend multi-bit registers, so d == 3 is false when d holds 3 #864 PR).

Found by review, not yet reproduced (read the cited code before acting)

• Unary minus keeps the operand's width: negating a 2-bit unsigned 11 yields 01 (+1), not -3 (bitvec_expression.rs evaluate_unary_op, arithmetic.rs::negate). The negation width, and the policy for negating the signed minimum, are undefined.
• as_i64 on an unsigned value with its top bit set returns a negative number. Shift counts use it, so shifting by a register holding 3 (2-bit 11) clamps the count to 0. WASM arguments use it too. Right shift is logical; whether a signed right shift exists is undefined.
• analyze_comparison treats "outermost node is unary minus" as "negative", so -0 < 0 is true, --1 > 0 is false, and -1 < (-2 + 0) is true. The shortcut runs before operands are evaluated, in both runtime evaluation and constant folding.
• Constant folding complements a literal at its parsed width while runtime zero-extends to the default width first, so ~1 folds to 14 but evaluates to 254 at default width 8.
• Mixed signed/unsigned bitwise operations: 15 & -1 at width 4 is a signed 1111 (-1) and 15 ^ -1 a signed 0 under any propagation rule; whatever the rule, it needs tests.
• Indexed assignment c[0] = 2 stores 1 (truthiness), not the low bit 0.
• Signedness and width of RNG and WASM function results, and of the void-result placeholder, are unstated; a function result compared directly is not supported by the recursive evaluator.
• qasm_to_phir.rs types every creg as i64 while qasm_to_phir_json.rs types it u32/u64 (QASM-to-PHIR lowerings disagree on the classical register type: i64 in the Rust path, u32/u64 in the JSON path #868).

Proposed shape

Carry signedness on the evaluated value (ExpressionValue::BitVec { bits, signed } or a signed variant), produced only by unary minus, propagated through operators, and consumed by widening, division, shifts and the i64 conversion. Registers are unsigned. Define negation width, division rounding, shift semantics and the conversion overflow policy in one place and test each with a bit-exact table. Delete the MSB-based heuristics (resize_to_same_width's sign guess, is_negative_expression's AST-shape guess) once the value carries the answer.

The review that produced this list is on the #864 PR.

[ciaranra]

PR #870 (the #864 fix) ended up covering more of this list than planned, under the shape-based rule (registers unsigned; only an outer unary minus is negative): comparison and assignment widening, arithmetic and bitwise operand widening, unary-minus width (one-bit widen before negation), the shift count (unsigned, saturating at the operand width), and the ~ literal fold (removed; runtime knows the width). Still open here, each verified or observed during that work: bitvec::divide reading operand MSBs as signs (b = 15; a = b / 2 still gives 0); as_i64 for WASM arguments; indexed assignment truthiness; signedness of RNG/WASM results; the constant folder and runtime disagreeing on the width of unary operators other than ~; and the shape rule's own edges, which the value-carried model would remove: a compound like 1 - 3 is an unsigned modular 14 so -(1 - 3) is -14, and a doubly negated count such as 8 >> -(-1) is negative by shape and clamps to 0.

[ciaranra]

A second blind review of #870 pulled two more items out of this list into that PR: division (a spare sign bit before bitvec::divide, quotient truncated back; 8 / 2 in a 4-bit register gave 12 and gives 4; divide itself untouched) and ~ on a register (now complemented at the target width like the binary bitwise operators). It also found and fixed a PHIR-JSON export bug outside this list: integer literals went through the signed to_i64, so creg c[4]; c = 8; emitted -8; they now go through a new unsigned pecos_core::bitvec::to_u64 and error if they exceed PHIR's i64. What remains here: bitvec::divide and bitvec::multiply reading operand MSBs as signs internally (now masked at the QASM layer by the spare bit, but still the wrong primitive shape), as_i64 for WASM arguments and for condition truthiness (both carry a comment pointing here), indexed assignment truthiness, RNG/WASM result signedness, folding width of unary operators other than ~, and the shape rule's edges (compounds are unsigned modular; a doubly negated expression is negative by shape).

[ciaranra]

Design pass written up in the pecos-docs vault as design/qasm-classical-signedness.md: the state after #870, the verified remaining defects, three options (patch the primitives; value-carried signedness on ExpressionValue, recommended, with a full semantics table; typed registers via PHIR types), a test plan, and three questions for the owner (integer versus modular intermediates, negative shift counts, whether signed cregs exist outside PHIR). No code until those are answered.

[ciaranra]

Decisions (recorded in the vault note design/qasm-classical-signedness.md): mirror the PHIR classical interpreter, which already implements the value-carried model (ExprValue::{Signed, Unsigned, Boolean} over pecos_core::BitUInt). (1) intermediates are modular at a 64-bit evaluation width with signedness carried on the value, a result signed if either operand is, so -(1 - 3) == 2 is true and a store still truncates to the register width; (2) a negative shift count is an error, as in PHIR; (3) no signed creg outside PHIR types, so c == -1 is false for any register and WASM arguments receive the unsigned value; #868 resolves toward u32/u64. Implementation: move ExprValue and its operator evaluation into pecos-core next to BitUInt, use it from both evaluators, then delete the #870 shape rule and spare-sign-bit widening.

[ciaranra]

Correction to the decisions above. The PHIR interpreter's rule is result_signed = lhs_signed && rhs_signed (crates/pecos-phir-json/src/v0_1/expression.rs), not "signed if either operand is signed", and integer literals that fit i64 are signed there while registers are unsigned. Those are the rules QASM adopts, since they were confirmed for PHIR in 2026-07 with a Python/Rust parity fuzz.

Consequences for QASM: 1 - 3 == -2, -(1 - 3) == 2 and -1 < 0 are true (literal-only expressions behave like integers); c == -1 and c > -1 are both false for an unsigned register (C's usual arithmetic conversions); c = -1 still stores the all-ones pattern; a negative shift count is an error.

One prerequisite surfaced while checking the code: BitUInt compares, multiplies and divides using only the low 64-bit word above 64 bits (crates/pecos-core/src/bit_uint.rs, the Large arms of PartialEq, Ord, Mul, Div, Rem). PHIR registers are at most 64 bits so this was unreachable; QASM registers wider than 64 bits would reach it. The shared evaluator lands in two PRs: first pecos-core (wide-width BitUInt correctness plus the moved ExprValue evaluator, behaviour-preserving for PHIR), then pecos-qasm adopting it and deleting the shape rule.

[ciaranra]

Implementation is split into three pull requests, each with its own oracle, because reconnaissance turned up a prerequisite. pecos_core::BitUInt was only correct at or below 64 bits: equality and ordering compared the low word, multiplication multiplied the two low words, division and remainder divided the low words, the raw-word constructor did not pad storage to its declared width, and the binary-string constructor read chunks from the wrong end. None of that is reachable from PHIR, whose typed environment caps registers at its 64-bit backing types. All of it is reachable from QASM, whose tests declare classical registers of 72, 80, 100, 128, 256 and 400 bits. Adopting the shared evaluator without repairing the primitive would have moved QASM from one set of wrong wide-register answers to another.

Slice A is #878, now open: the BitUInt repair, pecos-core only.

Slice B moves ExprValue and its operator evaluation into pecos-core next to BitUInt and has the PHIR interpreter call it there. Behaviour stays bit-for-bit identical, with the existing Rust and Python parity test as the oracle. Widening learns to sign-extend a signed value rather than zero-extend it, which PHIR cannot observe and QASM requires, and unary minus joins the operator table since PHIR has no such operator.

Slice C switches the QASM evaluator, the engine's assignment and condition paths, and the constant folder onto the shared value, and deletes the shape rule, is_negative_expression and the spare sign-bit widening.

One correction to the survey of what slice C changes. Evaluation width is the larger of 64 and the widest operand, not a flat 64, because MIN_EVAL_WIDTH in the PHIR evaluator is already a minimum rather than a fixed width. Wide registers therefore keep full-width arithmetic and the wide-register tests keep their current expectations. The only value that changes in the existing suite is the folding test asserting that (5+3)*2 is zero, which is the result of folding at the literal's four-bit width; it becomes 16.

[ciaranra]

Correction to the decisions recorded above, found while computing anchor values for the QASM adoption rather than by reading the prose again.

I wrote that c == -1 is false for an unsigned register. That holds only when the register is narrower than 64 bits. The evaluation width is the larger of 64 and the widest operand, so a register of 64 bits or more pulls the literal up to its own width, the literal sign-extends to all ones there, and an all-ones register compares equal to it.

register	evaluation width	all-ones register == -1
creg c[4]	64	false
creg c[64]	64	true
creg c[100]	100	true

This is not a defect and nothing needs to change. The PHIR interpreter already behaves this way for a 64-bit unsigned register, and it follows from the rules exactly as adopted. I am recording it because the flat claim was wrong, and because a test expectation written from that claim would have been wrong in the same way.

c > -1 is unaffected and remains false at every width, since the register's value never exceeds the sign-extended literal.