vela-state 0.77.0__tar.gz

vela_state-0.77.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: vela-state
+Version: 0.77.0
+Summary: Python loader, reducer, and verifier for Vela scientific frontier state. Cross-impl mirror of the Rust substrate.
+Author-email: Will Blair <william.blair0708@gmail.com>
+License: Apache-2.0 OR MIT
+Project-URL: Homepage, https://github.com/vela-science/vela
+Project-URL: Repository, https://github.com/vela-science/vela
+Project-URL: Documentation, https://github.com/vela-science/vela/blob/main/docs/PROTOCOL.md
+Project-URL: Issues, https://github.com/vela-science/vela/issues
+Project-URL: Changelog, https://github.com/vela-science/vela/releases
+Keywords: science,version-control,frontier,carina,vela,reproducibility,provenance,ai-attribution
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pynacl>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# Vela Python client
+
+Cross-implementation reducer + loader for the Vela protocol. The
+authoritative implementation is the Rust workspace under
+`crates/vela-protocol/`; this Python module mirrors the kernel
+behavior so a third-party Python tool can replay a frontier's
+event log and load a split-repo without depending on the Rust
+binary.
+
+The cross-impl invariant is: given the same canonical event log
+and the same Carina kernel digest, the Rust reducer and the
+Python reducer produce byte-equivalent finding-state digests.
+This is the load-bearing property that lets Vela claim "the
+protocol is implementation-portable."
+
+## What's here
+
+- `vela_reducer.py`: the reducer dispatch. Accepts a canonical
+  `StateEvent` JSON dict + a Project state dict, applies the
+  reducer arm for the event's `kind`, mutates state in place.
+  Mirrors `crates/vela-protocol/src/reducer.rs::apply_event`.
+
+- `vela_loader.py`: the split-repo loader. Reads
+  `.vela/findings/`, `.vela/events/`, `.vela/proposals/`, plus
+  `frontier.yaml`, populates `project.dependencies` from the v0.59
+  `frontiers_v2` schema, replays events through the reducer.
+  Mirrors `crates/vela-protocol/src/repo.rs::load_vela_repo`.
+  Yaml is parsed via `pyyaml` if present; otherwise a
+  hand-rolled parser narrow to the manifest's exact shape.
+
+- `tests/test_loader_frontiers_v2.py`: integration test
+  asserting the loader produces the same dependency state +
+  finding state the Rust loader does on a real frontier
+  (`projects/early-ad-biomarker-calibration`).
+
+## Usage
+
+```python
+from vela_loader import load_frontier_repo
+
+project = load_frontier_repo("/path/to/projects/early-ad-biomarker-calibration")
+
+# project is a dict with keys:
+#   project: { name, description, dependencies }
+#   frontier_id, findings, events, proposals
+#   review_events, confidence_updates, manifest
+#   negative_results, trajectories, artifacts, evidence_atoms
+
+print(f"frontier: {project['project']['name']} ({project['frontier_id']})")
+print(f"findings: {len(project['findings'])}")
+print(f"events:   {len(project['events'])}")
+print(f"deps:     {len(project['project']['dependencies'])}")
+```
+
+## What's NOT here (honest gaps)
+
+The Python loader does not currently rehydrate every field the
+Rust loader does. Specifically missing:
+
+- `vela.lock` (lockfile parsing).
+- `actors.json`, `peers.json` (federation surfaces).
+- `proof-state.json`.
+- `signatures/`, `replications/`, `datasets/`, `code-artifacts/`,
+  `predictions/`, `resolutions/`, `artifacts/`.
+- The v0.55 trajectories+nulls materialization.
+- The v0.56 evidence-atom locator materialization.
+- `.vela/links/manifest.json` redistribution.
+- `project::recompute_stats`.
+
+These are real gaps. The cross-impl invariant currently holds at
+the finding-state-digest level only; full Project parity is a
+follow-on cycle. Anyone implementing a third Vela language
+binding should target the same subset first and document their
+gaps as honestly.
+
+## Running the test
+
+The test runs without pytest if needed:
+
+```bash
+python3 clients/python/tests/test_loader_frontiers_v2.py
+```
+
+Or with pytest:
+
+```bash
+python3 -m pytest clients/python/tests/
+```
+
+## Cross-impl correctness
+
+The fixture harness is Rust-side at
+`crates/vela-protocol/tests/cross_impl_reducer_fixtures.rs`.
+Each fixture builder generates an event log; the test exports
+the same logs to JSON for the Python reducer to replay; the
+finding-state digests must match byte-for-byte. The test file's
+`fixture_coverage_includes_every_reducer_arm` assertion
+verifies every kind in `REDUCER_MUTATION_KINDS` has a fixture
+builder. New kinds added to the Rust reducer must be reflected
+in this Python module (a no-op match arm is sufficient if the
+kind doesn't mutate finding state) and in the fixture builders.
+
+## Doctrine
+
+The Python loader is a mirror, not the spec. When the Rust and
+Python reducers disagree, the Rust implementation is
+authoritative; the Python side is the bug. The cross-impl test
+catches the disagreement; the spec at `docs/PROTOCOL.md`
+documents the canonical behavior.
+
+No silent edits. No event-log mutation. No version-skew
+silently glossed; if a new kind appears in the event log that
+the Python dispatch doesn't know, the loader raises rather
+than silently dropping the event.

vela_state-0.77.0/README.md

@@ -0,0 +1,114 @@
+# Vela Python client
+
+Cross-implementation reducer + loader for the Vela protocol. The
+authoritative implementation is the Rust workspace under
+`crates/vela-protocol/`; this Python module mirrors the kernel
+behavior so a third-party Python tool can replay a frontier's
+event log and load a split-repo without depending on the Rust
+binary.
+
+The cross-impl invariant is: given the same canonical event log
+and the same Carina kernel digest, the Rust reducer and the
+Python reducer produce byte-equivalent finding-state digests.
+This is the load-bearing property that lets Vela claim "the
+protocol is implementation-portable."
+
+## What's here
+
+- `vela_reducer.py`: the reducer dispatch. Accepts a canonical
+  `StateEvent` JSON dict + a Project state dict, applies the
+  reducer arm for the event's `kind`, mutates state in place.
+  Mirrors `crates/vela-protocol/src/reducer.rs::apply_event`.
+
+- `vela_loader.py`: the split-repo loader. Reads
+  `.vela/findings/`, `.vela/events/`, `.vela/proposals/`, plus
+  `frontier.yaml`, populates `project.dependencies` from the v0.59
+  `frontiers_v2` schema, replays events through the reducer.
+  Mirrors `crates/vela-protocol/src/repo.rs::load_vela_repo`.
+  Yaml is parsed via `pyyaml` if present; otherwise a
+  hand-rolled parser narrow to the manifest's exact shape.
+
+- `tests/test_loader_frontiers_v2.py`: integration test
+  asserting the loader produces the same dependency state +
+  finding state the Rust loader does on a real frontier
+  (`projects/early-ad-biomarker-calibration`).
+
+## Usage
+
+```python
+from vela_loader import load_frontier_repo
+
+project = load_frontier_repo("/path/to/projects/early-ad-biomarker-calibration")
+
+# project is a dict with keys:
+#   project: { name, description, dependencies }
+#   frontier_id, findings, events, proposals
+#   review_events, confidence_updates, manifest
+#   negative_results, trajectories, artifacts, evidence_atoms
+
+print(f"frontier: {project['project']['name']} ({project['frontier_id']})")
+print(f"findings: {len(project['findings'])}")
+print(f"events:   {len(project['events'])}")
+print(f"deps:     {len(project['project']['dependencies'])}")
+```
+
+## What's NOT here (honest gaps)
+
+The Python loader does not currently rehydrate every field the
+Rust loader does. Specifically missing:
+
+- `vela.lock` (lockfile parsing).
+- `actors.json`, `peers.json` (federation surfaces).
+- `proof-state.json`.
+- `signatures/`, `replications/`, `datasets/`, `code-artifacts/`,
+  `predictions/`, `resolutions/`, `artifacts/`.
+- The v0.55 trajectories+nulls materialization.
+- The v0.56 evidence-atom locator materialization.
+- `.vela/links/manifest.json` redistribution.
+- `project::recompute_stats`.
+
+These are real gaps. The cross-impl invariant currently holds at
+the finding-state-digest level only; full Project parity is a
+follow-on cycle. Anyone implementing a third Vela language
+binding should target the same subset first and document their
+gaps as honestly.
+
+## Running the test
+
+The test runs without pytest if needed:
+
+```bash
+python3 clients/python/tests/test_loader_frontiers_v2.py
+```
+
+Or with pytest:
+
+```bash
+python3 -m pytest clients/python/tests/
+```
+
+## Cross-impl correctness
+
+The fixture harness is Rust-side at
+`crates/vela-protocol/tests/cross_impl_reducer_fixtures.rs`.
+Each fixture builder generates an event log; the test exports
+the same logs to JSON for the Python reducer to replay; the
+finding-state digests must match byte-for-byte. The test file's
+`fixture_coverage_includes_every_reducer_arm` assertion
+verifies every kind in `REDUCER_MUTATION_KINDS` has a fixture
+builder. New kinds added to the Rust reducer must be reflected
+in this Python module (a no-op match arm is sufficient if the
+kind doesn't mutate finding state) and in the fixture builders.
+
+## Doctrine
+
+The Python loader is a mirror, not the spec. When the Rust and
+Python reducers disagree, the Rust implementation is
+authoritative; the Python side is the bug. The cross-impl test
+catches the disagreement; the spec at `docs/PROTOCOL.md`
+documents the canonical behavior.
+
+No silent edits. No event-log mutation. No version-skew
+silently glossed; if a new kind appears in the event log that
+the Python dispatch doesn't know, the loader raises rather
+than silently dropping the event.

vela_state-0.77.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vela-state"
+version = "0.77.0"
+description = "Python loader, reducer, and verifier for Vela scientific frontier state. Cross-impl mirror of the Rust substrate."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0 OR MIT" }
+authors = [
+    { name = "Will Blair", email = "william.blair0708@gmail.com" }
+]
+keywords = [
+    "science",
+    "version-control",
+    "frontier",
+    "carina",
+    "vela",
+    "reproducibility",
+    "provenance",
+    "ai-attribution",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "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",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "pynacl>=1.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/vela-science/vela"
+Repository = "https://github.com/vela-science/vela"
+Documentation = "https://github.com/vela-science/vela/blob/main/docs/PROTOCOL.md"
+Issues = "https://github.com/vela-science/vela/issues"
+Changelog = "https://github.com/vela-science/vela/releases"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "ruff>=0.6",
+]
+
+[tool.setuptools]
+py-modules = ["vela_loader", "vela_reducer", "vela_verify"]
+
+[tool.setuptools.package-data]
+"*" = ["*.md"]

vela_state-0.77.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vela_state-0.77.0/tests/test_loader_frontiers_v2.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# Pairs with W1.7 (v0.66): the Python loader at
+# `clients/python/vela_loader.py` must rehydrate
+# `manifest.dependencies.frontiers_v2` into `project.dependencies`,
+# exactly the way `crates/vela-protocol/src/repo.rs::load_vela_repo`
+# does on the Rust side. Without it, a Python replay of the event log
+# cannot resolve cross-frontier link references.
+#
+# This test loads the early-AD biomarker calibration project, which in
+# v0.59 declared an anti-amyloid bridge dependency
+# (vfr_5076e7b3ff8e6b0f), and confirms the Python loader sees it. It
+# also confirms the event log replays cleanly (the v0.65 + v0.66 review
+# verdicts are accepted findings).
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Allow running both as `python3 -m pytest …` from repo root and as
+# `python3 tests/test_loader_frontiers_v2.py` from inside the package.
+_HERE = Path(__file__).resolve().parent
+_PACKAGE_DIR = _HERE.parent
+if str(_PACKAGE_DIR) not in sys.path:
+    sys.path.insert(0, str(_PACKAGE_DIR))
+
+from vela_loader import load_frontier_repo  # noqa: E402
+
+_REPO_ROOT = _PACKAGE_DIR.parent.parent
+_PROJECT = _REPO_ROOT / "projects" / "early-ad-biomarker-calibration"
+
+
+def test_dependencies_rehydrated_from_yaml() -> None:
+    repo = load_frontier_repo(str(_PROJECT))
+    deps = repo["project"]["dependencies"]
+    assert isinstance(deps, list) and len(deps) >= 1, (
+        "expected at least one entry under project.dependencies, got "
+        f"{deps!r}"
+    )
+    vfr_ids = {d.get("vfr_id") for d in deps}
+    assert "vfr_5076e7b3ff8e6b0f" in vfr_ids, (
+        "anti-amyloid bridge (vfr_5076e7b3ff8e6b0f) not rehydrated from "
+        f"frontier.yaml; saw {sorted(vfr_ids)!r}"
+    )
+
+    bridge = next(d for d in deps if d.get("vfr_id") == "vfr_5076e7b3ff8e6b0f")
+    assert bridge.get("source") == "vela.hub"
+    assert bridge.get("name") == "anti-amyloid-translation"
+    assert bridge.get("locator"), "bridge dep missing locator"
+    assert bridge.get("pinned_snapshot_hash"), "bridge dep missing pinned_snapshot_hash"
+
+
+def test_events_and_accepted_findings() -> None:
+    repo = load_frontier_repo(str(_PROJECT))
+    events = repo["events"]
+    assert isinstance(events, list) and len(events) > 0, (
+        "expected non-empty events list after split-repo load"
+    )
+
+    accepted = [
+        f
+        for f in repo["findings"]
+        if (f.get("flags") or {}).get("review_state") == "accepted"
+    ]
+    assert len(accepted) >= 4, (
+        f"expected at least 4 accepted findings after replay, got "
+        f"{len(accepted)} (review_states: "
+        f"{[ (f.get('flags') or {}).get('review_state') for f in repo['findings']]})"
+    )
+
+
+def test_frontier_id_loaded() -> None:
+    repo = load_frontier_repo(str(_PROJECT))
+    assert repo["frontier_id"] == "vfr_a22c9022674a2304"
+
+
+if __name__ == "__main__":
+    # Lightweight runner so `python3 test_loader_frontiers_v2.py` works
+    # even if pytest is unavailable in the local env.
+    failures = 0
+    for fn in (
+        test_dependencies_rehydrated_from_yaml,
+        test_events_and_accepted_findings,
+        test_frontier_id_loaded,
+    ):
+        try:
+            fn()
+            print(f"ok   · {fn.__name__}")
+        except AssertionError as e:
+            failures += 1
+            print(f"FAIL · {fn.__name__}: {e}")
+        except Exception as e:
+            failures += 1
+            print(f"ERR  · {fn.__name__}: {type(e).__name__}: {e}")
+    raise SystemExit(0 if failures == 0 else 1)