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/07 19:36:17 UTC
(causeway) 01/10: CAUSEWAY-4015: proposes suppressing initial fixture command logging
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch CAUSEWAY-4019
in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 01f5d875c2fc7bc7a2022cf62c418206f7168fdf
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 7 16:36:01 2026 +0100
CAUSEWAY-4015: proposes suppressing initial fixture command logging
---
.../.openspec.yaml | 2 +
.../design.md | 71 ++++++++++++++++++++++
.../proposal.md | 28 +++++++++
.../specs/command-recording-suppression/spec.md | 60 ++++++++++++++++++
.../tasks.md | 27 ++++++++
5 files changed, 188 insertions(+)
diff --git a/openspec/changes/suppress-fixture-initial-script-command-logging/.openspec.yaml b/openspec/changes/suppress-fixture-initial-script-command-logging/.openspec.yaml
new file mode 100644
index 00000000000..11967fcb6a7
--- /dev/null
+++ b/openspec/changes/suppress-fixture-initial-script-command-logging/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-07
diff --git a/openspec/changes/suppress-fixture-initial-script-command-logging/design.md b/openspec/changes/suppress-fixture-initial-script-command-logging/design.md
new file mode 100644
index 00000000000..2e8265bd515
--- /dev/null
+++ b/openspec/changes/suppress-fixture-initial-script-command-logging/design.md
@@ -0,0 +1,71 @@
+## Context
+
+Command-log persistence is handled by `CommandSubscriberForCommandLog`, which creates or syncs `CommandLogEntry` rows as published commands move through ready, started, and completed states.
+Existing command recording suppression is target-based and prevents helper objects from being recorded when command-log recording support is enabled.
+Initial fixture scripts are installed by `InitialFixtureScriptsInstaller` after the post-metamodel event and are executed through `FixtureScripts#run(...)`.
+That programmatic path can invoke domain actions while the command-log extension is active, causing startup fixture activity to appear as normal recorded commands.
+
+The command-log applib module already depends on the testing fixtures applib module, so command-log code can listen to fixture lifecycle events without adding a reverse dependency from testing fixtures to command-log.
+If pause and resume event classes are placed in command-log applib, fixture code must not import them unless the module dependency direction is intentionally changed.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a scoped command-log pause mechanism that prevents `CommandSubscriberForCommandLog` from creating or syncing command log entries while the scope is active.
+- Ensure command logging is resumed reliably after the scoped work completes, including exceptional fixture script execution.
+- Suppress commands produced by configured initial fixture scripts during application startup.
+- Keep normal command logging unchanged outside the paused scope.
+
+**Non-Goals:**
+
+- Do not disable command publishing globally or change command DTO construction.
+- Do not suppress audit trail, execution publishing, entity change publishing, or transaction behavior.
+- Do not change fixture script execution ordering, transaction boundaries, or multiple-execution strategy.
+- Do not remove existing target-based command recording suppression.
+
+## Decisions
+
+### Use a command-log-local pause state checked by the subscriber
+
+Add an internal command-log service that tracks whether logging is currently paused, and have `CommandSubscriberForCommandLog` return before create or sync work when the state is paused.
+This keeps the suppression close to persistence and avoids changing lower-level command creation or publishing behavior.
+
+Alternative considered: disable command publishing facets during fixture execution.
+That would be broader, harder to scope, and could affect unrelated subscribers that still need to see command activity.
+
+### Represent pause and resume as application events with an internal listener
+
+Add command-log application events such as `PauseLoggingEvent` and `ResumeLoggingEvent`, plus a command-log listener that updates the pause state.
+Use depth-counted pause state rather than a single boolean so nested pause scopes cannot resume logging too early.
+
+Alternative considered: expose imperative methods on a command-log pause service and inject that service into fixture code.
+Events keep the coupling looser for callers that can publish events, and the internal listener keeps the subscriber independent of event delivery details.
+
+### Bridge initial fixture execution without introducing a reverse module dependency
+
+Because testing fixtures applib should not depend on command-log applib, prefer one of these implementation shapes during apply.
+The lowest-coupling option is to have the initial fixture installation path publish fixture lifecycle events around the configured initial script and have command-log applib translate those fixture events into pause and resume state.
+If the module dependency direction is deliberately changed or an event type is moved to a shared module, `FixtureScripts` can instead publish the command-log `PauseLoggingEvent` and `ResumeLoggingEvent` directly around initial script execution.
+
+Alternative considered: call the existing UI-oriented `runFixtureScript(...)` lifecycle from the initial installer.
+That risks changing semantics for non-initial programmatic fixture runs and may suppress more fixture activity than requested.
+
+### Resume in finally blocks and tolerate missing starts
+
+The initial fixture path must publish resume in a `finally` block or use an equivalent scope helper.
+The pause state listener should also guard against unmatched resume events by never allowing its depth counter to become negative.
+
+Alternative considered: rely on normal successful completion of fixture scripts.
+That would leave logging paused after a failed startup fixture script and make subsequent diagnostics harder.
+
+## Risks / Trade-offs
+
+- [Risk] If pause and resume events are delivered through transaction-scoped or asynchronous event infrastructure, the subscriber might observe stale state.
+ → Mitigation: use the existing synchronous application event mechanism used by fixture lifecycle events, and test pause effects around command subscriber calls.
+- [Risk] A global pause state could affect concurrent interactions if startup fixture execution overlaps user requests.
+ → Mitigation: initial fixture installation occurs during startup before normal user traffic, and depth-counted state keeps nested scopes safe.
+- [Risk] Suppressing `onReady` but later receiving `onStarted` or `onCompleted` could find no command log entry.
+ → Mitigation: make all subscriber phases no-op while paused and keep existing optional lookup behavior after resume.
+- [Risk] Listening to broad fixture lifecycle events could suppress user-invoked fixture script commands, not only initial startup fixtures.
+ → Mitigation: prefer an initial-fixture-specific event or scoped helper when implementing the bridge, and add tests that document the intended scope.
diff --git a/openspec/changes/suppress-fixture-initial-script-command-logging/proposal.md b/openspec/changes/suppress-fixture-initial-script-command-logging/proposal.md
new file mode 100644
index 00000000000..8f552050e3e
--- /dev/null
+++ b/openspec/changes/suppress-fixture-initial-script-command-logging/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+Initial fixture scripts run automatically during application startup to seed an application before users begin normal work.
+When command-log recording support is enabled, commands produced while the initial script runs can pollute the command log with setup activity that is not user work and should not be exported or replayed as part of an application recording.
+
+## What Changes
+
+- Add a command-log applib mechanism to temporarily pause and resume command log persistence through published application events.
+- Provide internal command-log listeners that react to pause and resume events and cause `CommandSubscriberForCommandLog` to ignore commands while logging is paused.
+- Update the fixture initial script installer path so it emits pause and resume logging events around the configured initial script execution.
+- Preserve normal command logging outside the paused scope and ensure logging resumes even when initial fixture script execution fails.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `command-recording-suppression`: Extends command recording suppression from target-based suppression to scoped event-based pause and resume of command-log persistence.
+
+## Impact
+
+- Affects `extensions/core/commandlog/applib` by adding pause and resume event types plus internal subscriber state used by command log persistence.
+- Affects `CommandSubscriberForCommandLog` so it skips create and sync work while logging is paused.
+- Affects `testing/fixtures/applib` so `InitialFixtureScriptsInstaller` or `FixtureScripts` publishes the pause and resume events around initial script execution when command-log applib is present.
+- Adds tests covering pause and resume behavior and the initial fixture script startup path.
diff --git a/openspec/changes/suppress-fixture-initial-script-command-logging/specs/command-recording-suppression/spec.md b/openspec/changes/suppress-fixture-initial-script-command-logging/specs/command-recording-suppression/spec.md
new file mode 100644
index 00000000000..d8d94af0ee7
--- /dev/null
+++ b/openspec/changes/suppress-fixture-initial-script-command-logging/specs/command-recording-suppression/spec.md
@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: Command log persistence can be paused and resumed
+The system SHALL provide an application-event based mechanism to pause command log persistence.
+The system SHALL provide an application-event based mechanism to resume command log persistence after a previous pause.
+While command log persistence is paused, the command-log subscriber MUST NOT create new command log entries for published commands.
+While command log persistence is paused, the command-log subscriber MUST NOT sync existing command log entries for published command lifecycle updates.
+After command log persistence is resumed, subsequent eligible commands MUST remain persistable by the normal command-log subscriber flow.
+Nested pause scopes MUST NOT resume command log persistence until each active pause scope has been resumed.
+
+#### Scenario: Paused logging skips command entry creation
+- **GIVEN** command-log persistence is enabled
+- **AND** command log persistence has been paused
+- **WHEN** a command reaches the ready notification
+- **THEN** the system does not create a command log entry for that command
+
+#### Scenario: Paused logging skips command entry synchronization
+- **GIVEN** command-log persistence is enabled
+- **AND** command log persistence has been paused
+- **WHEN** a command reaches the started or completed notification
+- **THEN** the system does not sync a command log entry for that command notification
+
+#### Scenario: Resumed logging restores normal persistence
+- **GIVEN** command-log persistence is enabled
+- **AND** command log persistence was paused and has then been resumed
+- **WHEN** a subsequent eligible command reaches the ready notification
+- **THEN** the system can create a command log entry for that command through the normal command-log subscriber flow
+
+#### Scenario: Nested pause requires matching resumes
+- **GIVEN** command-log persistence is enabled
+- **AND** command log persistence has been paused twice
+- **WHEN** command log persistence is resumed once
+- **THEN** command log persistence remains paused
+- **WHEN** command log persistence is resumed a second time
+- **THEN** subsequent eligible commands can be persisted through the normal command-log subscriber flow
+
+### Requirement: Initial fixture script commands are not logged
+The system SHALL pause command log persistence while a configured initial fixture script is being installed during application startup.
+The system MUST resume command log persistence after the initial fixture script installation completes.
+The system MUST resume command log persistence if the initial fixture script installation fails.
+The pause MUST apply only to command-log persistence and MUST NOT prevent the fixture script from executing its domain logic normally.
+
+#### Scenario: Initial fixture script commands are suppressed
+- **GIVEN** command-log persistence is enabled
+- **AND** an application has a configured initial fixture script
+- **WHEN** the system installs the initial fixture script during startup
+- **THEN** commands produced by that initial fixture script are not persisted as command log entries
+- **AND** the fixture script domain logic still executes normally
+
+#### Scenario: Logging resumes after successful initial fixture installation
+- **GIVEN** command-log persistence is enabled
+- **AND** an application has installed its configured initial fixture script during startup
+- **WHEN** a subsequent eligible command is published after initial fixture installation completes
+- **THEN** the system can persist that command as a command log entry through the normal command-log subscriber flow
+
+#### Scenario: Logging resumes after failed initial fixture installation
+- **GIVEN** command-log persistence is enabled
+- **AND** an application has a configured initial fixture script that fails during startup installation
+- **WHEN** command processing continues after the failed initial fixture installation scope exits
+- **THEN** command log persistence is no longer paused because of the initial fixture installation scope
diff --git a/openspec/changes/suppress-fixture-initial-script-command-logging/tasks.md b/openspec/changes/suppress-fixture-initial-script-command-logging/tasks.md
new file mode 100644
index 00000000000..77ca15227dd
--- /dev/null
+++ b/openspec/changes/suppress-fixture-initial-script-command-logging/tasks.md
@@ -0,0 +1,27 @@
+## 1. Command Log Pause State
+
+- [ ] 1.1 Add command-log applib event types for pausing and resuming command log persistence, with API documentation describing their scoped use.
+- [ ] 1.2 Add an internal command-log pause state service that tracks nested pause depth and exposes whether command logging is currently paused.
+- [ ] 1.3 Add an internal command-log listener that reacts to pause and resume events and updates the pause state service.
+- [ ] 1.4 Register any new command-log listener or support service in `CausewayModuleExtCommandLogApplib` if component scanning does not already include it.
+
+## 2. Subscriber Suppression
+
+- [ ] 2.1 Update `CommandSubscriberForCommandLog#onReady` to return without creating or comparing command log entries while command logging is paused.
+- [ ] 2.2 Update `CommandSubscriberForCommandLog#onStarted` and `#onCompleted` to return without syncing command log entries while command logging is paused.
+- [ ] 2.3 Add unit tests for paused ready, started, and completed notifications.
+- [ ] 2.4 Add unit tests proving resumed and nested pause scopes restore normal command-log persistence only after all active pauses are resumed.
+
+## 3. Initial Fixture Script Integration
+
+- [ ] 3.1 Identify the lowest-coupling bridge from initial fixture installation to command-log pause state, respecting the existing dependency from command-log applib to testing fixtures applib.
+- [ ] 3.2 Update the initial fixture script execution path to enter a command-log pause scope before running the configured initial script and to resume in a `finally` path.
+- [ ] 3.3 Ensure the initial fixture script still executes through the existing `FixtureScripts` domain logic and transaction behavior.
+- [ ] 3.4 Add tests proving commands produced by the configured initial fixture script are not persisted as command log entries.
+- [ ] 3.5 Add tests proving command logging resumes after successful and failed initial fixture script execution.
+
+## 4. Verification
+
+- [ ] 4.1 Run focused command-log applib tests covering the new pause state and subscriber behavior.
+- [ ] 4.2 Run focused testing fixtures applib or integration tests covering initial fixture installation behavior.
+- [ ] 4.3 Run `openspec validate suppress-fixture-initial-script-command-logging --strict` and fix any proposal/spec/task issues.