@abraca/dabra 1.9.1 → 2.0.0

package/src/TreeManager.ts

@@ -12,6 +12,7 @@ import type {
 	TreeSearchResult,
 	PageMeta,
 } from "./DocTypes.ts";
+import { resolvePageType } from "./DocTypes.ts";
 import { toPlain, normalizeRootId } from "./DocUtils.ts";
 import type { DocumentManager } from "./DocumentManager.ts";
 
@@ -227,16 +228,50 @@ export class TreeManager {
 		};
 	}
 
+	/**
+	 * Create a document and auto-apply renderer defaults from the page type's
+	 * `defaultMetaFields` (toggle fields with `default` values).
+	 */
+	createWithTypeDefaults(opts: {
+		parentId?: string | null;
+		label: string;
+		type: string;
+		extraMeta?: Partial<PageMeta>;
+	}): TreeEntry {
+		const typeInfo = resolvePageType(opts.type);
+		const autoMeta: Record<string, unknown> = {};
+		if (typeInfo?.defaultMetaFields) {
+			for (const field of typeInfo.defaultMetaFields) {
+				if (field.type === "toggle" && field.key && field.default !== undefined) {
+					autoMeta[field.key] = field.default;
+				}
+			}
+		}
+		const mergedMeta =
+			Object.keys(autoMeta).length > 0 || opts.extraMeta
+				? { ...autoMeta, ...(opts.extraMeta ?? {}) }
+				: undefined;
+		return this.create({
+			parentId: opts.parentId,
+			label: opts.label,
+			type: opts.type,
+			meta: mergedMeta,
+		});
+	}
+
 	/** Rename a document. */
 	rename(docId: string, label: string): void {
 		const treeMap = this.dm.getTreeMap();
-		if (!treeMap) throw new Error("Not connected");
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) throw new Error("Not connected");
 
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
 		const entry = toPlain(raw) as Record<string, unknown>;
-		treeMap.set(docId, { ...entry, label, updatedAt: Date.now() });
+		rootDoc.transact(() => {
+			treeMap.set(docId, { ...entry, label, updatedAt: Date.now() });
+		});
 	}
 
 	/** Move a document to a new parent. */
@@ -246,33 +281,39 @@ export class TreeManager {
 		order?: number,
 	): void {
 		const treeMap = this.dm.getTreeMap();
-		if (!treeMap) throw new Error("Not connected");
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) throw new Error("Not connected");
 
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
 		const entry = toPlain(raw) as Record<string, unknown>;
-		treeMap.set(docId, {
-			...entry,
-			parentId: normalizeRootId(
-				newParentId ?? null,
-				this.dm.rootDocId,
-			),
-			order: order ?? Date.now(),
-			updatedAt: Date.now(),
+		rootDoc.transact(() => {
+			treeMap.set(docId, {
+				...entry,
+				parentId: normalizeRootId(
+					newParentId ?? null,
+					this.dm.rootDocId,
+				),
+				order: order ?? Date.now(),
+				updatedAt: Date.now(),
+			});
 		});
 	}
 
 	/** Change the page type of a document. */
 	changeType(docId: string, type: string): void {
 		const treeMap = this.dm.getTreeMap();
-		if (!treeMap) throw new Error("Not connected");
+		const rootDoc = this.dm.rootDocument;
+		if (!treeMap || !rootDoc) throw new Error("Not connected");
 
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
 		const entry = toPlain(raw) as Record<string, unknown>;
-		treeMap.set(docId, { ...entry, type, updatedAt: Date.now() });
+		rootDoc.transact(() => {
+			treeMap.set(docId, { ...entry, type, updatedAt: Date.now() });
+		});
 	}
 
 	/**
@@ -325,21 +366,24 @@ export class TreeManager {
 		const entry = toPlain(raw) as Record<string, unknown>;
 		const newId = crypto.randomUUID();
 		const now = Date.now();
+		const newLabel = ((entry.label as string) || "Untitled") + " (copy)";
 		treeMap.set(newId, {
 			...entry,
-			label: ((entry.label as string) || "Untitled") + " (copy)",
+			label: newLabel,
 			order: now,
+			createdAt: now,
+			updatedAt: now,
 		});
 
 		return {
 			id: newId,
-			label: ((entry.label as string) || "Untitled") + " (copy)",
+			label: newLabel,
 			parentId: (entry.parentId as string | null) ?? null,
 			order: now,
 			type: entry.type as string | undefined,
 			meta: entry.meta as PageMeta | undefined,
-			createdAt: entry.createdAt as number | undefined,
-			updatedAt: entry.updatedAt as number | undefined,
+			createdAt: now,
+			updatedAt: now,
 		};
 	}
 

package/src/TreeTimestamps.ts

@@ -8,8 +8,9 @@
  * This propagates "last edited" timestamps to all peers via the root CRDT,
  * without requiring any server-side changes.
  *
- * A trailing-edge throttle (default 5 s) limits writes to avoid CRDT bloat
- * on the root doc during rapid typing.
+ * Leading-edge + trailing-edge throttle (default 5 s window): the first
+ * update flushes immediately so the "last edited" badge updates instantly;
+ * follow-up updates within the window are coalesced into one trailing flush.
  */
 
 import * as Y from "yjs";
@@ -19,18 +20,15 @@ import type { OfflineStore } from "./OfflineStore.ts";
  * Attach an observer that writes `updatedAt` to the root doc-tree entry for
  * `childDocId` whenever the child doc receives a non-offline update.
  *
- * Writes are throttled: the first qualifying update records the timestamp;
- * a trailing-edge timer flushes it to the tree map after `throttleMs`.
- *
  * @param treeMap       The root doc's "doc-tree" Y.Map.
  * @param childDocId    The child document's UUID (key in treeMap).
  * @param childDoc      The child Y.Doc to observe.
  * @param offlineStore  The child provider's OfflineStore (used to detect
  *                      offline-replay origins and skip them). Pass null when
  *                      the offline store is disabled.
