feat(evidence): add deterministic exact snapshot manifests

README.md

@@ -177,6 +177,37 @@ Run the dedicated pivot capability artifact with:
 uv run excelbench cross-language-pivot-context --fixture fixtures/excel/tier2/15_pivot_tables.xlsx --output results-cross-language-pivots
 ```
 
+
+## Exact Evidence Manifests
+
+A benchmark directory can be bound to its exact source and artifact identities with
+a deterministic, path-free manifest:
+
+```bash
+uv run excelbench evidence-manifest \
+  --root results-release-2026-08-31 \
+  --snapshot-id wolfxl-2.1-linux-x86_64 \
+  --source-sha 0123456789abcdef0123456789abcdef01234567 \
+  --observed-at 2026-08-31T00:00:00Z \
+  --subject wolfxl-wheel@2.1.0=<wheel-sha256>
+
+uv run excelbench verify-evidence \
+  --root results-release-2026-08-31 \
+  --expected-source-sha 0123456789abcdef0123456789abcdef01234567
+```
+
+The v1 contract inventories every regular file, hashes a canonical sorted file set,
+rejects symlinks and cross-platform path collisions, and refuses undeclared, missing,
+or changed files. It excludes only the manifest itself. The observation timestamp is
+explicit so identical inputs produce identical manifest bytes.
+
+The manifest is the subject to sign or attest in release CI. Successful verification
+does not make an evidence lane current by itself: public claims must still name the
+snapshot date, source commit, tested package subjects, platform, and workload.
+
+Schema: [\`schemas/evidence-manifest-v1.schema.json\`](schemas/evidence-manifest-v1.schema.json)
+
+
 ## How It Works
 
 1. **Generate reference files** -- [xlwings](https://www.xlwings.org/) drives real Excel to produce canonical `.xlsx`/`.xls` test files with known features.

schemas/evidence-manifest-v1.schema.json

@@ -0,0 +1,118 @@
+{
+  "$id": "https://excelbench.dev/schemas/evidence-manifest/v1",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "artifact_count": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "artifact_set_sha256": {
+      "pattern": "^[0-9a-f]{64}$",
+      "type": "string"
+    },
+    "artifacts": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "type": "string"
+          },
+          "size_bytes": {
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "path",
+          "sha256",
+          "size_bytes"
+        ],
+        "type": "object"
+      },
+      "minItems": 1,
+      "type": "array"
+    },
+    "observed_at": {
+      "format": "date-time",
+      "pattern": "Z$",
+      "type": "string"
+    },
+    "schema": {
+      "const": "https://excelbench.dev/schemas/evidence-manifest/v1"
+    },
+    "schema_version": {
+      "const": 1
+    },
+    "snapshot_id": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "source": {
+      "additionalProperties": false,
+      "properties": {
+        "commit": {
+          "pattern": "^[0-9a-f]{40}$",
+          "type": "string"
+        },
+        "repository": {
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "repository",
+        "commit"
+      ],
+      "type": "object"
+    },
+    "subjects": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "type": "string"
+          },
+          "version": {
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "sha256"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total_size_bytes": {
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "schema",
+    "schema_version",
+    "snapshot_id",
+    "observed_at",
+    "source",
+    "subjects",
+    "artifacts",
+    "artifact_count",
+    "total_size_bytes",
+    "artifact_set_sha256"
+  ],
+  "title": "ExcelBench evidence manifest v1",
+  "type": "object"
+}

src/excelbench/cli.py

@@ -2001,5 +2001,120 @@ def show_summary(results: "BenchmarkResults") -> None:
     console.print(table)
 
 
+@app.command("evidence-manifest")
+def evidence_manifest(
+    root: Path = typer.Option(
+        Path("results"),
+        "--root",
+        help="Evidence directory to inventory exactly.",
+    ),
+    snapshot_id: str = typer.Option(
+        ...,
+        "--snapshot-id",
+        help="Stable identity for this evidence snapshot.",
+    ),
+    source_sha: str = typer.Option(
+        ...,
+        "--source-sha",
+        help="Exact 40-character source commit represented by the evidence.",
+    ),
+    observed_at: str = typer.Option(
+        ...,
+        "--observed-at",
+        help="Explicit timezone-aware observation timestamp.",
+    ),
+    repository: str = typer.Option(
+        "SynthGL/ExcelBench",
+        "--repository",
+        help="Source repository identity.",
+    ),
+    subject: list[str] | None = typer.Option(
+        None,
+        "--subject",
+        help="Bound artifact as NAME=SHA256 or NAME@VERSION=SHA256; repeatable.",
+    ),
+    manifest_name: str = typer.Option(
+        "excelbench-evidence.json",
+        "--manifest-name",
+        help="Manifest filename created directly below the evidence root.",
+    ),
+    replace: bool = typer.Option(
+        False,
+        "--replace",
+        help="Atomically replace an existing manifest.",
+    ),
+) -> None:
+    """Create a deterministic exact-file evidence manifest."""
+    from excelbench.evidence_manifest import (
+        EvidenceManifestError,
+        build_evidence_manifest,
+        parse_subject,
+        verify_evidence_manifest,
+        write_evidence_manifest,
+    )
+
+    try:
+        subjects = [parse_subject(value) for value in subject or []]
+        manifest = build_evidence_manifest(
+            root,
+            snapshot_id=snapshot_id,
+            repository=repository,
+            source_sha=source_sha,
+            observed_at=observed_at,
+            subjects=subjects,
+            manifest_name=manifest_name,
+        )
+        output = root.resolve() / manifest_name
+        write_evidence_manifest(output, manifest, replace=replace)
+        verify_evidence_manifest(root, manifest, manifest_name=manifest_name)
+    except (EvidenceManifestError, OSError) as exc:
+        console.print(f"[red]Evidence manifest refused: {exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]✓ Evidence manifest: {output}[/green]")
+    console.print(f"  Artifacts: {manifest['artifact_count']}")
+    console.print(f"  Artifact set: {manifest['artifact_set_sha256']}")
+
+
+@app.command("verify-evidence")
+def verify_evidence(
+    root: Path = typer.Option(
+        Path("results"),
+        "--root",
+        help="Evidence directory covered by the manifest.",
+    ),
+    manifest_name: str = typer.Option(
+        "excelbench-evidence.json",
+        "--manifest-name",
+        help="Manifest filename directly below the evidence root.",
+    ),
+    expected_source_sha: str | None = typer.Option(
+        None,
+        "--expected-source-sha",
+        help="Optional exact source commit required by the caller.",
+    ),
+) -> None:
+    """Fail unless a manifest exactly covers the current evidence directory."""
+    from excelbench.evidence_manifest import (
+        EvidenceManifestError,
+        read_evidence_manifest,
+        verify_evidence_manifest,
+    )
+
+    path = root.resolve() / manifest_name
+    try:
+        manifest = read_evidence_manifest(path)
+        verify_evidence_manifest(
+            root,
+            manifest,
+            expected_source_sha=expected_source_sha,
+            manifest_name=manifest_name,
+        )
+    except (EvidenceManifestError, OSError) as exc:
+        console.print(f"[red]Evidence verification failed: {exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[green]✓ Evidence verified: {path}[/green]")
+    console.print(f"  Artifact set: {manifest['artifact_set_sha256']}")
+
+
 if __name__ == "__main__":
     app()