Skip to content

[anneal] Refine design contract semantics - #3719

Open
joshlf wants to merge 5 commits into
mainfrom
anneal-refine-design-contract
Open

joshlf wants to merge 5 commits into
mainfrom
anneal-refine-design-contract

Conversation

@joshlf

@joshlf joshlf commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

Refine Anneal's shared design contract around a smaller semantic core and clearer dependency order.

This change:

  • defines claim semantics first: scope plus guarantees, each with its own requirements;
  • defines successful-result semantics next: the exact claim, complete TCB, and exact assurance policy;
  • requires those result components to have stable meaning through immutable identity or references;
  • requires successful results to expose their complete effective TCB;
  • prevents failed proof obligations from silently becoming trusted while still counting as successful verification;
  • requires development-only UB bypass outputs and their TCB logs to be explicitly tainted or irreparably untrustworthy;
  • makes the end-to-end source-to-compiled guarantee explicit;
  • presents closed programs and libraries as two scope-specific cases of the same baseline well-definedness guarantee;
  • aligns library admissibility with Rust's safe/unsafe API conventions while distinguishing well-defined Rust behavior from stronger API/library invariants such as UTF-8 for str;
  • removes unnecessary local terminology such as "guarantee clause"; and
  • preserves Anneal's open-ended property model and Rust-oriented ordinary interface.

One question remains explicitly unresolved: whether and how an unsafe API may relax API or library invariants that are stronger than Rust's language-level requirements for well-defined execution.

Authored by an AI agent acting on Josh Liebow-Feeser's behalf.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-24T23:14:20.544866Z c64bcf8 Manual request
🔒 Security Review ✅ Completed 2026-09-24T23:17:24.532728Z c64bcf8 Manual request

Security findings

Advisory findings (1)

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@joshlf
joshlf enabled auto-merge September 24, 2026 21:37
@codecov-commenter

codecov-commenter commented Sep 24, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.64%. Comparing base (0eca558) to head (11def47).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #3719   +/-   ##
=======================================
  Coverage   92.64%   92.64%           
=======================================
  Files          20       20           
  Lines        6429     6429           
=======================================
  Hits         5956     5956           
  Misses        473      473           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76b033373e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread anneal/DESIGN.md Outdated
Comment on lines +41 to +44
Why a fact is trusted does not change this core semantics. Anneal may record that
provenance for diagnostics, auditing, or policy, but an unfinished proof, an
external semantic assumption, and another unchecked premise are all trusted
premises at this level.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Keep unfinished proofs out of successful TCB assumptions

When an analysis leaves a UB obligation unfinished, these lines permit treating the missing proof exactly like an external TCB assumption; together with lines 36–39, a downstream design could therefore report ordinary verification success merely by logging the unproved obligation. That conflicts with PRINCIPLES.md's requirement that unsupported code fail closed and that development-only UB bypasses produce explicitly tainted results. Require unfinished proofs, skipped checks, and tool failures to emit an error or a clearly non-successful/tainted result rather than accepting them as ordinary trusted premises.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

Comment thread anneal/DESIGN.md Outdated
Comment on lines +149 to +153
By default, values passed to an unsafe API are also assumed to satisfy their
ordinary type invariants. Some unsafe APIs may need to accept values that violate
invariants normally associated with their types. Whether Anneal permits an unsafe
API contract to relax such an invariant, and how that permission is expressed,
remains unresolved.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Separate Rust validity from relaxable API invariants

When “ordinary type invariants” includes language validity invariants—as the preceding &str/UTF-8 example indicates—permitting an unsafe API to relax them cannot be a policy choice: producing or passing a value invalid for its Rust type is already undefined behavior, and an unsafe declaration does not suspend that rule. Choosing the permissive branch left open here could therefore certify a call that violates the baseline guarantee before the implementation begins. Require Rust validity invariants for every API, and reserve any opt-out mechanism for library or abstraction invariants that Rust permits an unsafe contract to suspend.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

Comment thread anneal/DESIGN.md Outdated

At a high level, an Anneal claim has:

- a **subject** whose behavior is being verified;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Bind every successful result to the verified artifact

For cached or CI results, and for crates built under multiple feature, target, or profile configurations, merely saying that a claim has a “subject” does not require the result to identify the exact source/generated artifacts and configuration domain it covers. A proof for one revision or build could therefore be reused as an apparently successful result for different code while still satisfying this schema. Require every successful result to bind an immutable artifact identity and the exact covered configuration and execution domain.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

@joshlf
joshlf disabled auto-merge September 24, 2026 21:53
@joshlf

