@byline/core 4.18.0 → 5.0.0

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

@@ -2,6 +2,7 @@ import type { RequestContext } from '@byline/auth';
 import type { CollectionDefinition } from '@byline/core';
 import type { DbErrorClassification } from '../lib/errors.js';
 import type { ISchedulerStore } from '../scheduler/types.js';
+import type { DocumentRevisionStore } from './document-revision.js';
 /**
  * Read mode for document queries.
  *
@@ -202,7 +203,18 @@ export interface FieldSort {
     /** Sort direction. */
     direction: 'asc' | 'desc';
 }
+/** Query-only executor facade, valid only during its snapshot callback. */
+export interface ReadSnapshotQueries {
+    collections: ICollectionQueries;
+    documents: Omit<IDocumentQueries, 'getDocumentSystemFieldsForUpdate'>;
+    audit: IAuditQueries;
+    singletons: ISingletonQueries;
+}
 export interface IDbAdapter {
+    /** Dedicated read-only repeatable-read transaction; never joins ambient writes. */
+    withReadSnapshot<T>(fn: (queries: ReadSnapshotQueries) => Promise<T>): Promise<T>;
+    /** Required revision schema and transaction-scoped guard capability. */
+    revisions: DocumentRevisionStore;
     commands: {
         collections: ICollectionCommands;
         documents: IDocumentCommands;
@@ -444,6 +456,11 @@ export interface ICounterCommands {
     nextScopedCounterValue(scopeName: string): Promise<number>;
 }
 export interface ICollectionCommands {
+    /** Acquire before document locks, inside an owned transaction. Shared locks
+     * admit independent writers; exclusive locks coordinate deletion/maintenance.
+     * Select the mode before locking documents; never upgrade a shared lock.
+     */
+    lockCollectionRegistration(collectionId: string, mode: 'shared' | 'exclusive'): Promise<void>;
     /**
      * Insert a new collection row. `opts.version` and `opts.schemaHash` are
      * used by the startup bootstrap to anchor initial values; omitted by
@@ -541,7 +558,7 @@ export interface TreeDeleteMutationResult {
 /** Durable state of one document-grain scheduled-publication intent. */
 export type DocumentPublishScheduleState = 'armed' | 'needs_reconfirm';
 /** Why an armed schedule stopped being executable. */
-type DocumentPublishScheduleSuspendedReason = 'content_edited';
+type DocumentPublishScheduleSuspendedReason = 'content_edited' | 'document_metadata_changed' | 'upgrade_invalidated';
 /**
  * Adapter-neutral representation of `byline_document_publish_schedules`.
  *
@@ -550,6 +567,8 @@ type DocumentPublishScheduleSuspendedReason = 'content_edited';
  * know whether the backing engine uses `timestamptz` or `datetime(6)`.
  */
 export interface DocumentPublishSchedule {
+    /** Revision authorized by the last arm/reconfirm; null for legacy suspended rows. */
+    authorizedRevision: number | null;
     documentId: string;
     collectionId: string;
     targetVersionId: string;
@@ -613,6 +632,8 @@ export interface DocumentPublishSchedulePage {
  * operations: core owns abilities, workflow validation, hooks, and audit.
  */
 export interface IDocumentPublishScheduleCommands {
+    /** Lock existing schedules in stable identity order after every affected document lock. */
+    lockDocuments(documentIds: readonly string[]): Promise<void>;
     /**
      * Create or reschedule one document's intent.
      *
@@ -635,6 +656,7 @@ export interface IDocumentPublishScheduleCommands {
         documentId: string;
         collectionId: string;
         expectedVersionId: string;
+        authorizedRevision: number;
         publishAt: Date;
         actorId: string | null;
     }): Promise<ScheduleDocumentPublishResult>;
@@ -649,6 +671,7 @@ export interface IDocumentPublishScheduleCommands {
         documentId: string;
         collectionId: string;
         expectedVersionId: string;
+        authorizedRevision: number;
         actorId: string | null;
     }): Promise<ConfirmDocumentPublishScheduleResult>;
     /**
@@ -670,6 +693,7 @@ export interface IDocumentPublishScheduleCommands {
     suspendForContentEdit(params: {
         documentId: string;
         collectionId: string;
+        reason?: 'content_edited' | 'document_metadata_changed';
     }): Promise<SuspendDocumentPublishScheduleResult>;
     /**
      * Atomically claim up to `batchSize` due rows, oldest `publishAt` first.
@@ -709,6 +733,7 @@ export interface IDocumentPublishScheduleCommands {
      * stale token without mutating the newer claimant's row.
      */
     suspendClaimForContentEdit(params: {
+        reason?: 'content_edited' | 'document_metadata_changed';
         documentId: string;
         executionToken: string;
     }): Promise<boolean>;
@@ -786,9 +811,12 @@ export interface IDocumentCommands {
         createdBy?: string;
         /**
          * When updating an existing document, the version ID of the version being
-         * replaced. If provided and `locale` is a specific locale (not 'all'),
-         * field-value rows for other locales are copied forward from this version
-         * into the new one so that per-locale content is not lost.
+         * replaced. The adapter verifies this ID against the current live version
+         * while holding the document-row lock and throws `ERR_CONFLICT` when it is
+         * stale. A locale-specific write to an existing versioned document must
+         * provide this value so field rows for every other locale can be copied
+         * forward safely. `locale: 'all'` writes replace the complete locale tree
+         * and may omit it; when supplied, it must still be current.
          */
         previousVersionId?: string;
         /**
@@ -877,6 +905,7 @@ export interface IDocumentCommands {
      */
     restoreSoftDeletedDocument(params: {
         document_id: string;
+        expectedRevision: number;
     }): Promise<number>;
     /**
      * Remove one content locale's data from a document by writing a new
@@ -975,6 +1004,11 @@ export interface ICollectionQueries {
     getCollectionById(id: string): Promise<any>;
 }
 export interface IDocumentQueries {
+    /** Internal observation; expose only alongside source data from the same snapshot. */
+    getDocumentRevision(params: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<number | null>;
     /** Scheduled-publication reads; callers resolve collection abilities above storage. */
     publishSchedules: IDocumentPublishScheduleQueries;
     /**

package/dist/@types/document-revision.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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
+ */
+/** The revision observed before preparing an existing-document mutation. */
+export interface DocumentWritePrecondition {
+    expectedRevision: number;
+}
+/** An empty singleton slot must be asserted explicitly, never by omission. */
+export type SingletonSavePrecondition = {
+    expectedState: 'empty';
+    expectedRevision?: never;
+} | {
+    expectedRevision: number;
+    expectedState?: never;
+};
+/** Returned only for the document state committed by a mutation. */
+export interface DocumentRevisionReceipt {
+    documentId: string;
+    revision: number;
+}
+/** Preserve operation-specific results, including committed side-effect failures. */
+export type DocumentMutationResult<T extends object> = T & DocumentRevisionReceipt;
+export interface StructuralMutationReceipt extends DocumentRevisionReceipt {
+    /** Hosts must authorize/filter these identities before returning them to clients. */
+    affectedDocuments: DocumentRevisionReceipt[];
+    scheduledPublicationsNeedReconfirmation: boolean;
+}
+export type DocumentStaleDetails = {
+    reason: 'revision_mismatch';
+    documentId: string;
+    expectedRevision: number;
+    currentRevision: number;
+} | {
+    reason: 'version_parent_mismatch';
+    documentId: string;
+    previousVersionId: string;
+    currentVersionId: string | null;
+} | {
+    reason: 'singleton_slot_changed';
+    singletonPath: string;
+    expectedState: 'empty';
+    currentState: 'document';
+};
+export type DocumentRevisionValidationDetails = {
+    reason: 'missing_document_revision';
+} | {
+    reason: 'invalid_document_revision';
+};
+/** Adapter-internal inputs. Lifecycle services authorize these targets before locking. */
+export interface DocumentRevisionTarget extends DocumentWritePrecondition {
+    documentId: string;
+    collectionId: string;
+    previousVersionId?: string;
+    locale?: string;
+}
+/** An adapter-issued observation valid only inside its originating transaction. */
+export interface LockedDocumentRevision extends DocumentRevisionReceipt {
+    readonly collectionId: string;
+    readonly currentVersionId: string | null;
+    readonly status: string | null;
+    readonly sourceLocale: string;
+    readonly path: string | null;
+    readonly availableLocales: readonly string[];
+}
+/** Transaction-scoped structural state; used under an exclusive collection lock. */
+export interface DocumentStructuralState {
+    documentId: string;
+    revision: number;
+    orderKey: string | null;
+    placed: boolean;
+    parentDocumentId: string | null;
+    treeOrderKey: string | null;
+    live: boolean;
+}
+/** Storage primitives; public SDK mutations compose them inside the service boundary. */
+export interface DocumentRevisionStore {
+    readStructure(params: {
+        collectionId: string;
+        documentIds?: readonly string[];
+        parentDocumentId?: string;
+    }): Promise<DocumentStructuralState[]>;
+    assertCompatibleSchema(): Promise<void>;
+    isInTransaction(): boolean;
+    /** Lock in stable document identity order, then validate every observation before returning. */
+    lock(targets: readonly DocumentRevisionTarget[]): Promise<readonly LockedDocumentRevision[]>;
+    /** Advance an authentic locked observation exactly once; participates in rollback/savepoints. */
+    advance(locked: LockedDocumentRevision): Promise<DocumentRevisionReceipt>;
+}

package/dist/@types/document-revision.js

@@ -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/@types/index.d.ts

@@ -8,6 +8,7 @@
 export * from './admin-types.js';
 export * from './collection-types.js';
 export * from './db-types.js';
+export * from './document-revision.js';
 export * from './field-data-types.js';
 export * from './field-types.js';
 export * from './populate-types.js';

package/dist/@types/index.js

@@ -8,6 +8,7 @@
 export * from './admin-types.js';
 export * from './collection-types.js';
 export * from './db-types.js';
+export * from './document-revision.js';
 export * from './field-data-types.js';
 export * from './field-types.js';
 export * from './populate-types.js';

package/dist/config/attach-hooks.test.node.js

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { resolveHooks, resolveUploadHooks } from '../@types/collection-types.js';
 import { initBylineCore } from '../core.js';
+import { testAdapter } from '../storage/db-adapter.test-helper.js';
 import { commitHookAttachment, prepareHookAttachment } from './attach-hooks.js';
 function collection(path = 'documents') {
     return {
@@ -197,7 +198,7 @@ describe('server hook attachment', () => {
         }));
         const invalid = {
             collections: [definition],
-            db: {},
+            db: testAdapter({}),
             hooks: { collections: { documents: replacement } },
             i18n: {
                 admin: { defaultLocale: 'en', locales: ['en'] },

package/dist/config/config-hooks.test.node.js

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it } from 'vitest';
 import { defineAdmin, defineSingletonAdmin } from '../@types/admin-types.js';
 import { defineCollection, defineSingleton } from '../@types/collection-types.js';
+import { testAdapter } from '../storage/db-adapter.test-helper.js';
 import { defineAdminConfig, defineServerConfig, getCollectionAdminConfig, getCollectionDefinition, getSingletonAdminConfig, } from './config.js';
 const SERVER_CONFIG = Symbol.for('__byline_server_config__');
 const ADMIN_CONFIG = Symbol.for('__byline_admin_config__');
@@ -53,7 +54,7 @@ describe('collection definition config preference', () => {
         defineAdminConfig({ collections: [client], i18n });
         defineServerConfig({
             collections: [server],
-            db: {},
+            db: testAdapter({}),
             hooks: { collections: { docs: hooks } },
             i18n,
         });

package/dist/core.js

@@ -18,6 +18,7 @@ import { validateTreeAuditCapability } from './services/document-lifecycle/audit
 import { validateTranslations } from './services/i18n-validator.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
 import { validateSearchConfig } from './services/validate-search-config.js';
+import { assertDocumentRevisionCapability } from './storage/document-revision-capability.js';
 /**
  * Initialize Byline CMS core services via the typed registry.
  *
@@ -118,6 +119,7 @@ export const initBylineCore = async (config, pinoLogger) => {
     // Reconcile collection definitions with the database: insert new rows,
     // bump schema versions when the fingerprint has drifted, and build the
     // in-memory record cache used by the lifecycle/upload/client paths.
+    await assertDocumentRevisionCapability(composed.db);
     const collectionRecords = await ensureCollections({
         definitions: composed.collections,
         db: composed.db,
@@ -161,6 +163,12 @@ export const initBylineCore = async (config, pinoLogger) => {
     // abilities. Plugins and subsystems add their own via
     // `core.registerAbility()` or `core.abilities.register()`.
     const abilities = new AbilityRegistry();
+    abilities.register({
+        key: 'system.documentMaintenance',
+        label: 'Maintain document fields while preserving status',
+        group: 'system',
+        source: 'core',
+    });
     for (const definition of composed.collections) {
         registerDocumentAbilities(abilities, definition);
     }

package/dist/core.test.node.js

@@ -1,11 +1,12 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { defineServerConfig, getServerConfig } from './config/config.js';
 import { initBylineCore } from './core.js';
+import { testAdapter } from './storage/db-adapter.test-helper.js';
 function serverConfig(admin) {
     return {
         routes: { admin },
         collections: [],
-        db: {},
+        db: testAdapter({}),
         i18n: {
             admin: { defaultLocale: 'en', locales: [] },
             content: { defaultLocale: 'en', locales: [] },
@@ -25,3 +26,27 @@ describe('initBylineCore configuration registration', () => {
         expect(getServerConfig().routes.admin).toBe('/stable/admin');
     });
 });
+it('rejects revision-incompatible storage before any boot database writes', async () => {
+    const config = serverConfig('/revision-check/admin');
+    const write = vi.fn();
+    const schemaError = new Error('fence and upgrade the revision schema');
+    config.db = testAdapter({
+        withTransaction: vi.fn(),
+        withReadSnapshot: vi.fn(),
+        revisions: {
+            assertCompatibleSchema: vi.fn().mockRejectedValue(schemaError),
+            isInTransaction: () => false,
+            lock: vi.fn(),
+            readStructure: vi.fn(),
+            advance: vi.fn(),
+        },
+        commands: {
+            collections: { create: write, update: write, lockCollectionRegistration: write },
+            documents: { publishSchedules: { lockDocuments: write } },
+            counters: { ensureCounterGroup: write },
+        },
+        backfillSourceLocales: write,
+    });
+    await expect(initBylineCore(config, {})).rejects.toBe(schemaError);
+    expect(write).not.toHaveBeenCalled();
+});

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';
@@ -18,7 +18,9 @@ export { mergePredicates, type ParseContext, type ParsedSort, type ParsedWhere,
 export { defineRecurringTask, MIN_INTERVAL_MS, MIN_LEASE_MS, } from './scheduler/define-recurring-task.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';
+export { documentRevisionFromDatabase, isDocumentRevision, parseDocumentRevision, } from './storage/document-revision.js';
 export * from './storage/index.js';
+export { runReadSnapshot } from './storage/read-snapshot.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, type SlugifierFn, type SlugifyContext, slugify, } from './utils/slugify.js';
 export { type FilenameSlugifierFn, type FilenameSlugifyContext, resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';

package/dist/index.js

@@ -20,7 +20,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';
@@ -30,7 +30,9 @@ export { mergePredicates, parsePredicateFilters, parseSort, parseWhere, } from '
 export { defineRecurringTask, MIN_INTERVAL_MS, MIN_LEASE_MS, } from './scheduler/define-recurring-task.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';
+export { documentRevisionFromDatabase, isDocumentRevision, parseDocumentRevision, } from './storage/document-revision.js';
 export * from './storage/index.js';
+export { runReadSnapshot } from './storage/read-snapshot.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, slugify, } from './utils/slugify.js';
 export { resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';

package/dist/lib/errors.d.ts

@@ -19,6 +19,7 @@
  *     details: { documentId },
  *   }).log(logger)
  */
+import type { DocumentStaleDetails } from '../@types/document-revision.js';
 import type { BylineLogger, LogLevel, LogLevelWithSilent } from './logger.js';
 export type ErrorReport = {
     code: string;
@@ -83,24 +84,40 @@ export declare const ErrorCodes: {
     readonly INVALID_TRANSITION: 'ERR_INVALID_TRANSITION';
     readonly PATCH_FAILED: 'ERR_PATCH_FAILED';
     readonly DATABASE: 'ERR_DATABASE';
+    readonly LOCK_CONFLICT: 'ERR_LOCK_CONFLICT';
     readonly STORAGE: 'ERR_STORAGE';
     readonly READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED';
     readonly READ_RECURSION: 'ERR_READ_RECURSION';
     readonly PATH_CONFLICT: 'ERR_PATH_CONFLICT';
     readonly AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED';
+    readonly DOCUMENT_HOOK_COMMITTED: 'ERR_DOCUMENT_HOOK_COMMITTED';
+    readonly DOCUMENT_STALE: 'ERR_DOCUMENT_STALE';
     readonly TREE_HOOK_COMMITTED: 'ERR_TREE_HOOK_COMMITTED';
 };
 /** Stable message fallback for stale tree-placement `ERR_CONFLICT` errors. */
 export declare const TREE_PLACEMENT_STALE_MARKER = "[ERR_CONFLICT:TREE_PLACEMENT_STALE]";
 /** Stable message fallback for `ERR_TREE_HOOK_COMMITTED` errors. */
 export declare const TREE_HOOK_COMMITTED_MARKER = "[ERR_TREE_HOOK_COMMITTED]";
+/** Stable message fallback for `ERR_DOCUMENT_HOOK_COMMITTED` errors. */
+export declare const DOCUMENT_HOOK_COMMITTED_MARKER = "[ERR_DOCUMENT_HOOK_COMMITTED]";
 export declare const ERR_UNHANDLED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_NOT_FOUND: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_CONFLICT: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/** Editorial stale state has its own code; other conflicts must not trigger reload. */
+export declare const ERR_DOCUMENT_STALE: (options: Omit<BylineErrorOptions, 'details'> & {
+    details: DocumentStaleDetails;
+}) => BylineError;
 export declare const ERR_VALIDATION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_INVALID_TRANSITION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_PATCH_FAILED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_DATABASE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+export declare const ERR_LOCK_CONFLICT: (options: BylineErrorOptions) => BylineError;
+/** Safe, small contract for live errors, reports, and message-only Error transports. */
+export declare function getLockConflictDetails(error: unknown): {
+    reason: 'lock_conflict';
+    rolledBack: true;
+    retryable: true;
+} | null;
 export declare const ERR_STORAGE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_BUDGET_EXCEEDED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_RECURSION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
@@ -121,6 +138,13 @@ export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstruc
  * docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * A document version committed, but its post-commit `afterCreate` or
+ * `afterUpdate` hook failed. Callers still receive a rejection so existing
+ * SDK error handling keeps working, while hosts can distinguish this from a
+ * rolled-back write and reconcile their UI without replaying the mutation.
+ */
+export declare const ERR_DOCUMENT_HOOK_COMMITTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 /**
  * A tree mutation and its audit row committed, but its post-commit
  * `afterTreeChange` work failed. Callers still receive a rejection so they can
@@ -142,6 +166,7 @@ export declare const ERR_TREE_HOOK_COMMITTED: (opts: BylineErrorOptions, errorCo
 export declare const DbErrorCodes: {
     readonly UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION';
     readonly FOREIGN_KEY_VIOLATION: 'DB_FOREIGN_KEY_VIOLATION';
+    readonly LOCK_CONFLICT: 'DB_LOCK_CONFLICT';
     readonly UNKNOWN: 'DB_UNKNOWN';
 };
 export type DbErrorCode = (typeof DbErrorCodes)[keyof typeof DbErrorCodes];

package/dist/lib/errors.js

@@ -117,27 +117,61 @@ export const ErrorCodes = {
     INVALID_TRANSITION: 'ERR_INVALID_TRANSITION',
     PATCH_FAILED: 'ERR_PATCH_FAILED',
     DATABASE: 'ERR_DATABASE',
+    LOCK_CONFLICT: 'ERR_LOCK_CONFLICT',
     STORAGE: 'ERR_STORAGE',
     READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED',
     READ_RECURSION: 'ERR_READ_RECURSION',
     PATH_CONFLICT: 'ERR_PATH_CONFLICT',
     AUDIT_UNSUPPORTED: 'ERR_AUDIT_UNSUPPORTED',
+    DOCUMENT_HOOK_COMMITTED: 'ERR_DOCUMENT_HOOK_COMMITTED',
+    DOCUMENT_STALE: 'ERR_DOCUMENT_STALE',
     TREE_HOOK_COMMITTED: 'ERR_TREE_HOOK_COMMITTED',
 };
 /** Stable message fallback for stale tree-placement `ERR_CONFLICT` errors. */
 export const TREE_PLACEMENT_STALE_MARKER = '[ERR_CONFLICT:TREE_PLACEMENT_STALE]';
 /** Stable message fallback for `ERR_TREE_HOOK_COMMITTED` errors. */
 export const TREE_HOOK_COMMITTED_MARKER = '[ERR_TREE_HOOK_COMMITTED]';
+/** Stable message fallback for `ERR_DOCUMENT_HOOK_COMMITTED` errors. */
+export const DOCUMENT_HOOK_COMMITTED_MARKER = '[ERR_DOCUMENT_HOOK_COMMITTED]';
 // ---------------------------------------------------------------------------
 // Pre-instantiated factories
 // ---------------------------------------------------------------------------
 export const ERR_UNHANDLED = createErrorType(ErrorCodes.UNHANDLED);
 export const ERR_NOT_FOUND = createErrorType(ErrorCodes.NOT_FOUND, 'warn');
 export const ERR_CONFLICT = createErrorType(ErrorCodes.CONFLICT, 'warn');
+/** Editorial stale state has its own code; other conflicts must not trigger reload. */
+export const ERR_DOCUMENT_STALE = (options) => new BylineError(ErrorCodes.DOCUMENT_STALE, { logLevel: 'warn', ...options });
 export const ERR_VALIDATION = createErrorType(ErrorCodes.VALIDATION, 'warn');
 export const ERR_INVALID_TRANSITION = createErrorType(ErrorCodes.INVALID_TRANSITION, 'warn');
 export const ERR_PATCH_FAILED = createErrorType(ErrorCodes.PATCH_FAILED);
 export const ERR_DATABASE = createErrorType(ErrorCodes.DATABASE);
+/** Only emitted after the owned transaction has confirmed complete rollback. */
+const LOCK_CONFLICT_MARKER = '[ERR_LOCK_CONFLICT:ROLLED_BACK]';
+export const ERR_LOCK_CONFLICT = (options) => new BylineError(ErrorCodes.LOCK_CONFLICT, {
+    ...options,
+    logLevel: 'warn',
+    message: `${LOCK_CONFLICT_MARKER} This change could not be saved because another operation was using the document. Reload before trying again.`,
+    details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+});
+/** Safe, small contract for live errors, reports, and message-only Error transports. */
+export function getLockConflictDetails(error) {
+    try {
+        if (typeof error !== 'object' || error === null)
+            return null;
+        const details = Reflect.get(error, 'details');
+        const typed = Reflect.get(error, 'code') === ErrorCodes.LOCK_CONFLICT &&
+            details?.reason === 'lock_conflict' &&
+            details?.rolledBack === true &&
+            details?.retryable === true;
+        const message = Reflect.get(error, 'message');
+        if (!typed && !(typeof message === 'string' && message.startsWith(LOCK_CONFLICT_MARKER)))
+            return null;
+        return { reason: 'lock_conflict', rolledBack: true, retryable: true };
+    }
+    catch {
+        return null;
+    }
+}
 export const ERR_STORAGE = createErrorType(ErrorCodes.STORAGE);
 export const ERR_READ_BUDGET_EXCEEDED = createErrorType(ErrorCodes.READ_BUDGET_EXCEEDED);
 export const ERR_READ_RECURSION = createErrorType(ErrorCodes.READ_RECURSION);
@@ -158,6 +192,13 @@ export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn
  * docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);
+/**
+ * A document version committed, but its post-commit `afterCreate` or
+ * `afterUpdate` hook failed. Callers still receive a rejection so existing
+ * SDK error handling keeps working, while hosts can distinguish this from a
+ * rolled-back write and reconcile their UI without replaying the mutation.
+ */
+export const ERR_DOCUMENT_HOOK_COMMITTED = createErrorType(ErrorCodes.DOCUMENT_HOOK_COMMITTED, 'warn');
 /**
  * A tree mutation and its audit row committed, but its post-commit
  * `afterTreeChange` work failed. Callers still receive a rejection so they can
@@ -182,5 +223,6 @@ export const ERR_TREE_HOOK_COMMITTED = createErrorType(ErrorCodes.TREE_HOOK_COMM
 export const DbErrorCodes = {
     UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION',
     FOREIGN_KEY_VIOLATION: 'DB_FOREIGN_KEY_VIOLATION',
+    LOCK_CONFLICT: 'DB_LOCK_CONFLICT',
     UNKNOWN: 'DB_UNKNOWN',
 };

package/dist/lib/lock-conflict.test.node.d.ts

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

package/dist/lib/lock-conflict.test.node.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { ERR_LOCK_CONFLICT, getLockConflictDetails } from './errors.js';
+describe('confirmed lock conflict transport', () => {
+    it('preserves the contract through reports and message-only Error reconstruction', () => {
+        const cause = Object.assign(new Error('secret driver SQL'), { code: '40P01' });
+        const error = ERR_LOCK_CONFLICT({ cause, message: cause.message });
+        expect(error.cause).toBe(cause);
+        for (const transported of [
+            error,
+            JSON.parse(JSON.stringify(error.report())),
+            new Error(error.message),
+        ]) {
+            expect(getLockConflictDetails(transported)).toEqual({
+                reason: 'lock_conflict',
+                rolledBack: true,
+                retryable: true,
+            });
+        }
+        expect(JSON.stringify(error.report())).not.toContain('secret driver SQL');
+    });
+    it('rejects stale state, driver failures, and incomplete rollback claims', () => {
+        for (const error of [
+            null,
+            { code: 'ERR_DOCUMENT_STALE' },
+            { code: '40P01' },
+            { code: 'ERR_LOCK_CONFLICT' },
+            { code: 'ERR_LOCK_CONFLICT', details: { rolledBack: false } },
+        ])
+            expect(getLockConflictDetails(error)).toBeNull();
+    });
+});

package/dist/scheduler/run-due-tasks.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/scheduler/run-due-tasks.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
@@ -384,13 +385,13 @@ describe('runDueTasks', () => {
         const injectedRun = vi.fn(async () => { });
         const store = fakeStore({ claim: vi.fn(async ({ name }) => claimed(name)) });
         const core = {
-            db: { scheduler: store },
+            db: testAdapter({ scheduler: store }),
             recurringTasks: [task('core-task', coreRun)],
             logger: silentLogger,
         };
         await runDueTasks(core, { owner: 'test', tasks: [task('injected-task', injectedRun)] });
         expect(coreRun).toHaveBeenCalledTimes(1);
         expect(injectedRun).not.toHaveBeenCalled();
-        await expect(runDueTasks({ ...core, db: {} }, { owner: 'test' })).rejects.toThrow(/scheduler capability/i);
+        await expect(runDueTasks({ ...core, db: testAdapter() }, { owner: 'test' })).rejects.toThrow(/scheduler capability/i);
     });
 });

package/dist/scheduler/scheduled-publication.d.ts

@@ -7,6 +7,20 @@
  */
 import type { BylineCore } from '../core.js';
 import type { BylineLogger } from '../lib/logger.js';
+/** The sweep depends only on this server-side operational surface. */
+type ScheduledPublicationCore = Pick<BylineCore, 'db' | 'collections' | 'collectionRecords' | 'storage' | 'logger'> & {
+    config: {
+        slugifier?: BylineCore['config']['slugifier'];
+        i18n: {
+            content: {
+                defaultLocale: string;
+            };
+        };
+        scheduledPublication?: {
+            enabled?: boolean;
+        };
+    };
+};
 export interface ScheduledPublicationSweepOptions {
     /** Abort before claiming another batch. */
     signal?: AbortSignal;
@@ -28,4 +42,5 @@ export interface ScheduledPublicationSweepResult {
  * Database claims provide the execution fence, so independent external
  * orchestrators may invoke this operation concurrently.
  */
-export declare function runScheduledPublicationSweep(core: BylineCore, options?: ScheduledPublicationSweepOptions): Promise<ScheduledPublicationSweepResult>;
+export declare function runScheduledPublicationSweep(core: ScheduledPublicationCore, options?: ScheduledPublicationSweepOptions): Promise<ScheduledPublicationSweepResult>;
+export {};