Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
15 changes: 7 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,17 +142,16 @@ 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.
(`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.
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.
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`.

Expand Down
12 changes: 5 additions & 7 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,15 @@

- 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))
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
`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
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
Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,16 @@ Netsuke currently requires:
- [Ninja](https://ninja-build.org/) on `PATH`;
- when installing from source, the dated Rust nightly toolchain pinned in
[`rust-toolchain.toml`](rust-toolchain.toml) (`rustup` installs it
automatically in a checkout). Netsuke builds with the Polonius borrow
checker (`-Zpolonius=next`), which is nightly-only until it stabilizes; see
automatically in a checkout). Netsuke builds with the Polonius borrow checker
(`-Zpolonius=next`), which is nightly-only until it stabilizes; see
[ADR-006](docs/adr-006-adopt-polonius-nightly-toolchain.md).

### Installation

Netsuke v0.1.0 is available from crates.io. Where
[`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) is
available, prefer it: it fetches a prebuilt release binary and avoids the
toolchain requirement below.
[`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) is available,
prefer it: it fetches a prebuilt release binary and avoids the toolchain
requirement below.

<!-- tested-example: readme-binstall-install -->

Expand All @@ -53,8 +53,8 @@ cargo binstall netsuke
```

Building from the registry instead runs outside a repository checkout, so
neither the pinned toolchain nor the Polonius flag is picked up
automatically; supply both explicitly:
neither the pinned toolchain nor the Polonius flag is picked up automatically;
supply both explicitly:

<!-- tested-example: readme-crates-io-install -->

Expand Down
37 changes: 18 additions & 19 deletions docs/adr-006-adopt-polonius-nightly-toolchain.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ several of these shapes, so the natural borrow-returning form of an accessor
can compile where NLL rejected it.

Adopting those borrow-centric designs binds the source tree to a
Polonius-enabled compiler, which is nightly-only until the analysis
stabilizes. That conflicts with three standing policies:
Polonius-enabled compiler, which is nightly-only until the analysis stabilizes.
That conflicts with three standing policies:

- `rust-toolchain.toml` pinned stable `1.89.0`;
- `Cargo.toml` declared `rust-version = "1.89.0"` as a minimum supported Rust
Expand Down Expand Up @@ -52,20 +52,20 @@ Adopt Polonius now, as a nightly-only source tree:
nightly requirement there, and advertising `1.89.0` would misstate the
contract; `rust-toolchain.toml` is now the single source of truth.

Every borrow-centric rewrite that depends on the flag is verified both with
and without `-Zpolonius=next` and recorded in
Every borrow-centric rewrite that depends on the flag is verified both with and
without `-Zpolonius=next` and recorded in
[polonius migration notes](polonius.md), including refusals where owned style
remains correct.

## Rationale

- **Design over deployment breadth.** Netsuke ships binaries, not a library
API. Consumers install packaged artefacts or build from source; the
toolchain pin costs contributors one `rustup` fetch, whereas NLL-era
double lookups and key clones cost every call site, forever.
API. Consumers install packaged artefacts or build from source; the toolchain
pin costs contributors one `rustup` fetch, whereas NLL-era double lookups and
key clones cost every call site, forever.
- **Reproducibility.** A dated nightly behaves like a release: the same
compiler bits build the tree everywhere. `rustup` provisions it
automatically from `rust-toolchain.toml`.
compiler bits build the tree everywhere. `rustup` provisions it automatically
from `rust-toolchain.toml`.
- **Coherent tooling.** Putting the flag in `.cargo/config.toml` keeps
rust-analyzer, Clippy, Whitaker (whose Dylint driver is nightly-based), and
Kani borrow-checking the same dialect, avoiding phantom editor errors on
Expand All @@ -81,19 +81,18 @@ remains correct.
`rust-toolchain.toml` and `.cargo/config.toml` (and Cargo would not apply
them to a registry build anyway), so a bare `cargo install netsuke` of a
Polonius-dependent release fails borrow checking on the user's default
toolchain. Registry installs must select the pinned nightly and pass the
flag explicitly
(`RUSTFLAGS=-Zpolonius=next cargo +nightly-2026-06-25 install netsuke`);
the README and users' guide document this command and a contract test pins
it. Source installs from a checkout are unaffected because the pinned
toolchain and workspace configuration apply there.
toolchain. Registry installs must select the pinned nightly and pass the flag
explicitly
(`RUSTFLAGS=-Zpolonius=next cargo +nightly-2026-06-25 install netsuke`); the
README and users' guide document this command and a contract test pins it.
Source installs from a checkout are unaffected because the pinned toolchain
and workspace configuration apply there.
- Release packaging builds from the pinned nightly. Binary artefacts are
unaffected: the borrow checker changes what compiles, not what is
generated.
unaffected: the borrow checker changes what compiles, not what is generated.
- Dependabot-style toolchain drift is impossible; moving the pin is a
deliberate act. Move it forward periodically (and especially once Polonius
stabilizes), re-running the full gate suite, and update this ADR's
references when doing so.
stabilizes), re-running the full gate suite, and update this ADR's references
when doing so.
- Sites that genuinely require Polonius are tagged `POLONIUS(...)` in source
and must not be rewritten into NLL-era defensive forms; `AGENTS.md` and
[polonius migration notes](polonius.md) carry the anti-regression guidance.
Expand Down
Loading
Loading