From 6816d4b7e050d75b29194cbf96a53f64610447c1 Mon Sep 17 00:00:00 2001
From: Rob Simmons <robsimmons@gmail.com>
Date: Thu, 29 Oct 2026 10:27:09 -0400
Subject: [PATCH 1/2] chore: clarify docstrigns around UUIDs and names

---
 shared/shared.ts         |  4 ++--
 src/prisma/schema.prisma | 18 +++++-------------
 2 files changed, 7 insertions(+), 15 deletions(-)

diff --git a/shared/shared.ts b/shared/shared.ts
index 9e13fe56..8c650e0b 100644
--- a/shared/shared.ts
+++ b/shared/shared.ts
@@ -5,8 +5,8 @@ import { z } from 'zod'
  *
  * - IDs are used in file paths and in URLs.
  *   They must never contain traversal characters (`/` and `.`).
- *   Project and user IDs are currently required to be UUID v4.
- * - Project names are not used in file paths, but may be used in URLs.
+ *   Project and user IDs are randomized strings (UUIDv4 or BetterAuth's custom ID format)
+ * - Project and user names are not used in file paths, but may be used in URLs.
  *   We enforce alphanumeric ASCII names.
  *   Names are unique up to recasing, natively in the database (`COLLATE NOCASE`).
  *   Unicode names may be added in the future.
diff --git a/src/prisma/schema.prisma b/src/prisma/schema.prisma
index 1f21b584..2a4a80a5 100644
--- a/src/prisma/schema.prisma
+++ b/src/prisma/schema.prisma
@@ -13,19 +13,11 @@ datasource db {
 model User {
   /// Better-auth identifier (matches BETTERAUTH_ID_RE)
   id            String    @id
-  /// Better-auth does not require uniqueness but we do.
-  /// These names serve two distinct purposes that require uniqueness.
-  ///
-  /// First, they are a user-controlled identifier that appears in a URL as to signify the project's owner
+  /// Better-auth does not require name uniqueness but we do:
+  /// names are user-controlled identifiers that appear in a URL as part of locating the project
   /// (e.g. https://example.com/my-user-name/my-first-project).
   ///
-  /// Second, they are unique long-lasting filesystem identifiers used to group a user's project
-  /// data on the file system.
-  ///
-  /// (It's possible that in the future we will want to tease these apart,
-  /// and allow the URL-appearing identifier to be changed more freely by users.)
-  ///
-  /// Names must match `ALPHANUM_NAME_RE`.
+  /// Names must match ALPHANUM_NAME_RE.
   /// This column is `COLLATE NOCASE` in migration.sql
   /// (Prisma cannot express SQLite collation settings),
   /// so uniqueness and lookups are case-insensitive
@@ -111,7 +103,7 @@ model Verification {
 // Workbench-specific tables
 
 model Project {
-  /// 128-bit UUID.
+  /// 128-bit UUIDv4.
   id           String              @id
   /// Project's owner.
   user         User                @relation(fields: [userId], references: [id], onDelete: Cascade)
@@ -135,7 +127,7 @@ model Project {
 /// A publication is live exactly while its row exists:
 /// every request for it resolves through this table.
 model Publication {
-  /// UUID; the publication's durable identity, and its directory under `publications/`.
+  /// UUIDv4; the publication's durable identity, and its directory under `publications/`.
   id        String   @id
   project   Project  @relation(fields: [projectId], references: [id], onDelete: Cascade)
   projectId String

From 4ed231328f17e39f33ed7027b7a49f4aa03068ef Mon Sep 17 00:00:00 2001
From: "Robert J. Simmons" <442315+robsimmons@users.noreply.github.com>
Date: Thu, 29 Oct 2026 15:56:04 -0400
Subject: [PATCH 2/2] Update shared/shared.ts

Co-authored-by: Wojciech Nawrocki <13901751+Vtec234@users.noreply.github.com>
---
 shared/shared.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/shared/shared.ts b/shared/shared.ts
index 8c650e0b..0f1e3fd3 100644
--- a/shared/shared.ts
+++ b/shared/shared.ts
@@ -5,7 +5,7 @@ import { z } from 'zod'
  *
  * - IDs are used in file paths and in URLs.
  *   They must never contain traversal characters (`/` and `.`).
- *   Project and user IDs are randomized strings (UUIDv4 or BetterAuth's custom ID format)
+ *   Project and user IDs are randomized strings (UUIDv4 and BetterAuth's custom ID format, respectively)
  * - Project and user names are not used in file paths, but may be used in URLs.
  *   We enforce alphanumeric ASCII names.
  *   Names are unique up to recasing, natively in the database (`COLLATE NOCASE`).