@byline/core 3.12.2 → 3.13.1

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

@@ -471,6 +471,39 @@ export interface DeleteContext {
     /** The document's canonical (source-locale) routing path. */
     path: string;
 }
+/**
+ * Context passed to the `afterTreeChange` hook — the structural-change
+ * invalidation event for `tree: true` collections (docs/DOCUMENT-TREE.md).
+ *
+ * Tree mutations are document-grain and **unversioned**, so the normal
+ * version-write invalidation (`afterCreate` / `afterUpdate` / `afterStatusChange`)
+ * never fires for them. A single structural change ripples — the moved node, its
+ * descendants (their breadcrumb trails changed), and the old/new parents and
+ * sibling lists — so the hook fires **once per write** carrying the whole
+ * `affectedDocumentIds` set as a batched event, rather than one event per edge.
+ * Consumers (cache / ISR invalidation, markdown-export refresh, search reindex)
+ * refresh exactly that set.
+ */
+export interface TreeChangeContext {
+    collectionPath: string;
+    /**
+     * The kind of structural change:
+     *   - `'place'`  — a node was placed, reordered, or re-parented.
+     *   - `'remove'` — a node was removed from the tree (back to *unplaced*).
+     *   - `'promote-on-delete'` — a document was deleted, so its children were
+     *     promoted to root and it left the tree.
+     */
+    change: 'place' | 'remove' | 'promote-on-delete';
+    /** The primary node the change acted on. */
+    documentId: string;
+    /**
+     * Every document whose tree position, breadcrumb trail, or sibling context
+     * changed and which downstream caches / indexes should refresh: the acted-on
+     * node, its descendants, the old and new parents, and the affected sibling
+     * lists. De-duplicated; order is not significant.
+     */
+    affectedDocumentIds: string[];
+}
 /**
  * Context passed to `beforeStore` hooks (configured on
  * `field.upload.hooks`).
@@ -746,6 +779,15 @@ export interface CollectionHooks {
     beforeDelete?: CollectionHookSlot<DeleteContext>;
     /** Runs after a document is deleted. */
     afterDelete?: CollectionHookSlot<DeleteContext>;
+    /**
+     * Runs after a structural change to a `tree: true` collection's hierarchy —
+     * a place / reorder / re-parent (`placeTreeNode`), a removal
+     * (`removeFromTree`), or the promote-children-to-root that accompanies a
+     * delete. Tree writes mint no document version, so this is the only
+     * invalidation signal for them. Fires once per write with the full affected
+     * set ({@link TreeChangeContext}). See docs/DOCUMENT-TREE.md.
+     */
+    afterTreeChange?: CollectionHookSlot<TreeChangeContext>;
     /**
      * Runs once per `findDocuments` call (and once per populate batch, per
      * target collection), **before** any DB work. Returns a `QueryPredicate`
@@ -967,6 +1009,33 @@ export interface CollectionDefinition {
      * inside a collection (bios, team members, FAQ items, sections).
      */
     orderable?: boolean;
