universal-physics-tensor 10.0.0 → 12.0.0

package/dist/cli/expr-print.js.map

@@ -1 +1 @@
-{"version":3,"file":"expr-print.js","sourceRoot":"","sources":["../../src/cli/expr-print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three printed forms of a scalar composed AST (`upt symbolic`, audit F12 and I10):\n *\n * - DISPLAY: plain text for the reader, `·` for a product.\n * - EVAL: a formula `upt eval` parses, every named factor spelled so it evaluates (`8pi` → `(8*pi)`).\n * - LATEX: `\\frac` for every division, `\\cdot` for a product, braces for every exponent.\n *\n * Only `symbol` and `op` nodes are printed; any other node gives `null`, never a guess.\n */\nimport type { ExprNode } from '../dimensional/validator.js';\nimport type { Dimension } from '../dimensional/types.js';\n\ninterface PrintStyle {\n  readonly times: string;\n  readonly divide: string;\n  readonly symbol: (name: string) => string;\n}\n\nconst DISPLAY: PrintStyle = { times: '·', divide: ' / ', symbol: (name) => name };\n\n/** Named numeric stubs spelled so `upt eval` parses them. */\nexport const EVAL_STUBS: Readonly<Record<string, string>> = {\n  '8pi': '(8*pi)',\n  '4pi': '(4*pi)',\n  '2pi': '(2*pi)',\n  ln2: 'ln(2)',\n};\nconst EVAL: PrintStyle = { times: '*', divide: '/', symbol: (name) => EVAL_STUBS[name] ?? name };\n\n/**\n * Precedence-aware printing. Every divisor that is not a bare power is\n * grouped, so `a / (b·c)` never prints as `a / b·c` (audit F12); a quotient\n * inside a product or as a dividend is grouped too, for the reader.\n */\nfunction printInfix(n: ExprNode, style: PrintStyle): string | null {\n  if (n.kind === 'symbol') return style.symbol(n.name);\n  if (n.kind !== 'op') return null;\n  const parts: string[] = [];\n  for (let i = 0; i < n.args.length; i++) {\n    const a = n.args[i]!;\n    const s = printInfix(a, style);\n    if (s === null) return null;\n    const aOp = a.kind === 'op' ? a.op : null;\n    const group =\n      aOp !== null &&\n      (n.op === '^'\n        ? true\n        : n.op === '/'\n          ? i === 0\n            ? aOp === '+' || aOp === '-' || aOp === '/'\n            : aOp !== '^'\n          : n.op === '*'\n            ? aOp === '+' || aOp === '-' || aOp === '/'\n            : n.op === '-' && i > 0 && (aOp === '+' || aOp === '-'));\n    parts.push(group ? `(${s})` : s);\n  }\n  const sep = n.op === '*' ? style.times : n.op === '/' ? style.divide : n.op === '^' ? '^' : ` ${n.op} `;\n  return parts.join(sep);\n}\n\nexport const printDisplay = (n: ExprNode): string | null => printInfix(n, DISPLAY);\nexport const printEval = (n: ExprNode): string | null => printInfix(n, EVAL);\n\n/** LaTeX for the constant and stub names; any other name is spelled by {@link latexName}. */\nconst LATEX_NAMES: Readonly<Record<string, string>> = {\n  hbar: '\\\\hbar',\n  k_B: 'k_{\\\\mathrm{B}}',\n  '8pi': '8\\\\pi',\n  '4pi': '4\\\\pi',\n  '2pi': '2\\\\pi',\n  ln2: '\\\\ln 2',\n  pi: '\\\\pi',\n  epsilon_0: '\\\\varepsilon_{0}',\n  sigma_sb: '\\\\sigma_{\\\\mathrm{SB}}',\n};\n\n/** A name in LaTeX: one letter or a number as is, a hyphenated name as text, otherwise upright. */\nexport function latexName(name: string): string {\n  const known = LATEX_NAMES[name];\n  if (known !== undefined) return known;\n  if (/^[A-Za-z]$/.test(name) || Number.isFinite(Number(name))) return name;\n  return name.includes('-') ? `\\\\text{${name}}` : `\\\\mathrm{${name.replace(/_/g, '\\\\_')}}`;\n}\n\n/** The AST in LaTeX; `null` for a node other than `symbol` or `op`. */\nexport function printLatex(n: ExprNode): string | null {\n  if (n.kind === 'symbol') return latexName(n.name);\n  if (n.kind !== 'op') return null;\n  const args: string[] = [];\n  for (const a of n.args) {\n    const s = printLatex(a);\n    if (s === null) return null;\n    args.push(s);\n  }\n  const isOp = (a: ExprNode, ...ops: string[]): boolean => a.kind === 'op' && ops.includes(a.op);\n  const paren = (s: string): string => `\\\\left(${s}\\\\right)`;\n  switch (n.op) {\n    case '/':\n      return args.slice(1).reduce((num, den) => `\\\\frac{${num}}{${den}}`, args[0]!);\n    case '*':\n      return args.map((s, i) => (isOp(n.args[i]!, '+', '-') ? paren(s) : s)).join(' \\\\cdot ');\n    case '^': {\n      // The validator's arity guard makes `^` binary; a base that is not a symbol is grouped.\n      const base = n.args[0]!.kind === 'symbol' ? args[0]! : paren(args[0]!);\n      return `{${base}}^{${args[1]}}`;\n    }\n    case '+':\n      return args.join(' + ');\n    case '-':\n      return args.length === 1\n        ? `-${isOp(n.args[0]!, '+', '-') ? paren(args[0]!) : args[0]}`\n        : args.map((s, i) => (i > 0 && isOp(n.args[i]!, '+', '-') ? paren(s) : s)).join(' - ');\n  }\n}\n\nconst SI_BASE: readonly (readonly [keyof Dimension, string])[] = [\n  ['M', 'kg'],\n  ['L', 'm'],\n  ['T', 's'],\n  ['I', 'A'],\n  ['Theta', 'K'],\n  ['N', 'mol'],\n  ['J', 'cd'],\n];\n\nconst DIM_KEYS: readonly (keyof Dimension)[] = ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'];\nconst dimEqual = (a: Dimension, b: Dimension): boolean => DIM_KEYS.every((k) => (a[k] ?? 0) === (b[k] ?? 0));\nconst dimPow = (a: Dimension, n: number): Dimension =>\n  Object.fromEntries(DIM_KEYS.map((k) => [k, (a[k] ?? 0) * n])) as unknown as Dimension;\nconst dimMul = (a: Dimension, b: Dimension): Dimension =>\n  Object.fromEntries(DIM_KEYS.map((k) => [k, (a[k] ?? 0) + (b[k] ?? 0)])) as unknown as Dimension;\nconst isDimensionless = (d: Dimension): boolean => DIM_KEYS.every((k) => (d[k] ?? 0) === 0);\n\n/** One coherent SI unit of the table: a scale of exactly 1 and a dimension. */\nexport interface CoherentUnit {\n  readonly name: string;\n  readonly dim: Dimension;\n}\n\n/**\n * The coherent named SI units of a unit table (`unitRows()`): scale exactly 1,\n * not dimensionless, the first spelling the table gives for each dimension\n * (`ohm` before `Ω`). The seven base units are added so a label can mix them.\n * A cycle-counting unit (`Hz`, `rpm`; the table's `cycles` flag) is never a\n * label: a 1/s output may be an angular frequency, and `Hz` would say it\n * counts cycles. Such an output reads `1/s`, which is its dimension.\n */\nexport function coherentUnits(\n  rows: ReadonlyMap<\n    string,\n    { readonly scale: { readonly num: bigint; readonly den: bigint; readonly irrational: number }; readonly dim: Dimension; readonly cycles?: true }\n  >,\n): CoherentUnit[] {\n  const out: CoherentUnit[] = [];\n  const seen: Dimension[] = [];\n  const add = (name: string, dim: Dimension): void => {\n    if (isDimensionless(dim) || seen.some((d) => dimEqual(d, dim))) return;\n    seen.push(dim);\n    out.push({ name, dim });\n  };\n  for (const [name, row] of rows) {\n    if (row.cycles === true) continue;\n    if (row.scale.num === 1n && row.scale.den === 1n && row.scale.irrational === 1) add(name, row.dim);\n  }\n  for (const [k, u] of SI_BASE) {\n    add(u, Object.fromEntries(DIM_KEYS.map((key) => [key, key === k ? 1 : 0])) as unknown as Dimension);\n  }\n  return out;\n}\n\n/**\n * A dimension's label: the one coherent named unit whose dimension it is (`Pa`, `J`, `V`,\n * `ohm`, `T`), else the SI base form (`m/s`, `kg^2*m^4/(s^5*A^2)`). A product of two\n * named units is never chosen: a search over pairs once labelled a velocity `W/N` and a\n * voltage-noise density `J*ohm`, readings that are dimensionally right and physically\n * unreadable. Presentation only: the dimension is the fact, the label is a reading of it.\n */\nexport function derivedUnitOf(dim: Dimension, units: readonly CoherentUnit[]): string {\n  if (isDimensionless(dim)) return '1';\n  const base = new Set(SI_BASE.map(([, u]) => u));\n  const named = units.find((u) => !base.has(u.name) && dimEqual(u.dim, dim));\n  return named === undefined ? siUnitOf(dim) : named.name;\n}\n\n/** The SI base-unit form of a dimension (`m/s`, `kg*m^2/(s^3*A)`), `1` when dimensionless. */\nexport function siUnitOf(dim: Dimension): string {\n  const factor = (u: string, e: number): string => (e === 1 ? u : `${u}^${e}`);\n  const num = SI_BASE.filter(([k]) => dim[k] > 0).map(([k, u]) => factor(u, dim[k]));\n  const den = SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, -dim[k]));\n  if (num.length === 0 && den.length === 0) return '1';\n  if (num.length === 0) return SI_BASE.filter(([k]) => dim[k] < 0).map(([k, u]) => factor(u, dim[k])).join('*');\n  if (den.length === 0) return num.join('*');\n  return `${num.join('*')}/${den.length === 1 ? den[0] : `(${den.join('*')})`}`;\n}\n"]}
+{"version":3,"file":"expr-print.js","sourceRoot":"","sources":["../../src/cli/expr-print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three printed forms of a scalar composed AST (`upt symbolic`, audit F12 and I10):\n *\n * - DISPLAY: plain text for the reader, `·` for a product.\n * - EVAL: a formula `upt eval` parses, every named factor spelled so it evaluates (`8pi` → `(8*pi)`).\n * - LATEX: `\\frac` for every division, `\\cdot` for a product, braces for every exponent.\n *\n * Only `symbol` and `op` nodes are printed; any other node gives `null`, never a guess.\n */\nimport type { ExprNode } from '../dimensional/validator.js';\nimport type { Dimension } from '../dimensional/types.js';\nimport { BASES, exactlyEquals, isDimensionless, SI_BASE, siUnitOf } from '../dimensional/algebra.js';\nimport { isDecimalLiteral } from '../dimensional/ast-leaves.js';\n\ninterface PrintStyle {\n  readonly times: string;\n  readonly divide: string;\n  readonly symbol: (name: string) => string;\n}\n\nconst DISPLAY: PrintStyle = { times: '·', divide: ' / ', symbol: (name) => name };\n\n/** Named numeric stubs spelled so `upt eval` parses them. */\nexport const EVAL_STUBS: Readonly<Record<string, string>> = {\n  '8pi': '(8*pi)',\n  '4pi': '(4*pi)',\n  '2pi': '(2*pi)',\n  ln2: 'ln(2)',\n};\nconst EVAL: PrintStyle = { times: '*', divide: '/', symbol: (name) => EVAL_STUBS[name] ?? name };\n\n/**\n * Precedence-aware printing. Every divisor that is not a bare power is\n * grouped, so `a / (b·c)` never prints as `a / b·c` (audit F12); a quotient\n * inside a product or as a dividend is grouped too, for the reader.\n */\nfunction printInfix(n: ExprNode, style: PrintStyle): string | null {\n  if (n.kind === 'symbol') return style.symbol(n.name);\n  if (n.kind !== 'op') return null;\n  const parts: string[] = [];\n  for (let i = 0; i < n.args.length; i++) {\n    const a = n.args[i]!;\n    const s = printInfix(a, style);\n    if (s === null) return null;\n    const aOp = a.kind === 'op' ? a.op : null;\n    const group =\n      aOp !== null &&\n      (n.op === '^'\n        ? true\n        : n.op === '/'\n          ? i === 0\n            ? aOp === '+' || aOp === '-' || aOp === '/'\n            : aOp !== '^'\n          : n.op === '*'\n            ? aOp === '+' || aOp === '-' || aOp === '/'\n            : n.op === '-' && i > 0 && (aOp === '+' || aOp === '-'));\n    parts.push(group ? `(${s})` : s);\n  }\n  const sep = n.op === '*' ? style.times : n.op === '/' ? style.divide : n.op === '^' ? '^' : ` ${n.op} `;\n  return parts.join(sep);\n}\n\nexport const printDisplay = (n: ExprNode): string | null => printInfix(n, DISPLAY);\nexport const printEval = (n: ExprNode): string | null => printInfix(n, EVAL);\n\n/** LaTeX for the constant and stub names; any other name is spelled by {@link latexName}. */\nconst LATEX_NAMES: Readonly<Record<string, string>> = {\n  hbar: '\\\\hbar',\n  k_B: 'k_{\\\\mathrm{B}}',\n  '8pi': '8\\\\pi',\n  '4pi': '4\\\\pi',\n  '2pi': '2\\\\pi',\n  ln2: '\\\\ln 2',\n  pi: '\\\\pi',\n  epsilon_0: '\\\\varepsilon_{0}',\n  sigma_sb: '\\\\sigma_{\\\\mathrm{SB}}',\n};\n\n/** A name in LaTeX: one letter or a number as is, a hyphenated name as text, otherwise upright. */\nexport function latexName(name: string): string {\n  const known = LATEX_NAMES[name];\n  if (known !== undefined) return known;\n  // A decimal literal prints as is; `Number()` also read '' and '0x10' as numbers.\n  if (/^[A-Za-z]$/.test(name) || isDecimalLiteral(name)) return name;\n  return name.includes('-') ? `\\\\text{${name}}` : `\\\\mathrm{${name.replace(/_/g, '\\\\_')}}`;\n}\n\n/** The AST in LaTeX; `null` for a node other than `symbol` or `op`. */\nexport function printLatex(n: ExprNode): string | null {\n  if (n.kind === 'symbol') return latexName(n.name);\n  if (n.kind !== 'op') return null;\n  const args: string[] = [];\n  for (const a of n.args) {\n    const s = printLatex(a);\n    if (s === null) return null;\n    args.push(s);\n  }\n  const isOp = (a: ExprNode, ...ops: string[]): boolean => a.kind === 'op' && ops.includes(a.op);\n  const paren = (s: string): string => `\\\\left(${s}\\\\right)`;\n  switch (n.op) {\n    case '/':\n      return args.slice(1).reduce((num, den) => `\\\\frac{${num}}{${den}}`, args[0]!);\n    case '*':\n      return args.map((s, i) => (isOp(n.args[i]!, '+', '-') ? paren(s) : s)).join(' \\\\cdot ');\n    case '^': {\n      // The validator's arity guard makes `^` binary; a base that is not a symbol is grouped.\n      const base = n.args[0]!.kind === 'symbol' ? args[0]! : paren(args[0]!);\n      return `{${base}}^{${args[1]}}`;\n    }\n    case '+':\n      return args.join(' + ');\n    case '-':\n      return args.length === 1\n        ? `-${isOp(n.args[0]!, '+', '-') ? paren(args[0]!) : args[0]}`\n        : args.map((s, i) => (i > 0 && isOp(n.args[i]!, '+', '-') ? paren(s) : s)).join(' - ');\n  }\n}\n\n\n/** One coherent SI unit of the table: a scale of exactly 1 and a dimension. */\nexport interface CoherentUnit {\n  readonly name: string;\n  readonly dim: Dimension;\n}\n\n/**\n * The coherent named SI units of a unit table (`unitRows()`): scale exactly 1,\n * not dimensionless, the first spelling the table gives for each dimension\n * (`ohm` before `Ω`). The seven base units are added so a label can mix them.\n * A cycle-counting unit (`Hz`, `rpm`; the table's `cycles` flag) is never a\n * label: a 1/s output may be an angular frequency, and `Hz` would say it\n * counts cycles. Such an output reads `1/s`, which is its dimension.\n */\nexport function coherentUnits(\n  rows: ReadonlyMap<\n    string,\n    { readonly scale: { readonly num: bigint; readonly den: bigint; readonly irrational: number }; readonly dim: Dimension; readonly cycles?: true }\n  >,\n): CoherentUnit[] {\n  const out: CoherentUnit[] = [];\n  const seen: Dimension[] = [];\n  const add = (name: string, dim: Dimension): void => {\n    if (isDimensionless(dim) || seen.some((d) => exactlyEquals(d, dim))) return;\n    seen.push(dim);\n    out.push({ name, dim });\n  };\n  for (const [name, row] of rows) {\n    if (row.cycles === true) continue;\n    if (row.scale.num === 1n && row.scale.den === 1n && row.scale.irrational === 1) add(name, row.dim);\n  }\n  for (const [k, u] of SI_BASE) {\n    add(u, Object.fromEntries(BASES.map((key) => [key, key === k ? 1 : 0])) as unknown as Dimension);\n  }\n  return out;\n}\n\n/**\n * A dimension's label: the one coherent named unit whose dimension it is (`Pa`, `J`, `V`,\n * `ohm`, `T`), else the SI base form (`m/s`, `kg^2*m^4/(s^5*A^2)`). A product of two\n * named units is never chosen: a search over pairs once labelled a velocity `W/N` and a\n * voltage-noise density `J*ohm`, readings that are dimensionally right and physically\n * unreadable. Presentation only: the dimension is the fact, the label is a reading of it.\n */\nexport function derivedUnitOf(dim: Dimension, units: readonly CoherentUnit[]): string {\n  if (isDimensionless(dim)) return '1';\n  const base = new Set(SI_BASE.map(([, u]) => u));\n  const named = units.find((u) => !base.has(u.name) && exactlyEquals(u.dim, dim));\n  return named === undefined ? siUnitOf(dim) : named.name;\n}\n"]}

