@vantageos/mcp-boilerplate 0.2.4 → 0.3.0

package/dist/exampleItems.js

@@ -1,3 +1,5 @@
+/** Ascending order of the collection key, the order `rangeAfter` binary-searches. */
+const byKey = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 export const EXAMPLE_ITEMS = [
     {
         id: "item-1",
@@ -20,4 +22,29 @@ export const EXAMPLE_ITEMS = [
         createdBy: "org_b",
         namespace: "org_b",
     },
-];
+].sort(byKey);
+/**
+ * The rows strictly after `afterKey` (all rows when it is undefined), at most `limit` of them,
+ * from a collection SORTED by `id`: a binary search for the first key above `afterKey`, then a
+ * slice of the page. That is the `indexed-range` mechanism the list tools declare
+ * (src/toolRecord.ts): the cost follows the page, not the collection. It requires sorted input;
+ * `EXAMPLE_ITEMS` is sorted above and scoping by tenant (a filter) preserves the order.
+ *
+ * In this in-memory seed the tenant scoping that precedes it is a filter over the rows. A fork
+ * backed by a store reads the same range from a compound (orgId, id) index instead.
+ */
+export function rangeAfter(sortedRows, afterKey, limit) {
+    let low = 0;
+    if (afterKey !== undefined) {
+        let high = sortedRows.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            const key = sortedRows[mid]?.id ?? "";
+            if (key <= afterKey)
+                low = mid + 1;
+            else
+                high = mid;
+        }
+    }
+    return sortedRows.slice(low, limit === undefined ? undefined : low + limit);
+}

package/dist/httpApp.d.ts

@@ -25,8 +25,11 @@
 import { Hono } from "hono";
 import { type AuthConfig } from "./auth.js";
 import type { AuthMode } from "./config.js";