+    /**
+     * When `true`, this collection is a **document tree** — a self-referential,
+     * single-parent ordered hierarchy (the structural backbone for documentation
+     * / book sites). Each node's parent and its per-parent sibling order are
+     * stored document-grain and unversioned in `byline_document_relationships`
+     * and mutated via the dedicated tree commands (`placeTreeNode` /
+     * `removeFromTree`), which mint no document version — exactly like `path`,
+     * `availableLocales`, and `order_key`.
+     *
+     * Lives on the schema (not `defineAdmin`) because it changes **storage
+     * authority and the read path**, not just presentation: it turns on the
+     * edge-table storage + commands, the recursive tree read path
+     * (`getTreeSubtree` / `getTreeAncestors` / `getTreeChildren`), the authoring
+     * tree widget, and the structural-change invalidation event.
+     *
+     * Mutually exclusive with `orderable`: the tree owns ordering (per-parent, on
+     * the edge row), so `byline_documents.order_key` is inert for a tree
+     * collection. Setting both throws at startup.
+     *
+     * The hierarchy is *meta* — it describes where a document sits in a table of
+     * contents and says nothing about its content; re-parenting and reordering
+     * touch no user fields. Do **not** also declare a `parent` relation field; the
+     * tree owns structure (a topic that genuinely belongs in two places is a
+     * cross-link relation field, never a second tree edge). See
+     * docs/DOCUMENT-TREE.md.
+     */
+    tree?: boolean;
     /**
      * Optional explicit version pin. When omitted, the startup bootstrap
      * auto-increments the collection's stored version any time the schema

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

@@ -573,6 +573,51 @@ export interface IDocumentCommands {
         document_id: string;
         order_key: string;
     }): Promise<void>;
+    /**
+     * Place or move a document within its collection's single-parent ordered
+     * tree (the `tree: true` document-tree primitive). Upserts the node's edge
+     * row in `byline_document_relationships`: sets `parentDocumentId` (or NULL
+     * for a root node) and mints a per-parent fractional `order_key` between the
+     * resolved in-group neighbours. Covers place, reorder, and re-parent — they
+     * differ only in whether `parentDocumentId` changes.
+     *
+     * Document-grain and unversioned: writes the edge table only — no new
+     * document version, no status change, no user-field write (exactly like
+     * `setOrderKey` / `updateDocumentPath`).
+     *
+     * Two invariants the DB cannot hold are enforced in the same transaction as
+     * the write, so concurrent cross-moves cannot race them:
+     *   - **cycle guard** — rejects a move that would make the node its own
+     *     ancestor (walks the new parent's ancestor chain).
+     *   - **same-collection guard** — both endpoints must belong to
+     *     `collectionId` (the tree is self-referential within one collection).
+     *
+     * Neighbour semantics match `reorderCollectionDocument`: `beforeDocumentId`
+     * is the sibling the placed node should land immediately **after** (its left
+     * neighbour) and `afterDocumentId` is the sibling it should land immediately
+     * **before** (its right neighbour). Either may be null — `{}` appends as the
+     * only/last child, `beforeDocumentId` alone appends after it, `afterDocumentId`
+     * alone prepends before it. Both are resolved within the *target* parent
+     * group. See docs/DOCUMENT-TREE.md.
+     */
+    placeTreeNode(params: {
+        collectionId: string;
+        documentId: string;
+        parentDocumentId: string | null;
+        beforeDocumentId?: string | null;
+        afterDocumentId?: string | null;
+    }): Promise<{
+        orderKey: string;
+    }>;
+    /**
+     * Remove a document's edge row, returning it to the *unplaced* state (in the
+     * collection, but not in the tree). Distinct from document deletion — the
+     * document and its content are untouched. No-op when the node is already
+     * unplaced. See docs/DOCUMENT-TREE.md.
+     */
+    removeFromTree(params: {
+        documentId: string;
+    }): Promise<void>;
 }
 export interface ICollectionQueries {
     getAllCollections(): Promise<any[]>;
@@ -873,4 +918,96 @@ export interface IDocumentQueries {
         id: string;
         order_key: string | null;
     }>>;
+    /**
+     * Walk a document's ancestor chain upward through the document tree
+     * (`byline_document_relationships`). Returns the ancestors ordered
+     * **root-first** with a 1-based `depth` (1 = the document's immediate
+     * parent, increasing toward the root). Empty for a root or unplaced node.
+     *
+     * Backs breadcrumbs and the read-time hierarchical-URL canonicalization
+     * (docs/DOCUMENT-TREE.md). Depth-bounded as a backstop against pathological
+     * key state even though the write-path cycle guard prevents true cycles.
+     *
+     * **Status-at-edge.** `readMode: 'published'` joins
+     * `byline_current_published_documents` at each hop and **stops at the first
+     * unpublished ancestor** — it does *not* skip past it. So an unpublished
+     * mid-spine node truncates the returned chain, which the hierarchical-URL
+     * splat handler turns into a 404 (the "unpublished node hides its subtree"
+     * decision, enforced at the URL layer). `readMode: 'any'` (the default) walks
+     * the raw edges, matching the breadcrumb/lifecycle use that wants every
+     * ancestor regardless of status.
+     */
+    getTreeAncestors(params: {
+        document_id: string;
+        maxDepth?: number;
+        readMode?: ReadMode;
+    }): Promise<Array<{
+        document_id: string;
+        depth: number;
+    }>>;
+    /**
+     * List the immediate children of a tree node, ordered by the per-parent
+     * `order_key`. `parentDocumentId: null` returns the collection's root nodes.
+     * Scoped to `collectionId` so root reads (which have no parent to scope by)
+     * stay within the collection. One level only — the recursive subtree read is
+     * a separate query. See docs/DOCUMENT-TREE.md.
+     */
+    getTreeChildren(params: {
+        collectionId: string;
+        parentDocumentId: string | null;
+    }): Promise<Array<{
+        document_id: string;
+        order_key: string;
+    }>>;
+    /**
+     * Resolve a single node's placement state in the tree, distinguishing the
+     * three tri-states (docs/DOCUMENT-TREE.md → "Node placement"):
+     *
+     *   - **Unplaced** (no edge row) → `{ placed: false, parentDocumentId: null }`
+     *   - **Root** (edge row, null parent) → `{ placed: true,  parentDocumentId: null }`
+     *   - **Child** (edge row, parent set) → `{ placed: true,  parentDocumentId: <id> }`
+     *
+     * `getTreeAncestors` returns `[]` for *both* a root and an unplaced node, so it
+     * cannot tell them apart; this primitive can. Backs the update-time self-heal
+     * (re-root a stray doc) and the authoring widget's "Add to tree" vs "Top level"
+     * distinction.
+     */
+    getTreeParent(params: {
+        document_id: string;
+    }): Promise<{
+        placed: boolean;
+        parentDocumentId: string | null;
+    }>;
+    /**
+     * Read a node's subtree as a flat, **pre-order (depth-first)** list — each
+     * node immediately followed by its descendants, siblings in `order_key`
+     * order, with a 0-based `depth` (the requested root / the collection roots
+     * are depth 0). Drives the authoring tree, server-rendered navigation, and
+     * the prev/next spine flatten.
+     *
+     * `rootDocumentId: null` (the default) reads the whole tree from the
+     * collection's roots; a value reads the subtree rooted at (and including)
+     * that node.
+     *
+     * **Status-at-edge.** `readMode: 'published'` joins
+     * `byline_current_published_documents` and drops any node without a current
+     * published version; because the walk only recurses through *included*
+     * nodes, an unpublished node's entire subtree is omitted — the spine is
+     * broken and descendants are not promoted (see docs/DOCUMENT-TREE.md).
+     * `readMode: 'any'` (the default) includes every current, non-deleted node.
+     * Depth-bounded by `maxDepth` as a backstop.
+     *
+     * Returns structure only; hydrate content via `getDocumentsByDocumentIds`.
+     */
+    getTreeSubtree(params: {
+        collectionId: string;
+        rootDocumentId?: string | null;
+        maxDepth?: number;
+        readMode?: ReadMode;
+    }): Promise<Array<{
+        document_id: string;
+        parent_document_id: string | null;
+        depth: number;
+        order_key: string;
+    }>>;
 }

