@enbox/agent 0.7.7 → 0.7.8

package/src/sync-topological-sort.ts

@@ -1,14 +1,71 @@
-import type { GenericMessage } from '@enbox/dwn-sdk-js';
+import type { GenericMessage, ProtocolDefinition } from '@enbox/dwn-sdk-js';
 
+import { getInvokedPermissionGrantIds } from './sync-permission-grants.js';
 import { DwnInterfaceName, DwnMethodName, PermissionsProtocol } from '@enbox/dwn-sdk-js';
 
+type DescriptorWithRecordId = GenericMessage['descriptor'] & {
+  recordId?: string;
+};
+
+type RecordsDescriptor = GenericMessage['descriptor'] & {
+  dateCreated?: string;
+  parentId?: string;
+  protocol?: string;
+  protocolPath?: string;
+};
+
+type ProtocolsConfigureDescriptor = GenericMessage['descriptor'] & {
+  definition?: Partial<ProtocolDefinition>;
+};
+
+function isRecordsDescriptor(descriptor: GenericMessage['descriptor']): descriptor is RecordsDescriptor {
+  return descriptor.interface === DwnInterfaceName.Records;
+}
+
+function isRecordsWriteDescriptor(descriptor: GenericMessage['descriptor']): descriptor is RecordsDescriptor {
+  return descriptor.interface === DwnInterfaceName.Records && descriptor.method === DwnMethodName.Write;
+}
+
+function isRecordsDeleteDescriptor(descriptor: GenericMessage['descriptor']): descriptor is DescriptorWithRecordId {
+  return descriptor.interface === DwnInterfaceName.Records && descriptor.method === DwnMethodName.Delete;
+}
+
+function isProtocolsConfigureDescriptor(
+  descriptor: GenericMessage['descriptor']
+): descriptor is ProtocolsConfigureDescriptor {
+  return descriptor.interface === DwnInterfaceName.Protocols && descriptor.method === DwnMethodName.Configure;
+}
+
+function getRecordId(message: GenericMessage): string | undefined {
+  return (message as GenericMessage & { recordId?: string }).recordId;
+}
+
+function getProtocolDefinition(message: GenericMessage): Partial<ProtocolDefinition> | undefined {
+  const { descriptor } = message;
+  return isProtocolsConfigureDescriptor(descriptor) ? descriptor.definition : undefined;
+}
+
+function getConfiguredProtocol(message: GenericMessage): string | undefined {
+  const protocol = getProtocolDefinition(message)?.protocol;
+  return typeof protocol === 'string' ? protocol : undefined;
+}
+
+function getComposedProtocolDependencies(message: GenericMessage): string[] {
+  const uses = getProtocolDefinition(message)?.uses;
+  if (!uses) {
+    return [];
+  }
+
+  return Object.values(uses).filter((protocol): protocol is string => typeof protocol === 'string');
+}
+
 /**
  * Checks whether a message is an initial RecordsWrite (not an update).
  * An initial write has dateCreated === messageTimestamp (first write for this recordId).
  */
 function isInitialWrite(message: GenericMessage): boolean {
-  const desc = message.descriptor as any;
-  if (desc.interface !== DwnInterfaceName.Records || desc.method !== DwnMethodName.Write) {
+  const desc = message.descriptor;
+  if (!isRecordsWriteDescriptor(desc)) {
     return false;
   }
   // A RecordsWrite is initial if dateCreated === messageTimestamp (first write for this recordId).
@@ -21,9 +78,10 @@ function isInitialWrite(message: GenericMessage): boolean {
  *
  * Dependencies:
  * - ProtocolsConfigure must come before any RecordsWrite using that protocol
+ * - Composed ProtocolsConfigure must come after ProtocolsConfigure messages for protocols in `uses`
  * - Parent record must come before child record (via parentId)
  * - Initial write must come before update writes (same recordId, not initial)
- * - Permission grant must come before records using that permissionGrantId
+ * - Permission grants must come before messages that invoke them
  */
 export function topologicalSort<T extends { message: GenericMessage }>(
   messages: T[]
@@ -44,14 +102,14 @@ export function topologicalSort<T extends { message: GenericMessage }>(
     const desc = entry.message.descriptor;
 
     if (desc.interface === DwnInterfaceName.Protocols && desc.method === DwnMethodName.Configure) {
-      const protocolUrl = (desc as any).definition?.protocol;
+      const protocolUrl = getConfiguredProtocol(entry.message);
       if (protocolUrl) {
         protocolConfigureIndex.set(protocolUrl, i);
       }
     }
 
-    if (desc.interface === DwnInterfaceName.Records && desc.method === DwnMethodName.Write) {
-      const recordId = (entry.message as any).recordId;
+    if (isRecordsWriteDescriptor(desc)) {
+      const recordId = getRecordId(entry.message);
       const initial = isInitialWrite(entry.message);
       if (initial && recordId) {
         initialWriteIndex.set(recordId, i);
@@ -59,8 +117,8 @@ export function topologicalSort<T extends { message: GenericMessage }>(
 
       // Index permission grants by recordId so dependents can reference them.
       if (
-        (desc as any).protocol === PermissionsProtocol.uri &&
-        (desc as any).protocolPath === PermissionsProtocol.grantPath &&
+        desc.protocol === PermissionsProtocol.uri &&
+        desc.protocolPath === PermissionsProtocol.grantPath &&
         recordId
       ) {
         grantIndex.set(recordId, i);
@@ -89,42 +147,52 @@ export function topologicalSort<T extends { message: GenericMessage }>(
   for (let i = 0; i < messages.length; i++) {
     const desc = messages[i].message.descriptor;
 
+    // Composition dependency: a composed protocol depends on its referenced protocol definitions.
+    if (isProtocolsConfigureDescriptor(desc)) {
+      for (const protocol of getComposedProtocolDependencies(messages[i].message)) {
+        if (protocolConfigureIndex.has(protocol)) {
+          addEdge(protocolConfigureIndex.get(protocol)!, i);
+        }
+      }
+    }
+
     // Protocol dependency: RecordsWrite depends on ProtocolsConfigure for its protocol.
-    if (desc.interface === DwnInterfaceName.Records) {
-      const protocol = (desc as any).protocol;
+    if (isRecordsDescriptor(desc)) {
+      const protocol = desc.protocol;
       if (protocol && protocolConfigureIndex.has(protocol)) {
         addEdge(protocolConfigureIndex.get(protocol)!, i);
       }
     }
 
     // Parent dependency: child record depends on parent record.
-    if (desc.interface === DwnInterfaceName.Records && (desc as any).parentId) {
-      const parentId = (desc as any).parentId;
+    if (isRecordsDescriptor(desc) && desc.parentId) {
+      const parentId = desc.parentId;
       if (initialWriteIndex.has(parentId)) {
         addEdge(initialWriteIndex.get(parentId)!, i);
       }
     }
 
     // Initial write dependency: update depends on initial write.
-    if (desc.interface === DwnInterfaceName.Records && desc.method === DwnMethodName.Write) {
-      const recordId = (messages[i].message as any).recordId;
+    if (isRecordsWriteDescriptor(desc)) {
+      const recordId = getRecordId(messages[i].message);
       if (recordId && !isInitialWrite(messages[i].message) && initialWriteIndex.has(recordId)) {
         addEdge(initialWriteIndex.get(recordId)!, i);
       }
     }
 
     // Delete depends on initial write.
-    if (desc.interface === DwnInterfaceName.Records && desc.method === DwnMethodName.Delete) {
-      const recordId = (desc as any).recordId;
+    if (isRecordsDeleteDescriptor(desc)) {
+      const recordId = desc.recordId;
       if (recordId && initialWriteIndex.has(recordId)) {
         addEdge(initialWriteIndex.get(recordId)!, i);
       }
     }
 
-    // Permission grant dependency: message depends on the grant it references.
-    const permissionGrantId = (desc as any).permissionGrantId;
-    if (permissionGrantId && grantIndex.has(permissionGrantId)) {
-      addEdge(grantIndex.get(permissionGrantId)!, i);
+    // Permission grant dependency: message depends on each grant it references.
+    for (const permissionGrantId of getInvokedPermissionGrantIds(messages[i].message)) {
+      if (grantIndex.has(permissionGrantId)) {
+        addEdge(grantIndex.get(permissionGrantId)!, i);
+      }
     }
   }
 

package/src/types/permissions.ts

@@ -79,6 +79,8 @@ export type GetPermissionParams = {
   delegateDid: string;
   messageType: DwnInterface;
   protocol?: string;
+  protocolPath?: string;
+  contextId?: string;
   cached?: boolean;
   delegate?: boolean;
 };

package/src/types/sync.ts

@@ -1,7 +1,16 @@
-import type { ProgressToken } from '@enbox/dwn-sdk-js';
+import type { NormalizedRecordsProjectionScope, ProgressToken, RecordsProjectionScope } from '@enbox/dwn-sdk-js';
 
 import type { EnboxPlatformAgent } from './agent.js';
 
+import { RECORDS_PROJECTION_ROOT_VERSION, RecordsProjection } from '@enbox/dwn-sdk-js';
+
+/** Deterministic bytewise string comparator for hash inputs and canonical IDs. */
+export function lexicographicalCompare(a: string, b: string): number {
+  if (a > b) { return 1; }
+  if (a < b) { return -1; }
+  return 0;
+}
+
 /**
  * The SyncEngine is responsible for syncing messages between the agent and the platform.
  */
@@ -14,6 +23,10 @@ export type SyncIdentityOptions = {
    * The protocols that should be synced for this identity.
    * - `'all'` — sync all protocols (full replica).
    * - `string[]` — sync only the listed protocol URIs.
+   *
+   * Composed protocols are not expanded automatically. If a protocol definition
+   * declares `uses`, include every referenced protocol that the local DWN must
+   * install or use while applying that projection.
    */
   protocols: 'all' | [string, ...string[]];
 };
@@ -34,64 +47,204 @@ 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.
+ * Projection-root algorithm used by StateIndex full/protocol sync scopes.
+ *
+ * Sync compares either the existing full-tenant StateIndex root or existing
+ * per-protocol StateIndex roots. Records-primary projection scopes use the
+ * DWN SDK's `RECORDS_PROJECTION_ROOT_VERSION` instead.
+ */
+export const SYNC_PROJECTION_ROOT_VERSION = 'state-index-full-protocol-root-v1';
+
+/**
+ * Authorization-epoch algorithm used by delegated Messages.Read sync links.
+ *
+ * The authorization epoch is separate from the projection ID: re-granting the
+ * same scope or changing delegate grants must invalidate in-flight work without
+ * changing the primary CID set being compared.
+ */
+export const SYNC_AUTHORIZATION_EPOCH_VERSION = 'messages-read-grants-v1';
+
+/** A non-empty, sorted, duplicate-free string list. */
+export type NonEmptyStringArray = [string, ...string[]];
+
+/** A non-empty, sorted, duplicate-free, subsumption-reduced Records projection scope union. */
+export type NonEmptyRecordsProjectionScopes = [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]];
+
+/**
+ * Describes the primary CID set a replication link syncs.
+ *
+ * Full and protocol-set sync use the existing StateIndex roots. Records
+ * projections use the `records-primary-scope-root-v1` root over latest Records
+ * primary messages selected by protocol, exact protocolPath, or context
+ * subtree. For composed protocols, the scope must include the composed protocol
+ * and any `uses` targets required for local protocol installation and closure
+ * evaluation.
  */
 export type SyncScope = {
-  /** Scope kind. Only `'full'` is implemented in Phase 1. */
+  /** Full-tenant projection. Valid only for owner sync or unscoped delegated grants. */
   kind: 'full';
 } | {
-  /**
-   * Protocol-scoped sync. Deferred to Phase 3 — included here for type
-   * forward-compatibility only.
-   */
-  kind: 'protocol';
-  protocol: string;
-  protocolPathPrefixes?: string[];
-  contextIdPrefixes?: string[];
+  /** Protocol-set projection over one or more protocol roots. */
+  kind: 'protocolSet';
+  protocols: NonEmptyStringArray;
+} | {
+  /** Records-primary projected root over protocol/path/context scope entries. */
+  kind: 'recordsProjection';
+  scopes: NonEmptyRecordsProjectionScopes;
 };
 
 /**
- * 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}`.
+ * Authorization context for a link. Owner links do not invoke grants. Delegate
+ * links carry the active Messages.Read grants that authorize the scope union.
  */
-export async function computeScopeId(scope: SyncScope): Promise<string> {
-  const canonical: Record<string, unknown> = { kind: scope.kind };
-  if (scope.kind === 'protocol') {
-    canonical.protocol = scope.protocol;
-    if (scope.protocolPathPrefixes !== undefined) {
-      canonical.protocolPathPrefixes = [...new Set(scope.protocolPathPrefixes)].sort((a, b) => a.localeCompare(b));
-    }
-    if (scope.contextIdPrefixes !== undefined) {
-      canonical.contextIdPrefixes = [...new Set(scope.contextIdPrefixes)].sort((a, b) => a.localeCompare(b));
-    }
+export type SyncAuthorization =
+  | { kind: 'owner' }
+  | {
+    kind: 'delegate';
+    delegateDid: string;
+    permissionGrantIds: NonEmptyStringArray;
+  };
+
+/** Grant metadata that participates in delegated authorization-epoch hashing. */
+export type SyncAuthorizationGrant = {
+  id: string;
+  dateExpires: string;
+  dateGranted?: string;
+};
+
+/**
+ * Normalizes a protocol list into canonical scope-union order.
+ */
+export function normalizeSyncProtocols(protocols: [string, ...string[]] | string[]): NonEmptyStringArray {
+  const unique = [...new Set(protocols)].sort(lexicographicalCompare);
+  if (unique.length === 0) {
+    throw new Error('SyncScope: protocol-set scope requires at least one protocol URI.');
   }
+  return unique as NonEmptyStringArray;
+}
+
+/** Converts persisted identity options into the canonical sync scope. */
+export function syncScopeFromProtocols(protocols: SyncIdentityOptions['protocols']): SyncScope {
+  return protocols === 'all'
+    ? { kind: 'full' }
+    : { kind: 'protocolSet', protocols: normalizeSyncProtocols(protocols) };
+}
+
+/** Converts Records projection scopes into the canonical sync scope shape. */
+export function syncScopeFromRecordsProjectionScopes(
+  scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]],
+): Extract<SyncScope, { kind: 'recordsProjection' }> {
+  return {
+    kind   : 'recordsProjection',
+    scopes : RecordsProjection.normalizeScopes(scopes),
+  };
+}
+
+/** Returns the protocol list covered by a scope, or `undefined` for full scope. */
+export function protocolsForSyncScope(scope: SyncScope): NonEmptyStringArray | undefined {
+  if (scope.kind === 'full') {
+    return undefined;
+  }
+
+  if (scope.kind === 'protocolSet') {
+    return scope.protocols;
+  }
+
+  return normalizeSyncProtocols(scope.scopes.map(scope => scope.protocol));
+}
 
-  // Stable JSON: keys sorted by construction order (kind < protocol < protocolPathPrefixes).
-  const json = JSON.stringify(canonical);
+/** Returns the single protocol root covered by a protocol-set scope, if any. */
+export function singleProtocolForSyncScope(scope: SyncScope): string | undefined {
+  return scope.kind === 'protocolSet' && scope.protocols.length === 1 ? scope.protocols[0] : undefined;
+}
+
+/** Stable base64url SHA-256 hash for canonical JSON objects. */
+async function hashCanonicalObject(value: Record<string, unknown>): Promise<string> {
+  const json = JSON.stringify(value);
   const bytes = new TextEncoder().encode(json);
   const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
   const hashArray = new Uint8Array(hashBuffer);
 
-  // base64url encode (no padding).
   let base64 = '';
   for (const b of hashArray) {
     base64 += String.fromCharCode(b);
   }
   const result = btoa(base64).replaceAll('+', '-').replaceAll('/', '_');
-  // Strip trailing '=' padding without regex quantifiers (avoids ReDoS scanners).
   let end = result.length;
-  while (end > 0 && result.codePointAt(end - 1) === 61) { end--; } // 61 === '='
+  while (end > 0 && result.codePointAt(end - 1) === 61) { end--; }
   return end === result.length ? result : result.slice(0, end);
 }
 
+/** Returns a canonical JSON-ready representation of a sync scope. */
+export function canonicalizeSyncScope(scope: SyncScope): SyncScope {
+  if (scope.kind === 'full') {
+    return { kind: 'full' };
+  }
+
+  if (scope.kind === 'protocolSet') {
+    return { kind: 'protocolSet', protocols: normalizeSyncProtocols(scope.protocols) };
+  }
+
+  return {
+    kind   : 'recordsProjection',
+    scopes : RecordsProjection.normalizeScopes(scope.scopes),
+  };
+}
+
+/**
+ * Computes a deterministic, collision-resistant projection ID.
+ *
+ * The projection ID is derived from tenant DID, normalized scope, and the
+ * projection-root algorithm version. It intentionally excludes endpoint,
+ * grant IDs, authorization epoch, and remote diff contents.
+ */
+export async function computeProjectionId(tenantDid: string, scope: SyncScope): Promise<string> {
+  const canonicalScope = canonicalizeSyncScope(scope);
+  const version = canonicalScope.kind === 'recordsProjection'
+    ? RECORDS_PROJECTION_ROOT_VERSION
+    : SYNC_PROJECTION_ROOT_VERSION;
+
+  return hashCanonicalObject({
+    scope: canonicalScope,
+    tenantDid,
+    version,
+  });
+}
+
+/**
+ * Computes the authorization epoch for a link.
+ *
+ * Owner epochs are stable for the owner projection. Delegate epochs are derived
+ * from the delegate DID plus the active grant IDs and expiry metadata. A changed
+ * grant set creates a new link key even when the projection ID is unchanged.
+ */
+export async function computeAuthorizationEpoch(input:
+  | { kind: 'owner' }
+  | { kind: 'delegate'; delegateDid: string; grants: [SyncAuthorizationGrant, ...SyncAuthorizationGrant[]] }
+): Promise<string> {
+  if (input.kind === 'owner') {
+    return hashCanonicalObject({
+      kind    : 'owner',
+      version : SYNC_AUTHORIZATION_EPOCH_VERSION,
+    });
+  }
+
+  const grants = [...input.grants]
+    .sort((a, b) => lexicographicalCompare(a.id, b.id))
+    .map(grant => ({
+      dateExpires : grant.dateExpires,
+      dateGranted : grant.dateGranted,
+      id          : grant.id,
+    }));
+
+  return hashCanonicalObject({
+    delegateDid : input.delegateDid,
+    grants,
+    kind        : 'delegate',
+    version     : SYNC_AUTHORIZATION_EPOCH_VERSION,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Replication checkpoint types
 // ---------------------------------------------------------------------------
@@ -137,16 +290,18 @@ export type DirectionCheckpoint = {
  *
  * - `initializing` — link created, no subscriptions open yet.
  * - `live` — actively receiving events via subscription.
+ * - `polling` — current link is reconciled by periodic SMT sync; live subscription is not supported for its scope.
  * - `repairing` — gap detected or pending overflow; running SMT reconciliation.
  * - `degraded_poll` — subscription failed; polling at reduced frequency.
+ * - `terminal_incomplete` — closure failed with a terminal dependency error; requires a new scope/authorization epoch.
  * - `paused` — explicitly paused by the application.
  */
-export type LinkStatus = 'initializing' | 'live' | 'repairing' | 'degraded_poll' | 'paused';
+export type LinkStatus = 'initializing' | 'live' | 'polling' | 'repairing' | 'degraded_poll' | 'terminal_incomplete' | '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)`.
+ * `(tenantDid, remoteEndpoint, projectionId, authorizationEpoch)`.
  */
 export type ReplicationLinkState = {
   /** The tenant DID this link syncs for. */
@@ -155,12 +310,18 @@ export type ReplicationLinkState = {
   /** The remote DWN endpoint URL. */
   remoteEndpoint: string;
 
-  /** Deterministic hash of the {@link SyncScope}. See {@link computeScopeId}. */
-  scopeId: string;
+  /** Deterministic hash of tenant DID, normalized scope, and root algorithm version. */
+  projectionId: string;
+
+  /** Deterministic hash of owner/delegate grant context for this link. */
+  authorizationEpoch: string;
 
   /** The scope definition this link covers. */
   scope: SyncScope;
 
+  /** Owner/delegate authorization context used to sign sync messages. */
+  authorization: SyncAuthorization;
+
   /** Current link status. */
   status: LinkStatus;
 
@@ -181,15 +342,6 @@ export type ReplicationLinkState = {
   /** 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;
 };
@@ -230,7 +382,7 @@ export type StartSyncParams = {
    *   push. Falls back to SMT reconciliation on cold start or long disconnect.
    *   An infrequent SMT integrity check still runs at `interval`.
    *
-   * - `'poll'`: Legacy mode. Performs a full SMT set-reconciliation sync on a
+   * - `'poll'`: Performs a full SMT set-reconciliation sync on a
    *   fixed interval. No WebSocket subscriptions are used.
    */
   mode?: SyncMode;
@@ -251,22 +403,35 @@ export type StartSyncParams = {
 // Sync observability events
 // ---------------------------------------------------------------------------
 
+/** Sync scope metadata attached to observability events. */
+export type SyncEventScope = {
+  /** Present only when the event belongs to a single-protocol link. */
+  protocol?: string;
+  /** Present when the event belongs to a protocol-set link. */
+  protocols?: NonEmptyStringArray;
+};
+
+type SyncEventBase = {
+  tenantDid: string;
+  remoteEndpoint: string;
+} & SyncEventScope;
+
 /**
  * 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: '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 }
-  | { type: 'degraded-poll:entered'; tenantDid: string; remoteEndpoint: string; protocol?: string }
-  | { type: 'gap:detected'; tenantDid: string; remoteEndpoint: string; protocol?: string; reason: string };
+  | SyncEventBase & { type: 'link:status-change'; from: LinkStatus; to: LinkStatus }
+  | SyncEventBase & { type: 'link:connectivity-change'; from: SyncConnectivityState; to: SyncConnectivityState }
+  | SyncEventBase & { type: 'checkpoint:pull-advance'; position: string; messageCid: string }
+  | SyncEventBase & { type: 'reconcile:needed'; reason: string }
+  | SyncEventBase & { type: 'reconcile:completed' }
+  | SyncEventBase & { type: 'repair:started'; attempt: number }
+  | SyncEventBase & { type: 'repair:completed' }
+  | SyncEventBase & { type: 'repair:failed'; attempt: number; error: string }
+  | SyncEventBase & { type: 'degraded-poll:entered' }
+  | SyncEventBase & { type: 'gap:detected'; reason: string };
 
 export type SyncEventListener = (event: SyncEvent) => void;
 
@@ -275,7 +440,7 @@ export type SyncEventListener = (event: SyncEvent) => void;
 // ---------------------------------------------------------------------------
 
 /** Category of sync failure for dead letter entries. */
-export type DeadLetterCategory = 'push-permanent' | 'push-exhausted' | 'pull-processing' | 'closure';
+export type DeadLetterCategory = 'push-permanent' | 'push-exhausted' | 'pull-processing' | 'pull-scope-rejected' | 'closure';
 
 /** A message that permanently failed to sync. */
 export type DeadLetterEntry = {
@@ -312,8 +477,16 @@ export type SyncHealthSummary = {
    * the engine self-heals — entries are auto-cleared on later success.
    */
   failedMessageCount: number;
-  /** Number of links currently in 'repairing' or 'degraded_poll' status. */
+  /**
+   * Number of current closure failures. A link can have matching sync roots
+   * while still being unusable because required dependencies are missing; this
+   * count keeps that state visible to callers.
+   */
+  closureFailureCount: number;
+  /** Number of current sync links in 'repairing', 'degraded_poll', or terminal-incomplete status. */
   degradedLinkCount: number;
+  /** True only when there are no failed messages and no degraded links. */
+  syncHealthy: boolean;
 };
 
 export interface SyncEngine {