Metadata-Version: 2.4
Name: szl-evidence-mandate
Version: 0.1.2
Summary: Scientific Evidence Gate engine plus evidence-backed estate audits (GitHub + Hugging Face).
License: Apache-2.0
Project-URL: Homepage, https://github.com/szl-holdings/szl-evidence-mandate
Project-URL: Source, https://github.com/szl-holdings/szl-evidence-mandate
Project-URL: Issues, https://github.com/szl-holdings/szl-evidence-mandate/issues
Project-URL: Changelog, https://github.com/szl-holdings/szl-evidence-mandate/releases
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Provides-Extra: sign
Requires-Dist: cryptography>=42; extra == "sign"
Dynamic: license-file

# szl-evidence-mandate

<!-- szl:header v1 -->
<!-- Native identity: szl-brand@4309f6fce89179331b0b3ed8c99494e76c5be256; Orbit v2 icon. -->
<p>
  <a href="https://github.com/szl-holdings">
    <img src="https://raw.githubusercontent.com/szl-holdings/szl-brand/4309f6fce89179331b0b3ed8c99494e76c5be256/kit/logos/orbit-v2/suite/szl-icon-32.svg" alt="SZL Holdings — Orbit v2" width="32" height="32" />
  </a>
</p>

**Control before action. Evidence after.**

[Product](https://a-11-oy.com) · [Proof](https://a11oy.net) · [GitHub organization](https://github.com/szl-holdings)
<!-- /szl:header -->

## Scope and data boundary

This repository is not a clinical tool: its evidence engine and audits must
never receive patient data, PHI or clinical records. It audits repositories and
Hugging Face assets of the SZL Holdings estate, and its engine reads the project
files that a manifest declares.

[![PyPI](https://img.shields.io/pypi/v/szl-evidence-mandate)](https://pypi.org/project/szl-evidence-mandate/) [![Python](https://img.shields.io/pypi/pyversions/szl-evidence-mandate)](https://pypi.org/project/szl-evidence-mandate/)

A Scientific Evidence Gate engine plus evidence-backed, read-only audits of the
`szl-holdings` GitHub organisation and the `SZLHOLDINGS` Hugging Face estate.

> A passing check must emit enough evidence to prove it had the opportunity to fail.
> The system producing an answer must not be the sole authority certifying that its own
> verification occurred.

**Maturity:** research prototype (0.1.2 source candidate; the last PyPI release may differ).
**Licence:** Apache-2.0 (org standard; see `LICENSE`).

## What it does

| Component | What it verifies |
|---|---|
| `szl_evidence` engine | Manifest-declared inputs are present, opened and fully examined; every required check ran (hash-chained invocation ledger); claims are registered, replayable and numerically correct; dependency staleness blocks publication; receipts are canonical and content-bound. Exit codes: PASS 0, FAIL 1, ABSTAIN 2, ERROR 3. |
| Mutation harness | 19 mandated mutations + 4 blind-spot probes; undetected mutations are reported as `BLIND_SPOT`, never hidden. |
| `audit.github` | Every repo (all pages), shallow clones, file-class presence, licence consistency, secret scan (locations only), risky-code patterns, CI/release/protection state, clean-venv install/import/--help/tests, 12-axis scorecard. |
| `audit.huggingface` | Every model/dataset/Space, card scorecard, Space runtime + read-only probes, weight-header checks by HTTP range, small-array loads without pickle, dataset slices, conformance-corpus replay against the paired verifier. |
| `reconcile` / `zoomout` | Cross-surface links, orphans, version drift, schema skew, recomputed inventories vs every stated count; band-aid detection with root cause and structural fix. |

## Quick start (under ten minutes)

```bash
python -m venv .venv
.venv/bin/pip install -e ".[dev]"          # Windows: .venv\Scripts\pip
szl-audit engine verify fixtures/valid      # exit 0
szl-audit engine verify fixtures/empty-input  # exit 2 (ABSTAIN: nothing examined)
szl-audit engine mutate fixtures/valid      # prints BLIND_SPOTS
python -m pytest -q
```

Full audit (read-only; uses `GITHUB_TOKEN`/`gh auth token` and `HF_TOKEN`/HF cache token if present, never printed):

```bash
szl-audit engine report --output reports
szl-audit github --org szl-holdings --clone --stream --deep --output reports   # --stream: one repo on disk at a time
szl-audit hf --org SZLHOLDINGS --functional --output reports
szl-audit reconcile --output reports
szl-audit zoomout --output reports      # also renders reports/00..11
```

Every command writes a receipt under `reports/receipts/` and supports `--dry-run`.

### Optional signed engine receipts

Install the `sign` extra to make Ed25519 signing available, then configure
`SZL_RECEIPT_ED25519_KEY` with the path to a protected, unencrypted Ed25519 PEM private key.
Do not put the key or its contents in a repository or receipt. For an engine run that must
produce a signature, use `szl-audit engine verify fixtures/valid --require-signed`.
An absent dependency, key, or usable Ed25519 signature retains an `UNSIGNED` receipt and
returns CLI exit code 3 with `signature_requirement: BLOCKED_UNSIGNED`, even if the engine
checks themselves passed. The receipt keeps the engine result so the signing failure cannot
erase a scientific finding. Without the flag, signing remains optional and honest `UNSIGNED`
receipts keep their existing exit codes. A successful local signature is self-checked before
the receipt is written, but a recipient must independently verify it against a trusted public
key; `engine verify-receipt` currently checks content/ledger integrity, **not** signer identity.

## Evidence boundary

- **Integrity:** receipts bind content by SHA-256 and chain invocations. Receipts are
  `UNSIGNED` unless a usable Ed25519 key and signing dependency are configured; no signature
  is ever fabricated. `SIGNED` identifies local signing, not independent signer trust.
- **Performance:** not measured by this tool beyond wall-clock durations of smoke tests.
- **Validity:** not established. A receipt supports integrity, provenance, and
  replayability. It does not establish scientific truth, accuracy, safety, or fitness for use.

## What this does not prove

- That audited repositories or models are correct, secure, or fit for any purpose.
- That the engine catches defect classes outside its mutation set (see published blind spots).
- That a claim marked `UNVERIFIABLE` is false, or that a `STALE` claim was ever wrong.
- That install failures observed on the (Windows) audit host reproduce on Linux.

## Layout

`src/szl_evidence/` engine and audits · `fixtures/` 19 generated fixtures (regenerate
with `szl_evidence.fixturegen.build_all`) · `schemas/` receipt and manifest JSON Schemas ·
`tests/` · `reports/` generated output · `examples/`.
