Propose social MVP: public-content-visibility + demo-activity-bot

Two stacked OpenSpec change proposals for a demoable social layer,
with scope deliberately minimal ("enough to send a URL and have it
open to real-looking content without signup"):

1. public-content-visibility
   - Adds visibility enum {private, unlisted, public} on routes +
     activities, defaulting to private for every existing row.
   - Detail pages (/routes/:id, /activities/:id) become accessible to
     logged-out visitors when content is public or unlisted; private
     → 404 (not 403) to avoid existence leaks.
   - Broadens /users/:username into a public profile listing only
     public routes + activities; 404s when there's no public content
     to prevent account enumeration.
   - Open Graph / Twitter Card meta on public detail + profile pages.
   - Visibility selector in the owner's edit flow.
   - Out of scope: follow/follower, cross-user feed, reactions,
     federation.

2. demo-activity-bot  (depends on #1)
   - A single bot user, Bruno the trail dog, seeded on worker startup
     when DEMO_BOT_ENABLED=true. Reserved username, sentinel email,
     no credentials.
   - pg-boss recurring job fires every 90 min, decides-to-walk with
     p=0.12 during 07:00-21:00 local, yielding ~2-3 walks/day at
     organic times.
   - Each walk: random start + end within inner-Berlin bbox, trekking
     only (dogs don't ride bikes), 2-12 km crow. BRouter plans the
     route; the route GPX is also attached as the activity's trace.
   - Everything inserted with visibility=public, synthetic=true.
   - Daily prune deletes synthetic rows > DEMO_BOT_RETENTION_DAYS old
     (default 14). Hard cap of 40 items/14d protects against runaway
     growth.
   - Small "🐕 demo account" badge on /users/bruno for honesty.

Both changes are artifacts only — no code lands with this PR. Apply
in order after merge: public-content-visibility first, then
demo-activity-bot.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer 2026-04-19 08:49:59 +02:00
parent 94ce350565
commit dcbd703f47
No known key found for this signature in database
GPG key ID: A32FF691A0F752D9
14 changed files with 706 additions and 0 deletions

View file

@ -0,0 +1,16 @@
## ADDED Requirements
### Requirement: Synthetic activity flag
The Journal SHALL persist a `synthetic` boolean on every activity so automated / demo content can be distinguished from user-created content.
#### Scenario: User-created activities default to non-synthetic
- **WHEN** an activity is created through any user-facing flow (GPX upload, sync import, Planner handoff)
- **THEN** the activity row is persisted with `synthetic = false`
#### Scenario: Bot inserts flag their rows as synthetic
- **WHEN** the demo-activity-bot inserts an activity
- **THEN** the row is persisted with `synthetic = true`
#### Scenario: Synthetic flag is not user-editable
- **WHEN** an activity owner edits the activity via any user-facing action
- **THEN** the stored `synthetic` value is not changed by the edit

View file

@ -0,0 +1,77 @@
## ADDED Requirements
### 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.
#### Scenario: Bot user created on first run
- **WHEN** the Journal worker starts with `DEMO_BOT_ENABLED=true` and no `users` row matches the reserved demo username
- **THEN** a new `users` row is inserted with the reserved username, a public-facing display name, a sentinel email (`demo@<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.
#### 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:0021: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 templated Bruno-voiced name/description
- **AND** the route and activity are attributed to the demo user
#### Scenario: Decide-to-walk does not fire
- **WHEN** the local hour is outside 07:0021:00, or the Bernoulli roll does not fire
- **THEN** the job returns without inserting anything — Bruno just isn't walking right now
#### 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 35 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

View file

@ -0,0 +1,16 @@
## ADDED Requirements
### Requirement: Synthetic route flag
The Journal SHALL persist a `synthetic` boolean on every route so automated / demo content can be distinguished from user-created content.
#### Scenario: User-created routes default to non-synthetic
- **WHEN** a route is created through any user-facing flow (New Route, GPX import, Planner handoff)
- **THEN** the route row is persisted with `synthetic = false`
#### Scenario: Bot inserts flag their rows as synthetic
- **WHEN** the demo-activity-bot inserts a route
- **THEN** the row is persisted with `synthetic = true`
#### Scenario: Synthetic flag is not user-editable
- **WHEN** a route owner edits a route via any user-facing action
- **THEN** the stored `synthetic` value is not changed by the edit