Brabo API (0.1.0)

正常运行时一个密钥；AUTH_JWT_SECRET 轮换期间两个。

不存在的邮箱、错误的密码和被锁定的账户都返回完全相同的 401 响应——相同的响应体，相同的状态码。

始终返回 204，即使令牌未知——在此返回 401 将成为令牌有效性的探测口。

成功时跳转到 WEB_ORIGIN/ 并已设置会话 cookie；失败时跳转到 WEB_ORIGIN/login?oauth_error=1，不说明原因。

state 以其自身专用用途经 HMAC 签名——绝不使用 git 连接到项目流程的签名（见 ADR 0084）。

所出示的 refresh 会被消耗。重复出示已轮换的令牌会撤销整个令牌族并记录一条安全事件——即使原因只是客户端重复提交。

无论是新地址还是已注册地址都返回 202——响应不会透露账户是否存在。第二种情况下不会创建任何内容，地址所有者会收到通知。

无论地址已知还是未知都返回 202。这也是从 Keycloak 导入且尚未设置密码的用户所走的路径。

撤销该用户的所有会话。不签发令牌：重置密码的人会被引导去登录，这样邮箱被攻破并不等于一步就接管了账户。

流程 gate 的声明式索引（ADR 0054）。界面从这里推导存在哪些步骤以及每一步由谁判定，而不是在代码中重复这份列表——过去正是这样在无人察觉中过时的。

停滞超过 2 小时的 gate 周期会被暂停，而不是自行重启（ADR 0207）。这是恢复它的人工操作。

之所以公开，是因为到达这里的是用户的浏览器，从提供商跳转而来，没有 api 会话。但它并非不受限制：state 经 HMAC 校验，没有有效的 state 调用会被拒绝。从不返回 JSON——始终重定向，因为在浏览器导航中显示原始错误体体验极差。

为已声明的 blame 待办项（PHASE 26b）打基础——逐行标注编辑器的界面尚不存在。当文件超过标注行数上限时，truncated 会发出提示。

为丰富的下拉菜单（PHASE 26b）打基础——目前 ref 选择器是普通文本框。ahead/behind 相对于仓库的默认分支；提供商无法计算时为 null（诚实的降级，而非错误）。它不是 listBranches（Gitflow 引导使用的那个）——而是一个独立的操作，因为丰富信息需要为每个分支额外调用一次提供商。

UTF-8，超过字节上限时截断并带 truncated: true。逃出项目文件夹的路径会被 RN-095 的中央检查以 400 拒绝——绝不用 404，那会招来探测。

为可导航列表（PHASE 26b）打基础——目前 diff 只能通过已知 id 访问（例如从 Approvals 进入）；此路由解决了无需记住 id 也能找到它的问题。当列表超过单次调用上限时，truncated 会发出提示。

patch 为 null 用于区分提供商没有交付文本（二进制文件或补丁过大）与文本返回为空这两种情况。把两者混为一谈，界面就会说一个已更改的二进制文件没有变化。当文件列表超过上限时，truncated 字段会发出提示。

搜索不是 git 契约中的操作：它是在树和内容之上组合而成的，因此是唯一一个成本随仓库大小增长的读取。三项预算为其设限——遍历的目录数、打开的文件数和返回的匹配数——truncated 表示它已停止。filesScanned 显示它产生的成本。

按契约设计不递归：标签页按需导航，而请求大型仓库的整棵树正是本阶段禁止的流量放大器。当该层级超过条目上限时，truncated 会发出提示。

不重定向：返回 URL，由客户端决定何时让浏览器跳转。state 经 HMAC 签名，正是这一点防止回调被伪造。

同步执行：只有在整个引导过程（永久分支、保护规则、模板）运行完毕后才会返回响应——背后没有 worker 也没有队列。它是幂等且可恢复的，因此失败后再次调用会从失败的步骤继续。通过 GET /projects/:id/git/bootstrap 跟踪进度并读取失败原因。

用 getRepo 校验访问权限，并生成引导将要执行的计划（dry-run）——缺失的分支、缺失的保护规则、文件。不会在仓库上执行任何操作：之后通过 plan/approve 或 plan/skip 做决定。重新接入同一个仓库会收敛（重新生成计划而不会重复记录）。

当前处于哪一步、是否失败以及在哪里失败、尝试了多少次。逐步的细节来自专用会话中的 bootstrap.step_* 事件。

protect_branches 在免费计划的私有仓库上会失败，向导会事先就此发出警告。没有这个出口，唯一的按钮是“重试”，而它总会因同样的原因失败——provision_failed 又会让仪表盘把项目重定向回置备页面，使其永远无法进入。只有保护步骤的失败可以被确认：它是最后一步，也是唯一一个失败后仍留下可用仓库的步骤。产品自身的合并锁（RN-006）不依赖提供商的保护，会继续生效。

存在计划且 decision: null 是什么都不会运行的状态——等待批准或按原样接入（RN-045）。

批准是全有或全无的：批准零散的步骤会破坏 dev←main, qa←dev, rc←qa 级联。实际运行的是在执行时重新推导的计划——等于或小于所展示的，绝不会更大。

