brawny 0.1.13__py3-none-any.whl → 0.1.22__py3-none-any.whl

brawny/db/migrate.py

@@ -1,7 +1,4 @@
-"""Database migration management for brawny.
-
-Handles schema migrations for both PostgreSQL and SQLite.
-"""
+"""Database migration management for brawny (SQLite-only)."""
 
 from __future__ import annotations
 
@@ -12,12 +9,14 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from brawny.model.errors import DatabaseError
+from brawny.logging import get_logger
 
 if TYPE_CHECKING:
     from brawny.db.base import Database
 
 
 MIGRATIONS_DIR = Path(__file__).parent / "migrations"
+logger = get_logger(__name__)
 
 
 @dataclass
@@ -85,7 +84,6 @@ def get_applied_migrations(db: Database) -> set[str]:
         Set of version strings that have been applied
     """
     try:
-        # Check if migrations table exists
         result = db.execute_returning(
             """
             SELECT version, applied_at
@@ -94,9 +92,21 @@ def get_applied_migrations(db: Database) -> set[str]:
             """
         )
         return {row["version"] for row in result}
-    except Exception:
-        # Table doesn't exist yet
-        return set()
+    except Exception as e:
+        db_info = _db_context(db)
+        if _is_missing_schema_migrations(e):
+            logger.warning(
+                "migrations.schema_missing",
+                db=db_info,
+                error=str(e)[:200],
+            )
+            return set()
+        logger.warning(
+            "migrations.schema_read_failed",
+            db=db_info,
+            error=str(e)[:200],
+        )
+        raise DatabaseError("Failed to read schema_migrations table") from e
 
 
 def get_pending_migrations(db: Database) -> list[Migration]:
@@ -134,8 +144,21 @@ def get_migration_status(db: Database) -> list[Migration]:
         )
         for row in result:
             applied[row["version"]] = row["applied_at"]
-    except Exception:
-        pass
+    except Exception as e:
+        db_info = _db_context(db)
+        if _is_missing_schema_migrations(e):
+            logger.warning(
+                "migrations.schema_missing",
+                db=db_info,
+                error=str(e)[:200],
+            )
+        else:
+            logger.warning(
+                "migrations.schema_read_failed",
+                db=db_info,
+                error=str(e)[:200],
+            )
+            raise DatabaseError("Failed to read schema_migrations table") from e
 
     all_migrations = discover_migrations()
     for migration in all_migrations:
@@ -156,7 +179,7 @@ def run_migration(db: Database, migration: Migration) -> None:
         DatabaseError: If migration fails
     """
     try:
-        if db.dialect == "sqlite" and migration.version == "012":
+        if migration.version == "012":
             with db.transaction():
                 existing = {
                     r["name"].lower()
@@ -180,6 +203,30 @@ def run_migration(db: Database, migration: Migration) -> None:
                     (migration.version,),
                 )
             return
+        if migration.version == "014":
+            with db.transaction():
+                existing = {
+                    r["name"].lower()
+                    for r in db.execute_returning("PRAGMA table_info(tx_intents)")
+                }
+                if "lease_expires_at" in existing:
+                    db.execute(
+                        "INSERT OR IGNORE INTO schema_migrations (version) VALUES (?)",
+                        (migration.version,),
+                    )
+                    return
+                try:
+                    db.execute(
+                        "ALTER TABLE tx_intents ADD COLUMN lease_expires_at TIMESTAMP"
+                    )
+                except Exception as exc:
+                    if "duplicate column name" not in str(exc).lower():
+                        raise
+                db.execute(
+                    "INSERT OR IGNORE INTO schema_migrations (version) VALUES (?)",
+                    (migration.version,),
+                )
+            return
 
         with db.transaction():
             # Split SQL into individual statements for SQLite compatibility
@@ -263,6 +310,19 @@ def _split_sql_statements(sql: str) -> list[str]:
     return statements
 
 
