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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user