neutron-framework 0.1.0__tar.gz

neutron_framework-0.1.0/.gitignore

@@ -0,0 +1,240 @@
+# Build artifacts
+target/
+dist/
+build/
+.next/
+.svelte-kit/
+.solid/
+out/
+
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Environment & secrets
+.env
+.env.*
+!.env.example
+
+# IDE / OS
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.vscode/settings.json
+.idea/
+
+# Logs
+*.log
+server_err.log
+
+# Temporary files
+*.tmp
+*.bak
+
+# Compiled Mojo outputs
+/tmp/test_*
+
+# Archive — planning docs & research
+archive/
+**/ARCHITECTURE.md
+**/PLAN.md
+**/STATUS.md
+**/TODO-NEXT.md
+# Exception: the framework-excellence program's master plan is a tracked deliverable.
+!docs/framework-excellence/PLAN.md
+**/EXECUTION.md
+**/CHECKLIST.md
+**/NEUTRON_FINISH_CHECKLIST.md
+**/BENCHMARK_UPDATE.md
+**/competitive-analysis*.md
+**/PARITY-COMPARISON.md
+**/COMPETITOR-GAPS.md
+**/AUDIT-REPORT.md
+**/ai-ml-database-research.md
+**/SPRINT-*.md
+**/SPRINTS-*.md
+**/IMPLEMENTATION-COMPLETE.md
+**/IMPLEMENTATION_PLAN.md
+**/COMPLETION_REPORT.md
+**/ENGINEERING_EFFORT_ANALYSIS.md
+**/PROJECT_STATUS_*.md
+**/ONE_WEEK_RELEASE_PLAN.md
+**/TECHNICAL_DEEP_DIVE.md
+**/FULL_STACK_ANALYSIS.md
+**/MULTI_LANGUAGE_CLIENT_ANALYSIS.md
+**/NUCLEUS_CLIENT_SPEC.md
+**/ORM_CLIENT_STUDIO_DECISION.md
+**/NEUTRON-VS-REMIX.md
+**/NEUTRON-FEATURE-AUDIT.md
+**/ECOSYSTEM_*.md
+**/DOCS_API_ECOSYSTEM.md
+**/rust-PLAN.md
+**/DEFER-EXAMPLE.md
+**/URGENT-NOTE.md
+**/QUICK-REFERENCE.md
+**/ASTRO6-NEXTJS16-FEATURES.md
+**/SVELTEKIT-SOLIDJS-FEATURES.md
+**/REMIX-FEATURES-TO-ADOPT.md
+
+# Vercel parity / product strategy research (local only)
+/docs/VERCEL_PARITY_BACKLOG.md
+/docs/design/
+
+# Planning & audit docs
+**/NUCLEUS-AUDIT.md
+**/NUCLEUS-ROADMAP.md
+LAUNCH_PROMPTS.md
+
+# Benchmark & debug artifacts
+**/benchmark_results.json
+**/compete_results.json
+**/clippy_out.txt
+**/clippy_remain.txt
+
+# Deprecated
+mobile-preview/
+
+# Third-party benchmark apps are tracked like every other subject app — an
+# ignored subject is a benchmark row nobody else can reproduce. Their own
+# .gitignore files keep node_modules and build output out.
+
+# Observe (separate project)
+typescript/apps/observe/
+
+# Zig build artifacts
+zig/.zig-cache/
+zig/zig-out/
+
+# Mojo validation reports, research, and internal specs
+mojo/reports/
+mojo/study/
+mojo/specs/
+
+# NOT ignored: typescript/.turbo-ls-normalized.json. It looks like turbo cache
+# and was filed here as "Turbo internal", but it is the authored BASELINE that
+# `pnpm run ci:workspace` compares the workspace graph against. Ignoring it made
+# the check fail on every CI run with "Missing snapshot file" — a gate that can
+# only pass on the laptop that generated it is not a gate.
+
+# Scratch / dev tooling files
+**/do_edit.py
+**/edit_distributed.py
+**/coord_lines.py
+**/coord_methods.rs
+
+# Rust framework (rust/) — the SOURCE is tracked. Only the cargo build output is
+# ignored. (Earlier this was `/rust/` under the mistaken belief the source lived
+# in `rs/`; `rs/` was renamed to `rust/` in 6079213, so `/rust/` was silently
+# excluding the entire framework from version control. Fixed to ignore only target/.)
+/rust/target/
+
+# Site build output (source is tracked, dist is not)
+typescript/apps/site/dist/
+typescript/apps/site/.neutron/
+# Same for the playground: .neutron/runtime/entry.node.ts is emitted by
+# `neutron-ts build`, so a tracked copy goes stale the moment the codegen
+# changes and dirties the tree on every build.
+typescript/apps/playground/.neutron/
+
+# Claude internal
+.claude/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+
+# Rust — track the framework + engine lockfiles for reproducible builds.
+# (The `!rs/Cargo.lock` exception was stale: `rs/` was renamed to `rust/` in
+# 6079213, so the framework lockfile silently went untracked.)
+Cargo.lock
+!rust/Cargo.lock
+!nucleus/Cargo.lock
+# Database files
+*.db
+
+# Rust build artifacts (added after filter-repo cleanup of history)
+**/target/
+**/debug/
+*.rlib
+*.rmeta
+*.rcgu.o
+
+# ---------------------------------------------------------------------------
+# Working docs, notes and context — local only, never committed
+# ---------------------------------------------------------------------------
+# Everything above this block is a DENYLIST OF EXACT FILENAMES, added reactively
+# one name at a time. That shape cannot hold: a working note is tracked by
+# default until somebody remembers to add its exact name here, and the rule only
+# ever arrives after the file already exists. It also does nothing to a file that
+# is already tracked -- `.gitignore` does not untrack -- which is how
+# `nucleus/PARITY-COMPARISON.md` sat public on the GitHub mirror from 2026-07-20
+# while both the ignore list and the document's own first line called it
+# local-only.
+#
+# The patterns below are CONVENTIONS instead: name a note in any of these shapes
+# and it is ignored the moment it is created, without an edit here. Prefer them
+# for anything new.
+#
+# `.github/scripts/check_ignored_not_tracked.py` enforces the whole file: it
+# fails if any tracked path matches an ignore rule, so intent and reality cannot
+# drift apart again silently.
+
+# Private planning trees. `_internal/` is its own private git repo (Forgejo
+# `Tyler/neutron-internal`) — gitignored here so the public repo never sees it,
+# versioned there so it is not single-copy on one laptop.
+/_internal/
+**/_internal/
+**/_notes/
+**/_scratch/
+**/.notes/
+
+# Note/context/session filename conventions
+**/INTERNAL.md
+**/NOTES.md
+**/*_NOTES.md
+**/*-NOTES.md
+**/NOTES-*.md
+**/SESSION_*.md
+**/SESSION-*.md
+**/HANDOFF*.md
+**/*_HANDOFF.md
+**/SCRATCH*.md
+**/WIP*.md
+**/DRAFT*.md
+**/TODO.md
+**/TODO-*.md
+**/BRAINSTORM*.md
+**/RESEARCH-*.md
+**/*-RESEARCH.md
+**/POSTMORTEM*.md
+**/RETRO*.md
+**/DECISIONS.md
+**/OPEN_WORK.md
+**/PROGRESS.md
+**/ORCHESTRATION.md
+**/GROUND_TRUTH.md
+
+# The universal escape hatch: any file may be made local-only by adding `.local`
+# before its extension. Use this instead of extending the denylist above.
+**/*.local.md
+**/*.local.txt
+**/*.local.json
+**/*.local.*
+
+uv.lock
+
+# Conformance executor build output. `go build ./...` in the executor directory
+# drops a binary named after its module; it is a 10 MB artifact of running the
+# suite, not part of it.
+conformance/live/executors/go/neutron-live-conformance-go
+conformance/live/executors/rust/target/
+
+# Zig conformance executor build output.
+conformance/live/executors/zig/.zig-cache/
+conformance/live/executors/zig/zig-out/
+uuid
+status

