openstatspec 0.6.0__tar.gz → 0.7.0__tar.gz

openstatspec-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,204 @@
+name: Release
+
+env:
+  OPENSTATSPEC_SPECIFICATION_DIR: ${{ github.workspace }}/openstatspec-specification
+  OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR: ${{ github.workspace }}/openstatspec-specification-package
+  OPENSTATSPEC_SPECIFICATION_PACKAGE_REF: 2778b784afcb63868ce3c3235a5f1fa190100f9d
+  OPENSTATSPEC_SPECIFICATION_PACKAGE_VERSION: 0.1.0
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      release_ref:
+        description: "Existing release tag to rebuild and publish idempotently"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/tags/${{ inputs.release_ref || github.ref_name }}
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Verify release tag exists and targets this package version
+        env:
+          RELEASE_TAG: ${{ inputs.release_ref || github.ref_name }}
+        run: |
+          set -eu
+          git fetch --force --no-tags origin "refs/tags/${RELEASE_TAG}:refs/tags/${RELEASE_TAG}"
+          python .github/verify_release_ref.py
+      - run: python -m pip install --upgrade pip build twine pytest
+      - name: Verify required SPSS engine is publicly installable
+        run: >-
+          python -m pip download --only-binary=:all: --no-deps
+          --dest /tmp/openstatspec-engine-release
+          openstatspec-pyspssio==0.5.1.post2
+      - name: Checkout normative specification fixtures
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: OpenStatSpec/specification
+          ref: f2fdf687d8cb32b944ca55a3e9e7215ffc603019
+          path: openstatspec-specification
+      - name: Checkout specification package source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: OpenStatSpec/specification
+          ref: ${{ env.OPENSTATSPEC_SPECIFICATION_PACKAGE_REF }}
+          path: openstatspec-specification-package
+      - name: Verify specification package source
+        env:
+          SPECIFICATION_PACKAGE_DIR: ${{ env.OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR }}
+          SPECIFICATION_PACKAGE_REF: ${{ env.OPENSTATSPEC_SPECIFICATION_PACKAGE_REF }}
+          SPECIFICATION_PACKAGE_VERSION: ${{ env.OPENSTATSPEC_SPECIFICATION_PACKAGE_VERSION }}
+        run: |
+          python - <<'PY'
+          import os
+          import subprocess
+          import tomllib
+          from pathlib import Path
+
+          source = Path(os.environ["SPECIFICATION_PACKAGE_DIR"])
+          expected_ref = os.environ["SPECIFICATION_PACKAGE_REF"]
+          actual_ref = subprocess.check_output(
+              ["git", "rev-parse", "HEAD"], cwd=source, text=True,
+          ).strip()
+          if actual_ref != expected_ref:
+              raise SystemExit(
+                  f"specification package ref {actual_ref!r} does not match "
+                  f"expected {expected_ref!r}"
+              )
+          project = tomllib.loads(
+              (source / "pyproject.toml").read_text(encoding="utf-8")
+          )["project"]
+          if project["name"] != "openstatspec-specification":
+              raise SystemExit("unexpected specification package name")
+          expected_version = os.environ["SPECIFICATION_PACKAGE_VERSION"]
+          if project["version"] != expected_version:
+              raise SystemExit(
+                  f"specification package version {project['version']!r} does "
+                  f"not match expected {expected_version!r}"
+              )
+          for required in (
+              "pyproject.toml",
+              "src/openstatspec_specification/dolt.py",
+              "sql/dolt-adapter-declaration-schema.json",
+          ):
+              if not (source / required).is_file():
+                  raise SystemExit(f"missing specification package resource: {required}")
+          PY
+      - name: Verify specification package tests and repository
+        run: |
+          python -m pip install -e "$OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR"
+          python -m pytest -q "$OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR/tests/test_dolt_declarations.py"
+          python "$OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR/tools/validate_repository.py"
+      - name: Build clean release distributions
+        run: |
+          rm -rf dist /tmp/openstatspec-release-dists
+          mkdir -p dist/openstatspec dist/openstatspec-specification \
+            /tmp/openstatspec-release-dists/openstatspec \
+            /tmp/openstatspec-release-dists/specification
+          python -m build --outdir /tmp/openstatspec-release-dists/openstatspec .
+          python -m build --outdir /tmp/openstatspec-release-dists/specification "$OPENSTATSPEC_SPECIFICATION_PACKAGE_DIR"
+          python -m twine check \
+            /tmp/openstatspec-release-dists/openstatspec/* \
+            /tmp/openstatspec-release-dists/specification/*
+          python - <<'PY'
+          from pathlib import Path
+          from shutil import copy2
+
+          sources = {
+              "openstatspec": (
+                  Path("/tmp/openstatspec-release-dists/openstatspec"),
+                  Path("dist/openstatspec"),
+              ),
+              "openstatspec_specification": (
+                  Path("/tmp/openstatspec-release-dists/specification"),
+                  Path("dist/openstatspec-specification"),
+              ),
+          }
+          copied = []
+          for normalized_name, (source, destination_dir) in sources.items():
+              destination_dir.mkdir(parents=True, exist_ok=True)
+              files = sorted(path for path in source.iterdir() if path.is_file())
+              if len(files) != 2 or {path.suffix for path in files} != {".whl", ".gz"}:
+                  raise SystemExit(
+                      f"expected one wheel and one sdist for {normalized_name}, got "
+                      f"{[path.name for path in files]}"
+                  )
+              for path in files:
+                  normalized_artifact = path.name.replace("-", "_").lower()
+                  if not normalized_artifact.startswith(normalized_name + "_"):
+                      raise SystemExit(
+                          f"unexpected artifact name for {normalized_name}: {path.name}"
+                      )
+                  destination = destination_dir / path.name
+                  copy2(path, destination)
+                  copied.append(destination)
+          if len(copied) != 4:
+              raise SystemExit(f"expected four release artifacts, got {len(copied)}")
+          print("release artifacts:", ", ".join(path.name for path in copied))
+          PY
+      - name: Checkout required SPSS engine
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: TonisOrmisson/pyspssio
+          ref: e069adf33c70bcd9e8e6ee495106479463a84fa2
+          path: openstatspec-pyspssio
+      - run: python -m pip install ./openstatspec-pyspssio
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -m "not services"
+      - run: python -m venv /tmp/openstatspec-release-smoke
+      - run: /tmp/openstatspec-release-smoke/bin/python -m pip install ./openstatspec-pyspssio
+      - run: /tmp/openstatspec-release-smoke/bin/python -m pip install dist/openstatspec/openstatspec-*.whl
+      - run: /tmp/openstatspec-release-smoke/bin/openstatspec capabilities
+      - name: Smoke-test specification wheel
+        run: |
+          python -m venv /tmp/openstatspec-specification-release-smoke
+          /tmp/openstatspec-specification-release-smoke/bin/python -m pip install dist/openstatspec-specification/openstatspec_specification-*.whl
+          /tmp/openstatspec-specification-release-smoke/bin/python - <<'PY'
+          from openstatspec_specification import DoltDeclarationSource
+
+          source = DoltDeclarationSource.packaged()
+          schema = source.read_json("sql/dolt-adapter-declaration-schema.json")
+          if schema.get("schema_id") != "openstatspec-dolt-adapter-declaration-v1":
+              raise SystemExit("packaged specification schema has the wrong identifier")
+          PY
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/openstatspec
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-distributions
+          path: dist/
+      - name: Publish openstatspec to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/openstatspec/
+          skip-existing: true
+      - name: Publish openstatspec-specification to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/openstatspec-specification/
+          skip-existing: true

{openstatspec-0.6.0 → openstatspec-0.7.0}/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this reference implementation are documented here.
 
 _No unreleased changes._
 
+## 0.7.0 - 2026-08-11
+
+### Added
+
+- Added root release workflow support for publishing the normative
+  `openstatspec-specification` companion distribution, with independent
+  artifact validation, smoke tests, and PyPI publishing.
+- Carried the complete 0.6.0 transformation, PostgreSQL, and documentation
+  work forward into the versioned 0.7.0 release from `main`.
+
 ## 0.6.0 - 2026-08-05
 
 ### Added

{openstatspec-0.6.0 → openstatspec-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openstatspec
-Version: 0.6.0
+Version: 0.7.0
 Summary: Reference adapter for the OpenStatSpec relational contract
 Author: OpenStatSpec
 License: Apache-2.0
@@ -87,6 +87,7 @@ implemented capability boundary.
 ## SPSS-like transformation frontend
 
 The bounded SPSS-like frontend lowers `RECODE`, sequential `COMPUTE` and `IF`,
+`STRING` declarations, and `DELETE VARIABLES`,
 `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

{openstatspec-0.6.0 → openstatspec-0.7.0}/README.md

@@ -68,6 +68,7 @@ implemented capability boundary.
 ## SPSS-like transformation frontend
 
 The bounded SPSS-like frontend lowers `RECODE`, sequential `COMPUTE` and `IF`,
+`STRING` declarations, and `DELETE VARIABLES`,
 `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

{openstatspec-0.6.0 → openstatspec-0.7.0}/docs/release-readiness.md

@@ -1,4 +1,4 @@
-# 0.5.0 release readiness
+# 0.7.0 release readiness
 
 This page records the expected release contract, not a publication event.
 Creating a version tag remains a separate maintainer action.
@@ -69,6 +69,8 @@ The gate must prove that:
   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`;
+- bounded `STRING` declarations and `DELETE VARIABLES` operations preserve
+  the resulting schema and physical-column identity on supported profiles;
 - 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;

{openstatspec-0.6.0 → openstatspec-0.7.0}/docs/transformations.md

@@ -4,9 +4,10 @@ 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 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
+The implemented bounded SPSS-like frontend accepts bounded `STRING`
+declarations, `RECODE`, sequential `COMPUTE` and `IF`, `DELETE VARIABLES`,
+`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,

openstatspec-0.7.0/openstatspec-specification/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  specification:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - run: python tools/validate_repository.py

openstatspec-0.7.0/openstatspec-specification/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.py[cod]

openstatspec-0.7.0/openstatspec-specification/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## Unreleased
+
+Target stable specification release: `v0.3.0` (not published).
+
+Until a protected or signed `v0.3.0` tag targets this work, implementations MUST identify it with `specification_status: release_candidate`, `specification_release: null`, and the exact immutable specification commit. The entries below do not constitute a stable release.
+
+- Added backward-compatible Transformation Plan and SPSS Syntax Frontend 0.2
+  contracts for sequential numeric `COMPUTE` and conditional `IF`, bounded
+  comparison/`AND`/`OR` expressions, `FORMATS`, `VARIABLE LEVEL`, and
+  `EXECUTE`.
+- Defined exact SQL three-valued missing semantics and deterministic complete
+  plan JSON hashing while preserving every 0.1 contract, fixture, and hash.
+- Kept create-target apply fail-closed on MySQL, MariaDB, and Dolt; these
+  profiles require a separately versioned physical-and-catalog provisioning
+  action followed by an existing-target apply with no automatic Dolt commit.
+- Added independent synthetic golden fixtures, hashes, examples, and repository
+  validation gates for the new contracts.
+- Corrected the SPSS Syntax Frontend 0.1 schema's `$defs` and `$ref` keywords
+  so typed value-label values are constrained as the existing contract states;
+  this is eligible for a patch-series backport under the schema-defect policy.
+
+## v0.2.0 - 2026-07-31
+
+- Added canonical Transformation Plan and SPSS Syntax Frontend profiles for a
+  bounded `RECODE`, `VARIABLE LABELS`, and `VALUE LABELS` subset.
+- Added plan/frontend JSON Schemas, canonical-hash conformance cases, examples,
+  and repository validation gates.
+- Added a product-neutral in-place binding for supported SQL profiles: direct
+  same-table data/metadata mutation, compact operation audit, no automatic
+  commit, and no derived/copy/snapshot/rollback history layer. Dolt adds a
+  controlled branch/HEAD/working-set context.
+
+## v0.1.0 - 2026-07-31
+
+- Defined conservative maintained release-series claims and exact CI targets
+  for MySQL 8.4.11/9.7.2, MariaDB 11.4.12/11.8.8/12.3.2 and PostgreSQL
+  17.10/18.4.
+- Expanded the independent Dolt claim from exact 2.2.2 to the conservative
+  `>=2.2.2,<2.3.0` portion of 2.2.x and added exact 2.2.3 CI
+  evidence alongside retained 2.2.2 evidence.
+- Clarified the non-conflicting SQLite core/optional-workflow policies.
+- Added an explicitly unsupported Microsoft SQL Server dialect roadmap.
+- Prepared the initial specification release as `v0.1.0`.
+
+- Defined the strict one-source-dataset to one-wide-table relational contract.
+- Added the normative operation and fidelity-event model.
+- Added SQLite, PostgreSQL, and MySQL/MariaDB dialect capability profiles.
+- Added generated CC0 SAV/ZSAV conformance fixtures and a machine-readable manifest.
+- Added Python and PHP reference-adapter conformance coverage.
+- Made the singular normative catalog the required source of truth for export.
+- Added case-weight, typed multiple-response counted values, label-source, and explicit LOWEST/HIGHEST coverage.
+- Required immutable specification identity, theoretical/effective SQL limits, tested server versions, and concrete canonical fixture expectations in capability declarations and conformance runs.
+- Clarified prerelease identity, dimensioned identifier limits, and exclusive catalog namespace ownership.
+- Added an independent, fail-closed Dolt 2.2.2 SQL profile with a dedicated-database binding, evidence-labelled adapter limits, and complete compensating cleanup for non-atomic DDL.
+- Added optional SQL Transformation Workflow Profile 0.1 without changing the immutable source-faithful core contract.

openstatspec-0.7.0/openstatspec-specification/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to OpenStatSpec
+
+OpenStatSpec is at release-candidate status. Contributions that make its source-faithful SPSS-to-relational contract clearer, testable, or implementable are welcome.
+
+## Useful first contributions
+
+- Propose a clarification when a mapping rule is ambiguous or incomplete. Describe the source behavior, the intended relational representation, and any fidelity risk.
+- Add a small, lawful fixture that demonstrates a real SPSS dictionary or value edge case, along with the expected wide table and metadata outcome.
+- Draft a dialect profile that states identifier, column, binary64, text, and row/value-size capabilities, plus the required preflight behavior.
+- Report or contribute adapter support, including what source features it preserves and any machine-readable fidelity events it emits.
+- Improve documentation, examples, or terminology when it helps an implementer apply the existing scope correctly.
+
+## Scope guardrails
+
+The standard preserves the source package's native rectangular dataset: one source dataset is one dedicated wide table, each case is a row, and each variable is a physical column. Metadata exists to preserve source semantics and exportability.
+
+Do not propose a second data model as part of this contract. In particular, long-form cells, EAV/JSON value storage, automatic reshaping, splitting a source table, automatic harmonization, inferred respondent keys, and question/study/wave entities are outside scope.
+
+If a relational target cannot faithfully represent a source dataset within its declared limits, the correct outcome is an atomic, machine-readable capability failure—not a silent transformation.
+
+## How to propose a change
+
+1. Check the relevant profile, schema outline, and example first.
+2. Keep the proposal small and name the affected source behavior.
+3. Explain the expected mapping and whether it changes conformance, fixtures, or a dialect capability declaration.
+4. Include a minimal example or test fixture when practical.
+
+There is no formal governance process in this draft yet. Clear, evidence-based proposals that preserve the strict scope are the best starting point.

openstatspec-0.7.0/openstatspec-specification/README.md

@@ -0,0 +1,100 @@
+# OpenStatSpec
+
+OpenStatSpec is an open, SQL-oriented specification for representing a statistical data file and its dictionary metadata in a relational database without changing the source package's rectangular data model.
+
+The first profile targets IBM SPSS Statistics system files. It maps one source dataset to one dedicated wide SQL table: each source case becomes one row and each source variable becomes one physical column. Supporting catalog tables retain only the metadata needed to interpret and export that SPSS dataset faithfully.
+
+## Conformance scope
+
+The [SPSS SAV/ZSAV profile](docs/spss-sav-zsav-profile-1.0.md) defines normative conformance language, a canonical relational schema, generated fixtures, and reference-adapter coverage. The SQL layer includes independent SQLite, PostgreSQL, MySQL/MariaDB/InnoDB, and Dolt profiles. Implementations must pin the exact specification commit they test against. Release identifiers and immutable provenance belong in tagged releases and capability declarations rather than in this README.
+
+The [server-version policy](sql/server-version-policy.md) covers the maintained
+MySQL 8.4.x/9.7.x, MariaDB 11.4.x/11.8.x/12.3.x and PostgreSQL 17.x/18.x
+series while requiring exact patch-version CI evidence. Microsoft SQL Server
+remains an explicitly unsupported [future dialect](docs/mssql-dialect-roadmap.md).
+
+## Core contract
+
+- One source dataset maps to exactly one dedicated SQL data table.
+- One SPSS case maps to exactly one row, in source order.
+- One SPSS variable maps to exactly one physical SQL column, in source order.
+- The table contains a reserved technical ordinal column, `__case_ordinal`, used only to preserve case order. It is never exported as an SPSS variable.
+- Numeric system-missing values map to SQL `NULL`; SPSS user-missing codes remain their original stored values and are described in metadata.
+- Dates, times, and currencies remain SPSS numeric values plus SPSS format metadata.
+- String blanks remain values, not missing values.
+
+OpenStatSpec does not define long-form cells, EAV storage, table splitting, reshaping, automatic harmonization, or questionnaire/study entities. It does not infer respondent keys or combine datasets. All conformant database-object identifiers are generic; the double-underscore prefix is reserved for standard technical identifiers.
+
+[Versioning](VERSIONING.md) defines compatibility and release rules. [Roadmap](ROADMAP.md) tracks remaining project work and maintainer setup.
+
+## Optional SQL transformation workflow
+
+The [SQL Transformation Workflow Profile 0.1](docs/sql-transformation-workflow-profile-0.1.md)
+adds versioned, parameterized and auditable SQL-derived datasets beside the core.
+It never reclassifies derived output as a source-faithful core dataset and never
+permits a transformation to mutate a core import.
+
+That separate derived-data profile is not used by the SPSS-like in-place
+frontend below.
+
+The release-candidate [Transformation Plan Profile 0.2](docs/transformation-plan-profile-0.2.md)
+adds sequential bounded numeric assignment and conditional assignment to the
+unchanged 0.1 operations. The
+[SPSS Syntax Frontend Profile 0.2](docs/spss-syntax-frontend-profile-0.2.md)
+lowers `COMPUTE`, `IF`, `FORMATS`, `VARIABLE LEVEL`, and `EXECUTE`
+alongside the 0.1 `RECODE`, `VARIABLE LABELS`, and `VALUE LABELS` subset.
+Programs using only the 0.1 subset retain exact 0.1 plan identity and hash. The
+[in-place binding](docs/transformation-plan-sql-binding-0.2.md) applies the plan
+to the same dataset and same physical wide table on supported SQL profiles. It
+creates no derived dataset, data copy, or OpenStatSpec undo layer; Dolt-specific
+history and commits remain Dolt's. MySQL, MariaDB, and Dolt require a new target
+to be provisioned separately before an in-place transformation apply.
+
+## Repository layout
+
+- `sql/server-version-policy.md` — server release-series claims and exact reference-CI targets.
+- `docs/mssql-dialect-roadmap.md` — unsupported future SQL Server dialect plan.
+
+- `docs/architecture.md` — model boundary and catalog outline.
+- `docs/spss-profile.md` — SPSS source-faithful mapping rules.
+- [Python / pinned pyspssio implementation profile](docs/implementation-profiles/python-pyspssio-0.5.1.md) — Python adapter pyspssio capability boundary; it does not relax the normative SAV/ZSAV profile.
+- `sql/dialect-profiles.md` — initial SQLite, PostgreSQL, MySQL/MariaDB and Dolt physical profiles.
+- `sql/` — dialect-neutral schema outline and profile notes.
+- `sql/transformation-workflow-profile-schema.sql` - optional derived-data
+  catalog outline, separate from the immutable core catalog.
+- `transformation/plan-0.1.schema.json` — canonical transformation-plan schema.
+- `sql/transformation-plan-profile-schema.sql` — compact in-place apply audit;
+  it is not a dataset-version catalog.
+- `conformance/transformation-plan-0.2.json` and
+  `conformance/spss-syntax-frontend-0.2.json` — additive plan and frontend
+  conformance cases with independent golden hashes; `conformance/in-place-transformation-0.2.json`
+  fixes the same-dataset/same-table execution invariants and the additional
+  controlled Dolt context. The 0.1 schemas and fixtures remain unchanged.
+- `examples/` — small illustrative mapping fixtures.
+
+## Conformance principle
+
+Implementations must preflight target capabilities before import. If the target cannot faithfully create one wide table because of column, identifier, string, or row limits, import must fail atomically with a machine-readable capability diagnostic. It must never silently truncate, drop, split, transpose, pivot, or transform source data.
+
+This specification repository publishes only normative Transformation Plan and SPSS syntax frontend schemas, documentation, and declarative fixtures. Executable validation or behavioral conformance code, including parser, SQL-engine, transaction, and adapter behavior, belongs in each implementation or adapter repository.
+
+## Who it is for
+
+OpenStatSpec is for people and projects that need to move statistical datasets between SPSS and relational databases without turning the data into a different model. It is especially relevant to:
+
+- implementers building SPSS import/export adapters or language libraries;
+- data managers and statistical-data practitioners preserving SPSS dictionaries in SQL-backed workflows;
+- database maintainers preparing a dialect profile with clear capability boundaries; and
+- users who need an inspectable, source-faithful relational target for SPSS data.
+
+## Trying the profile
+
+Read the [SPSS profile](docs/spss-profile.md) and the [schema outline](sql/schema-outline.sql), then map a small unencrypted `.sav` or `.zsav` file to one dedicated wide table plus the catalog metadata. Preserve source case and variable order, retain raw values, and use the metadata tables to retain labels, missing-value rules, formats, and other dictionary semantics.
+
+An implementation must publish its database dialect capabilities and reject any source dataset it cannot represent faithfully in one table. The [basic example](examples/basic-spss-mapping.md) illustrates the intended shape.
+
+## Contribute and adopt
+
+This profile welcomes real-world review. Implementers, statistical-data practitioners, and database maintainers are invited to test it against actual SPSS datasets and contribute findings, fixtures, dialect profiles, adapter support, or documentation improvements. Start with [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The standard remains deliberately narrow: it defines a source-faithful relational representation, not a statistics engine, survey platform, harmonization system, or general data warehouse model.

openstatspec-0.7.0/openstatspec-specification/ROADMAP.md

@@ -0,0 +1,112 @@
+# Roadmap
+
+This is a working to-do list for OpenStatSpec. Items below describe intended work, not promises of a release date or expanded scope.
+
+## 1. Core SPSS relational specification
+
+- [x] Complete the SPSS `.sav` and `.zsav` mapping rules for values, dictionary metadata, ordering, missing values, formats, attributes, documents, variable sets, and multiple-response sets.
+- [x] Review the source-faithful wide-table contract for clarity and implementability.
+- [x] Define the machine-readable fidelity-event and target-capability diagnostic fields.
+- [ ] Review terminology and examples with statistical-data practitioners and adapter implementers.
+
+## 2. Canonical fixtures and conformance tests
+
+- [x] Create small lawful SPSS fixtures covering ordinary values and dictionary metadata.
+- [x] Add edge-case fixtures for system-missing, user-missing values and ranges, strings, labels, formats, long names, and identifier collisions.
+- [x] Define expected relational outcomes and semantic round-trip checks.
+- [x] Publish conformance-test guidance for dialect profiles and adapters.
+
+## 3. Reference adapters
+
+Prerequisite: the core mapping and canonical fixtures are stable enough to test against.
+
+- [x] Establish a Python reference-adapter repository that imports and exports the SPSS profile, reports fidelity events, and runs the canonical fixtures.
+- [x] Establish a PHP reference-adapter repository with the same profile boundary and fixture expectations.
+- [x] Document supported source features and declared database capabilities for each adapter.
+
+## 4. CI, releases, and documentation
+
+- [x] Add continuous checks for specification links, schema examples, fixtures, and adapter conformance once the relevant repositories exist.
+- [x] Define versioning and compatibility guidance for the specification and profiles.
+- [x] Publish release notes and tagged specification releases; `v0.2.0` is the
+  current public specification release.
+- [ ] Expand implementation, dialect-profile, and adoption documentation from real adapter experience.
+
+## 5. Future adapters
+
+Prerequisite: the SPSS profile, fixtures, and reference-adapter lessons are mature.
+
+- [ ] Assess separate source-faithful profiles and adapters for SAS, Stata, and other statistical packages.
+- [ ] Do not begin a future adapter by broadening the relational contract; each profile must preserve the source package's native rectangular data model and declare its own fidelity boundary.
+
+## 6. Optional SQL transformation workflow
+
+- [x] Define an independent catalog for immutable SQL-derived datasets.
+- [x] Define parameter binding, lineage, hashes, audit, metadata and weight
+  propagation, dialect boundaries, and atomic publication.
+- [x] Add machine-readable positive and failure conformance cases.
+- [ ] Run all cases in reference adapters before publishing profile 1.0.
+
+## 7. Canonical transformation plans and syntax frontends
+
+- [x] Define a language-neutral canonical plan for ordered recodes and variable
+  and value-label metadata operations.
+- [x] Define a bounded SPSS-syntax frontend with stable diagnostics and
+  machine-readable conformance cases.
+- [x] Define the in-place binding that preserves dataset/table identity on
+  supported SQL profiles and never creates an OpenStatSpec undo/copy layer.
+- [ ] Run the in-place apply service matrix against every claimed SQL profile
+  before publishing execution claims.
+- [ ] Evaluate additional language frontends as separate adapters that lower to
+  the same canonical plan.
+
+## 8. Microsoft SQL Server dialect
+
+Microsoft SQL Server is not currently supported. The
+[MSSQL dialect roadmap](docs/mssql-dialect-roadmap.md) defines the future
+scope without creating a capability claim.
+
+- [ ] Select and pin Python and PHP driver stacks after fidelity and security evaluation.
+- [ ] Define T-SQL types, quoting, catalog binding, identity probes and effective-limit preflight.
+- [ ] Add exact cumulative-update CI services and complete conformance/fault-injection evidence.
+- [ ] Publish an independent dialect profile only after both reference adapters pass the evidence gate.
+- [ ] Evaluate Azure SQL identities separately; do not inherit a SQL Server claim implicitly.
+
+## 9. Next release dependency order
+
+The next release work must proceed in this order. Completion of an earlier
+artifact is a dependency, not evidence that later adapter or service-matrix
+work has passed.
+
+1. [x] Merged Transformation Plan and SPSS Frontend profile 0.2 as
+   unreleased, release-candidate work for the planned specification `v0.3.0`.
+2. [ ] Rebase Python `0.5.0` conditional transformations on the lifecycle
+   implementation, pin the final profile commit, and pass the combined service
+   and conformance gates before making an adapter claim.
+3. [ ] Migrate PHP to the canonical transformation plan and pass the same
+   relevant conformance cases before it claims conditional profile 0.2 support.
+4. [ ] Select the exact intended `v0.3.0` commit and require that
+   same commit to pass repository validation and all required reference-adapter
+   gates. Only after those gates pass and release-tag signing or protection is
+   configured, create a signed or protected `v0.3.0` tag on that commit.
+   Until then claims use `release_candidate`, a null release identifier, and
+   the exact tested commit.
+
+The pending in-place service matrix and adapter conformance work in sections 6
+and 7 remains required; implementation package publication does not complete
+either evidence gate.
+
+## Maintainer setup
+
+These are maintainer actions, not implementation tasks for the specification repository itself.
+
+- [x] Publish the OpenStatSpec Python distribution and establish its public PyPI
+  project. Published package releases establish the public project; they do not
+  by themselves re-verify owner security or the Trusted Publishing workflow.
+- [ ] Re-verify secure PyPI/TestPyPI ownership and Trusted Publishing before the
+  next Python release workflow is relied on.
+- [x] Register and publish the OpenStatSpec PHP package through Packagist. The
+  public package establishes the registry setup; repository update ownership
+  still needs release-process verification.
+- [ ] Decide the release owner(s), tag naming convention, and release checklist for every repository.
+- [ ] Protect the default branches and ensure release tags are created only by the agreed release workflow; `main` is currently unprotected.

openstatspec-0.7.0/openstatspec-specification/VERSIONING.md

@@ -0,0 +1,35 @@
+# Versioning and compatibility
+
+OpenStatSpec uses semantic versioning for tagged specification releases.
+
+- A major release may change normative relational semantics, required catalogue fields, conformance expectations, or the meaning of an existing requirement.
+- A minor release may add backward-compatible optional metadata, a new independent source or SQL profile, or new fixtures that do not invalidate an implementation's existing declared conformance scope.
+- A patch release may clarify wording, correct examples, or fix fixture and schema defects without changing normative meaning. A schema-defect correction may be backported to a published release series only when it restores the already-stated normative contract; it must not introduce new required behavior, broaden the accepted contract, or silently revise canonical artifacts.
+
+Optional workflow profiles are versioned and claimed independently from the
+core source profile. Adding or revising an optional profile does not authorize
+changes to core datasets. A breaking workflow-profile change increments that
+profile's major version even when the core version is unchanged.
+
+Transformation Plan and frontend contracts are selected by their exact
+contract identifiers. An implementation may support multiple versions
+simultaneously. It MUST preserve the canonical bytes and hashes of accepted
+older plans and MUST NOT silently reinterpret or rewrite an older plan under a
+newer schema. A frontend that accepts a newer request contract but receives a
+program entirely inside the 0.1 command subset emits the exact 0.1 plan
+contract. Explicit recompilation to a newer plan is a new identified operation,
+not migration of the old plan or audit row.
+
+The SPSS SAV/ZSAV profile is versioned independently in its document and manifest. A conforming implementation must publish the exact profile version, immutable specification commit, specification status, supported directions, supported SQL profiles, and engine capability declaration it tested.
+
+The immutable commit is mandatory for both release candidates and stable releases. `specification_release` is additive provenance, not an alternative to the commit:
+
+- for untagged work on `main`, `specification_status` is `release_candidate` and `specification_release` is NULL;
+- for a published tagged release candidate, `specification_status` remains `release_candidate` and `specification_release` is the exact prerelease identifier whose target is the declared commit; and
+- for a published stable release, `specification_status` is `released` and `specification_release` is the exact release identifier whose target is the declared commit.
+
+Development work on `main` is not a released standard. Release candidates may be used for interoperability testing but must be identified as such. A stable release is created only by a signed or protected tag after the repository validation and reference-adapter conformance gates pass.
+
+A release-candidate tag is optional. An immutable commit is sufficient for CI and interoperability review. If maintainers publish a named release candidate, its protected or signed tag is recorded as `specification_release`, while the commit remains mandatory.
+
+Adapter package versions are independent from specification versions. An adapter update that changes its declared conformance scope or fidelity behavior must document that change even when the specification version is unchanged.

openstatspec-0.7.0/openstatspec-specification/conformance/fixtures/LICENSE.md

@@ -0,0 +1,10 @@
+# Conformance fixture data: CC0-1.0
+
+The generated `.sav` and `.zsav` fixture files in this directory are dedicated
+to the public domain under [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).
+
+They contain synthetic test data only and must not contain any real respondents,
+third-party datasets, or personal data.
+
+The accompanying `generate-fixtures.sps` source is part of the OpenStatSpec
+specification and follows the repository licence.