@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.1

package/lib/types/agent-config-contract/cs-hosting.js

@@ -0,0 +1,163 @@
+/** 客服托管权、租约与运行状态检查点契约。子账号归属使用本服务 UserId。 @module */
+import { z } from 'zod';
+import { TenantId, UserId } from "./ids.js";
+/** 旺旺账号的稳定、不透明标识；不作昵称或大小写归一化。 */
+export const WangwangAccountId = z.string().min(1).max(200).brand();
+/** 本机安装标识，由 Host 产生并持久保存。 */
+export const InstallationId = z.uuid().brand();
+/** 云端沙箱标识，不限定执行器的标识格式。 */
+export const SandboxId = z.string().min(1).max(200).brand();
+/** 持有者种类参与匹配，相同文本的安装与沙箱不是同一持有者。 */
+export const HostingHolder = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('installation'), id: InstallationId }),
+    z.object({ kind: z.literal('sandbox'), id: SandboxId }),
+]).meta({ id: 'HostingHolder' });
+/** 单调递增的 CAS 代次，JSON 安全整数。 */
+export const HostingEpoch = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+export const HostingLeaseParams = z.object({ tenantId: TenantId, userId: UserId, accountId: WangwangAccountId });
+/** 禁止通过查询串指定身份或客户端时间。 */
+export const HostingLeaseQuery = z.strictObject({});
+/** 未开通不保存记录，调用方按本地既有行为继续运行。 */
+export const HostingNotEnabled = z.object({ cloudEnabled: z.literal(false), serverTime: z.iso.datetime() }).meta({ id: 'HostingNotEnabled' });
+/** 有效性以 serverTime 为准；到期记录保留持有者与 epoch 供 CAS 接管。 */
+export const HostingEnabled = z.object({
+    cloudEnabled: z.literal(true), holder: HostingHolder.nullable(), epoch: HostingEpoch,
+    state: z.enum(['unheld', 'active', 'expired']), leaseExpiresAt: z.iso.datetime().nullable(),
+    remainingSeconds: z.number().int().nonnegative(), serverTime: z.iso.datetime(), updatedAt: z.iso.datetime(),
+}).meta({ id: 'HostingEnabled' });
+export const HostingLeaseResponse = z.discriminatedUnion('cloudEnabled', [HostingNotEnabled, HostingEnabled]).meta({ id: 'HostingLeaseResponse' });
+/** 取得只允许无持有者或已到期；expectedEpoch 必须匹配，成功后加一。 */
+export const AcquireHostingLeaseRequest = z.strictObject({ holder: HostingHolder, expectedEpoch: HostingEpoch }).meta({ id: 'AcquireHostingLeaseRequest' });
+/** 云端首次开通只接受当前沙箱；不携带 epoch，也不接受本机安装。 */
+export const FirstEnableHostingLeaseRequest = z.strictObject({ holder: z.strictObject({ kind: z.literal('sandbox'), id: SandboxId }) }).meta({ id: 'FirstEnableHostingLeaseRequest' });
+/** 续约和释放验证完整持有者与当前 epoch；过期续约拒绝。 */
+export const HostingLeaseOwnerRequest = z.strictObject({ holder: HostingHolder, epoch: HostingEpoch }).meta({ id: 'HostingLeaseOwnerRequest' });
+/** 交接要求源租约有效；目标获得新 epoch 与完整 TTL。 */
+export const HandoffHostingLeaseRequest = HostingLeaseOwnerRequest.extend({ target: HostingHolder }).meta({ id: 'HandoffHostingLeaseRequest' });
+const path = '/v1/tenants/{tenantId}/cs-hosting/users/{userId}/accounts/{accountId}/lease';
+const problems = {
+    503: ['SERVICE_UNAVAILABLE'],
+    401: ['SESSION_REQUIRED', 'SESSION_EXPIRED'],
+    403: ['NO_CURRENT_TENANT', 'NOT_A_MEMBER', 'HOSTING_UNAVAILABLE', 'HOSTING_USER_MISMATCH'],
+    409: ['TENANT_NOT_CURRENT', 'HOSTING_EPOCH_MISMATCH', 'HOSTING_HELD', 'HOSTING_HOLDER_MISMATCH', 'HOSTING_LEASE_EXPIRED'],
+};
+const responses = { 200: { description: '托管权状态；未开通的操作同样返回 cloudEnabled=false，不创建记录', schema: HostingLeaseResponse, headers: { 'Cache-Control': { description: '租约状态不得缓存', schema: z.literal('no-store') } } } };
+const queryResponses = { 200: { description: '托管权状态。本账号没有记录但同一用户在其他旺旺账号上已有未过期的 active 持有者时，返回该持有者且 cloudEnabled=true。本账号已有未开通记录，或没有其他 active 持有者时，返回 cloudEnabled=false，不创建记录', schema: HostingLeaseResponse, headers: responses[200].headers } };
+const firstEnableResponses = { 200: { description: '已开通的托管权。没有租约记录且同一用户没有其他 active 持有者时创建沙箱持有的 active 租约；同一沙箱重复调用不改变 epoch、持有者或到期时间', schema: HostingLeaseResponse, headers: { 'Cache-Control': { description: '租约状态不得缓存', schema: z.literal('no-store') } } } };
+/** 只能查询当前店铺租户中本人的旺旺账号托管权。本账号无记录但同一用户已有 active 持有者时返回该持有者。 */
+export const getHostingLease = { method: 'get', path, summary: '查询本人托管权', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery }, responses: queryResponses, problems };
+const acquireResponses = { 200: { description: '托管权状态。同一用户在其他旺旺账号上已有 active 持有者时回答 HOSTING_HELD，不创建记录。本账号未开通且没有其他 active 持有者时返回 cloudEnabled=false，不创建记录', schema: HostingLeaseResponse, headers: responses[200].headers } };
+/** 同一用户在其他旺旺账号上已有 active 持有者时回答 HOSTING_HELD，不创建记录。本账号未开通且没有其他 active 持有者时仍返回 cloudEnabled=false。 */
+export const acquireHostingLease = { method: 'post', path: `${path}/acquire`, summary: 'CAS 取得托管租约', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: AcquireHostingLeaseRequest }, responses: acquireResponses, problems: { ...problems, 409: [...problems[409], 'LOCAL_HOST_REPLACED'] } };
+/** 没有租约记录时创建 cloudEnabled 的沙箱租约；已有记录拒绝，不抢占。同一用户在其他旺旺账号上已有 active 持有者时回答 HOSTING_HELD，不插入。 */
+export const firstEnableHostingLease = { method: 'post', path: `${path}/first-enable`, summary: '云端沙箱首次开通本人托管权', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: FirstEnableHostingLeaseRequest }, responses: firstEnableResponses, problems: { ...problems, 403: [...problems[403], 'CLOUD_NOT_ELIGIBLE', 'SANDBOX_SESSION_UNBOUND'] } };
+const renewResponses = { 200: { description: '已续约的托管权。本机持有者未开通时返回 cloudEnabled=false 且不创建记录；沙箱持有者没有租约行，或前任观察与锁内判断不一致时不刷新租约', schema: HostingLeaseResponse, headers: responses[200].headers } };
+/** 已交接或首次开通给沙箱的同一 epoch，在采用及续约时重新确认旧实例退出，成功保持该 epoch。没有租约行，或未完成与锁内判断一致的前任观察时，沙箱续约拒绝且不更新。 */
+export const renewHostingLease = { method: 'post', path: `${path}/renew`, summary: '续约本人托管权', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: HostingLeaseOwnerRequest }, responses: renewResponses, problems: { ...problems, 403: [...problems[403], 'SANDBOX_SESSION_UNBOUND'], 409: [...problems[409], 'LOCAL_HOST_REPLACED', 'PLACEMENT_KEY_NOT_READY', 'PREDECESSOR_STILL_RUNNING'], 503: ['SERVICE_UNAVAILABLE', 'PREDECESSOR_EXIT_UNKNOWN'] } };
+/** 释放推进 epoch 并清空持有者；到期的当前持有者也可释放。 */
+export const releaseHostingLease = { method: 'post', path: `${path}/release`, summary: '释放本人托管权', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: HostingLeaseOwnerRequest }, responses, problems };
+export const handoffHostingLease = { method: 'post', path: `${path}/handoff`, summary: 'CAS 交接本人托管权', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: HandoffHostingLeaseRequest }, responses, problems: { ...problems, 409: [...problems[409], 'LOCAL_HOST_REPLACED'] } };
+const whitespace = /\s/u;
+/** 不透明令牌：非空，且不含空白或 ASCII 控制字符。 */
+function opaqueText(value) {
+    if (whitespace.test(value))
+        return false;
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (code < 32 || code === 127)
+            return false;
+    }
+    return true;
+}
+const opaque = (max) => z.string().min(1).max(max).refine(opaqueText);
+const count = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+/** 一条消息流的不透明游标。同一次上报里 streamId 不可重复，不含消息正文。 */
+export const HostingStreamCursor = z.strictObject({
+    streamId: opaque(200),
+    cursor: opaque(1024),
+}).meta({ id: 'HostingStreamCursor' });
+/** 各消息流游标，最多 64 条。 */
+export const HostingStreamCursors = z.array(HostingStreamCursor).max(64).superRefine((items, ctx) => {
+    const seen = new Set();
+    items.forEach((item, index) => {
+        if (!seen.has(item.streamId)) {
+            seen.add(item.streamId);
+            return;
+        }
+        ctx.addIssue({ code: 'custom', path: [index, 'streamId'], message: 'Duplicate stream' });
+    });
+});
+/** 已提交事件的 sha256，不是正文摘要。 */
+export const HostingCheckpointSession = z.strictObject({
+    id: opaque(200),
+    eventCount: count,
+    digest: z.string().regex(/^[a-f0-9]{64}$/),
+}).meta({ id: 'HostingCheckpointSession' });
+/** running 正在自动接待，draining 正在排空，stopped 已停止自动接待，unavailable 无法确认仍在接待。 */
+export const HostingCheckpointStatus = z.enum(['running', 'draining', 'stopped', 'unavailable']).meta({ id: 'HostingCheckpointStatus' });
+const hostVersion = z.string().regex(/^[0-9A-Za-z][0-9A-Za-z.+_-]{0,99}$/);
+/** 规范 SemVer 2.0，最多 200 字符，保留预发布和构建元数据，不接受前缀或空白。 */
+export const AgentConfigSemver = z.string().max(200).regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?(?![\s\S])/);
+/** 与 Host Agent 配置错误分类对齐；查询失败与作用域变化不计采用拒绝。 */
+export const AgentConfigErrorCode = z.enum([
+    'AGENT_CONFIG_INCOMPATIBLE', 'AGENT_CONFIG_DIGEST_MISMATCH', 'AGENT_CONFIG_INVALID',
+    'AGENT_CONFIG_DOWNLOAD_FAILED', 'AGENT_CONFIG_APPLY_FAILED', 'AGENT_CONFIG_QUERY_FAILED', 'AGENT_CONFIG_SCOPE_CHANGED',
+]).meta({ id: 'AgentConfigErrorCode' });
+/** 仅包含固定码与已知时的被拒版本，不包含消息、路径、URL 或凭据。 */
+export const AgentConfigRejection = z.strictObject({ code: AgentConfigErrorCode, version: AgentConfigSemver.optional() }).meta({ id: 'AgentConfigRejection' });
+/**
+ * 某个旺旺账号的最新运行状态检查点。revision 从 1 起，跨 epoch 单调递增，不随代次重置。
+ * reportedAt 是服务端记下的上报时间，调用方用它判断是否过期。旧检查点不能作为补发依据。
+ */
+export const HostingCheckpoint = z.strictObject({
+    tenantId: TenantId,
+    userId: UserId,
+    accountId: WangwangAccountId,
+    epoch: HostingEpoch,
+    revision: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    streamCursors: HostingStreamCursors,
+    session: HostingCheckpointSession.nullable(),
+    pendingCount: count,
+    unknownSendCount: count,
+    status: HostingCheckpointStatus,
+    hostVersion,
+    reportedAt: z.iso.datetime(),
+}).meta({ id: 'HostingCheckpoint' });
+/**
+ * 上报当前检查点。expectedRevision 为 0 表示尚无记录，否则必须等于当前 revision。
+ * 只接受 held 且 epoch 匹配的托管租约；未开通、未持有或 epoch 不同为 HOSTING_EPOCH_MISMATCH。
+ * revision 不匹配或加一后超出安全整数为 HOSTING_REVISION_MISMATCH，且不修改记录。限制开关关闭时不比较持有者；开启时本地请求必须提供与模块名册一致的 holder。
+ */
+export const ReportHostingCheckpointRequest = z.strictObject({
+    /** 本地 Host 限制开启时必须提供；与模块名册的 hostId 相同。 */
+    holder: HostingHolder.optional(),
+    epoch: HostingEpoch,
+    expectedRevision: count,
+    streamCursors: HostingStreamCursors,
+    session: HostingCheckpointSession.nullable(),
+    pendingCount: count,
+    unknownSendCount: count,
+    status: HostingCheckpointStatus,
+    hostVersion,
+    /** Host 已经成功应用的 Agent 配置版本；未上报表示未知，不接受以分配版本代替。 */
+    agentConfigVersion: z.string().min(1).max(200).optional(),
+    /** Host 的 Agent 配置 API，独立于应用 hostVersion；缺失表示未知。 */
+    hostAgentConfigApiVersion: AgentConfigSemver.optional(),
+    /** 已提交内容是否禁止执行；缺失不代表 false。 */
+    agentConfigBlocked: z.boolean().optional(),
+    /** null 明确表示没有拒绝，缺失表示未上报；三个新字段齐全才构成完整观测。 */
+    agentConfigRejection: AgentConfigRejection.nullable().optional(),
+}).meta({ id: 'ReportHostingCheckpointRequest' });
+const checkpointPath = '/v1/tenants/{tenantId}/cs-hosting/users/{userId}/accounts/{accountId}/checkpoint';
+const checkpointResponses = { 200: { description: '最新运行状态与游标。reportedAt 为上报时间，调用方据此判断是否过期；旧检查点不能作为补发依据', schema: HostingCheckpoint, headers: { 'Cache-Control': { description: '检查点不得缓存', schema: z.literal('no-store') } } } };
+const checkpointProblems = {
+    503: ['SERVICE_UNAVAILABLE'],
+    401: ['SESSION_REQUIRED', 'SESSION_EXPIRED'],
+    403: ['NO_CURRENT_TENANT', 'NOT_A_MEMBER', 'HOSTING_UNAVAILABLE', 'HOSTING_USER_MISMATCH'],
+    409: ['TENANT_NOT_CURRENT'],
+};
+/** 读取本人该旺旺账号的最新检查点。没有记录时 404，不把缺失当成可补发的空游标。 */
+export const getHostingCheckpoint = { method: 'get', path: checkpointPath, summary: '读取本人运行状态检查点', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery }, responses: checkpointResponses, problems: { ...checkpointProblems, 404: ['NOT_FOUND'] } };
+/** 当前持有者上报。本机会话与沙箱会话都只按租约 epoch 判断，旧 epoch 或旧 revision 被拒绝。 */
+export const reportHostingCheckpoint = { method: 'post', path: checkpointPath, summary: 'CAS 上报本人运行状态检查点', auth: 'tenant', request: { params: HostingLeaseParams, query: HostingLeaseQuery, body: ReportHostingCheckpointRequest }, responses: checkpointResponses, problems: { ...checkpointProblems, 409: ['TENANT_NOT_CURRENT', 'HOSTING_EPOCH_MISMATCH', 'HOSTING_REVISION_MISMATCH', 'HOSTING_HOLDER_MISMATCH', 'LOCAL_HOST_REPLACED'] } };
+export const CS_HOSTING_ROUTES = [getHostingLease, acquireHostingLease, firstEnableHostingLease, renewHostingLease, releaseHostingLease, handoffHostingLease, getHostingCheckpoint, reportHostingCheckpoint];

