Run pipeling, update sqllite file

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.
+`NamesByCountry::SampleName()` 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/ROADMAP.md

@@ -33,28 +33,60 @@ 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`,
+- [x] Add `first_name`, `last_name`, `gender`, and `activity_weight` to
-      `bio`).
+      `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`) and a `NamesByCountry` class (not a bare typedef) that owns
+      two maps — `std::unordered_map<std::string, std::vector<ForenameEntry>>`
+      and `std::unordered_map<std::string, std::vector<std::string>>`, both
+      keyed by ISO 3166-1 code — and exposes `SampleName(iso3166_1, rng)`.
+      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
+      `LoadNamesByCountry()` below.
 - [ ] Extend `GeneratedBrewery` with `brewery_id`, `context_completeness`,
       `metadata` (currently just `{location, brewery}`).
-- [ ] Add `GeneratedBeer`, `GeneratedUser`, `GeneratedCheckin`,
+- [ ] Add `GeneratedBeer`, `GeneratedCheckin`, `GeneratedRating`,
-      `GeneratedRating`, `GeneratedFollow` aggregate structs.
+      `GeneratedFollow` aggregate structs.
-- [ ] Add `UserPersona` (`name`, `description`, `style_affinities`).
+- [x] Add `GeneratedUser` aggregate struct. Carries `email`, `date_of_birth`,
+      and `password` — programmatically generated by the orchestrator, never
+      LLM-authored — so a downstream auth-account seeding consumer (outside
+      this repo tree's docs) can register real accounts from the pipeline's
+      SQLite export. Skips `user_id`/`metadata` for now, matching
+      `GeneratedBrewery`'s current (pre-`brewery_id`/`metadata`) shape. Not
+      yet wired into `IExportService`/`SqliteExportService` — `GenerateUsers`
+      currently only logs and holds `generated_users_` in memory; no `users`
+      table exists in the SQLite export yet (see §5).
+- [x] Add `UserPersona` (`name`, `description`, `style_affinities`).
 
 ## 2. Data Preloading
 
 `tooling/pipeline/includes/json_handling/`, fixture files.
 
-- [ ] Extract a `DataPreloader` interface; have `JsonLoader` implement it
+- [ ] Extract a `DataPreloader` interface; have `JsonLoader` implement it.
-      instead of exposing only a static `LoadLocations()`.
+      `JsonLoader` now also exposes static `LoadPersonas()` and
+      `LoadNamesByCountry()` (see below), but as additional static methods,
+      not yet behind a formal interface.
 - [ ] 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).
+- [x] Add `LoadPersonas()` and author `personas.json` (doesn't exist yet).
-- [ ] Add `LoadNamesByCountry()` and author `names-by-country.json` (doesn't
+- [x] Add `LoadNamesByCountry(forenames_filepath, surnames_filepath)`,
-      exist yet).
+      parsing `tooling/pipeline/forenames-by-country.json` and
+      `surnames-by-country.json` into a `NamesByCountry`. 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 +115,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
+- [x] Implement `LlamaGenerator::GenerateUser` for real, with a retry loop
-      returns a hardcoded `{"test_user", "This is a test user profile from
+      mirroring `GenerateBrewery` (GBNF grammar, `ValidateUserJson`, up to 3
-    {locale}."}` regardless of input — see the `// TODO` at the top of
+      attempts with corrective feedback) and a new
-      `src/data_generation/llama/generate_user.cc`.
+      `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

docs/pipeline/diagrams/planned/activity.puml

@@ -43,7 +43,7 @@ fork again
   :EnrichmentService::PreWarmLocationCache(sampled_locations);
 end fork
 fork
-  :JsonLoader::LoadNamesByCountry("names-by-country.json");
+  :JsonLoader::LoadNamesByCountry(\n  "forenames-by-country.json",\n  "surnames-by-country.json");
 fork again
   :JsonLoader::LoadPersonas("personas.json");
 end fork

docs/pipeline/diagrams/planned/class.puml

@@ -67,11 +67,47 @@ 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
+  }
+
+  class NamesByCountry {
+    - forenames_by_country_ : std::unordered_map<std::string, std::vector<ForenameEntry>>
+    - surnames_by_country_ : std::unordered_map<std::string, std::vector<std::string>>
+    + SampleName(iso3166_1 : const std::string&,\n  rng : std::mt19937&) : std::optional<Name>
+  }
+
+  note right of NamesByCountry
+    Backed by two source-shaped maps,
+    keyed by ISO 3166-1 country code,
+    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
+
+  NamesByCountry *-- "0..*" ForenameEntry
+  NamesByCountry ..> Name : produces
+
   class CheckinResult {
     + checked_in_at : std::string
     + note : std::string
@@ -110,9 +146,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
@@ -321,15 +368,15 @@ 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>
+    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<UserPersona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+    + LoadNamesByCountry(forenames_filepath : const std::filesystem::path&,\n  surnames_filepath : const std::filesystem::path&) : NamesByCountry
   }
 
   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>
+    + LoadPersonas(filepath : const std::filesystem::path&) : std::vector<UserPersona>
-    + LoadNamesByCountry(filepath : const std::filesystem::path&) : NamesByCountry
+    + LoadNamesByCountry(forenames_filepath : const std::filesystem::path&,\n  surnames_filepath : const std::filesystem::path&) : NamesByCountry
   }
 
 }
@@ -380,7 +427,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
   }

tooling/pipeline-results-viewer/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

tooling/pipeline-results-viewer/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pipeline Results Viewer</title>
+  </head>
+  <body>
+    <div class="dialog" id="window">
+      <div class="dialog-header">
+        <p>Pipeline Results Viewer</p>
+      </div>
+      <div class="dialog-body">
+        <div class="field-group">
+          <label for="table-select">Table</label>
+          <select id="table-select"></select>
+        </div>
+        <p id="status"></p>
+        <div id="table-container"></div>
+      </div>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

tooling/pipeline-results-viewer/package-lock.json

@@ -0,0 +1,939 @@
+{
+  "name": "pipeline-results-viewer",
+  "version": "0.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pipeline-results-viewer",
+      "version": "0.0.0",
+      "dependencies": {
+        "95css": "^0.4.2",
+        "sql.js": "^1.14.1"
+      },
+      "devDependencies": {
+        "@types/sql.js": "^1.4.11",
+        "typescript": "^6.0.3",
+        "vite": "^8.0.12"
+      }
+    },
+    "node_modules/@emnapi/core": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
+      "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.2.1",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@emnapi/wasi-threads": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+      "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.5.tgz",
+      "integrity": "sha512-AWPoBRJ9tsnVhor4sjO7rkni+7p+2IAEFj6cx06UgP10jkQHqay/36uRV/bFkgrh18D9vb4cr8Q0Pthskgzy+Q==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tybys/wasm-util": "^0.10.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "peerDependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1"
+      }
+    },
+    "node_modules/@oxc-project/types": {
+      "version": "0.133.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.133.0.tgz",
+      "integrity": "sha512-KzkdCd6Uxqnf6l3HOw1xfatAlUURA0g14cvBYFyJ5SaNOQbOUvBr9PKArcPcrNIeRsBdgcUzOGrhKveVpvOIGA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/Boshen"
+      }
+    },
+    "node_modules/@rolldown/binding-android-arm64": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.3.tgz",
+      "integrity": "sha512-454rs7jHngixp/NMxd5srYD57OnzSlZ/eFTETjORQHLwJG1lRtmNOJcBerZlfu4GjKqeq8aCCIQrMdHyhI51Hw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-arm64": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.3.tgz",
+      "integrity": "sha512-PcAhP+ynjURNyy8SKGl5DQP94aGuB/7JrXJb/t7P+hanXvQVMWzUvRRhBAcg/lNRadBhoUPqSoP4xw5tR/KBEA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-darwin-x64": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.3.tgz",
+      "integrity": "sha512-9YpfeUvSE2RS7wysJ81uOZkXJz7f7Q55H2Gvp3VEw/EsahqDtrphrZ0EwDLK5vvKOzaCrBsjF8JmnMLcUt78Gg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-freebsd-x64": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.3.tgz",
+      "integrity": "sha512-yB1IlAsSNHncV6SCTL27/MVGR5htvQsoGxIv5KMGXALp+Ll1wYsn+x98M9MW7qa+NdSbvrrY7ANI4wLJ0n1e6g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.3.tgz",
+      "integrity": "sha512-Yi30IVAAfLUCy2MseFjbB1jAMDl1VMCAas5StnYp8da9+CKvMd2H2cbEjWcw5NPaPqzvYkVIaF1nNUG+b7u/sw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-gnu": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.3.tgz",
+      "integrity": "sha512-jsO7R8To+AdlYgUmN5sHSCZbfhtMBkO0WUx8iORQnPcMMdgr7qM2DQmMwgabs3GhNztdmoKkMKQFHD6DTMCIQw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-arm64-musl": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.3.tgz",
+      "integrity": "sha512-VWkUHwWriDciit80wleYwKILoR/KMvxh/IdwS/paX+ZgpuRpCrKLUdadJbc0NpBEiyhpYawsJ73j9aCvOH+f7Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.3.tgz",
+      "integrity": "sha512-5f1laC0SlIR0yDbFCd8acUhvJIag6N3zC5P7oUPN6wX0aOma+uKJ0wBDH5aq7I1PVI2ttTlhJwzwRIBnLiSGEg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-s390x-gnu": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.3.tgz",
+      "integrity": "sha512-Iq4ko0r4XsgbrF/LunNgHtAGLRRVE2kXonAXQ/MV0mC6jQpMOhW1SvtZja2EhC/kd05++bP78dsqBeIQyYJ6Yg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-gnu": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.3.tgz",
+      "integrity": "sha512-B8m6tD5+/N5FeNQFbKlLA/2yVq9ycQP1SeedyEYYKWBNR3ZQbkvIUcNnDNM03lO1l5F2roiiFJGgvoLLyZXtSg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-linux-x64-musl": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.3.tgz",
+      "integrity": "sha512-pSdpdUJHkuCxun9LE7jvgUB9qsRgaiyNNCX7m/AvHTcq67AiT/Yhoxvw5zPfhrM8k/BfP8ce/hMOpthKDpEUow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-openharmony-arm64": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.3.tgz",
+      "integrity": "sha512-OXXS3RKJgX2uLwM+gYyuH5omcH8fL1LJs96pZGgtetVCahON57+d4SJHzTgZiOjxgGkSnpXpOsWuPDGAKAigEg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-wasm32-wasi": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.3.tgz",
+      "integrity": "sha512-JTtb8BWFynicNSoPrehsCzBtOKjZ6jhMiPFEmOiuXg1Fl8dn2KHQob+GuPSGR0dryQa1PQJbzjF3dqO/whhjLg==",
+      "cpu": [
+        "wasm32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "1.10.0",
+        "@emnapi/runtime": "1.10.0",
+        "@napi-rs/wasm-runtime": "^1.1.4"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-arm64-msvc": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.3.tgz",
+      "integrity": "sha512-gEdFFEN70A/jxb2svrWsN3aDL7OUtmvlOy+6fa2jxG8K0wQ1ZbdeLGnidov6Yu5/733dI5ySfzFlQ/cb0bSz1g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/binding-win32-x64-msvc": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.3.tgz",
+      "integrity": "sha512-eXB7CHuaQdqmJcc3koCNtNPmT/bj2gc999kUFgBxG8Ac0NdgXc4rkCHhqrgrhN3zddvvvrgzj1e90SuSfmyIXA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
+      "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@tybys/wasm-util": {
+      "version": "0.10.2",
+      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
+      "integrity": "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@types/emscripten": {
+      "version": "1.41.5",
+      "resolved": "https://registry.npmjs.org/@types/emscripten/-/emscripten-1.41.5.tgz",
+      "integrity": "sha512-cMQm7pxu6BxtHyqJ7mQZ2kXWV5SLmugybFdHCBbJ5eHzOo6VhBckEgAT3//rP5FwPHNPeEiq4SmQ5ucBwsOo4Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/node": {
+      "version": "26.0.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.0.0.tgz",
+      "integrity": "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.3.0"
+      }
+    },
+    "node_modules/@types/sql.js": {
+      "version": "1.4.11",
+      "resolved": "https://registry.npmjs.org/@types/sql.js/-/sql.js-1.4.11.tgz",
+      "integrity": "sha512-QXIx38p2ZThJaK9vP5ZdqdlRe1FG9I8SmCZOS7FHfB/2qPAjZwkL7/vlfPg6N/oWHuuOaGg/P/IRwfP2W0kWVQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/emscripten": "*",
+        "@types/node": "*"
+      }
+    },
+    "node_modules/95css": {
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/95css/-/95css-0.4.2.tgz",
+      "integrity": "sha512-lzlM1rTgaGCxQL66qZTTzH7H+fHOMwwOZQsry3FcgoeUTrPp3mFReY4LUFPiTywC+Qeve0OH2VxrjDhHgRyu5A==",
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/lightningcss": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.32.0.tgz",
+      "integrity": "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==",
+      "dev": true,
+      "license": "MPL-2.0",
+      "dependencies": {
+        "detect-libc": "^2.0.3"
+      },
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      },
+      "optionalDependencies": {
+        "lightningcss-android-arm64": "1.32.0",
+        "lightningcss-darwin-arm64": "1.32.0",
+        "lightningcss-darwin-x64": "1.32.0",
+        "lightningcss-freebsd-x64": "1.32.0",
+        "lightningcss-linux-arm-gnueabihf": "1.32.0",
+        "lightningcss-linux-arm64-gnu": "1.32.0",
+        "lightningcss-linux-arm64-musl": "1.32.0",
+        "lightningcss-linux-x64-gnu": "1.32.0",
+        "lightningcss-linux-x64-musl": "1.32.0",
+        "lightningcss-win32-arm64-msvc": "1.32.0",
+        "lightningcss-win32-x64-msvc": "1.32.0"
+      }
+    },
+    "node_modules/lightningcss-android-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.32.0.tgz",
+      "integrity": "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-arm64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.32.0.tgz",
+      "integrity": "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-darwin-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.32.0.tgz",
+      "integrity": "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-freebsd-x64": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.32.0.tgz",
+      "integrity": "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm-gnueabihf": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.32.0.tgz",
+      "integrity": "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.32.0.tgz",
+      "integrity": "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-arm64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.32.0.tgz",
+      "integrity": "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-gnu": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.32.0.tgz",
+      "integrity": "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-linux-x64-musl": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.32.0.tgz",
+      "integrity": "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-arm64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.32.0.tgz",
+      "integrity": "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/lightningcss-win32-x64-msvc": {
+      "version": "1.32.0",
+      "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.32.0.tgz",
+      "integrity": "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MPL-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 12.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/parcel"
+      }
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.15",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.15.tgz",
+      "integrity": "sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/rolldown": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.3.tgz",
+      "integrity": "sha512-i00lAJ2ks1BYr7rjNjKC7BcqAS7nVfiT3QX1SI5aY+AFHblCmaUf9OE9dbdzDvW6dJxbi2ZCZiy9v3CcwOiX3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@oxc-project/types": "=0.133.0",
+        "@rolldown/pluginutils": "^1.0.0"
+      },
+      "bin": {
+        "rolldown": "bin/cli.mjs"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "optionalDependencies": {
+        "@rolldown/binding-android-arm64": "1.0.3",
+        "@rolldown/binding-darwin-arm64": "1.0.3",
+        "@rolldown/binding-darwin-x64": "1.0.3",
+        "@rolldown/binding-freebsd-x64": "1.0.3",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.3",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.3",
+        "@rolldown/binding-linux-arm64-musl": "1.0.3",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.3",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.3",
+        "@rolldown/binding-linux-x64-gnu": "1.0.3",
+        "@rolldown/binding-linux-x64-musl": "1.0.3",
+        "@rolldown/binding-openharmony-arm64": "1.0.3",
+        "@rolldown/binding-wasm32-wasi": "1.0.3",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.3",
+        "@rolldown/binding-win32-x64-msvc": "1.0.3"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/sql.js": {
+      "version": "1.14.1",
+      "resolved": "https://registry.npmjs.org/sql.js/-/sql.js-1.14.1.tgz",
+      "integrity": "sha512-gcj8zBWU5cFsi9WUP+4bFNXAyF1iRpA3LLyS/DP5xlrNzGmPIizUeBggKa8DbDwdqaKwUcTEnChtd2grWo/x/A==",
+      "license": "MIT"
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.17",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+      "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/typescript": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
+      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vite": {
+      "version": "8.0.16",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.16.tgz",
+      "integrity": "sha512-h9bXPmJichP5fLmVQo3PyaGSDE2n3aPuomeAlVRm0JLmt4rY6zmPKd59HYI4LNW8oTK7tlTsuC7l/m7awx9Jcw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "lightningcss": "^1.32.0",
+        "picomatch": "^4.0.4",
+        "postcss": "^8.5.15",
+        "rolldown": "1.0.3",
+        "tinyglobby": "^0.2.17"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "@vitejs/devtools": "^0.1.18",
+        "esbuild": "^0.27.0 || ^0.28.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "@vitejs/devtools": {
+          "optional": true
+        },
+        "esbuild": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

tooling/pipeline-results-viewer/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "pipeline-results-viewer",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@types/sql.js": "^1.4.11",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.12"
+  },
+  "dependencies": {
+    "95css": "^0.4.2",
+    "sql.js": "^1.14.1"
+  }
+}

tooling/pipeline-results-viewer/src/main.ts

@@ -0,0 +1,85 @@
+import "95css/css/95css.css";
+import initSqlJs, { type Database } from "sql.js";
+import sqlWasmUrl from "sql.js/dist/sql-wasm.wasm?url";
+import "./style.css";
+
+const DB_URL = "/biergarten.sqlite";
+
+const tableSelect = document.querySelector<HTMLSelectElement>("#table-select")!;
+const tableContainer =
+  document.querySelector<HTMLDivElement>("#table-container")!;
+const status = document.querySelector<HTMLParagraphElement>("#status")!;
+
+const renderTable = (db: Database, name: string) => {
+  const result = db.exec(`SELECT * FROM "${name}"`);
+  tableContainer.replaceChildren();
+
+  if (result.length === 0) {
+    tableContainer.append(
+      Object.assign(document.createElement("p"), { textContent: "No rows." }),
+    );
+    return;
+  }
+
+  const { columns, values } = result[0];
+  const table = document.createElement("table");
+
+  const head = table.createTHead().insertRow();
+  for (const column of columns) {
+    const th = document.createElement("th");
+    th.textContent = column;
+    head.append(th);
+  }
+
+  const body = table.createTBody();
+  for (const row of values) {
+    const tr = body.insertRow();
+    for (const cell of row) {
+      const td = document.createElement("td");
+      td.textContent = String(cell ?? "");
+      tr.append(td);
+    }
+  }
+
+  tableContainer.append(table);
+};
+
+async function main(): Promise<void> {
+  status.textContent = "Loading database...";
+
+  const sqlJs = await initSqlJs({ locateFile: () => sqlWasmUrl });
+  const response = await fetch(DB_URL);
+  const buffer = await response.arrayBuffer();
+  const db = new sqlJs.Database(new Uint8Array(buffer));
+
+  const tables =
+    db
+      .exec(
+        `SELECT name
+         FROM sqlite_master
+         WHERE
+          type = 'table'
+         AND
+          name NOT LIKE 'sqlite_%'
+         ORDER BY name`,
+      )[0]
+      ?.values.map((row) => String(row[0])) ?? [];
+
+  for (const name of tables) {
+    tableSelect.append(new Option(name, name));
+  }
+
+  tableSelect.addEventListener("change", () =>
+    renderTable(db, tableSelect.value),
+  );
+
+  if (tables.length > 0) {
+    renderTable(db, tables[0]);
+  }
+
+  status.textContent = "";
+}
+
+main().catch((error: unknown) => {
+  status.textContent = `Failed to load database: ${String(error)}`;
+});

tooling/pipeline-results-viewer/src/style.css

@@ -0,0 +1,28 @@
+body {
+  margin: 0;
+  padding: 24px;
+}
+
+#window {
+  width: 100%;
+  max-width: 1600px;
+  margin: 0 auto;
+}
+
+#table-container {
+  overflow-x: auto;
+  margin-top: 8px;
+}
+
+table {
+  border-collapse: collapse;
+}
+
+th,
+td {
+  border: 1px solid #808080;
+  padding: 4px 8px;
+  text-align: left;
+  font-size: 14px;
+  white-space: nowrap;
+}

tooling/pipeline-results-viewer/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "esnext",
+    "lib": ["ES2023", "DOM"],
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

tooling/pipeline/CMakeLists.txt

@@ -151,6 +151,11 @@ target_sources(${PROJECT_NAME} PRIVATE
         src/json_handling/json_loader.cc
 )
 
+# --- data_model ---
+target_sources(${PROJECT_NAME} PRIVATE
+        src/data_model/names_by_country.cc
+)
+
 # --- application_options ---
 target_sources(${PROJECT_NAME} PRIVATE
         src/application_options/parse_arguments.cc
@@ -161,6 +166,7 @@ target_sources(${PROJECT_NAME} PRIVATE
         src/biergarten_pipeline_orchestrator/log_results.cc
         src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc
         src/biergarten_pipeline_orchestrator/generate_breweries.cc
+        src/biergarten_pipeline_orchestrator/generate_users.cc
         src/biergarten_pipeline_orchestrator/run.cc
         src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc
 )
@@ -204,6 +210,7 @@ target_sources(${PROJECT_NAME} PRIVATE
 # --- services: sqlite ---
 target_sources(${PROJECT_NAME} PRIVATE
 	src/services/sqlite/process_record.cc
+	src/services/sqlite/process_user_record.cc
 	src/services/sqlite/sqlite_export_service.cc
 	src/services/sqlite/finalize.cc
 	src/services/sqlite/initialize.cc
@@ -260,6 +267,21 @@ configure_file(
         ${CMAKE_BINARY_DIR}/locations.json
         COPYONLY
 )
+configure_file(
+        ${CMAKE_SOURCE_DIR}/personas.json
+        ${CMAKE_BINARY_DIR}/personas.json
+        COPYONLY
+)
+configure_file(
+        ${CMAKE_SOURCE_DIR}/forenames-by-country.json
+        ${CMAKE_BINARY_DIR}/forenames-by-country.json
+        COPYONLY
+)
+configure_file(
+        ${CMAKE_SOURCE_DIR}/surnames-by-country.json
+        ${CMAKE_BINARY_DIR}/surnames-by-country.json
+        COPYONLY
+)
 add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
         COMMAND ${CMAKE_COMMAND} -E copy_directory
         ${CMAKE_SOURCE_DIR}/prompts

tooling/pipeline/format-per-directory.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# Walks every directory under src/ and includes/ (including nested
+# subdirectories), runs clang-format on the C/C++ files in that directory
+# only (non-recursive), and commits the result with its own commit.
+#
+# Usage: ./format-per-directory.sh [-y]
+#   -y  skip the confirmation prompt
+
+set -euo pipefail
+
+SKIP_CONFIRM=false
+if [[ "${1:-}" == "-y" ]]; then
+    SKIP_CONFIRM=true
+fi
+
+cd "$(dirname "$0")"
+
+if [ ! -f .clang-format ]; then
+    echo "ERROR: .clang-format file not found."
+    exit 1
+fi
+
+if ! command -v clang-format &>/dev/null; then
+    echo "ERROR: clang-format not found."
+    exit 1
+fi
+
+if ! command -v git &>/dev/null; then
+    echo "ERROR: git not found."
+    exit 1
+fi
+
+echo "WARNING: This script will format .cpp, .h, .cxx, .cc, .c, .hpp files"
+echo "directory-by-directory under src/ and includes/, committing after each"
+echo "directory is formatted."
+
+if [[ "$SKIP_CONFIRM" == false ]]; then
+    read -p "Do you want to continue? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Aborted."
+        exit 1
+    fi
+fi
+
+if [[ -n "$(git status --porcelain)" ]]; then
+    echo "ERROR: working tree is not clean. Commit or stash your changes first."
+    exit 1
+fi
+
+dirs=$(find src includes -type d | sort)
+
+for dir in $dirs; do
+    files=$(find "$dir" -maxdepth 1 -type f \( -name "*.cpp" -o -name "*.hpp" -o -name "*.h" -o -name "*.c" -o -name "*.cc" -o -name "*.cxx" \))
+
+    if [[ -z "$files" ]]; then
+        continue
+    fi
+
+    echo "Formatting $dir..."
+    echo "$files" | xargs clang-format -i
+
+    if [[ -n "$(git status --porcelain -- "$dir")" ]]; then
+        git add -- "$dir"
+        git commit -m "Formatted $dir"
+    else
+        echo "No changes in $dir, skipping commit."
+    fi
+done
+
+echo "Done."

tooling/pipeline/includes/biergarten_pipeline_orchestrator.h

@@ -2,11 +2,11 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
 
 /**
- * @file biergarten_data_generator.h
+ * @file biergarten_pipeline_orchestrator.h
- * @brief Orchestration for end-to-end brewery data generation pipeline.
+ * @brief Orchestration for end-to-end brewery and user data generation.
  *
- * Intent: Coordinates location loading, enrichment, and generation phases
+ * Coordinates location loading, enrichment, and generation phases to produce
- * to produce a complete dataset. Coordinates dependencies via composition root.
+ * a complete dataset, wiring dependencies selected at the composition root.
  */
 
 #include <memory>
@@ -15,25 +15,28 @@
 
 #include "data_generation/data_generator.h"
 #include "data_model/generated_models.h"
+#include "services/curated_data/curated_data_service.h"
 #include "services/database/export_service.h"
 #include "services/enrichment/enrichment_service.h"
-
 #include "services/logging/logger.h"
 
 /**
- * @brief Main data generator class for the Biergarten pipeline.
+ * @brief Main orchestrator for the Biergarten data generation pipeline.
  *
- * This class encapsulates the core logic for generating brewery data.
+ * Handles location loading, city enrichment, and brewery/user generation.
- * It handles location loading, city enrichment, and brewery generation.
  */
 class BiergartenPipelineOrchestrator {
  public:
   /**
    * @brief Constructs the orchestrator with injected pipeline dependencies.
    *
+   * @param logger Sink for pipeline diagnostics.
    * @param context_service Provides regional context for locations.
- * @param generator Implementation (Llama or Mock) for brewery/user generation.
+   * @param generator Implementation (Llama or Mock) for brewery/user
+   * generation.
    * @param exporter Database backend for persisting generated records.
+   * @param curated_data_service Loads curated location, persona, and name
+   * data used to seed generation.
    * @param application_options CLI configuration and paths.
    */
   BiergartenPipelineOrchestrator(
@@ -41,6 +44,7 @@ class BiergartenPipelineOrchestrator {
       std::unique_ptr<IEnrichmentService> context_service,
       std::unique_ptr<DataGenerator> generator,
       std::unique_ptr<IExportService> exporter,
+      std::unique_ptr<ICuratedDataService> curated_data_service,
       const ApplicationOptions& application_options);
 
   /**
@@ -49,38 +53,42 @@ class BiergartenPipelineOrchestrator {
    * Performs the following steps:
    * 1. Load curated locations from JSON
    * 2. Resolve context for each city using the injected context service
-   * 3. Generate brewery data for sampled cities
+   * 3. Generate brewery and user data for sampled cities
    *
    * @note STRUCTURAL CONCURRENCY REQUIREMENT:
-   * When transitioned to a multithreaded design, this method MUST structurally
+   * When transitioned to a multithreaded design, this method MUST
-   * enforce that all deployed worker threads are joined before returning (e.g.
+   * structurally enforce that all deployed worker threads are joined before
-   * by using std::jthread or a structured concurrency primitive). This ensures
+   * returning (e.g. by using std::jthread or a structured concurrency
-   * workers do not attempt to log to a closed channel during application teardown.
+   * primitive). This ensures workers do not attempt to log to a closed
+   * channel during application teardown.
    *
    * @return true if successful, false if not
    */
   bool Run();
 
  private:
-  /// @brief Logger instance for emitting pipeline messages.
   std::shared_ptr<ILogger> logger_;
-
-  /// @brief Owning context provider dependency.
   std::unique_ptr<IEnrichmentService> context_service_;
 
-  /// @brief Generator dependency selected in the composition root.
+  /**
+   * @brief Generator implementation selected at the composition root (Llama
+   * or Mock).
+   */
   std::unique_ptr<DataGenerator> generator_;
 
-   /// @brief Storage backend for generated brewery records.
+  /**
+   * @brief Storage backend for generated brewery and user records.
+   */
   std::unique_ptr<IExportService> exporter_;
+  std::unique_ptr<ICuratedDataService> curated_data_service_;
 
-   /// @brief CLI configuration: paths, model settings, generation parameters.
   ApplicationOptions application_options_;
 
   /**
    * @brief Load locations from JSON and sample cities.
    *
-   * @return Vector of sampled locations capped at 50 entries.
+   * @return Vector of locations randomly sampled per
+   * PipelineOptions::location_count.
    */
   std::vector<Location> QueryCitiesWithCountries();
 
@@ -92,11 +100,24 @@ class BiergartenPipelineOrchestrator {
   void GenerateBreweries(std::span<const EnrichedCity> cities);
 
   /**
-   * @brief Log the generated brewery results.
+   * @brief Generate users grounded in sampled names and personas for
+   * enriched cities.
+   *
+   * Loads personas.json / forenames-by-country.json /
+   * surnames-by-country.json itself, mirroring how QueryCitiesWithCountries()
+   * owns its own locations.json load.
+   *
+   * @param cities Span of enriched city data.
+   */
+  void GenerateUsers(std::span<const EnrichedCity> cities);
+
+  /**
+   * @brief Log the generated brewery and user results.
    */
   void LogResults() const;
 
-  /// @brief Stores generated brewery data.
+  std::vector<BreweryRecord> generated_breweries_;
-  std::vector<GeneratedBrewery> generated_breweries_;
+  std::vector<UserRecord> generated_users_;
 };
+
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_

tooling/pipeline/includes/concurrency/bounded_channel.h

@@ -9,10 +9,12 @@
 
 /**
  * @file bounded_channel.h
- * @brief Thread-safe, bounded multi-producer/multi-consumer synchronous channel.
+ * @brief Thread-safe, bounded multi-producer/multi-consumer synchronous
+ * channel.
  *
  * Intent: Enables asynchronous inter-thread communication with backpressure.
- * Models a synchronous channel where producers/consumers block on capacity limits.
+ * Models a synchronous channel where producers/consumers block on capacity
+ * limits.
  */
 
 /**

tooling/pipeline/includes/data_generation/data_generator.h

@@ -28,12 +28,16 @@ class DataGenerator {
                                         const std::string& region_context) = 0;
 
   /**
-   * @brief Generates a user profile for a locale.
+   * @brief Generates a user profile grounded in a sampled name and persona.
    *
-   * @param locale Locale hint used by generator.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype grounding the generated bio.
+   * @param name Sampled first/last name (and gender)
    * @return User generation result.
    */
-  virtual UserResult GenerateUser(const std::string& locale) = 0;
+  virtual UserResult GenerateUser(const EnrichedCity& city,
+                                  const UserPersona& persona,
+                                  const Name& name) = 0;
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_DATA_GENERATOR_H_

tooling/pipeline/includes/data_generation/json_grammars.h

@@ -0,0 +1,52 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_JSON_GRAMMARS_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_JSON_GRAMMARS_H_
+
+/**
+ * @file data_generation/json_grammars.h
+ * @brief GBNF grammars constraining structured JSON output from
+ * LlamaGenerator inference calls.
+ */
+
+#include <string_view>
+
+// GBNF grammar for structured user JSON output.
+// thought-block permits the model to emit free-form reasoning before the
+// JSON object (the prompts explicitly invite this); only the "{...}" tail is
+// constrained to the expected shape.
+inline constexpr std::string_view kUserJsonGrammar = R"json_user(
+root ::= thought-block (
+    "{" ws
+    "\"username\"" ws ":" ws string ws "," ws
+    "\"bio\"" ws ":" ws string ws "," ws
+    "\"activity_weight\"" ws ":" ws number ws
+  "}" ws
+)
+thought-block ::= [^{]*
+ws            ::= [ \t\n\r]*
+string        ::= "\"" char+ "\""
+char          ::= [^"\\\x7F\x00-\x1F] | [\\] escape
+escape        ::= ["\\/bfnrt] | "u" hex hex hex hex
+hex           ::= [0-9a-fA-F]
+number        ::= "-"? ("0" | [1-9] [0-9]*) ("." [0-9]+)?
+)json_user";
+
+// GBNF grammar for structured brewery JSON output (see thought-block note
+// above).
+inline constexpr std::string_view kBreweryJsonGrammar = R"json_brewery(
+root ::= thought-block (
+    "{" ws
+    "\"name_en\"" ws ":" ws string ws "," ws
+    "\"description_en\"" ws ":" ws string ws "," ws
+    "\"name_local\"" ws ":" ws string ws "," ws
+    "\"description_local\"" ws ":" ws string ws
+  "}" ws
+)
+thought-block ::= [^{]*
+ws            ::= [ \t\n\r]*
+string        ::= "\"" char+ "\""
+char          ::= [^"\\\x7F\x00-\x1F] | [\\] escape
+escape        ::= ["\\/bfnrt] | "u" hex hex hex hex
+hex           ::= [0-9a-fA-F]
+)json_brewery";
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_JSON_GRAMMARS_H_

tooling/pipeline/includes/data_generation/llama_generator.h

@@ -44,14 +44,9 @@ class LlamaGenerator final : public DataGenerator {
 
   ~LlamaGenerator() override;
 
-  // disable copy constructor
   LlamaGenerator(const LlamaGenerator&) = delete;
-
-  // disable copy assignment operator
   LlamaGenerator& operator=(const LlamaGenerator&) = delete;
-  // disable move constructor
   LlamaGenerator(LlamaGenerator&&) = delete;
-  // disable move assignment operator
   LlamaGenerator& operator=(LlamaGenerator&&) = delete;
 
   /**
@@ -65,12 +60,15 @@ class LlamaGenerator final : public DataGenerator {
                                 const std::string& region_context) override;
 
   /**
-   * @brief Generates a user profile for the provided locale.
+   * @brief Generates a user profile grounded in a sampled name and persona.
    *
-   * @param locale Locale hint.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype grounding the generated bio.
+   * @param name Sampled first/last name -- not LLM-invented.
    * @return Generated user profile.
    */
-  UserResult GenerateUser(const std::string& locale) override;
+  UserResult GenerateUser(const EnrichedCity& city, const UserPersona& persona,
+                          const Name& name) override;
 
  private:
   static constexpr int32_t kDefaultMaxTokens = 10000;

tooling/pipeline/includes/data_generation/llama_generator_helpers.h

@@ -47,4 +47,18 @@ void AppendTokenPiece(const llama_vocab* vocab, llama_token token,
 std::optional<std::string> ValidateBreweryJson(const std::string& raw,
                                                BreweryResult& brewery_out);
 
+/**
+ * @brief Validates and parses user JSON output.
+ *
+ * Only populates `username`, `bio`, and `activity_weight` -- `first_name`
+ * and `last_name` are not LLM-authored and are set separately from the
+ * sampled Name.
+ *
+ * @param raw Raw model output.
+ * @param user_out Parsed user payload.
+ * @return Validation error message if invalid, or std::nullopt on success.
+ */
+std::optional<std::string> ValidateUserJson(const std::string& raw,
+                                            UserResult& user_out);
+
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_LLAMA_GENERATOR_HELPERS_H_

tooling/pipeline/includes/data_generation/mock_generator.h

@@ -28,12 +28,16 @@ class MockGenerator final : public DataGenerator {
                                 const std::string& region_context) override;
 
   /**
-   * @brief Generates deterministic user data for a locale.
+   * @brief Generates deterministic user data grounded in a sampled name and
+   * persona.
    *
-   * @param locale Locale hint.
+   * @param city Enriched city the user is associated with.
+   * @param persona Persona archetype.
+   * @param name Sampled first/last name, copied directly into the result.
    * @return Generated user result.
    */
-  UserResult GenerateUser(const std::string& locale) override;
+  UserResult GenerateUser(const EnrichedCity& city, const UserPersona& persona,
+                          const Name& name) override;
 
  private:
   /**
@@ -44,12 +48,25 @@ class MockGenerator final : public DataGenerator {
    */
   static size_t DeterministicHash(const Location& location);
 
+  /**
+   * @brief Combines city, persona, and name into a stable hash value.
+   *
+   * @param location City and country names.
+   * @param persona Persona archetype.
+   * @param name Sampled first/last name.
+   * @return Deterministic hash value.
+   */
+  static size_t DeterministicHash(const Location& location,
+                                  const UserPersona& persona, const Name& name);
+
   // Hash stride constants for deterministic distribution across fixed-size
   // arrays. These coprime strides spread hash values uniformly without
   // clustering, ensuring diverse output across different hash inputs.
   static constexpr size_t kNounHashStride = 7;
   static constexpr size_t kDescriptionHashStride = 13;
   static constexpr size_t kBioHashStride = 11;
+  static constexpr size_t kActivityWeightHashStride = 17;
+  static constexpr size_t kActivityWeightHashRange = 1000;
 
   static constexpr std::array<std::string_view, 18> kBreweryAdjectives = {
       "Craft",      "Heritage", "Local",  "Artisan",  "Pioneer",    "Golden",
@@ -124,7 +141,8 @@ class MockGenerator final : public DataGenerator {
       "Visits breweries for the stories, stays for the flagship pours.",
       "Craft beer fan mapping tasting notes and favorite brew routes.",
       "Always ready to trade recommendations for underrated local breweries.",
-      "Keeping a running list of must-try collab releases and tap takeovers."};
+      "Keeping a running list of must-try collab releases and tap "
+      "takeovers."};
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_MOCK_GENERATOR_H_

tooling/pipeline/includes/data_model/generated_models.h

@@ -3,8 +3,8 @@
 
 /**
  * @file data_model/generated_models.h
- * @brief Generated output models from the pipeline: brewery/user results, enriched data,
+ * @brief Generated output models from the pipeline: brewery/user results,
- * and complete generation results.
+ * enriched data, and complete generation results.
  */
 
 #include <string>
@@ -19,16 +19,24 @@
  * @brief Generated brewery payload.
  */
 struct BreweryResult {
-  /// @brief Brewery display name in English.
+  /**
+   * @brief Brewery display name in English.
+   */
   std::string name_en;
 
-  /// @brief Brewery description text in English.
+  /**
+   * @brief Brewery description text in English.
+   */
   std::string description_en;
 
-  /// @brief Brewery display name in the local language.
+  /**
+   * @brief Brewery display name in the local language.
+   */
   std::string name_local;
 
-  /// @brief Brewery description text in the local language.
+  /**
+   * @brief Brewery description text in the local language.
+   */
   std::string description_local;
 };
 
@@ -36,11 +44,39 @@ struct BreweryResult {
  * @brief Generated user profile payload.
  */
 struct UserResult {
-  /// @brief Username handle.
+  /**
+   * @brief First (given) name, copied from the sampled Name -- not
+   * LLM-invented.
+   */
+  std::string first_name{};
+
+  /**
+   * @brief Last (family) name, copied from the sampled Name -- not
+   * LLM-invented.
+   */
+  std::string last_name{};
+
+  /**
+   * @brief Gender associated with the sampled first name, copied from the
+   * sampled Name -- not LLM-invented.
+   */
+  std::string gender{};
+
+  /**
+   * @brief Username handle.
+   */
   std::string username{};
 
-  /// @brief Short user biography.
+  /**
+   * @brief Short user biography.
+   */
   std::string bio{};
+
+  /**
+   * @brief Relative check-in/activity weight for this user, used to drive
+   * a J-curve activity profile in later pipeline phases.
+   */
+  float activity_weight{};
 };
 
 // ============================================================================
@@ -58,9 +94,23 @@ struct EnrichedCity {
 /**
  * @brief Helper struct to store generated brewery data.
  */
-struct GeneratedBrewery {
+struct BreweryRecord {
   Location location;
   BreweryResult brewery;
 };
 
+/**
+ * @brief Helper struct to store generated user data.
+ *
+ * `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.
+ */
+struct UserRecord {
+  Location location;
+  UserResult user;
+  std::string email{};
+  std::string date_of_birth{};
+};
+
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_GENERATED_MODELS_H_

tooling/pipeline/includes/data_model/models.h

@@ -28,40 +28,91 @@ namespace prog_opts = boost::program_options;
  * @brief Canonical location record for city-level generation.
  */
 struct Location {
-  /// @brief City name.
   std::string city{};
-
-  /// @brief State or province name.
   std::string state_province{};
 
-  /// @brief ISO 3166-2 subdivision code.
+  /**
+   * @brief ISO 3166-2 subdivision code.
+   */
   std::string iso3166_2{};
 
-  /// @brief Country name.
   std::string country{};
 
-  /// @brief ISO 3166-1 country code.
+  /**
+   * @brief ISO 3166-1 country code.
+   */
   std::string iso3166_1{};
 
-  /// @brief Local language codes in priority order.
+  /**
+   * @brief Local language codes in priority order.
+   */
   std::vector<std::string> local_languages{};
 
-  /// @brief Latitude in decimal degrees.
+  /**
+   * @brief Latitude in decimal degrees.
+   */
   double latitude{};
 
-  /// @brief Longitude in decimal degrees.
+  /**
+   * @brief Longitude in decimal degrees.
+   */
   double longitude{};
 };
 
-/**
+// ============================================================================
- * @brief Non-owning brewery location input.
+// Name / Persona Models
- */
+// ============================================================================
-struct BreweryLocation {
-  /// @brief City name.
-  std::string_view city_name;
 
-  /// @brief Country name.
+/**
-  std::string_view country_name;
+ * @brief A sampled first/last name pair, with the source forename's gender.
+ *
+ * Produced by NamesByCountry::SampleName();
+ */
+struct Name {
+  std::string first_name{};
+  std::string last_name{};
+
+  /**
+   * @brief Gender associated with the sampled forename (e.g. "M", "F"), as
+   * reported by the source dataset.
+   */
+  std::string gender{};
+};
+
+/**
+ * @brief A single forename entry from the names-by-country fixture data.
+ */
+struct ForenameEntry {
+  /**
+   * @brief Romanized forename.
+   */
+  std::string name{};
+
+  /**
+   * @brief Gender associated with this forename, as reported by the source
+   * dataset (e.g. "M", "F").
+   */
+  std::string gender{};
+};
+
+/**
+ * @brief A persona archetype used to ground LLM-generated user bios.
+ */
+struct UserPersona {
+  /**
+   * @brief Persona display name (e.g. "Hophead Explorer").
+   */
+  std::string name{};
+
+  /**
+   * @brief Short description of the persona's interests and voice.
+   */
+  std::string description{};
+
+  /**
+   * @brief Beer styles this persona gravitates toward.
+   */
+  std::vector<std::string> style_affinities{};
 };
 
 // ============================================================================
@@ -72,22 +123,34 @@ struct BreweryLocation {
  * @brief LLM sampling parameters.
  */
 struct SamplingOptions {
-  /// @brief LLM sampling temperature (0.0 to 1.0, higher = more random).
+  /**
+   * @brief LLM sampling temperature (higher = more random).
+   */
   float temperature = 1.0F;
 
-  /// @brief LLM nucleus sampling top-p parameter.
+  /**
+   * @brief LLM nucleus sampling top-p parameter.
+   */
   float top_p = 0.95F;
 
-  /// @brief LLM top-k sampling parameter.
+  /**
+   * @brief LLM top-k sampling parameter.
+   */
   uint32_t top_k = 64;
 
-  /// @brief Context window size (tokens).
+  /**
+   * @brief Context window size (tokens).
+   */
   uint32_t n_ctx = 8192;
 
-  /// @brief Random seed (-1 for random, otherwise non-negative).
+  /**
+   * @brief Random seed (-1 for random, otherwise non-negative).
+   */
   int seed = -1;
 
-  /// @brief Number of layers to offload to GPU.
+  /**
+   * @brief Number of layers to offload to GPU.
+   */
   int n_gpu_layers = 0;
 };
 
@@ -95,16 +158,20 @@ struct SamplingOptions {
  * @brief Configuration for the LLM generator component.
  */
 struct GeneratorOptions {
-  /// @brief Path to the LLM model file (gguf format).
+  /**
+   * @brief Path to the LLM model file (gguf format).
+   */
   std::filesystem::path model_path;
 
-  /// @brief Use mocked generator instead of actual LLM inference.
+  /**
+   * @brief Use mocked generator instead of actual LLM inference.
+   */
   bool use_mocked = false;
 
-
+  /**
-
+   * @brief Specific sampling parameters for this generator.
-  /// @brief Specific sampling parameters for this generator.
+   * If nullopt, the application should use global defaults.
-  /// If nullopt, the application should use global defaults.
+   */
   std::optional<SamplingOptions> sampling;
 };
 
@@ -112,18 +179,23 @@ struct GeneratorOptions {
  * @brief Configuration for the pipeline execution and output.
  */
 struct PipelineOptions {
-  /// @brief Directory for generated artifacts.
+  /**
+   * @brief Directory for generated artifacts.
+   */
   std::filesystem::path output_path;
 
-  /// @brief Directory that contains named prompt files (e.g.
+  /**
-  /// BREWERY_GENERATION.md).
+   * @brief Directory that contains named prompt files (e.g.
+   * BREWERY_GENERATION.md).
+   */
   std::filesystem::path prompt_dir;
 
-  /// @brief Path for application logs.
   std::filesystem::path log_path;
 
-  /// @brief Number of locations to sample from the dataset
+  /**
-  /// More locations -> more users/more breweries
+   * @brief Number of locations to sample from the dataset
+   * More locations -> more users/more breweries
+   */
   uint32_t location_count;
 };
 
@@ -139,7 +211,7 @@ struct ApplicationOptions {
 // Function Declarations
 // ============================================================================
 
-std::optional<ApplicationOptions> ParseArguments(const int argc, char** argv,
+std::optional<ApplicationOptions> ParseArguments(
-                                                std::shared_ptr<ILogger> logger = nullptr);
+    const int argc, char** argv, std::shared_ptr<ILogger> logger = nullptr);
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_MODELS_H_

tooling/pipeline/includes/data_model/names_by_country.h

@@ -0,0 +1,51 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_
+
+/**
+ * @file data_model/names_by_country.h
+ * @brief Sampling over the names-by-country fixture data.
+ */
+
+#include <optional>
+#include <random>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "data_model/models.h"
+
+/**
+ * @brief Samples locale-appropriate names from curated forename/surname
+ * fixture data, keyed by ISO 3166-1 country code.
+ *
+ * Forenames and surnames are kept in separate maps (mirroring the source
+ * dataset's own shape) so per-forename gender is preserved; pairing happens
+ * at sample time rather than being precomputed, so no information from the
+ * source dataset is discarded up front.
+ */
+class NamesByCountry {
+ public:
+  NamesByCountry(std::unordered_map<std::string, std::vector<ForenameEntry>>
+                     forenames_by_country,
+                 std::unordered_map<std::string, std::vector<std::string>>
+                     surnames_by_country);
+
+  /**
+   * @brief Samples a first/last name pair for the given country.
+   *
+   * @param iso3166_1 ISO 3166-1 country code to sample for.
+   * @param rng Random source used for sampling.
+   * @return A sampled Name, or std::nullopt if the country has no forename
+   * or no surname entries.
+   */
+  [[nodiscard]] std::optional<Name> SampleName(const std::string& iso3166_1,
+                                               std::mt19937& rng) const;
+
+ private:
+  std::unordered_map<std::string, std::vector<ForenameEntry>>
+      forenames_by_country_;
+  std::unordered_map<std::string, std::vector<std::string>>
+      surnames_by_country_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_DATA_MODEL_NAMES_BY_COUNTRY_H_

tooling/pipeline/includes/json_handling/json_loader.h

@@ -3,23 +3,45 @@
 
 /**
  * @file json_handling/json_loader.h
- * @brief Loader API for curated location data.
+ * @brief JSON-backed implementation of ICuratedDataService.
  */
 
 #include <filesystem>
-#include <memory>
 #include <vector>
 
 #include "data_model/models.h"
-#include "services/logging/logger.h"
+#include "data_model/names_by_country.h"
+#include "services/curated_data/curated_data_service.h"
 
-/// @brief Loads curated world locations from a JSON file into memory.
+/**
-class JsonLoader {
+ * @brief Loads curated location, persona, and name data from JSON files.
+ */
+class JsonLoader final : public ICuratedDataService {
  public:
-  /// @brief Parses a JSON array file and returns all location records.
+  JsonLoader() = default;
-  static std::vector<Location> LoadLocations(
+
-      const std::filesystem::path& filepath,
+  /**
-      std::shared_ptr<ILogger> logger = nullptr);
+   * @brief Parses a JSON array file and returns all location records.
+   */
+  std::vector<Location> LoadLocations(
+      const std::filesystem::path& filepath) override;
+
+  /**
+   * @brief Parses a JSON array file and returns all persona records.
+   */
+  std::vector<UserPersona> LoadPersonas(
+      const std::filesystem::path& filepath) override;
+
+  /**
+   * @brief Parses the names-by-country fixture pair into a sampling-capable
+   * NamesByCountry.
+   *
+   * @param forenames_filepath Path to forenames-by-country.json.
+   * @param surnames_filepath Path to surnames-by-country.json.
+   */
+  NamesByCountry LoadNamesByCountry(
+      const std::filesystem::path& forenames_filepath,
+      const std::filesystem::path& surnames_filepath) override;
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_JSON_LOADER_H_

tooling/pipeline/includes/llama_backend_state.h

@@ -16,16 +16,10 @@
  */
 class LlamaBackendState {
  public:
-  /// @brief Initializes global llama backend state.
   LlamaBackendState() { llama_backend_init(); }
-
-  /// @brief Cleans up global llama backend state.
   ~LlamaBackendState() { llama_backend_free(); }
 
-  /// @brief Non-copyable type.
   LlamaBackendState(const LlamaBackendState&) = delete;
-
-  /// @brief Non-copyable type.
   LlamaBackendState& operator=(const LlamaBackendState&) = delete;
 };
 

tooling/pipeline/includes/services/curated_data/curated_data_service.h

@@ -0,0 +1,53 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_CURATED_DATA_CURATED_DATA_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_CURATED_DATA_CURATED_DATA_SERVICE_H_
+
+/**
+ * @file services/curated_data/curated_data_service.h
+ * @brief Abstraction for loading curated location, persona, and name data.
+ */
+
+#include <filesystem>
+#include <vector>
+
+#include "data_model/models.h"
+#include "data_model/names_by_country.h"
+
+/**
+ * @brief Interface for services that load curated data used to seed
+ * brewery/user generation.
+ */
+class ICuratedDataService {
+ public:
+  ICuratedDataService() = default;
+  virtual ~ICuratedDataService() = default;
+
+  ICuratedDataService(const ICuratedDataService&) = delete;
+  ICuratedDataService& operator=(const ICuratedDataService&) = delete;
+  ICuratedDataService(ICuratedDataService&&) = delete;
+  ICuratedDataService& operator=(ICuratedDataService&&) = delete;
+
+  /**
+   * @brief Loads all curated location records.
+   */
+  virtual std::vector<Location> LoadLocations(
+      const std::filesystem::path& filepath) = 0;
+
+  /**
+   * @brief Loads all curated persona records.
+   */
+  virtual std::vector<UserPersona> LoadPersonas(
+      const std::filesystem::path& filepath) = 0;
+
+  /**
+   * @brief Loads the names-by-country fixture pair into a sampling-capable
+   * NamesByCountry.
+   *
+   * @param forenames_filepath Path to forenames-by-country.json.
+   * @param surnames_filepath Path to surnames-by-country.json.
+   */
+  virtual NamesByCountry LoadNamesByCountry(
+      const std::filesystem::path& forenames_filepath,
+      const std::filesystem::path& surnames_filepath) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_CURATED_DATA_CURATED_DATA_SERVICE_H_

tooling/pipeline/includes/services/database/export_service.h

@@ -16,8 +16,6 @@
 class IExportService {
  public:
   IExportService() = default;
-
-  /// @brief Virtual destructor for polymorphic cleanup.
   virtual ~IExportService() = default;
 
   IExportService(const IExportService&) = delete;
@@ -25,7 +23,9 @@ class IExportService {
   IExportService(IExportService&&) = delete;
   IExportService& operator=(IExportService&&) = delete;
 
-  /// @brief Prepares the export destination for a new run.
+  /**
+   * @brief Prepares the export destination for a new run.
+   */
   virtual void Initialize() = 0;
 
   /**
@@ -33,9 +33,18 @@ class IExportService {
    *
    * @param brewery Generated brewery payload to store.
    */
-  virtual uint64_t ProcessRecord(const GeneratedBrewery& brewery) = 0;
+  virtual uint64_t ProcessRecord(const BreweryRecord& brewery) = 0;
 
-  /// @brief Finalizes the export destination.
+  /**
+   * @brief Persists one generated user record.
+   *
+   * @param user Generated user payload to store.
+   */
+  virtual uint64_t ProcessRecord(const UserRecord& user) = 0;
+
+  /**
+   * @brief Finalizes the export destination.
+   */
   virtual void Finalize() = 0;
 };
 

tooling/pipeline/includes/services/database/sqlite_export_service.h

@@ -11,8 +11,8 @@
 #include <string>
 #include <unordered_map>
 
-#include "data_model/models.h"
 #include "../datetime/date_time_provider.h"
+#include "data_model/models.h"
 #include "export_service.h"
 #include "sqlite_export_service_helpers.h"
 
@@ -30,7 +30,8 @@ class SqliteExportService final : public IExportService {
   SqliteExportService& operator=(SqliteExportService&&) = delete;
 
   void Initialize() override;
-  uint64_t ProcessRecord(const GeneratedBrewery& brewery) override;
+  uint64_t ProcessRecord(const BreweryRecord& brewery) override;
+  uint64_t ProcessRecord(const UserRecord& user) override;
   void Finalize() override;
 
  private:
@@ -46,6 +47,15 @@ class SqliteExportService final : public IExportService {
   [[nodiscard]] std::filesystem::path BuildDatabasePath() const;
   [[nodiscard]] static std::string BuildLocationKey(const Location& location);
 
+  /**
+   * @brief Returns the row id for @p location, inserting it first if it has
+   * not already been seen during this run.
+   *
+   * Shared by both ProcessRecord() overloads so breweries and users
+   * referencing the same location resolve to the same row.
+   */
+  [[nodiscard]] sqlite3_int64 ResolveLocationId(const Location& location);
+
   std::unique_ptr<IDateTimeProvider> date_time_provider_;
   std::filesystem::path output_path_;
   std::string run_timestamp_utc_;
@@ -53,6 +63,7 @@ class SqliteExportService final : public IExportService {
   SqliteDatabaseHandle db_handle_;
   SqliteStatementHandle insert_location_stmt_;
   SqliteStatementHandle insert_brewery_stmt_;
+  SqliteStatementHandle insert_user_stmt_;
   bool transaction_open_ = false;
   std::unordered_map<std::string, sqlite3_int64> location_cache_;
 };

tooling/pipeline/includes/services/database/sqlite_statement_helpers.h

@@ -50,6 +50,26 @@ CREATE INDEX IF NOT EXISTS idx_breweries_location_id ON breweries(location_id);
 
 )sql";
 
+inline constexpr std::string_view kCreateUsersTableSql = R"sql(
+
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  location_id INTEGER NOT NULL,
+  first_name TEXT NOT NULL,
+  last_name TEXT NOT NULL,
+  gender TEXT NOT NULL,
+  username TEXT NOT NULL,
+  bio TEXT NOT NULL,
+  activity_weight REAL NOT NULL,
+  email TEXT NOT NULL UNIQUE,
+  date_of_birth TEXT NOT NULL,
+  FOREIGN KEY(location_id) REFERENCES locations(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_location_id ON users(location_id);
+
+)sql";
+
 inline constexpr std::string_view kInsertLocationSql = R"sql(
 INSERT INTO locations (
   city,
@@ -73,6 +93,22 @@ INSERT INTO breweries (
 ) VALUES (?, ?, ?, ?, ?);
 )sql";
 
+inline constexpr std::string_view kInsertUserSql = R"sql(
+INSERT INTO users (
+  location_id,
+  first_name,
+  last_name,
+  gender,
+  username,
+  bio,
+  activity_weight,
+  email,
+  date_of_birth
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?);
+)sql";
+
+// sqlite3_bind_*() parameter indices are 1-based, matching the "?"
+// placeholder order in the SQL above.
 inline constexpr int kLocationCityBindIndex = 1;
 inline constexpr int kLocationStateProvinceBindIndex = 2;
 inline constexpr int kLocationIso31662BindIndex = 3;
@@ -88,6 +124,16 @@ inline constexpr int kBreweryEnglishDescriptionBindIndex = 3;
 inline constexpr int kBreweryLocalNameBindIndex = 4;
 inline constexpr int kBreweryLocalDescriptionBindIndex = 5;
 
+inline constexpr int kUserLocationIdBindIndex = 1;
+inline constexpr int kUserFirstNameBindIndex = 2;
+inline constexpr int kUserLastNameBindIndex = 3;
+inline constexpr int kUserGenderBindIndex = 4;
+inline constexpr int kUserUsernameBindIndex = 5;
+inline constexpr int kUserBioBindIndex = 6;
+inline constexpr int kUserActivityWeightBindIndex = 7;
+inline constexpr int kUserEmailBindIndex = 8;
+inline constexpr int kUserDateOfBirthBindIndex = 9;
+
 SqliteStatementHandle PrepareStatement(const SqliteDatabaseHandle& db_handle,
                                        std::string_view sql,
                                        const char* action);

tooling/pipeline/includes/services/datetime/date_time_provider.h

@@ -18,7 +18,6 @@
  */
 class IDateTimeProvider {
  public:
-  /// @brief Virtual destructor for polymorphic cleanup.
   virtual ~IDateTimeProvider() = default;
 
   IDateTimeProvider() = default;

tooling/pipeline/includes/services/enrichment/enrichment_service.h

@@ -15,7 +15,6 @@
  */
 class IEnrichmentService {
  public:
-  /// @brief Virtual destructor for polymorphic cleanup.
   virtual ~IEnrichmentService() = default;
 
   /**

tooling/pipeline/includes/services/enrichment/mock_enrichment.h

@@ -1,13 +1,18 @@
-//
-// Created by aaronpo on 13/05/2026.
-//
-
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
+
+/**
+ * @file services/enrichment/mock_enrichment.h
+ * @brief No-op IEnrichmentService used when network enrichment is disabled.
+ */
+
 #include <string>
 
 #include "enrichment_service.h"
 
+/**
+ * @brief Enrichment service that returns no context for any location.
+ */
 class MockEnrichmentService final : public IEnrichmentService {
  public:
   std::string GetLocationContext(const Location& /*loc*/) override {

tooling/pipeline/includes/services/enrichment/wikipedia_service.h

@@ -15,21 +15,33 @@
 #include "services/logging/logger.h"
 #include "web_client/web_client.h"
 
-/// @brief Provides Wikipedia summary lookups backed by cached raw extracts.
+/**
+ * @brief Provides Wikipedia summary lookups backed by cached raw extracts.
+ */
 class WikipediaEnrichmentService final : public IEnrichmentService {
  public:
-  /// @brief Creates a new Wikipedia service with the provided web client.
+  /**
+   * @brief Creates a new Wikipedia service with the provided web client.
+   */
   explicit WikipediaEnrichmentService(std::unique_ptr<WebClient> client,
                                       std::shared_ptr<ILogger> logger);
 
-  /// @brief Returns the Wikipedia-derived context for a location.
+  /**
+   * @brief Returns the Wikipedia-derived context for a location.
+   */
   [[nodiscard]] std::string GetLocationContext(const Location& loc) override;
 
  private:
   std::string FetchExtract(std::string_view query);
   std::unique_ptr<WebClient> client_;
   std::shared_ptr<ILogger> logger_;
-  /// @brief Canonical cache for raw Wikipedia query extracts.
+  /**
+   * @brief Cache for raw Wikipedia query extracts, keyed by query string.
+   *
+   * GetLocationContext() always queries "brewing" and reuses "beer in
+   * {country}" for every city in that country, so caching avoids refetching
+   * the same extract across locations in a run.
+   */
   std::unordered_map<std::string, std::string> extract_cache_;
 };
 

tooling/pipeline/includes/services/logging/log_entry.h

@@ -20,10 +20,22 @@
  * @brief Severity levels supported by the logging infra.
  */
 enum class LogLevel {
-  Debug,  ///< Development/debugging information.
+  /**
-  Info,   ///< General informational messages.
+   * @brief Development/debugging information.
-  Warn,   ///< Warning conditions.
+   */
-  Error,  ///< Error conditions.
+  Debug,
+  /**
+   * @brief General informational messages.
+   */
+  Info,
+  /**
+   * @brief Warning conditions.
+   */
+  Warn,
+  /**
+   * @brief Error conditions.
+   */
+  Error,
 };
 
 /**
@@ -34,18 +46,44 @@ enum class LogLevel {
  * pipeline that emitted it.
  */
 enum class PipelinePhase {
-  Startup,                   ///< Initialization and validation.
+  /**
-  UserGeneration,            ///< User profile generation.
+   * @brief Initialization and validation.
-  BreweryAndBeerGeneration,  ///< Brewery and beer data generation.
+   */
-  CheckinGeneration,         ///< Checkin (visit) record generation.
+  Startup,
-  RatingGeneration,          ///< Rating and review generation.
+  /**
-  FollowGeneration,          ///< Follow relationship generation.
+   * @brief Location/context enrichment (e.g. Wikipedia lookups).
-  Teardown,                  ///< Finalization and cleanup.
+   */
+  Enrichment,
+  /**
+   * @brief User profile generation.
+   */
+  UserGeneration,
+  /**
+   * @brief Brewery and beer data generation.
+   */
+  BreweryAndBeerGeneration,
+  /**
+   * @brief Checkin (visit) record generation.
+   */
+  CheckinGeneration,
+  /**
+   * @brief Rating and review generation.
+   */
+  RatingGeneration,
+  /**
+   * @brief Follow relationship generation.
+   */
+  FollowGeneration,
+  /**
+   * @brief Finalization and cleanup.
+   */
+  Teardown,
 };
 
 /**
  * @struct LogDTO
- * @brief User-provided subset of log fields. Used to capture call-site info transparently.
+ * @brief User-provided subset of log fields. Used to capture call-site info
+ * transparently.
  */
 struct LogDTO {
   LogLevel level;
@@ -64,25 +102,35 @@ struct LogDTO {
  * before the entry is dispatched.
  */
 struct LogEntry {
-  /// @brief Timestamp when the entry was created.
+  /**
+   * @brief Timestamp when the entry was created.
+   */
   std::chrono::system_clock::time_point timestamp{};
 
-  /// @brief Source location where the log call was made.
+  /**
+   * @brief Source location where the log call was made.
+   */
   std::source_location origin{};
 
-  /// @brief Thread responsible for emitting the log.
+  /**
+   * @brief Thread responsible for emitting the log.
+   */
   std::thread::id thread_id{};
 
-
+  /**
-  /// @brief Severity level of this entry.
+   * @brief Severity level of this entry.
+   */
   LogLevel level;
 
-  /// @brief Pipeline phase associated with the entry.
+  /**
+   * @brief Pipeline phase associated with the entry.
+   */
   PipelinePhase phase;
 
-  /// @brief Log message text.
+  /**
+   * @brief Log message text.
+   */
   std::string message;
-
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_

tooling/pipeline/includes/services/logging/logger.h

@@ -39,7 +39,8 @@ class ILogger {
    */
   void Log(LogDTO payload,
            std::source_location origin = std::source_location::current(),
-           std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now(),
+           std::chrono::system_clock::time_point timestamp =
+               std::chrono::system_clock::now(),
            std::thread::id thread_id = std::this_thread::get_id()) {
     LogEntry entry;
     entry.timestamp = timestamp;

tooling/pipeline/includes/web_client/http_web_client.h

@@ -6,14 +6,13 @@
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_HTTP_WEB_CLIENT_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_HTTP_WEB_CLIENT_H_
 
-
-#include "web_client/web_client.h"
-#include "services/logging/logger.h"
-
 #include <memory>
 #include <string>
 #include <utility>
 
+#include "services/logging/logger.h"
+#include "web_client/web_client.h"
+
 /**
  * @brief WebClient implementation backed by cpp-httplib.
  *
@@ -34,7 +33,8 @@ public:
   /**
    * @brief Executes a blocking HTTP/HTTPS GET request against a full URL.
    *
-   * @param url Fully-qualified URL, e.g. "https://en.wikipedia.org/api/rest_v1/page/summary/Berlin"
+   * @param url Fully-qualified URL, e.g.
+   * "https://en.wikipedia.org/api/rest_v1/page/summary/Berlin"
    * @return Response body on HTTP 2xx; throws std::runtime_error otherwise.
    */
   std::string Get(const std::string& url) override;
@@ -52,5 +52,4 @@ public:
   std::shared_ptr<ILogger> logger_;
 };
 
-
 #endif

tooling/pipeline/includes/web_client/web_client.h

@@ -13,7 +13,6 @@
  */
 class WebClient {
  public:
-  /// @brief Virtual destructor for polymorphic cleanup.
   virtual ~WebClient() = default;
 
   /**

tooling/pipeline/personas.json

@@ -0,0 +1,42 @@
+[
+  {
+    "name": "Hophead Explorer",
+    "description": "Chases the newest hop varieties and double-digit IBUs, tracking hazy releases and limited tap takeovers across town.",
+    "style_affinities": ["American IPA", "Double IPA", "New England IPA", "Black IPA"]
+  },
+  {
+    "name": "Malt & Tradition Loyalist",
+    "description": "Prefers clean, balanced lagers brewed the way their region has brewed them for generations, and is quick to defend a well-made Helles.",
+    "style_affinities": ["Munich Helles", "Vienna Lager", "Märzen", "Festbier"]
+  },
+  {
+    "name": "Dark & Roasty Devotee",
+    "description": "Orders the darkest beer on the board year-round, drawn to roasted malt, coffee, and chocolate notes over carbonated lightness.",
+    "style_affinities": ["Imperial Stout", "Robust Porter", "Baltic Porter", "Oatmeal Stout"]
+  },
+  {
+    "name": "Sour & Wild Forager",
+    "description": "Seeks out barrel-aged, spontaneously fermented, and funky beers, and will travel for a fresh bottling of something wild.",
+    "style_affinities": ["Lambic", "Gueuze", "Flanders Red Ale", "Wild Ale"]
+  },
+  {
+    "name": "Session Sipper",
+    "description": "Values an easy-drinking pint that holds up over a long afternoon at the taproom more than raw intensity or novelty.",
+    "style_affinities": ["Session IPA", "Ordinary Bitter", "Cream Ale", "Blonde Ale"]
+  },
+  {
+    "name": "Belgian Abbey Pilgrim",
+    "description": "Collects abbey and trappist releases, drawn to the dried-fruit esters and warming strength of classic Belgian ales.",
+    "style_affinities": ["Belgian Tripel", "Belgian Dubbel", "Belgian Quadrupel", "Trappist Single"]
+  },
+  {
+    "name": "Wheat & Citrus Casual",
+    "description": "Reaches for something light, cloudy, and refreshing, usually with a citrus or coriander note, especially on a patio in summer.",
+    "style_affinities": ["Hefeweizen", "Witbier", "American Wheat Beer", "Berliner Weisse"]
+  },
+  {
+    "name": "Big & Boozy Connoisseur",
+    "description": "Sips slowly from a snifter, seeking out high-ABV releases meant for aging and savoring rather than quick refreshment.",
+    "style_affinities": ["English Barleywine", "Wee Heavy", "Doppelbock", "Old Ale"]
+  }
+]

tooling/pipeline/prompts/USER_GENERATION.md

@@ -0,0 +1,122 @@
+# FULL SYSTEM PROMPT
+
+You are a craft beer community profile writer. You write short, first-person
+biographies for fictional users of a brewery-discovery app, grounded in the
+exact name, locale, and persona provided. You do not invent the user's name --
+it is given to you and must not be altered, translated, or abbreviated beyond
+forming a username.
+
+You will receive the inputs like this:
+
+## NAME:
+
+[First name] [Last name]
+
+## GENDER:
+
+[Gender associated with the given first name]
+
+## CITY:
+
+[City Name]
+
+## COUNTRY:
+
+[Country Name]
+
+## PERSONA:
+
+[Persona archetype name]
+
+## PERSONA DESCRIPTION:
+
+[What this persona cares about and how they talk about beer]
+
+## STYLE AFFINITIES:
+
+[Comma-separated beer styles this persona favors]
+
+## CRITICAL OUTPUT FORMAT (READ CAREFULLY):
+
+ABSOLUTELY NO MARKDOWN FORMATTING. Do NOT wrap your response in json or ```
+blocks.
+
+Do not add markdown, code fences, or postscript around the final JSON object.
+Do not say "Here is the JSON" or "Enjoy!".
+
+The JSON must contain exactly three keys ("username", "bio",
+"activity_weight") in that order. Do not rename or add any other keys.
+
+ESCAPE ALL QUOTES inside the bio field using \", or use single quotes (' ')
+instead.
+
+DO NOT use actual line breaks (\n) inside any string. Keep the bio as one
+continuous string.
+
+The bio must be between 25 and 60 words, written in first person, and must
+read as something this specific person would write about themselves -- not a
+generic profile blurb.
+
+`activity_weight` is a number between 0 and 1 (inclusive) representing how
+often this persona checks in at breweries relative to other users. Persona
+archetypes implying frequent, habitual brewery visits should skew higher;
+casual or occasional-visitor personas should skew lower. Do not default to
+0.5 -- vary it meaningfully based on the persona description.
+
+Expected JSON format:
+
+```json
+{
+  "username": "a handle derived from the given name",
+  "bio": "The first-person bio goes here.",
+  "activity_weight": 0.62
+}
+```
+
+## CONTENT RULES AND CONSTRAINTS:
+
+### THE USERNAME:
+
+Derive the username from the given first and/or last name (e.g. lowercase,
+abbreviated, or combined with a short word or number tied to the persona's
+style affinities). Do not invent an unrelated handle. Do not include spaces.
+
+### THE BIO:
+
+Ground the bio in the supplied persona description and style affinities --
+mention at least one specific beer style from the style affinities list, in a
+way that sounds like a personal preference rather than a list. Reference the
+city or country naturally if it fits, but do not force it.
+
+### VOICE & PERSPECTIVE:
+
+Write in the first person ("I"/"my"). The tone should match the persona:
+an enthusiastic explorer sounds different from a relaxed, easy-drinking
+regular. Do not write in second or third person.
+
+### THE BLOCKLIST (FORBIDDEN CONCEPTS):
+
+You absolutely cannot use the following words and phrases. Make sure your
+final output doesn't have any of these:
+
+- "hidden gem"
+- "passion"
+- "authentic"
+- "craft beer enthusiast"
+- "beer connoisseur"
+- "journey"
+
+#### FORBIDDEN WRITING PATTERNS
+
+The following patterns are common AI writing pitfalls and must not appear in
+the bio:
+
+- Negative parallelism constructions: "It's not X, it's Y"
+- Inflated significance phrases: "stands as a testament," "plays a vital
+  role," "deeply rooted"
+- Superficial trailing analyses: sentences ending in -ing words that add
+  opinion without content
+- Promotional travel-copy tone: "breathtaking," "must-visit," "vibrant"
+- Overused conjunctive transitions used as sentence openers: "Moreover,"
+  "Furthermore," "In addition"
+- Rule of three: do not consistently organise ideas or examples in triplets

tooling/pipeline/run.sh

@@ -0,0 +1,8 @@
+./biergarten-pipeline \
+    --model ../models/google_gemma-4-E4B-it-Q6_K.gguf \
+    --temperature 1.0 \
+    --top-p 0.95 \
+    --top-k 64 \
+    --n-ctx 8192 \
+    --location-count 15 \
+    --prompt-dir ../prompts

tooling/pipeline/src/application_options/parse_arguments.cc

@@ -15,8 +15,6 @@ std::optional<ApplicationOptions> ParseArguments(
 
   opt("help,h", "Produce help message");
 
-  // Defaults sourced from SamplingOptions{} so the CLI and LlamaGenerator
-  // share a single source of truth — changing the struct updates both.
   auto add_sampling_options = [&]() -> void {
     const SamplingOptions sampling_defaults{};
     opt("temperature",
@@ -53,7 +51,8 @@ std::optional<ApplicationOptions> ParseArguments(
         prog_opts::value<std::string>()->default_value("pipeline.log"),
         "Path for application logs");
     opt("prompt-dir", prog_opts::value<std::string>()->default_value(""),
-        "Directory containing named prompt files (e.g. BREWERY_GENERATION.md)."
+        "Directory containing named prompt files (e.g. "
+        "BREWERY_GENERATION.md)."
         " Required when not using --mocked.");
     opt("location-count", prog_opts::value<uint32_t>()->default_value(10));
   };
@@ -108,10 +107,12 @@ std::optional<ApplicationOptions> ParseArguments(
     const std::string model_path = var_map["model"].as<std::string>();
     const int n_gpu_layers = var_map["n-gpu-layers"].as<int>();
 
-    // Enforce mutual exclusivity before any further configuration is applied.
+    // Enforce mutual exclusivity before any further configuration is
+    // applied.
     if (use_mocked && !model_path.empty()) {
       const std::string msg =
-          "Invalid arguments: --mocked and --model are mutually exclusive";
+          "Invalid arguments: --mocked and --model are mutually "
+          "exclusive";
       if (logger) {
         logger->Log(LogDTO{.level = LogLevel::Error,
                            .phase = PipelinePhase::Startup,
@@ -124,7 +125,8 @@ std::optional<ApplicationOptions> ParseArguments(
 
     if (!use_mocked && model_path.empty()) {
       const std::string msg =
-          "Invalid arguments: either --mocked or --model must be specified";
+          "Invalid arguments: either --mocked or --model must be "
+          "specified";
       if (logger) {
         logger->Log(LogDTO{.level = LogLevel::Error,
                            .phase = PipelinePhase::Startup,
@@ -139,7 +141,8 @@ std::optional<ApplicationOptions> ParseArguments(
     // generator has no use for it and should not require it to be present.
     if (!use_mocked && options.pipeline.prompt_dir.empty()) {
       const std::string msg =
-          "Invalid arguments: --prompt-dir is required when not using --mocked";
+          "Invalid arguments: --prompt-dir is required when not using "
+          "--mocked";
       if (logger) {
         logger->Log({.level = LogLevel::Error,
                      .phase = PipelinePhase::Startup,
@@ -152,7 +155,6 @@ std::optional<ApplicationOptions> ParseArguments(
 
     options.generator.use_mocked = use_mocked;
     options.generator.model_path = model_path;
-    // options.generator.n_gpu_layers = n_gpu_layers;
 
     // Only populate sampling config when the user explicitly overrides at
     // least one value. Leaving it as std::nullopt lets LlamaGenerator fall

tooling/pipeline/src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc
- * @brief BiergartenDataGenerator constructor implementation.
+ * @brief BiergartenPipelineOrchestrator constructor implementation.
  */
 
 #include "biergarten_pipeline_orchestrator.h"
@@ -12,9 +12,12 @@ BiergartenPipelineOrchestrator::BiergartenPipelineOrchestrator(
     std::unique_ptr<IEnrichmentService> context_service,
     std::unique_ptr<DataGenerator> generator,
     std::unique_ptr<IExportService> exporter,
-    const ApplicationOptions &app_options)
+    std::unique_ptr<ICuratedDataService> curated_data_service,
+    const ApplicationOptions& application_options)
   : logger_(std::move(logger)),
     context_service_(std::move(context_service)),
     generator_(std::move(generator)),
     exporter_(std::move(exporter)),
-      application_options_(app_options) {}
+    curated_data_service_(std::move(curated_data_service)),
+    application_options_(application_options) {
+}

tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_breweries.cc

@@ -1,10 +1,11 @@
 /**
  * @file biergarten_pipeline_orchestrator/generate_breweries.cc
- * @brief BiergartenDataGenerator::GenerateBreweries() implementation.
+ * @brief BiergartenPipelineOrchestrator::GenerateBreweries() implementation.
  */
 
 #include <chrono>
 #include <format>
+#include <optional>
 
 #include "biergarten_pipeline_orchestrator.h"
 #include "services/logging/logger.h"
@@ -19,39 +20,57 @@ void BiergartenPipelineOrchestrator::GenerateBreweries(
   size_t skipped_count = 0;
   size_t export_failed_count = 0;
 
-  for (const auto& [location, region_context] : cities) {
+  const auto generate_record =
+      [this, &skipped_count](
+          const Location& location,
+          const std::string& region_context) -> std::optional<BreweryRecord> {
     try {
       const BreweryResult brewery =
           generator_->GenerateBrewery(location, region_context);
-
+      return BreweryRecord{.location = location, .brewery = brewery};
-      const GeneratedBrewery gen{.location = location, .brewery = brewery};
+    } catch (const std::exception& e) {
-
+      ++skipped_count;
-      generated_breweries_.push_back(gen);
-
-      try {
-        exporter_->ProcessRecord(gen);
-      } catch (const std::exception& export_exception) {
-        ++export_failed_count;
 
       logger_->Log(
           {.level = LogLevel::Warn,
            .phase = PipelinePhase::BreweryAndBeerGeneration,
-             .message =
+           .message = std::format("[Pipeline] Skipping city '{}' ({}): brewery "
-                 std::format("[Pipeline] Generated brewery for '{}' ({}) but SQLite export failed: {}",
+                                  "generation failed: {}",
-                 location.city, location.country, export_exception.what())});
-      }
-    } catch (const std::exception& e) {
-      ++skipped_count;
-
-      logger_->Log({.level = LogLevel::Warn,
-                    .phase = PipelinePhase::BreweryAndBeerGeneration,
-                    .message = std::format("[Pipeline] Skipping city '{}' ({}): brewery generation failed: {}",
                                   location.city, location.country, e.what())});
+      return std::nullopt;
     }
+  };
+
+  const auto export_record = [this, &export_failed_count](
+                                 const BreweryRecord& record) {
+    try {
+      exporter_->ProcessRecord(record);
+    } catch (const std::exception& export_exception) {
+      ++export_failed_count;
+      logger_->Log(
+          {.level = LogLevel::Warn,
+           .phase = PipelinePhase::BreweryAndBeerGeneration,
+           .message = std::format("[Pipeline] Generated brewery for '{}' ({}) "
+                                  "but SQLite export failed: {}",
+                                  record.location.city, record.location.country,
+                                  export_exception.what())});
+    }
+  };
+
+  for (const auto& [location, region_context] : cities) {
+    const std::optional<BreweryRecord> record =
+        generate_record(location, region_context);
+    if (!record.has_value()) {
+      continue;
+    }
+
+    generated_breweries_.push_back(*record);
+    export_record(*record);
   }
 
   if (skipped_count > 0) {
-    logger_->Log({.level = LogLevel::Warn,
+    logger_->Log(
+        {.level = LogLevel::Warn,
          .phase = PipelinePhase::BreweryAndBeerGeneration,
          .message = std::format(
              "[Pipeline] Skipped {} city/cities due to generation errors",
@@ -59,10 +78,11 @@ void BiergartenPipelineOrchestrator::GenerateBreweries(
   }
 
   if (export_failed_count > 0) {
-    logger_->Log({.level = LogLevel::Warn,
+    logger_->Log(
+        {.level = LogLevel::Warn,
          .phase = PipelinePhase::Teardown,
-                  .message = std::format(
+         .message = std::format("[Pipeline] Failed to export {} generated "
-                      "[Pipeline] Failed to export {} generated brewery/breweries to SQLite",
+                                "brewery/breweries to SQLite",
                                 export_failed_count)});
   }
 }

tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc

@@ -0,0 +1,188 @@
+/**
+ * @file biergarten_pipeline_orchestrator/generate_users.cc
+ * @brief BiergartenPipelineOrchestrator::GenerateUsers() implementation.
+ */
+
+#include <cctype>
+#include <chrono>
+#include <format>
+#include <optional>
+#include <random>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <unordered_set>
+
+#include "biergarten_pipeline_orchestrator.h"
+#include "json_handling/json_loader.h"
+#include "services/logging/logger.h"
+
+namespace {
+std::string Sanitize(std::string_view value) {
+  std::string out;
+  out.reserve(value.size());
+  for (const char character : value) {
+    if (std::isalnum(static_cast<unsigned char>(character)) != 0) {
+      out.push_back(static_cast<char>(
+        std::tolower(static_cast<unsigned char>(character))));
+    }
+  }
+  return out;
+}
+
+std::string BuildEmail(const Name& name,
+                       std::unordered_set<std::string>& used_local_parts) {
+  const std::string base =
+      std::format("{}.{}", Sanitize(name.first_name), Sanitize(name.last_name));
+
+  std::string local_part = base;
+  uint32_t suffix = 1;
+
+  while (used_local_parts.contains(local_part)) {
+    local_part = std::format("{}{}", base, suffix);
+    ++suffix;
+  }
+
+  used_local_parts.insert(local_part);
+
+  return std::format("{}@thebiergarten.app", local_part);
+}
+
+std::string GenerateDateOfBirth(std::mt19937& rng) {
+  using namespace std::chrono;
+
+  constexpr int kMinAge = 19;
+  constexpr int kMaxAge = 48;
+  constexpr int kMaxDayOffset = 364;
+
+  std::uniform_int_distribution<int> age_dist(kMinAge, kMaxAge);
+  std::uniform_int_distribution<int> day_offset_dist(0, kMaxDayOffset);
+
+  const year_month_day today{floor<days>(system_clock::now())};
+  const year_month_day birth_year_anchor{today.year() - years{age_dist(rng)},
+                                         today.month(), today.day()};
+  const sys_days birth_date =
+      sys_days{birth_year_anchor} - days{day_offset_dist(rng)};
+  const year_month_day birth_ymd{birth_date};
+
+  return std::format("{:04}-{:02}-{:02}", static_cast<int>(birth_ymd.year()),
+                     static_cast<unsigned>(birth_ymd.month()),
+                     static_cast<unsigned>(birth_ymd.day()));
+}
+} // namespace
+
+void BiergartenPipelineOrchestrator::GenerateUsers(
+    std::span<const EnrichedCity> cities) {
+  logger_->Log({.level = LogLevel::Info,
+                .phase = PipelinePhase::UserGeneration,
+                .message = "=== SAMPLE USER GENERATION ==="});
+
+  const std::vector<UserPersona> personas =
+      curated_data_service_->LoadPersonas("personas.json");
+
+  if (personas.empty()) {
+    throw std::runtime_error(
+        "No personas available in personas.json for user generation");
+  }
+
+  const NamesByCountry names_by_country =
+      curated_data_service_->LoadNamesByCountry(
+          "forenames-by-country.json", "surnames-by-country.json");
+
+  std::mt19937 rng(std::random_device{}());
+  std::uniform_int_distribution<size_t> persona_dist(0, personas.size() - 1);
+
+  generated_users_.clear();
+  size_t skipped_count = 0;
+  size_t export_failed_count = 0;
+
+  const auto generate_record =
+      [this, &rng, &skipped_count](
+      const EnrichedCity& city, const UserPersona& persona,
+      const Name& sampled_name) -> std::optional<UserRecord> {
+    try {
+      std::unordered_set<std::string> used_email_local_parts;
+
+      const UserResult user =
+          generator_->GenerateUser(city, persona, sampled_name);
+
+      return UserRecord{
+          .location = city.location,
+          .user = user,
+          .email = BuildEmail(sampled_name, used_email_local_parts),
+          .date_of_birth = GenerateDateOfBirth(rng),
+      };
+    } catch (const std::exception& e) {
+      ++skipped_count;
+      logger_->Log({.level = LogLevel::Warn,
+                    .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
+                        "[Pipeline] Skipping city '{}' ({}): "
+                        "user generation failed: {}",
+                        city.location.city, city.location.country, e.what())});
+      return std::nullopt;
+    }
+  };
+
+  const auto export_record = [this,
+        &export_failed_count](const UserRecord& record) {
+    try {
+      exporter_->ProcessRecord(record);
+    } catch (const std::exception& export_exception) {
+      ++export_failed_count;
+
+      logger_->Log(
+      {.level = LogLevel::Warn,
+       .phase = PipelinePhase::UserGeneration,
+       .message = std::format("[Pipeline] Generated user for '{}' ({}) but "
+                              "SQLite export failed: {}",
+                              record.location.city, record.location.country,
+                              export_exception.what())});
+    }
+  };
+
+  for (const auto& city : cities) {
+    const std::optional<Name> sampled_name =
+        names_by_country.SampleName(city.location.iso3166_1, rng);
+
+    if (!sampled_name.has_value()) {
+      ++skipped_count;
+      logger_->Log({.level = LogLevel::Warn,
+                    .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
+                        "[Pipeline] Skipping city '{}' ({}): no names "
+                        "available for country '{}'",
+                        city.location.city, city.location.country,
+                        city.location.iso3166_1)});
+      continue;
+    }
+
+    const UserPersona& persona = personas[persona_dist(rng)];
+
+    const std::optional<UserRecord> record =
+        generate_record(city, persona, *sampled_name);
+    if (!record.has_value()) {
+      continue;
+    }
+
+    generated_users_.push_back(*record);
+    export_record(*record);
+  }
+
+  if (skipped_count > 0) {
+    logger_->Log(
+    {.level = LogLevel::Warn,
+     .phase = PipelinePhase::UserGeneration,
+     .message = std::format(
+         "[Pipeline] Skipped {} city/cities during user generation",
+         skipped_count)});
+  }
+
+  if (export_failed_count > 0) {
+    logger_->Log({.level = LogLevel::Warn,
+                  .phase = PipelinePhase::Teardown,
+                  .message = std::format("[Pipeline] Failed to export {} "
+                                         "generated user/users to SQLite",
+                                         export_failed_count)});
+  }
+}

tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/log_results.cc
- * @brief BiergartenDataGenerator::LogResults() implementation.
+ * @brief BiergartenPipelineOrchestrator::LogResults() implementation.
  */
 
 #include <boost/json/array.hpp>
@@ -10,11 +10,12 @@
 #include "../../includes/json_handling/pretty_print.h"
 #include "biergarten_pipeline_orchestrator.h"
 #include "services/logging/logger.h"
+
 void BiergartenPipelineOrchestrator::LogResults() const {
-  boost::json::array output;
+  boost::json::array brewery_output;
 
   for (const auto& [location, brewery] : generated_breweries_) {
-    output.push_back(boost::json::object{
+    brewery_output.push_back(boost::json::object{
         {"name_en", brewery.name_en},
         {"description_en", brewery.description_en},
         {"name_local", brewery.name_local},
@@ -29,9 +30,30 @@ void BiergartenPipelineOrchestrator::LogResults() const {
                      }}});
   }
 
-  std::ostringstream oss;
+  std::ostringstream brewery_oss;
-  PrettyPrint(oss, output);
+  PrettyPrint(brewery_oss, brewery_output);
   logger_->Log({.level = LogLevel::Info,
                 .phase = PipelinePhase::Teardown,
-                .message = oss.str()});
+                .message = brewery_oss.str()});
+
+  boost::json::array user_output;
+
+  for (const auto& generated_user : generated_users_) {
+    user_output.push_back(boost::json::object{
+        {"first_name", generated_user.user.first_name},
+        {"last_name", generated_user.user.last_name},
+        {"gender", generated_user.user.gender},
+        {"username", generated_user.user.username},
+        {"bio", generated_user.user.bio},
+        {"activity_weight", generated_user.user.activity_weight},
+        {"email", generated_user.email},
+        {"date_of_birth", generated_user.date_of_birth},
+    });
+  }
+
+  std::ostringstream user_oss;
+  PrettyPrint(user_oss, user_output);
+  logger_->Log({.level = LogLevel::Info,
+                .phase = PipelinePhase::Teardown,
+                .message = user_oss.str()});
 }

tooling/pipeline/src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc

@@ -1,6 +1,7 @@
 /**
  * @file biergarten_pipeline_orchestrator/query_cities_with_countries.cc
- * @brief BiergartenDataGenerator::QueryCitiesWithCountries() implementation.
+ * @brief BiergartenPipelineOrchestrator::QueryCitiesWithCountries()
+ * implementation.
  */
 
 #include <algorithm>
@@ -22,7 +23,7 @@ BiergartenPipelineOrchestrator::QueryCitiesWithCountries() {
 
   const std::filesystem::path locations_path = "locations.json";
 
-  auto all_locations = JsonLoader::LoadLocations(locations_path, logger_);
+  auto all_locations = curated_data_service_->LoadLocations(locations_path);
 
   const size_t sample_count = std::min(
       static_cast<size_t>(application_options_.pipeline.location_count),

tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/run.cc
- * @brief BiergartenDataGenerator::Run() implementation.
+ * @brief BiergartenPipelineOrchestrator::Run() implementation.
  */
 
 #include <chrono>
@@ -22,42 +22,40 @@ bool BiergartenPipelineOrchestrator::Run() {
     for (auto& city : cities) {
       try {
         std::string region_context = context_service_->GetLocationContext(city);
-        // logger_->Log(LogLevel::Debug, PipelinePhase::UserGeneration,
-        //              "[Pipeline] Context for '" + city.city + "' (" +
-        //              city.iso3166_2 + ") gathered:\n" + region_context);
 
         enriched.push_back(
             EnrichedCity{.location = std::move(city),
                          .region_context = std::move(region_context)});
       } catch (const std::exception& exception) {
         ++skipped_count;
-        logger_->Log(
+        logger_->Log({.level = LogLevel::Warn,
-            {.level = LogLevel::Warn,
+                      .phase = PipelinePhase::Enrichment,
-             .phase = PipelinePhase::UserGeneration,
                       .message = std::format(
-                 "[Pipeline] Skipping city '{}' ({}): context lookup failed: {}",
+                          "[Pipeline] Skipping city '{}' ({}): context "
+                          "lookup failed: {}",
                           city.city, city.country, exception.what())});
       }
     }
 
     if (skipped_count > 0) {
-      logger_->Log({.level = LogLevel::Warn,
+      logger_->Log(
-                    .phase = PipelinePhase::UserGeneration,
+          {.level = LogLevel::Warn,
-                    .message = std::format(
+           .phase = PipelinePhase::Enrichment,
-                        "[Pipeline] Skipped {} city/cities due to context lookup errors",
+           .message = std::format("[Pipeline] Skipped {} city/cities due "
+                                  "to context lookup errors",
                                   skipped_count)});
     }
 
+    this->GenerateUsers(enriched);
     this->GenerateBreweries(enriched);
     exporter_->Finalize();
     this->LogResults();
     return true;
   } catch (const std::exception& e) {
-    logger_->Log(
+    logger_->Log({.level = LogLevel::Error,
-        {.level = LogLevel::Error,
                   .phase = PipelinePhase::Teardown,
-         .message =
+                  .message = std::format(
-             std::format("Pipeline execution failed with error: {}", e.what())});
+                      "Pipeline execution failed with error: {}", e.what())});
     return false;
   }
 }

tooling/pipeline/src/data_generation/llama/generate_brewery.cc

@@ -12,6 +12,7 @@
 #include <string_view>
 #include <vector>
 
+#include "data_generation/json_grammars.h"
 #include "data_generation/llama_generator.h"
 #include "data_generation/llama_generator_helpers.h"
 
@@ -32,19 +33,6 @@ static std::string FormatLocalLanguageCodes(
   return formatted;
 }
 
-// GBNF grammar for structured brewery JSON output.
-// @TODO move to a separate gbnf file if it grows in complexity or is shared
-// across modules.
-static constexpr std::string_view kBreweryJsonGrammar = R"json_brewery(
-root ::= thought-block "{" ws "\"name_en\"" ws ":" ws string ws "," ws "\"description_en\"" ws ":" ws string ws "," ws "\"name_local\"" ws ":" ws string ws "," ws "\"description_local\"" ws ":" ws string ws "}" ws
-thought-block ::= [^{]*
-ws ::= [ \t\n\r]*
-string ::= "\"" char+ "\""
-char ::= [^"\\\x7F\x00-\x1F] | [\\] escape
-escape ::= ["\\/bfnrt] | "u" hex hex hex hex
-hex ::= [0-9a-fA-F]
-)json_brewery";
-
 static constexpr int kBreweryInitialMaxTokens = 2800;
 
 BreweryResult LlamaGenerator::GenerateBrewery(
@@ -83,15 +71,14 @@ BreweryResult LlamaGenerator::GenerateBrewery(
 
   /**
    * RETRY LOOP with validation and error correction
-   * Attempts to generate valid brewery data up to 3 times, with feedback-based
+   * Attempts to generate valid brewery data up to 3 times, with
-   * refinement
+   * feedback-based refinement
    */
   constexpr int max_attempts = 3;
   std::string raw;
   std::string last_error;
 
   // Token budget: too small risks truncating valid JSON mid-string.
-  // Start conservatively but allow adaptive increases on truncation.
   int max_tokens = kBreweryInitialMaxTokens;
 
   // Limit output length to keep it concise and focused
@@ -120,7 +107,8 @@ BreweryResult LlamaGenerator::GenerateBrewery(
         logger_->Log(
             {.level = LogLevel::Info,
              .phase = PipelinePhase::BreweryAndBeerGeneration,
-             .message = std::format("LlamaGenerator: successfully generated brewery data on attempt {}",
+             .message = std::format("LlamaGenerator: successfully generated "
+                                    "brewery data on attempt {}",
                                     attempt + 1)});
       }
 
@@ -134,32 +122,37 @@ BreweryResult LlamaGenerator::GenerateBrewery(
       logger_->Log(
           {.level = LogLevel::Warn,
            .phase = PipelinePhase::BreweryAndBeerGeneration,
-           .message =
+           .message = std::format(
-               std::format("LlamaGenerator: malformed brewery JSON (attempt {}): {}",
+               "LlamaGenerator: malformed brewery JSON (attempt {}): {}",
                attempt + 1, *validation_error)});
     }
 
     // Update prompt with error details to guide LLM toward correct output.
     user_prompt = std::format(
         "Your previous response was invalid. Error: {}\nReturn the thought "
-        "process before the JSON if needed, then return ONLY valid JSON with "
+        "process before the JSON if needed, then return ONLY valid JSON "
-        "exactly these keys, in this exact order: {{\"name_en\": \"<English "
+        "with "
+        "exactly these keys, in this exact order: {{\"name_en\": "
+        "\"<English "
         "brewery name>\", \"description_en\": \"<English single-paragraph "
-        "description>\", \"name_local\": \"<local-language brewery name>\", "
+        "description>\", \"name_local\": \"<local-language brewery "
+        "name>\", "
         "\"description_local\": \"<local-language single-paragraph "
-        "description>\"}}.\nDo not include markdown, comments, extra keys, or "
+        "description>\"}}.\nDo not include markdown, comments, extra keys, "
-        "literal placeholder values.\n\nKeep the JSON strings concise enough "
+        "or "
+        "literal placeholder values.\n\nKeep the JSON strings concise "
+        "enough "
         "to fit within the token budget.\n\n{}",
         *validation_error, retry_location);
   }
 
   // All retry attempts exhausted: log failure and throw exception
   if (logger_) {
-    logger_->Log(
+    logger_->Log({.level = LogLevel::Error,
-        {.level = LogLevel::Error,
                   .phase = PipelinePhase::BreweryAndBeerGeneration,
                   .message = std::format(
-         "LlamaGenerator: malformed brewery response after {} attempts: {}",
+                      "LlamaGenerator: malformed brewery "
+                      "response after {} attempts: {}",
                       max_attempts, last_error.empty() ? raw : last_error)});
   }
   throw std::runtime_error("LlamaGenerator: malformed brewery response");

tooling/pipeline/src/data_generation/llama/generate_user.cc

@@ -1,24 +1,112 @@
 /**
  * @file data_generation/llama/generate_user.cc
- * @brief Generates locale-aware user profiles with strict two-line formatting,
+ * @brief Builds persona/name-grounded user prompts, performs retry-based
- * retry handling, and output sanitization for downstream parsing.
+ * inference, and validates structured JSON output for user records.
  */
 
-
 #include <format>
+#include <optional>
+#include <stdexcept>
 #include <string>
+#include <string_view>
 
+#include "data_generation/json_grammars.h"
 #include "data_generation/llama_generator.h"
 #include "data_generation/llama_generator_helpers.h"
 
-// TODO: Implement locale-aware user profile generation.
+static constexpr int kUserInitialMaxTokens = 1200;
-// Current implementation returns a hardcoded test value and ignores the
+
-// locale parameter. Future implementation should:
+UserResult LlamaGenerator::GenerateUser(const EnrichedCity& city,
-// 1. Load a USER_GENERATION.md prompt template with locale context
+                                        const UserPersona& persona,
-// 2. Perform LLM inference with locale-specific username/bio generation
+                                        const Name& name) {
-// 3. Parse and validate JSON output with retry handling (similar to brewery)
+  std::string style_affinities;
-// 4. Return locale-aware username and biography
+  for (const std::string& style : persona.style_affinities) {
-UserResult LlamaGenerator::GenerateUser(const std::string& locale) {
+    if (!style_affinities.empty()) {
-  return {.username = "test_user",
+      style_affinities += ", ";
-          .bio = std::format("This is a test user profile from {}.", locale)};
+    }
+    style_affinities += style;
+  }
+
+  const std::string system_prompt = prompt_directory_->Load("USER_GENERATION");
+
+  std::string user_prompt = std::format(
+      "## NAME:\n{} {}\n\n## GENDER:\n{}\n\n## CITY:\n{}\n\n## "
+      "COUNTRY:\n{}\n\n"
+      "## PERSONA:\n{}\n\n## PERSONA DESCRIPTION:\n{}\n\n## STYLE "
+      "AFFINITIES:\n{}",
+      name.first_name, name.last_name, name.gender, city.location.city,
+      city.location.country, persona.name, persona.description,
+      style_affinities);
+
+  const std::string retry_context = std::format(
+      "Name: {} {}\nCity: {}, {}\nPersona: {}", name.first_name, name.last_name,
+      city.location.city, city.location.country, persona.name);
+
+  constexpr int max_attempts = 3;
+  std::string raw;
+  std::string last_error;
+  int max_tokens = kUserInitialMaxTokens;
+
+  for (int attempt = 0; attempt < max_attempts; ++attempt) {
+    raw = this->Infer(system_prompt, user_prompt, max_tokens, kUserJsonGrammar);
+    if (logger_) {
+      logger_->Log(
+          {.level = LogLevel::Debug,
+           .phase = PipelinePhase::UserGeneration,
+           .message = std::format("LlamaGenerator: raw output (attempt {}): {}",
+                                  attempt + 1, raw)});
+    }
+
+    UserResult user;
+    const std::optional<std::string> validation_error =
+        ValidateUserJson(raw, user);
+
+    if (!validation_error.has_value()) {
+      if (logger_) {
+        logger_->Log(
+            {.level = LogLevel::Info,
+             .phase = PipelinePhase::UserGeneration,
+             .message = std::format("LlamaGenerator: successfully "
+                                    "generated user data on attempt {}",
+                                    attempt + 1)});
+      }
+
+      user.first_name = name.first_name;
+      user.last_name = name.last_name;
+      user.gender = name.gender;
+      return user;
+    }
+
+    last_error = *validation_error;
+    if (logger_) {
+      logger_->Log({.level = LogLevel::Warn,
+                    .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
+                        "LlamaGenerator: malformed user JSON (attempt {}): {}",
+                        attempt + 1, *validation_error)});
+    }
+
+    user_prompt = std::format(
+        "Your previous response was invalid. Error: {}\nReturn the thought "
+        "process before the JSON if needed, then return ONLY valid JSON "
+        "with "
+        "exactly these keys, in this exact order: {{\"username\": "
+        "\"<handle "
+        "derived from the given name>\", \"bio\": \"<first-person bio "
+        "grounded in the persona>\", \"activity_weight\": <number between "
+        "0 "
+        "and 1>}}.\nDo not include markdown, comments, extra keys, or "
+        "literal placeholder values.\n\n{}",
+        *validation_error, retry_context);
+  }
+
+  if (logger_) {
+    logger_->Log({.level = LogLevel::Error,
+                  .phase = PipelinePhase::UserGeneration,
+                  .message = std::format(
+                      "LlamaGenerator: malformed user response "
+                      "after {} attempts: {}",
+                      max_attempts, last_error.empty() ? raw : last_error)});
+  }
+  throw std::runtime_error("LlamaGenerator: malformed user response");
 }

tooling/pipeline/src/data_generation/llama/helpers.cc

@@ -9,6 +9,7 @@
 #include <boost/json.hpp>
 #include <cctype>
 #include <optional>
+#include <span>
 #include <stdexcept>
 #include <string>
 #include <string_view>
@@ -76,7 +77,7 @@ bool ReadRequiredTrimmedStringField(const boost::json::object& obj,
   return !out.empty();
 }
 
-bool HasSchemaPlaceholder(const std::array<std::string*, 4>& values) {
+bool HasSchemaPlaceholder(std::span<std::string* const> values) {
   for (const std::string* value : values) {
     std::string lowered = *value;
     std::ranges::transform(lowered, lowered.begin(),
@@ -207,3 +208,58 @@ std::optional<std::string> ValidateBreweryJson(const std::string& raw,
 
   return std::nullopt;
 }
+
+std::optional<std::string> ValidateUserJson(const std::string& raw,
+                                            UserResult& user_out) {
+  boost::system::error_code error_code;
+  const std::string_view raw_view(raw);
+  const size_t opening_brace = raw_view.find('{');
+  if (opening_brace == std::string_view::npos) {
+    return "JSON parse error: missing opening brace '{'";
+  }
+
+  const std::string_view json_payload = raw_view.substr(opening_brace);
+  boost::json::value json_value = boost::json::parse(json_payload, error_code);
+  if (error_code) {
+    return "JSON parse error: " + error_code.message();
+  }
+
+  if (!json_value.is_object()) {
+    return "JSON root must be an object";
+  }
+
+  const auto& obj = json_value.get_object();
+  if (obj.size() != 3) {
+    return "JSON object must contain exactly three keys";
+  }
+
+  std::string validation_error;
+  if (!ReadRequiredTrimmedStringField(obj, "username", user_out.username,
+                                      &validation_error)) {
+    return validation_error;
+  }
+
+  if (!ReadRequiredTrimmedStringField(obj, "bio", user_out.bio,
+                                      &validation_error)) {
+    return validation_error;
+  }
+
+  const boost::json::value* activity_weight_field =
+      obj.if_contains("activity_weight");
+  if (activity_weight_field == nullptr || !activity_weight_field->is_number()) {
+    return "Missing or invalid numeric field: activity_weight";
+  }
+
+  const double activity_weight = activity_weight_field->to_number<double>();
+  if (activity_weight < 0.0 || activity_weight > 1.0) {
+    return "activity_weight must be between 0 and 1";
+  }
+  user_out.activity_weight = static_cast<float>(activity_weight);
+
+  const std::array schema_placeholders = {&user_out.username, &user_out.bio};
+  if (HasSchemaPlaceholder(schema_placeholders)) {
+    return "JSON appears to be a schema placeholder, not content";
+  }
+
+  return std::nullopt;
+}

tooling/pipeline/src/data_generation/mock/deterministic_hash.cc

@@ -14,3 +14,13 @@ size_t MockGenerator::DeterministicHash(const Location& location) {
   boost::hash_combine(seed, location.country);
   return seed;
 }
+
+size_t MockGenerator::DeterministicHash(const Location& location,
+                                        const UserPersona& persona,
+                                        const Name& name) {
+  size_t seed = DeterministicHash(location);
+  boost::hash_combine(seed, persona.name);
+  boost::hash_combine(seed, name.first_name);
+  boost::hash_combine(seed, name.last_name);
+  return seed;
+}

tooling/pipeline/src/data_generation/mock/generate_user.cc

@@ -1,22 +1,31 @@
 /**
  * @file data_generation/mock/generate_user.cc
- * @brief Generates deterministic mock user profiles by hashing locale values
+ * @brief Generates deterministic mock user profiles by hashing city, persona,
- * into predefined username and bio collections.
+ * and sampled name into predefined username and bio collections.
  */
 
-#include <functional>
-#include <string>
 #include <string_view>
 
 #include "data_generation/mock_generator.h"
 
-UserResult MockGenerator::GenerateUser(const std::string& locale) {
+UserResult MockGenerator::GenerateUser(const EnrichedCity& city,
-  const size_t hash = std::hash<std::string>{}(locale);
+                                       const UserPersona& persona,
+                                       const Name& name) {
+  const size_t hash = DeterministicHash(city.location, persona, name);
 
-  UserResult result;
   const std::string_view username = kUsernames[hash % kUsernames.size()];
   const std::string_view bio = kBios[hash / kBioHashStride % kBios.size()];
-  result.username = username;
+  const float activity_weight =
-  result.bio = bio;
+      static_cast<float>(hash / kActivityWeightHashStride %
-  return result;
+                         kActivityWeightHashRange) /
+      static_cast<float>(kActivityWeightHashRange);
+
+  return {
+      .first_name = name.first_name,
+      .last_name = name.last_name,
+      .gender = name.gender,
+      .username = std::string(username),
+      .bio = std::string(bio),
+      .activity_weight = activity_weight,
+  };
 }

tooling/pipeline/src/data_model/names_by_country.cc

@@ -0,0 +1,40 @@
+/**
+ * @file data_model/names_by_country.cc
+ * @brief NamesByCountry::SampleName() implementation.
+ */
+
+#include "data_model/names_by_country.h"
+
+#include <utility>
+
+NamesByCountry::NamesByCountry(
+    std::unordered_map<std::string, std::vector<ForenameEntry>>
+        forenames_by_country,
+    std::unordered_map<std::string, std::vector<std::string>>
+        surnames_by_country)
+    : forenames_by_country_(std::move(forenames_by_country)),
+      surnames_by_country_(std::move(surnames_by_country)) {}
+
+std::optional<Name> NamesByCountry::SampleName(const std::string& iso3166_1,
+                                               std::mt19937& rng) const {
+  const auto forenames_it = forenames_by_country_.find(iso3166_1);
+  const auto surnames_it = surnames_by_country_.find(iso3166_1);
+
+  if (forenames_it == forenames_by_country_.end() ||
+      surnames_it == surnames_by_country_.end() ||
+      forenames_it->second.empty() || surnames_it->second.empty()) {
+    return std::nullopt;
+  }
+
+  const std::vector<ForenameEntry>& forenames = forenames_it->second;
+  const std::vector<std::string>& surnames = surnames_it->second;
+
+  std::uniform_int_distribution<size_t> forename_dist(0, forenames.size() - 1);
+  std::uniform_int_distribution<size_t> surname_dist(0, surnames.size() - 1);
+
+  const ForenameEntry& forename = forenames[forename_dist(rng)];
+
+  return Name{.first_name = forename.name,
+              .last_name = surnames[surname_dist(rng)],
+              .gender = forename.gender};
+}

tooling/pipeline/src/json_handling/json_loader.cc

@@ -6,16 +6,18 @@
 
 #include "json_handling/json_loader.h"
 
-#include <format>
-#include "services/logging/logger.h"
-#include <iostream>
-
 #include <boost/json.hpp>
+#include <format>
 #include <fstream>
+#include <iostream>
 #include <sstream>
 #include <stdexcept>
 #include <string>
 #include <string_view>
+#include <unordered_map>
+#include <utility>
+
+#include "services/logging/logger.h"
 
 static std::string ReadRequiredString(const boost::json::object& object,
                                       const char* key) {
@@ -59,24 +61,54 @@ static std::vector<std::string> ReadRequiredStringArray(
   return items;
 }
 
-std::vector<Location> JsonLoader::LoadLocations(
+namespace {
-    const std::filesystem::path& filepath, std::shared_ptr<ILogger> logger) {
+
+boost::json::value ParseJsonFile(const std::filesystem::path& filepath,
+                                 const char* what) {
   std::ifstream input(filepath);
   if (!input.is_open()) {
-    throw std::runtime_error("Failed to open locations file: " +
+    throw std::runtime_error(
-                             filepath.string());
+        std::format("Failed to open {} file: {}", what, filepath.string()));
   }
 
   std::stringstream buffer;
   buffer << input.rdbuf();
-  const std::string content = buffer.str();
 
   boost::system::error_code error;
-  boost::json::value root = boost::json::parse(content, error);
+  boost::json::value root = boost::json::parse(buffer.str(), error);
   if (error) {
-    throw std::runtime_error("Failed to parse locations JSON: " +
+    throw std::runtime_error(
-                             error.message());
+        std::format("Failed to parse {} JSON: {}", what, error.message()));
   }
+  return root;
+}
+
+/**
+ * @brief Returns the first element of a string array field, falling back to
+ * `fallback_key` if `key` is missing/empty (some source entries only have a
+ * "localized" form and no "romanized" form).
+ */
+std::string ReadFirstOfStringArray(const boost::json::object& object,
+                                   const char* key, const char* fallback_key) {
+  for (const char* candidate_key : {key, fallback_key}) {
+    const boost::json::value* value = object.if_contains(candidate_key);
+    if (value == nullptr || !value->is_array()) {
+      continue;
+    }
+    const auto& array = value->as_array();
+    if (!array.empty() && array.front().is_string()) {
+      return std::string(array.front().as_string());
+    }
+  }
+  throw std::runtime_error(
+      std::format("Missing or invalid string array field: {}", key));
+}
+
+}  // namespace
+
+std::vector<Location> JsonLoader::LoadLocations(
+    const std::filesystem::path& filepath) {
+  const boost::json::value root = ParseJsonFile(filepath, "locations");
 
   if (!root.is_array()) {
     throw std::runtime_error(
@@ -108,3 +140,97 @@ std::vector<Location> JsonLoader::LoadLocations(
 
   return locations;
 }
+
+std::vector<UserPersona> JsonLoader::LoadPersonas(
+    const std::filesystem::path& filepath) {
+  const boost::json::value root = ParseJsonFile(filepath, "personas");
+
+  if (!root.is_array()) {
+    throw std::runtime_error(
+        "Invalid personas JSON: root element must be an array");
+  }
+
+  std::vector<UserPersona> personas;
+  const auto& items = root.as_array();
+  personas.reserve(items.size());
+
+  for (const auto& item : items) {
+    if (!item.is_object()) {
+      throw std::runtime_error(
+          "Invalid personas JSON: each entry must be an object");
+    }
+
+    const auto& object = item.as_object();
+    personas.push_back(UserPersona{
+        .name = ReadRequiredString(object, "name"),
+        .description = ReadRequiredString(object, "description"),
+        .style_affinities = ReadRequiredStringArray(object, "style_affinities"),
+    });
+  }
+
+  return personas;
+}
+
+NamesByCountry JsonLoader::LoadNamesByCountry(
+    const std::filesystem::path& forenames_filepath,
+    const std::filesystem::path& surnames_filepath) {
+  const boost::json::value forenames_root =
+      ParseJsonFile(forenames_filepath, "forenames-by-country");
+  const boost::json::value surnames_root =
+      ParseJsonFile(surnames_filepath, "surnames-by-country");
+
+  if (!forenames_root.is_object() || !surnames_root.is_object()) {
+    throw std::runtime_error(
+        "Invalid names-by-country JSON: root element must be an object "
+        "keyed by ISO 3166-1 country code");
+  }
+
+  std::unordered_map<std::string, std::vector<ForenameEntry>>
+      forenames_by_country;
+  for (const auto& [country_code, regions] : forenames_root.as_object()) {
+    if (!regions.is_array()) {
+      continue;
+    }
+    std::vector<ForenameEntry> entries;
+    for (const auto& region : regions.as_array()) {
+      if (!region.is_object()) {
+        continue;
+      }
+      const boost::json::value* names = region.as_object().if_contains("names");
+      if (names == nullptr || !names->is_array()) {
+        continue;
+      }
+      for (const auto& name_value : names->as_array()) {
+        if (!name_value.is_object()) {
+          continue;
+        }
+        const auto& name_object = name_value.as_object();
+        entries.push_back(ForenameEntry{
+            .name =
+                ReadFirstOfStringArray(name_object, "romanized", "localized"),
+            .gender = ReadRequiredString(name_object, "gender"),
+        });
+      }
+    }
+    forenames_by_country.emplace(country_code, std::move(entries));
+  }
+
+  std::unordered_map<std::string, std::vector<std::string>> surnames_by_country;
+  for (const auto& [country_code, name_entries] : surnames_root.as_object()) {
+    if (!name_entries.is_array()) {
+      continue;
+    }
+    std::vector<std::string> surnames;
+    for (const auto& name_value : name_entries.as_array()) {
+      if (!name_value.is_object()) {
+        continue;
+      }
+      surnames.push_back(ReadFirstOfStringArray(name_value.as_object(),
+                                                "romanized", "localized"));
+    }
+    surnames_by_country.emplace(country_code, std::move(surnames));
+  }
+
+  return NamesByCountry(std::move(forenames_by_country),
+                        std::move(surnames_by_country));
+}

tooling/pipeline/src/main.cc

@@ -24,7 +24,9 @@
 #include "data_generation/mock_generator.h"
 #include "data_generation/prompt_formatting/gemma4_jinja_prompt_formatter.h"
 #include "data_model/models.h"
+#include "json_handling/json_loader.h"
 #include "llama_backend_state.h"
+#include "services/curated_data/curated_data_service.h"
 #include "services/database/export_service.h"
 #include "services/database/sqlite_export_service.h"
 #include "services/datetime/timer.h"
@@ -53,6 +55,7 @@ int main(const int argc, char** argv) {
       std::make_shared<LogProducer>(log_channel);
 
   std::thread log_thread([&log_dispatcher] { log_dispatcher->Run(); });
+
   auto shutdown = [&](const int exit_code) {
     log_channel.Close();
     log_thread.join();
@@ -103,6 +106,7 @@ int main(const int argc, char** argv) {
         di::bind<ApplicationOptions>().to(options),
         di::bind<std::string>().to(model_path),
         di::bind<IExportService>().to<SqliteExportService>(),
+        di::bind<ICuratedDataService>().to<JsonLoader>(),
         di::bind<IPromptFormatter>().to([options, log_producer] {
           if (options.generator.use_mocked) {
             {
@@ -131,11 +135,11 @@ int main(const int argc, char** argv) {
             }
             return std::unique_ptr<WebClient>(nullptr);
           }
-          {
+
           log_producer->Log({.level = LogLevel::Info,
                              .phase = PipelinePhase::Startup,
                              .message = "Web client: HttpWebClient"});
-          }
+
           return std::unique_ptr<WebClient>(
               std::make_unique<HttpWebClient>(log_producer));
         }),
@@ -143,43 +147,42 @@ int main(const int argc, char** argv) {
             [options, &log_producer](
             const auto& inj) -> std::unique_ptr<IEnrichmentService> {
               if (options.generator.use_mocked) {
-                {
                 log_producer->Log({.level = LogLevel::Info,
                                    .phase = PipelinePhase::Startup,
                                    .message = "Enrichment: mock"});
-                }
+
                 return std::make_unique<MockEnrichmentService>();
               }
-              {
+
               log_producer->Log({.level = LogLevel::Info,
                                  .phase = PipelinePhase::Startup,
                                  .message = "Enrichment: Wikipedia"});
-              }
+
               return std::make_unique<WikipediaEnrichmentService>(
                   inj.template create<std::unique_ptr<WebClient>>(),
                   log_producer);
             }),
         di::bind<DataGenerator>().to(
             [&options, &model_path, &sampling, &prompt_directory,
-             &log_producer](const auto& inj) -> std::unique_ptr<DataGenerator> {
+              &log_producer
+            ](const auto& inj) -> std::unique_ptr<DataGenerator> {
               if (options.generator.use_mocked) {
-                {
                 log_producer->Log({.level = LogLevel::Info,
                                    .phase = PipelinePhase::Startup,
                                    .message = "Generator: mock"});
-                }
+
                 return std::make_unique<MockGenerator>();
               }
-              {
+
               log_producer->Log(
               {.level = LogLevel::Info,
                .phase = PipelinePhase::Startup,
                .message = std::format(
-                         "Generator: LlamaGenerator | model={} | temp={:.2f} "
+                   "Generator: LlamaGenerator | model={} | "
-                         "top_p={:.2f} top_k={} n_ctx={} seed={}",
+                   "temp={:.2f} top_p={:.2f} top_k={} n_ctx={} seed={}",
                    model_path, sampling.temperature, sampling.top_p,
                    sampling.top_k, sampling.n_ctx, sampling.seed)});
-              }
+
               return std::make_unique<LlamaGenerator>(
                   options, model_path, log_producer,
                   inj.template create<std::unique_ptr<IPromptFormatter>>(),
@@ -202,7 +205,6 @@ int main(const int argc, char** argv) {
                                               timer.Elapsed())});
 
     return shutdown(EXIT_SUCCESS);
-
   } catch (const std::exception& exception) {
     const LogDTO log_entry{.level = LogLevel::Error,
                            .phase = PipelinePhase::Teardown,

tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc

@@ -1,5 +1,6 @@
 /**
  * @file wikipedia/fetch_extract.cc
+ * @brief WikipediaEnrichmentService::FetchExtract() implementation.
  */
 
 #include <boost/json.hpp>
@@ -20,8 +21,9 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   if (const auto cache_it = this->extract_cache_.find(cache_key);
       cache_it != this->extract_cache_.end()) {
     if (logger_) {
-      logger_->Log({.level = LogLevel::Debug,
+      logger_->Log(
-                    .phase = PipelinePhase::UserGeneration,
+          {.level = LogLevel::Debug,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("Wikipedia: Cache hit for {}!", cache_key)});
     }
     return cache_it->second;
@@ -30,7 +32,8 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   const std::string encoded = this->client_->EncodeURL(cache_key);
   const std::string url = std::format(
       "https://en.wikipedia.org/w/"
-      "api.php?action=query&titles={}&prop=extracts&explaintext=1&format=json",
+      "api.php?action=query&titles={}&prop=extracts&explaintext=1&format="
+      "json",
       encoded);
 
   const std::string body = this->client_->Get(url);
@@ -45,10 +48,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
   if (ec) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message = std::format("WikipediaService: JSON parse error for '{}': {}",
+                        "WikipediaService: JSON parse error for '{}': {}",
                         std::string(query), ec.message())});
     }
     return {};
@@ -58,11 +61,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   const json::object* obj = doc.if_object();
   if (obj == nullptr) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message =
+                        "WikipediaService: Expected root object for '{}'",
-               std::format("WikipediaService: Expected root object for '{}'",
                         std::string(query))});
     }
     return {};
@@ -76,11 +78,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
   if ((pages_ptr == nullptr) || !pages_ptr->is_object()) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message =
+                        "WikipediaService: Missing query.pages for '{}'",
-               std::format("WikipediaService: Missing query.pages for '{}'",
                         std::string(query))});
     }
     return {};
@@ -90,10 +91,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
   if (pages.empty()) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message = std::format("WikipediaService: No pages returned for '{}'",
+                        "WikipediaService: No pages returned for '{}'",
                         std::string(query))});
     }
     this->extract_cache_.emplace(cache_key, "");
@@ -106,11 +107,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
   if (!page_val.is_object()) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message =
+                        "WikipediaService: Unexpected page format for '{}'",
-               std::format("WikipediaService: Unexpected page format for '{}'",
                         std::string(query))});
     }
     return {};
@@ -121,8 +121,9 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   // Handle 404/Missing status
   if (page.contains("missing")) {
     if (logger_) {
-      logger_->Log({.level = LogLevel::Warn,
+      logger_->Log(
-                    .phase = PipelinePhase::UserGeneration,
+          {.level = LogLevel::Warn,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("WikipediaService: Page '{}' does not exist",
                                   std::string(query))});
     }
@@ -134,11 +135,10 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
 
   if ((extract_ptr == nullptr) || !extract_ptr->is_string()) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Warn,
-          {.level = LogLevel::Warn,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-           .message =
+                        "WikipediaService: No extract string found for '{}'",
-               std::format("WikipediaService: No extract string found for '{}'",
                         std::string(query))});
     }
     this->extract_cache_.emplace(cache_key, "");
@@ -148,8 +148,9 @@ std::string WikipediaEnrichmentService::FetchExtract(std::string_view query) {
   // 4. Success
   std::string extract(extract_ptr->as_string());
   if (logger_) {
-    logger_->Log({.level = LogLevel::Info,
+    logger_->Log(
-                  .phase = PipelinePhase::UserGeneration,
+        {.level = LogLevel::Info,
+         .phase = PipelinePhase::Enrichment,
          .message = std::format("WikipediaService: Fetched {} chars for '{}'",
                                 extract.size(), std::string(query))});
   }

tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc

@@ -1,6 +1,6 @@
 /**
  * @file wikipedia/get_summary.cc
- * @brief WikipediaService::GetLocationContext() implementation.
+ * @brief WikipediaEnrichmentService::GetLocationContext() implementation.
  */
 
 #include <chrono>
@@ -16,7 +16,7 @@ std::string WikipediaEnrichmentService::GetLocationContext(
   if (!this->client_) {
     if (logger_) {
       logger_->Log({.level = LogLevel::Warn,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
                     .message = "Wikipedia client is nullptr."});
     }
     return {};
@@ -24,13 +24,6 @@ std::string WikipediaEnrichmentService::GetLocationContext(
 
   std::string result;
 
-  // std::string region_query(loc.city);
-  // if (!loc.country.empty()) {
-  //   region_query += loc.state_province,
-  //   region_query += ", ";
-  //   region_query += loc.country;
-  // }
-
   constexpr std::string_view brewing_query = "brewing";
   const std::string location_query =
       std::format("{}, {}", loc.city, loc.iso3166_2);
@@ -51,8 +44,9 @@ std::string WikipediaEnrichmentService::GetLocationContext(
     append_extract(FetchExtract(beer_query));
     if (logger_) {
       logger_->Log({.level = LogLevel::Info,
-                    .phase = PipelinePhase::UserGeneration,
+                    .phase = PipelinePhase::Enrichment,
-                    .message = std::format("Done fetching for {}. Sleeping for 10 seconds.",
+                    .message = std::format(
+                        "Done fetching for {}. Sleeping for 10 seconds.",
                         location_query)});
     }
     std::this_thread::sleep_for(10s);
@@ -61,7 +55,7 @@ std::string WikipediaEnrichmentService::GetLocationContext(
     if (logger_) {
       logger_->Log(
           {.level = LogLevel::Debug,
-           .phase = PipelinePhase::UserGeneration,
+           .phase = PipelinePhase::Enrichment,
            .message = std::format("WikipediaService lookup failed for '{}': {}",
                                   location_query, e.what())});
     }

tooling/pipeline/src/services/enrichment/wikipedia/wikipedia_service.cc

@@ -1,6 +1,6 @@
 /**
  * @file services/wikipedia/wikipedia_service.cc
- * @brief WikipediaService constructor implementation.
+ * @brief WikipediaEnrichmentService constructor implementation.
  */
 
 #include "services/enrichment/wikipedia_service.h"

tooling/pipeline/src/services/logging/log_dispatcher.cc

@@ -19,6 +19,8 @@ namespace {
   switch (phase) {
     case PipelinePhase::Startup:
       return "Startup";
+    case PipelinePhase::Enrichment:
+      return "Enrichment";
     case PipelinePhase::UserGeneration:
       return "User Generation";
     case PipelinePhase::BreweryAndBeerGeneration:

tooling/pipeline/src/services/prompt_directory.cc

@@ -44,8 +44,8 @@ PromptDirectory::PromptDirectory(const std::filesystem::path& prompt_dir,
   // Scenario 4: directory must be readable (probe with directory_iterator).
   std::filesystem::directory_iterator probe(prompt_dir_, ec);
   if (ec) {
-    throw std::runtime_error(
+    throw std::runtime_error(std::format(
-        std::format("PromptDirectory: prompt directory is not readable: {} ({})",
+        "PromptDirectory: prompt directory is not readable: {} ({})",
         prompt_dir_.string(), ec.message()));
   }
 
@@ -84,14 +84,17 @@ std::string PromptDirectory::Load(std::string_view key) {
   file.close();
 
   if (content.empty()) {
-    throw std::runtime_error(std::format("PromptDirectory: prompt file for key '{}' is empty: {}",
+    throw std::runtime_error(
+        std::format("PromptDirectory: prompt file for key '{}' is empty: {}",
                     key_str, file_path.string()));
   }
 
   if (logger_) {
-    logger_->Log({.level = LogLevel::Info,
+    logger_->Log(
+        {.level = LogLevel::Info,
          .phase = PipelinePhase::Startup,
-                  .message = std::format("[PromptDirectory] Loaded prompt '{}' from '{}' ({} chars)",
+         .message = std::format(
+             "[PromptDirectory] Loaded prompt '{}' from '{}' ({} chars)",
              key_str, file_path.string(), content.size())});
   }
 

tooling/pipeline/src/services/sqlite/finalize.cc

@@ -14,6 +14,7 @@ void SqliteExportService::Finalize() {
   }
 
   try {
+    insert_user_stmt_.reset();
     insert_brewery_stmt_.reset();
     insert_location_stmt_.reset();
     if (transaction_open_) {

tooling/pipeline/src/services/sqlite/initialize.cc

@@ -18,8 +18,8 @@ std::filesystem::path SqliteExportService::BuildDatabasePath() const {
   std::filesystem::path candidate = output_path_ / base_filename;
 
   for (int suffix = 1; std::filesystem::exists(candidate); ++suffix) {
-    candidate = output_path_ /
+    candidate = output_path_ / std::filesystem::path(
-                std::filesystem::path(std::format("biergarten_seed_{}-{}.sqlite",
+                                   std::format("biergarten_seed_{}-{}.sqlite",
                                                run_timestamp_utc_, suffix));
   }
 
@@ -33,6 +33,9 @@ void SqliteExportService::InitializeSchema() const {
   sqlite_export_service_internal::ExecSql(
       db_handle_, sqlite_export_service_internal::kCreateBreweriesTableSql,
       "Failed to create SQLite breweries table");
+  sqlite_export_service_internal::ExecSql(
+      db_handle_, sqlite_export_service_internal::kCreateUsersTableSql,
+      "Failed to create SQLite users table");
 }
 
 void SqliteExportService::PrepareStatements() {
@@ -42,6 +45,9 @@ void SqliteExportService::PrepareStatements() {
   insert_brewery_stmt_ = sqlite_export_service_internal::PrepareStatement(
       db_handle_, sqlite_export_service_internal::kInsertBrewerySql,
       "Failed to prepare SQLite brewery insert statement");
+  insert_user_stmt_ = sqlite_export_service_internal::PrepareStatement(
+      db_handle_, sqlite_export_service_internal::kInsertUserSql,
+      "Failed to prepare SQLite user insert statement");
 }
 
 void SqliteExportService::RollbackAndCloseNoThrow() noexcept {
@@ -54,6 +60,7 @@ void SqliteExportService::RollbackAndCloseNoThrow() noexcept {
     transaction_open_ = false;
   }
 
+  insert_user_stmt_.reset();
   insert_brewery_stmt_.reset();
   insert_location_stmt_.reset();
   db_handle_.reset();

tooling/pipeline/src/services/sqlite/process_record.cc

@@ -1,6 +1,7 @@
 /**
  * @file services/sqlite/process_record.cc
- * @brief SqliteExportService::ProcessRecord() implementation.
+ * @brief SqliteExportService::ProcessRecord() implementation
+ * and the shared location-resolution helper.
  */
 
 #include <iomanip>
@@ -29,95 +30,99 @@ std::string SqliteExportService::BuildLocationKey(const Location& location) {
   return key_stream.str();
 }
 
-uint64_t SqliteExportService::ProcessRecord(const GeneratedBrewery& brewery) {
+sqlite3_int64 SqliteExportService::ResolveLocationId(const Location& location) {
-  if (db_handle_ == nullptr || !transaction_open_) {
+  const std::string location_key = BuildLocationKey(location);
-    throw std::runtime_error("SQLite export service is not initialized");
+  const auto cached_location = location_cache_.find(location_key);
+  if (cached_location != location_cache_.end()) {
+    return cached_location->second;
   }
 
-  const std::string location_key = BuildLocationKey(brewery.location);
-  const auto cached_location = location_cache_.find(location_key);
-  sqlite3_int64 location_id = 0;
-
-  if (cached_location != location_cache_.end()) {
-    location_id = cached_location->second;
-  } else {
   const std::string local_languages_json =
-        sqlite_export_service_internal::SerializeVector(
+      sqlite_export_service_internal::SerializeVector(location.local_languages);
-            brewery.location.local_languages);
 
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationCityBindIndex,
-            .value = brewery.location.city,
+          .value = location.city,
           .action = "Failed to bind SQLite location city"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index =
               sqlite_export_service_internal::kLocationStateProvinceBindIndex,
-            .value = brewery.location.state_province,
+          .value = location.state_province,
           .action = "Failed to bind SQLite location state/province"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationIso31662BindIndex,
-            .value = brewery.location.iso3166_2,
+          .value = location.iso3166_2,
           .action = "Failed to bind SQLite location ISO 3166-2 code"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationCountryBindIndex,
-            .value = brewery.location.country,
+          .value = location.country,
           .action = "Failed to bind SQLite location country"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kLocationIso31661BindIndex,
-            .value = brewery.location.iso3166_1,
+          .value = location.iso3166_1,
           .action = "Failed to bind SQLite location ISO 3166-1 code"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
-            .index =
+          .index = sqlite_export_service_internal::kLocationLanguagesBindIndex,
-                sqlite_export_service_internal::kLocationLanguagesBindIndex,
           .value = local_languages_json,
           .action = "Failed to bind SQLite location languages"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam{
           .index = sqlite_export_service_internal::kLocationLatitudeBindIndex,
-            .value = brewery.location.latitude,
+          .value = location.latitude,
           .action = "Failed to bind SQLite location latitude"});
   sqlite_export_service_internal::Bind(
       insert_location_stmt_,
       sqlite_export_service_internal::BindParam{
-            .index =
+          .index = sqlite_export_service_internal::kLocationLongitudeBindIndex,
-                sqlite_export_service_internal::kLocationLongitudeBindIndex,
+          .value = location.longitude,
-            .value = brewery.location.longitude,
           .action = "Failed to bind SQLite location longitude"});
 
   sqlite_export_service_internal::StepStatement(
       db_handle_, insert_location_stmt_,
       "Failed to insert SQLite location row");
 
-    location_id = sqlite_export_service_internal::LastInsertRowId(db_handle_);
+  const sqlite3_int64 location_id =
+      sqlite_export_service_internal::LastInsertRowId(db_handle_);
   location_cache_.emplace(location_key, location_id);
   sqlite_export_service_internal::ResetStatement(insert_location_stmt_);
+
+  return location_id;
 }
 
+uint64_t SqliteExportService::ProcessRecord(const BreweryRecord& brewery) {
+  if (db_handle_ == nullptr || !transaction_open_) {
+    throw std::runtime_error("SQLite export service is not initialized");
+  }
+
+  const sqlite3_int64 location_id = ResolveLocationId(brewery.location);
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<sqlite3_int64>{
           .index = sqlite_export_service_internal::kBreweryLocationIdBindIndex,
           .value = location_id,
           .action = "Failed to bind SQLite brewery location id"});
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kBreweryEnglishNameBindIndex,
           .value = brewery.brewery.name_en,
           .action = "Failed to bind SQLite brewery English name"});
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
@@ -125,12 +130,14 @@ uint64_t SqliteExportService::ProcessRecord(const GeneratedBrewery& brewery) {
               kBreweryEnglishDescriptionBindIndex,
           .value = brewery.brewery.description_en,
           .action = "Failed to bind SQLite brewery English description"});
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{
           .index = sqlite_export_service_internal::kBreweryLocalNameBindIndex,
           .value = brewery.brewery.name_local,
           .action = "Failed to bind SQLite brewery local name"});
+
   sqlite_export_service_internal::Bind(
       insert_brewery_stmt_,
       sqlite_export_service_internal::BindParam<std::string_view>{

tooling/pipeline/src/services/sqlite/process_user_record.cc

@@ -0,0 +1,79 @@
+/**
+ * @file services/sqlite/process_user_record.cc
+ * @brief SqliteExportService::ProcessRecord(UserRecord) implementation.
+ */
+
+#include <stdexcept>
+
+#include "services/database/sqlite_export_service.h"
+#include "services/database/sqlite_export_service_helpers.h"
+
+uint64_t SqliteExportService::ProcessRecord(const UserRecord& user) {
+  if (db_handle_ == nullptr || !transaction_open_) {
+    throw std::runtime_error("SQLite export service is not initialized");
+  }
+
+  const sqlite3_int64 location_id = ResolveLocationId(user.location);
+
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<sqlite3_int64>{
+          .index = sqlite_export_service_internal::kUserLocationIdBindIndex,
+          .value = location_id,
+          .action = "Failed to bind SQLite user location id"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserFirstNameBindIndex,
+          .value = user.user.first_name,
+          .action = "Failed to bind SQLite user first name"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserLastNameBindIndex,
+          .value = user.user.last_name,
+          .action = "Failed to bind SQLite user last name"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserGenderBindIndex,
+          .value = user.user.gender,
+          .action = "Failed to bind SQLite user gender"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserUsernameBindIndex,
+          .value = user.user.username,
+          .action = "Failed to bind SQLite user username"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserBioBindIndex,
+          .value = user.user.bio,
+          .action = "Failed to bind SQLite user bio"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<double>{
+          .index = sqlite_export_service_internal::kUserActivityWeightBindIndex,
+          .value = static_cast<double>(user.user.activity_weight),
+          .action = "Failed to bind SQLite user activity weight"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserEmailBindIndex,
+          .value = user.email,
+          .action = "Failed to bind SQLite user email"});
+  sqlite_export_service_internal::Bind(
+      insert_user_stmt_,
+      sqlite_export_service_internal::BindParam<std::string_view>{
+          .index = sqlite_export_service_internal::kUserDateOfBirthBindIndex,
+          .value = user.date_of_birth,
+          .action = "Failed to bind SQLite user date of birth"});
+
+  sqlite_export_service_internal::StepStatement(
+      db_handle_, insert_user_stmt_, "Failed to insert SQLite user row");
+
+  sqlite_export_service_internal::ResetStatement(insert_user_stmt_);
+
+  return sqlite_export_service_internal::LastInsertRowId(db_handle_);
+}

tooling/pipeline/src/web_client/http_web_client.cc

@@ -48,18 +48,17 @@ std::string HttpWebClient::Get(const std::string& url) {
   const httplib::Result result = client.Get(path);
 
   if (!result) {
-    throw std::runtime_error(std::format(
+    throw std::runtime_error(
-        "[HttpWebClient] Request failed for URL: {} — {}", url,
+        std::format("[HttpWebClient] Request failed for URL: {} — {}", url,
                     httplib::to_string(result.error())));
   }
 
   if (result->status < kSuccessMin || result->status >= kSuccessMax) {
     if (logger_) {
-      logger_->Log(
+      logger_->Log({.level = LogLevel::Error,
-          {.level = LogLevel::Error,
+                    .phase = PipelinePhase::Enrichment,
-           .phase = PipelinePhase::UserGeneration,
+                    .message = std::format(
-         .message =
+                        "[HttpWebClient] Request failed for URL: {}", url)});
-           std::format("[HttpWebClient] Request failed for URL: {}", url)});
     }
     throw std::runtime_error(std::format("[HttpWebClient] HTTP {} for URL: {}",
                                          result->status, url));