NPZ Contracts¶

This project uses .npz artifacts as the primary offline-first exchange format.

Common keys¶

Quantum mass¶

Many Tier-2 tools accept one of: - quantum_mass (preferred) - mass - M

Positions¶

Some tools can compute quantum_mass if one of the following exists: - positions (N×D) - ra + dec (degrees)

Lensing signal¶

Cosmic/candidate catalogs commonly use: - kappa (N,)

Security and Format¶

Pickle-free NPZ files¶

All NPZ files created by this project avoid dtype=object arrays to enable loading with allow_pickle=False. This prevents arbitrary code execution when loading untrusted NPZ files.

Instead of saving dictionaries as object arrays:

# ❌ Avoid (requires allow_pickle=True)
np.savez(path, metadata=np.array([{"n": 100, "mean": 0.5}], dtype=object))

We flatten dictionaries into separate arrays with prefixed keys:

# ✓ Preferred (works with allow_pickle=False)
np.savez(path, 
    metadata__n=np.int64(100),
    metadata__mean=np.float64(0.5))

For lists of strings or complex data, we serialize to JSON:

# ✓ Preferred
np.savez(path, 
    issues_json=json.dumps(["error1", "error2"]),
    issues_count=np.int64(2))

Flattened output structure¶

Tier-2 outputs use __ (double underscore) to namespace flattened dictionaries: - mass_stats__n, mass_stats__mean, mass_stats__std - mass_stats__percentile_p10, mass_stats__percentile_p25, etc. (percentiles are expanded) - spectrum__k, spectrum__gap, spectrum__eigenvalues - collatz_fingerprint__n, collatz_fingerprint__log10_q50

This ensures all outputs are loadable with allow_pickle=False for security.

Notes¶

Tools should not download data implicitly.
Tools should close .npz handles promptly (important on Windows).
All output NPZ files must be loadable with allow_pickle=False.