@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/sync/central-version-storage.js

@@ -0,0 +1,387 @@
+/**
+ * Central Version Storage — DIS-backed version snapshot storage.
+ *
+ * Implements IVersionStorage using the Data Ingest Service (DIS) as the backing
+ * store, attaching a system widget (`_ema_versions`) to each persona.
+ *
+ * Design:
+ * - Each version is a JSON file: `v{NNN}__{hash}.json`
+ * - A `_manifest.json` file tracks all versions for efficient listing
+ * - A `_policy.json` file stores per-persona versioning policy
+ * - DIS has no overwrite — re-uploads create duplicates. Cleaned up on read.
+ * - Manifest reconciliation rebuilds from DIS scan if counts mismatch.
+ *
+ * ───────────────────────────────────────────────────────────────────────────────
+ * TODO(data-snapshots): Future — Data Source Snapshot Support
+ * ───────────────────────────────────────────────────────────────────────────────
+ *
+ * Currently, persona versions capture config + workflow + data source REFERENCES
+ * (file_id, filename, widget_name) but not the actual file contents. This means:
+ *
+ * - Restore works for config/workflow (re-pushed via updateAiEmployee)
+ * - Restore does NOT restore deleted data source files
+ * - The `data_sources` array in the snapshot is a point-in-time inventory
+ *
+ * To support full data restore, consider:
+ *
+ * 1. **On snapshot**: For each DataSourceRef, download the file content from DIS
+ *    and upload it into `_ema_versions` with a name like `data_v{N}__{file_id}.bin`.
+ *    Pro: complete restore. Con: doubles storage, N downloads per snapshot.
+ *
+ * 2. **On restore**: For each DataSourceRef in the snapshot, check if file_id
+ *    still exists (via list). If missing, either warn or re-upload from the
+ *    backed-up copy. Pro: graceful degradation. Con: requires backup from (1).
+ *
+ * 3. **Deferred download**: Don't back up files on snapshot. On restore, check
+ *    existence and warn about missing files. Cheapest option — works if files
+ *    are rarely deleted. Pro: zero overhead. Con: lossy restore.
+ *
+ * 4. **Content-addressable dedup**: Store file content keyed by hash. Multiple
+ *    versions sharing the same file reference one copy. Pro: optimal storage.
+ *    Con: complex, needs hash computation for every file on snapshot.
+ *
+ * Implementation hooks (where to add this):
+ * - `saveVersion()` — optionally download + store data source files
+ * - `getRestoreData()` in VersionPolicyEngine — check file existence, include re-upload plan
+ * - `version.ts` restore handler — execute re-upload plan if files were backed up
+ * - `pruneVersions()` — also clean up backed-up data files for pruned versions
+ *
+ * See also: DataSourceRef TODO in version-tracking.ts
+ * ───────────────────────────────────────────────────────────────────────────────
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const MANIFEST_FILENAME = "_manifest.json";
+const POLICY_FILENAME = "_policy.json";
+/** Pattern: v{NNN}__{hash}.json */
+const VERSION_FILE_PATTERN = /^v(\d+)__([a-f0-9]+)\.json$/;
+const DEFAULT_POLICY = {
+    auto_version_on_deploy: true,
+    auto_version_on_sync: true,
+    max_versions: 50,
+    prune_strategy: "oldest",
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// CentralVersionStorage
+// ─────────────────────────────────────────────────────────────────────────────
+export class CentralVersionStorage {
+    port;
+    personaId;
+    /**
+     * @param port - DIS port for file operations
+     * @param personaId - The persona ID this storage is scoped to.
+     *   CentralVersionStorage is constructed per-persona (unlike local storage
+     *   which is per-workspace). Call sites create one per operation.
+     */
+    constructor(port, personaId) {
+        this.port = port;
+        this.personaId = personaId;
+    }
+    // ─────────────── Version CRUD ───────────────
+    async saveVersion(version) {
+        const filename = `v${String(version.version_number).padStart(3, "0")}__${version.content_hash}.json`;
+        const content = Buffer.from(JSON.stringify(version, null, 2), "utf-8");
+        // Upload the version file
+        const fileId = await this.port.upload(this.personaId, filename, content);
+        // Update manifest
+        const manifest = await this.loadManifest();
+        const entry = {
+            id: version.id,
+            version_number: version.version_number,
+            version_name: version.version_name,
+            content_hash: version.content_hash,
+            created_at: version.created_at,
+            created_by: version.created_by,
+            trigger: version.trigger,
+            message: version.message,
+            parent_version_id: version.parent_version_id,
+            dis_file_id: fileId,
+        };
+        // Guard: reconcileManifest may have already added this entry
+        const alreadyExists = manifest.versions.some((v) => v.dis_file_id === fileId || (v.version_number === version.version_number && v.content_hash === version.content_hash));
+        if (!alreadyExists) {
+            manifest.versions.push(entry);
+        }
+        manifest.latest_version_number = version.version_number;
+        manifest.latest_version_id = version.id;
+        manifest.updated_at = new Date().toISOString();
+        await this.saveManifest(manifest);
+    }
+    async getVersion(personaId, versionNumber) {
+        const manifest = await this.loadManifest();
+        const entry = manifest.versions.find((v) => v.version_number === versionNumber);
+        if (!entry)
+            return null;
+        return this.downloadSnapshot(entry.dis_file_id);
+    }
+    async getVersionById(personaId, versionId) {
+        // Check manifest first (avoids downloading all versions)
+        const manifest = await this.loadManifest();
+        const entry = manifest.versions.find((v) => v.id === versionId);
+        if (!entry)
+            return null;
+        return this.downloadSnapshot(entry.dis_file_id);
+    }
+    async getVersionByName(personaId, versionName) {
+        if (versionName === "latest") {
+            return this.getLatestVersion(personaId);
+        }
+        const match = versionName.match(/^v(\d+)$/);
+        if (!match)
+            return null;
+        return this.getVersion(personaId, parseInt(match[1], 10));
+    }
+    async getLatestVersion(personaId) {
+        const manifest = await this.loadManifest();
+        if (manifest.versions.length === 0)
+            return null;
+        // Sort descending and pick the latest
+        const sorted = [...manifest.versions].sort((a, b) => b.version_number - a.version_number);
+        return this.downloadSnapshot(sorted[0].dis_file_id);
+    }
+    // ─────────────── Listing & Queries ───────────────
+    async listVersions(_personaId) {
+        const manifest = await this.loadManifest();
+        // Return without DIS-specific fields
+        return manifest.versions.map(({ dis_file_id, ...entry }) => entry);
+    }
+    async hasContentHash(_personaId, contentHash) {
+        const manifest = await this.loadManifest();
+        return manifest.versions.some((v) => v.content_hash === contentHash);
+    }
+    async getNextVersionNumber(_personaId) {
+        const manifest = await this.loadManifest();
+        if (manifest.versions.length === 0)
+            return 1;
+        // Compute from actual entries — don't trust latest_version_number field
+        const maxVer = Math.max(...manifest.versions.map((v) => v.version_number));
+        return maxVer + 1;
+    }
+    async getManifest(_personaId) {
+        const manifest = await this.loadManifest();
+        if (manifest.versions.length === 0 && manifest.latest_version_number === 0) {
+            return null;
+        }
+        // Strip DIS-specific fields for the public interface
+        // Compute latest from actual entries (not stored field which may be stale)
+        const latestEntry = manifest.versions.length > 0
+            ? [...manifest.versions].sort((a, b) => b.version_number - a.version_number)[0]
+            : null;
+        return {
+            persona_id: manifest.persona_id,
+            environment: manifest.environment,
+            latest_version_id: latestEntry?.id ?? null,
+            latest_version_number: latestEntry?.version_number ?? 0,
+            versions: manifest.versions.map(({ dis_file_id, ...entry }) => entry),
+            updated_at: manifest.updated_at,
+        };
+    }
+    // ─────────────── Policy ───────────────
+    async getPolicy(personaId) {
+        const files = await this.port.list(this.personaId);
+        const policyFiles = files.filter((f) => f.filename === POLICY_FILENAME);
+        if (policyFiles.length === 0) {
+            return { persona_id: personaId, ...DEFAULT_POLICY };
+        }
+        // Cleanup duplicates (DIS has no overwrite)
+        if (policyFiles.length > 1) {
+            await this.cleanupDuplicates(policyFiles);
+        }
+        try {
+            // Download the most recent one (last uploaded)
+            const latest = policyFiles[policyFiles.length - 1];
+            const buf = await this.port.download(latest.file_id);
+            const policy = JSON.parse(buf.toString("utf-8"));
+            return { ...DEFAULT_POLICY, ...policy, persona_id: personaId };
+        }
+        catch {
+            return { persona_id: personaId, ...DEFAULT_POLICY };
+        }
+    }
+    async savePolicy(policy) {
+        const content = Buffer.from(JSON.stringify(policy, null, 2), "utf-8");
+        await this.port.upload(this.personaId, POLICY_FILENAME, content);
+        // Best-effort cleanup of old policy files
+        const files = await this.port.list(this.personaId);
+        const policyFiles = files.filter((f) => f.filename === POLICY_FILENAME);
+        if (policyFiles.length > 1) {
+            await this.cleanupDuplicates(policyFiles);
+        }
+    }
+    // ─────────────── Maintenance ───────────────
+    async pruneVersions(_personaId) {
+        const policy = await this.getPolicy(this.personaId);
+        const maxVersions = policy.max_versions ?? 50;
+        const manifest = await this.loadManifest();
+        if (manifest.versions.length <= maxVersions)
+            return 0;
+        // Sort oldest first
+        const sorted = [...manifest.versions].sort((a, b) => a.version_number - b.version_number);
+        const toRemove = sorted.slice(0, sorted.length - maxVersions);
+        // Track which file IDs were actually deleted — only remove those from manifest
+        const deletedFileIds = new Set();
+        for (const entry of toRemove) {
+            try {
+                await this.port.delete(this.personaId, entry.dis_file_id);
+                deletedFileIds.add(entry.dis_file_id);
+            }
+            catch {
+                // Keep in manifest — DIS file still exists
+            }
+        }
+        // Only remove manifest entries for successfully deleted files
+        manifest.versions = manifest.versions.filter((v) => !deletedFileIds.has(v.dis_file_id));
+        // Recompute latest_version_number from remaining entries
+        if (manifest.versions.length > 0) {
+            const maxVer = Math.max(...manifest.versions.map((v) => v.version_number));
+            manifest.latest_version_number = maxVer;
+            const latestEntry = manifest.versions.find((v) => v.version_number === maxVer);
+            manifest.latest_version_id = latestEntry?.id ?? null;
+        }
+        else {
+            manifest.latest_version_number = 0;
+            manifest.latest_version_id = null;
+        }
+        manifest.updated_at = new Date().toISOString();
+        await this.saveManifest(manifest);
+        return deletedFileIds.size;
+    }
+    // ─────────────── Private Helpers ───────────────
+    /**
+     * Load the manifest from DIS, with cleanup-on-read for duplicates
+     * and reconciliation if the manifest is missing/corrupt.
+     */
+    async loadManifest() {
+        const files = await this.port.list(this.personaId);
+        const manifestFiles = files.filter((f) => f.filename === MANIFEST_FILENAME);
+        if (manifestFiles.length === 0) {
+            // No manifest — try to reconcile from version files
+            return this.reconcileManifest(files);
+        }
+        // Cleanup duplicate manifests
+        if (manifestFiles.length > 1) {
+            await this.cleanupDuplicates(manifestFiles);
+        }
+        try {
+            // Download the most recent manifest
+            const latest = manifestFiles[manifestFiles.length - 1];
+            const buf = await this.port.download(latest.file_id);
+            const manifest = JSON.parse(buf.toString("utf-8"));
+            // Validate: count version files in DIS vs manifest entries
+            const versionFiles = files.filter((f) => VERSION_FILE_PATTERN.test(f.filename));
+            if (versionFiles.length !== manifest.versions.length) {
+                // Mismatch — reconcile from DIS
+                return this.reconcileManifest(files);
+            }
+            return manifest;
+        }
+        catch {
+            // Corrupt manifest — reconcile from DIS
+            return this.reconcileManifest(files);
+        }
+    }
+    /**
+     * Rebuild manifest by scanning version files in DIS.
+     */
+    async reconcileManifest(files) {
+        const versionFiles = files.filter((f) => VERSION_FILE_PATTERN.test(f.filename));
+        const entries = [];
+        let maxVersionNumber = 0;
+        for (const file of versionFiles) {
+            const match = file.filename.match(VERSION_FILE_PATTERN);
+            if (!match)
+                continue;
+            const versionNumber = parseInt(match[1], 10);
+            // Download to get full metadata
+            try {
+                const buf = await this.port.download(file.file_id);
+                const snapshot = JSON.parse(buf.toString("utf-8"));
+                entries.push({
+                    id: snapshot.id,
+                    version_number: snapshot.version_number,
+                    version_name: snapshot.version_name,
+                    content_hash: snapshot.content_hash,
+                    created_at: snapshot.created_at,
+                    created_by: snapshot.created_by,
+                    trigger: snapshot.trigger,
+                    message: snapshot.message,
+                    parent_version_id: snapshot.parent_version_id,
+                    dis_file_id: file.file_id,
+                });
+                if (versionNumber > maxVersionNumber) {
+                    maxVersionNumber = versionNumber;
+                }
+            }
+            catch {
+                // Skip corrupt version files during reconciliation
+            }
+        }
+        // Sort by version number
+        entries.sort((a, b) => a.version_number - b.version_number);
+        const latestEntry = entries.length > 0 ? entries[entries.length - 1] : null;
+        const manifest = {
+            persona_id: this.personaId,
+            environment: "central",
+            latest_version_id: latestEntry?.id ?? null,
+            latest_version_number: maxVersionNumber,
+            versions: entries,
+            updated_at: new Date().toISOString(),
+        };
+        // Save the reconciled manifest (if there are any versions)
+        if (entries.length > 0) {
+            await this.saveManifest(manifest);
+        }
+        return manifest;
+    }
+    /**
+     * Save manifest to DIS. Uploads a new copy and cleans up old ones.
+     */
+    async saveManifest(manifest) {
+        const content = Buffer.from(JSON.stringify(manifest, null, 2), "utf-8");
+        await this.port.upload(this.personaId, MANIFEST_FILENAME, content);
+        // Best-effort cleanup of old manifest files
+        const files = await this.port.list(this.personaId);
+        const manifestFiles = files.filter((f) => f.filename === MANIFEST_FILENAME);
+        if (manifestFiles.length > 1) {
+            await this.cleanupDuplicates(manifestFiles);
+        }
+    }
+    /**
+     * Download and parse a version snapshot by file ID.
+     */
+    async downloadSnapshot(fileId) {
+        try {
+            const buf = await this.port.download(fileId);
+            return JSON.parse(buf.toString("utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Clean up duplicate files (DIS has no overwrite), keeping the most recent.
+     * Deletes all but the last entry (assumed most recently uploaded).
+     */
+    async cleanupDuplicates(files) {
+        // Keep the last one (most recently uploaded), delete the rest
+        const toDelete = files.slice(0, files.length - 1);
+        for (const file of toDelete) {
+            try {
+                await this.port.delete(this.personaId, file.file_id);
+            }
+            catch {
+                // Best-effort
+            }
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a CentralVersionStorage instance scoped to a persona.
+ */
+export function createCentralVersionStorage(port, personaId) {
+    return new CentralVersionStorage(port, personaId);
+}

package/dist/sync/dis-port.js

@@ -0,0 +1,75 @@
+/**
+ * DIS Port - Dependency injection interface for Data Ingest Service operations.
+ *
+ * DISPort abstracts the DIS operations needed by CentralVersionStorage,
+ * enabling both production (DISAdapter → SDK) and test (MockDISPort → Map) usage.
+ */
+/** System widget name for version storage. Prefixed with `_` to exclude from search/validation. */
+export const SYSTEM_WIDGET_NAME = "_ema_versions";
+/** ContentNodeStatus values for soft-deleted files (still appear in listings during deletion). */
+const DELETED_STATUSES = new Set([5 /* DELETE_IN_PROGRESS */, 7 /* DELETED */]);
+/**
+ * Production DIS adapter wrapping the SDK client (EmaClientV2).
+ */
+export class DISAdapter {
+    client;
+    personaIdForAuth;
+    constructor(client, personaIdForAuth) {
+        this.client = client;
+        this.personaIdForAuth = personaIdForAuth;
+    }
+    async upload(personaId, filename, content) {
+        const result = await this.client.uploadDataSource(personaId, content, filename, {
+            widgetName: SYSTEM_WIDGET_NAME,
+            tags: SYSTEM_WIDGET_NAME,
+            mimeType: "application/json",
+        });
+        return result.fileId;
+    }
+    async list(personaId) {
+        const allFiles = [];
+        let page = 1;
+        const limit = 100;
+        // Paginate through all files
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const resp = await this.client.listDataSourceFiles(personaId, {
+                widgetName: SYSTEM_WIDGET_NAME,
+                page,
+                limit,
+            });
+            for (const node of resp.data) {
+                // Skip soft-deleted files (still appear in listings during DIS deletion)
+                if (node.status != null && DELETED_STATUSES.has(node.status))
+                    continue;
+                allFiles.push({
+                    file_id: node.id,
+                    filename: node.nodeName,
+                    created_at: node.createdAt
+                        ? new Date(Number(node.createdAt.seconds) * 1000).toISOString()
+                        : undefined,
+                });
+            }
+            // Exit when: no pagination info, at last page, or no data returned
+            const pagination = resp.pagination;
+            if (!pagination || page >= pagination.totalPages || resp.data.length === 0) {
+                break;
+            }
+            page++;
+        }
+        return allFiles;
+    }
+    async download(fileId) {
+        return this.client.downloadFile(fileId, this.personaIdForAuth);
+    }
+    async delete(personaId, fileId) {
+        try {
+            await this.client.deleteDataSource(personaId, fileId, {
+                widgetName: SYSTEM_WIDGET_NAME,
+            });
+        }
+        catch {
+            // Best-effort: file may already be gone
+        }
+    }
+}

package/dist/sync/version-policy.js

@@ -4,6 +4,8 @@
  * Handles automatic versioning decisions based on policies.
  * Determines when to create snapshots, manages retention, and
  * enforces versioning rules.
+ *
+ * All methods are async to support both local and central (DIS) storage.
  */
 import { createVersionSnapshot, hashSnapshot, createSnapshotFromPersona, generateChangesSummary, compareVersions, } from "./version-tracking.js";
 // ─────────────────────────────────────────────────────────────────────────────
@@ -18,12 +20,12 @@ export class VersionPolicyEngine {
     /**
      * Check if a version should be created for a persona.
      */
-    checkPolicy(persona, trigger) {
-        const policy = this.storage.getPolicy(persona.id);
+    async checkPolicy(persona, trigger) {
+        const policy = await this.storage.getPolicy(persona.id);
         const snapshot = createSnapshotFromPersona(persona);
         const contentHash = hashSnapshot(snapshot);
         // Check if this would be a duplicate
-        const isDuplicate = this.storage.hasContentHash(persona.id, contentHash);
+        const isDuplicate = await this.storage.hasContentHash(persona.id, contentHash);
         // Determine if we should create based on trigger and policy
         let shouldCreate = false;
         let reason = "";
@@ -69,7 +71,7 @@ export class VersionPolicyEngine {
             case "auto":
                 // Check interval if specified
                 if (policy.min_interval) {
-                    const latest = this.storage.getLatestVersion(persona.id);
+                    const latest = await this.storage.getLatestVersion(persona.id);
                     if (latest && !this.hasIntervalPassed(latest.created_at, policy.min_interval)) {
                         shouldCreate = false;
                         skipReason = `Minimum interval (${policy.min_interval}) not yet passed`;
@@ -122,6 +124,9 @@ export class VersionPolicyEngine {
             intervalMs += parseInt(minutes, 10) * 60 * 1000;
         if (days)
             intervalMs += parseInt(days, 10) * 24 * 60 * 60 * 1000;
+        // Unrecognized format → interval not passed (safe default: don't auto-create)
+        if (intervalMs === 0)
+            return false;
         return now.getTime() - last.getTime() >= intervalMs;
     }
     // ─────────────── Version Creation ───────────────
@@ -129,9 +134,9 @@ export class VersionPolicyEngine {
      * Create a version if policy allows.
      * This is the main entry point for automatic versioning.
      */
-    createVersionIfAllowed(persona, trigger, options) {
+    async createVersionIfAllowed(persona, trigger, options) {
         // Check policy (unless forced)
-        const check = this.checkPolicy(persona, trigger);
+        const check = await this.checkPolicy(persona, trigger);
         if (!options.force && !check.should_create_version) {
             return {
                 created: false,
@@ -140,7 +145,7 @@ export class VersionPolicyEngine {
             };
         }
         // Get parent version info
-        const latest = this.storage.getLatestVersion(persona.id);
+        const latest = await this.storage.getLatestVersion(persona.id);
         const previousVersionNumber = latest?.version_number;
         const parentVersionId = latest?.id;
         // Create the version
@@ -162,9 +167,9 @@ export class VersionPolicyEngine {
             version.changes_summary = changesFromParent;
         }
         // Save the version
-        this.storage.saveVersion(version);
+        await this.storage.saveVersion(version);
         // Prune if necessary
-        const versionsPruned = this.storage.pruneVersions(persona.id);
+        const versionsPruned = await this.storage.pruneVersions(persona.id);
         return {
             created: true,
             version,
@@ -176,7 +181,7 @@ export class VersionPolicyEngine {
     /**
      * Force create a version regardless of policy.
      */
-    forceCreateVersion(persona, options) {
+    async forceCreateVersion(persona, options) {
         return this.createVersionIfAllowed(persona, "manual", {
             ...options,
             force: true,
@@ -187,18 +192,18 @@ export class VersionPolicyEngine {
      * Get the snapshot data needed to restore a version.
      * Returns the persona configuration that can be applied via updateAiEmployee.
      */
-    getRestoreData(personaId, versionIdentifier) {
+    async getRestoreData(personaId, versionIdentifier) {
         // Get the version
         let version = null;
         if (typeof versionIdentifier === "number") {
-            version = this.storage.getVersion(personaId, versionIdentifier);
+            version = await this.storage.getVersion(personaId, versionIdentifier);
         }
         else if (versionIdentifier.match(/^v\d+$/)) {
-            version = this.storage.getVersionByName(personaId, versionIdentifier);
+            version = await this.storage.getVersionByName(personaId, versionIdentifier);
         }
         else {
             // Assume it's a version ID
-            version = this.storage.getVersionById(personaId, versionIdentifier);
+            version = await this.storage.getVersionById(personaId, versionIdentifier);
         }
         if (!version) {
             return {
@@ -226,28 +231,28 @@ export class VersionPolicyEngine {
     /**
      * Get policy for a persona.
      */
-    getPolicy(personaId) {
+    async getPolicy(personaId) {
         return this.storage.getPolicy(personaId);
     }
     /**
      * Update policy for a persona.
      */
-    updatePolicy(personaId, updates) {
-        const current = this.storage.getPolicy(personaId);
+    async updatePolicy(personaId, updates) {
+        const current = await this.storage.getPolicy(personaId);
         const updated = {
             ...current,
             ...updates,
             persona_id: personaId, // Ensure this is always set
         };
-        this.storage.savePolicy(updated);
+        await this.storage.savePolicy(updated);
         return updated;
     }
     // ─────────────── Query Methods ───────────────
     /**
      * List versions for a persona with optional filtering.
      */
-    listVersions(personaId, options) {
-        let versions = this.storage.listVersions(personaId);
+    async listVersions(personaId, options) {
+        let versions = await this.storage.listVersions(personaId);
         // Apply filters
         if (options?.trigger) {
             versions = versions.filter((v) => v.trigger === options.trigger);
@@ -275,7 +280,7 @@ export class VersionPolicyEngine {
     /**
      * Get a specific version with full details.
      */
-    getVersion(personaId, versionIdentifier) {
+    async getVersion(personaId, versionIdentifier) {
         if (versionIdentifier === "latest") {
             return this.storage.getLatestVersion(personaId);
         }
@@ -292,9 +297,9 @@ export class VersionPolicyEngine {
     /**
      * Compare two versions.
      */
-    compareVersions(personaId, v1Identifier, v2Identifier) {
-        const v1 = this.getVersion(personaId, v1Identifier);
-        const v2 = this.getVersion(personaId, v2Identifier);
+    async compareVersions(personaId, v1Identifier, v2Identifier) {
+        const v1 = await this.getVersion(personaId, v1Identifier);
+        const v2 = await this.getVersion(personaId, v2Identifier);
         if (!v1) {
             return { success: false, error: `Version not found: ${v1Identifier}` };
         }
@@ -309,13 +314,6 @@ export class VersionPolicyEngine {
             summary,
         };
     }
-    // ─────────────── Storage Access ───────────────
-    /**
-     * Get the underlying storage instance.
-     */
-    getStorage() {
-        return this.storage;
-    }
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory Function

package/dist/sync/version-storage-interface.js

@@ -0,0 +1,11 @@
+/**
+ * IVersionStorage - Async contract for version snapshot storage.
+ *
+ * Implemented by:
+ * - VersionStorage (local file-based, .ema-versions/)
+ * - CentralVersionStorage (DIS-backed, _ema_versions widget)
+ *
+ * All methods return Promise<T> to accommodate async DIS operations.
+ * Local storage wraps synchronous fs calls in Promise.resolve().
+ */
+export {};