feat!: add opt-in strict transactional audit mode

[Zhortein]

Summary

Add an opt-in strict transactional audit mode while preserving the existing
legacy audit behavior by default.

The application owns its transactional audit entity, entry factory, storage,
PSR-20 clock and transaction boundary. The bundle supplies deterministic
Doctrine identifier extraction, Symfony Security actor resolution, strict audit
orchestration and conditional Symfony container wiring.

Why

The legacy listener remains useful for automatic fail-open audit histories, but
its fail-open behavior and persister-owned flush cannot guarantee that business
and audit writes share the same commit or rollback.

The new recorder supports application flows where an audit failure must prevent
the business commit without imposing an audit schema or persistence model.

Breaking changes and platform baseline

• PHP 8.3 or later is required.
• Symfony 7.4 or 8.x is supported.
• Doctrine ORM 3.x is required; Doctrine ORM 2 is no longer supported.
• DoctrineBundle 2.19 or 3.x is required.
• The development branch alias now targets the 2.x series.

Dropping Doctrine ORM 2 and raising the DoctrineBundle minimum are the reasons
this work targets the future 2.x series.

Legacy compatibility

The default configuration remains:

• enabled: true
• legacy_mapping.enabled: true
• transactional.enabled: false

The historical AuditEntry mapping, audit_entry schema, integer identifier,
columns, indexes, automatic listener, service aliases, sync/async writers and
fail-open behavior remain unchanged by default.

No SQL migration is mandatory merely to retain the default legacy mode.

Transactional architecture

The strict recorder is enabled explicitly with:

zhortein_auditable:
  transactional:
    enabled: true

Applications must provide:

• AuditEntryFactoryInterface
• AuditStorageInterface
• Psr\Clock\ClockInterface

The bundle does not impose a factory, storage, audit entity, table or migration.
It provides default, replaceable aliases for:

• IdentifierExtractorInterface
• AuditActorResolverInterface

The recorder:

• resolves explicit or strategy-provided subjects, actors and timestamps;
• delegates entry creation and storage;
• performs no flush, commit or rollback;
• catches no factory or storage exception;
• provides no transactional best_effort mode.

Identifier and actor resolution

The default Doctrine extractor supports:

• integers;
• strings;
• backed enums;
• stringable identifiers such as UUID objects;
• deterministic primitive composite identifiers.

The stable composite format is doctrine-composite-v1.

Identifier associations are not handled by the default extractor. Applications
can replace the extractor or provide an explicit AuditSubject.

The default Symfony Security resolver uses getUserIdentifier() and immediate
SwitchUserToken impersonation context. System and technical actors should be
provided explicitly.

PostgreSQL guarantees

A dedicated PostgreSQL 16 suite proves that an application-owned business
mutation and audit entry can:

• remain absent before the application flush;
• remain invisible outside the transaction after flush;
• become visible together after commit;
• be rolled back together;
• roll back an already-flushed business mutation when strict audit storage
  fails before commit.

These guarantees require the same EntityManager and underlying connection. The
application storage only calls persist() and never flushes.

Transactional-only applications

Applications no longer using the legacy path can explicitly configure:

zhortein_auditable:
  enabled: false

  legacy_mapping:
    enabled: false

  transactional:
    enabled: true

Disabling the mapping:

• never drops the existing audit_entry table;
• provides no migration;
• requires legacy audit production and workers to be stopped first;
• requires pending PersistAuditEntryMessage messages to be processed or
  drained;
• leaves data retention, archival or migration to the application.

Security and privacy

Applications remain responsible for:

• data minimization;
• authorization;
• retention;
• encryption;
• backup;
• compliance;
• access to audit data.

The bundle does not automatically provide cryptographic signatures, hash
chaining, append-only storage, tamper evidence, archival, purge, anonymization
or legal compliance.

getUserIdentifier() may itself be personal data. Applications needing an
opaque actor identifier can replace the actor resolver or provide an explicit
AuditActor.

Supported matrix

The CI executes:

• PHP 8.3, 8.4 and 8.5;
• Symfony 7.4, 8.0 and 8.1;
• DoctrineBundle 2.19, 2.x and 3.x;
• Doctrine ORM 3;
• DBAL 3 and 4;
• native and polyfilled mbstring boundaries;
• PostgreSQL 16 transactional proofs.

PHPStan 2 runs at maximum level across PHP 8.3 through 8.5 without a baseline or
global ignored errors.

Test results

General runtime matrix, six lines:

• 222 tests
• 2,220 assertions
• 0 failures, errors, skips or risky tests

PostgreSQL matrix, two lines:

• 4 tests
• 78 assertions
• 0 failures, errors, skips or risky tests

Additional gates:

• PHPStan 2 at maximum level;
• PHP-CS-Fixer;
• Composer Audit;
• Actionlint;
• self-contained Composer package archive;
• no-dev package installation and runtime autoload verification.

Migration and operating documentation

The branch includes:

• UPGRADE-2.0.md
• docs/legacy-mode.md
• docs/transactional-doctrine.md
• docs/security-privacy.md
• docs/compatibility.md

Both the 1.0.0 and future 2.0.0 public APIs are protected by deterministic
contract snapshots.

Release workflow

This draft pull request targets develop, the integration branch.

It must not be merged into main directly.

After review and green CI on develop, the release process will use a separate
release/2.0.0 branch created from develop. That release branch will:

• finalize the 2.0.0 changelog version and release date;
• receive a final release-candidate validation;
• open a separate pull request toward main.

Tagging 2.0.0, creating a GitHub Release and publishing to Packagist remain
separate operations requiring explicit maintainer authorization.

After the release, main must be synchronized back into develop.

Out of scope

• no default transactional audit entity;
• no default entry factory or storage;
• no hidden flush or transaction control;
• no transactional best_effort mode;
• no automatic legacy table removal;
• no production migration;
• no automatic Doctrine ORM downgrade path;
• no tag, GitHub release or Packagist publication in this PR.

Release status

This is a draft integration branch for the future 2.x series.

It has not been tagged, released or published.