@byline/core 4.10.1 → 4.11.0

package/dist/@types/db-types.d.ts

@@ -594,15 +594,29 @@ export interface IDocumentCommands {
         excludeVersionId?: string;
     }): Promise<number>;
     /**
-     * Soft-delete a document by setting `is_deleted = true` on ALL of its
-     * versions. The `current_documents` view automatically filters these out,
-     * so the document disappears from listings without physically removing data.
+     * Soft-delete a document by marking ALL of its path rows inactive and
+     * setting `is_deleted = true` on ALL of its versions in one transaction.
+     * Live views and path resolution filter the tombstones without physically
+     * removing retained content or path values.
      *
      * Returns the number of version rows marked as deleted.
      */
     softDeleteDocument(params: {
         document_id: string;
     }): Promise<number>;
+    /**
+     * Restore a fully soft-deleted document by reactivating ALL of its path
+     * rows and versions in one transaction. Returns `0` when the document is
+     * missing, versionless, already live, or in a legacy partially-live state.
+     *
+     * This storage primitive does not reconstruct tree placement or
+     * search/cache projections.
+     *
+     * Returns the number of version rows restored.
+     */
+    restoreSoftDeletedDocument(params: {
+        document_id: string;
+    }): Promise<number>;
     /**
      * Remove one content locale's data from a document by writing a new
      * immutable version that carries forward every store row except the target

package/dist/services/collection-bootstrap.test.node.js

@@ -42,6 +42,7 @@ function createMockDb(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                restoreSoftDeletedDocument: vi.fn(fail),
                 deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
                 placeTreeNode: vi.fn(fail),

package/dist/services/discover-counter-groups.test.node.js

@@ -29,6 +29,7 @@ function makeAdapter(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                restoreSoftDeletedDocument: vi.fn(fail),
                 deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
                 placeTreeNode: vi.fn(fail),

package/dist/services/document-lifecycle/context.d.ts

@@ -31,15 +31,16 @@ export interface DocumentLifecycleContext {
     /** The collection `path` string (e.g. `'docs'`, `'news'`). */
     collectionPath: string;
     /**
-     * Storage provider for this collection. Required when the collection
-     * has any upload-capable image/file field, so that the original files
-     * and their persisted variants can be cleaned up on document deletion.
+     * Storage provider for this collection. Required when the collection has
+     * upload-capable image/file fields so lifecycle writes can persist sources,
+     * generate variants, and clean up superseded objects.
      *
      * Resolved by the route layer as:
      *   `field.upload?.storage ?? serverConfig.storage`
      *
-     * Optional — callers whose collections have no upload-capable fields
-     * are unaffected.
+     * Whole-document soft delete deliberately retains uploaded objects for
+     * restoration. Optional — callers whose collections have no upload-capable
+     * fields are unaffected.
      */
     storage?: IStorageProvider;
     /** Structured logger instance. Provided via the DI registry. */

package/dist/services/document-lifecycle/create.js

@@ -86,7 +86,7 @@ export async function createDocument(ctx, params) {
             orderKey,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale, 'create'));
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
         // `tree: true` collections place every document in the tree by default:

package/dist/services/document-lifecycle/delete.d.ts

@@ -8,7 +8,7 @@
 import { ErrorCodes } from '../../lib/errors.js';
 import type { DocumentLifecycleContext } from './context.js';
 export type DeleteDocumentOutcome = 'committed' | 'committed-with-side-effect-failures';
