## Purpose

A scheduled background job in the Journal that generates plausible synthetic routes and activities under a dedicated demo user ("Bruno"), so that fresh deployments and public landing pages have life in the feed without requiring real users. Synthetic content is flagged in the database, capped, and pruned on a configurable retention window.

## Requirements

### Requirement: Persona configuration
The Journal SHALL load a demo persona — username, display name, bio, supported locales, and per-locale content pools — from configuration at worker boot, and SHALL fall back to a built-in default persona if no override is supplied or the supplied override fails validation.

#### Scenario: No override supplied — built-in default applies
- **WHEN** the worker starts with `DEMO_BOT_ENABLED=true` and `DEMO_BOT_PERSONA` is unset
- **THEN** the bot uses the built-in default persona (`username=bruno`, playful Berlin-flavoured display name and bio, `locales=["en","de"]`, and the shipped Bruno-voiced name/description pools)
- **AND** behaviour is identical to the demo bot before this change

#### Scenario: Inline JSON override
- **WHEN** `DEMO_BOT_PERSONA` is set to a valid inline JSON object with `username`, `displayName`, `bio`, `locales`, and `content.names` / `content.descriptions` for each listed locale
- **THEN** the bot uses that persona — `ensureDemoUser` inserts a row with the persona's username/displayName/bio/sentinel email, and subsequent generated routes and activities draw names and descriptions from the persona's per-locale pools

#### Scenario: File-backed override
- **WHEN** `DEMO_BOT_PERSONA` is set to `file:<absolute-path>` and the referenced file contains a valid persona JSON object
- **THEN** the worker reads the file once at boot and uses its contents as the persona

#### Scenario: Invalid JSON or schema violation → fall back
- **WHEN** `DEMO_BOT_PERSONA` is set but the value is not valid JSON, or fails the persona schema (bad username pattern, empty or too-short pool, unsupported locale, etc.)
- **THEN** the worker logs a warn-level entry describing the first validation failure and uses the built-in default persona
- **AND** the bot continues to run

#### Scenario: File-backed path unreadable → fall back
- **WHEN** `DEMO_BOT_PERSONA=file:<path>` but the file cannot be read (missing, permission denied, not a file)
- **THEN** the worker logs a warn-level entry and uses the built-in default persona

### Requirement: Persona username clash detection
The Journal SHALL refuse to attach the demo bot to a pre-existing non-demo user account when the supplied persona username collides with a human user already registered on the instance.

#### Scenario: Configured username belongs to a real user
- **WHEN** the worker starts, the persona's username matches an existing `users` row, and that row has no marker identifying it as a prior demo user (i.e. it was registered via the normal signup flow)
- **THEN** the worker logs an error-level "demo persona username clash" entry naming the colliding username
- **AND** the generation + prune jobs are not scheduled for this process — the bot stays disabled until the operator picks a different username
- **AND** the rest of the Journal continues to serve requests normally

### Requirement: Demo user bootstrap
The Journal SHALL ensure a dedicated bot user exists when the demo bot starts, creating it on first run if missing. The user's identity (username, display name, bio, sentinel email local-part) is derived from the active persona — either the operator-supplied persona or the built-in default.

#### Scenario: Bot user created on first run
- **WHEN** the Journal worker starts with `DEMO_BOT_ENABLED=true` and no `users` row matches the persona's username
- **THEN** a new `users` row is inserted with that username, the persona's display name, the persona's bio, a sentinel email `<username>@<domain>`, no passkey credentials, and `terms_accepted_at` + `terms_version` populated at the current version
- **AND** subsequent worker startups are idempotent — no second row is inserted

#### Scenario: Demo user has no usable credentials
- **WHEN** any request attempts to authenticate as the demo user via passkey or magic-link
- **THEN** authentication fails because no passkey is registered and no mailbox receives magic-link mails

