OCaml implementation

Source of truth

• `.mli` files are the specification and outrank tests.
• If an interface and a test disagree, fix the test.
• Changing an interface is a deliberate design decision — raise it, don't drift into it.

Style

• Modern, idiomatic OCaml. Favour the principle of least surprise: a reader should not need to learn a local idiom to follow the code.
• Prefer readable, shallow code. A flat sequence a reader can follow top to bottom beats a deeply nested tower of `match` arms.
• Reach for `let*` when it flattens nested cases — chained `result` or `result Lwt.t` plumbing where each step short-circuits on error. Used this way, a bind improves flow and cuts indentation. - A single `match` is clearer than a monad; don't reach for one reflexively. - Two or three cascading `match ... with Error _ -> ... | Ok x -> ...` steps are the signal to switch to `let*`.
• Abstract types with smart constructors for anything carrying an invariant.
• Use `result` for expected, recoverable failure. - This includes converting untrusted external data and domain feedback a caller can present or recover from. - Each module defines its own errors; no shared catch-all error type or `string` errors.
• Raise a module-specific exception for a violated authored-plan precondition after validation. - Do not use exceptions for normal domain outcomes or recorded deviations.
• Prefer closed variants — they keep `match` exhaustiveness working for you.
• Total functions where practical; make partiality visible in the type.

Layering

Three libraries, dependencies pointing inward only:

• `hito.core` — pure domain. No framework, database, or serialization dependencies. Ever.
• `hito.app` — `Repository` port, `Service`, adapters. Knows nothing of Dream.
• `hito.web` — Dream application. The only place Dream and dream-html appear.

Rules:

• Ports are module types; adapters implement them.
• Persistence identity is assigned in `hito.app`, not in the core.