@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/foundation/release/handoff.d.mts

@@ -10,6 +10,14 @@
  * @returns {string}
  */
 export function whoAnsweredLine(choice: import("./choose.mjs").ReleaseChoice, computer?: boolean): string;
+/**
+ * The line for a run this copy answers in place of the project's own CLI,
+ * which a host declined, when this copy is that CLI's release (FR2).
+ * @param {string} version
+ * @param {string} reason the reason, as {@link declinedReasonText} words it
+ * @returns {string}
+ */
+export function inPlaceOfProjectLine(version: string, reason: string): string;
 /**
  * The line for a run handed to the project's own CLI.
  * @param {string} projectVersion
@@ -41,15 +49,26 @@ export function progressText(event: "install" | "wait", version: string): string
  * @returns {string}
  */
 export function fallbackLine(wanted: string, reason: string, answering: string): string;
+/**
+ * The fallback warning's reason for a project CLI a host declined.
+ * @param {string} reason the host's own words
+ * @returns {string}
+ */
+export function declinedReasonText(reason: string): string;
 /**
  * Choose who answers and hand off when it is not this copy.
- * @param {{cliRoot: string, argv: string[]}} input argv after `node astryx`
- * @returns {Promise<void>} resolves when this copy answers
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ *   argv after `node astryx`; the reason a programmatic host declined the
+ *   project's own CLI, when it did
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves with nothing when this copy answers, and with that release's
+ *   result when another package set's host entry answered a hosted run
  */
-export function startRun({ cliRoot, argv }: {
+export function startRun({ cliRoot, argv, declinedProjectCli }: {
     cliRoot: string;
     argv: string[];
-}): Promise<void>;
+    declinedProjectCli?: string;
+}): Promise<import("../../host/index.js").HostedCliResult | undefined>;
 /**
  * How long a hand-off waits after an interrupt before passing it on to a CLI
  * that is still running. An interrupt sent to the whole process group (a

package/foundation/release/handoff.mjs

@@ -19,9 +19,26 @@
  * (notices.mjs); a global copy also starts the daily update check, which
  * installs nothing (global-state.mjs).
  *
- * @input  the running copy, argv, the working folder
- * @output returns when this copy answers; otherwise never returns
- * @position foundation/release — called once by clients/cli/bin/astryx.mjs.
+ * A programmatic host that found the project's own CLI and did not run it
+ * passes the reason (spec AST-081 FR1, FR2). That run is never handed to the
+ * project's CLI: this copy answers in its place when it is that CLI's release,
+ * saying so in a line of its own; a package set of the host's whose CLI is
+ * that release answers through its own host entry; and otherwise this copy
+ * answers as for a release that cannot be obtained, with the warning naming
+ * the reason.
+ *
+ * A hosted run installs nothing (architecture:cli-surface INV30): a release
+ * other than this copy comes only from the first of the host's package sets
+ * that qualifies. When that CLI ships a host entry, the entry runs in this
+ * process with the same inputs, discover sources included, and the host's
+ * call settles with its result; otherwise its bin takes the run. With no such
+ * set, this copy answers, announced.
+ *
+ * @input  the running copy, argv, the working folder, and a host's
+ *   declined-project-CLI reason
+ * @output returns when this copy answers, or with another release's result
+ *   when its host entry answered; never returns after a hand-off to a bin
+ * @position foundation/release — called once per run by clients/cli/run.mjs.
  */
 
 import {spawn} from 'node:child_process';
@@ -32,8 +49,10 @@ import {
   isGlobalCopy,
   namesWhoAnswered,
   packageRootOf,
+  projectRootOf,
   runningCopy,
 } from './choose.mjs';
