@fungi.computer/forage 0.2.0 → 0.2.1

package/dist/app-api.d.ts

@@ -3,7 +3,16 @@ 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.
+/**
+ * One decoded, immutable App declaration as a JSON-only Standard Schema.
+ * Release and family-listing decoders own its JSON boundary. A catalog
+ * describes every installed method on each capture but a turn validates only
+ * the few it calls. Compiling every method eagerly exhausted an Agent Durable
+ * Object's isolate. A draft 2020-12 description is the declaration itself;
+ * validators compile for the call in hand and are never kept on the surface.
+ */
+export declare function appJsonSchema(declaration: AppApi["methods"][string]["input"] | boolean): Pick<z.ZodType<z.output<z.ZodJSONSchema>>, "parse" | "safeParse" | "~standard">;
+/** Describe App methods with call-scoped JSON validators.
  * 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. */
@@ -17,7 +26,7 @@ export declare function appMethodSchemas(api: AppApi): {
         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. */
+/** Describe discoverable App methods only; direct RPC validation uses appMethodSchemas. */
 export declare function appToolSchemas(api: AppApi): {
     [k: string]: {
         readonly description: string;

package/dist/app-api.js

@@ -4,25 +4,45 @@ const bindingName = z.lazy(() => z
     .min(1)
     .max(75)
     .regex(/^[A-Za-z][A-Za-z0-9_]*$/));
-const jsonSchema = z.lazy(() => z.union([z.record(z.string(), z.json()), z.boolean()]));
+const jsonSchemaDocument = z.lazy(() => z.record(z.string(), z.json()));
+const jsonSchema = z.lazy(() => z.union([jsonSchemaDocument, 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());
+/**
+ * One decoded, immutable App declaration as a JSON-only Standard Schema.
+ * Release and family-listing decoders own its JSON boundary. A catalog
+ * describes every installed method on each capture but a turn validates only
+ * the few it calls. Compiling every method eagerly exhausted an Agent Durable
+ * Object's isolate. A draft 2020-12 description is the declaration itself;
+ * validators compile for the call in hand and are never kept on the surface.
+ */
+export function appJsonSchema(declaration) {
+    const build = () => jsonSchemaToZod(declaration);
+    const validate = () => z.intersection(build(), z.json());
+    const describe = (io, options) => {
+        if (options.target === "draft-2020-12" &&
+            declaration !== true &&
+            declaration !== false)
+            return declaration;
+        return build()["~standard"].jsonSchema[io](options);
+    };
     return {
-        parse: (value, options) => validator.parse(value, options),
-        safeParse: (value, options) => validator.safeParse(value, options),
+        parse: (value, options) => validate().parse(value, options),
+        safeParse: (value, options) => validate().safeParse(value, options),
         "~standard": {
-            ...validator["~standard"],
-            jsonSchema: declared["~standard"].jsonSchema,
+            version: 1,
+            vendor: "zod",
+            validate: (value, options) => validate()["~standard"].validate(value, options),
+            jsonSchema: {
+                input: (options) => describe("input", options),
+                output: (options) => describe("output", options),
+            },
         },
     };
 }
-/** Compile App validators and their Standard JSON Schema descriptions.
+/** Describe App methods with call-scoped JSON validators.
  * 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. */
@@ -34,12 +54,12 @@ export function appMethodSchemas(api) {
             effect: declaration.effect,
             requires: declaration.requires,
             pending: declaration.pending,
-            input: appMethodSchema(declaration.input),
-            output: appMethodSchema(declaration.output),
+            input: appJsonSchema(declaration.input),
+            output: appJsonSchema(declaration.output),
         },
     ]));
 }
-/** Compile discoverable App methods only; direct RPC validation uses appMethodSchemas. */
+/** Describe discoverable App methods only; direct RPC validation uses appMethodSchemas. */
 export function appToolSchemas(api) {
     return appMethodSchemas({
         ...api,
@@ -83,7 +103,7 @@ export function appToolFamilySchemas(api, reply) {
     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));
+    const inventory = familyInventory.parse(appJsonSchema(list.output).parse(reply));
     return {
         name: family.name,
         call: family.call,
@@ -97,8 +117,8 @@ export function appToolFamilySchemas(api, reply) {
                 description: [row.title, row.description]
                     .filter((text) => text.length > 0)
                     .join("\n"),
-                input: appMethodSchema(row.input),
-                output: appMethodSchema(row.output),
+                input: appJsonSchema(row.input),
+                output: appJsonSchema(row.output),
             })),
     };
 }

package/dist/catalog.js

@@ -1,11 +1,34 @@
+import { z } from "zod";
 import { ForageError } from "./errors.js";
-import { catalogInputSchema, forageDescribeInput, forageSearchInput, maximumDescriptionTypes, } from "./schemas.js";
+import { catalogInputSchema, forageDescribeInput, forageSearchInput, maximumDescriptionTypes, maximumSampleBytes, maximumSampleDepth, maximumSampleEntries, jsonDepth, } 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 { renderOperationTypes, schemaProjectionSize } from "./rendering.js";
+import { rawSchema, schemaText } from "./rendering.js";
 const maximumCatalogProjectionBytes = 1_000_000;