package/dist/cli/flag-help.d.ts

@@ -21,6 +21,7 @@ export declare const BUILTIN_VERBS: readonly {
     example: string;
     group: 'utilities';
 }[];
+/** The usage heading of one flag, showing how its value is written. */
 export declare function flagHeading(flag: FlagSpec): string;
 /** The Flags block a command's help string ends with. Empty when the command takes no flags. */
 export declare function renderFlagCatalog(flags: readonly FlagSpec[], heading?: string): string;

package/dist/cli/flag-help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flag-help.d.ts","sourceRoot":"","sources":["../../src/cli/flag-help.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,SAAS,EAAE,QAIvB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAOzE;AAED,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,SAAS,QAAQ,EA8B3C,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,SAAS;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB,EAaA,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAgBlD;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,SAAW,GAAG,MAAM,CAYxF;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAG7E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,EAAE,CAEpF"}
+{"version":3,"file":"flag-help.d.ts","sourceRoot":"","sources":["../../src/cli/flag-help.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,SAAS,EAAE,QAIvB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAOzE;AAED,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,SAAS,QAAQ,EA8B3C,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,SAAS;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB,EAaA,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAgBlD;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,SAAW,GAAG,MAAM,CAYxF;AAED,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAG7E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,EAAE,CAEpF"}

package/dist/cli/flag-help.js

@@ -66,6 +66,7 @@ export const BUILTIN_VERBS = [
         group: 'utilities',
     },
 ];
