@byline/db-postgres 3.12.1 → 3.13.0

package/dist/database/schema/common.d.ts

@@ -24,7 +24,6 @@ export declare const timestamps: {
 /**
  * `created_at` only — for tables whose rows are immutable once
  * inserted (junction tables like `byline_admin_role_admin_user`,
- * append-only relationship rows like `byline_document_relationships`,
  * registry rows like `byline_counter_groups`).
  *
  * Spread into a `pgTable` definition the same way as `timestamps`.

package/dist/database/schema/common.js

@@ -35,7 +35,6 @@ export const timestamps = {
 /**
  * `created_at` only — for tables whose rows are immutable once
  * inserted (junction tables like `byline_admin_role_admin_user`,
- * append-only relationship rows like `byline_document_relationships`,
  * registry rows like `byline_counter_groups`).
  *
  * Spread into a `pgTable` definition the same way as `timestamps`.

package/dist/database/schema/index.d.ts

@@ -768,8 +768,25 @@ export declare const documentRelationships: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        parent_document_id: import("drizzle-orm/pg-core").PgColumn<{
-            name: "parent_document_id";
+        updated_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "byline_document_relationships";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        child_document_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "child_document_id";
             tableName: "byline_document_relationships";
             dataType: "string";
             columnType: "PgUUID";
@@ -785,14 +802,14 @@ export declare const documentRelationships: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
-        child_document_id: import("drizzle-orm/pg-core").PgColumn<{
-            name: "child_document_id";
+        parent_document_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "parent_document_id";
             tableName: "byline_document_relationships";
             dataType: "string";
             columnType: "PgUUID";
             data: string;
             driverParam: string;
-            notNull: true;
+            notNull: false;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
@@ -802,6 +819,25 @@ export declare const documentRelationships: import("drizzle-orm/pg-core").PgTabl
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        order_key: import("drizzle-orm/pg-core").PgColumn<{
+            name: "order_key";
+            tableName: "byline_document_relationships";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
+        }>;
     };
     dialect: "pg";
 }>;
@@ -3268,8 +3304,6 @@ export declare const collectionsRelations: import("drizzle-orm").Relations<"byli
 }>;
 export declare const documentsRelations: import("drizzle-orm").Relations<"byline_document_versions", {
     collection: import("drizzle-orm").One<"byline_collections", true>;
-    parent_relationships: import("drizzle-orm").Many<"byline_document_relationships">;
-    child_relationships: import("drizzle-orm").Many<"byline_document_relationships">;
     text_values: import("drizzle-orm").Many<"byline_store_text">;
     numeric_values: import("drizzle-orm").Many<"byline_store_numeric">;
     boolean_values: import("drizzle-orm").Many<"byline_store_boolean">;
@@ -3279,8 +3313,12 @@ export declare const documentsRelations: import("drizzle-orm").Relations<"byline
     json_values: import("drizzle-orm").Many<"byline_store_json">;
 }>;
 export declare const documentRelationshipsRelations: import("drizzle-orm").Relations<"byline_document_relationships", {
-    parent: import("drizzle-orm").One<"byline_document_versions", true>;
-    child: import("drizzle-orm").One<"byline_document_versions", true>;
+    parent: import("drizzle-orm").One<"byline_documents", false>;
+    child: import("drizzle-orm").One<"byline_documents", true>;
+}>;
+export declare const documentTreeRelations: import("drizzle-orm").Relations<"byline_documents", {
+    tree_parent_edge: import("drizzle-orm").Many<"byline_document_relationships">;
+    tree_child_edges: import("drizzle-orm").Many<"byline_document_relationships">;
 }>;
 export declare const textStoreRelations: import("drizzle-orm").Relations<"byline_store_text", {
     document: import("drizzle-orm").One<"byline_document_versions", true>;

package/dist/database/schema/index.js

@@ -179,23 +179,35 @@ export const documentVersionLocales = pgTable('byline_document_version_locales',
         .references(() => documentVersions.id, { onDelete: 'cascade' }),
     locale: varchar('locale', { length: 10 }).notNull(),
 }, (table) => [primaryKey({ columns: [table.document_version_id, table.locale] })]);
-// Document Relationships (Parent/Child) - Many-to-Many
+// Document Tree — single-parent ordered adjacency. See docs/DOCUMENT-TREE.md.
+//
+// A document-grain, unversioned hierarchy primitive for `tree: true`
+// collections (self-referential, single collection). Rows reference the logical
+// `document_id`, not the version `id`. Unlike most edge tables the FKs are
+// load-bearing here:
+//   - child  → cascade : when the document is deleted, its membership row
+//                        disappears (the node leaves the tree).
+//   - parent → set null: when a parent document is deleted, its children's
+//                        parent pointer clears — they promote to root.
 export const documentRelationships = pgTable('byline_document_relationships', {
-    // Note: These reference the logical `document_id`, not the version `id`.
-    // Foreign key constraints are not used; integrity is handled at the application layer.
-    parent_document_id: uuid('parent_document_id')
-        .notNull()
-        .references(() => documents.id, { onDelete: 'cascade' }),
     child_document_id: uuid('child_document_id')
         .notNull()
         .references(() => documents.id, { onDelete: 'cascade' }),
-    ...createdAt,
+    // Nullable = root node. `set null` promotes orphans to root on parent delete.
+    parent_document_id: uuid('parent_document_id').references(() => documents.id, {
+        onDelete: 'set null',
+    }),
+    // Per-parent sibling order (each parent is its own keyspace). COLLATE "C"
+    // so DB ordering matches the JS fractional-index algorithm, exactly like
+    // `byline_documents.order_key`.
+    order_key: varcharByteSorted('order_key', { length: 128 }).notNull(),
+    ...timestamps,
 }, (table) => [
-    // Composite primary key to ensure a child is only parented once by the same parent.
-    unique().on(table.parent_document_id, table.child_document_id),
-    // Indexes for efficient lookups of children and parents.
-    index('idx_document_relationships_parent').on(table.parent_document_id),
-    index('idx_document_relationships_child').on(table.child_document_id),
+    // Single-parent invariant: each document appears in at most one row.
+    unique('uq_document_relationships_child').on(table.child_document_id),
+    // Per-parent sibling read, in order — drives the authoring tree and the
+    // read-side flatten.
+    index('idx_document_relationships_parent_order').on(table.parent_document_id, table.order_key),
 ]);
 // Current Documents View — latest version of each logical document via
 // `ROW_NUMBER() OVER (PARTITION BY document_id ORDER BY id DESC)`.
@@ -522,11 +534,6 @@ export const documentsRelations = relations(documentVersions, ({ one, many }) =>
         fields: [documentVersions.collection_id],
         references: [collections.id],
     }),
-    // Relations for parent/child documents
-    // A document can be a child in many relationships. This finds the links.
-    parent_relationships: many(documentRelationships, { relationName: 'child' }),
-    // A document can be a parent in many relationships. This finds the links.
-    child_relationships: many(documentRelationships, { relationName: 'parent' }),
     // Relations for field values
     text_values: many(textStore),
     numeric_values: many(numericStore),
@@ -537,17 +544,28 @@ export const documentsRelations = relations(documentVersions, ({ one, many }) =>
     json_values: many(jsonStore),
 }));
 export const documentRelationshipsRelations = relations(documentRelationships, ({ one }) => ({
-    parent: one(documentVersions, {
+    parent: one(documents, {
         fields: [documentRelationships.parent_document_id],
-        references: [documentVersions.document_id],
-        relationName: 'parent',
+        references: [documents.id],
+        relationName: 'tree_parent',
     }),
-    child: one(documentVersions, {
+    child: one(documents, {
         fields: [documentRelationships.child_document_id],
-        references: [documentVersions.document_id],
-        relationName: 'child',
+        references: [documents.id],
+        relationName: 'tree_child',
     }),
 }));
+// Document-tree edges on the logical document. The tree read path itself is a
+// recursive CTE (see docs/DOCUMENT-TREE.md), not the Drizzle query builder —
+// these relations exist for completeness / ad-hoc joins.
+export const documentTreeRelations = relations(documents, ({ many }) => ({
+    // The membership edge where this document is the child — its placement in the
+    // tree. 0..1 by the unique(child_document_id) constraint; modelled as `many`
+    // per Drizzle's inverse-side convention (the FK lives on the edge table).
+    tree_parent_edge: many(documentRelationships, { relationName: 'tree_child' }),
+    // Edges where this document is the parent — its ordered children.
+    tree_child_edges: many(documentRelationships, { relationName: 'tree_parent' }),
+}));
 // Field value relations
 export const textStoreRelations = relations(textStore, ({ one }) => ({
     document: one(documentVersions, {

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

@@ -390,6 +390,30 @@ export declare class DocumentCommands implements IDocumentCommands {
         document_id: string;
         order_key: string;
     }): Promise<void>;
+    /**
+     * placeTreeNode — see {@link IDocumentCommands.placeTreeNode}.
+     *
+     * Single transaction: same-collection guard → cycle guard → resolve the
+     * target sibling group's neighbour keys → mint a fractional key → upsert the
+     * edge row (conflict on `child_document_id`, the single-parent invariant).
+     * Unversioned; touches only `byline_document_relationships`.
+     */
+    placeTreeNode(params: {
+        collectionId: string;
+        documentId: string;
+        parentDocumentId: string | null;
+        beforeDocumentId?: string | null;
+        afterDocumentId?: string | null;
+    }): Promise<{
+        orderKey: string;
+    }>;
+    /**
+     * removeFromTree — see {@link IDocumentCommands.removeFromTree}.
+     * Single-row delete; no-op when the node is already unplaced.
+     */
+    removeFromTree(params: {
+        documentId: string;
+    }): Promise<void>;
 }
 export declare function createCommandBuilders(dbManager: DBManager, defaultContentLocale: string): {
     collections: CollectionCommands;

package/dist/modules/storage/storage-commands.js

@@ -5,12 +5,20 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { and, desc, eq, ne, sql } from 'drizzle-orm';
+import { ERR_NOT_FOUND, ERR_VALIDATION, generateKeyBetween } from '@byline/core';
+import { and, desc, eq, inArray, ne, sql } from 'drizzle-orm';
 import { v7 as uuidv7 } from 'uuid';
-import { booleanStore, collections, datetimeStore, documentAvailableLocales, documentPaths, documents, documentVersionLocales, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
+import { booleanStore, collections, datetimeStore, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersionLocales, documentVersions, fileStore, jsonStore, metaStore, numericStore, relationStore, textStore, } from '../../database/schema/index.js';
 import { flattenFieldSetData } from './storage-flatten.js';
 import { prepareFieldInsertBuckets } from './storage-insert.js';
 import { getFirstOrThrow } from './storage-utils.js';
+/**
+ * Depth backstop for the document-tree recursive walks (cycle guard, ancestor
+ * walk). The write-path cycle guard prevents true cycles, so this only bounds
+ * recursion against pre-existing pathological state — far deeper than any real
+ * documentation hierarchy. See docs/DOCUMENT-TREE.md.
+ */
+const TREE_MAX_DEPTH = 10_000;
 /**
  * CollectionCommands
  */
@@ -853,6 +861,140 @@ export class DocumentCommands {
         })
             .where(eq(documents.id, params.document_id));
     }