package/dist/config/validate-collections.d.ts

@@ -29,6 +29,9 @@ export declare const RESERVED_FIELD_NAMES: ReadonlySet<string>;
  *  - When `advertiseLocales` is `true`, the collection must have at least
  *    one `localized` field — advertising content locales is meaningless
  *    otherwise.
+ *  - A collection may not set both `tree: true` and `orderable: true`. A
+ *    document-tree owns ordering per-parent on the tree edge, so
+ *    `byline_documents.order_key` is inert for it.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are

package/dist/config/validate-collections.js

@@ -71,6 +71,9 @@ function walkFields(fields, visit) {
  *  - When `advertiseLocales` is `true`, the collection must have at least
  *    one `localized` field — advertising content locales is meaningless
  *    otherwise.
+ *  - A collection may not set both `tree: true` and `orderable: true`. A
+ *    document-tree owns ordering per-parent on the tree edge, so
+ *    `byline_documents.order_key` is inert for it.
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
@@ -96,5 +99,8 @@ export function validateCollections(collections) {
         if (collection.advertiseLocales === true && !hasLocalizedField(collection.fields)) {
             throw new Error(`Collection "${collection.path}" sets \`advertiseLocales: true\` but has no localized fields. The available-locales control advertises content locales, which is only meaningful when at least one field is \`localized\`.`);
         }
+        if (collection.tree === true && collection.orderable === true) {
+            throw new Error(`Collection "${collection.path}" sets both \`tree: true\` and \`orderable: true\`. A document-tree collection owns ordering on the tree edge (per-parent), so \`byline_documents.order_key\` is inert — set only \`tree: true\`.`);
+        }
     }
 }

package/dist/config/validate-collections.test.node.js

