@byline/core 3.20.4 → 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/schemas/zod/builder.js

@@ -118,9 +118,12 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = z.number().int();
             break;
         case 'float':
-        case 'decimal':
             schema = z.number();
             break;
+        case 'decimal':
+            // Postgres numeric values are restored as strings to preserve precision.
+            schema = z.string();
+            break;
         case 'image':
         case 'file': {
             // StoredFileValue — the object written by the upload endpoint and
@@ -132,7 +135,7 @@ export const fieldToZodSchema = (field, strict = true) => {
                 filename: z.string(),
                 originalFilename: z.string(),
                 mimeType: z.string(),
-                fileSize: z.string(),
+                fileSize: z.number(),
                 storageProvider: z.string(),
                 storagePath: z.string(),
                 storageUrl: z.string().nullable().optional(),
@@ -181,7 +184,8 @@ export const fieldToZodSchema = (field, strict = true) => {
                 schema = arr;
             }
             else {
-                schema = relationValue.nullable();
+                // Storage omits cleared values; it never restores a relation as null.
+                schema = relationValue;
             }
             break;
         }

package/dist/schemas/zod/builder.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schemas/zod/builder.test.node.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { defineCollection } from '../../@types/collection-types.js';
+import { createCollectionSchemas } from './builder.js';
+const Assets = defineCollection({
+    path: 'assets',
+    labels: { singular: 'Asset', plural: 'Assets' },
+    fields: [
+        { name: 'price', type: 'decimal' },
+        { name: 'download', type: 'file' },
+        { name: 'owner', type: 'relation', targetCollection: 'people' },
+    ],
+});
+const fieldsFixture = {
+    price: '1234567890.123456789',
+    download: {
+        fileId: 'file-1',
+        filename: 'report.pdf',
+        originalFilename: 'Report.pdf',
+        mimeType: 'application/pdf',
+        fileSize: 4096,
+        storageProvider: 'local',
+        storagePath: 'assets/report.pdf',
+        processingStatus: 'complete',
+    },
+    owner: {
+        targetDocumentId: 'person-1',
+        targetCollectionId: 'people',
+    },
+};
+describe('collection Zod schemas', () => {
+    it('parses the canonical decimal and file storage read shapes', () => {
+        const parsed = createCollectionSchemas(Assets).get.parse({
+            id: '550e8400-e29b-41d4-a716-446655440000',
+            status: 'published',
+            createdAt: '2026-07-15T12:00:00.000Z',
+            updatedAt: '2026-07-15T12:00:00.000Z',
+            fields: fieldsFixture,
+        });
+        expect(parsed.fields.price).toBe(fieldsFixture.price);
+        expect(parsed.fields.download?.fileSize).toBe(4096);
+    });
+    it('rejects null for a required single relation in the strict fields schema', () => {
+        const result = createCollectionSchemas(Assets).fields.safeParse({
+            ...fieldsFixture,
+            owner: null,
+        });
+        expect(result.success).toBe(false);
+    });
+});

package/dist/services/collection-bootstrap.d.ts

@@ -19,7 +19,7 @@ export interface CollectionRecord {
     schemaHash: string;
 }
 export interface EnsureCollectionsInput {
-    definitions: CollectionDefinition[];
+    definitions: readonly CollectionDefinition[];
     db: IDbAdapter;
     logger?: BylineLogger;
 }

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.d.ts

@@ -9,7 +9,7 @@ import { type CollectionDefinition } from '../@types/index.js';
 import type { IDbAdapter } from '../@types/db-types.js';
 import type { BylineLogger } from '../lib/logger.js';
 export interface DiscoverCounterGroupsInput {
-    definitions: CollectionDefinition[];
+    definitions: readonly CollectionDefinition[];
     db: IDbAdapter;
     logger?: BylineLogger;
 }

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.d.ts

@@ -17,8 +17,8 @@ export interface CreateDocumentResult {
  *   1. Default-locale enforcement: reject if `params.locale` is anything
  *      other than the configured default content locale (a brand-new
  *      document's canonical `path` lives in the default locale).
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeCreate({ data, collectionPath })`, then normalize numerics again
  *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
  *      → UUID fallback.
  *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')

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

@@ -13,7 +13,10 @@ 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, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { normalizeNumericFields } from '../normalize-numeric-fields.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.
  *
@@ -21,8 +24,8 @@ import { actorId, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumen
  *   1. Default-locale enforcement: reject if `params.locale` is anything
  *      other than the configured default content locale (a brand-new
  *      document's canonical `path` lives in the default locale).
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeCreate({ data, collectionPath })`, then normalize numerics again
  *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
  *      → UUID fallback.
  *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
@@ -32,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;
@@ -42,7 +49,9 @@ export async function createDocument(ctx, params) {
             }).log(ctx.logger);
         }
         normaliseDateFields(data);
+        normalizeNumericFields(definition.fields, data);
         await invokeHook(hooks?.beforeCreate, { data, collectionPath });
+        normalizeNumericFields(definition.fields, data);
         // Allocate counter-field values after beforeCreate so user-land hooks
         // can run their own logic on the raw payload, but before the flatten/
         // insert pass so the assigned values are persisted on the same write.
@@ -83,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.
  *