Add relational ingest + schema-fingerprinted DatasetView flattening (Phases 0–2)

.github/copilot-instructions.md

@@ -0,0 +1,17 @@
+# Copilot instructions for this repository
+
+When creating or modifying Java code:
+
+1. Always add/update Javadocs for every class and every method (including private, but not test methods).
+2. Keep Javadocs synchronized with signature changes:
+   - update all `@param`
+   - add/update `@return` when non-void
+   - add/update `@throws` when exceptions are declared
+3. Use tabs (size 4), LF line endings, and K&R braces.
+4. Follow Google Java naming conventions.
+5. Do not leave TODO Javadocs; provide meaningful descriptions.
+6. Ensure that `mvn verify` passes.
+7. Ensure that each file has a license header at the top, as specified in the LICENSE file.
+8. Provide comprehensive test coverage for new or modified code, and ensure that all tests pass.
+9. When making changes, provide a clear and concise commit message that describes the purpose of the change.
+10. When making changes, unless specifically instructed to change existing functionality, make sure that new code is backward compatible with existing code and does not break existing functionality.

CLAUDE.md

@@ -56,14 +56,15 @@ mistyped path fails fast and offline — keep that ordering, it is what keeps th
 touching the network.
 
 Configuration defaults live in `src/main/resources/application.properties`
