From cddc205fe8baf6f91039e3d2a2971762825d27e4 Mon Sep 17 00:00:00 2001
From: "M.V. Hutz" <git@maximhutz.me>
Date: Sat, 2 May 2026 11:43:08 -0400
Subject: [PATCH] docs: insert, copy

---
 adr/001_interface_design.md | 39 +++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/adr/001_interface_design.md b/adr/001_interface_design.md
index 6568244..6aba8f2 100644
--- a/adr/001_interface_design.md
+++ b/adr/001_interface_design.md
@@ -356,3 +356,42 @@ To conform with the standard library, a new function should be added.
 Once again, the function is free because it is symmetric.
 
 </details>
+
+<details>
+<summary><code>maps.Insert(m, seq)</code></summary>
+
+This functionality requires a new receiver:
+
+```go
+func (t *Table[K, V]) Insert(seq *iter.Seq2[K, V]) error
+```
+
+A receiver fits better even though `maps.Insert` is a free function, because copying it is asymmetric.
+Map `dst` receives entries from map `src`.
+It is only free because Go's standard map is built into the language, and so cannot have receivers.
+
+In terms of naming, `t.Extend` is more accurate, and has precedent in [Python](docs.python.org/3/tutorial/datastructures.html#more-on-lists) and [Rust](https://doc.rust-lang.org/std/iter/trait.Extend.html).
+Ultimately, `t.Insert()` is a better choice because of
+
+</details>
+
+<details>
+<summary><code>maps.Copy(dst, src)</code></summary>
+
+To solve this, we must implement a new receiver:
+
+```go
+func (t *Table[K, V]) Copy(src *Table[K, V]) error
+```
+
+A receiver fits better even though `maps.Copy` is a free function, 'copying' it is asymmetric: `dst` is writen into by `src`.
+It is only free because Go's standard map is built into the language, and so cannot have receivers.
+
+The name `t.Merge()` might be more accurate, but it does work because:
+
+- `t.Copy()` matches Go's builtin `copy()`, and `io.Copy()`. The Go team used [the same logic](https://github.com/golang/go/discussions/47330#discussioncomment-1167799) to name `maps.Copy()`.
+  In this case, `t.Merge()` would be an outlier.
+- `t.Merge()` implies some sort of conflict-resolution, when there is not.
+  It simply overwrites the values.
+
+</details>