refactor: expand runtime contracts and debt ratchets

tests/fixtures/architecture/complexity-baseline.json

@@ -1,8 +1,6 @@
 {
   "api_endpoint": {
     "app/api/endpoints/agent.py:web_agent_stream": 346,
-    "app/api/endpoints/download.py:add": 92,
-    "app/api/endpoints/mcp.py:mcp_jsonrpc": 83,
     "app/api/endpoints/media.py:scrape": 105,
     "app/api/endpoints/openai.py:chat_completions": 107,
     "app/api/endpoints/openai.py:responses": 105,
@@ -20,8 +18,7 @@
   },
   "chain_public": {
     "app/chain/download.py:DownloadChain.batch_download": 572,
-    "app/chain/download.py:DownloadChain.download_single": 276,
-    "app/chain/download.py:DownloadChain.get_no_exists_info": 152,
+    "app/chain/download.py:DownloadChain.download_single": 255,
     "app/chain/mediaserver.py:MediaServerChain.sync": 292,
     "app/chain/site.py:SiteChain.sync_cookies": 180,
     "app/chain/subscribe.py:SubscribeChain.add": 183,

tests/fixtures/architecture/configuration-debt-baseline.json

@@ -9,7 +9,7 @@
     "root": "app"
   },
   "settings_imports": {
-    "count": 169,
+    "count": 164,
     "files": [
       "app/adapters/cache/backends.py",
       "app/adapters/cache/redis.py",
@@ -49,9 +49,6 @@
       "app/agent/tools/impl/update_system_settings.py",
       "app/api/endpoints/agent.py",
       "app/api/endpoints/anthropic.py",
-      "app/api/endpoints/dashboard.py",
-      "app/api/endpoints/history.py",
-      "app/api/endpoints/login.py",
       "app/api/endpoints/media.py",
       "app/api/endpoints/message.py",
       "app/api/endpoints/openai.py",
@@ -83,7 +80,6 @@
       "app/chain/scraping.py",
       "app/chain/search.py",
       "app/chain/site.py",
-      "app/chain/storage.py",
       "app/chain/subscribe.py",
       "app/chain/system.py",
       "app/chain/torrents.py",
@@ -166,7 +162,6 @@
       "app/runtime/extensions/plugin_manager.py",
       "app/runtime/state.py",
       "app/runtime/thread.py",
-      "app/scheduler.py",
       "app/startup/agent_initializer.py",
       "app/startup/database.py",
       "app/startup/database_initializer.py",
@@ -184,10 +179,6 @@
   },
   "system_config_oper_constructions": {
     "calls": [
-      {
-        "file": "app/scheduler.py",
-        "name": "SystemConfigOper"
-      },
       {
         "file": "app/startup/modules_initializer.py",
         "name": "SystemConfigOper"
@@ -245,6 +236,6 @@
         "name": "SystemConfigOper"
       }
     ],
-    "count": 15
+    "count": 14
   }
 }

tests/fixtures/architecture/dependency-baseline.json

@@ -13,8 +13,8 @@
     "runtime_to_db": [],
     "workflow_to_db": []
   },
