Skip to content

Commit e3e0cc4

Browse files
committed
test: verify owned snapshots and document isolation contract
1 parent 1dc4816 commit e3e0cc4

4 files changed

Lines changed: 125 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,17 @@ The host must discard/dismiss the preview on document close, target change or ot
7373
handle command failure without adding history, and revalidate its own permissions and locks.
7474
Applying preview values directly to the live model violates this library's contract.
7575

76+
Values and contexts must be stable snapshots. For example, a struct containing owned
77+
`String` and `Vec` fields can be cloned into an independent draft. Cloning an
78+
`Rc<RefCell<_>>` or `Arc<Mutex<_>>` instead shares mutable storage: changing it can
79+
also change the captured original or live document, defeating cancellation and freshness
80+
checks. Use owned values or immutable shared data, and ensure `PartialEq` compares every
81+
relevant field. `Clone` alone does not guarantee isolation.
82+
83+
The library clones the original once at construction and once for each `reset`.
84+
`propose` moves the accepted value; checks and `finish` do not clone it. Keep snapshots
85+
small, and let the application own images, rendering and background work.
86+
7687
## Validation
7788

7889
```sh

‎docs/VALIDATION.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
# Validation evidence
22

3+
## Snapshot contract review - 25 October 2026
4+
5+
On macOS arm64 with the minimum compiler, Rust 1.88.0:
6+
7+
- **16 lifecycle tests and 1 compile-fail doctest pass**.
8+
- Formatting, strict Clippy on all targets, and rustdoc with warnings denied pass.
9+
- A new owned multi-field form test checks independent drafts, invalid input retaining
10+
the previous proposal, and one complete before/after change.
11+
- A clone-count test checks that 999 proposals and freshness checks do not repeatedly
12+
clone snapshots. Only construction and Reset clone the original.
13+
14+
No lifecycle algorithm or API change was needed. Documentation now explicitly requires
15+
independent value snapshots, stable contexts and equality over all relevant fields.
16+
Shared mutable pointers cannot provide that isolation merely by implementing Clone.
17+
These tests do not claim an application benchmark or prevent host contract violations.
18+
No consumer dependency pins were changed.
19+
320
## PdfCraft consumer proposal — 25 October 2026
421

522
[PR #4594](https://github.com/storytold/pdfcraft/pull/4594), consumer commit `535d990d10832baf3b0a64910c51b280c224bd5c` on upstream

‎src/lib.rs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
//! only its local draft. Store small parameters here, not a full document per pointer event.
55
//! A context must include stable document/target identity and a revision that changes on
66
//! every relevant edit (including undo/redo). Comparing values alone cannot detect ABA edits.
7+
//! Values must be independent snapshots: `Clone` alone does not guarantee isolation if a
8+
//! value shares mutable storage with the host. Equality must cover all relevant fields.
79
#![no_std]
810
#![forbid(unsafe_code)]
911

@@ -33,7 +35,9 @@ impl core::error::Error for FinishError {}
3335
/// A proposed change. The caller must apply it through its existing command engine.
3436
#[derive(Debug, PartialEq, Eq)]
3537
pub struct Change<T> {
38+
/// The snapshot captured when the session began.
3639
pub before: T,
40+
/// The last accepted proposal, to be applied by the host.
3741
pub after: T,
3842
}
3943

@@ -53,6 +57,11 @@ pub struct EditSession<T, C> {
5357

5458
impl<T: Clone, C> EditSession<T, C> {
5559
/// Begin from a value already validated by the application.
60+
///
61+
/// Cloning `original` must produce an independently editable snapshot. Shared mutable
62+
/// pointers such as `Rc<RefCell<_>>` can let edits change the original or live document
63+
/// and defeat cancellation/conflict checks. Use owned fields or immutable shared data.
64+
/// The context must also remain a stable snapshot until the session ends.
5665
pub fn new(original: T, context: C) -> Self {
5766
Self {
5867
preview: original.clone(),

‎tests/lifecycle.rs‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,3 +178,91 @@ fn finish_errors_support_standard_error_reporting() {
178178
assert!(reported.source().is_none());
179179
}
180180
}
181+
182+
#[test]
183+
fn owned_form_fields_remain_isolated_until_one_change_is_finished() {
184+
#[derive(Clone, Debug, PartialEq, Eq)]
185+
struct Fields {
186+
title: String,
187+
tags: Vec<String>,
188+
inherited_size: Option<u16>,
189+
}
190+
let live = Fields {
191+
title: "original".into(),
192+
tags: vec!["keep".into()],
193+
inherited_size: None,
194+
};
195+
let mut draft = EditSession::new(live.clone(), 7);
196+
let mut proposal = draft.preview().clone();
197+
proposal.title.push_str(" edited");
198+
proposal.tags.push("new".into());
199+
proposal.inherited_size = Some(12);
200+
assert_eq!(draft.propose::<()>(Ok(proposal.clone())), Ok(()));
201+
assert_eq!(draft.original(), &live);
202+
assert_eq!(live.title, "original");
203+
assert_eq!(live.tags, ["keep"]);
204+
assert_eq!(live.inherited_size, None);
205+
assert!(draft.propose(Err("incomplete field")).is_err());
206+
assert_eq!(draft.preview(), &proposal);
207+
assert_eq!(draft.check(&live, &7), Err(FinishError::InvalidProposal));
208+
assert_eq!(draft.propose::<()>(Ok(proposal.clone())), Ok(()));
209+
assert_eq!(
210+
draft.finish(&live, &7),
211+
Ok(Some(Change {
212+
before: live,
213+
after: proposal,
214+
}))
215+
);
216+
}
217+
218+
#[test]
219+
fn proposing_and_checking_do_not_clone_snapshots_per_event() {
220+
use std::cell::Cell;
221+
struct Value<'a> {
222+
number: u16,
223+
clones: &'a Cell<usize>,
224+
}
225+
impl Clone for Value<'_> {
226+
fn clone(&self) -> Self {
227+
self.clones.set(self.clones.get() + 1);
228+
Self {
229+
number: self.number,
230+
clones: self.clones,
231+
}
232+
}
233+
}
234+
impl PartialEq for Value<'_> {
235+
fn eq(&self, other: &Self) -> bool {
236+
self.number == other.number
237+
}
238+
}
239+
let clones = Cell::new(0);
240+
let live = Value {
241+
number: 0,
242+
clones: &clones,
243+
};
244+
let mut draft = EditSession::new(
245+
Value {
246+
number: 0,
247+
clones: &clones,
248+
},
249+
7,
250+
);
251+
assert_eq!(clones.get(), 1);
252+
for number in 1..1000 {
253+
assert!(
254+
draft
255+
.propose::<()>(Ok(Value {
256+
number,
257+
clones: &clones
258+
}))
259+
.is_ok()
260+
);
261+
assert!(draft.check(&live, &7).is_ok());
262+
}
263+
assert_eq!(clones.get(), 1);
264+
draft.reset();
265+
assert_eq!(clones.get(), 2);
266+
assert!(matches!(draft.finish(&live, &7), Ok(None)));
267+
assert_eq!(clones.get(), 2);
268+
}

0 commit comments

Comments
 (0)