- * @param options       Optional config. `throttleMs` controls the write
- *                      interval (default 5000).
- * @returns             Cleanup function — call on provider destroy.  Flushes
+ * @param options       Optional config. `throttleMs` controls the throttle
+ *                      window (default 5000).
+ * @returns             Cleanup function — call on provider destroy. Flushes
  *                      any pending write before detaching.
  */
 export function attachUpdatedAtObserver(
@@ -42,34 +40,39 @@ export function attachUpdatedAtObserver(
 ): () => void {
 	const throttleMs = options?.throttleMs ?? 5000;
 
-	let latestTs = 0;
+	let lastFlushedAt = 0;
+	let pendingTs = 0;
 	let timer: ReturnType<typeof setTimeout> | null = null;
 
-	function flush(): void {
-		if (latestTs === 0) return;
-		const ts = latestTs;
-		latestTs = 0;
-		timer = null;
-
+	function writeTs(ts: number): void {
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
-
-		// Guard: if the entry is a nested Y.Map (possible after Yrs
-		// document compaction), convert to plain object so spread works.
 		const entry = raw instanceof Y.Map ? (raw as any).toJSON() : raw;
 		treeMap.set(childDocId, { ...entry, updatedAt: ts });
+		lastFlushedAt = ts;
+	}
+
+	function flushPending(): void {
+		timer = null;
+		if (pendingTs === 0) return;
+		const ts = pendingTs;
+		pendingTs = 0;
+		writeTs(ts);
 	}
 
 	function handler(_update: Uint8Array, origin: unknown): void {
-		// Skip updates replayed from the local offline store — they represent
-		// content that was already "seen" and shouldn't advance updatedAt.
 		if (offlineStore !== null && origin === offlineStore) return;
 
-		latestTs = Date.now();
-
-		// Schedule a trailing-edge flush if none is pending.
+		const now = Date.now();
+		if (now - lastFlushedAt >= throttleMs) {
+			// Leading edge — flush immediately.
+			writeTs(now);
+			return;
+		}
+		// Inside the throttle window — coalesce into a trailing flush.
+		pendingTs = now;
 		if (timer === null) {
-			timer = setTimeout(flush, throttleMs);
+			timer = setTimeout(flushPending, throttleMs - (now - lastFlushedAt));
 		}
 	}
 
@@ -79,7 +82,7 @@ export function attachUpdatedAtObserver(
 		childDoc.off("update", handler);
 		if (timer !== null) {
 			clearTimeout(timer);
-			flush(); // persist the last pending timestamp
+			flushPending();
 		}
 	};
 }

package/src/index.ts

@@ -37,8 +37,52 @@ export type {
 } from "./IdentityDoc.ts";
 export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";
 export { ChatClient } from "./ChatClient.ts";
-export type { ChatClientTransport } from "./ChatClient.ts";
+export { RpcClient, RpcError, RPC_PREFIX } from "./RpcClient.ts";
+export type {
+	RpcKind,
+	RpcFrame,
+	RpcErrorPayload,
+	RpcErrorCode,
+	RpcTransport,
+	RpcTarget,
+	RpcCallOptions,
+	RpcCallHandle,
+	RpcHandler,
+	RpcHandlerContext,
+} from "./RpcClient.ts";
+export type {
+	ChatClientTransport,
+	SendMessageInput,
+	SendMessageResult,
+	EditMessageInput,
+	DeleteMessageInput,
+	MarkReadInput as ChatMarkReadInput,
+} from "./ChatClient.ts";
+export {
+	EncryptedChatClient,
+	ChannelKeyResolver,
+	encryptChatContent,
+	decryptChatContent,
+	isEncryptedContent,
+} from "./EncryptedChatClient.ts";
+export {
+	foldRecords,
+	recordFromYAny,
+} from "./messageRecord.ts";
+export type {
+	MessageRecord,
+	FoldedMessage,
+} from "./messageRecord.ts";
 export { NotificationsClient } from "./NotificationsClient.ts";
+export type {
+	InboxEntry,
+	FetchInboxInput,
+	MarkReadInput as InboxMarkReadInput,
+} from "./NotificationsClient.ts";
+// Legacy type re-exports — wire-shape types from the deprecated chat:* / notify:*
+// protocol that consumers may still import. The dashboard's reactive layer
+// reads/writes these shapes directly off Y.Array entries on channel-period and
+// inbox docs, independently of ChatClient/NotificationsClient.
 export type {
 	ChatMessage,
 	ChatChannel,
@@ -62,3 +106,29 @@ export {
 	unwrapSeed,
 	bip39Wordlist,
 } from "./MnemonicKeyDerivation.ts";
+export { DocumentManager } from "./DocumentManager.ts";
+export type { DocumentManagerConfig } from "./DocumentManager.ts";
+export { TreeManager } from "./TreeManager.ts";
+export { ContentManager } from "./ContentManager.ts";
+export type { DocumentContent } from "./ContentManager.ts";
+export { MetaManager } from "./MetaManager.ts";
+export type { DocumentMetaInfo } from "./MetaManager.ts";
+export * from "./DocTypes.ts";
+export { waitForSync, withTimeout, normalizeRootId, toPlain } from "./DocUtils.ts";
+export {
+	yjsToMarkdown,
+	populateYDocFromMarkdown,
+	parseFrontmatter,
+	filenameToLabel,
+	buildHeadingElement,
+	buildParagraphElement,
+	buildBulletListElement,
+	buildOrderedListElement,
+	buildTaskListElement,
+	buildCodeBlockElement,
+	buildBlockquoteElement,
+	buildHorizontalRuleElement,
+	buildBlocksFromMarkdown,
+	readBlocksFromFragment,
+} from "./DocConverters.ts";
+export type { DocumentBlock } from "./DocConverters.ts";

package/src/messageRecord.ts

@@ -0,0 +1,121 @@
+/**
+ * Decode + fold message records from a period doc's `messages` Y.Array
+ * into the flat `ChatMessage[]` shape the dashboard renders.
+ *
+ * The server appends three kinds of records to the array (see
+ * `abracadabra-rs/crates/abracadabra/src/messages.rs`):
+ *
+ *   - `record_kind: "message"`     — a real message (default kind).
+ *   - `record_kind: "edit"`        — an updated version of `target_id`.
+ *   - `record_kind: "tombstone"`   — `target_id` is deleted.
+ *
+ * Folding rules:
+ *   - For each `target_id`, apply edits in `ts` order; the *last* edit's
+ *     content wins. The original message's id, sender_id, and ts stay.
+ *     `editedAt` is the latest edit's ts.
+ *   - Any target_id with a tombstone is dropped from the output entirely.
+ *   - Records without record_kind default to "message" (back-compat).
+ *
+ * Cross-period folding: edits and tombstones can in principle target a
+ * message in a *prior* period (e.g. user edits a message that lived on
+ * the previous period after rollover). Callers that paginate across
+ * periods should fold the joined list, not each period independently.
+ */
+
+export interface MessageRecord {
+  record_kind?: 'message' | 'edit' | 'tombstone'
+  id: string
+  target_id?: string
+  sender_id: string
+  channel_doc_id: string
+  period_id: string
+  ts: number
+  content: string
+  mentions?: string[]
+  reply_to?: string | null
+  sig?: string
+  server_sig?: string
+}
+
+export interface FoldedMessage {
+  id: string
+  channel: string
+  senderId: string
+  senderName?: string
+  content: string
+  createdAt: number
+  /** Set if the message has been edited at least once. */
+  editedAt?: number
+  /** Reply target message id, if any. */
+  replyTo?: string
+}
+
+/**
+ * Fold an ordered list of records (oldest-first) into the visible
+ * messages a UI should render. Records may come from one period or
+ * across multiple periods concatenated in time order.
+ */
+export function foldRecords(records: MessageRecord[]): FoldedMessage[] {
+  const tombstoned = new Set<string>()
+  for (const r of records) {
+    if (r.record_kind === 'tombstone' && r.target_id) tombstoned.add(r.target_id)
+  }
+
+  const base = new Map<string, FoldedMessage>()
+  for (const r of records) {
+    const kind = r.record_kind ?? 'message'
+    if (kind !== 'message') continue
+    if (tombstoned.has(r.id)) continue
+    base.set(r.id, {
+      id: r.id,
+      channel: r.channel_doc_id,
+      senderId: r.sender_id,
+      content: r.content,
+      createdAt: r.ts,
+      ...(r.reply_to ? { replyTo: r.reply_to } : {}),
+    })
+  }
+
+  for (const r of records) {
+    if (r.record_kind !== 'edit' || !r.target_id) continue
+    if (tombstoned.has(r.target_id)) continue
+    const original = base.get(r.target_id)
+    if (!original) continue
+    original.content = r.content
+    original.editedAt = r.ts
+  }
+
+  return [...base.values()].sort((a, b) => a.createdAt - b.createdAt)
+}
+
+/**
+ * Decode whatever the Y.Array stored for an entry into a MessageRecord.
+ * Note: the server stamps `ts` server-side via `Any::BigInt(now_ts_ms())`,
+ * so on the wire it round-trips as a JS BigInt — `typeof` is `'bigint'`,
+ * not `'number'`. Accept both and coerce.
+ */
+export function recordFromYAny(any: unknown): MessageRecord | null {
+  if (!any || typeof any !== 'object') return null
+  const o = any as Record<string, unknown>
+  const tsRaw = o.ts
+  const tsIsValid = typeof tsRaw === 'number' || typeof tsRaw === 'bigint'
+  if (typeof o.id !== 'string' || typeof o.sender_id !== 'string'
+    || typeof o.channel_doc_id !== 'string' || !tsIsValid) {
+    return null
+  }
+  const ts = typeof tsRaw === 'bigint' ? Number(tsRaw) : (tsRaw as number)
+  return {
+    record_kind: typeof o.record_kind === 'string' ? o.record_kind as MessageRecord['record_kind'] : 'message',
+    id: o.id,
+    target_id: typeof o.target_id === 'string' ? o.target_id : undefined,
+    sender_id: o.sender_id,
+    channel_doc_id: o.channel_doc_id,
+    period_id: typeof o.period_id === 'string' ? o.period_id : '',
+    ts,
+    content: typeof o.content === 'string' ? o.content : '',
+    mentions: Array.isArray(o.mentions) ? o.mentions as string[] : [],
+    reply_to: typeof o.reply_to === 'string' ? o.reply_to : null,
+    sig: typeof o.sig === 'string' ? o.sig : undefined,
+    server_sig: typeof o.server_sig === 'string' ? o.server_sig : undefined,
+  }
+}

package/src/types.ts

@@ -183,20 +183,68 @@ export interface UserProfile {
   role: string;
   /** Account-level Ed25519 public key (base64url). Canonical user identity. */
   publicKey: string | null;
+  /**
+   * Whether the user has a password set. `false` for key-based soft
+   * identities until they opt in via {@link AbracadabraClient.setPassword}.
+   * Drives the UI's "Set password" vs "Change password" branching.
+   */
+  hasPassword?: boolean;
 }
 
 export interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  /**
+   * Renderer hint — `"kanban"`, `"checklist"`, `"outline"`, `"graph"`,
+   * `"sheet"`, `"mindmap"`, `"doc"`, etc. Drives the dashboard's choice of
+   * Vue component for this doc. Orthogonal to {@link kind}.
+   */
   doc_type?: string | null;
   label?: string | null;
   description?: string | null;
   public_access?: string | null;
   owner_id?: string | null;
-  is_hub?: boolean;
+  /**
+   * Structural role hint — `"server"` for the reserved server-root doc,
+   * `"space"` for top-level workspace containers, `null`/absent otherwise.
+   * Distinct from {@link doc_type}: a Space (`kind: "space"`) can contain
+   * many Kanban boards (each `doc_type: "kanban"`).
+   */
+  kind?: string | null;
   updated_at?: number | null;
 }
 
+/**
+ * Well-known structural roles for the {@link DocumentMeta.kind} field. These
+ * are conventions only — the server treats `kind` as an opaque string. Use
+ * these constants instead of string literals to avoid typos.
+ */
+export const Kind = {
+  /** The reserved server root document. There is exactly one per server. */
+  Server: "server",
+  /** A top-level workspace container — what the dashboard calls a "Space". */
+  Space: "space",
+  /** A regular content page rendered by the editor. */
+  Page: "page",
+  /** A group chat container under a Space. */
+  Channel: "channel",
+  /** A direct-message container at the server root with two-member permissions. */
+  Dm: "dm",
+  /** A child of channel/dm holding the messages Y.Array. */
+  ChannelPeriod: "channel-period",
+  /** A per-user inbox doc holding inbox entries; child of server root. */
+  Inbox: "inbox",
+} as const;
+export type Kind = typeof Kind[keyof typeof Kind];
+
+/**
+ * Hardcoded UUID of the reserved server root document. Every doc in the tree
+ * chains up to this row, so a permission grant on this doc cascades into
+ * every descendant. Mirrors the constant in the Rust crate
+ * (`crate::types::SERVER_ROOT_ID_STR`).
+ */
+export const SERVER_ROOT_ID = "00000000-0000-0000-0000-000000000000";
+
 export interface UploadMeta {
   id: string;
   doc_id: string;
@@ -250,10 +298,30 @@ export interface SnapshotMeta {
   label?: string | null;
   created_by?: string | null;
   created_at: number;
+  /** Number of uploads referenced by this snapshot's CRDT state.
+   *  Always 0 on servers older than the `snapshot_files` migration, or for
+   *  snapshots created before that migration ran (until the operator runs
+   *  `POST /admin/snapshots/backfill-refs`). */
+  file_count?: number;
+  /** Signed byte delta vs. the previous-version snapshot for this doc.
+   *  `null` for the first snapshot of a doc (or when the previous version
+   *  has been pruned). Lets the UI render `+12 KB` / `−3 KB`. */
+  delta_bytes?: number | null;
+}
+
+export interface SnapshotFileEntry {
+  id: string;
+  doc_id: string;
+  filename: string;
+  mime_type?: string | null;
+  size?: number | null;
 }
 
 export interface SnapshotData extends SnapshotMeta {
   data: string;
+  /** Populated only when fetched with `?include=files`. Each entry is an
+   *  upload referenced by this snapshot's CRDT state. */
+  files?: SnapshotFileEntry[];
 }
 
 export interface SnapshotCreateResult {
@@ -285,10 +353,23 @@ export interface ServerInfo {
   version?: string;
   /** Hocuspocus wire protocol version (currently 2). */
   protocol_version?: number;
-  /** Entry-point document ID advertised by the server, if configured. */
-  index_doc_id?: string;
-  /** Default role assigned to users without explicit permissions. */
-  default_role?: string;
+  /**
+   * The reserved server root document id. Every doc in the tree chains up
+   * to this row; granting Admin here cascades to every doc. Hardcoded by
+   * the server — clients can also use {@link SERVER_ROOT_ID} directly.
+   */
+  root_doc_id?: string;
+  /**
+   * Server-wide access policy. Drives client-side decisions like "show the
+   * sign-up CTA?" (anonymous mode) or "warn before publishing?" (anonymous
+   * grants).
+   */
+  access?: {
+    /** `"none"` rejects unauthenticated requests; `"observer"` allows public read. */
+    anonymous?: "none" | "observer";
+    /** Server-wide floor for authed users with no explicit grant. */
+    authenticated?: "none" | "observer" | "viewer" | "editor";
+  };
   /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
   auth_methods?: string[];
   /** Whether open registration is enabled. */
@@ -297,6 +378,13 @@ export interface ServerInfo {
   invite_only?: boolean;
   /** Server encryption configuration. */
   encryption?: { default_mode?: string; minimum_mode?: string };
+  /**
+   * Ed25519 public key (base64url, no padding) the server uses to sign every
+   * accepted `messages:*` record (`server_sig`). Clients can verify message
+   * placement / ordering by checking each record's `server_sig` against this
+   * key over the canonical `{ msg_id, period_id, ts, client_sig }` payload.
+   */
+  messages_signer_pubkey?: string;
 }
 
 // ── Search ───────────────────────────────────────────────────────────────────
@@ -307,21 +395,83 @@ export interface SearchResult {
   score: number;
 }
 
-// ── Spaces ───────────────────────────────────────────────────────────────────
+/**
+ * A single hit returned by the server's full-text search endpoint
+ * (`GET /docs/search`). Distinct from {@link SearchResult}, which is the
+ * client-side trigram index in `SearchIndex.ts`.
+ *
+ * `snippet` is server-rendered HTML with `<mark>` wrappers around the
+ * matched tokens — safe to inject after standard sanitization. `rank` is
+ * a backend-specific score (SQLite bm25 vs Postgres ts_rank); the only
+ * guarantee is that hits arrive in best-first order.
+ */
+export interface DocSearchHit {
+  doc_id: string;
+  parent_id: string | null;
+  label: string | null;
+  kind: string | null;
+  /** HTML-safe snippet with `<mark>` markers around the matched tokens. */
+  snippet: string;
+  rank: number;
+}
 
-export interface SpaceMeta {
+// ── Audit log (admin) ────────────────────────────────────────────────────────
+
+/**
+ * A single row from `GET /admin/audit`. Mirrors the server's audit log
+ * row format (see `audit::AuditLogRow`). `metadata` is the parsed JSON
+ * object the server stored, or `null` if the row had no metadata. Each
+ * row carries an internal `prev_hash` / `row_hash` chain that admins
+ * verify with {@link AuditVerifyResult}.
+ */
+export interface AuditLogEntry {
   id: string;
-  doc_id: string;
-  name: string;
-  description: string | null;
-  visibility: "public" | "private" | "invite";
-  is_hub: boolean;
-  owner_id: string | null;
-  created_at: number;
-  updated_at: number;
-  public_access?: string | null;
+  ts: number;
+  event_type: string;
+  actor_user_id: string | null;
+  actor_ip: string | null;
+  request_id: string | null;
+  target_type: string | null;
+  target_id: string | null;
+  metadata: Record<string, unknown> | null;
+  outcome: string;
+}
+
+/** Filters for `GET /admin/audit`. All optional and AND-combined. */
+export interface AuditQueryOpts {
+  event_type?: string;
+  actor_user_id?: string;
+  target_type?: string;
+  target_id?: string;
+  since_ts?: number;
+  until_ts?: number;
+  limit?: number;
+  offset?: number;
 }
 
+/** Response of `GET /admin/audit/verify`. `status: "broken"` carries `break`. */
+export interface AuditVerifyResult {
+  status: "ok" | "broken";
+  message?: string;
+  break?: { rows_checked: number; row_id: string; reason: string };
+}
+
+// ── Readiness ────────────────────────────────────────────────────────────────
+
+/** Response of `GET /readyz`. HTTP 200 when ready, 503 when not. */
+export interface ReadyzStatus {
+  status: "ready" | "unready";
+  version: string;
+  checks: { database: "ok" | "error" };
+}
+
+// ── Spaces ───────────────────────────────────────────────────────────────────
+//
+// Spaces are documents whose `parent_id` is the server root and whose `kind`
+// is `"space"`. Listing them is `client.listSpaces()`; they come back as
+// regular `DocumentMeta` objects. Visibility is encoded in `public_access`:
+// `null` (or `"none"`) = private, `"observer"` = public read-only.
+
 // ── Invites ──────────────────────────────────────────────────────────────────
 
 export interface InviteRow {