+/** The usage heading of one flag, showing how its value is written. */
 export function flagHeading(flag) {
     const repeat = flag.repeatable ? ' (repeatable)' : '';
     switch (flag.valueStyle) {

package/dist/cli/flag-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"flag-help.js","sourceRoot":"","sources":["../../src/cli/flag-help.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Flag text for `upt help` and for `docs/CLI.md`.\n *\n * The parser reads `FlagSpec` (`args.ts`). This module renders the same\n * objects. A command's help string is `commandHelp(prose, flags)`, so the\n * Flags section cannot list a different set than the parser accepts.\n */\n\nimport type { FlagSpec } from './args.js';\n\n/** `--json` on a data-bearing command. The same object is the global option. */\nexport const JSON_FLAG: FlagSpec = {\n  name: '--json',\n  valueStyle: 'none',\n  description: 'Write a JSON envelope to stdout instead of the text report.',\n};\n\n/**\n * `--source=VALUE` for a graph command.\n * `detail` is the sentence; `defaultValue` is what the command uses when the flag is absent.\n */\nexport function sourceFlag(defaultValue: string, detail: string): FlagSpec {\n  return {\n    name: '--source',\n    valueStyle: 'attached',\n    description: detail,\n    defaultValue,\n  };\n}\n\n/** Dispatcher options. `main.ts` accepts these before the command name. */\nexport const GLOBAL_FLAGS: readonly FlagSpec[] = [\n  {\n    name: '--help',\n    valueStyle: 'none',\n    description:\n      'Show this command list, or `upt help <command>` for one command. `-h` is the same. `upt <command> --help` prints that command.',\n  },\n  {\n    name: '--version',\n    valueStyle: 'none',\n    description: 'Print the package version as one semver line and exit. `-v` and `upt version` are the same. Neither takes --json.',\n  },\n  JSON_FLAG,\n  {\n    name: '--record',\n    valueStyle: 'attached',\n    description:\n      'Run the following command unchanged and append one JSONL entry to FILE: arguments, stdout, stderr, exit code, versions, and hashes. A failed run is recorded too.',\n  },\n  {\n    name: '--replay',\n    valueStyle: 'attached',\n    description:\n      'Re-run every entry of FILE and report reproduced, differs, or not replayable. Takes no command. `--json` after it selects the JSON report. Exit 0 when every entry is reproduced and unchanged, 3 when any differs, 1 otherwise.',\n  },\n  {\n    name: '--show-record',\n    valueStyle: 'attached',\n    description: 'Print FILE as a transcript and run nothing. Takes no command. `--json` after it selects the JSON report.',\n  },\n];\n\nexport const BUILTIN_VERBS: readonly {\n  name: string;\n  summary: string;\n  example: string;\n  group: 'utilities';\n}[] = [\n  {\n    name: 'help',\n    summary: 'Show every command, or one command\\'s usage and flags. `upt help statuses` defines the status words.',\n    example: 'upt help eval',\n    group: 'utilities',\n  },\n  {\n    name: 'version',\n    summary: 'Print the installed package version as one semver line.',\n    example: 'upt version',\n    group: 'utilities',\n  },\n];\n\nexport function flagHeading(flag: FlagSpec): string {\n  const repeat = flag.repeatable ? ' (repeatable)' : '';\n  switch (flag.valueStyle) {\n    case 'none':\n      return `${flag.name}${repeat}`;\n    case 'attached':\n      return `${flag.name}=VALUE${repeat}`;\n    case 'next':\n      return `${flag.name} VALUE${repeat}`;\n    case 'either':\n      return `${flag.name}=VALUE${repeat} (or ${flag.name} VALUE)`;\n    default: {\n      const _never: never = flag.valueStyle;\n      return _never;\n    }\n  }\n}\n\n/** The Flags block a command's help string ends with. Empty when the command takes no flags. */\nexport function renderFlagCatalog(flags: readonly FlagSpec[], heading = 'Flags:'): string {\n  if (flags.length === 0) return '';\n  const lines = [heading];\n  for (const flag of flags) {\n    if (flag.description === undefined || flag.description.trim() === '') {\n      throw new Error(`flag ${flag.name} has no description`);\n    }\n    lines.push(`  ${flagHeading(flag)}`);\n    const def = flag.defaultValue === undefined ? '' : ` Default: ${flag.defaultValue}.`;\n    lines.push(`        ${flag.description}${def}`);\n  }\n  return lines.join('\\n');\n}\n\n/** Prose plus the flag catalog. The catalog is the spec; the prose is the narrative. */\nexport function commandHelp(prose: string, flags: readonly FlagSpec[]): string {\n  const catalog = renderFlagCatalog(flags);\n  return catalog === '' ? prose : `${prose}\\n${catalog}`;\n}\n\n/**\n * Flags whose description is missing from `help`.\n * A command that forgot `commandHelp` fails here. A description that is present does not.\n */\nexport function undocumentedFlags(help: string, flags: readonly FlagSpec[]): string[] {\n  return flags.filter((flag) => flag.description === undefined || !help.includes(flag.description)).map((flag) => flag.name);\n}\n"]}
+{"version":3,"file":"flag-help.js","sourceRoot":"","sources":["../../src/cli/flag-help.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Flag text for `upt help` and for `docs/CLI.md`.\n *\n * The parser reads `FlagSpec` (`args.ts`). This module renders the same\n * objects. A command's help string is `commandHelp(prose, flags)`, so the\n * Flags section cannot list a different set than the parser accepts.\n */\n\nimport type { FlagSpec } from './args.js';\n\n/** `--json` on a data-bearing command. The same object is the global option. */\nexport const JSON_FLAG: FlagSpec = {\n  name: '--json',\n  valueStyle: 'none',\n  description: 'Write a JSON envelope to stdout instead of the text report.',\n};\n\n/**\n * `--source=VALUE` for a graph command.\n * `detail` is the sentence; `defaultValue` is what the command uses when the flag is absent.\n */\nexport function sourceFlag(defaultValue: string, detail: string): FlagSpec {\n  return {\n    name: '--source',\n    valueStyle: 'attached',\n    description: detail,\n    defaultValue,\n  };\n}\n\n/** Dispatcher options. `main.ts` accepts these before the command name. */\nexport const GLOBAL_FLAGS: readonly FlagSpec[] = [\n  {\n    name: '--help',\n    valueStyle: 'none',\n    description:\n      'Show this command list, or `upt help <command>` for one command. `-h` is the same. `upt <command> --help` prints that command.',\n  },\n  {\n    name: '--version',\n    valueStyle: 'none',\n    description: 'Print the package version as one semver line and exit. `-v` and `upt version` are the same. Neither takes --json.',\n  },\n  JSON_FLAG,\n  {\n    name: '--record',\n    valueStyle: 'attached',\n    description:\n      'Run the following command unchanged and append one JSONL entry to FILE: arguments, stdout, stderr, exit code, versions, and hashes. A failed run is recorded too.',\n  },\n  {\n    name: '--replay',\n    valueStyle: 'attached',\n    description:\n      'Re-run every entry of FILE and report reproduced, differs, or not replayable. Takes no command. `--json` after it selects the JSON report. Exit 0 when every entry is reproduced and unchanged, 3 when any differs, 1 otherwise.',\n  },\n  {\n    name: '--show-record',\n    valueStyle: 'attached',\n    description: 'Print FILE as a transcript and run nothing. Takes no command. `--json` after it selects the JSON report.',\n  },\n];\n\nexport const BUILTIN_VERBS: readonly {\n  name: string;\n  summary: string;\n  example: string;\n  group: 'utilities';\n}[] = [\n  {\n    name: 'help',\n    summary: 'Show every command, or one command\\'s usage and flags. `upt help statuses` defines the status words.',\n    example: 'upt help eval',\n    group: 'utilities',\n  },\n  {\n    name: 'version',\n    summary: 'Print the installed package version as one semver line.',\n    example: 'upt version',\n    group: 'utilities',\n  },\n];\n\n/** The usage heading of one flag, showing how its value is written. */\nexport function flagHeading(flag: FlagSpec): string {\n  const repeat = flag.repeatable ? ' (repeatable)' : '';\n  switch (flag.valueStyle) {\n    case 'none':\n      return `${flag.name}${repeat}`;\n    case 'attached':\n      return `${flag.name}=VALUE${repeat}`;\n    case 'next':\n      return `${flag.name} VALUE${repeat}`;\n    case 'either':\n      return `${flag.name}=VALUE${repeat} (or ${flag.name} VALUE)`;\n    default: {\n      const _never: never = flag.valueStyle;\n      return _never;\n    }\n  }\n}\n\n/** The Flags block a command's help string ends with. Empty when the command takes no flags. */\nexport function renderFlagCatalog(flags: readonly FlagSpec[], heading = 'Flags:'): string {\n  if (flags.length === 0) return '';\n  const lines = [heading];\n  for (const flag of flags) {\n    if (flag.description === undefined || flag.description.trim() === '') {\n      throw new Error(`flag ${flag.name} has no description`);\n    }\n    lines.push(`  ${flagHeading(flag)}`);\n    const def = flag.defaultValue === undefined ? '' : ` Default: ${flag.defaultValue}.`;\n    lines.push(`        ${flag.description}${def}`);\n  }\n  return lines.join('\\n');\n}\n\n/** Prose plus the flag catalog. The catalog is the spec; the prose is the narrative. */\nexport function commandHelp(prose: string, flags: readonly FlagSpec[]): string {\n  const catalog = renderFlagCatalog(flags);\n  return catalog === '' ? prose : `${prose}\\n${catalog}`;\n}\n\n/**\n * Flags whose description is missing from `help`.\n * A command that forgot `commandHelp` fails here. A description that is present does not.\n */\nexport function undocumentedFlags(help: string, flags: readonly FlagSpec[]): string[] {\n  return flags.filter((flag) => flag.description === undefined || !help.includes(flag.description)).map((flag) => flag.name);\n}\n"]}

package/dist/cli/graphs.d.ts

@@ -7,7 +7,9 @@
 import type { BridgeEdge } from '../composition/edge.js';
 import type { ParsedArgs } from './args.js';
 import type { CommandCtx } from './command.js';
+/** The graph that a command reads, as chosen by its `--source` flag. */
 export type SourceName = 'catalog' | 'canonical' | 'both';
+/** Resolve the `--source` flag to graph edges, a banner label and the source name. */
 export declare function resolveGraph(api: CommandCtx['api'], flags: ParsedArgs['flags']): {
     graph: BridgeEdge[];
     label: string;

package/dist/cli/graphs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1D,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,GACzB;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CA0B5D;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1G,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,IAAI,EAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAChE,WAAW,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAIzC;AAED,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAEzF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,GAAG,MAAM,CAGlF;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAEpE"}
+{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1D,sFAAsF;AACtF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,GACzB;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CA0B5D;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1G,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,IAAI,EAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAChE,WAAW,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAIzC;AAED,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAEzF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,GAAG,MAAM,CAGlF;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAEpE"}

package/dist/cli/graphs.js

@@ -5,6 +5,7 @@
  * this once to get the graph + a human-readable label for its banner.
  */
 import { CliError } from './errors.js';
+/** Resolve the `--source` flag to graph edges, a banner label and the source name. */
 export function resolveGraph(api, flags) {
     const values = flags.get('source');
     const src = values && values.length > 0 ? values[values.length - 1] : 'catalog';

package/dist/cli/graphs.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphs.js","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,MAAM,UAAU,YAAY,CAC1B,GAAsB,EACtB,KAA0B;IAE1B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhF,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC;gBAC7B,KAAK,EAAE,YAAY,GAAG,CAAC,gBAAgB,CAAC,MAAM,UAAU;gBACxD,MAAM,EAAE,SAAS;aAClB,CAAC;QACJ,KAAK,WAAW;YACd,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC;gBAC/B,KAAK,EAAE,wDAAwD;gBAC/D,MAAM,EAAE,WAAW;aACpB,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,EAAE,GAAG,GAAG,CAAC,eAAe,CAAC;gBACrD,KAAK,EAAE,qBAAqB;gBAC5B,MAAM,EAAE,MAAM;aACf,CAAC;QACJ;YACE,MAAM,IAAI,QAAQ,CAAC,0BAA0B,GAAG,0CAA0C,CAAC,CAAC;IAChG,CAAC;AACH,CAAC;AAaD,8GAA8G;AAC9G,MAAM,UAAU,iBAAiB,CAC/B,GAAsB,EACtB,IAAiE;IAEjE,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS;QACnC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,GAAG,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;QACxD,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC5D,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,UAAU,CAAC,KAA4B;IACrD,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,aAAa,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AAC/G,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,CAA0C;IACxE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChF,OAAO,WAAW,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC;AAC7G,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,CAAmC;IAC1D,OAAO,2DAA2D,CAAC,CAAC,gBAAgB,0CAA0C,CAAC,CAAC,KAAK,gBAAgB,CAAC;AACxJ,CAAC","sourcesContent":["/**\n * Shared `--source=catalog|canonical|both` graph resolution — replaces\n * `bin/upt.mjs`'s `resolveGraph` (lines 53-67). Every analysis command\n * (`discover` / `candidates` / `map` / ...) that accepts `--source` calls\n * this once to get the graph + a human-readable label for its banner.\n */\n\nimport type { BridgeEdge } from '../composition/edge.js';\nimport type { ParsedArgs } from './args.js';\nimport type { CommandCtx } from './command.js';\nimport { CliError } from './errors.js';\n\nexport type SourceName = 'catalog' | 'canonical' | 'both';\n\nexport function resolveGraph(\n  api: CommandCtx['api'],\n  flags: ParsedArgs['flags']\n): { graph: BridgeEdge[]; label: string; source: SourceName } {\n  const values = flags.get('source');\n  const src = values && values.length > 0 ? values[values.length - 1] : 'catalog';\n\n  switch (src) {\n    case 'catalog':\n      return {\n        graph: [...api.CATALOG_GRAPH],\n        label: `catalog (${api.BRIDGE_EQUATIONS.length}-bridge)`,\n        source: 'catalog',\n      };\n    case 'canonical':\n      return {\n        graph: [...api.CANONICAL_GRAPH],\n        label: 'canonical (standard-physics L-layer, bridges excluded)',\n        source: 'canonical',\n      };\n    case 'both':\n      return {\n        graph: [...api.CATALOG_GRAPH, ...api.CANONICAL_GRAPH],\n        label: 'catalog + canonical',\n        source: 'both',\n      };\n    default:\n      throw new CliError(`upt: unknown --source='${src}' (expected: catalog | canonical | both)`);\n  }\n}\n\n/**\n * What a result is anchored to (audit I3), printed beside the source in text and carried as the\n * envelope's `anchor` in `--json`. Two different anchors exist and are never merged:\n * `groundTruth` is the discovery funnel's known values (`--anchor=k=v`, default one solar mass);\n * `core` is the set of established-confidence edges that \"anchored\" means in a linkage view.\n */\nexport interface AnchorScope {\n  readonly groundTruth?: { readonly values: Readonly<Record<string, number>>; readonly isDefault: boolean };\n  readonly core?: { readonly establishedEdges: number; readonly edges: number };\n}\n\n/** The discovery ground truth a result is relative to: the `--anchor` values when given, else the default. */\nexport function groundTruthAnchor(\n  api: CommandCtx['api'],\n  opts: { readonly groundTruth?: Readonly<Record<string, number>> },\n): NonNullable<AnchorScope['groundTruth']> {\n  return opts.groundTruth === undefined\n    ? { values: { ...api.ANCHOR_DEFAULT }, isDefault: true }\n    : { values: { ...opts.groundTruth }, isDefault: false };\n}\n\n/** The established core of `graph`: its established-confidence edge count beside its edge count. */\nexport function coreAnchor(graph: readonly BridgeEdge[]): NonNullable<AnchorScope['core']> {\n  return { establishedEdges: graph.filter((e) => e.confidence === 'established').length, edges: graph.length };\n}\n\n/** The text line naming the ground-truth anchor and whether it is the default. */\nexport function groundTruthLine(a: NonNullable<AnchorScope['groundTruth']>): string {\n  const values = Object.entries(a.values).map(([k, v]) => `${k}=${v}`).join(', ');\n  return `anchor: ${values}${a.isDefault ? ' (the default; --anchor=k=v replaces it)' : ' (from --anchor)'}`;\n}\n\n/** The text line stating what \"anchored\" means for a graph's established core. */\nexport function coreLine(a: NonNullable<AnchorScope['core']>): string {\n  return `anchored core: the clusters holding at least one of the ${a.establishedEdges} established-confidence edge(s) of the ${a.edges} in this graph`;\n}"]}
+{"version":3,"file":"graphs.js","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKvC,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAC1B,GAAsB,EACtB,KAA0B;IAE1B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhF,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC;gBAC7B,KAAK,EAAE,YAAY,GAAG,CAAC,gBAAgB,CAAC,MAAM,UAAU;gBACxD,MAAM,EAAE,SAAS;aAClB,CAAC;QACJ,KAAK,WAAW;YACd,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC;gBAC/B,KAAK,EAAE,wDAAwD;gBAC/D,MAAM,EAAE,WAAW;aACpB,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,EAAE,GAAG,GAAG,CAAC,eAAe,CAAC;gBACrD,KAAK,EAAE,qBAAqB;gBAC5B,MAAM,EAAE,MAAM;aACf,CAAC;QACJ;YACE,MAAM,IAAI,QAAQ,CAAC,0BAA0B,GAAG,0CAA0C,CAAC,CAAC;IAChG,CAAC;AACH,CAAC;AAaD,8GAA8G;AAC9G,MAAM,UAAU,iBAAiB,CAC/B,GAAsB,EACtB,IAAiE;IAEjE,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS;QACnC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,GAAG,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE;QACxD,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC5D,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,UAAU,CAAC,KAA4B;IACrD,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,aAAa,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;AAC/G,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,CAA0C;IACxE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChF,OAAO,WAAW,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC;AAC7G,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,CAAmC;IAC1D,OAAO,2DAA2D,CAAC,CAAC,gBAAgB,0CAA0C,CAAC,CAAC,KAAK,gBAAgB,CAAC;AACxJ,CAAC","sourcesContent":["/**\n * Shared `--source=catalog|canonical|both` graph resolution — replaces\n * `bin/upt.mjs`'s `resolveGraph` (lines 53-67). Every analysis command\n * (`discover` / `candidates` / `map` / ...) that accepts `--source` calls\n * this once to get the graph + a human-readable label for its banner.\n */\n\nimport type { BridgeEdge } from '../composition/edge.js';\nimport type { ParsedArgs } from './args.js';\nimport type { CommandCtx } from './command.js';\nimport { CliError } from './errors.js';\n\n/** The graph that a command reads, as chosen by its `--source` flag. */\nexport type SourceName = 'catalog' | 'canonical' | 'both';\n\n/** Resolve the `--source` flag to graph edges, a banner label and the source name. */\nexport function resolveGraph(\n  api: CommandCtx['api'],\n  flags: ParsedArgs['flags']\n): { graph: BridgeEdge[]; label: string; source: SourceName } {\n  const values = flags.get('source');\n  const src = values && values.length > 0 ? values[values.length - 1] : 'catalog';\n\n  switch (src) {\n    case 'catalog':\n      return {\n        graph: [...api.CATALOG_GRAPH],\n        label: `catalog (${api.BRIDGE_EQUATIONS.length}-bridge)`,\n        source: 'catalog',\n      };\n    case 'canonical':\n      return {\n        graph: [...api.CANONICAL_GRAPH],\n        label: 'canonical (standard-physics L-layer, bridges excluded)',\n        source: 'canonical',\n      };\n    case 'both':\n      return {\n        graph: [...api.CATALOG_GRAPH, ...api.CANONICAL_GRAPH],\n        label: 'catalog + canonical',\n        source: 'both',\n      };\n    default:\n      throw new CliError(`upt: unknown --source='${src}' (expected: catalog | canonical | both)`);\n  }\n}\n\n/**\n * What a result is anchored to (audit I3), printed beside the source in text and carried as the\n * envelope's `anchor` in `--json`. Two different anchors exist and are never merged:\n * `groundTruth` is the discovery funnel's known values (`--anchor=k=v`, default one solar mass);\n * `core` is the set of established-confidence edges that \"anchored\" means in a linkage view.\n */\nexport interface AnchorScope {\n  readonly groundTruth?: { readonly values: Readonly<Record<string, number>>; readonly isDefault: boolean };\n  readonly core?: { readonly establishedEdges: number; readonly edges: number };\n}\n\n/** The discovery ground truth a result is relative to: the `--anchor` values when given, else the default. */\nexport function groundTruthAnchor(\n  api: CommandCtx['api'],\n  opts: { readonly groundTruth?: Readonly<Record<string, number>> },\n): NonNullable<AnchorScope['groundTruth']> {\n  return opts.groundTruth === undefined\n    ? { values: { ...api.ANCHOR_DEFAULT }, isDefault: true }\n    : { values: { ...opts.groundTruth }, isDefault: false };\n}\n\n/** The established core of `graph`: its established-confidence edge count beside its edge count. */\nexport function coreAnchor(graph: readonly BridgeEdge[]): NonNullable<AnchorScope['core']> {\n  return { establishedEdges: graph.filter((e) => e.confidence === 'established').length, edges: graph.length };\n}\n\n/** The text line naming the ground-truth anchor and whether it is the default. */\nexport function groundTruthLine(a: NonNullable<AnchorScope['groundTruth']>): string {\n  const values = Object.entries(a.values).map(([k, v]) => `${k}=${v}`).join(', ');\n  return `anchor: ${values}${a.isDefault ? ' (the default; --anchor=k=v replaces it)' : ' (from --anchor)'}`;\n}\n\n/** The text line stating what \"anchored\" means for a graph's established core. */\nexport function coreLine(a: NonNullable<AnchorScope['core']>): string {\n  return `anchored core: the clusters holding at least one of the ${a.establishedEdges} established-confidence edge(s) of the ${a.edges} in this graph`;\n}"]}

package/dist/cli/main.d.ts

@@ -15,5 +15,13 @@
  */
 import { type Io } from './record.js';
 import './commands/index.js';
+/**
+ * The last-resort handler `bin/upt.mjs` calls when `runCli` rethrows: a defect, since every
+ * usage error and value refusal was mapped to an exit code inside `runCli`. Prints one line,
+ * `upt: internal error: <message>` (the message, not the stack), and returns 70 (EX_SOFTWARE).
+ * A thrown value that is not an Error, or an Error with no message, prints as its string.
+ */
+export declare function reportInternalError(error: unknown, io?: Pick<Io, 'err'>): number;
+/** Run one `upt` invocation and return its exit code. */
 export declare function runCli(argv: string[], io?: Io): Promise<number>;
 //# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,OAAO,EAA8C,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,qBAAqB,CAAC;AAmC7B,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,EAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDhF"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,OAAO,EAA8C,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,qBAAqB,CAAC;AAuB7B;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAa,GAAG,MAAM,CAI3F;AAiBD,yDAAyD;AACzD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,EAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDhF"}

package/dist/cli/main.js

@@ -37,6 +37,19 @@ function stdoutRaw(s) {
     process.stdout.write(s);
 }
 const defaultIo = { out: stdoutLine, err: stderrLine, write: stdoutRaw };
+/** EX_SOFTWARE (sysexits.h): the exit code of a defect, an error `runCli` did not map. */
+const EX_SOFTWARE = 70;
+/**
+ * The last-resort handler `bin/upt.mjs` calls when `runCli` rethrows: a defect, since every
+ * usage error and value refusal was mapped to an exit code inside `runCli`. Prints one line,
+ * `upt: internal error: <message>` (the message, not the stack), and returns 70 (EX_SOFTWARE).
+ * A thrown value that is not an Error, or an Error with no message, prints as its string.
+ */
+export function reportInternalError(error, io = defaultIo) {
+    const message = error instanceof Error && error.message !== '' ? error.message : String(error);
+    io.err(`upt: internal error: ${message}`);
+    return EX_SOFTWARE;
+}
 const unknownCommandMessage = (name) => `Unknown command '${name}'. See \`upt help\`.`;
 const GLOBAL_FILE_OPTION = /^--(record|replay|show-record)(?:=(.*))?$/;
 /**
@@ -49,6 +62,7 @@ const GLOBAL_FILE_OPTION = /^--(record|replay|show-record)(?:=(.*))?$/;
  * own flag spec parses it. `upt <command> --help` prints that command.
  */
 const NO_JSON_VERBS = new Set(['help', '--help', '-h', 'version', '--version', '-v']);
+/** Run one `upt` invocation and return its exit code. */
 export async function runCli(argv, io = defaultIo) {
     const files = {};
     let json = false;
@@ -127,7 +141,7 @@ async function dispatch(argv, io) {
             if (!explainCmd) {
                 throw new CliError("upt: the demo needs the 'explain' command, which is not registered yet");
             }
-            const explainArgs = parseArgs('explain', ['hawking-temperature', 'mass=1.989e30'], explainCmd.flags);
+            const explainArgs = parseArgs('explain', ['hawking-temperature', 'mass=1.989e30'], explainCmd.flags, explainCmd.positionals);
             const explainCtx = { args: explainArgs, api, out, err, write };
             const explainStatus = await explainCmd.run(explainCtx);
             if (explainStatus !== 0)
@@ -136,7 +150,7 @@ async function dispatch(argv, io) {
             if (!priorityCmd) {
                 throw new CliError("upt: the demo needs the 'priority' command, which is not registered yet");
             }
-            const priorityArgs = parseArgs('priority', [], priorityCmd.flags);
+            const priorityArgs = parseArgs('priority', [], priorityCmd.flags, priorityCmd.positionals);
             const priorityCtx = { args: priorityArgs, api, out, err, write };
             return await priorityCmd.run(priorityCtx);
         }
@@ -183,7 +197,9 @@ async function dispatch(argv, io) {
             out(command.help);
             return 0;
         }
-        const parsed = parseArgs(command.name, rest, command.flags);
+        // The parser refuses a positional past the command's declared arity (none when it
+        // declares none), so a token the command would not read never reaches `run`.
+        const parsed = parseArgs(command.name, rest, command.flags, command.positionals);
         const ctx = { args: parsed, api, out, err, write };
         return await command.run(ctx);
     }

package/dist/cli/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Verb-first dispatcher for the UPT CLI — `upt <command> [args...]`.\n *\n * Owns: top-level `help`/`version` handling, the no-args demo, unknown-verb\n * exit-2 contract, and per-command dispatch (parse -> run -> map thrown\n * UsageError/CliError to the documented exit codes). Individual commands are\n * plain data (see `command.ts`) registered via `registerCommand`; this file\n * never special-cases a command by name, so later tasks add commands without\n * touching `runCli`'s body.\n *\n * `main.ts` is the one place that imports the real `cli-api.js` barrel and\n * wires `out`/`err`/`write` to real stdio — every `Command.run` receives\n * those as an injected `CommandCtx`, never reaching for `process.*` itself,\n * which is what makes commands testable in-process against `dist/cli/*.js`.\n */\n\nimport * as api from '../cli-api.js';\nimport { UsageError, CliError } from './errors.js';\nimport { optionTokens, parseArgs } from './args.js';\nimport { packageVersion } from './version.js';\nimport { glossaryText } from './statuses.js';\nimport { listCommandNames, resolveCommand, type Command, type CommandCtx } from './command.js';\nimport { GLOBAL_FLAGS } from './flag-help.js';\nimport { renderTopLevelHelp } from './top-level-help.js';\nimport { recordInvocation, replayRecord, showRecord, type Io } from './record.js';\n// Side-effect import: registers every ported command (see commands/index.ts).\nimport './commands/index.js';\n\n// `Io` is the writer surface `runCli` needs. In production these wrap\n// `process.stdout`/`process.stderr` with exact `console.log`/`console.error`\n// semantics; tests pass a capturing stand-in as the optional second argument.\n\nfunction stdoutLine(line?: string): void {\n  process.stdout.write((line ?? '') + '\\n');\n}\n\nfunction stderrLine(line?: string): void {\n  process.stderr.write((line ?? '') + '\\n');\n}\n\nfunction stdoutRaw(s: string): void {\n  process.stdout.write(s);\n}\n\nconst defaultIo: Io = { out: stdoutLine, err: stderrLine, write: stdoutRaw };\n\nconst unknownCommandMessage = (name: string): string => `Unknown command '${name}'. See \\`upt help\\`.`;\n\nconst GLOBAL_FILE_OPTION = /^--(record|replay|show-record)(?:=(.*))?$/;\n\n/**\n * Verb-first CLI entry point. `argv` is the command + its arguments (NOT\n * `process.argv` — callers slice off the node/script prefix themselves, as\n * `bin/upt.mjs` did with `process.argv.slice(2)`).\n *\n * Leading `--record=FILE` / `--replay=FILE` / `--show-record=FILE` / `--json`\n * are global options. `--json` is moved onto the command so the command's\n * own flag spec parses it. `upt <command> --help` prints that command.\n */\nconst NO_JSON_VERBS = new Set(['help', '--help', '-h', 'version', '--version', '-v']);\n\nexport async function runCli(argv: string[], io: Io = defaultIo): Promise<number> {\n  const files: Partial<Record<'record' | 'replay' | 'show-record', string>> = {};\n  let json = false;\n  let i = 0;\n  try {\n    for (; i < argv.length; i++) {\n      const m = GLOBAL_FILE_OPTION.exec(argv[i]);\n      if (m) {\n        const name = m[1] as keyof typeof files;\n        if (!m[2]) throw new UsageError(`upt: '--${name}' requires '--${name}=FILE'`);\n        if (files[name] !== undefined) throw new UsageError(`upt: '--${name}' given more than once`);\n        files[name] = m[2];\n      } else if (argv[i] === '--json') {\n        if (json) throw new UsageError(`upt: '--json' given more than once`);\n        json = true;\n      } else {\n        break;\n      }\n    }\n    let rest = argv.slice(i);\n    if (json && (files.replay !== undefined || files['show-record'] !== undefined)) {\n      // `--replay` / `--show-record` consume --json themselves and take no command.\n    } else if (json) {\n      if (rest.length === 0) throw new UsageError(`upt: '--json' requires a command`);\n      const verb = rest[0]!;\n      if (NO_JSON_VERBS.has(verb)) throw new UsageError(`upt: '${verb}' does not take --json`);\n      rest = [verb, '--json', ...rest.slice(1)];\n    }\n    if (i === 0 && !json) return await dispatch(argv, io);\n    if (Object.keys(files).length > 1) {\n      throw new UsageError('upt: use one of --record, --replay and --show-record at a time');\n    }\n    if (files.record !== undefined) return await recordInvocation(files.record, rest, dispatch, io, api);\n    if (files.replay !== undefined || files['show-record'] !== undefined) {\n      if (rest.length > 0) {\n        throw new UsageError(`upt: '--${files.replay !== undefined ? 'replay' : 'show-record'}' takes no command (got '${rest[0]}')`);\n      }\n      if (files.replay !== undefined) return await replayRecord(files.replay, json, dispatch, io, api);\n      return showRecord(files['show-record']!, json, io);\n    }\n    return await dispatch(rest, io);\n  } catch (e) {\n    if (e instanceof UsageError) {\n      io.err(e.message);\n      return 2;\n    }\n    if (e instanceof CliError) {\n      io.err(e.message);\n      return 1;\n    }\n    throw e;\n  }\n}\n\nasync function dispatch(argv: string[], io: Io): Promise<number> {\n  const { out, err, write } = io;\n\n  try {\n    const [cmd, ...rest] = argv;\n\n    if (cmd === undefined) {\n      // Byte-identical to bin/upt.mjs's `case undefined` (lines 861-865): a\n      // banner line, then dispatch to the registered `explain` + `priority`\n      // commands with their historical demo arguments.\n      out('upt — bridge-inference CLI. Demo (run `upt help` for usage):');\n\n      const explainCmd = resolveCommand('explain');\n      if (!explainCmd) {\n        throw new CliError(\"upt: the demo needs the 'explain' command, which is not registered yet\");\n      }\n      const explainArgs = parseArgs('explain', ['hawking-temperature', 'mass=1.989e30'], explainCmd.flags);\n      const explainCtx: CommandCtx = { args: explainArgs, api, out, err, write };\n      const explainStatus = await explainCmd.run(explainCtx);\n      if (explainStatus !== 0) return explainStatus;\n\n      const priorityCmd = resolveCommand('priority');\n      if (!priorityCmd) {\n        throw new CliError(\"upt: the demo needs the 'priority' command, which is not registered yet\");\n      }\n      const priorityArgs = parseArgs('priority', [], priorityCmd.flags);\n      const priorityCtx: CommandCtx = { args: priorityArgs, api, out, err, write };\n      return await priorityCmd.run(priorityCtx);\n    }\n\n    if (cmd === 'help' || cmd === '--help' || cmd === '-h') {\n      if (rest.length > 1) throw new UsageError('upt help takes at most one command name');\n      // `upt help -h` and `upt help --help` ask for the command list, as `upt help` does.\n      const target = rest[0] === '--help' || rest[0] === '-h' ? undefined : rest[0];\n      if (target === 'statuses') {\n        out(glossaryText());\n        return 0;\n      }\n      if (target !== undefined) {\n        const command = resolveCommand(target);\n        if (!command) throw new UsageError(unknownCommandMessage(target));\n        out(command.help);\n        return 0;\n      }\n      const commands: Command[] = [];\n      for (const name of listCommandNames()) {\n        const command = resolveCommand(name);\n        if (command !== undefined) commands.push(command);\n      }\n      out(renderTopLevelHelp(commands, GLOBAL_FLAGS));\n      return 0;\n    }\n\n    if (cmd === 'version' || cmd === '--version' || cmd === '-v') {\n      if (rest.length > 0) throw new UsageError('upt version takes no arguments');\n      out(packageVersion());\n      return 0;\n    }\n\n    const command = resolveCommand(cmd);\n    if (!command) {\n      err(unknownCommandMessage(cmd));\n      return 2;\n    }\n\n    // `-h` is `--help` on every command, as the global help says. A token after a\n    // bare `--` is a positional, so it is not read as the help request.\n    const options = optionTokens(rest);\n    if (options.includes('--help') || options.includes('-h')) {\n      out(command.help);\n      return 0;\n    }\n\n    const parsed = parseArgs(command.name, rest, command.flags);\n    const ctx: CommandCtx = { args: parsed, api, out, err, write };\n    return await command.run(ctx);\n  } catch (e) {\n    if (e instanceof UsageError) {\n      err(e.message);\n      return 2;\n    }\n    if (e instanceof CliError) {\n      err(e.message);\n      return 1;\n    }\n    throw e;\n  }\n}\n"]}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,GAAG,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAiC,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU,EAAW,MAAM,aAAa,CAAC;AAClF,8EAA8E;AAC9E,OAAO,qBAAqB,CAAC;AAE7B,sEAAsE;AACtE,6EAA6E;AAC7E,8EAA8E;AAE9E,SAAS,UAAU,CAAC,IAAa;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,UAAU,CAAC,IAAa;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,SAAS,GAAO,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAE7E,0FAA0F;AAC1F,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,EAAE,GAAoB,SAAS;IACjF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/F,EAAE,CAAC,GAAG,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;IAC1C,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,qBAAqB,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,oBAAoB,IAAI,sBAAsB,CAAC;AAEvG,MAAM,kBAAkB,GAAG,2CAA2C,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;AAEtF,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc,EAAE,EAAE,GAAO,SAAS;IAC7D,MAAM,KAAK,GAAiE,EAAE,CAAC;IAC/E,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAuB,CAAC;gBACxC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;oBAAE,MAAM,IAAI,UAAU,CAAC,WAAW,IAAI,iBAAiB,IAAI,QAAQ,CAAC,CAAC;gBAC9E,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS;oBAAE,MAAM,IAAI,UAAU,CAAC,WAAW,IAAI,wBAAwB,CAAC,CAAC;gBAC7F,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC;iBAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAChC,IAAI,IAAI;oBAAE,MAAM,IAAI,UAAU,CAAC,oCAAoC,CAAC,CAAC;gBACrE,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;YAC/E,8EAA8E;QAChF,CAAC;aAAM,IAAI,IAAI,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,kCAAkC,CAAC,CAAC;YAChF,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;YACtB,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,SAAS,IAAI,wBAAwB,CAAC,CAAC;YACzF,IAAI,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,UAAU,CAAC,gEAAgE,CAAC,CAAC;QACzF,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACrG,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;YACrE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,UAAU,CAAC,WAAW,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,4BAA4B,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAChI,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YACjG,OAAO,UAAU,CAAC,KAAK,CAAC,aAAa,CAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;YAC5B,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAClB,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC;YAC1B,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAClB,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,IAAc,EAAE,EAAM;IAC5C,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAE/B,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAE5B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,sEAAsE;YACtE,sEAAsE;YACtE,iDAAiD;YACjD,GAAG,CAAC,8DAA8D,CAAC,CAAC;YAEpE,MAAM,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,IAAI,QAAQ,CAAC,wEAAwE,CAAC,CAAC;YAC/F,CAAC;YACD,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;YAC7H,MAAM,UAAU,GAAe,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;YAC3E,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACvD,IAAI,aAAa,KAAK,CAAC;gBAAE,OAAO,aAAa,CAAC;YAE9C,MAAM,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;YAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,IAAI,QAAQ,CAAC,yEAAyE,CAAC,CAAC;YAChG,CAAC;YACD,MAAM,YAAY,GAAG,SAAS,CAAC,UAAU,EAAE,EAAE,EAAE,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;YAC3F,MAAM,WAAW,GAAe,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;YAC7E,OAAO,MAAM,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACvD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;YACrF,oFAAoF;YACpF,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9E,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC1B,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;gBACpB,OAAO,CAAC,CAAC;YACX,CAAC;YACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;gBACvC,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,UAAU,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;gBAClE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAClB,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,EAAE,CAAC;gBACtC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;gBACrC,IAAI,OAAO,KAAK,SAAS;oBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACpD,CAAC;YACD,GAAG,CAAC,kBAAkB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;YAChD,OAAO,CAAC,CAAC;QACX,CAAC;QAED,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC7D,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,IAAI,UAAU,CAAC,gCAAgC,CAAC,CAAC;YAC5E,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;YAChC,OAAO,CAAC,CAAC;QACX,CAAC;QAED,8EAA8E;QAC9E,oEAAoE;QACpE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,CAAC,CAAC;QACX,CAAC;QAED,kFAAkF;QAClF,6EAA6E;QAC7E,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;QACjF,MAAM,GAAG,GAAe,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/D,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,UAAU,EAAE,CAAC;YAC5B,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACf,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,YAAY,QAAQ,EAAE,CAAC;YAC1B,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACf,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC","sourcesContent":["/**\n * Verb-first dispatcher for the UPT CLI — `upt <command> [args...]`.\n *\n * Owns: top-level `help`/`version` handling, the no-args demo, unknown-verb\n * exit-2 contract, and per-command dispatch (parse -> run -> map thrown\n * UsageError/CliError to the documented exit codes). Individual commands are\n * plain data (see `command.ts`) registered via `registerCommand`; this file\n * never special-cases a command by name, so later tasks add commands without\n * touching `runCli`'s body.\n *\n * `main.ts` is the one place that imports the real `cli-api.js` barrel and\n * wires `out`/`err`/`write` to real stdio — every `Command.run` receives\n * those as an injected `CommandCtx`, never reaching for `process.*` itself,\n * which is what makes commands testable in-process against `dist/cli/*.js`.\n */\n\nimport * as api from '../cli-api.js';\nimport { UsageError, CliError } from './errors.js';\nimport { optionTokens, parseArgs } from './args.js';\nimport { packageVersion } from './version.js';\nimport { glossaryText } from './statuses.js';\nimport { listCommandNames, resolveCommand, type Command, type CommandCtx } from './command.js';\nimport { GLOBAL_FLAGS } from './flag-help.js';\nimport { renderTopLevelHelp } from './top-level-help.js';\nimport { recordInvocation, replayRecord, showRecord, type Io } from './record.js';\n// Side-effect import: registers every ported command (see commands/index.ts).\nimport './commands/index.js';\n\n// `Io` is the writer surface `runCli` needs. In production these wrap\n// `process.stdout`/`process.stderr` with exact `console.log`/`console.error`\n// semantics; tests pass a capturing stand-in as the optional second argument.\n\nfunction stdoutLine(line?: string): void {\n  process.stdout.write((line ?? '') + '\\n');\n}\n\nfunction stderrLine(line?: string): void {\n  process.stderr.write((line ?? '') + '\\n');\n}\n\nfunction stdoutRaw(s: string): void {\n  process.stdout.write(s);\n}\n\nconst defaultIo: Io = { out: stdoutLine, err: stderrLine, write: stdoutRaw };\n\n/** EX_SOFTWARE (sysexits.h): the exit code of a defect, an error `runCli` did not map. */\nconst EX_SOFTWARE = 70;\n\n/**\n * The last-resort handler `bin/upt.mjs` calls when `runCli` rethrows: a defect, since every\n * usage error and value refusal was mapped to an exit code inside `runCli`. Prints one line,\n * `upt: internal error: <message>` (the message, not the stack), and returns 70 (EX_SOFTWARE).\n * A thrown value that is not an Error, or an Error with no message, prints as its string.\n */\nexport function reportInternalError(error: unknown, io: Pick<Io, 'err'> = defaultIo): number {\n  const message = error instanceof Error && error.message !== '' ? error.message : String(error);\n  io.err(`upt: internal error: ${message}`);\n  return EX_SOFTWARE;\n}\n\nconst unknownCommandMessage = (name: string): string => `Unknown command '${name}'. See \\`upt help\\`.`;\n\nconst GLOBAL_FILE_OPTION = /^--(record|replay|show-record)(?:=(.*))?$/;\n\n/**\n * Verb-first CLI entry point. `argv` is the command + its arguments (NOT\n * `process.argv` — callers slice off the node/script prefix themselves, as\n * `bin/upt.mjs` did with `process.argv.slice(2)`).\n *\n * Leading `--record=FILE` / `--replay=FILE` / `--show-record=FILE` / `--json`\n * are global options. `--json` is moved onto the command so the command's\n * own flag spec parses it. `upt <command> --help` prints that command.\n */\nconst NO_JSON_VERBS = new Set(['help', '--help', '-h', 'version', '--version', '-v']);\n\n/** Run one `upt` invocation and return its exit code. */\nexport async function runCli(argv: string[], io: Io = defaultIo): Promise<number> {\n  const files: Partial<Record<'record' | 'replay' | 'show-record', string>> = {};\n  let json = false;\n  let i = 0;\n  try {\n    for (; i < argv.length; i++) {\n      const m = GLOBAL_FILE_OPTION.exec(argv[i]);\n      if (m) {\n        const name = m[1] as keyof typeof files;\n        if (!m[2]) throw new UsageError(`upt: '--${name}' requires '--${name}=FILE'`);\n        if (files[name] !== undefined) throw new UsageError(`upt: '--${name}' given more than once`);\n        files[name] = m[2];\n      } else if (argv[i] === '--json') {\n        if (json) throw new UsageError(`upt: '--json' given more than once`);\n        json = true;\n      } else {\n        break;\n      }\n    }\n    let rest = argv.slice(i);\n    if (json && (files.replay !== undefined || files['show-record'] !== undefined)) {\n      // `--replay` / `--show-record` consume --json themselves and take no command.\n    } else if (json) {\n      if (rest.length === 0) throw new UsageError(`upt: '--json' requires a command`);\n      const verb = rest[0]!;\n      if (NO_JSON_VERBS.has(verb)) throw new UsageError(`upt: '${verb}' does not take --json`);\n      rest = [verb, '--json', ...rest.slice(1)];\n    }\n    if (i === 0 && !json) return await dispatch(argv, io);\n    if (Object.keys(files).length > 1) {\n      throw new UsageError('upt: use one of --record, --replay and --show-record at a time');\n    }\n    if (files.record !== undefined) return await recordInvocation(files.record, rest, dispatch, io, api);\n    if (files.replay !== undefined || files['show-record'] !== undefined) {\n      if (rest.length > 0) {\n        throw new UsageError(`upt: '--${files.replay !== undefined ? 'replay' : 'show-record'}' takes no command (got '${rest[0]}')`);\n      }\n      if (files.replay !== undefined) return await replayRecord(files.replay, json, dispatch, io, api);\n      return showRecord(files['show-record']!, json, io);\n    }\n    return await dispatch(rest, io);\n  } catch (e) {\n    if (e instanceof UsageError) {\n      io.err(e.message);\n      return 2;\n    }\n    if (e instanceof CliError) {\n      io.err(e.message);\n      return 1;\n    }\n    throw e;\n  }\n}\n\nasync function dispatch(argv: string[], io: Io): Promise<number> {\n  const { out, err, write } = io;\n\n  try {\n    const [cmd, ...rest] = argv;\n\n    if (cmd === undefined) {\n      // Byte-identical to bin/upt.mjs's `case undefined` (lines 861-865): a\n      // banner line, then dispatch to the registered `explain` + `priority`\n      // commands with their historical demo arguments.\n      out('upt — bridge-inference CLI. Demo (run `upt help` for usage):');\n\n      const explainCmd = resolveCommand('explain');\n      if (!explainCmd) {\n        throw new CliError(\"upt: the demo needs the 'explain' command, which is not registered yet\");\n      }\n      const explainArgs = parseArgs('explain', ['hawking-temperature', 'mass=1.989e30'], explainCmd.flags, explainCmd.positionals);\n      const explainCtx: CommandCtx = { args: explainArgs, api, out, err, write };\n      const explainStatus = await explainCmd.run(explainCtx);\n      if (explainStatus !== 0) return explainStatus;\n\n      const priorityCmd = resolveCommand('priority');\n      if (!priorityCmd) {\n        throw new CliError(\"upt: the demo needs the 'priority' command, which is not registered yet\");\n      }\n      const priorityArgs = parseArgs('priority', [], priorityCmd.flags, priorityCmd.positionals);\n      const priorityCtx: CommandCtx = { args: priorityArgs, api, out, err, write };\n      return await priorityCmd.run(priorityCtx);\n    }\n\n    if (cmd === 'help' || cmd === '--help' || cmd === '-h') {\n      if (rest.length > 1) throw new UsageError('upt help takes at most one command name');\n      // `upt help -h` and `upt help --help` ask for the command list, as `upt help` does.\n      const target = rest[0] === '--help' || rest[0] === '-h' ? undefined : rest[0];\n      if (target === 'statuses') {\n        out(glossaryText());\n        return 0;\n      }\n      if (target !== undefined) {\n        const command = resolveCommand(target);\n        if (!command) throw new UsageError(unknownCommandMessage(target));\n        out(command.help);\n        return 0;\n      }\n      const commands: Command[] = [];\n      for (const name of listCommandNames()) {\n        const command = resolveCommand(name);\n        if (command !== undefined) commands.push(command);\n      }\n      out(renderTopLevelHelp(commands, GLOBAL_FLAGS));\n      return 0;\n    }\n\n    if (cmd === 'version' || cmd === '--version' || cmd === '-v') {\n      if (rest.length > 0) throw new UsageError('upt version takes no arguments');\n      out(packageVersion());\n      return 0;\n    }\n\n    const command = resolveCommand(cmd);\n    if (!command) {\n      err(unknownCommandMessage(cmd));\n      return 2;\n    }\n\n    // `-h` is `--help` on every command, as the global help says. A token after a\n    // bare `--` is a positional, so it is not read as the help request.\n    const options = optionTokens(rest);\n    if (options.includes('--help') || options.includes('-h')) {\n      out(command.help);\n      return 0;\n    }\n\n    // The parser refuses a positional past the command's declared arity (none when it\n    // declares none), so a token the command would not read never reaches `run`.\n    const parsed = parseArgs(command.name, rest, command.flags, command.positionals);\n    const ctx: CommandCtx = { args: parsed, api, out, err, write };\n    return await command.run(ctx);\n  } catch (e) {\n    if (e instanceof UsageError) {\n      err(e.message);\n      return 2;\n    }\n    if (e instanceof CliError) {\n      err(e.message);\n      return 1;\n    }\n    throw e;\n  }\n}\n"]}

package/dist/cli/numeric-flag.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The integer a flag was given, or a `UsageError` naming the flag and the token.
+ * `command` is the command word for the message (`''` for an option of upt itself);
+ * `label` names the flag (`--max-routes`, or `--sweep sample count` for one field of a value).
+ */
+export declare function integerFlag(command: string, label: string, raw: string): number;
+/**
+ * The real number a flag was given, or a `UsageError` naming the flag and the token. The
+ * arguments are {@link integerFlag}'s. An exponent is a decimal form (`1e-3`); hex is not.
+ */
+export declare function realFlag(command: string, label: string, raw: string): number;
+//# sourceMappingURL=numeric-flag.d.ts.map

package/dist/cli/numeric-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-flag.d.ts","sourceRoot":"","sources":["../../src/cli/numeric-flag.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAO5E"}

package/dist/cli/numeric-flag.js

@@ -0,0 +1,44 @@
+/**
+ * The one reader of a numeric flag value for the UPT CLI.
+ *
+ * `Number()` accepts hex (`0x10`), binary, octal, an exponent on an integer (`1e1`), and reads
+ * `''` and whitespace as 0, so a flag read through it took a value the user did not type
+ * (`upt map --max-routes=0x10` ran with 16). An integer flag is digits with an optional sign; a
+ * real flag is a decimal with an optional fraction and exponent, the AST's one literal rule
+ * (`DECIMAL_LITERAL`, `src/dimensional/ast-leaves.ts`). A token outside the grammar is
+ * a malformed invocation (`UsageError`, exit 2) naming the flag and the token; a well-formed
+ * value outside the flag's range is the command's own value refusal (exit 1), judged after.
+ *
+ * @module cli/numeric-flag
+ * @internal
+ */
+import { DECIMAL_LITERAL } from '../dimensional/ast-leaves.js';
+import { UsageError } from './errors.js';
+/** `3`, `-2`, `+7`, `010`: digits with an optional sign, nothing else. */
+const INTEGER = /^[+-]?\d+$/;
+/** The help pointer, worded as the parser's unknown-flag message words it. */
+function hint(command) {
+    return command === '' ? 'see upt help' : `see upt help ${command.split(' ')[0]}`;
+}
+/**
+ * The integer a flag was given, or a `UsageError` naming the flag and the token.
+ * `command` is the command word for the message (`''` for an option of upt itself);
+ * `label` names the flag (`--max-routes`, or `--sweep sample count` for one field of a value).
+ */
+export function integerFlag(command, label, raw) {
+    if (!INTEGER.test(raw)) {
+        throw new UsageError(`upt${command === '' ? '' : ` ${command}`}: ${label} '${raw}' is not an integer (digits only, such as 3 or -2; ${hint(command)})`);
+    }
+    return Number(raw);
+}
+/**
+ * The real number a flag was given, or a `UsageError` naming the flag and the token. The
+ * arguments are {@link integerFlag}'s. An exponent is a decimal form (`1e-3`); hex is not.
+ */
+export function realFlag(command, label, raw) {
+    if (!DECIMAL_LITERAL.test(raw)) {
+        throw new UsageError(`upt${command === '' ? '' : ` ${command}`}: ${label} '${raw}' is not a number (a decimal such as 2, 0.5 or 1e-3; ${hint(command)})`);
+    }
+    return Number(raw);
+}
+//# sourceMappingURL=numeric-flag.js.map

package/dist/cli/numeric-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric-flag.js","sourceRoot":"","sources":["../../src/cli/numeric-flag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,0EAA0E;AAC1E,MAAM,OAAO,GAAG,YAAY,CAAC;AAE7B,8EAA8E;AAC9E,SAAS,IAAI,CAAC,OAAe;IAC3B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,KAAa,EAAE,GAAW;IACrE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,UAAU,CAClB,MAAM,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,KAAK,KAAK,KAAK,GAAG,sDAAsD,IAAI,CAAC,OAAO,CAAC,GAAG,CAClI,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,KAAa,EAAE,GAAW;IAClE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAClB,MAAM,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,KAAK,KAAK,KAAK,GAAG,wDAAwD,IAAI,CAAC,OAAO,CAAC,GAAG,CACpI,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC","sourcesContent":["/**\n * The one reader of a numeric flag value for the UPT CLI.\n *\n * `Number()` accepts hex (`0x10`), binary, octal, an exponent on an integer (`1e1`), and reads\n * `''` and whitespace as 0, so a flag read through it took a value the user did not type\n * (`upt map --max-routes=0x10` ran with 16). An integer flag is digits with an optional sign; a\n * real flag is a decimal with an optional fraction and exponent, the AST's one literal rule\n * (`DECIMAL_LITERAL`, `src/dimensional/ast-leaves.ts`). A token outside the grammar is\n * a malformed invocation (`UsageError`, exit 2) naming the flag and the token; a well-formed\n * value outside the flag's range is the command's own value refusal (exit 1), judged after.\n *\n * @module cli/numeric-flag\n * @internal\n */\nimport { DECIMAL_LITERAL } from '../dimensional/ast-leaves.js';\nimport { UsageError } from './errors.js';\n\n/** `3`, `-2`, `+7`, `010`: digits with an optional sign, nothing else. */\nconst INTEGER = /^[+-]?\\d+$/;\n\n/** The help pointer, worded as the parser's unknown-flag message words it. */\nfunction hint(command: string): string {\n  return command === '' ? 'see upt help' : `see upt help ${command.split(' ')[0]}`;\n}\n\n/**\n * The integer a flag was given, or a `UsageError` naming the flag and the token.\n * `command` is the command word for the message (`''` for an option of upt itself);\n * `label` names the flag (`--max-routes`, or `--sweep sample count` for one field of a value).\n */\nexport function integerFlag(command: string, label: string, raw: string): number {\n  if (!INTEGER.test(raw)) {\n    throw new UsageError(\n      `upt${command === '' ? '' : ` ${command}`}: ${label} '${raw}' is not an integer (digits only, such as 3 or -2; ${hint(command)})`,\n    );\n  }\n  return Number(raw);\n}\n\n/**\n * The real number a flag was given, or a `UsageError` naming the flag and the token. The\n * arguments are {@link integerFlag}'s. An exponent is a decimal form (`1e-3`); hex is not.\n */\nexport function realFlag(command: string, label: string, raw: string): number {\n  if (!DECIMAL_LITERAL.test(raw)) {\n    throw new UsageError(\n      `upt${command === '' ? '' : ` ${command}`}: ${label} '${raw}' is not a number (a decimal such as 2, 0.5 or 1e-3; ${hint(command)})`,\n    );\n  }\n  return Number(raw);\n}\n"]}

package/dist/cli/output.d.ts

@@ -7,7 +7,27 @@
  * deep-copies a value into a JSON-safe shape first, encoding NaN/Infinity
  * as explicit strings so round-tripping through JSON preserves them.
  */
+import { UsageError, type CliError } from './errors.js';
 import type { AnchorScope } from './graphs.js';
+/**
+ * The `--json` form of a refusal: no `result`; the error's kind (`usage` for a malformed
+ * invocation, `value` for a value the command refuses), the exit code the process returns,
+ * and the message the text mode prints on stderr.
+ */
+export interface JsonErrorEnvelope {
+    command: string;
+    error: {
+        kind: 'usage' | 'value';
+        exitCode: 1 | 2;
+        message: string;
+    };
+}
+/**
+ * Write a refusal as a JSON envelope on stdout and return the exit code it stands for: 2 for a
+ * `UsageError`, 1 for a `CliError`. A command that answers in JSON calls this instead of
+ * letting the dispatcher print the message on stderr, so a JSON consumer reads one stream.
+ */
+export declare function emitJsonError(command: string, e: UsageError | CliError, write?: (s: string) => void): 1 | 2;
 /** The shape of every `--json` output: the command, what it read, and its result. */
 export interface JsonEnvelope {
     command: string;
@@ -38,6 +58,14 @@ export interface JsonEnvelope {
      */
     compositionRecovery?: unknown;
 }
+/**
+ * Make a value JSON-safe. NaN and infinite numbers become strings.
+ * A function is omitted from an object and becomes null in an array.
+ */
 export declare function sanitize(v: unknown): unknown;
+/**
+ * Write the `--json` envelope of one command to `write`.
+ * The status definitions of the command are added when it has any.
+ */
 export declare function emitJson(env: JsonEnvelope, write?: (s: string) => void): void;
 //# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;IACpD,4GAA4G;IAC5G,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,gHAAgH;IAChH,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,4GAA4G;IAC5G,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA2C5C;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAqC,GAAG,IAAI,CAK7G"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,CAAC,EAAE,UAAU,GAAG,QAAQ,EACxB,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAqC,GAC1D,CAAC,GAAG,CAAC,CAQP;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;IACpD,4GAA4G;IAC5G,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,gHAAgH;IAChH,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,4GAA4G;IAC5G,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA2C5C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAqC,GAAG,IAAI,CAK7G"}

package/dist/cli/output.js

@@ -8,6 +8,25 @@
  * as explicit strings so round-tripping through JSON preserves them.
  */
 import { definitionsFor } from './statuses.js';
+import { UsageError } from './errors.js';
+/**
+ * Write a refusal as a JSON envelope on stdout and return the exit code it stands for: 2 for a
+ * `UsageError`, 1 for a `CliError`. A command that answers in JSON calls this instead of
+ * letting the dispatcher print the message on stderr, so a JSON consumer reads one stream.
+ */
+export function emitJsonError(command, e, write = (s) => process.stdout.write(s)) {
+    const usage = e instanceof UsageError;
+    const envelope = {
+        command,
+        error: { kind: usage ? 'usage' : 'value', exitCode: usage ? 2 : 1, message: e.message },
+    };
+    write(JSON.stringify(envelope, null, 2) + '\n');
+    return envelope.error.exitCode;
+}
+/**
+ * Make a value JSON-safe. NaN and infinite numbers become strings.
+ * A function is omitted from an object and becomes null in an array.
+ */
 export function sanitize(v) {
     if (typeof v === 'number') {
         if (Number.isNaN(v))
@@ -52,6 +71,10 @@ export function sanitize(v) {
     }
     return v;
 }
+/**
+ * Write the `--json` envelope of one command to `write`.
+ * The status definitions of the command are added when it has any.
+ */
 export function emitJson(env, write = (s) => process.stdout.write(s)) {
     const definitions = definitionsFor(env.command);
     const { result, ...head } = env;

package/dist/cli/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAkC/C,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAClC,IAAI,CAAC,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,QAAQ;YAAE,OAAO,WAAW,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;QAC5B,wEAAwE;QACxE,uEAAuE;QACvE,6CAA6C;QAC7C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,GAAG,GAAc,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjC,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,SAAS;YAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,SAAS;YACjE,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAiB,EAAE,KAAK,GAAwB,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACrG,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1F,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACxD,CAAC","sourcesContent":["/**\n * JSON output envelope for the UPT CLI.\n *\n * Physics results genuinely contain non-finite numbers (e.g. `anchoring:\n * Infinity` in the priority board). `JSON.stringify` silently turns those\n * into `null`, which is indistinguishable from an absent value. `sanitize`\n * deep-copies a value into a JSON-safe shape first, encoding NaN/Infinity\n * as explicit strings so round-tripping through JSON preserves them.\n */\n\nimport { definitionsFor } from './statuses.js';\nimport type { AnchorScope } from './graphs.js';\n\n/** The shape of every `--json` output: the command, what it read, and its result. */\nexport interface JsonEnvelope {\n  command: string;\n  /**\n   * The graph a command read. `'atlas'` is `upt map --route` / `--family`,\n   * which read the atlas families rather than an equation graph.\n   */\n  source?: 'catalog' | 'canonical' | 'both' | 'atlas';\n  /** What the result is anchored to (audit I3): the discovery ground truth, the established core, or both. */\n  anchor?: AnchorScope;\n  options?: Record<string, unknown>;\n  epistemics?: string;\n  /** `upt confront` — count of confrontations by rigor tier (stringent/moderate/loose). */\n  rigorDistribution?: Record<string, number>;\n  /** `upt confront` — count of confrontations by statistical object (σ-test, limit, consistency ratio, table). */\n  statisticDistribution?: Record<string, number>;\n  /** `upt confront` — preprocessing and independence counts, recorded vs not recorded, each counted apart. */\n  dataHandlingDistribution?: Record<string, Record<string, number>>;\n  /**\n   * The meaning of each status the command can emit, from STATUS_GLOSSARY (audit I13). `emitJson`\n   * fills it in; a command never sets it.\n   */\n  definitions?: Record<string, string>;\n  result: unknown;\n  /**\n   * `upt recover` — two-edge symbolic chains examined against the canonical\n   * registry, and the structural matches. A chain is never restates-canonical.\n   */\n  compositionRecovery?: unknown;\n}\n\nexport function sanitize(v: unknown): unknown {\n  if (typeof v === 'number') {\n    if (Number.isNaN(v)) return 'NaN';\n    if (v === Infinity) return 'Infinity';\n    if (v === -Infinity) return '-Infinity';\n    return v;\n  }\n\n  if (typeof v === 'function') {\n    // Caller decides how to represent \"no value here\" (omit vs. null) based\n    // on context (object key vs. array slot); signal via undefined and let\n    // the array/object branches below handle it.\n    return undefined;\n  }\n\n  if (Array.isArray(v)) {\n    const out: unknown[] = [];\n    for (const item of v) {\n      const sanitized = sanitize(item);\n      out.push(typeof item === 'function' ? null : sanitized);\n    }\n    return out;\n  }\n\n  if (v instanceof Map) {\n    const out: Record<string, unknown> = {};\n    for (const [key, value] of v) {\n      if (typeof value === 'function') continue;\n      out[String(key)] = sanitize(value);\n    }\n    return out;\n  }\n\n  if (v !== null && typeof v === 'object') {\n    const out: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(v)) {\n      if (value === undefined || typeof value === 'function') continue;\n      out[key] = sanitize(value);\n    }\n    return out;\n  }\n\n  return v;\n}\n\nexport function emitJson(env: JsonEnvelope, write: (s: string) => void = (s) => process.stdout.write(s)): void {\n  const definitions = definitionsFor(env.command);\n  const { result, ...head } = env;\n  const full = Object.keys(definitions).length > 0 ? { ...head, definitions, result } : env;\n  write(JSON.stringify(sanitize(full), null, 2) + '\\n');\n}\n"]}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * JSON output envelope for the UPT CLI.\n *\n * Physics results genuinely contain non-finite numbers (e.g. `anchoring:\n * Infinity` in the priority board). `JSON.stringify` silently turns those\n * into `null`, which is indistinguishable from an absent value. `sanitize`\n * deep-copies a value into a JSON-safe shape first, encoding NaN/Infinity\n * as explicit strings so round-tripping through JSON preserves them.\n */\n\nimport { definitionsFor } from './statuses.js';\nimport { UsageError, type CliError } from './errors.js';\nimport type { AnchorScope } from './graphs.js';\n\n/**\n * The `--json` form of a refusal: no `result`; the error's kind (`usage` for a malformed\n * invocation, `value` for a value the command refuses), the exit code the process returns,\n * and the message the text mode prints on stderr.\n */\nexport interface JsonErrorEnvelope {\n  command: string;\n  error: { kind: 'usage' | 'value'; exitCode: 1 | 2; message: string };\n}\n\n/**\n * Write a refusal as a JSON envelope on stdout and return the exit code it stands for: 2 for a\n * `UsageError`, 1 for a `CliError`. A command that answers in JSON calls this instead of\n * letting the dispatcher print the message on stderr, so a JSON consumer reads one stream.\n */\nexport function emitJsonError(\n  command: string,\n  e: UsageError | CliError,\n  write: (s: string) => void = (s) => process.stdout.write(s),\n): 1 | 2 {\n  const usage = e instanceof UsageError;\n  const envelope: JsonErrorEnvelope = {\n    command,\n    error: { kind: usage ? 'usage' : 'value', exitCode: usage ? 2 : 1, message: e.message },\n  };\n  write(JSON.stringify(envelope, null, 2) + '\\n');\n  return envelope.error.exitCode;\n}\n\n/** The shape of every `--json` output: the command, what it read, and its result. */\nexport interface JsonEnvelope {\n  command: string;\n  /**\n   * The graph a command read. `'atlas'` is `upt map --route` / `--family`,\n   * which read the atlas families rather than an equation graph.\n   */\n  source?: 'catalog' | 'canonical' | 'both' | 'atlas';\n  /** What the result is anchored to (audit I3): the discovery ground truth, the established core, or both. */\n  anchor?: AnchorScope;\n  options?: Record<string, unknown>;\n  epistemics?: string;\n  /** `upt confront` — count of confrontations by rigor tier (stringent/moderate/loose). */\n  rigorDistribution?: Record<string, number>;\n  /** `upt confront` — count of confrontations by statistical object (σ-test, limit, consistency ratio, table). */\n  statisticDistribution?: Record<string, number>;\n  /** `upt confront` — preprocessing and independence counts, recorded vs not recorded, each counted apart. */\n  dataHandlingDistribution?: Record<string, Record<string, number>>;\n  /**\n   * The meaning of each status the command can emit, from STATUS_GLOSSARY (audit I13). `emitJson`\n   * fills it in; a command never sets it.\n   */\n  definitions?: Record<string, string>;\n  result: unknown;\n  /**\n   * `upt recover` — two-edge symbolic chains examined against the canonical\n   * registry, and the structural matches. A chain is never restates-canonical.\n   */\n  compositionRecovery?: unknown;\n}\n\n/**\n * Make a value JSON-safe. NaN and infinite numbers become strings.\n * A function is omitted from an object and becomes null in an array.\n */\nexport function sanitize(v: unknown): unknown {\n  if (typeof v === 'number') {\n    if (Number.isNaN(v)) return 'NaN';\n    if (v === Infinity) return 'Infinity';\n    if (v === -Infinity) return '-Infinity';\n    return v;\n  }\n\n  if (typeof v === 'function') {\n    // Caller decides how to represent \"no value here\" (omit vs. null) based\n    // on context (object key vs. array slot); signal via undefined and let\n    // the array/object branches below handle it.\n    return undefined;\n  }\n\n  if (Array.isArray(v)) {\n    const out: unknown[] = [];\n    for (const item of v) {\n      const sanitized = sanitize(item);\n      out.push(typeof item === 'function' ? null : sanitized);\n    }\n    return out;\n  }\n\n  if (v instanceof Map) {\n    const out: Record<string, unknown> = {};\n    for (const [key, value] of v) {\n      if (typeof value === 'function') continue;\n      out[String(key)] = sanitize(value);\n    }\n    return out;\n  }\n\n  if (v !== null && typeof v === 'object') {\n    const out: Record<string, unknown> = {};\n    for (const [key, value] of Object.entries(v)) {\n      if (value === undefined || typeof value === 'function') continue;\n      out[key] = sanitize(value);\n    }\n    return out;\n  }\n\n  return v;\n}\n\n/**\n * Write the `--json` envelope of one command to `write`.\n * The status definitions of the command are added when it has any.\n */\nexport function emitJson(env: JsonEnvelope, write: (s: string) => void = (s) => process.stdout.write(s)): void {\n  const definitions = definitionsFor(env.command);\n  const { result, ...head } = env;\n  const full = Object.keys(definitions).length > 0 ? { ...head, definitions, result } : env;\n  write(JSON.stringify(sanitize(full), null, 2) + '\\n');\n}\n"]}

package/dist/cli/record-reach.js

@@ -18,7 +18,7 @@
  * The same import graph gives the modules the command loads. Each one's source is hashed, so a
  * change to a literal a module keeps private, which no constant table holds, is still named.
  */
-import { createHash } from 'node:crypto';
+import { sha256Hex } from '../core/hash.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { MODULE_EXT, SOURCE_ROOT, tableName } from './record-tables.js';
@@ -157,7 +157,7 @@ function loadedModules(command) {
  */
 export function sourceHash(file) {
     try {
-        return createHash('sha256').update(readFileSync(file)).digest('hex');
+        return sha256Hex(readFileSync(file));
     }
     catch (e) {
         const code = e instanceof Error && 'code' in e && typeof e.code === 'string' ? e.code : 'error';