attach dev console at bottom, pin to network tab

get rid of nag dialogue (thanks, Google) + add comments
temporary disable video models (omni / website gens only - app unaffected) (#1369 )
2026-10-21 09:22:41 -04:00 · 2026-04-15 01:40:15 -04:00 · 2026-04-15 01:27:54 -04:00 · 2026-04-14 11:53:11 -04:00 · 2026-04-14 11:49:12 -04:00 · 2026-04-14 11:47:16 -04:00
199 changed files with 10416 additions and 1929 deletions
@@ -6,7 +6,11 @@
 - No minimum supported Rust version; use latest stable features freely
 - `#[macro_use] extern crate serde_derive;` is used in binary crates; library crates use `use serde_derive::{Serialize, Deserialize};`
 - Never use `println!` or `eprintln!` outside of tests; use `log` crate macros (`info!`, `warn!`, `error!`, `debug!`, `trace!`) instead
- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code
+- Use `anyhow::Result` / `AnyhowResult` for fallible functions in application code; new database queries should use `Result<T, sqlx::Error>` instead
+- SQLx queries: prefer `sqlx::query!` and `sqlx::query_as!` compile-time checked macros over 
+  runtime `sqlx::query()` / `sqlx::query_as()`. The macros catch SQL typos, column mismatches, 
+  and type errors at build time. Use runtime queries only when assembling complicated 
+  dynamic/branching queries that cannot be expressed as a compile-time macro.
 - Enum Display/Debug: use `impl_enum_display_and_debug_using_to_str!` macro, not `derive_more::Display` (CLion doesn't understand it)
 - Fields that are optional use the `maybe_` prefix: `maybe_creator_user_token`, `maybe_prompt_token`
 - When implementing `fmt::Display` for error types, use the pattern: `write!(f, "{:?}", self)`
@@ -56,8 +60,14 @@ then the story, then the fine print.
  `use artcraft_router::...::CommonResolution as CommonResolutionRouter;`
  This avoids long fully-qualified paths in function signatures and bodies.

+## MySQL 
+
+- MySQL tables: primary key `id` columns must be `BIGINT(20) UNSIGNED`. Do not use signed IDs. 
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+
 ## TypeScript / Frontend

 - TypeScript with React, Vite, Zustand, Three.js
 - Nx monorepo under `crates/frontend/`
 - Two spaces for indentation
+
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.impersonated_user_token = ?\n  AND uir.id < ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "27cebaa36f0ec873f86cdf8fa994d499db1a5cc84d2c6fceb3587145eb2f9bec"
+}
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.impersonated_user_token = ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "381e13ab37a2f4ce39bd6db9d90202c301091376108f645a9bb5264a9cd113d7"
+}
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  sal.id,\n  sal.token as `token: StaffAuditLogToken`,\n  sal.audit_action,\n  sal.maybe_entity_type,\n  sal.maybe_entity_token,\n  target_user.username as maybe_target_username,\n  target_user.display_name as maybe_target_display_name,\n  sal.staff_user_token as `staff_user_token: UserToken`,\n  staff_user.username as staff_username,\n  staff_user.display_name as staff_display_name,\n  sal.staff_ip_address,\n  sal.created_at\nFROM staff_audit_logs sal\nLEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token\nLEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token\nORDER BY sal.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "token: StaffAuditLogToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "audit_action",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_entity_type",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_entity_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "maybe_target_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_target_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "staff_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "staff_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "staff_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "staff_ip_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true,
+      true,
+      false,
+      false
+    ]
+  },
+  "hash": "3846628765bd34ea2ce01e15a0db732121ce473c5c542d0e971ad29b2b421193"
+}
@@ -1,6 +1,6 @@
 {
  "db_name": "MySQL",
-  "query": "\nUPDATE users\nSET\n    is_banned = ?,\n    maybe_mod_comments = ?,\n    maybe_mod_user_token  = ?,\n    version = version + 1\n\nWHERE users.token = ?\nLIMIT 1\n        ",
+  "query": "\nUPDATE users\nSET\n    is_banned = ?,\n    maybe_mod_comments = ?,\n    maybe_mod_user_token  = ?,\n    version = version + 1\n\nWHERE users.token = ?\nLIMIT 1\n    ",
  "describe": {
    "columns": [],
    "parameters": {
@@ -8,5 +8,5 @@
    },
    "nullable": []
  },
-  "hash": "eab69a8d679b2dcfb06a9ccc79851f6c693d0c372142ff0e7ded89c95e4bcf44"
+  "hash": "3d746dcb479005f1f4ae5e157a5ace7626eda4849d44c6c2d7079fd346eb4edc"
 }
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nWHERE uir.id < ?\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "5d45897a5d4c326c8d17f105cae81db7f5878c197b55e8ea61c225e739d11234"
+}
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  sal.id,\n  sal.token as `token: StaffAuditLogToken`,\n  sal.audit_action,\n  sal.maybe_entity_type,\n  sal.maybe_entity_token,\n  target_user.username as maybe_target_username,\n  target_user.display_name as maybe_target_display_name,\n  sal.staff_user_token as `staff_user_token: UserToken`,\n  staff_user.username as staff_username,\n  staff_user.display_name as staff_display_name,\n  sal.staff_ip_address,\n  sal.created_at\nFROM staff_audit_logs sal\nLEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token\nLEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token\nWHERE sal.id < ?\nORDER BY sal.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "token: StaffAuditLogToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "audit_action",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "maybe_entity_type",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 64
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "maybe_entity_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "maybe_target_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "maybe_target_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "staff_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "MULTIPLE_KEY | BINARY",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "staff_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "staff_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "staff_ip_address",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 160
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      true,
+      false,
+      true,
+      true,
+      true,
+      true,
+      true,
+      false,
+      false
+    ]
+  },
+  "hash": "9132f832752ea40736bedf4729c76af7fe019cc69ed5cc280fce87e68c3f4846"
+}
@@ -0,0 +1,80 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  token,\n  impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonator_user_token as `impersonator_user_token: UserToken`,\n  user_impersonation_token,\n  is_redeemed as `is_redeemed: bool`,\n  expires_at\nFROM user_impersonation_requests\nWHERE user_impersonation_token = ?\nLIMIT 1\n    ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "user_impersonation_token",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "9dc83df0b7f1cf2716352e947b6b7fcb6c455fb0c12d72e584612f35366831f4"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_sessions (\n  token,\n  user_token,\n  maybe_impersonation_user_token,\n  ip_address_creation,\n  expires_at\n)\nVALUES (?, ?, ?, ?, ?)\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 5
+    },
+    "nullable": []
+  },
+  "hash": "ba5b0a542d4b95b781077b8895529d222dd682eb28c9d00031a820ec6f37e095"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO staff_audit_logs\nSET\n  token = ?,\n  audit_action = ?,\n  maybe_entity_type = ?,\n  maybe_entity_token = ?,\n  staff_user_token = ?,\n  staff_ip_address = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "c39800423a5fe0aa324e117e624015f85d039c3ca6833cf6865471345ab0768e"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nINSERT INTO user_impersonation_requests\nSET\n  token = ?,\n  impersonated_user_token = ?,\n  impersonator_user_token = ?,\n  user_impersonation_token = ?,\n  ip_address_creation = ?,\n  expires_at = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 6
+    },
+    "nullable": []
+  },
+  "hash": "cc782c807dadcaaaad08f469935f61dc2e9f3217aa01532d6602b8e37cedf92d"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "MySQL",
+  "query": "\nUPDATE user_impersonation_requests\nSET\n  is_redeemed = TRUE,\n  ip_address_redemption = ?\nWHERE user_impersonation_token = ?\n    ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "cf4be26ce3a48c7108640faa6c9fc68a48136327a9d374c52c16848c006f0984"
+}
@@ -0,0 +1,146 @@
+{
+  "db_name": "MySQL",
+  "query": "\nSELECT\n  uir.id,\n  uir.impersonator_user_token as `impersonator_user_token: UserToken`,\n  impersonator.username as impersonator_username,\n  impersonator.display_name as impersonator_display_name,\n  uir.impersonated_user_token as `impersonated_user_token: UserToken`,\n  impersonated.username as impersonated_username,\n  impersonated.display_name as impersonated_display_name,\n  uir.is_redeemed as `is_redeemed: bool`,\n  (uir.expires_at < NOW()) as `is_expired: bool`,\n  uir.expires_at,\n  uir.created_at,\n  uir.updated_at\nFROM user_impersonation_requests uir\nJOIN users impersonator ON impersonator.token = uir.impersonator_user_token\nJOIN users impersonated ON impersonated.token = uir.impersonated_user_token\nORDER BY uir.id DESC\nLIMIT ?\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "id",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | PRIMARY_KEY | UNSIGNED | AUTO_INCREMENT",
+          "char_set": 63,
+          "max_size": 20
+        }
+      },
+      {
+        "ordinal": 1,
+        "name": "impersonator_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 2,
+        "name": "impersonator_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 3,
+        "name": "impersonator_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 4,
+        "name": "impersonated_user_token: UserToken",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | MULTIPLE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 128
+        }
+      },
+      {
+        "ordinal": 5,
+        "name": "impersonated_username",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | UNIQUE_KEY | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 6,
+        "name": "impersonated_display_name",
+        "type_info": {
+          "type": "VarString",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 224,
+          "max_size": 80
+        }
+      },
+      {
+        "ordinal": 7,
+        "name": "is_redeemed: bool",
+        "type_info": {
+          "type": "Tiny",
+          "flags": "NOT_NULL",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 8,
+        "name": "is_expired: bool",
+        "type_info": {
+          "type": "LongLong",
+          "flags": "NOT_NULL | BINARY",
+          "char_set": 63,
+          "max_size": 1
+        }
+      },
+      {
+        "ordinal": 9,
+        "name": "expires_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | NO_DEFAULT_VALUE",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 10,
+        "name": "created_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP",
+          "char_set": 63,
+          "max_size": 19
+        }
+      },
+      {
+        "ordinal": 11,
+        "name": "updated_at",
+        "type_info": {
+          "type": "Timestamp",
+          "flags": "NOT_NULL | BINARY | TIMESTAMP | ON_UPDATE_NOW",
+          "char_set": 63,
+          "max_size": 19
+        }
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false,
+      false
+    ]
+  },
+  "hash": "e72b3dfdd9df4ee10a696faa4dfc3fb8addc9d2b88017f503c339fb616bef6f1"
+}
@@ -58,7 +58,7 @@ artcraft/

 - Rust with no minimum supported version
 - Actix-web for HTTP services
- SQLx for MySQL and SQLite
+- SQLx for MySQL and SQLite; prefer `sqlx::query!` / `sqlx::query_as!` compile-time checked macros over runtime `sqlx::query()` whenever possible
 - A mix of wreq and reqwest for Rust HTTP clients
 - Never use `println!` or `eprintln!` outside of tests; use `log` crate macros instead
 - When two crates export the same type name, alias imports with a suffix: `use foo::Bar as BarFoo;`
