hakorune/docs/guides/box-design-checklist.md

Box Design Checklist (docs-only)

Use this checklist when introducing a new Box or evolving an existing one.

Lifecycle

• Define birth parameters and side effects (allocation, registration).
• State machine: initial → running → closed → fini; reentrancy rules.
• fini() idempotent; post-fini methods: error vs no-op.

Ownership & Sharing

• Who owns the resource? Is there a LeaseBox form?
• Mutation boundaries (single-thread/Actor only?).
• Cross-thread usage: mailbox-only or direct allowed?

Concurrency

• Blocking APIs: provide try_* and *_timeout(ms).
• Cancellation: accept CancelToken/Deadline; ensure prompt unblock.
• Busy-wait forbidden; document waiting strategy (Phase‑0 cooperative / later OS).

Close Semantics

• What does close() mean? Which ops fail after close?
• Draining behavior and End marker shape.
• Double close and use-after-close handling.

Observability

• Events to emit (op, ok, extra fields) and Box ID.
• Env toggles (e.g., NYASH_*_TRACE=1).
• Expected order/causality in traces.

Capabilities & Affinity

• External authorities needed (fs/net/io/thread).
• Thread affinity constraints (creator thread / any / Actor only).

Performance

• Hot vs cold paths; offer ThinBox where needed.
• Complexity of operations; backpressure strategy.

Errors & Types

• Error shape (Bool/Option/Result) and consistency with ecosystem.
• Type expectations (runtime tags vs future static types).