@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/kernel/driver/postgres.js

@@ -0,0 +1,98 @@
+import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { context, guard } from "./transaction-context.js";
+const transactions = new WeakSet();
+const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
+export const read = (db, sql, binds) => { guard(db); return db.unsafe(sql, binds); };
+export async function run(db, sql, binds) {
+    const rows = await read(db, sql, binds);
+    return { rows, changes: Number(rows.count ?? 0) };
+}
+/** SQLSTATE of a server error: `errno` on Bun.SQL, `code` on postgres.js. */
+const sqlstate = (error) => { const e = error; return typeof e?.errno === "string" ? e.errno : e?.code; };
+/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+export function definitive(error) {
+    if (error instanceof ContractError)
+        return error.code === "CONFLICT";
+    const state = sqlstate(error);
+    return typeof state === "string" && /^[0-9A-Z]{5}$/.test(state) && typeof error?.severity === "string" && !/^(08|28|53|57|58|XX)/.test(state);
+}
+/**
+ * The error to throw when a PostgreSQL write fails where it may already have committed (autocommit, or COMMIT).
+ * A server ErrorResponse (SQLSTATE + severity) outside connection/resource classes rolled back; anything else, such as a
+ * lost socket, is OUTCOME_UNKNOWN.
+ */
+export function postgresOutcome(error, path) {
+    if (definitive(error))
+        return error;
+    return new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile before retrying.", path, { cause: error });
+}
+/**
+ * One statement is atomic on its own (a row statement touches at most one row, so a failed count check changes nothing)
+ * and runs in autocommit. Several run in `begin(serializable)`: a failure before the callback returns was rolled back;
+ * only a failed COMMIT can leave the outcome unknown.
+ */
+export async function procedure(db, steps, path) {
+    const execute = async (handle) => {
+        const results = [];
+        for (const s of steps) {
+            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : checkConflict(path, error, sqlstate(error) === "23514") ?? error; });
+            if (s.row && changes !== 1)
+                throw conflict(path, false);
+            results.push(rows);
+        }
+        return results;
+    };
+    if (transactions.has(db))
+        return execute(db);
+    if (steps.length === 1) {
+        try {
+            return await execute(db);
+        }
+        catch (error) {
+            throw error instanceof ContractError ? error : postgresOutcome(error, path);
+        }
+    }
+    return transaction(db, execute, undefined, path);
+}
+/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
+export async function transaction(db, fn, options = {}, path = "store/transaction") {
+    guard(db);
+    if (transactions.has(db))
+        throw new Error("Nested transactions are not supported.");
+    // a transaction handle the app opened (postgres.js types it without `begin`) only suits reads and single statements
+    if (typeof db.begin !== "function")
+        throw new Error("This PostgreSQL handle is a transaction the app opened and cannot begin another: open the transaction with store(pool, caller).transaction and call Procedures through its tx.");
+    let committing = false;
+    const state = { outer: db };
+    try {
+        // printed into BEGIN, so only PostgreSQL's own four levels: a handler may pass request input here
+        const level = options.isolation ?? "serializable";
+        if (!ISOLATION.includes(level))
+            throw new ContractError("INPUT_VALIDATION_FAILED", `isolation '${level}' is not a PostgreSQL isolation level`, path);
+        return await db.begin(`isolation level ${level}`, async (handle) => {
+            let active = true;
+            const tx = { unsafe: (sql, values) => {
+                    if (!active)
+                        throw new Error("Transaction has ended.");
+                    return handle.unsafe(sql, values);
+                }, begin: async () => { throw new Error("Nested transactions are not supported."); } };
+            transactions.add(tx);
+            state.handle = tx;
+            try {
+                const result = await context.run(state, () => fn(tx));
+                committing = true;
+                return result;
+            }
+            finally {
+                active = false;
+            }
+        });
+    }
+    catch (error) {
+        throw error instanceof ContractError || !committing ? error : postgresOutcome(error, path);
+    }
+    finally {
+        state.outer = undefined;
+        state.handle = undefined;
+    }
+}

package/dist/kernel/driver/transaction-context.d.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const context: AsyncLocalStorage<{
+    outer?: object;
+    handle?: object;
+    changes?: Map<string, number>;
+    parents?: Map<string, number>;
+}>;
+export declare function guard(db: object): void;
+/** One atomic write cannot publish a translation and change its parent's status. */
+export declare function translationWrite(db: object, schema: string, parent?: string): () => void;

