@byline/core 3.0.1 → 3.1.0

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

@@ -323,6 +323,12 @@ export interface BeforeCreateContext {
  * Includes the `documentId` and `documentVersionId` returned by storage
  * so the hook can reference the persisted document.
  *
+ * `path` is the document's canonical (source-locale) routing path as
+ * written into `byline_document_paths` — the value a consumer needs to
+ * invalidate a cache key, purge a CDN URL, or fire a webhook against the
+ * specific document. (Resolved *after* `beforeCreate`, since that hook may
+ * mutate the source field that path derivation reads.)
+ *
  * `duplicate` mirrors `BeforeCreateContext.duplicate` — present only when
  * the create was triggered by `duplicateDocument`.
  */
@@ -331,6 +337,8 @@ export interface AfterCreateContext {
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     duplicate?: {
         sourceDocumentId: string;
     };
@@ -360,6 +368,10 @@ export interface BeforeUpdateContext {
         sourceLocale: string;
         targetLocale: string;
     };
+    /** Set only when the update originates from a Delete-Locale operation. */
+    deleteLocale?: {
+        locale: string;
+    };
 }
 /**
  * Context passed to `afterUpdate` hooks.
@@ -367,6 +379,11 @@ export interface BeforeUpdateContext {
  * Includes the `documentId` and `documentVersionId` of the newly created
  * version so the hook can reference the persisted document.
  *
+ * `path` is the document's canonical (source-locale) routing path after the
+ * update — surfaced explicitly so cache-invalidation / CDN-purge / webhook
+ * hooks need not dig it out of `originalData`. (Previously available only
+ * implicitly via `originalData.path`.)
+ *
  * `restore` mirrors `BeforeUpdateContext.restore` — present only when the
  * update was triggered by restoring a historical version.
  * `copyToLocale` mirrors `BeforeUpdateContext.copyToLocale` — present only
@@ -378,6 +395,8 @@ export interface AfterUpdateContext {
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     restore?: {
         sourceVersionId: string;
     };
@@ -385,40 +404,67 @@ export interface AfterUpdateContext {
         sourceLocale: string;
         targetLocale: string;
     };
+    /** Mirrors `BeforeUpdateContext.deleteLocale`. */
+    deleteLocale?: {
+        locale: string;
+    };
 }
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so a status-change hook (publish → purge CDN, archive → drop cache key) can
+ * act on the specific document/URL rather than invalidating the whole
+ * collection.
  */
 export interface StatusChangeContext {
     documentId: string;
     documentVersionId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     previousStatus: string;
     nextStatus: string;
 }
 /**
  * Context passed to `beforeUnpublish` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so an unpublish hook can target the specific document/URL.
  */
 export interface BeforeUnpublishContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
 }
 /**
  * Context passed to `afterUnpublish` hooks.
  *
  * `archivedCount` indicates how many published versions were archived.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so an unpublish hook can target the specific document/URL.
  */
 export interface AfterUnpublishContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
     archivedCount: number;
 }
 /**
- * Context passed to `beforeDelete` / `afterDelete` hooks (future).
+ * Context passed to `beforeDelete` / `afterDelete` hooks.
+ *
+ * `path` is the document's canonical (source-locale) routing path — present
+ * so a delete hook can purge the specific document/URL (cache key, CDN, search
+ * index) rather than the entire collection.
  */
 export interface DeleteContext {
     documentId: string;
     collectionPath: string;
+    /** The document's canonical (source-locale) routing path. */
+    path: string;
 }
 /**
  * Context passed to `beforeStore` hooks (configured on

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

@@ -373,6 +373,24 @@ export interface IDocumentCommands {
     softDeleteDocument(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
+     * locale's (the `'all'` rows and all other locales are kept). The prior
+     * version still holds the deleted locale, so the operation is recoverable.
+     *
+     * `status` is the new version's status (the lifecycle service passes the
+     * workflow default — a fresh draft). Returns the new and previous version
+     * ids, or `null` when the document has no current version.
+     */
+    deleteDocumentLocale(params: {
+        documentId: string;
+        locale: string;
+        status?: string;
+    }): Promise<{
+        newVersionId: string;
+        previousVersionId: string;
+    } | null>;
     /**
      * Write the fractional-index `order_key` on a single `byline_documents`
      * row. Used by the reorder server fn for `orderable: true` collections.
@@ -450,6 +468,21 @@ export interface IDocumentQueries {
         created_at: Date;
         updated_at: Date;
     } | null>;
+    /**
+     * Resolve a document's canonical (source-locale) routing path.
+     *
+     * Returns the `byline_document_paths` row for the document under its own
+     * `source_locale` anchor (falling back to the configured default content
+     * locale for rows predating `source_locale`). Narrow by design — used by
+     * the lifecycle to populate `path` on the status-change / unpublish hook
+     * contexts without widening `getCurrentVersionMetadata`.
+     *
+     * Returns `null` when the document has no path row (or does not exist).
+     */
+    getCurrentPath(params: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<string | null>;
     getDocumentByPath(params: {
         collection_id: string;
         path: string;

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),
+                deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
             },
             counters: {
@@ -58,6 +59,7 @@ function createMockDb(options) {
             documents: {
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
+                getCurrentPath: vi.fn(fail),
                 getDocumentByPath: vi.fn(fail),
                 getDocumentByVersion: vi.fn(fail),
                 getDocumentsByVersionIds: vi.fn(fail),
@@ -183,6 +185,7 @@ describe('ensureCollections', () => {
                     setDocumentStatus: vi.fn(),
                     archivePublishedVersions: vi.fn(),
                     softDeleteDocument: vi.fn(),
+                    deleteDocumentLocale: vi.fn(),
                     setOrderKey: vi.fn(),
                 },
                 counters: {
@@ -199,6 +202,7 @@ describe('ensureCollections', () => {
                 documents: {
                     getDocumentById: vi.fn(),
                     getCurrentVersionMetadata: vi.fn(),
+                    getCurrentPath: vi.fn(),
                     getDocumentByPath: vi.fn(),
                     getDocumentByVersion: vi.fn(),
                     getDocumentsByVersionIds: vi.fn(),

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

@@ -27,6 +27,7 @@ function makeAdapter(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
             },
             counters: {
@@ -43,6 +44,7 @@ function makeAdapter(options) {
             documents: {
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
+                getCurrentPath: vi.fn(fail),
                 getDocumentByPath: vi.fn(fail),
                 getDocumentByVersion: vi.fn(fail),
                 getDocumentsByVersionIds: vi.fn(fail),

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

@@ -135,6 +135,13 @@ export interface CopyToLocaleResult {
      */
     fieldsUpdated: number;
 }
+export interface DeleteLocaleResult {
+    documentId: string;
+    /** The newly-created version that omits the deleted locale's content. */
+    documentVersionId: string;
+    /** The content locale that was removed. */
+    locale: string;
+}
 export interface DuplicateDocumentResult {
     /** The newly-created document's id. */
     documentId: string;
@@ -421,3 +428,32 @@ export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
     targetLocale: string;
     overwrite: boolean;
 }): Promise<CopyToLocaleResult>;
+/**
+ * Remove one content locale's data from a document, in place on the same
+ * document, by writing a new immutable version that omits that locale's
+ * store rows (every other locale and all non-localized `'all'` rows are
+ * carried forward by the storage primitive).
+ *
+ * The default content locale is the document's anchor (path + source_locale)
+ * and can never be removed — rejected up front. The new version lands as the
+ * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
+ * previously-published version keeps serving — including the locale being
+ * removed — until the new version is reviewed and published. The deletion is
+ * recoverable: the prior version still holds the locale, so restoring it
+ * brings the content back.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
+ *   2. Reject `locale === defaultLocale`.
+ *   3. Read the document in the target locale (validates existence; supplies
+ *      `originalData` for hooks and the availability set for the presence
+ *      check).
+ *   4. Reject when the locale has no content to delete.
+ *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
+ *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
+ *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
+ */
+export declare function deleteLocale(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    locale: string;
+}): Promise<DeleteLocaleResult>;

package/dist/services/document-lifecycle.js

@@ -255,6 +255,7 @@ export async function createDocument(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: resolvedPath,
         });
         return { documentId, documentVersionId };
     });
@@ -340,6 +341,7 @@ export async function updateDocument(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: pathForCommand ?? originalData.path,
         });
         return { documentId, documentVersionId };
     });
@@ -453,6 +455,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             collectionPath,
             documentId,
             documentVersionId,
+            path: pathForCommand ?? originalData.path,
         });
         return { documentId, documentVersionId };
     });