@@ -770,6 +770,7 @@ dependencies = [
 "anyhow",
 "artcraft_api_defs",
 "artcraft_client",
+ "enums",
 "fal_client",
 "log",
 "muapi_client",
@@ -3876,6 +3877,13 @@ dependencies = [
 "windows-sys 0.59.0",
 ]

+[[package]]
+name = "error_utils"
+version = "0.0.1"
+dependencies = [
+ "regex",
+]
+
 [[package]]
 name = "errors"
 version = "0.0.1"
@@ -7743,6 +7751,17 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "624a8340c38c1b80fd549087862da4ba43e08858af025b236e509b6649fc13d5"

+[[package]]
+name = "opaque_cursors"
+version = "0.0.1"
+dependencies = [
+ "base64 0.22.1",
+ "magic-crypt",
+ "serde",
+ "serde_derive",
+ "serde_json",
+]
+
 [[package]]
 name = "open"
 version = "5.3.3"
@@ -11234,6 +11253,7 @@ dependencies = [
 "elasticsearch",
 "elasticsearch_schema",
 "enums",
+ "error_utils",
 "errors",
 "fal_client",
 "ffmpeg_utils",
@@ -11261,6 +11281,7 @@ dependencies = [
 "mimetypes",
 "mysql_queries",
 "once_cell",
+ "opaque_cursors",
 "pager",
 "password",
 "primitives",
@@ -59,6 +59,7 @@ members = [
  "crates/lib/data/primitives",
  "crates/lib/data/web_base64",
  "crates/lib/easyenv", # NB: Vendored version of https://github.com/echelon/easyenv.rs that we'll improve.
+  "crates/lib/error_utils",
  "crates/lib/errors",
  "crates/lib/ffmpeg_utils",
  "crates/lib/files/file_to_base64_url",
@@ -72,6 +73,7 @@ members = [
  "crates/lib/http_headers",
  "crates/lib/jobs_common",
  "crates/lib/jwt_light",
+  "crates/lib/opaque_cursors",
  "crates/lib/jwt_signer",
  "crates/lib/logging",
  "crates/lib/markdown",
@@ -236,6 +238,7 @@ cookie_store = { path = "crates/lib/cookie_store" }
 crockford = { path = "crates/lib/data/crockford" }
 easyenv = { path = "crates/lib/easyenv" }
 enums = { path = "crates/schema/public/enums" }
+error_utils = { path = "crates/lib/error_utils" }
 errors = { path = "crates/lib/errors" }
 fal_client = { path = "crates/api_clients/fal_client" }
 ffmpeg_utils = { path = "crates/lib/ffmpeg_utils" }
@@ -250,6 +253,7 @@ images = { path = "crates/lib/files/images" }
 jobs_common = { path = "crates/lib/jobs_common" }
 jwt_light = { path = "crates/lib/jwt_light" }
 jwt_signer = { path = "crates/lib/jwt_signer" }
+opaque_cursors = { path = "crates/lib/opaque_cursors" }
 memory_caching = { path = "crates/lib/caching/memory_caching" }
 memory_store = { path = "crates/lib/caching/memory_store" }
 midjourney_client = { path = "crates/api_clients/midjourney_client" }
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;
@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,6 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE user_sessions
+  DROP COLUMN maybe_impersonation_user_token;
@@ -0,0 +1,7 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+ALTER TABLE user_sessions
+  ADD COLUMN maybe_impersonation_user_token VARCHAR(32) DEFAULT NULL
+  AFTER user_token;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;
@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,35 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Recreate with the original signed BIGINT id.
+CREATE TABLE user_impersonation_requests (
+
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  token VARCHAR(32) NOT NULL,
+
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  expires_at TIMESTAMP NOT NULL,
+
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS user_impersonation_requests;
@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,31 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+-- Recreate with the original signed BIGINT id.
+CREATE TABLE staff_audit_logs (
+
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  token VARCHAR(32) NOT NULL,
+
+  audit_action VARCHAR(32) NOT NULL,
+
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;
@@ -0,0 +1,5 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+DROP TABLE IF EXISTS staff_audit_logs;
@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,38 @@
+# SQL Migrations
+
+Incremental schema changes applied in order by timestamp prefix.
+
+## Naming Convention
+
+Migration directories follow the format:
+
+```
+YYYY-MM-DD-HHMMSS-NNNN_description_goes_here/
+  up.sql
+  down.sql
+```
+
+These are created with the `diesel` tool, and in particular:
+
+> `diesel migration generate description_goes_here`
+
+- `NNNN` is a zero-padded sequence number for ordering multiple migrations on the same timestamp.
+- `up.sql` applies the migration forward.
+- `down.sql` reverses it.
+
+## Table Conventions
+
+- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs.
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+- All SQL files should start with the standard IntelliJ noinspection comments:
+  ```sql
+  -- noinspection SqlDialectInspectionForFile
+  -- noinspection SqlNoDataSourceInspectionForFile
+  -- noinspection SqlResolveForFile
+  ```
+
+## Rules
+
+- Every `up.sql` must have a corresponding `down.sql` that cleanly reverses the migration.
+- For `CREATE TABLE` migrations, the `down.sql` is typically `DROP TABLE IF EXISTS table_name;`.
+- For `ALTER TABLE` migrations, the `down.sql` reverses the alteration (e.g. `DROP COLUMN`).
@@ -0,0 +1,26 @@
+# Squashed / Materialized Schemas
+
+Fully materialized table definitions representing the current state of each table
+after all migrations have been applied. These are not executed — they exist as
+human-readable documentation of the current schema.
+
+## When to Update
+
+Update the corresponding squashed file whenever a migration changes a table's schema
+(adding columns, changing types, dropping and recreating, etc.).
+
+## Table Conventions
+
+- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs.
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+- All SQL files should start with the standard IntelliJ noinspection comments:
+  ```sql
+  -- noinspection SqlDialectInspectionForFile
+  -- noinspection SqlNoDataSourceInspectionForFile
+  -- noinspection SqlResolveForFile
+  ```
+
+## File Organization
+
+Files are named after their table (e.g. `users.sql`, `media_files.sql`).
+Some tables are grouped into subdirectories (e.g. `user_tables/`).
@@ -0,0 +1,39 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE staff_audit_logs (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Effective "primary key" of the audit log item (in case we add a UI or notes)
+  token VARCHAR(32) NOT NULL,
+
+  -- The type of action taken
+  audit_action VARCHAR(32) NOT NULL,
+
+  -- The type of entity acted upon (if any)
+  maybe_entity_type VARCHAR(16) DEFAULT NULL,
+
+  -- The token of the entity mutated (if any)
+  maybe_entity_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who performed the action.
+  staff_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- For abuse tracking.
+  -- Wide enough for IPv4/6
+  staff_ip_address VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY index_maybe_entity_type (maybe_entity_type),
+  KEY index_maybe_entity_token (maybe_entity_token),
+  KEY index_staff_user_token (staff_user_token),
+  KEY index_created_at (created_at)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,44 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_impersonation_requests (
+
+  -- Not used for anything except replication.
+  id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+
+  -- Internal "primary key"
+  token VARCHAR(32) NOT NULL,
+
+  -- The user being impersonated.
+  impersonated_user_token VARCHAR(32) NOT NULL,
+
+  -- The staff user who initiated the impersonation.
+  impersonator_user_token VARCHAR(32) NOT NULL,
+
+  -- The actual secret that must be presented to redeem the impersonation.
+  user_impersonation_token VARCHAR(32) NOT NULL,
+
+  -- Whether this request has been redeemed (used to create a session).
+  is_redeemed BOOLEAN NOT NULL DEFAULT FALSE,
+
+  -- IP address of the staff user who created the request.
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  -- IP address from which the request was redeemed, if redeemed.
+  ip_address_redemption VARCHAR(40) DEFAULT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- The request expires after this time if not redeemed.
+  expires_at TIMESTAMP NOT NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  UNIQUE KEY (user_impersonation_token),
+  KEY index_impersonated_user_token (impersonated_user_token),
+  KEY index_impersonator_user_token (impersonator_user_token)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,50 @@
+-- noinspection SqlDialectInspectionForFile
+-- noinspection SqlNoDataSourceInspectionForFile
+-- noinspection SqlResolveForFile
+
+CREATE TABLE user_sessions (
+  -- Not used for anything except replication.
+  id BIGINT(20) NOT NULL AUTO_INCREMENT,
+
+  -- Session primary key
+  token VARCHAR(32) NOT NULL,
+
+  -- The user that the session belongs to.
+  user_token VARCHAR(32) NOT NULL,
+
+  -- NEVER IMPERSONATE A USER'S ACCOUNT WITHOUT THEIR CONSENT!
+  --
+  -- For support requests and inquiries, we can have staff log into user accounts
+  -- to verify and debug possible broken states. The user is always told about
+  -- this if we are to use this for support cases.
+  --
+  -- Every action performed by impersonated sessions is logged for auditing.
+  --
+  -- If this session is impersonating another user, this is the token of
+  -- the staff user who initiated the impersonation.
+  maybe_impersonation_user_token VARCHAR(32) DEFAULT NULL,
+
+  -- Track each session's creation IP.
+  -- Wide enough for IPv4/6
+  ip_address_creation VARCHAR(40) NOT NULL,
+
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+
+  -- Session termination time.
+  -- This must be set by the server code, or the session is invalid
+  expires_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  -- deletion = session termination
+  -- Typically these are destroyed by users, but if in the future we allow mods to
+  -- delete them, it doesn't really matter who did the deletion: sessions are not
+  -- designed to be recoverable.
+  deleted_at TIMESTAMP NULL,
+
+  -- INDICES --
+  PRIMARY KEY (id),
+  UNIQUE KEY (token),
+  KEY fk_user_token (user_token),
+  KEY index_ip_address_creation (ip_address_creation)
+
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
@@ -0,0 +1,11 @@
+$kind: http-request
+name: Impersonate User Request
+url: "{{api_host}}/v1/moderation/user_sessions/impersonate"
+method: POST
+body:
+  type: json
+  content: |-
+    {
+        "username": "newuser3"
+    }
+order: 4318829221021218
@@ -16,7 +16,8 @@ pub struct GenerateVeo2ImageToVideoRequest {
  
  /// Optional text prompt.
  pub prompt: Option<String>,
-  
+
+  /// **NB(bt): ASPECT RATIO IS ACTUALLY NOT USED IN VEO 2 IMAGE-TO-VIDEO**
  /// Optional: aspect ratio of the generated video.
  pub aspect_ratio: Option<GenerateVeo2AspectRatio>,

@@ -21,6 +21,9 @@ pub struct GenerateVeo3FastImageToVideoRequest {
  pub resolution: Option<GenerateVeo3FastResolution>,

  /// Optional: aspect ratio of the generated video.
+  pub aspect_ratio: Option<GenerateVeo3FastAspectRatio>,
+
+  /// Optional: duration of the generated video.
  pub duration: Option<GenerateVeo3FastDuration>,

  /// Optional: Generate an audio track along with the video
@@ -34,6 +37,14 @@ pub enum GenerateVeo3FastResolution {
  TenEightyP, // 1080p
 }

+#[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum GenerateVeo3FastAspectRatio {
+  Auto,
+  SixteenByNine,
+  NineBySixteen,
+}
+
 #[derive(Copy, Clone, Debug, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "snake_case")]
 pub enum GenerateVeo3FastDuration {
@@ -42,6 +42,10 @@ pub struct GenerateVeo3ImageToVideoRequest {
 pub enum GenerateVeo3AspectRatio {
  WideSixteenNine, // 16:9
  TallNineSixteen, // 9:16
+  
+  /// NB: DO NOT REMOVE. This is an unsupported resolution for Veo 3, but we can't 
+  /// impact existing callers by removing it. The handler will convert this to a 
+  /// supported resolution or 400 the request instead.
  Square, // 1:1
 }

@@ -120,6 +120,9 @@ pub struct OmniGenImageModelDetails {

  #[serde(skip_serializing_if = "Option::is_none")]
  pub batch_size_default: Option<u16>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub is_disabled: Option<bool>,
 }

 impl Default for OmniGenImageModelDetails {
@@ -145,6 +148,7 @@ impl Default for OmniGenImageModelDetails {
      batch_size_max: None,
      batch_size_options: None,
      batch_size_default: None,
+      is_disabled: None,
    }
  }
 }
@@ -163,6 +163,9 @@ pub struct OmniGenVideoModelDetails {
  
  #[serde(skip_serializing_if = "Option::is_none")]
  pub batch_size_default: Option<u16>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub is_disabled: Option<bool>,
 }

 impl Default for OmniGenVideoModelDetails {
@@ -202,6 +205,7 @@ impl Default for OmniGenVideoModelDetails {
      batch_size_max: None,
      batch_size_options: None,
      batch_size_default: None,
+      is_disabled: None,
    }
  }
 }
@@ -2,6 +2,7 @@ pub mod analytics;
 pub mod credits;
 pub mod generate;
 pub mod jobs;
+pub mod omni_gen;
 pub mod media_files;
 pub mod prompts;
 pub mod stripe_artcraft;
@@ -0,0 +1 @@
+pub mod video;
@@ -0,0 +1 @@
+pub mod omni_gen_video;
@@ -0,0 +1,21 @@
+use crate::credentials::storyteller_credential_set::StorytellerCredentialSet;
+use crate::error::storyteller_error::StorytellerError;
+use crate::utils::api_host::ApiHost;
+use crate::utils::basic_json_post_request::basic_json_post_request;
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_video_cost_and_generate_request::OmniGenVideoCostAndGenerateRequest;
+use artcraft_api_defs::omni_gen::generate_response::omni_gen_video_generate_response::OmniGenVideoGenerateResponse;
+
+pub const OMNI_GEN_VIDEO_GENERATE_PATH: &str = "/v1/omni_gen/generate/video";
+
+pub async fn omni_gen_video_generate(
+  api_host: &ApiHost,
+  maybe_creds: Option<&StorytellerCredentialSet>,
+  request: OmniGenVideoCostAndGenerateRequest,
+) -> Result<OmniGenVideoGenerateResponse, StorytellerError> {
+  Ok(basic_json_post_request(
+    api_host,
+    OMNI_GEN_VIDEO_GENERATE_PATH,
+    maybe_creds,
+    request,
+  ).await?)
+}
@@ -0,0 +1 @@
+pub mod generate;
@@ -17,6 +17,7 @@ workspace-build-acceleration.workspace = true

 # Internal
 artcraft_api_defs.workspace = true
+enums.workspace = true
 artcraft_client.workspace = true
 fal_client.workspace = true
 muapi_client.workspace = true
@@ -6,31 +6,72 @@ use crate::generate::generate_video::generate_video_response::{
 };
 use crate::generate::generate_video::plan::artcraft::plan_generate_video_artcraft_veo_2::PlanArtcraftVeo2;
 use artcraft_api_defs::generate::video::generate_veo_2_image_to_video::GenerateVeo2ImageToVideoRequest;
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_video_cost_and_generate_request::OmniGenVideoCostAndGenerateRequest;
 use artcraft_client::endpoints::generate::video::generate_veo_2_image_to_video::generate_veo_2_image_to_video;
+use artcraft_client::endpoints::omni_gen::generate::video::omni_gen_video::omni_gen_video_generate;
+use enums::common::generation::common_video_model::CommonVideoModel;

 pub async fn execute_artcraft_veo_2(
  plan: &PlanArtcraftVeo2<'_>,
  artcraft_client: &RouterArtcraftClient,
 ) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
-  let request = GenerateVeo2ImageToVideoRequest {
-    uuid_idempotency_token: plan.idempotency_token.clone(),
-    media_file_token: Some(plan.start_frame.to_owned()),
-    prompt: plan.prompt.map(|p| p.to_string()),
-    aspect_ratio: plan.aspect_ratio.clone(),
-    duration: plan.duration.clone(),
+  let inference_job_token = match plan.start_frame {
+    Some(media_file_token) => {
+      // Image-to-video: use the legacy dedicated endpoint.
+      let request = GenerateVeo2ImageToVideoRequest {
+        uuid_idempotency_token: plan.idempotency_token.clone(),
+        media_file_token: Some(media_file_token.to_owned()),
+        prompt: plan.prompt.map(|p| p.to_string()),
+        aspect_ratio: plan.aspect_ratio.clone(),
+        duration: plan.duration.clone(),
+      };
+
+      let response = generate_veo_2_image_to_video(
+        &artcraft_client.api_host,
+        Some(&artcraft_client.credentials),
+        request,
+      )
+      .await
+      .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
+
+      response.inference_job_token
+    }
+    None => {
+      // Text-to-video: use the omni-gen unified endpoint.
+      let request = OmniGenVideoCostAndGenerateRequest {
+        idempotency_token: Some(plan.idempotency_token.clone()),
+        model: Some(CommonVideoModel::Veo2),
+        prompt: plan.prompt.map(|p| p.to_string()),
+        negative_prompt: None,
+        start_frame_image_media_token: None,
+        end_frame_image_media_token: None,
+        reference_image_media_tokens: None,
+        reference_video_media_tokens: None,
+        reference_audio_media_tokens: None,
+        reference_character_tokens: None,
+        resolution: None,
+        aspect_ratio: None,
+        quality: None,
+        duration_seconds: None,
+        video_batch_count: None,
+        generate_audio: None,
+      };
+
+      let response = omni_gen_video_generate(
+        &artcraft_client.api_host,
+        Some(&artcraft_client.credentials),
+        request,
+      )
+      .await
+      .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
+
+      response.inference_job_token
+    }
  };

-  let response = generate_veo_2_image_to_video(
-    &artcraft_client.api_host,
-    Some(&artcraft_client.credentials),
-    request,
-  )
-    .await
-    .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
-
-  let all_tokens = vec![response.inference_job_token.clone()];
+  let all_tokens = vec![inference_job_token.clone()];
  Ok(GenerateVideoResponse::Artcraft(ArtcraftVideoResponsePayload {
-    inference_job_token: response.inference_job_token,
+    inference_job_token,
    all_inference_job_tokens: all_tokens,
  }))
 }
@@ -6,33 +6,74 @@ use crate::generate::generate_video::generate_video_response::{
 };
 use crate::generate::generate_video::plan::artcraft::plan_generate_video_artcraft_veo_3::PlanArtcraftVeo3;
 use artcraft_api_defs::generate::video::generate_veo_3_image_to_video::GenerateVeo3ImageToVideoRequest;
+use artcraft_api_defs::omni_gen::cost_and_generate_requests::omni_gen_video_cost_and_generate_request::OmniGenVideoCostAndGenerateRequest;
 use artcraft_client::endpoints::generate::video::generate_veo_3_image_to_video::generate_veo_3_image_to_video;
+use artcraft_client::endpoints::omni_gen::generate::video::omni_gen_video::omni_gen_video_generate;
+use enums::common::generation::common_video_model::CommonVideoModel;

 pub async fn execute_artcraft_veo_3(
  plan: &PlanArtcraftVeo3<'_>,
  artcraft_client: &RouterArtcraftClient,
 ) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
-  let request = GenerateVeo3ImageToVideoRequest {
-    uuid_idempotency_token: plan.idempotency_token.clone(),
-    media_file_token: Some(plan.start_frame.to_owned()),
-    prompt: plan.prompt.map(|p| p.to_string()),
-    aspect_ratio: plan.aspect_ratio,
-    resolution: plan.resolution,
-    duration: plan.duration,
-    generate_audio: plan.generate_audio,
+  let inference_job_token = match plan.start_frame {
+    Some(media_file_token) => {
+      // Image-to-video: use the legacy dedicated endpoint.
+      let request = GenerateVeo3ImageToVideoRequest {
+        uuid_idempotency_token: plan.idempotency_token.clone(),
+        media_file_token: Some(media_file_token.to_owned()),
+        prompt: plan.prompt.map(|p| p.to_string()),
+        aspect_ratio: plan.aspect_ratio,
+        resolution: plan.resolution,
+        duration: plan.duration,
+        generate_audio: plan.generate_audio,
+      };
+
+      let response = generate_veo_3_image_to_video(
+        &artcraft_client.api_host,
+        Some(&artcraft_client.credentials),
+        request,
+      )
+      .await
+      .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
+
+      response.inference_job_token
+    }
+    None => {
+      // Text-to-video: use the omni-gen unified endpoint.
+      let request = OmniGenVideoCostAndGenerateRequest {
+        idempotency_token: Some(plan.idempotency_token.clone()),
+        model: Some(CommonVideoModel::Veo3),
+        prompt: plan.prompt.map(|p| p.to_string()),
+        negative_prompt: None,
+        start_frame_image_media_token: None,
+        end_frame_image_media_token: None,
+        reference_image_media_tokens: None,
+        reference_video_media_tokens: None,
+        reference_audio_media_tokens: None,
+        reference_character_tokens: None,
+        resolution: None,
+        aspect_ratio: None,
+        quality: None,
+        duration_seconds: None,
+        video_batch_count: None,
+        generate_audio: plan.generate_audio,
+      };
+
+      let response = omni_gen_video_generate(
+        &artcraft_client.api_host,
+        Some(&artcraft_client.credentials),
+        request,
+      )
+      .await
+      .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
+
+      response.inference_job_token
+    }
  };

-  let response = generate_veo_3_image_to_video(
-    &artcraft_client.api_host,
-    Some(&artcraft_client.credentials),
-    request,
-  )
-    .await
-    .map_err(|err| ArtcraftRouterError::Provider(ProviderError::Storyteller(err)))?;
-
-  let all_tokens = vec![response.inference_job_token.clone()];
+  let all_tokens = vec![inference_job_token.clone()];
  Ok(GenerateVideoResponse::Artcraft(ArtcraftVideoResponsePayload {
-    inference_job_token: response.inference_job_token,
+    inference_job_token,
    all_inference_job_tokens: all_tokens,
  }))
 }
@@ -14,8 +14,9 @@ pub async fn execute_artcraft_veo_3_fast(
 ) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
  let request = GenerateVeo3FastImageToVideoRequest {
    uuid_idempotency_token: plan.idempotency_token.clone(),
-    media_file_token: Some(plan.start_frame.to_owned()),
+    media_file_token: plan.start_frame.map(|t| t.to_owned()),
    prompt: plan.prompt.map(|p| p.to_string()),
+    aspect_ratio: plan.aspect_ratio,
    resolution: plan.resolution,
    duration: plan.duration,
    generate_audio: plan.generate_audio,
@@ -4,28 +4,50 @@ use crate::errors::provider_error::ProviderError;
 use crate::generate::generate_video::generate_video_response::{
  FalVideoResponsePayload, GenerateVideoResponse,
 };
-use crate::generate::generate_video::plan::fal::plan_generate_video_fal_veo_2::PlanFalVeo2;
+use crate::generate::generate_video::plan::fal::plan_generate_video_fal_veo_2::{
+  FalVeo2Mode, PlanFalVeo2,
+};
 use fal_client::requests::webhook::video::image::enqueue_veo_2_image_to_video_webhook::{
-  enqueue_veo_2_image_to_video_webhook, Veo2Args,
+  enqueue_veo_2_image_to_video_webhook, Veo2Args, Veo2AspectRatio,
+};
+use fal_client::requests::webhook::video::text::enqueue_veo_2_text_to_video_webhook::{
+  enqueue_veo_2_text_to_video_webhook, Veo2TextToVideoArgs,
 };

 pub async fn execute_fal_veo_2(
  plan: &PlanFalVeo2,
  fal_client: &RouterFalClient,
 ) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
-  let args = Veo2Args {
-    image_url: plan.start_frame_url.as_str(),
-    prompt: plan.prompt.as_str(),
-    api_key: &fal_client.api_key,
-    duration: plan.duration,
-    aspect_ratio: plan.aspect_ratio,
-    webhook_url: fal_client.webhook_url.as_str(),
+  let webhook_response = match &plan.mode {
+    FalVeo2Mode::TextToVideo => {
+      let args = Veo2TextToVideoArgs {
+        prompt: plan.prompt.as_str(),
+        negative_prompt: plan.negative_prompt.as_deref(),
+        api_key: &fal_client.api_key,
+        duration: plan.duration,
+        aspect_ratio: plan.aspect_ratio.unwrap_or(Veo2AspectRatio::Auto),
+        webhook_url: fal_client.webhook_url.as_str(),
+      };
+      enqueue_veo_2_text_to_video_webhook(args)
+        .await
+        .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?
+    }
+    FalVeo2Mode::ImageToVideo { image_url } => {
+      // Image-to-video does not support aspect_ratio — the output
+      // inherits the source image's aspect ratio.
+      let args = Veo2Args {
+        image_url: image_url.as_str(),
+        prompt: plan.prompt.as_str(),
+        api_key: &fal_client.api_key,
+        duration: plan.duration,
+        webhook_url: fal_client.webhook_url.as_str(),
+      };
+      enqueue_veo_2_image_to_video_webhook(args)
+        .await
+        .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?
+    }
  };

-  let webhook_response = enqueue_veo_2_image_to_video_webhook(args)
-    .await
-    .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?;
-
  Ok(GenerateVideoResponse::Fal(FalVideoResponsePayload {
    request_id: webhook_response.request_id,
    gateway_request_id: webhook_response.gateway_request_id,
@@ -4,30 +4,106 @@ use crate::errors::provider_error::ProviderError;
 use crate::generate::generate_video::generate_video_response::{
  FalVideoResponsePayload, GenerateVideoResponse,
 };
-use crate::generate::generate_video::plan::fal::plan_generate_video_fal_veo_3::PlanFalVeo3;
-use fal_client::requests::webhook::video::image::enqueue_veo_3_image_to_video_webhook::{
-  enqueue_veo_3_image_to_video_webhook, Veo3Args,
+use crate::generate::generate_video::plan::fal::plan_generate_video_fal_veo_3::{
+  FalVeo3Duration, FalVeo3I2vAspectRatio, FalVeo3Mode, FalVeo3Resolution,
+  FalVeo3T2vAspectRatio, PlanFalVeo3,
 };
+use fal_client::requests::webhook::video::image::enqueue_veo_3_image_to_video_webhook::{
+  enqueue_veo_3_image_to_video_webhook, Veo3Args, Veo3I2vAspectRatio, Veo3I2vDuration,
+  Veo3I2vResolution,
+};
+use fal_client::requests::webhook::video::text::enqueue_veo_3_text_to_video_webhook::{
+  enqueue_veo_3_text_to_video_webhook, Veo3T2vAspectRatio, Veo3T2vDuration, Veo3T2vResolution,
+  Veo3TextToVideoArgs,
+};
+
+fn to_i2v_duration(d: FalVeo3Duration) -> Veo3I2vDuration {
+  match d {
+    FalVeo3Duration::Default => Veo3I2vDuration::Default,
+    FalVeo3Duration::FourSeconds => Veo3I2vDuration::FourSeconds,
+    FalVeo3Duration::SixSeconds => Veo3I2vDuration::SixSeconds,
+    FalVeo3Duration::EightSeconds => Veo3I2vDuration::EightSeconds,
+  }
+}
+
+fn to_t2v_duration(d: FalVeo3Duration) -> Veo3T2vDuration {
+  match d {
+    FalVeo3Duration::Default => Veo3T2vDuration::Default,
+    FalVeo3Duration::FourSeconds => Veo3T2vDuration::FourSeconds,
+    FalVeo3Duration::SixSeconds => Veo3T2vDuration::SixSeconds,
+    FalVeo3Duration::EightSeconds => Veo3T2vDuration::EightSeconds,
+  }
+}
+
+fn to_i2v_resolution(r: FalVeo3Resolution) -> Veo3I2vResolution {
+  match r {
+    FalVeo3Resolution::Default => Veo3I2vResolution::Default,
+    FalVeo3Resolution::SevenTwentyP => Veo3I2vResolution::SevenTwentyP,
+    FalVeo3Resolution::TenEightyP => Veo3I2vResolution::TenEightyP,
+  }
+}
+
+fn to_t2v_resolution(r: FalVeo3Resolution) -> Veo3T2vResolution {
+  match r {
+    FalVeo3Resolution::Default => Veo3T2vResolution::Default,
+    FalVeo3Resolution::SevenTwentyP => Veo3T2vResolution::SevenTwentyP,
+    FalVeo3Resolution::TenEightyP => Veo3T2vResolution::TenEightyP,
+  }
+}
+
+fn to_t2v_aspect_ratio(ar: FalVeo3T2vAspectRatio) -> Veo3T2vAspectRatio {
+  match ar {
+    FalVeo3T2vAspectRatio::Default => Veo3T2vAspectRatio::Default,
+    FalVeo3T2vAspectRatio::WideSixteenNine => Veo3T2vAspectRatio::WideSixteenNine,
+    FalVeo3T2vAspectRatio::TallNineSixteen => Veo3T2vAspectRatio::TallNineSixteen,
+  }
+}
+
+fn to_i2v_aspect_ratio(ar: FalVeo3I2vAspectRatio) -> Veo3I2vAspectRatio {
+  match ar {
+    FalVeo3I2vAspectRatio::Auto => Veo3I2vAspectRatio::Auto,
+    FalVeo3I2vAspectRatio::WideSixteenNine => Veo3I2vAspectRatio::WideSixteenNine,
+    FalVeo3I2vAspectRatio::TallNineSixteen => Veo3I2vAspectRatio::TallNineSixteen,
+  }
+}

 pub async fn execute_fal_veo_3(
  plan: &PlanFalVeo3,
  fal_client: &RouterFalClient,
 ) -> Result<GenerateVideoResponse, ArtcraftRouterError> {
-  let args = Veo3Args {
-    image_url: plan.start_frame_url.as_str(),
-    prompt: plan.prompt.as_str(),
-    duration: plan.duration,
-    aspect_ratio: plan.aspect_ratio,
-    resolution: plan.resolution,
-    generate_audio: plan.generate_audio,
-    api_key: &fal_client.api_key,
-    webhook_url: fal_client.webhook_url.as_str(),
+  let webhook_response = match &plan.mode {
+    FalVeo3Mode::TextToVideo => {
+      let args = Veo3TextToVideoArgs {
+        prompt: plan.prompt.as_str(),
+        negative_prompt: plan.negative_prompt.as_deref(),
+        api_key: &fal_client.api_key,
+        duration: to_t2v_duration(plan.duration),
+        aspect_ratio: plan.t2v_aspect_ratio.map(to_t2v_aspect_ratio).unwrap_or(Veo3T2vAspectRatio::Default),
+        resolution: to_t2v_resolution(plan.resolution),
+        generate_audio: plan.generate_audio,
+        webhook_url: fal_client.webhook_url.as_str(),
+      };
+      enqueue_veo_3_text_to_video_webhook(args)
+        .await
+        .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?
+    }
+    FalVeo3Mode::ImageToVideo { image_url } => {
+      let args = Veo3Args {
+        image_url: image_url.as_str(),
+        prompt: plan.prompt.as_str(),
+        duration: to_i2v_duration(plan.duration),
+        aspect_ratio: plan.i2v_aspect_ratio.map(to_i2v_aspect_ratio).unwrap_or(Veo3I2vAspectRatio::Auto),
+        resolution: to_i2v_resolution(plan.resolution),
+        generate_audio: plan.generate_audio,
+        api_key: &fal_client.api_key,
+        webhook_url: fal_client.webhook_url.as_str(),
+      };
+      enqueue_veo_3_image_to_video_webhook(args)
+        .await
+        .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?
+    }
  };

-  let webhook_response = enqueue_veo_3_image_to_video_webhook(args)
-    .await
-    .map_err(|e| ArtcraftRouterError::Provider(ProviderError::Fal(e)))?;
-
  Ok(GenerateVideoResponse::Fal(FalVideoResponsePayload {
    request_id: webhook_response.request_id,
    gateway_request_id: webhook_response.gateway_request_id,
@@ -16,6 +16,7 @@ pub async fn execute_fal_veo_3_fast(
  let args = Veo3FastArgs {
    prompt: plan.prompt.as_str(),
    image_url: plan.start_frame_url.as_str(),
+    aspect_ratio: plan.aspect_ratio,
    duration: plan.duration,
    api_key: &fal_client.api_key,
    resolution: plan.resolution,
@@ -13,7 +13,10 @@ use tokens::tokens::media_files::MediaFileToken;
 #[derive(Debug, Clone)]
 pub struct PlanArtcraftVeo2<'a> {
  pub prompt: Option<&'a str>,
-  pub start_frame: &'a MediaFileToken,
+  /// Required for execution. May be None on the cost path when the omni-gen
+  /// distillation hydrated the media token to a URL (which the Artcraft
+  /// provider can't use but cost estimation doesn't need).
+  pub start_frame: Option<&'a MediaFileToken>,
  pub aspect_ratio: Option<GenerateVeo2AspectRatio>,
  pub duration: Option<GenerateVeo2Duration>,
  pub idempotency_token: String,
@@ -25,16 +28,13 @@ pub fn plan_generate_video_artcraft_veo_2<'a>(
  let strategy = request.request_mismatch_mitigation_strategy;

  let start_frame = match request.start_frame {
-    Some(ImageRef::MediaFileToken(t)) => t,
-    Some(ImageRef::Url(_)) => {
-      return Err(ArtcraftRouterError::Client(ClientError::ArtcraftOnlySupportsMediaTokens))
-    }
-    None => {
-      return Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
-        field: "start_frame",
-        value: "Veo 2 requires a starting frame".to_string(),
-      }))
-    }
+    Some(ImageRef::MediaFileToken(t)) => Some(t),
+    // Omni-gen distillation hydrates media tokens to URLs before running the
+    // Artcraft cost path. Cost only depends on duration, so URL-form refs are
+    // accepted and dropped.
+    Some(ImageRef::Url(_)) => None,
+    // No start_frame = text-to-video mode.
+    None => None,
  };

  if request.end_frame.is_some() {
@@ -44,7 +44,14 @@ pub fn plan_generate_video_artcraft_veo_2<'a>(
    }));
  }

-  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
+  // Aspect ratio only applies to text-to-video; image-to-video inherits
+  // the source frame's aspect ratio.
+  let is_image_mode = request.start_frame.is_some();
+  let aspect_ratio = if is_image_mode {
+    None
+  } else {
+    plan_aspect_ratio(request.aspect_ratio, strategy)?
+  };
  let duration = plan_duration(request.duration_seconds, strategy)?;

  Ok(VideoGenerationPlan::ArtcraftVeo2(PlanArtcraftVeo2 {
@@ -14,10 +14,16 @@ use tokens::tokens::media_files::MediaFileToken;
 #[derive(Debug, Clone)]
 pub struct PlanArtcraftVeo3<'a> {
  pub prompt: Option<&'a str>,
-  pub start_frame: &'a MediaFileToken,
+  /// Required for image-to-video. None for text-to-video or when the
+  /// omni-gen distillation hydrated the token to a URL.
+  pub start_frame: Option<&'a MediaFileToken>,
  pub aspect_ratio: Option<GenerateVeo3AspectRatio>,
  pub resolution: Option<GenerateVeo3Resolution>,
  pub duration: Option<GenerateVeo3Duration>,
+  /// The raw requested duration in seconds, preserved for cost estimation.
+  /// The `duration` field above maps everything to `EightSeconds` for the
+  /// legacy endpoint, but cost should reflect the actual requested value.
+  pub duration_seconds_raw: Option<u16>,
  pub generate_audio: Option<bool>,
  pub idempotency_token: String,
 }
@@ -28,16 +34,13 @@ pub fn plan_generate_video_artcraft_veo_3<'a>(
  let strategy = request.request_mismatch_mitigation_strategy;

  let start_frame = match request.start_frame {
-    Some(ImageRef::MediaFileToken(t)) => t,
-    Some(ImageRef::Url(_)) => {
-      return Err(ArtcraftRouterError::Client(ClientError::ArtcraftOnlySupportsMediaTokens))
-    }
-    None => {
-      return Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
-        field: "start_frame",
-        value: "Veo 3 requires a starting frame".to_string(),
-      }))
-    }
+    Some(ImageRef::MediaFileToken(t)) => Some(t),
+    // Omni-gen distillation hydrates media tokens to URLs before running the
+    // Artcraft cost path. Cost only depends on duration/audio, so URL-form
+    // refs are accepted and dropped.
+    Some(ImageRef::Url(_)) => None,
+    // No start_frame = text-to-video mode.
+    None => None,
  };

  if request.end_frame.is_some() {
@@ -47,7 +50,14 @@ pub fn plan_generate_video_artcraft_veo_3<'a>(
    }));
  }

-  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
+  // Aspect ratio only applies to text-to-video; image-to-video inherits
+  // the source frame's aspect ratio.
+  let is_image_mode = request.start_frame.is_some();
+  let aspect_ratio = if is_image_mode {
+    None
+  } else {
+    plan_aspect_ratio(request.aspect_ratio, strategy)?
+  };
  let resolution = plan_resolution(request.resolution, strategy)?;
  let duration = plan_duration(request.duration_seconds, strategy)?;

@@ -57,6 +67,7 @@ pub fn plan_generate_video_artcraft_veo_3<'a>(
    aspect_ratio,
    resolution,
    duration,
+    duration_seconds_raw: request.duration_seconds,
    generate_audio: request.generate_audio,
    idempotency_token: request.get_or_generate_idempotency_token(),
  }))
@@ -112,14 +123,19 @@ fn plan_resolution(
  }
 }

-// Legacy storyteller endpoint for Veo 3 only exposes EightSeconds.
+// The legacy storyteller endpoint for Veo 3 only exposes EightSeconds, but
+// the artcraft plan stores the raw duration_seconds from the omni request so
+// that cost estimation works for all supported durations (4/6/8).
 fn plan_duration(
  duration_seconds: Option<u16>,
  strategy: RequestMismatchMitigationStrategy,
 ) -> Result<Option<GenerateVeo3Duration>, ArtcraftRouterError> {
  match duration_seconds {
    None => Ok(None),
-    Some(8) => Ok(Some(GenerateVeo3Duration::EightSeconds)),
+    // The api_defs enum only has EightSeconds; all durations map to it for
+    // the legacy endpoint. The actual seconds are tracked via
+    // `duration_seconds_raw` below for cost estimation.
+    Some(4) | Some(6) | Some(8) => Ok(Some(GenerateVeo3Duration::EightSeconds)),
    Some(other) => match strategy {
      RequestMismatchMitigationStrategy::ErrorOut => {
        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
@@ -127,18 +143,25 @@ fn plan_duration(
          value: format!("{}", other),
        }))
      }
-      _ => Ok(Some(GenerateVeo3Duration::EightSeconds)),
+      RequestMismatchMitigationStrategy::PayMoreUpgrade => Ok(Some(GenerateVeo3Duration::EightSeconds)),
+      RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(Some(GenerateVeo3Duration::EightSeconds)),
    },
  }
 }

 impl PlanArtcraftVeo3<'_> {
-  /// Mirrors the Fal client default (8s) used by the legacy generate handler.
+  /// Duration in seconds for cost estimation. Uses the raw requested
+  /// duration, clamped to {4, 6, 8}, defaulting to 8s.
  pub fn duration_seconds_for_cost(&self) -> u64 {
-    8
+    match self.duration_seconds_raw {
+      Some(s) if s <= 4 => 4,
+      Some(s) if s <= 6 => 6,
+      _ => 8, // None, 7, 8, or above → 8s
+    }
  }

  /// Legacy Veo 3 generate handler defaults `generate_audio` to false.
+  /// The omni path defaults to true (matching the fal plan builder).
  pub fn generate_audio_for_cost(&self) -> bool {
    self.generate_audio.unwrap_or(false)
  }
@@ -1,3 +1,4 @@
+use crate::api::common_aspect_ratio::CommonAspectRatio;
 use crate::api::common_resolution::CommonResolution;
 use crate::api::image_ref::ImageRef;
 use crate::client::request_mismatch_mitigation_strategy::RequestMismatchMitigationStrategy;
@@ -6,14 +7,15 @@ use crate::errors::client_error::ClientError;
 use crate::generate::generate_video::generate_video_request::GenerateVideoRequest;
 use crate::generate::generate_video::video_generation_plan::VideoGenerationPlan;
 use artcraft_api_defs::generate::video::generate_veo_3_fast_image_to_video::{
-  GenerateVeo3FastDuration, GenerateVeo3FastResolution,
+  GenerateVeo3FastAspectRatio, GenerateVeo3FastDuration, GenerateVeo3FastResolution,
 };
 use tokens::tokens::media_files::MediaFileToken;

 #[derive(Debug, Clone)]
 pub struct PlanArtcraftVeo3Fast<'a> {
  pub prompt: Option<&'a str>,
-  pub start_frame: &'a MediaFileToken,
+  pub start_frame: Option<&'a MediaFileToken>,
+  pub aspect_ratio: Option<GenerateVeo3FastAspectRatio>,
  pub resolution: Option<GenerateVeo3FastResolution>,
  pub duration: Option<GenerateVeo3FastDuration>,
  pub generate_audio: Option<bool>,
@@ -26,16 +28,9 @@ pub fn plan_generate_video_artcraft_veo_3_fast<'a>(
  let strategy = request.request_mismatch_mitigation_strategy;

  let start_frame = match request.start_frame {
-    Some(ImageRef::MediaFileToken(t)) => t,
-    Some(ImageRef::Url(_)) => {
-      return Err(ArtcraftRouterError::Client(ClientError::ArtcraftOnlySupportsMediaTokens))
-    }
-    None => {
-      return Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
-        field: "start_frame",
-        value: "Veo 3 Fast requires a starting frame".to_string(),
-      }))
-    }
+    Some(ImageRef::MediaFileToken(t)) => Some(t),
+    Some(ImageRef::Url(_)) => None,
+    None => None,
  };

  if request.end_frame.is_some() {
@@ -45,12 +40,14 @@ pub fn plan_generate_video_artcraft_veo_3_fast<'a>(
    }));
  }

+  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
  let resolution = plan_resolution(request.resolution, strategy)?;
  let duration = plan_duration(request.duration_seconds, strategy)?;

  Ok(VideoGenerationPlan::ArtcraftVeo3Fast(PlanArtcraftVeo3Fast {
    prompt: request.prompt,
    start_frame,
+    aspect_ratio,
    resolution,
    duration,
    generate_audio: request.generate_audio,
@@ -58,6 +55,33 @@ pub fn plan_generate_video_artcraft_veo_3_fast<'a>(
  }))
 }

+fn plan_aspect_ratio(
+  aspect_ratio: Option<CommonAspectRatio>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<Option<GenerateVeo3FastAspectRatio>, ArtcraftRouterError> {
+  use GenerateVeo3FastAspectRatio as Ar;
+  match aspect_ratio {
+    None
+    | Some(CommonAspectRatio::Auto)
+    | Some(CommonAspectRatio::Auto2k)
+    | Some(CommonAspectRatio::Auto3k)
+    | Some(CommonAspectRatio::Auto4k) => Ok(Some(Ar::Auto)),
+
+    Some(CommonAspectRatio::WideSixteenByNine) | Some(CommonAspectRatio::Wide) => Ok(Some(Ar::SixteenByNine)),
+    Some(CommonAspectRatio::TallNineBySixteen) | Some(CommonAspectRatio::Tall) => Ok(Some(Ar::NineBySixteen)),
+
+    Some(unsupported) => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(ArtcraftRouterError::Client(ClientError::ModelDoesNotSupportOption {
+          field: "aspect_ratio",
+          value: format!("{:?}", unsupported),
+        }))
+      }
+      _ => Ok(Some(Ar::Auto)),
+    },
+  }
+}
+
 fn plan_resolution(
  resolution: Option<CommonResolution>,
  strategy: RequestMismatchMitigationStrategy,
@@ -9,11 +9,22 @@ use fal_client::requests::webhook::video::image::enqueue_veo_2_image_to_video_we
  Veo2AspectRatio, Veo2Duration,
 };

