From 1f25f1cf9eae38acc5036095489ec0de487d982b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=B5nis=20Ormisson?= Date: Thu, 10 Sep 2026 16:43:01 +0300 Subject: [PATCH] docs: record staged adapter alignment and evidence gates --- ROADMAP.md | 8 +++ docs/adapter-alignment-plan.md | 100 +++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 docs/adapter-alignment-plan.md diff --git a/ROADMAP.md b/ROADMAP.md index e2b9a25..cee5b07 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -19,6 +19,14 @@ This is a working to-do list for OpenStatSpec. Items below describe intended wor ### Immediate next work +The [adapter alignment plan](docs/adapter-alignment-plan.md) defines three +reviewed implementation blocks and their separate merge/release gates: +Python extension identities, official Python Frontend 0.3, then PHP parity. +Implementations are in Python PRs [#31](https://github.com/OpenStatSpec/python/pull/31) +and [#32](https://github.com/OpenStatSpec/python/pull/32), and PHP +[#16](https://github.com/OpenStatSpec/php/pull/16); pending checkboxes below +remain open until the relevant merge and evidence gates are complete. + - [ ] Finish the PHP `0.7.2` release: finalize release metadata, verify the exact release commit's CI, tag, and verify a clean Packagist install. - [ ] Reconcile Python's schema-change contract identifiers with the published diff --git a/docs/adapter-alignment-plan.md b/docs/adapter-alignment-plan.md new file mode 100644 index 0000000..58ed33e --- /dev/null +++ b/docs/adapter-alignment-plan.md @@ -0,0 +1,100 @@ +# Reference-adapter alignment plan + +## Scope and release boundary + +Align Python and PHP with the optional SPSS Syntax Frontend 0.3 already +published in specification `v0.5.0`, pinned at +`864e84479f554b8ee250ffed44c4dfb963750d4a`. This is implementation work, not a +new normative profile or a claim of full SPSS compatibility. + +Deliver the three blocks below in dependency order. Each has its own reviewed +pull request and local/CI evidence. Merge and package publication are separate +steps: Python `0.8.1` and PHP `0.7.1` do not gain these changes retroactively. +The merged PHP `0.7.2` preparation is not proof of registry publication. +Do not move published tags or silently rewrite saved plans and audit history. + +## Block 1 — Separate Python extension identities + +[Python PR #31](https://github.com/OpenStatSpec/python/pull/31). + +- Emit `openstatspec-python-schema-change-plan-v0.1` and + `openstatspec-python-schema-change-spss-v0.1` for Python's existing + create/delete-variable extension; retain public constant names. +- Continue accepting the legacy Python plan identifier + `openstatspec-transformation-plan-v0.3` with its exact canonical bytes, + hash and operation semantics. Legacy acceptance is not official conformance. +- Do not reinterpret old frontend audit identifiers as official Frontend 0.3. +- Preserve official Plan 0.1/0.2 schema-operation rejection, dataset/table + identity, native atomicity, and caller-owned Dolt history. +- Document reader upgrade order: older adapters do not recognize newly emitted + Python-owned identifiers. No automatic stored-plan or catalog migration. + +Gate: compatibility/hash and in-place tests, full Python service matrix, +read-only review, and merge before block 2. Implementation is in PR #31; +publication remains pending. + +## Block 2 — Official Frontend 0.3 in Python + +[Python PR #32](https://github.com/OpenStatSpec/python/pull/32), stacked on #31. + +- Keep the existing default API behavior. Add explicit official selection via + the exact `openstatspec-spss-syntax-frontend-v0.3` request contract and the + live-apply frontend selector. +- Validate real request fields and types before compilation; do not establish + conformance merely by changing a test's contract string. +- Support comments, dictionary-order `TO` lists, grouped supported commands, + `NE`/`<>`/`~=`, recursive `NOT`, finite open recode ranges, and ordered + `ADD VALUE LABELS` state. +- Emit only exact Plan 0.1/0.2 objects in official mode; reject Python-owned + schema operations there. Preserve source hashes independently of plan hashes. +- Merge additive labels from live metadata under the dataset lock. Prevent + stale pre-lock snapshots on MySQL/MariaDB without changing Dolt policy. + +Gate: all 35 declared and 90 effective cases, exact inherited plans/hashes, +strict-input regressions, native in-place evidence, full service CI including +MySQL/MariaDB interleaved label updates, and read-only review. + +## Block 3 — Official Frontend 0.3 in PHP + +[PHP PR #16](https://github.com/OpenStatSpec/php/pull/16). + +- Accept the exact official request contract explicitly; retain the existing + Frontend 0.2 default and reuse the existing parser/binder and executor. +- Implement the same official syntax, typed metadata ordering, source hashing, + canonical Plan 0.1/0.2 lowering, and fail-closed boundaries as Python. +- Keep the pure compiler's request-schema boundary explicit: additive labels + merge against labels supplied in that schema; callers must provide current + metadata. This is not a new live-database schema discovery API. +- Keep codec, database support, specification pin and Dolt commit ownership + unchanged. Do not fold catalog refactoring into this block. + +Gate: all 90 effective cases, request/grammar regressions, native SQLite +in-place evidence, `composer check`, full PHP service matrix and read-only +review. Compare both adapters' canonical results, not their internal classes. + +## Shared interpretation and invariants + +Both implementations use comparison evaluation before `NOT`, then `AND`, then +`OR`; parentheses override grouping. Tests make this interpretation explicit. +Negation preserves UNKNOWN and flattens same-operator boolean chains without +reordering operands. No additional expression operations or SQL binding version +are introduced. + +Successful in-place applies preserve dataset and physical-table identity and +case count/order. No copied dataset, staging/output table, snapshot, or hidden +recovery version is introduced. Native transaction rollback is allowed; Dolt +remains the only persistent dataset history/versioning layer. + +## Completion checklist + +- [ ] Merge Python #31, then #32; retain final-commit CI evidence after any merge + or follow-up edits rather than relying only on earlier branch runs. +- [ ] Merge PHP #16 after its final-commit CI and review gates. +- [ ] Update the roadmap's pending adapter claims with merged evidence. PR + implementation is not a published-package support claim. +- [ ] Select package versions and perform each adapter's release checklist, + including clean registry installation. Keep prepared PHP 0.7.2 release notes + distinct from these new Unreleased features until release scope is selected. + +Out of scope: new arithmetic/date/string profiles, case/group/cross-dataset +operations, MSSQL, SAS/Stata, unrelated optimization, and automatic publication.