Quality and Security Harness

voiage treats repository automation as a release surface. The local harness and GitHub workflows therefore validate both Python behavior and the controls that protect changes, dependencies, and published artifacts.

Local gates

Run affected checks during iteration and the complete gate once for the final candidate:

tox run-parallel -p 2

For local acceptance runs, wrap that same gate in the resource guard using the verified repository interpreter and a work directory on a volume with space:

.venv/bin/python scripts/guard_verification.py \
  --work-dir .conductor/local/guarded-acceptance \
  -- .venv/bin/tox run-parallel -p 2

The guard samples combined process-group RSS every two seconds, stops the job above 4 GiB, after one hour, or below 2 GiB free in its work or temporary volume. It places temporary files in a unique sibling of the checkout on the same volume, cleans them after successful runs, limits native thread pools, and writes resource-report.json with the peak sampled RSS and termination reason. A limit exit is a failed gate, never acceptance evidence. Increase a limit only after reviewing the recorded workload. Coverage uses two workers. Sampling cannot prevent a brief allocation spike; subprocesses must retain their process group. The guard only terminates its own isolated group, including leftover children. It disables detached Git file-monitor daemons for the job through a process-local override, preserving existing Git settings and shared repository configuration.

The harness is included in tox; a second standalone harness run is unnecessary. Record the tested tree, environment and result. Reuse successful local evidence when these inputs remain unchanged. A new runtime, dependency, shared-fixture or test-infrastructure change requires broader validation. Hosted required checks remain bound to the current PR revision. Batch edits before pushing, rebase locally with signed commits, and inspect the actual failed gate before changing a branch; repeated pushes restart hosted validation.

The harness tox environment checks that workflows declare explicit permissions, external actions are pinned to immutable commits, required security workflows exist, and repository governance files are present. The full tox environment additionally runs linting, type checking, docs, contract validation, the supported Python matrix, and the coverage threshold.

The installed-provider consumer test uses a private download cache by default and ignores an inherited UV_CACHE_DIR. To reuse an existing writable cache deliberately, locate it with uv cache dir, then set VOIAGE_TEST_UV_CACHE_DIR to that directory when running pytest or tox. This reuses dependency downloads only: each test still builds the real wheels, creates a fresh consumer environment, copies installed files, and probes the public SDK outside the checkout. It does not disable dependency resolution or make the test offline. Each build, install, and probe has a ten-minute timeout. Reuse follows uv’s cache-safety contract; do not manually change files inside that cache.

For dependency-only changes, also run uvx --from pip-audit pip-audit --local --progress-spinner off and pnpm audit --prod from docs/astro-site.

Before starting a local gate in a shared checkout, check whether another task already owns a running tox process and its result log. Coordinate reuse of that run instead of launching a second process against the same .tox directory. Use the same tox executable and interpreter for follow-up environments: mixing global and repository-managed tox processes can recreate each other’s caches. If an independent run is necessary, give it a separate work directory. Do not stop another task’s process or treat its pending result as a pass.

Dependency and experimental-feature policy

The supported Python 3.15.1 range tracks compatible stable dependencies and commits uv.lock for reproducibility. Before dependency or runtime changes, run uv lock --upgrade and python scripts/dependency_frontier.py . --strict.

Apache Arrow/Parquet is the canonical public tabular interchange; JSON Lines is an explicit human-debug format. Experimental serializers, JAX, NumPyro, accelerators, and distributed runtimes remain behind named extras and require round-trip, numerical-equivalence, provenance, and CPU-reference evidence before promotion. Python free-threading remains an observation lane rather than a release or performance claim.

Standardized-ingestion benchmarks use generated, bounded local fixtures and record stages, input dimensions, and memory rather than enforcing elapsed-time budgets. They cover only the strict Croissant CSV and Frictionless local CSV/JSON/Parquet/Arrow profiles; they are not evidence about network transport, remote catalogues, or upstream parser performance.

GitHub gates

The hosted repository runs CodeQL, OpenSSF Scorecard, Dependency Review, and Zizmor. Workflows also enforce SHA-pinned actions, least-privilege permissions, disabled credential persistence on security-sensitive checkouts, and release artifact provenance attestations. The release workflow also publishes the signed SLSA bundle as a .intoto.jsonl release asset so independent tools can discover provenance without privileged access to GitHub’s attestation store.

The protected main ruleset requires pull requests, resolved review threads, successful required checks, signed commits, and linear history. The required approval count is zero for the single-maintainer operating model; CODEOWNERS still routes review responsibility without creating an impossible independent approval gate. Hosted settings must be verified through the GitHub API because they are not represented by files in the checkout.

OpenSSF’s aggregate Scorecard is interpreted check by check. Independent human review and multi-organisation contributor diversity are useful signals, but a single-maintainer project cannot manufacture either signal. The repository therefore retains zero required approvals while requiring the complete automated matrix, signed commits, current branches, resolved threads, and immutable releases. Those deliberate exceptions should not be bypassed with bot approvals, alternate accounts, synthetic contributors, or placeholder releases.

GitHub immutable releases should be enabled in hosted repository settings so published release assets and their tag cannot be modified.

