Ensure the API follows "Rust API Guidelines"

[ddrcode]

Status

• Ready to be implemented.
• If problems found it may introduce breaking changes. As such it's aimed for 0.3.0
• All new features planned for 0.3.0 must follow the guidelines; so - ideally - this ticket should be implemented first

Rationale

There are well defined Rust API Guidelines and Maiko, as a public library, must follow them with no exception.

Checklist

Here is a copy-paste of the checklist provided by the guidelines. Completion of this ticket requires that each item has been checked. Some items might be irrelevant to Maiko - if that's verified - mark them as checked.

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 ([C-CASE])
  • Ad-hoc conversions follow as_, to_, into_ conventions ([C-CONV])
  • Getter names follow Rust convention ([C-GETTER])
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter ([C-ITER])
  • Iterator type names match the methods that produce them ([C-ITER-TY])
  • Feature names are free of placeholder words ([C-FEATURE])
  • Names use a consistent word order ([C-WORD-ORDER])
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits ([C-COMMON-TRAITS])
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
  • Conversions use the standard traits From, AsRef, AsMut ([C-CONV-TRAITS])
  • Collections implement FromIterator and Extend ([C-COLLECT])
  • Data structures implement Serde's Serialize, Deserialize ([C-SERDE])
  • Types are Send and Sync where possible ([C-SEND-SYNC])
  • Error types are meaningful and well-behaved ([C-GOOD-ERR])
  • Binary number types provide Hex, Octal, Binary formatting ([C-NUM-FMT])
  • Generic reader/writer functions take R: Read and W: Write by value ([C-RW-VALUE])
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output ([C-EVOCATIVE])
  • Macros compose well with attributes ([C-MACRO-ATTR])
  • Item macros work anywhere that items are allowed ([C-ANYWHERE])
  • Item macros support visibility specifiers ([C-MACRO-VIS])
  • Type fragments are flexible ([C-MACRO-TY])
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples ([C-CRATE-DOC])
  • All items have a rustdoc example ([C-EXAMPLE])
  • Examples use ?, not try!, not unwrap ([C-QUESTION-MARK])
  • Function docs include error, panic, and safety considerations ([C-FAILURE])
  • Prose contains hyperlinks to relevant things ([C-LINK])
  • Cargo.toml includes all common metadata ([C-METADATA])
    • authors, description, license, homepage, documentation, repository,
      keywords, categories
  • Release notes document all significant changes ([C-RELNOTES])
  • Rustdoc does not show unhelpful implementation details ([C-HIDDEN])
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods ([C-SMART-PTR])
  • Conversions live on the most specific type involved ([C-CONV-SPECIFIC])
  • Functions with a clear receiver are methods ([C-METHOD])
  • Functions do not take out-parameters ([C-NO-OUT])
  • Operator overloads are unsurprising ([C-OVERLOAD])
  • Only smart pointers implement Deref and DerefMut ([C-DEREF])
  • Constructors are static, inherent methods ([C-CTOR])
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work ([C-INTERMEDIATE])
  • Caller decides where to copy and place data ([C-CALLER-CONTROL])
  • Functions minimize assumptions about parameters by using generics ([C-GENERIC])
  • Traits are object-safe if they may be useful as a trait object ([C-OBJECT])
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions ([C-NEWTYPE])
  • Arguments convey meaning through types, not bool or Option ([C-CUSTOM-TYPE])
  • Types for a set of flags are bitflags, not enums ([C-BITFLAG])
  • Builders enable construction of complex values ([C-BUILDER])
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments ([C-VALIDATE])
  • Destructors never fail ([C-DTOR-FAIL])
  • Destructors that may block have alternatives ([C-DTOR-BLOCK])
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug ([C-DEBUG])
  • Debug representation is never empty ([C-DEBUG-NONEMPTY])
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations ([C-SEALED])
  • Structs have private fields ([C-STRUCT-PRIVATE])
  • Newtypes encapsulate implementation details ([C-NEWTYPE-HIDE])
  • Data structures do not duplicate derived trait bounds ([C-STRUCT-BOUNDS])
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable ([C-STABLE])
  • Crate and its dependencies have a permissive license ([C-PERMISSIVE])

Acceptance criteria

• Check the code (all code, all features) against the list above
• If any inconsistency with the guidelines found, apply the following (No exceptions):
  • change the code to match the guidelines,
  • if the code can't be changed yet, add the required change to the todo list below
  • report inconsistencies/changes in the comments below for reference,
  • if relevant - update the changelog document,
• This ticket is a blocker for releasing 0.3.0

Required changes

This section contains already identified issues, that hasn't been implemented yet. Treat it as a TODO list. If more problems found, add them here if they cannot be implemented immediately.

• ActorId doesn't implement some of the required std traits (C-COMMON-TRAITS) )
• Meta doesn't implement some of the required std traits (C-COMMON-TRAITS) )
• Envelope and ActorId implement Deref that violates Only smart pointers implement Deref and DerefMut (C-DEREF)
• Change license to dual: MIT + Apache (C-PERMISSIVE)
• Make Config fields private and provide getters for them

Development work suggestions

This ticket may take multiple stages to implement. Keep all partial changes in sync with v0.3.0 branch (already created), so once the version released, all changes will be grouped there.

[ddrcode]

Findings by Severity

1. Breaking - Must Fix for 0.3.0

B1. Struct trait bounds (C-STRUCT-BOUNDS)

Every generic struct carries E: Event / T: Topic<E> bounds on the struct
definition. Per the guideline, bounds belong on impl blocks, not structs.
This prevents natural #[derive(Debug)] and forces manual trait impls.

Affected (all public): Envelope<E>, Context<E>, Supervisor<E,T>,
Subscribe<E,T>, ActorBuilder<E,T,A>, Harness<E,T>, EventQuery<E,T>,
EventEntry<E,T>, EventSpy<E,T>, ActorSpy<E,T>, TopicSpy<E,T>,
EventChain<E,T>, EventMatcher<E,T>, Expectation<E,T,F>

Action: Remove bounds from all struct definitions, move to impl blocks.

B2. Deref impls on non-smart-pointer types (C-DEREF)

• ActorId: Deref<Target=str> - makes ActorId silently coerce to &str
• Envelope<E>: Deref<Target=E> - makes envelope silently coerce to event

Action: Remove both Deref impls. Replace with explicit accessor methods:

• ActorId already has .name() -> &str - sufficient
• Envelope already has .event() -> &E - sufficient

B3. Config public fields (C-STRUCT-PRIVATE)

Config has 4 public fields (with TODOs to fix in 0.3.0):

• pub channel_size -> private, use broker_channel_capacity()
• pub max_events_per_tick -> private, use default_max_events_per_tick()
• pub maintenance_interval -> private, use maintenance_interval()
• pub monitoring_channel_size -> private, use monitoring_channel_capacity()

Deprecated builder methods (with_channel_size, etc.) should be removed.

Action: Make all fields private, remove deprecated methods.

B4. Error variant casing (C-CASE)

Error::IOError should be Error::IoError per Rust acronym conventions.

Action: Rename IOError -> IoError.

B5. EventEntry sender/receiver asymmetry

• sender() returns &str
• receiver() returns &ActorId

These are the same concept (actor identity) with different return types.

Action: Both should return &ActorId for consistency. Users can call
.name() when they need &str.

---

2. Additive - Should Fix for 0.3.0

A1. Missing common traits (C-COMMON-TRAITS, C-DEBUG)

Type	Missing	Action
Meta	PartialEq, Eq, Hash	Derive (compare by id)
DefaultTopic	Copy	Derive (zero-sized unit struct)
StepAction	Hash	Derive
Context<E>	Debug	Manual impl (print actor_id)
Subscribe<E,T>	Debug, Clone	Derive
EventEntry<E,T>	PartialEq	Manual impl (compare by id + receiver)
All testing types	Debug	Derive or manual impl (see below)

Testing types lacking Debug:
Harness, EventQuery, EventSpy, ActorSpy, TopicSpy,
EventChain, EventMatcher, Expectation, ActorTrace, EventTrace

