Bring doc comments in line with the current code

The dumb-storage and saga/commit refactoring left doc comments across the
workspace describing removed or renamed behavior. Correct them so every
/// and //! matches what the code does today.

Main corrections: replace the stale posting lifecycle names
(PendingInactive/Inactive) with the real PostingState terms
(Reserved/Spent); drop the removed NoOverdraft policy label in favor of the
single DEBIT_MUST_NOT_EXCEED_CREDIT flag; retire the defunct three-phase
load/plan/apply commit narrative in favor of the two-step reserve/finalize
saga; fix the validate module claim about enforcing ownership (never
constructed); and refresh stale storage-sql and dashboard examples.

crates/kuatia-core/src/validate.rs

@@ -1,8 +1,8 @@
 //! Pure, sync validation — the auditable heart of the ledger.
 //!
 //! [`validate_and_plan`] enforces every invariant (conservation, double-spend,
-//! ownership, overdraft) and produces a [`Plan`] describing the effects to
-//! apply. It takes no IO, no clock, and no randomness, so it is deterministic
+//! account state, overdraft, book policy) and produces a [`Plan`] describing the
+//! effects to apply. It takes no IO, no clock, and no randomness, so it is deterministic
 //! and testable with golden vectors. The caller provides pre-loaded state via
 //! [`PlanInput`]; this module never touches storage.
 
@@ -39,7 +39,7 @@ pub struct PlanInput<'a> {
 pub struct Plan {
     /// Content-addressed id of the validated transfer.
     pub transfer_id: EnvelopeId,
-    /// Postings to mark as inactive (consumed).
+    /// Postings the consumer must spend (mark `Spent`).
     pub postings_to_deactivate: Vec<PostingId>,
     /// New postings to persist.
     pub postings_to_create: Vec<Posting>,

crates/kuatia-dashboard/src/ui.rs

@@ -111,14 +111,14 @@ struct BalanceView {
 
 #[derive(Serialize)]
 struct AccountView {
-    /// Base account id (used only for the route; the display uses `display_id`).
+    /// Raw numeric base id. The display uses `display_id`; routes use `link`.
     id: i64,
     sub: i64,
-    /// `"5"` for a main account, `"5.7"` for subaccount 7 of base 5.
+    /// The account's IBAN-style code, grouped for display (five blocks of four).
     display_id: String,
-    /// Full-page detail link (`/accounts/5` or `/accounts/5/7`).
+    /// Full-page detail link, keyed by the machine-format code (`/accounts/<code>`).
     link: String,
-    /// htmx partial link (`/ui/accounts/5` or `/ui/accounts/5/7`).
+    /// htmx partial link (`/ui/accounts/<code>`).
     ui_link: String,
     name: String,
     version: u64,
@@ -156,7 +156,7 @@ struct TransferView {
 struct EventView {
     seq: u64,
     kind: &'static str,
-    /// Account display id (`"5"` or `"5.7"`), if the event names an account.
+    /// Account's grouped IBAN-style code, if the event names an account.
     account: Option<String>,
     transfer_short: Option<String>,
     time: String,

crates/kuatia-storage-sql/src/lib.rs

@@ -4,7 +4,7 @@
 //! `sqlite` or `postgres` to select the backend.
 //!
 //! ```text
-//! let pool = sqlx::any::Pool<Any>Options::new()
+//! let pool = sqlx::any::AnyPoolOptions::new()
 //!     .connect("sqlite::memory:").await?;
 //! let store = SqlStore::new(pool);
 //! store.migrate().await?;

crates/kuatia-storage/src/store_tests.rs

@@ -767,7 +767,7 @@ pub async fn spent_posting_remains_in_immutable_table(store: &(impl Store + 'sta
 }
 
 /// The `Live` filter returns active and reserved postings but excludes spent
-/// ones (the replacement for the old "not Inactive" balance-bearing set).
+/// ones (the balance-bearing set of active plus reserved postings).
 pub async fn get_postings_by_account_live_filter(store: &(impl Store + 'static)) {
     let active = make_posting([0xB2; 32], 0, 1, 1, 100);
     let reserved = make_posting([0xB2; 32], 1, 1, 1, 200);
@@ -893,8 +893,8 @@ pub async fn reserve_twice_second_zero(store: &(impl Store + 'static)) {
     );
 }
 
-/// A posting cannot be deactivated twice: once Inactive, a second raw deactivate
-/// reports zero — the double-spend guard at the storage layer.
+/// A posting cannot be deactivated twice: once spent, a second raw deactivate
+/// reports zero, the double-spend guard at the storage layer.
 pub async fn deactivate_twice_second_zero(store: &(impl Store + 'static)) {
     let consumed = make_posting([7; 32], 0, 1, 1, 100);
     seed_active(store, 200, std::slice::from_ref(&consumed)).await;

crates/kuatia-types/src/lib.rs

@@ -35,7 +35,7 @@ pub use canonical::{
 /// An account is a base `id` plus a `subaccount`. `sub = 0` is the main account
 /// (the default when subaccounts are not used); a non-zero `sub` is a
 /// subaccount of the same base id. Each `(id, sub)` is a full account record
-/// with its own policy and lifecycle. See ADR-0012 and ADR-0015.
+/// with its own flags and lifecycle. See ADR-0012 and ADR-0015.
 ///
 /// Both legs are stored as `i64` (they hash and persist as full `i64`), but the
 /// IBAN-style string form ([`Display`](fmt::Display) / [`FromStr`](std::str::FromStr))
@@ -356,7 +356,7 @@ pub enum PostingFilter {
     Active,
     /// Reserved (in-flight) postings only.
     Reserved,
-    /// Active or reserved — the balance-bearing set (the old "not Inactive").
+    /// Active or reserved: the balance-bearing set (everything not yet Spent).
     Live,
     /// Every posting ever created, including spent ones.
     All,
@@ -391,7 +391,8 @@ pub enum PostingState {
 ///
 /// A positive posting is value controlled by the account; a negative posting is
 /// an offset position (issuance, external flow, overdraft, or system balancing).
-/// Negative postings are allowed on every policy except `NoOverdraft`.
+/// Negative postings are allowed on any account except one that forbids
+/// overdraft (carries [`AccountFlags::DEBIT_MUST_NOT_EXCEED_CREDIT`]).
 ///
 /// A `Posting` is an immutable record: once created it is never updated. Its
 /// lifecycle state is not a field here; it is derived from index-table

crates/kuatia/src/inflight.rs

@@ -2,9 +2,9 @@
 //! later.
 //!
 //! An inflight transaction is an ordinary trade whose every destination is
-//! rewritten to a per-destination holding subaccount (`NoOverdraft`, flagged
-//! [`AccountFlags::INFLIGHT`], keyed by a subaccount derived from the trade).
-//! Committing that rewritten transfer parks the
+//! rewritten to a per-destination holding subaccount (flagged
+//! [`AccountFlags::INFLIGHT`] and forbidding overdraft, keyed by a subaccount
+//! derived from the trade). Committing that rewritten transfer parks the
 //! funds. Confirm and void are ordinary commits that move a hold's balance to
 //! its destination or back to its funder. Nothing new is stored: the authorize
 //! transfer's metadata carries the leg table, and every artifact is tagged with
@@ -294,8 +294,8 @@ impl Ledger {
     ///
     /// Each movement delivers `amount` of `asset` from the matching leg's hold to
     /// its destination. `amount` must not exceed the amount still held; the
-    /// `NoOverdraft` hold makes over-confirmation impossible regardless. A hold is
-    /// closed once fully drained.
+    /// overdraft-forbidding hold makes over-confirmation impossible regardless. A
+    /// hold is closed once fully drained.
     ///
     /// Movements settle in order, each its own commit, so the batch is not atomic:
     /// a later movement failing leaves earlier confirmations applied.

crates/kuatia/src/ledger/commit.rs

@@ -90,10 +90,10 @@ struct LoadedState {
 
 impl Ledger {
     // -----------------------------------------------------------------------
-    // Three-piece API: load -> plan -> apply
+    // Validation phases: load (read state) -> plan (pure validate)
     // -----------------------------------------------------------------------
 
-    /// Phase 1: load all state needed for validation.
+    /// Load all state needed for validation.
     #[instrument(skip(self, envelope), name = "ledger.load")]
     async fn load(&self, envelope: &Envelope) -> Result<LoadedState, LedgerError> {
         let consumed_postings = if envelope.consumes().is_empty() {
@@ -146,7 +146,7 @@ impl Ledger {
         })
     }
 
-    /// Phase 2: run pure validation and produce a plan.
+    /// Run pure validation over the loaded state and produce a plan.
     fn plan(
         &self,
         envelope: &Envelope,

crates/kuatia/src/lib.rs

@@ -1,8 +1,8 @@
 //! Kuatia — async ledger resource built on top of [`kuatia_core`].
 //!
 //! This crate adds IO to the pure decision logic: the [`Store`](kuatia_storage::store::Store) trait
-//! abstracts storage, and the [`Ledger`](crate::ledger::Ledger) struct composes the three-phase
-//! commit pipeline (load → plan → apply) behind a convenient async API.
+//! abstracts storage, and the [`Ledger`](crate::ledger::Ledger) struct drives the two-step
+//! commit saga (reserve then finalize, validation inside finalize) behind an async API.
 
 pub mod error;
 pub mod inflight;