few shots update

.ai/shots/critical_module.py

@@ -0,0 +1,79 @@
+# [DEF:TransactionCore:Module]
+# @TIER: CRITICAL
+# @SEMANTICS: Finance, ACID, Transfer, Ledger
+# @PURPOSE: Core banking transaction processor with ACID guarantees.
+# @LAYER: Domain (Core)
+# @RELATION: DEPENDS_ON -> [DEF:Infra:PostgresDB]
+# @RELATION: DEPENDS_ON -> [DEF:Infra:AuditLog]
+# @INVARIANT: Total system balance must remain constant (Double-Entry Bookkeeping).
+# @INVARIANT: Negative transfers are strictly forbidden.
+
+# @TEST_DATA: sufficient_funds -> {"from": "acc_A", "to": "acc_B", "amt": 100.00}
+# @TEST_DATA: insufficient_funds -> {"from": "acc_empty", "to": "acc_B", "amt": 1000.00}
+# @TEST_DATA: concurrency_lock -> {./fixtures/transactions.json#race_condition}
+
+from decimal import Decimal
+from typing import NamedTuple
+from ...core.logger import belief_scope
+from ...core.db import atomic_transaction, get_balance, update_balance
+from ...core.exceptions import BusinessRuleViolation
+
+class TransferResult(NamedTuple):
+    tx_id: str
+    status: str
+    new_balance: Decimal
+
+# [DEF:execute_transfer:Function]
+# @PURPOSE: Atomically move funds between accounts with audit trails.
+# @PARAM: sender_id (str) - Source account.
+# @PARAM: receiver_id (str) - Destination account.
+# @PARAM: amount (Decimal) - Positive amount to transfer.
+# @PRE: amount > 0; sender != receiver; sender_balance >= amount.
+# @POST: sender_balance -= amount; receiver_balance += amount; Audit Record Created.
+# @SIDE_EFFECT: Database mutation (Rows locked), Audit IO.
+#
+# @UX_STATE: Success -> Returns 200 OK + Transaction Receipt.
+# @UX_STATE: Error(LowBalance) -> 422 Unprocessable -> UI shows "Top-up needed" modal.
+# @UX_STATE: Error(System) -> 500 Internal -> UI shows "Retry later" toast.
+def execute_transfer(sender_id: str, receiver_id: str, amount: Decimal) -> TransferResult:
+    # Guard: Input Validation
+    if amount <= Decimal("0.00"):
+        raise BusinessRuleViolation("Transfer amount must be positive.")
+    if sender_id == receiver_id:
+        raise BusinessRuleViolation("Cannot transfer to self.")
+
+    with belief_scope("execute_transfer") as context:
+        context.logger.info("Initiating transfer", data={"from": sender_id, "to": receiver_id})
+
+        try:
+            # 1. Action: Atomic DB Transaction
+            # @RELATION: CALLS -> atomic_transaction
+            with atomic_transaction():
+                # Guard: State Validation (Strict)
+                current_balance = get_balance(sender_id, for_update=True)
+                
+                if current_balance < amount:
+                    # @UX_FEEDBACK: Triggers specific UI flow for insufficient funds
+                    context.logger.warn("Insufficient funds", data={"balance": current_balance})
+                    raise BusinessRuleViolation("INSUFFICIENT_FUNDS")
+
+                # 2. Action: Mutation
+                new_src_bal = update_balance(sender_id, -amount)
+                new_dst_bal = update_balance(receiver_id, +amount)
+
+                # 3. Action: Audit
+                tx_id = context.audit.log_transfer(sender_id, receiver_id, amount)
+                
+                context.logger.info("Transfer committed", data={"tx_id": tx_id})
+                return TransferResult(tx_id, "COMPLETED", new_src_bal)
+
+        except BusinessRuleViolation as e:
+            # Logic: Explicit re-raise for UI mapping
+            raise e
+        except Exception as e:
+            # Logic: Catch-all safety net
+            context.logger.error("Critical Transfer Failure", error=e)
+            raise RuntimeError("TRANSACTION_ABORTED") from e
+# [/DEF:execute_transfer:Function]
+
+# [/DEF:TransactionCore:Module]