Module

config.hash

Configuration hash utility for cache invalidation.

This module provides deterministic hashing of configuration state, enabling automatic cache invalidation when the effective configuration changes (including env vars, profiles, and split config files).

Architecture:

The hash captures the *resolved* configuration state, not just file contents.
This ensures cache correctness when:
  • Environment variables change (BENGAL_*)
  • Build profiles change (--profile writer)
  • Split config files change (config/environments/local.yaml)

Related:

  • bengal/cache/build_cache.py: Uses config_hash for validation
  • bengal/config/loader.py: Produces the config dict to hash
  • plan/active/rfc-zensical-inspired-patterns.md: Design rationale
View source
2 Functions

Functions

_json_default
Handle non-JSON-serializable types for hashing. Converts Path, set, frozenset, and other types to …
1 str 
def _json_default(obj: Any) -> str

Handle non-JSON-serializable types for hashing.

Converts Path, set, frozenset, and other types to strings for consistent serialization.

Parameters 1

Name Type Default Description
obj Any —

Object to convert

Returns

str —

String representation suitable for hashing

compute_config_hash
Compute deterministic SHA-256 hash of configuration state. The hash is computed from the *resolved…
1 str 
def compute_config_hash(config: dict[str, Any]) -> str

Compute deterministic SHA-256 hash of configuration state.

The hash is computed from the resolved configuration dictionary, capturing all effective settings including:

  • Base configuration from config files
  • Environment variable overrides
  • Profile-specific settings
  • Merged split config files

Algorithm:

1. Recursively sort all dictionary keys (deterministic ordering)
2. Serialize to JSON with custom handler for non-JSON types
3. Compute SHA-256 hash
4. Return first 16 characters (sufficient for uniqueness)

Parameters 1

Name Type Default Description
config dict[str, Any] —

Resolved configuration dictionary

Returns

str —

16-character hex string (truncated SHA-256)