Merge pull request #12 from OpenStatSpec/agent/catalog-dolt-lifecycle-minimal

Recover minimal catalog and Dolt lifecycle integration

Author: TonisOrmisson

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@v7
         with: &specification-checkout
           repository: OpenStatSpec/specification
-          ref: e49252c00890aed76dcaabc5d1ab5121b45929db
+          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

@@ -28,12 +28,15 @@ Planned adapter release: `0.5.0`, after lifecycle integration and final specific
   format, and measurement level in both normative and compatibility catalogs.
 - 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
-  `e49252c00890aed76dcaabc5d1ab5121b45929db`. Its
+  `f2fdf687d8cb32b944ca55a3e9e7215ffc603019`. Its
   `specification_release` remains null until that commit receives a stable tag.
 
 ## 0.4.0 — 2026-07-31
@@ -143,6 +146,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.
 
@@ -155,3 +169,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.

docs/release-readiness.md

@@ -114,7 +114,7 @@ capability claim, or implied support.
 5. Confirm `openstatspec capabilities` reflects the intended support boundary.
 6. Confirm CI, release fixtures, and capabilities use the untagged OpenStatSpec
    specification release candidate at exact commit
-   `e49252c00890aed76dcaabc5d1ab5121b45929db`, publish
+   `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.

pyproject.toml

@@ -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 (
     AssignOperation, BooleanExpression, ComparisonExpression,
     ConditionalAssignOperation, ExecuteOperation, Operand, PredicateExpression,
@@ -27,19 +27,19 @@
     "AssignOperation", "BooleanExpression", "ComparisonExpression",
     "ConditionalAssignOperation", "ExecuteOperation", "Operand",
     "PredicateExpression",
-    "CapabilityDeclaration", "LossReport", "SpssFrontendCompilation",
-    "TransformationError", "TransformationFrontendError",
+    "CapabilityDeclaration", "DoltConformanceSource", "LossReport",
+    "SpssFrontendCompilation", "TransformationError",
+    "TransformationFrontendError",
     "RecodeMatch", "RecodeOperation", "RecodeResult", "RecodeRule",
     "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",

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,
@@ -34,7 +40,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.
@@ -87,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": (
@@ -99,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]:
@@ -145,6 +222,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 bounded sequential SPSS syntax to one SQL dataset/table.
 
@@ -157,6 +235,7 @@ def apply_spss_in_place(
         actor=actor,
         expected_branch=expected_branch,
         expected_head=expected_head,
+        dolt_conformance_source=dolt_conformance_source,
     ))
 
 
@@ -165,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(
@@ -174,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]:

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":