@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/src/execution/error-details.js

@@ -0,0 +1,399 @@
+'use strict';
+
+const { executionFor } = require('./request-state');
+const { issueReasons } = require('./error-model');
+const { ParserError } = require('./parser-error');
+const contexts = new WeakMap();
+const reasons = new Set(issueReasons);
+const constraintKeys = ['type', 'enum', 'const', 'minimum', 'maximum', 'exclusiveMinimum',
+  'exclusiveMaximum', 'minLength', 'maxLength', 'minItems', 'maxItems', 'format', 'pattern'];
+const pointer = value => String(value).replaceAll('~', '~0').replaceAll('/', '~1');
+const segments = path => path.split('/').slice(1).map(value => value.replaceAll('~1', '/').replaceAll('~0', '~'));
+
+function resolveModel(schema, model) {
+  const seen = new Set();
+  while (model?.$ref?.startsWith('#/') && !seen.has(model.$ref)) {
+    seen.add(model.$ref);
+    model = segments(model.$ref.slice(1)).reduce((node, key) => node?.[key], schema);
+  }
+  return model;
+}
+
+function modelAt(schema, section, path) {
+  let model = resolveModel(schema, schema[section]);
+  for (const key of segments(path)) {
+    if (model?.properties && Object.hasOwn(model.properties, key)) model = model.properties[key];
+    else if ((model?.type === 'array' || (Array.isArray(model?.type) && model.type.includes('array'))) && /^(0|[1-9]\d*)$/.test(key)) model = model.items;
+    else return undefined;
+    model = resolveModel(schema, model);
+  }
+  return model;
+}
+
+function constraints(model) {
+  return Object.fromEntries(constraintKeys.filter(key => Object.hasOwn(model || {}, key))
+    .map(key => [key, structuredClone(model[key])]));
+}
+
+function validationIssues(errors, schema, section) {
+  const issues = [];
+  const seen = new Set();
+  const keywords = {
+    required: 'required', type: 'invalid_type', enum: 'invalid_choice', const: 'invalid_choice',
+    minimum: 'out_of_range', maximum: 'out_of_range', exclusiveMinimum: 'out_of_range',
+    exclusiveMaximum: 'out_of_range', minLength: 'out_of_range', maxLength: 'out_of_range',
+    minItems: 'out_of_range', maxItems: 'out_of_range', format: 'invalid_format',
+    pattern: 'invalid_format', dependencies: 'conditional_required',
+    additionalProperties: 'unexpected_property'
+  };
+  for (const error of errors) {
+    if (error.keyword === 'if') continue;
+    let path = error.instancePath;
+    let relatedPaths;
+    if (['required', 'dependencies'].includes(error.keyword)) {
+      path += `/${pointer(error.params.missingProperty)}`;
+      if (error.keyword === 'dependencies') {
+        relatedPaths = [`${error.instancePath}/${pointer(error.params.property)}`];
+      }
+    }
+    if (!modelAt(schema, section, path)) {
+      while (path && !modelAt(schema, section, path)) path = path.slice(0, path.lastIndexOf('/'));
+    }
+    const model = modelAt(schema, section, path);
+    if (!model) continue;
+    const issue = { source: section, path, reason: keywords[error.keyword] || 'constraint' };
+    const expected = constraints(model);
+    if (error.keyword === 'additionalProperties') expected.additionalProperties = false;
+    if (error.keyword === 'contains') {
+      const branch = resolveModel(schema, segments(error.schemaPath.slice(1))
+        .slice(0, -1).reduce((node, key) => node?.[key], schema[section]));
+      if (branch?.contains) expected.contains = structuredClone(branch.contains);
+    }
+    if (Object.keys(expected).length) issue.expected = expected;
+    if (relatedPaths) issue.relatedPaths = relatedPaths;
+    const key = JSON.stringify(issue);
+    if (!seen.has(key)) {
+      seen.add(key);
+      issues.push(issue);
+      if (issues.length > 16) return { issues: issues.slice(0, 16), issuesTruncated: true };
+    }
+  }
+  return { issues: issues.slice(0, 16), ...(issues.length > 16 ? { issuesTruncated: true } : {}) };
+}
+
+class CommandValueError extends Error {
+  constructor(section, errors, schema) {
+    super(`Invalid ${section}: ${[...new Set(errors.map(error => error.keyword))].join(', ')}`);
+    this.section = section;
+    Object.assign(this, validationIssues(errors, schema, section));
+  }
+}
+
+class InputIssueError extends Error {
+  constructor(issues) {
+    super('输入参数不符合要求');
+    this.section = 'input';
+    this.issues = issues;
+  }
+}
+
+function inputIssue(path, reason, expected, relatedPaths) {
+  return new InputIssueError([{ source: 'input', path, reason,
+    ...(expected ? { expected } : {}), ...(relatedPaths ? { relatedPaths } : {}) }]);
+}
+
+function withInputScope(scope, action) {
+  try { return action(); }
+  catch (error) {
+    if (error instanceof CommandValueError || error instanceof InputIssueError) error.inputScope = scope;
+    throw error;
+  }
+}
+
+function parseIntegerOption(raw, schema, path) {
+  const expected = constraints(modelAt(schema, 'input', path));
+  if (typeof raw !== 'string' || !/^(0|[1-9]\d*)$/.test(raw)) {
+    throw inputIssue(path, 'invalid_format', expected);
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < expected.minimum || value > expected.maximum) {
+    throw inputIssue(path, 'out_of_range', expected);
+  }
+  return value;
+}
+
+function copyErrorDetails(details, overrides = {}) {
+  const result = {};
+  for (const key of ['category', 'stage', 'command', 'targetScope', 'requestState', 'nextStep',
+    'issues', 'issuesTruncated', 'errorVersion', 'recovery', 'execution', 'suggestions', 'helpArgv']) {
+    if (Object.hasOwn(details, key)) result[key] = structuredClone(details[key]);
+  }
+  for (const key of ['businessCode', 'gatewayCode']) {
+    const value = details[key];
+    if (Number.isSafeInteger(value) || (typeof value === 'string' && /^-?\d{1,12}$/.test(value))) result[key] = value;
+  }
+  for (const key of ['trace_id', 'request_id']) {
+    if (typeof details[key] === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(details[key])) result[key] = details[key];
+  }
+  if (Number.isInteger(details.httpStatus) && details.httpStatus >= 100 && details.httpStatus <= 599) {
+    result.httpStatus = details.httpStatus;
+  }
+  if (Number.isSafeInteger(details.pageNo) && details.pageNo > 0) result.pageNo = details.pageNo;
+  if (typeof details.api === 'string' && /^[a-z][a-z0-9._-]*\/\d+\.\d+\.\d+$/.test(details.api)) result.api = details.api;
+  return Object.assign(result, overrides);
+}
+
+function bindError(error, context) {
+  if (error instanceof Error) {
+    contexts.set(error, context);
+    if (!error.cliDetails && ['input', 'argv'].includes(error.section)) {
+      error.cliDetails = {
+        category: context.parameterCategory, stage: 'input', command: context.path,
+        targetScope: error.inputScope || {}, requestState: 'not_sent',
+        nextStep: '按同版契约核对输入；恢复动作以最终错误诊断为准。'
+      };
+    }
+  }
+  return error;
+}
+
+function optionFor(path, context) {
+  let candidate = path;
+  while (candidate) {
+    const attribute = context.optionPaths?.[candidate] ||
+      (segments(candidate).length === 1 ? segments(candidate)[0] : undefined);
+    const option = context.command.options.find(value => value.attributeName() === attribute);
+    if (option) return option.long || option.short;
+    candidate = candidate.slice(0, candidate.lastIndexOf('/'));
+  }
+}
+
+function safeIssues(error, context) {
+  return (error.issues || error.cliDetails?.issues || []).slice(0, 16).flatMap(issue => {
+    if (!reasons.has(issue.reason) || !['argv', 'input', 'context', 'output', 'preview'].includes(issue.source)) return [];
+    if (issue.path !== undefined && (typeof issue.path !== 'string' ||
+      (issue.path !== '' && !issue.path.startsWith('/')) || !modelAt(context.schema,
+      ['argv', 'context'].includes(issue.source) ? 'input' : issue.source, issue.path))) return [];
+    const result = { source: issue.source, reason: issue.reason };
+    if (issue.path !== undefined) result.path = issue.path;
+    const option = issue.source === 'context' ? undefined :
+      issue.option && context.command.options.some(value =>
+        [value.long, value.short].includes(issue.option)) ? issue.option : optionFor(issue.path || '', context);
+    if (option) result.option = option;
+    if (issue.expected) result.expected = structuredClone(issue.expected);
+    if (issue.relatedPaths) result.relatedPaths = issue.relatedPaths.filter(path =>
+      modelAt(context.schema, 'input', path));
+    return [result];
+  });
+}
+
+const localContextMessages = Object.freeze({
+  context_missing: '执行前需要登录并选择店铺',
+  target_missing: '缺少目标店铺；请先登录选店，或在 --dry-run 中显式提供 --kdt-id',
+  context_invalid: '当前用户上下文无效，请检查 userId、hq、shopId 和 orgType',
+  requires_hq: '当前是店铺上下文，此命令只能在总部上下文执行。',
+  requires_shop: '当前是总部上下文，此命令只能在店铺上下文执行。'
+});
+
+function localContextReason(error, details, execution) {
+  return Object.hasOwn(localContextMessages, error.diagnosticReason || '') &&
+    ['configuration', 'permission'].includes(details.category) &&
+    ['context', 'configuration'].includes(details.stage) &&
+    execution.requestState === 'not_sent' && execution.coverage === 'complete' &&
+    execution.observedAttempts === 0 ? error.diagnosticReason : undefined;
+}
+
+function describeRecovery(details, execution, missingAuthentication = false, contextReason, responseReason) {
+  if (contextReason) return { action: 'stop_and_inspect', nextStep:
+    ['context_missing', 'target_missing'].includes(contextReason)
+      ? '未登录先执行 zan-saas auth login；登录后用 zan-saas shop list 和 zan-saas shop use <kdtId> 选店。缺少上下文时仅可显式指定店铺做 --dry-run，不自动切店或重放。'
+      : contextReason === 'context_invalid'
+        ? '检查上下文中的 userId、hq、shopId 和 orgType；不自动切店、换身份或重放。'
+        : '请核对本次目标所需的总部或店铺上下文；不自动切店、换身份或重放，权限仍由服务端校验。' };
+  if (execution.requestState === 'not_sent' && execution.coverage === 'complete' &&
+      execution.observedAttempts === 0 && ['input', 'validation'].includes(details.stage) &&
+      ['parameter', 'validation'].includes(details.category) &&
+      details.issues?.some(issue => ['argv', 'input'].includes(issue.source))) {
+    const fields = [...new Set(details.issues.map(issue => issue.option).filter(Boolean))].join('、');
+    return { action: 'correct_input',
+      nextStep: `按同版契约修正${fields || '输入参数'}；本次未发送请求，修正后可重新构造调用。` };
+  }
+  if (details.category === 'provider_unavailable' && details.command === 'privacy.field.decrypt') {
+    return { action: 'stop_and_inspect', nextStep: '当前仅支持离线预览，请加 --dry-run；真实解密服务尚未接入。' };
+  }
+  if (missingAuthentication || details.category === 'authentication') {
+    return { action: 'complete_authentication',
+      nextStep: '检查 zan-saas auth status --format json，按公共认证流程完成登录；不在聊天中提供凭证，不自动重放原调用。' };
+  }
+  if (gatewayAccessDenied(details)) {
+    return { action: 'request_access_review',
+      nextStep: '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查，不自动重放。' };
+  }
+  if (details.category === 'permission') {
+    return { action: 'request_access_review',
+      nextStep: '核对原账号、目标店铺与服务端授权，可提供脱敏接口及 trace_id 给管理员；不切店、换身份或自动重放。' };
+  }
+  if (details.stage === 'shop-binding' && execution.requestState === 'sent') {
+    return { action: 'stop_and_inspect',
+      nextStep: '店铺核验失败，后续业务请求尚未发送；本次已有核验请求记录，核对原店铺和凭证后停止，不自动切店或重放。' };
+  }
+  if (responseReason) return { action: 'stop_and_inspect',
+    nextStep: `${responseReason.nextStep} 不自动重放、切店或换身份。` };
+  if (details.requestState === 'sent' && details.category === 'business_rejected') {
+    return { action: 'stop_and_inspect',
+      nextStep: '接口已拒绝本次查询；将诊断中的 api、businessCode 或 gatewayCode、trace_id 提供给管理员核查服务端原因。错误码本身不能证明是权限或数据问题，不自动重放、切店或换身份。' };
+  }
+  if (details.requestState === 'sent' && details.category === 'protocol' &&
+      details.issues?.some(issue => issue.source === 'output')) {
+    return { action: 'stop_and_inspect',
+      nextStep: '接口已返回数据，但 issues 指出的字段不符合本命令契约；提供字段路径、预期类型及 api、trace_id 核查响应和适配，不将失败解释为空结果，不自动重放。' };
+  }
+  return { action: 'stop_and_inspect',
+    nextStep: execution.requestState === 'unknown' ?
+      '本次请求或业务结果可能未知，停止并核对脱敏诊断；不能视为未执行，不自动重放。' :
+      execution.observedAttempts ?
+        '本次已有请求发送，当前阶段状态见 requestState；停止并核对脱敏诊断，不把失败解释为空结果，不自动重放。' :
+        '核对本次上下文、配置及同版契约后停止处理；不自动切店、换身份或重放。' };
+}
+
+// Response adapters may select a reason only from the leaf's static, same-version contract.
+// Never use upstream free text as a diagnostic message or guess the original failure field.
+function declaredResponseReason(error, context, details, execution) {
+  const entries = context.schema.errors?.responseReasons;
+  const key = error.diagnosticReason;
+  if (typeof key !== 'string' || !entries || !Object.hasOwn(entries, key) ||
+      details.requestState !== 'sent' || execution.requestState !== 'sent' ||
+      execution.coverage !== 'complete' || execution.observedAttempts === 0) return undefined;
+  const reason = entries[key];
+  return reason && reason.category === details.category && reason.stage === details.stage &&
+    typeof reason.message === 'string' && typeof reason.nextStep === 'string' ? reason : undefined;
+}
+
+function businessRejectionMessage(details) {
+  const code = details.gatewayCode !== undefined ? `网关码 ${details.gatewayCode}` :
+    details.businessCode !== undefined ? `业务码 ${details.businessCode}` : undefined;
+  return `接口拒绝了本次查询${code ? `（${code}）` : ''}，已停止处理。`;
+}
+
+function gatewayAccessDenied(details) {
+  return details?.requestState === 'sent' &&
+    ['business_rejected', 'permission'].includes(details.category) &&
+    [4204, '4204'].includes(details.gatewayCode);
+}
+
+function finalizeError(error, registeredContext) {
+  if (error instanceof ParserError) return structuredClone(error.result);
+  const context = contexts.get(error) || registeredContext;
+  if (context?.schema.errors?.diagnosticsVersion !== 2) {
+    if (gatewayAccessDenied(error.cliDetails)) {
+      error.message = '网关拒绝访问：没有操作权限。';
+      error.cliDetails.nextStep = '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查。';
+    }
+    return { success: false, code: -10001, message: error.message,
+      ...(error.cliDetails ? { details: error.cliDetails } : {}) };
+  }
+  let execution = executionFor(error);
+  if (execution.requestState === 'not_sent' &&
+      ['sent', 'unknown'].includes(error.cliDetails?.requestState)) {
+    execution = { ...execution, requestState: 'unknown', coverage: 'partial' };
+  }
+  try {
+    return diagnosticError(error, context, execution);
+  } catch {
+    return { success: false, code: -10001, message: '命令执行失败，已停止处理',
+      details: {
+        category: 'protocol', stage: 'output-model', command: context.path, targetScope: {},
+        requestState: 'unknown', errorVersion: 2, execution,
+        recovery: { action: 'stop_and_inspect', automaticBusinessRetry: false },
+        nextStep: '诊断信息不符合本命令契约；停止核查，不推定未执行，不自动重放。'
+      } };
+  }
+}
+
+function issueMessage(issues) {
+  const first = issues.find(issue => issue.option);
+  if (!first) {
+    const parserMessages = { unknown_option: '命令中有不支持的选项，请查看此命令 --help',
+      unknown_command: '命令路径不支持，请查看 --help',
+      excess_arguments: '命令中有多余的位置参数，请查看此命令 --help',
+      required: '缺少必填参数，请查看此命令 --help' };
+    const parserIssue = issues.find(issue => issue.source === 'argv' && parserMessages[issue.reason]);
+    if (parserIssue) return parserMessages[parserIssue.reason];
+    return issues.find(issue => ['constraint', 'conditional_required'].includes(issue.reason) && issue.expected?.format)?.expected.format || '输入参数不符合要求';
+  }
+  const { option, reason, expected = {} } = first;
+  if (reason === 'required') return `请提供 ${option}`;
+  if (reason === 'missing_value') return `请为 ${option} 提供值`;
+  if (reason === 'out_of_range' && expected.minimum !== undefined && expected.maximum !== undefined) {
+    return `${option} 必须在 ${expected.minimum} 到 ${expected.maximum} 之间`;
+  }
+  if (expected.enum) return `${option} 只能使用：${expected.enum.join('、')}`;
+  if (expected.items?.enum) return `${option} 只能使用：${expected.items.enum.join('、')}；多个值用逗号分隔`;
+  if (reason === 'invalid_format' && expected.format) {
+    return `${option} 格式不正确：${expected.format}`;
+  }
+  if (['constraint', 'conditional_required'].includes(reason) && expected.format) return `${option}：${expected.format}`;
+  if (first.relatedPaths?.length) return `${option} 与其他参数组合不符合要求，请核对关联条件`;
+  return `${option} 不符合要求，请按 issues.expected 修正`;
+}
+
+function diagnosticError(error, context, execution) {
+  const inputError = ['input', 'argv'].includes(error.section);
+  const details = copyErrorDetails(error.cliDetails || {}, {
+    category: error.cliDetails?.category || (inputError ? context.parameterCategory : 'protocol'),
+    stage: error.cliDetails?.stage || (inputError ? 'input' : 'output-model'),
+    command: context.path, targetScope: {}, requestState: error.cliDetails?.requestState ||
+      (inputError ? 'not_sent' : 'unknown'), errorVersion: 2, execution
+  });
+  const sourceScope = error.cliDetails?.targetScope || error.inputScope || {};
+  const scopeModel = context.schema.error.properties.details.properties.targetScope;
+  // Preserve only static declared scalar scope fields; union schemas may also allow an empty scope.
+  const branches = scopeModel.oneOf || scopeModel.anyOf || [scopeModel];
+  for (const branch of branches) {
+    const model = resolveModel(context.schema, branch);
+    if (!model?.properties) continue;
+    const scope = {};
+    for (const [name, field] of Object.entries(model.properties)) {
+      const target = resolveModel(context.schema, field);
+      const value = sourceScope[name];
+      if (target?.type === 'string' && name === 'kdtId' && typeof value === 'string' &&
+          /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value))) scope[name] = value;
+      if (target?.type === 'integer' && Number.isSafeInteger(value) &&
+          (name !== 'kdtId' || value > 0) && (!target.enum || target.enum.includes(value))) scope[name] = value;
+    }
+    if ((model.required || []).every(name => Object.hasOwn(scope, name))) {
+      details.targetScope = scope;
+      break;
+    }
+  }
+  const issues = safeIssues(error, context);
+  delete details.issues;
+  if (issues.length) details.issues = issues;
+  if (error.issuesTruncated) details.issuesTruncated = true;
+  const contextReason = localContextReason(error, details, execution);
+  const responseReason = declaredResponseReason(error, context, details, execution);
+  const recovery = describeRecovery(details, execution, error.diagnosticReason === 'missing_authentication', contextReason, responseReason);
+  const groupConflict = inputError && context.path === 'item.group.list' &&
+    issues.some(issue => issue.path === '/parentGroupId' && issue.reason === 'constraint' && issue.relatedPaths?.includes('/title'))
+    ? context.schema.errors.parentTitleConflict : undefined;
+  if (groupConflict && recovery.action === 'correct_input') recovery.nextStep = groupConflict.nextStep;
+  details.recovery = { action: recovery.action, automaticBusinessRetry: false };
+  details.nextStep = recovery.nextStep;
+  const result = { success: false, code: -10001,
+    message: inputError ? (groupConflict?.message || issueMessage(issues)) :
+      contextReason ? localContextMessages[contextReason] :
+      gatewayAccessDenied(details) ? '网关拒绝访问：没有操作权限。' :
+      details.category === 'provider_unavailable' && context.path === 'privacy.field.decrypt' ? '当前仅支持离线预览，真实解密服务尚未接入' :
+      responseReason ? responseReason.message :
+      details.category === 'business_rejected' && details.requestState === 'sent' ? businessRejectionMessage(details) :
+      issues.some(issue => issue.source === 'output') ?
+        `返回数据字段 ${issues.find(issue => issue.source === 'output').path} 不符合要求，已停止查询` :
+        '命令执行失败，详情见安全诊断', details };
+  require('./command-schema').validateCommandValue(context.schema, 'error', result);
+  return result;
+}
+
+module.exports = {
+  CommandValueError, InputIssueError, inputIssue, parseIntegerOption, copyErrorDetails,
+  bindError, finalizeError, describeRecovery, modelAt, constraints, withInputScope
+};

