Merge remote-tracking branch 'origin/main' into agent/fix-strict-sav-export

# Conflicts:
#	CHANGELOG.md
#	src/openstatspec/sql/inplace_transform.py
#	src/openstatspec/sql/wide.py
#	tests/test_atomic_import.py
#	tests/test_attribute_catalog.py
#	tests/test_loss_reports.py
#	tests/test_sql_services.py
#	tests/test_vls_compatible_names.py

Author: TonisOrmisson

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@v7
         with: &specification-checkout
           repository: OpenStatSpec/specification
-          ref: 79339ec3d8f8aa81789b7e85f6b8afa6f1374e50
+          ref: f2fdf687d8cb32b944ca55a3e9e7215ffc603019
           path: openstatspec-specification
       - name: Checkout required SPSS engine
         uses: actions/checkout@v7
@@ -143,7 +143,7 @@ jobs:
     steps: *sql-test-steps
 
   dolt-integration:
-    name: Dolt ${{ matrix.dolt }} integration
+    name: Dolt ${{ matrix.dolt }} read-only / fail-closed integration
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -217,7 +217,7 @@ jobs:
                   connection.close()
                   break
           PY
-      - run: python -m pytest -m services
+      - run: python -m pytest -m "services and not candidate_evidence"
       - name: Show Dolt logs on failure and stop server
         if: always()
         run: |

.github/workflows/release.yml

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

CHANGELOG.md

@@ -4,18 +4,53 @@ All notable changes to this reference implementation are documented here.
 
 ## Unreleased
 
+Planned adapter release: `0.5.0`, after lifecycle integration and final specification conformance.
 ### Fixed
 
 - Removed the temporary `*_catalog` compatibility schema and made SAV/ZSAV
   import, validation, export, fidelity reporting, and in-place metadata edits
   use the normative UUID-keyed OpenStatSpec catalog exclusively.
-- Existing databases that contain only the former compatibility catalog must be
-  remediated manually before export.
+- Existing databases that contain former compatibility relations must be
+  remediated manually before further operations.
 - Imports now reject dataset names that collide with normative UUID identifiers,
   cleanup drops only a physical table actually created by the failing import,
   and non-preserved SPSS compatible variable names are reported as an explicit
   loss requiring export consent.
 
+
+### Added
+
+- Added bounded typed expressions with variable references, numeric literals,
+  parentheses, `=`, `<`, `<=`, `>`, `>=`, `AND`, and `OR`. String comparison
+  and v0.2 string assignment fail closed pending exact portable semantics.
+- Added sequential SPSS-like `COMPUTE` and `IF` assignment operations plus
+  `FORMATS`, `VARIABLE LEVEL`, and `EXECUTE`.
+- Added atomic numeric target creation on SQLite and PostgreSQL. MySQL,
+  MariaDB, and Dolt fail closed on `target_mode=create`; their targets must be
+  provisioned physically and in the catalog by a separate versioned stage
+  before this executor applies assignment and metadata operations.
+- Added synthetic exact-program, catalog, failure-boundary, and pre-existing
+  target regression coverage.
+
+### Changed
+
+- Bumped the canonical transformation-plan and SPSS frontend contracts to
+  `v0.2`; canonical JSON and hashes include every sequential operation.
+- In-place apply records variable label, value labels, `F` print/write
+  format, and measurement level only in the normative catalog.
+- Dolt still requires an exact branch, exact HEAD, and clean working set;
+  successful apply leaves an inspectable diff and never calls `DOLT_COMMIT`.
+- Dolt declaration validation is implemented by the Python adapter. The
+  specification remains a language-neutral source of JSON contracts and
+  fixtures and is not installed as a Python distribution.
+
+### Specification basis
+
+- Release validation is pinned to the untagged OpenStatSpec specification
+  release candidate at immutable commit
+  `f2fdf687d8cb32b944ca55a3e9e7215ffc603019`. Its
+  `specification_release` remains null until that commit receives a stable tag.
+
 ## 0.4.0 — 2026-07-31
 
 ### Added
@@ -123,6 +158,17 @@ SPSS profile.
 - 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.
+- Read-only positive Dolt identity and working-set inspection. Operational
+  Dolt writes use adapter-owned declaration validation and remain fail-closed
+  because the adapter ships no concrete declaration claim. The specification
+  remains language-neutral and is consumed only as JSON contracts and fixtures.
+- Added explicit packaged/directory conformance-source injection and exact
+  single-match binding across active Dolt product version, adapter
+  implementation and version, and specification commit before mutation.
+- Explicit catalog initialization/migration through `initialize_catalog` and
+  `openstatspec init`; data operations never auto-create catalog relations.
+- Read-only Dolt working-set evidence through `dolt_state_snapshot` and
+  `openstatspec dolt-state`; core performs no Dolt version-control mutations.
 - Preflight checks for target profile limits, atomic imports, validation, a
   command-line interface, and machine-readable capability and loss reports.
 
@@ -135,3 +181,11 @@ SPSS profile.
 - Multiple-response sets, variable alignment, variable sets, and custom
   attributes have explicit capability diagnostics; see the SAV profile.
 - Encrypted SPSS files are not supported.
+- Dolt adapter-envelope values are not claims about Dolt server limits. Failure
+  recovery is compensating and reports deterministic residual inventory; a
+  verified catalog receives a best-effort failed-operation audit when cleanup
+  itself fails.
+- Export publication uses a durable, audit-recorded prior-file backup through
+  SQL finalization. Post-success backup retention is reported separately and
+  does not rewrite a successful export as failed; pre-success failures restore
+  the prior destination and close the running operation as failed.

README.md

@@ -67,12 +67,19 @@ implemented capability boundary.
 
 ## 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`.
+The bounded SPSS-like frontend lowers `RECODE`, sequential `COMPUTE` and `IF`,
+`VARIABLE LABELS`, `VALUE LABELS`, numeric `FORMATS`, `VARIABLE LEVEL`, and
+`EXECUTE` into a language-neutral typed canonical plan. Conditions support
+parentheses, variable and numeric literal operands, comparisons, `AND`, and
+`OR`. String comparison and v0.2 string assignment currently fail closed.
+The in-place path applies the plan to the same logical dataset, physical wide
+table, and normative/compatibility metadata without a derived dataset, copied
+table, snapshot, or hidden history layer. Numeric targets may be created
+atomically on SQLite and PostgreSQL. MySQL, MariaDB, and Dolt fail closed on
+`target_mode=create` and require a separately provisioned physical and catalog
+target before assignment. Dolt requires the caller's exact clean branch/HEAD,
+leaves success as an inspectable working-set diff, and never calls
+`DOLT_COMMIT`.
 
 See the [dataset transformations manual](docs/transformations.md) for schema
 installation, Python and CLI surfaces, database invariants, audit provenance,

docs/release-readiness.md

@@ -1,4 +1,4 @@
-# 0.4.0 release readiness
+# 0.5.0 release readiness
 
 This page records the expected release contract, not a publication event.
 Creating a version tag remains a separate maintainer action.
@@ -67,6 +67,17 @@ The gate must prove that:
 
 - a TransformationPlan object and its strict JSON mapping produce the same
   plan hash and in-place result;
+- the exact bounded `COMPUTE`/`IF` program compiles to all seven ordered
+  operations without dropping `FORMATS`, `VARIABLE LEVEL`, or `EXECUTE`;
+- boolean data results match the equivalent expression and the target's label,
+  0/1 value labels, `F1.0` print/write format, and nominal level exist in the
+  normative catalog;
+- injected schema, data, catalog, and audit failures leave no partial apply;
+- compensation tracks only newly created targets and never drops or rewrites a
+  pre-existing target;
+- MySQL, MariaDB, and Dolt reject create-target plans before mutation; their
+  service evidence covers assignment to a separately provisioned physical and
+  catalog target without schema DDL;
 - 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
@@ -78,8 +89,11 @@ The gate must prove that:
   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.
+- Dolt checks expected branch, HEAD, and a clean working set; success changes
+  neither HEAD nor branch and never commits or resets; state is rechecked after
+  the dataset lock and success must leave an inspectable working-set diff;
+  other supported SQL connections remain allowed; and
+- string comparisons and v0.2 string assignments fail closed until exact
 
 The built wheel must contain the generic openstatspec.transform modules and the
 implemented openstatspec.frontends.spss package. Stata and SAS remain empty
