@fungi.computer/forage 0.0.0-stage → 0.0.1

package/docs/api/index.md

@@ -0,0 +1,859 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/forage**](README.md)
+
+---
+
+[@fungi.computer/forage](README.md) / index
+
+# index
+
+## Classes
+
+### ForageError
+
+A bounded, machine-readable failure at a Forage public seam.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ForageError(
+   code,
+   message,
+   options?
+): ForageError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `code`     | \| `"empty_query"` \| `"empty_catalog"` \| `"unknown_target"` \| `"duplicate_operation"` \| `"invalid_input"` |
+| `message`  | `string`                                                                                                      |
+| `options?` | `ErrorOptions`                                                                                                |
+
+###### Returns
+
+[`ForageError`](#forageerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code:
+  | "empty_query"
+  | "empty_catalog"
+  | "unknown_target"
+  | "duplicate_operation"
+  | "invalid_input";
+```
+
+##### failure
+
+```ts
+readonly failure: object;
+```
+
+###### code
+
+```ts
+code:
+  | "empty_query"
+  | "empty_catalog"
+  | "unknown_target"
+  | "duplicate_operation"
+  | "invalid_input";
+```
+
+###### message
+
+```ts
+message: string;
+```
+
+## Type Aliases
+
+### ForageCatalog
+
+```ts
+type ForageCatalog = Readonly<{
+  revision: string;
+  search: (rawInput) => SearchOutput;
+  describe: (rawInput) => DescribeOutput;
+  list: (rawInput) => ListOutput;
+  stamp: () => string;
+}>;
+```
+
+Immutable public facade for one prepared catalog revision.
+
+---
+
+### ForageDefinition
+
+```ts
+type ForageDefinition = Readonly<{
+  replay: "safe";
+  path: string;
+  description: string;
+  input:
+    | typeof forageSearchInput
+    | typeof forageDescribeInput
+    | typeof forageListInput;
+  output:
+    | typeof searchOutputSchema
+    | typeof describeOutputSchema
+    | typeof listOutputSchema;
+}>;
+```
+
+Structural operation definition consumed by a capability composer.
+
+---
+
+### ForageApi
+
+```ts
+type ForageApi = object;
+```
+
+Public convenience namespace contract.
+
+#### Properties
+
+##### createCatalog
+
+```ts
+createCatalog: typeof createCatalog;
+```
+
+Construct one immutable catalog revision.
+
+##### forageSearchDefinition
+
+```ts
+forageSearchDefinition: typeof forageSearchDefinition;
+```
+
+Structural search operation definition.
+
+##### forageDescribeDefinition
+
+```ts
+forageDescribeDefinition: typeof forageDescribeDefinition;
+```
+
+Structural description operation definition.
+
+##### forageListDefinition
+
+```ts
+forageListDefinition: typeof forageListDefinition;
+```
+
+Structural exhaustive listing definition.
+
+---
+
+### JsonSchemaTarget
+
+```ts
+type JsonSchemaTarget = Readonly<{
+  target: "draft-2020-12";
+}>;
+```
+
+Options Forage passes when it asks a schema for its JSON Schema.
+
+---
+
+### JsonSchemaSource
+
+```ts
+type JsonSchemaSource = Readonly<{
+  ~standard: Readonly<{
+     jsonSchema: Readonly<{
+        input: (options) => object;
+        output: (options) => object;
+     }>;
+  }>;
+}>;
+```
+
+Any schema that describes itself through Standard JSON Schema: Zod 4 schemas
+natively, and Effect schemas through Mycelium. Forage only renders descriptions;
+validation stays with the schema's owner.
+
+---
+
+### ForageSearchInput
+
+```ts
+type ForageSearchInput = z.input<typeof forageSearchInput>;
+```
+
+Parsed search request type.
+
+---
+
+### ForageListInput
+
+```ts
+type ForageListInput = z.input<typeof forageListInput>;
+```
+
+Exhaustive listing request type.
+
+---
+
+### ListOutput
+
+```ts
+type ListOutput = z.infer<typeof listOutputSchema>;
+```
+
+Exhaustive page response type.
+
+---
+
+### ForageDescribeInput
+
+```ts
+type ForageDescribeInput = z.input<typeof forageDescribeInput>;
+```
+
+Parsed description request type.
+
+---
+
+### SearchResult
+
+```ts
+type SearchResult = z.infer<typeof searchResultSchema>;
+```
+
+One ranked search result type.
+
+---
+
+### SearchOutput
+
+```ts
+type SearchOutput = z.infer<typeof searchOutputSchema>;
+```
+
+Search response envelope type.
+
+---
+
+### DescribeOutput
+
+```ts
+type DescribeOutput = z.infer<typeof describeOutputSchema>;
+```
+
+Description response type.
+
+---
+
+### ForageFailure
+
+```ts
+type ForageFailure = z.infer<typeof forageFailureSchema>;
+```
+
+Typed failure value type.
+
+---
+
+### Operation
+
+```ts
+type Operation = z.infer<typeof operationSchema>;
+```
+
+Catalog operation descriptor type.
+
+---
+
+### CatalogInput
+
+```ts
+type CatalogInput = z.input<typeof catalogInputSchema>;
+```
+
+Catalog construction input type.
+
+## Variables
+
+### forageSearchDefinition
+
+```ts
+const forageSearchDefinition: ForageDefinition;
+```
+
+The search operation has schema metadata only; it has no host behavior.
+
+---
+
+### forageDescribeDefinition
+
+```ts
+const forageDescribeDefinition: ForageDefinition;
+```
+
+The description operation has schema metadata only; it has no host behavior.
+
+---
+
+### forageListDefinition
+
+```ts
+const forageListDefinition: ForageDefinition;
+```
+
+Pure exhaustive catalog listing; no execution or authority is granted.
+
+---
+
+### Forage
+
+```ts
+const Forage: ForageApi;
+```
+
+Narrow convenience namespace for the package's public seams.
+
+---
+
+### forageSearchInput
+
+```ts
+const forageSearchInput: ZodObject<
+  {
+    query: ZodString;
+    maxResults: ZodDefault<ZodNumber>;
+  },
+  $strip
+>;
+```
+
+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
+>;
+```
+
+Input accepted by the pure catalog description seam.
+
+---
+
+### forageListInput
+
+```ts
+const forageListInput: ZodObject<
+  {
+    cursor: ZodOptional<ZodString>;
+    limit: ZodDefault<ZodNumber>;
+    namespace: ZodOptional<ZodString>;
+  },
+  $strip
+>;
+```
+
+Exhaustive listing request; cursor is scoped to one immutable catalog and
+filter.
+
+---
+
+### searchResultSchema
+
+```ts
+const searchResultSchema: 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
+>;
+```
+
+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
+>;
+```
+
+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
+>;
+```
+
+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
+>;
+```
+
+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
+>;
+```
+
+Closed failure vocabulary for malformed or absent catalog requests.
+
+---
+
+### operationSchema
+
+```ts
+const operationSchema: ZodObject<{
+  path: ZodString;
+  description: ZodOptional<ZodString>;
+  input: ZodCustom<Readonly<{
+     ~standard: Readonly<{
+        jsonSchema: Readonly<{
+           input: (options) => object;
+           output: (options) => object;
+        }>;
+     }>;
+   }>, Readonly<{
+     ~standard: Readonly<{
+        jsonSchema: Readonly<{
+           input: (options) => object;
+           output: (options) => object;
+        }>;
+     }>;
+  }>>;
+  output: ZodOptional<ZodCustom<Readonly<{
+     ~standard: Readonly<{
+        jsonSchema: Readonly<{
+           input: (options) => ...;
+           output: (options) => ...;
+        }>;
+     }>;
+   }>, Readonly<{
+     ~standard: Readonly<{
+        jsonSchema: Readonly<{
+           input: (options) => ...;
+           output: (options) => ...;
+        }>;
+     }>;
+  }>>>;
+  capabilityNotes: ZodOptional<ZodString>;
+  instructions: ZodOptional<ZodString>;
+}, $strip>;
+```
+
+A secret-free, callback-free operation descriptor.
+
+---
+
+### catalogInputSchema
+
+```ts
+const catalogInputSchema: ZodObject<{
+  revision: ZodString;
+  operations: ZodArray<ZodObject<{
+     path: ZodString;
+     description: ZodOptional<ZodString>;
+     input: ZodCustom<Readonly<{
+        ~standard: Readonly<{
+           jsonSchema: Readonly<...>;
+        }>;
+      }>, Readonly<{
+        ~standard: Readonly<{
+           jsonSchema: Readonly<...>;
+        }>;
+     }>>;
+     output: ZodOptional<ZodCustom<Readonly<{
+        ~standard: Readonly<{
+           jsonSchema: ...;
+        }>;
+      }>, Readonly<{
+        ~standard: Readonly<{
+           jsonSchema: ...;
+        }>;
+     }>>>;
+     capabilityNotes: ZodOptional<ZodString>;
+     instructions: ZodOptional<ZodString>;
+  }, $strip>>;
+}, $strip>;
+```
+
+Input used to construct one immutable catalog revision.
+
+## Functions
+
+### jsonSchemaToZod()
+
+```ts
+function jsonSchemaToZod(
+  source,
+  defaultTarget?,
+): ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>;
+```
+
+The shared JSON-Schema compiler for App methods and OpenAPI operations.
+
+#### Parameters
+
+| Parameter       | Type                                 | Default value     |
+| --------------- | ------------------------------------ | ----------------- |
+| `source`        | `unknown`                            | `undefined`       |
+| `defaultTarget` | `"draft-2020-12"` \| `"openapi-3.0"` | `"draft-2020-12"` |
+
+#### Returns
+
+`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\>
+
+---
+
+### appMethodSchemas()
+
+```ts
+function appMethodSchemas(api): object;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `api`     | `AppApi` |
+
+#### Returns
+
+`object`
+
+---
+
+### appToolSchemas()
+
+```ts
+function appToolSchemas(api): object;
+```
+
+Compile discoverable App methods only; direct RPC validation uses
+appMethodSchemas.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `api`     | `AppApi` |
+
+#### Returns
+
+`object`
+
+---
+
+### appToolFamilySchemas()
+
+```ts
+function appToolFamilySchemas(
+  api,
+  reply,
+): {
+  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;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type      |
+| --------- | --------- |
+| `api`     | `AppApi`  |
+| `reply`   | `unknown` |
+
+#### 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`
+
+---
+
+### appApiOperations()
+
+```ts
+function appApiOperations(name, api): readonly object[];
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `name`    | `string` |
+| `api`     | `AppApi` |
+
+#### Returns
+
+readonly `object`[]
+
+---
+
+### createCatalog()
+
+```ts
+function createCatalog(input): ForageCatalog;
+```
+
+Construct one immutable catalog revision with a narrow public facade.
+
+#### Parameters
+
+| Parameter          | Type                                                  |
+| ------------------ | ----------------------------------------------------- |
+| `input`            | \{ `revision`: `string`; `operations`: `object`[]; \} |
+| `input.revision`   | `string`                                              |
+| `input.operations` | `object`[]                                            |
+
+#### Returns
+
+[`ForageCatalog`](#foragecatalog)
+
+---
+
+### listOperations()
+
+```ts
+function listOperations(operations, catalogStamp, rawInput): object;
+```
+
+Page a trusted immutable operation-summary view. Hosts may filter the existing
+catalog to their bound operations before paging; this is the one cursor owner.
+Order is namespace then full path, compared by UTF-16 code units, never locale.
+Unlike search, no equivalent operations are merged into peers.
+
+#### Parameters
+
+| Parameter             | Type                                                                   |
+| --------------------- | ---------------------------------------------------------------------- |
+| `operations`          | readonly `object`[]                                                    |
+| `catalogStamp`        | `string`                                                               |
+| `rawInput`            | \{ `cursor?`: `string`; `limit?`: `number`; `namespace?`: `string`; \} |
+| `rawInput.cursor?`    | `string`                                                               |
+| `rawInput.limit?`     | `number`                                                               |
+| `rawInput.namespace?` | `string`                                                               |
+
+#### Returns
+
+`object`
+
+| Name           | Type               |
+| -------------- | ------------------ |
+| `results`      | `object`[]         |
+| `total`        | `number`           |
+| `nextCursor`   | `string` \| `null` |
+| `catalogStamp` | `string`           |
+
+## References
+
+### default
+
+Renames and re-exports [Forage](#forage)