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/08/04 18:47:34 UTC
(causeway) 03/22: CAUSEWAY-3910: plan command recording core policy reconciliation
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 1b7f593e9eff8c2a4d95bf631da6eab84f706da2
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Aug 4 10:28:55 2026 +0100
CAUSEWAY-3910: plan command recording core policy reconciliation
---
.../.openspec.yaml | 2 +
.../design.md | 126 ++++++++++++++++++
.../proposal.md | 33 +++++
.../specs/command-recording-control/spec.md | 146 +++++++++++++++++++++
.../tasks.md | 29 ++++
5 files changed, 336 insertions(+)
diff --git a/openspec/changes/reconcile-command-recording-core-policy/.openspec.yaml b/openspec/changes/reconcile-command-recording-core-policy/.openspec.yaml
new file mode 100644
index 00000000000..1b062d3a7c7
--- /dev/null
+++ b/openspec/changes/reconcile-command-recording-core-policy/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-04
diff --git a/openspec/changes/reconcile-command-recording-core-policy/design.md b/openspec/changes/reconcile-command-recording-core-policy/design.md
new file mode 100644
index 00000000000..0b583380771
--- /dev/null
+++ b/openspec/changes/reconcile-command-recording-core-policy/design.md
@@ -0,0 +1,126 @@
+## Context
+
+The maintenance branch introduced command recording as an opt-in mode that later enables safe-action, property-edit, and synthetic-navigation commands to participate in the normal command publishing pipeline.
+Causeway 4 currently has command publishing and commandlog persistence, but it has no recording-support switch, no target-level suppression contract, and no scoped mechanism to pause commandlog persistence.
+
+This change implements dependency-graph node C1 from `openspec/reconciliation/maintenance-branch/dependency-graph.md`.
+It deliberately establishes control contracts before any later change broadens command publishing eligibility.
+
+The maintenance implementation uses mutable configuration classes, `javax` APIs, and the Causeway 2 member-execution structure.
+The Causeway 4 implementation must use immutable configuration records, Jakarta APIs, the current event bus, and the current `InteractionCarrier`-based member executor.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Introduce the disabled-by-default recording-support configuration contract.
+- Provide a core applib marker that prevents marked helper interactions from becoming recorded commands.
+- Provide extension-independent pause and resume event contracts.
+- Maintain nested, application-wide commandlog pause state.
+- Make all commandlog subscriber lifecycle callbacks honour pause state.
+- Suppress initial fixture-script command persistence with guaranteed resume behaviour.
+- Mark the commandlog helper types currently present on `main` as recording-suppressed.
+- Preserve ordinary member execution when command recording is suppressed.
+
+**Non-Goals:**
+
+- Enable command publishing for safe actions.
+- Enable command publishing for property edits that are not currently publishable.
+- Generate selector or navigation actions.
+- Capture new result shapes or export result metadata.
+- Add replay mapping.
+- Replace `CommandExportManager` and `CommandReplayManager` with the maintenance `CommandManager`.
+- Add recording or replay background-completion guards.
+
+## Decisions
+
+### Keep recording support under commandlog extension configuration
+
+Add `RecordingSupport recordingSupport` to the Causeway 4 `CausewayConfiguration.Extensions.CommandLog` record with `@DefaultValue("DISABLED")`.
+The enum has `ENABLED` and `DISABLED` values and an `isEnabled()` convenience method.
+
+This preserves the maintenance external property `causeway.extensions.command-log.recording-support` and avoids introducing a second safe-action-specific property.
+Although later behaviour affects core metamodel construction, the feature remains an opt-in commandlog capability.
+
+An alternative was to place the switch under `causeway.core.runtime-services` because member execution consumes it.
+That would break maintenance configuration compatibility and incorrectly present recording support as a core feature independent of commandlog.
+
+### Keep public control contracts in core applib
+
+Add `CommandRecordingSuppressed`, `PauseCommandLoggingEvent`, and `ResumeCommandLoggingEvent` under `org.apache.causeway.applib.services.command`.
+The events use the current Causeway applib event base and carry their publisher as the source.
+
+This allows domain types and fixture infrastructure to use the contracts without depending on the commandlog extension.
+The commandlog extension remains responsible for interpreting pause and resume events.
+
+An alternative was to define the contracts in commandlog applib.
+That would create an undesirable reverse dependency from testing fixtures and application domain types to an optional persistence extension.
+
+### Suppress command preparation at the normal execution seam
+
+The current `MemberExecutorServiceDefault.prepareCommandForPublishing(...)` seam will check both the interaction owner and target for `CommandRecordingSuppressed` before advancing the command to the publishing-ready phase.
+The invocation itself continues normally.
+
+Checking both owner and target preserves maintenance semantics for contributed and mixin members where those objects can differ.
+Placing the check in normal command preparation ensures future recording-aware facets cannot bypass suppression.
+
+An alternative was to suppress only in `CommandSubscriberForCommandLog`.
+That would allow other command subscribers to observe and act on a command that recording policy declared suppressed, and it would duplicate target-resolution logic outside member execution.
+
+### Use application-wide nested pause depth
+
+The commandlog extension will hold pause state in a singleton service backed by an `AtomicInteger`.
+A Spring application-event listener increments the depth for each pause event and decrements it for each resume event.
+An unmatched resume clamps the depth to zero.
+The commandlog is paused whenever the depth is greater than zero.
+
+This follows the authoritative maintenance behaviour and treats pause as a commandlog-persistence state for the application context rather than a thread-local or interaction-local state.
+Atomic state allows events and command notifications to arrive on different threads without corrupting the nesting count.
+
+An alternative was a thread-local pause scope.
+That would fail when event publication and command persistence occur on different threads and would not match maintenance semantics.
+
+### Check pause state at every subscriber lifecycle phase
+
+`CommandSubscriberForCommandLog` will return without creating or synchronizing an entry when persistence is disabled or pause state is active.
+The check applies independently to ready, started, and completed notifications.
+
+This prevents a command created before a pause from being synchronized while paused and prevents a command first observed while paused from being created by a later phase.
+
+### Pause initial fixture installation with try/finally
+
+`InitialFixtureScriptsInstaller` will publish a pause event immediately before running the configured initial fixture script and publish the matching resume event from a `finally` block.
+The installer depends only on core applib event contracts and `EventBusService`.
+Fixture domain logic and exception propagation remain unchanged.
+
+An alternative was to make the installer detect the commandlog extension directly.
+That would couple testing fixtures to an optional extension and is therefore rejected.
+
+### Mark current helper types without anticipating future classes
+
+The existing `CommandExportManager`, `CommandReplayManager`, `ReplayableCommand`, and commandlog entry view/entity abstractions on `main` will implement the suppression marker where their public type hierarchy permits it.
+Future `CommandManager` and `ReplayableCommandParticipant` types will implement the same marker when their respective reconciliation changes introduce them.
+
+This prevents the first change from introducing placeholder types or prematurely redesigning the manager model.
+
+## Risks / Trade-offs
+
+- [Risk] Application-wide pause affects unrelated concurrent command interactions while a pause scope is active. → Mitigation: preserve maintenance semantics, keep pause scopes short, and guarantee fixture resume with `finally`.
+- [Risk] A missing resume event can leave persistence paused. → Mitigation: document paired events, support nesting explicitly, and use `try/finally` in framework-owned scopes.
+- [Risk] An unmatched resume may hide an event-pairing defect. → Mitigation: clamp at zero to preserve availability and cover the behaviour with unit tests; diagnostic logging can be considered during implementation.
+- [Risk] Record-based configuration constructor changes can affect configuration tests and direct constructors. → Mitigation: use `@DefaultValue`, update focused construction tests, and retain the existing external property hierarchy.
+- [Risk] Suppression in the core publishing seam affects every command subscriber, not only commandlog. → Mitigation: this matches the maintenance execution seam and is limited to types that deliberately implement the marker.
+- [Risk] Existing and maintenance helper class names differ because the manager redesign has not yet been reconciled. → Mitigation: mark only current helper types now and record future marker adoption in downstream designs.
+
+## Migration Plan
+
+The configuration defaults to `DISABLED`, so applications that do not opt in retain existing recording eligibility.
+The new events and marker are additive public contracts.
+Commandlog helper interactions become suppressed once those helper types implement the marker.
+Rollback consists of removing the configuration component, event listener and pause state, fixture event publication, marker checks, and helper marker declarations.
+No persistent schema migration is required.
+
+## Open Questions
+
+No blocking design questions remain for C1.
+The exact diagnostic policy for unmatched resume events can be decided during implementation without changing the specified behaviour.
diff --git a/openspec/changes/reconcile-command-recording-core-policy/proposal.md b/openspec/changes/reconcile-command-recording-core-policy/proposal.md
new file mode 100644
index 00000000000..09005da3c46
--- /dev/null
+++ b/openspec/changes/reconcile-command-recording-core-policy/proposal.md
@@ -0,0 +1,33 @@
+## Why
+
+Causeway 4 lacks the maintenance-branch control contracts needed to enable command recording safely without recursively recording commandlog helper interactions or startup fixture activity.
+This change establishes dependency-graph node C1 as the foundation for later safe-action, property-edit, synthetic-navigation, and replay work.
+
+## What Changes
+
+- Add an opt-in `causeway.extensions.command-log.recording-support` configuration property with `ENABLED` and `DISABLED` values and a default of `DISABLED`.
+- Add a core applib marker that allows domain objects and view models to suppress recording-support command logging while preserving normal invocation behaviour.
+- Ensure the normal execution and commandlog subscriber flow honours the suppression marker without creating a parallel logging mechanism.
+- Add core applib pause and resume application events for temporarily suspending commandlog persistence.
+- Make commandlog persistence pause-aware for ready, started, and completed command notifications, including nested pause scopes.
+- Suppress commandlog persistence while an initial fixture script is installed and always resume it when the fixture scope exits.
+- Mark the existing commandlog export, replay, entry, and replayable-command helper types that are present on `main` as recording-suppressed.
+- Preserve existing Causeway 4 command-publishing behaviour while recording support is disabled.
+- Defer safe-action publishing, property-edit publishing, synthetic actions, result metadata, replay mapping, and command-manager redesign to later reconciliation changes.
+
+## Capabilities
+
+### New Capabilities
+
+- `command-recording-control`: Defines opt-in recording-support configuration, target-level recording suppression, nested commandlog persistence pause/resume, and startup fixture suppression.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change affects public contracts in `api/applib`, immutable configuration records in `core/config`, command execution or publishing coordination in `core/runtimeservices`, initial fixture installation, and the commandlog extension subscriber and helper view models.
+The new applib contracts must remain independent of the commandlog extension so applications and fixture infrastructure do not acquire a reverse dependency on commandlog.
+The configuration and implementation must use the current Causeway 4 record-based configuration, Jakarta, and Spring Boot 4 architecture rather than copying the mutable Causeway 2 implementation.
+The programme context and downstream dependencies are recorded in `openspec/reconciliation/maintenance-branch/`.
diff --git a/openspec/changes/reconcile-command-recording-core-policy/specs/command-recording-control/spec.md b/openspec/changes/reconcile-command-recording-core-policy/specs/command-recording-control/spec.md
new file mode 100644
index 00000000000..cd5bba6c73f
--- /dev/null
+++ b/openspec/changes/reconcile-command-recording-core-policy/specs/command-recording-control/spec.md
@@ -0,0 +1,146 @@
+## ADDED Requirements
+
+### Requirement: Command recording support is opt-in
+The system SHALL provide the `causeway.extensions.command-log.recording-support` configuration property.
+The property SHALL accept `ENABLED` and `DISABLED` values.
+The property SHALL default to `DISABLED`.
+When recording support is `DISABLED`, the system MUST preserve existing command-publishing eligibility and MUST NOT broaden command logging solely because recording support exists.
+
+#### Scenario: Recording support is disabled by default
+- **WHEN** an application does not configure command-log recording support
+- **THEN** recording support is `DISABLED`
+- **AND** existing command-publishing eligibility is unchanged
+
+#### Scenario: Application enables recording support
+- **WHEN** an application configures `causeway.extensions.command-log.recording-support=ENABLED`
+- **THEN** the configuration model reports recording support as enabled
+- **AND** later recording-aware policies can use that state without a separate safe-action-specific configuration property
+
+### Requirement: Marked targets are ignored by command recording support
+The system SHALL provide a core applib marker interface that domain objects and view models can implement to opt out of command recording support.
+When an action owner or target implements the marker interface, the system MUST NOT prepare that member interaction for command persistence through recording support.
+When a property owner or target implements the marker interface, the system MUST NOT prepare that property edit for command persistence through recording support.
+The system SHALL continue to execute the member invocation normally when its owner or target implements the marker interface.
+The marker interface MUST NOT suppress command recording for unmarked owners and targets.
+
+#### Scenario: Marked action target is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an action target implements the command recording suppression marker interface
+- **WHEN** a user invokes an action on that target
+- **THEN** the system executes the action normally
+- **AND** the system does not persist a command log entry for that invocation through recording support
+
+#### Scenario: Marked property target is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** a property target implements the command recording suppression marker interface
+- **WHEN** a user edits the property
+- **THEN** the system executes the property edit normally
+- **AND** the system does not persist a command log entry for that edit through recording support
+
+#### Scenario: Marked member owner is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** a contributed or mixin member owner implements the command recording suppression marker interface
+- **WHEN** a user invokes the contributed or mixin member
+- **THEN** the system executes the member normally
+- **AND** the system does not persist a command log entry for that invocation through recording support
+
+#### Scenario: Unmarked target remains eligible
+- **GIVEN** command-log recording support is `ENABLED`
+- **AND** an interaction owner and target do not implement the command recording suppression marker interface
+- **WHEN** the interaction is otherwise eligible for command publishing
+- **THEN** the marker policy does not prevent normal command publication
+
+### Requirement: Commandlog helper objects suppress recording
+The existing command export manager SHALL implement the command recording suppression marker interface.
+The existing command replay manager SHALL implement the command recording suppression marker interface.
+The replayable command view model SHALL implement the command recording suppression marker interface.
+Command log entry view and entity types SHALL implement the command recording suppression marker interface where their shared type hierarchy permits it.
+Interactions with marked commandlog helper objects MUST NOT be persisted as replayable user commands through recording support.
+
+#### Scenario: Export manager interaction is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **WHEN** a user invokes an action on the command export manager
+- **THEN** the system does not persist that helper interaction through recording support
+
+#### Scenario: Replay manager interaction is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **WHEN** a user invokes an action on the command replay manager
+- **THEN** the system does not persist that helper interaction through recording support
+
+#### Scenario: Replayable command interaction is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **WHEN** a user invokes an action on a replayable command view model
+- **THEN** the system does not persist that helper interaction through recording support
+
+#### Scenario: Command log entry interaction is not recorded
+- **GIVEN** command-log recording support is `ENABLED`
+- **WHEN** a user invokes an action on a marked command log entry object
+- **THEN** the system does not persist that helper interaction through recording support
+
+### Requirement: Command log persistence can be paused and resumed
+The system SHALL provide `PauseCommandLoggingEvent` in core applib as an application-event contract for pausing command log persistence.
+The system SHALL provide `ResumeCommandLoggingEvent` in core applib as an application-event contract for resuming command log persistence.
+Command logging implementations SHALL consume these events without requiring event publishers to depend on a command logging implementation module.
+While command log persistence is paused, the commandlog subscriber MUST NOT create command log entries for ready notifications.
+While command log persistence is paused, the commandlog subscriber MUST NOT synchronize command log entries for started or completed notifications.
+After command log persistence is resumed, subsequent eligible commands MUST remain persistable through the normal commandlog subscriber flow.
+Nested pause scopes MUST NOT resume command log persistence until each active pause has received a matching resume.
+An unmatched resume MUST NOT make pause depth negative or disable subsequent command logging.
+
+#### Scenario: Paused logging skips command entry creation
+- **GIVEN** commandlog persistence is enabled
+- **AND** commandlog persistence has been paused by a `PauseCommandLoggingEvent`
+- **WHEN** a command reaches the ready notification
+- **THEN** the subscriber does not create a command log entry for that command
+
+#### Scenario: Paused logging skips command entry synchronization
+- **GIVEN** commandlog persistence is enabled
+- **AND** commandlog persistence has been paused by a `PauseCommandLoggingEvent`
+- **WHEN** a command reaches the started or completed notification
+- **THEN** the subscriber does not synchronize a command log entry for that notification
+
+#### Scenario: Resumed logging restores normal persistence
+- **GIVEN** commandlog persistence is enabled
+- **AND** commandlog persistence was paused and then resumed
+- **WHEN** a subsequent eligible command reaches the ready notification
+- **THEN** the subscriber can create a command log entry through the normal flow
+
+#### Scenario: Nested pause requires matching resumes
+- **GIVEN** commandlog persistence is enabled
+- **AND** commandlog persistence has been paused twice
+- **WHEN** commandlog persistence is resumed once
+- **THEN** commandlog persistence remains paused
+- **WHEN** commandlog persistence is resumed a second time
+- **THEN** subsequent eligible commands can be persisted through the normal flow
+
+#### Scenario: Unmatched resume is harmless
+- **GIVEN** commandlog persistence is not paused
+- **WHEN** a `ResumeCommandLoggingEvent` is published
+- **THEN** commandlog persistence remains unpaused
+- **AND** subsequent eligible commands can be persisted through the normal flow
+
+### Requirement: Initial fixture script commands are not persisted
+The system SHALL publish `PauseCommandLoggingEvent` immediately before installing a configured initial fixture script during application startup.
+The system MUST publish the matching `ResumeCommandLoggingEvent` after initial fixture installation completes.
+The system MUST publish the matching resume event if initial fixture installation fails.
+The pause MUST apply only to commandlog persistence and MUST NOT prevent the fixture script from executing its domain logic normally.
+The initial fixture installation path MUST NOT depend on the commandlog extension.
+
+#### Scenario: Initial fixture commands are suppressed
+- **GIVEN** commandlog persistence is enabled
+- **AND** an application has a configured initial fixture script
+- **WHEN** the framework installs the initial fixture script
+- **THEN** commands produced by the fixture script are not persisted as command log entries
+- **AND** the fixture script domain logic executes normally
+
+#### Scenario: Logging resumes after successful fixture installation
+- **GIVEN** commandlog persistence is enabled
+- **AND** initial fixture installation completes successfully
+- **WHEN** a subsequent eligible command is published
+- **THEN** the command can be persisted through the normal commandlog subscriber flow
+
+#### Scenario: Logging resumes after failed fixture installation
+- **GIVEN** commandlog persistence is enabled
+- **AND** initial fixture installation fails
+- **WHEN** the fixture installation scope exits
+- **THEN** commandlog persistence is no longer paused by that fixture installation scope
diff --git a/openspec/changes/reconcile-command-recording-core-policy/tasks.md b/openspec/changes/reconcile-command-recording-core-policy/tasks.md
new file mode 100644
index 00000000000..b7bbcf3c9a8
--- /dev/null
+++ b/openspec/changes/reconcile-command-recording-core-policy/tasks.md
@@ -0,0 +1,29 @@
+## 1. Public contracts and configuration
+
+- [ ] 1.1 Add the Causeway 4 record-based `causeway.extensions.command-log.recording-support` configuration with `ENABLED` and `DISABLED` values, a disabled default, configuration documentation, and focused configuration tests.
+- [ ] 1.2 Add the core applib `CommandRecordingSuppressed`, `PauseCommandLoggingEvent`, and `ResumeCommandLoggingEvent` public contracts with API documentation and focused contract tests where applicable.
+
+## 2. Member execution suppression
+
+- [ ] 2.1 Adapt `MemberExecutorServiceDefault` so marked interaction owners or targets bypass command preparation while member execution continues normally.
+- [ ] 2.2 Add runtime-service tests covering marked owner, marked target, unmarked target, and unaffected member invocation behaviour.
+
+## 3. Commandlog pause state
+
+- [ ] 3.1 Add the application-wide atomic pause-depth service and application-event listener, with unit tests for nesting and unmatched resume events.
+- [ ] 3.2 Make commandlog ready, started, and completed subscriber callbacks honour pause state, with focused subscriber or integration tests for creation and synchronization suppression.
+
+## 4. Framework-owned pause scope
+
+- [ ] 4.1 Publish paired pause and resume events around initial fixture-script installation using `try/finally` and without adding a commandlog extension dependency.
+- [ ] 4.2 Add fixture-installer tests covering successful execution, failed execution, event ordering, and guaranteed resume publication.
+
+## 5. Commandlog helper suppression
+
+- [ ] 5.1 Mark the existing export manager, replay manager, replayable command, and applicable command log entry abstractions as recording-suppressed.
+- [ ] 5.2 Add or adapt commandlog tests proving helper actions are not persisted through recording support while ordinary eligible interactions remain unaffected.
+
+## 6. Verification
+
+- [ ] 6.1 Run the focused applib, configuration, runtime-services, testing-fixtures, and commandlog test suites and resolve regressions caused by the new contracts.
+- [ ] 6.2 Verify the external configuration property, Jakarta imports, public API documentation, and module dependency direction against the specification and programme ledger.