@marinoscar/platform-db 0.0.0-stage → 0.1.0-next.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/LICENSE +21 -0
  3. package/README.md +382 -2
  4. package/bin/platform.js +28 -0
  5. package/dist/baseline/deps.d.ts +32 -0
  6. package/dist/baseline/deps.d.ts.map +1 -0
  7. package/dist/baseline/deps.js +64 -0
  8. package/dist/baseline/deps.js.map +1 -0
  9. package/dist/baseline/errors.d.ts +34 -0
  10. package/dist/baseline/errors.d.ts.map +1 -0
  11. package/dist/baseline/errors.js +23 -0
  12. package/dist/baseline/errors.js.map +1 -0
  13. package/dist/baseline/fs.d.ts +9 -0
  14. package/dist/baseline/fs.d.ts.map +1 -0
  15. package/dist/baseline/fs.js +39 -0
  16. package/dist/baseline/fs.js.map +1 -0
  17. package/dist/baseline/index.d.ts +8 -0
  18. package/dist/baseline/index.d.ts.map +1 -0
  19. package/dist/baseline/index.js +24 -0
  20. package/dist/baseline/index.js.map +1 -0
  21. package/dist/baseline/mapping.d.ts +43 -0
  22. package/dist/baseline/mapping.d.ts.map +1 -0
  23. package/dist/baseline/mapping.js +80 -0
  24. package/dist/baseline/mapping.js.map +1 -0
  25. package/dist/baseline/normalise.d.ts +42 -0
  26. package/dist/baseline/normalise.d.ts.map +1 -0
  27. package/dist/baseline/normalise.js +133 -0
  28. package/dist/baseline/normalise.js.map +1 -0
  29. package/dist/baseline/plan.d.ts +66 -0
  30. package/dist/baseline/plan.d.ts.map +1 -0
  31. package/dist/baseline/plan.js +105 -0
  32. package/dist/baseline/plan.js.map +1 -0
  33. package/dist/baseline/report.d.ts +125 -0
  34. package/dist/baseline/report.d.ts.map +1 -0
  35. package/dist/baseline/report.js +85 -0
  36. package/dist/baseline/report.js.map +1 -0
  37. package/dist/baseline/run.d.ts +106 -0
  38. package/dist/baseline/run.d.ts.map +1 -0
  39. package/dist/baseline/run.js +339 -0
  40. package/dist/baseline/run.js.map +1 -0
  41. package/dist/bin/db-commands.d.ts +31 -0
  42. package/dist/bin/db-commands.d.ts.map +1 -0
  43. package/dist/bin/db-commands.js +276 -0
  44. package/dist/bin/db-commands.js.map +1 -0
  45. package/dist/bin/fs-io.d.ts +7 -0
  46. package/dist/bin/fs-io.d.ts.map +1 -0
  47. package/dist/bin/fs-io.js +45 -0
  48. package/dist/bin/fs-io.js.map +1 -0
  49. package/dist/bin/platform.d.ts +21 -0
  50. package/dist/bin/platform.d.ts.map +1 -0
  51. package/dist/bin/platform.js +99 -0
  52. package/dist/bin/platform.js.map +1 -0
  53. package/dist/compose/api.d.ts +84 -0
  54. package/dist/compose/api.d.ts.map +1 -0
  55. package/dist/compose/api.js +101 -0
  56. package/dist/compose/api.js.map +1 -0
  57. package/dist/compose/compose.d.ts +51 -0
  58. package/dist/compose/compose.d.ts.map +1 -0
  59. package/dist/compose/compose.js +177 -0
  60. package/dist/compose/compose.js.map +1 -0
  61. package/dist/compose/diff.d.ts +7 -0
  62. package/dist/compose/diff.d.ts.map +1 -0
  63. package/dist/compose/diff.js +68 -0
  64. package/dist/compose/diff.js.map +1 -0
  65. package/dist/compose/errors.d.ts +31 -0
  66. package/dist/compose/errors.d.ts.map +1 -0
  67. package/dist/compose/errors.js +35 -0
  68. package/dist/compose/errors.js.map +1 -0
  69. package/dist/compose/index.d.ts +3 -0
  70. package/dist/compose/index.d.ts.map +1 -0
  71. package/dist/compose/index.js +11 -0
  72. package/dist/compose/index.js.map +1 -0
  73. package/dist/compose/parse.d.ts +65 -0
  74. package/dist/compose/parse.d.ts.map +1 -0
  75. package/dist/compose/parse.js +122 -0
  76. package/dist/compose/parse.js.map +1 -0
  77. package/dist/drift/db-conformance.d.ts +49 -0
  78. package/dist/drift/db-conformance.d.ts.map +1 -0
  79. package/dist/drift/db-conformance.js +65 -0
  80. package/dist/drift/db-conformance.js.map +1 -0
  81. package/dist/drift/index.d.ts +5 -0
  82. package/dist/drift/index.d.ts.map +1 -0
  83. package/dist/drift/index.js +26 -0
  84. package/dist/drift/index.js.map +1 -0
  85. package/dist/drift/raw-sql-indexes.d.ts +106 -0
  86. package/dist/drift/raw-sql-indexes.d.ts.map +1 -0
  87. package/dist/drift/raw-sql-indexes.js +113 -0
  88. package/dist/drift/raw-sql-indexes.js.map +1 -0
  89. package/dist/drift/raw-sql-tripwire.d.ts +150 -0
  90. package/dist/drift/raw-sql-tripwire.d.ts.map +1 -0
  91. package/dist/drift/raw-sql-tripwire.js +394 -0
  92. package/dist/drift/raw-sql-tripwire.js.map +1 -0
  93. package/dist/drift/run.d.ts +128 -0
  94. package/dist/drift/run.d.ts.map +1 -0
  95. package/dist/drift/run.js +201 -0
  96. package/dist/drift/run.js.map +1 -0
  97. package/dist/index.d.ts +16 -0
  98. package/dist/index.d.ts.map +1 -0
  99. package/dist/index.js +33 -0
  100. package/dist/index.js.map +1 -0
  101. package/dist/lock/hash.d.ts +13 -0
  102. package/dist/lock/hash.d.ts.map +1 -0
  103. package/dist/lock/hash.js +19 -0
  104. package/dist/lock/hash.js.map +1 -0
  105. package/dist/lock/index.d.ts +5 -0
  106. package/dist/lock/index.d.ts.map +1 -0
  107. package/dist/lock/index.js +20 -0
  108. package/dist/lock/index.js.map +1 -0
  109. package/dist/lock/lock.d.ts +117 -0
  110. package/dist/lock/lock.d.ts.map +1 -0
  111. package/dist/lock/lock.js +140 -0
  112. package/dist/lock/lock.js.map +1 -0
  113. package/dist/lock/manifest.d.ts +60 -0
  114. package/dist/lock/manifest.d.ts.map +1 -0
  115. package/dist/lock/manifest.js +95 -0
  116. package/dist/lock/manifest.js.map +1 -0
  117. package/dist/lock/semver.d.ts +10 -0
  118. package/dist/lock/semver.d.ts.map +1 -0
  119. package/dist/lock/semver.js +13 -0
  120. package/dist/lock/semver.js.map +1 -0
  121. package/dist/seed/index.d.ts +4 -0
  122. package/dist/seed/index.d.ts.map +1 -0
  123. package/dist/seed/index.js +10 -0
  124. package/dist/seed/index.js.map +1 -0
  125. package/dist/seed/input.d.ts +52 -0
  126. package/dist/seed/input.d.ts.map +1 -0
  127. package/dist/seed/input.js +77 -0
  128. package/dist/seed/input.js.map +1 -0
  129. package/dist/seed/seed-platform.d.ts +28 -0
  130. package/dist/seed/seed-platform.d.ts.map +1 -0
  131. package/dist/seed/seed-platform.js +133 -0
  132. package/dist/seed/seed-platform.js.map +1 -0
  133. package/dist/seed/types.d.ts +277 -0
  134. package/dist/seed/types.d.ts.map +1 -0
  135. package/dist/seed/types.js +5 -0
  136. package/dist/seed/types.js.map +1 -0
  137. package/dist/sync/apply.d.ts +29 -0
  138. package/dist/sync/apply.d.ts.map +1 -0
  139. package/dist/sync/apply.js +37 -0
  140. package/dist/sync/apply.js.map +1 -0
  141. package/dist/sync/check.d.ts +56 -0
  142. package/dist/sync/check.d.ts.map +1 -0
  143. package/dist/sync/check.js +108 -0
  144. package/dist/sync/check.js.map +1 -0
  145. package/dist/sync/errors.d.ts +31 -0
  146. package/dist/sync/errors.d.ts.map +1 -0
  147. package/dist/sync/errors.js +23 -0
  148. package/dist/sync/errors.js.map +1 -0
  149. package/dist/sync/index.d.ts +9 -0
  150. package/dist/sync/index.d.ts.map +1 -0
  151. package/dist/sync/index.js +25 -0
  152. package/dist/sync/index.js.map +1 -0
  153. package/dist/sync/ledger.d.ts +65 -0
  154. package/dist/sync/ledger.d.ts.map +1 -0
  155. package/dist/sync/ledger.js +49 -0
  156. package/dist/sync/ledger.js.map +1 -0
  157. package/dist/sync/plan.d.ts +61 -0
  158. package/dist/sync/plan.d.ts.map +1 -0
  159. package/dist/sync/plan.js +79 -0
  160. package/dist/sync/plan.js.map +1 -0
  161. package/dist/sync/promote.d.ts +58 -0
  162. package/dist/sync/promote.d.ts.map +1 -0
  163. package/dist/sync/promote.js +93 -0
  164. package/dist/sync/promote.js.map +1 -0
  165. package/dist/sync/timestamps.d.ts +41 -0
  166. package/dist/sync/timestamps.d.ts.map +1 -0
  167. package/dist/sync/timestamps.js +68 -0
  168. package/dist/sync/timestamps.js.map +1 -0
  169. package/dist/sync/version.d.ts +28 -0
  170. package/dist/sync/version.d.ts.map +1 -0
  171. package/dist/sync/version.js +66 -0
  172. package/dist/sync/version.js.map +1 -0
  173. package/migrations/0001_initial/migration.sql +297 -0
  174. package/migrations/0002_add_personal_access_tokens/migration.sql +31 -0
  175. package/migrations/0003_add_credentials/migration.sql +20 -0
  176. package/migrations/0004_add_notification_deliveries/migration.sql +27 -0
  177. package/migrations/0005_drop_stale_uuid_defaults/migration.sql +35 -0
  178. package/migrations/0006_add_notifications/migration.sql +22 -0
  179. package/migrations/0007_add_push_subscriptions/migration.sql +25 -0
  180. package/migrations/0008_add_jobs/migration.sql +110 -0
  181. package/migrations/0009_add_worker_nodes/migration.sql +90 -0
  182. package/migrations/0010_add_database_backup_runs/migration.sql +104 -0
  183. package/migrations/0011_add_notification_broadcasts/migration.sql +57 -0
  184. package/migrations/0012_add_backup_run_job_link/migration.sql +87 -0
  185. package/migrations/0013_add_job_node_secrets/migration.sql +61 -0
  186. package/migrations/0014_add_backup_run_pg_dump_version/migration.sql +26 -0
  187. package/migrations/0015_add_job_claim_token/migration.sql +92 -0
  188. package/migrations/0016_add_ai_platform/migration.sql +108 -0
  189. package/migrations/0017_revoke_viewer_ai_use/migration.sql +32 -0
  190. package/migrations/0018_add_user_credentials/migration.sql +29 -0
  191. package/migrations/0019_add_device_session_credential_link/migration.sql +52 -0
  192. package/migrations/0020_add_worker_node_vitals/migration.sql +3 -0
  193. package/migrations/0021_add_job_trace_context/migration.sql +6 -0
  194. package/migrations/0022_add_retention_created_at_indexes/migration.sql +13 -0
  195. package/migrations/0023_add_organizations/migration.sql +142 -0
  196. package/migrations/0024_split_system_org_roles/migration.sql +131 -0
  197. package/migrations/manifest.json +240 -0
  198. package/package.json +75 -4
  199. package/raw-sql-indexes.json +49 -0
  200. package/schema/ai.prisma +387 -0
  201. package/schema/base.prisma +11 -0
  202. package/schema/credentials.prisma +108 -0
  203. package/schema/db-backup.prisma +376 -0
  204. package/schema/identity.prisma +407 -0
  205. package/schema/jobs.prisma +731 -0
  206. package/schema/notifications.prisma +610 -0
  207. package/schema/settings.prisma +35 -0
  208. package/schema/storage.prisma +57 -0
