semantic update

.ai/PROJECT_MAP.md

@@ -73,6 +73,40 @@
       - 📝 Recursive helper to write entity tree to Markdown with tier badges and enhanced details.
   - ƒ **to_dict** (`Function`) `[TRIVIAL]`
     - 📝 Auto-detected function (orphan)
+- 📦 **PluginExampleShot** (`Module`)
+  - 📝 Reference implementation of a plugin following GRACE standards.
+  - 🔗 IMPLEMENTS -> `[DEF:Std:Plugin]`
+  - ƒ **get_schema** (`Function`)
+    - 📝 Defines input validation schema.
+  - ƒ **execute** (`Function`)
+    - 📝 Core plugin logic with structured logging and progress reporting.
+  - ƒ **id** (`Function`) `[TRIVIAL]`
+    - 📝 Auto-detected function (orphan)
+  - ƒ **name** (`Function`) `[TRIVIAL]`
+    - 📝 Auto-detected function (orphan)
+  - ƒ **description** (`Function`) `[TRIVIAL]`
+    - 📝 Auto-detected function (orphan)
+  - ƒ **version** (`Function`) `[TRIVIAL]`
+    - 📝 Auto-detected function (orphan)
+- 📦 **BackendRouteShot** (`Module`)
+  - 📝 Reference implementation of a task-based route using GRACE-Poly.
+  - 🔗 IMPLEMENTS -> `[DEF:Std:API_FastAPI]`
+  - ƒ **create_task** (`Function`)
+    - 📝 Create and start a new task using TaskManager. Non-blocking.
+    - 🔗 CALLS -> `task_manager.create_task`
+- 🧩 **FrontendComponentShot** (`Component`)
+  - 📝 Reference implementation of a task-spawning component using
+  - 🏗️ Layer: UI
+  - 📥 Props: plugin_id: any, params: any
+  - ⬅️ READS_FROM `lib`
+  - ⬅️ READS_FROM `t`
+- 📦 **DashboardTypes** (`Module`) `[TRIVIAL]`
+  - 📝 TypeScript interfaces for Dashboard entities
+  - 🏗️ Layer: Domain
+- 🧩 **Counter** (`Component`) `[TRIVIAL]`
+  - 📝 Simple counter demo component
+  - 🏗️ Layer: UI
+  - ➡️ WRITES_TO `state`
 - 📦 **stores_module** (`Module`)
   - 📝 Global state management using Svelte stores.
   - 🏗️ Layer: UI-State
@@ -116,6 +150,11 @@
     - 📝 Generic request wrapper.
   - 📦 **api** (`Data`)
     - 📝 API client object with specific methods.
+- 📦 **Utils** (`Module`) `[TRIVIAL]`
+  - 📝 General utility functions (class merging)
+  - 🏗️ Layer: Infra
+  - ƒ **cn** (`Function`) `[TRIVIAL]`
+    - 📝 Auto-detected function (orphan)
 - 🗄️ **authStore** (`Store`)
   - 📝 Manages the global authentication state on the frontend.
   - 🏗️ Layer: Feature
@@ -131,9 +170,9 @@
       - 📝 Clears authentication state and storage.
     - ƒ **setLoading** (`Function`)
       - 📝 Updates the loading state.
-- 📦 **debounce** (`Module`) `[TRIVIAL]`
-  - 📝 Auto-generated module for frontend/src/lib/utils/debounce.js
-  - 🏗️ Layer: Unknown
+- 📦 **Debounce** (`Module`) `[TRIVIAL]`
+  - 📝 Debounce utility for limiting function execution rate
+  - 🏗️ Layer: Infra
   - ƒ **debounce** (`Function`) `[TRIVIAL]`
     - 📝 Auto-detected function (orphan)
 - 🗄️ **taskDrawer** (`Store`) `[CRITICAL]`
@@ -181,8 +220,9 @@
   - 📝 Unit tests for sidebar store
   - 🏗️ Layer: Domain (Tests)
   - ƒ **test_sidebar_initial_state** (`Function`)
-    - ƒ **test_toggleSidebar** (`Function`)
-      - ƒ **test_setActiveItem** (`Function`)
+  - ƒ **test_toggleSidebar** (`Function`)
+  - ƒ **test_setActiveItem** (`Function`)
+  - ƒ **test_mobile_functions** (`Function`)
 - 📦 **frontend.src.lib.stores.__tests__.test_activity** (`Module`)
   - 📝 Unit tests for activity store
   - 🏗️ Layer: UI
