Skip to content

ci: keep Loom models from drifting (shim lint + model-sync mapping) - #276

Merged
unbalancedparentheses merged 2 commits into
mainfrom
ci/loom-model-sync
Nov 16, 2026
Merged

unbalancedparentheses merged 2 commits into
mainfrom
ci/loom-model-sync

Conversation

@unbalancedparentheses

Copy link
Copy Markdown
Contributor

Keeps the Loom models from drifting away from the code they check.

1. Shim lint (concurrency/clippy.toml)

Bans direct std::sync::{Mutex, MutexGuard, RwLock, Condvar, Barrier}, every std::sync::atomic::Atomic*, parking_lot::{Mutex, MutexGuard, RwLock, Condvar, ReentrantMutex} and std::sync::atomic::fence / std::thread::{spawn, yield_now}.

Scope. The production sync shims re-export the std/parking_lot types (zero cost), so clippy resolves super::sync::Mutex to the same DefId as std::sync::Mutex: in an ordinary build the lint cannot tell a shim use from a direct one (tried: 224 hits crate-wide, including every shim import in the cores). So:

  • concurrency/Cargo.toml allows disallowed_types/disallowed_methods for the package (no change to any non-Loom code);
  • each Loom harness puts #[deny(...)] on its #[path]-included core mod;
  • the mailbox-loom job runs cargo clippy on the six harnesses under --cfg spawned_scheduler_loom (with -A clippy::all so only the ban is enforced there), where every shim type is Loom's and anything left is a direct use.

Negative control (local): appending a std::sync::atomic::AtomicBool static to stop_token/core.rs fails with use of a disallowed type. No violations existed in the cores; no source file in src/ changes, so zero runtime cost.

2. model-sync