@@ -0,0 +1,387 @@
1
+ // =============================================================================
2
+ // AI Platform (issue #423, epic #419, umbrella #418)
3
+ // =============================================================================
4
+ //
5
+ // Four tables — the model catalog, per-user encrypted provider keys,
6
+ // background AI run results, and usage accounting — for the whole platform
7
+ // this epic builds. THIS ISSUE OWNS SCHEMA ONLY: no service or controller in
8
+ // this build reads or writes any of these tables yet (that is #427, #428,
9
+ // #431, #432). They land ahead of their consumers, on the same "declare the
10
+ // collision hotspot once, let every other AI story run in parallel" logic
11
+ // `system-settings.service.ts`'s operations-namespaces header already argues
12
+ // for `system_settings`: `schema.prisma`, `seed-data.ts`,
13
+ // `roles.constants.ts` and `settings.schema.ts` are each touched by every
14
+ // story in the epic, so this one story claims them in a single migration
15
+ // instead of every later story racing to edit the same four files.
16
+ //
17
+ // -----------------------------------------------------------------------------
18
+ // ⚠ NO COLUMN HERE CAN EVER HOLD A PLAINTEXT PROVIDER KEY
19
+ // -----------------------------------------------------------------------------
20
+ // `UserAiKey.secret` is ciphertext ONLY — the output of `encryptSecret(
21
+ // plaintext, 'ai_user_key')` (`@marinoscar/platform-api/core`), the same
22
+ // AES-GCM helper `Credential.secret` already uses, keyed under a purpose
23
+ // label specific to this table so a ciphertext lifted from one row cannot be
24
+ // decrypted as if it were the other's. `hint` is the non-secret display aid
25
+ // (`'••••' + last 4`, mirroring `Credential.hint`), never enough on its own
26
+ // to reconstruct the key. `AiRun.request` is explicitly a NORMALIZED request
27
+ // — model id, parameters, truncated/redacted prompt shape — never the
28
+ // caller's raw provider key, which the run's own executor already holds
29
+ // separately (from `UserAiKey`, decrypted for that one call and discarded).
30
+ //
31
+ // -----------------------------------------------------------------------------
32
+ // `UserAiKey` — Cascade, NOT SetNull, and the contrast with `Credential` is
33
+ // deliberate
34
+ // -----------------------------------------------------------------------------
35
+ // `Credential.updatedByUser` is `SetNull`: that table is shared
36
+ // infrastructure (an SMTP password, a storage secret) that outlives whoever
37
+ // last edited it, because the credential belongs to the DEPLOYMENT, not to
38
+ // the editor. `UserAiKey.user` is the opposite shape on purpose — a BYOK key
39
+ // belongs to the ONE ACCOUNT that typed it in, has no meaning to anyone else,
40
+ // and (like `PushSubscription.user`, which makes the identical argument for a
41
+ // live per-device credential) has no reader once that account is gone. There
42
+ // is no "the deployment's OpenAI key" here, only "this user's OpenAI key", so
43
+ // deleting the user is what should delete it.
44
+ //
45
+ // -----------------------------------------------------------------------------
46
+ // `AiRun.user` / `AiUsageEvent.user` — SetNull, matching `NotificationDelivery
47
+ // .user`
48
+ // -----------------------------------------------------------------------------
49
+ // Both are HISTORY, not live state: a run's output and a usage event's token
50
+ // counts remain meaningful — for billing reconciliation, for "was this
51
+ // account affected by the incident on provider X" — after the account that
52
+ // triggered them is gone, exactly the argument `NotificationDelivery.user`'s
53
+ // own block comment makes for a delivery attempt. Nulling the FK preserves
54
+ // that record; cascading it would erase usage accounting as a side effect of
55
+ // an unrelated account-deletion path elsewhere in the app. Both are also
56
+ // deliberately nullable up front (not merely nullable-after-cascade), the same
57
+ // "global job" shape `Job.subjectType`/`subjectId` use: a background run or a
58
+ // catalog-discovery usage event may have no requesting user at all.
59
+ //
60
+ // -----------------------------------------------------------------------------
61
+ // `capabilities` / `units` — JSONB, not typed columns, and Zod-validated in
62
+ // code
63
+ // -----------------------------------------------------------------------------
64
+ // `AiModel.capabilities` (what a model can do — text, vision, tool calling,
65
+ // structured output, ...) and `AiUsageEvent.units` (a per-operation unit
66
+ // count that varies by kind: `{ images: 2 }`, `{ audioSeconds: 31.4 }`) are
67
+ // each shaped differently per provider and per operation, and neither is
68
+ // filtered or indexed on by any query this issue's schema needs to support.
69
+ // Both follow `Job.payload`'s and `WorkerNode.capabilities`' own precedent:
70
+ // opaque JSONB here, a real Zod schema (`AiModelCapabilities`) at the
71
+ // consuming layer that arrives with #427/#428. A typed column per capability
72
+ // would be a migration every time a provider ships a new one.
73
+ //
74
+ // -----------------------------------------------------------------------------
75
+ // `provider` / `operation` / `status` / `keySource` — plain strings, not
76
+ // Prisma enums
77
+ // -----------------------------------------------------------------------------
78
+ // Same reasoning as `Job.type`, `NotificationDelivery.channel` and
79
+ // `WorkerNode.executor` throughout this file: these are small, code-owned,
80
+ // GROWING sets (`AI_PROVIDER_IDS` names `'openai'` today and Phase 3 appends
81
+ // to it; new operations and key sources are exactly the shape of change a
82
+ // provider integration adds), so a Postgres enum would reintroduce the
83
+ // migration this design otherwise avoids, and a row must be able to outlive
84
+ // whatever build produced it. `AiRun.status` and `AiUsageEvent.status` are
85
+ // each that model's OWN closed state machine in every other sense — but they
86
+ // are kept as strings rather than promoted to a Prisma enum for the same
87
+ // forward-compatibility reason the rest of this section gives, not because
88
+ // they are open-ended in practice.
89
+ //
90
+ // -----------------------------------------------------------------------------
91
+ // `AiModel.capabilitySource` — `'catalog' | 'admin_override' | 'unclassified'`
92
+ // -----------------------------------------------------------------------------
93
+ // Records WHERE `capabilities` came from, because the three sources disagree
94
+ // in trustworthiness and in how long they last: `'catalog'` is the
95
+ // provider's own advertised capability list (refreshed on discovery, and the
96
+ // first thing a later sync overwrites), `'admin_override'` is a deployment
97
+ // operator's manual correction (must survive a catalog refresh that would
98
+ // otherwise clobber it — that survival rule belongs to #427's sync logic, not
99
+ // to this column), and `'unclassified'` is the default for a model this
100
+ // deployment has seen but never classified at all. A model discovered before
101
+ // any classification runs is `'unclassified'`, never a guess.
102
+ model AiModel {
103
+ id String @id @default(uuid()) @db.Uuid
104
+
105
+ // The provider registration this model belongs to, e.g. `'openai'`. See
106
+ // `AI_PROVIDER_IDS` (`common/schemas/settings.schema.ts`) — a growing,
107
+ // code-owned list, and a plain string here for the reason given above.
108
+ provider String
109
+
110
+ // The provider's own raw model identifier (e.g. `'gpt-4o-mini'`), as
111
+ // opposed to `id` above, which is this table's own row identity.
112
+ modelId String @map("model_id")
113
+
114
+ // Operator/UI-facing label. Nullable: a freshly discovered model has none
115
+ // until an admin (or a later sync) names it.
116
+ displayName String? @map("display_name")
117
+
118
+ // AiModelCapabilities, Zod-validated at the consuming layer (#427) — see
119
+ // the block comment above for why this is JSONB rather than typed columns.
120
+ capabilities Json
121
+
122
+ // Where `capabilities` came from — see the block comment above.
123
+ // `'unclassified'` is the default: a model this deployment has observed but
124
+ // not yet classified, one way or the other.
125
+ capabilitySource String @default("unclassified") @map("capability_source")
126
+
127
+ // Whether this deployment offers the model to callers at all. Defaults to
128
+ // `false`: a freshly discovered model is inert until an administrator (or a
129
+ // later sync's own policy) turns it on, the same "nothing changes behaviour
130
+ // on discovery alone" posture `WorkerNode.status` defaulting to `offline`
131
+ // and `databaseBackup.enabled` defaulting to `false` both take elsewhere in
132
+ // this schema.
133
+ enabled Boolean @default(false)
134
+
135
+ contextWindow Int? @map("context_window")
136
+ maxOutputTokens Int? @map("max_output_tokens")
137
+
138
+ // When this row was first created, vs. `lastSeenAt` below, which moves on
139
+ // every discovery sync that still finds the model — the same "creation time
140
+ // vs. liveness" split `WorkerNode.registeredAt`/`.lastHeartbeatAt` make for
141
+ // an entirely different kind of inventory.
142
+ discoveredAt DateTime @default(now()) @map("discovered_at") @db.Timestamptz
143
+ lastSeenAt DateTime @default(now()) @map("last_seen_at") @db.Timestamptz
144
+ // Set by a discovery sync (#427) that no longer sees this model in the
145
+ // provider's own catalog. Nullable: most rows are never deprecated.
146
+ // Deliberately not deleted — a deprecated model may still be referenced by
147
+ // historical `AiRun`/`AiUsageEvent` rows via its `provider`/`modelId` pair,
148
+ // and losing the row would lose the display name and capability record for
149
+ // that history.
150
+ deprecatedAt DateTime? @map("deprecated_at") @db.Timestamptz
151
+
152
+ // Provenance of the last edit — see the block comment above for why this
153
+ // is `SetNull`, matching `Credential.updatedByUser` rather than
154
+ // `UserAiKey.user` below.
155
+ updatedByUserId String? @map("updated_by_user_id") @db.Uuid
156
+ updatedByUser User? @relation("AiModelUpdatedBy", fields: [updatedByUserId], references: [id], onDelete: SetNull)
157
+ updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
158
+
159
+ // One row per (provider, model) pair, ever — a discovery sync upserts on
160
+ // this rather than inserting duplicates on every re-run.
161
+ @@unique([provider, modelId])
162
+ // "Which models may this deployment currently offer" — the catalog read
163
+ // every AI-calling path needs, filtered to the provider in play.
164
+ @@index([provider, enabled])
165
+ @@map("ai_models")
166
+ }
167
+
168
+ // BYOK ("bring your own key"): one encrypted provider key per (user,
169
+ // provider), never per deployment. See the block comment above this section
170
+ // for why `user` is `Cascade` here and NOT `SetNull` like `Credential
171
+ // .updatedByUser` or `AiModel.updatedByUser` above — this key has exactly one
172
+ // owner and no meaning to anyone else once that owner's account is gone.
173
+ model UserAiKey {
174
+ id String @id @default(uuid()) @db.Uuid
175
+ userId String @map("user_id") @db.Uuid
176
+
177
+ // Which provider this key authenticates against, e.g. `'openai'`. Plain
178
+ // string for the same forward-compatibility reason `AiModel.provider` is.
179
+ provider String
180
+
181
+ // Ciphertext ONLY — `encryptSecret(plaintext, 'ai_user_key')`. See the
182
+ // block comment above this section (and `Credential.secret`'s own comment)
183
+ // for the full argument; @db.Text for the identical reason
184
+ // `Credential.secret` is: an AES-GCM payload has no meaningful length
185
+ // bound, so it must never be truncated.
186
+ secret String @db.Text
187
+
188
+ // Non-secret display aid (`'••••' + last 4`), mirroring `Credential.hint`.
189
+ // Nullable: a key can exist before anyone has decided how to hint it.
190
+ hint String?
191
+
192
+ // The last time this key was proven to work against its provider (a live
193
+ // probe call, not merely "was saved"). Nullable: never verified yet.
194
+ verifiedAt DateTime? @map("verified_at") @db.Timestamptz
195
+ // The provider's own error code from the most recent failed verification or
196
+ // use, so a user who cannot see why a key stopped working has somewhere to
197
+ // look. Nullable: no failure recorded (yet, or ever).
198
+ lastErrorCode String? @map("last_error_code")
199
+
200
+ // Which of this provider's models this specific key was actually able to
201
+ // reach on its last verification, as opposed to `AiModel.enabled`, which is
202
+ // a DEPLOYMENT-WIDE policy decision independent of any one key. A key with
203
+ // a narrower API scope, or one hitting a provider-side allowlist, can
204
+ // legitimately reach fewer models than the deployment otherwise offers.
205
+ reachableModelIds String[] @default([]) @map("reachable_model_ids")
206
+ reachableCheckedAt DateTime? @map("reachable_checked_at") @db.Timestamptz
207
+
208
+ createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
209
+ updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
210
+
211
+ // Relations
212
+ //
213
+ // Cascade — see the block comment above this section for why this
214
+ // deliberately reverses `Credential.updatedByUser`'s `SetNull`.
215
+ user User @relation(fields: [userId], references: [id], onDelete: Cascade)
216
+
217
+ // One key per (user, provider) — saving a new key for a provider replaces
218
+ // the old one rather than accumulating a history of them.
219
+ @@unique([userId, provider])
220
+ @@map("user_ai_keys")
221
+ }
222
+
223
+ // One row per AI call this platform ever ran through the background queue —
224
+ // the record `#432`'s job handler(s) read from and write progress/output to.
225
+ // This issue is schema only, matching every other table in this section: no
226
+ // enqueue path, no job handler and no controller exists yet.
227
+ model AiRun {
228
+ id String @id @default(uuid()) @db.Uuid
229
+
230
+ // Nullable, deliberately — see the block comment above this section for why
231
+ // this is `SetNull` rather than `Cascade`, and why a run may have no
232
+ // requesting user at all (a system-initiated run, mirroring `Job.subjectType`
233
+ // /`subjectId` both being null together for a global job).
234
+ userId String? @map("user_id") @db.Uuid
235
+
236
+ // The `jobs` row this run executes under, when it runs through the queue at
237
+ // all. Nullable, and deliberately NOT a foreign key — mirrors
238
+ // `DatabaseBackupRun`'s OWN relation to `Job` in spirit (a dedicated table
239
+ // outliving the generic queue's retention) but stays a plain column rather
240
+ // than a `@relation`+`@unique` pair: unlike a backup run, an `AiRun` is not
241
+ // one-to-one with its job in every future shape this platform may take
242
+ // (a retried run may reuse the id, or a future synchronous path may have no
243
+ // job at all), so this issue commits only to recording the id, not to the
244
+ // stronger one-to-one relation `DatabaseBackupRun.jobId` commits to.
245
+ jobId String? @map("job_id") @db.Uuid
246
+
247
+ // pending|running|succeeded|failed|cancelled — this run's own state
248
+ // machine, kept as a plain string rather than a Prisma enum for the
249
+ // forward-compatibility reason given in the block comment above this
250
+ // section.
251
+ status String @default("pending")
252
+
253
+ provider String
254
+ modelId String @map("model_id")
255
+
256
+ // The NORMALIZED request — model id, parameters, and the FULL prompt shape
257
+ // (instructions, input, tools, structured-output schema) `toStoredRunRequest`
258
+ // (`runtime/ai-run-request.ts`) built from it — and NEVER the caller's key
259
+ // material, which this run's executor holds separately and only for the
260
+ // duration of the call. Deliberately not redacted or truncated: the
261
+ // worker that claims this job re-issues the user's exact request, and a
262
+ // truncated prompt would make the replayed call diverge from the one the
263
+ // user actually asked for. See the ⚠ block comment above this section.
264
+ request Json
265
+
266
+ output Json?
267
+ errorCode String? @map("error_code")
268
+ errorMessage String? @map("error_message")
269
+
270
+ createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
271
+ updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
272
+ completedAt DateTime? @map("completed_at") @db.Timestamptz
273
+
274
+ // Relations
275
+ //
276
+ // SetNull — see the block comment above this section.
277
+ user User? @relation(fields: [userId], references: [id], onDelete: SetNull)
278
+
279
+ // "This user's run history, most recent first" — the one query this table
280
+ // is known to need today (a user's own run list).
281
+ @@index([userId, createdAt])
282
+ // The retention sweep (`ai.runs.purge`, #681): "oldest first, older than
283
+ // the cutoff" across every user, which `[userId, createdAt]` cannot serve.
284
+ @@index([createdAt])
285
+ @@map("ai_runs")
286
+ }
287
+
288
+ // One row per AI operation attempted, successful or not — the usage/billing
289
+ // accounting ledger, deliberately separate from `AiRun` above. `AiRun` is
290
+ // "what did this background call do" (one row per queued call, with its own
291
+ // request/output); `AiUsageEvent` is "what did this cost", covering every
292
+ // operation kind (`responses|images|audio.transcribe|audio.speech|
293
+ // embeddings|catalog`) whether or not it went through the queue at all — a
294
+ // synchronous catalog-listing call has no `AiRun` but still consumes a
295
+ // provider call worth recording.
296
+ model AiUsageEvent {
297
+ id String @id @default(uuid()) @db.Uuid
298
+
299
+ // Nullable, `SetNull` — see the block comment above this section. A
300
+ // catalog-discovery sync run by the deployment itself, not by any one
301
+ // user, is the concrete case that leaves this null.
302
+ userId String? @map("user_id") @db.Uuid
303
+
304
+ provider String
305
+ modelId String @map("model_id")
306
+
307
+ // responses|images|audio.transcribe|audio.speech|embeddings|catalog — the
308
+ // kind of provider call this event records. Plain string for the
309
+ // forward-compatibility reason given above: a new operation kind (a future
310
+ // provider capability) must cost zero migrations here.
311
+ operation String
312
+
313
+ // user|org|admin_discovery — WHOSE key paid for this call. Distinct from
314
+ // `provider`/`modelId` (which model answered) and from `userId` (who asked):
315
+ // an admin-triggered catalog discovery sync can be `keySource:
316
+ // 'admin_discovery'` with no requesting `userId` at all, and a BYOK-only
317
+ // deployment's every real usage event is `keySource: 'user'`. `'org'` is
318
+ // reserved for a future org-wide fallback key, matching `AI_KEY_POLICIES`'
319
+ // `'byok_with_org_fallback'` in `common/schemas/settings.schema.ts`.
320
+ keySource String @map("key_source")
321
+
322
+ // Token accounting. All nullable: an `images`/`audio.*` operation has no
323
+ // token counts at all, and `reasoningTokens`/`cachedInputTokens` are
324
+ // provider-specific breakdowns that not every provider or model reports.
325
+ inputTokens Int? @map("input_tokens")
326
+ outputTokens Int? @map("output_tokens")
327
+ reasoningTokens Int? @map("reasoning_tokens")
328
+ cachedInputTokens Int? @map("cached_input_tokens")
329
+
330
+ // Non-token unit accounting for operations tokens don't measure — e.g.
331
+ // `{ images: 2 }` for an image generation call, `{ audioSeconds: 31.4 }` for
332
+ // transcription/speech. JSONB for the reason given in the block comment
333
+ // above this section: the shape varies by `operation` and no query here
334
+ // filters or indexes on it.
335
+ units Json?
336
+
337
+ latencyMs Int @map("latency_ms")
338
+
339
+ // succeeded|failed|cancelled — this event's own closed outcome, kept as a
340
+ // plain string for the identical forward-compatibility reason `AiRun
341
+ // .status` is.
342
+ status String
343
+ errorCode String? @map("error_code")
344
+
345
+ // The provider's own request/trace id, for reconciling a usage row against
346
+ // that provider's dashboard or support ticket. Nullable: not every provider
347
+ // call surfaces one.
348
+ providerRequestId String? @map("provider_request_id")
349
+
350
+ // The `jobs` row this usage event was incurred under, when it was. Plain
351
+ // column, no relation — same reasoning as `AiRun.jobId` above.
352
+ jobId String? @map("job_id") @db.Uuid
353
+
354
+ createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
355
+
356
+ // Relations
357
+ user User? @relation(fields: [userId], references: [id], onDelete: SetNull)
358
+
359
+ // "This user's usage history, most recent first" — mirrors `AiRun`'s own
360
+ // index for the identical reason.
361
+ @@index([userId, createdAt])
362
+ // "Usage across all users in a time window" — the deployment-wide
363
+ // accounting/billing query, independent of any one user.
364
+ @@index([createdAt])
365
+ @@map("ai_usage_events")
366
+ }
367
+
368
+ extend model User {
369
+ // AI platform (#423, epic #419). Four relations, four different
370
+ // `onDelete` answers — see each model's own block comment for why:
371
+ // - `aiModelsUpdated` (`AiModel.updatedByUser`) is provenance on a
372
+ // CATALOG row nobody owns, so `SetNull`, matching `Credential
373
+ // .updatedByUser` above.
374
+ // - `aiKeys` (`UserAiKey.user`) is `Cascade`: a BYOK key belongs to the
375
+ // user who typed it in, in exactly the sense `PushSubscription.user`
376
+ // does — there is no reader for it once the account is gone.
377
+ // - `aiRuns` (`AiRun.user`) is `SetNull`: a run is history, kept for
378
+ // usage/audit purposes independent of whether its requester's account
379
+ // still exists, matching `NotificationDelivery.user`.
380
+ // - `aiUsageEvents` (`AiUsageEvent.user`) is `SetNull` for the identical
381
+ // reason `aiRuns` is: usage accounting must outlive the account it
382
+ // billed.
383
+ aiModelsUpdated AiModel[] @relation("AiModelUpdatedBy")
384
+ aiKeys UserAiKey[]
385
+ aiRuns AiRun[]
386
+ aiUsageEvents AiUsageEvent[]
387
+ }
@@ -0,0 +1,11 @@
1
+ // =============================================================================
2
+ // Prisma Schema - Web Application Foundation
3
+ // =============================================================================
4
+
5
+ generator client {
6
+ provider = "prisma-client-js"
7
+ }
8
+
9
+ datasource db {
10
+ provider = "postgresql"
11
+ }
@@ -0,0 +1,108 @@
1
+ // =============================================================================
2
+ // Encrypted Credential Store (issue #115, epic #108)
3
+ // =============================================================================
4
+ //
5
+ // Runtime-configured secrets (an SMTP password, an OAuth client secret, a
6
+ // second bucket's S3 key, ...) addressed by (purpose, name) rather than one
7
+ // column per consumer, so every future secret reuses this table instead of
8
+ // inventing its own column, its own encrypt call, and its own chance to leak.
9
+ //
10
+ // `secret` holds ONLY the opaque base64 ciphertext produced by
11
+ // `encryptSecret()` from `@marinoscar/platform-api/core`, encrypted under
12
+ // `purpose` as the sub-key derivation label — a ciphertext lifted from one
13
+ // row cannot be decrypted under a different purpose. This model stores
14
+ // ciphertext and non-secret metadata only; it never sees plaintext, and
15
+ // Prisma performs no encryption of its own.
16
+ //
17
+ // NEVER select `secret` into anything that reaches an API response or a log
18
+ // line. `CredentialsService` is the sole reader/writer and is what actually
19
+ // enforces that split (a plaintext-returning method for server-side
20
+ // consumers, a metadata-only method for presentation) — this comment is the
21
+ // signpost, not the guarantee.
22
+ model Credential {
23
+ id String @id @default(uuid()) @db.Uuid
24
+ purpose String
25
+ name String
26
+ // Opaque [iv][authTag][ciphertext] payload, base64-encoded by
27
+ // encryptSecret(). @db.Text (not the default `varchar`) because a base64
28
+ // AES-GCM payload has no meaningful bound: encrypted key material,
29
+ // passwords, or tokens of arbitrary length must never be truncated.
30
+ secret String @db.Text
31
+ // Non-secret display aid for the admin UI (e.g. last 4 chars, or a fixed
32
+ // mask like '••••'). Nullable: a credential can exist before anyone has
33
+ // decided how to hint it, and some secrets have no meaningful suffix to show.
34
+ hint String?
35
+ // Human-readable description for the admin UI. Nullable for the same reason.
36
+ label String?
37
+ updatedByUserId String? @map("updated_by_user_id") @db.Uuid
38
+ createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
39
+ updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
40
+
41
+ // Relations
42
+ //
43
+ // onDelete: SetNull — deliberately NOT Cascade. A credential is
44
+ // infrastructure shared by whatever consumer looks it up by (purpose,
45
+ // name); the admin who last set it is provenance, not an owner the
46
+ // credential's lifetime should depend on. Offboarding the user who last
47
+ // typed in the SMTP password must not silently delete a working SMTP
48
+ // configuration — that failure mode (email breaks because someone left
49
+ // the company) is exactly what this FK behaviour avoids. The credential
50
+ // outliving its last editor is correct; losing it is not.
51
+ updatedByUser User? @relation("CredentialUpdatedBy", fields: [updatedByUserId], references: [id], onDelete: SetNull)
52
+
53
+ @@unique([purpose, name])
54
+ @@map("credentials")
55
+ }
56
+
57
+ // =============================================================================
58
+ // Per-User Encrypted Credentials (issue #387)
59
+ // =============================================================================
60
+ //
61
+ // The sibling of `Credential` above for secrets OWNED BY ONE USER — a user's
62
+ // own key for some external service (bring-your-own-key). Addressed by
63
+ // (userId, purpose, name); `credentials` is untouched and keeps its
64
+ // ownerless (purpose, name) address.
65
+ //
66
+ // `secret` is the same opaque base64 [iv][authTag][ciphertext] payload
67
+ // `encryptSecret()` produces, but encrypted under an OWNER-BOUND sub-key
68
+ // domain, `user:<userId>:<purpose>` (`userCredentialPurpose()` in
69
+ // `@marinoscar/platform-api/core`), not under `purpose` alone. A ciphertext
70
+ // copied from user A's row into user B's row therefore fails GCM
71
+ // authentication instead of handing B the use of A's key.
72
+ //
73
+ // All three unique columns are NOT NULL, so `@@unique` is a real Postgres
74
+ // constraint (NULLs are distinct in a unique index) and `findUnique`/`upsert`
75
+ // on `userId_purpose_name` work. Its leading column also serves every
76
+ // by-user lookup, so there is no separate `user_id` index.
77
+ //
78
+ // onDelete: Cascade — deliberately the OPPOSITE of `Credential.updatedByUser`
79
+ // (SetNull). There, the user is provenance for shared infrastructure; here,
80
+ // the user is the owner, and a secret nobody owns is a secret nobody can
81
+ // revoke. `UserCredentialsService` is the sole reader/writer; NEVER select
82
+ // `secret` into anything that reaches an API response or a log line.
83
+ model UserCredential {
84
+ id String @id @default(uuid()) @db.Uuid
85
+ userId String @map("user_id") @db.Uuid
86
+ purpose String
87
+ name String
88
+ // @db.Text for the same reason as `Credential.secret`: never truncate.
89
+ secret String @db.Text
90
+ // Non-secret display aid, derived from the plaintext on write.
91
+ hint String?
92
+ // Human-readable description. User-entered, non-secret.
93
+ label String?
94
+ createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
95
+ updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
96
+
97
+ user User @relation("UserCredentials", fields: [userId], references: [id], onDelete: Cascade)
98
+
99
+ @@unique([userId, purpose, name])
100
+ @@map("user_credentials")
101
+ }
102
+
103
+ extend model User {
104
+ credentialUpdates Credential[] @relation("CredentialUpdatedBy")
105
+ // Per-user encrypted credentials (issue #387). Cascade: a user-owned
106
+ // secret has no meaning once its owner is gone — see `UserCredential`.
107
+ userCredentials UserCredential[] @relation("UserCredentials")
108
+ }