用途
add-a-feature-flag 用于在 rat-stack 体系中声明一个带类型的特性开关。开关通过预先声明的“证据阶梯”（ladder）选择行为：每次沿阶梯攀升都需要来自当前级别、且与确切读取作用域（read scope）对应的证据。读取作用域是开关取值及其证据的分区。
主要能力
技能围绕五部分展开：
-
判断开关是否适用：部署 Config 用于杀死开关和安全停止。KV 是最终一致的，另一位置可能保留旧值 60 秒或更久。
off会记录一次停止而无需等待审批，但不会让 KV 传播立即生效；必须对每个请求立即生效的停止需要更强的控制路径。示例中EVENTS_ENABLED因其选择云资源而保留在部署 Config 中。 -
声明阶梯：使用 core 或子声明模块中的
defineFlag，声明稳定的名称与 JSON 编码的值 schema、安全默认值、所有者、用途、字面量removeBy日期、非空且默认值在前的 rungs 元组、每个 rung 唯一名称与取值、authority（agent、arbiter 或 owner）、每个非最终 rung 的证据退出条件并以一个最终 rung 结束、子级提供的 readScope schema（省略则为字面 global 作用域）、kill 策略（默认 rung、上一 rung 或显式拒绝原因）以及 failurePolicy（默认 use-catalog-default，回退不安全时用 refuse）。声明会拒绝重复的 rung 名称或取值、错位的最终退出，以及与默认值不同的首值。 -
命名每个退出条件的证据：为每个退出测量指明被测量事件、读取位置（如验收报告或命名查询）、阈值（at-least 或 at-most，带有限计数）以及适用该测量的读取作用域。通过
record_flag_evidence记录测量值与来源引用；事件、读取位置和当前 rung 必须与声明匹配。较新的观测会替换该事件的当前测量，attempt 账本保留已提交的观测；翻转会清除当前证据，旧测量不能使之后对该 rung 的访问合格。schema 不匹配返回FlagScopeMismatch并带 repair 字段。 -
组合权限与存储：仅在子级的 operator 面上挂载
flip_feature_flag、record_flag_evidence、read_flag_ledger，公共读取方与沙箱保持只读。在分派前于子级组合中完成操作员请求认证；令牌认证保持在 Approval 之外，因为 off 会绕过审批。在组合处提供 capability Approval 服务，它授权所请求的角色、目标、作用域和引用的 approvalRef；角色字段或令牌名称本身不授予权限。高于 agent 的攀升需要非空审批引用以及 approval。flip_feature_flag 对攀升调用 implement 的审批门；对 off，其审计处理器提供一个始终授予的审批实现，可用拒绝其他所有调用的服务来测试该路径。默认账本使用@rat-stack/flags/cloudflare中的cloudflareFlagControlLayer()；子目录可传入defineFlagLedger(registry, deployOnly)返回的定义。每个 flag 与作用域路由到各自的 Durable Object；常规cloudflareFlagsLayer只读 KV，从不调用 Durable Object。DO 在一个存储事务中提交权威值、回执与脏投影标记，告警将已提交值投影到 KV；失败投影保留标记，Cloudflare 从 2 秒退避开始重试失败告警六次，最终失败后在下一个指数退避步长调度新窗口，操作员也可在恢复后调用内部 redrive 方法。成功翻转意味着已提交，而非全局可见。kvFlagControlLayer(registry, kv)默认以FlagAtomicityRequired拒绝权威翻转与证据写入，读取和 attempt 日志仍可用；可通过第三个参数传入{ authoritativeWrites: "accept-non-atomic-unserialized" }接受较弱保证，但这不会使并发写入变得安全；内存适配器为测试提供相同的领域行为。 -
验证与移除：跨作用域运行生成的翻转与证据历史，验证无本地证据不得攀升、无审批不得高权限攀升、只能经由 off 下降、每次尝试都被记录；植入每条规则的一次违反，记录失败属性与重放信息后恢复代码；在提交后、投影前崩溃，重建账本、redrive 并证明副本收敛，同时检查读取方在间隙期间可能看到旧值或声明的默认值。保持生命周期模型为绿，运行
pnpm turbo run check test build。在removeBy前移除开关及其调用点，或使其最终行为永久化。最后报告开关的用途、所有者、移除日期、作用域、退出条件、审批边界、所选适配器与证明，并指出本地测试无法确立的提供方行为。
使用方式与适用场景
该技能以声明模块和操作面函数的形式提供能力，适用于需要在多作用域下安全地逐级放出行为、并对证据和审批留痕的场景。
限制
KV 最终一致，停止不能立即全局生效；kv 适配器默认不支持原子权威写入；成功翻转不等于全局可见；本地测试无法确立提供方行为。