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/06 08:21:23 UTC
(causeway) 31/39: CAUSEWAY-4012: adds selector prefix rename proposal
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 5000754bf4a526223bd6f7d856f87ad7a06795dd
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Jun 6 06:19:33 2026 +0100
CAUSEWAY-4012: adds selector prefix rename proposal
---
.../.openspec.yaml | 2 +
.../design.md | 43 ++++++++++++++++++
.../proposal.md | 24 ++++++++++
.../parented-collection-selector-actions/spec.md | 51 ++++++++++++++++++++++
.../rename-selector-prefix-to-select-from/tasks.md | 14 ++++++
5 files changed, 134 insertions(+)
diff --git a/openspec/changes/rename-selector-prefix-to-select-from/.openspec.yaml b/openspec/changes/rename-selector-prefix-to-select-from/.openspec.yaml
new file mode 100644
index 00000000000..b4c82a0a957
--- /dev/null
+++ b/openspec/changes/rename-selector-prefix-to-select-from/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-06
diff --git a/openspec/changes/rename-selector-prefix-to-select-from/design.md b/openspec/changes/rename-selector-prefix-to-select-from/design.md
new file mode 100644
index 00000000000..b13baf41c58
--- /dev/null
+++ b/openspec/changes/rename-selector-prefix-to-select-from/design.md
@@ -0,0 +1,43 @@
+## Context
+
+Synthetic parented collection selector actions are framework-generated safe actions that support command recording for parent-to-child collection navigation.
+The current implementation uses a single reserved action id prefix constant in `ObjectSpecificationAbstract` and appends the parented collection id to produce deterministic action ids.
+The requested change is intentionally small, but it changes a framework-visible identifier that can appear in command export, replay, and tests.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Rename the reserved selector action id prefix to `__causeway_select_from_`.
+- Preserve deterministic action ids by keeping the collection id suffix unchanged.
+- Keep the user-facing action name `Select` unchanged.
+- Keep selector action synthesis, parameter behavior, invocation behavior, and command publishing behavior unchanged.
+- Update tests and OpenSpec requirements so the new reserved id is covered explicitly.
+
+**Non-Goals:**
+
+- Do not add compatibility aliases for the old `__causeway_select_` prefix.
+- Do not change command DTO shape beyond the synthetic action id value.
+- Do not rename the synthetic action display name.
+- Do not revisit selector eligibility, parameter filtering, or ordering rules.
+
+## Decisions
+
+- Replace the prefix constant in the selector synthesis utility rather than deriving the new id at call sites.
+ This keeps all generated selector action ids consistent and avoids duplicated string construction.
+ The alternative was to post-process ids in export or replay, but that would leave the metamodel with the less readable id and create split behavior.
+- Treat the prefix rename as a breaking identifier change.
+ Existing stored command recordings that reference `__causeway_select_...` will not match the renamed synthetic action without data migration or regeneration.
+ The alternative was to support both prefixes, but compatibility aliases would weaken the deterministic one-action-per-collection model and add unnecessary complexity for a readability improvement.
+- Keep the suffix as the associated collection id.
+ This preserves the existing deterministic mapping from a parented collection to its selector action.
+ The alternative was to include parent type or other metadata, but that is outside the requested rename and would broaden the compatibility impact.
+
+## Risks / Trade-offs
+
+- [Risk] Existing command recordings or tests may reference the old id prefix.
+ Mitigation: document the rename as breaking in the proposal and update repository tests that assert the generated id.
+- [Risk] The new prefix may require updates in downstream replay fixtures or exported examples.
+ Mitigation: search for the old prefix across source, tests, and OpenSpec artifacts during implementation.
+- [Risk] A partial update could leave code and specs describing different prefixes.
+ Mitigation: validate the OpenSpec change and run selector action tests after implementation.
diff --git a/openspec/changes/rename-selector-prefix-to-select-from/proposal.md b/openspec/changes/rename-selector-prefix-to-select-from/proposal.md
new file mode 100644
index 00000000000..38d4d744f16
--- /dev/null
+++ b/openspec/changes/rename-selector-prefix-to-select-from/proposal.md
@@ -0,0 +1,24 @@
+## Why
+
+Synthetic parented collection selector action ids currently use the reserved prefix `__causeway_select_`.
+Renaming the prefix to `__causeway_select_from_` makes the generated ids read more clearly as actions that select from a specific collection while retaining deterministic framework-owned ids.
+
+## What Changes
+
+- Change the reserved synthetic parented collection selector action id prefix from `__causeway_select_` to `__causeway_select_from_`.
+- Preserve deterministic action id generation by continuing to append the associated collection id after the prefix.
+- Update tests and OpenSpec requirements that describe the reserved selector action id format.
+- **BREAKING**: Existing recordings, integrations, or assertions that reference the old synthetic action id prefix will need to use the new prefix.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `parented-collection-selector-actions`: the deterministic selector action identifier requirement changes to use the reserved `__causeway_select_from_` prefix.
+
+## Impact
+
+- Affected code is expected around synthetic selector action creation in `ObjectSpecificationAbstract`.
+- Affected tests are expected around parented collection selector action id generation and metadata assertions.
+- Exported command or replay data that stores synthetic selector action ids may need corresponding updates because the reserved id string changes.
diff --git a/openspec/changes/rename-selector-prefix-to-select-from/specs/parented-collection-selector-actions/spec.md b/openspec/changes/rename-selector-prefix-to-select-from/specs/parented-collection-selector-actions/spec.md
new file mode 100644
index 00000000000..983f22eca78
--- /dev/null
+++ b/openspec/changes/rename-selector-prefix-to-select-from/specs/parented-collection-selector-actions/spec.md
@@ -0,0 +1,51 @@
+## MODIFIED Requirements
+
+### Requirement: Framework synthesizes selector actions for parented collections
+The system SHALL provide the `causeway.extensions.command-log.recording-support` configuration property that controls command-log recording support behavior.
+The `recording-support` property SHALL be an enum with values `ENABLED` and `DISABLED`.
+The system SHALL default `recording-support` to `DISABLED`.
+When `recording-support` is `ENABLED`, the system SHALL synthesize a safe metamodel `ObjectAction` for each eligible parented collection association.
+When `recording-support` is `DISABLED`, the system MUST NOT synthesize parented collection selector actions.
+The system MUST NOT require or use a separate `causeway.extensions.command-log.parented-collection-selector-actions-enabled` boolean property to enable synthetic parented collection selector action creation.
+The synthetic action SHALL represent navigation from the collection owner to one selected collection element.
+The synthetic action SHALL have a deterministic identifier that does not collide with developer-authored actions.
+The synthetic action identifier SHALL use the reserved prefix `__causeway_select_from_` followed by the associated parented collection id.
+The synthetic action SHALL be distinguishable from developer-authored actions by framework metadata.
+The synthetic action SHALL be associated with the parented collection through layout metadata equivalent to `@ActionLayout(associateWith=...)`.
+The synthetic action SHALL have the display name `Select` through name metadata equivalent to `@ActionLayout(named="Select")`.
+
+#### Scenario: Synthetic action is not available by default
+- **GIVEN** an entity type has a parented collection of child entities
+- **AND** command-log recording support is not configured
+- **WHEN** the framework fully introspects the entity type
+- **THEN** the metamodel does not include a synthetic selector action for that collection
+
+#### Scenario: Synthetic action is available when recording support is enabled for a parented collection
+- **GIVEN** an entity type has a parented collection of child entities
+- **AND** command-log recording support is `ENABLED`
+- **WHEN** the framework fully introspects the entity type
+- **THEN** the metamodel includes a synthetic safe action for selecting one element from that collection
+- **AND** the synthetic action is associated with the collection owner type
+
+#### Scenario: Synthetic action id is deterministic
+- **GIVEN** the framework introspects the same parented collection in two application runs
+- **WHEN** the synthetic selector action is created in each run
+- **THEN** both actions have the same action identifier
+- **AND** the identifier uses the reserved prefix `__causeway_select_from_`
+- **AND** the identifier is reserved so it does not conflict with application action ids
+
+#### Scenario: Ordinary action lists can identify synthetic actions
+- **WHEN** a viewer or metamodel exporter enumerates actions for a type
+- **THEN** it can determine whether a listed action is a synthetic parented collection selector action
+
+#### Scenario: Synthetic action is associated with its parented collection
+- **GIVEN** an entity type `Lease` has a parented collection `items`
+- **AND** command-log recording support is `ENABLED`
+- **WHEN** the framework synthesizes the selector action for `items`
+- **THEN** the action has layout association metadata for collection id `items`
+
+#### Scenario: Synthetic action display name is Select
+- **GIVEN** an entity type `Lease` has a parented collection `items`
+- **AND** command-log recording support is `ENABLED`
+- **WHEN** the framework synthesizes the selector action for `items`
+- **THEN** the action display name is `Select`
diff --git a/openspec/changes/rename-selector-prefix-to-select-from/tasks.md b/openspec/changes/rename-selector-prefix-to-select-from/tasks.md
new file mode 100644
index 00000000000..1b32d532fa8
--- /dev/null
+++ b/openspec/changes/rename-selector-prefix-to-select-from/tasks.md
@@ -0,0 +1,14 @@
+## 1. Implementation
+
+- [ ] 1.1 Update the synthetic parented collection selector action id prefix constant from `__causeway_select_` to `__causeway_select_from_`.
+- [ ] 1.2 Verify selector action id construction still appends the associated parented collection id without changing display name, layout association, parameters, or invocation behavior.
+
+## 2. Tests and Documentation
+
+- [ ] 2.1 Update selector action unit tests and any fixtures that assert the old `__causeway_select_` prefix.
+- [ ] 2.2 Search source, tests, and OpenSpec artifacts for remaining references to the old prefix and update only the references that describe current behavior.
+
+## 3. Validation
+
+- [ ] 3.1 Run the focused selector action test suite for `ParentedCollectionSelectorActionUtilTest`.
+- [ ] 3.2 Run `openspec validate rename-selector-prefix-to-select-from --strict`.