You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/06/07 14:49:20 UTC
(causeway) 29/50: CAUSEWAY-4014: proposes replayable command participant refinements
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 ca008a833e7474c66d3496b1d24aa043a7af0701
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 7 11:58:02 2026 +0100
CAUSEWAY-4014: proposes replayable command participant refinements
---
.../.openspec.yaml | 2 +
.../design.md | 51 +++++++++++++++
.../proposal.md | 30 +++++++++
.../specs/replayable-command-remappings/spec.md | 74 ++++++++++++++++++++++
.../tasks.md | 14 ++++
5 files changed, 171 insertions(+)
diff --git a/openspec/changes/replayable-command-participant-refinements/.openspec.yaml b/openspec/changes/replayable-command-participant-refinements/.openspec.yaml
new file mode 100644
index 00000000000..11967fcb6a7
--- /dev/null
+++ b/openspec/changes/replayable-command-participant-refinements/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-07
diff --git a/openspec/changes/replayable-command-participant-refinements/design.md b/openspec/changes/replayable-command-participant-refinements/design.md
new file mode 100644
index 00000000000..7c0505a079c
--- /dev/null
+++ b/openspec/changes/replayable-command-participant-refinements/design.md
@@ -0,0 +1,51 @@
+## Context
+
+`ReplayableCommand` derives participant rows from the recorded command DTO, replay state, and replay mapping listeners.
+Target and reference parameter rows already have recorded bookmarks before replay.
+The current derivation only exposes actual target and parameter bookmarks after successful replay, even when a replay mapping listener can already provide a mapped bookmark.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Populate actual bookmark values for target participants when replay mapping lookup returns a mapping.
+- Populate actual bookmark values for reference parameter participants when replay mapping lookup returns a mapping.
+- Keep unmapped target and parameter actual bookmarks empty before successful replay.
+- Keep successful replay fallback behaviour for unmapped target and parameter participants.
+- Preserve result participant behaviour.
+
+**Non-Goals:**
+
+- Do not change the replay mapping SPI signatures.
+- Do not change participant layout or column ordering.
+- Do not change replay execution remapping behaviour.
+- Do not add persistence or schema changes.
+
+## Decisions
+
+### Split actual bookmark derivation by role
+
+Target and parameter participants should ask replay mapping listeners first, regardless of replay state.
+If lookup returns a bookmark, that bookmark becomes the actual bookmark shown on the participant.
+If lookup returns no bookmark and the command has replay state `OK`, the participant keeps the current fallback to its recorded bookmark.
+If lookup returns no bookmark and the command is not `OK`, the actual bookmark remains empty.
+
+The alternative was to keep actual values tied entirely to successful replay state, but that hides mappings that are already known before replay.
+
+### Keep result derivation tied to successful replay
+
+Result actual bookmarks should remain tied to successful replay because result mappings are observations produced by replay execution.
+This avoids presenting speculative result actuals before the command has run.
+The alternative was to apply the same eager lookup to results, but that could conflate historical result mappings with the current command execution state.
+
+### Keep listener failure tolerance
+
+Participant derivation should continue to tolerate listener lookup failures and still return rows with recorded bookmarks.
+This keeps the UI usable even when a mapping listener cannot answer a lookup.
+
+## Risks / Trade-offs
+
+- [Risk] Rendering participants may call replay mapping listeners before replay.
+ → Mitigate by reusing existing safe lookup handling and keeping failures non-fatal.
+- [Risk] A mapping available before replay might later differ if listener state changes.
+ → Mitigate by deriving rows on demand so the table reflects current listener lookup state.
diff --git a/openspec/changes/replayable-command-participant-refinements/proposal.md b/openspec/changes/replayable-command-participant-refinements/proposal.md
new file mode 100644
index 00000000000..358d76ec023
--- /dev/null
+++ b/openspec/changes/replayable-command-participant-refinements/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+Replayable command participants currently populate actual target and parameter bookmarks only when the command is already marked successful.
+Users need target and parameter rows to use replay mapping lookup immediately so known mappings are visible before replay as well as after replay.
+
+## What Changes
+
+- Refine participant derivation so target participants ask replay mapping listeners for an actual bookmark whenever a mapping exists.
+- Refine reference parameter participants to ask replay mapping listeners for an actual bookmark whenever a mapping exists.
+- Populate the target or parameter actual bookmark when lookup returns a mapped bookmark.
+- Leave actual bookmark empty for target and parameter participants when lookup returns no mapping and the command has not successfully replayed.
+- Preserve the current successful replay fallback where unchanged target and parameter participants use their recorded bookmark as the actual bookmark.
+- Keep result participant behaviour unchanged.
+- Keep the replay mapping SPI signatures unchanged.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `replayable-command-remappings`: Refines target and parameter participants so available replay mappings populate their actual bookmarks independently of replay success state.
+
+## Impact
+
+- Affects `ReplayableCommand` participant derivation in `extensions/core/commandlog/applib`.
+- Affects focused command log applib tests for participants.
+- No persistence schema, public replay mapping SPI, layout, or result participant changes are expected.
diff --git a/openspec/changes/replayable-command-participant-refinements/specs/replayable-command-remappings/spec.md b/openspec/changes/replayable-command-participant-refinements/specs/replayable-command-remappings/spec.md
new file mode 100644
index 00000000000..489718719b0
--- /dev/null
+++ b/openspec/changes/replayable-command-participant-refinements/specs/replayable-command-remappings/spec.md
@@ -0,0 +1,74 @@
+## MODIFIED Requirements
+
+### Requirement: Replayable command displays command participants
+The system SHALL expose a participants collection on each replayable command.
+The participants collection SHALL contain rows represented by `ReplayableCommandParticipant` view models.
+Each participant SHALL expose the role, parameter name, recorded bookmark, target object, parameter object, result object, and actual bookmark in that order.
+The system SHALL include target participants when the command DTO has recorded target bookmarks.
+The system SHALL include reference parameter participants when the command DTO has recorded reference parameter bookmarks.
+The system MUST NOT include non-reference parameters as bookmark participants.
+The system SHALL include a result participant when the recorded command has a recorded result bookmark.
+Each included participant SHALL expose its recorded bookmark.
+Target participants SHALL expose an actual bookmark whenever replay mapping lookup provides a mapped bookmark.
+Reference parameter participants SHALL expose an actual bookmark whenever replay mapping lookup provides a mapped bookmark.
+Target and reference parameter participants SHALL leave actual bookmarks empty before successful replay when replay mapping lookup provides no mapped bookmark.
+Target and reference parameter participants SHALL use their recorded bookmark as the actual bookmark after successful replay when replay mapping lookup provides no mapped bookmark.
+Result participants SHALL expose actual bookmarks only after the replayable command has successfully replayed.
+When a successful replay has no explicit replacement bookmark for a result participant, the participant SHALL use its recorded bookmark as the actual bookmark.
+
+#### Scenario: Target participant appears in replayable command details
+- **WHEN** a replayable command has recorded target bookmark `demoCustomer:1`
+- **THEN** the replayable command participants collection contains a participant with role `TARGET`
+- **AND** the participant has recorded bookmark `demoCustomer:1`
+
+#### Scenario: Reference parameter participant appears in replayable command details
+- **WHEN** a replayable command has reference parameter `customer` recorded as bookmark `demoCustomer:1`
+- **THEN** the replayable command participants collection contains a participant with role `PARAMETER`
+- **AND** the participant has parameter name `customer`
+- **AND** the participant has recorded bookmark `demoCustomer:1`
+
+#### Scenario: Non-reference parameter is omitted
+- **WHEN** a replayable command has parameter `name` recorded as a string value
+- **THEN** the replayable command participants collection does not contain a participant for parameter `name`
+
+#### Scenario: Pending command populates mapped target actual bookmark
+- **WHEN** a replayable command has replay state `PENDING`
+- **AND** the replayable command has recorded target bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides actual bookmark `demoCustomer:2`
+- **THEN** the target participant has actual bookmark `demoCustomer:2`
+
+#### Scenario: Pending command populates mapped parameter actual bookmark
+- **WHEN** a replayable command has replay state `PENDING`
+- **AND** the replayable command has reference parameter `customer` recorded as bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides actual bookmark `demoCustomer:2`
+- **THEN** the parameter participant has actual bookmark `demoCustomer:2`
+
+#### Scenario: Pending command leaves unmapped target actual bookmark empty
+- **WHEN** a replayable command has replay state `PENDING`
+- **AND** the replayable command has recorded target bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides no actual bookmark
+- **THEN** the target participant has no actual bookmark
+
+#### Scenario: Pending command leaves unmapped parameter actual bookmark empty
+- **WHEN** a replayable command has replay state `PENDING`
+- **AND** the replayable command has reference parameter `customer` recorded as bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides no actual bookmark
+- **THEN** the parameter participant has no actual bookmark
+
+#### Scenario: Successful replay populates mapped target actual bookmark
+- **WHEN** a replayable command has replay state `OK`
+- **AND** the replayable command has recorded target bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides actual bookmark `demoCustomer:2`
+- **THEN** the target participant has actual bookmark `demoCustomer:2`
+
+#### Scenario: Successful replay keeps unchanged target actual bookmark populated
+- **WHEN** a replayable command has replay state `OK`
+- **AND** the replayable command has recorded target bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides no actual bookmark
+- **THEN** the target participant has actual bookmark `demoCustomer:1`
+
+#### Scenario: Successful replay keeps unchanged parameter actual bookmark populated
+- **WHEN** a replayable command has replay state `OK`
+- **AND** the replayable command has reference parameter `customer` recorded as bookmark `demoCustomer:1`
+- **AND** replay mapping lookup provides no actual bookmark
+- **THEN** the parameter participant has actual bookmark `demoCustomer:1`
diff --git a/openspec/changes/replayable-command-participant-refinements/tasks.md b/openspec/changes/replayable-command-participant-refinements/tasks.md
new file mode 100644
index 00000000000..8243e04d882
--- /dev/null
+++ b/openspec/changes/replayable-command-participant-refinements/tasks.md
@@ -0,0 +1,14 @@
+## 1. Participant Actual Bookmark Lookup
+
+- [ ] 1.1 Update target participant actual bookmark derivation to use replay mapping lookup before checking replay state.
+- [ ] 1.2 Update reference parameter participant actual bookmark derivation to use replay mapping lookup before checking replay state.
+- [ ] 1.3 Preserve successful replay fallback to recorded bookmark when no target or parameter mapping exists.
+- [ ] 1.4 Preserve result participant actual bookmark behaviour.
+
+## 2. Tests and Validation
+
+- [ ] 2.1 Add or update tests for mapped target actual bookmark population before successful replay.
+- [ ] 2.2 Add or update tests for mapped parameter actual bookmark population before successful replay.
+- [ ] 2.3 Add or update tests for unmapped target and parameter actual bookmarks before and after successful replay.
+- [ ] 2.4 Run focused command log applib tests for replayable command mapping and participant behaviour.
+- [ ] 2.5 Run `openspec validate replayable-command-participant-refinements --strict`.