From eb3a7d9f66a6f5aad17661a09c3119f3af1ae5fb Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Sun, 18 Oct 2026 00:55:53 +0800 Subject: [PATCH] docs(quality): qualify default delivery on SQLite performance Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- AGENTS.md | 9 ++++ .../typescript-control-plane-migration-v0.md | 16 +++++-- ...script-control-plane-migration-v0.zh-CN.md | 10 +++++ docs/development/testing-and-quality.md | 42 +++++++++++++++++++ 4 files changed, 74 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c75f3f4599..68a4333c01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -408,6 +408,15 @@ evidence gap that holds delivery qualification, not a passing skip. Keep code volume a cost: refactors should localize the next change, test and rollback, not introduce unused production structure. +Performance qualification follows the [default-provider rule](docs/development/testing-and-quality.md#default-provider-performance-qualification--默认-provider-性能资格). +The current default local authority is SQLite: its real-path performance gates +qualify default delivery. A File-only performance miss must be disclosed but +does not block that SQLite qualification. Explicit File performance work still +qualifies File separately. Keep correctness, durability, authority, recovery and +data-integrity checks for every affected supported backend, including File and +the required real PostgreSQL suite. Preserve historical failures and frozen +experiment criteria; changing the qualification scope is not a historical pass. + ### Bounded Future-Facing Refactoring During development and before approving or merging, apply the diff --git a/docs/architecture/rfcs/typescript-control-plane-migration-v0.md b/docs/architecture/rfcs/typescript-control-plane-migration-v0.md index 112ac1d6f3..41f6990086 100644 --- a/docs/architecture/rfcs/typescript-control-plane-migration-v0.md +++ b/docs/architecture/rfcs/typescript-control-plane-migration-v0.md @@ -2256,6 +2256,15 @@ matched durability baseline rather than the 2 ms kernel budget. A miss, or a tail regression hidden by a faster microbenchmark, is an owner review gate and cannot be silently relaxed. +Default delivery applies these performance gates to the shipped default profile, +currently SQLite for new local Goals. File performance is separate: disclose a +File-only miss without blocking an otherwise qualified default SQLite delivery. +Explicit File performance claims still require File qualification. Correctness, +durability, authority, data integrity and recovery remain required for every +affected supported backend. Declare the profile in existing review evidence; +preserve historical failures and frozen experiment criteria when a maintainer +changes the qualification scope. See the [validation rule](../../development/testing-and-quality.md#default-provider-performance-qualification--默认-provider-性能资格). + ## 7. Install, upgrade, and rollback The migration must not ask users to manage a service. The Python-transition @@ -2388,9 +2397,10 @@ exact diagnostic floors for wait, fallback and replan readers. One Goal-context reduction shares fresh counts with its nested helpers, while standalone calls remain fresh. Python retains fact/result codecs and original row identity; there is no persisted cache, new packet field or changed execution authority. -The same real File/SQLite entrypoints must qualify functional parity and the -original full-CLI cost gate together. Fewer crossings alone do not explain a -whole-CLI tail regression or complete writer/backup/default-provider retirement. +The same real File/SQLite entrypoints must qualify functional parity; full-CLI +performance follows the default SQLite profile and explicit additional targets +in §6. Fewer crossings alone do not explain a whole-CLI tail regression or +complete writer/backup/default-provider retirement. Fresh public-boundary scanning retains its specialized Python regex / Host IO owner. Characterization covers all eleven `splitlines` diff --git a/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md b/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md index 4d7cb3a032..7be61c6624 100644 --- a/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md +++ b/docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md @@ -1659,6 +1659,12 @@ transaction 要和 matched durability baseline 比较，而不是套用 2 ms ker 不达标，或用更快的 microbenchmark 隐藏 tail regression，都是 owner review gate， 不能静默放宽。 +默认交付将上述性能门槛用于实际发布的默认 profile，当前新建本地 Goal 为 SQLite。 +File 性能单独判断：仅 File 未达标须披露，但不阻塞其它条件已合格的默认 SQLite +交付；明确宣称 File 性能结果仍须取得 File 资格。受影响支持后端的正确性、持久化、 +authority、数据完整性和恢复要求保持。在既有评审证据声明 profile；维护者修订资格 +范围时保留历史失败和冻结实验标准，见[验证规则](../../development/testing-and-quality.md#default-provider-performance-qualification--默认-provider-性能资格)。 + ## 7. 安装、升级与回滚 迁移不能要求用户管理服务。Python 过渡版本要求 Node.js 22.18.0 或更新版本， @@ -1749,6 +1755,10 @@ TS 摘要批次；Python 保留旧格式解码、公开字段筛选及渲染。 查询命中情况覆盖。见[语义及回滚](../../reference/todo-work-counts.md)。这是 T3/L5 的 共享读取边界推进，不替代 D2/D3 或 provider 默认切换。 +上述共享读取边界仍须通过真实 File/SQLite 入口的功能等价验证；完整 CLI 性能 +按 §6 的默认 SQLite profile 及明确附加目标判断。减少 crossing 不能替代尾延迟 +解释，也不代表 writer／备份／默认 provider 退役已完成。 + fresh 公共边界扫描继续归现有专门 Python regex／Host IO owner。 Characterization 已覆盖全部十一种 `splitlines` 分隔符、Unicode regex 折叠、 casefold 扩展的假阳性、逐规则命中顺序、凭据引用、公共主机例外及字面量元字符； diff --git a/docs/development/testing-and-quality.md b/docs/development/testing-and-quality.md index 40acbe6915..127cebc773 100644 --- a/docs/development/testing-and-quality.md +++ b/docs/development/testing-and-quality.md @@ -301,6 +301,48 @@ hold delivery. workflow 会在临时实例上运行该 ladder row 与 service admission 套件，因此这条路径在 CI 与本地都会保持验证。没有安全的真实环境则暂停交付。 +#### Default-Provider Performance Qualification / 默认 Provider 性能资格 + +Default delivery qualifies the shipped default execution/storage profile. New +local Goals currently default to SQLite through the existing +[`goal_storage` configuration owner](../../loopx/capabilities/machine_configuration/goal_storage.py). +Apply the owning RFC's unchanged performance limits to the real SQLite caller, +complete workload and immutable base/head. A passing File result cannot replace +a failing SQLite result; a File-only performance miss does not veto an otherwise +qualified default SQLite delivery. + +The profile distinction applies to performance qualification. Correctness, +durability, permissions, data integrity, migration/recovery and supported-caller +compatibility remain mandatory on every affected backend. In particular, this +does not waive the real PostgreSQL requirement above, or permit a shared-runtime +regression that affects SQLite. A PR explicitly targeting File performance, +changing a provider default, or claiming another profile must qualify that +profile before claiming its result. + +Declare the profile in the existing PR/review validation matrix and CQR evidence; +do not add a separate approval workflow. Keep measured File regressions visible +as nonblocking performance risks for default SQLite delivery, with their actual +values, source and limits. They are not passing checks. When the maintainer +revises a previously declared profile, record a new scoped qualification and +the reason; retain the original failed observation and its original criteria. +This rule changes neither performance thresholds nor frozen benchmark/scoring, +resource, deadline or promotion contracts. + +默认交付按实际发布的默认执行／存储 profile 取得性能资格；当前新建本地 Goal +由既有 `goal_storage` owner 默认选择 SQLite。对真实 SQLite 入口、完整负载及 +不可变 base/head 使用所属 RFC 的原性能门槛。File 通过不能替代 SQLite 失败； +仅 File 性能未达标，不阻塞其它条件均合格的默认 SQLite 交付。 + +这一区分只适用于性能资格。受影响后端的正确性、持久化、权限、数据完整性、 +迁移／恢复及支持调用方兼容性仍必须验证；上面的真实 PostgreSQL 要求和影响 +SQLite 的共享运行时回归仍是门禁。明确优化 File、改变默认 provider 或宣称其它 +profile 的 PR，仍须验证相应 profile，才能宣称该结果。 + +在既有 PR／评审验证矩阵和 CQR 证据中说明 profile，不新增审批流程。File 的 +性能失败按实际数值、版本和门槛披露，作为默认 SQLite 交付的非阻塞性能风险， +不能写成通过。维护者修订既定 profile 时，保留原标准及失败，另记有明确原因的 +新范围资格；性能阈值及冻结 benchmark／评分、资源、时限和晋升合同均不改变。 + When one semantic owner fronts multiple authority providers, use a three-arm refactor comparison: the immutable legacy baseline, the file provider, and a real PostgreSQL provider. All three arms must start from the same