@agent-native/core 0.211.0 → 0.212.0-nightly-20261021010049

package/dist/collab/ydoc-manager.d.ts

@@ -1,6 +1,7 @@
 import * as Y from "yjs";
-import type { DbExec } from "../db/client.js";
+import { type DbExec } from "../db/client.js";
 import { type PatchOp } from "./json-to-yjs.js";
+import { type LiveCopyBinding, type LiveCopyOutcome } from "./live-copy.js";
 export declare class CollabBaseVersionConflictError extends Error {
     constructor(message: string);
 }
@@ -16,9 +17,95 @@ export interface PreparedYDocMutationLease {
     persist(transaction: DbExec, textSnapshot: string): Promise<void>;
 }
 export declare function withPreparedYDocMutation<T>(docId: string, requestSource: string | undefined, run: (lease: PreparedYDocMutationLease) => Promise<T>): Promise<T>;
-export declare function getDocForWrite(docId: string): Promise<Y.Doc>;
+/** Refuses live copies with `read_refused`; read those with `readLiveCopy`. */
 export declare function getDoc(docId: string): Promise<Y.Doc>;
-export declare function applyUpdate(docId: string, update: Uint8Array, requestSource?: string): Promise<void>;
+/**
+ * Commits a client update. Once any live copy is defined, the result says
+ * whether the app's rows were derived from it; with none defined it is
+ * undefined, as before live copies existed.
+ */
+export declare function applyUpdate(docId: string, update: Uint8Array, requestSource?: string): Promise<LiveCopyOutcome | undefined>;
+export type LiveCopyRead = {
+    kind: "absent";
+} | {
+    kind: "unseeded";
+    version: number;
+    state: Uint8Array;
+} | {
+    kind: "live";
+    version: number;
+    state: Uint8Array;
+    text: string;
+};
+/**
+ * The stored live copy and derive(state). Absent (no row), unseeded (a row
+ * with nothing in the field, including a zero-byte state) and malformed
+ * (throws `malformed_state`) are never conflated.
+ */
+export declare function readLiveCopy(binding: LiveCopyBinding, docId: string): Promise<LiveCopyRead>;
+export interface MutateLiveCopyOptions {
+    /**
+     * The name of an edit in the runner's module
+     * (`defineLiveCopyTasks({ edits })`). It runs in the runner and is re-run
+     * against fresh state after each version conflict.
+     */
+    edit: string;
+    /** Passed to the edit. */
+    input?: unknown;
+    requestSource?: string;
+    maxAttempts?: number;
+    /**
+     * Writes this call's own rows (say, claiming the suggestion the edit
+     * applies) in the transaction that commits the edit, after the binding's
+     * persist and before `_collab_docs`, so they commit or roll back together.
+     * When the edit changes nothing it runs in a transaction of its own. A
+     * throw reaches the caller and nothing is published. Re-run on each
+     * version-conflict attempt.
+     */
+    persist?(tx: DbExec, change: LiveCopyCallChange): Promise<void>;
+}
+export interface LiveCopyCallChange {
+    changed: boolean;
+    /** The version this call leaves stored. */
+    version: number;
+    /** derive(state) at that version. */
+    text: string;
+}
+export interface LiveCopyMutationResult extends LiveCopyOutcome {
+    changed: boolean;
+    /** The stored version after the call; an unchanged edit leaves it as is. */
+    version: number;
+    state: Uint8Array;
+    /** derive(state). */
+    text: string;
+    /** What this call added to the state it edited. Empty when unchanged. */
+    update: Uint8Array;
+    attempts: number;
+}
+/**
+ * Applies a named edit to a seeded live copy and commits it with its derived
+ * text, retrying on `_collab_docs.version` conflicts. Throws `not_seeded`
+ * for an absent or unseeded copy; seed it with `seedLiveCopy` first.
+ */
+export declare function mutateLiveCopy(binding: LiveCopyBinding, docId: string, options: MutateLiveCopyOptions): Promise<LiveCopyMutationResult>;
+export interface SeedLiveCopyOptions {
+    /** Passed to the seed handler in the runner's module. */
+    source: string;
+    requestSource?: string;
+}
+export interface LiveCopySeedResult extends LiveCopyOutcome {
+    seeded: boolean;
+    version: number;
+    state: Uint8Array;
+    /** derive(state). */
+    text: string;
+}
+/**
+ * Seeds an absent or unseeded live copy from `source`. A live copy that
+ * already has content comes back unchanged with `seeded: false`; malformed
+ * stored state throws `malformed_state` and is never overwritten.
+ */
+export declare function seedLiveCopy(binding: LiveCopyBinding, docId: string, options: SeedLiveCopyOptions): Promise<LiveCopySeedResult>;
 export declare function seedXmlFragmentIfEmpty(docId: string, seedUpdate: Uint8Array, requestSource?: string): Promise<{
     seeded: boolean;
     state: Uint8Array;
@@ -39,4 +126,6 @@ export declare function applyJson(docId: string, newJson: any, fieldName?: strin
 export declare function applyPatchOps(docId: string, ops: PatchOp[], fieldName?: string, requestSource?: string): Promise<void>;
 export declare function getJson(docId: string, fieldName?: string): Promise<any>;
 export declare function seedFromJson(docId: string, json: any, fieldName?: string, type?: "map" | "array", client?: DbExec): Promise<void>;
+/** Overwrites a document's stored state and text. Refuses live copies. */
+export declare function saveYDocState(docId: string, state: Uint8Array, textSnapshot: string): Promise<void>;
 export declare function releaseDoc(docId: string): void;