Document that produce() drafts must stay a tree, not a graph

[berendkleinhaneveld]

Neither docs/guide/gotchas.md nor docs/guide/produce.md mentioned what happens when the same object is reachable from two locations in a draft. Verified against actual behavior and documented two distinct failure modes:

• The default (copy) mode silently de-aliases pre-existing shared references in the base object -- even with a no-op recipe, result[a] and result[b] stop being the same object.
• in_place=True preserves identity, but the recorded patches still only capture what each proxy independently observes, so replaying patches against a non-aliased copy (e.g. after a JSON round-trip) silently drops writes made through the other alias.

Also notes that reference cycles aren't detected and lead to unbounded recursion rather than a clean error.

Both code examples in the new section are executed against the library and their assertions verified to pass.

[berendkleinhaneveld]

I figured that this requirement would be good to mention in the docs somewhere.

[Korijn]

Does this limitation also apply to diff?

[berendkleinhaneveld]

I don't think so, since with diff you capture a moment in time. Here, the nuance is that produce records the patches while the changes are applied.