csvops 0.3.0.alpha → 0.5.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9663c50901b31a8073c4a5a0524e9e30c81c20bbe1b736af71649e60a7150a0e
-  data.tar.gz: a622dad35eb52afeded279726d2575db0cd210c8ed4aa07650506bfd2e2b6de5
+  metadata.gz: b96fb7e03fa0629d3412a97d3abff5414492ac46ad08ede2c872e2176fcbfc62
+  data.tar.gz: 856b7735a472b5810d5f19dff6371a565a7fcc538ce5b6eba52260fff0028760
 SHA512:
-  metadata.gz: 28726bb66d05881caead074ce529d79db5424b85a7552f8b56cca44e891b3bb0c34cd850ff22351d6d93a5ef725e3891ccc8b7ac7e1e62d24d4e4c4d7d9b344d
-  data.tar.gz: 0fb96011d8737fb757b30e6226b9086453aa3ef6e5def1e95b77bb8bdbd414e25b72adfe6a8e65ee0498bbb88f2a809777a0d2405057689d00b3858c73014b93
+  metadata.gz: 5f643d331c6b54cb5feb0fe5db4ff7f8f7bc5c28461f74e3bfca5cf93d25703b84f497e72377302874b2b6302ef0fb542995c72d2d21798e3a998f6d5b294704
+  data.tar.gz: 0e254fa75780ce0605054c24b28301d8786535a0f2bbff7adfb45a75f09e60e5315e950648208fa5772d08cdd6abce95ea382838f568947af05ceaa77ba1888f

data/README.md

@@ -35,22 +35,30 @@ bundle exec csvtool menu
 CSV Tool Menu
 1. Extract column
 2. Extract rows (range)
