liveframe 0.1.0__tar.gz

liveframe-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+release/
+
+# LaTeX build scratch files
+paper/arxiv/*.aux
+paper/arxiv/*.blg
+paper/arxiv/*.log
+paper/arxiv/*.out
+
+# Large or machine-local artifacts
+outputs/
+weights/
+checkpoints/
+third_party/
+artifacts/h100-holdout-results/
+artifacts/mlx-holdout-results/
+artifacts/shared-rolling-noise.v1/
+*.pt
+*.pth
+*.safetensors
+*.mp4
+*.mov
+*.mkv
+
+# Runtime state
+.liveframe/
+.claude/settings.local.json

liveframe-0.1.0/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by the
+      copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all other
+      entities that control, are controlled by, or are under common control
+      with that entity. For the purposes of this definition, "control" means
+      (i) the power, direct or indirect, to cause the direction or management
+      of such entity, whether by contract or otherwise, or (ii) ownership of
+      fifty percent (50%) or more of the outstanding shares, or (iii)
+      beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity exercising
+      permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation source,
+      and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and conversions
+      to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or Object
+      form, made available under the License, as indicated by a copyright
+      notice that is included in or attached to the work (an example is
+      provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object form,
+      that is based on (or derived from) the Work and for which the editorial
+      revisions, annotations, elaborations, or other modifications represent,
+      as a whole, an original work of authorship. For the purposes of this
+      License, Derivative Works shall not include works that remain separable
+      from, or merely link (or bind by name) to the interfaces of, the Work and
+      Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including the original
+      version of the Work and any modifications or additions to that Work or
+      Derivative Works thereof, that is intentionally submitted to Licensor for
+      inclusion in the Work by the copyright owner or by an individual or Legal
+      Entity authorized to submit on behalf of the copyright owner. For the
+      purposes of this definition, "submitted" means any form of electronic,
+      verbal, or written communication sent to the Licensor or its
+      representatives, including but not limited to communication on electronic
+      mailing lists, source code control systems, and issue tracking systems
+      that are managed by, or on behalf of, the Licensor for the purpose of
+      discussing and improving the Work, but excluding communication that is
+      conspicuously marked or otherwise designated in writing by the copyright
+      owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity on
+      behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+      reproduce, prepare Derivative Works of, publicly display, publicly
+      perform, sublicense, and distribute the Work and such Derivative Works in
+      Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of this
+      License, each Contributor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+      this section) patent license to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work, where such license applies only
+      to those patent claims licensable by such Contributor that are
+      necessarily infringed by their Contribution(s) alone or by combination of
+      their Contribution(s) with the Work to which such Contribution(s) was
+      submitted. If You institute patent litigation against any entity
+      (including a cross-claim or counterclaim in a lawsuit) alleging that the
+      Work or a Contribution incorporated within the Work constitutes direct or
+      contributory patent infringement, then any patent licenses granted to You
+      under this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work or
+      Derivative Works thereof in any medium, with or without modifications, and
+      in Source or Object form, provided that You meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works a
+          copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices stating
+          that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that You
+          distribute, all copyright, patent, trademark, and attribution notices
+          from the Source form of the Work, excluding those notices that do not
+          pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained within
+          such NOTICE file, excluding those notices that do not pertain to any
+          part of the Derivative Works, in at least one of the following places:
+          within a NOTICE text file distributed as part of the Derivative Works;
+          within the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the Derivative
+          Works, if and wherever such third-party notices normally appear. The
+          contents of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own copyright statement to Your modifications and may
+      provide additional or different license terms and conditions for use,
+      reproduction, or distribution of Your modifications, or for any such
+      Derivative Works as a whole, provided Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions stated in
+      this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise, any
+      Contribution intentionally submitted for inclusion in the Work by You to
+      the Licensor shall be under the terms and conditions of this License,
+      without any additional terms or conditions. Notwithstanding the above,
+      nothing herein shall supersede or modify the terms of any separate license
+      agreement you may have executed with Licensor regarding such
+      Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade names,
+      trademarks, service marks, or product names of the Licensor, except as
+      required for reasonable and customary use in describing the origin of the
+      Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+      writing, Licensor provides the Work (and each Contributor provides its
+      Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+      ANY KIND, either express or implied, including, without limitation, any
+      warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+      FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
+      determining the appropriateness of using or redistributing the Work and
+      assume any risks associated with Your exercise of permissions under this
+      License.
+
+   8. Limitation of Liability. In no event and under no legal theory, whether in
+      tort (including negligence), contract, or otherwise, unless required by
+      applicable law (such as deliberate and grossly negligent acts) or agreed
+      to in writing, shall any Contributor be liable to You for damages,
+      including any direct, indirect, special, incidental, or consequential
+      damages of any character arising as a result of this License or out of the
+      use or inability to use the Work (including but not limited to damages for
+      loss of goodwill, work stoppage, computer failure or malfunction, or any
+      and all other commercial damages or losses), even if such Contributor has
+      been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing the Work
+      or Derivative Works thereof, You may choose to offer, and charge a fee for,
+      acceptance of support, warranty, indemnity, or other liability obligations
+      and/or rights consistent with this License. However, in accepting such
+      obligations, You may act only on Your own behalf and on Your sole
+      responsibility, not on behalf of any other Contributor, and only if You
+      agree to indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor by
+      reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following boilerplate
+      notice, with the fields enclosed by brackets "[]" replaced with your own
+      identifying information. (Don't include the brackets!) The text should be
+      enclosed in the appropriate comment syntax for the file format. We also
+      recommend that a file or class name and description of purpose be included
+      on the same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

liveframe-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: liveframe
+Version: 0.1.0
+Summary: Evidence-first measurement of real-time autoregressive diffusion video. Verifier CLI for LiveFrame claim ledgers and digest-bound artifacts.
+Project-URL: Repository, https://github.com/kkjcodes/liveframe
+Author-email: "Kumar K. Jha" <kumar.krishnanand@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: benchmarking,cuda,diffusion,mlx,reproducibility,video-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# LiveFrame
+
+**Real-time video generation, honestly measured.**
+
+LiveFrame is an evidence-first measurement framework for real-time autoregressive
+diffusion video, spanning NVIDIA CUDA and Apple MLX. It separates four claim layers —
+numerical trajectory, intrinsic quality, same-seed identity, and complete-wall
+performance — with pre-registered thresholds and digest-bound provenance.
+
+Paper: *LiveFrame: Evidence-First Measurement of Real-Time Autoregressive Diffusion
+Video Across CUDA and Apple MLX* (2026).
+
+## This release (0.1.0)
+
+This first release ships the **evidence verifier** for LiveFrame claim ledgers:
+
+```bash
+pip install liveframe
+
+# re-hash every unique digest-bound artifact referenced by a ledger (fail-closed)
+liveframe verify path/to/liveframe-publication-claims.v1.json --artifacts-root path/to/repo
+
+# independently recompute headline arithmetic from values recorded in the ledger
+liveframe recompute path/to/liveframe-publication-claims.v1.json
+```
+
+`verify` requires the separately distributed evidence artifacts referenced by the
+ledger; model weights and evidence files are not bundled in this Python package.
+It rejects missing files, digest mismatches, unsupported schemas, conflicting
+references, and artifact paths outside the selected root.
+
+The streaming engine APIs (`stream`, `clip`, `benchmark`) are planned for later
+releases. See the repository for the full evidence bundle, claim protocol, and
+reports.
+
+## License
+
+Apache-2.0

liveframe-0.1.0/README.md

@@ -0,0 +1,38 @@
+# LiveFrame
+
+**Real-time video generation, honestly measured.**
+
+LiveFrame is an evidence-first measurement framework for real-time autoregressive
+diffusion video, spanning NVIDIA CUDA and Apple MLX. It separates four claim layers —
+numerical trajectory, intrinsic quality, same-seed identity, and complete-wall
+performance — with pre-registered thresholds and digest-bound provenance.
+
+Paper: *LiveFrame: Evidence-First Measurement of Real-Time Autoregressive Diffusion
+Video Across CUDA and Apple MLX* (2026).
+
+## This release (0.1.0)
+
+This first release ships the **evidence verifier** for LiveFrame claim ledgers:
+
+```bash
+pip install liveframe
+
+# re-hash every unique digest-bound artifact referenced by a ledger (fail-closed)
+liveframe verify path/to/liveframe-publication-claims.v1.json --artifacts-root path/to/repo
+
+# independently recompute headline arithmetic from values recorded in the ledger
+liveframe recompute path/to/liveframe-publication-claims.v1.json
+```
+
+`verify` requires the separately distributed evidence artifacts referenced by the
+ledger; model weights and evidence files are not bundled in this Python package.
+It rejects missing files, digest mismatches, unsupported schemas, conflicting
+references, and artifact paths outside the selected root.
+
+The streaming engine APIs (`stream`, `clip`, `benchmark`) are planned for later
+releases. See the repository for the full evidence bundle, claim protocol, and
+reports.
+
+## License
+
+Apache-2.0

liveframe-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "liveframe"
+version = "0.1.0"
+description = "Evidence-first measurement of real-time autoregressive diffusion video. Verifier CLI for LiveFrame claim ledgers and digest-bound artifacts."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Kumar K. Jha", email = "kumar.krishnanand@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["diffusion", "video-generation", "benchmarking", "reproducibility", "mlx", "cuda"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Repository = "https://github.com/kkjcodes/liveframe"
+
+[project.scripts]
+liveframe = "liveframe.cli:main"
+
+[tool.hatch.build.targets.sdist]
+ignore-vcs = true
+only-include = ["src", "tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/liveframe"]

liveframe-0.1.0/src/liveframe/__init__.py

@@ -0,0 +1,11 @@
+"""LiveFrame: evidence-first measurement of real-time autoregressive diffusion video.
+
+Real-time video generation, honestly measured.
+
+This initial release ships the evidence verifier for LiveFrame claim ledgers
+(schema ``liveframe.publication-claims.v1``): it re-hashes referenced artifacts,
+checks digest bindings, and recomputes headline arithmetic from ledger values.
+The streaming engine APIs (``stream``, ``clip``, ``benchmark``) land in later releases.
+"""
+
+__version__ = "0.1.0"

liveframe-0.1.0/src/liveframe/cli.py

@@ -0,0 +1,227 @@
+"""LiveFrame evidence verifier CLI.
+
+Usage:
+    liveframe verify <claims-ledger.json> [--artifacts-root DIR]
+    liveframe recompute <claims-ledger.json>
+    liveframe version
+
+``verify`` re-hashes every artifact referenced by the ledger and fails closed on
+any digest mismatch or missing file. ``recompute`` independently recalculates the
+headline arithmetic (speedup, reduction fractions, target gap) from the values
+recorded in the ledger and reports any inconsistency.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+LEDGER_SCHEMA = "liveframe.publication-claims.v1"
+SHA256_PATTERN = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return "sha256:" + h.hexdigest()
+
+
+def _load_ledger(path: Path) -> dict[str, Any]:
+    ledger = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(ledger, dict):
+        raise ValueError("claims ledger must be a JSON object")
+    if ledger.get("schema") != LEDGER_SCHEMA:
+        raise ValueError(
+            f"unsupported claims ledger schema: {ledger.get('schema', '<missing>')}"
+        )
+    return ledger
+
+
+def _iter_artifact_refs(node: object, refs: dict[str, str]) -> dict[str, str]:
+    if isinstance(node, dict):
+        artifact = node.get("artifact")
+        digest = node.get("sha256")
+        if artifact is not None or digest is not None:
+            if not isinstance(artifact, str) or not isinstance(digest, str):
+                raise ValueError(
+                    "artifact references require string artifact and sha256 fields"
+                )
+            if not SHA256_PATTERN.fullmatch(digest):
+                raise ValueError(f"invalid SHA-256 digest for artifact: {artifact}")
+            previous = refs.get(artifact)
+            if previous is not None and previous != digest:
+                raise ValueError(f"conflicting digests for artifact: {artifact}")
+            refs[artifact] = digest
+        for value in node.values():
+            _iter_artifact_refs(value, refs)
+    elif isinstance(node, list):
+        for value in node:
+            _iter_artifact_refs(value, refs)
+    return refs
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    ledger_path = Path(args.ledger)
+    ledger = _load_ledger(ledger_path)
+    print(f"ledger: {ledger_path}  schema: {ledger['schema']}")
+    root = (
+        Path(args.artifacts_root) if args.artifacts_root else ledger_path.parent.parent
+    ).resolve()
+    refs = _iter_artifact_refs(ledger, {})
+    if not refs:
+        print("FAIL: ledger references no digest-bound artifacts")
+        return 2
+    failures = 0
+    for rel, expected in sorted(refs.items()):
+        relative = Path(rel)
+        if relative.is_absolute() or ".." in relative.parts:
+            print(f"  INVALID  {rel} (artifact path must remain below root)")
+            failures += 1
+            continue
+        target = (root / relative).resolve()
+        if not target.is_relative_to(root):
+            print(f"  INVALID  {rel} (artifact path resolves outside root)")
+            failures += 1
+            continue
+        if not target.is_file():
+            print(f"  MISSING  {rel}")
+            failures += 1
+            continue
+        actual = _sha256(target)
+        status = "ok" if actual == expected else "DIGEST MISMATCH"
+        if actual != expected:
+            failures += 1
+            print(f"  {status}  {rel}\n    expected {expected}\n    actual   {actual}")
+        else:
+            print(f"  ok       {rel}")
+    if failures:
+        print(
+            f"FAIL: {failures}/{len(refs)} artifact reference(s) "
+            "did not verify (fail-closed)"
+        )
+        return 1
+    print(f"PASS: all {len(refs)} unique digest-bound artifacts verified")
+    return 0
+
+
+def _number(container: Mapping[str, Any], name: str, context: str) -> float:
+    value = container.get(name)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{context}.{name} must be numeric")
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError(f"{context}.{name} must be finite")
+    return result
+
+
+def cmd_recompute(args: argparse.Namespace) -> int:
+    ledger = _load_ledger(Path(args.ledger))
+    problems = 0
+    checks = 0
+    engineering_speedups = ledger.get("engineering_speedups")
+    negative_results = ledger.get("negative_results")
+    if not isinstance(engineering_speedups, list):
+        raise ValueError("engineering_speedups must be an array")
+    if not isinstance(negative_results, list):
+        raise ValueError("negative_results must be an array")
+    for claim in engineering_speedups:
+        if not isinstance(claim, dict):
+            raise ValueError("each engineering speedup must be an object")
+        base, cand = claim.get("baseline", {}), claim.get("candidate", {})
+        if not isinstance(base, dict) or not isinstance(cand, dict):
+            raise ValueError("engineering speedup baseline and candidate must be objects")
+        claim_id = str(claim.get("id", "<missing>"))
+        bw = _number(base, "wall_seconds", f"{claim_id}.baseline")
+        cw = _number(cand, "wall_seconds", f"{claim_id}.candidate")
+        if bw <= 0 or cw <= 0:
+            raise ValueError(f"{claim_id} wall times must be positive")
+        speedup = bw / cw
+        reduction = (bw - cw) / bw
+        bv = _number(base, "vae_seconds", f"{claim_id}.baseline")
+        cv = _number(cand, "vae_seconds", f"{claim_id}.candidate")
+        if bv <= 0 or cv < 0:
+            raise ValueError(f"{claim_id} VAE times must be non-negative with positive baseline")
+        vae_reduction = (bv - cv) / bv
+        for name, computed in (
+            ("wall_speedup", speedup),
+            ("wall_reduction_fraction", reduction),
+            ("vae_reduction_fraction", vae_reduction),
+        ):
+            recorded = _number(claim, name, claim_id)
+            ok = abs(recorded - computed) < 1e-9
+            checks += 1
+            problems += 0 if ok else 1
+            print(
+                f"  {claim_id}: {name} recorded={recorded:.9f} "
+                f"recomputed={computed:.9f} {'ok' if ok else 'MISMATCH'}"
+            )
+    for neg in negative_results:
+        if not isinstance(neg, dict):
+            raise ValueError("each negative result must be an object")
+        ev = neg.get("evidence", {})
+        if not isinstance(ev, dict) or not any(
+            name in ev
+            for name in ("generated_fps", "target_fps", "target_gap_factor")
+        ):
+            continue
+        claim_id = str(neg.get("id", "<missing>"))
+        fps = _number(ev, "generated_fps", f"{claim_id}.evidence")
+        target = _number(ev, "target_fps", f"{claim_id}.evidence")
+        gap = _number(ev, "target_gap_factor", f"{claim_id}.evidence")
+        if fps <= 0 or target <= 0:
+            raise ValueError(f"{claim_id} FPS values must be positive")
+        computed = target / fps
+        ok = abs(gap - computed) < 1e-9
+        checks += 1
+        problems += 0 if ok else 1
+        print(
+            f"  {claim_id}: target_gap_factor recorded={gap:.9f} "
+            f"recomputed={computed:.9f} {'ok' if ok else 'MISMATCH'}"
+        )
+    if checks == 0:
+        print("FAIL: ledger contains no supported arithmetic claims")
+        return 2
+    if problems:
+        print(f"FAIL: {problems} arithmetic inconsistency(ies)")
+        return 1
+    print("PASS: ledger arithmetic reproduces")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="liveframe", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_verify = sub.add_parser(
+        "verify", help="verify digest-bound artifact references in a claims ledger"
+    )
+    p_verify.add_argument("ledger")
+    p_verify.add_argument(
+        "--artifacts-root",
+        default=None,
+        help="root directory artifact paths are relative to (default: ledger grandparent)",
+    )
+    p_verify.set_defaults(func=cmd_verify)
+    p_re = sub.add_parser("recompute", help="recompute headline arithmetic from ledger values")
+    p_re.add_argument("ledger")
+    p_re.set_defaults(func=cmd_recompute)
+    p_v = sub.add_parser("version", help="print version")
+    p_v.set_defaults(func=lambda a: (print(__import__("liveframe").__version__), 0)[1])
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (OSError, UnicodeError, json.JSONDecodeError, ValueError) as error:
+        print(f"FAIL: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

liveframe-0.1.0/tests/test_cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from io import StringIO
+from pathlib import Path
+
+from liveframe.cli import main
+
+
+class CliTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary_directory = tempfile.TemporaryDirectory()
+        self.root = Path(self.temporary_directory.name)
+        artifact = self.root / "artifacts" / "sample.json"
+        artifact.parent.mkdir()
+        artifact.write_text('{"passed": true}\n', encoding="utf-8")
+        digest = "sha256:" + hashlib.sha256(artifact.read_bytes()).hexdigest()
+        self.ledger = self.root / "artifacts" / "claims.json"
+        self.payload = {
+            "schema": "liveframe.publication-claims.v1",
+            "engineering_speedups": [
+                {
+                    "id": "speedup",
+                    "baseline": {
+                        "artifact": "artifacts/sample.json",
+                        "sha256": digest,
+                        "wall_seconds": 10.0,
+                        "vae_seconds": 8.0,
+                    },
+                    "candidate": {
+                        "artifact": "artifacts/sample.json",
+                        "sha256": digest,
+                        "wall_seconds": 8.0,
+                        "vae_seconds": 6.0,
+                    },
+                    "wall_speedup": 1.25,
+                    "wall_reduction_fraction": 0.2,
+                    "vae_reduction_fraction": 0.25,
+                }
+            ],
+            "negative_results": [
+                {
+                    "id": "target-gap",
+                    "evidence": {
+                        "generated_fps": 2.0,
+                        "target_fps": 16.0,
+                        "target_gap_factor": 8.0,
+                    },
+                }
+            ],
+        }
+        self._write_ledger()
+
+    def tearDown(self) -> None:
+        self.temporary_directory.cleanup()
+
+    def _write_ledger(self) -> None:
+        self.ledger.write_text(json.dumps(self.payload), encoding="utf-8")
+
+    def _run(self, *arguments: str) -> tuple[int, str]:
+        output = StringIO()
+        with redirect_stdout(output), redirect_stderr(output):
+            result = main(list(arguments))
+        return result, output.getvalue()
+
+    def test_verify_deduplicates_repeated_artifact(self) -> None:
+        result, output = self._run(
+            "verify", str(self.ledger), "--artifacts-root", str(self.root)
+        )
+        self.assertEqual(result, 0)
+        self.assertIn("all 1 unique digest-bound artifacts verified", output)
+
+    def test_verify_fails_on_digest_mismatch(self) -> None:
+        self.payload["engineering_speedups"][0]["baseline"]["sha256"] = (
+            "sha256:" + "0" * 64
+        )
+        self.payload["engineering_speedups"][0]["candidate"]["sha256"] = (
+            "sha256:" + "0" * 64
+        )
+        self._write_ledger()
+        result, output = self._run(
+            "verify", str(self.ledger), "--artifacts-root", str(self.root)
+        )
+        self.assertEqual(result, 1)
+        self.assertIn("DIGEST MISMATCH", output)
+
+    def test_verify_rejects_path_outside_root(self) -> None:
+        claim = self.payload["engineering_speedups"][0]
+        claim["baseline"]["artifact"] = "../sample.json"
+        claim["candidate"]["artifact"] = "../sample.json"
+        self._write_ledger()
+        result, output = self._run(
+            "verify", str(self.ledger), "--artifacts-root", str(self.root)
+        )
+        self.assertEqual(result, 1)
+        self.assertIn("artifact path must remain below root", output)
+
+    def test_verify_rejects_incomplete_artifact_reference(self) -> None:
+        del self.payload["engineering_speedups"][0]["baseline"]["sha256"]
+        self._write_ledger()
+        result, output = self._run("verify", str(self.ledger))
+        self.assertEqual(result, 2)
+        self.assertIn("artifact references require", output)
+
+    def test_recompute_checks_all_supported_arithmetic(self) -> None:
+        result, output = self._run("recompute", str(self.ledger))
+        self.assertEqual(result, 0)
+        self.assertEqual(output.count(" ok"), 4)
+        self.assertIn("vae_reduction_fraction", output)
+
+    def test_recompute_rejects_empty_ledger(self) -> None:
+        self.payload["engineering_speedups"] = []
+        self.payload["negative_results"] = []
+        self._write_ledger()
+        result, output = self._run("recompute", str(self.ledger))
+        self.assertEqual(result, 2)
+        self.assertIn("no supported arithmetic claims", output)
+
+    def test_rejects_unsupported_schema_without_traceback(self) -> None:
+        self.payload["schema"] = "unknown"
+        self._write_ledger()
+        result, output = self._run("verify", str(self.ledger))
+        self.assertEqual(result, 2)
+        self.assertIn("unsupported claims ledger schema", output)
+        self.assertNotIn("Traceback", output)
+
+
+if __name__ == "__main__":
+    unittest.main()