Module Fingerprints

def parse_fingerprint(raw: dict) -> ModuleFingerprint:
    """
    Parse and validate a raw fingerprint dict (as provided by a module at
    registration time) into a ModuleFingerprint.

    Raises ValueError with a descriptive message on any validation failure.
    """
    _require_keys(raw, ["module_id", "cluster", "version",
                        "question_template", "default_threshold"])

    module_id = _require_str(raw, "module_id")
    cluster = _require_str(raw, "cluster")
    version = _require_str(raw, "version")
    question_template = _require_str(raw, "question_template")
    default_threshold = _require_float_in_range(raw, "default_threshold", 0.0, 1.0)

    # Validate question_template contains at least {location}
    if "{location}" not in question_template:
        raise ValueError(
            "question_template must contain '{location}' placeholder, got: "
            f"{question_template!r}"
        )

    # Parse signal priors...
    return ModuleFingerprint(...)

def slot_relevance_mask(self) -> np.ndarray:
    """
    Returns a float32 array of length FEATURE_DIM where each value is
    in [0.0, 1.0] and indicates how much this module cares about that
    feature slot. Used by limbic to initialise model weights with a
    meaningful prior instead of random noise.

    A value of 1.0 means the slot is directly relevant.
    A value of 0.5 means the slot is weakly relevant or context-dependent.
    A value of 0.0 means the slot is not relevant to this module.
    """
    mask = np.zeros(FEATURE_DIM, dtype=np.float32)

    # [0] magnitude: relevant for all modules
    mask[0] = 1.0

    # [1] delta_type: highly relevant when filesystem events are expected
    mask[1] = 1.0 if self.filesystem is not None else 0.5

    # [2] source: always relevant (distinguishes event types)
    mask[2] = 1.0

    # [3–6] temporal cyclical features: relevant when time priors exist
    if self.time is not None:
        has_hour_pref = self.time.active_hours != (0, 23)
        has_day_pref = len(self.time.active_days) < 7
        hour_weight = 1.0 if has_hour_pref else 0.5
        day_weight = 1.0 if has_day_pref else 0.5
        mask[3] = hour_weight   # hour_sin
        mask[4] = hour_weight   # hour_cos
        mask[5] = day_weight    # dow_sin
        mask[6] = day_weight    # dow_cos

    # [7] minutes_since_last_activation: relevant when typical interval is declared
    if self.time is not None:
        mask[7] = 1.0

    # [8–10] filesystem features
    if self.filesystem is not None:
        mask[8] = 1.0   # size_bytes log-normalised
        mask[9] = 1.0   # directory_depth normalised
        mask[10] = 1.0 if self.filesystem.relevant_extensions else 0.5

    # [11–15] reserved (memory/network, not yet implemented)
    return mask

def relevant_extension_hashes(self) -> list[float]:
    """
    CRC32-based hash values for each relevant extension, normalised to
    [0.0, 1.0) using the same formula as SignalEvent.to_feature_vector
    slot [10]. Used by limbic to build positive synthetic examples.
    """
    if self.filesystem is None:
        return []
    return [
        (zlib.crc32(ext.encode()) % 1000) / 1000.0
        for ext in self.filesystem.relevant_extensions
    ]

@dataclass
class ModuleFingerprint:
    """
    Parsed and validated representation of a module's signal fingerprint.

    Constructed by parse_fingerprint(); never build directly from raw dicts.
    """
    module_id: str
    cluster: str
    version: str
    question_template: str
    default_threshold: float        # 0.0–1.0

    filesystem: Optional[FilesystemPrior] = field(default=None)
    memory: Optional[MemoryPrior] = field(default=None)
    time: Optional[TimePrior] = field(default=None)