@byline/client 4.19.0 → 5.1.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/admin-context.d.ts

@@ -6,45 +6,13 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Request-scoped auth context for admin server functions.
+ * Verification-only request context. Renewal belongs to the explicit host endpoint.
  *
- * Reads the session cookies, verifies the access token, transparently
- * refreshes when needed, and returns a `RequestContext` carrying the
- * authenticated `AdminAuth`. Every admin server fn calls this as its
- * first step — it is the single point where the admin transport boundary
- * meets the actor/ability machinery.
- *
- * Flow, in order:
- *
- *   1. Read the access cookie.
- *   2. If present, try `sessionProvider.verifyAccessToken`. On success,
- *      return the context — no DB write, no cookie churn.
- *   3. On verify failure (or missing access cookie), read the refresh
- *      cookie. If present, call `sessionProvider.refreshSession` — this
- *      rotates the refresh token atomically and issues a new access
- *      token. Write both fresh cookies to the response.
- *   4. Verify the new access token (populate the actor) and return the
- *      context.
- *   5. Any failure along the way clears both cookies so the browser
- *      stops sending a session the server has already rejected, and
- *      throws `ERR_UNAUTHENTICATED`.
- *
- * Burns a refresh-token rotation only when the access token actually
- * fails verification — not on every request. The "one session" UX is
- * the consequence of this helper working invisibly behind each call.
- *
- * Resolution is memoized per request (`oncePerRequest`): every call within
- * one logical request returns the same `RequestContext` instance — same
- * actor snapshot, same `requestId`. Two invariants depend on this:
- *
- *   - The read-authorization layer binds each `ReadContext` to one
- *     immutable authority token that includes `requestId`; a fresh id per
- *     call makes any two reads sharing a `ReadContext` (the admin tree
- *     view, hook-threaded nested reads) throw
- *     'ReadContext cannot be reused across request authorities'.
- *   - The refresh path rotates the refresh token; a second unmemoized call
- *     in the same request would re-run the dance against the
- *     already-rotated cookie and sign the admin out.
+ * oncePerRequest preserves the same context, actor snapshot, and requestId for
+ * every call in one logical request. The read-authorization layer binds each
+ * ReadContext to one authority token including requestId. Generating a new id
+ * per call would make nested reads sharing a ReadContext throw:
+ * "ReadContext cannot be reused across request authorities".
  */
 import { type RequestContext } from '@byline/auth';
 export declare function getAdminRequestContext(): Promise<RequestContext>;