-export type DeleteDocumentSideEffectPhase = 'storageCleanup' | 'afterTreeChange' | 'afterDelete';
+export type DeleteDocumentSideEffectPhase = 'afterTreeChange' | 'afterDelete';
 export type DeleteDocumentSideEffectCode = typeof ErrorCodes.STORAGE | typeof ErrorCodes.UNHANDLED;
 export interface DeleteDocumentSideEffectFailure {
     phase: DeleteDocumentSideEffectPhase;
@@ -28,24 +28,16 @@ export type DeleteDocumentResult = DeleteDocumentCommittedResult | DeleteDocumen
 /**
  * Soft-delete a document.
  *
- * Marks all versions of the document as deleted (`is_deleted = true`). The
- * `current_documents` view automatically filters deleted rows, so the
- * document disappears from all list / page queries without physically
- * removing data.
- *
- * When the collection has any upload-capable image/file field and
- * `ctx.storage` is provided, every original file and persisted variant
- * across those fields is also removed from storage after the DB
- * soft-delete succeeds. Variant paths are read from the field value's
- * `variants` array (no re-derivation from `upload.sizes`), so cleanup
- * stays correct even if the size set changed between upload and delete.
- * File cleanup failures are logged but are non-fatal.
+ * Marks every version and path row for the document as deleted. Live views
+ * and path resolution exclude those tombstones, while content, retained path
+ * values, uploaded sources, and persisted variants remain available for a
+ * later restoration workflow.
  *
  * Flow:
- *   1. Fetch current document (reconstruct when upload-capable fields exist)
+ *   1. Fetch current document metadata, including its original path
  *   2. `hooks.beforeDelete({ documentId, collectionPath })`
  *   3. `db.commands.documents.softDeleteDocument({ document_id })`
- *   4. Storage file + variant cleanup (skipped when no upload fields, non-fatal)
+ *   4. Tree-change hooks, when applicable
  *   5. `hooks.afterDelete({ documentId, collectionPath })`
  */
 export declare function deleteDocument(ctx: DocumentLifecycleContext, params: {

package/dist/services/document-lifecycle/delete.js

@@ -9,8 +9,6 @@ import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ErrorCodes } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
-import { hasUploadField, isUploadField } from '../../utils/storage-utils.js';
-import { walkFieldTree } from '../walk-field-tree.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability, requireTreeAuditCapability, } from './audit.js';
 import { invokeHook } from './internals.js';
 import { firePromoteTreeChange, reconcileTreeOnDeleteInTransaction } from './tree.js';
@@ -35,24 +33,16 @@ function serializeSideEffectFailure(phase, error) {
 /**
  * Soft-delete a document.
  *
- * Marks all versions of the document as deleted (`is_deleted = true`). The
- * `current_documents` view automatically filters deleted rows, so the
- * document disappears from all list / page queries without physically
- * removing data.
- *
- * When the collection has any upload-capable image/file field and
- * `ctx.storage` is provided, every original file and persisted variant
- * across those fields is also removed from storage after the DB
- * soft-delete succeeds. Variant paths are read from the field value's
- * `variants` array (no re-derivation from `upload.sizes`), so cleanup
- * stays correct even if the size set changed between upload and delete.
- * File cleanup failures are logged but are non-fatal.
+ * Marks every version and path row for the document as deleted. Live views
+ * and path resolution exclude those tombstones, while content, retained path
+ * values, uploaded sources, and persisted variants remain available for a
+ * later restoration workflow.
  *
  * Flow:
- *   1. Fetch current document (reconstruct when upload-capable fields exist)
+ *   1. Fetch current document metadata, including its original path
  *   2. `hooks.beforeDelete({ documentId, collectionPath })`
  *   3. `db.commands.documents.softDeleteDocument({ document_id })`
- *   4. Storage file + variant cleanup (skipped when no upload fields, non-fatal)
+ *   4. Tree-change hooks, when applicable
  *   5. `hooks.afterDelete({ documentId, collectionPath })`
  */
 export async function deleteDocument(ctx, params) {
@@ -60,17 +50,13 @@ export async function deleteDocument(ctx, params) {
         const { db, collectionPath, definition, logger } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'delete');
         const hooks = await resolveHooks(definition);
-        // 1. Verify the document exists.
-        //    For collections that have any upload-capable image/file field
-        //    AND a storage provider, fetch with reconstruct: true so we
-        //    can read the stored file paths (and persisted variant paths)
-        //    from the field values before the DB rows are deleted.
-        const storage = ctx.storage;
-        const isUploadCollection = hasUploadField(definition) && storage != null;
+        // 1. Verify the document exists. Soft delete retains field rows and
+        //    uploaded objects, so only the envelope and original path projection
+        //    are needed for hooks.
         const latest = await db.queries.documents.getDocumentById({
             collection_id: ctx.collectionId,
             document_id: params.documentId,
-            reconstruct: isUploadCollection,
+            reconstruct: false,
         });
         if (latest == null) {
             throw ERR_NOT_FOUND({
@@ -78,42 +64,12 @@ export async function deleteDocument(ctx, params) {
                 details: { documentId: params.documentId },
             }).log(ctx.logger);
         }
-        // Collect storage paths for every upload-capable field on the doc:
-        // the original file plus every persisted variant. The schema/data
-        // walk descends into `group` / `array` / `blocks`, so upload fields
-        // nested in repeating structures are cleaned up too. Reading the
-        // variants from the field value (rather than re-deriving from
-        // `upload.sizes`) keeps cleanup correct even when the size set
-        // changes between upload and delete.
-        const storagePathsToDelete = [];
-        if (isUploadCollection) {
-            const data = latest?.fields;
-            for (const leaf of walkFieldTree(definition.fields, data)) {
-                if (!isUploadField(leaf.field))
-                    continue;
-                const fieldValue = leaf.value;
-                if (!fieldValue || typeof fieldValue !== 'object')
-                    continue;
-                const stored = fieldValue;
-                if (typeof stored.storagePath === 'string') {
-                    storagePathsToDelete.push(stored.storagePath);
-                }
-                if (Array.isArray(stored.variants)) {
-                    for (const variant of stored.variants) {
-                        if (variant && typeof variant.storagePath === 'string') {
-                            storagePathsToDelete.push(variant.storagePath);
-                        }
-                    }
-                }
-            }
-        }
         const hookCtx = {
             documentId: params.documentId,
             collectionPath,
-            // The current document was fetched above (reconstructed only for
-            // upload collections, but the envelope carries the locale-resolved
-            // `path` projection either way). Surface it so delete hooks can purge
-            // the specific document/URL.
+            // The non-reconstructed envelope carries the locale-resolved `path`
+            // projection. Capture it before the path row becomes inactive so
+            // delete hooks can purge the specific document/URL.
             path: latest.path ?? '',
         };
         // 2. beforeDelete hook.
@@ -124,9 +80,7 @@ export async function deleteDocument(ctx, params) {
         //    back, so soft-deleted documents cannot leak live edges.
         //    whole-document delete mints no new version, so the version stream
         //    never records it — the audit log is the only place a deletion is
-        //    accountable (docs/07-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
-        //    DB↔external side-effect and stays OUTSIDE the transaction — it is
-        //    post-commit, best-effort compensation (docs/03-architecture/03-transactions.md).
+        //    accountable (docs/07-auth-and-security/02-auditability.md).
         const treeAudit = definition.tree === true ? requireTreeAuditCapability(db) : undefined;
         const audit = treeAudit ?? requireAuditCapability(db);
         const actor = auditActor(ctx);
@@ -150,25 +104,7 @@ export async function deleteDocument(ctx, params) {
         // Everything below is post-commit. Each operation and the logger get an
         // independent attempt; none can turn the committed delete into a rejection.
         const sideEffectFailures = [];
-        // 4. Clean up every storage file. Returned failures omit paths, while
-        // internal logs retain the target needed for operational reconciliation.
-        if (storage && storagePathsToDelete.length > 0) {
-            for (const storagePath of storagePathsToDelete) {
-                try {
-                    await storage.delete(storagePath);
-                }
-                catch (error) {
-                    sideEffectFailures.push(serializeSideEffectFailure('storageCleanup', error));
-                    try {
-                        logger.error({ err: error, documentId: params.documentId, storagePath }, 'failed to delete storage file');
-                    }
-                    catch {
-                        // Diagnostic logging must not interrupt the remaining cleanup attempts.
-                    }
-                }
-            }
-        }
-        // 5-6. Both post-commit hook families get an independent attempt. A tree
+        // 4-5. Both post-commit hook families get an independent attempt. A tree
         // invalidation failure must not prevent afterDelete consumers (search,
         // cache removal) from running, or vice versa.
         try {

package/dist/services/document-lifecycle/duplicate.js

@@ -172,7 +172,7 @@ export async function duplicateDocument(ctx, params) {
                 orderKey,
                 createdBy: actorId(ctx),
             })
-                .catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale));
+                .catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale, 'duplicate'));
         }
         catch (err) {
             if (!isPathConflictError(err)) {
@@ -197,7 +197,7 @@ export async function duplicateDocument(ctx, params) {
                 orderKey,
                 createdBy: actorId(ctx),
             })
-                .catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale));
+                .catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale, 'duplicate'));
         }
         const newDocumentId = extractDocumentId(result.document);
         const newDocumentVersionId = extractVersionId(result.document);

