Authority Drift Simulation Reviewer Package

This repository targets Python 3.12.x. On systems with PEP 668 enabled, python3 -m pip install -r requirements.txt may fail outside a virtual environment; use python3.12 scripts/bootstrap_reviewer_env.py as the default setup path.

This repository is a reviewer-facing technical companion to "A Monitorability Standard for Governance Telemetry: Evidence from Workflow-Null Screening." It contains the simulation code, the Streamlit methodological companion, the COMPAS feasibility bridge, a single authoritative submission bundle, focused tests, and traceability documents that map paper claims to code and artifacts.

Reviewers should treat the authoritative submission bundle under results/authoritative/submission_bundle/ as the main evidence package.

The repository also keeps the underlying component analyses under results/v1/, but those are reproducibility provenance rather than the default review path.

Review from the authority_drift_simulation/ directory.

The LaTeX sources under paper_text_code/latex/ are kept in this repository as manuscript source for traceability and revision control. They are secondary to the authoritative submission bundle and reviewer docs.

Reviewer Quick Start

If you are reviewing the paper and want the shortest read-only path to the evidence:

1. Open review/REVIEWER_SUMMARY_REPORT.md.
2. Follow its 5-minute review path through summary.json, signal_tier_table.json, gate_trace.json, and positive_control_benchmark.json.
3. Use review/PAPER_SECTION_BUNDLE_MAP.md only if you want a section-by-section manuscript companion.

If those files look coherent, the rest of the review is about claim strength and method quality rather than artifact navigation.

If you need to execute the code locally, use the optional replication path:

1. Run python3.12 scripts/bootstrap_reviewer_env.py.
2. If you want to rerun the lightweight checks manually after bootstrap, run python3.12 scripts/reviewer_smoke_test.py.
3. If you want to rerun the lightweight checks manually after bootstrap, run python3.12 scripts/reviewer_bundle_parity.py.

Reviewer Documents

• review/REVIEWER_SUMMARY_REPORT.md: canonical landing page for manuscript review.
• review/PAPER_SECTION_BUNDLE_MAP.md: appendix-style section-by-section map from paper claims to bundle artifacts.
• review/REVIEW_CHECKLIST.md: appendix-style required-vs-optional review checklist.
• review/ARTIFACT_GLOSSARY.md: reference aid for bundle filenames and table roles.
• review/SIMULATION_TECHNICAL_SPEC.md: reference technical specification of the simulation.
• review/current_runs.md: reference locator for the currently exposed authoritative bundle.

Key Bundle Files

Inside the authoritative submission bundle, these files do most of the review work:

• summary.json: compact run summary, including artifact count, claim count, and component run directories.
• artifact_manifest.json: reviewer navigation map from exposed paper-facing artifact names to bundle files and results/v1/... provenance paths.
• paper_artifacts.json: collected paper-facing payloads in one file.
• claim_traceability.json: map from claim identifiers to the source analyses that substantiate them.
• positive_control_benchmark.json: exogenous framework-validation benchmark showing the screen can validate a disentangled detector.
• workflow_native_validation_benchmark.json: workflow-native validation benchmark showing the shared screening stack can validate an intentionally instrumented in-workflow telemetry channel.
• falsification_and_robustness_table.json: falsification scenarios and bounded robustness interpretation.
• contamination_robustness_table.json: contamination robustness and calibrated-recovery checks.

Repository Contents

• authority_drift_sim/: simulation package used by the paper-facing analyses.
• streamlit_app.py: Streamlit methodological companion.
• data/compas/: COMPAS files used by the feasibility-only illustration.
• paper_text_code/latex/: manuscript source and compiled paper assets.
• results/authoritative/submission_bundle/: single exposed authoritative submission bundle.
• review/: reviewer-facing traceability documents.
• scripts/reviewer_preflight.py: environment and package sanity checks for reviewers.
• scripts/bootstrap_reviewer_env.py: one-command local environment bootstrap.
• scripts/reviewer_smoke_test.py: lightweight post-setup smoke test of preflight, bundle metadata, and parity.
• scripts/rebuild_paper_bundle.py: cross-platform rerun driver.
• tests/: focused paper-facing and app-facing tests.

Replication Setup

Use one command:

python3.12 scripts/bootstrap_reviewer_env.py