package/src/execution/error-model.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+const object = (properties, required = Object.keys(properties)) => ({
+  type: 'object', additionalProperties: false, required, properties
+});
+const text = description => ({ type: 'string', description });
+const integer = description => ({ type: 'integer', description });
+const number = description => ({ type: 'number', description });
+const choices = (values, description) => ({ enum: values, description });
+const scalar = { anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'null' }],
+  description: '契约声明的静态标量约束。' };
+const issueReasons = ['required', 'invalid_type', 'invalid_choice', 'out_of_range',
+  'invalid_format', 'conditional_required', 'constraint', 'unexpected_property',
+  'unknown_option', 'unknown_command', 'excess_arguments', 'missing_value'];
+const definitions = {
+  diagnosticExpected: object({
+    type: { anyOf: [text('预期的 JSON 类型。'), {
+      type: 'array', items: text('预期的 JSON 类型。')
+    }], description: '同版模型允许的类型。' },
+    enum: { type: 'array', items: scalar, description: '同版模型允许的静态值。' },
+    const: scalar,
+    minimum: number('包含的最小值。'), maximum: number('包含的最大值。'),
+    exclusiveMinimum: number('不包含的最小值。'), exclusiveMaximum: number('不包含的最大值。'),
+    minLength: integer('最少字符数。'), maxLength: integer('最多字符数。'),
+    minItems: integer('最少元素数。'), maxItems: integer('最多元素数。'),
+    format: text('同版模型声明的格式。'), pattern: text('同版模型声明的字符约束。'),
+    additionalProperties: { const: false, description: '对象拒绝契约以外的属性。' },
+    contains: object({ const: scalar }),
+    items: object({ enum: { type: 'array', items: scalar, description: '元素允许的静态值。' } })
+  }, []),
+  diagnosticIssue: object({
+    source: choices(['argv', 'input', 'context', 'output', 'preview'], '问题所属的参数、输入、上下文、结果或预览模型。'),
+    path: text('对应模型中的 JSON Pointer；不含原始输入或动态字典键。'),
+    option: text('可定位时给出的已注册 CLI 选项。'),
+    reason: choices(issueReasons, '字段违反的约束类型，原始值不回显。'),
+    expected: { $ref: '#/definitions/diagnosticExpected', description: '同版契约的静态预期。' },
+    relatedPaths: { type: 'array', items: text('关联字段的 JSON Pointer。'), description: '触发条件约束的关联字段。' }
+  }, ['source', 'reason']),
+  diagnosticRecovery: object({
+    action: choices(['correct_input', 'complete_authentication', 'request_access_review', 'stop_and_inspect'],
+      '依次表示修正本地输入、补认证、核对权限或停止核查；仅是说明，不执行操作或授予权限。'),
+    automaticBusinessRetry: { const: false, description: '不据此自动重放业务请求。' }
+  }),
+  diagnosticExecution: object({
+    requestState: choices(['not_sent', 'sent', 'unknown'], '整次调用尚未发送、已有发送记录或无法排除未知请求；不代表业务完成。'),
+    coverage: choices(['complete', 'partial'], '请求观察覆盖全部已接入路径，或存在未观测路径；部分覆盖不能声明零请求。'),
+    observedAttempts: { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER,
+      description: '本地已进入发送边界的观测次数下界，不是服务端执行次数。' }
+  })
+};
+const properties = {
+  errorVersion: { const: 2, description: '本命令采用错误诊断协议第二版。' },
+  issues: { type: 'array', minItems: 1, maxItems: 16, items: { $ref: '#/definitions/diagnosticIssue' },
+    description: '最多十六个已定位问题，不包含收到的原值。' },
+  issuesTruncated: { const: true, description: '问题超过返回上限，当前列表没有穷尽全部问题。' },
+  recovery: { $ref: '#/definitions/diagnosticRecovery', description: '受限的恢复说明，不会自动执行。' },
+  execution: { $ref: '#/definitions/diagnosticExecution', description: '整次调用的请求观察，独立于失败阶段的 requestState。' }
+};
+
+function applyDiagnosticModel(schema) {
+  schema.definitions = { ...schema.definitions, ...structuredClone(definitions) };
+  Object.assign(schema.error.properties.details.properties, structuredClone(properties));
+  schema.error.properties.details.required = [...new Set([
+    ...schema.error.properties.details.required, 'errorVersion', 'recovery', 'execution'
+  ])];
+  schema.errors.diagnosticsVersion = 2;
+  return schema;
+}
+
+function assertDiagnosticModel(schema) {
+  if (schema.errors?.diagnosticsVersion !== 2) return;
+  const details = schema.error?.properties?.details;
+  if (!Object.entries(definitions).every(([key, value]) => isDeepStrictEqual(schema.definitions?.[key], value)) ||
+      !Object.entries(properties).every(([key, value]) => isDeepStrictEqual(details?.properties?.[key], value)) ||
+      !['errorVersion', 'recovery', 'execution'].every(key => details?.required?.includes(key))) {
+    throw new Error('Diagnostic contract differs from shared model; run node scripts/sync-error-diagnostics.js');
+  }
+}
+
+module.exports = { applyDiagnosticModel, assertDiagnosticModel, issueReasons,
+  diagnosticDefinitions: definitions };

