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

package/host/prisma/schema/platform.ai.prisma

@@ -0,0 +1,419 @@
+// GENERATED by platform db compose — do not edit
+// source: package:ai.prisma
+
+// =============================================================================
+// AI Platform (issue #423, epic #419, umbrella #418)
+// =============================================================================
+//
+// Four tables — the model catalog, per-user encrypted provider keys,
+// background AI run results, and usage accounting — for the whole platform
+// this epic builds. THIS ISSUE OWNS SCHEMA ONLY: no service or controller in
+// this build reads or writes any of these tables yet (that is #427, #428,
+// #431, #432). They land ahead of their consumers, on the same "declare the
+// collision hotspot once, let every other AI story run in parallel" logic
+// `system-settings.service.ts`'s operations-namespaces header already argues
+// for `system_settings`: `schema.prisma`, `seed-data.ts`,
+// `roles.constants.ts` and `settings.schema.ts` are each touched by every
+// story in the epic, so this one story claims them in a single migration
+// instead of every later story racing to edit the same four files.
+//
+// -----------------------------------------------------------------------------
+// ⚠ NO COLUMN HERE CAN EVER HOLD A PLAINTEXT PROVIDER KEY
+// -----------------------------------------------------------------------------
+// `UserAiKey.secret` is ciphertext ONLY — the output of `encryptSecret(
+// plaintext, 'ai_user_key')` (`@marinoscar/platform-api/core`), the same
+// AES-GCM helper `Credential.secret` already uses, keyed under a purpose
+// label specific to this table so a ciphertext lifted from one row cannot be
+// decrypted as if it were the other's. `hint` is the non-secret display aid
+// (`'••••' + last 4`, mirroring `Credential.hint`), never enough on its own
+// to reconstruct the key. `AiRun.request` is explicitly a NORMALIZED request
+// — model id, parameters, truncated/redacted prompt shape — never the
+// caller's raw provider key, which the run's own executor already holds
+// separately (from `UserAiKey`, decrypted for that one call and discarded).
+//
+// -----------------------------------------------------------------------------
+// `UserAiKey` — Cascade, NOT SetNull, and the contrast with `Credential` is
+// deliberate
+// -----------------------------------------------------------------------------
+// `Credential.updatedByUser` is `SetNull`: that table is shared
+// infrastructure (an SMTP password, a storage secret) that outlives whoever
+// last edited it, because the credential belongs to the DEPLOYMENT, not to
+// the editor. `UserAiKey.user` is the opposite shape on purpose — a BYOK key
+// belongs to the ONE ACCOUNT that typed it in, has no meaning to anyone else,
+// and (like `PushSubscription.user`, which makes the identical argument for a
+// live per-device credential) has no reader once that account is gone. There
+// is no "the deployment's OpenAI key" here, only "this user's OpenAI key", so
+// deleting the user is what should delete it.
+//
+// -----------------------------------------------------------------------------
+// `AiRun.user` / `AiUsageEvent.user` — SetNull, matching `NotificationDelivery
+// .user`
+// -----------------------------------------------------------------------------
+// Both are HISTORY, not live state: a run's output and a usage event's token
+// counts remain meaningful — for billing reconciliation, for "was this
+// account affected by the incident on provider X" — after the account that
+// triggered them is gone, exactly the argument `NotificationDelivery.user`'s
+// own block comment makes for a delivery attempt. Nulling the FK preserves
+// that record; cascading it would erase usage accounting as a side effect of
+// an unrelated account-deletion path elsewhere in the app. Both are also
+// deliberately nullable up front (not merely nullable-after-cascade), the same
+// "global job" shape `Job.subjectType`/`subjectId` use: a background run or a
+// catalog-discovery usage event may have no requesting user at all.
+//
+// -----------------------------------------------------------------------------
+// `capabilities` / `units` — JSONB, not typed columns, and Zod-validated in
+// code
+// -----------------------------------------------------------------------------
+// `AiModel.capabilities` (what a model can do — text, vision, tool calling,
+// structured output, ...) and `AiUsageEvent.units` (a per-operation unit
+// count that varies by kind: `{ images: 2 }`, `{ audioSeconds: 31.4 }`) are
+// each shaped differently per provider and per operation, and neither is
+// filtered or indexed on by any query this issue's schema needs to support.
+// Both follow `Job.payload`'s and `WorkerNode.capabilities`' own precedent:
+// opaque JSONB here, a real Zod schema (`AiModelCapabilities`) at the
+// consuming layer that arrives with #427/#428. A typed column per capability
+// would be a migration every time a provider ships a new one.
+//
+// -----------------------------------------------------------------------------
+// `provider` / `operation` / `status` / `keySource` — plain strings, not
+// Prisma enums
+// -----------------------------------------------------------------------------
+// Same reasoning as `Job.type`, `NotificationDelivery.channel` and
+// `WorkerNode.executor` throughout this file: these are small, code-owned,
+// GROWING sets (`AI_PROVIDER_IDS` names `'openai'` today and Phase 3 appends
+// to it; new operations and key sources are exactly the shape of change a
+// provider integration adds), so a Postgres enum would reintroduce the
+// migration this design otherwise avoids, and a row must be able to outlive
+// whatever build produced it. `AiRun.status` and `AiUsageEvent.status` are
+// each that model's OWN closed state machine in every other sense — but they
+// are kept as strings rather than promoted to a Prisma enum for the same
+// forward-compatibility reason the rest of this section gives, not because
+// they are open-ended in practice.
+//
+// -----------------------------------------------------------------------------
+// `AiModel.capabilitySource` — `'catalog' | 'admin_override' | 'unclassified'`
+// -----------------------------------------------------------------------------
+// Records WHERE `capabilities` came from, because the three sources disagree
+// in trustworthiness and in how long they last: `'catalog'` is the
+// provider's own advertised capability list (refreshed on discovery, and the
+// first thing a later sync overwrites), `'admin_override'` is a deployment
+// operator's manual correction (must survive a catalog refresh that would
+// otherwise clobber it — that survival rule belongs to #427's sync logic, not
+// to this column), and `'unclassified'` is the default for a model this
+// deployment has seen but never classified at all. A model discovered before
+// any classification runs is `'unclassified'`, never a guess.
+model AiModel {
+  id String @id @default(uuid()) @db.Uuid
+
+  // The provider registration this model belongs to, e.g. `'openai'`. See
+  // `AI_PROVIDER_IDS` (`common/schemas/settings.schema.ts`) — a growing,
+  // code-owned list, and a plain string here for the reason given above.
+  provider String
+
+  // The provider's own raw model identifier (e.g. `'gpt-4o-mini'`), as
+  // opposed to `id` above, which is this table's own row identity.
+  modelId String @map("model_id")
+
+  // Operator/UI-facing label. Nullable: a freshly discovered model has none
+  // until an admin (or a later sync) names it.
+  displayName String? @map("display_name")
+
+  // AiModelCapabilities, Zod-validated at the consuming layer (#427) — see
+  // the block comment above for why this is JSONB rather than typed columns.
+  capabilities Json
+
+  // Where `capabilities` came from — see the block comment above.
+  // `'unclassified'` is the default: a model this deployment has observed but
+  // not yet classified, one way or the other.
+  capabilitySource String @default("unclassified") @map("capability_source")
+
+  // Whether this deployment offers the model to callers at all. Defaults to
+  // `false`: a freshly discovered model is inert until an administrator (or a
+  // later sync's own policy) turns it on, the same "nothing changes behaviour
+  // on discovery alone" posture `WorkerNode.status` defaulting to `offline`
+  // and `databaseBackup.enabled` defaulting to `false` both take elsewhere in
+  // this schema.
+  enabled Boolean @default(false)
+
+  contextWindow   Int? @map("context_window")
+  maxOutputTokens Int? @map("max_output_tokens")
+
+  // When this row was first created, vs. `lastSeenAt` below, which moves on
+  // every discovery sync that still finds the model — the same "creation time
+  // vs. liveness" split `WorkerNode.registeredAt`/`.lastHeartbeatAt` make for
+  // an entirely different kind of inventory.
+  discoveredAt DateTime  @default(now()) @map("discovered_at") @db.Timestamptz
+  lastSeenAt   DateTime  @default(now()) @map("last_seen_at") @db.Timestamptz
+  // Set by a discovery sync (#427) that no longer sees this model in the
+  // provider's own catalog. Nullable: most rows are never deprecated.
+  // Deliberately not deleted — a deprecated model may still be referenced by
+  // historical `AiRun`/`AiUsageEvent` rows via its `provider`/`modelId` pair,
+  // and losing the row would lose the display name and capability record for
+  // that history.
+  deprecatedAt DateTime? @map("deprecated_at") @db.Timestamptz
+
+  // Provenance of the last edit — see the block comment above for why this
+  // is `SetNull`, matching `Credential.updatedByUser` rather than
+  // `UserAiKey.user` below.
+  updatedByUserId String?  @map("updated_by_user_id") @db.Uuid
+  updatedByUser   User?    @relation("AiModelUpdatedBy", fields: [updatedByUserId], references: [id], onDelete: SetNull)
+  updatedAt       DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // One row per (provider, model) pair, ever — a discovery sync upserts on
+  // this rather than inserting duplicates on every re-run.
+  @@unique([provider, modelId])
+  // "Which models may this deployment currently offer" — the catalog read
+  // every AI-calling path needs, filtered to the provider in play.
+  @@index([provider, enabled])
+  @@map("ai_models")
+}
+
+// BYOK ("bring your own key"): one encrypted provider key per (user,
+// provider), never per deployment. See the block comment above this section
+// for why `user` is `Cascade` here and NOT `SetNull` like `Credential
+// .updatedByUser` or `AiModel.updatedByUser` above — this key has exactly one
+// owner and no meaning to anyone else once that owner's account is gone.
+model UserAiKey {
+  id     String @id @default(uuid()) @db.Uuid
+  userId String @map("user_id") @db.Uuid
+
+  // Which provider this key authenticates against, e.g. `'openai'`. Plain
+  // string for the same forward-compatibility reason `AiModel.provider` is.
+  provider String
+
+  // Ciphertext ONLY — `encryptSecret(plaintext, 'ai_user_key')`. See the
+  // block comment above this section (and `Credential.secret`'s own comment)
+  // for the full argument; @db.Text for the identical reason
+  // `Credential.secret` is: an AES-GCM payload has no meaningful length
+  // bound, so it must never be truncated.
+  secret String @db.Text
+
+  // Non-secret display aid (`'••••' + last 4`), mirroring `Credential.hint`.
+  // Nullable: a key can exist before anyone has decided how to hint it.
+  hint String?
+
+  // The last time this key was proven to work against its provider (a live
+  // probe call, not merely "was saved"). Nullable: never verified yet.
+  verifiedAt    DateTime? @map("verified_at") @db.Timestamptz
+  // The provider's own error code from the most recent failed verification or
+  // use, so a user who cannot see why a key stopped working has somewhere to
+  // look. Nullable: no failure recorded (yet, or ever).
+  lastErrorCode String?   @map("last_error_code")
+
+  // Which of this provider's models this specific key was actually able to
+  // reach on its last verification, as opposed to `AiModel.enabled`, which is
+  // a DEPLOYMENT-WIDE policy decision independent of any one key. A key with
+  // a narrower API scope, or one hitting a provider-side allowlist, can
+  // legitimately reach fewer models than the deployment otherwise offers.
+  reachableModelIds  String[]  @default([]) @map("reachable_model_ids")
+  reachableCheckedAt DateTime? @map("reachable_checked_at") @db.Timestamptz
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  //
+  // Cascade — see the block comment above this section for why this
+  // deliberately reverses `Credential.updatedByUser`'s `SetNull`.
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  // One key per (user, provider) — saving a new key for a provider replaces
+  // the old one rather than accumulating a history of them.
+  @@unique([userId, provider])
+  @@map("user_ai_keys")
+}
+
+// One row per AI call this platform ever ran through the background queue —
+// the record `#432`'s job handler(s) read from and write progress/output to.
+// This issue is schema only, matching every other table in this section: no
+// enqueue path, no job handler and no controller exists yet.
+// @extensible — back-relations only, added with "extend model AiRun { ... }" in a fragment
+// (an app's own annotation of a run, for example a review verdict). The table is org-owned
+// with row-level security forced, so a table of the app's that holds `org_id` links to a run
+// with a composite foreign key `(ai_run_id, org_id)` -> `ai_runs (id, org_id)`; the
+// `@@unique([id, orgId])` below exists for it.
+model AiRun {
+  id String @id @default(uuid()) @db.Uuid
+
+  // Nullable, deliberately — see the block comment above this section for why
+  // this is `SetNull` rather than `Cascade`, and why a run may have no
+  // requesting user at all (a system-initiated run, mirroring `Job.subjectType`
+  // /`subjectId` both being null together for a global job).
+  userId String? @map("user_id") @db.Uuid
+
+  // The `jobs` row this run executes under, when it runs through the queue at
+  // all. Nullable, and deliberately NOT a foreign key — mirrors
+  // `DatabaseBackupRun`'s OWN relation to `Job` in spirit (a dedicated table
+  // outliving the generic queue's retention) but stays a plain column rather
+  // than a `@relation`+`@unique` pair: unlike a backup run, an `AiRun` is not
+  // one-to-one with its job in every future shape this platform may take
+  // (a retried run may reuse the id, or a future synchronous path may have no
+  // job at all), so this issue commits only to recording the id, not to the
+  // stronger one-to-one relation `DatabaseBackupRun.jobId` commits to.
+  jobId String? @map("job_id") @db.Uuid
+
+  // pending|running|succeeded|failed|cancelled — this run's own state
+  // machine, kept as a plain string rather than a Prisma enum for the
+  // forward-compatibility reason given in the block comment above this
+  // section.
+  status String @default("pending")
+
+  provider String
+  modelId  String @map("model_id")
+
+  // The NORMALIZED request — model id, parameters, and the FULL prompt shape
+  // (instructions, input, tools, structured-output schema) `toStoredRunRequest`
+  // (`runtime/ai-run-request.ts`) built from it — and NEVER the caller's key
+  // material, which this run's executor holds separately and only for the
+  // duration of the call. Deliberately not redacted or truncated: the
+  // worker that claims this job re-issues the user's exact request, and a
+  // truncated prompt would make the replayed call diverge from the one the
+  // user actually asked for. See the ⚠ block comment above this section.
+  request Json
+
+  output       Json?
+  errorCode    String? @map("error_code")
+  errorMessage String? @map("error_message")
+
+  createdAt   DateTime  @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime  @updatedAt @map("updated_at") @db.Timestamptz
+  completedAt DateTime? @map("completed_at") @db.Timestamptz
+
+  // The organization the run belongs to (#725). NOT NULL, row-level security
+  // forced (policy `ai_runs_org_isolation`). `Restrict`, not `SetNull`: the
+  // column is NOT NULL, so history cannot survive an organization's deletion
+  // by nulling it; deleting an organization first purges its runs.
+  orgId String @map("org_id") @db.Uuid
+
+  // The registered AI feature the run was started for (`registerAiFeature`,
+  // PP-14.17, #935): a bounded id the feature registry validated, NEVER free
+  // text. Nullable (a run started without a feature, and every row written
+  // before this column existed), and a plain string rather than a reference:
+  // a feature is code, not data, and a row must outlive the feature that
+  // wrote it. Carried onto the run's usage rows, so per-feature usage is
+  // answerable from the database.
+  feature String?
+
+  // Relations
+  //
+  // SetNull — see the block comment above this section.
+  user User?         @relation(fields: [userId], references: [id], onDelete: SetNull)
+  org  Organization  @relation(fields: [orgId], references: [id], onDelete: Restrict)
+
+  // "This user's run history, most recent first" — the one query this table
+  // is known to need today (a user's own run list).
+  @@index([userId, createdAt])
+  // The same query behind the policy filter `org_id = X`.
+  @@index([orgId, userId, createdAt])
+  // The retention sweep (`ai.runs.purge`, #681): "oldest first, older than
+  // the cutoff" across every user, which `[userId, createdAt]` cannot serve.
+  @@index([createdAt])
+  // The target of an app table's composite foreign key (id, org_id), like
+  // `Group` and `StorageObject`: a plain FK on `id` would let a row of one
+  // organization point at another's (an FK check bypasses row-level security).
+  @@unique([id, orgId])
+  @@map("ai_runs")
+}
+
+// One row per AI operation attempted, successful or not — the usage/billing
+// accounting ledger, deliberately separate from `AiRun` above. `AiRun` is
+// "what did this background call do" (one row per queued call, with its own
+// request/output); `AiUsageEvent` is "what did this cost", covering every
+// operation kind (`responses|images|audio.transcribe|audio.speech|
+// embeddings|catalog`) whether or not it went through the queue at all — a
+// synchronous catalog-listing call has no `AiRun` but still consumes a
+// provider call worth recording.
+model AiUsageEvent {
+  id String @id @default(uuid()) @db.Uuid
+
+  // Nullable, `SetNull` — see the block comment above this section. A
+  // catalog-discovery sync run by the deployment itself, not by any one
+  // user, is the concrete case that leaves this null.
+  userId String? @map("user_id") @db.Uuid
+
+  provider String
+  modelId  String @map("model_id")
+
+  // responses|images|audio.transcribe|audio.speech|embeddings|catalog — the
+  // kind of provider call this event records. Plain string for the
+  // forward-compatibility reason given above: a new operation kind (a future
+  // provider capability) must cost zero migrations here.
+  operation String
+
+  // user|org|admin_discovery — WHOSE key paid for this call. Distinct from
+  // `provider`/`modelId` (which model answered) and from `userId` (who asked):
+  // an admin-triggered catalog discovery sync can be `keySource:
+  // 'admin_discovery'` with no requesting `userId` at all, and a BYOK-only
+  // deployment's every real usage event is `keySource: 'user'`. `'org'` is
+  // reserved for a future org-wide fallback key, matching `AI_KEY_POLICIES`'
+  // `'byok_with_org_fallback'` in `common/schemas/settings.schema.ts`.
+  keySource String @map("key_source")
+
+  // Token accounting. All nullable: an `images`/`audio.*` operation has no
+  // token counts at all, and `reasoningTokens`/`cachedInputTokens` are
+  // provider-specific breakdowns that not every provider or model reports.
+  inputTokens       Int? @map("input_tokens")
+  outputTokens      Int? @map("output_tokens")
+  reasoningTokens   Int? @map("reasoning_tokens")
+  cachedInputTokens Int? @map("cached_input_tokens")
+
+  // Non-token unit accounting for operations tokens don't measure — e.g.
+  // `{ images: 2 }` for an image generation call, `{ audioSeconds: 31.4 }` for
+  // transcription/speech. JSONB for the reason given in the block comment
+  // above this section: the shape varies by `operation` and no query here
+  // filters or indexes on it.
+  units Json?
+
+  latencyMs Int @map("latency_ms")
+
+  // succeeded|failed|cancelled — this event's own closed outcome, kept as a
+  // plain string for the identical forward-compatibility reason `AiRun
+  // .status` is.
+  status    String
+  errorCode String? @map("error_code")
+
+  // The provider's own request/trace id, for reconciling a usage row against
+  // that provider's dashboard or support ticket. Nullable: not every provider
+  // call surfaces one.
+  providerRequestId String? @map("provider_request_id")
+
+  // The `jobs` row this usage event was incurred under, when it was. Plain
+  // column, no relation — same reasoning as `AiRun.jobId` above.
+  jobId String? @map("job_id") @db.Uuid
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  // The organization that incurred the call (#725). Nullable on purpose: a
+  // deployment-wide event (a catalogue sync) has none, and `SetNull` keeps the
+  // history of a deleted organization. Row-level security forced (policy
+  // `ai_usage_events_org_isolation`): a NULL row is visible to the system
+  // client only.
+  orgId String? @map("org_id") @db.Uuid
+
+  // The registered AI feature the call was made for (`registerAiFeature`,
+  // PP-14.17, #935), so usage can be filtered and grouped per feature from
+  // the database. Nullable: a call made without a feature, a catalogue sync,
+  // and every row written before this column existed have none. A plain
+  // string, never a reference, and never free text: only an id the feature
+  // registry validated is written.
+  feature String?
+
+  // Relations
+  user User?         @relation(fields: [userId], references: [id], onDelete: SetNull)
+  org  Organization? @relation(fields: [orgId], references: [id], onDelete: SetNull)
+
+  // "This user's usage history, most recent first" — mirrors `AiRun`'s own
+  // index for the identical reason.
+  @@index([userId, createdAt])
+  // The same query behind the policy filter `org_id = X`, and the per-org
+  // usage window.
+  @@index([orgId, userId, createdAt])
+  @@index([orgId, createdAt])
+  // "This organization's usage of one feature in a window" (PP-14.17, #935):
+  // the per-feature filter and group-by of the usage report.
+  @@index([orgId, feature, createdAt])
+  // "Usage across all users in a time window" — the deployment-wide
+  // accounting/billing query, independent of any one user.
+  @@index([createdAt])
+  @@map("ai_usage_events")
+}

