@graview/core 0.1.57 → 0.1.59

package/dist/sync/engine.d.ts

@@ -1,6 +1,7 @@
 import type { PlannedChange, Store } from "../store.js";
 import type { AnySchema } from "../schema/schema.js";
-import { type ConflictPolicy, type RemoteSystem, type RemoteWrite, type SyncConflict, type SyncMapping, type SyncState } from "./types.js";
+import type { MutationCall } from "../mutations/types.js";
+import { type ConflictPolicy, type LinkResolver, type RemoteSystem, type RemoteWrite, type SyncConflict, type SyncMapping, type SyncState } from "./types.js";
 /** A conflict the engine's policy settled, and the side it took. */
 export type SettledConflict = SyncConflict & {
     readonly took: "ours" | "theirs";
@@ -41,6 +42,12 @@ export interface SyncReport {
     /** Records the remote deleted: removed here through `removeInbound`, or, without one, kept here and no longer synced. */
     readonly gone: readonly string[];
     readonly offline: boolean;
+    /**
+     * What the remote said when it could not be reached, in its transport's
+     * words — a secret it refused, a database not shared — so a host says
+     * why rather than only that. Absent when the run reached it.
+     */
+    readonly problem?: string;
     readonly state: SyncState;
 }
 /**
@@ -58,6 +65,8 @@ export interface SyncRefusal {
     readonly id?: string;
 }
 export type { SyncConflict } from "./types.js";
+/** A relation's value as both sides compare it: the remote ids it reaches, once each, sorted; none is `null`. */
+export declare function edgeValue(ids: unknown): string[] | null;
 export interface SyncOptions<S extends AnySchema> {
     readonly store: Store<S>;
     readonly mapping: SyncMapping;
@@ -110,7 +119,43 @@ export interface SyncOptions<S extends AnySchema> {
         readonly name: string;
         readonly args: Record<string, unknown>;
     } | null;
+    /**
+     * WHERE A RECORD A RELATION REACHES IS FOUND, by either id: every engine
+     * of the app when its relations reach records another engine keeps
+     * (`syncLinks`). Absent: this engine's own links.
+     */
+    readonly links?: LinkResolver;
+    /** The act that links a record to another, for a relation the remote linked (`connect-<kind>-<edge>`). Required for a mapping with `edges`. */
+    connectInbound?(call: {
+        readonly localId: string;
+        readonly kind: string;
+        readonly edge: string;
+        readonly to: string;
+    }): MutationCall | null;
+    /** The act that unlinks them, for a link the remote took away (`disconnect-<kind>-<edge>`). Absent: the link stays here. */
+    disconnectInbound?(call: {
+        readonly localId: string;
+        readonly kind: string;
+        readonly edge: string;
+        readonly to: string;
+    }): MutationCall | null;
 }
+/**
+ * ONE PLACE TO FIND A RECORD BY EITHER ID, over every engine added to it:
+ * what an app's engines share when their relations reach each other's
+ * records (one Notion connection per table, each table's relations to
+ * another's pages). Read live, so a record another engine linked a moment
+ * ago is found; an id is matched as written, then as Notion writes one
+ * (hyphenated, lower case).
+ */
+export interface SharedLinks extends LinkResolver {
+    /** Adds an engine whose links are looked in. */
+    add(engine: {
+        linkOf(localId: string): string | undefined;
+        linkedTo(id: string): string | undefined;
+    }): void;
+}
+export declare function sharedLinks(): SharedLinks;
 /**
  * Two-way sync, on top of the op log rather than beside it.
  *
@@ -131,6 +176,8 @@ export interface SyncOptions<S extends AnySchema> {
 export declare class SyncEngine<S extends AnySchema> {
     private state;
     private readonly options;
+    private readonly resolver;
+    private reverse?;
     constructor(options: SyncOptions<S>, state?: SyncState);
     get snapshot(): SyncState;
     private get policy();
@@ -143,6 +190,41 @@ export declare class SyncEngine<S extends AnySchema> {
      * an act is even offered.
      */
     refuses(kind: string): string | undefined;
+    /** The remote's id of a record this engine linked. */
+    linkOf(localId: string): string | undefined;
+    /** Our id of the remote's record, if this engine linked it. */
+    linkedTo(id: string): string | undefined;
+    /**
+     * A NODE'S VALUES AS THE REMOTE IS COMPARED WITH: its mapped fields, and
+     * each mapped relation as the remote ids of the records it reaches — those
+     * linked, and those held until they are — sorted. A record it reaches that
+     * no engine has linked yet (made here, not sent) is not in it until it is.
+     */
+    private valuesOf;
+    /**
+     * THE ACTS ONE CHANGE COMING IN LANDS THROUGH, in one batch: the record
+     * made (`create`) or its fields edited (`applyInbound`), then each of its
+     * relations brought to what the remote says — links it lost taken away
+     * first, so a relation of one is never refused for holding two — and the
+     * remote ids no engine has linked yet, to hold.
+     */
+    private inboundCalls;
+    /** Keeps what a landed change left to link, by our id and edge. */
+    private hold;
+    /**
+     * LANDS ONE CHANGE COMING IN through its acts, authored by the remote's
+     * system, and holds the links it could not make yet. Undefined when this
+     * store refused it (said in `refused`, or thrown without it).
+     */
+    private landInbound;
+    /**
+     * LINKS WHAT WAS HELD, now that its records are linked — by this engine
+     * or another of the app's. Nothing is sent for it: the relation's value
+     * already held those ids. A host running several engines calls this on
+     * each after a pass, so the order they ran in does not matter; `run`
+     * calls it too. Returns the records it linked.
+     */
+    resolveHeld(refused?: SyncRefusal[]): string[];
     /** Every node that participates in the sync, by our id. */
     private participants;
     /** A link for every participant whose mapping names its version field and that carries one. */

package/dist/sync/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/sync/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/sync/engine.ts"],"names":[],"mappings":"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"}

package/dist/sync/engine.js

@@ -3,6 +3,13 @@ import { PermissionDeniedError } from "../permissions/types.js";
 import { seesId } from "../seen.js";
 import { NewerFormatError } from "../format-error.js";
 import { EMPTY_SYNC_STATE, SYNC_STATE_FORMAT, systemAuthor, } from "./types.js";
+/** Everything a mapping keeps in step, its fields and its relations: ours → theirs. */
+const keptOf = (mapping) => (mapping.edges ? { ...mapping.fields, ...mapping.edges } : mapping.fields);
+/** A relation's value as both sides compare it: the remote ids it reaches, once each, sorted; none is `null`. */
+export function edgeValue(ids) {
+    const list = Array.isArray(ids) ? [...new Set(ids.filter((id) => typeof id === "string" && id !== ""))].sort() : typeof ids === "string" && ids !== "" ? [ids] : [];
+    return list.length > 0 ? list : null;
+}
 /** Reads a node's mapped values, in OUR field names. */
 function mappedValues(node, mapping) {
     const values = {};
@@ -19,19 +26,20 @@ function mappedValues(node, mapping) {
  */
 function ourFields(remote, mapping, all = false) {
     const values = {};
-    for (const [ours, theirs] of Object.entries(mapping.fields)) {
+    for (const [ours, theirs] of Object.entries(keptOf(mapping))) {
         if (!all && mapping.ours?.includes(ours))
             continue;
         if (!(theirs in remote))
             continue;
         const decode = mapping.decode?.[ours];
-        values[ours] = decode ? decode(remote[theirs]) : remote[theirs];
+        const value = decode ? decode(remote[theirs]) : remote[theirs];
+        values[ours] = mapping.edges && ours in mapping.edges ? edgeValue(value) : value;
     }
     return values;
 }
 function remoteFields(values, mapping, node = values) {
     const out = {};
-    for (const [ours, theirs] of Object.entries(mapping.fields)) {
+    for (const [ours, theirs] of Object.entries(keptOf(mapping))) {
         if (!(ours in values))
             continue;
         const encode = mapping.encode?.[ours];
@@ -43,6 +51,36 @@ const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
 /** Where a conflict is held: by node and field, and a record deleted here by node alone. */
 const heldKey = (localId, field = "") => `${localId}\u0000${field}`;
 const keyOf = (conflict) => heldKey(conflict.localId, conflict.field);
+const hyphenated = (id) => {
+    const hex = id.replace(/-/g, "").toLowerCase();
+    return /^[0-9a-f]{32}$/.test(hex) ? `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` : undefined;
+};
+export function sharedLinks() {
+    const engines = [];
+    const find = (id) => {
+        for (const engine of engines) {
+            const found = engine.linkedTo(id);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return {
+        add: (engine) => void (engines.includes(engine) || engines.push(engine)),
+        remoteId(localId) {
+            for (const engine of engines) {
+                const found = engine.linkOf(localId);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        },
+        localId(id) {
+            const other = hyphenated(id);
+            return find(id) ?? (other && other !== id ? find(other) : undefined);
+        },
+    };
+}
 /**
  * Two-way sync, on top of the op log rather than beside it.
  *
@@ -63,8 +101,11 @@ const keyOf = (conflict) => heldKey(conflict.localId, conflict.field);
 export class SyncEngine {
     state;
     options;
+    resolver;
+    reverse;
     constructor(options, state = EMPTY_SYNC_STATE) {
         this.options = options;
+        this.resolver = options.links ?? { remoteId: (localId) => this.linkOf(localId), localId: (id) => this.linkedTo(id) };
         // A state a newer build wrote is not run on: its links may say what this build would misread (stability.md §2).
         const format = state.format ?? 1;
         if (!(format <= SYNC_STATE_FORMAT))
@@ -99,6 +140,165 @@ export class SyncEngine {
         const mapping = this.options.mapping.resources.find((resource) => resource.kind === kind);
         return mapping?.readonly ? this.because(mapping) : undefined;
     }
+    /** The remote's id of a record this engine linked. */
+    linkOf(localId) {
+        return this.state?.links[localId]?.id;
+    }
+    /** Our id of the remote's record, if this engine linked it. */
+    linkedTo(id) {
+        const links = this.state?.links;
+        if (!links)
+            return undefined;
+        if (this.reverse?.links !== links)
+            this.reverse = { links, byId: new Map(Object.entries(links).map(([localId, link]) => [link.id, localId])) };
+        return this.reverse.byId.get(id);
+    }
+    /**
+     * A NODE'S VALUES AS THE REMOTE IS COMPARED WITH: its mapped fields, and
+     * each mapped relation as the remote ids of the records it reaches — those
+     * linked, and those held until they are — sorted. A record it reaches that
+     * no engine has linked yet (made here, not sent) is not in it until it is.
+     */
+    valuesOf(node, mapping) {
+        const values = mappedValues(node, mapping);
+        if (!mapping.edges)
+            return values;
+        const id = node["id"];
+        const held = this.state?.unresolved?.[id];
+        for (const edge of Object.keys(mapping.edges)) {
+            const reached = this.options.store.graph.out(id, edge, { archived: "all" }).map((target) => this.resolver.remoteId(target.id));
+            values[edge] = edgeValue([...reached, ...(held?.[edge] ?? [])]);
+        }
+        return values;
+    }
+    /**
+     * THE ACTS ONE CHANGE COMING IN LANDS THROUGH, in one batch: the record
+     * made (`create`) or its fields edited (`applyInbound`), then each of its
+     * relations brought to what the remote says — links it lost taken away
+     * first, so a relation of one is never refused for holding two — and the
+     * remote ids no engine has linked yet, to hold.
+     */
+    inboundCalls(inbound) {
+        const { localId, mapping, values, create } = inbound;
+        const edges = mapping.edges ?? {};
+        const fields = Object.fromEntries(Object.entries(values).filter(([key]) => !(key in edges)));
+        const calls = [];
+        if (create)
+            calls.push(create);
+        else if (Object.keys(fields).length > 0)
+            calls.push(this.options.applyInbound({ localId, kind: mapping.kind, fields }));
+        const held = {};
+        const graph = this.options.store.graph;
+        for (const edge of Object.keys(edges)) {
+            if (!(edge in values))
+                continue;
+            const wanted = edgeValue(values[edge]) ?? [];
+            const reach = [];
+            held[edge] = [];
+            for (const id of wanted) {
+                const target = this.resolver.localId(id);
+                if (target === undefined)
+                    held[edge].push(id);
+                // Linked, and gone here: its delete is on its way there, and the link with it.
+                else if (graph.getNode(target))
+                    reach.push(target);
+            }
+            const now = create ? [] : graph.out(localId, edge, { archived: "all" }).map((target) => target.id);
+            const about = { localId, kind: mapping.kind, edge };
+            // A link to a record the remote has never seen (made here, not sent yet) is not the remote's to take away.
+            for (const to of now) {
+                if (reach.includes(to) || this.resolver.remoteId(to) === undefined)
+                    continue;
+                const call = this.options.disconnectInbound?.({ ...about, to });
+                if (call)
+                    calls.push(call);
+            }
+            for (const to of reach) {
+                if (now.includes(to))
+                    continue;
+                const call = this.options.connectInbound?.({ ...about, to });
+                if (call)
+                    calls.push(call);
+            }
+        }
+        return { calls, held };
+    }
+    /** Keeps what a landed change left to link, by our id and edge. */
+    hold(localId, held) {
+        if (Object.keys(held).length === 0)
+            return;
+        const was = this.state.unresolved ?? {};
+        const mine = { ...was[localId], ...held };
+        for (const edge of Object.keys(mine))
+            if (mine[edge].length === 0)
+                delete mine[edge];
+        const { [localId]: _was, ...rest } = was;
+        const unresolved = Object.keys(mine).length > 0 ? { ...rest, [localId]: mine } : rest;
+        const { unresolved: _before, ...state } = this.state;
+        this.state = { ...state, ...(Object.keys(unresolved).length > 0 ? { unresolved } : {}) };
+    }
+    /**
+     * LANDS ONE CHANGE COMING IN through its acts, authored by the remote's
+     * system, and holds the links it could not make yet. Undefined when this
+     * store refused it (said in `refused`, or thrown without it).
+     */
+    landInbound(inbound, intent, about, refused) {
+        const { calls, held } = this.inboundCalls(inbound);
+        if (calls.length === 0) {
+            this.hold(inbound.localId, held);
+            return {};
+        }
+        const result = this.land(calls, intent, about, refused);
+        if (!result)
+            return undefined;
+        this.hold(inbound.localId, held);
+        return { result };
+    }
+    /**
+     * LINKS WHAT WAS HELD, now that its records are linked — by this engine
+     * or another of the app's. Nothing is sent for it: the relation's value
+     * already held those ids. A host running several engines calls this on
+     * each after a pass, so the order they ran in does not matter; `run`
+     * calls it too. Returns the records it linked.
+     */
+    resolveHeld(refused) {
+        const unresolved = this.state.unresolved;
+        if (!unresolved)
+            return [];
+        const graph = this.options.store.graph;
+        const linked = [];
+        for (const [localId, edges] of Object.entries(unresolved)) {
+            const node = graph.getNode(localId);
+            const mapping = node ? this.mappingFor(node["kind"]) : undefined;
+            if (!node || !mapping?.edges) {
+                this.hold(localId, Object.fromEntries(Object.keys(edges).map((edge) => [edge, []])));
+                continue;
+            }
+            const calls = [];
+            const still = {};
+            for (const [edge, ids] of Object.entries(edges)) {
+                still[edge] = [];
+                for (const id of ids) {
+                    const to = this.resolver.localId(id);
+                    if (to === undefined) {
+                        still[edge].push(id);
+                        continue;
+                    }
+                    if (!graph.getNode(to) || graph.out(localId, edge, { archived: "all" }).some((target) => target.id === to))
+                        continue;
+                    const call = this.options.connectInbound?.({ localId, kind: mapping.kind, edge, to });
+                    if (call)
+                        calls.push(call);
+                }
+            }
+            if (calls.length > 0 && !this.land(calls, `${this.options.mapping.system}: linked`, { localId, resource: mapping.resource, id: this.linkOf(localId) ?? "" }, refused))
+                continue;
+            this.hold(localId, still);
+            if (calls.length > 0)
+                linked.push(localId);
+        }
+        return linked;
+    }
     /** Every node that participates in the sync, by our id. */
     participants() {
         const graph = this.options.store.graph;
@@ -230,7 +430,7 @@ export class SyncEngine {
                  * BACK HERE (the delete taken back): what it holds against what the
                  * remote made of it is held field by field, never sent over the edit.
                  */
-                const ours = mappedValues(node, mapping);
+                const ours = this.valuesOf(node, mapping);
                 for (const [field, theirs] of Object.entries(conflict.theirs)) {
                     if (same(ours[field], theirs))
                         links = { ...links, [conflict.localId]: { ...links[conflict.localId], fields: { ...links[conflict.localId].fields, [field]: theirs } } };
@@ -240,7 +440,7 @@ export class SyncEngine {
                 changed = true;
                 continue;
             }
-            if (!node || conflict.deleted || !same(mappedValues(node, mapping)[conflict.field], conflict.theirs)) {
+            if (!node || conflict.deleted || !same(this.valuesOf(node, mapping)[conflict.field], conflict.theirs)) {
                 still.set(keyOf(conflict), conflict);
                 continue;
             }
@@ -272,7 +472,7 @@ export class SyncEngine {
             if (mapping.readonly || gone.has(localId))
                 continue;
             const link = this.state.links[localId];
-            const values = mappedValues(node, mapping);
+            const values = this.valuesOf(node, mapping);
             if (!link) {
                 writes.push({
                     resource: mapping.resource,
@@ -320,8 +520,10 @@ export class SyncEngine {
         const held = this.held();
         const policy = this.policy;
         let offline = false;
+        let problem;
         let links = { ...this.state.links };
         let cursor = this.state.cursor;
+        const skipped = { ...this.state.skipped };
         /*
          * A HELD FIELD ONLY THE REMOTE CHANGED is no conflict: ours is back at
          * the value both last agreed — a delete taken back leaves it there, or
@@ -333,15 +535,14 @@ export class SyncEngine {
             const node = this.options.store.graph.getNode(conflict.localId);
             const link = links[conflict.localId];
             const mapping = link && this.mappingFor(link.resource);
-            if ("deleted" in conflict || !node || !mapping || !same(mappedValues(node, mapping)[conflict.field], conflict.base))
+            if ("deleted" in conflict || !node || !mapping || !same(this.valuesOf(node, mapping)[conflict.field], conflict.base))
                 continue;
             landing.set(conflict.localId, { ...landing.get(conflict.localId), [conflict.field]: conflict.theirs });
             held.delete(key);
         }
         for (const [localId, fields] of landing) {
             const link = links[localId];
-            const call = this.options.applyInbound({ localId, kind: this.mappingFor(link.resource).kind, fields });
-            if (!this.land(call, `${this.options.mapping.system}: ${Object.keys(fields).join(", ")}`, { localId, resource: link.resource, id: link.id }, refused))
+            if (!this.landInbound({ localId, mapping: this.mappingFor(link.resource), values: fields }, `${this.options.mapping.system}: ${Object.keys(fields).join(", ")}`, { localId, resource: link.resource, id: link.id }, refused))
                 continue;
             links[localId] = { ...link, fields: { ...link.fields, ...fields } };
             applied.push(localId);
@@ -368,9 +569,19 @@ export class SyncEngine {
                     continue;
                 }
                 if (!localId) {
+                    const remoteKey = `${change.resource}:${change.id}`;
                     // A deletion of a record we never had is not news: a first full
                     // pull lists every canceled event the remote remembers.
-                    if (change.deleted)
+                    if (change.deleted) {
+                        delete skipped[remoteKey];
+                        continue;
+                    }
+                    /*
+                     * REFUSED ONCE, AS IT STANDS. A record there this store would not
+                     * make (a blank row) is said once, then left until it changes
+                     * there: refused on every pass, it was the same line every 30 s.
+                     */
+                    if (skipped[remoteKey] === change.version)
                         continue;
                     const created = this.options.createInbound?.({
                         resource: change.resource,
@@ -379,17 +590,25 @@ export class SyncEngine {
                     });
                     if (!created)
                         continue;
-                    const result2 = this.land(created, `${this.options.mapping.system}: new ${change.resource}`, { localId: String(created.args["id"] ?? ""), resource: change.resource, id: change.id }, refused);
-                    if (!result2)
+                    const values = ourFields(change.fields ?? {}, mapping);
+                    const madeAs = String(created.args["id"] ?? "");
+                    // Its links are made in the same batch, which needs the id it is made with; without one, they wait for the next pass.
+                    const landed = madeAs
+                        ? this.landInbound({ localId: madeAs, mapping, values, create: created }, `${this.options.mapping.system}: new ${change.resource}`, { localId: madeAs, resource: change.resource, id: change.id }, refused)?.result
+                        : this.land(created, `${this.options.mapping.system}: new ${change.resource}`, { localId: "", resource: change.resource, id: change.id }, refused);
+                    if (!landed) {
+                        skipped[remoteKey] = change.version;
                         continue;
-                    const madeId = String(created.args["id"] ?? result2.writes[0] ?? "");
+                    }
+                    delete skipped[remoteKey];
+                    const madeId = String(created.args["id"] ?? landed.writes[0] ?? "");
                     if (madeId) {
                         applied.push(madeId);
                         links[madeId] = {
                             resource: change.resource,
                             id: change.id,
                             version: change.version,
-                            fields: ourFields(change.fields ?? {}, mapping),
+                            fields: values,
                         };
                     }
                     continue;
@@ -446,7 +665,7 @@ export class SyncEngine {
                     continue;
                 }
                 const theirs = ourFields(change.fields ?? {}, mapping);
-                const ours = mappedValues(node, mapping);
+                const ours = this.valuesOf(node, mapping);
                 /*
                  * Field by field: what lands, what both sides now agree on, and what
                  * is contested — both changed since the version we last agreed on,
@@ -488,11 +707,12 @@ export class SyncEngine {
                     agreed[field] = value;
                 }
                 if (Object.keys(lands).length > 0) {
-                    const call = this.options.applyInbound({ localId, kind: mapping.kind, fields: lands });
                     // Refused here, the link keeps what was last agreed, so the field is still news on the next change there.
-                    if (!this.land(call, `${this.options.mapping.system}: ${Object.keys(lands).join(", ")}`, { localId, resource: change.resource, id: change.id }, refused))
+                    const landed = this.landInbound({ localId, mapping, values: lands }, `${this.options.mapping.system}: ${Object.keys(lands).join(", ")}`, { localId, resource: change.resource, id: change.id }, refused);
+                    if (!landed)
                         continue;
-                    applied.push(localId);
+                    if (landed.result)
+                        applied.push(localId);
                 }
                 links[localId] = {
                     ...link,
@@ -503,7 +723,7 @@ export class SyncEngine {
                 };
             }
         }
-        catch {
+        catch (error) {
             /*
              * OFFLINE degrades to local-only. Only the remote throws this far: a
              * change this store refused is caught where it lands, and said in
@@ -514,11 +734,17 @@ export class SyncEngine {
              * asks for the same window again.
              */
             offline = true;
+            problem = error instanceof Error ? error.message : String(error);
         }
         // What the inbound pass decided is what the outbound pass sends from.
-        const { conflicts: _before, gone: _gone, ...kept } = this.state;
+        const { conflicts: _before, gone: _gone, skipped: _skipped, ...kept } = this.state;
         const unsynced = [...new Set([...(this.state.gone ?? []), ...gone])].filter((id) => this.options.store.graph.getNode(id));
-        this.state = { ...kept, links, ...this.heldState(held), ...(unsynced.length > 0 ? { gone: unsynced } : {}) };
+        this.state = { ...kept, links, ...this.heldState(held), ...(unsynced.length > 0 ? { gone: unsynced } : {}), ...(Object.keys(skipped).length > 0 ? { skipped } : {}) };
+        // What a relation reached that was not linked yet, linked now that this pull may have made it.
+        if (!offline)
+            for (const id of this.resolveHeld(refused))
+                if (!applied.includes(id))
+                    applied.push(id);
         /*
          * A RECORD THE REMOTE OWNS, DELETED HERE, is refused here and said once:
          * the link goes, so the next pass does not refuse it again, and the
@@ -567,8 +793,9 @@ export class SyncEngine {
                 const acked = new Set(acks.map((ack) => ack.localId));
                 queued = deduped.filter((write) => !acked.has(write.localId));
             }
-            catch {
+            catch (error) {
                 offline = true;
+                problem = error instanceof Error ? error.message : String(error);
             }
         }
         this.state = {
@@ -577,6 +804,8 @@ export class SyncEngine {
             outbox: queued,
             ...this.heldState(held),
             ...(this.state.gone ? { gone: this.state.gone } : {}),
+            ...(this.state.unresolved ? { unresolved: this.state.unresolved } : {}),
+            ...(this.state.skipped ? { skipped: this.state.skipped } : {}),
         };
         return {
             system: this.options.mapping.system,
@@ -589,6 +818,7 @@ export class SyncEngine {
             refused,
             gone,
             offline,
+            ...(problem ? { problem } : {}),
             state: this.snapshot,
         };
     }
@@ -630,7 +860,7 @@ export class SyncEngine {
      */
     land(call, intent, about, refused) {
         try {
-            return this.options.store.apply(call, { author: systemAuthor(this.options.mapping.system), intent });
+            return this.options.store.applyAll(Array.isArray(call) ? call : [call], { author: systemAuthor(this.options.mapping.system), intent });
         }
         catch (error) {
             if (!refused)
@@ -655,7 +885,10 @@ export class SyncEngine {
         const created = this.options.createInbound?.({ resource: link.resource, id: link.id, fields: remoteFields(record, mapping) });
         if (!created)
             return { links: rest };
-        const result = this.land(created, `${this.options.mapping.system}: restored ${link.resource}`, { localId, resource: link.resource, id: link.id }, refused);
+        const madeAs = String(created.args["id"] ?? "");
+        const about = { localId, resource: link.resource, id: link.id };
+        const intent = `${this.options.mapping.system}: restored ${link.resource}`;
+        const result = madeAs ? this.landInbound({ localId: madeAs, mapping, values: record, create: created }, intent, about, refused)?.result : this.land(created, intent, about, refused);
         if (!result)
             return { links };
         const id = String(created.args["id"] ?? result.writes[0] ?? "");
@@ -694,14 +927,7 @@ export class SyncEngine {
             return;
         }
         if (take === "theirs") {
-            this.options.store.apply(this.options.applyInbound({
-                localId: conflict.localId,
-                kind: mapping.kind,
-                fields: { [conflict.field]: conflict.theirs },
-            }), {
-                author: systemAuthor(this.options.mapping.system),
-                intent: `${this.options.mapping.system}: took their "${conflict.field}"`,
-            });
+            this.landInbound({ localId: conflict.localId, mapping, values: { [conflict.field]: conflict.theirs } }, `${this.options.mapping.system}: took their "${conflict.field}"`, { localId: conflict.localId, resource: link.resource, id: link.id });
         }
         const held = this.held();
         held.delete(heldKey(conflict.localId, conflict.field));
@@ -729,6 +955,17 @@ export class SyncEngine {
             if (op.author.kind === "system" && op.author.id === this.options.mapping.system)
                 continue;
             for (const primitive of op.primitives) {
+                if (primitive.op === "add-edge" || primitive.op === "remove-edge") {
+                    // A link the remote keeps, made or taken away on a record it owns.
+                    const from = graph.getNode(primitive.edge.from);
+                    const mapping = from ? this.options.mapping.resources.find((resource) => resource.kind === from["kind"]) : undefined;
+                    if (!mapping?.readonly || !mapping.edges || !(primitive.edge.kind in mapping.edges) || (mapping.match && !mapping.match(from)))
+                        continue;
+                    // A record of ours removed takes its links with it, those the remote keeps too: that is the record's removal, not a change to the link.
+                    if (primitive.op === "remove-edge" && op.primitives.some((other) => other.op === "remove-node" && other.node.id === primitive.edge.to))
+                        continue;
+                    throw new PermissionDeniedError({ mutation: op.mutation?.name ?? "", kind: mapping.kind, message: this.because(mapping), wouldNeed: [] });
+                }
                 const node = (primitive.op === "add-node" || primitive.op === "remove-node"
                     ? primitive.node
                     : primitive.op === "patch-node" || primitive.op === "splice-text"