package/src/execution/exact-json.js

@@ -0,0 +1,80 @@
+'use strict';
+
+function exactNumber(source) {
+  const number = Number(source);
+  if (!Number.isInteger(number)) return number;
+  const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(source);
+  const fraction = match[3] || '';
+  const significant = `${match[2]}${fraction}`.replace(/^0+/, '');
+  const digits = significant.replace(/0+$/, '');
+  if (!digits) return number;
+  if (number === 0) return NaN;
+  const scale = Number(match[4] || 0) - fraction.length + significant.length - digits.length;
+  const integer = BigInt(number).toString();
+  const magnitude = integer.startsWith('-') ? integer.slice(1) : integer;
+  if (scale < 0 || digits.length + scale !== magnitude.length) return NaN;
+  return `${match[1]}${digits}${'0'.repeat(scale)}` === integer ? number : NaN;
+}
+
+function parseExactJson(text, decodeNumber = exactNumber, { rejectDuplicates = false } = {}) {
+  JSON.parse(text);
+  let index = 0;
+  let result;
+  const stack = [];
+  const numberPattern = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+  function append(value) {
+    if (stack.length === 0) result = value;
+    else {
+      const parent = stack[stack.length - 1];
+      if (Array.isArray(parent.value)) parent.value.push(value);
+      else {
+        if (rejectDuplicates && Object.hasOwn(parent.value, parent.key)) {
+          throw new Error('duplicate JSON member');
+        }
+        Object.defineProperty(parent.value, parent.key, {
+          value, enumerable: true, configurable: true, writable: true
+        });
+        parent.key = null;
+      }
+    }
+  }
+  while (index < text.length) {
+    const token = text[index++];
+    if (token.charCodeAt(0) <= 32 || token === ':' || token === ',') continue;
+    if (token === '{' || token === '[') {
+      const value = token === '{' ? {} : [];
+      append(value);
+      stack.push({ value, key: null });
+    } else if (token === '}' || token === ']') {
+      stack.pop();
+    } else if (token === '"') {
+      const start = index - 1;
+      while (index < text.length) {
+        const character = text[index++];
+        if (character === '\\') index++;
+        else if (character === '"') break;
+      }
+      const value = JSON.parse(text.slice(start, index));
+      const parent = stack[stack.length - 1];
+      if (parent && !Array.isArray(parent.value) && parent.key === null) parent.key = value;
+      else append(value);
+    } else if (token === 't') {
+      index += 3;
+      append(true);
+    } else if (token === 'f') {
+      index += 4;
+      append(false);
+    } else if (token === 'n') {
+      index += 3;
+      append(null);
+    } else {
+      numberPattern.lastIndex = index - 1;
+      const number = numberPattern.exec(text)[0];
+      index = numberPattern.lastIndex;
+      append(decodeNumber(number));
+    }
+  }
+  return result;
+}
+
+module.exports = { parseExactJson };

