@enbox/agent 0.5.9 → 0.5.11

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

@@ -1,3 +1,4 @@
+import type { ProgressToken } from '@enbox/dwn-sdk-js';
 import type { EnboxPlatformAgent } from './agent.js';
 /**
  * The SyncEngine is responsible for syncing messages between the agent and the platform.
@@ -21,6 +22,123 @@ export type SyncConnectivityState = 'online' | 'offline' | 'unknown';
  * `'live'` for `MessagesSubscribe`-based real-time sync with SMT fallback.
  */
 export type SyncMode = 'poll' | 'live';
+/**
+ * Describes what a replication link syncs. Currently whole-tenant only
+ * (`kind: 'full'`). Scoped subset sync (`kind: 'protocol'` with
+ * `protocolPathPrefixes` / `contextIdPrefixes`) is deferred to Phase 3.
+ */
+export type SyncScope = {
+    /** Scope kind. Only `'full'` is implemented in Phase 1. */
+    kind: 'full';
+} | {
+    /**
+     * Protocol-scoped sync. Deferred to Phase 3 — included here for type
+     * forward-compatibility only.
+     */
+    kind: 'protocol';
+    protocol: string;
+    protocolPathPrefixes?: string[];
+    contextIdPrefixes?: string[];
+};
+/**
+ * Computes a deterministic, collision-resistant identifier for a {@link SyncScope}.
+ *
+ * The ID is `base64url(SHA-256(canonicalJSON))` where `canonicalJSON` is the
+ * scope object with keys sorted alphabetically and array values sorted
+ * lexicographically.
+ *
+ * Used as part of the LevelDB key for the replication ledger:
+ * `{tenantDid}^{remoteEndpoint}^{scopeId}`.
+ */
+export declare function computeScopeId(scope: SyncScope): Promise<string>;
+/**
+ * Maximum number of in-flight deliveries (runtime ordinals) a link may
+ * accumulate before transitioning to `repairing`. This is the overflow
+ * threshold for the engine's in-memory delivery tracker, not for durable
+ * checkpoint state. Normative per the sync redesign RFC.
+ */
+export declare const MAX_PENDING_TOKENS = 100;
+/**
+ * Tracks directional (pull or push) replay progression for a single
+ * replication link. All tokens belong to the same `(streamId, epoch)`.
+ *
+ * This is the **durable** replication checkpoint persisted to the ledger.
+ * In-memory delivery-order tracking (ordinals, in-flight commits) is owned
+ * by the sync engine and is not persisted — on crash recovery, replay
+ * restarts from `contiguousAppliedToken` and idempotent apply handles
+ * any re-delivered events.
+ */
+export type DirectionCheckpoint = {
+    /**
+     * The latest token received from the source (pull) or confirmed by the
+     * remote (push). May be ahead of `contiguousAppliedToken` when events
+     * arrive out of order. Used for observability.
+     */
+    receivedToken?: ProgressToken;
+    /**
+     * The highest token such that all earlier delivered tokens for this link
+     * have been durably applied. This is the resume point after crash/reconnect.
+     *
+     * Advancement is controlled by the engine's delivery-order tracking,
+     * not by position arithmetic. Positions may be sparse (filtered streams).
+     */
+    contiguousAppliedToken?: ProgressToken;
+};
+/**
+ * Status of a replication link.
+ *
+ * - `initializing` — link created, no subscriptions open yet.
+ * - `live` — actively receiving events via subscription.
+ * - `repairing` — gap detected or pending overflow; running SMT reconciliation.
+ * - `degraded_poll` — subscription failed; polling at reduced frequency.
+ * - `paused` — explicitly paused by the application.
+ */
+export type LinkStatus = 'initializing' | 'live' | 'repairing' | 'degraded_poll' | 'paused';
+/**
+ * Durable state of a single replication link. Persisted to LevelDB and
+ * loaded on startup. Each link is identified by the tuple
+ * `(tenantDid, remoteEndpoint, scopeId)`.
+ */
+export type ReplicationLinkState = {
+    /** The tenant DID this link syncs for. */
+    tenantDid: string;
+    /** The remote DWN endpoint URL. */
+    remoteEndpoint: string;
+    /** Deterministic hash of the {@link SyncScope}. See {@link computeScopeId}. */
+    scopeId: string;
+    /** The scope definition this link covers. */
+    scope: SyncScope;
+    /** Current link status. */
+    status: LinkStatus;
+    /** Pull-direction replication checkpoint (remote → local). */
+    pull: DirectionCheckpoint;
+    /** Push-direction replication checkpoint (local → remote). */
+    push: DirectionCheckpoint;
+    /** Per-link connectivity state. Used to compute the aggregate engine-level state. */
+    connectivity: SyncConnectivityState;
+    /** Delegate DID used to sign sync messages, if any. */
+    delegateDid?: string;
+    /**
+     * Protocol filter for this link, if any. Duplicates the protocol in `scope`
+     * for operational convenience — used by permission lookups and cursor key
+     * building. The scope is the source of truth for what to sync; this field
+     * is the source of truth for how to authenticate. To be consolidated in
+     * Phase 3 when scope resolution is more complex.
+     */
+    protocol?: string;
+    /** ISO-8601 timestamp of last successful sync activity. */
+    lastActivityAt?: string;
+};
+/**
+ * Result of a batch push operation. Replaces the previous throw-on-first-failure
+ * pattern so callers can advance the push replication checkpoint incrementally.
+ */
+export type PushResult = {
+    /** messageCids that were accepted (202/204/409 — idempotent success). */
+    succeeded: string[];
+    /** messageCids that failed (retryable or hard error). */
+    failed: string[];
+};
 /**
  * Parameters for {@link SyncEngine.startSync}.
  */