package/dist/kernel/driver/transaction-context.js

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ContractError } from "../contracts.js";
+export const context = new AsyncLocalStorage();
+export function guard(db) {
+    if (context.getStore()?.outer === db)
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Inside store.transaction use tx, not the outer store or handle.", "store/transaction");
+}
+/** One atomic write cannot publish a translation and change its parent's status. */
+export function translationWrite(db, schema, parent) {
+    const state = context.getStore();
+    if (!state || state.handle !== db)
+        return () => { };
+    schema = schema.toLowerCase();
+    parent = parent?.toLowerCase();
+    if (state.parents?.has(schema) || parent && state.changes?.has(parent))
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Publish the translation and change its parent status in separate writes.", "translations");
+    const changes = state.changes ??= new Map(), parents = state.parents ??= new Map();
+    changes.set(schema, (changes.get(schema) ?? 0) + 1);
+    if (parent)
+        parents.set(parent, (parents.get(parent) ?? 0) + 1);
+    return () => { for (const [map, key] of [[changes, schema], [parents, parent]])
+        if (key) {
+            const count = map.get(key) - 1;
+            if (count)
+                map.set(key, count);
+            else
+                map.delete(key);
+        } };
+}

package/dist/kernel/email.d.ts

@@ -0,0 +1,28 @@
+/** The transactional-email port (Better Auth email OTP and magic link, admin invitations). The sender decides how to branch on `locale`; `category` names the template lane. */
+export interface EmailSender {
+    send(args: EmailSendArgs): Promise<void>;
+}
+export interface EmailSendArgs {
+    readonly to: string;
+    readonly subject: string;
+    /** Plain-text body — always required so non-HTML clients work. */
+    readonly text: string;
+    /** Optional HTML body. */
+    readonly html?: string;
+    /** BCP 47 locale the recipient is expected to read. */
+    readonly locale: string;
+    /** Optional categorization for templating / deliverability segmentation. */
+    readonly category?: string;
+}
+type EmailContent = Pick<EmailSendArgs, "subject" | "text">;
+export declare function signInCodeEmail(code: string): EmailContent;
+export declare function signInLinkEmail(url: string): EmailContent;
+export declare function adminInvitationEmail(role: string, signInUrl: string): EmailContent;
+/**
+ * Local development only: logs recipients and sign-in secrets, sends nothing.
+ * Select at the application's environment boundary; never use in production.
+ */
+export declare class ConsoleEmailSender implements EmailSender {
+    send(args: EmailSendArgs): Promise<void>;
+}
+export {};

package/dist/{auth/emailTemplates.js → kernel/email.js}

@@ -17,11 +17,22 @@ export function signInLinkEmail(url) {
         "The link expires shortly.",
     ]);
 }
