在渐进式交付流程中，决策（promote、abort 或 pause）直接决定了服务状态。虽然控制器负责执行这些决策，但验证决策的依据至关重要。现有的做法往往依赖运行时状态或模糊的日志，缺乏确定的证据链。dsh-canary-decision-proof 提供了一种离线、确定性的方法，证明已记录的 canary 决策遵循了显式、仅哈希的策略。

这是什么

这是一个控制器无关的离线证据验证器。它不执行 rollout，不查询 live metrics，不进行认证或授权，也不证明统计显著性或用户结果。它的核心职责是接收提供的证据，通过严格的逻辑规则进行重算，并生成一份内容寻址的报告。如果证据不完整，它会失败到 pause。

核心功能

该插件通过以下机制实现决策的可验证性：

  1. 证据完整性校验：插件会检查证据是否包含必要的指纹（artifact digest）、环境信息、收据、分析窗口、最大流量、最小窗口长度、观察者阈值、新鲜度以及指标规则。如果证据不完整、过期、未绑定或采样不足，判定逻辑会优先触发 pause。
  2. 确定性指标计算：指标值使用正固定点整数 (valueMicros)。对于“越高越好”的指标，回归值为 (baseline - canary) / baseline；对于“越低越好”的指标，回归值为 (canary - baseline) / baseline。使用整数基点进行判断，确保计算结果的确定性。
  3. 决策优先级：插件定义了明确的决策优先级顺序：
    • 证据不完整、过期或无效 → pause
    • 存在失败的指标 → abort
    • 其他情况 → promote
  4. 输出内容寻址报告：插件在显式的工作区相对 artifactDir 下写入报告。它拒绝路径转义和符号链接，仅生成包含哈希、计数、时间戳、定点比较、检查和裁决的报告，不包含原始业务文本或密钥。

环境与兼容性

  • 依赖环境：需要 Node.js 22 或更高版本。
  • DSH 版本兼容：与 DSH >= 0.1.2-alpha.4 兼容。
  • 权限注意：该插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。

典型用法

插件提供了 inspect 和 verify 两个主要命令，用于查看和验证证据。

# 验证证据并输出报告
node bin/dsh-canary-decision-proof.mjs verify examples/promote.json

# 检查证据详情
node bin/dsh-canary-decision-proof.mjs inspect examples/promote.json

除了命令行工具，插件还通过 dsh_canary_decision_inspect、dsh_canary_decision_verify 暴露接口，并支持通过独立的 stdio MCP 服务器调用 canary_decision_inspect 和 canary_decision_verify。

适用场景

该插件适合需要严格审计决策逻辑的场景。例如，在需要证明某次 promote 决策确实满足所有预设阈值和窗口条件时，可以使用此插件进行离线复核。它不适用于需要实时流量控制或自动回滚的场景（这通常由 dsh-ankh-guard 等插件负责）。

总结

dsh-canary-decision-proof 专注于“证明”而非“执行”。它将决策依据固化为可验证的证据，为渐进式交付提供了审计层面的确定性。对于需要严格合规或复杂回滚策略的团队，这是一个可控、离线的辅助验证工具。

目录页：dsh-canary-decision-proof
源码仓库：github.com/dongsheng123132/dsh-canary-decision-proof

In a progressive delivery process, decisions (promote, abort, or pause) directly determine service state. Although controllers are responsible for executing these decisions, validating the basis of a decision is critical. Existing practices often rely on runtime state or ambiguous logs, lacking a deterministic evidence chain. dsh-canary-decision-proof provides an offline, deterministic method to prove that recorded canary decisions followed explicit, hash-only policies.

What This Is

It is a controller-agnostic offline evidence verifier. It does not perform rollouts, query live metrics, authenticate or authorize, or prove statistical significance or user outcomes. Its core responsibility is to accept supplied evidence, recompute it using strict logical rules, and generate a content-addressed report. If the evidence is incomplete, it fails closed to pause.

Core Features

The plugin implements decision verifiability through the following mechanisms:

  1. Evidence Integrity Validation: The plugin checks whether the evidence contains required fingerprints (artifact digests), environment information, receipts, analysis windows, maximum traffic, minimum window length, observer thresholds, freshness, and metric rules. If the evidence is incomplete, stale, unbound, or undersampled, the decision logic prioritizes triggering pause.
  2. Deterministic Metric Computation: Metric values use positive fixed-point integers (valueMicros). For “higher-is-better” metrics, the regression value is (baseline - canary) / baseline; for “lower-is-better” metrics, the regression value is (canary - baseline) / baseline. Integer basis points are used for the comparison to ensure deterministic results.
  3. Decision Precedence: The plugin defines an explicit decision precedence order:
    • Evidence is incomplete, stale, or invalid → pause
    • A failed metric exists → abort
    • Otherwise → promote
  4. Content-Addressed Report Output: The plugin writes reports under an explicit workspace-relative artifactDir. It rejects path escapes and symbolic links, and generates only reports containing hashes, counts, timestamps, fixed-point comparisons, checks, and verdicts, without raw business text or secrets.

Environment and Compatibility

  • Runtime: Requires Node.js 22 or later.
  • DSH Compatibility: Compatible with DSH >= 0.1.2-alpha.4.
  • Permission Note: The plugin runs with the permissions of the current DSH process. Review the source code and license before installation.

Typical Usage

The plugin provides two primary commands, inspect and verify, to inspect and verify evidence.

# 验证证据并输出报告
node bin/dsh-canary-decision-proof.mjs verify examples/promote.json

# 检查证据详情
node bin/dsh-canary-decision-proof.mjs inspect examples/promote.json

In addition to the command-line tool, the plugin exposes interfaces through dsh_canary_decision_inspect and dsh_canary_decision_verify, and supports invoking canary_decision_inspect and canary_decision_verify through a standalone stdio MCP server.

Use Cases

The plugin is suitable for scenarios that require strict auditing of decision logic. For example, when it is necessary to prove that a given promote decision actually satisfied all preset thresholds and window conditions, this plugin can be used for offline review. It is not suitable for scenarios requiring real-time traffic control or automatic rollback (these are typically handled by plugins such as dsh-ankh-guard).

Summary

dsh-canary-decision-proof focuses on “proof” rather than “execution”. It solidifies decision rationale into verifiable evidence, providing audit-level determinism for progressive delivery. For teams that require strict compliance or complex rollback policies, this is a controlled, offline auxiliary verification tool.

Catalog Page: dsh-canary-decision-proof
Source Repository: github.com/dongsheng123132/dsh-canary-decision-proof