@byline/core 4.7.0 → 4.9.0

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

@@ -844,7 +844,7 @@ export interface AfterReadContext {
  *   - `collectionPath` — the collection being queried (useful when the
  *     same hook function is reused across collections).
  *
- * See `docs/06-auth-and-security/01-authn-authz.md` for the strategic rationale; the Quick
+ * See `docs/07-auth-and-security/01-authn-authz.md` for the strategic rationale; the Quick
  * Reference there carries six worked recipes.
  */
 export interface BeforeReadContext {
@@ -937,7 +937,7 @@ export interface CollectionHooks {
      * that the query layer ANDs onto the caller's `where` to enforce
      * read-side row scoping (multi-tenant, owner-only-drafts, soft-delete
      * hide, etc). Returning `void` applies no scoping. Multiple functions
-     * combine with implicit AND. See `docs/06-auth-and-security/01-authn-authz.md` (Read-side
+     * combine with implicit AND. See `docs/07-auth-and-security/01-authn-authz.md` (Read-side
      * scoping + Quick Reference recipes).
      */
     beforeRead?: BeforeReadHookSlot;
@@ -1042,7 +1042,7 @@ export interface CollectionDefinition {
      * of what to index. The implementor names fields by the role they play;
      * core derives each field's type from the schema and assembles the
      * type-enriched `SearchDocument` (see the `SearchProvider` seam in
-     * `docs/05-reading-and-delivery/07-search.md`). Nothing is auto-pulled, so
+     * `docs/06-search/01-configuration.md`). Nothing is auto-pulled, so
      * unindexed content (editorial notes, internal fields) never leaks into
      * the index.
      *
@@ -1131,7 +1131,7 @@ export interface CollectionDefinition {
      * collection has at least one `localized` field, so the validator rejects
      * `advertiseLocales: true` on a collection with none.
      *
-     * See `docs/07-internationalization/index.md`.
+     * See `docs/08-internationalization/index.md`.
      */
     advertiseLocales?: boolean;
     /**

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.
@@ -39,7 +40,7 @@ export type ReadMode = 'any' | 'published';
  * safe default for internal/direct reads); `@byline/client` defaults it to
  * `'fallback'` for application reads. Availability follows path-coverage against
  * the default content locale; a document with no localized content is available
- * in every locale. See `docs/07-internationalization/index.md`.
+ * in every locale. See `docs/08-internationalization/index.md`.
  */
 export type MissingLocalePolicy = 'empty' | 'fallback' | 'omit';
 /**
@@ -240,16 +241,26 @@ export interface IDbAdapter {
      * boot by `initBylineCore` so in-place upgrades self-heal without a manual
      * step or a migrate-ordering constraint — a no-op (zero rows) once every
      * document is stamped. Optional so adapters that don't model `source_locale`
-     * need not implement it. See docs/07-internationalization/index.md.
+     * need not implement it. See docs/08-internationalization/index.md.
      */
     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
  * admin-user actions, `'user'` reserved for the end-user realm, `'system'`
- * for deliberate internal-tooling writes. See docs/06-auth-and-security/02-auditability.md.
+ * for deliberate internal-tooling writes. See docs/07-auth-and-security/02-auditability.md.
  */
 export type AuditActorRealm = 'admin' | 'user' | 'system';
 /** Input to `IAuditCommands.append` — one audit-log row. */
@@ -294,7 +305,7 @@ export interface AuditLogPage {
 }
 /**
  * Append-only audit-log writes. The companion read interface is
- * `IAuditQueries`. See docs/06-auth-and-security/02-auditability.md — Workstream 2.
+ * `IAuditQueries`. See docs/07-auth-and-security/02-auditability.md — Workstream 2.
  */
 export interface IAuditCommands {
     /**
@@ -307,7 +318,7 @@ export interface IAuditCommands {
         id: string;
     }>;
 }
-/** Audit-log reads. See docs/06-auth-and-security/02-auditability.md — Workstreams 3 & 4. */
+/** Audit-log reads. See docs/07-auth-and-security/02-auditability.md — Workstreams 3 & 4. */
 export interface IAuditQueries {
     /**
      * The audit history for one document, newest first, paged. Backs the
@@ -321,7 +332,7 @@ export interface IAuditQueries {
         page_size?: number;
     }): Promise<AuditLogPage>;
     /**
-     * The system-wide activity feed (docs/06-auth-and-security/02-auditability.md — Workstream 4), newest
+     * The system-wide activity feed (docs/07-auth-and-security/02-auditability.md — Workstream 4), newest
      * first, paged and filterable. A read-time **union** of two disjoint event
      * sources, normalised onto the `AuditLogEntry` shape:
      *
@@ -506,7 +517,7 @@ export interface IDocumentCommands {
          * editorial advertised-locale set. `undefined` leaves the existing set
          * untouched (sticky across versions, like `path`); `[]` clears it. The
          * locale values are the advertised content locales themselves, not the
-         * write locale. See `docs/07-internationalization/index.md`.
+         * write locale. See `docs/08-internationalization/index.md`.
          */
         availableLocales?: string[];
         locale?: string;
@@ -538,7 +549,7 @@ export interface IDocumentCommands {
      * the change is immediate and applies across every version. Backs the admin
      * path widget's direct-write Save. The unique constraint on
      * `(collection_id, locale, path)` may surface as `ERR_PATH_CONFLICT` from the
-     * lifecycle layer. See `docs/07-internationalization/index.md`.
+     * lifecycle layer. See `docs/08-internationalization/index.md`.
      */
     updateDocumentPath(params: {
         documentId: string;
@@ -552,7 +563,7 @@ export interface IDocumentCommands {
      * wholesale **without** minting a new version or touching workflow status —
      * the change is immediate and applies across every version. `[]` clears it.
      * Backs the admin available-locales widget's direct-write Save. See
-     * `docs/07-internationalization/index.md`.
+     * `docs/08-internationalization/index.md`.
      */
     setDocumentAvailableLocales(params: {
         documentId: string;
@@ -606,7 +617,7 @@ export interface IDocumentCommands {
         documentId: string;
         locale: string;
         status?: string;
-        /** Acting user id for the version audit trail (`created_by`). See docs/06-auth-and-security/02-auditability.md. */
+        /** Acting user id for the version audit trail (`created_by`). See docs/07-auth-and-security/02-auditability.md. */
         createdBy?: string;
     }): Promise<{
         newVersionId: string;
@@ -720,7 +731,7 @@ export interface IDocumentQueries {
         /**
          * Request-scoped auth context. Adapters thread it through to
          * `assertActorCanPerform` for ability assertion and to `beforeRead`
-         * hooks for query scoping. See docs/06-auth-and-security/01-authn-authz.md.
+         * hooks for query scoping. See docs/07-auth-and-security/01-authn-authz.md.
          */
         requestContext?: RequestContext;
         /**

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

@@ -16,18 +16,19 @@
  * the provider never sees EAV store rows. The document carries a typed,
  * role-tagged field projection ({@link SearchField}) so a driver can map
  * each field onto its own index schema (Postgres store columns + weighted
- * tsvector, Solr dynamic fields, a vector store's payload, …) without
- * re-deriving types. A built-in Postgres full-text driver ships as
- * `@byline/search-postgres`; external drivers implement the same interface
- * rather than forking the read path.
+ * tsvector, MySQL FULLTEXT columns, Solr dynamic fields, a vector store's
+ * payload, …) without re-deriving types. Built-in SQL full-text drivers ship as
+ * `@byline/search-postgres` and `@byline/search-mysql`; external drivers
+ * implement the same interface rather than forking the read path.
  *
- * The provider factory (e.g. `postgresSearch({ getClient })`) lives in the
+ * The provider factory (e.g. `postgresSearch({ pool })` or
+ * `mysqlSearch({ pool })`) lives in the
  * driver package, not here — core declares only the interface and its data
  * types, the same way `RichTextPopulateFn` is declared in core while
  * `lexicalEditorPopulateServer()` lives in `@byline/richtext-lexical`. This
  * keeps `@byline/core` from depending on `@byline/client`.
  *
- * See `docs/05-reading-and-delivery/07-search.md` for the full design.
+ * See `docs/06-search/04-provider-contract.md` for the full contract.
  */
 import type { QueryPredicate } from './query-predicate.js';
 /**
@@ -138,14 +139,47 @@ export interface SearchDocument {
     /** ISO-8601 timestamp of the indexed version. */
     updatedAt: string;
 }
+/** How independently analyzed query concepts combine for full-text matching. */
+export type SearchTermOperator = 'all' | 'any';
+/**
+ * Phrase behavior for a lexical query:
+ *
+ * - `auto` — quoted spans are phrases; unquoted text follows `operator`.
+ * - `required` — the complete non-empty query is also required as a phrase.
+ * - `off` — do not create phrase constraints, including for quoted spans.
+ */
+export type SearchPhraseMode = 'auto' | 'required' | 'off';
+/**
+ * Provider-neutral full-text matching intent. Providers translate this into
+ * their native query syntax; it is product behavior, not a ranking hint.
+ */
+export interface SearchMatching {
+    /** Whether every concept or any concept must match. Defaults to `all`. */
+    operator?: SearchTermOperator;
+    /**
+     * Require at least this many concepts when `operator` is `any`.
+     * Providers that cannot express this advertise that limitation through
+     * `capabilities.fullText.minimumShouldMatch`.
+     */
+    minimumShouldMatch?: number;
+    /** Phrase handling. Defaults to `auto`. */
+    phrase?: SearchPhraseMode;
+}
+/** Maximum UTF-16 length accepted for one full-text query. */
+export declare const MAX_SEARCH_QUERY_LENGTH = 1024;
 /**
  * A search request. Either collection-scoped (`collectionPath`) for
  * homogeneous results, or zone-scoped (`zone`) for heterogeneous
  * cross-collection results — see the two `client.search()` entry points.
  */
 export interface SearchQuery {
-    /** The free-text query string. */
+    /** The free-text query string, limited to {@link MAX_SEARCH_QUERY_LENGTH}. */
     query: string;
+    /**
+     * Explicit full-text matching semantics. Defaults to all concepts required
+     * with quoted spans treated as phrases.
+     */
+    matching?: SearchMatching;
     /**
      * Cross-collection scope — every collection indexed into this zone.
      * Mutually exclusive with `collectionPath` in practice.
@@ -239,6 +273,21 @@ export interface SearchCapabilities {
     weighting: boolean;
     /** Matched-snippet highlighting in results. */
     highlights: boolean;
+    /** Detailed full-text analysis and matching capabilities. */
+    fullText: {
+        /** The backend applies its own language analyzer to original text. */
+        nativeAnalysis: boolean;
+        /** The backend can index application-produced portable logical tokens. */
+        portableAnalysis: boolean;
+        /** Supports `matching.operator: 'all'`. */
+        allTerms: boolean;
+        /** Supports `matching.operator: 'any'`. */
+        anyTerms: boolean;
+        /** Supports `matching.minimumShouldMatch`. */
+        minimumShouldMatch: boolean;
+        /** Supports ordered phrase constraints. */
+        phrase: boolean;
+    };
 }
 /**
  * The provider-agnostic search seam. A driver implements indexing
@@ -271,11 +320,11 @@ export interface SearchProvider {
     /** Execute a query and return ranked hits. */
     search(query: SearchQuery): Promise<SearchResults>;
     /**
-     * Drop and rebuild a collection's slice (or the whole index). Used for
-     * first-time backfill, driver swaps, and after a `search` config change.
-     * Optional — not every driver supports bulk rebuild.
+     * Clear a collection's slice (or the whole derived index) before the caller
+     * rebuilds it. Required because search projections are disposable and must
+     * be reproducible after analyzer, schema, or provider changes.
      */
-    reindex?(opts: {
+    reindex(opts: {
         collectionPath?: string;
     }): Promise<void>;
 }

package/dist/@types/search-types.js

@@ -5,4 +5,5 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export {};
+/** Maximum UTF-16 length accepted for one full-text query. */
+export const MAX_SEARCH_QUERY_LENGTH = 1_024;

package/dist/@types/site-config.d.ts

@@ -70,7 +70,7 @@ export interface BaseConfig {
              * its path locale, and the completeness ledger — so changing this value
              * is safe for existing data: they keep reading against the locale they
              * were authored in. New documents created after the change anchor to the
-             * new value. See docs/07-internationalization/index.md.
+             * new value. See docs/08-internationalization/index.md.
              *
              * (Switching this on a live system still needs the one-time
              * `backfillSourceLocales()` maintenance step to have stamped any rows
@@ -109,7 +109,7 @@ export interface BaseConfig {
          *
          * Optional at the type level so `BaseConfig` stays loose for tests
          * and seed scripts; required at runtime via `validateTranslations`
-         * whenever `interface.locales` is non-empty. See `docs/07-internationalization/index.md` for
+         * whenever `interface.locales` is non-empty. See `docs/08-internationalization/index.md` for
          * the design.
          *
          * The shape is declared inline (rather than imported from
@@ -415,10 +415,10 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      * beside `db` and `storage`, composed by `initBylineCore()`.
      *
      * Drivers ship as separate packages and are constructed via a factory,
-     * mirroring the richText server adapters. The built-in Postgres
-     * full-text driver is `@byline/search-postgres`. When any collection
-     * opts into search (`CollectionDefinition.search`) but no provider is
-     * registered, `initBylineCore()` fails fast.
+     * mirroring the richText server adapters. The built-in SQL full-text drivers
+     * are `@byline/search-postgres` and `@byline/search-mysql`. When any
+     * collection opts into search (`CollectionDefinition.search`) but no
+     * provider is registered, `initBylineCore()` fails fast.
      *
      * @example
      * ```ts
@@ -426,7 +426,7 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      *
      * defineServerConfig({
      *   // ...
-     *   search: postgresSearch({ getClient: getAdminBylineClient }),
+     *   search: postgresSearch({ pool: db.pool }),
      * })
      * ```
      */

package/dist/auth/assert-actor-can-perform.d.ts

@@ -33,6 +33,6 @@ import { type CollectionAbilityVerb } from './register-collection-abilities.js';
  * bypass this helper — the same escape hatch that skips collection
  * hooks. Seeds, migrations, and internal tooling live there.
  *
- * See docs/06-auth-and-security/01-authn-authz.md.
+ * See docs/07-auth-and-security/01-authn-authz.md.
  */
 export declare function assertActorCanPerform(context: RequestContext | undefined, collectionPath: string, verb: CollectionAbilityVerb): void;

package/dist/auth/assert-actor-can-perform.js

@@ -33,7 +33,7 @@ import { collectionAbilityKey, } from './register-collection-abilities.js';
  * bypass this helper — the same escape hatch that skips collection
  * hooks. Seeds, migrations, and internal tooling live there.
  *
- * See docs/06-auth-and-security/01-authn-authz.md.
+ * See docs/07-auth-and-security/01-authn-authz.md.
  */
 export function assertActorCanPerform(context, collectionPath, verb) {
     if (!context) {

package/dist/auth/register-collection-abilities.d.ts

@@ -32,7 +32,7 @@ import type { CollectionDefinition } from '../@types/index.js';
  * predictable and avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/06-auth-and-security/01-authn-authz.md.
+ * docs/07-auth-and-security/01-authn-authz.md.
  */
 export declare function registerCollectionAbilities(registry: AbilityRegistry, definition: CollectionDefinition): void;
 /** The ability suffixes that every collection contributes. Exposed for contract tests. */

package/dist/auth/register-collection-abilities.js

@@ -30,7 +30,7 @@
  * predictable and avoids hidden conditional logic downstream.
  *
  * Called from `initBylineCore()` for each declared collection. See
- * docs/06-auth-and-security/01-authn-authz.md.
+ * docs/07-auth-and-security/01-authn-authz.md.
  */
 export function registerCollectionAbilities(registry, definition) {
     const path = definition.path;

package/dist/config/config.d.ts

@@ -51,7 +51,7 @@ export declare function getServerConfig(): ResolvedServerConfig;
  * config-driven at the read source. The payoff is canonical downstream
  * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
  * the order a document declared its locales in. Read-time projection only;
- * nothing persisted changes. See docs/07-internationalization/index.md.
+ * nothing persisted changes. See docs/08-internationalization/index.md.
  */
 export declare function orderByContentLocale(codes: string[]): string[];
 export declare function defineBylineCore(core: unknown): void;

package/dist/config/config.js

@@ -147,7 +147,7 @@ export function getServerConfig() {
  * config-driven at the read source. The payoff is canonical downstream
  * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
  * the order a document declared its locales in. Read-time projection only;
- * nothing persisted changes. See docs/07-internationalization/index.md.
+ * nothing persisted changes. See docs/08-internationalization/index.md.
  */
 export function orderByContentLocale(codes) {
     const content = getServerConfigInstance()?.i18n?.content;

package/dist/core.d.ts

@@ -38,7 +38,7 @@ export interface BylineCore<TAdminStore = unknown> {
      * during server bootstrap and before any admin UI renders.
      *
      * Consumed at runtime by `AdminAuth.assertAbility()` and at design
-     * time by the admin role-editor UI. See docs/06-auth-and-security/01-authn-authz.md.
+     * time by the admin role-editor UI. See docs/07-auth-and-security/01-authn-authz.md.
      */
     abilities: AbilityRegistry;
     /** Convenience wrapper around `abilities.register()`. */

package/dist/core.js

@@ -105,7 +105,7 @@ export const initBylineCore = async (config, pinoLogger) => {
     // and is a no-op (zero rows) once every document is stamped. Self-heals
     // in-place upgrades without a manual maintenance step. The write path stamps
     // new documents directly, so steady-state boots touch nothing. See
-    // docs/07-internationalization/index.md.
+    // docs/08-internationalization/index.md.
     if (typeof composed.db.backfillSourceLocales === 'function') {
         const { rowsUpdated } = await composed.db.backfillSourceLocales();
         if (rowsUpdated > 0) {

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

@@ -118,7 +118,7 @@ export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstruc
  * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
  * user error: an auditability guarantee cannot be honoured non-atomically, so
  * the write is refused loudly rather than recorded with a gap. See
- * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
+ * 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;
 /**
@@ -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

@@ -155,7 +155,7 @@ export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn
  * `commands.audit` / `queries.audit` surfaces. A misconfiguration, not a
  * user error: an auditability guarantee cannot be honoured non-atomically, so
  * the write is refused loudly rather than recorded with a gap. See
- * docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
+ * docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTED);
 /**
@@ -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/schemas/zod/builder.js

@@ -247,7 +247,7 @@ export const createBaseSchema = (collection) => {
         id: z.uuid(),
         versionId: z.uuid().optional(),
         path: z.string().optional(),
-        // The document's content source-locale anchor (see docs/07-internationalization/index.md).
+        // The document's content source-locale anchor (see docs/08-internationalization/index.md).
         // Carried through list/get responses so the admin can badge it; Zod would
         // otherwise strip it as an undeclared key.
         sourceLocale: z.string().optional(),
@@ -255,7 +255,7 @@ export const createBaseSchema = (collection) => {
         hasPublishedVersion: z.boolean().optional(),
         createdAt: z.iso.datetime(),
         updatedAt: z.iso.datetime(),
-        // Version audit metadata — acting user + action (see docs/06-auth-and-security/02-auditability.md — Workstream 1).
+        // Version audit metadata — acting user + action (see docs/07-auth-and-security/02-auditability.md — Workstream 1).
         // Declared so list/get/history responses carry them through the
         // server-fn parse; Zod would otherwise strip them as undeclared keys.
         createdBy: z.uuid().optional(),

package/dist/services/build-search-document.d.ts

@@ -10,7 +10,7 @@
  * `SearchProvider` seam. Walks a collection's role-based `search` config
  * against one locale-resolved document and emits a single, type-enriched
  * `SearchDocument` for a driver to index. See
- * `docs/05-reading-and-delivery/07-search.md`.
+ * `docs/06-search/04-provider-contract.md`.
  *
  * Role-based and explicit: only the fields named in `search.{body,facets,
  * filters}` are projected — nothing is auto-pulled, so unindexed content

package/dist/services/build-search-document.js

@@ -10,7 +10,7 @@
  * `SearchProvider` seam. Walks a collection's role-based `search` config
  * against one locale-resolved document and emits a single, type-enriched
  * `SearchDocument` for a driver to index. See
- * `docs/05-reading-and-delivery/07-search.md`.
+ * `docs/06-search/04-provider-contract.md`.
  *
  * Role-based and explicit: only the fields named in `search.{body,facets,
  * filters}` are projected — nothing is auto-pulled, so unindexed content

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

@@ -51,7 +51,7 @@ export interface TreeAuditCapability extends AuditCapability {
  * **both** `withTransaction` and `commands.audit`. Returns a non-null
  * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
  * rather than silently skipping the audit row or running it non-atomically.
- * See docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
+ * See docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export declare function requireAuditCapability(db: IDbAdapter): AuditCapability;
 /**

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

@@ -7,7 +7,7 @@
  */
 /**
  * Audit-log write helpers for the document-grain lifecycle write-points
- * (docs/06-auth-and-security/02-auditability.md — Workstream 2). The audit log records the changes the
+ * (docs/07-auth-and-security/02-auditability.md — Workstream 2). The audit log records the changes the
  * immutable version stream does NOT capture an actor for: non-versioned
  * system-field writes (path, available-locales), in-place status transitions,
  * and deletions. Each such mutation and its audit row commit atomically inside
@@ -46,7 +46,7 @@ export function auditActor(ctx) {
  * **both** `withTransaction` and `commands.audit`. Returns a non-null
  * capability the caller composes; throws `ERR_AUDIT_UNSUPPORTED` otherwise,
  * rather than silently skipping the audit row or running it non-atomically.
- * See docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
+ * See docs/03-architecture/03-transactions.md and docs/07-auth-and-security/02-auditability.md.
  */
 export function requireAuditCapability(db) {
     const withTransaction = db.withTransaction;

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

@@ -73,7 +73,7 @@ export interface DocumentLifecycleContext {
      * — `assertActorCanPerform` runs at every lifecycle entry and rejects
      * a missing context.
      *
-     * See docs/06-auth-and-security/01-authn-authz.md.
+     * See docs/07-auth-and-security/01-authn-authz.md.
      */
     requestContext?: RequestContext;
 }

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

@@ -39,7 +39,7 @@ export declare function createDocument(ctx: DocumentLifecycleContext, params: {
      * sidebar widget). Document-grain and sticky like `path`: passed straight
      * to the storage primitive, which replaces the document's rows wholesale.
      * `undefined` writes nothing (a new document starts with an empty set —
-     * the safe opt-in default); `[]` clears it. See docs/07-internationalization/index.md.
+     * the safe opt-in default); `[]` clears it. See docs/08-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<CreateDocumentResult>;

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/delete.js

@@ -124,7 +124,7 @@ export async function deleteDocument(ctx, params) {
         //    back, so soft-deleted documents cannot leak live edges.
         //    whole-document delete mints no new version, so the version stream
         //    never records it — the audit log is the only place a deletion is
-        //    accountable (docs/06-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
+        //    accountable (docs/07-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
         //    DB↔external side-effect and stays OUTSIDE the transaction — it is
         //    post-commit, best-effort compensation (docs/03-architecture/03-transactions.md).
         const treeAudit = definition.tree === true ? requireTreeAuditCapability(db) : undefined;

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';
@@ -28,7 +28,7 @@ import type { DocumentLifecycleContext } from './context.js';
  * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
  * `created_by`, which the history strip renders as "unknown". Real
  * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
- * is unaffected. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
+ * is unaffected. See docs/07-auth-and-security/02-auditability.md — Workstream 1.
  */
 export declare function actorId(ctx: DocumentLifecycleContext): string | undefined;
 /**
@@ -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';
@@ -36,7 +36,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * (the seeds/migrations escape hatch) — both yield `undefined` → NULL
  * `created_by`, which the history strip renders as "unknown". Real
  * `AdminAuth` / `UserAuth` actors always carry UUID ids, so their attribution
- * is unaffected. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
+ * is unaffected. See docs/07-auth-and-security/02-auditability.md — Workstream 1.
  */
 export function actorId(ctx) {
     const id = ctx.requestContext?.actor?.id;
@@ -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;
 }
@@ -186,7 +179,7 @@ export function resolvePathForUpdate(args) {
         // skip the write (existing path row stays as-is — sticky). The path row
         // lives under the document's source_locale (its anchor), not the mutable
         // global default — so this stays correct after the global default is
-        // switched. See docs/07-internationalization/index.md.
+        // switched. See docs/08-internationalization/index.md.
         return explicitPath ?? undefined;
     }
     // Non-source-locale (translation) write: reject any path change with a warn

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/status.js

@@ -89,7 +89,7 @@ export async function changeDocumentStatus(ctx, params) {
         // 4–5. Mutate status in-place + auto-archive, atomically with the audit
         //      record. Status mutates the version row rather than minting a new
         //      version, so the version stream never captures *who* changed it —
-        //      the audit log is its only accountability home (docs/06-auth-and-security/02-auditability.md).
+        //      the audit log is its only accountability home (docs/07-auth-and-security/02-auditability.md).
         const audit = requireAuditCapability(db);
         const actor = auditActor(ctx);
         await audit.withTransaction(async () => {

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

@@ -31,7 +31,7 @@ export interface UpdateDocumentSystemFieldsResult {
  * version. This service backs the admin path / available-locales widgets'
  * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
  * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/07-internationalization/index.md.
+ * the resolved version's completeness ledger. See docs/08-internationalization/index.md.
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.

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

@@ -23,7 +23,7 @@ import { invokeHook, resolvePathForUpdate, rethrowPathConflict } from './interna
  * version. This service backs the admin path / available-locales widgets'
  * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
  * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/07-internationalization/index.md.
+ * the resolved version's completeness ledger. See docs/08-internationalization/index.md.
  *
  * Flow:
  *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
@@ -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.d.ts

@@ -43,7 +43,7 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
      * The editorial advertised-locale set. `undefined` leaves the existing
      * set untouched (sticky — document-grain, like `path`); an explicit array
      * (empty included) replaces it wholesale. Driven by the admin
-     * available-locales sidebar widget. See docs/07-internationalization/index.md.
+     * available-locales sidebar widget. See docs/08-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentResult>;
@@ -78,7 +78,7 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      * The editorial advertised-locale set (typically supplied alongside
      * patches when the admin available-locales widget has been edited).
      * `undefined` leaves the existing set untouched (sticky); an explicit
-     * array replaces it wholesale. See docs/07-internationalization/index.md.
+     * array replaces it wholesale. See docs/08-internationalization/index.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentWithPatchesResult>;

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
@@ -45,12 +45,25 @@ function createMockDb() {
     const getDocumentSystemFieldsForUpdate = vi.fn().mockResolvedValue(null);
     const getCurrentVersionMetadata = vi.fn().mockResolvedValue(null);
     const getCurrentPath = vi.fn().mockResolvedValue('current-path');
-    // Audit capability (docs/06-auth-and-security/02-auditability.md — W2). `withTransaction` is a passthrough
+    // 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' });
     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(),
@@ -197,7 +210,7 @@ describe('Document lifecycle service', () => {
                 data: { title: 'Hello' },
                 locale: 'en',
             });
-            // Audit contract (docs/06-auth-and-security/02-auditability.md — W1): every version row
+            // Audit contract (docs/07-auth-and-security/02-auditability.md — W1): every version row
             // records the actor that created it.
             expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe(TEST_ACTOR_ID);
         });
@@ -793,7 +806,7 @@ describe('Document lifecycle service', () => {
             getCurrentVersionMetadata.mockResolvedValue({ ...metadataRow });
             const ctx = buildCtx(db);
             await changeDocumentStatus(ctx, { documentId: 'doc-1', nextStatus: 'published' });
-            // The mutation + audit row run inside one withTransaction (docs/06-auth-and-security/02-auditability.md).
+            // The mutation + audit row run inside one withTransaction (docs/07-auth-and-security/02-auditability.md).
             expect(withTransaction).toHaveBeenCalledOnce();
             expect(auditAppend).toHaveBeenCalledWith(expect.objectContaining({
                 documentId: 'doc-1',

package/dist/services/validate-search-config.js

@@ -27,6 +27,6 @@ export function validateSearchConfig(collections, adapters) {
         return;
     throw new Error(`initBylineCore: ${optedIn.length} collection(s) opt into search ` +
         `(${optedIn.join(', ')}) but no search provider is registered. ` +
-        `Wire one via ServerConfig.search — see \`@byline/search-postgres\` → ` +
-        `\`postgresSearch()\` for the built-in Postgres full-text driver.`);
+        `Wire one via ServerConfig.search — use \`postgresSearch()\` from ` +
+        `\`@byline/search-postgres\` or \`mysqlSearch()\` from \`@byline/search-mysql\`.`);
 }

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.9.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.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",