(causeway) 13/50: CAUSEWAY-4013: adds replayable command result proposal

[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 a046d1157dd025e1bc3cfcb9752802117f446dda
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 7 06:59:29 2026 +0100

    CAUSEWAY-4013: adds replayable command result proposal
---
 .../show-replayable-command-result/.openspec.yaml  |  2 +
 .../show-replayable-command-result/design.md       | 47 ++++++++++++++++++++++
 .../show-replayable-command-result/proposal.md     | 24 +++++++++++
 .../specs/command-export-yaml-result/spec.md       | 22 ++++++++++
 .../show-replayable-command-result/tasks.md        | 13 ++++++
 5 files changed, 108 insertions(+)

diff --git a/openspec/changes/show-replayable-command-result/.openspec.yaml b/openspec/changes/show-replayable-command-result/.openspec.yaml
new file mode 100644
index 00000000000..11967fcb6a7
--- /dev/null
+++ b/openspec/changes/show-replayable-command-result/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-07
diff --git a/openspec/changes/show-replayable-command-result/design.md b/openspec/changes/show-replayable-command-result/design.md
new file mode 100644
index 00000000000..a51464f0639
--- /dev/null
+++ b/openspec/changes/show-replayable-command-result/design.md
@@ -0,0 +1,47 @@
+## Context
+
+ReplayableCommand is a view model over command-log entries used to inspect and replay imported commands.
+It currently renders the recorded `CommandDto` as YAML through the `dto` property and exposes replay state, target, member, and timestamp details.
+Command export and import already preserve returned object metadata as a `result` element containing bookmark `type` and `id` values.
+That metadata is stored on the associated `CommandLogEntry`, but it is not visible directly on ReplayableCommand.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose recorded result bookmark metadata on ReplayableCommand using the same shape users see in exported YAML.
+- Keep the new display read-only and inspection-oriented.
+- Preserve the existing command DTO display and replay behavior.
+- Cover result-present and result-absent cases with focused tests.
+
+**Non-Goals:**
+
+- Change the command export YAML format.
+- Change command replay execution or replay mapping listener behavior.
+- Resolve the recorded result bookmark to a live domain object as part of the display.
+- Reintroduce or display the legacy `returnedObject` field name.
+
+## Decisions
+
+- Add a ReplayableCommand property for the recorded result bookmark rather than modifying the existing DTO property.
+  This keeps the raw command DTO view unchanged and makes result metadata easy to find in the details for imported or exported commands.
+  An alternative was to append the result into the displayed `CommandDto` YAML, but that would blur the distinction between the command DTO and the export wrapper metadata.
+
+- Render result metadata from `CommandLogEntry#getResult()` using `type` and `id` fields.
+  This matches the export wrapper contract while avoiding object resolution.
+  An alternative was to display a `Bookmark` string, but that would not match the exported `result` element shape requested by users.
+
+- Omit or render no value when a command has no recorded result bookmark.
+  This mirrors exported YAML, where result metadata is absent for commands without a result.
+  An alternative was to show an explicit empty YAML block, but that would make absent data look present.
+
+## Risks / Trade-offs
+
+- [Risk] The result is stored on `CommandLogEntry`, while ReplayableCommand caches only selected command data.
+  → Mitigation: Read the result through the existing command-log-entry lookup path and invalidate behavior only if necessary.
+
+- [Risk] A result bookmark might not resolve in the current environment after import.
+  → Mitigation: Display bookmark metadata only and do not require object lookup.
+
+- [Risk] Table views could become noisy if result metadata is shown in collection tables.
+  → Mitigation: Use layout settings consistent with the existing DTO property and hide the detailed result from tables if the implementation chooses an AsciiDoc/YAML rendering.
diff --git a/openspec/changes/show-replayable-command-result/proposal.md b/openspec/changes/show-replayable-command-result/proposal.md
new file mode 100644
index 00000000000..838a75a0900
--- /dev/null
+++ b/openspec/changes/show-replayable-command-result/proposal.md
@@ -0,0 +1,24 @@
+## Why
+
+ReplayableCommand currently exposes the recorded `CommandDto` but hides the result metadata stored alongside imported/exported commands.
+Operators need to inspect replay inputs and the recorded returned object in one place so they can verify replay mappings and exported command streams without opening the underlying command log entry.
+
+## What Changes
+
+- Add the recorded result metadata to the ReplayableCommand view model when a result bookmark is available.
+- Render the result using the same logical type and identifier shape used by exported command YAML under the `result` element.
+- Leave commands without result metadata unchanged.
+- Preserve the existing command DTO display and replay behavior.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `command-export-yaml-result`: ReplayableCommand exposes the exported `result` metadata for inspection.
+
+## Impact
+
+- Affects the command-log applib replay view model, especially `ReplayableCommand` and related tests.
+- May add a read-only property or DTO field rendering for the recorded result bookmark.
+- No expected changes to replay execution, import/export YAML format, or public replay mapping SPI contracts.
diff --git a/openspec/changes/show-replayable-command-result/specs/command-export-yaml-result/spec.md b/openspec/changes/show-replayable-command-result/specs/command-export-yaml-result/spec.md
new file mode 100644
index 00000000000..3eda608875f
--- /dev/null
+++ b/openspec/changes/show-replayable-command-result/specs/command-export-yaml-result/spec.md
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Replayable command displays exported result metadata
+The system SHALL expose recorded result metadata on ReplayableCommand when the underlying command log entry has a non-null result bookmark.
+The displayed result metadata SHALL use the same `result` element shape as exported command YAML, with `type` and `id` fields derived from the result bookmark.
+The system SHALL leave ReplayableCommand result metadata absent when the underlying command log entry has no result bookmark.
+The system MUST NOT display the legacy `returnedObject` field name for ReplayableCommand result metadata.
+The system MUST NOT require the result bookmark to resolve to a live domain object before displaying the metadata.
+
+#### Scenario: Replayable command with recorded result
+- **WHEN** a ReplayableCommand wraps a command log entry whose result bookmark is `demoCustomer:1`
+- **THEN** ReplayableCommand displays result metadata using field `result` with type `demoCustomer` and id `1`
+- **AND** ReplayableCommand does not display field `returnedObject`
+
+#### Scenario: Replayable command without recorded result
+- **WHEN** a ReplayableCommand wraps a command log entry whose result bookmark is null
+- **THEN** ReplayableCommand does not display result metadata
+- **AND** ReplayableCommand does not display field `returnedObject`
+
+#### Scenario: Replayable command result is unresolved locally
+- **WHEN** a ReplayableCommand wraps an imported command log entry whose result bookmark does not resolve to a local domain object
+- **THEN** ReplayableCommand still displays the bookmark type and id as result metadata
diff --git a/openspec/changes/show-replayable-command-result/tasks.md b/openspec/changes/show-replayable-command-result/tasks.md
new file mode 100644
index 00000000000..0215e821e22
--- /dev/null
+++ b/openspec/changes/show-replayable-command-result/tasks.md
@@ -0,0 +1,13 @@
+## 1. ReplayableCommand Result Display
+
+- [ ] 1.1 Inspect current ReplayableCommand properties and layout to choose where the recorded result display belongs.
+- [ ] 1.2 Add a read-only ReplayableCommand property that obtains `CommandLogEntry#getResult()` and renders it as exported `result` metadata with `type` and `id` fields.
+- [ ] 1.3 Ensure the property is absent or empty when no result bookmark is recorded and never emits `returnedObject`.
+- [ ] 1.4 Ensure the property displays bookmark metadata without resolving the bookmark to a domain object.
+
+## 2. Tests and Validation
+
+- [ ] 2.1 Add focused tests for ReplayableCommand result display with a recorded result bookmark.
+- [ ] 2.2 Add focused tests for no recorded result and unresolved-result behavior.
+- [ ] 2.3 Run the relevant command-log applib tests.
+- [ ] 2.4 Run `openspec validate show-replayable-command-result --strict`.