flameox 0.2.2__tar.gz → 0.2.4__tar.gz

{flameox-0.2.2 → flameox-0.2.4}/.github/workflows/release.yml

@@ -300,9 +300,35 @@ jobs:
           tar -xzf "$archive" mcp-publisher
 
       - name: Publish MCP server metadata
+        env:
+          RELEASE_VERSION: ${{ needs.build.outputs.version }}
         run: |
+          set -euo pipefail
           ./mcp-publisher login github-oidc
-          ./mcp-publisher publish server.json
+          for attempt in {1..12}; do
+            set +e
+            output=$(./mcp-publisher publish server.json 2>&1)
+            status=$?
+            set -e
+            printf '%s\n' "$output"
+
+            if [[ "$status" -eq 0 ]]; then
+              exit 0
+            fi
+
+            missing_version="version '${RELEASE_VERSION}' was not found (status: 404)"
+            if ! grep --fixed-strings --quiet "$missing_version" <<< "$output"; then
+              exit "$status"
+            fi
+
+            if [[ "$attempt" -lt 12 ]]; then
+              echo "MCP Registry has not observed PyPI $RELEASE_VERSION; retrying in 10 seconds"
+              sleep 10
+            fi
+          done
+
+          echo "MCP Registry did not observe PyPI $RELEASE_VERSION within 120 seconds" >&2
+          exit 1
 
   verify-npm-latest:
     name: Verify npm latest bootstrap

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

@@ -2,6 +2,56 @@
 
 All notable changes to flameox are documented in this file.
 
+## [0.2.4] - 2026-09-02
+
+### Bug Fixes
+
+- **mcp:** Include cwd in capture examples
+- **release:** Retry MCP registry propagation
+
+### Documentation
+
+- Explain workspace-free evidence runtime
+
+### Features
+
+- **setup:** Configure global MCP clients
+
+### Refactoring
+
+- **runtime:** Simplify bounded capture lifecycle
+- **runtime:** Remove workspace binding
+
+### Styling
+
+- Format capture provider module
+
+### Testing
+
+- Remove stale redesign assertions
+- Remove unused execution helper
+## [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.4}/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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flameox
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -16,13 +16,14 @@ Requires-Dist: ijson<4,>=3.4
 Requires-Dist: mcp-types==2.0.0
 Requires-Dist: mcp==2.0.0
 Requires-Dist: packaging<27,>=24
-Requires-Dist: portalocker<4,>=3.2
 Requires-Dist: psutil<8,>=7.0
 Requires-Dist: pyarrow<26,>=20
 Requires-Dist: pydantic<2.14,>=2.13.4
 Requires-Dist: pyperf<2.11,>=2.10
 Requires-Dist: pytz>=2024.2
+Requires-Dist: questionary<3,>=2.1
 Requires-Dist: rfc8785==0.1.4
+Requires-Dist: tomlkit<1,>=0.13
 Requires-Dist: typer<1,>=0.16
 Provides-Extra: all
 Requires-Dist: aiperf<0.13,>=0.12; extra == 'all'
@@ -77,23 +78,36 @@ 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
+uv run flameox capture --provider direct --cwd "$PWD" -- python benchmark.py
 ```
 
-The MCP server fixes its project root at startup. Manual launches default to
-the startup working directory:
+The MCP server has no workspace or project binding:
 
 ```console
-uv run flameox mcp serve --project-root "$PWD"
+uv run flameox mcp serve
 ```
 
-`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`.
+Run the short global setup wizard through npm:
+
+```console
+npx flameox@latest setup
+```
+
+Setup detects Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Google Antigravity, then asks
+which clients should use Flameox. It preserves unrelated client configuration and writes a
+Python 3.12 `uvx` launcher pinned to the exact Flameox release that ran setup. Restart or reconnect
+changed clients afterward. For automation, pass `--client codex --yes`, repeat `--client`, or use
+`--all --yes`; `--dry-run` reports the same global paths without writing them. Detection is never
+automation consent.
+
+Explicit `--provider` selections prepare the exact version-pinned `uvx` environment in the saved
+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 or mutates a
+project.
 
 ## Authority model
 
@@ -109,14 +123,16 @@ explicit artifact paths / typed direct target
                        explicit preservation
                               │
                               ▼
-                    <project>/.flameox
+             user Flameox data directory
 ```
 
 Analysis and unpreserved capture make no durable Flameox writes. Capture
