@abraca/dabra 2.0.10 → 2.4.0

package/dist/index.d.ts

@@ -548,6 +548,25 @@ declare class AbracadabraClient {
   searchDocs(query: string, opts?: {
     limit?: number;
   }): Promise<DocSearchHit[]>;
+  /**
+   * Query for documents matching a structural predicate. v1 of the
+   * indexed-query layer described in
+   * `ARCHITECTURE/20-kickoff-phase3-queries.md`.
+   *
+   * The wire shape accepts a `where` field so v2 (meta-predicate
+   * filtering on top of the `doc_meta_index` projection) can light up
+   * without a compatibility break. Sending a non-empty `where` today
+   * returns a 400 — callers should leave it absent.
+   *
+   * Returns docs the requester can read at viewer-or-above, filtered
+   * through the cascading permission resolver server-side.
+   */
+  queryDocs(opts: {
+    type?: string;
+    parentId?: string;
+    labelContains?: string;
+    limit?: number;
+  }): Promise<DocumentMeta[]>;
   /**
    * List the direct children of a document, returning full metadata. Pass
    * no argument to list the children of the server root — what the
@@ -2254,6 +2273,113 @@ declare class RpcClient extends EventEmitter {
   private onCancel;
 }
 //#endregion
+//#region packages/provider/src/QueryClient.d.ts
+/**
+ * V2 query layer — live subscription client.
+ *
+ * Mirrors the server in `crates/abracadabra/src/query_stream.rs`. Frames
+ * travel as `MSG_STATELESS` payloads with the literal `query:v1:` prefix
+ * followed by a JSON envelope.
+ *
+ * Each call to `subscribeQuery(...)` opens a long-lived subscription:
+ *   1. The client sends `req` with a fresh correlation id.
+ *   2. The server replies `ack` with an initial snapshot
+ *      (`DocumentMeta[]`).
+ *   3. The server emits `delta` frames as the doc-tree projection
+ *      drifts under the predicate.
+ *   4. The client sends `cancel` to tear it down (or relies on the
+ *      WebSocket close path to free server state).
+ *
+ * The shape of the `query` field mirrors the REST `POST /docs/query`
+ * body — `type`, `parentId`, `labelContains`, `where`, `limit`.
+ */
+declare const QUERY_PREFIX = "query:v1:";
+type QueryKind = "req" | "ack" | "delta" | "cancel" | "err";
+/** Mirrors `crate::query_stream::QuerySpec`. */
+interface QuerySpec {
+  /** Match `documents.kind` exactly. */
+  type?: string;
+  /** Narrow to children of this doc. */
+  parentId?: string;
+  /** Case-insensitive substring on `documents.label`. */
+  labelContains?: string;
+  /** Maximum rows returned (default 50, hard cap 500 server-side). */
+  limit?: number;
+  /** Predicate AST. See `@abraca/schema/src/query.ts` for the shape. */
+  where?: unknown;
+}
+interface DocumentMetaWire {
+  id: string;
+  parent_id?: string | null;
+  label?: string | null;
+  kind?: string | null;
+  doc_type?: string | null;
+  public_access?: string | null;
+  description?: string | null;
+  owner_id?: string | null;
+}
+interface QueryFrame {
+  kind: QueryKind;
+  id: string;
+  query?: QuerySpec;
+  initial?: DocumentMetaWire[];
+  added?: DocumentMetaWire[];
+  updated?: DocumentMetaWire[];
+  removed?: string[];
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+declare class QueryError extends Error {
+  code: string;
+  constructor(code: string, message: string);
+}
+interface QuerySubscriptionHandlers {
+  /** Fired once with the initial snapshot from the server's `ack`. */
+  onSnapshot?: (rows: DocumentMetaWire[]) => void;
+  /**
+   * Fired on every `delta` after the initial ack. `added` are rows
+   * newly matching the predicate; `removed` are doc_ids that no
+   * longer match (or are no longer readable). v2 does not emit
+   * `updated` — clients see updates as remove + add today; that
+   * gap closes in v3 when row-level updates are tracked.
+   */
+  onDelta?: (delta: {
+    added: DocumentMetaWire[];
+    removed: string[];
+  }) => void;
+  /** Fired on `err` frames from the server. */
+  onError?: (err: QueryError) => void;
+}
+interface QuerySubscriptionHandle {
+  /** Correlation id assigned when the request was sent. */
+  readonly id: string;
+  /** Send a `cancel` to the server and stop dispatching to handlers. */
+  cancel(): void;
+}
+/**
+ * Minimal transport surface — matches `RpcTransport` so the provider
+ * can satisfy both without extra glue.
+ */
+interface QueryTransport {
+  sendStateless(payload: string): void;
+  on(event: string, fn: Function): unknown;
+  off(event: string, fn?: Function): unknown;
+}
+declare class QueryClient extends EventEmitter {
+  private readonly transport;
+  private readonly subs;
+  private readonly onStatelessBound;
+  private idCounter;
+  constructor(transport: QueryTransport);
+  destroy(): void;
+  subscribeQuery(spec: QuerySpec, handlers?: QuerySubscriptionHandlers): QuerySubscriptionHandle;
+  private nextId;
+  private send;
+  private receive;
+}
+//#endregion
 //#region packages/provider/src/AbracadabraBaseProvider.d.ts
 type AbracadabraBaseProviderConfiguration = Required<Pick<CompleteAbracadabraBaseProviderConfiguration, "name">> & Partial<CompleteAbracadabraBaseProviderConfiguration> & ((Required<Pick<CompleteAbracadabraWSConfiguration, "url">> & Partial<Pick<CompleteAbracadabraWSConfiguration, "preserveTrailingSlash">>) | Required<Pick<CompleteAbracadabraBaseProviderConfiguration, "websocketProvider">>);
 /** @deprecated Use AbracadabraBaseProviderConfiguration */
@@ -2340,6 +2466,20 @@ declare class AbracadabraBaseProvider extends EventEmitter {
    */
   private _rpc;
   get rpc(): RpcClient;
+  /**
+   * Lazily-constructed V2 query subscription client. See
+   * `QueryClient`. Each call to `subscribeQuery(...)` opens a
+   * long-lived subscription that fires `onSnapshot` with the initial
+   * result set and `onDelta` whenever the projection moves.
+   */
+  private _queryClient;
+  private getQueryClient;
+  /**
+   * Open a live query subscription. Mirrors the v1 REST shape
+   * (`POST /docs/query`) but pushes deltas as the server-side
+   * projection drifts under the predicate.
+   */
+  subscribeQuery(spec: QuerySpec, handlers?: QuerySubscriptionHandlers): QuerySubscriptionHandle;
   constructor(configuration: AbracadabraBaseProviderConfiguration);
   boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;
   boundAwarenessUpdateHandler: ({
@@ -2404,6 +2544,127 @@ declare const HocuspocusProvider: typeof AbracadabraBaseProvider;
 /** @deprecated Use AbracadabraBaseProvider */
 type HocuspocusProvider = AbracadabraBaseProvider;
 //#endregion
+//#region packages/provider/src/TokenManager.d.ts
+/**
+ * On-disk shape of a device session. The server returns these values from
+ * `POST /auth/device-session`; persistence keeps them across reloads so a
+ * warm boot can mint a fresh JWT without re-prompting for the passkey.
+ */
+interface DeviceSessionRecord {
+  sessionId: string;
+  sessionToken: string;
+  /** Unix seconds — matches what the server returns. */
+  expiresAt: number;
+}
+interface DeviceSessionStorage {
+  load(): DeviceSessionRecord | null;
+  save(record: DeviceSessionRecord): void;
+  clear(): void;
+}
+/** localStorage-backed storage; safe in SSR/Node (no-ops without localStorage). */
+declare class LocalStorageDeviceSessionStorage implements DeviceSessionStorage {
+  private readonly key;
+  constructor(key?: string);
+  load(): DeviceSessionRecord | null;
+  save(record: DeviceSessionRecord): void;
+  clear(): void;
+}
+interface TokenManagerOptions {
+  client: AbracadabraClient;
+  /**
+   * Where the device session record lives. Defaults to a localStorage
+   * adapter under "abracadabra:device-session".
+   */
+  storage?: DeviceSessionStorage;
+  /**
+   * Refresh the JWT this many milliseconds before its `exp`. Defaults to
+   * 5 minutes — well clear of clock skew without burning a refresh per
+   * minute. Refreshes are also dedup'd via in-flight promise.
+   */
+  refreshLeadMs?: number;
+  /**
+   * Hook `document.visibilitychange` and `window.online` to opportunistically
+   * refresh when the tab/network resumes. Default true. The proactive
+   * `setTimeout` doesn't fire reliably while the tab is hidden or the
+   * laptop is asleep, which is the actual breakage path being addressed —
+   * the resume hook is what makes the system self-heal after a long sleep.
+   */
+  installResumeHandlers?: boolean;
+}
+/**
+ * Manages the lifetime of the short-lived JWT against a long-lived device
+ * session token.
+ *
+ * Flow:
+ *  - Bootstrap: if a stored device session exists, exchange it for a fresh
+ *    JWT immediately (`bootstrap()`). Otherwise the consumer must run a
+ *    full crypto-auth handshake and then call `attachSession(record)` once
+ *    the server returns a device-session token.
+ *  - Steady state: `getValidToken()` returns the JWT, refreshing if the
+ *    JWT is within `refreshLeadMs` of expiry. Concurrent callers share one
+ *    in-flight refresh.
+ *  - Background: a proactive timer fires `refreshLeadMs` before `exp`.
+ *    `visibilitychange` and `online` events trigger an opportunistic
+ *    refresh in case the timer was suppressed (hidden tab, sleeping
+ *    laptop). The combination is what restores the WS without a reload.
+ *  - Failure: refresh errors with status 401/403 mean the device session
+ *    itself is dead (revoked or 30 d expired). The record is cleared and
+ *    `session-expired` fires so the consumer can prompt re-auth. Other
+ *    errors (network) are transparent — the existing JWT is returned and
+ *    the caller's normal retry loop covers it.
+ */
+declare class TokenManager extends EventEmitter {
+  private readonly client;
+  private readonly storage;
+  private readonly refreshLeadMs;
+  private session;
+  private refreshing;
+  private proactiveTimer;
+  private resumeHandlersInstalled;
+  private boundOnResume;
+  private disposed;
+  constructor(options: TokenManagerOptions);
+  get hasSession(): boolean;
+  get currentSession(): DeviceSessionRecord | null;
+  /**
+   * Persist a freshly-issued device session and exchange it immediately
+   * for a JWT. Call this once after a successful crypto-auth login when
+   * the server returns a device-session token.
+   */
+  attachSession(record: DeviceSessionRecord): Promise<string>;
+  /**
+   * Drop the local device session (no server call). Use after a logout
+   * or when `session-expired` fires. To revoke server-side as well, call
+   * `client.revokeDeviceSession(sessionId)` first.
+   */
+  clearSession(): void;
+  /**
+   * Return a valid JWT, refreshing if it is missing or within
+   * `refreshLeadMs` of expiry. Safe to call concurrently — one
+   * refresh is in flight at a time.
+   *
+   * Transient refresh errors (network) fall back to the cached JWT so
+   * the WS auth attempt can still proceed; the server will reject and
+   * the next reconnect tries again. Only 401/403 from the refresh
+   * endpoint surfaces as a thrown error here, since those mean the
+   * device session itself is dead.
+   */
+  getValidToken(): Promise<string>;
+  /**
+   * If a stored device session exists, exchange it for a fresh JWT now.
+   * Returns the JWT (or null if there is no session to bootstrap from).
+   * Throws on 401/403 — the stored session is invalid and the caller
+   * should fall through to a full crypto-auth flow.
+   */
+  bootstrap(): Promise<string | null>;
+  dispose(): void;
+  private runRefresh;
+  private tokenIsFresh;
+  private parseExp;
+  private scheduleProactiveRefresh;
+  private installResumeHandlers;
+}
+//#endregion
 //#region packages/provider/src/auth.d.ts
 declare enum AuthMessageType {
   Token = 0,
@@ -2758,6 +3019,8 @@ declare class BackgroundSyncManager extends EventEmitter {
   private readonly persistence;
   private readonly semaphore;
   private readonly syncStates;
+  /** Doc ids we've already warned about; keeps the log to one line per id. */
+  private readonly _warnedInvalidIds;
   private _destroyed;
   private _initPromise;
   constructor(rootProvider: AbracadabraProvider, client: AbracadabraClient, fileBlobStore?: FileBlobStore | null, opts?: BackgroundSyncManagerOptions);
@@ -4295,6 +4558,98 @@ declare const PAGE_TYPES: Record<string, PageTypeInfo>;
 declare const TYPE_ALIASES: Record<string, string>;
 declare function resolvePageType(key: string | undefined): PageTypeInfo | undefined;
 //#endregion
+//#region packages/provider/src/SchemaTypes.d.ts
+/**
+ * Structural shape of a typed schema registry. The `TMap` parameter is the
+ * meta-type map keyed by doc-type name (e.g. `{ "kanban": KanbanMeta, ... }`).
+ * `@abraca/schema`'s `SchemaRegistry<TMap>` satisfies this shape.
+ */
+interface SchemaRegistryLike<TMap extends Record<string, unknown> = Record<string, unknown>> {
+  readonly types: ReadonlyMap<string, unknown>;
+  readonly __metaMap?: TMap;
+}
+/** Extract the doc-type names from a registry. */
+type SchemaDocTypeName<S> = S extends SchemaRegistryLike<infer M> ? keyof M & string : never;
+/** Extract the meta type for a given doc-type name from a registry. */
+type SchemaMetaOf<S, N extends string> = S extends SchemaRegistryLike<infer M> ? N extends keyof M ? M[N] : never : never;
+/**
+ * A tree entry projected against a typed registry. The `meta` field is
+ * narrowed to `TMap[N] | undefined` so consumers get full type inference
+ * without an explicit cast.
+ *
+ * Note: `meta` is optional even when the registry mandates fields — the
+ * tree may contain entries written before the schema was authored, and
+ * Rule 4 means we don't reject them at read time.
+ */
+interface TypedTreeEntry<TMap extends Record<string, unknown>, N extends keyof TMap & string> {
+  readonly id: string;
+  readonly type: N;
+  readonly label: string;
+  readonly parentId: string | null;
+  readonly order: number;
+  readonly meta: TMap[N] | undefined;
+  readonly createdAt: number | undefined;
+  readonly updatedAt: number | undefined;
+}
+/**
+ * A typed surface bound to a schema. Returned by
+ * `DocumentManager.docs(schema)` so the schema doesn't have to be repeated
+ * at every call site.
+ *
+ * Read methods (`get`, `getEntry`, `narrow`) project the existing
+ * untyped tree without performing schema validation. Write methods
+ * (`update`, `set`, `clear`) delegate to `MetaManager` and are subject
+ * to whatever validator was attached via `MetaManager.setSchema` —
+ * they do NOT auto-attach the registry passed to `dm.docs()`.
+ */
+interface TypedDocsClient<TMap extends Record<string, unknown>> {
+  /**
+   * Fetch a tree entry projected as the requested doc-type. Returns
+   * `null` when the entry doesn't exist OR when its `type` field doesn't
+   * match `expectedType`.
+   */
+  get<N extends keyof TMap & string>(expectedType: N, id: string): TypedTreeEntry<TMap, N> | null;
+  /**
+   * Fetch the raw, untyped entry (no type-narrowing applied). Useful when
+   * the caller wants the underlying record without the projection.
+   */
+  getEntry(id: string): TreeEntry | null;
+  /**
+   * Discriminator helper: narrows an arbitrary `TreeEntry` to the
+   * requested doc-type, returning a typed projection or `null` on mismatch.
+   * No runtime read — pure type-guard helper.
+   */
+  narrow<N extends keyof TMap & string>(expectedType: N, entry: TreeEntry | null | undefined): TypedTreeEntry<TMap, N> | null;
+  /**
+   * Merge typed meta into a document's metadata. Throws
+   * `TypedDocTypeMismatchError` when the stored entry's `type` doesn't
+   * match `expectedType`; throws `MetaValidationError` when a validator
+   * is attached and the merged meta fails validation.
+   */
+  update<N extends keyof TMap & string>(expectedType: N, id: string, meta: Partial<TMap[N]>): void;
+  /**
+   * Replace all metadata on a document with a fully-typed payload.
+   * Same throw semantics as `update`.
+   */
+  set<N extends keyof TMap & string>(expectedType: N, id: string, meta: TMap[N]): void;
+  /**
+   * Delete specific metadata keys. Constrained to the typed key-set of
+   * `TMap[N]` so typos surface at compile time.
+   */
+  clear<N extends keyof TMap & string>(expectedType: N, id: string, keys: ReadonlyArray<keyof TMap[N] & string>): void;
+}
+/**
+ * Thrown by typed write methods on `TypedDocsClient` when the stored
+ * entry's `type` doesn't match the caller's `expectedType`. Distinct from
+ * `MetaValidationError` (which signals schema-content mismatches).
+ */
+declare class TypedDocTypeMismatchError extends Error {
+  readonly docId: string;
+  readonly expectedType: string;
+  readonly actualType: string | undefined;
+  constructor(docId: string, expectedType: string, actualType: string | undefined);
+}
+//#endregion
 //#region packages/provider/src/TreeManager.d.ts
 declare class TreeManager {
   private dm;
@@ -4308,6 +4663,18 @@ declare class TreeManager {
   /** Build nested tree JSON. */
   buildTree(rootId?: string | null, maxDepth?: number): TreeNode[];
   private _buildTree;
+  /**
+   * Schema-typed lookup. Returns a `TypedTreeEntry<TMap, N>` when the
+   * entry's `type` matches `expectedType`, else `null`. Pure projection
+   * over the existing untyped tree — no schema validation is performed
+   * here (the entry's data is whatever was last synced; meta correctness
+   * is the writer's responsibility, optionally enforced via
+   * `MetaManager.setSchema`).
+   *
+   * Rule 4 alignment: when the entry's type doesn't match, returns null
+   * rather than throwing — callers branch on the result.
+   */
+  getTyped<TMap extends Record<string, unknown>, N extends keyof TMap & string>(_schema: SchemaRegistryLike<TMap>, expectedType: N, docId: string): TypedTreeEntry<TMap, N> | null;
   /** Find a single entry by ID. */
   get(docId: string): TreeEntry | null;
   /** Search by label (case-insensitive substring match). */
@@ -4459,25 +4826,75 @@ interface DocumentMetaInfo {
   type?: string;
   meta: PageMeta;
 }
+/**
+ * Structural shape of a schema validator MetaManager can consult before
+ * writes. Compatible with `@abraca/schema`'s `SchemaRegistry`.
+ *
+ * Implementations MUST treat unknown doc-types as unconstrained
+ * (return `{ ok: true }`) — Rule 4: existing-app traffic for doc-types
+ * not in the validator's bundle is never rejected.
+ */
+interface SchemaValidatorLike {
+  validateMeta(docType: string, meta: unknown): {
+    ok: true;
+    value?: unknown;
+  } | {
+    ok: false;
+    errors: ReadonlyArray<{
+      path: ReadonlyArray<PropertyKey>;
+      message: string;
+      code?: string;
+    }>;
+  };
+}
+declare class MetaValidationError extends Error {
+  readonly docId: string;
+  readonly docType: string;
+  readonly errors: ReadonlyArray<{
+    path: ReadonlyArray<PropertyKey>;
+    message: string;
+    code?: string;
+  }>;
+  constructor(docId: string, docType: string, errors: ReadonlyArray<{
+    path: ReadonlyArray<PropertyKey>;
+    message: string;
+    code?: string;
+  }>);
+}
 declare class MetaManager {
   private dm;
+  private schema;
   constructor(dm: DocumentManager);
+  /**
+   * Attach (or detach with `null`) a schema validator. When set, every
+   * `update` / `set` validates the post-write meta against the entry's
+   * declared `type` before writing to the doc-tree. Entries without a
+   * `type` field pass through unconditionally.
+   */
+  setSchema(schema: SchemaValidatorLike | null): void;
   /** Read metadata for a document. Returns null if not found. */
   get(docId: string): DocumentMetaInfo | null;
   /**
    * Merge fields into a document's metadata.
    * Existing keys not in the update are preserved.
+   *
+   * @throws {MetaValidationError} when a schema is attached and the
+   *   merged meta fails validation for the entry's declared type.
    */
   update(docId: string, meta: Partial<PageMeta>): void;
   /**
    * Replace all metadata on a document.
    * This overwrites the entire meta object.
+   *
+   * @throws {MetaValidationError} when a schema is attached and the
+   *   replacement meta fails validation for the entry's declared type.
    */
   set(docId: string, meta: PageMeta): void;
   /**
    * Clear specific metadata keys (set them to null/undefined).
    */
   clear(docId: string, keys: string[]): void;
+  private validateOrThrow;
 }
 //#endregion
 //#region packages/provider/src/DocumentManager.d.ts
@@ -4533,6 +4950,20 @@ declare class DocumentManager {
   private _rootProvider;
   private childCache;
   constructor(config: DocumentManagerConfig);
+  /**
+   * Bind a schema registry to a typed accessor surface. The returned
+   * client offers `.get(type, id)` with the registry's meta types
+   * inferred at the call site, removing the need to pass `schema`
+   * to every lookup. The provider remains schema-free at runtime —
+   * `schema` is only used to drive type inference (see
+   * `SchemaRegistryLike` for the structural witness).
+   *
+   * @example
+   *   const docs = dm.docs(kanbanSchema);
+   *   const board = docs.get("kanban", id);
+   *   if (board) console.log(board.meta.kanbanColumnWidth); // typed
+   */
+  docs<TMap extends Record<string, unknown>>(_schema: SchemaRegistryLike<TMap>): TypedDocsClient<TMap>;
   get displayName(): string;
   get displayColor(): string;
   get serverInfo(): ServerInfo | null;
@@ -4600,4 +5031,4 @@ declare function normalizeRootId(id: string | null | undefined, rootDocId: strin
  */
 declare function toPlain(val: unknown): unknown;
 //#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 DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, 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, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, 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, 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, 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, TreeEntry, TreeManager, TreeNode, TreeSearchResult, 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, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.0.10",
+  "version": "2.4.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -39,5 +39,11 @@
   "peerDependencies": {
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.8"
+  },
+  "devDependencies": {
+    "@abraca/schema": "2.4.0"
+  },
+  "scripts": {
+    "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"
   }
-}
+}

package/src/AbracadabraBaseProvider.ts

@@ -12,6 +12,8 @@ import { AuthenticationMessage } from "./OutgoingMessages/AuthenticationMessage.
 import { AwarenessMessage } from "./OutgoingMessages/AwarenessMessage.ts";
 import { StatelessMessage } from "./OutgoingMessages/StatelessMessage.ts";
 import { RpcClient } from "./RpcClient.ts";
+import { QueryClient } from "./QueryClient.ts";
+import type { QuerySpec, QuerySubscriptionHandlers, QuerySubscriptionHandle } from "./QueryClient.ts";
 import { SyncStepOneMessage } from "./OutgoingMessages/SyncStepOneMessage.ts";
 import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
 import type {
@@ -181,6 +183,32 @@ export class AbracadabraBaseProvider extends EventEmitter {
     return this._rpc;
   }
 
+  /**
+   * Lazily-constructed V2 query subscription client. See
+   * `QueryClient`. Each call to `subscribeQuery(...)` opens a
+   * long-lived subscription that fires `onSnapshot` with the initial
+   * result set and `onDelta` whenever the projection moves.
+   */
+  private _queryClient: QueryClient | undefined;
+  private getQueryClient(): QueryClient {
+    if (!this._queryClient) {
+      this._queryClient = new QueryClient(this);
+    }
+    return this._queryClient;
+  }
+
+  /**
+   * Open a live query subscription. Mirrors the v1 REST shape
+   * (`POST /docs/query`) but pushes deltas as the server-side
+   * projection drifts under the predicate.
+   */
+  subscribeQuery(
+    spec: QuerySpec,
+    handlers: QuerySubscriptionHandlers = {},
+  ): QuerySubscriptionHandle {
+    return this.getQueryClient().subscribeQuery(spec, handlers);
+  }
+
   constructor(configuration: AbracadabraBaseProviderConfiguration) {
     super();
     this.setConfiguration(configuration);

package/src/AbracadabraClient.ts

@@ -603,6 +603,38 @@ export class AbracadabraClient {
 		return res.results;
 	}
 
+	/**
+	 * Query for documents matching a structural predicate. v1 of the
+	 * indexed-query layer described in
+	 * `ARCHITECTURE/20-kickoff-phase3-queries.md`.
+	 *
+	 * The wire shape accepts a `where` field so v2 (meta-predicate
+	 * filtering on top of the `doc_meta_index` projection) can light up
+	 * without a compatibility break. Sending a non-empty `where` today
+	 * returns a 400 — callers should leave it absent.
+	 *
+	 * Returns docs the requester can read at viewer-or-above, filtered
+	 * through the cascading permission resolver server-side.
+	 */
+	async queryDocs(opts: {
+		type?: string;
+		parentId?: string;
+		labelContains?: string;
+		limit?: number;
+	}): Promise<DocumentMeta[]> {
+		const body: Record<string, unknown> = {};
+		if (opts.type != null) body.type = opts.type;
+		if (opts.parentId != null) body.parent_id = opts.parentId;
+		if (opts.labelContains != null) body.label_contains = opts.labelContains;
+		if (opts.limit != null) body.limit = opts.limit;
+		const res = await this.request<{ documents: DocumentMeta[]; v: number }>(
+			"POST",
+			"/docs/query",
+			{ body },
+		);
+		return res.documents;
+	}
+
 	/**
 	 * List the direct children of a document, returning full metadata. Pass
 	 * no argument to list the children of the server root — what the