Skip to content

Add a harness attribute that turns off unwinding assertions - #4977

Open
srivatsansamraj wants to merge 5 commits into
model-checking:mainfrom
srivatsansamraj:per-harness-unwinding-checks
Open

srivatsansamraj wants to merge 5 commits into
model-checking:mainfrom
srivatsansamraj:per-harness-unwinding-checks

Conversation

@srivatsansamraj

@srivatsansamraj srivatsansamraj commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Unwinding assertions can only be turned off for a whole run, with --no-unwinding-checks. A crate that verifies some harnesses up to a bound on purpose, and others completely, has to split them into separate runs.

This adds #[kani::no_unwinding_checks], which turns off unwinding assertions for the harness it annotates. It is built the way #[kani::should_panic] is: the compiler records it in the harness metadata, and the driver gives CBMC the same flags as the global option, for that harness only. It takes no arguments, may be used once per harness, and requires #[kani::proof]. It is rejected on a proof_for_contract harness, since stub_verified would then trust the contract beyond the bound. The attribute reference documents it, including that a successful result then holds only for executions within the unwinding bound.

tests/ui/no-unwinding-checks-attribute/per-harness runs two harnesses with the same loop and bound, and checks that only the one without the attribute fails its unwinding assertion, so the test fails both if the attribute is ignored and if it leaks to the other harness. with-args, multiple-attrs, without-proof and contract-harness check the errors for an argument, a second use, a function that is not a harness, and a contract harness.

Resolves #1710

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 and MIT licenses.

@srivatsansamraj
srivatsansamraj requested review from a team as code owners October 5, 2026 23:49
@srivatsansamraj

Copy link
Copy Markdown
Contributor Author

@CYJ904 @Tianshu-Huang @wodex1nhaoIeng @acearyanarun for review. Kani can only switch off its "did the loop run enough times" checks for a whole run. This adds #[kani::no_unwinding_checks], which switches them off for one harness, so harnesses that check code only up to a bound can sit next to complete ones in the same run. It follows the way #[kani::should_panic] is built, and the tests check that the switch reaches only the harness it is on. No number moves in the standard-library run; it is a new option for harness writers.

@github-actions github-actions Bot added Z-EndToEndBenchCI Tag a PR to run benchmark CI Z-CompilerBenchCI Tag a PR to run benchmark CI labels Oct 6, 2026

@Tianshu-Huang Tianshu-Huang left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new attribute is missing from --export-json.

I ran the per-harness test on this branch with -Z unstable-options --export-json. Both harnesses come out with the same "attributes": {"kind": "Proof", "should_panic": false} and "is_bounded": false. One is Success, the other Failure. So anyone reading the JSON cannot tell that the Success only holds within the unwind bound.

Fix: in kani-driver/src/frontend/schema_utils.rs line 229, next to should_panic, add "no_unwinding_checks": h.attributes.no_unwinding_checks, and add a row for it in the RFC 0015 schema table. #4958 does the same for its is_aliasing flag.

Everything else looks right. The attribute goes through the same code path as the global --no-unwinding-checks flag, so CBMC gets the same arguments. All 5 ui tests pass here, and the per-harness test shows the attribute does not leak to the other harness.

@srivatsansamraj
srivatsansamraj force-pushed the per-harness-unwinding-checks branch from 33fb8e8 to 768dba9 Compare October 9, 2026 16:51
@srivatsansamraj

Copy link
Copy Markdown
Contributor Author

Added in 768dba9: no_unwinding_checks is now in the exported attributes and the RFC 0015 table, and the multiple-harnesses JSON test checks it for each harness.

@feliperodri feliperodri self-assigned this Oct 22, 2026
@feliperodri feliperodri added [C] Feature / Enhancement A new feature request or enhancement to an existing feature. Z-Autoharness Issue related to autoharness subcommand labels Nov 6, 2026
@feliperodri feliperodri added this to the Autoharness milestone Nov 6, 2026
@feliperodri feliperodri removed the Z-Autoharness Issue related to autoharness subcommand label Nov 6, 2026
@feliperodri feliperodri removed this from the Autoharness milestone Nov 6, 2026
@feliperodri feliperodri added the [F] Soundness Kani failed to detect an issue label Nov 6, 2026
@feliperodri