@@ -514,10 +517,18 @@ export async function changeDocumentStatus(ctx, params) {
                 details: { currentStatus, nextStatus: params.nextStatus },
             }).log(ctx.logger);
         }
+        // Resolve the document's canonical path so the hooks can act on the
+        // specific document/URL (CDN purge, cache-key drop). Narrow lookup —
+        // getCurrentVersionMetadata deliberately omits the path subquery.
+        const path = (await ctx.db.queries.documents.getCurrentPath({
+            collection_id: collectionId,
+            document_id: params.documentId,
+        })) ?? '';
         const hookCtx = {
             documentId: params.documentId,
             documentVersionId,
             collectionPath,
+            path,
             previousStatus: currentStatus,
             nextStatus: params.nextStatus,
         };
@@ -550,7 +561,7 @@ export async function changeDocumentStatus(ctx, params) {
  */
 export async function unpublishDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'unpublishDocument' }, async () => {
-        const { db, collectionPath, definition } = ctx;
+        const { db, collectionId, collectionPath, definition } = ctx;
         // Unpublish is a workflow transition out of `published` — reuse the
         // changeStatus gate rather than a separate ability.
         assertActorCanPerform(ctx.requestContext, collectionPath, 'changeStatus');
@@ -563,9 +574,16 @@ export async function unpublishDocument(ctx, params) {
             }).log(ctx.logger);
         }
         const hooks = definition.hooks;