+/**
+ * A nesting bound on the raw producer document, not a second JSON decoder.
+ * The ceiling bounds recursion; sibling order cannot change the maximum.
+ * Indexed traversal avoids cold iterator results and heap stack entries.
+ */
+function schemaDepth(children, depth = 0) {
+    if (depth >= maximumSampleDepth)
+        return children.length === 0 ? depth : depth + 1;
+    let maximum = depth;
+    for (let index = children.length - 1; index >= 0; index -= 1) {
+        const child = children[index];
+        let childDepth = depth + 1;
+        if (Array.isArray(child))
+            childDepth = schemaDepth(child, childDepth);
+        else if (z.util.isObject(child))
+            childDepth = schemaDepth(Object.values(child), childDepth);
+        maximum = Math.max(maximum, childDepth);
+        if (maximum > maximumSampleDepth)
+            return maximum;
+    }
+    return maximum;
+}
 function parseCatalog(input) {
     const parsed = catalogInputSchema.safeParse(input);
     if (!parsed.success) {
@@ -16,24 +39,42 @@ function parseCatalog(input) {
     }
     const operations = [...parsed.data.operations].sort((left, right) => compareCodeUnits(left.path, right.path));
     const paths = new Set();
+    const preparedOperations = [];
     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) {
+        const inputProjection = schemaText(operation.input, "input").length;
+        if (inputProjection > maximumDescriptionTypes ||
+            schemaDepth(Object.values(rawSchema(operation.input, "input"))) >
+                maximumSampleDepth) {
             throw new ForageError("invalid_input", `Schema projection is too large: ${operation.path}`);
         }
         const outputProjection = operation.output
-            ? schemaProjectionSize(operation.output, "output")
+            ? schemaText(operation.output, "output").length
             : 0;
-        if (outputProjection === undefined) {
+        if (outputProjection > maximumDescriptionTypes ||
+            (operation.output !== undefined &&
+                schemaDepth(Object.values(rawSchema(operation.output, "output"))) >
+                    maximumSampleDepth)) {
             throw new ForageError("invalid_input", `Schema output projection is too large: ${operation.path}`);
         }
+        const prepared = prepareOperation(operation);
+        const sample = prepared.sample;
+        const sampleBytes = sample === undefined ? 0 : JSON.stringify(sample).length;
+        if (sample !== undefined &&
+            (Object.keys(sample).length > maximumSampleEntries ||
+                sampleBytes > maximumSampleBytes ||
+                jsonDepth(sample, 0) > maximumSampleDepth))
+            throw new ForageError("invalid_input", `Schema projection is too large: ${operation.path}`);
+        preparedOperations.push(prepared);
         projectionBytes +=
-            inputProjection + outputProjection + operation.path.length;
+            prepared.inputBytes +
+                prepared.outputBytes +
+                sampleBytes +
+                operation.path.length;
         projectionBytes += operation.description?.length ?? 0;
         projectionBytes += operation.capabilityNotes?.length ?? 0;
         projectionBytes += operation.instructions?.length ?? 0;
@@ -41,16 +82,6 @@ function parseCatalog(input) {
             throw new ForageError("invalid_input", "Catalog metadata exceeds the bounded projection");
         }
     }
-    const preparedOperations = operations.map((operation) => prepareOperation(operation));
-    // 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) {
-        if (renderOperationTypes([operation.rendered]).length >
-            maximumDescriptionTypes) {
-            throw new ForageError("invalid_input", `Operation description exceeds the bounded output: ${operation.path}`);
-        }
-    }
     return {
         revision: parsed.data.revision,
         operations: preparedOperations,

package/dist/describe.js

@@ -1,6 +1,6 @@
 import { describeOutputSchema, maximumDescriptionTypes, } from "./schemas.js";
-import { compareCodeUnits } from "./normalization.js";
-import { renderNamespaceIndex, renderOperationTypes } from "./rendering.js";
+import { compareCodeUnits, jsonValueSchema } from "./normalization.js";
+import { rawSchema, renderOperation, renderNamespaceIndex, renderOperationTypes, } from "./rendering.js";
 import { ForageError } from "./errors.js";
 function boundedDescription(value) {
     return value && value.length > 0 ? value : undefined;
@@ -17,16 +17,19 @@ export function describeCatalog(operations, rawInput) {
     const operation = operations.find((candidate) => candidate.path === rawInput.path);
     if (operation) {
         const callPath = `env.${operation.path}`;
+        const inputSchema = jsonValueSchema.safeParse(rawSchema(operation.input, "input"));
+        if (!inputSchema.success)
+            throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
         const output = {
             path: operation.path,
             description: boundedDescription(operation.description),
-            types: renderOperationTypes([operation.rendered]),
+            types: renderOperationTypes([renderOperation(operation)]),
             kind: "operation",
-            inputSchema: operation.inputSchema,
+            inputSchema: inputSchema.data,
             usage: `await ${callPath}({ ... })`,
         };
         if (output.types.length > maximumDescriptionTypes) {
-            throw new ForageError("invalid_input", "Description types exceed the bounded output");
+            throw new ForageError("invalid_input", "Operation description exceeds the bounded output");
         }
         return checkedDescription(output);
     }
@@ -46,13 +49,13 @@ export function describeCatalog(operations, rawInput) {
         : namespaceOperations;
     let types;
     if (rawInput.detail === "index") {
-        types = renderNamespaceIndex(namespaceOperations.map((operation) => operation.rendered));
+        types = renderNamespaceIndex(namespaceOperations.map(renderOperation));
     }
     else if (rawInput.methods?.length && selected.length === 0) {
-        types = renderNamespaceIndex(namespaceOperations.map((operation) => operation.rendered));
+        types = renderNamespaceIndex(namespaceOperations.map(renderOperation));
     }
     else {
-        types = renderOperationTypes((selected.length > 0 ? selected : namespaceOperations).map((operation) => operation.rendered));
+        types = renderOperationTypes((selected.length > 0 ? selected : namespaceOperations).map(renderOperation));
     }
     if (types.length > maximumDescriptionTypes) {
         throw new ForageError("invalid_input", "Description types exceed the bounded output");

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CatalogInput, DescribeOutput, ForageDescribeInput, ForageFailure,
 export type { ForageDefinition } from "./definitions.js";
 export { ForageError } from "./errors.js";
 export { createCatalog } from "./catalog.js";
-export { appApiOperations, appMethodSchemas, appToolSchemas, appToolFamilySchemas, jsonSchemaToZod, } from "./app-api.js";
+export { appApiOperations, appJsonSchema, appMethodSchemas, appToolSchemas, appToolFamilySchemas, jsonSchemaToZod, } from "./app-api.js";
 export { listOperations } from "./list.js";
 export type { ForageCatalog } from "./catalog.js";
 export { forageDescribeDefinition, forageSearchDefinition, forageListDefinition, } from "./definitions.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { catalogInputSchema, describeOutputSchema, forageDescribeInput, forageFailureSchema, forageSearchInput, operationSchema, searchOutputSchema, searchResultSchema, forageListInput, listOutputSchema, } from "./schemas.js";
 export { ForageError } from "./errors.js";
 export { createCatalog } from "./catalog.js";
-export { appApiOperations, appMethodSchemas, appToolSchemas, appToolFamilySchemas, jsonSchemaToZod, } from "./app-api.js";
+export { appApiOperations, appJsonSchema, appMethodSchemas, appToolSchemas, appToolFamilySchemas, jsonSchemaToZod, } from "./app-api.js";
 export { listOperations } from "./list.js";
 export { forageDescribeDefinition, forageSearchDefinition, forageListDefinition, } from "./definitions.js";
 import { createCatalog } from "./catalog.js";

package/dist/normalization.d.ts

@@ -16,7 +16,6 @@ export declare function normalizeQuery(query: string): string;
 export declare function tokenize(text: string): string[];
 export declare function isStopword(token: string): boolean;
 export declare function stemVariants(token: string): string[];
-export declare function canonicalStringify(value: JsonValue): string;
 export declare function hashString64(value: string): string;
 export declare function operationMethod(path: Operation["path"]): string;
 export declare function operationNamespace(path: Operation["path"]): string;

package/dist/normalization.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 export const jsonValueSchema = z.json();
-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
@@ -8,9 +7,7 @@ const jsonPrimitiveSchema = z.lazy(() => z.union([z.string(), z.number(), z.bool
  * made walking a large schema quadratic.
  */
 export function isJsonObject(value) {
-    return (value !== null &&
-        !Array.isArray(value) &&
-        !jsonPrimitiveSchema.safeParse(value).success);
+    return value !== null && !Array.isArray(value) && typeof value === "object";
 }
 export function compareCodeUnits(left, right) {
     if (left === right)
@@ -63,6 +60,9 @@ export function stemVariants(token) {
         add(token.slice(0, -3));
     if (token.endsWith("ed") && token.length > 3)
         add(token.slice(0, -2));
+    if (token.endsWith("ation") && token.length > 6) {
+        add(`${token.slice(0, -3)}e`);
+    }
     if (token.endsWith("ies") && token.length > 4) {
         add(token.slice(0, -3));
         add(`${token.slice(0, -3)}y`);
@@ -74,32 +74,29 @@ export function stemVariants(token) {
     }
     return variants;
 }
-export function canonicalStringify(value) {
-    if (value === null)
-        return "null";
-    const primitive = jsonPrimitiveSchema.safeParse(value);
-    if (primitive.success) {
-        return JSON.stringify(primitive.data);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map((item) => canonicalStringify(item)).join(",")}]`;
-    }
-    if (!isJsonObject(value))
-        return "null";
-    const entries = Object.entries(value).sort(([left], [right]) => compareCodeUnits(left, right));
-    return `{${entries
-        .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalStringify(entry)}`)
-        .join(",")}}`;
-}
 export function hashString64(value) {
-    let hash = 0xcbf29ce484222325n;
-    const prime = 0x100000001b3n;
-    const mask = (1n << 64n) - 1n;
+    let word0 = 0x2325;
+    let word1 = 0x8422;
+    let word2 = 0x9ce4;
+    let word3 = 0xcbf2;
     for (let index = 0; index < value.length; index += 1) {
-        hash ^= BigInt(value.charCodeAt(index));
-        hash = (hash * prime) & mask;
+        const low = word0 ^ value.charCodeAt(index);
+        // The prime is 2^40 + 435. Four 16-bit limbs preserve modulo 2^64;
+        // every intermediate stays below 2^26, including before V8 optimizes
+        // this loop. Unsigned 32-bit limbs allocated boxed numbers when cold.
+        const product0 = low * 435;
+        const product1 = word1 * 435 + (product0 >>> 16);
+        const product2 = word2 * 435 + (product1 >>> 16) + (low << 8);
+        const product3 = word3 * 435 + (product2 >>> 16) + (word1 << 8);
+        word0 = product0 & 0xffff;
+        word1 = product1 & 0xffff;
+        word2 = product2 & 0xffff;
+        word3 = product3 & 0xffff;
     }
-    return hash.toString(16).padStart(16, "0");
+    return (word3.toString(16).padStart(4, "0") +
+        word2.toString(16).padStart(4, "0") +
+        word1.toString(16).padStart(4, "0") +
+        word0.toString(16).padStart(4, "0"));
 }
 export function operationMethod(path) {
     return path.slice(path.indexOf(".") + 1);

package/dist/rendering.d.ts

@@ -1,26 +1,20 @@
 import type { JsonValue } from "./normalization.js";
-import { type JsonSchemaSource } from "./schemas.js";
-/** Installation-time TypeScript projections for one catalog operation. */
+import type { JsonSchemaSource, Operation } from "./schemas.js";
+/** Requested TypeScript projections for one catalog operation. */
 export type RenderedOperation = Readonly<{
     types: string;
     environment: string;
     indexEnvironment: string;
 }>;
+/** The producer's document, without a recursive projection decode or copy. */
+export declare function rawSchema(schema: JsonSchemaSource, io: "input" | "output"): object;
+/** Native serialization owns the document's text representation and failures. */
+export declare function schemaText(schema: JsonSchemaSource, io: "input" | "output"): string;
 /** Render a namespace index as a callable nested environment. */
 export declare function renderNamespaceIndex(operations: readonly RenderedOperation[]): string;
 /** Render whole-operation schemas and their callable nested environment. */
 export declare function renderOperationTypes(operations: readonly RenderedOperation[]): string;
-/** Prepare all TypeScript descriptions for one operation at installation. */
-export declare function renderOperation(operation: {
-    path: string;
-    input: JsonSchemaSource;
-    output?: JsonSchemaSource | undefined;
-}): RenderedOperation;
+/** Render only requested operations, once per immutable prepared operation. */
+export declare function renderOperation(operation: Operation): RenderedOperation;
 /** Derive sample arguments solely from input-schema examples and defaults. */
 export declare function deriveSample(schema: JsonSchemaSource): Record<string, JsonValue> | undefined;
-/** Preserve validator constraints in the operation's Standard JSON Schema. */
-export declare function inputSchemaProjection(schema: JsonSchemaSource): JsonValue;
-/** Produce a canonical schema representation used in peer identity and stamps. */
-export declare function schemaFingerprint(schema: JsonSchemaSource, io?: "input" | "output"): string;
-/** Validate the bounded JSON projection before a catalog is installed. */
-export declare function schemaProjectionSize(schema: JsonSchemaSource, io: "input" | "output"): number | undefined;

package/dist/rendering.js

@@ -1,67 +1,71 @@
 import { z } from "zod";
 import { ForageError } from "./errors.js";
-import { canonicalStringify, compareCodeUnits, isJsonObject, jsonValueSchema, } from "./normalization.js";
-import { maximumSampleBytes, maximumSampleDepth, maximumSampleEntries, } from "./schemas.js";
-const schemaNode = z.lazy(() => z.union([
-    z.boolean(),
+import { compareCodeUnits, jsonValueSchema } from "./normalization.js";
+/** The JSON Schema subset Forage reads when it renders and samples a schema. */
+const schemaNode = z.union([
     z.looseObject({
         $ref: z.string().optional(),
-        $defs: z.record(z.string(), schemaNode).optional(),
-        definitions: z.record(z.string(), schemaNode).optional(),
+        $defs: z.record(z.string(), z.unknown()).optional(),
+        definitions: z.record(z.string(), z.unknown()).optional(),
         const: z.unknown().optional(),
         enum: z.array(z.unknown()).optional(),
-        oneOf: z.array(schemaNode).optional(),
-        anyOf: z.array(schemaNode).optional(),
-        allOf: z.array(schemaNode).optional(),
+        oneOf: z.array(z.unknown()).optional(),
+        anyOf: z.array(z.unknown()).optional(),
+        allOf: z.array(z.unknown()).optional(),
         type: z.union([z.string(), z.array(z.string())]).optional(),
-        properties: z.record(z.string(), schemaNode).optional(),
-        additionalProperties: schemaNode.optional(),
+        properties: z.record(z.string(), z.unknown()).optional(),
+        additionalProperties: z.unknown().optional(),
         required: z.array(z.string()).optional(),
-        prefixItems: z.array(schemaNode).optional(),
-        items: z.union([schemaNode, z.array(schemaNode)]).optional(),
+        prefixItems: z.array(z.unknown()).optional(),
+        items: z.unknown().optional(),
         examples: z.array(z.unknown()).optional(),
         default: z.unknown().optional(),
     }),
-]));
-/**
- * Facts already derived, per schema object and direction. A Standard JSON
- * Schema describes an immutable schema, so its projection is a pure function
- * of the object: compiling a catalog asks for the same projection several
- * times per operation (size, fingerprint, sample, rendering), and a host that
- * recompiles a catalog over the same installed schemas asks again on every
- * compile. Projecting, validating, fingerprinting and sizing once per schema
- * keeps catalog compilation proportional to what actually changed.
- */
-const schemaFacts = new WeakMap();
-function factsFor(schema, io) {
-    let entry = schemaFacts.get(schema);
+    z.boolean(),
+]);
+/** Standard JSON Schema projections are immutable, per source and direction. */
+const projections = new WeakMap();
+function projectionFor(schema, io) {
+    let entry = projections.get(schema);
     const cached = entry?.[io];
     if (cached !== undefined)
         return cached;
-    let node;
+    let raw;
     try {
-        node = schemaNode.parse(schema["~standard"].jsonSchema[io]({ target: "draft-2020-12" }));
+        raw = schema["~standard"].jsonSchema[io]({ target: "draft-2020-12" });
     }
     catch {
         throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
     }
-    const json = jsonValueSchema.safeParse(node);
-    const facts = {
-        node,
-        json: json.success ? json.data : undefined,
-    };
+    decodeNode(raw);
+    const projection = { raw };
     if (entry === undefined) {
         entry = {};
-        schemaFacts.set(schema, entry);
+        projections.set(schema, entry);
     }
-    entry[io] = facts;
-    return facts;
+    entry[io] = projection;
+    return projection;
 }
-function schemaFor(schema, io) {
-    return factsFor(schema, io).node;
+/** The producer's document, without a recursive projection decode or copy. */
+export function rawSchema(schema, io) {
+    return projectionFor(schema, io).raw;
 }
-function isNodeList(value) {
-    return Array.isArray(value);
+/** Native serialization owns the document's text representation and failures. */
+export function schemaText(schema, io) {
+    const projection = projectionFor(schema, io);
+    try {
+        projection.text ??= JSON.stringify(projection.raw);
+        return projection.text;
+    }
+    catch {
+        throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
+    }
+}
+function decodeNode(value) {
+    const parsed = schemaNode.safeParse(value);
+    if (!parsed.success)
+        throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
+    return parsed.data;
 }
 /** Bounds the work and size of expanding shared `$defs` in one description. */
 const maximumReferenceExpansions = 256;
@@ -77,7 +81,7 @@ function renderReference(reference, depth, refs) {
     refs.budget.expansions += 1;
     if (refs.budget.expansions > maximumReferenceExpansions)
         throw new ForageError("invalid_input", `Schema references expand more than ${String(maximumReferenceExpansions)} times; flatten its shared definitions`);
-    return renderNode(target, depth, {
+    return renderNode(decodeNode(target), depth, {
         definitions: refs.definitions,
         expanding: new Set([...refs.expanding, name]),
         budget: refs.budget,
@@ -94,7 +98,7 @@ function rendersUnion(node, refs) {
             : refs.definitions[name];
         return (name !== undefined &&
             target !== undefined &&
-            rendersUnion(target, {
+            rendersUnion(decodeNode(target), {
                 definitions: refs.definitions,
                 expanding: new Set([...refs.expanding, name]),
                 budget: refs.budget,
@@ -106,10 +110,17 @@ function rendersUnion(node, refs) {
         (node.oneOf !== undefined && node.oneOf.length > 1) ||
         (node.anyOf !== undefined && node.anyOf.length > 1));
 }
-function renderNode(node, depth, refs) {
-    if (node === undefined || node === true || node === false || depth > 12) {
+function renderNode(node, depth, scope) {
+    if (depth > 12) {
         return "unknown";
     }
+    if (node === true || node === false)
+        return "unknown";
+    const refs = scope ?? {
+        definitions: { ...node.definitions, ...node.$defs },
+        expanding: new Set(),
+        budget: { expansions: 0 },
+    };
     if (node.$ref)
         return renderReference(node.$ref, depth, refs);
     if (node.const !== undefined)
@@ -118,20 +129,21 @@ function renderNode(node, depth, refs) {
         return node.enum.map((value) => JSON.stringify(value)).join(" | ");
     if (node.oneOf) {
         return node.oneOf
-            .map((value) => renderNode(value, depth + 1, refs))
+            .map((value) => renderNode(decodeNode(value), depth + 1, refs))
             .join(" | ");
     }
     if (node.anyOf) {
         return node.anyOf
-            .map((value) => renderNode(value, depth + 1, refs))
+            .map((value) => renderNode(decodeNode(value), depth + 1, refs))
             .join(" | ");
     }
     if (node.allOf) {
         return node.allOf
             .map((value) => {
-            const member = renderNode(value, depth + 1, refs);
+            const child = decodeNode(value);
+            const member = renderNode(child, depth + 1, refs);
             // `&` binds tighter than `|`: keep a union member whole.
-            return rendersUnion(value, refs) ? `(${member})` : member;
+            return rendersUnion(child, refs) ? `(${member})` : member;
         })
             .join(" & ");
     }
@@ -142,13 +154,13 @@ function renderNode(node, depth, refs) {
             if (additional === false)
                 return "Record<string, never>";
             if (additional && additional !== true) {
-                return `Record<string, ${renderNode(additional, depth + 1, refs)}>`;
+                return `Record<string, ${renderNode(decodeNode(additional), depth + 1, refs)}>`;
             }
             return "Record<string, unknown>";
         }
         const required = new Set(node.required ?? []);
         const lines = properties.map(([key, value]) => {
-            const child = renderNode(value, depth + 1, refs);
+            const child = renderNode(decodeNode(value), depth + 1, refs);
             const optional = required.has(key) ? "" : "?";
             const safeKey = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
                 ? key
@@ -162,21 +174,21 @@ ${"  ".repeat(depth)}}`;
     if (node.type === "array") {
         const items = node.items;
         if (node.prefixItems && node.prefixItems.length > 0) {
-            const tuple = node.prefixItems.map((value) => renderNode(value, depth + 1, refs));
-            if (items !== undefined && items !== true && !isNodeList(items)) {
-                tuple.push(`...${renderNode(items, depth + 1, refs)}[]`);
+            const tuple = node.prefixItems.map((value) => renderNode(decodeNode(value), depth + 1, refs));
+            if (items !== undefined && items !== true && !Array.isArray(items)) {
+                tuple.push(`...${renderNode(decodeNode(items), depth + 1, refs)}[]`);
             }
             return `[${tuple.join(", ")}]`;
         }
-        if (items !== undefined && isNodeList(items))
-            return `[${items.map((value) => renderNode(value, depth + 1, refs)).join(", ")}][]`;
-        const item = renderNode(items, depth + 1, refs);
-        const compoundItem = items !== undefined &&
-            items !== true &&
-            items !== false &&
-            (items.oneOf !== undefined ||
-                items.anyOf !== undefined ||
-                items.allOf !== undefined);
+        if (items !== undefined && Array.isArray(items))
+            return `[${items.map((value) => renderNode(decodeNode(value), depth + 1, refs)).join(", ")}][]`;
+        const itemNode = items === undefined ? true : decodeNode(items);
+        const item = renderNode(itemNode, depth + 1, refs);
+        const compoundItem = itemNode !== true &&
+            itemNode !== false &&
+            (itemNode.oneOf !== undefined ||
+                itemNode.anyOf !== undefined ||
+                itemNode.allOf !== undefined);
         return `${compoundItem ? `(${item})` : item}[]`;
     }
     switch (node.type) {
@@ -195,15 +207,7 @@ ${"  ".repeat(depth)}}`;
 }
 /** Render one schema's JSON Schema as deterministic TypeScript type text. */
 function renderSchemaType(schema, io = "input") {
-    const root = schemaFor(schema, io);
-    const definitions = root === true || root === false
-        ? {}
-        : { ...root.definitions, ...root.$defs };
-    return renderNode(root, 0, {
-        definitions,
-        expanding: new Set(),
-        budget: { expansions: 0 },
-    });
+    return renderNode(decodeNode(rawSchema(schema, io)), 0);
 }
 function safeTypeName(name) {
     return name.replace(/[^A-Za-z0-9_$]/g, "_");
@@ -228,33 +232,38 @@ export function renderOperationTypes(operations) {
         ? types
         : `${types}\nexport declare const env: ${operations.map((operation) => operation.environment).join(" & ")};`;
 }
-/** Prepare all TypeScript descriptions for one operation at installation. */
+const renderedOperations = new WeakMap();
+/** Render only requested operations, once per immutable prepared operation. */
 export function renderOperation(operation) {
+    const cached = renderedOperations.get(operation);
+    if (cached !== undefined)
+        return cached;
     const name = safeTypeName(operation.path.replace(/\./g, "$"));
     const input = renderSchemaType(operation.input, "input");
     const output = operation.output
         ? renderSchemaType(operation.output, "output")
         : "unknown";
-    return Object.freeze({
+    const rendered = Object.freeze({
         indexEnvironment: renderEnvironment(operation.path, input, output),
         environment: renderEnvironment(operation.path, `${name}_Input`, `${name}_Output`),
         types: `export type ${name}_Input = ${input};\nexport type ${name}_Output = ${output};`,
     });
+    renderedOperations.set(operation, rendered);
+    return rendered;
 }
 /** Derive sample arguments solely from input-schema examples and defaults. */
 export function deriveSample(schema) {
-    const node = schemaFor(schema, "input");
+    const node = decodeNode(rawSchema(schema, "input"));
     if (node === true || node === false || !node.properties) {
         return undefined;
     }
-    const properties = node.properties;
     const sample = {};
     let found = false;
-    const entries = Object.entries(properties).sort(([left], [right]) => compareCodeUnits(left, right));
+    const entries = Object.entries(node.properties).sort(([left], [right]) => compareCodeUnits(left, right));
     for (const [key, value] of entries) {
-        if (value === true || value === false)
+        const property = decodeNode(value);
+        if (property === true || property === false)
             continue;
-        const property = value;
         const examples = property.examples;
         if (examples && examples.length > 0) {
             const example = jsonValueSchema.safeParse(examples[0]);
@@ -273,69 +282,3 @@ export function deriveSample(schema) {
     }
     return found ? sample : undefined;
 }
-/** Preserve validator constraints in the operation's Standard JSON Schema. */
-export function inputSchemaProjection(schema) {
-    const projection = factsFor(schema, "input").json;
-    if (projection === undefined) {
-        throw new ForageError("invalid_input", "Schema cannot be projected to JSON Schema");
-    }
-    return projection;
-}
-/** Produce a canonical schema representation used in peer identity and stamps. */
-export function schemaFingerprint(schema, io = "input") {
-    const facts = factsFor(schema, io);
-    facts.fingerprint ??= canonicalStringify(facts.json ?? null);
-    return facts.fingerprint;
-}
-function schemaDepth(value, depth) {
-    if (depth > maximumSampleDepth)
-        return depth;
-    if (Array.isArray(value)) {
-        let maximum = depth;
-        for (const item of value) {
-            maximum = Math.max(maximum, schemaDepth(item, depth + 1));
-        }
-        return maximum;
-    }
-    if (!isJsonObject(value))
-        return depth;
-    let maximum = depth;
-    for (const entry of Object.values(value)) {
-        maximum = Math.max(maximum, schemaDepth(entry, depth + 1));
-    }
-    return maximum;
-}
-/** Validate the bounded JSON projection before a catalog is installed. */
-export function schemaProjectionSize(schema, io) {
-    const facts = factsFor(schema, io);
-    facts.size ??= { bytes: measureProjection(schema, io, facts.json) };
-    return facts.size.bytes;
-}
-function measureProjection(schema, io, projection) {
-    if (!projection)
-        return undefined;
-    const encoded = JSON.stringify(projection);
-    if (encoded.length > 20_000 ||
-        schemaDepth(projection, 0) > maximumSampleDepth) {
-        return undefined;
-    }
-    if (io === "output")
-        return encoded.length;
-    const sample = deriveSample(schema);
-    if (!sample)
-        return encoded.length;
-    if (Object.keys(sample).length > maximumSampleEntries ||
-        schemaDepth(sample, 0) > maximumSampleDepth) {
-        return undefined;
-    }
-    let sampleText;
-    try {
-        sampleText = JSON.stringify(sample);
-    }
-    catch {
-        throw new ForageError("invalid_input", "Derived schema sample cannot be serialized");
-    }
-    if (!sampleText || sampleText.length > maximumSampleBytes)
-        return undefined;
-    return encoded.length + sampleText.length;
-}

package/dist/schemas.d.ts

@@ -3,6 +3,7 @@ export declare const maximumDescriptionTypes = 20000;
 export declare const maximumSampleEntries = 100;
 export declare const maximumSampleBytes = 4000;
 export declare const maximumSampleDepth = 16;
+export declare function jsonDepth(value: z.output<z.ZodJSONSchema>, depth: number): number;
 /** Input accepted by the pure catalog search seam. */
 export declare const forageSearchInput: z.ZodLazy<z.ZodObject<{
     query: z.ZodString;

package/dist/schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isJsonObject } from "./normalization.js";
 const pathPattern = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/;
 const maximumCatalogOperations = 1_000;
 const maximumScore = 221;
@@ -6,7 +7,7 @@ export const maximumDescriptionTypes = 20_000;
 export const maximumSampleEntries = 100;
 export const maximumSampleBytes = 4_000;
 export const maximumSampleDepth = 16;
-function jsonDepth(value, depth) {
+export function jsonDepth(value, depth) {
     if (depth > maximumSampleDepth)
         return depth;
     if (Array.isArray(value)) {
@@ -16,13 +17,10 @@ function jsonDepth(value, depth) {
         }
         return maximum;
     }
-    if (value === null)
-        return depth;
-    const record = z.record(z.string(), z.json()).safeParse(value);
-    if (!record.success)
+    if (!isJsonObject(value))
         return depth;
     let maximum = depth;
-    for (const item of Object.values(record.data)) {
+    for (const item of Object.values(value)) {
         maximum = Math.max(maximum, jsonDepth(item, depth + 1));
     }
     return maximum;

package/dist/search.d.ts

@@ -1,12 +1,11 @@
 import { type Operation, type SearchOutput } from "./schemas.js";
-import { type RenderedOperation } from "./rendering.js";
 import type { JsonValue } from "./normalization.js";
 /** Private installation-time projection used by the pure ranking function. */
 export type PreparedOperation = Operation & {
     readonly fingerprint: string;
-    readonly inputSchema: JsonValue;
     readonly sample: Record<string, JsonValue> | undefined;
-    readonly rendered: RenderedOperation;
+    readonly inputBytes: number;
+    readonly outputBytes: number;
 };
 /** Prepare schema-derived search metadata once for an immutable catalog revision. */
 export declare function prepareOperation(operation: Operation): PreparedOperation;

package/dist/search.js

@@ -1,15 +1,17 @@
 import { searchOutputSchema, } from "./schemas.js";
-import { canonicalStringify, compareCodeUnits, hashString64, isStopword, normalizeQuery, operationMethod, operationNamespace, stemVariants, tokenize, } from "./normalization.js";
-import { deriveSample, inputSchemaProjection, renderOperation, schemaFingerprint, } from "./rendering.js";
+import { compareCodeUnits, hashString64, isStopword, normalizeQuery, operationMethod, operationNamespace, stemVariants, tokenize, } from "./normalization.js";
+import { deriveSample, schemaText } from "./rendering.js";
 import { ForageError } from "./errors.js";
 /** Prepare schema-derived search metadata once for an immutable catalog revision. */
 export function prepareOperation(operation) {
+    const input = schemaText(operation.input, "input");
+    const output = operation.output ? schemaText(operation.output, "output") : "";
     return Object.freeze({
         ...operation,
-        fingerprint: schemaFingerprint(operation.input),
-        inputSchema: inputSchemaProjection(operation.input),
+        fingerprint: hashString64(input + "\n" + output),
+        inputBytes: input.length,
+        outputBytes: output.length,
         sample: deriveSample(operation.input),
-        rendered: renderOperation(operation),
     });
 }
 const matchWeight = {
@@ -21,33 +23,33 @@ const matchWeight = {
     substring: 2,
     includes: 1,
 };
-function fieldWeight(field) {
-    switch (field) {
-        case "path":
-            return 12;
-        case "namespace":
-            return 8;
-        case "method":
-            return 10;
-        case "description":
-            return 5;
-        default:
-            return 5;
-    }
-}
+const fieldWeight = {
+    path: 12,
+    namespace: 8,
+    method: 10,
+    description: 5,
+};
+const fullCoverageBonus = 25;
+const partialCoverageBonus = 10;
+const firstTokenBonus = 8;
+const exactMatchBonus = 20;
+const maxBonus = Math.max(fullCoverageBonus, partialCoverageBonus) +
+    firstTokenBonus +
+    exactMatchBonus;
+const dominanceDivisor = 1 +
+    Math.max(...Object.values(matchWeight)) *
+        Math.max(...Object.values(fieldWeight)) +
+    maxBonus;
 /** Identify every model-visible part of the catalog, including schemas. */
 function catalogStamp(operations) {
     const lines = [...operations]
         .sort((left, right) => compareCodeUnits(left.path, right.path))
-        .map((operation) => canonicalStringify([
+        .map((operation) => JSON.stringify([
         operation.path,
         operation.description ?? null,
         operation.capabilityNotes ?? null,
         operation.instructions ?? null,
         operation.fingerprint,
-        operation.output === undefined
-            ? null
-            : schemaFingerprint(operation.output, "output"),
     ]));
     return hashString64(lines.join("\n"));
 }
@@ -74,7 +76,7 @@ function scoreField(rawValue, field, queryTokens) {
     const value = normalizeQuery(rawValue);
     let bestLevel = "none";
     let bestScore = 0;
-    let matchedTokens = [];
+    const matchedTokens = [];
     for (const token of queryTokens) {
         const terms = [token, ...stemVariants(token)];
         let selected = "none";
@@ -87,14 +89,12 @@ function scoreField(rawValue, field, queryTokens) {
         }
         if (selected === "none")
             continue;
-        const score = matchWeight[selected] * fieldWeight(field);
+        const score = matchWeight[selected] * fieldWeight[field];
+        if (!matchedTokens.includes(token))
+            matchedTokens.push(token);
         if (score > bestScore) {
             bestLevel = selected;
             bestScore = score;
-            matchedTokens = [token];
-        }
-        else if (score === bestScore && !matchedTokens.includes(token)) {
-            matchedTokens.push(token);
         }
     }
     return { level: bestLevel, score: bestScore, matchedTokens };
@@ -139,7 +139,7 @@ function emptyResult(stamp) {
         catalogStamp: stamp,
     });
 }
-function scoreCandidate(operation, normalizedQuery, queryTokens, coverageTokens, threshold) {
+function scoreCandidate(operation, queryTokens, coverageTokens) {
     const namespace = operationNamespace(operation.path);
     const method = operationMethod(operation.path);
     const description = operation.description ?? "";
@@ -149,23 +149,27 @@ function scoreCandidate(operation, normalizedQuery, queryTokens, coverageTokens,
     const methodScore = scoreField(method, "method", queryTokens);
     const descriptionScore = scoreField(description, "description", queryTokens);
     const matched = coverageTokens.filter((token) => fields.some((field) => tokenMatches(field, token))).length;
-    const coverage = matched / coverageTokens.length;
-    const phraseMatch = normalizeQuery(`${operation.path} ${description}`).includes(normalizedQuery);
-    if (coverage < threshold && !phraseMatch)
+    if (matched === 0)
         return undefined;
+    const coverage = matched / coverageTokens.length;
     const baseScore = Math.max(pathScore.score, namespaceScore.score, methodScore.score, descriptionScore.score);
     if (baseScore === 0)
         return undefined;
-    let bonus = matched === coverageTokens.length ? 25 : coverage * 10;
+    let bonus = matched === coverageTokens.length
+        ? fullCoverageBonus
+        : coverage * partialCoverageBonus;
     const firstToken = coverageTokens[0];
     if (firstToken && fields.some((field) => tokenMatches(field, firstToken))) {
-        bonus += 8;
+        bonus += firstTokenBonus;
+    }
+    if (pathScore.level === "exact" || methodScore.level === "exact") {
+        bonus += exactMatchBonus;
     }
-    if (pathScore.level === "exact" || methodScore.level === "exact")
-        bonus += 20;
     const result = {
         path: operation.path,
-        score: baseScore + bonus,
+        // A whole matched word outranks any field-quality difference; the
+        // derived divisor keeps all field and bonus evidence below one word.
+        score: matched + (baseScore + bonus) / dominanceDivisor,
     };
     if (description)
         result.description = description;
@@ -246,10 +250,9 @@ export function searchCatalog(operations, query, maxResults = 50, stamp) {
     const coverageTokens = queryTokens.filter((token) => !isStopword(token));
     if (coverageTokens.length === 0)
         return emptyResult(stamp);
-    const threshold = coverageTokens.length <= 2 ? 1 : 0.6;
     const candidates = [];
     for (const operation of operations) {
-        const candidate = scoreCandidate(operation, normalizedQuery, queryTokens, coverageTokens, threshold);
+        const candidate = scoreCandidate(operation, queryTokens, coverageTokens);
         if (candidate)
             candidates.push(candidate);
     }

package/docs/api/index.md

@@ -622,16 +622,47 @@ The shared JSON-Schema compiler for App methods and OpenAPI operations.
 
 ---
 
+### appJsonSchema()
+
+```ts
+function appJsonSchema(
+  declaration,
+): Pick<
+  z.ZodType<z.output<z.ZodJSONSchema>>,
+  "parse" | "safeParse" | "~standard"
+>;
+```
+
+One decoded, immutable App declaration as a JSON-only Standard Schema. Release
+and family-listing decoders own its JSON boundary. A catalog describes every
+installed method on each capture but a turn validates only the few it calls.
+Compiling every method eagerly exhausted an Agent Durable Object's isolate. A
+draft 2020-12 description is the declaration itself; validators compile for the
+call in hand and are never kept on the surface.
+
+#### Parameters
+
+| Parameter     | Type                                                                                                                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `declaration` | \| `boolean` \| \{ \[`key`: `string`\]: \| `null` \| `string` \| `number` \| `false` \| `true` \| \{ \[`index`: `number`\]: AppApiJsonValue; `length`: `number`; \} \| AppApiJsonObject; \} |
+
+#### Returns
+
+`Pick`\<`z.ZodType`\<`z.output`\<`z.ZodJSONSchema`\>\>, `"parse"` \|
+`"safeParse"` \| `"~standard"`\>
+
+---
+
 ### 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.
+Describe App methods with call-scoped JSON validators. 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
 
@@ -651,7 +682,7 @@ includes Pending for opted-in methods.
 function appToolSchemas(api): object;
 ```
 
-Compile discoverable App methods only; direct RPC validation uses
+Describe discoverable App methods only; direct RPC validation uses
 appMethodSchemas.
 
 #### Parameters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/forage",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.2.0",
+    "@fungi.computer/puffball": "0.3.0",
     "yaml": "2.9.0",
     "zod": "4.4.3"
   },