docs: formalize locator refresh state contract

[karthiknadig]

Summary:

• Document the refresh-state contract for transient locator refreshes.
• Add an inventory of current locator mutable state and classifications.
• Add a regression test that pins create_locators() refresh-state classifications by platform.

Validation:

• cargo test -p pet test_locator_graph_refresh_state_contracts_are_explicit
• cargo fmt --all
• cargo clippy --all -- -D warnings

Fixes #387

[github-actions]

Performance Report (Linux) ➖

Metric	PR (P50)	PR (P95)	Baseline (P50)	Delta	Change
Server Startup	1ms	1ms	1ms	0ms	0%
Full Refresh	79ms	293ms	78ms	1ms	0%

Results based on 10 iterations. P50 = median, P95 = 95th percentile.

---

Legend

• 🚀 Significant speedup (>100ms faster)
• ✅ Faster than baseline
• ➖ No significant change
• 🔺 Slower than baseline (>100ms)
• ⚠️ Significant slowdown (>500ms)

[github-actions]

Test Coverage Report (Linux)

Metric	Value
Current Coverage	73.6%
Base Branch Coverage	73.4%
Delta	.2% ✅

---

Coverage increased! Great work!

[github-actions]

Performance Report (macOS)

Metric	PR (P50)	PR (P95)	Baseline (P50)	Delta
Server Startup	85ms	1078ms	101ms	-16ms
Full Refresh	151ms	38247ms	184ms	-33ms

Results based on 10 iterations. P50 = median, P95 = 95th percentile.

---

Legend

• 🚀 Significant speedup (>100ms faster)
• ✅ Faster than baseline
• ➖ No significant change
• 🔺 Slower than baseline (>100ms)
• ⚠️ Significant slowdown (>500ms)

[github-actions]

Performance Report (Windows) ➖

Metric	PR (P50)	PR (P95)	Baseline (P50)	Delta	Change
Server Startup	9ms	12ms	9ms	0ms	0%
Full Refresh	164ms	2378ms	155ms	9ms	5.8%

Results based on 10 iterations. P50 = median, P95 = 95th percentile.

---

Legend

• 🚀 Significant speedup (>100ms faster)
• ✅ Faster than baseline
• ➖ No significant change
• 🔺 Slower than baseline (>100ms)
• ⚠️ Significant slowdown (>500ms)

[github-actions]

Test Coverage Report (Windows)

Metric	Value
Current Coverage	69.86%
Base Branch Coverage	69.65%
Delta	0.21% ✅

---

Coverage increased! Great work!

[Copilot]

Pull request overview

This PR formalizes and documents PET’s “refresh-state” contract for transient locator graphs, clarifying which locator state is expected to persist across refresh boundaries and adding a regression test to prevent accidental drift in those classifications.

Changes:

• Add a dedicated document describing Locator::refresh_state() classifications and an inventory of current locator mutable state.
• Link the new locator-state documentation from the project README.
• Add a unit test that pins create_locators() locator ordering + RefreshStatePersistence classifications per platform.

Show a summary per file

File	Description
README.md	Adds a pointer to the new locator refresh-state contract documentation.
docs/LOCATOR_STATE.md	Introduces the refresh-state contract and inventories locator state/classifications.
crates/pet/src/jsonrpc.rs	Adds a regression test asserting each created locator’s refresh_state() classification (platform-aware).
crates/pet-core/src/lib.rs	Expands inline documentation for RefreshStatePersistence and the Locator::refresh_state() contract.

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 1

[Copilot]

Pull request overview

This PR formalizes and documents the “refresh-state” contract for locators when refresh executes against a transient locator graph, ensuring it’s explicit which locator state is allowed/required to survive refresh boundaries.

Changes:

• Add docs/LOCATOR_STATE.md documenting refresh-state classifications and an inventory of locator mutable state.
• Link the new locator-state documentation from the root README.
• Add a regression test that asserts create_locators() returns locators with explicit RefreshStatePersistence classifications per platform; clarify the contract in pet-core docs.

Show a summary per file

File	Description
README.md	Adds a pointer to the new locator refresh-state contract documentation; minor formatting cleanup.
docs/LOCATOR_STATE.md	New doc describing refresh-state classifications and current locator state inventory.
crates/pet/src/jsonrpc.rs	Adds a unit test pinning locator kinds to RefreshStatePersistence for the create_locators() graph.
crates/pet-core/src/lib.rs	Expands rustdoc for RefreshStatePersistence and Locator::refresh_state() to codify the contract.

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 0 new