Skip to content

Migrate to Polonius and evolve internal APIs around borrowing (#465) #472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
leynos wants to merge 20 commits into
base: main
Choose a base branch
from
Open

Migrate to Polonius and evolve internal APIs around borrowing (#465) #472

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
0dc5b3a
Adopt Polonius on pinned nightly toolchain
Jul 28, 2026
2286179
Evolve graph_view node registry to borrow-returning form
Jul 28, 2026
7564c72
Drop redundant key clone in group_by grouping loop
Jul 28, 2026
081cfa8
Snapshot borrowed keys in cycle detection traversal
Jul 28, 2026
4a033a0
Borrow search directories in the which resolver
Jul 28, 2026
d87fe4a
Tag principled Polonius refusals at ownership boundaries
Jul 28, 2026
9b2fa4d
Document the Polonius audit and anti-regression contract
Jul 28, 2026
8f56c9d
Compile Kani cfg policy fixture directly, not via trybuild
Jul 28, 2026
5000642
Record harness consequences in Polonius notes
Jul 28, 2026
da75c18
Keep Polonius flag when CI presets RUSTFLAGS
leynos Jul 29, 2026
931fb61
Restructure edge registration to flatten nested logic
leynos Jul 29, 2026
2da93c8
Keep Polonius flag in release artefact builds
leynos Jul 29, 2026
32f998d
Address review: checkout credentials and audit wording
leynos Jul 29, 2026
6935b5f
Document explicit toolchain for registry installs
leynos Jul 29, 2026
166359a
Address review: config wording, edge helper, cwd duplication
leynos Jul 29, 2026
2572834
Split Windows setup checks out of install contract test
leynos Jul 29, 2026
9aecea5
Extract release-install checks from install contract test
leynos Jul 29, 2026
e70cafe
Route quickstart installs through the users' guide
leynos Jul 29, 2026
f00feef
Collapse double blank line left by rebase merge
leynos Jul 30, 2026
7618f5c
Collapse double blank line from rebase merge
leynos Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .cargo/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Enable the Polonius alpha borrow-checking analysis for every Cargo
# invocation, including rust-analyzer and `cargo kani`, so editors and
# verification tooling agree with CI about what borrows are legal.
#
# Note: an inherited `RUSTFLAGS` environment variable overrides this table.
# Wrappers that set `RUSTFLAGS` (see the Makefile) must re-state
# `-Zpolonius=next` themselves. See
# docs/adr-006-adopt-polonius-nightly-toolchain.md.
[build]
rustflags = ["-Zpolonius=next"]

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 29, 2026

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 Preserve Polonius settings for registry installs

Once this source is published, the documented bare cargo install netsuke runs outside the checkout and therefore receives neither this flag nor the pinned nightly: the manifest's package allow-list excludes both .cargo/config.toml and rust-toolchain.toml (Cargo's package --list help describes that command as printing the files included in the package). The packaged source now contains a Polonius-only accessor, so ordinary registry installs compile it under the user's toolchain without -Zpolonius=next and fail with E0499. Keep distributed source NLL-compatible or document and validate an install command that explicitly selects the nightly and passes the flag.

AGENTS.md reference: AGENTS.md:L205-L207

Useful? React with 👍 / 👎.

@leynos leynos Jul 29, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

@coderabbitai Has this now been resolved in the latest commit?

Use codegraph analysis to determine your answer.

If this comment is now resolved, please mark it as such using the API. Otherwise, please provide an AI agent prompt for the remaining work to be done to address this comment.

@coderabbitai coderabbitai Bot Jul 29, 2026

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.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Current commit and package configuration =='
git rev-parse HEAD
printf '\n-- Cargo package fields --\n'
rg -n -A12 -B3 '^\[package\]|\b(include|exclude)\s*=' Cargo.toml || true
printf '\n-- Files Cargo says are packaged --\n'
cargo package --list --allow-dirty 2>&1 | sed -n '1,220p' || true

printf '\n== Module map ==\n'
ast-grep outline src/graph_view/mod.rs --items all --match 'NodePathRegistry|ensure_node_mut|EdgeRegistrar|from_build_graph' --view expanded

printf '\n== Borrow-centric registry symbols and callers ==\n'
rg -n -C5 '\b(NodePathRegistry|ensure_node_mut)\b' src/graph_view/mod.rs src/graph_view/tests.rs

printf '\n== Polonius-tagged sites and installation guidance ==\n'
rg -n -C4 'POLONIUS|cargo install|install netsuke|Zpolonius|nightly-2026-06-25' \
  Cargo.toml README.md docs AGENTS.md Makefile .cargo/config.toml rust-toolchain.toml \
  -g '!docs/contents.md' || true

printf '\n== Tracked package/build configuration status ==\n'
git ls-files .cargo/config.toml rust-toolchain.toml Cargo.toml README.md docs/adr-006-adopt-polonius-nightly-toolchain.md docs/polonius.md

Length of output: 1254

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== PR head =='
git rev-parse HEAD

printf '%s\n' '== Package boundary =='
sed -n '1,140p' Cargo.toml
printf '%s\n' '-- configuration files tracked by Git --'
git ls-files --stage .cargo/config.toml rust-toolchain.toml

printf '%s\n' '== Registry accessor definition and direct call graph =='
ast-grep outline src/graph_view/mod.rs --items all --match 'NodePathRegistry|ensure_node_mut|EdgeRegistrar|from_build_graph' --view expanded
rg -n -C5 '\b(NodePathRegistry|ensure_node_mut)\b' src/graph_view/mod.rs src/graph_view/tests.rs

printf '%s\n' '== Packaged-install and Polonius guidance =='
rg -n -i -C4 'cargo\s*(\+[^[:space:]]+\s*)?install|install\s+netsuke|registry|Zpolonius|nightly-2026-06-25|POLONIUS' \
  README.md Cargo.toml docs AGENTS.md .cargo/config.toml rust-toolchain.toml || true

Length of output: 74717

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Documentation contract-test map =='
ast-grep outline tests/documentation_examples_tests.rs --items all --view expanded

printf '%s\n' '== Registry-install example assertions and fixture discovery =='
rg -n -i -C6 'readme-crates-io-install|guide-crates-io-install|RUSTFLAGS=-Zpolonius=next|cargo \+nightly-2026-06-25 install netsuke|rustup toolchain install nightly-2026-06-25' \
  tests README.md docs/users-guide.md

printf '%s\n' '== All documentation-example test call sites =='
rg -n -C4 'tested-example|documentation_examples|README\.md|users-guide\.md' tests \
  -g '*.rs' -g '*.md' || true

Length of output: 753

@leynos, do not resolve this thread. The latest commit fixes the README and users’ guide, but docs/quickstart.md still tells users to install via bare cargo install netsuke (Line 11). That registry build receives neither the pinned nightly nor -Zpolonius=next, while the NodePathRegistry::ensure_node_mut code path remains explicitly Polonius-only.

The documentation-contract-test inspection also failed because repository setup was unavailable, so its coverage remains unverified.

Use this AI-agent prompt to finish the remaining work:

Fix the remaining unsupported crates.io installation instruction for Netsuke.

Context:
- `Cargo.toml` packages neither `.cargo/config.toml` nor `rust-toolchain.toml`.
- `src/graph_view/mod.rs::NodePathRegistry::ensure_node_mut` requires `-Zpolonius=next`; it is intentionally rejected by NLL.
- The supported registry installation command is:
  rustup toolchain install nightly-2026-06-25
  RUSTFLAGS=-Zpolonius=next cargo +nightly-2026-06-25 install netsuke
- `README.md` and `docs/users-guide.md` already use this command.
- `docs/quickstart.md` still says `cargo install netsuke`, which is unsupported and must not remain as a standalone installation instruction.

Required changes:
1. Update `docs/quickstart.md` to direct users to the supported pinned-nightly and Polonius registry-install command, or link unambiguously to the canonical installation instructions in `docs/users-guide.md`.
2. Inspect `tests/documentation_examples_tests.rs` and its helpers/fixtures. Add or update a contract test so every tagged registry-install example requires both:
   - `cargo +nightly-2026-06-25`
   - `RUSTFLAGS=-Zpolonius=next`
3. Search all user-facing documentation for `cargo install netsuke`. Replace any bare registry-install command or explicitly scope it to a checkout-local `cargo install --path .` invocation where the repository configuration applies.
4. Run the project’s documentation validation and relevant test target under the pinned nightly with Polonius enabled.
5. Report the changed files, the exact validation commands, and their results.

5 changes: 5 additions & 0 deletions .github/workflows/build-and-package.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ jobs:
BIN_NAME: ${{ inputs['bin-name'] }}
VERSION: ${{ inputs.version }}
MAN_ARCH: ${{ inputs['package-arch'] != '' && inputs['package-arch'] || 'unknown' }}
# Pre-set RUSTFLAGS so the setup-rust-toolchain step nested inside
# rust-build-release does not export its "-D warnings" default, which
# would shadow .cargo/config.toml and strip -Zpolonius=next (see
# docs/adr-006-adopt-polonius-nightly-toolchain.md).
RUSTFLAGS: -Zpolonius=next
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
# v7.0.1
Expand Down
40 changes: 13 additions & 27 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,20 @@ on:

jobs:
build-test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest]
rust: [stable, '1.89.0']
# Nightly is experimental; stable and MSRV are the supported toolchains
include:
- os: ubuntu-latest
rust: nightly
experimental: true
continue-on-error: ${{ matrix.experimental || false }}
runs-on: ubuntu-latest
permissions:
contents: read
env:
CARGO_TERM_COLOR: always
BUILD_PROFILE: debug
# Override rust-toolchain.toml to actually use the matrix toolchain
RUSTUP_TOOLCHAIN: ${{ matrix.rust }}
# The tree requires -Zpolonius=next (see
# docs/adr-006-adopt-polonius-nightly-toolchain.md), so CI builds with
# the dated nightly pinned in rust-toolchain.toml.
NETSUKE_RUST_TOOLCHAIN: nightly-2026-06-25
# Pre-set RUSTFLAGS so setup-rust-toolchain's "-D warnings" default does
# not shadow .cargo/config.toml and strip -Zpolonius=next; tools such as
# cargo-llvm-cov append their own flags to this value.
RUSTFLAGS: -D warnings -Zpolonius=next
WHITAKER_INSTALLER_VERSION: '0.2.6'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Expand All @@ -36,7 +31,7 @@ jobs:
- name: Setup Rust
uses: leynos/shared-actions/.github/actions/setup-rust@4d696e72fff6db49f34302ccf119ba978f1032c9
with:
toolchain: ${{ matrix.rust }}
toolchain: ${{ env.NETSUKE_RUST_TOOLCHAIN }}
components: rustfmt, clippy
- name: Show rustc version
run: |
Expand All @@ -48,15 +43,13 @@ jobs:
- name: Format
run: make check-fmt
- name: Cache Whitaker installer
if: matrix.rust == 'stable'
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: |
~/.cargo/bin/whitaker-installer
~/.cache/cargo-binstall
key: whitaker-installer-${{ runner.os }}-${{ runner.arch }}-${{ env.WHITAKER_INSTALLER_VERSION }}
- name: Install Whitaker
if: matrix.rust == 'stable'
run: |
if ! command -v whitaker-installer >/dev/null 2>&1; then
if cargo binstall --version >/dev/null 2>&1; then
Expand All @@ -68,13 +61,7 @@ jobs:
fi
whitaker-installer
- name: Lint
if: matrix.rust == 'stable'
run: make lint
# Whitaker lints under its own pinned toolchain, so re-running it per
# matrix leg repeats identical work; non-stable legs run Clippy only.
- name: Lint (Clippy only)
if: matrix.rust != 'stable'
run: make lint-clippy
- name: Setup uv
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990
with:
Expand All @@ -86,17 +73,16 @@ jobs:
path: |
.typos-oxendict-base.json
.typos-oxendict-base.toml
key: oxendict-${{ runner.os }}-${{ matrix.rust }}-${{ hashFiles('typos.local.toml') }}-${{ github.run_id }}
key: oxendict-${{ runner.os }}-${{ env.NETSUKE_RUST_TOOLCHAIN }}-${{ hashFiles('typos.local.toml') }}-${{ github.run_id }}
restore-keys: |
oxendict-${{ runner.os }}-${{ matrix.rust }}-${{ hashFiles('typos.local.toml') }}-
oxendict-${{ runner.os }}-${{ env.NETSUKE_RUST_TOOLCHAIN }}-${{ hashFiles('typos.local.toml') }}-
- name: Spelling
run: make spelling
- name: Workflow contract tests
run: make test-workflow-contracts
- name: Test
run: make test
- name: Test and Measure Coverage
if: matrix.rust == 'stable'
uses: leynos/shared-actions/.github/actions/generate-coverage@18bed1ca49a6de3d8882bd72635a32ae3f023d57
with:
output-path: lcov.info
Expand All @@ -105,7 +91,7 @@ jobs:
# coverage-main.yml (caches saved on main are readable by every PR).
with-ratchet: 'true'
- name: Check coverage against CodeScene gates
if: matrix.rust == 'stable' && env.CS_ACCESS_TOKEN != '' && github.event_name == 'pull_request'
if: env.CS_ACCESS_TOKEN != '' && github.event_name == 'pull_request'
env:
CS_ACCESS_TOKEN: ${{ secrets.CS_ACCESS_TOKEN }}
uses: leynos/shared-actions/.github/actions/upload-codescene-coverage@18bed1ca49a6de3d8882bd72635a32ae3f023d57
Expand Down
10 changes: 9 additions & 1 deletion .github/workflows/coverage-main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,20 @@ jobs:
env:
CARGO_TERM_COLOR: always
BUILD_PROFILE: debug
# Pre-set RUSTFLAGS so setup-rust-toolchain's "-D warnings" default does
# not shadow .cargo/config.toml and strip -Zpolonius=next; cargo-llvm-cov
# appends its instrumentation flags to this value.
RUSTFLAGS: -D warnings -Zpolonius=next
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
Comment thread
coderabbitai[bot] marked this conversation as resolved.
with:
persist-credentials: false
- name: Setup Rust
uses: leynos/shared-actions/.github/actions/setup-rust@4d696e72fff6db49f34302ccf119ba978f1032c9
with:
toolchain: stable
# Match rust-toolchain.toml: the tree needs -Zpolonius=next (see
# docs/adr-006-adopt-polonius-nightly-toolchain.md).
toolchain: nightly-2026-06-25
components: rustfmt, clippy
- name: Test and Measure Coverage
uses: leynos/shared-actions/.github/actions/generate-coverage@18bed1ca49a6de3d8882bd72635a32ae3f023d57
Expand Down
19 changes: 11 additions & 8 deletions .github/workflows/netsukefile-test.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,24 @@ on:
jobs:
netsukefile:
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
rust: [stable, '1.89.0']
permissions:
contents: read
env:
RUSTUP_TOOLCHAIN: ${{ matrix.rust }}
# Match rust-toolchain.toml: the tree needs -Zpolonius=next (see
# docs/adr-006-adopt-polonius-nightly-toolchain.md).
NETSUKE_RUST_TOOLCHAIN: nightly-2026-06-25
# Pre-set RUSTFLAGS so setup-rust-toolchain's "-D warnings" default does
# not shadow .cargo/config.toml and strip -Zpolonius=next.
RUSTFLAGS: -Zpolonius=next
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Setup Rust
uses: leynos/shared-actions/.github/actions/setup-rust@4d696e72fff6db49f34302ccf119ba978f1032c9
with:
toolchain: ${{ matrix.rust }}
toolchain: ${{ env.NETSUKE_RUST_TOOLCHAIN }}
- name: Show rustc version
run: |
rustup show
Expand All @@ -36,9 +39,9 @@ jobs:
path: |
~/.cargo/registry
~/.cargo/git
key: ${{ runner.os }}-cargo-${{ matrix.rust }}-${{ hashFiles('**/Cargo.lock') }}
key: ${{ runner.os }}-cargo-${{ env.NETSUKE_RUST_TOOLCHAIN }}-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
${{ runner.os }}-cargo-${{ matrix.rust }}-
${{ runner.os }}-cargo-${{ env.NETSUKE_RUST_TOOLCHAIN }}-
${{ runner.os }}-cargo-
- name: Clean build artefacts
run: make clean
Expand Down
23 changes: 23 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,29 @@ This repository is written in Rust and uses Cargo for building and dependency
management. Contributors should follow these best practices when working on the
project:

