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:39 UTC

(causeway) 48/50: CAUSEWAY-4014: proposes readable replay participant mementos

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 fda65b615978101b899db04b1988d7105f206b1c
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 7 15:39:54 2026 +0100

    CAUSEWAY-4014: proposes readable replay participant mementos
---
 .../.openspec.yaml                                 |  2 ++
 .../design.md                                      | 36 ++++++++++++++++++++++
 .../proposal.md                                    | 32 +++++++++++++++++++
 .../specs/replayable-command-remappings/spec.md    | 35 +++++++++++++++++++++
 .../tasks.md                                       | 22 +++++++++++++
 5 files changed, 127 insertions(+)

diff --git a/openspec/changes/simplify-replayable-command-participant-memento/.openspec.yaml b/openspec/changes/simplify-replayable-command-participant-memento/.openspec.yaml
new file mode 100644
index 00000000000..11967fcb6a7
--- /dev/null
+++ b/openspec/changes/simplify-replayable-command-participant-memento/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-07
diff --git a/openspec/changes/simplify-replayable-command-participant-memento/design.md b/openspec/changes/simplify-replayable-command-participant-memento/design.md
new file mode 100644
index 00000000000..158e0b7b2b1
--- /dev/null
+++ b/openspec/changes/simplify-replayable-command-participant-memento/design.md
@@ -0,0 +1,36 @@
+## Context
+
+`ReplayableCommandParticipant` is a view model whose current memento includes interaction id, role, parameter name, recorded bookmark, and actual bookmark.
+The bookmark data is already derived from the owning replayable command's `CommandLogEntry` and replay mapping lookups.
+Including that derived data in the memento makes URLs noisy and can make stale bookmark values appear canonical.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Use compact readable mementos based on command interaction id and participant identity.
+- Recompute recorded bookmark, actual bookmark, and object links from the owning command log entry.
+- Keep the public view model constructor shape valid with the string memento first and injected services after it.
+- Inject `CommandLogEntryRepository` into the view model constructor if that is the simplest way to rehydrate participant state.
+- Preserve existing participant UI behaviour after rehydration.
+
+**Non-Goals:**
+
+- Do not change the participants collection content or ordering.
+- Do not change replay mapping SPI signatures.
+- Do not persist participant rows independently.
+- Do not retain the old pipe-delimited bookmark-bearing memento format as the canonical URL format.
+
+## Decisions
+
+- Use `--` as the memento delimiter because the requested forms are readable and map directly to participant roles.
+- Encode target and result participants as `[commandInteractionId]--target` and `[commandInteractionId]--result` because each command has at most one semantic target participant set and one result participant in the current UI contract.
+- Encode parameter participants as `[commandInteractionId]--parameter--[parameterName]` because the parameter name distinguishes reference parameter participants.
+- Rehydrate by loading the owning `CommandLogEntry` and selecting the matching participant from the replayable command's derived participant list.
+- Keep non-public construction helpers available for tests and collection derivation, but ensure the framework-facing constructor remains a single public constructor with memento string first.
+
+## Risks / Trade-offs
+
+- Parameter names that contain `--` could make a plain split ambiguous → Parse only the first two delimiters or preserve the remaining suffix as the parameter name.
+- Old URLs that include bookmark data will not be canonical → Treat this as a breaking URL-format refinement.
+- Rehydration adds a repository lookup for standalone participant URLs → Keep collection-derived construction direct and use repository lookup only for memento reconstruction.
diff --git a/openspec/changes/simplify-replayable-command-participant-memento/proposal.md b/openspec/changes/simplify-replayable-command-participant-memento/proposal.md
new file mode 100644
index 00000000000..6c847ebb87d
--- /dev/null
+++ b/openspec/changes/simplify-replayable-command-participant-memento/proposal.md
@@ -0,0 +1,32 @@
+## Why
+
+`ReplayableCommandParticipant` currently serializes bookmark details into its view-model memento, making generated URLs hard to read and duplicating information that can be derived from the owning replayable command.
+Using a compact role-based memento keeps URLs readable while ensuring bookmark values remain calculated from the command log entry as source of truth.
+
+## What Changes
+
+- Change `ReplayableCommandParticipant` mementos to use readable role-based forms:
+  - `[commandInteractionId]--target`
+  - `[commandInteractionId]--parameter--[parameterName]`
+  - `[commandInteractionId]--result`
+- Stop serializing recorded and actual bookmark values in the participant memento.
+- Rehydrate participant bookmark data by looking up the owning command log entry by command interaction id.
+- Inject `CommandLogEntryRepository` into the view model constructor if needed to support memento rehydration.
+- Preserve participant display behaviour for recorded bookmarks, actual bookmarks, object links, title, parent link, and role-specific visibility.
+- **BREAKING**: Existing URLs that use the old pipe-delimited participant memento format will no longer be the canonical participant URL format.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `replayable-command-remappings`: Simplify replayable command participant mementos and derive bookmark data from the owning replayable command.
+
+## Impact
+
+- Affects the command log applib replay participant view model memento format and constructor dependencies.
+- Affects participant derivation and tests around memento round-tripping.
+- Does not affect replay mapping SPI signatures or persistence schema.
diff --git a/openspec/changes/simplify-replayable-command-participant-memento/specs/replayable-command-remappings/spec.md b/openspec/changes/simplify-replayable-command-participant-memento/specs/replayable-command-remappings/spec.md
new file mode 100644
index 00000000000..3c0861d004e
--- /dev/null
+++ b/openspec/changes/simplify-replayable-command-participant-memento/specs/replayable-command-remappings/spec.md
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: Replayable command participant mementos are readable and derived
+The `ReplayableCommandParticipant` view model SHALL use a readable memento based on the owning command interaction id and participant identity.
+A target participant memento SHALL use the form `[commandInteractionId]--target`.
+A parameter participant memento SHALL use the form `[commandInteractionId]--parameter--[parameterName]`.
+A result participant memento SHALL use the form `[commandInteractionId]--result`.
+The participant memento MUST NOT include recorded bookmark or actual bookmark values.
+When a participant is reconstructed from its memento, the system SHALL derive recorded bookmark, actual bookmark, and object link values from the owning replayable command and command log entry.
+The participant view model constructor used by the framework SHALL accept the string memento as its first parameter and injected services after it.
+
+#### Scenario: Target participant has readable memento
+- **WHEN** a replayable command participant has command interaction id `11111111-1111-1111-1111-111111111111` and role `TARGET`
+- **THEN** the participant memento is `11111111-1111-1111-1111-111111111111--target`
+- **AND** the memento does not contain recorded or actual bookmark values
+
+#### Scenario: Parameter participant has readable memento
+- **WHEN** a replayable command participant has command interaction id `11111111-1111-1111-1111-111111111111`, role `PARAMETER`, and parameter name `customer`
+- **THEN** the participant memento is `11111111-1111-1111-1111-111111111111--parameter--customer`
+- **AND** the memento does not contain recorded or actual bookmark values
+
+#### Scenario: Result participant has readable memento
+- **WHEN** a replayable command participant has command interaction id `11111111-1111-1111-1111-111111111111` and role `RESULT`
+- **THEN** the participant memento is `11111111-1111-1111-1111-111111111111--result`
+- **AND** the memento does not contain recorded or actual bookmark values
+
+#### Scenario: Participant rehydrates derived bookmarks from memento
+- **WHEN** a replayable command participant is reconstructed from a readable memento
+- **AND** the owning command log entry can be found by command interaction id
+- **THEN** the participant exposes the same recorded bookmark, actual bookmark, and object link values as the matching participant derived from the owning replayable command
+
+#### Scenario: View model constructor uses framework-compatible parameter order
+- **WHEN** the framework reconstructs a replayable command participant view model
+- **THEN** the constructor accepts the string memento first
+- **AND** injected services follow the string memento parameter
diff --git a/openspec/changes/simplify-replayable-command-participant-memento/tasks.md b/openspec/changes/simplify-replayable-command-participant-memento/tasks.md
new file mode 100644
index 00000000000..23956b709fb
--- /dev/null
+++ b/openspec/changes/simplify-replayable-command-participant-memento/tasks.md
@@ -0,0 +1,22 @@
+## 1. Memento Format
+
+- [ ] 1.1 Change `ReplayableCommandParticipant#viewModelMemento()` to emit `[commandInteractionId]--target` for target participants.
+- [ ] 1.2 Change `ReplayableCommandParticipant#viewModelMemento()` to emit `[commandInteractionId]--parameter--[parameterName]` for parameter participants.
+- [ ] 1.3 Change `ReplayableCommandParticipant#viewModelMemento()` to emit `[commandInteractionId]--result` for result participants.
+- [ ] 1.4 Ensure participant mementos do not include recorded bookmark or actual bookmark values.
+
+## 2. Memento Rehydration
+
+- [ ] 2.1 Keep the framework-facing view model constructor in the form `String memento` first, injected services after.
+- [ ] 2.2 Inject `CommandLogEntryRepository` or another minimal collaborator needed to find the owning command log entry by interaction id.
+- [ ] 2.3 Reconstruct target, parameter, and result participants from the owning replayable command's derived participant data.
+- [ ] 2.4 Preserve recorded bookmark, actual bookmark, object link, title, parent link, and role-specific visibility behaviour after reconstruction.
+- [ ] 2.5 Parse parameter mementos without losing parameter names that contain delimiter-like text.
+
+## 3. Tests and Validation
+
+- [ ] 3.1 Add focused tests for target, parameter, and result memento strings.
+- [ ] 3.2 Add focused tests that reconstruct participants from mementos and verify derived bookmark values.
+- [ ] 3.3 Add focused test coverage for framework-compatible constructor ordering.
+- [ ] 3.4 Run the command log applib focused test suite for replayable command mapping.
+- [ ] 3.5 Run OpenSpec validation for the change.