diff --git a/.ai/shots/backend_route.py b/.ai/shots/backend_route.py
index b5239e76..b67a4767 100644
--- a/.ai/shots/backend_route.py
+++ b/.ai/shots/backend_route.py
@@ -1,4 +1,4 @@
-# [DEF:BackendRouteShot:Module]
+#[DEF:BackendRouteShot:Module]
# @TIER: STANDARD
# @SEMANTICS: Route, Task, API, Async
# @PURPOSE: Reference implementation of a task-based route using GRACE-Poly.
@@ -9,53 +9,66 @@
from typing import Dict, Any
from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel
-from ...core.logger import belief_scope
+# GRACE: Правильный импорт глобального логгера и scope
+from ...core.logger import logger, belief_scope
from ...core.task_manager import TaskManager, Task
from ...core.config_manager import ConfigManager
from ...dependencies import get_task_manager, get_config_manager, get_current_user
router = APIRouter()
+# [DEF:CreateTaskRequest:Class]
+# @PURPOSE: DTO for task creation payload.
class CreateTaskRequest(BaseModel):
plugin_id: str
params: Dict[str, Any]
+# [/DEF:CreateTaskRequest:Class]
-@router.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED)
# [DEF:create_task:Function]
# @PURPOSE: Create and start a new task using TaskManager. Non-blocking.
-# @PARAM: request (CreateTaskRequest) - Plugin and params.
-# @PARAM: task_manager (TaskManager) - Async task executor.
+# @DATA_CONTRACT: Input -> CreateTaskRequest, Output -> Task
# @PRE: plugin_id must match a registered plugin.
-# @POST: A new task is spawned; Task ID returned immediately.
-# @SIDE_EFFECT: Writes to DB, Trigger background worker.
+# @POST: A new task is spawned; Task object returned immediately.
+# @SIDE_EFFECT: Writes to DB, Triggers background worker.
+#
+# @UX_STATE: Success -> 201 Created
+# @UX_STATE: Error(Validation) -> 400 Bad Request
+# @UX_STATE: Error(System) -> 500 Internal Server Error
+@router.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED)
async def create_task(
request: CreateTaskRequest,
task_manager: TaskManager = Depends(get_task_manager),
config: ConfigManager = Depends(get_config_manager),
current_user = Depends(get_current_user)
):
- # Context Logging
+ # GRACE: Открываем семантическую транзакцию
with belief_scope("create_task"):
try:
- # 1. Action: Configuration Resolution
+ # GRACE: [REASON] - Фиксируем начало дедуктивной цепочки
+ logger.reason("Resolving configuration and spawning task", extra={"plugin_id": request.plugin_id})
+
timeout = config.get("TASKS_DEFAULT_TIMEOUT", 3600)
- # 2. Action: Spawn async task
# @RELATION: CALLS -> task_manager.create_task
task = await task_manager.create_task(
plugin_id=request.plugin_id,
params={**request.params, "timeout": timeout}
)
+
+ # GRACE:[REFLECT] - Подтверждаем выполнение @POST перед выходом
+ logger.reflect("Task spawned successfully", extra={"task_id": task.id})
return task
except ValueError as e:
- # 3. Recovery: Domain logic error mapping
+ # GRACE: [EXPLORE] - Обработка ожидаемого отклонения
+ logger.explore("Domain validation error during task creation", exc_info=e)
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=str(e)
)
except Exception as e:
- # @UX_STATE: Error feedback -> 500 Internal Error
+ # GRACE: [EXPLORE] - Обработка критического сбоя
+ logger.explore("Internal Task Spawning Error", exc_info=e)
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="Internal Task Spawning Error"
diff --git a/.ai/shots/critical_module.py b/.ai/shots/critical_module.py
index 79a9db38..8a72e130 100644
--- a/.ai/shots/critical_module.py
+++ b/.ai/shots/critical_module.py
@@ -3,34 +3,28 @@
# @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:PostgresDB]
#
# @INVARIANT: Total system balance must remain constant (Double-Entry Bookkeeping).
# @INVARIANT: Negative transfers are strictly forbidden.
-# --- Test Specifications (The "What" and "Why", not the "Data") ---
-# @TEST_CONTRACT: Input -> TransferInputDTO, Output -> TransferResultDTO
-
-# Happy Path
+# --- Test Specifications ---
+# @TEST_CONTRACT: TransferRequestDTO -> TransferResultDTO
# @TEST_SCENARIO: sufficient_funds -> Returns COMPLETED, balances updated.
# @TEST_FIXTURE: sufficient_funds -> file:./__tests__/fixtures/transfers.json#happy_path
-
-# Edge Cases (CRITICAL)
-# @TEST_SCENARIO: insufficient_funds -> Throws BusinessRuleViolation("INSUFFICIENT_FUNDS").
-# @TEST_SCENARIO: negative_amount -> Throws BusinessRuleViolation("Transfer amount must be positive.").
-# @TEST_SCENARIO: self_transfer -> Throws BusinessRuleViolation("Cannot transfer to self.").
-# @TEST_SCENARIO: audit_failure -> Throws RuntimeError("TRANSACTION_ABORTED").
-# @TEST_SCENARIO: concurrency_conflict -> Throws DBTransactionError.
-
-# Linking Tests to Invariants
+# @TEST_EDGE: insufficient_funds -> Throws BusinessRuleViolation("INSUFFICIENT_FUNDS").
+# @TEST_EDGE: negative_amount -> Throws BusinessRuleViolation("Transfer amount must be positive.").
+# @TEST_EDGE: concurrency_conflict -> Throws DBTransactionError.
+#
# @TEST_INVARIANT: total_balance_constant -> VERIFIED_BY: [sufficient_funds, concurrency_conflict]
# @TEST_INVARIANT: negative_transfer_forbidden -> VERIFIED_BY: [negative_amount]
-
from decimal import Decimal
from typing import NamedTuple
-from ...core.logger import belief_scope
+# GRACE: Импорт глобального логгера с семантическими методами
+from ...core.logger import logger, belief_scope
from ...core.db import atomic_transaction, get_balance, update_balance
+from ...core.audit import log_audit_trail
from ...core.exceptions import BusinessRuleViolation
class TransferResult(NamedTuple):
@@ -40,55 +34,54 @@ class TransferResult(NamedTuple):
# [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.
+# @DATA_CONTRACT: Input -> (sender_id: str, receiver_id: str, amount: Decimal), Output -> TransferResult
# @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
+ # Guard: Input Validation (Вне belief_scope, так как это trivial проверка)
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})
+ # GRACE: Используем strict Context Manager без 'as context'
+ with belief_scope("execute_transfer"):
+ # GRACE: [REASON] - Жесткая дедукция, начало алгоритма
+ logger.reason("Initiating transfer", extra={"from": sender_id, "to": receiver_id, "amount": amount})
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})
+ # GRACE: [EXPLORE] - Отклонение от Happy Path (фолбэк/ошибка)
+ logger.explore("Insufficient funds validation hit", extra={"balance": current_balance})
raise BusinessRuleViolation("INSUFFICIENT_FUNDS")
- # 2. Action: Mutation
+ # 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)
+ # Audit
+ tx_id = log_audit_trail("TRANSFER", sender_id, receiver_id, amount)
+
+ # GRACE:[REFLECT] - Сверка с @POST перед возвратом
+ logger.reflect("Transfer committed successfully", extra={"tx_id": tx_id, "new_balance": new_src_bal})
- 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
+ # 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)
+ # GRACE: [EXPLORE] - Неожиданный сбой
+ logger.explore("Critical Transfer Failure", exc_info=e)
raise RuntimeError("TRANSACTION_ABORTED") from e
-# [/DEF:execute_transfer:Function]
+#[/DEF:execute_transfer:Function]
# [/DEF:TransactionCore:Module]
\ No newline at end of file
diff --git a/.ai/shots/frontend_component.svelte b/.ai/shots/frontend_component.svelte
index d5d18e12..c4dcf4f3 100644
--- a/.ai/shots/frontend_component.svelte
+++ b/.ai/shots/frontend_component.svelte
@@ -11,45 +11,27 @@
* @INVARIANT: Loading state must always terminate (no infinite spinner).
* @INVARIANT: User must receive feedback on both success and failure.
*
+ * @UX_REACTIVITY: Props -> $props(), LocalState -> $state(isLoading).
+ *
* @TEST_CONTRACT: ComponentState ->
* {
- * required_fields: {
- * isLoading: bool
- * },
- * invariants: [
+ * required_fields: { isLoading: bool },
+ * invariants:[
* "isLoading=true implies button.disabled=true",
- * "isLoading=true implies aria-busy=true",
- * "isLoading=true implies spinner visible"
+ * "isLoading=true implies aria-busy=true"
* ]
* }
*
- * @TEST_CONTRACT: ApiResponse ->
- * {
- * required_fields: {},
- * optional_fields: {
- * task_id: str
- * }
- * }
-
- * @TEST_FIXTURE: idle_state ->
- * {
- * isLoading: false
- * }
- *
- * @TEST_FIXTURE: successful_response ->
- * {
- * task_id: "task_123"
- * }
-
+ * @TEST_FIXTURE: idle_state -> { isLoading: false }
+ * @TEST_FIXTURE: successful_response -> { task_id: "task_123" }
+ *
* @TEST_EDGE: api_failure -> raises Error("Network")
* @TEST_EDGE: empty_response -> {}
* @TEST_EDGE: rapid_double_click -> special: concurrent_click
- * @TEST_EDGE: unresolved_promise -> special: pending_state
-
- * @TEST_INVARIANT: prevent_double_submission -> verifies: [rapid_double_click]
- * @TEST_INVARIANT: loading_state_consistency -> verifies: [idle_state, pending_state]
- * @TEST_INVARIANT: feedback_always_emitted -> verifies: [successful_response, api_failure]
-
+ *
+ * @TEST_INVARIANT: prevent_double_submission -> VERIFIED_BY:[rapid_double_click]
+ * @TEST_INVARIANT: feedback_always_emitted -> VERIFIED_BY:[successful_response, api_failure]
+ *
* @UX_STATE: Idle -> Button enabled, primary color, no spinner.
* @UX_STATE: Loading -> Button disabled, spinner visible, aria-busy=true.
* @UX_STATE: Success -> Toast success displayed.
@@ -59,44 +41,39 @@
*
* @UX_TEST: Idle -> {click: spawnTask, expected: isLoading=true}
* @UX_TEST: Loading -> {double_click: ignored, expected: single_api_call}
- * @UX_TEST: Success -> {api_resolve: task_id, expected: toast.success called}
- * @UX_TEST: Error -> {api_reject: error, expected: toast.error called}
+ */
-->