@byline/core 4.8.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

@@ -40,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';
 /**
@@ -241,7 +241,7 @@ 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;
@@ -260,7 +260,7 @@ export interface IDbAdapter {
 /**
  * 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. */
@@ -305,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 {
     /**
@@ -318,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
@@ -332,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:
      *
@@ -517,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;
@@ -549,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;
@@ -563,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;
@@ -617,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;
@@ -731,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/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;
 /**

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);
 /**

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/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/internals.d.ts

@@ -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;
 /**

package/dist/services/document-lifecycle/internals.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;
@@ -179,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/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.

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.test.node.js

@@ -45,7 +45,7 @@ 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' });
@@ -210,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);
         });
@@ -806,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/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.8.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.8.0"
+    "@byline/auth": "4.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",