honest-features

The Flag Vocabulary Schema

FEATURES: dict[str, dict] = {
    "flag_name": {
        "states":  set[str],   # complete set of valid states, min 2 members
        "default": str,        # must be a member of states
    },
    ...
}

Rules: - states must contain at least two members - default must be a member of states - No other keys are permitted at the vocabulary level - The vocabulary is declared at module scope, not constructed dynamically - FEATURES is the canonical inventory of all flags. No flag may be referenced that is not declared here.

The _state Dict

_state: dict[str, str] = {k: v["default"] for k, v in FEATURES.items()}

_state is initialized at module import time. No I/O. No environment variables. No config files. Initialization is deterministic.

The feature_state() Contract

def feature_state(flag: str) -> str:
    return _state[flag]

• Returns the current state of the named flag
• Raises KeyError for undeclared flag names — not a silent default
• This is intentional: an undeclared flag reference is a programming error, not a runtime condition

The Toggle Endpoint

POST /hf/features/set
Content-Type: application/json

{
    "flag":      string,    # must be in FEATURES
    "state":     string,    # must be in FEATURES[flag]["states"]
    "timestamp": integer,   # Unix timestamp
    "signature": string,    # HMAC-SHA256 hex digest
}

Validation order: 1. flag in FEATURES → 400 if not 2. state in FEATURES[flag]["states"] → 400 if not 3. timestamp within replay window → 403 if outside 4. signature valid → 403 if not

Signature construction:

message   = f"{flag}:{state}:{timestamp}"
signature = hmac_sha256(secret, message)

Signature verification must use hmac.compare_digest (or language equivalent constant-time comparison). String equality comparison is vulnerable to timing attacks.

Replay window: configurable, default 60 seconds. Requests with |now() - timestamp| > window are rejected with 403.

Successful response (200):

{"flag": "new_checkout", "state": "on", "previous": "off"}

The Handler Table Pattern

Every dispatch on flag state must use a handler table. if/else on feature_state() return values is an HC-P001 violation.

# Required pattern
HANDLERS: dict[str, Callable] = {
    "on":  handler_a,
    "off": handler_b,
}

def dispatch(manifest: dict) -> dict:
    return HANDLERS[feature_state("flag_name")](manifest)

Handler table completeness: the table must contain an entry for every state in the flag's vocabulary. A missing state raises KeyError at dispatch time. honest-check HC-HF002 catches incomplete handler tables statically.

honest-observe Integration

The toggle endpoint emits on every successful state change:

{
    "event_type":    "hf.features.changed",
    "flag":          "flag_name",
    "previous":      "old_state",
    "state":         "new_state",
    "timestamp":     1710000000,
    "requesting_ip": "10.0.0.1"
}

feature_state() emits on every call within a request context:

{
    "event_type":  "hf.features.evaluated",
    "flag":        "flag_name",
    "state":       "current_state",
    "request_id":  "req_abc123"
}

Evaluation events outside a request context (background tasks, startup) are not emitted.

Testing Contract

Tests manipulate _state directly. No API calls. No process restart. No environment manipulation.

from features import _state, FEATURES

def test_flag_on():
    _state["flag_name"] = "on"
    result = dispatch(manifest)
    assert result == expected

# Reset fixture — must be autouse
@pytest.fixture(autouse=True)
def reset_features():
    yield
    for flag, spec in FEATURES.items():
        _state[flag] = spec["default"]

The reset fixture must be autouse=True. Tests that do not reset _state produce ordering-dependent results, which is a honesty violation.

honest-check Rules

Conformance Requirements