@fgv/ts-extras 5.1.0-55 → 5.1.0-57

package/lib/packlets/mustache/mustacheTemplate.js.map

@@ -1 +1 @@
-{"version":3,"file":"mustacheTemplate.js","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport Mustache, { EscapeFunction, TemplateSpans, Writer } from 'mustache';\n\nimport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IRequiredMustacheTemplateOptions,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType\n} from './interfaces';\n\n/**\n * Default options for MustacheTemplate\n */\nconst DEFAULT_OPTIONS: IRequiredMustacheTemplateOptions = {\n  tags: ['{{', '}}'],\n  includeComments: false,\n  includePartials: false,\n  escape: 'html'\n};\n\n/**\n * HTML entity map matching mustache.js's internal `escapeHtml`. Held\n * locally so the `'html'` escape strategy does not depend on the global\n * `Mustache.escape` (which other packlets — notably `experimental` —\n * mutate at module load and which mustache.js itself defines as\n * mutable). Per-instance escape avoids that shared-state coupling.\n */\nconst HTML_ENTITY_MAP: Readonly<Record<string, string>> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n  '/': '&#x2F;',\n  '`': '&#x60;',\n  '=': '&#x3D;'\n};\n\nconst HTML_ESCAPE: EscapeFunction = (value) =>\n  String(value).replace(/[&<>\"'`=/]/g, (ch) => HTML_ENTITY_MAP[ch]);\n\nconst PASSTHROUGH_ESCAPE: EscapeFunction = (value) => String(value);\n\n/**\n * Resolves a {@link MustacheEscapeStrategy} into the per-render\n * `escape` function understood by `Mustache.Writer.render`. The\n * resolved function is always non-`undefined` so the writer never\n * consults the (mutable, process-global) `Mustache.escape`.\n */\nfunction _resolveEscapeFunction(strategy: MustacheEscapeStrategy): EscapeFunction {\n  if (strategy === 'html') {\n    return HTML_ESCAPE;\n  }\n  if (strategy === 'none') {\n    return PASSTHROUGH_ESCAPE;\n  }\n  return (value) => strategy(String(value));\n}\n\n/**\n * A helper class for working with Mustache templates that provides\n * validation, variable extraction, and context validation utilities.\n * @public\n */\nexport class MustacheTemplate {\n  /**\n   * The original template string\n   */\n  public readonly template: string;\n\n  /**\n   * The options used for parsing this template\n   */\n  public readonly options: Readonly<IRequiredMustacheTemplateOptions>;\n\n  private readonly _tokens: TemplateSpans;\n  private readonly _writer: Writer;\n  private readonly _escapeFn: EscapeFunction;\n  private _variables?: readonly IVariableRef[];\n\n  private constructor(template: string, tokens: TemplateSpans, options: IRequiredMustacheTemplateOptions) {\n    this.template = template;\n    this._tokens = tokens;\n    this.options = options;\n    this._writer = new Mustache.Writer();\n    this._escapeFn = _resolveEscapeFunction(options.escape);\n  }\n\n  /**\n   * Creates a new MustacheTemplate instance.\n   * @param template - The Mustache template string to parse\n   * @param options - Optional parsing options\n   * @returns Success with the template instance, or Failure if parsing fails\n   */\n  public static create(template: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess((tokens) => {\n      return succeed(new MustacheTemplate(template, tokens, resolvedOptions));\n    });\n  }\n\n  /**\n   * Validates that a template string has valid Mustache syntax.\n   * @param template - The template string to validate\n   * @param options - Optional parsing options\n   * @returns Success with true if valid, or Failure with a descriptive error message\n   */\n  public static validate(template: string, options?: IMustacheTemplateOptions): Result<true> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess(() => succeed(true as const));\n  }\n\n  /**\n   * Checks if this template instance has valid syntax.\n   * Always returns Success(true) since parsing succeeded in create().\n   * @returns Success with true\n   */\n  public validate(): Result<true> {\n    return succeed(true as const);\n  }\n\n  /**\n   * Extracts all variable references from the template.\n   * @returns An array of variable references found in the template\n   */\n  public extractVariables(): readonly IVariableRef[] {\n    if (this._variables === undefined) {\n      this._variables = this._extractVariablesFromTokens(this._tokens);\n    }\n    return this._variables;\n  }\n\n  /**\n   * Extracts unique variable names from the template.\n   * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])\n   */\n  public extractVariableNames(): readonly string[] {\n    const variables = this.extractVariables();\n    const seen = new Set<string>();\n    const names: string[] = [];\n\n    for (const variable of variables) {\n      if (!seen.has(variable.name)) {\n        seen.add(variable.name);\n        names.push(variable.name);\n      }\n    }\n\n    return names;\n  }\n\n  /**\n   * Validates that a context object has all required variables.\n   * @param context - The context object to validate\n   * @returns Success with validation result containing details about present/missing variables\n   */\n  public validateContext(context: unknown): Result<IContextValidationResult> {\n    const variables = this.extractVariables();\n    const presentVariables: string[] = [];\n    const missingVariables: string[] = [];\n    const missingDetails: IMissingVariableDetail[] = [];\n    const checked = new Set<string>();\n\n    for (const variable of variables) {\n      if (checked.has(variable.name)) {\n        continue;\n      }\n      checked.add(variable.name);\n\n      const lookup = this._lookupPath(context, variable.path);\n\n      if (lookup.found) {\n        presentVariables.push(variable.name);\n      } else {\n        missingVariables.push(variable.name);\n        missingDetails.push({\n          variable,\n          failedAtSegment: lookup.failedAt,\n          existingPath: lookup.existingPath\n        });\n      }\n    }\n\n    return succeed({\n      isValid: missingVariables.length === 0,\n      presentVariables,\n      missingVariables,\n      missingDetails\n    });\n  }\n\n  /**\n   * Renders the template with the given context.\n   * Use this for pre-validated contexts where you've already checked\n   * that all required variables are present.\n   * @param context - The context object for template rendering\n   * @returns Success with the rendered string, or Failure if rendering fails\n   */\n  public render(context: unknown): Result<string> {\n    return captureResult(() =>\n      this._writer.render(this.template, context, undefined, { escape: this._escapeFn })\n    );\n  }\n\n  /**\n   * Validates the context and renders the template if validation passes.\n   * @param context - The context object to validate and render with\n   * @returns Success with the rendered string, or Failure with validation or render errors\n   */\n  public validateAndRender(context: unknown): Result<string> {\n    return this.validateContext(context).onSuccess((validation) => {\n      if (!validation.isValid) {\n        const missing = validation.missingVariables.join(', ');\n        return fail(`Missing required variables: ${missing}`);\n      }\n      return this.render(context);\n    });\n  }\n\n  private static _resolveOptions(options?: IMustacheTemplateOptions): IRequiredMustacheTemplateOptions {\n    if (options === undefined) {\n      return DEFAULT_OPTIONS;\n    }\n\n    return {\n      tags: options.tags ? [options.tags[0], options.tags[1]] : DEFAULT_OPTIONS.tags,\n      includeComments: options.includeComments ?? DEFAULT_OPTIONS.includeComments,\n      includePartials: options.includePartials ?? DEFAULT_OPTIONS.includePartials,\n      escape: options.escape ?? DEFAULT_OPTIONS.escape\n    };\n  }\n\n  private static _parseTokens(\n    template: string,\n    options: IRequiredMustacheTemplateOptions\n  ): Result<TemplateSpans> {\n    return captureResult(() => Mustache.parse(template, options.tags));\n  }\n\n  private _extractVariablesFromTokens(tokens: TemplateSpans): IVariableRef[] {\n    const variables: IVariableRef[] = [];\n\n    for (const token of tokens) {\n      const type = token[0] as MustacheTokenType;\n      const value = token[1] as string;\n\n      // Skip text tokens\n      if (type === 'text') {\n        continue;\n      }\n\n      // Handle comments based on options\n      if (type === '!' && !this.options.includeComments) {\n        continue;\n      }\n\n      // Handle partials based on options\n      if (type === '>' && !this.options.includePartials) {\n        continue;\n      }\n\n      // Handle variable tokens: 'name', '&', '#', '^', and optionally '!', '>'\n      if (type === 'name' || type === '&' || type === '#' || type === '^' || type === '!' || type === '>') {\n        const isSection = type === '#' || type === '^';\n        variables.push({\n          name: value,\n          path: this._parsePath(value),\n          tokenType: type,\n          isSection\n        });\n      }\n\n      // Recursively extract from nested tokens in sections\n      if ((type === '#' || type === '^') && token.length > 4) {\n        const nestedTokens = token[4] as TemplateSpans;\n        if (nestedTokens) {\n          variables.push(...this._extractVariablesFromTokens(nestedTokens));\n        }\n      }\n    }\n\n    return variables;\n  }\n\n  private _parsePath(name: string): readonly string[] {\n    // Handle special case of '.' which means current context\n    if (name === '.') {\n      return ['.'];\n    }\n\n    // Split on dots to get path segments\n    return name.split('.').filter((segment) => segment.length > 0);\n  }\n\n  private _lookupPath(\n    context: unknown,\n    path: readonly string[]\n  ): { found: boolean; existingPath: string[]; failedAt?: string } {\n    // Handle '.' which always exists if context is not null/undefined\n    if (path.length === 1 && path[0] === '.') {\n      return { found: context !== undefined && context !== null, existingPath: [] };\n    }\n\n    let current: unknown = context;\n    const existingPath: string[] = [];\n\n    for (const segment of path) {\n      if (current === undefined || current === null) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      if (typeof current !== 'object') {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      const obj = current as Record<string, unknown>;\n      if (!(segment in obj)) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      current = obj[segment];\n      existingPath.push(segment);\n    }\n\n    return { found: true, existingPath };\n  }\n}\n"]}
+{"version":3,"file":"mustacheTemplate.js","sourceRoot":"","sources":["../../../src/packlets/mustache/mustacheTemplate.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, captureResult, fail, succeed } from '@fgv/ts-utils';\nimport Mustache, { Context, EscapeFunction, TemplateSpans, Writer } from 'mustache';\n\nimport {\n  IContextValidationResult,\n  IMissingVariableDetail,\n  IMustacheTemplateOptions,\n  IRequiredMustacheTemplateOptions,\n  IVariableRef,\n  MustacheEscapeStrategy,\n  MustacheTokenType,\n  IRenderedSegment,\n  IRenderedTemplate\n} from './interfaces';\n\n/**\n * Default options for MustacheTemplate\n */\nconst DEFAULT_OPTIONS: IRequiredMustacheTemplateOptions = {\n  tags: ['{{', '}}'],\n  includeComments: false,\n  includePartials: false,\n  escape: 'html'\n};\n\n/**\n * HTML entity map matching mustache.js's internal `escapeHtml`. Held\n * locally so the `'html'` escape strategy does not depend on the global\n * `Mustache.escape` (which other packlets — notably `experimental` —\n * mutate at module load and which mustache.js itself defines as\n * mutable). Per-instance escape avoids that shared-state coupling.\n */\nconst HTML_ENTITY_MAP: Readonly<Record<string, string>> = {\n  '&': '&amp;',\n  '<': '&lt;',\n  '>': '&gt;',\n  '\"': '&quot;',\n  \"'\": '&#39;',\n  '/': '&#x2F;',\n  '`': '&#x60;',\n  '=': '&#x3D;'\n};\n\nconst HTML_ESCAPE: EscapeFunction = (value) =>\n  String(value).replace(/[&<>\"'`=/]/g, (ch) => HTML_ENTITY_MAP[ch]);\n\nconst PASSTHROUGH_ESCAPE: EscapeFunction = (value) => String(value);\n\n/**\n * Resolves a {@link MustacheEscapeStrategy} into the per-render\n * `escape` function understood by `Mustache.Writer.render`. The\n * resolved function is always non-`undefined` so the writer never\n * consults the (mutable, process-global) `Mustache.escape`.\n */\nfunction _resolveEscapeFunction(strategy: MustacheEscapeStrategy): EscapeFunction {\n  if (strategy === 'html') {\n    return HTML_ESCAPE;\n  }\n  if (strategy === 'none') {\n    return PASSTHROUGH_ESCAPE;\n  }\n  return (value) => strategy(String(value));\n}\n\n/**\n * A helper class for working with Mustache templates that provides\n * validation, variable extraction, and context validation utilities.\n * @public\n */\nexport class MustacheTemplate {\n  /**\n   * The original template string\n   */\n  public readonly template: string;\n\n  /**\n   * The options used for parsing this template\n   */\n  public readonly options: Readonly<IRequiredMustacheTemplateOptions>;\n\n  private readonly _tokens: TemplateSpans;\n  private readonly _writer: Writer;\n  private readonly _escapeFn: EscapeFunction;\n  private _variables?: readonly IVariableRef[];\n\n  private constructor(template: string, tokens: TemplateSpans, options: IRequiredMustacheTemplateOptions) {\n    this.template = template;\n    this._tokens = tokens;\n    this.options = options;\n    this._writer = new Mustache.Writer();\n    this._escapeFn = _resolveEscapeFunction(options.escape);\n  }\n\n  /**\n   * Creates a new MustacheTemplate instance.\n   * @param template - The Mustache template string to parse\n   * @param options - Optional parsing options\n   * @returns Success with the template instance, or Failure if parsing fails\n   */\n  public static create(template: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess((tokens) => {\n      return succeed(new MustacheTemplate(template, tokens, resolvedOptions));\n    });\n  }\n\n  /**\n   * Validates that a template string has valid Mustache syntax.\n   * @param template - The template string to validate\n   * @param options - Optional parsing options\n   * @returns Success with true if valid, or Failure with a descriptive error message\n   */\n  public static validate(template: string, options?: IMustacheTemplateOptions): Result<true> {\n    const resolvedOptions = MustacheTemplate._resolveOptions(options);\n    return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess(() => succeed(true as const));\n  }\n\n  /**\n   * Checks if this template instance has valid syntax.\n   * Always returns Success(true) since parsing succeeded in create().\n   * @returns Success with true\n   */\n  public validate(): Result<true> {\n    return succeed(true as const);\n  }\n\n  /**\n   * Extracts all variable references from the template.\n   * @returns An array of variable references found in the template\n   */\n  public extractVariables(): readonly IVariableRef[] {\n    if (this._variables === undefined) {\n      this._variables = this._extractVariablesFromTokens(this._tokens);\n    }\n    return this._variables;\n  }\n\n  /**\n   * Extracts unique variable names from the template.\n   * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])\n   */\n  public extractVariableNames(): readonly string[] {\n    const variables = this.extractVariables();\n    const seen = new Set<string>();\n    const names: string[] = [];\n\n    for (const variable of variables) {\n      if (!seen.has(variable.name)) {\n        seen.add(variable.name);\n        names.push(variable.name);\n      }\n    }\n\n    return names;\n  }\n\n  /**\n   * Validates that a context object has all required variables.\n   * @param context - The context object to validate\n   * @returns Success with validation result containing details about present/missing variables\n   */\n  public validateContext(context: unknown): Result<IContextValidationResult> {\n    const variables = this.extractVariables();\n    const presentVariables: string[] = [];\n    const missingVariables: string[] = [];\n    const missingDetails: IMissingVariableDetail[] = [];\n    const checked = new Set<string>();\n\n    for (const variable of variables) {\n      if (checked.has(variable.name)) {\n        continue;\n      }\n      checked.add(variable.name);\n\n      const lookup = this._lookupPath(context, variable.path);\n\n      if (lookup.found) {\n        presentVariables.push(variable.name);\n      } else {\n        missingVariables.push(variable.name);\n        missingDetails.push({\n          variable,\n          failedAtSegment: lookup.failedAt,\n          existingPath: lookup.existingPath\n        });\n      }\n    }\n\n    return succeed({\n      isValid: missingVariables.length === 0,\n      presentVariables,\n      missingVariables,\n      missingDetails\n    });\n  }\n\n  /**\n   * Renders the template with the given context.\n   * Use this for pre-validated contexts where you've already checked\n   * that all required variables are present.\n   * @param context - The context object for template rendering\n   * @returns Success with the rendered string, or Failure if rendering fails\n   */\n  public render(context: unknown): Result<string> {\n    return captureResult(() =>\n      this._writer.render(this.template, context, undefined, { escape: this._escapeFn })\n    );\n  }\n\n  /**\n   * Renders the template and reports which part of the output came from where.\n   *\n   * @remarks\n   * The rendered `text` is identical to `render`'s. What is added is\n   * `segments`: a document-ordered, contiguous, gapless attribution of every code unit to either\n   * template literal text or a named interpolation. It answers \"what is in this output, in what\n   * order, and how much of it is each part\" — a prompt's composition, a generated document's\n   * section sizes, a diff-free view of where a template's bulk actually goes.\n   *\n   * **Offsets are computed during the render, never recovered afterwards.** Recovering them by\n   * searching the output for each substituted value is the obvious shortcut and it is unsound: a\n   * value can occur more than once, can render empty, can be a substring of the surrounding\n   * literal text, and can be altered by escaping between input and output. That failure is silent\n   * and produces plausible offsets, which is the worst property a diagnostic can have.\n   *\n   * **Sections, inverted sections and partials are refused, not approximated.** Their rendered\n   * output is not a linear image of the token order — a section may repeat its body, or omit it —\n   * so a segment list walked from the template would mis-describe the result. Failing names the\n   * construct. Comments and set-delimiter tags emit nothing and are skipped; because each\n   * interpolation is rendered from its already-parsed token rather than from a re-parsed slice of\n   * the template, a set-delimiter tag has no effect on what this produces.\n   *\n   * **Every context value is evaluated exactly once, as `render()` evaluates it.** A lambda in the\n   * context is therefore invoked the same number of times either way, and a context whose lambda\n   * answers differently per call is rendered rather than rejected — the returned `segments` always\n   * describe the returned `text`, whatever that text was. (The concatenation identity is asserted\n   * across every shape in this package's test suite, not re-checked at runtime: re-checking means\n   * a second full render, which is precisely what would double those invocations.)\n   *\n   * @param context - The context object for template rendering.\n   * @returns Success with the rendered text and its segment map, or Failure if the\n   * template contains a construct this cannot describe\n   */\n  public renderWithSegments(context: unknown): Result<IRenderedTemplate> {\n    return captureResult((): IRenderedTemplate => {\n      const segments: IRenderedSegment[] = [];\n      const lookup = new Mustache.Context(context);\n      let text = '';\n\n      for (const token of this._tokens) {\n        const type = token[0] as MustacheTokenType;\n        if (type === '!' || type === '=') {\n          continue; // emits nothing\n        }\n        if (type !== 'text' && type !== 'name' && type !== '&') {\n          throw new Error(\n            `renderWithSegments does not support '${type}' tokens (sections, inverted sections ` +\n              `and partials render non-linearly, so a segment map walked from the template would ` +\n              `misdescribe the output). Use render() for this template.`\n          );\n        }\n\n        const rendered =\n          type === 'text' ? String(token[1]) : this._renderInterpolation(type, String(token[1]), lookup);\n\n        segments.push({\n          kind: type === 'text' ? 'literal' : 'substitution',\n          ...(type === 'text' ? {} : { name: String(token[1]) }),\n          start: text.length,\n          length: rendered.length,\n          escaped: type === 'name'\n        });\n        text += rendered;\n      }\n\n      // Deliberately NOT re-rendered and compared against render() here. Such a check did once\n      // catch a real defect, but paying for it means a second full render — which invokes every\n      // lambda in the context a second time, so the check both doubles a caller's side effects\n      // and turns a context whose lambda answers differently per call into a failure on a\n      // template that renders fine. The identity is asserted in the test suite instead, where a\n      // second render costs nobody anything.\n      return { text, segments };\n    });\n  }\n\n  /**\n   * Renders one interpolation token against a prepared lookup context.\n   *\n   * @remarks\n   * Delegates to the same `Writer` primitives `render()` reaches through `renderTokens`, so the\n   * value semantics — dotted paths, lambdas, `null` and `undefined` rendering empty, non-string\n   * coercion — are mustache.js's rather than a reimplementation of them.\n   *\n   * The token is passed as a freshly built `[type, name]` array rather than the parsed span. Both\n   * primitives read only the name, and `@types/mustache` declares the parameter as `string[]`\n   * while a parsed span carries its source offsets as numbers — so handing over the span would\n   * need a cast to work around the typings. Building the pair the primitives actually read needs\n   * none.\n   *\n   * @param type - `'name'` for an escaped interpolation, `'&'` for an unescaped one.\n   * @param name - The interpolation's name (may be a dotted path).\n   * @param lookup - The context to resolve the name against.\n   * @returns The rendered value; empty when the name resolves to `null` or `undefined`.\n   */\n  private _renderInterpolation(type: 'name' | '&', name: string, lookup: Context): string {\n    const token: string[] = [type, name];\n    const value =\n      type === 'name'\n        ? this._writer.escapedValue(token, lookup, { escape: this._escapeFn })\n        : this._writer.unescapedValue(token, lookup);\n    // Both primitives guard with `if (value != null)` and so return `undefined` — never `null` —\n    // for an absent value, which is why only `undefined` is tested here. `renderTokens` appends\n    // nothing in that case and string-coerces everything else.\n    return value === undefined ? '' : String(value);\n  }\n\n  /**\n   * Validates the context and renders the template if validation passes.\n   * @param context - The context object to validate and render with\n   * @returns Success with the rendered string, or Failure with validation or render errors\n   */\n  public validateAndRender(context: unknown): Result<string> {\n    return this.validateContext(context).onSuccess((validation) => {\n      if (!validation.isValid) {\n        const missing = validation.missingVariables.join(', ');\n        return fail(`Missing required variables: ${missing}`);\n      }\n      return this.render(context);\n    });\n  }\n\n  private static _resolveOptions(options?: IMustacheTemplateOptions): IRequiredMustacheTemplateOptions {\n    if (options === undefined) {\n      return DEFAULT_OPTIONS;\n    }\n\n    return {\n      tags: options.tags ? [options.tags[0], options.tags[1]] : DEFAULT_OPTIONS.tags,\n      includeComments: options.includeComments ?? DEFAULT_OPTIONS.includeComments,\n      includePartials: options.includePartials ?? DEFAULT_OPTIONS.includePartials,\n      escape: options.escape ?? DEFAULT_OPTIONS.escape\n    };\n  }\n\n  private static _parseTokens(\n    template: string,\n    options: IRequiredMustacheTemplateOptions\n  ): Result<TemplateSpans> {\n    return captureResult(() => Mustache.parse(template, options.tags));\n  }\n\n  private _extractVariablesFromTokens(tokens: TemplateSpans): IVariableRef[] {\n    const variables: IVariableRef[] = [];\n\n    for (const token of tokens) {\n      const type = token[0] as MustacheTokenType;\n      const value = token[1] as string;\n\n      // Skip text tokens\n      if (type === 'text') {\n        continue;\n      }\n\n      // Handle comments based on options\n      if (type === '!' && !this.options.includeComments) {\n        continue;\n      }\n\n      // Handle partials based on options\n      if (type === '>' && !this.options.includePartials) {\n        continue;\n      }\n\n      // Handle variable tokens: 'name', '&', '#', '^', and optionally '!', '>'\n      if (type === 'name' || type === '&' || type === '#' || type === '^' || type === '!' || type === '>') {\n        const isSection = type === '#' || type === '^';\n        variables.push({\n          name: value,\n          path: this._parsePath(value),\n          tokenType: type,\n          isSection\n        });\n      }\n\n      // Recursively extract from nested tokens in sections\n      if ((type === '#' || type === '^') && token.length > 4) {\n        const nestedTokens = token[4] as TemplateSpans;\n        if (nestedTokens) {\n          variables.push(...this._extractVariablesFromTokens(nestedTokens));\n        }\n      }\n    }\n\n    return variables;\n  }\n\n  private _parsePath(name: string): readonly string[] {\n    // Handle special case of '.' which means current context\n    if (name === '.') {\n      return ['.'];\n    }\n\n    // Split on dots to get path segments\n    return name.split('.').filter((segment) => segment.length > 0);\n  }\n\n  private _lookupPath(\n    context: unknown,\n    path: readonly string[]\n  ): { found: boolean; existingPath: string[]; failedAt?: string } {\n    // Handle '.' which always exists if context is not null/undefined\n    if (path.length === 1 && path[0] === '.') {\n      return { found: context !== undefined && context !== null, existingPath: [] };\n    }\n\n    let current: unknown = context;\n    const existingPath: string[] = [];\n\n    for (const segment of path) {\n      if (current === undefined || current === null) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      if (typeof current !== 'object') {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      const obj = current as Record<string, unknown>;\n      if (!(segment in obj)) {\n        return { found: false, existingPath, failedAt: segment };\n      }\n\n      current = obj[segment];\n      existingPath.push(segment);\n    }\n\n    return { found: true, existingPath };\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-55",
+  "version": "5.1.0-57",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -69,10 +69,10 @@
   },
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-extras#ts-utils",
   "devDependencies": {
-    "@jest/expect-utils": "^29.7.0",
+    "@jest/expect-utils": "^30.5.2",
     "@microsoft/api-documenter": "^7.28.2",
     "@microsoft/api-extractor": "^7.55.2",
-    "@types/jest": "^29.5.14",
+    "@types/jest": "^30.0.0",
     "@types/mustache": "^4.2.5",
     "@types/node": "^20.14.9",
     "@types/papaparse": "^5.3.14",
@@ -82,28 +82,28 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^7.2.1",
-    "jest": "^29.7.0",
+    "jest": "^30.5.2",
     "jest-extended": "^4.0.2",
-    "jest-matcher-utils": "^29.7.0",
+    "jest-matcher-utils": "^30.5.2",
     "rimraf": "^6.1.2",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.12",
     "ts-node": "^10.9.2",
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
-    "jest-snapshot": "~29.7.0",
-    "@rushstack/heft": "1.2.7",
-    "@rushstack/heft-node-rig": "2.11.27",
+    "jest-snapshot": "~30.5.2",
+    "@rushstack/heft": "1.3.0",
+    "@rushstack/heft-node-rig": "2.11.50",
     "@rushstack/eslint-config": "4.6.4",
     "@types/heft-jest": "1.0.6",
-    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@rushstack/heft-jest-plugin": "2.0.17",
     "eslint-plugin-tsdoc": "~0.5.2",
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-55",
-    "@fgv/typedoc-compact-theme": "5.1.0-55",
-    "@fgv/ts-utils-jest": "5.1.0-55",
-    "@fgv/ts-utils": "5.1.0-55"
+    "@fgv/heft-dual-rig": "5.1.0-57",
+    "@fgv/typedoc-compact-theme": "5.1.0-57",
+    "@fgv/ts-utils-jest": "5.1.0-57",
+    "@fgv/ts-utils": "5.1.0-57"
   },
   "dependencies": {
     "@types/luxon": "^3.7.1",
@@ -112,10 +112,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-55"
+    "@fgv/ts-json-base": "5.1.0-57"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-55"
+    "@fgv/ts-utils": "5.1.0-57"
   },
   "repository": {
     "type": "git",

package/perf/promptCacheAnthropicBreakpoint.js

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ *
+ * A/B for whether C3's Anthropic prompt-cache breakpoint emission (IAiCacheRequest.systemBreakpoints
+ * -> `cache_control`) actually produces a cache hit against a live provider.
+ *
+ * Every prompt-cache measurement shipped by this stream so far (promptCacheObservability.js,
+ * promptCacheRoutingAb.js) ran against xAI, whose caching is automatic — no directive is sent, so
+ * neither harness exercises C3's emit path at all. Anthropic is the sharp case: its cache is
+ * EXPLICIT OPT-IN PER CONTENT BLOCK. There is no automatic path, so a breakpoint is the only thing
+ * that can produce a hit. If C3's Anthropic emission is wrong, nothing else in the repo would show
+ * it — this is the first live exercise of that code path.
+ *
+ *   ANTHROPIC_API_KEY=... node perf/promptCacheAnthropicBreakpoint.js
+ *   SALT=run2 ANTHROPIC_API_KEY=... node perf/promptCacheAnthropicBreakpoint.js   # see "traps" below
+ *
+ * Requires a built lib/ (`rushx build` first). Deliberately NOT a jest test: live traffic and a
+ * bill do not belong behind CI's green (TESTING_GUIDELINES.md § Measurement Harnesses).
+ *
+ * The prefix builder, the ratio arithmetic, and the CONFIRMS/MISSES/AMBIGUOUS/inconclusive verdict
+ * below all live in `src/packlets/ai-assist/promptCacheAnthropicBreakpointHarness.ts`, reusing
+ * `promptCacheUsageMath.ts`'s shared comparison rather than re-deriving it, and unit-tested against
+ * fixture usage blocks in `src/test/unit/ai-assist/promptCacheAnthropicBreakpointHarness.test.ts` —
+ * this file is a thin wrapper that supplies the live network transport and prints the result.
+ *
+ * ---------------------------------------------------------------------------
+ * TARGET MODEL AND FIXTURE SIZING
+ *
+ * Target: `claude-sonnet-5` — this provider's default `'base'` tier (registry.ts), the same tier
+ * this stream's other harnesses default to. design.md §7's verified-minimum table gives Sonnet-class
+ * models (including claude-sonnet-5) a 1,024-token minimum cacheable prefix. Anthropic's minimum is
+ * non-monotonic across the model family (Haiku-class models need 4,096), so this harness's fixture
+ * is sized well above BOTH floors rather than just the one this model needs: the 400-line generator
+ * this file shares with promptCacheObservability.js / promptCacheRoutingAb.js measured ~8,700 tokens
+ * for a comparable prefix earlier in this stream. A fixture below the minimum would produce a real
+ * miss that means nothing about C3 — this one is not close to that line.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT IT COMPARES
+ *
+ * Both arms send the same large system prefix twice (cold, then warm) and vary only the final user
+ * turn — what a real caller does. The arms differ in exactly one thing: whether `cache.systemBreakpoints`
+ * is supplied, marking almost the entire prefix as a single cacheable block.
+ *
+ *   - arm 1 (WITHOUT systemBreakpoints) — the negative control. Anthropic caching is opt-in per
+ *     block; with no `cache_control` sent, nothing should be written or read, on either call.
+ *   - arm 2 (WITH systemBreakpoints)    — the cold call should show a cache WRITE
+ *     (`cacheWriteTokens` > 0, `cachedInputTokens` ~ 0); the warm call should show a cache READ
+ *     (`cachedInputTokens` clearing roughly the size of the cached prefix).
+ *
+ * `usage.reports` should be `'reads-and-writes'` on every call here — unlike xAI, which this
+ * stream's other harnesses measured as `'reads'`-only on both of its routes. Anthropic's normalizer
+ * (`normalizeAnthropicUsage`) reports both fields unconditionally.
+ *
+ * ---------------------------------------------------------------------------
+ * THE PREDICTION, WRITTEN DOWN BEFORE THE FIRST RUN
+ * (TESTING_GUIDELINES.md § "State the prediction before running it")
+ *
+ *   - arm 1 cold and warm — `cachedInputTokens` and `cacheWriteTokens` both absent or 0 on both
+ *     calls. No directive was sent, so nothing should be written or read.
+ *   - arm 2 cold          — `cacheWriteTokens` > 0 (writing the ~8,700-token prefix into the
+ *     cache), `cachedInputTokens` near 0 (nothing to read yet on a first-ever write).
+ *   - arm 2 warm           — `cachedInputTokens` clears roughly the prefix size — high, not a small
+ *     fixed floor the way xAI's automatic cache showed a ~192-token floor even on a cold call in
+ *     this stream's earlier runs. Anthropic's cache is explicit, so there is no equivalent
+ *     scaffolding-cost floor predicted here.
+ *
+ * A miss means C3's Anthropic emission is wrong, or this design's model of Anthropic caching is
+ * wrong. The response is to revise the design or the code — NOT to lower a threshold or re-run
+ * until a favourable number appears.
+ *
+ * ---------------------------------------------------------------------------
+ * TRAPS THAT MAKE A SINGLE RUN MISLEADING (carried over from promptCacheRoutingAb.js, and still
+ * live even though Anthropic's cache mechanism differs from xAI's per-server routing)
+ *
+ * 1. Re-running within the cache TTL taints the cold reading, because the "cold" call would hit a
+ *    prefix a previous run already wrote. Pass a fresh SALT (or wait out the TTL, ~5 minutes on
+ *    Anthropic's default ephemeral cache) — each run's prefix is salted so re-runs cannot warm a
+ *    prior run's cache, and the two arms are independently salted so they cannot warm each other.
+ *
+ * 2. A failed call must not print a ratio. If either arm's cold or warm call fails outright, the
+ *    verdict reports 'inconclusive' rather than fabricating a 0% or 100% from missing data — see
+ *    `runPromptCacheAnthropicBreakpointHarness`'s propagated failures and
+ *    `compareCacheHitRatios`'s `undefined` handling in `promptCacheUsageMath.ts`.
+ * ---------------------------------------------------------------------------
+ */
+
+/* eslint-disable no-console */
+
+const { AiAssist } = require('../lib/index');
+const {
+  describeAnthropicBreakpointUsage,
+  formatAnthropicBreakpointVerdict,
+  runPromptCacheAnthropicBreakpointHarness
+} = require('../lib/packlets/ai-assist/promptCacheAnthropicBreakpointHarness');
+
+const API_KEY = process.env.ANTHROPIC_API_KEY;
+if (!API_KEY) {
+  console.error('ANTHROPIC_API_KEY is required. See the file header for usage.');
+  process.exit(1);
+}
+const SALT = process.env.SALT ?? 'run1';
+
+async function main() {
+  console.log(`=== Anthropic prompt-cache breakpoint A/B (salt=${SALT}) ===`);
+  console.log('Both arms vary only the final user turn. They differ only in cache.systemBreakpoints.');
+
+  const descriptor = AiAssist.getProviderDescriptor('anthropic').orThrow();
+
+  const result = await runPromptCacheAnthropicBreakpointHarness(
+    { callCompletion: AiAssist.callProviderCompletion },
+    { descriptor, apiKey: API_KEY, salt: SALT }
+  );
+  if (result.isFailure()) {
+    console.error(result.message);
+    process.exit(1);
+  }
+
+  const { value } = result;
+  console.log(`\n--- ${value.withoutBreakpoint.label} ---`);
+  console.log(describeAnthropicBreakpointUsage('  cold', value.withoutBreakpoint.coldUsage));
+  console.log(describeAnthropicBreakpointUsage('  warm', value.withoutBreakpoint.warmUsage));
+  console.log(`\n--- ${value.withBreakpoint.label} ---`);
+  console.log(describeAnthropicBreakpointUsage('  cold', value.withBreakpoint.coldUsage));
+  console.log(describeAnthropicBreakpointUsage('  warm', value.withBreakpoint.warmUsage));
+
+  console.log('\n--- verdict ---');
+  console.log(formatAnthropicBreakpointVerdict(value));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/perf/promptCacheObservability.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ *
+ * Standing assertion for C1 of `ai-assist-prompt-caching` (design.md §8).
+ *
+ * Deliberately NOT a jest test. It is a live-traffic measurement, not a behavior —
+ * putting it in the suite would put CI's runtime and its green/red behind a network
+ * call and a bill (see TESTING_GUIDELINES.md § "Measurement Harnesses"). It lives
+ * here so it can be run on demand and its output pasted into the stream's
+ * `result.md`.
+ *
+ *   XAI_API_KEY=... node perf/promptCacheObservability.js
+ *
+ * Requires a built `lib/` (`rushx build` first).
+ *
+ * The ratio arithmetic, the cold/warm comparison, and the prediction verdict below all live in
+ * `src/packlets/ai-assist/promptCacheObservabilityHarness.ts`, unit-tested against fixture usage
+ * blocks in `src/test/unit/ai-assist/promptCacheObservabilityHarness.test.ts` — this file is a
+ * thin wrapper that supplies the live network transport and prints the result.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY xAI, NOT ANTHROPIC (corrected 2026-09-19 — the previous version of this note argued from a
+ * premise C3 has since retired; see below for what changed):
+ *
+ * xAI (and Gemini, and OpenAI's default mode) cache automatically with no request-side opt-in —
+ * confirmed live against xAI in this stream's design phase (design.md §12, OQ-1, the
+ * `xai-cache-probe` testbed scenario). A repeat request against xAI is therefore a valid test of
+ * whether C1's *reading* of the usage block is correct, on a provider whose cache needs no
+ * cooperation from the request this harness sends.
+ *
+ * Anthropic's prompt cache, by contrast, is opt-in per content block via `cache_control`, and
+ * this harness sends no cache directive of any kind — it calls `AiAssist.callProviderCompletion`
+ * with a plain `system` string and no `cache` field. That is no longer because "C1 sends no cache
+ * directive" (the reason this note originally gave): **C3 shipped and does emit `cache_control`
+ * when a caller supplies `IAiCacheRequest.systemBreakpoints`** — this harness simply doesn't pass
+ * one. So an Anthropic leg is possible now, in a way it structurally was not when this note was
+ * first written; it would need `IAiCacheRequest.systemBreakpoints` set on the request. It has
+ * never been run and is out of scope for this change — see design.md §8's addendum for what is
+ * and is not claimed here.
+ * ---------------------------------------------------------------------------
+ *
+ * THE PREDICTION, WRITTEN DOWN BEFORE THE FIRST RUN (per TESTING_GUIDELINES.md
+ * § "State the prediction before running it"), calibrated to the live numbers
+ * design.md §12 already recorded for this exact provider:
+ *
+ *   Two back-to-back requests share one large, byte-identical system-prompt
+ *   prefix and differ only in their final user turn.
+ *
+ *   - `usage.reports` should be `'reads'` on both calls — xAI never reports
+ *     cache writes on either of its routes (design.md §12, OQ-1).
+ *   - The FIRST (cold) call may still show a small nonzero
+ *     `usage.cachedInputTokens` — design.md §12 recorded a **128-token floor**
+ *     on a genuinely cold call against a prefix xAI had never seen, most
+ *     plausibly fixed chat-template scaffolding. A nonzero cold figure is
+ *     therefore NOT itself evidence of a bug; judge by the ratio, not the raw
+ *     count (design.md §9's explicit warning).
+ *   - The SECOND (warm) call should show `usage.cachedInputTokens` at
+ *     roughly **99%** of `usage.uncachedInputTokens + usage.cachedInputTokens`
+ *     for that call — design.md §12 measured 99.5% (Chat Completions) and
+ *     99.2% (Responses) on the same prefix-caching mechanism this harness
+ *     exercises.
+ *
+ *   A miss (cold and warm ratios roughly equal, or `reports` not `'reads'`)
+ *   means the C1 normalization is not doing what the design claims — the
+ *   response is to revise the design or the code, not to lower a threshold
+ *   until this harness goes green.
+ * ---------------------------------------------------------------------------
+ */
+
+/* eslint-disable no-console */
+
+const { AiAssist } = require('../lib/index');
+const {
+  describeObservabilityUsage,
+  runPromptCacheObservabilityHarness
+} = require('../lib/packlets/ai-assist/promptCacheObservabilityHarness');
+
+const API_KEY = process.env.XAI_API_KEY;
+if (!API_KEY) {
+  console.error('XAI_API_KEY is required. See the file header for usage.');
+  process.exit(1);
+}
+
+async function main() {
+  const descriptor = AiAssist.getProviderDescriptor('xai-grok').orThrow();
+
+  const result = await runPromptCacheObservabilityHarness(
+    { callCompletion: AiAssist.callProviderCompletion },
+    descriptor,
+    API_KEY
+  );
+  if (result.isFailure()) {
+    console.error(result.message);
+    process.exit(1);
+  }
+
+  const { value } = result;
+  console.log(describeObservabilityUsage('cold call ', value.cold));
+  console.log(describeObservabilityUsage('warm call ', value.warm));
+  console.log(`\nverdict: ${value.verdict.toUpperCase()} — ${value.detail}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/perf/promptCacheRoutingAb.js

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ *
+ * A/B for the xAI prompt-cache ROUTING key (IAiCacheRequest.cacheKey).
+ *
+ * Sibling to promptCacheObservability.js, which measures whether C1 *reads* the usage block
+ * correctly. This one measures whether the routing key actually *buys* anything — the claim
+ * this branch ships and the one thing its request-shape tests cannot check.
+ *
+ *   XAI_API_KEY=... node perf/promptCacheRoutingAb.js
+ *   SALT=run2 XAI_API_KEY=... node perf/promptCacheRoutingAb.js    # see "second trap" below
+ *
+ * Requires a built lib/ (`rushx build` first). Deliberately NOT a jest test: live traffic and a
+ * bill do not belong behind CI's green (TESTING_GUIDELINES.md § Measurement Harnesses).
+ *
+ * The prefix builder, the ratio arithmetic, and the CONFIRMS/MISSES/AMBIGUOUS verdict below all
+ * live in `src/packlets/ai-assist/promptCacheRoutingAbHarness.ts`, unit-tested against fixture
+ * usage blocks in `src/test/unit/ai-assist/promptCacheRoutingAbHarness.test.ts` — this file is a
+ * thin wrapper that supplies the live network transport and prints the result.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT IT COMPARES
+ *
+ * Both arms send the same large system prefix twice and vary only the final user turn — which
+ * is what a real caller does, and what the plain observability harness showed returns ~2%
+ * cached. The arms differ in exactly one thing: whether a stable `cache.cacheKey` is supplied.
+ *
+ * xAI matches byte-for-byte from the start of the messages array, but its cache is PER-SERVER
+ * and evictable, so two requests sharing a prefix can still miss when routed to different
+ * boxes. The key (x-grok-conv-id on Chat Completions) pins them together.
+ *
+ * ---------------------------------------------------------------------------
+ * THE PREDICTION, WRITTEN DOWN BEFORE THE FIRST RUN
+ * (TESTING_GUIDELINES.md § "State the prediction before running it")
+ *
+ *   - arm 1 (no key)  — warm stays near the ~2% floor, matching the observability harness's
+ *     measured 192-of-8876 on this exact shape.
+ *   - arm 2 (key)     — warm jumps toward ~99%, matching what the OQ-1 probe gets from
+ *     byte-identical requests.
+ *
+ * A miss means the routing key does not do what this branch claims. The response is to revise
+ * the change or the claim — NOT to re-run until a favourable number appears.
+ *
+ * ---------------------------------------------------------------------------
+ * TWO TRAPS THAT MAKE A SINGLE RUN MISLEADING
+ *
+ * 1. A hit in arm 1 is NOT a refutation. Without a routing key you can still land on the same
+ *    server by luck — that non-determinism is the whole reason the key exists. The meaningful
+ *    negative result is arm 2 FAILING to jump, not arm 1 happening to succeed.
+ *
+ * 2. Re-running within the cache TTL taints the cold reading, because the "cold" call hits a
+ *    prefix the previous run already warmed. Pass a fresh SALT (or wait out the TTL) — each arm
+ *    already gets its own salted prefix so the arms cannot warm each other, which is the
+ *    mistake the OQ-1 probe had to fix in its own first version.
+ * ---------------------------------------------------------------------------
+ */
+
+/* eslint-disable no-console */
+
+const { AiAssist } = require('../lib/index');
+const {
+  describeRoutingAbUsage,
+  formatRoutingAbVerdict,
+  runPromptCacheRoutingAbHarness
+} = require('../lib/packlets/ai-assist/promptCacheRoutingAbHarness');
+
+const API_KEY = process.env.XAI_API_KEY;
+if (!API_KEY) {
+  console.error('XAI_API_KEY is required. See the file header for usage.');
+  process.exit(1);
+}
+const SALT = process.env.SALT ?? 'run1';
+
+async function main() {
+  console.log(`=== xAI prompt-cache routing A/B (salt=${SALT}) ===`);
+  console.log('Both arms vary only the final user turn. They differ only in the routing key.');
+
+  const descriptor = AiAssist.getProviderDescriptor('xai-grok').orThrow();
+
+  const result = await runPromptCacheRoutingAbHarness(
+    { callCompletion: AiAssist.callProviderCompletion },
+    { descriptor, apiKey: API_KEY, salt: SALT }
+  );
+  if (result.isFailure()) {
+    console.error(result.message);
+    process.exit(1);
+  }
+
+  const { value } = result;
+  console.log(`\n--- ${value.withoutKey.label} ---`);
+  console.log(`  cold: ${describeRoutingAbUsage(value.withoutKey.coldUsage)}`);
+  console.log(`  warm: ${describeRoutingAbUsage(value.withoutKey.warmUsage)}`);
+  console.log(`\n--- ${value.withKey.label} ---`);
+  console.log(`  cold: ${describeRoutingAbUsage(value.withKey.coldUsage)}`);
+  console.log(`  warm: ${describeRoutingAbUsage(value.withKey.warmUsage)}`);
+
+  console.log('\n--- verdict ---');
+  console.log(formatRoutingAbVerdict(value));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});