package/lib/types/agent-config-contract/errors.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Error model of the v1 API: RFC 9457 `application/problem+json` bodies with a closed `code` set.
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * Closed set of problem codes. Clients choose localized copy by `code` and fall back to generic copy
+ * for a code they do not know; `title` and `detail` are diagnostic only.
+ */
+export declare const ERROR_CODES: readonly ["MERCHANT_NOT_ALLOWED", "MERCHANT_ACCOUNT_TYPE_UNSUPPORTED", "MERCHANT_SUB_ACCOUNT_MISMATCH", "MERCHANT_IDENTITY_NOT_FOUND", "MERCHANT_IDENTITY_KIND_MISMATCH", "MERCHANT_IDENTITY_UNAVAILABLE", "MERCHANT_ALREADY_ALLOWED", "MERCHANT_PREVIEW_CHANGED", "SANDBOX_ALREADY_EXISTS", "NAS_CAPACITY_INSUFFICIENT", "NAS_USAGE_UNAVAILABLE", "MERCHANT_TOKEN_UNAVAILABLE", "TEST_ACCOUNT_NOT_REGISTERED", "TEST_ACCOUNT_CLAIMED", "TEST_ACCOUNT_CLAIM_HOLDER_MISMATCH", "VALIDATION_FAILED", "NOT_FOUND", "SESSION_REQUIRED", "SESSION_EXPIRED", "NO_CURRENT_TENANT", "TENANT_NOT_CURRENT", "NOT_A_MEMBER", "ADMIN_REQUIRED", "RESOURCE_CENTER_UNAVAILABLE", "CLOUD_MODELS_UNAVAILABLE", "CLOUD_QUOTA_EXCEEDED", "CLOUD_LOGIN_RATE_LIMITED", "AGENT_CONFIGS_UNAVAILABLE", "AGENT_CONFIG_PLAN_NOT_INITIALIZED", "SHOP_ACCOUNT_CANNOT_JOIN", "SHOP_ACCOUNT_CANNOT_SWITCH", "SHOP_ACCOUNT_CANNOT_CREATE", "SHOP_TENANT_CANNOT_REMOVE_MEMBER", "SHOP_TENANT_NAME_IMMUTABLE", "SHOP_TENANT_CANNOT_INVITE", "INVITE_EXPIRED", "INVITE_REVOKED", "OWNER_IMMUTABLE", "ROLE_NAME_TAKEN", "VERSION_CONFLICT", "OPERATION_CONFLICT", "MATERIAL_REFERENCED", "ASSET_CHECKSUM_MISMATCH", "ASSET_COMMIT_IN_PROGRESS", "ASSET_NOT_UPLOADED", "ASSET_NOT_COMMITTED", "MATERIAL_ARCHIVED", "CLIENT_UPGRADE_REQUIRED", "LOGIN_ATTEMPT_GONE", "LOGIN_VERIFIER_MISMATCH", "SERVICE_UNAVAILABLE", "PLATFORM_IDENTITY_NOT_ALLOWED", "PLATFORM_IDENTITY_MISMATCH", "KNOWLEDGE_MANAGE_REQUIRED", "KNOWLEDGE_OPERATION_NOT_ALLOWED", "KNOWLEDGE_PERSONAL_USE_REQUIRED", "KNOWLEDGE_SHOP_ONLY", "KNOWLEDGE_CONFLICT", "KNOWLEDGE_RUNTIME_CURSOR_EXPIRED", "KNOWLEDGE_OPS_ADMIN_REQUIRED", "KNOWLEDGE_RECOVERY_OUTCOME_UNKNOWN", "KNOWLEDGE_DISTILL_OUTCOME_UNKNOWN", "PREVIEW_STALE", "AMAP_MCP_SHOP_ONLY", "AMAP_MCP_METHOD_NOT_ALLOWED", "AMAP_MCP_TOOL_NOT_ALLOWED", "AMAP_MCP_TOO_LARGE", "AMAP_MCP_UNAVAILABLE", "AMAP_MCP_PROVIDER_LIMITED", "AMAP_MCP_UPSTREAM_ERROR", "AMAP_MCP_TIMEOUT", "AMAP_MCP_PROTOCOL_ERROR", "HOSTING_UNAVAILABLE", "HOSTING_USER_MISMATCH", "HOSTING_EPOCH_MISMATCH", "HOSTING_REVISION_MISMATCH", "HOSTING_ARCHIVE_CONFLICT", "HOSTING_HELD", "HOSTING_HOLDER_MISMATCH", "HOSTING_LEASE_EXPIRED", "SANDBOX_UNAVAILABLE", "SANDBOX_NOT_RUNNING", "EVALUATION_ACTIVE", "EVALUATION_EXECUTOR_UNSUPPORTED", "EVALUATION_HOSTING_ACTIVE", "SANDBOX_UPGRADE_CONFLICT", "SANDBOX_RECOVERY_CONFLICT", "SANDBOX_UPGRADE_REJECTED", "SANDBOX_RELEASE_UNAVAILABLE", "SANDBOX_SESSION_UNBOUND", "PREDECESSOR_STILL_RUNNING", "PREDECESSOR_EXIT_UNKNOWN", "ENTRY_TOKEN_REJECTED", "ENTRY_TOKEN_EXPIRED", "ENTRY_TOKEN_SANDBOX_MISMATCH", "OPERATOR_INVALID_CREDENTIALS", "OPERATOR_INVALID_2FA", "OPERATOR_ROLE_REQUIRED", "OPERATOR_ACCOUNT_INACTIVE", "OPERATOR_RATE_LIMITED", "OPERATOR_SESSION_LIMIT", "OPERATOR_LOGIN_RATE_LIMITED", "OPERATOR_SESSION_REQUIRED", "OPERATOR_SESSION_EXPIRED", "SUB2API_UNAVAILABLE", "SERVICE_CREDENTIAL_REQUIRED", "SERVICE_CREDENTIAL_REJECTED", "CUSTOMER_MESSAGES_UNAVAILABLE", "MESSAGE_PENDING_VERIFICATION", "MAPPING_NOT_ALLOWED", "SPACE_TOKEN_REQUIRED", "SPACE_TOKEN_REJECTED", "SEGMENT_SPACE_FORBIDDEN", "CLOUD_NOT_ELIGIBLE", "OPERATION_MISMATCH", "SANDBOX_PROVISION_CONFLICT", "PROVISION_ALREADY_COMPLETED", "HANDOFF_CONFLICT", "HANDOFF_REVISION_MISMATCH", "HANDOFF_NOT_CANCELLABLE", "INSTALLATION_SESSION_REQUIRED", "INSTALLATION_CHALLENGE_REJECTED", "INSTALLATION_CHALLENGE_EXPIRED", "INSTALLATION_BINDING_CONFLICT", "INSTALLATION_BINDING_REQUIRED", "LOCAL_HOST_REPLACED", "HANDOFF_STATE_CONFLICT", "HANDOFF_IMPORT_REQUIRED", "HANDOFF_MANIFEST_MISMATCH", "PLACEMENT_KEY_CONFLICT", "PLACEMENT_KEY_NOT_READY", "PLACEMENT_TOKEN_REJECTED", "SALES_CASES_SHOP_ONLY", "OBSERVATION_BINDING_REJECTED", "OBSERVATION_EXPIRED", "OBSERVATION_TOO_LARGE", "CUSTOMER_SHOP_REQUIRED", "CUSTOMER_NOT_FOUND", "CUSTOMER_REVISION_CONFLICT", "CUSTOMER_OPERATION_MISMATCH", "CUSTOMER_SOURCE_STALE", "CUSTOMER_ACTIVE_CASE_EXISTS", "CUSTOMER_WRITE_FENCED", "CUSTOMER_EVIDENCE_PENDING", "CUSTOMER_SEND_UNRESOLVED", "CUSTOMER_DATA_TOO_LARGE", "CUSTOMER_CAPACITY_EXCEEDED", "CUSTOMER_RATE_LIMITED", "CUSTOMER_DATA_UNAVAILABLE", "INTERNAL"];
+/** One member of {@link ERROR_CODES}. */
+export declare const ErrorCode: z.ZodEnum<{
+    MERCHANT_NOT_ALLOWED: "MERCHANT_NOT_ALLOWED";
+    MERCHANT_ACCOUNT_TYPE_UNSUPPORTED: "MERCHANT_ACCOUNT_TYPE_UNSUPPORTED";
+    MERCHANT_SUB_ACCOUNT_MISMATCH: "MERCHANT_SUB_ACCOUNT_MISMATCH";
+    MERCHANT_IDENTITY_NOT_FOUND: "MERCHANT_IDENTITY_NOT_FOUND";
+    MERCHANT_IDENTITY_KIND_MISMATCH: "MERCHANT_IDENTITY_KIND_MISMATCH";
+    MERCHANT_IDENTITY_UNAVAILABLE: "MERCHANT_IDENTITY_UNAVAILABLE";
+    MERCHANT_ALREADY_ALLOWED: "MERCHANT_ALREADY_ALLOWED";
+    MERCHANT_PREVIEW_CHANGED: "MERCHANT_PREVIEW_CHANGED";
+    SANDBOX_ALREADY_EXISTS: "SANDBOX_ALREADY_EXISTS";
+    NAS_CAPACITY_INSUFFICIENT: "NAS_CAPACITY_INSUFFICIENT";
+    NAS_USAGE_UNAVAILABLE: "NAS_USAGE_UNAVAILABLE";
+    MERCHANT_TOKEN_UNAVAILABLE: "MERCHANT_TOKEN_UNAVAILABLE";
+    TEST_ACCOUNT_NOT_REGISTERED: "TEST_ACCOUNT_NOT_REGISTERED";
+    TEST_ACCOUNT_CLAIMED: "TEST_ACCOUNT_CLAIMED";
+    TEST_ACCOUNT_CLAIM_HOLDER_MISMATCH: "TEST_ACCOUNT_CLAIM_HOLDER_MISMATCH";
+    VALIDATION_FAILED: "VALIDATION_FAILED";
+    NOT_FOUND: "NOT_FOUND";
+    SESSION_REQUIRED: "SESSION_REQUIRED";
+    SESSION_EXPIRED: "SESSION_EXPIRED";
+    NO_CURRENT_TENANT: "NO_CURRENT_TENANT";
+    TENANT_NOT_CURRENT: "TENANT_NOT_CURRENT";
+    NOT_A_MEMBER: "NOT_A_MEMBER";
+    ADMIN_REQUIRED: "ADMIN_REQUIRED";
+    RESOURCE_CENTER_UNAVAILABLE: "RESOURCE_CENTER_UNAVAILABLE";
+    CLOUD_MODELS_UNAVAILABLE: "CLOUD_MODELS_UNAVAILABLE";
+    CLOUD_QUOTA_EXCEEDED: "CLOUD_QUOTA_EXCEEDED";
+    CLOUD_LOGIN_RATE_LIMITED: "CLOUD_LOGIN_RATE_LIMITED";
+    AGENT_CONFIGS_UNAVAILABLE: "AGENT_CONFIGS_UNAVAILABLE";
+    AGENT_CONFIG_PLAN_NOT_INITIALIZED: "AGENT_CONFIG_PLAN_NOT_INITIALIZED";
+    SHOP_ACCOUNT_CANNOT_JOIN: "SHOP_ACCOUNT_CANNOT_JOIN";
+    SHOP_ACCOUNT_CANNOT_SWITCH: "SHOP_ACCOUNT_CANNOT_SWITCH";
+    SHOP_ACCOUNT_CANNOT_CREATE: "SHOP_ACCOUNT_CANNOT_CREATE";
+    SHOP_TENANT_CANNOT_REMOVE_MEMBER: "SHOP_TENANT_CANNOT_REMOVE_MEMBER";
+    SHOP_TENANT_NAME_IMMUTABLE: "SHOP_TENANT_NAME_IMMUTABLE";
+    SHOP_TENANT_CANNOT_INVITE: "SHOP_TENANT_CANNOT_INVITE";
+    INVITE_EXPIRED: "INVITE_EXPIRED";
+    INVITE_REVOKED: "INVITE_REVOKED";
+    OWNER_IMMUTABLE: "OWNER_IMMUTABLE";
+    ROLE_NAME_TAKEN: "ROLE_NAME_TAKEN";
+    VERSION_CONFLICT: "VERSION_CONFLICT";
+    OPERATION_CONFLICT: "OPERATION_CONFLICT";
+    MATERIAL_REFERENCED: "MATERIAL_REFERENCED";
+    ASSET_CHECKSUM_MISMATCH: "ASSET_CHECKSUM_MISMATCH";
+    ASSET_COMMIT_IN_PROGRESS: "ASSET_COMMIT_IN_PROGRESS";
+    ASSET_NOT_UPLOADED: "ASSET_NOT_UPLOADED";
+    ASSET_NOT_COMMITTED: "ASSET_NOT_COMMITTED";
+    MATERIAL_ARCHIVED: "MATERIAL_ARCHIVED";
+    CLIENT_UPGRADE_REQUIRED: "CLIENT_UPGRADE_REQUIRED";
+    LOGIN_ATTEMPT_GONE: "LOGIN_ATTEMPT_GONE";
+    LOGIN_VERIFIER_MISMATCH: "LOGIN_VERIFIER_MISMATCH";
+    SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    PLATFORM_IDENTITY_NOT_ALLOWED: "PLATFORM_IDENTITY_NOT_ALLOWED";
+    PLATFORM_IDENTITY_MISMATCH: "PLATFORM_IDENTITY_MISMATCH";
+    KNOWLEDGE_MANAGE_REQUIRED: "KNOWLEDGE_MANAGE_REQUIRED";
+    KNOWLEDGE_OPERATION_NOT_ALLOWED: "KNOWLEDGE_OPERATION_NOT_ALLOWED";
+    KNOWLEDGE_PERSONAL_USE_REQUIRED: "KNOWLEDGE_PERSONAL_USE_REQUIRED";
+    KNOWLEDGE_SHOP_ONLY: "KNOWLEDGE_SHOP_ONLY";
+    KNOWLEDGE_CONFLICT: "KNOWLEDGE_CONFLICT";
+    KNOWLEDGE_RUNTIME_CURSOR_EXPIRED: "KNOWLEDGE_RUNTIME_CURSOR_EXPIRED";
+    KNOWLEDGE_OPS_ADMIN_REQUIRED: "KNOWLEDGE_OPS_ADMIN_REQUIRED";
+    KNOWLEDGE_RECOVERY_OUTCOME_UNKNOWN: "KNOWLEDGE_RECOVERY_OUTCOME_UNKNOWN";
+    KNOWLEDGE_DISTILL_OUTCOME_UNKNOWN: "KNOWLEDGE_DISTILL_OUTCOME_UNKNOWN";
+    PREVIEW_STALE: "PREVIEW_STALE";
+    AMAP_MCP_SHOP_ONLY: "AMAP_MCP_SHOP_ONLY";
+    AMAP_MCP_METHOD_NOT_ALLOWED: "AMAP_MCP_METHOD_NOT_ALLOWED";
+    AMAP_MCP_TOOL_NOT_ALLOWED: "AMAP_MCP_TOOL_NOT_ALLOWED";
+    AMAP_MCP_TOO_LARGE: "AMAP_MCP_TOO_LARGE";
+    AMAP_MCP_UNAVAILABLE: "AMAP_MCP_UNAVAILABLE";
+    AMAP_MCP_PROVIDER_LIMITED: "AMAP_MCP_PROVIDER_LIMITED";
+    AMAP_MCP_UPSTREAM_ERROR: "AMAP_MCP_UPSTREAM_ERROR";
+    AMAP_MCP_TIMEOUT: "AMAP_MCP_TIMEOUT";
+    AMAP_MCP_PROTOCOL_ERROR: "AMAP_MCP_PROTOCOL_ERROR";
+    HOSTING_UNAVAILABLE: "HOSTING_UNAVAILABLE";
+    HOSTING_USER_MISMATCH: "HOSTING_USER_MISMATCH";
+    HOSTING_EPOCH_MISMATCH: "HOSTING_EPOCH_MISMATCH";
+    HOSTING_REVISION_MISMATCH: "HOSTING_REVISION_MISMATCH";
+    HOSTING_ARCHIVE_CONFLICT: "HOSTING_ARCHIVE_CONFLICT";
+    HOSTING_HELD: "HOSTING_HELD";
+    HOSTING_HOLDER_MISMATCH: "HOSTING_HOLDER_MISMATCH";
+    HOSTING_LEASE_EXPIRED: "HOSTING_LEASE_EXPIRED";
+    SANDBOX_UNAVAILABLE: "SANDBOX_UNAVAILABLE";
+    SANDBOX_NOT_RUNNING: "SANDBOX_NOT_RUNNING";
+    EVALUATION_ACTIVE: "EVALUATION_ACTIVE";
+    EVALUATION_EXECUTOR_UNSUPPORTED: "EVALUATION_EXECUTOR_UNSUPPORTED";
+    EVALUATION_HOSTING_ACTIVE: "EVALUATION_HOSTING_ACTIVE";
+    SANDBOX_UPGRADE_CONFLICT: "SANDBOX_UPGRADE_CONFLICT";
+    SANDBOX_RECOVERY_CONFLICT: "SANDBOX_RECOVERY_CONFLICT";
+    SANDBOX_UPGRADE_REJECTED: "SANDBOX_UPGRADE_REJECTED";
+    SANDBOX_RELEASE_UNAVAILABLE: "SANDBOX_RELEASE_UNAVAILABLE";
+    SANDBOX_SESSION_UNBOUND: "SANDBOX_SESSION_UNBOUND";
+    PREDECESSOR_STILL_RUNNING: "PREDECESSOR_STILL_RUNNING";
+    PREDECESSOR_EXIT_UNKNOWN: "PREDECESSOR_EXIT_UNKNOWN";
+    ENTRY_TOKEN_REJECTED: "ENTRY_TOKEN_REJECTED";
+    ENTRY_TOKEN_EXPIRED: "ENTRY_TOKEN_EXPIRED";
+    ENTRY_TOKEN_SANDBOX_MISMATCH: "ENTRY_TOKEN_SANDBOX_MISMATCH";
+    OPERATOR_INVALID_CREDENTIALS: "OPERATOR_INVALID_CREDENTIALS";
+    OPERATOR_INVALID_2FA: "OPERATOR_INVALID_2FA";
+    OPERATOR_ROLE_REQUIRED: "OPERATOR_ROLE_REQUIRED";
+    OPERATOR_ACCOUNT_INACTIVE: "OPERATOR_ACCOUNT_INACTIVE";
+    OPERATOR_RATE_LIMITED: "OPERATOR_RATE_LIMITED";
+    OPERATOR_SESSION_LIMIT: "OPERATOR_SESSION_LIMIT";
+    OPERATOR_LOGIN_RATE_LIMITED: "OPERATOR_LOGIN_RATE_LIMITED";
+    OPERATOR_SESSION_REQUIRED: "OPERATOR_SESSION_REQUIRED";
+    OPERATOR_SESSION_EXPIRED: "OPERATOR_SESSION_EXPIRED";
+    SUB2API_UNAVAILABLE: "SUB2API_UNAVAILABLE";
+    SERVICE_CREDENTIAL_REQUIRED: "SERVICE_CREDENTIAL_REQUIRED";
+    SERVICE_CREDENTIAL_REJECTED: "SERVICE_CREDENTIAL_REJECTED";
+    CUSTOMER_MESSAGES_UNAVAILABLE: "CUSTOMER_MESSAGES_UNAVAILABLE";
+    MESSAGE_PENDING_VERIFICATION: "MESSAGE_PENDING_VERIFICATION";
+    MAPPING_NOT_ALLOWED: "MAPPING_NOT_ALLOWED";
+    SPACE_TOKEN_REQUIRED: "SPACE_TOKEN_REQUIRED";
+    SPACE_TOKEN_REJECTED: "SPACE_TOKEN_REJECTED";
+    SEGMENT_SPACE_FORBIDDEN: "SEGMENT_SPACE_FORBIDDEN";
+    CLOUD_NOT_ELIGIBLE: "CLOUD_NOT_ELIGIBLE";
+    OPERATION_MISMATCH: "OPERATION_MISMATCH";
+    SANDBOX_PROVISION_CONFLICT: "SANDBOX_PROVISION_CONFLICT";
+    PROVISION_ALREADY_COMPLETED: "PROVISION_ALREADY_COMPLETED";
+    HANDOFF_CONFLICT: "HANDOFF_CONFLICT";
+    HANDOFF_REVISION_MISMATCH: "HANDOFF_REVISION_MISMATCH";
+    HANDOFF_NOT_CANCELLABLE: "HANDOFF_NOT_CANCELLABLE";
+    INSTALLATION_SESSION_REQUIRED: "INSTALLATION_SESSION_REQUIRED";
+    INSTALLATION_CHALLENGE_REJECTED: "INSTALLATION_CHALLENGE_REJECTED";
+    INSTALLATION_CHALLENGE_EXPIRED: "INSTALLATION_CHALLENGE_EXPIRED";
+    INSTALLATION_BINDING_CONFLICT: "INSTALLATION_BINDING_CONFLICT";
+    INSTALLATION_BINDING_REQUIRED: "INSTALLATION_BINDING_REQUIRED";
+    LOCAL_HOST_REPLACED: "LOCAL_HOST_REPLACED";
+    HANDOFF_STATE_CONFLICT: "HANDOFF_STATE_CONFLICT";
+    HANDOFF_IMPORT_REQUIRED: "HANDOFF_IMPORT_REQUIRED";
+    HANDOFF_MANIFEST_MISMATCH: "HANDOFF_MANIFEST_MISMATCH";
+    PLACEMENT_KEY_CONFLICT: "PLACEMENT_KEY_CONFLICT";
+    PLACEMENT_KEY_NOT_READY: "PLACEMENT_KEY_NOT_READY";
+    PLACEMENT_TOKEN_REJECTED: "PLACEMENT_TOKEN_REJECTED";
+    SALES_CASES_SHOP_ONLY: "SALES_CASES_SHOP_ONLY";
+    OBSERVATION_BINDING_REJECTED: "OBSERVATION_BINDING_REJECTED";
+    OBSERVATION_EXPIRED: "OBSERVATION_EXPIRED";
+    OBSERVATION_TOO_LARGE: "OBSERVATION_TOO_LARGE";
+    CUSTOMER_SHOP_REQUIRED: "CUSTOMER_SHOP_REQUIRED";
+    CUSTOMER_NOT_FOUND: "CUSTOMER_NOT_FOUND";
+    CUSTOMER_REVISION_CONFLICT: "CUSTOMER_REVISION_CONFLICT";
+    CUSTOMER_OPERATION_MISMATCH: "CUSTOMER_OPERATION_MISMATCH";
+    CUSTOMER_SOURCE_STALE: "CUSTOMER_SOURCE_STALE";
+    CUSTOMER_ACTIVE_CASE_EXISTS: "CUSTOMER_ACTIVE_CASE_EXISTS";
+    CUSTOMER_WRITE_FENCED: "CUSTOMER_WRITE_FENCED";
+    CUSTOMER_EVIDENCE_PENDING: "CUSTOMER_EVIDENCE_PENDING";
+    CUSTOMER_SEND_UNRESOLVED: "CUSTOMER_SEND_UNRESOLVED";
+    CUSTOMER_DATA_TOO_LARGE: "CUSTOMER_DATA_TOO_LARGE";
+    CUSTOMER_CAPACITY_EXCEEDED: "CUSTOMER_CAPACITY_EXCEEDED";
+    CUSTOMER_RATE_LIMITED: "CUSTOMER_RATE_LIMITED";
+    CUSTOMER_DATA_UNAVAILABLE: "CUSTOMER_DATA_UNAVAILABLE";
+    INTERNAL: "INTERNAL";
+}>;
+/** One member of {@link ERROR_CODES}. */
+export type ErrorCode = z.infer<typeof ErrorCode>;
+/** Media type of every error response. */
+export declare const PROBLEM_MEDIA_TYPE = "application/problem+json";
+/** One failed validation check. `path` locates the field; input values are never echoed. */
+export declare const ValidationIssue: z.ZodObject<{
+    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    code: z.ZodString;
+}, z.core.$strip>;
+/** One failed validation check. */
+export type ValidationIssue = z.infer<typeof ValidationIssue>;
+/** 仅用于知识库管理核对/清空的受控 RFC 9457 扩展，不承载任意上游原因。 */
+export declare const KnowledgeDistillProblemReason: z.ZodEnum<{
+    processing_incomplete: "processing_incomplete";
+    generation_conflict: "generation_conflict";
+    scope_drift: "scope_drift";
+    document_mismatch: "document_mismatch";
+    publication_pause_required: "publication_pause_required";
+    task_result_unknown: "task_result_unknown";
+    scan_incomplete: "scan_incomplete";
+    preview_not_ready: "preview_not_ready";
+    preview_failed: "preview_failed";
+}>;
+export type KnowledgeDistillProblemReason = z.infer<typeof KnowledgeDistillProblemReason>;
+/**
+ * RFC 9457 problem details body returned by every error response. `code` is a string whose known
+ * values are {@link ERROR_CODES}; new codes are added within v1, so a client parses any string and
+ * narrows it with {@link ErrorCode}. The OpenAPI document declares the known values as
+ * `x-extensible-enum`.
+ */
+export declare const Problem: z.ZodObject<{
+    type: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodNumber;
+    code: z.ZodString;
+    requestId: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    testClaim: z.ZodOptional<z.ZodObject<{
+        issue: z.ZodObject<{
+            repo: z.ZodDefault<z.ZodString>;
+            number: z.ZodNumber;
+        }, z.core.$strict>;
+        demandName: z.ZodString;
+        claimedAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    reason: z.ZodOptional<z.ZodString>;
+    issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        code: z.ZodString;
+    }, z.core.$strip>>>;
+    conflict: z.ZodOptional<z.ZodObject<{
+        actualRevision: z.ZodOptional<z.ZodString>;
+        customerId: z.ZodOptional<z.ZodString>;
+        caseId: z.ZodOptional<z.ZodString>;
+        operationId: z.ZodOptional<z.ZodString>;
+        requestId: z.ZodOptional<z.ZodString>;
+        refresh: z.ZodLiteral<"reload">;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+/** RFC 9457 problem details body returned by every error response. */
+export type Problem = z.infer<typeof Problem>;

package/lib/types/agent-config-contract/errors.js

@@ -0,0 +1,202 @@
+/**
+ * Error model of the v1 API: RFC 9457 `application/problem+json` bodies with a closed `code` set.
+ * @module
+ */
+import { z } from 'zod';
+import { TestAccountClaim } from "./test-account-claim.js";
+/**
+ * Closed set of problem codes. Clients choose localized copy by `code` and fall back to generic copy
+ * for a code they do not know; `title` and `detail` are diagnostic only.
+ */
+export const ERROR_CODES = [
+    'MERCHANT_NOT_ALLOWED',
+    'MERCHANT_ACCOUNT_TYPE_UNSUPPORTED',
+    'MERCHANT_SUB_ACCOUNT_MISMATCH',
+    'MERCHANT_IDENTITY_NOT_FOUND',
+    'MERCHANT_IDENTITY_KIND_MISMATCH',
+    'MERCHANT_IDENTITY_UNAVAILABLE',
+    'MERCHANT_ALREADY_ALLOWED',
+    'MERCHANT_PREVIEW_CHANGED',
+    'SANDBOX_ALREADY_EXISTS',
+    'NAS_CAPACITY_INSUFFICIENT',
+    'NAS_USAGE_UNAVAILABLE',
+    'MERCHANT_TOKEN_UNAVAILABLE',
+    'TEST_ACCOUNT_NOT_REGISTERED',
+    'TEST_ACCOUNT_CLAIMED',
+    'TEST_ACCOUNT_CLAIM_HOLDER_MISMATCH',
+    'VALIDATION_FAILED',
+    'NOT_FOUND',
+    'SESSION_REQUIRED',
+    'SESSION_EXPIRED',
+    'NO_CURRENT_TENANT',
+    'TENANT_NOT_CURRENT',
+    'NOT_A_MEMBER',
+    'ADMIN_REQUIRED',
+    'RESOURCE_CENTER_UNAVAILABLE',
+    'CLOUD_MODELS_UNAVAILABLE',
+    'CLOUD_QUOTA_EXCEEDED',
+    'CLOUD_LOGIN_RATE_LIMITED',
+    'AGENT_CONFIGS_UNAVAILABLE',
+    'AGENT_CONFIG_PLAN_NOT_INITIALIZED',
+    'SHOP_ACCOUNT_CANNOT_JOIN',
+    'SHOP_ACCOUNT_CANNOT_SWITCH',
+    'SHOP_ACCOUNT_CANNOT_CREATE',
+    'SHOP_TENANT_CANNOT_REMOVE_MEMBER',
+    'SHOP_TENANT_NAME_IMMUTABLE',
+    'SHOP_TENANT_CANNOT_INVITE',
+    'INVITE_EXPIRED',
+    'INVITE_REVOKED',
+    'OWNER_IMMUTABLE',
+    'ROLE_NAME_TAKEN',
+    'VERSION_CONFLICT',
+    'OPERATION_CONFLICT',
+    'MATERIAL_REFERENCED',
+    'ASSET_CHECKSUM_MISMATCH',
+    'ASSET_COMMIT_IN_PROGRESS',
+    'ASSET_NOT_UPLOADED',
+    'ASSET_NOT_COMMITTED',
+    'MATERIAL_ARCHIVED',
+    'CLIENT_UPGRADE_REQUIRED',
+    'LOGIN_ATTEMPT_GONE',
+    'LOGIN_VERIFIER_MISMATCH',
+    'SERVICE_UNAVAILABLE',
+    'PLATFORM_IDENTITY_NOT_ALLOWED',
+    'PLATFORM_IDENTITY_MISMATCH',
+    'KNOWLEDGE_MANAGE_REQUIRED',
+    'KNOWLEDGE_OPERATION_NOT_ALLOWED',
+    'KNOWLEDGE_PERSONAL_USE_REQUIRED',
+    'KNOWLEDGE_SHOP_ONLY',
+    'KNOWLEDGE_CONFLICT',
+    'KNOWLEDGE_RUNTIME_CURSOR_EXPIRED',
+    'KNOWLEDGE_OPS_ADMIN_REQUIRED',
+    'KNOWLEDGE_RECOVERY_OUTCOME_UNKNOWN',
+    'KNOWLEDGE_DISTILL_OUTCOME_UNKNOWN',
+    'PREVIEW_STALE',
+    'AMAP_MCP_SHOP_ONLY',
+    'AMAP_MCP_METHOD_NOT_ALLOWED',
+    'AMAP_MCP_TOOL_NOT_ALLOWED',
+    'AMAP_MCP_TOO_LARGE',
+    'AMAP_MCP_UNAVAILABLE',
+    'AMAP_MCP_PROVIDER_LIMITED',
+    'AMAP_MCP_UPSTREAM_ERROR',
+    'AMAP_MCP_TIMEOUT',
+    'AMAP_MCP_PROTOCOL_ERROR',
+    'HOSTING_UNAVAILABLE',
+    'HOSTING_USER_MISMATCH',
+    'HOSTING_EPOCH_MISMATCH',
+    'HOSTING_REVISION_MISMATCH',
+    'HOSTING_ARCHIVE_CONFLICT',
+    'HOSTING_HELD',
+    'HOSTING_HOLDER_MISMATCH',
+    'HOSTING_LEASE_EXPIRED',
+    'SANDBOX_UNAVAILABLE',
+    'SANDBOX_NOT_RUNNING',
+    'EVALUATION_ACTIVE',
+    'EVALUATION_EXECUTOR_UNSUPPORTED',
+    'EVALUATION_HOSTING_ACTIVE',
+    'SANDBOX_UPGRADE_CONFLICT',
+    'SANDBOX_RECOVERY_CONFLICT',
+    'SANDBOX_UPGRADE_REJECTED',
+    'SANDBOX_RELEASE_UNAVAILABLE',
+    'SANDBOX_SESSION_UNBOUND',
+    'PREDECESSOR_STILL_RUNNING',
+    'PREDECESSOR_EXIT_UNKNOWN',
+    'ENTRY_TOKEN_REJECTED',
+    'ENTRY_TOKEN_EXPIRED',
+    'ENTRY_TOKEN_SANDBOX_MISMATCH',
+    'OPERATOR_INVALID_CREDENTIALS',
+    'OPERATOR_INVALID_2FA',
+    'OPERATOR_ROLE_REQUIRED',
+    'OPERATOR_ACCOUNT_INACTIVE',
+    'OPERATOR_RATE_LIMITED',
+    'OPERATOR_SESSION_LIMIT', // v1 兼容保留；登录路由不再返回。
+    'OPERATOR_LOGIN_RATE_LIMITED',
+    'OPERATOR_SESSION_REQUIRED',
+    'OPERATOR_SESSION_EXPIRED',
+    'SUB2API_UNAVAILABLE',
+    'SERVICE_CREDENTIAL_REQUIRED',
+    'SERVICE_CREDENTIAL_REJECTED',
+    'CUSTOMER_MESSAGES_UNAVAILABLE',
+    'MESSAGE_PENDING_VERIFICATION',
+    'MAPPING_NOT_ALLOWED',
+    'SPACE_TOKEN_REQUIRED',
+    'SPACE_TOKEN_REJECTED',
+    'SEGMENT_SPACE_FORBIDDEN',
+    'CLOUD_NOT_ELIGIBLE',
+    'OPERATION_MISMATCH',
+    'SANDBOX_PROVISION_CONFLICT',
+    'PROVISION_ALREADY_COMPLETED',
+    'HANDOFF_CONFLICT',
+    'HANDOFF_REVISION_MISMATCH',
+    'HANDOFF_NOT_CANCELLABLE',
+    'INSTALLATION_SESSION_REQUIRED',
+    'INSTALLATION_CHALLENGE_REJECTED',
+    'INSTALLATION_CHALLENGE_EXPIRED',
+    'INSTALLATION_BINDING_CONFLICT',
+    'INSTALLATION_BINDING_REQUIRED',
+    'LOCAL_HOST_REPLACED',
+    'HANDOFF_STATE_CONFLICT',
+    'HANDOFF_IMPORT_REQUIRED',
+    'HANDOFF_MANIFEST_MISMATCH',
+    'PLACEMENT_KEY_CONFLICT',
+    'PLACEMENT_KEY_NOT_READY',
+    'PLACEMENT_TOKEN_REJECTED',
+    'SALES_CASES_SHOP_ONLY',
+    'OBSERVATION_BINDING_REJECTED',
+    'OBSERVATION_EXPIRED',
+    'OBSERVATION_TOO_LARGE',
+    'CUSTOMER_SHOP_REQUIRED',
+    'CUSTOMER_NOT_FOUND',
+    'CUSTOMER_REVISION_CONFLICT',
+    'CUSTOMER_OPERATION_MISMATCH',
+    'CUSTOMER_SOURCE_STALE',
+    'CUSTOMER_ACTIVE_CASE_EXISTS',
+    'CUSTOMER_WRITE_FENCED',
+    'CUSTOMER_EVIDENCE_PENDING',
+    'CUSTOMER_SEND_UNRESOLVED',
+    'CUSTOMER_DATA_TOO_LARGE',
+    'CUSTOMER_CAPACITY_EXCEEDED',
+    'CUSTOMER_RATE_LIMITED',
+    'CUSTOMER_DATA_UNAVAILABLE',
+    'INTERNAL',
+];
+/** One member of {@link ERROR_CODES}. */
+export const ErrorCode = z.enum(ERROR_CODES);
+/** Media type of every error response. */
+export const PROBLEM_MEDIA_TYPE = 'application/problem+json';
+/** One failed validation check. `path` locates the field; input values are never echoed. */
+export const ValidationIssue = z
+    .object({
+    path: z.array(z.union([z.string(), z.number()])),
+    code: z.string(),
+})
+    .meta({ id: 'ValidationIssue' });
+/** 仅用于知识库管理核对/清空的受控 RFC 9457 扩展，不承载任意上游原因。 */
+export const KnowledgeDistillProblemReason = z.enum(['processing_incomplete', 'generation_conflict', 'scope_drift', 'document_mismatch', 'publication_pause_required', 'task_result_unknown', 'scan_incomplete', 'preview_not_ready', 'preview_failed']);
+/**
+ * RFC 9457 problem details body returned by every error response. `code` is a string whose known
+ * values are {@link ERROR_CODES}; new codes are added within v1, so a client parses any string and
+ * narrows it with {@link ErrorCode}. The OpenAPI document declares the known values as
+ * `x-extensible-enum`.
+ */
+export const Problem = z
+    .object({
+    type: z.string(),
+    title: z.string(),
+    status: z.number().int(),
+    code: z.string().meta({ 'x-extensible-enum': [...ERROR_CODES], description: 'MERCHANT_ACCOUNT_TYPE_UNSUPPORTED：不是天猫主账号或账号不存在；MERCHANT_IDENTITY_KIND_MISMATCH：账号层级不符（子账号预热：不是子账号或账号不存在）' }),
+    requestId: z.string(),
+    detail: z.string().optional(),
+    testClaim: TestAccountClaim.optional(),
+    reason: z.string().meta({ 'x-extensible-enum': [...KnowledgeDistillProblemReason.options], description: '可扩展原因文本；已知值供客户端收窄，代理仍只输出各接口允许的原因' }).optional(),
+    issues: z.array(ValidationIssue).optional(),
+    conflict: z.strictObject({
+        actualRevision: z.string().optional(),
+        customerId: z.string().optional(),
+        caseId: z.string().optional(),
+        operationId: z.string().optional(),
+        requestId: z.string().optional(),
+        refresh: z.literal('reload'),
+    }).optional(),
+})
+    .meta({ id: 'Problem' });