Repository navigation
architecture: establish PHP 8.4 persistence package contract, standards adoption and migration design #1
Description
Architecture & Standards Study — foundational decision gate (READ-ONLY)
0. Status / authority
This is the first Work Unit for a separate new PHP package, not permission to port source or publish a release. The Owner has created Maatify/php-persistence, which is currently completely empty: GitHub default branch is described as main, but no Git commit / actual branch yet, no prior Issues/PRs, no PHP code. Do not initialize main, publish a work branch or write files during this study. Present decision-ready architecture for Owner acceptance first. Technical Lead reviews; Owner authorizes subsequent implementation boundaries.
1. Frozen factual input baseline (do not confuse source code with a released artifact)
- Old source repository: Maatify/persistence,
main@1f6a7aafe601090b7e55f60d83794364afdefe67/ Git Treec1e25e7653a3173c3339a269b1ad23b26f335b9d. Exact-main CI #39985574051 10/10 successful, MySQL 8.4.10 Integration on PHP 8.2/8.5, consumers, audit and residue; #68, #69, #76 completed. - Old published Composer package
maatify/persistence, PSR-4Maatify\\Persistence\\, declared PHP>=8.2,ext-pdo,maatify/exceptions:^1.0; latest actually tagged/published versionv1.4.0. Its currentmaincontains UNRELEASED API and behavioral changes. Preserve the explicit distinction: Published v1.4.0 vs Old main Unreleased vs Proposed New Package. - Old source consists of 26
src/PHP files spanning Ordering, Pagination, Transaction and Exceptions (plus tests/CI/docs). The oldPageResultpublic DTO-like naming mismatch is tracked in old #66, NON-COMPLIANCE / Owner policy conflict, not a permission to break the published old package. - Old release-readiness umbrella old #37 is OPEN / RELEASE NO-GO; this new architecture work does not authorize old v1.5.0, renaming/removing the old repo, changing installed consumers, tagging, publishing or a Composer
replace.
2. Governing standards — independent new-package adoption, not old repo's stale pin
- Central standards source: Maatify/php-engineering-standards. Snapshot observed at kickoff:
main@5b69c03419ad09369ad207a9a7976cc9cc0617d3. This snapshot is an investigation input, not an automatic approved consumer pin; verify current authoritative, stable exact upstream commit and any applicable finalized/versioned status before proposing an Adoption Commit. - Read current central
AGENTS.md,standards/STANDARDS_ADOPTION_STANDARD_AR.mdin full, decision governance + decision index/currentACTIVEdecisions relevant to package/initial bootstrap, and the full canonical Engineering Standards of the resolved candidate set, especially Package Building, Composer Package, CI Workflow, Testing, Library Presentation, PHP Source Documentation, PHP Coding Style, Documentation Lifecycle, AI Collaboration and GitHub Phase Stack. - Candidate Profiles:
composer-package+repository-governancescoped to/. Perform actual structural/transitive profile resolution → canonical applicability → final applicable set for a standalone PDO/MySQL package. Evaluate conditional external-provider rules; do not automatically include every central standard or copy the entire standards tree. Define the exact Pinned Adoption Control Set + Pinned Applicable Standards Set, local manifest and precedence. Initial source of truth for rules remains central pinned canonical standards, not a duplicated interpretation in project instructions. - The current canonical Package Building Standard explicitly sets PHP 8.4 minimum for new libraries; Composer Package Standard prescribes
"php": "^8.4". Published old package must keep its separate>=8.2promise. New-package identity is intended to bemaatify/php-persistence, notmaatify/persistence.
3. Architecture decisions to present (do not silently choose by porting files)
- Identity & namespaces: Evaluate
Maatify\\{PackageName}\\under current naming rules; propose a distinct PSR-4 namespace and concrete public FQCN naming such that oldMaatify\\Persistence\\and new artifact may coexist. State aliases/bridges only if justified; no Composerreplace, forced conflicts, deceptive compatibility promise or silent in-place upgrade. - Exact contract inventory / 3-way matrix: For every currently observable old public class/interface/enum/exception/method, distinguish (A) published
v1.4.0, (B) oldmainunreleased, and (C) new-package proposed KEEP / RENAME / REDESIGN / OMIT, with exact source references, semantics (especially caller-owned transactions, savepoints, deadlock 1213 retries, ordering, pagination), dependent consumers/risks and SemVer migration consequences. Don't label behaviorunchangedwithout actual test/source support. - Architecture / structure: Choose one source topology (single vs multi-capability vs multi-domain) grounded in actual Ordering/Pagination/Transaction responsibilities and documented boundaries; comply with current DTO
*DTO, Interface*Interface, Enum*Enum, Exception*Exceptionnaming rules for new/unpublished APIs. AddressPageResultcorrectly in the new artifact without retroactive changes to the old published API. - Runtime dependencies & DB contract: Review
ext-pdo, shared exceptions package, direct PDO, no ORM, MySQL/MariaDB support claims only with verified test coverage. Old project CI verifies MySQL 8.4.10; MariaDB is not independently verified and old evidence identifies an engine-specific caller-owned-transaction caveat. Document precisely what the new library will support, exclude, or qualify; do not promise MariaDB by textual SQL similarity. - Testing/CI/package readiness: Specify PHP version matrix consistent with
^8.4, real DB Integration, deterministic transaction/retry/deadlock tests, unit/regression, static analysis PHPStan max, coding style, lowest/latest security-clean Composer resolution, actual external Composer consumer twice from clean environments, DB residue, CI Gate, documentation and release-artifact checks. Do not extrapolate published support from untested engines or versions. - Consumer migration strategy: Explicit migration table for
composer require maatify/persistence→maatify/php-persistence, FQCN/import changes, behavior exceptions, gradual coexistence or conflict, rollback strategy, compatibility policy and staged adoption plan. Identify actual consumers only from permitted verified evidence; don't invent projects or assume automatic migration. - Bootstrap governance: Repo is EMPTY: specify how first
mainCommit will safely establish necessaryAGENTS.md, pinned standards control/applicable set and manifest, decision/architecture doc, Composer skeleton, CI etc in separately authorized and reviewable steps without pretending existing branch/PR gates can operate before a first commit. Separate Owner decisions from Executor tasks. - Release boundary: First RC and first stable SemVer must follow exact artifact verification and Owner approval; no tag/release or claim of automatic migration. Keep the old umbrella and standards correction decisions separate.
4. Deliverable & acceptance
Return a READ-ONLY decision-ready Architecture Study in the Issue discussion (no repository files, branches, commits, PRs or source changes). Include:
- exact refs/hash and a reproducible inventory with source evidence and all unverified items identified explicitly;
- applicable standards matrix with section refs, profile resolution, canonical ownership and selected candidate pinned commit (pending Owner approval);
- public API + contract and migration matrices across published old, unreleased old main and proposed new;
- architecture options with tradeoffs, one recommended design and specifically which decisions Owner must ratify;
- ordered, small independent bootstrap/implementation Work Units with exit gates and rollback/compatibility controls;
- risks/open decisions clearly distinguished from tested facts; no ambiguous multi-source truth;
- handoff stops at Owner/Lead architecture acceptance. No coding, migration, first commit, PR, tags, releases, new Composer package registration, or mutation of old repository in this issue.
Completion = Lead's independent architectural review and Owner's approved decision record, not implementation.
Activity
megyptm commentedon Oct 23, 2026
Technical Lead — START AUTHORIZATION: Issue #1 READ-ONLY Architecture Study
Authorization applies ONLY to analysis and a decision-ready report submitted as GitHub Issue comment(s). It does not authorize initial Git commit, branch, PR, source extraction, Composer publication, any Tag/Release, or modifications in the old repository. Owner ratification follows an independent Lead architecture review.
Preflight verified directly on GitHub (2026-10-23)
Maatify/php-persistenceis empty (size 0, no branches despitedefault_branch=mainmetadata); Issue architecture: establish PHP 8.4 persistence package contract, standards adoption and migration design #1 is the first issue.Maatify/persistence@1f6a7aafe601090b7e55f60d83794364afdefe67, Treec1e25e7653a3173c3339a269b1ad23b26f335b9d, final reconciled 10/10 CI #39985574051.Maatify/php-engineering-standardsobservation:main@5b69c03419ad09369ad207a9a7976cc9cc0617d3(not yet Owner-approved as an adoption pin). Re-check governance/version status before proposing the exact adoption commit; never use a floating source as the effective pin.maatify/persistenceis v1.4.0, PHP>=8.2; oldmaincontains separate UNRELEASED behavior/API changes. Old issue #37 remains RELEASE NO-GO and F4-04/#66 is unresolved. Do not conflate these three baselines.Execute the study defined in the Issue body
AGENTS.md, Adoption Standard in full, Decision Governance Standard + ACTIVE decision records relevant to the task, and the actual current candidate Profile/Canonical Standards text in full (not only headings). Resolvecomposer-packageandrepository-governancefor/via structural/transitive references then canonical applicability; list required local files and candidate exact pin, with version/frozen-state caveats.src/public types and actual signatures/behavior, using exact source files and relevant contract tests. Supply a three-column, evidence-cited matrix: Publishedv1.4.0vs oldmain@1f6a7aaUnreleased vs Proposedmaatify/php-persistenceAPI. Explicitly classify unchanged vs renamed vs intentionally redesigned vs omitted; do not silently portPageResultor assume a compatibility namespace.^8.4, Composer dependency/replace/conflict policy, PDO/MySQL and honest MariaDB qualification, consumer coexistence/migration & rollback, CI/real DB/consumer harness, docs and phase-specific gates. The proposed API must satisfy the current naming and architecture standards unless explicitly rejected by Owner.Delivery contract / hard stop
main, create branches, modify either repo, open PR, or publish.Current status: Issue #1 ACTIVE — READ-ONLY ARCHITECTURE STUDY ONLY.
megyptm commentedon Oct 23, 2026
📐 Architecture Study & Decision Register — Issue #1 (READ-ONLY) · [1/6] الملخص التنفيذي وقاعدة الأدلة
0. فهرس التسليم
v1.4.0/ OldmainUnreleased / Proposed) + مصفوفة السلوك1. قاعدة الأدلة المثبتة
[V]Maatify/php-persistence—PUBLIC،isEmpty=true،defaultBranchRef=""، 0 branches، Issue #1 هي الوحيدةgh repo view·gh api repos/Maatify/php-persistence/branches1f6a7aafe601090b7e55f60d83794364afdefe67· Treec1e25e7653a3173c3339a269b1ad23b26f335b9dgit rev-parse 1f6a7aa^{tree}successعلىheadSha=1f6a7aa…؛ 10 jobs ناجحة: Quality(8.2) · Unit/Regression(8.2/8.3/8.4/8.5) · Integration(8.2 وَ 8.5, MySQL 8.4.10) · Lowest(8.2, MySQL 8.4.10) · Workflow lint · CI Gategh run view 39985574051 -R Maatify/persistencev1.4.0→ commitfc1459b49fe5af5ead17814eeb3ada7a3fa81791· Treeb477b06d23fc2101581513ca97c0948259079b67؛ GitHub Release "Latest" (2026-09-18)؛ Packagist:v1.4.0الأحدث،php: >=8.2git rev-parse v1.4.0·gh release list·repo.packagist.org/p2/maatify/persistence.jsonsrc/: 21 → 26 ملف؛ 10 ملفات متغيرة (+843/−60): 5 مضافة، 5 معدلةgit diff --name-status v1.4.0 1f6a7aa -- srcgit ls-treeMaatify/php-engineering-standards@5b69c03419ad09369ad207a9a7976cc9cc0617d3= HEAD لحظة الدراسة (commit date 2026-10-23 14:47 +0300)؛ لا توجد tags في المستودع (git tagفارغ) ⇒ لا حالة finalized/versioned على مستوى المستودعgit log -1·git tagmaatify/exceptionsv1.0.0,v1.1.0؛php: ^8.2(v1.1.0)gh api …/tags· Packagistmaatify/php-persistenceعلى Packagistcurl repo.packagist.org/p2/maatify/php-persistence.jsonاصطلاح الإحالات:
A@path:L= المنشورv1.4.0(fc1459b) ·B@path:L= الـ main غير المنشورة (1f6a7aa) ·S@path:L= المعايير (5b69c03). الرابط الدائم:https://github.com/Maatify/persistence/blob/<SHA>/<path>#L<n>وَhttps://github.com/Maatify/php-engineering-standards/blob/5b69c03419ad09369ad207a9a7976cc9cc0617d3/<path>#L<n>.تصنيفات الحقائق:
[V]مثبت بمصدر/أمر قابل للإعادة ·[I]استنتاج المنفذ ·[P]تصميم مقترح ·[U]غير مُتحقق منه ·[OD-n]يحتاج اعتماد المالك.2. التوصية المختصرة
[P]اختيار البديل B (مفصّل في [4/6]): حزمة جديدة مستقلة
maatify/php-persistence(repophp-persistence) بدلًا من ترقيةmaatify/persistenceأو محاكاتها:maatify/php-persistence(مفروضة بنص Composer §7.1 للحزم الجديدة — لا بديل ولا انحراف مسموح).Maatify\PhpPersistence\متميز عنMaatify\Persistence\القديم ⇒ تعايش فعلي دونreplace/conflict/aliases/bridges[OD-02].Ordering/·Pagination/·Transaction/، مع اتجاه التبعيةOrdering → Transactionفقط؛ بلا جذر تقنيPdo/وبلاInternal/[OD-04].PageResult→PageResultDTO، marker→…ExceptionInterface، توزيع Responsibilities)، والإبقاء على أسماء/توقيعات بقية الأنواع لتقليل كلفة الهجرة؛ كل تغيير مصنّف KEEP/RENAME/REDESIGN/OMIT مع دليله[OD-05].mainغير المنشورة (lazy savepoint، clamp من locking read،getNextPositionForUpdate، deadlock-retry) كأساس للتصميم، لاv1.4.0وحدها؛ والـ runners القديمة المهملة تُحذف وتُدمج أجيالها تحت الأسماء البسيطة[OD-07][OD-08].php: ^8.4؛ ادعاء الدعم MySQL 8.4 فقط (المُتحقَّق منه فعلًا)، وMariaDB غير مدعومة/غير مُتحقق منها مع توثيق الفروق كمعلومة لا كوعد[OD-10].1.0.0-rc.1) ثم Stable[OD-13][OD-18].3. أهم النتائج التي تستحق انتباه Lead قبل أي قرار
maatify/persistenceوَ`Maatify\Persistence\Pdo\Orderingكمالك وحيد** لآليات ordering/pagination: PB §2 (S@standards/packages/PACKAGE_BUILDING_STANDARD.md:73-76)، §11 (:699-818)، §16 (:959-973، ويثبّت رابط المرجع علىfc1459b). لا يوجد نص استثناء أو مسار "خلافة"[V]`.{PackageName}(PB §4:141-150) غير معرَّف لمستودعاتphp-*. الممارسة المرصودة في 8 حزم عامة:Maatify\Category,Slug,I18n,RateLimiter,Eligibility,EventLogging,ReturnTarget,Seo(دونPhp)[V]⇒ الاشتقاق الحرفي =Maatify\Persistence\= جذر القديمة نفسه.OD-02S@standards/GITHUB_PHASE_STACK_WORKFLOW_AR.md:33-61،AI_COLLABORATION…:529-551)، بينما لا يمكن فتح PR دون base[V: defaultBranchRef=""].OD-13Mutable Candidateعند5b69c03(Adoption 5.0.1، Composer 5.0.0، CI 5.0.0، Library Presentation 5.0.1، AI Collab 13.0.0، Phase Stack 5.0.0) وحالة تجميد PB 4.0.0/Testing 3.0.0/Doc-Lifecycle 3.1.0 غير قابلة للإثبات[U]. Adoption أول سيُجمّدها فعليًا (Adoption §5.1.1). قواعد PHP 8.4 والتسمية والـtopology موجودة أيضًا في commit أقدم (2ea426a, PB 3.0.2)[V]؛ ما يضيفه5b69c03للإصدار هو خصوصًا Release/Published Artifact Verification (CI/LP 5.0.0).OD-11mainالقديمة تحمل تغييرات سلوكية غير منشورة (#33 clamp، #55 savepoint، API جديد، runners جديدة) — لا يجوز تسميتها "unchanged" مقابلv1.4.0.OD-07services:+docker exec)، ولا Integration على PHP 8.4 (8.2/8.5 فقط)، وMySQL 8.4.10 فقط.:902-905) يمنع SQL في Service بينماPdoPaginator/ScopedOrderingManagerيبنيان وينفذان SQL.OD-04PageRequest/PageResultالأكثر استخدامًا؛PdoTransactionRunner/PdoSavepointTransactionRunnerمستخدمة مباشرة؛ مستهلك واحد على الأقل خاص (غير مُسمّى هنا لأن هذا Issue عام).PageResult→PageResultDTOوَ runners على الهجرة حقيقي.COMPOSER_PACKAGE_PROFILE.md(ضمن Control Set) يشير إلىEXTERNAL_PROVIDER_VERIFICATION_STANDARD.mdالمستبعد بـ Stage 2؛ وفحص الإغلاق الميكانيكي يُغلق كل المعايير المنطبقة بلا أي خروج؛ فهذا الرابط هو الاستثناء الوحيد[V].4. حدود هذا التقرير
[I]والتصميم[P]ليست حقائق؛ كل ما يحتاج اعتمادًا مرقّمOD-nفي [6/6].الروابط: 2/6 · 3/6 · 4/6 · 5/6 · 6/6. بعد [6/6] أتوقف.
megyptm commentedon Oct 23, 2026
[2/6] دراسة المعايير: Profile Resolution · Canonical Applicability · Pinned Adoption المقترح
2.1 سجل القراءة (Reading Ledger) — بصدق
AGENTS.mdstandards/STANDARDS_ADOPTION_STANDARD_AR.mdstandards/profiles/COMPOSER_PACKAGE_PROFILE.md·REPOSITORY_GOVERNANCE_PROFILE.mdpackages/PACKAGE_BUILDING_STANDARD.mdpackages/COMPOSER_PACKAGE_STANDARD.mdpackages/CI_WORKFLOW_STANDARD.mdpackages/LIBRARY_PRESENTATION_STANDARD.mdtesting/TESTING_STANDARD.mdgovernance/DOCUMENTATION_LIFECYCLE_STANDARD_AR.mdgovernance/DECISION_GOVERNANCE_STANDARD_AR.mdphp/PHP_CODING_STYLE_STANDARD.md·php/PHP_SOURCE_DOCUMENTATION_STANDARD.mdintegrations/EXTERNAL_PROVIDER_VERIFICATION_STANDARD.mdai/AI_COLLABORATION_WORKFLOW_AR.mdGITHUB_PHASE_STACK_WORKFLOW_AR.mddocs/decisions/DECISIONS_INDEX.mdACTIVEاستُخدم فيها صف الـIndex والمعيار المالك المقروء كاملًا؛ سجلات DEC-023/030/031/032 وغيرها لم تُقرأ[U]governance/STANDARD_VERSIONING_POLICY_AR.md:101)2.2 Stage 1 — Structural / Transitive Resolution
Activations المقترحة (Adoption §6
:250-307):composer-package/repository-governance/project-host:263-277)لا يوجد
Extends⇒ لا Profiles موروثة ⇒ Control Set = 3 ملفات.Candidate Standard References (اتحاد المراجع المباشرة، بترتيب Profile):
13 مرجعًا مباشرًا ⇒ 12 مرشحًا فريدًا. سلامة بنيوية: كل المراجع موجودة عند
5b69c03[V](فحصos.path.existsعلى الشجرة المستنسخة).2.3 Stage 2 — Canonical Applicability ⇒ Final Resolved Applicable Standards Set
:18-35: مكتبات PHP/Composer قابلة لإعادة الاستخدام؛ القواعد الشرطية تنطبق لأن الحزمة تملك سلوك SQL/PDO. DEC-005:89-93: "standalone reusable PHP Composer libraries":9: standalone Composer packages:57-63:75-94: "Every standalone reusable Package"؛ §4.7 Host فقط:14-16: ينطبق فقط على Provider Contract Owner؛ MySQL خدمة repository-controlled/provisionable (§3:32). استبعاد Stage 2 ليس Exception (Adoption §7:345، §16.3:679):15-21[I][I]:13-17: وجودdocs/decisions/DECISIONS_INDEX.mdإلزامي ولو دون قرارات⇒ Final Resolved Applicable Standards Set = 11 معيارًا. الـ Final Set + Control Set = 14 ملفًا upstream +
STANDARDS_MANIFEST.md(محلي).Local Reference Closure (Adoption §7.1
:347-363) — فحص ميكانيكي[V]: كتبتُ سكربتًا مؤقتًا (خارج المستودعين) يستخرج الروابط النسبية من كل ملف في المجموعة (بعد حذف كتل الكود) ويتحقق من أن الهدف ضمن Control Set ∪ Final Set.السكربت والنتيجة (قابلان للإعادة)
النتيجة: كل الـ11 معيارًا + Adoption + REPOSITORY_GOVERNANCE_PROFILE = closed؛ الاستثناء الوحيد
COMPOSER_PACKAGE_PROFILE.md⇒../integrations/EXTERNAL_PROVIDER_VERIFICATION_STANDARD.md(موجود upstream، مستبعد من Final Set).[I]الرابط الخارج عن المجموعة موجود في Profile manifest (جزء من Control Set) وليس في Standard منطبقة؛ نص §7.1 يخص "Standard منطبقة" ويصرّح (:159) بأن مراجع Profiles اللازمة للحل البنيوي تبقى ظاهرة في الملفات المثبتة. أرى هذا Resolved لكنه يستحق تثبيتًا صريحًا عند Adoption: إن عامله الـvalidator كـ"broken closure" فهو عيب upstream (Adoption يمنع نسخ المستبعد لإبقاء رابط حيًا:349-351) ويُرفع كـFinding upstream لا كاستثناء (DEC-045).2.4 Pinned Adoption المقترح (بانتظار قرار المالك)
الملفات المحلية (Adoption §8
:369-404؛ لا يُنسخdocs/decisions/ولا Profiles/Standards غير المنطبقة، ولاSTANDARD_VERSIONING_POLICY_AR.md):محتوى
STANDARDS_MANIFEST.mdالمطلوب (Adoption §9:406-440): Upstream Repository · Adoption Commit · تاريخ · Control Set · Active Profiles + Versions + Scope · Final Resolved Applicable Standards Set (11 فقط + إصداراتها، دون المستبعد) · Explicit Additional Standards: None · Explicit Exceptions/Overrides: None ·Pinned Operational Assets Set: غائب (= لا Operational Assets، صحيح بنص:105-111)[OD-12].AGENTS.mdالمحلي (AI Collab §1.2:38-46، Adoption §10:459-461): يشير إلىSTANDARDS_MANIFEST.mdوAdoption Standard فقط، يُلزم بقراءة AI Collaboration، ويسجّل قواعد المشروع الخاصة دون تكرار قواعد عامة. الأولوية: تعليمات المالك ←AGENTS.md← مصادر المشروع (المعايير/ADRs/Package Reference) ← توجيه المهمة ← المعيار العام (AI Collab §1.3:48-60).خيارات الـPin (جدول مقارنة
[V]منgit show <commit>:<file>):7dd9d1d(2026-09-22)5f872d3(2026-10-01)2ea426a(2026-10-04)5b69c03(2026-10-23)5b69c03:27-29، topology، التسمية) وعقد الإصدار الأحدث: Release Artifact Verification وPublished Artifact Verification (CI 5.0.0:79-117) وهوية Release Artifact (LP 5.0.0:260-278، DEC-030) وهي غير موجودة في2ea426a[V: grep]. الثمن: ستة معاييرMutable Candidate+ حالة تجميد PB/Testing/Doc-Lifecycle غير قابلة للإثبات[U]⇒ Adoption أول يجمّدها فعليًا (Adoption §5.1.1:218-240)2ea426a:1487، CI Std:521)[V: grep عند 2ea426a]، وبعض إصداراته مثبتة كـFrozen Baseline بأدلة مستهلك (Composer 4.1.0، CI 4.0.0). لكن يفتقد RAV/PAV وهوية Release Artifact (CI/LP 5.0.0) ومعها Adoption 5.0.x وواجبات AI Collab 11–13 ⇒ يستلزم Upgrade عند الاقتراب من RC. فرق PB 3.0.2→4.0.0 نفسه تصحيح لحدود Ordering الخاصة بالمستهلكين فقط (§11)[V: git diff]توصيتي
[P]: (P-B بديل محافظ مشروع إن فضّل المالك Frozen Baselines وقبل Upgrade لاحق). المرشح للاعتماد =5b69c03419ad09369ad207a9a7976cc9cc0617d3بشروط: (1) قبول المالك الصريح أن Adoption يجمّد المرشحات (OD-11)؛ (2) عند بداية WU-2 يُعاد التحقق من HEAD upstream والـ version table وسكربت الإغلاق، وإن تحرك HEAD يُقيَّم الفرق ولا يُرقّى تلقائيًا (Phase Stack §7:371-378يثبت الـSnapshot طوال الـTrain)؛ (3) التحقق byte-for-byte لكل ملف مقابلgit show <commit>:<path>(سابقة المستهلكين). حالة تجميد Profiles (4.0.0/3.0.0):[I]مدعومة بنصوص السجل، غير مثبتة بمقارنة blob مع manifest مستهلك ⇒ إن تعذر الإثبات تكون النتيجة نصًّاOWNER DECISION REQUIRED — VERSION BASELINE STATUS(Adoption:234-240).2.5 مصفوفة امتثال/تبنٍّ مؤقتة (Provisional) — ما يشكّل التصميم
:27-29) · تسمية*Interface/*Enum/*DTO/*Exception(:152-171) · topology موحّدة معلنة في Package Reference (:175-229) ·Responsibilityvocabulary (:231-269) · لا جذر تقنيPdo/(:291-308) · لاInternal/(:310-312) · marker{PackageName}ExceptionInterface(:443-455) · rollback + إعادة رمي الأصل (:524-549) · SQLSTATE vs driver-code (:498-505) ·final readonlyDTO (:591-629) · PHPStan max بلا baseline (:1044-1067) · txn/concurrency (:1191-1203) · تصنيف Operational Read/Reporting (:917-955)maatify/php-{domain}(:237-244) · PSR-4src/·^8.4(:549-569) ·requireللـext-pdo(+ext-pdo_mysql؟) · لاversionولاcomposer.lock(:1122-1137) · لاreplaceبلا موافقة معمارية (:749-763) · scripts القياسية (:861-931) ·config.policyfail-closed (:1036-1096) · archive لا يستبعد ملفات إلزامية (:810-819,:1141-1171):26-32) · Compose للـIntegration (:317-343) · matrix 8.4+latest (:228-246) · lowest/latest · audit fail-closed (:272-296) · actions مثبتة بالـSHA (:365-386) · stable gate (:424-437) · Release Artifact Verification وPAV (:79-117):75-94) · Unit/Integration/System · RED/GREEN للعيوب المثبتة (:134-137)README,CHANGELOG,SECURITY,CONTRIBUTING,CODE_OF_CONDUCT,LICENSE, Package Reference,docs/guides/USAGE_GUIDE.md,examples/,llms.txt(:126-148) · RC → Harness → ≥2 Hosts → Stable (:572-594) · Release Artifact identity (:260-278)[U]:46-54) وPHPDoc بالإنجليزية (:56-81) · لا ملفات لكل Work Unit (:139-151):66-98)[U]— يُتحقق منه في WU الهيكلFresh Full Acceptance· Pre-Release Strict Lead Acceptance قبل RC/Stable (§13.1.2:1414-1655):33-61) · Batch/Draft · Standards Freeze (:371-378) · بوابات الدمج الأربع (:461-555) · Post-Merge Verification (:565):73-87)2.6 تناقضات وفجوات في المعايير نفسها (لا اختراع استثناءات)
[V]maatify/persistenceمالكًا وحيدًا لـordering/pagination ويحظر "نسخًا محلية" ويجعل القدرة الناقصة تُقترح داخله:73-76("Persistence Utilities … must depend onmaatify/persistence")،:76(Rule: لا duplicates)،:703-708(Authoritative owner)،:806-812(Missing Capability)،:816-818(Source of Truth)،:973(مرجع مثبّت علىfc1459b)[I]النص يخاطب الحزم المستهلِكة ولا يتناول حزمة خلف تحل محل المالك؛ لكنه يعبّر عن افتراض تصميمي "حزمة مشتركة واحدة". لا يوجد استثناء متاح (Decision Governance:269-275: قرار المستودع لا يجعل انحرافًا ممنوعًا متوافقًا). المسار الصحيح: قرار مالك + تعديل معياري مستقل يسجّل الخلافة، بعد/مع الإصدار الأول (يتسق مع ترتيب #37: "أصدر الحزمة أولًا ثم حدّث حقائق المعايير")OD-03{PackageName}غير معرَّف لـphp-*:143-150، Composer:237-244؛ 8 حزم عامة تستخدم الاسم بدونPhp(composer.jsonلـphp-category/slug/i18n/rate-limiter/eligibility/event-logging/return-target/seo)OD-02؛ ويُرفع توضيح upstream:33-61,:95-103؛ AI Collab:529-551؛ لا ذكر لـ"initial/first commit" أو "empty repository" في أي معيار من المجموعة (grep -iعلى AI Collab وPhase Stack وAdoption وgovernance/ وpackages/؛ كلمة "bootstrap" ترد فقط بمعنى إصدار تأسيسي للمعيار أو DI):296-304)OD-13:231-269مقابل:902-905(Services never contain raw SQL)Repository/للمنفّذات التي تبني/تنفذ SQL،Service/للـrunners التي تنفذ أوامر تحكم (SAVEPOINT,DO 0) فقط — تفسير يُعتمدOD-04Internal/غير canonical لكن الحاجة لأنواع@internalقائمة:310-312@internalفي PHPDoc، لا مجلدInternal/OD-11:572-594[U]أي Hostين؟ (admin-control-panel عام؛ الثاني خاص) — يحتاج تحديد المالكOD-18:317-343مقابل ci.yml القديم2.7 قرارات مركزية
ACTIVEذات صلة (منDECISIONS_INDEX.md)DEC-002(Profiles مستقلة) ·DEC-005(Persistence Applicability) ·DEC-008(Final-class testing) ·DEC-009(Selective Pinned Adoption) ·DEC-012(llms.txt) ·DEC-013(Profile resolution) ·DEC-017(PR لكل branch منشورة) ·DEC-018(إسناد التنفيذ للـLead صريح) ·DEC-023(Strict Acceptance قبل RC/Stable) ·DEC-025(Optional Runtime Capability: لا ينطبق—ext-pdoأساسي) ·DEC-030(Release Artifact Self-Consistency) ·DEC-031/032(Operational Assets—غير معتمدة افتراضيًا) ·DEC-033/041(سلامة الأدلة/Post-Merge) ·DEC-038/043/044/045/047(Lead/Executor duties) ·DEC-046(عمليات الحالة المشتركة: تسجيل Packagist ونشر الحزمة خارج الاختبارات المعزولة تحتاج تفويض مالك) ·DEC-042(عدم ذكر مشاريع مستهلِكة بعينها في المعايير المركزية — لا يقيّد هذا التقرير).megyptm commentedon Oct 23, 2026
[3/6] الجرد الشامل: مصفوفة العقود الثلاثية + مصفوفة السلوك
الأعمدة: A = Published
v1.4.0(fc1459b) · B = OldmainUnreleased (1f6a7aa) · C = Proposedmaatify/php-persistence(P\=Maatify\PhpPersistence\— الاسم نفسه قيدOD-02).المسارات نسبية إلى
src/؛Pdo/…يعنيsrc/Pdo/…؛:N= رقم السطر في الملف نفسه عند ذلك الـSHA. الأعمدة الخاصة بالتصنيف:KEEP= نفس الاسم القصير والتوقيع العام (لكن الـFQCN يتغير دائمًا) ·RENAME·REDESIGN·OMIT.قابلية الإعادة:
git ls-tree -r --name-only v1.4.0 -- src(21 ملف) ·… 1f6a7aa -- src(26) ·git diff --name-status v1.4.0 1f6a7aa -- src(5 مضافة + 5 معدلة) · التوقيعات:git show <sha>:<path> | grep -nE '^(final readonly class|interface|enum) |^ public (static )?function'.3.1 مصفوفة الأنواع العامة (26 ملفًا في B)
أ) Exceptions
Exception/PersistenceException.php:17interface … extends \Throwable:17P\Exception\PhpPersistenceExceptionInterface:163-167وَ §7:443-455:{PackageName}ExceptionInterface. استثناء "Legacy Published Marker":457-471خاص بالحزمة ولا يُنسخ لحزم جديدة (:468). المرجع القديم يوثّق الاحتفاظ بالاسم طوال1.x(PERSISTENCE_PACKAGE_REFERENCE.md:719-734). اختبارات النقل:tests/Regression/Exception/*Exception/InvalidOrderingConfigurationException.php:22final … extends SystemMaatifyException:22P\Ordering\Exception\InvalidOrderingConfigurationException:322(استثناء خاص بقدرة تحت{Capability}/Exception/).ErrorCodeEnum::MAATIFY_ERROR.tests/Regression/Exception/InvalidOrderingConfigurationExceptionTest.php:17,24,36,51…/InvalidOrderingOperationException.php:20extends ValidationMaatifyException(INVALID_ARGUMENT):22P\Ordering\Exception\InvalidOrderingOperationExceptiongetNextPositionForUpdateخارج معاملة (B@Pdo/Ordering/ScopedOrderingManager.php:174-178)…/InvalidPaginationConfigurationException.php:11:11P\Pagination\Exception\InvalidPaginationConfigurationExceptiontests/Regression/Exception/PaginationExceptionContractTest.php:25…/InvalidPaginationQueryException.php:11:11P\Pagination\Exception\InvalidPaginationQueryException…/PaginationExecutionException.php:11:11P\Pagination\Exception\PaginationExecutionException…ExceptionTest.php:44يثبت عدم وجود marker خاص بالـpagination…/TransactionExecutionException.php:11:11P\Transaction\Exception\TransactionExecutionExceptionB@Pdo/Transaction/Internal/OwnedTransactionExecutor.php:104-139…/InvalidTransactionConfigurationException.php:20P\Transaction\Exception\InvalidTransactionConfigurationExceptionOwnedTransactionExecutor.php:77-83؛DeadlockRetryRunnerPublicApiRegressionTest.php:129…/OrderingTransactionException.php:18@deprecated(UnsupportedMaatifyException):18نفسه:12-16)؛OrderingPublicApiRegressionTest.php:127,157تثبت بقاءها عامة ومهملة وعدم استخدامها. صفر قيمة لحزمة جديدة (PB:349: لا استثناء legacy لبنية لم تُنشر)ب) Ordering
Pdo/Ordering/ScopedOrderingConfig.php:29final readonly; ctor:40(table, scopeColumn, idColumn, orderColumn, deletedAtColumn, nullableScope, updatedAtColumn)؛quoted*():79-125P\Ordering\Config\ScopedOrderingConfig:147-216؛OrderingPublicApiRegressionTest.php:28؛tests/Unit/…/ScopedOrderingConfigTest.phpPdo/Ordering/ScopedOrderingManager.php:31؛getNextPosition:46·moveWithinScope:97·rowExistsInScope:176:48؛getNextPosition:79·getNextPositionForUpdate:167·moveWithinScope:270·rowExistsInScope:365P\Ordering\Repository\ScopedOrderingManagerPdoTransactionRunnerالمهملة (B:9,B:298) ⇒ يُعاد توصيله بالجيل الثاني؛OrderingPublicApiRegressionTest.php:59,94Pdo/Ordering/Internal/OperationSavepoint.php:30(@internal :28)@internalيُدمج مع منطق savepoint في TransactionOperationSavepointوَPdoSavepointTransactionRunnerوَPdoDeadlockRetrySavepointTransactionRunner[V](قراءة المصدر) ⇒ ثلاث نسخ متقاربةج) Pagination
Pdo/Pagination/PageRequest.php:7ctor:9(int|string|null $page, $perPage; ?string $sortBy, $sortDirection)P\Pagination\Criteria\PageRequest:581: مدخلات query تذهب إلىCriteria؛ لا قاعدة لاحقة.OD-05…/PageResult.php:13final readonly … implements JsonSerializable(@template T)؛toArray:38·jsonSerialize:59P\Pagination\DTO\PageResultDTO:593-629(DTO نتيجة،final readonly,JsonSerializable) وَ §4:159-161. المنشور مخالف (old #66 F4-04 مفتوحة). شكلtoArray()/jsonSerialize()ثابت (انظر B-08)…/PaginationConfig.php:9ctor:13P\Pagination\Config\PaginationConfig:23-31…/PdoPaginationQueryDescriptor.php:9ctor:19P\Pagination\Criteria\PdoPaginationQueryDescriptor;والبادئة المحجوزة:35-55…/PdoPaginator.php:11;paginate:25P\Pagination\Repository\PdoPaginatorPageResultDTO…/SortDirectionEnum.php:7enum … : stringP\Pagination\Enum\SortDirectionEnum*Enum(PB:160)…/SortWhitelist.php:9;contains:24·quotedIdentifierFor:32P\Pagination\ValueObject\SortWhitelist:74-88د) Transaction
Pdo/Transaction/TransactionRunnerInterface.php:7;run(callable):mixed :15P\Transaction\Service\TransactionRunnerInterfaceDeadlockRetryRunnerPublicApiRegressionTest.php:111(غير مهملة)…/SavepointTransactionRunnerInterface.php:7P\Transaction\Service\SavepointTransactionRunnerInterface…/PdoTransactionRunner.php:14ctor(PDO):16:20—@deprecatedلصالحPdoDeadlockRetryTransactionRunnerP\Transaction\Service\PdoTransactionRunnerبسلوك الجيل الثاني وctor(PDO $pdo, int $maxDeadlockRetries = 0)OD-08؛ delta سلوكي موصوف في B-10…/PdoSavepointTransactionRunner.php:16:23—@deprecatedP\Transaction\Service\PdoSavepointTransactionRunner(جيل ثانٍ)…/PdoDeadlockRetryTransactionRunner.php:44…/PdoDeadlockRetrySavepointTransactionRunner.php:39…/Internal/OwnedTransactionExecutor.php:51(@internal :49),MAX_DEADLOCK_RETRIES = 3 :53P\Transaction\Service\OwnedTransactionExecutor(@internalفي PHPDoc)Internal/ملخص الجرد
@internal.replace/alias/class_alias/bridge[P](Composer:749-763).3.2 مصفوفة العقد السلوكي
getNextPositionMAX(order)+1بقراءة عادية، بلا معاملة ولا قفل، مع تجاهل المحذوف ناعمًاA@Pdo/Ordering/ScopedOrderingManager.php:46buildScopeWhereB:79-97REPEATABLE READ(B docblock:61-75)OrderingPublicApiRegressionTest.php:94(القراءتان مدعومتان وغير مهملتين)؛tests/Integration/…/ScopedOrderingManagerReadOperationsTest.phpgetNextPositionForUpdateInvalidOrderingOperationException:174-178؛SELECT … ORDER BY order DESC, id DESC LIMIT 1 FOR UPDATE:185-192تتكرر حتى تتطابق قراءتان:199-214⇒ ≥2 قراءة قفل حتى لنطاق فارغ؛ نطاق فارغ بلا صف لقفله:125-127؛ تأخذ lock footprint واسعًا بلا فهرس(scope, order):128-141Bdocblock:100-166؛tests/Integration/Pdo/Ordering/ScopedOrderingManagerStaleSnapshotTest.php؛ أمثلةexamples/next-position/01–05؛ فاعلية MariaDB1020موثقة (:148-160)moveWithinScope— الـclampA:123ثمgetMaxPositionA:131(A:286-303) =SELECT COALESCE(MAX(order),0)بلا قفل ⇒ clamp قديم داخل snapshot أقدم في معاملة مستدعٍREPEATABLE READB:300,308(#33)ScopedOrderingManagerMoveStaleSnapshotTest.php:55,73,90,107,124,141,158,180,196,213,227,253,267,285· commita75a41a· #37 يذكر #33 كتغيير سلوكي ناجح يجب أن يظهر في ملاحظات الترقيةmoveWithinScope— معاملة المستدعي والفشلfalseبعد الإزاحات لا يتراجع عن إزاحاته (يبقى القرار للمستدعي)B:295,315؛cleanupAfterFailure :332-336·undoOrFailعندfalse:338-342·releaseOrUndo :344؛ لا savepoint للـno-op أو الصف المفقود؛ يرميTransactionExecutionExceptionقبل أي mutation إن كانت المعاملة انتهتOperationSavepoint.php:49-51ScopedOrderingManagerLazySavepointTest.php:116,136,155,180,206,240,276,298,316,340,353,365,379,391· ADR 0005 · #37 يصف #55 "published-behavior failure-path change"[V: نص #37]moveWithinScope— المسار المملوكPdoTransactionRunner(v1): begin → callback → commit؛false⇒ sentinel ⇒ rollback ⇒ يعيدfalseB:298beginTransaction()/commit()يعيدانfalseبدل رمي (نمطERRMODE_SILENT)ScopedOrderingManagerTransactionTest.php:160,171,184؛LazySavepointTest.php:379,391trueعند النجاح،trueإن كان الصف في الموضع المطلوب،falseإن غاب الصفBdocblock:231-235)rowExistsInScopeA:176B:365نفس المنطقpage/perPageperPageيُقيَّد بـ[min,max]؛ تحليل نصي بحدودPHP_INT_*PdoPaginator.php:74-119PdoPaginatorNormalizationTest.php:21,56,79,113:121-143؛ORDER BYمقتبس + tie-breaker مختلف إن لزم:262-269PaginationSqlContractRegressionTest.php:21total,filtered) صفّ/عمود واحد فقط، سالب/أكبر منPHP_INT_MAXمرفوض:146-164,240-260PdoPaginatorFailureTest·…FailureContractTestfiltered=0⇒ نتيجة فارغة صفحة 1 بلا استعلام بيانات:42-44؛page>totalPages⇒ صفحة 1:46-48PaginationSqlContractRegressionTest.php:58LIMIT/OFFSETبـPARAM_INTوأسماء محجوزة__pagination_*:15-16,54-55,190-197PdoPaginationQueryDescriptorTesttests/Integration/Pdo/Pagination/PdoPaginatorTransactionTest.php:14[I]PdoPaginator.php:38-57PageResult— الثوابت والشكلassertValid :79-98(قائمة، عناصر array|object،page≥1،perPage≥1،count≤perPage، صيغةtotalPages، حالة فارغة، أعلام التنقل)؛ مفاتيح JSON:data+pagination{page, per_page, total, filtered, total_pages, has_next, has_previous, sort_by, sort_direction}:38-53:793: لا تغيير صامت لشكل الاستجابة؛PageResultTest·PaginationPublicApiRegressionTest.php:80A@Pdo/Transaction/PdoTransactionRunner.php:26-44: يشارك إن كانت المعاملة نشطة؛ وإلا begin→callback→commit؛Throwable⇒ rollback-if-active (فشل rollback يُبتلع) ⇒ إعادة رمي الأصل. قيمة إرجاعbegin/commitغير مفحوصةOwnedTransactionExecutor.php:99-143:begin()==false⇒TransactionExecutionExceptionقبل الـcallback؛commit()==false⇒ rollback best-effort ثمTransactionExecutionExceptionPdoDeadlockRetryRunnerIntegrationTest.php:216·DeadlockRetryRunnerFailClosedTestSAVEPOINT maatify_persistence_sp_<32hex>→ callback →RELEASE؛ فشل callback ⇒ROLLBACK TO+RELEASEbest-effort وإعادة رمي الأصل؛ فشل RELEASE ⇒ cleanup ثم رمي فشل RELEASEA@Pdo/Transaction/PdoSavepointTransactionRunner.php:33-59maatify_persistence_sp_<32 hex>موثّقة وتُختبر ⇒ تُبقى كما هي (انظر ملاحظة التصميم 4.6)PdoSavepointTransactionRunnerTest.php:92·…ParityTest.php:99·…RetryTest.php:124,147,148maxDeadlockRetries ∈ [0,3]وإلاInvalidTransactionConfigurationException:77-83؛ لا إعادة افتراضيًا (0)؛ لا إعادة إلا إذا: المعاملة مملوكة، والـcallback رمىPDOExceptionبـerrorInfo[0]='40001'وerrorInfo[1]===1213:145-156، وبقي عدد محاولات، والسائق ما زال يُبلغ معاملة ثمDO 0ينجح ويُبلغ لا معاملة:166-181؛ تأخير: لا شيء / 0–10ms / 0–20ms:194-207؛ لا إعادة: معاملة المستدعي · فشل BEGIN/COMMIT ·1205· غير ذلك؛ المحاولة الأخيرة تُعيد رمي الاستثناء الأصليPdoDeadlockRetry*)PdoDeadlockRetryTransactionRunnerTest.php:50…321(14+)؛ تكامل حقيقي:PdoDeadlockRetryRunnerIntegrationTest.php:35,57,81,111,145,182,216,238·OwnedTransactionExecutorTest· ADR 0004 ("Owner-accepted limit")PDOException/Throwableالخارجية تمر كما هي؛ rollback للمملوك فقط؛ فشل التنظيف لا يستبدل الأصل؛ الاستثناءات المسماة للتكوين/التنفيذ/المدخلات فقط:437-441)OperationSavepoint.php:21-25· runnersScopedOrderingConfig.php:189,SortWhitelist.php:87)،FOR UPDATE،SAVEPOINT،DO 0(OwnedTransactionExecutor.php:57) ⇒ لهجة MySQL/MariaDB؛requireفيهext-pdoفقط (composer.json)ext-pdo+ (ext-pdo_mysql؟)OD-10schema/README.md؛ المرجع القديم:49-57php >=8.2·ext-pdo·maatify/exceptions ^1.0php ^8.4·ext-pdo· (ext-pdo_mysql) ·maatify/exceptions ^1.0؛ صلاحية الحد الأدنى على 8.4 تُثبت بوظيفة lowest[U]:549-569.gitattributesexport-ignoreلنتائج Issue #32 الخام (commitaaafab6, PR #62).gitattributesأدنى؛ ملفات Composer §26 لا تُستبعد:1141-11713.3 أثر الهجرة بحسب النوع (SemVer / Consumer)
composer require maatify/persistence→maatify/php-persistenceuseMaatify\Persistence\Pdo\{Ordering,Pagination,Transaction}\X→Maatify\PhpPersistence\{Ordering,Pagination,Transaction}\<Resp>\Xuseميكانيكية قابلة للتحقق بـPHPStan)PageResult→PageResultDTOinstanceof؛ المصفوفة/JSON ثابتانPersistenceException→PhpPersistenceExceptionInterfacecatch[U]لم يُحصَPdoTransactionRunner(PDO)→ نفس الاسم، ctor(PDO, int=0)begin/commit=false(B-10)moveWithinScopeOrderingTransactionExceptionv1.3.0(CHANGELOG.md§[1.3.0] Deprecated؛OrderingPublicApiRegressionTest.php:157)getNextPositionForUpdatemegyptm commentedon Oct 23, 2026
[4/6] ما لا يُنقل · البدائل المعمارية · التوصية · التصميم المقترح
4.1 ما لا يُنقل إلى المكتبة الجديدة (ومبرراته)
[V]PageResultبلا لاحقةDTO:159-161, §9:593-629)؛ منشور منذv1.1.0؛ old #66 (F4-04) مفتوحة (NON-COMPLIANCE / Owner policy conflict) ولا استثناء مسجلB@Pdo/Pagination/PageResult.php:13؛ نص #66PageResultDTO(T-14) — بلا تغيير في القديمةPersistenceExceptionبلاInterface:163-167؛ استثناء "Legacy Published Marker" لا يُنسخ لحزم جديدة:468…Exception/PersistenceException.php:17؛ المرجع القديم:719-734PhpPersistenceExceptionInterface(T-01)src/Pdo/…src/Pdo/" (PB:308)؛ التقنية جوهرية لهوية الحزمة كلها فلا تتكرر كمجلد (:308)src/Pdo/{Ordering,Pagination,Transaction}Ordering/ · Pagination/ · Transaction/Internal/Shared/,Helpers/,Utils/,Internal/are not canonical" (PB:312)Pdo/Ordering/Internal/,Pdo/Transaction/Internal/@internalفي PHPDoc داخل Responsibility المالكة (S-5)src/Exception/مجمّع لكل القدرات{Capability}/Exception/والجذر للـmarker فقط (PB:314-322):231-269(Config/Criteria/DTO/ValueObject/Enum/Repository/Service)OrderingTransactionExceptionv1.3.0)CHANGELOG.md[1.3.0] Deprecated؛OrderingPublicApiRegressionTest.php:157PdoTransactionRunner/PdoSavepointTransactionRunner(الجيل 1)@deprecatedفي B لصالح الجيل 2؛ لا تتحقق من إرجاعbegin/commitB:Pdo/Transaction/PdoTransactionRunner.php:14-18PdoDeadlockRetry*0= لا إعادة؛ لم تُنشر قطPdoDeadlockRetryTransactionRunner.php:53OD-08)executeControlStatement/tryControlStatementمكررتان فيOperationSavepoint.php:98-114وPdoSavepointTransactionRunner.php:73-78,106-115وPdoDeadlockRetrySavepointTransactionRunner.php:94-99,127-136(+ منطق cleanup المتقارب)؛ScopedOrderingManager.php:9,298@internal(T-12)docs/php-engineering-standards/(Adoption قديم)44c8827(Adoption 2.0.0 / PB 1.4.0 …) ⇒ الحزمة الجديدة تتبنى مستقلةdocs/php-engineering-standards/STANDARDS_MANIFEST.mddocs/studies/**(+harness/*.phpداخلdocs/)،docs/adr/*:296-304)؛ كود PHP داخل docs ليس مكانهgit ls-tree:41-45: الدعم المُعلن يلزمه تنفيذ واختبار حقيقيان؛ توفر driver ≠ دعمschema/README.md, المرجع القديم:49-57; #51 أُغلقت ضمن نطاق MySQL فقطphp >=8.2·platform.php 8.2.0:27-29+ Composer:549-569للحزم الجديدةcomposer.json^8.4·8.4.0:317-343؛ وPHP 8.4 بلا Integrationci.yml(jobs المسرودة في [1/6])Maatify\Persistence\composer.jsonالقديمMaatify\PhpPersistence\(OD-02)ما يستحق النقل عبر WUs مراجَعة (مع provenance: SHA المصدر في PR): منطق الأنواع بعد إعادة التموضع (T-10…T-26)، اختبارات Unit/Regression/Integration ذات الصلة بعد إعادة التسمية،
tests/Fixtures/MySql/*.sqlوَtests/Support/MySql/*(بعد مراجعة أسماء الجداول وفقmaa_{package_short_name}_PB:414)، Consumer Harness (يُكتب من جديد على Composer root خارجي)، أمثلةexamples/*(بعد تكييف)، ومحتوى المرجع/الأدلة (إعادة صياغة للهوية الجديدة؛ منع النسخ الحرفي وفق LP §22:850-865).4.2 البدائل المعمارية
maatify/persistence: إماv1.5.0additive (PageResultDTOجديد + إهمالPageResult،php >=8.2) أوv2.0.0Major (^8.4+ إعادة تسمية كاملة)>=8.2. يبقى جذرPdo/المحمي بتوافق v1 ما لم يصدر Major (PB «Deferred Structural Obligation»:343-406). مرجع للمقارنة فقطmaatify/php-persistence، namespace مميز، إعادة تموضع كاملة وفق المعايير الحالية، سلوك أساسه B، تعايش بلاreplace، حزمة واحدة Multi-CapabilityrequireالقديمMaatify\Persistence\(اشتقاق حرفي)php-ordering·php-pagination·php-transaction)Orderingيعتمد علىTransaction؛ يضاعف CI/RC/Hosts ×3؛ مخالفة لافتراض مستودع واحدphp-persistence؛ لا أدلة حدودية مستقلة تدعمهاclass_alias/bridge/replace/provide)replaceيحتاج موافقة معمارية صريحة ولا يجوز إخفاء الازدواج به (Composer:749-763)؛ والـIssue يحظر وعد توافق مخادعمقارنة معللة (B مقابل A):
Pdo/وPageResultمحميان بالتوافق>=8.2للمنشور^8.4ما لم يصدر Majorphp-persistence4.3 التصميم المقترح
[P](يُجمَّد في Package Reference/ADR بعد اعتماد المالك)4.3.1 الهوية والـ Namespace
maatify/php-persistence· repo:php-persistence(Composer:237-244؛ لا انحرافات)."Maatify\\PhpPersistence\\": "src/"· dev:"Maatify\\PhpPersistence\\Tests\\": "tests/"(COMPOSER :478-537).Maatify\PhpPersistence\Exception\PhpPersistenceExceptionInterface.php-persistence → PhpPersistence) تفسير لـ{PackageName}غير منصوص (F-2/S-2) فيُعتمد صراحةً ويُرفع توضيح upstream.PHP_PERSISTENCE_PACKAGE_REFERENCE.md(الجذر، الصيغة{PACKAGE_NAME}_PACKAGE_REFERENCE.mdPB:96-137) لتمييزه عنPERSISTENCE_PACKAGE_REFERENCE.mdالقديم.4.3.2 Source Topology (يُعلن حرفيًا في Package Reference — PB
:183-201)Ordering → Transactionفقط؛PaginationوTransactionمستقلان؛ لاCommon/.:229).OD-04، يعالج S-4): المنفّذات التي تبني/تنفذ SQL (ScopedOrderingManager,PdoPaginator) ⇒Repository/(حدود persistence/query)؛ الـrunners تنسّق callback داخل معاملة وتنفذ فقط أوامر تحكم (SAVEPOINT,RELEASE,ROLLBACK TO,DO 0) ⇒Service/. البديل: وضع الجميع فيService/مع تفسير موثّق لـPB:902-905.4.3.3 Composer (مخطط مقترح؛ الحقول بالترتيب القانوني
COMPOSER :173-211){ "name": "maatify/php-persistence", "description": "Direct-PDO ordering, pagination, and transaction utilities for MySQL.", "keywords": ["persistence","pdo","mysql","ordering","pagination","transaction","savepoint","php","maatify"], "homepage": "https://github.com/Maatify/php-persistence", "type": "library", "license": "MIT", // OD-14 "authors": [{"name":"Maatify","email":"support@maatify.dev","homepage":"https://maatify.dev"}], "support": {"issues":"…/php-persistence/issues","source":"…/php-persistence","security":"…/security/policy"}, "autoload": {"psr-4": {"Maatify\\PhpPersistence\\": "src/"}}, "autoload-dev": {"psr-4": {"Maatify\\PhpPersistence\\Tests\\": "tests/"}}, "require": {"ext-pdo":"*", /* "ext-pdo_mysql":"*" ← OD-10 */ "maatify/exceptions":"^1.0", "php":"^8.4"}, "require-dev": { /* phpstan, php-cs-fixer, phpunit, (symfony/process إن لزم Partner-process) — أحدث مستقر متوافق */ }, "scripts": {"analyse":…, "format":…, "test":…, "test:unit":…, "test:regression":…, "test:integration":…, "test:consumer":…}, "config": {"optimize-autoloader":true,"sort-packages":true,"platform":{"php":"8.4.0"} /* + policy.* Composer §23.5 */}, "minimum-stability":"stable","prefer-stable":true }لا
versionولاcomposer.lockولاrepositoriesولاreplace/conflict/provide(بلا حاجة مبرَّرة).ext-pdoأساسي فلا ينطبق DEC-025 (Optional Capability). حدmaatify/exceptions ^1.0موروث ومُجرَّب lowest على PHP 8.2 في القديمة؛ على 8.4[U]ويُثبت بوظيفة lowest الجديدة (v1.0.0 على Packagist لا يعلن قيد php في البيانات الوصفية المقروءة).4.3.4 PHP 8.4
php ^8.4فقط (لا حد أعلى، Composer:567). لا إعادة كتابة مجانية بميزات 8.4؛final readonly classموجودة. مصفوفة CI: الحد الأدنى 8.4 + أحدث مستقر (8.5 عند الدراسة[U]يُعاد التحقق عند WU-CI) + أي minor وسيط. خطر معروف[U]: منطق إعادة المحاولة يعتمد على أنpdo_mysqlيشتقPDO::inTransaction()من آخر رد خادم (OwnedTransactionExecutor.php:28-35)؛ القديمة اختبرت Integration على 8.2 وَ8.5 فقط ⇒ لا دليل Integration على 8.4 ⇒ يلزم الجديد تشغيله على 8.4 و8.5.4.3.5 قاعدة البيانات
pdo_mysql(المُتحقق منه فعلًا: 8.4.10 في CI القديمة[V]).innodb_snapshot_isolation=ON⇒1020، ورد savepoint guard على 11.8.9 دون 11.4.7) معلومات سلوكية وليست دعمًا (المرجع القديم:124,145,151)؛ لا تُوعد بمجرد تشابه SQL. فتح الدعم يتطلب قرار مالك + مصفوفة Compose بصورة MariaDB + اختبارات مخصصة (WU مستقلة لاحقة).المرجع :151لكنه ليس ضمن مصفوفة CI).mysqlفقط، لاmariadb) والوصف (Composer:320).4.3.6 الاستثناءات (PB §7
:426-549)maatify/exceptionsكما هي (SystemMaatifyExceptionللتكوين/التنفيذ،ValidationMaatifyExceptionلمدخلات العملية).4.3.7 عقد Ordering/Pagination/Transactions (يُجمَّد حرفيًا من B-01…B-13)
getNextPosition(عادية)،getNextPositionForUpdate(تتطلب معاملة)،moveWithinScope(قفل نطاق ثم clamp من قراءة القفل؛ savepoint كسول عند المشاركة)،rowExistsInScope. الضمانات مشروطة بالمحرك (MySQL 8.4) وتُوثَّق.maxDeadlockRetries∈ [0,3]؛ replay فقط للمعاملة المملوكة وبشروط B-12؛ المعاملة التي يملكها المستدعي لا تُعاد أبدًا.maatify_persistence_sp_<32 hex>تبقى (موثقة ومُختبرة؛ العشوائية 128-bit تمنع التصادم بين الحزمتين المتعايشتين).4.3.8 تصنيفات الحزمة المطلوبة في Package Reference
[I]:917-955): Out of Scope — الحزمة آلية بنية تحتية لا تملك حالة تشغيلية/نطاقية خاصة بها (لا جداول مملوكة؛schema/README.mdالقديم يقول ذلك)، فلا تُخترع واجهات تقارير.updatedAtValueنص يمرره المستدعي).:993-1002).:410-422):schema/README.mdفقط يشرح أن الحزمة لا تملك جداول وأن ما تحتاجه من أعمدة/فهارس يوفره المستهلك؛ جداول الاختبار بالبادئةmaa_….:1191-1203) يُوثَّق بمثال Ordering/Pagination/Transaction.4.4 نقاط تصميم تُحسَم داخل WUs (ليست قرارات مالك)
undoOrFail/cleanupAfterFailureيُحفظ).PHP_CODING_STYLE :66-98).COMPOSER :687).CI :319).megyptm commentedon Oct 23, 2026
[5/6] CI والاختبارات والإصدار · هجرة المستهلكين والتعايش والتراجع
5.1 CI المقترح (مطابق لـ
CI_WORKFLOW_STANDARD5.0.0)[P]ما لا يُنقل: workflow القديم كما هو (F-6/N-15). ما يُعاد استخدامه كفكرة: أسماء الأبواب الناجحة في القديم (Workflow lint، Quality، Unit/Regression، Lowest، Integration، CI Gate).
Workflow lintactionlintبإصدار مثبت + checksum (يغطي كل.github/workflows/*):298-306Quality (PHP 8.4)composer validate --strict·dump-autoload --optimize --strict-psr· resolve ·composer check-platform-reqs(بلا--ignore-platform-req) · audit fail-closed (Composer ≥ 2.10) · syntax لكل PHP (src/tests/examples/config) · PHPStan max علىsrc testsبلا baseline/ignoreErrors · php-cs-fixer--dry-run --diff(PER-CS 3.1) · whitespace · validation للأمثلة:165-195, :248-296; Composer:1036-1096:26-32)Unit/Regression (PHP 8.4 · latest)unitوregressionبلا Docker:228-246, :264fail-fast: falseLowest dependencies (PHP 8.4)composer update --prefer-lowest --prefer-stableثم الفحوص والاختبارات:213-226maatify/exceptions ^1.0على 8.4[U→WU]Integration (PHP 8.4 · latest) × MySQL 8.4.xsleep) ← مخطط جديد ← suite ← فحص residue/repeatability (تشغيل ثانٍ) ←down -vعند النجاح والفشل؛ منفذ loopback ديناميكي؛ بلاcontainer_nameثابت؛ project identity لكل run؛ بيانات اعتماد مؤقتة؛composer test:integrationهو المدخل:307-363Consumer Verification Harness:75-94; CI:34-44Coexistence Harness(إضافة مقترحة)maatify/persistence:^1.4وmaatify/php-persistenceمعًا في root نظيف ويستعمل الاثنين على اتصال PDO واحد + اختبار تفاضلي (انظر 5.2)Archive/Distribution checkcomposer archive/git archiveالفعلي: الملفات الإلزامية موجودة، لا أسرار/dev artifacts:1141-1171; CI:79-97CI Gateif: always()، تفحصneeds.*.result:424-437pull_requestإلى الافتراضي +pushإلى الافتراضي (+workflow_dispatch) (CI:439-446). Model A (دائمًا يعمل) لأن الحزمة صغيرة (CI:127).permissions: contents: read؛ كل action خارجي مثبت بـ full SHA (يُعاد التحقق من كل SHA عند الكتابة، لا نسخ تلقائي من القديمة)؛ لاpull_request_target؛timeout-minutesوَconcurrency(:365-416).[I](فعل مالك).5.2 خطة الاختبارات
tests/Unit/**OwnedTransactionExecutorTest,OperationSavepointTest(يتبع قرار دمج الـhelper)tests/Regression/**Docs/*(4 ملفات تفحص نص التوثيق) تُنقل فقط إن بقي نصها صحيحًا (قرار WU)tests/Integration/**+Support/MySql/**+Fixtures/MySql/*.sqlmaa_{short}_PB:414) على MySQL 8.4 و PHP 8.4 + latest (ثغرة الدليل F-6)؛ تشمل partner-process للـdeadlock الحقيقيtests/Consumer/run.phpPdoPaginatorالقديم مقابل الجديد ⇒toArray()متطابق حرفيًا؛ والـOrdering: نتائج متطابقة إلا في deltas B-03/B-04/B-10 الموثقةPDO::inTransaction()علىpdo_mysql(ثغرة الدليل):1201:137)5.3 مسار الإصدار والحوكمة
1.0.0-rc.1يُحسب «RC» حقًا فقط بعد نشره وقابليته للتثبيت (LP:588)؛ قبل ذلك:Status = Development، لا Latest/Stable/Install badges (LP:195-205)، وSECURITY.md«لا خط Stable مدعوم» (LP:596-598).CHANGELOGيحوي قسمًا غير مؤرخ للهدف قبل الـtag (LP:651-688).:178-186,:547-569,:1643-1653؛ DEC-046). لا شيء منها يحدث في هذه الدراسة.[U]: Hostان فعليان يستهلكانphp-persistenceRC — مرشحان محتملانadmin-control-panel(عام) وHost خاص؛ يحدده المالك (OD-18).5.4 هجرة المستهلكين
5.4.1 الأدلة المرصودة
[V](خمس مستودعات عامة، HEAD عند الدراسة؛ عد تكرارات FQCN داخل*.php— ليس تحليل استخدام شاملًا)maatify/persistencephp-slug(787f3f6)^1.1^8.4PageRequest(12)PageResult(5)SortWhitelistSortDirectionEnumPdoPaginatorPdoPaginationQueryDescriptorPaginationConfiglistAliases(...): PageResult… (PdoSlugManagementQueryRepository.php:59-107)v1.0.0-rc.1/rc.2php-i18n(d3579c7)^1.4^8.4PageRequest(13)PageResult(10)PdoTransactionRunner(8)TransactionRunnerInterface(7) +Paginator types(3 كلٌّ)InvalidOrderingOperationException(2)ScopedOrderingManager(1)DomainRepositoryInterface::search(): PageResult(:53-63) وغيرهاv1.0.0-rc.1php-eligibility(bdb5e57)^1.4^8.4PageRequest(12)PageResult(6)PdoSavepointTransactionRunner(6)SavepointTransactionRunnerInterface(3)PdoTransactionRunner(1) …RuleManagementQueryInterface::findByCriteria(): PageResult(:40-42)v1.0.0-rc.1/rc.2php-event-logging(8044125)^1.1.0^8.2PaginationExecutionException(12)SortWhitelist(10)SortDirectionEnum(10)PdoPaginationQueryDescriptor(10)PaginationConfig(10)InvalidPaginationQueryException(10)InvalidPaginationConfigurationException(7)PdoPaginator(6)PageRequest(6)PageResult)admin-control-panel(f15c00f)^1.4^8.4ScopedOrderingManager(3)ScopedOrderingConfig(3)PdoTransactionRunner(2)PageResult(1)PageRequest(1)PageResultعبرPackageListMapper.php:41(نتيجة من php-i18n)maatify/persistenceفيcomposer.json(بحث كود GitHub) — غير مفصَّل هنا لأن الـIssue عام[V]؛ باقي المستهلكين الخاصين غير محصورين[U].PageResultفي واجهاتهم العامة ⇒ هجرتهم تغيّر API العام الخاص بهم (PB:793-804: يسمح بـthin adapter يحفظ العقد، أو إصدار Major مُبرَّر LP:641-649). لحسن الحظ هم Pre-Stable (rc) ⇒ لا وعد Stable يُكسر[I]— نافذة زمنية مناسبة قبل أول Stable لهم (مع مراعاة أن كلًا منهم سيمر بشرط Hostين).PageResult→PageResultDTOوفي تغييرuseالميكانيكي؛ أما Transaction/Ordering فسلوكيًا متوافقة (B-05/B-10).php-event-loggingعلى^8.2⇒ لا يستطيع طلبphp-persistence ^8.4دون رفع حد PHP لديه (تغيير عام لديه)[I].admin-control-panel) يستهلكPageResultالصادر عن php-i18n ⇒ ترتيب الهجرة يجب أن يتبع اتجاه التبعية (مكتبة ← Host)، أو يستخدم Host adapter مؤقتًا.5.4.2 التعايش
replaceولاconflictولا class_alias. المستهلك الذي يهاجر جزئيًا يبقى على القديمة في أجزاء وعلى الجديدة في أخرى.maatify/persistence(F-1) ⇒ قبل أول هجرة مستهلك يلزم قرارOD-03+ تعديل معياري مستقل (أو قبول المالك صراحة لحالة انتقالية موثقة).5.4.3 مراحل التبني (كل مرحلة = قرار/تفويض مستقل في مستودع المستهلك)
php-slug: Pagination فقط) في branch/PR داخل مستودعهOD-03محسوم + RC منشور + تفويض مالك للمستودعphp-eligibilityأوphp-i18n)admin-control-panel: Ordering + Transactions)5.4.4 جدول هجرة الإجراءات (للمستهلك)
"maatify/persistence": "^1.x""maatify/php-persistence": "^1.0"(بعد النشر) — وقد يبقى القديم أثناء الانتقالuse Maatify\Persistence\Pdo\Ordering\ScopedOrderingConfig;use Maatify\PhpPersistence\Ordering\Config\ScopedOrderingConfig;…Pdo\Ordering\ScopedOrderingManager…PhpPersistence\Ordering\Repository\ScopedOrderingManager…Pdo\Pagination\{PageRequest,PdoPaginationQueryDescriptor}…PhpPersistence\Pagination\Criteria\{PageRequest,PdoPaginationQueryDescriptor}…Pdo\Pagination\PageResult…PhpPersistence\Pagination\DTO\PageResultDTO(type-hints وdocblocks@return PageResult<T>)…Pdo\Pagination\{PaginationConfig}/SortWhitelist/SortDirectionEnum/PdoPaginator…\Pagination\Config\PaginationConfig/…\ValueObject\SortWhitelist/…\Enum\SortDirectionEnum/…\Repository\PdoPaginator…Pdo\Transaction\{TransactionRunnerInterface,SavepointTransactionRunnerInterface,PdoTransactionRunner,PdoSavepointTransactionRunner}…PhpPersistence\Transaction\Service\<نفس الاسم>…Pdo\Transaction\PdoDeadlockRetry{,Savepoint}TransactionRunner(غير منشورة)PdoTransactionRunner/PdoSavepointTransactionRunnerمعmaxDeadlockRetriescatch (PersistenceException $e)catch (PhpPersistenceExceptionInterface $e)Maatify\Persistence\Exception\X(X ≠ OrderingTransactionException)…PhpPersistence\{Ordering|Pagination|Transaction}\Exception\XOrderingTransactionExceptionملاحظة آلية
[P]: يمكن توليد خريطة FQCN 1:1 من جدول 3.1 وتنفيذها بأداة مراجعة (Rector/sed) ثم التحقق بـPHPStan max؛ لا يُنفَّذ ذلك في هذه الدراسة.5.4.5 التراجع (Rollback) والسياسة
requireالقديم؛ لا بيانات ولا مخطط يتغيران لأن أيًّا من الحزمتين لا تملك جداول (schema/README.mdالقديم)[V]⇒ التراجع كودي فقط.:115-117)؛ العلاج بإصدار جديد.1.x(بما فيه مرشحv1.5.0المعلق في old #37) قرار منفصلOD-19. لا إشعار deprecate ولاabandonedولا إعادة تسمية للمستودع القديم ضمن هذا العمل.megyptm commentedon Oct 23, 2026
[6/6] Work Units وشروط القبول · Owner Decision Register · المخاطر · Verified/Unverified · حدود التوقف
6.1 سلسلة Work Units المقترحة (متتابعة، صغيرة، قابلة للمراجعة)
مبادئ التسلسل: كل WU = وحدة هندسية كاملة (Runtime + اختباراتها + توثيقها المتأثر، Phase Stack §4.1)؛ لا PR لتسجيل PASS فقط (
:223-233)؛ لا mega-PR؛ كل GitHub Merge بإذن مالك صريح ومنفصل (AI Collab:547-569)؛ بعد كل Merge: Post-Merge Main Verification (DEC-041). لا تبدأ أي WU بغير تفويض كتابي مستقل (الاستخدام الحالي = دراسة فقط). Standards Freeze يسري من دمج WU-2 (Phase Stack:371-378).OD-nكتعليق في #1ODالمحجوب لـWU-1..3 محسوم؛ تعارضات F-1…F-9 لها قرار؛ تحديد المنفِّذ لكل WU (DEC-018)main(المستودع فارغ ⇒ لا PR ممكن)OD-13)LICENSE(OD-14) ·.gitignore(vendor/, composer.lock, caches, IDE) ·README.mdتمهيدي (Status = Development، بلا شارات نشر/تثبيت، يحيل #1)mainموجود وهو الافتراضي · لا branches أخرى · بعده يضبط المالك حمايةmain(PR مطلوب، منع force/delete):602-608)؛ الخطأ يُصحَّح بـPR لاحق؛ المستودع بلا مستهلكين فإعادة إنشائه (فعل مالك) هو أقصى تراجعAGENTS.md·docs/php-engineering-standards/**(14 ملفًا +STANDARDS_MANIFEST.md) ·docs/decisions/DECISIONS_INDEX.md:550-584) · Overall Resolution Status = VALID مع تشخيص لكل Activation · مطابقة byte-for-byte لكل ملف مقابلgit show <AdoptionCommit>:<path>· سكربت الإغلاق المحلي closed (مع توثيق S-6) · لا floating main · لا نسخ Standards غير منطبقة أوdocs/decisions/المركزية · قبول المالك لتجميد المرشحات (OD-11) · Lead Fresh Full Acceptance + Merge مالك + Post-Merge Verificationdocs/architecture/…يجمّد العقود B-01…B-16 + تحديث Index:73-87) · لا ADR «تاريخية مختلقة» (:296-304): الدليل = تعليقات المالك في #1 · اللغة وفقOD-16:235-257)composer.json·.gitattributes·phpstan.neon·phpunit.xml(suites) ·.php-cs-fixer.php·scripts/*·tests/bootstrap.php· marker interface + اختبار smokecomposer validate --strict·dump-autoload --optimize --strict-psr· PHPStan max بلا baseline · php-cs-fixer dry-run (PER-CS 3.1) ·git diff --check· لاcomposer.lockولاversion· الأوامر المحلية القياسية تعمل (Composer:861-931).github/workflows/ci.yml· Compose واحد parameterized · أوامرcomposer test:integration/ harness · اختبار Integration تمهيدي (اتصال/مخطط/residue/تكرار):26-32) · actions مثبتة بالـSHA · بعد الدمج: run علىmainأخضر (DEC-041) ثم يضبط المالك «CI Gate» كـrequired checkinTransaction()على pdo_mysql (R-1) · DocBlocks دلالية (PHP Source Doc) · Lead Fresh FullPageResultDTO) + اختباراتهاtoArray()/jsonSerialize()مطابق لقيم golden من القديمة؛ نفس بوابات WU-6PHP_PERSISTENCE_PACKAGE_REFERENCE.md(Source Topology، قوائم API، الاستثناءات، دعم DB، التصنيفات، workflow) ·README.md(Development) ·docs/guides/USAGE_GUIDE.md·examples/·llms.txt·CHANGELOG.md·SECURITY.md·CONTRIBUTING.md·CODE_OF_CONDUCT.md·schema/README.mdllms.txt§10.4 · لا روابط/أسماء من القديمة (LP §22) · الإنجليزية افتراضيًا (Doc Lifecycle:46-54)vendor/سابق · Coexistence أخضر · داخل CI Gate1.0.0-rc.1[1.0.0-rc.1]غير مؤرخ · README/SECURITY لحالة «الهدف مُجهَّز وغير منشور»v1.0.0-rc.1على SHA المؤهَّل · Release · تسجيل الحزمة:115-117):590) · لا إعادة عد لنفس Harness أو بيئتين لـHost واحد1.0.0:1619-1625،:1639-1655؛ PAVphp-engineering-standardsOD-03)v1.4.0وmainو#37 و#66 كما هي6.2 Owner Decision Register
maatify/php-persistence/ repophp-persistence:237-244)؛ القديمة تحتفظ بهويتها (:263)Maatify\PhpPersistence\· N1Maatify\Persistence\· غيرهماphp-*التي حذفتPhpلكنه اشتقاق حرفي من الـslug. N1: يوافق الممارسة لكنه يصادم القديمة (F-2). غيرهما: لا أساس معياري{PackageName}(S-2)Repository/للمنفّذات وService/للـrunners · (ب) كلهاService/مع تفسير PB:902-905· (ج) ثلاث حزم:231-269ويحفظ فصل SQL؛ (ب) أبسط لكنه يخالف روح:902-905؛ (ج) كلفة ×3 بلا مكسبPageRequest→PageCriteria· (ج) (أ) + حذف بادئةPdoمنPdoPaginator/PdoPaginationQueryDescriptorPageResultDTO، marker بـInterface، حذفOrderingTransactionException، الاستثناءات حسب القدرة:850-865)mainغير المنشورة (B) · (ب)v1.4.0(A) فقط · (ج) A + انتقاء من BgetNextPositionForUpdateوإعادة المحاولة؛ هذه الأخيرة لم تُنشر قط وتحمل خطر الاستقرار (#37 RELEASE NO-GO، #68 root cause غير متحقق). (ب) أضيق لكنه يبقي clamp قديمًا وفشل بلا savepoint. (ج) تعقيد تقييمPdoTransactionRunner/PdoSavepointTransactionRunnerبـctor(PDO, int=0)· (ب) إبقاء الأسماء الطويلةPdoDeadlockRetry*+ حذف القديمة · (ج) نقل الجيلين^8.4(مفروض) + matrix: 8.4 وأحدث مستقر (+ أي minor وسيط):237)ext-pdo+ext-pdo_mysql· (ب) (أ) لكنext-pdoفقط · (ج) MySQL + MariaDB مع مصفوفة Compose واختبارات مخصصة · (د) إبقاء «MySQL/MariaDB-compatible» نصًّا1020, savepoint guard)، يؤخر الإصدار. (د) ممنوع: توفر السائق/تشابه SQL ≠ دعم (PB:41-45)5b69c03(يجمّد المرشحات) · P-B2ea426a(محافظ: Frozen Baselines لبعض المعايير، لكن بلا RAV/PAV وهوية Release Artifact ⇒ Upgrade قبل RC) · P-C تأجيل حتى تجميد upstream:105-111)؛ (ب) يتطلب جرد Kind/Path/SHA-256mainLICENSEوComposer وGitHub (Composer:389-403)؛ تغيير الترخيص قرار قانوني:317-343؛ (ب) استثناء مشروط بعدم إمكان Compose فعليًا:46-54) · العربية1.0.0-rc.1→ Harness على المنشور → Hostان مستقلان →1.0.0· (ب)0.x· (ج) Stable مباشر:572-594). (ب)(ج) يخالفان أو يلتفان على الشرطadmin-control-panel+ Host خاص)v1.xوقرارv1.5.0/#37/#66 مسارات منفصلة · (ب) إعلان deprecate/migration بعد Stable · (ج) تجميد[I]schema/README.mdبلا جداول مملوكة:917-955) ويتجنب اختراع واجهات6.3 سجل المخاطر
PDO::inTransaction()علىpdo_mysqlفي PHP 8.4/8.5 يعتمد عليه منطق الـdeadlock replay؛ القديمة لم تُجرِ Integration على 8.4[U]maatify/exceptions ^1.0الأدنى على PHP 8.4 غير مُثبت[U]2 vs 4غير متحقق)PageResult→PageResultDTOتمسّ API عامًا لثلاثة مستهلكين عامّين:793-804)؛ M1→M4:371-378) + إعادة تحقق عند WU-2[U]mariadb6.4 الحقائق: مُتحقق منها مقابل غير مُتحقق منها
[V]مُتحقق (قابل للإعادة): حالة المستودع الجديد (فارغ، 0 branches، Issue #1) · SHAs/Trees للقديمة وv1.4.0 · نجاح CI #39985574051 وقائمة jobs · 21→26 ملفًا وقائمة الفروق · التوقيعات ومواضعها · محتوى المعايير عند5b69c03وإصداراتها عبر 4 commits · غياب tags في المستودع المركزي · غياب أي عقد bootstrap لمستودع فارغ · إغلاق المراجع المحلية للمجموعة (باستثناء رابط Profile) · أسماء 8 حزمphp-*ونمط namespace · استخدام 5 مستودعات عامة لأنواع القديمة وتعرّض 3 منها لـPageResult· حالة Pre-Stable للثلاثة · Packagist (v1.4.0 الأحدث؛php-persistenceغير مسجل) · غياب Compose في شجرة القديمة وCI على 8.2/8.5 للتكامل.[I]استنتاج المنفذ: تجميد Profiles 4.0.0/3.0.0 · انطباق AI Collab/Phase Stack على المستودع · تفسير الـResponsibility (Repository/Service) · عدم ارتباط §7.1 بروابط Profile · تصنيف Operational Read Out of Scope · نافذة Pre-Stable للمستهلكين · أن ترتيب الهجرة يتبع اتجاه التبعية · أن CI Gate لا يظهر كخيار حماية قبل أول run.[U]غير مُتحقق منه — يجب إثباته أو حسمه: حالة تجميد PB/Testing/Doc-Lifecycle · معرّف ruleset المطابق لـPER-CS 3.1 · سلوكmaatify/exceptions ^1.0الأدنى على 8.4 · Integration على PHP 8.4 · أحدث PHP مستقر وقت التنفيذ · الHostان المستقلان · المستهلكون الخاصون (عددهم ومحتواهم) · وجودcatch (PersistenceException)في المستهلكين · سجلات DEC غير المقروءة كاملة · جدوى مطابقة Profile blobs مع manifest مستهلك لإثبات التجميد · عدد الاختبارات الفعلي بالتشغيل (لم أشغّل أي suite؛ هذه دراسة قراءة فقط).6.5 التزامات هذا التسليم وحدوده
[P]تصميم مقترح لا يُنفَّذ قبل: حكم Lead المستقل ← اعتماد المالك لـOD-n← تفويض تنفيذ منفصل لكل WU.decision-ready؛ ذلك لـLead بعد مراجعته المستقلة.⏸ توقفت هنا بانتظار Independent Architecture Review الكاملة.
megyptm commentedon Oct 23, 2026
Technical Lead — Independent Architecture Review #1 (all six report comments): NEEDS REMEDIATION / OWNER DECISION NO-GO
Independent scope and evidence
Read the complete six-part Issue #1 study (1/6, 2/6, 3/6, 4/6, 5/6, 6/6). Independently checked old published tag
fc1459b49fe5af5ead17814eeb3ada7a3fa81791and Treeb477b06d23fc2101581513ca97c0948259079b67; old sourcemain@1f6a7aafe601090b7e55f60d83794364afdefe67, Treec1e25e7653a3173c3339a269b1ad23b26f335b9d; oldcomposer.json, representative public API/exception/runner source, and the current canonical standards text. New repo remains empty, 0 branches, Issue #1 OPEN, no implementation PR/commit. No tests were executed independently as this is a source/architecture review, not runtime acceptance.At review time central
mainadvanced from study's5b69c03419ad09369ad207a9a7976cc9cc0617d3to1d75e56e8a40b33a707110f288842f9b94d036bb; independent commit comparison: one file only,standards/modules/MODULE_SLIM_BUILDING_STANDARD.md, outside this standalone library's proposed applicable set. Therefore study's5b69c03419ad09369ad207a9a7976cc9cc0617d3remains a valid immutable study snapshot, not a silently approved adoption pin. Verify final snapshot/frozen baselines at WU-2.Accepted as solid study input, not yet authorized design
mainbehavior as a published contract.Maatify\\PhpPersistence\\gives true Composer/PSR-4 coexistence if ratified;maatify/php-persistenceidentity andphp:^8.4align with new-package standards; noreplace/alias assumed.PageResultDTOrather than copying legacyPageResult, genuine MySQL 8.4 verification plan, conservative MariaDB support claims, and explicit consumer-migration risks are reasonable architectural proposals.AR-01 — BLOCKER: mandatory Host-validation path contradicts proposed standards-update timing
Sources: study 6/6 OD-03 recommends changing central standards after first Stable while blocking consumer migration until then. The same study's WU-13 and 5/6 §§5.3–5.4 require published RC adoption/pilot M1→M3 and two independent real Hosts before Stable. The canonical Package Building §2 / §11 and §11 lines 699–818 explicitly assign reusable ordering/pagination to
maatify/persistenceand prescribe old FQCN/dependency in consumer packages. A consumer/Host cannot be called standards-compliant with the new package merely by recording an Issue-level Owner preference or an unsupported exception.Required: correct the dependency graph and OD-03: the central ownership/integration policy must be reconciled under its own authorized independent PR before any standards-governed consumer/Host RC pilot whose adoption conflicts with the published rule. Account explicitly for the controlled RC-stage validation needed before Stable, rather than deferring the fix until after Stable. An upstream change must correctly distinguish legacy published consumers, successor development/RC verification, and stable successor distribution; do not make unreleased APIs consumable by fiction. Treat conflict in implementing duplicate shared capability as an unresolved architectural ownership boundary too, not just a future consumer-doc polish. No central edits in this study; propose a distinct Owner-controlled Track S gating WU-13 (possibly earlier), with clear standard version/adoption implications. Do not reuse old #37's release-then-standard-facts rule automatically for a different package identity and consumer migration.
AR-02 — BLOCKER: initial-commit 'exception' is asserted without proving normative violation; durable decision is scheduled too late
Sources: study 2/6 S-3 and 6/6 WU-1, WU-3, OD-13. But canonical Phase Stack §1.1 and ACTIVE DEC-017 make the Branch→PR obligation about published non-default governed work branches. DEC-017 explicitly states it does not require a PR for the default branch itself. The inability to open a PR before the very first commit does not by itself prove an exception to that narrow rule. However AI Collaboration §6.3–6.4 still requires operation-specific authority and a reviewed integration result. Decision Governance §3 requires any approved material decision to be stored in durable repository Decision Record + index before or atomically with implementation, not held only in a GitHub issue until a later WU-3.
Required: replace the unproven 'mandatory waiver from DEC-017' with an explicit, bounded first-default-branch-bootstrap procedure that identifies exactly which Git operations are Owner-authorized, proves the reviewed initial Tree/contents and no runtime changes, and says precisely whether a real deviation from any other governing rule exists (cite it if so). If first-bootstrap is indeed a material cross-WU policy/architecture decision, include its ADR/Decision Index in that first commit (or find an equally compliant before/atomic boundary); do not postpone a material record to WU-3. Update WU-1 contents and WU-3 accordingly. Do not add an artificial PR where there is no base.
AR-03 — VERIFICATION HOLD: active decision-record preflight incomplete for the authority being recommended
The executor's own 2/6 Reading Ledger explicitly leaves relevant ACTIVE decision records only partially read or unread, including DEC-023 (strict RC/Stable acceptance), DEC-030 (exact target release artifact and live publication truth), DEC-031/032 (operational/adoption pin rules) and authorization/post-merge decisions. The Issue #1 mandate expressly required checking applicable ACTIVE records, not only Index rows. Lead has independently checked canonical §3 for material decisions and reviewed complete DEC-023/030 plus other representative records; the study's own recommended Release/Pin/Bootstrap plan still needs its own explicit completed applicable decision evidence.
Required: finish a targeted preflight of the records actually relevant to the design (
DEC-009,013,017,018,023,030,031,032,033,041,046as applicable, plus related active records justified by concerns). Update decision applicability/evidence matrix; clearly mark irrelevant ones N/A by scope. Inspect central Versioning Governance as an external authoritative verification source if needed for claims about Frozen/Mutable status: 'not in the local Pinned Set' means not copied, not that its content can never inform a claim about central version baselines. For unresolved frozen-status evidence maintain the mandated OWNER DECISION REQUIRED — VERSION BASELINE STATUS, and never createSTANDARDS_MANIFEST.mdclaiming VALID prematurely.AR-04 — DESIGN COMPLETENESS: tighten exception-marker and decision ownership boundaries
PhpPersistenceExceptionInterfacedirectly/indirectly. The proposed T-01/T-02…T-08 mapping establishes a marker/name and shared hierarchy but does not clearly map/verify marker conformance for every new exception. Add it explicitly to the contract matrix and regression acceptance; external propagatedPDOExceptionmust not implement it.OD-04Repository-vs-Service placement is treated as a real design interpretation against PB §5 (SQL only at persistence/query boundary); makeOperationSavepointhelper ownership and tests explicit before final API freeze. Do not silently preserve a public FQCN under a superficial 'KEEP' label.Disposition / next exact action
Issue #1 stays OPEN; study = NEEDS REMEDIATION, NOT OWNER-DECISION-READY. Preserve original six comments and their history; publish one ordered amendment/addendum linking each AR-01…04, replacing only affected OD/WU/decision-readiness assertions, with a fixed dependency timeline and focused decision evidence. The rest of the 3-way inventory can remain intact unless your re-verification finds a material delta. Supply a revised concise Owner Decision Register and state which decisions block WU-1 versus later WUs.
Strict READ-ONLY boundary continues: No new repo branch/commit/PR, no code port, no mutation of old repo or central standards, no automatic tag/release/Packagist. Lead will independently review the corrected addendum before presenting any specific material decisions to Owner. This review is a report, not authorization for implementation or waiver.
megyptm commentedon Oct 23, 2026
🛠️ Addendum 1/2 — معالجة AR-01 … AR-04 (READ-ONLY) · Re-Review Package
ACTIVE+ دليل تجميد قاطع بمطابقة blobs +UNRESOLVEDالصحيححالة المعايير المركزية عند الإعداد:
mainتقدمت إلى1d75e56e8a40b33a707110f288842f9b94d036bb؛ تحققتُ[V](git diff --stat 5b69c03 origin/main) أن الفرق ملف واحدstandards/modules/MODULE_SLIM_BUILDING_STANDARD.mdخارج المجموعة المنطبقة ⇒5b69c03يبقى لقطة دراسة غير معتمدة كـpin، كما حكم Lead.1. AR-01 — تصحيح التعارض بين توقيت تعديل المعيار وشرط Host Validation
1.1 الاعتراف وسحب التوصية
التوصية السابقة (OD-03 أ: تعديل معياري بعد أول Stable مع حجب هجرة المستهلكين) مسحوبة. سبب التناقض
[V]:standards/packages/LIBRARY_PRESENTATION_STANDARD.md:572-594) يوجب قبل أول Stable: RC منشور ← Harness على ذلك RC ← Real Host Validation في ≥2 Host مستقلين على RC نفسه.PACKAGE_BUILDING_STANDARD.md:73-78) وَ§11 (:699-818) تُلزم المستهلك بـmaatify/persistenceوتمنع «نسخ محلية»، وتشترط «minimum stable dependency version» (:78) وتحظر استهلاك contracts غير منشورة كأنها API.⇒ لا يمكن أن يكون أي Host/Consumer ملتزمًا بمعاييره المثبتة إذا اعتمد RC الخلف قبل أن تُوفّق المعايير. ولا ترث هذه الخطة قاعدة old #37 «أصدر ثم حدّث المعايير» لأنها سُنّت لإصدار نفس الهوية (
maatify/persistence) لا لهوية وهجرة مختلفتين.1.2 النموذج المصحَّح (يُقترح تعديلًا مركزيًا مستقلًا Track S — لا يُنفَّذ هنا)
يجب أن يميّز تعديل PB §2/§11/§16 بين أربع حالات للمالك المشترك لقدرة ordering/pagination/transaction:
maatify/persistence ^1.xبلا تغييرmaatify/php-persistenceغير قابلة للاستهلاك؛ ممنوع نسخ APIs غير منشورة (PB:78يبقى):76) بملكية واحدة لا اثنتينحدود الملكية (يُعالج «الازدواج كحد ملكية غير محسوم»): النموذج المقترح = Successor: بعد S تصبح
php-persistenceالمالك الكنسي للأعمال الجديدة، وmaatify/persistenceفي صيانة قديمة بقرار مالك منفصل. بدائل رُفضت: ملكيتان متوازيتان (يخالف «مصدر حقيقة واحد» PB:814-818و:76)، أو ترك التعارض بلا معالجة (لا آلية استثناء متاحة: Decision Governance:269-275). القرار للمالك (M-1).آثار الإصدار/التبنّي
[I](تحسمها Version Finalization المركزية لا هذا التقرير): PB 4.0.0 Mutable Candidate (لا لقطة مستهلك مطابقة، §3.2) ⇒ التعديل غالبًا يُمتص في Candidate قائمة بلا bump متسلسل (Versioning Policy §3.4)؛ لكن أي مستهلك/Host يريد الاستفادة يحتاج Upgrade لـAdoption إلى commit يحتويه.1.3 قيود مضافة على مرحلة RC (تصحيح لخطة M1→M3 السابقة)
:78) وbـminimum-stability: stable(Composer:1109-1117) ⇒ لا هجرة مكتبة قبل1.0.0Stable؛ تسقط فكرة «Pilot على RC» لمكتبة ما لم يغطّه نص Track S صراحةً. هذه المكتبات لا تُحسب شرطًا لأول Stable.[U](لم أقرأ معايير Host المثبتة): لذلك يلزم قبل أي Real Host Validation: (1) Track S مدموج، (2) Upgrade Adoption للـHost إلى commit يحتويه، (3) تفويض مالك لمستودع الـHost.2. Dependency Timeline المثبَّت (يستبدل أي ترتيب سابق)
:371-378):78+ Composer stability3. AR-02 / AR-03 — انظر الأقسام التالية
3.1 (AR-02) إجراء الـFirst-Default-Branch Bootstrap — بديلًا عن «الاستثناء الإلزامي»
إقرار: سحبتُ ادعاء أن Commit الأول يحتاج waiver من DEC-017. الفحص
[V]::33-61): PR لكل non-default governed work branch منشورةmain:513-644):529-583:602-608:73-87): السجل الدائم قبل/مع التنفيذmainالبعيدة = الشجرة المراجَعة[I]— انظر UNRESOLVED-2 §3.3⇒ لا يوجد انتهاك مثبت لقاعدة معيارية؛ الموجود فجوة توثيق في المعايير (S-3)، لذلك يُعامل الإجراء كـمجموعة عمليات مفوَّضة صراحة ومحددة وليس «استثناءً/waiver».
الإجراء المقترح (يُنفَّذ فقط بتفويض منفصل):
git init/استنساخ المستودع الفارغ في مجلد عمل محلي وإنشاء الفرع المحليmaingit diff --cached --check/--name-status/--stat+ تسجيلgit write-tree(Tree المرشح)git commitواحد (بلا amend)git push origin main(إنشاءmainالبعيدة، بلا force)git ls-remote⇒main= الـcommit؛ Tree البعيد = Tree المراجَع؛ ref وحيدmain(PR مطلوب، منع force/delete)محتوى الـcommit الأول (6 ملفات، بلا كود ولا workflows ولا ادعاءات معيارية):
LICENSE·.gitignore·README.md(Status = Development، يحيل #1، بلا شارات نشر/تثبيت — LP:195-205) ·docs/decisions/DECISIONS_INDEX.md·docs/decisions/DEC-001-…md(Bootstrap: العمليات المفوَّضة + المحتوى + الدليل = تعليق تفويض المالك) ·docs/decisions/DEC-002-…md(الترخيص).AGENTS.mdليست في الـcommit الأول (تُشير إلىSTANDARDS_MANIFEST.mdغير الموجود قبل WU-2).docs/decisionsالمركزي؛ ID محليDEC-NNN(Adoption §9.1:451يفصل المركزي عن المحلي).ملاحظة تراجع محدثة (تصحيح WU-1 السابق): «إعادة إنشاء المستودع» غير مقبولة كتراجع عادي لأنها تحذف Issue #1 وتاريخ هذه المراجعة؛ التصحيح = commit تصحيحي عبر PR بعد حماية
main. وقبل حمايةmainيبقى أي تصحيح بلا force/amend (AI Collab :602-608).3.2 إعادة توقيت القرارات المادية (Decision Governance §3)
LICENSE)composer.json/src/)3.3 (AR-03) Preflight القرارات
ACTIVE+ دليل التجميدأ) أدلة التجميد (Frozen vs Mutable) — طريقة قاطعة قابلة للإعادة. Versioning Policy §3.3 (
STANDARD_VERSIONING_POLICY_AR.md:158-170) : الـFreeze يحدث فقط بـCompleted VALID Adoption/Upgradeيثبت الـartifact snapshot. قارنتُ blob كل ملف عند1d75e56(يساوي5b69c03للمجموعة) بنفسه عند commits Adoption الموثقة لمستهلكين عامّين (ebcf55bphp-product وphp-rate-limiter·73abc86php-return-target ·5f872d3php-i18n ·7dd9d1dphp-slug/eligibility ·2ea426a) عبرgit rev-parse <commit>:<path>:VALID2c21ee8ebcf55b 73abc86 5f872d3 7dd9d1d 2ea426a[V]92864c0[V]a4cfae0[V]ef7e133[V]9c7bf19ebcf55b 2ea426a[V](manifest php-product: OverallVALID)071b764df57ba11cbcbfa24ca8e4cc936b96d743293c508e1589b446c1bbc75known frozen-version/content mismatch⇒INVALIDلو ثبت، Adoption:654-656).OWNER DECISION REQUIRED — VERSION BASELINE STATUS(Adoption:234-240، Versioning §3.3) إلى أن يُثبت Lead بمسح المستهلكين الخاصين أو يقرّ المالك. لا يُنشأSTANDARDS_MANIFEST.mdبحالةVALIDقبل زوالها (يعالجه WU-2 كشرط دخول)..agents/helpers/maatify-governance-context.phpعلى المرشح (مع بقائه Operational Asset غير مُتبنّى).ب) مصفوفة انطباق القرارات
ACTIVE(preflight مستهدف):[I]ext-pdoأساسي/llms.txtإلزاميUNRESOLVED-3(سجلات غير مقروءة كاملة؛ لا أثر متوقع)DEC-045 handoff (لم تُنشأ Issues لأن الحدود READ-ONLY ولا تفويض إنشاء): مسودات مقترحة للـLead: (1)
php-engineering-standards: PB §2/§11/§16 ملكية Successor (L/D/R/S)؛ (2) تعريف{PackageName}لحزمphp-*؛ (3) فجوة توثيقية: لا عقد لأول commit في مستودع فارغ؛ (4) توضيح أن رابط Profile لمعيار مستبعد ليس خرقًا لإغلاق Adoption §7.1.الحالات
UNRESOLVEDالمتبقية: U-1 تجميد التسعة (مستهلكون خاصون) · U-2 انطباق DEC-046 الحرفي على إعدادات GitHub/Packagist · U-3 سجلات DEC غير المقروءة (لا أثر متوقع) · U-4 معايير الـHost المثبتة (لشرط WU-13b).megyptm commentedon Oct 23, 2026
🛠️ Addendum 2/2 — AR-04 · Owner Decision Register المحدَّث · WU المعدّلة · Errata
(يكمل Addendum 1/2: AR-01 + Timeline + AR-02 + AR-03.)
4. AR-04 — اكتمال التصميم
4.1 Exception Marker conformance (PB §7
:443-455)القاعدة: كل exception يعرّفها الحزمة تُنفّذ
PhpPersistenceExceptionInterfaceمباشرة أو غير مباشرة، وPDOException/الـThrowables الخارجية لا تُنفّذه (:455).الدليل في القديمة
[V]:grep "implements PersistenceException" src/Exception/*.php= 8 من 8 كلاسًا مباشرةً (الملف التاسع هو الـinterface نفسه).maatify/exceptions)P\Ordering\Exception\InvalidOrderingConfigurationExceptionSystemMaatifyExceptionInvalidOrderingConfigurationExceptionTest.php:17P\Ordering\Exception\InvalidOrderingOperationExceptionValidationMaatifyException[V](فجوة)P\Pagination\Exception\InvalidPaginationConfigurationExceptionSystemMaatifyExceptionPaginationExceptionContractTest.php:25P\Pagination\Exception\InvalidPaginationQueryExceptionSystemMaatifyExceptionP\Pagination\Exception\PaginationExecutionExceptionSystemMaatifyExceptionP\Transaction\Exception\TransactionExecutionExceptionSystemMaatifyExceptionTransactionPublicApiRegressionTest.php:67P\Transaction\Exception\InvalidTransactionConfigurationExceptionSystemMaatifyExceptionDeadlockRetryRunnerPublicApiRegressionTest.php:136OrderingTransactionExceptionOrderingPublicApiRegressionTest.php:141(يسقط مع الحذف)PDOException/\ThrowableخارجيassertSameللاستثناء الأصلي المعاد رميه (PdoDeadlockRetryRunnerIntegrationTest.php:111)شروط قبول (تُضاف إلى بوابات WU-4/6/7/8):
src/**/Exception/*Exception.php): كل كلاس يُنفّذ الـmarker ويمتد من هرميةmaatify/exceptions؛ الـmarkerinterfaceويمتد\Throwable— يمنع تجاوز استثناء مستقبلي (الاختبارات القديمة جزئية لا شاملة).assertNotInstanceOf(marker).*Exceptionخارج مجلدException/للقدرة، ولا marker ثانٍ (PB:466-468).:169).4.2 مراجعة التصنيف: إلغاء وسم «KEEP»
وسم KEEP كان مضللًا لأن كل FQCN يتغير. الاستبدال:
RELOCATE= نفس الاسم القصير/التوقيع، FQCN جديد (ليس توافق استيراد).PhpPersistenceExceptionInterface، T-14 →PageResultDTO4.3 OD-04 — تفسير Repository مقابل Service (تعديل توصيتي)
معطيات المعيار
[V]: PB:879-880«SQL lives in Repositories or package-local SQL support builders»؛:902-905Services never contain raw SQL؛:257Repository = «persistence/query boundaries and their implementations»؛:271-289الواجهة تُوضع مع الـResponsibility التي تصفها.SAVEPOINT x,RELEASE,ROLLBACK TO,DO 0) عبرPDO::exec(OwnedTransactionExecutor.php:173،PdoSavepointTransactionRunner.php:73-78). وضعها فيService/(توصيتي السابقة) يخاطر بمخالفة حرفية لـ:902-905؛ وضعها فيRepository/لا يخالف نصًا ويقتصر الخطر على ملاءمة الاسم.Repository/؛ ولا يُنشأService/في هذه الحزمة. التأثير على المصفوفة:P\Transaction\Repository\{TransactionRunnerInterface, SavepointTransactionRunnerInterface, PdoTransactionRunner, PdoSavepointTransactionRunner, OwnedTransactionExecutor}؛ وOrdering\Repository\ScopedOrderingManager؛ وPagination\Repository\PdoPaginator. (يستبدلTransaction\Service\…في [3/6] و[4/6].)Service/+ تفسير موثق (PB:902-905)؛ يُعاد فتحه فقط إن قرر Lead أن أوامر التحكم ليست «raw SQL» — مسار ADR، ويجمَّد قبل WU-6.4.4 ملكية
OperationSavepointوالاختبارات قبل تجميد الـAPI[V]: ثلاث نسخ متقاربة منexecuteControlStatement/tryControlStatementوسلوك التنظيف:OperationSavepoint.php:98-114،PdoSavepointTransactionRunner.php:73-115،PdoDeadlockRetrySavepointTransactionRunner.php:94-136. يختلفOperationSavepointعنها في ثلاثة أمور فقط (docblock:11-27): (1)undoOrFail()يمرّر فشلROLLBACK TO(2) لا مسار «معاملة مملوكة» (3)begin()يفشل إن لم تبقَ المعاملة نشطة بعدSAVEPOINT.Transaction\Repository\SavepointScope،@internal)، وOrdering يستهلكه (الاتجاهOrdering → Transactionمُعلَن أصلًا). كلاس@internalفي PHP يبقى قابلًا للتحميل ⇒ يعلن Package Reference أنه خارج العقد العام/SemVer، ولا يكتفى بالوسم.OperationSavepointTest.php:27,66,112,121,131,140,149,163+ اختبارات runners الثلاثة (PdoSavepointTransactionRunnerTest.php:92،…ParityTest.php:99،…RetryTest.php:124,147,148) +ScopedOrderingManagerLazySavepointTest.php(14 اختبارًا). شروط القبول: تُنقل دون تعديل أي تأكيد، تمر على الكود الحالي (قبل الدمج) ثم تمر على الـhelper المدموج بلا تعديل؛ أي اختلاف = تغيير سلوك يحتاج ADR.4.5 الـOD تُصنَّف في ثلاث طبقات (يستبدل سجل الـ20 في 6/6 §6.2)
الطبقة 1 — Owner Material Decisions (9 فقط)
maatify/persistenceMaatify\PhpPersistence\✅ · N1Maatify\Persistence\ext-pdo_mysqlext-pdo+ext-pdo_mysql✅ · (ب)ext-pdoفقط · (ج) MySQL+MariaDB بمصفوفةVERSION BASELINE STATUSللتسعة5b69c03/أحدث ·P-B2ea426a· P-C تأجيلadmin-control-panel+ Host خاصالطبقة 2 — Standard-Mandated Defaults (يُقرّ المالك دفعة واحدة؛ لا قرار شخصي لكل بند)
maatify/php-persistence/ repophp-persistence:237-244php ^8.4؛ CI على الأدنى والأحدث المستقر (+الوسيط):27-29؛ Composer:559-561؛ CI:232-237:105-111؛ DEC-031CI Gateوحيد:127, :317-343, :424-437:46-54:572-594؛ DEC-023replace/conflict/provide/class_aliasبلا موافقة معمارية؛ لاversionولاcomposer.lock:749-763, :1122-1137…DTO,…Interface,…Enum,…Exception، marker{PackageName}ExceptionInterface، استثناءات كل قدرة تحت{Capability}/Exception/:152-171, :314-322Pdo/ولاInternal/:175-229, :291-312:917-955, :993-1002:861-931, :1036-1096؛ PB:1044-1067:73-87؛ Testing:75-94؛ CI:79-117الطبقة 3 — تفاصيل تصميم/تنفيذ (Lead/Executor، تُسجَّل في ADR أو Package Reference عند اللزوم)
Repository/(§4.3)PageRequest→PageCriteria، حذف بادئةPdo) — الافتراضي: لاPHP_PERSISTENCE_PACKAGE_REFERENCE.mdRegression/Docs/*من عدمهmaatify_persistence_sp_<32hex>(موثقة ومختبرة)5. WU المعدّلة (الصفوف المتأثرة فقط؛ بقية جدول 6/6 §6.1 باقٍ)
VERSION BASELINE STATUSأو قبول مالك صريح؛ validator evidence؛ لا ManifestVALIDقبل ذلك1.0.0فقط (§1.3)6. Errata — ما يُستبدل في التقرير الأصلي
Transaction\Service\)Transaction\Repository\(§4.3)[I]»[V]بمطابقة blob؛ التسعة الأخرى Mutable /OWNER DECISION REQUIRED — VERSION BASELINE STATUS(§3.3)7. حدود التسليم
لم أنفّذ أي commit/branch/PR/tag ولا تعديل لأي مستودع أو معيار مركزي، ولم أنشئ Issues (الدفعة المقترحة في §3.3 DEC-045). القراءات الجديدة: سجلات DEC المستهدفة، Versioning Policy، مقارنة blobs مع لقطات المستهلكين العامّين، وفحص commit المعايير المتقدم. أي بند غير مثبت مصنَّف
UNRESOLVED(U-1…U-4).⏸ توقفت بانتظار Fresh Independent Architecture Re-Review.
megyptm commentedon Oct 23, 2026
Technical Lead — Fresh Independent Architecture Re-Review #2 (Addendum 1/2 + 2/2)
Verdict: PARTIAL ACCEPTANCE of design remediation;
Issue #1is NOT YET FULLY DECISION-READY. Standards Adoption WU-2 = NO-GO on candidate5b69c03/ current1d75e56until a newly independently PROVEN structural version conflict is repaired. No permission to bootstrap, push, merge, port source or release is granted by this review.Read both complete addenda (1/2, 2/2) against all six original study sections, prior AR-01…AR-04, old source
main@1f6a7aafe601090b7e55f60d83794364afdefe67, central canonical adoption/versioning/Package Building/Composer/CI/Decision Governance/DEC-017/DEC-023/DEC-030, and actual completedVALIDpublic-consumer manifest and frozen file blobs. Central current head1d75e56e8a40b33a707110f288842f9b94d036bbchanges only Slim Standard from the study5b69c03snapshot, so the comparison and findings below apply identically to both candidate pins. New repo still EMPTY (0 commits/branches/PRs).Accepted corrections
docs/decisions/DECISIONS_INDEX.mdand material Bootstrap/License ADRs before-or-atomic with their reliance. No first Commit authorized yet. Corrected rollback language preserves Issue architecture: establish PHP 8.4 persistence package contract, standards adoption and migration design #1's history. Clarify the planning contradiction: G0/WU-0 currently says Owner must ratify M-1…M-9 before any WU, whereas §2 says first WU needs only M-6 (MIT) + M-7 (bounded bootstrap). Lead chooses progressive decision gates: M-6/M-7 required for WU-1; other material decisions must be approved/recorded before the first Work Unit actually relying on each; do not require blanket nine-item approval for a six-file bootstrap.PhpPersistenceExceptionInterfacewith comprehensive runtime/reflection negative regression planned; externalPDOExceptionremains unmarked; every new FQCN is RELOCATE/RENAME/REDESIGN, not deceptively KEEP. ProposedTransaction/Repositoryplacement is a provisional Lead architecture interpretation, grounded in raw SQL/savepoint commands vs PB §13 "Services never contain raw SQL", to be documented as ADR and rechecked against actual implementation. The single@internalsavepoint-helper owner and characterization tests are proposed; consolidation is not yet proven behavior-preserving until WU-6 real test evidence. 9 material decisions vs defaults/implementation details is an improved review surface.AR-03b — NEW PROVEN BLOCKER: THREE
KNOWN FROZEN-VERSION/CONTENT MISMATCHartifactsThe addendum's §3.3 classifies nine current standards as merely "Mutable Candidate /
OWNER DECISION REQUIRED — VERSION BASELINE STATUS" based on a limited public-consumer scan. That classification is factually wrong for at least three. I independently checkedMaatify/php-productmanifest onmain:Overall Resolution Status: VALID, exact upstream Adoption Commitebcf55b0591db61d18a1407bc3effef0197b388f. Its pinned local files exactly match central blobs at that commit. At study's candidate5b69c03419ad09369ad207a9a7976cc9cc0617d3these three have the SAME declared version but different complete file contents:5.0.064ce9bc38a87034c5a57df0265f551d083658b321cbcbfafe29c031c17cd7453b54fde9e3a98a1be5.0.074e499519da522f0f1719c6370c58c2a4eef15a324ca8e42c105777c78c0b53b1a297eff7ac2ca7f3.1.05e75fa711a507f4195d7ca4b8cc43874d6255d5c3c508e1754cebfe8b2a6903b71d718823644313eChanges were inspected: they are Issue #168 / DEC-042 editorial-only consumer-identity neutralizations in the historical change-log lines, not obvious new normative technical rules. But Versioning Policy §3.3 freezes the exact artifact content, and Adoption §16.3 says known frozen-version/content mismatch ⇒
INVALID, structural, non-waivable. Editorial/non-contract nature does NOT create a written exemption from exact blob identity. The approved closed central #168 appears to have relied on a no-freeze premise contradicted by this integrated consumer's ownVALIDevidence; review authority must be reconciled centrally, not overridden by a new consumer.Result for the proposed pin:
INVALIDat least for these three artifacts if adopting their present identical version labels and divergent content; not merelyOWNER DECISION REQUIRED. Unknown private freezes for the other six still require baseline-status evidence (cannot be assumed mutable). No Owner consent can waive this structural failure. Opened actionable central #179 to verify the earliest Freeze and repair the central version lineage before any newVALIDAdoption. No standard content was changed.Required narrow correction / next gates
KNOWN FROZEN-VERSION/CONTENT MISMATCH → INVALID, other six unknown unless proved, linking #179 and exact proof. Remove the option "Owner accepts nine unresolved⇒ manifest VALID" from WU-2 and M-5. Owner may resolve an unknown baseline by supplying authoritative evidence; cannot approve a known mismatch into validity.Final classification: NEEDS ONE BOUNDED FACTUAL ADDENDUM (AR-03b), NOT A NEW FULL STUDY; no Owner blanket OD approval yet. All repository implementation authority remains suspended. The evidence here is GitHub source/manifest/blob examination, not locally executed PHP/MySQL verification.
megyptm commentedon Oct 23, 2026
✏️ Corrective Addendum (AR-03b) — تصحيح واقعي محدود · READ-ONLY
1. اعتراف بالخطأ
في §3.3 صنّفتُ تسعة معايير «Mutable Candidate» لأن مسحي بحث عن تطابق blob فقط ولم يفحص تطابق رقم الإصدار مع اختلاف المحتوى. غياب التطابق لا يعني غياب التجميد؛ هذا استنتاج خاطئ مني. التصحيح أدناه.
2. إعادة التصنيف (تحققتُ مستقلًا
[V]بـgit rev-parse <commit>:<path>على نسخة محلية للمستودع المركزي)لقطة
php-productالـVALID(Adoption Commitebcf55b0591db61d18a1407bc3effef0197b388f) مقابل5b69c03(وَ1d75e56له نفس blobs):ebcf55b5b69c03=1d75e565.0.064ce9bc38a87034c5a57df0265f551d083658b321cbcbfafe29c031c17cd7453b54fde9e3a98a1beINVALID5.0.074e499519da522f0f1719c6370c58c2a4eef15a324ca8e42c105777c78c0b53b1a297eff7ac2ca7fINVALID3.1.05e75fa711a507f4195d7ca4b8cc43874d6255d5c3c508e1754cebfe8b2a6903b71d718823644313eINVALID[V](git diff ebcf55b 5b69c03لكل ملف: +2/−1 سطر): سطر سجل التغييرات التاريخي فقط (تحييد هوية مستهلك تحت #168/DEC-042). لا أدّعي أنه يغيّر عقدًا معياريًا — لكن هوية الـFreeze هي محتوى الـartifact الكامل (Versioning Policy §3.3STANDARD_VERSIONING_POLICY_AR.md:158-170)، وAdoption §16.3 (:633-676) يجعل المطابقة الخاطئةINVALIDبنيويًا غير قابل للـwaive. لا نص مرجعي يستثني سجل التغييرات (لم أجده؛ وهذا موضع التحقيق المركزي).ebcf55b(5.0.0 / 5.0.0 / 3.0.2 / 2.0.0 / 12.0.0 / 4.0.0) ⇒ لا تعارض ثابت مع تلك اللقطة، لكن حالتهاUNVERIFIED BASELINE STATUS(مستهلكون خاصون غير مفحوصين)، لا تُفترض Mutable. وَالخمسة المطابقة سابقًا (Decision Governance، PHP Source Doc، PHP Coding Style، وكلا الـProfiles) تبقىFROZEN MATCHكما في الأصل.3. أثر التصحيح على الخطة
5b69c03و1d75e56⇒INVALIDلثلاثة artifacts؛ لا يوجد خيار «الأخذ مع تجميد/قبول مالك». يُحذف من M-5 وWU-2 أي مسار «يقبل المالك التسعة غير المحسومة ⇒ ManifestVALID». المالك قد يقدّم دليلًا موثوقًا يحسم حالة مجهولة، ولا يملك تحويل عدم تطابق معروف إلى صلاحية (Owner Approval ≠ علاج مخالفة بنيوية؛ Adoption:660-666).2ea426aيبقى فقط كمرجع تاريخي؛ تقييمه يتطلب فحص الـblobs نفسه قبل أي اقتراح، ولم يُفحص لهذه الغاية).4. G0 / WU-0 — تصحيح التعارض (قرارات تدريجية)
يستبدل نص «يعتمد M-1…M-9 قبل أي WU»:
5. القطار الموصى به (محدَّث)
WU-1 يمكن النظر فيه منفردًا بعد موافقة المالك الصريحة على MIT والملفات الستة والعمليات المسماة، لأنه لا ينشئ Manifest ولا كود PHP. لا WU آخر مُفوَّض.
6. ما لم يتغير
الجرد الثلاثي (26 نوعًا) والعقود والبدائل وTrack S ومصفوفة Marker وتصنيف 9/12/9 والـUNRESOLVED الأخرى (U-1 يصبح: حالة الستة المجهولة فقط، U-2…U-4 كما هي).
⏸ توقفت. READ-ONLY: لا commit/branch/PR ولا تعديل لمعيار أو مستودع قديم.
megyptm commentedon Oct 23, 2026
Technical Lead — Fresh Independent Architecture Re-Review #3: STUDY ACCEPTED WITH EXPLICIT IMPLEMENTATION GATES
Reviewed: Corrective Addendum AR-03b against Re-Review #2, Addendum 1/2, Addendum 2/2 and six original architecture study comments. Independently checked the public consumer
Maatify/php-productSTANDARDS_MANIFEST.md, pinned upstreamebcf55b0591db61d18a1407bc3effef0197b388f, and the exact three source blobs in current centralmain@1d75e56e8a40b33a707110f288842f9b94d036bb. New repository is still empty (0 branches, no PRs/commits); Issue #1 OPEN.Specific finding closure
php-productmanifest isVALIDat pinnedebcf55b, and its exact three pinned file blobs equal that upstream snapshot. Current central still declares those SAME versions with DIFFERENT bytes:5.0.064ce9bc38a87034c5a57df0265f551d083658b321cbcbfafe29c031c17cd7453b54fde9e3a98a1be5.0.074e499519da522f0f1719c6370c58c2a4eef15a324ca8e42c105777c78c0b53b1a297eff7ac2ca7f3.1.05e75fa711a507f4195d7ca4b8cc43874d6255d5c3c508e1754cebfe8b2a6903b71d718823644313eKNOWN FROZEN-VERSION/CONTENT MISMATCH → INVALIDfor this proposed pin, not Owner-waivable. The remaining six unmatched current versions areUNVERIFIED BASELINE STATUS, not automatically Mutable. The earlier five matching frozen artifacts remain consistent. Investigation/remediation owned by central #179. This correction is now reflected in M-5/WU-2; noVALIDadoption manifest can be created on these conflicted snapshots.Explicit project status, next action, and authority
ISSUE #1 ARCHITECTURE STUDY: ACCEPTED AS DECISION-READY WITH STAGED IMPLEMENTATION CONDITIONS. This closes the study/review findings, NOT Issue #1 itself, the structural standards mismatch, the central ownership change, the API design implementation, or any release gate.
LICENSE,.gitignore,README.md(development-only),docs/decisions/DECISIONS_INDEX.md,docs/decisions/DEC-001-…mdfor bootstrap procedure,docs/decisions/DEC-002-…mdfor MIT. Initialmainhas no commit; use explicitly approved sequence only: prepare six files, review staged diff/tree, named Owner permission for commit and non-force push of exact reviewed Tree, verify remote main commit/tree, then enable protection. NoAGENTS.md,STANDARDS_MANIFEST.md, PHP source or CI/Composer skeleton in first Tree. Owner approval on a plan does not eliminate the required pre-commit Tree review.2ea426ais NOT an approved fallback.Maatify/persistence/#37 RELEASE NO-GO remains separate; no old contract change, consumer migration, Tag/Release/Packagist action or backdoor standards update is implied.Result: Architecture Study ACCEPTED; proceed next with Owner presentation of only M-6/M-7 for WU-1. Do not create a branch, commit, PR, release or modify upstream under this comment.
megyptm commentedon Oct 23, 2026
Owner Decision M-6 — RATIFIED: Proprietary (NOT MIT) — licensing correction to WU-1
Authority: Owner's explicit instruction in the project leadership discussion on 2026-10-23: "الرخصه هتكون propration مش mit", interpreted as the recognized Proprietary software licensing model. This is an Owner licensing decision and supersedes the architect/executor's recommended MIT in original Issue #1 study, Addendum, decision register, and Lead's WU-1 decision request. MIT was never Owner-ratified for this new repository.
Binding update (prospective, no repository file edits)
LICENSElegal text is NOT YET DRAFTED/APPROVED. Do not copy old MIT text into the newLICENSE, nor manufacture a commercial usage grant, customer permission, sublicense, non-transferability clause, or organizational ownership clause not approved by the actual rights holder.composer.jsonmust use"license": "proprietary", Composer's documented valid closed-source identifier (https://getcomposer.org/doc/04-schema.md#license), and stay consistent with theLICENSEfile, repository metadata, README, later package presentation/registry disclosure. Central Composer Package Standard §10.4 does not mandate MIT, but requires consistency and Owner-controlled legal/repository licensing decisions. The accepted phraseproprietaryis a Composer-specific special license identifier, not a claim that it is an ordinary SPDX open-source license.LICENSE,.gitignore,README.md(Development / Proprietary, no published/install badges),docs/decisions/DECISIONS_INDEX.md,docs/decisions/DEC-001-…md(first-default-branch bootstrap),docs/decisions/DEC-002-…md(M-6 Proprietary licensing decision). Record a direct link to this Owner decision and do not describe MIT as active. Material decision M-6 must be durable, indexed and in the same initial Tree as theLICENSEit governs.Maatify/persistence@1f6a7aafe601090b7e55f60d83794364afdefe67includes an actual MITLICENSE(Copyright 2026 Maatify). Changing the license declaration in a distinct new repository does not retroactively remove rights granted by the old MIT release. Before importing/copying any old code, verify rights-holder control, inherited notices and any contributor/third-party obligations; preserve any required MIT copyright/license notices where applicable. Do not assume ownership or relicensing rights merely because the two repos share an organization. This is a legal provenance/compliance prerequisite for the future source-porting Work Units; it does not block a clean six-file bootstrap if the newLICENSEis legally reviewed.Authorization boundary
M-6 licensing choice is ratified. M-7 is NOT YET approved merely by choosing the license. First Git commit/branch/Staging/Push (and any change to GitHub visibility/settings) still require the independently specified authority and exact pre-commit Tree Review under WU-1; no file, branch, PR, commit or push is authorized in this comment. WU-2 remains blocked by central #179 and #180.
Next Lead action: update WU-1 instructions to draft a proprietary
LICENSEfor rights-holder/legal review without committing, rather than defaulting to MIT, and seek separate M-7 authorization for the six-file bootstrap and its pre-commit Tree gate.megyptm commentedon Oct 23, 2026
Technical Lead correction — WU-1 review responsibility and GitHub-first handoff
Clarification of the final wording in the M-6 Proprietary ratification and architecture acceptance:
Owner is NOT required to receive, inspect or approve local files, a local staged diff, or a local Git Tree as a separate delivery artifact before GitHub publication. That would wrongly shift technical-review responsibility to the Owner.
The bounded empty-repository bootstrap procedure remains:
LICENSEwording and rights-holder authority must be resolved as part of the authorized execution/review, without claiming invented rights.main. This initial default-branch creation cannot have a base PR; do not fabricate a branch-only PR exception. Lead independently reconciles remote commit/tree and then verifies branch protections.Important separation: owner's authorization of the first bounded Git operations is required; owner's personal technical inspection of local working files is not required.
22 remaining items
WU-6: restore SavepointScope dead-transaction guard; fix README versi…
WU-6: Transaction Capability — Gen2 ownership, savepoint characteriza…
megyptm commentedon Oct 28, 2026
Milestone reconciliation — WU-6 completed (2026-10-28)
Sequential delivery: WU-1 through WU-6 now MERGED and reconciled. WU-6 PR #13 was Owner-squash-merged after exact-HEAD Fresh Full Independent Re-Review #2 TECHNICAL PASS. WU-6 Issue #12 has been closed/completed with full independent post-merge evidence.
Git integrity: accepted PR HEAD
9e8b2e047ecca54ebc9e5d35c3ec20884c2ccd02, accepted tree2f9bcabd65066e73b3d9a525b1bfb70ed844c889; currentmainsquash mergea63d030de70b1aee072c367d83d4fb9853041a32, sole parentb2f2716e6469334ada7e50c2629543ec81d90947, tree exactly2f9bcabd65066e73b3d9a525b1bfb70ed844c889. 29 WU-6 paths, no other PR or concurrent merge.Gates: CI run 40757796753 completed/success on accepted HEAD, all 18 required jobs passed, including 11 MySQL/MariaDB Integration cells (genuine deadlocks), four lowest/latest PHP/Composer compatibility cells, and the single protected
CI gate; optional exploratory Innovation job intentionally skipped. Original savepoint characterization and post-SAVEPOINT transaction-ended guard passed after F13-01 correction, README ambiguity fixed by F13-02. Both findings were closed by the Lead before squash.Scope semantics: Transaction Gen2 now exists and is tested, but Ordering and Pagination remain unimplemented.
DEC-013 ACTIVEis a test-only DB version matrix and is not a support-range claim.DEC-009remains PROPOSED on the MariaDB 1020 post-error contract. No package release, tag, external consumer migration, central Standards or legacy source repository work has been authorized here.Current next milestone: WU-7 Pagination is not opened/started by this reconciliation. Its separate owner authorization and scope/preflight remain required; leave umbrella Issue #1 OPEN.
megyptm commentedon Oct 28, 2026
Sequential milestone — WU-7 AUTHORIZED / EXECUTION OPEN (2026-10-28)
The Owner explicitly approved beginning the next WU ("جميل يلا"). The Lead verified WU-1…WU-6 merged and reconciled,
main@a63d030de70b1aee072c367d83d4fb9853041a32tree2f9bcabd65066e73b3d9a525b1bfb70ed844c889,protect-mainACTIVE with requiredCI gate, no open implementation PR and no overlapping work Issue prior to the new unit.WU-7 Issue #14 is OPEN and bounded to the Pagination capability: seven relocated legacy Pagination types, three capability-specific exceptions, only approved short-name delta
PageResult→PageResultDTOandpaginate()return type, original API/SQL/array/JSON golden contract, normalization and negative-path regression, deterministic real MySQL/MariaDB Integration including caller transaction ownership and B-08a three-read snapshot limitation, plus directly relevant docs. Single Draft PR, no Order/Transaction API changes or version-range support claim. Original legacy seven Pagination files are not deprecated; do not revive any of the three retired legacy types.Legacy
main@1f6a7aafe601090b7e55f60d83794364afdefe67and publishedv1.4.0@fc1459b49fe5af5ead17814eeb3ada7a3fa81791separately checked. Pinned standards unchanged. Required source-copy provenance/rights gate, full exact-head CI, Fresh Full Independent Lead Review and separate Owner Squash Merge authorization remain mandatory.DEC-013test-only matrix remains ACTIVE; MariaDB 1020 handling remainsDEC-009 PROPOSED.Current state: WU-7 Issue opened/authorized, but no WU-7 branch/PR/code changes have been made in this Lead session. WU-8 does not start before WU-7 acceptance, Owner-authorized merge and reconciliation. Umbrella Issue #1 remains OPEN.
megyptm commentedon Oct 29, 2026
Sequential milestone reconciliation — WU-7 COMPLETED (2026-10-29)
WU-1 through WU-7 have now been merged and reconciled sequentially. WU-7 PR #15 is
MERGEDvia squash after the exact-head Fresh Full Independent Review #1 — TECHNICAL PASS. WU-7 Issue #14 is CLOSED/completed, with full post-merge reconciliation recorded.Git identity: accepted head
ca202e2953b9f0acab49691c8f0691d287639072, accepted treef855c9bb9633a913f0d381fcd53c4125089daa5a→ squashmain@659f3dc44f196380acf62d34b7cc578cf1ccbf7cwith its sole parenta63d030de70b1aee072c367d83d4fb9853041a32and identical treef855c9bb9633a913f0d381fcd53c4125089daa5a. Exactly 35 WU-7 files.refs/heads/mainverified at that squash commit; zero divergence.Evidence: CI #40766573066, exact accepted PR head: 18/18 required jobs SUCCESS, including
CI gate, four PHP compatibility jobs, 11 MySQL/MariaDB Integration jobs; optional exploratory Innovation SKIPPED by design. Golden Pagination SQL/API/JSON, B-08/B-08a/B-09, real database snapshot interleaving, failure and transaction-state tests accepted. No code delta after review because trees match.Current scope: Transaction (WU-6) and Pagination (WU-7) both delivered to
main; Ordering (WU-8) remains NOT STARTED. This reconciliation is not authorization to begin WU-8, create a tag/release, declare a DB supported range, alter central/legacy repositories, or migrate consumers.DEC-009remains PROPOSED andDEC-013is test-only. Architecture umbrella #1 remains OPEN for remaining work and later Owner decisions.megyptm commentedon Oct 29, 2026
Sequential milestone — WU-8 AUTHORIZED / EXECUTION SCOPE OPEN (2026-10-29)
The Owner expressly authorized the next Work Unit ("يلا") after verified WU-7 post-merge reconciliation. WU-1 through WU-7 are MERGED/RECONCILED. The authoritative default branch is
main@659f3dc44f196380acf62d34b7cc578cf1ccbf7c, treef855c9bb9633a913f0d381fcd53c4125089daa5a; WU-7 Issue #14 is CLOSED/completed. No open implementation PR or prior open execution Issue before this WU.protect-mainactive with exactly one required status check,CI gate. Read-only legacymain@1f6a7aafe601090b7e55f60d83794364afdefe67unchanged.WU-8 Issue #16 is now OPEN, a single vertical Ordering scope:
ScopedOrderingConfig,ScopedOrderingManager, two relocated exception classes, B-01…B-07 public and behavioral golden contracts, reuse existing Gen2 transaction runner and the shared@internalSavepointScope, stale-snapshot/lazy-savepoint/rollback/nullable-scope/soft-delete cases, source provenance, real MySQL/MariaDB experiments/CI and directly affected docs. The deprecatedOrderingTransactionExceptionand legacy duplicate helper remain excluded. Plan: one work branch / one Draft PR / independent cumulative Lead review / separate Owner Squash Merge authorization / post-merge reconciliation.Open Owner decision stays open, not silently ratified:
DEC-009 PROPOSEDon MariaDB1020caller-owned transaction safety. WU-8 is authorized to build already-approved behavior and collect test evidence (including test-only ON/OFF at MariaDB endpoints), not to adopt a new safety policy or declare supported MariaDB ranges. Its final MariaDB acceptance remains gated until the Owner resolves that material policy decision on evidence.DEC-013 ACTIVEremains test-matrix only.Current state: WU-8 issue/scoped handoff opened; no implementation PR, source branch publication, merge, release, tag, or consumer migration claimed. Architecture umbrella #1 stays OPEN.
Address Fresh Full Independent Review #1 findings F17-01 and F17-02
megyptm commentedon Oct 30, 2026
Sequential milestone — WU-8 COMPLETED / RECONCILED (2026-10-30)
WU-1 through WU-8 are now Owner-authorized SQUASH MERGED and post-merge reconciled. Ordering completes the planned three implemented capabilities (
Transaction,Pagination,Ordering) onmain. WU-8 PR #17 received independent Re-Review #2 — TECHNICAL PASS after repairing F17-01/F17-02; Issue #16 is CLOSED/completed.Git reconciliation: accepted PR HEAD
79f09d799ea969ab7b58bc3f0fb2a5da55120119, accepted tree671636e19b1064782528aac59e0acbea4298d73f→ squashmain@2212fb0a74e8f44c82b2c508f3585e2b87ed5a8c, same tree, only parent659f3dc44f196380acf62d34b7cc578cf1ccbf7c. 32 scoped files; exactly one new commit above WU-7;refs/heads/mainindependently confirmed. No other intervening main changes.Exact-HEAD evidence: CI #40969473328: 18/18 mandatory SUCCESS, including 11 required MySQL/MariaDB real integration jobs, 4 PHP/dependency compatibility jobs, static checks, workflow lint and protected
CI gate. One optional Innovation job skipped by design. Full unit/regression 505 tests; 221 integration tests per suite pass, 2 passes × 2 clean service lifecycles, zero residue. Saved review and final issue reconciliation contain detailed evidence.Next boundary: Architecture umbrella #1 stays OPEN. WU-9 documentation has NOT begun and requires Owner authorization.
DEC-009remains PROPOSED/Owner-deferred; no unconditional MariaDB support / MariaDB1020policy approved and no engine range declared.DEC-013remains test-only. No tag/release, consumer migration, legacy or central repo changes. Owner's merge permission did not grant any further release or WU authority.megyptm commentedon Oct 30, 2026
Sequential milestone — WU-9 AUTHORIZED / DOCUMENTATION SCOPE OPEN (2026-10-30)
المالك صرّح صراحةً ببدء WU-9 — Documentation & Package Reference («يلا») بعد التحقق الجديد من أن WU-8 دُمجت ومصالحتها مكتملة. فُتحت Issue #18 كوحدة توثيقية واحدة مغلقة النطاق، تشمل Package Reference canonical في جذر الحزمة، README، Usage Guide، examples،
llms.txt، وملفات presentation/governance المطلوبة لحالة Development/Unpublished، مع تحقق الأمثلة والتطابق الدلالي مع Runtime الفعلي.Exact baseline قبل التنفيذ:
main@2212fb0a74e8f44c82b2c508f3585e2b87ed5a8c، tree671636e19b1064782528aac59e0acbea4298d73f. PR #17 MERGED؛ Issue #16 CLOSED/completed؛ WU-1…WU-8 RECONCILED. في لحظة فتح #18، كانت Architecture Umbrella #1 هي الـIssue الوحيدة المفتوحة ولا توجد Open PRs. الـpinned standards ثابتة عندebcf55b0591db61d18a1407bc3effef0197b388f.Authority and policy boundary:
DEC-009تظلPROPOSED / Owner-deferred، وDEC-013 ACTIVEتختص بمصفوفة اختبارات لا إعلان Supported Database Range. لا Runtime/API redesign أو تغييرات على Legacy/central standards، ولا ادعاء Release/Composer Publication. إذن بدء WU-9 ليس إذنًا بالـMerge أو Tag أو Release أو Publish أو بدء WU-10.الحالة الآن: Issue #18 OPEN / نطاق التنفيذ مثبت. لا Implementation PR أو Merge أو Release مُعلن حتى الآن. المساعد القائد مسؤول عن Fresh Full Independent Review والـPR metadata والبوابات؛ ويتطلب أي Squash Merge إذنًا صريحًا مستقلًا من المالك.
megyptm commentedon Nov 12, 2026
WU-9 — COMPLETED / RECONCILED (2026-11-12)
اكتمل دمج ومصالحة WU-1 إلى WU-9. دُمجت PR #19 بالـSquash بتصريح المالك بعد Technical PASS على HEAD
f50f8ec9468474c2f741e92994fce52a4b1d1d7b. أصبحmain@1e13f0428665b7d18862caa969357ba9befed852بالشجرة المقبولة3a947b7b7f6b44123efa5a8ad18b6b3b88ee7fc2. نجحت وظائف CI المطلوبة العشرون على commit الدمج. أُغلقت Issue #18 كـcompleted.يتضمن
mainالآن مرجع الحزمة ودليل الاستخدام والأمثلة والتحقق منها لقدرات Transaction وPagination وOrdering. الحزمة Development / Unpublished. يظل DEC-009 مؤجلًا وDEC-013 مصفوفة اختبار. تبقى Architecture Umbrella مفتوحة، وWU-10 بانتظار تصريح بدء مستقل.CI على main
megyptm commentedon Nov 12, 2026
WU-10 — COMPLETED / RECONCILED (2026-11-12)
اكتمل دمج ومصالحة WU-1 إلى WU-10. دُمجت PR #21 بالـSquash بتصريح المالك بعد Technical PASS وإغلاق F21-04 على HEAD
d14d09bfc0cb78825d0e41ca0ea4480ad506f35b. أصبحmain@375f9aa73dacc4aa789986c6bfae0f22e8bb18d7بالشجرة المقبولة95c81dfb02845f52add52fdf87049d548f51888f.نجحت وظائف CI المطلوبة 21/21 على commit الدمج. أثبتت دورتا MySQL التعايش والتغطية التفاضلية وdeadlock replay، مع تنظيف محقق. الحزمة Development / Unpublished. تبقى Architecture Umbrella مفتوحة، وWU-11 بانتظار تصريح بدء مستقل.
Issue #20 المغلقة · CI على main
megyptm commentedon Nov 12, 2026
WU-11 — COMPLETED / RECONCILED (2026-11-12)
اكتمل دمج ومصالحة WU-1 إلى WU-11. دُمجت PR #23 بالـSquash بتصريح المالك بعد Strict Lead Preparation PASS على HEAD
2387100c7715866768ecc51dd047e2fc35a2cb3b. أصبحmain@61d4158a7c2d6edf6c0134d207058fdc2ae9cbb4بالشجرة المقبولة0e7a191580be6a7db94726e9f69f146662a3309d.هذه الـSHA مؤهلة للهدف
maatify/php-persistence:1.0.0-rc.1بعد نجاح 22/22 وظيفة مطلوبة، وفحص أرشيفَي Git وComposer المستقلين على الـSHA نفسها. تضمّن كل منهما 75 ملفًا بقائمة متطابقة. أُغلقت Issue #22 كـcompleted. الحزمة Development / Unpublished، وWU-12 بانتظار تصريح مستقل. تبقى Architecture Umbrella مفتوحة.CI على main · سجل الأرشيفين
سجل مصالحة Issue #22
megyptm commentedon Nov 12, 2026
1.0.0-rc.1 — إعادة تأهيل SHA بعد PR #24
دُمجت PR #24 بالـSquash بتصريح المالك. أصبح
main@057a87c260d6e31060a1c9d2b582db4c43eb5238، Tree4e3fb02779b0fef0f41a67c9e73ea52a85f770fa. يتضمن هذا الهدف تحديث الكلمات المفتاحية فقط فوق61d4158.هذه هي الـSHA المؤهلة للهدف
maatify/php-persistence:1.0.0-rc.1بعد نجاح 22/22 وظيفة مطلوبة وفحص أرشيفَي Git وComposer على الـSHA نفسها. WU-11 مكتملة، والحزمة Development / Unpublished، وWU-12 تنتظر تصريحًا مستقلًا.CI على main · فحص الأرشيفين
سجل إعادة التأهيل
megyptm commentedon Nov 12, 2026
1.0.0-rc.1 — إعادة تأهيل SHA بعد PR #25
دُمجت PR #25 بالـSquash بتصريح المالك. أصبح
main@4022913974e0378c9990f1ebd0e0ccd15ae25add، Tree7867d4650d8d59eced574d148a0b75d2cb5f3b08. يعكس هذا الهدف نقل المستودع إلىMaatify-ltd/php-persistenceفي روابطه الحالية وصف Repository في DEC-004.هذه هي الـSHA المؤهلة للهدف
maatify/php-persistence:1.0.0-rc.1بعد نجاح 22/22 وظيفة مطلوبة وفحص أرشيفَي Git وComposer على الـSHA نفسها. WU-11 مكتملة، والحزمة Development / Unpublished. WU-12 تنتظر تصريحًا مستقلًا.CI على main · فحص الأرشيفين
سجل إعادة التأهيل
megyptm commentedon Nov 14, 2026
حالة أول Release Candidate
نُشرت
maatify/php-persistence:1.0.0-rc.1على Packagist كنسخة تجريبية. يشير الوسم v1.0.0-rc.1 وحزمةdistإلى34c3b874525d36ae064c162cdd553bc75d18772b.نجح تثبيت النسخة الدقيقة من Packagist وتشغيل Consumer Harness عليها. دليل التحقق.
تظل #29 مفتوحة لتسجيل تجربة نفس النسخة
1.0.0-rc.1في مشروعين حقيقيين مستقلين. تُراجع أدلة التجربة قبل اتخاذ قرار أول إصدار Stable.