ofw-mcp 2.10.2 → 2.12.0

package/dist/cache/store.js

@@ -261,8 +261,13 @@ export class OFWCacheCore {
     listMessages(opts) {
         const { where, params } = buildMessageFilter(opts);
         const offset = (opts.page - 1) * opts.size;
+        // Direction comes from a closed set of literals, never from caller input.
+        // `id` tiebreaks in the SAME direction as `sent_at` so paging stays a total
+        // order: rows sharing a timestamp keep a stable relative position, and none
+        // is skipped or repeated at a page boundary.
+        const dir = opts.sort === 'oldest' ? 'ASC' : 'DESC';
         const rows = this.db.all(`SELECT * FROM messages ${where}
-       ORDER BY sent_at DESC, id DESC
+       ORDER BY sent_at ${dir}, id ${dir}
        LIMIT ? OFFSET ?`, [...params, opts.size, offset]);
         return rows.map(rowFromDb);
     }

package/dist/client.js

@@ -3,6 +3,7 @@ import { TokenManager } from '@chrischall/mcp-utils/session';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveAuth } from './auth.js';
+import { createSessionCache, reportCacheWriteFailure } from './session-cache.js';
 import { BASE_URL, OFW_PROTOCOL_HEADERS, OFW_TOKEN_TTL_MS, OFW_TOKEN_EXPIRY_SKEW_MS } from './protocol.js';
 // Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb
 // bundle). loadDotenvSafely applies override:false + quiet:true and swallows a
