@abraca/dabra 2.4.0 → 2.6.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,82 @@ 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;
+    }>;
+  }>;
+  /**
+   * List `service`-role users (runners, demo seeders, automation
+   * identities). Requires Service role. Admins can see service users via
+   * `/admin/users` too but cannot mint or rotate them.
+   */
+  adminListServiceAccounts(): Promise<{
+    items: Array<{
+      id: string;
+      username: string;
+      public_key: string | null;
+      revoked: boolean;
+      display_name: string | null;
+    }>;
+  }>;
+  /**
+   * Create a new `service`-role user. When `public_key` is omitted the
+   * server generates a keypair and returns the private half in the
+   * response — show it to the operator **once** and discard; the server
+   * never persists it. Requires Service role.
+   */
+  adminCreateServiceAccount(body: {
+    username: string;
+    public_key?: string;
+  }): Promise<{
+    id: string;
+    username: string;
+    public_key: string;
+    role: string;
+    private_key?: string;
+  }>;
+  /**
+   * Rotate the active keypair on a service account. Old JWTs are
+   * invalidated; old device keys are marked revoked; the canonical
+   * `users.public_key` swaps to the new value. `users.id` stays put so
+   * existing permission rows keep matching. Returns the new pubkey (and
+   * private half when the server generated it). Requires Service role.
+   */
+  adminRotateServiceAccountKey(userId: string, body?: {
+    public_key?: string;
+  }): Promise<{
+    id: string;
+    public_key: string;
+    private_key?: string;
+  }>;
+  /**
+   * Lock a service account and revoke all of its device keys. Idempotent.
+   * Refuses targets whose `users.role` isn't `"service"`. Requires
+   * Service role.
+   */
+  adminRevokeServiceAccount(userId: string): Promise<void>;
+  /**
+   * Revoke a single device key on a user (any role). Bumps
+   * `tokens_invalid_before` so open WS sessions tied to the key must
+   * re-auth. Requires elevated role (Service or Admin@root).
+   */
+  adminRevokeDeviceKey(userId: string, keyId: string): Promise<void>;
   /**
    * Page through the audit log. Filters AND-combine; `limit` defaults to
    * 100 server-side. Requires elevated role.
@@ -799,6 +940,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 +4808,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 +5140,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 +5185,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 +5252,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.6.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.4.0"
+    "@abraca/schema": "2.6.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,112 @@ 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}`,
+		);
+	}
+
+	/**
+	 * List `service`-role users (runners, demo seeders, automation
+	 * identities). Requires Service role. Admins can see service users via
+	 * `/admin/users` too but cannot mint or rotate them.
+	 */
+	async adminListServiceAccounts(): Promise<{
+		items: Array<{
+			id: string;
+			username: string;
+			public_key: string | null;
+			revoked: boolean;
+			display_name: string | null;
+		}>;
+	}> {
+		return this.request("GET", "/admin/service-accounts");
+	}
+
+	/**
+	 * Create a new `service`-role user. When `public_key` is omitted the
+	 * server generates a keypair and returns the private half in the
+	 * response — show it to the operator **once** and discard; the server
+	 * never persists it. Requires Service role.
+	 */
+	async adminCreateServiceAccount(body: {
+		username: string;
+		public_key?: string;
+	}): Promise<{
+		id: string;
+		username: string;
+		public_key: string;
+		role: string;
+		private_key?: string;
+	}> {
+		return this.request("POST", "/admin/service-accounts", { body });
+	}
+
+	/**
+	 * Rotate the active keypair on a service account. Old JWTs are
+	 * invalidated; old device keys are marked revoked; the canonical
+	 * `users.public_key` swaps to the new value. `users.id` stays put so
+	 * existing permission rows keep matching. Returns the new pubkey (and
+	 * private half when the server generated it). Requires Service role.
+	 */
+	async adminRotateServiceAccountKey(
+		userId: string,
+		body: { public_key?: string } = {},
+	): Promise<{ id: string; public_key: string; private_key?: string }> {
+		return this.request(
+			"POST",
+			`/admin/service-accounts/${encodeURIComponent(userId)}/rotate-key`,
+			{ body },
+		);
+	}
+
+	/**
+	 * Lock a service account and revoke all of its device keys. Idempotent.
+	 * Refuses targets whose `users.role` isn't `"service"`. Requires
+	 * Service role.
+	 */
+	async adminRevokeServiceAccount(userId: string): Promise<void> {
+		await this.request(
+			"DELETE",
+			`/admin/service-accounts/${encodeURIComponent(userId)}`,
+		);
+	}
+
+	/**
+	 * Revoke a single device key on a user (any role). Bumps
+	 * `tokens_invalid_before` so open WS sessions tied to the key must
+	 * re-auth. Requires elevated role (Service or Admin@root).
+	 */
+	async adminRevokeDeviceKey(userId: string, keyId: string): Promise<void> {
+		await this.request(
+			"POST",
+			`/admin/users/${encodeURIComponent(userId)}/device-keys/${encodeURIComponent(keyId)}/revoke`,
+		);
+	}
+
 	/**
 	 * Page through the audit log. Filters AND-combine; `limit` defaults to
 	 * 100 server-side. Requires elevated role.
@@ -1203,6 +1421,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. */