### Requirement: Synthetic content generation job
The Journal SHALL run a recurring background job that generates one public route and one linked public activity for the demo user per run, subject to an env flag and a rate cap. The generated name and description are drawn from the active persona's per-locale content pools.

#### Scenario: Disabled in non-production environments
- **WHEN** the `DEMO_BOT_ENABLED` env var is absent or any value other than `"true"`
- **THEN** the job body is a no-op: no BRouter calls, no inserts, no errors

#### Scenario: Enabled generation flow (decide-to-walk fires)
- **WHEN** `DEMO_BOT_ENABLED=true`, the local hour is within 07:00–21:00, the per-tick Bernoulli roll fires, and the hard cap has not been reached
- **THEN** the job picks a random start and end point within the configured seed region, calls BRouter with the `trekking` profile, persists the returned GPX as a new route with `visibility='public'` and `synthetic=true`, and inserts a linked activity with the same GPX, `visibility='public'`, `synthetic=true`, a plausible `started_at` and `duration`, and a persona-voiced name + description sampled from one of the persona's supported locales
- **AND** the route and activity are attributed to the demo user

#### Scenario: Locale restricted to a single language
- **WHEN** the persona's `locales` list is `["en"]`
- **THEN** every generated route's name and description come from the persona's English pool — the German pool is never sampled

#### Scenario: Decide-to-walk does not fire
- **WHEN** the local hour is outside 07:00–21:00, or the Bernoulli roll does not fire
- **THEN** the job returns without inserting anything

#### Scenario: BRouter failure is tolerated
- **WHEN** the BRouter call returns no route, a rate-limit, or an error
- **THEN** the job logs the failure, inserts nothing, and exits without throwing — the next scheduled tick retries

#### Scenario: Hard cap prevents runaway growth
- **WHEN** there are already 40 or more synthetic items created in the last 14 days
- **THEN** the job skips generation for that tick

#### Scenario: Singleton scheduling prevents overlap
- **WHEN** a tick fires while the previous run is still executing
- **THEN** the new tick is skipped (pg-boss singleton semantics) so the job cannot overlap itself

### Requirement: Synthetic content retention
The Journal SHALL run a recurring job that deletes synthetic routes and activities older than a configurable window.

#### Scenario: Prune removes old synthetic content
- **WHEN** the prune job runs with `DEMO_BOT_RETENTION_DAYS=14`
- **THEN** every row in `journal.routes` and `journal.activities` with `synthetic=true` and `created_at < now() - 14 days` is deleted
- **AND** route-version rows cascade-delete via existing foreign keys
- **AND** rows with `synthetic=false` are never touched

#### Scenario: Prune is a no-op when nothing is old
- **WHEN** the prune job runs and no synthetic rows exceed the retention window
- **THEN** no DELETE statements execute and the job returns normally

#### Scenario: Disabled in non-production environments
- **WHEN** `DEMO_BOT_ENABLED` is not `"true"`
- **THEN** the prune job body is a no-op

### Requirement: Initial backfill
On first enablement (when no synthetic content exists yet) the Journal SHALL populate the demo profile with a small batch of items so the first visitor does not see a single-item feed.

#### Scenario: First enablement backfills several items
- **WHEN** the bot is enabled for the first time and the count of synthetic routes is 0
- **THEN** the generation job produces 3–5 items in sequence during its first run
- **AND** subsequent runs produce one item at a time as normal

### Requirement: Seed region is configurable
The Journal SHALL read the seed region (bounding box) from an env var so the deployment can change it without a code change.

#### Scenario: Env-configured region
- **WHEN** `DEMO_BOT_REGION` is set to a JSON object containing a `bbox` array of four numbers `[west, south, east, north]`
- **THEN** all generated start and end points fall within that box

#### Scenario: Sensible default
- **WHEN** `DEMO_BOT_REGION` is unset
- **THEN** the job uses a documented default region (inner Berlin) so that out-of-the-box runs still produce plausible Bruno-style walks