-export function staffInvitationEmail(role, signInUrl) {
+export function adminInvitationEmail(role, signInUrl) {
     return englishEmail("You have been invited to Mantle", [
         `You now have ${role} access to Mantle.`,
         "Sign in with this email address to accept the invitation:",
         signInUrl,
     ]);
 }
-//# sourceMappingURL=emailTemplates.js.map
+/**
+ * Local development only: logs recipients and sign-in secrets, sends nothing.
+ * Select at the application's environment boundary; never use in production.
+ */
+export class ConsoleEmailSender {
+    async send(args) {
+        const { to, subject, text, locale, category } = args;
+        console.log(`[ConsoleEmailSender] ${category ?? "email"} → ${to} (${locale})\n` +
+            `  subject: ${subject}\n` +
+            `  body: ${text}`);
+    }
+}

package/dist/kernel/host-access.d.ts

@@ -0,0 +1,10 @@
+/** Request-only gateway decisions and observation; no database or compiler dependencies. */
+import { type AccessEvent, type Caller, type GatewayOptions, type RequestContext } from "./contracts.js";
+export declare function accessRequest(ctx: RequestContext | undefined, options: GatewayOptions): {
+    readonly dryRun: boolean;
+    select(target: string, resolved?: Caller): Promise<void>;
+    check(readOnly: boolean, variant?: string): Promise<void>;
+    finish(error?: unknown): AccessEvent;
+    finishResponse(response: Response): Promise<AccessEvent>;
+    response(): Response;
+};

package/dist/kernel/host-access.js

@@ -0,0 +1,65 @@
+/** Request-only gateway decisions and observation; no database or compiler dependencies. */
+import { forwarded, ContractError, wire } from "./contracts.js";
+import { isHostCaller, checkFresh } from "./caller-identity.js";
+const logged = new WeakSet();
+export function accessRequest(ctx, options) {
+    const present = forwarded(ctx);
+    const props = ctx?.props?.mantle;
+    let caller, id = "", meta, finished;
+    let targets;
+    const fail = (code, status, field) => { throw new ContractError(code, code, id, { status, fields: field ? { field } : undefined }); };
+    return {
+        get dryRun() { return !!caller && isHostCaller(caller) && "dryRun" in caller && caller.dryRun === true; },
+        async select(target, resolved) {
+            id = target;
+            caller = resolved;
+            const all = await (targets ??= options.accessTargets?.());
+            meta = all && Object.hasOwn(all, id) ? all[id] : undefined;
+        },
+        async check(readOnly, variant) {
+            if (!caller || !isHostCaller(caller))
+                return;
+            const c = caller;
+            if (c.target !== undefined && c.target !== id)
+                fail("TARGET_MISMATCH", 412);
+            if (c.targetHash !== undefined && (!meta || c.targetHash !== meta.targetHash))
+                fail("TARGET_HASH_MISMATCH", 412);
+            checkFresh(caller, readOnly, id);
+            const policy = variant ? meta?.variants?.find(v => v.id === variant) ?? meta : meta;
+            if (this.dryRun && (!policy || policy.opaque || policy.guard))
+                fail("DRY_RUN_UNSUPPORTED", 412);
+        },
+        finish(error) {
+            if (finished)
+                return finished;
+            const failure = error === undefined ? undefined : wire(error);
+            finished = { v: 1, requestId: caller && "requestId" in caller ? caller.requestId ?? "" : typeof props?.requestId === "string" ? props.requestId : "", target: id, targetHash: meta?.targetHash ?? "",
+                caller: { kind: caller?.kind ?? (props?.layer === "member" ? "user" : "host"), subject: caller && "subject" in caller ? caller.subject : typeof props?.user === "object" && props.user && typeof props.user.id === "string" ? (props.layer === "admin" ? "host:" : "") + props.user.id : "", layer: caller && isHostCaller(caller) ? caller.kind === "host" ? "admin" : "member" : props?.layer === "member" ? "member" : "admin" },
+                outcome: failure ? [401, 403].includes(failure.status) ? "deny" : "error" : "allow", ...(failure ? { reason: failure.status === 401 ? "AUTH_DENIED" : failure.error.code, ...(typeof failure.error.field === "string" ? { field: failure.error.field } : {}) } : {}), dryRun: caller && isHostCaller(caller) ? this.dryRun : props?.dryRun === true };
+            finished = Object.freeze({ ...finished, caller: Object.freeze(finished.caller) });
+            if (present && options.onAccess) {
+                const listener = options.onAccess;
+                const log = () => { if (!logged.has(listener)) {
+                    logged.add(listener);
+                    console.error("[mantle onAccess] listener failed");
+                } };
+                // Schedule observation after the decision without awaiting its promise.
+                queueMicrotask(() => { try {
+                    void Promise.resolve(listener(finished)).catch(log);
+                }
+                catch {
+                    log();
+                } });
+            }
+            return finished;
+        },
+        async finishResponse(response) {
+            if (response.status < 400)
+                return this.finish();
+            const payload = await response.clone().json().catch(() => null);
+            const code = typeof payload?.error?.code === "string" ? payload.error.code : [401, 403].includes(response.status) ? "AUTH_DENIED" : response.status < 500 ? "INPUT_VALIDATION_FAILED" : "INTERNAL_ERROR";
+            return this.finish(new ContractError(code, "", id, { status: response.status, fields: payload?.error?.field ? { field: payload.error.field } : undefined }));
+        },
+        response() { return Response.json({ dryRun: true, event: this.finish() }, { headers: { "cache-control": "private, no-store" } }); },
+    };
+}

package/dist/kernel/host-caller.d.ts

@@ -0,0 +1,39 @@
+/** Request-only host contract validation. */
+export { draining } from "./drain.js";
+import { type Caller, type Gateway, type RequestContext } from "./contracts.js";
+import type { UserFields, UserValue } from "./user-fields.js";
+/** The complete JSON supplied as ctx.props.mantle by a trusted gateway. */
+export interface HostProps {
+    readonly v: 1;
+    readonly tenant: string;
+    readonly layer: "admin" | "member";
+    readonly user: Readonly<Record<string, UserValue>> & {
+        readonly id: string;
+        readonly role?: string;
+    };
+    readonly authenticatedAs: "snapshot" | "fresh";
+    readonly credential: "session" | "oauth";
+    readonly requestId: string;
+    /** Forwarded target pinning. */
+    readonly target?: string;
+    readonly targetHash?: string;
+    readonly dryRun?: boolean;
+}
+export type HostCaller = Extract<Caller, {
+    kind: "user" | "host";
+}> & {
+    readonly authenticatedAs: HostProps["authenticatedAs"];
+    readonly credential: HostProps["credential"];
+    readonly requestId: string;
+};
+/** Validate the forwarding contract and reuse the ordinary user validation and brand. */
+export declare function hostCaller(props: unknown, options: {
+    readonly tenant: string;
+    readonly fields?: UserFields;
+}): HostCaller;
+/** Resolve only forwarded props, or trip on an entry that did not opt in. */
+export declare function gatewayCaller(ctx: RequestContext | undefined, gateway: Gateway | undefined, fields?: UserFields): Caller;
+/** Host errors are machine-readable and never challenge for application credentials. */
+export declare function hostFailure(error: unknown, caller?: Caller, where?: string, challenge?: string): Response;
+export { isHostCaller } from "./caller-identity.js";
+export { checkFresh } from "./caller-identity.js";

package/dist/kernel/host-caller.js

@@ -0,0 +1,56 @@
+/** Request-only host contract validation. */
+export { draining } from "./drain.js";
+import { forwarded, ContractError, surfaceError, surfaceFailure } from "./contracts.js";
+import { userCaller } from "./user-caller.js";
+import { identities, isHostCaller } from "./caller-identity.js";
+const hostContract = (message, field) => { throw new ContractError("HOST_CONTRACT", message, "", { status: 412, fields: field ? { field } : undefined }); };
+/** Validate the forwarding contract and reuse the ordinary user validation and brand. */
+export function hostCaller(props, options) {
+    const record = (v) => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+    const text = (v) => typeof v === "string" && v.length > 0 && !v.includes("\0") && v.isWellFormed();
+    if (!record(props))
+        return hostContract("Expected host contract v1.");
+    const keys = "v tenant layer user authenticatedAs credential requestId target targetHash dryRun".split(" ");
+    if (Object.keys(props).some(key => !keys.includes(key)) || props.v !== 1 || !text(props.tenant) || props.tenant !== options.tenant || !["admin", "member"].includes(props.layer) || !["snapshot", "fresh"].includes(props.authenticatedAs) || !["session", "oauth"].includes(props.credential) || !text(props.requestId) || !record(props.user))
+        return hostContract("Malformed host contract or tenant mismatch.");
+    for (const key of ["target", "targetHash"])
+        if (Object.hasOwn(props, key) && !text(props[key]))
+            return hostContract(`Invalid '${key}'.`, key);
+    if (Object.hasOwn(props, "dryRun") && typeof props.dryRun !== "boolean")
+        return hostContract("Invalid 'dryRun'.", "dryRun");
+    for (const key of ["target", "targetHash"])
+        if (props.layer === "admin" && !text(props[key]))
+            return hostContract(`Admin callers require '${key}'.`, key);
+    const user = props.user;
+    if (!text(user.id))
+        return hostContract("Invalid user id.", "id");
+    let base;
+    try {
+        base = userCaller(user, { fields: options.fields, adminRoles: [], credential: props.credential });
+    }
+    catch (error) {
+        return hostContract(error.message);
+    }
+    const caller = Object.freeze({ ...base, kind: props.layer === "admin" ? "host" : "user", subject: props.layer === "admin" ? "host:" + base.subject : base.subject, admin: props.layer === "admin", authenticatedAs: props.authenticatedAs, credential: props.credential, requestId: props.requestId, target: props.target, targetHash: props.targetHash, dryRun: props.dryRun === true });
+    identities.set(caller, Object.freeze({ ...identities.get(base), admin: caller.admin, host: true }));
+    return caller;
+}
+/** Resolve only forwarded props, or trip on an entry that did not opt in. */
+export function gatewayCaller(ctx, gateway, fields) {
+    const present = forwarded(ctx);
+    if (!gateway)
+        throw new ContractError('HOST_CONTRACT', 'Host props require gateway mode.', '', { status: 412 });
+    if (!present)
+        return { kind: 'anonymous' };
+    return hostCaller(ctx.props.mantle, { tenant: gateway.tenant, fields });
+}
+/** Host errors are machine-readable and never challenge for application credentials. */
+export function hostFailure(error, caller, where, challenge) {
+    if ((!caller || !isHostCaller(caller)) && !(error instanceof ContractError && error.code === 'HOST_CONTRACT'))
+        return surfaceFailure(error, challenge, where);
+    const result = surfaceError(error, where);
+    const code = result.status === 401 ? 'AUTH_DENIED' : result.error.code;
+    return Response.json({ error: { code, ...(typeof result.error.field === 'string' ? { field: result.error.field } : {}), ...(result.error.path ? { target: result.error.path } : {}) } }, { status: result.status === 401 ? 403 : result.status, headers: { 'cache-control': 'private, no-store' } });
+}
+export { isHostCaller } from "./caller-identity.js";
+export { checkFresh } from "./caller-identity.js";

package/dist/kernel/json-body.d.ts

@@ -0,0 +1,4 @@
+/** Request-only JSON reader: bound bytes before copying or parsing, independent of UTF-8 chunk boundaries. */
+/** Bound raw bytes before decoding a request body. */
+export declare function bytes(request: Request, limit: number, fail: (message: string) => never): Promise<Uint8Array>;
+export declare function body(request: Request, limit: number, fail: (message: string) => never): Promise<Record<string, unknown>>;

package/dist/kernel/json-body.js

@@ -0,0 +1,44 @@
+/** Request-only JSON reader: bound bytes before copying or parsing, independent of UTF-8 chunk boundaries. */
+/** Bound raw bytes before decoding a request body. */
+export async function bytes(request, limit, fail) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        fail("Body limit must be a positive safe integer.");
+    const reader = request.body?.getReader();
+    let bytes = new Uint8Array(0), length = 0;
+    try {
+        while (reader) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const end = length + value.byteLength;
+            if (end > limit) {
+                await reader.cancel().catch(() => { });
+                fail(`Request body exceeds ${limit} bytes.`);
+            }
+            if (end > bytes.length) {
+                const grown = new Uint8Array(Math.max(end, Math.min(limit, Math.max(1024, bytes.length * 2))));
+                grown.set(bytes);
+                bytes = grown;
+            }
+            bytes.set(value, length);
+            length = end;
+        }
+    }
+    finally {
+        reader?.releaseLock();
+    }
+    return bytes.subarray(0, length);
+}
+export async function body(request, limit, fail) {
+    const raw = await bytes(request, limit, fail);
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(raw).trim() || "{}");
+    }
+    catch {
+        fail("Expected a JSON body.");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("Expected a JSON object.");
+    return value;
+}

