openstatspec 0.2.0__tar.gz → 0.4.0__tar.gz

{openstatspec-0.2.0 → openstatspec-0.4.0}/.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@v7
         with: &specification-checkout
           repository: OpenStatSpec/specification
-          ref: fef0dc6f4b17ff7141dad3f49d0524c63efbfed5
+          ref: 79339ec3d8f8aa81789b7e85f6b8afa6f1374e50
           path: openstatspec-specification
       - name: Checkout required SPSS engine
         uses: actions/checkout@v7
@@ -63,7 +63,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        postgres: ["17", "18"]
+        postgres: ["17.10", "18.4"]
     services:
       postgres:
         image: postgres:${{ matrix.postgres }}
@@ -77,6 +77,7 @@ jobs:
           --health-interval 10s --health-timeout 5s --health-retries 5
     env:
       OPENSTATSPEC_POSTGRES_URL: postgresql+psycopg://openstatspec:openstatspec@localhost:5432/openstatspec
+      OPENSTATSPEC_EXPECTED_POSTGRES_VERSION: ${{ matrix.postgres }}
     steps: &sql-test-steps
       - uses: actions/checkout@v7
       - name: Checkout OpenStatSpec specification fixtures
@@ -99,7 +100,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        mysql: ["8.4", "9.7"]
+        mysql: ["8.4.11", "9.7.2"]
     services:
       mysql:
         image: mysql:${{ matrix.mysql }}
@@ -114,6 +115,7 @@ jobs:
           --health-interval 10s --health-timeout 5s --health-retries 10
     env:
       OPENSTATSPEC_MYSQL_URL: mysql+pymysql://openstatspec:openstatspec@localhost:3306/openstatspec
+      OPENSTATSPEC_EXPECTED_MYSQL_VERSION: ${{ matrix.mysql }}
     steps: *sql-test-steps
 
   mariadb-integration:
@@ -122,7 +124,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        mariadb: ["11.4", "11.8", "12.3"]
+        mariadb: ["11.4.12", "11.8.8", "12.3.2"]
     services:
       mariadb:
         image: mariadb:${{ matrix.mariadb }}
@@ -137,13 +139,24 @@ jobs:
           --health-interval 10s --health-timeout 5s --health-retries 10
     env:
       OPENSTATSPEC_MARIADB_URL: mysql+pymysql://openstatspec:openstatspec@localhost:3306/openstatspec
+      OPENSTATSPEC_EXPECTED_MARIADB_VERSION: ${{ matrix.mariadb }}
     steps: *sql-test-steps
 
   dolt-integration:
-    name: Dolt 2.2.2 integration
+    name: Dolt ${{ matrix.dolt }} integration
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - dolt: "2.2.2"
+            image: dolthub/dolt:2.2.2@sha256:ae85afdd95317f0a982cab87fa3092a5a2e6689bc5de822ad7ae4f65b86d39a1
+          - dolt: "2.2.3"
+            image: dolthub/dolt:2.2.3@sha256:1a651e738a2e7275b9c69fec8c5f42c6e23954314405c412f4dc9287ee7c0080
     env:
       OPENSTATSPEC_DOLT_URL: mysql+pymysql://openstatspec:openstatspec@127.0.0.1:13308/openstatspec
+      OPENSTATSPEC_EXPECTED_DOLT_VERSION: ${{ matrix.dolt }}
+      OPENSTATSPEC_DOLT_IMAGE: ${{ matrix.image }}
     steps:
       - uses: actions/checkout@v7
       - name: Checkout OpenStatSpec specification fixtures
@@ -155,29 +168,29 @@ jobs:
       - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
-      - name: Initialize Dolt 2.2.2
+      - name: Initialize Dolt ${{ matrix.dolt }}
         run: |
           mkdir -p "$RUNNER_TEMP/openstatspec-dolt"
           docker run --rm \
             --volume "$RUNNER_TEMP/openstatspec-dolt:/var/lib/dolt" \
             --workdir /var/lib/dolt \
