Appendix & Developer Guide

Experimental research disclaimers, internal audit status matrix, environment setup, and detector module developer contracts.

1. Experimental Research Disclaimer

Experimental Research Pending External Review

This project is experimental and provided for research and educational purposes only.

All performance claims are preliminary, self-reported, and have not been independently validated or peer-reviewed. This software system must not be used for safety-critical, medical, financial, or production decisions without independent professional assessment and external review by qualified domain experts. Use at your own risk.

2. Audit & Review Status Matrix

Milestone	Status	Details
Internal Code Integrity Audit	Passed	All pipeline modules verified as real, non-stub implementations
Internal Results Integrity Audit	Reopened	Causal scoring and provenance controls applied; external reproduction remains pending
Unit, Integration & E2E Tests	Smoke Checks Passed	Unit/integration checks pass; end-to-end tests verify finite, reproducible behavior rather than fixed synthetic accuracy targets
Zero-Lookahead Invariant	Verified	Stream vs batch Euclidean distance = 0.0000
Execution Determinism	Verified	SHA-256 hash reproducibility across independent execution runs
VUS Metric Correction	Applied	Label-only range buffering enforced; predicted scores never buffered
Independent External Peer Review	Pending	Not yet independently reviewed or reproduced by external labs
Safety-Critical / Production Audit	Not Audited	Not suitable for deployment without rigorous external security audit

3. Remediation Details

During internal scientific audit, the following technical discrepancies were identified and remediated:

Causal State Update Fix

Detectors, robust normalization, and adaptive gating now score the current observation before incorporating it into future state.

Provenance-Controlled Data

Benchmark loading requires a sidecar manifest with source, license, label semantics, synthetic status, and checksum; synthetic data is opt-in for smoke tests only.

Explicit Null Evaluation

The stream protocol reports chronological warm-up, a persistence baseline, IAAFT surrogate statistics, empirical significance, and per-detector results.

VUS Score Inflation Fix

apply_range_buffer was erroneously applied to both ground-truth labels and predicted anomaly scores. Corrected to buffer labels only.

Detector Naming Realignment

Two detectors were renamed to accurately reflect their underlying mathematical structures (ARFilterDetector and MSETransformerAutoencoder).

Reference Comparison Removal

External comparative claims against closed-source references were removed due to metric and evaluation protocol mismatches.

Unit Test Fixes

Resolved three failing tests by correcting StreamBuffer __len__ calculation, MetaJudge convex fusion normalization, and FNN threshold calibration.

4. Requesting an Independent Review

If you are a researcher or domain expert interested in auditing or replicating these results:

Open a Scientific Review Request Issue on the project GitHub repository.
Submit your independent evaluation methodology, datasets, and reproduction results.
All external replication reports will be linked on this site, whether they confirm or challenge the reported metrics.

5. Environment Setup

To set up a local development environment for the Python codebase:

git clone https://github.com/mohamedhossammohamed/open-phase-ensemble.git
cd open-phase-ensemble

# Create & activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install editable package with dev dependencies
pip install --upgrade pip
pip install -e .

# Run pytest test suite
PYTHONPATH=src pytest tests/ -v

6. Adding a New Detector Module

All detector modules in the 6-detector battery implement the DetectorABC contract defined in src/tsad/detectors/base.py:

from abc import ABC, abstractmethod
import numpy as np
from typing import Tuple

class DetectorABC(ABC):
    @abstractmethod
    def score(self, Z_t: np.ndarray, v_t: float) -> Tuple[float, float]:
        """
        Calculates instantaneous anomaly score s_t in [0, 1] 
        and forward forecast v_hat_{t+h}.
        """
        pass

    @abstractmethod
    def update(self, v_true: float):
        """
        Updates internal model state with newly observed true scalar v_t.
        """
        pass

Steps to Register a New Detector:

Create a module file in src/tsad/detectors/your_detector.py inheriting from DetectorABC.
Calibrate raw output scores $s_t \in [0, 1]$ using robust median/MAD statistics so normal baseline output is $\approx 0.0$.
Register the detector class in src/tsad/pipeline.py inside self.detectors.
Update K_DETECTORS in src/tsad/config.py.
Add unit tests in tests/unit/test_detectors.py.