@@ -62,9 +63,9 @@ export class OFWClient {
     // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
     // (proactive refresh inside the skew window, single-flight refresh so a burst
     // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
-    // guarded against double-refresh). It is created lazily, seeded with an
-    // already-expired placeholder token so the first request drives the refresh
-    // callback — i.e. the original "log in on first request" behavior.
+    // guarded against double-refresh). It is created lazily, and mints on first
+    // use through the function form of `initial` — see `mint` below for why that
+    // form rather than a seeded placeholder.
     tokenManager;
     // Optional injected auth resolver. When set, the refresh callback uses it
     // instead of the module-level global `resolveAuth` (env-var → fetchproxy
@@ -78,22 +79,33 @@ export class OFWClient {
     }
     getTokenManager() {
         if (!this.tokenManager) {
+            // Minting and renewing are the SAME operation here — OFW has no refresh
+            // grant — so one function serves as both `initial` and `refresh`. It has
+            // to be the function form: the eager object form skips persistence, so
+            // the expired placeholder that used to sit here would have meant the
+            // cache was written but never read.
+            const mint = async () => {
+                const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
+                return {
+                    accessToken: token,
+                    refreshToken: OFW_REFRESH_SENTINEL,
+                    expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
+                };
+            };
             this.tokenManager = new TokenManager({
-                initial: { accessToken: '', refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+                initial: mint,
+                persistence: createSessionCache({ injectedResolver: this.authResolver !== undefined }) ?? undefined,
+                onPersistError: reportCacheWriteFailure,
+                // A failed renewal IS a failed login here, so the library's
+                // re-mint-on-revoked recovery would just repeat the call that failed.
+                isRefreshRevoked: () => false,
                 skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
                 // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
                 // returns a token and a best-effort expiry; when the fetchproxy path
                 // can't supply one we fall back to the same 6h estimate the password
                 // path uses (the 401-replay covers a wrong guess). We re-arm the
                 // sentinel so the manager can refresh again later.
-                refresh: async () => {
-                    const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
-                    return {
-                        accessToken: token,
-                        refreshToken: OFW_REFRESH_SENTINEL,
-                        expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime(),
-                    };
-                },
+                refresh: mint,
             });
         }
         return this.tokenManager;

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.10.2', // x-release-please-version
+    version: '2.12.0', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/session-cache.js

@@ -0,0 +1,78 @@
+import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
+/**
+ * Where the OFW session token is cached between runs.
+ *
+ * OFW has no OAuth refresh token — every renewal re-runs the full
+ * `resolveAuth()` (a password POST, or a fetchproxy snapshot). The token itself
+ * is good for six hours (`OFW_TOKEN_TTL_MS`), so on a scale-to-zero host, where
+ * children idle out after ten minutes and every start is a cold one, the same
+ * six-hour token was being re-minted many times over. Caching it turns those
+ * restarts into zero-cost ones; an expired token still costs exactly what it did
+ * before.
+ */
+export function sessionCachePath(env = process.env) {
+    return resolveStateFile({
+        env,
+        envVar: 'OFW_SESSION_FILE',
+        subdir: '.ofw-mcp',
+        fileName: 'session.json',
+    });
+}
+/** Only a token pair is ever stored — never the username or password. */
+function isTokens(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const t = raw;
+    return (typeof t.accessToken === 'string' &&
+        t.accessToken !== '' &&
+        typeof t.expiresAt === 'number' &&
+        (t.refreshToken === undefined || typeof t.refreshToken === 'string'));
+}
+/**
+ * The session cache, or `null` when it must not be used.
+ *
+ * Three ways it comes back `null`, each deliberate:
+ *
+ *  - `OFW_SESSION_CACHE=false` — the operator opted out.
+ *  - **A caller-injected auth resolver.** That is the per-user hosted path, and
+ *    this registration declares no `identity.perUserChild`, so one process can
+ *    serve several people. A single cache file would hand one user's session to
+ *    the next; until the child is per-user, that path simply does not cache.
+ *  - **No env credentials.** The fetchproxy path authenticates from a signed-in
+ *    browser tab rather than a stored secret, so there is nothing stable to bind
+ *    a cached token to — and it is local-only, where cold starts are rare.
+ *
+ * When it is used, the record is bound to the credentials that minted it, so
+ * rotating either discards it. Only a salted digest is written.
+ */
+export function createSessionCache(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.injectedResolver === true)
+        return null;
+    if (!parseBoolEnv('OFW_SESSION_CACHE', { env, default: true }))
+        return null;
+    const username = readEnvVar('OFW_USERNAME', { env });
+    const password = readEnvVar('OFW_PASSWORD', { env });
+    if (username === undefined || password === undefined)
+        return null;
+    return createFileStatePersistence({
+        filePath: sessionCachePath(env),
+        // Joined on a NUL, written as an escape rather than a literal byte: a
+        // password may contain spaces, so a space-joined pair could collide with
+        // a different pair by shifting the boundary between the two halves.
+        boundTo: [username.trim().toLowerCase(), password].join('\u0000'),
+        validate: (raw) => (isTokens(raw) ? raw : null),
+    });
+}
+/**
+ * Report a cache write that failed. Not fatal: OFW tokens are re-mintable from
+ * the credentials in the environment, so a lost write costs the next start a
+ * login rather than access. Still worth saying — a read-only data dir otherwise
+ * looks exactly like a server that never caches. stderr only; stdout is JSON-RPC.
+ */
+export function reportCacheWriteFailure(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`[ofw-mcp] could not cache the session token (${detail}); continuing without the ` +
+        'cache — every restart will re-authenticate until this is fixed.');
+}

package/dist/tools/expenses.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.js';
+import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerExpenseTools(server, client) {
     // Expense writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
@@ -12,17 +13,34 @@ export function registerExpenseTools(server, client) {
         return jsonResponse(data);
     });
     server.registerTool('ofw_list_expenses', {
-        description: 'List OurFamilyWizard expenses with pagination',
+        description: 'List OurFamilyWizard expenses. Offset-paged via start/max. The response leads with its paging state — `hasMore` and `nextStart` (null when the list is exhausted) — BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an expense total or an absence from one page.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().int().min(0).describe('Start offset (default 0)').optional(),
+            start: z.number().int().min(0).describe('Start offset, 0-based (default 0). To continue a listing, pass the `nextStart` from the previous response.').optional(),
             max: z.number().int().min(1).describe('Max results (default 20)').optional(),
         },
     }, async (args) => {
         const start = args.start ?? 0;
         const max = args.max ?? 20;
         const data = await client.request('GET', `/pub/v2/expense/expenses?start=${start}&max=${max}`);
-        return jsonResponse(data);
+        // Paging state FIRST, records after — a partial read of a spilled response
+        // must reach "there are more" before it reaches the records. See
+        // src/tools/pagination.ts for why the order is load-bearing.
+        //
+        // OFW wraps these listings as {data, metadata} and its metadata carries a
+        // `last` boolean, so "is there another page" is answered by the server
+        // rather than inferred from a full page (verified live).
+        const { returned, total, last } = readUpstreamPaging(data);
+        const wrapped = withPaginationFirst({
+            state: offsetState({ start, max, returned, total, last, base: 0 }),
+            start, max, returned, total,
+            hint: `Re-call ofw_list_expenses with start:${start + max}.`,
+            payload: data,
+        });
+        // A payload that is not a plain object cannot carry the paging keys at all.
+        // Pass it through untouched rather than relocating it — an added field is
+        // never worth changing a response's top-level shape.
+        return jsonResponse(wrapped ?? data);
     });
     if (allowWrites)
         server.registerTool('ofw_create_expense', {

package/dist/tools/journal.js

@@ -1,14 +1,15 @@
 import { z } from 'zod';
 import { jsonResponse } from './_shared.js';
+import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerJournalTools(server, client) {
     // Journal writes land on the court-visible record — OFW_WRITE_MODE 'all' only.
     const allowWrites = getWriteMode() === 'all';
     server.registerTool('ofw_list_journal_entries', {
-        description: 'List OurFamilyWizard journal entries',
+        description: 'List OurFamilyWizard journal entries. Offset-paged via start/max (1-based). The response leads with its paging state — `hasMore` and `nextStart` (null when the list is exhausted) — BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an entry count or an absence from one page.',
         annotations: { readOnlyHint: true },
         inputSchema: {
-            start: z.number().int().min(1).describe('Start offset (default 1)').optional(),
+            start: z.number().int().min(1).describe('Start offset, 1-based (default 1). To continue a listing, pass the `nextStart` from the previous response.').optional(),
             max: z.number().int().min(1).describe('Max results (default 10)').optional(),
         },
     }, async (args) => {
@@ -16,7 +17,24 @@ export function registerJournalTools(server, client) {
         const start = args.start ?? 1;
         const max = args.max ?? 10;
         const data = await client.request('GET', `/pub/v1/journals?start=${start}&max=${max}`);
-        return jsonResponse(data);
+        // Paging state FIRST, records after — a partial read of a spilled response
+        // must reach "there are more" before it reaches the records. See
+        // src/tools/pagination.ts for why the order is load-bearing.
+        //
+        // OFW wraps these listings as {data, metadata} and its metadata carries a
+        // `last` boolean, so "is there another page" is answered by the server
+        // rather than inferred from a full page (verified live).
+        const { returned, total, last } = readUpstreamPaging(data);
+        const wrapped = withPaginationFirst({
+            state: offsetState({ start, max, returned, total, last, base: 1 }),
+            start, max, returned, total,
+            hint: `Re-call ofw_list_journal_entries with start:${start + max}.`,
+            payload: data,
+        });
+        // A payload that is not a plain object cannot carry the paging keys at all.
+        // Pass it through untouched rather than relocating it — an added field is
+        // never worth changing a response's top-level shape.
+        return jsonResponse(wrapped ?? data);
     });
     if (allowWrites)
         server.registerTool('ofw_create_journal_entry', {

package/dist/tools/messages.js

@@ -10,6 +10,7 @@ import { getAllowMarkRead, getAttachmentsDir, getAutoRefreshStaleReads, getDefau
 import { basename, join } from 'node:path';
 import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, reportsThreaded, reportsUnthreaded, textResponse, threadedReplyTo, verifyWriteLanded, withReadState } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
+import { pageState } from './pagination.js';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
 const DateSchema = z.looseObject({ dateTime: z.string() });
@@ -254,7 +255,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         return jsonResponse({ folders: data, freshness });
     });
     server.registerTool('ofw_list_messages', {
-        description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
+        description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based (1-based `page`) but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
         annotations: { readOnlyHint: false },
         inputSchema: {
             folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
@@ -263,11 +264,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             since: z.string().describe('ISO date or datetime — only messages with sent_at >= since (inclusive)').optional(),
             until: z.string().describe('ISO date or datetime — only messages with sent_at < until (exclusive)').optional(),
             q: z.string().describe('Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.').optional(),
+            sort: z.enum(['newest', 'oldest']).describe('Result order: "newest" (default, newest first) or "oldest" (oldest first). This decides which end a truncated page keeps — with "newest" page 1 of a wide date range holds its most RECENT slice, with "oldest" its earliest. Use "oldest" to start at the old end of a range instead of paging to it.').optional(),
             autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
+        const sort = args.sort ?? 'newest';
         const folderArg = args.folderId ?? 'both';
         let folder;
         if (folderArg === 'inbox')
@@ -303,7 +306,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // can be stale (a message read after it was first scraped), so `read`
                 // is derived from the record's own `viewedAt`/`fetchedBodyAt` and
                 // `listData` is forced to agree — see withReadState.
-                const messages = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
+                const messages = (await cache.listMessages({ ...filter, page, size, sort })).map((m) => withReadState(m));
                 // Served from the local cache, so the result must say how old it is and
                 // whether anything vouches for it — a caller cannot state current state
                 // from this payload without either re-reading or surfacing the caveat.
@@ -328,7 +331,28 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // needs one boolean to check before saying "you have N messages".
         const fullSlice = page === 1 && messages.length === total;
         const complete = fullSlice && freshness.staleness === 'fresh' && freshness.historyComplete;
-        const payload = { messages, total, page, size, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Key ORDER is load-bearing, not cosmetic. These responses are large enough
+        // that a client may spill them to a file and a script may pull out only the
+        // fields it thought to name — which is how a correct `complete:false` next
+        // to a correct `completeNote` was dropped, and a 60-of-391 slice was
+        // reported as "October 1-28 is unreachable". Paging state and freshness are
+        // emitted BEFORE `messages` so a head, a preview, or a truncated read hits
+        // "this is a slice, fetch page 2" before it hits the first message body.
+        // The bulk goes last. See tests asserting this order — a refactor that
+        // rebuilds this literal silently undoes it.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            // The honest record count, as a scalar and ahead of the array — a
+            // consumer never has to reach `messages` to learn how many came back.
+            returned: messages.length,
+            total,
+            page,
+            size,
+            sort,
+        };
         if (!complete) {
             payload.completeNote = [
                 !fullSlice ? `this page holds ${messages.length} of ${total} matching cached messages` : null,
@@ -342,11 +366,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             payload.note = 'No messages match these filters, and the cache IS verified-fresh for these folders — so this is a real "nothing matched", not a stale-cache artefact. If you expected results, relax the filters.';
         }
         else if (page * size < total) {
-            payload.note = `Showing ${(page - 1) * size + 1}–${(page - 1) * size + messages.length} of ${total}. Increase 'page' to see more, or narrow with since/until/q.`;
+            payload.note = `Showing ${(page - 1) * size + 1}–${(page - 1) * size + messages.length} of ${total}, ${sort} first. Increase 'page' to see more, narrow with since/until/q, or set sort:"${sort === 'newest' ? 'oldest' : 'newest'}" to start from the other end.`;
         }
         if (refreshed) {
             payload.autoRefreshed = true;
         }
+        payload.freshness = freshness;
+        payload.messages = messages;
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
@@ -916,7 +942,18 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // against OFW inside the freshness window AND not a slice of a larger list.
         const fullSlice = page === 1 && drafts.length === total;
         const complete = serverConfirmed && fullSlice;
-        const payload = { drafts, total, page, size, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Paging state and freshness ahead of the bulk — see the note in
+        // ofw_list_messages.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            returned: drafts.length,
+            total,
+            page,
+            size,
+        };
         if (!complete) {
             payload.completeNote = [
                 !fullSlice ? `this page holds ${drafts.length} of ${total} cached drafts` : null,
@@ -937,6 +974,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (verifyNote !== null) {
             payload.verifyNote = verifyNote;
         }
+        payload.freshness = freshness;
+        payload.drafts = drafts;
         return jsonResponse(payload);
     });
     if (allowDrafts)
@@ -1226,7 +1265,20 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
             }
         }
-        const payload = { unread, scanned: sent.length, total, complete, freshness };
+        const { hasMore, nextPage } = pageState({ page, size, total });
+        // Paging state ahead of the bulk — see the note in ofw_list_messages. Note
+        // `unread` is a VERDICT list, not the scanned set: it is routinely empty
+        // while the scan itself is truncated, which is what `scanned`/`total`/
+        // `complete` are for.
+        const payload = {
+            complete,
+            hasMore,
+            nextPage,
+            total,
+            scanned: sent.length,
+            page,
+            size,
+        };
         if (!complete) {
             payload.completeNote = `This verdict covers the ${sent.length} of ${total} cached sent messages on this page${freshness.staleness === 'fresh' ? '' : `, from a cache that is "${freshness.staleness}"`}. It is not a statement about every message you have sent.`;
         }
@@ -1236,6 +1288,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (refreshed) {
             payload.autoRefreshed = true;
         }
+        payload.freshness = freshness;
+        payload.unread = unread;
         return jsonResponse(payload);
     });
     if (allowDrafts)

package/dist/tools/pagination.js

@@ -0,0 +1,120 @@
+/**
+ * Pagination state that survives lossy consumption.
+ *
+ * The failure this module exists to prevent: a correct response was ignored.
+ * Three wide date-range reads each returned `complete:false` alongside a `note`
+ * and a `completeNote` spelling out that the page held 60 of 391 and how to get
+ * the rest. The responses were large, so the client spilled them to a JSON file
+ * and a script pulled out `total` and `messages` — dropping every field that
+ * said "this is a slice". The caller then reported October 1-28 as unreachable.
+ *
+ * The tool cannot fix a cherry-picking script. It can stop being easy to
+ * cherry-pick wrongly, which is what these helpers encode:
+ *
+ *  - **State before bulk.** Callers place the paging/freshness keys ahead of the
+ *    data array, so a `head`, a truncated preview, or a partial read reaches
+ *    "this is 60 of 391" before it reaches the first message body. Key order in
+ *    JSON is free — an object literal's insertion order is what JSON.stringify
+ *    emits — so this costs nothing and is pure upside.
+ *  - **The remedy is a value, not an inference.** `complete:false` tells a
+ *    reader something is wrong; `nextPage: 2` tells it what to do. A reader that
+ *    understands neither prose nor booleans can still act on an integer.
+ *  - **The honest count is a scalar, not the array's length.** `returned` sits
+ *    in the header beside `total`, so a consumer never has to reach the array
+ *    to learn how many records came back.
+ */
+/**
+ * Compute paging state for a 1-based `page`/`size` read.
+ *
+ * `hasMore` is decided from the OFFSET, not from `returned < total`: on a page
+ * past the end of the result set, `returned` is 0 while `total` is large, and
+ * comparing those two would advertise a `nextPage` that returns nothing forever.
+ */
+export function pageState(input) {
+    const hasMore = input.page * input.size < input.total;
+    return { hasMore, nextPage: hasMore ? input.page + 1 : null };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Read the paging facts out of an OFW `{data, metadata}` list envelope. */
+function recordArray(root) {
+    // `data` is the envelope both endpoints actually use, so it wins outright.
+    // Falling back to the first array-valued key matters because the alternative
+    // is silently publishing `returned: 0` and a "reaches the end of the list"
+    // note ALONGSIDE real records — the precise shape of lie this file exists to
+    // prevent, reintroduced by a backend rename.
+    if (Array.isArray(root.data))
+        return root.data;
+    for (const value of Object.values(root)) {
+        if (Array.isArray(value))
+            return value;
+    }
+    return null;
+}
+export function readUpstreamPaging(payload) {
+    const root = asRecord(payload);
+    const rows = root === null ? null : recordArray(root);
+    const meta = root === null ? null : asRecord(root.metadata);
+    const total = meta !== null && typeof meta.totalElements === 'number' && Number.isFinite(meta.totalElements)
+        ? meta.totalElements
+        : null;
+    const last = meta !== null && typeof meta.last === 'boolean' ? meta.last : null;
+    return { returned: rows?.length ?? 0, total, last };
+}
+/**
+ * Compute paging state for a `start`/`max` read, best evidence first.
+ *
+ * OFW's own `metadata.last` is authoritative and used whenever present. Failing
+ * that, a reported total settles it. Failing both, a FULL page is treated as
+ * probably-more: the bias is one-directional on purpose, because a `nextStart`
+ * that returns an empty page costs one wasted call, while a null that hides a
+ * further page reproduces the bug this file exists for — a slice narrated as
+ * the whole.
+ */
+export function offsetState(input) {
+    const last = input.last ?? null;
+    const consumed = input.start - input.base + input.returned;
+    const hasMore = last !== null
+        ? !last
+        : input.total !== null
+            ? consumed < input.total
+            : input.returned >= input.max;
+    return { hasMore, nextStart: hasMore ? input.start + input.max : null };
+}
+/**
+ * Prepend paging state to an OFW list envelope, renaming and dropping nothing.
+ *
+ * The upstream object is spread in BEHIND the paging keys, so every key it had
+ * stays exactly where a caller expects to find it — only the order changes.
+ * The head is then spread a SECOND time: a plain `{...head, ...body}` lets an
+ * upstream `hasMore`/`nextStart`/`paginationNote` overwrite the computed value
+ * while keeping the head's key position, which is worse than either — a paging
+ * field sitting in the paging slot, reading as ours, sourced from elsewhere.
+ * Re-spreading restores our values; keys keep their first-insertion position,
+ * so the order is unchanged.
+ * Returns null when the payload is not a plain object and therefore cannot
+ * carry sibling keys at all; the caller then passes it through untouched rather
+ * than relocating it, so this can never change a response's top-level shape.
+ */
+export function withPaginationFirst(input) {
+    const body = asRecord(input.payload);
+    if (body === null)
+        return null;
+    const scope = input.total !== null ? ` of ${input.total}` : '';
+    const head = {
+        hasMore: input.state.hasMore,
+        nextStart: input.state.nextStart,
+        start: input.start,
+        max: input.max,
+        returned: input.returned,
+        ...(input.total !== null ? { total: input.total } : {}),
+        paginationNote: input.state.hasMore
+            ? `PARTIAL: this response holds ${input.returned} record(s) starting at ${input.start}${scope}. `
+                + `${input.hint} Do not state a total or an absence from this response alone.`
+            : `This response reaches the end of the list${scope === '' ? '' : ` (${input.total} record(s) in total)`}.`,
+    };
+    return { ...head, ...body, ...head };
+}