@@ -202,7 +242,9 @@
 - 🧩 **Select** (`Component`) `[TRIVIAL]`
   - 📝 Standardized dropdown selection component.
   - 🏗️ Layer: Atom
-  - 📥 Props: label: string , value: string | number , disabled: boolean 
+  - ⬅️ READS_FROM `lib`
+  - ➡️ WRITES_TO `bindable`
+  - ➡️ WRITES_TO `props`
 - 📦 **ui** (`Module`) `[TRIVIAL]`
   - 📝 Central export point for standardized UI components.
   - 🏗️ Layer: Atom
@@ -210,21 +252,26 @@
 - 🧩 **PageHeader** (`Component`) `[TRIVIAL]`
   - 📝 Standardized page header with title and action area.
   - 🏗️ Layer: Atom
-  - 📥 Props: title: string 
+  - ⬅️ READS_FROM `lib`
+  - ➡️ WRITES_TO `props`
 - 🧩 **Card** (`Component`) `[TRIVIAL]`
   - 📝 Standardized container with padding and elevation.
   - 🏗️ Layer: Atom
-  - 📥 Props: title: string 
+  - ⬅️ READS_FROM `lib`
+  - ➡️ WRITES_TO `props`
 - 🧩 **Button** (`Component`) `[TRIVIAL]`
-  - 📝 Define component interface and default values.
+  - 📝 Define component interface and default values (Svelte 5 Runes).
   - 🏗️ Layer: Atom
   - 🔒 Invariant: Supports accessible labels and keyboard navigation.
-  - 📥 Props: isLoading: boolean , disabled: boolean 
+  - ⬅️ READS_FROM `lib`
+  - ➡️ WRITES_TO `props`
 - 🧩 **Input** (`Component`) `[TRIVIAL]`
   - 📝 Standardized text input component with label and error handling.
   - 🏗️ Layer: Atom
   - 🔒 Invariant: Consistent spacing and focus states.
-  - 📥 Props: label: string , value: string , placeholder: string , error: string , disabled: boolean 
+  - ⬅️ READS_FROM `lib`
+  - ➡️ WRITES_TO `bindable`
+  - ➡️ WRITES_TO `props`
 - 🧩 **LanguageSwitcher** (`Component`) `[TRIVIAL]`
   - 📝 Dropdown component to switch between supported languages.
   - 🏗️ Layer: Atom
@@ -293,10 +340,9 @@
   - 📝 Display page hierarchy navigation
   - 🏗️ Layer: UI
   - 🔒 Invariant: Always shows current page path
-  - 📥 Props: maxVisible: any
   - ⬅️ READS_FROM `app`
   - ⬅️ READS_FROM `lib`
-  - ⬅️ READS_FROM `page`
+  - ➡️ WRITES_TO `props`
 - 📦 **Breadcrumbs** (`Module`) `[TRIVIAL]`
   - 📝 Auto-generated module for frontend/src/lib/components/layout/Breadcrumbs.svelte
   - 🏗️ Layer: Unknown
@@ -328,6 +374,12 @@
     - 📝 Auto-detected function (orphan)
   - ƒ **disconnectWebSocket** (`Function`) `[TRIVIAL]`
     - 📝 Auto-detected function (orphan)
+- 📦 **ErrorPage** (`Page`)
+  - 📝 Global error page displaying HTTP status and messages
+  - 🏗️ Layer: UI
+- 📦 **RootLayoutConfig** (`Module`) `[TRIVIAL]`
+  - 📝 Root layout configuration (SPA mode)
+  - 🏗️ Layer: Infra
 - 📦 **HomePage** (`Page`) `[CRITICAL]`
   - 📝 Redirect to Dashboard Hub as per UX requirements
   - 🏗️ Layer: UI
@@ -692,8 +744,9 @@
 - 🧩 **PasswordPrompt** (`Component`)
   - 📝 A modal component to prompt the user for database passwords when a migration task is paused.
   - 🏗️ Layer: UI
-  - 📥 Props: show: any, databases: any, errorMessage: any
   - ⚡ Events: cancel, resume