+def _is_missing_schema_migrations(error: Exception) -> bool:
+    message = str(error).lower()
+    return "no such table" in message and "schema_migrations" in message
+
+
+def _db_context(db: Database) -> dict[str, str]:
+    info: dict[str, str] = {"dialect": getattr(db, "dialect", "unknown")}
+    db_path = getattr(db, "_database_path", None)
+    if isinstance(db_path, str):
+        info["path"] = db_path
+    return info
+
+
 def run_pending_migrations(db: Database) -> list[Migration]:
     """Run all pending migrations.
 
@@ -281,32 +341,119 @@ def run_pending_migrations(db: Database) -> list[Migration]:
         run_migration(db, migration)
         migration.applied_at = datetime.utcnow()
 
-    verify_critical_schema(db)
-
     return pending
 
 
 def verify_critical_schema(db: Database) -> None:
     """Hard-fail if critical columns missing. Runs for daemon + CLI."""
-    # If earlier schemas lacked any of these, reduce to the minimum needed for safe operation.
-    required = {"intent_id", "status", "claim_token", "claimed_at", "claimed_by"}
-
-    if db.dialect == "sqlite":
-        rows = db.execute_returning("PRAGMA table_info(tx_intents)")
+    # Keep the list short and hot-path only.
+    required_by_table: dict[str, set[str]] = {
+        "tx_intents": {
+            "intent_id",
+            "status",
+            "claim_token",
+            "claimed_at",
+            "claimed_by",
+            "lease_expires_at",
+        },
+        "tx_attempts": {
+            "attempt_id",
+            "intent_id",
+            "status",
+            "created_at",
+        },
+        "nonce_reservations": {
+            "id",
+            "chain_id",
+            "signer_address",
+            "nonce",
+            "status",
+            "intent_id",
+            "created_at",
+            "updated_at",
+        },
+    }
+
+    missing_by_table: dict[str, set[str]] = {}
+    for table_name, required in required_by_table.items():
+        rows = db.execute_returning(f"PRAGMA table_info({table_name})")
         existing = {r["name"].lower() for r in rows}
-    else:
+        missing = {col for col in required if col.lower() not in existing}
+        if missing:
+            missing_by_table[table_name] = missing
+
+    if not missing_by_table:
+        return
+
+    expected_version = _latest_migration_version()
+    current_version, current_version_note = _read_schema_version(db)
+    remediation = _schema_remediation(expected_version, current_version, current_version_note)
+
+    missing_details = "; ".join(
+        f"{table}: {', '.join(sorted(cols))}"
+        for table, cols in sorted(missing_by_table.items())
+    )
+    message_parts = [
+        f"Missing critical columns: {missing_details}.",
+    ]
+    if expected_version:
+        message_parts.append(f"Expected schema version: {expected_version}.")
+    if current_version:
+        message_parts.append(f"Current schema version: {current_version}.")
+    elif current_version_note:
+        message_parts.append(f"Current schema version: unknown ({current_version_note}).")
+    message_parts.append(f"Remediation: {remediation}.")
+    raise RuntimeError(" ".join(message_parts))
+
+
+def _latest_migration_version() -> str | None:
+    migrations = discover_migrations()
+    if not migrations:
+        return None
+    return max(migrations, key=lambda m: int(m.version)).version
+
+
+def _read_schema_version(db: Database) -> tuple[str | None, str | None]:
+    try:
         rows = db.execute_returning(
-            "SELECT column_name FROM information_schema.columns "
-            "WHERE table_schema = current_schema() AND table_name = 'tx_intents'"
+            "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1"
         )
-        existing = {r["column_name"].lower() for r in rows}
-
-    missing = required - existing
-    if missing:
-        raise RuntimeError(
-            f"FATAL: tx_intents missing columns {missing}. "
-            f"Migration 012 may have failed. Check DB manually."
+    except Exception as exc:
+        if _is_missing_schema_migrations(exc):
+            return None, "schema_migrations missing"
+        logger.warning(
+            "migrations.schema_read_failed",
+            db=_db_context(db),
+            error=str(exc)[:200],
         )
+        return None, "schema_migrations unreadable"
+
+    if not rows:
+        return None, "schema_migrations empty"
+    return str(rows[0]["version"]), None
+
+
+def _schema_remediation(
+    expected_version: str | None,
+    current_version: str | None,
+    current_version_note: str | None,
+) -> str:
+    if current_version_note is not None:
+        return "DB appears out-of-band; delete/re-init or run a repair script if available"
+    if expected_version and current_version:
+        expected_int = _parse_version_int(expected_version)
+        current_int = _parse_version_int(current_version)
+        if expected_int is not None and current_int is not None:
+            if current_int < expected_int:
+                return "run `brawny db migrate`"
+    return "DB appears out-of-band; delete/re-init or run a repair script if available"
+
+
+def _parse_version_int(version: str) -> int | None:
+    try:
+        return int(version)
+    except ValueError:
+        return None
 
 
 class Migrator:

brawny/db/migrations/001_init.sql

@@ -25,7 +25,7 @@ CREATE TABLE IF NOT EXISTS block_state (
 -- 2. Block Hash History - for reorg detection
 -- ============================================================================
 CREATE TABLE IF NOT EXISTS block_hash_history (
-    id SERIAL PRIMARY KEY,
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
     chain_id INTEGER NOT NULL,
     block_number BIGINT NOT NULL,
     block_hash VARCHAR(66) NOT NULL,
@@ -81,7 +81,7 @@ CREATE TABLE IF NOT EXISTS signers (
 -- 6. Nonce Reservations - tracks nonce allocation and status
 -- ============================================================================
 CREATE TABLE IF NOT EXISTS nonce_reservations (
-    id SERIAL PRIMARY KEY,
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
     chain_id INTEGER NOT NULL,
     signer_address VARCHAR(42) NOT NULL,
     nonce BIGINT NOT NULL,
@@ -118,6 +118,7 @@ CREATE TABLE IF NOT EXISTS tx_intents (
     claim_token VARCHAR(100),
     claimed_at TIMESTAMP,
     claimed_by VARCHAR(200),
+    lease_expires_at TIMESTAMP,
     created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
     updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
@@ -141,7 +142,7 @@ CREATE TABLE IF NOT EXISTS tx_attempts (
     tx_hash VARCHAR(66),
     gas_params_json TEXT NOT NULL,
     status VARCHAR(20) NOT NULL DEFAULT 'signed' CHECK (
-        status IN ('signed', 'broadcast', 'pending', 'confirmed', 'failed', 'replaced')
+        status IN ('signed', 'pending_send', 'broadcast', 'pending', 'confirmed', 'failed', 'replaced')
     ),
     error_code VARCHAR(100),
     error_detail TEXT,

brawny/db/migrations/010_add_nonce_gap_index.sql

@@ -1,7 +1,7 @@
 -- Add composite index for efficient nonce gap age queries
 -- Makes the MIN(created_at) scan an index walk instead of heap scan
 -- Version: 010
--- Note: CONCURRENTLY removed for SQLite compatibility (PostgreSQL-only syntax)
+-- Note: CONCURRENTLY removed for SQLite compatibility
 
 CREATE INDEX IF NOT EXISTS idx_nonce_res_chain_signer_status_nonce_created
 ON nonce_reservations (chain_id, signer_address, status, nonce, created_at);

brawny/db/migrations/011_add_job_logs.sql

@@ -1,9 +1,8 @@
 -- Job logs for operator-visible snapshots during check()
 -- Version: 011
--- Note: SERIAL becomes INTEGER on SQLite (handled by sqlite.py adapter)
 
 CREATE TABLE IF NOT EXISTS job_logs (
-    id SERIAL PRIMARY KEY,
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
     chain_id INTEGER NOT NULL,
     job_id VARCHAR(200) NOT NULL,
     block_number BIGINT,

brawny/db/migrations/012_add_claimed_by.sql

@@ -1,5 +1,5 @@
--- Postgres only (SQLite handled in migrator)
-ALTER TABLE tx_intents ADD COLUMN IF NOT EXISTS claimed_by VARCHAR(200);
+-- SQLite handled in migrator (idempotent)
+ALTER TABLE tx_intents ADD COLUMN claimed_by VARCHAR(200);
 
 INSERT INTO schema_migrations (version) VALUES ('012')
 ON CONFLICT (version) DO NOTHING;

brawny/db/migrations/013_attempt_unique.sql

@@ -0,0 +1,10 @@
+-- Add binding identifier for attempts and enforce uniqueness per binding
+
+ALTER TABLE tx_intents ADD COLUMN broadcast_binding_id UUID;
+ALTER TABLE tx_attempts ADD COLUMN endpoint_binding_id UUID;
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_tx_attempts_intent_nonce_binding_hash
+    ON tx_attempts(intent_id, nonce, endpoint_binding_id, tx_hash)
+    WHERE tx_hash IS NOT NULL AND endpoint_binding_id IS NOT NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('013');

brawny/db/migrations/014_add_lease_expires_at.sql

@@ -0,0 +1,5 @@
+-- Add lease_expires_at for intent claim leases
+ALTER TABLE tx_intents ADD COLUMN lease_expires_at TIMESTAMP;
+
+INSERT INTO schema_migrations (version) VALUES ('014')
+ON CONFLICT (version) DO NOTHING;

brawny/db/migrations/015_add_signer_alias.sql

@@ -0,0 +1,14 @@
+-- Add signer_alias columns for intent/transaction auditing
+-- Note: SQLite does not support "IF NOT EXISTS" for ALTER TABLE ADD COLUMN
+
+ALTER TABLE tx_intents ADD COLUMN signer_alias VARCHAR(200);
+
+-- Normalize existing address data to lowercase canonical form.
+UPDATE signers SET signer_address = lower(signer_address);
+UPDATE nonce_reservations SET signer_address = lower(signer_address);
+UPDATE tx_intents SET signer_address = lower(signer_address), to_address = lower(to_address);
+UPDATE abi_cache SET address = lower(address);
+UPDATE proxy_cache SET proxy_address = lower(proxy_address),
+    implementation_address = lower(implementation_address);
+
+INSERT INTO schema_migrations (version) VALUES ('015');

brawny/db/migrations/016_runtime_controls_and_quarantine.sql

@@ -0,0 +1,32 @@
+-- Description: Add signer quarantine, runtime controls, and mutation audit
+
+-- Signer containment
+ALTER TABLE signers ADD COLUMN quarantined_at TIMESTAMP;
+ALTER TABLE signers ADD COLUMN quarantine_reason TEXT;
+ALTER TABLE signers ADD COLUMN replacements_paused INTEGER NOT NULL DEFAULT 0;
+
+-- Runtime controls (containment with TTL)
+CREATE TABLE IF NOT EXISTS runtime_controls (
+    control VARCHAR(100) PRIMARY KEY,
+    active INTEGER NOT NULL DEFAULT 0,
+    expires_at TIMESTAMP,
+    reason TEXT,
+    actor TEXT,
+    mode VARCHAR(20) NOT NULL DEFAULT 'auto',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Durable mutation audit (minimal, append-only)
+CREATE TABLE IF NOT EXISTS mutation_audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    entity_type VARCHAR(50) NOT NULL,
+    entity_id TEXT NOT NULL,
+    action VARCHAR(100) NOT NULL,
+    actor TEXT,
+    reason TEXT,
+    source TEXT,
+    metadata_json TEXT,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO schema_migrations (version) VALUES ('016');

brawny/db/migrations/017_add_job_drain.sql

@@ -0,0 +1,6 @@
+-- Description: Add job drain controls
+
+ALTER TABLE jobs ADD COLUMN drain_until TIMESTAMP;
+ALTER TABLE jobs ADD COLUMN drain_reason TEXT;
+
+INSERT INTO schema_migrations (version) VALUES ('017');

brawny/db/migrations/018_add_nonce_reset_audit.sql

@@ -0,0 +1,20 @@
+-- Audit table for nonce force resets
+-- Provides durable record of destructive nonce operations for incident investigation
+
+CREATE TABLE IF NOT EXISTS nonce_reset_audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    chain_id INTEGER NOT NULL,
+    signer_address TEXT NOT NULL,
+    old_next_nonce INTEGER,
+    new_next_nonce INTEGER NOT NULL,
+    released_reservations INTEGER NOT NULL DEFAULT 0,
+    source TEXT NOT NULL,  -- 'cli', 'executor', 'api'
+    reason TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_nonce_reset_audit_signer
+    ON nonce_reset_audit(chain_id, signer_address);
+
+CREATE INDEX IF NOT EXISTS idx_nonce_reset_audit_created
+    ON nonce_reset_audit(created_at);

brawny/db/migrations/019_add_job_cooldowns.sql

@@ -0,0 +1,8 @@
+-- Add job cooldown tracking
+CREATE TABLE IF NOT EXISTS job_cooldowns (
+    cooldown_key TEXT PRIMARY KEY,
+    last_intent_at INTEGER NOT NULL
+);
+
+INSERT INTO schema_migrations (version) VALUES ('019')
+ON CONFLICT (version) DO NOTHING;

brawny/db/migrations/020_attempt_unique_initial.sql

@@ -0,0 +1,7 @@
+-- Enforce single initial attempt per intent+nonce (replacements allowed)
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_tx_attempts_intent_nonce_initial
+    ON tx_attempts(intent_id, nonce)
+    WHERE replaces_attempt_id IS NULL;
+
+INSERT INTO schema_migrations (version) VALUES ('020');

brawny/db/ops/__init__.py

@@ -1,29 +1,7 @@
-"""Database operations modules.
-
-Flat function-based operations for each domain:
-- blocks: Block state and hash history
-- jobs: Job configuration and KV store
-- intents: Transaction intents
-- attempts: Transaction attempts
-- nonces: Signer state and nonce reservations
-- cache: ABI and proxy cache
-
-Usage:
-    from brawny.db import ops
-
-    # Use functions from specific modules
-    state = ops.blocks.get_block_state(db, chain_id)
-    job = ops.jobs.get_job(db, job_id)
-    intent = ops.intents.create_intent(db, ...)
-"""
+"""Database operations modules."""
 
 from __future__ import annotations
 
-from brawny.db.ops import blocks
-from brawny.db.ops import jobs
-from brawny.db.ops import intents
-from brawny.db.ops import attempts
-from brawny.db.ops import nonces
-from brawny.db.ops import cache
+from brawny.db.ops import logs
 
-__all__ = ["blocks", "jobs", "intents", "attempts", "nonces", "cache"]
+__all__ = ["logs"]

brawny/db/ops/logs.py

@@ -71,8 +71,7 @@ def list_all_logs(
 
 def list_latest_logs(db: "Database", chain_id: int) -> list[dict[str, Any]]:
     """Get the most recent log entry per job."""
-    query = Q.LIST_LATEST_JOB_LOGS[db.dialect]
-    rows = db.execute_returning(query, {"chain_id": chain_id})
+    rows = db.execute_returning(Q.LIST_LATEST_JOB_LOGS, {"chain_id": chain_id})
     return [_row_to_log(row) for row in rows]