-artifacts stay in bounded session scratch until preservation or server
-shutdown. The first `preserve_evidence` call creates `.flameox`, stores native
-bytes and a canonical evidence bundle by SHA-256, and adds `.flameox/` to the
-repository-local `.git/info/exclude` when applicable.
+artifacts stay in bounded session scratch until preservation, least-recently-used eviction, or
+server shutdown. An evicted `analysis_id` returns `EXPIRED_SESSION_ANALYSIS`; preserve conclusions
+before relying on them. The first `preserve_evidence` call creates the user-level Flameox data
+directory and stores native bytes and a canonical evidence bundle by SHA-256. `FLAMEOX_DATA_DIR`
+overrides the platform default for isolation or another storage location. Flameox never edits
+project Git files.
 
 The agent owns hypotheses and narrative findings in its own notes. Flameox owns
 only observed inputs, effective requests, execution provenance, typed evidence,
@@ -124,14 +140,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:
+
+```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
+```
 
-- `discover_capabilities`
-- `inspect_capabilities`
-- `analyze`
-- `capture_and_analyze`
-- `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 +164,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, an explicit absolute 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.4/README.md

@@ -0,0 +1,158 @@
+<h1 align="center">flameox</h1>
+
+<p align="center"><strong>Bounded local runtime evidence for coding agents.</strong></p>
+
+<!-- mcp-name: io.github.morluto/flameox -->
+
+Flameox coordinates profilers, benchmark tools, trace processors, and direct
+local targets. It gives an agent a short path from an explicit native artifact
+or live command to bounded evidence, while keeping preservation optional.
+
+Version 0.2 is a clean break. There is no workspace to initialize, no
+`flameox.toml`, no SQLite control plane, no durable job to poll, and no parent
+directory discovery. Existing artifacts remain usable by passing their exact
+paths and formats to `analyze`; old `.diagnostics` state is not migrated.
+
+## Quick start
+
+```console
+uv sync --extra dev --extra memory --extra trace --extra cpu
+uv run flameox mcp inspect
+uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
+uv run flameox capture --provider direct --cwd "$PWD" -- python benchmark.py
+```
+
+The MCP server has no workspace or project binding:
+
+```console
+uv run flameox mcp serve
+```
+
+Run the short global setup wizard through npm:
+
+```console
+npx flameox@latest setup
+```
+
+Setup detects Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Google Antigravity, then asks
+which clients should use Flameox. It preserves unrelated client configuration and writes a
+Python 3.12 `uvx` launcher pinned to the exact Flameox release that ran setup. Restart or reconnect
+changed clients afterward. For automation, pass `--client codex --yes`, repeat `--client`, or use
+`--all --yes`; `--dry-run` reports the same global paths without writing them. Detection is never
+automation consent.
+
+Explicit `--provider` selections prepare the exact version-pinned `uvx` environment in the saved
+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 or mutates a
+project.
+
+## Authority model
+
+```text
+explicit artifact paths / typed direct target
+                    │
+                    ▼
+         bounded process-lifespan runtime
+             │                │
+             ▼                ▼
+       inline evidence   session scratch/cache
+                              │
+                       explicit preservation
+                              │
+                              ▼
+             user Flameox data directory
+```
+
+Analysis and unpreserved capture make no durable Flameox writes. Capture
+artifacts stay in bounded session scratch until preservation, least-recently-used eviction, or
+server shutdown. An evicted `analysis_id` returns `EXPIRED_SESSION_ANALYSIS`; preserve conclusions
+before relying on them. The first `preserve_evidence` call creates the user-level Flameox data
+directory and stores native bytes and a canonical evidence bundle by SHA-256. `FLAMEOX_DATA_DIR`
+overrides the platform default for isolation or another storage location. Flameox never edits
+project Git files.
+
+The agent owns hypotheses and narrative findings in its own notes. Flameox owns
+only observed inputs, effective requests, execution provenance, typed evidence,
+coverage, truncation, limitations, and optional immutable preservation.
+
+## MCP interface
+
+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:
+
+```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
+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, an explicit absolute 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 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. 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
+
+An investigation still follows:
+
+```text
+symptom → capture or explicit artifact → bounded evidence → hypothesis
+        → discriminating experiment → supported, refuted, or inconclusive finding
+```
+
+A profile supports exploration, not causality. Confirmatory claims require a
+representative target, declared metric and estimand, compatible identities,
+preserved samples, a practical threshold, and an appropriate semantic oracle.
+
+See [architecture](docs/architecture.md), [storage and evidence](docs/storage-and-evidence.md),
+[interfaces](docs/interfaces.md), [runtime safety](docs/runtime-safety.md), and
+[investigations](docs/investigations.md) for the contracts.
+
+## Development
+
+Flameox requires Python 3.12 or newer and uses the committed `uv.lock`.
+
+```console
+uv run ruff check src tests tools
+uv run ruff format --check src tests tools
+uv run mypy src tests tools
+uv run lint-imports
+uv run pytest -q
+```
+
+The project is licensed under the MIT License.

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

