@spooky-sync/core 0.0.1-canary.322 → 0.0.1-canary.324

package/AGENTS.md

@@ -38,7 +38,7 @@ re-materialized from state, never patched in place.
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.
 - `AuthService` — token management, sign-in/sign-out events.
-- `CrdtManager`, `CrdtField`, `cursorColorFromName`, `CURSOR_COLORS` — Loro-CRDT integration.
+- `CrdtManager`, `CrdtField`, `cursorColorFromName`, `CURSOR_COLORS`: collaborative `@crdt` fields on Loro. Client methods: `openCrdtField(table, recordId, field, draft?)` -> `Promise<CrdtField>` (every open of one field in a tab shares one `LoroDoc`; pair each with a close), `closeCrdtField(table, recordId, field)` -> `Promise<void>` (resolves once unsent edits are in the outbox), `createCrdtDraft(table, field)` -> a detached `CrdtField` for a record not created yet (`db.create` first, then pass it to `openCrdtField` as `draft`). `CrdtField`: `getDoc()`, `hasContent()`, `pushCursorState(bytes)`, `onCursorUpdate = cb` (a setter). Config: `crdt: true` preloads Loro, `crdtDebounceMs` (default 300, max wait 2 s). Design: `docs/crdt-v2.md` at the repo root.
 - Types: `Sp00kyConfig` (client-solid wraps it as `SyncedDbConfig`), `QueryTimeToLive`, `PersistenceClient`, `StoreType`, `UpdateOptions`, `RunOptions`, `PreloadOptions`.
 - Subpath: `@spooky-sync/core/otel` — `createOtelTransmit(endpoint)` for piping pino logs to OpenTelemetry.
 - `client.webPush` (`WebPushModule`, `db.webPush` in the Solid bindings) - Web Push on the page: `support()`, `info()`, `subscribe(opts)` (call from a click), `unsubscribe(opts)`, `sync()`, `isSubscribed()`, `update(opts)`, `devices()`, `notify(msg)`, `cancel(id)`, `test()`, `bridge()`, `onMessage(cb)`. Server calls are `fn::push::*`; typed `WebPushError`; config `webPush` in `types.ts`. Sign-out runs through `AuthService.onBeforeSignOut`.
@@ -49,12 +49,13 @@ re-materialized from state, never patched in place.
 - **Use UI hooks, not the client directly.** In a Solid app, call `useDb()` from `@spooky-sync/client-solid`. Touch `Sp00kyClient` only inside `provider.client` for advanced flows.
 - **Mutations are optimistic.** `db.create` / `db.update` / `db.delete` return immediately; the queue drains in the background. Inspect progress via `pendingMutationCount`.
 - **Record IDs are full strings.** `db.create('thread:abc123', {...})` — *not* `db.create('thread', { id: 'abc123' })`. The first arg is `'<table>:<id>'`. Generate IDs with `Uuid` from `surrealdb` (re-exported by `client-solid`).
-- **`db.update` takes `(table, id, payload, options?)`**. The `debounced` option (`{ debounced: true }` or `{ debounced: { delay, key, flushOnHide } }`) coalesces rapid updates — use it for CRDT text/title fields. With `flushOnHide` (default `true`) the merged patch is also kept in the local `_00_pending_writes` table and pushed as soon as the page is hidden, so a reload or closed tab inside the delay does not lose it (the next boot moves a leftover patch into the outbox). `flushOnHide: false` keeps the patch in memory only.
+- **`db.update` takes `(table, id, payload, options?)`**. The `debounced` option (`{ debounced: true }` or `{ debounced: { delay, key, flushOnHide } }`) coalesces rapid updates, e.g. a plain text input saved as you type (never for `@crdt` fields, which are not written with `db.update`). With `flushOnHide` (default `true`) the merged patch is also kept in the local `_00_pending_writes` table and pushed as soon as the page is hidden, so a reload or closed tab inside the delay does not lose it (the next boot moves a leftover patch into the outbox). `flushOnHide: false` keeps the patch in memory only.
 - **`db.remoteQuery(sql, vars?)` is the one-shot remote read.** It runs one SurrealQL statement through the client's remote path (connect gate, per-statement timeout, concurrency limit) and returns the SurrealDB result array; results are not synced into the local cache. Use it for counts and other reads the query builder can't express.
 - **`db.useRemote(fn)` hands out the bare SDK client.** Same cache bypass, but it skips the connect gate (a call during a reconnect fails with "Specify a namespace to use"). Reserve it for SDK features `remoteQuery` cannot reach (transactions, `live`).
 - **Raw remote calls are gated by the query allowlist.** When the generated schema carries `policy.queryAllowlist: 'warn' | 'enforce'` (from `sync.queryAllowlist` in `sp00ky.yml`), `remoteQuery`, `useRemote` and `queryRaw` throw unless the client config sets `allowRawRemote: true`; builder queries are unaffected. A registration the SSP refuses as not allowlisted (403 `not_allowlisted`) is marked `remote: 'failed'` after one attempt with an error-level log carrying the surql and a `spky generate` hint; the view stays cold (`membershipKnown` false), it is never read as confirmed empty.