Action: Add Debug to all. After B1 (removing struct bounds), most can use
#[derive(Debug)] directly.

A2. ActorId ergonomic constructors (C-CONV-TRAITS)

Currently: ActorId::new(Arc::from("name")) - awkward at every call site.

Action: Add From<&str>, From<String>, From<Arc<str>> for ActorId.
Keep new(Arc<str>) for zero-allocation sharing.

A3. Missing PartialEq on Error

Cannot use assert_eq! or matches! with error values in tests.

Action: Derive or manually implement PartialEq on Error.
Note: JoinError and io::Error don't implement PartialEq - may need
variant-level comparison (match on discriminant, not inner value).

A4. EventQuery missing IntoIterator (C-ITER)

Users cannot do for entry in test.events() { ... }.

Action: Implement IntoIterator for EventQuery (consuming, returns owned
entries). Keep iter() as pub(crate).

A5. EventSpy::sender() panics (C-FAILURE)

Hidden .expect() - should return Option<ActorId>.

Action: Change return type to Option<ActorId>. Document.

A6. EventChain: println in library code

pretty_print() calls println! directly - side effect in library code.

Action: Implement Display for EventChain (use to_string_tree() output).
Remove pretty_print() or make it call Display.

---

3. Project - Non-Code Changes

P1. License (C-PERMISSIVE)

Currently MIT only. Rust convention is dual MIT OR Apache-2.0.

Action: Add Apache-2.0 as alternative. Update both Cargo.toml files.

P2. Panic documentation (C-FAILURE)

• Meta::new() - panics if system clock before Unix epoch
• MonitorRegistry::add() - panics if dispatcher channel closed

Action: Add # Panics sections to rustdoc.

P3. maiko-macros Cargo.toml

Missing readme field.

Action: Add readme = "../README.md" or create a minimal one.

P4. Unnecessary Ord/PartialOrd

Config and ActorConfig derive Ord/PartialOrd - meaningless for config
types (what does "Config A > Config B" mean?).

OverflowPolicy derives Ord - variant declaration order defines ordering,
which is fragile.

Action: Remove Ord/PartialOrd from Config, ActorConfig, OverflowPolicy.

---

Non-Breaking (can ship in 0.2.x)

These items add new impls or documentation without changing existing API:

Item	What	Why non-breaking
A1	Add missing common traits	Adding trait impls is additive (manual impls needed while struct bounds exist)
A2	ActorId From impls	New conversion impls, no existing API touched
A3	Error PartialEq	New trait impl
A4	EventQuery IntoIterator	New trait impl
A6	EventChain Display	New trait impl (keep pretty_print until 0.3.0)
P1	Dual license (MIT OR Apache-2.0)	Strictly more permissive
P2	Panic documentation	Rustdoc only
P3	maiko-macros readme	Cargo.toml metadata only

Breaking (0.3.0 only)

Item	What	Why breaking
B1	Remove struct trait bounds	Changes type signatures
B2	Remove Deref impls	Code using *actor_id or *envelope breaks
B3	Config private fields	Direct field access breaks
B4	IOError -> IoError	Enum variant rename
B5	EventEntry sender return type	&str -> &ActorId
A5	EventSpy::sender() -> Option	Return type change
P4	Remove Ord/PartialOrd	Removing trait impls

Implementation Order

0.2.x (non-breaking, can ship now)

• A1 - Add missing common traits (manual impls)
• A2 - ActorId From impls
• A3 - Error PartialEq
• A4 - EventQuery IntoIterator
• A6 - EventChain Display
• P1 - Dual license
• P2 - Panic docs
• P3 - macros readme

0.3.0 (breaking changes)

Phase 1 (structural, enables everything else):

• B1 - Remove struct bounds (unblocks natural derives)
• A1 - Switch manual impls to derives (now possible)

Phase 2 (breaking API changes):

• B2 - Remove Deref impls
• B3 - Config private fields + remove deprecated methods
• B4 - IOError -> IoError
• B5 - EventEntry sender/receiver consistency
• A5 - EventSpy::sender() -> Option
• A6 - Remove pretty_print() (Display added in 0.2.x)
• P4 - Remove unnecessary Ord