@byline/core 3.21.0 → 4.0.0

package/dist/query/parse-where.test.node.js

@@ -7,7 +7,7 @@
  */
 import { describe, expect, it } from 'vitest';
 import { defineCollection, defineWorkflow } from '../@types/collection-types.js';
-import { mergePredicates, parseSort, parseWhere } from './parse-where.js';
+import { mergePredicates, parsePredicateFilters, parseSort, parseWhere } from './parse-where.js';
 const testCollection = defineCollection({
     path: 'test-articles',
     labels: { singular: 'Article', plural: 'Articles' },
@@ -691,6 +691,65 @@ describe('parseWhere — `id` reserved key', () => {
         expect(result.filters).toHaveLength(1);
     });
 });
+describe('parsePredicateFilters', () => {
+    const idA = '018f4f7c-6a2b-7d91-8f21-111111111111';
+    const idB = '018f4f7c-6a2b-7d91-8f21-222222222222';
+    it('keeps top-level status and path inside the adapter filter list', async () => {
+        const filters = await parsePredicateFilters({ status: 'published', path: { $contains: 'docs' }, featured: true }, testCollection);
+        expect(filters).toEqual([
+            { kind: 'docColumn', column: 'status', operator: '$eq', value: 'published' },
+            { kind: 'docColumn', column: 'path', operator: '$contains', value: 'docs' },
+            expect.objectContaining({ kind: 'field', fieldName: 'featured' }),
+        ]);
+    });
+    it.each([
+        [{ typoedTenant: 't-1' }, 'unknown field'],
+        [{ query: 'secret' }, 'not supported'],
+        [{ $or: [] }, 'non-empty array'],
+        [{ $or: [{ typoedTenant: 't-1' }] }, 'unknown field'],
+        [{ title: { $wat: 'x' } }, 'supported operator'],
+        [{ status: { $contains: 'pub' } }, 'not supported'],
+        [{ status: { $in: 'published' } }, 'requires an array'],
+        [{ status: { $in: ['published', 1] } }, 'requires string values'],
+        [{ path: { $gt: '/private' } }, 'not supported'],
+        [{ path: { $in: ['/a', 1] } }, 'requires string values'],
+        [{ id: '__none__' }, 'requires UUID values'],
+        [{ id: { $eq: [idA] } }, 'requires a string'],
+        [{ id: { $in: ['not-a-uuid'] } }, 'requires UUID values'],
+    ])('rejects invalid security predicate %o', async (predicate, message) => {
+        await expect(parsePredicateFilters(predicate, testCollection, ctx, { strict: true })).rejects.toThrow(message);
+    });
+    it('preserves status, path, and id arrays in strict predicates', async () => {
+        const filters = await parsePredicateFilters({
+            status: { $in: ['draft', 'published'] },
+            path: { $nin: ['/private', '/internal'] },
+            id: { $in: [idA, idB] },
+        }, testCollection, ctx, { strict: true });
+        expect(filters).toEqual([
+            {
+                kind: 'docColumn',
+                column: 'status',
+                operator: '$in',
+                value: ['draft', 'published'],
+            },
+            {
+                kind: 'docColumn',
+                column: 'path',
+                operator: '$nin',
+                value: ['/private', '/internal'],
+            },
+            { kind: 'docColumn', column: 'id', operator: '$in', value: [idA, idB] },
+        ]);
+    });
+    it('compiles an empty id set as a safe always-false document filter', async () => {
+        await expect(parsePredicateFilters({ id: { $in: [] } }, testCollection, ctx, { strict: true })).resolves.toEqual([{ kind: 'docColumn', column: 'id', operator: '$in', value: [] }]);
+    });
+    it('keeps caller-query compilation permissive for unknown fields', async () => {
+        await expect(parseWhere({ typoedTenant: 't-1' }, testCollection)).resolves.toEqual({
+            filters: [],
+        });
+    });
+});
 // ---------------------------------------------------------------------------
 // mergePredicates
 // ---------------------------------------------------------------------------

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

@@ -21,10 +21,8 @@ function baseCollection() {
         },
     };
 }
