@byline/core 1.10.3 → 1.11.0

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

@@ -179,6 +179,23 @@ export interface CollectionAdminConfig<T = any> {
     slug: string;
     /** Group name for organising collections in the admin sidebar. */
     group?: string;
+    /**
+     * When true, documents in this collection carry a fractional-index
+     * `order_key` and the list view sorts by it ascending by default, with
+     * drag-to-reorder enabled in the admin UI.
+     *
+     * Storage: `byline_documents.order_key` — admin metadata, never per-version
+     * and never EAV. Reordering writes the single column and does NOT mint a
+     * new document version.
+     *
+     * Backfill: existing rows in newly-`orderable` collections start with
+     * `order_key = NULL`. They sort to the bottom (NULLS LAST) until the
+     * editor drags them into position.
+     *
+     * Orthogonal to `hasMany` array order. Use this for top-level order
+     * inside a collection (bios, team members, FAQ items, sections).
+     */
+    orderable?: boolean;
     /** Column definitions for the collection list view. */
     columns?: ColumnDefinition<T>[];
     /**

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

@@ -226,6 +226,14 @@ export interface IDocumentCommands {
          * into the new one so that per-locale content is not lost.
          */
         previousVersionId?: string;
+        /**
+         * Fractional-index order key written onto the new `byline_documents` row.
+         * Only set on the initial create (when `documentId` is undefined) for
+         * collections with `orderable: true`. Ignored on subsequent versions of
+         * an existing document — order is admin metadata on the logical document,
+         * not per-version content. See docs/ORDERABLE.md.
+         */
+        orderKey?: string;
     }): Promise<{
         document: any;
         fieldCount: number;
@@ -263,6 +271,18 @@ export interface IDocumentCommands {
     softDeleteDocument(params: {
         document_id: string;
     }): Promise<number>;
+    /**
+     * Write the fractional-index `order_key` on a single `byline_documents`
+     * row. Used by the reorder server fn for `orderable: true` collections.
+     *
+     * This is a single-column metadata update — it does NOT create a new
+     * document version and does NOT touch `documentVersions`. `updated_at`
+     * on the row is refreshed so list-view caches can invalidate cleanly.
+     */
+    setOrderKey(params: {
+        document_id: string;
+        order_key: string;
+    }): Promise<void>;
 }
 export interface ICollectionQueries {
     getAllCollections(): Promise<any[]>;
@@ -478,4 +498,57 @@ export interface IDocumentQueries {
         documents: any[];
         total: number;
     }>;
+    /**
+     * Return the largest `order_key` currently in use for the given collection,
+     * or `null` if there are no keyed rows yet. Used at create-time on
+     * `orderable: true` collections to append the new row to the end.
+     *
+     * Ignores `is_deleted` rows (soft-deleted documents) and rows with a
+     * NULL `order_key`. If every document in the collection is unkeyed,
+     * returns `null` and the caller seeds the first key from scratch.
+     */
+    getLastOrderKey(params: {
+        collection_id: string;
+    }): Promise<string | null>;
+    /**
+     * Resolve the `order_key` values immediately bracketing a target gap.
+     *
+     * Called by the reorder server fn. The caller passes the IDs of the
+     * documents the dragged row should land **between** (`before` is the doc
+     * that should come immediately before, `after` immediately after). Either
+     * can be `null` to mean "the end" (`after: null`) or "the start"
+     * (`before: null`); both null is "append to a collection with no rows."
+     *
+     * Resolving keys in one query (instead of two round-trips that read
+     * each neighbor separately) keeps the read consistent with the moment
+     * the next-key computation runs, so concurrent reorders don't race into
+     * a degenerate gap.
+     */
+    getNeighborOrderKeys(params: {
+        collection_id: string;
+        before_document_id: string | null;
+        after_document_id: string | null;
+    }): Promise<{
+        left: string | null;
+        right: string | null;
+    }>;
+    /**
+     * Return every document in the collection in its canonical list-view
+     * order: `order_key ASC NULLS LAST, created_at DESC`. Keyed rows come
+     * first (in key order), then any unkeyed rows fall through to newest-
+     * first by creation time — exactly what the editor sees in the list
+     * view today.
+     *
+     * Used by the reorder server fn to lazily backfill unkeyed rows AND to
+     * detect / recover from pathological key state (duplicates, descending
+     * runs) by re-keying the entire collection in displayed order. Collection
+     * sizes for `orderable` use cases are small by design (bios, FAQs,
+     * sections), so the full read is cheap.
+     */
+    getCanonicalDocumentOrder(params: {
+        collection_id: string;
+    }): Promise<Array<{
+        id: string;
+        order_key: string | null;
+    }>>;
 }

package/dist/index.d.ts

@@ -7,6 +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 { BylineError, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_STORAGE, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, } 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';
 export * from './patches/index.js';

package/dist/index.js

@@ -23,6 +23,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { BylineError, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_STORAGE, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, } 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';
 export * from './patches/index.js';

package/dist/lib/fractional-index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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
+ *
+ * Fractional-index keys for stable, drag-and-drop reordering without a
+ * rebalancing pass. Keys are base-62 strings that sort lexicographically;
+ * `generateKeyBetween(a, b)` produces a new key strictly between two
+ * neighbors (or before/after a single neighbor when the other is null).
+ *
+ * Implementation follows David Greenspan's algorithm
+ * (https://observablehq.com/@dgreensp/implementing-fractional-indexing).
+ * Each key has two parts: a head character that encodes the integer-part
+ * length, followed by the integer digits and an optional base-62 fraction.
+ * Heads 'A'..'Z' carry positive integer-part lengths 2..27; heads 'a'..'z'
+ * carry negative integer-part lengths 2..27. This allows unbounded
+ * prepend/append without ever needing a rebalance.
+ *
+ * Used by `orderable: true` collections to drive the
+ * `byline_documents.order_key` column.
+ */
+/**
+ * Validate a complete order_key — head + integer + optional fraction.
+ * Returns true if the key is well-formed; false otherwise. Does not throw.
+ */
+export declare function validateOrderKey(key: string): boolean;
+/**
+ * Generate an order_key strictly between `a` and `b`.
+ *
+ * - `(null, null)` returns a midpoint near zero
+ * - `(a, null)` returns a key greater than `a`
+ * - `(null, b)` returns a key less than `b`
+ * - `(a, b)` returns a key strictly between (requires `a < b`)
+ *
+ * Throws if `a >= b`, if either key is malformed, or if the integer
+ * head is already at its extreme bound (effectively never under normal
+ * use — would require ~10^40 unbounded prepends or appends).
+ */
+export declare function generateKeyBetween(a: string | null, b: string | null): string;
+/**
+ * Generate `n` order_keys strictly between `a` and `b`, in ascending order.
+ * Used when inserting a contiguous run of rows (bulk import, multi-select drop).
+ */
+export declare function generateNKeysBetween(a: string | null, b: string | null, n: number): string[];

package/dist/lib/fractional-index.js

@@ -0,0 +1,265 @@
+/**
+ * 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
+ *
+ * Fractional-index keys for stable, drag-and-drop reordering without a
+ * rebalancing pass. Keys are base-62 strings that sort lexicographically;
+ * `generateKeyBetween(a, b)` produces a new key strictly between two
+ * neighbors (or before/after a single neighbor when the other is null).
+ *
+ * Implementation follows David Greenspan's algorithm
+ * (https://observablehq.com/@dgreensp/implementing-fractional-indexing).
+ * Each key has two parts: a head character that encodes the integer-part
+ * length, followed by the integer digits and an optional base-62 fraction.
+ * Heads 'A'..'Z' carry positive integer-part lengths 2..27; heads 'a'..'z'
+ * carry negative integer-part lengths 2..27. This allows unbounded
+ * prepend/append without ever needing a rebalance.
+ *
+ * Used by `orderable: true` collections to drive the
+ * `byline_documents.order_key` column.
+ */
+const ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const SMALLEST_INTEGER = 'A00000000000000000000000000';
+const INTEGER_ZERO = 'a0';
+function getIntegerLength(head) {
+    if (head === undefined)
+        throw new Error('invalid order_key head: empty');
+    if (head >= 'a' && head <= 'z')
+        return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2;
+    if (head >= 'A' && head <= 'Z')
+        return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2;
+    throw new Error(`invalid order_key head: ${head}`);
+}
+function getIntegerPart(key) {
+    const len = getIntegerLength(key[0]);
+    if (len > key.length)
+        throw new Error(`invalid order_key (truncated integer): ${key}`);
+    return key.slice(0, len);
+}
+function validateInteger(int) {
+    if (int.length !== getIntegerLength(int[0])) {
+        throw new Error(`invalid order_key integer part: ${int}`);
+    }
+}
+function charAt(s, i) {
+    const c = s[i];
+    if (c === undefined)
+        throw new Error(`order_key out-of-bounds at ${i}: ${s}`);
+    return c;
+}
+/**
+ * Validate a complete order_key — head + integer + optional fraction.
+ * Returns true if the key is well-formed; false otherwise. Does not throw.
+ */
+export function validateOrderKey(key) {
+    if (typeof key !== 'string' || key.length === 0)
+        return false;
+    try {
+        const int = getIntegerPart(key);
+        validateInteger(int);
+        // Every char must be in the alphabet (integer digits + fraction).
+        for (let i = 1; i < key.length; i++) {
+            if (ALPHABET.indexOf(charAt(key, i)) === -1)
+                return false;
+        }
+        // No trailing zero in the fraction part — keeps representations unique.
+        if (key.length > int.length && charAt(key, key.length - 1) === '0')
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function incrementInteger(x) {
+    validateInteger(x);
+    const head = charAt(x, 0);
+    const digs = x.slice(1).split('');
+    let carry = true;
+    for (let i = digs.length - 1; carry && i >= 0; i--) {
+        const d = ALPHABET.indexOf(digs[i]) + 1;
+        if (d === ALPHABET.length) {
+            digs[i] = '0';
+        }
+        else {
+            digs[i] = charAt(ALPHABET, d);
+            carry = false;
+        }
+    }
+    if (carry) {
+        if (head === 'Z') {
+            return `a${charAt(ALPHABET, 0)}`;
+        }
+        if (head === 'z')
+            return null;
+        const headCode = head.charCodeAt(0) + 1;
+        const newHead = String.fromCharCode(headCode);
+        if (newHead > 'a') {
+            digs.push('0');
+        }
+        else {
+            digs.pop();
+        }
+        return newHead + digs.join('');
+    }
+    return head + digs.join('');
+}
+function decrementInteger(x) {
+    validateInteger(x);
+    const head = charAt(x, 0);
+    const digs = x.slice(1).split('');
+    const lastAlpha = charAt(ALPHABET, ALPHABET.length - 1);
+    let borrow = true;
+    for (let i = digs.length - 1; borrow && i >= 0; i--) {
+        const d = ALPHABET.indexOf(digs[i]) - 1;
+        if (d === -1) {
+            digs[i] = lastAlpha;
+        }
+        else {
+            digs[i] = charAt(ALPHABET, d);
+            borrow = false;
+        }
+    }
+    if (borrow) {
+        if (head === 'a') {
+            return `Z${lastAlpha}`;
+        }
+        if (head === 'A')
+            return null;
+        const headCode = head.charCodeAt(0) - 1;
+        const newHead = String.fromCharCode(headCode);
+        if (newHead < 'a') {
+            digs.push(lastAlpha);
+        }
+        else {
+            digs.pop();
+        }
+        return newHead + digs.join('');
+    }
+    return head + digs.join('');
+}
+/**
+ * Find the "midpoint" fraction strictly between two fraction strings (a, b).
+ * Both inputs are the fraction portion only (everything after the integer
+ * part), and must not have a trailing '0'. Either can be empty / null.
+ */
+function midpoint(a, b) {
+    if (b !== null && a >= b) {
+        throw new Error(`midpoint: a >= b (${a}, ${b})`);
+    }
+    if (a.slice(-1) === '0' || (b && b.slice(-1) === '0')) {
+        throw new Error('midpoint: trailing zero');
+    }
+    if (b !== null) {
+        let n = 0;
+        while ((a[n] ?? '0') === b[n])
+            n++;
+        if (n > 0) {
+            return b.slice(0, n) + midpoint(a.slice(n), b.slice(n));
+        }
+    }
+    const digitA = a ? ALPHABET.indexOf(charAt(a, 0)) : 0;
+    const digitB = b !== null && b.length > 0 ? ALPHABET.indexOf(charAt(b, 0)) : ALPHABET.length;
+    if (digitB - digitA > 1) {
+        const midDigit = Math.round(0.5 * (digitA + digitB));
+        return charAt(ALPHABET, midDigit);
+    }
+    if (b !== null && b.length > 1) {
+        return b.slice(0, 1);
+    }
+    return charAt(ALPHABET, digitA) + midpoint(a.slice(1), null);
+}
+/**
+ * Generate an order_key strictly between `a` and `b`.
+ *
+ * - `(null, null)` returns a midpoint near zero
+ * - `(a, null)` returns a key greater than `a`
+ * - `(null, b)` returns a key less than `b`
+ * - `(a, b)` returns a key strictly between (requires `a < b`)
+ *
+ * Throws if `a >= b`, if either key is malformed, or if the integer
+ * head is already at its extreme bound (effectively never under normal
+ * use — would require ~10^40 unbounded prepends or appends).
+ */
+export function generateKeyBetween(a, b) {
+    if (a !== null && !validateOrderKey(a)) {
+        throw new Error(`generateKeyBetween: invalid 'a' (${a})`);
+    }
+    if (b !== null && !validateOrderKey(b)) {
+        throw new Error(`generateKeyBetween: invalid 'b' (${b})`);
+    }
+    if (a !== null && b !== null && a >= b) {
+        throw new Error(`generateKeyBetween: a >= b (${a} >= ${b})`);
+    }
+    if (a === null) {
+        if (b === null)
+            return INTEGER_ZERO;
+        const ib = getIntegerPart(b);
+        const fb = b.slice(ib.length);
+        if (ib === SMALLEST_INTEGER) {
+            return ib + midpoint('', fb);
+        }
+        if (ib < b)
+            return ib;
+        const res = decrementInteger(ib);
+        if (res === null) {
+            throw new Error('generateKeyBetween: cannot decrement past lower bound');
+        }
+        return res;
+    }
+    if (b === null) {
+        const ia = getIntegerPart(a);
+        const fa = a.slice(ia.length);
+        const i = incrementInteger(ia);
+        return i === null ? ia + midpoint(fa, null) : i;
+    }
+    const ia = getIntegerPart(a);
+    const fa = a.slice(ia.length);
+    const ib = getIntegerPart(b);
+    const fb = b.slice(ib.length);
+    if (ia === ib) {
+        return ia + midpoint(fa, fb);
+    }
+    const i = incrementInteger(ia);
+    if (i === null) {
+        throw new Error('generateKeyBetween: cannot increment past upper bound');
+    }
+    if (i < b)
+        return i;
+    return ia + midpoint(fa, null);
+}
+/**
+ * Generate `n` order_keys strictly between `a` and `b`, in ascending order.
+ * Used when inserting a contiguous run of rows (bulk import, multi-select drop).
+ */
+export function generateNKeysBetween(a, b, n) {
+    if (n === 0)
+        return [];
+    if (n === 1)
+        return [generateKeyBetween(a, b)];
+    if (b === null) {
+        let c = generateKeyBetween(a, b);
+        const result = [c];
+        for (let i = 0; i < n - 1; i++) {
+            c = generateKeyBetween(c, b);
+            result.push(c);
+        }
+        return result;
+    }
+    if (a === null) {
+        let c = generateKeyBetween(a, b);
+        const result = [c];
+        for (let i = 0; i < n - 1; i++) {
+            c = generateKeyBetween(a, c);
+            result.push(c);
+        }
+        result.reverse();
+        return result;
+    }
+    const mid = Math.floor(n / 2);
+    const c = generateKeyBetween(a, b);
+    return [...generateNKeysBetween(a, c, mid), c, ...generateNKeysBetween(c, b, n - mid - 1)];
+}

package/dist/lib/fractional-index.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/lib/fractional-index.test.node.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { generateKeyBetween, generateNKeysBetween, validateOrderKey } from './fractional-index.js';
+describe('fractional-index', () => {
+    describe('generateKeyBetween — bounded cases', () => {
+        it('returns the canonical zero key for (null, null)', () => {
+            const k = generateKeyBetween(null, null);
+            expect(k).toBe('a0');
+            expect(validateOrderKey(k)).toBe(true);
+        });
+        it('produces a key strictly greater than `a` for (a, null)', () => {
+            const a = generateKeyBetween(null, null);
+            const b = generateKeyBetween(a, null);
+            expect(b > a).toBe(true);
+            expect(validateOrderKey(b)).toBe(true);
+        });
+        it('produces a key strictly less than `b` for (null, b)', () => {
+            const b = generateKeyBetween(null, null);
+            const a = generateKeyBetween(null, b);
+            expect(a < b).toBe(true);
+            expect(validateOrderKey(a)).toBe(true);
+        });
+        it('produces a key strictly between `a` and `b`', () => {
+            const a = generateKeyBetween(null, null);
+            const c = generateKeyBetween(a, null);
+            const mid = generateKeyBetween(a, c);
+            expect(a < mid).toBe(true);
+            expect(mid < c).toBe(true);
+            expect(validateOrderKey(mid)).toBe(true);
+        });
+        it('keeps splitting the same gap arbitrarily deep', () => {
+            const lo = generateKeyBetween(null, null);
+            let hi = generateKeyBetween(lo, null);
+            // 200 in-the-middle inserts into the same gap.
+            for (let i = 0; i < 200; i++) {
+                const mid = generateKeyBetween(lo, hi);
+                expect(lo < mid).toBe(true);
+                expect(mid < hi).toBe(true);
+                hi = mid;
+            }
+        });
+    });
+    describe('generateKeyBetween — error cases', () => {
+        it('throws when a >= b', () => {
+            const a = generateKeyBetween(null, null);
+            const b = generateKeyBetween(a, null);
+            expect(() => generateKeyBetween(b, a)).toThrow();
+            expect(() => generateKeyBetween(a, a)).toThrow();
+        });
+        it('throws when given a malformed key', () => {
+            expect(() => generateKeyBetween('not-a-real-key!!!', null)).toThrow();
+            expect(() => generateKeyBetween(null, '?')).toThrow();
+        });
+    });
+    describe('generateNKeysBetween', () => {
+        it('returns an empty array for n=0', () => {
+            expect(generateNKeysBetween(null, null, 0)).toEqual([]);
+        });
+        it('returns one key for n=1', () => {
+            const keys = generateNKeysBetween(null, null, 1);
+            expect(keys.length).toBe(1);
+            expect(validateOrderKey(keys[0])).toBe(true);
+        });
+        it('returns n strictly ascending keys (open interval)', () => {
+            const keys = generateNKeysBetween(null, null, 10);
+            expect(keys.length).toBe(10);
+            for (let i = 1; i < keys.length; i++) {
+                expect(keys[i - 1] < keys[i]).toBe(true);
+                expect(validateOrderKey(keys[i])).toBe(true);
+            }
+        });
+        it('returns n strictly ascending keys between two neighbors', () => {
+            const a = generateKeyBetween(null, null);
+            const b = generateKeyBetween(a, null);
+            const keys = generateNKeysBetween(a, b, 20);
+            expect(keys.length).toBe(20);
+            expect(a < keys[0]).toBe(true);
+            expect(keys[keys.length - 1] < b).toBe(true);
+            for (let i = 1; i < keys.length; i++) {
+                expect(keys[i - 1] < keys[i]).toBe(true);
+            }
+        });
+    });
+    describe('validateOrderKey', () => {
+        it('accepts well-formed keys', () => {
+            expect(validateOrderKey('a0')).toBe(true);
+            expect(validateOrderKey(generateKeyBetween(null, null))).toBe(true);
+        });
+        it('rejects empty / non-string / malformed input', () => {
+            expect(validateOrderKey('')).toBe(false);
+            expect(validateOrderKey(null)).toBe(false);
+            expect(validateOrderKey(undefined)).toBe(false);
+            expect(validateOrderKey('!')).toBe(false);
+            // Trailing zero in fraction part is forbidden (non-canonical).
+            expect(validateOrderKey('a00')).toBe(false);
+        });
+    });
+    describe('fuzz — random insert / prepend / append mix', () => {
+        it('maintains a globally sorted list after 1000 random operations', () => {
+            const list = [generateKeyBetween(null, null)];
+            for (let i = 0; i < 1000; i++) {
+                const op = Math.floor(Math.random() * 3);
+                if (op === 0) {
+                    const k = generateKeyBetween(null, list[0]);
+                    list.unshift(k);
+                }
+                else if (op === 1) {
+                    const k = generateKeyBetween(list[list.length - 1], null);
+                    list.push(k);
+                }
+                else {
+                    if (list.length < 2)
+                        continue;
+                    const idx = Math.floor(Math.random() * (list.length - 1));
+                    const k = generateKeyBetween(list[idx], list[idx + 1]);
+                    list.splice(idx + 1, 0, k);
+                }
+            }
+            for (let i = 1; i < list.length; i++) {
+                expect(list[i - 1] < list[i]).toBe(true);
+            }
+        });
+    });
+});

package/dist/query/parse-where.js

@@ -20,6 +20,8 @@ const DOCUMENT_SORT_COLUMNS = {
     path: 'path',
     created_at: 'created_at',
     updated_at: 'updated_at',
+    orderKey: 'order_key',
+    order_key: 'order_key',
 };
 // ---------------------------------------------------------------------------
 // Parse functions

package/dist/services/collection-bootstrap.test.node.js

@@ -42,6 +42,7 @@ function createMockDb(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                setOrderKey: vi.fn(fail),
             },
         },
         queries: {
@@ -62,6 +63,9 @@ function createMockDb(options) {
                 getPublishedDocumentIds: vi.fn(fail),
                 getDocumentCountsByStatus: vi.fn(fail),
                 findDocuments: vi.fn(fail),
+                getLastOrderKey: vi.fn(fail),
+                getNeighborOrderKeys: vi.fn(fail),
+                getCanonicalDocumentOrder: vi.fn(fail),
             },
         },
     };
@@ -175,6 +179,7 @@ describe('ensureCollections', () => {
                     setDocumentStatus: vi.fn(),
                     archivePublishedVersions: vi.fn(),
                     softDeleteDocument: vi.fn(),
+                    setOrderKey: vi.fn(),
                 },
             },
             queries: {
@@ -195,6 +200,9 @@ describe('ensureCollections', () => {
                     getPublishedDocumentIds: vi.fn(),
                     getDocumentCountsByStatus: vi.fn(),
                     findDocuments: vi.fn(),
+                    getLastOrderKey: vi.fn(),
+                    getNeighborOrderKeys: vi.fn(),
+                    getCanonicalDocumentOrder: vi.fn(),
                 },
             },
         };

package/dist/services/document-lifecycle.js

@@ -7,7 +7,9 @@
  */
 import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
+import { getCollectionAdminConfig } from '../config/config.js';
 import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, ErrorCodes, } from '../lib/errors.js';
+import { generateKeyBetween } from '../lib/fractional-index.js';
 import { withLogContext } from '../lib/logger.js';
 import { applyPatches } from '../patches/index.js';
 import { normaliseDateFields } from '../utils/normalise-dates.js';
@@ -28,6 +30,22 @@ async function invokeHook(hook, ctx) {
         await fn(ctx);
     }
 }