package/dist/kernel/mcp-apps.d.ts

@@ -0,0 +1,69 @@
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** What `resources/read` passes an HTML loader. */
+export interface McpAppRender {
+    /** The tools this caller's `tools/list` shows on the endpoint, so the HTML names none it cannot see. */
+    readonly tools: ReadonlySet<string>;
+    /** The request's environment as the handler received it: Worker bindings such as `ASSETS`, or whatever a Bun host passes. */
+    readonly env: unknown;
+    /** The `resources/read` request, for its origin. */
+    readonly request: Request;
+}
+/** The CSP a resource asks its host for, as `_meta.ui.csp`. */
+export type McpAppCsp = {
+    readonly connectDomains?: readonly string[];
+    readonly resourceDomains?: readonly string[];
+    readonly frameDomains?: readonly string[];
+    readonly baseUriDomains?: readonly string[];
+};
+/** What a loader may return beside a plain string: the HTML and a CSP known only when it is read. It is sent on `resources/read` and replaces the resource's static `csp` (lists are not merged). */
+export interface McpAppPage {
+    readonly html: string;
+    readonly csp?: McpAppCsp;
+}
+/** One `ui://` resource. The HTML is a reusable asset and never carries caller data: that travels in tool results. */
+export interface McpAppResource {
+    readonly uri: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly html: string | ((render: McpAppRender) => string | McpAppPage | Promise<string | McpAppPage>);
+    readonly csp?: McpAppCsp;
+    readonly permissions?: {
+        readonly camera?: Record<string, never>;
+        readonly microphone?: Record<string, never>;
+        readonly geolocation?: Record<string, never>;
+        readonly clipboardWrite?: Record<string, never>;
+    };
+    readonly prefersBorder?: boolean;
+    /** `_meta.ui.domain`: the dedicated sandbox origin a host should serve this App from, in the form that host documents. */
+    readonly domain?: string;
+    /** Tool names whose results this resource renders. */
+    readonly renders?: readonly string[];
+    /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. A Procedure cannot be hidden from the model. */
+    readonly appOnly?: readonly string[];
+}
+export interface McpApps {
+    readonly resources: readonly McpAppResource[];
+}
+/** An application-owned contributor resolved after the endpoint's caller gate. */
+export type McpAppsSource = McpApps | ((context: Pick<McpAppRender, "env" | "request">) => McpApps | Promise<McpApps>);
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
+export declare const resourcesOf: (apps: McpApps | readonly McpApps[]) => McpApps;
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
+export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlySet<string>, views?: ReadonlySet<string>): {
+    resources: McpAppResource[];
+    renders: Map<string, string>;
+    appOnly: Set<string>;
+};
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export declare function linkSurface(apps: McpApps | readonly McpApps[], selected: readonly {
+    name: string;
+    page?: unknown;
+}[], previous?: {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+}): {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+};

