@fungi.computer/agar 0.1.0 → 0.3.0

package/dist/method-refusal.js

@@ -36,13 +36,13 @@ export class AppMethodRefusal extends Error {
     }
 }
 /** A refused call as it crosses the generated method boundary. */
-export const appMethodRefusedReplySchema = z.strictObject({
+export const appMethodRefusedReplySchema = z.lazy(() => z.strictObject({
     kind: z.literal("refused"),
     code: z.enum(appMethodRefusalCodes),
     message: z.string().min(1).max(maxAppMethodRefusalMessage),
-});
+}));
 /** Every generated App method RPC answers with exactly one of these. */
-export const appMethodReplySchema = z.discriminatedUnion("kind", [
+export const appMethodReplySchema = z.lazy(() => z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("ok"), value: z.json() }),
     appMethodRefusedReplySchema,
-]);
+]));

package/dist/query.d.ts

@@ -54,9 +54,9 @@ export declare function useMemberInbox(app: QueryApp | null): {
             readonly nodeId: string;
             readonly iteration: string;
         };
-        readonly state: "pending" | "closed" | "answered" | "delivered" | "timed_out";
-        readonly workflowId: string | null;
+        readonly state: "pending" | "answered" | "closed" | "delivered" | "timed_out";
         readonly expiresAt: number;
+        readonly workflowId: string | null;
         readonly installationId: string;
         readonly workflowTitle: string;
         readonly reviewTitle: string;

package/dist/react-mount.d.ts

@@ -1,16 +1,22 @@
 import { type QueryClient } from "@tanstack/react-query";
 import { type ReactNode } from "react";
+import { AppError } from "./errors.js";
 import type { AppRoot } from "./root.js";
 import type { Disposer } from "./store.js";
 /** The App connection state passed to `mountApp`'s `render` callback:
  * `live` once connected, or `connecting`/`standalone`/`ended` while there
- * is no usable App. */
+ * is no usable App. An embedded page whose handshake fails is `not-hosted`,
+ * never standalone; Agar also renders that failure visibly. */
 export type AppMountState = Readonly<{
     app: AppRoot;
     status: "live";
 } | {
     app: null;
     status: "connecting" | "standalone" | "ended";
+} | {
+    app: null;
+    status: "not-hosted";
+    error: AppError;
 }>;
 /** Options passed to `mountApp`. */
 export type AppMountOptions = Readonly<{

package/dist/react-mount.js

@@ -1,6 +1,6 @@
 import { applyTheme, getTheme } from "@fungi.computer/stipe/theme";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { createElement, useLayoutEffect } from "react";
+import { createElement, Fragment, useLayoutEffect, } from "react";
 import { createRoot } from "react-dom/client";
 import { connectApp } from "./connect.js";
 import { AppError } from "./errors.js";
@@ -37,17 +37,25 @@ export function mountApp(element, options, render) {
             themed = false;
         }
     };
-    const { referrer, defaultView } = element.ownerDocument;
+    const { defaultView } = element.ownerDocument;
     performance.mark("fungi.app-open.react-root-render-start");