+- **A `@crdt` field is server-written plain text.** Edit it only through `openCrdtField` / `useCrdtField`; leave it out of `db.create` / `db.update` payloads (a client write keeps the old value). Reading it (lists, search, `where`) is fine, but it trails live edits until the SSP folds the edit log (about a minute after the last edit by default). Edits travel as `<table>__crdt_log` rows through the ordinary outbox; each tab claims a random Loro peer in `_00_crdt_peer`, and log rows whose blob is not an update made by that peer are refused everywhere (`modules/crdt/acceptance.ts`, mirrored in Rust). Unsent edits survive reloads in `_00_crdt_local`. Dart (`spooky_core`) does not implement CRDT fields yet.
 - **`@parent` columns are auto-populated.** Defined in the `.surql` schema as `record<user>` with the `-- @parent` annotation; never write them yourself — they're set from the auth context server-side.
-- **`db.preload` is a registered query.** Resolved before on this device (a `_00_view` row exists) it returns at once; never resolved it waits until the server's membership and every body are local. It holds no subscriber, so it is evicted a ttl after registration unless a view mounts the same query. `refresh`/`staleTime` are ignored; pass `signal` to abort a cold wait.
+- **`db.preload` is a registered query.** Resolved before on this device (a `_00_view` row exists) it returns at once; never resolved it waits until the server's membership and every body are local. A signed-out session without `enableAnonymousLiveQueries` is never sent membership, so its preload returns at once instead of blocking. It holds no subscriber, so it is evicted a ttl after registration unless a view mounts the same query. `refresh`/`staleTime` are ignored; pass `signal` to abort a cold wait.
 - **A never-resolved query paints only vouched rows.** Before the server answers (`cold`), the local predicate scan shows a cached body only if some `_00_view` row names it (as a member or subquery child) or a write for it is in flight. A body no view names is an orphan (deleted upstream while nothing watched it): it stays hidden, and the GC deletes it 30 s after boot and then hourly. A `_00_view` row no query has resolved for 14 days is retired by the same sweep, so that query paints cold again.
 - **A rejected write is not lost.** Application errors roll the local row back (create/update/delete) and move the mutation to `_00_failed_mutations`; the tray API above lists, retries (as a fresh write) or discards it. Network errors keep the row queued.
 

package/dist/index.d.ts