-3. Exit
+3. Randomize rows
+4. Dedupe using another CSV
+5. Exit
 >
 ```
 
-Select `1` to run extraction.
+Select `1` for column extraction, `2` for row-range extraction, `3` for row randomization, or `4` for cross-CSV dedupe.
 
 ### 3. Follow prompts
 
-Prompt flow:
+Each menu action runs through a dedicated CLI workflow (`interface/cli/workflows/*`) that handles prompts/output and delegates execution to an interface-agnostic application use case.
 
-- CSV file path
-- Separator (`comma`, `tab`, `semicolon`, `pipe`, or `custom`)
-- Optional header filter + column selection
-- Skip blanks (`Y/n`, default `Y`)
-- Preview + confirmation
-- Output destination (`console` or `file`)
+Workflow internals are split into small composable parts:
+
+- `workflows/builders/*` for session construction
+- `workflows/support/*` for shared mapping/dispatch utilities
+- `workflows/presenters/*` for output formatting and summaries
+
+Prompt flow by action:
+
+- `Extract column`: file path, separator, optional header filter + column select, skip blanks, preview/confirm, output destination.
+- `Extract rows (range)`: file path, separator, start row, end row, output destination.
+- `Randomize rows`: file path, separator, headers present, optional seed, output destination.
+- `Dedupe using another CSV`: source/reference files, separators, header modes, key selectors, match options, output destination.
 
 ### 4. Example interaction (console output)
 
@@ -111,6 +119,53 @@ With Bundler:
 bundle exec csvtool column /path/to/file.csv column_name
 ```
 
+### 7. Dedupe interaction example
+
+Legend: ` ` = prompt/menu, `+` = user input, `-` = tool output
+
+```diff
+ CSV Tool Menu
+ 1. Extract column
+ 2. Extract rows (range)
+ 3. Randomize rows
+ 4. Dedupe using another CSV
+ 5. Exit
++> 4
+ CSV file path: /tmp/source.csv
+ Source CSV separator:
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Source headers present? [Y/n]:
+ Reference CSV file path: /tmp/reference.csv
+ Reference CSV separator:
+ Choose separator:
+ 1. comma (,)
+ 2. tab (\t)
+ 3. semicolon (;)
+ 4. pipe (|)
+ 5. custom
++Separator choice [1]: 1
+ Reference headers present? [Y/n]:
+ Source key column name: customer_id
+ Reference key column name: external_id
+ Trim whitespace before matching? [Y/n]:
+ Case-insensitive matching? [y/N]:
+ Output destination:
+ 1. console
+ 2. file
++Output destination [1]: 1
+-
+-customer_id,name
+-1,Alice
+-3,Cara
+-Summary: source_rows=5 removed_rows=3 kept_rows=2
+```
+
 ## Testing
 
 Run tests:
@@ -127,7 +182,7 @@ bundle exec rake test
 
 ## Alpha release
 
-Current prerelease version: `0.3.0.alpha`
+Current prerelease version: `0.5.0.alpha`
 
 Install prerelease from RubyGems:
 
@@ -137,146 +192,11 @@ gem install csvops --pre
 
 Release runbook:
 
-- `docs/release-v0.3.0-alpha.md`
+- `docs/release-v0.5.0-alpha.md`
 
-## Architecture
-
-The codebase follows a DDD-lite layered structure:
-
-- `domain/`: core domain models and invariants (`ColumnSession`, `RowSession`, and `RandomizationSession` aggregates + supporting entities/value objects).
-- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`).
-- `infrastructure/`: CSV reading/streaming and output adapters (console/file).
-- `interface/cli/`: menu, prompts, and user-facing error presentation.
-- `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
-
-## Domain model
-
-Bounded contexts: `Column Extraction`, `Row Extraction`, and `Row Randomization`.
-
-### Column Extraction
-
-- Aggregate root: `ColumnSession`
-  - Controls extraction state transitions (`start`, `with_preview`, `confirm!`, `with_output_destination`).
-  - Enforces session-level invariants.
-- Entities:
-  - `CsvSource` (file path + `Separator`)
-  - `ColumnSelection` (chosen header)
-- Value objects:
-  - `Separator`
-  - `ExtractionOptions` (`skip_blanks`, `preview_limit`)
-  - `Preview` (list of `ExtractionValue`)
-  - `ExtractionValue`
-  - `OutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunExtraction` orchestrates one extraction request.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::ValueStreamer`
-  - `Infrastructure::Output::ConsoleWriter`
-  - `Infrastructure::Output::CsvFileWriter`
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI["Interface CLI\n(Menu + Prompts + Errors)"] --> APP["Application Use Case\nRunExtraction"]
-  APP --> AGG["Domain Aggregate\nColumnSession"]
-
-  AGG --> E1["Entity\nCsvSource"]
-  AGG --> E2["Entity\nColumnSelection"]
-  AGG --> V1["Value Objects\nSeparator / ExtractionOptions / Preview / OutputDestination / ExtractionValue"]
-
-  APP --> INFCSV["Infrastructure CSV\nHeaderReader + ValueStreamer"]
-  APP --> INFOUT["Infrastructure Output\nConsoleWriter + CsvFileWriter"]
-```
-
-### Row Extraction
-
-Core DDD structure:
-
-- Aggregate root: `RowSession`
-  - Captures one row-range extraction request.
-  - Holds selected source, requested range, and output destination.
-- Entity:
-  - `RowSource` (file path + separator)
-- Value objects:
-  - `RowRange` (`start_row`, `end_row`) plus row-range validation errors
-  - `RowOutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunRowExtraction` orchestrates row-range extraction.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::RowStreamer`
-  - `Infrastructure::Output::CsvRowConsoleWriter`
-  - `Infrastructure::Output::CsvRowFileWriter`
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI2["Interface CLI\n(Menu + Prompts + Errors)"] --> APP2["Application Use Case\nRunRowExtraction"]
-  APP2 --> AGG2["Domain Aggregate\nRowSession"]
-
-  AGG2 --> E3["Entity\nRowSource"]
-  AGG2 --> V2["Value Objects\nRowRange / RowOutputDestination"]
-
-  APP2 --> INFCSV2["Infrastructure CSV\nHeaderReader + RowStreamer"]
-  APP2 --> INFOUT2["Infrastructure Output\nCsvRowConsoleWriter + CsvRowFileWriter"]
-```
 
-### Row Randomization
-
-Core DDD structure:
-
-- Aggregate root: `RandomizationSession`
-  - Captures one randomization request from source + options + output destination.
-- Entity:
-  - `RandomizationSource` (file path + separator + header mode)
-- Value objects:
-  - `RandomizationOptions` (optional deterministic `seed`)
-  - `RandomizationOutputDestination` (`console` or `file(path)`)
-- Application service:
-  - `Application::UseCases::RunRowRandomization` orchestrates row randomization.
-- Infrastructure adapters:
-  - `Infrastructure::CSV::HeaderReader`
-  - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
-- Interface adapters:
-  - `Interface::CLI::MenuLoop`
-  - `Interface::CLI::Prompts::*`
-  - `Interface::CLI::Errors::Presenter`
-
-```mermaid
-flowchart LR
-  UI3["Interface CLI\n(Menu + Prompts + Errors)"] --> APP3["Application Use Case\nRunRowRandomization"]
-  APP3 --> AGG3["Domain Aggregate\nRandomizationSession"]
-
-  AGG3 --> E4["Entity\nRandomizationSource"]
-  AGG3 --> V3["Value Objects\nRandomizationOptions / RandomizationOutputDestination"]
-
-  APP3 --> INFCSV3["Infrastructure CSV\nHeaderReader + RowRandomizer"]
-```
+## Architecture
 
-## Project layout
+Full architecture and domain documentation lives in:
 
-```text
-bin/tool              # CLI entrypoint
-lib/csvtool/cli.rb
-lib/csvtool/domain/column_session/*
-lib/csvtool/domain/row_session/*
-lib/csvtool/domain/row_randomization_session/*
-lib/csvtool/application/use_cases/run_extraction.rb
-lib/csvtool/application/use_cases/run_row_extraction.rb
-lib/csvtool/application/use_cases/run_row_randomization.rb
-lib/csvtool/infrastructure/csv/*
-lib/csvtool/infrastructure/output/*
-lib/csvtool/interface/cli/menu_loop.rb
-lib/csvtool/interface/cli/prompts/*
-lib/csvtool/interface/cli/errors/presenter.rb
-test/csvtool/cli_test.rb         # end-to-end workflow tests
-test/csvtool/**/*_test.rb        # focused unit tests by component folder
-test/test_helper.rb
-```
+- [`docs/architecture.md`](docs/architecture.md)

data/docs/architecture.md

@@ -0,0 +1,396 @@
+# Architecture
+
+The codebase follows a DDD-lite layered structure:
+
+- `domain/`: core domain models and invariants (`ColumnSession`, `RowSession`, `RandomizationSession`, and `CrossCsvDedupeSession` aggregates + supporting entities/value objects).
+- `application/`: use-case orchestration (`RunExtraction`, `RunRowExtraction`, `RunRowRandomization`, `RunCrossCsvDedupe`).
+- `infrastructure/`: CSV reading/streaming and output adapters (console/file), plus cross-CSV dedupe adapter.
+- `interface/cli/`: menu, prompts, workflows, and user-facing error presentation.
+- `Csvtool::CLI`: entrypoint wiring from command args to interface/application flow.
+
+## Workflow boundary (standardized)
+
+For all interactive domains (`Column Extraction`, `Row Extraction`, `Row Randomization`, `Cross-CSV Dedupe`), the boundary is:
+
+- `interface/cli/workflows/*`: owns prompts, stdout rendering, and user-facing error presentation.
+- `interface/cli/workflows/builders/*`: builds domain sessions/aggregates from prompt results.
+- `interface/cli/workflows/support/*`: shared workflow utilities (error routing, output destination mapping).
+- `interface/cli/workflows/presenters/*`: workflow-level output/summary rendering.
+- `interface/cli/workflows/steps/*`: optional step-pipeline units for complex workflow orchestration.
+- `application/use_cases/*`: interface-agnostic orchestration with request/result style contracts.
+- `domain/*`: invariants and domain policies.
+- `infrastructure/*`: CSV mechanics and output adapters.
+
+Write-boundary rule:
+- Use cases coordinate write paths but do not perform direct file writes.
+- Direct write APIs (`CSV.open`, writable `File.open`, `File.write`, `IO.write`) are infrastructure-only.
+- File output behavior is implemented in `infrastructure/output/*` writer adapters.
+
+Current usage:
+
+- `RunExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::Extraction::*`.
+- `RunRowExtractionWorkflow` uses `WorkflowStepPipeline` + `Steps::RowExtraction::*`.
+- `RunRowRandomizationWorkflow` uses `WorkflowStepPipeline` + `Steps::RowRandomization::*`.
+- `RunCrossCsvDedupeWorkflow` uses `WorkflowStepPipeline` + `Steps::CrossCsvDedupe::*`.
+
+## Adding New Concepts
+
+Use this checklist when introducing a new capability (for example: a new transformation function, validator, comparer, or exporter).
+
+### 1) Classify the concept first
+
+- `Workflow concept`: interactive flow and prompt sequence.
+- `Domain concept`: business rule/invariant and core vocabulary.
+- `Application concept`: use-case orchestration and request/result contract.
+- `Infrastructure concept`: file/CSV mechanics, streaming, persistence, or external IO.
+
+If it does not clearly fit one layer, split it until each part has one responsibility.
+
+### 2) Add the feature vertically (thin slice)
+
+Implement in this order:
+
+1. `interface/cli/workflows/*`: new workflow entry or new branch in an existing workflow.
+2. `interface/cli/prompts/*`: prompts for user inputs.
+3. `interface/cli/workflows/builders/*`: build domain session/request objects.
+4. `application/use_cases/*`: interface-agnostic use case with `Result` success/failure.
+5. `domain/*`: new entities/value objects/aggregate changes for invariants.
+6. `infrastructure/*`: adapters needed by the use case.
+7. `interface/cli/workflows/presenters/*`: output and summaries.
+
+Keep each step testable on its own before moving to the next.
+
+### 3) Function type patterns
+
+For a new function type, prefer one of these patterns:
+
+- `Transform` (changes output rows/values):
+  - Domain: transformation options/value objects.
+  - Application: orchestrate transform over streamed rows.
+  - Infrastructure: stream reader/writer implementation.
+- `Validate` (checks and reports findings):
+  - Domain: validation policy and finding model.
+  - Application: run checks and return findings in result data.
+  - Presenter: format findings and summary.
+- `Compare` (source vs reference logic):
+  - Domain: mapping/selectors/match options.
+  - Application: compare strategy and stats.
+  - Infrastructure: dual-source readers and selector helpers.
+- `Export` (destination-focused):
+  - Domain: output destination value object.
+  - Application: orchestrate write path only.
+  - Infrastructure: writer adapter.
+
+### 4) Required boundaries and rules
+
+- Workflows do not contain business rules.
+- Use cases do not prompt or print.
+- Domain does not depend on interface or infrastructure.
+- Infrastructure does not own workflow decisions.
+- Shared workflow helpers belong under `workflows/support/*`.
+- Reusable construction logic belongs under `workflows/builders/*`.
+- Rendering/summary formatting belongs under `workflows/presenters/*`.
+
+### 5) Minimum tests for each new concept
+
+- Prompt tests for each new prompt class.
+- Builder tests for each new builder class.
+- Use-case tests for request/result behavior.
+- Workflow behavior tests for prompt + output integration.
+- One end-to-end CLI test for the happy path.
+
+### 6) Naming and structure guidance
+
+- Prefer domain-first names (`RowRange`, `ColumnSelection`, `MatchOptions`) over technical names.
+- Use `Run<Concept>` for use cases and `Run<Concept>Workflow` for workflows.
+- Keep one file per class and mirror structure under `test/csvtool/...`.
+
+## Domain model
+
+Bounded contexts: `Column Extraction`, `Row Extraction`, `Row Randomization`, and `Cross-CSV Dedupe`.
+
+### Cross-CSV Dedupe (Large-file behavior)
+
+- Workflow: remove rows from a source CSV when source key matches a key from a reference CSV.
+- Scaling strategy:
+  - Reference CSV keys are loaded into a `Set` for fast membership checks.
+  - Source CSV rows are streamed directly to the selected output destination (console or file).
+- Memory tradeoff:
+  - Memory is dominated by the number of unique keys in the reference CSV.
+  - Source-row memory stays bounded because retained rows are not accumulated in memory before writing.
+
+### Column Extraction
+
+- Aggregate root: `ColumnSession`
+  - Controls extraction state transitions (`start`, `with_preview`, `confirm!`, `with_output_destination`).
+  - Enforces session-level invariants.
+- Entities:
+  - `CsvSource` (file path + `Separator`)
+  - `ColumnSelection` (chosen header)
+- Value objects:
+  - `Separator`
+  - `ExtractionOptions` (`skip_blanks`, `preview_limit`)
+  - `Preview` (list of `ExtractionValue`)
+  - `ExtractionValue`
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunExtraction` is interface-agnostic and exposes request/result operations.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::ValueStreamer`
+  - `Infrastructure::Output::ConsoleWriter`
+  - `Infrastructure::Output::CsvFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::ColumnSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::Extraction::*`
+  - `Interface::CLI::Workflows::Presenters::ColumnExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunExtractionWorkflow
+  class Prompts
+  class Errors
+  class RunExtraction
+  class ColumnSession
+  class CsvSource
+  class ColumnSelection
+  class ExtractionOptions
+  class Preview
+  class ExtractionValue
+  class OutputDestination
+  class HeaderReader
+  class ValueStreamer
+  class CsvFileWriter
+
+  MenuLoop --> RunExtractionWorkflow : invokes
+  RunExtractionWorkflow --> Prompts : uses
+  RunExtractionWorkflow --> Errors : reports failures
+  RunExtractionWorkflow --> RunExtraction : calls
+  RunExtraction --> ColumnSession : orchestrates
+  ColumnSession o-- CsvSource
+  ColumnSession o-- ColumnSelection
+  ColumnSession o-- ExtractionOptions
+  ColumnSession o-- Preview
+  Preview o-- ExtractionValue
+  ColumnSession o-- OutputDestination
+  RunExtraction --> HeaderReader
+  RunExtraction --> ValueStreamer
+  RunExtraction --> CsvFileWriter
+```
+
+### Row Extraction
+
+Core DDD structure:
+
+- Aggregate root: `RowSession`
+  - Captures one row-range extraction request.
+  - Holds selected source, requested range, and output destination.
+- Entity:
+  - `RowSource` (file path + separator)
+- Value objects:
+  - `RowRange` (`start_row`, `end_row`) plus row-range validation errors
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunRowExtraction` is interface-agnostic and exposes request/result operations.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::RowStreamer`
+  - `Infrastructure::Output::CsvRowFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowExtractionWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowExtractionSessionBuilder`
+  - `Interface::CLI::Workflows::Presenters::RowExtractionPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowExtraction::*`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunRowExtractionWorkflow
+  class Prompts
+  class Errors
+  class RunRowExtraction
+  class RowSession
+  class RowSource
+  class RowRange
+  class OutputDestination
+  class HeaderReader
+  class RowStreamer
+  class CsvRowFileWriter
+  MenuLoop --> RunRowExtractionWorkflow : invokes
+  RunRowExtractionWorkflow --> Prompts : uses
+  RunRowExtractionWorkflow --> Errors : reports failures
+  RunRowExtractionWorkflow --> RunRowExtraction : calls
+  RunRowExtraction --> RowSession : orchestrates
+  RowSession o-- RowSource
+  RowSession o-- RowRange
+  RowSession o-- OutputDestination
+  RunRowExtraction --> HeaderReader
+  RunRowExtraction --> RowStreamer
+  RunRowExtraction --> CsvRowFileWriter
+```
+
+### Row Randomization
+
+Core DDD structure:
+
+- Aggregate root: `RandomizationSession`
+  - Captures one randomization request from source + options + output destination.
+- Entity:
+  - `RandomizationSource` (file path + separator + header mode)
+- Value objects:
+  - `RandomizationOptions` (optional deterministic `seed`)
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunRowRandomization` is interface-agnostic and exposes request/result operations.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::RowRandomizer` (external chunked `RAND + sort` + merge)
+  - `Infrastructure::Output::CsvRandomizedRowFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunRowRandomizationWorkflow`
+  - `Interface::CLI::Workflows::Builders::RowRandomizationSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::RowRandomization::*`
+  - `Interface::CLI::Workflows::Presenters::RowRandomizationPresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunRowRandomizationWorkflow
+  class Prompts
+  class Errors
+  class RunRowRandomization
+  class RandomizationSession
+  class RandomizationSource
+  class RandomizationOptions
+  class OutputDestination
+  class HeaderReader
+  class RowRandomizer
+  class CsvRandomizedRowFileWriter
+
+  MenuLoop --> RunRowRandomizationWorkflow : invokes
+  RunRowRandomizationWorkflow --> Prompts : uses
+  RunRowRandomizationWorkflow --> Errors : reports failures
+  RunRowRandomizationWorkflow --> RunRowRandomization : calls
+  RunRowRandomization --> RandomizationSession : orchestrates
+  RandomizationSession o-- RandomizationSource
+  RandomizationSession o-- RandomizationOptions
+  RandomizationSession o-- OutputDestination
+  RunRowRandomization --> HeaderReader
+  RunRowRandomization --> RowRandomizer
+  RunRowRandomization --> CsvRandomizedRowFileWriter
+```
+
+### Cross-CSV Dedupe
+
+Core DDD structure:
+
+- Aggregate root: `CrossCsvDedupeSession`
+  - Captures one dedupe request with source/reference profiles, key mapping, match options, and output destination.
+- Entities:
+  - `CsvProfile` (path + separator + header mode) for source and reference CSVs.
+  - `KeyMapping` (source selector + reference selector).
+- Value objects:
+  - `ColumnSelector` (header name or 1-based index mode)
+  - `MatchOptions` (`trim_whitespace`, `case_insensitive`, plus normalization behavior)
+  - Shared `OutputDestination` (`console` or `file(path)`)
+- Application service:
+  - `Application::UseCases::RunCrossCsvDedupe` orchestrates dedupe workflow.
+- Infrastructure adapters:
+  - `Infrastructure::CSV::HeaderReader`
+  - `Infrastructure::CSV::SelectorValidator`
+  - `Infrastructure::CSV::CrossCsvDeduper` (streams source rows while checking membership against reference key set)
+  - `Infrastructure::Output::CsvCrossCsvDedupeFileWriter`
+- Interface adapters:
+  - `Interface::CLI::MenuLoop`
+  - `Interface::CLI::Workflows::RunCrossCsvDedupeWorkflow`
+  - `Interface::CLI::Workflows::Builders::CrossCsvDedupeSessionBuilder`
+  - `Interface::CLI::Workflows::Steps::WorkflowStepPipeline`
+  - `Interface::CLI::Workflows::Steps::CrossCsvDedupe::*`
+  - `Interface::CLI::Workflows::Presenters::CrossCsvDedupePresenter`
+  - `Interface::CLI::Workflows::Support::{OutputDestinationMapper,ResultErrorHandler}`
+  - `Interface::CLI::Prompts::*`
+  - `Interface::CLI::Errors::Presenter`
+
+```mermaid
+classDiagram
+  direction LR
+  class MenuLoop
+  class RunCrossCsvDedupeWorkflow
+  class Prompts
+  class Errors
+  class RunCrossCsvDedupe
+  class CrossCsvDedupeSession
+  class CsvProfile
+  class KeyMapping
+  class ColumnSelector
+  class MatchOptions
+  class OutputDestination
+  class HeaderReader
+  class SelectorValidator
+  class CrossCsvDeduper
+  class CsvCrossCsvDedupeFileWriter
+
+  MenuLoop --> RunCrossCsvDedupeWorkflow : invokes
+  Prompts --> RunCrossCsvDedupeWorkflow : provides input
+  RunCrossCsvDedupeWorkflow --> Errors : reports failures
+  RunCrossCsvDedupeWorkflow --> RunCrossCsvDedupe : calls
+  RunCrossCsvDedupe --> CrossCsvDedupeSession : orchestrates
+  CrossCsvDedupeSession o-- CsvProfile
+  CrossCsvDedupeSession o-- KeyMapping
+  KeyMapping o-- ColumnSelector
+  CrossCsvDedupeSession o-- MatchOptions
+  CrossCsvDedupeSession o-- OutputDestination
+  RunCrossCsvDedupe --> HeaderReader
+  RunCrossCsvDedupe --> SelectorValidator
+  RunCrossCsvDedupe --> CrossCsvDeduper
+  RunCrossCsvDedupe --> CsvCrossCsvDedupeFileWriter
+```
+
+## Project layout
+
+```text
+bin/tool              # CLI entrypoint
+lib/csvtool/cli.rb
+lib/csvtool/domain/column_session/*
+lib/csvtool/domain/row_session/*
+lib/csvtool/domain/row_randomization_session/*
+lib/csvtool/domain/cross_csv_dedupe_session/*
+lib/csvtool/domain/shared/output_destination.rb
+lib/csvtool/application/use_cases/run_extraction.rb
+lib/csvtool/application/use_cases/run_row_extraction.rb
+lib/csvtool/application/use_cases/run_row_randomization.rb
+lib/csvtool/application/use_cases/run_cross_csv_dedupe.rb
+lib/csvtool/infrastructure/csv/*
+lib/csvtool/infrastructure/output/*
+lib/csvtool/interface/cli/menu_loop.rb
+lib/csvtool/interface/cli/workflows/*
+lib/csvtool/interface/cli/workflows/builders/*
+lib/csvtool/interface/cli/workflows/support/*
+lib/csvtool/interface/cli/workflows/presenters/*
+lib/csvtool/interface/cli/workflows/steps/*
+lib/csvtool/interface/cli/prompts/*
+lib/csvtool/interface/cli/errors/presenter.rb
+test/csvtool/cli_test.rb         # end-to-end workflow tests
+test/csvtool/**/*_test.rb        # focused unit tests by component folder
+test/test_helper.rb
+```