ASTRA synthetic gating demo

Security Health

Scope / Non-Claim Statement

This repository supports the ASTRA synthetic gating demo: a controlled, fixed-seed toy experiment showing how an amplitude-based gating (preprocessing) step can suppress a short transient prior to downstream scoring. It is not a detector-data result and makes no astrophysical detection claim. No proprietary detector data are included.

Licensing (Split by Artifact Type)

• Software code in this repository (Python package and helper scripts): MIT License — full text in LICENSE.
• Manuscript text and figures (the preprint and LaTeX prose under paper/): CC-BY-4.0.
• Generated reproduction artifacts (logs, CSV, TeX tables, NPZ outputs produced by the scripts): CC0-1.0 public domain dedication.

Only the MIT text is bundled in this repository; the CC-BY-4.0 and CC0-1.0 grants above are made by reference to the canonical texts linked. Where a file contains its own license notice, that notice takes precedence for that file.

Citation

For citation metadata, see CITATION.cff.

Artifact Consistency Checks (What Is and Is Not Verified)

Run:

• python repro/verify_astra.py

repro/verify_astra.py checks the regenerated bundle against a fixed contract: that the four expected artifacts exist, that verification_log.txt and mc_summary.csv carry the required fields, that the run used seed 123 and produced 200 Monte Carlo rows, that snr_after < snr_before, and that the gated fraction lands in (0, 0.1).

On its own that is an internal-consistency check, not a golden-file diff: a run that satisfied every invariant with different numbers would still pass. So a second script closes that gap.

• python repro/check_reference_artifacts.py

This one diffs the regenerated bundle against the reference copies tracked in paper/, cell by cell. Both scripts run in CI on Windows and Linux.

The comparison is exact, on both platforms CI runs. Getting there meant fixing two things rather than loosening the check.

np.std reduces in an order that depends on SIMD width, so identical values summed to a different final ulp on different CPUs. That shifted threshold = 8σ and moved the reported statistics. astra.astra_proof.population_std reduces with math.fsum, which is correctly rounded and therefore order-independent.

Separately, numpy's normal generator is not bit-reproducible across C runtimes: a handful of the 245,760 draws come out one ulp apart on different machines. This is visible even between two Linux CI runners with different CPUs, so it cannot be pinned away. Reporting those statistics to 17 significant digits was therefore claiming precision that encodes which processor ran the job. astra.astra_proof.report serialises them at ten significant digits — far more than a peak-based SNR proxy carries, and the precision at which the published artifacts actually reproduce.

Full-precision arrays are still written to astra_injection.npz for anyone who wants them; it is the reported summary statistics that are rounded.

Directory structure

• engine/ — MIT-licensed Python package source (astra), including the demo entrypoint (python -m astra).
• paper/ — LaTeX manuscript sources used to rebuild the preprint (includes paper.tex and sections/).
• repro/ — Cross-platform scripts to regenerate artifacts, build the PDF, and verify outputs (writes a run manifest for traceability).
• tests/ — Unit tests for the gating functions and the reproduction driver.
• .github/ — CI, CodeQL, SBOM, release-attestation and Scorecard workflows, plus branch-protection ruleset payloads.
• .clusterfuzzlite/ — ClusterFuzzLite PR fuzzing target and build definition.
• scripts/ — Maintainer helper for auditing the repository's GitHub hardening settings.
• ops/, docs/ — Terraform ruleset definitions and the notes describing how they are applied.
• astra_output/ — Runtime-generated outputs from a non-MC run (created by the reproduction scripts).
• astra_submission_bundle/ — Runtime-generated bundle layout used by the paper build and verification scripts.

Quickstart

• Pinned runtime: Python 3.11.9. Dependency pins for reproduction live in requirements-lock.txt.

1) Install

Create and activate a Python 3.11.9 environment, then install the pinned dependencies and the package itself:

• pip install -r requirements-lock.txt
• pip install -e .

Installing the package is what makes python -m astra and the astra console script available. The repro/ scripts below add engine/ to PYTHONPATH themselves, so they also work from a clean clone with only pip install -r requirements.txt.

2) Generate artifacts

• python repro/run_astra.py

3) Verify generated artifacts

• python repro/verify_astra.py

4) Build the paper PDF

• python repro/build_paper.py

Building the PDF requires a LaTeX distribution available on your PATH (e.g., MiKTeX on Windows, TeX Live on Linux).