+  - ➡️ WRITES_TO `props`
+  - ⬅️ READS_FROM `effect`
   - ƒ **handleSubmit** (`Function`)
     - 📝 Validates and dispatches the passwords to resume the task.
   - ƒ **handleCancel** (`Function`)
@@ -703,6 +756,7 @@
   - 🏗️ Layer: Feature
   - 🔒 Invariant: Each source database can be mapped to one target database.
   - ⚡ Events: update
+  - ➡️ WRITES_TO `props`
   - ƒ **updateMapping** (`Function`)
     - 📝 Updates a mapping for a specific source database.
   - ƒ **getSuggestion** (`Function`)
@@ -711,13 +765,12 @@
   - 📝 Displays detailed logs for a specific task inline or in a modal using TaskLogPanel.
   - 🏗️ Layer: UI
   - 🔒 Invariant: Real-time logs are always appended without duplicates.
-  - 📥 Props: show: any, inline: any, taskId: any, taskStatus: any, realTimeLogs: any
   - ⚡ Events: close
-  - ⬅️ READS_FROM `t`
+  - ➡️ WRITES_TO `bindable`
+  - ➡️ WRITES_TO `props`
+  - ➡️ WRITES_TO `state`
   - 📦 **handleRealTimeLogs** (`Action`)
-    - 📝 Append real-time logs as they arrive from WebSocket, preventing duplicates */
   - ƒ **fetchLogs** (`Function`)
-    - 📝 Fetches logs for the current task from API (polling fallback).
 - 📦 **TaskLogViewer** (`Module`) `[TRIVIAL]`
   - 📝 Auto-generated module for frontend/src/components/TaskLogViewer.svelte
   - 🏗️ Layer: Unknown
@@ -732,8 +785,8 @@
   - 📝 Prompts the user to provide a database mapping when one is missing during migration.
   - 🏗️ Layer: Feature
   - 🔒 Invariant: Modal blocks migration progress until resolved or cancelled.
-  - 📥 Props: show: boolean , sourceDbName: string , sourceDbUuid: string 
   - ⚡ Events: cancel, resolve
+  - ➡️ WRITES_TO `props`
   - ƒ **resolve** (`Function`)
     - 📝 Dispatches the resolution event with the selected mapping.
   - ƒ **cancel** (`Function`)
@@ -742,10 +795,10 @@
   - 📝 Displays a grid of dashboards with selection and pagination.
   - 🏗️ Layer: Component
   - 🔒 Invariant: Selected IDs must be a subset of available dashboards.
-  - 📥 Props: dashboards: DashboardMetadata[] , selectedIds: number[] , environmentId: string 
   - ⚡ Events: selectionChanged
+  - ➡️ WRITES_TO `props`
+  - ➡️ WRITES_TO `derived`
   - ➡️ WRITES_TO `t`
-  - ⬅️ READS_FROM `t`
   - ƒ **handleValidate** (`Function`)
     - 📝 Triggers dashboard validation task.
   - ƒ **handleSort** (`Function`)
@@ -816,8 +869,8 @@
 - 🧩 **TaskList** (`Component`)
   - 📝 Displays a list of tasks with their status and execution details.
   - 🏗️ Layer: Component
-  - 📥 Props: tasks: Array<any> , loading: boolean 
   - ⚡ Events: select
+  - ➡️ WRITES_TO `props`
   - ➡️ WRITES_TO `t`
   - ⬅️ READS_FROM `t`
   - ƒ **getStatusColor** (`Function`)
@@ -829,8 +882,8 @@
 - 🧩 **DynamicForm** (`Component`)
   - 📝 Generates a form dynamically based on a JSON schema.
   - 🏗️ Layer: UI
-  - 📥 Props: schema: any
   - ⚡ Events: submit
+  - ➡️ WRITES_TO `props`
   - ƒ **handleSubmit** (`Function`)
     - 📝 Dispatches the submit event with the form data.
   - ƒ **initializeForm** (`Function`)
@@ -839,8 +892,8 @@
   - 📝 Provides a UI component for selecting source and target environments.
   - 🏗️ Layer: Feature
   - 🔒 Invariant: Source and target environments must be selectable from the list of configured environments.
-  - 📥 Props: label: string , selectedId: string 
   - ⚡ Events: change