@@ -5,27 +5,28 @@ Flameox 是面向编码代理的本地、有界运行时证据层。它协调分
 
 0.2 是一次不兼容重构：无需初始化工作区，没有命名工作负载、SQLite 控制面、
 持久 DuckDB 目录或可轮询的后台任务。调用方直接传入原生证据的绝对路径，或
-包含 argv、项目内 cwd、环境覆盖、提供方参数和限制的类型化目标。
+包含 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"
+uv run flameox capture --provider direct --cwd "$PWD" -- python benchmark.py
+uv run flameox mcp serve
 ```
 
 `flameox setup` 会输出 MCP 客户端配置。显式传入 `--provider` 时，它可将对应的
 Python 扩展安装到持久的 uv 工具环境；NVIDIA 等系统或厂商工具则提供外部安装
-指引。setup 不会初始化项目，也不会创建 `.flameox`。
+指引。setup 不会初始化或修改项目。
 
-分析和未保存的采集不会在项目中写入 Flameox 状态。只有显式调用
-`preserve_evidence` 或 CLI 的 `--preserve` 后，才会延迟创建
-`<project>/.flameox`。原生字节和证据清单按 SHA-256 寻址，并通过同一文件系统
-上的暂存、校验、fsync 和原子重命名发布。
+分析和未保存的采集不会写入持久状态。只有显式调用 `preserve_evidence` 或 CLI 的
+`--preserve` 后，才会延迟创建用户级 Flameox 数据目录；`FLAMEOX_DATA_DIR` 可覆盖
+平台默认位置。原生字节和证据清单按 SHA-256 寻址，并通过同一文件系统上的暂存、
+校验、fsync 和原子重命名发布。Flameox 不修改项目的 Git 配置。
 
-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.4}/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.4/docs/architecture.md

@@ -0,0 +1,73 @@
+# Architecture
+
+Flameox 0.2 is a process-lifespan capability runtime with an optional immutable
+evidence repository. It is not a workspace application and has no mutable
+control plane.
+
+## Authority map
+
+| Concern | Authority |
+| --- | --- |
+| Artifact location | Exact paths supplied by each analysis request |
+| Target location | Exact absolute `cwd` supplied by each capture request |
+| Available operations | Process-lifespan capability registry |
+| In-progress work | Current MCP request and cancellation scope |
+| Unpreserved output | Bounded session scratch |
+| Completed preserved evidence | Immutable manifest in the user Flameox data directory |
+| Native bytes | Content-addressed artifact bundle |
+| Query view | Sorted manifest inventory pinned for one query |
+| Limits | Startup defaults, lowerable per request |
+| Hypotheses and narrative | Agent-owned notes outside Flameox |
+
+The runtime has no workspace identity and never searches parent directories. Analysis consumes
+explicit absolute paths. Capture consumes a typed argv and explicit absolute working directory.
+Neither is interpreted relative to server startup.
+
+## Process model
+
+`AnalysisRuntime` owns the capability registry, subprocess broker, bounded scratch,
+conversion cache, and least-recently-used session analysis cache. The MCP lifespan creates one
+runtime, exposes it through the SDK request context, and destroys its scratch on shutdown. Evicting
+a capture analysis removes its native session artifacts; a later preservation attempt reports that
+the session handle expired. Long work stays inside the request that started it. Progress is reported
+through the SDK context and cancellation unwinds the broker, including descendant cleanup.
+
+`analysis_id` is a session handle. It is intentionally meaningless after
+restart and can only be passed to `preserve_evidence`. `evidence_id` is a
+durable SHA-256 identity derived from the canonical manifest body.
+
+## Package boundaries
+
+- `runtime_contracts.py` owns public models and the capability/capture-provider registries.
+- `stateless.py` owns bounded analysis, capture orchestration, scratch, and the session cache.
+- `providers/capture.py` owns provider-specific command construction and expected native outputs;
+  `providers/availability.py` owns installation and workload requirements.
+- `repository.py` owns lazy repository creation, validation, publication,
+  inventory queries, and immutable resource reads.
+- `execution.py` and `command_binding.py` own executable binding, subprocess
+  limits, cancellation, output bounds, and descendant cleanup.
+- `mcp/server.py` and `cli.py` are thin projections over the same runtime.
+- Provider adapters accept resolved explicit inputs and return typed evidence;
+  they do not discover source trees or publish evidence.
+
+DuckDB may be used in memory for bounded aggregation. It is never a durable
+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,
+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
+output, timeouts, resource observation, and exact executable identity.