+/**
+ * For collections with `orderable: true` in their admin config, compute an
+ * append-at-end fractional-index key for a newly-inserted document.
+ * Returns `undefined` when the collection hasn't opted in (or has no admin
+ * config registered, e.g. in unit-test environments), so the storage row
+ * gets `order_key = NULL` and the existing "no ordering" behavior holds.
+ */
+async function maybeAppendOrderKey(ctx, collectionPath) {
+    const adminConfig = getCollectionAdminConfig(collectionPath);
+    if (adminConfig?.orderable !== true)
+        return undefined;
+    const last = await ctx.db.queries.documents.getLastOrderKey({
+        collection_id: ctx.collectionId,
+    });
+    return generateKeyBetween(last, null);
+}
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 function extractVersionId(document) {
     return document?.id ?? document?.document_version_id ?? '';
@@ -157,6 +175,11 @@ export async function createDocument(ctx, params) {
         await invokeHook(hooks?.beforeCreate, { data, collectionPath });
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const resolvedPath = explicitPath ?? derivePath(definition, data, defaultLocale, slugifier);
+        // Append-at-end order_key for `orderable: true` collections.
+        // Computed before the insert so the single createDocumentVersion call
+        // carries the key into the byline_documents row. No effect when the
+        // admin config opts out or isn't registered.
+        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
         const result = await db.commands.documents
             .createDocumentVersion({
             collectionId,
@@ -167,6 +190,7 @@ export async function createDocument(ctx, params) {
             path: resolvedPath,
             status: params.status ?? data.status,
             locale: params.locale ?? defaultLocale,
+            orderKey,
         })
             .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);
@@ -860,6 +884,10 @@ export async function duplicateDocument(ctx, params) {
         let finalPath = candidatePath;
         let pathRetried = false;
         let result;
+        // Append-at-end order_key for `orderable: true` collections. Computed
+        // before the insert; the source row's order is intentionally not
+        // copied — duplicates land at the end of the list.
+        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
         try {
             result = await db.commands.documents
                 .createDocumentVersion({
@@ -871,6 +899,7 @@ export async function duplicateDocument(ctx, params) {
                 path: finalPath,
                 status: defaultStatus,
                 locale: 'all',
+                orderKey,
             })
                 .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
         }
@@ -894,6 +923,7 @@ export async function duplicateDocument(ctx, params) {
                 path: finalPath,
                 status: defaultStatus,
                 locale: 'all',
+                orderKey,
             })
                 .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
         }

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

@@ -47,6 +47,7 @@ function createMockDb() {
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,
+                setOrderKey: vi.fn(),
             },
         },
         queries: {
@@ -67,6 +68,9 @@ function createMockDb() {
                 getPublishedDocumentIds: vi.fn(),
                 getDocumentCountsByStatus: vi.fn(),
                 findDocuments: vi.fn(),
+                getLastOrderKey: vi.fn(),
+                getNeighborOrderKeys: vi.fn(),
+                getCanonicalDocumentOrder: vi.fn(),
             },
         },
     };

package/dist/services/field-upload.test.node.js

@@ -56,6 +56,7 @@ function createMockDb() {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                setOrderKey: vi.fn(),
             },
         },
         queries: {
@@ -76,6 +77,9 @@ function createMockDb() {
                 getPublishedDocumentIds: vi.fn(),
                 getDocumentCountsByStatus: vi.fn(),
                 findDocuments: vi.fn(),
+                getLastOrderKey: vi.fn(),
+                getNeighborOrderKeys: vi.fn(),
+                getCanonicalDocumentOrder: vi.fn(),
             },
         },
     };

package/dist/services/populate.test.node.js

@@ -144,6 +144,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                setOrderKey: vi.fn(),
             },
         },
         queries: {
@@ -164,6 +165,9 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 getPublishedDocumentIds: vi.fn(),
                 getDocumentCountsByStatus: vi.fn(),
                 findDocuments: vi.fn(),
+                getLastOrderKey: vi.fn(),
+                getNeighborOrderKeys: vi.fn(),
+                getCanonicalDocumentOrder: vi.fn(),
             },
         },
     };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "1.10.3"
+    "@byline/auth": "1.11.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",