(causeway) 25/39: CAUSEWAY-4012: adds selector export proposal

[da...@apache.org]

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

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

commit ccd5ee53ee61d6e4c4548cd3b78714bcb0cf6dde
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Jun 5 16:49:38 2026 +0100

    CAUSEWAY-4012: adds selector export proposal
---
 .../.openspec.yaml                                 |  2 +
 .../publish-selector-actions-for-export/design.md  | 46 ++++++++++++++++++++++
 .../proposal.md                                    | 29 ++++++++++++++
 .../specs/command-export-yaml-result/spec.md       | 28 +++++++++++++
 .../specs/safe-action-command-publishing/spec.md   | 35 ++++++++++++++++
 .../publish-selector-actions-for-export/tasks.md   | 22 +++++++++++
 6 files changed, 162 insertions(+)

diff --git a/openspec/changes/publish-selector-actions-for-export/.openspec.yaml b/openspec/changes/publish-selector-actions-for-export/.openspec.yaml
new file mode 100644
index 00000000000..c53ef21aaaf
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-05
diff --git a/openspec/changes/publish-selector-actions-for-export/design.md b/openspec/changes/publish-selector-actions-for-export/design.md
new file mode 100644
index 00000000000..cf99468454f
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/design.md
@@ -0,0 +1,46 @@
+## Context
+
+Synthetic parented collection selector actions are safe metamodel actions generated at runtime when selector action creation is enabled.
+Safe action command publishing relies on normal command publishing facet metadata to decide whether an invocation should create a command log entry.
+If the synthetic action does not carry the expected command publishing facet, the action can exist and invoke successfully while still being invisible to the command log and therefore unavailable for export.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Ensure synthetic selector actions install command publishing metadata through the same facet model used by normal actions.
+- Ensure selector action command logging remains controlled by the existing safe action command publishing configuration.
+- Ensure a logged selector action entry can be exported by the existing command export pipeline.
+- Add focused coverage that verifies the selector action has command publishing metadata and is exportable once logged.
+
+**Non-Goals:**
+
+- Do not introduce a selector-action-specific command logging path outside the normal action invocation flow.
+- Do not make safe action command publishing enabled by default.
+- Do not change selector action ids, parameters, validation, or invocation matching behavior.
+- Do not change replay result mapping behavior.
+
+## Decisions
+
+- Install or repair the command publishing facet on synthetic selector actions during synthetic action creation.
+  This keeps the metamodel contract aligned with normal framework actions and avoids special cases in command logging or export.
+  The alternative was to add a command-log special case for selector actions, but that would bypass the facet model and increase the chance of duplicate or inconsistent logging.
+
+- Reuse the existing safe action command publishing configuration to decide whether the facet publishes commands.
+  This preserves disabled-by-default behavior and means selector actions follow the same policy as other safe actions.
+  The alternative was to add a selector-specific publishing property, but selector action creation is already separately opt-in and the command publishing policy should remain centralized.
+
+- Validate export through the presence of a persisted command log entry rather than a separate export hook.
+  The export pipeline should not need to know whether a command came from a synthetic or developer-authored safe action.
+  The alternative was to add selector-specific export handling, but that would duplicate the existing safe action export behavior.
+
+## Risks / Trade-offs
+
+- The synthetic action may already attempt to install a command publishing facet, so the defect could be caused by facet creation timing or holder metadata rather than a missing line of code.
+  Mitigation: inspect the existing facet factory path and add a test that fails on the current observed absence from command logging or export.
+
+- A metamodel-only test can prove the facet is present but not the full export behavior.
+  Mitigation: add the lightest integration-style test available for command log creation or command export when safe action publishing is enabled.
+
+- Command logging behavior depends on both selector action creation and safe action command publishing configuration.
+  Mitigation: cover both enabled and disabled safe publishing paths so selector actions do not start logging when the safe publishing opt-in is off.
diff --git a/openspec/changes/publish-selector-actions-for-export/proposal.md b/openspec/changes/publish-selector-actions-for-export/proposal.md
new file mode 100644
index 00000000000..919ff6a117c
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+Synthetic parented collection selector actions are expected to participate in safe action command publishing, but they are not appearing in the command log for export.
+This indicates that the synthetic action metamodel may not be exposing the command publishing metadata needed by the normal command logging and export pipeline.
+
+## What Changes
+
+- Ensure synthetic parented collection selector actions carry the same command publishing facet metadata expected by the safe action command publishing flow.
+- Ensure invoking a synthetic selector action creates a command log entry when safe action command publishing and selector action creation are both enabled.
+- Ensure logged synthetic selector action commands are available to command export with their command DTO and returned object metadata.
+- Preserve disabled-by-default behavior when safe action command publishing is not enabled.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `safe-action-command-publishing`: clarify that synthetic selector actions must expose command publishing facet metadata and create command log entries through the normal flow when enabled.
+- `command-export-yaml-result`: clarify that logged synthetic selector actions are exportable like other logged safe actions.
+
+## Impact
+
+- Affects synthetic selector action metamodel facet installation.
+- Affects command logging behavior for selector action invocations when both relevant opt-in properties are enabled.
+- Affects command export coverage for recorded parent-to-child navigation steps.
+- Requires focused tests proving selector actions have command publishing metadata and can be exported once logged.
diff --git a/openspec/changes/publish-selector-actions-for-export/specs/command-export-yaml-result/spec.md b/openspec/changes/publish-selector-actions-for-export/specs/command-export-yaml-result/spec.md
new file mode 100644
index 00000000000..425e61cad8b
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/specs/command-export-yaml-result/spec.md
@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: Exported command YAML includes logged safe action returned object metadata
+The system SHALL export safe action command log entries using the existing command export YAML shape when safe action command publishing created those entries.
+The system SHALL export synthetic parented collection selector action command log entries using the same command export YAML shape as other logged safe action entries.
+When a logged safe action entry has a non-null returned object bookmark, the exported YAML SHALL include returned object metadata containing the bookmark logical type name and identifier.
+The system SHALL preserve compatibility with existing command replay import for exported safe action entries.
+
+#### Scenario: Export logged safe action command with returned object
+- **GIVEN** safe action command publishing is enabled
+- **AND** a safe action command log entry has result bookmark `demoCustomer:1`
+- **WHEN** the command is selected for export
+- **THEN** the generated YAML contains the embedded command DTO for the safe action invocation
+- **AND** the generated YAML contains returned object metadata with logical type name `demoCustomer` and id `1`
+
+#### Scenario: Export logged selector action command with returned object
+- **GIVEN** synthetic parented collection selector action creation is enabled
+- **AND** safe action command publishing is enabled
+- **AND** a synthetic selector action command log entry has result bookmark `demoChild:1`
+- **WHEN** the selector action command is selected for export
+- **THEN** the generated YAML contains the embedded command DTO for the selector action invocation
+- **AND** the generated YAML contains returned object metadata with logical type name `demoChild` and id `1`
+
+#### Scenario: Export command stream containing safe and state-changing commands
+- **GIVEN** a command export selection contains a logged safe action command followed by a state-changing command that uses the found object
+- **WHEN** the commands are exported
+- **THEN** the generated YAML preserves both command entries in replay order
+- **AND** the safe action entry includes its returned object metadata when available
diff --git a/openspec/changes/publish-selector-actions-for-export/specs/safe-action-command-publishing/spec.md b/openspec/changes/publish-selector-actions-for-export/specs/safe-action-command-publishing/spec.md
new file mode 100644
index 00000000000..a636093801c
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/specs/safe-action-command-publishing/spec.md
@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: Synthetic selector actions participate in safe action command publishing
+When synthetic parented collection selector action creation is enabled, the system SHALL treat synthetic parented collection selector actions as safe actions for command publishing purposes.
+The system SHALL expose command publishing facet metadata on synthetic parented collection selector actions using the normal action command publishing facet model.
+When safe action command publishing is disabled, invoking a synthetic selector action MUST NOT create a command log entry solely because it is synthetic.
+When safe action command publishing is enabled and a synthetic selector action is invoked through the normal action invocation flow, the system SHALL create a command log entry through the normal command publishing flow.
+The command log entry for a synthetic selector action SHALL include the command DTO for the selector action invocation.
+When the synthetic selector action returns a bookmarkable child object and the framework captures a returned object bookmark, the command log entry SHALL store that returned object's bookmark as the result.
+
+#### Scenario: Selector action exposes command publishing metadata
+- **GIVEN** synthetic parented collection selector action creation is enabled
+- **WHEN** the framework synthesizes a selector action
+- **THEN** the synthetic selector action exposes command publishing facet metadata through the normal action facet model
+
+#### Scenario: Disabled safe action publishing does not log selector action
+- **GIVEN** synthetic parented collection selector action creation is enabled
+- **AND** safe action command publishing is disabled
+- **WHEN** a synthetic selector action is invoked
+- **THEN** the system does not create a command log entry solely for that invocation
+
+#### Scenario: Enabled safe action publishing logs selector action
+- **GIVEN** synthetic parented collection selector action creation is enabled
+- **AND** safe action command publishing is enabled
+- **WHEN** a synthetic selector action is invoked
+- **THEN** the system creates a command log entry for the selector action invocation through the normal command publishing flow
+- **AND** the command log entry contains the selector action command DTO
+
+#### Scenario: Logged selector action stores returned child bookmark
+- **GIVEN** synthetic parented collection selector action creation is enabled
+- **AND** safe action command publishing is enabled
+- **AND** a synthetic selector action returns bookmark `demoChild:1`
+- **WHEN** the synthetic selector action is invoked through the normal action invocation flow
+- **THEN** the system creates a command log entry for the selector action invocation
+- **AND** the command log entry result is bookmark `demoChild:1`
diff --git a/openspec/changes/publish-selector-actions-for-export/tasks.md b/openspec/changes/publish-selector-actions-for-export/tasks.md
new file mode 100644
index 00000000000..6a7b965755b
--- /dev/null
+++ b/openspec/changes/publish-selector-actions-for-export/tasks.md
@@ -0,0 +1,22 @@
+## 1. Investigate Existing Command Publishing Path
+
+- [ ] 1.1 Inspect how normal safe actions receive `CommandPublishingFacet` metadata.
+- [ ] 1.2 Inspect current synthetic selector action facet installation and identify why the command publishing facet is absent or ineffective.
+- [ ] 1.3 Identify the lightest command-log or export test fixture that can exercise a synthetic selector action invocation.
+
+## 2. Selector Action Publishing Implementation
+
+- [ ] 2.1 Ensure synthetic selector actions expose command publishing facet metadata through the normal action facet model.
+- [ ] 2.2 Ensure the facet respects the existing safe action command publishing configuration.
+- [ ] 2.3 Ensure no selector action command log entry is created when safe action command publishing is disabled.
+
+## 3. Command Log and Export Coverage
+
+- [ ] 3.1 Add focused metamodel coverage that verifies a synthetic selector action has command publishing metadata when safe action publishing is enabled.
+- [ ] 3.2 Add coverage that verifies a synthetic selector action invocation creates a command log entry with a selector command DTO when both opt-in properties are enabled.
+- [ ] 3.3 Add coverage that verifies a logged synthetic selector action is included by command export with returned object metadata when available.
+
+## 4. Validation
+
+- [ ] 4.1 Run the focused selector action and command publishing tests.
+- [ ] 4.2 Run `openspec validate publish-selector-actions-for-export --strict`.