### Borrow checker: Polonius, not NLL

Netsuke compiles with the Polonius alpha analysis (`-Zpolonius=next`) on the
dated nightly pinned in `rust-toolchain.toml` (see
`docs/adr-006-adopt-polonius-nightly-toolchain.md` and `docs/polonius.md`).
Internal APIs are borrow-centric: lookups and get-or-create accessors return
references, clone keys only on insertion, and build error context lazily.

- **Never** rewrite a site tagged `POLONIUS(...)` into a double lookup
(`contains_key` + `get_mut`), an `entry(key.clone())` call, or an
id/index round-trip. Those forms are the NLL-era workarounds this
codebase deliberately retired; the direct form is compiler-verified.
- **Never** silence a borrow error by adding a defensive `.clone()`, an
eager error-context computation, or a snapshot `collect()` without first
compiling the natural borrow-returning form under the project toolchain —
it usually compiles.
- Respect `POLONIUS-REFUSED(...)` tags: the named constraint (persistent
identity, lock boundaries, aliasing, suspension points, thread
boundaries) is permanent. Do not convert those sites to
reference-returning forms.
- When adding a new borrow-centric API, verify it with and without
`-Zpolonius=next` and record the classification in `docs/polonius.md`.

- Run `make check-fmt`, `make lint`, and `make test` before committing. These
targets wrap the following commands, so contributors understand the exact
behaviour and policy enforced:
Expand Down
26 changes: 26 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Changelog