+    /**
+     * placeTreeNode — see {@link IDocumentCommands.placeTreeNode}.
+     *
+     * Single transaction: same-collection guard → cycle guard → resolve the
+     * target sibling group's neighbour keys → mint a fractional key → upsert the
+     * edge row (conflict on `child_document_id`, the single-parent invariant).
+     * Unversioned; touches only `byline_document_relationships`.
+     */
+    async placeTreeNode(params) {
+        const { collectionId, documentId, parentDocumentId } = params;
+        const beforeDocumentId = params.beforeDocumentId ?? null;
+        const afterDocumentId = params.afterDocumentId ?? null;
+        if (parentDocumentId === documentId) {
+            throw ERR_VALIDATION({
+                message: 'a document cannot be its own parent in the document tree',
+                details: { documentId },
+            });
+        }
+        return await this.db.transaction(async (tx) => {
+            // Same-collection guard — both endpoints must live in `collectionId`.
+            const ids = parentDocumentId ? [documentId, parentDocumentId] : [documentId];
+            const docRows = await tx
+                .select({ id: documents.id, collection_id: documents.collection_id })
+                .from(documents)
+                .where(inArray(documents.id, ids));
+            const collectionById = new Map(docRows.map((r) => [r.id, r.collection_id]));
+            if (collectionById.get(documentId) == null) {
+                throw ERR_NOT_FOUND({ message: 'document not found', details: { documentId } });
+            }
+            if (collectionById.get(documentId) !== collectionId) {
+                throw ERR_VALIDATION({
+                    message: 'document does not belong to the collection',
+                    details: { documentId, collectionId },
+                });
+            }
+            if (parentDocumentId != null) {
+                if (collectionById.get(parentDocumentId) == null) {
+                    throw ERR_NOT_FOUND({
+                        message: 'parent document not found',
+                        details: { parentDocumentId },
+                    });
+                }
+                if (collectionById.get(parentDocumentId) !== collectionId) {
+                    throw ERR_VALIDATION({
+                        message: 'parent document is in a different collection',
+                        details: { parentDocumentId, collectionId },
+                    });
+                }
+                // Cycle guard — reject when `documentId` is the new parent itself or
+                // any of its ancestors (which would put the node below its own
+                // subtree). Walk upward from `parentDocumentId`; depth-bounded.
+                const cycle = await tx.execute(sql `
+          WITH RECURSIVE chain AS (
+            SELECT ${parentDocumentId}::uuid AS node_id, 0 AS depth
+            UNION ALL
+            SELECT r.parent_document_id, c.depth + 1
+            FROM byline_document_relationships r
+            JOIN chain c ON r.child_document_id = c.node_id
+            WHERE r.parent_document_id IS NOT NULL AND c.depth < ${TREE_MAX_DEPTH}
+          )
+          SELECT 1 FROM chain WHERE node_id = ${documentId}::uuid LIMIT 1
+        `);
+                if (cycle.rows.length > 0) {
+                    throw ERR_VALIDATION({
+                        message: 'move would create a cycle in the document tree',
+                        details: { documentId, parentDocumentId },
+                    });
+                }
+            }
+            // Resolve the neighbour keys within the target sibling group and mint a
+            // fractional key between them. Per-parent keyspace, so collisions across
+            // sibling groups are structurally impossible.
+            const neighbourIds = [];
+            if (beforeDocumentId)
+                neighbourIds.push(beforeDocumentId);
+            if (afterDocumentId)
+                neighbourIds.push(afterDocumentId);
+            let left = null;
+            let right = null;
+            if (neighbourIds.length > 0) {
+                const edgeRows = await tx
+                    .select({
+                    child: documentRelationships.child_document_id,
+                    order_key: documentRelationships.order_key,
+                })
+                    .from(documentRelationships)
+                    .where(inArray(documentRelationships.child_document_id, neighbourIds));
+                const keyByChild = new Map(edgeRows.map((r) => [r.child, r.order_key]));
+                left = beforeDocumentId ? (keyByChild.get(beforeDocumentId) ?? null) : null;
+                right = afterDocumentId ? (keyByChild.get(afterDocumentId) ?? null) : null;
+            }
+            let orderKey;
+            try {
+                orderKey = generateKeyBetween(left, right);
+            }
+            catch (err) {
+                throw ERR_VALIDATION({
+                    message: 'cannot generate order_key between the supplied tree neighbours',
+                    details: {
+                        documentId,
+                        parentDocumentId,
+                        left,
+                        right,
+                        cause: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+            await tx
+                .insert(documentRelationships)
+                .values({
+                child_document_id: documentId,
+                parent_document_id: parentDocumentId,
+                order_key: orderKey,
+            })
+                .onConflictDoUpdate({
+                target: documentRelationships.child_document_id,
+                set: {
+                    parent_document_id: parentDocumentId,
+                    order_key: orderKey,
+                    updated_at: new Date(),
+                },
+            });
+            return { orderKey };
+        });
+    }
+    /**
+     * removeFromTree — see {@link IDocumentCommands.removeFromTree}.
+     * Single-row delete; no-op when the node is already unplaced.
+     */
+    async removeFromTree(params) {
+        await this.db
+            .delete(documentRelationships)
+            .where(eq(documentRelationships.child_document_id, params.documentId));
+    }
 }
 export function createCommandBuilders(dbManager, defaultContentLocale) {
     return {

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

@@ -449,6 +449,77 @@ export declare class DocumentQueries implements IDocumentQueries {
         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.
+     */
+    getTreeAncestors({ document_id, maxDepth, readMode, }: {
+        document_id: string;
+        maxDepth?: number;
+        readMode?: ReadMode;
+    }): 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).
+     */
+    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.
+     */
+    getTreeParent({ document_id, }: {
+        document_id: string;
+    }): Promise<{
+        placed: boolean;
+        parentDocumentId: string | null;
+    }>;
+    /**
+     * 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 under `COLLATE "C"` 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). 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.
+     */
+    getTreeSubtree({ collectionId, rootDocumentId, maxDepth, readMode, }: {
+        collectionId: string;
+        rootDocumentId?: string | null;
+        maxDepth?: number;
+        readMode?: ReadMode;
+    }): Promise<Array<{
+        document_id: string;
+        parent_document_id: string | null;
+        depth: number;
+        order_key: string;
+    }>>;
     /**
      * getDocumentCountsByStatus
      *

package/dist/modules/storage/storage-queries.js

@@ -10,8 +10,8 @@
 // logger. A future refactor could inject the logger at construction time by
 // either deferring adapter construction or accepting a lazy logger parameter.
 import { ERR_DATABASE, ERR_NOT_FOUND, getLogger, orderByContentLocale } from '@byline/core';
-import { and, desc, eq, inArray, isNotNull, sql } from 'drizzle-orm';
-import { collections, currentDocumentsView, currentPublishedDocumentsView, documentAvailableLocales, documentPaths, documents, documentVersionLocales, documentVersions, metaStore, } from '../../database/schema/index.js';
+import { and, desc, eq, inArray, isNotNull, isNull, sql } from 'drizzle-orm';
+import { collections, currentDocumentsView, currentPublishedDocumentsView, documentAvailableLocales, documentPaths, documentRelationships, documents, documentVersionLocales, documentVersions, metaStore, } from '../../database/schema/index.js';
 import { extractFlattenedFieldValue, restoreFieldSetData } from './storage-restore.js';
 import { allStoreTypes, storeSelectList, storeTableNames, } from './storage-store-manifest.js';
 import { resolveStoreTypes } from './storage-utils.js';
@@ -899,6 +899,136 @@ export class DocumentQueries {
             .orderBy(sql `${documents.order_key} ASC NULLS LAST`, desc(documents.created_at));
         return rows;
     }
+    /**
+     * 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.
+     */
+    async getTreeAncestors({ document_id, maxDepth = 10_000, readMode = 'any', }) {
+        // Published mode gates every hop on the ancestor having a current published
+        // version; `any` mode imposes no such gate (raw edge walk).
+        const publishedGate = (parentColumn) => readMode === 'published'
+            ? sql `AND EXISTS (
+            SELECT 1 FROM byline_current_published_documents v
+            WHERE v.document_id = ${sql.raw(parentColumn)}
+          )`
+            : sql ``;
+        const { rows } = await this.db.execute(sql `
+      WITH RECURSIVE ancestors AS (
+        SELECT parent_document_id AS ancestor_id, child_document_id AS node_id, 1 AS depth
+        FROM byline_document_relationships
+        WHERE child_document_id = ${document_id}::uuid AND parent_document_id IS NOT NULL
+        ${publishedGate('parent_document_id')}
+        UNION ALL
+        SELECT r.parent_document_id, r.child_document_id, a.depth + 1
+        FROM byline_document_relationships r
+        JOIN ancestors a ON r.child_document_id = a.ancestor_id
+        WHERE r.parent_document_id IS NOT NULL AND a.depth < ${maxDepth}
+        ${publishedGate('r.parent_document_id')}
+      )
+      SELECT ancestor_id AS document_id, depth FROM ancestors ORDER BY depth DESC
+    `);
+        return rows.map((r) => ({
+            document_id: r.document_id,
+            depth: Number(r.depth),
+        }));
+    }
+    /**
+     * 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).
+     */
+    async getTreeChildren({ collectionId, parentDocumentId, }) {
+        const rows = await this.db
+            .select({
+            document_id: documentRelationships.child_document_id,
+            order_key: documentRelationships.order_key,
+        })
+            .from(documentRelationships)
+            .innerJoin(documents, eq(documents.id, documentRelationships.child_document_id))
+            .where(and(eq(documents.collection_id, collectionId), parentDocumentId == null
+            ? isNull(documentRelationships.parent_document_id)
+            : eq(documentRelationships.parent_document_id, parentDocumentId)))
+            .orderBy(documentRelationships.order_key);
+        return rows;
+    }
+    /**
+     * 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.
+     */
+    async getTreeParent({ document_id, }) {
+        const rows = await this.db
+            .select({ parent_document_id: documentRelationships.parent_document_id })
+            .from(documentRelationships)
+            .where(eq(documentRelationships.child_document_id, document_id))
+            .limit(1);
+        const row = rows[0];
+        if (row == null)
+            return { placed: false, parentDocumentId: null };
+        return { placed: true, parentDocumentId: row.parent_document_id ?? null };
+    }
+    /**
+     * 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 under `COLLATE "C"` 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). 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.
+     */
+    async getTreeSubtree({ collectionId, rootDocumentId = null, maxDepth = 10_000, readMode = 'any', }) {
+        const statusView = readMode === 'published' ? 'byline_current_published_documents' : 'byline_current_documents';
+        const rootCondition = rootDocumentId == null
+            ? sql `r.parent_document_id IS NULL`
+            : sql `r.child_document_id = ${rootDocumentId}::uuid`;
+        const { rows } = await this.db.execute(sql `
+      WITH RECURSIVE subtree AS (
+        SELECT r.child_document_id, r.parent_document_id, r.order_key,
+               0 AS depth, r.order_key::text AS path
+        FROM byline_document_relationships r
+        JOIN byline_documents d ON d.id = r.child_document_id
+        WHERE d.collection_id = ${collectionId}::uuid
+          AND ${rootCondition}
+          AND EXISTS (
+            SELECT 1 FROM ${sql.raw(statusView)} v WHERE v.document_id = r.child_document_id
+          )
+        UNION ALL
+        SELECT r.child_document_id, r.parent_document_id, r.order_key,
+               s.depth + 1, s.path || '/' || r.order_key
+        FROM byline_document_relationships r
+        JOIN subtree s ON r.parent_document_id = s.child_document_id
+        WHERE s.depth + 1 <= ${maxDepth}
+          AND EXISTS (
+            SELECT 1 FROM ${sql.raw(statusView)} v WHERE v.document_id = r.child_document_id
+          )
+      )
+      SELECT child_document_id AS document_id, parent_document_id, depth, order_key
+      FROM subtree
+      ORDER BY path COLLATE "C"
+    `);
+        return rows.map((r) => ({
+            document_id: r.document_id,
+            parent_document_id: r.parent_document_id ?? null,
+            depth: Number(r.depth),
+            order_key: r.order_key,
+        }));
+    }
     /**
      * getDocumentCountsByStatus
      *

package/dist/modules/storage/tests/storage-document-tree.test.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/modules/storage/tests/storage-document-tree.test.js

@@ -0,0 +1,434 @@
+/**
+ * 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 { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+let commandBuilders;
+let queryBuilders;
+const timestamp = Date.now();
+const TreeCollectionConfig = {
+    path: `tree-${timestamp}`,
+    labels: { singular: 'TreeTest', plural: 'TreeTests' },
+    useAsPath: 'title',
+    fields: [{ name: 'title', type: 'text' }],
+};
+const OtherCollectionConfig = {
+    path: `tree-other-${timestamp}`,
+    labels: { singular: 'TreeOther', plural: 'TreeOthers' },
+    useAsPath: 'title',
+    fields: [{ name: 'title', type: 'text' }],
+};
+let treeCollection = {};
+let otherCollection = {};
+async function createDoc(collectionId, config, title, status = 'published') {
+    const created = await commandBuilders.documents.createDocumentVersion({
+        collectionId,
+        collectionVersion: 1,
+        collectionConfig: config,
+        action: 'create',
+        documentData: { title },
+        path: `${title.toLowerCase().replace(/\s+/g, '-')}-${timestamp}`,
+        locale: 'all',
+        status,
+    });
+    return created.document.document_id;
+}
+function childIds(rows) {
+    return rows.map((r) => r.document_id);
+}
+describe('document-tree commands', () => {
+    beforeAll(async () => {
+        const testDB = setupTestDB([TreeCollectionConfig, OtherCollectionConfig]);
+        commandBuilders = testDB.commandBuilders;
+        queryBuilders = testDB.queryBuilders;
+        const tree = await commandBuilders.collections.create(TreeCollectionConfig.path, TreeCollectionConfig);
+        const other = await commandBuilders.collections.create(OtherCollectionConfig.path, OtherCollectionConfig);
+        if (tree[0] == null || other[0] == null)
+            throw new Error('Failed to create test collections');
+        treeCollection = { id: tree[0].id };
+        otherCollection = { id: other[0].id };
+    });
+    afterAll(async () => {
+        try {
+            await commandBuilders.collections.delete(treeCollection.id);
+            await commandBuilders.collections.delete(otherCollection.id);
+        }
+        catch (error) {
+            console.error('Failed to cleanup test collections:', error);
+        }
+        await teardownTestDB();
+    });
+    it('places roots and children, ordered per-parent', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'Root A');
+        const b = await createDoc(treeCollection.id, TreeCollectionConfig, 'Root B');
+        const c = await createDoc(treeCollection.id, TreeCollectionConfig, 'Child C');
+        const d = await createDoc(treeCollection.id, TreeCollectionConfig, 'Child D');
+        // Two roots, A then B.
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: b,
+            parentDocumentId: null,
+            beforeDocumentId: a,
+        });
+        const roots = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: null,
+        });
+        expect(childIds(roots)).toEqual([a, b]);
+        // Two children of A, C then D.
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: a,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: d,
+            parentDocumentId: a,
+            beforeDocumentId: c,
+        });
+        const aChildren = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        });
+        expect(childIds(aChildren)).toEqual([c, d]);
+    });
+    it('reorders siblings without changing parent or count', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'P A');
+        const x = await createDoc(treeCollection.id, TreeCollectionConfig, 'X');
+        const y = await createDoc(treeCollection.id, TreeCollectionConfig, 'Y');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: x,
+            parentDocumentId: a,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: y,
+            parentDocumentId: a,
+            beforeDocumentId: x,
+        });
+        let kids = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        });
+        expect(childIds(kids)).toEqual([x, y]);
+        // Move Y before X.
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: y,
+            parentDocumentId: a,
+            afterDocumentId: x,
+        });
+        kids = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        });
+        expect(childIds(kids)).toEqual([y, x]);
+        expect(kids.length, 'no duplicate row from upsert').toBe(2);
+    });
+    it('re-parents atomically and updates ancestors', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'RA');
+        const b = await createDoc(treeCollection.id, TreeCollectionConfig, 'RB');
+        const c = await createDoc(treeCollection.id, TreeCollectionConfig, 'RC');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: b,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: a,
+        });
+        expect((await queryBuilders.documents.getTreeAncestors({ document_id: c })).map((r) => r.document_id)).toEqual([a]);
+        // Move C under B.
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: b,
+        });
+        const aKids = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        });
+        const bKids = await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: b,
+        });
+        expect(childIds(aKids)).not.toContain(c);
+        expect(childIds(bKids)).toEqual([c]);
+        expect((await queryBuilders.documents.getTreeAncestors({ document_id: c })).map((r) => r.document_id)).toEqual([b]);
+    });
+    it('walks ancestors root-first with increasing depth', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'GA');
+        const b = await createDoc(treeCollection.id, TreeCollectionConfig, 'GB');
+        const c = await createDoc(treeCollection.id, TreeCollectionConfig, 'GC');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: b,
+            parentDocumentId: a,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: b,
+        });
+        const ancestors = await queryBuilders.documents.getTreeAncestors({ document_id: c });
+        expect(ancestors.map((r) => r.document_id)).toEqual([a, b]); // root-first
+        expect(ancestors.map((r) => r.depth)).toEqual([2, 1]); // a is 2 hops up, b is 1
+        // Root + unplaced nodes have no ancestors.
+        expect(await queryBuilders.documents.getTreeAncestors({ document_id: a })).toEqual([]);
+    });
+    it('getTreeParent distinguishes unplaced, root, and child', async () => {
+        const root = await createDoc(treeCollection.id, TreeCollectionConfig, 'TP Root');
+        const child = await createDoc(treeCollection.id, TreeCollectionConfig, 'TP Child');
+        const stray = await createDoc(treeCollection.id, TreeCollectionConfig, 'TP Stray');
+        // Stray is created but never placed → unplaced (no edge row). This is the
+        // state getTreeAncestors cannot tell apart from a root.
+        expect(await queryBuilders.documents.getTreeParent({ document_id: stray })).toEqual({
+            placed: false,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: root,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: child,
+            parentDocumentId: root,
+        });
+        // Root: placed with a null parent.
+        expect(await queryBuilders.documents.getTreeParent({ document_id: root })).toEqual({
+            placed: true,
+            parentDocumentId: null,
+        });
+        // Child: placed with its parent id.
+        expect(await queryBuilders.documents.getTreeParent({ document_id: child })).toEqual({
+            placed: true,
+            parentDocumentId: root,
+        });
+        // Both root and unplaced report empty ancestors — the conflation getTreeParent fixes.
+        expect(await queryBuilders.documents.getTreeAncestors({ document_id: root })).toEqual([]);
+        expect(await queryBuilders.documents.getTreeAncestors({ document_id: stray })).toEqual([]);
+    });
+    it('getTreeAncestors stops at the first unpublished ancestor in published mode', async () => {
+        // GP(pub) ─ MID(draft) ─ LEAF(pub)
+        const gp = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE GP', 'published');
+        const mid = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE Mid', 'draft');
+        const leaf = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE Leaf', 'published');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: gp,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: mid,
+            parentDocumentId: gp,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: leaf,
+            parentDocumentId: mid,
+        });
+        // any-mode: the full chain, root-first.
+        expect((await queryBuilders.documents.getTreeAncestors({ document_id: leaf, readMode: 'any' })).map((r) => r.document_id)).toEqual([gp, mid]);
+        // published-mode: the walk stops at the draft MID — it does NOT skip to GP.
+        expect(await queryBuilders.documents.getTreeAncestors({ document_id: leaf, readMode: 'published' })).toEqual([]);
+        // A draft root above a published parent truncates at the root, keeping the
+        // published parent but never reaching the draft root.
+        const draftRoot = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE DRoot', 'draft');
+        const pubMid = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE PMid', 'published');
+        const pubLeaf = await createDoc(treeCollection.id, TreeCollectionConfig, 'AE PLeaf', 'published');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: draftRoot,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pubMid,
+            parentDocumentId: draftRoot,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pubLeaf,
+            parentDocumentId: pubMid,
+        });
+        expect((await queryBuilders.documents.getTreeAncestors({
+            document_id: pubLeaf,
+            readMode: 'published',
+        })).map((r) => r.document_id)).toEqual([pubMid]); // stops below the draft root, does not include it
+    });
+    it('rejects a self-parent and a cycle', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'CA');
+        const c = await createDoc(treeCollection.id, TreeCollectionConfig, 'CC');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: a,
+        });
+        // Self-parent.
+        await expect(commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: a,
+        })).rejects.toThrow();
+        // Cycle: A is C's ancestor, so making A a child of C is a cycle.
+        await expect(commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: c,
+        })).rejects.toThrow();
+    });
+    it('rejects a cross-collection edge', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'XA');
+        const foreign = await createDoc(otherCollection.id, OtherCollectionConfig, 'Foreign');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await expect(commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: foreign,
+        })).rejects.toThrow();
+    });
+    it('removeFromTree returns a node to the unplaced state', async () => {
+        const a = await createDoc(treeCollection.id, TreeCollectionConfig, 'UA');
+        const c = await createDoc(treeCollection.id, TreeCollectionConfig, 'UC');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: a,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: c,
+            parentDocumentId: a,
+        });
+        expect(childIds(await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        }))).toEqual([c]);
+        await commandBuilders.documents.removeFromTree({ documentId: c });
+        expect(await queryBuilders.documents.getTreeChildren({
+            collectionId: treeCollection.id,
+            parentDocumentId: a,
+        })).toEqual([]);
+        expect(await queryBuilders.documents.getTreeAncestors({ document_id: c })).toEqual([]);
+        // Idempotent — removing an already-unplaced node is a no-op.
+        await expect(commandBuilders.documents.removeFromTree({ documentId: c })).resolves.toBeUndefined();
+    });
+    it('getTreeSubtree returns a pre-order depth-first walk with 0-based depth', async () => {
+        // Build:  SA ─ SB ─ SD
+        //              └ SC
+        const sa = await createDoc(treeCollection.id, TreeCollectionConfig, 'SA');
+        const sb = await createDoc(treeCollection.id, TreeCollectionConfig, 'SB');
+        const sc = await createDoc(treeCollection.id, TreeCollectionConfig, 'SC');
+        const sd = await createDoc(treeCollection.id, TreeCollectionConfig, 'SD');
+        // beforeDocumentId = left neighbour → the node lands immediately AFTER it.
+        const place = (documentId, parentDocumentId, beforeDocumentId) => commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId,
+            parentDocumentId,
+            beforeDocumentId,
+        });
+        await place(sa, null);
+        await place(sb, sa);
+        await place(sc, sa, sb); // SC lands after SB
+        await place(sd, sb); // SD under SB
+        const subtree = await queryBuilders.documents.getTreeSubtree({
+            collectionId: treeCollection.id,
+            rootDocumentId: sa,
+        });
+        // Pre-order: SA(0) → SB(1) → SD(2) → SC(1)
+        expect(subtree.map((n) => n.document_id)).toEqual([sa, sb, sd, sc]);
+        expect(subtree.map((n) => n.depth)).toEqual([0, 1, 2, 1]);
+        expect(subtree.find((n) => n.document_id === sd)?.parent_document_id).toBe(sb);
+        // Depth bound: only the root and its immediate children.
+        const shallow = await queryBuilders.documents.getTreeSubtree({
+            collectionId: treeCollection.id,
+            rootDocumentId: sa,
+            maxDepth: 1,
+        });
+        expect(shallow.map((n) => n.document_id)).toEqual([sa, sb, sc]);
+    });
+    it('status-at-edge hides an unpublished node and its whole subtree', async () => {
+        // PA(pub) ─ PB(pub)
+        //        └ PC(draft) ─ PD(pub)
+        const pa = await createDoc(treeCollection.id, TreeCollectionConfig, 'PPA', 'published');
+        const pb = await createDoc(treeCollection.id, TreeCollectionConfig, 'PPB', 'published');
+        const pc = await createDoc(treeCollection.id, TreeCollectionConfig, 'PPC', 'draft');
+        const pd = await createDoc(treeCollection.id, TreeCollectionConfig, 'PPD', 'published');
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pa,
+            parentDocumentId: null,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pb,
+            parentDocumentId: pa,
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pc,
+            parentDocumentId: pa,
+            beforeDocumentId: pb, // PC lands after PB
+        });
+        await commandBuilders.documents.placeTreeNode({
+            collectionId: treeCollection.id,
+            documentId: pd,
+            parentDocumentId: pc,
+        });
+        // any-mode sees the whole subtree.
+        const any = await queryBuilders.documents.getTreeSubtree({
+            collectionId: treeCollection.id,
+            rootDocumentId: pa,
+            readMode: 'any',
+        });
+        expect(any.map((n) => n.document_id)).toEqual([pa, pb, pc, pd]);
+        // published-mode drops the draft PC, and PD (under PC) is unreachable —
+        // the spine is broken, so the whole subtree is hidden, not promoted.
+        const published = await queryBuilders.documents.getTreeSubtree({
+            collectionId: treeCollection.id,
+            rootDocumentId: pa,
+            readMode: 'published',
+        });
+        expect(published.map((n) => n.document_id)).toEqual([pa, pb]);
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/admin": "3.12.1",
-    "@byline/core": "3.12.1",
-    "@byline/auth": "3.12.1"
+    "@byline/admin": "3.13.0",
+    "@byline/auth": "3.13.0",
+    "@byline/core": "3.13.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",