Boundary-Aware Feature Masks

Implement helpers for interpreting permission bitmasks under four boundary policies: one that rejects unknown bits, one that silently trims them, one that ejects to a plain integer, and one that keeps unknown combinations as pseudo-members while preserving known feature checks. The same three permissions are used everywhere: READ (1), WRITE (2), and EXECUTE (4).

Capabilities

Strict masks reject unknown bits

• strict_mask(0b1000) raises a ValueError because the bit is not defined by the permission set; valid masks keep working with membership checks (e.g., WRITE in strict_mask(0b0011) is true). @test

Conforming masks discard extras

• conforming_mask(0b1111) returns a mask whose value equals 0b0111 while maintaining membership for the defined bits. @test

Eject invalid masks to raw ints

• ejecting_mask(0b1000) returns the integer 8 instead of a mask instance when the incoming mask includes undefined bits; valid masks still produce the typed mask. @test

Pseudo-members keep unknown bits

• lenient_mask(0b1001) returns a pseudo-member retaining the original value (0b1001); membership checks still succeed for defined bits, and describe returns a |-joined string where unknown portions show as UNKNOWN(0x...) (e.g., READ|UNKNOWN(0x8)). @test

Implementation

@generates

API

from typing import Union

class AccessFlag:
    READ: "AccessFlag"   # bit value 1
    WRITE: "AccessFlag"  # bit value 2
    EXECUTE: "AccessFlag"  # bit value 4

def strict_mask(mask: int) -> AccessFlag: ...

def conforming_mask(mask: int) -> AccessFlag: ...

def ejecting_mask(mask: int) -> Union[AccessFlag, int]: ...

def lenient_mask(mask: int) -> AccessFlag: ...

def describe(mask: AccessFlag) -> str: ...

Dependencies { .dependencies }

aenum { .dependency }

Provides advanced flag enums with configurable boundary handling and pseudo-member support.