-// Build a minimal IDbAdapter. We only wire the methods `ensureCollections`
-// actually calls; the others throw if touched so we catch accidental usage.
 function createMockDb(options) {
-    const getCollectionByPath = vi.fn().mockResolvedValue(options.existingRow ?? null);
+    const getCollectionByPath = vi.fn(options.getCollectionByPath ?? (async () => options.existingRow ?? null));
     const create = vi
         .fn()
         .mockImplementation(async (_path, _config, _opts) => [
@@ -48,12 +46,23 @@ function createMockDb(options) {
                 setOrderKey: vi.fn(fail),
                 placeTreeNode: vi.fn(fail),
                 removeFromTree: vi.fn(fail),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
             },
             counters: {
                 ensureCounterGroup: vi.fn(fail),
                 nextCounterValue: vi.fn(fail),
                 nextScopedCounterValue: vi.fn(fail),
             },
+            audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
         },
         queries: {
             collections: {
@@ -62,6 +71,7 @@ function createMockDb(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
+                getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
                 getCurrentPath: vi.fn(fail),
@@ -82,7 +92,18 @@ function createMockDb(options) {
                 getTreeParent: vi.fn(fail),
                 getTreeSubtree: vi.fn(fail),
             },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
         },
+        withTransaction: async (fn) => fn(),
     };
     return { db, create, update, getCollectionByPath };
 }
@@ -179,63 +200,13 @@ describe('ensureCollections', () => {
         const b = { ...baseCollection(), path: 'pages' };
         const hashA = await fingerprintCollection(a);
         // For `a` the DB matches; for `b` it does not exist yet.
-        const getCollectionByPath = vi.fn(async (path) => {
-            if (path === 'news')
-                return { id: 'col-news', version: 2, schema_hash: hashA };
-            return null;
-        });
-        const create = vi.fn().mockResolvedValue([{ id: 'col-pages' }]);
-        const update = vi.fn();
-        const db = {
-            commands: {
-                collections: { create, update, delete: vi.fn() },
-                documents: {
-                    createDocumentVersion: vi.fn(),
-                    updateDocumentPath: vi.fn(),
-                    setDocumentAvailableLocales: vi.fn(),
-                    setDocumentStatus: vi.fn(),
-                    archivePublishedVersions: vi.fn(),
-                    softDeleteDocument: vi.fn(),
-                    deleteDocumentLocale: vi.fn(),
-                    setOrderKey: vi.fn(),
-                    placeTreeNode: vi.fn(),
-                    removeFromTree: vi.fn(),
-                },
-                counters: {
-                    ensureCounterGroup: vi.fn(),
-                    nextCounterValue: vi.fn(),
-                    nextScopedCounterValue: vi.fn(),
-                },
-            },
-            queries: {
-                collections: {
-                    getAllCollections: vi.fn(),
-                    getCollectionByPath,
-                    getCollectionById: vi.fn(),
-                },
-                documents: {
-                    getDocumentById: vi.fn(),
-                    getCurrentVersionMetadata: vi.fn(),
-                    getCurrentPath: vi.fn(),
-                    getDocumentByPath: vi.fn(),
-                    getDocumentByVersion: vi.fn(),
-                    getDocumentsByVersionIds: vi.fn(),
-                    getDocumentsByDocumentIds: vi.fn(),
-                    getDocumentHistory: vi.fn(),
-                    getPublishedVersion: vi.fn(),
-                    getPublishedDocumentIds: vi.fn(),
-                    getDocumentCountsByStatus: vi.fn(),
-                    findDocuments: vi.fn(),
-                    getLastOrderKey: vi.fn(),
-                    getNeighborOrderKeys: vi.fn(),
-                    getCanonicalDocumentOrder: vi.fn(),
-                    getTreeAncestors: vi.fn(),
-                    getTreeChildren: vi.fn(),
-                    getTreeParent: vi.fn(),
-                    getTreeSubtree: vi.fn(),
-                },
+        const { db, create, update } = createMockDb({
+            getCollectionByPath: async (path) => {
+                if (path === 'news')
+                    return { id: 'col-news', version: 2, schema_hash: hashA };
+                return null;
             },
-        };
+        });
         const records = await ensureCollections({ definitions: [a, b], db });
         expect(records.get('news')?.version).toBe(2);
         expect(records.get('pages')?.version).toBe(1);

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

@@ -33,12 +33,23 @@ function makeAdapter(options) {
                 setOrderKey: vi.fn(fail),
                 placeTreeNode: vi.fn(fail),
                 removeFromTree: vi.fn(fail),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
             },
             counters: {
                 ensureCounterGroup,
                 nextCounterValue: vi.fn(fail),
                 nextScopedCounterValue: vi.fn(fail),
             },
+            audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
         },
         queries: {
             collections: {
@@ -47,6 +58,7 @@ function makeAdapter(options) {
                 getCollectionById: vi.fn(fail),
             },
             documents: {
+                getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(fail),
                 getCurrentVersionMetadata: vi.fn(fail),
                 getCurrentPath: vi.fn(fail),
@@ -67,7 +79,18 @@ function makeAdapter(options) {
                 getTreeParent: vi.fn(fail),
                 getTreeSubtree: vi.fn(fail),
             },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
         },
+        withTransaction: async (fn) => fn(),
     };
     return { db, ensureCounterGroup };
 }

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

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { AuditActorRealm, AuditLogAppendInput, IDbAdapter } from '../../@types/index.js';
+import type { AuditActorRealm, AuditLogAppendInput, CollectionDefinition, IDbAdapter, TreeDeleteMutationResult, TreeMutationResult } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from './context.js';
 /** Namespaced audit actions for document-grain changes. */
 export declare const AUDIT_ACTIONS: {
@@ -13,6 +13,10 @@ export declare const AUDIT_ACTIONS: {
     readonly localesChanged: 'document.locales.changed';
     readonly statusChanged: 'document.status.changed';
     readonly deleted: 'document.deleted';
+    readonly treePlaced: 'document.tree.placed';
+    readonly treeReparented: 'document.tree.reparented';
+    readonly treeReordered: 'document.tree.reordered';
+    readonly treeRemoved: 'document.tree.removed';
 };
 /**
  * The actor id + realm for an audit-log row. Mirrors `actorId()`: a real
@@ -33,6 +37,15 @@ export interface AuditCapability {
         id: string;
     }>;
 }
+/** Auditing plus the locked mutation primitives required by document trees. */
+export interface TreeAuditCapability extends AuditCapability {
+    place: (input: Parameters<IDbAdapter['commands']['documents']['placeTreeNode']>[0]) => Promise<TreeMutationResult>;
+    remove: (input: Parameters<IDbAdapter['commands']['documents']['removeFromTree']>[0]) => Promise<TreeMutationResult>;
+    promoteAndRemove: (input: {
+        collectionId: string;
+        documentId: string;
+    }) => Promise<TreeDeleteMutationResult>;
+}
 /**
  * Assert the adapter can record an audited write atomically — it must provide
  * **both** `withTransaction` and `commands.audit`. Returns a non-null
@@ -41,5 +54,13 @@ export interface AuditCapability {
  * See docs/03-architecture/03-transactions.md and docs/06-auth-and-security/02-auditability.md.
  */
 export declare function requireAuditCapability(db: IDbAdapter): AuditCapability;
+/**
+ * Require the complete audited-tree capability. Called at bootstrap and before
+ * create so a tree collection can never silently strand a document merely
+ * because its adapter lacks atomic audit/reconciliation support.
+ */
+export declare function requireTreeAuditCapability(db: IDbAdapter): TreeAuditCapability;
+/** Fail fast during server bootstrap when any tree collection lacks support. */
+export declare function validateTreeAuditCapability(definitions: readonly CollectionDefinition[], db: IDbAdapter): void;
 /** Order-insensitive equality for the advertised-locale set. */
 export declare function sameLocaleSet(a: readonly string[], b: readonly string[]): boolean;

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

@@ -22,6 +22,10 @@ export const AUDIT_ACTIONS = {
     localesChanged: 'document.locales.changed',
     statusChanged: 'document.status.changed',
     deleted: 'document.deleted',
+    treePlaced: 'document.tree.placed',
+    treeReparented: 'document.tree.reparented',
+    treeReordered: 'document.tree.reordered',
+    treeRemoved: 'document.tree.removed',
 };
 /**
  * The actor id + realm for an audit-log row. Mirrors `actorId()`: a real
@@ -47,7 +51,7 @@ export function auditActor(ctx) {
 export function requireAuditCapability(db) {
     const withTransaction = db.withTransaction;
     const audit = db.commands.audit;
-    if (withTransaction == null || audit == null) {
+    if (typeof withTransaction !== 'function' || typeof audit?.append !== 'function') {
         throw ERR_AUDIT_UNSUPPORTED({
             message: 'audited write requires a db adapter with withTransaction + commands.audit support',
         });
@@ -57,6 +61,33 @@ export function requireAuditCapability(db) {
         append: (input) => audit.append(input),
     };
 }
+/**
+ * Require the complete audited-tree capability. Called at bootstrap and before
+ * create so a tree collection can never silently strand a document merely
+ * because its adapter lacks atomic audit/reconciliation support.
+ */
+export function requireTreeAuditCapability(db) {
+    const audit = requireAuditCapability(db);
+    const documents = db.commands.documents;
+    const promoteChildrenAndRemove = documents.promoteChildrenAndRemoveFromTree;
+    if (typeof promoteChildrenAndRemove !== 'function') {
+        throw ERR_AUDIT_UNSUPPORTED({
+            message: 'tree-enabled writes require an adapter with locked tree mutation and delete-reconciliation support',
+        });
+    }
+    return {
+        ...audit,
+        place: (input) => documents.placeTreeNode(input),
+        remove: (input) => documents.removeFromTree(input),
+        promoteAndRemove: (input) => promoteChildrenAndRemove.call(documents, input),
+    };
+}
+/** Fail fast during server bootstrap when any tree collection lacks support. */
+export function validateTreeAuditCapability(definitions, db) {
+    if (!definitions.some((definition) => definition.tree === true))
+        return;
+    requireTreeAuditCapability(db);
+}
 /** Order-insensitive equality for the advertised-locale set. */
 export function sameLocaleSet(a, b) {
     if (a.length !== b.length)

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

@@ -14,7 +14,9 @@ import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
-import { actorId, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { requireTreeAuditCapability } from './audit.js';
+import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { appendTreeRoot } from './tree.js';
 /**
  * Create a new document.
  *
@@ -33,6 +35,10 @@ export async function createDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'createDocument' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        // Reject unsupported tree adapters before hooks, counters, or persistence
+        // can create a document that cannot be placed and audited safely.
+        if (definition.tree === true)
+            requireTreeAuditCapability(db);
         const slugifier = ctx.slugifier ?? slugify;
         const hooks = await resolveHooks(definition);
         const data = params.data;
@@ -86,11 +92,12 @@ export async function createDocument(ctx, params) {
         // `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/04-collections/03-document-trees.md.
+        // (the actor already passed the `create` ability), so it uses the internal
+        // placement primitive without an `update` re-assertion or separate tree
+        // event (afterCreate covers invalidation). Placement + audit are atomic.
+        // Post-version and best-effort: a runtime audit/storage failure leaves the
+        // document created-but-unplaced and is logged. Missing capability was
+        // rejected before persistence above.
         if (definition.tree === true) {
             try {
                 await appendTreeRoot(ctx, documentId);

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

@@ -5,10 +5,26 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { ErrorCodes } from '../../lib/errors.js';
 import type { DocumentLifecycleContext } from './context.js';
-export interface DeleteDocumentResult {
+export type DeleteDocumentOutcome = 'committed' | 'committed-with-side-effect-failures';
+export type DeleteDocumentSideEffectPhase = 'storageCleanup' | 'afterTreeChange' | 'afterDelete';
+export type DeleteDocumentSideEffectCode = typeof ErrorCodes.STORAGE | typeof ErrorCodes.UNHANDLED;
+export interface DeleteDocumentSideEffectFailure {
+    phase: DeleteDocumentSideEffectPhase;
+    code: DeleteDocumentSideEffectCode;
+}
+export interface DeleteDocumentCommittedResult {
+    deletedVersionCount: number;
+    outcome: 'committed';
+    sideEffectFailures: [];
+}
+export interface DeleteDocumentCommittedWithSideEffectFailuresResult {
     deletedVersionCount: number;
+    outcome: 'committed-with-side-effect-failures';
+    sideEffectFailures: [DeleteDocumentSideEffectFailure, ...DeleteDocumentSideEffectFailure[]];
 }
+export type DeleteDocumentResult = DeleteDocumentCommittedResult | DeleteDocumentCommittedWithSideEffectFailuresResult;
 /**
  * Soft-delete a document.
  *

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

@@ -7,13 +7,31 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { ERR_NOT_FOUND, ErrorCodes } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { hasUploadField, isUploadField } from '../../utils/storage-utils.js';
 import { walkFieldTree } from '../walk-field-tree.js';
-import { AUDIT_ACTIONS, auditActor, requireAuditCapability } from './audit.js';
+import { AUDIT_ACTIONS, auditActor, requireAuditCapability, requireTreeAuditCapability, } from './audit.js';
 import { invokeHook } from './internals.js';
-import { promoteChildrenAndRemove } from './tree.js';
+import { firePromoteTreeChange, reconcileTreeOnDeleteInTransaction } from './tree.js';
+function readErrorCode(error) {
+    try {
+        if ((typeof error !== 'object' || error === null) && typeof error !== 'function') {
+            return undefined;
+        }
+        const value = Reflect.get(error, 'code');
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function serializeSideEffectFailure(phase, error) {
+    return {
+        phase,
+        code: readErrorCode(error) === ErrorCodes.STORAGE ? ErrorCodes.STORAGE : ErrorCodes.UNHANDLED,
+    };
+}
 /**
  * Soft-delete a document.
  *
@@ -47,7 +65,8 @@ export async function deleteDocument(ctx, params) {
         //    AND a storage provider, fetch with reconstruct: true so we
         //    can read the stored file paths (and persisted variant paths)
         //    from the field values before the DB rows are deleted.
-        const isUploadCollection = hasUploadField(definition) && ctx.storage != null;
+        const storage = ctx.storage;
+        const isUploadCollection = hasUploadField(definition) && storage != null;
         const latest = await db.queries.documents.getDocumentById({
             collection_id: ctx.collectionId,
             document_id: params.documentId,
@@ -99,15 +118,20 @@ export async function deleteDocument(ctx, params) {
         };
         // 2. beforeDelete hook.
         await invokeHook(hooks?.beforeDelete, hookCtx);
-        // 3. Soft-delete all versions, atomically with the audit record. A
+        // 3. Soft-delete all versions atomically with the document audit and,
+        //    for tree collections, locked child promotion/removal plus every
+        //    parent/child tree audit row. Any failure rolls the entire delete
+        //    back, so soft-deleted documents cannot leak live edges.
         //    whole-document delete mints no new version, so the version stream
         //    never records it — the audit log is the only place a deletion is
         //    accountable (docs/06-auth-and-security/02-auditability.md). Storage-file cleanup (step 4) is a
         //    DB↔external side-effect and stays OUTSIDE the transaction — it is
         //    post-commit, best-effort compensation (docs/03-architecture/03-transactions.md).
-        const audit = requireAuditCapability(db);
+        const treeAudit = definition.tree === true ? requireTreeAuditCapability(db) : undefined;
+        const audit = treeAudit ?? requireAuditCapability(db);
         const actor = auditActor(ctx);
         let deletedVersionCount = 0;
+        let treeResult;
         await audit.withTransaction(async () => {
             deletedVersionCount = await db.commands.documents.softDeleteDocument({
                 document_id: params.documentId,
@@ -119,36 +143,77 @@ export async function deleteDocument(ctx, params) {
                 actorRealm: actor.actorRealm,
                 action: AUDIT_ACTIONS.deleted,
             });
+            if (treeAudit != null) {
+                treeResult = await reconcileTreeOnDeleteInTransaction(ctx, params.documentId, treeAudit);
+            }
         });
-        // 4. Clean up storage files. Non-fatal: logs errors but does not throw.
-        if (ctx.storage && storagePathsToDelete.length > 0) {
+        // Everything below is post-commit. Each operation and the logger get an
+        // independent attempt; none can turn the committed delete into a rejection.
+        const sideEffectFailures = [];
+        // 4. Clean up every storage file. Returned failures omit paths, while
+        // internal logs retain the target needed for operational reconciliation.
+        if (storage && storagePathsToDelete.length > 0) {
             for (const storagePath of storagePathsToDelete) {
                 try {
-                    await ctx.storage.delete(storagePath);
+                    await storage.delete(storagePath);
                 }
-                catch (err) {
-                    logger.error({ err, storagePath }, 'failed to delete storage file');
+                catch (error) {
+                    sideEffectFailures.push(serializeSideEffectFailure('storageCleanup', error));
+                    try {
+                        logger.error({ err: error, documentId: params.documentId, storagePath }, 'failed to delete storage file');
+                    }
+                    catch {
+                        // Diagnostic logging must not interrupt the remaining cleanup attempts.
+                    }
                 }
             }
         }
-        // 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/04-collections/03-document-trees.md.
-        if (definition.tree === true) {
+        // 5-6. Both post-commit hook families get an independent attempt. A tree
+        // invalidation failure must not prevent afterDelete consumers (search,
+        // cache removal) from running, or vice versa.
+        try {
+            if (treeResult != null) {
+                await firePromoteTreeChange(ctx, params.documentId, treeResult);
+            }
+        }
+        catch (error) {
+            sideEffectFailures.push(serializeSideEffectFailure('afterTreeChange', error));
+            try {
+                logger.error({ err: error, documentId: params.documentId }, 'afterTreeChange hook failed after document delete');
+            }
+            catch {
+                // Diagnostic logging must not affect the committed result.
+            }
+        }
+        try {
+            await invokeHook(hooks?.afterDelete, hookCtx);
+        }
+        catch (error) {
+            sideEffectFailures.push(serializeSideEffectFailure('afterDelete', error));
+            try {
+                logger.error({ err: error, documentId: params.documentId }, 'afterDelete hook failed after document delete');
+            }
+            catch {
+                // Diagnostic logging must not affect the committed result.
+            }
+        }
+        const [firstFailure, ...remainingFailures] = sideEffectFailures;
+        if (firstFailure != null) {
             try {
-                await promoteChildrenAndRemove(ctx, { documentId: params.documentId });
+                logger.error({
+                    documentId: params.documentId,
+                    sideEffectFailures: [firstFailure, ...remainingFailures],
+                }, 'post-commit delete side effects failed');
             }
-            catch (err) {
-                logger.error({ err, documentId: params.documentId }, 'failed to reconcile document tree on delete');
+            catch {
+                // A reporting failure cannot change the already-committed outcome.
             }
+            return {
+                deletedVersionCount,
+                outcome: 'committed-with-side-effect-failures',
+                sideEffectFailures: [firstFailure, ...remainingFailures],
+            };
         }
-        // 6. afterDelete hook.
-        await invokeHook(hooks?.afterDelete, hookCtx);
-        return { deletedVersionCount };
+        return { deletedVersionCount, outcome: 'committed', sideEffectFailures: [] };
     });
 }

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

@@ -35,7 +35,7 @@ export { updateDocument, updateDocumentWithPatches } from './update.js';
 export type { DocumentLifecycleContext } from './context.js';
 export type { CopyToLocaleResult } from './copy-to-locale.js';
 export type { CreateDocumentResult } from './create.js';
-export type { DeleteDocumentResult } from './delete.js';
+export type { DeleteDocumentCommittedResult, DeleteDocumentCommittedWithSideEffectFailuresResult, DeleteDocumentOutcome, DeleteDocumentResult, DeleteDocumentSideEffectCode, DeleteDocumentSideEffectFailure, DeleteDocumentSideEffectPhase, } from './delete.js';
 export type { DeleteLocaleResult } from './delete-locale.js';
 export type { DuplicateDocumentResult } from './duplicate.js';
 export type { RestoreVersionResult } from './restore.js';

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

@@ -59,26 +59,6 @@ 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/04-collections/03-document-trees.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`. */