@@ -214,4 +214,28 @@ describe('validateCollections', () => {
     it('accepts advertiseLocales omitted regardless of localized fields', () => {
         expect(() => validateCollections([baseCollection])).not.toThrow();
     });
+    it('accepts tree: true on its own', () => {
+        const collection = {
+            ...baseCollection,
+            useAsTitle: 'title',
+            useAsPath: 'title',
+            tree: true,
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('rejects tree: true together with orderable: true', () => {
+        const collection = {
+            ...baseCollection,
+            tree: true,
+            orderable: true,
+        };
+        expect(() => validateCollections([collection])).toThrow(/tree: true.*orderable: true|orderable/);
+    });
+    it('accepts orderable: true without tree', () => {
+        const collection = {
+            ...baseCollection,
+            orderable: true,
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
 });

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

@@ -46,6 +46,8 @@ function createMockDb(options) {
                 softDeleteDocument: vi.fn(fail),
                 deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
+                placeTreeNode: vi.fn(fail),
+                removeFromTree: vi.fn(fail),
             },
             counters: {
                 ensureCounterGroup: vi.fn(fail),
@@ -74,6 +76,10 @@ function createMockDb(options) {
                 getLastOrderKey: vi.fn(fail),
                 getNeighborOrderKeys: vi.fn(fail),
                 getCanonicalDocumentOrder: vi.fn(fail),
+                getTreeAncestors: vi.fn(fail),
+                getTreeChildren: vi.fn(fail),
+                getTreeParent: vi.fn(fail),
+                getTreeSubtree: vi.fn(fail),
             },
         },
     };
@@ -191,6 +197,8 @@ describe('ensureCollections', () => {
                     softDeleteDocument: vi.fn(),
                     deleteDocumentLocale: vi.fn(),
                     setOrderKey: vi.fn(),
+                    placeTreeNode: vi.fn(),
+                    removeFromTree: vi.fn(),
                 },
                 counters: {
                     ensureCounterGroup: vi.fn(),
@@ -219,6 +227,10 @@ describe('ensureCollections', () => {
                     getLastOrderKey: vi.fn(),
                     getNeighborOrderKeys: vi.fn(),
                     getCanonicalDocumentOrder: vi.fn(),
+                    getTreeAncestors: vi.fn(),
+                    getTreeChildren: vi.fn(),
+                    getTreeParent: vi.fn(),
+                    getTreeSubtree: vi.fn(),
                 },
             },
         };

package/dist/services/discover-counter-groups.test.node.js

@@ -31,6 +31,8 @@ function makeAdapter(options) {
                 softDeleteDocument: vi.fn(fail),
                 deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
+                placeTreeNode: vi.fn(fail),
+                removeFromTree: vi.fn(fail),
             },
             counters: {
                 ensureCounterGroup,
@@ -59,6 +61,10 @@ function makeAdapter(options) {
                 getLastOrderKey: vi.fn(fail),
                 getNeighborOrderKeys: vi.fn(fail),
                 getCanonicalDocumentOrder: vi.fn(fail),
+                getTreeAncestors: vi.fn(fail),
+                getTreeChildren: vi.fn(fail),
+                getTreeParent: vi.fn(fail),
+                getTreeSubtree: vi.fn(fail),
             },
         },
     };

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

@@ -13,7 +13,7 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { actorId, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 /**
  * Create a new document.
  *
@@ -80,6 +80,22 @@ export async function createDocument(ctx, params) {
             .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
+        // `tree: true` collections place every document in the tree by default:
+        // a new document is appended as a root (a top-level nav entry) so it is
+        // never stranded in the "unplaced" limbo. This is a system step of create
+        // (the actor already passed the `create` ability), so it calls the storage
+        // command directly — no `update` re-assertion, no separate tree event
+        // (afterCreate covers invalidation). Post-version and best-effort: a
+        // failure leaves the document created-but-unplaced and is logged, not
+        // thrown. See docs/DOCUMENT-TREE.md.
+        if (definition.tree === true) {
+            try {
+                await appendTreeRoot(ctx, documentId);
+            }
+            catch (err) {
+                ctx.logger.error({ err, documentId }, 'failed to auto-place new document in tree');
+            }
+        }
         await invokeHook(hooks?.afterCreate, {
             data,
             collectionPath,

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

@@ -12,6 +12,7 @@ import { withLogContext } from '../../lib/logger.js';
 import { getUploadFields } from '../../utils/storage-utils.js';
 import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
 import { invokeHook } from './internals.js';
+import { promoteChildrenAndRemove } from './tree.js';
 /**
  * Soft-delete a document.
  *
@@ -124,7 +125,23 @@ export async function deleteDocument(ctx, params) {
                 }
             }
         }
-        // 5. afterDelete hook.
+        // 5. Reconcile the document tree for `tree: true` collections. Byline
+        //    deletes are soft (the document row survives), so the table's
+        //    promote/cascade foreign keys never fire — promote the node's
+        //    children to root and remove its edge here instead, firing the
+        //    structural-change invalidation event. Post-commit and best-effort,
+        //    like file cleanup: a failure here leaves the soft-delete intact
+        //    (status-at-edge already hides the deleted node's subtree from
+        //    reads) and is logged rather than thrown. See docs/DOCUMENT-TREE.md.
+        if (definition.tree === true) {
+            try {
+                await promoteChildrenAndRemove(ctx, { documentId: params.documentId });
+            }
+            catch (err) {
+                logger.error({ err, documentId: params.documentId }, 'failed to reconcile document tree on delete');
+            }
+        }
+        // 6. afterDelete hook.
         await invokeHook(hooks?.afterDelete, hookCtx);
         return { deletedVersionCount };
     });

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

@@ -30,6 +30,7 @@ export { duplicateDocument } from './duplicate.js';
 export { restoreDocumentVersion } from './restore.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
+export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';
 export { updateDocument, updateDocumentWithPatches } from './update.js';
 export type { DocumentLifecycleContext } from './context.js';
 export type { CopyToLocaleResult } from './copy-to-locale.js';

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

@@ -30,4 +30,5 @@ export { duplicateDocument } from './duplicate.js';
 export { restoreDocumentVersion } from './restore.js';
 export { changeDocumentStatus, unpublishDocument } from './status.js';
 export { updateDocumentSystemFields } from './system-fields.js';
+export { placeTreeNode, promoteChildrenAndRemove, removeFromTree } from './tree.js';
 export { updateDocument, updateDocumentWithPatches } from './update.js';

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

@@ -59,6 +59,26 @@ export declare function applyRichTextEmbed(ctx: DocumentLifecycleContext, data:
  * gets `order_key = NULL` and the existing "no ordering" behavior holds.
  */
 export declare function maybeAppendOrderKey(ctx: DocumentLifecycleContext, collectionPath: string): Promise<string | undefined>;
+/**
+ * Append a document as the **last root** of its `tree: true` collection's tree.
+ * Mints a fresh root-group `order_key` after the current trailing root. Used by
+ * create's auto-place and update's self-heal so a tree collection never strands a
+ * document in the "unplaced" limbo. Issues the storage command directly — the
+ * caller has already asserted the relevant ability and this is a system step.
+ */
+export declare function appendTreeRoot(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
+/**
+ * Self-heal a genuinely-*unplaced* document on update: if the collection is a
+ * tree and the document has no edge row, append it as a root (mirroring create's
+ * auto-place). `getTreeParent` distinguishes unplaced from root, so an existing
+ * root or child is left exactly where it is — only strays (e.g. docs created
+ * before the flag, or whose create-time auto-place failed) are re-treed.
+ *
+ * No-op for non-tree collections. Best-effort and post-version: a failure leaves
+ * the document saved-but-unplaced and is logged, never thrown. See
+ * docs/DOCUMENT-TREE.md.
+ */
+export declare function selfHealTreePlacement(ctx: DocumentLifecycleContext, documentId: string): Promise<void>;
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 export declare function extractVersionId(document: any): string;
 /** Extract the logical document id from the document object returned by `createDocumentVersion`. */

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

@@ -103,6 +103,49 @@ export async function maybeAppendOrderKey(ctx, collectionPath) {
     });
     return generateKeyBetween(last, null);
 }
+/**
+ * Append a document as the **last root** of its `tree: true` collection's tree.
+ * Mints a fresh root-group `order_key` after the current trailing root. Used by
+ * create's auto-place and update's self-heal so a tree collection never strands a
+ * document in the "unplaced" limbo. Issues the storage command directly — the
+ * caller has already asserted the relevant ability and this is a system step.
+ */
+export async function appendTreeRoot(ctx, documentId) {
+    const roots = await ctx.db.queries.documents.getTreeChildren({
+        collectionId: ctx.collectionId,
+        parentDocumentId: null,
+    });
+    await ctx.db.commands.documents.placeTreeNode({
+        collectionId: ctx.collectionId,
+        documentId,
+        parentDocumentId: null,
+        beforeDocumentId: roots.at(-1)?.document_id ?? null,
+    });
+}
+/**
+ * Self-heal a genuinely-*unplaced* document on update: if the collection is a
+ * tree and the document has no edge row, append it as a root (mirroring create's
+ * auto-place). `getTreeParent` distinguishes unplaced from root, so an existing
+ * root or child is left exactly where it is — only strays (e.g. docs created
+ * before the flag, or whose create-time auto-place failed) are re-treed.
+ *
+ * No-op for non-tree collections. Best-effort and post-version: a failure leaves
+ * the document saved-but-unplaced and is logged, never thrown. See
+ * docs/DOCUMENT-TREE.md.
+ */
+export async function selfHealTreePlacement(ctx, documentId) {
+    if (ctx.definition.tree !== true)
+        return;
+    try {
+        const { placed } = await ctx.db.queries.documents.getTreeParent({ document_id: documentId });
+        if (placed)
+            return;
+        await appendTreeRoot(ctx, documentId);
+    }
+    catch (err) {
+        ctx.logger.error({ err, documentId }, 'failed to self-heal tree placement on update');
+    }
+}
 /** Extract `id` from the document object returned by `createDocumentVersion`. */
 export function extractVersionId(document) {
     return document?.id ?? document?.document_version_id ?? '';

package/dist/services/document-lifecycle/tree.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
+ */
+import type { DocumentLifecycleContext } from './context.js';
+/**
+ * Place or move a node within the collection's tree (place / reorder /
+ * re-parent — one upsert). Asserts the `update` ability, performs the storage
+ * write, then fires `afterTreeChange` with the affected set. The affected-set
+ * reads are skipped entirely when the collection declares no `afterTreeChange`
+ * hook, so the event machinery adds no overhead to collections that don't
+ * consume it.
+ */
+export declare function placeTreeNode(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    parentDocumentId: string | null;
+    beforeDocumentId?: string | null;
+    afterDocumentId?: string | null;
+}): Promise<{
+    orderKey: string;
+}>;
+/**
+ * Remove a node from the tree (back to the *unplaced* state). Asserts `update`,
+ * performs the storage delete, then fires `afterTreeChange`. Distinct from
+ * deleting the document.
+ */
+export declare function removeFromTree(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+}): Promise<void>;
+/**
+ * Promote a soft-deleted node's children to root and remove the node from the
+ * tree — the application-level equivalent of the table's `parent → set null`
+ * (promote) and `child → cascade` (leave) foreign keys, which only fire on a
+ * *hard* row delete. Byline deletes are soft (the document row survives), so the
+ * tree must be reconciled here. Fires one `afterTreeChange` (`promote-on-delete`)
+ * covering the deleted node, the promoted children, and their subtrees.
+ *
+ * Best-effort and idempotent: a node with no children or no edge row is a no-op.
+ * Called by the document delete lifecycle for `tree: true` collections.
+ */
+export declare function promoteChildrenAndRemove(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+}): Promise<void>;

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

@@ -0,0 +1,184 @@
+/**
+ * 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
+ */
+/**
+ * Document-tree lifecycle service — the unversioned structural mutations for
+ * `tree: true` collections (docs/DOCUMENT-TREE.md). Wraps the storage adapter's
+ * tree commands so that, like the versioned lifecycle services, they enforce the
+ * actor ability and fire a collection hook. Tree writes mint no document version
+ * and touch no user fields, so the `afterTreeChange` hook is the *only*
+ * invalidation signal for them.
+ *
+ * The hook payload is the **affected set** — not a single node — because one
+ * structural change ripples: the moved node, its descendants (breadcrumb trails
+ * changed), the old and new parents, and both sibling lists. Computed with a few
+ * cheap tree reads around the write and emitted as one batched event.
+ */
+import { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { withLogContext } from '../../lib/logger.js';
+import { invokeHook } from './internals.js';
+/** Immediate parent of a node, or `null` when it is a root or unplaced. */
+async function immediateParentId(ctx, documentId) {
+    const ancestors = await ctx.db.queries.documents.getTreeAncestors({ document_id: documentId });
+    // `getTreeAncestors` is root-first, so the last entry (depth 1) is the parent.
+    return ancestors.length > 0 ? (ancestors[ancestors.length - 1]?.document_id ?? null) : null;
+}
+/** Document ids of a node and all its descendants (status-agnostic). */
+async function subtreeIds(ctx, rootDocumentId) {
+    const rows = await ctx.db.queries.documents.getTreeSubtree({
+        collectionId: ctx.collectionId,
+        rootDocumentId,
+        readMode: 'any',
+    });
+    return rows.map((r) => r.document_id);
+}
+/** Document ids of a parent's immediate children (`null` = the collection roots). */
+async function childIds(ctx, parentDocumentId) {
+    const rows = await ctx.db.queries.documents.getTreeChildren({
+        collectionId: ctx.collectionId,
+        parentDocumentId,
+    });
+    return rows.map((r) => r.document_id);
+}
+/** Resolve and fire the `afterTreeChange` hook with a de-duplicated affected set. */
+async function fireTreeChange(ctx, definition, event) {
+    const hooks = await resolveHooks(definition);
+    if (hooks?.afterTreeChange == null)
+        return;
+    await invokeHook(hooks.afterTreeChange, {
+        collectionPath: ctx.collectionPath,
+        change: event.change,
+        documentId: event.documentId,
+        affectedDocumentIds: [...new Set(event.affectedDocumentIds)],
+    });
+}
+/**
+ * Place or move a node within the collection's tree (place / reorder /
+ * re-parent — one upsert). Asserts the `update` ability, performs the storage
+ * write, then fires `afterTreeChange` with the affected set. The affected-set
+ * reads are skipped entirely when the collection declares no `afterTreeChange`
+ * hook, so the event machinery adds no overhead to collections that don't
+ * consume it.
+ */
+export async function placeTreeNode(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'tree', function: 'placeTreeNode' }, async () => {
+        const { db, definition, collectionPath } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        const hooks = await resolveHooks(definition);
+        const wantsEvent = hooks?.afterTreeChange != null;
+        // Affected-before: the moved node's old parent, its subtree (descendants
+        // travel with it), and its old sibling group.
+        const before = wantsEvent
+            ? {
+                oldParentId: await immediateParentId(ctx, params.documentId),
+                subtree: await subtreeIds(ctx, params.documentId),
+            }
+            : null;
+        const oldSiblings = before ? await childIds(ctx, before.oldParentId) : [];
+        const result = await db.commands.documents.placeTreeNode({
+            collectionId: ctx.collectionId,
+            documentId: params.documentId,
+            parentDocumentId: params.parentDocumentId,
+            beforeDocumentId: params.beforeDocumentId ?? null,
+            afterDocumentId: params.afterDocumentId ?? null,
+        });
+        if (before) {
+            const newSiblings = await childIds(ctx, params.parentDocumentId);
+            await fireTreeChange(ctx, definition, {
+                change: 'place',
+                documentId: params.documentId,
+                affectedDocumentIds: [
+                    params.documentId,
+                    ...before.subtree,
+                    ...(before.oldParentId ? [before.oldParentId] : []),
+                    ...(params.parentDocumentId ? [params.parentDocumentId] : []),
+                    ...oldSiblings,
+                    ...newSiblings,
+                ],
+            });
+        }
+        return result;
+    });
+}
+/**
+ * Remove a node from the tree (back to the *unplaced* state). Asserts `update`,
+ * performs the storage delete, then fires `afterTreeChange`. Distinct from
+ * deleting the document.
+ */
+export async function removeFromTree(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'tree', function: 'removeFromTree' }, async () => {
+        const { db, definition, collectionPath } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        const hooks = await resolveHooks(definition);
+        const wantsEvent = hooks?.afterTreeChange != null;
+        const oldParentId = wantsEvent ? await immediateParentId(ctx, params.documentId) : null;
+        const subtree = wantsEvent ? await subtreeIds(ctx, params.documentId) : [];
+        const oldSiblings = wantsEvent ? await childIds(ctx, oldParentId) : [];
+        await db.commands.documents.removeFromTree({ documentId: params.documentId });
+        if (wantsEvent) {
+            await fireTreeChange(ctx, definition, {
+                change: 'remove',
+                documentId: params.documentId,
+                affectedDocumentIds: [
+                    params.documentId,
+                    ...subtree,
+                    ...(oldParentId ? [oldParentId] : []),
+                    ...oldSiblings,
+                ],
+            });
+        }
+    });
+}
+/**
+ * Promote a soft-deleted node's children to root and remove the node from the
+ * tree — the application-level equivalent of the table's `parent → set null`
+ * (promote) and `child → cascade` (leave) foreign keys, which only fire on a
+ * *hard* row delete. Byline deletes are soft (the document row survives), so the
+ * tree must be reconciled here. Fires one `afterTreeChange` (`promote-on-delete`)
+ * covering the deleted node, the promoted children, and their subtrees.
+ *
+ * Best-effort and idempotent: a node with no children or no edge row is a no-op.
+ * Called by the document delete lifecycle for `tree: true` collections.
+ */
+export async function promoteChildrenAndRemove(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'tree', function: 'promoteChildrenAndRemove' }, async () => {
+        const { db, definition } = ctx;
+        // Capture the affected set before mutating: the node, its (direct)
+        // children, and each child's subtree (their breadcrumbs all change as
+        // they promote to root).
+        const hooks = await resolveHooks(definition);
+        const wantsEvent = hooks?.afterTreeChange != null;
+        const children = await childIds(ctx, params.documentId);
+        const affected = new Set([params.documentId]);
+        if (wantsEvent) {
+            for (const childId of children) {
+                for (const id of await subtreeIds(ctx, childId))
+                    affected.add(id);
+            }
+        }
+        // Promote each child to root. `placeTreeNode` with no neighbours mints a
+        // fresh root-group key, so promoted orphans no longer carry a stale
+        // per-parent key.
+        for (const childId of children) {
+            await db.commands.documents.placeTreeNode({
+                collectionId: ctx.collectionId,
+                documentId: childId,
+                parentDocumentId: null,
+            });
+        }
+        // The deleted node leaves the tree.
+        await db.commands.documents.removeFromTree({ documentId: params.documentId });
+        if (wantsEvent) {
+            await fireTreeChange(ctx, definition, {
+                change: 'promote-on-delete',
+                documentId: params.documentId,
+                affectedDocumentIds: affected,
+            });
+        }
+    });
+}

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

