@fungi.computer/forage 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This package contains behavior re-expressed from @cloudflare/codemode (MIT).
+Copyright (c) 2025 Cloudflare, Inc. https://github.com/cloudflare/agents

package/README.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+# Forage (`@fungi.computer/forage`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Forage lists, searches and describes a catalog of operations that a host has
+already provided, so a caller or a model can find the right one by name or by
+description. It helps a caller discover a capability. It does not execute that
+capability or grant permission to use it.
+
+## Install or set up
+
+```sh
+npm install @fungi.computer/forage
+```
+
+The package ships ESM only and depends on Zod, YAML, JSON Schema Ref Parser and
+[App Release](../puffball/README.md) at runtime. Each operation's input and
+output is any schema that implements Standard JSON Schema, such as a Zod 4
+schema; Forage only renders the JSON Schema it describes. Its discovery
+entrypoint is `@fungi.computer/forage`; host-only OpenAPI intake is
+`@fungi.computer/forage/openapi`. The pure JSON-Schema subset decoder is
+`@fungi.computer/forage/json-schema-subset`: `jsonSchemaSubset()` validates
+remote schemas before the shared `jsonSchemaToZod` compiler reads them. The
+subset rejects references, regular-expression constraints and reserved property
+names anywhere in the schema or JSON values. The decoder refuses depth over 32
+and more than 50,000 expanded nodes before recursive decoding; callers bound
+transport bytes separately.
+
+## Quick start
+
+This illustrative example creates an immutable catalog, searches it, and
+describes one operation:
+
+```ts
+import { Forage } from "@fungi.computer/forage";
+import { z } from "zod";
+
+const catalog = Forage.createCatalog({
+  revision: "run-1",
+  operations: [
+    {
+      path: "files.read",
+      description: "Read a file",
+      input: z.object({ path: z.string() }),
+    },
+  ],
+});
+
+const matches = catalog.search({ query: "read" });
+const description = catalog.describe({ path: "files.read" });
+const firstPage = catalog.list({ limit: 25 });
+```
+
+The catalog tests exercise creation, search, description, and stable stamps in
+[`test/catalog.test.ts`](test/catalog.test.ts).
+
+## Core concepts
+
+A catalog has a caller-supplied revision and a set of operations. Each operation
+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.
+
+`search` ranks matching operations. `describe` returns a bounded TypeScript
+description for one operation or a namespace. Operation descriptions also
+include `inputSchema`, projected from the same validator through Standard JSON
+Schema, so callers can see length, range and array bounds that TypeScript cannot
+express. Paths may have any namespace depth; descriptions declare a callable
+nested `env` with the operation's input and output types. Generated type aliases
+separate every path segment with `$`: `computer.echo` declares
+`computer$echo_Input` and `computer$echo_Output`, and the nested
+`computers.local.files.read` declares `computers$local$files$read_Input` and
+`computers$local$files$read_Output`. This keeps paths with underscores distinct
+from nested paths. The same rule applies at every depth. `stamp()` returns a
+stable identity for the sorted catalog metadata, including schema projections,
+capability notes and instructions.
+
+## Exhaustive listing
+
+`forage.list({limit?, cursor?, namespace?})` (or `catalog.list` directly)
+enumerates every registered operation exactly once. Ordering is by namespace
+(the first path segment), then full operation path, compared by UTF-16 code
+units, not locale. Registration order never changes it. Equivalent operations
+are not merged into peers, unlike search.
+
+Each page has `results`, `total`, `catalogStamp` and `nextCursor`. Results use
+the same summary schema as search (path, description, sample and capability
+notes); score is zero because listing does not rank matches. The default and
+maximum limit is 50; the minimum is 1. Follow `nextCursor` until it is null.
+Total counts all operations under the selected namespace, including its nested
+namespaces, not just this page. For example, `namespace: "apps.bazaar"` also
+selects `apps.bazaar.windows.open`. An absent namespace means every namespace;
+an unknown namespace returns an empty page with total zero.
+
+Cursors are opaque to callers and belong to one catalog stamp and namespace
+filter. Reusing a cursor after either changes fails explicitly. Begin a fresh
+listing instead. A host that narrows a guest's bound operations filters the
+existing summaries and uses the same `listOperations` owner before paging. It
+does not introduce another registry or leak unbound paths. Search and describe
+keep their existing contracts.
+
+## OpenAPI intake
+
+Import `normalizeOpenApi` and `parseOpenApiTable` from
+`@fungi.computer/forage/openapi` on the host. This entrypoint uses the
+Node-oriented reference resolver; neutral Worker/guest discovery consumers use
+the core entrypoint without importing intake.
+
+`normalizeOpenApi(specText, {authParameter?})` accepts owner-supplied OpenAPI
+3.0/3.1 JSON or YAML. It returns server and authentication hints plus supported
+operations and explicit unsupported-operation reasons. It performs no fetch,
+credential access or execution. Swagger 2 must be converted first.
+
+Intake is bounded to 2 MiB, depth 32, 50,000 nodes and 500 operations. YAML
+aliases and external references are refused. Local references are resolved by
+JSON Schema Ref Parser with file and HTTP resolvers disabled; recursive schemas
+are unsupported. The expansion budget counts every shared-reference occurrence
+before recursive schema decoding or compilation. Input and declared JSON success
+schemas use the same `jsonSchemaToZod` compiler as App methods. Schemas with
+constraints the supported compiler subset cannot preserve are unsupported,
+rather than widened.
+
+Operations expose scalar path/query/header parameters with default OpenAPI
+serialization and an optional JSON `body`. Other serialization styles, body
+media, referenced Path Items and TRACE are unsupported. Required path parameters
+must match the path. Reserved transport headers, declared API-key parameters and
+an owner-provided `authParameter` cannot become guest input. GET/HEAD/OPTIONS
+are reads; other supported methods are writes. Sanitized method names are unique
+and reserve `describe`, `search`, `then` and JavaScript object member names.
+Paths cannot change the origin, traverse dot segments or contain query/fragment
+syntax or encoded separators. Header names follow RFC token grammar and exclude
+transport, forwarding, credential and method-override headers. Prototype names
+are refused before decoding. Regex keywords (`pattern`, `patternProperties`) and
+all `format` constraints are unsupported. OpenAPI 3.0 `nullable` is supported;
+OpenAPI 3.1 must use null types instead. Unknown schema keywords are refused.
+
+Provider-authored descriptions/schema annotations are bounded to 2,048
+characters, titles to 200, and tags to 16 entries of 64 characters each.
+Operations mark their text as `third_party`; hosts must frame it as data. Server
+hints require HTTPS without userinfo; relative hints remain relative to the
+retrieved spec. Hints confer no network admission and do not select a credential
+destination: that belongs to the private Veil execution door.
+
+`parseOpenApiTable(selectedOperations)` decodes 1–64 supported methods before
+storage, rejects duplicate names and tables above 512 KiB, and returns a stable
+SHA-256 digest. It stores normalized schemas and call shapes, never raw specs or
+credentials. A compiler result with no declared output constraint still needs
+the execution owner's bounded JSON output decoder. Neither intake nor table
+validation grants execution permission or validates a server's network
+admission. A connector owner selects from its server-built preview by HTTP
+method + path, never client-supplied operation bodies or generated method names;
+collision suffixes can change when the spec changes.
+
+The pure intake and selected-table laws are exercised in
+[`test/openapi.test.ts`](test/openapi.test.ts).
+
+## API reference
+
+### App backend methods
+
+`appApiOperations(bindingName, api)` projects a decoded App Release API into
+operations such as `PRINTS.generate`, called as `env.PRINTS.generate()`; a
+dotted method `desktop.arrange` is `env.TOURTOIS.desktop.arrange()`. The App
+author generates that API through Agar during the build; Forage uses the same
+declaration instead of a second method list. The host supplies the
+installation's binding name and can project the same API under an explicit role
+alias.
+
+`appMethodSchemas(api)` supplies the same converted input and output schemas,
+with the declared description, effect and requirements, to execution owners.
+`appToolSchemas(api)` uses the same converter after excluding methods marked
+`hidden: true`. `appApiOperations` and host Agent/MCP discovery share this
+filtered projection. `appMethodSchemas` keeps every declared method for direct
+RPC validators. Converting a declaration grants no authority to execute it.
+
+Each visible method is searchable and has input and output types in `describe`.
+Describing `PRINTS` returns the callable nested `env` declaration with
+asynchronous methods. The projection includes declared effects and capability
+requirements as discovery notes. It supplies no execution handler or permission
+grant.
+
+The generated-declaration round trip and nested descriptions are exercised by
+Hub’s `app-api-discovery` test.
+
+See the generated [Forage API reference](docs/api/README.md). It covers
+`Forage.createCatalog`, the `createCatalog` function, operation definitions, and
+the search and description result types.
+
+## Examples and checks
+
+The existing catalog suite covers validation, deterministic search and
+description, and catalog stamps. Run it with:
+
+```sh
+pnpm --filter @fungi.computer/forage test
+```
+
+## Limits and errors
+
+Forage is immutable discovery data. It has no executor, credentials,
+authorization state, refresh operation, or host client. A result from `search`
+or `describe` does not run the operation. An execution owner must make that
+decision separately.
+
+Catalogs must contain at least one operation and cannot repeat an operation
+path. Forage bounds metadata and rendered descriptions. Invalid or oversized
+input throws `ForageError`. The stable stamp identifies the immutable discovery
+snapshot, not authority to execute its operations.
+
+## Contribute and license
+
+Forage is MIT licensed. See [`LICENSE`](LICENSE). Its retained source
+attribution and notice are in [`THIRD_PARTY_NOTICES`](THIRD_PARTY_NOTICES).
+
+## Dynamic App tool schemas
+
+`appToolFamilySchemas(api, reply)` validates a dynamic listing through its
+signed method output, then compiles each row's input and output with the
+ordinary App schema decoder. It returns the family name, call method, declared
+effect and requirements, plus rows and their validators. An `unindexed` listing
+has no tools. App-owned selectors remain row data; the host constructs the
+invocation through that App's call owner. The projection supplies no handlers,
+binding defaults or authority. SDK modules and labelled MCP tools can consume
+the same rows and validators.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,13 @@
+Forage re-expresses discovery behavior from @cloudflare/codemode.
+Copyright (c) 2025 Cloudflare, Inc.; MIT License.
+Source: https://github.com/cloudflare/agents
+
+YAML 2.9.0 (yaml): ISC License.
+Copyright Eemeli Aro <eemeli@gmail.com>.
+Source: https://github.com/eemeli/yaml
+License: https://github.com/eemeli/yaml/blob/v2.9.0/LICENSE
+
+JSON Schema Ref Parser 16.0.3: MIT License.
+Copyright (c) 2015 James Messinger.
+Source: https://github.com/APIDevTools/json-schema-ref-parser
+License: https://github.com/APIDevTools/json-schema-ref-parser/blob/v16.0.3/LICENSE

