aperture-gate 0.1.5__tar.gz

aperture_gate-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the Aperture project · honesty.tools
+
+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.

aperture_gate-0.1.5/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include tests *.py
+recursive-include tests/fixtures *.json

aperture_gate-0.1.5/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: aperture-gate
+Version: 0.1.5
+Summary: Deploy honesty.tools calibration certificates: gate model answers as ON_MAP / UNCERTAIN / OFF_MAP via a words-first refusal reader and a per-model logprob fingerprint probe.
+Author-email: the Aperture project <hello@honesty.tools>
+License: MIT
+Project-URL: Homepage, https://honesty.tools
+Project-URL: Documentation, https://honesty.tools/docs
+Project-URL: Calibrate, https://honesty.tools/calibrate
+Keywords: llm,hallucination,confabulation,calibration,logprobs,honesty,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: verify
+Requires-Dist: cryptography>=41; extra == "verify"
+Dynamic: license-file
+
+# aperture-gate
+
+Deploy a [honesty.tools](https://honesty.tools) calibration certificate.
+
+You calibrated a model at [honesty.tools/calibrate](https://honesty.tools/calibrate)
+(or with the public `aperture_calibrate.py`) and got a certificate JSON —
+`aperture.cert.v1` — containing a logistic probe fitted to *your model's*
+logprob confidence fingerprint over a Wikipedia-validated battery of real and
+fabricated entities. This package is the deployment half: it consumes that
+certificate and gates live answers.
+
+**The method, honestly stated.** Two instruments, words first:
+
+1. **words** — if the answer itself refuses or hedges ("no such company",
+   "I couldn't find any record…"), the verdict is `OFF_MAP`. The model said
+   so; believe it.
+2. **fingerprint** — otherwise, the gate scores
+   `[mean logprob, min logprob, mean top-5 entropy, max top-5 entropy]`
+   through the certificate's probe. Higher score = more likely fabricated.
+   `score >= off_map_thr` → `OFF_MAP`; `>= uncertain_thr` → `UNCERTAIN`;
+   else `ON_MAP`.
+3. With no logprobs and no refusal, the read degrades honestly to
+   `ON_MAP` (instrument `words-only`).
+
+The probe is calibrated **per model** — deploy the certificate for the model
+you actually serve. It separates grounded answers from confabulated answers
+about entities; it is not a general lie detector.
+
+Zero runtime dependencies (pure stdlib), Python ≥ 3.9, MIT.
+
+## Install
+
+```bash
+pip install https://honesty.tools/sdk/aperture_gate-0.1.5-py3-none-any.whl
+
+# optional — verify certificate signatures against the registry key (adds `cryptography`):
+pip install "aperture-gate[verify] @ https://honesty.tools/sdk/aperture_gate-0.1.5-py3-none-any.whl"
+```
+
+**Certificate trust.** Registry certificates are ed25519-signed. With the `[verify]` extra
+installed, `Gate.from_cert(...)` verifies the signature against the registry's pinned public
+key and **rejects a tampered or wrongly-signed certificate** (raises `ValueError`); every
+verdict carries `signature_verified` (`true`/`false`/`null`). Without `[verify]` the gate still
+works — it just notes that the signature was not verified. Expired certificates always warn.
+
+## Quickstart
+
+```python
+from aperture_gate import Gate
+
+# a registry id, a local cert path, or the cert dict itself
+gate = Gate.from_cert("openai/gpt-4o-mini")        # openai/gpt-4o-mini reference cert
+
+# 1) words-only read of any text
+gate.read_text("I couldn't find any record of that company.")
+# {'verdict': 'OFF_MAP', 'band': 'off-map', 'instrument': 'words', ...}
+
+# 2) read a raw chat.completions response (ask for logprobs yourself)
+verdict = gate.read_response(resp_dict_or_openai_object)
+
+# 3) let the gate call the endpoint (sends logprobs=true, top_logprobs=5, temperature=0)
+out = gate.ask("Tell me about the novel Glass over Brackwald.",
+               base_url="https://openrouter.ai/api/v1", api_key="sk-or-...")
+print(out["verdict"], out["score"], out["answer"][:80])
+
+# 4) or wrap an openai-python client (openai>=1.x) transparently
+client = gate.wrap(OpenAI())
+r = client.chat.completions.create(model="gpt-4o-mini",
+                                   messages=[{"role": "user", "content": "..."}])
+print(r.aperture)   # the verdict dict rides along on the response
+
+# 5) gate a STREAM in real time — the verdict lands before the answer finishes.
+#    Chunks pass through to your loop unchanged; the gate scores the calibrated
+#    window prefix as it arrives and (optionally) ABORTS off-map answers mid-stream.
+client = gate.wrap(OpenAI(), on_verdict=lambda v: v["verdict"] == "OFF_MAP")
+stream = client.chat.completions.create(model="gpt-4o-mini", stream=True,
+                                        messages=[{"role": "user", "content": "..."}])
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="")   # stops early if it reads off-map
+print(stream.aperture)   # the verdict, scored on the first `window` tokens
+```
+
+## CLI
+
+```bash
+aperture-gate read --cert openai/gpt-4o-mini --text "No such film exists."
+aperture-gate read --cert ./aperture-cert-my-model.json \
+    --query "Who founded Brindlewick & Thorne?" \
+    --base-url http://localhost:8000/v1 --key sk-...
+aperture-gate calibrate --base-url http://localhost:8000/v1 --model my-llama-70b
+aperture-gate verify     # conformance self-test against frozen vectors
+```
+
+## MCP server
+
+A pure-stdlib stdio MCP server, for Claude Desktop / Claude Code / any MCP client:
+
+```bash
+python -m aperture_gate.mcp
+```
+
+Tools: `aperture_read {query, model?}` (ask the upstream model and gate the
+answer) and `aperture_check_text {text}` (words-only read, no model call).
+Configure with `APERTURE_BASE_URL` (default `https://openrouter.ai/api/v1`),
+`APERTURE_UPSTREAM_KEY` or `OPENROUTER_API_KEY`, and `APERTURE_CERT`
+(path or registry id; default `openai/gpt-4o-mini`).
+
+## Conformance
+
+`aperture-gate verify` (or `python -m aperture_gate.verify`) runs six frozen
+vectors computed from the real gpt-4o-mini registry certificate and the
+public demo battery — three fingerprint scores to six decimal places and
+three refusal-reader reads pinning the normalization and guard logic. If any
+vector fails, the install does not implement the certified method.
+
+## Docs
+
+Full method, evidence, and the certificate registry: [honesty.tools/docs](https://honesty.tools/docs)

aperture_gate-0.1.5/README.md

@@ -0,0 +1,118 @@
+# aperture-gate
+
+Deploy a [honesty.tools](https://honesty.tools) calibration certificate.
+
+You calibrated a model at [honesty.tools/calibrate](https://honesty.tools/calibrate)
+(or with the public `aperture_calibrate.py`) and got a certificate JSON —
+`aperture.cert.v1` — containing a logistic probe fitted to *your model's*
+logprob confidence fingerprint over a Wikipedia-validated battery of real and
+fabricated entities. This package is the deployment half: it consumes that
+certificate and gates live answers.
+
+**The method, honestly stated.** Two instruments, words first:
+
+1. **words** — if the answer itself refuses or hedges ("no such company",
+   "I couldn't find any record…"), the verdict is `OFF_MAP`. The model said
+   so; believe it.
+2. **fingerprint** — otherwise, the gate scores
+   `[mean logprob, min logprob, mean top-5 entropy, max top-5 entropy]`
+   through the certificate's probe. Higher score = more likely fabricated.
+   `score >= off_map_thr` → `OFF_MAP`; `>= uncertain_thr` → `UNCERTAIN`;
+   else `ON_MAP`.
+3. With no logprobs and no refusal, the read degrades honestly to
+   `ON_MAP` (instrument `words-only`).
+
+The probe is calibrated **per model** — deploy the certificate for the model
+you actually serve. It separates grounded answers from confabulated answers
+about entities; it is not a general lie detector.
+
+Zero runtime dependencies (pure stdlib), Python ≥ 3.9, MIT.
+
+## Install
+
+```bash
+pip install https://honesty.tools/sdk/aperture_gate-0.1.5-py3-none-any.whl
+
+# optional — verify certificate signatures against the registry key (adds `cryptography`):
+pip install "aperture-gate[verify] @ https://honesty.tools/sdk/aperture_gate-0.1.5-py3-none-any.whl"
+```
+
+**Certificate trust.** Registry certificates are ed25519-signed. With the `[verify]` extra
+installed, `Gate.from_cert(...)` verifies the signature against the registry's pinned public
+key and **rejects a tampered or wrongly-signed certificate** (raises `ValueError`); every
+verdict carries `signature_verified` (`true`/`false`/`null`). Without `[verify]` the gate still
+works — it just notes that the signature was not verified. Expired certificates always warn.
+
+## Quickstart
+
+```python
+from aperture_gate import Gate
+
+# a registry id, a local cert path, or the cert dict itself
+gate = Gate.from_cert("openai/gpt-4o-mini")        # openai/gpt-4o-mini reference cert
+
+# 1) words-only read of any text
+gate.read_text("I couldn't find any record of that company.")
+# {'verdict': 'OFF_MAP', 'band': 'off-map', 'instrument': 'words', ...}
+
+# 2) read a raw chat.completions response (ask for logprobs yourself)
+verdict = gate.read_response(resp_dict_or_openai_object)
+
+# 3) let the gate call the endpoint (sends logprobs=true, top_logprobs=5, temperature=0)
+out = gate.ask("Tell me about the novel Glass over Brackwald.",
+               base_url="https://openrouter.ai/api/v1", api_key="sk-or-...")
+print(out["verdict"], out["score"], out["answer"][:80])
+
+# 4) or wrap an openai-python client (openai>=1.x) transparently
+client = gate.wrap(OpenAI())
+r = client.chat.completions.create(model="gpt-4o-mini",
+                                   messages=[{"role": "user", "content": "..."}])
+print(r.aperture)   # the verdict dict rides along on the response
+
+# 5) gate a STREAM in real time — the verdict lands before the answer finishes.
+#    Chunks pass through to your loop unchanged; the gate scores the calibrated
+#    window prefix as it arrives and (optionally) ABORTS off-map answers mid-stream.
+client = gate.wrap(OpenAI(), on_verdict=lambda v: v["verdict"] == "OFF_MAP")
+stream = client.chat.completions.create(model="gpt-4o-mini", stream=True,
+                                        messages=[{"role": "user", "content": "..."}])
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="")   # stops early if it reads off-map
+print(stream.aperture)   # the verdict, scored on the first `window` tokens
+```
+
+## CLI
+
+```bash
+aperture-gate read --cert openai/gpt-4o-mini --text "No such film exists."
+aperture-gate read --cert ./aperture-cert-my-model.json \
+    --query "Who founded Brindlewick & Thorne?" \
+    --base-url http://localhost:8000/v1 --key sk-...
+aperture-gate calibrate --base-url http://localhost:8000/v1 --model my-llama-70b
+aperture-gate verify     # conformance self-test against frozen vectors
+```
+
+## MCP server
+
+A pure-stdlib stdio MCP server, for Claude Desktop / Claude Code / any MCP client:
+
+```bash
+python -m aperture_gate.mcp
+```
+
+Tools: `aperture_read {query, model?}` (ask the upstream model and gate the
+answer) and `aperture_check_text {text}` (words-only read, no model call).
+Configure with `APERTURE_BASE_URL` (default `https://openrouter.ai/api/v1`),
+`APERTURE_UPSTREAM_KEY` or `OPENROUTER_API_KEY`, and `APERTURE_CERT`
+(path or registry id; default `openai/gpt-4o-mini`).
+
+## Conformance
+
+`aperture-gate verify` (or `python -m aperture_gate.verify`) runs six frozen
+vectors computed from the real gpt-4o-mini registry certificate and the
+public demo battery — three fingerprint scores to six decimal places and
+three refusal-reader reads pinning the normalization and guard logic. If any
+vector fails, the install does not implement the certified method.
+
+## Docs
+
+Full method, evidence, and the certificate registry: [honesty.tools/docs](https://honesty.tools/docs)

aperture_gate-0.1.5/aperture_gate/__init__.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""aperture-gate: deploy honesty.tools calibration certificates.
+
+A team calibrates a model at https://honesty.tools/calibrate and downloads a
+certificate (``aperture.cert.v1``) containing a logistic probe over the
+model's logprob confidence fingerprint. This package consumes that
+certificate and gates live answers: words-first refusal reading, then the
+fingerprint probe, yielding ON_MAP / UNCERTAIN / OFF_MAP verdicts.
+
+Quickstart::
+
+    from aperture_gate import Gate
+    gate = Gate.from_cert("371e95d23ba7")           # registry id, path, or dict
+    gate.read_text("I couldn't find any record of that company.")
+    # -> {'verdict': 'OFF_MAP', 'instrument': 'words', ...}
+
+Zero runtime dependencies (stdlib only), Python >= 3.9.
+"""
+from .gate import Gate
+from .hedge import read_hedge
+
+__version__ = "0.1.5"
+__all__ = ["Gate", "read_hedge", "__version__"]

aperture_gate-0.1.5/aperture_gate/calibrate.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Calibrate the Aperture honesty layer to YOUR model — vendored CLI.
+
+This is the public ``https://honesty.tools/aperture_calibrate.py`` adapted as
+a package module so ``aperture-gate calibrate --base-url ... --model ...``
+works; the behavior is identical. The shared math (the refusal reader and the
+feature/scoring functions) lives in :mod:`aperture_gate.hedge` and
+:mod:`aperture_gate.gate` — byte-for-byte the same code — and is imported
+here rather than duplicated.
+
+What it does (the exact deployed method, in the open):
+  1. pulls the current public battery from honesty.tools (84 real / 84
+     fabricated entities, every one validated against Wikipedia; the battery
+     hash binds the certificate)
+  2. asks your model all 168 questions (max_tokens=24, temperature=0,
+     logprobs+top-5 if exposed)
+  3. the refusal reader catches fakes your model declines IN WORDS
+  4. a logistic probe on [mean logprob, min logprob, mean top-5 entropy,
+     max top-5 entropy] separates grounded answers from confabulations —
+     5-fold CV AUROC, P95-anchored thresholds
+  5. a shuffled-label permutation null tries to kill the signal; the verdict
+     lands honestly: CALIBRATED / WORDS-DOMINANT / REFUSAL-READER (no
+     logprobs) / PROBE-WEAK
+  6. writes aperture-cert-<model>.json — the certificate plus the deployable
+     probe
+
+Nothing leaves your machine except calls to YOUR endpoint — unless you pass
+``--register``, which uploads only the finished certificate (never the
+prompts, answers, or key) to the public registry.
+"""
+from __future__ import annotations
+
+import argparse
+import concurrent.futures as cf
+import json
+import math
+import random
+import re
+import sys
+import urllib.error
+import urllib.request
+from typing import List, Optional
+
+from .gate import feats_from, score_one, sigmoid
+from .hedge import refused
+
+SITE = "https://honesty.tools"
+SEED = 20260610
+MIN_CONFAB, AUROC_PASS, NPERM = 8, 0.70, 120
+FIT = {"alpha": 0.008, "iters": 1000, "lr": 0.5}     # parity-locked vs the deployed sklearn re-fit
+
+
+# ── the fit (pure-python port, parity-locked vs sklearn: AUROC 0.968 == 0.968 on the reference) ──
+def standardize_fit(X):
+    n, d = len(X), len(X[0])
+    mean = [sum(r[j] for r in X) / n for j in range(d)]
+    scale = []
+    for j in range(d):
+        v = sum((r[j] - mean[j]) ** 2 for r in X) / n
+        scale.append(math.sqrt(v) if v > 1e-24 else 1.0)
+    return mean, scale
+
+
+def fit_logreg(Z, y):
+    n, d = len(Z), len(Z[0])
+    w, b = [0.0] * d, 0.0
+    for _ in range(FIT["iters"]):
+        gw, gb = [0.0] * d, 0.0
+        for i in range(n):
+            err = sigmoid(b + sum(w[j] * Z[i][j] for j in range(d))) - y[i]
+            gb += err
+            for j in range(d):
+                gw[j] += err * Z[i][j]
+        b -= FIT["lr"] * (gb / n)
+        for j in range(d):
+            w[j] -= FIT["lr"] * (gw[j] / n + FIT["alpha"] * w[j])
+    return w, b
+
+
+def auroc(scores, y):
+    pairs = sorted(range(len(scores)), key=lambda i: scores[i])
+    rank, i = [0.0] * len(scores), 0
+    while i < len(pairs):
+        j = i
+        while j + 1 < len(pairs) and scores[pairs[j + 1]] == scores[pairs[i]]:
+            j += 1
+        for k in range(i, j + 1):
+            rank[pairs[k]] = (i + j) / 2 + 1
+        i = j + 1
+    pos = [i for i in range(len(y)) if y[i] == 1]
+    neg = [i for i in range(len(y)) if y[i] == 0]
+    if not pos or not neg:
+        return float("nan")
+    return (sum(rank[i] for i in pos) - len(pos) * (len(pos) + 1) / 2) / (len(pos) * len(neg))
+
+
+def percentile(arr, p):
+    a = sorted(arr)
+    if len(a) == 1:
+        return a[0]
+    idx = (p / 100) * (len(a) - 1)
+    lo, hi = int(math.floor(idx)), int(math.ceil(idx))
+    return a[lo] + (a[hi] - a[lo]) * (idx - lo)
+
+
+def cv_scores(X, y, k, rng):
+    pos = [i for i in range(len(y)) if y[i] == 1]
+    neg = [i for i in range(len(y)) if y[i] == 0]
+    rng.shuffle(pos)
+    rng.shuffle(neg)
+    folds = [[] for _ in range(k)]
+    for m, ix in enumerate(pos):
+        folds[m % k].append(ix)
+    for m, ix in enumerate(neg):
+        folds[m % k].append(ix)
+    oof = [0.5] * len(y)
+    for f in range(k):
+        test = set(folds[f])
+        trX = [X[i] for i in range(len(y)) if i not in test]
+        trY = [y[i] for i in range(len(y)) if i not in test]
+        if not trX:
+            continue
+        mean, scale = standardize_fit(trX)
+        Z = [[(r[j] - mean[j]) / scale[j] for j in range(4)] for r in trX]
+        w, b = fit_logreg(Z, trY)
+        probe = {"mean": mean, "scale": scale, "coef": w, "intercept": b}
+        for i in test:
+            oof[i] = score_one(X[i], probe)
+    return oof
+
+
+# ── plumbing ─────────────────────────────────────────────────────────────────────────────────────
+def http_json(url, payload=None, headers=None, timeout=60):
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json", **(headers or {})})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read().decode())
+
+
+def get_battery(path=None):
+    if path:
+        raw = open(path, encoding="utf-8").read()
+    else:
+        with urllib.request.urlopen(SITE + "/battery.js", timeout=30) as r:
+            raw = r.read().decode()
+    m = re.search(r"window\.APERTURE_BATTERY\s*=\s*(\{.*\});", raw, re.S)
+    return json.loads(m.group(1))
+
+
+def call_model(base, key, model, q):
+    url = base.rstrip("/")
+    if not url.endswith("/chat/completions"):
+        url += "/chat/completions"
+    payload = {"model": model, "messages": [{"role": "user", "content": q}],
+               "max_tokens": 24, "temperature": 0, "logprobs": True, "top_logprobs": 5}
+    headers = {"Authorization": "Bearer " + key} if key else {}
+    last = "?"
+    for attempt in range(3):
+        try:
+            d = http_json(url, payload, headers)
+            ch = d["choices"][0]
+            text = (ch.get("message") or {}).get("content") or ""
+            cont = (ch.get("logprobs") or {}).get("content")
+            return {"text": text, "feats": feats_from(cont)}
+        except urllib.error.HTTPError as e:
+            if e.code == 400:          # logprobs unsupported on some servers -> words-only retry
+                try:
+                    d = http_json(url, {"model": model, "messages": payload["messages"],
+                                        "max_tokens": 40, "temperature": 0}, headers)
+                    return {"text": d["choices"][0]["message"]["content"] or "", "feats": None}
+                except Exception as e2:  # noqa: BLE001
+                    last = str(e2)[:80]
+            else:
+                last = f"HTTP {e.code}"
+        except Exception as e:  # noqa: BLE001
+            last = str(e)[:80]
+    return {"error": last}
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    ap = argparse.ArgumentParser(prog="aperture-gate calibrate",
+                                 description="Calibrate the Aperture honesty layer to your model.")
+    ap.add_argument("--base-url", required=True, help="your OpenAI-compatible /v1 base URL")
+    ap.add_argument("--key", default="", help="API key if your endpoint needs one (sent ONLY to your endpoint)")
+    ap.add_argument("--model", required=True, help="the model id your server hosts")
+    ap.add_argument("--workers", type=int, default=4)
+    ap.add_argument("--battery", default=None, help="local battery.js (defaults to fetching the current one)")
+    ap.add_argument("--out", default=None, help="output cert path (default aperture-cert-<model>.json)")
+    ap.add_argument("--register", action="store_true",
+                    help="publish the finished certificate to the honesty.tools registry (self-attested)")
+    a = ap.parse_args(argv)
+
+    bat = get_battery(a.battery)
+    items = bat["items"]
+    print(f"battery {bat['hash']} — {len(items)} items ({bat['n_real']} real / {bat['n_fake']} fabricated)")
+    print(f"model   {a.model} @ {a.base_url}")
+
+    cap = call_model(a.base_url, a.key, a.model, "What is the capital of France?")
+    if "error" in cap:
+        sys.exit(f"cannot reach the endpoint: {cap['error']}")
+    print(f"logprobs exposed: {'yes' if cap.get('feats') else 'NO — words-only calibration'}\n")
+
+    rows, done = [], 0
+    with cf.ThreadPoolExecutor(max_workers=a.workers) as ex:
+        for it, r in zip(items, ex.map(lambda it: call_model(a.base_url, a.key, a.model, it["q"]), items)):
+            done += 1
+            if "error" in r:
+                rows.append({**it, "text": "", "feats": None, "refused": False, "error": r["error"]})
+            else:
+                rows.append({**it, "text": r["text"], "feats": r["feats"], "refused": refused(r["text"])})
+            if done % 24 == 0:
+                print(f"  {done}/{len(items)}")
+    errs = sum(1 for r in rows if r.get("error"))
+    if errs > len(items) * 0.2:
+        sys.exit(f"too many collection errors ({errs}/{len(items)}) — check the endpoint and retry")
+
+    ok_rows = [r for r in rows if not r.get("error")]
+    reals_all = [r for r in ok_rows if r["label"] == 0]
+    fakes_all = [r for r in ok_rows if r["label"] == 1]
+    refused_fakes = [r for r in fakes_all if r["refused"]]
+    false_ref = [r for r in reals_all if r["refused"]]
+    coverage = len(refused_fakes) / max(1, len(fakes_all))
+    cert = {"schema": "aperture.cert.v1", "grade": "self-attested", "model": a.model,
+            "method": "logprob confidence-fingerprint probe (reals vs confabulated fakes) + words refusal reader",
+            "battery": {"hash": bat["hash"], "version": bat["version"],
+                        "n_real": len(reals_all), "n_fake": len(fakes_all)},
+            "refusal_reader": {"fakes_refused": len(refused_fakes), "coverage": round(coverage, 3),
+                               "false_refusals_on_reals": len(false_ref)},
+            "fingerprint_probe": None, "combined": None, "samples": []}
+
+    reals = [r for r in reals_all if r["feats"]]
+    confab = [r for r in fakes_all if r["feats"] and not r["refused"]]
+    if not [r for r in ok_rows if r["feats"]]:
+        cert["verdict"] = "REFUSAL-READER"
+        cert["combined"] = {"detect_rate": round(coverage, 3),
+                            "fp_rate": round(len(false_ref) / max(1, len(reals_all)), 3)}
+    elif len(confab) < MIN_CONFAB:
+        cert["verdict"] = "WORDS-DOMINANT"
+        cert["combined"] = {"detect_rate": round(coverage, 3),
+                            "fp_rate": round(len(false_ref) / max(1, len(reals_all)), 3)}
+    else:
+        X = [r["feats"] for r in reals + confab]
+        y = [0] * len(reals) + [1] * len(confab)
+        oof = cv_scores(X, y, 5, random.Random(SEED))
+        au = auroc(oof, y)
+        p95 = percentile([oof[i] for i in range(len(y)) if y[i] == 0], 95)
+        un, off = round(p95 + 0.10, 3), round(p95 + 0.22, 3)
+        rng = random.Random(SEED)
+        boots = []
+        for _ in range(400):
+            ix = [rng.randrange(len(y)) for _ in range(len(y))]
+            aa = auroc([oof[i] for i in ix], [y[i] for i in ix])
+            if aa == aa:
+                boots.append(aa)
+        ci = [round(percentile(boots, 2.5), 3), round(percentile(boots, 97.5), 3)]
+        null = []
+        print(f"\nnull test ({NPERM} label permutations)…")
+        for pi in range(NPERM):
+            ys = y[:]
+            rng.shuffle(ys)
+            o2 = cv_scores(X, ys, 5, random.Random(SEED + pi))
+            aa = auroc(o2, ys)
+            if aa == aa:
+                null.append(aa)
+        nmean = sum(null) / len(null)
+        nsd = math.sqrt(sum((v - nmean) ** 2 for v in null) / len(null)) or 1e-9
+        z = (au - nmean) / nsd
+        pval = (sum(1 for v in null if v >= au) + 1) / (len(null) + 1)
+        mean, scale = standardize_fit(X)
+        Z = [[(r[j] - mean[j]) / scale[j] for j in range(4)] for r in X]
+        w, b = fit_logreg(Z, y)
+        probe = {"mean": [round(v, 6) for v in mean], "scale": [round(v, 6) for v in scale],
+                 "coef": [round(v, 6) for v in w], "intercept": round(b, 6),
+                 "uncertain_thr": un, "off_map_thr": off, "cv_auroc": round(au, 4)}
+        caught = len(refused_fakes) + sum(1 for r in confab if score_one(r["feats"], probe) >= off)
+        fp = sum(1 for r in reals if r["refused"] or score_one(r["feats"], probe) >= off)
+        cert["verdict"] = "CALIBRATED" if (au >= AUROC_PASS and pval < 0.05) else "PROBE-WEAK"
+        cert["fingerprint_probe"] = {"cv_auroc": round(au, 4), "ci95": ci, "n_confabulations": len(confab),
+                                     "null": {"mean": round(nmean, 3), "z": round(z, 2), "p": round(pval, 5)},
+                                     "probe": probe}
+        cert["combined"] = {"detect_rate": round(caught / max(1, len(fakes_all)), 3),
+                            "fp_rate": round(fp / max(1, len(reals)), 3)}
+        cc = [r for r in confab if score_one(r["feats"], probe) >= off]
+        cert["samples"] = ([{"q": r["q"], "answer": (r["text"] or "")[:120], "caught_by": "words", "score": None}
+                            for r in refused_fakes[:1]] +
+                           [{"q": r["q"], "answer": (r["text"] or "")[:120], "caught_by": "fingerprint",
+                             "score": round(score_one(r["feats"], probe), 3)} for r in cc[:2]])
+
+    out = a.out or ("aperture-cert-" + re.sub(r"[^A-Za-z0-9]+", "-", a.model) + ".json")
+    json.dump(cert, open(out, "w", encoding="utf-8"), indent=2, ensure_ascii=False)
+    print("\n" + "=" * 64)
+    print(f"  VERDICT  {cert['verdict']}")
+    print(f"  refusal reader   {len(refused_fakes)}/{len(fakes_all)} fakes caught in words "
+          f"({round(100 * coverage)}%), {len(false_ref)} false on reals")
+    if cert["fingerprint_probe"]:
+        fpd = cert["fingerprint_probe"]
+        print(f"  fingerprint      AUROC {fpd['cv_auroc']}  CI {fpd['ci95']}  "
+              f"null z={fpd['null']['z']} p={fpd['null']['p']}")
+    if cert["combined"]:
+        print(f"  combined         {round(100 * cert['combined']['detect_rate'])}% of fabrications caught "
+              f"at {round(100 * cert['combined']['fp_rate'])}% real-FP")
+    print(f"  certificate      {out}")
+    print("=" * 64)
+    if a.register:
+        try:
+            res = http_json(SITE + "/api/cert/register", cert)
+            if res.get("id"):
+                print(f"\nregistered: {SITE}/cert/{res['id']}")
+            else:
+                print(f"\nregistry said: {res.get('error', res)}")
+        except Exception as e:  # noqa: BLE001
+            print(f"\ncould not register: {e}")
+
+
+if __name__ == "__main__":
+    main()