Source: https://guthlabs.ai/docs/instruments/two-s-complement-calculator/mechanism/

instrument mechanism / verified-clean

# Two's Complement Calculator mechanism

The inspectable method record for Two's Complement Calculator, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

Core two's-complement range and negative-encoding concepts are standard, but the specification needs an explicit decoding formula and an exact overflow contract. The empty honest_label is a concern: the product should disclose supported widths, exact 64-bit implementation requirements, input validation, and whether overflow rejects or wraps values.

- The negative-number encoding rule is underspecified: it must invert the fixed-width n-bit representation of |x| and add 1, with the result masked to n bits.

- No decoding formula is provided. Standard decoding is unsigned_value for an unset sign bit, and unsigned_value - 2^n when the most-significant bit is set.

- Behavior for values outside [-2^(n-1), 2^(n-1)-1] is undefined: the specification must state whether to reject the value, return no bit pattern, or wrap modulo 2^n while asserting overflow.

- The specification allows only widths 8, 16, 32, and 64, but the formula does not explicitly constrain n to those values.

## Units and conventions

- All values are dimensionless integers; decimal input is base 10 and binary input is an n-bit base-2 string.

- The bit width n is exactly 8, 16, 32, or 64, and binary strings must contain exactly n bits, including leading zeroes.

- For encoding, positive values and zero are represented directly in n-bit binary; negative values use the fixed-width two's-complement rule.

- For decoding, an n-bit pattern with unsigned value u represents u when its top bit is 0, and u - 2^n when its top bit is 1.

- A 64-bit implementation must use exact integer arithmetic such as BigInt or string-based arithmetic rather than IEEE-754 JavaScript Number arithmetic.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "operation": "encode",
    "decimal_value": 5,
    "bit_width": 8
  },
  "expected_outputs": {
    "binary_bit_pattern": "00000101",
    "decimal_value": 5,
    "overflow_flag": false
  },
  "working": "Range for 8 bits: [-2^(8-1), 2^(8-1)-1] = [-128, 127]. 5 is in range, so overflow = false. 5 in 8-bit binary is 00000101. Therefore bit pattern = 00000101 and decoded decimal value = 5."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

A pure-JavaScript implementation that parses large decimal inputs as Number can round -9223372036854775809 to -9223372036854775808, incorrectly accepting an out-of-range value and producing a valid-looking bit pattern. The signed-versus-unsigned interpretation of bit patterns is also a user-facing convention hazard.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/qualification/>)

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json`

- `evidence-tranche2/tranche2-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`