ofw-mcp 2.7.1 → 2.9.0

package/dist/extract/zip.js

@@ -0,0 +1,110 @@
+// A minimal, dependency-free ZIP reader.
+//
+// OOXML attachments (.xlsx/.docx/.pptx) are ZIP containers of XML parts, so
+// reading one is the first step of every office-document extractor. This is
+// deliberately not a general ZIP library: it reads the central directory,
+// slices an entry's bytes, and inflates DEFLATE members via the WHATWG
+// `DecompressionStream` — which exists in BOTH Node ≥18 and workerd, so the
+// same code runs on the stdio server and the hosted connector. Using
+// `node:zlib` here would break the Worker build; adding a userland inflate
+// dependency would bloat it. Neither is necessary.
+import { inflateBounded, MAX_DECOMPRESSED_BYTES } from './inflate.js';
+const EOCD_SIG = 0x06054b50;
+const CENTRAL_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+const ZIP64_SENTINEL = 0xffffffff;
+/**
+ * Hard ceiling on a single decompressed member (32 MiB). An attachment is a
+ * co-parent-supplied file, so a zip bomb is a real (if unlikely) input, and the
+ * Worker's memory budget is what is being protected.
+ *
+ * The cap is enforced on the bytes as they arrive ({@link inflateBounded}), NOT
+ * on the size the archive declares for itself. The declared size is checked too
+ * — it rejects an HONEST oversized member without inflating anything — but it
+ * is an optimization, not the guarantee: a central directory is free to claim
+ * 1 KB in front of a member that expands to a gigabyte.
+ */
+export const ZIP_MAX_UNCOMPRESSED_BYTES = MAX_DECOMPRESSED_BYTES;
+/** Locate the end-of-central-directory record, scanning back past any comment. */
+function findEocd(bytes) {
+    // The comment field is a uint16, so the record starts at most 22+65535 bytes
+    // from the end. Scan backwards for the signature.
+    const earliest = Math.max(0, bytes.length - (22 + 0xffff));
+    for (let i = bytes.length - 22; i >= earliest; i--) {
+        if (bytes.readUInt32LE(i) === EOCD_SIG)
+            return i;
+    }
+    throw new Error('not a ZIP archive (no end-of-central-directory record)');
+}
+export async function readZip(bytes, opts = {}) {
+    const limit = opts.maxUncompressedBytes ?? ZIP_MAX_UNCOMPRESSED_BYTES;
+    const eocd = findEocd(bytes);
+    const count = bytes.readUInt16LE(eocd + 10);
+    const cdOffset = bytes.readUInt32LE(eocd + 16);
+    if (cdOffset === ZIP64_SENTINEL || count === 0xffff) {
+        throw new Error('ZIP64 archives are not supported');
+    }
+    const entries = new Map();
+    let p = cdOffset;
+    for (let i = 0; i < count; i++) {
+        if (bytes.readUInt32LE(p) !== CENTRAL_SIG) {
+            throw new Error(`corrupt ZIP central directory at offset ${p}`);
+        }
+        const nameLen = bytes.readUInt16LE(p + 28);
+        const extraLen = bytes.readUInt16LE(p + 30);
+        const commentLen = bytes.readUInt16LE(p + 32);
+        const name = bytes.toString('utf8', p + 46, p + 46 + nameLen);
+        entries.set(name, {
+            name,
+            method: bytes.readUInt16LE(p + 10),
+            compressedSize: bytes.readUInt32LE(p + 20),
+            uncompressedSize: bytes.readUInt32LE(p + 24),
+            localOffset: bytes.readUInt32LE(p + 42),
+        });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    const cache = new Map();
+    async function read(name) {
+        const cached = cache.get(name);
+        if (cached)
+            return cached;
+        const entry = entries.get(name);
+        if (!entry)
+            return null;
+        // Cheap pre-check for an honest oversized member. A lying header falls
+        // through to the streaming cap below, which is the real guarantee.
+        if (entry.uncompressedSize > limit) {
+            throw new Error(`ZIP member ${name} is too large to extract (${entry.uncompressedSize} bytes)`);
+        }
+        // The central directory records the local header's offset, but the local
+        // header carries its OWN name/extra lengths (they can differ from the
+        // central copy), so the data offset must be computed from it.
+        const lo = entry.localOffset;
+        if (bytes.readUInt32LE(lo) !== LOCAL_SIG) {
+            throw new Error(`corrupt ZIP local header for ${name}`);
+        }
+        const start = lo + 30 + bytes.readUInt16LE(lo + 26) + bytes.readUInt16LE(lo + 28);
+        const raw = bytes.subarray(start, start + entry.compressedSize);
+        let out;
+        if (entry.method === 0)
+            out = Buffer.from(raw);
+        else if (entry.method === 8)
+            out = await inflateBounded(raw, 'deflate-raw', limit, `ZIP member ${name}`);
+        else
+            throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
+        cache.set(name, out);
+        return out;
+    }
+    return {
+        names: () => [...entries.keys()],
+        has: (name) => entries.has(name),
+        read,
+        async readText(name) {
+            const buf = await read(name);
+            if (!buf)
+                return null;
+            const text = buf.toString('utf8');
+            return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+        },
+    };
+}

package/dist/index.js

@@ -35,7 +35,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.7.1', // x-release-please-version
+    version: '2.9.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -94,6 +94,10 @@ export async function resolveFolderIds(client, store) {
     // label an uncached message sent-vs-inbox from the detail payload's own folder
     // id, instead of hard-defaulting to inbox.
     await store.setMeta('sent_folder_id', ids.sent);
+    // And inbox, which completes the map a lifecycle probe needs to turn a detail
+    // payload's own folder id into "draft" / "sent" / "received" (see
+    // tools/lifecycle.ts). Without all three, a probe can only say "unknown".
+    await store.setMeta('inbox_folder_id', ids.inbox);
     return ids;
 }
 // Required fields are the ones the sync loop reads unguarded (id keys the
