Feat/stage profiling phase1 3

[lxsaah]

Implements automatic per-stage wall-clock timing for .source() / .tap() / .link() callbacks. The feature is off by default and zero-cost when disabled; alloc + a runtime clock is enough, so it works on no_std + alloc (including thumbv7em-none-eabihf via portable-atomic's critical-section fallback).

What's new

Core (aimdb-core, feature profiling)

• New profiling module: StageMetrics (atomic call_count / total / avg / min / max), RecordProfilingMetrics per-record container, serializable StageProfilingInfo snapshot.
• Instrumentation strategy: ProducerProfilingState times the interval between successive Producer::produce() calls; ProfilingBufferReader wraps the buffer reader returned by Consumer::subscribe() and times the interval between successive recv() yields. No change to the whole-task closure shape of .source() / .tap().
• RecordRegistrar::with_name("...") names the most recently registered source/tap/link (always callable; no-op when feature is off).
• RecordMetadata.stage_profiling field, attached automatically by TypedRecord::collect_metadata.
• AimDb::reset_stage_profiling() and new profiling.reset AimX RPC (write-permission gated).
• New RuntimeForProfiling marker trait keeps the public builder API unchanged when the feature is off.

Executor (aimdb-executor)

• TimeOps trait gains a required duration_as_nanos(duration) -> u64 method (runtime-agnostic numeric representation of elapsed time). Implemented in the tokio, embassy, and wasm adapters.

Adapters

• aimdb-tokio-adapter: profiling feature forwards to core; duration_as_nanos impl saturates u128 → u64.
• aimdb-embassy-adapter: profiling feature pulls portable-atomic/{fallback,critical-section} (via core) for 64-bit-atomic emulation on thumbv7em; duration_as_nanos uses microsecond granularity (portable lower bound). New make test-embedded cross-compile gate.
• aimdb-wasm-adapter: duration_as_nanos for WasmDuration (ms → ns, saturating).

Tools

• aimdb-client: AimxClient::reset_stage_profiling().
• aimdb-mcp: two new tools — get_stage_profiling (per-stage metrics + bottleneck detection with recommendation string) and reset_stage_profiling. The MCP server now depends on aimdb-core with profiling enabled.

Example demo (examples/remote-access-demo)

Temperature and SystemStatus are now driven by in-AimDB .source() + .tap() tasks with .with_name("...") labels. slow_status_processor deliberately sleeps 100 ms per value so get_stage_profiling record_key="SystemStatus" flags it as the bottleneck. README documents how to query and reset profiling via MCP and socat.

Tests

• Unit tests in StageMetrics (record, reset, accessors, concurrent record under std).
• Unit tests in RecordProfilingMetrics (sequential indices, set_stage_name, reset_all).
• Integration test aimdb-tokio-adapter/tests/stage_profiling.rs: drives a source/tap pipeline, asserts min ≤ avg ≤ max, verifies .with_name(...) lands on the registered stages, and that reset_all() clears counters.
• make build / make test gain profiling feature combinations for aimdb-core (std and no_std + alloc) and aimdb-tokio-adapter.
• make test-embedded gains cargo check --target thumbv7em-none-eabihf --features "embassy-runtime,profiling".

Test plan

• [x ] make check passes
• [x ] make all passes
• [x ] cargo run --package remote-access-demo --bin server starts cleanly; get_stage_profiling record_key="SystemStatus" via MCP returns ~100 ms avg_time_ns for slow_status_processor and flags it as the bottleneck

Closes #58.

[Copilot]

Pull request overview

Adds an opt-in, runtime-agnostic stage profiling feature across AimDB (core + adapters) and surfaces it via new MCP tools, along with an updated demo and tests to exercise the feature end-to-end.

Changes:

• Introduces aimdb-core stage profiling (profiling feature): per-stage metrics collection, naming via .with_name(..), metadata snapshotting, and a reset API/RPC.
• Extends aimdb-executor::TimeOps with duration_as_nanos() and implements it in Tokio/Embassy/WASM adapters.
• Adds aimdb-mcp tools (get_stage_profiling, reset_stage_profiling) plus demo, docs, changelogs, and CI Makefile gates.

Reviewed changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tools/aimdb-mcp/src/tools/profiling.rs	New MCP tool implementations for stage profiling query/reset
tools/aimdb-mcp/src/tools/mod.rs	Exposes the new profiling tools module and re-exports handlers
tools/aimdb-mcp/src/server.rs	Registers/dispatches the new MCP tools and schemas
tools/aimdb-mcp/README.md	Documents new MCP tools and expected outputs
tools/aimdb-mcp/CHANGELOG.md	Changelog entry for added profiling tools
tools/aimdb-mcp/Cargo.toml	Enables aimdb-core/profiling in MCP server dependency
Makefile	Adds build/test matrix entries for profiling (incl. embedded check)
examples/remote-access-demo/src/server.rs	Refactors demo to use .source()/.tap() with stage names and a deliberate bottleneck
examples/remote-access-demo/README.md	Adds “Stage Profiling” section and usage instructions
examples/remote-access-demo/Cargo.toml	Enables profiling features for core + tokio adapter
docs/design/014-M6-stage-profiling.md	Updates RFC status and adds implementation notes
CHANGELOG.md	Top-level changelog entries for the profiling feature and demo updates
Cargo.lock	Updates lockfile for new/updated dependencies
aimdb-wasm-adapter/src/time.rs	Implements TimeOps::duration_as_nanos for WASM duration type
aimdb-wasm-adapter/CHANGELOG.md	Notes the new duration_as_nanos implementation
aimdb-tokio-adapter/tests/stage_profiling.rs	New integration test for profiling instrumentation and naming
aimdb-tokio-adapter/src/runtime.rs	Implements TimeOps::duration_as_nanos for Tokio Duration
aimdb-tokio-adapter/CHANGELOG.md	Documents profiling feature + TimeOps update + integration test
aimdb-tokio-adapter/Cargo.toml	Adds profiling feature forwarding to aimdb-core/profiling
aimdb-executor/src/lib.rs	Adds required TimeOps::duration_as_nanos method
aimdb-executor/CHANGELOG.md	Documents the new required TimeOps method
aimdb-embassy-adapter/src/runtime.rs	Implements duration_as_nanos with microsecond granularity conversion
aimdb-embassy-adapter/CHANGELOG.md	Documents profiling feature and embedded compile gate
aimdb-embassy-adapter/Cargo.toml	Adds adapter-level profiling feature forwarding
aimdb-core/src/typed_record.rs	Stores per-record profiling metrics, injects instrumentation, and attaches metadata snapshots
aimdb-core/src/typed_api.rs	Adds stage naming (with_name) plumbing and wraps Consumer::subscribe() when profiling enabled
aimdb-core/src/remote/metadata.rs	Adds optional stage_profiling metadata field + helper
aimdb-core/src/remote/handler.rs	Adds profiling.reset RPC handler (write-permission gated)
aimdb-core/src/profiling/stage_metrics.rs	New atomic StageMetrics implementation + tests
aimdb-core/src/profiling/record_profiling.rs	New per-record container for per-stage metrics + naming + reset
aimdb-core/src/profiling/mod.rs	New instrumentation primitives (Clock, producer state, profiling buffer reader)
aimdb-core/src/profiling/info.rs	New serializable snapshot type (StageProfilingInfo) and snapshot builder
aimdb-core/src/lib.rs	Exposes profiling module/exports and adds RuntimeForProfiling marker trait
aimdb-core/src/context.rs	Exposes Time::duration_as_nanos() convenience accessor
aimdb-core/src/builder.rs	Wires a shared profiling clock into AimDb and adds reset method
aimdb-core/CHANGELOG.md	Core changelog entry for profiling feature
aimdb-core/Cargo.toml	Adds profiling feature and portable-atomic feature flags
aimdb-client/src/connection.rs	Adds AimxClient::reset_stage_profiling() RPC helper
aimdb-client/CHANGELOG.md	Documents new client reset method
.vscode/mcp.json	Adds a local MCP server entry for running aimdb-mcp via cargo run

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.