package/dist/app-api.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { AppApi } from "@fungi.computer/puffball";
+import type { Operation } from "./schemas.js";
+/** The shared JSON-Schema compiler for App methods and OpenAPI operations. */
+export declare function jsonSchemaToZod(source: unknown, defaultTarget?: "draft-2020-12" | "openapi-3.0"): z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+/** Compile App validators and their Standard JSON Schema descriptions.
+ * Validation enforces both the declaration and JSON-only values; discovery
+ * describes the declaration without adding JSON guard nesting.
+ * Agar's emitted output already includes Pending for opted-in methods. */
+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 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">;
+    };
+};
+/** Compile discoverable App methods only; direct RPC validation uses appMethodSchemas. */
+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 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">;
+    };
+};
+/** 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. */
+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")[];
+    kind: "ready" | "unindexed";
+    tools: {
+        row: {
+            [x: string]: z.core.util.JSONType;
+            tool: string;
+            title: string;
+            description: string;
+            input: Record<string, z.core.util.JSONType>;
+            output: Record<string, z.core.util.JSONType>;
+            call: Record<string, z.core.util.JSONType>;
+        };
+        description: string;
+        input: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
+        output: Pick<z.ZodType<z.core.util.JSONType, unknown, z.core.$ZodTypeInternals<z.core.util.JSONType, unknown>>, "~standard" | "parse" | "safeParse">;
+    }[];
+} | null;
+/**
+ * Project an already decoded Release API into discovery data with the same
+ * paths the Agent catalog uses (`PRINTS.generate`, called as
+ * `env.PRINTS.generate()`). The introduction owner supplies the installation's
+ * binding name; this function grants no access and supplies no execution
+ * handler. Role aliases can project the same API.
+ */
+export declare function appApiOperations(name: string, api: AppApi): readonly Operation[];