-            dolthub/dolt:2.2.2 init \
+            "$OPENSTATSPEC_DOLT_IMAGE" init \
             --name "OpenStatSpec CI" --email "ci@openstatspec.org"
           docker run --rm \
             --volume "$RUNNER_TEMP/openstatspec-dolt:/var/lib/dolt" \
             --workdir /var/lib/dolt \
-            dolthub/dolt:2.2.2 sql \
+            "$OPENSTATSPEC_DOLT_IMAGE" sql \
             -q "CREATE DATABASE openstatspec"
           docker run --rm \
             --volume "$RUNNER_TEMP/openstatspec-dolt:/var/lib/dolt" \
             --workdir /var/lib/dolt \
-            dolthub/dolt:2.2.2 sql \
+            "$OPENSTATSPEC_DOLT_IMAGE" sql \
             -q "CREATE USER 'openstatspec'@'%' IDENTIFIED BY 'openstatspec'; GRANT ALL PRIVILEGES ON openstatspec.* TO 'openstatspec'@'%'"
           docker run --detach --name openstatspec-dolt \
             --publish 127.0.0.1:13308:3306 \
             --volume "$RUNNER_TEMP/openstatspec-dolt:/var/lib/dolt" \
             --workdir /var/lib/dolt \
-            dolthub/dolt:2.2.2 sql-server -H 0.0.0.0 -l warning
+            "$OPENSTATSPEC_DOLT_IMAGE" sql-server -H 0.0.0.0 -l warning
       - run: python -m pip install --upgrade pip
       - run: python -m pip install ./openstatspec-pyspssio
       - run: python -m pip install -e ".[dev,sql]"

{openstatspec-0.2.0 → openstatspec-0.4.0}/.github/workflows/release.yml

@@ -47,7 +47,7 @@ jobs:
         uses: actions/checkout@v7
         with:
           repository: OpenStatSpec/specification
-          ref: fef0dc6f4b17ff7141dad3f49d0524c63efbfed5
+          ref: 79339ec3d8f8aa81789b7e85f6b8afa6f1374e50
           path: openstatspec-specification
       - name: Checkout required SPSS engine
         uses: actions/checkout@v7