package/dist/kernel/mcp-apps.js

@@ -0,0 +1,40 @@
+import { ContractError } from "./contracts.js";
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
+export const resourcesOf = (apps) => ({ resources: (Array.isArray(apps) ? apps : [apps]).flatMap(app => app.resources) });
+/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
+export function linkApps(apps, tools, views) {
+    const resources = resourcesOf(apps).resources;
+    const uris = new Set(), names = new Set(), renders = new Map(), appOnly = new Set();
+    const refuse = (message) => { throw new ContractError("MCP_APP_CONFLICT", message, "mcp:apps", { status: 500 }); };
+    for (const resource of resources) {
+        if (!resource.uri.startsWith("ui://"))
+            refuse(`MCP App resource '${resource.name}' must use a ui:// URI.`);
+        if (uris.has(resource.uri))
+            refuse(`MCP App resource URI '${resource.uri}' is registered twice.`);
+        if (names.has(resource.name))
+            refuse(`MCP App resource name '${resource.name}' is registered twice.`);
+        uris.add(resource.uri);
+        names.add(resource.name);
+        for (const tool of [...resource.renders ?? [], ...resource.appOnly ?? []]) {
+            if (tools && !tools.has(tool))
+                refuse(`MCP App resource '${resource.name}' names tool '${tool}', which this endpoint does not serve.`);
+            if (renders.has(tool) && renders.get(tool) !== resource.uri)
+                refuse(`Tool '${tool}' is claimed by two MCP App resources.`);
+            renders.set(tool, resource.uri);
+        }
+        // an App acts for the user without the model seeing the call, so only a read may be hidden from the model
+        for (const tool of resource.appOnly ?? []) {
+            if (views && !views.has(tool))
+                refuse(`App-only tool '${tool}' must be a View this endpoint serves.`);
+            appOnly.add(tool);
+        }
+    }
+    return { resources, renders, appOnly };
+}
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export function linkSurface(apps, selected, previous) {
+    const key = JSON.stringify(selected.map(tool => tool.name).sort());
+    return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
+}

