openstatspec 0.4.0__tar.gz → 0.5.0__tar.gz

{openstatspec-0.4.0 → openstatspec-0.5.0}/.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: |

{openstatspec-0.4.0 → openstatspec-0.5.0}/.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

{openstatspec-0.4.0 → openstatspec-0.5.0}/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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 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
@@ -109,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.
 
@@ -121,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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openstatspec
-Version: 0.4.0
+Version: 0.5.0
 Summary: Reference adapter for the OpenStatSpec relational contract
 Author: OpenStatSpec
 License: Apache-2.0
@@ -30,10 +30,10 @@ For each supported import, one source dataset becomes one dedicated wide SQL
 table. Cases are rows and source variables are physical SQL columns. The
 singular UUID-keyed tables from the specification (`dataset`, `variable`,
 `operation`, `fidelity_event`, and related metadata tables) are the public
-catalog contract. Historical `*_catalog` tables are an internal compatibility
-layer for the current exporter and are not the standard database interface.
-The adapter does not reshape data, create EAV
-or long-form tables, or harmonize studies or waves.
+catalog contract and the only catalog representation created or read by the
+adapter. Databases created with the former `*_catalog` compatibility schema
+must be remediated to the normative schema before use. The adapter does not
+reshape data, create EAV or long-form tables, or harmonize studies or waves.
 
 Unsupported source features, SQL targets, or export paths fail explicitly.
 There is no silent truncation, type conversion, metadata loss, or partial
@@ -86,12 +86,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,

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

@@ -11,10 +11,10 @@ For each supported import, one source dataset becomes one dedicated wide SQL
 table. Cases are rows and source variables are physical SQL columns. The
 singular UUID-keyed tables from the specification (`dataset`, `variable`,
 `operation`, `fidelity_event`, and related metadata tables) are the public
-catalog contract. Historical `*_catalog` tables are an internal compatibility
-layer for the current exporter and are not the standard database interface.
-The adapter does not reshape data, create EAV
-or long-form tables, or harmonize studies or waves.
+catalog contract and the only catalog representation created or read by the
+adapter. Databases created with the former `*_catalog` compatibility schema
+must be remediated to the normative schema before use. The adapter does not
+reshape data, create EAV or long-form tables, or harmonize studies or waves.
 
 Unsupported source features, SQL targets, or export paths fail explicitly.
 There is no silent truncation, type conversion, metadata loss, or partial
@@ -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,

{openstatspec-0.4.0 → openstatspec-0.5.0}/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

{openstatspec-0.4.0 → openstatspec-0.5.0}/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
 

{openstatspec-0.4.0 → openstatspec-0.5.0}/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"]

openstatspec-0.5.0/src/openstatspec/__init__.py