openstatspec-0.4.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to this reference implementation are documented here.
+
+## 0.4.0 — 2026-07-31
+
+### Added
+
+- Added a public canonical transformation-plan in-place API accepting either
+  typed plan objects or strictly validated mappings.
+- Added apply-plan and install-in-place-schema CLI workflows alongside the
+  compatible apply-spss command.
+- Added explicit audit provenance distinguishing canonical plan documents from
+  SPSS syntax sources.
+- Added a transformation manual covering the canonical core, frontend boundary,
+  execution invariants, CLI/API workflows, and extension rules.
+
+### Changed
+
+- Moved the SPSS parser, binder, compiler, and convenience execution adapter to
+  the dedicated openstatspec.frontends.spss package.
+- Kept openstatspec.transform language-neutral with canonical plan, schema, and
+  live-schema validation modules while preserving previous SPSS import paths.
+- Reserved empty Stata and SAS frontend directories without exposing parsers,
+  capabilities, CLI choices, or support claims.
+- Strengthened pre-mutation target-type checks and target-scoped physical table
+  identity guards. The executor continues to modify the same dataset and table
+  without creating OpenStatSpec rollback, copy, snapshot, or history layers.
+
+### Specification basis
+
+- Conformance and release validation continue to use OpenStatSpec specification
+  release v0.2.0 at exact commit
+  79339ec3d8f8aa81789b7e85f6b8afa6f1374e50.
+
+## 0.3.0 — 2026-07-31
+
+### Added
+
+- Added a bounded SPSS-like `RECODE`, `VARIABLE LABELS`, and `VALUE LABELS`
+  parser with stable diagnostics and conformance fixtures.
+- Added canonical Transformation Plan serialization, RFC 8785 hashes, schema
+  binding, deterministic typed operations, and an agent-facing CLI/API.
+- Added product-neutral in-place execution with same dataset/table identity,
+  direct data and metadata mutation, and compact operation audit. Dolt adds
+  expected branch/HEAD and clean-working-set checks.
+
+### Changed
+
+- Version history, diff, rollback, restoration, and commit remain database
+  responsibilities; the transformer creates no derived/copy/snapshot/recovery
+  layer and performs no `DOLT_COMMIT`.
+- SQL server support now distinguishes conservative family claims from exact
+  CI evidence: PostgreSQL 17.x/18.x at 17.10/18.4, MySQL 8.4.x/9.7.x at
+  8.4.11/9.7.2, and MariaDB 11.4.x/11.8.x/12.3.x at
+  11.4.12/11.8.8/12.3.2. Each service job verifies the live normalized version.
+- Dolt remains an independent core profile, now claiming canonical stable
+  versions `>=2.2.2,<2.3.0` and running its complete service suite at exact
+  versions 2.2.2 and 2.2.3 from immutable container-image pins.
+  SQLite retains its core `>=3.24.0,<4.0.0` and optional workflow
+  `>=3.35.0,<4.0.0` tiers. MSSQL remains unsupported and roadmap-only.
+
+### Specification basis
+
+- CI, release validation, and machine-readable capabilities use OpenStatSpec
+  specification release `v0.2.0` at exact commit
+  `79339ec3d8f8aa81789b7e85f6b8afa6f1374e50`.
+
+## 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 release
+  `v1.0.0-rc.1` at exact commit
+  `fef0dc6f4b17ff7141dad3f49d0524c63efbfed5`.
+
+## 0.1.0 — 2026-07-29
+
+First public reference implementation of the OpenStatSpec strict wide-table
+SPSS profile.
+
+### Included
+
+- 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.
+- 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.
+
+### Important boundaries
+
+- This release promises semantic round-trip equivalence only for supported
+  features; it never promises byte-identical SAV/ZSAV output.
+- The adapter requires explicit `allow_loss` consent before exporting known
+  unsupported or lossy dictionary semantics.
+- Multiple-response sets, variable alignment, variable sets, and custom
+  attributes have explicit capability diagnostics; see the SAV profile.
+- Encrypted SPSS files are not supported.

