detectorproof 0.1.0__tar.gz

detectorproof-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,152 @@
+name: CI
+
+# `workflow_call` matters: release.yml invokes this file rather than repeating
+# its steps, so there is exactly one definition of "the gate" and a release can
+# never run a weaker one than a pull request.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+# Read-only for every job in this file. Nothing here needs to write to the
+# repository, and nothing here may publish: `id-token` is never granted, so no
+# job defined in this workflow can mint a PyPI credential even if a step tried.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  attribution:
+    name: attribution
+    runs-on: ubuntu-latest
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          # The scan reads recent commit messages; the default shallow clone of
+          # depth 1 would silently scan one commit and pass.
+          fetch-depth: 25
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+      - name: Scan the tracked tree, the metadata and recent commits
+        run: python scripts/ci.py attribution
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+      # Pinned on purpose. An unpinned linter turns a green repository red on a
+      # morning when nobody changed anything. Bumping this is a pull request.
+      - name: Install ruff
+        run: pip install "ruff==0.16.1"
+      - name: Lint
+        run: ruff check .
+
+  test:
+    name: pytest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One red cell must not hide the other seven. Which versions fail is the
+      # information a matrix exists to produce.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install the package and its dev extra
+        run: pip install -e ".[dev]"
+      - name: Run the test suite
+        run: pytest -q
+      # This package has no optional dependencies, so nothing can legitimately
+      # skip. A skip means a test that runs in no environment at all.
+      - name: Nothing is skipped
+        run: python scripts/ci.py noskips
+
+  clone:
+    name: a fresh clone can run its own tests
+    runs-on: ubuntu-latest
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+      # This is a src-layout package. Every job above installs it first and so
+      # would never notice if a bare checkout could not collect its own tests -
+      # the exact defect this job exists to catch in the sibling repository.
+      - name: Install pytest and nothing else
+        run: pip install "pytest>=8"
+      - name: Run the suite against the bare checkout
+        run: pytest -q
+
+  contract:
+    name: published exit codes
+    runs-on: ubuntu-latest
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+      - name: Install the package
+        run: pip install -e "."
+      # The README publishes what each exit code means to anyone wiring this
+      # into a pipeline. Unit tests cover the functions; this covers the
+      # promise, through the console script.
+      - name: Exit-code contract
+        run: python scripts/ci.py contract
+
+  package:
+    name: build and verify the artifact
+    runs-on: ubuntu-latest
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: pip install "build==1.5.1" "twine==6.2.0"
+      - name: Versions agree
+        run: python scripts/ci.py version
+      - name: Build sdist and wheel
+        run: python -m build
+      # The filenames carry the version. A build that quietly produced a stale
+      # one would still pass `twine check` and still install, so the names are
+      # checked against the project version before anything downstream trusts
+      # them.
+      - name: Distributions match the project version
+        run: python scripts/ci.py artifact
+      - name: Metadata is renderable
+        run: twine check dist/*
+      # Everything above tests the source tree. This installs the artifact a
+      # user would download, into an interpreter with no source directory on its
+      # path, and asks it to work.
+      - name: Install the wheel into a clean environment and smoke it
+        run: python scripts/ci.py wheelcheck
+      # v7.0.1
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: distributions
+          path: dist/

detectorproof-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: Release
+
+# A tag is the only trigger. There is no manual "publish" button, no
+# workflow_dispatch, and no branch that publishes on merge, so the released
+# version is always a named point in history that someone can check out.
+#
+# Read this line before typing `git tag`: pushing a v* tag IS publishing to
+# PyPI. There is no second confirmation step anywhere below.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  # The same file a pull request runs - not a copy of it and not a subset. A
+  # release that could pass a weaker gate than a pull request is the fault this
+  # reuse exists to prevent. ci.yml already builds the distributions, checks
+  # their filenames carry the project version, renders the metadata and installs
+  # the wheel into a clean interpreter, so there is nothing left for this file
+  # to verify about the artifact itself.
+  gate:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: publish to PyPI
+    needs: gate
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/detectorproof
+    permissions:
+      # A job-level `permissions:` block REPLACES the workflow-level one, it
+      # does not add to it. Declaring only `id-token: write` here therefore set
+      # `contents` to none, and `actions/checkout` needs `contents: read` - on a
+      # private repository the checkout below would have failed. Both are listed
+      # explicitly.
+      #
+      # `contents` stays READ. Creating the GitHub release needs write, and that
+      # is a separate job with its own block.
+      #
+      # Trusted publishing: PyPI mints a short-lived token from this OIDC
+      # identity, so there is no long-lived API token in the repository, in an
+      # organisation secret, or on the maintainer's laptop. Nothing to leak and
+      # nothing to rotate.
+      contents: read
+      id-token: write
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.12"
+
+      # `ci.py version` already checks pyproject against the package's
+      # __version__. This checks both against the tag, which is the one pairing
+      # no local gate can see - a correct package under a wrong name in history.
+      - name: The tag matches the version in the source
+        run: python scripts/ci.py version --expect "${{ github.ref_name }}"
+
+      # Publish the artifact the gate verified. Rebuilding here would upload
+      # bytes nothing tested: a different wheel, from the same source, built by
+      # a job holding an OIDC token.
+      # v7.0.0
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131
+        with:
+          name: distributions
+          path: dist
+
+      # Every third-party action in this repository is pinned to a commit SHA,
+      # not a tag, with the human-readable version in the comment above it. A
+      # moving tag is a moving credential holder, and SHA-pinning only the
+      # publisher would leave the other actions in this same OIDC-enabled job
+      # able to change under it.
+      # v1.14.2
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+
+  github-release:
+    name: GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      # v7.0.0
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131
+        with:
+          name: distributions
+          path: dist
+      # v2.6.2
+      - uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65
+        with:
+          files: dist/*
+          generate_release_notes: true

detectorproof-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.1.0 — 2026-09-22
+
+First release.
+
+`panel` only. The instrument's own build order puts `panel` first and says not to build all
+four commands at once: it is the gate `probe`, `identity` and `falsepositive` depend on, and
+it has to refuse correctly on a detector already known to be incompetent before anything is
+built on top of it.
+
+**Added**
+
+- `run_panel` — score a declared panel of frozen detectors over a labelled control set and
+  return a per-detector competence verdict.
+- Five refusals enforced in code: chance-level exclusion, panel declared before the run,
+  duplicate detector/item rows rejected rather than averaged, NOT MEASURED as a third state,
+  band-edge results recorded rather than re-banded.
+- `domain` — a declared domain for every field read, with rejection messages that name the
+  domain rather than a catalogue of values previously seen to be wrong.
+- `stats` — tie-aware midranks, AUC from the rank sum, Holm–Bonferroni with the running
+  maximum.
+- `report.render` — plain-text report in which excluded detectors still appear in full and a
+  null is worded as no evidence of a difference.
+- `detectorproof panel` command line reading three files a study already has.
+- Property fuzz over generated junk values, asserting invariants rather than outcomes.
+
+**Deliberately absent**
+
+- Any function that recommends a transformation to move a detector score. Tuning audio
+  against a chosen detector statistic was measured, in the work behind this package, to make
+  the audio more separable rather than less.

detectorproof-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Panagiotis (Panos) Gkilis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detectorproof-0.1.0/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include tests *.py
+
+# The sdist ships its tests, so it must ship what those tests read. The audit
+# regression suite exercises the release gate itself and the workflow
+# configuration, so an sdist carrying the tests but not these files produced ten
+# failures when its own bundled suite was run from the unpacked archive.
+#
+# Nothing here is private: the gate script and the two workflow files are the
+# same ones a reader gets from the repository.
+include scripts/ci.py
+include .github/workflows/ci.yml
+include .github/workflows/release.yml

detectorproof-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: detectorproof
+Version: 0.1.0
+Summary: Measure the detectors before trusting them: a declared panel of frozen synthetic-speech detectors, scored on your control set, with a chance-level detector refused rather than averaged in.
+Author-email: "Panagiotis (Panos) Gkilis" <bedvibe@bedvibe.studio>
+License: MIT
+Project-URL: Homepage, https://ai.bedvibe.studio/
+Keywords: audio-deepfake-detection,synthetic-speech-detection,detector-robustness,false-positives,neural-audio-codec,analysis-resynthesis,pre-registration,reproducibility,auc,multiple-comparisons
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=2.3; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# detectorproof
+
+**Measure the detectors before you trust any of them.**
+
+`detectorproof` is not a synthetic-speech detector and must not become one. It is an
+instrument for measuring detectors: what a declared panel of frozen checkpoints can and
+cannot do on *your* material, and what their judgments are reacting to.
+
+One command is built: `panel`. It scores a declared set of frozen detectors over a labelled
+control set, reports the area under the ROC curve for each, and refuses to let an
+incompetent one contribute to anything downstream.
+
+No audio is read and no model is loaded. It works on a score table you already have, has no
+dependencies, and runs on a machine that will never hold the corpus.
+
+```
+pip install detectorproof
+```
+
+Or from a clone, which is what you want if you intend to run the tests:
+
+```
+git clone https://github.com/Mormolykos/detectorproof.git
+cd detectorproof
+pip install .          # or: pip install -e ".[dev]" && pytest
+```
+
+Python 3.10 or newer, no runtime dependencies. Both forms install the `detectorproof`
+command and the importable package. See `CHANGELOG.md` for release status.
+
+## Why this exists
+
+On one corpus, three widely benchmarked anti-spoofing detectors sat at chance while their
+model cards advertised sub-1% equal error rates. A panel that quietly averaged them in would
+have reported a confident number built partly on models that could not do the task at all.
+
+Separately, and this is the finding the package is built around: **genuine human speech can
+move strongly toward "synthetic" after ordinary benign processing that generates nothing.**
+A neural-codec round trip of real studio recordings moved 9 of 13 frozen detectors past
+multiple-comparison correction, three of them on 47 of 47 utterances at the maximum a rank
+statistic can reach. A phase-retrieval algorithm from 1984 moved 12 of 13.
+
+Those numbers are not asserted here. They come from a published, independently audited
+study, and every one of them regenerates from its deposit:
+
+> Gkilis, P. (2026). *Reconstruction history, not synthesis: benign processing moves frozen
+> detectors on genuine human speech.* Zenodo.
+> [10.5281/zenodo.22819223](https://doi.org/10.5281/zenodo.22819223) · CC BY 4.0
+
+⚠️ Read its scope limits before quoting it: three speakers, 47 utterances, neutral speech,
+one language; seven of the thirteen detectors come from a single research group; **no
+mechanism is identified and no listening test was run.** Thirteen of that paper's own claims
+were withdrawn during three rounds of independent adversarial audit, and the withdrawals are
+published in it.
+
+So a detector score is not interpretable without knowing the provenance of the audio it was
+computed on — and before any of that, you need to know which detectors on your panel can do
+the task on your material at all. That is what `panel` answers.
+
+## Usage
+
+```
+detectorproof panel \
+  --panel panel.json \
+  --scores scores.csv \
+  --labels labels.csv \
+  --condition CTRL
+```
+
+**`panel.json`** — the declaration, fixed before the run.
+
+```json
+[
+  {"name": "det-a", "orientation": "higher_bonafide", "identity": "sha256:1f3a...", "source": "..."},
+  {"name": "det-b", "orientation": "higher_synthetic", "identity": "rev:c1dbe2ae"},
+  {"name": "det-c", "orientation": "unresolved", "identity": "commit:72c32e28"}
+]
+```
+
+`orientation` is resolved from the model's own documentation or training-label path, never
+from what makes your benchmark look right. `unresolved` is a first-class value: the detector
+is scored and reported, and its *sign* is not interpreted.
+
+`identity` pins the weights — a revision, a commit, a file hash. It is required. A panel that
+cannot say which checkpoint produced a number is not frozen.
+
+**`scores.csv`** — `detector,item,condition,score`. One row per detector per item per
+condition. Scores are in each detector's native units. A missing measurement is written
+`NOT_MEASURED` (or `n/a`), never `0`.
+
+**`labels.csv`** — `item,label`, where label is `bonafide` or `synthetic`.
+
+In Python:
+
+```python
+from detectorproof import Detector, run_panel, render
+
+report = run_panel(detectors, scores, labels, condition="CTRL")
+print(render(report))
+
+for result in report.competent_detectors():   # the only set you may aggregate over
+    ...
+```
+
+## The refusals
+
+These are enforced in code, not described here. Each was bought by a specific measured
+failure.
+
+| refusal | the failure that bought it |
+|---|---|
+| A detector at or near chance is **NOT COMPETENT ON THIS MATERIAL** — reported in full, excluded from every aggregate | three benchmarked detectors at chance while advertising sub-1% EER |
+| The panel is **declared before the run**. An undeclared detector in the scores is a fault; a declared detector with no scores stays in the report as NOT MEASURED | a panel assembled after seeing results is a selection, not a measurement |
+| Two scores for one detector and item are a **fault**, not something to average | overlapping analysis windows treated as independent samples inflated one published proportion from 75% to 86% |
+| **NOT MEASURED is a third state** — never zero, never an absence of effect | a missing measurement reported as zero is worse than reporting nothing |
+| A near miss at the band edge is **recorded**, not resolved by widening the band | one detector landed at 0.447 against a declared band of [0.45, 0.55] and the band stayed where it was |
+
+There is deliberately **no function that recommends a transformation** to move a score, and
+there will not be one. In the work this came from, an intervention tuned against a chosen
+detector statistic made the audio *more* separable, not less — one detector's AUC moved from
+0.576 to 0.763. The instrument reports; it does not advise. That refusal is the point, not an
+omission.
+
+## What a verdict means
+
+`NOT COMPETENT ON THIS MATERIAL` is a statement about **that checkpoint on your control
+set**. It is never a statement about a detector's general quality. Every detector was trained
+by someone else, on other data, for other purposes.
+
+An empty competent set is a reportable result about your panel and your material. It is
+**not** evidence that your audio is genuine, and it is not evidence that detection is
+impossible. Absence of evidence is not evidence of absence, and nothing downstream may run on
+an empty competent set.
+
+## Design
+
+Zero dependencies in the core. Ties are handled by midranks everywhere, because a detector
+whose scores compress near zero produces long runs of equal values and a rank statistic that
+breaks ties arbitrarily reports a different answer depending on the order its input arrived
+in. AUC is computed from the rank sum rather than by counting pairs.
+
+Every field this package reads has a **declared domain** — its type, its admissible values,
+and what absence means. Validation asks whether a value is inside that declaration; it does
+not carry a list of bad values anyone has seen. That list is unbounded and the domain is not.
+
+## The family
+
+`trainproof` (training runs) · `ttsproof` (TTS failure modes) · `spkproof` (speaker-verification
+false rejection) · **`detectorproof`** (detector competence and robustness).
+
+"Did the processing preserve speaker identity?" is a different question with different
+statistics, and `spkproof` answers it. **Version 0.1.0 has no dependency on `spkproof` and does
+not call it** — the two are used side by side, not chained.
+
+## Status
+
+`panel` is built and tested. `probe`, `identity` and `falsepositive` are specified and not
+built. They are deliberately not built at the same time — `panel` is the gate the other three
+depend on, and it has to refuse correctly on a detector already known to be incompetent
+before anything is built on top of it.
+
+## Licence
+
+MIT.

detectorproof-0.1.0/README.md

@@ -0,0 +1,164 @@
+# detectorproof
+
+**Measure the detectors before you trust any of them.**
+
+`detectorproof` is not a synthetic-speech detector and must not become one. It is an
+instrument for measuring detectors: what a declared panel of frozen checkpoints can and
+cannot do on *your* material, and what their judgments are reacting to.
+
+One command is built: `panel`. It scores a declared set of frozen detectors over a labelled
+control set, reports the area under the ROC curve for each, and refuses to let an
+incompetent one contribute to anything downstream.
+
+No audio is read and no model is loaded. It works on a score table you already have, has no
+dependencies, and runs on a machine that will never hold the corpus.
+
+```
+pip install detectorproof
+```
+
+Or from a clone, which is what you want if you intend to run the tests:
+
+```
+git clone https://github.com/Mormolykos/detectorproof.git
+cd detectorproof
+pip install .          # or: pip install -e ".[dev]" && pytest
+```
+
+Python 3.10 or newer, no runtime dependencies. Both forms install the `detectorproof`
+command and the importable package. See `CHANGELOG.md` for release status.
+
+## Why this exists
+
+On one corpus, three widely benchmarked anti-spoofing detectors sat at chance while their
+model cards advertised sub-1% equal error rates. A panel that quietly averaged them in would
+have reported a confident number built partly on models that could not do the task at all.
+
+Separately, and this is the finding the package is built around: **genuine human speech can
+move strongly toward "synthetic" after ordinary benign processing that generates nothing.**
+A neural-codec round trip of real studio recordings moved 9 of 13 frozen detectors past
+multiple-comparison correction, three of them on 47 of 47 utterances at the maximum a rank
+statistic can reach. A phase-retrieval algorithm from 1984 moved 12 of 13.
+
+Those numbers are not asserted here. They come from a published, independently audited
+study, and every one of them regenerates from its deposit:
+
+> Gkilis, P. (2026). *Reconstruction history, not synthesis: benign processing moves frozen
+> detectors on genuine human speech.* Zenodo.
+> [10.5281/zenodo.22819223](https://doi.org/10.5281/zenodo.22819223) · CC BY 4.0
+
+⚠️ Read its scope limits before quoting it: three speakers, 47 utterances, neutral speech,
+one language; seven of the thirteen detectors come from a single research group; **no
+mechanism is identified and no listening test was run.** Thirteen of that paper's own claims
+were withdrawn during three rounds of independent adversarial audit, and the withdrawals are
+published in it.
+
+So a detector score is not interpretable without knowing the provenance of the audio it was
+computed on — and before any of that, you need to know which detectors on your panel can do
+the task on your material at all. That is what `panel` answers.
+
+## Usage
+
+```
+detectorproof panel \
+  --panel panel.json \
+  --scores scores.csv \
+  --labels labels.csv \
+  --condition CTRL
+```
+
+**`panel.json`** — the declaration, fixed before the run.
+
+```json
+[
+  {"name": "det-a", "orientation": "higher_bonafide", "identity": "sha256:1f3a...", "source": "..."},
+  {"name": "det-b", "orientation": "higher_synthetic", "identity": "rev:c1dbe2ae"},
+  {"name": "det-c", "orientation": "unresolved", "identity": "commit:72c32e28"}
+]
+```
+
+`orientation` is resolved from the model's own documentation or training-label path, never
+from what makes your benchmark look right. `unresolved` is a first-class value: the detector
+is scored and reported, and its *sign* is not interpreted.
+
+`identity` pins the weights — a revision, a commit, a file hash. It is required. A panel that
+cannot say which checkpoint produced a number is not frozen.
+
+**`scores.csv`** — `detector,item,condition,score`. One row per detector per item per
+condition. Scores are in each detector's native units. A missing measurement is written
+`NOT_MEASURED` (or `n/a`), never `0`.
+
+**`labels.csv`** — `item,label`, where label is `bonafide` or `synthetic`.
+
+In Python:
+
+```python
+from detectorproof import Detector, run_panel, render
+
+report = run_panel(detectors, scores, labels, condition="CTRL")
+print(render(report))
+
+for result in report.competent_detectors():   # the only set you may aggregate over
+    ...
+```
+
+## The refusals
+
+These are enforced in code, not described here. Each was bought by a specific measured
+failure.
+
+| refusal | the failure that bought it |
+|---|---|
+| A detector at or near chance is **NOT COMPETENT ON THIS MATERIAL** — reported in full, excluded from every aggregate | three benchmarked detectors at chance while advertising sub-1% EER |
+| The panel is **declared before the run**. An undeclared detector in the scores is a fault; a declared detector with no scores stays in the report as NOT MEASURED | a panel assembled after seeing results is a selection, not a measurement |
+| Two scores for one detector and item are a **fault**, not something to average | overlapping analysis windows treated as independent samples inflated one published proportion from 75% to 86% |
+| **NOT MEASURED is a third state** — never zero, never an absence of effect | a missing measurement reported as zero is worse than reporting nothing |
+| A near miss at the band edge is **recorded**, not resolved by widening the band | one detector landed at 0.447 against a declared band of [0.45, 0.55] and the band stayed where it was |
+
+There is deliberately **no function that recommends a transformation** to move a score, and
+there will not be one. In the work this came from, an intervention tuned against a chosen
+detector statistic made the audio *more* separable, not less — one detector's AUC moved from
+0.576 to 0.763. The instrument reports; it does not advise. That refusal is the point, not an
+omission.
+
+## What a verdict means
+
+`NOT COMPETENT ON THIS MATERIAL` is a statement about **that checkpoint on your control
+set**. It is never a statement about a detector's general quality. Every detector was trained
+by someone else, on other data, for other purposes.
+
+An empty competent set is a reportable result about your panel and your material. It is
+**not** evidence that your audio is genuine, and it is not evidence that detection is
+impossible. Absence of evidence is not evidence of absence, and nothing downstream may run on
+an empty competent set.
+
+## Design
+
+Zero dependencies in the core. Ties are handled by midranks everywhere, because a detector
+whose scores compress near zero produces long runs of equal values and a rank statistic that
+breaks ties arbitrarily reports a different answer depending on the order its input arrived
+in. AUC is computed from the rank sum rather than by counting pairs.
+
+Every field this package reads has a **declared domain** — its type, its admissible values,
+and what absence means. Validation asks whether a value is inside that declaration; it does
+not carry a list of bad values anyone has seen. That list is unbounded and the domain is not.
+
+## The family
+
+`trainproof` (training runs) · `ttsproof` (TTS failure modes) · `spkproof` (speaker-verification
+false rejection) · **`detectorproof`** (detector competence and robustness).
+
+"Did the processing preserve speaker identity?" is a different question with different
+statistics, and `spkproof` answers it. **Version 0.1.0 has no dependency on `spkproof` and does
+not call it** — the two are used side by side, not chained.
+
+## Status
+
+`panel` is built and tested. `probe`, `identity` and `falsepositive` are specified and not
+built. They are deliberately not built at the same time — `panel` is the gate the other three
+depend on, and it has to refuse correctly on a detector already known to be incompetent
+before anything is built on top of it.
+
+## Licence
+
+MIT.