| # Command Export Command Reordering Specification |
| |
| ## Purpose |
| |
| Define deterministic unified-manager command movement through synchronized command-log and DTO retimestamping without persistence-schema changes. |
| ## Requirements |
| ### Requirement: Unified manager moves selected commands after an active target |
| When command-log recording support is `ENABLED`, the unified manager SHALL provide one `moveCommands` action associated with `commandsInSequence`. It SHALL move one or more selected commands earlier or later by retimestamping them after an unselected target command. Selected and target choices SHALL come from the current baseline-and-limit-bounded sequence, with selected commands removed from target choices. Direct invocation MUST reject disabled recording support, an empty selection, a missing target, a selected target, or any selected or target interaction id outside the fresh current sequence before changing any timestamp. Excluded commands MUST NOT be selectable or targetable, and separate `moveCommandsUp` and `moveCommandsDown` actions MUST NOT be exposed. |
| |
| #### Scenario: Target choices exclude the selected block |
| - **GIVEN** active sequence commands `A`, `B`, and `C` and selected commands `B` and `C` |
| - **WHEN** movement target choices are requested |
| - **THEN** `A` is offered |
| - **AND** `B` and `C` are not offered |
| |
| #### Scenario: One action moves earlier or later |
| - **GIVEN** active sequence order `A`, `B`, `C` |
| - **WHEN** `C` is moved after `A` or `A` is moved after `C` |
| - **THEN** each invocation is accepted and retimestamps the selected command after its target |
| - **AND** no direction-specific movement action is required |
| |
| #### Scenario: Invalid movement changes nothing |
| - **GIVEN** selected command `A` is active and command `B` is excluded or outside the current bounded sequence |
| - **WHEN** direct invocation uses `B` as target or includes it in the selected block |
| - **THEN** movement is rejected |
| - **AND** no command-log or DTO timestamp changes |
| |
| ### Requirement: Movement preserves selected order with a one-second minimum gap |
| The action SHALL derive selected order from the fresh manager sequence before mutation and SHALL place the first selected command exactly one second after the target timestamp. For each later selected command, it SHALL preserve the original elapsed time from its preceding selected command only when that gap is positive and at least one second; otherwise it SHALL use a one-second increment. The action SHALL update each selected entry's command-log timestamp and embedded `CommandDto` timestamp to the same value. It MUST NOT change the target timestamp, any unselected entry timestamp, replay states, results, repository membership, manager baseline, or manager limit. |
| |
| #### Scenario: Selected timing gaps are preserved |
| - **GIVEN** selected commands `A` and `B` are 2.5 seconds apart and target `C` has timestamp `10:00:00` |
| - **WHEN** the block is moved after `C` without timing squash |
| - **THEN** `A` has timestamp `10:00:01` |
| - **AND** `B` has timestamp `10:00:03.5` |
| - **AND** both embedded DTO timestamps match their entry timestamps |
| |
| #### Scenario: Invalid or short gaps use deterministic minimum |
| - **GIVEN** two selected commands have equal, reversed, unavailable, or sub-second relative timing |
| - **WHEN** they are moved after a target without timing squash |
| - **THEN** their new timestamps retain selected manager order |
| - **AND** adjacent selected commands are separated by at least one second |
| |
| #### Scenario: Movement is observational outside selected timestamps |
| - **WHEN** a selected block is moved after a target |
| - **THEN** target and unselected timestamps remain unchanged |
| - **AND** replay states, results, repository membership, baseline, and limit remain unchanged |
| |
| ### Requirement: Movement can squash selected timing gaps |
| The movement action SHALL provide a `squashTimings` boolean parameter defaulting to false. When false, it SHALL apply the preserve-gap policy with the one-second minimum. When true, it SHALL discard every original selected-command gap, place the first selected command one second after the target, and place each later selected command exactly one second after its predecessor while retaining selected manager order. |
| |
| #### Scenario: Timing squash produces one-second spacing |
| - **GIVEN** selected commands `A`, `B`, and `C` have arbitrary original gaps |
| - **WHEN** they are moved with timing squash enabled |
| - **THEN** `A` is one second after the target |
| - **AND** `B` is one second after `A` |
| - **AND** `C` is one second after `B` |
| |
| #### Scenario: Timing preservation remains the default |
| - **WHEN** movement parameter defaults are requested |
| - **THEN** `squashTimings` is false |
| - **AND** positive original gaps of at least one second are preserved unless the user opts in |
| |
| ### Requirement: JPA persists movement without a new ordering schema |
| Causeway 4 SHALL persist moved command-log and DTO timestamps through the existing managed `CommandLogEntry` mutation contract and Jakarta Persistence adapter. W1 MUST NOT add a persistent order field, datastore migration, JDO-specific implementation, or restored commandlog JDO adapter. Reloading moved entries SHALL retain matching timestamps and established timestamp-based queries SHALL observe the new order. |
| |
| #### Scenario: Reload observes moved timestamps and order |
| - **WHEN** selected commands are moved and the JPA transaction commits |
| - **THEN** reloaded entry timestamps match their embedded DTO timestamps |
| - **AND** foreground timestamp ordering reflects the movement |
| |
| #### Scenario: Persistence model remains compatible |
| - **WHEN** W1 is deployed |
| - **THEN** the existing command-log schema remains usable without migration |
| - **AND** no commandlog JDO adapter is introduced |
