feat(pointer): keep the first final state, and look before taking one

Cargo.toml

@@ -214,6 +214,13 @@ webrtc-direct = [
     "saorsa-transport/webrtc-direct",
 ]
 
+[patch.crates-io]
+# The published 4.0.0 carries pointers (ADR-0016) but not the final state this
+# change relies on (ADR-0018). A rev, not a branch, so the pin is immutable.
+# Drop it once a release includes the companion change. Versions are bumped at
+# release.
+ant-protocol = { git = "https://github.com/WithAutonomi/ant-protocol", rev = "718f60682bb3704b68fbba0bea34f2a0416fa876" }
+
 [profile.release]
 lto = true
 codegen-units = 1

docs/adr/README.md

@@ -37,5 +37,6 @@ See [`TOOLING.md`](./TOOLING.md) for `adrs`, `adr-kit`, and AI harness setup.
 - [ADR-0015: Direct browser clients over WebRTC Direct](./ADR-0015-direct-browser-clients-over-webrtc-direct.md)
 - [ADR-0016: Pointers — paid mutable references with an immutable owner](./ADR-0016-pointers-immutable-owner.md)
 - [ADR-0017: Bounded fresh-replication offers and copy-free message sends](./ADR-0017-bounded-fresh-offers-and-copy-free-sends.md)
+- [ADR-0018: Pointer ownership transfer by final redirection](./ADR-0018-pointer-transfer-by-final-redirection.md)
 - [ADR-0019: Pointer audits serve the record round 1 bound](./ADR-0019-pointer-audits-serve-the-record-round-one-bound.md)
 - [ADR-0022: Remove the LMDB Chunk Store](./ADR-0022-remove-the-lmdb-chunk-store.md)

src/node.rs

@@ -270,11 +270,10 @@ impl NodeBuilder {
         };
 
         // ADR-0016: pointers replicate through the same engine. The PUT handler
-        // hands each newly stored paid state to it on this channel.
+        // hands each newly stored paid state to it, and asks it before taking
+        // a final state (ADR-0018).
         if let Some(service) = protocol.pointer_service() {
-            let (writes, fresh_writes) = tokio::sync::mpsc::unbounded_channel();
-            service.attach_fresh_writes(writes);
-            engine.with_pointers(service.store().clone(), fresh_writes);
+            engine.with_pointer_service(service);
         }
 
         // ADR-0004: wire the engine's commitment state as the quote generator's

src/pointer/mod.rs

@@ -3,10 +3,18 @@
 //! Implements `docs/adr/ADR-0016-pointers-immutable-owner.md`.
 //!
 //! A pointer is a mutable, owner-signed reference stored at an address derived
-//! from the owner's public key. Ownership is fixed at creation: there is no
-//! transfer, no lineage, no certificates and no key rotation. That choice is
-//! what lets the design be this small — the owner key is inlined in the
-//! record, so validating a pointer needs nothing but the pointer.
+//! from the owner's public key. The owner key is fixed at creation: there is no
+//! lineage, no certificates and no key rotation. That choice is what lets the
+//! design be this small — the owner key is inlined in the record, so
+//! validating a pointer needs nothing but the pointer.
+//!
+//! What the address resolves to can still be handed over for good
+//! (`docs/adr/ADR-0018-pointer-transfer-by-final-redirection.md`): a state at
+//! the final counter is replaced by nothing, so once a node holds one pointing
+//! at the new owner's pointer, the former owner cannot take it back there. The
+//! store gets that from the merge rule; the service adds one look at the close
+//! group before taking a final state, so a node that had not heard of the
+//! first refuses a second one when a peer proves the first in time.
 //!
 //! # What lives here
 //!
@@ -53,8 +61,8 @@ pub mod store;
 
 pub use ant_protocol::pointer::{
     pointer_address, state_id_for_body, ParsedPointer, Pointer, PointerError, PointerState,
-    PointerTarget, PointerTargetKind, DATA_TYPE_POINTER, POINTER_BODY_LEN, POINTER_FORMAT_VERSION,
-    POINTER_WIRE_LEN, TARGET_WIRE_LEN,
+    PointerTarget, PointerTargetKind, DATA_TYPE_POINTER, FINAL_COUNTER, POINTER_BODY_LEN,
+    POINTER_FORMAT_VERSION, POINTER_WIRE_LEN, TARGET_WIRE_LEN,
 };
-pub use service::PointerService;
+pub use service::{FinalStateWitness, FinalityCheck, PointerService};
 pub use store::{PointerStore, PutOutcome};