package/host/prisma/schema/platform.android-app.prisma

@@ -0,0 +1,46 @@
+// GENERATED by platform db compose — do not edit
+// source: package:android-app.prisma
+
+/// An Android APK this deployment hosts (#746, PP-9.4; merged from EvoPath and
+/// MemoriaHub). Uploaded by an administrator (the admin Android app page, or
+/// `appctl android publish`), streamed into object storage under the
+/// `android-releases/` key prefix, downloaded by signed-in users through a
+/// short-lived signed link (`/api/android-app/download/<token>`).
+///
+/// AT MOST ONE RELEASE IS CURRENT deployment-wide: the raw-SQL partial unique
+/// index `android_app_releases_one_current_uniq_idx` (migration SQL only;
+/// Prisma cannot express a partial unique index). Never declare it as
+/// @@unique and never replace it with a findFirst pre-check: make-current
+/// clears the old flag and sets the new one in one transaction, and the
+/// database rejects a second current row (P2002, mapped to 409
+/// RELEASE_CURRENT_CONFLICT).
+///
+/// `sizeBytes` is BigInt (MemoriaHub's choice; EvoPath used Int): the API
+/// returns it as a decimal string. `storageProvider` and `bucket` record where
+/// the bytes were written (the DatabaseBackupRun precedent), so a doctor check
+/// can tell a release stranded by a provider switch. A deployment artifact:
+/// kept by the user-data reset (uploader SetNull) and by the factory reset
+/// (its prefix is registered `survivesFactoryReset: true`).
+model AndroidAppRelease {
+  id              String   @id @default(uuid()) @db.Uuid
+  packageName     String   @map("package_name")
+  versionName     String   @map("version_name") @db.VarChar(50)
+  versionCode     Int      @map("version_code")
+  signingSha256   String   @map("signing_sha256")
+  fileSha256      String   @map("file_sha256") @db.Char(64)
+  sizeBytes       BigInt   @map("size_bytes")
+  storageKey      String   @map("storage_key")
+  storageProvider String?  @map("storage_provider")
+  bucket          String?
+  notes           String?  @db.VarChar(2000)
+  isCurrent       Boolean  @default(false) @map("is_current")
+  uploadedById    String?  @map("uploaded_by_id") @db.Uuid
+  createdAt       DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  uploadedBy User? @relation("AndroidAppReleaseUploader", fields: [uploadedById], references: [id], onDelete: SetNull)
+
+  @@unique([packageName, versionCode])
+  @@index([createdAt])
+  @@index([uploadedById])
+  @@map("android_app_releases")
+}

