@byline/core 4.19.0 → 5.1.0

package/dist/services/document-lifecycle/scheduled-publish.js

@@ -9,12 +9,14 @@ import { ERR_UNAUTHENTICATED } from '@byline/auth';
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { documentAbilityKey } from '../../auth/register-collection-abilities.js';
-import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION, } from '../../lib/errors.js';
+import { ERR_CONFLICT, ERR_DOCUMENT_STALE, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION, } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
+import { documentRevisionFromDatabase } from '../../storage/document-revision.js';
 import { getWorkflow, validateStatusTransition } from '../../workflow/workflow.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
 import { actorId, invokeHook } from './internals.js';
 import { publishScheduleAuditValue } from './publish-schedule-consistency.js';
+import { assertLifecycleTransactionOwnership, commitGuardedDocumentMutation, readDocumentForMutation, } from './revision-guard.js';
 import { commitDocumentStatusTransition } from './status-transition.js';
 class ClaimedPublicationOutcome extends Error {
     result;
@@ -27,23 +29,25 @@ function assertScheduleAbilities(ctx) {
     assertActorCanPerform(ctx.requestContext, ctx.definition, 'changeStatus');
     assertActorCanPerform(ctx.requestContext, ctx.definition, 'publish');
 }
-async function assertCurrentVersionCanPublish(ctx, documentId, expectedVersionId) {
-    const current = await ctx.db.queries.documents.getCurrentVersionMetadata({
-        collection_id: ctx.collectionId,
-        document_id: documentId,
-    });
-    if (current === null) {
+async function assertCurrentVersionCanPublish(ctx, documentId, expectedVersionId, lockedCurrent) {
+    const current = lockedCurrent ??
+        (await ctx.db.queries.documents.getCurrentVersionMetadata({
+            collection_id: ctx.collectionId,
+            document_id: documentId,
+        }));
+    if (current === null || current.status === null || current.document_version_id === null) {
         throw ERR_NOT_FOUND({
             message: 'document not found',
             details: { documentId },
         }).log(ctx.logger);
     }
     if (current.document_version_id !== expectedVersionId) {
-        throw ERR_CONFLICT({
+        throw ERR_DOCUMENT_STALE({
             message: 'the document changed before its publication schedule could be saved',
             details: {
                 documentId,
-                expectedVersionId,
+                reason: 'version_parent_mismatch',
+                previousVersionId: expectedVersionId,
                 currentVersionId: current.document_version_id,
             },
         }).log(ctx.logger);
@@ -94,15 +98,21 @@ function throwScheduleStorageOutcome(ctx, documentId, status) {
 export async function scheduleDocumentPublish(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'scheduleDocumentPublish' }, async () => {
         assertScheduleAbilities(ctx);
+        await readDocumentForMutation(ctx, params);
         await assertCurrentVersionCanPublish(ctx, params.documentId, params.expectedVersionId);
         const publishAt = parsePublishAt(params.publishAt);
         const audit = requireAuditCapability(ctx.db);
         const actor = auditActor(ctx);
-        return audit.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, params, async (locked) => {
+            await assertCurrentVersionCanPublish(ctx, params.documentId, params.expectedVersionId, {
+                document_version_id: locked.currentVersionId,
+                status: locked.status,
+            });
             const result = await ctx.db.commands.documents.publishSchedules.schedule({
                 documentId: params.documentId,
                 collectionId: ctx.collectionId,
                 expectedVersionId: params.expectedVersionId,
+                authorizedRevision: locked.revision + 1,
                 publishAt,
                 actorId: actorId(ctx) ?? null,
             });
@@ -121,21 +131,28 @@ export async function scheduleDocumentPublish(ctx, params) {
                 before: result.previous === null ? null : publishScheduleAuditValue(result.previous),
                 after: publishScheduleAuditValue(result.schedule),
             });
-            return result.schedule;
+            return { value: result.schedule, changed: true };
         });
+        return { ...committed.value, revision: committed.revision };
     });
 }
 export async function confirmDocumentScheduledPublish(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'confirmDocumentScheduledPublish' }, async () => {
         assertScheduleAbilities(ctx);
+        await readDocumentForMutation(ctx, params);
         await assertCurrentVersionCanPublish(ctx, params.documentId, params.expectedVersionId);
         const audit = requireAuditCapability(ctx.db);
         const actor = auditActor(ctx);
-        return audit.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, params, async (locked) => {
+            await assertCurrentVersionCanPublish(ctx, params.documentId, params.expectedVersionId, {
+                document_version_id: locked.currentVersionId,
+                status: locked.status,
+            });
             const result = await ctx.db.commands.documents.publishSchedules.confirm({
                 documentId: params.documentId,
                 collectionId: ctx.collectionId,
                 expectedVersionId: params.expectedVersionId,
+                authorizedRevision: locked.revision + 1,
                 actorId: actorId(ctx) ?? null,
             });
             if (result.status !== 'confirmed') {
@@ -165,16 +182,18 @@ export async function confirmDocumentScheduledPublish(ctx, params) {
                 },
                 after: publishScheduleAuditValue(result.schedule),
             });
-            return result.schedule;
+            return { value: result.schedule, changed: true };
         });
+        return { ...committed.value, revision: committed.revision };
     });
 }
 export async function cancelDocumentScheduledPublish(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'cancelDocumentScheduledPublish' }, async () => {
         assertScheduleAbilities(ctx);
+        await readDocumentForMutation(ctx, params);
         const audit = requireAuditCapability(ctx.db);
         const actor = auditActor(ctx);
-        return audit.withTransaction(async () => {
+        const committed = await commitGuardedDocumentMutation(ctx, params, async (_locked) => {
             const schedule = await ctx.db.commands.documents.publishSchedules.cancel({
                 documentId: params.documentId,
                 collectionId: ctx.collectionId,
@@ -191,8 +210,9 @@ export async function cancelDocumentScheduledPublish(ctx, params) {
                     after: { reason: 'explicit' },
                 });
             }
-            return schedule;
+            return { value: schedule, changed: schedule !== null };
         });
+        return { schedule: committed.value, revision: committed.revision };
     });
 }
 export async function getDocumentScheduledPublish(ctx, params) {
@@ -222,12 +242,25 @@ export async function listDocumentPublishSchedules(core, requestContext, params)
             collectionIds.push(core.getCollectionRecord(definition.path).collectionId);
         }
     }
