AGENTS.md

Operating rules for anyone — human or AI — working on justapi Runtime.
Read this before touching code. If you are an AI agent resuming after a
context reset, read this file and PLAN.md first, in that order.

1. The one rule that overrides everything else

Do not begin a phase in PLAN.md until the previous phase's exit criteria
are checked off there. If you're unsure whether a gate passed, check
BENCHMARKS.md and CI history — don't assume.

2. Rust-first implementation mandate

If a feature can be implemented in Rust, it must be implemented in Rust — not in the
Python package. Python is reserved for application-facing glue and user callbacks only.

This is the runtime's core performance thesis (see DECISIONS.md ADR-008: "Rust owns I/O and
scheduling, Python owns application logic"). Concretely, the following belong in Rust and must
not be re-implemented under crates/justapi-py/python/justapi/:

• Networking, sockets, TLS, connection management.
• HTTP/protocol parsing and response writing.
• Routing, middleware chaining, rate-limiting, auth/JWT/OAuth2 validation.
• Scheduling, worker/thread pools, background-task execution, concurrency primitives.
• (De)serialization of framework data (encoding bodies/responses for the framework, not user
  callbacks).
• Hot paths: parsing, validation, buffering, compression.

Python in the framework package is acceptable only for:

• Thin PyO3 re-exports / binding glue (from ._justapi import X).
• Translating between Rust values and Python callables (e.g. invoking a user route/handler).
• User-facing helpers that are not on a hot path and have no Rust equivalent.

Before adding Python logic to the framework, ask: "Could this live in justapi-core /
justapi-py Rust instead?" If yes, put it in Rust.

3. Roles

Even in single-agent execution, work through these lenses in sequence for
any non-trivial change — they catch different classes of mistakes:

• Core Runtime — networking, protocol, memory, scheduler correctness and
  safety (justapi-core).
• Python Bindings — PyO3 boundary, GIL/free-threading correctness, the
  ASGI shim, native API (justapi-py).
• Protocol/Security — TLS, auth, JWT, OAuth2/OIDC, request validation,
  SAST scanning, fuzzing, anything parsing untrusted input.
  Every change here needs a fuzz target or an explanation of why not.
• Data & Validation — Pydantic-style schemas, DB ORM integration,
  serialization, type-safe request/response contracts, background tasks.
• Resilience — circuit breakers, graceful degradation, retry policies,
  rate-limit backpressure, connection pooling.
• QA/Benchmark — owns BENCHMARKS.md, the CI regression gate, and
  calling out unqualified performance claims. Target: beat FastAPI on every
  benchmark.
• Platform/DX — CLI, hot reload, OpenAPI generation, Docker/K8s tooling,
  multi-cloud deployment, skills/ directory upkeep.
• Observability — distributed tracing (OTel), structured logging, metric
  dashboards, health checks, alerting integration.

4. Conventions

• Commits: <emoji> <phase>: <what changed> e.g. 📦 p3: add per-request arena allocator. One logical change per commit.
• Commit size: Keep each commit under 100 lines of diff (git diff --cached --stat). If a file is over 100 lines, split it into smaller
  files (types.rs, message.rs, state.rs instead of a single
  mod.rs). Use git add -p to stage partial hunks if needed.
  Exceptions: Cargo.lock (auto-generated) and single cohesive files at
  ~140 lines max.
• Branches: phase-N/<short-description>.
• unsafe code: every block needs a // SAFETY: comment explaining the
  invariant that makes it sound, and a test that would fail if the invariant
  were violated where feasible.
• New dependency: justify it in DECISIONS.md — what it replaces or
  enables, why the alternative (usually: writing it yourself) is worse.
• Public API changes: rustdoc/docstrings required before merge, not after.
• Error handling: use anyhow::Result in application code (CLI, bench);
  use typed errors (thiserror) in library crates (justapi-core,
  justapi-py) for errors that cross crate boundaries.

5. Before opening a PR / calling a phase done

• No feature that could be Rust was added in Python (see §2); new framework
  Python is glue only
• Tests pass (cargo test --workspace)
• cargo clippy --workspace --tests -- -D warnings clean (includes test code)
• cargo fmt --check clean
• cargo miri test -p justapi-core clean (if core touched)
• Benchmarks run, numbers appended to BENCHMARKS.md (not overwritten)
• No p99 regression >5% vs. previous phase without a DECISIONS.md entry
• PLAN.md updated: phase status, next steps
• New recurring pattern or gotcha? Add/update a skills/*/SKILL.md

6. Resuming work after a context reset

1. Read PLAN.md — find the current phase and its status.
2. Read the most recent DECISIONS.md entries for context on why things are
   the way they are.
3. Skim relevant skills/*/SKILL.md files for the area you're touching.
4. Check BENCHMARKS.md for the last recorded numbers so you know the bar.
5. Continue from where PLAN.md says to continue — don't restart planning
   from scratch.

7. When something in the master prompt seems wrong

It might be. If a requirement conflicts with something you've learned during
implementation (e.g., a benchmark shows a "required" custom scheduler isn't
needed, or a crate assumption in the master prompt is stale), write the
conflict and your recommendation into DECISIONS.md and proceed with the
better-informed choice. Don't silently deviate, and don't blindly follow a
now-wrong instruction either.

8. Architecture quick reference

justapi/
  Cargo.toml                # workspace root
  crates/
    justapi-core/          # networking, protocol, scheduler, memory
    justapi-py/            # PyO3 bindings, ASGI shim, native API
    justapi-cli/           # `justapi` CLI binary
    justapi-bench/         # internal benchmark harness
  python/
    justapi/               # pip-installable Python package (maturin-built)
  skills/                   # reusable knowledge modules
  benchmarks/               # workload scripts for baseline comparisons
  AGENTS.md                 # this file
  PLAN.md                   # living roadmap (single source of truth)
  DECISIONS.md              # append-only ADR log
  BENCHMARKS.md             # append-only results ledger
  PROMPT.md                 # master engineering prompt (reference only)

Request pipeline (target shape)

Kernel → epoll/io_uring → Connection Manager → tokio task
  → TLS (rustls) → HTTP parse (hyper) → Router (matchit)
  → Middleware chain (Rust: auth/CORS/rate-limit/compression)
  → Python boundary (typed, zero-copy request view via PyO3 buffer protocol)
  → Application code (ASGI shim OR native handler)
  → Rust serializer (serde_json/simd-json)
  → Response write → Socket

Crate dependency graph

justapi-cli → justapi-core
justapi-py  → justapi-core
justapi-bench → justapi-core

9. Key skills to consult

Add new skills as patterns emerge. A good skill saves the next session from
rediscovering a non-obvious invariant or workflow.