记录决定，不触碰仓库。计划作为刻意未应用内容的证据保留，引导游标也不会被改动——没有任何步骤运行。

执行 select 1。只透露数据库是否响应；不透露拓扑或版本。之所以公开，是因为调用方是 kubelet，它不携带令牌。

故意不访问数据库。如果访问，一个缓慢的 Postgres 会让所有副本同时重启，把性能降级变成全面停机。Pod 由 /health 从负载均衡中摘除。

不是 JSON：而是 exposition 格式的 text/plain。出于必要而公开（抓取器不携带令牌），并通过网络加以限制——生产环境的 Ingress 在边缘阻止此路径，NetworkPolicy 只允许监控命名空间访问。

GitHub Releases 代理——platform 只接受 linux-x64、linux-arm64、darwin-arm64。无需认证：二进制文件不是机密。在返回任何内容之前，字节会与同一 Release 的 checksums.txt 核对（ADR 0149，RN-525）；该路由不验证清单的签名——这是完整性而非来源，验证签名的是 install.sh。

供一行命令安装器使用，它运行在未配置邮件传输的环境中：生成的 .env 不含任何邮件变量，MAIL_TRANSPORT 回落为 log，而常规注册会等待一封永远不会到达的邮件。账户一出生即已验证，因为运行安装器的人已经证明了比控制一个邮箱更强的东西——他们控制着这台机器、.env 和 Docker 守护进程。常规注册不受影响。当安装中已有任何用户时以 409 拒绝：条件针对的是安装，而非这个邮箱，因此迁移恢复会通过同一检查让这一步保持静默。密码绝不在此生成，除了 argon2id 哈希外也绝不存储在任何地方；个人 workspace（RN-410）在同一事务中创建。

注册表只做描述，不做执行：没有任何 gate 会因为它而被强制执行，在此修改字段也不会改变任何行为。每个 gate 都说明其通过的证据存放在哪里（evidencia），因为并非所有证据都在事件日志中。

如果同一 name 已存在哈希相同的版本，则不会创建新版本——而是返回已有版本（幂等命中不会改变 HTTP 状态：为简单起见始终为 201——响应体与新建时完全相同）。

指定 version 时按相等查找；省略时查找最新的 active 版本。模板（或所请求的版本）不存在时返回 404。

供一行命令安装器在创建第一个账户后立即使用：本地代理需要一份凭据，而此前唯一存在的凭据绑定在项目上——而此时安装中还没有任何项目。密钥对在机器上生成，只有公开的一半到达这里；请把返回的 id 作为 kid 写入私有 JWK（RN-475），这是磁盘上的文件与服务器上公开一半之间唯一的关联。请求体中故意没有 userId：所有者是该安装的唯一用户，由 api 解析，因此持有服务令牌绝不意味着可以选择为谁签发凭据。注册即替换：所有者现有的机器密钥在同一事务中被撤销，因此重装的机器可以工作，也不可能存在上千把机器密钥。项目密钥（ADR 0118）不受影响。

绝不会因为某一个提供商而失败：每个提供商在报告中各自作答，附带被跳过的原因以及失败时的来源。未响应的提供商会被跳过，而不是被标记为不可用。

与 Backlog 标签页相同的 epic → story → task 树，经由同一用例（每个项目三次读取，绝无 N+1）。PO 借此看到孤立的 epic 和没有任务的 story，而不是重新创建已有内容（RN-164）。

项目所有会话中的每一条 artifact.business_rule——而不仅是当前会话的，那曾是 PO 启动上下文的上限——带有完整的 description 以及哪些 story 已引用每条规则。uncoveredCount 是待办项：没有任何 story 覆盖的规则（RN-164）。完全没有规则的项目返回 200 和空列表：“尚未捕获任何规则”不是错误。

仅由 engine 调用，当 Engine.Actions.TerminalExecutor 判定命令应在真实容器内执行时（execution_mode: container 且有已登记的 running 记录）。代理到 ContainerBrokerPort.exec（ADR 0130/0134）——broker 五个操作中最后一个获得真实调用方的。响应中的 sucesso: false——绝不是抛出的错误——是 broker 拒绝或不可达时的正常形态：在登记的 running 记录与本次调用之间，容器可能已在外部死亡或被移除（RN-486，登记状态与观测状态绝不合并），这是命令失败，而非传输错误。

项目标识、执行模式以及 Architect 当前的镜像决定。broker 在把任何东西交给守护进程之前都会重新校验——从这里读取并不等于信任它，拒绝时会指明字段。不返回任何绝对路径：绑定源由守护进程依据宿主机文件系统解析，而来自 api 容器内部的路径会静默挂载一个空文件夹。传递的是 localizacao（RN-503）——使用 broker 两个根目录中的哪一个，以及该根目录未覆盖的相对段。

返回干净的源地址（不嵌入凭据），对于远程提供商，还返回即时解密的 workspace 所有者令牌（RN-058）。使用方按每次调用注入令牌，绝不写入文件——.git/config 位于 RN-075 授予 dev agent 自动批准读取权限的文件夹内。