ZPE Video

Perception receipts for AI video pipelines. Cross-writer bit-exact under default settings. Zero runtime dependencies.

• Package: zpe-video v0.1.0
• Python: 3.11 / 3.12 / 3.13
• Repository: https://github.com/Zer0pa/ZPE-Video
• Contact: architects@zer0pa.ai

What This Is

Perception-receipt video codec. Staged v0.1.0 receipt surface with explicit non-claims for C2PA and end-to-end latency.

Codec Mechanics

Key Metrics

Source: docs/transparency/phase9_4_1_1_2_1_candidate_b_video_llm_object_memory/summary.json and docs/transparency/phase09_4_1_1_2_2_receipt_core_provenance_benchmark/summary.json

Repo Identity

Readiness

Honest Blocker

Repo PRIVATE during initial crafting; full proof anchors will surface on visibility flip. Phase 1 perception-receipts schema is the active surface.

What We Prove

• Bit-exact cross-writer output under default settings — pinned by tests/test_receipt.py::test_cross_writer_independent_implementation_matches, which hand-rolls an independent from-spec encoder and asserts byte-identical output.
• Per-frame CRC32 integrity on every decode; any corruption raises ReceiptCorrupted — pinned by tests/test_receipt.py::test_crc_mismatch_raises.
• Deterministic hash: receipt_hash(blob) = SHA-256 of the encoded bytes, stable across conforming writers — pinned by tests/test_receipt.py::test_receipt_hash_is_stable.
• Round-trip fidelity: decode_receipt(encode_receipt(r)) recovers the same frame content up to canonical sort order — pinned by tests/test_receipt.py::test_round_trip_small.
• Zero runtime dependencies for the core zpe_video.receipt module — confirmed by installing the built wheel into a clean venv with no extras and running the import surface check (.github/workflows/verify-package.yml).
• Full wire-format specification in docs/WIRE_FORMAT.md sufficient for third-party re-implementation.
• Full falsification history preserved alongside the defended wedge — every kill verdict is recorded in docs/TRANSPARENCY_JOURNEY.md and docs/transparency/.

What We Don't Claim

• We do not claim universal video-codec superiority. Falsified at Phase 08 against AV1, VVC, and learned baselines on both detector families; record preserved.
• We do not claim the archive-query-on-box-state surface is a ZPE-specific wedge. Falsified at Phase 09.4.1.1.2 against a 60-line raw-struct+zlib baseline; raw-struct+zlib strictly dominates ZPE on both storage and query latency for that workload.
• We do not claim the ROI/foveated-sidecar produces a packet-specific lift. Killed at Phase 09.4.1.1.2.1-A when a spatially-uninformed mean-importance control lane produced the identical +7.93% matched-bitrate mAP@50 lift.
• We do not claim Parquet cannot be configured to match. The wedge is specifically about default settings; Parquet tuned with enforced encoding and sorting can close the gap.
• We do not claim buyer-visible end-to-end latency win in video-LLM pipelines. LLM generation dominates ~97% of end-to-end time; the receipt's speed advantage is a storage/memory property.
• We do not claim the Compass-8 / 8-primitive directional-encoding architecture. This codec does not use it. The Compass-8 substrate is a research thesis that was tested in pre-0.1.0 phases and did not produce a defended product closure; the v0.1.0 product is the perception receipt, which stands on its own.

Verification Status

Proof Anchors

Repo Shape

Competitive Benchmarks

Source: docs/transparency/phase9_4_1_1_2_1_candidate_b_video_llm_object_memory/cross_writer_hashes.json and docs/transparency/phase9_4_1_1_2_fair_baseline/summary.json

Raw struct + zlib is smaller in raw bytes but has no per-frame CRC32, no schema, no versioning — unsuitable as a receipt. ZPE is the smallest format that is also cross-writer stable under defaults AND carries integrity.

Quick Start

git clone https://github.com/Zer0pa/ZPE-Video.git
cd ZPE-Video
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip uv
uv sync --extra dev
uv run pytest tests -v
uv run python examples/02_cross_writer.py   # expected: "cross-writer wedge: VERIFIED"

Expected: 29/29 tests pass; the cross-writer example prints cross-writer wedge: VERIFIED with byte-identical output from the library and an independent from-spec encoder.

Ecosystem

ZPE Video is one lane in a broader family of ZPE repositories. Each lane follows the same evidence-first discipline: narrow wedges, preserved kill verdicts, cross-writer or cross-implementation determinism where it's the load-bearing product property.

• ZPE-Neuro — neural-recording spike-sorting and breadth adjudication.
• ZPE-Prosody — speech prosody and rhythm analysis.

Common conventions: stdlib-heavy cores, deterministic binary artifacts, explicit non-claims, and falsification ledgers shipped alongside defended wedges.

Who This Is For

• Platform teams building AI perception pipelines who need an auditable "what was seen" record that survives platform migration without re-running the detector.
• Regulated video workflows (police body-worn cameras, insurance fraud, legal discovery) that need to disclose track state without disclosing pixels.
• C2PA implementers who want a tiny, stable, binary artifact to reference by hash from a Content Credentials manifest.
• Video-LLM / VideoRAG infrastructure needing integrity-guaranteed, cross-platform object-memory caches.
• ML teams redistributing detection output as training data across languages and toolchains.

Not for teams that need full-fidelity video compression, perceptual video quality, or a VMS replacement. See docs/WEDGE.md for the full buyer-shape list and non-claims.

Upcoming Workstreams

Active lane priorities under the 0.1.0 perception-receipt wedge. Cadence is continuous, not milestoned. Open items, falsification routes, and decision criteria live in docs/_reorientation/2026-04-17/OPEN_QUESTIONS.md and the synthesis docs under docs/transparency/research_ledger/.

• Receipt-core provenance benchmark adoption — Active. Promote the Phase 09.4.1.1.2.2 receipt-core provenance benchmark from internal transparency bundle to a CI-anchored, repo-generated reproducibility surface. See docs/transparency/phase09_4_1_1_2_2_receipt_core_provenance_benchmark/.
• Cross-writer-stable hash defense — Active. Maintain byte-identical output between the library writer and the independent from-spec writer in examples/02_cross_writer.py; extend coverage to the full WIRE_FORMAT.md surface.
• C2PA Content Credentials binding — Research-Deferred. Define the manifest-binding shape that lets a C2PA producer reference a perception receipt by hash without embedding receipt bytes in the credential. See docs/transparency/phase09_4_1_1_2_2_receipt_core_provenance_benchmark/manifest_binding.json.
• Authority-packet promotion — Operations. Move proofs/manifests/CURRENT_AUTHORITY_PACKET.md from staged state to a release-cut authority packet bound to a tagged version; gate via scripts/authority_bundle.py and scripts/compliance_audit.sh.