flameox 0.2.2__tar.gz → 0.2.3__tar.gz

{flameox-0.2.2 → flameox-0.2.3}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to flameox are documented in this file.
 
+## [0.2.3] - 2026-09-02
+
+### Bug Fixes
+
+- **setup:** Pin generated MCP launchers
+
+### Documentation
+
+- **mcp:** Clarify provider and comparison workflows
+- **setup:** Clarify uvx preparation lifecycle (#421) ([#421](https://github.com/morluto/flameox/pull/421))
+
+### Features
+
+- **mcp:** Return provider reconnection action
+- **mcp:** Expose typed capability tools (#422) ([#422](https://github.com/morluto/flameox/pull/422))
+- **mcp:** Restore explicit provider preparation (#419) ([#419](https://github.com/morluto/flameox/pull/419))
+- **runtime:** Unify bounded capture contracts (#417) ([#417](https://github.com/morluto/flameox/pull/417))
+
+### Refactoring
+
+- **setup:** Prepare the returned uvx environment (#420) ([#420](https://github.com/morluto/flameox/pull/420))
+- **runtime:** Validate captures atomically (#418) ([#418](https://github.com/morluto/flameox/pull/418))
 ## [0.2.2] - 2026-09-01
 
 ### Bug Fixes

{flameox-0.2.2 → flameox-0.2.3}/CONTRIBUTING.md

@@ -45,11 +45,11 @@ uv sync --extra dev --extra memory --extra trace --extra cpu --extra torch
 
 ## Understand the contract you are changing
 
-Production code uses a `src/` layout. Domain types and errors belong in
-`src/flameox/domain/`, transport-independent orchestration in
-`src/flameox/application/`, persistence in `src/flameox/storage/`, external tool
-integration in `src/flameox/adapters/`, and transport code in `src/flameox/cli.py`
-and `src/flameox/mcp/`. Tests mirror these boundaries under `tests/`.
+Production code uses a `src/` layout. `runtime_contracts.py` owns public contracts and registries,
+`stateless.py` owns request-local orchestration, `repository.py` owns optional immutable
+preservation, and `execution.py` owns bounded subprocess work. Provider integrations live in
+`providers/`, reusable native-format parsing in `adapters/`, isolated protocols in `workers/`, and
+transport code in `cli.py` and `mcp/`. Tests mirror these semantic owners under `tests/`.
 
 Read the contract that owns the behavior before editing it:
 
@@ -58,7 +58,7 @@ Read the contract that owns the behavior before editing it:
 | Process model, dependencies, and package boundaries | [Architecture](docs/architecture.md) |
 | Storage, provenance, publication, and schemas | [Storage and evidence](docs/storage-and-evidence.md) |
 | Experiments, comparisons, statistics, and evidence quality | [Investigations](docs/investigations.md) |
-| Profiler integrations, compatibility, and capability probing | [Adapters](docs/adapters.md) |
+| Profiler integrations, compatibility, and adapter policy | [Adapters](docs/adapters.md) |
 | Concurrency, recovery, integrity, security, and privacy | [Runtime safety](docs/runtime-safety.md) |
 | CLI and MCP behavior and trust boundaries | [Interfaces](docs/interfaces.md) |
 | Test markers, provider requirements, and CI | [Testing](docs/testing.md) |

{flameox-0.2.2 → flameox-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flameox
-Version: 0.2.2
+Version: 0.2.3
 Summary: Runtime evidence that helps agents trace, profile, and burn down hotspots in application and native code, GPU kernels, and inference stacks.
 Project-URL: Homepage, https://github.com/morluto/flameox
 Project-URL: Repository, https://github.com/morluto/flameox
@@ -77,7 +77,7 @@ paths and formats to `analyze`; old `.diagnostics` state is not migrated.
 
 ```console
 uv sync --extra dev --extra memory --extra trace --extra cpu
-uv run flameox capabilities discover --intent "CPU hotspots"
+uv run flameox mcp inspect
 uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
 uv run flameox capture --provider direct -- python benchmark.py
 ```
@@ -89,11 +89,17 @@ the startup working directory:
 uv run flameox mcp serve --project-root "$PWD"
 ```
 
-`flameox setup` prints the equivalent stdio client configuration. Explicit
-`--provider` selections add the matching Python extras to a persistent uv tool
-environment without removing its existing provider extras. System and vendor
-tools are diagnosed with external install guidance. Setup never initializes the
-project or creates `.flameox`.
+`flameox setup` prints a version-bound stdio client configuration using Python
+3.12 and the exact running Flameox release. It does not change an MCP client
+registration; apply the printed command through the client's supported MCP
+management interface. Explicit
+`--provider` selections prepare the exact version-pinned `uvx` environment in
+the printed launcher by resolving it once into uvx's cache; they do not create a
+persistent global `uv tool` installation. Each invocation declares the complete
+managed provider set for that launcher rather than adding to remembered state.
+Use `--timeout-seconds` for a slow cold resolution. System and vendor tools are
+diagnosed with external install guidance. Setup never initializes the project
+or creates `.flameox`.
 
 ## Authority model
 
@@ -124,14 +130,23 @@ coverage, truncation, limitations, and optional immutable preservation.
 
 ## MCP interface
 
-The server exposes exactly six tools:
+The server exposes actual evidence operations for client-side tool search instead of hiding its
+capabilities behind `discover`, `inspect`, or generic `analyze(capability_id, arguments)` calls.
+There are 24 read-only analysis tools, 17 executing capture tools, and three lifecycle tools. For
+example:
 
-- `discover_capabilities`
-- `inspect_capabilities`
-- `analyze`
-- `capture_and_analyze`
-- `preserve_evidence`
-- `query_evidence`
+```text
+analyze_cpu_hotspots       capture_cpu_hotspots
+analyze_gpu_launches       capture_gpu_launches
+analyze_benchmark_compare  capture_benchmark_summary
+analyze_kernel_validation  capture_sanitizer_failures
+prepare_providers          preserve_evidence          query_evidence
+```
+
+Each tool advertises its capability-specific options and compatible providers in its input schema.
+Analysis and capture have separate names and annotations because reading an artifact and executing a
+target are materially different effects. Tool search happens in the MCP client; Flameox does not
+require an additional catalog-search call.
 
 It exposes one resource template, `flameox://evidence/{evidence_id}`, for the
 digest-bound, redacted projection of the canonical immutable manifest. Full
@@ -139,16 +154,28 @@ argv, environment values, working directories, and host paths remain available
 only through explicit local manifest inspection. Native artifact bytes are
 deliberately not available as MCP resources.
 
-Direct capture accepts an argv array, a project-contained cwd, bounded
-environment overrides, provider and analysis arguments, and limits. Shell
-strings are never accepted. Work remains owned by the live MCP request, so SDK
-progress and cancellation apply directly; there are no detached or
-restart-surviving tasks.
+Direct capture accepts an argv array, a project-contained cwd, bounded environment overrides, a
+typed compatible-provider variant, capability-specific options, an explicit single/experiment
+choice, and limits as top-level tool arguments. There is no generic request or arguments envelope.
+Shell strings are never accepted. Work remains owned by the live MCP request, so SDK progress and
+cancellation apply directly; there are no detached or restart-surviving tasks.
 
-Managed external collectors such as py-spy execute from Flameox's uv tool
+Managed external collectors such as py-spy execute from Flameox's uvx
 environment. In-process collectors such as coverage.py and Memray are verified
 in, and run with, the workload's declared Python interpreter. Flameox does not
-substitute one Python runtime for the other.
+substitute one Python runtime for the other. When a capture reports a missing managed provider,
+`prepare_providers` prepares its version-pinned uvx environment and returns that same launcher for
+reconnection. The agent supplies the complete provider list it wants in that launcher; Flameox does
+not merge it with prior calls. Preparation does not modify the running MCP process. When the client
+must reconnect, the result returns a typed `next_action` with `kind: "reconnect_mcp"`, an agent-facing
+message, and the launcher to use. The managed provider IDs are `aiperf`, `memray`, `otlp`, `perfetto`,
+`py-spy`, and `torch`. Host tools, drivers, and permissions are never installed or changed; the same
+result reports their setup guidance.
+
+Comparison is intentionally a two-stage workflow. Flameox captures representative baseline and
+candidate summaries separately, optionally preserves them, and then passes both artifacts to an
+`analyze_*_compare` tool. There are no `capture_*_compare` tools: experiment capture measures cases
+and reports an effect, but it is not a substitute for comparing explicit native artifacts.
 
 ## Evidence quality
 

{flameox-0.2.2 → flameox-0.2.3}/README.md

@@ -17,7 +17,7 @@ paths and formats to `analyze`; old `.diagnostics` state is not migrated.
 
 ```console
 uv sync --extra dev --extra memory --extra trace --extra cpu
-uv run flameox capabilities discover --intent "CPU hotspots"
+uv run flameox mcp inspect
 uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
 uv run flameox capture --provider direct -- python benchmark.py
 ```
@@ -29,11 +29,17 @@ the startup working directory:
 uv run flameox mcp serve --project-root "$PWD"
 ```
 
-`flameox setup` prints the equivalent stdio client configuration. Explicit
-`--provider` selections add the matching Python extras to a persistent uv tool
-environment without removing its existing provider extras. System and vendor
-tools are diagnosed with external install guidance. Setup never initializes the
-project or creates `.flameox`.
+`flameox setup` prints a version-bound stdio client configuration using Python
+3.12 and the exact running Flameox release. It does not change an MCP client
+registration; apply the printed command through the client's supported MCP
+management interface. Explicit
+`--provider` selections prepare the exact version-pinned `uvx` environment in
+the printed launcher by resolving it once into uvx's cache; they do not create a
+persistent global `uv tool` installation. Each invocation declares the complete
+managed provider set for that launcher rather than adding to remembered state.
+Use `--timeout-seconds` for a slow cold resolution. System and vendor tools are
+diagnosed with external install guidance. Setup never initializes the project
+or creates `.flameox`.
 
 ## Authority model
 
@@ -64,14 +70,23 @@ coverage, truncation, limitations, and optional immutable preservation.
 
 ## MCP interface
 
-The server exposes exactly six tools:
+The server exposes actual evidence operations for client-side tool search instead of hiding its
+capabilities behind `discover`, `inspect`, or generic `analyze(capability_id, arguments)` calls.
+There are 24 read-only analysis tools, 17 executing capture tools, and three lifecycle tools. For
+example:
 
-- `discover_capabilities`
-- `inspect_capabilities`
-- `analyze`
-- `capture_and_analyze`
-- `preserve_evidence`
-- `query_evidence`
+```text
+analyze_cpu_hotspots       capture_cpu_hotspots
+analyze_gpu_launches       capture_gpu_launches
+analyze_benchmark_compare  capture_benchmark_summary
+analyze_kernel_validation  capture_sanitizer_failures
+prepare_providers          preserve_evidence          query_evidence
+```
+
+Each tool advertises its capability-specific options and compatible providers in its input schema.
+Analysis and capture have separate names and annotations because reading an artifact and executing a
+target are materially different effects. Tool search happens in the MCP client; Flameox does not
+require an additional catalog-search call.
 
 It exposes one resource template, `flameox://evidence/{evidence_id}`, for the
 digest-bound, redacted projection of the canonical immutable manifest. Full
@@ -79,16 +94,28 @@ argv, environment values, working directories, and host paths remain available
 only through explicit local manifest inspection. Native artifact bytes are
 deliberately not available as MCP resources.
 
-Direct capture accepts an argv array, a project-contained cwd, bounded
-environment overrides, provider and analysis arguments, and limits. Shell
-strings are never accepted. Work remains owned by the live MCP request, so SDK
-progress and cancellation apply directly; there are no detached or
-restart-surviving tasks.
+Direct capture accepts an argv array, a project-contained cwd, bounded environment overrides, a
+typed compatible-provider variant, capability-specific options, an explicit single/experiment
+choice, and limits as top-level tool arguments. There is no generic request or arguments envelope.
+Shell strings are never accepted. Work remains owned by the live MCP request, so SDK progress and
+cancellation apply directly; there are no detached or restart-surviving tasks.
 
-Managed external collectors such as py-spy execute from Flameox's uv tool
+Managed external collectors such as py-spy execute from Flameox's uvx
 environment. In-process collectors such as coverage.py and Memray are verified
 in, and run with, the workload's declared Python interpreter. Flameox does not
-substitute one Python runtime for the other.
+substitute one Python runtime for the other. When a capture reports a missing managed provider,
+`prepare_providers` prepares its version-pinned uvx environment and returns that same launcher for
+reconnection. The agent supplies the complete provider list it wants in that launcher; Flameox does
+not merge it with prior calls. Preparation does not modify the running MCP process. When the client
+must reconnect, the result returns a typed `next_action` with `kind: "reconnect_mcp"`, an agent-facing
+message, and the launcher to use. The managed provider IDs are `aiperf`, `memray`, `otlp`, `perfetto`,
+`py-spy`, and `torch`. Host tools, drivers, and permissions are never installed or changed; the same
+result reports their setup guidance.
+
+Comparison is intentionally a two-stage workflow. Flameox captures representative baseline and
+candidate summaries separately, optionally preserves them, and then passes both artifacts to an
+`analyze_*_compare` tool. There are no `capture_*_compare` tools: experiment capture measures cases
+and reports an effect, but it is not a substitute for comparing explicit native artifacts.
 
 ## Evidence quality
 

{flameox-0.2.2 → flameox-0.2.3}/README.zh-CN.md

@@ -8,7 +8,7 @@ Flameox 是面向编码代理的本地、有界运行时证据层。它协调分
 包含 argv、项目内 cwd、环境覆盖、提供方参数和限制的类型化目标。
 
 ```console
-uv run flameox capabilities discover --intent "CPU 热点"
+uv run flameox mcp inspect
 uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
 uv run flameox capture --provider direct -- python benchmark.py
 uv run flameox mcp serve --project-root "$PWD"
@@ -23,9 +23,10 @@ Python 扩展安装到持久的 uv 工具环境；NVIDIA 等系统或厂商工
 `<project>/.flameox`。原生字节和证据清单按 SHA-256 寻址，并通过同一文件系统
 上的暂存、校验、fsync 和原子重命名发布。
 
-MCP 只公开六个工具：`discover_capabilities`、`inspect_capabilities`、
-`analyze`、`capture_and_analyze`、`preserve_evidence` 和
-`query_evidence`。唯一资源模板是
+MCP 公开面向任务的类型化分析和采集工具，例如 `analyze_cpu_hotspots`、
+`capture_gpu_launches` 和 `analyze_benchmark_compare`，以及
+`prepare_providers`、`preserve_evidence` 和 `query_evidence`。工具搜索由 MCP
+客户端负责。唯一资源模板是
 `flameox://evidence/{evidence_id}`，只返回不可变规范清单，不公开原生载荷。
 
 `analysis_id` 仅在当前服务进程内有效；重启后过期。`evidence_id` 是持久的内容

{flameox-0.2.2 → flameox-0.2.3}/docs/adapters.md

@@ -11,14 +11,19 @@ Each capability registry entry owns:
 - the capability descriptor and stable ID;
 - accepted source modes and formats;
 - a strict validation-equivalent argument model;
-- provider probes and compatibility rules;
+- compatibility rules derived from declared artifact formats;
 - capture and analysis handlers;
-- bounded examples, limits, overhead, and limitations.
+- model-visible selection guidance, bounded examples, limits, overhead, and limitations.
 
-Discovery probes packages, executables, platform, supported version, permission,
-and required external resources without mutating the host. Missing dependencies
-are successful availability results with remediation outside Flameox. Invoking
-an unavailable provider is a typed tool error.
+One immutable capture-provider contract owns each provider's argument model, declared artifact
+roles and formats, and selection description. Generated MCP schemas, pre-execution compatibility
+checks, and capture argument validation consume that same contract so their format claims cannot
+drift.
+
+Capability tools remain discoverable when a provider is absent. Capture validates the selected
+provider's package, executable, platform, version, permission, and required external resources as
+part of the attempted operation, before workload execution. An unavailable provider returns a typed
+error with either an exact `prepare_providers` retry action or external host guidance.
 
 ## Evidence and capture support
 
@@ -29,7 +34,7 @@ Artifact analysis and typed capture are separate contracts:
 
 | Evidence family | Explicit artifact analysis | Typed capture provider |
 | --- | --- | --- |
-| CPU profiles | Node/V8, py-spy Speedscope, perf collapsed stacks, perf data | `node-cpu-profile`, `py-spy`, `perf` |
+| CPU profiles | Node/V8, cProfile pstats, py-spy Speedscope, perf collapsed stacks, perf data | `node-cpu-profile`, `py-spy`, `perf` |
 | Memory profiles | Memray | `memray` |
 | Benchmarks | pyperf, benchmark samples, PyTorch samples, NVBench | `pyperf`, `benchmark-samples`, `nvbench` |
 | Execution traces | Perfetto/Chrome, PyTorch, OTLP, ROCprof PFTrace, xctrace, Nsight Systems | `torch-profiler`, `rocprofv3`, `xctrace`, `nsight-systems` |
@@ -37,7 +42,7 @@ Artifact analysis and typed capture are separate contracts:
 | Reliability | pytest events, observations, coverage.py | `pytest`, `observations`, `coverage` |
 | Static candidates | SARIF | — |
 | Inference exports | AIPerf, vLLM, SGLang, Mooncake | — |
-| Generic previews | JSON, JSONL, CSV, text, Parquet | — |
+| Generic previews | JSON, JSONL, CSV, text, Parquet | `direct` process output |
 
 An em dash means callers provide an explicit artifact path; it does not mean
 the format is unsupported. The offline inference readers omit prompts,
@@ -45,6 +50,11 @@ generations, error text, endpoints, tools, payloads, and prefix-hash values.
 Pytest capture runs an explicit `python -m pytest` target with a request-bound,
 bounded event plugin.
 
+`failures.summary` scans the complete bounded pytest event artifact for aggregate outcomes, but its
+table projects only failed, errored, interrupted, and unexecuted identities. Failed collection
+reports retain their collector identity; successful collection events, passing tests, and skipped
+tests cannot consume the diagnostic row budget.
+
 Support is honest rather than substitutive. A missing Trace Processor does not
 turn a Perfetto request into a JSON preview; a missing `ncu` does not become an
 empty kernel report.
@@ -82,14 +92,22 @@ session-local in-memory DuckDB; it does not create a temporary SQLite database.
 
 ## Provider setup boundary
 
-An explicit `flameox setup --provider ...` invocation adds the selected Python
-extras to the persistent uv tool environment while retaining extras from its
-existing uv receipt. The result reports the complete managed provider set.
+An explicit `flameox setup --provider ...` invocation prepares the exact
+version-pinned uvx environment returned in its launcher. The invocation's
+provider list is complete; Flameox retains no provider inventory or setup receipt.
 System and vendor packages remain externally installed. Setup creates no
 project state and is not a prerequisite for explicit-path analysis.
+Nsight Compute capture requires both the `ncu` executable and NVIDIA's vendor-shipped
+`extras/python/ncu_report.py` reader. Flameox resolves both before workload execution and returns
+external setup guidance if the installation is incomplete.
 
 Provider ownership is explicit during capture. External collectors installed
-with Flameox, such as py-spy, execute from the managed tool environment rather
+with Flameox, such as py-spy, execute from the launched uvx environment rather
 than ambient request `PATH`. In-process collectors, including coverage.py and
 Memray, must be installed in the declared workload interpreter; capture probes
 that interpreter before execution and never substitutes Flameox's interpreter.
+
+Pyperf command capture preserves multiline typed argv through a metadata-safe launcher because
+pyperf rejects newline characters in its display metadata. The launcher executes the original argv
+without shell parsing, but its startup is included in each command measurement; exact Flameox
+capture provenance remains authoritative for the requested argv.

{flameox-0.2.2 → flameox-0.2.3}/docs/architecture.md

@@ -36,8 +36,8 @@ durable SHA-256 identity derived from the canonical manifest body.
 
 ## Package boundaries
 
-- `stateless.py` owns public models, capability discovery, bounded analysis,
-  capture orchestration, scratch, and the session cache.
+- `runtime_contracts.py` owns public models and the capability/capture-provider registries.
+- `stateless.py` owns bounded analysis, capture orchestration, scratch, and the session cache.
 - `repository.py` owns lazy repository creation, validation, publication,
   inventory queries, and immutable resource reads.
 - `execution.py` and `command_binding.py` own executable binding, subprocess
@@ -51,13 +51,18 @@ catalog. Flameox production code must not create or depend on SQLite state.
 
 ## Capability boundary
 
-One registry entry owns a capability descriptor, strict argument model,
-accepted formats, provider probes, and capture/analysis semantics. Discovery
-performs only bounded suffix/header sniffing. Missing packages, executables,
-permissions, versions, or platforms are successful discovery states; Flameox
-never installs remediation automatically. The separately invoked CLI setup
-command may install an explicitly selected Python provider-extra set into a uv
-tool environment; it creates no project state and owns no durable operation.
+One registry entry owns a capability descriptor, strict argument model, accepted formats,
+capture/analysis semantics, and model-visible selection guidance. MCP projects each entry
+into a read-only analysis tool and, when a compatible capture provider exists, a separate executing
+capture tool. The generated callable closes over the stable capability ID; agents never pass a
+capability selector or a free-form analysis argument object.
+
+Capture-provider contracts supply the discriminated provider variants for each compatible capture
+tool. Missing packages, executables, permissions, versions, or platforms do not change the catalog;
+the attempted tool returns typed remediation. The separately invoked CLI setup command or MCP
+`prepare_providers` tool may prepare the exact version-pinned uvx environment named by an explicit
+Python provider set; neither creates project state nor owns a durable operation or provider
+inventory. Host profilers, drivers, and permissions remain external and receive guidance only.
 
 Direct capture is trusted local execution, not containment. Typed argv prevents
 shell interpretation, while the broker provides process-group cleanup, bounded

flameox-0.2.3/docs/interfaces.md

@@ -0,0 +1,173 @@
+# Interfaces
+
+CLI and MCP are thin transports over `AnalysisRuntime`. They do not own storage,
+provider behavior, or lifecycle state.
+
+## MCP catalog
+
+The catalog exposes task-shaped tools for client-side tool search. Flameox does not add a second
+search/inspect protocol in front of its operations. A caller that knows the evidence question can
+invoke its tool directly; an unfamiliar caller relies on the MCP client's ordinary tool search and
+then receives the selected tool's complete schema.
+
+There are exactly 44 tools:
+
+| Group | Count | Examples | Effect |
+| --- | ---: | --- | --- |
+| Existing-artifact analysis | 24 | `analyze_cpu_hotspots`, `analyze_gpu_launches`, `analyze_benchmark_compare`, `analyze_kernel_validation`, `preview_artifact` | Read-only and idempotent. |
+| Capture and immediate analysis | 17 | `capture_cpu_hotspots`, `capture_gpu_launches`, `capture_benchmark_summary`, `capture_sanitizer_failures`, `capture_process_output` | Executes typed argv; not read-only or idempotent. |
+| Evidence lifecycle | 3 | `prepare_providers`, `preserve_evidence`, `query_evidence` | Prepare an explicit uvx environment or manage immutable evidence. |
+
+The capability registry generates the analysis and capture tools through the Python MCP SDK 2.0
+registration API. The SDK derives each top-level input schema directly from the registered callable.
+A generated analysis tool has `sources`, capability-specific typed `options`, optional lowered
+`limits`, and an optional `continuation`. A generated capture tool has `target`, a discriminated
+`provider` union containing only compatible capture providers, capability-specific typed `options`,
+an explicit `single` or `experiment` execution union, optional lowered `limits`, and optional
+`preserve`. There is no extra request envelope and there are no free-form provider or analysis
+argument objects.
+
+For example, a single Nsight Compute capture for kernel metrics has this argument shape:
+
+```json
+{
+  "target": {"argv": ["python", "kernel.py"]},
+  "provider": {"kind": "nsight-compute", "options": {"launch_count": 1}},
+  "options": {},
+  "execution": {"kind": "single"},
+  "preserve": true
+}
+```
+
+Analysis and capture remain separate tools even when they return the same evidence envelope. MCP
+annotations describe a whole tool, so combining read-only artifact analysis and target execution
+behind a mode flag would conceal a material effect change. Provider choice stays inside a capture
+tool because it is a typed implementation choice for one evidence question; incompatible providers
+cannot be represented by that tool's schema.
+
+There is one resource template:
+
+```text
+flameox://evidence/{evidence_id}
+```
+
+`resources/list` is empty. `resources/read` returns a redacted, digest-bound projection of the
+canonical manifest with its own versioned media type. It omits argv, environment values, working
+directories, and host paths. The local CLI `evidence show` command is the explicit full-provenance
+view. A missing resource is a protocol error.
+
+Every tool advertises a compact output schema for its stable result envelope. Provider-specific
+metrics and rows remain open JSON values. Success uses structured content directly, without an
+`ok/result/error` wrapper. Tool failures set `isError=true` and carry a stable code, message, and
+details. MCP SDK argument-validation errors occur before tool execution and therefore use the
+protocol error shape rather than the tool's output schema.
+
+`prepare_providers` is the only open-world tool. It resolves the exact package requirement through
+`uvx`, verifies that environment by running Flameox's version command, and returns the same
+requirement in a project-bound MCP launcher. The request names the complete managed provider set;
+Flameox keeps no installed-provider inventory or setup receipt. System profilers, drivers, device
+access, and OS permissions remain external requirements; Flameox returns guidance for them but does
+not invoke a system package manager or elevate privileges. Preparation creates no project state,
+durable job, or plan, and it cannot add packages to the currently running server. A result with
+a non-null `next_action` identifies the typed `reconnect_mcp` handoff, explains that the current
+server is unchanged, and directs the agent to reconnect with the returned launcher before retrying
+the capture. Host-only preparation returns `next_action: null`. Managed provider IDs are `aiperf`,
+`memray`, `otlp`, `perfetto`, `py-spy`, and `torch`; every call declares the complete desired set. A
+provider such as Perfetto may be both prepared Python support and an external host Trace Processor
+requirement. Preparation waits up to 1,800 seconds by default; callers may set `timeout_seconds`
+from 1 through 3,600. A uvx failure returns its complete stderr in `SETUP_FAILURE`.
+
+## Sources and limits
+
+The strict source union is:
+
+```text
+PathSource     {kind: "path", path, format?, producer?, expected_sha256?}
+EvidenceSource {kind: "evidence", evidence_id, artifact_role?}
+```
+
+Continuations are opaque integrity cursors bound to the request and exact input
+digests. They contain no authority, credentials, or artifact data and are not
+an authentication boundary: a caller already authorized to submit the analysis
+can choose which of its rows to request. They can cross process boundaries, so
+a CLI invocation can resume a previous page. A changed input cannot reuse a
+continuation.
+
+Projection providers may expose a bounded prefix when their native reader cannot
+resume safely. Such results keep `coverage.complete=false`, identify
+`truncation.reason=provider_limit`, and do not emit a continuation after the last
+retrievable row. A continuation therefore always names a consumable next page;
+it never promises access beyond a provider's declared projection bound.
+
+Requests may lower startup row, result-byte, timeout, output-byte, and durable
+provenance-byte limits. Durable provenance bounds the captured argv and execution
+metadata retained for explicit preservation.
+They cannot raise them.
+
+## Capture
+
+A direct target contains an argv array, project-contained cwd, and at most 32 bounded environment
+overrides after experiment-case overrides are merged. Provider fields live in the capture tool's
+typed provider union, and analysis fields live in its capability-specific `options` model. Shell
+command strings are not accepted.
+
+Provider output formats are compared with the requested capability before scratch creation or
+execution. Statically incompatible pairs fail with the declared formats and compatible capture
+providers. Capture also resolves the cwd and executable, checks aggregate scratch and durable
+provenance capacity, and validates every experiment case before creating request scratch. There is
+no separate plan or preflight authority: the typed capture request is validated atomically by the
+operation that executes it.
+
+Callers may request preservation as part of capture. Once native collection succeeds, requested
+preservation publishes the native artifacts even if immediate analysis fails; the result then
+reports separate capture execution state and a typed `analysis_failure`. An analysis failure is
+never converted into empty successful evidence.
+
+Experiment mode adds 2-16 cases, 1-100 blocks, a seed, metric, estimand,
+practical threshold, and optional semantic-oracle argv. Version 0.2 evaluates
+`wall_time_ns` with a paired `median_difference` or `mean_difference`, reports
+eligible blocks and a deterministic percentile interval when at least three
+blocks survive capture/oracle validation, and classifies the effect against the
+declared threshold. Work is not detached; the request receives progress and owns
+cancellation.
+
+Comparison tools consume explicit artifacts; they do not capture their inputs. A caller captures
+representative baseline and candidate summaries separately, preserves them when durable provenance
+is needed, and supplies at least two sources to `analyze_benchmark_compare`,
+`analyze_inference_compare`, or `analyze_kernel_compare`. Flameox does not advertise
+`capture_*_compare`: experiment capture reports the declared cases' effect but does not create the
+case-grouped native inputs required by artifact comparison.
+
+## Stable failure codes
+
+The transport distinguishes invalid input, unavailable providers,
+missing or changed input, unsupported format, decode failure, execution failure,
+cancellation, limit exceeded, expired session analysis, missing evidence,
+repository I/O failure, repository corruption, and unsupported repository
+format. An unavailable managed provider identifies `prepare_providers` and the exact provider list
+needed for a retry; an unavailable system provider returns external setup guidance.
+
+## CLI
+
+The retained surface is:
+
+```text
+flameox setup
+flameox mcp serve|inspect
+flameox analyze [--continuation TOKEN] [--preserve]
+flameox capture [--preserve] -- <argv...>
+flameox evidence query|show
+```
+
+`setup` prints stdio configuration that launches the exact running Flameox
+release through `uvx` on Python 3.12. It reports that no MCP client registration
+was changed; client-owned management interfaces apply the returned command.
+Repeated `--provider` options declare the complete Python provider set for the
+exact version-pinned uvx environment used by the returned launcher.
+`--timeout-seconds` accepts 1 through 3,600 and defaults to 1,800. Resolver,
+download, and compatibility failures retain uvx's complete stderr. System and
+vendor providers receive external installation guidance. Setup does not create
+a persistent global tool, project repository, durable operation, or MCP setup
+endpoint.
+Other CLI commands construct the same runtime and project-root rules used by
+MCP.

{flameox-0.2.2 → flameox-0.2.3}/docs/investigations.md

@@ -33,10 +33,16 @@ containment must not be silently promoted to complete evidence.
 
 ## Experiments
 
-`capture_and_analyze` supports `single` and `experiment` modes. An experiment
-declares cases, blocks, seed, metric, estimand, practical threshold, and an
-optional semantic oracle. Cases are bounded and execute through the same broker
-as a single capture.
+Every `capture_*` capability tool accepts a discriminated `single` or `experiment` execution
+request. An experiment declares cases, blocks, seed, metric, estimand, practical threshold, and an
+optional semantic oracle. Cases are bounded and execute through the same broker as a single capture.
+
+For GPU kernel work, the agent normally compiles and edits with its native coding tools, records
+correctness through `analyze_kernel_validation` and `analyze_kernel_compare`, checks hazards with
+`capture_sanitizer_failures`, measures representative baseline/candidate cases with
+`capture_benchmark_summary` in experiment mode, and profiles only the remaining uncertainty with
+`capture_gpu_launches` or `capture_gpu_kernel_metrics`. Flameox preserves the verification evidence;
+it does not generate kernels, wrap compilers, or decide which optimization to implement.
 
 The 0.2 runtime accepts `wall_time_ns` and paired `median_difference` or
 `mean_difference`. Each non-baseline case is compared with the first declared
@@ -45,6 +51,12 @@ reported as limitations; fewer than three eligible pairs produce a descriptive
 estimate without a confidence interval. The practical-threshold decision is
 returned as typed comparison evidence, not retained only as request metadata.
 
+Artifact comparison is separate from that experiment result. Capture the representative baseline
+and candidate summaries independently, preserve them if they must survive the session, then submit
+both sources to the matching `analyze_*_compare` tool. There is no `capture_*_compare` shortcut:
+comparison requires explicit artifact identity, while experiment mode owns randomized case order
+and repeated measurements within one request.
+
 Randomization and blocking reduce ordering and environmental bias; they do not
 make an unrepresentative workload representative. Failed and partial trials are
 evidence and must stay visible in the returned episode. A semantic oracle checks