| 1 | /** |
| 2 | * vocabulary.ts — shared, locale-aware product vocabulary for codewhale.net. |
| 3 | * |
| 4 | * This module is the single source of truth for the exact product nouns a new |
| 5 | * user meets on the site: the Fleet/Workflow/Lane/Runtime execution nouns, |
| 6 | * the Plan/Work/Operate + Ask/Auto-Review/Full Access control vocabulary, the |
| 7 | * public Advisor role, and the fields that make route provenance legible. |
| 8 | * |
| 9 | * TRUTH CONTRACT: |
| 10 | * - `short.en` for every product term MUST equal the verbatim definition in |
| 11 | * docs/public-surface-facts.json → product.terminology, which is itself |
| 12 | * pinned verbatim against docs/FLEET.md by public-surface-contract.test.ts. |
| 13 | * - Mode and posture names MUST equal matrix.control.modes / |
| 14 | * matrix.control.permissionPostures (pinned against docs/MODES.md). |
| 15 | * - No marketing adjectives. Each description states behavior and boundary. |
| 16 | * |
| 17 | * EXTENSION PATH FOR NEW LOCALES (localization lane): |
| 18 | * Every user-facing string is a `{ en, zh }` pair. Add the new locale key to |
| 19 | * each pair (and widen the `LocalizedText` type) — the consuming components |
| 20 | * and tests pick it up without structural changes. The tests assert key |
| 21 | * parity across locales, so a missing translation fails deterministically. |
| 22 | */ |
| 23 | |
| 24 | export interface LocalizedText { |
| 25 | en: string; |
| 26 | zh: string; |
| 27 | } |
| 28 | |
| 29 | export interface ProductTerm { |
| 30 | /** The exact product noun. Never translate the noun itself. */ |
| 31 | term: "Fleet" | "Workflow" | "Lane" | "Runtime"; |
| 32 | /** One-line definition; `en` is verbatim from docs/public-surface-facts.json. */ |
| 33 | short: LocalizedText; |
| 34 | /** One-sentence elaboration used on docs pages. */ |
| 35 | long: LocalizedText; |
| 36 | } |
| 37 | |
| 38 | export const PRODUCT_TERMS: ProductTerm[] = [ |
| 39 | { |
| 40 | term: "Fleet", |
| 41 | short: { |
| 42 | en: "the user's model inventory: who is in the roster and which member is selected", |
| 43 | zh: "用户的模型清单：花名册中有哪些成员，以及选中了哪一位", |
| 44 | }, |
| 45 | long: { |
| 46 | en: "Fleet records member IDs and names, semantic roles, provider/model identities, and roster state.", |
| 47 | zh: "Fleet 记录成员 ID 和名称、语义角色、提供商/模型身份以及花名册状态。", |
| 48 | }, |
| 49 | }, |
| 50 | { |
| 51 | term: "Workflow", |
| 52 | short: { en: "what order the work follows", zh: "工作按什么顺序进行" }, |
| 53 | long: { |
| 54 | en: "What order the work follows: phases, gates, budgets, replay, and fan-in.", |
| 55 | zh: "工作按什么顺序进行：阶段、门禁、预算、回放和汇总。", |
| 56 | }, |
| 57 | }, |
| 58 | { |
| 59 | term: "Lane", |
| 60 | short: { en: "one running Workflow instance", zh: "一个正在运行的 Workflow 实例" }, |
| 61 | long: { |
| 62 | en: "One running Workflow instance and its live progress.", |
| 63 | zh: "一个正在运行的 Workflow 实例及其实时进度。", |
| 64 | }, |
| 65 | }, |
| 66 | { |
| 67 | term: "Runtime", |
| 68 | short: { |
| 69 | en: "where, how, and with what authority selected work executes", |
| 70 | zh: "选定工作在哪里、如何以及以何种权限执行", |
| 71 | }, |
| 72 | long: { |
| 73 | en: "Runtime owns the local or remote process, provider route, project/workspace trust, filesystem, network, secrets, approvals, sandbox, tools, and API boundary.", |
| 74 | zh: "Runtime 负责本地或远程进程、提供商路由、项目/工作区信任、文件系统、网络、密钥、审批、沙箱、工具和 API 边界。", |
| 75 | }, |
| 76 | }, |
| 77 | ]; |
| 78 | |
| 79 | export interface ControlTerm { |
| 80 | /** The exact control noun. Never translate the noun itself. */ |
| 81 | term: string; |
| 82 | kind: "mode" | "permission-posture"; |
| 83 | /** Behavioral description aligned with docs/MODES.md. */ |
| 84 | description: LocalizedText; |
| 85 | } |
| 86 | |
| 87 | /** TUI modes — cycle with Tab when the composer is empty (docs/MODES.md). */ |
| 88 | export const CONTROL_MODES: ControlTerm[] = [ |
| 89 | { |
| 90 | term: "Plan", |
| 91 | kind: "mode", |
| 92 | description: { |
| 93 | en: "Design-first and read-only: the primitive names stay stable while mutation and shell execution are centrally refused.", |
| 94 | zh: "设计优先且只读：基础工具名称保持稳定，但修改与 shell 执行会被集中拒绝。", |
| 95 | }, |
| 96 | }, |
| 97 | { |
| 98 | term: "Work", |
| 99 | kind: "mode", |
| 100 | description: { |
| 101 | en: "The default execution mode: multi-step tool use under the active permission posture, sandbox, and repository rules.", |
| 102 | zh: "新会话的默认工作模式：多步骤工具调用，每次 shell 调用都有审批提示把关。", |
| 103 | }, |
| 104 | }, |
| 105 | { |
| 106 | term: "Operate", |
| 107 | kind: "mode", |
| 108 | description: { |
| 109 | en: "Multitask conductor under the same permission posture, sandbox, and safety rules as Work; background worker dispatch is the default for separable work.", |
| 110 | zh: "在与 Work 相同的权限姿态、沙箱和安全规则下进行多任务调度；可分离工作默认派发给后台 worker。", |
| 111 | }, |
| 112 | }, |
| 113 | ]; |
| 114 | |
| 115 | /** Permission postures — cycle with Shift+Tab unless a non-Config modal owns input. */ |
| 116 | export const PERMISSION_POSTURES: ControlTerm[] = [ |
| 117 | { |
| 118 | term: "Ask", |
| 119 | kind: "permission-posture", |
| 120 | description: { |
| 121 | en: "The default: Codewhale asks when an unresolved choice materially changes authority, cost, scope, or outcome.", |
| 122 | zh: "默认值：当一个未决选择会实质改变权限、成本、范围或结果时，Codewhale 会询问。", |
| 123 | }, |
| 124 | }, |
| 125 | { |
| 126 | term: "Auto-Review", |
| 127 | kind: "permission-posture", |
| 128 | description: { |
| 129 | en: "Fully autonomous: never opens a user question; resolves ambiguity to a safe reversible interpretation or reports that it cannot proceed safely.", |
| 130 | zh: "完全自主：从不弹出用户提问；把歧义消解为安全可逆的解释，或明确报告无法安全继续。", |
| 131 | }, |
| 132 | }, |
| 133 | { |
| 134 | term: "Full Access", |
| 135 | kind: "permission-posture", |
| 136 | description: { |
| 137 | en: "Ordinary tool calls skip approval prompts; non-bypassable safety, repository-law, and managed-policy holds still fail closed.", |
| 138 | zh: "普通工具调用不再显示审批提示；不可绕过的安全、仓库法则和托管策略拦截仍然会失败关闭。", |
| 139 | }, |
| 140 | }, |
| 141 | ]; |
| 142 | |
| 143 | /** |
| 144 | * Route identity vocabulary. Requested and effective reasoning are separate: |
| 145 | * an adaptive request is not itself evidence of the tier a provider used. |
| 146 | * Routing source is provenance, not a provider or model substitute. Unknown |
| 147 | * effective values stay explicitly unknown. |
| 148 | */ |
| 149 | export const ROUTE_IDENTITY: { term: string; description: LocalizedText }[] = [ |
| 150 | { |
| 151 | term: "Provider", |
| 152 | description: { |
| 153 | en: "Who serves inference — a hosted API, a gateway, or a loopback local runtime (Ollama, vLLM, SGLang). A configured provider is never inferred from a model name.", |
| 154 | zh: "谁提供推理——托管 API、网关或本机回环本地运行时（Ollama、vLLM、SGLang）。绝不会根据模型名称推断已配置的 provider。", |
| 155 | }, |
| 156 | }, |
| 157 | { |
| 158 | term: "Model", |
| 159 | description: { |
| 160 | en: "The exact model on that provider. Codewhale treats models as selectable components; no provider or model is privileged over another.", |
| 161 | zh: "该提供商上的具体模型。Codewhale 把模型当作可选组件；任何提供商或模型都不享有特权。", |
| 162 | }, |
| 163 | }, |
| 164 | { |
| 165 | term: "Requested reasoning", |
| 166 | description: { |
| 167 | en: "The policy requested for the frozen route: inherit, off, low, medium, high, max, or auto. Auto permits adaptive reasoning; it never permits a silent provider or model switch.", |
| 168 | zh: "为冻结路由请求的策略：inherit、off、low、medium、high、max 或 auto。Auto 允许自适应思考，但绝不允许静默切换 provider 或模型。", |
| 169 | }, |
| 170 | }, |
| 171 | { |
| 172 | term: "Effective reasoning", |
| 173 | description: { |
| 174 | en: "The tier actually applied for the run when the runtime or provider can establish it. If it cannot be established, the value is unavailable — never copied from the request or invented.", |
| 175 | zh: "运行时或 provider 能够确认时，显示该次运行实际采用的档位；无法确认时标为暂不可用，绝不从请求值复制或臆造。", |
| 176 | }, |
| 177 | }, |
| 178 | { |
| 179 | term: "Routing source", |
| 180 | description: { |
| 181 | en: "Why this configured route was selected, such as an explicit member profile or inherited session setting. Missing provenance stays unavailable rather than being guessed.", |
| 182 | zh: "说明为何选择这条已配置路由，例如显式成员档案或继承的会话设置。缺失的来源保持暂不可用，绝不猜测。", |
| 183 | }, |
| 184 | }, |
| 185 | ]; |
| 186 | |
| 187 | /** Public advisory role vocabulary; legacy spellings are input compatibility. */ |
| 188 | export const ADVISORY_ROLE = { |
| 189 | term: "Advisor", |
| 190 | description: { |
| 191 | en: "The public read-only advisory fleet role. The historical consultant and oracle spellings remain compatibility aliases for saved configuration and replay only; new product surfaces say Advisor.", |
| 192 | zh: "面向用户的只读 fleet 咨询角色。历史拼写 consultant 与 oracle 仅作为已保存配置和回放的兼容别名保留；新的产品界面统一使用 Advisor。", |
| 193 | }, |
| 194 | } as const; |
| 195 | |
| 196 | /** |
| 197 | * Measurement truth — what the site may claim about benchmark-style numbers. |
| 198 | * These are policy statements, not results: the site publishes no leaderboard, |
| 199 | * and any future number must carry its exact route identity and harness. |
| 200 | */ |
| 201 | export const MEASUREMENT_PRINCIPLES: LocalizedText[] = [ |
| 202 | { |
| 203 | en: "Provider token and cache usage is shown locally when the provider reports it; unknown usage stays unknown and is never displayed as zero.", |
| 204 | zh: "当提供商上报时，token 与缓存用量会在本地显示；未知用量保持未知，绝不显示为零。", |
| 205 | }, |
| 206 | { |
| 207 | en: "Costs, progress, capabilities, and delivery state are shown only when a source establishes them. Unavailable values remain unavailable rather than becoming zero or success.", |
| 208 | zh: "成本、进度、能力和交付状态仅在有来源能够确认时显示。暂不可用的值保持暂不可用，绝不会变成零或成功。", |
| 209 | }, |
| 210 | { |
| 211 | en: "This site publishes no benchmark leaderboard. Any number Codewhale ever publishes must name its exact provider, model, requested and effective reasoning, and measurement harness alongside the result.", |
| 212 | zh: "本站不发布基准排行榜。Codewhale 今后发布任何数字时，都必须同时给出确切的提供商、模型、请求与实际思考档位和测量工具链。", |
| 213 | }, |
| 214 | ]; |
| 215 |