TestPyPI promotion requires exact SHA-256 equality with the privately reviewed release payload, GitHub build-provenance verification, cryptographic attestation verification, and clean-install smoke tests on every supported Python version. Because the attestation client’s direct-URL mode accepts only the production distribution host, the workflow retrieves each provenance object from TestPyPI’s Integrity API and verifies it against the corresponding reviewed local distribution. Integrity API, identity, digest, signature, and certificate errors all fail closed.

Owner and organization gates

Some controls cannot be configured from this repository alone:

• organization-wide Actions policies, runner groups, and required workflows;
• billing- or plan-dependent secret-scanning validity checks;
• enterprise security policy and outside-collaborator restrictions;
• environment reviewers and production deployment approvals.

These remain administrator-owned follow-up gates and must not be represented as locally complete merely because repository workflows pass.

Runtime dependency agreement

The reviewed runtime set in specs/dependency-runtime-policy.json binds PyPI, Conda requirements, tox Polars/Arrow floor/latest lanes and dependency previews. Run .venv/bin/python scripts/check_packaging_dependencies.py . to reject drift. Polars >=2.1.0,<3 and Arrow >=26.0.0,<27 retain the qualified Python 3.15.1 surface; scientific core bounds remain unchanged. Published requirements omit pandas and xarray. The explicit, unpublished producer-tests group supplies external producer/oracle tests and stays outside default and wheel installs. Test setup uses uv sync --extra ci --extra dev --group producer-tests.

Conda’s immutable published source pin remains a separate release handoff. Dependency agreement and a clean wheel are not native Conda build acceptance.

Pandas-free enforcement

The required lint lane runs .venv/bin/python scripts/check_pandas_free.py --source voiage. It rejects direct pandas/xarray import nodes in every Python source and type stub, including lazy, unreachable and type-only imports. It has no file exclusions and does not honor noqa or suppression pragmas. Templates and metadata strings are not import nodes; their separate repository-reference gate remains Phase 7.

tox run -e pandas-free installs the real wheel with no extras, dependency groups or test dependencies. A fresh isolated Python 3.15.1 subprocess verifies that neither legacy distribution is installed and neither module is loaded by import voiage. It checks the package path against the tox environment to reject source shadowing. Negative controls demonstrate actual rejection. Linux, macOS and Windows CI use that same lane. The bootstrap’s unpublished verification group contains only locked tox tools and is separate from the no-extras target environment and the producer-test group.

The existing protected Lint & Type Check job invokes the source rule directly, and Unit Tests (Python 3.15.1) also executes the no-extras tox lane. These checks therefore remain part of the current required status contexts; no branch-protection relaxation or new-job registration is needed.

External producer acceptance

The default producer-compatibility tox lane tests the installed base wheel with pytest and the unpublished producer-tests group. Isolated Python, importlib-mode collection and a narrow conftest boundary keep checkout imports out of that lane; both its main and fresh child processes verify the package location. Real caller-created frames exercise frozen row/binding/digest results, nullable and sliced inputs, buffer identity, import ownership and stable errors. Negative controls prove the runtime-import watcher detects reintroduced imports.

The existing protected unit job and Linux/macOS/Windows base-runtime matrix run this lane alongside pandas-free. The latter retains its separate environment with no producer tooling. Observed numeric buffer sharing does not change the existing strict-copy policy or claim that every conversion is zero-copy.

Complete reference policy

Both protected lint and local tox run scripts/check_reference_policy.py. It scans every Git-tracked text file, including notebook JSON, generated-code strings and workflows. Exact reference-line fingerprints include occurrence counts, so an approved producer test cannot hide an added or duplicated reference. Whole-file hashes protect immutable historical evidence. Deleted permissions, changed evidence, unsafe paths and empty scans fail closed. No path globs, suppression directives or automatic refresh command are supported.

The producer-compatibility scope includes the existing external Parquet metadata key, explicit test-tool declarations and executable absence controls. These narrow permissions preserve caller behavior; the runtime AST import ban still has no exemption. Old source-bound HPC inputs remain unchanged and independently validated; current candidate declarations have separate unfulfilled native source/solver/build/installed-module gates.

Build-capacity observations

The obsolete fixed EasyBuild replay admission floor has been removed from the current candidate. Current sizing and the accepted support scope are tracked by B6-CAP1–B6-CAP4; G04.4/G04.5 own common instrumentation and ordinary verification calibration.

The guard accepts --workload-id, --cache-state (cold, warm, mixed or unknown), --identity-file (a JSON object describing feature/toolchain configuration), repeatable --artifact-dir and repeatable --disk-path. Disk paths must exist; artifact directories may be absent before a build. It records source/configuration hashes, interpreter identity, start/end/minimum filesystem free space and before/after directory allocation. Declare cache state honestly; do not purge shared caches. Pass explicit cache/temporary volumes via --disk-path when needed.

Filesystem samples deduplicate device IDs and run at the existing guard interval. Directory scans occur only before launch and after termination, before successful private-temporary cleanup. Failed runs retain their private temporary evidence. Snapshots are not peaks; filesystem deltas include unrelated activity and sampled peaks may miss spikes. Directory allocations can include shared blocks and must not be summed across overlapping roots. A VM needs separate host-backing evidence; this guard alone never claims physical-capacity qualification. Monitoring failures remain failures even when the child command succeeded.