joshlf commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: a4c6dd1629

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4c6dd1629

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread anneal/DESIGN.md Outdated
- **API or library invariants** may be stronger than Rust language validity.
Rust's conventions may permit an API implementation to rely on such an
invariant even though violating the invariant is not itself immediate undefined
behavior. Valid UTF-8 for `str` is an example.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Treat valid UTF-8 as a language validity requirement

The revised split still places valid UTF-8 for str on the relaxable API/library side, but Rust defines a non-UTF-8 str as an invalid value; producing or passing an invalid &str is already undefined behavior, not merely an invariant violation that an unsafe API can opt out of. If the unresolved relaxation in lines 199–203 is applied to this stated example, Anneal could certify a call whose argument is invalid before the implementation begins, contradicting its baseline well-definedness guarantee. Move this example to the language-validity category and use a genuinely library-only invariant here.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

Comment thread anneal/DESIGN.md Outdated
Comment on lines +48 to +49
Every fact Anneal itself needs to justify a reported claim must either be
established by checked evidence or represented explicitly in the TCB.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Require successful results to expose their complete TCB

These lines require unchecked facts to be represented in the TCB, but the revision removes the prior requirements that the trusted code and assumptions be identified in the result and remain visible. A lower-level result format could therefore expose only an assurance-policy name while keeping the actual admissions internal and still satisfy this contract, even though PRINCIPLES.md promises users a TCB audit log whose code and assumptions they can inspect to interpret the conditional guarantee. Require each successful result to expose or immutably reference its complete, concretely identified TCB.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

@joshlf

joshlf commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c40555425d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread anneal/DESIGN.md Outdated
Comment on lines +88 to +89
TCB. Development workflows may deliberately accept weaker assurance, but their
results must remain distinguishable from ordinary successful verification.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Mark development-only UB bypass results as tainted

When a development workflow bypasses a required UB obligation, requiring its result to be merely “distinguishable” still permits it to be presented as a weaker successful result without labeling either the result or TCB as tainted or irreparably untrustworthy. That weakens PRINCIPLES.md's explicit rule for UB-bypass modes and could let downstream tooling or users treat an unverified program as a valid success category. Fresh evidence is the newly added development-workflow exception here, which specifies only distinguishability rather than the required taint semantics.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

Comment thread anneal/DESIGN.md Outdated
Comment on lines +77 to +78
The result must identify the assurance policy under which it reports success, so
that its actual TCB can be interpreted against that policy.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Bind results to an immutable assurance policy

When a cached or archived result identifies a policy through a mutable name such as default, these lines allow later policy edits to change whether the recorded TCB qualifies as successful; unlike the TCB references above, the policy is not required to have an immutable identity or version. The same stored result can therefore be reinterpreted under a weaker policy than the one actually evaluated, undermining its auditability. Require the result to embed or immutably reference the exact assurance policy used.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: c40555425d

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

@joshlf

joshlf commented Sep 24, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c64bcf8e1d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread anneal/DESIGN.md Outdated
Comment on lines +162 to +163
For a closed program, Anneal's well-definedness guarantee applies to complete
executions covered by the claim.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Require non-vacuous baseline coverage

For a closed program, this permits the claim's scope to include only executions that are already well-defined—or to give the baseline clause an equivalent requirement—so an unsafe program could receive an ordinary successful result because every excluded execution is simply “not covered.” Precision alone does not prevent this circular scope, undermining the principles that UB-freedom is always on and unsupported code fails closed; require the baseline to cover all executions enabled by the artifact and independently justified environment domain, without assuming the well-definedness it is meant to establish.

AGENTS.md reference: anneal/AGENTS.md:L11-L13

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🛡️ Codex Security Review · Automatically triggered

Here are some automated security review suggestions for this pull request.

Reviewed commit: c64bcf8e1d

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

Comment thread anneal/DESIGN.md Outdated
Comment on lines +208 to +209
assume that a `str` contains valid UTF-8 even though constructing a non-UTF-8
`str` is not itself immediate undefined behavior.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🛡️ Codex Security Review · Automatically triggered

P2 Badge Security: Treat UTF-8 validity as a Rust validity condition

If this contract guides unsafe-API verification, classifying UTF-8 for str as a relaxable API/library invariant can let a contract admit a non-UTF-8 str and still claim baseline well-definedness. Rustc rejects from_utf8_unchecked(&[0xff]) as undefined behavior: a str with invalid UTF-8 is an invalid Rust value, so unsafe cannot make it admissible. Lines 228–235 only block this when correctly classified and then leave library-invariant relaxation open. Fresh evidence versus the earlier review is the newly added assertion that constructing such a str is not immediate UB. Move UTF-8 validity to the language-level category and use a truly library-only invariant here.

Useful? React with 👍 / 👎.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants