@enbox/agent 0.5.9 → 0.5.11

package/dist/types/index.d.ts

@@ -5,6 +5,11 @@ export type * from './types/identity-vault.js';
 export type * from './types/key-manager.js';
 export type * from './types/permissions.js';
 export type * from './types/sync.js';
+export { computeScopeId, MAX_PENDING_TOKENS } from './types/sync.js';
+export { ReplicationLedger } from './sync-replication-ledger.js';
+export { ClosureFailureCode, createClosureContext } from './sync-closure-types.js';
+export type { ClosureDependencyEdge, ClosureEvaluationContext, ClosureResult } from './sync-closure-types.js';
+export { evaluateClosure, evaluateClosureBatch } from './sync-closure-resolver.js';
 export type * from './types/vc.js';
 export * from './agent-did-resolver-cache.js';
 export * from './anonymous-dwn-api.js';

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,kBAAkB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,2BAA2B,CAAC;AAC/C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,iBAAiB,CAAC;AACrC,mBAAmB,eAAe,CAAC;AAEnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAItC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,kBAAkB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,mBAAmB,qBAAqB,CAAC;AACzC,mBAAmB,2BAA2B,CAAC;AAC/C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,wBAAwB,CAAC;AAC5C,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC9G,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACnF,mBAAmB,eAAe,CAAC;AAEnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAItC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uBAAuB,CAAC"}

package/dist/types/sync-closure-resolver.d.ts

@@ -0,0 +1,19 @@
+import type { SyncScope } from './types/sync.js';
+import type { ClosureEvaluationContext, ClosureResult } from './sync-closure-types.js';
+import type { GenericMessage, MessageStore } from '@enbox/dwn-sdk-js';
+/**
+ * Evaluates closure completeness for a single operation (closure root).
+ *
+ * Uses BFS traversal with deduplication and depth limiting. Shared caching
+ * across evaluation batches via {@link ClosureEvaluationContext}.
+ *
+ * The resolver queries the local MessageStore directly (bypassing auth)
+ * because it needs to verify dependency presence, not access-control the
+ * syncing agent's own local store.
+ */
+export declare function evaluateClosure(message: GenericMessage, messageStore: MessageStore, scope: SyncScope, context: ClosureEvaluationContext): Promise<ClosureResult>;
+/**
+ * Evaluate closure for a batch of messages. Shares caching across all roots.
+ */
+export declare function evaluateClosureBatch(messages: GenericMessage[], messageStore: MessageStore, scope: SyncScope, tenantDid: string, maxDepth?: number): Promise<ClosureResult[]>;
+//# sourceMappingURL=sync-closure-resolver.d.ts.map

package/dist/types/sync-closure-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-closure-resolver.d.ts","sourceRoot":"","sources":["../../src/sync-closure-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAEV,wBAAwB,EACxB,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyZtE;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC,CA8FxB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,cAAc,EAAE,EAC1B,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,EAAE,CAAC,CAU1B"}

package/dist/types/sync-closure-types.d.ts

