@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/host/prisma/schema/app.kvox.ask.prisma

@@ -0,0 +1,110 @@
+// GENERATED by platform db compose — do not edit
+// source: app:kvox.ask.prisma
+
+// GENERATED by kvox-db sync — do not edit
+// source: @marinoscar/kvox-db:schema/kvox.ask.prisma
+
+// =============================================================================
+// Ask — saved conversations with the read-only graph agent (issue #376, epic #348)
+// =============================================================================
+//
+// `ask_conversations` is one saved conversation; `ask_messages` is one turn in
+// it. An assistant turn's `content` is the DURABLE STREAM BUFFER the
+// `ask.respond` job (#378) appends to while it streams and the SSE endpoint
+// (#379) reads from — the same "durable buffer, stream is a view" contract
+// `note_generations` established (docs/specs/notes.md), so a turn completes
+// identically whether or not anyone is watching.
+//
+// Ownership: `owner_id` CASCADES (a deleted account leaves no Ask history, and
+// there is deliberately no `ask:read_any` — a conversation derives from the
+// owner's private recordings). `scope_entity_id` is SetNull: forgetting or
+// merging the scoped person drops only the scope link; the conversation text
+// is the user's own content, never graph data. `conversation_id` CASCADES.
+// `job_id` mirrors `TranscriptExport.jobId` exactly (`@unique`/nullable/SetNull).
+//
+// INTENTIONAL SCHEMA DRIFT: `ask_messages_one_running_turn_uniq_idx` — a
+// partial UNIQUE index on `(conversation_id) WHERE role = 'assistant' AND
+// status IN ('pending','streaming')` — exists ONLY in migration.sql, because
+// Prisma cannot express a partial index. It is what enforces "at most one
+// running turn per conversation" (the `database_backup_runs_active_uniq_idx`
+// pattern — never a `findFirst` before the insert, which races). #378 maps a
+// violation to 409 `ask_turn_running`. Do not "fix" the drift with a
+// `@@unique`.
+// =============================================================================
+
+enum AskMessageRole {
+  user
+  assistant
+}
+
+enum AskMessageStatus {
+  pending
+  streaming
+  complete
+  failed
+}
+
+enum AskErrorClass {
+  auth
+  refusal
+  rate_limit
+  budget
+  timeout
+  other
+}
+
+// Why an assistant turn ended (spec §21.3). Anything but `stop` means the
+// turn hit a cap and ended with its best answer — the UI says "stopped early".
+enum AskFinishReason {
+  stop
+  step_cap
+  token_cap
+  time_cap
+}
+
+model AskConversation {
+  id            String       @id @default(uuid()) @db.Uuid
+  ownerId       String       @map("owner_id") @db.Uuid
+  owner         User         @relation(fields: [ownerId], references: [id], onDelete: Cascade)
+  // null until the first message; then the first 80 chars of it (#378).
+  title         String?
+  scopeEntityId String?      @map("scope_entity_id") @db.Uuid
+  // Forgetting a person drops the scope, keeps the conversation.
+  scopeEntity   KgEntity?    @relation(fields: [scopeEntityId], references: [id], onDelete: SetNull)
+  messages      AskMessage[]
+  createdAt     DateTime     @default(now()) @map("created_at") @db.Timestamptz(6)
+  updatedAt     DateTime     @updatedAt @map("updated_at") @db.Timestamptz(6)
+
+  @@index([ownerId, updatedAt(sort: Desc)])
+  @@index([ownerId, scopeEntityId])
+  @@map("ask_conversations")
+}
+
+model AskMessage {
+  id               String           @id @default(uuid()) @db.Uuid
+  conversationId   String           @map("conversation_id") @db.Uuid
+  conversation     AskConversation  @relation(fields: [conversationId], references: [id], onDelete: Cascade)
+  role             AskMessageRole
+  // assistant: the durable stream buffer, APPEND-ONLY while streaming.
+  content          String           @default("") @db.Text
+  status           AskMessageStatus @default(pending)
+  // AskToolCall[] / AskCitation[] — see `apps/api/src/ask/dto/ask.dto.ts`.
+  toolCalls        Json             @default("[]") @map("tool_calls")
+  citations        Json             @default("[]")
+  model            String?
+  provider         String?
+  promptTokens     Int?             @map("prompt_tokens")
+  completionTokens Int?             @map("completion_tokens")
+  errorClass       AskErrorClass?   @map("error_class")
+  // spec §21.3: a capped turn ends with its best answer and says so.
+  finishReason     AskFinishReason? @map("finish_reason")
+  // Mirrors TranscriptExport.jobId.
+  jobId            String?          @unique @map("job_id") @db.Uuid
+  job              Job?             @relation(fields: [jobId], references: [id], onDelete: SetNull)
+  createdAt        DateTime         @default(now()) @map("created_at") @db.Timestamptz(6)
+
+  @@index([conversationId, createdAt])
+  // HAND-WRITTEN in migration.sql only: `ask_messages_one_running_turn_uniq_idx`
+  // — see the section header's "INTENTIONAL SCHEMA DRIFT" note.
+  @@map("ask_messages")
+}