The plan for the pointer arm cimport already promised

docs/handoffs/HANDOFF-cimport-ptr.md

@@ -0,0 +1,47 @@
+# Handoff — the pointer arm `agrees` already promised
+
+`lib/cimport.ml`'s `agrees` decides whether a hand-written `declare-c` and the C header
+say the same thing. Its comment has always listed three differences that are "expected and
+are not reported"; the code implements two of them. The missing one — *a `(Ptr T)` where
+the header says `T *`* — is what `../PORTING.md` §A.1 and §A.2 ran into, and it is why
+`GetCodepointPrevious` cannot be bound honestly and why `UpdateTexture` has to be handed
+`(addr (.r (at (slice-from-ptr pixels n) 0)))`.
+
+This file is the running record of building that arm.
+
+## The plan
+
+1. A `ptr_agrees` beside `agrees`, consulted only at the two `declare-c` sites in
+   `diff_bound`, where the C spelling is still in hand. `agrees` itself is left alone:
+   `check_structs` uses it for field *widths*, and loosening it there is the hazard the
+   check exists to catch.
+2. Breadth, decided rather than fallen into — see "What it accepts" below.
+3. Rewrite the comment at `lib/cimport.ml:1291` so it describes the code instead of
+   promising it, and take the rotting binding count out of it.
+4. Use it: `get-codepoint-previous-raw` in `vendor/raylib/raylib.flan`, and the
+   `(Ptr Color)` binding for `UpdateTexture`. Delete both workarounds.
+5. `docs/PORTING.md` §A.1 and §A.2 annotated closed in the file's existing style.
+
+## What it accepts (to be confirmed as it is built)
+
+- `(Ptr T)` against a C `T *` for the same `T`.
+- `(Ptr u8)` against `char *` — a byte is a byte, and the two spellings of one are not a
+  width disagreement. Scoped to the pointee, never to `agrees` at large.
+- `(Ptr T)` for any `T` against `void *`. `value_ty` already *invents* `(Ptr u8)` for a
+  `void *`, so the check as it stands enforces cimport's own guess as if the header had
+  said it.
+- `const` does not enter into it, because a non-const `char *` parameter makes `param_ty`
+  refuse and `diff_bound` skips a parameter it cannot render at all.
+
+## What it still refuses
+
+- `(Ptr A)` against `B *` for different named `A` and `B`.
+- Anything that is not a pointer on the Flan side against a C pointer, and the reverse.
+
+## Status
+
+- [ ] the arm
+- [ ] the comment
+- [ ] tests, positive and negative
+- [ ] the two raylib bindings
+- [ ] PORTING.md