@@ -0,0 +1,122 @@
+import type { GenericMessage } from '@enbox/dwn-sdk-js';
+/**
+ * Typed failure codes for closure resolution. Each code maps to a specific
+ * dependency class from the closure RFC.
+ */
+export declare enum ClosureFailureCode {
+    /** Class 1: The ProtocolsConfigure for the protocol could not be found. */
+    ProtocolMetadataMissing = "ClosureProtocolMetadataMissing",
+    /** Class 2: The initialWrite for a non-initial RecordsWrite is missing. */
+    InitialWriteMissing = "ClosureInitialWriteMissing",
+    /** Class 2: A parent record in the parentId chain is missing. */
+    ParentChainMissing = "ClosureParentChainMissing",
+    /** Class 2: A context ancestor record is missing. */
+    ContextChainMissing = "ClosureContextChainMissing",
+    /** Class 3: A permission grant referenced by permissionGrantId is missing. */
+    GrantMissing = "ClosureGrantMissing",
+    /** Class 3: The grant exists but is not yet active at the message's timestamp. */
+    GrantNotYetActive = "ClosureGrantNotYetActive",
+    /** Class 3: The grant exists but has expired at the message's timestamp. */
+    GrantExpired = "ClosureGrantExpired",
+    /** Class 3: A revocation record that affects a referenced grant is missing. */
+    GrantRevocationMissing = "ClosureGrantRevocationMissing",
+    /** Class 4: A squash floor or visibility-floor record is missing. */
+    VisibilityFloorMissing = "ClosureVisibilityFloorMissing",
+    /** Class 5: An encryption/key-delivery dependency is missing. */
+    EncryptionDependencyMissing = "ClosureEncryptionDependencyMissing",
+    /** Class 6: A cross-protocol $ref dependency is missing. */
+    CrossProtocolReferenceMissing = "ClosureCrossProtocolReferenceMissing",
+    /** A dependency exists but the syncing principal is not authorized to fetch it. */
+    DependencyForbidden = "ClosureDependencyForbidden",
+    /** Traversal depth exceeded the configured maximum (default 32). */
+    DepthExceeded = "ClosureDepthExceeded"
+}
+/**
+ * A single dependency edge in the closure graph — identifies what is needed
+ * and why. Used for diagnostics, deduplication, and fetch queue management.
+ */
+export type ClosureDependencyEdge = {
+    /** The dependency class that produced this edge. */
+    dependencyClass: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Human-readable label for the dependency (e.g., "initialWrite", "grant", "protocolsConfigure"). */
+    label: string;
+    /**
+     * The identifier used to look up this dependency. Typically a `messageCid`
+     * or `recordId` depending on the dependency class.
+     */
+    identifier: string;
+    /** The type of identifier — determines the fetch strategy. */
+    identifierType: 'messageCid' | 'recordId' | 'protocol' | 'grantId' | 'filter';
+    /**
+     * When `identifierType` is `'filter'`, this carries the full query filter
+     * as a structured object. Used for dependencies that require multi-field
+     * queries (e.g., cross-protocol role records queried by protocol +
+     * protocolPath + recipient + contextId prefix).
+     */
+    filter?: Record<string, unknown>;
+};
+/**
+ * Result of closure evaluation for a single operation (closure root).
+ */
+export type ClosureResult = {
+    /** Whether all hard dependencies are satisfied. */
+    complete: boolean;
+    /** The closure root's messageCid. */
+    rootMessageCid: string;
+    /** All dependency edges that were evaluated. */
+    edges: ClosureDependencyEdge[];
+    /**
+     * If incomplete, the first unsatisfied dependency. Used for diagnostics
+     * and determines the failure code for repair transitions.
+     */
+    failure?: {
+        code: ClosureFailureCode;
+        edge: ClosureDependencyEdge;
+        detail: string;
+    };
+    /** Total number of dependency hops traversed. */
+    depth: number;
+};
+/**
+ * Shared context for a batch of closure evaluations. Caches protocol
+ * definitions, grant records, and previously resolved operations to avoid
+ * redundant queries across closure roots in the same evaluation pass.
+ */
+export type ClosureEvaluationContext = {
+    /** Tenant DID for this evaluation batch. */
+    tenantDid: string;
+    /** Cached ProtocolsConfigure definitions keyed by protocol URI. */
+    protocolCache: Map<string, any>;
+    /** Cached grant records keyed by grantId. */
+    grantCache: Map<string, GenericMessage | null>;
+    /**
+     * Set of dependency identifiers already known to be locally present.
+     * Keyed by `${identifierType}:${identifier}` to prevent cross-namespace
+     * collisions (e.g., a recordId and a grantId with the same string value).
+     */
+    satisfiedDeps: Set<string>;
+    /**
+     * Set of dependency identifiers already known to be missing/unfetchable.
+     * Same composite key format as `satisfiedDeps`.
+     */
+    missingDeps: Set<string>;
+    /** Maximum traversal depth. Default 32. */
+    maxDepth: number;
+};
+/**
+ * Create a fresh evaluation context for a batch of closure evaluations.
+ */
+export declare function createClosureContext(tenantDid: string, maxDepth?: number): ClosureEvaluationContext;
+/**
+ * Invalidate cached entries that may be affected by a newly processed message.
+ * Called after `processRawMessage` succeeds to ensure subsequent closure
+ * evaluations see the updated state.
+ *
+ * - `ProtocolsConfigure` → clears protocolCache for that protocol URI
+ * - Permissions grant write → clears grantCache for that recordId
+ * - Permissions revocation → clears grantCache for the parent grantId
+ * - Any Records message → clears satisfiedDeps/missingDeps for that recordId
+ *   (the message may have changed what's locally present)
+ */
+export declare function invalidateClosureCache(context: ClosureEvaluationContext, message: GenericMessage): void;
+//# sourceMappingURL=sync-closure-types.d.ts.map