Copy link
Copy Markdown
Member

Unwinding assertions is a big part of our soundness story. If this is disable for individual harnesses, how visible would it be for users to make them understand the harness they are running doesn't guarantee a proof across all execution paths because it won't be able to prove the loops were fully unwind?

Unwinding assertions could only be turned off for a whole run, with
`--no-unwinding-checks`, so a harness that verifies code up to a bound
on purpose could not share a run with harnesses that need the checks
(model-checking#1710). The new `#[kani::no_unwinding_checks]` attribute sets a
`no_unwinding_checks` field in the harness metadata, and the driver
then gives CBMC the flags that `--no-unwinding-checks` gives, for that
harness only. It is rejected on a `proof_for_contract` harness, since
`stub_verified` would then trust the contract beyond the bound.
`tests/ui/no-unwinding-checks-attribute/per-harness` runs two harnesses
with the same loop and bound and checks that only the one without the
attribute fails its unwinding assertion; `with-args`, `multiple-attrs`,
`without-proof` and `contract-harness` check the errors for an
argument, a second use, a function that is not a harness, and a
contract harness.
A successful result of a harness with `#[kani::no_unwinding_checks]`
holds only for the executions within the unwinding bound. Print a
warning with the harness's result, and list each such harness that
verified successfully in the final summary.
`--output-into-files` writes each harness's result to its own file,
which now carries the same warning as the terminal output.

@feliperodri feliperodri left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the work on this. The mechanism looks right: the attribute follows should_panic, it's rejected on proof_for_contract, and the per-harness test catches leaks in both directions.

Needs changes before merge (small):

  1. Visibility. Nothing in the terminal output says a result excludes unwinding checks. Please print a line for each such harness, something like "unwinding checks disabled by #[kani::no_unwinding_checks]", so a success isn't read as a full proof. This also answers the question above on who will notice.
  2. Doc example. The "verifies this harness successfully" claim and the "below 3" bound aren't tested in CI. Please add it as a UI test, or remove the bound claim.
  3. unwind plus this attribute. The PR doesn't say what happens when both are on one harness. Please reject the combination, or document what the unwind value does then.

Comment thread kani-driver/src/call_cbmc.rs Resolved
Comment thread docs/src/reference/attributes.md Resolved
The example in the attribute's documentation becomes a UI test, with
covers that show the result reaches `n` = 2 and not `n` = 3. The
documentation also says that the unwinding value sets the bound.
@srivatsansamraj
srivatsansamraj force-pushed the per-harness-unwinding-checks branch from 768dba9 to c4b377c Compare November 7, 2026 03:32
@srivatsansamraj

Copy link
Copy Markdown
Contributor Author

@feliperodri each harness with the attribute now gets a warning with its result, and the summary lists every one that verified (d126d94c9; the same warning goes into --output-into-files files, 9a02d4116). The documented example is a UI test, and the documentation says that the unwinding value sets the bound (c4b377ccb): using both on one harness is the intended case.

@feliperodri feliperodri self-assigned this Nov 7, 2026

@feliperodri feliperodri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, all three points are addressed: each harness with the attribute gets a warning with its result and a line in the summary, the doc example is a UI test whose covers show the bound, and the docs say the unwind value sets the bound. The BuildBundle-MacOs-x86_64 failure is an artifact upload timeout on GitHub's side.


It has the effect of the `--no-unwinding-checks` option on the annotated harness only.
It is meant to be used with an unwinding value (`#[kani::unwind(N)]` or `--default-unwind`), which sets the bound: an execution that needs more loop iterations is cut off instead of failing.
Kani does not report loops that weren't unwound enough times, and a successful result only holds for the executions that stay within the unwinding value.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: without #[kani::unwind] or --default-unwind, the attribute does nothing useful. Consider a warning in the driver when no unwind value is set for such a harness.

@feliperodri feliperodri removed the [F] Soundness Kani failed to detect an issue label Nov 8, 2026
@feliperodri feliperodri removed their assignment Nov 8, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[C] Feature / Enhancement A new feature request or enhancement to an existing feature. Z-CompilerBenchCI Tag a PR to run benchmark CI Z-EndToEndBenchCI Tag a PR to run benchmark CI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow disabling unwinding assertions for specific harnesses

3 participants