@modelprofile.com/flexharness 13.0.0 → 13.1.1

package/ts_typedrequest/describe.ts

@@ -7,14 +7,11 @@ import type {
   TFlexTypedRequestSchema,
 } from './interfaces.js';
 import { normalizeOmissionPaths } from './omissions.js';
+import { definitionsPrefix, isRecord, referencedType, referencesIn } from './references.js';
 
 const componentsPrefix = '#/components/schemas/';
-const definitionsPrefix = '#/$defs/';
 const maxSummaryCharacters = 120;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
 /** A schema whose references name `#/$defs/<type>` instead of the OpenAPI components. */
 const withDefinitionRefs = (value: unknown): unknown => {
   if (Array.isArray(value)) return value.map(withDefinitionRefs);
@@ -27,12 +24,6 @@ const withDefinitionRefs = (value: unknown): unknown => {
   ]));
 };
 
-/** The type a `#/$defs/<type>` reference names. */
-const referencedType = (schema: TFlexTypedRequestSchema): string | undefined =>
-  typeof schema.$ref === 'string' && schema.$ref.startsWith(definitionsPrefix)
-    ? schema.$ref.slice(definitionsPrefix.length)
-    : undefined;
-
 /**
  * A request schema without the omitted properties: an object loses them, and a reference to a
  * named type that holds one becomes the type's own schema without them.
@@ -167,18 +158,6 @@ const requiresNothing = (
     || schema.allOf.every((member) => !isRecord(member) || requiresNothing(member, types));
 };
 
-/** The named types a schema refers to. */
-const referencesIn = (value: unknown, found: Set<string>): Set<string> => {
-  if (Array.isArray(value)) {
-    for (const entry of value) referencesIn(entry, found);
-  } else if (isRecord(value)) {
-    const target = referencedType(value);
-    if (target !== undefined) found.add(target);
-    for (const child of Object.values(value)) referencesIn(child, found);
-  }
-  return found;
-};
-
 /** The first sentence of a contract's JSDoc, its tags left out, within the summary's length. */
 const summaryOf = (documentation: string | undefined, method: string): string => {
   const prose = (documentation ?? '').split(/\n(?=@)/)[0].replace(/\s+/g, ' ').trim();

package/ts_typedrequest/interfaces.ts

@@ -125,7 +125,10 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
     method: IFlexTypedRequestMethod,
     context: IFlexCatalogRunContext<TScope>,
   ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
-  /** The methods the model may use. Default: every method that is not deprecated. */
+  /**
+   * The methods the model may use. Default: every method that is not deprecated. The catalog keeps
+   * only the named types these methods reach.
+   */
   include?(method: IFlexTypedRequestMethod): boolean;
   /**
    * The methods that only read: a call has no effect but its result. Such a method is declared

package/ts_typedrequest/readme.md

@@ -41,7 +41,7 @@ The surface is plain JSON, so a build step can write it next to the server and t
 - `request` fills the omitted properties. A call takes from what it returns only the omitted properties its method's request has, so one answer serves every method (`{ identity, csrfToken }`), and a method whose request has none is routed without asking it. A value the model passes for any omitted property never reaches the router.
 - Method-specific fills copy only the selected leaves, retaining public siblings. Array wildcards fill existing elements at corresponding indexes without adding or removing elements. An absent object parent can be created for a supplied leaf; an explicit null or scalar parent is refused. Input objects are not mutated. A surface with additional paths requires `request`; a serialized global-only surface without `omittedPaths` remains valid.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
-- `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
+- `include` picks the methods the model may use, by default every method that is not deprecated, and the catalog's types are the surface's types those methods reach, through their schemas' `$ref`s and the names their declarations' code uses: a type only methods left out use is neither declared nor described, unless it holds a lower identifier of a kept type's name, which keeps that type's identifier as the whole surface declares it (`a_b` stays for `a-b`, declared `a_b_2`; `FlexToolCatalog.identifiersOf()`). `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
 - `readOnly` marks the methods that only read, including their policy hook. A marked method is declared `readOnly` and its `onCall` still decides every validated call, so reads run concurrently, may start while the model still streams, and a turn answers identical ones once after each call's hook allows it; every other method's calls, gated by `onCall` or not, run in the order the model made them. A policy that proposes changes must return `run` for the reads it allows, rather than relying on reads skipping the hook. Mark nothing that asks for permission.
 - `params` makes the request a call routes of the model's validated parameters, such as the parameters with the short names the model was shown for records turned back into their IDs; by default the parameters themselves. It runs when the call runs, after `onCall` decided it where the method has one, so `onCall` and a proposal see the model's parameters. The omitted properties are dropped from what it returns as from the model's, and only `request` fills them. A throw refuses the call with its error, and so does a result that is no object.
 - The same validation, policy, stripping and filling apply to `execute` and every call inside `run_code`. Private inputs are rejected before `onCall`; a proposed change does not run `params`, `request` or the router. Omissions cover inputs only: use `response` to remove secrets from answers before they reach the model.

package/ts_typedrequest/references.ts

@@ -0,0 +1,68 @@
+import * as plugins from './plugins.js';
+import type { IFlexCatalogType } from '@modelprofile.com/flexharness';
+import type { IFlexTypedRequestMethod, TFlexTypedRequestSchema } from './interfaces.js';
+
+export const definitionsPrefix = '#/$defs/';
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The type a `#/$defs/<type>` reference names. */
+export const referencedType = (schema: TFlexTypedRequestSchema): string | undefined =>
+  typeof schema.$ref === 'string' && schema.$ref.startsWith(definitionsPrefix)
+    ? schema.$ref.slice(definitionsPrefix.length)
+    : undefined;
+
+/** The named types a schema refers to. */
+export const referencesIn = (value: unknown, found: Set<string>): Set<string> => {
+  if (Array.isArray(value)) {
+    for (const entry of value) referencesIn(entry, found);
+  } else if (isRecord(value)) {
+    const target = referencedType(value);
+    if (target !== undefined) found.add(target);
+    for (const child of Object.values(value)) referencesIn(child, found);
+  }
+  return found;
+};
+
+/**
+ * The types of `types` that `methods` reach, in their order: the ones the methods' schemas refer
+ * to and their declarations' code names, and the ones those types reach the same way. A type only
+ * other methods use is left out. A declaration names a type by the identifier the catalog of all of
+ * `types` declares it under (`FlexToolCatalog.identifiersOf()`); as that depends on the other
+ * types, a reached type keeps the ones that took the lower identifiers of its name along, so it is
+ * declared under the same identifier.
+ */
+export const typesReachedBy = (
+  methods: readonly IFlexTypedRequestMethod[],
+  types: readonly IFlexCatalogType[],
+): IFlexCatalogType[] => {
+  const identifiers = plugins.FlexToolCatalog.identifiersOf(types.map((type) => type.name));
+  const byName = new Map(types.map((type) => [type.name, type]));
+  const byIdentifier = new Map(types.map((type) => [identifiers.get(type.name)!, type]));
+  const pending: IFlexCatalogType[] = [];
+  const reach = (schemas: unknown, declaration: string | undefined) => {
+    for (const name of referencesIn(schemas, new Set())) {
+      const type = byName.get(name);
+      if (type !== undefined) pending.push(type);
+    }
+    for (const identifier of declaration === undefined ? [] : plugins.FlexToolCatalog.identifiersIn(declaration)) {
+      const type = byIdentifier.get(identifier);
+      if (type !== undefined) pending.push(type);
+    }
+  };
+  for (const method of methods) reach([method.inputSchema, method.outputSchema], method.declaration);
+  const reached = new Set<IFlexCatalogType>();
+  while (pending.length) {
+    const type = pending.pop()!;
+    if (reached.has(type)) continue;
+    reached.add(type);
+    reach(type.schema, type.declaration);
+    const identifier = identifiers.get(type.name)!;
+    const base = plugins.FlexToolCatalog.identifierOf(type.name);
+    for (let suffix = 1, lower = base; lower !== identifier; lower = `${base}_${++suffix}`) {
+      pending.push(byIdentifier.get(lower)!);
+    }
+  }
+  return types.filter((type) => reached.has(type));
+};