thalarch-apilisted

# Thalarch API An API is a compatibility contract, not merely a controller function. ## Contract first Identify: - caller(s) and trust boundary; - request/response or message schema; - success and error semantics; - authentication vs authorization; - idempotency/retry behavior; - pagination/order/filter semantics; - timeouts/cancellation; - compatibility/versioning requirements; - observability expectations. Reuse the repository's existing API conventions before introducing a new envelope, error format, version strategy, or serialization stack. ## Input and schema Validate untrusted input at the boundary. Distinguish malformed input, invalid domain state, authentication failure, authorization failure, conflict, missing resource, rate limiting, and server failure according to the protocol/framework in use. Do not expose internal exception text, stack traces, secrets, or database details as public error contracts. ## Idempotency and retries For operations that may be retried, define whether repeating the request is safe and how duplicate side effects are prevented. Do not add automatic retries to non-idempotent operations without a safe key/transaction/deduplication model. Retries require bounded attempts, backoff/jitter where appropriate, cancellation, and a clear list of retryable failures. ## Pagination and ordering For paginated data: - define a stable ordering; - avoid offset pagination when data churn/scale makes it incorrect or expensive; - treat cursor con