neutron_framework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neutron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neutron_framework-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: neutron-framework
+Version: 0.1.0
+Summary: The AI application development framework for Python
+Project-URL: Homepage, https://neutron.build/
+Project-URL: Documentation, https://neutron.build/docs/python/overview
+Project-URL: Repository, https://github.com/neutron-build/neutron
+Project-URL: Issues, https://github.com/neutron-build/neutron/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: cyclopts>=3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: starlette>=0.38.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: ai
+Requires-Dist: httpx>=0.27.0; extra == 'ai'
+Provides-Extra: all
+Requires-Dist: argon2-cffi>=23.1.0; extra == 'all'
+Requires-Dist: granian>=2.0.0; extra == 'all'
+Requires-Dist: httpx>=0.27.0; extra == 'all'
+Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Provides-Extra: crypto
+Requires-Dist: argon2-cffi>=23.1.0; extra == 'crypto'
+Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'crypto'
+Provides-Extra: granian
+Requires-Dist: granian>=2.0.0; extra == 'granian'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: test
+Requires-Dist: argon2-cffi>=23.1.0; extra == 'test'
+Requires-Dist: editables>=0.5; extra == 'test'
+Requires-Dist: httpx>=0.27.0; extra == 'test'
+Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# neutron-framework
+
+The AI application development framework for Python — Starlette underneath,
+Pydantic throughout, with a first-class client for [Nucleus](https://github.com/neutron-build/neutron/tree/main/nucleus), the
+multi-model database the rest of Neutron is built on.
+
+```bash
+pip install neutron-framework
+```
+
+> The distribution is **`neutron-framework`**, not `neutron` — that name on PyPI
+> belongs to OpenStack's networking service.
+
+## A first app
+
+```python
+from pydantic import BaseModel
+from neutron import App, Router
+
+app = App(title="My API", version="1.0.0")
+router = Router()
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int) -> User:
+    return await app.db.sql.query_one(
+        User, "SELECT * FROM users WHERE id = $1", user_id
+    )
+
+app.include_router(router)
+```
+
+Return a Pydantic model and you get validation, serialisation and an OpenAPI
+3.1 schema from the same declaration. `GET /health`, `GET /openapi.json` and
+`GET /docs` are mounted for you.
+
+## What ships
+
+| Area | Module |
+|---|---|
+| Routing, handlers, dependency injection | `neutron/router.py`, `handler.py`, `depends.py` |
+| Middleware (the contract's 10-layer order) | `neutron/middleware.py`, `default_stack()` |
+| Errors as RFC 7807 problem+json | `neutron/error.py` |
+| OpenAPI 3.1 generation | `neutron/openapi.py` |
+| Nucleus client — all 14 data models | `neutron/nucleus/` |
+| AI: providers, agents, RAG, MCP | `neutron/ai/` |
+| Auth, cache, jobs, realtime | `neutron/auth/`, `cache/`, `jobs/`, `realtime/` |
+| CLI (`python -m neutron`) | `neutron/cli.py` |
+| Test helpers | `neutron/test/` |
+
+## Extras
+
+```bash
+pip install "neutron-framework[ai]"      # AI providers, agents, RAG
+pip install "neutron-framework[crypto]"  # password hashing
+pip install "neutron-framework[granian]" # the Granian server
+pip install "neutron-framework[rich]"    # richer CLI output
+pip install "neutron-framework[all]"     # everything above
+```
+
+`[test]` is the development extra and is what CI installs.
+
+## Nucleus
+
+One pgwire connection reaches every data model; the non-relational models are
+SQL functions rather than separate services or ports.
+
+```python
+from neutron.nucleus import NucleusClient
+
+db = await NucleusClient.connect("postgresql://localhost:5432/mydb")
+
+await db.kv.set("session:abc", "user-1", ttl=3600)
+await db.vector.search("docs", embedding, k=5)
+await db.document.insert("events", {"kind": "signup"})
+```
+
+Any PostgreSQL client works against Nucleus, so `asyncpg` and `psycopg` remain
+available if you would rather not use this client at all.
+
+## Documentation
+
+Published docs — overview, quickstart, routing, middleware, database, realtime,
+deployment — start at **https://neutron.build/docs/python/overview**. The wire-level
+contract every Neutron SDK implements is
+[`FRAMEWORK_CONTRACT.md`](https://github.com/neutron-build/neutron/blob/main/FRAMEWORK_CONTRACT.md); this SDK scores 12/12 on
+its conformance matrix.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Live-database tests skip unless `NEUTRON_TEST_DATABASE_URL` points at a running
+Nucleus instance.

neutron_framework-0.1.0/README.md

@@ -0,0 +1,101 @@
+# neutron-framework
+
+The AI application development framework for Python — Starlette underneath,
+Pydantic throughout, with a first-class client for [Nucleus](https://github.com/neutron-build/neutron/tree/main/nucleus), the
+multi-model database the rest of Neutron is built on.
+
+```bash
+pip install neutron-framework
+```
+
+> The distribution is **`neutron-framework`**, not `neutron` — that name on PyPI
+> belongs to OpenStack's networking service.
+
+## A first app
+
+```python
+from pydantic import BaseModel
+from neutron import App, Router
+
+app = App(title="My API", version="1.0.0")
+router = Router()
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+@router.get("/users/{user_id}")
+async def get_user(user_id: int) -> User:
+    return await app.db.sql.query_one(
+        User, "SELECT * FROM users WHERE id = $1", user_id
+    )
+
+app.include_router(router)
+```
+
+Return a Pydantic model and you get validation, serialisation and an OpenAPI
+3.1 schema from the same declaration. `GET /health`, `GET /openapi.json` and
+`GET /docs` are mounted for you.
+
+## What ships
+
+| Area | Module |
+|---|---|
+| Routing, handlers, dependency injection | `neutron/router.py`, `handler.py`, `depends.py` |
+| Middleware (the contract's 10-layer order) | `neutron/middleware.py`, `default_stack()` |
+| Errors as RFC 7807 problem+json | `neutron/error.py` |
+| OpenAPI 3.1 generation | `neutron/openapi.py` |
+| Nucleus client — all 14 data models | `neutron/nucleus/` |
+| AI: providers, agents, RAG, MCP | `neutron/ai/` |
+| Auth, cache, jobs, realtime | `neutron/auth/`, `cache/`, `jobs/`, `realtime/` |
+| CLI (`python -m neutron`) | `neutron/cli.py` |
+| Test helpers | `neutron/test/` |
+
+## Extras
+
+```bash
+pip install "neutron-framework[ai]"      # AI providers, agents, RAG
+pip install "neutron-framework[crypto]"  # password hashing
+pip install "neutron-framework[granian]" # the Granian server
+pip install "neutron-framework[rich]"    # richer CLI output
+pip install "neutron-framework[all]"     # everything above
+```
+
+`[test]` is the development extra and is what CI installs.
+
+## Nucleus
+
+One pgwire connection reaches every data model; the non-relational models are
+SQL functions rather than separate services or ports.
+
+```python
+from neutron.nucleus import NucleusClient
+
+db = await NucleusClient.connect("postgresql://localhost:5432/mydb")
+
+await db.kv.set("session:abc", "user-1", ttl=3600)
+await db.vector.search("docs", embedding, k=5)
+await db.document.insert("events", {"kind": "signup"})
+```
+
+Any PostgreSQL client works against Nucleus, so `asyncpg` and `psycopg` remain
+available if you would rather not use this client at all.
+
+## Documentation
+
+Published docs — overview, quickstart, routing, middleware, database, realtime,
+deployment — start at **https://neutron.build/docs/python/overview**. The wire-level
+contract every Neutron SDK implements is
+[`FRAMEWORK_CONTRACT.md`](https://github.com/neutron-build/neutron/blob/main/FRAMEWORK_CONTRACT.md); this SDK scores 12/12 on
+its conformance matrix.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Live-database tests skip unless `NEUTRON_TEST_DATABASE_URL` points at a running
+Nucleus instance.

neutron_framework-0.1.0/benchmarks/.gitignore

@@ -0,0 +1,8 @@
+# Generated by run_bench.py / measure_noise.py. Machine-specific throughput
+# numbers do not belong in the repository: the reproducible artifact is the
+# harness plus the pinned environment in requirements-bench.txt, not any
+# individual figure measured on one laptop. Committing them is how a number
+# nobody can reproduce ends up quoted.
+results/
+.venv-bench/
+__pycache__/

neutron_framework-0.1.0/benchmarks/README.md

@@ -0,0 +1,134 @@
+# Python ASGI Benchmark Protocol
+
+Measures `neutron-py` against its real peer set — **FastAPI, Starlette,
+Litestar** — on the same eight scenarios the TypeScript harness uses
+(`typescript/benchmarks/run-comparison.mjs`), with the same client
+(autocannon), so the two suites share vocabulary and scenario shapes.
+
+## What it tests
+
+- Frameworks (5 rows):
+  - `neutron` — `App()` with no user middleware (routing/serialization
+    overhead on top of the Starlette it wraps)
+  - `neutron-default` — `App(middleware=default_stack())`, the documented
+    production posture: a uuid4 request-id plus a structlog event per request
+  - `starlette` — bare Starlette, the floor both neutron-py and FastAPI sit on
+  - `fastapi` — `FastAPI()` defaults, pydantic-validated body
+  - `litestar` — `Litestar()` defaults, pydantic body via DTO
+- Scenarios (exact ports of the TS routes; see `bench_apps/common.py` for the
+  provenance of every constant):
+  - `static`: `GET /` (constant HTML)
+  - `dynamic`: `GET /users/1` (dict lookup + render)
+  - `compute`: `GET /compute` (140k-iteration arithmetic loop)
+  - `big`: `GET /big` (400 rows rendered per request, ~16 KB HTML)
+  - `mutate`: `POST /api/mutate` with `{"seed":13,"repeat":6000}`
+  - `login`: `GET /login` (constant HTML)
+  - `protected`: `GET /protected` with `Authorization: Bearer valid-token`
+  - `session-refresh`: `POST /api/session/refresh` (auth check, body `{}`)
+- Parity probes run against every app before any measurement: status codes,
+  byte-identical bodies, content types, and the negative-auth 401 paths.
+  `compute` and `mutate` return values are asserted equal to the TypeScript
+  implementation's values (JS and Python verified to produce 719963 and
+  258368509 respectively).
+
+## Fairness model
+
+- Same server for everyone: one uvicorn worker, `--no-access-log`, default
+  uvloop + httptools, app stdout/stderr to DEVNULL.
+- Same client for everyone: autocannon (borrowed read-only from
+  `typescript/benchmarks/node_modules`; override with `AUTOCANNON_MODULE`),
+  100 connections, HTTP/1.1, pipelining 1.
+- Frameworks run as shipped: FastAPI and Litestar keep their default
+  openapi/docs routes (not measured); `neutron-default`'s per-request logging
+  cost is measured and reported as its own row rather than hidden.
+- The TS harness measures SSR frameworks rendering HTML; these are ASGI apps
+  doing the same per-route work. In-suite comparisons are apples-to-apples;
+  cross-suite (TS vs Python) numbers are directional only.
+
+## Error policy
+
+Every run asserts zero socket errors, zero timeouts, and zero non-2xx
+responses. Violations are recorded, excluded from medians, printed, and fail
+the invocation (exit 1). A framework serving 500s fast cannot look like a
+win — this is the exact defect that produced the bad Nucleus numbers.
+
+## Run it
+
+```bash
+# one-time setup (venv lives inside python/benchmarks)
+uv venv benchmarks/.venv-bench --python 3.12
+uv pip install --python benchmarks/.venv-bench/bin/python \
+  -e ".[crypto]" fastapi "litestar[standard]" "uvicorn[standard]" httpx editables
+# peer versions are frozen in benchmarks/requirements-bench.txt — a rerun
+# should install from that file, not from latest
+
+cd python/benchmarks
+.venv-bench/bin/python run_bench.py          # main matrix
+.venv-bench/bin/python measure_noise.py --repeats 6   # noise floor + gate check
+```
+
+If `typescript/benchmarks/node_modules` is absent (it is a borrowed install,
+not a dependency of this suite), point `AUTOCANNON_MODULE` at any autocannon
+8.x — e.g. `npm install autocannon@8.0.0` in a scratch dir and export
+`AUTOCANNON_MODULE=<dir>/node_modules/autocannon`. The recorded provenance
+follows the override, so the artifact still names the client it used.
+
+Tunables (local defaults, NOT the TS CI profile): `PYBENCH_CONNECTIONS`
+(100), `PYBENCH_DURATION` (5), `PYBENCH_WARMUP` (2), `PYBENCH_RUNS` (3),
+`PYBENCH_FRAMEWORKS`, `PYBENCH_SCENARIOS`, `PYBENCH_PORT`.
+
+Outputs: `results/run-<ts>.json`, `results/latest.json`,
+`results/noise-<ts>.json` — every file carries a provenance block (machine,
+Python, package versions, client, profile, exclusions). Raw per-run rows are
+kept, not just medians.
+
+## Noise, gates, and honest limits
+
+`measure_noise.py` repeats the full matrix with rotated framework order
+(this machine's throughput drifts with warm-up state, so fixed order would
+confound framework with position), computes per-cell medians, and reports the
+worst single-repeat deviation for the neutron rows. That deviation is the
+noise floor. Do not wire a CI regression gate below it. The suggested
+thresholds follow the same derivation as
+`typescript/benchmarks/scripts/measure-gate-noise.mjs`; if the floor is too
+wide for a gate at the current profile, that is the finding — say so, don't
+tune the number.
+
+**The floor was measured (2026-08-19, Apple M4 / 10 cores / macOS): no gate
+is possible on this harness on this machine class, so none is wired.**
+Three runs, all 6 repeats of the full matrix:
+
+- Quietest attainable window (background load still swung the 1-min loadavg
+  from 7 to 35 during the run; a dev laptop is never idle while in use):
+  worst single-repeat rps drop on neutron rows **95.4%**, six cells above
+  79%.
+- Contaminated window (a concurrent 4-core `rustc` build; loadavg 8 → 98):
+  worst drop **100%** — one neutron/compute repeat measured 0 rps with zero
+  errors, a green run indistinguishable from a dead framework.
+- The interrupted 2026-08-18 run (4 repeats, "idle-ish"): worst drop
+  **76.8%**.
+
+A 10x regression is a 90% rps drop — at or below the green-run floor, so a
+threshold high enough to never fire on a green run can never fire on a real
+regression either. A paired within-repeat ratio (neutron/starlette, which
+load bursts should cancel if anything could) deviates up to 257% from its
+own median, so ratio gates are out too. The suggested-threshold column that
+`measure_noise.py` prints is a derivation, not a recommendation: when it
+says 135%, the answer is "no gate", not "gate at 135%".
+
+No competitive figures are publishable from this machine either: framework
+medians differ by less than ~26% on every scenario while single cells swing
+1.6x–36x across green repeats of the same framework. Revisit only on a
+machine whose background load is controlled (dedicated runner; the noise
+artifacts now record the per-repeat loadavg precisely so contamination is
+visible in the artifact, not inferred afterwards).
+
+## Known caveats
+
+- `compute`/`mutate` are GIL-bound pure-Python arithmetic. CPython executes
+  these loops ~10x slower than V8 executes the identical TS loops, so those
+  two scenarios measure the language runtime, not the framework; the
+  framework signal there is small relative to the interpreter cost.
+- Single machine, single worker, loopback. Numbers are not comparable to
+  other machines; the reproducible artifact is the harness plus the pinned
+  environment, not any individual figure.