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/08 10:34:29 UTC
(causeway) 09/17: CAUSEWAY-4026: adds first command domain service export proposal
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-4028
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 44c866ba9fbc3246ebbea7e7b5c15bcca7db12dd
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Jun 8 10:39:38 2026 +0100
CAUSEWAY-4026: adds first command domain service export proposal
---
.../.openspec.yaml | 2 +
.../design.md | 47 ++++++++++++++++++++++
.../proposal.md | 24 +++++++++++
.../specs/command-export-known-targets/spec.md | 33 +++++++++++++++
.../specs/replayable-command-exportability/spec.md | 29 +++++++++++++
.../tasks.md | 23 +++++++++++
6 files changed, 158 insertions(+)
diff --git a/openspec/changes/require-export-first-command-domain-service/.openspec.yaml b/openspec/changes/require-export-first-command-domain-service/.openspec.yaml
new file mode 100644
index 00000000000..e8d4ccfe905
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-08
diff --git a/openspec/changes/require-export-first-command-domain-service/design.md b/openspec/changes/require-export-first-command-domain-service/design.md
new file mode 100644
index 00000000000..78c8d6067be
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/design.md
@@ -0,0 +1,47 @@
+## Context
+
+Command export validation models a replayable sequence as a path from an export root to later command targets and reference parameters.
+Known objects are built from command results that precede the command being validated.
+For the first command in the sequence, there are no prior results, so the only valid target is an export root domain service.
+
+The current validator already treats domain services as export roots and ordinary domain objects as non-roots.
+This change makes the first-command consequence explicit in validation and in the `ReplayableCommand` exportability indicator.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Reject export sequences whose first selected action command targets an ordinary domain object.
+- Continue accepting first selected action commands whose target is a domain service export root.
+- Ensure the row-level `exportable` indicator reports the same result for first commands.
+- Preserve existing behavior for later commands whose targets are established by earlier results.
+
+**Non-Goals:**
+
+- Do not change how export roots are identified.
+- Do not change YAML export generation.
+- Do not change command recording or replay-state transitions.
+
+## Decisions
+
+1. Use the existing known-target validator semantics.
+
+A first command has an empty known-participant set.
+Therefore it is exportable only when each target and reference participant is an export root.
+This avoids adding special-case export logic while making the expected first-command behavior explicit and tested.
+
+Alternative considered: add a dedicated first-command branch.
+That would be more direct, but it risks diverging from the existing known-target graph semantics.
+
+2. Test both action validation and exportability.
+
+The export action and the `ReplayableCommand` property are two user-facing paths into the same rule.
+Tests should cover both paths so the export button and table indicator remain aligned.
+
+Alternative considered: test only the lower-level validator.
+That would miss integration mistakes in how export-manager context and export roots are supplied.
+
+## Risks / Trade-offs
+
+- Existing manually selected exports that start from a domain object will be rejected → This is the intended constraint because replay cannot reach that object without an earlier finder or navigation result.
+- Domain-service detection depends on metamodel lookup → Existing export-root tests already cover this dependency, and this change will add first-command-specific coverage.
diff --git a/openspec/changes/require-export-first-command-domain-service/proposal.md b/openspec/changes/require-export-first-command-domain-service/proposal.md
new file mode 100644
index 00000000000..0a3254748f5
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/proposal.md
@@ -0,0 +1,24 @@
+## Why
+
+Command export sequences need a reachable starting point.
+The first exported action cannot rely on a prior result bookmark, so it should only be exportable when its target is an export root, meaning a domain service.
+
+## What Changes
+
+- Require the first selected/exportable command in a command export sequence to target a domain service export root.
+- Ensure a first command targeting an ordinary domain object is rejected for export even if that object can be resolved locally.
+- Ensure the `ReplayableCommand` exportability indicator reports `false` for a first command whose target is not a domain service.
+- No breaking changes to exported YAML format or command recording.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `command-export-known-targets`: Clarifies that the first command is valid only when its target is an export root domain service because no prior command results are known.
+- `replayable-command-exportability`: Ensures the per-command exportability indicator follows the same first-command domain-service rule.
+
+## Impact
+
+- Affects command export validation and replayable command exportability checks in `extensions/core/commandlog/applib`.
+- Adds tests for first-command validation and exportability behavior.
diff --git a/openspec/changes/require-export-first-command-domain-service/specs/command-export-known-targets/spec.md b/openspec/changes/require-export-first-command-domain-service/specs/command-export-known-targets/spec.md
new file mode 100644
index 00000000000..c6bb7968614
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/specs/command-export-known-targets/spec.md
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: First export command requires an export root target
+When command-log recording support is `ENABLED`, the first selected action command in an export sequence SHALL be valid only when its target is an export root.
+A first selected action command targeting an ordinary domain object MUST be rejected unless an earlier selected command in export order establishes that object as a known result.
+The validation message SHALL identify the first selected command and SHALL state that the target is unknown for command export.
+This rule MUST follow the baseline-bounded export ordering used by command export validation.
+
+#### Scenario: First selected command on domain service is accepted
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** the first selected action command targets a menu service annotated with `@DomainService`
+- **WHEN** the export manager validates the selected command sequence
+- **THEN** the system accepts the first command target as an export root
+
+#### Scenario: First selected command on ordinary domain object is rejected
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** the first selected action command targets bookmark `demoCustomer:1`
+- **AND** bookmark `demoCustomer:1` is not a menu service root
+- **AND** no earlier selected command in export order has result bookmark `demoCustomer:1`
+- **WHEN** the export manager validates the selected command sequence
+- **THEN** the system prevents the export from occurring
+- **AND** the validation message identifies the first selected command target `demoCustomer:1`
+
+#### Scenario: Earlier finder allows later domain object command
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** the first selected action command targets a menu service annotated with `@DomainService`
+- **AND** the first selected action command has result bookmark `demoCustomer:1`
+- **AND** a later selected action command targets bookmark `demoCustomer:1`
+- **WHEN** the export manager validates the selected command sequence
+- **THEN** the system accepts the later command target as known
diff --git a/openspec/changes/require-export-first-command-domain-service/specs/replayable-command-exportability/spec.md b/openspec/changes/require-export-first-command-domain-service/specs/replayable-command-exportability/spec.md
new file mode 100644
index 00000000000..beebe8c20f8
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/specs/replayable-command-exportability/spec.md
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: First command exportability follows export root rule
+When command-log recording support is `ENABLED`, a replayable command that is first in the export-manager command ordering SHALL report exportable `true` only when its target and reference participants are export roots.
+A first replayable action command targeting an ordinary domain object SHALL report exportable `false` when no prior command result establishes that object.
+A later replayable action command targeting an ordinary domain object SHALL report exportable `true` when an earlier command result establishes that object.
+
+#### Scenario: First replayable command on domain service is exportable
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** the first replayable action command targets a menu service annotated with `@DomainService`
+- **WHEN** the system computes exportability for that replayable command in the export manager commands collection
+- **THEN** the replayable command exportability property is `true`
+
+#### Scenario: First replayable command on ordinary domain object is not exportable
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** the first replayable action command targets bookmark `demoCustomer:1`
+- **AND** bookmark `demoCustomer:1` is not a menu service root
+- **WHEN** the system computes exportability for that replayable command in the export manager commands collection
+- **THEN** the replayable command exportability property is `false`
+
+#### Scenario: Later replayable command on earlier result is exportable
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an export manager baseline is set
+- **AND** an earlier replayable command has result bookmark `demoCustomer:1`
+- **AND** a later replayable action command targets bookmark `demoCustomer:1`
+- **WHEN** the system computes exportability for the later replayable command in the export manager commands collection
+- **THEN** the replayable command exportability property is `true`
diff --git a/openspec/changes/require-export-first-command-domain-service/tasks.md b/openspec/changes/require-export-first-command-domain-service/tasks.md
new file mode 100644
index 00000000000..29a4bb455e9
--- /dev/null
+++ b/openspec/changes/require-export-first-command-domain-service/tasks.md
@@ -0,0 +1,23 @@
+## 1. Validation Behavior
+
+- [ ] 1.1 Review current command export known-target validation to confirm first-command semantics are handled by an empty known-participant set.
+- [ ] 1.2 Adjust validation logic if the first selected command can currently be accepted with an ordinary domain-object target.
+- [ ] 1.3 Ensure disabled command-log recording support continues to bypass dotted-path known-target export validation.
+
+## 2. Exportability Indicator
+
+- [ ] 2.1 Review `ReplayableCommand#getExportable()` and `CommandExportManager#knownParticipantsAsOf(...)` for first-command behavior.
+- [ ] 2.2 Adjust exportability logic if the first replayable command can currently report `true` for an ordinary domain-object target.
+- [ ] 2.3 Ensure a first replayable command targeting a domain service reports `true` when recording support is enabled.
+
+## 3. Tests
+
+- [ ] 3.1 Add or update export action validation tests for a first selected command targeting a domain service.
+- [ ] 3.2 Add or update export action validation tests for a first selected command targeting an ordinary domain object.
+- [ ] 3.3 Add or update exportability indicator tests for first-command domain-service and ordinary-domain-object targets.
+- [ ] 3.4 Add regression coverage showing a later command is exportable when an earlier finder result establishes its target.
+
+## 4. Verification
+
+- [ ] 4.1 Run the focused commandlog applib command export tests.
+- [ ] 4.2 Run OpenSpec validation for `require-export-first-command-domain-service`.