Pipeline: Add LLM and mocked user generation to the pipeline (#230)

docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md

@@ -13,6 +13,7 @@ low-resource language failures.
 - [Model Bias and Language Quality](#model-bias-and-language-quality)
 - [Western and Eurocentric Lens](#western-and-eurocentric-lens)
 - [Wikipedia Enrichment](#wikipedia-enrichment)
+- [Names-by-Country Dataset](#names-by-country-dataset)
 - [The "Avoid AI Phrases" Prompt Instruction](#the-avoid-ai-phrases-prompt-instruction)
 - [Known Issues](#known-issues)
   - [Hallucinated Brewing Techniques](#hallucinated-brewing-techniques)
@@ -91,6 +92,33 @@ generated descriptions.
 
 ---
 
+## Names-by-Country Dataset
+
+`tooling/pipeline/forenames-by-country.json` and `surnames-by-country.json`
+(used to sample a `Name` per ISO 3166-1 country code for user generation) are
+vendored verbatim, unmodified, from
+[sigpwned/popular-names-by-country-dataset](https://github.com/sigpwned/popular-names-by-country-dataset)
+(the `common-forenames-by-country.json` / `common-surnames-by-country.json`
+release assets), released under **CC0** (public domain). That dataset's own
+forename/surname lists are pulled from Wikipedia's "Lists of most common
+surnames" and "List of most popular given names" as of the week of
+2023-07-08 — see that project's README for full provenance. Names are not
+LLM-generated; this is curated fixture data per ROADMAP.md §2. Per-forename
+gender from the source data is preserved through to the sampled `Name`
+(rather than discarded during loading) so it's available for gender-aware
+persona/bio generation later.
+
+The full multinational dataset is kept as-is (106 countries for forenames,
+75 for surnames) rather than trimmed to `locations.json`'s current country
+list, so it doesn't need re-sourcing if more countries are added later.
+`SampleName()` (a free helper in `generate_users.cc`) returns no result for
+a country present in neither file; of the countries in `locations.json`,
+that's currently `KE`, `SE`, `SG`, `TH`, `VN`, and `ZA` — `GenerateUsers`
+skips cities in those countries the same way brewery generation skips
+cities whose enrichment lookup fails.
+
+---
+
 ## The "Avoid AI Phrases" Prompt Instruction
 
 The system prompt instructs the model to avoid common AI-generated phrasing

docs/pipeline/README.md

@@ -1,8 +1,9 @@
 # Biergarten Pipeline
 
 A C++20 command-line pipeline that samples city records from local JSON,
-enriches each with Wikipedia context, and generates bilingual brewery names and
-descriptions via a local GGUF model or a deterministic mock.
+enriches each with Wikipedia context, and generates bilingual brewery names
+and descriptions plus locale-grounded user profiles via a local GGUF model or
+a deterministic mock.
 
 > **This pipeline produces AI-generated data.** It is not a source of truth for
 > brewing techniques, cultural representation, or local-language accuracy. See
@@ -45,6 +46,7 @@ step.
 | Beer reviews and ratings         | Stable brewery fixtures with enough context to anchor review pages |
 | Social follow relationships      | Repeatable brewery entities for feeds, follows, and saved lists    |
 | Geospatial brewery experiences   | Latitude, longitude, and country-level metadata                    |
+| User accounts and profiles       | Locale-grounded names, bios, and an auth-ready email/date-of-birth pair for seeding real accounts |
 
 ---
 
@@ -218,35 +220,46 @@ environment variables listed above to match your run.
 
 ### Pipeline Stages
 
-| Stage    | Implementation                                                                                                                          |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Load     | `JsonLoader::LoadLocations()` reads `locations.json` into typed `Location` records.                                                     |
-| Sample   | `BiergartenPipelineOrchestrator::QueryCitiesWithCountries()` samples `--location-count` locations per run (default `10`).               |
-| Enrich   | `WikipediaEnrichmentService` fetches brewing and beer-related context. Keeps going when a lookup fails. `--mocked` runs use `MockEnrichmentService` instead and skip Wikipedia entirely. |
-| Generate | `MockGenerator` or `LlamaGenerator` produces brewery names and descriptions in English and the local language.                          |
-| Store    | `SqliteExportService` writes each successful brewery into a fresh dated `.sqlite` database with normalized location and brewery tables. |
-| Log      | `spdlog` writes results and warnings to the console.                                                                                    |
+| Stage           | Implementation                                                                                                                          |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Load            | `ICuratedDataService` (`CuratedJsonDataService`) reads `locations.json`, `personas.json`, `forenames-by-country.json`, and `surnames-by-country.json` (paths supplied via a `CuratedDataFilePaths` DTO at construction) into typed records, caching each after its first load. `--mocked` runs use `MockCuratedDataService`'s fixed in-memory dataset instead. |
+| Sample          | `BiergartenPipelineOrchestrator::QueryCitiesWithCountries()` samples `--location-count` locations per run (default `10`).               |
+| Enrich          | `WikipediaEnrichmentService` fetches brewing and beer-related context. Keeps going when a lookup fails. `--mocked` runs use `MockEnrichmentService` instead and skip Wikipedia entirely. |
+| Generate Users  | `GenerateUsers()` samples a persona and a forename/surname pair per enriched city (skipping countries with no name data), then `MockGenerator` or `LlamaGenerator` produces a username, bio, and activity weight around the sampled name. |
+| Generate Breweries | `MockGenerator` or `LlamaGenerator` produces brewery names and descriptions in English and the local language.                       |
+| Store           | `SqliteExportService` writes each successful user and brewery into a fresh dated `.sqlite` database with normalized `locations`, `users`, and `breweries` tables. |
+| Log             | `spdlog` writes results and warnings to the console.                                                                                    |
 
-If enrichment or generation fails for a city, that city is skipped and the
-pipeline continues.
+If name sampling, enrichment, or generation fails for a city, that city is
+skipped and the pipeline continues. `GenerateUsers()` runs before
+`GenerateBreweries()` in `BiergartenPipelineOrchestrator::Run()`.
 
 ### Key Components
 
 - `src/main.cc` — argument parsing and Boost.DI composition root.
-- `JsonLoader` — validates curated location input.
+- `CuratedJsonDataService` — implements `ICuratedDataService`; takes a
+  `CuratedDataFilePaths` DTO (locations/personas/forenames/surnames paths) in
+  its constructor, then parses and validates curated location, persona, and
+  forename/surname JSON, memoizing each result after its first load on a
+  given instance. `MockCuratedDataService` is the in-memory substitute (4
+  fixed locations, 3 personas, and name data for `US`/`DE`/`FR`/`BE`) used in
+  `--mocked` runs.
 - `WikipediaEnrichmentService` — queries Wikipedia extracts, caches results,
   returns empty context on failure. `MockEnrichmentService` is the no-op
   substitute used in `--mocked` runs.
-- `LlamaGenerator` — formats prompts for Gemma 4, validates JSON output, retries
-  malformed responses up to three times with corrective feedback in the
-  retry prompt. The token budget is fixed across attempts; it is not raised
-  automatically on truncation.
-- `MockGenerator` — stable hash-based output so the same city input always
-  produces the same brewery.
-- `SqliteExportService` — creates a dated SQLite file per run and persists each
-  successful brewery into normalized tables.
+- `LlamaGenerator` — formats prompts for Gemma 4, validates JSON output for
+  both `GenerateBrewery` and `GenerateUser`, retries malformed responses up
+  to three times with corrective feedback in the retry prompt. The token
+  budget is fixed across attempts; it is not raised automatically on
+  truncation.
+- `MockGenerator` — stable hash-based output so the same city/persona/name
+  input always produces the same brewery or user.
+- `SqliteExportService` — creates a dated SQLite file per run and persists
+  each successful user and brewery into normalized tables.
 - Brewery payloads include English and local-language name and description
-  fields.
+  fields. User payloads carry a sampled first/last name and gender, an
+  LLM-generated username/bio/activity weight, and a programmatically
+  generated (not LLM-authored) unique email and date of birth.
 
 ### Runtime Behaviour
 
@@ -266,6 +279,18 @@ valid output on the first pass; the retry path is kept for resilience.
 `MockGenerator` uses stable hashes for repeatable output in demos and Storybook
 runs.
 
+`CuratedJsonDataService` memoizes each of `LoadLocations()`, `LoadPersonas()`,
+`LoadForenamesByCountry()`, and `LoadSurnamesByCountry()` independently the
+first time each is called, since `BiergartenPipelineOrchestrator` owns a
+single `ICuratedDataService` instance for the whole run — later calls return
+the cached result instead of re-parsing. 
+
+`GenerateUsers()` samples a forename/surname pair per city via `SampleName()`,
+keyed by the city's ISO 3166-1 code. Countries present in `locations.json`
+but absent from either name fixture (currently `KE`, `SE`, `SG`, `TH`, `VN`,
+`ZA`) are skipped, the same way a failed enrichment or generation call skips
+a city — see ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section.
+
 ### Process Flow - Activity Diagram
 
 ![An activity diagram](./diagrams/current/output/activity.svg)
@@ -278,9 +303,10 @@ runs.
 
 ## Generated Output
 
-Each successful run stores a `GeneratedBrewery` pair with the source location
-and a `BreweryResult` payload. The same generated records are also written to a
-fresh SQLite export file named with the current UTC timestamp.
+Each successful run stores a `BreweryRecord` pair with the source location
+and a `BreweryResult` payload, and a `UserRecord` pair with the source
+location and a `UserResult` payload. The same generated records are also
+written to a fresh SQLite export file named with the current UTC timestamp.
 
 | Field               | Meaning                                    |
 | ------------------- | ------------------------------------------ |
@@ -289,6 +315,17 @@ fresh SQLite export file named with the current UTC timestamp.
 | `name_local`        | Brewery name in the local language.        |
 | `description_local` | Brewery description in the local language. |
 
+| Field             | Meaning                                                          |
+| ----------------- | ----------------------------------------------------------------- |
+| `first_name`      | Sampled forename, copied from the curated name data (not LLM-invented). |
+| `last_name`       | Sampled surname, copied from the curated name data (not LLM-invented).  |
+| `gender`          | Gender associated with the sampled forename in the source dataset. |
+| `username`        | LLM-generated handle.                                            |
+| `bio`             | LLM-generated short biography.                                   |
+| `activity_weight` | Relative check-in/activity weight, reserved for a future J-curve activity profile. |
+| `email`           | Unique `@thebiergarten.app` address, generated programmatically from the sampled name. |
+| `date_of_birth`   | Randomized date of birth (age 19-48), generated programmatically. |
+
 The log dump also includes city, country, state or province, ISO subdivision
 code, latitude, and longitude for each entry.
 
@@ -367,11 +404,17 @@ Silicon; CUDA or HIP/ROCm is detected on Linux when the toolkit is present.
 ## Fixture Strategy
 
 - `--mocked` for stable fixtures, repeatable screenshots, and Storybook runs.
+  `MockCuratedDataService` swaps in for `CuratedJsonDataService`, so no
+  fixture files need to be present on disk.
 - `--model` when geographically grounded content matters for demos.
 - Keep `locations.json` structured enough to support discovery and future
   filtering.
-- Treat SQLite output as seed material for the app's brewery domain, not
-  production data.
+- `personas.json`, `forenames-by-country.json`, and
+  `surnames-by-country.json` are curated/vendored fixture data, not
+  LLM-generated — see ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset
+  section for provenance.
+- Treat SQLite output as seed material for the app's brewery and user
+  domains, not production data.
 
 ---
 
@@ -382,6 +425,9 @@ Silicon; CUDA or HIP/ROCm is detected on Linux when the toolkit is present.
 | `tooling/pipeline/includes/`           | Public headers and shared models.                  |
 | `tooling/pipeline/src/`                | Implementation files.                              |
 | `tooling/pipeline/locations.json`      | Curated city input copied into the build tree.     |
+| `tooling/pipeline/personas.json`       | Curated user persona archetypes copied into the build tree. |
+| `tooling/pipeline/forenames-by-country.json` | Vendored (CC0) forename data by ISO 3166-1 country code. |
+| `tooling/pipeline/surnames-by-country.json`  | Vendored (CC0) surname data by ISO 3166-1 country code. |
 | `tooling/pipeline/prompts/`            | System prompts used by the model-backed path.      |
 | `tooling/pipeline/runpod/`             | Dockerfile, launcher, and RunPod pod template.      |
 | `docs/pipeline/diagrams/`              | Architecture and pipeline diagrams.                |
@@ -396,6 +442,9 @@ Paths below are relative to `tooling/pipeline/`.
 - `src/main.cc` — argument parsing and DI composition root.
 - `src/biergarten_pipeline_orchestrator/` — orchestration, sampling, logging,
   and export.
+- `src/services/curated_data/` — `CuratedJsonDataService`, the file-backed
+  `ICuratedDataService`, and `MockCuratedDataService`, the in-memory
+  `ICuratedDataService` used in `--mocked` runs.
 - `src/services/enrichment/wikipedia/` — enrichment service and cache.
 - `src/services/sqlite/` — SQLite export implementation.
 - `src/data_generation/llama/` — local inference, prompt loading, output
@@ -407,11 +456,12 @@ Paths below are relative to `tooling/pipeline/`.
 
 ## Next Steps
 
-The pipeline currently produces city-aware brewery records and dated SQLite
-exports. The next passes add additional fixture types so the app can exercise
-the full brewery domain without live data. For the detailed engineering
-breakdown of what's needed to reach the architecture in
-[`diagrams/planned/`](./diagrams/planned/), see [ROADMAP.md](./ROADMAP.md).
+The pipeline currently produces city-aware brewery and user records and
+dated SQLite exports. The next passes add additional fixture types so the
+app can exercise the full brewery and social domains without live data. For
+the detailed engineering breakdown of what's needed to reach the
+architecture in [`diagrams/planned/`](./diagrams/planned/), see
+[ROADMAP.md](./ROADMAP.md).
 
 ### Testing — Very High Priority
 
@@ -433,12 +483,6 @@ Generate catalog entries with style, ABV, IBU, color, aroma notes, and food
 pairing hints. Link beers back to breweries and cities. Keep style coverage wide
 enough to exercise search, sort, and category filters.
 
-### User Generation
-
-Generate user profiles with stable names, bios, locale hints, and preference
-signals. Include stable IDs for downstream fixture joins. Keep output
-deterministic for screenshots while allowing larger randomized batches.
-
 ### Check-In System
 
 Produce timestamped check-in events between users and breweries. Use a J-curve

docs/pipeline/ROADMAP.md

@@ -33,28 +33,93 @@ architecture needs.
 - [ ] Add `BeerResult`, `CheckinResult`, `RatingResult` result payloads.
 - [ ] Add `GenerationMetadata` (`generation_id`, `generated_time`,
       `context_provided`, `generated_with`).
-- [ ] Add `activity_weight` to `UserResult` (currently just `username`,
-      `bio`).
+- [x] Add `first_name`, `last_name`, `gender`, and `activity_weight` to
+      `UserResult` (currently just `username`, `bio`). `first_name`/
+      `last_name`/`gender` are copied from the sampled `Name` (see below),
+      not LLM-invented.
+- [x] Add `Name` (`first_name`, `last_name`, `gender`) — the sampled result
+      handed to `DataGenerator::GenerateUser`. Add `ForenameEntry` (`name`,
+      `gender`). Landed as a flatter shape than originally planned here: no
+      `NamesByCountry` wrapper class. `curated_data_service.h` instead
+      declares `ForenameList = std::vector<ForenameEntry>` and
+      `SurnameList = std::vector<std::string>`, and
+      `ICuratedDataService` exposes two maps keyed by ISO 3166-1 code —
+      `ForenamesByCountryMap = unordered_map<string, ForenameList>` and
+      `SurnamesByCountryMap = unordered_map<string, SurnameList>` —
+      directly (see §2). Sampling is
+      a free function, `SampleName(forenames_by_country,
+      surnames_by_country, iso3166_1, rng)`, in
+      `generate_users.cc`'s anonymous namespace, not a method on a class.
+      Pairing a forename with a surname happens at sample time so gender
+      (present per-forename in the source data) is never discarded the way a
+      pre-flattened `{first_name, last_name}` list would lose it; see §2.
 - [ ] Extend `GeneratedBrewery` with `brewery_id`, `context_completeness`,
       `metadata` (currently just `{location, brewery}`).
-- [ ] Add `GeneratedBeer`, `GeneratedUser`, `GeneratedCheckin`,
-      `GeneratedRating`, `GeneratedFollow` aggregate structs.
-- [ ] Add `UserPersona` (`name`, `description`, `style_affinities`).
+- [ ] Add `GeneratedBeer`, `GeneratedCheckin`, `GeneratedRating`,
+      `GeneratedFollow` aggregate structs.
+- [x] Add `UserRecord` (`location`, `user : UserResult`, `email`,
+      `date_of_birth`) as the current stand-in for the planned
+      `GeneratedUser` — `email` and `date_of_birth` are programmatically
+      generated by the orchestrator, never LLM-authored, so a downstream
+      auth-account seeding consumer can register real accounts from the
+      pipeline's SQLite export. No `password`, `user_id`, or `metadata`
+      field yet, matching `BreweryRecord`'s equally pre-`metadata` shape.
+      Already wired into `IExportService`/`SqliteExportService`: a `users`
+      table exists and `GenerateUsers()` exports each successful record via
+      `ProcessRecord(const UserRecord&)` (see §5) in addition to logging and
+      holding `generated_users_` in memory. Still missing vs. the planned
+      `GeneratedUser`: `user_id`, `password`, and `metadata`.
+- [x] Add `UserPersona` (`name`, `description`, `style_affinities`).
 
 ## 2. Data Preloading
 
-`tooling/pipeline/includes/json_handling/`, fixture files.
+`tooling/pipeline/includes/services/curated_data/`, fixture files.
 
-- [ ] Extract a `DataPreloader` interface; have `JsonLoader` implement it
-      instead of exposing only a static `LoadLocations()`.
+- [x] Extract an interface; have `CuratedJsonDataService` implement it.
+      Landed as `ICuratedDataService`
+      (`services/curated_data/curated_data_service.h`), not `DataPreloader`
+      — `LoadLocations()`, `LoadPersonas()`, `LoadForenamesByCountry()`, and
+      `LoadSurnamesByCountry()` are all virtual methods returning `const&`
+      and take no arguments. `CuratedJsonDataService`
+      (`services/curated_data/curated_json_data_service.h`, originally
+      landed as `JsonLoader` under `json_handling/` before being renamed and
+      moved) takes a `CuratedDataFilePaths` DTO (`locations_path`,
+      `personas_path`, `forenames_path`, `surnames_path`) in its
+      constructor rather than a path per `Load*()` call, and memoizes each
+      result in a private `cache` struct (`locations`, `personas`,
+      `forenames_by_country`, `surnames_by_country`), so a second call on
+      the same instance returns the cached result instead of re-parsing —
+      safe because `CuratedJsonDataService` outlives every call site (owned
+      by `BiergartenPipelineOrchestrator` via
+      `unique_ptr<ICuratedDataService>` for the whole run). `main.cc`'s DI
+      injector also gained a `MockCuratedDataService` (fixed in-memory
+      data: 4 locations across `US`/`DE`/`FR`/`BE`, 3 personas, and
+      matching forename/surname sets for those four countries), bound in
+      place of `CuratedJsonDataService` under `--mocked`, mirroring the
+      existing `MockEnrichmentService`/`MockGenerator` pattern.
 - [ ] Add `LoadBeerStyles()`. `beer-styles.json` already exists in the repo
       and is already copied into the Docker image
       (`runpod/Dockerfile`), but no loader reads it yet, and the native
       CMake build doesn't copy it into `build/` at all — `CMakeLists.txt`'s
       "Runtime Assets" step only copies `locations.json` and `prompts/`.
-- [ ] Add `LoadPersonas()` and author `personas.json` (doesn't exist yet).
-- [ ] Add `LoadNamesByCountry()` and author `names-by-country.json` (doesn't
-      exist yet).
+- [x] Add `LoadPersonas()` and author `personas.json` (doesn't exist yet).
+- [x] Add name-by-country loading, parsing
+      `tooling/pipeline/forenames-by-country.json` and
+      `surnames-by-country.json`. Landed as two separate methods —
+      `LoadForenamesByCountry()` and `LoadSurnamesByCountry()` — each
+      returning a flat `ForenamesByCountryMap` / `SurnamesByCountryMap`
+      (aliases for `unordered_map<string, ForenameList>` /
+      `unordered_map<string, SurnameList>`) keyed by ISO 3166-1 code, rather
+      than one combined `LoadNamesByCountry() : NamesByCountry` call. Both
+      files are vendored verbatim (unmodified,
+      full multinational coverage) from
+      `sigpwned/popular-names-by-country-dataset` (CC0) — see
+      ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section for
+      provenance. Deliberately not pre-paired or filtered down to just the
+      countries in `locations.json`: keeping the source shape (including
+      per-forename gender) intact means the loader can support more
+      countries later, or gender-aware persona/bio generation, without
+      re-sourcing data.
 
 ## 3. Policy / Strategy Layer
 
@@ -83,10 +148,14 @@ Entirely new — no `includes/policy/` (or equivalent) directory exists today.
 - [ ] Extend the `DataGenerator` interface with `GenerateBeer`,
       `GenerateCheckin`, `GenerateRating` (today: only `GenerateBrewery` and
       `GenerateUser`).
-- [ ] Implement `LlamaGenerator::GenerateUser` for real. It currently
-      returns a hardcoded `{"test_user", "This is a test user profile from
-    {locale}."}` regardless of input — see the `// TODO` at the top of
-      `src/data_generation/llama/generate_user.cc`.
+- [x] Implement `LlamaGenerator::GenerateUser` for real, with a retry loop
+      mirroring `GenerateBrewery` (GBNF grammar, `ValidateUserJson`, up to 3
+      attempts with corrective feedback) and a new
+      `prompts/USER_GENERATION.md`. Changed the `DataGenerator::GenerateUser`
+      signature to
+      `(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult`,
+      matching what the activity diagram actually passes. `MockGenerator::GenerateUser`
+      updated to match the new signature too.
 - [ ] Implement `MockGenerator::GenerateBeer` / `GenerateCheckin` /
       `GenerateRating`.
 - [ ] Add `IPromptFormatter::ExpectedArchitecture()` and
@@ -100,12 +169,19 @@ Entirely new — no `includes/policy/` (or equivalent) directory exists today.
 
 `tooling/pipeline/includes/services/database/`, `src/services/sqlite/`.
 
-- [ ] Extend `IExportService` with `ProcessBeer`, `ProcessUser`,
-      `ProcessCheckin`, `ProcessRating`, `ProcessFollow` (today only
-      `ProcessRecord(const GeneratedBrewery&)` exists).
-- [ ] Add `beers`, `users`, `checkins`, `ratings`, `follows` tables to
-      `SqliteExportService::InitializeSchema()` — see
-      `kCreateLocationsTableSql` / `kCreateBreweriesTableSql` in
+- [x] `IExportService::ProcessRecord(const UserRecord&)` and
+      `SqliteExportService`'s `users` table (see
+      `kCreateUsersTableSql` / `kInsertUserSql` in
+      `includes/services/database/sqlite_statement_helpers.h`) are
+      implemented — `GenerateUsers()` exports every successful user
+      alongside its resolved `location_id`.
+- [ ] Extend `IExportService` with `ProcessBeer`, `ProcessCheckin`,
+      `ProcessRating`, `ProcessFollow` (today `ProcessRecord(const
+      BreweryRecord&)` and `ProcessRecord(const UserRecord&)` exist).
+- [ ] Add `beers`, `checkins`, `ratings`, `follows` tables to
+      `SqliteExportService::InitializeSchema()` (`locations`, `breweries`,
+      and `users` already exist) — see `kCreateLocationsTableSql` /
+      `kCreateBreweriesTableSql` / `kCreateUsersTableSql` in
       `includes/services/database/sqlite_statement_helpers.h` for the
       existing pattern to follow.
 - [ ] Add a `brewery_cache_` alongside the existing `location_cache_`, and
@@ -151,7 +227,8 @@ Entirely new — no `includes/policy/` (or equivalent) directory exists today.
 
 ## 8. Fixtures / Build
 
-- [ ] Author `personas.json` and `names-by-country.json` (see §2).
+- [x] Author `personas.json`, `forenames-by-country.json`, and
+      `surnames-by-country.json` (see §2).
 - [ ] Fix the `beer-styles.json` build-tree gap: add it to the "Runtime
       Assets" `configure_file` step in `CMakeLists.txt` so native builds and
       the Docker image agree on what's available at runtime.

docs/pipeline/diagrams/current/activity.puml

@@ -93,6 +93,77 @@ while (For each sampled Location?) is (Remaining cities)
   endif
 endwhile (Done)
 
+|#EAF0E8|BiergartenPipelineOrchestrator|
+:GenerateUsers(enriched_cities);
+
+|#E2EBDC|JsonLoader|
+:LoadPersonas("personas.json");
+:LoadForenamesByCountry("forenames-by-country.json");
+:LoadSurnamesByCountry("surnames-by-country.json");
+note right
+  Each call is cached after its first parse.
+  MockCuratedDataService (--mocked) returns a
+  fixed in-memory dataset instead and skips
+  these three JSON files entirely.
+end note
+
+|#EAF0E8|BiergartenPipelineOrchestrator|
+while (For each EnrichedCity?) is (Remaining cities)
+  :SampleName(forenames_by_country,\n  surnames_by_country, location.iso3166_1);
+  if (Names available for country?) then (no)
+    :Log warning, skip city;
+  else (yes)
+    :Sample UserPersona (uniform random);
+
+    |#E5EDE1|DataGenerator|
+    if (Generator Mode) then (MockGenerator)
+      :DeterministicHash & Format;
+    else (LlamaGenerator)
+      :prompt_directory_->Load("USER_GENERATION");
+      note right
+        Resolves to USER_GENERATION.md inside --prompt-dir.
+      end note
+      repeat
+        :Infer(system_prompt, user_prompt, max_tokens, kUserJsonGrammar);
+        :ValidateUserJson(raw, user);
+        if (Is JSON Valid?) then (yes)
+          break
+        else (no)
+          :Attempt++;
+          :Append validation error to retry prompt;
+        endif
+      repeat while (Attempt < 3?) is (yes)
+    endif
+
+    |#EAF0E8|BiergartenPipelineOrchestrator|
+    if (Generation successful?) then (yes)
+      :BuildEmail(name, used_email_local_parts);
+      :GenerateDateOfBirth(rng);
+      note right
+        email and date_of_birth are generated
+        programmatically, never LLM-authored.
+      end note
+
+      |#E0EAE0|SqliteExportService|
+      :ProcessRecord(UserRecord);
+      if (Location in cache?) then (yes)
+        :Reuse location_id;
+      else (no)
+        :Insert Location & Cache ID;
+      endif
+      :Insert User (FK: location_id);
+
+      if (Exception caught during insert?) then (yes)
+        |#EAF0E8|BiergartenPipelineOrchestrator|
+        :Log warning "SQLite export failed";
+      else (no)
+      endif
+    else (no)
+      :Log warning "Generation failed, skipping...";
+    endif
+  endif
+endwhile (Done)
+
 |#EAF0E8|BiergartenPipelineOrchestrator|
 :GenerateBreweries(enriched_cities);
 

docs/pipeline/diagrams/current/class.puml

@@ -30,11 +30,14 @@ class BiergartenPipelineOrchestrator {
   - context_service_ : std::unique_ptr<IEnrichmentService>
   - generator_ : std::unique_ptr<DataGenerator>
   - exporter_ : std::unique_ptr<IExportService>
+  - curated_data_service_ : std::unique_ptr<ICuratedDataService>
   - application_options_ : ApplicationOptions
-  - generated_breweries_ : std::vector<GeneratedBrewery>
+  - generated_breweries_ : std::vector<BreweryRecord>
+  - generated_users_ : std::vector<UserRecord>
   + Run() : bool
   - QueryCitiesWithCountries() : std::vector<Location>
   - GenerateBreweries(cities : std::span<const EnrichedCity>) : void
+  - GenerateUsers(cities : std::span<const EnrichedCity>) : void
   - LogResults() : void
 }
 
@@ -113,13 +116,14 @@ class HttpWebClient {
 
 interface DataGenerator <<interface>> {
   + GenerateBrewery(location : const Location&, region_context : const std::string&) : BreweryResult
-  + GenerateUser(locale : const std::string&) : UserResult
+  + GenerateUser(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult
 }
 
 class MockGenerator {
-  + GenerateBrewery(...) : BreweryResult
-  + GenerateUser(...) : UserResult
+  + GenerateBrewery(location : const Location&, region_context : const std::string&) : BreweryResult
+  + GenerateUser(city : const EnrichedCity&, persona : const UserPersona&, name : const Name&) : UserResult
   - DeterministicHash(location : const Location&) : size_t
+  - DeterministicHash(location : const Location&, persona : const UserPersona&, name : const Name&) : size_t
 }
 
 class LlamaGenerator {
@@ -153,13 +157,49 @@ class PromptDirectory {
   + Load(key : std::string_view) : std::string
 }
 
-class JsonLoader {
-  + {static} LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
+interface ICuratedDataService <<interface>> {
+  + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+  + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+  + LoadForenamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+  + LoadSurnamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
 }
 
+class JsonLoader {
+  - cache_ : cache
+  + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+  + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+  + LoadForenamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+  + LoadSurnamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
+}
+
+note right of JsonLoader
+  Each Load* method memoizes its result in
+  cache_ on first call; later calls on the
+  same instance return the cached value
+  without re-parsing.
+end note
+
+class MockCuratedDataService {
+  - locations_ : std::vector<Location>
+  - personas_ : std::vector<UserPersona>
+  - forenames_by_country_ : std::unordered_map<std::string, forename_list>
+  - surnames_by_country_ : std::unordered_map<std::string, surname_list>
+  + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+  + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+  + LoadForenamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+  + LoadSurnamesByCountry(filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
+}
+
+note right of MockCuratedDataService
+  Fixed 4-location / 3-persona dataset
+  (US, DE, FR, BE) used in --mocked runs;
+  filepath arguments are ignored.
+end note
+
 interface IExportService <<interface>> {
   + Initialize() : void
-  + ProcessRecord(brewery : const GeneratedBrewery&) : void
+  + ProcessRecord(brewery : const BreweryRecord&) : uint64_t
+  + ProcessRecord(user : const UserRecord&) : uint64_t
   + Finalize() : void
 }
 
@@ -167,15 +207,18 @@ class SqliteExportService {
   - date_time_provider_ : std::unique_ptr<IDateTimeProvider>
   - run_timestamp_utc_ : std::string
   - database_path_ : std::filesystem::path
-  - db_handle_ : sqlite3*
-  - insert_location_stmt_ : sqlite3_stmt*
-  - insert_brewery_stmt_ : sqlite3_stmt*
+  - db_handle_ : SqliteDatabaseHandle
+  - insert_location_stmt_ : SqliteStatementHandle
+  - insert_brewery_stmt_ : SqliteStatementHandle
+  - insert_user_stmt_ : SqliteStatementHandle
   - transaction_open_ : bool
   - location_cache_ : std::unordered_map<std::string, sqlite3_int64>
   + Initialize() : void
-  + ProcessRecord(brewery : const GeneratedBrewery&) : void
+  + ProcessRecord(brewery : const BreweryRecord&) : uint64_t
+  + ProcessRecord(user : const UserRecord&) : uint64_t
   + Finalize() : void
   - InitializeSchema() : void
+  - ResolveLocationId(location : const Location&) : sqlite3_int64
 }
 
 interface IDateTimeProvider <<interface>> {
@@ -191,6 +234,7 @@ BiergartenPipelineOrchestrator *-- ILogger : owns
 BiergartenPipelineOrchestrator *-- IEnrichmentService : owns
 BiergartenPipelineOrchestrator *-- DataGenerator : owns
 BiergartenPipelineOrchestrator *-- IExportService : owns
+BiergartenPipelineOrchestrator *-- ICuratedDataService : owns
 
 LogEntry *-- LogLevel
 LogEntry *-- PipelinePhase
@@ -215,7 +259,8 @@ LlamaGenerator *-- IPromptDirectory : uses
 IPromptFormatter <|.. Gemma4JinjaPromptFormatter : implements
 IPromptDirectory <|.. PromptDirectory : implements
 
-BiergartenPipelineOrchestrator ..> JsonLoader : uses
+ICuratedDataService <|.. JsonLoader : implements
+ICuratedDataService <|.. MockCuratedDataService : implements
 
 IExportService <|.. SqliteExportService : implements
 SqliteExportService *-- IDateTimeProvider : owns

docs/pipeline/diagrams/planned/activity.puml

@@ -43,10 +43,18 @@ fork again
   :EnrichmentService::PreWarmLocationCache(sampled_locations);
 end fork
 fork
-  :JsonLoader::LoadNamesByCountry("names-by-country.json");
+  :JsonLoader::LoadForenamesByCountry(\n  "forenames-by-country.json");
+fork again
+  :JsonLoader::LoadSurnamesByCountry(\n  "surnames-by-country.json");
 fork again
   :JsonLoader::LoadPersonas("personas.json");
 end fork
+note right
+  Each call is memoized after its first parse
+  (implemented today). MockCuratedDataService
+  returns a fixed in-memory dataset instead
+  under --mocked, skipping these JSON files.
+end note
 
 ' ═══════════════════════════════════════════
 ' PHASE 0 — USER GENERATION
@@ -82,11 +90,15 @@ fork again
       ibu_preference, checkin_weight.
     end note
 
-    :NamesByCountry::SampleName(\n  location.iso3166_1);
+    :SampleName(forenames_by_country,\n  surnames_by_country, location.iso3166_1, rng);
     note right
       Deterministic lookup -- no LLM involved.
-      Name selected from pre-keyed table
+      Free function (implemented today in
+      generate_users.cc), not a class method.
+      Name selected from pre-keyed maps
       and passed into the generation prompt.
+      Skips the city if either map has no
+      entry for iso3166_1.
     end note
 
     :GenerateUser(enriched_city, persona, sampled_name)\nvia DataGenerator;

docs/pipeline/diagrams/planned/class.puml

@@ -67,11 +67,50 @@ package "Domain: Models" {
   }
 
   class UserResult {
+    + first_name : std::string
+    + last_name : std::string
+    + gender : std::string
     + username : std::string
     + bio : std::string
     + activity_weight : float
   }
 
+  class Name {
+    + first_name : std::string
+    + last_name : std::string
+    + gender : std::string
+  }
+
+  class ForenameEntry {
+    + name : std::string
+    + gender : std::string
+  }
+
+  note right of ForenameEntry
+    forename_list = std::unordered_set<ForenameEntry>
+    surname_list = std::unordered_set<std::string>
+    (aliases declared in curated_data_service.h).
+    ICuratedDataService::LoadForenamesByCountry() /
+    LoadSurnamesByCountry() each return a flat
+    std::unordered_map<std::string, forename_list>
+    or <std::string, surname_list> keyed by ISO
+    3166-1 country code -- no NamesByCountry
+    wrapper class. SampleName(forenames_by_country,
+    surnames_by_country, iso3166_1, rng) is a free
+    function, not a method, so it can be called by
+    any per-city worker without owning the maps.
+    Sourced from popular-names-by-country-dataset
+    (CC0) -- see ETHICS-AND-KNOWN-ISSUES.md. Gender
+    is preserved per forename so it can be threaded
+    through to persona/bio generation later; surnames
+    carry no gender in the source data. Pairing
+    happens at sample time, not at fixture-authoring
+    time, so no information from the source dataset
+    is discarded up front.
+  end note
+
+  ForenameEntry ..> Name : SampleName() produces
+
   class CheckinResult {
     + checked_in_at : std::string
     + note : std::string
@@ -110,9 +149,20 @@ package "Domain: Models" {
     + user_id : uint64_t
     + location : Location
     + user : UserResult
+    + email : std::string
+    + date_of_birth : std::string
+    + password : std::string
     + metadata : GenerationMetadata
   }
 
+  note right of GeneratedUser
+    email, date_of_birth, and password are
+    programmatically generated by the orchestrator
+    (not LLM-authored) so a downstream auth-account
+    seeding consumer can register real accounts from
+    this export. See ROADMAP.md §1.
+  end note
+
   class GeneratedCheckin {
     + checkin_id : uint64_t
     + user_id : uint64_t
@@ -318,20 +368,43 @@ package "Infrastructure: Pipeline Channel" {
 
 package "Infrastructure: Data Preloading" {
 
-  interface DataPreloader <<interface>> {
-    + LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
-    + LoadBeerStyles(filepath : const std::filesystem::path&) : std::vector<BeerStyle>
-    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<Persona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+  interface ICuratedDataService <<interface>> {
+    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
+    + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+    + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+    + LoadSurnamesByCountry(surnames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
   }
 
   class JsonLoader {
-    + LoadLocations(filepath : const std::filesystem::path&) : std::vector<Location>
-    + LoadBeerStyles(filepath : const std::filesystem::path&) : std::vector<BeerStyle>
-    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<Persona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
+    + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+    + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+    + LoadSurnamesByCountry(surnames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
   }
 
+  note right of JsonLoader
+    Each Load* call is memoized after its first
+    parse -- implemented today, ahead of the rest
+    of this package (LoadBeerStyles is still planned).
+  end note
+
+  class MockCuratedDataService {
+    + LoadLocations(filepath : const std::filesystem::path&) : const std::vector<Location>&
+    + LoadBeerStyles(filepath : const std::filesystem::path&) : const std::vector<BeerStyle>&
+    + LoadPersonas(filepath : const std::filesystem::path&) : const std::vector<UserPersona>&
+    + LoadForenamesByCountry(forenames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, forename_list>&
+    + LoadSurnamesByCountry(surnames_filepath : const std::filesystem::path&) : const std::unordered_map<std::string, surname_list>&
+  }
+
+  note right of MockCuratedDataService
+    Fixed in-memory dataset used in --mocked mode,
+    implemented today for Locations/Personas/
+    Forenames/Surnames; would need a LoadBeerStyles
+    fixture too once that method is implemented.
+  end note
+
 }
 
 package "Infrastructure: Enrichment" {
@@ -380,7 +453,7 @@ package "Infrastructure: Data Generation" {
   interface DataGenerator <<interface>> {
     + GenerateBrewery(location : const Location&,\n  context : const LocationContext&) : BreweryResult
     + GenerateBeer(brewery_id : uint64_t,\n  location : const Location&,\n  context : const LocationContext&,\n  style : const BeerStyle&) : BeerResult
-    + GenerateUser(location : const Location&) : UserResult
+    + GenerateUser(city : const EnrichedCity&,\n  persona : const UserPersona&,\n  name : const Name&) : UserResult
     + GenerateCheckin(user : const GeneratedUser&,\n  brewery : const GeneratedBrewery&,\n  timestamp : const std::string&) : CheckinResult
     + GenerateRating(user : const GeneratedUser&,\n  beer : const GeneratedBeer&,\n  checkin_id : uint64_t) : RatingResult
   }
@@ -473,7 +546,7 @@ package "Infrastructure: Data Export" {
 }
 
 class BiergartenPipelineOrchestrator {
-  - preloader_ : std::unique_ptr<DataPreloader>
+  - curated_data_service_ : std::unique_ptr<ICuratedDataService>
   - enrichment_service_ : std::unique_ptr<EnrichmentService>
   - generator_ : std::unique_ptr<DataGenerator>
   - logger_ : std::unique_ptr<Logger>
@@ -501,7 +574,7 @@ class BiergartenPipelineOrchestrator {
 }
 
 ' --- Orchestration Aggregations (Services & Strategies) ---
-BiergartenPipelineOrchestrator *--  DataPreloader
+BiergartenPipelineOrchestrator *--  ICuratedDataService
 BiergartenPipelineOrchestrator *--  EnrichmentService
 BiergartenPipelineOrchestrator *--  DataGenerator
 BiergartenPipelineOrchestrator *--  ExportService
@@ -520,7 +593,8 @@ BiergartenPipelineOrchestrator *-- "0..*" GeneratedCheckin : checkin_pool_
 BiergartenPipelineOrchestrator *-- "0..*" GeneratedFollow  : follow_pool_
 
 ' --- Interfaces & Implementations ---
-DataPreloader                  <|.. JsonLoader
+ICuratedDataService            <|.. JsonLoader
+ICuratedDataService            <|.. MockCuratedDataService
 Logger                         <|.. PipelineLogger
 ContextStrategy                <|.. BreweryContextStrategy
 ContextStrategy                <|.. BeerContextStrategy