package/src/execution/list-total.js

@@ -0,0 +1,10 @@
+'use strict';
+
+function readTotal(source, field, invalid = () => new TypeError('Invalid list total')) {
+  const total = source[field];
+  if (total === undefined || total === null) return null;
+  if (!Number.isSafeInteger(total) || total < 0) throw invalid();
+  return total;
+}
+
+module.exports = { readTotal };

package/src/execution/money.js

@@ -0,0 +1,59 @@
+'use strict';
+
+function fenToYuan(value) {
+  if (!Number.isSafeInteger(value)) throw new Error('Amount must be a safe integer in fen');
+  const amount = BigInt(value);
+  const absolute = amount < 0n ? -amount : amount;
+  return `${amount < 0n ? '-' : ''}${absolute / 100n}.${String(absolute % 100n).padStart(2, '0')}`;
+}
+
+function formatYuan(value) {
+  // The API explicitly returns an empty string for some origin_price values.
+  if (value === '') return value;
+  if (typeof value !== 'string' || value.trim() !== value || !/^-?\d+(?:\.\d+)?$/.test(value)) {
+    throw new Error('Amount must be decimal text in yuan');
+  }
+  const negative = value.startsWith('-');
+  const [whole, fraction = ''] = (negative ? value.slice(1) : value).split('.');
+  if (/[1-9]/.test(fraction.slice(2))) throw new Error('Amount cannot be represented exactly in fen');
+  const cents = BigInt(whole) * 100n + BigInt(fraction.slice(0, 2).padEnd(2, '0'));
+  return `${negative && cents !== 0n ? '-' : ''}${cents / 100n}.${String(cents % 100n).padStart(2, '0')}`;
+}
+
+function yuanToFenBigInt(value) {
+  const normalized = formatYuan(value);
+  if (normalized === '') throw new Error('Amount must be decimal text in yuan');
+  return BigInt(normalized.replace('.', ''));
+}
+
+function yuanToFen(value) {
+  const cents = yuanToFenBigInt(value);
+  const result = Number(cents);
+  if (!Number.isSafeInteger(result)) throw new Error('Amount exceeds safe integer fen');
+  return result;
+}
+
+function compareYuan(left, right) {
+  const a = yuanToFenBigInt(left);
+  const b = yuanToFenBigInt(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function normalizeMoney(value, model) {
+  if (value == null) return value;
+  if (model.$comment === 'upstream-money:fen') return fenToYuan(value);
+  if (model.$comment === 'upstream-money:yuan') return formatYuan(value);
+  if (Array.isArray(value) && model.items) {
+    return value.map(entry => normalizeMoney(entry, model.items));
+  }
+  if (typeof value === 'object' && !Array.isArray(value) && model.properties) {
+    const result = { ...value };
+    for (const [key, child] of Object.entries(model.properties)) {
+      if (Object.hasOwn(value, key)) result[key] = normalizeMoney(value[key], child);
+    }
+    return result;
+  }
+  return value;
+}
+
+module.exports = { normalizeMoney, formatYuan, yuanToFen, compareYuan };