@byline/core 6.3.0 → 6.5.0

package/dist/services/review-probes.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/review-probes.test.node.js

@@ -0,0 +1,349 @@
+/**
+ * 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 { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
+import { describe, expect, it, vi } from 'vitest';
+import { BylineError, DbErrorCodes, ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ErrorCodes, } from '../lib/errors.js';
+import { runReadSnapshot } from '../storage/read-snapshot.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
+import { cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copyToLocale, createDocument, deleteDocument, deleteLocale, duplicateDocument, listDocumentPublishSchedules, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
+// ---------------------------------------------------------------------------
+// Fixtures / Helpers
+// ---------------------------------------------------------------------------
+const minimalCollection = {
+    path: 'articles',
+    labels: { singular: 'Article', plural: 'Articles' },
+    fields: [{ name: 'title', type: 'text', label: 'Title' }],
+    workflow: {
+        statuses: [
+            { name: 'draft', label: 'Draft' },
+            { name: 'published', label: 'Published' },
+            { name: 'archived', label: 'Archived' },
+        ],
+    },
+};
+const numericCollection = {
+    ...minimalCollection,
+    fields: [
+        { name: 'quantity', type: 'integer' },
+        { name: 'score', type: 'float' },
+        { name: 'price', type: 'decimal' },
+    ],
+};
+function publishScheduleRow(overrides = {}) {
+    const now = new Date('2026-08-22T12:00:00.000Z');
+    return {
+        documentId: 'doc-1',
+        collectionId: 'col-1',
+        targetVersionId: 'ver-1',
+        authorizedRevision: 1,
+        publishAt: new Date('2026-08-23T12:00:00.000Z'),
+        state: 'armed',
+        suspendedAt: null,
+        suspendedReason: null,
+        scheduledBy: TEST_ACTOR_ID,
+        lastAuthorizedBy: TEST_ACTOR_ID,
+        lastAuthorizedAt: now,
+        scheduledAt: now,
+        updatedAt: now,
+        executionToken: null,
+        executionExpiresAt: null,
+        lastAttemptAt: null,
+        nextAttemptAt: new Date('2026-08-23T12:00:00.000Z'),
+        attemptCount: 0,
+        lastError: null,
+        ...overrides,
+    };
+}
+/** Build a mock IDbAdapter. Returns the adapter plus individual mock fns. */
+function createMockDb() {
+    const createDocumentVersion = vi.fn().mockResolvedValue({
+        document: { id: 'ver-1', document_id: 'doc-1' },
+        fieldCount: 3,
+    });
+    const setDocumentStatus = vi.fn().mockResolvedValue(undefined);
+    const archivePublishedVersions = vi.fn().mockResolvedValue(0);
+    const softDeleteDocument = vi.fn().mockResolvedValue(1);
+    const deleteDocumentLocale = vi.fn().mockResolvedValue({ newVersionId: 'ver-2' });
+    const getDocumentById = vi.fn().mockImplementation(async () => {
+        const metadata = await getCurrentVersionMetadata();
+        return metadata == null ? null : { ...metadata, fields: {}, path: await getCurrentPath() };
+    });
+    const getDocumentSystemFieldsForUpdate = vi.fn().mockResolvedValue(null);
+    const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
+    const getCurrentPath = vi.fn().mockResolvedValue('current-path');
+    const publishSchedule = vi.fn().mockResolvedValue({ status: 'document_not_found' });
+    const confirmPublishSchedule = vi.fn().mockResolvedValue({ status: 'schedule_not_found' });
+    const cancelPublishSchedule = vi.fn().mockResolvedValue(null);
+    const suspendPublishSchedule = vi.fn().mockResolvedValue({ status: 'schedule_not_found' });
+    const claimDuePublishSchedules = vi.fn().mockResolvedValue([]);
+    const lockPublishScheduleClaim = vi.fn().mockResolvedValue(null);
+    const deletePublishScheduleClaim = vi.fn().mockResolvedValue(false);
+    const suspendPublishScheduleClaim = vi.fn().mockResolvedValue(false);
+    const releasePublishScheduleClaim = vi.fn().mockResolvedValue(false);
+    const getPublishSchedule = vi.fn().mockResolvedValue(null);
+    const listPublishSchedules = vi.fn().mockResolvedValue({ schedules: [], total: 0 });
+    // Audit capability (docs/07-auth-and-security/02-auditability.md — W2). `withTransaction` is a passthrough
+    // in unit tests (runs the unit of work immediately, no real tx); `append`
+    // records the calls so write-point tests can assert the audit rows emitted.
+    const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
+    let transactionDepth = 0;
+    const revisions = new Map();
+    const transaction = {
+        run: async (fn) => {
+            transactionDepth++;
+            try {
+                return await fn();
+            }
+            finally {
+                transactionDepth--;
+            }
+        },
+    };
+    const withTransaction = vi.spyOn(transaction, 'run');
+    const fail = () => {
+        throw new Error('unexpected singleton mapping call');
+    };
+    // Fake classifier mirroring db-postgres's real one closely enough for
+    // rethrowPathConflict's consumption of the seam: a pg-shaped 23505 with a
+    // constraint name classifies as a unique violation; anything else is
+    // unknown. Individual tests inject pg-shaped errors on `createDocumentVersion`
+    // (see `translates a Postgres unique-constraint violation...` below).
+    const classifyError = vi.fn((err) => {
+        const e = err;
+        if (e?.code === '23505') {
+            return { code: DbErrorCodes.UNIQUE_VIOLATION, constraint: e.constraint };
+        }
+        return { code: DbErrorCodes.UNKNOWN };
+    });
+    const db = {
+        classifyError,
+        revisions: {
+            ...unusedRevisionStore,
+            isInTransaction: () => transactionDepth > 0,
+            lock: vi.fn(async (targets) => {
+                const observations = [];
+                for (const target of targets) {
+                    const revision = revisions.get(target.documentId) ?? 1;
+                    if (target.expectedRevision !== revision)
+                        throw ERR_DOCUMENT_STALE({
+                            message: 'stale',
+                            details: {
+                                reason: 'revision_mismatch',
+                                documentId: target.documentId,
+                                expectedRevision: target.expectedRevision,
+                                currentRevision: revision,
+                            },
+                        });
+                    const system = await getDocumentSystemFieldsForUpdate({
+                        collection_id: target.collectionId,
+                        document_id: target.documentId,
+                    });
+                    const source = await getDocumentById.mock.results.at(-1)?.value;
+                    if (!system && !source)
+                        throw ERR_NOT_FOUND({ message: 'document not found' });
+                    observations.push({
+                        documentId: target.documentId,
+                        collectionId: target.collectionId,
+                        revision,
+                        currentVersionId: source?.document_version_id ?? 'ver-1',
+                        status: source?.status ?? 'draft',
+                        sourceLocale: system?.source_locale ?? source?.source_locale ?? 'en',
+                        path: system?.path ?? source?.path ?? null,
+                        availableLocales: system?.availableLocales ?? source?.availableLocales ?? [],
+                    });
+                }
+                return observations;
+            }),
+            advance: vi.fn(async (locked) => {
+                const revision = locked.revision + 1;
+                revisions.set(locked.documentId, revision);
+                return { documentId: locked.documentId, revision };
+            }),
+        },
+        withReadSnapshot: (fn) => runReadSnapshot(db.queries, fn),
+        commands: {
+            collections: {
+                lockCollectionRegistration: vi.fn(async () => { }),
+                create: vi.fn(),
+                update: vi.fn(),
+                delete: vi.fn(),
+            },
+            documents: {
+                publishSchedules: {
+                    lockDocuments: vi.fn(async () => { }),
+                    schedule: publishSchedule,
+                    confirm: confirmPublishSchedule,
+                    cancel: cancelPublishSchedule,
+                    suspendForContentEdit: suspendPublishSchedule,
+                    claimDue: claimDuePublishSchedules,
+                    lockClaim: lockPublishScheduleClaim,
+                    deleteClaim: deletePublishScheduleClaim,
+                    suspendClaimForContentEdit: suspendPublishScheduleClaim,
+                    releaseClaim: releasePublishScheduleClaim,
+                },
+                createDocumentVersion,
+                updateDocumentPath: vi.fn().mockResolvedValue(undefined),
+                setDocumentAvailableLocales: vi.fn().mockResolvedValue(undefined),
+                setDocumentStatus,
+                archivePublishedVersions,
+                softDeleteDocument,
+                restoreSoftDeletedDocument: vi.fn(),
+                deleteDocumentLocale: deleteDocumentLocale,
+                setOrderKey: vi.fn(),
+                placeTreeNode: vi.fn(),
+                removeFromTree: vi.fn(),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
+            },
+            counters: {
+                ensureCounterGroup: vi.fn(),
+                nextCounterValue: vi.fn(),
+                nextScopedCounterValue: vi.fn(),
+            },
+            audit: { append: auditAppend },
+            singletons: {
+                lockSlot: vi.fn(async () => { }),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
+        },
+        withTransaction: transaction.run,
+        queries: {
+            collections: {
+                getAllCollections: vi.fn(),
+                getCollectionByPath: vi.fn(),
+                getCollectionById: vi.fn(),
+            },
+            documents: {
+                publishSchedules: {
+                    get: getPublishSchedule,
+                    list: listPublishSchedules,
+                },
+                getDocumentRevision: async ({ document_id }) => revisions.get(document_id) ?? 1,
+                getDocumentSystemFieldsForUpdate,
+                getDocumentById,
+                getCurrentVersionMetadata,
+                getCurrentPath,
+                getDocumentByPath: vi.fn(),
+                getDocumentByVersion: vi.fn(),
+                getDocumentsByVersionIds: vi.fn(),
+                getDocumentsByDocumentIds: vi.fn(),
+                getDocumentHistory: vi.fn(),
+                getPublishedVersion: vi.fn(),
+                getPublishedDocumentIds: vi.fn(),
+                getDocumentCountsByStatus: vi.fn(),
+                findDocuments: vi.fn(),
+                getLastOrderKey: vi.fn(),
+                getNeighborOrderKeys: vi.fn(),
+                getCanonicalDocumentOrder: vi.fn(),
+                getTreeAncestors: vi.fn(),
+                getTreeChildren: vi.fn(),
+                getTreeParent: vi.fn(),
+                getTreeSubtree: vi.fn(),
+            },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
+        },
+    };
+    return {
+        db,
+        createDocumentVersion,
+        setDocumentStatus,
+        archivePublishedVersions,
+        softDeleteDocument,
+        deleteDocumentLocale,
+        getDocumentById,
+        getDocumentSystemFieldsForUpdate,
+        getCurrentVersionMetadata,
+        getCurrentPath,
+        publishSchedule,
+        confirmPublishSchedule,
+        cancelPublishSchedule,
+        suspendPublishSchedule,
+        claimDuePublishSchedules,
+        lockPublishScheduleClaim,
+        deletePublishScheduleClaim,
+        suspendPublishScheduleClaim,
+        releasePublishScheduleClaim,
+        getPublishSchedule,
+        listPublishSchedules,
+        auditAppend,
+        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(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    silent: vi.fn(),
+};
+// A real persisted-user id is a UUID; `actorId()` only attributes UUIDs (see
+// the regression note below). Use a valid UUID so the default context's
+// writes are attributed.
+const TEST_ACTOR_ID = '01901234-0000-7000-8000-000000000001';
+function buildCtx(db, definition = minimalCollection) {
+    return {
+        db,
+        definition,
+        collectionId: 'col-1',
+        collectionVersion: 1,
+        collectionPath: definition.path,
+        logger: noopLogger,
+        defaultLocale: 'en',
+        // Inject a super-admin context by default so the bulk of existing
+        // tests do not have to care about ability enforcement. The dedicated
+        // "enforcement" block below covers the missing-context / missing-ability
+        // negative cases.
+        requestContext: createSuperAdminContext({ id: TEST_ACTOR_ID }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('review probes', () => {
+    it('rejects caller-selected published status for a create-only actor', async () => {
+        const { db } = createMockDb();
+        const ctx = buildCtx(db);
+        ctx.requestContext = createRequestContext({ actor: new AdminAuth({
+                id: 'editor', abilities: ['collections.articles.create'],
+            }) });
+        await expect(createDocument(ctx, { data: { title: 'Direct publish' }, status: 'published' })).rejects.toMatchObject({ code: AuthErrorCodes.FORBIDDEN });
+    });
+    it('rejects an undeclared initial workflow status', async () => {
+        const { db } = createMockDb();
+        const ctx = buildCtx(db);
+        await expect(createDocument(ctx, { data: { title: 'Invalid status' }, status: 'not-a-status' })).rejects.toBeDefined();
+    });
+});

package/dist/services/singleton-lifecycle/index.d.ts

@@ -11,4 +11,5 @@ export { restoreSingletonVersion } from './restore.js';
 export { updateSingleton } from './update.js';
 export type { CopySingletonToLocaleParams } from './copy-to-locale.js';
 export type { SingletonSaveResult } from './internals.js';
+export type { RestoreSingletonVersionResult } from './restore.js';
 export type { UpdateSingletonParams, UpdateSingletonResult } from './update.js';

package/dist/services/singleton-lifecycle/restore.d.ts

@@ -5,10 +5,20 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { DocumentFieldIssue } from '../../validation/document-fields.js';
 import type { DocumentLifecycleContext } from '../document-lifecycle/context.js';
 import type { SingletonSaveResult } from './internals.js';
+export interface RestoreSingletonVersionResult extends SingletonSaveResult {
+    /**
+     * Ways the restored content fails today's field validation. Restore is
+     * exempt from that gate, so these never block it — they are reported so the
+     * editor can say what must be fixed before the next ordinary save. Mirrors
+     * `RestoreVersionResult.validationIssues` on the collection path.
+     */
+    validationIssues?: DocumentFieldIssue[];
+}
 /** Restore one historical singleton version as the new current version. */
 export declare function restoreSingletonVersion(ctx: DocumentLifecycleContext, params: {
     sourceVersionId: string;
     expectedRevision: number;
-}): Promise<SingletonSaveResult>;
+}): Promise<RestoreSingletonVersionResult>;

package/dist/services/singleton-lifecycle/restore.js

@@ -7,6 +7,7 @@
  */
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
+import { validateDocumentFields } from '../../validation/document-fields.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { applyRichTextEmbed } from '../document-lifecycle/internals.js';
 import { persistExistingDocumentVersion } from '../document-lifecycle/persistence.js';
@@ -16,7 +17,11 @@ export async function restoreSingletonVersion(ctx, params) {
     params = { ...params };
     return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'restoreSingletonVersion' }, async () => {
         const definition = authorizeSingletonUpdate(ctx);
-        return commitSingletonSave({
+        // Restore is exempt from the content gate (see assertWritableContent).
+        // Collect the issues for reporting only, after the embed pass, so the
+        // editor can explain why its next ordinary save is refused.
+        let validationIssues = [];
+        const result = await commitSingletonSave({
             ctx,
             definition,
             expectedRevision: params.expectedRevision,
@@ -77,7 +82,13 @@ export async function restoreSingletonVersion(ctx, params) {
                     data,
                     originalData,
                     locale: 'all',
-                    prepareWrite: () => applyRichTextEmbed(ctx, data),
+                    prepareWrite: async () => {
+                        await applyRichTextEmbed(ctx, data);
+                        validationIssues = validateDocumentFields(definition.fields, data, {
+                            locale: 'all',
+                            onCallbackError: ({ path, site, error }) => ctx.logger.error({ err: error, fieldPath: path, site }, 'restore diagnostic callback threw'),
+                        });
+                    },
                     write: async () => {
                         return persistExistingDocumentVersion(ctx, {
                             documentId: slot.documentId,
@@ -91,5 +102,6 @@ export async function restoreSingletonVersion(ctx, params) {
                 };
             },
         });
+        return { ...result, ...(validationIssues.length > 0 ? { validationIssues } : {}) };
     });
 }

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

@@ -411,6 +411,40 @@ describe('singleton lifecycle service', () => {
         expect(afterSave).toHaveBeenCalledWith(hookShape);
         expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({ action: 'restore', locale: 'all' }));
     });
+    it('reports validation issues on a restore without blocking it', async () => {
+        // The singleton restore path shares the persistence exemption, so it must
+        // also share the reporting the shared restore modal renders.
+        const harness = createHarness({ mapped: true });
+        harness.views.set('all', { fields: { title: { en: 'Current' }, count: 2 } });
+        harness.versions.set('ver-source', {
+            document_id: 'doc-1',
+            // Predates `title` — a required localized field — and carries a count
+            // that today's integer rule rejects.
+            fields: { count: 'not-a-number' },
+        });
+        const result = await restoreSingletonVersion(harness.ctx, {
+            expectedRevision: 1,
+            sourceVersionId: 'ver-source',
+        });
+        expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({ action: 'restore', locale: 'all' }));
+        expect(result.validationIssues?.map((issue) => [issue.field, issue.kind])).toEqual([
+            ['title', 'required'],
+            ['count', 'invalid'],
+        ]);
+    });
+    it('omits validationIssues when the restored singleton version is clean', async () => {
+        const harness = createHarness({ mapped: true });
+        harness.views.set('all', { fields: { title: { en: 'Current' }, count: 2 } });
+        harness.versions.set('ver-source', {
+            document_id: 'doc-1',
+            fields: { title: { en: 'Historic' }, count: 1 },
+        });
+        const result = await restoreSingletonVersion(harness.ctx, {
+            expectedRevision: 1,
+            sourceVersionId: 'ver-source',
+        });
+        expect(result.validationIssues).toBeUndefined();
+    });
     it('copies the merged target payload and distinguishes overwrite modes', async () => {
         const run = async (overwrite) => {
             const beforeSave = vi.fn();

package/dist/validation/document-fields.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { FieldSet } from '../@types/field-types.js';
+import type { BylineLogger } from '../lib/logger.js';
+export interface DocumentFieldIssue {
+    field: string;
+    message: string;
+    /**
+     * `required` marks a value that is absent but declared non-optional — the
+     * shape schema tightening produces. Every other failure, including a custom
+     * `validate` callback's message, is `invalid`: it describes a value that is
+     * present and wrong, or a container that cannot be stored. Nothing branches
+     * on this to decide whether a write proceeds; it exists so callers can tell
+     * an editor what is missing separately from what is wrong.
+     */
+    kind: 'required' | 'invalid';
+}
+export interface DocumentFieldValidationDetails {
+    reason: 'invalid_document_fields';
+    issues: DocumentFieldIssue[];
+}
+type CallbackSite = 'validate' | 'condition' | 'schema';
+/**
+ * Validate schema data without transforming or stripping persistence values.
+ *
+ * Never throws. Three things here run schema-author code and can fail on data
+ * they did not anticipate: `validate`, `condition`, and the per-field Zod
+ * schema, whose `validation.rules` may carry a throwing `custom` predicate or a
+ * malformed `pattern` that fails while the schema is being built. A validator
+ * calling `value.trim()` meets a historical version that lacks the field. A raw
+ * exception would abort the walk, discarding the issues already collected, and
+ * escape as an unhandled error rather than a field result.
+ *
+ * Each site is therefore isolated and a failure recorded as an `invalid` issue,
+ * so an ordinary save still refuses the write, and a caller using this for
+ * diagnostics only — restore — is never blocked by it. The editor-facing
+ * message is fixed; the exception goes to `onCallbackError`.
+ */
+export declare function validateDocumentFields(fields: FieldSet, data: Record<string, any>, options?: {
+    locale?: string;
+    /** Browser-only presentation precheck; the lifecycle never exempts hidden fields. */
+    respectConditions?: boolean;
+    /** Pending uploads are validated after transport by the lifecycle. */
+    skip?: (path: string) => boolean;
+    /**
+     * Receives the real exception when a schema-author callback throws, for
+     * server-side diagnostics. The editor only ever sees `CALLBACK_FAILED`.
+     */
+    onCallbackError?: (detail: {
+        path: string;
+        site: CallbackSite;
+        error: unknown;
+    }) => void;
+}): DocumentFieldIssue[];
+/**
+ * Enforce the collection's declared field contract over prepared content.
+ *
+ * Every versioned write passes through this except a restore, which is exempt
+ * structurally rather than by a parameter here — see `assertWritableContent`
+ * in the lifecycle's `persistence.ts` for why, and for what that exemption
+ * does and does not promise.
+ */
+export declare function assertDocumentFields(fields: FieldSet, data: Record<string, any>, locale?: string, logger?: Pick<BylineLogger, 'error'>): void;
+/** Accept live errors and serialized reports, discarding all non-contract data. */
+export declare function getDocumentFieldValidationDetails(error: unknown): DocumentFieldValidationDetails | null;
+export {};