(causeway) 14/39: CAUSEWAY-4012: adds proposal for selector parent parameter refinement

[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 a65ab885a8e10f6746180660415abfbe68a2e801
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Jun 5 11:28:48 2026 +0100

    CAUSEWAY-4012: adds proposal for selector parent parameter refinement
---
 .../.openspec.yaml                                 |  2 +
 .../refine-selector-parent-parameter/design.md     | 47 ++++++++++++++++++++++
 .../refine-selector-parent-parameter/proposal.md   | 26 ++++++++++++
 .../parented-collection-selector-actions/spec.md   | 36 +++++++++++++++++
 .../refine-selector-parent-parameter/tasks.md      | 19 +++++++++
 5 files changed, 130 insertions(+)

diff --git a/openspec/changes/refine-selector-parent-parameter/.openspec.yaml b/openspec/changes/refine-selector-parent-parameter/.openspec.yaml
new file mode 100644
index 00000000000..c53ef21aaaf
--- /dev/null
+++ b/openspec/changes/refine-selector-parent-parameter/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-05
diff --git a/openspec/changes/refine-selector-parent-parameter/design.md b/openspec/changes/refine-selector-parent-parameter/design.md
new file mode 100644
index 00000000000..cb7d409cf0e
--- /dev/null
+++ b/openspec/changes/refine-selector-parent-parameter/design.md
@@ -0,0 +1,47 @@
+## Context
+
+Synthetic parented collection selector actions use a mandatory first parameter typed as the collection owner.
+The action is associated with the collection and is intended to be invoked in the context of a parent object, so that first parameter should be populated from the action target and should not be editable.
+Handcrafted actions express equivalent parameter behavior through parameter default facets and disabled facets derived from `default...` and `disableParam...` support methods.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a default value for the synthetic selector action’s first parent parameter using the current action target.
+- Disable the first parent parameter so the user cannot change it in a prompt.
+- Use the existing `ActionParameterDefaultsFacet` and `DisabledFacet` contracts consumed by viewers and metamodel tooling.
+- Keep the parent parameter mandatory and typed as the collection owner.
+
+**Non-Goals:**
+
+- Do not disable scalar child filter parameters.
+- Do not change selector invocation semantics or filtering rules.
+- Do not change action identity, layout association, display name, or command publishing behavior.
+
+## Decisions
+
+### Default the parent parameter from the action target
+
+Install an `ActionParameterDefaultsFacet` on parameter zero that returns the action target from the `ParameterNegotiationModel`.
+This mirrors the effective behavior of a handcrafted default support method while keeping synthetic action construction annotation-free.
+Returning the target also aligns the prompt with invocation semantics, where the collection is read from the supplied parent object.
+
+Alternative considered: rely only on parent choices containing the current target.
+Choices make the target selectable, but they do not pre-populate the prompt and still allow the user to pick a different parent.
+
+### Disable only the parent parameter
+
+Install a `DisabledFacet` on parameter zero with a clear reason that the parent is fixed by the selector action target.
+This mirrors the effective behavior of a handcrafted `disableParam...` support method.
+Scalar child filter parameters remain editable so recordings can provide enough values to identify exactly one child.
+
+Alternative considered: omit the parent parameter entirely and always use the action target internally.
+That would simplify the prompt, but it would change the command DTO parameter shape already established for selector actions.
+
+## Risks / Trade-offs
+
+- Some tooling might have expected all parameters to be editable.
+  Mitigation: only parameter zero is disabled, and it represents contextual navigation rather than user-supplied selection criteria.
+- Defaulting from the action target depends on the target being available in the parameter negotiation model.
+  Mitigation: selector actions are associated with and invoked against the parent object, and tests should verify the default uses that target.
diff --git a/openspec/changes/refine-selector-parent-parameter/proposal.md b/openspec/changes/refine-selector-parent-parameter/proposal.md
new file mode 100644
index 00000000000..ee8a2e0c7e3
--- /dev/null
+++ b/openspec/changes/refine-selector-parent-parameter/proposal.md
@@ -0,0 +1,26 @@
+## Why
+
+The synthetic selector action’s first parameter represents the collection owner and should be fixed to the current action target.
+If a user or recorder can change that parameter, the action no longer behaves like contextual navigation from the displayed parent collection.
+
+## What Changes
+
+- Ensure the first synthetic selector action parameter defaults to the current action target.
+- Disable the first synthetic selector action parameter using the same facet contract as a handcrafted `disableParam...` support method.
+- Preserve the existing mandatory parent parameter type, selector action id, layout association, display name, scalar filter parameters, and invocation behavior.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `parented-collection-selector-actions`: The mandatory parent parameter gains a target default and is disabled so it cannot be changed by the user.
+
+## Impact
+
+- Affects synthetic selector action parameter facet installation in `core/metamodel`.
+- Adds or updates metamodel tests for parent parameter defaults and disabled usability.
+- Does not change command logging, export, replay, action ids, layout metadata, or selector filtering semantics.
diff --git a/openspec/changes/refine-selector-parent-parameter/specs/parented-collection-selector-actions/spec.md b/openspec/changes/refine-selector-parent-parameter/specs/parented-collection-selector-actions/spec.md
new file mode 100644
index 00000000000..f7558fb116c
--- /dev/null
+++ b/openspec/changes/refine-selector-parent-parameter/specs/parented-collection-selector-actions/spec.md
@@ -0,0 +1,36 @@
+## MODIFIED Requirements
+
+### Requirement: Selector actions expose parent and scalar child parameters
+The synthetic selector action SHALL define one mandatory parent object parameter.
+The parent parameter SHALL be typed as the collection owner type.
+The parent parameter SHALL default to the current action target.
+The parent parameter SHALL be disabled so it cannot be changed by the user.
+The synthetic selector action SHALL define optional parameters for eligible scalar properties of the collection element type.
+The synthetic selector action MUST NOT automatically create selector parameters for child collections or reference properties.
+
+#### Scenario: Parent parameter is mandatory
+- **GIVEN** an entity type `Lease` has a parented collection `items`
+- **WHEN** the framework synthesizes the selector action for `items`
+- **THEN** the action has a mandatory parameter typed as `Lease`
+
+#### Scenario: Parent parameter defaults to action target
+- **GIVEN** an entity type `Lease` has a parented collection `items`
+- **AND** synthetic parented collection selector action creation is enabled
+- **WHEN** the framework evaluates defaults for the selector action on a `Lease` target
+- **THEN** the parent parameter default is that `Lease` target
+
+#### Scenario: Parent parameter is disabled
+- **GIVEN** an entity type `Lease` has a parented collection `items`
+- **AND** synthetic parented collection selector action creation is enabled
+- **WHEN** the framework evaluates parameter usability for the selector action
+- **THEN** the parent parameter is disabled
+
+#### Scenario: Scalar child properties become optional filters
+- **GIVEN** `LeaseItem` has scalar properties suitable for equality matching
+- **WHEN** the framework synthesizes the selector action for `Lease.items`
+- **THEN** the action has optional parameters corresponding to those scalar properties
+
+#### Scenario: Non-scalar child members are excluded from automatic filters
+- **GIVEN** `LeaseItem` has a child collection and a reference property
+- **WHEN** the framework synthesizes the selector action for `Lease.items`
+- **THEN** the action does not create automatic parameters for the child collection or reference property
diff --git a/openspec/changes/refine-selector-parent-parameter/tasks.md b/openspec/changes/refine-selector-parent-parameter/tasks.md
new file mode 100644
index 00000000000..d6c7614c5d8
--- /dev/null
+++ b/openspec/changes/refine-selector-parent-parameter/tasks.md
@@ -0,0 +1,19 @@
+## 1. Parent Parameter Defaults
+
+- [ ] 1.1 Identify the existing parameter default facet contract used by action parameter defaults.
+- [ ] 1.2 Add a synthetic default facet for selector parent parameters that returns the current action target.
+- [ ] 1.3 Install the parent default facet on parameter zero of synthetic selector actions.
+
+## 2. Parent Parameter Disabled State
+
+- [ ] 2.1 Identify the existing disabled facet contract used by disabled action parameters.
+- [ ] 2.2 Add a synthetic disabled facet for selector parent parameters with a clear fixed-parent reason.
+- [ ] 2.3 Install the disabled facet on parameter zero only, leaving scalar filter parameters editable.
+
+## 3. Tests and Validation
+
+- [ ] 3.1 Add or update metamodel tests proving the parent parameter has a default.
+- [ ] 3.2 Add or update metamodel tests proving the parent parameter default is the current action target.
+- [ ] 3.3 Add or update metamodel tests proving the parent parameter is disabled and scalar filter parameters are not disabled by this feature.
+- [ ] 3.4 Run focused metamodel tests for the synthetic selector action factory.
+- [ ] 3.5 Run `openspec validate refine-selector-parent-parameter --strict` and fix any proposal/spec/task validation issues.