-    return core.db.queries.documents.publishSchedules.list({
-        collectionIds,
-        states: params.states,
-        lastAuthorizedBy: params.lastAuthorizedBy,
-        page: params.page,
-        pageSize: params.pageSize,
+    return core.db.withReadSnapshot(async (queries) => {
+        const page = await queries.documents.publishSchedules.list({
+            collectionIds,
+            states: params.states,
+            lastAuthorizedBy: params.lastAuthorizedBy,
+            page: params.page,
+            pageSize: params.pageSize,
+        });
+        const schedules = [];
+        for (const schedule of page.schedules) {
+            const scope = { collection_id: schedule.collectionId, document_id: schedule.documentId };
+            const revision = documentRevisionFromDatabase(await queries.documents.getDocumentRevision(scope));
+            schedules.push({
+                ...schedule,
+                revision,
+                documentPath: await queries.documents.getCurrentPath(scope),
+            });
+        }
+        return { ...page, schedules };
     });
 }
 /**
@@ -236,23 +269,32 @@ export async function listDocumentPublishSchedules(core, requestContext, params)
  * was armed, so callers must construct an explicit system context.
  */
 export async function publishClaimedScheduledDocument(ctx, params) {
+    assertLifecycleTransactionOwnership(ctx);
     const workflow = getWorkflow(ctx.definition);
-    const initial = await ctx.db.queries.documents.getCurrentVersionMetadata({
-        collection_id: ctx.collectionId,
-        document_id: params.documentId,
-    });
-    if (initial === null) {
+    const { initial, schedule, revision } = await ctx.db.withReadSnapshot(async (queries) => ({
+        initial: await queries.documents.getCurrentVersionMetadata({
+            collection_id: ctx.collectionId,
+            document_id: params.documentId,
+        }),
+        schedule: await queries.documents.publishSchedules.get({
+            documentId: params.documentId,
+            collectionId: ctx.collectionId,
+        }),
+        revision: await queries.documents.getDocumentRevision({
+            collection_id: ctx.collectionId,
+            document_id: params.documentId,
+        }),
+    }));
+    if (initial === null)
         return { status: 'terminal', reason: 'document_not_found' };
-    }
-    const schedule = await ctx.db.queries.documents.publishSchedules.get({
-        documentId: params.documentId,
-        collectionId: ctx.collectionId,
-    });
-    if (schedule === null || schedule.executionToken !== params.executionToken) {
+    if (schedule === null ||
+        schedule.state !== 'armed' ||
+        schedule.executionToken !== params.executionToken)
         return { status: 'claim_lost' };
-    }
+    if (schedule.authorizedRevision === null || revision !== schedule.authorizedRevision)
+        return { status: 'target_changed', reason: 'document_metadata_changed' };
     if (initial.document_version_id !== schedule.targetVersionId) {
-        return { status: 'target_changed' };
+        return { status: 'target_changed', reason: 'content_edited' };
     }
     if (initial.status === 'published') {
         return { status: 'terminal', reason: 'already_published' };
@@ -276,64 +318,84 @@ export async function publishClaimedScheduledDocument(ctx, params) {
     };
     await invokeHook(hooks?.beforeStatusChange, hookCtx);
     try {
-        await commitDocumentStatusTransition({
-            db: ctx.db,
-            documentId: params.documentId,
-            documentVersionId: initial.document_version_id,
-            collectionId: ctx.collectionId,
-            previousStatus: initial.status,
-            nextStatus: 'published',
-            actor: auditActor(ctx),
-            contributions: {
-                beforeStatusWrite: async () => {
-                    const locked = await ctx.db.commands.documents.publishSchedules.lockClaim({
-                        documentId: params.documentId,
-                        executionToken: params.executionToken,
-                    });
-                    if (locked === null) {
-                        throw new ClaimedPublicationOutcome({ status: 'claim_lost' });
-                    }
-                    const current = await ctx.db.queries.documents.getCurrentVersionMetadata({
-                        collection_id: ctx.collectionId,
-                        document_id: params.documentId,
-                    });
-                    if (current === null) {
-                        throw new ClaimedPublicationOutcome({
-                            status: 'terminal',
-                            reason: 'document_not_found',
-                        });
-                    }
-                    if (current.document_version_id !== locked.targetVersionId ||
-                        current.document_version_id !== initial.document_version_id) {
-                        throw new ClaimedPublicationOutcome({ status: 'target_changed' });
-                    }
-                    if (current.status === 'published') {
-                        throw new ClaimedPublicationOutcome({
-                            status: 'terminal',
-                            reason: 'already_published',
+        await commitGuardedDocumentMutation(ctx, { documentId: params.documentId, expectedRevision: schedule.authorizedRevision }, async (document) => {
+            await commitDocumentStatusTransition({
+                db: ctx.db,
+                documentId: params.documentId,
+                documentVersionId: initial.document_version_id,
+                collectionId: ctx.collectionId,
+                previousStatus: initial.status,
+                nextStatus: 'published',
+                actor: auditActor(ctx),
+                contributions: {
+                    beforeStatusWrite: async () => {
+                        const locked = await ctx.db.commands.documents.publishSchedules.lockClaim({
+                            documentId: params.documentId,
+                            executionToken: params.executionToken,
                         });
-                    }
-                    if (!validateStatusTransition(workflow, current.status, 'published').valid) {
-                        throw new ClaimedPublicationOutcome({
-                            status: 'terminal',
-                            reason: 'invalid_transition',
+                        if (locked === null) {
+                            throw new ClaimedPublicationOutcome({ status: 'claim_lost' });
+                        }
+                        const current = document.currentVersionId === null
+                            ? null
+                            : { document_version_id: document.currentVersionId, status: document.status };
+                        if (locked.authorizedRevision !== document.revision || locked.state !== 'armed')
+                            throw new ClaimedPublicationOutcome({
+                                status: 'target_changed',
+                                reason: 'document_metadata_changed',
+                            });
+                        if (current === null) {
+                            throw new ClaimedPublicationOutcome({
+                                status: 'terminal',
+                                reason: 'document_not_found',
+                            });
+                        }
+                        if (current.document_version_id !== locked.targetVersionId ||
+                            current.document_version_id !== initial.document_version_id) {
+                            throw new ClaimedPublicationOutcome({
+                                status: 'target_changed',
+                                reason: 'document_metadata_changed',
+                            });
+                        }
+                        if (current.status === 'published') {
+                            throw new ClaimedPublicationOutcome({
+                                status: 'terminal',
+                                reason: 'already_published',
+                            });
+                        }
+                        if (!validateStatusTransition(workflow, current.status ?? '', 'published').valid) {
+                            throw new ClaimedPublicationOutcome({
+                                status: 'terminal',
+                                reason: 'invalid_transition',
+                            });
+                        }
+                    },
+                    afterAuditAppend: async () => {
+                        const deleted = await ctx.db.commands.documents.publishSchedules.deleteClaim({
+                            documentId: params.documentId,
+                            executionToken: params.executionToken,
                         });
-                    }
+                        if (!deleted)
+                            throw new ClaimedPublicationOutcome({ status: 'claim_lost' });
+                    },
                 },
-                afterAuditAppend: async () => {
-                    const deleted = await ctx.db.commands.documents.publishSchedules.deleteClaim({
-                        documentId: params.documentId,
-                        executionToken: params.executionToken,
-                    });
-                    if (!deleted)
-                        throw new ClaimedPublicationOutcome({ status: 'claim_lost' });
-                },
-            },
+            });
+            return { value: undefined, changed: true };
         });
     }
     catch (error) {
         if (error instanceof ClaimedPublicationOutcome)
             return error.result;
+        if (error != null &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ERR_NOT_FOUND')
+            return { status: 'terminal', reason: 'document_not_found' };
+        if (error != null &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ERR_DOCUMENT_STALE')
+            return { status: 'target_changed', reason: 'document_metadata_changed' };
         throw error;
     }
     try {

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

@@ -0,0 +1,13 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { DocumentRevisionValidationDetails, DocumentStaleDetails } from '../../@types/document-revision.js';
+/** Decode only allowlisted fields; works with live errors and serialized reports. */
+export declare function getDocumentStaleDetails(error: unknown): DocumentStaleDetails | null;
+export declare function getDocumentRevisionValidationDetails(error: unknown): DocumentRevisionValidationDetails | null;
+/** Private lifecycle boundary adapter; never reclassify unrelated conflict errors. */
+export declare function normalizeDocumentVersionParentError(error: unknown): unknown;

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

@@ -0,0 +1,95 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { ERR_DOCUMENT_STALE, ErrorCodes } from '../../lib/errors.js';
+import { isDocumentRevision } from '../../storage/document-revision.js';
+function property(value, key) {
+    try {
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        return Reflect.get(value, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+function nonemptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** Decode only allowlisted fields; works with live errors and serialized reports. */
+export function getDocumentStaleDetails(error) {
+    if (property(error, 'code') !== ErrorCodes.DOCUMENT_STALE)
+        return null;
+    const details = property(error, 'details');
+    const reason = property(details, 'reason');
+    if (reason === 'singleton_slot_changed') {
+        const singletonPath = property(details, 'singletonPath');
+        if (!nonemptyString(singletonPath) ||
+            property(details, 'expectedState') !== 'empty' ||
+            property(details, 'currentState') !== 'document') {
+            return null;
+        }
+        return { reason, singletonPath, expectedState: 'empty', currentState: 'document' };
+    }
+    const documentId = property(details, 'documentId');
+    if (!nonemptyString(documentId))
+        return null;
+    if (reason === 'revision_mismatch') {
+        const expectedRevision = property(details, 'expectedRevision');
+        const currentRevision = property(details, 'currentRevision');
+        if (!isDocumentRevision(expectedRevision) ||
+            !isDocumentRevision(currentRevision) ||
+            expectedRevision === currentRevision) {
+            return null;
+        }
+        return { reason, documentId, expectedRevision, currentRevision };
+    }
+    if (reason === 'version_parent_mismatch') {
+        const previousVersionId = property(details, 'previousVersionId');
+        const currentVersionId = property(details, 'currentVersionId');
+        if (!nonemptyString(previousVersionId) ||
+            (currentVersionId !== null && !nonemptyString(currentVersionId)) ||
+            previousVersionId === currentVersionId) {
+            return null;
+        }
+        return { reason, documentId, previousVersionId, currentVersionId };
+    }
+    return null;
+}
+export function getDocumentRevisionValidationDetails(error) {
+    if (property(error, 'code') !== ErrorCodes.VALIDATION)
+        return null;
+    const reason = property(property(error, 'details'), 'reason');
+    if (reason !== 'missing_document_revision' && reason !== 'invalid_document_revision') {
+        return null;
+    }
+    return { reason };
+}
+/** Private lifecycle boundary adapter; never reclassify unrelated conflict errors. */
+export function normalizeDocumentVersionParentError(error) {
+    if (property(error, 'code') !== ErrorCodes.CONFLICT)
+        return error;
+    const details = property(error, 'details');
+    if (property(details, 'reason') !== 'stale')
+        return error;
+    const staleDetails = getDocumentStaleDetails({
+        code: ErrorCodes.DOCUMENT_STALE,
+        details: {
+            reason: 'version_parent_mismatch',
+            documentId: property(details, 'documentId'),
+            previousVersionId: property(details, 'previousVersionId'),
+            currentVersionId: property(details, 'currentVersionId'),
+        },
+    });
+    if (staleDetails === null)
+        return error;
+    return ERR_DOCUMENT_STALE({
+        message: 'the document changed before the new version could be saved',
+        details: staleDetails,
+        cause: error,
+    });
+}

package/dist/services/document-lifecycle/stale-document.test.node.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,121 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { ERR_CONFLICT, ERR_DOCUMENT_STALE, ERR_VALIDATION, ErrorCodes } from '../../lib/errors.js';
+import { assertDocumentVersionParent } from '../../storage/document-version-parent.js';
+import { getDocumentRevisionValidationDetails, getDocumentStaleDetails, normalizeDocumentVersionParentError, } from './stale-document.js';
+const variants = [
+    { reason: 'revision_mismatch', documentId: 'doc', expectedRevision: 1, currentRevision: 2 },
+    {
+        reason: 'version_parent_mismatch',
+        documentId: 'doc',
+        previousVersionId: 'previous',
+        currentVersionId: 'current',
+    },
+    {
+        reason: 'version_parent_mismatch',
+        documentId: 'doc',
+        previousVersionId: 'previous',
+        currentVersionId: null,
+    },
+    {
+        reason: 'singleton_slot_changed',
+        singletonPath: 'settings',
+        expectedState: 'empty',
+        currentState: 'document',
+    },
+];
+describe('document stale error contract', () => {
+    it.each(variants)('decodes live and serialized $reason errors with allowlisted fields', (details) => {
+        const error = ERR_DOCUMENT_STALE({
+            message: 'stale',
+            details,
+            logExtra: { secret: 'private' },
+        });
+        expect(getDocumentStaleDetails(error)).toEqual(details);
+        const report = JSON.parse(JSON.stringify(error.report()));
+        report.details.secret = 'must not propagate';
+        expect(getDocumentStaleDetails(report)).toEqual(details);
+        expect(report).not.toHaveProperty('logExtra');
+    });
+    it.each([
+        null,
+        undefined,
+        {},
+        new Error('stale_document'),
+        { code: ErrorCodes.CONFLICT, details: variants[0] },
+        { code: ErrorCodes.DOCUMENT_STALE },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[0], expectedRevision: '1' } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[0], currentRevision: 1 } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[0], currentRevision: Infinity } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[0], documentId: ' ' } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[1], currentVersionId: undefined } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[1], currentVersionId: 'previous' } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[3], expectedState: 'document' } },
+        { code: ErrorCodes.DOCUMENT_STALE, details: { ...variants[3], singletonPath: '' } },
+    ])('rejects unrelated or malformed payload %s', (value) => {
+        expect(getDocumentStaleDetails(value)).toBeNull();
+    });
+    it('tolerates hostile properties without throwing', () => {
+        const hostile = new Proxy({}, {
+            get: () => {
+                throw new Error('unreadable');
+            },
+        });
+        expect(getDocumentStaleDetails(hostile)).toBeNull();
+        expect(getDocumentStaleDetails({ code: ErrorCodes.DOCUMENT_STALE, details: hostile })).toBeNull();
+        expect(getDocumentRevisionValidationDetails(hostile)).toBeNull();
+        expect(normalizeDocumentVersionParentError(hostile)).toBe(hostile);
+    });
+    it.each(['missing_document_revision', 'invalid_document_revision'])('decodes typed validation reason %s only with the validation code', (reason) => {
+        const error = ERR_VALIDATION({ message: 'invalid', details: { reason, secret: true } });
+        expect(getDocumentRevisionValidationDetails(error)).toEqual({ reason });
+        expect(getDocumentRevisionValidationDetails(JSON.parse(JSON.stringify(error.report())))).toEqual({ reason });
+        expect(getDocumentRevisionValidationDetails({ code: ErrorCodes.CONFLICT, details: { reason } })).toBeNull();
+        expect(getDocumentStaleDetails(error)).toBeNull();
+    });
+    it('does not treat an unrelated validation error as an old-client revision error', () => {
+        expect(getDocumentRevisionValidationDetails(ERR_VALIDATION({ message: 'wrong path' }))).toBeNull();
+    });
+    it('normalizes a real adapter parent conflict without changing the raw adapter contract', () => {
+        let raw;
+        try {
+            assertDocumentVersionParent({
+                documentId: 'doc',
+                locale: 'en',
+                previousVersionId: 'old',
+                currentVersionId: 'new',
+            });
+        }
+        catch (error) {
+            raw = error;
+        }
+        expect(raw).toMatchObject({ code: ErrorCodes.CONFLICT, details: { reason: 'stale' } });
+        const normalized = normalizeDocumentVersionParentError(raw);
+        expect(normalized).toMatchObject({ code: ErrorCodes.DOCUMENT_STALE, cause: raw });
+        expect(getDocumentStaleDetails(normalized)).toEqual({
+            reason: 'version_parent_mismatch',
+            documentId: 'doc',
+            previousVersionId: 'old',
+            currentVersionId: 'new',
+        });
+    });
+    it.each([
+        { reason: 'missing', documentId: 'doc', previousVersionId: null, currentVersionId: 'new' },
+        { reason: 'stale' },
+        { reason: 'stale', documentId: 'doc', previousVersionId: 'same', currentVersionId: 'same' },
+        { reason: 'status_changed' },
+        { reason: 'path_conflict' },
+        { reason: 'stale_tree' },
+    ])('preserves conflict identity for $reason without a valid stale-parent shape', (details) => {
+        const error = ERR_CONFLICT({ message: 'conflict', details });
+        expect(normalizeDocumentVersionParentError(error)).toBe(error);
+    });
+    it('retains existing committed-failure discriminants when adding required revision receipts', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toExtend();
+        expectTypeOf().toExtend();
+        expectTypeOf().toExtend();
+        expectTypeOf().not.toExtend();
+        expectTypeOf().not.toExtend();
+    });
+});

package/dist/services/document-lifecycle/status-transition.test.node.d.ts

@@ -1,8 +1 @@
-/**
- * This Source Code is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
 export {};

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

@@ -1,3 +1,4 @@
+import { testAdapter } from '../../storage/db-adapter.test-helper.js';
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -12,7 +13,7 @@ function createTransitionHarness() {
     const auditRows = [];
     let status = 'draft';
     let archived = false;
-    const db = {
+    const db = testAdapter({
         commands: {
             documents: {
                 setDocumentStatus: async ({ status: nextStatus }) => {
@@ -53,7 +54,7 @@ function createTransitionHarness() {
                 throw error;
             }
         },
-    };
+    });
     return {
         db,
         order,

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

@@ -5,37 +5,21 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { DocumentRevisionReceipt } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
-export interface ChangeStatusResult {
+export interface ChangeStatusResult extends DocumentRevisionReceipt {
     previousStatus: string;
     newStatus: string;
 }
-export interface UnpublishResult {
+export interface UnpublishResult extends DocumentRevisionReceipt {
     archivedCount: number;
 }
-/**
- * Change a document's workflow status.
- *
- * Flow:
- *   1. Fetch current document metadata
- *   2. Validate transition via `validateStatusTransition()`
- *   3. `hooks.beforeStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
- *   4. `db.commands.documents.setDocumentStatus(...)` — in-place mutation
- *   5. Auto-archive: if transitioning to `'published'`, archive other published versions
- *   6. `hooks.afterStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
- */
 export declare function changeDocumentStatus(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     nextStatus: string;
 }): Promise<ChangeStatusResult>;
-/**
- * Unpublish a document by archiving its published version(s).
- *
- * Flow:
- *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
- *   2. Archive published versions and append the status audit atomically
- *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
- */
 export declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
 }): Promise<UnpublishResult>;