package/dist/types/sync-closure-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-closure-types.d.ts","sourceRoot":"","sources":["../../src/sync-closure-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,2EAA2E;IAC3E,uBAAuB,mCAAmC;IAC1D,2EAA2E;IAC3E,mBAAmB,+BAA+B;IAClD,iEAAiE;IACjE,kBAAkB,8BAA8B;IAChD,qDAAqD;IACrD,mBAAmB,+BAA+B;IAClD,8EAA8E;IAC9E,YAAY,wBAAwB;IACpC,kFAAkF;IAClF,iBAAiB,6BAA6B;IAC9C,4EAA4E;IAC5E,YAAY,wBAAwB;IACpC,+EAA+E;IAC/E,sBAAsB,kCAAkC;IACxD,qEAAqE;IACrE,sBAAsB,kCAAkC;IACxD,iEAAiE;IACjE,2BAA2B,uCAAuC;IAClE,4DAA4D;IAC5D,6BAA6B,yCAAyC;IACtE,mFAAmF;IACnF,mBAAmB,+BAA+B;IAClD,oEAAoE;IACpE,aAAa,yBAAyB;CACvC;AAMD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,oDAAoD;IACpD,eAAe,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACvC,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,cAAc,EAAE,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9E;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,mDAAmD;IACnD,QAAQ,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,kBAAkB,CAAC;QACzB,IAAI,EAAE,qBAAqB,CAAC;QAC5B,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,6CAA6C;IAC7C,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B;;;OAGG;IACH,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,wBAAwB,CASnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,cAAc,GACtB,IAAI,CAmHN"}

package/dist/types/sync-engine-level.d.ts

@@ -1,7 +1,7 @@
 import type { AbstractLevel } from 'abstract-level';
 import type { GenericMessage } from '@enbox/dwn-sdk-js';
 import type { EnboxPlatformAgent } from './types/agent.js';
