feat(documents): entity-folder archive / restore / demote helpers

applyEntityArchivedSuffix stamps " (archived)" + archived_at on the
entity subfolder so the UI mutes it and auto-deposit halts. Restore
is the inverse. demoteSystemFolderOnEntityDelete flips
system_managed=false, appends " (deleted)", and clears the entity FK
so the partial unique index releases the slot — orphaned files
retain their entity FK snapshots and surface in the rep's clean-up
view.

All three helpers are best-effort from the entity-side hooks; folder
errors are logged at warn level but do not fail the entity-update
operation. UPDATE WHERE clauses include port_id (defense-in-depth).

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

src/lib/services/clients.service.ts

@@ -24,7 +24,11 @@ import { buildListQuery } from '@/lib/db/query-builder';
 import { diffEntity } from '@/lib/entity-diff';
 import { softDelete, restore, withTransaction } from '@/lib/db/utils';
 import { logger } from '@/lib/logger';
-import { syncEntityFolderName } from '@/lib/services/document-folders.service';
+import {
+  syncEntityFolderName,
+  applyEntityArchivedSuffix,
+  applyEntityRestoredSuffix,
+} from '@/lib/services/document-folders.service';
 import type {
   CreateClientInput,
   UpdateClientInput,
@@ -553,6 +557,10 @@ export async function archiveClient(id: string, portId: string, meta: AuditMeta)
 
   await softDelete(clients, clients.id, id);
 
+  void applyEntityArchivedSuffix(portId, 'client', id).catch((err) => {
+    logger.warn({ err, clientId: id }, 'Failed to apply archived suffix to client folder');
+  });
+
   void createAuditLog({
     userId: meta.userId,
     portId,
@@ -581,6 +589,10 @@ export async function restoreClient(id: string, portId: string, meta: AuditMeta)
 
   await restore(clients, clients.id, id);
 
+  void applyEntityRestoredSuffix(portId, 'client', id).catch((err) => {
+    logger.warn({ err, clientId: id }, 'Failed to clear archived suffix on client folder');
+  });
+
   void createAuditLog({
     userId: meta.userId,
     portId,