docs: freeze Phase 3 contract - sections (25), second looks with rounds, match points + tank gauge, agent pass; UI-SPEC v3 + DESIGN/RANKING/DATA-MODEL/PLAN additions

This commit is contained in:
Alex (Hermes)
2026-11-10 22:52:51 -04:00
parent 49e284ff56
commit 40b42b1d40
5 changed files with 174 additions and 19 deletions

View File

@@ -105,3 +105,64 @@ LIMIT :deck_size;
- **Badge:** `prefs['badge_seen_at']` (ISO). `new` = active rows with `first_seen` > COALESCE(badge_seen_at,'0'); `POST /api/badge/seen` stamps now.
- **Media mirror:** files at `data/img/{listing_id}.webp`; `GET /img/{id}` → file (200) → `img_url` (302) → 404 (UI placeholder). Downloads via `app/imgfetch.py` (polite: ~1 req/s, skip-existing, resumable). `img_url` enrichment happens upstream in the hunt state (`motorcycle-hunt-img.py`; atomic writes; rescans keep curated imgs) and lands via import.
- **Dedupe refinement (stretch, targeted):** for cross-province groups with >2 members, replace collapse-to-one with `min(ns,nb)` completeness pairing; surplus siblings stay active. Expected dup ≈ 77 (vs 80). Verify counts and report.
## P3 additions — frozen 2026-11-10 (personalization)
New tables (guarded, idempotent creation; fresh AND existing DBs migrate in place):
```sql
swipe_events ( -- append-only strike log; the learning source of truth
id INTEGER PRIMARY KEY AUTOINCREMENT,
listing_id INTEGER NOT NULL REFERENCES listings(id) ON DELETE CASCADE,
action TEXT NOT NULL CHECK (action IN ('like','nope','maybe')),
round INTEGER NOT NULL DEFAULT 1, -- 1 = first verdict; 2+ = second look (engine caps influence at round 2)
section_id INTEGER, -- section it happened in (NULL for list edits / legacy)
created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX idx_events_listing ON swipe_events (listing_id, round);
CREATE INDEX idx_events_time ON swipe_events (created_at);
sections (
id INTEGER PRIMARY KEY AUTOINCREMENT,
status TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open','report','closed')),
size INTEGER NOT NULL,
profile_version INTEGER, -- taste_profile.version used at compose
recipe TEXT, -- JSON summary {new, return, wildcard, caps_applied, note}
created_at TEXT DEFAULT (datetime('now')),
closed_at TEXT
);
section_items (
section_id INTEGER NOT NULL REFERENCES sections(id) ON DELETE CASCADE,
listing_id INTEGER NOT NULL REFERENCES listings(id) ON DELETE CASCADE,
slot TEXT NOT NULL CHECK (slot IN ('new','return','wildcard')),
position INTEGER NOT NULL,
PRIMARY KEY (section_id, listing_id)
);
taste_profile (
version INTEGER PRIMARY KEY AUTOINCREMENT,
created_at TEXT DEFAULT (datetime('now')),
source TEXT NOT NULL CHECK (source IN ('agent','mock','fallback')),
payload TEXT NOT NULL -- JSON: lead, leanings, changes, chips, adjustments, wildcards
);
agent_runs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
started_at TEXT, finished_at TEXT,
ok INTEGER NOT NULL DEFAULT 0,
source TEXT, model TEXT, cost_note TEXT, error TEXT,
profile_version INTEGER
);
```
Semantics:
- **Learning = `swipe_events` only** (append-only). A cleared swipe keeps its history — clearing removes the *UI verdict*, not the record. **UI truth = `swipes`** (latest verdict / cleared), unchanged from P1–P2.
- Round = prior events for that listing + 1, assigned at write time. Rounds cap at 2 for engine influence (any later events weigh as round 2; v1 returns never produce rounds >2 by design).
- **Migration seeding:** when `swipe_events` is empty and `swipes` has rows → insert one round-1 event per swipe row (created_at copied). Only-when-empty, hence idempotent.
- **Sections:** at most ONE `open` section at a time. The deck = that section's `section_items` in `position` order, filtered to items undecided at read. Exhausted = no item undecided → `status='report'`. Forge = close current + open new. First-ever read composes a cold section (rubric-weighted, w=0).
- **Returns eligibility (v1 contract):** a verdict exists (like/maybe/nope in `swipes`); listing `active`; NOT in either of the previous two sections; no round≥2 `nope` ever (rested); not already returned once (round cap). Selection prefers maybe > like > nope; nope candidates must be "surprising" (points ≥55 or net-positive family). Max 5 returns per section, ≤2 of them nopes.
- **`points` is computed, not stored** (deterministic from events + profile; a cache is allowed only if it never changes semantics).
- **prefs:** `forge_mode` ('ondemand' default | 'strict'). Existing keys unchanged.
- **Legacy deck semantics:** `/api/deck` (cursor paging; 7-day maybe re-admit) stays as a read-only fallback for debugging; sections are the production flow.