-import type { StartSyncParams, SyncConnectivityState, SyncEngine, SyncIdentityOptions } from './types/sync.js';
+import type { StartSyncParams, SyncConnectivityState, SyncEngine, SyncEventListener, SyncIdentityOptions } from './types/sync.js';
 export type SyncEngineLevelParams = {
     agent?: EnboxPlatformAgent;
     dataPath?: string;
@@ -22,6 +22,26 @@ export declare class SyncEngineLevel implements SyncEngine {
     private _db;
     private _syncIntervalId?;
     private _syncLock;
+    /**
+     * Durable replication ledger — persists per-link checkpoint state.
+     * Used by live sync to track pull/push progression independently per link.
+     * Poll-mode sync still uses the legacy `getCursor`/`setCursor` path.
+     * Lazily initialized on first use to avoid sublevel() calls on mock dbs.
+     */
+    private _ledger?;
+    /**
+     * In-memory cache of active links, keyed by `{did}^{dwnUrl}^{protocol}`.
+     * Populated from the ledger on `startLiveSync`, used by subscription handlers
+     * to avoid async ledger lookups on every event.
+     */
+    private _activeLinks;
+    /**
+     * Per-link in-memory delivery-order tracking for the pull path. Keyed by
+     * the same link key as `_activeLinks`. Not persisted — on crash, replay
+     * restarts from `contiguousAppliedToken` and idempotent apply handles
+     * re-delivered events.
+     */
+    private _linkRuntimes;
     /**
      * Hex-encoded default hashes for empty subtrees at each depth, keyed by depth.
      * Lazily initialized on first use. Used by `walkTreeDiff` to detect empty subtrees
@@ -30,6 +50,13 @@ export declare class SyncEngineLevel implements SyncEngine {
     private _defaultHashHex?;
     /** Current sync mode, set by `startSync`. */
     private _syncMode;
+    /**
+     * Monotonic session generation counter. Incremented on every teardown.
+     * Async operations (repair, retry timers) capture the generation at start
+     * and bail if it has changed — this prevents stale work from mutating
+     * state after teardown or mode switch.
+     */
+    private _syncGeneration;
     /** Active live pull subscriptions (remote -> local via MessagesSubscribe). */
     private _liveSubscriptions;
     /** Active local EventLog subscriptions for push-on-write (local -> remote). */
@@ -38,8 +65,27 @@ export declare class SyncEngineLevel implements SyncEngine {
     private _connectivityState;
     /** Debounce timer for batched push-on-write. */
     private _pushDebounceTimer?;
-    /** Pending message CIDs to push, accumulated during the debounce window. */
+    /** Registered event listeners for observability. */
+    private _eventListeners;
+    /** Entry in the pending push queue — a message CID with its local EventLog token. */
     private _pendingPushCids;
+    /**
+     * CIDs recently received via pull subscription, keyed by `cid|dwnUrl` to
+     * scope suppression per remote endpoint. A message pulled from Provider A
+     * is only suppressed for push back to Provider A — it still fans out to
+     * Provider B and C. TTL: 60 seconds. Cap: 10,000 entries.
+     */
+    private _recentlyPulledCids;
+    /** TTL for echo-loop suppression entries (60 seconds). */
+    private static readonly ECHO_SUPPRESS_TTL_MS;
+    /**
+     * Per-tenant closure evaluation contexts for the current live sync session.
+     * Caches ProtocolsConfigure and grant lookups across events for the same
+     * tenant. Keyed by tenantDid to prevent cross-tenant cache pollution.
+     */
+    private _closureContexts;
+    /** Maximum entries in the echo-loop suppression cache. */
+    private static readonly ECHO_SUPPRESS_MAX_ENTRIES;
     /** Count of consecutive SMT sync failures (for backoff in poll mode). */
     private _consecutiveFailures;
     /** Maximum consecutive failures before entering backoff. */
@@ -47,6 +93,8 @@ export declare class SyncEngineLevel implements SyncEngine {
     /** Backoff multiplier for consecutive failures (caps at 4x the configured interval). */
     private static readonly MAX_BACKOFF_MULTIPLIER;
     constructor({ agent, dataPath, db }: SyncEngineLevelParams);
+    /** Lazy accessor for the replication ledger. */
+    private get ledger();
     /**
      * Retrieves the `EnboxPlatformAgent` execution context.
      *
@@ -56,6 +104,9 @@ export declare class SyncEngineLevel implements SyncEngine {
     get agent(): EnboxPlatformAgent;
     set agent(agent: EnboxPlatformAgent);
     get connectivityState(): SyncConnectivityState;
+    on(listener: SyncEventListener): () => void;
+    /** Emit a sync event to all registered listeners. */
+    private emitEvent;
     clear(): Promise<void>;
     close(): Promise<void>;
     registerIdentity({ did, options }: {
@@ -84,6 +135,73 @@ export declare class SyncEngineLevel implements SyncEngine {
      * 4. Schedules an infrequent SMT integrity check at `interval`.
      */
     private startLiveSync;
+    /**
+     * Get or create the runtime state for a link.
+     */
+    private getOrCreateRuntime;
+    /**
+     * Drain contiguously committed ordinals from the runtime state, advancing
+      * the link's pull checkpoint for each drained entry. Returns the number of
+     * entries drained (0 if the next ordinal is not yet committed).
+     */
+    private drainCommittedPull;
+    /** Maximum consecutive repair attempts before falling back to degraded_poll. */
+    private static readonly MAX_REPAIR_ATTEMPTS;
+    /** Per-link degraded-poll interval timers. */
+    private _degradedPollTimers;
+    /** Per-link repair attempt counters. */
+    private _repairAttempts;
+    /** Per-link active repair promises — prevents concurrent repair for the same link. */
+    private _activeRepairs;
+    /** Per-link retry timers for failed repairs below max attempts. */
+    private _repairRetryTimers;
+    /** Backoff schedule for repair retries (milliseconds). */
+    private static readonly REPAIR_BACKOFF_MS;
+    /**
+     * Per-link repair context — stores ProgressGap metadata for use during
+     * repair. The `resumeToken` (from `gapInfo.latestAvailable`) is used as
+     * the post-repair checkpoint so the reopened subscription replays from
+     * a valid boundary instead of starting live-only.
+     */
+    private _repairContext;
+    /**
+     * Central helper for transitioning a link to `repairing`. Encapsulates:
+     * - status change
+     * - optional gap context storage
+     * - repair kick-off with retry scheduling on failure
+     *
+     * All code paths that set `repairing` should go through this helper to
+     * guarantee a future retry path.
+     */
+    private transitionToRepairing;
+    /**
+     * Schedule a retry for a failed repair. Uses exponential backoff.
+     * No-op if the link is already in `degraded_poll` (timer loop owns retries)
+     * or if a retry is already scheduled.
+     */
+    private scheduleRepairRetry;
+    /**
+     * Repair a single link. Deduplicates concurrent calls via `_activeRepairs`.
+     * If repair is already running for this link, returns the existing promise.
+     */
+    private repairLink;
+    /**
+     * Internal repair implementation. Runs SMT set reconciliation for a single
+     * link, then attempts to re-establish live subscriptions. If repair succeeds,
+     * transitions to `live`. If it fails, throws so callers (degraded_poll timer,
+     * startup) can handle retry scheduling.
+     */
+    private doRepairLink;
+    /**
+     * Close pull and push subscriptions for a specific link.
+     */
+    private closeLinkSubscriptions;
+    /**
+     * Transition a link to `degraded_poll` and start a per-link polling timer.
+     * The timer runs SMT reconciliation at a reduced frequency (30s with jitter)
+     * and attempts to re-establish live subscriptions after each successful repair.
+     */
+    private enterDegradedPoll;
     /**
      * Tears down all live subscriptions and push listeners.
      */
@@ -103,6 +221,12 @@ export declare class SyncEngineLevel implements SyncEngine {
      */
     private flushPendingPushes;
     private buildCursorKey;
+    /**
+     * Retrieves a stored progress token. Handles migration from old string cursors:
+     * if the stored value is a bare string (pre-ProgressToken format), it is treated
+     * as absent — the sync engine will do a full SMT reconciliation on first startup
+     * after upgrade, which is correct and safe.
+     */
     private getCursor;
     private setCursor;
     /**
@@ -147,13 +271,6 @@ export declare class SyncEngineLevel implements SyncEngine {
      * Returns a hex-encoded root hash string.
      */
     private getRemoteRoot;
-    /**
-     * Walks the local and remote SMTs in parallel, recursing into subtrees whose
-     * hashes differ, until reaching `MAX_DIFF_DEPTH` where leaves are enumerated.
-     *
-     * Returns the sets of messageCids that exist only locally or only remotely.
-     */
-    private walkTreeDiff;
     /**
      * Compute the diff between local and remote in a single HTTP round-trip.
      *
@@ -184,7 +301,6 @@ export declare class SyncEngineLevel implements SyncEngine {
      * In remote mode: constructs a signed MessagesSync message and routes through RPC.
      */
     private getLocalSubtreeHash;
-    private getRemoteSubtreeHash;
     /**
      * Get all leaf messageCids under a given prefix from the local DWN.
      *
@@ -192,7 +308,6 @@ export declare class SyncEngineLevel implements SyncEngine {
      * In remote mode: constructs a signed MessagesSync message and routes through RPC.
      */
     private getLocalLeaves;
-    private getRemoteLeaves;
     /**
      * Fetches missing messages from the remote DWN and processes them locally
      * in dependency order (topological sort).
@@ -202,6 +317,17 @@ export declare class SyncEngineLevel implements SyncEngine {
      * Only `messageCids` that were NOT prefetched are fetched individually.
      */
     private pullMessages;
+    /**
+     * Evicts expired entries from the echo-loop suppression cache.
+     * Also enforces the size cap by evicting oldest entries first.
+     */
+    private evictExpiredEchoEntries;
+    /**
+     * Checks whether a CID was recently pulled from a specific remote endpoint
+     * and should not be pushed back to that same endpoint (echo-loop suppression).
+     * Does not suppress pushes to other endpoints — multi-provider fan-out works.
+     */
+    private isRecentlyPulled;
     /**
      * Reads missing messages from the local DWN and pushes them to the remote DWN
      * in dependency order (topological sort).

package/dist/types/sync-engine-level.d.ts.map

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

package/dist/types/sync-messages.d.ts

@@ -1,5 +1,6 @@
 import type { EnboxPlatformAgent } from './types/agent.js';
 import type { PermissionsApi } from './types/permissions.js';
+import type { PushResult } from './types/sync.js';
 import type { GenericMessage, MessagesSyncDiffEntry, UnionMessageReply } from '@enbox/dwn-sdk-js';
 /** Entry type for fetched messages with optional data stream and retry buffer. */
 export type SyncMessageEntry = {
@@ -56,6 +57,10 @@ export declare function fetchRemoteMessages({ did, dwnUrl, delegateDid, protocol
  * Messages are fetched first, then sorted in dependency order (topological sort)
  * so that initial writes come before updates, and ProtocolsConfigures come before
  * records that reference those protocols.
+ *
+ * Returns a {@link PushResult} with per-CID outcome tracking instead of throwing
+ * on the first failure. Callers use this to advance the push checkpoint
+ * incrementally — only up to the highest contiguous success.
  */
 export declare function pushMessages({ did, dwnUrl, delegateDid, protocol, messageCids, agent, permissionsApi }: {
     did: string;
@@ -65,7 +70,7 @@ export declare function pushMessages({ did, dwnUrl, delegateDid, protocol, messa
     messageCids: string[];
     agent: EnboxPlatformAgent;
     permissionsApi: PermissionsApi;
-}): Promise<void>;
+}): Promise<PushResult>;
 /**
  * Reads a message from the local DWN by its CID using MessagesRead.
  */

package/dist/types/sync-messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-messages.d.ts","sourceRoot":"","sources":["../../src/sync-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAqB,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWrH,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACxC,8FAA8F;IAC9F,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAS9E;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IACzH,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gGAAgG;IAChG,UAAU,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFhB;AA4DD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IACpH,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoE9B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IAC7G,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChB;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAmCxC"}
+{"version":3,"file":"sync-messages.d.ts","sourceRoot":"","sources":["../../src/sync-messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAqB,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWrH,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACxC,8FAA8F;IAC9F,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAS9E;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IACzH,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gGAAgG;IAChG,UAAU,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFhB;AA4DD;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IACpH,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoE9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IAC7G,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,UAAU,CAAC,CA2CtB;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IAC1G,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;CAChC,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAmCxC"}

package/dist/types/sync-replication-ledger.d.ts

@@ -0,0 +1,72 @@
+import type { AbstractLevel } from 'abstract-level';
+import type { ProgressToken } from '@enbox/dwn-sdk-js';
+import type { DirectionCheckpoint, LinkStatus, ReplicationLinkState, SyncScope } from './types/sync.js';
+/**
+ * Durable replication ledger — persists {@link ReplicationLinkState} for each
+ * sync link in a LevelDB sublevel. Provides CRUD operations and replication
+ * checkpoint helpers.
+ *
+ * Key format: `{tenantDid}^{remoteEndpoint}^{scopeId}`
+ *
+ * Each link tracks independent pull and push {@link DirectionCheckpoint}s.
+ * The ledger does not own subscriptions or timers — it is a passive state
+ * store called by the sync engine.
+ */
+export declare class ReplicationLedger {
+    private readonly db;
+    private sublevel;
+    constructor(db: AbstractLevel<string | Buffer | Uint8Array>);
+    /** Build the compound key for a link. */
+    private static buildKey;
+    /**
+     * Get-or-create a link. If the link does not exist, it is created with
+     * `initializing` status and empty checkpoints.
+     */
+    getOrCreateLink(params: {
+        tenantDid: string;
+        remoteEndpoint: string;
+        scope: SyncScope;
+        delegateDid?: string;
+        protocol?: string;
+    }): Promise<ReplicationLinkState>;
+    /** Persist the current state of a link. */
+    saveLink(link: ReplicationLinkState): Promise<void>;
+    /** Delete a link. */
+    deleteLink(tenantDid: string, remoteEndpoint: string, scopeId: string): Promise<void>;
+    /** List all links for a tenant. */
+    getLinksForTenant(tenantDid: string): Promise<ReplicationLinkState[]>;
+    /** List all links. */
+    getAllLinks(): Promise<ReplicationLinkState[]>;
+    /** Transition a link to a new status and persist. */
+    setStatus(link: ReplicationLinkState, status: LinkStatus): Promise<void>;
+    /**
+     * Compare two tokens by position (BigInt numeric comparison).
+     * Returns negative if a < b, zero if equal, positive if a > b.
+     * Caller must verify streamId and epoch match before calling.
+     */
+    static comparePosition(a: ProgressToken, b: ProgressToken): number;
+    /**
+     * Check whether a token belongs to the same domain (streamId + epoch) as
+     * the checkpoint's current baseline. Returns `true` if domains match or if
+     * the checkpoint has no baseline yet.
+     */
+    static validateTokenDomain(checkpoint: DirectionCheckpoint, token: ProgressToken): boolean;
+    /**
+     * Update `receivedToken` to the highest seen token (for observability).
+     * Does NOT advance `contiguousAppliedToken` — that is owned by the engine's
+     * delivery-order tracking.
+     */
+    static setReceivedToken(checkpoint: DirectionCheckpoint, token: ProgressToken): void;
+    /**
+     * Commit a token as the new contiguous applied baseline. The caller (engine)
+     * must have already verified that all earlier delivered tokens for this link
+     * are durably committed before calling this.
+     */
+    static commitContiguousToken(checkpoint: DirectionCheckpoint, token: ProgressToken): void;
+    /**
+     * Reset a replication checkpoint (e.g., after repair or domain change).
+     * Clears all state.
+     */
+    static resetCheckpoint(checkpoint: DirectionCheckpoint, token?: ProgressToken): void;
+}
+//# sourceMappingURL=sync-replication-ledger.d.ts.map

package/dist/types/sync-replication-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-replication-ledger.d.ts","sourceRoot":"","sources":["../../src/sync-replication-ledger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOxG;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA8C;IACjE,OAAO,CAAC,QAAQ,CAAC;gBAEL,EAAE,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;IAS3D,yCAAyC;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ;IAYvB;;;OAGG;IACU,eAAe,CAAC,MAAM,EAAE;QACnC,SAAS,EAAG,MAAM,CAAC;QACnB,cAAc,EAAG,MAAM,CAAC;QACxB,KAAK,EAAG,SAAS,CAAC;QAClB,WAAW,CAAC,EAAG,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAG,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAoCjC,2CAA2C;IAC9B,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhE,qBAAqB;IACR,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlG,mCAAmC;IACtB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAWlF,sBAAsB;IACT,WAAW,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAY3D,qDAAqD;IACxC,SAAS,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IASrF;;;;OAIG;WACW,eAAe,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM;IAOzE;;;;OAIG;WACW,mBAAmB,CAAC,UAAU,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO;IAMjG;;;;OAIG;WACW,gBAAgB,CAAC,UAAU,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAS3F;;;;OAIG;WACW,qBAAqB,CAAC,UAAU,EAAE,mBAAmB,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAIhG;;;OAGG;WACW,eAAe,CAAC,UAAU,EAAE,mBAAmB,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI;CAI5F"}