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

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

@@ -0,0 +1,726 @@
+// GENERATED by platform db compose — do not edit
+// source: app:kvox.transcripts.prisma
+
+// GENERATED by kvox-db sync — do not edit
+// source: @marinoscar/kvox-db:schema/kvox.transcripts.prisma
+
+// =============================================================================
+// Transcripts (issue #24, epic #19) — docs/specs/transcription.md §3
+// =============================================================================
+//
+// Six tables, all keyed to one `transcripts` row per uploaded recording. This
+// issue adds only the schema — the upload/pipeline/editing/sharing/export
+// logic that reads and writes it all arrives in issues #25–#29. What is here
+// is deliberately complete on its own, mirroring the `jobs`/`worker_nodes`
+// precedent of "the schema ships whole, ahead of the code that will use it,
+// so nothing downstream needs a follow-up migration to these tables
+// themselves." Every column, enum member and index below is named for and
+// justified by docs/specs/transcription.md §1, §3, §4, §5, §6, §8 and §10 —
+// read those sections for the full reasoning; this comment restates only
+// what has to live beside the code to stay correct.
+//
+// -----------------------------------------------------------------------------
+// Three status enums, not one — restated from spec §1.4
+// -----------------------------------------------------------------------------
+// `transcripts.status` (`TranscriptStatus`) is what every list view and every
+// permission check reads. `transcriptionStatus` and `playbackStatus` are
+// detail fields for the pipeline stepper (issue #30): the transcode and the
+// transcription round trip run CONCURRENTLY, so a single top-level enum would
+// need one member per combination of the two sub-pipelines' states and would
+// still need a second field to say which failure belongs to which
+// sub-pipeline. This is the same design `worker_nodes` already uses for its
+// own health (`status` for stated intent, `lastHeartbeatAt` for computed
+// liveness): small, independently updatable pieces of state, not one field
+// pretending to be several.
+//
+// -----------------------------------------------------------------------------
+// owner_id CASCADES; source_object_id (and every other storage_objects FK
+// below) RESTRICTS — the same column shape, the opposite `onDelete`, because
+// they answer opposite ownership questions
+// -----------------------------------------------------------------------------
+// `owner_id` points UP the ownership chain: a `transcripts` row's only reason
+// to exist is that exactly one user owns it. This is the same "belongs
+// entirely to this user" shape `user_settings`, `refresh_tokens`,
+// `personal_access_tokens` and `device_codes` already use Cascade for — NOT
+// the audit/history shape `AuditEvent.actorUserId`, `Credential
+// .updatedByUserId` or `DatabaseBackupRun.createdById` use SetNull for. The
+// difference is what the row IS: an audit row is a record of an act someone
+// performed against shared infrastructure and must survive the actor's
+// deletion to keep meaning; a transcript is not a record OF anything, it IS
+// the private content itself, and this application's own access model (§6.1)
+// has no path to it once its owner is gone — there is deliberately no
+// `transcripts:read_any` (§6.2), so an owner-less transcript would be a row
+// nobody, including an admin, could ever read, share, edit or delete again.
+// Cascading it away when the account goes is the only outcome consistent
+// with "no read-any, ever."
+//
+// `source_object_id` / `playback_object_id` / `raw_result_object_id` (below)
+// and `transcript_versions.snapshot_object_id` / `transcript_exports
+// .object_id` all point SIDEWAYS, across a module boundary, into a DIFFERENT
+// feature's table (`storage_objects`, issue #21) that this feature does not
+// own. Restrict here protects the referenced object FROM this table's own
+// module boundary being crossed by someone else: a `storage_objects` row a
+// transcript still needs may never be deleted out from under it by the
+// generic storage endpoints or an unrelated cleanup sweep (the exact
+// `managed_by` discipline spec §9.3 already gives every managed object). The
+// only path that may ever remove one of these objects is `transcript.purge`
+// (spec §1.5.7, §10) deleting the referencing row FIRST — which a Restrict
+// FK permits freely, because Restrict blocks deleting the REFERENCED
+// `storage_objects` row while a reference exists, not deleting the
+// REFERENCING transcript row itself.
+//
+// ⚠ ONE CONSEQUENCE OF THAT PAIRING, STATED HONESTLY RATHER THAN PAPERED
+// OVER: `owner_id`'s Cascade fires at the Postgres level on a raw user
+// deletion and does not, and cannot, invoke `transcript.purge`'s storage and
+// provider cleanup — a cascading DELETE only removes SQL rows, and Restrict
+// on the sideways FKs means Postgres will not even attempt to touch the
+// `storage_objects` rows those columns pointed at (a Restrict's ON DELETE
+// action fires only when deleting the REFERENCED row, never when the
+// referencing row disappears by any means, cascade included). A user
+// deleted by a path other than the transcript's own `DELETE
+// /api/transcripts/:id` → `transcript.purge` route therefore leaves that
+// transcript's audio, rendition, raw result and export files as orphaned
+// `storage_objects` rows — reclaimable, but not reclaimed by this cascade.
+// This mirrors the same asymmetry already accepted for `WorkerNode
+// .createdBy`'s Cascade (deleting the SQL row is not the same act as
+// deleting the credential's real-world effects) and is exactly why spec §10
+// frames `transcript.purge` as the only complete-deletion path — a future
+// issue that adds account deletion as a first-class flow should route it
+// through that job rather than a bare `prisma.user.delete()`. This is a
+// decision made explicitly for issue #24, not an oversight; #25–#29 are the
+// right place to close it if account deletion becomes a real user-facing
+// flow.
+//
+// -----------------------------------------------------------------------------
+// speaker_id on transcript_segments — also Restrict, for a same-feature
+// reason rather than a cross-module one
+// -----------------------------------------------------------------------------
+// Unlike the storage FKs above, this Restrict is WITHIN the transcript
+// feature: a speaker may not be deleted while any segment still names it.
+// `speaker.merge` (spec §4.1) is the only op that ever deletes a speaker, and
+// it re-points every one of that speaker's segments to the merge target
+// FIRST, in the same transaction, before deleting the source speaker rows —
+// exactly the shape Restrict requires and enforces. A hypothetical direct
+// "delete this speaker" operation with segments still attached is therefore
+// unrepresentable at the database level, not merely disallowed by service
+// code that could have a bug.
+//
+// -----------------------------------------------------------------------------
+// Hand-written, Prisma-inexpressible constraints — INTENTIONAL SCHEMA DRIFT,
+// the same pattern `jobs_active_dedup_uniq_idx` / `database_backup_runs
+// _active_uniq_idx` already establish
+// -----------------------------------------------------------------------------
+// `transcript_speakers_transcript_id_label_key`, declared only in this
+// migration's `migration.sql`, not as a `@@unique` here: a provider-supplied
+// `label` (e.g. `"A"`) must be unique per transcript, but a user-created
+// speaker (`speaker.create`, spec §4.1) legitimately has none, and Prisma's
+// `@@index`/`@@unique` DSL has no syntax for the partial index's `WHERE
+// "label" IS NOT NULL` clause that scopes the constraint to labelled rows.
+// See that migration file's own header for the full accounting. Every OTHER
+// uniqueness constraint below (`transcript_versions` on `(transcriptId,
+// version)` and `(transcriptId, clientBatchId)`) is fully expressible as a
+// plain `@@unique` and is declared that way — Postgres's standard "NULLS DISTINCT" behaviour already
+// gives `clientBatchId` exactly the semantics spec §5 wants (many versions
+// with a null `clientBatchId`, at most one per transcript for any given
+// non-null value) with no partial index required.
+// =============================================================================
+
+enum TranscriptStatus {
+  uploading
+  processing
+  ready
+  failed
+  deleting
+}
+
+enum TranscriptionStatus {
+  waiting_input
+  queued
+  submitting
+  submitted
+  processing
+  completed
+  failed
+  cancelled
+}
+
+enum PlaybackStatus {
+  pending
+  processing
+  ready
+  failed
+  not_needed
+}
+
+model Transcript {
+  id String @id @default(uuid()) @db.Uuid
+
+  ownerId  String  @map("owner_id") @db.Uuid
+  // The organization this transcript belongs to (issue #485): the scope the
+  // platform sharing slice decides access in (`grants.org_id` must equal it).
+  // Single-organization deployment, so every row carries the default
+  // organization. `transcripts` is deliberately NOT under row-level security:
+  // `AccessPolicy` and the conformance suite need only this column (spike in
+  // the PR for #485, `registerResourceType` in `app-registrations/sharing.ts`).
+  orgId    String  @map("org_id") @db.Uuid
+  title    String
+  language String?
+
+  status              TranscriptStatus    @default(uploading)
+  transcriptionStatus TranscriptionStatus @default(waiting_input) @map("transcription_status")
+  playbackStatus      PlaybackStatus      @default(pending) @map("playback_status")
+
+  // The storage triple. See the block comment above for why every one of
+  // these three is `onDelete: Restrict`, and why that is the opposite choice
+  // from `ownerId` just above despite the same `String @db.Uuid` shape.
+  sourceObjectId    String  @map("source_object_id") @db.Uuid
+  playbackObjectId  String? @map("playback_object_id") @db.Uuid
+  rawResultObjectId String? @map("raw_result_object_id") @db.Uuid
+
+  // Which `TranscriptionProvider` (spec §2.1) this transcript was submitted
+  // to, and that provider's own job id once submitted. Plain strings, not an
+  // enum/FK — the provider registry is code-owned and open (a future
+  // provider is one new class, per spec §2.1), the same reasoning `Job.type`
+  // and `storage_objects.managed_by` already use for an open, code-owned set.
+  provider        String
+  providerJobId   String? @map("provider_job_id")
+  // `{ speakersExpected?, language? }` (spec §2.1/§3.1) — the per-transcript
+  // overrides a submitter chose, opaque JSONB for the same reason every
+  // other provider-shaped payload in this schema (`Job.payload`) is: a
+  // provider-specific option set must not force a migration per provider.
+  providerOptions Json?   @map("provider_options") @db.JsonB
+
+  submittedAt     DateTime? @map("submitted_at") @db.Timestamptz
+  lastPolledAt    DateTime? @map("last_polled_at") @db.Timestamptz
+  completedAt     DateTime? @map("completed_at") @db.Timestamptz
+  // Set once `provider.deleteRemote` succeeds (spec §1.5.2–4, §10) — either
+  // right after `transcription.ingest` commits (the default,
+  // `deleteRemoteAfterIngest: true`) or by `transcript.purge` if it had not
+  // happened yet. NULL means the provider may still hold a copy.
+  remoteDeletedAt DateTime? @map("remote_deleted_at") @db.Timestamptz
+  // Set when `DELETE /api/transcripts/:id` moves this row to `deleting`
+  // (spec §1.1) — i.e. WHEN REMOVAL WAS REQUESTED, not when it finished:
+  // spec §10 is explicit that `transcript.purge` deletes the SQL row once it
+  // is done ("only then deletes the SQL rows"), and the `TranscriptStatus`
+  // enum has no terminal `deleted` member for a finished purge to move to.
+  // This column therefore answers "how long has this been in `deleting`" —
+  // the same question `database_backup_runs.lastHeartbeatAt` answers for a
+  // running dump — for as long as the row exists to ask it of; it never
+  // survives to describe a completed deletion, because nothing does.
+  deletedAt       DateTime? @map("deleted_at") @db.Timestamptz
+  createdAt       DateTime  @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt       DateTime  @updatedAt @map("updated_at") @db.Timestamptz
+  // When the recording was made — defaults to the upload instant; the Meeting
+  // date the knowledge graph reads (docs/specs/ontology.md §5.4). Issue #352:
+  // backfilled from `created_at`, and `TranscriptsService.create` stamps it
+  // with the same `Date` instance as `createdAt`. Editable by the owner or an
+  // editor through `PATCH /api/transcripts/:id`; not versioned, like `title`.
+  recordedAt      DateTime  @default(now()) @map("recorded_at") @db.Timestamptz
+
+  durationMs     Int?    @map("duration_ms")
+  failureReason  String? @map("failure_reason")
+  // Bumped by the SAME conditional `UPDATE ... WHERE current_version = $n`
+  // spec §5 describes for the batch-save race — 0 until `transcription
+  // .ingest` writes version 1 inside its own transaction (spec §1.5.4).
+  currentVersion Int     @default(0) @map("current_version")
+  // Denormalized off `transcript_speakers`/`transcript_segments` so a list
+  // view never joins and counts on every row, matching the "cheap to read
+  // often, recomputed by the one write path that changes the true count"
+  // shape `worker_nodes` and `job_stats_rollup` already use for their own
+  // derived numbers elsewhere in this schema.
+  speakerCount   Int     @default(0) @map("speaker_count")
+  wordCount      Int     @default(0) @map("word_count")
+
+  // A map `speakerId → displayName` recording the first time a user named an
+  // AI-detected speaker (e.g. "Speaker A" -> "Oscar") — issue #323. That
+  // naming is an IDENTIFICATION, metadata about the recording like `title`,
+  // not a correction to its content, so it is deliberately NOT versioned:
+  // `materialize()` overlays this map onto any speaker still at its ingest
+  // default name (`Speaker <label>`) at ANY version, the same way a rename
+  // applies uniformly regardless of which version is being viewed. Keys are
+  // speaker ids with no FK — an entry for a speaker later merged or deleted
+  // is simply ignored on overlay, which is harmless and needs no cleanup.
+  speakerIdentities Json @default("{}") @map("speaker_identities") @db.JsonB
+
+  // GENERATED ALWAYS AS (to_tsvector('english'::regconfig, coalesce(title,
+  // ''))) STORED, plus a GIN index — issue #174, epic #164. Hand-written in
+  // `20260915120000_add_search_vectors/migration.sql` (Prisma has no DSL for
+  // a generated column's expression or an index's access method); see that
+  // migration's header for the full argument, including why it is its OWN
+  // column rather than folded into `TranscriptSegment.searchVector` (a
+  // title match must surface a transcript with no matching segment at all)
+  // and why the two-argument `to_tsvector` form is required (IMMUTABLE,
+  // unlike the one-argument form). `Unsupported` and nullable-optional even
+  // though the database column is generation-populated on every row —
+  // Prisma has no syntax for "the database writes this," and an
+  // `Unsupported` field is never selectable or writable through the client
+  // regardless: every read of this column goes through raw SQL, by design.
+  titleSearchVector Unsupported("tsvector")? @map("title_search_vector")
+
+  owner           User           @relation("TranscriptOwner", fields: [ownerId], references: [id], onDelete: Cascade)
+  org             Organization   @relation(fields: [orgId], references: [id], onDelete: Cascade)
+  sourceObject    StorageObject  @relation("TranscriptSourceObject", fields: [sourceObjectId], references: [id], onDelete: Restrict)
+  playbackObject  StorageObject? @relation("TranscriptPlaybackObject", fields: [playbackObjectId], references: [id], onDelete: Restrict)
+  rawResultObject StorageObject? @relation("TranscriptRawResultObject", fields: [rawResultObjectId], references: [id], onDelete: Restrict)
+
+  speakers      TranscriptSpeaker[]
+  segments      TranscriptSegment[]
+  versions      TranscriptVersion[]
+  exports       TranscriptExport[]
+  // Every note that named this transcript as its source (issue #48, epic
+  // #45) — Restrict on `notes.source_transcript_id`, so a transcript with a
+  // dependent note cannot be deleted until `notes.service.ts`'s own delete
+  // guard clears it. See the block comment above the `Note` model.
+  notesAsSource Note[]                @relation("NoteSourceTranscript")
+  // AI name-check runs against this transcript (issue #328, epic #326). See
+  // the block comment above the `TranscriptNameCheck` model.
+  nameChecks    TranscriptNameCheck[]
+
+  // Connected Knowledge (epic #344, issue #351). Both SetNull: an evidence
+  // row is a citation that survives losing what it points to (`quote` is
+  // what keeps it readable — see the block comment above `KgEvidence`), and
+  // a mention Cascades instead (see the block comment above `KgMention`).
+  kgEvidence KgEvidence[]
+  kgMentions KgMention[]
+
+  // "This owner's transcripts, newest first" — the transcript list view.
+  @@index([ownerId, updatedAt(sort: Desc)])
+  // "This owner's transcripts by when they were recorded" (issue #352).
+  @@index([ownerId, recordedAt(sort: Desc)])
+  // "Every transcript in state X" — `transcripts.housekeeping`'s scans
+  // (spec §1.5.8) and any future admin-adjacent health check.
+  @@index([status])
+  // The organization column's foreign key (issue #485).
+  @@index([orgId])
+  @@map("transcripts")
+}
+
+model TranscriptSpeaker {
+  id           String @id @default(uuid()) @db.Uuid
+  transcriptId String @map("transcript_id") @db.Uuid
+
+  // The provider's own diarization label (e.g. `"A"`). NULL for a speaker a
+  // user created directly (`speaker.create`, spec §4.1), which has none.
+  // Unique per transcript AMONG LABELLED ROWS ONLY — see the block comment
+  // above the enums for why that constraint is hand-written in
+  // `migration.sql` rather than a `@@unique` here.
+  label       String?
+  displayName String  @map("display_name")
+  colorIndex  Int     @map("color_index")
+  // Optimistic-concurrency counter (spec §5). Starts at 1 — the row's first
+  // write (ingest, or `speaker.create`) is already its first version.
+  rev         Int     @default(1)
+
+  transcript Transcript          @relation(fields: [transcriptId], references: [id], onDelete: Cascade)
+  segments   TranscriptSegment[]
+
+  // Connected Knowledge (epic #344, issue #351). The `IDENTIFIED_AS` edge a
+  // diarized speaker gets linked to a real entity through — Cascade, so a
+  // deleted (merged-away) speaker's link goes with it. See the block
+  // comment above `KgRelation` for why this is a real FK to a speaker
+  // rather than a polymorphic `from_kind`/`from_id` pair.
+  kgRelationsAsSpeaker KgRelation[]
+
+  @@map("transcript_speakers")
+}
+
+enum WordsAlignment {
+  exact
+  interpolated
+  none
+}
+
+enum SegmentOrigin {
+  ai
+  user
+}
+
+model TranscriptSegment {
+  // STABLE ACROSS EDITS (spec §3.5, §4.1's `segment.split` test vector): a
+  // split keeps this id on the earlier half specifically so a bookmark, an
+  // export reference, or a concurrent editor's stale `rev` for this segment
+  // still names something real.
+  id           String @id @default(uuid()) @db.Uuid
+  transcriptId String @map("transcript_id") @db.Uuid
+  // Restrict, not Cascade or SetNull — see the block comment above the
+  // enums: a speaker may not be deleted while a segment still names it;
+  // `speaker.merge` re-points every segment away first.
+  speakerId    String @map("speaker_id") @db.Uuid
+
+  startMs Int   @map("start_ms")
+  endMs   Int   @map("end_ms")
+  // Gap-based float, NOT a dense integer sequence (spec §3.4): a
+  // `segment.split` only needs the midpoint between its two neighbours and
+  // touches no other row, versus an integer sequence that would need to
+  // renumber every later segment on every single split.
+  ordinal Float
+
+  text           String
+  // `[{t, s, e, c}]` — text, start, end, confidence per word (spec §3.3),
+  // kept terse because a 10-hour transcript's word array is the single
+  // largest thing in this schema. Opaque JSONB, not a child table: word rows
+  // are never queried or updated independently of their segment.
+  words          Json           @db.JsonB
+  // How much of `words[]` to trust after an edit (spec §3.5). `exact` is the
+  // default because a freshly ingested (`ai_original`) segment, and either
+  // half of a `segment.split`/`segment.join`, are always exact — nothing
+  // about dividing or concatenating an existing array invents a timing.
+  wordsAlignment WordsAlignment @default(exact) @map("words_alignment")
+  confidence     Float?
+
+  // Whether this segment's TEXT originated from the provider or was created
+  // by a person. Defaults `ai` because every segment `transcription.ingest`
+  // writes is exactly that; nothing in spec §4.1's op table currently
+  // creates a segment from nothing (only `speaker.create` has a from-nothing
+  // shape), so `user` exists for a future op without one today.
+  origin     SegmentOrigin @default(ai)
+  // Optimistic-concurrency counter (spec §5), same starting value and same
+  // reasoning as `TranscriptSpeaker.rev` above.
+  rev        Int           @default(1)
+  editedById String?       @map("edited_by_id") @db.Uuid
+  editedAt   DateTime?     @map("edited_at") @db.Timestamptz
+
+  // GENERATED ALWAYS AS (to_tsvector('english'::regconfig, coalesce(text,
+  // ''))) STORED, plus a GIN index — issue #174, epic #164. Unweighted,
+  // unlike `Note.searchVector` below: a segment is one line of speech with
+  // no title of its own to weight against. Hand-written in
+  // `20260915120000_add_search_vectors/migration.sql`; see that migration's
+  // header for the full argument (why the two-argument `to_tsvector` form
+  // is required, why `'english'` is a stated v1 limitation, why a generated
+  // column rather than a trigger — a trigger does not fire under the
+  // `session_replication_role = replica` a database restore runs under).
+  // `Unsupported` and nullable-optional for the same reason
+  // `Transcript.titleSearchVector` is: Prisma cannot express "the database
+  // writes this," and this field is never selectable or writable through
+  // the client — every read goes through raw SQL.
+  searchVector Unsupported("tsvector")? @map("search_vector")
+
+  transcript Transcript        @relation(fields: [transcriptId], references: [id], onDelete: Cascade)
+  speaker    TranscriptSpeaker @relation(fields: [speakerId], references: [id], onDelete: Restrict)
+  // SetNull, matching `AuditEvent.actorUserId`/`Credential.updatedByUserId`:
+  // "who last hand-edited this line" is an audit fact about the segment, not
+  // something the segment's own existence depends on.
+  editedBy   User?             @relation("TranscriptSegmentEditor", fields: [editedById], references: [id], onDelete: SetNull)
+
+  // AI name-check suggestions proposed against this segment (issue #328,
+  // epic #326). See the block comment above the `TranscriptNameCheck` model.
+  nameSuggestions TranscriptNameSuggestion[]
+
+  // Connected Knowledge (epic #344, issue #351). SetNull — an evidence row
+  // is a citation that survives losing the segment it pointed to; `quote`
+  // is what keeps it readable afterwards. See the block comment above
+  // `KgEvidence`.
+  kgEvidence KgEvidence[]
+
+  // The compound order both a segment list and a time-window query
+  // (`GET /:id/words?fromMs&toMs`) need (spec §3.3).
+  @@index([transcriptId, startMs, ordinal])
+  @@map("transcript_segments")
+}
+
+enum TranscriptVersionKind {
+  ai_original
+  edit
+  restore
+}
+
+model TranscriptVersion {
+  id           String                @id @default(uuid()) @db.Uuid
+  transcriptId String                @map("transcript_id") @db.Uuid
+  version      Int
+  kind         TranscriptVersionKind
+
+  // NULL means "the AI" — the ingest handler is the only writer that ever
+  // leaves this null (spec §4.5); every human-triggered version (`edit`,
+  // `restore`) always has a real author. SetNull, not Restrict/Cascade: a
+  // version is permanent history (spec §4.5 — "nothing in this design ever
+  // deletes a `transcript_versions` row"; only `transcript.purge` deleting
+  // the whole transcript does) and must survive the author's own account
+  // being deleted, the same audit posture as `DatabaseBackupRun.createdById`.
+  authorId String? @map("author_id") @db.Uuid
+  summary  String?
+  // The concrete ops this version applied (spec §4.1) — e.g. the expanded
+  // `segment.update_text` ops a `transcript.find_replace` call becomes
+  // (spec §4.2), NEVER the abstract find/replace call itself, so replaying
+  // history stays correct even if this application's matching logic changes
+  // later.
+  ops      Json    @db.JsonB
+
+  // The version number this row restored FROM, when `kind: restore` (spec
+  // §4.5). A plain version number, not a self-relation FK: it names another
+  // row's `(transcriptId, version)` pair, which is not a column any FK can
+  // point at directly, and a restore's target version is immutable history
+  // that is never itself deleted (short of purging the whole transcript).
+  restoredFromVersion Int?    @map("restored_from_version")
+  // The gzipped materialized state at this version, when this version was
+  // snapshotted (spec §4.3 — always for v1 and every restore, otherwise on a
+  // size-or-count trigger). NULL for a version materialized purely by
+  // replaying `ops` from the nearest earlier snapshot.
+  snapshotObjectId    String? @map("snapshot_object_id") @db.Uuid
+  // Idempotency key for a retried save (spec §5): a client that saved but
+  // never saw the response retries with the SAME `clientBatchId`, and
+  // `@@unique([transcriptId, clientBatchId])` below is what lets the write
+  // path detect the retry and return the original version instead of
+  // creating a second one. NULL for a version this application created
+  // itself (ingest, restore) rather than in response to a client batch —
+  // Postgres's standard NULLS-DISTINCT behaviour is exactly what is wanted
+  // there: any number of null-`clientBatchId` versions may coexist.
+  clientBatchId       String? @map("client_batch_id")
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  transcript     Transcript     @relation(fields: [transcriptId], references: [id], onDelete: Cascade)
+  author         User?          @relation("TranscriptVersionAuthor", fields: [authorId], references: [id], onDelete: SetNull)
+  // Restrict, matching every other storage_objects FK on this feature — see
+  // the block comment above the enums.
+  snapshotObject StorageObject? @relation("TranscriptVersionSnapshotObject", fields: [snapshotObjectId], references: [id], onDelete: Restrict)
+
+  // The version sequence itself, and what `materialize()` (spec §4.4) looks
+  // up by.
+  @@unique([transcriptId, version])
+  // The idempotent-retry key described above. Plain `@@unique`, not a
+  // hand-written partial index: Postgres's default NULLS DISTINCT behaviour
+  // already gives exactly the wanted semantics for a nullable column, unlike
+  // `transcript_speakers`' label uniqueness above.
+  @@unique([transcriptId, clientBatchId])
+  @@map("transcript_versions")
+}
+
+enum TranscriptExportStatus {
+  pending
+  ready
+  failed
+}
+
+model TranscriptExport {
+  id           String @id @default(uuid()) @db.Uuid
+  transcriptId String @map("transcript_id") @db.Uuid
+  version      Int
+
+  // The exporter's own registry key (`markdown`, `pdf`, or the permanent
+  // published JSON format spec §8.2 names). Plain string, not an enum, for
+  // the same self-registering-registry reason `Job.type` is: adding an
+  // exporter (spec §8.1 — "one new class registering itself") must cost
+  // zero migrations to this table.
+  format      String
+  // The requester's export options, as passed to the exporter's own
+  // `optionsSchema` (spec §8.1) — opaque JSONB, since the option shape is
+  // defined by the exporter, not by this table.
+  options     Json                   @db.JsonB
+  // sha256 (or similar) of `{ format, version, options }` (spec §8.5) — the
+  // content-addressed key `POST /:id/exports` looks up to decide whether an
+  // existing, unexpired export can be returned instead of rendering again.
+  optionsHash String                 @map("options_hash")
+  status      TranscriptExportStatus @default(pending)
+
+  // The rendered file, once `status: ready`. Restrict, matching every other
+  // storage_objects FK on this feature (block comment above the enums) —
+  // only `transcripts.housekeeping`'s expiry sweep (spec §8.5) may remove
+  // it, and only after deleting this row first.
+  objectId      String? @map("object_id") @db.Uuid
+  // The `transcript.export` job that rendered this row, when one did (spec
+  // §1.5.6). `@unique`/SetNull, mirroring `DatabaseBackupRun.jobId` exactly:
+  // a second render for the SAME job is unrepresentable, this row's own
+  // 7-day retention is independent of `job.history.purge`'s schedule for the
+  // underlying `jobs` row, and losing the link on a history purge must never
+  // mean losing the export.
+  jobId         String? @unique @map("job_id") @db.Uuid
+  // Who asked for this export. NOT NULL and Cascade — unlike every SetNull
+  // audit column elsewhere in this schema, an export is a disposable,
+  // byte-for-byte reproducible artifact with a 7-day expiry already built in
+  // (spec §8.5): nothing is lost by deleting a pending/ready export row
+  // alongside the account that requested it, the same way nothing is lost
+  // by `transcripts.housekeeping` expiring it on its own schedule.
+  requestedById String  @map("requested_by_id") @db.Uuid
+
+  error     String?
+  // 7 days out from creation by default (spec §8.5) — what
+  // `transcripts.housekeeping`'s sweep compares against.
+  expiresAt DateTime @map("expires_at") @db.Timestamptz
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  transcript  Transcript     @relation(fields: [transcriptId], references: [id], onDelete: Cascade)
+  object      StorageObject? @relation("TranscriptExportObject", fields: [objectId], references: [id], onDelete: Restrict)
+  job         Job?           @relation(fields: [jobId], references: [id], onDelete: SetNull)
+  requestedBy User           @relation("TranscriptExportRequestedBy", fields: [requestedById], references: [id], onDelete: Cascade)
+
+  // The reuse-by-content-hash lookup spec §8.5 names explicitly ("the index
+  // issue #24 declares for exactly this lookup"). Not unique: an expired or
+  // failed row may briefly coexist with a fresh one sharing the same key
+  // before housekeeping removes the stale one.
+  //
+  // `map:` pins an explicit name: Prisma's own default-generated name for
+  // this four-column index is 64 bytes, one over PostgreSQL's 63-byte
+  // identifier limit, which would otherwise leave the exact truncated name
+  // to guess at in the hand-written migration.sql this issue ships without a
+  // live database to diff against.
+  @@index([transcriptId, version, format, optionsHash], map: "transcript_exports_lookup_idx")
+  @@map("transcript_exports")
+}
+
+// =============================================================================
+// Transcript Name Checks (issue #328, epic #326)
+// =============================================================================
+//
+// AI-assisted detection of misspelled/mis-transcribed proper names and terms
+// across a transcript's segments. A `TranscriptNameCheck` is one AI run —
+// the request, its cost accounting, and its terminal state — and a
+// `TranscriptNameSuggestion` is one PROPOSED edit that run produced. Both
+// tables are deliberately never a second source of truth for transcript
+// content: accepting a suggestion turns it into an ordinary
+// `segment.update_text` op recorded through the exact same `/operations`
+// path and `TranscriptVersion` history every other correction uses (see the
+// block comment above `TranscriptVersion`) — these rows never write
+// `transcript_segments.text` directly, only propose a change to it.
+// `segmentRev` on a suggestion pins the `TranscriptSegment.rev` its offsets
+// were computed against, the identical optimistic-concurrency shape
+// `TranscriptVersion`'s `rev` split already uses elsewhere in this schema,
+// so a suggestion whose segment was edited out from under it is detectable
+// at apply time rather than silently misapplied at the wrong offset —
+// `status: stale` is that outcome, not a bug report.
+
+enum TranscriptNameCheckMode {
+  standard
+  thorough
+}
+
+enum TranscriptNameCheckStatus {
+  pending
+  running
+  ready
+  failed
+}
+
+model TranscriptNameCheck {
+  id           String @id @default(uuid()) @db.Uuid
+  transcriptId String @map("transcript_id") @db.Uuid
+
+  // Who asked for this run. SetNull, not Cascade/Restrict — unlike
+  // `TranscriptExport.requestedById` (a disposable, re-renderable artifact
+  // deleted with its requester), a name-check run and the suggestions it
+  // produced are worth keeping as transcript history even after the
+  // requesting account is gone, the same audit posture
+  // `TranscriptVersion.authorId` already takes.
+  requestedById String? @map("requested_by_id") @db.Uuid
+
+  // `standard` (segments only) vs `thorough` (a wider discovery pass) — a
+  // closed, spec-defined pair, worth a real enum rather than a string.
+  mode   TranscriptNameCheckMode
+  status TranscriptNameCheckStatus @default(pending)
+
+  // The `Transcript.currentVersion` this run read segment text from,
+  // matching `TranscriptExport.version`'s reasoning: a run started against
+  // one version must not be silently reinterpreted against a later one once
+  // edits land mid-run.
+  basedOnVersion Int @map("based_on_version")
+
+  // The target names/terms this run checked for — a string array, opaque
+  // JSONB for the same reason `TranscriptSegment.words` and
+  // `Transcript.providerOptions` are: the caller-supplied or AI-discovered
+  // term list has no shape this table needs to enforce.
+  terms Json @db.JsonB
+
+  // Which AI provider/model produced this run's suggestions — plain
+  // strings, not an enum/FK, matching `Transcript.provider`'s own
+  // open-registry reasoning: a new provider must cost zero migrations here.
+  providerId String? @map("provider_id")
+  model      String?
+
+  // Denormalized off `transcript_name_suggestions` so a list/detail read
+  // never joins and counts on every request, matching
+  // `Transcript.speakerCount`/`.wordCount`'s "cheap to read often,
+  // recomputed by the one write path that changes the true count" shape.
+  candidateCount  Int @default(0) @map("candidate_count")
+  suggestionCount Int @default(0) @map("suggestion_count")
+
+  // Cost accounting for this run's own AI call(s), the same pair
+  // `NoteGeneration` tracks per generation.
+  inputTokens  Int @default(0) @map("input_tokens")
+  outputTokens Int @default(0) @map("output_tokens")
+
+  // A closed-in-spirit taxonomy kept as a plain string rather than a second
+  // copy of `NoteGenerationErrorClass`'s enum, matching `Job.type`'s own
+  // "plain string, code-owned set" reasoning.
+  errorClass String? @map("error_class")
+  error      String?
+
+  // The `transcript.name_check` job that ran this check, when one did. `@unique`/
+  // nullable/`SetNull`, mirroring `TranscriptExport.jobId`/
+  // `DatabaseBackupRun.jobId` exactly: this row's own lifetime (read by the
+  // review UI long after job history is purged) is independent of
+  // `job.history.purge`'s schedule for the underlying `jobs` row.
+  jobId String? @unique @map("job_id") @db.Uuid
+
+  createdAt   DateTime  @default(now()) @map("created_at") @db.Timestamptz
+  startedAt   DateTime? @map("started_at") @db.Timestamptz
+  completedAt DateTime? @map("completed_at") @db.Timestamptz
+
+  transcript  Transcript @relation(fields: [transcriptId], references: [id], onDelete: Cascade)
+  requestedBy User?      @relation("TranscriptNameCheckRequestedBy", fields: [requestedById], references: [id], onDelete: SetNull)
+  job         Job?       @relation(fields: [jobId], references: [id], onDelete: SetNull)
+
+  suggestions TranscriptNameSuggestion[]
+
+  // "This transcript's name-check runs, newest first" — the run history
+  // list.
+  @@index([transcriptId, createdAt(sort: Desc)])
+  @@map("transcript_name_checks")
+}
+
+enum TranscriptNameSuggestionStatus {
+  pending
+  accepted
+  rejected
+  stale
+}
+
+model TranscriptNameSuggestion {
+  id      String @id @default(uuid()) @db.Uuid
+  checkId String @map("check_id") @db.Uuid
+
+  // Cascade, matching `TranscriptSegment`'s own relation to `Transcript`: a
+  // suggestion against a segment that no longer exists (a later
+  // `segment.split`/`segment.join`/delete) has nothing left to apply to.
+  segmentId  String @map("segment_id") @db.Uuid
+  // The `TranscriptSegment.rev` these offsets were computed against — see
+  // the block comment above for why a mismatch at apply time means `stale`,
+  // never a silently wrong offset.
+  segmentRev Int    @map("segment_rev")
+
+  // UTF-16 offsets into `TranscriptSegment.text` at `segmentRev` — matching
+  // JavaScript string indexing end to end, so the editor, the API and this
+  // column all agree on one encoding.
+  start Int
+  end   Int
+
+  original    String
+  replacement String
+
+  confidence Float?
+  reason     String?
+  // `'phonetic' | 'discovery'` today — plain string, not an enum, matching
+  // `Transcript.provider`'s own open-registry reasoning: which detection
+  // strategies exist is code, not schema.
+  source     String
+
+  status      TranscriptNameSuggestionStatus @default(pending)
+  decidedAt   DateTime?                      @map("decided_at") @db.Timestamptz
+  // SetNull, matching `TranscriptSegment.editedById`: "who accepted or
+  // rejected this suggestion" is an audit fact about the suggestion, not
+  // something its own existence depends on.
+  decidedById String?                        @map("decided_by_id") @db.Uuid
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  check     TranscriptNameCheck @relation(fields: [checkId], references: [id], onDelete: Cascade)
+  segment   TranscriptSegment   @relation(fields: [segmentId], references: [id], onDelete: Cascade)
+  decidedBy User?               @relation("TranscriptNameSuggestionDecidedBy", fields: [decidedById], references: [id], onDelete: SetNull)
+
+  // "This run's suggestions, filtered by status" — the review UI's default
+  // list.
+  @@index([checkId, status])
+  // "Every suggestion touching this segment" — applying/staling suggestions
+  // when a segment is edited elsewhere.
+  @@index([segmentId])
+  @@map("transcript_name_suggestions")
+}