docs(invariants): add programmability screening methodology and canar…

[zjy-dev]

…y results

Introduce a project-level screening framework in invariants/README.md so each mechanism's invariant survey can separate "checker-worthy" rows from explicitly-excluded ones using the same four dimensions (observability, decisiveness, cost, static/dynamic category). Apply the framework to stack-canary.md, listing 10 invariants that pass and 18 that are excluded with reasons pointing back to specific dimensions.

Summary by Sourcery

Define a shared project-level methodology for screening invariants for programmability and apply it to the stack canary invariant survey, classifying which invariants are checker-worthy and which are explicitly excluded with reasons.

Documentation:

• Document a common four-dimensional framework for evaluating which invariants should become automated checkers and how they map to static vs dynamic analysis.
• Update the stack canary invariants doc to list the invariants that pass the programmability screening and those that are excluded, with categorized reasons referencing the shared framework.

[sourcery-ai]

Reviewer's Guide

Introduces a shared project-level methodology for determining which documented invariants are suitable for automated checking, and applies it to the stack-canary invariants by adding a new section that classifies each invariant as checker-worthy or explicitly excluded with reasons tied to the four screening dimensions.

Flow diagram for invariant programmability screening methodology

flowchart TD
    A[Invariant from survey] --> B[Evaluate observability]
    B --> C[Evaluate decisiveness]
    C --> D[Evaluate implementation_cost]
    D --> E[Determine static_vs_dynamic category]

    E --> F{Any dimension severely inadequate?}

    F -- Yes --> G[Classify as excluded_invariant]
    G --> H[Record 排除理由 referencing specific dimension]

    F -- No --> I[Classify as checker_worthy_invariant]
    I --> J[Record 通过理由 referencing dimensions]

    J --> K[Emit entry under stack_canary 可程序化 invariants]
    H --> K

Loading

File-Level Changes

Change	Details	Files
Define a project-wide programmability screening methodology for invariants and integrate it into the invariants documentation structure.	Replace the previous "写新 survey 的流程" section 4 with a new "可程序化筛选方法论" section describing the purpose of programmability screening and its distinction from the broader research-oriented invariant survey. Introduce four evaluation dimensions (observability, decisiveness, implementation cost, static/dynamic category) with definitions and typical failure signals, and clarify that any single dimension can be a sufficient exclusion reason. Specify criteria for classifying invariants as static vs dynamic and how this maps to oracle categories and existing documentation (story_line.md, invariant.go). Define a standard recording format for per-mechanism "可程序化 invariants" chapters, including required fields for accepted and excluded invariants and explicit links back to the shared methodology section. Clarify documentation conventions: per-mechanism docs should not repeat the methodology, should avoid implementation details and prioritization, and must phrase exclusion reasons in terms of the four dimensions.	docs/tech-docs/invariants/README.md
Apply the new programmability screening framework to the stack-canary invariants by adding a dedicated section that classifies which invariants should become checkers and which should be excluded, with rationale.	Insert a new section "可程序化 invariants" before the existing open-questions section in the stack-canary survey, referencing the shared methodology in README.md instead of re-describing it. List "通过筛选" stack-canary invariants (10 items) including guard symbol presence, main/no_stack_protector behavior, attribute-driven protection, VLA/alloca-triggered canaries, canary layout and sharing, stack_chk_fail semantics, epilogue scrub behavior, and the GCC 2023-4039 historical violation, each tagged as static or dynamic with a short acceptance rationale tied to observability, decisiveness, cost, and reuse of existing checkers/templates. List "未通过筛选" stack-canary invariants (18 items) covering heuristic flags, configuration/linker contracts, compiler-internal state, hardening-ideal properties, ISA-specific layout details, guard source/placement, runtime hooks, LTO interactions, and cross-DSO behavior, each with an explicit exclusion reason mapped to a screening dimension such as observability gaps, decisiveness issues, or implementation cost. Adjust section numbering so that the new "可程序化 invariants" section becomes section 11 and the previous "开放问题 / 未覆盖 invariants (Follow-ups)" moves to section 12. Ensure the new section reuses existing terminology (e.g., references to BinaryInspector, DynamicBufferSearchChecker, EpilogueCanaryScrubChecker, seed templates, and dynamic search channels) to make it clear how the classified invariants relate to current and potential oracle implementations.	docs/tech-docs/invariants/stack-canary.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}