Recover minimal catalog and Dolt lifecycle integration

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@v7
         with: &specification-checkout
           repository: OpenStatSpec/specification
-          ref: 79339ec3d8f8aa81789b7e85f6b8afa6f1374e50
+          ref: 5b62bce1d2f4d719ac6ca42d73f07e7a127c7093
           path: openstatspec-specification
       - name: Checkout required SPSS engine
         uses: actions/checkout@v7
@@ -32,6 +32,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install --upgrade pip
+      - run: python -m pip install ./openstatspec-specification
       - run: python -m pip install ./openstatspec-pyspssio
       - run: python -m pip install -e ".[dev]"
       - run: python -m pytest -m "not services"
@@ -53,6 +54,7 @@ jobs:
       - run: python -m pip install --upgrade pip build
       - run: python -m build
       - run: python -m venv /tmp/openstatspec-wheel-smoke
+      - run: /tmp/openstatspec-wheel-smoke/bin/python -m pip install ./openstatspec-specification
       - run: /tmp/openstatspec-wheel-smoke/bin/python -m pip install ./openstatspec-pyspssio
       - run: /tmp/openstatspec-wheel-smoke/bin/python -m pip install dist/*.whl
       - run: /tmp/openstatspec-wheel-smoke/bin/openstatspec capabilities
@@ -90,6 +92,7 @@ jobs:
         with:
           python-version: "3.12"
       - run: python -m pip install --upgrade pip
+      - run: python -m pip install ./openstatspec-specification
       - run: python -m pip install ./openstatspec-pyspssio
       - run: python -m pip install -e ".[dev,sql]"
       - run: python -m pytest -m services
@@ -143,7 +146,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
@@ -192,6 +195,7 @@ jobs:
             --workdir /var/lib/dolt \
             "$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-specification
       - run: python -m pip install ./openstatspec-pyspssio
       - run: python -m pip install -e ".[dev,sql]"
       - name: Wait for Dolt
@@ -217,7 +221,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: |

CHANGELOG.md

@@ -109,6 +109,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 load the shared `openstatspec-specification` declaration
+  validator and remain fail-closed because the packaged concrete declaration
+  set is empty.
+- 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 +132,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.

pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = {text = "Apache-2.0"}
 authors = [{name = "OpenStatSpec"}]
-dependencies = ["SQLAlchemy>=2.0", "pandas>=2.2", "openstatspec-pyspssio==0.5.1.post2", "sqlglot>=30.14", "rfc8785>=0.1.4"]
+dependencies = ["SQLAlchemy>=2.0", "pandas>=2.2", "openstatspec-pyspssio==0.5.1.post2", "openstatspec-specification==0.2.1", "sqlglot>=30.14", "rfc8785>=0.1.4"]
 
 [project.optional-dependencies]
 dev = ["pytest>=8"]
@@ -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,17 +2,17 @@
 
 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 (
     RecodeMatch, RecodeOperation, RecodeResult, RecodeRule,
     ReplaceValueLabelsOperation, SetVariableLabelOperation,
@@ -21,18 +21,17 @@
 )
 
 __all__ = [
-    "CapabilityDeclaration", "LossReport", "SpssFrontendCompilation",
-    "TransformationError", "TransformationFrontendError",
+    "CapabilityDeclaration", "DoltConformanceSource", "LossReport", "TransformationError",
+    "SpssFrontendCompilation", "TransformationFrontendError",
     "RecodeMatch", "RecodeOperation", "RecodeResult", "RecodeRule",
     "ReplaceValueLabelsOperation", "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",

src/openstatspec/api.py

@@ -7,7 +7,13 @@
 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,
@@ -33,7 +39,11 @@
 
 
 
-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.
@@ -86,9 +96,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 +117,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,6 +221,7 @@ 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."""
     return result(_apply_spss_in_place(
@@ -153,6 +231,7 @@ def apply_spss_in_place(
         actor=actor,
         expected_branch=expected_branch,
         expected_head=expected_head,
+        dolt_conformance_source=dolt_conformance_source,
     ))
 
 
@@ -161,6 +240,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 +250,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]:

src/openstatspec/cli.py

@@ -6,9 +6,9 @@
 
 from .api import (
     apply_spss_in_place, apply_transformation_plan_in_place,
-    capability_matrix, derive_sql_dataset,
+    capability_matrix, derive_sql_dataset, dolt_state_snapshot,
     execute_sql_transformation,
-    export_sav, get_dataset, import_sav, inspect, list_datasets,
+    export_sav, get_dataset, import_sav, initialize_catalog, inspect, list_datasets,
     install_in_place_transformation_schema, register_sql_transformation,
     validate, validate_derived,
 )
@@ -29,6 +29,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     commands = parser.add_subparsers(dest="command", required=True)
     capability_parser = commands.add_parser("capabilities", help="show supported and lossy feature matrix")
     capability_parser.add_argument("--database-url", help="include active connection limits")
+    dolt_state = commands.add_parser("dolt-state", help="show read-only Dolt branch, HEAD, status, and diff evidence")
+    dolt_state.add_argument("--database-url", required=True)
+    initializer = commands.add_parser("init", help="initialize or migrate a dedicated catalog")
+    initializer.add_argument("--database-url", required=True)
     importer = commands.add_parser("import", help="import one SAV/ZSAV file")
     importer.add_argument("source")
     importer.add_argument("--database-url", required=True)
@@ -114,6 +118,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     args = parser.parse_args(argv)
     if args.command == "capabilities":
         output = capability_matrix(database_url=args.database_url)
+    elif args.command == "dolt-state":
+        output = dolt_state_snapshot(database_url=args.database_url)
+    elif args.command == "init":
+        output = initialize_catalog(database_url=args.database_url)
     elif args.command == "import":
         output = import_sav(args.source, database_url=args.database_url, dataset_id=args.dataset_id)
     elif args.command == "export":