@@ -98,9 +112,12 @@ capability claim, or implied support.
 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`.
+6. Confirm CI, release fixtures, and capabilities use the untagged OpenStatSpec
+   specification release candidate at exact commit
+   `f2fdf687d8cb32b944ca55a3e9e7215ffc603019`, publish
+   `specification_status=release_candidate`, and leave
+   `specification_release` null. If that exact commit receives a stable tag
+   before this package is tagged, update the identity and re-run every gate.
 7. Review this document, the README, and CHANGELOG for accurate scope.
 
 The tag-triggered release workflow repeats the non-service test suite, builds

docs/transformations.md

@@ -4,8 +4,13 @@ OpenStatSpec separates transformation syntax, canonical meaning, and database
 mutation. This lets multiple language frontends produce the same plan without
 coupling the executor to any one language.
 
-The implemented frontend accepts a small SPSS-like subset: `RECODE`,
-`VARIABLE LABELS`, and `VALUE LABELS`. Stata and SAS are not implemented.
+The implemented bounded SPSS-like frontend accepts `RECODE`, sequential
+`COMPUTE` and `IF`, `VARIABLE LABELS`, `VALUE LABELS`, numeric `FORMATS`,
+`VARIABLE LEVEL`, and `EXECUTE`. Predicates support typed variable/literal
+operands, parentheses, numeric comparisons, `AND`, and `OR`. String comparison
+and v0.2 string assignment fail closed until exact profile-independent
+collation and explicit-width semantics are available; arbitrary SPSS, Python,
+and SQL expressions are rejected. Stata and SAS are not implemented.
 
 ## Architecture
 
@@ -106,9 +111,13 @@ result = openstatspec.apply_spss_in_place(
     dataset_id="responses",
     actor="agent@example.org",
     source_text="""
-      RECODE age (18 THRU 34 = 1) (35 THRU 64 = 2).
-      VARIABLE LABELS age 'Age group'.
-      VALUE LABELS age 1 '18-34' 2 '35-64'.
+      COMPUTE target = 0.
+      IF (source_a = 1 AND source_b = 1) target = 1.
+      VARIABLE LABELS target 'Example label'.
+      VALUE LABELS target 0 'No' 1 'Yes'.
+      FORMATS target (F1.0).
+      VARIABLE LEVEL target (NOMINAL).
+      EXECUTE.
     """,
 )
 ```
@@ -130,20 +139,25 @@ On Dolt, also pass `--expected-branch` and `--expected-head`.
 Every successful apply preserves the logical `dataset_id` and physical
 schema/table identity. It creates no derived dataset, output table, full-table
 copy, staging table, snapshot, rollback artifact, or recovery/history layer.
-Existing-target recodes use direct `UPDATE`; label operations mutate existing
-catalog rows.
-
-SQLite and PostgreSQL may add a numeric target where native transactions make
-the complete operation atomic. MySQL, MariaDB, and Dolt reject target-creating
-plans before the first mutation because implicit-commit DDL could leave a
-partial apply. Their target column and metadata must already exist.
-
-Dolt is the sole history, diff, branch, and rollback layer for Dolt-backed
-datasets. Before mutation, the executor verifies the expected branch and
-`HEAD` and requires clean `dolt_status`. Success changes the same working set
-without changing `HEAD`. OpenStatSpec does not call `DOLT_COMMIT`, switch
-branches, merge, reset, tag, or create a hidden recovery commit. The caller
-reviews `dolt diff` and separately decides whether to commit or restore.
+Assignments and recodes use ordered `UPDATE` statements; later operations see
+earlier results. Label, value-label, format, and measurement-level operations
+update the normative catalog.
+
+A numeric create target is supported atomically on SQLite and PostgreSQL.
+MySQL, MariaDB, and Dolt reject `target_mode=create` before mutation. On those
+profiles a separate versioned stage must first provision the nullable numeric
+physical column and normative variable row; the transformation executor then
+sees a pre-existing target and performs no schema DDL.
+The public operation reports success only after physical data, normative
+metadata, and the compact audit row are mutually complete.
+
+Before Dolt mutation, the executor verifies the expected branch and `HEAD` and
+requires clean `dolt_status`. Success changes the same working set without
+changing `HEAD`; OpenStatSpec does not call `DOLT_COMMIT`, `DOLT_RESET`, switch
+branches, merge, tag, or create a hidden recovery commit. It rechecks branch,
+HEAD, and a clean working set after locking the dataset and immediately before
+mutation. The caller reviews a successful `dolt diff` and
+separately decides whether to commit or restore.
 
 ## Audit and provenance
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openstatspec"
-version = "0.4.0"
+version = "0.5.0"
 description = "Reference adapter for the OpenStatSpec relational contract"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,7 +22,10 @@ openstatspec = "openstatspec.cli:main"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-q"
