跳到主要内容

CommitErrorCode

const CommitErrorCode: object;

Defined in: packages/rxdb-plugin-working-tree/src/commit/commit-error-codes.ts:36

提交能力的稳定错误码

Type Declaration​

ambiguous_active_branch​

readonly ambiguous_active_branch: "ambiguous_active_branch" = 'ambiguous_active_branch';

发现 RxDBBranch.activated 有多行为真。

Remarks​

首次启用迁移命中即整条迁移回滚，不按查询顺序猜一个（FR-048）。「按顺序取第一条」 不是容错而是掷骰子：两行 active 时，用户的未提交条目挂在哪条分支上没有答案， 而猜错的那一半会被当成「另一条分支的历史」写进提交图。

零行 active 不走本码，走 CommitErrorCode.no_active_branch。

activationRevision 只防并发切换，替代不了这条基数不变量：它能告诉你「切换过了」， 不能告诉你「现在有两个 active」。

branch_not_materializable​

readonly branch_not_materializable: "branch_not_materializable" = 'branch_not_materializable';

首次启用迁移时，某个本地分支无法沿 RxDBChange 链无缺口物化。

Remarks​

迁移整体失败，不留下部分启用状态（FR-049）。断链的成因包括已被清理的 change、 被压缩掉的区间、无法配平的回滚标记。判定复用既有分支物化路径，MUST NOT 为迁移 另写第二套重放引擎。

唯一例外是 metadata-only 远端分支：它此时不创建 baseline 或 CommitBranchRef， 也不因此判失败——它的首次物化归 US-308，失败码是 CommitErrorCode.branch_not_materialized。

branch_not_materialized​

readonly branch_not_materialized: "branch_not_materialized" = 'branch_not_materialized';

metadata-only 远端分支首次切换时物化依据不足。

Remarks​

与 CommitErrorCode.branch_not_materializable 是两个时点、两种主体，不可互换： 前者是迁移期对既有本地分支的可物化性判定，后者是运行期对远端 metadata-only 分支的一次物化尝试。

全量回滚，来源分支保持 active，不留下部分目标投影；只留可安全重试 / 按 attempt 清理的 durable staging（FR-044）。成因包括网络失败、sync scope 漂移、配额不足、不收敛。

commit_capability_disabled​

readonly commit_capability_disabled: "commit_capability_disabled" = 'commit_capability_disabled';

未启用提交能力的数据库上调用了 enable() / isEnabled() 以外的成员。

Remarks​

与「静默降级成空实现」相对：未启用时库的行为必须与 v3 完全一致（FR-046）， 所以这些成员既不能假装成功、也不能返回空结果，只能在入口拒绝。

commit_capability_mismatch​

readonly commit_capability_mismatch: "commit_capability_mismatch" = 'commit_capability_mismatch';

写入绕过了工作树捕获——raw 写路径或批量写方法命中了版本化业务实体表。

Remarks​

三处共用本码：

  • adapter 四步 bypass 判定的第 3 步（写目标表 ∩ 版本化业务实体表 ≠ ∅ 且 被写列集 ⊄ untracked 字段域），见 contracts/adapter-contract.md；
  • upsertMany() / deleteByIds() 这两个够不到 rawQuery 的公开批量写方法；
  • EntityManager.notifyExternalUpdate() 对版本化实体。

拒绝发生在语句执行前，业务表零变化——不是写完再回滚。目标表或列集无法确定时 按拒绝处理（fail-closed），宁可误伤。

同一个码也用于「已启用的库遇到未声明该能力或协议版本不匹配的 writer」（FR-037）： 两者是同一件事——有人正在裸写版本化业务表。

commit_graph_corrupted​

readonly commit_graph_corrupted: "commit_graph_corrupted" = 'commit_graph_corrupted';

提交图上命中了可达损坏——commit() / restore() / switch-to 三条入口各自返回它。

Remarks​

「可达」指从该分支 ref 沿完整父链能走到的损坏。孤立损坏（不在任何 ref 的可达链上） 单独隔离，其他分支照常可用，不抛本码。

可达损坏使该分支 corrupted_read_only：仍可读取不依赖重放的当前投影、导出诊断、 切离该分支；但 MUST NOT 自动回退到较早 commit、空工作树或内存模式——那会把 「数据损坏」伪装成「数据就是这样」。判定由 FR-051 要求的共享 guard 实现， 三条入口在各自写事务内调用同一份，不各写一份。

mixed_versioned_cache_transaction​

readonly mixed_versioned_cache_transaction: "mixed_versioned_cache_transaction" = 'mixed_versioned_cache_transaction';

tracked 与 untracked 实体混进了同一个事务单元。

Remarks​

抛出即回滚整个事务（FR-046）。两者写语义不可调和：版本化实体写本地并进 changelog， QueryCache 实体先写远端再落可丢弃缓存；同批只会得到「一半进了变更历史、一半没有」。

承载者是既有的 RxDBMixedVersionedCacheTransactionError，它先于本模块存在。 origin='remote_sync' 不是 untracked——来源不改变是否被捕获。

no_active_branch​

readonly no_active_branch: "no_active_branch" = 'no_active_branch';

运行期发现一行 active 分支都没有。

Remarks​

与 CommitErrorCode.ambiguous_active_branch 是同一条基数不变量的两侧，但只有 这一侧非它不可：「至多一个」由 rxdb_branch.activeKey 的唯一约束在 schema 层拦住， 「至少一个」是一张空表也满足的条件，任何列约束都表达不了。

只有运行期入口抛本码。迁移期不抛：那一侧沿用既有 resolve_current_branch 语义 修复（优先激活 main，没有则创建）。两者的差别不是严格程度，是时点——迁移是唯一 一个「库里还没有 active 分支」属于正常状态的时刻。

运行期 MUST NOT 顺手修复：「有 main 就当没事」会把用户从 feature-x 静默挪到 main，未提交条目还挂在 feature-x 上，界面却显示一个干净的空工作树。

stale_active_branch​

readonly stale_active_branch: "stale_active_branch" = 'stale_active_branch';

写入时发现调用方手里的 active branch token 已经过期。

Remarks​

token 是 { branchId, activationRevision }，在读取 / 实例化实体时由调用方 realm 捕获； 另一个 realm 期间切换了分支，这一笔写入就带着旧 token 落到写路径上（FR-020、spec.md 场景 5）。

校验的是捕获到的那个 token。在事务里重新读一次 active 分支再把旧实体归过去，是明令禁止的 形态：那样永远不会失败，代价是用户在 feature-x 上编辑的实体被写进 main，而且没有任何提示。 同理，MUST NOT 只靠 BroadcastChannel 或内存状态承担这条正确性——两者都不跨进程重启。

拒绝发生在业务写入之前，业务表零变化。与 CommitErrorCode.no_active_branch 的分工：那条是「一行 active 都没有」，本条是 「有 active，但不是你以为的那一个」。

Remarks​

值即对外可见的码字符串：它会进日志、错误上报与跨 realm 的判别分支，不得改名。 键与值逐字相同，由 __tests__/commit/commit-error-codes.spec.ts 钉死。