feat(documents): schema for hub split + entity-folder lifecycle

Adds system_managed / entity_type / entity_id / archived_at to
document_folders for the three system roots (Clients/Companies/
Yachts) + per-entity auto-subfolders. Adds files.folder_id so a
file's home is a first-class field (not derived from storagePath
prefix). Partial unique index uniq_document_folders_entity dedupes
entity subfolders per port; chk_system_folder_shape pins the shape
of system rows. Migration is idempotent and ships without backfill —
the backfill script runs as a separate deploy step.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/db/schema/documents.ts

@@ -30,6 +30,9 @@ export const files = pgTable(
     clientId: text('client_id').references(() => clients.id),
     yachtId: text('yacht_id').references(() => yachts.id, { onDelete: 'set null' }),
     companyId: text('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    folderId: text('folder_id').references((): AnyPgColumn => documentFolders.id, {
+      onDelete: 'set null',
+    }),
     filename: text('filename').notNull(),
     originalName: text('original_name').notNull(),
     mimeType: text('mime_type'),
@@ -45,6 +48,8 @@ export const files = pgTable(
     index('idx_files_client').on(table.clientId),
     index('idx_files_yacht').on(table.yachtId),
     index('idx_files_company').on(table.companyId),
+    index('idx_files_folder').on(table.folderId),
+    index('idx_files_port_folder').on(table.portId, table.folderId),
   ],
 );
 
@@ -290,6 +295,20 @@ export const documentFolders = pgTable(
     // parent in a transaction instead of cascading.
     parentId: text('parent_id'),
     name: text('name').notNull(),
+    /** True = folder is managed by the system (one of the three roots
+     *  Clients/Companies/Yachts, or an auto-created entity subfolder).
+     *  System folders reject rename/move/delete at the API layer. Demoted
+     *  to false when the owning entity is hard-deleted. */
+    systemManaged: boolean('system_managed').notNull().default(false),
+    /** null | 'root' | 'client' | 'company' | 'yacht'. 'root' is the
+     *  three system roots; the entity values mark per-entity subfolders. */
+    entityType: text('entity_type'),
+    /** Null when entityType is null or 'root'; the entity's id otherwise.
+     *  Combined with entityType to dedupe entity folders per port. */
+    entityId: text('entity_id'),
+    /** Mirrors the entity's archive state. Non-null = folder muted in UI
+     *  and auto-deposit halted. Cleared on entity restore. */
+    archivedAt: timestamp('archived_at', { withTimezone: true }),
     createdBy: text('created_by').notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
@@ -302,6 +321,11 @@ export const documentFolders = pgTable(
       sql`COALESCE(${table.parentId}, '__root__')`,
       sql`LOWER(${table.name})`,
     ),
+    // One subfolder per entity per port. Excludes 'root' folders (the
+    // three system roots are deduped by sibling-name uniqueness).
+    uniqueIndex('uniq_document_folders_entity')
+      .on(table.portId, table.entityType, table.entityId)
+      .where(sql`${table.entityId} IS NOT NULL`),
   ],
 );