-    if (!defaultView ||
-        defaultView.parent === defaultView ||
-        !URL.canParse(referrer)) {
+    if (!defaultView) {
+        publish({
+            app: null,
+            status: "not-hosted",
+            error: new AppError("The App document has no window", {
+                code: "DISCONNECTED",
+                retryable: false,
+            }),
+        });
+    }
+    else if (defaultView.parent === defaultView) {
         publish({ app: null, status: "standalone" });
     }
     else {
         publish({ app: null, status: "connecting" });
         void connectApp({
-            expectedHostOrigin: new URL(referrer).origin,
+            host: "parent",
             signal: controller.signal,
         })
             .then((app) => {
@@ -85,7 +93,17 @@ export function mountApp(element, options, render) {
             console.error(`${options.name} host connection failed`, cause);
             releaseConnection();
             if (!controller.signal.aborted)
-                publish({ app: null, status: "ended" });
+                publish({
+                    app: null,
+                    status: "not-hosted",
+                    error: cause instanceof AppError
+                        ? cause
+                        : new AppError("The App host is unavailable", {
+                            cause,
+                            code: "HOST_FAILURE",
+                            retryable: true,
+                        }),
+                });
         });
     }
     return () => {
@@ -104,5 +122,7 @@ function AppView({ state, render, }) {
         if (state.app)
             performance.mark("fungi.app-open.react-connected-commit");
     }, [state.app]);
-    return render(state);
+    return createElement(Fragment, null, state.status === "not-hosted"
+        ? createElement("p", { role: "alert" }, "App host connection unavailable. Open this App through its host to try again.")
+        : null, render(state));
 }

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { type WhistleContribution, type WhistleRuntime } from "@fungi.computer/whistle";
-import type { AppBackHandler, HostNavigation } from "./window.js";
+import type { AppBackHandler, AppCrumb, AppHeaderCommand, AppHeaderStatus, HostNavigation } from "./window.js";
 import type { AppContext } from "./lifecycle.js";
 import type { AppStatusActionHandler, AppStatusItem } from "./ui.js";
 import type { AppRoot } from "./root.js";
@@ -31,11 +31,23 @@ export type HostNavigationOptions = Readonly<{
     canGoBack: boolean;
     /** The current page's title, shown after the App name in window chrome. */
     title?: string | undefined;
+    /** The App's path, shown in the window header in place of the title. */
+    crumbs?: readonly AppCrumb[] | undefined;
+    /** The view's main commands, as header buttons. */
+    primary?: readonly AppHeaderCommand[] | undefined;
+    /** Less common commands, behind the header's overflow menu. */
+    menu?: readonly AppHeaderCommand[] | undefined;
+    /** Facts about the view, shown as muted text with a status bead. */
+    status?: readonly AppHeaderStatus[] | undefined;
     onBack: AppBackHandler;
+    /** The person chose a crumb, or a sibling from a switcher crumb. */
+    onCrumb?: ((crumbId: string, siblingId?: string) => void) | undefined;
+    /** The person used a primary or menu command. */
+    onAction?: ((actionId: string) => void) | undefined;
 }>;
 /**
  * Publish an App's navigation state to its host and own the host's Back
  * requests while mounted. Pass `app?.window.navigation`; with no connected
  * App it does nothing. Unmounting withdraws Back from the host chrome.
  */
-export declare function useHostNavigation(navigation: HostNavigation | null | undefined, { canGoBack, title, onBack }: HostNavigationOptions): void;
+export declare function useHostNavigation(navigation: HostNavigation | null | undefined, { canGoBack, title, crumbs, primary, menu, status, onBack, onCrumb, onAction, }: HostNavigationOptions): void;

package/dist/react.js

@@ -80,26 +80,62 @@ export function useAppCommandCatalog(app, { sourceId, namespace }, build) {
  * requests while mounted. Pass `app?.window.navigation`; with no connected
  * App it does nothing. Unmounting withdraws Back from the host chrome.
  */
-export function useHostNavigation(navigation, { canGoBack, title, onBack }) {
+export function useHostNavigation(navigation, { canGoBack, title, crumbs, primary, menu, status, onBack, onCrumb, onAction, }) {
     const latestBack = useRef(onBack);
+    const latestCrumb = useRef(onCrumb);
+    const latestAction = useRef(onAction);
     useEffect(() => {
         latestBack.current = onBack;
-    }, [onBack]);
+        latestCrumb.current = onCrumb;
+        latestAction.current = onAction;
+    }, [onBack, onCrumb, onAction]);
     useEffect(() => {
         if (!navigation)
             return undefined;
         const release = navigation.onBack(() => latestBack.current());
+        const releaseActivation = navigation.onActivate((activation) => {
+            if (activation.kind === "action") {
+                const handler = latestAction.current;
+                handler?.(activation.actionId);
+                return handler !== undefined;
+            }
+            const handler = latestCrumb.current;
+            if (activation.siblingId === undefined)
+                handler?.(activation.crumbId);
+            else
+                handler?.(activation.crumbId, activation.siblingId);
+            return handler !== undefined;
+        });
         return () => {
             release();
+            releaseActivation();
             report(navigation, { canGoBack: false });
         };
     }, [navigation]);
+    // Callers pass fresh arrays each render; the report follows their content.
+    const lists = JSON.stringify([crumbs, primary, menu, status]);
+    const latestLists = useRef({ crumbs, primary, menu, status });
+    useEffect(() => {
+        latestLists.current = { crumbs, primary, menu, status };
+    }, [crumbs, primary, menu, status]);
     // Each change replaces the last report; only unmount withdraws Back.
     useEffect(() => {
         if (!navigation)
             return;
-        report(navigation, title === undefined ? { canGoBack } : { canGoBack, title });
-    }, [navigation, canGoBack, title]);
+        let state = { canGoBack };
+        if (title !== undefined)
+            state = { ...state, title };
+        const current = latestLists.current;
+        if (current.crumbs !== undefined)
+            state = { ...state, crumbs: current.crumbs };
+        if (current.primary !== undefined)
+            state = { ...state, primary: current.primary };
+        if (current.menu !== undefined)
+            state = { ...state, menu: current.menu };
+        if (current.status !== undefined)
+            state = { ...state, status: current.status };
+        report(navigation, state);
+    }, [navigation, canGoBack, title, lists]);
 }
 function report(navigation, state) {
     navigation.publish(state).catch((cause) => {

package/dist/read-copy.d.ts

@@ -52,7 +52,7 @@ export declare function countingGit(binding: GitBinding, options: {
         delete(name: string): Promise<boolean>;
         log(name: string, options: {
             ref: string;
-            limit?: number;
+            limit? /** Bind a namespace to its maintained App decoder. */: number;
             offset?: number;
         }): Promise<import("./git.js").GitCommit[]>;
         readCommit(name: string, hash: string): Promise<import("./git.js").GitCommit | null>;

package/dist/read-copy.js

@@ -44,18 +44,15 @@ export function countingGit(binding, options) {
         /** Dispatch counts by maintained Git operation. */ counts: () => Object.fromEntries(counts),
     };
 }
-const rowSchema = z.strictObject({
+const rowSchema = z.lazy(() => z.strictObject({
     head: gitSha1Schema.nullable(),
     version: z.number().int(),
     revision: z.number().int(),
     value: z.string().nullable(),
-});
+}));
 const name = z.string().min(1).max(1024);
 const zero = "0".repeat(40);
-const blobHash = z.union([
-    gitSha1Schema,
-    z.string().regex(/^sha256:[0-9a-f]{64}$/),
-]);
+const blobHash = z.lazy(() => z.union([gitSha1Schema, z.string().regex(/^sha256:[0-9a-f]{64}$/)]));
 /** Own bounded rows and content-addressed bytes in the App facet, not a host/provider cache. */
 export function createReadCopies(sql, limits) {
     z.strictObject({

package/dist/storage.js

@@ -140,4 +140,4 @@ function client(raw) {
     };
 }
 /** This App's own declared data. The host seals App and member identities. */
-export const appStorage = defineCapability("app.storage", 1, rawSchema.transform(client));
+export const appStorage = defineCapability("app.storage", 1, z.lazy(() => rawSchema.transform(client)));

package/dist/test-kit/git.js

@@ -1,6 +1,6 @@
 import { pathToFileURL } from "node:url";
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod";
@@ -13,7 +13,21 @@ export function realGit() {
     const info = (name) => existsSync(join(root, `${name}.git`))
         ? { name, defaultBranch: "main", lastPushAt: null, source: null }
         : null;
+    // A full object id names an immutable commit, so one read serves every
+    // later ask; refs and abbreviations move and are never cached.
+    const commits = new Map();
+    const immutable = (hash) => /^[0-9a-f]{40,64}$/u.test(hash);
     const readCommit = (name, hash) => {
+        // The repository's directory identity keeps a deleted-and-recreated name
+        // from serving the old repository's commits, however it was removed.
+        const dir = statSync(join(root, `${name}.git`), {
+            bigint: true,
+            throwIfNoEntry: false,
+        });
+        const key = `${name}\0${String(dir?.ino)}\0${String(dir?.birthtimeNs)}\0${hash}`;
+        const cached = immutable(hash) ? commits.get(key) : undefined;
+        if (cached !== undefined)
+            return structuredClone(cached);
         const found = spawnSync("git", [`--git-dir=${join(root, `${name}.git`)}`, "cat-file", "-t", hash], { encoding: "utf8" });
         if (found.status !== 0 || found.stdout.trim() !== "commit")
             return null;
@@ -31,7 +45,7 @@ export function realGit() {
             z.string(),
         ])
             .parse(run(name, "show", "-s", "--format=%H%x00%T%x00%P%x00%an%x00%ae%x00%cn%x00%ce%x00%at%x00%ct%x00%B", hash).split("\0"));
-        return {
+        const commit = {
             hash: oid,
             treeHash,
             parents: parents ? parents.split(" ") : [],
@@ -41,6 +55,9 @@ export function realGit() {
             committedAt: Number(committedAt),
             message,
         };
+        if (immutable(hash))
+            commits.set(key, structuredClone(commit));
+        return commit;
     };
     const git = {
         cloneUrl: (name) => {

package/dist/window.d.ts

@@ -9,6 +9,58 @@ export type BeforeAppClose = () => boolean | Promise<boolean>;
 export declare const APP_NAVIGATION_CONTRACT_VERSION: 1;
 /** The longest page title a host shows beside the App's own name. */
 export declare const APP_NAVIGATION_TITLE_MAX = 80;
+/** The most crumbs one navigation report may carry. */
+export declare const APP_NAVIGATION_CRUMBS_MAX = 8;
+/** The most siblings one switcher crumb may offer. */
+export declare const APP_NAVIGATION_SIBLINGS_MAX = 16;
+/** The most primary header commands one report may carry. */
+export declare const APP_NAVIGATION_PRIMARY_MAX = 3;
+/** The most header status facts one report may carry. */
+export declare const APP_NAVIGATION_STATUS_MAX = 4;
+/** The most ⋯ menu commands one report may carry. */
+export declare const APP_NAVIGATION_MENU_MAX = 12;
+/** The longest crumb or command label a host shows. */
+export declare const APP_NAVIGATION_LABEL_MAX = 80;
+/** One place in the App's path; `siblings` makes it a switcher. */
+export type AppCrumb = Readonly<{
+    id: string;
+    label: string;
+    siblings?: readonly Readonly<{
+        id: string;
+        label: string;
+    }>[];
+}>;
+/** A command the App offers in its window header; the App owns its effect. */
+export type AppHeaderCommand = Readonly<{
+    id: string;
+    label: string;
+    /** Supported icon-only presentation; label remains the accessible name. */
+    icon?: "play";
+    /** The Caps button a primary command wears; default `outline`. */
+    variant?: "primary" | "outline" | "ghost";
+    /** A menu command that removes or discards something. */
+    tone?: "destructive";
+    disabled?: boolean;
+}>;
+/** A quiet fact about the view, shown as muted text with a status bead. */
+export type AppHeaderStatus = Readonly<{
+    id: string;
+    label: string;
+    /** Show the bead alone, with label retained as accessible text and a hint. */
+    presentation?: "bead";
+    tone?: "neutral" | "info" | "warning" | "success" | "error";
+}>;
+/** The person used a crumb (or a switcher's sibling) or a header command. */
+export type AppNavigationActivation = Readonly<{
+    kind: "crumb";
+    crumbId: string;
+    siblingId?: string;
+}> | Readonly<{
+    kind: "action";
+    actionId: string;
+}>;
+/** Handles one activation; `true` when the App acted on it. */
+export type AppNavigationActivationHandler = (activation: AppNavigationActivation) => boolean | Promise<boolean>;
 /**
  * What the App's own router can do right now. The App owns its history; the
  * host only offers a Back affordance and relays the person's request.
@@ -17,6 +69,14 @@ export type AppNavigationState = Readonly<{
     canGoBack: boolean;
     /** The current page's title, shown after the App name in window chrome. */
     title?: string;
+    /** The App's path; the host shows it in place of the App name and title. */
+    crumbs?: readonly AppCrumb[];
+    /** The view's main commands, as buttons in the header. */
+    primary?: readonly AppHeaderCommand[];
+    /** Less common commands, behind the header's overflow menu. */
+    menu?: readonly AppHeaderCommand[];
+    /** Facts about the view, such as "Valid" or "Saved". Data only. */
+    status?: readonly AppHeaderStatus[];
 }>;
 /** Go back one step in the App's own history; `true` when it moved. */
 export type AppBackHandler = () => boolean | Promise<boolean>;
@@ -26,6 +86,8 @@ export type HostNavigation = Readonly<{
     publish(state: AppNavigationState): Promise<void>;
     /** Own the host's Back requests; one owner at a time. */
     onBack(handler: AppBackHandler): Disposer;
+    /** Own the host's crumb and command activations; one owner at a time. */
+    onActivate(handler: AppNavigationActivationHandler): Disposer;
 }>;
 /** App-owned presentation policy consulted before a user closes its window. */
 export type AppWindow = Readonly<{
@@ -39,3 +101,9 @@ export type AppWindow = Readonly<{
  * accepts every report and never asks the App to go back.
  */
 export declare const inertHostNavigation: HostNavigation;
+/**
+ * Whether an activation names something the App published now: a crumb (and
+ * its sibling), or an enabled command. Every hop applies this rule against
+ * its own latest copy of the report, so a stale shell cannot reach the App.
+ */
+export declare function navigationActivationAllowed(state: AppNavigationState, activation: AppNavigationActivation): boolean;

package/dist/window.js

@@ -5,6 +5,18 @@
 export const APP_NAVIGATION_CONTRACT_VERSION = 1;
 /** The longest page title a host shows beside the App's own name. */
 export const APP_NAVIGATION_TITLE_MAX = 80;
+/** The most crumbs one navigation report may carry. */
+export const APP_NAVIGATION_CRUMBS_MAX = 8;
+/** The most siblings one switcher crumb may offer. */
+export const APP_NAVIGATION_SIBLINGS_MAX = 16;
+/** The most primary header commands one report may carry. */
+export const APP_NAVIGATION_PRIMARY_MAX = 3;
+/** The most header status facts one report may carry. */
+export const APP_NAVIGATION_STATUS_MAX = 4;
+/** The most ⋯ menu commands one report may carry. */
+export const APP_NAVIGATION_MENU_MAX = 12;
+/** The longest crumb or command label a host shows. */
+export const APP_NAVIGATION_LABEL_MAX = 80;
 /**
  * Navigation for a root with no host chrome, such as a workbench fixture: it
  * accepts every report and never asks the App to go back.
@@ -12,4 +24,23 @@ export const APP_NAVIGATION_TITLE_MAX = 80;
 export const inertHostNavigation = Object.freeze({
     publish: () => Promise.resolve(),
     onBack: () => () => undefined,
+    onActivate: () => () => undefined,
 });
+/**
+ * Whether an activation names something the App published now: a crumb (and
+ * its sibling), or an enabled command. Every hop applies this rule against
+ * its own latest copy of the report, so a stale shell cannot reach the App.
+ */
+export function navigationActivationAllowed(state, activation) {
+    if (activation.kind === "action") {
+        const command = [...(state.primary ?? []), ...(state.menu ?? [])].find((candidate) => candidate.id === activation.actionId);
+        return command !== undefined && command.disabled !== true;
+    }
+    const crumb = state.crumbs?.find((candidate) => candidate.id === activation.crumbId);
+    if (crumb === undefined)
+        return false;
+    if (activation.siblingId === undefined)
+        return true;
+    return (crumb.siblings?.some((sibling) => sibling.id === activation.siblingId) ===
+        true);
+}

package/docs/api/README.md

@@ -6,21 +6,21 @@
 
 # Agar API overview
 
-| Import                                     | Export                                                 | Purpose                                                                                  |
-| ------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| `@fungi.computer/agar`                     | `connectApp`                                           | Connect a host-mounted App frontend and receive its context and grants.                  |
-| `@fungi.computer/agar`                     | `defineCapability`, `AppError`                         | Declare a typed host capability; the SDK's one typed failure.                            |
-| `@fungi.computer/agar/host`                | `connectAppHost`                                       | Mount an App in an author-owned iframe test or standalone page.                          |
-| `@fungi.computer/agar/react`               | `mountApp`, `useAppContext`                            | Mount a React App and read its host context.                                             |
-| `@fungi.computer/agar/query`               | `queryKeys`                                            | TanStack Query keys and live feeds for host data.                                        |
-| `@fungi.computer/agar/errors`              | `describeAppError`                                     | Turn a failure into approved, action-hinted UI copy.                                     |
-| `@fungi.computer/agar/backend-definition`  | `defineAppBackend`, `defineAppMethod`                  | Define typed backend methods once, with Zod input and output.                            |
-| `@fungi.computer/agar/backend-declaration` | `buildAppApi`, `buildAppDeclaration`                   | Project the backend definition to the JSON Schema App API at build time.                 |
-| `@fungi.computer/agar/backend`             | `appBackend`                                           | Call the App's own backend from its frontend.                                            |
-| `@fungi.computer/agar/rpc`                 | `rpcHandleSchema`, `rpcMethod`                         | Validate object-capability handles received over Cap'n Web.                              |
-| `@fungi.computer/agar/files`               | `readAppFile`, `writeAppFile`                          | Turn a host-owned file read or write handle into a `File` or an upload.                  |
-| `@fungi.computer/agar/storage`             | `appStorage`                                           | Read, write and watch the App's own member and Team data.                                |
-| `@fungi.computer/agar/computer-contracts`  | `workflowGitPassResultSchema`, `WorkflowGitPassResult` | Validate host-issued, credential-free Workflow pass metadata without granting authority. |
+| Import                                     | Export                                                              | Purpose                                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `@fungi.computer/agar`                     | `connectApp`                                                        | Connect a host-mounted App frontend and receive its context and grants.                             |
+| `@fungi.computer/agar`                     | `defineCapability`, `AppError`                                      | Declare a typed host capability; the SDK's one typed failure.                                       |
+| `@fungi.computer/agar/host`                | `connectAppHost`                                                    | Mount an App in an author-owned iframe test or standalone page.                                     |
+| `@fungi.computer/agar/react`               | `mountApp`, `useAppContext`                                         | Mount a React App and read its host context.                                                        |
+| `@fungi.computer/agar/query`               | `queryKeys`                                                         | TanStack Query keys and live feeds for host data.                                                   |
+| `@fungi.computer/agar/errors`              | `describeAppError`                                                  | Turn a failure into approved, action-hinted UI copy.                                                |
+| `@fungi.computer/agar/backend-definition`  | `defineAppBackend`, `defineAppMethod`                               | Define typed backend methods once, with Zod input and output.                                       |
+| `@fungi.computer/agar/backend-declaration` | `buildAppApi`, `buildAppDeclaration`                                | Project the backend definition to the JSON Schema App API at build time.                            |
+| `@fungi.computer/agar/backend`             | `appBackend`                                                        | Call the App's own backend from its frontend.                                                       |
+| `@fungi.computer/agar/rpc`                 | `rpcHandleSchema`, `rpcMethod`                                      | Validate object-capability handles received over Cap'n Web.                                         |
+| `@fungi.computer/agar/files`               | `readAppFile`, `writeAppFile`                                       | Turn a host-owned file read or write handle into a `File` or an upload.                             |
+| `@fungi.computer/agar/storage`             | `appStorage`                                                        | Read, write and watch the App's own member and Team data.                                           |
+| `@fungi.computer/agar/computer-contracts`  | `appComputerAdmissionRefusalSchema`, `appComputerExecTimeoutSchema` | Validate public Computer admission, dispatch and budget outcomes without exposing host credentials. |
 
 A host decides what an App may do: the frontend asks for a capability and the
 host grants, denies or revokes it. The backend definition is runtime-neutral;

package/docs/api/backend-definition.md

@@ -30,6 +30,9 @@ type MethodPolicy = Readonly<{
   hidden?: true;
   anonymous?: true;
   pending?: true;
+  present?: Readonly<{
+    verb: string;
+  }>;
 }>;
 ```
 
@@ -37,6 +40,44 @@ A method's schemas own both its TypeScript contract and JSON boundary.
 
 ---
 
+### ResultRowCodec
+
+```ts
+type ResultRowCodec = Readonly<{
+  decode: (row) => ResultRow;
+  schema: z.ZodType;
+}>;
+```
+
+Decodes and bounds result rows; see `resultRows` in
+`@fungi.computer/agar/method-presentation`.
+
+---
+
+### MethodPresentation
+
+```ts
+type MethodPresentation<I, O> = Readonly<{
+  verb: string;
+  row: (call) => ResultRow;
+  rows: ResultRowCodec;
+}>;
+```
+
+How a finished call reads to a person: a pure projection run in the App backend.
+`rows` is `resultRows` from `@fungi.computer/agar/method-presentation`; only a
+backend that presents imports it, so one without presentations carries no row
+decoder.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `I`            |
+| `O`            |
+
+---
+
 ### AppBackendMethod
 
 ```ts
@@ -44,6 +85,8 @@ type AppBackendMethod<Context> = Readonly<{
   policy: MethodPolicy;
   input: z.ZodType;
   output: z.ZodType;
+  present?: (input, output) => ResultRow;
+  presentRow?: z.ZodType;
   call: (input, context, caller) => Promise<WhistleJsonValue>;
 }>;
 ```
@@ -58,6 +101,24 @@ Prepared method export consumed by the backend and its build.
 
 ---
 
+### AppBackendMethods
+
+```ts
+type AppBackendMethods<Context> = Readonly<
+  Record<string, AppBackendMethod<Context>>
+>;
+```
+
+The prepared methods of one backend, keyed by their public names.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| -------------- | ------------ |
+| `Context`      | `void`       |
+
+---
+
 ### AppBackendClass
 
 ```ts
@@ -123,18 +184,31 @@ EVENTS.emit acknowledges delivery with native void, not a JSON value.
 ### appSendBudgetRefusalSchema
 
 ```ts
-const appSendBudgetRefusalSchema: ZodObject<
-  {
-    error: ZodLiteral<"send_budget_exceeded">;
-    retryAfterMs: ZodNumber;
-  },
-  $strict
+const appSendBudgetRefusalSchema: ZodLazy<
+  ZodObject<
+    {
+      error: ZodLiteral<"send_budget_exceeded">;
+      retryAfterMs: ZodNumber;
+    },
+    $strict
+  >
 >;
 ```
 
 App-originated Session send refusal; retry advice is a duration, not a
 timestamp.
 
+---
+
+### presentMethodName
+
+```ts
+const presentMethodName: "present" = "present";
+```
+
+Name of the generated, hidden read method that projects a finished call into its
+row.
+
 ## Functions
 
 ### defineAppMethod()
@@ -155,9 +229,9 @@ Define a typed method once; neither discovery nor builds execute its handler.
 
 #### Parameters
 
-| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `method`  | `Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.toolPolicy"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `anonymous?`: `true`; `pending?`: `true`; \}\> & \{ input: I; output: O; \} & (\{ pending: true; handler: (input: output\<I\>, context: Context, caller: \{ computerId: string \| null; actor: \{ kind: "member"; memberId: string; \} \| \{ ...; \} \| \{ ...; \}; ... 5 more ...; idempotencyKey?: string \| undefined; \}) =\> Readonly\<...\> \| ... 1 more ... \| Promise\<...\>; \} \| \{ ...; \}) |
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`  | `Omit`\<`Readonly`\<\{ `description`: `string`; `effect`: `"external"` \| `"read"` \| `"write"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"` \| `"approvals"` \| `"apps.open"` \| `"apps.call"` \| `"llm.generation"` \| `"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"app.storage"` \| `"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \| `"channels.read"` \| `"channels.personal.manage"`)[]; `hidden?`: `true`; `anonymous?`: `true`; `pending?`: `true`; `present?`: `Readonly`\<\{ `verb`: `string`; \}\>; \}\>, `"present"`\> & \{ input: I; output: O; present?: Readonly\<\{ verb: string; row: (call: Readonly\<\{ input: output\<I\>; output: output\<O\>; \}\>) =\> \{ readonly id: string; readonly title: string; ... 4 more ...; readonly media?: \{ ...; \} \| undefined; \}; rows: Readonly\<...\>; \}\> \| undefined; \} & (\{ ...; \} \| \{ ...; \}) |
 
 #### Returns