`AIKnowledgeReference` shapes; adds `AIConfidencePolicy` (research.md — not in doc 06, required
by FR-005).
## AISupportSession
| Field | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| ticketId | String | FK → `Ticket`. One **active** session per ticket at a time (FR-001) — enforced in the repository (partial-condition check, not a DB constraint, since a ticket accumulates multiple ended sessions over time if re-escalated and re-opened) |
**Index**: `(ticketId, status)` — the exact shape the "one active session per ticket" check and
the ticket-detail view both query on.
## AIDiagnosis
| Field | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| sessionId | String | FK → `AISupportSession` |
| product | String | Echoes the ticket's product for readability; not a second source of truth for scoping (the session's `ticketId` → `Ticket.productId` remains authoritative) |
| feature | String? | |
| problemType | String | Matched against `Runbook.key` for the runbook-engine trigger (research.md) |
| severity | String | |
| confidence | Float | 0–1; the value the confidence-band policy (FR-004) is applied to |
| possibleCauses | String[] | |
| createdAt | DateTime @default(now()) | |
Never updated in place — a session accumulates one row per diagnosis attempt (initial + each
re-diagnosis after a customer reply), matching FR-002's "never overwriting a prior one."
## AIInteraction
| Field | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| sessionId | String | FK → `AISupportSession` |
| role | String | `customer` \| `ai` |
| content | String | |
| createdAt | DateTime @default(now()) | |
An `AIInteraction` with `role: ai` that's a clarifying question or guided-step message is *also*
written as a `TicketMessage` (`type: AI_MESSAGE`) via the existing messages module — `AIInteraction`
is the session's own ordered transcript for reasoning-call context; `TicketMessage` is the
customer-visible record. They're intentionally two records: the session transcript may include
turns not meant to duplicate onto the ticket (e.g., an internal re-diagnosis triggered by a tool
result, with no new customer-facing text).
## AIAction / AIActionResult
| Field (`AIAction`) | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| sessionId | String | FK → `AISupportSession` |
| toolName | String | Must match a name in the code-defined registry (research.md) |
| input | Json | The model's proposed input, before any validation |
| riskLevel | String | Copied from the registry at evaluation time (`low`/`medium`/`high`) — a durable record of what risk tier applied, independent of later registry changes |
| evaluationOutcome | String | `approved` \| `pending_approval` \| `refused` — the deterministic gate's decision (research.md), always recorded even when nothing executes |
| refusalReason | String? | Set when `evaluationOutcome = refused` (unknown tool, product not in scope, etc.) |
| approvedBy | String? | `system-policy` for auto-approved low-risk; null while `pending_approval`; an agent id if a future approval UI fills it in |
| createdAt | DateTime @default(now()) | |
| Field (`AIActionResult`) | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| actionId | String @unique | FK → `AIAction` — only exists when `evaluationOutcome = approved` and execution actually ran |
| output | Json | |
| status | String | `success` \| `failed` |
| createdAt | DateTime @default(now()) | |
A `pending_approval` or `refused``AIAction` has no `AIActionResult` row — the absence itself is
the record of "never executed" (FR-013 requires the proposal+evaluation to be recorded either
way, not that every proposal produces a result).
## AIKnowledgeReference
| Field | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| sessionId | String | FK → `AISupportSession` |
| knowledgeId | String | `KnowledgeEntry.id` (004) — not a DB-level FK across module boundaries per this codebase's convention of modules only depending on each other's `index.ts`, but a plain string reference resolved through `knowledge`'s exported repository |
| relevanceScore | Float? | Null for now — 004's retrieval doesn't emit a numeric score (structured filtering + validation-status ranking, not a similarity score); reserved for a future semantic-retrieval layer (spec.md Assumptions) |
| createdAt | DateTime @default(now()) | |
One row per knowledge entry actually included in a reasoning call's context — the durable record
of what the AI was actually shown, satisfying doc 03 §9's "AI must never invent... expose
internal notes" concern from the audit side (you can always answer "what knowledge did the AI
see for this session").
## AIConfidencePolicy
| Field | Type | Notes |
|---|---|---|
| id | String @id@default(cuid()) | |
| productId | String? | Null = system-wide default row (optional; env-var defaults cover the no-row case too — research.md) |
| categoryId | String? | Null = applies to every category of `productId` |