+  - ➡️ WRITES_TO `props`
   - ƒ **handleSelect** (`Function`)
     - 📝 Dispatches the selection change event.
 - 🧩 **ProtectedRoute** (`Component`) `[TRIVIAL]`
@@ -850,11 +903,13 @@
   - ⬅️ READS_FROM `app`
   - ⬅️ READS_FROM `auth`
 - 🧩 **TaskLogPanel** (`Component`)
-  - 📝 Component properties and state.
+  - 📝 Combines log filtering and display into a single cohesive dark-themed panel.
   - 🏗️ Layer: UI
   - 🔒 Invariant: Must always display logs in chronological order and respect auto-scroll preference.
-  - 📥 Props: logs: any, autoScroll: any
   - ⚡ Events: filterChange
+  - ➡️ WRITES_TO `bindable`
+  - ➡️ WRITES_TO `props`
+  - ➡️ WRITES_TO `state`
 - 📦 **TaskLogPanel** (`Module`) `[TRIVIAL]`
   - 📝 Auto-generated module for frontend/src/components/tasks/TaskLogPanel.svelte
   - 🏗️ Layer: Unknown
@@ -869,7 +924,9 @@
 - 🧩 **LogFilterBar** (`Component`)
   - 📝 Compact filter toolbar for logs — level, source, and text search in a single dense row.
   - 🏗️ Layer: UI
-  - 📥 Props: availableSources: any, selectedLevel: any, selectedSource: any, searchText: any
+  - ➡️ WRITES_TO `bindable`
+  - ➡️ WRITES_TO `props`
+  - ➡️ WRITES_TO `derived`
 - 📦 **LogFilterBar** (`Module`) `[TRIVIAL]`
   - 📝 Auto-generated module for frontend/src/components/tasks/LogFilterBar.svelte
   - 🏗️ Layer: Unknown
@@ -884,21 +941,15 @@
 - 🧩 **LogEntryRow** (`Component`)
   - 📝 Renders a single log entry with stacked layout optimized for narrow drawer panels.
   - 🏗️ Layer: UI
-  - 📥 Props: log: any, showSource: any
+  - ➡️ WRITES_TO `props`
+  - ➡️ WRITES_TO `derived`
   - ƒ **formatTime** (`Function`)
     - 📝 Format ISO timestamp to HH:MM:SS */
-- 📦 **LogEntryRow** (`Module`) `[TRIVIAL]`
-  - 📝 Auto-generated module for frontend/src/components/tasks/LogEntryRow.svelte
-  - 🏗️ Layer: Unknown
-  - ƒ **getLevelClass** (`Function`) `[TRIVIAL]`
-    - 📝 Auto-detected function (orphan)
-  - ƒ **getSourceClass** (`Function`) `[TRIVIAL]`
-    - 📝 Auto-detected function (orphan)
 - 🧩 **FileList** (`Component`)
   - 📝 Displays a table of files with metadata and actions.
   - 🏗️ Layer: UI
-  - 📥 Props: files: any
   - ⚡ Events: delete, navigate
+  - ➡️ WRITES_TO `props`
   - ➡️ WRITES_TO `t`
   - ⬅️ READS_FROM `t`
   - ƒ **isDirectory** (`Function`)
@@ -911,6 +962,7 @@
   - 📝 Provides a form for uploading files to a specific category.
   - 🏗️ Layer: UI
   - ⚡ Events: uploaded
+  - ➡️ WRITES_TO `props`
   - ⬅️ READS_FROM `t`
   - ➡️ WRITES_TO `t`
   - ƒ **handleUpload** (`Function`)
@@ -964,7 +1016,7 @@
 - 🧩 **CommitHistory** (`Component`)
   - 📝 Displays the commit history for a specific dashboard.
   - 🏗️ Layer: Component
-  - 📥 Props: dashboardId: any
+  - ➡️ WRITES_TO `props`
   - ⬅️ READS_FROM `t`
   - ➡️ WRITES_TO `t`
   - ƒ **onMount** (`Function`)
@@ -975,8 +1027,9 @@
   - 📝 Modal for deploying a dashboard to a target environment.
   - 🏗️ Layer: Component
   - 🔒 Invariant: Cannot deploy without a selected environment.
-  - 📥 Props: dashboardId: any, show: any
   - ⚡ Events: deploy
