@byline/core 4.7.0 → 4.8.0

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

@@ -1,5 +1,6 @@
 import type { RequestContext } from '@byline/auth';
 import type { CollectionDefinition } from '@byline/core';
+import type { DbErrorClassification } from '../lib/errors.js';
 import type { QueryPredicate } from './query-predicate.js';
 /**
  * Read mode for document queries.
@@ -245,6 +246,16 @@ export interface IDbAdapter {
     backfillSourceLocales?: () => Promise<{
         rowsUpdated: number;
     }>;
+    /**
+     * Classify a raw driver error into an adapter-agnostic, code-based shape so
+     * core can map database failures to domain errors without knowing driver
+     * anatomy. The error-side analogue of the storage `normalizeRow` seam.
+     *
+     * Optional: when absent, core treats every error as `DB_UNKNOWN` and rethrows
+     * it unchanged — the current behaviour for adapters that do not implement it.
+     * Canonical adapters (db-postgres, db-mysql) implement it.
+     */
+    classifyError?(err: unknown): DbErrorClassification;
 }
 /**
  * The realm of the actor that performed an audited change. `'admin'` for

package/dist/index.d.ts

@@ -7,7 +7,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, 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_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 { 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';

package/dist/index.js

@@ -23,7 +23,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, 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_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 { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';

package/dist/lib/errors.d.ts

@@ -127,3 +127,29 @@ export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorCons
  * reconcile, while transports can distinguish it from a rolled-back mutation.
  */
 export declare const ERR_TREE_HOOK_COMMITTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * Code-based classification of a raw database driver error, produced by
+ * `IDbAdapter.classifyError`. The error-side analogue of the storage
+ * `normalizeRow` seam: the adapter canonicalises driver anatomy into these
+ * codes so `@byline/core` can map DB failures to domain errors (e.g.
+ * `ERR_PATH_CONFLICT`) without knowing any driver's error shape.
+ *
+ * Distinct from `ErrorCodes` above: those are thrown `BylineError` codes;
+ * these are returned classification values. Extend with new codes (e.g. a
+ * future `STALE_RECORD` for optimistic-concurrency failures) as consumers
+ * need them.
+ */
+export declare const DbErrorCodes: {
+    readonly UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION';
+    readonly UNKNOWN: 'DB_UNKNOWN';
+};
+export type DbErrorCode = (typeof DbErrorCodes)[keyof typeof DbErrorCodes];
+export interface DbErrorClassification {
+    code: DbErrorCode;
+    /**
+     * For `DB_UNIQUE_VIOLATION`: the violated constraint / index name when the
+     * driver exposes it (Postgres carries it structurally; MySQL parses it from
+     * the error message). Absent when the driver surfaces no name.
+     */
+    constraint?: string;
+}

package/dist/lib/errors.js

@@ -164,3 +164,22 @@ export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTE
  * reconcile, while transports can distinguish it from a rolled-back mutation.
  */
 export const ERR_TREE_HOOK_COMMITTED = createErrorType(ErrorCodes.TREE_HOOK_COMMITTED, 'warn');
+// ---------------------------------------------------------------------------
+// Database error classification (adapter seam)
+// ---------------------------------------------------------------------------
+/**
+ * Code-based classification of a raw database driver error, produced by
+ * `IDbAdapter.classifyError`. The error-side analogue of the storage
+ * `normalizeRow` seam: the adapter canonicalises driver anatomy into these
+ * codes so `@byline/core` can map DB failures to domain errors (e.g.
+ * `ERR_PATH_CONFLICT`) without knowing any driver's error shape.
+ *
+ * Distinct from `ErrorCodes` above: those are thrown `BylineError` codes;
+ * these are returned classification values. Extend with new codes (e.g. a
+ * future `STALE_RECORD` for optimistic-concurrency failures) as consumers
+ * need them.
+ */
+export const DbErrorCodes = {
+    UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION',
+    UNKNOWN: 'DB_UNKNOWN',
+};

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

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

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

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

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

@@ -11,7 +11,7 @@
  * the barrel (`index.ts`), so the package's public surface is unchanged
  * by the per-operation split.
  */
-import { type CollectionDefinition, type CollectionHookSlot } from '../../@types/index.js';
+import { type CollectionDefinition, type CollectionHookSlot, type IDbAdapter } from '../../@types/index.js';
 import type { BylineLogger } from '../../lib/logger.js';
 import type { SlugifierFn } from '../../utils/slugify.js';
 import type { DocumentLifecycleContext } from './context.js';
@@ -64,20 +64,18 @@ export declare function extractVersionId(document: any): string;
 /** Extract the logical document id from the document object returned by `createDocumentVersion`. */
 export declare function extractDocumentId(document: any): string;
 /**
- * Detect a Postgres unique-constraint violation on
+ * Detect a unique-constraint violation on
  * `byline_document_paths(collection_id, locale, path)` and translate it
  * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
  *
- * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
- * the constraint name on the error object (`constraint`); matching by
- * name keeps this targeted to the path constraint and avoids spuriously
- * rebranding unrelated unique violations as path conflicts.
- *
- * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
- * original attached as `cause`, so we walk a short cause chain to find
- * the carried `code` / `constraint`.
+ * Driver anatomy (SQLSTATE codes, `cause`-chain walking, constraint-name
+ * carriage) is delegated to `db.classifyError` — the adapter seam that
+ * canonicalises a raw driver error into a `DbErrorClassification`. This
+ * function only knows the classification codes and the path constraint's
+ * name substring; it stays targeted to the path constraint so unrelated
+ * unique violations aren't spuriously rebranded as path conflicts.
  */
