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

instrument / verified-clean

# Two's Complement Calculator

The current ledger marks this instrument verified clean within the source-bound verification corpus.

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

## Inspectable records

[01**Overview**Purpose and lifecycle](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/>)[02**Mechanism**Method and assumptions](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/mechanism/>)[03**Implementation**Binding and validation](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/implementation/>)[04**Qualification**Evidence and errata](<https://guthlabs.ai/docs/instruments/two-s-complement-calculator/qualification/>)

## Ledger state

The current ledger marks this instrument verified clean within the source-bound verification corpus.

**Area**: Computing & Information

**Tranche**: tranche-2

**Evidence ID**: t2-004

**Ledger rows**: 1

No ledger note is attached.

## Review findings

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.

### Formula and scope findings

- 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.

### Unit assumptions

- 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.

## Boundary hardening

**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.

## Errata and corrections

No applied erratum is attached to this unique-name record.

## Inspectable example

4 review vectors are recorded. One source-bound sample is shown below.

````
{
  "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."
}
````

## Related workflows

No source-defined multi-instrument workflow membership is recorded.

## Sources and evidence

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

- `VERIFIED_LEDGER.json · VERIFIED_CLEAN`

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

- `BOUNDARY_HAZARD_CATALOG.json`