+#[derive(Debug, Clone)]
+pub enum FalVeo2Mode {
+  TextToVideo,
+  ImageToVideo {
+    image_url: String,
+  },
+}
+
 #[derive(Debug, Clone)]
 pub struct PlanFalVeo2 {
  pub prompt: String,
-  pub start_frame_url: String,
-  pub aspect_ratio: Veo2AspectRatio,
+  pub negative_prompt: Option<String>,
+  pub mode: FalVeo2Mode,
+  /// Only set for text-to-video. Image-to-video inherits the source frame's
+  /// aspect ratio and doesn't accept this parameter.
+  pub aspect_ratio: Option<Veo2AspectRatio>,
  pub duration: Veo2Duration,
 }

@@ -22,35 +33,37 @@ pub fn plan_generate_video_fal_veo_2<'a>(
 ) -> Result<VideoGenerationPlan<'a>, ArtcraftRouterError> {
  let strategy = request.request_mismatch_mitigation_strategy;

-  let start_frame_url = resolve_required_image_url(request.start_frame, "start_frame")?;
  if request.end_frame.is_some() {
    return Err(unsupported("end_frame", "Veo 2 does not support an ending frame"));
  }

-  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
+  let mode = match request.start_frame {
+    Some(ImageRef::Url(url)) => FalVeo2Mode::ImageToVideo {
+      image_url: url.to_string(),
+    },
+    Some(ImageRef::MediaFileToken(_)) => {
+      return Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls));
+    }
+    None => FalVeo2Mode::TextToVideo,
+  };
+
+  // Aspect ratio only applies to text-to-video; image-to-video inherits
+  // the source frame's aspect ratio.
+  let aspect_ratio = match &mode {
+    FalVeo2Mode::TextToVideo => Some(plan_aspect_ratio(request.aspect_ratio, strategy)?),
+    FalVeo2Mode::ImageToVideo { .. } => None,
+  };
  let duration = plan_duration(request.duration_seconds, strategy)?;

  Ok(VideoGenerationPlan::FalVeo2(PlanFalVeo2 {
    prompt: request.prompt.unwrap_or("").to_string(),
-    start_frame_url,
+    negative_prompt: request.negative_prompt.map(|s| s.to_string()),
+    mode,
    aspect_ratio,
    duration,
  }))
 }

