Migrate to Polonius and evolve internal APIs around borrowing

[leynos]

Summary

Migrate Netsuke to the Polonius alpha borrow-checking analysis
(-Zpolonius=next) and use the migration to evolve internal APIs towards a
borrow-centric ownership model.

Netsuke is a pre-1.0 application, so this should use Mode E: model
evolution, not stop at enabling a compiler flag. The goal is to replace
NLL-shaped owned-value APIs with natural reference-returning forms where
Polonius removes a lifetime limitation, while retaining ownership where
aliasing, suspension points, thread/process boundaries, or persistent identity
require it.

Deployment posture

Adopt Polonius now:

• Pin a dated nightly toolchain.
• Enable -Zpolonius=next for Cargo, CI, and rust-analyzer.
• Reconcile the current stable/MSRV CI policy and rust-version = "1.89.0"
  metadata with a nightly-only, Polonius-dependent source tree.
• Record the compiler-policy decision in an ADR and update build, contributor,
  and release documentation.

Audit and model evolution

Run the nll-to-polonius two-pass audit and classify every candidate with the
compiler as the oracle:

1. Scan local NLL workaround shapes.
2. Scan structural design pressure: owned lookup results, id/index
   indirection, clone-modify-writeback, eager error context, snapshot
   collection, and clone hotspots.

For each change, verify it both with and without -Zpolonius=next so the
tracking document distinguishes genuine Polonius-dependent designs from
improvements that already compile under NLL.

The existing audit identifies an initial evolution target in
src/graph_view/mod.rs: the three entry(path.clone()).or_insert(...) sites
should be routed through a node-path registry accessor that returns &mut NodeKind, performs one lookup on hits, and clones a path only on insertion.

The action hash in src/ir/from_manifest_support.rs is a deliberate refusal:
the hash is persistent IR identity, so it should remain owned unless callers
develop a demonstrated need for the canonical interned value. Record it as
POLONIUS-REFUSED(id-is-data) rather than converting ids indiscriminately.

Documentation and sequencing

• Land one owning API evolution per atomic commit, migrating call sites before
  deleting superseded APIs.
• Add docs/polonius.md with rewritten sites, API evolution targets,
  stabilization candidates, and principled refusals.
• Tag source sites with POLONIUS(...), POLONIUS-CANDIDATE(...), or
  POLONIUS-REFUSED(...) as appropriate.
• Add anti-regression guidance to AGENTS.md so direct borrow-centric forms are
  not rewritten into double lookups, defensive clones, or id indirection.
• Update README.md, docs/developers-guide.md, docs/netsuke-design.md, the
  changelog, and docs/contents.md with the new toolchain and design contract.

Acceptance criteria

• A dated nightly is pinned and Cargo, CI, and rust-analyzer consistently
  enable -Zpolonius=next.
• An ADR explicitly resolves the stable/MSRV, package metadata, and release
  consequences of adopting a nightly-only borrow checker.
• The complete two-pass audit is recorded in docs/polonius.md, including
  refusals for permanent ownership constraints.
• The graph_view node registry uses the borrow-returning, clone-on-miss
  accessor and its Polonius dependency is compiler-verified.
• Each evolution is checked with and without the Polonius flag, then covered
  by the unchanged behavioural test suite.
• No test behaviour is weakened merely to accommodate ownership changes.
• Clone counts and clone-modify-writeback findings are recorded before and
  after the migration.
• make check-fmt, make lint, make test, make markdownlint, and
  make nixie pass under the adopted toolchain contract.

References

• src/graph_view/mod.rs
• src/ir/from_manifest_support.rs
• rust-toolchain.toml
• .github/workflows/ci.yml
• docs/netsuke-design.md
• docs/developers-guide.md

[coderabbitai]

🔗 Related PRs

leynos/rust-skill#4 - Extend the Rust skill catalogue with verification and supply-chain skills [closed]
leynos/rentaneko#6 - Plan: Minimal Octocrab-to-Simulacat compatibility checkpoint (1.1.1) [merged]
leynos/zamburak#57 - Adopt the Whitaker Dylint suite in the lint gate and CI [merged]
#427 - Align v0.1.0 documentation and test every example [merged]
leynos/wildside#445 - Patch frontend dependency vulnerabilities [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!