-markers = ["services: requires a configured PostgreSQL, MySQL, MariaDB, or Dolt service"]
+markers = [
+    "services: requires a configured PostgreSQL, MySQL, MariaDB, or Dolt service",
+    "candidate_evidence: non-claiming manual probe excluded from release gates",
+]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/openstatspec"]

src/openstatspec/__init__.py

@@ -2,37 +2,44 @@
 
 from .api import (
     apply_spss_in_place, apply_transformation_plan_in_place,
-    capabilities, capability_matrix, derive_sql_dataset,
-    execute_sql_transformation,
-    export_sav, get_dataset, import_sav, inspect,
-    install_in_place_transformation_schema, list_datasets,
+    capabilities, capability_matrix, derive_sql_dataset, dolt_state_snapshot, execute_sql_transformation,
+    export_sav, get_dataset, import_sav, initialize_catalog, inspect, list_datasets,
+    install_in_place_transformation_schema,
     register_sql_transformation, reconcile_derived_removals,
     reconcile_sql_transformation_runs,
     remove_derived_physical_relation, retire_derived, validate, validate_derived,
 )
 from .core import CapabilityDeclaration, LossReport, UnsupportedOperationError
-from .sql.workflow import TransformationError
 from .frontends.spss import SpssFrontendCompilation, compile_spss_syntax
+from .sql import DoltConformanceSource
+from .sql.workflow import TransformationError
 from .transform import (
+    AssignOperation, BooleanExpression, ComparisonExpression,
+    ConditionalAssignOperation, ExecuteOperation, Operand, PredicateExpression,
     RecodeMatch, RecodeOperation, RecodeResult, RecodeRule,
-    ReplaceValueLabelsOperation, SetVariableLabelOperation,
+    ReplaceValueLabelsOperation, SetFormatOperation,
+    SetMeasurementLevelOperation, SetVariableLabelOperation,
     TransformationFrontendError, TransformationPlan, TypedValue, ValueLabel,
     VariableDefinition, VariableSchema, transformation_plan_from_dict,
 )
 
 __all__ = [
-    "CapabilityDeclaration", "LossReport", "SpssFrontendCompilation",
-    "TransformationError", "TransformationFrontendError",
+    "AssignOperation", "BooleanExpression", "ComparisonExpression",
+    "ConditionalAssignOperation", "ExecuteOperation", "Operand",
+    "PredicateExpression",
+    "CapabilityDeclaration", "DoltConformanceSource", "LossReport",
+    "SpssFrontendCompilation", "TransformationError",
+    "TransformationFrontendError",
     "RecodeMatch", "RecodeOperation", "RecodeResult", "RecodeRule",
-    "ReplaceValueLabelsOperation", "SetVariableLabelOperation",
+    "ReplaceValueLabelsOperation", "SetFormatOperation",
+    "SetMeasurementLevelOperation", "SetVariableLabelOperation",
     "TransformationPlan", "TypedValue", "ValueLabel",
     "VariableDefinition", "VariableSchema", "transformation_plan_from_dict",
-    "UnsupportedOperationError", "capabilities", "capability_matrix",
     "apply_spss_in_place", "apply_transformation_plan_in_place",
-    "compile_spss_syntax", "derive_sql_dataset",
-    "execute_sql_transformation", "export_sav",
-    "get_dataset", "import_sav", "inspect",
-    "install_in_place_transformation_schema", "list_datasets",
+    "compile_spss_syntax", "install_in_place_transformation_schema",
+    "UnsupportedOperationError", "capabilities", "capability_matrix",
+    "derive_sql_dataset", "dolt_state_snapshot", "execute_sql_transformation", "export_sav", "get_dataset",
+    "import_sav", "initialize_catalog", "inspect", "list_datasets",
     "register_sql_transformation", "reconcile_derived_removals",
     "reconcile_sql_transformation_runs",
     "remove_derived_physical_relation", "retire_derived", "validate",