package/dist/services/document-lifecycle/internals.d.ts

@@ -75,7 +75,7 @@ export declare function extractDocumentId(document: any): string;
  * name substring; it stays targeted to the path constraint so unrelated
  * unique violations aren't spuriously rebranded as path conflicts.
  */
-export declare function rethrowPathConflict(db: IDbAdapter, err: unknown, path: string, locale: string): never;
+export declare function rethrowPathConflict(db: IDbAdapter, err: unknown, path: string, locale: string, operation: 'create' | 'update' | 'duplicate'): never;
 /**
  * Detect whether an error is the `ERR_PATH_CONFLICT` raised by
  * `rethrowPathConflict`. Used by `duplicateDocument`'s retry logic to

package/dist/services/document-lifecycle/internals.js

@@ -142,12 +142,17 @@ export function extractDocumentId(document) {
  * name substring; it stays targeted to the path constraint so unrelated
  * unique violations aren't spuriously rebranded as path conflicts.
  */
-export function rethrowPathConflict(db, err, path, locale) {
+export function rethrowPathConflict(db, err, path, locale, operation) {
     const classification = db.classifyError?.(err);
     if (classification?.code === DbErrorCodes.UNIQUE_VIOLATION &&
         classification.constraint?.includes('document_paths_collection_locale_path')) {
+        const message = operation === 'create'
+            ? `cannot create a document at path "${path}" because a live document already uses it in this collection (locale: ${locale})`
+            : operation === 'update'
+                ? `cannot update this document to path "${path}" because a live document already uses it in this collection (locale: ${locale})`
+                : `cannot duplicate this document to path "${path}" because a live document already uses it in this collection (locale: ${locale})`;
         throw ERR_PATH_CONFLICT({
-            message: `path "${path}" is already in use in this collection (locale: ${locale})`,
+            message,
             details: { path, locale, constraint: classification.constraint },
         });
     }

package/dist/services/document-lifecycle/rethrow-path-conflict.test.node.js

@@ -10,32 +10,51 @@ import { ErrorCodes } from '../../lib/errors.js';
 import { rethrowPathConflict } from './internals.js';
 const adapterWith = (c) => ({ classifyError: c === undefined ? undefined : () => c });
 describe('rethrowPathConflict', () => {
-    it('maps a unique violation on the path constraint to ERR_PATH_CONFLICT', () => {
+    it.each([
+        [
+            'create',
+            'cannot create a document at path "news/hello" because a live document already uses it in this collection (locale: en)',
+        ],
+        [
+            'update',
+            'cannot update this document to path "news/hello" because a live document already uses it in this collection (locale: en)',
+        ],
+        [
+            'duplicate',
+            'cannot duplicate this document to path "news/hello" because a live document already uses it in this collection (locale: en)',
+        ],
+    ])('maps a path unique violation for %s with live-occupant language', (operation, message) => {
+        const constraint = 'byline_document_paths_document_paths_collection_locale_path';
         const db = adapterWith({
             code: 'DB_UNIQUE_VIOLATION',
-            constraint: 'byline_document_paths_document_paths_collection_locale_path',
+            constraint,
         });
         try {
-            rethrowPathConflict(db, new Error('raw'), 'news/hello', 'en');
+            rethrowPathConflict(db, new Error('raw'), 'news/hello', 'en', operation);
             throw new Error('should have thrown');
         }
         catch (e) {
-            expect(e.code).toBe(ErrorCodes.PATH_CONFLICT);
+            expect(e).toMatchObject({
+                code: ErrorCodes.PATH_CONFLICT,
+                message,
+                details: { path: 'news/hello', locale: 'en', constraint },
+            });
+            expect(e.details).not.toHaveProperty('documentId');
         }
     });
     it('rethrows raw when the unique violation is on a different constraint', () => {
         const raw = new Error('raw');
         const db = adapterWith({ code: 'DB_UNIQUE_VIOLATION', constraint: 'some_other_unique' });
-        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en', 'create')).toThrow(raw);
     });
     it('rethrows raw for DB_UNKNOWN', () => {
         const raw = new Error('raw');
         const db = adapterWith({ code: 'DB_UNKNOWN' });
-        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en', 'create')).toThrow(raw);
     });
     it('rethrows raw when the adapter has no classifyError', () => {
         const raw = new Error('raw');
         const db = adapterWith(undefined);
-        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en', 'create')).toThrow(raw);
     });
 });

package/dist/services/document-lifecycle/system-fields.js

@@ -104,7 +104,7 @@ export async function updateDocumentSystemFields(ctx, params) {
                     locale: sourceLocale,
                     path: pathForCommand,
                 })
-                    .catch((err) => rethrowPathConflict(db, err, pathForCommand, sourceLocale));
+                    .catch((err) => rethrowPathConflict(db, err, pathForCommand, sourceLocale, 'update'));
                 await audit.append({
                     documentId: params.documentId,
                     collectionId,

package/dist/services/document-lifecycle/update.js

@@ -91,7 +91,7 @@ export async function updateDocument(ctx, params) {
             previousVersionId: originalData.document_version_id,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
@@ -210,7 +210,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             previousVersionId: originalData.document_version_id,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any

package/dist/services/document-lifecycle.test.node.js

@@ -7,7 +7,7 @@
  */
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
-import { BylineError, DbErrorCodes, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
+import { BylineError, DbErrorCodes, ErrorCodes } from '../lib/errors.js';
 import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
@@ -77,6 +77,7 @@ function createMockDb() {
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,
+                restoreSoftDeletedDocument: vi.fn(),
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),
@@ -154,6 +155,12 @@ function createMockDb() {
         withTransaction,
     };
 }
+function pathUniqueViolation() {
+    return Object.assign(new Error('duplicate key value violates unique constraint'), {
+        code: '23505',
+        constraint: 'idx_document_paths_collection_locale_path',
+    });
+}
 const noopLogger = {
     log: vi.fn(),
     fatal: vi.fn(),
@@ -315,6 +322,20 @@ describe('Document lifecycle service', () => {
             const persistedPath = createDocumentVersion.mock.calls[0]?.[0].path;
             expect(persistedPath).toBe('custom/route');
         });
+        it('describes a create path conflict as ownership by a live document', async () => {
+            const { db, createDocumentVersion } = createMockDb();
+            createDocumentVersion.mockRejectedValueOnce(pathUniqueViolation());
+            const ctx = buildCtx(db);
+            await expect(createDocument(ctx, { data: { title: 'Home' }, path: 'home' })).rejects.toMatchObject({
+                code: ErrorCodes.PATH_CONFLICT,
+                message: 'cannot create a document at path "home" because a live document already uses it in this collection (locale: en)',
+                details: {
+                    path: 'home',
+                    locale: 'en',
+                    constraint: 'idx_document_paths_collection_locale_path',
+                },
+            });
+        });
         it('falls back to a UUID when no useAsPath and no explicit path', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const ctx = buildCtx(db); // minimalCollection has no useAsPath
@@ -632,10 +653,7 @@ describe('Document lifecycle service', () => {
             // Simulate the pg driver throwing a unique-violation on the path
             // constraint when the upsert tries to claim a slug owned by another
             // document in the same (collection, locale).
-            createDocumentVersion.mockRejectedValueOnce(Object.assign(new Error('duplicate key value violates unique constraint'), {
-                code: '23505',
-                constraint: 'idx_document_paths_collection_locale_path',
-            }));
+            createDocumentVersion.mockRejectedValueOnce(pathUniqueViolation());
             const ctx = buildCtx(db);
             try {
                 await updateDocument(ctx, {
@@ -647,7 +665,15 @@ describe('Document lifecycle service', () => {
             }
             catch (err) {
                 expect(err).toBeInstanceOf(BylineError);
-                expect(err.code).toBe(ErrorCodes.PATH_CONFLICT);
+                expect(err).toMatchObject({
+                    code: ErrorCodes.PATH_CONFLICT,
+                    message: 'cannot update this document to path "home" because a live document already uses it in this collection (locale: en)',
+                    details: {
+                        path: 'home',
+                        locale: 'en',
+                        constraint: 'idx_document_paths_collection_locale_path',
+                    },
+                });
             }
         });
         it('rethrows non-23505 errors unchanged', async () => {
@@ -749,6 +775,31 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('describes a patched path conflict as ownership by a live document', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-current',
+                path: 'old-slug',
+                source_locale: 'de',
+                fields: { title: 'Old' },
+            });
+            createDocumentVersion.mockRejectedValueOnce(pathUniqueViolation());
+            const ctx = buildCtx(db);
+            await expect(updateDocumentWithPatches(ctx, {
+                documentId: 'doc-1',
+                patches: [],
+                path: 'new-slug',
+                locale: 'de',
+            })).rejects.toMatchObject({
+                code: ErrorCodes.PATH_CONFLICT,
+                message: 'cannot update this document to path "new-slug" because a live document already uses it in this collection (locale: de)',
+                details: {
+                    path: 'new-slug',
+                    locale: 'de',
+                    constraint: 'idx_document_paths_collection_locale_path',
+                },
+            });
+        });
         it('normalizes patched and hook-produced numeric values before persistence', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({
@@ -1078,7 +1129,7 @@ describe('Document lifecycle service', () => {
             expect(softDeleteDocument).not.toHaveBeenCalled();
             expect(afterDelete).not.toHaveBeenCalled();
         });
-        it('cleans up stored files for upload fields at any nesting depth', async () => {
+        it('retains stored files when soft-deleting an upload-capable document', async () => {
             const { db, getDocumentById } = createMockDb();
             const upload = { mimeTypes: ['application/pdf'], maxFileSize: 1024 };
             const definition = {
@@ -1121,14 +1172,8 @@ describe('Document lifecycle service', () => {
                 storage: { delete: storageDelete },
             };
             await deleteDocument(ctx, { documentId: 'doc-1' });
-            // reconstruct: true because the collection is upload-capable
-            expect(getDocumentById).toHaveBeenCalledWith(expect.objectContaining({ reconstruct: true }));
-            expect(storageDelete.mock.calls.map((c) => c[0])).toEqual([
-                'covers/original.jpg',
-                'covers/thumb.avif',
-                'files/a.pdf',
-                'files/b.pdf',
-            ]);
+            expect(getDocumentById).toHaveBeenCalledWith(expect.objectContaining({ reconstruct: false }));
+            expect(storageDelete).not.toHaveBeenCalled();
         });
         it('returns only allowlisted failures and keeps raw details in internal logs', async () => {
             const { db, getDocumentById } = createMockDb();
@@ -1172,37 +1217,22 @@ describe('Document lifecycle service', () => {
                 logger: { ...noopLogger, error: vi.fn() },
             };
             const result = await deleteDocument(ctx, { documentId: 'doc-1' });
-            expect(storageDelete.mock.calls.map((call) => call[0])).toEqual([
-                'private/original.pdf',
-                'private/preview.pdf',
-                'private/thumbnail.pdf',
-            ]);
+            expect(storageDelete).not.toHaveBeenCalled();
             expect(result).toEqual({
                 deletedVersionCount: 1,
                 outcome: 'committed-with-side-effect-failures',
-                sideEffectFailures: [
-                    { phase: 'storageCleanup', code: 'ERR_STORAGE' },
-                    { phase: 'storageCleanup', code: 'ERR_UNHANDLED' },
-                    { phase: 'afterDelete', code: 'ERR_UNHANDLED' },
-                ],
+                sideEffectFailures: [{ phase: 'afterDelete', code: 'ERR_UNHANDLED' }],
             });
             const serializedResult = JSON.stringify(result);
-            expect(serializedResult).not.toContain('storage unavailable');
-            expect(serializedResult).not.toContain('cleanup failed');
             expect(serializedResult).not.toContain('hook leaked');
             expect(serializedResult).not.toContain('private/');
             expect(serializedResult).not.toContain('ERR_SEARCH');
-            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({
-                err: expect.objectContaining({ message: 'storage unavailable' }),
+            expect(ctx.logger.error).toHaveBeenCalledTimes(2);
+            expect(ctx.logger.error).toHaveBeenNthCalledWith(1, expect.objectContaining({ err: hookError, documentId: 'doc-1' }), 'afterDelete hook failed after document delete');
+            expect(ctx.logger.error).toHaveBeenNthCalledWith(2, expect.objectContaining({
                 documentId: 'doc-1',
-                storagePath: 'private/original.pdf',
-            }), 'failed to delete storage file');
-            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({
-                err: expect.objectContaining({ message: 'cleanup failed' }),
-                documentId: 'doc-1',
-                storagePath: 'private/thumbnail.pdf',
-            }), 'failed to delete storage file');
-            expect(ctx.logger.error).toHaveBeenCalledWith(expect.objectContaining({ err: hookError, documentId: 'doc-1' }), 'afterDelete hook failed after document delete');
+                sideEffectFailures: [{ phase: 'afterDelete', code: 'ERR_UNHANDLED' }],
+            }), 'post-commit delete side effects failed');
         });
     });
     // -----------------------------------------------------------------------
@@ -1239,6 +1269,24 @@ describe('Document lifecycle service', () => {
                 after: 'new-slug',
             }));
         });
+        it('describes a system-field path conflict as ownership by a live document', async () => {
+            const { db, getDocumentSystemFieldsForUpdate } = createMockDb();
+            setupDoc(getDocumentSystemFieldsForUpdate);
+            db.commands.documents.updateDocumentPath.mockRejectedValueOnce(pathUniqueViolation());
+            const ctx = buildCtx(db);
+            await expect(updateDocumentSystemFields(ctx, {
+                documentId: 'doc-1',
+                path: 'new-slug',
+            })).rejects.toMatchObject({
+                code: ErrorCodes.PATH_CONFLICT,
+                message: 'cannot update this document to path "new-slug" because a live document already uses it in this collection (locale: en)',
+                details: {
+                    path: 'new-slug',
+                    locale: 'en',
+                    constraint: 'idx_document_paths_collection_locale_path',
+                },
+            });
+        });
         it('does not write, audit, or fire the hook when the path is unchanged', async () => {
             const { db, getDocumentSystemFieldsForUpdate, auditAppend, withTransaction } = createMockDb();
             setupDoc(getDocumentSystemFieldsForUpdate);
@@ -1806,13 +1854,13 @@ describe('Document lifecycle service', () => {
             const mocks = createMockDb();
             setupSource(mocks);
             const ctx = buildCtx(mocks.db, localizedCollection);
-            // First call: throw a path-conflict error. Second call: succeed.
+            // First call: throw a raw path unique violation. The lifecycle maps it
+            // to ERR_PATH_CONFLICT, then the duplicate retry classifier handles it.
             let attempt = 0;
             mocks.createDocumentVersion.mockImplementation(() => {
                 attempt += 1;
                 if (attempt === 1) {
-                    const err = ERR_PATH_CONFLICT({ message: 'path conflict' });
-                    return Promise.reject(err);
+                    return Promise.reject(pathUniqueViolation());
                 }
                 return Promise.resolve({
                     document: { id: 'ver-new', document_id: 'doc-new' },
@@ -1833,11 +1881,28 @@ describe('Document lifecycle service', () => {
             const mocks = createMockDb();
             setupSource(mocks);
             const ctx = buildCtx(mocks.db, localizedCollection);
-            // Both attempts throw path-conflict.
+            // Both attempts throw raw path unique violations, exercising both
+            // duplicateDocument conflict-mapping calls.
             mocks.createDocumentVersion.mockImplementation(() => {
-                return Promise.reject(ERR_PATH_CONFLICT({ message: 'path conflict' }));
+                return Promise.reject(pathUniqueViolation());
+            });
+            let thrown;
+            try {
+                await duplicateDocument(ctx, { sourceDocumentId: 'doc-source' });
+            }
+            catch (err) {
+                thrown = err;
+            }
+            const retryPath = mocks.createDocumentVersion.mock.calls[1]?.[0].path;
+            expect(thrown).toMatchObject({
+                code: ErrorCodes.PATH_CONFLICT,
+                message: `cannot duplicate this document to path "${retryPath}" because a live document already uses it in this collection (locale: en)`,
+                details: {
+                    path: retryPath,
+                    locale: 'en',
+                    constraint: 'idx_document_paths_collection_locale_path',
+                },
             });
-            await expect(duplicateDocument(ctx, { sourceDocumentId: 'doc-source' })).rejects.toMatchObject({ code: ErrorCodes.PATH_CONFLICT });
             // Bounded to exactly two attempts.
             expect(mocks.createDocumentVersion).toHaveBeenCalledTimes(2);
         });

package/dist/services/field-upload.test.node.js

@@ -59,6 +59,7 @@ function createMockDb() {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                restoreSoftDeletedDocument: vi.fn(),
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),

package/dist/services/populate.test.node.js

@@ -147,6 +147,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                restoreSoftDeletedDocument: vi.fn(),
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.10.1",
+  "version": "4.11.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -82,7 +82,7 @@
     "sharp": "^0.35.3",
     "uuid": "^14.0.1",
     "zod": "^4.4.3",
-    "@byline/auth": "4.10.1"
+    "@byline/auth": "4.11.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",