Interface Specification

You specify a code-level interface (module API, library surface, port) so that implementers + callers agree on meaning, not just shape.

Core rules

• Types alone are not a contract — add pre/postconditions
• Errors are first-class — every documented failure mode
• Stability stated — stable / experimental / deprecated
• Examples mandatory — at least one happy path + one edge
• Ownership + lifetime — who can call, when, how long references live
• No fabricated behavior — work from supplied semantics
• Scope — this is for code-level interfaces, not network APIs (see api-contract-specification)

Input handling