convex-self-heal

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gated production self-healing loop

受控生产环境自修复循环

Sentry/Datadog/Vercel can go error→investigate→draft-PR, but they treat the backend as opaque and stop at the human merge gate with an unverified diff. Convex can do the step they can't: because the error rows live in the user's own deployment and the fix can be rehearsed on a preview of that deployment, the platform certifies the fix against real invariants before anyone reviews it. This capability is the composition capstone — it wires sentinel (capture) → the findings bus (diagnose) → the fixers (repair) → migrate-rehearse/tsc/probe (certify) → a human PR (decide) → deploy-guard (promote). The human keeps the merge button; the machine does everything up to and including proving the fix works.

Sentry/Datadog/Vercel可以实现从错误→调查→生成PR草稿的流程，但它们将后端视为黑盒，在人工合并环节仅提供未经验证的代码差异便停止推进。Convex则能完成它们做不到的步骤：由于错误数据存储在用户自己的部署环境中，且修复方案可在该环境的预览版上预演，平台会在人工审核前就针对真实约束验证修复方案的有效性。这一功能是组合式能力的顶峰——它将哨兵（捕获）→发现总线（诊断）→修复器（修复）→migrate-rehearse/tsc/探测（验证）→人工PR（决策）→deploy-guard（推广）串联起来。人工保留合并权限，而机器负责完成包括验证修复有效性在内的所有前置工作。

Workflow

工作流程

