[P3][kernel] Design typed error contract for public API failures #28

Summary

All failures surface as bare Error with libredb: prefix strings. Callers must match message text — fragile for a public API surface about to lock.

Audit ID: Section 4 Low — Wave 3 roadmap

Proposal

Design a small typed error taxonomy before API is public-locked:

export class LibreDbError extends Error {
  readonly code: "CLOSED" | "NESTED_TX" | "CORRUPT_WAL" | ...;
}

Or discriminated union on cause — research SQLite/libSQL patterns.

Deliverable

1. Design note: codes list, stability promise, migration from string matching.
2. Implement incrementally starting with kernel errors.

Acceptance criteria

• Design agreed in issue or short doc PR.
• At least kernel hot paths use stable code.
• Changeset required when exported.

Non-goals

• Full i18n; English messages remain.

Related

• EBADF-on-close issue (subset of codes).