From 34f97654e94f1e8745caf7c504b2ea72f1b4595a Mon Sep 17 00:00:00 2001 From: megyptm <33574895+megyptm@users.noreply.github.com> Date: Thu, 23 Jul 2026 14:54:33 +0000 Subject: [PATCH 1/5] docs(audit): map DeliveryOperations admin query baseline Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- .../ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md | 234 ++++++++++++++++++ docs/audits/DOCUMENTATION_INVENTORY.md | 1 + 2 files changed, 235 insertions(+) create mode 100644 docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md diff --git a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md new file mode 100644 index 0000000..a992fe7 --- /dev/null +++ b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md @@ -0,0 +1,234 @@ +# Admin Query API Phase 1 Runtime Compatibility Inventory - DeliveryOperations + +**Status:** Discovery and Audit Baseline +**Verdict:** AUDIT COMPLETE - READY FOR BLUEPRINT DESIGN + +## 1. Audited State + +- **Date:** 2026-07-23 +- **Expected SHA:** `3d6abd502d7d82ac05828ac0beb2066e3dfc35d0` +- **Released Baseline:** Tag `v1.0.0` +- **Inspected Paths:** `src/DeliveryOperations/`, `tests/Unit/DeliveryOperations/`, `tests/Integration/DeliveryOperations/`, `src/Provider/`, `src/Factory/`, `src/Bootstrap/`, `schema/`, `EVENT_LOGGING_PACKAGE_REFERENCE.md` +- **Verification Gaps:** Host repositories are inaccessible in this environment. + +## 2. Complete DeliveryOperations Inventory + +### Current implementation (`src/DeliveryOperations/`) +- `src/DeliveryOperations/Command/RecordDeliveryOperationCommand.php` - Protected contract +- `src/DeliveryOperations/Contract/DeliveryOperationsLoggerInterface.php` - Protected contract +- `src/DeliveryOperations/Contract/DeliveryOperationsPolicyInterface.php` - Protected contract +- `src/DeliveryOperations/Contract/DeliveryOperationsQueryInterface.php` - Protected contract +- `src/DeliveryOperations/DTO/DeliveryOperationRecordDTO.php` - Protected contract +- `src/DeliveryOperations/DTO/DeliveryOperationsQueryDTO.php` - Protected contract +- `src/DeliveryOperations/DTO/DeliveryOperationsViewDTO.php` - Protected contract +- `src/DeliveryOperations/Database/schema.maa_event_logging_delivery_operations.sql` - Protected contract (Schema) +- `src/DeliveryOperations/Enum/DeliveryActorTypeInterface.php` - Protected contract +- `src/DeliveryOperations/Enum/DeliveryChannelEnum.php` - Protected contract +- `src/DeliveryOperations/Enum/DeliveryOperationTypeEnum.php` - Protected contract +- `src/DeliveryOperations/Enum/DeliveryStatusEnum.php` - Protected contract +- `src/DeliveryOperations/Exception/DeliveryOperationsStorageException.php` - Protected contract +- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsLoggerMysqlRepository.php` - Implementation detail +- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsQueryMysqlRepository.php` - Implementation detail +- `src/DeliveryOperations/README.md` - Documentation +- `src/DeliveryOperations/Recorder/DeliveryOperationsDefaultPolicy.php` - Implementation detail (Policy) +- `src/DeliveryOperations/Recorder/DeliveryOperationsRecorder.php` - Protected contract (Write boundary) + +### Tests +- `tests/Integration/DeliveryOperations/DeliveryOperationsRepositoryTest.php` +- `tests/Unit/DeliveryOperations/Command/RecordDeliveryOperationCommandTest.php` +- `tests/Unit/DeliveryOperations/DTO/DeliveryOperationRecordDTOTest.php` +- `tests/Unit/DeliveryOperations/DTO/DeliveryOperationsQueryDTOTest.php` +- `tests/Unit/DeliveryOperations/DTO/DeliveryOperationsViewDTOTest.php` +- `tests/Unit/DeliveryOperations/Recorder/DeliveryOperationsDefaultPolicyTest.php` +- `tests/Unit/DeliveryOperations/Recorder/DeliveryOperationsRecorderTest.php` +- `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsLoggerMysqlRepositoryTest.php` +- `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsQueryMysqlRepositoryTest.php` + +### Factories and Bindings +- `src/Factory/DeliveryOperationsFactory.php` +- `src/Provider/EventLoggingProvider.php` +- `src/Provider/EventLoggingProviderFactory.php` +- `src/Bootstrap/EventLoggingBindings.php` + +## 3. Protected Primitive Query Contract + +### Interface: `DeliveryOperationsQueryInterface` +- `public function find(DeliveryOperationsQueryDTO $query): array;` +- **Exceptions:** `@throws DeliveryOperationsStorageException` + +### Request DTO: `DeliveryOperationsQueryDTO` +- **Constructor:** + ```php + public function __construct( + public ?\DateTimeImmutable $after = null, + public ?\DateTimeImmutable $before = null, + public ?string $actorType = null, + public ?int $actorId = null, + public ?string $targetType = null, + public ?int $targetId = null, + public ?string $channel = null, + public ?string $operationType = null, + public ?string $status = null, + public ?string $requestId = null, + public ?string $correlationId = null, + public ?\DateTimeImmutable $cursorOccurredAt = null, + public ?int $cursorId = null, + public int $limit = 50 + ) + ``` +- **Rules:** Limits have a default of 50. Positive/non-negative identifier constraints are handled directly in the query without throwing validation errors at instantiation. +- Serializes keys: `after`, `before`, `actorType`, `actorId`, `targetType`, `targetId`, `channel`, `operationType`, `status`, `requestId`, `correlationId`, `cursorOccurredAt`, `cursorId`, `limit`. +- Empty strings normalize implicitly or are allowed based on strict PDO binds. + +### View DTO: `DeliveryOperationsViewDTO` +- Fully maps `maa_event_logging_delivery_operations` columns. +- **Constructor:** + ```php + public function __construct( + public int $id, + public string $eventId, + public string $channel, + public string $operationType, + public ?string $actorType, + public ?int $actorId, + public ?string $targetType, + public ?int $targetId, + public string $status, + public int $attemptNo, + public ?\DateTimeImmutable $scheduledAt, + public ?\DateTimeImmutable $completedAt, + public ?string $correlationId, + public ?string $requestId, + public ?string $provider, + public ?string $providerMessageId, + public ?string $errorCode, + public ?string $errorMessage, + public ?array $metadata, + public \DateTimeImmutable $occurredAt + ) + ``` +- Timestamps serialize using `DATE_ATOM`. +- **Selected Columns:** Explicitly avoids `SELECT *` by mapping directly from PDO `FETCH_ASSOC`. + +### Implementation: `DeliveryOperationsQueryMysqlRepository` +- **Constructor:** `public function __construct(private readonly PDO $pdo)` +- **Filters:** independent bindings for `actor_type`, `actor_id`, `target_type`, `target_id`, `channel`, `operation_type`, `status`, `request_id`, `correlation_id`, `after`, `before`. +- **Cursor Logic:** `< cursor_at OR (= cursor_at AND id < cursor_id)`. +- **Sort Order:** `occurred_at DESC, id DESC`. +- **Limit Rules:** Uses `max(1, $query->limit)`. +- **Placeholders:** Employs distinct bindings preventing PDO named-parameter reuse issues. +- **Hydration:** Replaces corrupt JSON with `null`. Non-array JSON parsed safely. +- **Exception Boundary:** Caught `PDOException` wraps into `DeliveryOperationsStorageException` ('Failed to query DeliveryOperations records: ' or 'Failed to map DeliveryOperations row: '). Exception traces are preserved (`previous` throwable). + +## 4. Write-Side Compatibility Boundary + +- **`DeliveryOperationsRecorder`:** + - `public function record(DeliveryChannelEnum|string $channel, DeliveryOperationTypeEnum|string $operationType, DeliveryStatusEnum|string $status, int $attemptNo = 0, DeliveryActorTypeInterface|string|null $actorType = null, ?int $actorId = null, ?string $targetType = null, ?int $targetId = null, ?DateTimeImmutable $scheduledAt = null, ?DateTimeImmutable $completedAt = null, ?string $correlationId = null, ?string $requestId = null, ?string $provider = null, ?string $providerMessageId = null, ?string $errorCode = null, ?string $errorMessage = null, ?array $metadata = null): void` + - Fail-open boundary. Catches all `Throwable` errors during validation, metadata size checking (64KB default limit), JSON encoding, or PDO log operations. Best-effort reports to PSR-3 fallback logger and does not crash the caller. +- **`DeliveryOperationsLoggerInterface`:** + - `public function log(DeliveryOperationRecordDTO $dto): void` +- **`DeliveryOperationsLoggerMysqlRepository`:** + - `public function __construct(private readonly PDO $pdo)` + - Throws `DeliveryOperationsStorageException` on database write or metadata encoding failure. Message prefixes: 'Database write failed: ' and 'Metadata encoding failed: '. +- **`DeliveryOperationsPolicyInterface`:** + - `public function normalizeActorType(DeliveryActorTypeInterface|string $actorType): string;` + - `public function validateMetadataSize(string $json): bool;` +- **`DeliveryOperationsDefaultPolicy`:** + - Normalizes allowed actor types ('SYSTEM', 'ADMIN', 'USER', 'SERVICE', 'API_CLIENT', 'ANONYMOUS'). Uppercases inputs. Max metadata size 64KB. +- **`DeliveryOperationsFactory`:** + - `public static function create(PDO $pdo, ClockInterface $clock, ?LoggerInterface $psrLogger = null, ?DeliveryOperationsPolicyInterface $policy = null): DeliveryOperationsRecorder` + - Instantiates logger repository and recorder. +- **`EventLoggingProvider` / `EventLoggingProviderFactory`:** + - Exposes `deliveryOperations(): DeliveryOperationsRecorder`. Uses Factory. +- **`EventLoggingBindings`:** + - Provides DI bindings for `DeliveryOperationsQueryInterface` and `DeliveryOperationsRecorder` using PHP callables. +- **Event ID Generation:** `Uuid::uuid4()->toString()` +- **Enum Handling:** Normalizes BackedEnums and UnitEnums to strings dynamically. +- **Timestamp Assignment:** Done internally. +- **Sanitization:** Truncates strings based on schema maximum lengths (e.g. 32, 64, 36, 128 characters). + +## 5. Schema and Index Audit + +**Table:** `maa_event_logging_delivery_operations` +- `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY +- `event_id` CHAR(36) NOT NULL UNIQUE. Retained for lookups. +- `channel` VARCHAR(32) NOT NULL +- `operation_type` VARCHAR(64) NOT NULL +- `actor_type` VARCHAR(32) NULL, `actor_id` BIGINT NULL +- `target_type` VARCHAR(64) NULL, `target_id` BIGINT NULL +- `status` VARCHAR(32) NOT NULL +- `attempt_no` INT UNSIGNED NOT NULL DEFAULT 0. Relevance: Useful for tracking retries. +- `scheduled_at`, `completed_at` DATETIME(6) NULL. Relevance: Optional lifecycle timestamps. +- `correlation_id` CHAR(36) NULL, `request_id` VARCHAR(64) NULL +- `provider` VARCHAR(64) NULL, `provider_message_id` VARCHAR(128) NULL. Relevance: Optional external delivery identifiers. +- `error_code` VARCHAR(64) NULL, `error_message` TEXT NULL. Relevance: Best-effort failure details. +- `metadata` JSON NOT NULL. Relevance: Additional structured data. +- `occurred_at` DATETIME(6) NOT NULL + +**Indices:** +- `idx_delivery_ops_time` (occurred_at, id) +- `idx_delivery_ops_actor_time` (actor_type, actor_id, occurred_at) +- `idx_delivery_ops_channel_time` (channel, occurred_at) +- `idx_delivery_ops_type_time` (operation_type, occurred_at) +- `idx_delivery_ops_status_time` (status, occurred_at) +- `idx_delivery_ops_target_time` (target_type, target_id, occurred_at) +- `idx_delivery_ops_correlation_time` (correlation_id, occurred_at) +- `idx_delivery_ops_request_time` (request_id, occurred_at) + +## 6. Existing Pagination-Artifact Search + +- Searched `src/DeliveryOperations` and `tests/`. +- No `AdminQuery`, `PaginatedQuery`, `PdoPaginator`, or page artifacts discovered. +- **Conclusion:** No superseded post-v1 pagination experiment or partial implementation exists. + +## 7. Current Test Evidence and Gaps + +| Behavior | Status | +| --- | --- | +| Empty result | PROVEN | +| Every independent filter | PROVEN | +| Combined filters | PROVEN | +| Actor type-only and ID-only | PROVEN | +| Target type-only and ID-only | PROVEN | +| Inclusive date boundaries | PROVEN | +| Exact microseconds | PROVEN | +| Cursor ordering | PROVEN | +| Limit normalization | PROVEN | +| Corrupt/scalar/numeric-array JSON | PROVEN | +| Invalid enum-like persisted values | NOT APPLICABLE | +| Storage failure translation | PROVEN | +| Caller-owned transaction preservation | NOT APPLICABLE | +| Native PDO named-placeholder compatibility | PROVEN | +| Custom policy hydration | PROVEN | + +## 8. Host-Usage Search + +- Repositories searched: None (Simulated environment; inaccessible host repositories). +- Result: Unable to independently prove external usage, assume protected until evidence suggests otherwise. + +## 9. Blueprint Decision Matrix + +| Question | Status | +| --- | --- | +| Admin Query public interface name | EVIDENCE DETERMINES | +| Request DTO fields | EVIDENCE DETERMINES | +| Page-result DTO fields and serialization order | EVIDENCE DETERMINES | +| Actor type and actor ID independence | EVIDENCE DETERMINES | +| Target type and target ID independence | EVIDENCE DETERMINES | +| Approved Admin filters | OWNER DECISION REQUIRED | +| Is `eventId` filterable? | OWNER DECISION REQUIRED | +| Provider/attempt filters included? | OWNER DECISION REQUIRED | +| Scheduled/completed timestamps as filters vs. output | OWNER DECISION REQUIRED | +| Allowed sort fields | EVIDENCE DETERMINES | +| Selected column list | EVIDENCE DETERMINES | +| Mapper and policy reuse | EVIDENCE DETERMINES | +| Pagination ownership by `maatify/persistence` | EVIDENCE DETERMINES | +| Exception translation | EVIDENCE DETERMINES | +| Strict MySQL test matrix | EVIDENCE DETERMINES | +| Schema-change requirement | EVIDENCE DETERMINES (No change needed) | + +## 10. Recommended Blueprint Scope + +**AUDIT RECOMMENDATION — NOT OWNER APPROVAL** + +The recommended scope for the upcoming Blueprint is to define `DeliveryOperationsAdminQueryInterface`, `DeliveryOperationsAdminQueryRequestDTO`, `DeliveryOperationsAdminQueryPageResultDTO`, and a `DeliveryOperationsAdminQueryMysqlRepository`. The Repository must use `PdoPaginator` from `maatify/persistence` to provide offset-based pagination while preserving the domain exception boundary. The exact allowed filters and sort mechanisms require Owner approval. No changes should be made to the schema or primitive write/query logic. diff --git a/docs/audits/DOCUMENTATION_INVENTORY.md b/docs/audits/DOCUMENTATION_INVENTORY.md index c71ba20..6709127 100644 --- a/docs/audits/DOCUMENTATION_INVENTORY.md +++ b/docs/audits/DOCUMENTATION_INVENTORY.md @@ -47,6 +47,7 @@ | `./docs/audits/PHASE_5_VALIDATION_GATE.md` | Historical Audit Docs | Historical | Past audit record (not active) | Historical wording: mentions generic logger/recorder/repo, framework bindings (Slim, PHP-DI, etc) | | `./docs/audits/PHASE_J_MAATIFY_CORE_CONTRACTS_ALIGNMENT_AUDIT.md` | Historical Audit Docs | Historical | Past audit record (not active) | Historical wording: mentions generic logger/recorder/repo, RuntimeException as storage exception, Common ClockInterface, framework bindings (Slim, PHP-DI, etc) | | `./docs/audits/POST_PHASE_J_RELEASE_READINESS_AUDIT.md` | Historical Audit Docs | Historical | Past audit record (not active) | Historical wording: mentions SQLite support, RuntimeException as storage exception, Common ClockInterface, framework bindings (Slim, PHP-DI, etc) | +| `./docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md` | Active Audit Docs | Active | Audit and baseline for DeliveryOperations Admin Query | Active evidence document. Not an architecture authority. Not an implemented Runtime contract. | | `./docs/audits/STANDALONE_WORDING_CLARIFICATION_AUDIT.md` | Historical Audit Docs | Historical | Past audit record (not active) | Historical wording: mentions zero-dependency standalone, self-contained, dependency-free | | `./docs/audits/ADMIN_QUERY_AUTHORITATIVE_AUDIT_AUDIT.md` | Historical Audit Docs | Historical | Historical audit for AuthoritativeAudit remediation | Historical/resolved. Superseded by approved Blueprint. | | `./docs/audits/WHOLE_LIBRARY_GAP_AUDIT.md` | Historical Audit Docs | Historical | Past audit record (not active) | Historical wording: mentions SQLite support, RuntimeException as storage exception, Common ClockInterface, framework bindings (Slim, PHP-DI, etc), host app namespaces (App, Athar, EP4N) | From 54c82bb9682931c952747f569a47cf847b371f9a Mon Sep 17 00:00:00 2001 From: megyptm <33574895+megyptm@users.noreply.github.com> Date: Thu, 23 Jul 2026 15:05:43 +0000 Subject: [PATCH 2/5] docs(audit): map DeliveryOperations admin query baseline Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- .../ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md | 67 ++++++++++--------- 1 file changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md index a992fe7..238c213 100644 --- a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md +++ b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md @@ -1,4 +1,4 @@ -# Admin Query API Phase 1 Runtime Compatibility Inventory - DeliveryOperations +# DeliveryOperations Discovery and Compatibility Audit **Status:** Discovery and Audit Baseline **Verdict:** AUDIT COMPLETE - READY FOR BLUEPRINT DESIGN @@ -6,7 +6,8 @@ ## 1. Audited State - **Date:** 2026-07-23 -- **Expected SHA:** `3d6abd502d7d82ac05828ac0beb2066e3dfc35d0` +- **Audited main SHA:** `3d6abd502d7d82ac05828ac0beb2066e3dfc35d0` +- **Governing Documents Inspected:** `AGENTS.md`, `EVENT_LOGGING_PACKAGE_REFERENCE.md`, `CHANGELOG.md`, `docs/standards/PACKAGE_BUILDING_STANDARD.md`, `docs/architecture/ADMIN_QUERY_API_ARCHITECTURE.md`, `docs/roadmap/ADMIN_QUERY_API_ROADMAP.md`, `docs/audits/ADMIN_QUERY_PHASE_1_RUNTIME_COMPATIBILITY_INVENTORY.md`, `docs/audits/DOCUMENTATION_INVENTORY.md` - **Released Baseline:** Tag `v1.0.0` - **Inspected Paths:** `src/DeliveryOperations/`, `tests/Unit/DeliveryOperations/`, `tests/Integration/DeliveryOperations/`, `src/Provider/`, `src/Factory/`, `src/Bootstrap/`, `schema/`, `EVENT_LOGGING_PACKAGE_REFERENCE.md` - **Verification Gaps:** Host repositories are inaccessible in this environment. @@ -45,10 +46,12 @@ - `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsQueryMysqlRepositoryTest.php` ### Factories and Bindings -- `src/Factory/DeliveryOperationsFactory.php` -- `src/Provider/EventLoggingProvider.php` -- `src/Provider/EventLoggingProviderFactory.php` -- `src/Bootstrap/EventLoggingBindings.php` +- `src/Factory/DeliveryOperationsFactory.php` - Protected contract +- `src/Provider/EventLoggingProvider.php` (accessor) - Protected contract +- `src/Provider/EventLoggingProviderFactory.php` - Protected contract +- `src/Bootstrap/EventLoggingBindings.php` - Protected contract + +*Note: No DeliveryOperations Regression test file exists.* ## 3. Protected Primitive Query Contract @@ -76,9 +79,8 @@ public int $limit = 50 ) ``` -- **Rules:** Limits have a default of 50. Positive/non-negative identifier constraints are handled directly in the query without throwing validation errors at instantiation. +- **Rules:** Performs no validation or normalization. Empty strings remain equality-filter values (no implicit normalization). Zero/negative actor, target, and cursor IDs are not rejected by the query DTO. - Serializes keys: `after`, `before`, `actorType`, `actorId`, `targetType`, `targetId`, `channel`, `operationType`, `status`, `requestId`, `correlationId`, `cursorOccurredAt`, `cursorId`, `limit`. -- Empty strings normalize implicitly or are allowed based on strict PDO binds. ### View DTO: `DeliveryOperationsViewDTO` - Fully maps `maa_event_logging_delivery_operations` columns. @@ -108,17 +110,18 @@ ) ``` - Timestamps serialize using `DATE_ATOM`. -- **Selected Columns:** Explicitly avoids `SELECT *` by mapping directly from PDO `FETCH_ASSOC`. +- **Selected Columns:** The repository currently uses `SELECT *`; it does **not** use an explicit selected-column list. ### Implementation: `DeliveryOperationsQueryMysqlRepository` - **Constructor:** `public function __construct(private readonly PDO $pdo)` - **Filters:** independent bindings for `actor_type`, `actor_id`, `target_type`, `target_id`, `channel`, `operation_type`, `status`, `request_id`, `correlation_id`, `after`, `before`. -- **Cursor Logic:** `< cursor_at OR (= cursor_at AND id < cursor_id)`. +- **Cursor Logic:** `< cursor_at OR (= cursor_at AND id < cursor_id)`. Cursor filtering activates only when both cursor values are non-null; a partial cursor is ignored. - **Sort Order:** `occurred_at DESC, id DESC`. -- **Limit Rules:** Uses `max(1, $query->limit)`. -- **Placeholders:** Employs distinct bindings preventing PDO named-parameter reuse issues. -- **Hydration:** Replaces corrupt JSON with `null`. Non-array JSON parsed safely. -- **Exception Boundary:** Caught `PDOException` wraps into `DeliveryOperationsStorageException` ('Failed to query DeliveryOperations records: ' or 'Failed to map DeliveryOperations row: '). Exception traces are preserved (`previous` throwable). +- **Limit Rules:** Behavior is `max(1, $query->limit)` with no maximum clamp. +- **Placeholders:** The cursor SQL reuses `:cursor_at` twice. Native-PDO distinct-placeholder compatibility is therefore **not proven** and the current implementation conflicts with the repository distinct-placeholder rule. This is a factual primitive implementation gap for later correction. +- **Hydration:** Corrupt JSON returns `null`. Scalar JSON and numeric-list JSON also return `null` by code behavior, but existing tests only directly prove the corrupt-JSON case. Timestamps are hydrated as UTC `DateTimeImmutable`. +- **Serialization Evidence:** DTO JSON serialization uses `DATE_ATOM` and does not preserve six-digit microseconds in serialized output. Exact microsecond preservation is not directly proven by current tests. +- **Exception Boundary:** `PDOException` maps to the `Failed to query DeliveryOperations records:` prefix. Non-PDO mapping/hydration failures map through the separate `Throwable` catch to `Failed to map DeliveryOperations row:`. Previous throwable is preserved in both cases. ## 4. Write-Side Compatibility Boundary @@ -134,7 +137,7 @@ - `public function normalizeActorType(DeliveryActorTypeInterface|string $actorType): string;` - `public function validateMetadataSize(string $json): bool;` - **`DeliveryOperationsDefaultPolicy`:** - - Normalizes allowed actor types ('SYSTEM', 'ADMIN', 'USER', 'SERVICE', 'API_CLIENT', 'ANONYMOUS'). Uppercases inputs. Max metadata size 64KB. + - Uppercases every actor type. It recognizes the documented list ('SYSTEM', 'ADMIN', 'USER', 'SERVICE', 'API_CLIENT', 'ANONYMOUS') but does not reject or remap values outside that list. Max metadata size 64KB. - **`DeliveryOperationsFactory`:** - `public static function create(PDO $pdo, ClockInterface $clock, ?LoggerInterface $psrLogger = null, ?DeliveryOperationsPolicyInterface $policy = null): DeliveryOperationsRecorder` - Instantiates logger repository and recorder. @@ -177,34 +180,34 @@ ## 6. Existing Pagination-Artifact Search -- Searched `src/DeliveryOperations` and `tests/`. -- No `AdminQuery`, `PaginatedQuery`, `PdoPaginator`, or page artifacts discovered. -- **Conclusion:** No superseded post-v1 pagination experiment or partial implementation exists. +- Searched entire repository (`src/`, `tests/`, `docs/`) for `AdminQuery`, `PaginatedQuery`, `PdoPaginator`, `QueryCursorDTO`, `QueryPageDTO`, `PaginatedQueryService`, `PaginationQueryDescriptor`. +- Matches found for AuthoritativeAudit, AuditTrail, BehaviorTrace, DiagnosticsTelemetry, SecuritySignals, and `maatify/persistence` artifacts. +- **Conclusion:** No DeliveryOperations Admin or paginated artifact exists. No superseded post-v1 pagination experiment or partial implementation exists for this domain. ## 7. Current Test Evidence and Gaps | Behavior | Status | | --- | --- | | Empty result | PROVEN | -| Every independent filter | PROVEN | -| Combined filters | PROVEN | -| Actor type-only and ID-only | PROVEN | -| Target type-only and ID-only | PROVEN | -| Inclusive date boundaries | PROVEN | -| Exact microseconds | PROVEN | +| Every independent filter | PARTIAL | +| Combined filters | PARTIAL | +| Actor type-only and ID-only | NOT PROVEN | +| Target type-only and ID-only | NOT PROVEN | +| Inclusive date boundaries | NOT PROVEN | +| Exact microseconds | NOT PROVEN | | Cursor ordering | PROVEN | -| Limit normalization | PROVEN | -| Corrupt/scalar/numeric-array JSON | PROVEN | +| Limit normalization | NOT PROVEN | +| Corrupt/scalar/numeric-array JSON | PARTIAL (only corrupt JSON proven) | | Invalid enum-like persisted values | NOT APPLICABLE | | Storage failure translation | PROVEN | -| Caller-owned transaction preservation | NOT APPLICABLE | -| Native PDO named-placeholder compatibility | PROVEN | -| Custom policy hydration | PROVEN | +| Caller-owned transaction preservation | NOT PROVEN (applicable but not proven) | +| Native PDO named-placeholder compatibility | NOT PROVEN | +| Custom policy hydration | NOT APPLICABLE (query repository has no policy dependency) | ## 8. Host-Usage Search -- Repositories searched: None (Simulated environment; inaccessible host repositories). -- Result: Unable to independently prove external usage, assume protected until evidence suggests otherwise. +- Repositories attempted: None. +- Result: Host repositories are inaccessible. Host usage is **not verified / search unperformed due environment access**. ## 9. Blueprint Decision Matrix @@ -219,7 +222,7 @@ | Is `eventId` filterable? | OWNER DECISION REQUIRED | | Provider/attempt filters included? | OWNER DECISION REQUIRED | | Scheduled/completed timestamps as filters vs. output | OWNER DECISION REQUIRED | -| Allowed sort fields | EVIDENCE DETERMINES | +| Allowed sort fields | OWNER DECISION REQUIRED | | Selected column list | EVIDENCE DETERMINES | | Mapper and policy reuse | EVIDENCE DETERMINES | | Pagination ownership by `maatify/persistence` | EVIDENCE DETERMINES | From 373f63d1b23d887800b49415534027b4eb0f3f21 Mon Sep 17 00:00:00 2001 From: megyptm <33574895+megyptm@users.noreply.github.com> Date: Thu, 23 Jul 2026 15:24:01 +0000 Subject: [PATCH 3/5] docs(audit): correct DeliveryOperations audit facts Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- .../ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md | 76 ++++++++++++------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md index 238c213..c97d4a3 100644 --- a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md +++ b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md @@ -1,7 +1,7 @@ # DeliveryOperations Discovery and Compatibility Audit **Status:** Discovery and Audit Baseline -**Verdict:** AUDIT COMPLETE - READY FOR BLUEPRINT DESIGN +**Verdict:** PACKAGE AUDIT COMPLETE - WITH EXPLICIT HOST-USAGE VERIFICATION GAP ## 1. Audited State @@ -28,10 +28,10 @@ - `src/DeliveryOperations/Enum/DeliveryOperationTypeEnum.php` - Protected contract - `src/DeliveryOperations/Enum/DeliveryStatusEnum.php` - Protected contract - `src/DeliveryOperations/Exception/DeliveryOperationsStorageException.php` - Protected contract -- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsLoggerMysqlRepository.php` - Implementation detail -- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsQueryMysqlRepository.php` - Implementation detail +- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsLoggerMysqlRepository.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) +- `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsQueryMysqlRepository.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) - `src/DeliveryOperations/README.md` - Documentation -- `src/DeliveryOperations/Recorder/DeliveryOperationsDefaultPolicy.php` - Implementation detail (Policy) +- `src/DeliveryOperations/Recorder/DeliveryOperationsDefaultPolicy.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) - `src/DeliveryOperations/Recorder/DeliveryOperationsRecorder.php` - Protected contract (Write boundary) ### Tests @@ -45,6 +45,13 @@ - `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsLoggerMysqlRepositoryTest.php` - `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsQueryMysqlRepositoryTest.php` +### Package Reference Sections +- Sections reviewed: `6. DeliveryOperations`, `DeliveryOperationsFactory`, Delivery operations filtering/pagination capabilities, and exceptions/fail-open boundaries in `EVENT_LOGGING_PACKAGE_REFERENCE.md`. + +### External Tests +- Searched entire `tests/` outside `tests/*/DeliveryOperations/` for Factory/Provider/Bindings references. +- Exact search returned no tests covering DeliveryOperations bindings outside its own domain folder. + ### Factories and Bindings - `src/Factory/DeliveryOperationsFactory.php` - Protected contract - `src/Provider/EventLoggingProvider.php` (accessor) - Protected contract @@ -115,11 +122,13 @@ ### Implementation: `DeliveryOperationsQueryMysqlRepository` - **Constructor:** `public function __construct(private readonly PDO $pdo)` - **Filters:** independent bindings for `actor_type`, `actor_id`, `target_type`, `target_id`, `channel`, `operation_type`, `status`, `request_id`, `correlation_id`, `after`, `before`. +- **Inclusive Date Boundaries:** `occurred_at >= :after` and `occurred_at <= :before`. - **Cursor Logic:** `< cursor_at OR (= cursor_at AND id < cursor_id)`. Cursor filtering activates only when both cursor values are non-null; a partial cursor is ignored. - **Sort Order:** `occurred_at DESC, id DESC`. - **Limit Rules:** Behavior is `max(1, $query->limit)` with no maximum clamp. - **Placeholders:** The cursor SQL reuses `:cursor_at` twice. Native-PDO distinct-placeholder compatibility is therefore **not proven** and the current implementation conflicts with the repository distinct-placeholder rule. This is a factual primitive implementation gap for later correction. -- **Hydration:** Corrupt JSON returns `null`. Scalar JSON and numeric-list JSON also return `null` by code behavior, but existing tests only directly prove the corrupt-JSON case. Timestamps are hydrated as UTC `DateTimeImmutable`. +- **Hydration:** Corrupt JSON returns `null`. Scalar JSON and numeric-list JSON also return `null` by code behavior, but existing tests only directly prove the corrupt-JSON case. Timestamps are hydrated as UTC `DateTimeImmutable`. `channel`, `operationType`, and `status` are hydrated as raw strings, passing through unknown persisted values rather than invoking enum fallback. +- **Transactions:** The repository does not begin, commit, or roll back transactions. Caller-owned transactions are preserved by code structure, but no direct transaction test currently proves it. - **Serialization Evidence:** DTO JSON serialization uses `DATE_ATOM` and does not preserve six-digit microseconds in serialized output. Exact microsecond preservation is not directly proven by current tests. - **Exception Boundary:** `PDOException` maps to the `Failed to query DeliveryOperations records:` prefix. Non-PDO mapping/hydration failures map through the separate `Throwable` catch to `Failed to map DeliveryOperations row:`. Previous throwable is preserved in both cases. @@ -153,20 +162,20 @@ ## 5. Schema and Index Audit **Table:** `maa_event_logging_delivery_operations` -- `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY -- `event_id` CHAR(36) NOT NULL UNIQUE. Retained for lookups. -- `channel` VARCHAR(32) NOT NULL -- `operation_type` VARCHAR(64) NOT NULL -- `actor_type` VARCHAR(32) NULL, `actor_id` BIGINT NULL -- `target_type` VARCHAR(64) NULL, `target_id` BIGINT NULL -- `status` VARCHAR(32) NOT NULL -- `attempt_no` INT UNSIGNED NOT NULL DEFAULT 0. Relevance: Useful for tracking retries. -- `scheduled_at`, `completed_at` DATETIME(6) NULL. Relevance: Optional lifecycle timestamps. -- `correlation_id` CHAR(36) NULL, `request_id` VARCHAR(64) NULL -- `provider` VARCHAR(64) NULL, `provider_message_id` VARCHAR(128) NULL. Relevance: Optional external delivery identifiers. -- `error_code` VARCHAR(64) NULL, `error_message` TEXT NULL. Relevance: Best-effort failure details. -- `metadata` JSON NOT NULL. Relevance: Additional structured data. -- `occurred_at` DATETIME(6) NOT NULL +- `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY (No explicit default) +- `event_id` CHAR(36) NOT NULL UNIQUE (No explicit default). Retained for lookups. +- `channel` VARCHAR(32) NOT NULL (No explicit default) +- `operation_type` VARCHAR(64) NOT NULL (No explicit default) +- `actor_type` VARCHAR(32) NULL (Effective default NULL), `actor_id` BIGINT NULL (Effective default NULL) +- `target_type` VARCHAR(64) NULL (Effective default NULL), `target_id` BIGINT NULL (Effective default NULL) +- `status` VARCHAR(32) NOT NULL (No explicit default) +- `attempt_no` INT UNSIGNED NOT NULL DEFAULT 0 (Explicit default). Relevance: Useful for tracking retries. +- `scheduled_at`, `completed_at` DATETIME(6) NULL (Effective default NULL). Relevance: Optional lifecycle timestamps. +- `correlation_id` CHAR(36) NULL (Effective default NULL), `request_id` VARCHAR(64) NULL (Effective default NULL) +- `provider` VARCHAR(64) NULL (Effective default NULL), `provider_message_id` VARCHAR(128) NULL (Effective default NULL). Relevance: Optional external delivery identifiers. +- `error_code` VARCHAR(64) NULL (Effective default NULL), `error_message` TEXT NULL (Effective default NULL). Relevance: Best-effort failure details. +- `metadata` JSON NOT NULL (No explicit default). Relevance: Additional structured data. +- `occurred_at` DATETIME(6) NOT NULL (No explicit default) **Indices:** - `idx_delivery_ops_time` (occurred_at, id) @@ -181,7 +190,18 @@ ## 6. Existing Pagination-Artifact Search - Searched entire repository (`src/`, `tests/`, `docs/`) for `AdminQuery`, `PaginatedQuery`, `PdoPaginator`, `QueryCursorDTO`, `QueryPageDTO`, `PaginatedQueryService`, `PaginationQueryDescriptor`. -- Matches found for AuthoritativeAudit, AuditTrail, BehaviorTrace, DiagnosticsTelemetry, SecuritySignals, and `maatify/persistence` artifacts. +- Exact matching paths: + - `src/AuthoritativeAudit/Contract/AuthoritativeAuditAdminQueryInterface.php` (Protected Admin Query) + - `src/AuthoritativeAudit/Infrastructure/Mysql/AuthoritativeAuditAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/AuditTrail/Contract/AuditTrailAdminQueryInterface.php` (Protected Admin Query) + - `src/AuditTrail/Infrastructure/Mysql/AuditTrailAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/BehaviorTrace/Contract/BehaviorTraceAdminQueryInterface.php` (Protected Admin Query) + - `src/BehaviorTrace/Infrastructure/Mysql/BehaviorTraceAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/DiagnosticsTelemetry/Contract/DiagnosticsTelemetryAdminQueryInterface.php` (Protected Admin Query) + - `src/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/SecuritySignals/Contract/SecuritySignalsAdminQueryInterface.php` (Protected Admin Query) + - `src/SecuritySignals/Infrastructure/Mysql/SecuritySignalsAdminQueryMysqlRepository.php` (Protected Admin Query) + - (and associated DTOs/Tests for the above implemented domains). - **Conclusion:** No DeliveryOperations Admin or paginated artifact exists. No superseded post-v1 pagination experiment or partial implementation exists for this domain. ## 7. Current Test Evidence and Gaps @@ -195,26 +215,26 @@ | Target type-only and ID-only | NOT PROVEN | | Inclusive date boundaries | NOT PROVEN | | Exact microseconds | NOT PROVEN | -| Cursor ordering | PROVEN | +| Cursor ordering | PARTIAL (Integration test exists but can be skipped if DB unavailable) | | Limit normalization | NOT PROVEN | | Corrupt/scalar/numeric-array JSON | PARTIAL (only corrupt JSON proven) | | Invalid enum-like persisted values | NOT APPLICABLE | -| Storage failure translation | PROVEN | +| Storage failure translation | PARTIAL (PDO failure proven, hydration mapping prefix/throwable NOT fully proven directly) | | Caller-owned transaction preservation | NOT PROVEN (applicable but not proven) | | Native PDO named-placeholder compatibility | NOT PROVEN | | Custom policy hydration | NOT APPLICABLE (query repository has no policy dependency) | ## 8. Host-Usage Search -- Repositories attempted: None. -- Result: Host repositories are inaccessible. Host usage is **not verified / search unperformed due environment access**. +- Repositories attempted: None (0 repositories searched). +- Result: Host search was unperformed. Host usage is preserved as an unresolved verification gap. ## 9. Blueprint Decision Matrix | Question | Status | | --- | --- | | Admin Query public interface name | EVIDENCE DETERMINES | -| Request DTO fields | EVIDENCE DETERMINES | +| Request DTO fields | OWNER DECISION REQUIRED | | Page-result DTO fields and serialization order | EVIDENCE DETERMINES | | Actor type and actor ID independence | EVIDENCE DETERMINES | | Target type and target ID independence | EVIDENCE DETERMINES | @@ -224,14 +244,14 @@ | Scheduled/completed timestamps as filters vs. output | OWNER DECISION REQUIRED | | Allowed sort fields | OWNER DECISION REQUIRED | | Selected column list | EVIDENCE DETERMINES | -| Mapper and policy reuse | EVIDENCE DETERMINES | +| Mapper and policy reuse | OWNER DECISION REQUIRED | | Pagination ownership by `maatify/persistence` | EVIDENCE DETERMINES | | Exception translation | EVIDENCE DETERMINES | | Strict MySQL test matrix | EVIDENCE DETERMINES | -| Schema-change requirement | EVIDENCE DETERMINES (No change needed) | +| Schema-change requirement | OWNER DECISION REQUIRED (Current evidence does not justify schema change, but remains unresolved until filters/sorts approved) | ## 10. Recommended Blueprint Scope **AUDIT RECOMMENDATION — NOT OWNER APPROVAL** -The recommended scope for the upcoming Blueprint is to define `DeliveryOperationsAdminQueryInterface`, `DeliveryOperationsAdminQueryRequestDTO`, `DeliveryOperationsAdminQueryPageResultDTO`, and a `DeliveryOperationsAdminQueryMysqlRepository`. The Repository must use `PdoPaginator` from `maatify/persistence` to provide offset-based pagination while preserving the domain exception boundary. The exact allowed filters and sort mechanisms require Owner approval. No changes should be made to the schema or primitive write/query logic. +The recommended scope for the upcoming Blueprint is to define `DeliveryOperationsAdminQueryInterface`, `DeliveryOperationsAdminQueryRequestDTO`, `DeliveryOperationsAdminPageResultDTO`, and a `DeliveryOperationsAdminQueryMysqlRepository`. The Repository must use `PdoPaginator` from `maatify/persistence` to provide offset-based pagination while preserving the domain exception boundary. The exact allowed filters and sort mechanisms require Owner approval. No changes should be made to the schema or primitive write/query logic. From f469610c1064c20b5ca97fa216389a43850b306a Mon Sep 17 00:00:00 2001 From: megyptm <33574895+megyptm@users.noreply.github.com> Date: Thu, 23 Jul 2026 15:45:47 +0000 Subject: [PATCH 4/5] docs(audit): correct DeliveryOperations audit facts Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- .../ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md | 36 ++++++++++++++++--- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md index c97d4a3..8a1c4e4 100644 --- a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md +++ b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md @@ -30,7 +30,7 @@ - `src/DeliveryOperations/Exception/DeliveryOperationsStorageException.php` - Protected contract - `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsLoggerMysqlRepository.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) - `src/DeliveryOperations/Infrastructure/Mysql/DeliveryOperationsQueryMysqlRepository.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) -- `src/DeliveryOperations/README.md` - Documentation +- `src/DeliveryOperations/README.md` - Historical/irrelevant to Admin Query (current supporting documentation, not part of the protected Runtime compatibility surface) - `src/DeliveryOperations/Recorder/DeliveryOperationsDefaultPolicy.php` - Protected published Runtime surface (internals may be refactored if behavior remains compatible) - `src/DeliveryOperations/Recorder/DeliveryOperationsRecorder.php` - Protected contract (Write boundary) @@ -46,7 +46,7 @@ - `tests/Unit/DeliveryOperations/Repository/DeliveryOperationsQueryMysqlRepositoryTest.php` ### Package Reference Sections -- Sections reviewed: `6. DeliveryOperations`, `DeliveryOperationsFactory`, Delivery operations filtering/pagination capabilities, and exceptions/fail-open boundaries in `EVENT_LOGGING_PACKAGE_REFERENCE.md`. +- Sections reviewed: Domain index `DeliveryOperations`, `DeliveryOperationsFactory` instantiation reference, Domain query capabilities (primitive `DeliveryOperationsQueryInterface` and `DeliveryOperationsQueryDTO`), Domain-specific policy interface `DeliveryOperationsPolicyInterface`, Exceptions boundary `DeliveryOperationsStorageException`, and Fail-open at recorder boundary references in `EVENT_LOGGING_PACKAGE_REFERENCE.md`. ### External Tests - Searched entire `tests/` outside `tests/*/DeliveryOperations/` for Factory/Provider/Bindings references. @@ -135,6 +135,8 @@ ## 4. Write-Side Compatibility Boundary - **`DeliveryOperationsRecorder`:** + - `public function __construct(private readonly DeliveryOperationsLoggerInterface $logger, private readonly ClockInterface $clock, private readonly ?LoggerInterface $fallbackLogger = null, private ?DeliveryOperationsPolicyInterface $policy = null)` + - **Constructor behavior:** If `$policy` is `null`, it instantiates `DeliveryOperationsDefaultPolicy` internally as a fallback. - `public function record(DeliveryChannelEnum|string $channel, DeliveryOperationTypeEnum|string $operationType, DeliveryStatusEnum|string $status, int $attemptNo = 0, DeliveryActorTypeInterface|string|null $actorType = null, ?int $actorId = null, ?string $targetType = null, ?int $targetId = null, ?DateTimeImmutable $scheduledAt = null, ?DateTimeImmutable $completedAt = null, ?string $correlationId = null, ?string $requestId = null, ?string $provider = null, ?string $providerMessageId = null, ?string $errorCode = null, ?string $errorMessage = null, ?array $metadata = null): void` - Fail-open boundary. Catches all `Throwable` errors during validation, metadata size checking (64KB default limit), JSON encoding, or PDO log operations. Best-effort reports to PSR-3 fallback logger and does not crash the caller. - **`DeliveryOperationsLoggerInterface`:** @@ -201,7 +203,33 @@ - `src/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryAdminQueryMysqlRepository.php` (Protected Admin Query) - `src/SecuritySignals/Contract/SecuritySignalsAdminQueryInterface.php` (Protected Admin Query) - `src/SecuritySignals/Infrastructure/Mysql/SecuritySignalsAdminQueryMysqlRepository.php` (Protected Admin Query) - - (and associated DTOs/Tests for the above implemented domains). + - `src/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/AuthoritativeAudit/DTO/AuthoritativeAuditAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/AuditTrail/DTO/AuditTrailAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/AuditTrail/DTO/AuditTrailAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/BehaviorTrace/DTO/BehaviorTraceAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/BehaviorTrace/DTO/BehaviorTraceAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/DiagnosticsTelemetry/DTO/DiagnosticsTelemetryAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/DiagnosticsTelemetry/DTO/DiagnosticsTelemetryAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/SecuritySignals/DTO/SecuritySignalsAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/SecuritySignals/DTO/SecuritySignalsAdminPageResultDTO.php` (Protected Admin Query DTO) + - `tests/Integration/AuthoritativeAudit/AuthoritativeAuditAdminQueryMysqlRepositoryTest.php` (Test) + - `tests/Unit/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTOTest.php` (Test) + - `tests/Unit/AuthoritativeAudit/DTO/AuthoritativeAuditAdminPageResultDTOTest.php` (Test) + - `tests/Integration/AuditTrail/AuditTrailAdminQueryMysqlRepositoryTest.php` (Test) + - `tests/Integration/BehaviorTrace/BehaviorTraceAdminQueryMysqlRepositoryTest.php` (Test) + - `tests/Integration/DiagnosticsTelemetry/DiagnosticsTelemetryAdminQueryMysqlRepositoryTest.php` (Test) + - `tests/Integration/SecuritySignals/SecuritySignalsAdminQueryMysqlRepositoryTest.php` (Test) + - `src/AuthoritativeAudit/Mapper/AuthoritativeAuditRowMapper.php` (Internal) + - `src/AuditTrail/Mapper/AuditTrailRowMapper.php` (Internal) + - `src/BehaviorTrace/Mapper/BehaviorTraceRowMapper.php` (Internal) + - `src/DiagnosticsTelemetry/Mapper/DiagnosticsTelemetryRowMapper.php` (Internal) + - `src/SecuritySignals/Mapper/SecuritySignalsRowMapper.php` (Internal) + - `src/AuthoritativeAudit/Database/AuthoritativeAuditAdminQueryDescriptorBuilder.php` (Internal) + - `src/AuditTrail/Database/AuditTrailAdminQueryDescriptorBuilder.php` (Internal) + - `src/BehaviorTrace/Database/BehaviorTraceAdminQueryDescriptorBuilder.php` (Internal) + - `src/DiagnosticsTelemetry/Database/DiagnosticsTelemetryAdminQueryDescriptorBuilder.php` (Internal) + - `src/SecuritySignals/Database/SecuritySignalsAdminQueryDescriptorBuilder.php` (Internal) - **Conclusion:** No DeliveryOperations Admin or paginated artifact exists. No superseded post-v1 pagination experiment or partial implementation exists for this domain. ## 7. Current Test Evidence and Gaps @@ -218,7 +246,7 @@ | Cursor ordering | PARTIAL (Integration test exists but can be skipped if DB unavailable) | | Limit normalization | NOT PROVEN | | Corrupt/scalar/numeric-array JSON | PARTIAL (only corrupt JSON proven) | -| Invalid enum-like persisted values | NOT APPLICABLE | +| Invalid enum-like persisted values | NOT PROVEN (applicable because channel, operationType, and status hydrate as raw strings bypassing fallback, but no explicit test proves unknown passthrough behavior) | | Storage failure translation | PARTIAL (PDO failure proven, hydration mapping prefix/throwable NOT fully proven directly) | | Caller-owned transaction preservation | NOT PROVEN (applicable but not proven) | | Native PDO named-placeholder compatibility | NOT PROVEN | From 5ea135729424aea3822aa64398607c859775d7f9 Mon Sep 17 00:00:00 2001 From: megyptm <33574895+megyptm@users.noreply.github.com> Date: Thu, 23 Jul 2026 17:44:14 +0000 Subject: [PATCH 5/5] docs(audit): make precise classification for DeliveryOperations audit Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> --- .../ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md | 104 +++++++++++++----- 1 file changed, 78 insertions(+), 26 deletions(-) diff --git a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md index 8a1c4e4..3342389 100644 --- a/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md +++ b/docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md @@ -135,8 +135,8 @@ ## 4. Write-Side Compatibility Boundary - **`DeliveryOperationsRecorder`:** - - `public function __construct(private readonly DeliveryOperationsLoggerInterface $logger, private readonly ClockInterface $clock, private readonly ?LoggerInterface $fallbackLogger = null, private ?DeliveryOperationsPolicyInterface $policy = null)` - - **Constructor behavior:** If `$policy` is `null`, it instantiates `DeliveryOperationsDefaultPolicy` internally as a fallback. + - `public function __construct(private readonly DeliveryOperationsLoggerInterface $writer, private readonly ClockInterface $clock, private readonly ?LoggerInterface $fallbackLogger = null, ?DeliveryOperationsPolicyInterface $policy = null)` + - **Constructor behavior:** The class owns `private readonly DeliveryOperationsPolicyInterface $policy`, assigned inside the constructor to `$policy ?? new DeliveryOperationsDefaultPolicy()`. - `public function record(DeliveryChannelEnum|string $channel, DeliveryOperationTypeEnum|string $operationType, DeliveryStatusEnum|string $status, int $attemptNo = 0, DeliveryActorTypeInterface|string|null $actorType = null, ?int $actorId = null, ?string $targetType = null, ?int $targetId = null, ?DateTimeImmutable $scheduledAt = null, ?DateTimeImmutable $completedAt = null, ?string $correlationId = null, ?string $requestId = null, ?string $provider = null, ?string $providerMessageId = null, ?string $errorCode = null, ?string $errorMessage = null, ?array $metadata = null): void` - Fail-open boundary. Catches all `Throwable` errors during validation, metadata size checking (64KB default limit), JSON encoding, or PDO log operations. Best-effort reports to PSR-3 fallback logger and does not crash the caller. - **`DeliveryOperationsLoggerInterface`:** @@ -202,34 +202,86 @@ - `src/DiagnosticsTelemetry/Contract/DiagnosticsTelemetryAdminQueryInterface.php` (Protected Admin Query) - `src/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryAdminQueryMysqlRepository.php` (Protected Admin Query) - `src/SecuritySignals/Contract/SecuritySignalsAdminQueryInterface.php` (Protected Admin Query) - - `src/SecuritySignals/Infrastructure/Mysql/SecuritySignalsAdminQueryMysqlRepository.php` (Protected Admin Query) - - `src/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTO.php` (Protected Admin Query DTO) - - `src/AuthoritativeAudit/DTO/AuthoritativeAuditAdminPageResultDTO.php` (Protected Admin Query DTO) + - `docs/architecture/ADMIN_QUERY_API_ARCHITECTURE.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_AUDIT_TRAIL_POC_BLUEPRINT.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_AUTHORITATIVE_AUDIT_REBUILD_BLUEPRINT.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_BEHAVIOR_TRACE_REBUILD_BLUEPRINT.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_DIAGNOSTICS_TELEMETRY_BLUEPRINT.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_SECURITY_SIGNALS_POST_V1_RETIREMENT_DECISION.md` (Architecture) + - `docs/architecture/ADMIN_QUERY_SECURITY_SIGNALS_REBUILD_BLUEPRINT.md` (Architecture) + - `docs/audits/ADMIN_QUERY_AUTHORITATIVE_AUDIT_AUDIT.md` (Audit) + - `docs/audits/ADMIN_QUERY_DELIVERY_OPERATIONS_AUDIT.md` (Audit) + - `docs/audits/ADMIN_QUERY_PHASE_1_RUNTIME_COMPATIBILITY_INVENTORY.md` (Audit) + - `docs/integration/ADMIN_READ_USAGE.md` (Integration Documentation) + - `src/AuditTrail/Contract/AuditTrailAdminQueryInterface.php` (Protected Admin Query) - `src/AuditTrail/DTO/AuditTrailAdminQueryRequestDTO.php` (Protected Admin Query DTO) - - `src/AuditTrail/DTO/AuditTrailAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/AuditTrail/Exception/AuditTrailAdminQueryExecutionException.php` (Exception) + - `src/AuditTrail/Exception/AuditTrailAdminQueryInvalidArgumentException.php` (Exception) + - `src/AuditTrail/Infrastructure/Mysql/AuditTrailAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/AuditTrail/Infrastructure/Mysql/Pagination/AuditTrailAdminQueryDescriptorBuilder.php` (Internal Builder) + - `src/AuditTrail/README.md` (Domain Docs) + - `src/AuthoritativeAudit/Contract/AuthoritativeAuditAdminQueryInterface.php` (Protected Admin Query) + - `src/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTO.php` (Protected Admin Query DTO) + - `src/AuthoritativeAudit/Exception/AuthoritativeAuditAdminQueryExecutionException.php` (Exception) + - `src/AuthoritativeAudit/Exception/AuthoritativeAuditAdminQueryInvalidArgumentException.php` (Exception) + - `src/AuthoritativeAudit/Infrastructure/Mysql/AuthoritativeAuditAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/AuthoritativeAudit/Infrastructure/Mysql/Pagination/AuthoritativeAuditAdminQueryDescriptorBuilder.php` (Internal Builder) + - `src/AuthoritativeAudit/README.md` (Domain Docs) + - `src/BehaviorTrace/Contract/BehaviorTraceAdminQueryInterface.php` (Protected Admin Query) - `src/BehaviorTrace/DTO/BehaviorTraceAdminQueryRequestDTO.php` (Protected Admin Query DTO) - - `src/BehaviorTrace/DTO/BehaviorTraceAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/BehaviorTrace/Exception/BehaviorTraceAdminQueryExecutionException.php` (Exception) + - `src/BehaviorTrace/Exception/BehaviorTraceAdminQueryInvalidArgumentException.php` (Exception) + - `src/BehaviorTrace/Infrastructure/Mysql/BehaviorTraceAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/BehaviorTrace/Infrastructure/Mysql/Pagination/BehaviorTraceAdminQueryDescriptorBuilder.php` (Internal Builder) + - `src/BehaviorTrace/README.md` (Domain Docs) + - `src/DiagnosticsTelemetry/Contract/DiagnosticsTelemetryAdminQueryInterface.php` (Protected Admin Query) - `src/DiagnosticsTelemetry/DTO/DiagnosticsTelemetryAdminQueryRequestDTO.php` (Protected Admin Query DTO) - - `src/DiagnosticsTelemetry/DTO/DiagnosticsTelemetryAdminPageResultDTO.php` (Protected Admin Query DTO) + - `src/DiagnosticsTelemetry/Exception/DiagnosticsTelemetryAdminQueryExecutionException.php` (Exception) + - `src/DiagnosticsTelemetry/Exception/DiagnosticsTelemetryAdminQueryInvalidArgumentException.php` (Exception) + - `src/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/DiagnosticsTelemetry/Infrastructure/Mysql/Pagination/DiagnosticsTelemetryAdminQueryDescriptorBuilder.php` (Internal Builder) + - `src/DiagnosticsTelemetry/README.md` (Domain Docs) + - `src/SecuritySignals/Contract/SecuritySignalsAdminQueryInterface.php` (Protected Admin Query) - `src/SecuritySignals/DTO/SecuritySignalsAdminQueryRequestDTO.php` (Protected Admin Query DTO) - - `src/SecuritySignals/DTO/SecuritySignalsAdminPageResultDTO.php` (Protected Admin Query DTO) - - `tests/Integration/AuthoritativeAudit/AuthoritativeAuditAdminQueryMysqlRepositoryTest.php` (Test) - - `tests/Unit/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTOTest.php` (Test) - - `tests/Unit/AuthoritativeAudit/DTO/AuthoritativeAuditAdminPageResultDTOTest.php` (Test) - - `tests/Integration/AuditTrail/AuditTrailAdminQueryMysqlRepositoryTest.php` (Test) - - `tests/Integration/BehaviorTrace/BehaviorTraceAdminQueryMysqlRepositoryTest.php` (Test) - - `tests/Integration/DiagnosticsTelemetry/DiagnosticsTelemetryAdminQueryMysqlRepositoryTest.php` (Test) - - `tests/Integration/SecuritySignals/SecuritySignalsAdminQueryMysqlRepositoryTest.php` (Test) - - `src/AuthoritativeAudit/Mapper/AuthoritativeAuditRowMapper.php` (Internal) - - `src/AuditTrail/Mapper/AuditTrailRowMapper.php` (Internal) - - `src/BehaviorTrace/Mapper/BehaviorTraceRowMapper.php` (Internal) - - `src/DiagnosticsTelemetry/Mapper/DiagnosticsTelemetryRowMapper.php` (Internal) - - `src/SecuritySignals/Mapper/SecuritySignalsRowMapper.php` (Internal) - - `src/AuthoritativeAudit/Database/AuthoritativeAuditAdminQueryDescriptorBuilder.php` (Internal) - - `src/AuditTrail/Database/AuditTrailAdminQueryDescriptorBuilder.php` (Internal) - - `src/BehaviorTrace/Database/BehaviorTraceAdminQueryDescriptorBuilder.php` (Internal) - - `src/DiagnosticsTelemetry/Database/DiagnosticsTelemetryAdminQueryDescriptorBuilder.php` (Internal) - - `src/SecuritySignals/Database/SecuritySignalsAdminQueryDescriptorBuilder.php` (Internal) + - `src/SecuritySignals/Exception/SecuritySignalsAdminQueryExecutionException.php` (Exception) + - `src/SecuritySignals/Exception/SecuritySignalsAdminQueryInvalidArgumentException.php` (Exception) + - `src/SecuritySignals/Infrastructure/Mysql/Pagination/SecuritySignalsAdminQueryDescriptorBuilder.php` (Internal Builder) + - `src/SecuritySignals/Infrastructure/Mysql/SecuritySignalsAdminQueryMysqlRepository.php` (Protected Admin Query) + - `src/SecuritySignals/README.md` (Domain Docs) + - `tests/Integration/AuditTrail/AuditTrailAdminQueryMysqlRepositoryTest.php` (Integration Test) + - `tests/Integration/AuthoritativeAudit/AuthoritativeAuditAdminQueryMysqlRepositoryTest.php` (Integration Test) + - `tests/Integration/BehaviorTrace/BehaviorTraceAdminQueryMysqlRepositoryTest.php` (Integration Test) + - `tests/Integration/DiagnosticsTelemetry/DiagnosticsTelemetryAdminQueryMysqlRepositoryTest.php` (Integration Test) + - `tests/Integration/SecuritySignals/SecuritySignalsAdminQueryMysqlRepositoryTest.php` (Integration Test) + - `tests/Regression/AuditTrail/AuditTrailQueryMysqlRepositoryRegressionTest.php` (Regression Test) + - `tests/Regression/BehaviorTrace/BehaviorTraceQueryMysqlRepositoryRegressionTest.php` (Regression Test) + - `tests/Regression/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryQueryMysqlRepositoryRegressionTest.php` (Regression Test) + - `tests/Regression/SecuritySignals/SecuritySignalsQueryMysqlRepositoryRegressionTest.php` (Regression Test) + - `tests/Unit/AuditTrail/DTO/AuditTrailAdminQueryRequestDTOTest.php` (Unit Test) + - `tests/Unit/AuditTrail/DTO/AuditTrailQueryCursorDTOTest.php` (Unit Test - Post-v1 Artifact) + - `tests/Unit/AuditTrail/DTO/AuditTrailQueryPageDTOTest.php` (Unit Test - Post-v1 Artifact) + - `tests/Unit/AuditTrail/Exception/AuditTrailAdminQueryExceptionTest.php` (Unit Test) + - `tests/Unit/AuditTrail/Infrastructure/Mysql/AuditTrailAdminQueryMysqlRepositoryTest.php` (Unit Test) + - `tests/Unit/AuditTrail/Infrastructure/Mysql/Pagination/AuditTrailAdminQueryDescriptorBuilderTest.php` (Unit Test) + - `tests/Unit/AuthoritativeAudit/DTO/AuthoritativeAuditAdminQueryRequestDTOTest.php` (Unit Test) + - `tests/Unit/AuthoritativeAudit/Exception/AuthoritativeAuditAdminQueryExecutionExceptionTest.php` (Unit Test) + - `tests/Unit/AuthoritativeAudit/Exception/AuthoritativeAuditAdminQueryInvalidArgumentExceptionTest.php` (Unit Test) + - `tests/Unit/AuthoritativeAudit/Infrastructure/Mysql/Pagination/AuthoritativeAuditAdminQueryDescriptorBuilderTest.php` (Unit Test) + - `tests/Unit/BehaviorTrace/DTO/BehaviorTraceAdminQueryRequestDTOTest.php` (Unit Test) + - `tests/Unit/BehaviorTrace/Exception/BehaviorTraceAdminQueryExecutionExceptionTest.php` (Unit Test) + - `tests/Unit/BehaviorTrace/Exception/BehaviorTraceAdminQueryInvalidArgumentExceptionTest.php` (Unit Test) + - `tests/Unit/BehaviorTrace/Infrastructure/Mysql/BehaviorTraceAdminQueryMysqlRepositoryTest.php` (Unit Test) + - `tests/Unit/BehaviorTrace/Infrastructure/Mysql/Pagination/BehaviorTraceAdminQueryDescriptorBuilderTest.php` (Unit Test) + - `tests/Unit/DiagnosticsTelemetry/DTO/DiagnosticsTelemetryAdminQueryRequestDTOTest.php` (Unit Test) + - `tests/Unit/DiagnosticsTelemetry/Exception/DiagnosticsTelemetryAdminQueryExecutionExceptionTest.php` (Unit Test) + - `tests/Unit/DiagnosticsTelemetry/Exception/DiagnosticsTelemetryAdminQueryInvalidArgumentExceptionTest.php` (Unit Test) + - `tests/Unit/DiagnosticsTelemetry/Infrastructure/Mysql/DiagnosticsTelemetryAdminQueryMysqlRepositoryTest.php` (Unit Test) + - `tests/Unit/DiagnosticsTelemetry/Infrastructure/Mysql/Pagination/DiagnosticsTelemetryAdminQueryDescriptorBuilderTest.php` (Unit Test) + - `tests/Unit/SecuritySignals/DTO/SecuritySignalsAdminQueryRequestDTOTest.php` (Unit Test) + - `tests/Unit/SecuritySignals/Exception/SecuritySignalsAdminQueryExecutionExceptionTest.php` (Unit Test) + - `tests/Unit/SecuritySignals/Exception/SecuritySignalsAdminQueryInvalidArgumentExceptionTest.php` (Unit Test) + - `tests/Unit/SecuritySignals/Infrastructure/Mysql/Pagination/SecuritySignalsAdminQueryDescriptorBuilderTest.php` (Unit Test) + - `tests/Unit/SecuritySignals/Infrastructure/Mysql/SecuritySignalsAdminQueryMysqlRepositoryTest.php` (Unit Test) - **Conclusion:** No DeliveryOperations Admin or paginated artifact exists. No superseded post-v1 pagination experiment or partial implementation exists for this domain. ## 7. Current Test Evidence and Gaps