Deal Modeling slice: ship The Deal Brief

[SolidFebin]

Wednesday tool that turns fuzzy deal emails into a structured, confirmed source of truth before the show. Closes the 62% gap of unsupported deal types (Vs, walkout, ratchet, % of net, door) by giving the existing settlement engine richer typed inputs — not by building a better calculator.

WHAT'S NEW

• /shows/[id]/brief — new surface for confirming deal terms. Paste email → extract structured terms → see ambiguities and contradictions → confirm with agent reply → brief locks.
• Settlement page reads from confirmed briefs when present; falls back to the legacy calculator otherwise. Brief-backed steps cite their source clauses via hover tooltips.
• Brief CTA banner on show detail page (three states: no-brief / draft / awaiting / confirmed).

ARCHITECTURE — 4-tier extraction pipeline

• Tier 0: regex parser, ~72% of deals at $0, ~5ms each.
• Tier 1: local embeddings (Xenova MiniLM-L6, runs in Node). Near-duplicate clone when similarity >= 0.95; otherwise supplies top-3 examples as few-shot to Tier 2.
• Tier 2: free-tier LLM. Groq Llama 3.3 70B preferred (30 RPM, ~500ms); Gemini 2.5 Flash as alternative. Two passes: structured extraction + ambiguity detection.
• Tier 3: manual entry / Mariana review. Drafts never auto-confirm. AI proposes, Mariana confirms — every time.

Provider abstraction selects automatically (Groq > Gemini > Manual) or via AI_PROVIDER env var. ~80% of real deals never touch the LLM. Steady-state runs on free tier — ~$0/venue.

CONTRADICTION CHECKS — pure SQL, no LLM

Eight per-show checks plus a cross-show agent pattern detector. Surfaces 9 of the 12 planted breadcrumbs in db/seed.ts: percentage drift, deal-type mismatch, stale priorShowCount, silent hospitality overrun, disputed-with-positive-signoff, paid-with-disputed-recoup, reversed timestamps, duplicate expenses, and "agent X has N+ prior disputed marketing recoups."

DEAL BRIEF SCHEMA

New deal_briefs table (additive, no breaking changes to existing schema). recoupPlacement (inside_cap | outside_cap) is required — the single field that would have prevented the Coastal Spell $720 dispute. Vs flavors (standard, walkout, ratchet, vs_gross) are first-class. Per-field confidence, source-span provenance, and provenance-tier tracking.

DEFENSIVE LAYERS

• PercentageSchema transform normalizes LLM output that drifts between decimal (0.80) and percentage points (80).
• normalizeLLMBriefOutput absorbs common LLM variance: missing nullable fields, null arrays, enum variants like "marketing_recoup" vs "marketing".
• briefIsEmpty short-circuits the persist + contradiction pipeline when extraction yields nothing meaningful.
• describeDbError maps SQLITE_READONLY_DBMOVED to an actionable user message (restart dev server).

DELIVERABLES

• README.md: updated with setup, AI provider config, key URLs, sample emails, 3-minute walkthrough, troubleshooting.
• MEMO.md: 1-2 page PRD memo (slice defense, design choices, what was cut, validation plan, what ships next).
• scripts/validate-flows.ts: re-runnable end-to-end validation across three test shows (Tier 2 + contradictions + brief-backed settle math).

DEPENDENCIES ADDED

• zod (^4.4.3) — runtime validation of LLM output
• groq-sdk (^1.2.0) — primary LLM provider
• @google/generative-ai (^0.24.1) — alternative LLM provider
• @xenova/transformers (^2.17.2) — local embeddings