@agent-native/core 0.211.0 → 0.211.1-nightly-20261020213022

package/dist/collab/live-copy-tasks.js

@@ -0,0 +1,330 @@
+import * as Y from "yjs";
+// The worker half of a live copy. Every Yjs operation on a live copy runs
+// here, inside a bounded task, and never on the request thread: integrating a
+// crafted update costs time quadratic in nesting depth (a 6,000-deep tree
+// takes seconds), and only a worker can be stopped when it overruns. Import
+// nothing here that a worker bundle cannot carry.
+export const LIVE_COPY_TASK = {
+    read: "liveCopy.read",
+    apply: "liveCopy.apply",
+    seed: "liveCopy.seed",
+    edit: "liveCopy.edit",
+};
+class TaskFailure extends Error {
+    code;
+    reason;
+    constructor(code, reason, message) {
+        super(message);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+function fail(code, reason, message) {
+    throw new TaskFailure(code, reason, message);
+}
+function isRefusal(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === "refused" &&
+        typeof value.reason === "string");
+}
+function describeRefusal(refusal) {
+    return `${refusal.reason}${refusal.detail ? ` (${refusal.detail})` : ""}`;
+}
+function hasLiveContent(type) {
+    for (let item = type._start; item !== null; item = item.right) {
+        if (!item.deleted)
+            return true;
+    }
+    for (const item of type._map.values()) {
+        if (!item.deleted)
+            return true;
+    }
+    return false;
+}
+function fieldHasContent(doc, field) {
+    const type = doc.share.get(field);
+    return type !== undefined && hasLiveContent(type);
+}
+/**
+ * Content outside the field would be invisible to derive, so the stored text
+ * would silently omit it. Refuse instead.
+ */
+function assertOnlyField(doc, field) {
+    const stray = [];
+    for (const [name, type] of doc.share) {
+        if (name !== field && hasLiveContent(type))
+            stray.push(name);
+    }
+    if (stray.length > 0) {
+        fail("unsupported_content", stray.join(","), `holds content outside "${field}": ${stray.join(", ")}`);
+    }
+}
+/**
+ * Yjs parks structs and deletions whose dependencies are missing instead of
+ * applying them; derive would never see them.
+ */
+function hasParked(doc) {
+    return doc.store.pendingStructs !== null || doc.store.pendingDs !== null;
+}
+function assertIntegrated(doc, what) {
+    if (hasParked(doc)) {
+        fail("malformed_state", "missing_dependencies", `the ${what} depends on changes it does not have`);
+    }
+}
+/**
+ * Applies a whole update and reports whether every byte was read.
+ * `Y.applyUpdate` stops after the delete set and ignores the rest, so junk
+ * after a valid prefix would pass as state. The reader is lib0's decoder
+ * shape, which Yjs reads structurally; lib0 is not a dependency of core.
+ */
+function readWhole(doc, bytes) {
+    const decoder = { arr: bytes, pos: 0 };
+    Y.readUpdate(decoder, doc, null);
+    return decoder.pos === bytes.length;
+}
+function catchUp(doc) {
+    const stateVector = Y.encodeStateVector(doc);
+    return { stateVector, deletions: Y.encodeStateAsUpdate(doc, stateVector) };
+}
+function load(state, field) {
+    const doc = new Y.Doc();
+    try {
+        if (state !== null && state.length > 0) {
+            let whole = false;
+            try {
+                whole = readWhole(doc, state);
+            }
+            catch {
+                whole = false;
+            }
+            if (!whole) {
+                fail("malformed_state", "yjs", "the stored state is not a Yjs update");
+            }
+            assertIntegrated(doc, "stored state");
+        }
+        assertOnlyField(doc, field);
+        return doc;
+    }
+    catch (error) {
+        doc.destroy();
+        throw error;
+    }
+}
+function watchChanges(doc) {
+    let changed = false;
+    const onUpdate = () => {
+        changed = true;
+    };
+    doc.on("update", onUpdate);
+    return {
+        changed: () => changed,
+        stop: () => doc.off("update", onUpdate),
+    };
+}
+function applyChange(doc, update, what) {
+    const watch = watchChanges(doc);
+    let whole = false;
+    try {
+        whole = readWhole(doc, update);
+    }
+    catch {
+        whole = false;
+    }
+    finally {
+        watch.stop();
+    }
+    if (!whole) {
+        fail("malformed_state", "update", `the ${what} is not a Yjs update`);
+    }
+    assertIntegrated(doc, what);
+    return watch.changed();
+}
+function encode(doc, maxStateBytes) {
+    const state = Y.encodeStateAsUpdate(doc);
+    if (state.length > maxStateBytes) {
+        fail("state_too_large", String(state.length), `would be ${state.length} bytes; the limit is ${maxStateBytes}`);
+    }
+    return state;
+}
+async function derive(handlers, doc, field) {
+    const watch = watchChanges(doc);
+    let output;
+    try {
+        output = await handlers.derive(doc, field);
+    }
+    finally {
+        watch.stop();
+    }
+    // An edit here would make the stored text describe a state never stored.
+    // Parking an update emits no update event, so check for that too.
+    if (watch.changed() || hasParked(doc)) {
+        fail("derive_failed", "derive_edited", "derive edited the document");
+    }
+    if (typeof output === "string")
+        return output;
+    if (isRefusal(output)) {
+        fail("derive_refused", output.reason, `cannot be derived: ${describeRefusal(output)}`);
+    }
+    fail("derive_failed", "invalid_output", "derive returned neither text nor a refusal");
+}
+async function build(what, run) {
+    const output = await run();
+    if (output === undefined)
+        return;
+    if (isRefusal(output)) {
+        fail("build_refused", output.reason, `${what} refused: ${describeRefusal(output)}`);
+    }
+    fail("build_failed", "invalid_output", `${what} returned something other than nothing or a refusal`);
+}
+function guarded(run) {
+    return async (input) => {
+        try {
+            return await run(input);
+        }
+        catch (error) {
+            if (error instanceof TaskFailure) {
+                return {
+                    kind: "failed",
+                    code: error.code,
+                    reason: error.reason,
+                    message: error.message,
+                };
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * The tasks a live copy's runner must host. Export the result as `tasks`
+ * from the module the runner bundles, alongside any tasks of your own.
+ */
+export function defineLiveCopyTasks(handlers) {
+    if (typeof handlers?.derive !== "function") {
+        throw new TypeError("defineLiveCopyTasks needs a derive(doc, field) handler");
+    }
+    const edits = handlers.edits ?? {};
+    return {
+        [LIVE_COPY_TASK.read]: guarded(async (input) => {
+            const doc = load(input.state, input.field);
+            try {
+                if (!fieldHasContent(doc, input.field)) {
+                    return { kind: "unseeded", ...catchUp(doc) };
+                }
+                if (!input.derive)
+                    return { kind: "live", ...catchUp(doc) };
+                return {
+                    kind: "live",
+                    ...catchUp(doc),
+                    text: await derive(handlers, doc, input.field),
+                };
+            }
+            finally {
+                doc.destroy();
+            }
+        }),
+        [LIVE_COPY_TASK.apply]: guarded(async (input) => {
+            const doc = load(input.state, input.field);
+            try {
+                if (!applyChange(doc, input.update, "update")) {
+                    return { kind: "unchanged" };
+                }
+                assertOnlyField(doc, input.field);
+                // An empty field reads as unseeded, and a seed would then write over
+                // what the user deleted. Editors always keep one block.
+                if (!fieldHasContent(doc, input.field)) {
+                    fail("unsupported_content", "empty", `the update would leave "${input.field}" empty`);
+                }
+                const state = encode(doc, input.maxStateBytes);
+                const caughtUp = catchUp(doc);
+                const text = await derive(handlers, doc, input.field);
+                return { kind: "changed", state, text, ...caughtUp };
+            }
+            finally {
+                doc.destroy();
+            }
+        }),
+        [LIVE_COPY_TASK.seed]: guarded(async (input) => {
+            const seed = handlers.seed;
+            if (typeof seed !== "function") {
+                fail("build_failed", "seed_unknown", "the task module defines no seed");
+            }
+            const doc = load(input.state, input.field);
+            try {
+                if (fieldHasContent(doc, input.field)) {
+                    return {
+                        kind: "live",
+                        ...catchUp(doc),
+                        text: await derive(handlers, doc, input.field),
+                    };
+                }
+                const seeded = new Y.Doc();
+                let seedUpdate;
+                try {
+                    await build("the seed", () => seed(seeded, input.field, input.source));
+                    assertIntegrated(seeded, "seed");
+                    seedUpdate = Y.encodeStateAsUpdate(seeded);
+                }
+                finally {
+                    seeded.destroy();
+                }
+                const before = Y.encodeStateVector(doc);
+                applyChange(doc, seedUpdate, "seed");
+                assertOnlyField(doc, input.field);
+                if (!fieldHasContent(doc, input.field)) {
+                    fail("build_refused", "empty", `the seed left "${input.field}" empty`);
+                }
+                const state = encode(doc, input.maxStateBytes);
+                const update = Y.encodeStateAsUpdate(doc, before);
+                const caughtUp = catchUp(doc);
+                const text = await derive(handlers, doc, input.field);
+                return { kind: "changed", state, text, update, ...caughtUp };
+            }
+            finally {
+                doc.destroy();
+            }
+        }),
+        [LIVE_COPY_TASK.edit]: guarded(async (input) => {
+            const edit = Object.prototype.hasOwnProperty.call(edits, input.edit)
+                ? edits[input.edit]
+                : undefined;
+            if (typeof edit !== "function") {
+                fail("build_failed", "edit_unknown", `the task module defines no edit named ${input.edit}`);
+            }
+            const doc = load(input.state, input.field);
+            try {
+                if (!fieldHasContent(doc, input.field)) {
+                    fail("not_seeded", "unseeded", "is unseeded; seed it before editing");
+                }
+                const before = Y.encodeStateVector(doc);
+                const watch = watchChanges(doc);
+                try {
+                    await build(`edit ${input.edit}`, () => edit(doc, input.field, input.input));
+                }
+                finally {
+                    watch.stop();
+                }
+                // An edit that applies an update can leave part of it parked.
+                assertIntegrated(doc, `edit ${input.edit}`);
+                if (!watch.changed()) {
+                    return {
+                        kind: "unchanged",
+                        text: await derive(handlers, doc, input.field),
+                    };
+                }
+                assertOnlyField(doc, input.field);
+                if (!fieldHasContent(doc, input.field)) {
+                    fail("build_refused", "empty", `edit ${input.edit} would leave "${input.field}" empty`);
+                }
+                const state = encode(doc, input.maxStateBytes);
+                const update = Y.encodeStateAsUpdate(doc, before);
+                const caughtUp = catchUp(doc);
+                const text = await derive(handlers, doc, input.field);
+                return { kind: "changed", state, text, update, ...caughtUp };
+            }
+            finally {
+                doc.destroy();
+            }
+        }),
+    };
+}

package/dist/collab/live-copy.d.ts

@@ -0,0 +1,188 @@
+import { type DbExec } from "../db/client.js";
+import { type BoundedTaskRunner } from "./bounded-tasks.js";
+import { type LiveCopyCatchUp } from "./live-copy-tasks.js";
+import { type YDocStamp } from "./storage.js";
+export declare const LIVE_COPY_DEFAULT_FIELD = "default";
+export type LiveCopyErrorCode = "not_live_copy" | "not_seeded" | "write_refused" | "read_refused" | "malformed_state" | "unsupported_content" | "state_too_large" | "derive_refused" | "derive_failed" | "build_refused" | "build_failed" | "version_conflict";
+export declare class LiveCopyError extends Error {
+    readonly code: LiveCopyErrorCode;
+    readonly docId: string;
+    /**
+     * Refusal reason from the task, the malformed-state reason, the bounded
+     * task error code, or the refused path, depending on `code`.
+     */
+    readonly reason?: string;
+    constructor(code: LiveCopyErrorCode, docId: string, message: string, options?: {
+        reason?: string;
+        cause?: unknown;
+    });
+}
+export interface LiveCopyCommit {
+    readonly docId: string;
+    readonly origin: "update" | "mutation" | "seed";
+    /** Null when this commit creates the `_collab_docs` row. */
+    readonly previousVersion: number | null;
+    readonly version: number;
+    readonly text: string;
+    readonly state: Uint8Array;
+    readonly requestSource?: string;
+}
+/**
+ * What `persist` reports. Returning nothing means the app's rows were
+ * derived; `derived: false` means it left them alone (say the document went
+ * back to its legacy writer), and the Yjs state still commits.
+ */
+export type LiveCopyPersistOutcome = {
+    derived: true;
+} | {
+    derived: false;
+    reason: string;
+};
+/**
+ * How a write left the app's derived rows. `unchanged` means nothing was
+ * committed, so persist did not run.
+ */
+export interface LiveCopyOutcome {
+    liveCopy: "derived" | "not_derived" | "unchanged";
+    liveCopyReason?: string;
+}
+export interface LiveCopyOptions {
+    /**
+     * Stable identity. Defining a binding under the same name again, as a dev
+     * server does when it evaluates the app's module again, replaces the old
+     * one.
+     */
+    name: string;
+    /** Which collab documents are live copies. Checked on every write. */
+    appliesTo(docId: string): boolean | Promise<boolean>;
+    /**
+     * Hosts the live-copy tasks: its module exports
+     * `tasks = defineLiveCopyTasks({ derive, seed, edits })`.
+     */
+    runner: BoundedTaskRunner;
+    /** The one root type a live copy may hold. Default "default". */
+    field?: string;
+    /** Encoded state above this is refused. Default 4 MiB. */
+    maxStateBytes?: number;
+    /**
+     * Writes to one document allowed to wait while another commits. Beyond
+     * this, a write fails with `build_failed` / `queue_full` instead of
+     * holding its payload until its turn. Default 16.
+     */
+    maxWaitingWrites?: number;
+    /**
+     * Writes the app's derived stores inside the commit transaction. It runs
+     * before core updates `_collab_docs`, so app row locks are always taken
+     * first. A throw rolls the commit back and reaches the caller unchanged.
+     * It may run more than once per write when a version conflict retries.
+     * It runs in the caller's async context, and `getDbExec()` inside it is
+     * `tx`; a Drizzle `getDb()` handle is not, so query through `tx`.
+     */
+    persist?(tx: DbExec, commit: LiveCopyCommit): Promise<void | LiveCopyPersistOutcome>;
+}
+export interface LiveCopyBinding {
+    readonly name: string;
+    readonly appliesTo: (docId: string) => boolean | Promise<boolean>;
+    readonly runner: BoundedTaskRunner;
+    readonly field: string;
+    readonly maxStateBytes: number;
+    readonly maxWaitingWrites: number;
+    readonly persist?: (tx: DbExec, commit: LiveCopyCommit) => Promise<void | LiveCopyPersistOutcome>;
+}
+/**
+ * Declares which collab documents are live copies and how their text is
+ * derived. While a binding exists, core's other write paths (text, JSON,
+ * search-replace, prepared mutations, and the text/JSON/XML seeders) refuse
+ * documents it covers.
+ */
+export declare function defineLiveCopy(options: LiveCopyOptions): LiveCopyBinding;
+/** Synchronous, so a caller can keep main's behavior when none is defined. */
+export declare function liveCopiesDefined(): boolean;
+/**
+ * Removes a binding so its documents take ordinary collab writes again. A
+ * binding already replaced under its name leaves the replacement in place.
+ */
+export declare function releaseLiveCopy(binding: LiveCopyBinding): void;
+export declare function liveCopyBindingFor(docId: string): Promise<LiveCopyBinding | null>;
+/**
+ * Throws `write_refused` when a live copy covers `docId`. With no binding
+ * defined it returns synchronously, so a write that has not taken its lock
+ * yet keeps its place in line.
+ */
+export declare function refuseLiveCopyWrite(docId: string, path: string): Promise<void> | undefined;
+export declare function liveCopyWriteRefused(docId: string, path: string): LiveCopyError;
+export declare function assertLiveCopy(binding: LiveCopyBinding, docId: string): Promise<void>;
+/** Throws unless `binding` is still the one registered under its name. */
+export declare function assertActiveLiveCopy(binding: LiveCopyBinding, docId: string): void;
+/**
+ * A commit updates this instance's cache and notifies connected editors as
+ * soon as it lands, so it must own its transaction: inside a caller's, a
+ * later rollback would leave editors holding state that was never saved.
+ */
+export declare function assertOwnTransaction(docId: string, path: string): void;
+export type StoredLiveCopy = {
+    kind: "absent";
+} | {
+    kind: "stored";
+    state: Uint8Array;
+    version: number;
+    digest: string;
+};
+/**
+ * The stored bytes, read strictly: unreadable base64 or a bad version throws
+ * `malformed_state` instead of reading as empty. The bytes are not decoded
+ * as Yjs here; the tasks do that in the runner.
+ */
+export declare function readStoredLiveCopy(binding: LiveCopyBinding, client: DbExec, docId: string): Promise<StoredLiveCopy>;
+export interface LiveCopyChange {
+    kind: "changed";
+    state: Uint8Array;
+    text: string;
+    /** What this change added to the state it started from. */
+    update: Uint8Array;
+    catchUp: LiveCopyCatchUp;
+}
+/** Validates stored state in the runner; derives its text when asked. */
+export declare function readLiveCopyState(binding: LiveCopyBinding, docId: string, state: Uint8Array, derive: boolean): Promise<{
+    kind: "unseeded";
+    catchUp: LiveCopyCatchUp;
+} | {
+    kind: "live";
+    text: string | null;
+    catchUp: LiveCopyCatchUp;
+}>;
+/** Merges a client update in the runner; null state means absent. */
+export declare function applyLiveCopyUpdate(binding: LiveCopyBinding, docId: string, state: Uint8Array | null, update: Uint8Array): Promise<{
+    kind: "unchanged";
+} | {
+    kind: "changed";
+    state: Uint8Array;
+    text: string;
+    catchUp: LiveCopyCatchUp;
+}>;
+/** Seeds an absent or unseeded copy; a live one comes back with its text. */
+export declare function seedLiveCopyState(binding: LiveCopyBinding, docId: string, state: Uint8Array | null, source: string): Promise<{
+    kind: "live";
+    text: string;
+} | LiveCopyChange>;
+/** Runs a named edit from the runner's module on seeded state. */
+export declare function editLiveCopyState(binding: LiveCopyBinding, docId: string, state: Uint8Array, edit: string, editInput: unknown): Promise<{
+    kind: "unchanged";
+    text: string;
+} | LiveCopyChange>;
+/** A caller's own write, added to the transaction of one live-copy write. */
+export type LiveCopyCallPersist = (tx: DbExec) => Promise<void>;
+export declare function sameStamp(a: YDocStamp | null, b: YDocStamp | null): boolean;
+/**
+ * Commits a derived state: the binding's persist hook, the caller's, then
+ * the `_collab_docs` write, in one transaction, at the row `base` names
+ * (null: no row). Returns null when another writer changed the row first;
+ * nothing is written in that case.
+ */
+export declare function commitLiveCopy(binding: LiveCopyBinding, commit: LiveCopyCommit, base: YDocStamp | null, callPersist?: LiveCopyCallPersist): Promise<LiveCopyOutcome | null>;
+/**
+ * Runs a caller's persist by itself, for a write that committed nothing,
+ * while the copy is still the row `base` names. Returns false, with nothing
+ * written, when another writer changed it first.
+ */
+export declare function persistLiveCopyCall(binding: LiveCopyBinding, docId: string, base: YDocStamp, callPersist: LiveCopyCallPersist): Promise<boolean>;