microcoreos 0.4.4__tar.gz → 0.4.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/feature-plan.md +5 -2
  2. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/new-domain.md +12 -9
  3. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/new-tool.md +7 -2
  4. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/solo-build.md +23 -4
  5. {microcoreos-0.4.4 → microcoreos-0.4.6}/.env.example +43 -9
  6. {microcoreos-0.4.4 → microcoreos-0.4.6}/AGENTS.md +27 -5
  7. {microcoreos-0.4.4 → microcoreos-0.4.6}/AI_CONTEXT.md +173 -81
  8. {microcoreos-0.4.4 → microcoreos-0.4.6}/INSTRUCTIONS_FOR_AI.md +65 -71
  9. {microcoreos-0.4.4 → microcoreos-0.4.6}/PKG-INFO +26 -4
  10. {microcoreos-0.4.4 → microcoreos-0.4.6}/README.md +25 -3
  11. microcoreos-0.4.6/ROADMAP.md +906 -0
  12. microcoreos-0.4.4/ROADMAP.md → microcoreos-0.4.6/ROADMAP_DONE.md +87 -584
  13. {microcoreos-0.4.4 → microcoreos-0.4.6}/conftest.py +62 -1
  14. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/CLI.md +17 -0
  15. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/HTTP_SERVER.md +14 -0
  16. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/INDEX.md +6 -0
  17. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/PARALLEL_DEVELOPMENT.md +10 -8
  18. microcoreos-0.4.6/domains/devtools/plugins/system_lint_plugin.py +158 -0
  19. microcoreos-0.4.6/domains/system/plugins/event_schemas_plugin.py +163 -0
  20. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_metrics_plugin.py +4 -1
  21. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_traces_plugin.py +41 -2
  22. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_traces_stream_plugin.py +28 -1
  23. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/postgresql_tool.py +48 -38
  24. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/redis_state/redis_state_tool.py +17 -7
  25. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/catalog.py +11 -3
  26. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/cli.py +10 -5
  27. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/container.py +28 -8
  28. microcoreos-0.4.6/microcoreos/external_extras.py +571 -0
  29. microcoreos-0.4.6/microcoreos/project_agents.md +262 -0
  30. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/project_readme.md +49 -4
  31. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/scaffold.py +10 -210
  32. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/cli.py +4 -1
  33. microcoreos-0.4.6/microcoreos_dev/lint/__init__.py +18 -0
  34. microcoreos-0.4.6/microcoreos_dev/lint/checkers/__init__.py +1 -0
  35. microcoreos-0.4.6/microcoreos_dev/lint/checkers/divergence.py +152 -0
  36. microcoreos-0.4.6/microcoreos_dev/lint/checkers/doc_drift.py +116 -0
  37. microcoreos-0.4.4/domains/devtools/plugins/event_contract_linter_plugin.py → microcoreos-0.4.6/microcoreos_dev/lint/checkers/events.py +128 -190
  38. microcoreos-0.4.6/microcoreos_dev/lint/checkers/isolation.py +115 -0
  39. microcoreos-0.4.6/microcoreos_dev/lint/checkers/naming.py +103 -0
  40. microcoreos-0.4.6/microcoreos_dev/lint/checkers/routes.py +93 -0
  41. microcoreos-0.4.6/microcoreos_dev/lint/checkers/tables.py +70 -0
  42. microcoreos-0.4.6/microcoreos_dev/lint/report.py +71 -0
  43. microcoreos-0.4.6/microcoreos_dev/lint/runner.py +134 -0
  44. microcoreos-0.4.6/microcoreos_dev/lint/schema.py +53 -0
  45. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/pipeline.py +40 -0
  46. {microcoreos-0.4.4 → microcoreos-0.4.6}/pyproject.toml +2 -2
  47. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_core_purity.py +1 -1
  48. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_tool_proxy.py +38 -0
  49. microcoreos-0.4.6/tests/dev/test_lint_runner.py +151 -0
  50. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/test_pipeline.py +1 -1
  51. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_discovery_naming_linter.py +45 -55
  52. microcoreos-0.4.6/tests/linters/test_domain_isolation_linter.py +130 -0
  53. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_event_contract_linter.py +7 -11
  54. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_field_divergence_linter.py +29 -43
  55. microcoreos-0.4.6/tests/linters/test_route_collision_linter.py +93 -0
  56. microcoreos-0.4.6/tests/linters/test_system_lint_plugin.py +74 -0
  57. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_table_ownership_linter.py +9 -19
  58. microcoreos-0.4.6/tests/linters/test_tool_doc_drift_linter.py +33 -0
  59. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_event_schemas_plugin.py +32 -1
  60. microcoreos-0.4.6/tests/system/test_external_extras.py +276 -0
  61. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_system_traces_plugin.py +35 -0
  62. microcoreos-0.4.6/tests/tools/context/test_tool_signatures.py +207 -0
  63. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_pipeline.py +101 -21
  64. microcoreos-0.4.6/tests/tools/http_server/test_trusted_proxies_and_ws_origin.py +251 -0
  65. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_migrations.py +48 -0
  66. microcoreos-0.4.6/tests/tools/test_tool_setup_cleanup.py +273 -0
  67. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/context_tool.py +15 -3
  68. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/renderers.py +41 -0
  69. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/event_bus_tool.py +15 -5
  70. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/redis_streams_driver.py +27 -14
  71. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/context.py +35 -7
  72. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/http_server_tool.py +166 -10
  73. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/pipeline.py +207 -34
  74. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/migrations.py +22 -8
  75. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/sqlite_tool.py +39 -28
  76. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/system/registry_tool.py +1 -1
  77. {microcoreos-0.4.4 → microcoreos-0.4.6}/uv.lock +2 -2
  78. microcoreos-0.4.4/domains/devtools/lint/plugin_sources.py +0 -51
  79. microcoreos-0.4.4/domains/devtools/plugins/discovery_naming_linter_plugin.py +0 -118
  80. microcoreos-0.4.4/domains/devtools/plugins/domain_isolation_linter_plugin.py +0 -80
  81. microcoreos-0.4.4/domains/devtools/plugins/event_schemas_plugin.py +0 -94
  82. microcoreos-0.4.4/domains/devtools/plugins/field_divergence_linter_plugin.py +0 -178
  83. microcoreos-0.4.4/domains/devtools/plugins/route_collision_linter_plugin.py +0 -51
  84. microcoreos-0.4.4/domains/devtools/plugins/table_ownership_linter_plugin.py +0 -66
  85. microcoreos-0.4.4/domains/devtools/plugins/tool_doc_drift_linter_plugin.py +0 -74
  86. microcoreos-0.4.4/tests/linters/test_domain_isolation_linter.py +0 -90
  87. microcoreos-0.4.4/tests/linters/test_route_collision_linter.py +0 -69
  88. microcoreos-0.4.4/tests/linters/test_tool_doc_drift_linter.py +0 -53
  89. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/skills/microcoreos-architecture/SKILL.md +0 -0
  90. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/skills/microcoreos-architecture/agent.md +0 -0
  91. {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/multi-domain-plan.md +0 -0
  92. {microcoreos-0.4.4 → microcoreos-0.4.6}/.claude/settings.local.json +0 -0
  93. {microcoreos-0.4.4 → microcoreos-0.4.6}/.dockerignore +0 -0
  94. {microcoreos-0.4.4 → microcoreos-0.4.6}/.github/workflows/ci.yml +0 -0
  95. {microcoreos-0.4.4 → microcoreos-0.4.6}/.github/workflows/release.yml +0 -0
  96. {microcoreos-0.4.4 → microcoreos-0.4.6}/.gitignore +0 -0
  97. {microcoreos-0.4.4 → microcoreos-0.4.6}/.mutmut-cache +0 -0
  98. {microcoreos-0.4.4 → microcoreos-0.4.6}/.python-version +0 -0
  99. {microcoreos-0.4.4 → microcoreos-0.4.6}/Dockerfile +0 -0
  100. {microcoreos-0.4.4 → microcoreos-0.4.6}/LICENSE +0 -0
  101. {microcoreos-0.4.4 → microcoreos-0.4.6}/cli.py +0 -0
  102. {microcoreos-0.4.4 → microcoreos-0.4.6}/dev_infra/cache_probe.py +0 -0
  103. {microcoreos-0.4.4 → microcoreos-0.4.6}/dev_infra/docker-compose.yml +0 -0
  104. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/CORE_INFRASTRUCTURE.md +0 -0
  105. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/ELASTIC_DEPLOYMENT.md +0 -0
  106. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/EVENT_BUS.md +0 -0
  107. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/OBSERVABILITY.md +0 -0
  108. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/OBSERVABILITY_API.md +0 -0
  109. {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/translations/es/README.md +0 -0
  110. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/event_delivery_monitor_plugin.py +0 -0
  111. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_events_plugin.py +0 -0
  112. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_events_stream_plugin.py +0 -0
  113. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_logs_stream_plugin.py +0 -0
  114. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_status_plugin.py +0 -0
  115. {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/tool_health_plugin.py +0 -0
  116. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/blocking_boot_plugin.py +0 -0
  117. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/chaos_control_plugin.py +0 -0
  118. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/failing_plugin.py +0 -0
  119. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/stress_plugin.py +0 -0
  120. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/ping/plugins/ping_plugin.py +0 -0
  121. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/migrations/001_scheduler_one_shots.sql +0 -0
  122. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/models/scheduler_one_shot.py +0 -0
  123. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/plugins/durable_one_shots_plugin.py +0 -0
  124. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/migrations/001_create_users.sql +0 -0
  125. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/models/user.py +0 -0
  126. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/create_user_plugin.py +0 -0
  127. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/delete_user_plugin.py +0 -0
  128. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_me_plugin.py +0 -0
  129. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_user_by_id_plugin.py +0 -0
  130. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_users_plugin.py +0 -0
  131. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/login_plugin.py +0 -0
  132. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/logout_plugin.py +0 -0
  133. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/update_user_plugin.py +0 -0
  134. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/welcome_service_plugin.py +0 -0
  135. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/auth/auth_tool.py +0 -0
  136. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/auth/tests/auth_tool_test.py +0 -0
  137. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/chaos/chaos_tool.py +0 -0
  138. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/kafka/kafka_driver.py +0 -0
  139. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/tests/postgresql_describe_schema_test.py +0 -0
  140. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/tests/postgresql_tool_test.py +0 -0
  141. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/rabbitmq/rabbitmq_driver.py +0 -0
  142. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/__init__.py +0 -0
  143. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/s3_tool.py +0 -0
  144. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/tests/s3_tool_test.py +0 -0
  145. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/scheduler_tool.py +0 -0
  146. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/tests/scheduler_singleton_test.py +0 -0
  147. {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/tests/scheduler_tool_test.py +0 -0
  148. {microcoreos-0.4.4 → microcoreos-0.4.6}/hatch_build.py +0 -0
  149. {microcoreos-0.4.4 → microcoreos-0.4.6}/main.py +0 -0
  150. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/__init__.py +0 -0
  151. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/base_plugin.py +0 -0
  152. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/base_tool.py +0 -0
  153. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/context.py +0 -0
  154. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/kernel.py +0 -0
  155. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/project.py +0 -0
  156. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/registry.py +0 -0
  157. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/upgrade.py +0 -0
  158. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/__init__.py +0 -0
  159. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/fuzzer.py +0 -0
  160. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/__init__.py +0 -0
  161. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/rules.py +0 -0
  162. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/scan.py +0 -0
  163. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/schema.py +0 -0
  164. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/sync.py +0 -0
  165. {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/probe.py +0 -0
  166. {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/README.md +0 -0
  167. {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/active_plan.md +0 -0
  168. {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/active_plan.yaml +0 -0
  169. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_core.py +0 -0
  170. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_kernel.py +0 -0
  171. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_no_retry.py +0 -0
  172. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_plugin_di_fixtures.py +0 -0
  173. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_registry_collisions.py +0 -0
  174. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/corpus/README.md +0 -0
  175. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/corpus/qwen_twitter_plan.yaml +0 -0
  176. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/test_plan_validator.py +0 -0
  177. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/ping/test_ping_plugin.py +0 -0
  178. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_create_user_plugin.py +0 -0
  179. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_delete_user_plugin.py +0 -0
  180. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_me_plugin.py +0 -0
  181. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_user_by_id_plugin.py +0 -0
  182. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_users_plugin.py +0 -0
  183. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_login_plugin.py +0 -0
  184. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_logout_plugin.py +0 -0
  185. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_update_user_plugin.py +0 -0
  186. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_welcome_service_plugin.py +0 -0
  187. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/active_db.py +0 -0
  188. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/async_wait.py +0 -0
  189. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/mock_db.py +0 -0
  190. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/trace_chains.py +0 -0
  191. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_catalog.py +0 -0
  192. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_chaos_control.py +0 -0
  193. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_chaos_tool.py +0 -0
  194. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_cli.py +0 -0
  195. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_durable_one_shots.py +0 -0
  196. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_scaffold.py +0 -0
  197. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_system_events_stats.py +0 -0
  198. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_trace_chain_helper.py +0 -0
  199. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_upgrade.py +0 -0
  200. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/config/test_config_tool.py +0 -0
  201. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/context/test_context_tool.py +0 -0
  202. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/db/test_db_parity.py +0 -0
  203. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_broker_parity.py +0 -0
  204. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_groups.py +0 -0
  205. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_kafka_parity.py +0 -0
  206. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_rabbitmq_parity.py +0 -0
  207. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_tool.py +0 -0
  208. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_redis_streams_driver.py +0 -0
  209. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_params_hardening.py +0 -0
  210. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_server_tool.py +0 -0
  211. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_security_hardening.py +0 -0
  212. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/logger/test_logger_tool.py +0 -0
  213. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/registry/test_registry_tool.py +0 -0
  214. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/s3/test_s3_parity.py +0 -0
  215. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_concurrency.py +0 -0
  216. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_describe_schema.py +0 -0
  217. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_driver.py +0 -0
  218. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_tool.py +0 -0
  219. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/state/test_state_parity.py +0 -0
  220. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/state/test_state_tool.py +0 -0
  221. {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/telemetry/test_telemetry_tool.py +0 -0
  222. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/config/config_tool.py +0 -0
  223. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/authoring_guide.md +0 -0
  224. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/scanners.py +0 -0
  225. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/drivers.py +0 -0
  226. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/envelope.py +0 -0
  227. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/sqlite_driver.py +0 -0
  228. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/types.py +0 -0
  229. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/logger/logger_tool.py +0 -0
  230. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/errors.py +0 -0
  231. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/transaction.py +0 -0
  232. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/state/state_tool.py +0 -0
  233. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/telemetry/__init__.py +0 -0
  234. {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/telemetry/telemetry_tool.py +0 -0
@@ -105,8 +105,11 @@ Publish with `XxxPayload(...).model_dump()` — bare call, no arguments.
105
105
 
106
106
  - One test per plugin proving the black-box contract: input → output, DB
107
107
  effects on the declared tables, published payloads with the declared fields.
108
- Mock exactly the tools the plan's `tools:` lists; run the rest as real
109
- in-memory instances (`INSTRUCTIONS_FOR_AI.md` § Testing).
108
+ Use the generated `db` fixture with `@pytest.mark.migrations("{domain}")`
109
+ for persisted rows, and real event/state fixtures for delivery/state effects.
110
+ Mock only branch logic and controlled failures, not the persistence being
111
+ asserted (`INSTRUCTIONS_FOR_AI.md` § Testing). Save tests at the plan's
112
+ declared paths; tool dependencies are not a list of tools to mock.
110
113
  - One double-delivery test per idempotent link (same envelope twice → same
111
114
  final state), at the path declared in `idempotency_test`.
112
115
  - One chain test per flow, using the helper:
@@ -159,9 +159,12 @@ microcoreos # or: uv run main.py (identical) — Ctrl-C when done
159
159
 
160
160
  ### 6. Generate tests
161
161
 
162
- Create `tests/test_{name}_plugin.py` with one test per plugin. Mock exactly
163
- the tools the plan's `tools:` field lists; run the rest as real in-memory
164
- instances (`INSTRUCTIONS_FOR_AI.md` § Testing).
162
+ Create each plugin's test at the exact `test:` path declared by the plan.
163
+ Use the generated `db` fixture and `@pytest.mark.migrations("{domain}")` for
164
+ persistence assertions, and real event/state fixtures for delivery/state effects.
165
+ Use mocks for branch logic and controlled failures, not as evidence of persisted
166
+ rows (`INSTRUCTIONS_FOR_AI.md` § Testing). The example below tests only the
167
+ handler's returned result and error handling.
165
168
 
166
169
  **Configure the method, not the mock.** A plugin awaits `self.db.execute(...)`,
167
170
  never `self.db(...)` — so `AsyncMock(return_value=1)` and
@@ -198,10 +201,10 @@ async def test_create_{name}_db_error():
198
201
  assert "DB down" not in result["error"] # Safe Errors: technical detail never reaches the client
199
202
  ```
200
203
 
201
- `pytest.mark.anyio` needs an `anyio_backend` fixture; the generated
202
- the generated root `conftest.py` already ships one, along with `mock_logger` and
203
- `mock_state`. The richer alternative — the real db tool with this domain's
204
- migrations applied, asserting on rows instead of on mock calls — is the
205
- black-box style of `tests/domains/users/test_create_user_plugin.py`.
204
+ `pytest.mark.anyio` needs an `anyio_backend` fixture; the generated root
205
+ `conftest.py` already ships one, along with `mock_logger` and `mock_state`.
206
+ For persistence, copy the complete fixture-based example in
207
+ `INSTRUCTIONS_FOR_AI.md` § Black-Box Integration Testing. Framework tests under
208
+ `tests/domains/users/` are not shipped to generated applications.
206
209
 
207
- Run with `uv run -m pytest tests/test_{name}_plugin.py`.
210
+ Run `uv run -m pytest` with the plan's exact `test:` path.
@@ -65,8 +65,13 @@ No imports from other tools, no plugin imports, stateless where possible.
65
65
 
66
66
  The same test battery runs against the reference implementation AND yours:
67
67
 
68
- - Canonical examples: `tests/tools/state/test_state_parity.py`,
69
- `tests/tools/event_bus/test_event_bus_broker_parity.py` (parameterized over transports).
68
+ - Framework-maintainer examples (in the framework repository, not shipped to
69
+ generated applications): `tests/tools/state/test_state_parity.py` and
70
+ `tests/tools/event_bus/test_event_bus_broker_parity.py`.
71
+ - In an application repository, create the parity suite locally: parameterize
72
+ the same contract assertions over reference and replacement implementations,
73
+ isolate their state, and exercise success, failure and cleanup behavior.
74
+ Do not assume the framework's test files exist in the scaffold.
70
75
  - If the backend needs a server, the suite skips itself when unavailable and
71
76
  the server is added to CI services (`dev_infra/docker-compose.yml`).
72
77
  - **A replacement that does not pass the reference's parity suite is not a
@@ -58,7 +58,9 @@ For each feature declared in `features:`:
58
58
  2. **Write its Test**: `tests/domains/{domain}/test_{feature}_plugin.py`.
59
59
  - Black-box integration tests using `@pytest.mark.migrations("{domain}")`.
60
60
  - Assert status codes, response envelope, and DB side effects.
61
- 3. **Mark Checklist**: Check off the task in `plans/active_plan.md`.
61
+ 3. **Track implementation**: Keep verification checkboxes pending in
62
+ `plans/active_plan.md` until the corresponding tests and gates pass.
63
+ Writing the files is not proof that the feature works.
62
64
 
63
65
  ---
64
66
 
@@ -67,8 +69,25 @@ For each feature declared in `features:`:
67
69
  ```bash
68
70
  uv run -m pytest
69
71
  ```
70
- 2. **Boot verification**:
72
+ 2. **Run the offline architecture gate**:
71
73
  ```bash
72
- microcoreos migrate # regenerates AI_CONTEXT.md and validates system integrity
74
+ microcoreos check --strict
73
75
  ```
74
- 3. Done!
76
+ Resolve errors and warnings; migration success does not replace this check.
77
+ 3. **Refresh and compare the manifest**:
78
+ ```bash
79
+ microcoreos migrate
80
+ microcoreos schema
81
+ microcoreos status
82
+ ```
83
+ Confirm that tables, routes, events and tool interfaces match the plan and
84
+ that the manifest is fresh. These commands terminate; they do not prove
85
+ that the HTTP endpoints behave correctly.
86
+ 4. **Final runtime verification**: After the offline gates pass, start
87
+ `microcoreos` for the final integration check. Verify `GET /system/lint`
88
+ is clean and exercise the endpoints/events declared by the plan. Stop the
89
+ server with Ctrl-C when finished; do not leave a background server running.
90
+ If runtime verification cannot run, record the blocker rather than claiming
91
+ it passed. Likewise, report skipped infrastructure tests explicitly.
92
+ 5. **Close the checklist**: Mark only verified tasks/gates as complete in
93
+ `plans/active_plan.md`. Report commands, results and remaining limitations.
@@ -12,25 +12,59 @@
12
12
  # │ HTTP SERVER tools/http_server │
13
13
  # ╰────────────────────────────────────────────────────────────────────────────╯
14
14
 
15
+ # Port where the HTTP server listens.
15
16
  HTTP_PORT=5000
16
17
 
17
- # Bind address. Default: 127.0.0.1 (dev-safe).
18
- # PRODUCTION / DOCKER: must be 0.0.0.0 or the service refuses external connections.
18
+ # Bind network interface.
19
+ # Default: 127.0.0.1 (local machine only, dev-safe).
20
+ # PRODUCTION / DOCKER: set to 0.0.0.0 so external traffic or Docker port maps can reach the service.
19
21
  # HTTP_HOST=0.0.0.0
20
22
 
21
- # CORS allowed origins. Default: * (dev-friendly).
22
- # Production: your actual frontend domain(s), comma-separated.
23
+ # CORS (Cross-Origin Resource Sharing): Allowed frontend origins for browser API calls.
24
+ # Default: * (accepts all origins for zero-friction local development).
25
+ # PRODUCTION: Comma-separated list of your actual frontend URL(s).
23
26
  # HTTP_CORS_ORIGINS=https://app.example.com,https://admin.example.com
24
27
 
25
- # Let cross-origin requests carry cookies. Default: false. Needed only when a
26
- # browser app on ANOTHER origin authenticates by cookie instead of by Bearer
27
- # token. Requires an explicit HTTP_CORS_ORIGINS list — the tool refuses to boot
28
- # with '*', which would authorize every site to send the session cookie.
28
+ # Allow cross-origin requests to send session cookies.
29
+ # Default: false (not needed if your frontend uses "Authorization: Bearer <token>").
30
+ # IMPORTANT: When set to true, browsers prohibit the wildcard '*'.
31
+ # The server will refuse to boot unless HTTP_CORS_ORIGINS defines explicit domain(s).
29
32
  # HTTP_CORS_CREDENTIALS=true
30
33
 
31
- # Uvicorn log level. Default: warning. Set to info for HTTP access logs.
34
+ # Uvicorn server log level. Options: debug | info | warning | error.
35
+ # Default: warning (quiet; shows errors only). Set to 'info' to log every incoming HTTP request.
32
36
  # HTTP_LOG_LEVEL=info
33
37
 
38
+ # Trusted reverse proxies for client IP resolution (context.client_ip).
39
+ # Default: * (trusts all local proxies such as Vite dev server, Next.js proxy, or Docker bridge).
40
+ # PRODUCTION: Replace '*' with the explicit IPs or CIDR blocks of your reverse proxy or load balancer
41
+ # (e.g. 10.0.0.0/8, 172.16.0.0/12). If direct internet callers connect to 0.0.0.0 while '*' is active,
42
+ # an attacker can spoof X-Forwarded-For headers.
43
+ HTTP_TRUSTED_PROXIES=*
44
+
45
+ # Custom edge client IP header from trusted reverse proxies or CDNs.
46
+ # Default: empty (uses the standard X-Forwarded-For chain).
47
+ # Examples: X-Real-IP, True-Client-IP, CF-Connecting-IP.
48
+ # Only evaluated if the connecting peer matches an IP/CIDR in HTTP_TRUSTED_PROXIES.
49
+ # HTTP_CUSTOM_CLIENT_IP_HEADER=X-Real-IP
50
+
51
+ # WebSocket Origin validation policy. Options: off | allowlist.
52
+ # Default: off (accepts WebSocket connections from any origin, standard dev behavior).
53
+ # PRODUCTION: Set to 'allowlist' to protect browser WebSockets against Cross-Site WebSocket Hijacking (CSWSH).
54
+ # In allowlist mode, unauthorized origins are closed immediately with code 1008 before handshake or auth.
55
+ # HTTP_WS_ORIGIN_POLICY=off
56
+
57
+ # Allowed WebSocket origins when HTTP_WS_ORIGIN_POLICY=allowlist.
58
+ # Comma-separated list of explicit origins with scheme and port if non-standard (e.g. http://localhost:3000).
59
+ # No wildcards allowed.
60
+ # HTTP_WS_ORIGINS=http://localhost:3000,https://app.example.com
61
+
62
+ # Behavior when a WebSocket client does not send an 'Origin' header in allowlist mode.
63
+ # Default: false (rejects connections without an Origin header).
64
+ # Browsers always send an Origin header, but native mobile apps, Postman, or CLI tools might omit it.
65
+ # Set to true if you need to support non-browser WebSocket clients alongside browser clients.
66
+ # HTTP_WS_ALLOW_MISSING_ORIGIN=false
67
+
34
68
  # ╭────────────────────────────────────────────────────────────────────────────╮
35
69
  # │ DATABASE — SQLite tools/sqlite │
36
70
  # ╰────────────────────────────────────────────────────────────────────────────╯
@@ -4,6 +4,25 @@ This file is the single, absolute entry point for any AI agent (Gemini, Claude,
4
4
 
5
5
  ---
6
6
 
7
+ ## 🛠️ Maintainer Mandate: Framework Core vs Downstream Application Guides
8
+
9
+ You are working in the **MicroCoreOS framework repository**.
10
+
11
+ ### 1. Two Guides, Two Audiences
12
+ - **`AGENTS.md` (this file)**: The guide for AI agents developing the **MicroCoreOS Framework itself** (Kernel, Base Tools, Devtools, CLI, Packaging).
13
+ - **`microcoreos/project_agents.md`**: The template guide shipped into downstream user applications created via `microcoreos new`.
14
+
15
+ ### 2. Synchronization Rule (MANDATORY)
16
+ Whenever you introduce, update, or refactor:
17
+ - Application conventions or rules (plugins, event contracts, HTTP endpoints, auth validators, DI)
18
+ - CLI commands intended for application developers (`microcoreos plan validate`, `migrate`, `check`, `schema`, `add`)
19
+ - Testing patterns, fixtures, or mocks in `conftest.py`
20
+
21
+ **YOU MUST KEEP `microcoreos/project_agents.md` UPDATED IN LOCKSTEP.**
22
+ Never let `microcoreos/project_agents.md` drift from the canonical application patterns. Any change to how developers or their agents write apps must immediately be reflected in `microcoreos/project_agents.md`.
23
+
24
+ ---
25
+
7
26
  ## 🚦 Start here: `microcoreos status`
8
27
 
9
28
  One command, before anything else. It answers the three questions that
@@ -83,7 +102,7 @@ reviews a real file rather than a description of one.
83
102
  | Planner | `microcoreos status`, `microcoreos plan validate` |
84
103
  | Phase 0 Builder | `microcoreos migrate`, `microcoreos schema` |
85
104
  | Executor | none — write your two files and stop |
86
- | Coordinator | `uv run -m pytest`, `microcoreos status`, and `microcoreos` (the real boot) for the final lint |
105
+ | Coordinator | `uv run -m pytest`, `microcoreos check`, `microcoreos status`, and `microcoreos` (the real boot) for the final lint |
87
106
  | Solo | All of the above — but each in its phase, and the real boot only at the end |
88
107
 
89
108
  **Never `microcoreos run` / `uv run main.py` outside that last row.** It serves
@@ -136,6 +155,7 @@ The plan pipeline — prefix with `uv run` if the package is installed in a venv
136
155
  ```bash
137
156
  microcoreos status # Active plan, progress, manifest freshness
138
157
  microcoreos plan validate # The 18 plan rules, OFFLINE (no server, no jq, no curl)
158
+ microcoreos check # The 7 architecture linters, OFFLINE (--strict, --format=json)
139
159
  microcoreos migrate # Apply migrations AND regenerate AI_CONTEXT.md
140
160
  microcoreos schema # The live tables and columns, read by the db tool itself
141
161
  ```
@@ -222,11 +242,13 @@ When writing a new feature, read these specific files under demand to copy their
222
242
  | **Minimal Plugin (No DB)** | `extras/available_domains/ping/plugins/ping_plugin.py` |
223
243
  | **Database Migrations** | `extras/available_domains/users/migrations/001_create_users.sql` |
224
244
  | **Dynamic Introspection** | `domains/system/plugins/system_status_plugin.py` |
225
- | **Black-Box Integration Tests** | `tests/domains/users/test_login_plugin.py` |
245
+ | **Black-Box Integration Tests** | `INSTRUCTIONS_FOR_AI.md` § Black-Box Integration Testing — complete fixture-based example |
226
246
 
227
- Both point into `extras/` because both are extras: readable in any project,
228
- and `microcoreos add auth` / `add ping` is what moves them into `domains/`.
229
- Reading them needs no install — the files are there either way.
247
+ Plugin and migration examples under `extras/` are readable in generated
248
+ projects; `microcoreos add auth` / `add ping` installs the corresponding extra.
249
+ The testing example is embedded in the shipped guide and states its install
250
+ prerequisites. Framework-repository tests such as `tests/domains/users/` and
251
+ `tests/core/` are maintainer references, not files shipped by `microcoreos new`.
230
252
 
231
253
  ---
232
254
 
@@ -15,7 +15,106 @@ For plugin development guides, critical rules, and syntax examples, see [AGENTS.
15
15
  ## 🛠️ Available Tools
16
16
  Check method signatures before implementation.
17
17
 
18
+ ### 🔧 Tool: `config` (Status: ✅)
19
+
20
+ **Public Signatures:**
21
+ ```python
22
+ def get(key: str, default: Optional[str] = None, required: bool = False) -> Optional[str]
23
+ def require(*keys: str) -> None
24
+ ```
25
+
26
+ ```text
27
+ Configuration Tool (config):
28
+ - PURPOSE: Validated access to environment variables for plugins.
29
+ Tools read their own env vars with os.getenv() — this tool is for plugins.
30
+ - CAPABILITIES:
31
+ - get(key, default=None, required=False) -> str | None:
32
+ Returns the value of the environment variable.
33
+ If required=True and the variable is not set, raises EnvironmentError.
34
+ - require(*keys) -> None:
35
+ Validates that all specified variables are set.
36
+ Call in on_boot() to fail early with a clear error message.
37
+ Example: self.config.require("STRIPE_KEY", "SENDGRID_KEY")
38
+ ```
39
+
40
+ ### 🔧 Tool: `event_bus` (Status: ✅)
41
+
42
+ **Public Signatures:**
43
+ ```python
44
+ def add_failure_listener(cb)
45
+ def add_listener(cb)
46
+ def get_subscribers() -> dict
47
+ def get_trace_history() -> List[tools.event_bus.envelope.TraceNode]
48
+ async def publish(event_name: str, data: dict, **kwargs)
49
+ async def request(event_name: str, data: dict, timeout: float = 5)
50
+ async def subscribe(event_name: str, callback: Callable, group: Optional[str] = None, retries: int = 0, backoff: float = 0.5, broadcast: bool = False)
51
+ async def unsubscribe(event_name: str, callback: Callable)
52
+ ```
53
+
54
+ ```text
55
+ Universal Event Bus (event_bus):
56
+ - publish(event_name, data, **kwargs): Broadcast an event.
57
+ - subscribe(event_name, callback, group=None, retries=0, backoff=0.5, broadcast=False):
58
+ Listen for events. group=None derives a STABLE group from the callback identity:
59
+ replicas of the same plugin consume each event exactly once across the fleet,
60
+ while distinct plugins each get their own copy. Use group="pool" for explicit
61
+ worker pools, broadcast=True ONLY for instance-local concerns (every replica
62
+ receives a copy — e.g. local cache invalidation).
63
+ - request(event_name, data, timeout=5): Async RPC (returns dict).
64
+ - unsubscribe(event_name, callback): Stop listening.
65
+ - get_trace_history() -> List[TraceNode]: Last 500 event records.
66
+ - get_subscribers() -> dict: Current subscriber map.
67
+ - add_listener(callback): Sink for all events (record: dict).
68
+ - add_failure_listener(callback): Sink for errors (record: dict).
69
+
70
+ CRITICAL: Subscribing callbacks receive the event envelope as their single
71
+ argument — read event.payload. Leave the parameter untyped (no annotation,
72
+ no import needed): async def on_event(self, event): print(event.payload)
73
+
74
+ RETRIES & IDEMPOTENCY:
75
+ - If 'retries' > 0, the handler will be re-executed on failure with exponential backoff.
76
+ - Ensure handlers are idempotent as they may run multiple times.
77
+
78
+ DEAD-LETTER QUEUE (DLQ):
79
+ - Final failures are published to '_dlq.<original_event>'.
80
+ - Payload includes 'original' envelope, 'subscriber', 'error', and 'attempts'.
81
+ - Loop protection: '_dlq.*' and '_reply.*' events are never dead-lettered.
82
+ - Toggle via EVENT_BUS_DLQ_ENABLED (default: true).
83
+
84
+ UNIVERSAL CAPABILITIES (kwargs):
85
+ - key: String. Strict ordering PER KEY. Without a key, do NOT assume
86
+ cross-event ordering: it varies by transport (total in-process,
87
+ partition-dependent on Kafka).
88
+ - priority: Integer (1-10). Importance (RabbitMQ).
89
+ - delay: Integer (seconds). Delivery schedule. Crash-safe only when
90
+ the active transport claims delay=native (see ACTIVE TRANSPORT).
91
+ - ttl: Float (seconds). Message expiration hint. Counted from PUBLISH
92
+ time and therefore INCLUDES any delay (delay=60 + ttl=30 expires
93
+ before it can ever be delivered).
94
+ - correlation_id: String. Cross-reference for RPC.
95
+
96
+ RESILIENCE:
97
+ - A subscriber that reaches 5 consecutive FINAL failures for a specific event is auto-unsubscribed.
98
+ - Each auto-unsubscribe publishes 'system.subscriber.dropped'
99
+ (payload: event, subscriber, error, consecutive_failures) so the drop
100
+ is observable — subscribe to it for alerting/monitoring.
101
+
102
+ ACTIVE TRANSPORT: InProcessDriver — capability claims: {'delay': 'in_bus', 'retries': 'in_bus', 'dlq': 'in_bus'}
103
+ ("native" = the broker implements it, crash-safe; "in_bus" = software
104
+ fallback in this process' memory).
105
+ ```
106
+
18
107
  ### 🔧 Tool: `http` (Status: ✅)
108
+
109
+ **Public Signatures:**
110
+ ```python
111
+ def add_endpoint(path: str, method: str, handler: Callable, tags: Optional[list] = None, request_model=None, response_model=None, auth_validator: Optional[Callable] = None, has_files: bool = False) -> None
112
+ def add_sse_endpoint(path: str, generator: Callable, tags: Optional[list] = None, auth_validator: Optional[Callable] = None) -> None
113
+ def add_ws_endpoint(path: str, on_connect: Callable, on_disconnect: Optional[Callable] = None, auth_validator: Optional[Callable] = None) -> None
114
+ def mount_static(path: str, directory_path: str, html: bool = False, allow_extensions: Optional[set] = None, optional: bool = False) -> None
115
+ def register_pre_mount_hook(hook: Callable[[list[dict]], NoneType]) -> None
116
+ ```
117
+
19
118
  ```text
20
119
  HTTP Server Tool (http):
21
120
  - PURPOSE: FastAPI-powered HTTP gateway. Supports REST, static files, WebSockets and SSE.
@@ -28,6 +127,11 @@ HTTP Server Tool (http):
28
127
  - SECURITY DEFAULTS:
29
128
  - Cookies set via context.set_cookie are 'Secure=True', 'HttpOnly=True', 'SameSite=Lax'.
30
129
  - CSRF Guard: Mutations (POST/PUT/DELETE) using cookie auth REQUIRE 'X-Requested-With' header.
130
+ - WebSocket Origin Policy: Configurable via HTTP_WS_ORIGIN_POLICY=off|allowlist.
131
+ In allowlist mode, connections from unlisted origins are closed with 1008 before handshake.
132
+ - Trusted Proxies: Forwarding headers (X-Forwarded-For or custom edge header)
133
+ are only evaluated if the direct peer is in HTTP_TRUSTED_PROXIES. Otherwise direct peer IP
134
+ is used. An optional custom edge header is configurable via HTTP_CUSTOM_CLIENT_IP_HEADER.
31
135
  - Swagger UI (/docs): endpoints with auth_validator show a lock icon and accept
32
136
  tokens via the "Authorize" button (documentation-only; real check unaffected).
33
137
  - CAPABILITIES:
@@ -46,6 +150,7 @@ HTTP Server Tool (http):
46
150
  - add_ws_endpoint(path, on_connect, on_disconnect=None, auth_validator=None):
47
151
  WebSocket support. on_connect receives a WebSocketConnection: send_text,
48
152
  send_json, receive_text, receive_json, close, query_params, path_params.
153
+ WebSocket Origin policy (HTTP_WS_ORIGIN_POLICY) is enforced first.
49
154
  With auth_validator the token is read from the Authorization header, the
50
155
  `token` query param, then the access_token cookie; an invalid one is
51
156
  closed with 1008 BEFORE the handshake and on_connect takes (conn, payload).
@@ -63,32 +168,29 @@ HTTP Server Tool (http):
63
168
  - context.set_cookie(key, value, max_age=3600, ...): Set secure response cookie.
64
169
  - context.set_header(key, value): Add custom response header.
65
170
  - context.set_binary_response(content: bytes, media_type: str): Return raw file.
66
- - context.client_ip: Best-effort caller IP (property). Raw signal only — the
67
- plugin decides what to do with it (e.g. state.increment() keyed by IP for
68
- an identity-aware business rule). Never security-authoritative on its own;
69
- see context.py's client_ip docstring for the trust order and its limits.
171
+ - context.raw_body: Exact inbound HTTP request body bytes. Use for webhook
172
+ signature verification; providers sign bytes, not a re-serialized dict.
173
+ - context.get_header(key, default=None): Read inbound request headers
174
+ case-insensitively (e.g. X-Signature for signed webhooks).
175
+ - context.client_ip: Best-effort caller IP (property). Resolved against
176
+ HTTP_TRUSTED_PROXIES (no trust by default). Direct callers cannot spoof
177
+ forwarding headers. When proxied, right-to-left X-Forwarded-For evaluation
178
+ determines the first untrusted caller. Custom edge header configurable via
179
+ HTTP_CUSTOM_CLIENT_IP_HEADER. Never security-authoritative on its own.
70
180
  - RESPONSE CONTRACT:
71
181
  - Standard: return {"success": bool, "data": ..., "error": ...}
72
182
  - WARNING: All values in 'data' must be JSON-serializable. Pydantic model
73
183
  instances are NOT serializable — always call .model_dump() before returning.
74
184
  ```
75
185
 
76
- ### 🔧 Tool: `config` (Status: ✅)
77
- ```text
78
- Configuration Tool (config):
79
- - PURPOSE: Validated access to environment variables for plugins.
80
- Tools read their own env vars with os.getenv() — this tool is for plugins.
81
- - CAPABILITIES:
82
- - get(key, default=None, required=False) -> str | None:
83
- Returns the value of the environment variable.
84
- If required=True and the variable is not set, raises EnvironmentError.
85
- - require(*keys) -> None:
86
- Validates that all specified variables are set.
87
- Call in on_boot() to fail early with a clear error message.
88
- Example: self.config.require("STRIPE_KEY", "SENDGRID_KEY")
186
+ ### 🔧 Tool: `telemetry` (Status: ✅)
187
+
188
+ **Public Signatures:**
189
+ ```python
190
+ def get_meter(scope: str)
191
+ def get_tracer(scope: str)
89
192
  ```
90
193
 
91
- ### 🔧 Tool: `telemetry` (Status: ✅)
92
194
  ```text
93
195
  Telemetry Tool (telemetry):
94
196
  - PURPOSE: OpenTelemetry distributed tracing AND metrics. Auto-instruments all tool
@@ -123,60 +225,6 @@ Telemetry Tool (telemetry):
123
225
  uv add opentelemetry-sdk opentelemetry-exporter-otlp
124
226
  ```
125
227
 
126
- ### 🔧 Tool: `event_bus` (Status: ✅)
127
- ```text
128
- Universal Event Bus (event_bus):
129
- - publish(event_name, data, **kwargs): Broadcast an event.
130
- - subscribe(event_name, callback, group=None, retries=0, backoff=0.5, broadcast=False):
131
- Listen for events. group=None derives a STABLE group from the callback identity:
132
- replicas of the same plugin consume each event exactly once across the fleet,
133
- while distinct plugins each get their own copy. Use group="pool" for explicit
134
- worker pools, broadcast=True ONLY for instance-local concerns (every replica
135
- receives a copy — e.g. local cache invalidation).
136
- - request(event_name, data, timeout=5): Async RPC (returns dict).
137
- - unsubscribe(event_name, callback): Stop listening.
138
- - get_trace_history() -> List[TraceNode]: Last 500 event records.
139
- - get_subscribers() -> dict: Current subscriber map.
140
- - add_listener(callback): Sink for all events (record: dict).
141
- - add_failure_listener(callback): Sink for errors (record: dict).
142
-
143
- CRITICAL: Subscribing callbacks receive the event envelope as their single
144
- argument — read event.payload. Leave the parameter untyped (no annotation,
145
- no import needed): async def on_event(self, event): print(event.payload)
146
-
147
- RETRIES & IDEMPOTENCY:
148
- - If 'retries' > 0, the handler will be re-executed on failure with exponential backoff.
149
- - Ensure handlers are idempotent as they may run multiple times.
150
-
151
- DEAD-LETTER QUEUE (DLQ):
152
- - Final failures are published to '_dlq.<original_event>'.
153
- - Payload includes 'original' envelope, 'subscriber', 'error', and 'attempts'.
154
- - Loop protection: '_dlq.*' and '_reply.*' events are never dead-lettered.
155
- - Toggle via EVENT_BUS_DLQ_ENABLED (default: true).
156
-
157
- UNIVERSAL CAPABILITIES (kwargs):
158
- - key: String. Strict ordering PER KEY. Without a key, do NOT assume
159
- cross-event ordering: it varies by transport (total in-process,
160
- partition-dependent on Kafka).
161
- - priority: Integer (1-10). Importance (RabbitMQ).
162
- - delay: Integer (seconds). Delivery schedule. Crash-safe only when
163
- the active transport claims delay=native (see ACTIVE TRANSPORT).
164
- - ttl: Float (seconds). Message expiration hint. Counted from PUBLISH
165
- time and therefore INCLUDES any delay (delay=60 + ttl=30 expires
166
- before it can ever be delivered).
167
- - correlation_id: String. Cross-reference for RPC.
168
-
169
- RESILIENCE:
170
- - A subscriber that reaches 5 consecutive FINAL failures for a specific event is auto-unsubscribed.
171
- - Each auto-unsubscribe publishes 'system.subscriber.dropped'
172
- (payload: event, subscriber, error, consecutive_failures) so the drop
173
- is observable — subscribe to it for alerting/monitoring.
174
-
175
- ACTIVE TRANSPORT: InProcessDriver — capability claims: {'delay': 'in_bus', 'retries': 'in_bus', 'dlq': 'in_bus'}
176
- ("native" = the broker implements it, crash-safe; "in_bus" = software
177
- fallback in this process' memory).
178
- ```
179
-
180
228
  ### 🔧 Tool: `context_manager` (Status: ✅)
181
229
  ```text
182
230
  Context Manager Tool (context_manager):
@@ -191,6 +239,15 @@ Context Manager Tool (context_manager):
191
239
  ```
192
240
 
193
241
  ### 🔧 Tool: `logger` (Status: ✅)
242
+
243
+ **Public Signatures:**
244
+ ```python
245
+ def add_sink(callback: Callable[[str, str, str], NoneType])
246
+ def error(message: str)
247
+ def info(message: str)
248
+ def warning(message: str)
249
+ ```
250
+
194
251
  ```text
195
252
  Logging Tool (logger):
196
253
  - PURPOSE: Record system events and business activity for audit and debugging.
@@ -205,6 +262,19 @@ Logging Tool (logger):
205
262
  ```
206
263
 
207
264
  ### 🔧 Tool: `state` (Status: ✅)
265
+
266
+ **Public Signatures:**
267
+ ```python
268
+ async def clear(namespace: str = 'default') -> None
269
+ async def delete(key: str, namespace: str = 'default') -> None
270
+ async def get(key: str, default=None, namespace: str = 'default')
271
+ async def get_all(namespace: str = 'default') -> dict
272
+ async def has(key: str, namespace: str = 'default') -> bool
273
+ async def increment(key: str, amount: int | float = 1, namespace: str = 'default', ttl: float | None = None) -> int | float
274
+ async def keys(namespace: str = 'default') -> list
275
+ async def set(key: str, value, namespace: str = 'default', ttl: float | None = None) -> None
276
+ ```
277
+
208
278
  ```text
209
279
  Key-Value State Tool (state):
210
280
  - PURPOSE: Share volatile global data between plugins safely.
@@ -226,6 +296,16 @@ Key-Value State Tool (state):
226
296
  ```
227
297
 
228
298
  ### 🔧 Tool: `registry` (Status: ✅)
299
+
300
+ **Public Signatures:**
301
+ ```python
302
+ def add_metrics_sink(callback)
303
+ def get_domain_metadata() -> dict
304
+ def get_metrics() -> list
305
+ def get_system_dump() -> dict
306
+ def update_tool_status(name: str, status: str, message: str = None)
307
+ ```
308
+
229
309
  ```text
230
310
  Systems Registry Tool (registry):
231
311
  - PURPOSE: Introspection and discovery of the system's architecture at runtime.
@@ -253,7 +333,7 @@ Systems Registry Tool (registry):
253
333
  A tool that silently stopped responding may still show "OK".
254
334
  - get_domain_metadata() -> dict: Detailed analysis of models and schemas.
255
335
  - get_metrics() -> list[dict]: Last 1000 tool call records.
256
- Each record: {tool, method, duration_ms, success, timestamp}.
336
+ Each record: {caller, event_id, tool, method, duration_ms, success, error, timestamp}.
257
337
  Use to build /system/metrics or feed into an observability sink.
258
338
  - add_metrics_sink(callback): Register a sink for real-time metric records.
259
339
  Signature: callback(record: dict).
@@ -264,6 +344,18 @@ Systems Registry Tool (registry):
264
344
  ```
265
345
 
266
346
  ### 🔧 Tool: `db` (Status: ✅)
347
+
348
+ **Public Signatures:**
349
+ ```python
350
+ async def describe_schema() -> dict
351
+ async def execute(sql: str, params: list | None = None) -> int | None
352
+ async def execute_many(sql: str, params_list: list[list]) -> None
353
+ async def health_check() -> bool
354
+ async def query(sql: str, params: list | None = None) -> list[dict]
355
+ async def query_one(sql: str, params: list | None = None) -> dict | None
356
+ def transaction() -> tools.sqlite.transaction.Transaction
357
+ ```
358
+
267
359
  ```text
268
360
  Async SQLite Persistence Tool (sqlite):
269
361
  - PURPOSE: PostgreSQL-compatible relational storage (drop-in swap at the
@@ -314,28 +406,28 @@ Async SQLite Persistence Tool (sqlite):
314
406
  ### `devtools`
315
407
  - **Tables**: none
316
408
  - **Endpoints**:
317
- - `GET /system/events/schemas`
318
- - **res**: EventSchemasData(schemas: dict)
319
409
  - `GET /system/lint`
320
- - **res**: SystemLintData(arch_violations: list[str], drift_warnings: list[str], event_contract_violations: list[LintFinding(code: str, severity: str, event: Optional[str], publisher: Optional[str], consumer: Optional[str], detail: str)], route_collisions: list[str], table_ownership_warnings: list[str], field_divergence_warnings: list[str], dead_path_warnings: list[str])
410
+ - **res**: SystemLintData(discovery_naming_violations: list[str], arch_violations: list[str], drift_warnings: list[str], event_contract_violations: list[LintFinding(code: str, severity: str, event: Optional[str], publisher: Optional[str], consumer: Optional[str], detail: str)], route_collisions: list[str], table_ownership_warnings: list[str], field_divergence_warnings: list[str], dead_path_warnings: list[str])
321
411
  - **Events emitted**: none
322
412
  - **Events consumed**: none
323
413
  - **Dependencies**: container, http, logger
324
- - **Plugins**: devtools.DiscoveryNamingLinterPlugin, devtools.DomainIsolationLinterPlugin, devtools.EventContractLinterPlugin, devtools.EventSchemasPlugin, devtools.FieldDivergenceLinterPlugin, devtools.RouteCollisionLinterPlugin, devtools.TableOwnershipLinterPlugin, devtools.ToolDocDriftLinterPlugin
414
+ - **Plugins**: devtools.SystemLintPlugin
325
415
 
326
416
  ### `system`
327
417
  - **Tables**: none
328
418
  - **Endpoints**:
329
419
  - `GET /system/events`
330
420
  - **res**: SystemEventsData(events: list[EventEntry(event: str, subscribers: list[str], last_emitters: list[str], times_fired: int)])
421
+ - `GET /system/events/schemas`
422
+ - **res**: EventSchemasData(schemas: dict)
331
423
  - `GET /system/metrics`
332
- - **res**: list[MetricRecord(tool: str, method: str, duration_ms: float, success: bool, timestamp: float)]
424
+ - **res**: list[MetricRecord(caller: str, event_id: Optional[str], tool: str, method: str, duration_ms: float, success: bool, error: Optional[str], timestamp: float)]
333
425
  - `GET /system/status`
334
426
  - **res**: SystemStatusData(tools: list[ToolStatus(name: str, status: str, message: Optional[str])], plugins: list[PluginStatus(name: str, domain: Optional[str], status: str, error: Optional[str], tools: list[str])])
335
427
  - `GET /system/traces/flat`
336
- - **res**: list[TraceFlatNode(id: str, parent_id: Optional[str], event: str, emitter: str, subscribers: list[str], payload_keys: list[str], timestamp: float, key: Optional[str], priority: Optional[int], delay: Optional[int])]
428
+ - **res**: list[TraceFlatNode(id: str, parent_id: Optional[str], event: str, emitter: str, subscribers: list[str], payload_keys: list[str], timestamp: float, key: Optional[str], priority: Optional[int], delay: Optional[int], tool_calls: list[TraceToolCall])]
337
429
  - `GET /system/traces/tree`
338
- - **res**: list[TraceNode(id: str, parent_id: Optional[str], event: str, emitter: str, subscribers: list[str], payload_keys: list[str], timestamp: float, key: Optional[str], priority: Optional[int], delay: Optional[int], children: list['TraceNode'])]
430
+ - **res**: list[TraceNode(id: str, parent_id: Optional[str], event: str, emitter: str, subscribers: list[str], payload_keys: list[str], timestamp: float, key: Optional[str], priority: Optional[int], delay: Optional[int], tool_calls: list[TraceToolCall], children: list['TraceNode'])]
339
431
  - `SSE /system/events/stream`
340
432
  - `SSE /system/logs/stream`
341
433
  - `SSE /system/metrics/stream`
@@ -343,7 +435,7 @@ Async SQLite Persistence Tool (sqlite):
343
435
  - **Events emitted**: `event.delivery.failed` (attempts, error, event, event_id, subscriber)
344
436
  - **Events consumed**: none
345
437
  - **Dependencies**: config, container, event_bus, http, logger, registry
346
- - **Plugins**: system.EventDeliveryMonitorPlugin, system.SystemEventsPlugin, system.SystemEventsStreamPlugin, system.SystemLogsStreamPlugin, system.SystemMetricsPlugin, system.SystemStatusPlugin, system.SystemTracesPlugin, system.SystemTracesStreamPlugin, system.ToolHealthPlugin
438
+ - **Plugins**: system.EventDeliveryMonitorPlugin, system.EventSchemasPlugin, system.SystemEventsPlugin, system.SystemEventsStreamPlugin, system.SystemLogsStreamPlugin, system.SystemMetricsPlugin, system.SystemStatusPlugin, system.SystemTracesPlugin, system.SystemTracesStreamPlugin, system.ToolHealthPlugin
347
439
 
348
440
  ## 🧩 Plugin Authoring Guide
349
441