microcoreos 0.3.0__tar.gz → 0.3.2__tar.gz

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/skills/microcoreos-architecture/SKILL.md

@@ -11,14 +11,14 @@ open — a Planner that also loads the plugin templates spends ~3,000 tokens on
 code it will never write.
 
 This file deliberately holds no rules, no reading path and no checklist of its
-own. It used to hold all three, and all three had drifted: its reading path
-sent plugin authors to `INSTRUCTIONS_FOR_AI.md` for templates that live in the
-generated manifest, and its checklist was a fifth partial copy of the 13
-Non-Negotiable Rules — one that never mentioned typed event payloads.
+own. It is a routing table and nothing else: every row points at the one place
+that owns its subject. Add a rule, a path or a checklist here and it becomes a
+rival copy of something canonical — which is the one failure this file exists
+to prevent.
 
 | You need | It is in |
 |---|---|
-| The rules | `AGENTS.md` § Non-Negotiable Rules (13, canonical) |
+| The rules | `AGENTS.md` § Non-Negotiable Rules (canonical) |
 | Kernel/tool/event-bus laws | `AGENTS.md` § Core Architectural Laws |
 | The plugin template | `AI_CONTEXT.md` § Plugin Authoring Guide (regenerated every boot) |
 | What exists right now | `AI_CONTEXT.md` § Available Tools / § Domains |

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/skills/microcoreos-architecture/agent.md

@@ -10,7 +10,7 @@ You are a **Systems Architect** specialized in high-performance, resilient micro
 ## Decision Framework
 - **Core First**: Is this change affecting the Core? If yes, look for an alternative in Plugins/Tools.
 - **Tool Isolation**: Does this Tool import another Tool? If so, REJECT the design and move the logic to a Plugin (Bridge).
-- **Rules Review**: Before implementing, check the 13 Non-Negotiable Rules in `AGENTS.md`. (This line used to cite "Three Golden Rules in SKILL.md" — a document that never existed.)
+- **Rules Review**: Before implementing, check the Non-Negotiable Rules in `AGENTS.md`.
 - **Resilience**: Will a failure here crash the entire system?
 - **Observability**: Can this be monitored via the `registry`?
 

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/workflows/feature-plan.md

@@ -30,8 +30,8 @@ existing vocabulary implies, put it in the YAML, and flag it in a comment.
 
 `docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
 Read it when a validator error is unclear, not before — and never reach for
-plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
-planner that did produced a plan with every field renamed.
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape:
+reading an implementation to infer the format renames every field in your plan.
 
 ## Prerequisites
 
@@ -127,10 +127,19 @@ assert_chain(build_tree(bus.get_trace_history()), ["order.cancelled", "order.ref
 ### 5. Close
 
 ```bash
-// turbo
-uv run main.py   # or: microcoreos (if you installed the package)
+microcoreos migrate   # the boot that ends: applies migrations, regenerates AI_CONTEXT.md
 ```
 
-- `GET /system/lint` → no warnings, no `UNTYPED_PAYLOAD` for your events.
 - Regenerated `AI_CONTEXT.md` matches the plan (routes, events, keys).
   **The feature is done when AI_CONTEXT == plan.**
+
+Then, for the lint only — the one boot this workflow sanctions (`AGENTS.md`
+§ reading route). This boot **serves forever**: foreground, read, Ctrl-C.
+Never background it; a process holding port 5000 makes the next
+`microcoreos migrate` refuse to run.
+
+```bash
+microcoreos           # or: uv run main.py (identical) — Ctrl-C when done
+```
+
+- `GET /system/lint` → no warnings, no `UNTYPED_PAYLOAD` for your events.

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/workflows/multi-domain-plan.md

@@ -35,8 +35,8 @@ existing vocabulary implies, put it in the YAML, and flag it in a comment.
 
 `docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
 Read it when a validator error is unclear, not before — and never reach for
-plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
-planner that did produced a plan with every field renamed.
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape:
+reading an implementation to infer the format renames every field in your plan.
 
 ## Phase 1 — The full plan (the contract, authored FIRST)
 
@@ -73,14 +73,14 @@ never patch it in code.
 ## Phases 0, 2 and 3
 
 Identical to any other plan — `docs/PARALLEL_DEVELOPMENT.md` owns them, and
-restating them here is how this file once kept prescribing a boot command that
-had stopped regenerating the manifest.
+nothing about them is restated here. A second copy of a phase is a second
+command to keep in step, and only one of the two gets updated.
 
 Two things are specific to multi-domain work and are the only reason this
 section exists:
 
 - **Migration ordering across domains.** One author for the numbering, and
-  `-- depends: other_domain/001_file.sql` wherever a table in one domain must
+  `-- depends: other_domain/001_file.sql` wherever a table in one domain must  <!-- lint:no-path -->
   exist before another's. The db tool resolves the order and prints each file
   as it applies it.
 - **Never assign two agents to the same feature**, and never let one agent

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/workflows/new-domain.md

@@ -32,13 +32,13 @@ existing vocabulary implies, put it in the YAML, and flag it in a comment.
 
 `docs/PARALLEL_DEVELOPMENT.md` § Phase 1 holds the rules behind the format.
 Read it when a validator error is unclear, not before — and never reach for
-plugin source under `domains/`, `tools/` or `extras/` to infer the shape. A
-planner that did produced a plan with every field renamed.
+plugin source under `domains/`, `tools/` or `extras/` to infer the shape:
+reading an implementation to infer the format renames every field in your plan.
 
 ## Prerequisites
 
 Both files above. Nothing else: the plugin template lives in `AI_CONTEXT.md`
-§ Plugin Authoring Guide, generated on every boot, and the rules are the 13
+§ Plugin Authoring Guide, generated on every boot, and the rules are the
 Non-Negotiable Rules in `AGENTS.md`.
 
 ## Steps
@@ -65,7 +65,6 @@ lines of YAML, one pass.
 ### 1. Create the domain folder structure
 
 ```bash
-// turbo
 mkdir -p domains/{name}/models domains/{name}/migrations domains/{name}/plugins
 ```
 
@@ -93,13 +92,24 @@ class {Name}Entity(BaseModel):
 
 File: `domains/{name}/migrations/001_create_{name}_table.sql`
 
-Write raw SQL that creates the table. Use `$1, $2...` placeholders in queries (PostgreSQL-style, auto-converted for SQLite).
+Write raw SQL that creates the table. Queries use `$1, $2...` placeholders
+(PostgreSQL-style, auto-converted for SQLite) — but **migration SQL is never
+translated: it runs verbatim on the active engine** (Non-Negotiable Rule 8).
+The default engine is SQLite, which has neither `SERIAL` nor `NOW()`.
+
+Write portable SQL — `CURRENT_TIMESTAMP`, not `NOW()` — so the PostgreSQL swap
+stays free. The auto-increment PK is the one thing with no spelling common to
+both: write it the SQLite way and carry the swap note in the file. The
+reference is `extras/available_domains/users/migrations/001_create_users.sql`:
 
 ```sql
+-- Portable SQL except the auto-increment PK. On a PostgreSQL swap, change
+-- "INTEGER PRIMARY KEY" to "INTEGER PRIMARY KEY GENERATED BY DEFAULT AS
+-- IDENTITY" (see docs/ELASTIC_DEPLOYMENT.md, Stage 1 review).
 CREATE TABLE IF NOT EXISTS {name}s (
-    id SERIAL PRIMARY KEY,
-    -- columns matching the entity model
-    created_at TIMESTAMP DEFAULT NOW()
+    id         INTEGER PRIMARY KEY,
+    -- columns matching the entity model, with the plan's types
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 ```
 
@@ -108,7 +118,8 @@ CREATE TABLE IF NOT EXISTS {name}s (
 One plugin file per operation in `domains/{name}/plugins/`. The template — with
 request, response and event-payload schemas inline, and the rules that go with
 them — is `AI_CONTEXT.md` § **Plugin Authoring Guide**, regenerated on every
-boot and already inside every executor prompt. A fourth copy lived here.
+boot and already inside every executor prompt. Never copy it into this file
+or into a plan — the copy is what goes stale.
 
 The one thing that is this workflow's own decision: which operations exist.
 A CRUD domain is create / get_all / get_by_id / update / delete, one file each,
@@ -116,54 +127,81 @@ each declared in the plan before any of them is written.
 
 ### 5. Verify
 
+Most of the checklist needs no server. Start with the boot that ends:
+
+```bash
+microcoreos migrate   # applies migrations AND regenerates AI_CONTEXT.md
+```
+
 ```bash
-// turbo
-uv run main.py   # or: microcoreos (if you installed the package)
+microcoreos schema    # the live tables and columns
 ```
 
 Check that:
-- Migration ran successfully (look for `[Migration] ✅` in logs)
+- Migrations applied (look for `[Migration] ✅`) and `microcoreos schema` shows
+  the new tables with the columns the plan declared
+- `AI_CONTEXT.md` was regenerated with the new domain — **done when it matches
+  the plan**
+
+Only the lint endpoints need a live system, and this is the one place in this
+workflow sanctioned to boot one (`AGENTS.md` § reading route). This boot
+**serves forever**: run it in the foreground, read the endpoints, Ctrl-C.
+Never background it — a process left holding port 5000 makes the next
+`microcoreos migrate` refuse to run.
+
+```bash
+microcoreos           # or: uv run main.py (identical) — Ctrl-C when done
+```
+
 - Endpoints appear in the Swagger UI at `http://localhost:5000/docs`
 - `GET /system/lint` has no warnings and no `UNTYPED_PAYLOAD` for your events
 - `GET /system/events/schemas` lists every event the plan declared
-- `AI_CONTEXT.md` was regenerated with the new domain — **done when it matches the plan**
-- `microcoreos schema` shows the new tables with the columns the plan declared
 
 ### 6. Generate tests
 
 Create `tests/test_{name}_plugin.py` with one test per plugin. Mock exactly
 the tools the plan's `tools:` field lists; run the rest as real in-memory
-instances (`INSTRUCTIONS_FOR_AI.md` § Testing). Example with everything
-mocked (`tools: [http, db, event_bus, logger]`):
+instances (`INSTRUCTIONS_FOR_AI.md` § Testing).
+
+**Configure the method, not the mock.** A plugin awaits `self.db.execute(...)`,
+never `self.db(...)` — so `AsyncMock(return_value=1)` and
+`AsyncMock(side_effect=...)` configure a call that never happens. Set them on
+the method: `db.execute.return_value = 1`, `db.execute.side_effect = ...`.
 
 ```python
 import pytest
 from unittest.mock import MagicMock, AsyncMock
 from domains.{name}.plugins.create_{name}_plugin import Create{Name}Plugin
 
-@pytest.mark.anyio
-async def test_create_{name}_success():
-    plugin = Create{Name}Plugin(
-        http=MagicMock(),
-        db=AsyncMock(return_value=1),
-        event_bus=AsyncMock(),
-        logger=MagicMock(),
+pytestmark = pytest.mark.anyio
+
+
+def make_plugin(db):
+    return Create{Name}Plugin(
+        http=MagicMock(), db=db, event_bus=AsyncMock(), logger=MagicMock()
     )
-    result = await plugin.execute({"field1": "value", "field2": 42})
+
+
+async def test_create_{name}_success():
+    db = AsyncMock()
+    db.execute.return_value = 1          # the METHOD the plugin awaits
+    result = await make_plugin(db).execute({"field1": "value", "field2": 42})
     assert result["success"] is True
     assert result["data"]["id"] == 1
 
-@pytest.mark.anyio
+
 async def test_create_{name}_db_error():
-    plugin = Create{Name}Plugin(
-        http=MagicMock(),
-        db=AsyncMock(side_effect=Exception("DB down")),
-        event_bus=AsyncMock(),
-        logger=MagicMock(),
-    )
-    result = await plugin.execute({"field1": "value", "field2": 42})
+    db = AsyncMock()
+    db.execute.side_effect = Exception("DB down")
+    result = await make_plugin(db).execute({"field1": "value", "field2": 42})
     assert result["success"] is False
     assert "DB down" not in result["error"]  # Safe Errors: technical detail never reaches the client
 ```
 
+`pytest.mark.anyio` needs an `anyio_backend` fixture; the generated
+the generated root `conftest.py` already ships one, along with `mock_logger` and
+`mock_state`. The richer alternative — the real db tool with this domain's
+migrations applied, asserting on rows instead of on mock calls — is the
+black-box style of `tests/domains/users/test_create_user_plugin.py`.
+
 Run with `uv run -m pytest tests/test_{name}_plugin.py`.

{microcoreos-0.3.0 → microcoreos-0.3.2}/.agent/workflows/new-tool.md

@@ -20,16 +20,29 @@ else about them exists so they can be swapped without touching a single plugin.
 1. **Location**: `tools/{name}/{name}_tool.py` — or `extras/available_tools/{name}/`
    if it should not be active by default (a replacement ALWAYS starts in
    extras/: two tools with the same `name` silently overwrite each other).
-2. **The `name` property is the contract** — it is the DI injection key.
-3. **A tool never uses other tools.** If a capability needs `db` + `event_bus`
+   **The tool's own tests go in `{that folder}/tests/`**, so they travel with
+   the tool when `microcoreos add` moves it. Import the tool the way those
+   tests do — `tools.{name}` first, `extras.available_tools.{name}` as the
+   fallback — or the import dies the moment the folder moves. Parity suites
+   are the exception: they import two implementations at once, so they stay in
+   `tests/tools/{name}/`.
+2. **Name those tests `{name}_tool_test.py`, never `test_{name}_tool.py`.**
+   The Kernel imports every `*_tool.py` under `tools/`, and `test_s3_tool.py`
+   ends in exactly that: boot would import the test, and with it pytest, which
+   a deployed install does not have. pytest collects `*_test.py` by default,
+   so the safe name costs nothing. `DiscoveryNamingLinterPlugin` fails on the
+   unsafe one — this is the only place in the repo where `*_test.py` is the
+   required form.
+3. **The `name` property is the contract** — it is the DI injection key.
+4. **A tool never uses other tools.** If a capability needs `db` + `event_bus`
    + `scheduler`, it is not a tool: compose it in the plugin layer
    (precedents: DurableOneShotsPlugin, the deferred Outbox — Issue 28).
-4. **Self-documented**: every public method appears in
+5. **Self-documented**: every public method appears in
    `get_interface_description()` — the anti-drift linter warns on discrepancies.
-5. **Config via `os.getenv()`** inside the tool (the `config` tool is for plugins).
-6. **Header spec**: the tool's docstring/header documents its replacement
+6. **Config via `os.getenv()`** inside the tool (the `config` tool is for plugins).
+7. **Header spec**: the tool's docstring/header documents its replacement
    contract — the exact API and semantics a substitute must honor.
-7. **External backend?** Make its connection-error class inherit
+8. **External backend?** Make its connection-error class inherit
    `ToolUnavailableError` so ToolProxy marks it DEAD on the first
    infrastructure failure. In-memory/local tools skip this.
 
@@ -52,8 +65,8 @@ No imports from other tools, no plugin imports, stateless where possible.
 
 The same test battery runs against the reference implementation AND yours:
 
-- Canonical examples: `tests/tools/test_state_parity.py`,
-  `tests/tools/test_event_bus_broker_parity.py` (parameterized over transports).
+- Canonical examples: `tests/tools/state/test_state_parity.py`,
+  `tests/tools/event_bus/test_event_bus_broker_parity.py` (parameterized over transports).
 - If the backend needs a server, the suite skips itself when unavailable and
   the server is added to CI services (`dev_infra/docker-compose.yml`).
 - **A replacement that does not pass the reference's parity suite is not a

{microcoreos-0.3.0 → microcoreos-0.3.2}/.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(cp AI_CONTEXT.md /tmp/ai_context_antes.md)",
       "Read(//tmp/**)",
       "Bash(timeout 15 uv run main.py)",
-      "Bash(echo \"EXIT:$?\")"
+      "Bash(echo \"EXIT:$?\")",
+      "Bash(.venv/bin/python *)"
     ]
   }
 }

{microcoreos-0.3.0 → microcoreos-0.3.2}/.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           --health-timeout 5s
           --health-retries 5
 
-      # Real Redis so the state parity suite (tests/tools/test_state_parity.py)
+      # Real Redis so the state parity suite (tests/tools/state/test_state_parity.py)
       # runs against actual infrastructure instead of skipping itself.
       redis:
         image: redis:7-alpine
@@ -48,7 +48,7 @@ jobs:
           --health-retries 5
 
       # Real RabbitMQ so the broker parity suite
-      # (tests/tools/test_event_bus_rabbitmq_parity.py) runs instead of skipping.
+      # (tests/tools/event_bus/test_event_bus_rabbitmq_parity.py) runs instead of skipping.
       rabbitmq:
         image: rabbitmq:3.13-alpine
         ports:
@@ -103,7 +103,11 @@ jobs:
           uv run python -c "from microcoreos import BaseTool; print('✅ BaseTool OK')"
 
       - name: Run Core Tests
-        run: uv run -m pytest tests/ -v --tb=short
+        # No path argument: `testpaths` in pyproject.toml owns the set, and it
+        # is wider than tests/ — a tool's own tests live inside the tool's
+        # folder so they travel with it when `microcoreos add` moves it.
+        # Passing `tests/` here would silently drop every one of them.
+        run: uv run -m pytest -v --tb=short
 
   # Boots the REAL system against REAL infrastructure (MinIO as S3, SQLite on
   # disk) and asserts that every tool is OK and every plugin is READY. This is
@@ -373,7 +377,7 @@ jobs:
       # The filesystem-facing suites. The rest of tests/ needs Postgres, Redis
       # and RabbitMQ, which is what the Linux matrix is for.
       - name: Path and packaging suites
-        run: uv run -m pytest tests/test_upgrade.py tests/test_scaffold.py tests/test_catalog.py tests/test_cli.py -q
+        run: uv run -m pytest tests/system/test_upgrade.py tests/system/test_scaffold.py tests/system/test_catalog.py tests/system/test_cli.py -q
 
       - name: Build the wheel
         run: uv build --wheel -o dist

{microcoreos-0.3.0 → microcoreos-0.3.2}/.gitignore

@@ -55,3 +55,10 @@ package-lock.json
 # as a submodule with no .gitmodules, and every checkout since failed its
 # cleanup step with exit 128.
 .claude/worktrees/
+
+# Test Coverage & Mutation Testing
+.coverage
+htmlcov/
+.mutmut-cache/
+mutants/
+

{microcoreos-0.3.0 → microcoreos-0.3.2}/AGENTS.md

@@ -27,12 +27,42 @@ Four roles do the work, and **each needs a different slice**. Reading outside
 your slice is not thoroughness, it is budget: the Planner that also loads the
 plugin templates spends ~3,000 tokens on code it will never write.
 
+They are phases, not people. Doing all of them yourself is the fifth row — the
+common case for one or two features — and it means playing the four in order,
+taking each slice as you enter it, not reading everything up front.
+
 | You are… | Read exactly this | **Write exactly this** | Not this |
 |---|---|---|---|
 | **Planner** — turning a request into a plan | **1.** `plans/active_plan.yaml` — the file you are about to overwrite. It ships as a worked example of all three feature shapes, and it is the cheapest, densest statement of the format there is. **2.** `AI_CONTEXT.md` **down to `## 🧩 Plugin Authoring Guide`** (existing tools, tables, models, routes, events). **3.** `docs/PARALLEL_DEVELOPMENT.md` **§ Phase 1** for the rules behind it | **`plans/active_plan.yaml` + `plans/active_plan.md`, overwriting them.** Never a new filename — `plans/twitter_plan.yaml` is a plan nothing will execute | The Authoring Guide, Phases 2-3, `domains/`, `tools/`, `tests/`, `extras/` |
 | **Phase 0 Builder** — migrations, models, tools | `plans/active_plan.yaml` **§ phase_0** only | Exactly the files `phase_0` names: its migrations, its models, its tools | Everything else. The plan already decided every column |
 | **Executor** — one plugin + its test | **Nothing.** Your prompt already contains `AI_CONTEXT.md` + the plan + your one task line | Exactly two files: the `file:` and `test:` your task declares | Any file at all — opening one only invites guessed paths |
 | **Coordinator** — dispatch, verify, reconstruct | `plans/active_plan.md` (the checklist/state machine) + `docs/PARALLEL_DEVELOPMENT.md` **§ Phases 2-3** | Only the checkboxes in `plans/active_plan.md` | The plan's internals; the checklist is the state |
+| **Solo** — one agent, every phase, in sequence | The row above you, as you reach it — the Planner's slice first, and nothing else until you are past planning | Everything the four rows write, in their order | Skipping the plan because it is "only two features". See below |
+
+**If you are the Solo row**, exactly two things differ from the four above.
+You may read the code **you** wrote — the black box rule is about not seeing
+*another agent's* implementation, and it does not apply to your own
+(`docs/PARALLEL_DEVELOPMENT.md` § Features are black boxes). And you run the
+union of the command rows below, each in its own phase.
+
+What does **not** differ is the plan. `plans/active_plan.yaml` is still the
+first file you write, for one feature as much as for twelve. Three reasons,
+none of which are about coordinating anybody:
+
+- **The shipped plan is a valid plan.** Leave it untouched and `microcoreos
+  status` reports the *example* domain as the active work — to you now, and to
+  whoever opens the project next.
+- **`microcoreos plan validate` is the only pre-code check there is.** Route
+  collisions, consumed events that nothing publishes, tables owned by another
+  domain, the sad-path checklist. It runs offline, in a second, before a line
+  of code commits you to any of it.
+- **It is what survives you.** A context that gets compacted, a session that
+  dies at feature two of three — the plan is the only record of what "done"
+  meant. Prose in a reply is not.
+
+The cost is the honest objection, and it is small: one feature on an existing
+domain is ~10-15 lines of YAML, no `phase_0`, and no `flows` at all unless it
+publishes or consumes events (`.agent/workflows/feature-plan.md`).
 
 If you are the Planner, the first thing you write is `plans/active_plan.yaml`
 itself — not a draft under another name that someone copies later. The copy
@@ -54,6 +84,7 @@ reviews a real file rather than a description of one.
 | Phase 0 Builder | `microcoreos migrate`, `microcoreos schema` |
 | Executor | none — write your two files and stop |
 | Coordinator | `uv run -m pytest`, `microcoreos status`, and `microcoreos` (the real boot) for the final lint |
+| Solo | All of the above — but each in its phase, and the real boot only at the end |
 
 **Never `microcoreos run` / `uv run main.py` outside that last row.** It serves
 forever: in the foreground it hangs your session, in the background it leaves a
@@ -157,10 +188,9 @@ The Kernel (ToolProxy & Container) is infrastructure-blind:
 ## 🔄 The pipeline, in five lines
 
 The methodology, the phase numbering and the executor-prompt mechanics live in
-`docs/PARALLEL_DEVELOPMENT.md` — **canonically, and only there**. This used to
-be a second copy of it, which is precisely how the copy drifted: it prescribed
-`--boot-tool db` for phase 0 long after that stopped regenerating the manifest,
-and no one compares two documents to notice.
+`docs/PARALLEL_DEVELOPMENT.md` — **canonically, and only there**. What follows
+is a five-line index, not a second copy: nobody diffs two documents, so a copy
+here would keep prescribing a stale command with every test still green.
 
 | Phase | Command | Gate |
 |---|---|---|

{microcoreos-0.3.0 → microcoreos-0.3.2}/AI_CONTEXT.md

@@ -87,22 +87,31 @@ Configuration Tool (config):
 ### 🔧 Tool: `telemetry` (Status: ✅)
 ```text
 Telemetry Tool (telemetry):
-        - PURPOSE: OpenTelemetry distributed tracing. Auto-instruments all tool calls via ToolProxy.
-          No changes needed in plugins or existing tools to get basic spans.
+        - PURPOSE: OpenTelemetry distributed tracing AND metrics. Auto-instruments all tool
+          calls via ToolProxy. No changes needed in plugins or existing tools to get basic
+          spans or metrics.
         - ACTIVATION: Set OTEL_ENABLED=true. Degrades gracefully if disabled or packages missing.
         - ENV VARS:
             - OTEL_ENABLED: "true" to activate (default: "false").
-            - OTEL_SERVICE_NAME: Service name in traces (default: "microcoreos").
-            - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP/gRPC endpoint (e.g. "http://jaeger:4317").
-              If not set, traces are printed to console (development mode).
+            - OTEL_SERVICE_NAME: Service name in traces/metrics (default: "microcoreos").
+            - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP/gRPC endpoint (e.g. "http://otel-collector:4317").
+              If not set, traces and metrics are printed to console (development mode).
         - CAPABILITIES:
             - get_tracer(scope: str) -> Tracer: Named tracer for custom spans inside a plugin.
                 Usage: tracer = self.telemetry.get_tracer("my_plugin")
                        with tracer.start_as_current_span("my_operation"): ...
                 Returns a no-op tracer if OTel is disabled — safe to use unconditionally.
+            - get_meter(scope: str) -> Meter: Named meter for custom metrics inside a plugin.
+                Usage: meter = self.telemetry.get_meter("my_plugin")
+                       counter = meter.create_counter("orders_created")
+                       counter.add(1)
+                Returns a no-op meter if OTel is disabled — safe to use unconditionally.
         - AUTO-INSTRUMENTATION (zero config):
             Every tool call (db.execute, event_bus.publish, auth.create_token, etc.)
-            gets a span automatically via ToolProxy. No plugin changes needed.
+            gets a span automatically via ToolProxy, AND is recorded as an OTel histogram
+            (tool_call_duration_ms) and counter (tool_call_total) with tool/method/success
+            attributes — the same record already exposed at registry.get_metrics() / GET
+            /system/metrics, now also exported over OTLP. No plugin changes needed.
         - DRIVER-LEVEL INSTRUMENTATION (optional, per tool):
             Tools can implement on_instrument(tracer_provider) in BaseTool to add
             framework-specific spans (SQL query text, HTTP route, etc.).
@@ -304,11 +313,11 @@ Async SQLite Persistence Tool (sqlite):
   - `GET /system/events/schemas`
     - **res**: EventSchemasData(schemas: dict)
   - `GET /system/lint`
-    - **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])
+    - **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])
 - **Events emitted**: none
 - **Events consumed**: none
 - **Dependencies**: container, http, logger
-- **Plugins**: devtools.DiscoveryNamingLinterPlugin, devtools.DomainIsolationLinterPlugin, devtools.EventContractLinterPlugin, devtools.EventSchemasPlugin, devtools.FieldDivergenceLinterPlugin, devtools.RouteCollisionLinterPlugin, devtools.TableOwnershipLinterPlugin, devtools.ToolDocDriftLinterPlugin
+- **Plugins**: devtools.DiscoveryNamingLinterPlugin, devtools.DocPathLinterPlugin, devtools.DomainIsolationLinterPlugin, devtools.EventContractLinterPlugin, devtools.EventSchemasPlugin, devtools.FieldDivergenceLinterPlugin, devtools.RouteCollisionLinterPlugin, devtools.TableOwnershipLinterPlugin, devtools.ToolDocDriftLinterPlugin
 
 ### `system`
 - **Tables**: none

{microcoreos-0.3.0 → microcoreos-0.3.2}/INSTRUCTIONS_FOR_AI.md

@@ -27,9 +27,10 @@ These are the most frequent errors. Check these first before writing any code.
 
 ## ⚠️ The rules
 
-The 13 **Non-Negotiable Rules** in `AGENTS.md`, there and nowhere else. This
-section held a rival list of eleven that had never heard of "schemas inline" or
-typed event payloads — an agent's constitution depended on which file it opened.
+The **Non-Negotiable Rules** in `AGENTS.md`, there and nowhere else. Never
+restate them here, and never cite them with a count: a rival copy, or a number
+that another file has to keep in step, is one more thing that can disagree with
+the list an agent is standing in front of.
 
 Event bus capabilities (`ttl`, `retries`, `backoff`, DLQ) are in `AI_CONTEXT.md`
 § Tool: `event_bus`, generated from the tool itself so they cannot drift.
@@ -63,7 +64,8 @@ domains/{name}/
 
 `AI_CONTEXT.md` § **Plugin Authoring Guide** — one complete template per
 deliverable type, regenerated on every boot from `tools/context/authoring_guide.md` and
-already inside every executor prompt. A third copy lived here and had drifted.
+already inside every executor prompt. Never copy it here: the generated one
+is the only one that tracks the code.
 
 If you are writing a plugin you are an executor: nothing in this file is for you.
 
@@ -120,7 +122,9 @@ Rules of the pattern:
 
 ## 🔧 New Tool
 
-**Location**: `tools/{name}/{name}_tool.py`
+**Location**: `tools/{name}/{name}_tool.py`, with its own tests in
+`tools/{name}/tests/`, named `{name}_tool_test.py` — NEVER `test_{name}_tool.py`,
+which the Kernel would import at boot. They travel with the tool when it is installed or swapped.
 **Rule**: Stateless, isolated, self-documented. Use `EventBusDriver` pattern for new transport layers.
 
 ### The Parity Rule (Contract over Implementation)
@@ -130,9 +134,9 @@ replaces. This ensures that plugins remain infrastructure-blind and behavior
 is consistent across backends.
 
 **Canonical examples:**
-- `tests/tools/test_state_parity.py`: Verifies that `RedisStateTool` behaves
+- `tests/tools/state/test_state_parity.py`: Verifies that `RedisStateTool` behaves
   exactly like the default in-memory `StateTool`.
-- `tests/tools/test_event_bus_broker_parity.py`: Parametrized suite that
+- `tests/tools/event_bus/test_event_bus_broker_parity.py`: Parametrized suite that
   runs against both the local driver and `RedisStreamsDriver`.
 
 **Health contract (optional, only for tools with an external backend)**:
@@ -261,15 +265,15 @@ plugin against a contract the test itself declares, so if a tool's real API
 drifts the mock keeps passing. That gap is closed elsewhere, not by your test:
 the `ToolDocDriftLinter` (boot + `/system/lint`) compares each tool's
 documented interface against its implementation, and the parity suites
-(`tests/tools/test_state_parity.py`,
-`tests/tools/test_event_bus_broker_parity.py`) hold swappable tools to one
+(`tests/tools/state/test_state_parity.py`,
+`tests/tools/event_bus/test_event_bus_broker_parity.py`) hold swappable tools to one
 behaviour. Do not re-verify that in a plugin test.
 
 ### Ask for tools the way the plugin does
 
 A plugin never builds a tool: it names one in `__init__` and the Kernel hands
 it over. pytest injects by parameter name too, so **a test uses the same
-vocabulary** — `tests/conftest.py` publishes one fixture per Kernel injection
+vocabulary** — `conftest.py` (repo root) publishes one fixture per Kernel injection
 key (`db`, `event_bus`, `auth`, `state`, `logger`, `config`). No tool imports,
 no setup/teardown, no hand-built schema:
 
@@ -285,7 +289,7 @@ async def test_create_user_persists(db, event_bus, auth, logger):
     assert rows[0]["password_hash"] != "secret123"
 ```
 
-Worked example: `tests/test_plugin_di_fixtures.py`.
+Worked example: `tests/core/test_plugin_di_fixtures.py`.
 
 - `@pytest.mark.migrations("users", "system")` applies those domains' real
   migration files. **No marker = a real but empty database**, which is what a

{microcoreos-0.3.0 → microcoreos-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microcoreos
-Version: 0.3.0
+Version: 0.3.2
 Summary: Atomic Microkernel Architecture optimized for AI-Driven Development
 License: MIT
 License-File: LICENSE
@@ -184,7 +184,7 @@ That is the code your app depends on, and it is the whole of it: booting loads
 `kernel`, `container`, `registry`, `context` and the two base classes, and
 nothing else. The rest of the package — the scaffolder, the extras catalog,
 `upgrade` — is the `microcoreos` command, build-time work that never executes
-inside your application. `tests/test_core_purity.py` enforces both halves of
+inside your application. `tests/core/test_core_purity.py` enforces both halves of
 that: a third-party import in the kernel fails the suite, and so does the
 kernel importing the CLI half.
 
@@ -217,7 +217,7 @@ This pattern works for any infrastructure: swap the event bus backend, the HTTP
 
 Additional tools — PostgreSQL, Redis state, auth, S3, the scheduler, chaos — ship in `extras/` and install with `microcoreos add <name>`. If the new tool reuses an existing `name` (e.g. `redis_state` registers as `"state"`), move the tool it replaces out of `tools/` first: only one tool per name may be discovered.
 
-The Redis state swap is verified by a parity suite (`tests/tools/test_state_parity.py`): the same contract battery runs against the in-memory reference and against a real Redis, so the replacement is proven equivalent, not assumed.
+The Redis state swap is verified by a parity suite (`tests/tools/state/test_state_parity.py`): the same contract battery runs against the in-memory reference and against a real Redis, so the replacement is proven equivalent, not assumed.
 
 ### Honest Kernel & Smart Infrastructure.
 
@@ -231,7 +231,7 @@ The Kernel is "logic-free." `ToolProxy` observes and reports health but **never
 
 **Tool Call Metrics** — Every tool method call is automatically timed by ToolProxy. Access via `registry.get_metrics()` or attach a real-time sink.
 
-**OpenTelemetry** (optional) — Set `OTEL_ENABLED=true`. Every tool call gets a span. Export to Jaeger, Grafana Tempo, Datadog. Zero changes to plugins.
+**OpenTelemetry** (optional) — Set `OTEL_ENABLED=true`. Every tool call gets a span AND is recorded as a histogram (`tool_call_duration_ms`) + counter (`tool_call_total`). Export to Jaeger, Grafana Tempo, Prometheus, Datadog. Zero changes to plugins.
 
 ---
 
@@ -418,6 +418,23 @@ Two tracks — see [ROADMAP.md](ROADMAP.md) for the full plan and decision log:
 
 ---
 
+## 💖 Built on the Shoulders of Open-Source Giants
+
+MicroCoreOS provides the **Atomic Microkernel Architecture, DI container, orchestration engine, and 1-file decoupling**. Every swappable Tool is a contract wrapper powered by world-class open-source projects created by amazing maintainers:
+
+- **FastAPI, Starlette & Uvicorn** — Powers `HttpServerTool` (`http`)
+- **Pydantic** — Powers request/response schema validation
+- **aiosqlite & asyncpg** — Powers `SQLiteTool` and `PostgreSQLTool` (`db`)
+- **redis-py** — Powers `RedisStateTool` and Redis Streams event bus driver
+- **aiokafka & aio-pika** — Powers Kafka and RabbitMQ event bus drivers
+- **APScheduler** — Powers `SchedulerTool` (`scheduler`)
+- **PyJWT & bcrypt** — Powers `AuthTool` (`auth`)
+- **OpenTelemetry** — Powers `TelemetryTool` (`telemetry`)
+- **aioboto3** — Powers `S3Tool` (`s3`)
+- **mutmut & Locust** — Powers mutation blindage and the `MicroCoreBench` laboratory
+
+---
+
 ## License
 
 [MIT](LICENSE)