@kubun/connector-google-mail 0.17.0 → 0.17.2

package/lib/actions.d.ts

@@ -6,5 +6,6 @@ export type GoogleMailActionHandlerConfig = {
     };
     fetch?: typeof globalThis.fetch;
     writeAttachment?: WriteAttachment;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleMailActionHandler(config: GoogleMailActionHandlerConfig): ActionHandler;

package/lib/actions.js

@@ -1,44 +1,89 @@
 import { createDraft, createLabel, importMessageAttachment, modifyLabels, sendMessage, updateLabel } from './api.js';
+import { GoogleMailError } from './errors.js';
+// Gmail takes a label color only as the textColor/backgroundColor pair, so a
+// write that changes one of them carries the other from the target document.
+// With no companion to carry (absent or empty), the color cannot be written at all: the write is
+// rejected before any request, rather than sent without the change.
+function withColorPair(params, existing) {
+    const changesOne = 'textColor' in params !== 'backgroundColor' in params;
+    if (!changesOne) return params;
+    const missing = 'textColor' in params ? 'backgroundColor' : 'textColor';
+    const companion = existing?.[missing];
+    if (typeof companion !== 'string' || companion === '') {
+        throw new GoogleMailError(`Google Mail: a label color needs both textColor and backgroundColor, and the label has no ${missing} to keep`, {
+            kind: 'rejected'
+        });
+    }
+    return {
+        ...params,
+        [missing]: companion
+    };
+}
 export function createGoogleMailActionHandler(config) {
+    const mintActionFetchHLC = config.mintFetchHLC;
     return {
         async create (model, params) {
             if (model === 'GoogleMailLabel') {
-                return createLabel({
+                const record = await createLabel({
                     accessToken: config.credential.accessToken,
                     params,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
             if (params.draft === true) {
-                return createDraft({
+                const record = await createDraft({
                     accessToken: config.credential.accessToken,
                     params,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
-            return sendMessage({
+            const record = await sendMessage({
                 accessToken: config.credential.accessToken,
                 params,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         },
         async update (model, sourceID, params, existing) {
             if (model === 'GoogleMailLabel') {
-                return updateLabel({
+                const record = await updateLabel({
                     accessToken: config.credential.accessToken,
                     labelID: sourceID,
-                    params,
+                    params: withColorPair(params, existing),
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
             // On GoogleMailMessage, a providerRef selects an attachment to import: its
             // bytes are downloaded and written to the blob store, filling that entry's
-            // blob field. Without it, the update modifies labels as before.
+            // blob field. `attachments` is outside GoogleMailMessage's providerMergePolicy
+            // group (model.ts), so this write only ever touches a local-annotation
+            // field — never the provider content group — and says so (`localChange`):
+            // it is projected as an outside-group change, not a fetched SET. Without
+            // it, the update modifies labels as before.
             if (typeof params.providerRef === 'string') {
                 if (config.writeAttachment == null) {
                     throw new Error('Google Mail: cannot import attachment, no blob plugin installed');
                 }
-                return importMessageAttachment({
+                const record = await importMessageAttachment({
                     accessToken: config.credential.accessToken,
                     messageID: sourceID,
                     providerRef: params.providerRef,
@@ -46,14 +91,25 @@ export function createGoogleMailActionHandler(config) {
                     writeAttachment: config.writeAttachment,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC(),
+                    localChange: true
+                };
             }
-            return modifyLabels({
+            const record = await modifyLabels({
                 accessToken: config.credential.accessToken,
                 messageID: sourceID,
                 addLabelIds: params.addLabelIds,
                 removeLabelIds: params.removeLabelIds,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         }
     };
 }

package/lib/api.d.ts

@@ -1,4 +1,4 @@
-import type { EntityRecord, WriteAttachment } from '@kubun/connector';
+import { type EntityRecord, type WriteAttachment } from '@kubun/connector';
 export declare const MAIL_BASE_URL = "https://gmail.googleapis.com/gmail/v1";
 export declare function parseGoogleError(response: Response): Promise<string>;
 export declare function decodeBase64Url(data: string): string;
@@ -11,6 +11,12 @@ export declare function buildMessagesListURL(params: {
 export declare function buildMessageGetURL(params: {
     messageID: string;
 }): string;
+export declare function buildThreadGetURL(params: {
+    threadID: string;
+}): string;
+export declare function buildLabelGetURL(params: {
+    labelID: string;
+}): string;
 export declare function buildAttachmentGetURL(params: {
     messageID: string;
     attachmentID: string;
@@ -85,6 +91,11 @@ export type GmailMessagesListResponse = {
     nextPageToken?: string;
     resultSizeEstimate?: number;
 };
+export type GmailThreadResource = {
+    id: string;
+    historyId?: string;
+    messages?: Array<GmailMessageResource>;
+};
 export declare function getHeader(headers: Array<{
     name: string;
     value: string;
@@ -92,6 +103,24 @@ export declare function getHeader(headers: Array<{
 export declare function extractEmail(headerValue: string): string;
 export declare function extractEmails(headerValue: string | undefined): Array<string>;
 export declare function mapMessageToEntity(message: GmailMessageResource): EntityRecord;
+export declare function getMessage(config: {
+    accessToken: string;
+    messageID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailMessageResource>;
+export declare function getThread(config: {
+    accessToken: string;
+    threadID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailThreadResource>;
+export declare function getLabel(config: {
+    accessToken: string;
+    labelID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailLabelResource>;
 export declare function importMessageAttachment(config: {
     accessToken: string;
     messageID: string;

package/lib/api.js

@@ -1,3 +1,4 @@
+import { connectorHTTPError, markWriteSent } from '@kubun/connector';
 import { b64uFromUTF, b64uToUTF, fromB64U } from '@sozai/codec';
 export const MAIL_BASE_URL = 'https://gmail.googleapis.com/gmail/v1';
 export async function parseGoogleError(response) {
@@ -8,6 +9,15 @@ export async function parseGoogleError(response) {
         return `${response.status} ${response.statusText}`;
     }
 }
+// Build the error thrown by a Gmail call, tagged with the HTTP status and its
+// outcome classification (`kind`, see `classifyHTTPStatus`) — a definite
+// rejection dead-letters a write instead of re-driving it. The status is also
+// the seam fetchEntity/reconcile (provider.ts) use to turn a 404 into a
+// `present: false` result (deletion detected) instead of a throw.
+async function googleMailAPIError(response) {
+    const detail = await parseGoogleError(response);
+    return connectorHTTPError(`Google Mail API error: ${detail}`, response.status);
+}
 export function decodeBase64Url(data) {
     return b64uToUTF(data);
 }
@@ -28,6 +38,14 @@ export function buildMessageGetURL(params) {
     url.searchParams.set('format', 'full');
     return url.toString();
 }
+export function buildThreadGetURL(params) {
+    const url = new URL(`${MAIL_BASE_URL}/users/me/threads/${encodeURIComponent(params.threadID)}`);
+    url.searchParams.set('format', 'full');
+    return url.toString();
+}
+export function buildLabelGetURL(params) {
+    return `${MAIL_BASE_URL}/users/me/labels/${encodeURIComponent(params.labelID)}`;
+}
 export function buildAttachmentGetURL(params) {
     return `${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(params.messageID)}/attachments/${encodeURIComponent(params.attachmentID)}`;
 }
@@ -128,6 +146,54 @@ export function mapMessageToEntity(message) {
         }
     };
 }
+// Targeted single-message fetch (anti-entropy repair verification / write-back
+// recovery's fetchEntity+reconcile). A 404 here is the deletion signal — see
+// googleMailAPIError's doc.
+export async function getMessage(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const response = await fetchFn(buildMessageGetURL({
+        messageID: config.messageID
+    }), {
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`
+        },
+        signal: config.signal
+    });
+    if (!response.ok) throw await googleMailAPIError(response);
+    return await response.json();
+}
+// Targeted single-thread fetch — a real threads.get(format=full) read, mapped
+// from its own resource (id + constituent messages), never synthesized from a
+// bulk message listing's locally-scanned subject.
+export async function getThread(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const response = await fetchFn(buildThreadGetURL({
+        threadID: config.threadID
+    }), {
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`
+        },
+        signal: config.signal
+    });
+    if (!response.ok) throw await googleMailAPIError(response);
+    return await response.json();
+}
+// Targeted single-label fetch. Unlike labels.list (buildLabelsListURL, used by
+// the bulk labelBatch), a direct labels.get returns the full resource
+// including `color` — the list endpoint omits it.
+export async function getLabel(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const response = await fetchFn(buildLabelGetURL({
+        labelID: config.labelID
+    }), {
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`
+        },
+        signal: config.signal
+    });
+    if (!response.ok) throw await googleMailAPIError(response);
+    return await response.json();
+}
 function streamOfBytes(bytes) {
     return new ReadableStream({
         start (controller) {
@@ -137,9 +203,12 @@ function streamOfBytes(bytes) {
     });
 }
 // Download one attachment's bytes from Gmail, write them to the blob store, and
-// return the message entity with that attachment's `blob` set. Other attachments'
-// already-imported blobs are preserved from `existing`. Gmail returns the whole
-// attachment as a single base64url `data` field, so the bytes are buffered here.
+// return the message identity with just its `attachments`, that attachment's
+// `blob` set. Other attachments' already-imported blobs are preserved from
+// `existing`, and no other field of `existing` is carried: `attachments` is a
+// local annotation, and the local copy of the provider fields must never be
+// re-issued as if freshly read. Gmail returns the whole attachment as a single
+// base64url `data` field, so the bytes are buffered here.
 export async function importMessageAttachment(config) {
     const attachments = config.existing?.attachments ?? [];
     const target = attachments.find((a)=>a.providerRef === config.providerRef);
@@ -155,7 +224,7 @@ export async function importMessageAttachment(config) {
             Authorization: `Bearer ${config.accessToken}`
         }
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    if (!response.ok) throw await googleMailAPIError(response);
     const body = await response.json();
     if (body.data == null) throw new Error('Google Mail: attachment response has no data');
     const bytes = decodeBase64UrlBytes(body.data);
@@ -167,7 +236,6 @@ export async function importMessageAttachment(config) {
             blob: attachmentID
         } : a);
     return {
-        ...config.existing ?? {},
         sourceService: 'google-mail',
         sourceID: config.messageID,
         attachments: updated
@@ -228,17 +296,24 @@ function requireString(params, key) {
 // Gmail's write endpoints (messages.send, drafts.create, messages.modify) return only
 // { id, threadId, labelIds } -- no payload/headers/body. Re-fetch the full message so the
 // mapped entity carries real sender/body/subject/etc. instead of empty placeholders.
-async function fetchAndMapMessage(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
-    const response = await fetchFn(buildMessageGetURL({
-        messageID: config.messageID
-    }), {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        }
-    });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    return mapMessageToEntity(await response.json());
+// Everything here runs after the write went out, so any failure is marked sent: the
+// write may have landed, whatever the read-back did.
+async function readBackWrittenMessage(config) {
+    try {
+        const messageID = config.messageIDOf(await config.written.json());
+        const fetchFn = config.fetch ?? globalThis.fetch;
+        const response = await fetchFn(buildMessageGetURL({
+            messageID
+        }), {
+            headers: {
+                Authorization: `Bearer ${config.accessToken}`
+            }
+        });
+        if (!response.ok) throw await googleMailAPIError(response);
+        return mapMessageToEntity(await response.json());
+    } catch (err) {
+        throw markWriteSent(err);
+    }
 }
 export async function sendMessage(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
@@ -259,11 +334,11 @@ export async function sendMessage(config) {
             raw
         })
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const sent = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) throw await googleMailAPIError(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: sent.id,
+        written: response,
+        messageIDOf: (sent)=>sent.id,
         fetch: config.fetch
     });
 }
@@ -288,11 +363,11 @@ export async function createDraft(config) {
             }
         })
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const draft = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) throw await googleMailAPIError(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: draft.message.id,
+        written: response,
+        messageIDOf: (draft)=>draft.message.id,
         fetch: config.fetch
     });
 }
@@ -310,11 +385,11 @@ export async function modifyLabels(config) {
             removeLabelIds: config.removeLabelIds ?? []
         })
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const modified = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) throw await googleMailAPIError(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: modified.id,
+        written: response,
+        messageIDOf: (modified)=>modified.id,
         fetch: config.fetch
     });
 }
@@ -350,7 +425,7 @@ export async function createLabel(config) {
         },
         body: JSON.stringify(body)
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    if (!response.ok) throw await googleMailAPIError(response);
     return mapLabelToEntity(await response.json());
 }
 export async function updateLabel(config) {
@@ -364,6 +439,6 @@ export async function updateLabel(config) {
         },
         body: JSON.stringify(buildLabelBody(config.params))
     });
-    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    if (!response.ok) throw await googleMailAPIError(response);
     return mapLabelToEntity(await response.json());
 }

package/lib/connector.js

@@ -1,4 +1,5 @@
 import { createGoogleMailActionHandler } from './actions.js';
+import { mergeMailLocalAnnotations } from './local-annotations.js';
 import { googleMailClusters } from './model.js';
 import { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';
 export function createGoogleMailConnector(options) {
@@ -9,14 +10,19 @@ export function createGoogleMailConnector(options) {
         syncStrategies: [
             'on-demand'
         ],
+        // Two `create`/`update` verbs, each split per entityModel rather than one
+        // action spanning multiple models — schema.ts's dynamic mutation generator
+        // (connectorCreate<Model>/connectorUpdate<Model>) and the write-back
+        // recovery driver (writeback/workflow.ts) both select an action by
+        // (name, entityModel), so each model gets its own recoveryClass.
         actions: [
             {
                 name: 'create',
-                description: 'On GoogleMailMessage: send a message (or create a draft when draft is true). On GoogleMailLabel: create a label.',
+                description: 'Send a message (or create a draft when draft is true).',
+                entityModel: 'GoogleMailMessage',
                 input: {
                     type: 'object',
                     properties: {
-                        // GoogleMailMessage
                         to: {
                             type: 'array',
                             items: {
@@ -43,8 +49,23 @@ export function createGoogleMailConnector(options) {
                         },
                         draft: {
                             type: 'boolean'
-                        },
-                        // GoogleMailLabel
+                        }
+                    }
+                },
+                requiresCredential: true,
+                // Gmail assigns the message id — there is no caller-supplied
+                // deterministic id to key a safe reissue on, and a blind resend after
+                // an outcome-unknown failure could duplicate-send to the recipient.
+                // Recovery must reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
+            },
+            {
+                name: 'create',
+                description: 'Create a label.',
+                entityModel: 'GoogleMailLabel',
+                input: {
+                    type: 'object',
+                    properties: {
                         name: {
                             type: 'string'
                         },
@@ -62,15 +83,19 @@ export function createGoogleMailConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // Same reasoning as the google-contacts connector's create: Google
+                // assigns the label id, so a blind retry could create a duplicate
+                // label. Recovery must reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
             },
             {
                 name: 'update',
-                description: 'On GoogleMailMessage: add/remove labels, or import an attachment when providerRef is set. On GoogleMailLabel: rename or restyle the label.',
+                description: 'Add/remove labels on a message, or import an attachment when providerRef is set.',
+                entityModel: 'GoogleMailMessage',
                 input: {
                     type: 'object',
                     properties: {
-                        // GoogleMailMessage
                         addLabelIds: {
                             type: 'array',
                             items: {
@@ -86,8 +111,23 @@ export function createGoogleMailConnector(options) {
                         // Import the attachment identified by this Gmail part id into the blob store.
                         providerRef: {
                             type: 'string'
-                        },
-                        // GoogleMailLabel
+                        }
+                    }
+                },
+                requiresCredential: true,
+                // Both effects are idempotent under exact-input replay: re-applying the
+                // same add/remove label set is a no-op on the already-applied labels,
+                // and re-downloading + re-writing the same attachment bytes to the
+                // content-addressed blob store is a no-op re-write. Safe to reissue.
+                recoveryClass: 'reissue-safe'
+            },
+            {
+                name: 'update',
+                description: 'Rename or restyle a label.',
+                entityModel: 'GoogleMailLabel',
+                input: {
+                    type: 'object',
+                    properties: {
                         name: {
                             type: 'string'
                         },
@@ -105,14 +145,27 @@ export function createGoogleMailConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // Same blind-absolute-overwrite reasoning as the google-calendar/
+                // google-contacts connectors' update: a reissue of absolute field
+                // values could silently clobber an intervening edit, so recovery must
+                // reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
             }
         ],
+        mergeLocalAnnotations: mergeMailLocalAnnotations,
+        // A mail write lands in the account's own mailbox: its target is the
+        // account (`users/me`), already pinned by the operation's account key.
+        resolveActionTarget: async ({ input })=>({
+                target: 'users/me',
+                input
+            }),
         actionHandler: (config)=>{
             return createGoogleMailActionHandler({
                 credential: config.credential,
                 fetch: options?.fetch,
-                writeAttachment: config.writeAttachment
+                writeAttachment: config.writeAttachment,
+                mintFetchHLC: config.mintFetchHLC
             });
         },
         auth: {
@@ -131,7 +184,8 @@ export function createGoogleMailConnector(options) {
                 credential: config.credential,
                 boundary: config.boundary,
                 fetch: options?.fetch,
-                query: options?.query ?? DEFAULT_QUERY
+                query: options?.query ?? DEFAULT_QUERY,
+                mintFetchHLC: config.mintFetchHLC
             });
         }
     };

package/lib/errors.d.ts

@@ -0,0 +1,5 @@
+import { ConnectorError, type ConnectorErrorOptions } from '@kubun/connector';
+/** A Google Mail connector failure, classified the way `ConnectorError` is. */
+export declare class GoogleMailError extends ConnectorError {
+    constructor(message: string, options?: ConnectorErrorOptions);
+}

package/lib/errors.js

@@ -0,0 +1,7 @@
+import { ConnectorError } from '@kubun/connector';
+/** A Google Mail connector failure, classified the way `ConnectorError` is. */ export class GoogleMailError extends ConnectorError {
+    constructor(message, options = {}){
+        super(message, options);
+        this.name = 'GoogleMailError';
+    }
+}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { createGoogleMailActionHandler, type GoogleMailActionHandlerConfig } from './actions.js';
-export { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, type GmailHistoryListResponse, type GmailHistoryRecord, type GmailLabelResource, type GmailLabelsListResponse, type GmailMessagePart, type GmailMessageResource, type GmailMessagesListResponse, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel, } from './api.js';
+export { buildHistoryListURL, buildLabelGetURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, buildThreadGetURL, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, type GmailHistoryListResponse, type GmailHistoryRecord, type GmailLabelResource, type GmailLabelsListResponse, type GmailMessagePart, type GmailMessageResource, type GmailMessagesListResponse, type GmailThreadResource, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel, } from './api.js';
 export { type CreateGoogleMailConnectorOptions, createGoogleMailConnector } from './connector.js';
+export { GoogleMailError } from './errors.js';
+export { mergeMailLocalAnnotations } from './local-annotations.js';
 export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition, } from './model.js';
 export { createGoogleMailProvider, DEFAULT_QUERY, type GoogleMailProviderConfig, type MailCheckpoint, } from './provider.js';

package/lib/index.js

@@ -1,5 +1,7 @@
 export { createGoogleMailActionHandler } from './actions.js';
-export { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel } from './api.js';
+export { buildHistoryListURL, buildLabelGetURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, buildThreadGetURL, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel } from './api.js';
 export { createGoogleMailConnector } from './connector.js';
+export { GoogleMailError } from './errors.js';
+export { mergeMailLocalAnnotations } from './local-annotations.js';
 export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition } from './model.js';
 export { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';

package/lib/local-annotations.d.ts

@@ -0,0 +1,8 @@
+import type { LocalAnnotationMerger } from '@kubun/connector';
+/**
+ * The Gmail local-annotation merger (see `LocalAnnotationMerger`). Gmail
+ * authors a message's attachment metadata but never the `blob` an import
+ * adds locally: each incoming attachment without a blob keeps the one its
+ * existing counterpart holds. Nothing else is carried over.
+ */
+export declare const mergeMailLocalAnnotations: LocalAnnotationMerger;

package/lib/local-annotations.js

@@ -0,0 +1,39 @@
+import { googleMailMessageDefinition } from './model.js';
+function sameContent(a, b) {
+    return a.filename === b.filename && a.mimeType === b.mimeType && a.size === b.size;
+}
+// The existing attachment an incoming one is: the one with its attachment id,
+// or — Gmail may re-issue attachment ids — the only one of the message with
+// its filename, type and size when that is unambiguous on both sides. A
+// message's attachments never change, so that pairing is the same content.
+function counterpart(incoming, incomingAll, existingAll) {
+    const byRef = existingAll.find((a)=>a.providerRef === incoming.providerRef);
+    if (byRef != null) return byRef;
+    const matches = existingAll.filter((a)=>sameContent(a, incoming));
+    const twins = incomingAll.filter((a)=>sameContent(a, incoming));
+    return matches.length === 1 && twins.length === 1 ? matches[0] : undefined;
+}
+/**
+ * The Gmail local-annotation merger (see `LocalAnnotationMerger`). Gmail
+ * authors a message's attachment metadata but never the `blob` an import
+ * adds locally: each incoming attachment without a blob keeps the one its
+ * existing counterpart holds. Nothing else is carried over.
+ */ export const mergeMailLocalAnnotations = ({ model, incoming, existing })=>{
+    if (model !== googleMailMessageDefinition.name) return incoming;
+    if (!Array.isArray(incoming.attachments) || !Array.isArray(existing.attachments)) return incoming;
+    const incomingAll = incoming.attachments;
+    const existingAll = existing.attachments;
+    if (!existingAll.some((a)=>typeof a.blob === 'string')) return incoming;
+    const attachments = incomingAll.map((attachment)=>{
+        if (attachment.blob != null) return attachment;
+        const blob = counterpart(attachment, incomingAll, existingAll)?.blob;
+        return typeof blob === 'string' ? {
+            ...attachment,
+            blob
+        } : attachment;
+    });
+    return {
+        ...incoming,
+        attachments
+    };
+};

package/lib/model.d.ts

@@ -46,6 +46,9 @@ export declare const googleMailThreadDefinition: {
         };
     };
     readonly fieldsMeta: {};
+    readonly providerMergePolicy: {
+        readonly group: ["title", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailMessageDefinition: {
     readonly name: "GoogleMailMessage";
@@ -179,6 +182,9 @@ export declare const googleMailMessageDefinition: {
             readonly model: "#0";
         };
     };
+    readonly providerMergePolicy: {
+        readonly group: ["body", "sender", "subject", "snippet", "to", "cc", "labels", "sentAt", "unread", "threadID", "thread", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailLabelDefinition: {
     readonly name: "GoogleMailLabel";
@@ -249,5 +255,8 @@ export declare const googleMailLabelDefinition: {
         };
     };
     readonly fieldsMeta: {};
+    readonly providerMergePolicy: {
+        readonly group: ["name", "type", "messageListVisibility", "labelListVisibility", "textColor", "backgroundColor", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailClusters: import("@kubun/protocol").ClustersRecord;

package/lib/model.js

@@ -55,7 +55,17 @@ export const googleMailThreadDefinition = {
             ...commonDefinitions
         }
     },
-    fieldsMeta: {}
+    fieldsMeta: {},
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'title',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
+    }
 };
 export const googleMailMessageDefinition = {
     name: 'GoogleMailMessage',
@@ -185,6 +195,28 @@ export const googleMailMessageDefinition = {
             type: 'document',
             model: '#0'
         }
+    },
+    // lastSyncedAt is device-local sync bookkeeping; attachments carries the
+    // locally-materialized `blob` annotation (absent until an explicit import
+    // fills it), so the whole field stays outside the group rather than
+    // splitting a single top-level field between provider and device content.
+    providerMergePolicy: {
+        group: [
+            'body',
+            'sender',
+            'subject',
+            'snippet',
+            'to',
+            'cc',
+            'labels',
+            'sentAt',
+            'unread',
+            'threadID',
+            'thread',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
     }
 };
 export const googleMailLabelDefinition = {
@@ -245,7 +277,22 @@ export const googleMailLabelDefinition = {
             ...commonDefinitions
         }
     },
-    fieldsMeta: {}
+    fieldsMeta: {},
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'name',
+            'type',
+            'messageListVisibility',
+            'labelListVisibility',
+            'textColor',
+            'backgroundColor',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
+    }
 };
 const builder = new GraphBuilder({
     externalClusters: {

package/lib/provider.d.ts

@@ -3,11 +3,13 @@ import type { Credential } from '@kubun/credential-types';
 export declare const DEFAULT_QUERY = "in:inbox";
 export type MailCheckpoint = {
     historyId: string;
+    windowStart?: number;
 };
 export type GoogleMailProviderConfig = {
     credential: Credential;
     boundary?: SyncBoundary;
     fetch?: typeof globalThis.fetch;
     query?: string;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleMailProvider(config: GoogleMailProviderConfig): ServerDataProvider;

package/lib/provider.js

@@ -1,5 +1,5 @@
 import { resolveModelID } from '@kubun/connector';
-import { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, parseGoogleError } from './api.js';
+import { buildHistoryListURL, buildLabelsListURL, buildMessagesListURL, buildProfileURL, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, parseGoogleError } from './api.js';
 import { googleMailClusters } from './model.js';
 export const DEFAULT_QUERY = 'in:inbox';
 const THREAD_MODEL_ID = resolveModelID(googleMailClusters, 'GoogleMailThread');
@@ -17,12 +17,22 @@ async function fetchJSON(url, credential, fetchFn, signal) {
     }
     return await response.json();
 }
-function applyMaxAge(query, boundary) {
-    if (boundary?.maxAge == null) return query;
+/**
+ * The absolute lower bound (epoch seconds) for a full message listing: a window
+ * already frozen in the checkpoint, else `now − maxAge` computed once. Null when
+ * the boundary carries no `maxAge` (no floor).
+ */ function windowStartSeconds(boundary, frozen) {
+    if (frozen != null) return frozen;
+    if (boundary?.maxAge == null) return null;
     const match = /^P(\d+)D$/i.exec(boundary.maxAge);
-    if (match == null) return query;
+    if (match?.[1] == null) return null;
+    const days = Number.parseInt(match[1], 10);
+    return Math.floor((Date.now() - days * 86_400_000) / 1000);
+}
+/** Appends an absolute `after:<epoch seconds>` floor to a Gmail search query. */ function applyAfter(query, windowStart) {
+    if (windowStart == null) return query;
     if (/\b(newer_than:|after:)/i.test(query)) return query;
-    return `${query} newer_than:${match[1]}d`;
+    return `${query} after:${windowStart}`;
 }
 function maxHistoryId(messages) {
     let max = -1;
@@ -34,6 +44,13 @@ function maxHistoryId(messages) {
 }
 export function createGoogleMailProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
+    const mintFetchHLC = config.mintFetchHLC;
+    // getMessage/getThread/getLabel (api.ts) throw a plain Error tagged with
+    // `.httpStatus` — this is the seam fetchEntity/reconcile use to turn a 404
+    // into a `present: false` result instead of a throw.
+    function isNotFound(err) {
+        return err?.httpStatus === 404;
+    }
     async function listMessageIDs(query, signal) {
         const ids = [];
         let pageToken;
@@ -47,10 +64,16 @@ export function createGoogleMailProvider(config) {
         }while (pageToken != null)
         return ids;
     }
-    async function getMessage(id, signal) {
-        return fetchJSON(buildMessageGetURL({
-            messageID: id
-        }), config.credential, fetchFn, signal);
+    // Bulk-listing message fetch (fetchAll/fetchChanges) — delegates to the
+    // shared api.ts getMessage so both the bulk and targeted (fetchEntity)
+    // paths share one 404-tagging choke point.
+    async function getMessageResource(id, signal) {
+        return getMessage({
+            accessToken: config.credential.accessToken,
+            messageID: id,
+            fetch: fetchFn,
+            signal
+        });
     }
     async function profileHistoryId(signal) {
         const profile = await fetchJSON(buildProfileURL(), config.credential, fetchFn, signal);
@@ -61,19 +84,28 @@ export function createGoogleMailProvider(config) {
     // create/edit) but carries id, name, type, and the visibility fields.
     async function labelBatch(signal) {
         const data = await fetchJSON(buildLabelsListURL(), config.credential, fetchFn, signal);
+        const sourceFetchHLC = mintFetchHLC();
         return {
             modelID: LABEL_MODEL_ID,
-            entities: (data.labels ?? []).map(mapLabelToEntity),
+            entities: (data.labels ?? []).map((label)=>({
+                    present: true,
+                    record: mapLabelToEntity(label),
+                    sourceFetchHLC
+                })),
             hasMore: true
         };
     }
     async function* fetchAllEntities(params) {
         yield await labelBatch(params.signal);
-        const query = applyMaxAge(config.query ?? DEFAULT_QUERY, params.boundary);
+        // Reuse a window frozen by a prior sync (carried in a checkpoint on the 404
+        // resync path, or a re-driven initial); only a genuine first sync computes it.
+        const prior = params.checkpoint;
+        const windowStart = windowStartSeconds(params.boundary, prior?.windowStart);
+        const query = applyAfter(config.query ?? DEFAULT_QUERY, windowStart);
         const ids = await listMessageIDs(query, params.signal);
         const messages = [];
         for (const { id } of ids){
-            messages.push(await getMessage(id, params.signal));
+            messages.push(await getMessageResource(id, params.signal));
         }
         // Thread batch: one thread per distinct threadId, titled by its first message's subject.
         const threadSubjects = new Map();
@@ -82,19 +114,32 @@ export function createGoogleMailProvider(config) {
                 threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
             }
         }
+        const threadToken = mintFetchHLC();
         yield {
             modelID: THREAD_MODEL_ID,
             entities: [
                 ...threadSubjects
-            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            ].map(([threadId, subject])=>({
+                    present: true,
+                    record: mapThreadToEntity(threadId, subject),
+                    sourceFetchHLC: threadToken
+                })),
             hasMore: true
         };
         const checkpoint = {
-            historyId: maxHistoryId(messages) ?? await profileHistoryId(params.signal)
+            historyId: maxHistoryId(messages) ?? await profileHistoryId(params.signal),
+            ...windowStart != null ? {
+                windowStart
+            } : {}
         };
+        const messageToken = mintFetchHLC();
         yield {
             modelID: MESSAGE_MODEL_ID,
-            entities: messages.map(mapMessageToEntity),
+            entities: messages.map((message)=>({
+                    present: true,
+                    record: mapMessageToEntity(message),
+                    sourceFetchHLC: messageToken
+                })),
             hasMore: false,
             checkpoint
         };
@@ -150,7 +195,7 @@ export function createGoogleMailProvider(config) {
         ].filter((id)=>!deletedIDs.has(id));
         const messages = [];
         for (const id of survivingIDs){
-            messages.push(await getMessage(id, params.signal));
+            messages.push(await getMessageResource(id, params.signal));
         }
         const threadSubjects = new Map();
         for (const m of messages){
@@ -158,33 +203,112 @@ export function createGoogleMailProvider(config) {
                 threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
             }
         }
+        const threadToken = mintFetchHLC();
         yield {
             modelID: THREAD_MODEL_ID,
             entities: [
                 ...threadSubjects
-            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            ].map(([threadId, subject])=>({
+                    present: true,
+                    record: mapThreadToEntity(threadId, subject),
+                    sourceFetchHLC: threadToken
+                })),
             hasMore: true
         };
+        const messageToken = mintFetchHLC();
         yield {
             modelID: MESSAGE_MODEL_ID,
-            entities: messages.map(mapMessageToEntity),
+            entities: messages.map((message)=>({
+                    present: true,
+                    record: mapMessageToEntity(message),
+                    sourceFetchHLC: messageToken
+                })),
             deleted: [
                 ...deletedIDs
             ].map((id)=>({
-                    sourceService: 'google-mail',
-                    sourceID: id
+                    present: false,
+                    sourceID: id,
+                    sourceFetchHLC: messageToken
                 })),
             hasMore: false,
             checkpoint: {
-                historyId: latestHistoryId
+                historyId: latestHistoryId,
+                ...checkpoint.windowStart != null ? {
+                    windowStart: checkpoint.windowStart
+                } : {}
             }
         };
     }
+    // Targeted single-entity fetch (anti-entropy repair verification / write-back
+    // recovery). Mints its own fetch-order token at request start, independent of
+    // any batch token. `model` distinguishes the three GoogleMail* resources —
+    // Thread uses a real threads.get (not the bulk-listing subject synthesis
+    // fetchAll/fetchChanges use); Label uses labels.get (carries color, unlike
+    // the list endpoint labelBatch uses).
+    async function fetchEntity(model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        try {
+            if (model === THREAD_MODEL_ID) {
+                const thread = await getThread({
+                    accessToken: config.credential.accessToken,
+                    threadID: sourceID,
+                    fetch: fetchFn
+                });
+                const first = thread.messages?.[0];
+                const subject = first != null ? getHeader(first.payload?.headers, 'Subject') : undefined;
+                return {
+                    present: true,
+                    record: mapThreadToEntity(thread.id, subject),
+                    sourceFetchHLC
+                };
+            }
+            if (model === LABEL_MODEL_ID) {
+                const label = await getLabel({
+                    accessToken: config.credential.accessToken,
+                    labelID: sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    present: true,
+                    record: mapLabelToEntity(label),
+                    sourceFetchHLC
+                };
+            }
+            const message = await getMessage({
+                accessToken: config.credential.accessToken,
+                messageID: sourceID,
+                fetch: fetchFn
+            });
+            return {
+                present: true,
+                record: mapMessageToEntity(message),
+                sourceFetchHLC
+            };
+        } catch (err) {
+            if (isNotFound(err)) {
+                return {
+                    present: false,
+                    sourceID,
+                    sourceFetchHLC
+                };
+            }
+            throw err;
+        }
+    }
+    // Provider-authoritative re-read for write-back recovery. Gmail's
+    // resources carry no dependable ETag on a direct get, so this mirrors
+    // fetchEntity without a providerETag — present for contract parity with the
+    // other connectors' reconcile.
+    async function reconcile(model, sourceID) {
+        return fetchEntity(model, sourceID);
+    }
     return {
         supportedStrategies: [
             'on-demand'
         ],
         fetchAll: fetchAllEntities,
-        fetchChanges: fetchChangesEntities
+        fetchChanges: fetchChangesEntities,
+        fetchEntity,
+        reconcile
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-mail",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,10 +15,11 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.17.0",
-    "@kubun/credential-types": "^0.17.0",
+    "@kubun/connector": "^0.17.2",
+    "@kubun/credential-types": "^0.17.2",
+    "@kubun/hlc": "^0.17.0",
     "@kubun/models": "^0.17.0",
-    "@kubun/protocol": "^0.17.0",
+    "@kubun/protocol": "^0.17.1",
     "@kubun/provider-google": "^0.17.0",
     "@kubun/scalars": "^0.17.0",
     "@sozai/codec": "^0.4.0"