@jbctechsolutions/mcp-office365 2.5.1 → 4.0.0

package/dist/graph/repository.d.ts

@@ -11,6 +11,8 @@
 import type { IRepository, FolderRow, EmailRow, EventRow, ContactRow, TaskRow, NoteRow } from '../database/repository.js';
 import { GraphClient } from './client/index.js';
 import type { DeviceCodeCallback } from './auth/index.js';
+import type { StateStore } from '../state/store.js';
+import type { CompiledSearch } from '../search/compiler.js';
 import type { PlanVisualizationData } from '../visualization/types.js';
 /**
  * Repository implementation using Microsoft Graph API.
@@ -19,97 +21,148 @@ import type { PlanVisualizationData } from '../visualization/types.js';
  */
 export declare class GraphRepository implements IRepository {
     private readonly client;
+    private readonly store;
+    private readonly accountId;
     private readonly deltaLinks;
-    private readonly idCache;
-    constructor(deviceCodeCallback?: DeviceCodeCallback);
+    constructor(deviceCodeCallback?: DeviceCodeCallback, store?: StateStore, accountId?: () => string);
+    /**
+     * 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.
+     */
+    private toGraphId;
+    /**
+     * 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.
+     */
+    private mintAlias;
+    /**
+     * 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.
+     */
+    private mintAliasComposite;
+    /**
+     * 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.
+     */
+    private toGraphParts;
+    private resolveTeamId;
+    private resolvePlanId;
+    /** True for an HTTP 412 (Precondition Failed) — the `If-Match` etag we sent no
+     * longer matches the entity's current etag. */
+    private isPreconditionFailed;
+    /** Extracts the OData etag from a fetched entity, defaulting to `''` when absent. */
+    private extractEtag;
+    /**
+     * 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.
+     */
+    private withFreshEtag;
+    private resolveChatId;
     listFolders(): FolderRow[];
     listFoldersAsync(): Promise<FolderRow[]>;
-    getFolder(_id: number): FolderRow | undefined;
-    getFolderAsync(id: number): Promise<FolderRow | undefined>;
+    getFolder(_id: string): FolderRow | undefined;
+    getFolderAsync(id: string): Promise<FolderRow | undefined>;
     listEmails(_folderId: number, _limit: number, _offset: number): EmailRow[];
-    listEmailsAsync(folderId: number, limit: number, offset: number): Promise<EmailRow[]>;
+    listEmailsAsync(folderId: string, limit: number, offset: number): Promise<EmailRow[]>;
     private listEmailsWithGraphId;
     listUnreadEmails(_folderId: number, _limit: number, _offset: number): EmailRow[];
-    listUnreadEmailsAsync(folderId: number, limit: number, offset: number): Promise<EmailRow[]>;
+    listUnreadEmailsAsync(folderId: string, limit: number, offset: number): Promise<EmailRow[]>;
     private listUnreadEmailsWithGraphId;
     searchEmails(_query: string, _limit: number): EmailRow[];
     searchEmailsAsync(query: string, limit: number): Promise<EmailRow[]>;
     searchEmailsInFolder(_folderId: number, _query: string, _limit: number): EmailRow[];
-    searchEmailsInFolderAsync(folderId: number, query: string, limit: number): Promise<EmailRow[]>;
+    searchEmailsInFolderAsync(folderId: string, query: string, limit: number): Promise<EmailRow[]>;
     private searchEmailsInFolderWithGraphId;
     /**
-     * Advanced search using raw KQL query syntax.
-     */
-    searchEmailsAdvancedAsync(query: string, limit: number): Promise<EmailRow[]>;
-    /**
-     * Advanced search in a specific folder using raw KQL query syntax.
+     * Structured advanced search (U7 / D9). Runs a compiled query on the correct
+     * Graph mechanism ($filter / quoted $search / /search/query), then caches IDs
+     * and maps to EmailRow[] exactly like the raw-KQL path it replaces.
      */
-    searchEmailsAdvancedInFolderAsync(folderId: number, query: string, limit: number): Promise<EmailRow[]>;
-    checkNewEmailsAsync(folderId: number): Promise<{
+    searchEmailsStructuredAsync(compiled: CompiledSearch, limit: number): Promise<EmailRow[]>;
+    private runStructuredSearch;
+    checkNewEmailsAsync(folderId: string): Promise<{
         emails: EmailRow[];
         isInitialSync: boolean;
     }>;
-    getEmail(_id: number): EmailRow | undefined;
-    /**
-     * 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).
-     */
-    private refreshMessageCacheForGetEmail;
-    getEmailAsync(id: number): Promise<EmailRow | undefined>;
+    getEmail(_id: string): EmailRow | undefined;
+    getEmailAsync(id: string): Promise<EmailRow | undefined>;
     getUnreadCount(): number;
     getUnreadCountAsync(): Promise<number>;
     getUnreadCountByFolder(_folderId: number): number;
-    getUnreadCountByFolderAsync(folderId: number): Promise<number>;
+    getUnreadCountByFolderAsync(folderId: string): Promise<number>;
     /**
      * 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.
      */
-    listConversationAsync(messageId: number, limit: number): Promise<EmailRow[]>;
+    listConversationAsync(messageId: string, limit: number): Promise<EmailRow[]>;
     listCalendars(): FolderRow[];
     listCalendarsAsync(): Promise<FolderRow[]>;
     listEvents(_limit: number): EventRow[];
     listEventsAsync(limit: number): Promise<EventRow[]>;
     listEventsByFolder(_folderId: number, _limit: number): EventRow[];
-    listEventsByFolderAsync(folderId: number, limit: number): Promise<EventRow[]>;
+    listEventsByFolderAsync(folderId: string, limit: number): Promise<EventRow[]>;
     searchEvents(_query: string | null, _startDate: string | null, _endDate: string | null, _limit: number): EventRow[];
     searchEventsAsync(query: string | null, startDate: string | null, endDate: string | null, limit: number): Promise<EventRow[]>;
     listEventsByDateRange(_startDate: number, _endDate: number, _limit: number): EventRow[];
     listEventsByDateRangeAsync(startDate: number, endDate: number, limit: number): Promise<EventRow[]>;
-    getEvent(_id: number): EventRow | undefined;
-    getEventAsync(id: number): Promise<EventRow | undefined>;
-    listEventInstancesAsync(eventId: number, startDate: string, endDate: string): Promise<EventRow[]>;
+    getEvent(_id: string): EventRow | undefined;
+    getEventAsync(id: string): Promise<EventRow | undefined>;
+    /** Resolves an event id (durable `ev_` token or raw Graph id) to its Graph id. */
+    getEventGraphId(id: string): string;
+    listEventInstancesAsync(eventId: string, startDate: string, endDate: string): Promise<EventRow[]>;
     listContacts(_limit: number, _offset: number): ContactRow[];
     listContactsAsync(limit: number, offset: number): Promise<ContactRow[]>;
     searchContacts(_query: string, _limit: number): ContactRow[];
     searchContactsAsync(query: string, limit: number): Promise<ContactRow[]>;
-    getContact(_id: number): ContactRow | undefined;
-    getContactAsync(id: number): Promise<ContactRow | undefined>;
+    getContact(_id: string): ContactRow | undefined;
+    getContactAsync(id: string): Promise<ContactRow | undefined>;
+    /** Resolves a contact id (durable `ct_` token or raw Graph id) to its Graph id. */
+    getContactGraphId(id: string): string;
     listContactFoldersAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         parentFolderId: string | null;
     }>>;
-    createContactFolderAsync(name: string): Promise<number>;
-    deleteContactFolderAsync(folderId: number): Promise<void>;
-    listContactsInFolderAsync(folderId: number, limit?: number): Promise<ContactRow[]>;
-    getContactPhotoAsync(contactId: number): Promise<{
+    createContactFolderAsync(name: string): Promise<string>;
+    deleteContactFolderAsync(folderId: string): Promise<void>;
+    listContactsInFolderAsync(folderId: string, limit?: number): Promise<ContactRow[]>;
+    getContactPhotoAsync(contactId: string): Promise<{
         filePath: string;
         contentType: string;
     }>;
-    setContactPhotoAsync(contactId: number, filePath: string): Promise<void>;
+    setContactPhotoAsync(contactId: string, filePath: string): Promise<void>;
     listTasks(_limit: number, _offset: number): TaskRow[];
     listTasksAsync(limit: number, offset: number): Promise<TaskRow[]>;
     listIncompleteTasks(_limit: number, _offset: number): TaskRow[];
     listIncompleteTasksAsync(limit: number, offset: number): Promise<TaskRow[]>;
     searchTasks(_query: string, _limit: number): TaskRow[];
     searchTasksAsync(query: string, limit: number): Promise<TaskRow[]>;
-    getTask(_id: number): TaskRow | undefined;
-    getTaskAsync(id: number): Promise<TaskRow | undefined>;
+    getTask(_id: string): TaskRow | undefined;
+    getTaskAsync(id: string): Promise<TaskRow | undefined>;
     listTaskListsAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         isDefault: boolean;
     }>>;
@@ -126,55 +179,52 @@ export declare class GraphRepository implements IRepository {
      */
     getGraphClient(): GraphClient;
     /**
-     * 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: number): string | undefined;
+    getGraphIdForDraft(draftId: string): string;
     /**
-     * Gets the Graph string ID from a numeric ID.
+     * Gets task info (Graph taskListId/taskId) from a durable `td_` token.
      */
-    getGraphId(type: 'folder' | 'message' | 'event' | 'contact', numericId: number): string | undefined;
-    /**
-     * Gets task info from a numeric ID.
-     */
-    getTaskInfo(numericId: number): {
+    getTaskInfo(id: string): {
         taskListId: string;
         taskId: string;
     } | undefined;
     /**
-     * Gets the Graph string ID for a task list from a numeric ID.
-     */
-    getTaskListGraphId(numericId: number): string | undefined;
-    moveEmail(_emailId: number, _destinationFolderId: number): void;
-    deleteEmail(_emailId: number): void;
-    archiveEmail(_emailId: number): void;
-    junkEmail(_emailId: number): void;
-    markEmailRead(_emailId: number, _isRead: boolean): void;
-    setEmailFlag(_emailId: number, _flagStatus: number): void;
-    setEmailCategories(_emailId: number, _categories: string[]): void;
-    setEmailImportance(_emailId: number, _importance: string): void;
-    createFolder(_name: string, _parentFolderId?: number): FolderRow;
-    deleteFolder(_folderId: number): void;
-    renameFolder(_folderId: number, _newName: string): void;
-    moveFolder(_folderId: number, _destinationParentId: number): void;
-    emptyFolder(_folderId: number): void;
-    moveEmailAsync(emailId: number, destinationFolderId: number): Promise<void>;
-    deleteEmailAsync(emailId: number): Promise<void>;
-    archiveEmailAsync(emailId: number): Promise<void>;
-    junkEmailAsync(emailId: number): Promise<void>;
-    markEmailReadAsync(emailId: number, isRead: boolean): Promise<void>;
-    setEmailFlagAsync(emailId: number, flagStatus: number): Promise<void>;
-    setEmailCategoriesAsync(emailId: number, categories: string[]): Promise<void>;
-    setEmailImportanceAsync(emailId: number, importance: string): Promise<void>;
-    createFolderAsync(name: string, parentFolderId?: number): Promise<FolderRow>;
-    deleteFolderAsync(folderId: number): Promise<void>;
-    renameFolderAsync(folderId: number, newName: string): Promise<void>;
-    moveFolderAsync(folderId: number, destinationParentId: number): Promise<void>;
-    emptyFolderAsync(folderId: number): Promise<void>;
+     * Gets the Graph string ID for a task list from a durable `tl_` token.
+     */
+    getTaskListGraphId(id: string): string | undefined;
+    moveEmail(_emailId: string, _destinationFolderId: string): void;
+    deleteEmail(_emailId: string): void;
+    archiveEmail(_emailId: string): void;
+    junkEmail(_emailId: string): void;
+    markEmailRead(_emailId: string, _isRead: boolean): void;
+    setEmailFlag(_emailId: string, _flagStatus: number): void;
+    setEmailCategories(_emailId: string, _categories: string[]): void;
+    setEmailImportance(_emailId: string, _importance: string): void;
+    createFolder(_name: string, _parentFolderId?: string): FolderRow;
+    deleteFolder(_folderId: string): void;
+    renameFolder(_folderId: string, _newName: string): void;
+    moveFolder(_folderId: string, _destinationParentId: string): void;
+    emptyFolder(_folderId: string): void;
+    moveEmailAsync(emailId: string, destinationFolderId: string): Promise<void>;
+    deleteEmailAsync(emailId: string): Promise<void>;
+    archiveEmailAsync(emailId: string): Promise<void>;
+    junkEmailAsync(emailId: string): Promise<void>;
+    markEmailReadAsync(emailId: string, isRead: boolean): Promise<void>;
+    setEmailFlagAsync(emailId: string, flagStatus: number): Promise<void>;
+    setEmailCategoriesAsync(emailId: string, categories: string[]): Promise<void>;
+    setEmailImportanceAsync(emailId: string, importance: string): Promise<void>;
+    createFolderAsync(name: string, parentFolderId?: string): Promise<FolderRow>;
+    deleteFolderAsync(folderId: string): Promise<void>;
+    renameFolderAsync(folderId: string, newName: string): Promise<void>;
+    moveFolderAsync(folderId: string, destinationParentId: string): Promise<void>;
+    emptyFolderAsync(folderId: string): Promise<void>;
     /**
      * 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.
      */
     createDraftAsync(params: {
         subject: string;
@@ -184,15 +234,15 @@ export declare class GraphRepository implements IRepository {
         cc?: string[];
         bcc?: string[];
     }): Promise<{
-        numericId: number;
+        token: string;
         graphId: string;
     }>;
     /**
      * 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.
      */
-    updateDraftAsync(draftId: number, updates: Record<string, unknown>): Promise<void>;
+    updateDraftAsync(draftId: string, updates: Record<string, unknown>): Promise<void>;
     /**
      * Lists draft messages.
      *
@@ -202,9 +252,9 @@ export declare class GraphRepository implements IRepository {
     /**
      * 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.
      */
-    sendDraftAsync(draftId: number): Promise<void>;
+    sendDraftAsync(draftId: string): Promise<void>;
     /**
      * Sends a new email directly without creating a draft first.
      *
@@ -221,39 +271,38 @@ export declare class GraphRepository implements IRepository {
     /**
      * 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.
      */
-    replyMessageAsync(messageId: number, comment: string, replyAll: boolean): Promise<void>;
+    replyMessageAsync(messageId: string, comment: string, replyAll: boolean): Promise<void>;
     /**
      * 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.
      */
-    forwardMessageAsync(messageId: number, toRecipients: string[], comment?: string): Promise<void>;
+    forwardMessageAsync(messageId: string, toRecipients: string[], comment?: string): Promise<void>;
     /**
      * 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.
      */
-    replyAsDraftAsync(messageId: number, replyAll?: boolean, comment?: string, bodyType?: string): Promise<{
-        numericId: number;
+    replyAsDraftAsync(messageId: string, replyAll?: boolean, comment?: string, bodyType?: string): Promise<{
+        token: string;
         graphId: string;
     }>;
     /**
      * 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.
      */
-    forwardAsDraftAsync(messageId: number, toRecipients?: string[], comment?: string, bodyType?: string): Promise<{
-        numericId: number;
+    forwardAsDraftAsync(messageId: string, toRecipients?: string[], comment?: string, bodyType?: string): Promise<{
+        token: string;
         graphId: string;
     }>;
     getScheduleAsync(params: {
@@ -272,14 +321,13 @@ export declare class GraphRepository implements IRepository {
     /**
      * 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.
      */
-    listAttachmentsAsync(emailId: number): Promise<Array<{
-        id: number;
+    listAttachmentsAsync(emailId: string): Promise<Array<{
+        id: string;
         name: string;
         size: number;
         contentType: string;
@@ -288,13 +336,13 @@ export declare class GraphRepository implements IRepository {
     /**
      * 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.
      */
-    downloadAttachmentAsync(attachmentId: number): Promise<{
+    downloadAttachmentAsync(attachmentId: string): Promise<{
         filePath: string;
         name: string;
         size: number;
@@ -334,17 +382,17 @@ export declare class GraphRepository implements IRepository {
                 numberOfOccurrences?: number;
             };
         };
-        calendarId?: number;
+        calendarId?: string;
         is_online_meeting?: boolean;
         online_meeting_provider?: string;
-    }): Promise<number>;
+    }): Promise<string>;
     /**
      * Updates an existing calendar event.
      *
      * Looks up the Graph string ID from idCache.events, then calls
      * client.updateEvent(). Throws if the event is not cached.
      */
-    updateEventAsync(eventId: number, updates: Record<string, unknown>): Promise<void>;
+    updateEventAsync(eventId: string, updates: Record<string, unknown>): Promise<void>;
     /**
      * Deletes a calendar event.
      *
@@ -352,14 +400,14 @@ export declare class GraphRepository implements IRepository {
      * client.deleteEvent(), and removes the entry from idCache.
      * Throws if the event is not cached.
      */
-    deleteEventAsync(eventId: number): Promise<void>;
+    deleteEventAsync(eventId: string): Promise<void>;
     /**
      * Responds to a calendar event invitation.
      *
      * Looks up the Graph string ID from idCache.events, then calls
      * client.respondToEvent(). Throws if the event is not cached.
      */
-    respondToEventAsync(eventId: number, response: 'accept' | 'decline' | 'tentative', sendResponse: boolean, comment?: string): Promise<void>;
+    respondToEventAsync(eventId: string, response: 'accept' | 'decline' | 'tentative', sendResponse: boolean, comment?: string): Promise<void>;
     /**
      * Creates a new contact.
      *
@@ -379,14 +427,14 @@ export declare class GraphRepository implements IRepository {
         state?: string;
         postal_code?: string;
         country?: string;
-    }): Promise<number>;
+    }): Promise<string>;
     /**
      * Updates an existing contact.
      *
      * Looks up the Graph string ID from idCache.contacts, then calls
      * client.updateContact(). Throws if the contact is not cached.
      */
-    updateContactAsync(contactId: number, updates: Record<string, unknown>): Promise<void>;
+    updateContactAsync(contactId: string, updates: Record<string, unknown>): Promise<void>;
     /**
      * Deletes a contact.
      *
@@ -394,17 +442,17 @@ export declare class GraphRepository implements IRepository {
      * client.deleteContact(), and removes the entry from idCache.
      * Throws if the contact is not cached.
      */
-    deleteContactAsync(contactId: number): Promise<void>;
+    deleteContactAsync(contactId: string): Promise<void>;
     /**
      * 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.
      */
     createTaskAsync(params: {
         title: string;
-        task_list_id: number;
+        task_list_id: string;
         body?: string;
         body_type?: 'text' | 'html';
         due_date?: string;
@@ -421,77 +469,67 @@ export declare class GraphRepository implements IRepository {
             occurrences?: number | undefined;
         } | undefined;
         categories?: string[];
-    }): Promise<number>;
+    }): Promise<string>;
     /**
      * Updates an existing task.
-     *
-     * Looks up the Graph task info from idCache.tasks, then calls
-     * client.updateTask(). Throws if the task is not cached.
      */
-    updateTaskAsync(taskId: number, updates: Record<string, unknown>): Promise<void>;
+    updateTaskAsync(taskId: string, updates: Record<string, unknown>): Promise<void>;
     /**
      * Marks a task as completed.
      *
      * Convenience method that calls updateTaskAsync with status: 'completed'
      * and the current time as completedDateTime.
      */
-    completeTaskAsync(taskId: number): Promise<void>;
+    completeTaskAsync(taskId: string): Promise<void>;
     /**
      * 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.
      */
-    deleteTaskAsync(taskId: number): Promise<void>;
+    deleteTaskAsync(taskId: string): Promise<void>;
     /**
      * Creates a new task list.
-     *
-     * Calls client.createTaskList(), caches the resulting ID in
-     * idCache.taskLists, and returns a numeric ID.
      */
-    createTaskListAsync(displayName: string): Promise<number>;
+    createTaskListAsync(displayName: string): Promise<string>;
     /**
      * Renames a task list.
      */
-    renameTaskListAsync(listId: number, name: string): Promise<void>;
+    renameTaskListAsync(listId: string, name: string): Promise<void>;
     /**
      * Deletes a task list.
      */
-    deleteTaskListAsync(listId: number): Promise<void>;
-    listChecklistItemsAsync(taskId: number): Promise<Array<{
-        id: number;
+    deleteTaskListAsync(listId: string): Promise<void>;
+    listChecklistItemsAsync(taskId: string): Promise<Array<{
+        id: string;
         displayName: string;
         isChecked: boolean;
         createdDateTime: string;
     }>>;
-    createChecklistItemAsync(taskId: number, displayName: string, isChecked?: boolean): Promise<number>;
-    updateChecklistItemAsync(checklistItemId: number, updates: {
+    createChecklistItemAsync(taskId: string, displayName: string, isChecked?: boolean): Promise<string>;
+    updateChecklistItemAsync(checklistItemId: string, updates: {
         displayName?: string;
         isChecked?: boolean;
     }): Promise<void>;
-    deleteChecklistItemAsync(checklistItemId: number): Promise<void>;
-    listLinkedResourcesAsync(taskId: number): Promise<Array<{
-        id: number;
+    deleteChecklistItemAsync(checklistItemId: string): Promise<void>;
+    listLinkedResourcesAsync(taskId: string): Promise<Array<{
+        id: string;
         webUrl: string;
         applicationName: string;
         displayName: string;
     }>>;
-    createLinkedResourceAsync(taskId: number, webUrl: string, applicationName: string, displayName?: string): Promise<number>;
-    deleteLinkedResourceAsync(linkedResourceId: number): Promise<void>;
-    listTaskAttachmentsAsync(taskId: number): Promise<Array<{
-        id: number;
+    createLinkedResourceAsync(taskId: string, webUrl: string, applicationName: string, displayName?: string): Promise<string>;
+    deleteLinkedResourceAsync(linkedResourceId: string): Promise<void>;
+    listTaskAttachmentsAsync(taskId: string): Promise<Array<{
+        id: string;
         name: string;
         size: number;
         contentType: string;
     }>>;
-    createTaskAttachmentAsync(taskId: number, name: string, contentBytes: string, contentType?: string): Promise<number>;
-    deleteTaskAttachmentAsync(taskAttachmentId: number): Promise<void>;
+    createTaskAttachmentAsync(taskId: string, name: string, contentBytes: string, contentType?: string): Promise<string>;
+    deleteTaskAttachmentAsync(taskAttachmentId: string): Promise<void>;
     /**
      * Lists all inbox mail rules.
      */
     listMailRulesAsync(): Promise<Array<{
-        id: number;
+        id: string;
         displayName: string;
         sequence: number;
         isEnabled: boolean;
@@ -501,11 +539,11 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a new inbox mail rule.
      */
-    createMailRuleAsync(rule: Record<string, unknown>): Promise<number>;
+    createMailRuleAsync(rule: Record<string, unknown>): Promise<string>;
     /**
      * Deletes an inbox mail rule.
      */
-    deleteMailRuleAsync(ruleId: number): Promise<void>;
+    deleteMailRuleAsync(ruleId: string): Promise<void>;
     /**
      * Gets the current automatic replies (OOF) settings.
      */
@@ -551,45 +589,45 @@ export declare class GraphRepository implements IRepository {
      * Lists all master categories.
      */
     listCategoriesAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         color: string;
     }>>;
     /**
      * Creates a new master category.
      */
-    createCategoryAsync(name: string, color: string): Promise<number>;
+    createCategoryAsync(name: string, color: string): Promise<string>;
     /**
      * Deletes a master category.
      */
-    deleteCategoryAsync(categoryId: number): Promise<void>;
+    deleteCategoryAsync(categoryId: string): Promise<void>;
     /**
      * Lists all focused inbox overrides.
      */
     listFocusedOverridesAsync(): Promise<Array<{
-        id: number;
+        id: string;
         senderAddress: string;
         classifyAs: string;
     }>>;
     /**
      * Creates a focused inbox override.
      */
-    createFocusedOverrideAsync(senderAddress: string, classifyAs: 'focused' | 'other'): Promise<number>;
+    createFocusedOverrideAsync(senderAddress: string, classifyAs: 'focused' | 'other'): Promise<string>;
     /**
      * Deletes a focused inbox override.
      */
-    deleteFocusedOverrideAsync(overrideId: number): Promise<void>;
+    deleteFocusedOverrideAsync(overrideId: string): Promise<void>;
     /**
      * Gets internet message headers for an email.
      */
-    getMessageHeadersAsync(emailId: number): Promise<Array<{
+    getMessageHeadersAsync(emailId: string): Promise<Array<{
         name: string;
         value: string;
     }>>;
     /**
      * Gets the MIME content of a message and saves it as an .eml file.
      */
-    getMessageMimeAsync(emailId: number): Promise<{
+    getMessageMimeAsync(emailId: string): Promise<{
         filePath: string;
     }>;
     /**
@@ -607,21 +645,24 @@ export declare class GraphRepository implements IRepository {
     }>>;
     /**
      * 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.
      */
     listCalendarGroupsAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         classId: string;
     }>>;
     /**
      * Creates a new calendar group.
      */
-    createCalendarGroupAsync(name: string): Promise<number>;
+    createCalendarGroupAsync(name: string): Promise<string>;
     /**
      * Lists all permissions for a calendar.
      */
-    listCalendarPermissionsAsync(calendarId: number): Promise<Array<{
-        id: number;
+    listCalendarPermissionsAsync(calendarId: string): Promise<Array<{
+        id: string;
         emailAddress: string;
         role: string;
         isRemovable: boolean;
@@ -630,11 +671,11 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a calendar permission (shares a calendar with someone).
      */
-    createCalendarPermissionAsync(calendarId: number, email: string, role: string): Promise<number>;
+    createCalendarPermissionAsync(calendarId: string, email: string, role: string): Promise<string>;
     /**
      * Deletes a calendar permission.
      */
-    deleteCalendarPermissionAsync(permissionId: number): Promise<void>;
+    deleteCalendarPermissionAsync(permissionId: string): Promise<void>;
     /**
      * Lists all room lists.
      */
@@ -653,24 +694,24 @@ export declare class GraphRepository implements IRepository {
      * Lists all joined teams with cached numeric IDs.
      */
     listTeamsAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         description: string;
     }>>;
     /**
      * Lists all channels in a team with cached numeric IDs.
      */
-    listChannelsAsync(teamId: number): Promise<Array<{
-        id: number;
+    listChannelsAsync(teamId: string): Promise<Array<{
+        id: string;
         name: string;
         description: string;
         membershipType: string;
     }>>;
     /**
-     * Gets a specific channel by cached numeric ID.
+     * Gets a specific channel by durable cn_ token.
      */
-    getChannelAsync(channelId: number): Promise<{
-        id: number;
+    getChannelAsync(channelId: string): Promise<{
+        id: string;
         name: string;
         description: string;
         membershipType: string;
@@ -679,22 +720,22 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a new channel in a team.
      */
-    createChannelAsync(teamId: number, name: string, description?: string): Promise<number>;
+    createChannelAsync(teamId: string, name: string, description?: string): Promise<string>;
     /**
      * Updates a channel's properties.
      */
-    updateChannelAsync(channelId: number, updates: {
+    updateChannelAsync(channelId: string, updates: {
         name?: string;
         description?: string;
     }): Promise<void>;
     /**
      * Deletes a channel.
      */
-    deleteChannelAsync(channelId: number): Promise<void>;
+    deleteChannelAsync(channelId: string): Promise<void>;
     /**
      * Lists members of a team.
      */
-    listTeamMembersAsync(teamId: number): Promise<Array<{
+    listTeamMembersAsync(teamId: string): Promise<Array<{
         id: string;
         displayName: string;
         email: string;
@@ -703,8 +744,8 @@ export declare class GraphRepository implements IRepository {
     /**
      * Lists recent messages in a channel.
      */
-    listChannelMessagesAsync(channelId: number, limit?: number): Promise<Array<{
-        id: number;
+    listChannelMessagesAsync(channelId: string, limit?: number): Promise<Array<{
+        id: string;
         senderName: string;
         senderEmail: string;
         bodyPreview: string;
@@ -715,15 +756,15 @@ export declare class GraphRepository implements IRepository {
     /**
      * Gets a specific channel message with its replies.
      */
-    getChannelMessageAsync(messageId: number): Promise<{
-        id: number;
+    getChannelMessageAsync(messageId: string): Promise<{
+        id: string;
         senderName: string;
         senderEmail: string;
         bodyContent: string;
         contentType: string;
         createdDateTime: string;
         replies: Array<{
-            id: number;
+            id: string;
             senderName: string;
             senderEmail: string;
             bodyContent: string;
@@ -734,27 +775,27 @@ export declare class GraphRepository implements IRepository {
     /**
      * Sends a new message to a channel.
      */
-    sendChannelMessageAsync(channelId: number, body: string, contentType?: string): Promise<number>;
+    sendChannelMessageAsync(channelId: string, body: string, contentType?: string): Promise<string>;
     /**
      * Replies to a channel message.
      */
-    replyToChannelMessageAsync(messageId: number, body: string, contentType?: string): Promise<number>;
+    replyToChannelMessageAsync(messageId: string, body: string, contentType?: string): Promise<string>;
     listChatsAsync(limit?: number): Promise<Array<{
-        id: number;
+        id: string;
         topic: string;
         chatType: string;
         lastMessagePreview: string;
         createdDateTime: string;
     }>>;
-    getChatAsync(chatId: number): Promise<{
-        id: number;
+    getChatAsync(chatId: string): Promise<{
+        id: string;
         topic: string;
         chatType: string;
         createdDateTime: string;
         webUrl: string;
     }>;
-    listChatMessagesAsync(chatId: number, limit?: number): Promise<Array<{
-        id: number;
+    listChatMessagesAsync(chatId: string, limit?: number): Promise<Array<{
+        id: string;
         senderName: string;
         senderEmail: string;
         bodyPreview: string;
@@ -762,35 +803,35 @@ export declare class GraphRepository implements IRepository {
         contentType: string;
         createdDateTime: string;
     }>>;
-    sendChatMessageAsync(chatId: number, body: string, contentType?: string): Promise<number>;
-    listMessageReactionsAsync(messageId: number, messageType: 'channel' | 'chat'): Promise<Array<{
+    sendChatMessageAsync(chatId: string, body: string, contentType?: string): Promise<string>;
+    listMessageReactionsAsync(messageId: string, messageType: 'channel' | 'chat'): Promise<Array<{
         reactionType: string;
         user: {
             displayName: string;
         };
         createdDateTime: string;
     }>>;
-    addMessageReactionAsync(messageId: number, messageType: 'channel' | 'chat', reactionType: string): Promise<void>;
-    removeMessageReactionAsync(messageId: number, messageType: 'channel' | 'chat', reactionType: string): Promise<void>;
-    listChatMembersAsync(chatId: number): Promise<Array<{
+    addMessageReactionAsync(messageId: string, messageType: 'channel' | 'chat', reactionType: string): Promise<void>;
+    removeMessageReactionAsync(messageId: string, messageType: 'channel' | 'chat', reactionType: string): Promise<void>;
+    listChatMembersAsync(chatId: string): Promise<Array<{
         displayName: string;
         email: string;
         roles: string[];
     }>>;
     /**
-     * Lists all plans the current user has.
+     * Lists all plans the current user has, minting durable pl_ tokens.
      */
     listPlansAsync(): Promise<Array<{
-        id: number;
+        id: string;
         title: string;
         owner: string;
         createdDateTime: string;
     }>>;
     /**
-     * Gets a specific plan by cached numeric ID.
+     * Gets a specific plan.
      */
-    getPlanAsync(planId: number): Promise<{
-        id: number;
+    getPlanAsync(planId: string): Promise<{
+        id: string;
         title: string;
         owner: string;
         createdDateTime: string;
@@ -799,43 +840,62 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a new plan.
      */
-    createPlanAsync(title: string, groupId: string): Promise<number>;
+    createPlanAsync(title: string, groupId: string): Promise<string>;
     /**
-     * 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).
      */
-    updatePlanAsync(planId: number, updates: {
+    updatePlanAsync(planId: string, updates: {
         title?: string;
     }): Promise<void>;
     /**
-     * Lists all buckets in a plan.
+     * Lists all buckets in a plan, minting durable pb_ tokens.
      */
-    listBucketsAsync(planId: number): Promise<Array<{
-        id: number;
+    listBucketsAsync(planId: string): Promise<Array<{
+        id: string;
         name: string;
-        planId: number;
+        planId: string;
         orderHint: string;
     }>>;
     /**
      * Creates a new bucket in a plan.
      */
-    createBucketAsync(planId: number, name: string): Promise<number>;
+    createBucketAsync(planId: string, name: string): Promise<string>;
     /**
-     * Updates a bucket (requires cached ETag).
+     * Updates a bucket (U5b-5: fetches a fresh etag immediately before the write).
      */
-    updateBucketAsync(bucketId: number, updates: {
+    updateBucketAsync(bucketId: string, updates: {
         name?: string;
     }): Promise<void>;
     /**
-     * Deletes a bucket (requires cached ETag).
+     * Deletes a bucket (U5b-5: fetches a fresh etag immediately before the write).
      */
-    deleteBucketAsync(bucketId: number): Promise<void>;
+    deleteBucketAsync(bucketId: string): Promise<void>;
+    /**
+     * Lists all tasks in a plan, minting durable pt_ tokens.
+     */
+    listPlannerTasksAsync(planId: string): Promise<Array<{
+        id: string;
+        title: string;
+        bucketId: string | null;
+        assignees: string[];
+        percentComplete: number;
+        priority: number;
+        startDateTime: string;
+        dueDateTime: string;
+        createdDateTime: string;
+    }>>;
     /**
-     * Lists all tasks in a plan.
+     * 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.
      */
-    listPlannerTasksAsync(planId: number): Promise<Array<{
-        id: number;
+    listMyPlannerTasksAsync(): Promise<Array<{
+        id: string;
         title: string;
-        bucketId: number | null;
+        planId: string;
+        bucketId: string | null;
         assignees: string[];
         percentComplete: number;
         priority: number;
@@ -844,12 +904,12 @@ export declare class GraphRepository implements IRepository {
         createdDateTime: string;
     }>>;
     /**
-     * Gets a specific planner task by cached numeric ID.
+     * Gets a specific planner task.
      */
-    getPlannerTaskAsync(taskId: number): Promise<{
-        id: number;
+    getPlannerTaskAsync(taskId: string): Promise<{
+        id: string;
         title: string;
-        bucketId: number | null;
+        bucketId: string | null;
         assignees: string[];
         percentComplete: number;
         priority: number;
@@ -863,13 +923,13 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a new planner task.
      */
-    createPlannerTaskAsync(planId: number, title: string, bucketId?: number, assignments?: Record<string, object>, priority?: number, startDate?: string, dueDate?: string): Promise<number>;
+    createPlannerTaskAsync(planId: string, title: string, bucketId?: string, assignments?: Record<string, object>, priority?: number, startDate?: string, dueDate?: string): Promise<string>;
     /**
-     * Updates a planner task (requires cached ETag).
+     * Updates a planner task (U5b-5: fetches a fresh etag immediately before the write).
      */
-    updatePlannerTaskAsync(taskId: number, updates: {
+    updatePlannerTaskAsync(taskId: string, updates: {
         title?: string;
-        bucketId?: number;
+        bucketId?: string;
         percentComplete?: number;
         priority?: number;
         startDate?: string;
@@ -877,14 +937,15 @@ export declare class GraphRepository implements IRepository {
         assignments?: Record<string, object>;
     }): Promise<void>;
     /**
-     * Deletes a planner task (requires cached ETag).
+     * Deletes a planner task (U5b-5: fetches a fresh etag immediately before the write).
      */
-    deletePlannerTaskAsync(taskId: number): Promise<void>;
+    deletePlannerTaskAsync(taskId: string): Promise<void>;
     /**
-     * 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.
      */
-    getPlannerTaskDetailsAsync(taskId: number): Promise<{
-        id: number;
+    getPlannerTaskDetailsAsync(taskId: string): Promise<{
+        id: string;
         description: string;
         checklist: Record<string, unknown>;
         references: Record<string, unknown>;
@@ -899,10 +960,10 @@ export declare class GraphRepository implements IRepository {
      * Partial failures are handled gracefully: tasks whose detail fetch failed will
      * have `details` set to `undefined`.
      */
-    listPlannerTasksWithDetailsAsync(planId: number): Promise<Array<{
-        id: number;
+    listPlannerTasksWithDetailsAsync(planId: string): Promise<Array<{
+        id: string;
         title: string;
-        bucketId: number | null;
+        bucketId: string | null;
         assignees: string[];
         percentComplete: number;
         priority: number;
@@ -917,9 +978,11 @@ export declare class GraphRepository implements IRepository {
         } | undefined;
     }>>;
     /**
-     * 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).
      */
-    updatePlannerTaskDetailsAsync(taskId: number, updates: {
+    updatePlannerTaskDetailsAsync(taskId: string, updates: {
         description?: string;
         checklist?: Record<string, object>;
         references?: Record<string, object>;
@@ -927,44 +990,44 @@ export declare class GraphRepository implements IRepository {
     /**
      * Assembles plan, buckets, and tasks into a unified visualization data object.
      */
-    getPlanVisualizationDataAsync(planId: number): Promise<PlanVisualizationData>;
+    getPlanVisualizationDataAsync(planId: string): Promise<PlanVisualizationData>;
     listOnlineMeetingsAsync(limit?: number): Promise<Array<{
-        id: number;
+        id: string;
         subject: string;
         startDateTime: string;
         endDateTime: string;
         joinUrl: string;
     }>>;
-    getOnlineMeetingAsync(meetingId: number): Promise<{
-        id: number;
+    getOnlineMeetingAsync(meetingId: string): Promise<{
+        id: string;
         subject: string;
         startDateTime: string;
         endDateTime: string;
         joinUrl: string;
         participants: unknown;
     } | undefined>;
-    listMeetingRecordingsAsync(meetingId: number): Promise<Array<{
-        id: number;
+    listMeetingRecordingsAsync(meetingId: string): Promise<Array<{
+        id: string;
         createdDateTime: string;
         recordingContentUrl: string;
     }>>;
-    downloadMeetingRecordingAsync(recordingId: number, outputPath: string): Promise<string>;
-    listMeetingTranscriptsAsync(meetingId: number): Promise<Array<{
-        id: number;
+    downloadMeetingRecordingAsync(recordingId: string, outputPath: string): Promise<string>;
+    listMeetingTranscriptsAsync(meetingId: string): Promise<Array<{
+        id: string;
         createdDateTime: string;
         contentUrl: string;
     }>>;
-    getMeetingTranscriptContentAsync(transcriptId: number, format?: string): Promise<string>;
-    listWorksheetsAsync(fileId: number): Promise<Record<string, unknown>[]>;
-    getWorksheetRangeAsync(fileId: number, worksheetName: string, range: string): Promise<Record<string, unknown>>;
-    getUsedRangeAsync(fileId: number, worksheetName: string): Promise<Record<string, unknown>>;
-    updateWorksheetRangeAsync(fileId: number, worksheetName: string, range: string, values: unknown[][]): Promise<Record<string, unknown>>;
-    getTableDataAsync(fileId: number, tableName: string): Promise<Record<string, unknown>[]>;
+    getMeetingTranscriptContentAsync(transcriptId: string, format?: string): Promise<string>;
+    listWorksheetsAsync(fileId: string): Promise<Record<string, unknown>[]>;
+    getWorksheetRangeAsync(fileId: string, worksheetName: string, range: string): Promise<Record<string, unknown>>;
+    getUsedRangeAsync(fileId: string, worksheetName: string): Promise<Record<string, unknown>>;
+    updateWorksheetRangeAsync(fileId: string, worksheetName: string, range: string, values: unknown[][]): Promise<Record<string, unknown>>;
+    getTableDataAsync(fileId: string, tableName: string): Promise<Record<string, unknown>[]>;
     /**
      * Lists files/folders in a drive folder (or root).
      */
-    listDriveItemsAsync(folderId?: number): Promise<Array<{
-        id: number;
+    listDriveItemsAsync(folderId?: string): Promise<Array<{
+        id: string;
         name: string;
         size: number;
         lastModified: string;
@@ -975,7 +1038,7 @@ export declare class GraphRepository implements IRepository {
      * Searches drive items by query.
      */
     searchDriveItemsAsync(query: string, limit?: number): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         size: number;
         lastModified: string;
@@ -985,8 +1048,8 @@ export declare class GraphRepository implements IRepository {
     /**
      * Gets metadata for a specific drive item.
      */
-    getDriveItemAsync(itemId: number): Promise<{
-        id: number;
+    getDriveItemAsync(itemId: string): Promise<{
+        id: string;
         name: string;
         size: number;
         lastModified: string;
@@ -998,19 +1061,19 @@ export declare class GraphRepository implements IRepository {
     /**
      * Downloads a drive item to a local file.
      */
-    downloadFileAsync(itemId: number, outputPath: string): Promise<{
+    downloadFileAsync(itemId: string, outputPath: string): Promise<{
         savedPath: string;
         size: number;
     }>;
     /**
      * Uploads a local file to OneDrive.
      */
-    uploadFileAsync(parentPath: string, fileName: string, localFilePath: string): Promise<number>;
+    uploadFileAsync(parentPath: string, fileName: string, localFilePath: string): Promise<string>;
     /**
      * Lists recently accessed drive items.
      */
     listRecentFilesAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         size: number;
         lastModified: string;
@@ -1021,7 +1084,7 @@ export declare class GraphRepository implements IRepository {
      * Lists drive items shared with the user.
      */
     listSharedWithMeAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         size: number;
         lastModified: string;
@@ -1031,7 +1094,7 @@ export declare class GraphRepository implements IRepository {
     /**
      * Creates a sharing link for a drive item.
      */
-    createSharingLinkAsync(itemId: number, type: string, scope: string): Promise<{
+    createSharingLinkAsync(itemId: string, type: string, scope: string): Promise<{
         webUrl: string;
         type: string;
         scope: string;
@@ -1039,21 +1102,21 @@ export declare class GraphRepository implements IRepository {
     /**
      * Deletes a drive item.
      */
-    deleteDriveItemAsync(itemId: number): Promise<void>;
+    deleteDriveItemAsync(itemId: string): Promise<void>;
     /**
-     * Lists followed SharePoint sites, caching IDs.
+     * Lists followed SharePoint sites, minting durable si_ tokens.
      */
     listSitesAsync(): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         webUrl: string;
         displayName: string;
     }>>;
     /**
-     * Searches SharePoint sites by keyword, caching IDs.
+     * Searches SharePoint sites by keyword, minting durable si_ tokens.
      */
     searchSitesAsync(query: string): Promise<Array<{
-        id: number;
+        id: string;
         name: string;
         webUrl: string;
         displayName: string;
@@ -1061,27 +1124,27 @@ export declare class GraphRepository implements IRepository {
     /**
      * Gets details for a specific SharePoint site.
      */
-    getSiteAsync(siteId: number): Promise<{
-        id: number;
+    getSiteAsync(siteId: string): Promise<{
+        id: string;
         name: string;
         webUrl: string;
         displayName: string;
         description: string;
     }>;
     /**
-     * Lists document libraries for a SharePoint site, caching IDs.
+     * Lists document libraries for a SharePoint site, minting durable dl_ tokens.
      */
-    listDocumentLibrariesAsync(siteId: number): Promise<Array<{
-        id: number;
+    listDocumentLibrariesAsync(siteId: string): Promise<Array<{
+        id: string;
         name: string;
         webUrl: string;
         driveType: string;
     }>>;
     /**
-     * Lists items in a document library or folder, caching IDs.
+     * Lists items in a document library or folder, minting durable li_ tokens.
      */
-    listLibraryItemsAsync(libraryId: number, folderId?: number): Promise<Array<{
-        id: number;
+    listLibraryItemsAsync(libraryId: string, folderId?: string): Promise<Array<{
+        id: string;
         name: string;
         size: number;
         webUrl: string;
@@ -1091,14 +1154,84 @@ export declare class GraphRepository implements IRepository {
     /**
      * Downloads a file from a document library to the specified path.
      */
-    downloadLibraryFileAsync(itemId: number, outputPath: string): Promise<string>;
+    downloadLibraryFileAsync(itemId: string, outputPath: string): Promise<string>;
+    /**
+     * Resolves a folder id (durable `fd_` token or raw Graph id) to its Graph id.
+     */
+    getFolderGraphId(folderId: string): string;
+    /**
+     * Lists the SharePoint lists in a site, minting durable sl_ tokens. Each list
+     * token carries the {siteId, listId} tuple its Graph URL needs.
+     */
+    listSharePointListsAsync(siteId: string): Promise<Array<{
+        id: string;
+        name: string;
+        displayName: string;
+        description: string;
+        webUrl: string;
+    }>>;
+    /**
+     * Gets a specific SharePoint list, resolving the sl_ token to its tuple.
+     */
+    getSharePointListAsync(listId: string): Promise<{
+        id: string;
+        name: string;
+        displayName: string;
+        description: string;
+        webUrl: string;
+    }>;
+    /**
+     * Creates a SharePoint list in a site, minting a durable sl_ token.
+     */
+    createSharePointListAsync(siteId: string, displayName: string, description?: string): Promise<string>;
+    /**
+     * Lists the column definitions for a SharePoint list. Columns are addressed by
+     * name in item field values, so they carry no durable token.
+     */
+    listSharePointListColumnsAsync(listId: string): Promise<Array<{
+        id: string;
+        name: string;
+        displayName: string;
+        columnType: string;
+        required: boolean;
+        readOnly: boolean;
+    }>>;
+    /**
+     * Lists the items in a SharePoint list, minting durable sn_ tokens that carry
+     * the {siteId, listId, itemId} tuple.
+     */
+    listSharePointListItemsAsync(listId: string, limit?: number): Promise<Array<{
+        id: string;
+        fields: Record<string, unknown>;
+        webUrl: string;
+        createdDateTime: string;
+        lastModifiedDateTime: string;
+    }>>;
+    /**
+     * Gets a specific SharePoint list item, resolving the sn_ token to its tuple.
+     */
+    getSharePointListItemAsync(itemId: string): Promise<{
+        id: string;
+        fields: Record<string, unknown>;
+        webUrl: string;
+        createdDateTime: string;
+        lastModifiedDateTime: string;
+    }>;
+    /**
+     * Creates an item in a SharePoint list, minting a durable sn_ token.
+     */
+    createSharePointListItemAsync(listId: string, fields: Record<string, unknown>): Promise<string>;
+    /**
+     * Updates the field values of a SharePoint list item.
+     */
+    updateSharePointListItemAsync(itemId: string, fields: Record<string, unknown>): Promise<void>;
     /**
-     * Gets the Graph string ID for a folder from the cache.
+     * Deletes an item from a SharePoint list.
      */
-    getFolderGraphId(folderId: number): string | undefined;
+    deleteSharePointListItemAsync(itemId: string): Promise<void>;
 }
 /**
  * Creates a Microsoft Graph API repository.
  */
-export declare function createGraphRepository(deviceCodeCallback?: DeviceCodeCallback): GraphRepository;
+export declare function createGraphRepository(deviceCodeCallback?: DeviceCodeCallback, store?: StateStore, accountId?: () => string): GraphRepository;
 //# sourceMappingURL=repository.d.ts.map