diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index be03374..184b8e7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,6 @@ name: CI on: pull_request: - branches: - - main - - codex/transaction-savepoint-orchestration-draft push: branches: - main diff --git a/AGENTS.md b/AGENTS.md index d1df92e..02b75dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ ## قواعد خاصة بالمشروع -- هذه الحزمة مكتبة Composer مستقلة، framework-agnostic وhost-agnostic، وتستخدم PDO المباشر مع MySQL/MariaDB-compatible SQL. +- هذه الحزمة مكتبة Composer مستقلة، framework-agnostic وhost-agnostic، وتستخدم PDO المباشر مع SQL متوافق مع ملف MySQL/MariaDB. التحقق التشغيلي في هذا المستودع يتم على MySQL الحقيقي فقط، وMariaDB ليست مدخلة تحقق مستقلة في مصفوفة CI الحالية. - يجب الحفاظ على عقد v1.4.0 العام، بما في ذلك ملكية المعاملات، ودعم المعاملة الخارجية، ودلالات savepoint المعتمدة؛ لا يُجرى تغيير breaking public API. - اختبارات قاعدة البيانات تتطلب MySQL حقيقيًا؛ لا يجوز استخدام SQLite أو mocks لإثبات سلوك persistence الحقيقي. - لا يُتتبّع composer.lock، ولا يُضاف حقل Composer باسم version، ولا تُنشأ Tag أو GitHub Release ضمن أعمال هذا المستودع ما لم يصدر تصريح صريح بذلك. diff --git a/CHANGELOG.md b/CHANGELOG.md index 3435245..cafa528 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [1.4.0] - Stable Release Preparation (planned 2026-09-17) - -> **Release state:** Stable Release Preparation. The `v1.4.0` tag and release are not published; publication awaits owner approval. +## [1.4.0] - 2026-09-18 ### Added * Transaction savepoint orchestration capability (`SavepointTransactionRunnerInterface`, `PdoSavepointTransactionRunner`) for safe, operation-local rollback boundaries within caller-owned PDO transactions. diff --git a/PERSISTENCE_PACKAGE_REFERENCE.md b/PERSISTENCE_PACKAGE_REFERENCE.md index 746f118..9ba632d 100644 --- a/PERSISTENCE_PACKAGE_REFERENCE.md +++ b/PERSISTENCE_PACKAGE_REFERENCE.md @@ -19,9 +19,11 @@ The package owns the reusable PDO ordering, transaction, savepoint, and pagination behavior, but it does not own a persistent business entity or a production table. Consumers provide their own trusted table and column identifiers, SQL, scopes, and mapping. The package does not create migrations, -foreign keys, or joins to Host tables. MySQL/MariaDB-compatible SQL through -direct PDO is the supported persistence boundary; the package-level schema -notes are in [schema/README.md](schema/README.md). +foreign keys, or joins to Host tables. The persistence profile is +MySQL/MariaDB-compatible SQL through direct PDO. Repository integration and +Consumer verification run against real MySQL, with MySQL 8.4.10 as the current +CI baseline; MariaDB is not independently verified by the current CI matrix. +The package-level schema notes are in [schema/README.md](schema/README.md). ## Public API Inventory @@ -411,7 +413,7 @@ Renaming the marker MAY be reconsidered only as part of a separately approved, m * `PERSISTENCE_TEST_MYSQL_USER` * `PERSISTENCE_TEST_MYSQL_PASSWORD` * **Test Database Isolation**: Assumes isolated test tables and requires local package privileges (trigger/table cleanup). Tests include trigger failure injection. -* **Current CI MySQL Baseline**: 8.4.10. +* **Current CI MySQL Baseline**: MySQL 8.4.10. MariaDB is not independently verified by the current CI matrix. * **Consumer Verification Harness**: `composer test:consumer` installs the package into a separate non-symlinked Composer root and verifies a public ordering, savepoint, and pagination workflow against real MySQL twice from diff --git a/schema/README.md b/schema/README.md index b3e05aa..061d977 100644 --- a/schema/README.md +++ b/schema/README.md @@ -4,4 +4,4 @@ توجد مخططات MySQL المعزولة الخاصة باختبارات المستودع تحت [tests/Fixtures/MySql/](../tests/Fixtures/MySql/)، كما ينشئ Consumer Verification Harness جدوله المعزول مؤقتًا داخل قاعدة الاختبار ثم يحذفه. هذه الملفات ليست جداول Host ولا تعتمد على أي schema خارجي. -الحد التعاقدي لقاعدة البيانات هو MySQL/MariaDB-compatible SQL عبر PDO المباشر. لا تستخدم الحزمة ORM أو query builder خارجيًا، ولا تنشئ جداول عامة مثل logs أو event_logs، ولا تضيف مفاتيح خارجية أو JOINs إلى جداول Host. +الحد التعاقدي لقاعدة البيانات هو SQL متوافق مع ملف MySQL/MariaDB عبر PDO المباشر. التحقق الفعلي لهذه الحزمة واختبارات Consumer يتم على MySQL، وخط CI الحالي يستخدم MySQL 8.4.10؛ لم تُتحقق MariaDB بصورة مستقلة ضمن مصفوفة CI الحالية. لا تستخدم الحزمة ORM أو query builder خارجيًا، ولا تنشئ جداول عامة مثل logs أو event_logs، ولا تضيف مفاتيح خارجية أو JOINs إلى جداول Host. diff --git a/tests/Fixtures/MySql/create_global_ordering_table.sql b/tests/Fixtures/MySql/create_global_ordering_table.sql index 781a170..f714bfc 100644 --- a/tests/Fixtures/MySql/create_global_ordering_table.sql +++ b/tests/Fixtures/MySql/create_global_ordering_table.sql @@ -1,4 +1,5 @@ --- Consumer-owned fixture table for global ordering. +-- Test-only, consumer-owned fixture; the integration suite creates and drops it. +-- Global ordering uses display_order; no additional UNIQUE constraint is declared. -- No Host foreign keys or joins; soft-deleted rows are excluded by the package. CREATE TABLE `maa_persistence_test_global_ordering` ( `id` INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Fixture row identity.', diff --git a/tests/Fixtures/MySql/create_pagination_items_table.sql b/tests/Fixtures/MySql/create_pagination_items_table.sql index 71456cb..5d6f6eb 100644 --- a/tests/Fixtures/MySql/create_pagination_items_table.sql +++ b/tests/Fixtures/MySql/create_pagination_items_table.sql @@ -1,5 +1,7 @@ --- Consumer-owned fixture table for pagination. --- Host identity is supplied as tenant_id; this fixture adds no Host FK. +-- Test-only, consumer-owned fixture; the integration suite creates and drops it. +-- Pagination filters deleted_at and sorts through whitelisted fields with id as +-- the deterministic tie-breaker; no additional UNIQUE constraint is declared. +-- Host identity is supplied as tenant_id; this fixture adds no Host FK or JOIN. CREATE TABLE `maa_persistence_test_pagination_items` ( `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Fixture row identity.', `tenant_id` INT UNSIGNED NOT NULL COMMENT 'Host-provided tenant identity; no FK.', diff --git a/tests/Fixtures/MySql/create_scoped_ordering_table.sql b/tests/Fixtures/MySql/create_scoped_ordering_table.sql index 8795eb3..4293d1b 100644 --- a/tests/Fixtures/MySql/create_scoped_ordering_table.sql +++ b/tests/Fixtures/MySql/create_scoped_ordering_table.sql @@ -1,5 +1,7 @@ --- Consumer-owned fixture table for scoped ordering. --- NULL scope is an exact scope; it is not a wildcard or fallback. +-- Test-only, consumer-owned fixture; the integration suite creates and drops it. +-- Scoped ordering uses display_order within the exact scope_key; no additional +-- UNIQUE constraint is declared, and NULL scope is exact rather than a wildcard. +-- No Host foreign keys or joins; soft-deleted rows are excluded by the package. CREATE TABLE `maa_persistence_test_scoped_ordering` ( `id` INT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Fixture row identity.', `scope_key` VARCHAR(191) NULL DEFAULT NULL COMMENT 'Exact consumer-owned scope key.', diff --git a/tests/Fixtures/MySql/create_transaction_savepoint_items_table.sql b/tests/Fixtures/MySql/create_transaction_savepoint_items_table.sql index a930395..8358d2f 100644 --- a/tests/Fixtures/MySql/create_transaction_savepoint_items_table.sql +++ b/tests/Fixtures/MySql/create_transaction_savepoint_items_table.sql @@ -1,5 +1,7 @@ --- Consumer-owned fixture table for transaction/savepoint integration. --- The table is created and removed by the test suite; no Host tables are used. +-- Test-only, consumer-owned fixture; the integration suite creates and drops it. +-- Transaction/savepoint tests use only the primary-key identity; no additional +-- UNIQUE constraint is declared, and no ordering or soft-delete policy applies. +-- No Host foreign keys or joins; no Host tables are used. CREATE TABLE `maa_persistence_test_transaction_savepoint_items` ( `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Fixture row identity.', `payload` VARCHAR(128) NOT NULL COMMENT 'Fixture transaction payload.',