@abraca/dabra 2.4.0 → 2.5.0

package/dist/index.d.ts

@@ -289,6 +289,11 @@ declare class AbracadabraClient {
   private readonly _fetch;
   readonly cache: DocumentCache | null;
   private readonly _onAuthFailed;
+  /** Single-flight for root listings (`/docs?root=true`) — the per-row
+   * permission cascade makes this a multi-second / hundreds-of-KB call on
+   * a busy server, and a connect burst fires several identical ones.
+   * Keyed by the kind filter; cleared when the request settles. */
+  private readonly rootListInflight;
   constructor(config: AbracadabraClientConfig);
   get token(): string | null;
   set token(value: string | null);
@@ -576,7 +581,9 @@ declare class AbracadabraClient {
    * recursive tree walks; callers that need it can read `meta.id` from
    * the returned metas.
    */
-  listChildren(parentId?: string): Promise<DocumentMeta[]>;
+  listChildren(parentId?: string, opts?: {
+    kind?: string;
+  }): Promise<DocumentMeta[]>;
   /**
    * Create a child document under a parent (requires write permission).
    *
@@ -729,6 +736,64 @@ declare class AbracadabraClient {
     refCountsRepaired: number;
     blobsSwept: number;
   }>;
+  /**
+   * Admin one-shot: populate the `snapshot_files` table for snapshots
+   * created before that migration ran, so `SnapshotMeta.file_count` and
+   * upload-ref tracking become accurate. Idempotent (insert-or-ignore).
+   * Requires elevated role.
+   */
+  adminSnapshotsBackfillRefs(): Promise<{
+    snapshotsScanned: number;
+    refsWritten: number;
+  }>;
+  /**
+   * Admin one-shot: migrate pre-dedup inline snapshot data into the
+   * content-addressed `snapshot_blobs` store. Idempotent (only migrates
+   * rows with `data_hash IS NULL`). Requires elevated role.
+   */
+  adminSnapshotsBackfillBlobs(): Promise<{
+    snapshotsMigrated: number;
+    blobsAfter: number;
+    totalBytesAfter: number;
+  }>;
+  /**
+   * Admin: server-wide upload listing, joined with the owning document
+   * (label is best-effort — labels live in the CRDT, not the SQL row)
+   * and the content-addressed blob (`ref_count` exposes dedup).
+   * Server-side paginated + filtered. Requires elevated role.
+   */
+  adminListUploads(opts?: {
+    q?: string;
+    docId?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<{
+    uploads: Array<{
+      id: string;
+      doc_id: string;
+      doc_label: string | null;
+      filename: string;
+      mime_type: string | null;
+      size: number | null;
+      content_hash: string | null;
+      ref_count: number | null;
+      owner_id: string;
+      created_at: number;
+    }>;
+    total: number;
+  }>;
+  /**
+   * Admin: aggregate storage figures. `logicalBytes` is what users
+   * uploaded; `physicalBytes` is on-disk after content-addressed dedup;
+   * `dedupSaved` is the difference. Requires elevated role.
+   */
+  adminStorageStats(): Promise<{
+    uploadCount: number;
+    blobCount: number;
+    logicalBytes: number;
+    physicalBytes: number;
+    dedupSaved: number;
+  }>;
   /**
    * Clear the lockout state on a user account: zeroes the failed-login
    * counter and `locked_until`. Requires elevated role (Admin or
@@ -736,6 +801,26 @@ declare class AbracadabraClient {
    * `admin.user_unlock`.
    */
   adminUnlockUser(userId: string): Promise<void>;
+  /**
+   * Admin: every non-deleted document the user owns (`source: "owner"`)
+   * or has an explicit permission grant on (`source: "grant"`, with
+   * `role`). Answers "what does this identity touch" without an N+1
+   * client tree walk. Labels are best-effort (they live in the CRDT).
+   * Requires elevated role.
+   */
+  adminUserDocs(userId: string, opts?: {
+    limit?: number;
+  }): Promise<{
+    docs: Array<{
+      id: string;
+      label: string | null;
+      kind: string | null;
+      doc_type: string | null;
+      parent_id: string | null;
+      source: "owner" | "grant";
+      role: string | null;
+    }>;
+  }>;
   /**
    * Page through the audit log. Filters AND-combine; `limit` defaults to
    * 100 server-side. Requires elevated role.
@@ -799,6 +884,22 @@ declare class AbracadabraClient {
    * Secrets are redacted (`value: null`, `redacted: true`).
    */
   adminConfigEnvSnapshot(): Promise<EnvSnapshotResponse>;
+  /**
+   * List every route pattern that currently has at least one per-route
+   * config override. Use {@link adminConfigGetRoute} to read individual
+   * fields. Requires elevated role.
+   */
+  adminConfigListRoutes(): Promise<string[]>;
+  /**
+   * Read a field's effective value scoped to `route`, falling back to
+   * the global value when no per-route override exists. `origin_kind`
+   * is `"route_override"` only when an override is actually set.
+   */
+  adminConfigGetRoute(route: string, path: string): Promise<AdminConfigField>;
+  /** Set or replace a per-route override. Mirrors {@link adminConfigSet}. */
+  adminConfigSetRoute(route: string, path: string, value: unknown): Promise<AdminConfigField>;
+  /** Clear a per-route override (falls back to global). True if one existed. */
+  adminConfigUnsetRoute(route: string, path: string): Promise<boolean>;
   /** List snapshot metadata for a document. */
   listSnapshots(docId: string, opts?: {
     limit?: number;
@@ -4651,17 +4752,67 @@ declare class TypedDocTypeMismatchError extends Error {
 }
 //#endregion
 //#region packages/provider/src/TreeManager.d.ts
+interface ChildrenPage {
+  entries: TreeEntry[];
+  /** Pass back as `cursor` for the next page; `null` when exhausted. */
+  nextCursor: string | null;
+}
 declare class TreeManager {
   private dm;
   constructor(dm: DocumentManager);
+  private _idxMap;
+  private _idxObserver;
+  private _idxDirty;
+  private _byId;
+  private _childrenByParent;
+  /**
+   * Ensure the index is enabled, bound to the current root doc's tree
+   * map, and fresh. Returns `false` when the index is disabled or there
+   * is no tree map yet — callers then use the legacy scan path.
+   */
+  private ensureIndex;
+  private unbindIndex;
+  private rebuildIndex;
+  /**
+   * Release the deep observer. Optional — the observer is auto-rebound
+   * on space switch and becomes moot when the root Y.Doc is GC'd — but
+   * available for consumers that want deterministic teardown.
+   */
+  dispose(): void;
   /** Read all tree entries as plain objects. */
   readEntries(): TreeEntry[];
+  /**
+   * Like {@link readEntries} but with every entry's *stored* parentId
+   * run through {@link normalizeRootId} (parentId === rootDocId → null),
+   * so a cou-sh / orphan-rescue top-level doc (parentId === spaceRoot)
+   * resolves to top-level identically to a provider-created one
+   * (parentId: null). Without this, the raw `parentId === spaceRoot`
+   * form never matches the normalized `null` query and such docs are
+   * silently invisible cross-client. Mirrors the Rust provider's
+   * `normalized_entries`. readEntries/get keep raw values for
+   * round-trip consumers; only tree-walk reads use this.
+   */
+  private normalizedEntries;
   /** Get immediate children of a parent (sorted by order). */
   childrenOf(parentId: string | null): TreeEntry[];
+  /**
+   * Paginated immediate children — the Path-1 surface for large fan-out
+   * parents. Walks the same stable (order,id) sibling order as
+   * {@link childrenOf}; `cursor` is opaque (round-trip `nextCursor`).
+   * `limit` defaults to 100. A stale/garbage cursor restarts from the
+   * head rather than throwing. Cursor stability is exact when the index
+   * is enabled; on the legacy scan path siblings with equal `order`
+   * may shift between calls.
+   */
+  childrenOfPage(parentId: string | null, opts?: {
+    limit?: number;
+    cursor?: string | null;
+  }): ChildrenPage;
   /** Get all descendants recursively. */
   descendantsOf(parentId: string | null): TreeEntry[];
   /** Build nested tree JSON. */
   buildTree(rootId?: string | null, maxDepth?: number): TreeNode[];
+  private _buildTreeIndexed;
   private _buildTree;
   /**
    * Schema-typed lookup. Returns a `TypedTreeEntry<TMap, N>` when the
@@ -4933,6 +5084,16 @@ interface DocumentManagerConfig {
    * the entry-point docId is already known.
    */
   rootDocId?: string;
+  /**
+   * PROTOTYPE (Path-1 doctree scaling): opt into TreeManager's in-memory
+   * parent→children index. When `false` (default), every tree walk
+   * re-scans the whole `doc-tree` Y.Map (O(n) per call, O(n²) recursive
+   * traversal) — the historical behaviour, byte-for-byte. When `true`,
+   * walks resolve against a lazily-rebuilt adjacency index (O(k) per
+   * lookup, O(result) traversal) and `tree.childrenOfPage()` becomes
+   * usable. Behind a flag so it ships dark until benchmarked.
+   */
+  treeIndex?: boolean;
 }
 declare class DocumentManager {
   readonly client: AbracadabraClient;
@@ -4968,6 +5129,11 @@ declare class DocumentManager {
   get displayColor(): string;
   get serverInfo(): ServerInfo | null;
   get rootDocId(): string | null;
+  /**
+   * Whether the TreeManager in-memory index is enabled (Path-1 prototype).
+   * Off by default — see {@link DocumentManagerConfig.treeIndex}.
+   */
+  get treeIndexEnabled(): boolean;
   get rootDocument(): Y.Doc | null;
   get rootProvider(): AbracadabraProvider | null;
   /**
@@ -5030,5 +5196,29 @@ declare function normalizeRootId(id: string | null | undefined, rootDocId: strin
  * Safely read a tree map value, converting Y.Map to plain object if needed.
  */
 declare function toPlain(val: unknown): unknown;
+/**
+ * Build a tree/trash entry as a nested `Y.Map`. Use for a brand-new or
+ * re-created key (create / duplicate / restore) where no concurrent
+ * writer exists, so a whole-value write is safe. `undefined` fields are
+ * omitted; `null` is kept (a real value, e.g. top-level `parentId`).
+ */
+declare function makeEntryMap(fields: Record<string, unknown>): Y.Map<unknown>;
+/**
+ * Patch an EXISTING entry's fields per-key on its nested `Y.Map`, so a
+ * concurrent edit to a *different* field by a peer is preserved instead
+ * of being clobbered by a whole-entry write — the whole-entry-LWW fix
+ * (audit ⑦), the mirror of the Rust provider's `with_entry_mut`.
+ *
+ * - nested `Y.Map` entry → set/delete only the touched keys in place;
+ * - legacy opaque (plain-object) entry → migrated once to a `Y.Map`;
+ * - missing entry → created from the patch (lenient; matches the prior
+ *   call-site behaviour of spreading `undefined`).
+ *
+ * A patch value of `undefined` deletes the key; `null` is written.
+ * Self-transacting: it batches its writes in one `Y.Doc` transaction
+ * (a safe reentrant no-op join when already inside one), so callers
+ * don't need to pass or own a transaction.
+ */
+declare function patchEntry(treeMap: Y.Map<unknown>, id: string, patch: Record<string, unknown>, removeKeys?: string[]): void;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, type ChildrenPage, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.4.0"
+    "@abraca/schema": "2.5.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/AbracadabraClient.ts

@@ -95,6 +95,14 @@ export class AbracadabraClient {
 	private readonly _fetch: typeof globalThis.fetch;
 	readonly cache: DocumentCache | null;
 	private readonly _onAuthFailed: ((ctx: AuthFailureContext) => void) | null;
+	/** Single-flight for root listings (`/docs?root=true`) — the per-row
+	 * permission cascade makes this a multi-second / hundreds-of-KB call on
+	 * a busy server, and a connect burst fires several identical ones.
+	 * Keyed by the kind filter; cleared when the request settles. */
+	private readonly rootListInflight = new Map<
+		string,
+		Promise<DocumentMeta[]>
+	>();
 
 	constructor(config: AbracadabraClientConfig) {
 		this.baseUrl = config.url.replace(/\/+$/, "");
@@ -644,18 +652,50 @@ export class AbracadabraClient {
 	 * recursive tree walks; callers that need it can read `meta.id` from
 	 * the returned metas.
 	 */
-	async listChildren(parentId?: string): Promise<DocumentMeta[]> {
-		const path = parentId
-			? `/docs/${encodeURIComponent(parentId)}/children`
-			: "/docs?root=true";
-		const res = await this.request<{ documents: DocumentMeta[]; children?: string[] }>(
-			"GET",
-			path,
-		);
-		if (this.cache && parentId && res.children) {
-			await this.cache.setChildren(parentId, res.children).catch(() => null);
+	async listChildren(
+		parentId?: string,
+		opts?: { kind?: string },
+	): Promise<DocumentMeta[]> {
+		const kind = opts?.kind;
+		if (parentId) {
+			const res = await this.request<{
+				documents: DocumentMeta[];
+				children?: string[];
+			}>("GET", `/docs/${encodeURIComponent(parentId)}/children`);
+			if (this.cache && res.children) {
+				await this.cache.setChildren(parentId, res.children).catch(() => null);
+			}
+			return kind
+				? res.documents.filter((d) => d.kind === kind)
+				: res.documents;
 		}
-		return res.documents;
+		// Root listing. The server runs the per-row permission cascade for
+		// every top-level doc, so this is the expensive call. Send the
+		// optional server-side `kind` filter — a fixed server skips the
+		// cascade for non-matching docs; an old server ignores the unknown
+		// param and we still filter client-side below, so the result is
+		// identical either way. Concurrent identical root listings (a
+		// connect fans out several) share one in-flight request.
+		const key = kind ?? "";
+		const existing = this.rootListInflight.get(key);
+		const docs = existing
+			? await existing
+			: await (() => {
+					const p = this.request<{
+						documents: DocumentMeta[];
+						children?: string[];
+					}>(
+						"GET",
+						kind
+							? `/docs?root=true&kind=${encodeURIComponent(kind)}`
+							: "/docs?root=true",
+					)
+						.then((res) => res.documents)
+						.finally(() => this.rootListInflight.delete(key));
+					this.rootListInflight.set(key, p);
+					return p;
+				})();
+		return kind ? docs.filter((d) => d.kind === kind) : docs;
 	}
 
 	/**
@@ -889,8 +929,7 @@ export class AbracadabraClient {
 	 * spaces resolving to any role; anonymous users see public ones.
 	 */
 	async listSpaces(): Promise<DocumentMeta[]> {
-		const docs = await this.listChildren();
-		return docs.filter((d) => d.kind === Kind.Space);
+		return this.listChildren(undefined, { kind: Kind.Space });
 	}
 
 	/**
@@ -1044,6 +1083,79 @@ export class AbracadabraClient {
 		return this.request("POST", "/admin/storage/repair");
 	}
 
+	/**
+	 * Admin one-shot: populate the `snapshot_files` table for snapshots
+	 * created before that migration ran, so `SnapshotMeta.file_count` and
+	 * upload-ref tracking become accurate. Idempotent (insert-or-ignore).
+	 * Requires elevated role.
+	 */
+	async adminSnapshotsBackfillRefs(): Promise<{
+		snapshotsScanned: number;
+		refsWritten: number;
+	}> {
+		return this.request("POST", "/admin/snapshots/backfill-refs");
+	}
+
+	/**
+	 * Admin one-shot: migrate pre-dedup inline snapshot data into the
+	 * content-addressed `snapshot_blobs` store. Idempotent (only migrates
+	 * rows with `data_hash IS NULL`). Requires elevated role.
+	 */
+	async adminSnapshotsBackfillBlobs(): Promise<{
+		snapshotsMigrated: number;
+		blobsAfter: number;
+		totalBytesAfter: number;
+	}> {
+		return this.request("POST", "/admin/snapshots/backfill-blobs");
+	}
+
+	/**
+	 * Admin: server-wide upload listing, joined with the owning document
+	 * (label is best-effort — labels live in the CRDT, not the SQL row)
+	 * and the content-addressed blob (`ref_count` exposes dedup).
+	 * Server-side paginated + filtered. Requires elevated role.
+	 */
+	async adminListUploads(
+		opts: { q?: string; docId?: string; limit?: number; offset?: number } = {},
+	): Promise<{
+		uploads: Array<{
+			id: string;
+			doc_id: string;
+			doc_label: string | null;
+			filename: string;
+			mime_type: string | null;
+			size: number | null;
+			content_hash: string | null;
+			ref_count: number | null;
+			owner_id: string;
+			created_at: number;
+		}>;
+		total: number;
+	}> {
+		const p = new URLSearchParams();
+		if (opts.q) p.set("q", opts.q);
+		if (opts.docId) p.set("doc_id", opts.docId);
+		if (opts.limit != null) p.set("limit", String(opts.limit));
+		if (opts.offset != null) p.set("offset", String(opts.offset));
+		const qs = p.toString();
+		return this.request("GET", `/admin/uploads${qs ? `?${qs}` : ""}`);
+	}
+
+	/**
+	 * Admin: aggregate storage figures. `logicalBytes` is what users
+	 * uploaded; `physicalBytes` is on-disk after content-addressed dedup;
+	 * `dedupSaved` is the difference. Requires elevated role.
+	 */
+	async adminStorageStats(): Promise<{
+		uploadCount: number;
+		blobCount: number;
+		logicalBytes: number;
+		physicalBytes: number;
+		dedupSaved: number;
+	}> {
+		return this.request("GET", "/admin/storage/stats");
+	}
+
 	/**
 	 * Clear the lockout state on a user account: zeroes the failed-login
 	 * counter and `locked_until`. Requires elevated role (Admin or
@@ -1054,6 +1166,34 @@ export class AbracadabraClient {
 		await this.request("POST", `/admin/users/${encodeURIComponent(userId)}/unlock`);
 	}
 
+	/**
+	 * Admin: every non-deleted document the user owns (`source: "owner"`)
+	 * or has an explicit permission grant on (`source: "grant"`, with
+	 * `role`). Answers "what does this identity touch" without an N+1
+	 * client tree walk. Labels are best-effort (they live in the CRDT).
+	 * Requires elevated role.
+	 */
+	async adminUserDocs(
+		userId: string,
+		opts: { limit?: number } = {},
+	): Promise<{
+		docs: Array<{
+			id: string;
+			label: string | null;
+			kind: string | null;
+			doc_type: string | null;
+			parent_id: string | null;
+			source: "owner" | "grant";
+			role: string | null;
+		}>;
+	}> {
+		const qs = opts.limit != null ? `?limit=${opts.limit}` : "";
+		return this.request(
+			"GET",
+			`/admin/users/${encodeURIComponent(userId)}/docs${qs}`,
+		);
+	}
+
 	/**
 	 * Page through the audit log. Filters AND-combine; `limit` defaults to
 	 * 100 server-side. Requires elevated role.
@@ -1203,6 +1343,48 @@ export class AbracadabraClient {
 		return this.request<EnvSnapshotResponse>("GET", "/admin/config/env-snapshot");
 	}
 
+	/**
+	 * List every route pattern that currently has at least one per-route
+	 * config override. Use {@link adminConfigGetRoute} to read individual
+	 * fields. Requires elevated role.
+	 */
+	async adminConfigListRoutes(): Promise<string[]> {
+		const res = await this.request<{ routes: string[] }>(
+			"GET", "/admin/config/routes",
+		);
+		return res.routes;
+	}
+
+	/**
+	 * Read a field's effective value scoped to `route`, falling back to
+	 * the global value when no per-route override exists. `origin_kind`
+	 * is `"route_override"` only when an override is actually set.
+	 */
+	async adminConfigGetRoute(route: string, path: string): Promise<AdminConfigField> {
+		return this.request<AdminConfigField>(
+			"GET",
+			`/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`,
+		);
+	}
+
+	/** Set or replace a per-route override. Mirrors {@link adminConfigSet}. */
+	async adminConfigSetRoute(route: string, path: string, value: unknown): Promise<AdminConfigField> {
+		return this.request<AdminConfigField>(
+			"PUT",
+			`/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`,
+			{ body: { value } },
+		);
+	}
+
+	/** Clear a per-route override (falls back to global). True if one existed. */
+	async adminConfigUnsetRoute(route: string, path: string): Promise<boolean> {
+		const res = await this.request<{ existed: boolean }>(
+			"DELETE",
+			`/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`,
+		);
+		return res.existed;
+	}
+
 	// ── Snapshots ────────────────────────────────────────────────────────────
 
 	/** List snapshot metadata for a document. */

package/src/AbracadabraProvider.ts

@@ -712,30 +712,39 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	 * errors across async await boundaries.
 	 */
 	private async flushPendingUpdates() {
-		if (!this.canWrite) return;
 		const store = this.offlineStore;
 		if (!store) return;
 
-		const updates = await store.getPendingUpdates();
-		if (updates.length > 0) {
-			for (const update of updates) {
-				this.send(UpdateMessage, {
-					update,
-					documentName: this.configuration.name,
-				});
+		// Flushing queued *local* writes / subdoc registrations over the wire
+		// is only meaningful for writers — a read-only session has none and
+		// must not send. The snapshot save below is deliberately OUTSIDE this
+		// guard.
+		if (this.canWrite) {
+			const updates = await store.getPendingUpdates();
+			if (updates.length > 0) {
+				for (const update of updates) {
+					this.send(UpdateMessage, {
+						update,
+						documentName: this.configuration.name,
+					});
+				}
+				await store.clearPendingUpdates();
 			}
-			await store.clearPendingUpdates();
-		}
 
-		const pendingSubdocs = await store.getPendingSubdocs();
-		for (const { childId } of pendingSubdocs) {
-			this.send(SubdocMessage, {
-				documentName: this.configuration.name,
-				childDocumentName: childId,
-			} as any);
+			const pendingSubdocs = await store.getPendingSubdocs();
+			for (const { childId } of pendingSubdocs) {
+				this.send(SubdocMessage, {
+					documentName: this.configuration.name,
+					childDocumentName: childId,
+				} as any);
+			}
 		}
 
 		// Snapshot the current merged state so the next offline load sees it.
+		// This is the ONLY path that persists server-delivered content
+		// (documentUpdateHandler skips origin===this), so it MUST run for
+		// read-only roles too — otherwise observers/viewers get a permanently
+		// empty offline cache and every cold start waits for a full re-sync.
 		const snapshot = Y.encodeStateAsUpdate(this.document);
 		await store.saveDocSnapshot(snapshot).catch(() => null);
 	}

package/src/ContentManager.ts

@@ -5,7 +5,7 @@
  */
 import * as Y from "yjs";
 import type { PageMeta } from "./DocTypes.ts";
-import { toPlain } from "./DocUtils.ts";
+import { toPlain, patchEntry } from "./DocUtils.ts";
 import {
 	yjsToMarkdown,
 	populateYDocFromMarkdown,
@@ -51,11 +51,9 @@ export class ContentManager {
 		const provider = await this.dm.getChildProvider(docId);
 		const fragment = provider.document.getXmlFragment("default");
 
-		const { title, markdown } = yjsToMarkdown(fragment);
-
 		// Get tree metadata + immediate children
 		const treeMap = this.dm.getTreeMap();
-		let label = title;
+		let label = "Untitled";
 		let type: string | undefined;
 		let meta: PageMeta | undefined;
 		const childrenWithOrder: Array<{
@@ -70,7 +68,7 @@ export class ContentManager {
 			const raw = treeMap.get(docId);
 			if (raw) {
 				const entry = toPlain(raw) as Record<string, unknown>;
-				label = (entry.label as string) || title;
+				label = (entry.label as string) || label;
 				type = entry.type as string | undefined;
 				meta = entry.meta as PageMeta | undefined;
 			}
@@ -97,6 +95,12 @@ export class ContentManager {
 			meta,
 		}));
 
+		// yjsToMarkdown returns a string and takes the resolved label/meta/type
+		// so frontmatter round-trips. (Older code destructured an object and
+		// passed only the fragment — that silently produced `undefined`.)
+		const markdown = yjsToMarkdown(fragment, label, meta, type);
+		const title = label;
+
 		return { label, type, meta, title, markdown, children };
 	}
 
@@ -127,18 +131,22 @@ export class ContentManager {
 				const entry = treeMap.get(docId);
 				if (entry) {
 					rootDoc.transact(() => {
-						const updates: Record<string, unknown> = {
-							...entry,
+						const cur = toPlain(entry) as Record<
+							string,
+							unknown
+						>;
+						const patch: Record<string, unknown> = {
 							updatedAt: Date.now(),
 						};
-						if (title) updates.label = title;
+						if (title) patch.label = title;
 						if (Object.keys(meta).length > 0) {
-							updates.meta = {
-								...(entry.meta ?? {}),
+							patch.meta = {
+								...((cur.meta as Record<string, unknown>) ??
+									{}),
 								...meta,
 							};
 						}
-						treeMap.set(docId, updates);
+						patchEntry(treeMap, docId, patch);
 					});
 				}
 			}