@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/foundation/response/error-codes.doc.mjs

@@ -277,5 +277,17 @@ export const doc = {
       description:
         'Recorded in the debug log, never printed: the process was ended by a signal (Ctrl-C, SIGTERM) before the command reached a terminal path.',
     },
+
+    // Global mode
+    {
+      value: 'ERR_VERSIONS_UNAVAILABLE',
+      description:
+        'Nothing could answer this run, and nothing was written: the project\'s own CLI could not start and nothing else could answer, or the Core a command needs outside a project could not be installed.',
+    },
+    {
+      value: 'ERR_PROJECT_REQUIRED',
+      description:
+        'The command needs a project (an app with Astryx installed, or an integration package) and was run outside one. Nothing was written.',
+    },
   ],
 };

package/foundation/response/error-codes.mjs

@@ -88,6 +88,8 @@
  *   | 'ERR_LAYOUT_INVALID'
  *   | 'ERR_UNCLASSIFIED_EXIT'
  *   | 'ERR_SIGNAL_TERMINATED'
+ *   | 'ERR_VERSIONS_UNAVAILABLE'
+ *   | 'ERR_PROJECT_REQUIRED'
  * )} ErrorCode
  */
 
@@ -236,6 +238,21 @@ export const ERROR_CODES = Object.freeze({
    * command never reached a terminal path of its own.
    */
   ERR_SIGNAL_TERMINATED: 'ERR_SIGNAL_TERMINATED',
+
+  // ── Global mode (which release answers) ──────────────────────────
+  /**
+   * The CLI release a run needs could not run: the release that matches the
+   * project's Core is not installed and could not be fetched (offline, or the
+   * registry lacks it), the project's own CLI could not be started, or a copy
+   * that carries no Core could not install its release's Core outside a
+   * project. Nothing was written.
+   */
+  ERR_VERSIONS_UNAVAILABLE: 'ERR_VERSIONS_UNAVAILABLE',
+  /**
+   * The command needs a project (an app with Astryx installed, or an
+   * integration package) and was run outside one. Nothing was written.
+   */
+  ERR_PROJECT_REQUIRED: 'ERR_PROJECT_REQUIRED',
 });
 
 /**

package/foundation/response/error-codes.test.mjs

@@ -113,6 +113,7 @@ describe('error codes: shipped set', () => {
     'ERR_NO_SOURCE',
     'ERR_PALETTE_GENERATION',
     'ERR_PATH_TRAVERSAL',
+    'ERR_PROJECT_REQUIRED',
     'ERR_SIGNAL_TERMINATED',
     'ERR_THEME_INVALID',
     'ERR_THEME_LOAD',
@@ -133,6 +134,7 @@ describe('error codes: shipped set', () => {
     'ERR_UNKNOWN_THEME',
     'ERR_UNKNOWN_TOPIC',
     'ERR_VERSION_DETECT',
+    'ERR_VERSIONS_UNAVAILABLE',
     'ERR_WRITE_FAILED',
   ];
 

package/foundation/response/json-contract.test.mjs

@@ -70,13 +70,18 @@ describe('json envelope shape', () => {
     expect(env.apiVersion).toBe(API_VERSION);
     expect(env.type).toBe('docs.list');
     expect(env.data).toEqual([{name: 'Button'}]);
-    expect('meta' in env).toBe(false);
+    // The only meta every result carries names who answered (AST-081 FR5).
+    expect(Object.keys(env.meta)).toEqual(['answeredBy']);
+    const {cli, core, copy} = env.meta.answeredBy;
+    expect(typeof cli).toBe('string');
+    expect(core === null || typeof core === 'string').toBe(true);
+    expect(['project', 'matched', 'carried']).toContain(copy);
   });
 
   it('jsonOut attaches optional meta as a sibling of data', () => {
     jsonOut({type: 'discover.list', data: [], meta: {configured: false}});
     const env = JSON.parse(logs[0]);
-    expect(env.meta).toEqual({configured: false});
+    expect(env.meta).toEqual({configured: false, answeredBy: expect.any(Object)});
     expect(env.data).toEqual([]);
   });
 

package/foundation/response/json.mjs

@@ -30,6 +30,7 @@
  */
 import {ERROR_CODES, isErrorCode} from './error-codes.mjs';
 import {recordEnvelope, setOutcome} from '../debug/index.mjs';
