@byline/client 4.19.0 → 5.0.0

package/dist/collection-handle.d.ts

@@ -5,9 +5,10 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, DocumentWritePrecondition, RestoreVersionResult, StructuralMutationReceipt, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import { readSingletonForEdit } from './read-internals.js';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, EditableDocument, EditableFindResult, EditableSingleton, EditableTreeNode, FindByIdForEditOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindForEditOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeForEditOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -28,6 +29,7 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * (LATERAL JOINs).
      */
     find<F = TFields>(options?: FindOptions<F>): Promise<FindResult<F>>;
+    findForEdit<F = TFields>(options?: FindForEditOptions<F>): Promise<EditableFindResult<F>>;
     /**
      * Find a single document matching the given options. Returns `null` if no
      * document matches.
@@ -97,6 +99,9 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Find a document by its logical document ID.
      */
     findById<F = TFields>(documentId: string, options?: FindByIdOptions<F>): Promise<ClientDocument<F> | null>;
+    findByIdForEdit<F = TFields>(documentId: string, options?: FindByIdForEditOptions<F>): Promise<EditableDocument<F> | null>;
+    [readSingletonForEdit]<F = TFields>(options?: FindByIdForEditOptions<F>): Promise<EditableSingleton<F> | null>;
+    private readOneForEdit;
     /**
      * Find a document by its URL path/slug. Returns `null` when no document
      * exists at the given path (the storage adapter resolves missing paths
@@ -116,34 +121,41 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Creates a new immutable version row. Hooks receive the real previous
      * version as `originalData`.
      */
-    update(documentId: string, data: Record<string, any>, options?: UpdateOptions): Promise<UpdateDocumentResult>;
+    update(documentId: string, data: Record<string, any>, options: UpdateOptions): Promise<UpdateDocumentResult>;
     /**
      * Change a document's workflow status. The transition is validated
      * against the collection's declared workflow (±1 step or reset-to-first);
      * transitioning to `'published'` auto-archives any other published
      * versions of the same document.
      */
-    changeStatus(documentId: string, nextStatus: string): Promise<ChangeStatusResult>;
+    changeStatus(documentId: string, nextStatus: string, options: DocumentWritePrecondition): Promise<ChangeStatusResult>;
     /**
      * Arm or reschedule publication of the exact current version the caller
      * reviewed. The lifecycle requires both `changeStatus` and `publish` and
      * validates the instant against database time.
      */
