@byline/core 3.21.0 → 4.1.0

package/dist/query/parse-where.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { ERR_VALIDATION } from '../lib/errors.js';
 import { fieldTypeToStore } from '../storage/field-store-map.js';
 // ---------------------------------------------------------------------------
 // Document-level reserved keys
@@ -44,6 +45,144 @@ const DOCUMENT_SORT_COLUMNS = {
 export async function parseWhere(where, definition, ctx) {
     return parseWhereInternal(where, definition, ctx, { isNested: false, inCombinator: false });
 }
+/**
+ * Compile a predicate wholly to adapter `DocumentFilter`s. Unlike
+ * `parseWhere`, top-level `status` and `path` are emitted as document-column
+ * filters rather than scalar list-query options. This is the form used by
+ * `beforeRead` on detail, populate, count, and tree reads.
+ */
+export async function parsePredicateFilters(where, definition, ctx, options = {}) {
+    if (options.strict) {
+        await validateSecurityPredicate(where, definition, ctx);
+    }
+    const parsed = await parseWhereInternal(where, definition, ctx, {
+        isNested: false,
+        inCombinator: true,
+    });
+    return parsed.filters;
+}
+const FILTER_OPERATORS = new Set([
+    '$eq',
+    '$ne',
+    '$gt',
+    '$gte',
+    '$lt',
+    '$lte',
+    '$contains',
+    '$in',
+    '$nin',
+]);
+const DOCUMENT_COLUMN_OPERATORS = {
+    status: new Set(['$eq', '$ne', '$in', '$nin']),
+    path: new Set(['$eq', '$ne', '$contains', '$in', '$nin']),
+    id: new Set(['$eq', '$ne', '$in', '$nin']),
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Fail-closed validation used only for security predicates from hooks. */
+async function validateSecurityPredicate(predicate, definition, ctx, allowEmpty = false) {
+    if (predicate == null || typeof predicate !== 'object' || Array.isArray(predicate)) {
+        throw invalidSecurityPredicate(definition.path, 'predicate must be an object');
+    }
+    const entries = Object.entries(predicate).filter(([, value]) => value !== undefined);
+    if (entries.length === 0 && !allowEmpty) {
+        throw invalidSecurityPredicate(definition.path, 'predicate must contain at least one clause');
+    }
+    for (const [key, value] of entries) {
+        if (key === '$and' || key === '$or') {
+            if (!Array.isArray(value) || value.length === 0) {
+                throw invalidSecurityPredicate(definition.path, `${key} must be a non-empty array`);
+            }
+            for (const child of value) {
+                await validateSecurityPredicate(child, definition, ctx);
+            }
+            continue;
+        }
+        if (key === 'query') {
+            throw invalidSecurityPredicate(definition.path, '`query` is not supported in beforeRead security predicates');
+        }
+        if (key === 'status' || key === 'path' || key === 'id') {
+            validateDocumentColumnPredicate(value, definition.path, key);
+            continue;
+        }
+        const field = definition.fields.find((candidate) => candidate.name === key);
+        if (field == null) {
+            throw invalidSecurityPredicate(definition.path, `unknown field '${key}'`);
+        }
+        if (field.type === 'relation' && (isQuantifierObject(value) || isPlainSubWhere(value))) {
+            const targetPath = field.targetCollection;
+            const target = targetPath
+                ? ctx?.collections.find((candidate) => candidate.path === targetPath)
+                : null;
+            if (target == null) {
+                throw invalidSecurityPredicate(definition.path, `cannot resolve target collection for relation field '${key}'`);
+            }
+            if (isQuantifierObject(value)) {
+                for (const [quantifier, nested] of Object.entries(value)) {
+                    await validateSecurityPredicate(nested, target, ctx, quantifier === '$none');
+                }
+            }
+            else {
+                await validateSecurityPredicate(value, target, ctx);
+            }
+            continue;
+        }
+        if (fieldTypeToStore[field.type] == null) {
+            throw invalidSecurityPredicate(definition.path, `field '${key}' cannot be used as a predicate`);
+        }
+        validateSecurityOperator(value, definition.path, key);
+    }
+}
+function validateDocumentColumnPredicate(value, collectionPath, column) {
+    validateSecurityOperator(value, collectionPath, column);
+    const parsed = normaliseToOperator(value);
+    if (parsed == null || !DOCUMENT_COLUMN_OPERATORS[column].has(parsed.operator)) {
+        throw invalidSecurityPredicate(collectionPath, `operator '${parsed?.operator ?? 'unknown'}' is not supported for '${column}'`);
+    }
+    const values = Array.isArray(parsed.value) ? parsed.value : [parsed.value];
+    if ((parsed.operator === '$in' || parsed.operator === '$nin') && !Array.isArray(parsed.value)) {
+        throw invalidSecurityPredicate(collectionPath, `${parsed.operator} for '${column}' requires an array`);
+    }
+    if (parsed.operator !== '$in' && parsed.operator !== '$nin' && Array.isArray(parsed.value)) {
+        throw invalidSecurityPredicate(collectionPath, `${parsed.operator} for '${column}' requires a string`);
+    }
+    if (values.some((item) => typeof item !== 'string')) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for '${column}' requires string values`);
+    }
+    if (column === 'id' && values.some((item) => !UUID_RE.test(item))) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for 'id' requires UUID values; use { id: { $in: [] } } to deny all rows`);
+    }
+}
+function validateSecurityOperator(value, collectionPath, fieldName) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw invalidSecurityPredicate(collectionPath, `invalid predicate for '${fieldName}'`);
+    }
+    const entries = Object.entries(value);
+    if (entries.length !== 1 || !FILTER_OPERATORS.has(entries[0]?.[0] ?? '')) {
+        throw invalidSecurityPredicate(collectionPath, `predicate for '${fieldName}' must contain exactly one supported operator`);
+    }
+    const [operator, operand] = entries[0] ?? [];
+    if ((operator === '$in' || operator === '$nin') && !Array.isArray(operand)) {
+        throw invalidSecurityPredicate(collectionPath, `${operator} for '${fieldName}' requires an array`);
+    }
+    if (operator === '$contains' && typeof operand !== 'string') {
+        throw invalidSecurityPredicate(collectionPath, `$contains for '${fieldName}' requires a string`);
+    }
+    if (operand === undefined) {
+        throw invalidSecurityPredicate(collectionPath, `operator for '${fieldName}' requires a value`);
+    }
+}
+function invalidSecurityPredicate(collectionPath, reason) {
+    return ERR_VALIDATION({
+        message: `invalid beforeRead predicate for '${collectionPath}': ${reason}`,
+        details: { collectionPath, reason },
+    });
+}
 /**
  * Combine a `beforeRead` hook predicate with a caller-supplied where
  * clause using implicit AND. Returns whichever side is non-empty, or
@@ -179,7 +318,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                         kind: 'docColumn',
                         column: 'status',
                         operator: parsed.operator,
-                        value: parsed.value === null ? null : String(parsed.value),
+                        value: stringifyDocumentColumnValue(parsed.value),
                     });
                 }
                 continue;
@@ -211,7 +350,7 @@ async function parseWhereInternal(where, definition, ctx, { isNested, inCombinat
                         kind: 'docColumn',
                         column: 'path',
                         operator: parsed.operator,
-                        value: parsed.value === null ? null : String(parsed.value),
+                        value: stringifyDocumentColumnValue(parsed.value),
                     });
                 }
                 continue;
@@ -449,5 +588,10 @@ function normaliseToOperator(raw) {
         value: val,
     };
 }
+function stringifyDocumentColumnValue(value) {
+    if (value === null)
+        return null;
+    return Array.isArray(value) ? value.map(String) : String(value);
+}
 /** Exported for testing. */
 export { DOCUMENT_LEVEL_KEYS, DOCUMENT_SORT_COLUMNS };

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.
  *