## Unreleased

### Changed

- Route graph-view node registration through a borrow-returning
`NodePathRegistry` accessor that looks paths up once on hits and clones a
path only on insertion
([#465](https://github.com/leynos/netsuke/issues/465))
- Build with the Polonius borrow checker (`-Zpolonius=next`) on the pinned
`nightly-2026-06-25` toolchain; checkout builds pick this up
automatically via `rustup`, while registry installs must pass the
toolchain and flag explicitly
(`RUSTFLAGS=-Zpolonius=next cargo +nightly-2026-06-25 install netsuke`)
([#465](https://github.com/leynos/netsuke/issues/465))
- Remove the `rust-version = "1.89.0"` minimum-supported-Rust-version
declaration from `Cargo.toml`; `rust-toolchain.toml` is now the single
source of truth for the compiler contract
([#465](https://github.com/leynos/netsuke/issues/465))

## [0.1.0] - 2026-07-28

_Initial release._

[0.1.0]: https://github.com/leynos/netsuke/releases/tag/v0.1.0
55 changes: 0 additions & 55 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 0 additions & 2 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
name = "netsuke"
version = "0.1.0"
edition = "2024"
rust-version = "1.89.0"
include = [
"src/**",
"locales/**",
Expand Down Expand Up @@ -173,7 +172,6 @@ strip-ansi-escapes = "0.2"
toml = "0.8"
serde_yaml = "0.9"
proptest = "1.11.0"
trybuild = "1.0.116"

# Target-specific dev-deps
[target.'cfg(unix)'.dev-dependencies]
Expand Down
Loading
Loading