@@ -222,8 +226,13 @@ async function walkPages(client, folder, folderId, opts, store) {
                 await fetchAttachmentMetaBudgeted(client, item.id, detailFileIds, store, budget);
             }
         }
-        // Flush the page's rows in one transaction/RPC. Empty array is a no-op.
-        await store.upsertMessages(toUpsert);
+        // Flush the page's rows in one transaction/RPC. Skipped entirely when the
+        // page held nothing new: on the Worker this call is a Durable-Object RPC,
+        // and a DO RPC counts against the same subrequest budget as an OFW fetch.
+        // A deep re-walk crosses page after page of already-cached messages, so an
+        // unconditional "no-op" write spends the caller's budget to store nothing.
+        if (toUpsert.length > 0)
+            await store.upsertMessages(toUpsert);
         if (pageBudgetHit) {
             // Paused mid-page. Resume at THIS page: the partial rows are cached, so
             // getMessages skips them next time and upserts are idempotent.

package/dist/tools/delivery.js

@@ -0,0 +1,99 @@
+// The attachment delivery ladder.
+//
+// A successful fetch must always produce retrievable content. "The host cannot
+// render this type" is a DISPLAY limit, and letting it become a DATA limit is
+// the bug this module exists to close: `ofw_download_attachment` used to fetch
+// a 10 KB custody-schedule spreadsheet, hand back an EmbeddedResource, and have
+// the host reject it with "Resources of type '…spreadsheetml.sheet' are not
+// currently supported" — leaving the caller holding nothing at all.
+//
+// Every inline delivery now walks the same rungs and returns the first that
+// works:
+//
+//   1. host-renderable image  → ImageContent (the model sees the picture)
+//   2. extractable document   → the FILE'S TEXT, as text (see src/extract)
+//   3. raw bytes              → base64 EmbeddedResource, as before
+//
+// Rung 3 never disappears, so nothing regresses; rung 2 is what makes a
+// spreadsheet, PDF, Word or PowerPoint attachment readable at all. When a rung
+// is skipped or fails, the response says so by name in `deliveryAttempts` —
+// a caller must never be left guessing why it got bytes instead of content.
+import { extractAttachment } from '../extract/index.js';
+import { isHostRenderableImage } from './attachments.js';
+/**
+ * Attempt extraction, converting every failure into a REASON rather than an
+ * exception: a format we cannot read must still be delivered as bytes, and the
+ * caller is owed the explanation either way.
+ */
+export async function tryExtract(bytes, mimeType, fileName, opts) {
+    try {
+        const extracted = await extractAttachment(bytes, mimeType, fileName, {
+            maxChars: opts.maxChars,
+            parts: opts.parts,
+        });
+        if (!extracted) {
+            return { reason: `no text extractor for ${mimeType} (${fileName})` };
+        }
+        return { extracted, truncated: extracted.truncated ?? false };
+    }
+    catch (err) {
+        // A malformed .xlsx is still an .xlsx: report why it could not be read and
+        // fall through to the bytes, rather than failing the whole call.
+        return { reason: `extraction failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Build the content blocks for an inline download by walking the ladder.
+ * The first block is always a JSON meta block naming `deliveredVia`, so the
+ * caller can tell how the content arrived without inspecting block types.
+ */
+export async function buildInlineDelivery(input) {
+    const { fileId, fileName, mimeType, bytes, forcedInline, options } = input;
+    const meta = {
+        fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
+    };
+    if (forcedInline)
+        meta.forcedInline = true;
+    const block = () => ({ type: 'text', text: JSON.stringify(meta, null, 2) });
+    // Rung 1 — the host renders these itself, and a picture beats a description.
+    if (isHostRenderableImage(mimeType)) {
+        meta.deliveredVia = 'image';
+        return { content: [block(), { type: 'image', data: bytes.toString('base64'), mimeType }] };
+    }
+    // Rung 2 — extraction. Skipped only when the caller explicitly opts out.
+    const attempts = [];
+    if (options.extract === false) {
+        attempts.push('extraction skipped (extract:false)');
+    }
+    else {
+        const outcome = await tryExtract(bytes, mimeType, fileName, options);
+        if (outcome.extracted) {
+            meta.deliveredVia = 'extracted';
+            meta.extracted = outcome.extracted;
+            meta.truncated = outcome.truncated;
+            // The bytes are deliberately NOT also attached: the extracted text is the
+            // readable form, and a duplicate base64 blob would be the very payload
+            // the host rejects — plus double the response size.
+            meta.note = 'Content extracted from the file. Pass extract:false to get the raw bytes instead.';
+            return { content: [block()] };
+        }
+        /* v8 ignore next -- tryExtract always sets `reason` when it returns no extraction */
+        attempts.push(outcome.reason ?? 'extraction produced no content');
+    }
+    // Rung 3 — the bytes themselves. Always available, so a fetch that succeeded
+    // never ends with the caller holding nothing.
+    meta.deliveredVia = 'blob';
+    meta.deliveryAttempts = attempts;
+    meta.note = 'Returned as raw bytes. Some hosts cannot render an embedded resource of this type; '
+        + 'if it came back unreadable, the file has no text extractor here (see deliveryAttempts).';
+    return {
+        content: [block(), {
+                type: 'resource',
+                resource: {
+                    uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
+                    mimeType,
+                    blob: bytes.toString('base64'),
+                },
+            }],
+    };
+}

package/dist/tools/draft-freshness.js

@@ -39,18 +39,40 @@ const ServerDraftSchema = z.looseObject({
     body: z.string().optional(),
     replyToId: z.number().nullable().optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // Read for the LIFECYCLE answer (see tools/lifecycle.ts): which folder OFW
+    // itself says this id lives in right now. `existsOnServer` alone cannot
+    // distinguish "still a draft" from "was sent" — a sent draft still exists.
+    // `id` accepts BOTH spellings deliberately. This schema is parsed in
+    // `mode: 'strict'` because it backs the destructive-draft guard, so a
+    // present-but-mistyped field THROWS — and OFW is already inconsistent about
+    // this exact field: the folders listing (`FoldersSchema` in sync.ts) types it
+    // `z.string()`, while message detail has been observed returning a number.
+    // Pinning one spelling here would turn a harmless representation change into
+    // a hard failure of ofw_save_draft / ofw_delete_draft, which is the opposite
+    // of what a strict boundary is for: it exists to stop us acting on a response
+    // we cannot interpret, not to reject one we can. `folderId` is normalized to
+    // a string below, so both spellings compare correctly downstream.
+    folder: z.looseObject({
+        id: z.union([z.string(), z.number()]).optional(),
+        name: z.string().optional(),
+    }).nullable().optional(),
+    date: z.looseObject({ dateTime: z.string().optional() }).nullable().optional(),
 });
 function isNotFound(e) {
     return e instanceof Error && /OFW API error: 404\b/.test(e.message);
 }
 /**
- * Read a draft's AUTHORITATIVE state straight from OFW, bypassing the cache.
+ * Read a message's AUTHORITATIVE state straight from OFW, bypassing the cache.
  *
- * Returns `null` when the draft no longer exists (404). Any other failure
- * throws `DraftFreshnessError`: a freshness check that could not run must
- * abort the write, never wave it through — see the callers in messages.ts.
+ * Returns `null` when it no longer exists (404, or an empty body — OFW's other
+ * way of saying "no such message"). Any other failure throws.
+ *
+ * Most failures throw `DraftFreshnessError`, but not all — a strict
+ * `parseLenient` mismatch throws `McpToolError` instead. Callers must not assume
+ * the narrower type (the catch blocks read only `.message`, which every Error
+ * carries).
  */
-export async function fetchServerDraft(client, id) {
+export async function fetchMessageSnapshot(client, id) {
     let raw;
     try {
         raw = await client.request('GET', `/pub/v3/messages/${id}`);
@@ -71,12 +93,28 @@ export async function fetchServerDraft(client, id) {
         mode: 'strict',
     });
     return {
-        subject: detail.subject ?? '',
-        body: detail.body ?? '',
-        replyToId: detail.replyToId ?? null,
-        recipients: mapRecipients(detail.recipients),
+        content: {
+            subject: detail.subject ?? '',
+            body: detail.body ?? '',
+            replyToId: detail.replyToId ?? null,
+            recipients: mapRecipients(detail.recipients),
+        },
+        folderId: detail.folder?.id === undefined ? null : String(detail.folder.id),
+        folderName: detail.folder?.name ?? null,
+        dateTime: detail.date?.dateTime ?? null,
     };
 }
+/**
+ * The content-only view of {@link fetchMessageSnapshot}, used by the
+ * destructive-draft guard, which cares what the draft SAYS, not where it lives.
+ *
+ * Returns `null` when the draft no longer exists. Any other failure throws, and
+ * the callers in messages.ts abort on ALL of them: a freshness check that could
+ * not run must never wave the write through.
+ */
+export async function fetchServerDraft(client, id) {
+    return (await fetchMessageSnapshot(client, id))?.content ?? null;
+}
 /**
  * The fields whose divergence constitutes a REAL conflict — the actual message
  * content a caller would lose if we overwrote a copy edited elsewhere. Anything

package/dist/tools/lifecycle.js

@@ -0,0 +1,277 @@
+import { resolveFolderIds } from '../sync.js';
+import { draftRevision, fetchMessageSnapshot } from './draft-freshness.js';
+import { deriveRead } from './_shared.js';
+/** OFW's `folderType` discriminator for each folder we track. */
+export const FOLDER_TYPE = {
+    inbox: 'INBOX',
+    sent: 'SENT_MESSAGES',
+    drafts: 'DRAFTS',
+};
+/** Where each folder's id is persisted in the `meta` table. */
+const FOLDER_ID_META_KEY = {
+    inbox: 'inbox_folder_id',
+    sent: 'sent_folder_id',
+    drafts: 'drafts_folder_id',
+};
+const FOLDERS = ['inbox', 'sent', 'drafts'];
+/** Read whatever folder ids past syncs persisted. No requests. */
+export async function readFolderIdMap(store) {
+    return {
+        inbox: await store.getMeta(FOLDER_ID_META_KEY.inbox),
+        sent: await store.getMeta(FOLDER_ID_META_KEY.sent),
+        drafts: await store.getMeta(FOLDER_ID_META_KEY.drafts),
+    };
+}
+/**
+ * Persist folder ids harvested from a folders listing the caller ALREADY
+ * fetched.
+ *
+ * `ofw_check_freshness` asked about folders and ids in one call hits
+ * `/pub/v1/messageFolders?includeFolderCounts=true` for the counts, and then
+ * `ensureFolderIdMap` hit the very same endpoint again to learn the ids. The
+ * response in hand already carries them; taking them makes the second call a
+ * no-op instead of a duplicate round trip.
+ */
+export async function persistFolderIds(store, systemFolders) {
+    for (const folder of FOLDERS) {
+        const entry = systemFolders.find((f) => f.folderType === FOLDER_TYPE[folder]);
+        if (entry !== undefined)
+            await store.setMeta(FOLDER_ID_META_KEY[folder], entry.id);
+    }
+}
+/**
+ * The folder map, resolving it live when the cache has never held all three.
+ *
+ * Costs at most ONE request, and only when the map is genuinely incomplete —
+ * without it every probe degrades to `unknown`, which is a refusal to answer,
+ * not an answer. A failed resolve is swallowed: we fall back to the partial
+ * cached map and let classification say `unknown` honestly, rather than failing
+ * a whole status call over a folder listing.
+ */
+export async function ensureFolderIdMap(client, store) {
+    const cached = await readFolderIdMap(store);
+    if (cached.inbox !== null && cached.sent !== null && cached.drafts !== null) {
+        return { map: cached, requests: 0 };
+    }
+    try {
+        const ids = await resolveFolderIds(client, store);
+        return { map: { inbox: ids.inbox, sent: ids.sent, drafts: ids.drafts }, requests: 1 };
+    }
+    catch {
+        return { map: cached, requests: 1 };
+    }
+}
+/**
+ * Map a live snapshot to a lifecycle state. Pure — the request already happened.
+ *
+ * A null snapshot means OFW returned 404 / an empty body, i.e. `deleted`. An
+ * unmappable folder is `unknown` rather than being guessed at: guessing here is
+ * exactly how "still a draft" gets asserted about something that was sent.
+ */
+export function classifyState(snapshot, map) {
+    if (snapshot === null)
+        return 'deleted';
+    const { folderId } = snapshot;
+    if (folderId === null)
+        return 'unknown';
+    if (map.drafts !== null && folderId === map.drafts)
+        return 'draft';
+    if (map.sent !== null && folderId === map.sent)
+        return 'sent';
+    if (map.inbox !== null && folderId === map.inbox)
+        return 'received';
+    return 'unknown';
+}
+/**
+ * Would probing this id stamp the record?
+ *
+ * A probe is `GET /pub/v3/messages/{id}`, and for an UNREAD INBOX message that
+ * marks it read on OFW and writes a co-parent-visible "First Viewed" time —
+ * court-visible and irreversible. Everything else is free of side effects:
+ *
+ *   - a cached DRAFT: drafts have no read state at all;
+ *   - a cached SENT message: its view times belong to the recipient, and our
+ *     own fetch never writes one;
+ *   - a cached inbox message already derived as read: the stamp exists, and
+ *     `deriveRead` is monotonic so it cannot be added twice.
+ *
+ * An id with NO cached row returns true — whether it would stamp is exactly
+ * what cannot be known without making the request that stamps it.
+ */
+export function probeWouldStamp(cachedDraft, cachedMessage) {
+    if (cachedDraft !== null)
+        return false;
+    if (cachedMessage === null)
+        return true;
+    if (cachedMessage.folder === 'sent')
+        return false;
+    return !deriveRead(cachedMessage);
+}
+const SKIP_NOTE = 'Verifying this id requires fetching its detail from OurFamilyWizard, which would mark an unread inbox message as READ and stamp a co-parent-visible "First Viewed" time on the record. Ids already cached as drafts, as sent, or as already-read inbox messages are probed freely because none of those can stamp anything. Run ofw_sync_messages (it walks list pages, not bodies) or pass allowMarkRead:true.';
+function stateNote(state, cachedAsDraft, folderName) {
+    if (state === 'deleted') {
+        return cachedAsDraft
+            ? 'This draft is in the local cache but NO LONGER EXISTS on OurFamilyWizard — it was sent or deleted elsewhere. Do not describe it as still unsent.'
+            : 'Not found on OurFamilyWizard.';
+    }
+    if (state === 'sent') {
+        return cachedAsDraft
+            ? 'This id is cached as a DRAFT but OurFamilyWizard now has it in Sent — it was SENT (see sentAt). It is no longer a draft; saying it is still unsent would be false.'
+            : 'This id is a sent message on OurFamilyWizard.';
+    }
+    if (state === 'received') {
+        return cachedAsDraft
+            ? 'This id is cached as a draft but OurFamilyWizard has it in the Inbox. Run ofw_sync_messages to reconcile.'
+            : 'This id is an inbox message on OurFamilyWizard.';
+    }
+    if (state === 'unknown') {
+        return `OurFamilyWizard did not report a folder this tool can map${folderName === null ? '' : ` (it reported "${folderName}")`}, so what this id has become is NOT established. Treat it as unverified rather than assuming it is unchanged.`;
+    }
+    return undefined;
+}
+/**
+ * Probe a batch of ids live and return one lifecycle verdict each.
+ *
+ * Skips are decided BEFORE anything is fetched, so a call whose every id is
+ * refused spends zero OFW requests — including the folder-map resolve, which
+ * only happens when at least one id will actually be probed. Costs at most one
+ * request for the map plus one per probed id.
+ */
+export async function probeIds(client, store, ids, opts) {
+    // THREE cache reads for the whole batch, not three per id. On the Durable
+    // Object backend every cache call is a subrequest counting against the same
+    // hosting cap as the OFW fetches, so a per-id lookup would spend the caller's
+    // budget on bookkeeping before a single probe ran.
+    const draftsById = new Map((await store.getDrafts(ids)).map((d) => [d.id, d]));
+    const messagesById = new Map((await store.getMessages(ids)).map((m) => [m.id, m]));
+    const prepared = ids.map((id) => {
+        const cachedDraft = draftsById.get(id) ?? null;
+        const cachedMessage = cachedDraft === null ? messagesById.get(id) ?? null : null;
+        return {
+            id,
+            cachedDraft,
+            cachedMessage,
+            skip: !opts.allowMarkRead && probeWouldStamp(cachedDraft, cachedMessage),
+        };
+    });
+    let requests = 0;
+    let map = { inbox: null, sent: null, drafts: null };
+    if (prepared.some((p) => !p.skip)) {
+        const resolved = await ensureFolderIdMap(client, store);
+        map = resolved.map;
+        requests += resolved.requests;
+    }
+    const keyById = new Map((await store.getDraftLineageByIds(ids)).map((l) => [l.id, l.draftKey]));
+    const items = [];
+    for (const p of prepared) {
+        if (p.skip) {
+            items.push({ id: p.id, skipped: true, reason: 'WOULD_MARK_READ', note: SKIP_NOTE });
+            continue;
+        }
+        const probe = await probeOne(client, p, map, keyById.get(p.id) ?? null);
+        requests += probe.requests;
+        items.push(probe.item);
+    }
+    return { items, requests };
+}
+/**
+ * The live half of one probe. Never throws: a probe that could not run comes
+ * back as an error item, because a check that failed must never read as
+ * "in sync".
+ */
+async function probeOne(client, prepared, map, draftKey) {
+    const { id, cachedDraft } = prepared;
+    let snapshot;
+    try {
+        snapshot = await fetchMessageSnapshot(client, id);
+    }
+    catch (e) {
+        return {
+            requests: 1,
+            item: {
+                id,
+                error: 'FRESHNESS_CHECK_FAILED',
+                message: e.message,
+                inSync: null,
+                note: 'The freshness check itself failed, so nothing is confirmed either way.',
+            },
+        };
+    }
+    const state = classifyState(snapshot, map);
+    const cacheRevision = cachedDraft === null ? null : draftRevision(cachedDraft);
+    const serverRevision = snapshot === null ? null : draftRevision(snapshot.content);
+    const viewedAt = snapshot?.content.recipients.find((r) => r.viewedAt !== null)?.viewedAt ?? null;
+    // `inSync` compares the CACHED DRAFT against the server, and it is FALSE the
+    // moment the entity stops being what the cache says it is — even when every
+    // byte of content still matches. A sent draft keeps its subject and body
+    // verbatim, so a revision-only comparison reported inSync:true for exactly
+    // the case this whole mechanism exists to catch.
+    //
+    // `null` means "not compared", the same thing it means on the folder
+    // verdicts: there is no cached draft to compare, or the content matches but
+    // OFW did not tell us where the message now lives. Never `false` for those —
+    // false claims a drift was detected.
+    let inSync;
+    if (cachedDraft === null)
+        inSync = null;
+    else if (snapshot === null)
+        inSync = false;
+    else if (cacheRevision !== serverRevision)
+        inSync = false;
+    else if (state === 'draft')
+        inSync = true;
+    else if (state === 'unknown')
+        inSync = null;
+    else
+        inSync = false;
+    // State and content are INDEPENDENT signals, so both are reported. An
+    // unmappable folder must not swallow "this was edited on OFW", and a content
+    // match must not swallow "this is no longer a draft".
+    const notes = [];
+    const stateN = stateNote(state, cachedDraft !== null, snapshot?.folderName ?? null);
+    if (stateN !== undefined)
+        notes.push(stateN);
+    if (snapshot !== null && cachedDraft === null) {
+        notes.push('Not in the drafts cache, so there is no cached copy to compare its content against (inSync is null, not false).');
+    }
+    else if (snapshot !== null && cacheRevision !== serverRevision) {
+        notes.push('Content differs from the cache — it was edited on OurFamilyWizard since the last sync. Run ofw_sync_messages before reading or writing it.');
+    }
+    return {
+        requests: 1,
+        item: {
+            id,
+            state,
+            folder: snapshot?.folderName ?? null,
+            sentAt: state === 'sent' ? snapshot?.dateTime ?? null : null,
+            viewedAt,
+            existsOnServer: snapshot !== null,
+            cacheRevision,
+            serverRevision,
+            inSync,
+            ...(draftKey !== null ? { draftKey } : {}),
+            ...(notes.length > 0 ? { note: notes.join(' ') } : {}),
+        },
+    };
+}
+/**
+ * Resolve a stable {@link import('../cache/store.js').DraftLineageRow} key to
+ * the chain's CURRENT id.
+ *
+ * Returns null when the key was never recorded — an unknown key must not
+ * silently resolve to nothing-in-particular.
+ */
+export async function resolveDraftKey(store, draftKey) {
+    const chain = await store.getDraftLineage(draftKey);
+    if (chain.length === 0)
+        return null;
+    return { currentId: chain[chain.length - 1].id, ids: chain.map((r) => r.id) };
+}
+/**
+ * Mint a new stable draft identity. Uses the Web Crypto global, which both
+ * Node ≥19 and the Workers runtime provide — a `node:crypto` import would not
+ * bundle for the hosted connector.
+ */
+export function newDraftKey() {
+    return `dk_${crypto.randomUUID()}`;
+}