pytest-gpu-proof 0.1.0__tar.gz → 0.3.0__tar.gz

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to pytest-gpu-proof are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); versions follow
 [SemVer](https://semver.org/) (pre-1.0: minor bumps may break).
 
+## [0.3.0] — 2026-08-08
+
+### Added
+- Schema `"2"` sharded receipts: `--gpu-proof-shard NAME` +
+  `--gpu-proof-shard-fingerprint-paths` emit a per-shard narrow fingerprint;
+  `gpu-proof merge` unions schema-2 shards (unique names enforced).
+- Verifiable carry-forward: `gpu-proof merge --carry-from OLD` grafts shards
+  absent from the fresh inputs iff the old commit is an ancestor AND the
+  shard's narrow fingerprint recomputes clean; grafted shards are marked
+  `carried` and the verifier rejects them unless the policy sets
+  `allow_carried: true` (bounded by `carried_max_age_days`, default 30).
+- Verifier: schema-2 checks (per-shard fingerprint recompute, membership
+  partition of `tests[]`, carried-shard policy gate). Schema-1 receipts are
+  unchanged and a schema-1 receipt carrying a `shards` block is rejected.
+
+## [0.2.0] — 2026-08-07
+
+### Added
+- `gpu-proof merge`: union N shard receipts from one commit into a single
+  re-signed receipt (per-module crash isolation / machine sharding). Refuses
+  shards that disagree on schema, commit SHA, fingerprint, mode, or
+  environment; duplicate node IDs across shards are a hard error. Records
+  per-shard provenance under `session.shards` (additive — the verifier is
+  unchanged). `repo.dirty` is OR-ed; `gpu_info` survives CPU-only shards.
+  Docs: `docs/sharding.md`.
+
+### Fixed
+- Explicit CLI values equal to their built-in defaults are no longer silently
+  ignored in favor of `[tool.gpu_proof]` (value-taking options now register a
+  `None` sentinel; `--gpu-proof-fail-on-skip` ORs with the toml value since a
+  store_true flag can only turn it on).
+
 ## [0.1.0] — 2026-07-07
 
 First public release.

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-gpu-proof
-Version: 0.1.0
+Version: 0.3.0
 Summary: pytest plugin for GPU equivalence testing with signed receipts verified via GitHub SSH keys
 Project-URL: Homepage, https://github.com/A2R-Lab/pytest-gpu-proof
 Project-URL: Documentation, https://a2r-lab.github.io/pytest-gpu-proof/

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/docs/security_model.md

@@ -73,3 +73,15 @@ that a specific GPU executed a specific workload in a verified environment.
 This is out of scope for v1 but the receipt format is designed to be extendable —
 a `hardware_attestation` block could be added to the `environment` section in a
 future version without breaking existing receipts.
+
+## Carried shards (schema 2)
+
+A carried shard is an attestation about a **prior** run: the tests passed at an
+ancestor commit, and the shard's declared input paths are byte-identical at the
+verified commit (the verifier recomputes this; it is not taken on faith). What
+is NOT re-established: that the prior run's environment still exists, or that
+paths *outside* the shard's declared fingerprint didn't change its behavior —
+declaring too-narrow shard paths weakens the claim, exactly like declaring
+too-narrow global fingerprint paths. That is why `allow_carried` defaults to
+**false**: accepting carried shards is an explicit policy decision, bounded by
+`carried_max_age_days`.

pytest_gpu_proof-0.3.0/docs/sharding.md

@@ -0,0 +1,109 @@
+# Sharded runs & merging receipts
+
+Large suites often can't (or shouldn't) run as one pytest session: per-module
+subprocesses give crash isolation (one CUDA abort no longer erases the whole
+run's results), and big projects split GPU tests across invocations or
+machines. Each invocation emits its own receipt; CI wants **one** artifact.
+
+## Emit one receipt per shard
+
+Point each invocation at its own output path:
+
+```bash
+pytest tests/gpu/test_a.py --gpu-proof-enable --gpu-proof-out=receipts/a.json
+pytest tests/gpu/test_b.py --gpu-proof-enable --gpu-proof-out=receipts/b.json
+```
+
+Every shard receipt is a complete, individually verifiable receipt.
+
+## Merge
+
+```bash
+gpu-proof merge --out gpu-proof.json receipts/a.json receipts/b.json
+```
+
+`merge` unions the shards' `tests`, spans `session.started_at`/`ended_at`
+across them, records per-shard provenance under `session.shards`
+(`source`, `node_count`, timestamps, and each shard's recorded signer), and
+**re-signs the merged payload with your local SSH key**. The result flows
+through `gpu-proof verify` completely unchanged — same schema, same seven
+checks.
+
+Options:
+
+- `--github-user USERNAME` — recorded signer identity for the merged receipt
+  (default: the first shard's `repo.github_username`).
+- `--key PATH` — SSH private key (default: `git config user.signingKey`, then
+  `~/.ssh/id_ed25519` / `id_ecdsa` / `id_rsa`).
+- `--unsigned` — write `signature: null`; verifies only with
+  `--allow-unsigned`, loudly.
+
+## What merge refuses
+
+A merged receipt must mean exactly what a single-session receipt means, so
+`merge` hard-refuses shards that disagree on anything a receipt pins:
+
+- `schema_version`, `repo.commit_sha`, `fingerprint` (digest + paths),
+  `mode`, or the `environment` the tests ran under (python/pytest/plugin
+  versions, platform);
+- **duplicate node IDs across shards** — two shards attesting the same test is
+  a sharding bug in the runner, never something to dedupe silently.
+
+`repo.dirty` is OR-ed: one dirty shard makes the merged attestation dirty, and
+your verify-time dirty policy applies honestly. `gpu_info` is taken from the
+first shard that has one, so a CPU-only shard doesn't erase the GPU record.
+
+## Trust model
+
+Consistent with the [security model](security_model.md): the merged receipt is
+an **attestation by the merger**. Shard signatures are recorded as provenance
+but not re-verified at merge time (merging is offline); the merged signature
+is what CI verifies. If shards were signed by someone else, verification of
+the merged receipt attests that *you* vouch for the union.
+
+## Per-shard fingerprints & carry-forward (schema 2)
+
+Declare each invocation as a **shard** and the receipt becomes schema `"2"`,
+carrying that shard's own *narrow* fingerprint over the paths you declare:
+
+```bash
+pytest tests/gpu/test_a.py --gpu-proof-enable \
+    --gpu-proof-shard=test_a \
+    --gpu-proof-shard-fingerprint-paths=tests/gpu/test_a.py,src/kernels_a \
+    --gpu-proof-out=receipts/a.json
+```
+
+`gpu-proof merge` unions schema-2 shards exactly like schema-1 receipts (shard
+names must be unique). The new capability is **carry-forward**:
+
+```bash
+gpu-proof merge --out gpu-proof.json --carry-from last-green/gpu-proof.json \
+    --repo . receipts/*.json
+```
+
+Shards present in the old receipt but absent from the fresh inputs are grafted
+in, **marked `carried`**, iff:
+
+1. the old receipt's commit is an **ancestor** of the fresh one (same history), and
+2. the shard's narrow fingerprint **recomputes identical** against the current
+   tree — the inputs that shard proved are unchanged.
+
+A shard whose inputs changed refuses to carry (re-run it). Freshly re-run
+shards always win over old ones.
+
+### Verification of schema-2 receipts
+
+`gpu-proof verify` additionally checks, for every shard: the narrow
+fingerprint recomputes clean at the verifying tree, and shard membership
+exactly partitions `tests[]`. **Carried shards are rejected by default** — the
+policy must opt in:
+
+```yaml
+allow_carried: true          # default false — the trust boundary
+carried_max_age_days: 30     # carried shard's ORIGINAL run must be fresher
+```
+
+A receipt with carried shards verified under `allow_carried: true` means:
+*every test either ran at this commit, or ran at an ancestor commit on inputs
+that are provably byte-identical today, within the age window* — and the
+merger signed for that claim.

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/mkdocs.yml

@@ -33,6 +33,7 @@ nav:
   - Quickstart: quickstart.md
   - Local Mode: local_mode.md
   - CI-GPU Mode: ci_gpu_mode.md
+  - Sharding & Merge: sharding.md
   - Architecture: architecture.md
   - Security Model: security_model.md
   - Landscape: landscape.md

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-gpu-proof"
-version = "0.1.0"
+version = "0.3.0"
 description = "pytest plugin for GPU equivalence testing with signed receipts verified via GitHub SSH keys"
 readme = "README.md"
 requires-python = ">=3.11"

pytest_gpu_proof-0.3.0/src/pytest_gpu_proof/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/src/pytest_gpu_proof/cli.py

@@ -72,8 +72,64 @@ def main():
         "require_gpu = true in [tool.gpu_proof].",
     )
 
+    # merge
+    mp = subparsers.add_parser(
+        "merge",
+        help="Merge shard receipts from ONE commit into a single re-signed receipt",
+        description=(
+            "Union the tests of N shard receipts (same commit SHA, fingerprint, "
+            "and environment) into one receipt, re-signed with your local SSH "
+            "key, that flows through `gpu-proof verify` unchanged. Shards that "
+            "disagree on anything a receipt pins are refused; duplicate node "
+            "IDs across shards are always an error."
+        ),
+    )
+    mp.add_argument("shards", nargs="+", metavar="RECEIPT",
+                    help="Shard receipt paths (two or more, typically)")
+    mp.add_argument("--out", required=True, metavar="PATH",
+                    help="Path for the merged receipt")
+    mp.add_argument("--github-user", default=None, metavar="USERNAME",
+                    help="Recorded signer identity for the merged receipt "
+                    "(default: the first shard's repo.github_username)")
+    mp.add_argument("--key", default=None, metavar="PATH",
+                    help="SSH private key to sign with (default: git "
+                    "user.signingKey, then ~/.ssh/id_ed25519 etc.)")
+    mp.add_argument("--unsigned", action="store_true", default=False,
+                    help="Write signature: null — the merged receipt then "
+                    "verifies only with --allow-unsigned, loudly")
+    mp.add_argument("--carry-from", default=None, metavar="RECEIPT",
+                    help="Graft still-valid shards from an older schema-2 "
+                    "receipt: each absent-from-fresh shard is carried iff the "
+                    "old commit is an ancestor of the new one AND its narrow "
+                    "fingerprint recomputes clean at the current tree. Carried "
+                    "shards are marked and gated at verify time by policy "
+                    "allow_carried (default: rejected).")
+    mp.add_argument("--repo", default=".", metavar="PATH",
+                    help="Repo root for carry-from fingerprint/ancestry checks")
+
     args = parser.parse_args()
 
+    if args.command == "merge":
+        from .merge import MergeError, merge_receipts
+
+        try:
+            receipt = merge_receipts(
+                args.shards, args.out,
+                github_user=args.github_user,
+                key_path=args.key,
+                unsigned=args.unsigned,
+                carry_from=args.carry_from,
+                repo_root=args.repo,
+            )
+        except MergeError as e:
+            print(f"gpu-proof merge: {e}", file=sys.stderr)
+            sys.exit(1)
+        n = len(receipt.get("tests", []))
+        shards = len(receipt.get("session", {}).get("shards", []))
+        print(f"merged {shards} shard(s), {n} tests -> {args.out}"
+              + (" (UNSIGNED)" if args.unsigned else ""))
+        sys.exit(0)
+
     if args.command == "verify":
         from .verify import verify_receipt
 

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/src/pytest_gpu_proof/config.py

@@ -18,6 +18,10 @@ class GpuProofConfig:
     github_username: Optional[str] = None
     max_age_days: int = 30
     require_gpu: bool = False
+    # Sharded emission (schema "2"): a declared shard name + its narrow
+    # fingerprint paths (None -> the global fingerprint_paths).
+    shard_name: Optional[str] = None
+    shard_fingerprint_paths: Optional[List[str]] = None
 
 
 def load_toml_defaults(root: Union[str, Path]) -> Dict[str, Any]:
@@ -47,10 +51,13 @@ def load_config(pytest_config) -> GpuProofConfig:
             return default
 
     def resolve(opt_name, toml_key, default):
-        """Precedence: CLI flag (when it differs from its built-in default),
-        then [tool.gpu_proof] in pyproject.toml, then the built-in default."""
-        cli = opt(opt_name, default)
-        if cli != default:
+        """Precedence: CLI flag (when explicitly passed), then [tool.gpu_proof]
+        in pyproject.toml, then the built-in default. Value-taking options
+        register with ``default=None`` so an explicit CLI value that happens to
+        equal the built-in default still wins — previously it was silently
+        ignored in favor of the toml value."""
+        cli = opt(opt_name, None)
+        if cli is not None:
             return cli
         toml_val = toml_cfg.get(toml_key)
         if toml_val is not None:
@@ -63,6 +70,15 @@ def load_config(pytest_config) -> GpuProofConfig:
     else:
         paths = [str(p) for p in raw_paths]
 
+    raw_shard_paths = resolve("--gpu-proof-shard-fingerprint-paths",
+                              "shard_fingerprint_paths", None)
+    if isinstance(raw_shard_paths, str):
+        shard_paths = [p.strip() for p in raw_shard_paths.split(",") if p.strip()]
+    elif raw_shard_paths is not None:
+        shard_paths = [str(p) for p in raw_shard_paths]
+    else:
+        shard_paths = None
+
     max_age = toml_cfg.get("max_age_days")
     max_age_days = int(max_age) if max_age is not None else 30
 
@@ -74,9 +90,14 @@ def load_config(pytest_config) -> GpuProofConfig:
         signing_backend=resolve("--gpu-proof-signing-backend", "signing_backend", "ed25519"),
         policy_path=resolve("--gpu-proof-policy", "policy_path", None),
         required_marker=resolve("--gpu-proof-required-marker", "required_marker", "gpu_proof"),
-        fail_on_skip=bool(resolve("--gpu-proof-fail-on-skip", "fail_on_skip", False)),
+        # store_true flag: False just means "not passed", so OR with the toml
+        # value rather than sentinel-resolving (a CLI flag can only turn it ON).
+        fail_on_skip=bool(opt("--gpu-proof-fail-on-skip", False)
+                          or toml_cfg.get("fail_on_skip", False)),
         fingerprint_paths=paths,
         github_username=resolve("--gpu-proof-github-user", "github_username", None),
         max_age_days=max_age_days,
         require_gpu=bool(toml_cfg.get("require_gpu", False)),
+        shard_name=resolve("--gpu-proof-shard", "shard_name", None),
+        shard_fingerprint_paths=shard_paths,
     )

pytest_gpu_proof-0.3.0/src/pytest_gpu_proof/merge.py

@@ -0,0 +1,271 @@
+"""
+Merge shard receipts from one commit into a single re-signed receipt.
+
+Motivation: large suites run their GPU tests as several pytest invocations
+(per-module crash isolation, machine sharding). Each invocation emits its own
+receipt; CI wants ONE artifact to verify. ``gpu-proof merge`` unions the shard
+receipts' ``tests`` and re-signs the result with the merger's local SSH key —
+so the merged receipt flows through the existing ``gpu-proof verify`` path
+completely unchanged (schema_version stays "1"; the only addition is the
+OPTIONAL ``session.shards`` provenance list, which the verifier ignores).
+
+Trust model (consistent with docs/security_model.md): the merged receipt is an
+attestation by the MERGER — shard signatures are recorded as provenance but are
+NOT verified here (merge is offline by design); the merged receipt's signature
+is what CI verifies. Merging refuses to combine shards that disagree on
+anything a receipt pins: schema, commit SHA, fingerprint, mode, or the
+environment the tests ran under. Duplicate node IDs are always an error — two
+shards attesting the same test is a sharding bug, not a merge input.
+"""
+
+import json
+import os
+from typing import List, Optional
+
+from .receipt import finalize_receipt, write_receipt
+
+
+class MergeError(ValueError):
+    """A refusal to merge, with an actionable message."""
+
+
+def load_receipt(path: str) -> dict:
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        raise MergeError(f"{path}: not a readable receipt ({e})") from e
+    if not isinstance(data, dict) or "tests" not in data:
+        raise MergeError(f"{path}: not a gpu-proof receipt (no 'tests' key)")
+    return data
+
+
+def _require_identical(receipts: List[dict], sources: List[str], getter, what: str):
+    values = [getter(r) for r in receipts]
+    first = values[0]
+    for src, val in zip(sources[1:], values[1:]):
+        if val != first:
+            raise MergeError(
+                f"shards disagree on {what}: {sources[0]}={first!r} vs {src}={val!r} — "
+                f"a merged receipt must come from ONE commit/config; re-run the "
+                f"divergent shard."
+            )
+    return first
+
+
+def merge_payloads(receipts: List[dict], sources: List[str]) -> dict:
+    """Union shard payloads into one UNSIGNED payload. Raises MergeError on any
+    disagreement over what a receipt pins."""
+    if len(receipts) < 1:
+        raise MergeError("nothing to merge")
+
+    _require_identical(receipts, sources, lambda r: r.get("schema_version"), "schema_version")
+    schema = receipts[0].get("schema_version")
+    if schema not in ("1", "2"):
+        raise MergeError(
+            f"unsupported schema_version {schema!r} (this version merges "
+            f"schema '1' and schema '2' receipts, not mixed)"
+        )
+    _require_identical(receipts, sources, lambda r: r.get("repo", {}).get("commit_sha"),
+                       "repo.commit_sha")
+    _require_identical(receipts, sources, lambda r: r.get("fingerprint"), "fingerprint")
+    _require_identical(receipts, sources, lambda r: r.get("mode"), "mode")
+    for key in ("python_version", "platform", "pytest_version", "plugin_version"):
+        _require_identical(receipts, sources,
+                           lambda r, k=key: r.get("environment", {}).get(k),
+                           f"environment.{key}")
+
+    # tests: union; duplicate node ids are a sharding bug, never silently deduped.
+    tests: List[dict] = []
+    seen: dict = {}
+    for src, r in zip(sources, receipts):
+        for t in r.get("tests", []):
+            nid = t.get("node_id")
+            if nid in seen:
+                raise MergeError(
+                    f"duplicate node_id {nid!r} in {src} (already attested by "
+                    f"{seen[nid]}) — shards must partition the suite."
+                )
+            seen[nid] = src
+            tests.append(t)
+    if not tests:
+        raise MergeError("merged receipt would contain zero tests")
+
+    # schema 2: union the shards lists (shard names must be unique across
+    # inputs; a shard's node_ids stay attached to it, so the merged receipt
+    # still partitions tests[] by shard for the verifier's membership check).
+    merged_shards = None
+    if schema == "2":
+        merged_shards = []
+        shard_names: dict = {}
+        for src, r in zip(sources, receipts):
+            for shard in r.get("shards") or []:
+                nm = shard.get("name")
+                if nm in shard_names:
+                    raise MergeError(
+                        f"duplicate shard name {nm!r} in {src} (already from "
+                        f"{shard_names[nm]}) — shard names must be unique."
+                    )
+                shard_names[nm] = src
+                merged_shards.append(shard)
+
+    sessions = [r.get("session", {}) for r in receipts]
+    started = min(s.get("started_at") for s in sessions)
+    ended = max(s.get("ended_at") for s in sessions)
+
+    merged = dict(receipts[0])
+    merged.pop("signature", None)
+    # repo: the commit SHA is asserted identical above; branch/remote come from
+    # the first shard. `dirty` is OR-ed — one dirty shard makes the merged
+    # attestation dirty, and the verifier's dirty policy then applies honestly.
+    merged["repo"] = dict(receipts[0].get("repo", {}))
+    merged["repo"]["dirty"] = any(r.get("repo", {}).get("dirty") for r in receipts)
+    # environment: fields asserted identical above; gpu_info from the first
+    # shard that has one (a CPU-only shard shouldn't erase the GPU record).
+    merged["environment"] = dict(receipts[0].get("environment", {}))
+    merged["environment"]["gpu_info"] = next(
+        (r["environment"]["gpu_info"] for r in receipts
+         if r.get("environment", {}).get("gpu_info")), None)
+    merged["tests"] = tests
+    merged["session"] = {
+        "started_at": started,
+        "ended_at": ended,
+        "node_ids": [t["node_id"] for t in tests],
+        # Provenance (additive; the verifier ignores unknown session keys).
+        # Shard signers are recorded, not verified — the merged signature is
+        # the attestation CI checks.
+        "shards": [
+            {
+                "source": os.path.basename(src),
+                "node_count": len(r.get("tests", [])),
+                "started_at": s.get("started_at"),
+                "ended_at": s.get("ended_at"),
+                "signer": (r.get("signature") or {}).get("signer"),
+            }
+            for src, r, s in zip(sources, receipts, sessions)
+        ],
+    }
+    if merged_shards is not None:
+        merged["shards"] = merged_shards
+    return merged
+
+
+def _git_is_ancestor(repo_root: str, ancestor: str, descendant: str) -> bool:
+    import subprocess
+    try:
+        subprocess.run(
+            ["git", "-C", repo_root, "merge-base", "--is-ancestor", ancestor, descendant],
+            capture_output=True, check=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def carry_forward(payload: dict, old_receipt: dict, old_source: str,
+                  repo_root: str = ".") -> dict:
+    """Graft shards from ``old_receipt`` that are ABSENT from the fresh merged
+    ``payload``, marking each ``carried``. Soundness conditions per shard:
+
+      1. the old receipt is schema '2' and its commit is an ANCESTOR of the
+         fresh payload's commit (same history, older point);
+      2. the shard's narrow fingerprint recomputes IDENTICAL against the
+         current tree — the inputs that shard proved are unchanged at HEAD.
+
+    Shard signatures are provenance (merge is offline); the re-signed merged
+    receipt is the attestation, and the VERIFIER re-checks every carried
+    shard's fingerprint and gates them on policy ``allow_carried``."""
+    from .fingerprint import compute_fingerprint
+
+    if old_receipt.get("schema_version") != "2":
+        raise MergeError(
+            f"--carry-from {old_source}: not a schema '2' (sharded) receipt")
+    old_sha = old_receipt.get("repo", {}).get("commit_sha")
+    new_sha = payload.get("repo", {}).get("commit_sha")
+    if old_sha and new_sha and old_sha != new_sha and not _git_is_ancestor(
+            repo_root, old_sha, new_sha):
+        raise MergeError(
+            f"--carry-from {old_source}: its commit {old_sha[:12]} is not an "
+            f"ancestor of {new_sha[:12]} — different history, cannot carry.")
+
+    fresh_names = {s.get("name") for s in payload.get("shards") or []}
+    fresh_ids = {t.get("node_id") for t in payload.get("tests", [])}
+    old_tests = {t.get("node_id"): t for t in old_receipt.get("tests", [])}
+    carried_count = 0
+    for shard in old_receipt.get("shards") or []:
+        nm = shard.get("name")
+        if nm in fresh_names:
+            continue  # freshly re-run — the new result wins
+        sfp = shard.get("fingerprint", {})
+        snow = compute_fingerprint(sfp.get("included_paths", []), root=repo_root)
+        if snow["digest"] != sfp.get("digest"):
+            raise MergeError(
+                f"--carry-from {old_source}: shard {nm!r} fingerprint no longer "
+                f"matches the current tree — its inputs changed; re-run it "
+                f"instead of carrying.")
+        ids = shard.get("node_ids", [])
+        dup = fresh_ids.intersection(ids)
+        if dup:
+            raise MergeError(
+                f"--carry-from {old_source}: shard {nm!r} would re-introduce "
+                f"node id(s) already present (e.g. {sorted(dup)[0]!r}).")
+        grafted = dict(shard)
+        grafted["carried"] = {
+            "from": old_source.rsplit("/", 1)[-1],
+            "original_commit_sha": old_sha,
+            "original_ended_at": old_receipt.get("session", {}).get("ended_at"),
+            "original_signer": (old_receipt.get("signature") or {}).get("signer"),
+        }
+        payload.setdefault("shards", []).append(grafted)
+        for nid in ids:
+            if nid not in old_tests:
+                raise MergeError(
+                    f"--carry-from {old_source}: shard {nm!r} claims {nid!r} "
+                    f"which is not in its receipt's tests[].")
+            payload["tests"].append(old_tests[nid])
+            fresh_ids.add(nid)
+        carried_count += 1
+    payload["session"]["node_ids"] = [t["node_id"] for t in payload["tests"]]
+    payload["schema_version"] = "2"
+    if not carried_count:
+        print(f"[gpu-proof] merge: nothing to carry from {old_source} "
+              f"(all its shards were freshly re-run)")
+    return payload
+
+
+def merge_receipts(
+    paths: List[str],
+    out: str,
+    *,
+    github_user: Optional[str] = None,
+    key_path: Optional[str] = None,
+    unsigned: bool = False,
+    carry_from: Optional[str] = None,
+    repo_root: str = ".",
+) -> dict:
+    """Merge receipts at ``paths`` and write the re-signed result to ``out``.
+
+    ``github_user`` overrides the recorded signer identity (default: the first
+    shard's ``repo.github_username`` — correct when the merger is also the shard
+    runner). ``unsigned=True`` writes ``signature: null`` (verifies only with
+    ``--allow-unsigned``, loudly, same as the plugin's 'none' backend).
+    ``carry_from`` grafts still-valid shards from an older schema-2 receipt —
+    see :py:func:`carry_forward` for the soundness conditions.
+    """
+    receipts = [load_receipt(p) for p in paths]
+    payload = merge_payloads(receipts, list(paths))
+    if carry_from:
+        payload = carry_forward(payload, load_receipt(carry_from), carry_from,
+                                repo_root=repo_root)
+    if github_user:
+        payload["repo"] = dict(payload.get("repo", {}))
+        payload["repo"]["github_username"] = github_user
+
+    if unsigned:
+        receipt = dict(payload)
+        receipt["signature"] = None
+    else:
+        from .signers.ed25519 import SSHSigner
+        signer = SSHSigner(key_path=key_path)
+        receipt = finalize_receipt(payload, signer)
+    write_receipt(receipt, out)
+    return receipt

{pytest_gpu_proof-0.1.0 → pytest_gpu_proof-0.3.0}/src/pytest_gpu_proof/plugin.py

@@ -201,13 +201,13 @@ def pytest_addoption(parser):
     )
     group.addoption(
         "--gpu-proof-mode",
-        default="local",
+        default=None,
         choices=["local", "ci-gpu"],
         help="Execution mode: local (default) or ci-gpu",
     )
     group.addoption(
         "--gpu-proof-out",
-        default="gpu-proof.json",
+        default=None,
         metavar="PATH",
         help="Output path for the receipt JSON (default: gpu-proof.json)",
     )
@@ -219,7 +219,7 @@ def pytest_addoption(parser):
     )
     group.addoption(
         "--gpu-proof-signing-backend",
-        default="ed25519",
+        default=None,
         choices=["ed25519", "none"],
         help="Signing backend (default: ed25519 via SSH key)",
     )
@@ -231,7 +231,7 @@ def pytest_addoption(parser):
     )
     group.addoption(
         "--gpu-proof-required-marker",
-        default="gpu_proof",
+        default=None,
         help="Marker name that flags a test for the receipt (default: gpu_proof)",
     )
     group.addoption(
@@ -242,10 +242,25 @@ def pytest_addoption(parser):
     )
     group.addoption(
         "--gpu-proof-fingerprint-paths",
-        default="src,tests",
+        default=None,
         metavar="PATHS",
         help="Comma-separated paths to fingerprint (default: src,tests)",
     )
+    group.addoption(
+        "--gpu-proof-shard",
+        default=None,
+        metavar="NAME",
+        help="Declare this run as one SHARD of a larger suite: the receipt is "
+        "emitted as schema '2' with a per-shard fingerprint, enabling "
+        "verifiable carry-forward via `gpu-proof merge --carry-from`",
+    )
+    group.addoption(
+        "--gpu-proof-shard-fingerprint-paths",
+        default=None,
+        metavar="PATHS",
+        help="Comma-separated paths for THIS shard's narrow fingerprint "
+        "(default: the global fingerprint paths)",
+    )
     group.addoption(
         "--gpu-proof-github-user",
         default=None,