@@ -13,7 +13,7 @@ import { applyPatches } from '../../patches/index.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, selfHealTreePlacement, } from './internals.js';
 /**
  * Update a document via full replacement (PUT semantics).
  *
@@ -90,6 +90,9 @@ export async function updateDocument(ctx, params) {
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
+        // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
+        // save re-trees a stray (system step, best-effort, no-op when placed).
+        await selfHealTreePlacement(ctx, documentId);
         await invokeHook(hooks?.afterUpdate, {
             data,
             originalData,
@@ -204,6 +207,9 @@ export async function updateDocumentWithPatches(ctx, params) {
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
+        // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
+        // save re-trees a stray (system step, best-effort, no-op when placed).
+        await selfHealTreePlacement(ctx, documentId);
         // 7. afterUpdate hook.
         await invokeHook(hooks?.afterUpdate, {
             data: nextData,

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

@@ -57,6 +57,8 @@ function createMockDb() {
                 softDeleteDocument,
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
+                placeTreeNode: vi.fn(),
+                removeFromTree: vi.fn(),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
@@ -87,6 +89,10 @@ function createMockDb() {
                 getLastOrderKey: vi.fn(),
                 getNeighborOrderKeys: vi.fn(),
                 getCanonicalDocumentOrder: vi.fn(),
+                getTreeAncestors: vi.fn(),
+                getTreeChildren: vi.fn(),
+                getTreeParent: vi.fn(),
+                getTreeSubtree: vi.fn(),
             },
         },
     };

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

@@ -60,6 +60,8 @@ function createMockDb() {
                 softDeleteDocument: vi.fn(),
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
+                placeTreeNode: vi.fn(),
+                removeFromTree: vi.fn(),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
@@ -88,6 +90,10 @@ function createMockDb() {
                 getLastOrderKey: vi.fn(),
                 getNeighborOrderKeys: vi.fn(),
                 getCanonicalDocumentOrder: vi.fn(),
+                getTreeAncestors: vi.fn(),
+                getTreeChildren: vi.fn(),
+                getTreeParent: vi.fn(),
+                getTreeSubtree: vi.fn(),
             },
         },
     };

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

@@ -148,6 +148,8 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 softDeleteDocument: vi.fn(),
                 deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
+                placeTreeNode: vi.fn(),
+                removeFromTree: vi.fn(),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
@@ -176,6 +178,10 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 getLastOrderKey: vi.fn(),
                 getNeighborOrderKeys: vi.fn(),
                 getCanonicalDocumentOrder: vi.fn(),
+                getTreeAncestors: vi.fn(),
+                getTreeChildren: vi.fn(),
+                getTreeParent: vi.fn(),
+                getTreeSubtree: vi.fn(),
             },
         },
     };

package/package.json

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