(causeway) 18/50: CAUSEWAY-4014: proposes replay mapping finders

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch CAUSEWAY-4014
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit a60eb15a105eb3bead04f5b1c8952722802725e9
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 7 07:36:24 2026 +0100

    CAUSEWAY-4014: proposes replay mapping finders
---
 .../add-replay-mapping-finders/.openspec.yaml      |  2 +
 .../changes/add-replay-mapping-finders/design.md   | 48 +++++++++++++++
 .../changes/add-replay-mapping-finders/proposal.md | 26 +++++++++
 .../spec.md                                        | 68 ++++++++++++++++++++++
 .../changes/add-replay-mapping-finders/tasks.md    | 28 +++++++++
 5 files changed, 172 insertions(+)

diff --git a/openspec/changes/add-replay-mapping-finders/.openspec.yaml b/openspec/changes/add-replay-mapping-finders/.openspec.yaml
new file mode 100644
index 00000000000..11967fcb6a7
--- /dev/null
+++ b/openspec/changes/add-replay-mapping-finders/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-07
diff --git a/openspec/changes/add-replay-mapping-finders/design.md b/openspec/changes/add-replay-mapping-finders/design.md
new file mode 100644
index 00000000000..e34c896580d
--- /dev/null
+++ b/openspec/changes/add-replay-mapping-finders/design.md
@@ -0,0 +1,48 @@
+## Context
+
+The command log extension already has a persistent replay result mapping entity, an abstract repository contract, JDO/JPA concrete repositories, and a command log menu action that lists all persisted replay mappings.
+The repository currently supports `findAll()`, `findByRecordedBookmark(...)`, and `createAndPersist(...)`.
+The persistence entities currently define named queries for all mappings and recorded-bookmark lookup only.
+
+After identity replay results are recorded, replay mappings can support broader inspection workflows.
+Users need a changed-only view to focus on non-identity mappings, and they need lookup actions by both recorded and actual bookmarks.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add repository methods for changed mappings and actual-bookmark lookup.
+- Expose command log menu actions for all mappings, changed mappings, recorded bookmark lookup, and actual bookmark lookup.
+- Update both JDO and JPA named queries so the abstract repository can implement the new finders consistently.
+- Keep menu actions hidden when no persistent replay mapping repository is available.
+
+**Non-Goals:**
+- Do not change how mappings are recorded during replay.
+- Do not add new persistent entities or tables.
+- Do not add the final ReplayableCommand UI that consumes these finders.
+- Do not add write or delete menu actions for replay mappings.
+
+## Decisions
+
+- Keep finder methods on `CommandReplayResultMappingRepository` rather than introducing a separate query service.
+  The repository is already the abstraction used by the persistent listener and menu, and extending it keeps JDO and JPA support aligned.
+
+- Add `findChanged()` for non-identity mappings where recorded and actual bookmarks differ.
+  This creates the explicit “changed mappings” view requested by users while preserving `findAll()` for the complete view.
+
+- Add `findByActualBookmark(Bookmark)` returning a list rather than an optional value.
+  Recorded bookmark remains unique, but multiple recorded bookmarks can legitimately map to the same actual bookmark.
+
+- Add menu actions in `CommandLogMenu` next to the existing replay result mappings action.
+  The all-mappings action can retain or rename the existing behavior, while new actions should use safe semantics and disabled command/execution publishing like the current listing action.
+
+- Add an index for `actualBookmark` in JDO and JPA persistence metadata.
+  Actual-bookmark lookup is user-driven and should not require scanning all rows.
+
+## Risks / Trade-offs
+
+- [Risk] Query syntax for changed mappings differs between JDOQL and JPQL.
+  → Mitigation: Add persistence-specific named queries and test through repository integration coverage.
+- [Risk] Existing UI action names may shift if the current all-mappings action is renamed.
+  → Mitigation: Prefer adding clear actions while keeping existing behavior compatible where possible.
+- [Risk] `actualBookmark` is not unique.
+  → Mitigation: Return a list for actual-bookmark lookup and document that multiple mappings can match.
diff --git a/openspec/changes/add-replay-mapping-finders/proposal.md b/openspec/changes/add-replay-mapping-finders/proposal.md
new file mode 100644
index 00000000000..c3eb6e22b86
--- /dev/null
+++ b/openspec/changes/add-replay-mapping-finders/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+Replay result mappings now represent every replayed result object, including identity results.
+Operators need menu actions and repository finders to inspect those mappings, distinguish changed mappings, and locate mappings by either recorded or actual bookmark while working toward a richer ReplayableCommand UI.
+
+## What Changes
+
+- Add repository finder support for all replay mappings, changed-only mappings, lookup by recorded bookmark, and lookup by actual bookmark.
+- Add command log menu actions for listing all replay mappings, listing changed replay mappings, finding by recorded bookmark, and finding by actual bookmark.
+- Keep the existing list action behavior available, but align naming and behavior with the new finder set.
+- Add persistence-specific named queries and indexes where needed for actual bookmark lookup and changed-only listing.
+- Add tests for repository finders and menu actions.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `persistent-command-replay-mapping-listener`: Add finder and menu requirements for querying persisted replay mappings by all, changed-only, recorded bookmark, and actual bookmark views.
+
+## Impact
+
+- Affects the command log applib repository contract and repository abstract implementation for replay result mappings.
+- Affects JDO and JPA replay result mapping entities through additional named queries and actual-bookmark indexing.
+- Affects `CommandLogMenu` by adding user-facing safe actions for the new replay mapping finders.
+- Affects command log applib tests and persistence integration tests.
diff --git a/openspec/changes/add-replay-mapping-finders/specs/persistent-command-replay-mapping-listener/spec.md b/openspec/changes/add-replay-mapping-finders/specs/persistent-command-replay-mapping-listener/spec.md
new file mode 100644
index 00000000000..ec088df5f7f
--- /dev/null
+++ b/openspec/changes/add-replay-mapping-finders/specs/persistent-command-replay-mapping-listener/spec.md
@@ -0,0 +1,68 @@
+## MODIFIED Requirements
+
+### Requirement: Persistent replay mappings are represented by applib and persistence-specific types
+The system SHALL define an abstract applib replay result mapping entity that exposes recorded and actual bookmark properties.
+The system SHALL define an abstract applib repository for finding, listing, and creating replay result mappings.
+The abstract applib repository SHALL support listing all replay result mappings.
+The abstract applib repository SHALL support listing changed replay result mappings where the recorded bookmark and actual bookmark differ.
+The abstract applib repository SHALL support finding a replay result mapping by recorded bookmark.
+The abstract applib repository SHALL support finding replay result mappings by actual bookmark.
+The JDO command log persistence module SHALL provide a concrete replay result mapping entity and repository.
+The JPA command log persistence module SHALL provide a concrete replay result mapping entity and repository.
+
+#### Scenario: JDO module provides persistent mapping types
+- **WHEN** the command log JDO persistence module is active
+- **THEN** the system provides a concrete JDO replay result mapping entity and repository implementing the applib contracts
+
+#### Scenario: JPA module provides persistent mapping types
+- **WHEN** the command log JPA persistence module is active
+- **THEN** the system provides a concrete JPA replay result mapping entity and repository implementing the applib contracts
+
+#### Scenario: Repository lists changed replay mappings
+- **WHEN** persisted replay mappings include `demoInvoice:1` to `demoInvoice:1` and `demoInvoice:2` to `demoInvoice:3`
+- **THEN** the repository changed-mappings finder returns the mapping from `demoInvoice:2` to `demoInvoice:3`
+- **AND** the repository changed-mappings finder does not return the mapping from `demoInvoice:1` to `demoInvoice:1`
+
+#### Scenario: Repository finds replay mappings by actual bookmark
+- **WHEN** persisted replay mappings include recorded bookmark `demoInvoice:1` with actual bookmark `demoInvoice:9`
+- **AND** persisted replay mappings include recorded bookmark `demoInvoice:2` with actual bookmark `demoInvoice:9`
+- **THEN** the repository actual-bookmark finder for `demoInvoice:9` returns both persisted replay mappings
+
+### Requirement: Persistent replay mappings are listable from the command log menu
+The system SHALL provide a command log menu action that lists all persisted replay result mappings.
+The system SHALL provide a command log menu action that lists changed persisted replay result mappings where the recorded bookmark and actual bookmark differ.
+The system SHALL provide a command log menu action that finds a persisted replay result mapping by recorded bookmark.
+The system SHALL provide a command log menu action that finds persisted replay result mappings by actual bookmark.
+The system SHALL provide fallback layout metadata for the persisted replay result mapping entity.
+The list actions SHALL return persisted mappings using the abstract applib repository.
+The listed replay result mappings SHALL include identity replay results where the recorded and actual bookmarks are equal when the user asks for all mappings.
+The changed-mappings action MUST NOT return identity replay result mappings where the recorded and actual bookmarks are equal.
+The replay mapping menu actions MUST be hidden when no persistent replay result mapping repository is available.
+
+#### Scenario: User lists persisted replay mappings
+- **WHEN** a user invokes the command log menu action for all replay result mappings
+- **THEN** the system returns the persisted replay result mappings
+- **AND** each mapping displays its recorded and actual bookmarks
+
+#### Scenario: User lists persisted identity replay mappings
+- **WHEN** a persisted replay result mapping has recorded bookmark `demoInvoice:1` and actual bookmark `demoInvoice:1`
+- **AND** a user invokes the command log menu action for all replay result mappings
+- **THEN** the system returns the persisted identity replay result mapping
+- **AND** the mapping displays recorded bookmark `demoInvoice:1` and actual bookmark `demoInvoice:1`
+
+#### Scenario: User lists changed replay mappings
+- **WHEN** persisted replay mappings include `demoInvoice:1` to `demoInvoice:1` and `demoInvoice:2` to `demoInvoice:3`
+- **AND** a user invokes the command log menu action for changed replay result mappings
+- **THEN** the system returns the mapping from `demoInvoice:2` to `demoInvoice:3`
+- **AND** the system does not return the mapping from `demoInvoice:1` to `demoInvoice:1`
+
+#### Scenario: User finds replay mapping by recorded bookmark
+- **WHEN** a persisted replay result mapping has recorded bookmark `demoInvoice:1` and actual bookmark `demoInvoice:2`
+- **AND** a user invokes the command log menu action to find by recorded bookmark `demoInvoice:1`
+- **THEN** the system returns the persisted replay result mapping with recorded bookmark `demoInvoice:1`
+
+#### Scenario: User finds replay mappings by actual bookmark
+- **WHEN** persisted replay result mappings include recorded bookmark `demoInvoice:1` with actual bookmark `demoInvoice:9`
+- **AND** persisted replay result mappings include recorded bookmark `demoInvoice:2` with actual bookmark `demoInvoice:9`
+- **AND** a user invokes the command log menu action to find by actual bookmark `demoInvoice:9`
+- **THEN** the system returns both persisted replay result mappings
diff --git a/openspec/changes/add-replay-mapping-finders/tasks.md b/openspec/changes/add-replay-mapping-finders/tasks.md
new file mode 100644
index 00000000000..2a64f5eab81
--- /dev/null
+++ b/openspec/changes/add-replay-mapping-finders/tasks.md
@@ -0,0 +1,28 @@
+## 1. Repository finder contract
+
+- [ ] 1.1 Add `findChanged()` and `findByActualBookmark(Bookmark)` to `CommandReplayResultMappingRepository`.
+- [ ] 1.2 Implement the new finder methods in `CommandReplayResultMappingRepositoryAbstract` using named queries.
+- [ ] 1.3 Add named query constants for changed mappings and actual-bookmark lookup to `CommandReplayResultMapping.Nq`.
+
+## 2. Persistence queries and indexes
+
+- [ ] 2.1 Add JDO named queries for changed mappings and actual-bookmark lookup.
+- [ ] 2.2 Add JDO index metadata for `actualBookmark`.
+- [ ] 2.3 Add JPA named queries for changed mappings and actual-bookmark lookup.
+- [ ] 2.4 Add JPA index metadata for `actualBookmark`.
+
+## 3. Command log menu actions
+
+- [ ] 3.1 Keep or update the all replay mappings menu action to use the repository `findAll()` finder.
+- [ ] 3.2 Add a safe command log menu action to list changed replay mappings.
+- [ ] 3.3 Add a safe command log menu action to find a replay mapping by recorded bookmark.
+- [ ] 3.4 Add a safe command log menu action to find replay mappings by actual bookmark.
+- [ ] 3.5 Hide all replay mapping menu actions when no `CommandReplayResultMappingRepository` is available.
+
+## 4. Tests and validation
+
+- [ ] 4.1 Update repository fake/test implementations for the new finder methods.
+- [ ] 4.2 Add applib tests for changed-mapping and actual-bookmark finder behavior.
+- [ ] 4.3 Add or update menu tests for all, changed, recorded-bookmark, and actual-bookmark actions.
+- [ ] 4.4 Run focused command log applib and persistence tests covering replay mapping repository and menu behavior.
+- [ ] 4.5 Run OpenSpec validation for `add-replay-mapping-finders` and fix any issues.