-export declare function rethrowPathConflict(err: unknown, path: string, locale: string): never;
+export declare function rethrowPathConflict(db: IDbAdapter, err: unknown, path: string, locale: string): never;
 /**
  * Detect whether an error is the `ERR_PATH_CONFLICT` raised by
  * `rethrowPathConflict`. Used by `duplicateDocument`'s retry logic to

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

@@ -13,7 +13,7 @@
  */
 import { normalizeCollectionHook, } from '../../@types/index.js';
 import { getCollectionDefinition, getServerConfig } from '../../config/config.js';
-import { ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
+import { DbErrorCodes, ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
 import { generateKeyBetween } from '../../lib/fractional-index.js';
 import { createReadContext } from '../populate.js';
 import { embedRichTextFields } from '../richtext-embed.js';
@@ -131,32 +131,25 @@ export function extractDocumentId(document) {
     return document?.document_id ?? '';
 }
 /**
- * Detect a Postgres unique-constraint violation on
+ * Detect a unique-constraint violation on
  * `byline_document_paths(collection_id, locale, path)` and translate it
  * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
  *
- * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
- * the constraint name on the error object (`constraint`); matching by
- * name keeps this targeted to the path constraint and avoids spuriously
- * rebranding unrelated unique violations as path conflicts.
- *
- * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
- * original attached as `cause`, so we walk a short cause chain to find
- * the carried `code` / `constraint`.
+ * Driver anatomy (SQLSTATE codes, `cause`-chain walking, constraint-name
+ * carriage) is delegated to `db.classifyError` — the adapter seam that
+ * canonicalises a raw driver error into a `DbErrorClassification`. This
+ * function only knows the classification codes and the path constraint's
+ * name substring; it stays targeted to the path constraint so unrelated
+ * unique violations aren't spuriously rebranded as path conflicts.
  */
-export function rethrowPathConflict(err, path, locale) {
-    let e = err;
-    // Walk at most a few `cause` hops — DrizzleQueryError → underlying pg error.
-    for (let i = 0; i < 3 && e; i++) {
-        if (e.code === '23505' &&
-            typeof e.constraint === 'string' &&
-            e.constraint.includes('document_paths_collection_locale_path')) {
-            throw ERR_PATH_CONFLICT({
-                message: `path "${path}" is already in use in this collection (locale: ${locale})`,
-                details: { path, locale, constraint: e.constraint },
-            });
-        }
-        e = e.cause;
+export function rethrowPathConflict(db, err, path, locale) {
+    const classification = db.classifyError?.(err);
+    if (classification?.code === DbErrorCodes.UNIQUE_VIOLATION &&
+        classification.constraint?.includes('document_paths_collection_locale_path')) {
+        throw ERR_PATH_CONFLICT({
+            message: `path "${path}" is already in use in this collection (locale: ${locale})`,
+            details: { path, locale, constraint: classification.constraint },
+        });
     }
     throw err;
 }

package/dist/services/document-lifecycle/rethrow-path-conflict.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/document-lifecycle/rethrow-path-conflict.test.node.js

@@ -0,0 +1,41 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { ErrorCodes } from '../../lib/errors.js';
+import { rethrowPathConflict } from './internals.js';
+const adapterWith = (c) => ({ classifyError: c === undefined ? undefined : () => c });
+describe('rethrowPathConflict', () => {
+    it('maps a unique violation on the path constraint to ERR_PATH_CONFLICT', () => {
+        const db = adapterWith({
+            code: 'DB_UNIQUE_VIOLATION',
+            constraint: 'byline_document_paths_document_paths_collection_locale_path',
+        });
+        try {
+            rethrowPathConflict(db, new Error('raw'), 'news/hello', 'en');
+            throw new Error('should have thrown');
+        }
+        catch (e) {
+            expect(e.code).toBe(ErrorCodes.PATH_CONFLICT);
+        }
+    });
+    it('rethrows raw when the unique violation is on a different constraint', () => {
+        const raw = new Error('raw');
+        const db = adapterWith({ code: 'DB_UNIQUE_VIOLATION', constraint: 'some_other_unique' });
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+    it('rethrows raw for DB_UNKNOWN', () => {
+        const raw = new Error('raw');
+        const db = adapterWith({ code: 'DB_UNKNOWN' });
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+    it('rethrows raw when the adapter has no classifyError', () => {
+        const raw = new Error('raw');
+        const db = adapterWith(undefined);
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+});

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

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

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

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

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

@@ -7,7 +7,7 @@
  */
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
-import { BylineError, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
+import { BylineError, DbErrorCodes, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
 import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
@@ -50,7 +50,20 @@ function createMockDb() {
     // records the calls so write-point tests can assert the audit rows emitted.
     const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
     const withTransaction = vi.fn(async (fn) => fn());
+    // 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,
         commands: {
             collections: {
                 create: vi.fn(),

package/dist/storage/store-manifest.js

@@ -186,6 +186,10 @@ export const storeColumnManifest = [
         nullCast: 'varchar',
         sources: { json: 'json_schema' },
     },
+    // nullCast 'text[]' is the one abstract null-cast type with no MySQL array
+    // equivalent; the MySQL adapter maps it to CAST(NULL AS JSON) in its UNION
+    // null casts (Postgres uses NULL::text[]). See
+    // specs/2026-07-24-db-error-classification-seam-design.md §6.
     {
         name: 'object_keys',
         nullCast: 'text[]',

package/package.json

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