-  "edge_count": 6299,
-  "edge_sha256": "f98ab7d05c884a07a881eff1ab34b1ba5023751f1e95b956debcbad54c385810",
+  "edge_count": 6306,
+  "edge_sha256": "7ca2da728599965ef604010fdf8e8e03d2939c68f3f45eba5b93aff63c2838a4",
   "edges": [
     "app -> app.runtime",
     "app -> app.runtime.compat",
@@ -1479,6 +1479,7 @@
     "app.api.apiv1 -> app.api",
     "app.api.apiv1 -> app.api.router_specs",
     "app.api.context -> app.application",
+    "app.api.context -> app.application.configuration",
     "app.api.context -> app.application.messaging",
     "app.api.context -> app.application.messaging.chat",
     "app.api.context -> app.application.outbox",
@@ -1701,19 +1702,19 @@
     "app.api.endpoints.dashboard -> app.adapters.web.security",
     "app.api.endpoints.dashboard -> app.adapters.web.security.access",
     "app.api.endpoints.dashboard -> app.api",
+    "app.api.endpoints.dashboard -> app.api.context",
     "app.api.endpoints.dashboard -> app.api.dependencies",
     "app.api.endpoints.dashboard -> app.api.dependencies.auth",
     "app.api.endpoints.dashboard -> app.api.dependencies.history",
     "app.api.endpoints.dashboard -> app.api.response",
     "app.api.endpoints.dashboard -> app.application",
+    "app.api.endpoints.dashboard -> app.application.configuration",
     "app.api.endpoints.dashboard -> app.application.dashboard",
     "app.api.endpoints.dashboard -> app.application.directory",
     "app.api.endpoints.dashboard -> app.application.scheduling",
     "app.api.endpoints.dashboard -> app.chain",
     "app.api.endpoints.dashboard -> app.chain.dashboard",
     "app.api.endpoints.dashboard -> app.chain.storage",
-    "app.api.endpoints.dashboard -> app.runtime",
-    "app.api.endpoints.dashboard -> app.runtime.config",
     "app.api.endpoints.dashboard -> app.schemas",
     "app.api.endpoints.dashboard -> app.schemas.dashboard",
     "app.api.endpoints.dashboard -> app.schemas.response",
@@ -1798,11 +1799,13 @@
     "app.api.endpoints.history -> app.agent.prompt.transfer_redo",
     "app.api.endpoints.history -> app.agent.runtime_loader",
     "app.api.endpoints.history -> app.api",
+    "app.api.endpoints.history -> app.api.context",
     "app.api.endpoints.history -> app.api.dependencies",
     "app.api.endpoints.history -> app.api.dependencies.auth",
     "app.api.endpoints.history -> app.api.dependencies.history",
     "app.api.endpoints.history -> app.api.response",
     "app.api.endpoints.history -> app.application",
+    "app.api.endpoints.history -> app.application.configuration",
     "app.api.endpoints.history -> app.application.history",
     "app.api.endpoints.history -> app.runtime",
     "app.api.endpoints.history -> app.runtime.config",
@@ -1828,6 +1831,7 @@
     "app.api.endpoints.login -> app.adapters.web.security",
     "app.api.endpoints.login -> app.adapters.web.security.access",
     "app.api.endpoints.login -> app.api",
+    "app.api.endpoints.login -> app.api.context",
     "app.api.endpoints.login -> app.api.response",
     "app.api.endpoints.login -> app.application",
     "app.api.endpoints.login -> app.application.configuration",
@@ -1837,8 +1841,6 @@
     "app.api.endpoints.login -> app.application.site",
     "app.api.endpoints.login -> app.chain",
     "app.api.endpoints.login -> app.chain.user",
-    "app.api.endpoints.login -> app.runtime",
-    "app.api.endpoints.login -> app.runtime.config",
     "app.api.endpoints.login -> app.schemas",
     "app.api.endpoints.login -> app.schemas.response",
     "app.api.endpoints.login -> app.schemas.token",
@@ -2439,6 +2441,7 @@
     "app.application.chain.context -> app.application.chain",
     "app.application.chain.context -> app.application.chain.data",
     "app.application.chain.context -> app.application.chain.durable_events",
+    "app.application.chain.context -> app.application.configuration",
     "app.application.chain.durable_events -> app.application",
     "app.application.chain.durable_events -> app.application.history",
     "app.application.chain.durable_events -> app.domain",
@@ -3210,7 +3213,6 @@
     "app.chain.storage -> app.application.directory",
     "app.chain.storage -> app.chain",
     "app.chain.storage -> app.runtime",
-    "app.chain.storage -> app.runtime.config",
     "app.chain.storage -> app.runtime.log",
     "app.chain.storage -> app.schemas",
     "app.chain.storage -> app.schemas.workflow",
@@ -5579,6 +5581,7 @@
     "app.scheduler -> app.agent",
     "app.scheduler -> app.agent.runtime_loader",
     "app.scheduler -> app.application",
+    "app.scheduler -> app.application.configuration",
     "app.scheduler -> app.application.database",
     "app.scheduler -> app.application.image",
     "app.scheduler -> app.application.messaging",
@@ -5596,7 +5599,6 @@
     "app.scheduler -> app.db",
     "app.scheduler -> app.db.oper",
     "app.scheduler -> app.db.oper.agenttask",
-    "app.scheduler -> app.db.oper.systemconfig",
     "app.scheduler -> app.foundation",
     "app.scheduler -> app.foundation.singleton",
     "app.scheduler -> app.runtime",
@@ -5871,6 +5873,7 @@
     "app.startup.command_initializer -> app.application.commands",
     "app.startup.command_initializer -> app.command",
     "app.startup.context -> app.application",
+    "app.startup.context -> app.application.configuration",
     "app.startup.context -> app.application.messaging",
     "app.startup.context -> app.application.messaging.chat",
     "app.startup.context -> app.application.outbox",
@@ -5918,6 +5921,10 @@
     "app.startup.domain_initializer -> app.domain.metainfo",
     "app.startup.domain_initializer -> app.runtime",
     "app.startup.domain_initializer -> app.runtime.config",
+    "app.startup.download_failure -> app.db",
+    "app.startup.download_failure -> app.db.oper",
+    "app.startup.download_failure -> app.db.oper.downloadfailure",
+    "app.startup.download_failure -> app.db.uow",
     "app.startup.lifecycle -> app.adapters",
     "app.startup.lifecycle -> app.adapters.external",
     "app.startup.lifecycle -> app.adapters.external.server",
@@ -6017,7 +6024,6 @@
     "app.startup.modules_initializer -> app.db.oper",
     "app.startup.modules_initializer -> app.db.oper.agentchat",
     "app.startup.modules_initializer -> app.db.oper.agenttask",
-    "app.startup.modules_initializer -> app.db.oper.downloadfailure",
     "app.startup.modules_initializer -> app.db.oper.downloadhistory",
     "app.startup.modules_initializer -> app.db.oper.mediaserver",
     "app.startup.modules_initializer -> app.db.oper.message",
@@ -6056,6 +6062,7 @@
     "app.startup.modules_initializer -> app.startup.chain_events",
     "app.startup.modules_initializer -> app.startup.context",
     "app.startup.modules_initializer -> app.startup.database",
+    "app.startup.modules_initializer -> app.startup.download_failure",
     "app.startup.modules_initializer -> app.startup.managed_resources_initializer",
     "app.startup.modules_initializer -> app.startup.outbox",
     "app.startup.modules_initializer -> app.startup.subscription",
@@ -6316,7 +6323,7 @@
     "app.workflow.actions.transfer_file -> app.workflow",
     "app.workflow.actions.transfer_file -> app.workflow.actions"
   ],
