flan/docs/handoffs/HANDOFF-cimport-ptr.md

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