package/dist/kernel/mcp-call.d.ts

@@ -0,0 +1,5 @@
+import type { Caller } from "./contracts.js";
+import type { Tool } from "./mcp.js";
+export declare function callTool<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, db: Database, caller: Caller, handlers: Handlers): Promise<unknown>;
+/** Transport input is checked before acquiring an application-owned native handle. */
+export declare function callToolLazy<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, getDb: () => Database, caller: Caller, handlers: Handlers, dryRun?: () => unknown): Promise<unknown>;

package/dist/kernel/mcp-call.js

@@ -0,0 +1,25 @@
+import { convert, invalid } from "./surface.js";
+import { checkPageLimit } from "./paging.js";
+export async function callTool(tool, raw, db, caller, handlers) {
+    return callToolLazy(tool, raw, () => db, caller, handlers);
+}
+/** Transport input is checked before acquiring an application-owned native handle. */
+export async function callToolLazy(tool, raw, getDb, caller, handlers, dryRun) {
+    if (tool.page) {
+        const { limit, cursor, ...input } = raw;
+        if (limit !== undefined)
+            checkPageLimit(limit, tool.path);
+        if (cursor !== undefined && typeof cursor !== "string")
+            invalid("Invalid paging options.", tool.path);
+        await tool.validate(input);
+        convert(input, tool.convert);
+        if (dryRun)
+            return dryRun();
+        return tool.page(getDb(), caller, input, { limit: limit, cursor: cursor });
+    }
+    const input = await tool.validate(raw);
+    convert(input, tool.convert);
+    if (dryRun)
+        return dryRun();
+    return tool.run(getDb(), caller, input, handlers);
+}