+  - ➡️ WRITES_TO `props`
+  - ⬅️ READS_FROM `effect`
   - 📦 **loadStatus** (`Watcher`)
   - ƒ **loadEnvironments** (`Function`)
     - 📝 Fetch available environments from API.
@@ -986,8 +1039,8 @@
   - 📝 UI for resolving merge conflicts (Keep Mine / Keep Theirs).
   - 🏗️ Layer: Component
   - 🔒 Invariant: User must resolve all conflicts before saving.
-  - 📥 Props: conflicts: any, show: any
   - ⚡ Events: resolve
+  - ➡️ WRITES_TO `props`
   - ƒ **resolve** (`Function`)
     - 📝 Set resolution strategy for a file.
   - ƒ **handleSave** (`Function`)
@@ -995,8 +1048,9 @@
 - 🧩 **CommitModal** (`Component`)
   - 📝 Модальное окно для создания коммита с просмотром изменений (diff).
   - 🏗️ Layer: Component
-  - 📥 Props: dashboardId: any, show: any
   - ⚡ Events: commit
+  - ➡️ WRITES_TO `props`
+  - ⬅️ READS_FROM `effect`
   - ƒ **handleGenerateMessage** (`Function`)
     - 📝 Generates a commit message using LLM.
   - ƒ **loadStatus** (`Function`)
@@ -1006,8 +1060,8 @@
 - 🧩 **BranchSelector** (`Component`)
   - 📝 UI для выбора и создания веток Git.
   - 🏗️ Layer: Component
-  - 📥 Props: dashboardId: any, currentBranch: any
   - ⚡ Events: change
+  - ➡️ WRITES_TO `props`
   - ⬅️ READS_FROM `t`
   - ƒ **onMount** (`Function`)
     - 📝 Load branches when component is mounted.
@@ -1022,7 +1076,7 @@
 - 🧩 **GitManager** (`Component`)
   - 📝 Центральный компонент для управления Git-операциями конкретного дашборда.
   - 🏗️ Layer: Component
-  - 📥 Props: dashboardId: any, dashboardTitle: any, show: any
+  - ➡️ WRITES_TO `props`
   - ➡️ WRITES_TO `t`
   - ⬅️ READS_FROM `t`
   - ƒ **checkStatus** (`Function`)
@@ -1038,7 +1092,7 @@
 - 🧩 **DocPreview** (`Component`)
   - 📝 UI component for previewing generated dataset documentation before saving.
   - 🏗️ Layer: UI
-  - 📥 Props: documentation: any, onSave: any, onCancel: any
+  - ➡️ WRITES_TO `props`
   - ➡️ WRITES_TO `t`
   - ⬅️ READS_FROM `t`
 - 📦 **DocPreview** (`Module`) `[TRIVIAL]`
@@ -1049,7 +1103,7 @@
 - 🧩 **ProviderConfig** (`Component`)
   - 📝 UI form for managing LLM provider configurations.
   - 🏗️ Layer: UI
-  - 📥 Props: providers: any, onSave: any
+  - ➡️ WRITES_TO `props`
   - ➡️ WRITES_TO `t`
   - ⬅️ READS_FROM `t`
 - 📦 **ProviderConfig** (`Module`) `[TRIVIAL]`
@@ -1099,14 +1153,14 @@
     - 📝 Provides a WebSocket endpoint for real-time log streaming of a task with server-side filtering.
   - 📦 **StaticFiles** (`Mount`)
     - 📝 Mounts the frontend build directory to serve static assets.
+    - ƒ **serve_spa** (`Function`)
+      - 📝 Serves the SPA frontend for any path not matched by API routes.
     - ƒ **read_root** (`Function`)
       - 📝 A simple root endpoint to confirm that the API is running when frontend is missing.
   - ƒ **network_error_handler** (`Function`) `[TRIVIAL]`
     - 📝 Auto-detected function (orphan)
   - ƒ **matches_filters** (`Function`) `[TRIVIAL]`
     - 📝 Auto-detected function (orphan)
-  - ƒ **serve_spa** (`Function`) `[TRIVIAL]`
-    - 📝 Auto-detected function (orphan)
 - 📦 **Dependencies** (`Module`)
   - 📝 Manages creation and provision of shared application dependencies, such as PluginLoader and TaskManager, to avoid circular imports.
   - 🏗️ Layer: Core