@@ -0,0 +1,48 @@
+"""Public API for the OpenStatSpec Python reference implementation."""
+
+from .api import (
+    apply_spss_in_place, apply_transformation_plan_in_place,
+    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 .frontends.spss import SpssFrontendCompilation, compile_spss_syntax
+from .sql import DoltConformanceSource
+from .sql.workflow import TransformationError
+from .transform import (
+    AssignOperation, BooleanExpression, ComparisonExpression,
+    ConditionalAssignOperation, CreateVariableOperation, DeleteVariableOperation,
+    ExecuteOperation, Operand, PredicateExpression,
+    RecodeMatch, RecodeOperation, RecodeResult, RecodeRule,
+    ReplaceValueLabelsOperation, SetFormatOperation,
+    SetMeasurementLevelOperation, SetVariableLabelOperation,
+    TransformationFrontendError, TransformationPlan, TypedValue, ValueLabel,
+    VariableDefinition, VariableSchema, transformation_plan_from_dict,
+)
+
+__all__ = [
+    "AssignOperation", "BooleanExpression", "ComparisonExpression",
+    "ConditionalAssignOperation", "ExecuteOperation", "Operand",
+    "PredicateExpression", "CreateVariableOperation", "DeleteVariableOperation",
+    "CapabilityDeclaration", "DoltConformanceSource", "LossReport",
+    "SpssFrontendCompilation", "TransformationError",
+    "TransformationFrontendError",
+    "RecodeMatch", "RecodeOperation", "RecodeResult", "RecodeRule",
+    "ReplaceValueLabelsOperation", "SetFormatOperation",
+    "SetMeasurementLevelOperation", "SetVariableLabelOperation",
+    "TransformationPlan", "TypedValue", "ValueLabel",
+    "VariableDefinition", "VariableSchema", "transformation_plan_from_dict",
+    "apply_spss_in_place", "apply_transformation_plan_in_place",
+    "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",
+    "validate_derived",
+]

{openstatspec-0.4.0 → openstatspec-0.5.0}/src/openstatspec/api.py

@@ -7,7 +7,13 @@ from typing import Any
 from .core.results import result
 from .spss import export_dataset, import_dataset, inspect_source
 from .spss.sav import engine_identity
-from .sql import declared_profiles, validate_dataset
+from .sql import (
+    DoltConformanceSource,
+    declared_profiles,
+    dolt_state_snapshot as _dolt_state_snapshot,
+    initialize_catalog as _initialize_catalog,
+    validate_dataset,
+)
 from .sql.catalog_api import catalog_dataset as _catalog_dataset, catalog_datasets as _catalog_datasets
 from .sql.workflow import (
     derive_dataset as _derive_dataset,
@@ -28,12 +34,17 @@ from .sql.inplace_transform import (
 )
 from .transform import TransformationPlan
 from .sql.capabilities import (
-    SPECIFICATION_COMMIT, SPECIFICATION_RELEASE, active_connection, catalog_binding,
+    SPECIFICATION_COMMIT, SPECIFICATION_RELEASE, SPECIFICATION_STATUS,
+    active_connection, catalog_binding,
 )
 
 
 
-def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
+def capability_matrix(
+    database_url: str | None = None,
+    *,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+) -> Mapping[str, Any]:
     """Return the pyspssio-backed SAV/ZSAV fidelity boundary.
 
     supported means that the adapter has a tested faithful path.
@@ -44,7 +55,7 @@ def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
     """
     declaration = {
         "specification": "OpenStatSpec",
-        "specification_status": "released",
+        "specification_status": SPECIFICATION_STATUS,
         "specification_release": SPECIFICATION_RELEASE,
         "specification_commit": SPECIFICATION_COMMIT,
         "profile": "SPSS SAV/ZSAV 1.0",
@@ -73,7 +84,7 @@ def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
             "multiple_response_sets": "supported",
             "variable_alignment": "supported",
             "variable_sets": "supported",
-            "compatible_variable_names": "supported",
+            "compatible_variable_names": "requires-explicit-loss-consent",
             "custom_attributes": {
                 "scalar_values": "supported",
                 "ordered_value_arrays": "supported",
@@ -86,9 +97,18 @@ def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
             "maximum_source_file_bytes": None,
             "limit_basis": "runtime memory and active SQL connection limits",
         },
-        "active_connection": active_connection(database_url) if database_url else None,
+        "active_connection": (
+            active_connection(
+                database_url,
+                dolt_conformance_source=dolt_conformance_source,
+            )
+            if database_url else None
+        ),
         "catalog_binding": catalog_binding(database_url) if database_url else None,
-        "sql_profiles": declared_profiles(database_url),
+        "sql_profiles": declared_profiles(
+            database_url,
+            dolt_conformance_source=dolt_conformance_source,
+        ),
         "optional_profiles": {
             "sql_transformation_workflow": transformation_capabilities(database_url),
             "spss_in_place_transformation": (
@@ -98,26 +118,84 @@ def capability_matrix(database_url: str | None = None) -> Mapping[str, Any]:
     }
     return declaration
 
-def capabilities(database_url: str | None = None) -> Mapping[str, Any]:
-    return capability_matrix(database_url)
+def capabilities(
+    database_url: str | None = None,
+    *,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+) -> Mapping[str, Any]:
+    return capability_matrix(
+        database_url, dolt_conformance_source=dolt_conformance_source,
+    )
 
 
 def inspect(source: str | Path, /, **options: Any) -> Mapping[str, Any]:
     return result(inspect_source(source, **options))
 
 
-def import_sav(source: str | Path, /, *, database_url: Any, dataset_id: str, **options: Any) -> Mapping[str, Any]:
+def dolt_state_snapshot(
+    *,
+    database_url: Any,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+) -> Mapping[str, Any]:
+    """Return read-only Dolt branch, HEAD, status, and diff-summary evidence."""
+    return result(_dolt_state_snapshot(
+        database_url=database_url,
+        dolt_conformance_source=dolt_conformance_source,
+    ))
+
+
+def initialize_catalog(
+    *,
+    database_url: Any,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+) -> Mapping[str, Any]:
+    """Install or explicitly migrate a dedicated OpenStatSpec catalog."""
+    return result(_initialize_catalog(
+        database_url=database_url,
+        dolt_conformance_source=dolt_conformance_source,
+    ))
+
+
+def import_sav(
+    source: str | Path, /, *, database_url: Any, dataset_id: str,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+    **options: Any,
+) -> Mapping[str, Any]:
     """Import one source file into one dedicated wide SQL table."""
-    return result(import_dataset(source, database_url=database_url, dataset_id=dataset_id, **options))
+    return result(import_dataset(
+        source, database_url=database_url, dataset_id=dataset_id,
+        dolt_conformance_source=dolt_conformance_source,
+        **options,
+    ))
 
 
-def export_sav(*, database_url: Any, dataset_id: str, destination: str | Path, **options: Any) -> Mapping[str, Any]:
+def export_sav(
+    *, database_url: Any, dataset_id: str, destination: str | Path,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+    **options: Any,
+) -> Mapping[str, Any]:
     """Export one database-resident conforming dataset to SAV/ZSAV."""
-    return result(export_dataset(database_url=database_url, dataset_id=dataset_id, destination=destination, **options))
+    return result(export_dataset(
+        database_url=database_url, dataset_id=dataset_id,
+        destination=destination,
+        dolt_conformance_source=dolt_conformance_source,
+        **options,
+    ))
 
 
-def validate(*, database_url: Any, dataset_id: str, **options: Any) -> Mapping[str, Any]:
-    return result(validate_dataset(database_url=database_url, dataset_id=dataset_id, **options))
+def validate(
+    *,
+    database_url: Any,
+    dataset_id: str,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+    **options: Any,
+) -> Mapping[str, Any]:
+    return result(validate_dataset(
+        database_url=database_url,
+        dataset_id=dataset_id,
+        dolt_conformance_source=dolt_conformance_source,
+        **options,
+    ))
 
 
 def list_datasets(*, database_url: Any, kind: str | None = None) -> Mapping[str, Any]:
@@ -144,8 +222,12 @@ def apply_spss_in_place(
     *, database_url: Any, dataset_id: str, source_text: str,
     actor: str, expected_branch: str | None = None,
     expected_head: str | None = None,
+    dolt_conformance_source: DoltConformanceSource | None = None,
 ) -> Mapping[str, Any]:
-    """Apply supported SPSS-like syntax to the same SQL dataset/table."""
+    """Apply bounded sequential SPSS syntax to one SQL dataset/table.
+
+    Supports typed COMPUTE/IF predicates and dictionary metadata operations.
+    """
     return result(_apply_spss_in_place(
         database_url=str(database_url),
         dataset_id=dataset_id,
@@ -153,6 +235,7 @@ def apply_spss_in_place(
         actor=actor,
         expected_branch=expected_branch,
         expected_head=expected_head,
+        dolt_conformance_source=dolt_conformance_source,
     ))
 
 
@@ -161,6 +244,7 @@ def apply_transformation_plan_in_place(
     plan: TransformationPlan | Mapping[str, Any],
     actor: str, expected_branch: str | None = None,
     expected_head: str | None = None,
+    dolt_conformance_source: DoltConformanceSource | None = None,
 ) -> Mapping[str, Any]:
     """Apply a canonical plan to the same logical dataset and physical table."""
     return result(_apply_transformation_plan_in_place(
@@ -170,12 +254,20 @@ def apply_transformation_plan_in_place(
         actor=actor,
         expected_branch=expected_branch,
         expected_head=expected_head,
+        dolt_conformance_source=dolt_conformance_source,
     ))
 
 
-def install_in_place_transformation_schema(*, database_url: Any) -> None:
+def install_in_place_transformation_schema(
+    *,
+    database_url: Any,
+    dolt_conformance_source: DoltConformanceSource | None = None,
+) -> None:
     """Install the compact apply-audit relation before the first apply."""
-    _install_in_place_schema(database_url=str(database_url))
+    _install_in_place_schema(
+        database_url=str(database_url),
+        dolt_conformance_source=dolt_conformance_source,
+    )
 
 
 def validate_derived(*, database_url: Any, derived_dataset_id: str) -> Mapping[str, Any]: