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.
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/feature-plan.md +5 -2
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/new-domain.md +12 -9
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/new-tool.md +7 -2
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/solo-build.md +23 -4
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.env.example +43 -9
- {microcoreos-0.4.4 → microcoreos-0.4.6}/AGENTS.md +27 -5
- {microcoreos-0.4.4 → microcoreos-0.4.6}/AI_CONTEXT.md +173 -81
- {microcoreos-0.4.4 → microcoreos-0.4.6}/INSTRUCTIONS_FOR_AI.md +65 -71
- {microcoreos-0.4.4 → microcoreos-0.4.6}/PKG-INFO +26 -4
- {microcoreos-0.4.4 → microcoreos-0.4.6}/README.md +25 -3
- microcoreos-0.4.6/ROADMAP.md +906 -0
- microcoreos-0.4.4/ROADMAP.md → microcoreos-0.4.6/ROADMAP_DONE.md +87 -584
- {microcoreos-0.4.4 → microcoreos-0.4.6}/conftest.py +62 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/CLI.md +17 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/HTTP_SERVER.md +14 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/INDEX.md +6 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/PARALLEL_DEVELOPMENT.md +10 -8
- microcoreos-0.4.6/domains/devtools/plugins/system_lint_plugin.py +158 -0
- microcoreos-0.4.6/domains/system/plugins/event_schemas_plugin.py +163 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_metrics_plugin.py +4 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_traces_plugin.py +41 -2
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_traces_stream_plugin.py +28 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/postgresql_tool.py +48 -38
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/redis_state/redis_state_tool.py +17 -7
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/catalog.py +11 -3
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/cli.py +10 -5
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/container.py +28 -8
- microcoreos-0.4.6/microcoreos/external_extras.py +571 -0
- microcoreos-0.4.6/microcoreos/project_agents.md +262 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/project_readme.md +49 -4
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/scaffold.py +10 -210
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/cli.py +4 -1
- microcoreos-0.4.6/microcoreos_dev/lint/__init__.py +18 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/__init__.py +1 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/divergence.py +152 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/doc_drift.py +116 -0
- microcoreos-0.4.4/domains/devtools/plugins/event_contract_linter_plugin.py → microcoreos-0.4.6/microcoreos_dev/lint/checkers/events.py +128 -190
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/isolation.py +115 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/naming.py +103 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/routes.py +93 -0
- microcoreos-0.4.6/microcoreos_dev/lint/checkers/tables.py +70 -0
- microcoreos-0.4.6/microcoreos_dev/lint/report.py +71 -0
- microcoreos-0.4.6/microcoreos_dev/lint/runner.py +134 -0
- microcoreos-0.4.6/microcoreos_dev/lint/schema.py +53 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/pipeline.py +40 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/pyproject.toml +2 -2
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_core_purity.py +1 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_tool_proxy.py +38 -0
- microcoreos-0.4.6/tests/dev/test_lint_runner.py +151 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/test_pipeline.py +1 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_discovery_naming_linter.py +45 -55
- microcoreos-0.4.6/tests/linters/test_domain_isolation_linter.py +130 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_event_contract_linter.py +7 -11
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_field_divergence_linter.py +29 -43
- microcoreos-0.4.6/tests/linters/test_route_collision_linter.py +93 -0
- microcoreos-0.4.6/tests/linters/test_system_lint_plugin.py +74 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/linters/test_table_ownership_linter.py +9 -19
- microcoreos-0.4.6/tests/linters/test_tool_doc_drift_linter.py +33 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_event_schemas_plugin.py +32 -1
- microcoreos-0.4.6/tests/system/test_external_extras.py +276 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_system_traces_plugin.py +35 -0
- microcoreos-0.4.6/tests/tools/context/test_tool_signatures.py +207 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_pipeline.py +101 -21
- microcoreos-0.4.6/tests/tools/http_server/test_trusted_proxies_and_ws_origin.py +251 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_migrations.py +48 -0
- microcoreos-0.4.6/tests/tools/test_tool_setup_cleanup.py +273 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/context_tool.py +15 -3
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/renderers.py +41 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/event_bus_tool.py +15 -5
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/redis_streams_driver.py +27 -14
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/context.py +35 -7
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/http_server_tool.py +166 -10
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/pipeline.py +207 -34
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/migrations.py +22 -8
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/sqlite_tool.py +39 -28
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/system/registry_tool.py +1 -1
- {microcoreos-0.4.4 → microcoreos-0.4.6}/uv.lock +2 -2
- microcoreos-0.4.4/domains/devtools/lint/plugin_sources.py +0 -51
- microcoreos-0.4.4/domains/devtools/plugins/discovery_naming_linter_plugin.py +0 -118
- microcoreos-0.4.4/domains/devtools/plugins/domain_isolation_linter_plugin.py +0 -80
- microcoreos-0.4.4/domains/devtools/plugins/event_schemas_plugin.py +0 -94
- microcoreos-0.4.4/domains/devtools/plugins/field_divergence_linter_plugin.py +0 -178
- microcoreos-0.4.4/domains/devtools/plugins/route_collision_linter_plugin.py +0 -51
- microcoreos-0.4.4/domains/devtools/plugins/table_ownership_linter_plugin.py +0 -66
- microcoreos-0.4.4/domains/devtools/plugins/tool_doc_drift_linter_plugin.py +0 -74
- microcoreos-0.4.4/tests/linters/test_domain_isolation_linter.py +0 -90
- microcoreos-0.4.4/tests/linters/test_route_collision_linter.py +0 -69
- microcoreos-0.4.4/tests/linters/test_tool_doc_drift_linter.py +0 -53
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/skills/microcoreos-architecture/SKILL.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/skills/microcoreos-architecture/agent.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.agent/workflows/multi-domain-plan.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.claude/settings.local.json +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.dockerignore +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.github/workflows/ci.yml +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.github/workflows/release.yml +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.gitignore +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.mutmut-cache +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/.python-version +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/Dockerfile +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/LICENSE +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/cli.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/dev_infra/cache_probe.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/dev_infra/docker-compose.yml +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/CORE_INFRASTRUCTURE.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/ELASTIC_DEPLOYMENT.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/EVENT_BUS.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/OBSERVABILITY.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/OBSERVABILITY_API.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/docs/translations/es/README.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/event_delivery_monitor_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_events_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_events_stream_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_logs_stream_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/system_status_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/domains/system/plugins/tool_health_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/blocking_boot_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/chaos_control_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/failing_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/chaos/plugins/stress_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/ping/plugins/ping_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/migrations/001_scheduler_one_shots.sql +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/models/scheduler_one_shot.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/scheduler/plugins/durable_one_shots_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/migrations/001_create_users.sql +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/models/user.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/create_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/delete_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_me_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_user_by_id_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/get_users_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/login_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/logout_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/update_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_domains/users/plugins/welcome_service_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/auth/auth_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/auth/tests/auth_tool_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/chaos/chaos_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/kafka/kafka_driver.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/tests/postgresql_describe_schema_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/postgresql/tests/postgresql_tool_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/rabbitmq/rabbitmq_driver.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/__init__.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/s3_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/s3/tests/s3_tool_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/scheduler_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/tests/scheduler_singleton_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/extras/available_tools/scheduler/tests/scheduler_tool_test.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/hatch_build.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/main.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/__init__.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/base_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/base_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/context.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/kernel.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/project.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/registry.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos/upgrade.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/__init__.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/fuzzer.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/__init__.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/rules.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/scan.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/schema.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/plan/sync.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/microcoreos_dev/probe.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/README.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/active_plan.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/plans/active_plan.yaml +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_core.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_kernel.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_no_retry.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_plugin_di_fixtures.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/core/test_registry_collisions.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/corpus/README.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/corpus/qwen_twitter_plan.yaml +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/dev/test_plan_validator.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/ping/test_ping_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_create_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_delete_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_me_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_user_by_id_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_get_users_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_login_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_logout_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_update_user_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/domains/users/test_welcome_service_plugin.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/active_db.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/async_wait.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/mock_db.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/helpers/trace_chains.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_catalog.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_chaos_control.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_chaos_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_cli.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_durable_one_shots.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_scaffold.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_system_events_stats.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_trace_chain_helper.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/system/test_upgrade.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/config/test_config_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/context/test_context_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/db/test_db_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_broker_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_groups.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_kafka_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_rabbitmq_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_event_bus_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/event_bus/test_redis_streams_driver.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_params_hardening.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_http_server_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/http_server/test_security_hardening.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/logger/test_logger_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/registry/test_registry_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/s3/test_s3_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_concurrency.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_describe_schema.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_driver.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/sqlite/test_sqlite_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/state/test_state_parity.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/state/test_state_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tests/tools/telemetry/test_telemetry_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/config/config_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/authoring_guide.md +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/context/scanners.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/drivers.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/envelope.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/event_bus/sqlite_driver.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/http_server/types.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/logger/logger_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/errors.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/sqlite/transaction.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/state/state_tool.py +0 -0
- {microcoreos-0.4.4 → microcoreos-0.4.6}/tools/telemetry/__init__.py +0 -0
- {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
|
-
|
|
109
|
-
|
|
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
|
|
163
|
-
|
|
164
|
-
|
|
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
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
|
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
|
-
-
|
|
69
|
-
`tests/tools/
|
|
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. **
|
|
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. **
|
|
72
|
+
2. **Run the offline architecture gate**:
|
|
71
73
|
```bash
|
|
72
|
-
microcoreos
|
|
74
|
+
microcoreos check --strict
|
|
73
75
|
```
|
|
74
|
-
|
|
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
|
|
18
|
-
#
|
|
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
|
|
22
|
-
#
|
|
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
|
-
#
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
-
#
|
|
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.
|
|
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** | `
|
|
245
|
+
| **Black-Box Integration Tests** | `INSTRUCTIONS_FOR_AI.md` § Black-Box Integration Testing — complete fixture-based example |
|
|
226
246
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
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.
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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: `
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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.
|
|
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
|
|