@@ -48,6 +166,70 @@ export type StartSyncParams = {
      */
     interval?: string;
 };
+/**
+ * Events emitted by the sync engine at key state transitions.
+ * Consumers subscribe via `SyncEngine.on('event', handler)` and can
+ * hook these into metrics, logging, or UI state.
+ */
+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: '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;
+} | {
+    type: 'degraded-poll:entered';
+    tenantDid: string;
+    remoteEndpoint: string;
+    protocol?: string;
+} | {
+    type: 'gap:detected';
+    tenantDid: string;
+    remoteEndpoint: string;
+    protocol?: string;
+    reason: string;
+};
+export type SyncEventListener = (event: SyncEvent) => void;
 export interface SyncEngine {
     /**
      * The agent that the SyncEngine is attached to.
@@ -104,6 +286,12 @@ export interface SyncEngine {
      * @throws {Error} if the sync operation fails to stop before the timeout.
      */
     stopSync(timeout?: number): Promise<void>;
+    /**
+     * Subscribe to sync engine events. Returns an unsubscribe function.
+     * Events are emitted at key state transitions: checkpoint advancement,
+     * link status changes, repair, degraded_poll, gap detection.
+     */
+    on(listener: SyncEventListener): () => void;
     /**
      * Release all resources held by the sync engine (LevelDB handles, timers,
      * WebSocket subscriptions). After calling `close()`, the engine should not

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/types/sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,EAAE,kBAAkB,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,qBAAqB,CAAC;IAElD;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxF;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IAC1E;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F;;;;;OAKG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/types/sync.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/agent",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
@@ -71,8 +71,8 @@
   },
   "dependencies": {
     "@scure/bip39": "1.2.2",
-    "@enbox/dwn-clients": "0.2.4",
-    "@enbox/dwn-sdk-js": "0.3.0",
+    "@enbox/dwn-clients": "0.2.5",
+    "@enbox/dwn-sdk-js": "0.3.1",
     "@enbox/common": "0.1.0",
     "@enbox/crypto": "0.1.0",
     "@enbox/dids": "0.1.0",

package/src/dwn-api.ts

@@ -5,6 +5,7 @@ import type {
   EncryptionKeyDeriver,
   GenericMessage,
   KeyDecrypter,
+  ProgressToken,
   ProtocolDefinition,
   RecordsWrite,
   RecordsWriteMessage,
@@ -568,7 +569,7 @@ export class AgentDwnApi {
     // subscribe message with a cursor on reconnection.
     let resubscribeFactory: ResubscribeFactory | undefined;
     if (subscriptionHandler !== undefined && !('messageCid' in request)) {
-      resubscribeFactory = async (cursor?: string): Promise<GenericMessage> => {
+      resubscribeFactory = async (cursor?: ProgressToken): Promise<GenericMessage> => {
         const resumeParams = cursor !== undefined
           ? { ...request.messageParams, cursor } as DwnMessageParams[T]
           : request.messageParams;

package/src/dwn-record-upgrade.ts

@@ -158,7 +158,7 @@ export async function upgradeExternalRootRecord(
 
   // Notify real-time subscribers (mirrors handler behavior)
   if (eventLog !== undefined) {
-    await eventLog.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes);
+    await eventLog.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes, upgradedCid);
   }
 
   // Cache context key info for subsequent writes in this context

package/src/index.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';