@majikah/majik-message 0.3.5 → 0.3.7

package/dist/core/contacts/majik-contact-manager.js

@@ -1,36 +1,18 @@
-/* -------------------------------
- * Types
- * ------------------------------- */
+import { MajikContact, } from "@majikah/majik-contact";
 import { MajikContactDirectory } from "./majik-contact-directory";
 import { MajikContactGroupManager } from "./majik-contact-groups";
 import { MajikContactManagerError } from "./errors";
-/* -------------------------------
- * MajikContactManager Class
- * ------------------------------- */
-/**
- * Unified facade over MajikContactDirectory and MajikContactGroupManager.
- *
- * Responsibilities:
- *  - Owns both the directory and the group manager as a single cohesive unit
- *  - Proxies all directory methods so MajikMessage call sites need only change
- *    `contactDirectory` → `contacts` with no logic changes
- *  - Wires lifecycle hooks automatically so callers can never forget them:
- *      • removeContact()  → always calls groups.handleContactRemoved()
- *      • blockContact()   → always syncs the Blocked system group
- *      • unblockContact() → always syncs the Blocked system group
- *  - Exposes the group manager via `.group` for all group-specific operations
- *  - Serializes both directory and groups into one unified payload for
- *    MajikMessage.toJSON() / MajikMessage.fromJSON()
- *
- * Construction:
- *  - Pass nothing → fresh directory + fresh group manager (new session)
- *  - Pass a directory → wraps it, creates a fresh group manager bound to it
- *  - Pass both → fully restores a prior session (used by fromJSON)
- */
+import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, } from "../utils/utilities";
+import { KEY_ALGO } from "../crypto/constants";
+import { gunzipSync, gzipSync } from "fflate";
+import { InMemoryContactAdapter } from "../storage/contact-directory/contacts/adapter-memory";
+import { InMemoryContactGroupAdapter } from "../storage/contact-directory/groups/adapter-memory";
 export class MajikContactManager {
     directory;
     groupManager;
-    constructor(directory, groupManager) {
+    _contactAdapter;
+    _groupAdapter;
+    constructor(directory, groupManager, adapters) {
         this.directory = directory ?? new MajikContactDirectory();
         if (groupManager) {
             this.assertGroupManagerInstance(groupManager);
@@ -39,54 +21,169 @@ export class MajikContactManager {
         else {
             this.groupManager = new MajikContactGroupManager(this.directory);
         }
+        this._contactAdapter = adapters?.contacts ?? new InMemoryContactAdapter();
+        this._groupAdapter = adapters?.groups ?? new InMemoryContactGroupAdapter();
     }
-    /* ================================
-     * Group Manager Access
-     * ================================ */
+    // ── Adapter management ────────────────────────────────────────────────────
+    get contactAdapter() {
+        return this._contactAdapter;
+    }
+    get groupAdapter() {
+        return this._groupAdapter;
+    }
+    /**
+     * Swap both adapters at runtime. Does NOT migrate data.
+     *
+     * Migration pattern:
+     * ```ts
+     * const snap = await manager.toJSON();
+     * manager.setAdapters({ contacts: new IDBContactAdapter(), groups: new IDBGroupAdapter() });
+     * await manager.hydrate();                    // warms from new (empty) adapters
+     * await manager.bulkRestoreFromJSON(snap);    // writes old data into new adapters
+     * ```
+     */
+    setAdapters(adapters) {
+        if (adapters.contacts)
+            this._contactAdapter = adapters.contacts;
+        if (adapters.groups)
+            this._groupAdapter = adapters.groups;
+    }
+    // ── Hydration ─────────────────────────────────────────────────────────────
+    /**
+     * Load all contacts and groups from the adapters into the in-memory
+     * directory and group manager. Call once after construction (or after
+     * swapping adapters).
+     *
+     * Restoration order:
+     *  1. Contacts — must come first so groups can validate member existence.
+     *  2. Groups — restored via groupManager.fromJSON() which rebuilds the
+     *     reverse index and re-bootstraps system groups.
+     *  3. Orphan pruning — any group member ID not present in the restored
+     *     directory is silently removed (guards against data drift).
+     */
+    async hydrate() {
+        // ── 1. Contacts ───────────────────────────────────────────────────────
+        const serializedContacts = await this._contactAdapter.list();
+        this.directory.clear();
+        for (const item of serializedContacts) {
+            try {
+                const raw = base64ToArrayBuffer(item.publicKeyBase64);
+                let publicKey;
+                try {
+                    publicKey = await crypto.subtle.importKey("raw", raw, KEY_ALGO, true, []);
+                }
+                catch {
+                    publicKey = { raw: new Uint8Array(raw) };
+                }
+                const contact = MajikContact.create(item.id, publicKey, item.mlKey, item.fingerprint, item.meta, item.edPublicKeyBase64, item.mlDsaPublicKeyBase64);
+                // Use the internal map directly to avoid addContact's duplicate-check
+                // (re-hydrating from persisted state, not user-facing add)
+                this.directory["contacts"].set(contact.id, contact);
+                this.directory["fingerprintMap"].set(contact.fingerprint, contact.id);
+            }
+            catch (err) {
+                console.warn(`MajikContactManager.hydrate: skipping malformed contact "${item?.id}":`, err);
+            }
+        }
+        // ── 2. Groups ─────────────────────────────────────────────────────────
+        const serializedGroups = await this._groupAdapter.list();
+        this.groupManager.fromJSON({ groups: serializedGroups });
+        // ── 3. Orphan pruning ─────────────────────────────────────────────────
+        MajikContactManager.pruneOrphanedMembers(this.directory, this.groupManager);
+    }
+    // ── Write-through helpers ─────────────────────────────────────────────────
     /**
-     * Direct access to the full MajikContactGroupManager API.
-     * Use for all group-specific operations:
-     *   manager.group.addToFavorites(contactId)
-     *   manager.group.createGroup(id, name)
-     *   manager.group.getContactsInGroup(groupId)
-     *   etc.
+     * Persists a single contact to the adapter (called after every mutating
+     * operation that affects a contact's serialized form).
      */
-    get group() {
-        return this.groupManager;
+    async persistContact(contact) {
+        const json = await contact.toJSON();
+        await this._contactAdapter.save(json);
     }
     /**
-     * Direct access to the underlying MajikContactDirectory.
-     * Prefer the proxied methods on this class over accessing the directory
-     * directly — they keep group state in sync automatically.
+     * Persists a single group to the adapter.
      */
-    get directory_() {
-        return this.directory;
+    async persistGroup(group) {
+        await this._groupAdapter.save(group.toJSON());
     }
-    /* ================================
-     * Contact Management (Proxied)
-     * All signatures are intentionally identical to MajikContactDirectory
-     * so MajikMessage call sites require zero logic changes.
-     * ================================ */
-    addContact(contact) {
+    // ── CRUD ──────────────────────────────────────────────────────────────────
+    /**
+     * Adds a contact to the directory and persists it to the adapter.
+     */
+    async addContact(contact) {
         this.directory.addContact(contact);
+        await this.persistContact(contact);
         return this;
     }
-    addContacts(contacts) {
+    /**
+     * Adds multiple contacts atomically — adapter write uses bulkSave.
+     */
+    async addContacts(contacts) {
         this.directory.addContacts(contacts);
+        const jsons = await Promise.all(contacts.map((c) => c.toJSON()));
+        await this._contactAdapter.bulkSave(jsons);
         return this;
     }
     /**
-     * Removes a contact from the directory and automatically removes them
-     * from every group they belong to via the group manager hook.
-     * The two operations are always atomic from the caller's perspective.
+     * Removes a contact from the directory, all groups, and the adapter.
      */
-    removeContact(id) {
+    async removeContact(id) {
         const result = this.directory.removeContact(id);
         if (result.success) {
             this.groupManager.handleContactRemoved(id);
+            await this._contactAdapter.remove(id);
+            // Persist every group whose membership changed
+            await this._persistAllGroups();
         }
         return result;
     }
+    /**
+     * Updates contact metadata and persists the change.
+     */
+    async updateContactMeta(id, meta) {
+        const contact = this.directory.updateContactMeta(id, meta);
+        await this.persistContact(contact);
+        return contact;
+    }
+    /**
+     * Blocks a contact and persists both the contact and the Blocked group.
+     */
+    async blockContact(id) {
+        const contact = this.directory.blockContact(id);
+        const blocked = this.groupManager.addContactToGroupIfAbsent(this.groupManager.getBlockedGroup().id, id);
+        await this.persistContact(contact);
+        await this.persistGroup(blocked);
+        return contact;
+    }
+    /**
+     * Unblocks a contact and persists both the contact and the Blocked group.
+     */
+    async unblockContact(id) {
+        const contact = this.directory.unblockContact(id);
+        const blocked = this.groupManager.removeContactFromGroupIfPresent(this.groupManager.getBlockedGroup().id, id);
+        await this.persistContact(contact);
+        await this.persistGroup(blocked);
+        return contact;
+    }
+    async setMajikahStatus(id, status) {
+        const contact = this.directory.setMajikahStatus(id, status);
+        await this.persistContact(contact);
+        return contact;
+    }
+    /**
+     * Clears all contacts and groups from both the in-memory stores and adapters.
+     */
+    async clear() {
+        const allContactIds = this.directory.listContacts().map((c) => c.id);
+        this.directory.clear();
+        allContactIds.forEach((id) => this.groupManager.handleContactRemoved(id));
+        this.directory.clear();
+        this.groupManager.clear();
+        await this._contactAdapter.clear();
+        await this._groupAdapter.clear();
+        return this;
+    }
+    // ── Sync reads (unchanged from original) ──────────────────────────────────
     getContact(id) {
         return this.directory.getContact(id);
     }
@@ -108,263 +205,266 @@ export class MajikContactManager {
     listContacts(sortedByLabel = false, majikahOnly = false) {
         return this.directory.listContacts(sortedByLabel, majikahOnly);
     }
-    updateContactMeta(id, meta) {
-        return this.directory.updateContactMeta(id, meta);
-    }
-    /**
-     * Blocks a contact on the directory AND adds them to the system Blocked
-     * group — both sides are always kept in sync.
-     */
-    blockContact(id) {
-        const contact = this.directory.blockContact(id);
-        this.groupManager.addContactToGroupIfAbsent(this.groupManager.getBlockedGroup().id, id);
-        return contact;
-    }
-    /**
-     * Unblocks a contact on the directory AND removes them from the system
-     * Blocked group — both sides are always kept in sync.
-     */
-    unblockContact(id) {
-        const contact = this.directory.unblockContact(id);
-        this.groupManager.removeContactFromGroupIfPresent(this.groupManager.getBlockedGroup().id, id);
-        return contact;
-    }
-    setMajikahStatus(id, status) {
-        return this.directory.setMajikahStatus(id, status);
-    }
     isMajikahRegistered(id) {
         return this.directory.isMajikahRegistered(id);
     }
     isMajikahIdentityChecked(id) {
         return this.directory.isMajikahIdentityChecked(id);
     }
-    hasContactForEnvelope(envelope) {
-        return this.directory.hasContactForEnvelope(envelope);
+    // ── Group CRUD (now async, write-through) ─────────────────────────────────
+    get group() {
+        return this.groupManager;
     }
-    /* ================================
-     * Group CRUD Pass-throughs
-     * ================================ */
-    /**
-     * Creates and registers a new user-defined group.
-     * Throws if a group with the same ID already exists.
-     */
-    createGroup(id, name, meta, initialMemberIds) {
-        return this.groupManager.createGroup(id, name, meta, initialMemberIds);
+    get directory_() {
+        return this.directory;
     }
-    /**
-     * Registers an already-constructed MajikContactGroup instance.
-     * Throws if a group with the same ID already exists.
-     */
-    addGroup(group) {
+    async createGroup(id, name, meta, initialMemberIds) {
+        const group = this.groupManager.createGroup(id, name, meta, initialMemberIds);
+        await this.persistGroup(group);
+        return group;
+    }
+    async addGroup(group) {
         this.groupManager.addGroup(group);
+        await this.persistGroup(group);
         return this;
     }
-    /**
-     * Removes a user group by ID.
-     * System groups (Favorites, Blocked) cannot be deleted.
-     */
-    removeGroup(id) {
-        return this.groupManager.removeGroup(id);
+    async removeGroup(id) {
+        const result = this.groupManager.removeGroup(id);
+        if (result.success) {
+            await this._groupAdapter.remove(id);
+        }
+        return result;
     }
-    /**
-     * Returns a group by ID, or undefined if not found.
-     */
     getGroup(id) {
         return this.groupManager.getGroup(id);
     }
-    /**
-     * Returns a group by ID. Throws if not found.
-     */
     getGroupOrThrow(id) {
         return this.groupManager.getGroupOrThrow(id);
     }
-    /**
-     * Returns true if a group with the given ID exists.
-     */
     hasGroup(id) {
         return this.groupManager.hasGroup(id);
     }
-    /**
-     * Returns all groups.
-     *
-     * @param includeSystem  Include system groups (Favorites, Blocked). Default: true.
-     * @param sortedByName   Sort results alphabetically by group name. Default: false.
-     */
     listGroups(includeSystem = true, sortedByName = false) {
         return this.groupManager.listGroups(includeSystem, sortedByName);
     }
-    /**
-     * Returns only user-created groups (excludes Favorites and Blocked).
-     * Sorted alphabetically by name.
-     */
     listUserGroups(sortedByName = true) {
         return this.groupManager.listGroups(false, sortedByName);
     }
-    /**
-     * Returns only system groups (Favorites and Blocked).
-     */
     listSystemGroups() {
         return this.groupManager.listGroups(true).filter((g) => g.isSystem);
     }
-    /**
-     * Updates mutable metadata on a group (name, description).
-     * Name is locked on system groups — will throw if attempted.
-     */
-    updateGroupMeta(id, meta) {
-        return this.groupManager.updateGroupMeta(id, meta);
-    }
-    /* ================================
-     * Group Membership Pass-throughs
-     * ================================ */
-    /**
-     * Adds a contact to a group.
-     * Validates the contact exists in the directory.
-     * If the group is the system Blocked group, also calls contact.block().
-     * Throws if the contact is already a member — use addContactToGroupIfAbsent for idempotent.
-     */
-    addContactToGroup(groupId, contactId) {
-        return this.groupManager.addContactToGroup(groupId, contactId);
-    }
-    /**
-     * Idempotent variant — does not throw if the contact is already a member.
-     */
-    addContactToGroupIfAbsent(groupId, contactId) {
-        return this.groupManager.addContactToGroupIfAbsent(groupId, contactId);
-    }
-    /**
-     * Adds multiple contacts to a group in one call (all-or-nothing).
-     */
-    addContactsToGroup(groupId, contactIds) {
-        return this.groupManager.addContactsToGroup(groupId, contactIds);
-    }
-    /**
-     * Removes a contact from a group.
-     * If the group is the system Blocked group, also calls contact.unblock().
-     * Throws if the contact is not a member — use removeContactFromGroupIfPresent for idempotent.
-     */
-    removeContactFromGroup(groupId, contactId) {
-        return this.groupManager.removeContactFromGroup(groupId, contactId);
-    }
-    /**
-     * Idempotent variant — does not throw if the contact is not a member.
-     */
-    removeContactFromGroupIfPresent(groupId, contactId) {
-        return this.groupManager.removeContactFromGroupIfPresent(groupId, contactId);
-    }
-    /**
-     * Moves a contact from one group to another atomically.
-     * Throws if the contact is not a member of the source group.
-     */
-    moveContactBetweenGroups(contactId, fromGroupId, toGroupId) {
-        return this.groupManager.moveContact(contactId, fromGroupId, toGroupId);
-    }
-    /* ================================
-     * Group Query Pass-throughs
-     * ================================ */
-    /**
-     * Returns all hydrated MajikContact instances in the given group.
-     * Contacts removed from the directory since last save are silently skipped.
-     */
+    async updateGroupMeta(id, meta) {
+        const group = this.groupManager.updateGroupMeta(id, meta);
+        await this.persistGroup(group);
+        return group;
+    }
+    // ── Group membership (async, write-through) ───────────────────────────────
+    async addContactToGroup(groupId, contactId) {
+        const group = this.groupManager.addContactToGroup(groupId, contactId);
+        await this.persistGroup(group);
+        return group;
+    }
+    async addContactToGroupIfAbsent(groupId, contactId) {
+        const group = this.groupManager.addContactToGroupIfAbsent(groupId, contactId);
+        await this.persistGroup(group);
+        return group;
+    }
+    async addContactsToGroup(groupId, contactIds) {
+        const group = this.groupManager.addContactsToGroup(groupId, contactIds);
+        await this.persistGroup(group);
+        return group;
+    }
+    async removeContactFromGroup(groupId, contactId) {
+        const group = this.groupManager.removeContactFromGroup(groupId, contactId);
+        await this.persistGroup(group);
+        return group;
+    }
+    async removeContactFromGroupIfPresent(groupId, contactId) {
+        const group = this.groupManager.removeContactFromGroupIfPresent(groupId, contactId);
+        await this.persistGroup(group);
+        return group;
+    }
+    async moveContactBetweenGroups(contactId, fromGroupId, toGroupId) {
+        this.groupManager.moveContact(contactId, fromGroupId, toGroupId);
+        // Persist both affected groups
+        const from = this.groupManager.getGroup(fromGroupId);
+        const to = this.groupManager.getGroup(toGroupId);
+        const writes = [];
+        if (from)
+            writes.push(this.persistGroup(from));
+        if (to)
+            writes.push(this.persistGroup(to));
+        await Promise.all(writes);
+    }
+    // ── Group query pass-throughs (sync, unchanged) ───────────────────────────
     getContactsInGroup(groupId) {
         return this.groupManager.getContactsInGroup(groupId);
     }
-    /**
-     * Returns hydrated contacts in the group, sorted by label (or ID if no label).
-     */
     getContactsInGroupSorted(groupId) {
         return this.groupManager.getContactsInGroupSorted(groupId);
     }
-    /**
-     * Returns true if the contact is a member of the given group.
-     */
     isContactInGroup(groupId, contactId) {
         return this.groupManager.isContactInGroup(groupId, contactId);
     }
-    /**
-     * Returns all groups the contact belongs to.
-     */
     getGroupsForContact(contactId) {
         return this.groupManager.getGroupsForContact(contactId);
     }
-    /**
-     * Returns all group IDs the contact belongs to.
-     */
     getGroupIdsForContact(contactId) {
         return this.groupManager.getGroupIdsForContact(contactId);
     }
-    /* ================================
-     * System Group Convenience Pass-throughs
-     * ================================ */
-    /**
-     * Adds the contact to the Favorites group (idempotent).
-     */
-    addToFavorites(contactId) {
-        return this.groupManager.addToFavorites(contactId);
+    // ── System group convenience (async, write-through) ───────────────────────
+    async addToFavorites(contactId) {
+        const group = this.groupManager.addToFavorites(contactId);
+        await this.persistGroup(group);
+        return group;
     }
-    /**
-     * Removes the contact from the Favorites group (idempotent).
-     */
-    removeFromFavorites(contactId) {
-        return this.groupManager.removeFromFavorites(contactId);
+    async removeFromFavorites(contactId) {
+        const group = this.groupManager.removeFromFavorites(contactId);
+        await this.persistGroup(group);
+        return group;
     }
-    /**
-     * Returns true if the contact is in the Favorites group.
-     */
     isFavorite(contactId) {
         return this.groupManager.isFavorite(contactId);
     }
-    /**
-     * Returns true if the contact is in the Blocked group.
-     */
     isContactBlocked(contactId) {
         return this.groupManager.isBlocked(contactId);
     }
-    /**
-     * Returns the Favorites system group instance.
-     */
     getFavoritesGroup() {
         return this.groupManager.getFavoritesGroup();
     }
-    /**
-     * Returns the Blocked system group instance.
-     */
     getBlockedGroup() {
         return this.groupManager.getBlockedGroup();
     }
-    /**
-     * Returns all contacts in the Favorites group as hydrated MajikContact instances.
-     */
     getFavoriteContacts() {
         return this.groupManager.getContactsInGroup(this.groupManager.getFavoritesGroup().id);
     }
-    /**
-     * Returns all contacts in the Blocked group as hydrated MajikContact instances.
-     */
     getBlockedContacts() {
         return this.groupManager.getContactsInGroup(this.groupManager.getBlockedGroup().id);
     }
-    /* ================================
-     * Directory Clear
-     * ================================ */
-    /**
-     * Clears both the directory and all group memberships.
-     * System groups are preserved (re-bootstrapped by the group manager).
-     */
-    clear() {
-        const allContactIds = this.directory.listContacts().map((c) => c.id);
-        this.directory.clear();
-        // Notify the group manager for every contact so the reverse index
-        // and group memberships are cleaned up properly
-        allContactIds.forEach((id) => this.groupManager.handleContactRemoved(id));
-        return this;
+    // ── Import / Export (unchanged) ───────────────────────────────────────────
+    async exportContactAsJSON(contactId) {
+        const contact = this.getContact(contactId);
+        if (!contact)
+            return null;
+        let publicKeyBase64;
+        const anyPub = contact.publicKey;
+        if (anyPub?.raw instanceof Uint8Array) {
+            publicKeyBase64 = arrayBufferToBase64(anyPub.raw.buffer);
+        }
+        else {
+            const raw = await crypto.subtle.exportKey("raw", contact.publicKey);
+            publicKeyBase64 = arrayBufferToBase64(raw);
+        }
+        return JSON.stringify({
+            id: contact.id,
+            label: contact.meta?.label || "",
+            publicKey: publicKeyBase64,
+            fingerprint: contact.fingerprint,
+            mlKey: contact.mlKey,
+            edPublicKeyBase64: contact.edPublicKeyBase64,
+            mlDsaPublicKeyBase64: contact.mlDsaPublicKeyBase64,
+        }, null, 2);
+    }
+    async exportContactAsString(contactId) {
+        const contact = this.getContact(contactId);
+        if (!contact)
+            return null;
+        return this.exportContactCompressed(contact);
+    }
+    async importContactFromJSON(jsonStr) {
+        try {
+            const data = JSON.parse(jsonStr);
+            if (!data.id || !data.publicKey || !data.fingerprint) {
+                return { success: false, message: "Invalid contact JSON" };
+            }
+            const rawBuffer = base64ToArrayBuffer(data.publicKey);
+            let publicKey;
+            try {
+                publicKey = await crypto.subtle.importKey("raw", rawBuffer, KEY_ALGO, true, []);
+            }
+            catch {
+                publicKey = { raw: new Uint8Array(rawBuffer) };
+            }
+            const contact = new MajikContact({
+                id: data.id,
+                publicKey,
+                fingerprint: data.fingerprint,
+                meta: { label: data.label },
+                mlKey: data.mlKey,
+                edPublicKeyBase64: data.edPublicKeyBase64,
+                mlDsaPublicKeyBase64: data.mlDsaPublicKeyBase64,
+            });
+            await this.addContact(contact);
+            return { success: true, message: "Contact imported successfully" };
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: err instanceof Error ? err.message : "Unknown error",
+            };
+        }
     }
-    /* ================================
-     * Serialization / Persistence
-     * ================================ */
-    /**
-     * Serializes both the directory and all groups into a single unified payload.
-     * This is what MajikMessage.toJSON() should persist.
-     */
+    async importContactFromString(base64Str) {
+        try {
+            const contact = await this.importContactCompressed(base64Str);
+            await this.addContact(contact);
+            return { success: true, message: "Contact imported successfully" };
+        }
+        catch (err) {
+            return {
+                success: false,
+                message: err instanceof Error ? err.message : "Unknown error",
+            };
+        }
+    }
+    async exportContactCompressed(contact) {
+        let publicKeyBase64;
+        const anyPub = contact.publicKey;
+        if (anyPub?.raw instanceof Uint8Array) {
+            publicKeyBase64 = arrayBufferToBase64(anyPub.raw.buffer);
+        }
+        else {
+            const raw = await crypto.subtle.exportKey("raw", contact.publicKey);
+            publicKeyBase64 = arrayBufferToBase64(raw);
+        }
+        const jsonObj = {
+            id: contact.id,
+            label: contact.meta?.label || "",
+            publicKey: publicKeyBase64,
+            fingerprint: contact.fingerprint,
+            mlKey: contact.mlKey,
+            edPublicKeyBase64: contact.edPublicKeyBase64,
+            mlDsaPublicKeyBase64: contact.mlDsaPublicKeyBase64,
+        };
+        const compressed = gzipSync(new TextEncoder().encode(JSON.stringify(jsonObj)));
+        return arrayToBase64(compressed);
+    }
+    async importContactCompressed(base64Str) {
+        const compressed = base64ToArrayBuffer(base64Str);
+        const jsonStr = new TextDecoder().decode(gunzipSync(new Uint8Array(compressed)));
+        const data = JSON.parse(jsonStr);
+        const rawBuffer = base64ToArrayBuffer(data.publicKey);
+        let publicKey;
+        try {
+            publicKey = await crypto.subtle.importKey("raw", rawBuffer, KEY_ALGO, true, []);
+        }
+        catch {
+            publicKey = { raw: new Uint8Array(rawBuffer) };
+        }
+        if (!data?.id || !publicKey || !data?.fingerprint || !data?.mlKey) {
+            throw new Error("Invalid contact JSON");
+        }
+        return new MajikContact({
+            id: data.id,
+            publicKey,
+            fingerprint: data.fingerprint,
+            meta: { label: data.label },
+            mlKey: data.mlKey,
+            edPublicKeyBase64: data.edPublicKeyBase64,
+            mlDsaPublicKeyBase64: data.mlDsaPublicKeyBase64,
+        });
+    }
+    // ── Serialization ─────────────────────────────────────────────────────────
     async toJSON() {
         return {
             contacts: await this.directory.toJSON(),
@@ -372,18 +472,19 @@ export class MajikContactManager {
         };
     }
     /**
-     * Restores a MajikContactManager from a unified serialized payload.
-     *
-     * Restoration order:
-     *  1. Restore the directory (contacts + crypto keys)
-     *  2. Restore groups via the group manager
-     *  3. Silently strip any group member IDs that no longer exist in the
-     *     restored directory (orphan pruning) — guards against data drift
-     *     between directory and group state across serialization rounds
-     *
-     * @param data   The payload produced by toJSON().
+     * Restore from a JSON snapshot into the current adapters.
+     * Writes all contacts and groups through to the adapters.
+     * Used after setAdapters() to migrate data into a new store.
      */
-    static async fromJSON(data) {
+    async bulkRestoreFromJSON(data) {
+        if (!data?.contacts || !data?.groups) {
+            throw new MajikContactManagerError("bulkRestoreFromJSON: invalid payload — expected { contacts, groups }");
+        }
+        await this._contactAdapter.bulkSave(data.contacts.contacts);
+        await this._groupAdapter.bulkSave(data.groups.groups);
+        await this.hydrate();
+    }
+    static async fromJSON(data, adapters) {
         if (!data || typeof data !== "object") {
             throw new MajikContactManagerError("fromJSON: invalid payload — expected { contacts, groups }");
         }
@@ -393,52 +494,31 @@ export class MajikContactManager {
         if (!data.groups) {
             throw new MajikContactManagerError("fromJSON: missing required field 'groups'");
         }
-        // Step 1 — restore directory
-        let directory;
-        try {
-            directory = new MajikContactDirectory();
-            await directory.fromJSON(data.contacts);
-        }
-        catch (err) {
-            throw new MajikContactManagerError("fromJSON: failed to restore contact directory", err);
-        }
-        // Step 2 — restore group manager bound to the restored directory
-        let groupManager;
-        try {
-            groupManager = new MajikContactGroupManager(directory);
-            groupManager.fromJSON(data.groups);
-        }
-        catch (err) {
-            throw new MajikContactManagerError("fromJSON: failed to restore group manager", err);
-        }
-        // Step 3 — silently prune orphaned member IDs from every group
-        // An orphan is a contact ID that exists in a group but is absent from
-        // the restored directory. This can happen if a contact was removed
-        // between two save cycles or data was partially corrupted.
-        MajikContactManager.pruneOrphanedMembers(directory, groupManager);
-        return new MajikContactManager(directory, groupManager);
+        const manager = new MajikContactManager(undefined, undefined, adapters);
+        await manager.bulkRestoreFromJSON(data);
+        return manager;
     }
+    // ── Private helpers ───────────────────────────────────────────────────────
     /**
-     * Walks every group and removes any member ID not present in the directory.
-     * Operates directly on the group instances — no re-serialization needed.
+     * Persists every group currently in the group manager to the adapter.
+     * Used after bulk contact removal where multiple groups may be affected.
      */
+    async _persistAllGroups() {
+        const all = this.groupManager.listGroups(true);
+        await this._groupAdapter.bulkSave(all.map((g) => g.toJSON()));
+    }
     static pruneOrphanedMembers(directory, groupManager) {
-        const allGroups = groupManager.listGroups(true); // include system groups
+        const allGroups = groupManager.listGroups(true);
         for (const group of allGroups) {
             const orphans = group
                 .listMemberIds()
                 .filter((id) => !directory.hasContact(id));
             for (const orphanId of orphans) {
-                // Use the idempotent variant — safe even if the index is already clean
                 group.removeMemberIfPresent(orphanId);
-                // Also clean up the reverse index on the group manager
                 groupManager.handleContactRemoved(orphanId);
             }
         }
     }
-    /* ================================
-     * Assertions
-     * ================================ */
     assertGroupManagerInstance(gm) {
         if (!gm || !(gm instanceof MajikContactGroupManager)) {
             throw new MajikContactManagerError("groupManager must be a valid MajikContactGroupManager instance");