GUARD: deploy-guard — this loop reads prod and PROPOSES prod changes; classify + announce the deployment and get the standing consent for the loop's scope up front (what classes of fix it may auto-prepare vs must always defer). Never auto-merge; the human merge is the fixed boundary.
CAPTURE: require sentinel (prod errors in the user's own deployment, redacted at write time). If absent, offer to install it and stop — there is nothing to heal without capture.
TRIAGE a new/ recurring error: pull it via the official MCP (data/run-once-query over the sentinel table, or the monitor's prod_error event). Classify: transient (retry/ignore — do NOT open a PR for a one-off network blip), config (env/secret — hand to env, never guess a secret), or a code/schema defect (proceed).
ROOT-CAUSE on the findings bus: run the relevant audit pass on the implicated function — convex-insights (the failing requests + stacks), convex-advisor (if it's a read-limit/OCC cause), convex-reviewer/convex-authz (if it's a logic/authz defect). Produce a bus finding with evidence (the stack + the reproducing input) and a fixCapability. If root cause is unclear, STOP and report — a wrong fix is worse than an open error.
REPAIR via the finding's fixCapability (convex-authz, reviewer fixers, convex-expert for perf) on a branch — never on prod directly.
CERTIFY against the backend's own invariants BEFORE proposing (this is the differentiator — do not skip any that apply): (a)
```
tsc --noEmit
```
clean; (b) if the fix touches schema/data, run it through migrate-rehearse on a preview seeded with a prod snapshot — the schema-conformance gate must pass on real-shaped data; (c) reproduce-then-confirm-gone: replay the error's triggering input against the fixed code (a convex-test case or an MCP run on the preview) and assert the failure no longer occurs; (d) no-regression: the finding must be gone AND no new bus finding introduced on the touched function. A fix that fails any applicable certification is NOT proposed — it's reported as 'attempted, could not certify' with what failed.
PROPOSE, never merge: open a PR (or a diff for review) containing the fix, the certification evidence (tsc result, rehearsal outcome, the reproduced-then-gone assertion), the original error + finding, and the reversibility note. Label the change class. The human reviews and merges.
PROMOTE on merge via deploy-guard's prod consent; after deploy, re-check the sentinel table +
```
logs
```
(failures) to confirm that error signature stops recurring (do NOT use
```
insights
```
for this — it tracks only OCC/read-limit perf events, not arbitrary error signatures) — the loop is only closed when the error stops recurring in prod. If it recurs, reopen with the new evidence.
BOUND it: only classes the user pre-approved in step 1 are auto-prepared (default-safe set: validator fixes, missing-index adds, ownership-check adds, non-destructive backfills); anything destructive, security-sensitive beyond an added check, or ambiguous is always deferred to explicit human direction. Log every action to an append-only record so the loop is auditable.

防护机制：deploy-guard——该循环读取生产环境数据并提议生产环境变更；预先对部署进行分类和公示，并获取用户对循环范围的持续同意（即哪些类型的修复可自动准备，哪些必须始终交由人工处理）。绝不自动合并；人工合并是不可逾越的边界。
捕获：需要哨兵机制（用户自身部署环境中的生产错误，写入时已脱敏）。若未部署哨兵，则提供安装选项并终止流程——没有捕获机制就无法进行修复。
分类排查新/重复错误：通过官方MCP（对哨兵表执行一次性数据查询，或监控prod_error事件）获取错误信息。分类：瞬态错误（重试/忽略——勿为一次性网络波动创建PR）、配置错误（环境/密钥——交由环境管理，绝不猜测密钥）、代码/架构缺陷（继续流程）。
根因定位（通过发现总线）：对相关函数运行对应的审计流程——convex-insights（失败请求+调用栈）、convex-advisor（若为读取限制/OCC原因）、convex-reviewer/convex-authz（若为逻辑/权限缺陷）。生成包含证据（调用栈+复现输入）和fixCapability的总线发现结果。若根因不明确，则终止流程并上报——错误的修复比未解决的错误更糟糕。
修复：基于发现结果中的fixCapability（convex-authz、reviewer修复器、convex-expert用于性能问题）在分支上进行修复——绝不直接在生产环境操作。
验证（在提议修复前针对后端自身约束进行，这是核心差异——请勿跳过任何适用步骤）： (a)
```
tsc --noEmit
```
执行无错误； (b) 若修复涉及架构/数据，在填充了生产环境快照的预览版上运行migrate-rehearse——架构一致性检查必须通过真实形态的数据验证； (c) 复现后确认消除：将触发错误的输入在修复后的代码上重新执行（通过convex-test用例或在预览版上运行MCP），并断言故障已消除； (d) 无回归：原发现的问题必须已解决，且被修改的函数未产生新的总线发现结果。任何未通过适用验证步骤的修复都不会被提议——会被上报为“已尝试，但无法通过验证”并说明失败原因。
提议（绝不合并）：创建包含修复内容、验证证据（tsc结果、预演结果、复现后消除的断言）、原始错误+发现结果、可逆性说明的PR（或供审核的代码差异）。标注变更类型。由人工审核并合并。
推广：合并后通过deploy-guard的生产环境同意机制进行部署；部署完成后，重新检查哨兵表+
```
logs
```
（失败记录）以确认错误特征不再出现（请勿使用
insights
进行此检查——它仅跟踪OCC/读取限制性能事件，而非任意错误特征）——只有当生产环境中错误不再复发时，循环才会结束。若错误再次出现，则结合新证据重新开启流程。
边界限制：仅步骤1中用户预先批准的类型可自动准备修复（默认安全集合：验证器修复、添加缺失索引、添加所有权检查、非破坏性回填）；任何破坏性、超出新增检查范畴的安全敏感操作或不明确的变更，都必须始终交由人工明确处理。所有操作都记录到仅追加的日志中，确保循环可审计。

Rules

规则

The human keeps the merge button — this loop prepares and certifies fixes, it NEVER auto-merges or auto-deploys to prod (matches the industry boundary: no credible system ships unattended prod auto-merge).
Certify before proposing: tsc + (schema→migrate-rehearse on a prod-snapshot preview) + reproduce-then-confirm-the-failure-is-gone + no new bus finding. An uncertified fix is reported as 'could not certify', never proposed as done.
Triage first: transient blips get retried/ignored, config errors go to env (never guess a secret), only real code/schema defects enter the repair loop.
Repair on a branch/preview, never on prod directly; promote only through deploy-guard's fresh prod consent.
Only pre-approved fix classes are auto-prepared (default-safe: validator/index/ownership/non-destructive backfill); destructive or ambiguous changes are always deferred to the human.
Close the loop for real: after merge+deploy, confirm the error signature stops recurring via the sentinel table + logs (not insights, which only sees perf events); reopen if it persists.
Every action is logged to an append-only, auditable record; data residency stays in the user's own deployment (sentinel discipline).
If root cause is unclear, STOP and report — an uncertain fix is worse than an open, visible error.

人工保留合并权限——该循环仅准备并验证修复方案，绝不自动合并或自动部署到生产环境（符合行业边界：没有可信系统会在无人值守的情况下自动合并生产环境变更）。
先验证再提议：tsc +（涉及架构→在生产快照预览版上运行migrate-rehearse）+ 复现后确认故障消除 + 无新总线发现结果。未通过验证的修复会被上报为“无法通过验证”，绝不会作为已完成的修复提议。
先分类排查：瞬态波动进行重试/忽略，配置错误交由环境管理（绝不猜测密钥），只有真实的代码/架构缺陷才进入修复循环。
在分支/预览版上修复，绝不直接操作生产环境；仅通过deploy-guard的最新生产环境同意机制进行推广。
仅预先批准的修复类型可自动准备（默认安全类型：验证器/索引/所有权/非破坏性回填）；破坏性或不明确的变更始终交由人工处理。
真正结束循环：合并+部署后，通过哨兵表+日志确认错误特征不再出现（而非insights，它仅能看到性能事件）；若错误持续存在，则重新开启流程。
所有操作都记录到仅追加、可审计的日志中；数据驻留于用户自身部署环境（哨兵机制规范）。
若根因不明确，则终止流程并上报——不确定的修复比未解决、可见的错误更糟糕。