Define PDO coordinated operation contracts

[alexstandiford]

Purpose

Add optional coordinated operations to the MySQL PDO backend. Siren can reach this capability through the storage-neutral datastore contract and PHPNomad handler bridge. Siren Core receives no SQL or database object.

This PR targets main. Its shared database contracts resolve from the merged release/2.2 branch at 17fb84703d260a66de874704ae37cf924b9d8c2b.

Coordination contract

PdoCoordinatedDatabaseStrategy owns one attempt on its injected connection. It validates the session and every participant, guards the existing coordination record, invokes the callback once, and classifies commit, conflict, cleanup, or uncertain outcomes without replay.

Participant descriptors provide names only. Admission does not invoke descriptor identity callbacks. Each participant name is captured once. Primary-key identity comes from live storage metadata, and the coordination key is read before the transaction and rechecked after the record guard inside the transaction. A metadata change between those reads is refused before the callback.

The supported profile requires MySQL 8, stable InnoDB base tables, supported session settings, complete primary keys, and direct trigger visibility. MySQL 5.7 is not supported for coordination. It is explicitly classified and refused before the transaction and callback because the required role and session metadata is unavailable there.

Supplied queries and internal coordination statements check transaction ownership. An inactive driver failure is retryable only when the adapter observed that exact failure during the current owned attempt. Error numbers alone do not prove rollback.

Failure reporting

The adapter constructs the final classified operation failure before reporting it. If the logger throws an Exception or Error, CoordinatedOperationReportingFailedException retains both the exact operation failure and the exact reporting failure. Reporting is attempted once. It is not retried, and successful coordination does not touch the failure logger.

The contract covers validation refusal, confirmed callback rollback, confirmed conflict, commit uncertainty, cleanup failure, transaction ownership loss, and logger failures before and after a recorded entry. Tests assert callback count, persisted outcome, transaction state, reporting count, and retained exception identity.

Architecture and audit context:

• PHPNomad architecture: PDO coordinated operations (Source 9778)
• PHPNomad architecture: Coordinated failure reporting (Source 9935)
• Retrospective audit: PHPNomad database consumer compatibility (Source 9959)

Verification

• Composer validation passes with composer validate --strict.
• PHP syntax passes for every source and test file.
• The repository's configured PHPStan level 5 analysis passes across lib and tests.
• Focused PHPStan level 9 analysis passes for the changed coordination implementation and contracts.
• MySQL 8.4 full package proof passes with 325 tests, 3214 assertions using --exclude-group mysql57 --fail-on-incomplete --fail-on-skipped.
• MySQL 5.7 refusal proof passes with 2 tests, 20 assertions using --group mysql57 --fail-on-incomplete --fail-on-skipped.
• The descriptor compatibility proof requires each participant getName() exactly once and getFieldsForIdentity() never.
• The storage stability proof changes observed primary metadata after the coordination record guard and confirms refusal, rollback, no callback, and bounded reporting.
• Git diff checking passes.

The two pre-existing PHPStan findings were resolved narrowly. The late-static fromPdo() factory keeps its consumer-compatible API with a line-level analyzer exception. The placeholder parser now has a defensive default refusal for an unreachable token.

This remains a draft. This PR performs no merge, release, tag, deployment, or consumer wiring.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-28T18:02:15.779366Z	e3f0146	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.