Module heuristics_bank

Expand description

DSFB-Debug: Heuristics Bank — 32 hand-curated motifs with full Phase 0–8 fusion-axis decision parameters.

§What this module is

The heuristics bank is the IP claim of DSFB-Debug. It is a fixed-size compile-time-curated table of HeuristicEntry records that maps a structural residual signature to a named MotifClass interpretation. Each entry carries:

Reason-code anchor — which ReasonCode (drift / slew / boundary / oscillation) the motif matches.
Provenance — FrameworkDesign (hand-coded) / DatasetObserved (observed in a vendored upstream slice) / FieldValidated (confirmed in production deployment, reserved for Phase II partner engagement).
Evidence base — upstream evidence_dataset + DOI of the archive in which the signature was first observed (e.g. "tadbench_F04" + "10.5281/zenodo.6979726").
Taxonomy anchor — IEEE 24765 + Avizienis-Laprie-Randell decomposition (e.g. "IEEE 24765: 'fault propagation'; A-L-R: error → service-failure"). Every motif name is established vocabulary, never invented.
Drift / slew / boundary thresholds — gating predicates the closed episode must satisfy.
Correlation / duration ranges — multi-service motifs require min_correlation_count >= 3; transient motifs cap max_duration_windows.
Per-feature scoring weights — five weights (drift, slew, boundary, correlation, duration) let one motif emphasise drift while another emphasises slew.
Affinity-tier bitmask — which detector tiers route their evidence into this motif’s score (Routed Evidence Principle, paper §6.5).
Phase-5.6+ confuser-pair declaration — explicit motif that competes for the same residual signature; episodes failing the margin_vs_confuser gate surface as ConfuserAmbiguous rather than committing to a single typing.
Phase-7 primary witness tiers — strict subset of affinity tiers that MUST fire for typed confirmation.
Phase-8 named witness detectors — strict per-detector anti-hallucination gate; ≥1 of the captured named witnesses must fire.
Dashboard hint — operator-side template with ${ROOT_CAUSE_SERVICE}, ${PEAK_SLEW}, etc. placeholders that render::render_episode_summary substitutes at presentation time.

§Two lookup paths

lookup(reason_code, drift_persistence, slew_magnitude) — per-signal, called from evaluate_signal. Preserves the v0.1 wire shape (unit-weighted scoring across reason-code match + drift + slew). Populates SignalEvaluation.semantic_disposition.
match_episode_with_* family — per-episode, called from run_evaluation after aggregate_episodes closes each episode. Uses ALL features available at episode close. The post-Phase-8 entry point match_episode_with_consensus consults the 9-axis bank-aware fusion configuration (\S\ref{sec:nine_axis_fusion} in the paper); legacy match_episode_with_confidence and match_episode_with_tier_affinity are preserved for backward compatibility.

Both paths are deterministic: tie-breakers (higher provenance rank wins; lower index wins) preserve Theorem 9 across all configs.

§Endoductive discipline (panel-locked)

The bank intentionally does NOT carry motifs for LO2-style API-semantic anomalies (OAuth2 flow / architectural-degradation patterns). Those are validated against the SemanticDisposition::Unknown branch by tests/eval_lo2.rs. Adding LO2-specific motifs would destroy the validator. The absence is by design — see paper §5.6 and Session-3 panel directive.

§Standards alignment

NIST SP 800-53 AU-3 (“audit record content”): each entry’s (provenance, evidence_dataset, evidence_dataset_doi, taxonomy_ref, dashboard_hint) collectively satisfies the “what / when / where / source / outcome” content requirement at per-motif granularity.
NIST SP 800-53 AU-2 (“auditable events”): the primary_witness_detectors list defines the named auditable events that must fire for typed confirmation.
IEEE 24765 + Avizienis-Laprie-Randell: every motif name decomposes into established software-engineering vocabulary. No ad-hoc naming.
IEEE 1012-2016 (“verification and validation”): the confuser-boundary mechanism (margin_vs_confuser) provides independent confirmation of typed disposition before declaring Named(motif) rather than ConfuserAmbiguous.

§Theorem 9 contract

Every public method preserves deterministic replay. The bank itself is Copy + Clone + Debug + PartialEq (every field is Copy-able), so two HeuristicsBank instances with the same entries array produce byte-identical match_* results on the same inputs.

Structs§

HeuristicsBank: The heuristics bank: a fixed-size array of known motif patterns. Provenance-aware: each entry records where it came from.

Constants§

Functions§

affinity_tiers_for: Tier-affinity mask for a motif: which detector tiers are predictive for the motif’s reason-code structural signature. Multi-service motifs (min_correlation_count >= 3) get multivariate tiers added regardless.