-  "module_count": 784,
+  "module_count": 785,
   "modules": [
     "app",
     "app.adapters",
@@ -7069,6 +7076,7 @@
     "app.startup.database",
     "app.startup.database_initializer",
     "app.startup.domain_initializer",
+    "app.startup.download_failure",
     "app.startup.lifecycle",
     "app.startup.lifecycle.components",
     "app.startup.managed_resources_initializer",

tests/fixtures/architecture/runtime-contract-baseline.json

@@ -2343,7 +2343,10 @@
       "input_contract": "StorageDownloadRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "fileitem",
+        "path"
+      ],
       "result_contract": "FileItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2358,7 +2361,9 @@
       "input_contract": "MessageFinalizeRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "response"
+      ],
       "result_contract": "Message | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2373,7 +2378,10 @@
       "input_contract": "StorageItemRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "path",
+        "storage"
+      ],
       "result_contract": "FileItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2388,7 +2396,10 @@
       "input_contract": "StorageFolderRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "path",
+        "storage"
+      ],
       "result_contract": "FileItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2403,7 +2414,9 @@
       "input_contract": "StorageParentRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "fileitem"
+      ],
       "result_contract": "FileItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2418,7 +2431,10 @@
       "input_contract": "StorageListRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "fileitem",
+        "recursion"
+      ],
       "result_contract": "list[FileItem]",
       "supports_async": true,
       "supports_sync": true,
@@ -2448,7 +2464,10 @@
       "input_contract": "MediaServerItemRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "item_id",
+        "server"
+      ],
       "result_contract": "MediaServerItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2463,7 +2482,12 @@
       "input_contract": "MediaServerItemsRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "library_id",
+        "limit",
+        "server",
+        "start_index"
+      ],
       "result_contract": "list[MediaServerItem]",
       "supports_async": true,
       "supports_sync": true,
@@ -2478,7 +2502,10 @@
       "input_contract": "MediaServerPlayRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "item_id",
+        "server"
+      ],
       "result_contract": "str | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2493,7 +2520,10 @@
       "input_contract": "MediaServerEpisodesRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "item_id",
+        "server"
+      ],
       "result_contract": "list[MediaServerPlayItem]",
       "supports_async": true,
       "supports_sync": true,
@@ -2508,7 +2538,9 @@
       "input_contract": "MediaInfo",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "mediainfo"
+      ],
       "result_contract": "MediaInfo | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2523,7 +2555,14 @@
       "input_contract": "MediaRecognitionRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "cache",
+        "episode_group",
+        "media_id",
+        "media_source",
+        "meta",
+        "mtype"
+      ],
       "result_contract": "MediaInfo | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2538,7 +2577,9 @@
       "input_contract": "CommandRegistrationRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "commands"
+      ],
       "result_contract": "None",
       "supports_async": true,
       "supports_sync": true,
@@ -2553,7 +2594,10 @@
       "input_contract": "StorageRenameRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "fileitem",
+        "name"
+      ],
       "result_contract": "bool | FileItem",
       "supports_async": true,
       "supports_sync": true,
@@ -2583,7 +2627,10 @@
       "input_contract": "MediaSearchRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "media_source",
+        "meta"
+      ],
       "result_contract": "list[MediaInfo]",
       "supports_async": true,
       "supports_sync": true,
@@ -2613,7 +2660,13 @@
       "input_contract": "StorageSnapshotRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "last_snapshot_time",
+        "max_depth",
+        "path",
+        "previous_snapshot",
+        "storage"
+      ],
       "result_contract": "dict[str, dict] | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2628,7 +2681,10 @@
       "input_contract": "StorageManageRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "action",
+        "storage"
+      ],
       "result_contract": "Any",
       "supports_async": true,
       "supports_sync": true,
@@ -2643,7 +2699,11 @@
       "input_contract": "StorageUploadRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "fileitem",
+        "new_name",
+        "path"
+      ],
       "result_contract": "FileItem | None",
       "supports_async": true,
       "supports_sync": true,
@@ -2658,7 +2718,11 @@
       "input_contract": "WebhookRequest",
       "plugin_short_circuit": true,
       "public_to_plugins": true,
-      "required_parameters": [],
+      "required_parameters": [
+        "args",
+        "body",
+        "form"
+      ],
       "result_contract": "WebhookEventInfo | None",
       "supports_async": true,
       "supports_sync": true,

tests/fixtures/architecture/transaction-debt-baseline.json

@@ -3,10 +3,10 @@
     "by_kind": {
       "async_db_query": 49,
       "async_db_update": 12,
-      "db_query": 75,
-      "db_update": 40
+      "db_query": 74,
+      "db_update": 39
     },
-    "count": 176,
+    "count": 174,
     "methods": [
       {
         "decorator": "async_db_query",
@@ -83,16 +83,6 @@
         "file": "app/db/models/downloadfailure.py",
         "method": "DownloadFailure.delete_expired"
       },
-      {
-        "decorator": "db_query",
-        "file": "app/db/models/downloadfailure.py",
-        "method": "DownloadFailure.get_active_by_fingerprints"
-      },
-      {
-        "decorator": "db_update",
-        "file": "app/db/models/downloadfailure.py",
-        "method": "DownloadFailure.record_failure"
-      },
       {
         "decorator": "db_update",
         "file": "app/db/models/downloadhistory.py",