+        // Resolve the document's canonical path so the hooks can target the
+        // specific document/URL (CDN purge, cache-key drop).
+        const path = (await db.queries.documents.getCurrentPath({
+            collection_id: collectionId,
+            document_id: params.documentId,
+        })) ?? '';
         await invokeHook(hooks?.beforeUnpublish, {
             documentId: params.documentId,
             collectionPath,
+            path,
         });
         const archivedCount = await db.commands.documents.archivePublishedVersions({
             document_id: params.documentId,
@@ -573,6 +591,7 @@ export async function unpublishDocument(ctx, params) {
         await invokeHook(hooks?.afterUnpublish, {
             documentId: params.documentId,
             collectionPath,
+            path,
             archivedCount,
         });
         return { archivedCount };
@@ -709,13 +728,15 @@ export async function restoreDocumentVersion(ctx, params) {
         });
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
-        // 7. afterUpdate.
+        // 7. afterUpdate. Restore is path-sticky: the canonical path comes
+        //    from the current version's envelope (originalData), not the source.
         await invokeHook(hooks?.afterUpdate, {
             data: sourceFields,
             originalData,
             collectionPath,
             documentId,
             documentVersionId,
+            path: originalData.path ?? '',
             restore: restoreContext,
         });
         return {
@@ -797,6 +818,11 @@ export async function deleteDocument(ctx, params) {
         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.
+            path: latest.path ?? '',
         };
         // 2. beforeDelete hook.
         await invokeHook(hooks?.beforeDelete, hookCtx);
@@ -1041,6 +1067,7 @@ export async function duplicateDocument(ctx, params) {
             collectionPath,
             documentId: newDocumentId,
             documentVersionId: newDocumentVersionId,
+            path: finalPath,
             duplicate: duplicateMarker,
         });
         return {
@@ -1330,6 +1357,9 @@ export async function copyToLocale(ctx, params) {
             collectionPath,
             documentId: params.documentId,
             documentVersionId,
+            // Path is sticky and source-locale-anchored; copy-to-locale never
+            // touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
             copyToLocale: copyToLocaleMarker,
         });
         return {
@@ -1341,3 +1371,110 @@ export async function copyToLocale(ctx, params) {
         };
     });
 }