+import {answeredBy} from '../release/run-context.mjs';
 
 export const API_VERSION = 1;
 
@@ -101,7 +102,9 @@ export function jsonOut(response) {
   const envelope = {apiVersion: API_VERSION, type: response.type};
   if (response.package !== undefined) envelope.package = response.package;
   envelope.data = response.data;
-  if (response.meta !== undefined) envelope.meta = response.meta;
+  // Every successful result names the release that answered (spec AST-081
+  // FR5): the CLI, the Core it paired with, and which copy it was.
+  envelope.meta = {...(response.meta ?? {}), answeredBy: answeredBy()};
   // Serialize BEFORE marking handled. If JSON.stringify throws (a circular
   // reference or a BigInt in `data` — an author bug in a command's return
   // value), the `__xdsJsonHandled` flag must stay unset so the bin error

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

@@ -32,6 +32,11 @@ export const doc = {
       description:
         'The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.',
     },
+    {
+      value: 'init.user',
+      description:
+        'The computer-level agent text receipt — returned when --user is set: `data.files`, one `{path, action, reason?}` per path acted on, the skill file first and then each link to its folder (action `written` | `linked` | `unchanged` | `removed` | `absent` | `kept`; `reason` only on `kept`: `edited` when a person changed the text, `not-astryx` when Astryx did not write it), `data.command` (the command the text names), and `data.warnings`.',
+    },
     // component
     {
       value: 'component.list',
@@ -112,7 +117,7 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
@@ -139,7 +144,7 @@ export const doc = {
     {
       value: 'search',
       description:
-        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates).',
+        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why.',
     },
 
     // build
@@ -169,12 +174,13 @@ export const doc = {
     // gap reports
     {
       value: 'gap-report.categories',
-      description: 'The fixed gap category values and human-readable labels.',
+      description:
+        'The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person.',
     },
     {
       value: 'gap-report.file',
       description:
-        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
+        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories.',
     },
 
     // template
@@ -283,19 +289,19 @@ export const doc = {
     {
       value: 'upgrade.status',
       description:
-        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.',
+        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version.',
     },
     {
       value: 'upgrade.run',
       description:
-        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.',
+        'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.',
     },
 
     // manifest
     {
       value: 'manifest',
       description:
-        'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
+        "The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), and the flat responseTypes index.",
     },
 
     // help and version, which no single command owns
@@ -327,12 +333,12 @@ export const doc = {
     {
       value: 'integration.pack-check',
       description:
-        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
+        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message, fix?, file?, line?}] (the issues validation finds in the source and, prefixed packed_, in the packed tree, with the fix and the place when the check knows them).',
     },
     {
       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}.',
+        '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 cli_peer_version when the running CLI is outside the @astryxdesign/cli peer range of the package, 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. A runner_command note lists each Astryx command a topic writes with a package runner (its file, line and the bare command to write). 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). Since 0.7.3 each import apps cannot use is also a note (its fix in the message), listed only and failing --strict from the next minor. publicImports ({status: checked, findings: [], unchecked}) lists each import the check could not judge as {file, specifier, reason}; never counted or failed on.',
     },
     {
       value: 'integration.template-conflicts',
@@ -342,12 +348,17 @@ export const doc = {
     {
       value: 'integration.component-conflicts',
       description:
-        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked | skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings; a default_mismatch carries docDefault, codeDefault, and a fix), unchecked, typesNotCompared, and propsNotChecked.',
     },
     {
       value: 'integration.doc-conflicts',
       description:
-        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
+        'validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`). copiedPassages lists each pair of topics that repeat 10 or more words of prose word for word: topic, section, otherTopic, otherOwner (package | core), words, passages, owner (the topic that should keep the text), text (the passage as the topic writes it), line (where the copy starts in the topic to change, or null), and message (the exact replacement); each is also a copied_passage warning in issues. fluff lists padding phrases and low-density topics: topic, kind (phrase | density), phrase, section, file (relative to the package root), line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. strayPointers lists each code span that is exactly `astryx docs <name>` for a doc that exists, in the prose, description or summary of a topic or the text fields of a component doc: topic (the topic or component doc), kind (topic | component), section, field (the field outside any section, such as description or usage.bestPractices[0].description, else null), file (relative to the package root), line, pointer (the written command), link (the {@link} that replaces it), and message; each is also a stray_doc_pointer warning in issues.',
+    },
+    {
+      value: 'integration.check',
+      description:
+        'Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.',
     },
   ],
 };

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

@@ -12,6 +12,7 @@ import * as path from 'node:path';
 import {describe, it, expect} from 'vitest';
 import {doc} from './response-types.doc.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
+import {linkThisCliAsProjectCli} from '../../test-utils/release-fixtures.mjs';
 
 /** @param {string} type */
 const describedAs = type =>
@@ -112,6 +113,51 @@ describe('response-types EnumDoc names every field', () => {
     );
   });
 