+import type { ExampleItem } from "./exampleItems.js";
+import type { LakeReader } from "./lake/reader.js";
 import { type AuthorizationServerDeps } from "./oauth/authorizationServer.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import { type CallerResolution, type IdentityDeps } from "./verifiedPerson.js";
 export interface AppDeps {
     authMode?: AuthMode;
     /** External-issuer resource-server configuration (no authorization server mounted). */
@@ -35,9 +38,23 @@ export interface AppDeps {
     authorizationServer?: AuthorizationServerDeps;
     /** Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). */
     uiDomain?: string;
+    /**
+     * What @vantageos/cloud-identity needs to resolve the caller's verified PERSON
+     * (src/verifiedPerson.ts): the organisation mapping lookups, the principal lookups and the
+     * admin roles (required, non-empty, no default). Injected by the deployment, never built here.
+     * Absent: no person is resolved, and a tool that requires one is refused
+     * (`identity_not_configured`).
+     */
+    identity?: IdentityDeps;
+    /**
+     * The data-lake reader `list_items` reads through (src/lake/reader.ts), read-only by design.
+     * Injected by the deployment like `identity`; absent, the in-memory seed is read.
+     */
+    lake?: LakeReader<ExampleItem>;
 }
 type Variables = {
     tenant?: ResolvedTenant;
+    caller?: CallerResolution;
 };
 export declare function buildHttpApp(deps?: AppDeps): Hono<{
     Variables: Variables;

package/dist/httpApp.js

@@ -26,11 +26,14 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { unauthorizedChallenge } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
+import { getBuildIdentity } from "./buildIdentity.js";
 import { detectLocale, t } from "./i18n.js";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
 import { MCP_SCOPE } from "./oauth/settings.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
+import { assertIdentityDeps, resolveVerifiedPerson, } from "./verifiedPerson.js";
+import { SERVER_VERSION } from "./version.js";
 const PRM_PATHS = [
     "/.well-known/oauth-protected-resource",
     "/.well-known/oauth-protected-resource/mcp",
@@ -38,7 +41,11 @@ const PRM_PATHS = [
 export function buildHttpApp(deps = {}) {
     const app = new Hono();
     const authMode = deps.authMode ?? "public";
-    app.get("/health", (c) => c.json({ status: "ok" }));
+    if (deps.identity)
+        assertIdentityDeps(deps.identity);
+    // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a
+    // deployment is proven from what the server returns, not from what the deploy printed.
+    app.get("/health", (c) => c.json({ status: "ok", version: SERVER_VERSION, buildId: getBuildIdentity() }));
     if (authMode === "oauth") {
         // Resolves the resource-server configuration per request: the own-AS tier reads its
         // environment lazily, so a missing value is a 503 on the request, not a crash at boot.
@@ -110,18 +117,28 @@ export function buildHttpApp(deps = {}) {
             catch {
                 // No organization on this token — tenant stays unset.
             }
+            // The verified person, once per request, from the SAME verified claims, by the package
+            // resolver (verifiedPerson.ts). Not request-fatal either: an unresolved person is stored
+            // as its refusal, and only a tool that requires the person is refused, at the tool call.
+            c.set("caller", await resolveVerifiedPerson(result.session.claims, deps.identity));
             await next();
         });
     }
     // The one real MCP endpoint, both protocol eras (see header comment).
-    app.all("/mcp", (c) => {
+    app.all("/mcp", async (c) => {
         const tenant = authMode === "oauth" ? c.get("tenant") : undefined;
+        // Public tier: no verified session exists, so the person is never resolved there.
+        const caller = authMode === "oauth"
+            ? c.get("caller")
+            : await resolveVerifiedPerson(undefined, deps.identity);
         const locale = detectLocale(c.req.header("X-MCP-Locale"));
         const handler = createMcpHandler(() => createBoilerplateMcpServer({
             tenant,
             requireTenant: authMode === "oauth",
+            caller,
             locale,
             uiDomain: deps.uiDomain,
+            lake: deps.lake,
         }));
         return handler.fetch(c.req.raw);
     });

package/dist/i18n.d.ts

@@ -37,3 +37,13 @@ export declare function detectLocaleFromAcceptLanguage(headerValue: string | nul
  * locale is somehow missing a key the English resource carries.
  */
 export declare function t(locale: McpLocale, key: string): string;
+/** A `tBoth` placeholder value: literal text, or the key of a message translated per language. */
+export type BothParam = string | {
+    key: string;
+};
+/**
+ * A message in BOTH languages in one string ("EN / FR"), with `{name}` placeholders filled. A
+ * placeholder given as `{ key }` is itself translated, in the language being rendered. For
+ * failures raised where no caller locale exists: process start, build and release scripts.
+ */
+export declare function tBoth(key: string, params?: Record<string, BothParam>): string;

package/dist/i18n.js

@@ -67,6 +67,18 @@ export function t(locale, key) {
     const fromEnglish = readPath(RESOURCES.en.Mcp, path);
     return typeof fromEnglish === "string" ? fromEnglish : key;
 }
+/**
+ * A message in BOTH languages in one string ("EN / FR"), with `{name}` placeholders filled. A
+ * placeholder given as `{ key }` is itself translated, in the language being rendered. For
+ * failures raised where no caller locale exists: process start, build and release scripts.
+ */
+export function tBoth(key, params = {}) {
+    const render = (locale) => Object.entries(params).reduce((text, [name, value]) => {
+        const filled = typeof value === "string" ? value : t(locale, value.key);
+        return text.replaceAll(`{${name}}`, filled);
+    }, t(locale, key));
+    return `${render("en")} / ${render("fr")}`;
+}
 function readPath(root, path) {
     let node = root;
     for (const segment of path) {

package/dist/index.d.ts

@@ -1,2 +1,14 @@
+export { ConfigurationError, VARIABLE_TYPES, VariableDeclarationError, defineVariables, describeVariables, loadVariables, } from "./declaredVariables.js";
+export type { BilingualText, BooleanVariable, ConfigurationProblem, DeclaredVariables, EnumVariable, IntegerVariable, JsonContainer, JsonVariable, OriginListVariable, ProblemReason, StringVariable, UrlVariable, VariableDescription, VariableSpec, VariableType, VariablesOf, VariablesSpec, } from "./declaredVariables.js";
 export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+export { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, checkLakePage, createInMemoryLakeReader, } from "./lake/reader.js";
+export type { LakePage, LakePageRequest, LakeReadErrorCode, LakeReader, LakeScope, } from "./lake/reader.js";
+export { readPage } from "./pagination.js";
 export { buildHttpApp } from "./httpApp.js";
+export type { AppDeps } from "./httpApp.js";
+export { PERSON_UNRESOLVED_CODE, resolveVerifiedPerson, withVerifiedPerson, } from "./verifiedPerson.js";
+export type { CallerResolution, IdentityDeps, PersonUnresolvedReason, VerifiedPerson, } from "./verifiedPerson.js";
+export { UpstreamTokenError, clientCredentialsFromEnv, createClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";
+export type { ClientAuthMethod, ClientCredentialsEnvOptions, ClientCredentialsEnvVars, ClientCredentialsOptions, ClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";
+export { UpstreamPageError, createPaginatedUpstreamClient } from "./upstream/paginatedClient.js";
+export type { FetchLike, PaginatedUpstreamClient, PaginatedUpstreamOptions, PaginationPlacement, ParamObject, ParamValue, UpstreamPage, UpstreamPageErrorCode, UpstreamParams, } from "./upstream/paginatedClient.js";

package/dist/index.js

@@ -1,2 +1,8 @@
+export { ConfigurationError, VARIABLE_TYPES, VariableDeclarationError, defineVariables, describeVariables, loadVariables, } from "./declaredVariables.js";
 export { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+export { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, checkLakePage, createInMemoryLakeReader, } from "./lake/reader.js";
+export { readPage } from "./pagination.js";
 export { buildHttpApp } from "./httpApp.js";
+export { PERSON_UNRESOLVED_CODE, resolveVerifiedPerson, withVerifiedPerson, } from "./verifiedPerson.js";
+export { UpstreamTokenError, clientCredentialsFromEnv, createClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";
+export { UpstreamPageError, createPaginatedUpstreamClient } from "./upstream/paginatedClient.js";

package/dist/lake/convex.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Convex adapter of the data-lake reader (src/lake/reader.ts), served at its own subpath:
+ *
+ * ```ts
+ * import { convexLakeReaderFromEnv } from "@vantageos/mcp-boilerplate/lake/convex";
+ *
+ * const lake = convexLakeReaderFromEnv(
+ *   process.env,
+ *   { urlVar: "LAKE_URL", tokenVar: "LAKE_READ_KEY" },
+ *   {
+ *     functions: { page: "lakeRead:listRows", get: "lakeRead:getRow" },
+ *     keyField: "rowKey",
+ *     tokenArg: "readKey",
+ *   }
+ * );
+ * buildHttpApp({ ..., lake });
+ * ```
+ *
+ * The variable names, the function names and the key field above are examples: they are
+ * CONFIGURATION, chosen by the derived server; nothing here names a table, a function or a client.
+ * `convex` is an OPTIONAL peer dependency: only a server importing this subpath needs it.
+ *
+ * READ-ONLY. The adapter calls `ConvexHttpClient.query` and nothing else — never `mutation`,
+ * `action`, `function` or `consistentQuery` (tests/lakeReader.test.ts holds all five as spies). The
+ * client type it accepts (`ConvexLakeQueryClient`) has no write method.
+ *
+ * THE QUERY FUNCTIONS the derived server writes (Convex side), and their arguments:
+ *   - page `{ after?: string, limit: number, tenantId?: string }` -> an array of at most `limit`
+ *     rows whose key field is strictly after `after`, ascending by that key. The adapter asks for
+ *     ONE row more than the page: its presence tells a truncated page from an exhausted one.
+ *     `tenantId` is present only on a scoped read; the function applies it in its index range.
+ *   - get `{ key: string, tenantId?: string }` -> the row with that key, or null.
+ *   With `tokenArg`, every call also carries the read token under that argument name, for a
+ *   function that checks a shared read key. Without it, the token goes through `setAuth`
+ *   (`Authorization: Bearer`, which Convex reads as an identity JWT from a configured provider).
+ *
+ * FAIL CLOSED. An answer that is not a list, a row that is not an object or has no non-empty
+ * string key, more rows than asked, keys out of order or not after the cursor, a `get` row with
+ * another key, a row the derived server's `parseRow` refuses: each is a `LakeReadError`, never an
+ * empty page. A failing call is `read_failed`, and the client's message is NOT forwarded (it can
+ * carry the deployment URL or a credential); no `cause` is attached either. No error carries the
+ * token, a row value, or the URL.
+ *
+ * CONNECTION VARIABLES are declared with `defineVariables` (src/declaredVariables.ts): the
+ * deployment URL (`url`: https, or http on loopback only) and, when a token variable is named, the
+ * token (`secret: true`, required once named). A missing or invalid variable is ONE
+ * `ConfigurationError` at start, naming every variable, never a value.
+ */
+import { type FunctionReference } from "convex/server";
+import { type LakeReader } from "./reader.js";
+/** The names of the two Convex query functions to call, e.g. `"module:function"`. */
+export interface ConvexLakeFunctions {
+    readonly page: string;
+    readonly get: string;
+}
+/** The only client surface the adapter uses. It has no write method, by design. */
+export interface ConvexLakeQueryClient {
+    query(fn: FunctionReference<"query">, args: Record<string, unknown>): Promise<unknown>;
+    setAuth(token: string): void;
+}
+type RawRow = Readonly<Record<string, unknown>>;
+export interface ConvexLakeReaderOptions<Row = RawRow> {
+    /** The deployment URL: https, or http on a loopback host. No query, fragment or credentials. */
+    readonly url: string;
+    /** The read token. Sent through `setAuth`, or as the `tokenArg` argument when one is named. */
+    readonly token?: string;
+    /** The argument name the token travels under, for a function checking a shared read key. */
+    readonly tokenArg?: string;
+    readonly functions: ConvexLakeFunctions;
+    /** The row field holding the stable key pages are ordered by. Configuration, no default. */
+    readonly keyField: string;
+    /**
+     * Validates and types one raw row (e.g. a Zod `parse`). It must keep `keyField`. Throwing
+     * refuses the row (`malformed_row`); its message is not forwarded. Absent, the row is served as
+     * the store returned it, with only its key checked.
+     */
+    readonly parseRow?: (raw: RawRow) => Row;
+    /** A client to use instead of a `ConvexHttpClient` (a custom transport, a test double). */
+    readonly client?: ConvexLakeQueryClient;
+    /** A fetch implementation passed to the `ConvexHttpClient` built when `client` is absent. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * A read-only lake reader over a Convex deployment. Throws on an unreadable configuration (the
+ * message names the option, never its value).
+ */
+export declare function createConvexLakeReader<Row = RawRow>(options: ConvexLakeReaderOptions<Row>): LakeReader<Row>;
+/** Which environment variables hold the connection. The derived server names them. */
+export interface ConvexLakeEnvVars {
+    /** The deployment URL variable. Required. */
+    readonly urlVar: string;
+    /** The read token variable. Optional; once named, the variable is required. */
+    readonly tokenVar?: string;
+}
+/**
+ * Reads the connection from the variables the derived server names, declared with
+ * `defineVariables`, then builds the reader. Throws ONE `ConfigurationError` naming every missing
+ * or invalid variable (never a value) before any client is built.
+ */
+export declare function convexLakeReaderFromEnv<Row = RawRow>(env: NodeJS.ProcessEnv, names: ConvexLakeEnvVars, options: Omit<ConvexLakeReaderOptions<Row>, "url" | "token">): LakeReader<Row>;
+export {};

package/dist/lake/convex.js

@@ -0,0 +1,224 @@
+/**
+ * Convex adapter of the data-lake reader (src/lake/reader.ts), served at its own subpath:
+ *
+ * ```ts
+ * import { convexLakeReaderFromEnv } from "@vantageos/mcp-boilerplate/lake/convex";
+ *
+ * const lake = convexLakeReaderFromEnv(
+ *   process.env,
+ *   { urlVar: "LAKE_URL", tokenVar: "LAKE_READ_KEY" },
+ *   {
+ *     functions: { page: "lakeRead:listRows", get: "lakeRead:getRow" },
+ *     keyField: "rowKey",
+ *     tokenArg: "readKey",
+ *   }
+ * );
+ * buildHttpApp({ ..., lake });
+ * ```
+ *
+ * The variable names, the function names and the key field above are examples: they are
+ * CONFIGURATION, chosen by the derived server; nothing here names a table, a function or a client.
+ * `convex` is an OPTIONAL peer dependency: only a server importing this subpath needs it.
+ *
+ * READ-ONLY. The adapter calls `ConvexHttpClient.query` and nothing else — never `mutation`,
+ * `action`, `function` or `consistentQuery` (tests/lakeReader.test.ts holds all five as spies). The
+ * client type it accepts (`ConvexLakeQueryClient`) has no write method.
+ *
+ * THE QUERY FUNCTIONS the derived server writes (Convex side), and their arguments:
+ *   - page `{ after?: string, limit: number, tenantId?: string }` -> an array of at most `limit`
+ *     rows whose key field is strictly after `after`, ascending by that key. The adapter asks for
+ *     ONE row more than the page: its presence tells a truncated page from an exhausted one.
+ *     `tenantId` is present only on a scoped read; the function applies it in its index range.
+ *   - get `{ key: string, tenantId?: string }` -> the row with that key, or null.
+ *   With `tokenArg`, every call also carries the read token under that argument name, for a
+ *   function that checks a shared read key. Without it, the token goes through `setAuth`
+ *   (`Authorization: Bearer`, which Convex reads as an identity JWT from a configured provider).
+ *
+ * FAIL CLOSED. An answer that is not a list, a row that is not an object or has no non-empty
+ * string key, more rows than asked, keys out of order or not after the cursor, a `get` row with
+ * another key, a row the derived server's `parseRow` refuses: each is a `LakeReadError`, never an
+ * empty page. A failing call is `read_failed`, and the client's message is NOT forwarded (it can
+ * carry the deployment URL or a credential); no `cause` is attached either. No error carries the
+ * token, a row value, or the URL.
+ *
+ * CONNECTION VARIABLES are declared with `defineVariables` (src/declaredVariables.ts): the
+ * deployment URL (`url`: https, or http on loopback only) and, when a token variable is named, the
+ * token (`secret: true`, required once named). A missing or invalid variable is ONE
+ * `ConfigurationError` at start, naming every variable, never a value.
+ */
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { defineVariables, isSecureUrl, loadVariables } from "../declaredVariables.js";
+import { LakeReadError, assertOrderedKeys } from "./reader.js";
+const ARGUMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function configurationError(message) {
+    return new Error(`convex lake reader: ${message}`);
+}
+/** Refuses an unreadable configuration. Messages name the option, never its value. */
+function checkOptions(options) {
+    if (typeof options.url !== "string" || !isSecureUrl(options.url)) {
+        throw configurationError("url must be https, or http on a loopback host (value not shown)");
+    }
+    const url = new URL(options.url);
+    if (url.search !== "" || url.hash !== "" || url.username !== "" || url.password !== "") {
+        throw configurationError("url must carry no query, fragment or credentials: the token travels apart (value not shown)");
+    }
+    for (const [role, name] of [
+        ["functions.page", options.functions?.page],
+        ["functions.get", options.functions?.get],
+    ]) {
+        if (typeof name !== "string" || name.trim() === "" || /\s/.test(name)) {
+            throw configurationError(`${role} must be a Convex function name such as "module:function"`);
+        }
+    }
+    if (typeof options.keyField !== "string" || options.keyField === "") {
+        throw configurationError("keyField must be a non-empty field name");
+    }
+    if (options.token !== undefined && (typeof options.token !== "string" || options.token === "")) {
+        throw configurationError("token, when given, must be a non-empty string (value not shown)");
+    }
+    if (options.tokenArg !== undefined) {
+        if (typeof options.tokenArg !== "string" || !ARGUMENT_NAME.test(options.tokenArg)) {
+            throw configurationError("tokenArg must be an argument name ([A-Za-z_][A-Za-z0-9_]*)");
+        }
+        if (options.token === undefined)
+            throw configurationError("tokenArg is named but no token");
+        if (["after", "limit", "tenantId", "key"].includes(options.tokenArg)) {
+            throw configurationError("tokenArg collides with an argument the adapter sends");
+        }
+    }
+    // ConvexHttpClient appends `/api/...` to the address as given.
+    return options.url.replace(/\/+$/, "");
+}
+/** A ConvexHttpClient seen through the read-only surface. Its constructor errors name the URL. */
+function httpClient(url, fetchImpl) {
+    let http;
+    try {
+        http = new ConvexHttpClient(url, { logger: false, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
+    }
+    catch {
+        throw configurationError("the Convex client refused the deployment url (value not shown)");
+    }
+    return {
+        query: (fn, args) => http.query(fn, args),
+        setAuth: (token) => http.setAuth(token),
+    };
+}
+function isRawRow(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A read-only lake reader over a Convex deployment. Throws on an unreadable configuration (the
+ * message names the option, never its value).
+ */
+export function createConvexLakeReader(options) {
+    const url = checkOptions(options);
+    const { functions, keyField, token, tokenArg, parseRow } = options;
+    const client = options.client ?? httpClient(url, options.fetch);
+    if (token !== undefined && tokenArg === undefined)
+        client.setAuth(token);
+    const refs = {
+        page: makeFunctionReference(functions.page),
+        get: makeFunctionReference(functions.get),
+    };
+    // The token as an argument, built per call so it is held only in this closure.
+    const withToken = (args) => tokenArg !== undefined && token !== undefined ? { ...args, [tokenArg]: token } : args;
+    const scoped = (scope) => scope === undefined ? {} : { tenantId: scope.tenantId };
+    const call = async (which, args) => {
+        try {
+            return await client.query(refs[which], withToken(args));
+        }
+        catch (error) {
+            // The client's message is dropped: it can carry the URL or a credential.
+            const kind = error instanceof Error ? ` (${error.name})` : "";
+            throw new LakeReadError("read_failed", `query ${functions[which]} failed${kind}`);
+        }
+    };
+    // One raw row -> its key and the served row. Messages name the function and the key field only.
+    const readRow = (raw, fn) => {
+        if (!isRawRow(raw))
+            throw new LakeReadError("malformed_row", `${fn} returned a non-object row`);
+        const key = raw[keyField];
+        if (typeof key !== "string" || key === "") {
+            throw new LakeReadError("malformed_row", `${fn} returned a row whose "${keyField}" is not a non-empty string`);
+        }
+        if (parseRow === undefined)
+            return { key, row: raw };
+        let row;
+        try {
+            row = parseRow(raw);
+        }
+        catch {
+            throw new LakeReadError("malformed_row", `${fn} returned a row the row parser refused`);
+        }
+        if (!isRawRow(row) || row[keyField] !== key) {
+            throw new LakeReadError("malformed_row", `the row parser did not keep "${keyField}"`);
+        }
+        return { key, row };
+    };
+    const reader = {
+        keyOf(row) {
+            const key = isRawRow(row) ? row[keyField] : undefined;
+            if (typeof key !== "string" || key === "") {
+                throw new LakeReadError("malformed_row", `a row has no "${keyField}" key`);
+            }
+            return key;
+        },
+        async listPage({ after, limit, scope }) {
+            const asked = limit + 1;
+            const raw = await call("page", {
+                ...(after === undefined ? {} : { after }),
+                limit: asked,
+                ...scoped(scope),
+            });
+            if (!Array.isArray(raw)) {
+                throw new LakeReadError("malformed_page", `${functions.page} did not return a list`);
+            }
+            if (raw.length > asked) {
+                throw new LakeReadError("malformed_page", `${functions.page} returned more rows than asked`);
+            }
+            const read = raw.map((r) => readRow(r, functions.page));
+            assertOrderedKeys(read.map((r) => r.key), after);
+            return {
+                rows: read.slice(0, limit).map((r) => r.row),
+                exhausted: read.length <= limit,
+            };
+        },
+        async get(key, scope) {
+            const raw = await call("get", { key, ...scoped(scope) });
+            if (raw === null || raw === undefined)
+                return undefined;
+            const read = readRow(raw, functions.get);
+            if (read.key !== key) {
+                throw new LakeReadError("malformed_row", `${functions.get} returned a row with another key`);
+            }
+            return read.row;
+        },
+    };
+    return Object.freeze(reader);
+}
+const URL_DESCRIPTION = {
+    en: "Convex deployment URL of the data lake (https, or http on a loopback host)",
+    fr: "URL du déploiement Convex du data-lake (https, ou http sur une adresse de bouclage)",
+};
+const TOKEN_DESCRIPTION = {
+    en: "Read token of the data lake",
+    fr: "Jeton de lecture du data-lake",
+};
+/**
+ * Reads the connection from the variables the derived server names, declared with
+ * `defineVariables`, then builds the reader. Throws ONE `ConfigurationError` naming every missing
+ * or invalid variable (never a value) before any client is built.
+ */
+export function convexLakeReaderFromEnv(env, names, options) {
+    const url = { env: names.urlVar, type: "url", description: URL_DESCRIPTION };
+    if (names.tokenVar === undefined) {
+        const settings = loadVariables(defineVariables({ url }), env);
+        return createConvexLakeReader({ ...options, url: settings.url });
+    }
+    const settings = loadVariables(defineVariables({
+        url,
+        token: { env: names.tokenVar, type: "string", secret: true, description: TOKEN_DESCRIPTION },
+    }), env);
+    return createConvexLakeReader({ ...options, url: settings.url, token: settings.token });
+}

package/dist/lake/reader.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Data-lake reader: the READ-ONLY interface through which a server derived from this boilerplate
+ * reads its client's data lake (the single persisted source). The tools never know which store is
+ * behind it; the store is chosen by injection (`AppDeps.lake` / `McpServerDeps.lake`).
+ *
+ * The contract mirrors the cursor contract of src/pagination.ts:
+ *   - rows are keyed by a STABLE, non-empty string key (`keyOf`), served in strictly ascending key
+ *     order, so the last key served is the cursor;
+ *   - `listPage({ after, limit, scope })` returns at most `limit` rows whose key is strictly after
+ *     `after` (all rows when it is undefined), and `exhausted: true` exactly when no row follows
+ *     them (an exact fit is exhausted, never a false truncation); a truncated page has at least one
+ *     row;
+ *   - `scope` (the caller's resolved tenant) is applied INSIDE the range read — a compound
+ *     (tenant, key) index — never as a filter after the limit, which would shorten a page and make
+ *     its cursor lie;
+ *   - `get(key, scope)` returns the row with that key, or undefined.
+ *
+ * What a derived server adds: its own filters (a status, a date window, a person's portfolio) as
+ * arguments of its own adapter or query functions, and its own row type. What is out of scope, by
+ * design: writes. The interface has no write method, and the Convex adapter (src/lake/convex.ts)
+ * only ever calls queries.
+ *
+ * Fail closed: `readPage` (src/pagination.ts) checks every page against this contract with
+ * `checkLakePage`; a page it cannot read is a `LakeReadError`, never an empty or partial page.
+ * Its message names the contract clause broken, never a row value.
+ *
+ * The in-memory adapter below wraps the boilerplate's seed (src/exampleItems.ts) and is the
+ * default reader, so a server with no lake injected behaves exactly as before.
+ */
+import { type ExampleItem } from "../exampleItems.js";
+import { type TenantOwned } from "../tenancy.js";
+/** The caller's resolved tenant, applied inside the range read. */
+export interface LakeScope {
+    readonly tenantId: string;
+}
+export interface LakePageRequest {
+    /** The last key already served; omitted for the first page. */
+    readonly after?: string;
+    /** At most this many rows. A positive integer, already bounded by the tool. */
+    readonly limit: number;
+    readonly scope?: LakeScope;
+}
+export interface LakePage<Row> {
+    readonly rows: readonly Row[];
+    /** True exactly when no row follows the ones returned. */
+    readonly exhausted: boolean;
+}
+/** Read-only by design: there is no write method. */
+export interface LakeReader<Row> {
+    /** The row's stable key, the one pages are ordered by and cursors carry. */
+    keyOf(row: Row): string;
+    listPage(request: LakePageRequest): Promise<LakePage<Row>>;
+    get(key: string, scope?: LakeScope): Promise<Row | undefined>;
+}
+/**
+ * Every way a read can fail:
+ *  - `malformed_page`: the page breaks the contract (not a list, more rows than asked, keys out of
+ *    order or not after the cursor, a truncated page with no row);
+ *  - `malformed_row`: a row has no readable key, or the derived server's row parser refused it;
+ *  - `out_of_scope`: a row of another tenant came back from a scoped read;
+ *  - `read_failed`: the store call itself failed (its message is not forwarded: it may carry a
+ *    URL or a credential).
+ */
+export type LakeReadErrorCode = "malformed_page" | "malformed_row" | "out_of_scope" | "read_failed";
+/** The stable machine code of a tool result refused because the lake answer was unreadable. */
+export declare const LAKE_UNREADABLE_CODE = "lake_unreadable";
+export declare class LakeReadError extends Error {
+    readonly code: LakeReadErrorCode;
+    constructor(code: LakeReadErrorCode, message: string);
+}
+/**
+ * Checks that `keys` are strictly ascending and all strictly after `after`. Shared by
+ * `checkLakePage` and by adapters that read a raw answer.
+ */
+export declare function assertOrderedKeys(keys: readonly string[], after: string | undefined): void;
+/** Checks a page against the contract above; returns it, or throws a `LakeReadError`. */
+export declare function checkLakePage<Row>(reader: Pick<LakeReader<Row>, "keyOf">, request: LakePageRequest, page: unknown): LakePage<Row>;
+/**
+ * An in-memory reader over rows SORTED strictly ascending by `id` (refused otherwise, at
+ * creation: the range read relies on the order). The scope keeps the rows stamped with the
+ * caller's organisation (tenancy.ts `scopeRowsForTenant`) BEFORE the range, so a page is never
+ * shortened afterwards. A store-backed reader reads the same range from a (tenant, key) index.
+ */
+export declare function createInMemoryLakeReader<Row extends {
+    id: string;
+} & TenantOwned>(sortedRows: readonly Row[]): LakeReader<Row>;
+/** The default reader behind `list_items`: the in-memory seed. */
+export declare const EXAMPLE_ITEMS_READER: LakeReader<ExampleItem>;