Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ GraphFold statically analyzes control coverage and safety evidence for productio
- Selecting an artifact establishes the analysis input, not a startup contract. Do not require a runnable entrypoint, `Main-Class`, a container installation or a supported startup script to analyze a selected JAR/WAR. Missing static type or call evidence remains an analysis gap, not a startup-compatibility verdict.
- Do not expand the task into JVM startup-option compatibility checks or runtime-environment behavior modeling. Reading archive contents to establish the static input is distinct from verifying how an application starts or behaves at runtime.
- Runtime executions in tests may independently validate fixture behavior. They are not the engine's analysis method, cannot establish control coverage, and cannot by themselves justify accepting an uncontrolled change. Golden cases must assert static verdicts independently of whether observed outputs differ.
- General uncontrolled-but-safe acceptance and its fixture/result schema are tracked in [issue #6](https://github.com/johnsonlee/GraphFold/issues/6). The existing Boolean corpus labels do not establish support for that path. When implementing it, fixtures must separately assert control coverage, cited safety evidence and the acceptance decision, with paired cases accepting sufficient whole-change proof while retaining the uncontrolled classification and rejecting insufficient proof. Do not manufacture such evidence or relabel an existing controlled case to claim the capability is implemented.
- Fixtures must separately assert control coverage, cited safety evidence and the acceptance decision, with paired cases accepting sufficient whole-change proof while retaining the uncontrolled classification and rejecting insufficient proof. Boolean corpus labels alone do not establish this capability. Use engine-produced evidence; do not manufacture certificates or relabel an existing controlled case.
- An original-bytecode safety summary must not override a selected fold in the method or its transitive dependencies. Original control implementations are not substitutes for the explicitly selected values. Preserve production instructions that a proof does not traverse; an inactive branch cannot erase a changed body, effect or exception obligation.
- A new exposure predicate before an AB check may be eliminated only when static proof establishes that it is effect-free, nonthrowing, terminating, unused elsewhere, and redundant after folding the selected control. Being read-only or not observed to execute is insufficient.
- Review requests must be evaluated against this scope. Do not implement runtime-analysis features merely to satisfy a review comment; explain the scope boundary and address the relevant static-analysis concern.
- Multi-release JARs use only the JDK selected by the corresponding build, supplied by the integration. Do not enumerate JDK variants or select using the engine JVM. BASE and HEAD retain their own build JDK metadata.
Expand Down
35 changes: 32 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

Detect uncontrolled code changes through conditional folding.

GraphFold compares two Git commits under the same explicit folding assumptions. The diff establishes what must be proved; Graphite selects call sites with Cypher and folds JVM code; the engine compares the remaining representation and reports changes that could not be proved controlled. AB tests are one use case, not an engine-specific concept.
GraphFold compares two Git commits under the same explicit folding assumptions. The diff establishes what must be proved; Graphite selects call sites with Cypher and folds JVM code; the engine reports control coverage, static safety evidence and an acceptance decision. AB tests are one use case, not an engine-specific concept.

The gate is fail-closed: both surviving changes and analysis failures produce `FAIL`. Surviving structural differences are reported as unverified changes; build, Git, and incomplete-analysis errors are diagnostics rather than invented source locations.
An uncontrolled change can pass with a complete static equivalence proof while remaining classified as uncontrolled. Surviving differences without sufficient proof and analysis failures produce `FAIL`. Build, Git, and incomplete-analysis errors are diagnostics rather than invented source locations.

See [the design](docs/design.md) for the proof model, gaps, and trade-offs, and [validation results](docs/validation.md) for the executed checks.

Expand Down Expand Up @@ -98,6 +98,10 @@ scenarios:

Queries express caller-authorized assumptions; an overly broad rule is an overly broad assumption. GraphFold does not infer the intended feature ID from the source. The default scenario limit is 32; exceeding it fails rather than sampling scenarios.

Use an explicit `folds: []` to compare without selecting any controls. This permits
independent static safety proofs; it does not make uncontrolled changes controlled.
Omitting the `folds` field remains invalid.

Fold input must be one YAML document with an object root. Syntax, duplicate keys,
unknown fields and rule structure are validated before Git checkout or compilation;
named scenarios use the `scenarios` form. Cypher syntax and result shape are checked
Expand Down Expand Up @@ -150,13 +154,38 @@ outcomes; a rename label is a candidate, not an equivalence proof.
JSON preserves the existing code names. Other finite statuses and protocol kinds also
use enums internally, with strings decoded and encoded at external boundaries.

Reports declare `schemaVersion: 1` and follow the packaged
Reports declare `schemaVersion: 2` and follow the packaged
[verdict JSON Schema](engine/src/main/resources/io/johnsonlee/graphfold/engine/verdict.schema.json)
(draft 2020-12), also available through `AnalysisReports.schema()`. The schema applies
to the serialized result regardless of whether its filename is `verdict.json` or
the Gradle default `report.json`. Structural schema validation complements the
engine's cross-field and proof checks; it does not establish that a verdict is correct.

Each reason includes an `assessment` with independent `control`, `safety`,
`decision`, and `basis` fields. `CONTROLLED` requires proof connecting the change
to the selected controls. `UNCONTROLLED` can still be `ACCEPTED` on a complete
static whole-change equivalence proof; acceptance never relabels it controlled.
`UNPROVEN` records missing evidence, while `REFUTED` records a disproved safety
claim. A rejected assessment prevents the overall report from passing.

Safety evidence identifies its claim, status, subject, supporting evidence, and
assumptions. `EFFECT_FREE`, `NONTHROWING`, and `TERMINATING` method proofs alone
cannot justify acceptance: changing `return price` to `return 0` can satisfy all
three and still change the result. `STATIC_SAFETY` acceptance requires a cited,
`PROVEN` `WHOLE_CHANGE_EQUIVALENT` certificate. Representation equivalence and
input identity have separate acceptance bases; neither implies control coverage.
The schema validates the certificate structure, not the truth of its proof.

The safety analysis uses packaged method bodies, flow-sensitive null facts and
resolved callee summaries. Its supported equivalence proof compares total,
effect-free return expressions in both revisions and preserves untraversed
production instructions. Every surviving difference must be covered; changed
declarations, resources, dependencies or unresolved graph obligations cannot be
discharged by proving one helper safe. Original-bytecode proofs cannot override
selected folds in a method or its callees. Unsupported operations remain unproven.
The [safety golden manifest](engine/src/test/resources/safety/manifest.json) records
control, safety claims and acceptance separately for packaged Java/Kotlin cases.

`ruleAudits` records each scenario, revision and zero-based rule index. Each entry
contains the selector, `selectionStatus`, all unique raw `selectedNodes`, nullable
`selectedCount` and independent `matchedCallCount` from Graphite's fold report.
Expand Down
12 changes: 9 additions & 3 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ fold(head, A_PR) ≡ fold(base, A_PR)
| Verdict | 条件 |
| --- | --- |
| `PASS` | 分析成功完成,本次所有相关变化均被证明消除或等价 |
| `FAIL` | 确认 uncontrolled change,或存在阻止完成证明的错误、缺口或定位失败 |
| `FAIL` | 存在缺乏充分安全证明的 uncontrolled change,或存在阻止完成证明的错误、缺口或定位失败 |

`FAIL` 区分未受 control 约束的静态生产代码差异、证据不足的变更和分析过程错误;它不声称已经发生运行时业务行为差异。

Expand Down Expand Up @@ -190,7 +190,7 @@ data class AnalysisResult(
val metadata: AnalysisMetadata,
val reasons: List<VerdictReason> = emptyList(),
val ruleAudits: List<RuleAudit> = emptyList(),
) // schemaVersion 固定为 1;verdict 由 findings、blocking diagnostics 与证明完成情况派生,不由调用者赋值。
) // schemaVersion 固定为 2;verdict 由 findings、blocking diagnostics 与证明完成情况派生,不由调用者赋值。
```

`Evidence`、`Diagnostic`、`AnalysisMetadata` 和 `VerdictReason` 已在 engine 定义。`Finding.locations` 至少一项,可跨文件和 revision,且都是本次 diff 的归属位置;调用链等未修改位置放入 evidence。纯移动的 `VerdictReason.locations` 可为空,此时以旧/新路径描述变化,不制造字符 diff。
Expand All @@ -215,7 +215,7 @@ Finding 分类:

当前 Metadata 记录解析后的 SHA、Graphite 版本、场景和 obligation/证明完成数量。编译器版本、规则摘要、构建产物身份与完整 provenance 仍是待补的审计信息,不能声称已经输出。Finding ID 使用内容摘要,不依赖图节点编号。

JSON 报告包含 `schemaVersion: 1`,规范为 [verdict.schema.json](../engine/src/main/resources/io/johnsonlee/graphfold/engine/verdict.schema.json),采用 JSON Schema draft 2020-12,标识为 `urn:io.johnsonlee.graphfold:verdict:1`。同一资源随 engine 打包,可通过 `AnalysisReports.schema()` 读取。Schema 校验序列化结构、必需字段、枚举、空值与数值边界,不代替引擎的语义证明。它适用于任意报告文件名;Gradle 默认仍输出 `report.json`。
JSON 报告包含 `schemaVersion: 2`,规范为 [verdict.schema.json](../engine/src/main/resources/io/johnsonlee/graphfold/engine/verdict.schema.json),采用 JSON Schema draft 2020-12,标识为 `urn:io.johnsonlee.graphfold:verdict:2`。同一资源随 engine 打包,可通过 `AnalysisReports.schema()` 读取。Schema 校验序列化结构、必需字段、枚举、空值与数值边界,不代替引擎的语义证明。它适用于任意报告文件名;Gradle 默认仍输出 `report.json`。

## 4. 仓库获取与共享对象 checkout

Expand Down Expand Up @@ -904,6 +904,12 @@ P0 表示上线门禁前必须解决,或必须可靠识别并阻断;不意

`reasons` 对 PASS 和 FAIL 都提供解释,包括 AST 识别的 `changes`、证明结论 `code`、文字说明、场景、diff 位置和 base/head 路径。分类包括字段初始化值变化、条件增删、调用变化、成员增删、字段/方法重命名候选、文件移动/改名与类初始化变化。JavaParser/Kotlin PSI 只负责描述变化;分类本身不决定 verdict。

报告 v2 为每个 reason 增加 `assessment`,将 `control`(CONTROLLED / UNCONTROLLED / UNPROVEN)、`safety` 证据、`decision`(ACCEPTED / REJECTED)及 `basis` 分开。受控性必须来自选定 control 的静态证明,接受不等于受控:完整的整体变更等价证明可以接受 UNCONTROLLED 变化,但不能把它改标 CONTROLLED。显式 REJECTED assessment 阻止整体 PASS;没有 reason 的早期或空 diff 报告仍由 findings、blocking diagnostics 和证明计数判定。

每项 safety 证据包含 claim、status、subject、evidence 和 assumptions。PROVEN、REFUTED、UNPROVEN 分别表示已证明、已反证、未证明;未知不等于危险。EFFECT_FREE、NONTHROWING、TERMINATING 只是方法性质,例如将 `return price` 改成 `return 0` 仍可能满足这三项,不能据此接受变更。STATIC_SAFETY 接受要求 UNCONTROLLED 分类及带实际引用证据的 PROVEN WHOLE_CHANGE_EQUIVALENT 证明。INPUT_IDENTITY、REPRESENTATION_EQUIVALENCE 和 CONTROL_COVERAGE 是独立的接受依据;缺口和存活差异分别使用 INCOMPLETE_PROOF、SURVIVING_DIFFERENCE。Schema 验证这些字段及证书结构,不验证证明真实性。

显式 `folds: []` 请求独立的静态比较,不提供控制覆盖。一般安全分析从实际 class 和声明依赖读取方法体,传播空值事实、参数、返回值、异常、效果与终止证据。整体等价证明要求所有剩余差异都获得证明,方法声明一致,且不存在未解决的图义务;未遍历的生产指令也必须保留在比较证据中。原始字节码摘要不能覆盖选定折叠对当前方法或其传递依赖的修改。新增曝光条件仍独立要求与选定 control 关联、结果没有其他用途且折叠后冗余;原实现对 control 返回值的计算不能代替用户选定的值。

`FOLDED_EQUIVALENT` 表示受支持的表示中未留下差异;`UNREACHABLE` 表示同一输入内有静态证据证明,选定 control 的折叠消除了通往该变更的路径;未调用或没有流量本身不能得到该结论;`SURVIVING_DIFFERENCE` 表示仍有未证明一致的表示差异。分析完整性缺口由 blocking diagnostic 表达,不能伪装成已定位 violation。`METHOD_RENAMED`/`FIELD_RENAMED` 是一对一结构候选,正文或值同时变化时不能只凭名称相似进行配对。

分类器以实际 diff 范围筛选节点,并允许在两侧源码中配对重命名,使仅有 BASE 或 HEAD 位置的 obligation 也能得到解释。未细分的语法保守标记为 `DECLARATION_CHANGED`/`BODY_CHANGED`;例如部分构造器与 Kotlin 主构造器属性参数尚无专用分类。这影响解释粒度,不豁免证明义务。
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -195,12 +195,14 @@ data class AnalysisResult(
val ruleAudits: List<RuleAudit> = emptyList(),
) {
/** Version of the serialized report contract described by [AnalysisReports.schema]. */
val schemaVersion: Int = 1
/** Passes only with no findings, no blocking diagnostics, and all obligations proved. */
val schemaVersion: Int = 2
/** Passes only with no findings, blocking diagnostics, rejected assessments, or unproved obligations. */
val verdict: Verdict
get() = if (findings.isEmpty() && diagnostics.none { it.blocking } &&
metadata.obligations == metadata.provedObligations
) Verdict.PASS else Verdict.FAIL
get() {
val proofsComplete = metadata.obligations == metadata.provedObligations &&
reasons.none { it.assessment.decision == AcceptanceDecision.REJECTED }
return if (findings.isEmpty() && diagnostics.none { it.blocking } && proofsComplete) Verdict.PASS else Verdict.FAIL
}
}

/** Working storage and scenario limit for static analysis; no build or repository configuration. */
Expand Down Expand Up @@ -263,6 +265,8 @@ enum class ReasonCode {
FOLDED_EQUIVALENT,
/** Validated same-input evidence ties removal of all static paths to the explicitly selected controls. */
UNREACHABLE,
/** A complete, explicitly cited static whole-change proof supports acceptance without control coverage. */
STATIC_SAFETY_PROVEN,
/** The folded representations still differ for this obligation. */
SURVIVING_DIFFERENCE,
/** An analysis gap prevents a safety conclusion. */
Expand All @@ -279,6 +283,7 @@ enum class ReasonCode {
* @property scenario Name of the folding scenario used for this proof.
* @property basePath Repository-relative old path, or null if absent or unspecified.
* @property headPath Repository-relative new path, or null if absent or unspecified.
* @property assessment Independent control classification, safety evidence, and acceptance decision.
*/
data class VerdictReason(
val changes: Set<ChangeKind>,
Expand All @@ -288,4 +293,11 @@ data class VerdictReason(
val scenario: String,
val basePath: String? = null,
val headPath: String? = null,
)
val assessment: ChangeAssessment = code.defaultAssessment(),
) {
init {
if (code == ReasonCode.STATIC_SAFETY_PROVEN && assessment.decision == AcceptanceDecision.ACCEPTED) {
require(assessment.basis == AcceptanceBasis.STATIC_SAFETY) { "static proof requires static safety evidence" }
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ package io.johnsonlee.graphfold.engine

import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper

/** Common report encoding for the CLI, Gradle plugin, and SDK consumers. */
/** Common report encoding for Gradle and Maven plugins and SDK consumers. */
object AnalysisReports {
private val mapper = jacksonObjectMapper()

Expand Down Expand Up @@ -57,6 +57,8 @@ object AnalysisReports {
foldSelectionSummary(result).forEach { appendLine(it) }
result.reasons.forEach { reason ->
appendLine("${reason.code} [${reason.changes.joinToString()}]: ${reason.message}")
appendLine(" ${reason.assessment.control}: ${reason.assessment.decision} via ${reason.assessment.basis}")
reason.assessment.safety.forEach { proof -> appendSafetyEvidence(proof) }
}
result.findings.forEach { finding ->
appendLine("${finding.kind}: ${finding.message}")
Expand All @@ -72,3 +74,9 @@ object AnalysisReports {
}
}.trimEnd()
}

private fun StringBuilder.appendSafetyEvidence(proof: SafetyEvidence) {
appendLine(" ${proof.claim} ${proof.status}: ${proof.subject}")
proof.evidence.forEach { appendLine(" evidence: $it") }
proof.assumptions.forEach { appendLine(" assumption: $it") }
}
Loading
Loading