@jbctechsolutions/mcp-office365 3.0.0 → 4.0.0

package/dist/graph/repository.js

@@ -3,10 +3,16 @@
  * Licensed under the MIT License. See LICENSE file in the project root.
  */
 import { GraphClient } from './client/index.js';
-import { mapMailFolderToRow, mapCalendarToFolderRow, mapMessageToEmailRow, mapEventToEventRow, mapContactToContactRow, mapTaskToTaskRow, hashStringToNumber, } from './mappers/index.js';
+import { mapMailFolderToRow, mapCalendarToFolderRow, mapMessageToEmailRow, mapEventToEventRow, mapContactToContactRow, mapTaskToTaskRow, } from './mappers/index.js';
+import { currentAccountId } from './auth/index.js';
+import { resolveId } from '../ids/resolver.js';
+import { registerComposite } from '../ids/mint.js';
+import { mintSelfEncoded } from '../ids/token.js';
+import { IdUnknownError, isGraphSdkError } from '../utils/errors.js';
 import { downloadAttachment, getDownloadDir } from './attachments.js';
 import * as fs from 'fs';
 import * as path from 'path';
+import { createHash } from 'node:crypto';
 /**
  * Repository implementation using Microsoft Graph API.
  *
@@ -14,78 +20,179 @@ import * as path from 'path';
  */
 export class GraphRepository {
     client;
+    store;
+    accountId;
     deltaLinks = new Map();
-    idCache = {
-        folders: new Map(),
-        messages: new Map(),
-        conversations: new Map(),
-        events: new Map(),
-        contacts: new Map(),
-        tasks: new Map(),
-        taskLists: new Map(),
-        attachments: new Map(),
-        rules: new Map(),
-        contactFolders: new Map(),
-        categories: new Map(),
-        focusedOverrides: new Map(),
-        calendarGroups: new Map(),
-        calendars: new Map(),
-        calendarPermissions: new Map(),
-        teams: new Map(),
-        channels: new Map(),
-        channelMessages: new Map(),
-        chats: new Map(),
-        chatMessages: new Map(),
-        checklistItems: new Map(),
-        linkedResources: new Map(),
-        taskAttachments: new Map(),
-        plans: new Map(),
-        plannerBuckets: new Map(),
-        plannerTasks: new Map(),
-        plannerTaskDetails: new Map(),
-        onlineMeetings: new Map(),
-        recordings: new Map(),
-        transcripts: new Map(),
-        driveItems: new Map(),
-        sites: new Map(),
-        documentLibraries: new Map(),
-        libraryDriveItems: new Map(),
-    };
-    constructor(deviceCodeCallback) {
+    constructor(deviceCodeCallback, store, accountId = currentAccountId) {
         this.client = new GraphClient(deviceCodeCallback);
+        this.store = store;
+        this.accountId = accountId;
+    }
+    /**
+     * Resolves any id a tool receives — a durable token, a raw Graph id, or a
+     * legacy numeric id — to a live Graph id (U5). Self-encoding tokens decode with
+     * no store; alias-backed tokens need {@link store}; a numeric id on Graph is
+     * unsupported (D4). Throws a typed error on failure.
+     */
+    toGraphId(id, expectedEntityType) {
+        return resolveId(id, this.accountId(), this.store, expectedEntityType).graphId;
+    }
+    /**
+     * Mints an alias-backed token for a single-Graph-id entity (e.g. team, chat)
+     * and records token → graphId in the alias table so it resolves on later calls.
+     * Alias-backed (not self-encoding) so the token is short and account-scoped: a
+     * cold store yields ID_UNKNOWN rather than leaking a decodable tenant-global id.
+     */
+    mintAlias(entityType, graphId) {
+        if (this.store == null) {
+            // Production always has a store (index.ts) and degraded mode still yields a
+            // non-null in-memory one, so this is only reachable from a store-less
+            // embedding. Fail loudly rather than mint a token nothing can resolve.
+            throw new IdUnknownError(`${entityType} (durable state store unavailable)`, 'Alias-backed ids require the durable state store; construct the repository with one.');
+        }
+        return registerComposite(this.store, {
+            entityType,
+            parts: { id: graphId },
+            graphId,
+            accountId: this.accountId(),
+        });
+    }
+    /**
+     * Mints an alias-backed token for a composite entity whose Graph URL needs a
+     * tuple of ids (e.g. channel {teamId, channelId}). The tuple is the canonical
+     * key AND is stored JSON-encoded as the resolved value, so {@link toGraphParts}
+     * can recover every field.
+     */
+    mintAliasComposite(entityType, parts) {
+        if (this.store == null) {
+            throw new IdUnknownError(`<no store: cannot mint ${entityType}>`);
+        }
+        return registerComposite(this.store, {
+            entityType,
+            parts,
+            graphId: JSON.stringify(parts),
+            accountId: this.accountId(),
+        });
+    }
+    /**
+     * Resolves a composite token to its identifying tuple. The alias row stores the
+     * tuple JSON-encoded; a raw (non-token) string can't carry a tuple, so anything
+     * that doesn't decode to a JSON object carrying every required key is an unusable
+     * id (ID_UNKNOWN). Generic over the key set so callers get a precisely-typed
+     * result — every requested field is a guaranteed non-empty string.
+     */
+    toGraphParts(id, entityType, keys) {
+        const raw = this.toGraphId(id, entityType);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new IdUnknownError(String(id));
+        }
+        if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new IdUnknownError(String(id));
+        }
+        const obj = parsed;
+        const out = {};
+        for (const key of keys) {
+            const value = obj[key];
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new IdUnknownError(String(id));
+            }
+            out[key] = value;
+        }
+        return out;
     }
     // ===========================================================================
     // Cache Resolvers (auto-fetch parent on cache miss)
     // ===========================================================================
     async resolveTeamId(teamId) {
-        let graphId = this.idCache.teams.get(teamId);
-        if (graphId != null)
-            return graphId;
-        await this.listTeamsAsync();
-        graphId = this.idCache.teams.get(teamId);
-        if (graphId != null)
-            return graphId;
-        throw new Error(`Team ID ${teamId} not found. Verify the ID is correct by calling list_teams.`);
+        // tm_ tokens resolve from the alias store. On a cold miss (never listed this
+        // session, or a lost store) re-list — listTeamsAsync deterministically
+        // re-mints and re-stores the same token — then resolve again.
+        try {
+            return this.toGraphId(teamId, 'team');
+        }
+        catch (e) {
+            if (e instanceof IdUnknownError) {
+                await this.listTeamsAsync();
+                return this.toGraphId(teamId, 'team');
+            }
+            throw e;
+        }
     }
     async resolvePlanId(planId) {
-        let cached = this.idCache.plans.get(planId);
-        if (cached != null)
-            return cached;
-        await this.listPlansAsync();
-        cached = this.idCache.plans.get(planId);
-        if (cached != null)
-            return cached;
-        throw new Error(`Plan ID ${planId} not found. Verify the ID is correct by calling list_plans.`);
+        // pl_ tokens resolve from the alias store. On a cold miss (never listed this
+        // session, or a lost store) re-list — listPlansAsync deterministically
+        // re-mints and re-stores the same token — then resolve again.
+        try {
+            return this.toGraphId(planId, 'plan');
+        }
+        catch (e) {
+            if (e instanceof IdUnknownError) {
+                await this.listPlansAsync();
+                return this.toGraphId(planId, 'plan');
+            }
+            throw e;
+        }
+    }
+    /** True for an HTTP 412 (Precondition Failed) — the `If-Match` etag we sent no
+     * longer matches the entity's current etag. */
+    isPreconditionFailed(e) {
+        return isGraphSdkError(e) && e.statusCode === 412;
+    }
+    /** Extracts the OData etag from a fetched entity, defaulting to `''` when absent. */
+    extractEtag(entity) {
+        return entity['@odata.etag'] ?? '';
+    }
+    /**
+     * Fetches a fresh etag immediately before a write (U5b-5 — the Planner etag is
+     * mutable and per-sub-resource, so it can't ride in the durable token or a
+     * cache) and retries the write once with a re-fetched etag on a 412, covering
+     * the narrow race between the fetch and the write.
+     *
+     * CONCURRENCY SEMANTIC (deliberate, last-writer-wins): because MCP tool calls
+     * are stateless, the etag the caller observed at an earlier `get_*` cannot be
+     * carried into a later `update_*`. We therefore re-read the etag at write time,
+     * which means a concurrent edit landing between the caller's read and their
+     * write is NOT detected — the write overwrites it. This is the intended
+     * trade-off (it eliminates the spurious 412s the old cached-etag path produced
+     * for a lone editor); Planner writes are not cross-read conflict-protected.
+     */
+    async withFreshEtag(fetchEtag, write) {
+        // An empty If-Match is never a valid write intent — fail loudly rather than
+        // send `If-Match: ''` (which would 400/412 confusingly, or on a lenient
+        // endpoint become an unconditional overwrite).
+        const fetch = async () => {
+            const etag = await fetchEtag();
+            if (etag.length === 0) {
+                throw new Error('Cannot perform a conditional write: the entity returned no @odata.etag.');
+            }
+            return etag;
+        };
+        const etag = await fetch();
+        try {
+            return await write(etag);
+        }
+        catch (e) {
+            if (this.isPreconditionFailed(e)) {
+                return await write(await fetch());
+            }
+            throw e;
+        }
     }
     async resolveChatId(chatId) {
-        let graphId = this.idCache.chats.get(chatId);
-        if (graphId != null)
-            return graphId;
-        await this.listChatsAsync();
-        graphId = this.idCache.chats.get(chatId);
-        if (graphId != null)
-            return graphId;
-        throw new Error(`Chat ID ${chatId} not found. Verify the ID is correct by calling list_chats.`);
+        try {
+            return this.toGraphId(chatId, 'chat');
+        }
+        catch (e) {
+            if (e instanceof IdUnknownError) {
+                await this.listChatsAsync();
+                return this.toGraphId(chatId, 'chat');
+            }
+            throw e;
+        }
     }
     // ===========================================================================
     // Folders
@@ -97,31 +204,15 @@ export class GraphRepository {
         throw new Error('Use listFoldersAsync() for Graph repository');
     }
     async listFoldersAsync() {
+        // Rows carry self-encoding fd_ tokens (the mapper mints them) — no cache.
         const folders = await this.client.listMailFolders();
-        // Update ID cache
-        for (const folder of folders) {
-            if (folder.id != null) {
-                const numericId = hashStringToNumber(folder.id);
-                this.idCache.folders.set(numericId, folder.id);
-            }
-        }
         return folders.map(mapMailFolderToRow);
     }
     getFolder(_id) {
         throw new Error('Use getFolderAsync() for Graph repository');
     }
     async getFolderAsync(id) {
-        const graphId = this.idCache.folders.get(id);
-        if (graphId == null) {
-            // Try to find it by listing all folders
-            await this.listFoldersAsync();
-            const refreshedGraphId = this.idCache.folders.get(id);
-            if (refreshedGraphId == null) {
-                return undefined;
-            }
-            const folder = await this.client.getMailFolder(refreshedGraphId);
-            return folder != null ? mapMailFolderToRow(folder) : undefined;
-        }
+        const graphId = this.toGraphId(id, 'folder');
         const folder = await this.client.getMailFolder(graphId);
         return folder != null ? mapMailFolderToRow(folder) : undefined;
     }