package/host/prisma/schema/platform.base.prisma

@@ -0,0 +1,15 @@
+// GENERATED by platform db compose — do not edit
+// source: package:base.prisma
+
+// =============================================================================
+// Prisma Schema - Web Application Foundation
+// =============================================================================
+
+generator client {
+  provider = "prisma-client-js"
+  output   = "../../generated"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/host/prisma/schema/platform.credentials.prisma

@@ -0,0 +1,156 @@
+// GENERATED by platform db compose — do not edit
+// source: package:credentials.prisma
+
+// =============================================================================
+// Encrypted Credential Store  (issue #115, epic #108)
+// =============================================================================
+//
+// Runtime-configured secrets (an SMTP password, an OAuth client secret, a
+// second bucket's S3 key, ...) addressed by (purpose, name) rather than one
+// column per consumer, so every future secret reuses this table instead of
+// inventing its own column, its own encrypt call, and its own chance to leak.
+//
+// `secret` holds ONLY the opaque base64 ciphertext produced by
+// `encryptSecret()` from `@marinoscar/platform-api/core`, encrypted under
+// `purpose` as the sub-key derivation label — a ciphertext lifted from one
+// row cannot be decrypted under a different purpose. This model stores
+// ciphertext and non-secret metadata only; it never sees plaintext, and
+// Prisma performs no encryption of its own.
+//
+// NEVER select `secret` into anything that reaches an API response or a log
+// line. `CredentialsService` is the sole reader/writer and is what actually
+// enforces that split (a plaintext-returning method for server-side
+// consumers, a metadata-only method for presentation) — this comment is the
+// signpost, not the guarantee.
+// @extensible — back-relations only, added with "extend model Credential { ... }" in a
+// fragment, so an app can hang its own NON-SECRET bookkeeping on a deployment credential
+// (which feature uses it, when it was last rotated). The `secret` column is never the
+// app's to read or relate to: an app reads plaintext only through `CredentialsService`,
+// and no app table may copy ciphertext or plaintext of it.
+model Credential {
+  id              String   @id @default(uuid()) @db.Uuid
+  purpose         String
+  name            String
+  // Opaque [iv][authTag][ciphertext] payload, base64-encoded by
+  // encryptSecret(). @db.Text (not the default `varchar`) because a base64
+  // AES-GCM payload has no meaningful bound: encrypted key material,
+  // passwords, or tokens of arbitrary length must never be truncated.
+  secret          String   @db.Text
+  // Non-secret display aid for the admin UI (e.g. last 4 chars, or a fixed
+  // mask like '••••'). Nullable: a credential can exist before anyone has
+  // decided how to hint it, and some secrets have no meaningful suffix to show.
+  hint            String?
+  // Human-readable description for the admin UI. Nullable for the same reason.
+  label           String?
+  updatedByUserId String?  @map("updated_by_user_id") @db.Uuid
+  createdAt       DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt       DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  //
+  // onDelete: SetNull — deliberately NOT Cascade. A credential is
+  // infrastructure shared by whatever consumer looks it up by (purpose,
+  // name); the admin who last set it is provenance, not an owner the
+  // credential's lifetime should depend on. Offboarding the user who last
+  // typed in the SMTP password must not silently delete a working SMTP
+  // configuration — that failure mode (email breaks because someone left
+  // the company) is exactly what this FK behaviour avoids. The credential
+  // outliving its last editor is correct; losing it is not.
+  updatedByUser User? @relation("CredentialUpdatedBy", fields: [updatedByUserId], references: [id], onDelete: SetNull)
+
+  @@unique([purpose, name])
+  @@map("credentials")
+}
+
+// =============================================================================
+// Per-User Encrypted Credentials  (issue #387)
+// =============================================================================
+//
+// The sibling of `Credential` above for secrets OWNED BY ONE USER — a user's
+// own key for some external service (bring-your-own-key). Addressed by
+// (userId, purpose, name); `credentials` is untouched and keeps its
+// ownerless (purpose, name) address.
+//
+// `secret` is the same opaque base64 [iv][authTag][ciphertext] payload
+// `encryptSecret()` produces, but encrypted under an OWNER-BOUND sub-key
+// domain, `user:<userId>:<purpose>` (`userCredentialPurpose()` in
+// `@marinoscar/platform-api/core`), not under `purpose` alone. A ciphertext
+// copied from user A's row into user B's row therefore fails GCM
+// authentication instead of handing B the use of A's key.
+//
+// All three unique columns are NOT NULL, so `@@unique` is a real Postgres
+// constraint (NULLs are distinct in a unique index) and `findUnique`/`upsert`
+// on `userId_purpose_name` work. Its leading column also serves every
+// by-user lookup, so there is no separate `user_id` index.
+//
+// onDelete: Cascade — deliberately the OPPOSITE of `Credential.updatedByUser`
+// (SetNull). There, the user is provenance for shared infrastructure; here,
+// the user is the owner, and a secret nobody owns is a secret nobody can
+// revoke. `UserCredentialsService` is the sole reader/writer; NEVER select
+// `secret` into anything that reaches an API response or a log line.
+model UserCredential {
+  id        String   @id @default(uuid()) @db.Uuid
+  userId    String   @map("user_id") @db.Uuid
+  purpose   String
+  name      String
+  // @db.Text for the same reason as `Credential.secret`: never truncate.
+  secret    String   @db.Text
+  // Non-secret display aid, derived from the plaintext on write.
+  hint      String?
+  // Human-readable description. User-entered, non-secret.
+  label     String?
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  user User @relation("UserCredentials", fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, purpose, name])
+  @@map("user_credentials")
+}
+
+// =============================================================================
+// Organization-Owned Encrypted Credentials  (issue #735, PP-8.8)
+// =============================================================================
+//
+// The third tier: secrets OWNED BY ONE ORGANIZATION (an org's own AI provider
+// key, an org's own storage or e-mail account), addressed by
+// (orgId, purpose, name). It mirrors `UserCredential` exactly, with the owner
+// an organization instead of a user.
+//
+// `secret` is the opaque [iv][authTag][ciphertext] payload `encryptSecret()`
+// produces under the ORG-BOUND sub-key domain `org:<orgId>:<purpose>`
+// (`orgCredentialPurpose()` in `@marinoscar/platform-api/core`): a ciphertext
+// copied from one organization's row into another's fails GCM
+// authentication.
+//
+// A plain composite unique suffices (no raw-SQL index): all three columns are
+// NOT NULL. Its leading column serves every by-org lookup.
+//
+// TENANT DATA: `org_credentials` is an `org` table under FORCEd row-level
+// security (`org_credentials_org_isolation`, as in 0025/0026), so every read
+// and write runs in the owning organization's scope. Cascade with the
+// organization; the last editor is provenance only (SetNull), as on
+// `Credential`. `OrgCredentialsService` is the sole reader/writer; NEVER
+// select `secret` into anything that reaches an API response or a log line.
+// =============================================================================
+model OrgCredential {
+  id              String   @id @default(uuid()) @db.Uuid
+  orgId           String   @map("org_id") @db.Uuid
+  purpose         String
+  name            String
+  // @db.Text for the same reason as `Credential.secret`: never truncate.
+  secret          String   @db.Text
+  // Non-secret display aid, derived from the plaintext on write.
+  hint            String?
+  // Human-readable description. Admin-entered, non-secret.
+  label           String?
+  updatedByUserId String?  @map("updated_by_user_id") @db.Uuid
+  createdAt       DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt       DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  org           Organization @relation(fields: [orgId], references: [id], onDelete: Cascade)
+  updatedByUser User?        @relation("OrgCredentialUpdatedBy", fields: [updatedByUserId], references: [id], onDelete: SetNull)
+
+  @@unique([orgId, purpose, name])
+  @@map("org_credentials")
+}