-fn resolve_required_image_url(
-  image_ref: Option<ImageRef<'_>>,
-  field: &'static str,
-) -> Result<String, ArtcraftRouterError> {
-  match image_ref {
-    Some(ImageRef::Url(url)) => Ok(url.to_string()),
-    Some(ImageRef::MediaFileToken(_)) => {
-      Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls))
-    }
-    None => Err(unsupported(field, "Veo 2 requires a starting frame")),
-  }
-}
-
 fn plan_aspect_ratio(
  aspect_ratio: Option<CommonAspectRatio>,
  strategy: RequestMismatchMitigationStrategy,
@@ -60,6 +73,7 @@ fn plan_aspect_ratio(
    None
    | Some(CommonAspectRatio::Auto)
    | Some(CommonAspectRatio::Auto2k)
+    | Some(CommonAspectRatio::Auto3k)
    | Some(CommonAspectRatio::Auto4k) => Ok(Ar::Auto),

    Some(CommonAspectRatio::WideSixteenByNine) | Some(CommonAspectRatio::Wide) => Ok(Ar::WideSixteenNine),
@@ -7,16 +7,65 @@ use crate::errors::client_error::ClientError;
 use crate::generate::generate_video::generate_video_request::GenerateVideoRequest;
 use crate::generate::generate_video::video_generation_plan::VideoGenerationPlan;
 use fal_client::requests::webhook::video::image::enqueue_veo_3_image_to_video_webhook::{
-  Veo3AspectRatio, Veo3Duration, Veo3Resolution,
+  Veo3I2vAspectRatio, Veo3I2vDuration, Veo3I2vResolution,
 };
+use fal_client::requests::webhook::video::text::enqueue_veo_3_text_to_video_webhook::{
+  Veo3T2vAspectRatio, Veo3T2vDuration, Veo3T2vResolution,
+};
+
+#[derive(Debug, Clone)]
+pub enum FalVeo3Mode {
+  TextToVideo,
+  ImageToVideo {
+    image_url: String,
+  },
+}
+
+/// Router-level duration shared between both modes.
+#[derive(Debug, Clone, Copy)]
+pub enum FalVeo3Duration {
+  Default,
+  FourSeconds,
+  SixSeconds,
+  EightSeconds,
+}
+
+/// Router-level resolution shared between both modes.
+#[derive(Debug, Clone, Copy)]
+pub enum FalVeo3Resolution {
+  Default,
+  SevenTwentyP,
+  TenEightyP,
+}
+
+/// Router-level aspect ratio for text-to-video only (no Auto, no Square).
+#[derive(Debug, Clone, Copy)]
+pub enum FalVeo3T2vAspectRatio {
+  Default,
+  WideSixteenNine,
+  TallNineSixteen,
+}
+
+/// Router-level aspect ratio for image-to-video only (has Auto, no Square).
+#[derive(Debug, Clone, Copy)]
+pub enum FalVeo3I2vAspectRatio {
+  Auto,
+  WideSixteenNine,
+  TallNineSixteen,
+}

 #[derive(Debug, Clone)]
 pub struct PlanFalVeo3 {
  pub prompt: String,
-  pub start_frame_url: String,
-  pub aspect_ratio: Veo3AspectRatio,
-  pub resolution: Veo3Resolution,
-  pub duration: Veo3Duration,
+  pub negative_prompt: Option<String>,
+  pub mode: FalVeo3Mode,
+  /// Only set for text-to-video. Image-to-video inherits the source frame's
+  /// aspect ratio and uses `i2v_aspect_ratio` instead.
+  pub t2v_aspect_ratio: Option<FalVeo3T2vAspectRatio>,
+  /// Only set for image-to-video.
+  pub i2v_aspect_ratio: Option<FalVeo3I2vAspectRatio>,
+  pub resolution: FalVeo3Resolution,
+  pub duration: FalVeo3Duration,
  pub generate_audio: bool,
 }

@@ -25,58 +74,88 @@ pub fn plan_generate_video_fal_veo_3<'a>(
 ) -> Result<VideoGenerationPlan<'a>, ArtcraftRouterError> {
  let strategy = request.request_mismatch_mitigation_strategy;

-  let start_frame_url = resolve_required_image_url(request.start_frame)?;
  if request.end_frame.is_some() {
    return Err(unsupported("end_frame", "Veo 3 does not support an ending frame"));
  }

-  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
+  let mode = match request.start_frame {
+    Some(ImageRef::Url(url)) => FalVeo3Mode::ImageToVideo {
+      image_url: url.to_string(),
+    },
+    Some(ImageRef::MediaFileToken(_)) => {
+      return Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls));
+    }
+    None => FalVeo3Mode::TextToVideo,
+  };
+
+  let (t2v_aspect_ratio, i2v_aspect_ratio) = match &mode {
+    FalVeo3Mode::TextToVideo => {
+      (Some(plan_t2v_aspect_ratio(request.aspect_ratio, strategy)?), None)
+    }
+    FalVeo3Mode::ImageToVideo { .. } => {
+      (None, Some(plan_i2v_aspect_ratio(request.aspect_ratio, strategy)?))
+    }
+  };
  let resolution = plan_resolution(request.resolution, strategy)?;
  let duration = plan_duration(request.duration_seconds, strategy)?;
  let generate_audio = request.generate_audio.unwrap_or(true);

  Ok(VideoGenerationPlan::FalVeo3(PlanFalVeo3 {
    prompt: request.prompt.unwrap_or("").to_string(),
-    start_frame_url,
-    aspect_ratio,
+    negative_prompt: request.negative_prompt.map(|s| s.to_string()),
+    mode,
+    t2v_aspect_ratio,
+    i2v_aspect_ratio,
    resolution,
    duration,
    generate_audio,
  }))
 }

