@fungi.computer/forage 0.1.0 → 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.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 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.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 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.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")[];
+    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/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/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/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.1.0",
+  "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.1.0",
+    "@fungi.computer/puffball": "0.2.0",
     "yaml": "2.9.0",
     "zod": "4.4.3"
   },