@fungi.computer/forage 0.0.2 → 0.2.0

package/README.md

@@ -59,7 +59,13 @@ has a unique dotted path, an input schema, and optional description, capability
 notes, instructions, and output schema. Forage validates the catalog, orders its
 operations deterministically, and prepares descriptions once when the catalog is
 created. To change the catalog, create a new revision instead of mutating the
-existing one.
+existing one. Every operation must fit one complete description, and the
+catalog's aggregate metadata remains bounded. A whole namespace can exceed a
+description response without making its individually describable operations
+unavailable. Use paged `list({ namespace })` and describe one operation or
+select `methods` when a broad namespace description exceeds the response bound.
+This applies equally to flat namespaces and broad parents of nested namespaces;
+responses are never truncated and the response bound is unchanged.
 
 `search` ranks matching operations. `describe` returns a bounded TypeScript
 description for one operation or a namespace. Operation descriptions also

package/dist/app-api.d.ts

@@ -11,7 +11,7 @@ export declare function appMethodSchemas(api: AppApi): {
     [k: string]: {
         readonly description: string;
         readonly effect: "write" | "external" | "read";
-        readonly requires: readonly ("agent.list" | "agent.manage" | "agent.rename" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
+        readonly requires: readonly ("approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
         readonly pending: true | undefined;
         readonly input: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
         readonly output: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
@@ -22,7 +22,7 @@ export declare function appToolSchemas(api: AppApi): {
     [k: string]: {
         readonly description: string;
         readonly effect: "write" | "external" | "read";
-        readonly requires: readonly ("agent.list" | "agent.manage" | "agent.rename" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
+        readonly requires: readonly ("approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
         readonly pending: true | undefined;
         readonly input: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
         readonly output: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
@@ -35,7 +35,7 @@ export declare function appToolFamilySchemas(api: AppApi, reply: unknown): {
     name: string;
     call: string;
     effect: "write" | "external" | "read";
-    requires: readonly ("agent.list" | "agent.manage" | "agent.rename" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
+    requires: readonly ("approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
     kind: "ready" | "unindexed";
     tools: {
         row: {

package/dist/app-api.js

@@ -1,10 +1,10 @@
 import { z } from "zod";
-const bindingName = z
+const bindingName = z.lazy(() => z
     .string()
     .min(1)
     .max(75)
-    .regex(/^[A-Za-z][A-Za-z0-9_]*$/);
-const jsonSchema = z.union([z.record(z.string(), z.json()), z.boolean()]);
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/));
+const jsonSchema = z.lazy(() => z.union([z.record(z.string(), z.json()), z.boolean()]));
 /** The shared JSON-Schema compiler for App methods and OpenAPI operations. */
 export function jsonSchemaToZod(source, defaultTarget = "draft-2020-12") {
     return z.fromJSONSchema(jsonSchema.parse(source), { defaultTarget });
@@ -46,7 +46,7 @@ export function appToolSchemas(api) {
         methods: Object.fromEntries(Object.entries(api.methods).filter(([, method]) => method.hidden !== true)),
     });
 }
-const familyRow = z
+const familyRow = z.lazy(() => z
     .object({
     tool: bindingName,
     title: z.string().max(120),
@@ -61,8 +61,8 @@ const familyRow = z
     // verbatim; it never reads into or defaults any of it.
     call: z.record(z.string(), z.json()),
 })
-    .catchall(z.json());
-const familyInventory = z.discriminatedUnion("kind", [
+    .catchall(z.json()));
+const familyInventory = z.lazy(() => z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("unindexed") }),
     z.strictObject({
         kind: z.literal("ready"),
@@ -71,7 +71,7 @@ const familyInventory = z.discriminatedUnion("kind", [
             .max(100)
             .refine((rows) => new Set(rows.map((row) => row.tool)).size === rows.length, { message: "Tool family names must be distinct" }),
     }),
-]);
+]));
 /** Decode the signed listing before compiling dynamic discovery schemas.
  * Rows retain App-owned selectors as data. Hosts supply call admission and
  * invocation arguments; this projection supplies neither defaults nor handlers. */

package/dist/catalog.js

@@ -4,7 +4,7 @@ import { describeCatalog } from "./describe.js";
 import { catalogStamp, prepareOperation, searchCatalog, } from "./search.js";
 import { compareCodeUnits } from "./normalization.js";
 import { listOperations } from "./list.js";
-import { renderNamespaceIndex, renderOperationTypes, schemaProjectionSize, } from "./rendering.js";
+import { renderOperationTypes, schemaProjectionSize } from "./rendering.js";
 const maximumCatalogProjectionBytes = 1_000_000;
 function parseCatalog(input) {
     const parsed = catalogInputSchema.safeParse(input);
@@ -42,20 +42,13 @@ function parseCatalog(input) {
         }
     }
     const preparedOperations = operations.map((operation) => prepareOperation(operation));
-    const namespaces = new Map();
+    // Broad namespace descriptions can be narrowed through the existing methods
+    // selector or discovered through list pages. Every operation must still fit
+    // a complete description on its own; every response keeps the same bound.
     for (const operation of preparedOperations) {
-        const namespace = operation.path.slice(0, operation.path.lastIndexOf("."));
-        const group = namespaces.get(namespace) ?? [];
-        group.push(operation);
-        namespaces.set(namespace, group);
-    }
-    for (const [namespace, group] of namespaces) {
-        const rendered = group.map((operation) => operation.rendered);
-        const index = renderNamespaceIndex(rendered);
-        const full = renderOperationTypes(rendered);
-        if (index.length > maximumDescriptionTypes ||
-            full.length > maximumDescriptionTypes) {
-            throw new ForageError("invalid_input", `Namespace description exceeds the bounded output: ${namespace}`);
+        if (renderOperationTypes([operation.rendered]).length >
+            maximumDescriptionTypes) {
+            throw new ForageError("invalid_input", `Operation description exceeds the bounded output: ${operation.path}`);
         }
     }
     return {

package/dist/json-schema-boundary.d.ts

@@ -2,9 +2,9 @@ import * as z from "zod";
 export declare const schemaDepthLimit = 32;
 export declare const schemaNodeLimit = 50000;
 export declare const isUnsafeSchemaPropertyName: (name: string) => boolean;
-export declare const parameterName: z.ZodString;
+export declare const parameterName: z.ZodLazy<z.ZodString>;
 export declare const thirdPartyText: (limit: number) => z.core.$ZodBranded<z.ZodString, "ThirdPartyText", "out">;
-export declare const jsonSchemaContainer: z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+export declare const jsonSchemaContainer: z.ZodLazy<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
 export declare function jsonSchemaValueInspection(budget?: {
     nodes: number;
 }): z.ZodPipe<z.ZodUnknown, z.ZodTransform<"nodes_limit" | "depth_limit" | "unsafe_name" | null, unknown>>;

package/dist/json-schema-boundary.js

@@ -3,18 +3,15 @@ export const schemaDepthLimit = 32;
 export const schemaNodeLimit = 50_000;
 const unsafePropertyNames = new Set(["__proto__", "constructor", "prototype"]);
 export const isUnsafeSchemaPropertyName = (name) => unsafePropertyNames.has(name);
-export const parameterName = z
+export const parameterName = z.lazy(() => z
     .string()
     .min(1)
     .max(128)
-    .refine((name) => !unsafePropertyNames.has(name));
+    .refine((name) => !unsafePropertyNames.has(name)));
 export const thirdPartyText = (limit) => z.string().max(limit).brand();
 // Maintained decoding of one container level avoids expanding ref-parser's DAG
 // or recursively decoding remote JSON before the domain budget is checked.
-export const jsonSchemaContainer = z.union([
-    z.array(z.unknown()),
-    z.record(z.string(), z.unknown()),
-]);
+export const jsonSchemaContainer = z.lazy(() => z.union([z.array(z.unknown()), z.record(z.string(), z.unknown())]));
 export function jsonSchemaValueInspection(budget = { nodes: 0 }) {
     return z
         .unknown()

package/dist/json-schema-subset.js

@@ -1,6 +1,6 @@
 import * as z from "zod";
 import { jsonSchemaValueInspection, parameterName, thirdPartyText, } from "./json-schema-boundary.js";
-const jsonSchema = z.union([z.record(z.string(), z.json()), z.boolean()]);
+const jsonSchema = z.lazy(() => z.union([z.record(z.string(), z.json()), z.boolean()]));
 /** Decode the supported schema subset before using the shared Zod compiler.
  * Refuse depth over 32, more than 50,000 expanded nodes and reserved keys
  * before recursive decoding. Callers bound transport bytes separately.

package/dist/normalization.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export const jsonValueSchema = z.json();
-const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean()]);
+const jsonPrimitiveSchema = z.lazy(() => z.union([z.string(), z.number(), z.boolean()]));
 /**
  * Narrow an already-parsed JSON value to its object case. The value was
  * validated once at its boundary, so each nested level is told apart by its

package/dist/openapi.d.ts

@@ -38,7 +38,7 @@ export declare const openApiOperationSchema: z.ZodObject<{
     textSource: z.ZodLiteral<"third_party">;
     tags: z.ZodArray<z.core.$ZodBranded<z.ZodString, "ThirdPartyText", "out">>;
     parameters: z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
+        name: z.ZodLazy<z.ZodString>;
         in: z.ZodEnum<{
             header: "header";
             path: "path";

package/dist/openapi.js

@@ -11,6 +11,16 @@ const reservedNames = new Set([
     "prototype",
     ...Object.getOwnPropertyNames(Object.prototype),
 ]);
+const operationMethods = [
+    "get",
+    "head",
+    "options",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "trace",
+];
 const pathTemplate = z
     .string()
     .max(2048)
@@ -304,6 +314,18 @@ function inspectExpansion(source, budget) {
         throw new OpenApiError(refusal, messages[refusal]);
     }
 }
+function inspectOperationCount(paths) {
+    let count = 0;
+    for (const item of Object.values(paths)) {
+        count +=
+            item.$ref !== undefined
+                ? 1
+                : operationMethods.filter((method) => item[method] !== undefined)
+                    .length;
+        if (count > 500)
+            throw new OpenApiError("operations_limit", "The spec exceeds 500 operations");
+    }
+}
 /** Pure intake: the host supplies bounded spec text, never a fetch locator. */
 export async function normalizeOpenApi(source, options = {}) {
     const authParameter = intakeOptions.parse(options).authParameter;
@@ -349,9 +371,9 @@ export async function normalizeOpenApi(source, options = {}) {
     const budget = { nodes: 0 };
     const names = new Set(reservedNames);
     const operations = [];
+    // Refuse oversized catalogs before cloning or compiling individual operations.
+    inspectOperationCount(parsed.paths);
     for (const [path, item] of Object.entries(parsed.paths).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
-        if (operations.length >= 500)
-            throw new OpenApiError("operations_limit", "The spec exceeds 500 operations");
         if (item.$ref !== undefined) {
             operations.push({
                 status: "unsupported",
@@ -362,21 +384,10 @@ export async function normalizeOpenApi(source, options = {}) {
             });
             continue;
         }
-        for (const method of [
-            "get",
-            "head",
-            "options",
-            "post",
-            "put",
-            "patch",
-            "delete",
-            "trace",
-        ]) {
+        for (const method of operationMethods) {
             const raw = item[method];
             if (raw === undefined)
                 continue;
-            if (operations.length >= 500)
-                throw new OpenApiError("operations_limit", "The spec exceeds 500 operations");
             const label = z
                 .object({ operationId: z.string().max(128).optional() })
                 .safeParse(raw);

package/dist/schemas.d.ts

@@ -4,19 +4,19 @@ export declare const maximumSampleEntries = 100;
 export declare const maximumSampleBytes = 4000;
 export declare const maximumSampleDepth = 16;
 /** Input accepted by the pure catalog search seam. */
-export declare const forageSearchInput: z.ZodObject<{
+export declare const forageSearchInput: z.ZodLazy<z.ZodObject<{
     query: z.ZodString;
     maxResults: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** Input accepted by the pure catalog description seam. */
-export declare const forageDescribeInput: z.ZodObject<{
+export declare const forageDescribeInput: z.ZodLazy<z.ZodObject<{
     path: z.ZodString;
     detail: z.ZodDefault<z.ZodEnum<{
         index: "index";
         full: "full";
     }>>;
     methods: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** Exhaustive listing request; cursor is scoped to one immutable catalog and filter. */
 export declare const forageListInput: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
@@ -29,33 +29,33 @@ export declare const searchResultSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     score: z.ZodNumber;
     matchReason: z.ZodOptional<z.ZodString>;
-    sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    sample: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
     capabilityNotes: z.ZodOptional<z.ZodString>;
-    peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    peers: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
         path: z.ZodString;
         capabilityNotes: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 /** Bounded search response envelope. */
-export declare const searchOutputSchema: z.ZodObject<{
+export declare const searchOutputSchema: z.ZodLazy<z.ZodObject<{
     results: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         score: z.ZodNumber;
         matchReason: z.ZodOptional<z.ZodString>;
-        sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        sample: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
         capabilityNotes: z.ZodOptional<z.ZodString>;
-        peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        peers: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
             path: z.ZodString;
             capabilityNotes: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>>;
     total: z.ZodNumber;
     truncated: z.ZodBoolean;
     topScore: z.ZodNumber;
     margin: z.ZodNumber;
     catalogStamp: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** One exhaustive page, using the exact search operation summary schema. */
 export declare const listOutputSchema: z.ZodObject<{
     results: z.ZodArray<z.ZodObject<{
@@ -63,19 +63,19 @@ export declare const listOutputSchema: z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         score: z.ZodNumber;
         matchReason: z.ZodOptional<z.ZodString>;
-        sample: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        sample: z.ZodOptional<z.ZodLazy<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>>;
         capabilityNotes: z.ZodOptional<z.ZodString>;
-        peers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        peers: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
             path: z.ZodString;
             capabilityNotes: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
+        }, z.core.$strip>>>>;
     }, z.core.$strip>>;
     total: z.ZodNumber;
     nextCursor: z.ZodNullable<z.ZodString>;
     catalogStamp: z.ZodString;
 }, z.core.$strip>;
 /** Deterministic description response. */
-export declare const describeOutputSchema: z.ZodObject<{
+export declare const describeOutputSchema: z.ZodLazy<z.ZodObject<{
     path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     types: z.ZodString;
@@ -85,9 +85,9 @@ export declare const describeOutputSchema: z.ZodObject<{
         operation: "operation";
     }>;
     usage: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** Closed failure vocabulary for malformed or absent catalog requests. */
-export declare const forageFailureSchema: z.ZodObject<{
+export declare const forageFailureSchema: z.ZodLazy<z.ZodObject<{
     code: z.ZodEnum<{
         empty_query: "empty_query";
         empty_catalog: "empty_catalog";
@@ -96,7 +96,7 @@ export declare const forageFailureSchema: z.ZodObject<{
         invalid_input: "invalid_input";
     }>;
     message: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** Options Forage passes when it asks a schema for its JSON Schema. */
 export type JsonSchemaTarget = Readonly<{
     target: "draft-2020-12";
@@ -117,10 +117,10 @@ export type JsonSchemaSource = Readonly<{
     }>;
 }>;
 /** A secret-free, callback-free operation descriptor. */
-export declare const operationSchema: z.ZodObject<{
+export declare const operationSchema: z.ZodLazy<z.ZodObject<{
     path: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    input: z.ZodCustom<Readonly<{
+    input: z.ZodLazy<z.ZodCustom<Readonly<{
         "~standard": Readonly<{
             jsonSchema: Readonly<{
                 /** JSON Schema of the value the operation accepts. */
@@ -138,8 +138,8 @@ export declare const operationSchema: z.ZodObject<{
                 output: (options: JsonSchemaTarget) => object;
             }>;
         }>;
-    }>>;
-    output: z.ZodOptional<z.ZodCustom<Readonly<{
+    }>>>;
+    output: z.ZodOptional<z.ZodLazy<z.ZodCustom<Readonly<{
         "~standard": Readonly<{
             jsonSchema: Readonly<{
                 /** JSON Schema of the value the operation accepts. */
@@ -157,17 +157,17 @@ export declare const operationSchema: z.ZodObject<{
                 output: (options: JsonSchemaTarget) => object;
             }>;
         }>;
-    }>>>;
+    }>>>>;
     capabilityNotes: z.ZodOptional<z.ZodString>;
     instructions: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$strip>>;
 /** Input used to construct one immutable catalog revision. */
-export declare const catalogInputSchema: z.ZodObject<{
+export declare const catalogInputSchema: z.ZodLazy<z.ZodObject<{
     revision: z.ZodString;
-    operations: z.ZodArray<z.ZodObject<{
+    operations: z.ZodArray<z.ZodLazy<z.ZodObject<{
         path: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
-        input: z.ZodCustom<Readonly<{
+        input: z.ZodLazy<z.ZodCustom<Readonly<{
             "~standard": Readonly<{
                 jsonSchema: Readonly<{
                     /** JSON Schema of the value the operation accepts. */
@@ -185,8 +185,8 @@ export declare const catalogInputSchema: z.ZodObject<{
                     output: (options: JsonSchemaTarget) => object;
                 }>;
             }>;
-        }>>;
-        output: z.ZodOptional<z.ZodCustom<Readonly<{
+        }>>>;
+        output: z.ZodOptional<z.ZodLazy<z.ZodCustom<Readonly<{
             "~standard": Readonly<{
                 jsonSchema: Readonly<{
                     /** JSON Schema of the value the operation accepts. */
@@ -204,11 +204,11 @@ export declare const catalogInputSchema: z.ZodObject<{
                     output: (options: JsonSchemaTarget) => object;
                 }>;
             }>;
-        }>>>;
+        }>>>>;
         capabilityNotes: z.ZodOptional<z.ZodString>;
         instructions: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>>;
 /** Parsed search request type. */
 export type ForageSearchInput = z.input<typeof forageSearchInput>;
 /** Exhaustive listing request type. */

package/dist/schemas.js

@@ -27,9 +27,7 @@ function jsonDepth(value, depth) {
     }
     return maximum;
 }
-const sampleSchema = z
-    .record(z.string(), z.json())
-    .superRefine((value, context) => {
+const sampleSchema = z.lazy(() => z.record(z.string(), z.json()).superRefine((value, context) => {
     if (Object.keys(value).length > maximumSampleEntries) {
         context.addIssue({
             code: "custom",
@@ -48,18 +46,18 @@ const sampleSchema = z
             message: "Sample exceeds the depth bound",
         });
     }
-});
+}));
 /** Input accepted by the pure catalog search seam. */
-export const forageSearchInput = z.object({
+export const forageSearchInput = z.lazy(() => z.object({
     query: z.string().max(200),
     maxResults: z.number().int().min(1).max(50).default(50),
-});
+}));
 /** Input accepted by the pure catalog description seam. */
-export const forageDescribeInput = z.object({
+export const forageDescribeInput = z.lazy(() => z.object({
     path: z.string().max(160),
     detail: z.enum(["index", "full"]).default("full"),
     methods: z.array(z.string().max(80)).max(50).optional(),
-});
+}));
 /** Exhaustive listing request; cursor is scoped to one immutable catalog and filter. */
 export const forageListInput = z.object({
     cursor: z.string().max(400).optional(),
@@ -71,10 +69,10 @@ export const forageListInput = z.object({
         .regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/)
         .optional(),
 });
-const peerSchema = z.object({
+const peerSchema = z.lazy(() => z.object({
     path: z.string().max(160),
     capabilityNotes: z.string().max(500).optional(),
-});
+}));
 /** One ranked operation in a search response. */
 export const searchResultSchema = z.object({
     path: z.string().max(160),
@@ -86,7 +84,7 @@ export const searchResultSchema = z.object({
     peers: z.array(peerSchema).max(1000).optional(),
 });
 /** Bounded search response envelope. */
-export const searchOutputSchema = z.object({
+export const searchOutputSchema = z.lazy(() => z.object({
     results: z.array(searchResultSchema).max(50),
     total: z.number().int().min(0).max(maximumCatalogOperations),
     truncated: z.boolean(),
@@ -96,7 +94,7 @@ export const searchOutputSchema = z.object({
         .string()
         .length(16)
         .regex(/^[0-9a-f]{16}$/),
-});
+}));
 /** One exhaustive page, using the exact search operation summary schema. */
 export const listOutputSchema = z.object({
     results: z.array(searchResultSchema).max(50),
@@ -108,7 +106,7 @@ export const listOutputSchema = z.object({
         .regex(/^[0-9a-f]{16}$/),
 });
 /** Deterministic description response. */
-export const describeOutputSchema = z.object({
+export const describeOutputSchema = z.lazy(() => z.object({
     path: z.string().max(160),
     description: z.string().max(1000).optional(),
     types: z.string().max(20000),
@@ -119,9 +117,9 @@ export const describeOutputSchema = z.object({
         .optional(),
     kind: z.enum(["module", "operation"]),
     usage: z.string().max(300).optional(),
-});
+}));
 /** Closed failure vocabulary for malformed or absent catalog requests. */
-export const forageFailureSchema = z.object({
+export const forageFailureSchema = z.lazy(() => z.object({
     code: z.enum([
         "empty_query",
         "empty_catalog",
@@ -130,27 +128,27 @@ export const forageFailureSchema = z.object({
         "invalid_input",
     ]),
     message: z.string().max(1000),
-});
-const jsonSchemaDescriber = z.object({
+}));
+const jsonSchemaDescriber = z.lazy(() => z.object({
     "~standard": z.object({
         jsonSchema: z.object({
             input: z.instanceof(Function),
             output: z.instanceof(Function),
         }),
     }),
-});
-const jsonSchemaSource = z.custom((value) => jsonSchemaDescriber.safeParse(value).success, "Expected a Standard JSON Schema");
+}));
+const jsonSchemaSource = z.lazy(() => z.custom((value) => jsonSchemaDescriber.safeParse(value).success, "Expected a Standard JSON Schema"));
 /** A secret-free, callback-free operation descriptor. */
-export const operationSchema = z.object({
+export const operationSchema = z.lazy(() => z.object({
     path: z.string().min(3).max(160).regex(pathPattern),
     description: z.string().max(1000).optional(),
     input: jsonSchemaSource,
     output: jsonSchemaSource.optional(),
     capabilityNotes: z.string().max(500).optional(),
     instructions: z.string().max(1000).optional(),
-});
+}));
 /** Input used to construct one immutable catalog revision. */
-export const catalogInputSchema = z.object({
+export const catalogInputSchema = z.lazy(() => z.object({
     revision: z.string().min(1).max(160),
     operations: z.array(operationSchema).max(maximumCatalogOperations),
-});
+}));

package/docs/api/index.md

@@ -342,12 +342,14 @@ Narrow convenience namespace for the package's public seams.
 ### forageSearchInput
 
 ```ts
-const forageSearchInput: ZodObject<
-  {
-    query: ZodString;
-    maxResults: ZodDefault<ZodNumber>;
-  },
-  $strip
+const forageSearchInput: ZodLazy<
+  ZodObject<
+    {
+      query: ZodString;
+      maxResults: ZodDefault<ZodNumber>;
+    },
+    $strip
+  >
 >;
 ```
 
@@ -358,18 +360,20 @@ Input accepted by the pure catalog search seam.
 ### forageDescribeInput
 
 ```ts
-const forageDescribeInput: ZodObject<
-  {
-    path: ZodString;
-    detail: ZodDefault<
-      ZodEnum<{
-        index: "index";
-        full: "full";
-      }>
-    >;
-    methods: ZodOptional<ZodArray<ZodString>>;
-  },
-  $strip
+const forageDescribeInput: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      detail: ZodDefault<
+        ZodEnum<{
+          index: "index";
+          full: "full";
+        }>
+      >;
+      methods: ZodOptional<ZodArray<ZodString>>;
+    },
+    $strip
+  >
 >;
 ```
 
@@ -404,16 +408,18 @@ const searchResultSchema: ZodObject<
     description: ZodOptional<ZodString>;
     score: ZodNumber;
     matchReason: ZodOptional<ZodString>;
-    sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>;
+    sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
     capabilityNotes: ZodOptional<ZodString>;
     peers: ZodOptional<
       ZodArray<
-        ZodObject<
-          {
-            path: ZodString;
-            capabilityNotes: ZodOptional<ZodString>;
-          },
-          $strip
+        ZodLazy<
+          ZodObject<
+            {
+              path: ZodString;
+              capabilityNotes: ZodOptional<ZodString>;
+            },
+            $strip
+          >
         >
       >
     >;
@@ -429,40 +435,25 @@ One ranked operation in a search response.
 ### searchOutputSchema
 
 ```ts
-const searchOutputSchema: ZodObject<
-  {
-    results: ZodArray<
-      ZodObject<
-        {
-          path: ZodString;
-          description: ZodOptional<ZodString>;
-          score: ZodNumber;
-          matchReason: ZodOptional<ZodString>;
-          sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>;
-          capabilityNotes: ZodOptional<ZodString>;
-          peers: ZodOptional<
-            ZodArray<
-              ZodObject<
-                {
-                  path: ZodString;
-                  capabilityNotes: ZodOptional<ZodString>;
-                },
-                $strip
-              >
-            >
-          >;
-        },
-        $strip
-      >
-    >;
-    total: ZodNumber;
-    truncated: ZodBoolean;
-    topScore: ZodNumber;
-    margin: ZodNumber;
-    catalogStamp: ZodString;
-  },
-  $strip
->;
+const searchOutputSchema: ZodLazy<ZodObject<{
+  results: ZodArray<ZodObject<{
+     path: ZodString;
+     description: ZodOptional<ZodString>;
+     score: ZodNumber;
+     matchReason: ZodOptional<ZodString>;
+     sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
+     capabilityNotes: ZodOptional<ZodString>;
+     peers: ZodOptional<ZodArray<ZodLazy<ZodObject<{
+        path: ...;
+        capabilityNotes: ...;
+     }, $strip>>>>;
+  }, $strip>>;
+  total: ZodNumber;
+  truncated: ZodBoolean;
+  topScore: ZodNumber;
+  margin: ZodNumber;
+  catalogStamp: ZodString;
+}, $strip>>;
 ```
 
 Bounded search response envelope.
@@ -472,38 +463,23 @@ Bounded search response envelope.
 ### listOutputSchema
 
 ```ts
-const listOutputSchema: ZodObject<
-  {
-    results: ZodArray<
-      ZodObject<
-        {
-          path: ZodString;
-          description: ZodOptional<ZodString>;
-          score: ZodNumber;
-          matchReason: ZodOptional<ZodString>;
-          sample: ZodOptional<ZodRecord<ZodString, ZodJSONSchema>>;
-          capabilityNotes: ZodOptional<ZodString>;
-          peers: ZodOptional<
-            ZodArray<
-              ZodObject<
-                {
-                  path: ZodString;
-                  capabilityNotes: ZodOptional<ZodString>;
-                },
-                $strip
-              >
-            >
-          >;
-        },
-        $strip
-      >
-    >;
-    total: ZodNumber;
-    nextCursor: ZodNullable<ZodString>;
-    catalogStamp: ZodString;
-  },
-  $strip
->;
+const listOutputSchema: ZodObject<{
+  results: ZodArray<ZodObject<{
+     path: ZodString;
+     description: ZodOptional<ZodString>;
+     score: ZodNumber;
+     matchReason: ZodOptional<ZodString>;
+     sample: ZodOptional<ZodLazy<ZodRecord<ZodString, ZodJSONSchema>>>;
+     capabilityNotes: ZodOptional<ZodString>;
+     peers: ZodOptional<ZodArray<ZodLazy<ZodObject<{
+        path: ZodString;
+        capabilityNotes: ZodOptional<...>;
+     }, $strip>>>>;
+  }, $strip>>;
+  total: ZodNumber;
+  nextCursor: ZodNullable<ZodString>;
+  catalogStamp: ZodString;
+}, $strip>;
 ```
 
 One exhaustive page, using the exact search operation summary schema.
@@ -513,19 +489,21 @@ One exhaustive page, using the exact search operation summary schema.
 ### describeOutputSchema
 
 ```ts
-const describeOutputSchema: ZodObject<
-  {
-    path: ZodString;
-    description: ZodOptional<ZodString>;
-    types: ZodString;
-    inputSchema: ZodOptional<ZodJSONSchema>;
-    kind: ZodEnum<{
-      module: "module";
-      operation: "operation";
-    }>;
-    usage: ZodOptional<ZodString>;
-  },
-  $strip
+const describeOutputSchema: ZodLazy<
+  ZodObject<
+    {
+      path: ZodString;
+      description: ZodOptional<ZodString>;
+      types: ZodString;
+      inputSchema: ZodOptional<ZodJSONSchema>;
+      kind: ZodEnum<{
+        module: "module";
+        operation: "operation";
+      }>;
+      usage: ZodOptional<ZodString>;
+    },
+    $strip
+  >
 >;
 ```
 
@@ -536,18 +514,20 @@ Deterministic description response.
 ### forageFailureSchema
 
 ```ts
-const forageFailureSchema: ZodObject<
-  {
-    code: ZodEnum<{
-      empty_query: "empty_query";
-      empty_catalog: "empty_catalog";
-      unknown_target: "unknown_target";
-      duplicate_operation: "duplicate_operation";
-      invalid_input: "invalid_input";
-    }>;
-    message: ZodString;
-  },
-  $strip
+const forageFailureSchema: ZodLazy<
+  ZodObject<
+    {
+      code: ZodEnum<{
+        empty_query: "empty_query";
+        empty_catalog: "empty_catalog";
+        unknown_target: "unknown_target";
+        duplicate_operation: "duplicate_operation";
+        invalid_input: "invalid_input";
+      }>;
+      message: ZodString;
+    },
+    $strip
+  >
 >;
 ```
 
@@ -558,42 +538,36 @@ Closed failure vocabulary for malformed or absent catalog requests.
 ### operationSchema
 
 ```ts
-const operationSchema: ZodObject<{
+const operationSchema: ZodLazy<ZodObject<{
   path: ZodString;
   description: ZodOptional<ZodString>;
-  input: ZodCustom<Readonly<{
+  input: ZodLazy<ZodCustom<Readonly<{
      ~standard: Readonly<{
         jsonSchema: Readonly<{
-           input: (options) => object;
-           output: (options) => object;
+           input: ...;
+           output: ...;
         }>;
      }>;
    }>, Readonly<{
      ~standard: Readonly<{
         jsonSchema: Readonly<{
-           input: (options) => object;
-           output: (options) => object;
+           input: ...;
+           output: ...;
         }>;
      }>;
-  }>>;
-  output: ZodOptional<ZodCustom<Readonly<{
+  }>>>;
+  output: ZodOptional<ZodLazy<ZodCustom<Readonly<{
      ~standard: Readonly<{
-        jsonSchema: Readonly<{
-           input: (options) => ...;
-           output: (options) => ...;
-        }>;
+        jsonSchema: Readonly<...>;
      }>;
    }>, Readonly<{
      ~standard: Readonly<{
-        jsonSchema: Readonly<{
-           input: (options) => ...;
-           output: (options) => ...;
-        }>;
+        jsonSchema: Readonly<...>;
      }>;
-  }>>>;
+  }>>>>;
   capabilityNotes: ZodOptional<ZodString>;
   instructions: ZodOptional<ZodString>;
-}, $strip>;
+}, $strip>>;
 ```
 
 A secret-free, callback-free operation descriptor.
@@ -603,33 +577,21 @@ A secret-free, callback-free operation descriptor.
 ### catalogInputSchema
 
 ```ts
-const catalogInputSchema: ZodObject<{
+const catalogInputSchema: ZodLazy<ZodObject<{
   revision: ZodString;
-  operations: ZodArray<ZodObject<{
+  operations: ZodArray<ZodLazy<ZodObject<{
      path: ZodString;
      description: ZodOptional<ZodString>;
-     input: ZodCustom<Readonly<{
-        ~standard: Readonly<{
-           jsonSchema: Readonly<...>;
-        }>;
+     input: ZodLazy<ZodCustom<Readonly<{
+        ~standard: ...;
       }>, Readonly<{
-        ~standard: Readonly<{
-           jsonSchema: Readonly<...>;
-        }>;
-     }>>;
-     output: ZodOptional<ZodCustom<Readonly<{
-        ~standard: Readonly<{
-           jsonSchema: ...;
-        }>;
-      }>, Readonly<{
-        ~standard: Readonly<{
-           jsonSchema: ...;
-        }>;
+        ~standard: ...;
      }>>>;
+     output: ZodOptional<ZodLazy<ZodCustom<Readonly<...>, Readonly<...>>>>;
      capabilityNotes: ZodOptional<ZodString>;
      instructions: ZodOptional<ZodString>;
-  }, $strip>>;
-}, $strip>;
+  }, $strip>>>;
+}, $strip>>;
 ```
 
 Input used to construct one immutable catalog revision.
@@ -715,8 +677,12 @@ function appToolFamilySchemas(
   call: string;
   effect: "write" | "external" | "read";
   requires: readonly (
+    | "approvals"
     | "agent.list"
     | "agent.manage"
+    | "agent.rename"
+    | "agent.avatar"
+    | "agent.toolPolicy"
     | "agent.read"
     | "agent.send"
     | "computer.list"
@@ -760,15 +726,17 @@ arguments; this projection supplies neither defaults nor handlers.
 #### Returns
 
 \| \{ `name`: `string`; `call`: `string`; `effect`: `"write"` \| `"external"` \|
-`"read"`; `requires`: readonly ( \| `"agent.list"` \| `"agent.manage"` \|
-`"agent.read"` \| `"agent.send"` \| `"computer.list"` \| `"computer.readFile"`
-\| `"computer.writeFile"` \| `"computer.execute"` \| `"llm.generation"` \|
-`"media.generation"` \| `"games:servers"` \| `"git.repository"` \| `"apps.open"`
-\| `"apps.call"` \| `"app.storage"` \| `"app.events.emit"` \|
-`"team.workbenchHost"` \| `"marketplace.browse"` \| `"marketplace.purchase"` \|
-`"workflow.run"` \| `"workflow.publish"` \| `"workflow.arm"` \| `"world"` \|
-`"channels.read"` \| `"channels.personal.manage"`)[]; `kind`: `"ready"` \|
-`"unindexed"`; `tools`: `object`[]; \} \| `null`
+`"read"`; `requires`: readonly ( \| `"approvals"` \| `"agent.list"` \|
+`"agent.manage"` \| `"agent.rename"` \| `"agent.avatar"` \| `"agent.toolPolicy"`
+\| `"agent.read"` \| `"agent.send"` \| `"computer.list"` \|
+`"computer.readFile"` \| `"computer.writeFile"` \| `"computer.execute"` \|
+`"llm.generation"` \| `"media.generation"` \| `"games:servers"` \|
+`"git.repository"` \| `"apps.open"` \| `"apps.call"` \| `"app.storage"` \|
+`"app.events.emit"` \| `"team.workbenchHost"` \| `"marketplace.browse"` \|
+`"marketplace.purchase"` \| `"workflow.run"` \| `"workflow.publish"` \|
+`"workflow.arm"` \| `"world"` \| `"channels.read"` \|
+`"channels.personal.manage"`)[]; `kind`: `"ready"` \| `"unindexed"`; `tools`:
+`object`[]; \} \| `null`
 
 ---
 

package/docs/api/openapi.md

@@ -197,7 +197,7 @@ const openApiOperationSchema: ZodObject<
     parameters: ZodArray<
       ZodObject<
         {
-          name: ZodString;
+          name: ZodLazy<ZodString>;
           in: ZodEnum<{
             header: "header";
             path: "path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/forage",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Pure immutable Zod-typed capability discovery",
   "type": "module",
@@ -29,7 +29,7 @@
   ],
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "16.0.3",
-    "@fungi.computer/puffball": "0.0.2",
+    "@fungi.computer/puffball": "0.2.0",
     "yaml": "2.9.0",
     "zod": "4.4.3"
   },