@enbox/agent 0.5.13 → 0.5.15

package/src/sync-link-id.ts

@@ -0,0 +1,24 @@
+/** Separator used in compound runtime/legacy cursor keys. */
+export const LINK_ID_SEPARATOR = '^';
+
+/** Opaque runtime identifier for a replication link. */
+export type LinkId = string;
+
+/**
+ * Build the runtime identifier for a replication link.
+ *
+ * Runtime identity is `(tenantDid, remoteEndpoint, scopeId)`.
+ */
+export function buildLinkId(tenantDid: string, remoteEndpoint: string, scopeId: string): LinkId {
+  return `${tenantDid}${LINK_ID_SEPARATOR}${remoteEndpoint}${LINK_ID_SEPARATOR}${scopeId}`;
+}
+
+/**
+ * Build the legacy cursor key used by the deprecated `syncCursors` sublevel.
+ *
+ * This remains only for one-time migration of pre-Phase-1f data.
+ */
+export function buildLegacyCursorKey(tenantDid: string, remoteEndpoint: string, protocol?: string): string {
+  const base = `${tenantDid}${LINK_ID_SEPARATOR}${remoteEndpoint}`;
+  return protocol ? `${base}${LINK_ID_SEPARATOR}${protocol}` : base;
+}

package/src/sync-link-reconciler.ts