That command creates .venv if needed, upgrades pip, installs requirements.txt, runs preflight, runs the lightweight smoke test, and runs the authoritative-bundle parity check.

Supported Python range: >=3.12,<3.13

For shell-specific setup, manual alternatives, and troubleshooting, see SETUP_TROUBLESHOOTING.md.

Main Entry Points

• Core monitorability analysis:

python3.12 -m authority_drift_sim.experiments.run_core --seed 20260308 --run-label reviewer-core --seed-count 100 --num-decisions 240 --initialization-decisions 240 --surveillance-decisions 240 --case-mix-replicates 8

• Falsification analysis:

python3.12 -m authority_drift_sim.experiments.run_falsification --seed 20260308 --run-label reviewer-falsification --seed-count 100 --num-decisions 240

• Contamination analysis:

python3.12 -m authority_drift_sim.experiments.run_contamination --seed 20260308 --run-label reviewer-contamination --seed-count 100 --num-decisions 240 --case-mix-replicates 8

• COMPAS feasibility illustration:

python3.12 -m authority_drift_sim.experiments.run_compas --seed 20260308 --run-label reviewer-compas

• Submission bundle assembly:

python3.12 -m authority_drift_sim.experiments.run_submission_bundle --seed 20260308 --run-label reviewer-submission

• Streamlit app:

streamlit run ./streamlit_app.py

• Reviewer smoke test:

python3.12 scripts/reviewer_smoke_test.py

Creating A New Authoritative Run

The one-command rebuild path is [scripts/rebuild_paper_bundle.py]. Use --publish-authoritative when you want the rebuilt submission bundle copied into results/authoritative/submission_bundle/ and the reviewer metadata refreshed.

From the repo root:

python3.12 scripts/rebuild_paper_bundle.py --publish-authoritative --max-workers 4

Useful options:

python3.12 scripts/rebuild_paper_bundle.py --results-root results --seed 20260308 --seed-count 100 --workflow-decisions 240 --initialization-decisions 240 --surveillance-decisions 240 --case-mix-replicates 8 --max-workers 4 --publish-authoritative

What --publish-authoritative does:

• copies the new submission bundle into results/authoritative/submission_bundle/<run_id>/
• updates review/current_runs.json
• updates review/current_runs.md
• regenerates reviewer reports

Wrapper notes:

• scripts/rebuild_paper_bundle.py now accepts --max-workers and passes it through to the seed-parallel component analyses.
• PowerShell-specific wrapper usage is documented in SETUP_TROUBLESHOOTING.md.

If you need explicit per-analysis control beyond the shared rebuild-script --max-workers setting, use the individual module entrypoints directly. For example:

python3.12 -m authority_drift_sim.experiments.run_core --seed 20260308 --run-label reviewer-core --results-root results --seed-count 100 --num-decisions 240 --initialization-decisions 240 --surveillance-decisions 240 --case-mix-replicates 8 --max-workers 4

In that manual mode, run the component analyses first, then assemble the submission bundle with authority_drift_sim.experiments.run_submission_bundle.

Expanded Review Path

1. Read review/REVIEWER_SUMMARY_REPORT.md.
2. Use review/current_runs.md only if you need the published bundle locator or component run ids.
3. Use review/PAPER_SECTION_BUNDLE_MAP.md for section-by-section manuscript review only if needed.
4. Use review/REVIEW_CHECKLIST.md to distinguish required review steps from optional replication steps.
5. Inspect the authoritative submission bundle under results/authoritative/submission_bundle/.
6. If needed, read review/SIMULATION_TECHNICAL_SPEC.md for code-backed simulation details.
7. If needed, run python3.12 scripts/bootstrap_reviewer_env.py.
8. If needed, rerun the workflow manually with python3.12 scripts/run_reviewer_workflow.py --smoke-test --parity-check.
9. If needed, rerun the full paper-facing pipeline with python3.12 scripts/rebuild_paper_bundle.py.

Approximate runtimes on this machine:

• preflight: under 10 seconds
• smoke test: under 10 seconds
• parity check: under 10 seconds
• focused pytest suite: 5-15 minutes depending on hardware
• full rebuild: several hours depending on --max-workers and hardware (the 100-seed core analysis dominates wall time)