@@ -303,6 +303,10 @@ interface CircuitPrimeContext {
   /** Encoded ids with an unsettled local mutation (their `_00_rv` was bumped
    *  locally and may exceed the server's next version). */
   pendingIds: Set<string>;
+  /** Each table's client column set (`columnFingerprints`). An engine that
+   *  keeps bodies across schema changes resets the versions of a table whose
+   *  set changed before they are read, so its rows are fetched again whole. */
+  columnFingerprints?: Record<string, string>;
   /** Receives every `(id, rv)` the prime put into the circuit, per table, so
    *  the sync layer can skip re-downloading bodies it already has. */
   onVersions?: (table: string, entries: [string, number][]) => void;
@@ -494,189 +498,185 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
+//#region src/utils/index.d.ts
+declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
+/**
+ * Convert plain text to simple HTML paragraphs.
+ * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
+ */
+declare function textToHtml(text: string): string;
+/**
+ * Helper for retrying DB operations with exponential backoff
+ */
+//#endregion
+//#region src/modules/crdt/mirror.d.ts
+/**
+ * The plain text a `@crdt` field shows as its column value, rendered the same
+ * way the SSP fold renders it (`packages/ssp-node/src/crdt/mirror.rs`).
+ */
+type CrdtKind = 'text' | 'prosemirror';
+//#endregion
 //#region src/modules/crdt/crdt-field.d.ts
 declare const CURSOR_COLORS: string[];
 declare function cursorColorFromName(name: string): string;
+/** What a field handle needs from the manager that owns its session. */
+interface CrdtFieldHost {
+  pushPresence(state: Uint8Array): void;
+}
+/**
+ * An open collaborative field: the Loro document an editor binds to. Edits
+ * made on it are sent as the client's own edit-log rows; other clients' rows
+ * are imported into it as they arrive. Every open of the same field in one tab
+ * shares this document.
+ */
 declare class CrdtField {
-  private fieldName;
-  private doc;
-  private pushTimer;
-  private local;
-  private remote;
-  private recordId;
-  private sessionId;
-  private unsubscribe;
-  private lastPushTime;
-  private lastCursorPushTime;
-  private loadedFromCrdt;
-  private pushRetryCount;
-  private logger;
-  private cursorsEnabled;
-  /** Remote-push debounce. Local writes happen immediately on every Loro
-   *  update; the remote UPSERT is coalesced over this window. Configured
-   *  via `Sp00kyConfig.crdtDebounceMs`, default 500. */
-  private remoteDebounceMs;
+  readonly table: string;
+  readonly recordId: string;
+  readonly fieldName: string;
+  readonly kind: CrdtKind;
+  readonly cursorsEnabled: boolean;
+  private readonly doc;
+  private readonly host;
   private _onCursorUpdate;
   private pendingCursorUpdate;
-  /** Callback set by the editor to receive remote cursor updates.
-   *  Any cursor data that arrived before this callback was set will be replayed. */
-  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
-  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
-  /**
-   * @param LoroDocClass the `LoroDoc` constructor, injected by the caller after
-   *   awaiting {@link loadLoro} — keeps `loro-crdt` out of this module's static
-   *   import graph so it only ships to apps that use CRDT fields.
-   */
-  constructor(fieldName: string, cursorsEnabled: boolean, LoroDocClass: typeof LoroDoc, initialState?: Uint8Array, logger?: Logger$1 | null);
+  constructor(table: string, recordId: string, fieldName: string, kind: CrdtKind, cursorsEnabled: boolean, doc: LoroDoc, host: CrdtFieldHost);
   getDoc(): LoroDoc;
-  /** Whether the LoroDoc was loaded from saved CRDT state */
+  /** Whether the document holds anything yet (local state or edits). */
   hasContent(): boolean;
-  startSync(local: LocalStore, remote: RemoteDatabaseService, recordId: string, sessionId: string, debounceMs: number): void;
-  /**
-   * Stop syncing this field. Flushes one final remote push by default so the
-   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
-   * the remote session already belongs to the NEXT user, and pushing this
-   * (previous user's) snapshot under it would clobber the record remotely.
-   */
-  stopSync(options?: {
-    flush?: boolean;
-  }): void;
-  importRemote(state: Uint8Array): void;
-  exportSnapshot(): Uint8Array;
-  /** Push this session's cursor blob into the parent row at
-   *  `<field>.cursors[$sid]`. No-op when cursors aren't enabled on this
-   *  field — the editor still calls this method optimistically, but
-   *  without `@cursor` on the schema there's nowhere to store the blob.
-   *  The UPDATE itself fires the parent table's LIVE feed, so other
-   *  browsers receive the cursor change without a separate `_00_rv` bump. */
-  pushCursorState(encoded: Uint8Array): Promise<void>;
-  /** Import remote cursor state (called by CrdtManager from LIVE SELECT) */
-  importRemoteCursor(base64State: string): void;
-  private scheduleRemotePush;
-  /** SET path inside a parent row for the current snapshot. `@crdt`-only
-   *  fields hold the snapshot directly (`<field>`); `@crdt @cursor`
-   *  fields hold a `{ state, cursors }` object so the snapshot lives at
-   *  `<field>.state` next to per-session cursor blobs. */
-  private statePath;
-  /** Mirror the LoroDoc snapshot into the parent row locally. Runs on
-   *  every local update and every remote import so reloads (online or
-   *  offline) see the freshest content immediately. Failures are
-   *  swallowed — a stale local write must never block user input. */
-  private persistLocal;
-  private pushToRemote;
+  /** Publish this session's presence (an `EphemeralStore` encoding, e.g. the
+   *  editor's cursor). No-op unless the field is `@cursor`. */
+  pushCursorState(encoded: Uint8Array): void;
+  /** Called with every other session's presence blob. A blob that arrives
+   *  before the editor sets this is replayed when it does. */
+  set onCursorUpdate(cb: ((data: Uint8Array) => void) | null);
+  get onCursorUpdate(): ((data: Uint8Array) => void) | null;
+  /** @internal Deliver one remote presence blob. */
+  deliverPresence(data: Uint8Array): void;
 }
 //#endregion
 //#region src/modules/crdt/index.d.ts
 /**
- * CrdtManager manages active CrdtField instances and their sync channels.
+ * Collaborative (`@crdt`) fields.
  *
- * Collaborative state lives in two dedicated tables (defined in
- * `apps/cli/src/meta_tables_remote.surql`):
- *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
- *   - `_00_cursor` { record_id, session_id, field, state } — one row per
- *                    (record, session, field)
+ * Each open field is a Loro document. The client never sends the document,
+ * only its own edits: every batch of local edits becomes one row of the
+ * generated `<table>__crdt_log` table, written through the ordinary outbox
+ * (so it survives offline, reloads and retries), and every client receives
+ * the other rows through an ordinary query and merges them. Nobody writes the
+ * canonical state but the SSP, which folds the log into `_00_crdt_doc` and the
+ * parent field's plain text (see `packages/ssp-node/src/crdt`).
  *
- * Splitting them off the parent row is what makes offline edits mergeable:
- * each (record, field) gets its own row, so concurrent offline writes don't
- * collide on the parent's last-write-wins semantics.
+ * A row is imported only if it passes the acceptance rule the fold applies
+ * (`./acceptance`), so this tab and the server always hold the same ops.
  *
- * Cross-browser delivery still rides the parent table's existing LIVE feed
- * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
- * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
- * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
- * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
- * via subquery. Permission inheritance happens server-side via
- * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ * Edits carry this tab's Loro peer id, claimed for the signed-in user in
+ * `_00_crdt_peer` before the first row is sent; the database refuses a row
+ * whose peer its author does not own. A tab picks a fresh peer per session.
+ * Offline, edits stay local (and in the local snapshot) until the claim and
+ * the outbox can go through.
  */
+/** A followed query: stop following it, and know when the server answered. */
+interface Watch {
+  stop: () => void;
+  /** Resolves once the server's membership for the query is known and its
+   *  rows have landed locally (never rejects; may never resolve offline). */
+  settled: Promise<void>;
+}
+/** The runtime pieces the manager needs from the client facade. */
+interface CrdtPorts {
+  /** Register a query on `table` filtered by `where` and follow its rows. */
+  watch(table: string, where: Record<string, unknown>, onRows: (rows: Record<string, unknown>[]) => void): Promise<Watch>;
+  /** Optimistic create through the outbox. */
+  create(id: string, data: Record<string, unknown>): Promise<unknown>;
+}
 declare class CrdtManager {
   private schema;
   private local;
   private remote;
   private debounceMs;
-  private fields;
-  private liveByTable;
-  private pendingLive;
-  private staleTables;
-  private connectionGeneration;
-  private connectionUnsubscribes;
+  private sessions;
+  private opening;
+  private ports;
   private logger;
-  private sessionId;
+  private peer;
+  /** The current peer's claim: settled once the database holds it for us. */
+  private claim;
+  private claimRetry;
+  private connectionUnsubscribes;
   constructor(schema: SchemaStructure, local: LocalStore, remote: RemoteDatabaseService, logger: Logger$1, debounceMs?: number);
+  /** Hand over the runtime ports. Called once by the client facade. */
+  attach(ports: CrdtPorts): void;
   /**
-   * Re-establish table LIVEs after a socket drop.
-   *
-   * A LIVE subscription lives and dies with its WebSocket session, and
-   * `ensureTableSubscription` is memoized on `liveByTable` — so without this,
-   * the first reconnect leaves CRDT realtime permanently dead: the map still
-   * holds a uuid for a subscription the server has forgotten, so every later
-   * `open()` short-circuits and no LIVE is ever re-issued.
-   *
-   * Both drop events matter: the SDK publishes `reconnecting` (not
-   * `disconnected`) when it intends to recover on its own, and `disconnected`
-   * only once it has given up.
+   * A new signed-in identity (boot, sign-in, sign-out): edits from here on
+   * belong to it, under a peer it claims. Edits already made stay with the
+   * peer they were made under.
    */
-  private subscribeToReconnect;
-  /** Stop observing transport events. Separate from {@link closeAll}, which also
-   *  runs on a bucket switch where the manager keeps being used. */
+  setSessionId(_salt: string): void;
   dispose(): void;
-  private hasOpenFieldFor;
-  /** Set the session id that scopes this client's cursor entries. Must be
-   *  called before `open()` for cursors to be pushed under a stable key.
-   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
-   *  for the data-module salt). */
-  setSessionId(sessionId: string): void;
   /**
-   * Open a CRDT field for collaborative editing.
+   * Open a collaborative field. Every open of the same field shares one
+   * document; close each open with {@link close}.
    *
-   * @param table - Table name
-   * @param recordId - Full record ID (e.g., "thread:abc")
-   * @param field - Field name (e.g., "title", "content")
-   * @param fallbackText - Current plain text from the record, used to seed the
-   *                       LoroDoc if no CRDT state exists yet (migration path)
+   * `draft` (from {@link createDraft}) hands over edits made before the record
+   * existed: they are merged in and sent like this tab's own.
    */
-  open(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
-  close(table: string, recordId: string, field: string): void;
+  open(table: string, recordId: string, field: string, draft?: CrdtField): Promise<CrdtField>;
   /**
-   * Close every open field + table LIVE. Fields flush a final remote push by
-   * default; pass `{ flush: false }` on a bucket switch, where that flush
-   * would push the previous user's snapshot under the next user's session.
+   * A detached document for a field of a record that does not exist yet (a
+   * "new thread" form). Nothing is sent; pass it to {@link open} once the
+   * record is created and its edits become the record's first ones.
    */
+  createDraft(table: string, field: string): Promise<CrdtField>;
+  private adopt;
+  /** Close one open. The last close of a field resolves once its unsent
+   *  edits are in the outbox (or are left for a later session, offline). */
+  close(table: string, recordId: string, field: string): Promise<void>;
+  /** Close every field. `flush: false` (a bucket switch) drops unsent edits
+   *  from this session's memory; they stay in the local snapshot of the
+   *  bucket they belong to. */
   closeAll(options?: {
     flush?: boolean;
   }): void;
-  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
-   *  every open CrdtField on `table`. */
-  private ensureTableSubscription;
-  /** Apply a parent-row payload from a non-LIVE source (e.g. the
-   *  list_ref-driven sync engine, when the cross-user LIVE on the
-   *  parent table is filtered out by the SurrealDB cross-session
-   *  permission gap). Same semantics as the internal `dispatchRow`. */
-  applyRow(table: string, row: Record<string, unknown>): void;
-  /** Dispatch a parent-row LIVE event to every open CrdtField on that
-   *  record. Each open field reads its slice of the row directly — the
-   *  CRDT snapshot is a column on the parent now, so there is no
-   *  follow-up subquery. */
-  private dispatchRow;
-  /** One-shot remote fetch for a row whose CRDT field hasn't synced
-   *  locally yet (fresh device, memory-backed local DB after reload, …).
-   *  Used by `open()` when the local read came up empty. Subsequent
-   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
-  private fetchAndDispatchRow;
-  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
-   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
-  private fieldHasCursor;
-  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
-   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
-   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
-  private extractSnapshot;
-  private killTableSubscription;
-  private makeKey;
+  private fieldSpec;
+  private start;
+  private stop;
+  private ingest;
+  private tryImport;
+  private refetchCanonical;
+  private scheduleVerify;
   /**
-   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
-   * typos, removed annotations, and stale schema codegen at the call site instead
-   * of silently producing a non-CRDT writer.
+   * After a fold: compare this device's document with the one the server
+   * published, at the version the server published. Missing ops (rows this
+   * device never got before they were folded away) are repaired by merging
+   * the published snapshot in. The same ops giving a different state cannot
+   * be merged away; that is logged.
    */
-  private assertCrdtField;
+  private verify;
+  private scheduleFlush;
+  private flush;
+  /** Send every own peer's ops that are not in the outbox yet, one row per
+   *  peer. Only the peer's own ops travel (`updates-in-range`): a plain
+   *  `from: version` export would carry ops imported from others too, and
+   *  the acceptance rule refuses such a row. */
+  private sendOwnEdits;
+  private retryLater;
+  /** Claim this session's peer once; a failure (offline, signed out) is retried. */
+  private ensureClaimed;
+  private claimPeer;
+  private localId;
+  private readLocal;
+  private schedulePersist;
+  /** Save the merged document. Another tab may have saved too: merge with
+   *  its snapshot rather than overwrite it, and keep the further of the two
+   *  outbox marks per peer. */
+  private persist;
+  private pushPresence;
+  /** Presence is the latest state only: no outbox, no offline queue. */
+  private sendPresence;
+  /** Remove this session's cursor when the field closes; the server's TTL
+   *  sweep covers a tab that never gets here. */
+  private dropPresence;
+  private ingestPresence;
 }
 //#endregion
 //#region src/modules/feature-flag/index.d.ts
@@ -2114,8 +2114,15 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   clearFeatureOverrides(): void;
   getFeatureOverrides(): Record<string, FeatureFlagOverride>;
   appRelease(app: string, options?: AppReleaseOptions): AppReleaseHandle;
-  openCrdtField(table: string, recordId: string, field: string, fallbackText?: string): Promise<CrdtField>;
-  closeCrdtField(table: string, recordId: string, field: string): void;
+  /** Open a `@crdt` field for editing. `draft` (from {@link createCrdtDraft})
+   *  hands over edits made before the record existed. */
+  openCrdtField(table: string, recordId: string, field: string, draft?: CrdtField): Promise<CrdtField>;
+  /** A detached `@crdt` document for a record not created yet; see
+   *  {@link openCrdtField}. */
+  createCrdtDraft(table: string, field: string): Promise<CrdtField>;
+  /** Close a `@crdt` field. The last close resolves once its unsent edits
+   *  are queued in the outbox. */
+  closeCrdtField(table: string, recordId: string, field: string): Promise<void>;
   bucket<B extends BucketNames<S>>(name: B): BucketHandle;
   getBlobCacheStats(): BlobCacheStats;
 }
@@ -2153,17 +2160,5 @@ declare class LocalOpTimeoutError extends Error {
 /** Default deadline for one local-store operation. Generous: a cold 4k-row
  *  select on a throttled tab is seconds, not tens of seconds. */
 declare const DEFAULT_LOCAL_OP_TIMEOUT_MS = 30000;
-//#endregion
-//#region src/utils/index.d.ts
-declare function fileToUint8Array(file: File | Blob): Promise<Uint8Array>;
-/**
- * Convert plain text to simple HTML paragraphs.
- * Useful for seeding a rich-text editor (e.g. TipTap/ProseMirror) with fallback content.
- */
-declare function textToHtml(text: string): string;
-/**
- * Helper for retrying DB operations with exponential backoff
- */
-
 //#endregion
 export { ActiveImpersonation, AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, type BridgeSignOutMessage, type BridgeTokenMessage, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, IMPERSONATION_ACCESS, ImpersonationCandidate, ImpersonationInfo, ImpersonationTimerHost, ImpersonationTimers, InlineRow, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, ORIGIN_TOKEN_KEY, PUSH_ENDPOINT_KEY, PUSH_PAYLOAD_VERSION, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, type PushDeviceKind, type PushNotification, type PushNotificationAction, type PushOp, type PushPayload, type PushPayloadKind, type PushUrgency, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, SESSION_POLL_MS, SIGN_OUT_HOOK_TIMEOUT_MS, ServerViewMeta, SignOutContext, SignOutHook, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, TokenClaims, UpdateOptions, type WebPushClientMessage, type WebPushConfig, type WebPushDevice, WebPushError, type WebPushErrorCode, type WebPushInfo, type WebPushMessage, type WebPushMessageInput, WebPushModule, type WebPushSubscribeOptions, type WebPushSupport, type WebPushSyncOptions, type WebPushSyncStatus, type WebPushUnsubscribeOptions, type WebPushUnsupportedReason, type WebPushUpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, decodeTokenClaims, detectWebPushSupport, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, impersonationFromToken, isBlurhashValid, isImagePath, isPushPayload, renewDelayMs, sameImpersonation, semverGt, textToHtml };