pkgutil: formalize and enforce state invariants

[sighook]

Issue: Implicit invariants not encoded in API

Problem

Core invariants exist but are implicit:

• db_open() must precede most operations
• db_commit() required for persistence
• packages must reflect filesystem reality

These are not enforced -> misuse is easy.

Proposal

Add explicit state machine:

enum class state {
  uninitialized,
  opened,
  dirty
};

Enforce:

• db_open() -> state = opened
• mutating ops -> state = dirty
• db_commit() -> state = opened

All methods assert valid state transitions.

Optional

• debug mode: invariant verification pass
  • scan filesystem vs DB

Acceptance criteria

• invalid call sequences throw
• lifecycle clearly documented
• invariant violations detectable

[sighook]

Example 1 - State machine enforcement

Commit 1 - introduce state enum

pkgutil.h

+enum class pkgutil_state {
+    uninitialized,
+    opened,
+    dirty
+};

 private:
+    pkgutil_state state_;

---

Commit 2 - initialize + enforce

 pkgutil::pkgutil(...)
-    : root(name), has_lock_(false)
+    : root(name), has_lock_(false), state_(pkgutil_state::uninitialized)
 {}

 void pkgutil::db_open(...) {
+    if (state_ != pkgutil_state::uninitialized)
+        throw pkgcore_error("db_open: invalid state");
     ...
+    state_ = pkgutil_state::opened;
 }

 void pkgutil::db_add_pkg(...) {
+    if (state_ != pkgutil_state::opened)
+        throw pkgcore_error("db_add_pkg: db not opened");
+    state_ = pkgutil_state::dirty;

 void pkgutil::db_commit() {
+    if (state_ != pkgutil_state::dirty)
+        throw pkgcore_error("db_commit: nothing to commit");
     ...
+    state_ = pkgutil_state::opened;
 }