+  it('search, including meta.partial when Core cannot be obtained', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rt-partial-'));
+    // The project's own CLI answers and no Core is installed: an open search
+    // answers from docs and themes and says what it skipped.
+    linkThisCliAsProjectCli(empty);
+    try {
+      const res = await data(['search', 'button'], empty);
+      expect(res.meta.partial).toBeDefined();
+      expectNamed('search', ['meta', 'partial', ...fieldsOf(res.meta.partial)]);
+      for (const domain of res.meta.partial.skipped) {
+        expectNamed('search', [domain]);
+      }
+    } finally {
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+  });
+
+  it('init.user: every row field, action, and kept reason the receipt type declares', () => {
+    const types = fs.readFileSync(
+      new URL('../../api/init/init.type.mjs', import.meta.url),
+      'utf8',
+    );
+    /** The quoted members of the union a typedef or property declares. */
+    const union = (/** @type {RegExp} */ re) =>
+      [...(types.match(re)?.[1] ?? '').matchAll(/'([^']+)'/gu)].map(m => m[1]);
+    const actions = union(/@typedef \{([^}]*)\} InitUserAction/u);
+    const reasons = union(/@property \{([^}]*)\} \[reason\]/u);
+    expect(actions).toContain('linked');
+    expect(reasons.length).toBeGreaterThan(0);
+    const rowFields = [
+      ...types
+        .split('@typedef {object} InitUserFile')[1]
+        .split('*/')[0]
+        .matchAll(/@property \{[^}]*\} \[?(\w+)/gu),
+    ].map(m => m[1]);
+    expectNamed('init.user', [
+      'files',
+      'command',
+      'warnings',
+      ...rowFields,
+      ...actions,
+      ...reasons,
+    ]);
+  });
+
   it('build.kit, including the hint a thin kit carries', async () => {
     const res = await data(['build', 'zzqx-nothing-matches']);
     expect(res.type).toBe('build.kit');

package/foundation/response/response.doc.mjs

@@ -21,11 +21,11 @@ export const doc = {
   fields: [
     {
       name: 'Success envelope',
-      type: '{ apiVersion: number; type: string; package?: string; data: unknown; meta?: Record<string, unknown> }',
+      type: '{ apiVersion: number; type: string; package?: string; data: unknown; meta?: { answeredBy?: { cli: string; core: string | null; copy: "project" | "starting" | "matched" | "carried" | "fallback" } } & Record<string, unknown> }',
       description:
         'Emitted for every successful command in --json mode: a type ' +
         'discriminator, the package that owns what the response is about, ' +
-        'its data payload, and an optional meta sidecar.',
+        'its data payload, and an optional meta object beside data.',
       fields: [
         {
           name: 'apiVersion',
@@ -65,7 +65,7 @@ export const doc = {
           name: 'meta',
           type: 'Record<string, unknown>',
           description:
-            'Optional sidecar, emitted as a sibling of data (never merged in). A `deprecations` field is an array of `{id, replacements}` entries; each stable lifecycle id names the replacement commands without changing the command data.',
+            "Optional, emitted as a sibling of data (never merged in). `answeredBy` is on every successful result of a release that has it: `{cli, core, copy}`, the answering CLI version, the Core it pairs with (or null), and which copy answered: `project` (the project's own CLI), `starting` (the copy that started the run, in a project with no CLI of its own), `matched` (the release equal to the project's Core, when the project's own CLI cannot start), `carried` (outside a project), or `fallback` (the matched release could not be obtained, so the starting copy answered). A `deprecations` field is an array of `{id, replacements}` entries; each stable lifecycle id names the replacement commands without changing the command data. Other fields may be added (spec:AST-017 FR13).",
         },
       ],
     },

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>;
+};