package/dist/app-api.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+const bindingName = 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()]);
+/** 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 });
+}
+/** Validate JSON with Zod; describe the declaration without the redundant JSON guard. */
+function appMethodSchema(source) {
+    const declared = jsonSchemaToZod(source);
+    const validator = z.intersection(declared, z.json());
+    return {
+        parse: (value, options) => validator.parse(value, options),
+        safeParse: (value, options) => validator.safeParse(value, options),
+        "~standard": {
+            ...validator["~standard"],
+            jsonSchema: declared["~standard"].jsonSchema,
+        },
+    };
+}
+/** Compile App validators and their Standard JSON Schema descriptions.
+ * Validation enforces both the declaration and JSON-only values; discovery
+ * describes the declaration without adding JSON guard nesting.
+ * Agar's emitted output already includes Pending for opted-in methods. */
+export function appMethodSchemas(api) {
+    return Object.fromEntries(Object.entries(api.methods).map(([method, declaration]) => [
+        method,
+        {
+            description: declaration.description,
+            effect: declaration.effect,
+            requires: declaration.requires,
+            pending: declaration.pending,
+            input: appMethodSchema(declaration.input),
+            output: appMethodSchema(declaration.output),
+        },
+    ]));
+}
+/** Compile discoverable App methods only; direct RPC validation uses appMethodSchemas. */
+export function appToolSchemas(api) {
+    return appMethodSchemas({
+        ...api,
+        methods: Object.fromEntries(Object.entries(api.methods).filter(([, method]) => method.hidden !== true)),
+    });
+}
+const familyRow = z
+    .object({
+    tool: bindingName,
+    title: z.string().max(120),
+    description: z.string().max(1000),
+    input: z.record(z.string(), z.json()),
+    output: z.record(z.string(), z.json()),
+    // Opaque extra arguments the declaring App wants merged with the
+    // caller's own `input` when a host dispatches to the family's `call`
+    // method (e.g. which of its own resources this row identifies, and any
+    // App-to-App bindings only the declaring App can resolve). Required, so
+    // a row that needs none still says so with `{}`. A host spreads this
+    // 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", [
+    z.strictObject({ kind: z.literal("unindexed") }),
+    z.strictObject({
+        kind: z.literal("ready"),
+        tools: z
+            .array(familyRow)
+            .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. */
+export function appToolFamilySchemas(api, reply) {
+    const family = api.toolFamily;
+    if (family === undefined)
+        return null;
+    const list = api.methods[family.list];
+    const call = api.methods[family.call];
+    if (list === undefined || call === undefined)
+        throw new Error("Tool family references undeclared methods");
+    const inventory = familyInventory.parse(appMethodSchema(list.output).parse(reply));
+    return {
+        name: family.name,
+        call: family.call,
+        effect: call.effect,
+        requires: call.requires,
+        kind: inventory.kind,
+        tools: inventory.kind === "unindexed"
+            ? []
+            : inventory.tools.map((row) => ({
+                row,
+                description: [row.title, row.description]
+                    .filter((text) => text.length > 0)
+                    .join("\n"),
+                input: appMethodSchema(row.input),
+                output: appMethodSchema(row.output),
+            })),
+    };
+}
+/**
+ * Project an already decoded Release API into discovery data with the same
+ * paths the Agent catalog uses (`PRINTS.generate`, called as
+ * `env.PRINTS.generate()`). The introduction owner supplies the installation's
+ * binding name; this function grants no access and supplies no execution
+ * handler. Role aliases can project the same API.
+ */
+export function appApiOperations(name, api) {
+    const binding = bindingName.parse(name);
+    return Object.entries(appToolSchemas(api)).map(([method, declaration]) => ({
+        path: `${binding}.${method}`,
+        description: declaration.description,
+        input: declaration.input,
+        output: declaration.output,
+        capabilityNotes: `effect: ${declaration.effect}; requires: ${declaration.requires.join(", ") || "none"}`,
+    }));
+}

package/dist/catalog.d.ts

@@ -0,0 +1,16 @@
+import { type CatalogInput, type ForageDescribeInput, type ForageSearchInput, type SearchOutput, type DescribeOutput, type ForageListInput, type ListOutput } from "./schemas.js";
+/** Immutable public facade for one prepared catalog revision. */
+export type ForageCatalog = Readonly<{
+    /** Immutable revision supplied when the catalog was created. */
+    revision: string;
+    /** Deterministically rank provisioned operations for a bounded query. */
+    search: (rawInput: ForageSearchInput) => SearchOutput;
+    /** Render bounded types and operation input constraints from the validator. */
+    describe: (rawInput: ForageDescribeInput) => DescribeOutput;
+    /** Enumerate every operation exactly once in stable namespace/path order. */
+    list: (rawInput: ForageListInput) => ListOutput;
+    /** Return the stable identity stamp for this catalog revision. */
+    stamp: () => string;
+}>;
+/** Construct one immutable catalog revision with a narrow public facade. */
+export declare function createCatalog(input: CatalogInput): ForageCatalog;

package/dist/catalog.js

@@ -0,0 +1,108 @@
+import { ForageError } from "./errors.js";
+import { catalogInputSchema, forageDescribeInput, forageSearchInput, maximumDescriptionTypes, } from "./schemas.js";
+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";
+const maximumCatalogProjectionBytes = 1_000_000;
+function parseCatalog(input) {
+    const parsed = catalogInputSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new ForageError("invalid_input", parsed.error.message);
+    }
+    if (parsed.data.operations.length === 0) {
+        throw new ForageError("empty_catalog", "Catalog must contain an operation");
+    }
+    const operations = [...parsed.data.operations].sort((left, right) => compareCodeUnits(left.path, right.path));
+    const paths = new Set();
+    let projectionBytes = 0;
+    for (const operation of operations) {
+        if (paths.has(operation.path)) {
+            throw new ForageError("duplicate_operation", `Duplicate operation path: ${operation.path}`);
+        }
+        paths.add(operation.path);
+        const inputProjection = schemaProjectionSize(operation.input, "input");
+        if (inputProjection === undefined) {
+            throw new ForageError("invalid_input", `Schema projection is too large: ${operation.path}`);
+        }
+        const outputProjection = operation.output
+            ? schemaProjectionSize(operation.output, "output")
+            : 0;
+        if (outputProjection === undefined) {
+            throw new ForageError("invalid_input", `Schema output projection is too large: ${operation.path}`);
+        }
+        projectionBytes +=
+            inputProjection + outputProjection + operation.path.length;
+        projectionBytes += operation.description?.length ?? 0;
+        projectionBytes += operation.capabilityNotes?.length ?? 0;
+        projectionBytes += operation.instructions?.length ?? 0;
+        if (projectionBytes > maximumCatalogProjectionBytes) {
+            throw new ForageError("invalid_input", "Catalog metadata exceeds the bounded projection");
+        }
+    }
+    const preparedOperations = operations.map((operation) => prepareOperation(operation));
+    const namespaces = new Map();
+    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}`);
+        }
+    }
+    return {
+        revision: parsed.data.revision,
+        operations: preparedOperations,
+    };
+}
+/** Construct one immutable catalog revision with a narrow public facade. */
+export function createCatalog(input) {
+    const parsed = parseCatalog(input);
+    const operations = Object.freeze(parsed.operations);
+    const stamp = catalogStamp(operations);
+    const summaries = operations.map((operation) => {
+        const summary = { path: operation.path, score: 0 };
+        if (operation.description !== undefined)
+            summary.description = operation.description;
+        if (operation.sample !== undefined)
+            summary.sample = operation.sample;
+        if (operation.capabilityNotes !== undefined)
+            summary.capabilityNotes = operation.capabilityNotes;
+        return summary;
+    });
+    const search = (rawInput) => {
+        const parsed = forageSearchInput.safeParse(rawInput);
+        if (!parsed.success) {
+            throw new ForageError("invalid_input", parsed.error.message);
+        }
+        if (parsed.data.query.trim().length === 0) {
+            throw new ForageError("empty_query", "Search query must not be empty");
+        }
+        return searchCatalog(operations, parsed.data.query, parsed.data.maxResults, stamp);
+    };
+    const describe = (rawInput) => {
+        const parsed = forageDescribeInput.safeParse(rawInput);
+        if (!parsed.success) {
+            throw new ForageError("invalid_input", parsed.error.message);
+        }
+        if (parsed.data.path.trim().length === 0) {
+            throw new ForageError("empty_query", "Description target must not be empty");
+        }
+        return describeCatalog(operations, parsed.data);
+    };
+    return Object.freeze({
+        revision: parsed.revision,
+        search,
+        describe,
+        list: (input) => listOperations(summaries, stamp, input),
+        stamp: () => stamp,
+    });
+}

package/dist/definitions.d.ts

@@ -0,0 +1,16 @@
+import { describeOutputSchema, forageDescribeInput, forageSearchInput, searchOutputSchema, forageListInput, listOutputSchema } from "./schemas.js";
+/** Structural operation definition consumed by a capability composer. */
+export type ForageDefinition = Readonly<{
+    /** Pure catalog lookup; the enclosing Mycelium execute program is still unsafe. */
+    replay: "safe";
+    path: string;
+    description: string;
+    input: typeof forageSearchInput | typeof forageDescribeInput | typeof forageListInput;
+    output: typeof searchOutputSchema | typeof describeOutputSchema | typeof listOutputSchema;
+}>;
+/** The search operation has schema metadata only; it has no host behavior. */
+export declare const forageSearchDefinition: ForageDefinition;
+/** The description operation has schema metadata only; it has no host behavior. */
+export declare const forageDescribeDefinition: ForageDefinition;
+/** Pure exhaustive catalog listing; no execution or authority is granted. */
+export declare const forageListDefinition: ForageDefinition;

package/dist/definitions.js

@@ -0,0 +1,25 @@
+import { describeOutputSchema, forageDescribeInput, forageSearchInput, searchOutputSchema, forageListInput, listOutputSchema, } from "./schemas.js";
+/** The search operation has schema metadata only; it has no host behavior. */
+export const forageSearchDefinition = Object.freeze({
+    replay: "safe",
+    path: "forage.search",
+    description: "Search operation names and descriptions with short keywords, such as read or shell. If no results match, retry with one relevant keyword. Describe known operation paths directly with forage.describe.",
+    input: forageSearchInput,
+    output: searchOutputSchema,
+});
+/** The description operation has schema metadata only; it has no host behavior. */
+export const forageDescribeDefinition = Object.freeze({
+    replay: "safe",
+    path: "forage.describe",
+    description: "Describe a capability",
+    input: forageDescribeInput,
+    output: describeOutputSchema,
+});
+/** Pure exhaustive catalog listing; no execution or authority is granted. */
+export const forageListDefinition = Object.freeze({
+    replay: "safe",
+    path: "forage.list",
+    description: "List every available operation in stable namespace then path order (UTF-16 code units). Use limit (1–50) and nextCursor to page without duplicates, optionally filtering by exact namespace. total counts all operations in that filter; summaries match search, with score 0 and no peer merging. A cursor belongs to this catalog and filter; describe paths before calling them.",
+    input: forageListInput,
+    output: listOutputSchema,
+});

package/dist/describe.d.ts

@@ -0,0 +1,4 @@
+import { type DescribeOutput, type ForageDescribeInput } from "./schemas.js";
+import type { PreparedOperation } from "./search.js";
+/** Pure deterministic description of an operation or its namespace. */
+export declare function describeCatalog(operations: readonly PreparedOperation[], rawInput: ForageDescribeInput): DescribeOutput;