Prepare Python 0.2.0 release

Author: TonisOrmisson

.github/verify_release_ref.py

@@ -0,0 +1,63 @@
+"""Fail closed unless the requested release tag names HEAD and the package version."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tomllib
+
+
+def _git(*arguments: str) -> str:
+    completed = subprocess.run(
+        ["git", *arguments],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if completed.returncode:
+        detail = completed.stderr.strip() or completed.stdout.strip()
+        raise RuntimeError(detail or f"git {' '.join(arguments)} failed")
+    return completed.stdout.strip()
+
+
+def verify_release_ref() -> None:
+    release_tag = os.environ.get("RELEASE_TAG", "")
+    version = str(
+        tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"]
+    )
+    expected_tag = f"v{version}"
+    if release_tag != expected_tag:
+        raise RuntimeError(
+            f"release tag {release_tag!r} does not match package version {version!r}"
+        )
+
+    tag_ref = f"refs/tags/{release_tag}"
+    exists = subprocess.run(
+        ["git", "show-ref", "--verify", "--quiet", tag_ref],
+        check=False,
+    )
+    if exists.returncode:
+        raise RuntimeError(f"release tag ref {tag_ref!r} does not exist")
+
+    tag_commit = _git("rev-parse", "--verify", f"{tag_ref}^{{commit}}")
+    head_commit = _git("rev-parse", "--verify", "HEAD^{commit}")
+    if tag_commit != head_commit:
+        raise RuntimeError(
+            f"release tag {release_tag!r} resolves to {tag_commit}, not HEAD {head_commit}"
+        )
+
+
+def main() -> int:
+    try:
+        verify_release_ref()
+    except (KeyError, OSError, RuntimeError, tomllib.TOMLDecodeError) as error:
+        print(f"release ref verification failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.github/workflows/release.yml

@@ -23,10 +23,18 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ inputs.release_ref || github.ref }}
+          ref: refs/tags/${{ inputs.release_ref || github.ref_name }}
+          fetch-depth: 0
       - uses: actions/setup-python@v7
         with:
           python-version: "3.13"
+      - name: Verify release tag exists and targets this package version
+        env:
+          RELEASE_TAG: ${{ inputs.release_ref || github.ref_name }}
+        run: |
+          set -eu
+          git fetch --force --no-tags origin "refs/tags/${RELEASE_TAG}:refs/tags/${RELEASE_TAG}"
+          python .github/verify_release_ref.py
       - run: python -m pip install --upgrade pip build
       - name: Verify required SPSS engine is publicly installable
         run: >-

CHANGELOG.md

@@ -2,7 +2,37 @@
 
 All notable changes to this reference implementation are documented here.
 
-## 0.1.0 — unreleased
+## 0.2.0 — 2026-07-30
+
+This release extends the reference adapter while keeping imported source
+datasets immutable and all unsupported paths fail-closed.
+
+### Added
+
+- An optional SQLite-only Transformation Workflow for immutable, versioned,
+  parameterized SELECT definitions; materialized derived datasets; lineage and
+  weights; public catalog APIs; and CLI operations.
+- An independent Dolt core SQL profile for exact product version 2.2.2, with
+  service-backed coverage, conservative adapter limits, complete compensating
+  cleanup, and pre-DDL rejection of unsupported values. Transformation Workflow
+  support on Dolt is not claimed.
+
+### Changed
+
+- SAV and ZSAV validation now rewrites legacy compatible names consistently
+  across type-2 records and subtype-13/subtype-14 long-name metadata.
+- Transformation publication, interrupted-run reconciliation, retirement, and
+  physical-removal recovery now preserve auditable state and fail closed on
+  catalog or relation drift.
+- Release automation builds distributions before test-only source checkouts and
+  supports idempotent rebuilds of an existing release tag.
+
+### Specification basis
+
+- CI and release validation are pinned to OpenStatSpec specification commit
+  `34141dda023d9e0217c37c232e39f436edfb0746`; no specification tag is claimed.
+
+## 0.1.0 — 2026-07-29
 
 First public reference implementation of the OpenStatSpec strict wide-table
 SPSS profile.
@@ -12,11 +42,8 @@ SPSS profile.
 - Import of unencrypted SAV and ZSAV sources into one dedicated wide SQL table
   and its metadata catalog.
 - Export of supported dataset semantics to SAV and ZSAV.
-- Consistent legacy compatible-name rewriting across type-2, subtype-13, and
-  VLS subtype-14 records, with fail-closed SAV/ZSAV validation.
-- SQLite, PostgreSQL, MySQL, MariaDB, and independent Dolt profiles, including
-  service-backed PostgreSQL 17/18, MySQL 8.4/9.7, MariaDB 11.4/11.8/12.3, and
-  pinned Dolt 2.2.2 CI coverage. Dolt Transformation Workflow support is not claimed.
+- SQLite, PostgreSQL, MySQL, and MariaDB profiles, including service-backed
+  PostgreSQL 17/18, MySQL 8.4/9.7, and MariaDB 11.4/11.8/12.3 CI coverage.
 - Preflight checks for target profile limits, atomic imports, validation, a
   command-line interface, and machine-readable capability and loss reports.
 

README.md

@@ -55,7 +55,7 @@ See [the SQL transformation workflow](docs/sql-transformation-workflow.md) for
 Python and CLI examples, migration behavior, hashing, atomicity, and the exact
 implemented capability boundary.
 
-## 0.1.0 support status
+## 0.2.0 support status
 
 The adapter requires `openstatspec-pyspssio==0.5.1.post2` as its sole SPSS
 engine. Its import module remains `pyspssio`; the exact source commit is recorded

docs/release-readiness.md

@@ -1,4 +1,4 @@
-# 0.1.0 release readiness
+# 0.2.0 release readiness
 
 This page records the expected release contract, not a publication event.
 Creating a version tag remains a separate maintainer action.
@@ -20,9 +20,12 @@ database contract.
 | PostgreSQL | `postgresql+psycopg://…` | PostgreSQL 17 and 18 service jobs |
 | MySQL | `mysql+pymysql://…` | MySQL 8.4 and 9.7 service jobs |
 | MariaDB | `mysql+pymysql://…` | MariaDB 11.4, 11.8, and 12.3 service jobs |
+| Dolt | `mysql+pymysql://…` | Exact Dolt 2.2.2 service job |
 
 Separate service matrices test the shared MySQL/MariaDB profile contract while
-retaining distinct active-server identities and version claims. This does not
+retaining distinct active-server identities and version claims. Dolt is an
+independent core profile that fails closed unless the product version is exactly
+2.2.2; the optional Transformation Workflow remains SQLite-only. This does not
 claim coverage for every server configuration. The machine-readable capability
 declaration reports both the theoretical profile boundaries and effective
 limits observed from the active connection.
@@ -49,13 +52,16 @@ machine-readable loss report with the export result.
 1. Publish the pinned `openstatspec-pyspssio==0.5.1.post2` engine distribution
    first and confirm that a clean environment can download it from PyPI. The
    main package has no fallback SPSS engine.
-2. Run `python -m pytest`.
+2. Run `python -m pytest -m "not services"`.
 3. Confirm the GitHub Actions matrix is green for PostgreSQL 17/18, MySQL
-   8.4/9.7, and MariaDB 11.4/11.8/12.3.
+   8.4/9.7, MariaDB 11.4/11.8/12.3, and exact Dolt 2.2.2.
 4. Build with `python -m build` and install the generated wheel in a clean
    environment.
 5. Confirm `openstatspec capabilities` reflects the intended support boundary.
-6. Review this document, the README, and CHANGELOG for accurate scope.
+6. Confirm the `v0.2.0` tag matches package version `0.2.0`, and that CI and
+   release fixtures use specification commit
+   `34141dda023d9e0217c37c232e39f436edfb0746`.
+7. Review this document, the README, and CHANGELOG for accurate scope.
 
 The tag-triggered release workflow repeats the non-service test suite, builds
 the distributions, and installs the wheel with the exact required SPSS engine

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openstatspec"
-version = "0.1.0"
+version = "0.2.0"
 description = "Reference adapter for the OpenStatSpec relational contract"
 readme = "README.md"
 requires-python = ">=3.11"

tests/test_release_ref.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+VERIFY_RELEASE_REF = Path(__file__).parents[1] / ".github" / "verify_release_ref.py"
+
+
+def _git(repository: Path, *arguments: str) -> str:
+    completed = subprocess.run(
+        ["git", *arguments],
+        cwd=repository,
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    return completed.stdout.strip()
+
+
+def _repository(tmp_path: Path) -> Path:
+    repository = tmp_path / "repository"
+    repository.mkdir()
+    _git(repository, "init", "--quiet")
+    _git(repository, "config", "user.name", "Release Test")
+    _git(repository, "config", "user.email", "release@example.invalid")
+    (repository / "pyproject.toml").write_text(
+        '[project]\nname = "openstatspec"\nversion = "0.2.0"\n',
+        encoding="utf-8",
+    )
+    _git(repository, "add", "pyproject.toml")
+    _git(repository, "commit", "--quiet", "-m", "fixture")
+    return repository
+
+
+def _verify(repository: Path, release_tag: str) -> subprocess.CompletedProcess[str]:
+    environment = os.environ.copy()
+    environment["RELEASE_TAG"] = release_tag
+    return subprocess.run(
+        [sys.executable, str(VERIFY_RELEASE_REF)],
+        cwd=repository,
+        env=environment,
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+def test_release_ref_accepts_annotated_version_tag_at_head(tmp_path: Path) -> None:
+    repository = _repository(tmp_path)
+    _git(repository, "tag", "-a", "v0.2.0", "-m", "release")
+
+    assert _verify(repository, "v0.2.0").returncode == 0
+
+
+def test_release_ref_rejects_branch_with_version_name(tmp_path: Path) -> None:
+    repository = _repository(tmp_path)
+    _git(repository, "branch", "v0.2.0")
+
+    result = _verify(repository, "v0.2.0")
+
+    assert result.returncode == 1
+    assert "does not exist" in result.stderr
+
+
+def test_release_ref_rejects_commit_sha_input(tmp_path: Path) -> None:
+    repository = _repository(tmp_path)
+
+    result = _verify(repository, _git(repository, "rev-parse", "HEAD"))
+
+    assert result.returncode == 1
+    assert "does not match package version" in result.stderr
+
+
+def test_release_ref_rejects_missing_version_tag(tmp_path: Path) -> None:
+    repository = _repository(tmp_path)
+
+    result = _verify(repository, "v0.2.0")
+
+    assert result.returncode == 1
+    assert "does not exist" in result.stderr
+
+
+def test_release_ref_rejects_tag_targeting_another_commit(tmp_path: Path) -> None:
+    repository = _repository(tmp_path)
+    _git(repository, "tag", "-a", "v0.2.0", "-m", "release")
+    (repository / "README.md").write_text("later commit\n", encoding="utf-8")
+    _git(repository, "add", "README.md")
+    _git(repository, "commit", "--quiet", "-m", "later")
+
+    result = _verify(repository, "v0.2.0")
+
+    assert result.returncode == 1
+    assert "not HEAD" in result.stderr