@@ -132,58 +223,23 @@ export class GraphRepository {
         throw new Error('Use listEmailsAsync() for Graph repository');
     }
     async listEmailsAsync(folderId, limit, offset) {
-        const graphFolderId = this.idCache.folders.get(folderId);
-        if (graphFolderId == null) {
-            // Refresh folder cache
-            await this.listFoldersAsync();
-            const refreshedId = this.idCache.folders.get(folderId);
-            if (refreshedId == null) {
-                return [];
-            }
-            return this.listEmailsWithGraphId(refreshedId, limit, offset);
-        }
+        const graphFolderId = this.toGraphId(folderId, 'folder');
         return this.listEmailsWithGraphId(graphFolderId, limit, offset);
     }
     async listEmailsWithGraphId(folderId, limit, offset) {
+        // Rows carry self-encoding em_ tokens (the mapper mints them) — no cache.
         const messages = await this.client.listMessages(folderId, limit, offset);
-        // Update ID cache
-        for (const message of messages) {
-            if (message.id != null) {
-                const numericId = hashStringToNumber(message.id);
-                this.idCache.messages.set(numericId, message.id);
-            }
-            if (message.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
-            }
-        }
         return messages.map((m) => mapMessageToEmailRow(m, folderId));
     }
     listUnreadEmails(_folderId, _limit, _offset) {
         throw new Error('Use listUnreadEmailsAsync() for Graph repository');
     }
     async listUnreadEmailsAsync(folderId, limit, offset) {
-        const graphFolderId = this.idCache.folders.get(folderId);
-        if (graphFolderId == null) {
-            await this.listFoldersAsync();
-            const refreshedId = this.idCache.folders.get(folderId);
-            if (refreshedId == null) {
-                return [];
-            }
-            return this.listUnreadEmailsWithGraphId(refreshedId, limit, offset);
-        }
+        const graphFolderId = this.toGraphId(folderId, 'folder');
         return this.listUnreadEmailsWithGraphId(graphFolderId, limit, offset);
     }
     async listUnreadEmailsWithGraphId(folderId, limit, offset) {
         const messages = await this.client.listUnreadMessages(folderId, limit, offset);
-        for (const message of messages) {
-            if (message.id != null) {
-                const numericId = hashStringToNumber(message.id);
-                this.idCache.messages.set(numericId, message.id);
-            }
-            if (message.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
-            }
-        }
         return messages.map((m) => mapMessageToEmailRow(m, folderId));
     }
     searchEmails(_query, _limit) {
@@ -191,43 +247,17 @@ export class GraphRepository {
     }
     async searchEmailsAsync(query, limit) {
         const messages = await this.client.searchMessages(query, limit);
-        for (const message of messages) {
-            if (message.id != null) {
-                const numericId = hashStringToNumber(message.id);
-                this.idCache.messages.set(numericId, message.id);
-            }
-            if (message.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
-            }
-        }
         return messages.map((m) => mapMessageToEmailRow(m));
     }
     searchEmailsInFolder(_folderId, _query, _limit) {
         throw new Error('Use searchEmailsInFolderAsync() for Graph repository');
     }
     async searchEmailsInFolderAsync(folderId, query, limit) {
-        const graphFolderId = this.idCache.folders.get(folderId);
-        if (graphFolderId == null) {
-            await this.listFoldersAsync();
-            const refreshedId = this.idCache.folders.get(folderId);
-            if (refreshedId == null) {
-                return [];
-            }
-            return this.searchEmailsInFolderWithGraphId(refreshedId, query, limit);
-        }
+        const graphFolderId = this.toGraphId(folderId, 'folder');
         return this.searchEmailsInFolderWithGraphId(graphFolderId, query, limit);
     }
     async searchEmailsInFolderWithGraphId(folderId, query, limit) {
         const messages = await this.client.searchMessagesInFolder(folderId, query, limit);
-        for (const message of messages) {
-            if (message.id != null) {
-                const numericId = hashStringToNumber(message.id);
-                this.idCache.messages.set(numericId, message.id);
-            }
-            if (message.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
-            }
-        }
         return messages.map((m) => mapMessageToEmailRow(m, folderId));
     }
     /**
@@ -237,14 +267,6 @@ export class GraphRepository {
      */
     async searchEmailsStructuredAsync(compiled, limit) {
         const messages = await this.runStructuredSearch(compiled, limit);
-        for (const msg of messages) {
-            if (msg.id != null) {
-                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
-            }
-            if (msg.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
-            }
-        }
         return messages.map((m) => mapMessageToEmailRow(m));
     }
     runStructuredSearch(compiled, limit) {
@@ -258,22 +280,16 @@ export class GraphRepository {
         }
     }
     async checkNewEmailsAsync(folderId) {
-        const graphFolderId = this.idCache.folders.get(folderId);
-        if (graphFolderId == null)
-            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        const existingDeltaLink = this.deltaLinks.get(folderId);
+        const graphFolderId = this.toGraphId(folderId, 'folder');
+        // Key the delta cursor by the RESOLVED Graph id, not the input string: a
+        // folder can be addressed by its fd_ token or its raw Graph id, and both
+        // must share one cursor — otherwise the second form triggers a fresh initial
+        // sync and re-reports already-seen mail as new.
+        const existingDeltaLink = this.deltaLinks.get(graphFolderId);
         const isInitialSync = existingDeltaLink == null;
         const { messages, deltaLink } = await this.client.getMessagesDelta(graphFolderId, existingDeltaLink);
         if (deltaLink) {
-            this.deltaLinks.set(folderId, deltaLink);
-        }
-        for (const msg of messages) {
-            if (msg.id != null) {
-                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
-            }
-            if (msg.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
-            }
+            this.deltaLinks.set(graphFolderId, deltaLink);
         }
         const activeMessages = messages.filter((m) => m['@removed'] == null);
         return {
@@ -284,61 +300,8 @@ export class GraphRepository {
     getEmail(_id) {
         throw new Error('Use getEmailAsync() for Graph repository');
     }
-    /**
-     * Populates the message ID cache by listing messages from mail folders.
-     * Used as a fallback when getEmailAsync is called with an ID not yet in cache
-     * (e.g. after server restart or when list_emails/search_emails wasn't called first).
-     */
-    async refreshMessageCacheForGetEmail(targetId) {
-        let folders;
-        try {
-            folders = await this.listFoldersAsync();
-        }
-        catch {
-            return false;
-        }
-        if (folders.length === 0)
-            return false;
-        const MESSAGE_LIMIT_PER_FOLDER = 100;
-        const MAX_FOLDERS_TO_SCAN = 15;
-        for (let i = 0; i < Math.min(folders.length, MAX_FOLDERS_TO_SCAN); i++) {
-            const folder = folders[i];
-            const graphFolderId = this.idCache.folders.get(folder.id);
-            if (graphFolderId == null)
-                continue;
-            let messages;
-            try {
-                messages = await this.client.listMessages(graphFolderId, MESSAGE_LIMIT_PER_FOLDER, 0);
-            }
-            catch {
-                continue;
-            }
-            if (!Array.isArray(messages))
-                continue;
-            for (const message of messages) {
-                if (message.id != null) {
-                    const numericId = hashStringToNumber(message.id);
-                    this.idCache.messages.set(numericId, message.id);
-                    if (numericId === targetId)
-                        return true;
-                }
-                if (message.conversationId != null) {
-                    this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
-                }
-            }
-        }
-        return this.idCache.messages.has(targetId);
-    }
     async getEmailAsync(id) {
-        let graphId = this.idCache.messages.get(id);
-        if (graphId == null) {
-            const found = await this.refreshMessageCacheForGetEmail(id);
-            if (found)
-                graphId = this.idCache.messages.get(id) ?? undefined;
-        }
-        if (graphId == null) {
-            return undefined;
-        }
+        const graphId = this.toGraphId(id, 'message');
         const message = await this.client.getMessage(graphId);
         return message != null ? mapMessageToEmailRow(message) : undefined;
     }
@@ -353,16 +316,7 @@ export class GraphRepository {
         throw new Error('Use getUnreadCountByFolderAsync() for Graph repository');
     }
     async getUnreadCountByFolderAsync(folderId) {
-        const graphId = this.idCache.folders.get(folderId);
-        if (graphId == null) {
-            await this.listFoldersAsync();
-            const refreshedId = this.idCache.folders.get(folderId);
-            if (refreshedId == null) {
-                return 0;
-            }
-            const folder = await this.client.getMailFolder(refreshedId);
-            return folder?.unreadItemCount ?? 0;
-        }
+        const graphId = this.toGraphId(folderId, 'folder');
         const folder = await this.client.getMailFolder(graphId);
         return folder?.unreadItemCount ?? 0;
     }
@@ -372,27 +326,19 @@ export class GraphRepository {
     /**
      * Lists all messages in a conversation thread.
      *
-     * Looks up the message to get its conversationId, resolves the Graph string
-     * conversationId from cache, then queries for all messages with that ID.
+     * Resolves the message id to its Graph id (durable `em_` token or raw Graph
+     * id), fetches the message to read its raw Graph conversationId, then queries
+     * for all messages with that ID. No cache required.
      */
     async listConversationAsync(messageId, limit) {
-        const email = await this.getEmailAsync(messageId);
-        if (email == null)
-            throw new Error(`Message ID ${messageId} not found`);
-        if (email.conversationId == null)
+        const graphId = this.toGraphId(messageId, 'message');
+        const message = await this.client.getMessage(graphId);
+        if (message == null)
+            throw new Error('Message not found');
+        const convId = message.conversationId;
+        if (convId == null)
             throw new Error('Message has no conversation ID');
-        const graphConversationId = this.idCache.conversations.get(email.conversationId);
-        if (graphConversationId == null)
-            throw new Error('Conversation ID not found in cache. Try fetching the email first to populate the cache.');
-        const messages = await this.client.listConversationMessages(graphConversationId, limit);
-        for (const msg of messages) {
-            if (msg.id != null) {
-                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
-            }
-            if (msg.conversationId != null) {
-                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
-            }
-        }
+        const messages = await this.client.listConversationMessages(convId, limit);
         return messages.map((m) => mapMessageToEmailRow(m));
     }
     // ===========================================================================
@@ -402,72 +348,39 @@ export class GraphRepository {
         throw new Error('Use listCalendarsAsync() for Graph repository');
     }
     async listCalendarsAsync() {
+        // Rows carry self-encoding fd_ tokens (the mapper mints them) — no cache.
         const calendars = await this.client.listCalendars();
-        for (const calendar of calendars) {
-            if (calendar.id != null) {
-                const numericId = hashStringToNumber(calendar.id);
-                this.idCache.folders.set(numericId, calendar.id);
-                this.idCache.calendars.set(numericId, calendar.id);
-            }
-        }
         return calendars.map(mapCalendarToFolderRow);
     }
     listEvents(_limit) {
         throw new Error('Use listEventsAsync() for Graph repository');
     }
     async listEventsAsync(limit) {
+        // Rows carry self-encoding ev_ tokens (the mapper mints them) — no cache.
         const events = await this.client.listEvents(limit);
-        for (const event of events) {
-            if (event.id != null) {
-                const numericId = hashStringToNumber(event.id);
-                this.idCache.events.set(numericId, event.id);
-            }
-        }
         return events.map((e) => mapEventToEventRow(e));
     }
     listEventsByFolder(_folderId, _limit) {
         throw new Error('Use listEventsByFolderAsync() for Graph repository');
     }
     async listEventsByFolderAsync(folderId, limit) {
-        const graphCalendarId = this.idCache.folders.get(folderId);
-        if (graphCalendarId == null) {
-            return this.listEventsAsync(limit);
-        }
+        const graphCalendarId = this.toGraphId(folderId, 'folder');
         const events = await this.client.listEvents(limit, graphCalendarId);
-        for (const event of events) {
-            if (event.id != null) {
-                const numericId = hashStringToNumber(event.id);
-                this.idCache.events.set(numericId, event.id);
-            }
-        }
         return events.map((e) => mapEventToEventRow(e, graphCalendarId));
     }
     searchEvents(_query, _startDate, _endDate, _limit) {
         throw new Error('Use searchEventsAsync() for Graph repository');
     }
     async searchEventsAsync(query, startDate, endDate, limit) {
-        // Graph doesn't have direct event search, so we filter client-side
+        // Graph doesn't have direct event search, so we filter client-side on the
+        // Graph events (by subject) before mapping to rows.
         const start = startDate != null ? new Date(startDate) : undefined;
         const end = endDate != null ? new Date(endDate) : undefined;
         const events = await this.client.listEvents(1000, undefined, start, end);
-        for (const event of events) {
-            if (event.id != null) {
-                const numericId = hashStringToNumber(event.id);
-                this.idCache.events.set(numericId, event.id);
-            }
-        }
-        let rows = events.map((e) => mapEventToEventRow(e));
-        // Filter by title client-side if query provided
-        if (query != null) {
-            const queryLower = query.toLowerCase();
-            rows = rows.filter((row) => {
-                // EventRow doesn't have title, so we need to check the original event
-                const originalEvent = events.find((e) => e.id != null && hashStringToNumber(e.id) === row.id);
-                const subject = originalEvent?.subject?.toLowerCase() ?? '';
-                return subject.includes(queryLower);
-            });
-        }
-        return rows.slice(0, limit);
+        const matched = query != null
+            ? events.filter((e) => (e.subject?.toLowerCase() ?? '').includes(query.toLowerCase()))
+            : events;
+        return matched.slice(0, limit).map((e) => mapEventToEventRow(e));
     }
     listEventsByDateRange(_startDate, _endDate, _limit) {
         throw new Error('Use listEventsByDateRangeAsync() for Graph repository');
@@ -476,36 +389,23 @@ export class GraphRepository {
         const start = new Date(startDate * 1000);
         const end = new Date(endDate * 1000);
         const events = await this.client.listEvents(limit, undefined, start, end);
-        for (const event of events) {
-            if (event.id != null) {
-                const numericId = hashStringToNumber(event.id);
-                this.idCache.events.set(numericId, event.id);
-            }
-        }
         return events.map((e) => mapEventToEventRow(e));
     }
     getEvent(_id) {
         throw new Error('Use getEventAsync() for Graph repository');
     }
     async getEventAsync(id) {
-        const graphId = this.idCache.events.get(id);
-        if (graphId == null) {
-            return undefined;
-        }
+        const graphId = this.toGraphId(id, 'event');
         const event = await this.client.getEvent(graphId);
         return event != null ? mapEventToEventRow(event) : undefined;
     }
+    /** Resolves an event id (durable `ev_` token or raw Graph id) to its Graph id. */
+    getEventGraphId(id) {
+        return this.toGraphId(id, 'event');
+    }
     async listEventInstancesAsync(eventId, startDate, endDate) {
-        const graphId = this.idCache.events.get(eventId);
-        if (graphId == null) {
-            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        }
+        const graphId = this.toGraphId(eventId, 'event');
         const instances = await this.client.listEventInstances(graphId, startDate, endDate);
-        for (const inst of instances) {
-            if (inst.id != null) {
-                this.idCache.events.set(hashStringToNumber(inst.id), inst.id);
-            }
-        }
         return instances.map((e) => mapEventToEventRow(e));
     }
     // ===========================================================================
@@ -515,13 +415,9 @@ export class GraphRepository {
         throw new Error('Use listContactsAsync() for Graph repository');
     }
     async listContactsAsync(limit, offset) {
+        // Rows carry self-encoding `ct_` tokens (the mapper mints them), so there is
+        // no numeric-id cache to populate — the token decodes to the Graph id.
         const contacts = await this.client.listContacts(limit, offset);
-        for (const contact of contacts) {
-            if (contact.id != null) {
-                const numericId = hashStringToNumber(contact.id);
-                this.idCache.contacts.set(numericId, contact.id);
-            }
-        }
         return contacts.map(mapContactToContactRow);
     }
     searchContacts(_query, _limit) {
@@ -529,25 +425,20 @@ export class GraphRepository {
     }
     async searchContactsAsync(query, limit) {
         const contacts = await this.client.searchContacts(query, limit);
-        for (const contact of contacts) {
-            if (contact.id != null) {
-                const numericId = hashStringToNumber(contact.id);
-                this.idCache.contacts.set(numericId, contact.id);
-            }
-        }
         return contacts.map(mapContactToContactRow);
     }
     getContact(_id) {
         throw new Error('Use getContactAsync() for Graph repository');
     }
     async getContactAsync(id) {
-        const graphId = this.idCache.contacts.get(id);
-        if (graphId == null) {
-            return undefined;
-        }
+        const graphId = this.toGraphId(id, 'contact');
         const contact = await this.client.getContact(graphId);
         return contact != null ? mapContactToContactRow(contact) : undefined;
     }
+    /** Resolves a contact id (durable `ct_` token or raw Graph id) to its Graph id. */
+    getContactGraphId(id) {
+        return this.toGraphId(id, 'contact');
+    }
     // ===========================================================================
     // Contact Folders
     // ===========================================================================
@@ -555,10 +446,8 @@ export class GraphRepository {
         const folders = await this.client.listContactFolders();
         return folders.map((folder) => {
             const graphId = folder.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.contactFolders.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('contactFolder', graphId),
                 name: folder.displayName ?? '',
                 parentFolderId: folder.parentFolderId ?? null,
             };
@@ -566,47 +455,30 @@ export class GraphRepository {
     }
     async createContactFolderAsync(name) {
         const created = await this.client.createContactFolder(name);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.contactFolders.set(numericId, graphId);
-        return numericId;
+        return this.mintAlias('contactFolder', created.id);
     }
     async deleteContactFolderAsync(folderId) {
-        const graphId = this.idCache.contactFolders.get(folderId);
-        if (graphId == null)
-            throw new Error(`Contact folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(folderId, 'contactFolder');
         await this.client.deleteContactFolder(graphId);
-        this.idCache.contactFolders.delete(folderId);
     }
     async listContactsInFolderAsync(folderId, limit = 100) {
-        const graphId = this.idCache.contactFolders.get(folderId);
-        if (graphId == null)
-            throw new Error(`Contact folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(folderId, 'contactFolder');
         const contacts = await this.client.listContactsInFolder(graphId, limit);
-        return contacts.map((c) => {
-            if (c.id != null) {
-                this.idCache.contacts.set(hashStringToNumber(c.id), c.id);
-            }
-            return mapContactToContactRow(c);
-        });
+        return contacts.map(mapContactToContactRow);
     }
     // ===========================================================================
     // Contact Photos
     // ===========================================================================
     async getContactPhotoAsync(contactId) {
-        const graphId = this.idCache.contacts.get(contactId);
-        if (graphId == null)
-            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(contactId, 'contact');
         const photoData = await this.client.getContactPhoto(graphId);
         const downloadDir = getDownloadDir();
-        const filePath = path.join(downloadDir, `contact-${contactId}-photo.jpg`);
+        const filePath = path.join(downloadDir, `contact-${createHash('sha1').update(graphId).digest('hex').slice(0, 16)}-photo.jpg`);
         fs.writeFileSync(filePath, Buffer.from(photoData));
         return { filePath, contentType: 'image/jpeg' };
     }
     async setContactPhotoAsync(contactId, filePath) {
-        const graphId = this.idCache.contacts.get(contactId);
-        if (graphId == null)
-            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(contactId, 'contact');
         const photoData = fs.readFileSync(filePath);
         const ext = path.extname(filePath).toLowerCase();
         const contentType = ext === '.png' ? 'image/png' : 'image/jpeg';
@@ -620,66 +492,65 @@ export class GraphRepository {
     }
     async listTasksAsync(limit, offset) {
         const tasks = await this.client.listAllTasks(limit, offset, true);
-        for (const task of tasks) {
-            if (task.id != null && task.taskListId != null) {
-                const numericId = hashStringToNumber(task.id);
-                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
-                const listNumericId = hashStringToNumber(task.taskListId);
-                this.idCache.taskLists.set(listNumericId, task.taskListId);
-            }
-        }
-        return tasks.map(mapTaskToTaskRow);
+        return tasks
+            .filter((task) => task.id != null && task.taskListId != null)
+            .map((task) => {
+            const listTok = this.mintAlias('taskList', task.taskListId);
+            const taskTok = this.mintAliasComposite('task', { taskListId: task.taskListId, taskId: task.id });
+            return mapTaskToTaskRow({ ...task }, taskTok, listTok);
+        });
     }
     listIncompleteTasks(_limit, _offset) {
         throw new Error('Use listIncompleteTasksAsync() for Graph repository');
     }
     async listIncompleteTasksAsync(limit, offset) {
         const tasks = await this.client.listAllTasks(limit, offset, false);
-        for (const task of tasks) {
-            if (task.id != null && task.taskListId != null) {
-                const numericId = hashStringToNumber(task.id);
-                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
-                const listNumericId = hashStringToNumber(task.taskListId);
-                this.idCache.taskLists.set(listNumericId, task.taskListId);
-            }
-        }
-        return tasks.map(mapTaskToTaskRow);
+        return tasks
+            .filter((task) => task.id != null && task.taskListId != null)
+            .map((task) => {
+            const listTok = this.mintAlias('taskList', task.taskListId);
+            const taskTok = this.mintAliasComposite('task', { taskListId: task.taskListId, taskId: task.id });
+            return mapTaskToTaskRow({ ...task }, taskTok, listTok);
+        });
     }
     searchTasks(_query, _limit) {
         throw new Error('Use searchTasksAsync() for Graph repository');
     }
     async searchTasksAsync(query, limit) {
         const tasks = await this.client.searchTasks(query, limit);
-        for (const task of tasks) {
-            if (task.id != null && task.taskListId != null) {
-                const numericId = hashStringToNumber(task.id);
-                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
-            }
-        }
-        return tasks.map(mapTaskToTaskRow);
+        // Tasks without a taskListId can't form a {taskListId, taskId} composite
+        // token — skip them, matching the current cache-miss guard.
+        return tasks
+            .filter((task) => task.id != null && task.taskListId != null)
+            .map((task) => {
+            const listTok = this.mintAlias('taskList', task.taskListId);
+            const taskTok = this.mintAliasComposite('task', { taskListId: task.taskListId, taskId: task.id });
+            return mapTaskToTaskRow({ ...task }, taskTok, listTok);
+        });
     }
     getTask(_id) {
         throw new Error('Use getTaskAsync() for Graph repository');
     }
     async getTaskAsync(id) {
-        const taskInfo = this.idCache.tasks.get(id);
-        if (taskInfo == null) {
+        let taskInfo;
+        try {
+            taskInfo = this.toGraphParts(id, 'task', ['taskListId', 'taskId']);
+        }
+        catch {
             return undefined;
         }
         const task = await this.client.getTask(taskInfo.taskListId, taskInfo.taskId);
         if (task == null) {
             return undefined;
         }
-        return mapTaskToTaskRow({ ...task, taskListId: taskInfo.taskListId });
+        return mapTaskToTaskRow({ ...task, taskListId: taskInfo.taskListId }, String(id), this.mintAlias('taskList', taskInfo.taskListId));
     }
     async listTaskListsAsync() {
         const lists = await this.client.listTaskLists();
         return lists.map((list) => {
             const graphId = list.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.taskLists.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('taskList', graphId),
                 name: list.displayName ?? '',
                 isDefault: list.wellknownListName === 'defaultList',
             };
@@ -720,37 +591,33 @@ export class GraphRepository {
         return this.client;
     }
     /**
-     * Returns the Graph string ID for a cached draft numeric ID (satisfies IMailSendRepository).
+     * Resolves a draft id (durable `em_` token or raw Graph id) to its Graph id
+     * (satisfies IMailSendRepository). Drafts are messages.
      */
     getGraphIdForDraft(draftId) {
-        return this.idCache.messages.get(draftId);
+        return this.toGraphId(draftId, 'message');
     }
     /**
-     * Gets the Graph string ID from a numeric ID.
+     * Gets task info (Graph taskListId/taskId) from a durable `td_` token.
      */
-    getGraphId(type, numericId) {
-        switch (type) {
-            case 'folder':
-                return this.idCache.folders.get(numericId);
-            case 'message':
-                return this.idCache.messages.get(numericId);
-            case 'event':
-                return this.idCache.events.get(numericId);
-            case 'contact':
-                return this.idCache.contacts.get(numericId);
+    getTaskInfo(id) {
+        try {
+            return this.toGraphParts(id, 'task', ['taskListId', 'taskId']);
+        }
+        catch {
+            return undefined;
         }
     }
     /**
-     * Gets task info from a numeric ID.
-     */
-    getTaskInfo(numericId) {
-        return this.idCache.tasks.get(numericId);
-    }
-    /**
-     * Gets the Graph string ID for a task list from a numeric ID.
+     * Gets the Graph string ID for a task list from a durable `tl_` token.
      */
-    getTaskListGraphId(numericId) {
-        return this.idCache.taskLists.get(numericId);
+    getTaskListGraphId(id) {
+        try {
+            return this.toGraphId(id, 'taskList');
+        }
+        catch {
+            return undefined;
+        }
     }
     // ===========================================================================
     // Write Operations (Async)
@@ -797,42 +664,28 @@ export class GraphRepository {
     }
     // Async implementations
     async moveEmailAsync(emailId, destinationFolderId) {
-        const graphMessageId = this.idCache.messages.get(emailId);
-        const graphFolderId = this.idCache.folders.get(destinationFolderId);
-        if (graphMessageId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        if (graphFolderId == null)
-            throw new Error(`Folder ID ${destinationFolderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphMessageId = this.toGraphId(emailId, 'message');
+        const graphFolderId = this.toGraphId(destinationFolderId, 'folder');
         await this.client.moveMessage(graphMessageId, graphFolderId);
     }
     async deleteEmailAsync(emailId) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.deleteMessage(graphId);
     }
     async archiveEmailAsync(emailId) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.archiveMessage(graphId);
     }
     async junkEmailAsync(emailId) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.junkMessage(graphId);
     }
     async markEmailReadAsync(emailId, isRead) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.updateMessage(graphId, { isRead });
     }
     async setEmailFlagAsync(emailId, flagStatus) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         const flagStatusMap = {
             0: 'notFlagged',
             1: 'flagged',
@@ -843,55 +696,35 @@ export class GraphRepository {
         });
     }
     async setEmailCategoriesAsync(emailId, categories) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.updateMessage(graphId, { categories });
     }
     async setEmailImportanceAsync(emailId, importance) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         await this.client.updateMessage(graphId, { importance });
     }
     async createFolderAsync(name, parentFolderId) {
         const graphParentId = parentFolderId != null
-            ? this.idCache.folders.get(parentFolderId)
+            ? this.toGraphId(parentFolderId, 'folder')
             : undefined;
-        const folder = await this.client.createMailFolder(name, graphParentId ?? undefined);
-        // Update cache with new folder
-        if (folder.id != null) {
-            const numericId = hashStringToNumber(folder.id);
-            this.idCache.folders.set(numericId, folder.id);
-        }
+        const folder = await this.client.createMailFolder(name, graphParentId);
         return mapMailFolderToRow(folder);
     }
     async deleteFolderAsync(folderId) {
-        const graphId = this.idCache.folders.get(folderId);
-        if (graphId == null)
-            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(folderId, 'folder');
         await this.client.deleteMailFolder(graphId);
-        this.idCache.folders.delete(folderId);
     }
     async renameFolderAsync(folderId, newName) {
-        const graphId = this.idCache.folders.get(folderId);
-        if (graphId == null)
-            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(folderId, 'folder');
         await this.client.renameMailFolder(graphId, newName);
     }
     async moveFolderAsync(folderId, destinationParentId) {
-        const graphFolderId = this.idCache.folders.get(folderId);
-        const graphParentId = this.idCache.folders.get(destinationParentId);
-        if (graphFolderId == null)
-            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        if (graphParentId == null)
-            throw new Error(`Parent folder ID ${destinationParentId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphFolderId = this.toGraphId(folderId, 'folder');
+        const graphParentId = this.toGraphId(destinationParentId, 'folder');
         await this.client.moveMailFolder(graphFolderId, graphParentId);
     }
     async emptyFolderAsync(folderId) {
-        const graphId = this.idCache.folders.get(folderId);
-        if (graphId == null)
-            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(folderId, 'folder');
         await this.client.emptyMailFolder(graphId);
     }
     // ===========================================================================
@@ -901,7 +734,7 @@ export class GraphRepository {
      * Creates a new draft message.
      *
      * Converts email address strings to Recipient objects, calls the Graph client,
-     * adds the returned draft to idCache.messages, and returns its numeric ID.
+     * and returns a durable `em_` token plus the raw Graph id.
      */
     async createDraftAsync(params) {
         const toRecipients = (params.to ?? []).map(addr => ({
@@ -921,19 +754,15 @@ export class GraphRepository {
             bccRecipients,
         });
         const graphId = draft.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.messages.set(numericId, graphId);
-        return { numericId, graphId };
+        return { token: mintSelfEncoded('message', graphId), graphId };
     }
     /**
      * Updates an existing draft message.
      *
-     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     * Resolves the draft id to its Graph id, then calls the client.
      */
     async updateDraftAsync(draftId, updates) {
-        const graphId = this.idCache.messages.get(draftId);
-        if (graphId == null)
-            throw new Error(`Message ID ${draftId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(draftId, 'message');
         await this.client.updateDraft(graphId, updates);
     }
     /**
@@ -947,12 +776,10 @@ export class GraphRepository {
     /**
      * Sends an existing draft message.
      *
-     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     * Resolves the id to its Graph id, then calls the client.
      */
     async sendDraftAsync(draftId) {
-        const graphId = this.idCache.messages.get(draftId);
-        if (graphId == null)
-            throw new Error(`Message ID ${draftId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(draftId, 'message');
         await this.client.sendDraft(graphId);
     }
     /**
@@ -981,24 +808,20 @@ export class GraphRepository {
     /**
      * Replies to a message (or replies all).
      *
-     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     * Resolves the id to its Graph id, then calls the client.
      */
     async replyMessageAsync(messageId, comment, replyAll) {
-        const graphId = this.idCache.messages.get(messageId);
-        if (graphId == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(messageId, 'message');
         await this.client.replyMessage(graphId, comment, replyAll);
     }
     /**
      * Forwards a message to specified recipients.
      *
-     * Looks up the Graph string ID from idCache.messages, converts recipient
-     * email strings to Recipient objects, then calls the client.
+     * Resolves the id to its Graph id, converts recipient email strings to
+     * Recipient objects, then calls the client.
      */
     async forwardMessageAsync(messageId, toRecipients, comment) {
-        const graphId = this.idCache.messages.get(messageId);
-        if (graphId == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(messageId, 'message');
         const recipients = toRecipients.map(addr => ({
             emailAddress: { address: addr },
         }));
@@ -1010,42 +833,33 @@ export class GraphRepository {
     /**
      * Creates a reply (or reply-all) draft for a message.
      *
-     * Looks up the Graph string ID from idCache.messages, creates the draft
-     * via the client, caches the new draft ID, and optionally updates the body.
+     * Resolves the source message id to its Graph id, creates the draft via the
+     * client, and optionally updates the body.
      *
-     * @returns The numeric and graph IDs of the new draft.
+     * @returns A durable `em_` token and the raw Graph id of the new draft.
      */
     async replyAsDraftAsync(messageId, replyAll = false, comment, bodyType = 'text') {
-        const graphMessageId = this.idCache.messages.get(messageId);
-        if (graphMessageId == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphMessageId = this.toGraphId(messageId, 'message');
         // Pass comment/body through createReply so the quoted thread is preserved
         const body = comment != null ? { contentType: bodyType, content: comment } : undefined;
         const draft = replyAll
             ? await this.client.createReplyAllDraft(graphMessageId, undefined, body)
             : await this.client.createReplyDraft(graphMessageId, undefined, body);
         const graphId = draft.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.messages.set(numericId, graphId);
-        return { numericId, graphId };
+        return { token: mintSelfEncoded('message', graphId), graphId };
     }
     /**
      * Creates a forward draft for a message.
      *
-     * Looks up the Graph string ID from idCache.messages, creates the draft
-     * via the client, caches the new draft ID, and optionally updates the
-     * recipients and body.
+     * Resolves the source message id to its Graph id, creates the draft via the
+     * client, and optionally updates the recipients and body.
      *
-     * @returns The numeric and graph IDs of the new draft.
+     * @returns A durable `em_` token and the raw Graph id of the new draft.
      */
     async forwardAsDraftAsync(messageId, toRecipients, comment, bodyType = 'text') {
-        const graphMessageId = this.idCache.messages.get(messageId);
-        if (graphMessageId == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphMessageId = this.toGraphId(messageId, 'message');
         const draft = await this.client.createForwardDraft(graphMessageId);
         const graphId = draft.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.messages.set(numericId, graphId);
         const updates = {};
         if (toRecipients != null && toRecipients.length > 0) {
             updates.toRecipients = toRecipients.map(addr => ({
@@ -1058,7 +872,7 @@ export class GraphRepository {
         if (Object.keys(updates).length > 0) {
             await this.client.updateDraft(graphId, updates);
         }
-        return { numericId, graphId };
+        return { token: mintSelfEncoded('message', graphId), graphId };
     }
     // ---------------------------------------------------------------------------
     // Calendar Scheduling
@@ -1100,26 +914,18 @@ export class GraphRepository {
     /**
      * Lists attachments for a given email.
      *
-     * Looks up the Graph message ID from idCache.messages, calls
-     * client.listAttachments, hashes each attachment ID to a numeric key,
-     * and caches it in idCache.attachments with { messageId, attachmentId }.
+     * Resolves the id to its Graph id, calls client.listAttachments, and mints
+     * an `at_` composite alias token ({ messageId, attachmentId }) per item.
      *
      * @returns Array of attachment metadata objects.
      */
     async listAttachmentsAsync(emailId) {
-        const graphMessageId = this.idCache.messages.get(emailId);
-        if (graphMessageId == null)
-            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphMessageId = this.toGraphId(emailId, 'message');
         const attachments = await this.client.listAttachments(graphMessageId);
         return attachments.map((att) => {
             const attId = att.id ?? '';
-            const numericId = hashStringToNumber(attId);
-            this.idCache.attachments.set(numericId, {
-                messageId: graphMessageId,
-                attachmentId: attId,
-            });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('attachment', { messageId: graphMessageId, attachmentId: attId }),
                 name: att.name ?? '',
                 size: att.size ?? 0,
                 contentType: att.contentType ?? 'application/octet-stream',
@@ -1130,16 +936,14 @@ export class GraphRepository {
     /**
      * Downloads an attachment for a given email.
      *
-     * Looks up { messageId, attachmentId } from idCache.attachments,
-     * then delegates to the downloadAttachment helper which fetches
-     * the content and writes it to disk.
+     * Resolves the `at_` composite token to { messageId, attachmentId }, then
+     * delegates to the downloadAttachment helper which fetches the content and
+     * writes it to disk.
      *
      * @returns Metadata about the downloaded file including its local path.
      */
     async downloadAttachmentAsync(attachmentId) {
-        const cached = this.idCache.attachments.get(attachmentId);
-        if (cached == null)
-            throw new Error(`Attachment ID ${attachmentId} not found in cache. Call list_attachments first.`);
+        const cached = this.toGraphParts(attachmentId, 'attachment', ['messageId', 'attachmentId']);
         return downloadAttachment(this.client, cached.messageId, cached.attachmentId);
     }
     // ===========================================================================
@@ -1185,13 +989,11 @@ export class GraphRepository {
             graphEvent.onlineMeetingProvider = params.online_meeting_provider ?? 'teamsForBusiness';
         }
         const graphCalendarId = params.calendarId != null
-            ? this.idCache.folders.get(params.calendarId)
+            ? this.toGraphId(params.calendarId, 'folder')
             : undefined;
         const created = await this.client.createEvent(graphEvent, graphCalendarId);
         const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.events.set(numericId, graphId);
-        return numericId;
+        return mintSelfEncoded('event', graphId);
     }
     /**
      * Updates an existing calendar event.
@@ -1200,9 +1002,7 @@ export class GraphRepository {
      * client.updateEvent(). Throws if the event is not cached.
      */
     async updateEventAsync(eventId, updates) {
-        const graphId = this.idCache.events.get(eventId);
-        if (graphId == null)
-            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(eventId, 'event');
         await this.client.updateEvent(graphId, updates);
     }
     /**
@@ -1213,11 +1013,8 @@ export class GraphRepository {
      * Throws if the event is not cached.
      */
     async deleteEventAsync(eventId) {
-        const graphId = this.idCache.events.get(eventId);
-        if (graphId == null)
-            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(eventId, 'event');
         await this.client.deleteEvent(graphId);
-        this.idCache.events.delete(eventId);
     }
     /**
      * Responds to a calendar event invitation.
@@ -1226,9 +1023,7 @@ export class GraphRepository {
      * client.respondToEvent(). Throws if the event is not cached.
      */
     async respondToEventAsync(eventId, response, sendResponse, comment) {
-        const graphId = this.idCache.events.get(eventId);
-        if (graphId == null)
-            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(eventId, 'event');
         await this.client.respondToEvent(graphId, response, sendResponse, comment);
     }
     // ===========================================================================
@@ -1273,9 +1068,7 @@ export class GraphRepository {
         }
         const created = await this.client.createContact(graphContact);
         const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.contacts.set(numericId, graphId);
-        return numericId;
+        return mintSelfEncoded('contact', graphId);
     }
     /**
      * Updates an existing contact.
@@ -1284,9 +1077,7 @@ export class GraphRepository {
      * client.updateContact(). Throws if the contact is not cached.
      */
     async updateContactAsync(contactId, updates) {
-        const graphId = this.idCache.contacts.get(contactId);
-        if (graphId == null)
-            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(contactId, 'contact');
         await this.client.updateContact(graphId, updates);
     }
     /**
@@ -1297,11 +1088,8 @@ export class GraphRepository {
      * Throws if the contact is not cached.
      */
     async deleteContactAsync(contactId) {
-        const graphId = this.idCache.contacts.get(contactId);
-        if (graphId == null)
-            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(contactId, 'contact');
         await this.client.deleteContact(graphId);
-        this.idCache.contacts.delete(contactId);
     }
     // ===========================================================================
     // Task Write Operations (Async)
@@ -1309,14 +1097,12 @@ export class GraphRepository {
     /**
      * Creates a new task in a task list.
      *
-     * Looks up the Graph task list ID from idCache.taskLists, builds a
-     * Graph API task object from the given params, calls client.createTask(),
-     * caches the resulting ID, and returns a numeric ID.
+     * Resolves the `tl_` task list token to a Graph ID, builds a Graph API task
+     * object from the given params, calls client.createTask(), and returns a
+     * durable `td_` token for the created task.
      */
     async createTaskAsync(params) {
-        const graphListId = this.idCache.taskLists.get(params.task_list_id);
-        if (graphListId == null)
-            throw new Error(`Task list ID ${params.task_list_id} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphListId = this.toGraphId(params.task_list_id, 'taskList');
         const graphTask = {
             title: params.title,
         };
@@ -1362,22 +1148,14 @@ export class GraphRepository {
             };
         }
         const created = await this.client.createTask(graphListId, graphTask);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.tasks.set(numericId, { taskListId: graphListId, taskId: graphId });
-        return numericId;
+        return this.mintAliasComposite('task', { taskListId: graphListId, taskId: created.id });
     }
     /**
      * Updates an existing task.
-     *
-     * Looks up the Graph task info from idCache.tasks, then calls
-     * client.updateTask(). Throws if the task is not cached.
      */
     async updateTaskAsync(taskId, updates) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        await this.client.updateTask(taskInfo.taskListId, taskInfo.taskId, updates);
+        const { taskListId, taskId: gTaskId } = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
+        await this.client.updateTask(taskListId, gTaskId, updates);
     }
     /**
      * Marks a task as completed.
@@ -1396,64 +1174,42 @@ export class GraphRepository {
     }
     /**
      * Deletes a task.
-     *
-     * Looks up the Graph task info from idCache.tasks, calls
-     * client.deleteTask(), and removes the entry from idCache.
-     * Throws if the task is not cached.
      */
     async deleteTaskAsync(taskId) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
-        await this.client.deleteTask(taskInfo.taskListId, taskInfo.taskId);
-        this.idCache.tasks.delete(taskId);
+        const { taskListId, taskId: gTaskId } = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
+        await this.client.deleteTask(taskListId, gTaskId);
     }
     /**
      * Creates a new task list.
-     *
-     * Calls client.createTaskList(), caches the resulting ID in
-     * idCache.taskLists, and returns a numeric ID.
      */
     async createTaskListAsync(displayName) {
         const created = await this.client.createTaskList(displayName);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.taskLists.set(numericId, graphId);
-        return numericId;
+        return this.mintAlias('taskList', created.id);
     }
     /**
      * Renames a task list.
      */
     async renameTaskListAsync(listId, name) {
-        const graphId = this.idCache.taskLists.get(listId);
-        if (graphId == null)
-            throw new Error(`Task list ID ${listId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(listId, 'taskList');
         await this.client.updateTaskList(graphId, { displayName: name });
     }
     /**
      * Deletes a task list.
      */
     async deleteTaskListAsync(listId) {
-        const graphId = this.idCache.taskLists.get(listId);
-        if (graphId == null)
-            throw new Error(`Task list ID ${listId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(listId, 'taskList');
         await this.client.deleteTaskList(graphId);
-        this.idCache.taskLists.delete(listId);
     }
     // ===========================================================================
     // Checklist Items
     // ===========================================================================
     async listChecklistItemsAsync(taskId) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const items = await this.client.listChecklistItems(taskInfo.taskListId, taskInfo.taskId);
         return items.map((item) => {
             const graphId = item.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.checklistItems.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('checklistItem', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: graphId }),
                 displayName: item.displayName ?? '',
                 isChecked: item.isChecked ?? false,
                 createdDateTime: item.createdDateTime ?? '',
@@ -1461,19 +1217,12 @@ export class GraphRepository {
         });
     }
     async createChecklistItemAsync(taskId, displayName, isChecked = false) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const item = await this.client.createChecklistItem(taskInfo.taskListId, taskInfo.taskId, displayName, isChecked);
-        const graphId = item.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.checklistItems.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: graphId });
-        return numericId;
+        return this.mintAliasComposite('checklistItem', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: item.id });
     }
     async updateChecklistItemAsync(checklistItemId, updates) {
-        const cached = this.idCache.checklistItems.get(checklistItemId);
-        if (cached == null)
-            throw new Error(`Checklist item ID ${checklistItemId} not found in cache. Try listing checklist items first.`);
+        const cached = this.toGraphParts(checklistItemId, 'checklistItem', ['taskListId', 'taskId', 'checklistItemId']);
         const graphUpdates = {};
         if (updates.displayName != null)
             graphUpdates['displayName'] = updates.displayName;
@@ -1482,26 +1231,19 @@ export class GraphRepository {
         await this.client.updateChecklistItem(cached.taskListId, cached.taskId, cached.checklistItemId, graphUpdates);
     }
     async deleteChecklistItemAsync(checklistItemId) {
-        const cached = this.idCache.checklistItems.get(checklistItemId);
-        if (cached == null)
-            throw new Error(`Checklist item ID ${checklistItemId} not found in cache. Try listing checklist items first.`);
+        const cached = this.toGraphParts(checklistItemId, 'checklistItem', ['taskListId', 'taskId', 'checklistItemId']);
         await this.client.deleteChecklistItem(cached.taskListId, cached.taskId, cached.checklistItemId);
-        this.idCache.checklistItems.delete(checklistItemId);
     }
     // ===========================================================================
     // Linked Resources
     // ===========================================================================
     async listLinkedResourcesAsync(taskId) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const items = await this.client.listLinkedResources(taskInfo.taskListId, taskInfo.taskId);
         return items.map((item) => {
             const graphId = item.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.linkedResources.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('linkedResource', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: graphId }),
                 webUrl: item.webUrl ?? '',
                 applicationName: item.applicationName ?? '',
                 displayName: item.displayName ?? '',
@@ -1509,36 +1251,24 @@ export class GraphRepository {
         });
     }
     async createLinkedResourceAsync(taskId, webUrl, applicationName, displayName) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const item = await this.client.createLinkedResource(taskInfo.taskListId, taskInfo.taskId, webUrl, applicationName, displayName);
-        const graphId = item.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.linkedResources.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: graphId });
-        return numericId;
+        return this.mintAliasComposite('linkedResource', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: item.id });
     }
     async deleteLinkedResourceAsync(linkedResourceId) {
-        const cached = this.idCache.linkedResources.get(linkedResourceId);
-        if (cached == null)
-            throw new Error(`Linked resource ID ${linkedResourceId} not found in cache. Try listing linked resources first.`);
+        const cached = this.toGraphParts(linkedResourceId, 'linkedResource', ['taskListId', 'taskId', 'linkedResourceId']);
         await this.client.deleteLinkedResource(cached.taskListId, cached.taskId, cached.linkedResourceId);
-        this.idCache.linkedResources.delete(linkedResourceId);
     }
     // ===========================================================================
     // Task Attachments
     // ===========================================================================
     async listTaskAttachmentsAsync(taskId) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const items = await this.client.listTaskAttachments(taskInfo.taskListId, taskInfo.taskId);
         return items.map((item) => {
             const graphId = item.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.taskAttachments.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('taskAttachment', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: graphId }),
                 name: item['name'] ?? '',
                 size: item.size ?? 0,
                 contentType: item.contentType ?? '',
@@ -1546,21 +1276,13 @@ export class GraphRepository {
         });
     }
     async createTaskAttachmentAsync(taskId, name, contentBytes, contentType) {
-        const taskInfo = this.idCache.tasks.get(taskId);
-        if (taskInfo == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const taskInfo = this.toGraphParts(taskId, 'task', ['taskListId', 'taskId']);
         const item = await this.client.createTaskAttachment(taskInfo.taskListId, taskInfo.taskId, name, contentBytes, contentType);
-        const graphId = item.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.taskAttachments.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: graphId });
-        return numericId;
+        return this.mintAliasComposite('taskAttachment', { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: item.id });
     }
     async deleteTaskAttachmentAsync(taskAttachmentId) {
-        const cached = this.idCache.taskAttachments.get(taskAttachmentId);
-        if (cached == null)
-            throw new Error(`Task attachment ID ${taskAttachmentId} not found in cache. Try listing task attachments first.`);
+        const cached = this.toGraphParts(taskAttachmentId, 'taskAttachment', ['taskListId', 'taskId', 'attachmentId']);
         await this.client.deleteTaskAttachment(cached.taskListId, cached.taskId, cached.attachmentId);
-        this.idCache.taskAttachments.delete(taskAttachmentId);
     }
     // ===========================================================================
     // Mail Rules (Async)
@@ -1572,10 +1294,8 @@ export class GraphRepository {
         const rules = await this.client.listMailRules();
         return rules.map((rule) => {
             const graphId = rule.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.rules.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('mailRule', graphId),
                 displayName: rule.displayName ?? '',
                 sequence: rule.sequence ?? 0,
                 isEnabled: rule.isEnabled ?? true,
@@ -1589,20 +1309,14 @@ export class GraphRepository {
      */
     async createMailRuleAsync(rule) {
         const created = await this.client.createMailRule(rule);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.rules.set(numericId, graphId);
-        return numericId;
+        return this.mintAlias('mailRule', created.id);
     }
     /**
      * Deletes an inbox mail rule.
      */
     async deleteMailRuleAsync(ruleId) {
-        const graphId = this.idCache.rules.get(ruleId);
-        if (graphId == null)
-            throw new Error(`Rule ID ${ruleId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(ruleId, 'mailRule');
         await this.client.deleteMailRule(graphId);
-        this.idCache.rules.delete(ruleId);
     }
     // ===========================================================================
     // Automatic Replies (Out of Office)
@@ -1682,10 +1396,8 @@ export class GraphRepository {
         const categories = await this.client.listMasterCategories();
         return categories.map((cat) => {
             const graphId = cat.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.categories.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('category', graphId),
                 name: cat.displayName ?? '',
                 color: cat.color ?? 'none',
             };
@@ -1696,20 +1408,14 @@ export class GraphRepository {
      */
     async createCategoryAsync(name, color) {
         const created = await this.client.createMasterCategory(name, color);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.categories.set(numericId, graphId);
-        return numericId;
+        return this.mintAlias('category', created.id);
     }
     /**
      * Deletes a master category.
      */
     async deleteCategoryAsync(categoryId) {
-        const graphId = this.idCache.categories.get(categoryId);
-        if (graphId == null)
-            throw new Error(`Category ID ${categoryId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(categoryId, 'category');
         await this.client.deleteMasterCategory(graphId);
-        this.idCache.categories.delete(categoryId);
     }
     // ===========================================================================
     // Focused Inbox Overrides
@@ -1721,10 +1427,8 @@ export class GraphRepository {
         const overrides = await this.client.listFocusedOverrides();
         return overrides.map((o) => {
             const graphId = o.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.focusedOverrides.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('focusedOverride', graphId),
                 senderAddress: o.senderEmailAddress?.address ?? '',
                 classifyAs: o.classifyAs ?? '',
             };
@@ -1735,20 +1439,14 @@ export class GraphRepository {
      */
     async createFocusedOverrideAsync(senderAddress, classifyAs) {
         const created = await this.client.createFocusedOverride(senderAddress, classifyAs);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.focusedOverrides.set(numericId, graphId);
-        return numericId;
+        return this.mintAlias('focusedOverride', created.id);
     }
     /**
      * Deletes a focused inbox override.
      */
     async deleteFocusedOverrideAsync(overrideId) {
-        const graphId = this.idCache.focusedOverrides.get(overrideId);
-        if (graphId == null)
-            throw new Error(`Focused override ID ${overrideId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(overrideId, 'focusedOverride');
         await this.client.deleteFocusedOverride(graphId);
-        this.idCache.focusedOverrides.delete(overrideId);
     }
     // ===========================================================================
     // Message Headers & MIME
@@ -1757,21 +1455,17 @@ export class GraphRepository {
      * Gets internet message headers for an email.
      */
     async getMessageHeadersAsync(emailId) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Email ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         return await this.client.getMessageHeaders(graphId);
     }
     /**
      * Gets the MIME content of a message and saves it as an .eml file.
      */
     async getMessageMimeAsync(emailId) {
-        const graphId = this.idCache.messages.get(emailId);
-        if (graphId == null)
-            throw new Error(`Email ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphId = this.toGraphId(emailId, 'message');
         const mime = await this.client.getMessageMime(graphId);
         const downloadDir = getDownloadDir();
-        const filePath = path.join(downloadDir, `email-${emailId}.eml`);
+        const filePath = path.join(downloadDir, `email-${createHash('sha1').update(graphId).digest('hex').slice(0, 16)}.eml`);
         fs.writeFileSync(filePath, mime, 'utf-8');
         return { filePath };
     }
@@ -1802,15 +1496,16 @@ export class GraphRepository {
     // ===========================================================================
     /**
      * Lists all calendar groups.
+     *
+     * Orphan entity: no Graph URL takes a calendar-group id as a path segment,
+     * so this returns the raw Graph id string rather than minting a token.
      */
     async listCalendarGroupsAsync() {
         const groups = await this.client.listCalendarGroups();
         return groups.map((group) => {
             const graphId = group.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.calendarGroups.set(numericId, graphId);
             return {
-                id: numericId,
+                id: graphId,
                 name: group.name ?? '',
                 classId: group.classId?.toString() ?? '',
             };
@@ -1821,10 +1516,7 @@ export class GraphRepository {
      */
     async createCalendarGroupAsync(name) {
         const created = await this.client.createCalendarGroup(name);
-        const graphId = created.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.calendarGroups.set(numericId, graphId);
-        return numericId;
+        return created.id;
     }
     // ===========================================================================
     // Calendar Permissions
@@ -1833,17 +1525,12 @@ export class GraphRepository {
      * Lists all permissions for a calendar.
      */
     async listCalendarPermissionsAsync(calendarId) {
-        const graphCalendarId = this.idCache.calendars.get(calendarId);
-        if (graphCalendarId == null) {
-            throw new Error(`Calendar ID ${calendarId} not found in cache. Please call list_calendars first.`);
-        }
+        const graphCalendarId = this.toGraphId(calendarId, 'folder');
         const permissions = await this.client.listCalendarPermissions(graphCalendarId);
         return permissions.map((perm) => {
             const graphPermId = perm.id;
-            const numericId = hashStringToNumber(graphPermId);
-            this.idCache.calendarPermissions.set(numericId, { calendarId: graphCalendarId, permissionId: graphPermId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('calendarPermission', { calendarId: graphCalendarId, permissionId: graphPermId }),
                 emailAddress: perm.emailAddress?.address ?? '',
                 role: perm.role ?? 'none',
                 isRemovable: perm.isRemovable ?? false,
@@ -1855,10 +1542,7 @@ export class GraphRepository {
      * Creates a calendar permission (shares a calendar with someone).
      */
     async createCalendarPermissionAsync(calendarId, email, role) {
-        const graphCalendarId = this.idCache.calendars.get(calendarId);
-        if (graphCalendarId == null) {
-            throw new Error(`Calendar ID ${calendarId} not found in cache. Please call list_calendars first.`);
-        }
+        const graphCalendarId = this.toGraphId(calendarId, 'folder');
         const permission = await this.client.createCalendarPermission(graphCalendarId, {
             emailAddress: {
                 address: email,
@@ -1866,21 +1550,14 @@ export class GraphRepository {
             },
             role,
         });
-        const graphPermId = permission.id;
-        const numericId = hashStringToNumber(graphPermId);
-        this.idCache.calendarPermissions.set(numericId, { calendarId: graphCalendarId, permissionId: graphPermId });
-        return numericId;
+        return this.mintAliasComposite('calendarPermission', { calendarId: graphCalendarId, permissionId: permission.id });
     }
     /**
      * Deletes a calendar permission.
      */
     async deleteCalendarPermissionAsync(permissionId) {
-        const cached = this.idCache.calendarPermissions.get(permissionId);
-        if (cached == null) {
-            throw new Error(`Calendar permission ID ${permissionId} not found in cache. Please call list_calendar_permissions first.`);
-        }
-        await this.client.deleteCalendarPermission(cached.calendarId, cached.permissionId);
-        this.idCache.calendarPermissions.delete(permissionId);
+        const { calendarId, permissionId: permId } = this.toGraphParts(permissionId, 'calendarPermission', ['calendarId', 'permissionId']);
+        await this.client.deleteCalendarPermission(calendarId, permId);
     }
     // ===========================================================================
     // Room Lists & Rooms
@@ -1915,9 +1592,7 @@ export class GraphRepository {
         const teams = await this.client.listJoinedTeams();
         return teams.map((team) => {
             const graphId = team.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.teams.set(numericId, graphId);
-            return { id: numericId, name: team.displayName ?? '', description: team.description ?? '' };
+            return { id: this.mintAlias('team', graphId), name: team.displayName ?? '', description: team.description ?? '' };
         });
     }
     /**
@@ -1928,20 +1603,17 @@ export class GraphRepository {
         const channels = await this.client.listChannels(graphTeamId);
         return channels.map((ch) => {
             const graphId = ch.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.channels.set(numericId, { teamId: graphTeamId, channelId: graphId });
-            return { id: numericId, name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard' };
+            const id = this.mintAliasComposite('channel', { teamId: graphTeamId, channelId: graphId });
+            return { id, name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard' };
         });
     }
     /**
-     * Gets a specific channel by cached numeric ID.
+     * Gets a specific channel by durable cn_ token.
      */
     async getChannelAsync(channelId) {
-        const cached = this.idCache.channels.get(channelId);
-        if (cached == null)
-            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
-        const ch = await this.client.getChannel(cached.teamId, cached.channelId);
-        return { id: channelId, name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard', webUrl: ch.webUrl ?? '' };
+        const { teamId, channelId: graphChannelId } = this.toGraphParts(channelId, 'channel', ['teamId', 'channelId']);
+        const ch = await this.client.getChannel(teamId, graphChannelId);
+        return { id: String(channelId), name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard', webUrl: ch.webUrl ?? '' };
     }
     /**
      * Creates a new channel in a team.
@@ -1949,34 +1621,26 @@ export class GraphRepository {
     async createChannelAsync(teamId, name, description) {
         const graphTeamId = await this.resolveTeamId(teamId);
         const ch = await this.client.createChannel(graphTeamId, name, description);
-        const graphId = ch.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.channels.set(numericId, { teamId: graphTeamId, channelId: graphId });
-        return numericId;
+        return this.mintAliasComposite('channel', { teamId: graphTeamId, channelId: ch.id });
     }
     /**
      * Updates a channel's properties.
      */
     async updateChannelAsync(channelId, updates) {
-        const cached = this.idCache.channels.get(channelId);
-        if (cached == null)
-            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        const { teamId, channelId: graphChannelId } = this.toGraphParts(channelId, 'channel', ['teamId', 'channelId']);
         const graphUpdates = {};
         if (updates.name != null)
             graphUpdates['displayName'] = updates.name;
         if (updates.description != null)
             graphUpdates['description'] = updates.description;
-        await this.client.updateChannel(cached.teamId, cached.channelId, graphUpdates);
+        await this.client.updateChannel(teamId, graphChannelId, graphUpdates);
     }
     /**
      * Deletes a channel.
      */
     async deleteChannelAsync(channelId) {
-        const cached = this.idCache.channels.get(channelId);
-        if (cached == null)
-            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
-        await this.client.deleteChannel(cached.teamId, cached.channelId);
-        this.idCache.channels.delete(channelId);
+        const { teamId, channelId: graphChannelId } = this.toGraphParts(channelId, 'channel', ['teamId', 'channelId']);
+        await this.client.deleteChannel(teamId, graphChannelId);
     }
     /**
      * Lists members of a team.
@@ -1998,16 +1662,12 @@ export class GraphRepository {
      * Lists recent messages in a channel.
      */
     async listChannelMessagesAsync(channelId, limit = 25) {
-        const cached = this.idCache.channels.get(channelId);
-        if (cached == null)
-            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
-        const messages = await this.client.listChannelMessages(cached.teamId, cached.channelId, limit);
+        const { teamId, channelId: graphChannelId } = this.toGraphParts(channelId, 'channel', ['teamId', 'channelId']);
+        const messages = await this.client.listChannelMessages(teamId, graphChannelId, limit);
         return messages.map((msg) => {
             const graphId = msg.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('channelMessage', { teamId, channelId: graphChannelId, messageId: graphId }),
                 senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
                 senderEmail: msg.from?.user?.email ?? '',
                 bodyPreview: msg.body?.content?.substring(0, 200) ?? '',
@@ -2021,18 +1681,21 @@ export class GraphRepository {
      * Gets a specific channel message with its replies.
      */
     async getChannelMessageAsync(messageId) {
-        const cached = this.idCache.channelMessages.get(messageId);
-        if (cached == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+        const { teamId, channelId, messageId: graphMessageId } = this.toGraphParts(messageId, 'channelMessage', ['teamId', 'channelId', 'messageId']);
         const [msg, repliesRaw] = await Promise.all([
-            this.client.getChannelMessage(cached.teamId, cached.channelId, cached.messageId),
-            this.client.listChannelMessageReplies(cached.teamId, cached.channelId, cached.messageId),
+            this.client.getChannelMessage(teamId, channelId, graphMessageId),
+            this.client.listChannelMessageReplies(teamId, channelId, graphMessageId),
         ]);
         const replies = repliesRaw.map((r) => {
             const rGraphId = r.id;
-            const rNumericId = hashStringToNumber(rGraphId);
+            // Reply ids are display-only: a reply is a child entity addressed at
+            // /messages/{parentId}/replies/{replyId}, but this xm_ token (like the
+            // pre-migration numeric id before it) carries only {teamId, channelId,
+            // messageId}, so feeding it back to a message op resolves then 404s. No
+            // tool consumes a reply id — react/reply take the parent message id.
+            // Reply-level operations are tracked in issue #50.
             return {
-                id: rNumericId,
+                id: this.mintAliasComposite('channelMessage', { teamId, channelId, messageId: rGraphId }),
                 senderName: r.from?.user?.displayName ?? r.from?.application?.displayName ?? '',
                 senderEmail: r.from?.user?.email ?? '',
                 bodyContent: r.body?.content ?? '',
@@ -2041,7 +1704,7 @@ export class GraphRepository {
             };
         });
         return {
-            id: messageId,
+            id: String(messageId),
             senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
             senderEmail: msg.from?.user?.email ?? '',
             bodyContent: msg.body?.content ?? '',
@@ -2054,27 +1717,18 @@ export class GraphRepository {
      * Sends a new message to a channel.
      */
     async sendChannelMessageAsync(channelId, body, contentType = 'html') {
-        const cached = this.idCache.channels.get(channelId);
-        if (cached == null)
-            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
-        const msg = await this.client.sendChannelMessage(cached.teamId, cached.channelId, body, contentType);
+        const { teamId, channelId: graphChannelId } = this.toGraphParts(channelId, 'channel', ['teamId', 'channelId']);
+        const msg = await this.client.sendChannelMessage(teamId, graphChannelId, body, contentType);
         const graphId = msg.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
-        return numericId;
+        return this.mintAliasComposite('channelMessage', { teamId, channelId: graphChannelId, messageId: graphId });
     }
     /**
      * Replies to a channel message.
      */
     async replyToChannelMessageAsync(messageId, body, contentType = 'html') {
-        const cached = this.idCache.channelMessages.get(messageId);
-        if (cached == null)
-            throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
-        const reply = await this.client.replyToChannelMessage(cached.teamId, cached.channelId, cached.messageId, body, contentType);
-        const graphId = reply.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
-        return numericId;
+        const { teamId, channelId, messageId: graphMessageId } = this.toGraphParts(messageId, 'channelMessage', ['teamId', 'channelId', 'messageId']);
+        const reply = await this.client.replyToChannelMessage(teamId, channelId, graphMessageId, body, contentType);
+        return this.mintAliasComposite('channelMessage', { teamId, channelId, messageId: reply.id });
     }
     // ===========================================================================
     // Chats
@@ -2083,14 +1737,12 @@ export class GraphRepository {
         const chats = await this.client.listChats(limit);
         return chats.map((chat) => {
             const graphId = chat.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.chats.set(numericId, graphId);
             const chatRecord = chat;
             const preview = chatRecord.lastMessagePreview;
             const previewBody = preview?.body;
             const previewContent = previewBody?.content?.substring(0, 200) ?? '';
             return {
-                id: numericId,
+                id: this.mintAlias('chat', graphId),
                 topic: chat.topic ?? '',
                 chatType: chat.chatType ?? 'oneOnOne',
                 lastMessagePreview: previewContent,
@@ -2102,7 +1754,7 @@ export class GraphRepository {
         const graphId = await this.resolveChatId(chatId);
         const chat = await this.client.getChat(graphId);
         return {
-            id: chatId,
+            id: String(chatId),
             topic: chat.topic ?? '',
             chatType: chat.chatType ?? 'oneOnOne',
             createdDateTime: chat.createdDateTime ?? '',
@@ -2114,10 +1766,8 @@ export class GraphRepository {
         const messages = await this.client.listChatMessages(graphChatId, limit);
         return messages.map((msg) => {
             const graphId = msg.id;
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.chatMessages.set(numericId, { chatId: graphChatId, messageId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('chatMessage', { chatId: graphChatId, messageId: graphId }),
                 senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
                 senderEmail: msg.from?.user?.email ?? '',
                 bodyPreview: msg.body?.content?.substring(0, 200) ?? '',
@@ -2131,9 +1781,7 @@ export class GraphRepository {
         const graphChatId = await this.resolveChatId(chatId);
         const msg = await this.client.sendChatMessage(graphChatId, body, contentType);
         const graphId = msg.id;
-        const numericId = hashStringToNumber(graphId);
-        this.idCache.chatMessages.set(numericId, { chatId: graphChatId, messageId: graphId });
-        return numericId;
+        return this.mintAliasComposite('chatMessage', { chatId: graphChatId, messageId: graphId });
     }
     // ===========================================================================
     // Message Reactions
@@ -2152,46 +1800,34 @@ export class GraphRepository {
             });
         };
         if (messageType === 'channel') {
-            const cached = this.idCache.channelMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
-            const msg = await this.client.getChannelMessage(cached.teamId, cached.channelId, cached.messageId);
+            const { teamId, channelId, messageId: graphMessageId } = this.toGraphParts(messageId, 'channelMessage', ['teamId', 'channelId', 'messageId']);
+            const msg = await this.client.getChannelMessage(teamId, channelId, graphMessageId);
             return mapReactions(msg);
         }
         else {
-            const cached = this.idCache.chatMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
-            const msg = await this.client.getChatMessage(cached.chatId, cached.messageId);
+            const { chatId, messageId: graphMessageId } = this.toGraphParts(messageId, 'chatMessage', ['chatId', 'messageId']);
+            const msg = await this.client.getChatMessage(chatId, graphMessageId);
             return mapReactions(msg);
         }
     }
     async addMessageReactionAsync(messageId, messageType, reactionType) {
         if (messageType === 'channel') {
-            const cached = this.idCache.channelMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
-            await this.client.setChannelMessageReaction(cached.teamId, cached.channelId, cached.messageId, reactionType);
+            const { teamId, channelId, messageId: graphMessageId } = this.toGraphParts(messageId, 'channelMessage', ['teamId', 'channelId', 'messageId']);
+            await this.client.setChannelMessageReaction(teamId, channelId, graphMessageId, reactionType);
         }
         else {
-            const cached = this.idCache.chatMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
-            await this.client.setChatMessageReaction(cached.chatId, cached.messageId, reactionType);
+            const { chatId, messageId: graphMessageId } = this.toGraphParts(messageId, 'chatMessage', ['chatId', 'messageId']);
+            await this.client.setChatMessageReaction(chatId, graphMessageId, reactionType);
         }
     }
     async removeMessageReactionAsync(messageId, messageType, reactionType) {
         if (messageType === 'channel') {
-            const cached = this.idCache.channelMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
-            await this.client.unsetChannelMessageReaction(cached.teamId, cached.channelId, cached.messageId, reactionType);
+            const { teamId, channelId, messageId: graphMessageId } = this.toGraphParts(messageId, 'channelMessage', ['teamId', 'channelId', 'messageId']);
+            await this.client.unsetChannelMessageReaction(teamId, channelId, graphMessageId, reactionType);
         }
         else {
-            const cached = this.idCache.chatMessages.get(messageId);
-            if (cached == null)
-                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
-            await this.client.unsetChatMessageReaction(cached.chatId, cached.messageId, reactionType);
+            const { chatId, messageId: graphMessageId } = this.toGraphParts(messageId, 'chatMessage', ['chatId', 'messageId']);
+            await this.client.unsetChatMessageReaction(chatId, graphMessageId, reactionType);
         }
     }
     async listChatMembersAsync(chatId) {
@@ -2207,17 +1843,14 @@ export class GraphRepository {
     // Planner Plans
     // ===========================================================================
     /**
-     * Lists all plans the current user has.
+     * Lists all plans the current user has, minting durable pl_ tokens.
      */
     async listPlansAsync() {
         const plans = await this.client.listPlans();
         return plans.map((plan) => {
             const graphId = plan.id;
-            const numericId = hashStringToNumber(graphId);
-            const etag = plan['@odata.etag'] ?? '';
-            this.idCache.plans.set(numericId, { planId: graphId, etag });
             return {
-                id: numericId,
+                id: this.mintAlias('plan', graphId),
                 title: plan.title ?? '',
                 owner: plan.owner ?? '',
                 createdDateTime: plan.createdDateTime ?? '',
@@ -2225,19 +1858,17 @@ export class GraphRepository {
         });
     }
     /**
-     * Gets a specific plan by cached numeric ID.
+     * Gets a specific plan.
      */
     async getPlanAsync(planId) {
-        const cached = await this.resolvePlanId(planId);
-        const plan = await this.client.getPlan(cached.planId);
-        const etag = plan['@odata.etag'] ?? '';
-        this.idCache.plans.set(planId, { planId: cached.planId, etag });
+        const graphPlanId = await this.resolvePlanId(planId);
+        const plan = await this.client.getPlan(graphPlanId);
         return {
-            id: planId,
+            id: String(planId),
             title: plan.title ?? '',
             owner: plan.owner ?? '',
             createdDateTime: plan.createdDateTime ?? '',
-            etag,
+            etag: this.extractEtag(plan),
         };
     }
     /**
@@ -2245,42 +1876,34 @@ export class GraphRepository {
      */
     async createPlanAsync(title, groupId) {
         const plan = await this.client.createPlan(title, groupId);
-        const graphId = plan.id;
-        const numericId = hashStringToNumber(graphId);
-        const etag = plan['@odata.etag'] ?? '';
-        this.idCache.plans.set(numericId, { planId: graphId, etag });
-        return numericId;
+        return this.mintAlias('plan', plan.id);
     }
     /**
-     * Updates a plan (requires cached ETag).
+     * Updates a plan (U5b-5: fetches a fresh etag immediately before the write —
+     * etags are never cached across calls).
      */
     async updatePlanAsync(planId, updates) {
-        const cached = await this.resolvePlanId(planId);
+        const graphPlanId = await this.resolvePlanId(planId);
         const graphUpdates = {};
         if (updates.title != null)
             graphUpdates['title'] = updates.title;
-        const result = await this.client.updatePlan(cached.planId, graphUpdates, cached.etag);
-        const newEtag = result['@odata.etag'] ?? cached.etag;
-        this.idCache.plans.set(planId, { planId: cached.planId, etag: newEtag });
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getPlan(graphPlanId)), (etag) => this.client.updatePlan(graphPlanId, graphUpdates, etag));
     }
     // ===========================================================================
     // Planner Buckets
     // ===========================================================================
     /**
-     * Lists all buckets in a plan.
+     * Lists all buckets in a plan, minting durable pb_ tokens.
      */
     async listBucketsAsync(planId) {
-        const cached = await this.resolvePlanId(planId);
-        const buckets = await this.client.listBuckets(cached.planId);
+        const graphPlanId = await this.resolvePlanId(planId);
+        const buckets = await this.client.listBuckets(graphPlanId);
         return buckets.map((bucket) => {
             const graphId = bucket.id;
-            const numericId = hashStringToNumber(graphId);
-            const etag = bucket['@odata.etag'] ?? '';
-            this.idCache.plannerBuckets.set(numericId, { planId: cached.planId, bucketId: graphId, etag });
             return {
-                id: numericId,
+                id: this.mintAlias('plannerBucket', graphId),
                 name: bucket.name ?? '',
-                planId,
+                planId: String(planId),
                 orderHint: bucket.orderHint ?? '',
             };
         });
@@ -2289,61 +1912,42 @@ export class GraphRepository {
      * Creates a new bucket in a plan.
      */
     async createBucketAsync(planId, name) {
-        const cached = await this.resolvePlanId(planId);
-        const bucket = await this.client.createBucket(cached.planId, name);
-        const graphId = bucket.id;
-        const numericId = hashStringToNumber(graphId);
-        const etag = bucket['@odata.etag'] ?? '';
-        this.idCache.plannerBuckets.set(numericId, { planId: cached.planId, bucketId: graphId, etag });
-        return numericId;
+        const graphPlanId = await this.resolvePlanId(planId);
+        const bucket = await this.client.createBucket(graphPlanId, name);
+        return this.mintAlias('plannerBucket', bucket.id);
     }
     /**
-     * Updates a bucket (requires cached ETag).
+     * Updates a bucket (U5b-5: fetches a fresh etag immediately before the write).
      */
     async updateBucketAsync(bucketId, updates) {
-        const cached = this.idCache.plannerBuckets.get(bucketId);
-        if (cached == null)
-            throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
+        const graphBucketId = this.toGraphId(bucketId, 'plannerBucket');
         const graphUpdates = {};
         if (updates.name != null)
             graphUpdates['name'] = updates.name;
-        const result = await this.client.updateBucket(cached.bucketId, graphUpdates, cached.etag);
-        const newEtag = result['@odata.etag'] ?? cached.etag;
-        this.idCache.plannerBuckets.set(bucketId, { planId: cached.planId, bucketId: cached.bucketId, etag: newEtag });
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getBucket(graphBucketId)), (etag) => this.client.updateBucket(graphBucketId, graphUpdates, etag));
     }
     /**
-     * Deletes a bucket (requires cached ETag).
+     * Deletes a bucket (U5b-5: fetches a fresh etag immediately before the write).
      */
     async deleteBucketAsync(bucketId) {
-        const cached = this.idCache.plannerBuckets.get(bucketId);
-        if (cached == null)
-            throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
-        await this.client.deleteBucket(cached.bucketId, cached.etag);
-        this.idCache.plannerBuckets.delete(bucketId);
+        const graphBucketId = this.toGraphId(bucketId, 'plannerBucket');
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getBucket(graphBucketId)), (etag) => this.client.deleteBucket(graphBucketId, etag));
     }
     // ===========================================================================
     // Planner Tasks
     // ===========================================================================
     /**
-     * Lists all tasks in a plan.
+     * Lists all tasks in a plan, minting durable pt_ tokens.
      */
     async listPlannerTasksAsync(planId) {
-        const cached = await this.resolvePlanId(planId);
-        const tasks = await this.client.listPlannerTasks(cached.planId);
+        const graphPlanId = await this.resolvePlanId(planId);
+        const tasks = await this.client.listPlannerTasks(graphPlanId);
         return tasks.map((task) => {
             const graphId = task.id;
-            const numericId = hashStringToNumber(graphId);
-            const etag = task['@odata.etag'] ?? '';
-            this.idCache.plannerTasks.set(numericId, { taskId: graphId, etag });
-            // Resolve bucket numeric ID if present
-            let bucketNumericId = null;
-            if (task.bucketId != null) {
-                bucketNumericId = hashStringToNumber(task.bucketId);
-            }
             return {
-                id: numericId,
+                id: this.mintAlias('plannerTask', graphId),
                 title: task.title ?? '',
-                bucketId: bucketNumericId,
+                bucketId: task.bucketId != null ? this.mintAlias('plannerBucket', task.bucketId) : null,
                 assignees: task.assignments != null ? Object.keys(task.assignments) : [],
                 percentComplete: task.percentComplete ?? 0,
                 priority: task.priority ?? 5,
@@ -2354,23 +1958,39 @@ export class GraphRepository {
         });
     }
     /**
-     * Gets a specific planner task by cached numeric ID.
+     * Lists all Planner tasks assigned to the signed-in user, across every plan
+     * (`GET /me/planner/tasks`). Unlike the plan-scoped list, each task carries its
+     * own `planId`; the plan/bucket/task durable tokens are minted so follow-up
+     * get/update calls resolve without a re-list.
+     */
+    async listMyPlannerTasksAsync() {
+        const tasks = await this.client.listMyPlannerTasks();
+        return tasks.map((task) => {
+            const graphId = task.id;
+            return {
+                id: this.mintAlias('plannerTask', graphId),
+                title: task.title ?? '',
+                planId: task.planId != null ? this.mintAlias('plan', task.planId) : '',
+                bucketId: task.bucketId != null ? this.mintAlias('plannerBucket', task.bucketId) : null,
+                assignees: task.assignments != null ? Object.keys(task.assignments) : [],
+                percentComplete: task.percentComplete ?? 0,
+                priority: task.priority ?? 5,
+                startDateTime: task.startDateTime ?? '',
+                dueDateTime: task.dueDateTime ?? '',
+                createdDateTime: task.createdDateTime ?? '',
+            };
+        });
+    }
+    /**
+     * Gets a specific planner task.
      */
     async getPlannerTaskAsync(taskId) {
-        const cached = this.idCache.plannerTasks.get(taskId);
-        if (cached == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
-        const task = await this.client.getPlannerTask(cached.taskId);
-        const etag = task['@odata.etag'] ?? '';
-        this.idCache.plannerTasks.set(taskId, { taskId: cached.taskId, etag });
-        let bucketNumericId = null;
-        if (task.bucketId != null) {
-            bucketNumericId = hashStringToNumber(task.bucketId);
-        }
+        const gTaskId = this.toGraphId(taskId, 'plannerTask');
+        const task = await this.client.getPlannerTask(gTaskId);
         return {
-            id: taskId,
+            id: String(taskId),
             title: task.title ?? '',
-            bucketId: bucketNumericId,
+            bucketId: task.bucketId != null ? this.mintAlias('plannerBucket', task.bucketId) : null,
             assignees: task.assignments != null ? Object.keys(task.assignments) : [],
             percentComplete: task.percentComplete ?? 0,
             priority: task.priority ?? 5,
@@ -2379,20 +1999,17 @@ export class GraphRepository {
             createdDateTime: task.createdDateTime ?? '',
             conversationThreadId: task.conversationThreadId ?? '',
             orderHint: task.orderHint ?? '',
-            etag,
+            etag: this.extractEtag(task),
         };
     }
     /**
      * Creates a new planner task.
      */
     async createPlannerTaskAsync(planId, title, bucketId, assignments, priority, startDate, dueDate) {
-        const cachedPlan = await this.resolvePlanId(planId);
-        const body = { planId: cachedPlan.planId, title };
+        const graphPlanId = await this.resolvePlanId(planId);
+        const body = { planId: graphPlanId, title };
         if (bucketId != null) {
-            const cachedBucket = this.idCache.plannerBuckets.get(bucketId);
-            if (cachedBucket == null)
-                throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
-            body.bucketId = cachedBucket.bucketId;
+            body.bucketId = this.toGraphId(bucketId, 'plannerBucket');
         }
         if (assignments != null)
             body.assignments = assignments;
@@ -2403,28 +2020,18 @@ export class GraphRepository {
         if (dueDate != null)
             body.dueDateTime = dueDate;
         const task = await this.client.createPlannerTask(body);
-        const graphId = task.id;
-        const numericId = hashStringToNumber(graphId);
-        const etag = task['@odata.etag'] ?? '';
-        this.idCache.plannerTasks.set(numericId, { taskId: graphId, etag });
-        return numericId;
+        return this.mintAlias('plannerTask', task.id);
     }
     /**
-     * Updates a planner task (requires cached ETag).
+     * Updates a planner task (U5b-5: fetches a fresh etag immediately before the write).
      */
     async updatePlannerTaskAsync(taskId, updates) {
-        const cached = this.idCache.plannerTasks.get(taskId);
-        if (cached == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        const gTaskId = this.toGraphId(taskId, 'plannerTask');
         const graphUpdates = {};
         if (updates.title != null)
             graphUpdates['title'] = updates.title;
-        if (updates.bucketId != null) {
-            const cachedBucket = this.idCache.plannerBuckets.get(updates.bucketId);
-            if (cachedBucket == null)
-                throw new Error(`Bucket ID ${updates.bucketId} not found in cache. Try listing buckets first.`);
-            graphUpdates['bucketId'] = cachedBucket.bucketId;
-        }
+        if (updates.bucketId != null)
+            graphUpdates['bucketId'] = this.toGraphId(updates.bucketId, 'plannerBucket');
         if (updates.percentComplete != null)
             graphUpdates['percentComplete'] = updates.percentComplete;
         if (updates.priority != null)
@@ -2435,39 +2042,31 @@ export class GraphRepository {
             graphUpdates['dueDateTime'] = updates.dueDate;
         if (updates.assignments != null)
             graphUpdates['assignments'] = updates.assignments;
-        const result = await this.client.updatePlannerTask(cached.taskId, graphUpdates, cached.etag);
-        const newEtag = result['@odata.etag'] ?? cached.etag;
-        this.idCache.plannerTasks.set(taskId, { taskId: cached.taskId, etag: newEtag });
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getPlannerTask(gTaskId)), (etag) => this.client.updatePlannerTask(gTaskId, graphUpdates, etag));
     }
     /**
-     * Deletes a planner task (requires cached ETag).
+     * Deletes a planner task (U5b-5: fetches a fresh etag immediately before the write).
      */
     async deletePlannerTaskAsync(taskId) {
-        const cached = this.idCache.plannerTasks.get(taskId);
-        if (cached == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
-        await this.client.deletePlannerTask(cached.taskId, cached.etag);
-        this.idCache.plannerTasks.delete(taskId);
+        const gTaskId = this.toGraphId(taskId, 'plannerTask');
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getPlannerTask(gTaskId)), (etag) => this.client.deletePlannerTask(gTaskId, etag));
     }
     // ===========================================================================
     // Planner Task Details
     // ===========================================================================
     /**
-     * Gets details for a planner task (description, checklist, references).
+     * Gets details for a planner task (description, checklist, references). Task
+     * details piggyback the pt_ task token — they have no id of their own.
      */
     async getPlannerTaskDetailsAsync(taskId) {
-        const cached = this.idCache.plannerTasks.get(taskId);
-        if (cached == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
-        const details = await this.client.getPlannerTaskDetails(cached.taskId);
-        const etag = details['@odata.etag'] ?? '';
-        this.idCache.plannerTaskDetails.set(taskId, { taskId: cached.taskId, etag });
+        const gTaskId = this.toGraphId(taskId, 'plannerTask');
+        const details = await this.client.getPlannerTaskDetails(gTaskId);
         return {
-            id: taskId,
+            id: String(taskId),
             description: details.description ?? '',
             checklist: details.checklist ?? {},
             references: details.references ?? {},
-            etag,
+            etag: this.extractEtag(details),
         };
     }
     /**
@@ -2480,17 +2079,15 @@ export class GraphRepository {
      * have `details` set to `undefined`.
      */
     async listPlannerTasksWithDetailsAsync(planId) {
-        // Step 1: List all tasks (populates idCache.plannerTasks)
+        // Step 1: List all tasks (mints pt_ tokens, registered in the alias store)
         const tasks = await this.listPlannerTasksAsync(planId);
         if (tasks.length === 0)
             return [];
         // Step 2: Build batch requests for each task's details
         const batchRequests = tasks.map((task) => {
-            const cached = this.idCache.plannerTasks.get(task.id);
-            // cached is guaranteed to exist since listPlannerTasksAsync just populated it
-            const graphTaskId = cached.taskId;
+            const graphTaskId = this.toGraphId(task.id, 'plannerTask');
             return {
-                id: String(task.id),
+                id: task.id,
                 method: 'GET',
                 url: `/planner/tasks/${graphTaskId}/details`,
             };
@@ -2499,15 +2096,10 @@ export class GraphRepository {
         const batchResults = await this.client.batchRequests(batchRequests);
         // Step 4: Merge details into tasks
         return tasks.map((task) => {
-            const result = batchResults.get(String(task.id));
+            const result = batchResults.get(task.id);
             if (result != null && result.status >= 200 && result.status < 300) {
                 const detailBody = result.body;
                 const etag = result.headers?.ETag ?? result.headers?.etag ?? '';
-                // Cache the task detail ETag for later updates
-                const cachedTask = this.idCache.plannerTasks.get(task.id);
-                if (cachedTask != null) {
-                    this.idCache.plannerTaskDetails.set(task.id, { taskId: cachedTask.taskId, etag });
-                }
                 return {
                     ...task,
                     details: {
@@ -2523,15 +2115,12 @@ export class GraphRepository {
         });
     }
     /**
-     * Updates details for a planner task (requires cached ETag from getPlannerTaskDetailsAsync).
+     * Updates details for a planner task (U5b-5: fetches a fresh etag immediately
+     * before the write — the task details etag is independent of the task's own
+     * etag).
      */
     async updatePlannerTaskDetailsAsync(taskId, updates) {
-        const cachedTask = this.idCache.plannerTasks.get(taskId);
-        if (cachedTask == null)
-            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
-        const cachedDetails = this.idCache.plannerTaskDetails.get(taskId);
-        if (cachedDetails == null)
-            throw new Error(`Task details ETag for task ${taskId} not found in cache. Call get_planner_task_details first.`);
+        const gTaskId = this.toGraphId(taskId, 'plannerTask');
         const graphUpdates = {};
         if (updates.description != null)
             graphUpdates['description'] = updates.description;
@@ -2539,9 +2128,7 @@ export class GraphRepository {
             graphUpdates['checklist'] = updates.checklist;
         if (updates.references != null)
             graphUpdates['references'] = updates.references;
-        const result = await this.client.updatePlannerTaskDetails(cachedTask.taskId, graphUpdates, cachedDetails.etag);
-        const newEtag = result['@odata.etag'] ?? cachedDetails.etag;
-        this.idCache.plannerTaskDetails.set(taskId, { taskId: cachedTask.taskId, etag: newEtag });
+        await this.withFreshEtag(async () => this.extractEtag(await this.client.getPlannerTaskDetails(gTaskId)), (etag) => this.client.updatePlannerTaskDetails(gTaskId, graphUpdates, etag));
     }
     // ===========================================================================
     // Planner Visualization Data
@@ -2566,7 +2153,7 @@ export class GraphRepository {
             tasks: tasks.map(t => ({
                 id: t.id,
                 title: t.title,
-                bucketId: t.bucketId ?? 0,
+                bucketId: t.bucketId ?? '',
                 percentComplete: t.percentComplete,
                 priority: t.priority,
                 startDateTime: t.startDateTime || null,
@@ -2582,10 +2169,8 @@ export class GraphRepository {
         const meetings = await this.client.listOnlineMeetings(limit ?? 20);
         return meetings.map((meeting) => {
             const graphId = meeting.id ?? '';
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.onlineMeetings.set(numericId, graphId);
             return {
-                id: numericId,
+                id: this.mintAlias('onlineMeeting', graphId),
                 subject: meeting.subject ?? '',
                 startDateTime: meeting.startDateTime ?? '',
                 endDateTime: meeting.endDateTime ?? '',
@@ -2595,103 +2180,96 @@ export class GraphRepository {
     }
     async getOnlineMeetingAsync(meetingId) {
         const mapMeeting = (m) => ({
-            id: meetingId,
+            id: String(meetingId),
             subject: m.subject ?? '',
             startDateTime: m.startDateTime ?? '',
             endDateTime: m.endDateTime ?? '',
             joinUrl: m.joinWebUrl ?? '',
             participants: m.participants ?? null,
         });
-        const graphId = this.idCache.onlineMeetings.get(meetingId);
-        if (graphId == null) {
-            // Try to refresh cache
-            await this.listOnlineMeetingsAsync(100);
-            const refreshedId = this.idCache.onlineMeetings.get(meetingId);
-            if (refreshedId == null)
-                return undefined;
-            const meeting = await this.client.getOnlineMeeting(refreshedId);
-            return mapMeeting(meeting);
+        // om_ tokens resolve from the alias store. On a cold miss (never listed this
+        // session, or a lost store) re-list — listOnlineMeetingsAsync deterministically
+        // re-mints and re-stores the same token — then retry the resolve, matching
+        // the resolveTeamId self-heal pattern. A final miss means "not found" (the
+        // documented contract), not an error.
+        let graphId;
+        try {
+            graphId = this.toGraphId(meetingId, 'onlineMeeting');
+        }
+        catch (e) {
+            if (e instanceof IdUnknownError) {
+                await this.listOnlineMeetingsAsync();
+                try {
+                    graphId = this.toGraphId(meetingId, 'onlineMeeting');
+                }
+                catch (e2) {
+                    if (e2 instanceof IdUnknownError)
+                        return undefined;
+                    throw e2;
+                }
+            }
+            else {
+                throw e;
+            }
         }
         const meeting = await this.client.getOnlineMeeting(graphId);
         return mapMeeting(meeting);
     }
     async listMeetingRecordingsAsync(meetingId) {
-        const graphMeetingId = this.idCache.onlineMeetings.get(meetingId);
-        if (graphMeetingId == null)
-            throw new Error(`Meeting ID ${meetingId} not found in cache. Try listing online meetings first.`);
+        const graphMeetingId = this.toGraphId(meetingId, 'onlineMeeting');
         const recordings = await this.client.listMeetingRecordings(graphMeetingId);
         return recordings.map((recording) => {
             const graphId = recording.id ?? '';
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.recordings.set(numericId, { meetingId: graphMeetingId, recordingId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('recording', { meetingId: graphMeetingId, recordingId: graphId }),
                 createdDateTime: recording.createdDateTime ?? '',
                 recordingContentUrl: recording.recordingContentUrl ?? '',
             };
         });
     }
     async downloadMeetingRecordingAsync(recordingId, outputPath) {
-        const cached = this.idCache.recordings.get(recordingId);
-        if (cached == null)
-            throw new Error(`Recording ID ${recordingId} not found in cache. Call list_meeting_recordings first.`);
-        const content = await this.client.getMeetingRecordingContent(cached.meetingId, cached.recordingId);
+        const { meetingId, recordingId: recId } = this.toGraphParts(recordingId, 'recording', ['meetingId', 'recordingId']);
+        const content = await this.client.getMeetingRecordingContent(meetingId, recId);
         fs.writeFileSync(outputPath, Buffer.from(content));
         return outputPath;
     }
     async listMeetingTranscriptsAsync(meetingId) {
-        const graphMeetingId = this.idCache.onlineMeetings.get(meetingId);
-        if (graphMeetingId == null)
-            throw new Error(`Meeting ID ${meetingId} not found in cache. Try listing online meetings first.`);
+        const graphMeetingId = this.toGraphId(meetingId, 'onlineMeeting');
         const transcripts = await this.client.listMeetingTranscripts(graphMeetingId);
         return transcripts.map((transcript) => {
             const graphId = transcript.id ?? '';
-            const numericId = hashStringToNumber(graphId);
-            this.idCache.transcripts.set(numericId, { meetingId: graphMeetingId, transcriptId: graphId });
             return {
-                id: numericId,
+                id: this.mintAliasComposite('transcript', { meetingId: graphMeetingId, transcriptId: graphId }),
                 createdDateTime: transcript.createdDateTime ?? '',
                 contentUrl: transcript.contentUrl ?? '',
             };
         });
     }
     async getMeetingTranscriptContentAsync(transcriptId, format) {
-        const cached = this.idCache.transcripts.get(transcriptId);
-        if (cached == null)
-            throw new Error(`Transcript ID ${transcriptId} not found in cache. Call list_meeting_transcripts first.`);
-        return await this.client.getMeetingTranscriptContent(cached.meetingId, cached.transcriptId, format ?? 'text/vtt');
+        const { meetingId, transcriptId: tId } = this.toGraphParts(transcriptId, 'transcript', ['meetingId', 'transcriptId']);
+        return await this.client.getMeetingTranscriptContent(meetingId, tId, format ?? 'text/vtt');
     }
     // ===========================================================================
     // Excel Online (Workbook)
     // ===========================================================================
     async listWorksheetsAsync(fileId) {
-        const driveItemId = this.idCache.driveItems.get(fileId);
-        if (driveItemId == null)
-            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        const driveItemId = this.toGraphId(fileId, 'driveItem');
         return await this.client.listWorksheets(driveItemId);
     }
     async getWorksheetRangeAsync(fileId, worksheetName, range) {
-        const driveItemId = this.idCache.driveItems.get(fileId);
-        if (driveItemId == null)
-            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        const driveItemId = this.toGraphId(fileId, 'driveItem');
         return await this.client.getWorksheetRange(driveItemId, worksheetName, range);
     }
     async getUsedRangeAsync(fileId, worksheetName) {
-        const driveItemId = this.idCache.driveItems.get(fileId);
-        if (driveItemId == null)
-            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        const driveItemId = this.toGraphId(fileId, 'driveItem');
         return await this.client.getUsedRange(driveItemId, worksheetName);
     }
     async updateWorksheetRangeAsync(fileId, worksheetName, range, values) {
-        const driveItemId = this.idCache.driveItems.get(fileId);
-        if (driveItemId == null)
-            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        const driveItemId = this.toGraphId(fileId, 'driveItem');
         return await this.client.updateWorksheetRange(driveItemId, worksheetName, range, values);
     }
     async getTableDataAsync(fileId, tableName) {
-        const driveItemId = this.idCache.driveItems.get(fileId);
-        if (driveItemId == null)
-            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        const driveItemId = this.toGraphId(fileId, 'driveItem');
         return await this.client.getTableData(driveItemId, tableName);
     }
     // OneDrive
@@ -2700,19 +2278,15 @@ export class GraphRepository {
      * Lists files/folders in a drive folder (or root).
      */
     async listDriveItemsAsync(folderId) {
-        let graphFolderId;
-        if (folderId != null) {
-            graphFolderId = this.idCache.driveItems.get(folderId);
-            if (graphFolderId == null)
-                throw new Error(`Drive item ID ${folderId} not found in cache. Try listing drive items first.`);
-        }
+        const graphFolderId = folderId != null
+            ? this.toGraphId(folderId, 'driveItem')
+            : undefined;
         const items = await this.client.listDriveItems(graphFolderId);
+        // Rows carry self-encoding dr_ tokens (minted here) — no cache.
         return items.map((item) => {
             const itemId = item.id;
-            const numericId = hashStringToNumber(itemId);
-            this.idCache.driveItems.set(numericId, itemId);
             return {
-                id: numericId,
+                id: itemId.length > 0 ? mintSelfEncoded('driveItem', itemId) : '',
                 name: item.name ?? '',
                 size: item.size ?? 0,
                 lastModified: item.lastModifiedDateTime ?? '',
@@ -2728,10 +2302,8 @@ export class GraphRepository {
         const items = await this.client.searchDriveItems(query, limit);
         return items.map((item) => {
             const itemId = item.id;
-            const numericId = hashStringToNumber(itemId);
-            this.idCache.driveItems.set(numericId, itemId);
             return {
-                id: numericId,
+                id: itemId.length > 0 ? mintSelfEncoded('driveItem', itemId) : '',
                 name: item.name ?? '',
                 size: item.size ?? 0,
                 lastModified: item.lastModifiedDateTime ?? '',
@@ -2744,15 +2316,13 @@ export class GraphRepository {
      * Gets metadata for a specific drive item.
      */
     async getDriveItemAsync(itemId) {
-        const graphId = this.idCache.driveItems.get(itemId);
-        if (graphId == null)
-            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const graphId = this.toGraphId(itemId, 'driveItem');
         const item = await this.client.getDriveItem(graphId);
         const fileObj = item.file;
         const createdByObj = item.createdBy;
         const createdByUser = createdByObj?.user;
         return {
-            id: itemId,
+            id: mintSelfEncoded('driveItem', graphId),
             name: item.name ?? '',
             size: item.size ?? 0,
             lastModified: item.lastModifiedDateTime ?? '',
@@ -2766,9 +2336,7 @@ export class GraphRepository {
      * Downloads a drive item to a local file.
      */
     async downloadFileAsync(itemId, outputPath) {
-        const graphId = this.idCache.driveItems.get(itemId);
-        if (graphId == null)
-            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const graphId = this.toGraphId(itemId, 'driveItem');
         const content = await this.client.downloadDriveItem(graphId);
         const buffer = Buffer.from(content);
         fs.writeFileSync(outputPath, buffer);
@@ -2781,9 +2349,7 @@ export class GraphRepository {
         const content = fs.readFileSync(localFilePath);
         const result = await this.client.uploadDriveItem(parentPath, fileName, content);
         const resultId = result.id;
-        const numericId = hashStringToNumber(resultId);
-        this.idCache.driveItems.set(numericId, resultId);
-        return numericId;
+        return mintSelfEncoded('driveItem', resultId);
     }
     /**
      * Lists recently accessed drive items.
@@ -2792,10 +2358,8 @@ export class GraphRepository {
         const items = await this.client.listRecentDriveItems();
         return items.map((item) => {
             const itemId = item.id;
-            const numericId = hashStringToNumber(itemId);
-            this.idCache.driveItems.set(numericId, itemId);
             return {
-                id: numericId,
+                id: itemId.length > 0 ? mintSelfEncoded('driveItem', itemId) : '',
                 name: item.name ?? '',
                 size: item.size ?? 0,
                 lastModified: item.lastModifiedDateTime ?? '',
@@ -2811,10 +2375,8 @@ export class GraphRepository {
         const items = await this.client.listSharedWithMe();
         return items.map((item) => {
             const itemId = item.id;
-            const numericId = hashStringToNumber(itemId);
-            this.idCache.driveItems.set(numericId, itemId);
             return {
-                id: numericId,
+                id: itemId.length > 0 ? mintSelfEncoded('driveItem', itemId) : '',
                 name: item.name ?? '',
                 size: item.size ?? 0,
                 lastModified: item.lastModifiedDateTime ?? '',
@@ -2827,9 +2389,7 @@ export class GraphRepository {
      * Creates a sharing link for a drive item.
      */
     async createSharingLinkAsync(itemId, type, scope) {
-        const graphId = this.idCache.driveItems.get(itemId);
-        if (graphId == null)
-            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const graphId = this.toGraphId(itemId, 'driveItem');
         const result = await this.client.createSharingLink(graphId, type, scope);
         const link = result.link;
         return {
@@ -2842,17 +2402,14 @@ export class GraphRepository {
      * Deletes a drive item.
      */
     async deleteDriveItemAsync(itemId) {
-        const graphId = this.idCache.driveItems.get(itemId);
-        if (graphId == null)
-            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const graphId = this.toGraphId(itemId, 'driveItem');
         await this.client.deleteDriveItem(graphId);
-        this.idCache.driveItems.delete(itemId);
     }
     // ===========================================================================
     // SharePoint Sites & Document Libraries
     // ===========================================================================
     /**
-     * Lists followed SharePoint sites, caching IDs.
+     * Lists followed SharePoint sites, minting durable si_ tokens.
      */
     async listSitesAsync() {
         const sites = await this.client.listFollowedSites();
@@ -2860,10 +2417,8 @@ export class GraphRepository {
         for (const site of sites) {
             const siteId = site.id;
             if (siteId != null) {
-                const numericId = hashStringToNumber(siteId);
-                this.idCache.sites.set(numericId, siteId);
                 result.push({
-                    id: numericId,
+                    id: this.mintAlias('site', siteId),
                     name: site.name ?? '',
                     webUrl: site.webUrl ?? '',
                     displayName: site.displayName ?? '',
@@ -2873,7 +2428,7 @@ export class GraphRepository {
         return result;
     }
     /**
-     * Searches SharePoint sites by keyword, caching IDs.
+     * Searches SharePoint sites by keyword, minting durable si_ tokens.
      */
     async searchSitesAsync(query) {
         const sites = await this.client.searchSites(query);
@@ -2881,10 +2436,8 @@ export class GraphRepository {
         for (const site of sites) {
             const siteId = site.id;
             if (siteId != null) {
-                const numericId = hashStringToNumber(siteId);
-                this.idCache.sites.set(numericId, siteId);
                 result.push({
-                    id: numericId,
+                    id: this.mintAlias('site', siteId),
                     name: site.name ?? '',
                     webUrl: site.webUrl ?? '',
                     displayName: site.displayName ?? '',
@@ -2897,12 +2450,10 @@ export class GraphRepository {
      * Gets details for a specific SharePoint site.
      */
     async getSiteAsync(siteId) {
-        const graphId = this.idCache.sites.get(siteId);
-        if (graphId == null)
-            throw new Error(`Site ID ${siteId} not found in cache. Try listing or searching sites first.`);
+        const graphId = this.toGraphId(siteId, 'site');
         const site = await this.client.getSite(graphId);
         return {
-            id: siteId,
+            id: String(siteId),
             name: site.name ?? '',
             webUrl: site.webUrl ?? '',
             displayName: site.displayName ?? '',
@@ -2910,21 +2461,17 @@ export class GraphRepository {
         };
     }
     /**
-     * Lists document libraries for a SharePoint site, caching IDs.
+     * Lists document libraries for a SharePoint site, minting durable dl_ tokens.
      */
     async listDocumentLibrariesAsync(siteId) {
-        const graphSiteId = this.idCache.sites.get(siteId);
-        if (graphSiteId == null)
-            throw new Error(`Site ID ${siteId} not found in cache. Try listing or searching sites first.`);
+        const graphSiteId = this.toGraphId(siteId, 'site');
         const drives = await this.client.listDocumentLibraries(graphSiteId);
         const result = [];
         for (const drive of drives) {
             const driveId = drive.id;
             if (driveId != null) {
-                const numericId = hashStringToNumber(driveId);
-                this.idCache.documentLibraries.set(numericId, { siteId: graphSiteId, driveId });
                 result.push({
-                    id: numericId,
+                    id: this.mintAliasComposite('documentLibrary', { siteId: graphSiteId, driveId }),
                     name: drive.name ?? '',
                     webUrl: drive.webUrl ?? '',
                     driveType: drive.driveType ?? '',
@@ -2934,28 +2481,21 @@ export class GraphRepository {
         return result;
     }
     /**
-     * Lists items in a document library or folder, caching IDs.
+     * Lists items in a document library or folder, minting durable li_ tokens.
      */
     async listLibraryItemsAsync(libraryId, folderId) {
-        const libCached = this.idCache.documentLibraries.get(libraryId);
-        if (libCached == null)
-            throw new Error(`Library ID ${libraryId} not found in cache. Try listing document libraries first.`);
+        const libCached = this.toGraphParts(libraryId, 'documentLibrary', ['siteId', 'driveId']);
         let folderItemId;
         if (folderId != null) {
-            const folderCached = this.idCache.libraryDriveItems.get(folderId);
-            if (folderCached == null)
-                throw new Error(`Folder ID ${folderId} not found in cache. Try listing library items first.`);
-            folderItemId = folderCached.itemId;
+            folderItemId = this.toGraphParts(folderId, 'libraryDriveItem', ['driveId', 'itemId']).itemId;
         }
         const items = await this.client.listLibraryItems(libCached.driveId, folderItemId);
         const result = [];
         for (const item of items) {
             const itemGraphId = item.id;
             if (itemGraphId != null) {
-                const numericId = hashStringToNumber(itemGraphId);
-                this.idCache.libraryDriveItems.set(numericId, { driveId: libCached.driveId, itemId: itemGraphId });
                 result.push({
-                    id: numericId,
+                    id: this.mintAliasComposite('libraryDriveItem', { driveId: libCached.driveId, itemId: itemGraphId }),
                     name: item.name ?? '',
                     size: item.size ?? 0,
                     webUrl: item.webUrl ?? '',
@@ -2970,9 +2510,7 @@ export class GraphRepository {
      * Downloads a file from a document library to the specified path.
      */
     async downloadLibraryFileAsync(itemId, outputPath) {
-        const cached = this.idCache.libraryDriveItems.get(itemId);
-        if (cached == null)
-            throw new Error(`Item ID ${itemId} not found in cache. Try listing library items first.`);
+        const cached = this.toGraphParts(itemId, 'libraryDriveItem', ['driveId', 'itemId']);
         const content = await this.client.downloadLibraryFile(cached.driveId, cached.itemId);
         const resolvedPath = path.resolve(outputPath);
         const dir = path.dirname(resolvedPath);
@@ -2981,16 +2519,171 @@ export class GraphRepository {
         return resolvedPath;
     }
     /**
-     * Gets the Graph string ID for a folder from the cache.
+     * Resolves a folder id (durable `fd_` token or raw Graph id) to its Graph id.
      */
     getFolderGraphId(folderId) {
-        return this.idCache.folders.get(folderId);
+        return this.toGraphId(folderId, 'folder');
     }
+    // ===========================================================================
+    // SharePoint Lists
+    // ===========================================================================
+    /**
+     * Lists the SharePoint lists in a site, minting durable sl_ tokens. Each list
+     * token carries the {siteId, listId} tuple its Graph URL needs.
+     */
+    async listSharePointListsAsync(siteId) {
+        const graphSiteId = this.toGraphId(siteId, 'site');
+        const lists = await this.client.listSharePointLists(graphSiteId);
+        const result = [];
+        for (const list of lists) {
+            const listId = list.id;
+            if (listId != null) {
+                result.push({
+                    id: this.mintAliasComposite('sharePointList', { siteId: graphSiteId, listId }),
+                    name: list.name ?? '',
+                    displayName: list.displayName ?? '',
+                    description: list.description ?? '',
+                    webUrl: list.webUrl ?? '',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Gets a specific SharePoint list, resolving the sl_ token to its tuple.
+     */
+    async getSharePointListAsync(listId) {
+        const { siteId, listId: graphListId } = this.toGraphParts(listId, 'sharePointList', ['siteId', 'listId']);
+        const list = await this.client.getSharePointList(siteId, graphListId);
+        return {
+            id: String(listId),
+            name: list.name ?? '',
+            displayName: list.displayName ?? '',
+            description: list.description ?? '',
+            webUrl: list.webUrl ?? '',
+        };
+    }
+    /**
+     * Creates a SharePoint list in a site, minting a durable sl_ token.
+     */
+    async createSharePointListAsync(siteId, displayName, description) {
+        const graphSiteId = this.toGraphId(siteId, 'site');
+        const body = {
+            displayName,
+            list: { template: 'genericList' },
+        };
+        if (description != null) {
+            body.description = description;
+        }
+        const created = await this.client.createSharePointList(graphSiteId, body);
+        const newListId = created.id;
+        if (newListId == null || newListId.length === 0) {
+            // Mint guard (matches #46/#47): a composite token minted with an empty id
+            // would digest to a resolvable-but-wrong token and be reported as 'created'.
+            throw new Error('SharePoint list creation returned no id.');
+        }
+        return this.mintAliasComposite('sharePointList', { siteId: graphSiteId, listId: newListId });
+    }
+    /**
+     * Lists the column definitions for a SharePoint list. Columns are addressed by
+     * name in item field values, so they carry no durable token.
+     */
+    async listSharePointListColumnsAsync(listId) {
+        const { siteId, listId: graphListId } = this.toGraphParts(listId, 'sharePointList', ['siteId', 'listId']);
+        const columns = await this.client.listSharePointListColumns(siteId, graphListId);
+        return columns.map((col) => ({
+            id: col.id ?? '',
+            name: col.name ?? '',
+            displayName: col.displayName ?? '',
+            columnType: sharePointColumnType(col),
+            required: col.required ?? false,
+            readOnly: col.readOnly ?? false,
+        }));
+    }
+    /**
+     * Lists the items in a SharePoint list, minting durable sn_ tokens that carry
+     * the {siteId, listId, itemId} tuple.
+     */
+    async listSharePointListItemsAsync(listId, limit = 50) {
+        const { siteId, listId: graphListId } = this.toGraphParts(listId, 'sharePointList', ['siteId', 'listId']);
+        const items = await this.client.listSharePointListItems(siteId, graphListId, limit);
+        const result = [];
+        for (const item of items) {
+            const itemGraphId = item.id;
+            if (itemGraphId != null) {
+                result.push({
+                    id: this.mintAliasComposite('sharePointListItem', { siteId, listId: graphListId, itemId: itemGraphId }),
+                    fields: item.fields ?? {},
+                    webUrl: item.webUrl ?? '',
+                    createdDateTime: item.createdDateTime ?? '',
+                    lastModifiedDateTime: item.lastModifiedDateTime ?? '',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Gets a specific SharePoint list item, resolving the sn_ token to its tuple.
+     */
+    async getSharePointListItemAsync(itemId) {
+        const { siteId, listId, itemId: graphItemId } = this.toGraphParts(itemId, 'sharePointListItem', ['siteId', 'listId', 'itemId']);
+        const item = await this.client.getSharePointListItem(siteId, listId, graphItemId);
+        return {
+            id: String(itemId),
+            fields: item.fields ?? {},
+            webUrl: item.webUrl ?? '',
+            createdDateTime: item.createdDateTime ?? '',
+            lastModifiedDateTime: item.lastModifiedDateTime ?? '',
+        };
+    }
+    /**
+     * Creates an item in a SharePoint list, minting a durable sn_ token.
+     */
+    async createSharePointListItemAsync(listId, fields) {
+        const { siteId, listId: graphListId } = this.toGraphParts(listId, 'sharePointList', ['siteId', 'listId']);
+        const created = await this.client.createSharePointListItem(siteId, graphListId, fields);
+        const newItemId = created.id;
+        if (newItemId == null || newItemId.length === 0) {
+            // Mint guard (matches #46/#47): see createSharePointListAsync.
+            throw new Error('SharePoint list item creation returned no id.');
+        }
+        return this.mintAliasComposite('sharePointListItem', { siteId, listId: graphListId, itemId: newItemId });
+    }
+    /**
+     * Updates the field values of a SharePoint list item.
+     */
+    async updateSharePointListItemAsync(itemId, fields) {
+        const { siteId, listId, itemId: graphItemId } = this.toGraphParts(itemId, 'sharePointListItem', ['siteId', 'listId', 'itemId']);
+        await this.client.updateSharePointListItem(siteId, listId, graphItemId, fields);
+    }
+    /**
+     * Deletes an item from a SharePoint list.
+     */
+    async deleteSharePointListItemAsync(itemId) {
+        const { siteId, listId, itemId: graphItemId } = this.toGraphParts(itemId, 'sharePointListItem', ['siteId', 'listId', 'itemId']);
+        await this.client.deleteSharePointListItem(siteId, listId, graphItemId);
+    }
+}
+/**
+ * Derives a SharePoint column's type from its definition facets. Graph encodes
+ * the type as the presence of a facet (`text`, `number`, `boolean`, …) rather
+ * than a single field, so return the first facet present or 'unknown'.
+ */
+function sharePointColumnType(col) {
+    const facets = [
+        'text', 'number', 'boolean', 'dateTime', 'choice', 'currency',
+        'personOrGroup', 'lookup', 'hyperlinkOrPicture', 'calculated',
+    ];
+    for (const facet of facets) {
+        if (col[facet] != null)
+            return facet;
+    }
+    return 'unknown';
 }
 /**
  * Creates a Microsoft Graph API repository.
  */
-export function createGraphRepository(deviceCodeCallback) {
-    return new GraphRepository(deviceCodeCallback);
+export function createGraphRepository(deviceCodeCallback, store, accountId) {
+    return new GraphRepository(deviceCodeCallback, store, accountId);
 }
 //# sourceMappingURL=repository.js.map