+import {readReleaseFacts} from './project.mjs';
 import {ensureRelease, userCacheDir} from './cache.mjs';
 import {
   maybeFetchCore,
@@ -43,6 +62,8 @@ import {
 import {recordRunChoice} from './run-context.mjs';
 import {noticeLines} from './notices.mjs';
 import {cliDoor, runWithCliDoor} from '../env/cli-command.mjs';
+import {hostedRun} from '../runtime/package-root.mjs';
+import {qualifyingRoot} from '../runtime/package-set.mjs';
 
 /** Where each release's notes are published. */
 
@@ -63,6 +84,17 @@ export function whoAnsweredLine(choice, computer = false) {
     : `astryx: answered by CLI ${choice.version} with Core ${core}, outside a project`;
 }
 
+/**
+ * The line for a run this copy answers in place of the project's own CLI,
+ * which a host declined, when this copy is that CLI's release (FR2).
+ * @param {string} version
+ * @param {string} reason the reason, as {@link declinedReasonText} words it
+ * @returns {string}
+ */
+export function inPlaceOfProjectLine(version, reason) {
+  return `astryx: answered by CLI ${version}, the release of this project's CLI, in its place (${reason})`;
+}
+
 /**
  * The line for a run handed to the project's own CLI.
  * @param {string} projectVersion
@@ -131,16 +163,32 @@ function failUnavailable(message, json) {
   process.exit(1);
 }
 
+/**
+ * The fallback warning's reason for a project CLI a host declined.
+ * @param {string} reason the host's own words
+ * @returns {string}
+ */
+export function declinedReasonText(reason) {
+  return `project CLI skipped: ${reason}`;
+}
+
 /**
  * Choose who answers and hand off when it is not this copy.
- * @param {{cliRoot: string, argv: string[]}} input argv after `node astryx`
- * @returns {Promise<void>} resolves when this copy answers
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ *   argv after `node astryx`; the reason a programmatic host declined the
+ *   project's own CLI, when it did
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves with nothing when this copy answers, and with that release's
+ *   result when another package set's host entry answered a hosted run
  */
-export async function startRun({cliRoot, argv}) {
+export async function startRun({cliRoot, argv, declinedProjectCli}) {
   const json = argv.includes('--json');
   const self = runningCopy(cliRoot);
   const cacheDir = userCacheDir();
-  const global = isGlobalCopy(cliRoot, cacheDir);
+  // A host carries its own CLI and keeps it current itself: a hosted copy
+  // runs none of the global copy's background work, and installs nothing.
+  const hosted = hostedRun();
+  const global = !hosted && isGlobalCopy(cliRoot, cacheDir);
   if (global) {
     try {
       maybeStartCheck();
@@ -189,7 +237,46 @@ export async function startRun({cliRoot, argv}) {
     };
   }
 
-  if (choice.unavailable && choice.copy === 'project') {
+  // A host declined the project's own CLI (FR2): the run is never handed to
+  // it. The release equal to that CLI's version answers in its place when
+  // this copy is that release, or when a package set of the host's holds it
+  // with a host entry; otherwise this copy answers, announced as for a release
+  // that cannot be obtained, naming the reason.
+  let declined = null;
+  /** Set when this copy answers in place of the declined CLI, its release. */
+  let inPlace = null;
+  if (
+    declinedProjectCli &&
+    choice.copy === 'project' &&
+    choice.answer !== 'self'
+  ) {
+    if (choice.version === self.version) {
+      // Still the project CLI's release (`copy` stays `project`), never the
+      // release matched to the project's Core, which can be another.
+      choice = {...choice, answer: 'self', bin: null, unavailable: null};
+      inPlace = declinedReasonText(declinedProjectCli);
+    } else {
+      const served = hosted
+        ? qualifyingRoot({
+            release: choice.version,
+            projectDir: projectDirOf(process.cwd()),
+            roots: hosted.roots,
+            needsHostEntry: true,
+          })
+        : null;
+      if (served && 'root' in served && served.hostEntry) {
+        const answered = await answerInPackageSet(
+          served.hostEntry,
+          served.root,
+          {argv, declinedProjectCli},
+        );
+        if (answered) return answered;
+      }
+      declined = declinedReasonText(declinedProjectCli);
+    }
+  }
+
+  if (!declined && choice.unavailable && choice.copy === 'project') {
     failUnavailable(
       `This project's CLI ${choice.version} could not be started: ${choice.unavailable}. Reinstall the project's dependencies.`,
       json,
@@ -245,6 +332,11 @@ export async function startRun({cliRoot, argv}) {
     });
   };
 
+  if (declined) {
+    await fallBack(declined);
+    return;
+  }
+
   if (choice.unavailable) {
     await fallBack(choice.unavailable);
     return;
@@ -256,6 +348,8 @@ export async function startRun({cliRoot, argv}) {
     // line; a hint after the command, once a day, says how to match it.
     if (!json && (choice.copy === 'matched' || choice.copy === 'carried'))
       console.error(whoAnsweredLine(choice, computer));
+    else if (!json && inPlace)
+      console.error(inPlaceOfProjectLine(choice.version, inPlace));
     process.once('exit', code => {
       if (code === 0) notify();
     });
@@ -263,6 +357,32 @@ export async function startRun({cliRoot, argv}) {
   }
 
   let bin = choice.bin;
+  if (!bin && hosted) {
+    const served = qualifyingRoot({
+      release: choice.version,
+      projectDir: projectDirOf(process.cwd()),
+      roots: hosted.roots,
+    });
+    if (!('root' in served)) {
+      await fallBack(served.reason);
+      return;
+    }
+    if (served.hostEntry) {
+      const answered = await answerInPackageSet(served.hostEntry, served.root, {
+        argv,
+      });
+      if (answered) return answered;
+    }
+    // A hosted run installs nothing (INV30): a set whose CLI starts through
+    // neither its host entry nor a bin leaves this copy to answer.
+    if (!served.bin) {
+      await fallBack(
+        `the CLI ${choice.version} in the package set at ${served.root} could not be started`,
+      );
+      return;
+    }
+    bin = served.bin;
+  }
   if (!bin) {
     const release = ensureRelease(choice.version, {
       cacheDir,
@@ -295,6 +415,53 @@ export async function startRun({cliRoot, argv}) {
  */
 export const INTERRUPT_GRACE_MS = 5000;
 
+/**
+ * The project folder a run in `cwd` belongs to, or null outside a project.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+function projectDirOf(cwd) {
+  try {
+    return projectRootOf(readReleaseFacts(cwd));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hand a hosted run over to the CLI of one of the host's package sets,
+ * through that CLI's own host entry, in this process, with the inputs this run
+ * got: the arguments, the folder, the command name, the approved integrations,
+ * the discover sources, and the reason the host declined the project's CLI.
+ * Its roots are that package set alone. That CLI prints its own who-answered
+ * line and notices, and the host's call settles with its result.
+ * @param {string} hostEntry the package set's `host/index.mjs`
+ * @param {string} root the package set
+ * @param {{argv: string[], declinedProjectCli?: string}} run
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | null>} null
+ *   when the entry cannot be loaded, before anything ran
+ */
+async function answerInPackageSet(hostEntry, root, {argv, declinedProjectCli}) {
+  const hosted = hostedRun();
+  if (!hosted?.loadHostEntry) return null;
+  let answer;
+  try {
+    answer = await hosted.loadHostEntry(hostEntry);
+  } catch {
+    return null;
+  }
+  const door = cliDoor();
+  return answer({
+    argv,
+    cwd: process.cwd(),
+    roots: [root],
+    integrations: [...hosted.integrations],
+    discoverSources: [...hosted.discoverSources],
+    ...(door ? {cliCommand: door} : {}),
+    ...(declinedProjectCli ? {declinedProjectCli} : {}),
+  });
+}
+
 /**
  * Run `bin` as this run and end with its exit status.
  * @param {string} bin

package/foundation/release/run-context.mjs

@@ -22,6 +22,7 @@ import {progressLine} from './handoff.mjs';
 import {isJsonMode} from '../response/json.mjs';
 import {cachedRelease, ensureRelease, userCacheDir} from './cache.mjs';
 import {readJson, findReadCore, CORE_PACKAGE_NAME} from './project.mjs';
+import {hostedRun} from '../runtime/package-root.mjs';
 
 /** The running CLI package's folder. */
 const CLI_ROOT = path.resolve(
@@ -105,6 +106,19 @@ export function carriedCore(options = {}) {
   if (besidePkg?.name === CORE_PACKAGE_NAME && besidePkg.version === version) {
     return {dir: beside, unavailable: null};
   }
+  // A hosted run resolves from its package set alone and installs nothing
+  // (architecture:cli-surface INV30): the Core beside the CLI, or none.
+  if (hostedRun()) {
+    if (!fetch) return {dir: null, unavailable: null};
+    const reason =
+      "a hosted run installs nothing, and the host's package set holds no Core beside its CLI";
+    return {
+      dir: null,
+      unavailable: `Core ${version} could not be found: ${reason}`,
+      version,
+      reason,
+    };
+  }
   const cached = cachedRelease(version, cacheDir);
   if (cached) return {dir: cached.coreDir, unavailable: null};
   if (!fetch) return {dir: null, unavailable: null};

package/foundation/response/response-types.doc.mjs

@@ -338,7 +338,7 @@ export const doc = {
     {
       value: 'integration.validate',
       description:
-        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).',
+        'The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning | error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand, and the package layout findings added after the last minor release, each with its fix in the message (duplicate_component_doc, symlinked_root, unreadable_file, invalid_package_json, no_provider_id, source_without_component_doc where a doc and its source still pair), and doc_name_mismatch and unknown_block_component, until they become warnings in the next minor release. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked | skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked). When the manifest loads, docNames lists the component doc names it could not judge: status (checked), findings (always empty; a doc name the module its import names provably does not export is a doc_name_mismatch note, with its fix in the message) and unchecked ({file, name, reason}: a doc whose name differs from the name it is listed under and whose source exports cannot all be read, such as a re-export from another package). When the manifest loads, blockComponents lists the component names templates give in exampleFor or componentsUsed that could not be judged: status (checked), findings (always empty; a name neither the package nor Core has, and the template does not import, is an unknown_block_component note, with its fix in the message) and unchecked ({file, name, reason}: a name the template may reach through anything other than named imports and re-exports from Core, React, StyleX, local helpers or the entry of the package itself, such as an import from another package, a default or namespace import, an alias of or member read off an imported binding, require() or a dynamic import(), or a local module that cannot be read, or any name Core would have to resolve when Core is not installed).',
     },
     {
       value: 'integration.template-conflicts',

package/foundation/route/route.d.mts

@@ -0,0 +1,285 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file The small routing helper the commands that pick among candidates
+ * share (build, search): two node kinds and the runner that walks them.
+ *
+ * A searcher answers a request in its command's own result shape, or returns
+ * null to pass. A dispatcher scores nothing: it names the children that should
+ * answer, best first, with a confidence from 0 to 1. Below its floor, or when
+ * none of the children it named answers, its fallback searcher answers. A
+ * dispatcher's children may be dispatchers, so trees nest. A classifier is a
+ * dispatcher whose route is a static word-weight classifier: the request's
+ * tokens vote for a class, and a class with a searcher takes the request when
+ * the classifier is sure enough.
+ *
+ * A tree file types the helpers for its command once, by taking them from
+ * `routeKit` typed as `RouteKit<Request, Context, Answer>` (see
+ * api/search/tree.mjs); each node is then plain `{id, summary, run}`.
+ *
+ * Every node gets the same context, so any node can be run, measured, and
+ * tuned on its own: `runTree` takes an optional `tuning` with weights that
+ * replace a node's shipped weights for one call, and a trace callback that
+ * sees every step. Neither ever reaches a command's output.
+ *
+ * @input a tree of nodes, a request, and the context the command's adapter
+ *   gathered
+ * @output the first answer a searcher gives
+ * @position foundation; api/build and api/search build their trees with it
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {object} Searcher
+ * @property {'searcher'} kind
+ * @property {string} id
+ * @property {string} summary One plain line: what it answers.
+ * @property {(request: Request, ctx: Context, weights: unknown) => Answer | null | Promise<Answer | null>} run
+ *   `weights` is a tuning override for this node, or null for its shipped weights.
+ */
+/**
+ * @typedef {object} Route
+ * @property {readonly string[]} ids The children to try, best first.
+ * @property {number} confidence From 0 to 1.
+ */
+/**
+ * @template Request, Context
+ * @typedef {object} Dispatcher
+ * @property {'dispatcher'} kind
+ * @property {string} id
+ * @property {string} summary
+ * @property {readonly string[]} children
+ * @property {number} floor Below this confidence the fallback answers.
+ * @property {string} fallback A searcher's id.
+ * @property {(request: Request, ctx: Context, weights: unknown) => Route | Promise<Route>} route
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {Searcher<Request, Context, Answer> | Dispatcher<Request, Context>} TreeNode
+ */
+/**
+ * @template Request, Context, Answer
+ * @typedef {object} Tree
+ * @property {string} root
+ * @property {ReadonlyMap<string, TreeNode<Request, Context, Answer>>} nodes
+ */
+/**
+ * One step the runner took.
+ * @typedef {object} TraceStep
+ * @property {string} id
+ * @property {'searcher' | 'dispatcher'} kind
+ * @property {number} depth
+ * @property {boolean} fallback Whether this step ran as a fallback.
+ * @property {Route} [route] A dispatcher's route.
+ * @property {boolean} [answered] Whether a searcher answered.
+ */
+/**
+ * @typedef {object} Tuning
+ * @property {Readonly<Record<string, unknown>>} [weights] Weights by node id, replacing that node's shipped weights for this call.
+ * @property {(step: TraceStep) => void} [onTrace]
+ */
+/**
+ * Static classifier weights: one row of numbers per token, one number per
+ * class. A request's score for a class is the sum of its tokens' numbers.
+ * @typedef {object} ClassifierWeights
+ * @property {readonly string[]} classes
+ * @property {Readonly<Record<string, readonly number[]>>} tokens
+ */
+/**
+ * @template Request, Context
+ * @typedef {object} ClassifierSpec
+ * @property {string} id
+ * @property {string} summary
+ * @property {Readonly<Record<string, string>>} searchers Class name -> the
+ *   searcher that answers it. A class with no searcher goes to the fallback.
+ * @property {string} fallback The searcher that keeps every other request.
+ * @property {number} floor A searcher takes a request only when its class's
+ *   probability is at least this.
+ * @property {(request: Request, ctx: Context) => readonly string[]} features
+ *   The request's tokens.
+ * @property {(ctx: Context) => ClassifierWeights} weights The shipped weights,
+ *   which the command's adapter put in the context.
+ */
+/**
+ * The helpers, typed for one command's request, context, and answer.
+ * @template Request, Context, Answer
+ * @typedef {object} RouteKit
+ * @property {(node: Omit<Searcher<Request, Context, Answer>, 'kind'>) => Searcher<Request, Context, Answer>} defineSearcher
+ * @property {(node: Omit<Dispatcher<Request, Context>, 'kind'>) => Dispatcher<Request, Context>} defineDispatcher
+ * @property {(spec: ClassifierSpec<Request, Context>) => Dispatcher<Request, Context>} defineClassifier
+ * @property {(root: string, nodes: readonly TreeNode<Request, Context, Answer>[]) => Tree<Request, Context, Answer>} defineTree
+ */
+/**
+ * The probability of each class for these tokens: a softmax over the summed
+ * rows of the tokens the weights know.
+ * @param {ClassifierWeights} weights
+ * @param {readonly string[]} tokens
+ * @returns {number[]}
+ */
+export function classify(weights: ClassifierWeights, tokens: readonly string[]): number[];
+/**
+ * A dispatcher whose route is a static classifier. The most probable class
+ * (the first on a tie) is handed to its searcher; a class with no searcher,
+ * or the fallback's own class, stays with the fallback. Tuning weights for
+ * this node replace its shipped weights.
+ * @template Request, Context
+ * @param {ClassifierSpec<Request, Context>} spec
+ * @returns {Dispatcher<Request, Context>}
+ */
+export function defineClassifier<Request, Context>(spec: ClassifierSpec<Request, Context>): Dispatcher<Request, Context>;
+/**
+ * @template Request, Context, Answer
+ * @param {Omit<Searcher<Request, Context, Answer>, 'kind'>} node
+ * @returns {Searcher<Request, Context, Answer>}
+ */
+export function defineSearcher<Request, Context, Answer>(node: Omit<Searcher<Request, Context, Answer>, "kind">): Searcher<Request, Context, Answer>;
+/**
+ * @template Request, Context
+ * @param {Omit<Dispatcher<Request, Context>, 'kind'>} node
+ * @returns {Dispatcher<Request, Context>}
+ */
+export function defineDispatcher<Request, Context>(node: Omit<Dispatcher<Request, Context>, "kind">): Dispatcher<Request, Context>;
+/**
+ * A tree from its nodes. Throws on a duplicate id, a missing root, child, or
+ * fallback, a fallback that is not a searcher, or a dispatcher cycle.
+ * @template Request, Context, Answer
+ * @param {string} root
+ * @param {readonly TreeNode<Request, Context, Answer>[]} list
+ * @returns {Tree<Request, Context, Answer>}
+ */
+export function defineTree<Request, Context, Answer>(root: string, list: readonly TreeNode<Request, Context, Answer>[]): Tree<Request, Context, Answer>;
+/**
+ * Runs the tree from its root, or from `start` to run one node alone: a
+ * dispatcher below its floor runs its fallback; otherwise the children it
+ * names run in order and the first answer wins; when none answers, the
+ * fallback runs.
+ * @template Request, Context, Answer
+ * @param {Tree<Request, Context, Answer>} tree
+ * @param {Request} request
+ * @param {Context} ctx
+ * @param {{tuning?: Tuning, start?: string}} [options]
+ * @returns {Promise<Answer | null>}
+ */
+export function runTree<Request, Context, Answer>(tree: Tree<Request, Context, Answer>, request: Request, ctx: Context, options?: {
+    tuning?: Tuning;
+    start?: string;
+}): Promise<Answer | null>;
+/**
+ * The helpers in one object, for a tree file to type once (see the file
+ * comment).
+ * @type {RouteKit<any, any, any>}
+ */
+export const routeKit: RouteKit<any, any, any>;
+export type Searcher<Request, Context, Answer> = {
+    kind: "searcher";
+    id: string;
+    /**
+     * One plain line: what it answers.
+     */
+    summary: string;
+    /**
+     *   `weights` is a tuning override for this node, or null for its shipped weights.
+     */
+    run: (request: Request, ctx: Context, weights: unknown) => Answer | null | Promise<Answer | null>;
+};
+export type Route = {
+    /**
+     * The children to try, best first.
+     */
+    ids: readonly string[];
+    /**
+     * From 0 to 1.
+     */
+    confidence: number;
+};
+export type Dispatcher<Request, Context> = {
+    kind: "dispatcher";
+    id: string;
+    summary: string;
+    children: readonly string[];
+    /**
+     * Below this confidence the fallback answers.
+     */
+    floor: number;
+    /**
+     * A searcher's id.
+     */
+    fallback: string;
+    route: (request: Request, ctx: Context, weights: unknown) => Route | Promise<Route>;
+};
+export type TreeNode<Request, Context, Answer> = Searcher<Request, Context, Answer> | Dispatcher<Request, Context>;
+export type Tree<Request, Context, Answer> = {
+    root: string;
+    nodes: ReadonlyMap<string, TreeNode<Request, Context, Answer>>;
+};
+/**
+ * One step the runner took.
+ */
+export type TraceStep = {
+    id: string;
+    kind: "searcher" | "dispatcher";
+    depth: number;
+    /**
+     * Whether this step ran as a fallback.
+     */
+    fallback: boolean;
+    /**
+     * A dispatcher's route.
+     */
+    route?: Route | undefined;
+    /**
+     * Whether a searcher answered.
+     */
+    answered?: boolean | undefined;
+};
+export type Tuning = {
+    /**
+     * Weights by node id, replacing that node's shipped weights for this call.
+     */
+    weights?: Readonly<Record<string, unknown>> | undefined;
+    onTrace?: ((step: TraceStep) => void) | undefined;
+};
+/**
+ * Static classifier weights: one row of numbers per token, one number per
+ * class. A request's score for a class is the sum of its tokens' numbers.
+ */
+export type ClassifierWeights = {
+    classes: readonly string[];
+    tokens: Readonly<Record<string, readonly number[]>>;
+};
+export type ClassifierSpec<Request, Context> = {
+    id: string;
+    summary: string;
+    /**
+     * Class name -> the
+     * searcher that answers it. A class with no searcher goes to the fallback.
+     */
+    searchers: Readonly<Record<string, string>>;
+    /**
+     * The searcher that keeps every other request.
+     */
+    fallback: string;
+    /**
+     * A searcher takes a request only when its class's
+     * probability is at least this.
+     */
+    floor: number;
+    /**
+     *   The request's tokens.
+     */
+    features: (request: Request, ctx: Context) => readonly string[];
+    /**
+     * The shipped weights,
+     * which the command's adapter put in the context.
+     */
+    weights: (ctx: Context) => ClassifierWeights;
+};
+/**
+ * The helpers, typed for one command's request, context, and answer.
+ */
+export type RouteKit<Request, Context, Answer> = {
+    defineSearcher: (node: Omit<Searcher<Request, Context, Answer>, "kind">) => Searcher<Request, Context, Answer>;
+    defineDispatcher: (node: Omit<Dispatcher<Request, Context>, "kind">) => Dispatcher<Request, Context>;
+    defineClassifier: (spec: ClassifierSpec<Request, Context>) => Dispatcher<Request, Context>;
+    defineTree: (root: string, nodes: readonly TreeNode<Request, Context, Answer>[]) => Tree<Request, Context, Answer>;
+};