-fn resolve_required_image_url(
-  image_ref: Option<ImageRef<'_>>,
-) -> Result<String, ArtcraftRouterError> {
-  match image_ref {
-    Some(ImageRef::Url(url)) => Ok(url.to_string()),
-    Some(ImageRef::MediaFileToken(_)) => {
-      Err(ArtcraftRouterError::Client(ClientError::FalOnlySupportsUrls))
-    }
-    None => Err(unsupported("start_frame", "Veo 3 requires a starting frame")),
+/// Text-to-video: only 16:9 and 9:16 (no Auto, no Square).
+fn plan_t2v_aspect_ratio(
+  aspect_ratio: Option<CommonAspectRatio>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<FalVeo3T2vAspectRatio, ArtcraftRouterError> {
+  use FalVeo3T2vAspectRatio as Ar;
+  match aspect_ratio {
+    None => Ok(Ar::Default),
+
+    Some(CommonAspectRatio::WideSixteenByNine) | Some(CommonAspectRatio::Wide) => Ok(Ar::WideSixteenNine),
+    Some(CommonAspectRatio::TallNineBySixteen) | Some(CommonAspectRatio::Tall) => Ok(Ar::TallNineSixteen),
+
+    // Everything else (Auto*, Square, unsupported) → Default (16:9).
+    Some(_) => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(unsupported("aspect_ratio", &format!("{:?}", aspect_ratio.unwrap())))
+      }
+      _ => Ok(Ar::Default),
+    },
  }
 }

-fn plan_aspect_ratio(
+/// Image-to-video: Auto, 16:9, 9:16 (no Square).
+fn plan_i2v_aspect_ratio(
  aspect_ratio: Option<CommonAspectRatio>,
  strategy: RequestMismatchMitigationStrategy,
-) -> Result<Veo3AspectRatio, ArtcraftRouterError> {
-  use Veo3AspectRatio as Ar;
+) -> Result<FalVeo3I2vAspectRatio, ArtcraftRouterError> {
+  use FalVeo3I2vAspectRatio as Ar;
  match aspect_ratio {
    None
    | Some(CommonAspectRatio::Auto)
    | Some(CommonAspectRatio::Auto2k)
-    | Some(CommonAspectRatio::Auto4k) => Ok(Ar::Default),
+    | Some(CommonAspectRatio::Auto3k)
+    | Some(CommonAspectRatio::Auto4k) => Ok(Ar::Auto),

-    Some(CommonAspectRatio::Square) | Some(CommonAspectRatio::SquareHd) => Ok(Ar::Square),
    Some(CommonAspectRatio::WideSixteenByNine) | Some(CommonAspectRatio::Wide) => Ok(Ar::WideSixteenNine),
    Some(CommonAspectRatio::TallNineBySixteen) | Some(CommonAspectRatio::Tall) => Ok(Ar::TallNineSixteen),

-    Some(unsupported_ar) => match strategy {
+    // Everything else (Square, unsupported) → Auto.
+    Some(_) => match strategy {
      RequestMismatchMitigationStrategy::ErrorOut => {
-        Err(unsupported("aspect_ratio", &format!("{:?}", unsupported_ar)))
+        Err(unsupported("aspect_ratio", &format!("{:?}", aspect_ratio.unwrap())))
      }
-      _ => Ok(Ar::Default),
+      _ => Ok(Ar::Auto),
    },
  }
 }
@@ -84,8 +163,8 @@ fn plan_aspect_ratio(
 fn plan_resolution(
  resolution: Option<CommonResolution>,
  strategy: RequestMismatchMitigationStrategy,
-) -> Result<Veo3Resolution, ArtcraftRouterError> {
-  use Veo3Resolution as R;
+) -> Result<FalVeo3Resolution, ArtcraftRouterError> {
+  use FalVeo3Resolution as R;
  match resolution {
    None => Ok(R::Default),
    Some(CommonResolution::SevenTwentyP) => Ok(R::SevenTwentyP),
@@ -103,18 +182,18 @@ fn plan_resolution(
 fn plan_duration(
  duration_seconds: Option<u16>,
  strategy: RequestMismatchMitigationStrategy,
-) -> Result<Veo3Duration, ArtcraftRouterError> {
+) -> Result<FalVeo3Duration, ArtcraftRouterError> {
  match duration_seconds {
-    None => Ok(Veo3Duration::Default),
-    Some(4) => Ok(Veo3Duration::FourSeconds),
-    Some(6) => Ok(Veo3Duration::SixSeconds),
-    Some(8) => Ok(Veo3Duration::EightSeconds),
+    None => Ok(FalVeo3Duration::Default),
+    Some(4) => Ok(FalVeo3Duration::FourSeconds),
+    Some(6) => Ok(FalVeo3Duration::SixSeconds),
+    Some(8) => Ok(FalVeo3Duration::EightSeconds),
    Some(other) => match strategy {
      RequestMismatchMitigationStrategy::ErrorOut => {
        Err(unsupported("duration_seconds", &format!("{}", other)))
      }
-      RequestMismatchMitigationStrategy::PayMoreUpgrade => Ok(Veo3Duration::EightSeconds),
-      RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(Veo3Duration::FourSeconds),
+      RequestMismatchMitigationStrategy::PayMoreUpgrade => Ok(FalVeo3Duration::EightSeconds),
+      RequestMismatchMitigationStrategy::PayLessDowngrade => Ok(FalVeo3Duration::FourSeconds),
    },
  }
 }
@@ -129,9 +208,9 @@ fn unsupported(field: &'static str, value: &str) -> ArtcraftRouterError {
 impl PlanFalVeo3 {
  pub fn duration_seconds_for_cost(&self) -> u64 {
    match self.duration {
-      Veo3Duration::Default | Veo3Duration::EightSeconds => 8,
-      Veo3Duration::SixSeconds => 6,
-      Veo3Duration::FourSeconds => 4,
+      FalVeo3Duration::Default | FalVeo3Duration::EightSeconds => 8,
+      FalVeo3Duration::SixSeconds => 6,
+      FalVeo3Duration::FourSeconds => 4,
    }
  }
 }
@@ -5,14 +5,16 @@ use crate::errors::artcraft_router_error::ArtcraftRouterError;
 use crate::errors::client_error::ClientError;
 use crate::generate::generate_video::generate_video_request::GenerateVideoRequest;
 use crate::generate::generate_video::video_generation_plan::VideoGenerationPlan;
+use crate::api::common_aspect_ratio::CommonAspectRatio;
 use fal_client::requests::webhook::video::image::enqueue_veo_3_fast_image_to_video_webhook::{
-  Veo3FastDuration, Veo3FastResolution,
+  Veo3FastAspectRatio, Veo3FastDuration, Veo3FastResolution,
 };

 #[derive(Debug, Clone)]
 pub struct PlanFalVeo3Fast {
  pub prompt: String,
  pub start_frame_url: String,
+  pub aspect_ratio: Veo3FastAspectRatio,
  pub resolution: Veo3FastResolution,
  pub duration: Veo3FastDuration,
  pub generate_audio: bool,
@@ -28,6 +30,7 @@ pub fn plan_generate_video_fal_veo_3_fast<'a>(
    return Err(unsupported("end_frame", "Veo 3 Fast does not support an ending frame"));
  }

+  let aspect_ratio = plan_aspect_ratio(request.aspect_ratio, strategy)?;
  let resolution = plan_resolution(request.resolution, strategy)?;
  let duration = plan_duration(request.duration_seconds, strategy)?;
  let generate_audio = request.generate_audio.unwrap_or(true);
@@ -35,6 +38,7 @@ pub fn plan_generate_video_fal_veo_3_fast<'a>(
  Ok(VideoGenerationPlan::FalVeo3Fast(PlanFalVeo3Fast {
    prompt: request.prompt.unwrap_or("").to_string(),
    start_frame_url,
+    aspect_ratio,
    resolution,
    duration,
    generate_audio,
@@ -53,6 +57,30 @@ fn resolve_required_image_url(
  }
 }

+fn plan_aspect_ratio(
+  aspect_ratio: Option<CommonAspectRatio>,
+  strategy: RequestMismatchMitigationStrategy,
+) -> Result<Veo3FastAspectRatio, ArtcraftRouterError> {
+  use Veo3FastAspectRatio as Ar;
+  match aspect_ratio {
+    None
+    | Some(CommonAspectRatio::Auto)
+    | Some(CommonAspectRatio::Auto2k)
+    | Some(CommonAspectRatio::Auto3k)
+    | Some(CommonAspectRatio::Auto4k) => Ok(Ar::Auto),
+
+    Some(CommonAspectRatio::WideSixteenByNine) | Some(CommonAspectRatio::Wide) => Ok(Ar::WideSixteenNine),
+    Some(CommonAspectRatio::TallNineBySixteen) | Some(CommonAspectRatio::Tall) => Ok(Ar::TallNineSixteen),
+
+    Some(unsupported_ar) => match strategy {
+      RequestMismatchMitigationStrategy::ErrorOut => {
+        Err(unsupported("aspect_ratio", &format!("{:?}", unsupported_ar)))
+      }
+      _ => Ok(Ar::Auto),
+    },
+  }
+}
+
 fn plan_resolution(
  resolution: Option<CommonResolution>,
  strategy: RequestMismatchMitigationStrategy,
@@ -7,10 +7,6 @@ pub struct Veo2ImageToVideoInput {

  pub prompt: String,

-  /// Options: "auto", "16:9", "9:16"
-  #[serde(skip_serializing_if = "Option::is_none")]
-  pub aspect_ratio: Option<String>,
-
  /// Options: "4s", "6s", "8s"
  #[serde(skip_serializing_if = "Option::is_none")]
  pub duration: Option<String>,
@@ -7,6 +7,10 @@ pub struct Veo3FastImageToVideoInput {

  pub prompt: String,

+  /// Options: "auto", "16:9", "9:16"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub aspect_ratio: Option<String>,
+
  /// Options: "720p", "1080p"
  #[serde(skip_serializing_if = "Option::is_none")]
  pub resolution: Option<String>,
@@ -0,0 +1,34 @@
+use crate::requests::api::fal_request::FalRequest;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize, Default)]
+pub struct Veo2TextToVideoInput {
+  pub prompt: String,
+
+  /// Options: "16:9", "9:16", "1:1"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub aspect_ratio: Option<String>,
+
+  /// Options: "5s", "6s", "7s", "8s"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub duration: Option<String>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub negative_prompt: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Veo2TextToVideoVideoFile {
+  pub url: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Veo2TextToVideoOutput {
+  pub video: Veo2TextToVideoVideoFile,
+}
+
+pub fn veo_2_text_to_video(
+  params: Veo2TextToVideoInput,
+) -> FalRequest<Veo2TextToVideoInput, Veo2TextToVideoOutput> {
+  FalRequest::new("fal-ai/veo2", params)
+}
@@ -0,0 +1,41 @@
+use crate::requests::api::fal_request::FalRequest;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize, Default)]
+pub struct Veo3TextToVideoInput {
+  pub prompt: String,
+
+  /// Options: "16:9", "9:16"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub aspect_ratio: Option<String>,
+
+  /// Options: "720p", "1080p"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub resolution: Option<String>,
+
+  /// Options: "4s", "6s", "8s"
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub duration: Option<String>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub generate_audio: Option<bool>,
+
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub negative_prompt: Option<String>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Veo3TextToVideoVideoFile {
+  pub url: String,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Veo3TextToVideoOutput {
+  pub video: Veo3TextToVideoVideoFile,
+}
+
+pub fn veo_3_text_to_video(
+  params: Veo3TextToVideoInput,
+) -> FalRequest<Veo3TextToVideoInput, Veo3TextToVideoOutput> {
+  FalRequest::new("fal-ai/veo3", params)
+}
@@ -7,5 +7,7 @@ pub mod http_pixverse_v5_text_to_video;
 pub mod http_seedance_1p5_pro_text_to_video;
 pub mod http_sora_2_pro_text_to_video;
 pub mod http_sora_2_text_to_video;
+pub mod http_veo_2_text_to_video;
+pub mod http_veo_3_text_to_video;
 pub mod http_veo_3p1_fast_text_to_video;
 pub mod http_veo_3p1_text_to_video;
@@ -1,21 +1,22 @@
 use crate::creds::fal_api_key::FalApiKey;
 use crate::error::classify_fal_error::classify_fal_error;
 use crate::error::fal_error_plus::FalErrorPlus;
-use crate::requests::traits::fal_request_cost_calculator_trait::{FalRequestCostCalculator, UsdCents};
-use crate::requests::http::video::image::http_veo_2_image_to_video::{veo_2_image_to_video, Veo2ImageToVideoInput};
 use crate::requests::api::webhook_response::WebhookResponse;
+use crate::requests::http::video::image::http_veo_2_image_to_video::{veo_2_image_to_video, Veo2ImageToVideoInput};
+use crate::requests::traits::fal_request_cost_calculator_trait::{FalRequestCostCalculator, UsdCents};
 use reqwest::IntoUrl;

+/// Args for Veo 2 image-to-video. Note: image-to-video does NOT support
+/// aspect_ratio — the output inherits the source image's aspect ratio.
 pub struct Veo2Args<'a, U: IntoUrl, V: IntoUrl> {
  pub image_url: U,
  pub webhook_url: V,
  pub prompt: &'a str,
  pub api_key: &'a FalApiKey,
  pub duration: Veo2Duration,
-  pub aspect_ratio: Veo2AspectRatio,
 }

-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum Veo2Duration {
  Default, // NB: Default is 5 seconds
  FiveSeconds,
@@ -24,6 +25,9 @@ pub enum Veo2Duration {
  EightSeconds,
 }

+/// Aspect ratio enum — used by the text-to-video endpoint only.
+/// Kept here because it's the canonical location that the text-to-video
+/// webhook and the router plan both re-export from.
 #[derive(Copy, Clone, Debug)]
 pub enum Veo2AspectRatio {
  Auto,
@@ -59,22 +63,13 @@ pub async fn enqueue_veo_2_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
    Veo2Duration::SevenSeconds => Some("7s".to_string()),
    Veo2Duration::EightSeconds => Some("8s".to_string()),
  };
-  
-  let aspect_ratio = match args.aspect_ratio {
-    Veo2AspectRatio::Auto => Some("auto".to_string()),
-    Veo2AspectRatio::AutoPreferPortrait => Some("auto_prefer_portrait".to_string()),
-    Veo2AspectRatio::WideSixteenNine => Some("16:9".to_string()),
-    Veo2AspectRatio::TallNineSixteen => Some("9:16".to_string()),
-  };

  let image_url = args.image_url.as_str().to_string();

  let request = Veo2ImageToVideoInput {
    image_url,
    prompt: args.prompt.to_string(),
-    aspect_ratio,
    duration,
-    // Maybe expose these later
  };

  let result = veo_2_image_to_video(request)
@@ -89,26 +84,24 @@ pub async fn enqueue_veo_2_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
 #[cfg(test)]
 mod tests {
  use crate::creds::fal_api_key::FalApiKey;
-  use crate::requests::webhook::video::image::enqueue_veo_2_image_to_video_webhook::{enqueue_veo_2_image_to_video_webhook, Veo2Args, Veo2AspectRatio, Veo2Duration};
+  use crate::requests::webhook::video::image::enqueue_veo_2_image_to_video_webhook::{enqueue_veo_2_image_to_video_webhook, Veo2Args, Veo2Duration};
  use errors::AnyhowResult;
  use std::fs::read_to_string;
+  use test_data::web::image_urls::MOUNTAIN_TREE_IMAGE_URL;

  #[tokio::test]
  #[ignore]
-  async fn test_kling21_pro_video() -> AnyhowResult<()> {
-    let image_url = "https://cdn-2.fakeyou.com/media/3/4/h/f/s/34hfsmt8e38rvne6mwa4pwbxr6292sgy/image_34hfsmt8e38rvne6mwa4pwbxr6292sgy.png";
-
+  async fn test_veo_2_image_to_video() -> AnyhowResult<()> {
    // XXX: Don't commit secrets!
    let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?;

    let api_key = FalApiKey::from_str(&secret);

    let args = Veo2Args {
-      image_url: image_url,
+      image_url: MOUNTAIN_TREE_IMAGE_URL,
      prompt: "a shot of the mountains as the sun sets and reveals the moon and stars",
      api_key: &api_key,
      duration: Veo2Duration::Default,
-      aspect_ratio: Veo2AspectRatio::WideSixteenNine,
      webhook_url: "https://example.com/webhook",
    };

@@ -9,6 +9,7 @@ use reqwest::IntoUrl;
 pub struct Veo3FastArgs<'a, U: IntoUrl, V: IntoUrl> {
  pub prompt: &'a str,
  pub image_url: U,
+  pub aspect_ratio: Veo3FastAspectRatio,
  pub duration: Veo3FastDuration,
  pub api_key: &'a FalApiKey,
  pub resolution: Veo3FastResolution,
@@ -24,6 +25,13 @@ pub enum Veo3FastDuration {
  EightSeconds,
 }

+#[derive(Copy, Clone, Debug)]
+pub enum Veo3FastAspectRatio {
+  Auto,
+  WideSixteenNine, // 16:9
+  TallNineSixteen, // 9:16
+}
+
 #[derive(Copy, Clone, Debug)]
 pub enum Veo3FastResolution {
  Default,
@@ -62,7 +70,13 @@ pub async fn enqueue_veo_3_fast_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
    Veo3FastDuration::EightSeconds => Some("8s".to_string()),
  };
  
-  let resolution= match args.resolution {
+  let aspect_ratio = match args.aspect_ratio {
+    Veo3FastAspectRatio::Auto => Some("auto".to_string()),
+    Veo3FastAspectRatio::WideSixteenNine => Some("16:9".to_string()),
+    Veo3FastAspectRatio::TallNineSixteen => Some("9:16".to_string()),
+  };
+
+  let resolution = match args.resolution {
    Veo3FastResolution::Default => None,
    Veo3FastResolution::SevenTwentyP => Some("720p".to_string()),
    Veo3FastResolution::TenEightyP => Some("1080p".to_string()),
@@ -73,6 +87,7 @@ pub async fn enqueue_veo_3_fast_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
  let request = Veo3FastImageToVideoInput {
    image_url,
    prompt: args.prompt.to_string(),
+    aspect_ratio,
    resolution,
    duration,
    generate_audio: Some(args.generate_audio),
@@ -90,7 +105,7 @@ pub async fn enqueue_veo_3_fast_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
 #[cfg(test)]
 mod tests {
  use crate::creds::fal_api_key::FalApiKey;
-  use crate::requests::webhook::video::image::enqueue_veo_3_fast_image_to_video_webhook::{enqueue_veo_3_fast_image_to_video_webhook, Veo3FastArgs, Veo3FastDuration, Veo3FastResolution};
+  use crate::requests::webhook::video::image::enqueue_veo_3_fast_image_to_video_webhook::{enqueue_veo_3_fast_image_to_video_webhook, Veo3FastArgs, Veo3FastAspectRatio, Veo3FastDuration, Veo3FastResolution};
  use errors::AnyhowResult;
  use std::fs::read_to_string;
  use test_data::web::image_urls::ERNEST_GHOST_TREX_IMAGE_URL;
@@ -109,6 +124,7 @@ mod tests {
      image_url: image_url,
      prompt: "man is standing next to a ghost and t-rex, they begin to chase him as the camera pulls back to show the wider scene",
      api_key: &api_key,
+      aspect_ratio: Veo3FastAspectRatio::WideSixteenNine,
      duration: Veo3FastDuration::EightSeconds,
      generate_audio: true,
      resolution: Veo3FastResolution::TenEightyP,
@@ -9,32 +9,35 @@ use reqwest::IntoUrl;
 pub struct Veo3Args<'a, U: IntoUrl, V: IntoUrl> {
  pub image_url: U,
  pub prompt: &'a str,
-  pub duration: Veo3Duration,
-  pub aspect_ratio: Veo3AspectRatio,
-  pub resolution: Veo3Resolution,
+  pub duration: Veo3I2vDuration,
+  pub aspect_ratio: Veo3I2vAspectRatio,
+  pub resolution: Veo3I2vResolution,
  pub generate_audio: bool,
  pub api_key: &'a FalApiKey,
  pub webhook_url: V,
 }

+/// Duration for Veo 3 image-to-video. Default is 8 seconds.
 #[derive(Copy, Clone, Debug)]
-pub enum Veo3Duration {
+pub enum Veo3I2vDuration {
  Default, // Default is 8 seconds
  FourSeconds,
  SixSeconds,
  EightSeconds,
 }

+/// Aspect ratio for Veo 3 image-to-video.
+/// Supports Auto (inherit source), 16:9, and 9:16. No Square.
 #[derive(Copy, Clone, Debug)]
-pub enum Veo3AspectRatio {
-  Default,
-  WideSixteenNine,
-  TallNineSixteen,
-  Square,
+pub enum Veo3I2vAspectRatio {
+  Auto,
+  WideSixteenNine, // 16:9
+  TallNineSixteen, // 9:16
 }

+/// Resolution for Veo 3 image-to-video.
 #[derive(Copy, Clone, Debug)]
-pub enum Veo3Resolution {
+pub enum Veo3I2vResolution {
  Default,
  SevenTwentyP,
  TenEightyP,
@@ -48,14 +51,14 @@ impl <U: IntoUrl, V: IntoUrl> FalRequestCostCalculator for Veo3Args<'_, U, V> {
    //  For example, a 5s video with audio on will cost $2."

    match (self.duration, self.generate_audio) {
-      (Veo3Duration::FourSeconds, false) => 80,
-      (Veo3Duration::SixSeconds, false) => 120,
-      (Veo3Duration::EightSeconds, false) => 160,
-      (Veo3Duration::Default, false) => 160, // NB: Default is 8 seconds
-      (Veo3Duration::FourSeconds, true) => 160,
-      (Veo3Duration::SixSeconds, true) => 240,
-      (Veo3Duration::EightSeconds, true) => 320,
-      (Veo3Duration::Default, true) => 320, // NB: Default is 8 seconds320
+      (Veo3I2vDuration::FourSeconds, false) => 80,
+      (Veo3I2vDuration::SixSeconds, false) => 120,
+      (Veo3I2vDuration::EightSeconds, false) => 160,
+      (Veo3I2vDuration::Default, false) => 160,
+      (Veo3I2vDuration::FourSeconds, true) => 160,
+      (Veo3I2vDuration::SixSeconds, true) => 240,
+      (Veo3I2vDuration::EightSeconds, true) => 320,
+      (Veo3I2vDuration::Default, true) => 320,
    }
  }
 }
@@ -67,23 +70,22 @@ pub async fn enqueue_veo_3_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
  args: Veo3Args<'_, U, V>
 ) -> Result<WebhookResponse, FalErrorPlus> {
  let duration = match args.duration {
-    Veo3Duration::Default => None,
-    Veo3Duration::FourSeconds => Some("4s".to_string()),
-    Veo3Duration::SixSeconds => Some("6s".to_string()),
-    Veo3Duration::EightSeconds => Some("8s".to_string()),
+    Veo3I2vDuration::Default => None,
+    Veo3I2vDuration::FourSeconds => Some("4s".to_string()),
+    Veo3I2vDuration::SixSeconds => Some("6s".to_string()),
+    Veo3I2vDuration::EightSeconds => Some("8s".to_string()),
  };

  let aspect_ratio = match args.aspect_ratio {
-    Veo3AspectRatio::Default => None,
-    Veo3AspectRatio::WideSixteenNine => Some("16:9".to_string()),
-    Veo3AspectRatio::TallNineSixteen => Some("9:16".to_string()),
-    Veo3AspectRatio::Square => Some("1:1".to_string()),
+    Veo3I2vAspectRatio::Auto => Some("auto".to_string()),
+    Veo3I2vAspectRatio::WideSixteenNine => Some("16:9".to_string()),
+    Veo3I2vAspectRatio::TallNineSixteen => Some("9:16".to_string()),
  };
-  
-  let resolution= match args.resolution {
-    Veo3Resolution::Default => None,
-    Veo3Resolution::SevenTwentyP => Some("720p".to_string()),
-    Veo3Resolution::TenEightyP => Some("1080p".to_string()),
+
+  let resolution = match args.resolution {
+    Veo3I2vResolution::Default => None,
+    Veo3I2vResolution::SevenTwentyP => Some("720p".to_string()),
+    Veo3I2vResolution::TenEightyP => Some("1080p".to_string()),
  };

  let image_url = args.image_url.as_str().to_string();
@@ -109,7 +111,10 @@ pub async fn enqueue_veo_3_image_to_video_webhook<U: IntoUrl, V: IntoUrl>(
 #[cfg(test)]
 mod tests {
  use crate::creds::fal_api_key::FalApiKey;
-  use crate::requests::webhook::video::image::enqueue_veo_3_image_to_video_webhook::{enqueue_veo_3_image_to_video_webhook, Veo3Args, Veo3AspectRatio, Veo3Duration, Veo3Resolution};
+  use crate::requests::webhook::video::image::enqueue_veo_3_image_to_video_webhook::{
+    enqueue_veo_3_image_to_video_webhook, Veo3Args, Veo3I2vAspectRatio, Veo3I2vDuration,
+    Veo3I2vResolution,
+  };
  use errors::AnyhowResult;
  use std::fs::read_to_string;
  use test_data::web::image_urls::TREX_SKELETON_IMAGE_URL;
@@ -117,24 +122,21 @@ mod tests {
  #[tokio::test]
  #[ignore]
  async fn test() -> AnyhowResult<()> {
-    // XXX: Don't commit secrets!
    let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?;
-
    let api_key = FalApiKey::from_str(&secret);

    let args = Veo3Args {
      image_url: TREX_SKELETON_IMAGE_URL,
      prompt: "the t-rex skeleton starts walking towards the camera and roars",
      api_key: &api_key,
-      duration: Veo3Duration::EightSeconds,
-      aspect_ratio: Veo3AspectRatio::WideSixteenNine,
-      resolution: Veo3Resolution::TenEightyP,
+      duration: Veo3I2vDuration::EightSeconds,
+      aspect_ratio: Veo3I2vAspectRatio::WideSixteenNine,
+      resolution: Veo3I2vResolution::TenEightyP,
      generate_audio: true,
      webhook_url: "https://example.com/webhook",
    };

-    let result = enqueue_veo_3_image_to_video_webhook(args).await?;
-
+    let _result = enqueue_veo_3_image_to_video_webhook(args).await?;
    Ok(())
  }
 }
@@ -0,0 +1,103 @@
+use crate::creds::fal_api_key::FalApiKey;
+use crate::error::classify_fal_error::classify_fal_error;
+use crate::error::fal_error_plus::FalErrorPlus;
+use crate::requests::api::webhook_response::WebhookResponse;
+use crate::requests::http::video::text::http_veo_2_text_to_video::{
+  veo_2_text_to_video, Veo2TextToVideoInput,
+};
+use crate::requests::traits::fal_request_cost_calculator_trait::{
+  FalRequestCostCalculator, UsdCents,
+};
+// Re-use the same duration/aspect-ratio enums as image-to-video.
+pub use crate::requests::webhook::video::image::enqueue_veo_2_image_to_video_webhook::{
+  Veo2AspectRatio, Veo2Duration,
+};
+use reqwest::IntoUrl;
+
+pub struct Veo2TextToVideoArgs<'a, V: IntoUrl> {
+  pub prompt: &'a str,
+  pub negative_prompt: Option<&'a str>,
+  pub duration: Veo2Duration,
+  pub aspect_ratio: Veo2AspectRatio,
+  pub webhook_url: V,
+  pub api_key: &'a FalApiKey,
+}
+
+impl<V: IntoUrl> FalRequestCostCalculator for Veo2TextToVideoArgs<'_, V> {
+  fn calculate_cost_in_cents(&self) -> UsdCents {
+    // Same pricing as image-to-video:
+    // "For 5s video your request will cost $2.50.
+    // For every additional second you will be charged $0.50."
+    match self.duration {
+      Veo2Duration::Default => 250,
+      Veo2Duration::FiveSeconds => 250,
+      Veo2Duration::SixSeconds => 300,
+      Veo2Duration::SevenSeconds => 350,
+      Veo2Duration::EightSeconds => 400,
+    }
+  }
+}
+
+/// Veo 2 Text-to-Video
+/// https://fal.ai/models/fal-ai/veo2
+pub async fn enqueue_veo_2_text_to_video_webhook<V: IntoUrl>(
+  args: Veo2TextToVideoArgs<'_, V>,
+) -> Result<WebhookResponse, FalErrorPlus> {
+  let duration = match args.duration {
+    Veo2Duration::Default => None,
+    Veo2Duration::FiveSeconds => Some("5s".to_string()),
+    Veo2Duration::SixSeconds => Some("6s".to_string()),
+    Veo2Duration::SevenSeconds => Some("7s".to_string()),
+    Veo2Duration::EightSeconds => Some("8s".to_string()),
+  };
+
+  let aspect_ratio = match args.aspect_ratio {
+    Veo2AspectRatio::Auto => None, // Let the API default (16:9)
+    Veo2AspectRatio::AutoPreferPortrait => Some("9:16".to_string()),
+    Veo2AspectRatio::WideSixteenNine => Some("16:9".to_string()),
+    Veo2AspectRatio::TallNineSixteen => Some("9:16".to_string()),
+  };
+
+  let request = Veo2TextToVideoInput {
+    prompt: args.prompt.to_string(),
+    aspect_ratio,
+    duration,
+    negative_prompt: args.negative_prompt.map(|s| s.to_string()),
+  };
+
+  let result = veo_2_text_to_video(request)
+    .with_api_key(&args.api_key.0)
+    .queue_webhook(args.webhook_url)
+    .await;
+
+  result.map_err(|err| classify_fal_error(err))
+}
+
+#[cfg(test)]
+mod tests {
+  use crate::creds::fal_api_key::FalApiKey;
+  use crate::requests::webhook::video::text::enqueue_veo_2_text_to_video_webhook::{
+    enqueue_veo_2_text_to_video_webhook, Veo2TextToVideoArgs, Veo2AspectRatio, Veo2Duration,
+  };
+  use errors::AnyhowResult;
+  use std::fs::read_to_string;
+
+  #[tokio::test]
+  #[ignore]
+  async fn test_veo_2_text_to_video() -> AnyhowResult<()> {
+    let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?;
+    let api_key = FalApiKey::from_str(&secret);
+
+    let args = Veo2TextToVideoArgs {
+      prompt: "a drone shot of a coastal sunset with waves crashing on rocks",
+      negative_prompt: None,
+      api_key: &api_key,
+      duration: Veo2Duration::FiveSeconds,
+      aspect_ratio: Veo2AspectRatio::WideSixteenNine,
+      webhook_url: "https://example.com/webhook",
+    };
+
+    let _result = enqueue_veo_2_text_to_video_webhook(args).await?;
+    Ok(())
+  }
+}
@@ -0,0 +1,137 @@
+use crate::creds::fal_api_key::FalApiKey;
+use crate::error::classify_fal_error::classify_fal_error;
+use crate::error::fal_error_plus::FalErrorPlus;
+use crate::requests::api::webhook_response::WebhookResponse;
+use crate::requests::http::video::text::http_veo_3_text_to_video::{
+  veo_3_text_to_video, Veo3TextToVideoInput,
+};
+use crate::requests::traits::fal_request_cost_calculator_trait::{
+  FalRequestCostCalculator, UsdCents,
+};
+use reqwest::IntoUrl;
+
+pub struct Veo3TextToVideoArgs<'a, V: IntoUrl> {
+  pub prompt: &'a str,
+  pub negative_prompt: Option<&'a str>,
+  pub duration: Veo3T2vDuration,
+  pub aspect_ratio: Veo3T2vAspectRatio,
+  pub resolution: Veo3T2vResolution,
+  pub generate_audio: bool,
+  pub webhook_url: V,
+  pub api_key: &'a FalApiKey,
+}
+
+/// Duration for Veo 3 text-to-video. Default is 8 seconds.
+#[derive(Copy, Clone, Debug)]
+pub enum Veo3T2vDuration {
+  Default, // Default is 8 seconds
+  FourSeconds,
+  SixSeconds,
+  EightSeconds,
+}
+
+/// Aspect ratio for Veo 3 text-to-video.
+/// Only 16:9 and 9:16 are supported. No Auto, no Square.
+#[derive(Copy, Clone, Debug)]
+pub enum Veo3T2vAspectRatio {
+  Default, // Default is 16:9
+  WideSixteenNine, // 16:9
+  TallNineSixteen, // 9:16
+}
+
+/// Resolution for Veo 3 text-to-video.
+#[derive(Copy, Clone, Debug)]
+pub enum Veo3T2vResolution {
+  Default,
+  SevenTwentyP,
+  TenEightyP,
+}
+
+impl<V: IntoUrl> FalRequestCostCalculator for Veo3TextToVideoArgs<'_, V> {
+  fn calculate_cost_in_cents(&self) -> UsdCents {
+    // $0.20/sec audio off, $0.40/sec audio on.
+    match (self.duration, self.generate_audio) {
+      (Veo3T2vDuration::FourSeconds, false) => 80,
+      (Veo3T2vDuration::SixSeconds, false) => 120,
+      (Veo3T2vDuration::EightSeconds, false) => 160,
+      (Veo3T2vDuration::Default, false) => 160,
+      (Veo3T2vDuration::FourSeconds, true) => 160,
+      (Veo3T2vDuration::SixSeconds, true) => 240,
+      (Veo3T2vDuration::EightSeconds, true) => 320,
+      (Veo3T2vDuration::Default, true) => 320,
+    }
+  }
+}
+
+/// Veo 3 Text-to-Video
+/// https://fal.ai/models/fal-ai/veo3
+pub async fn enqueue_veo_3_text_to_video_webhook<V: IntoUrl>(
+  args: Veo3TextToVideoArgs<'_, V>,
+) -> Result<WebhookResponse, FalErrorPlus> {
+  let duration = match args.duration {
+    Veo3T2vDuration::Default => None,
+    Veo3T2vDuration::FourSeconds => Some("4s".to_string()),
+    Veo3T2vDuration::SixSeconds => Some("6s".to_string()),
+    Veo3T2vDuration::EightSeconds => Some("8s".to_string()),
+  };
+
+  let aspect_ratio = match args.aspect_ratio {
+    Veo3T2vAspectRatio::Default => None,
+    Veo3T2vAspectRatio::WideSixteenNine => Some("16:9".to_string()),
+    Veo3T2vAspectRatio::TallNineSixteen => Some("9:16".to_string()),
+  };
+
+  let resolution = match args.resolution {
+    Veo3T2vResolution::Default => None,
+    Veo3T2vResolution::SevenTwentyP => Some("720p".to_string()),
+    Veo3T2vResolution::TenEightyP => Some("1080p".to_string()),
+  };
+
+  let request = Veo3TextToVideoInput {
+    prompt: args.prompt.to_string(),
+    aspect_ratio,
+    resolution,
+    duration,
+    generate_audio: Some(args.generate_audio),
+    negative_prompt: args.negative_prompt.map(|s| s.to_string()),
+  };
+
+  let result = veo_3_text_to_video(request)
+    .with_api_key(&args.api_key.0)
+    .queue_webhook(args.webhook_url)
+    .await;
+
+  result.map_err(|err| classify_fal_error(err))
+}
+
+#[cfg(test)]
+mod tests {
+  use crate::creds::fal_api_key::FalApiKey;
+  use crate::requests::webhook::video::text::enqueue_veo_3_text_to_video_webhook::{
+    enqueue_veo_3_text_to_video_webhook, Veo3TextToVideoArgs, Veo3T2vAspectRatio,
+    Veo3T2vDuration, Veo3T2vResolution,
+  };
+  use errors::AnyhowResult;
+  use std::fs::read_to_string;
+
+  #[tokio::test]
+  #[ignore]
+  async fn test_veo_3_text_to_video() -> AnyhowResult<()> {
+    let secret = read_to_string("/Users/bt/Artcraft/credentials/fal_api_key.txt")?;
+    let api_key = FalApiKey::from_str(&secret);
+
+    let args = Veo3TextToVideoArgs {
+      prompt: "a drone shot of a coastal sunset with waves crashing on rocks",
+      negative_prompt: None,
+      api_key: &api_key,
+      duration: Veo3T2vDuration::EightSeconds,
+      aspect_ratio: Veo3T2vAspectRatio::WideSixteenNine,
+      resolution: Veo3T2vResolution::TenEightyP,
+      generate_audio: true,
+      webhook_url: "https://example.com/webhook",
+    };
+
+    let _result = enqueue_veo_3_text_to_video_webhook(args).await?;
+    Ok(())
+  }
+}
@@ -7,5 +7,7 @@ pub mod enqueue_pixverse_v5_text_to_video_webhook;
 pub mod enqueue_seedance_1p5_pro_text_to_video_webhook;
 pub mod enqueue_sora_2_pro_text_to_video_webhook;
 pub mod enqueue_sora_2_text_to_video_webhook;
+pub mod enqueue_veo_2_text_to_video_webhook;
+pub mod enqueue_veo_3_text_to_video_webhook;
 pub mod enqueue_veo_3p1_fast_text_to_video_webhook;
 pub mod enqueue_veo_3p1_text_to_video_webhook;
@@ -41,6 +41,7 @@ pub (super) async fn handle_artcraft_veo3_fast(
    generate_audio: request.generate_audio,
    duration: None, // TODO: Parameterize
    resolution: None, // TODO: Parameterize
+    aspect_ratio: None, // TODO: Parameterize
  };
  
  let result = generate_veo_3_fast_image_to_video(
@@ -1,4 +1,4 @@

 /// The version of the ArtCraft desktop app reported in the UI and via Analytics.
 /// This should match the CI builds.
-pub const ARTCRAFT_VERSION: &str = "0.27.0";
+pub const ARTCRAFT_VERSION: &str = "0.28.0";
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2.0.0-rc",
  "productName": "ArtCraft",
-  "version": "0.27.0",
+  "version": "0.28.0",
  "identifier": "ai.artcraft.app",
  "build": {
    "frontendDist": "../../../frontend/apps/artcraft/dist",
@@ -1,7 +1,7 @@
 {
  "$schema": "https://schema.tauri.app/config/2.0.0-rc",
  "productName": "ArtCraft",
-  "version": "0.27.0",
+  "version": "0.28.0",
  "identifier": "ai.artcraft.app",
  "build": {
    "frontendDist": "../../../frontend/apps/artcraft/dist",
@@ -0,0 +1,16 @@
+[package]
+name = "error_utils"
+edition = "2021"
+version = "0.0.1"
+authors = [
+    "Brandon Thomas <bt@brand.io>",
+    "Brandon Thomas <echelon@gmail.com>",
+]
+publish = false
+
+[lib]
+name = "error_utils"
+path = "src/lib.rs"
+
+[dependencies]
+regex.workspace = true
@@ -0,0 +1 @@
+pub mod try_error_name;
@@ -0,0 +1,157 @@
+use regex::Regex;
+use std::sync::LazyLock;
+
+/// Regex that matches CamelCase type names with an optional `::Variant` suffix.
+/// E.g. `CommonWebError::InvalidRequest`, `EnvError`, `KinoviError::RequestError`.
+static ERROR_NAME_RE: LazyLock<Regex> = LazyLock::new(|| {
+  Regex::new(r"[A-Z][0-9a-z]+(?:[A-Z][0-9a-z]+)*(?:::[A-Z][0-9a-z]+(?:[A-Z][0-9a-z]+)*)?")
+      .expect("error name regex should compile")
+});
+
+/// Try to extract a human-readable error title from the causal error's Debug
+/// representation. Looks for CamelCase type names like `EnvError::NotUnicode`.
+pub fn try_error_name(error: &dyn std::error::Error) -> Option<String> {
+  let debug_str = format!("{:?}", error);
+  try_extract_error_name(&debug_str)
+}
+
+/// Extract the leading CamelCase error name (with optional `::Variant`) from
+/// a Debug-formatted error string. Returns `None` if no match is found.
+///
+/// ```text
+/// "CommonWebError::InvalidRequest(\"bad\")" → Some("CommonWebError::InvalidRequest")
+/// "EnvError::ParseError { reason: \"foo\" }" → Some("EnvError::ParseError")
+/// "just a plain string"                      → None
+/// ```
+pub (crate) fn try_extract_error_name(debug_str: &str) -> Option<String> {
+  ERROR_NAME_RE.find(debug_str)
+      .map(|m| m.as_str().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  // --- try_extract_error_name tests ---
+
+  #[test]
+  fn extract_just_error_name() {
+    assert_eq!(
+      try_extract_error_name("JustErrorName"),
+      Some("JustErrorName".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_variant_and_string_payload() {
+    assert_eq!(
+      try_extract_error_name(r#"CommonWebError::InvalidRequest("Invalid request")"#),
+      Some("CommonWebError::InvalidRequest".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_unit_variant() {
+    assert_eq!(
+      try_extract_error_name("EnvError::NotUnicode"),
+      Some("EnvError::NotUnicode".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_struct_payload() {
+    assert_eq!(
+      try_extract_error_name(r#"EnvError::ParseError { reason: "foo" }"#),
+      Some("EnvError::ParseError".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_tuple_payload() {
+    assert_eq!(
+      try_extract_error_name("KinoviError::RequestError(asdf)"),
+      Some("KinoviError::RequestError".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_nested_errors() {
+    assert_eq!(
+      try_extract_error_name(
+        "ComplexError::SomeError(SomeError::SomeVariant(SomeInnerError::SomeInnerVariant))"
+      ),
+      Some("ComplexError::SomeError".to_string()),
+    );
+  }
+
+  #[test]
+  fn extract_error_with_struct_containing_nested() {
+    assert_eq!(
+      try_extract_error_name(
+        "WrappedError::Variant { inner: SomeInnerError::SomeInnerVariant }"
+      ),
+      Some("WrappedError::Variant".to_string()),
+    );
+  }
+
+  #[test]
+  fn no_match_for_lowercase_string() {
+    assert_eq!(
+      try_extract_error_name("just a plain error message with no type name"),
+      None,
+    );
+  }
+
+  #[test]
+  fn no_match_for_empty_string() {
+    assert_eq!(try_extract_error_name(""), None);
+  }
+
+  #[test]
+  fn single_word_camel_case() {
+    assert_eq!(
+      try_extract_error_name("Error"),
+      Some("Error".to_string()),
+    );
+  }
+
+  // --- try_error_title tests (with real error types) ---
+
+  #[test]
+  fn title_from_io_error() {
+    let err: Box<dyn std::error::Error> = Box::new(
+      std::io::Error::new(std::io::ErrorKind::NotFound, "file not found"),
+    );
+    let title = try_error_name(err.as_ref());
+    assert!(title.is_some());
+  }
+
+  /// A simple custom error for testing.
+  #[derive(Debug)]
+  enum TestAppError {
+    DatabaseTimeout,
+    InvalidInput(String),
+  }
+
+  impl std::fmt::Display for TestAppError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+      write!(f, "{:?}", self)
+    }
+  }
+
+  impl std::error::Error for TestAppError {}
+
+  #[test]
+  fn title_from_custom_unit_variant() {
+    let err = TestAppError::DatabaseTimeout;
+    let title = try_error_name(&err);
+    assert_eq!(title, Some("DatabaseTimeout".to_string()));
+  }
+
+  #[test]
+  fn title_from_custom_tuple_variant() {
+    let err = TestAppError::InvalidInput("bad data".to_string());
+    let title = try_error_name(&err);
+    assert_eq!(title, Some("InvalidInput".to_string()));
+  }
+}
@@ -0,0 +1,20 @@
+[package]
+name = "opaque_cursors"
+edition = "2021"
+version = "0.0.1"
+authors = [
+    "Brandon Thomas <bt@brand.io>",
+    "Brandon Thomas <echelon@gmail.com>",
+]
+publish = false
+
+[lib]
+name = "opaque_cursors"
+path = "src/lib.rs"
+
+[dependencies]
+base64.workspace = true
+magic-crypt = "3.1.13"
+serde.workspace = true
+serde_derive.workspace = true
+serde_json.workspace = true
@@ -0,0 +1,2 @@
+pub mod v1;
+pub mod v2;
@@ -0,0 +1 @@
+// Reserved for migrating the legacy SortKeyCrypto / SortId from storyteller-web.
@@ -0,0 +1,3 @@
+pub mod opaque_cursor_encoder_v2;
+pub mod opaque_cursor_error_v2;
+pub mod opaque_cursor_v2;
@@ -0,0 +1,243 @@
+use std::io::Cursor;
+
+use base64::alphabet::{Alphabet, URL_SAFE};
+use base64::engine::{DecodePaddingMode, GeneralPurpose, GeneralPurposeConfig};
+use base64::Engine;
+use magic_crypt::generic_array::typenum::U256;
+use magic_crypt::{MagicCrypt256, MagicCryptTrait, new_magic_crypt};
+
+use crate::v2::opaque_cursor_error_v2::OpaqueCursorErrorV2;
+use crate::v2::opaque_cursor_v2::OpaqueCursorV2;
+
+/// Encrypts and decrypts opaque cursor payloads so that internal database
+/// IDs are never leaked to the frontend.
+#[derive(Clone)]
+pub struct OpaqueCursorEncoderV2 {
+  crypt: MagicCrypt256,
+  alphabet: Alphabet,
+  base64_config: GeneralPurposeConfig,
+}
+
+impl OpaqueCursorEncoderV2 {
+  pub fn new(secret: &str) -> Self {
+    let base64_config = GeneralPurposeConfig::new()
+        .with_encode_padding(false)
+        .with_decode_allow_trailing_bits(true)
+        .with_decode_padding_mode(DecodePaddingMode::Indifferent);
+
+    Self {
+      crypt: new_magic_crypt!(secret, 256),
+      alphabet: URL_SAFE,
+      base64_config,
+    }
+  }
+
+  /// Encode a last-id cursor into an opaque string.
+  pub fn encode_last_id_cursor(&self, name: &str, id: u64) -> Result<String, OpaqueCursorErrorV2> {
+    let cursor = OpaqueCursorV2 {
+      name: Some(name.to_string()),
+      last_id: Some(id),
+    };
+    self.encode_cursor(&cursor)
+  }
+
+  /// Encode an arbitrary cursor payload into an opaque string.
+  pub fn encode_cursor(&self, cursor: &OpaqueCursorV2) -> Result<String, OpaqueCursorErrorV2> {
+    let json = serde_json::to_string(cursor)?;
+
+    let engine = GeneralPurpose::new(&self.alphabet, self.base64_config);
+
+    let mut reader = Cursor::new(json);
+    let mut writer = Vec::new();
+
+    self.crypt.encrypt_reader_to_writer2::<U256>(&mut reader, &mut writer)?;
+
+    Ok(engine.encode(&writer))
+  }
+
+  /// Decode an opaque cursor string and verify the name matches `expected_name`.
+  pub fn decode_cursor_expecting_name(
+    &self,
+    expected_name: &str,
+    cursor: &str,
+  ) -> Result<OpaqueCursorV2, OpaqueCursorErrorV2> {
+    let decoded = self.decode_cursor(cursor)?;
+
+    match &decoded.name {
+      None => Err(OpaqueCursorErrorV2::DecodedNameNotPresent),
+      Some(actual) if actual != expected_name => {
+        Err(OpaqueCursorErrorV2::DecodedNameMismatch {
+          expected: expected_name.to_string(),
+          actual: actual.clone(),
+        })
+      }
+      _ => Ok(decoded),
+    }
+  }
+
+  /// Decode an opaque cursor string back into a cursor payload.
+  pub fn decode_cursor(&self, cursor: &str) -> Result<OpaqueCursorV2, OpaqueCursorErrorV2> {
+    let engine = GeneralPurpose::new(&self.alphabet, self.base64_config);
+
+    let decoded_bytes = engine.decode(cursor)?;
+    let decrypted_bytes = self.crypt.decrypt_bytes_to_bytes(&decoded_bytes)?;
+
+    let json = String::from_utf8(decrypted_bytes)?;
+    let cursor = serde_json::from_str::<OpaqueCursorV2>(&json)?;
+
+    Ok(cursor)
+  }
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+
+  const SECRET: &str = "test_secret_key_for_opaque_cursors";
+
+  #[test]
+  fn roundtrip_last_id() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("test", 42).unwrap();
+    let decoded = encoder.decode_cursor(&encoded).unwrap();
+    assert_eq!(decoded.name, Some("test".to_string()));
+    assert_eq!(decoded.last_id, Some(42));
+  }
+
+  #[test]
+  fn roundtrip_none_fields() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let cursor = OpaqueCursorV2 { name: None, last_id: None };
+    let encoded = encoder.encode_cursor(&cursor).unwrap();
+    let decoded = encoder.decode_cursor(&encoded).unwrap();
+    assert_eq!(decoded.name, None);
+    assert_eq!(decoded.last_id, None);
+  }
+
+  #[test]
+  fn roundtrip_zero() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("zero", 0).unwrap();
+    let decoded = encoder.decode_cursor(&encoded).unwrap();
+    assert_eq!(decoded.name, Some("zero".to_string()));
+    assert_eq!(decoded.last_id, Some(0));
+  }
+
+  #[test]
+  fn roundtrip_large_id() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("big", u64::MAX).unwrap();
+    let decoded = encoder.decode_cursor(&encoded).unwrap();
+    assert_eq!(decoded.last_id, Some(u64::MAX));
+  }
+
+  #[test]
+  fn roundtrip_many_ids() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    for id in [0, 1, 100, 999, 100_000, 1_000_000_000, u64::MAX - 1] {
+      let encoded = encoder.encode_last_id_cursor("batch", id).unwrap();
+      let decoded = encoder.decode_cursor(&encoded).unwrap();
+      assert_eq!(decoded.name, Some("batch".to_string()));
+      assert_eq!(decoded.last_id, Some(id), "roundtrip failed for id={}", id);
+    }
+  }
+
+  #[test]
+  fn name_preserved_in_roundtrip() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("media_files_list", 999).unwrap();
+    let decoded = encoder.decode_cursor(&encoded).unwrap();
+    assert_eq!(decoded.name, Some("media_files_list".to_string()));
+    assert_eq!(decoded.last_id, Some(999));
+  }
+
+  #[test]
+  fn stable_cursor() {
+    let encoder = OpaqueCursorEncoderV2::new("stable_secret");
+    let encoded = encoder.encode_last_id_cursor("media_files_list", 123456).unwrap();
+    assert_eq!(encoded, "0-8bNhoOVA37eZAKwVQ0B8kWq-HLs0x0gQc51TJXjw2hWJ7PNfVqas7WvRnIK80O");
+  }
+
+  #[test]
+  fn different_secrets_produce_different_output() {
+    let encoder_a = OpaqueCursorEncoderV2::new("secret_a");
+    let encoder_b = OpaqueCursorEncoderV2::new("secret_b");
+
+    let encoded_a = encoder_a.encode_last_id_cursor("test", 42).unwrap();
+    let encoded_b = encoder_b.encode_last_id_cursor("test", 42).unwrap();
+
+    assert_ne!(encoded_a, encoded_b);
+  }
+
+  #[test]
+  fn wrong_secret_fails_to_decode() {
+    let encoder_a = OpaqueCursorEncoderV2::new("secret_a");
+    let encoder_b = OpaqueCursorEncoderV2::new("secret_b");
+
+    let encoded = encoder_a.encode_last_id_cursor("test", 42).unwrap();
+    let result = encoder_b.decode_cursor(&encoded);
+
+    assert!(result.is_err());
+  }
+
+  #[test]
+  fn invalid_base64_fails() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let result = encoder.decode_cursor("!!!not-valid-base64!!!");
+    assert!(result.is_err());
+  }
+
+  #[test]
+  fn empty_string_fails() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let result = encoder.decode_cursor("");
+    assert!(result.is_err());
+  }
+
+  #[test]
+  fn encoded_cursor_is_url_safe() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    for id in [0, 1, 42, 999_999_999] {
+      let encoded = encoder.encode_last_id_cursor("safe", id).unwrap();
+      assert!(
+        encoded.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_'),
+        "non-URL-safe character in cursor: {:?}",
+        encoded,
+      );
+    }
+  }
+
+  #[test]
+  fn decode_expecting_name_matches() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("my_list", 100).unwrap();
+    let decoded = encoder.decode_cursor_expecting_name("my_list", &encoded).unwrap();
+    assert_eq!(decoded.name, Some("my_list".to_string()));
+    assert_eq!(decoded.last_id, Some(100));
+  }
+
+  #[test]
+  fn decode_expecting_name_mismatch() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let encoded = encoder.encode_last_id_cursor("wrong_name", 100).unwrap();
+    let result = encoder.decode_cursor_expecting_name("expected_name", &encoded);
+    assert!(matches!(result, Err(OpaqueCursorErrorV2::DecodedNameMismatch { .. })));
+  }
+
+  #[test]
+  fn decode_expecting_name_not_present() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let cursor = OpaqueCursorV2 { name: None, last_id: Some(42) };
+    let encoded = encoder.encode_cursor(&cursor).unwrap();
+    let result = encoder.decode_cursor_expecting_name("anything", &encoded);
+    assert!(matches!(result, Err(OpaqueCursorErrorV2::DecodedNameNotPresent)));
+  }
+
+  #[test]
+  fn deterministic_output() {
+    let encoder = OpaqueCursorEncoderV2::new(SECRET);
+    let a = encoder.encode_last_id_cursor("det", 42).unwrap();
+    let b = encoder.encode_last_id_cursor("det", 42).unwrap();
+    assert_eq!(a, b);
+  }
+}
@@ -0,0 +1,48 @@
+use std::fmt;
+use std::string::FromUtf8Error;
+
+use magic_crypt::MagicCryptError;
+
+#[derive(Debug)]
+pub enum OpaqueCursorErrorV2 {
+  SerdeError(serde_json::Error),
+  MagicCryptError(MagicCryptError),
+  Base64DecodeError(base64::DecodeError),
+  Utf8Error(FromUtf8Error),
+  /// The decoded cursor did not contain a name at all.
+  DecodedNameNotPresent,
+  /// The decoded cursor's name did not match the expected name.
+  DecodedNameMismatch { expected: String, actual: String },
+}
+
+impl fmt::Display for OpaqueCursorErrorV2 {
+  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    write!(f, "{:?}", self)
+  }
+}
+
+impl std::error::Error for OpaqueCursorErrorV2 {}
+
+impl From<serde_json::Error> for OpaqueCursorErrorV2 {
+  fn from(err: serde_json::Error) -> Self {
+    Self::SerdeError(err)
+  }
+}
+
+impl From<MagicCryptError> for OpaqueCursorErrorV2 {
+  fn from(err: MagicCryptError) -> Self {
+    Self::MagicCryptError(err)
+  }
+}
+
+impl From<base64::DecodeError> for OpaqueCursorErrorV2 {
+  fn from(err: base64::DecodeError) -> Self {
+    Self::Base64DecodeError(err)
+  }
+}
+
+impl From<FromUtf8Error> for OpaqueCursorErrorV2 {
+  fn from(err: FromUtf8Error) -> Self {
+    Self::Utf8Error(err)
+  }
+}
@@ -0,0 +1,19 @@
+use serde_derive::{Deserialize, Serialize};
+
+/// An opaque cursor payload that encodes pagination state.
+///
+/// This gets encrypted and sent to the frontend as an opaque handle.
+/// The frontend cannot read or forge these cursors.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OpaqueCursorV2 {
+  /// Name for the cursor type.
+  #[serde(skip_serializing_if = "Option::is_none")]
+  #[serde(rename = "n")]
+  pub name: Option<String>,
+
+  /// The id of the last ordered element we fetched, so the next page
+  /// will start after (or before) this id depending on sort direction.
+  #[serde(skip_serializing_if = "Option::is_none")]
+  #[serde(rename = "l")]
+  pub last_id: Option<u64>,
+}
@@ -0,0 +1,79 @@
+# mysql_queries
+
+SQLx-based MySQL queries for the storyteller-web backend and background jobs.
+
+## Building
+
+```
+SQLX_OFFLINE=true cargo check -p mysql_queries
+```
+
+The `SQLX_OFFLINE=true` env var is **required** for compilation. This crate uses the sqlx
+offline cache (`.sqlx/` directory at the workspace root) to validate queries at compile time
+without a live database connection.
+
+## Query Style
+
+### Prefer `sqlx::query!` and `sqlx::query_as!` macros
+
+Always use the compile-time checked `sqlx::query!` and `sqlx::query_as!` macros over the
+runtime `sqlx::query()` and `sqlx::query_as()` functions. The macros validate SQL syntax,
+column names, and parameter types against the offline cache at compile time.
+
+```rust
+// PREFERRED: compile-time checked
+sqlx::query!(
+  r#"INSERT INTO my_table SET token = ?, name = ?"#,
+  token,
+  name,
+)
+  .execute(args.mysql_executor)
+  .await?;
+
+// AVOID: runtime only, no compile-time checking
+sqlx::query(r#"INSERT INTO my_table SET token = ?, name = ?"#)
+  .bind(token)
+  .bind(name)
+  .execute(args.mysql_executor)
+  .await?;
+```
+
+Use runtime `sqlx::query()` only when:
+- The query involves a table not yet in the offline cache and you cannot run `cargo sqlx prepare`
+- The query is dynamically constructed (rare)
+- SELECT queries for new tables where column type metadata isn't cached yet
+
+### Offline Cache
+
+When adding new queries for **existing tables**, the `.sqlx/` cache should already have the
+schema metadata. For **new tables**, you may need to:
+
+1. Run the migration against a real database
+2. Run `cargo sqlx prepare` to regenerate the cache
+3. Or manually create cache entries for simple INSERT/UPDATE queries (they only need parameter count)
+
+### Table Conventions
+
+- Primary key `id` columns must be `BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT`. Do not use signed IDs.
+- Always create tables with `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin`.
+
+### Error Types
+
+New queries should return `Result<T, sqlx::Error>` instead of the legacy `AnyhowResult<T>`.
+The `AnyhowResult` pattern is being phased out.
+
+### Transaction Support
+
+Use the executor-generic `Args` pattern for queries that need to work inside transactions:
+
+```rust
+pub struct MyQueryArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  pub field: &'a str,
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
+}
+```
+
+This allows the same query function to accept both `&MySqlPool` and `&mut Transaction`.
@@ -27,12 +27,14 @@ pub mod model_weights;
 pub mod prompt_context_items;
 pub mod prompts;
 pub mod public_event_feed;
+pub mod staff_audit_logs;
 pub mod stats;
 pub mod tags;
 pub mod trending_model_analytics;
 pub mod tts;
 pub mod twitch;
 pub mod unsubscribe_reason;
+pub mod user_impersonation_requests;
 pub mod users;
 pub mod vocoder;
 pub mod voice_clone_requests;
@@ -0,0 +1,54 @@
+use std::marker::PhantomData;
+
+use sqlx::{Executor, MySql};
+
+use enums::by_table::staff_audit_logs::staff_audit_action::StaffAuditAction;
+use enums::by_table::staff_audit_logs::staff_audit_entity_type::StaffAuditEntityType;
+use tokens::tokens::staff_audit_logs::StaffAuditLogToken;
+use tokens::tokens::users::UserToken;
+
+pub struct InsertStaffAuditLogArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  pub audit_action: StaffAuditAction,
+
+  pub maybe_entity_type: Option<StaffAuditEntityType>,
+  pub maybe_entity_token: Option<&'a str>,
+
+  pub staff_user_token: &'a UserToken,
+  pub actor_ip_address: &'a str,
+
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
+}
+
+pub async fn insert_staff_audit_log<'a, 'c, E>(
+  args: InsertStaffAuditLogArgs<'a, 'c, E>,
+) -> Result<StaffAuditLogToken, sqlx::Error>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  let token = StaffAuditLogToken::generate();
+
+  sqlx::query!(
+    r#"
+INSERT INTO staff_audit_logs
+SET
+  token = ?,
+  audit_action = ?,
+  maybe_entity_type = ?,
+  maybe_entity_token = ?,
+  staff_user_token = ?,
+  staff_ip_address = ?
+    "#,
+    token.as_str(),
+    args.audit_action.to_str(),
+    args.maybe_entity_type.map(|ty| ty.to_str()),
+    args.maybe_entity_token,
+    args.staff_user_token.as_str(),
+    args.actor_ip_address,
+  )
+    .execute(args.mysql_executor)
+    .await?;
+
+  Ok(token)
+}
@@ -0,0 +1,96 @@
+use chrono::{DateTime, Utc};
+use sqlx::MySqlPool;
+
+use tokens::tokens::staff_audit_logs::StaffAuditLogToken;
+use tokens::tokens::users::UserToken;
+
+pub struct StaffAuditLogListItem {
+  pub id: u64,
+  pub token: StaffAuditLogToken,
+  pub audit_action: String,
+  pub maybe_entity_type: Option<String>,
+  pub maybe_entity_token: Option<String>,
+  pub maybe_target_username: Option<String>,
+  pub maybe_target_display_name: Option<String>,
+  pub staff_user_token: Option<UserToken>,
+  pub staff_username: Option<String>,
+  pub staff_display_name: Option<String>,
+  pub staff_ip_address: String,
+  pub created_at: DateTime<Utc>,
+}
+
+pub struct ListStaffAuditLogsArgs<'a> {
+  pub maybe_cursor_id: Option<u64>,
+  pub limit: u32,
+  pub mysql_pool: &'a MySqlPool,
+}
+
+pub async fn list_staff_audit_logs(
+  args: ListStaffAuditLogsArgs<'_>,
+) -> Result<Vec<StaffAuditLogListItem>, sqlx::Error> {
+
+  let limit = args.limit as i64;
+
+  let items = match args.maybe_cursor_id {
+    Some(cursor_id) => {
+      sqlx::query_as!(
+        StaffAuditLogListItem,
+        r#"
+SELECT
+  sal.id,
+  sal.token as `token: StaffAuditLogToken`,
+  sal.audit_action,
+  sal.maybe_entity_type,
+  sal.maybe_entity_token,
+  target_user.username as maybe_target_username,
+  target_user.display_name as maybe_target_display_name,
+  sal.staff_user_token as `staff_user_token: UserToken`,
+  staff_user.username as staff_username,
+  staff_user.display_name as staff_display_name,
+  sal.staff_ip_address,
+  sal.created_at
+FROM staff_audit_logs sal
+LEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token
+LEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token
+WHERE sal.id < ?
+ORDER BY sal.id DESC
+LIMIT ?
+        "#,
+        cursor_id as u64,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+    None => {
+      sqlx::query_as!(
+        StaffAuditLogListItem,
+        r#"
+SELECT
+  sal.id,
+  sal.token as `token: StaffAuditLogToken`,
+  sal.audit_action,
+  sal.maybe_entity_type,
+  sal.maybe_entity_token,
+  target_user.username as maybe_target_username,
+  target_user.display_name as maybe_target_display_name,
+  sal.staff_user_token as `staff_user_token: UserToken`,
+  staff_user.username as staff_username,
+  staff_user.display_name as staff_display_name,
+  sal.staff_ip_address,
+  sal.created_at
+FROM staff_audit_logs sal
+LEFT JOIN users target_user ON target_user.token = sal.maybe_entity_token
+LEFT JOIN users staff_user ON staff_user.token = sal.staff_user_token
+ORDER BY sal.id DESC
+LIMIT ?
+        "#,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+  };
+
+  Ok(items)
+}
@@ -0,0 +1,2 @@
+pub mod insert_staff_audit_log;
+pub mod list_staff_audit_logs;
@@ -0,0 +1,51 @@
+use std::marker::PhantomData;
+
+use chrono::{DateTime, Utc};
+use sqlx::{Executor, MySql};
+
+use tokens::tokens::user_impersonation_requests::UserImpersonationRequestToken;
+use tokens::tokens::users::UserToken;
+
+pub struct InsertUserImpersonationRequestArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  pub impersonated_user_token: &'a UserToken,
+  pub impersonator_user_token: &'a UserToken,
+  pub user_impersonation_token: &'a str,
+  pub ip_address_creation: &'a str,
+  pub expires_at: DateTime<Utc>,
+
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
+}
+
+pub async fn insert_user_impersonation_request<'a, 'c, E>(
+  args: InsertUserImpersonationRequestArgs<'a, 'c, E>,
+) -> Result<UserImpersonationRequestToken, sqlx::Error>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  let token = UserImpersonationRequestToken::generate();
+
+  sqlx::query!(
+    r#"
+INSERT INTO user_impersonation_requests
+SET
+  token = ?,
+  impersonated_user_token = ?,
+  impersonator_user_token = ?,
+  user_impersonation_token = ?,
+  ip_address_creation = ?,
+  expires_at = ?
+    "#,
+    token.as_str(),
+    args.impersonated_user_token.as_str(),
+    args.impersonator_user_token.as_str(),
+    args.user_impersonation_token,
+    args.ip_address_creation,
+    args.expires_at,
+  )
+    .execute(args.mysql_executor)
+    .await?;
+
+  Ok(token)
+}
@@ -0,0 +1,95 @@
+use chrono::{DateTime, Utc};
+use sqlx::MySqlPool;
+
+use tokens::tokens::users::UserToken;
+
+pub struct UserImpersonationRequestListItem {
+  pub id: u64,
+  pub impersonator_user_token: UserToken,
+  pub impersonator_username: String,
+  pub impersonator_display_name: String,
+  pub impersonated_user_token: UserToken,
+  pub impersonated_username: String,
+  pub impersonated_display_name: String,
+  pub is_redeemed: bool,
+  pub is_expired: bool,
+  pub expires_at: DateTime<Utc>,
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+}
+
+pub struct ListUserImpersonationRequestsArgs<'a> {
+  pub maybe_cursor_id: Option<u64>,
+  pub limit: u32,
+  pub mysql_pool: &'a MySqlPool,
+}
+
+pub async fn list_user_impersonation_requests(
+  args: ListUserImpersonationRequestsArgs<'_>,
+) -> Result<Vec<UserImpersonationRequestListItem>, sqlx::Error> {
+
+  let limit = args.limit as i64;
+
+  let items = match args.maybe_cursor_id {
+    Some(cursor_id) => {
+      sqlx::query_as!(
+        UserImpersonationRequestListItem,
+        r#"
+SELECT
+  uir.id,
+  uir.impersonator_user_token as `impersonator_user_token: UserToken`,
+  impersonator.username as impersonator_username,
+  impersonator.display_name as impersonator_display_name,
+  uir.impersonated_user_token as `impersonated_user_token: UserToken`,
+  impersonated.username as impersonated_username,
+  impersonated.display_name as impersonated_display_name,
+  uir.is_redeemed as `is_redeemed: bool`,
+  (uir.expires_at < NOW()) as `is_expired: bool`,
+  uir.expires_at,
+  uir.created_at,
+  uir.updated_at
+FROM user_impersonation_requests uir
+JOIN users impersonator ON impersonator.token = uir.impersonator_user_token
+JOIN users impersonated ON impersonated.token = uir.impersonated_user_token
+WHERE uir.id < ?
+ORDER BY uir.id DESC
+LIMIT ?
+        "#,
+        cursor_id as u64,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+    None => {
+      sqlx::query_as!(
+        UserImpersonationRequestListItem,
+        r#"
+SELECT
+  uir.id,
+  uir.impersonator_user_token as `impersonator_user_token: UserToken`,
+  impersonator.username as impersonator_username,
+  impersonator.display_name as impersonator_display_name,
+  uir.impersonated_user_token as `impersonated_user_token: UserToken`,
+  impersonated.username as impersonated_username,
+  impersonated.display_name as impersonated_display_name,
+  uir.is_redeemed as `is_redeemed: bool`,
+  (uir.expires_at < NOW()) as `is_expired: bool`,
+  uir.expires_at,
+  uir.created_at,
+  uir.updated_at
+FROM user_impersonation_requests uir
+JOIN users impersonator ON impersonator.token = uir.impersonator_user_token
+JOIN users impersonated ON impersonated.token = uir.impersonated_user_token
+ORDER BY uir.id DESC
+LIMIT ?
+        "#,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+  };
+
+  Ok(items)
+}
@@ -0,0 +1,100 @@
+use chrono::{DateTime, Utc};
+use sqlx::MySqlPool;
+
+use tokens::tokens::users::UserToken;
+
+pub struct UserImpersonationRequestListItem {
+  pub id: u64,
+  pub impersonator_user_token: UserToken,
+  pub impersonator_username: String,
+  pub impersonator_display_name: String,
+  pub impersonated_user_token: UserToken,
+  pub impersonated_username: String,
+  pub impersonated_display_name: String,
+  pub is_redeemed: bool,
+  pub is_expired: bool,
+  pub expires_at: DateTime<Utc>,
+  pub created_at: DateTime<Utc>,
+  pub updated_at: DateTime<Utc>,
+}
+
+pub struct ListUserImpersonationRequestsArgs<'a> {
+  pub user_token: &'a str,
+  pub maybe_cursor_id: Option<u64>,
+  pub limit: u32,
+  pub mysql_pool: &'a MySqlPool,
+}
+
+pub async fn list_user_impersonation_requests_for_user(
+  args: ListUserImpersonationRequestsArgs<'_>,
+) -> Result<Vec<UserImpersonationRequestListItem>, sqlx::Error> {
+
+  let limit = args.limit as i64;
+
+  let items = match args.maybe_cursor_id {
+    Some(cursor_id) => {
+      sqlx::query_as!(
+        UserImpersonationRequestListItem,
+        r#"
+SELECT
+  uir.id,
+  uir.impersonator_user_token as `impersonator_user_token: UserToken`,
+  impersonator.username as impersonator_username,
+  impersonator.display_name as impersonator_display_name,
+  uir.impersonated_user_token as `impersonated_user_token: UserToken`,
+  impersonated.username as impersonated_username,
+  impersonated.display_name as impersonated_display_name,
+  uir.is_redeemed as `is_redeemed: bool`,
+  (uir.expires_at < NOW()) as `is_expired: bool`,
+  uir.expires_at,
+  uir.created_at,
+  uir.updated_at
+FROM user_impersonation_requests uir
+JOIN users impersonator ON impersonator.token = uir.impersonator_user_token
+JOIN users impersonated ON impersonated.token = uir.impersonated_user_token
+WHERE uir.impersonated_user_token = ?
+  AND uir.id < ?
+ORDER BY uir.id DESC
+LIMIT ?
+        "#,
+        args.user_token,
+        cursor_id as u64,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+    None => {
+      sqlx::query_as!(
+        UserImpersonationRequestListItem,
+        r#"
+SELECT
+  uir.id,
+  uir.impersonator_user_token as `impersonator_user_token: UserToken`,
+  impersonator.username as impersonator_username,
+  impersonator.display_name as impersonator_display_name,
+  uir.impersonated_user_token as `impersonated_user_token: UserToken`,
+  impersonated.username as impersonated_username,
+  impersonated.display_name as impersonated_display_name,
+  uir.is_redeemed as `is_redeemed: bool`,
+  (uir.expires_at < NOW()) as `is_expired: bool`,
+  uir.expires_at,
+  uir.created_at,
+  uir.updated_at
+FROM user_impersonation_requests uir
+JOIN users impersonator ON impersonator.token = uir.impersonator_user_token
+JOIN users impersonated ON impersonated.token = uir.impersonated_user_token
+WHERE uir.impersonated_user_token = ?
+ORDER BY uir.id DESC
+LIMIT ?
+        "#,
+        args.user_token,
+        limit,
+      )
+        .fetch_all(args.mysql_pool)
+        .await?
+    }
+  };
+
+  Ok(items)
+}
@@ -0,0 +1,40 @@
+use chrono::{DateTime, Utc};
+use sqlx::MySqlPool;
+
+use tokens::tokens::users::UserToken;
+
+pub struct UserImpersonationRequestRecord {
+  pub token: String,
+  pub impersonated_user_token: UserToken,
+  pub impersonator_user_token: UserToken,
+  pub user_impersonation_token: String,
+  pub is_redeemed: bool,
+  pub expires_at: DateTime<Utc>,
+}
+
+/// Look up a user impersonation request by the public impersonation token (the "password").
+pub async fn lookup_user_impersonation_request(
+  user_impersonation_token: &str,
+  mysql_pool: &MySqlPool,
+) -> Result<Option<UserImpersonationRequestRecord>, sqlx::Error> {
+  let maybe_record = sqlx::query_as!(
+    UserImpersonationRequestRecord,
+    r#"
+SELECT
+  token,
+  impersonated_user_token as `impersonated_user_token: UserToken`,
+  impersonator_user_token as `impersonator_user_token: UserToken`,
+  user_impersonation_token,
+  is_redeemed as `is_redeemed: bool`,
+  expires_at
+FROM user_impersonation_requests
+WHERE user_impersonation_token = ?
+LIMIT 1
+    "#,
+    user_impersonation_token,
+  )
+    .fetch_optional(mysql_pool)
+    .await?;
+
+  Ok(maybe_record)
+}
@@ -0,0 +1,35 @@
+use std::marker::PhantomData;
+
+use sqlx::{Executor, MySql};
+
+pub struct MarkImpersonationTokenAsRedeemedArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  pub user_impersonation_token: &'a str,
+  pub ip_address_redemption: &'a str,
+
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
+}
+
+pub async fn mark_impersonation_token_as_redeemed<'a, 'c, E>(
+  args: MarkImpersonationTokenAsRedeemedArgs<'a, 'c, E>,
+) -> Result<(), sqlx::Error>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  sqlx::query!(
+    r#"
+UPDATE user_impersonation_requests
+SET
+  is_redeemed = TRUE,
+  ip_address_redemption = ?
+WHERE user_impersonation_token = ?
+    "#,
+    args.ip_address_redemption,
+    args.user_impersonation_token,
+  )
+    .execute(args.mysql_executor)
+    .await?;
+
+  Ok(())
+}
@@ -0,0 +1,5 @@
+pub mod insert_user_impersonation_request;
+pub mod list_user_impersonation_requests;
+pub mod list_user_impersonation_requests_for_user;
+pub mod lookup_user_impersonation_request;
+pub mod mark_impersonation_token_as_redeemed;
@@ -1,20 +1,27 @@
-use anyhow::anyhow;
-use sqlx::MySqlPool;
+use std::marker::PhantomData;
+
+use sqlx::{Executor, MySql};

-use errors::AnyhowResult;
 use tokens::tokens::users::UserToken;

-pub struct SetUserBanStatsArgs<'a> {
+pub struct SetUserBanStatusArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
  pub subject_user_token: &'a UserToken,
  pub is_banned: bool,
  pub mod_user_token: &'a UserToken,
  pub maybe_mod_comments: Option<&'a str>,
-  pub mysql_pool: &'a MySqlPool,
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
 }

-pub async fn set_user_ban_status(args: SetUserBanStatsArgs<'_>) -> AnyhowResult<()> {
-  let query_result = sqlx::query!(
-        r#"
+pub async fn set_user_ban_status<'a, 'c, E>(
+  args: SetUserBanStatusArgs<'a, 'c, E>,
+) -> Result<(), sqlx::Error>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  sqlx::query!(
+    r#"
 UPDATE users
 SET
    is_banned = ?,
@@ -24,17 +31,14 @@ SET

 WHERE users.token = ?
 LIMIT 1
-        "#,
-      args.is_banned,
-      args.maybe_mod_comments,
-      args.mod_user_token,
-      args.subject_user_token,
-    )
-      .execute(args.mysql_pool)
-      .await;
+    "#,
+    args.is_banned,
+    args.maybe_mod_comments,
+    args.mod_user_token,
+    args.subject_user_token,
+  )
+    .execute(args.mysql_executor)
+    .await?;

-  match query_result {
-    Ok(_) => Ok(()),
-    Err(err) => Err(anyhow!("error with query: {:?}", err)),
-  }
+  Ok(())
 }
@@ -0,0 +1,53 @@
+use std::marker::PhantomData;
+
+use chrono::{DateTime, Utc};
+use sqlx::{Executor, MySql};
+
+use tokens::tokens::user_sessions::UserSessionToken;
+use tokens::tokens::users::UserToken;
+
+pub struct CreateImpersonatedUserSessionArgs<'a, 'c: 'a, E>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  /// The user being impersonated (the session will act as this user).
+  pub user_token: &'a UserToken,
+
+  /// The staff/moderator user who initiated the impersonation.
+  pub impersonator_user_token: &'a UserToken,
+
+  pub ip_address: &'a str,
+  pub expires_at: DateTime<Utc>,
+
+  pub mysql_executor: E,
+  pub phantom: PhantomData<&'c E>,
+}
+
+pub async fn create_impersonated_user_session<'a, 'c, E>(
+  args: CreateImpersonatedUserSessionArgs<'a, 'c, E>,
+) -> Result<UserSessionToken, sqlx::Error>
+  where E: 'a + Executor<'c, Database = MySql>
+{
+  let session_token = UserSessionToken::generate();
+
+  sqlx::query!(
+    r#"
+INSERT INTO user_sessions (
+  token,
+  user_token,
+  maybe_impersonation_user_token,
+  ip_address_creation,
+  expires_at
+)
+VALUES (?, ?, ?, ?, ?)
+    "#,
+    session_token.as_str(),
+    args.user_token.as_str(),
+    args.impersonator_user_token.as_str(),
+    args.ip_address,
+    args.expires_at,
+  )
+    .execute(args.mysql_executor)
+    .await?;
+
+  Ok(session_token)
+}
@@ -1,3 +1,4 @@
+pub mod create_impersonated_user_session;
 pub mod create_user_session;
 pub mod create_user_session_with_transactor;
 pub mod delete_user_session;
@@ -16,6 +16,7 @@ pub mod model_categories;
 pub mod model_weights;
 pub mod prompt_context_items;
 pub mod prompts;
+pub mod staff_audit_logs;
 pub mod tag_uses;
 pub mod trending_model_analytics;
 pub mod tts_models;
@@ -0,0 +1,2 @@
+pub mod staff_audit_action;
+pub mod staff_audit_entity_type;
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Brandon Thomas	42694bd361	attach dev console at bottom, pin to network tab	2026-04-15 01:40:15 -04:00
Brandon Thomas	33909e0420	get rid of nag dialogue (thanks, Google) + add comments	2026-04-15 01:27:54 -04:00
Brandon Thomas	963521d87b	temporary disable video models (omni / website gens only - app unaffected) (#1369 )	2026-04-14 11:53:11 -04:00
Brandon Thomas	4323743fe7	bump artcraft 0.27 -> 0.28 (#1368 )	2026-04-14 11:49:12 -04:00
Brandon Thomas	752fad12b3	fix build issue	2026-04-14 11:47:16 -04:00
BFlat	99b831c3b0	duration slider for video gen website (#1367 )	2026-04-14 21:31:45 +07:00
BFlat	4a1d1acddd	Omni API UI updates, styling updates, mobile reponsiveness (website) (#1340 ) - Characters for Seedance 2.0 - Character creation/selection modal, @-mention support with colored inline highlights via contentEditable MentionTextarea, character tokens sent in video generation API requests - Mobile responsive navbar - Hamburger menu with slide-down panel, all nav items accessible, credits/library/sign out included - Mobile responsive PromptBox - Tighter padding, stacked toolbar on small screens, flex-wrap for option buttons - Mobile responsive library - Proper sticky header offset, icon-only filter tabs on mobile - Task queue overhaul - Prompt text with marquee hover, copy button, model creator icons, detailed failure reasons on all card types (matching desktop app) - Gallery improvements - 512px thumbnails (was 250px), 12px grid gap, model + media type badges on hover, model icon + prompt on in-progress cards - Quality selector - QualityPicker for image models (High/Medium/Low), wired to cost estimate and generation API - Video batch enqueue - Multiple videos enqueue as separate jobs so each completes independently - Form consistency - All auth pages use shared `<Input>` component, `<form onSubmit>` for Enter key, consistent styling - Bug fixes - Lightbox type error, library carousel disabled, popover icon alignment, end frame library picker, image ref max default (1 → 6), task queue mobile overflow, clear session button removed - Mobile model selector - Model picker now appears in the PromptBox toolbar on mobile/tablet (`lg:hidden`), since the floating bottom-left selector is desktop-only - Responsive image prompt row - Start frame and end frame sections stack vertically on mobile with a horizontal divider, instead of side-by-side - Responsive lightbox - Stacks vertically on mobile (media top, info below), nav arrows always visible (not hover-only), sidebar goes full-width, darker backdrop (`bg-black/80`) - Safari video inline playback - Lightbox videos use `disablePictureInPicture`, `controlsList` restrictions, and vendor-prefixed attributes to prevent fullscreen/PiP pop-out on Safari	2026-04-14 20:51:06 +07:00
bflatastic	47d6ac6841	text to image to properly use the shared upload media api + delete double toast fix	2026-04-14 20:24:24 +07:00
BFlat	689bda8bf3	image ref uploads to show in gallery, media delete not disappearing fix (#1366 )	2026-04-14 20:02:47 +07:00
Brandon Thomas	7e36149d13	more omni gen video models, client bindings, tests (#1365 )	2026-04-14 04:48:59 -04:00
Brandon Thomas	2bbeb3de78	more support audit logs while we're at it (#1364 )	2026-04-14 03:44:48 -04:00
Brandon Thomas	eeacbf6719	ban users handler update / modernization (#1363 )	2026-04-14 03:19:59 -04:00
Brandon Thomas	af763669cc	staff audit logs list (#1362 )	2026-04-14 02:52:56 -04:00
Brandon Thomas	7ff78c6d94	audit impersonation (#1361 )	2026-04-14 02:18:52 -04:00
Brandon Thomas	588478da73	cursors (#1359 )	2026-04-14 01:00:01 -04:00
Brandon Thomas	5cb7b80b44	add api docs for impersonation (#1358 )	2026-04-13 22:58:09 -04:00
Brandon Thomas	50b1a7ed06	user impersonation for support inquiries (#1357 ) - only done with user consent - only available to support staff - thoroughly audited	2026-04-13 22:49:14 -04:00
Tanish Manku	44cadf84cc	Surface gallery load errors with message and copy-to-clipboard (#1356 ) When listUserMediaFiles fails (HTTP error, network error, null reference, or any other exception), the gallery now shows the error message with a "Copy error" button instead of silently falling through to "No items yet". This is a diagnostic aid for a macOS-only blank gallery bug where the root cause is unknown (CORS, session cookie, or runtime exception) and there is no access to production logs.	2026-04-13 16:23:49 -07:00
Brandon Thomas	b7c8151d28	error utils (reusable) (#1355 )	2026-04-13 17:47:06 -04:00
				`@@ -0,0 +1 @@`
				`// Reserved for migrating the legacy SortKeyCrypto / SortId from storyteller-web.`