{openstatspec-0.2.0 → openstatspec-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openstatspec
-Version: 0.2.0
+Version: 0.4.0
 Summary: Reference adapter for the OpenStatSpec relational contract
 Author: OpenStatSpec
 License: Apache-2.0
@@ -45,6 +45,10 @@ import.
   capabilities, and loss reports.
 - `openstatspec.sql`: database connection and wide-table/catalog operations.
 - `openstatspec.spss`: SAV/ZSAV adapter boundary.
+- `openstatspec.transform`: canonical plans, frontend-neutral schema concepts,
+  and plan validation.
+- `openstatspec.frontends.spss`: the SPSS-like syntax frontend and convenience
+  execution adapter.
 
 ## Intended workflow
 
@@ -69,12 +73,32 @@ derived datasets through a public catalog API. It uses a separate profile
 catalog and never presents SQL output as an imported source dataset.
 Workflow operations support SQLite only in this milestone and fail closed on
 PostgreSQL/MySQL/MariaDB; core import/export database support is unchanged.
+The core SQLite import/export profile accepts SQLite `>=3.24.0,<4.0.0`; the
+optional transformation workflow deliberately has the narrower
+`>=3.35.0,<4.0.0` runtime preflight. These independent tiers do not change the
+server-profile matrix. Microsoft SQL Server is not supported; its future
+dialect is scoped only in the specification's
+[MSSQL roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
 
 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.2.0 support status
+## SPSS-like transformation frontend
+
+The SPSS-like frontend lowers supported `RECODE`, `VARIABLE LABELS`, and
+`VALUE LABELS` syntax into a language-neutral canonical plan. The in-place
+path applies it to the same logical dataset, physical wide table, and metadata
+catalog without a derived dataset, copied table, snapshot, or separate
+rollback/history layer. Dolt remains the sole versioning layer for Dolt-backed
+edits, and the transformer never calls `DOLT_COMMIT`.
+
+See the [dataset transformations manual](docs/transformations.md) for schema
+installation, Python and CLI surfaces, database invariants, audit provenance,
+package layout, and extension guidance. Stata and SAS are unimplemented
+placeholders.
+
+## Current 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
@@ -82,13 +106,36 @@ in operation metadata. There is no fallback reader or writer. It supports unencr
 SAV/ZSAV export for the semantics exposed by that engine. SQLite is the local
 reference path.
 PostgreSQL, MySQL, MariaDB, and Dolt are each covered by separate service-backed CI
-conformance checks. Dolt support is an independent core profile pinned to 2.2.2;
-other Dolt versions and unknown MySQL-wire products fail closed. Use these explicit SQLAlchemy URLs:
+conformance checks. Dolt support is an independent core profile for the
+canonical stable range `>=2.2.2,<2.3.0`; earlier patches, other families,
+noncanonical versions, and unknown MySQL-wire products fail closed.
+
+The supported family claims are broader than the deliberately exact CI
+evidence points: PostgreSQL 17.x/18.x is exercised at 17.10/18.4, MySQL
+8.4.x/9.7.x at 8.4.11/9.7.2, and MariaDB 11.4.x/11.8.x/12.3.x at
+11.4.12/11.8.8/12.3.2. Each service job checks the normalized live server
+version against its exact matrix entry before that run can count as evidence.
+Dolt claims the conservative 2.2.x range `>=2.2.2,<2.3.0`; its full service
+suite is exercised independently at exact versions 2.2.2 and 2.2.3 using
+immutable container-image digests.
+
+| Engine/profile | Runtime supported policy | Exact CI-tested versions |
+| --- | --- | --- |
+| SQLite core / optional workflow | Core `>=3.24.0,<4.0.0`; optional workflow `>=3.35.0,<4.0.0` | Runtime-provided SQLite on Python 3.11–3.14 runners; not a pinned server image |
+| PostgreSQL | 17.x and 18.x | 17.10 and 18.4 |
+| MySQL | 8.4.x and 9.7.x | 8.4.11 and 9.7.2 |
+| MariaDB | 11.4.x, 11.8.x, and 12.3.x | 11.4.12, 11.8.8, and 12.3.2 |
+| Dolt | 2.2.x with `>=2.2.2,<2.3.0` | 2.2.2 and 2.2.3 |
+
+Microsoft SQL Server (MSSQL) remains roadmap-only and is not a supported
+runtime profile; see the specification's [MSSQL roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
+
+Use these explicit SQLAlchemy URLs:
 
 - SQLite: `sqlite:///dataset.sqlite`
 - PostgreSQL: `postgresql+psycopg://user:password@host/database`
 - MySQL/MariaDB: `mysql+pymysql://user:password@host/database`
-- Dolt 2.2.2: `mysql+pymysql://user:password@host/database` (detected by server identity)
+- Dolt `>=2.2.2,<2.3.0`: `mysql+pymysql://user:password@host/database` (detected by server identity)
 
 The Dolt core profile supports strict wide-table import, validation, and export;
 the separate Transformation Workflow is unsupported.

{openstatspec-0.2.0 → openstatspec-0.4.0}/README.md

@@ -26,6 +26,10 @@ import.
   capabilities, and loss reports.
 - `openstatspec.sql`: database connection and wide-table/catalog operations.
 - `openstatspec.spss`: SAV/ZSAV adapter boundary.
+- `openstatspec.transform`: canonical plans, frontend-neutral schema concepts,
+  and plan validation.
+- `openstatspec.frontends.spss`: the SPSS-like syntax frontend and convenience
+  execution adapter.
 
 ## Intended workflow
 
@@ -50,12 +54,32 @@ derived datasets through a public catalog API. It uses a separate profile
 catalog and never presents SQL output as an imported source dataset.
 Workflow operations support SQLite only in this milestone and fail closed on
 PostgreSQL/MySQL/MariaDB; core import/export database support is unchanged.
+The core SQLite import/export profile accepts SQLite `>=3.24.0,<4.0.0`; the
+optional transformation workflow deliberately has the narrower
+`>=3.35.0,<4.0.0` runtime preflight. These independent tiers do not change the
+server-profile matrix. Microsoft SQL Server is not supported; its future
+dialect is scoped only in the specification's
+[MSSQL roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
 
 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.2.0 support status
+## SPSS-like transformation frontend
+
+The SPSS-like frontend lowers supported `RECODE`, `VARIABLE LABELS`, and
+`VALUE LABELS` syntax into a language-neutral canonical plan. The in-place
+path applies it to the same logical dataset, physical wide table, and metadata
+catalog without a derived dataset, copied table, snapshot, or separate
+rollback/history layer. Dolt remains the sole versioning layer for Dolt-backed
+edits, and the transformer never calls `DOLT_COMMIT`.
+
+See the [dataset transformations manual](docs/transformations.md) for schema
+installation, Python and CLI surfaces, database invariants, audit provenance,
+package layout, and extension guidance. Stata and SAS are unimplemented
+placeholders.
+
+## Current 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
@@ -63,13 +87,36 @@ in operation metadata. There is no fallback reader or writer. It supports unencr
 SAV/ZSAV export for the semantics exposed by that engine. SQLite is the local
 reference path.
 PostgreSQL, MySQL, MariaDB, and Dolt are each covered by separate service-backed CI
-conformance checks. Dolt support is an independent core profile pinned to 2.2.2;
-other Dolt versions and unknown MySQL-wire products fail closed. Use these explicit SQLAlchemy URLs:
+conformance checks. Dolt support is an independent core profile for the
+canonical stable range `>=2.2.2,<2.3.0`; earlier patches, other families,
+noncanonical versions, and unknown MySQL-wire products fail closed.
+
+The supported family claims are broader than the deliberately exact CI
+evidence points: PostgreSQL 17.x/18.x is exercised at 17.10/18.4, MySQL
+8.4.x/9.7.x at 8.4.11/9.7.2, and MariaDB 11.4.x/11.8.x/12.3.x at
+11.4.12/11.8.8/12.3.2. Each service job checks the normalized live server
+version against its exact matrix entry before that run can count as evidence.
+Dolt claims the conservative 2.2.x range `>=2.2.2,<2.3.0`; its full service
+suite is exercised independently at exact versions 2.2.2 and 2.2.3 using
+immutable container-image digests.
+
+| Engine/profile | Runtime supported policy | Exact CI-tested versions |
+| --- | --- | --- |
+| SQLite core / optional workflow | Core `>=3.24.0,<4.0.0`; optional workflow `>=3.35.0,<4.0.0` | Runtime-provided SQLite on Python 3.11–3.14 runners; not a pinned server image |
+| PostgreSQL | 17.x and 18.x | 17.10 and 18.4 |
+| MySQL | 8.4.x and 9.7.x | 8.4.11 and 9.7.2 |
+| MariaDB | 11.4.x, 11.8.x, and 12.3.x | 11.4.12, 11.8.8, and 12.3.2 |
+| Dolt | 2.2.x with `>=2.2.2,<2.3.0` | 2.2.2 and 2.2.3 |
+
+Microsoft SQL Server (MSSQL) remains roadmap-only and is not a supported
+runtime profile; see the specification's [MSSQL roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
+
+Use these explicit SQLAlchemy URLs:
 
 - SQLite: `sqlite:///dataset.sqlite`
 - PostgreSQL: `postgresql+psycopg://user:password@host/database`
 - MySQL/MariaDB: `mysql+pymysql://user:password@host/database`
-- Dolt 2.2.2: `mysql+pymysql://user:password@host/database` (detected by server identity)
+- Dolt `>=2.2.2,<2.3.0`: `mysql+pymysql://user:password@host/database` (detected by server identity)
 
 The Dolt core profile supports strict wide-table import, validation, and export;
 the separate Transformation Workflow is unsupported.

openstatspec-0.4.0/docs/in-place-transformation.md

@@ -0,0 +1,9 @@
+# In-place transformations
+
+This page has moved to the comprehensive
+[dataset transformations manual](transformations.md).
+
+The manual covers the canonical plan, SPSS-like frontend, executor, audit
+schema, Python and CLI surfaces, database and Dolt invariants, provenance,
+package layout, and future frontend boundary. Stata and SAS remain
+unimplemented placeholders.

openstatspec-0.4.0/docs/release-readiness.md

@@ -0,0 +1,110 @@
+# 0.4.0 release readiness
+
+This page records the expected release contract, not a publication event.
+Creating a version tag remains a separate maintainer action.
+
+## Supported workflow
+
+For a supported unencrypted SAV or ZSAV source, the adapter imports one source
+dataset into exactly one dedicated wide data table plus the complete singular,
+UUID-keyed normative catalog from the SPSS profile. It can validate that
+representation and export it back to SAV or ZSAV. Historical `*_catalog`
+tables remain private compatibility storage and do not replace the normative
+database contract.
+
+## SQL profiles
+
+| Profile | Connection URL | Claimed versions | Exact CI evidence |
+| --- | --- | --- | --- |
+| SQLite | `sqlite:///dataset.sqlite` | `>=3.24.0,<4.0.0` | Active Python 3.11–3.14 runner version |
+| PostgreSQL | `postgresql+psycopg://…` | 17.x and 18.x | 17.10 and 18.4 |
+| MySQL | `mysql+pymysql://…` | 8.4.x and 9.7.x | 8.4.11 and 9.7.2 |
+| MariaDB | `mysql+pymysql://…` | 11.4.x, 11.8.x, and 12.3.x | 11.4.12, 11.8.8, and 12.3.2 |
+| Dolt | `mysql+pymysql://…` | 2.2.x with `>=2.2.2,<2.3.0` | 2.2.2 and 2.2.3 |
+
+Separate service matrices test the shared MySQL/MariaDB profile contract while
+retaining distinct active-server identities and version claims. Dolt is an
+independent core profile that accepts only canonical stable versions in
+`>=2.2.2,<2.3.0`; 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.
+Every server service job compares the normalized live product version with its
+exact matrix entry, so a moved or mismatched image cannot substantiate the CI
+declaration. SQLite's optional Transformation Workflow retains its narrower
+`>=3.35.0,<4.0.0` live preflight alongside the core `>=3.24.0,<4.0.0` policy.
+Microsoft SQL Server remains unsupported and must not appear in runtime
+capabilities; future implementation requirements are documented in the
+specification's
+[MSSQL dialect roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
+
+
+## Export-loss policy
+
+`capability_matrix()` and `openstatspec capabilities` expose the current
+feature state. Before export, the adapter combines source and writer
+diagnostics. An export with known loss fails unless the caller passes the
+relevant diagnostic codes through `allow_loss` or repeats `--allow-loss CODE`
+in the CLI.
+
+The concrete pyspssio boundaries are documented in the [SAV profile](sav-profile.md).
+The pinned OpenStatSpec fork preserves document text, file labels, legacy
+compatible names, separate print/write formats, variable sets,
+multiple-response sets, alignment, scalar attributes, and ordered
+custom-attribute arrays. Non-UTF-8 output requires an explicit matching locale;
+otherwise the strict export policy reports and blocks the loss. A caller
+that supplies consent for an available loss code receives the
+machine-readable loss report with the export result.
+
+## Transformation release gates
+
+The canonical transformation core and SPSS syntax frontend are separate public
+surfaces. A release must run the specification-owned canonical-plan and SPSS
+frontend conformance fixtures, then exercise both the generic plan apply API
+and the SPSS compatibility apply path.
+
+The gate must prove that:
+
+- a TransformationPlan object and its strict JSON mapping produce the same
+  plan hash and in-place result;
+- top-level SPSS compiler imports and legacy openstatspec.transform re-exports
+  still load from an installed wheel;
+- install-in-place-schema, apply-plan, and apply-spss execute their documented
+  CLI workflows;
+- invalid or unsupported plans fail before the first data or metadata mutation;
+- successful applies retain the same dataset ID, physical schema/table
+  identity, dataset count, and persistent physical data-table count;
+- audit rows distinguish canonical plans from SPSS syntax, preserve correct
+  source/plan hashes and frontend contract, and contain no copied data;
+- no OpenStatSpec rollback, snapshot, staging, copy, derived-dataset, or
+  parallel history artifacts are created; and
+- Dolt checks expected branch, HEAD, and a clean working set without committing
+  or changing HEAD; other supported SQL connections remain allowed.
+
+The built wheel must contain the generic openstatspec.transform modules and the
+implemented openstatspec.frontends.spss package. Stata and SAS remain empty
+source-tree placeholders and must expose no compiler, apply API, CLI choice,
+capability claim, or implied support.
+
+## Maintainer checks before tagging
+
+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 -m "not services"`.
+3. Confirm the GitHub Actions matrix is green for exact PostgreSQL 17.10/18.4,
+   MySQL 8.4.11/9.7.2, MariaDB 11.4.12/11.8.8/12.3.2, and exact Dolt
+   2.2.2/2.2.3 service evidence from the immutable image pins in CI.
+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. Confirm the release tag matches the package version and that CI, release
+   fixtures, and capabilities use OpenStatSpec specification release `v0.2.0`
+   at exact commit `79339ec3d8f8aa81789b7e85f6b8afa6f1374e50`.
+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
+in a clean environment before it can reach the protected `pypi` environment.
+It fails closed if that exact engine version is not already downloadable from
+PyPI, preventing publication of an uninstallable OpenStatSpec release.

{openstatspec-0.2.0 → openstatspec-0.4.0}/docs/sav-profile.md

@@ -15,12 +15,27 @@ unencrypted .sav and .zsav files, and writes both formats through the same imple
 
 SQLite has a local reference fixture. PostgreSQL, MySQL, MariaDB, and Dolt have
 separate service-backed conformance checks in GitHub Actions that import,
-validate, and export the supported fixture. Dolt is an independent core profile
-pinned to exact server version 2.2.2 and detected over `mysql+pymysql` by active
-server identity; other Dolt versions and unknown MySQL-wire products fail closed.
-The core Dolt profile does not claim support for the separate Transformation
-Workflow. An import that exceeds a target's strict single-table column or row
-envelope fails before it creates a dataset.
+validate, and export the supported fixture. The family claims and exact CI
+points are PostgreSQL 17.x/18.x at 17.10/18.4, MySQL 8.4.x/9.7.x at
+8.4.11/9.7.2, and MariaDB 11.4.x/11.8.x/12.3.x at
+11.4.12/11.8.8/12.3.2. CI compares each live normalized server version with
+that exact evidence point.
+
+Dolt is an independent core profile for canonical stable versions in
+`>=2.2.2,<2.3.0`, detected over `mysql+pymysql` by active server identity and
+service-tested at exact versions 2.2.2 and 2.2.3. Earlier patches, other
+families, noncanonical versions, and unknown MySQL-wire products fail closed.
+The core Dolt profile does not
+claim support for the separate Transformation Workflow. An import that exceeds
+a target's strict single-table column or row envelope fails before it creates a
+dataset.
+
+The core SQLite profile remains `>=3.24.0,<4.0.0`; only the optional
+Transformation Workflow requires `>=3.35.0,<4.0.0`. Microsoft SQL Server is
+not a supported profile. Its driver, SQL-difference, preflight, CI,
+conformance, security, and atomicity work is future scope in the
+specification's
+[MSSQL dialect roadmap](https://github.com/OpenStatSpec/specification/blob/main/docs/mssql-dialect-roadmap.md).
 
 ## Fidelity contract