Source: https://guthlabs.ai/docs/instruments/bitmask-flag-builder/mechanism/

instrument mechanism / verified-clean

# Bitmask / Flag Builder mechanism

The inspectable method record for Bitmask / Flag Builder, kept separate from implementation and qualification.

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

## Model scope

The mathematical formulas are standard for named power-of-two flags, subject to the stated assumptions. The specification needs an explicit bit-position range, duplicate-name/duplicate-bit policy, unknown-bit policy, and JavaScript numeric representation. The empty honest_label is a concern: the product should disclose whether it supports only 31 nonnegative JavaScript bitwise flags or supports larger masks through BigInt/string handling.

- The composition formula must sum only flags whose toggled state is true; this selection rule is not explicit in `mask = Σ flagᵢ`.

- The formula does not specify that each named flag maps to a unique nonnegative integer bit position; duplicate positions would make summation and decomposition ambiguous.

- The formula does not specify how unknown bits are handled during decomposition: ignored, returned as an unnamed remainder, or treated as an error.

- JavaScript `&` operates on signed 32-bit integers, so the mathematical result for bit 31 differs from the JavaScript result; the supported bit range and numeric representation must be specified.

## Units and conventions

- Flags are dimensionless integer bit positions, not quantities with physical units.

- Each bit position i must be a nonnegative integer; fractional and negative positions are invalid.

- A flag value is 2^i, and each active flag should be unique before summation.

- For ordinary JavaScript bitwise operations, use bits 0 through 30 for nonnegative results; bit 31 becomes a signed negative result, and higher bits are not supported by `&` without a BigInt-based implementation.

- No unit conversion applies.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "mode": "compose",
    "flags": {
      "read": {
        "bit": 0,
        "toggled": true
      },
      "write": {
        "bit": 1,
        "toggled": false
      },
      "execute": {
        "bit": 2,
        "toggled": true
      }
    },
    "tests": [
      "read",
      "write",
      "execute"
    ]
  },
  "expected_outputs": {
    "result": 5,
    "tests": {
      "read": 1,
      "write": 0,
      "execute": 4
    },
    "active_flags": [
      "read",
      "execute"
    ]
  },
  "working": "read = 2^0 = 1. write = 2^1 = 2, but it is off, so contribute 0. execute = 2^2 = 4. mask = 1 + 0 + 4 = 5. Tests: 5 & 1 = 1, 5 & 2 = 0, and 5 & 4 = 4. Therefore the active flags are read and execute."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

The extreme-magnitude vector exposes a real JavaScript Number precision failure: the exact mask 9007199254740993 is rounded to 9007199254740992, causing the bit-0 flag to disappear during decomposition. The convention probe also exposes an underspecified 0-based versus 1-based flag-index interpretation.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/bitmask-flag-builder/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/bitmask-flag-builder/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/bitmask-flag-builder/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`