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 reports control coverage, static safety evidence and an acceptance decision. AB tests are one use case, not an engine-specific concept.
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 for the proof model, gaps, and trade-offs, and validation results for the executed checks.
| Module | Artifact / entry point |
|---|---|
engine |
Git fetch/checkout/diff, static analysis, and the integration input contract |
plugin/gradle |
Gradle model integration; graphFoldInputs and graphFoldCheck |
plugin/maven |
MavenProject/MavenSession integration; snapshot and check goals |
gfc |
Optional javac/Kotlin compiler-origin provider |
Each integration has engine as its only project dependency. The plugins do
not depend on each other. Engine knows no Gradle/Maven model or build invocation.
Engine publishes the static input contract, archive decoding and snapshot storage
under engine.inputs. These classes compile once in engine; plugins supply their
native build-model data through that API. There is no shared source directory or adapters module.
GFC owns the Java-only compiler-origin protocol. Engine consumes it through its GFC
dependency; the compiler provider has no engine dependency and packages its own protocol.
Its compiler hooks use the host compiler APIs.
The three compiler-provider SPI registrations are generated by KSP from @AutoService annotations.
The engine receives folded methods directly through Graphite’s loadObserved API; it no longer registers a SnapshotExtension service.
Same-version integration does not remove target JDK/Kotlin compiler compatibility requirements.
The project targets JDK 17 and pins Graphite to 2.15.0. Engine uses JGit
7.8.0.202609011348-r for fetch, checkout and diff; no Git executable is required.
Shared objects and exclusively leased checkout pairs isolate concurrent requests.
The default is two workspace slots and a 25-minute acquisition budget. Git-ignored
files follow the repository's own ignore rules; engine has no special Gradle/Maven
cache-directory policy. Checkout hooks and smudge filters do not execute.
Gradle and Maven plugins run inside the user's normal build and export its model and packaged artifacts. Neither engine nor plugins launch a second build process.
The dependency target is the Graphite 2.15.0 release. Dependency resolution checks Maven Central first, then the upstream GitHub Packages registry for the io.johnsonlee.graphite group. The 2.15.0 Packages publication succeeded; its Sonatype release step failed. For local builds, set graphitePackagesUsername and graphitePackagesToken in user Gradle properties, or GITHUB_ACTOR and GITHUB_TOKEN in the environment. The token must have package read access; do not commit it. CI requests packages: read using its workflow token, and the upstream package must allow access from GraphFold. Current regression, coverage and hosted CI evidence are recorded in the validation record; earlier alpha1 source-build results remain historical evidence.
./gradlew checkcheck runs JUnit tests, detekt, and per-module JaCoCo verification requiring 100% line coverage and 100% branch coverage. No production classes are excluded from the coverage gates. Integration tests exercise real Git repositories, compilation, Graphite Cypher/folding, native plugin execution, and the Gradle Worker API.
All projects share the root detekt.yml, extending detekt's recommended defaults with null-safety, exception, coroutine, naming, complexity, performance and style checks. check includes ordinary scans, type-resolved detektMain and detektTest, and the engine's detektTestFixtures. The root scan covers the handwritten Gradle Kotlin scripts. Any finding fails the build; there is no baseline. HTML, XML and SARIF reports are written under each project's build/reports/detekt/.
To run static analysis without running tests:
./gradlew detekt detektMain detektTest :engine:detektTestFixturesCI compiles modules and corpus fixtures once per platform, then runs four independent GitHub Actions test shards on each of Ubuntu and macOS. Each shard uses one Gradle worker and one test process at a time. Ordinary tests are partitioned by class; the paired-source corpus is partitioned by case. Prepared compiler outputs retain their original source provenance and must be restored to the same absolute workspace path. The aggregate requires every discovered test class and every labelled corpus case, rejects duplicate or failed results, and combines all shard coverage before verification.
Coverage uses exact missed-line and missed-branch counts; rounding never turns a miss into 100%. Missing, malformed, or zero-total reports fail the coverage check. Reports are collected and uploaded even after a failed test run. The required run-unit-test job aggregates preparation, all eight test jobs, and both platform coverage gates. Pull requests run one matrix per revision; branch pushes do not start a duplicate matrix.
Each PR gets one coverage comment with a per-module table for both platforms and a link to the Build run. Later runs update the same bot-owned comment and remove duplicate owned comments. The reporter ignores stale commits and run attempts. It runs separately on workflow_run, checks out only the trusted default branch, and treats PR artifacts as bounded JSON data; fork PR code never receives the comment-writing token. This workflow starts reporting after it is merged into the default branch. A partially rerun matrix reports missing coverage for platforms without artifacts from that attempt, rather than silently reusing older results.
The manually labelled paired-source regression corpus is in fixtures. Its test records per-case results in engine/build/reports/detection/{java,kotlin}/results.json and checks precision and recall against the requested threshold. These are measurements on the checked-in corpus, not a claim of 90% accuracy on arbitrary production repositories. Operational failures are not accepted as successful detection evidence.
A rule contains a Cypher query selecting CallSite nodes, optional argument constraints, and a replacement value:
version: 1
folds:
- select: |
MATCH (cs:CallSite {callee_class: "sample.Ab", callee_name: "enabled"})
RETURN cs
args:
0: feature
value: falseThe same rules apply to both revisions. Multiple rules in one scenario apply together. Multiple explicitly enumerated scenarios can be supplied with a scenarios root; every scenario must pass:
scenarios:
- name: disabled
folds:
- select: |
MATCH (cs:CallSite {callee_class: "sample.Flags", callee_name: "enabled"})
RETURN cs
value: falseQueries 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
against the actual graph. A rule matching no foldable calls in either BASE or HEAD
blocks with UNMATCHED_RULE; a match in only one revision is allowed, since a new
controlled call may exist only in HEAD. A no-diff analysis skips graph selection.
Engine owns repository operations and the static input contract. Integrations supply bytecode, dependencies and optional source associations. Gradle reads its in-process project model; Maven reads MavenProject/MavenSession. No plugin launches a nested Gradle/Maven process.
dependencies {
implementation("io.johnsonlee.graphfold:engine:<version>")
}import io.johnsonlee.graphfold.engine.AnalysisReports
import io.johnsonlee.graphfold.engine.EngineConfiguration
import io.johnsonlee.graphfold.engine.GraphFoldEngine
import io.johnsonlee.graphfold.engine.inputs.PreparedRevision
import java.nio.file.Path
fun analyzePrepared(base: PreparedRevision, head: PreparedRevision, fold: String) {
val engine = GraphFoldEngine(
EngineConfiguration(cacheDirectory = Path.of("/path/to/cache")),
)
println(AnalysisReports.json(engine.analyze(base, head, fold)))
}PreparedRevision supplies a Git revision identity and its named static scopes.
Engine computes changed files from the Git trees; integrations do not supply diffs. Each scope supplies application class
bytes, external types, source roots, and verified compiler evidence. Repository
operations are implemented by engine RepositoryAnalyzer with an explicit
RevisionInputProvider. Plugins exchange immutable packaged inputs through
StaticInputSnapshots; engine obtains the Git diff and performs the comparison.
Results include verdict, findings, diagnostics, analysis metadata, and reasons
for both passing and failing obligations. Locations identify BASE or HEAD,
repository-relative paths, and one-based line: {start, end} / column: {start, end}
coordinates. End positions are exclusive and columns count UTF-16 code units.
Deletions can refer to BASE. Structural change categories are distinct from proof
outcomes; a rename label is a candidate, not an equivalence proof.
Diagnostic.code uses the DiagnosticCode enum throughout the engine and entrypoints;
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: 2 and follow the packaged
verdict JSON Schema
(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 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.
Node details include caller/callee signatures and descriptors, node and origin IDs,
ordinal and available debug line number. IDs belong only to that original unfolded
graph; they are not stable cross-revision identifiers or precise diff locations.
NOT_EXECUTED (including no diff) and FAILED are distinct from a successful
SELECTED result with zero nodes. A later folding failure can preserve successful
selection evidence while leaving the matched count unknown. Property-match rules
record candidate call sites; argument predicates may reduce actual matched calls.
Default [graphfold.fold] lines summarize each scenario/revision/rule with selection
status and separate selected/matched counts; unavailable counts appear as unknown.
Text reports include these summaries once. Full node lists remain in JSON reports.
Gradle emits summaries at lifecycle level and complete audit JSON only
with --info (or a more detailed log level).
The release workflow publishes plugin markers independently to Maven Central and GitHub Packages. For a version available on Central, add it to plugin resolution:
// settings.gradle.kts
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}// build.gradle.kts
plugins {
id("io.johnsonlee.graphfold") version "<version>"
}Export each revision during its own normal build, keeping the bundles in separate locations. The plugin reads that invocation's configured source sets, archive tasks, resolved dependencies and compiler output associations; it never reuses another revision's build model. Both bundles must be created by trusted builds; see Snapshot trust boundary.
# In BASE's checkout:
./gradlew graphFoldInputs -Pgraphfold.inputsDirectory=/tmp/graphfold-base
# In HEAD's checkout:
./gradlew graphFoldInputs -Pgraphfold.inputsDirectory=/tmp/graphfold-head
./gradlew graphFoldCheck \
-Pgraphfold.baseInputs=/tmp/graphfold-base/inputs.json \
-Pgraphfold.headInputs=/tmp/graphfold-head/inputs.json \
-Pgraphfold.fold=rules.ymlgraphFoldCheck consumes the exported bundles and invokes engine in an isolated
worker. It does not build either revision or launch a nested build. Reports are written to
build/reports/graphfold/report.json and report.txt. Snapshots record the producer's
Git revision alongside copied artifacts and mapping evidence; later compilation
cannot replace BASE's saved bytes.
The io.johnsonlee.graphfold:graphfold-maven-plugin:<version> artifact provides snapshot
and check goals. Invoke them after the normal verify lifecycle so the current
MavenProject has its packaged artifact and resolved dependencies. Produce both BASE
and HEAD snapshots through trusted builds; see Snapshot trust boundary.
# BASE checkout:
mvn verify io.johnsonlee.graphfold:graphfold-maven-plugin:<version>:snapshot \
-Dgraphfold.snapshotDirectory=/tmp/graphfold-base
# HEAD checkout:
mvn verify io.johnsonlee.graphfold:graphfold-maven-plugin:<version>:check \
-Dgraphfold.snapshotDirectory=/tmp/graphfold-head \
-Dgraphfold.baseSnapshot=/tmp/graphfold-base \
-Dgraphfold.rules=rules.ymlEach archive-producing module exports its own scope; POM aggregators do not invent
bytecode. A single-module session writes snapshot.json in the configured directory.
A reactor with multiple archive-producing modules writes
modules/<URL-encoded groupId:artifactId>/snapshot.json beneath that directory;
for example, modules/fixture%3Aservice/snapshot.json. The key excludes the version.
Pass the common BASE directory to check; it selects the matching module's snapshot.
An explicit BASE manifest file remains supported and must belong to the current module.
Reports are also isolated in a multi-module reactor: a configured
/tmp/reports/report.json becomes
/tmp/reports/modules/<URL-encoded groupId:artifactId>/report.json.
The filename is preserved, and single-module report paths remain unchanged.
This also applies to the default report under each module's target/graphfold.
The plugin reads MavenProject/MavenSession directly and never invokes an external Maven command. Source roots, output associations and compiler classpaths improve attribution; unavailable mapping evidence does not prevent static folding.
Generate both BASE and HEAD snapshots from their committed source revisions in trusted, controlled builds. Do not accept a snapshot manifest or its assets supplied with a PR as evidence. The build/export jobs and storage used to retain their outputs must prevent the PR from substituting either bundle before analysis. Trust must cover the build/export configuration, not just the CI runner: executing a PR-controlled exporter in CI does not authenticate its output.
Snapshot hashes detect missing, damaged or changed assets relative to the manifest; they do not authenticate the producer or bind arbitrary bytes to a Git commit. Someone who replaces an asset can also rewrite the manifest's hashes. Recording a SHA and checking that a source checkout matches it do not prove that those bytes were compiled from that source. The producer's trusted build process supplies that assurance; GraphFold's static proof relies on it.
Export rejects tracked changes and non-ignored untracked files, including new source
files. Commit source changes before export, and ignore normal generated build outputs
(such as build/ or target/) rather than ignoring production source files.
The Gradle plugin selects enabled bootJar and war tasks from the configured project model. For projects without either archive task, it selects the application plugin’s enabled jar task. If the build has no application archives, it uses the enabled JAR tasks published through runtimeElements. The normal Gradle task graph builds these archives before export; the plugin reads their final packages and declared API dependencies.
Each selected archive and its own dependencies form a separate static scope. Maven uses the current project's packaged artifact and resolved dependency model. Library JARs do not need Main-Class or a runnable entry point; archive contents establish the static inputs.
| Input | Current behavior |
|---|---|
| Gradle application or published library JAR | Analyze the packaged application and its ordered archive classpath |
| Maven selected JAR | Analyze the packaged JAR and the model-resolved dependency artifacts |
| Spring Boot archive layout | Read actual BOOT-INF/classes and nested BOOT-INF/lib archives in stable archive-name order |
| WAR | Read WEB-INF/classes and WEB-INF/lib, with build-declared external API types |
| Repository with no selected artifact scope | Report unavailable input; do not invent application graphs from every module |
| Nested JAR/ZIP outside the recognized archive layout | Preserve its bytes as resources; do not recursively search it for classes |
WAR analysis reads the selected archive's WEB-INF/classes and WEB-INF/lib.
Build-declared provided/compile-only dependencies supplement external type information
for that application. No Tomcat installation or startup configuration is required.
Packaged Boot, WAR and Flagr fixtures build and inspect actual artifacts, then assert static control-coverage verdicts. They do not launch applications or HTTP services. Historical runtime observations are retained as historical evidence only; they do not label the static cases. See the fixture inventory. An uncontrolled callback or unconsumed Stream body remains a production change, regardless of whether a request would invoke it.
An exposure predicate before an AB decision can be controlled when disabling that
decision leaves only safely disposable evaluation. The proof links the original
predicate to the exact selected call, verifies that the rule actually folded that
call, and removes only the resulting redundant branch and unused total computations.
Supported contracts include primitive conditions, bounded private static primitive
helpers, and String.equals on a proven literal receiver. Possible exceptions,
state writes, changed fallbacks and unrelated redundant conditions remain differences;
a method being described as “read-only” is not a purity proof.
Maven adapters read selected final archives and local manifest classpath entries. A manifest may supply static entry metadata, but a missing entry point does not invalidate a selected archive. Missing archive files or unavailable external types remain input problems. Arbitrary nested resources are not recursively interpreted as application classes.
Application startup, JVM options, launch scripts, and observed traffic are outside the engine's acceptance criterion. Archive layout and build-declared dependencies provide static inputs; observed runtime inactivity cannot waive an uncontrolled production change.
Research artifacts and reproducible probes are indexed by topic in docs/research.
- Java uses JavaParser; Kotlin uses headless Kotlin PSI and actual emitted JVM identities from ASM. Both produce UTF-16 source locations. UAST is not adopted; the UAST evaluation is retained as historical research, not a migration plan. Ambiguous Kotlin method/field mappings fall back to owner-level obligations. Missing source ownership limits attribution and leaves attribution-dependent obligations unproved; complete raw-bytecode proof can still establish control coverage.
- Anonymous objects use compiler-recorded source ranges and actual emitted owners, followed by unique source-context pairing. Generated numbering is never the pairing key. The same-binary Kotlin probe verifies 1.9.20/K1, 2.0.21/K2, 2.1.20/K2, 2.2.10/K2, and 2.1.20 with language 1.9/K1. This verifies provenance, not general equivalence between compiler lowerings; metadata normalization is limited to schemas through 2.1. Ambiguous copies, unsupported versions, and observable runtime-name changes block analysis. Method-local object flow can discharge unrelated rendering of proven-safe allocations, aliases and scalar values; unknown heap/call flows remain blocking, and stack capture and serialization retain independent guards.
- Java synthetic enum-switch holders and Kotlin callable references are classified separately from source anonymous objects. Library-inline implementation classes require verified compiler output, synthetic metadata and a verified enclosing declaration; their raw JVM identities remain significant. If provenance fails, graph analysis continues with raw identities and explicitly unverified diff observations, while the verdict remains FAIL and dependent obligations remain unproved. See origin boundaries.
- JDK declarations are resolved from the running JDK image, including
jdk.compiler, without searching GraphFold’s application classpath. This resolves declarations only; it does not establish safe effects for arbitrary JDK calls. Frontend proof decisions consume structured completeness from the final folded graph and reconcile the method receipts delivered by the sameloadObservedinvocation. Missing bodies, failed observations and incomplete dispatch cannot become evidence of no effects. Application string literals are not method-completeness records. Selection uses Graphite’s parsed Cypher AST: certified direct CallSite-property predicates can tolerate unrelated native/dispatch gaps, while other query shapes conservatively require complete graph evidence. Incomplete body extraction still blocks; selecting only known targets of incomplete dispatch cannot broaden the fold. - Native Gradle and Maven plugins consume packaged outputs from their current build models. There is no standalone CLI or plain-source build adapter. Direct javac/kotlinc fixture compilers are test-only. Custom compiler plugins, generators, Kotlin Multiplatform, and dependency arrangements require separate validation.
- Build-system analysis reads application classes from final packaged applications. Gradle application JARs use their build-declared ordered dependency archives; explicitly selected JARs also include local manifest
Class-Pathentries. Compiler outputs supply source provenance only and never add classes missing from the package. Bytecode replaced during packaging stays replaced in the graph; it cannot inherit compiler provenance without verified byte identity. Multi-release JARs select one view using the actual build JDK recorded by the integration, independently for BASE and HEAD; the analyzer host JVM does not choose a version. An integration’s ordered classpath or a complete packaged Spring BootBOOT-INF/classpath.idxdetermines which definition enters the graph. Without order evidence, different definitions remain unresolved static input; an index is unnecessary for unambiguous archives. All packaged class bytes, annotations and resources remain in the change inventory, including definitions outside the effective graph. Resources and service registrations come from packaged archives. - Each selected archive defines a separate static analysis scope. Library-only Gradle builds use production JARs declared by
runtimeElements; Maven uses each current module’s packaged artifact. Unrelated module outputs are never merged into an application. Reports qualify scenario names asname [scope identity]when multiple scopes are analyzed. Added and removed scopes are compared against empty inputs using their actual bytecode; scope membership is not itself a verdict. Plugins select final artifacts from their native models; engine input decoding normalizes archives and rejects unreadable inputs before graph analysis. Missing source mappings reduce attribution precision without preventing graph construction or folding. - Unknown external observation behavior does not block literal application-code comparison when declarations and method identities are retained without opaque normalization or method omission. Surviving method differences still fail control coverage. Missing application bodies, metadata changes, resource proofs and transformations requiring knowledge of an external observer retain their relevant diagnostics.
- Effective dependency projections are reused within one analysis only when dependency content, input projection policy, relevant class definitions and application class copies agree. Inputs are hashed again on lookup, including directory resources. This avoids repeated validation and rewriting of shared libraries without synthesizing deployment scopes from library modules.
- Normal Gradle and Maven builds own compilation, generators and incremental reuse. Each plugin exports the current model and completed archive outputs; analysis consumes immutable BASE/HEAD snapshots and does not rebuild either checkout. Source roots, compiler outputs and classpaths improve source attribution. The plugins do not automatically enable GFC or export its origin manifests; the input API accepts optional compiler evidence when explicitly supplied. General compiler-plugin, generator and cross-checkout cache compatibility still require their own evidence; GraphFold does not inject a Gradle init script.
- The diff determines which changes need proof, including newly added or unused methods/classes, uninvoked callbacks and unconsumed Streams. Absence of callers, traffic or observed execution is not control coverage. Removing an obligation requires static evidence from folding the explicitly selected controls in the same input. Calls, callbacks, constructed objects, fields and initialization establish static proof dependencies.
- Narrow private-member alignment can prove consistent field/method renames when declaration, reference, and body checks agree. A pure file move requires unchanged static input identity or a complete comparison proof; moving a class between artifact scopes changes the input and is not automatically exempt. Uncontrolled additions and changes remain failures even when the affected code is unused.
- Kotlin metadata is decoded and re-encoded with only private/private-to-this functions and properties removed from the contract projection. Public/internal/protected metadata remains significant, including parameter names, defaults, nullability, and inline flags. Unsupported metadata versions or malformed metadata block analysis; reflection is not covered by this private-name abstraction.
- Full graphs and folded Jimple are the comparison basis; AST categories only explain the source change. The invocation-local observer receives application and dependency snapshots from the same folded build, without promoting dependencies to application roots or constructing an auxiliary capture graph. A plain graph is still built when Cypher selection is required. The observer remains coupled to the SootUp backend; this integration does not provide a backend-neutral IR or validated observer-enabled performance. Unsupported folding, unmatched rules and missing required dependencies block the gate. Unresolved source ownership blocks obligations that need that attribution; it does not prevent graph construction, folding or a verdict supported by complete raw-bytecode proof. Arbitrary refactoring equivalence and context-sensitive shared-wrapper specialization are not general guarantees.
- Changes outside build-declared deployed production source roots, including test and build-tool Java/Kotlin files, use actual production inventories rather than path exclusions. Production source changes retain declaration proofs and also require whole-program output proof when packaged outputs change, including generated classes and resources. Unchanged application classes, processed resources, ordered runtime classpaths and package contents prove
BUILD_OUTPUT_UNCHANGED; changed classes require whole-program folded comparison. Existing ASCII properties resources support constant ResourceBundle/key readers: changed keys with no surviving folded reader can pass. Standard scalar output, scalar string building/concatenation and boxing/parsing have explicit resource-independent models. Resource proofs follow folded dependency bodies, callbacks and initialization from application entries, including inherited APIs and exposed static fields; ordinary dependencies such as Kotlin stdlib no longer block solely by their presence. Missing bodies, unresolved dispatch, dynamic loaders, escaping bundles, unmodeled configuration injection and implicit resource providers remain blocking gaps. An exact resource-call model can discharge that call’s resource uncertainty only:resourceEffectModeleddoes not remove the structural gap or excuse unavailable bodies and recovery. Resource proofs useDependencyBodyScope.Declared(artifacts = listOf("*"))to read supplied dependency artifacts eagerly while keeping application identity separate. Graphite also providesReachable, but GraphFold does not yet use it in production: inherited APIs and exposed static fields can activate resource reads without ordinary application call sites. Demand-driven expansion requires those implicit roots to be covered first. Cross-call resource-value specialization is not implemented. Other changed non-class outputs also remain blocking gaps. Mixed resource/source PRs retain source findings despite these gaps. Unavailable inventory also blocks without invented source violations. Gradle and Maven inventory selected final archives and their declared dependency archives. Source-only compilation cannot establish resource/package scope. Unselected artifact tasks and runtime filesystem inputs remain outside this evidence. See production scope. - Java/Kotlin reflection, native/JNI callbacks, serialization hooks, framework entry conventions, and effects of changed resources/configuration require explicit models. Detected unsupported dynamic access blocks analysis; the implemented checks are not a complete inventory of every possible runtime entry mechanism.
- Opaque-call gaps are scoped to surviving calls, change dependencies and bounded observed owners. Scalar values, scalar-typed arrays, proven factory-created value collections and scalar-only SLF4J logging have explicit models. Static/private/final application helper calls specialize scalar-payload return proofs to their actual arguments and retain local aliases and typed array element reads; unknown fields, overridable targets, recursion and helper-depth exhaustion remain conservative. These are payload-scope proofs, not claims that calls or array mutations have no effects. Supplied third-party calls also require an independent bytecode observation proof over exact callees and their initializers. Simple getters and closed helpers can pass that proof; native methods, hidden reflection, unknown virtual targets, dynamic bootstraps, missing or ambiguous classes and application callbacks retain a global observation diagnostic, even when the original call has no arguments. This proof does not authorize resource effects. A collection type alone proves nothing about its contents. Pure Class type queries are modeled; runtime-name observations remain guarded when anonymous owners are normalized. Unknown object graphs and arbitrary reflection retain global scope for field/class proofs, unreachable private callbacks, whole-program resource proofs and actual normalization differences (private renames, anonymous owner/nesting changes or erased initializer state). Ordinary reachable method proofs are not blocked by an unrelated opaque caller when these erasures are absent; relevant callers/dependencies and bounded observed owners still block. Dead or folded-away observations do not block. These diagnostics describe analysis gaps, not confirmed violations.
- A source proof can separately discharge an individual
dispatchOnlygap when every application method outside its actual comparison closure is unchanged in the unnormalized folded representation, global declaration/field/entry/initialization/override metadata agrees, compiler provenance is verified, and alignment or normalization has erased no differences. Methods inside that closure still require comparison. This does not infer the unknown targets or excuse body, recovery or opaque-observation gaps. Resource-effect proofs and fold selection never use this exemption;resourceEffectModeledalone cannot authorize a source proof. A changed but apparently unreachable method outside the closure can therefore still block a PR containing an unknown call. - Direct application dispatch also has a separate closed-input leaf-owner proof: all supplied class headers and required JDK ancestors must be complete and unambiguous, the concrete owner must have no subtype, and the target must be declared there and survive as a direct body call. Dynamically generated/loaded subclasses remain unmodeled. This proof never authorizes Cypher selection or erases body/recovery/resource effects. An obligation's own independently reached surviving method or initialization difference may establish FAIL despite dispatch uncertainty; it cannot produce PASS or discharge another obligation's unknown-only change. Independent witness reachability does not traverse any outgoing edge of a method with a remaining dispatch gap, including derived targets.
- Kotlin inline functions and properties (including individual accessors) compare copied code across all reachable methods. Findings remain anchored to the changed definition. Precise copy-level attribution is not implemented, so another surviving change in the same PR may conservatively block an inline obligation.
- Stream/lambda/callback and condition-control cases have paired controlled and uncontrolled fixtures. Java-equivalent Kotlin cases and Kotlin-specific features are included. The unfiltered validation passed all checked-in corpus cases; this does not establish accuracy across arbitrary production repositories. Refer to the validation record for executed evidence.
These limitations are not blanket exemptions. A surviving structural difference is reported as UNVERIFIABLE_CHANGE; an analysis gap is a blocking diagnostic. Neither is silently treated as a confirmed business counterexample or a successful proof.
Tags matching v<strict-semver> trigger Publish. Every release first runs the quality gates, stages all Maven publications locally, verifies implementation JARs and the plugin marker, and generates SHA-256 checksums. After preparation, Maven Central, GitHub Packages and GitHub Release run independently in parallel. A failed Central upload does not block the other channels; its job stays failed and the workflow summary records every channel's result.
Both Maven channels download the verified repository, reproduce their publications, and compare every JAR, POM and module-metadata payload. A second gate checks actual upload inputs immediately before each publication; mismatches stop that channel. Central signs its payloads; GitHub Packages publishes the same verified payloads without requiring Sonatype or GPG credentials. Archive timestamps/order are deterministic. Verified release artifacts are attached to a GitHub Release. Prerelease tags produce prereleases.
workflow_dispatch accepts a tag-shaped version and performs a dry run without remote publication. Artifacts remain downloadable from the workflow run. Local rehearsal:
./gradlew check publishAllPublicationsToReleaseVerificationRepository \
-Pversion=0.1.0-local.1
python3 .github/scripts/release.py verify build/repository 0.1.0-local.1Central publication requires the repository's Sonatype and signing secrets (OSSRH_USERNAME, OSSRH_PASSWORD, OSSRH_PACKAGE_GROUP, GPG_KEY_ARMOR, GPG_KEY_ID, and GPG_PASSPHRASE). GitHub Packages uses the workflow's GITHUB_TOKEN with job-scoped packages: write; its endpoint is https://maven.pkg.github.com/johnsonlee/graphfold. Manual workflow dispatch remains a dry run: it exercises the GitHub Packages publication tasks against a local file repository and performs no remote upload. Release preparation and publication are separate so missing credentials cannot be mistaken for a verified remote release.
GitHub's Maven registry requires authentication even for public packages. Consumers can use a classic PAT with read:packages, or a workflow token with access to the package. Configure the repository in dependency resolution and, when using the Gradle plugin, in pluginManagement.repositories as well:
maven {
url = uri("https://maven.pkg.github.com/johnsonlee/graphfold")
credentials {
username = providers.gradleProperty("githubPackagesUsername").orNull
password = providers.gradleProperty("githubPackagesPassword").orNull
}
content { includeGroup("io.johnsonlee.graphfold") }
}Graphite is a separate package repository. Until its release is available from
Central, SDK and Gradle plugin consumers also need this repository in dependency
resolution (and pluginManagement.repositories for plugin dependencies):
maven {
url = uri("https://maven.pkg.github.com/johnsonlee/graphite")
credentials {
username = providers.gradleProperty("graphitePackagesUsername").orNull
password = providers.gradleProperty("graphitePackagesToken").orNull
}
content { includeGroup("io.johnsonlee.graphite") }
}Keep credentials in user Gradle properties or environment-backed providers, outside the repository. Repository configuration is not inherited from GraphFold's published POM. GraphFold's package channel does not publish or supply Graphite dependencies. See GitHub's Gradle registry documentation.