+// ---------------------------------------------------------------------------
+// deleteLocale
+// ---------------------------------------------------------------------------
+/**
+ * Remove one content locale's data from a document, in place on the same
+ * document, by writing a new immutable version that omits that locale's
+ * store rows (every other locale and all non-localized `'all'` rows are
+ * carried forward by the storage primitive).
+ *
+ * The default content locale is the document's anchor (path + source_locale)
+ * and can never be removed — rejected up front. The new version lands as the
+ * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
+ * previously-published version keeps serving — including the locale being
+ * removed — until the new version is reviewed and published. The deletion is
+ * recoverable: the prior version still holds the locale, so restoring it
+ * brings the content back.
+ *
+ * Flow:
+ *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
+ *   2. Reject `locale === defaultLocale`.
+ *   3. Read the document in the target locale (validates existence; supplies
+ *      `originalData` for hooks and the availability set for the presence
+ *      check).
+ *   4. Reject when the locale has no content to delete.
+ *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
+ *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
+ *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
+ */
+export async function deleteLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        // The default locale anchors the document's path and source_locale —
+        // it cannot be deleted (the other locales fall back to it).
+        if (params.locale === defaultLocale) {
+            throw ERR_VALIDATION({
+                message: `cannot delete the default content locale ('${defaultLocale}')`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        // Read the document in the locale being removed — validates existence,
+        // supplies originalData for hooks, and the availability set for the
+        // content-presence check below.
+        const target = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.locale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (target == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        const targetRecord = target;
+        // `_availableVersionLocales` is the derived (path-coverage) set; it is
+        // the same source the editor's Delete-Locale picker is built from, so a
+        // locale offered in the UI resolves here. A partially-translated locale
+        // that never reached full coverage is not deletable through this path.
+        const available = targetRecord._availableVersionLocales ?? [];
+        if (!available.includes(params.locale)) {
+            throw ERR_NOT_FOUND({
+                message: `locale '${params.locale}' has no content to delete`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        const hooks = definition.hooks;
+        const deleteLocaleMarker = { locale: params.locale };
+        const originalData = targetRecord.fields ?? {};
+        await invokeHook(hooks?.beforeUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            deleteLocale: deleteLocaleMarker,
+        });
+        const result = await db.commands.documents.deleteDocumentLocale({
+            documentId: params.documentId,
+            locale: params.locale,
+            status: getDefaultStatus(definition),
+        });
+        if (result == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        await invokeHook(hooks?.afterUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            // Path is sticky and source-locale-anchored; deleting a translation
+            // never touches it. Read it off the target envelope.
+            path: targetRecord.path ?? '',
+            deleteLocale: deleteLocaleMarker,
+        });
+        return {
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            locale: params.locale,
+        };
+    });
+}

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

@@ -35,6 +35,7 @@ function createMockDb() {
     const softDeleteDocument = vi.fn().mockResolvedValue(1);
     const getDocumentById = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
+    const getCurrentPath = vi.fn().mockResolvedValue('current-path');
     const db = {
         commands: {
             collections: {
@@ -47,6 +48,7 @@ function createMockDb() {
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {
@@ -63,6 +65,7 @@ function createMockDb() {
             documents: {
                 getDocumentById,
                 getCurrentVersionMetadata,
+                getCurrentPath,
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),
@@ -86,6 +89,7 @@ function createMockDb() {
         softDeleteDocument,
         getDocumentById,
         getCurrentVersionMetadata,
+        getCurrentPath,
     };
 }
 const noopLogger = {
@@ -164,6 +168,14 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('afterCreate receives the resolved canonical path', async () => {
+            const afterCreate = vi.fn();
+            const { db } = createMockDb();
+            const definition = { ...minimalCollection, hooks: { afterCreate } };
+            const ctx = buildCtx(db, definition);
+            await createDocument(ctx, { data: { title: 'X' }, path: 'my-explicit-path' });
+            expect(afterCreate).toHaveBeenCalledWith(expect.objectContaining({ path: 'my-explicit-path' }));
+        });
         it('beforeCreate can mutate data before persistence', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const definition = {
@@ -327,6 +339,36 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('afterUpdate carries the sticky path forward when none is supplied', async () => {
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'sticky-path',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            const ctx = buildCtx(db, definition);
+            await updateDocument(ctx, { documentId: 'doc-1', data: { title: 'New' } });
+            expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({ path: 'sticky-path' }));
+        });
+        it('afterUpdate surfaces an explicitly-supplied path', async () => {
+            const afterUpdate = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'sticky-path',
+                fields: { title: 'Old' },
+            });
+            const definition = { ...minimalCollection, hooks: { afterUpdate } };
+            const ctx = buildCtx(db, definition);
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'New' },
+                path: 'new-path',
+            });
+            expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({ path: 'new-path' }));
+        });
         it('does not pass path to the storage primitive when no explicit path is supplied', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({
@@ -640,7 +682,9 @@ describe('Document lifecycle service', () => {
                 nextStatus: 'published',
                 documentId: 'doc-1',
                 documentVersionId: 'ver-1',
+                path: 'current-path',
             }));
+            expect(hooks.afterStatusChange).toHaveBeenCalledWith(expect.objectContaining({ path: 'current-path' }));
         });
         it('does not invoke hooks when transition is invalid', async () => {
             const hooks = {
@@ -727,9 +771,11 @@ describe('Document lifecycle service', () => {
             const ctx = buildCtx(db, definition);
             await unpublishDocument(ctx, { documentId: 'doc-1' });
             expect(callOrder).toEqual(['before', 'archive', 'after']);
+            expect(hooks.beforeUnpublish).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'current-path' }));
             expect(hooks.afterUnpublish).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 archivedCount: 2,
+                path: 'current-path',
             }));
         });
         it('works when no hooks are defined', async () => {
@@ -771,6 +817,27 @@ describe('Document lifecycle service', () => {
         });
     });
     // -----------------------------------------------------------------------
+    // deleteDocument
+    // -----------------------------------------------------------------------
+    describe('deleteDocument', () => {
+        it('invokes beforeDelete / afterDelete with the document path', async () => {
+            const beforeDelete = vi.fn();
+            const afterDelete = vi.fn();
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'ver-1',
+                document_id: 'doc-1',
+                path: 'doc-to-delete',
+                fields: {},
+            });
+            const definition = { ...minimalCollection, hooks: { beforeDelete, afterDelete } };
+            const ctx = buildCtx(db, definition);
+            await deleteDocument(ctx, { documentId: 'doc-1' });
+            expect(beforeDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
+            expect(afterDelete).toHaveBeenCalledWith(expect.objectContaining({ documentId: 'doc-1', path: 'doc-to-delete' }));
+        });
+    });
+    // -----------------------------------------------------------------------
     // restoreDocumentVersion
     // -----------------------------------------------------------------------
     describe('restoreDocumentVersion', () => {
@@ -915,6 +982,8 @@ describe('Document lifecycle service', () => {
             expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',
                 documentVersionId: 'ver-restored',
+                // Sticky path comes from the current version's envelope, not the source.
+                path: 'sticky-path',
                 restore: { sourceVersionId },
             }));
         });
