docs: add plans/ directory for design and implementation plans

[martin-belanger]

Add initial design plan (v10) under plans/

This adds the current design/implementation plan for the Python bindings + accessor refactor under plans/.

@dwsuse - You previously reviewed an earlier version (v6). This update reflects a few targeted refinements rather than a redesign:

---

Key changes from v6 → v10

1) SWIG Access model (main change)

• v6: all access via accessors
• v10: per-field access
  • generated → direct struct access (p->member)
  • custom → accessor function
  • none → no access

Rationale: generated accessors are trivial; custom accessors handle the real logic.

---

2) Removed !access:nested

• No longer needed
• Nested structs accessed directly (e.g. &fctx->cfg)

---

3) Generated setter semantics (updated)

• write=generated is allowed for all supported types
• Behavior is type-aware:
  • scalar → direct assignment
  • char * → free + strdup

Rationale: allows safe generation while keeping special cases in custom when needed.

---

4) Lifecycle annotation (new)

• Added struct-level lifecycle control:

  • !generate-lifecycle=generated
  • !generate-lifecycle=custom
  • (absence ⇒ no lifecycle)

• Generated lifecycle:

  • constructor: alloc + init + apply defaults
  • destructor: free owned members (e.g. char *) + struct

Rationale: makes ownership and allocation explicit and generator-driven.

---

5) Generator + typemap alignment

• Direct access for generated
• Accessors only for custom
• %immutable for write=none

---

6) Invariants clarified
A field is exposable if it has a usable access path:
read != none or write != none

---

Everything else (dict-based API, callbacks, lifetime model, generator structure, etc.) remains unchanged.

---

The goal of these changes is to simplify the bindings, reduce unnecessary indirection, and make the generator behavior more explicit and predictable.

---

Happy to adjust anything if you think this is going in the wrong direction.

[igaw]

Does it make sense to name the document “Implementation plan — libnvme Python bindings redesign”? I was under the impression this plan describes how to “write” the Python generator from scratch. Sure, the whole API is still moving around a bit, but we are slowly getting there, I think. From then on, it should just document the requirements and design decisions needed to be able to “re-write” the generator.

[martin-belanger]

Good point on the naming. The "Implementation plan" framing is intentional here, though: this document is specifically structured to be fed to an AI assistant (e.g. Claude) to carry out the work phase by phase. Each phase is a discrete session — the level of detail (invariants, truth tables, code snippets) is there to give the AI enough context to implement correctly without needing a human to re-explain things at every step.

I've added a short preface to the document making this explicit. Happy to also rename it to something like "Design & implementation plan" if that reads better, but I'd like to keep the phased structure since that's what drives the AI workflow.

[martin-belanger]

Closing. This is an AI-specific plan and as we just discussed does not belong in the main nvme-cli repo. A separate repo (e.g. nvme-cli-ai) would be a better place for this.