test: prepare Chinook database for installation acceptance without Evidence

2026-09-28 18:25:33 +02:00
parent 931ac2fad4
commit c3c9f509bf
3 changed files with 183 additions and 0 deletions
@@ -0,0 +1,112 @@
+# First installation acceptance fixture: Chinook without Evidence
+
+Decision agreed on 2026-09-28: the first installer acceptance may use one ad hoc
+workspace and a downloadable local database without Evidence. The three curated
+example databases remain a separate deferred subproject.
+
+Use [Chinook v1.4.5](https://github.com/lerocha/chinook-database/releases/tag/v1.4.5),
+the sample digital music store. The upstream PostgreSQL SQL asset contains both
+schema and data: 11 related tables for artists, albums, tracks, customers, employees,
+invoices and playlists. The source is licensed under
+[MIT](https://github.com/lerocha/chinook-database/blob/master/LICENSE.md).
+This fixture does not supply Evidence or claim that SQL schema information is Evidence.
+It uses native PostgreSQL DDL/data, so SQLite type conversion is not involved.
+
+## Prepare the independent test database
+
+Run in Ubuntu WSL2 with Docker Desktop integration, or in a Linux/macOS Bash
+terminal for a preliminary check. Docker, curl and OpenSSL must be available.
+The first formal host acceptance remains Windows/WSL2.
+
+The helper below is in the ThothII repository for maintainers/testers; it is not
+yet included in the downloadable operator bundle. It provisions only the test DWH,
+which is a separate container from the installation's PostgreSQL Metadata Catalog.
+
+```bash
+cd /path/to/ThothII
+bash scripts/prepare-chinook-test.sh "$HOME/thothii-chinook-test"
+```
+
+Use a new directory outside any workspace repository. The helper pins the upstream
+SQL version and checksum, creates private random passwords, starts PostgreSQL,
+imports schema/data, and creates `thoth_reader` with SELECT privileges. Passwords
+remain in the private directory, not in a workspace YAML or this repository.
+An existing directory or container is refused; the helper never resets it.
+An interrupted preparation leaves its private logs/container available for diagnosis.
+Do not rerun the upstream import manually against another database: its opening
+statements drop and recreate `chinook`.
+
+Default container: `thothii-test-chinook`. Host endpoint: `127.0.0.1:55432`.
+Override names/port before the command if needed:
+
+```bash
+CHINOOK_TEST_CONTAINER=my-chinook CHINOOK_TEST_PORT=55433 \
+  bash scripts/prepare-chinook-test.sh "$HOME/my-chinook-test"
+```
+
+Expected import counts: 11 tables, 3,503 tracks, 412 invoices and 2,240 invoice lines.
+The SQL download is 600,200 bytes. Its SHA-256 is
+`e3fde5c1a5b51a2a91429a702c9ca6e69ba56e6c7f5e112724d70c3d03db695e`.
+
+Stop/start retains the database:
+
+```bash
+docker stop thothii-test-chinook
+docker start thothii-test-chinook
+```
+
+Only when deliberately discarding this test database, `docker rm -f -v
+thothii-test-chinook` removes the container and its anonymous data volume. Private
+files in the preparation directory are separate and remain until removed explicitly.
+
+## Prepare the workspace documents
+
+Using the native bundle, keep `tht` beside `tht-workspace-documents` and run:
+
+```bash
+/path/to/bundle/bin/tht workspace prepare \
+  --directory "$HOME/thothii-workspaces-test" \
+  --id chinook-test --name "Chinook installation test" --language it
+/path/to/bundle/bin/tht workspace validate \
+  --directory "$HOME/thothii-workspaces-test"
+```
+
+The generated workspace has Evidence absent. Keep that configuration; no fake
+Evidence document or credential should be added merely to satisfy installation.
+
+The later installation-local binding must select PostgreSQL, database `chinook`,
+schema `public`, user `thoth_reader`, and reference the private `reader-password`
+file. Do not use the PostgreSQL administrator as the ThothII data source account.
+The host endpoint above is for host-side tools: `127.0.0.1` inside ThothII core
+would refer to core itself. At integration, configure and verify connectivity from
+both the preflight process and the core container; do not copy the host endpoint
+unchanged into a runtime binding. That integration belongs to the remaining
+installer/binding tickets and is not established by successful import here.
+
+## Acceptance scope
+
+After the remaining installer increments are available, verify prepared documents,
+non-interactive setup using published images, database connection, schema sync,
+required preprocessing/readiness and a real human-reviewed question. Then verify
+stop/start preserves application state. These checks do not validate Evidence
+ingestion, retrieval or interpretation; record those as not exercised for this fixture.
+
+Suggested practice questions, without target SQL:
+
+- Which five artists have the most tracks in the catalogue?
+- Which countries have the largest total invoice amounts?
+- Which customers bought tracks from more than three genres?
+
+These are practice prompts, not benchmark scores or a substitute for human review.
+Windows/WSL2 acceptance is followed by Omarchy and macOS in separate steps.
+
+## Preliminary verification, 2026-09-28
+
+The helper imported the pinned SQL into a fresh Linux amd64 PostgreSQL container
+on the macOS development host. Counts matched the values above. A real TCP
+connection using the generated `thoth_reader` password read the data;
+`default_transaction_read_only` was `on`, and an UPDATE without matching rows
+was still rejected with SQLSTATE `42501` even inside `BEGIN READ WRITE`.
+Native workspace preparation and JSON validation reported `ok: true` and
+`evidence: absent`, explicitly deferring Catalog binding, connectivity and runtime
+preprocessing. These are fixture checks, not Windows or full-installer acceptance.