@@ -1194,6 +1263,11 @@ describe('Document lifecycle service', () => {
             expect(afterCtx.duplicate).toEqual({ sourceDocumentId: 'doc-source' });
             expect(afterCtx.documentId).toBe('doc-new');
             expect(afterCtx.documentVersionId).toBe('ver-new');
+            // afterCreate carries the final path written for the duplicate — the
+            // same value handed to createDocumentVersion.
+            const writtenPath = mocks.createDocumentVersion.mock.calls[0]?.[0]?.path;
+            expect(typeof afterCtx.path).toBe('string');
+            expect(afterCtx.path).toBe(writtenPath);
         });
         it('enforces collections.<path>.create — rejects an admin actor missing the ability', async () => {
             const mocks = createMockDb();
@@ -1483,6 +1557,8 @@ describe('Document lifecycle service', () => {
                 sourceLocale: 'en',
                 targetLocale: 'fr',
             });
+            // Sticky path read off the target-locale envelope.
+            expect(afterUpdate.mock.calls[0]?.[0].path).toBe('hello');
         });
         it('enforces collections.<path>.update — rejects an admin actor missing the ability', async () => {
             const { mocks } = setupSourceTarget();

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

@@ -56,6 +56,7 @@ function createMockDb() {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {
@@ -72,6 +73,7 @@ function createMockDb() {
             documents: {
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
+                getCurrentPath: vi.fn(),
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),

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

@@ -144,6 +144,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {
@@ -160,6 +161,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
             documents: {
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
+                getCurrentPath: vi.fn(),
                 getDocumentByPath: vi.fn(),
                 getDocumentByVersion: vi.fn(),
                 getDocumentsByVersionIds: vi.fn(),

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.0.1"
+    "@byline/auth": "3.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",