-(`bdq.usecase.file`, `bdq.rdf.files`, `bdq.dataset`, `bdq.dataset.table`, `bdq.usecase.id`,
+(`bdq.usecase.file`, `bdq.rdf.files`, `bdq.dataset`, `bdq.dataset.table`, `bdq.dataset.view`, `bdq.usecase.id`,
 `bdq.discovery.packages`, `bdq.threads`, `bdq.execution.dedup`) and are merged with CLI/GUI
 overrides by `ConfigLoader`. `bdq.usecase.file` and `bdq.rdf.files` ship blank, which means "use
 the `WorkbenchDefaults` published sources"; set either to a local path or an HTTP URL to pin a
 run. `bdq.dataset.table` (CLI `--dataset-table`, GUI advanced options) names which table of a
 multi-table dataset to run against. Both entry points fetch and cache use-case/test-definition/
 ontology RDF from `bdq.tdwg.org` through `CachedResourceResolver`; RDF/XML, Turtle, and JSON-LD
-serializations are all supported. Logging is DEBUG-by-default to the
+serializations are all supported. `bdq.dataset.view` (CLI `--dataset-view`, GUI "Build Dataset View...")
+names a standalone JSON DatasetView used to flatten relational inputs before execution. Logging is DEBUG-by-default to the
 console via `src/main/resources/logback.xml`.
 
 ## Architecture

README.md

@@ -51,6 +51,14 @@ Configuration defaults are in `src/main/resources/application.properties` and ca
 java -jar target/bdq_workbench-0.1.0-SNAPSHOT.jar --dataset path/to/dataset.zip
 ```
 
+Reusable relational flattening views can be supplied with `--dataset-view` (`bdq.dataset.view` in config):
+
+```bash
+java -jar target/bdq_workbench-0.1.0-SNAPSHOT.jar \
+  --dataset path/to/datapackage.json \
+  --dataset-view path/to/bdq-dataset-view.json
+```
+
 Configuration precedence is:
 
 1. command-line or GUI-supplied overrides
@@ -76,7 +84,7 @@ Dataset input
    |
    +--> Load DwC-A zip / Data Package CSV
    |
-   +--> [optional] Build record filters from dataset terms/values (GUI)
+   +--> [optional] Build dataset view and/or record filters from dataset terms/values (GUI)
    |
    +--> [optional] Apply record filters
    |

src/main/java/org/filteredpush/bdq_workbench/app/AppConfig.java

@@ -48,17 +48,19 @@
  * @param datasetTable which of the input dataset's tables to run against — a Darwin Core
  *     Archive's core or one of its extensions, or one of a Data Package's resources — named by
  *     its location, resource name or Darwin Core row type; empty to let the ingestor choose
+ * @param datasetView optional path to a standalone dataset view JSON file
  */
 public record AppConfig(
-        Path useCaseXml,
-        List<Path> rdfDefinitions,
-        Path datasetPath,
-        String useCaseId,
-        List<String> implementationPackages,
-        int threadCount,
-        boolean dedupEnabled,
-        RecordFilterSpec recordFilter,
-        String datasetTable) {
+		Path useCaseXml,
+		List<Path> rdfDefinitions,
+		Path datasetPath,
+		String useCaseId,
+		List<String> implementationPackages,
+		int threadCount,
+		boolean dedupEnabled,
+		RecordFilterSpec recordFilter,
+		String datasetTable,
+		String datasetView) {
 
 	/**
 	 * Creates a configuration with no record filters.
@@ -80,7 +82,7 @@ public AppConfig(
 			int threadCount,
 			boolean dedupEnabled) {
 		this(useCaseXml, rdfDefinitions, datasetPath, useCaseId, implementationPackages, threadCount, dedupEnabled,
-				RecordFilterSpec.empty(), "");
+				RecordFilterSpec.empty(), "", "");
 	}
 
 	/**
@@ -105,7 +107,24 @@ public AppConfig(
 			boolean dedupEnabled,
 			RecordFilterSpec recordFilter) {
 		this(useCaseXml, rdfDefinitions, datasetPath, useCaseId, implementationPackages, threadCount, dedupEnabled,
-				recordFilter, "");
+				recordFilter, "", "");
+	}
+
+	/**
+	 * Creates a configuration with explicit table selection and no dataset view.
+	 */
+	public AppConfig(
+			Path useCaseXml,
+			List<Path> rdfDefinitions,
+			Path datasetPath,
+			String useCaseId,
+			List<String> implementationPackages,
+			int threadCount,
+			boolean dedupEnabled,
+			RecordFilterSpec recordFilter,
+			String datasetTable) {
+		this(useCaseXml, rdfDefinitions, datasetPath, useCaseId, implementationPackages, threadCount, dedupEnabled,
+				recordFilter, datasetTable, "");
 	}
 
 	/**
@@ -115,5 +134,6 @@ public AppConfig(
 	public AppConfig {
 		recordFilter = recordFilter == null ? RecordFilterSpec.empty() : recordFilter;
 		datasetTable = datasetTable == null ? "" : datasetTable.trim();
+		datasetView = datasetView == null ? "" : datasetView.trim();
 	}
 }

src/main/java/org/filteredpush/bdq_workbench/app/BdqWorkbenchApplication.java

@@ -191,7 +191,8 @@ private static AppConfig resolveDefaultUseCase(AppConfig config) {
                 config.threadCount(),
                 config.dedupEnabled(),
                 config.recordFilter(),
-                config.datasetTable());
+                config.datasetTable(),
+                config.datasetView());
     }
 
     /**
@@ -248,6 +249,7 @@ private static ParseResult parseArguments(String[] args) {
             String key = switch (arg) {
                 case "--dataset" -> "bdq.dataset";
                 case "--dataset-table" -> "bdq.dataset.table";
+                case "--dataset-view" -> "bdq.dataset.view";
                 case "--usecase-file" -> "bdq.usecase.file";
                 case "--rdf-files" -> "bdq.rdf.files";
                 case "--usecase-id" -> "bdq.usecase.id";
@@ -290,6 +292,7 @@ private static void renderUsage(PrintStream out) {
         out.println("  --dataset-table <name>         Which table of the dataset to run against, named by");
         out.println("                                 location, resource name or Darwin Core row type");
         out.println("                                 (default: the best-ranked table the dataset offers)");
+        out.println("  --dataset-view <path>          Standalone dataset view JSON file");
         out.println("  --usecase-file <path>          Use case XML file");
         out.println("  --rdf-files <paths>            Comma-separated RDF/OWL files");
         out.println("  --usecase-id <id>              Optional use case identifier");