New [loom.*] entries in verification/model-map.toml (RegistryTurn, ReplySlot, JobCore, LinkFence, StopToken, MailboxAdmission, ReadyGate). paths now treats TLA+ models and Loom harnesses as two sides: a core covered by both needs one of each updated (comment-only harness changes don't count), or the existing no-model-change label + reason. models fails if a */tests/*_loom.rs that #[path]-includes production code is unmapped, or if an entry's code differs from what its harness includes. 10 new self-tests (negative controls included); 45 pass.

Coverage floors and allowlists unchanged.

Model: no change because this PR only changes CI/lint configuration and Loom harness attributes.

concurrency/clippy.toml lists the atomics, locks and condvars Loom must see.
Production shims re-export the same types, so the lint is allowed for the
package and denied by each Loom harness on its #[path]-included core; the
mailbox-loom job runs clippy under --cfg spawned_scheduler_loom, where every
shim type is Loom's and a remaining std type is a direct use.
[loom.*] entries in verification/model-map.toml: a PR changing a core must
change one of its Loom harnesses (in addition to any covering TLA+ model) or
carry the no-model-change waiver. The models check requires every harness that
includes production code to be mapped, with code equal to its includes.
@unbalancedparentheses
unbalancedparentheses marked this pull request as ready for review November 16, 2026 12:35
@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: PR #276, Loom model-drift guards

The approach is sound. Running clippy under --cfg spawned_scheduler_loom means every shim type is Loom's, so any std or parking_lot sync type left in a core is a direct use. The model-map extension is a reasonable way to tie each core to its harness. Most findings are coverage gaps that could let drift through again.

Correctness and coverage gaps

1. ReadyGate is mapped but not linted.

  • model-map.toml adds [loom.ReadyGate] (benches/support/ready_gate.rs).
  • ready_gate_loom.rs gets no #[deny(clippy::disallowed_types, clippy::disallowed_methods)].
  • The workflow step (verification.yml:200) does not pass --test ready_gate_loom.
  • The clippy.toml header also omits it from the list of cores.

Either lint it like the others, or document why the bench prototype is exempt.

2. The harness list in the workflow is hardcoded.

  • verification.yml:200 repeats six --test names.
  • check_loom checks that every *_loom.rs has a map entry. It does not check that the harness carries the #[deny] attribute or appears in the clippy step.

So a new harness can satisfy model-sync and still escape the ban. Two options:

  • Have check_loom also assert that each #[path] include is preceded by the deny(clippy::disallowed_*) attribute.
  • Derive the --test list in the workflow from concurrency/tests/*_loom.rs.

3. concurrency/clippy.toml misses several things Loom models.

  • std::cell::UnsafeCell. Loom's UnsafeCell is how it detects data races. A core using std's version silently loses race checking, which is arguably the most important omission here.
  • std::sync::Arc. Loom tracks it for leak and drop ordering.
  • Guard and once types:
    • std::sync::{RwLockReadGuard, RwLockWriteGuard, Once, OnceLock, LazyLock, mpsc::*}
    • parking_lot::{RwLockReadGuard, RwLockWriteGuard, FairMutex, Once}
  • Other crates' primitives. tokio::sync::*, crossbeam*, and std::sync::atomic::AtomicBool reached through a third-party re-export are not covered.
  • Methods:
    • std::sync::atomic::compiler_fence
    • std::thread::{sleep, park, scope}
    • std::thread::Thread::unpark
    • std::hint::spin_loop
    • parking_lot::const_mutex

Also, the reason string "use the sync shim" reads oddly for std::thread::spawn. Something like "Loom-checked core must not spawn threads" would be clearer.

4. Possible override of a root config (concurrency/clippy.toml). Clippy uses the nearest clippy.toml and does not merge it with ancestors. If the workspace root has one (MSRV, thresholds, etc.), spawned-concurrency now silently drops those settings. Please verify, and copy shared settings into this file if needed.

scripts/check-model-sync.py

5. rust_content (~L363) only drops whole lines starting with //.

  • A trailing-comment edit (fn check() {} // note) counts as a model update.
  • A /* … */ block comment edit also counts as a model update.

The script already has rust_mask. Using it here would make "comments only" consistent with how #[path] detection treats comments.

6. loom_includes (~L695): include and path edge cases.

  • Non-production includes. Every #[path] counts as "production code". A harness that includes a shared test helper (e.g. #[path = "common/mod.rs"]) would be reported as unmapped, or would force the helper into code. Consider filtering to src/ and benches/, or adjust the error wording.
  • Escaping paths. target.relative_to(root) raises an uncaught ValueError if a path escapes the root, e.g. an absolute path or extra ... Catch it and report it as an error.
  • Missed forms (minor). #[cfg_attr(..., path = "...")] and #[path] on a mod nested inside an inline module (which uses a different base directory) aren't handled. Fine to leave, but worth a comment.

7. Docstring line length (L11). The line after the edit is well over the surrounding width. Rewrap it.

8. Shared waiver (design note). A single no-model-change label and reason now waives both the TLA+ side and the Loom side. That is reasonable, but say so explicitly in the docstring or model-map.toml. A reviewer could otherwise assume the waiver only covers TLA+.

Workflow details

9. -A clippy::all (verification.yml:200). Allowing all clippy lints works because source-level #[deny] overrides command-line -A. That precedence is subtle; a one-line comment would help.

The step reuses RUSTFLAGS from the test step, so the cache isn't thrashed. Good.

Minor

  • CHANGELOG. This is CI and tooling only, with no user-visible change. Consider whether it belongs in the changelog.
  • Tests. The new ModelPaths tests are good. They cover the asymmetric cases: TLA+-only and Loom-only updates each fail when both are required, and comment-only harness edits don't count. A test for a trailing or block comment in the harness would catch the issue in item 5.

Overall the design looks good. Items 1–3 are the substantive ones, because they are exactly the drift this PR is meant to prevent.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

  • [P2] Comment-only harness edits satisfy the model-update requirement — scripts/check-model-sync.py:363. rust_content() removes only full-line // comments. Editing an inline comment or a /* ... */ comment counts as a harness update, allowing a production-core change to pass without updating its Loom model or supplying the waiver. Strip Rust comments while preserving string literals, and add regression tests for both cases.

All 45 model-sync tests and the model inventory check pass. No production runtime behavior changes. The pinned-toolchain Clippy check could not run because rustup requires filesystem writes outside the permitted paths.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

This PR looks good. The mechanism for enforcing shim usage in the Loom-checked cores via item-scoped #[deny(clippy::disallowed_types, clippy::disallowed_methods)] under --cfg spawned_scheduler_loom (while keeping the lints allowed for production re-exports) is clean, and the check-model-sync.py extensions for [loom.*] mappings and two-sided TLA+/Loom coverage checks are well-structured and thoroughly covered by unit tests.


Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

The model-sync split is sound: TLA and Loom are independent gates, code must match #[path] includes, and the new tests cover that. The clippy enforcement in CI does not actually run.

Bug: the Loom clippy job cannot fail

.github/workflows/verification.yml (~line 200) ends with -- -A clippy::all. Command-line -A overrides in-source #[deny], including forbid. The #[deny(clippy::disallowed_types, clippy::disallowed_methods)] on the #[path] modules is therefore a no-op in this job, and a direct std::sync::atomic::* / parking_lot use in a core will still pass.

cargo clippy also injects -D warnings, which is why -A is there, but it has to be narrowed afterward. Later flags win:

run: cargo clippy --locked -p spawned-concurrency --no-default-features --test mailbox_admission_loom --test reply_slot_loom --test registry_turn_loom --test job_core_loom --test link_fence_loom --test stop_token_loom -- -A warnings -D clippy::disallowed_types -D clippy::disallowed_methods

That deny is crate-wide, not just the included core. Confirm the harnesses only spawn/synchronize through loom:: (they ban std::thread::spawn). Also confirm this job’s toolchain includes the clippy component; otherwise the step fails for an unrelated reason.

Gap: ready_gate is mapped but not linted

[loom.ReadyGate] in verification/model-map.toml treats concurrency/benches/support/ready_gate.rs as a Loom-checked core, but ready_gate_loom.rs never got the #[deny(...)], and the new clippy step does not pass --test ready_gate_loom. A direct std/parking_lot atomic there stays invisible to Loom. Either add both, or document that this prototype is exempt from concurrency/clippy.toml.

Smaller holes

  • rust_content in scripts/check-model-sync.py only drops full-line // comments. A /* */ edit, or a trailing // on a real line, counts as a harness update and satisfies model-sync without a logic change. Strip block comments the same way rust_mask already does for #[path].
  • concurrency/clippy.toml misses types that would also bypass the shim: AtomicU128 / AtomicI128, std::sync::{Once, OnceLock, LazyLock}, parking_lot::{FairMutex, Once}, and std::sync::atomic::compiler_fence. std::sync::mpsc is the same class of hole if a core starts using it.

Automated review by Grok (xAI) · grok-4.7 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

The PR only changes verification/tooling; no production concurrency code is touched. Overall the approach is good, but there are a few gaps in the enforcement scripts.

  1. Workflow omits ready_gate_loom from the clippy ban
    .github/workflows/verification.yml runs clippy for six --test targets, but the new verification/model-map.toml adds:

    [loom.ReadyGate]
    files = ["concurrency/tests/ready_gate_loom.rs"]
    code = ["concurrency/benches/support/ready_gate.rs"]

    If that harness exists, direct std/parking_lot synchronization in ready_gate.rs will not be rejected. Add --test ready_gate_loom to the clippy command, or remove the map entry.

  2. check_loom treats Loom files/code as literal paths, not globs
    scripts/check-model-sync.py in check_loom does:

    if not (root / f).is_file():
    ...
    included |= loom_includes(root, f)
    ...
    if included != code:

    while check_paths uses glob_match for both model files and code. The model-map.toml header says globs are supported and Loom entries are “mapped the same way”, so a future [loom.*] entry using a glob in files/code will fail check_models incorrectly. Either expand globs here consistently, or document that Loom entries require exact paths.

  3. rust_content mishandles block/trailing comments

    def rust_content(src):
        """Rust source without `//` comment lines and blank lines."""
        return [l.strip() for l in src.splitlines() if l.strip() and not l.strip().startswith("//")]

    This only strips standalone line comments. /* ... */, /** ... */, and trailing comments are treated as substantive code. That can let a PR change a core and add an unrelated block comment to a Loom harness, causing model_file_changed to count it as a material harness update and bypass the model-sync check. Reuse the existing rust_mask/comment stripper for .rs comparisons.

A minor note: confirm -A clippy::all in the new workflow does not override the source #[deny(clippy::disallowed_types, clippy::disallowed_methods)] attributes; source attributes usually win, but the whole job depends on that precedence.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

Findings

  1. Comment-only harness edits can incorrectly satisfy model-sync — scripts/check-model-sync.py:363-366
    rust_content() removes only blank lines and full-line // comments. Consequently, these comment-only changes count as substantive model updates:

    fn check() {} // still valid

    or:

    /* still valid */
    fn check() {}

    A PR could therefore change a Loom-checked core, make only such a comment edit to its harness, and pass without the waiver. Block-comment-only edits can also produce false failures in the opposite direction. Use Rust-aware comment stripping for both inline // and /* ... */ comments while preserving string literals; the existing rust_mask() machinery may help.

  2. The Clippy check can silently omit newly added Loom harnesses — .github/workflows/verification.yml:197-200, scripts/check-model-sync.py:692-731
    check_loom() ensures new harnesses are added to model-map.toml, but the Clippy job uses a separate, manually maintained --test list. A new harness can therefore be correctly mapped and pass model-sync, yet never have its included core checked for direct std/parking_lot synchronization. Omitting the #[deny(...)] attribute is likewise not validated. Consider deriving the Clippy test list from the map, or adding an inventory check tying mapped production-code harnesses to the workflow list. If ReadyGate is intentionally excluded because it is benchmark-only, encode that exclusion explicitly.

Otherwise, the split between TLA+ and Loom update requirements looks correct, including the case where a core needs both sides updated, and the map/include consistency tests cover the main inventory cases well.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@unbalancedparentheses
unbalancedparentheses added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit e2d36b8 Nov 16, 2026
57 checks passed
unbalancedparentheses added a commit that referenced this pull request Nov 16, 2026
…marks; map the ReadyGate Loom harness to benchmarks/experiments
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.

1 participant