@@ -0,0 +1,155 @@
+import type { GenericMessage, MessagesSyncDiffEntry } from '@enbox/dwn-sdk-js';
+
+import type { PushResult } from './types/sync.js';
+
+export type ReconcileDirection = 'pull' | 'push';
+
+export type ReconcileTarget = {
+  did: string;
+  dwnUrl: string;
+  delegateDid?: string;
+  protocol?: string;
+};
+
+export type ReconcileOutcome = {
+  aborted?: boolean;
+  changed: boolean;
+  didPull: boolean;
+  didPush: boolean;
+  localRoot?: string;
+  remoteRoot?: string;
+  postLocalRoot?: string;
+  postRemoteRoot?: string;
+  converged?: boolean;
+  pushResult?: PushResult;
+};
+
+type ReconcileDeps = {
+  getLocalRoot: (did: string, delegateDid?: string, protocol?: string) => Promise<string>;
+  getRemoteRoot: (did: string, dwnUrl: string, delegateDid?: string, protocol?: string) => Promise<string>;
+  diffWithRemote: (target: ReconcileTarget) => Promise<{ onlyRemote: MessagesSyncDiffEntry[]; onlyLocal: string[] }>;
+  pullMessages: (params: {
+    did: string;
+    dwnUrl: string;
+    delegateDid?: string;
+    protocol?: string;
+    messageCids: string[];
+    prefetched: (MessagesSyncDiffEntry & { message: GenericMessage })[];
+  }) => Promise<void>;
+  pushMessages: (params: {
+    did: string;
+    dwnUrl: string;
+    delegateDid?: string;
+    protocol?: string;
+    messageCids: string[];
+  }) => Promise<PushResult>;
+  shouldContinue?: () => boolean;
+};
+
+function partitionRemoteEntries(entries: MessagesSyncDiffEntry[]): {
+  prefetched: (MessagesSyncDiffEntry & { message: GenericMessage })[];
+  needsFetchCids: string[];
+} {
+  const prefetched: (MessagesSyncDiffEntry & { message: GenericMessage })[] = [];
+  const needsFetchCids: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.message) {
+      needsFetchCids.push(entry.messageCid);
+    } else if (
+      entry.message.descriptor.interface === 'Records' &&
+      entry.message.descriptor.method === 'Write' &&
+      (entry.message.descriptor as any).dataCid &&
+      !entry.encodedData
+    ) {
+      needsFetchCids.push(entry.messageCid);
+    } else {
+      prefetched.push(entry as MessagesSyncDiffEntry & { message: GenericMessage });
+    }
+  }
+
+  return { prefetched, needsFetchCids };
+}
+
+export class SyncLinkReconciler {
+  private readonly _deps: ReconcileDeps;
+
+  constructor(deps: ReconcileDeps) {
+    this._deps = deps;
+  }
+
+  public async reconcile(target: ReconcileTarget, options?: {
+    direction?: ReconcileDirection;
+    verifyConvergence?: boolean;
+  }): Promise<ReconcileOutcome> {
+    const { did, dwnUrl, delegateDid, protocol } = target;
+    const direction = options?.direction;
+    const verifyConvergence = options?.verifyConvergence ?? false;
+    const shouldContinue = this._deps.shouldContinue;
+
+    const localRoot = await this._deps.getLocalRoot(did, delegateDid, protocol);
+    if (shouldContinue && !shouldContinue()) { return { aborted: true, changed: false, didPull: false, didPush: false }; }
+
+    const remoteRoot = await this._deps.getRemoteRoot(did, dwnUrl, delegateDid, protocol);
+    if (shouldContinue && !shouldContinue()) { return { aborted: true, changed: false, didPull: false, didPush: false }; }
+
+    let didPull = false;
+    let didPush = false;
+    let pushResult: PushResult | undefined;
+
+    if (localRoot !== remoteRoot) {
+      const diff = await this._deps.diffWithRemote(target);
+      if (shouldContinue && !shouldContinue()) { return { aborted: true, changed: true, didPull: false, didPush: false, localRoot, remoteRoot }; }
+
+      if ((!direction || direction === 'pull') && diff.onlyRemote.length > 0) {
+        const { prefetched, needsFetchCids } = partitionRemoteEntries(diff.onlyRemote);
+        await this._deps.pullMessages({ did, dwnUrl, delegateDid, protocol, messageCids: needsFetchCids, prefetched });
+        if (shouldContinue && !shouldContinue()) { return { aborted: true, changed: true, didPull: true, didPush: false, localRoot, remoteRoot }; }
+        didPull = true;
+      }
+
+      if ((!direction || direction === 'push') && diff.onlyLocal.length > 0) {
+        pushResult = await this._deps.pushMessages({
+          did, dwnUrl, delegateDid, protocol, messageCids: diff.onlyLocal,
+        });
+        if (shouldContinue && !shouldContinue()) {
+          return { aborted: true, changed: true, didPull, didPush: true, localRoot, remoteRoot, pushResult };
+        }
+        didPush = true;
+      }
+    }
+
+    if (!verifyConvergence) {
+      return {
+        changed: localRoot !== remoteRoot,
+        didPull,
+        didPush,
+        localRoot,
+        remoteRoot,
+        pushResult,
+      };
+    }
+
+    const postLocalRoot = await this._deps.getLocalRoot(did, delegateDid, protocol);
+    if (shouldContinue && !shouldContinue()) {
+      return { aborted: true, changed: localRoot !== remoteRoot, didPull, didPush, localRoot, remoteRoot, pushResult };
+    }
+
+    const postRemoteRoot = await this._deps.getRemoteRoot(did, dwnUrl, delegateDid, protocol);
+    if (shouldContinue && !shouldContinue()) {
+      return { aborted: true, changed: localRoot !== remoteRoot, didPull, didPush, localRoot, remoteRoot, pushResult };
+    }
+
+    return {
+      changed   : localRoot !== remoteRoot,
+      didPull,
+      didPush,
+      localRoot,
+      remoteRoot,
+      postLocalRoot,
+      postRemoteRoot,
+      converged : postLocalRoot === postRemoteRoot,
+      pushResult,
+    };
+  }
+}

package/src/sync-messages.ts

@@ -361,7 +361,14 @@ export async function pushMessages({ did, dwnUrl, delegateDid, protocol, message
         // Permanent failures (400/401/403) will never succeed — do NOT retry.
         // These include protocol violations (RecordLimitExceeded), auth errors,
         // and schema validation failures.
-        console.warn(`SyncEngineLevel: push permanently failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);
+        if (reply.status.code === 400 && reply.status.detail?.includes('record limit')) {
+          // Expected for singleton convergence in multi-device scenarios:
+          // one device created a singleton record, this device has a
+          // different one, and the remote rejects the duplicate.
+          console.debug(`SyncEngineLevel: singleton already exists on remote, skipping push for ${cid}`);
+        } else {
+          console.warn(`SyncEngineLevel: push permanently failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);
+        }
         permanentlyFailed.push(cid);
       } else {
         // Transient failures (5xx, etc.) — worth retrying.

package/src/sync-replication-ledger.ts

@@ -62,6 +62,7 @@ export class ReplicationLedger {
     try {
       const raw = await this.sublevel.get(key);
       const link = JSON.parse(raw) as ReplicationLinkState;
+      delete (link as any).push; // strip legacy push field from old persisted links
       // connectivity is runtime state — always reset to 'unknown' on load
       // so stale 'online' from a previous session doesn't give false positives.
       link.connectivity = 'unknown';
@@ -82,7 +83,7 @@ export class ReplicationLedger {
       status         : 'initializing',
       connectivity   : 'unknown',
       pull           : {},
-      push           : {},
+      needsReconcile : false,
       delegateDid    : params.delegateDid,
       protocol       : params.protocol,
     };
@@ -193,5 +194,30 @@ export class ReplicationLedger {
     checkpoint.contiguousAppliedToken = token;
     checkpoint.receivedToken = token;
   }
+
+  // ---------------------------------------------------------------------------
+  // Reconciliation helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Mark a link as needing SMT reconciliation and persist.
+   * Idempotent — no-op if already set.
+   */
+  public async markNeedsReconcile(link: ReplicationLinkState, _reason?: string): Promise<void> {
+    if (!link.needsReconcile) {
+      link.needsReconcile = true;
+      await this.saveLink(link);
+    }
+  }
+
+  /**
+   * Clear the reconciliation flag after successful SMT reconciliation.
+   */
+  public async clearNeedsReconcile(link: ReplicationLinkState): Promise<void> {
+    if (link.needsReconcile) {
+      link.needsReconcile = false;
+      await this.saveLink(link);
+    }
+  }
 }
 

package/src/types/sync.ts

@@ -161,8 +161,13 @@ export type ReplicationLinkState = {
   /** Pull-direction replication checkpoint (remote → local). */
   pull: DirectionCheckpoint;
 
-  /** Push-direction replication checkpoint (local → remote). */
-  push: DirectionCheckpoint;
+  /**
+   * Whether this link needs SMT reconciliation. Set when push fails after
+   * retry exhaustion, when the link reconnects after an outage, or when
+   * the remote epoch changes. Cleared after successful reconciliation.
+   * Persisted so recovery survives app/browser restart.
+   */
+  needsReconcile?: boolean;
 
   /** Per-link connectivity state. Used to compute the aggregate engine-level state. */
   connectivity: SyncConnectivityState;
@@ -242,7 +247,8 @@ export type SyncEvent =
   | { type: 'link:status-change'; tenantDid: string; remoteEndpoint: string; protocol?: string; from: LinkStatus; to: LinkStatus }
   | { type: 'link:connectivity-change'; tenantDid: string; remoteEndpoint: string; protocol?: string; from: SyncConnectivityState; to: SyncConnectivityState }
   | { type: 'checkpoint:pull-advance'; tenantDid: string; remoteEndpoint: string; protocol?: string; position: string; messageCid: string }
-  | { type: 'checkpoint:push-advance'; tenantDid: string; remoteEndpoint: string; protocol?: string; position: string; messageCid: string }
+  | { type: 'reconcile:needed'; tenantDid: string; remoteEndpoint: string; protocol?: string; reason: string }
+  | { type: 'reconcile:completed'; tenantDid: string; remoteEndpoint: string; protocol?: string }
   | { type: 'repair:started'; tenantDid: string; remoteEndpoint: string; protocol?: string; attempt: number }
   | { type: 'repair:completed'; tenantDid: string; remoteEndpoint: string; protocol?: string }
   | { type: 'repair:failed'; tenantDid: string; remoteEndpoint: string; protocol?: string; attempt: number; error: string }