-    schedulePublish(documentId: string, options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo>;
+    schedulePublish(documentId: string, options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo & {
+        revision: number;
+    }>;
     /** Re-authorize a content-edited schedule against the reviewed version. */
-    confirmScheduledPublish(documentId: string, options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo>;
+    confirmScheduledPublish(documentId: string, options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo & {
+        revision: number;
+    }>;
     /**
      * Cancel the active schedule. A null result means no schedule remained when
      * the cancellation transaction acquired the row lock; callers must not
      * report that outcome as a successful cancellation.
      */
-    cancelScheduledPublish(documentId: string): Promise<DocumentPublishScheduleInfo | null>;
+    cancelScheduledPublish(documentId: string, options: DocumentWritePrecondition): Promise<{
+        schedule: DocumentPublishScheduleInfo | null;
+        revision: number;
+    }>;
     /** Read the active document-grain schedule under the same two abilities. */
     getScheduledPublish(documentId: string): Promise<DocumentPublishScheduleInfo | null>;
     /**
      * Archive the currently-published version(s) of a document.
      */
-    unpublish(documentId: string): Promise<UnpublishResult>;
+    unpublish(documentId: string, options: DocumentWritePrecondition): Promise<UnpublishResult>;
     /**
      * Restore a historical version as the new current version of this
      * document. Creates a new immutable version row whose content is copied
@@ -155,7 +167,7 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * a `restore: { sourceVersionId }` field on the hook context so userland
      * hooks can branch.
      */
-    restoreVersion(documentId: string, sourceVersionId: string): Promise<RestoreVersionResult>;
+    restoreVersion(documentId: string, sourceVersionId: string, options: DocumentWritePrecondition): Promise<RestoreVersionResult>;
     /**
      * Soft-delete a document. All versions are flagged `is_deleted = true`
      * and disappear from read paths (the `current_documents` view filters
@@ -164,7 +176,7 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * every persisted variant on each upload-capable field are removed
      * after the DB soft-delete — failures there are logged but non-fatal.
      */
-    delete(documentId: string): Promise<DeleteDocumentResult>;
+    delete(documentId: string, options: DocumentWritePrecondition): Promise<DeleteDocumentResult>;
     /**
      * Sum the current-version workflow status buckets visible to the actor,
      * optionally selecting one exact status. This is an editorial status-count
@@ -237,13 +249,13 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      */
     placeTreeNode(documentId: string, options: PlaceTreeNodeOptions): Promise<{
         orderKey: string;
-    }>;
+    } & StructuralMutationReceipt>;
     /**
      * Remove a document from the tree, returning it to the *unplaced* state (still
      * in the collection, but not in any table of contents). Distinct from
      * deleting the document. No-op when already unplaced.
      */
-    removeFromTree(documentId: string, options?: RemoveFromTreeOptions): Promise<void>;
+    removeFromTree(documentId: string, options: RemoveFromTreeOptions): Promise<StructuralMutationReceipt>;
     /**
      * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
      * `ClientDocument`s. `rootDocumentId: null` (default) returns the whole tree
@@ -254,6 +266,13 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * a hidden node and its descendants are omitted, never promoted.
      */
     getSubtree<F = TFields>(options?: GetSubtreeOptions<F>): Promise<TreeNode<F>[]>;
+    getSubtreeForEdit<F = TFields>(options?: GetSubtreeForEditOptions<F>): Promise<EditableTreeNode<F>[]>;
+    /** Whole admin tree and scoped unplaced documents share one structural snapshot. */
+    getTreeForEdit<F = TFields>(options?: Omit<GetSubtreeForEditOptions<F>, 'rootDocumentId' | 'depth'>): Promise<{
+        forest: EditableTreeNode<F>[];
+        unplaced: EditableDocument<F>[];
+    }>;
+    private readTreeForEdit;
     /**
      * Walk a document's ancestor chain upward, returning the ancestors
      * **root-first** (the breadcrumb trail, excluding the node itself), hydrated
@@ -274,6 +293,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * redacted to null. Structure-only — no document hydration.
      */
     getTreeParent(documentId: string, options?: GetTreeParentOptions): Promise<TreeParentResult>;
+    private captureEditObservations;
+    private shapeEditable;
     /**
      * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
      * resolved collection id, inherits the client-wide logger and storage

package/dist/collection-handle.js

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, assertActorCanPerform, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, assertActorCanPerform, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, documentAbilityKey, documentRevisionFromDatabase, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
-import { expectedDocumentId } from './read-internals.js';
+import { expectedDocumentId, readSingletonForEdit, } from './read-internals.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
 import { assertSearchFieldScope, assertSearchQueryLength, finalizeSearchHits } from './search.js';
 function toScheduleInfo(schedule) {
@@ -82,6 +82,57 @@ export class CollectionHandle {
             },
         };
     }
+    async findForEdit(options = {}) {
+        assertEditableOptions(options);
+        const readMode = 'any';
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const { where, select, sort, locale = this.client.defaultLocale, page = 1, pageSize = 20, } = options;
+        const securityFilters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const parsedWhere = await parseWhere(where, this.definition, {
+            collections: this.client.collections,
+            resolveCollectionId: (path) => this.client.resolveCollectionId(path),
+            logger: this.client.logger,
+        });
+        if (securityFilters)
+            parsedWhere.filters.push(...securityFilters);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        const parsedSort = parseSort(sort, this.definition);
+        const { result, observations } = await this.client.db.withReadSnapshot(async (queries) => {
+            const result = await queries.documents.findDocuments({
+                collection_id: collectionId,
+                filters: parsedWhere.filters,
+                status: parsedWhere.status,
+                pathFilter: parsedWhere.pathFilter,
+                query: parsedWhere.query,
+                sort: parsedSort.fieldSort,
+                orderBy: parsedSort.orderBy,
+                orderDirection: parsedSort.orderDirection,
+                locale,
+                page,
+                pageSize,
+                fields: select,
+                readMode,
+                onMissingLocale: options.onMissingLocale ?? 'fallback',
+            });
+            const observations = await this.captureEditObservations(queries, collectionId, result.documents, requestContext);
+            return { result, observations };
+        });
+        await this.populateIfRequested(collectionId, result.documents, locale, readMode, requestContext, {
+            ...options,
+            _readContext: readCtx,
+        });
+        await this.finishReadDocuments(result.documents, readCtx, requestContext, locale, readMode, options._bypassBeforeRead, select, readMaterialization(options.populate, options.depth));
+        return {
+            docs: result.documents.map((d, index) => this.shapeEditable(d, observations[index])),
+            meta: {
+                total: result.total,
+                page,
+                pageSize,
+                totalPages: Math.ceil(result.total / pageSize),
+            },
+        };
+    }
     /**
      * Find a single document matching the given options. Returns `null` if no
      * document matches.
@@ -337,6 +388,63 @@ export class CollectionHandle {
         await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
         return this.shapeWithPopulated(raw);
     }
+    async findByIdForEdit(documentId, options = {}) {
+        if (typeof documentId !== 'string' || !documentId)
+            throw ERR_VALIDATION({ message: 'A document ID is required' });
+        const result = await this.readOneForEdit(documentId, options);
+        return result === 'empty' ? null : result;
+    }
+    async [readSingletonForEdit](options = {}) {
+        const result = await this.readOneForEdit(null, options);
+        if (result === 'empty')
+            return { state: 'empty' };
+        if (result == null)
+            return null;
+        const { path: _path, ...document } = result;
+        return { state: 'document', document };
+    }
+    async readOneForEdit(documentId, options = {}) {
+        assertEditableOptions(options);
+        const readMode = 'any';
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const { locale = this.client.defaultLocale } = options;
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        const snapshot = await this.client.db.withReadSnapshot(async (queries) => {
+            const sourceId = documentId ?? (await queries.singletons.getMappedDocumentId(collectionId));
+            if (sourceId == null)
+                return 'empty';
+            const raw = await queries.documents.getDocumentById({
+                collection_id: collectionId,
+                document_id: sourceId,
+                locale,
+                reconstruct: true,
+                readMode,
+                filters,
+                lenient: options.lenient,
+                onMissingLocale: options.onMissingLocale ?? 'fallback',
+            });
+            if (raw == null)
+                return null;
+            const observations = await this.captureEditObservations(queries, collectionId, [raw], requestContext);
+            return { raw, observation: observations[0] };
+        });
+        if (snapshot == null || snapshot === 'empty')
+            return snapshot;
+        const { raw, observation } = snapshot;
+        // Trim to selected fields BEFORE populate so populate doesn't waste work
+        // on relations the caller filtered out. Mutates `raw.fields` in place.
+        if (options.select?.length) {
+            trimFields(raw, options.select);
+        }
+        await this.populateIfRequested(collectionId, [raw], locale, readMode, requestContext, {
+            ...options,
+            _readContext: readCtx,
+        });
+        await this.finishReadDocuments([raw], readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, readMaterialization(options.populate, options.depth));
+        return this.shapeEditable(raw, observation);
+    }
     /**
      * Find a document by its URL path/slug. Returns `null` when no document
      * exists at the given path (the storage adapter resolves missing paths
@@ -404,14 +512,15 @@ export class CollectionHandle {
      * Creates a new immutable version row. Hooks receive the real previous
      * version as `originalData`.
      */
-    async update(documentId, data, options = {}) {
+    async update(documentId, data, options) {
         const ctx = await this.buildLifecycleContext();
         return updateDocument(ctx, {
             documentId,
             data,
-            locale: options.locale,
-            path: options.path,
-            availableLocales: options.availableLocales,
+            expectedRevision: options?.expectedRevision,
+            locale: options?.locale,
+            path: options?.path,
+            availableLocales: options?.availableLocales,
         });
     }
     /**
@@ -420,9 +529,13 @@ export class CollectionHandle {
      * transitioning to `'published'` auto-archives any other published
      * versions of the same document.
      */
-    async changeStatus(documentId, nextStatus) {
+    async changeStatus(documentId, nextStatus, options) {
         const ctx = await this.buildLifecycleContext();
-        return changeDocumentStatus(ctx, { documentId, nextStatus });
+        return changeDocumentStatus(ctx, {
+            documentId,
+            nextStatus,
+            expectedRevision: options?.expectedRevision,
+        });
     }
     /**
      * Arm or reschedule publication of the exact current version the caller
@@ -431,22 +544,30 @@ export class CollectionHandle {
      */
     async schedulePublish(documentId, options) {
         const ctx = await this.buildLifecycleContext();
-        return toScheduleInfo(await scheduleDocumentPublish(ctx, { documentId, ...options }));
+        const result = await scheduleDocumentPublish(ctx, { documentId, ...options });
+        return { ...toScheduleInfo(result), revision: result.revision };
     }
     /** Re-authorize a content-edited schedule against the reviewed version. */
     async confirmScheduledPublish(documentId, options) {
         const ctx = await this.buildLifecycleContext();
-        return toScheduleInfo(await confirmDocumentScheduledPublish(ctx, { documentId, ...options }));
+        const result = await confirmDocumentScheduledPublish(ctx, { documentId, ...options });
+        return { ...toScheduleInfo(result), revision: result.revision };
     }
     /**
      * Cancel the active schedule. A null result means no schedule remained when
      * the cancellation transaction acquired the row lock; callers must not
      * report that outcome as a successful cancellation.
      */
-    async cancelScheduledPublish(documentId) {
+    async cancelScheduledPublish(documentId, options) {
         const ctx = await this.buildLifecycleContext();
-        const schedule = await cancelDocumentScheduledPublish(ctx, { documentId });
-        return schedule == null ? null : toScheduleInfo(schedule);
+        const result = await cancelDocumentScheduledPublish(ctx, {
+            documentId,
+            expectedRevision: options?.expectedRevision,
+        });
+        return {
+            schedule: result.schedule == null ? null : toScheduleInfo(result.schedule),
+            revision: result.revision,
+        };
     }
     /** Read the active document-grain schedule under the same two abilities. */
     async getScheduledPublish(documentId) {
@@ -457,9 +578,9 @@ export class CollectionHandle {
     /**
      * Archive the currently-published version(s) of a document.
      */
-    async unpublish(documentId) {
+    async unpublish(documentId, options) {
         const ctx = await this.buildLifecycleContext();
-        return unpublishDocument(ctx, { documentId });
+        return unpublishDocument(ctx, { documentId, expectedRevision: options?.expectedRevision });
     }
     /**
      * Restore a historical version as the new current version of this
@@ -472,9 +593,13 @@ export class CollectionHandle {
      * a `restore: { sourceVersionId }` field on the hook context so userland
      * hooks can branch.
      */
-    async restoreVersion(documentId, sourceVersionId) {
+    async restoreVersion(documentId, sourceVersionId, options) {
         const ctx = await this.buildLifecycleContext();
-        return restoreDocumentVersion(ctx, { documentId, sourceVersionId });
+        return restoreDocumentVersion(ctx, {
+            documentId,
+            sourceVersionId,
+            expectedRevision: options?.expectedRevision,
+        });
     }
     /**
      * Soft-delete a document. All versions are flagged `is_deleted = true`
@@ -484,9 +609,9 @@ export class CollectionHandle {
      * every persisted variant on each upload-capable field are removed
      * after the DB soft-delete — failures there are logged but non-fatal.
      */
-    async delete(documentId) {
+    async delete(documentId, options) {
         const ctx = await this.buildLifecycleContext();
-        return deleteDocument(ctx, { documentId });
+        return deleteDocument(ctx, { documentId, expectedRevision: options?.expectedRevision });
     }
     /**
      * Sum the current-version workflow status buckets visible to the actor,
@@ -658,10 +783,11 @@ export class CollectionHandle {
         const ctx = await this.buildLifecycleContext();
         return placeTreeNodeLifecycle(ctx, {
             documentId,
-            parentDocumentId: options.parentDocumentId,
-            beforeDocumentId: options.beforeDocumentId ?? null,
-            afterDocumentId: options.afterDocumentId ?? null,
-            reconcile: options.reconcile,
+            expectedRevision: options?.expectedRevision,
+            parentDocumentId: options?.parentDocumentId,
+            beforeDocumentId: options?.beforeDocumentId ?? null,
+            afterDocumentId: options?.afterDocumentId ?? null,
+            reconcile: options?.reconcile,
         });
     }
     /**
@@ -669,10 +795,14 @@ export class CollectionHandle {
      * in the collection, but not in any table of contents). Distinct from
      * deleting the document. No-op when already unplaced.
      */
-    async removeFromTree(documentId, options = {}) {
+    async removeFromTree(documentId, options) {
         this.assertTreeCollection();
         const ctx = await this.buildLifecycleContext();
-        await removeFromTreeLifecycle(ctx, { documentId, reconcile: options.reconcile });
+        return removeFromTreeLifecycle(ctx, {
+            documentId,
+            expectedRevision: options?.expectedRevision,
+            reconcile: options?.reconcile,
+        });
     }
     /**
      * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
@@ -724,6 +854,99 @@ export class CollectionHandle {
         }
         return roots;
     }
+    async getSubtreeForEdit(options = {}) {
+        return (await this.readTreeForEdit(options, false)).forest;
+    }
+    /** Whole admin tree and scoped unplaced documents share one structural snapshot. */
+    async getTreeForEdit(options = {}) {
+        return this.readTreeForEdit(options, true);
+    }
+    async readTreeForEdit(options, includeUnplaced) {
+        this.assertTreeCollection();
+        assertEditableOptions(options);
+        const readMode = 'any';
+        const readCtx = options._readContext ?? createReadContext();
+        const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
+        const locale = options.locale ?? this.client.defaultLocale;
+        const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        const { structure, raws, observations } = await this.client.db.withReadSnapshot(async (queries) => {
+            const structure = await queries.documents.getTreeSubtree({
+                collectionId,
+                rootDocumentId: options.rootDocumentId ?? null,
+                maxDepth: options.depth,
+                readMode,
+                locale,
+                filters,
+            });
+            const raws = structure.length === 0
+                ? []
+                : await queries.documents.getDocumentsByDocumentIds({
+                    collection_id: collectionId,
+                    document_ids: structure.map((row) => row.document_id),
+                    locale,
+                    readMode,
+                    filters,
+                    fields: options.select,
+                });
+            if (includeUnplaced) {
+                const seen = new Set(raws.map((raw) => raw.document_id));
+                // Preserve the admin's scoped unplaced read, with all pages in the same snapshot.
+                for (let page = 1;; page++) {
+                    const result = await queries.documents.findDocuments({
+                        collection_id: collectionId,
+                        filters,
+                        locale,
+                        readMode,
+                        fields: options.select,
+                        page,
+                        pageSize: 1000,
+                        orderBy: 'document_id',
+                        orderDirection: 'asc',
+                    });
+                    for (const raw of result.documents) {
+                        if (!seen.has(raw.document_id)) {
+                            raws.push(raw);
+                            seen.add(raw.document_id);
+                        }
+                    }
+                    if (page * 1000 >= result.total)
+                        break;
+                }
+            }
+            const observations = await this.captureEditObservations(queries, collectionId, raws, requestContext);
+            return { structure, raws, observations };
+        });
+        await this.finishReadDocuments(raws, readCtx, requestContext, locale, readMode, options._bypassBeforeRead, options.select, 'tree');
+        const shapedById = new Map(raws.map((raw, index) => {
+            const document = this.shapeEditable(raw, observations[index]);
+            return [document.id, document];
+        }));
+        // Assemble the nested forest. Rows arrive pre-order, so a parent is always
+        // materialised before its children; a row whose parent is not in the result
+        // set (null parent, or the requested root's own parent) is a top-level node.
+        const structuralIds = new Set(structure.map((row) => row.document_id));
+        const nodeById = new Map();
+        const roots = [];
+        for (const row of structure) {
+            const document = shapedById.get(row.document_id);
+            if (document == null)
+                continue;
+            const node = { document, depth: row.depth, children: [] };
+            nodeById.set(row.document_id, node);
+            const parent = row.parent_document_id != null ? nodeById.get(row.parent_document_id) : undefined;
+            if (parent) {
+                parent.children.push(node);
+            }
+            else if (row.parent_document_id == null || !structuralIds.has(row.parent_document_id)) {
+                roots.push(node);
+            }
+        }
+        return {
+            forest: roots,
+            unplaced: [...shapedById.values()].filter((doc) => !structuralIds.has(doc.id)),
+        };
+    }
     /**
      * Walk a document's ancestor chain upward, returning the ancestors
      * **root-first** (the breadcrumb trail, excluding the node itself), hydrated
@@ -799,6 +1022,41 @@ export class CollectionHandle {
     // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
+    async captureEditObservations(queries, collectionId, raws, requestContext) {
+        const actor = requestContext.actor;
+        const canSchedule = actor?.hasAbility(documentAbilityKey(this.definition, 'changeStatus')) === true &&
+            actor.hasAbility(documentAbilityKey(this.definition, 'publish'));
+        const observations = [];
+        for (const raw of raws) {
+            const revision = documentRevisionFromDatabase(await queries.documents.getDocumentRevision({
+                collection_id: collectionId,
+                document_id: raw.document_id,
+            }));
+            const schedule = canSchedule
+                ? await queries.documents.publishSchedules.get({
+                    collectionId,
+                    documentId: raw.document_id,
+                })
+                : null;
+            // Capture action identity and status independently of mutable hook input.
+            const { id, versionId, status } = shapeDocument(raw);
+            const source = { id, versionId, status };
+            observations.push({
+                source: structuredClone(source),
+                revision,
+                scheduledPublication: schedule == null ? null : toScheduleInfo(schedule),
+            });
+        }
+        return observations;
+    }
+    shapeEditable(raw, observation) {
+        return {
+            ...this.shapeWithPopulated(raw),
+            ...observation.source,
+            revision: observation.revision,
+            scheduledPublication: observation.scheduledPublication,
+        };
+    }
     /**
      * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
      * resolved collection id, inherits the client-wide logger and storage
@@ -1001,3 +1259,13 @@ function trimFields(raw, select) {
             delete fields[k];
     }
 }
+function assertEditableOptions(options) {
+    const input = options;
+    if (input.status !== undefined ||
+        input.versionId !== undefined ||
+        input.documentVersionId !== undefined) {
+        throw ERR_VALIDATION({
+            message: 'Editable reads select current state and do not accept status or version selectors',
+        });
+    }
+}

package/dist/index.d.ts

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type SingletonSaveResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
+export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type SingletonSaveResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, type UpdateSingletonResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
 export { SingletonHandle } from './singleton-handle.js';
 export type { Register, RegisteredCollections, RegisteredSingletons } from './register.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSingletonOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, SearchFacetBucket, SearchHit, SearchResults, SingletonDocument, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, UpdateSingletonOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, EditableDocument, EditableFindResult, EditableSingleton, EditableTreeNode, FilterOperators, FindByIdForEditOptions, FindByIdOptions, FindByPathOptions, FindForEditOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSingletonOptions, GetSubtreeForEditOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, SearchFacetBucket, SearchHit, SearchResults, SingletonDocument, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, UpdateSingletonOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';

package/dist/read-internals.d.ts

@@ -3,3 +3,5 @@ export declare const expectedDocumentId: unique symbol;
 export interface DocumentBoundFindByVersionOptions {
     [expectedDocumentId]?: string;
 }
+/** Internal singleton slot read; shares the collection reader's authorization pipeline. */
+export declare const readSingletonForEdit: unique symbol;

package/dist/read-internals.js

@@ -1,2 +1,4 @@
 /** Internal ownership constraint for singleton historical reads. */
 export const expectedDocumentId = Symbol('byline.expectedDocumentId');
+/** Internal singleton slot read; shares the collection reader's authorization pipeline. */
+export const readSingletonForEdit = Symbol('byline.readSingletonForEdit');

package/dist/server/request-context-contract.test.node.js

@@ -38,6 +38,7 @@ vi.mock('@byline/core', async () => {
     };
 });
 import { createBylineClient } from '../client.js';
+import { testAdapter } from '../test-adapter.test-helper.js';
 import { getAdminRequestContext } from './admin-context.js';
 const BRIDGE_SLOT = Symbol.for('__byline_host_request_bridge__');
 const previousBridge = globalThis[BRIDGE_SLOT];
@@ -52,7 +53,7 @@ const postsCollection = {
     fields: [{ name: 'title', type: 'text', label: 'Title' }],
 };
 function mockDb() {
-    return {
+    return testAdapter({
         commands: { collections: {}, documents: {}, counters: {} },
         queries: {
             collections: {
@@ -63,7 +64,7 @@ function mockDb() {
                 getDocumentsByDocumentIds: vi.fn().mockResolvedValue([]),
             },
         },
-    };
+    });
 }
 describe('request factory ↔ client authority contract', () => {
     beforeEach(() => {

package/dist/singleton-handle.d.ts

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { ChangeStatusResult, SingletonDefinition, SingletonSaveResult, UnpublishResult } from '@byline/core';
+import type { ChangeStatusResult, DocumentWritePrecondition, SingletonDefinition, SingletonSaveResult, UnpublishResult, UpdateSingletonResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { ClientDocument, ConfirmScheduledPublishOptions, DocumentPublishScheduleInfo, FindByVersionOptions, FindResult, GetSingletonOptions, HistoryOptions, SchedulePublishOptions, SingletonDocument, UpdateSingletonOptions } from './types.js';
+import type { ClientDocument, ConfirmScheduledPublishOptions, DocumentPublishScheduleInfo, EditableSingleton, FindByIdForEditOptions, FindByVersionOptions, FindResult, GetSingletonOptions, HistoryOptions, SchedulePublishOptions, SingletonDocument, UpdateSingletonOptions } from './types.js';
 /**
  * A document-ID-free handle for one registered singleton slot.
  *
@@ -22,17 +22,26 @@ export declare class SingletonHandle<TFields extends Record<string, any> = Recor
     private readonly reader;
     constructor(client: BylineClient<any, any>, definition: SingletonDefinition);
     get(options?: GetSingletonOptions<TFields>): Promise<SingletonDocument<TFields> | null>;
-    update(data: TFields, options?: UpdateSingletonOptions): Promise<SingletonSaveResult>;
-    changeStatus(nextStatus: string): Promise<ChangeStatusResult>;
-    unpublish(): Promise<UnpublishResult>;
-    schedulePublish(options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo>;
-    confirmScheduledPublish(options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo>;
-    cancelScheduledPublish(): Promise<DocumentPublishScheduleInfo | null>;
+    getForEdit(options?: FindByIdForEditOptions<TFields>): Promise<EditableSingleton<TFields> | null>;
+    update(data: TFields, options: UpdateSingletonOptions): Promise<UpdateSingletonResult>;
+    changeStatus(nextStatus: string, options: DocumentWritePrecondition): Promise<ChangeStatusResult>;
+    unpublish(options: DocumentWritePrecondition): Promise<UnpublishResult>;
+    schedulePublish(options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo & {
+        revision: number;
+    }>;
+    confirmScheduledPublish(options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo & {
+        revision: number;
+    }>;
+    cancelScheduledPublish(options: DocumentWritePrecondition): Promise<{
+        schedule: DocumentPublishScheduleInfo | null;
+        revision: number;
+    }>;
     getScheduledPublish(): Promise<DocumentPublishScheduleInfo | null>;
     history<F = TFields>(options?: HistoryOptions): Promise<FindResult<F>>;
     findByVersion<F = TFields>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
-    restoreVersion(sourceVersionId: string): Promise<SingletonSaveResult>;
+    restoreVersion(sourceVersionId: string, options: DocumentWritePrecondition): Promise<SingletonSaveResult>;
     copyToLocale(args: {
+        expectedRevision: number;
         sourceLocale: string;
         targetLocale: string;
         overwrite?: boolean;

package/dist/singleton-handle.js

@@ -8,7 +8,7 @@
 import { assertActorCanPerform, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copySingletonToLocale, createReadContext, ERR_NOT_FOUND, getDocumentScheduledPublish, resolveSingletonDocumentId, restoreSingletonVersion, scheduleDocumentPublish, unpublishDocument, updateSingleton, } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
 import { resolveReadRequestContext } from './read-context.js';
-import { expectedDocumentId } from './read-internals.js';
+import { expectedDocumentId, readSingletonForEdit, } from './read-internals.js';
 function toScheduleInfo(schedule) {
     const { executionToken: _executionToken, executionExpiresAt: _executionExpiresAt, ...info } = schedule;
     return info;
@@ -45,33 +45,48 @@ export class SingletonHandle {
         const { path: _path, ...singleton } = document;
         return singleton;
     }
-    async update(data, options = {}) {
+    async getForEdit(options = {}) {
+        return this.reader[readSingletonForEdit](options);
+    }
+    async update(data, options) {
         const ctx = await this.buildAuthorizedLifecycleContext(['update']);
         return updateSingleton(ctx, { data, ...options });
     }
-    async changeStatus(nextStatus) {
+    async changeStatus(nextStatus, options) {
         const abilities = ['changeStatus'];
         if (nextStatus === 'published')
             abilities.push('publish');
         const { ctx, documentId } = await this.resolveRequiredDocument(abilities);
-        return changeDocumentStatus(ctx, { documentId, nextStatus });
+        return changeDocumentStatus(ctx, {
+            documentId,
+            nextStatus,
+            expectedRevision: options?.expectedRevision,
+        });
     }
-    async unpublish() {
+    async unpublish(options) {
         const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus']);
-        return unpublishDocument(ctx, { documentId });
+        return unpublishDocument(ctx, { documentId, expectedRevision: options?.expectedRevision });
     }
     async schedulePublish(options) {
         const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
-        return toScheduleInfo(await scheduleDocumentPublish(ctx, { documentId, ...options }));
+        const result = await scheduleDocumentPublish(ctx, { documentId, ...options });
+        return { ...toScheduleInfo(result), revision: result.revision };
     }
     async confirmScheduledPublish(options) {
         const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
-        return toScheduleInfo(await confirmDocumentScheduledPublish(ctx, { documentId, ...options }));
+        const result = await confirmDocumentScheduledPublish(ctx, { documentId, ...options });
+        return { ...toScheduleInfo(result), revision: result.revision };
     }
-    async cancelScheduledPublish() {
+    async cancelScheduledPublish(options) {
         const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
-        const schedule = await cancelDocumentScheduledPublish(ctx, { documentId });
-        return schedule == null ? null : toScheduleInfo(schedule);
+        const result = await cancelDocumentScheduledPublish(ctx, {
+            documentId,
+            expectedRevision: options?.expectedRevision,
+        });
+        return {
+            schedule: result.schedule == null ? null : toScheduleInfo(result.schedule),
+            revision: result.revision,
+        };
     }
     async getScheduledPublish() {
         const ctx = await this.buildAuthorizedLifecycleContext(['changeStatus', 'publish']);
@@ -105,13 +120,16 @@ export class SingletonHandle {
         };
         return this.reader.findByVersion(versionId, boundOptions);
     }
-    async restoreVersion(sourceVersionId) {
+    async restoreVersion(sourceVersionId, options) {
         const ctx = await this.buildAuthorizedLifecycleContext(['update']);
-        return restoreSingletonVersion(ctx, { sourceVersionId });
+        return restoreSingletonVersion(ctx, {
+            sourceVersionId,
+            expectedRevision: options?.expectedRevision,
+        });
     }
     async copyToLocale(args) {
         const ctx = await this.buildAuthorizedLifecycleContext(['update']);
-        return copySingletonToLocale(ctx, { ...args, overwrite: args.overwrite ?? false });
+        return copySingletonToLocale(ctx, { ...args, overwrite: args?.overwrite ?? false });
     }
     async authorizeRead(readMode, readContext) {
         const requestContext = await resolveReadRequestContext(this.client, readContext, readMode);

package/dist/test-adapter.test-helper.d.ts

@@ -0,0 +1,26 @@
+import type { IDbAdapter } from '@byline/core';
+/** Unit fixture only: unused capabilities throw, including transactions and snapshots.
+ * Tests must explicitly implement every operation they exercise. Live adapter tests
+ * supply the transaction/rollback evidence; this helper cannot simulate it. */
+type Overrides = Partial<Omit<IDbAdapter, 'commands' | 'queries' | 'revisions'>> & {
+    revisions?: Partial<IDbAdapter['revisions']>;
+    commands?: {
+        collections?: Partial<IDbAdapter['commands']['collections']>;
+        documents?: Partial<Omit<IDbAdapter['commands']['documents'], 'publishSchedules'>> & {
+            publishSchedules?: Partial<IDbAdapter['commands']['documents']['publishSchedules']>;
+        };
+        counters?: Partial<IDbAdapter['commands']['counters']>;
+        audit?: Partial<IDbAdapter['commands']['audit']>;
+        singletons?: Partial<IDbAdapter['commands']['singletons']>;
+    };
+    queries?: {
+        collections?: Partial<IDbAdapter['queries']['collections']>;
+        documents?: Partial<Omit<IDbAdapter['queries']['documents'], 'publishSchedules'>> & {
+            publishSchedules?: Partial<IDbAdapter['queries']['documents']['publishSchedules']>;
+        };
+        audit?: Partial<IDbAdapter['queries']['audit']>;
+        singletons?: Partial<IDbAdapter['queries']['singletons']>;
+    };
+};
+export declare function testAdapter(overrides?: Overrides): IDbAdapter;
+export {};

package/dist/test-adapter.test-helper.js

@@ -0,0 +1,117 @@
+export function testAdapter(overrides = {}) {
+    const unused = () => {
+        throw new Error('Unexpected adapter operation in unit fixture');
+    };
+    return {
+        withTransaction: unused,
+        withReadSnapshot: unused,
+        ...overrides,
+        revisions: {
+            readStructure: unused,
+            assertCompatibleSchema: unused,
+            isInTransaction: () => false,
+            lock: unused,
+            advance: unused,
+            ...overrides.revisions,
+        },
+        commands: {
+            collections: {
+                lockCollectionRegistration: unused,
+                create: unused,
+                update: unused,
+                delete: unused,
+                ...overrides.commands?.collections,
+            },
+            documents: {
+                createDocumentVersion: unused,
+                updateDocumentPath: unused,
+                setDocumentAvailableLocales: unused,
+                setDocumentStatus: unused,
+                archivePublishedVersions: unused,
+                softDeleteDocument: unused,
+                restoreSoftDeletedDocument: unused,
+                deleteDocumentLocale: unused,
+                setOrderKey: unused,
+                placeTreeNode: unused,
+                removeFromTree: unused,
+                promoteChildrenAndRemoveFromTree: unused,
+                ...overrides.commands?.documents,
+                publishSchedules: {
+                    lockDocuments: unused,
+                    schedule: unused,
+                    confirm: unused,
+                    cancel: unused,
+                    suspendForContentEdit: unused,
+                    claimDue: unused,
+                    lockClaim: unused,
+                    deleteClaim: unused,
+                    suspendClaimForContentEdit: unused,
+                    releaseClaim: unused,
+                    ...overrides.commands?.documents?.publishSchedules,
+                },
+            },
+            counters: {
+                ensureCounterGroup: unused,
+                nextCounterValue: unused,
+                nextScopedCounterValue: unused,
+                ...overrides.commands?.counters,
+            },
+            audit: {
+                append: unused,
+                ...overrides.commands?.audit,
+            },
+            singletons: {
+                lockSlot: unused,
+                setMapping: unused,
+                clearMapping: unused,
+                ...overrides.commands?.singletons,
+            },
+        },
+        queries: {
+            collections: {
+                getAllCollections: unused,
+                getCollectionByPath: unused,
+                getCollectionById: unused,
+                ...overrides.queries?.collections,
+            },
+            documents: {
+                getDocumentRevision: unused,
+                getDocumentSystemFieldsForUpdate: unused,
+                getDocumentById: unused,
+                getCurrentVersionMetadata: unused,
+                getCurrentPath: unused,
+                getDocumentByPath: unused,
+                getDocumentByVersion: unused,
+                getDocumentsByVersionIds: unused,
+                getDocumentsByDocumentIds: unused,
+                getDocumentHistory: unused,
+                getPublishedVersion: unused,
+                getPublishedDocumentIds: unused,
+                getDocumentCountsByStatus: unused,
+                findDocuments: unused,
+                getLastOrderKey: unused,
+                getNeighborOrderKeys: unused,
+                getCanonicalDocumentOrder: unused,
+                getTreeAncestors: unused,
+                getTreeChildren: unused,
+                getTreeParent: unused,
+                getTreeSubtree: unused,
+                ...overrides.queries?.documents,
+                publishSchedules: {
+                    get: unused,
+                    list: unused,
+                    ...overrides.queries?.documents?.publishSchedules,
+                },
+            },
+            audit: {
+                getDocumentAuditLog: unused,
+                findAuditLog: unused,
+                ...overrides.queries?.audit,
+            },
+            singletons: {
+                getMappedDocumentId: unused,
+                ...overrides.queries?.singletons,
+            },
+        },
+    };
+}

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SingletonSavePrecondition, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -408,6 +408,8 @@ export interface CreateOptions {
     availableLocales?: string[];
 }
 export interface UpdateOptions {
+    /** Revision from the editable document observed before preparing this update. */
+    expectedRevision: number;
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
     locale?: string;
     /**
@@ -424,14 +426,13 @@ export interface UpdateOptions {
     availableLocales?: string[];
 }
 /** Write controls for `SingletonHandle.update()`. */
-export interface UpdateSingletonOptions {
-    /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
+export type UpdateSingletonOptions = SingletonSavePrecondition & {
+    /** Locale for field value resolution. Defaults to the client's defaultLocale. */
     locale?: string;
-    /** Reject the save when this is not the slot's current version id. */
-    expectedVersionId?: string;
-}
+};
 /** Optimistic, absolute-time input for `CollectionHandle.schedulePublish()`. */
 export interface SchedulePublishOptions {
+    expectedRevision: number;
     /** ISO instant carrying an explicit UTC offset or `Z`. */
     publishAt: string;
     /** The current version the editor reviewed and intends to publish. */
@@ -439,6 +440,7 @@ export interface SchedulePublishOptions {
 }
 /** Reviewed current version used to re-arm a suspended publication. */
 export interface ConfirmScheduledPublishOptions {
+    expectedRevision: number;
     expectedVersionId: string;
 }
 /**
@@ -459,6 +461,7 @@ export type DocumentPublishScheduleInfo = Omit<DocumentPublishSchedule, 'executi
  * may be null/omitted (append as last child, or prepend before a given sibling).
  */
 export interface PlaceTreeNodeOptions {
+    expectedRevision: number;
     /** The new parent; `null` makes the node a root. */
     parentDocumentId: string | null;
     /** Left neighbour — the node lands immediately after it. */
@@ -470,6 +473,7 @@ export interface PlaceTreeNodeOptions {
 }
 /** Options for an idempotent tree removal or post-commit hook retry. */
 export interface RemoveFromTreeOptions {
+    expectedRevision: number;
     /** Re-run `afterTreeChange` when the document is already unplaced. */
     reconcile?: boolean;
 }
@@ -706,3 +710,26 @@ export type WithPopulated<F, K extends keyof F, Target> = {
 export type WithPopulatedMany<F, K extends keyof F, Target> = {
     [P in keyof F]: P extends K ? Array<PopulatedRelation<Target>> : F[P];
 };
+/** Only explicit current editable reads carry mutation observations. */
+export interface EditableDocument<F = Record<string, any>> extends ClientDocument<F> {
+    revision: number;
+    scheduledPublication: DocumentPublishScheduleInfo | null;
+}
+export type EditableSingleton<F = Record<string, any>> = {
+    state: 'empty';
+} | {
+    state: 'document';
+    document: Omit<EditableDocument<F>, 'path'>;
+};
+export interface EditableFindResult<F = Record<string, any>> {
+    docs: EditableDocument<F>[];
+    meta: FindResult<F>['meta'];
+}
+export interface EditableTreeNode<F = Record<string, any>> {
+    document: EditableDocument<F>;
+    depth: number;
+    children: EditableTreeNode<F>[];
+}
+export type FindByIdForEditOptions<F = Record<string, any>> = Omit<FindByIdOptions<F>, 'status'>;
+export type FindForEditOptions<F = Record<string, any>> = Omit<FindOptions<F>, 'status'>;
+export type GetSubtreeForEditOptions<F = Record<string, any>> = Omit<GetSubtreeOptions<F>, 'status'>;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.19.0",
+  "version": "5.0.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,8 +44,8 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/auth": "4.19.0",
-    "@byline/core": "4.19.0"
+    "@byline/auth": "5.0.0",
+    "@byline/core": "5.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",
@@ -57,8 +57,8 @@
     "tsc-alias": "^1.9.2",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/db-postgres": "4.19.0",
-    "@byline/search-postgres": "4.19.0"
+    "@byline/search-postgres": "5.0.0",
+    "@byline/db-postgres": "5.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -73,6 +73,6 @@
     "test": "vitest run --mode=node",
     "test:watch": "vitest --mode=node",
     "test:integration": "vitest run --mode=integration",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json"
   }
 }