Merge main into joss-paper, resolving conflicts

Resolve conflicts in Makefile, README.md, and docs/dev.md by adopting
main's MyST version variable and docs-serve target.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vahid-ahmadi

.github/bump_version.py

@@ -1,11 +1,21 @@
 """Infer semver bump from towncrier fragment types and update version."""
 
 import re
+import subprocess
 import sys
 from pathlib import Path
 
+SEMVER_PATTERN = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
 
-def get_current_version(pyproject_path: Path) -> str:
+
+def parse_version(version: str) -> tuple[int, int, int]:
+    match = SEMVER_PATTERN.match(version)
+    if not match:
+        raise ValueError(f"Invalid semver: {version}")
+    return tuple(int(part) for part in match.groups())
+
+
+def get_pyproject_version(pyproject_path: Path) -> str:
     text = pyproject_path.read_text()
     match = re.search(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', text, re.MULTILINE)
     if not match:
@@ -17,6 +27,45 @@ def get_current_version(pyproject_path: Path) -> str:
     return match.group(1)
 
 
+def get_changelog_versions(changelog_path: Path) -> list[str]:
+    if not changelog_path.exists():
+        return []
+    return re.findall(
+        r"^## \[(\d+\.\d+\.\d+)\]", changelog_path.read_text(), re.MULTILINE
+    )
+
+
+def get_git_tag_versions(repo_root: Path) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "tag"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return []
+
+    versions = []
+    for tag in result.stdout.splitlines():
+        normalized = tag.removeprefix("v").strip()
+        if SEMVER_PATTERN.match(normalized):
+            versions.append(normalized)
+    return versions
+
+
+def get_current_version(
+    pyproject_path: Path,
+    changelog_path: Path,
+    repo_root: Path,
+) -> str:
+    candidates = [get_pyproject_version(pyproject_path)]
+    candidates.extend(get_changelog_versions(changelog_path))
+    candidates.extend(get_git_tag_versions(repo_root))
+    return max(candidates, key=parse_version)
+
+
 def infer_bump(changelog_dir: Path) -> str:
     fragments = [
         f for f in changelog_dir.iterdir() if f.is_file() and f.name != ".gitkeep"
@@ -48,12 +97,20 @@ def bump_version(version: str, bump: str) -> str:
         return f"{major}.{minor}.{patch + 1}"
 
 
-def update_file(path: Path, old_version: str, new_version: str):
+def update_file(path: Path, new_version: str):
     text = path.read_text()
-    updated = text.replace(
-        f'version = "{old_version}"',
-        f'version = "{new_version}"',
+    updated, replacements = re.subn(
+        r'(^version\s*=\s*")(\d+\.\d+\.\d+)(")',
+        rf"\g<1>{new_version}\g<3>",
+        text,
+        flags=re.MULTILINE,
     )
+    if replacements == 0:
+        print(
+            f"Could not update version in {path}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
     if updated != text:
         path.write_text(updated)
         print(f"  Updated {path}")
@@ -62,15 +119,16 @@ def update_file(path: Path, old_version: str, new_version: str):
 def main():
     root = Path(__file__).resolve().parent.parent
     pyproject = root / "pyproject.toml"
+    changelog = root / "CHANGELOG.md"
     changelog_dir = root / "changelog.d"
 
-    current = get_current_version(pyproject)
+    current = get_current_version(pyproject, changelog, root)
     bump = infer_bump(changelog_dir)
     new = bump_version(current, bump)
 
     print(f"Version: {current} -> {new} ({bump})")
 
-    update_file(pyproject, current, new)
+    update_file(pyproject, new)
 
 
 if __name__ == "__main__":

.github/workflows/push.yaml

@@ -81,10 +81,8 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 18.x
-      - name: Install MyST
-        run: npm install -g mystmd
       - name: Build HTML Assets
-        run: cd docs && myst build --html
+        run: make docs
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -108,6 +106,9 @@ jobs:
         uses: actions/checkout@v4
         with:
           token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 0
+      - name: Fetch tags
+        run: git fetch --tags --force
       - name: Setup Python
         uses: actions/setup-python@v5
         with:

CHANGELOG.md

@@ -1,3 +1,38 @@
+## [3.4.4] - 2026-04-13
+
+### Changed
+
+- Add TRACE TRO export helpers for certified runtime bundles and expose them through `policyengine.core`.
+
+
+## [3.4.3] - 2026-04-13
+
+### Fixed
+
+- Fix the release versioning workflow so it bumps from the highest known released version instead of regressing to a stale version from `pyproject.toml`.
+
+
+## [3.4.1] - 2026-04-13
+
+### Changed
+
+- Add certified bundle metadata that records runtime model pins alongside build-time data artifact provenance and compatibility fingerprints.
+
+
+## [3.4.2] - 2026-04-12
+
+### Changed
+
+- Align the bundled UK release manifest with the pinned `policyengine-uk` package version and updated data package revisions.
+
+
+## [3.4.1] - 2026-04-09
+
+### Fixed
+
+- Fixed the UK paper reproduction workflow so the checked-in example runs on Python 3.14 and the associated analysis helpers handle that path cleanly.
+
+
 ## [3.4.0] - 2026-04-08
 
 ### Added

Makefile

@@ -1,9 +1,15 @@
-.PHONY: docs
+.PHONY: docs docs-serve
+
+MYSTMD_VERSION ?= 1.8.3
+MYST_CMD = npx --yes mystmd@$(MYSTMD_VERSION)
 
 all: build-package
 
 docs:
-	cd docs && npx mystmd build --html
+	cd docs && $(MYST_CMD) build --html
+
+docs-serve:
+	cd docs && $(MYST_CMD) start
 
 install:
 	uv pip install -e ".[dev]"

README.md

@@ -105,7 +105,8 @@ uv pip install -e ".[dev]"      # install with dev dependencies (pytest, ruff, m
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # run the MyST docs build used in CI via npx
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 

changelog.d/codex.paper-repro-314.fixed.md

@@ -23,7 +23,8 @@ dependencies used in CI (pytest, ruff, mypy, towncrier).
 ```bash
 make format           # ruff format
 make test             # pytest with coverage
-make docs             # run the MyST docs build used in CI via npx
+make docs             # build static MyST/Jupyter Book 2 HTML docs
+make docs-serve       # preview the docs locally
 make clean            # remove caches, build artifacts, .h5 files
 ```
 
@@ -74,6 +75,8 @@ echo "Description of change" > changelog.d/my-change.added
 
 On merge, the versioning workflow bumps the version, builds the changelog, and creates a GitHub Release.
 
+For the target release-bundle architecture, see [Release bundles](release-bundles.md). That document defines the split between country `*-data` build manifests and `policyengine.py` certified runtime bundles.
+
 ## Architecture
 
 ### Package layout

docs/dev.md

@@ -16,4 +16,5 @@ We do this by:
 - [US tax-benefit model](country-models-us.md): Entities, parameters, reform examples
 - [Examples](examples.md): Complete working scripts
 - [Visualisation](visualisation.md): Publication-ready charts with Plotly
+- [Release bundles](release-bundles.md): Reproducible model-plus-data certification and provenance
 - [Development](dev.md): Setup, testing, CI, architecture

docs/index.md

@@ -17,6 +17,7 @@ project:
     - file: country-models-us.md
     - file: examples.md
     - file: visualisation.md
+    - file: release-bundles.md
     - file: dev.md
 
 site: