@byline/db-mysql 4.8.0

package/dist/modules/storage/storage-queries.d.ts

@@ -0,0 +1,805 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * The MySQL storage read path. Ported from
+ * `packages/db-postgres/src/modules/storage/storage-queries.ts`.
+ *
+ * Task 10A landed the UNION ALL reconstruction path (`getDocumentById`,
+ * `getDocumentByVersion`, `getDocumentHistory`) and a `findDocuments` scoped
+ * to what the `versioning` + `field-types` conformance suites needed.
+ *
+ * Task 10B (this port) completes the surface: the `DocumentFilter[]`
+ * predicate compiler (`$and`/`$or` combinators, relation hops,
+ * document-column filters), `findDocuments`' `pathFilter`/`query` (LIKE
+ * search)/`sort` (`LEFT JOIN LATERAL` field sort), `getDocumentByPath`,
+ * `getDocumentsByVersionIds`, `getDocumentsByDocumentIds`,
+ * `getPublishedVersion`, `getPublishedDocumentIds`,
+ * `getDocumentCountsByStatus`, order-key / tree reads, `getCurrentPath`, and
+ * `getDocumentSystemFieldsForUpdate`. `DocumentQueries` now declares
+ * `implements IDocumentQueries`.
+ */
+import type { CollectionDefinition, DocumentFilter, FieldFilterOperator, FieldSort, FlattenedStore, ICollectionQueries, IDocumentQueries, MissingLocalePolicy, ReadMode } from '@byline/core';
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../../database/schema/index.js';
+import type { DBManager } from '../../lib/db-manager.js';
+type DatabaseConnection = MySql2Database<typeof schema>;
+/**
+ * CollectionQueries
+ *
+ * Identical to pg's — a plain query-builder read against `byline_collections`,
+ * with no dialect-specific SQL anywhere.
+ */
+export declare class CollectionQueries implements ICollectionQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    getAllCollections(): Promise<{
+        created_at: Date;
+        updated_at: Date;
+        id: string;
+        path: string;
+        singular: string;
+        plural: string;
+        config: unknown;
+        version: number;
+        schema_hash: string | null;
+    }[]>;
+    getCollectionByPath(path: string): Promise<{
+        config: unknown;
+        created_at: Date;
+        id: string;
+        path: string;
+        plural: string;
+        schema_hash: string | null;
+        singular: string;
+        updated_at: Date;
+        version: number;
+    } | undefined>;
+    getCollectionById(id: string): Promise<{
+        config: unknown;
+        created_at: Date;
+        id: string;
+        path: string;
+        plural: string;
+        schema_hash: string | null;
+        singular: string;
+        updated_at: Date;
+        version: number;
+    } | undefined>;
+}
+/**
+ * DocumentQueries
+ */
+export declare class DocumentQueries implements IDocumentQueries {
+    private db;
+    private transactionDb;
+    private collections;
+    private defaultContentLocale;
+    private collectionPathCache;
+    constructor(db: DatabaseConnection, collections: readonly CollectionDefinition[], defaultContentLocale: string, transactionDb: DBManager);
+    /**
+     * Lock the logical document row before reading its document-grain system
+     * fields. Every audited system-field writer takes this same parent-row lock,
+     * so path and advertised-locale snapshots serialize without locking a
+     * variable set of child rows.
+     *
+     * Runs on `this.transactionDb.get()` — the ambient `withTransaction`
+     * executor when one is open, else the pool — so `FOR UPDATE` (unchanged
+     * syntax from pg) actually takes its lock inside the caller's transaction.
+     * A lock taken on a bare pool connection would release at the end of its
+     * own implicit transaction and serialise nothing; see the §H ruling in the
+     * Task 10B report for why `transactionDb` is a required constructor
+     * parameter rather than a silently-defaulted one.
+     */
+    getDocumentSystemFieldsForUpdate({ collection_id, document_id, }: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<{
+        source_locale: string;
+        path: string | null;
+        availableLocales: string[];
+    } | null>;
+    /**
+     * Resolve a collection UUID to its CollectionDefinition by looking up the
+     * collection's path in the DB and matching it against the injected array.
+     */
+    private getDefinitionForCollection;
+    /**
+     * Pick the Drizzle view reference to read from based on `readMode`.
+     *
+     *   - `'any'` (default) → `current_documents` — the latest version of
+     *     each logical document, regardless of status.
+     *   - `'published'`     → `current_published_documents` — the latest
+     *     version whose status is `'published'`, falling back past newer
+     *     drafts so public readers keep seeing previously-published
+     *     content while editors work on an unpublished draft.
+     *
+     * Both views share the same row shape, so the returned reference is
+     * drop-in substitutable at every select/where site.
+     */
+    private pickCurrentView;
+    /**
+     * Build the locale priority chain for fallback resolution:
+     * `[requested, floor]`, deduplicated when both are the same. The floor is
+     * the document's own `source_locale` anchor when known (so a re-anchored
+     * document, or any document read after the global default is switched, falls
+     * back to the locale it was actually authored in) — otherwise the configured
+     * global default, which is correct for not-yet-anchored rows and for
+     * row-less lookups (findByPath). See docs/07-internationalization/index.md.
+     */
+    private buildLocaleChain;
+    /**
+     * Build the `onMissingLocale: 'omit'` availability gate — an EXISTS against
+     * the version-locale ledger (`byline_document_version_locales`) that keeps
+     * only documents available in the requested locale. The `'all'` sentinel row
+     * covers locale-agnostic documents (no localized content). Returns `null`
+     * when the gate does not apply — a non-`'omit'` policy (`'empty'` /
+     * `'fallback'` / unset), or the admin sentinel `'all'` read — so callers can
+     * conditionally push it into a WHERE. No dialect-specific SQL — ports
+     * unchanged from pg.
+     */
+    private localeAvailabilityExists;
+    /**
+     * Batch-fetch the version-locale availability sets from the
+     * `byline_document_version_locales` ledger. For each version returns the
+     * concrete locales its content is complete in (`availableLocales`, in
+     * configured content-locale order), or `localeAgnostic: true` when the
+     * version carries only the `'all'` sentinel. Drives the
+     * `_availableVersionLocales` read metadata. One indexed query per call.
+     * Plain query-builder code — ports unchanged from pg.
+     */
+    private getAvailableLocalesByVersion;
+    /**
+     * Batch-fetch the editorial advertised-locale sets from
+     * `byline_document_available_locales` (document-grain). For each logical
+     * document returns the set of locales the editor has elected to advertise,
+     * in configured content-locale order. Surfaced on reads as
+     * `availableLocales`. One indexed query per call. Plain query-builder
+     * code — ports unchanged from pg.
+     */
+    private getAdvertisedLocalesByDocument;
+    /**
+     * Emit a SQL fragment that resolves the path string for a document via
+     * the locale priority chain. Used as a projected column expression
+     * inside `SELECT` lists.
+     *
+     * Postgres:
+     * ```sql
+     * (SELECT path FROM byline_document_paths
+     *  WHERE document_id = <docIdSql> AND locale = ANY(<chain>)
+     *  ORDER BY array_position(<chain>, locale) LIMIT 1)
+     * ```
+     * MySQL has no `ANY(ARRAY[...])` or `array_position` — the locale-chain
+     * conversion (design spec §2): `IN (…)` for the membership test, and
+     * `ORDER BY FIELD(locale, …)` for the priority order. `FIELD()` returns
+     * the 1-based position of the first argument within the remaining
+     * argument list (0 if absent); since the `WHERE … IN (chain)` clause
+     * already restricts every candidate row to a locale that's a member of
+     * the chain, `FIELD()` can never actually return 0 here — every row that
+     * reaches the `ORDER BY` has a genuine position, and ascending order
+     * therefore picks the earliest (highest-priority, i.e. most-requested)
+     * chain entry first, exactly matching `array_position`'s semantics.
+     * Verified live against MySQL 9.7.1 (see the Task 10A report) and pinned
+     * by `storage-queries.test.ts`'s locale-chain-ordering test.
+     */
+    private pathProjection;
+    /**
+     * Emit a SQL fragment that resolves a `(collection_id, path)` tuple to a
+     * `document_id` via the locale priority chain. Used inside `WHERE` clauses
+     * for findByPath-style lookups. Same `IN (…)` / `FIELD()` locale-chain
+     * conversion as `pathProjection` — see that method's docblock. Returns
+     * NULL when no row matches in any locale, which makes the outer `=`
+     * predicate fail cleanly (no document found).
+     */
+    private resolveDocumentIdByPath;
+    /**
+     * Project list for `current_documents` / `current_published_documents`
+     * reads, with `path` resolved through the locale priority chain. Used
+     * everywhere a read previously did `.select()` (which auto-pulls every
+     * view column) — `path` is no longer projected by the views, so call
+     * sites must list the projection explicitly.
+     */
+    private viewProjection;
+    /**
+     * Project list for direct `byline_document_versions` reads (history,
+     * version-by-id lookups). Mirrors `viewProjection` but against the
+     * underlying table — `path` is sourced from `byline_document_paths` via
+     * the locale priority chain, since it no longer lives on the version row.
+     */
+    private documentVersionsProjection;
+    /**
+     * Resolve the single effective content locale a version should be restored
+     * in, walking the fallback chain (`[requested, default]`) and returning the
+     * first locale the version is *available* in. Pure JS/data-structure code
+     * — no SQL — ports unchanged from pg. See pg's docblock for the full
+     * phase-1 availability rule.
+     */
+    private resolveEffectiveLocale;
+    /**
+     * Reconstruct document fields from unified row values using schema-aware
+     * restoration. Meta rows (from store_meta) are converted to
+     * FlattenedFieldValue entries so that restoreFieldSetData can inject
+     * _id and _type for blocks and array items inline. Pure JS/core-delegate
+     * code — ports unchanged from pg.
+     */
+    private reconstructFromUnifiedRows;
+    /**
+     * getCurrentVersionMetadata — narrow metadata fetch for the current version.
+     *
+     * Hits `current_documents` only; no field reconstruction, no meta fetch,
+     * no path subquery. Used by lifecycle operations (status changes,
+     * restore, delete checks) that only need `document_version_id` /
+     * `status` / timestamps before mutating.
+     */
+    getCurrentVersionMetadata({ collection_id, document_id, }: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<{
+        document_version_id: string;
+        document_id: string;
+        collection_id: string;
+        status: string;
+        created_at: Date;
+        updated_at: Date;
+    } | null>;
+    /**
+     * getCurrentPath — resolve a document's canonical (source-locale) path.
+     *
+     * Reuses `pathProjection` against `current_documents`, passing
+     * `requestedLocale: undefined` so the projection's fallback floor — the
+     * document's own `source_locale` (COALESCE-guarded to the default content
+     * locale for not-yet-anchored rows) — supplies the canonical path. Used by
+     * the lifecycle to populate `path` on the status-change / unpublish hook
+     * contexts. Returns `null` when no path row (or document) exists.
+     */
+    getCurrentPath({ collection_id, document_id, }: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<string | null>;
+    /**
+     * getDocumentById — gets the current version of a document by its logical document ID.
+     *
+     * When `lenient` is true, schema-mismatch warnings emitted during
+     * reconstruction are surfaced on the returned object as `restoreWarnings`
+     * rather than thrown. This is the admin edit path's "best-effort load"
+     * mode for documents written under a previous collection schema.
+     */
+    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, lenient, onMissingLocale, }: {
+        collection_id: string;
+        document_id: string;
+        locale?: string;
+        reconstruct?: boolean;
+        readMode?: ReadMode;
+        filters?: DocumentFilter[];
+        lenient?: boolean;
+        onMissingLocale?: MissingLocalePolicy;
+    }): Promise<{
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        event_type: string;
+        created_at: Date;
+        updated_at: Date;
+        created_by: string | null;
+        fields: any;
+        availableLocales: string[];
+        _availableVersionLocales: string[];
+        _localeAgnostic: boolean;
+        restoreWarnings?: string[] | undefined;
+    } | {
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        event_type: string;
+        created_at: Date;
+        updated_at: Date;
+        created_by: string | null;
+        fields: FlattenedStore[];
+    } | null>;
+    /**
+     * getDocumentByPath — resolves `(collection_id, path)` through the locale
+     * priority chain to a document_id, then reads and reconstructs its
+     * current version. See `resolveDocumentIdByPath` for the locale-chain
+     * SQL.
+     */
+    getDocumentByPath({ collection_id, path, locale, reconstruct, readMode, filters, onMissingLocale, }: {
+        collection_id: string;
+        path: string;
+        locale?: string;
+        reconstruct: boolean;
+        readMode?: ReadMode;
+        filters?: DocumentFilter[];
+        onMissingLocale?: MissingLocalePolicy;
+    }): Promise<{
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        event_type: string;
+        created_at: Date;
+        updated_at: Date;
+        created_by: string | null;
+        fields: any;
+        availableLocales: string[];
+        _availableVersionLocales: string[];
+        _localeAgnostic: boolean;
+    } | {
+        availableLocales?: undefined;
+        _availableVersionLocales?: undefined;
+        _localeAgnostic?: undefined;
+        document_version_id: string;
+        document_id: string;
+        path: string;
+        source_locale: string;
+        status: string | null;
+        event_type: string;
+        created_at: Date;
+        updated_at: Date;
+        created_by: string | null;
+        fields: FlattenedStore[];
+    } | null>;
+    /**
+     * getDocumentByVersion — fetches a specific version and reconstructs its fields.
+     */
+    getDocumentByVersion({ document_version_id, locale, collection_id, filters, }: {
+        document_version_id: string;
+        locale?: string;
+        collection_id?: string;
+        filters?: DocumentFilter[];
+    }): Promise<any | null>;
+    /**
+     * getDocumentsByVersionIds — fetches and reconstructs multiple documents by
+     * version ID. Used for batch loading a known set of versions (e.g.
+     * migration scripts, tests).
+     */
+    getDocumentsByVersionIds({ document_version_ids, locale, }: {
+        document_version_ids: string[];
+        locale?: string;
+    }): Promise<any[]>;
+    /**
+     * getDocumentsByDocumentIds — batch-fetch current versions for a list of
+     * logical document IDs, with optional selective field loading.
+     *
+     * Resolves each document_id to its current version via the
+     * `current_documents` view (soft-deleted documents are excluded by the
+     * view definition), then delegates to `reconstructDocuments` for the
+     * shared field + meta reconstruction path.
+     *
+     * Primary consumer is the client API's relationship populate pass —
+     * `store_relation` rows carry `target_document_id` (not version ID), so
+     * populate collects those IDs and resolves them here in one round trip.
+     */
+    getDocumentsByDocumentIds({ collection_id, document_ids, locale, fields, readMode, filters, }: {
+        collection_id: string;
+        document_ids: string[];
+        locale?: string;
+        fields?: string[];
+        readMode?: ReadMode;
+        filters?: DocumentFilter[];
+    }): Promise<any[]>;
+    /**
+     * getDocumentHistory — paginated version history for a document,
+     * including soft-deleted versions.
+     */
+    getDocumentHistory({ collection_id, document_id, locale, page, page_size, order, desc: descending, filters, }: {
+        collection_id: string;
+        document_id: string;
+        locale?: string;
+        page?: number;
+        page_size?: number;
+        order?: string;
+        desc?: boolean;
+        query?: string;
+        filters?: DocumentFilter[];
+    }): Promise<{
+        documents: any[];
+        meta: {
+            total: number;
+            page: number;
+            page_size: number;
+            total_pages: number;
+            order: string;
+            desc: boolean;
+        };
+    }>;
+    /**
+     * getPublishedVersion
+     *
+     * Find the latest version of a document that has a specific status
+     * (defaults to 'published'). Queries `document_versions` directly so it
+     * can find a published version even when a newer draft exists.
+     *
+     * Returns minimal version metadata (not reconstructed content), or null
+     * if no version with the requested status exists.
+     */
+    getPublishedVersion({ collection_id, document_id, status, }: {
+        collection_id: string;
+        document_id: string;
+        status?: string;
+    }): Promise<{
+        document_version_id: string;
+        document_id: string;
+        status: string;
+        created_at: Date;
+        updated_at: Date;
+    } | null>;
+    /**
+     * getPublishedDocumentIds
+     *
+     * Given a list of document IDs, return the subset that have at least one
+     * version with the requested status (defaults to 'published'). Uses a
+     * single batch query instead of per-document lookups.
+     */
+    getPublishedDocumentIds({ collection_id, document_ids, status, }: {
+        collection_id: string;
+        document_ids: string[];
+        status?: string;
+    }): Promise<Set<string>>;
+    /**
+     * getLastOrderKey
+     *
+     * Largest `order_key` currently in use for the given collection. Used
+     * at create-time on `orderable: true` collections to append the new
+     * row at the end. Returns `null` when no keyed rows exist yet.
+     */
+    getLastOrderKey({ collection_id }: {
+        collection_id: string;
+    }): Promise<string | null>;
+    /**
+     * getNeighborOrderKeys
+     *
+     * Resolve the `order_key` values bracketing a target gap in one query.
+     * `before_document_id` is the doc the moved row should land *after*;
+     * `after_document_id` is the doc it should land *before*. Either or
+     * both may be null (append / prepend / empty collection).
+     *
+     * Resolves both keys in a single round trip to keep the read consistent
+     * with the next-key computation that follows in the caller.
+     */
+    getNeighborOrderKeys({ collection_id, before_document_id, after_document_id, }: {
+        collection_id: string;
+        before_document_id: string | null;
+        after_document_id: string | null;
+    }): Promise<{
+        left: string | null;
+        right: string | null;
+    }>;
+    /**
+     * getCanonicalDocumentOrder
+     *
+     * Returns every document in the collection in its canonical list-view
+     * order: `order_key ASC NULLS LAST, created_at DESC`. Used by the reorder
+     * server fn for backfill and recovery from key corruption.
+     *
+     * Divergence from pg: MySQL has no `NULLS LAST`. MySQL's own `ASC`
+     * default sorts NULL *first* (the opposite of pg's `NULLS LAST`), so the
+     * `(col IS NULL) ASC, col ASC` emulation idiom — the same one
+     * `buildDocumentOrderClause` uses — is required here too.
+     */
+    getCanonicalDocumentOrder({ collection_id, }: {
+        collection_id: string;
+    }): Promise<Array<{
+        id: string;
+        order_key: string | null;
+    }>>;
+    /**
+     * getTreeAncestors — see {@link IDocumentQueries.getTreeAncestors}.
+     *
+     * Recursive CTE walking `parent_document_id` upward from the given node.
+     * Returns ancestors root-first (`ORDER BY depth DESC`), each with a 1-based
+     * depth (1 = immediate parent). Empty for a root or unplaced node.
+     *
+     * Status-at-edge: in `published` mode each hop must resolve in
+     * `byline_current_published_documents`, so the walk stops at the first
+     * unpublished ancestor rather than skipping it (a truncated spine the splat
+     * handler turns into a 404). `any` mode walks the raw edges unchanged.
+     *
+     * `WITH RECURSIVE` syntax is unchanged from pg (the 8.0.14 engine floor
+     * guarantees support); the `::uuid` cast on `document_id` is dropped —
+     * MySQL has no cast syntax for a UUID-shaped `CHAR(36)` column, and the
+     * driver already binds the plain string correctly.
+     */
+    getTreeAncestors({ document_id, maxDepth, readMode, locale, filters, }: {
+        document_id: string;
+        maxDepth?: number;
+        readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
+    }): Promise<Array<{
+        document_id: string;
+        depth: number;
+    }>>;
+    /**
+     * getTreeChildren — see {@link IDocumentQueries.getTreeChildren}.
+     *
+     * Immediate children of a node ordered by the per-parent `order_key`.
+     * `parentDocumentId: null` returns the collection's root nodes; the join to
+     * `byline_documents` scopes roots to the collection (they have no parent to
+     * scope by). Plain query-builder code — ports unchanged from pg.
+     */
+    getTreeChildren({ collectionId, parentDocumentId, }: {
+        collectionId: string;
+        parentDocumentId: string | null;
+    }): Promise<Array<{
+        document_id: string;
+        order_key: string;
+    }>>;
+    /**
+     * getTreeParent — see {@link IDocumentQueries.getTreeParent}.
+     *
+     * Single indexed lookup on the edge table by `child_document_id` (unique).
+     * No row → *unplaced*; a row with a null parent → *root*; a row with a parent
+     * → *child*. Distinguishes the unplaced/root states that `getTreeAncestors`
+     * (which returns `[]` for both) conflates. `::uuid` cast dropped, same as
+     * `getTreeAncestors`.
+     */
+    getTreeParent({ document_id, readMode, locale, filters, }: {
+        document_id: string;
+        readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
+    }): Promise<{
+        placed: boolean;
+        parentDocumentId: string | null;
+        parentRedacted?: true;
+    }>;
+    /**
+     * getTreeSubtree — see {@link IDocumentQueries.getTreeSubtree}.
+     *
+     * Recursive CTE descending from the requested root (or the collection's
+     * roots when `rootDocumentId` is null). Each row carries a `/`-joined path
+     * of ancestor `order_key`s; ordering by that path yields a pre-order
+     * depth-first walk (a parent's path is a prefix of its children's, and `/`
+     * (0x2F) sorts below every key character in an ascii_bin comparison).
+     * Status-at-edge: every node — anchor included — must exist in the chosen
+     * current-documents view, so an unpublished node and its whole subtree
+     * drop out in `published` mode.
+     *
+     * Three divergences from pg, all found (or, for the third, reproduced)
+     * live — not assumed from docs:
+     *
+     *   - `s.path || '/' || r.order_key` (pg's `||` string concat) is MySQL
+     *     boolean OR unless `PIPES_AS_CONCAT` is in `sql_mode` — confirmed
+     *     against this database's `@@sql_mode` (it isn't set), and confirmed
+     *     `SELECT 'a' || 'b'` returns `0`, not `'ab'`. `CONCAT(s.path, '/',
+     *     r.order_key)` is the portable form.
+     *   - `ORDER BY path COLLATE "C"` drops the explicit collation: `order_key`
+     *     (and therefore the CONCAT'd `path` column, once the width fix below
+     *     is in place) is already `ascii_bin` — byte-comparable — end to end
+     *     (`varcharByteSorted`, `database/schema/common.ts`), confirmed live
+     *     that `CONCAT()` over two `ascii_bin` operands plus a `'/'` literal
+     *     stays `ascii_bin` rather than falling back to the connection's
+     *     `utf8mb4_0900_ai_ci` default (which would reorder mixed-case keys
+     *     incorrectly, the same class of bug `varcharByteSorted` exists to
+     *     prevent on the base columns).
+     *   - pg's `r.order_key::text AS path` cast does **two** jobs, not one —
+     *     an earlier version of this docblock dropped the cast on collation
+     *     grounds alone and missed the second job. In Postgres, `::text`
+     *     also makes the anchor column **unbounded** (`text` has no length
+     *     cap), which an accumulating concatenation needs. MySQL infers a
+     *     recursive CTE's column types from the *non-recursive* (anchor) leg
+     *     only — a bare `r.order_key` reference in the anchor makes `path`
+     *     inherit `order_key`'s declared `varchar(128)` width
+     *     (`varcharByteSorted`, `database/schema/index.ts:299`), so every
+     *     recursive iteration's `CONCAT` is silently constrained to 128
+     *     bytes regardless of how the SELECT list is written. Reproduced
+     *     live against this server (`STRICT_TRANS_TABLES` is in `sql_mode`,
+     *     so it's a hard `ER_DATA_TOO_LONG`, not silent truncation):
+     *     `WITH RECURSIVE t AS (SELECT CAST('ab' AS CHAR(128) CHARACTER SET
+     *     ascii) AS p, 1 AS n UNION ALL SELECT CONCAT(p,'/','abc…xyz'), n+1
+     *     FROM t WHERE n<6) …` → `ERROR 1406 (22001): Data too long for
+     *     column 'p' at row 1`. The threshold — `Σ len(order_key) + depth − 1
+     *     > 128` — is far more reachable than the `cte_max_recursion_depth`
+     *     ceiling this method's own docblock elsewhere flags: roughly 11–40
+     *     tree levels for typical fractional-index keys, lower once keys
+     *     have grown through repeated same-position reordering. Fix: widen
+     *     the anchor's `path` column explicitly —
+     *     `CAST(r.order_key AS CHAR(4096) CHARACTER SET ascii) COLLATE
+     *     ascii_bin` — doing both jobs the pg cast did: width (4096 bytes,
+     *     generous headroom over the reachable-depth threshold above) *and*
+     *     collation (`CHARACTER SET ascii` alone resolves to
+     *     `ascii_general_ci`, not `ascii_bin` — confirmed live that a bare
+     *     `CAST(… AS CHAR(4096))` with no `CHARACTER SET`/`COLLATE` at all
+     *     reverts to the *connection's* default collation, not the source
+     *     column's, so both clauses are required, not just one).
+     */
+    getTreeSubtree({ collectionId, rootDocumentId, maxDepth, readMode, locale, filters, }: {
+        collectionId: string;
+        rootDocumentId?: string | null;
+        maxDepth?: number;
+        readMode?: ReadMode;
+        locale?: string;
+        filters?: DocumentFilter[];
+    }): Promise<Array<{
+        document_id: string;
+        parent_document_id: string | null;
+        depth: number;
+        order_key: string;
+    }>>;
+    /**
+     * getDocumentCountsByStatus
+     *
+     * Returns a count of current documents grouped by workflow status for a
+     * given collection. Uses the `current_documents` view so each logical
+     * document is counted once (at its latest/current version).
+     */
+    getDocumentCountsByStatus({ collection_id, filters, }: {
+        collection_id: string;
+        filters?: DocumentFilter[];
+    }): Promise<Array<{
+        status: string;
+        count: number;
+    }>>;
+    /**
+     * reconstructDocuments — retrieve field values and reconstruct multiple documents.
+     * Supports selective field loading via the `fields` parameter. Pure
+     * JS/core-delegate orchestration — ports unchanged from pg (the
+     * dialect-specific work is one level down, in
+     * `getAllFieldValuesForMultipleVersions`).
+     */
+    private reconstructDocuments;
+    /**
+     * Gets all field values for a single document version.
+     * Delegates to the multi-version dynamic UNION ALL builder.
+     */
+    private getAllFieldValues;
+    /**
+     * Gets field values for multiple versions in a single query — the UNION
+     * ALL that is the whole point of this task.
+     *
+     * When `storeTypes` is provided, only those store tables are included in
+     * the UNION ALL — this is the selective field loading optimisation for
+     * list views that only need a subset of fields.
+     *
+     * Locale-chain conversion (design spec §2, the store-row locale
+     * condition): pg's `locale = ANY(ARRAY[...]) ` → MySQL `locale IN (...)`.
+     * No `ORDER BY`/`FIELD()` needed here — this is a membership filter, not a
+     * priority pick (unlike `pathProjection`, every matching locale row is
+     * kept; `resolveEffectiveLocale`/`restoreFieldSetData` pick the effective
+     * one in JS afterwards).
+     *
+     * `db.execute()` on the mysql2 driver returns a `[rows, fields]` tuple
+     * (unlike pg's `{ rows }` result object) — see `storage-commands.ts` for
+     * the established pattern this mirrors.
+     */
+    private getAllFieldValuesForMultipleVersions;
+    /**
+     * findDocuments — field-level filtered, sorted, paginated query.
+     *
+     * Each `FieldFilter` becomes an EXISTS subquery against the appropriate EAV
+     * store table. A `RelationFilter` becomes a nested EXISTS that joins
+     * `store_relation` to the target collection's current-documents view
+     * (selected by `readMode` so draft leaks can't happen through filter
+     * predicates) and recurses into its own `nested` filters. A `FieldSort`
+     * becomes a LEFT JOIN LATERAL to pull the sort value into the outer query
+     * — unchanged syntax from pg (the 8.0.14 engine floor guarantees LATERAL
+     * support), confirmed live against this container. Document-level
+     * conditions (status, path) are applied directly on the current_documents
+     * view.
+     */
+    findDocuments({ collection_id, filters, status, pathFilter, query, sort, orderBy, orderDirection, locale, page, pageSize, fields: requestedFields, readMode, onMissingLocale, }: {
+        collection_id: string;
+        filters?: DocumentFilter[];
+        status?: string;
+        pathFilter?: {
+            operator: FieldFilterOperator;
+            value: string;
+        };
+        query?: string;
+        sort?: FieldSort;
+        orderBy?: string;
+        orderDirection?: 'asc' | 'desc';
+        locale?: string;
+        page?: number;
+        pageSize?: number;
+        fields?: string[];
+        readMode?: ReadMode;
+        onMissingLocale?: MissingLocalePolicy;
+    }): Promise<{
+        documents: any[];
+        total: number;
+    }>;
+    /**
+     * Compile status and `beforeRead` visibility for one tree edge endpoint.
+     * Ports unchanged from pg — the `EXISTS` shape has no dialect-specific
+     * SQL of its own (its nested `buildFilterExists` calls carry the
+     * dialect-specific bits).
+     */
+    private buildTreeVisibility;
+    /**
+     * Build an EXISTS subquery for a single DocumentFilter. Dispatches on
+     * `kind` — field filters emit a direct EXISTS against the field's EAV
+     * store; relation filters emit a nested EXISTS that joins through
+     * `store_relation` to the target collection's current-documents view
+     * and recurses against the target's own stores; combinator filters
+     * emit a parenthesised AND/OR group; document-column filters emit a
+     * direct comparison on the outer scope's status/path column. Ports
+     * unchanged from pg — the dispatch itself has no dialect-specific SQL.
+     */
+    private buildFilterExists;
+    /**
+     * Build a parenthesised AND/OR group from a CombinatorFilter. Each child
+     * compiles through `buildFilterExists` recursively, so combinators nest
+     * freely and inherit the outer scope. Ports unchanged from pg.
+     */
+    private buildCombinatorGroup;
+    /**
+     * Compile a `DocumentColumnFilter` against the outer scope's `status`,
+     * `path`, or `id` column. Plain comparison — no EXISTS — because the
+     * column lives directly on the outer relation (current-documents view),
+     * not in the EAV stores. Ports unchanged from pg.
+     */
+    private buildDocColumnFilter;
+    /**
+     * Build an EXISTS subquery for a single field-level filter. Ports
+     * unchanged from pg (aside from `buildFilterCondition`'s `ILIKE` → `LIKE`
+     * one level down).
+     */
+    private buildFieldExists;
+    /**
+     * Build a nested EXISTS subquery for a cross-collection relation filter.
+     *
+     * Joins `store_relation` to the target collection's current-documents
+     * view (`current_published_documents` under `readMode: 'published'`,
+     * `current_documents` otherwise — so a draft target doesn't leak when
+     * the outer read is in published mode), then recurses each nested
+     * filter against the target version's own `td.id`.
+     *
+     * `hasMany` relations store one row per item at an indexed field name
+     * (`<field>.0`, `<field>.1`, …), so the field match switches to a prefix
+     * match; single relations match the exact name.
+     *
+     * The `quantifier` selects the set semantics over the relation's
+     * (resolving) targets — see pg's docblock for the full 'some'/'none'/
+     * 'every' semantics; this method ports the SQL shape unchanged.
+     */
+    private buildRelationExists;
+    /**
+     * Build a comparison condition for a filter operator.
+     *
+     * `$contains` divergence (design spec §2, elected — not "fixed"): pg's
+     * `ILIKE` has no MySQL equivalent, so this compiles to plain `LIKE`. The
+     * store `value` columns keep the schema's default `utf8mb4_0900_ai_ci`
+     * collation, which is case- *and* accent-insensitive — a strictly wider
+     * match than pg's case-insensitive-only `ILIKE`. `byline_document_paths
+     * .path` is the one column this operator also reaches (via
+     * `buildDocColumnFilter`'s `path` branch) that is NOT `ai_ci` — it's
+     * `utf8mb4_bin` (`varcharCaseSensitive`, `database/schema/common.ts`), so
+     * a `$contains` against `path` stays byte-exact and matches pg exactly.
+     * Both behaviours fall out of the column's own collation; nothing here
+     * special-cases `path` vs a store value.
+     */
+    private buildFilterCondition;
+    /**
+     * Build an ORDER BY clause for a document-level column. `path` is
+     * intentionally not sortable here — see pg's docblock.
+     *
+     * Divergence from pg (found by reasoning, confirmed live against this
+     * container): MySQL has no `NULLS LAST`. For `DESC`, MySQL already sorts
+     * NULL last by default, so `d.order_key DESC` needs no help. For `ASC`,
+     * MySQL's default sorts NULL *first* — the opposite of pg's `NULLS LAST`
+     * — so the emulation idiom `ORDER BY (col IS NULL), col ASC` is required
+     * to match pg's behaviour (`(col IS NULL)` evaluates 0/1; ascending puts
+     * real values, which evaluate to 0, before NULLs, which evaluate to 1).
+     */
+    private buildDocumentOrderClause;
+    /**
+     * Converts a union field row back into an array of FlattenedStore that
+     * the reconstruction utilities expect. Pure JS mapping — ports unchanged
+     * from pg.
+     */
+    private convertUnionRowToFlattenedStores;
+}
+export declare function createQueryBuilders(db: DatabaseConnection, collections: readonly CollectionDefinition[], defaultContentLocale: string, transactionDb: DBManager): {
+    collections: CollectionQueries;
+    documents: DocumentQueries;
+};
+export {};