Production readiness testing

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: Bug report
+description: Report a reproducible Tomoe bug.
+title: "[bug]: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What broke?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include the smallest route, middleware, relic, or adapter code that reproduces the issue.
+      render: ts
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Tomoe version
+      placeholder: 1.0.0-rc.2
+    validations:
+      required: true
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Runtime
+      options:
+        - Bun
+        - Node.js
+        - Deno
+        - Cloudflare Workers
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Propose a focused production or DX improvement.
+title: "[feature]: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What real use case is blocked or painful?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the smallest API or behavior change that solves it.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility impact
+      description: Could this break existing apps, types, adapters, or middleware?

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+## Risk
+
+## Verification
+
+- [ ] `pnpm type-check`
+- [ ] `pnpm lint`
+- [ ] `pnpm test`
+- [ ] `pnpm build`
+
+## Compatibility
+
+- [ ] No public API change
+- [ ] Public API change documented
+- [ ] Migration note added when needed

.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 22, 24]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.6.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: pnpm type-check
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+  bun-smoke:
+    name: Bun smoke
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.6.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build package
+        run: pnpm --filter tomoejs build
+
+      - name: Run Bun smoke test
+        run: pnpm test:bun
+
+  soak:
+    name: Node soak
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.6.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run soak test
+        run: pnpm test:soak

.github/workflows/security.yml

@@ -0,0 +1,58 @@
+name: Security
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.6.5
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Audit production dependencies
+        run: pnpm audit --prod
+
+  codeql:
+    name: CodeQL
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3

CHANGELOG.md

@@ -6,7 +6,7 @@ All notable changes to the TomoeJS project will be documented in this file. This
 
 ## [1.0.0-rc.2] - 2026-05-24
 
-TomoeJS graduates to a complete, production-ready Release Candidate (`1.0.0-rc.2`)! This release brings a massive sweep of security hardening upgrades, routing optimizations, advanced middlewares, comprehensive validation enhancements, and a fully polished, zero-dependency web standard core.
+TomoeJS continues as a production-readiness Release Candidate (`1.0.0-rc.2`). This release brings security hardening upgrades, routing optimizations, advanced middlewares, validation enhancements, and a zero-dependency web standard core. Treat it as an RC until the release gates in `docs/production-readiness.md` are complete.
 
 ### 🌸 The Power of Tomoe (Key Highlights)
 * **Contract-Driven Correctness**: Declared relics and guards are validated and compiled at startup (`app.compile()`), throwing immediately on broken dependency chains rather than crashing silently in production.

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Development Setup
+
+```bash
+pnpm install
+pnpm type-check
+pnpm lint
+pnpm test
+pnpm build
+```
+
+Use small pull requests with a clear reproduction or use case. For framework behavior changes, include tests that fail before the change.
+
+## Compatibility Rules
+
+Tomoe is still in release-candidate status, but public API changes should be handled deliberately.
+
+- Avoid breaking route registration, middleware, relics, guards, context helpers, and adapters unless the change is required for correctness or security.
+- Document breaking changes in `CHANGELOG.md`.
+- Add migration notes for renamed APIs or changed runtime behavior.
+- Prefer additive APIs over replacing existing behavior.
+
+## Test Expectations
+
+Production-facing changes should include tests for at least one of:
+
+- Runtime behavior through `app.fetch`.
+- Type inference when public types change.
+- Adapter behavior for Node or Bun.
+- Error handling and edge cases.
+- Security-sensitive behavior such as headers, cookies, CSRF, validation, or body parsing.
+
+## Benchmarks
+
+Benchmarks are useful only when they are reproducible. Benchmark PRs should include:
+
+- Runtime versions.
+- Operating system and CPU.
+- Exact command.
+- Raw output or generated report.
+- Multiple runs or a note that results are single-run only.
+
+Do not update README performance claims without updating benchmark evidence.

README.md

@@ -28,6 +28,9 @@ Inspired by the design of frameworks like **Hono** and **Elysia**, Tomoe embrace
 
 However, Tomoe addresses the single largest flaw in modern web frameworks: **unsafe, untyped middleware side-effects.**
 
+> [!IMPORTANT]
+> TomoeJS is currently a release candidate, not a stable 1.0 framework. Review the [production readiness checklist](docs/production-readiness.md), [deployment guide](docs/deployment.md), [release checklist](docs/release-checklist.md), and [security policy](SECURITY.md) before using it for critical services.
+
 ---
 
 ## 🌸 The Power of Tomoe
@@ -50,7 +53,7 @@ To ensure absolute honesty and fairness, we run scientific load tests using `Aut
 * **Node version**: `v24.13.0`
 * **Bun version**: `v1.3.3` (or equivalent local version)
 * **Framework Versions**:
-  - **TomoeJS**: `v1.0.0-rc.1`
+  - **TomoeJS**: `v1.0.0-rc.2`
   - **Hono**: `v4.12.22` (Latest stable release)
   - **Elysia**: `v1.4.28` (Latest stable release)
   - **Express**: `v5.2.1` (Latest major Express 5)
@@ -70,7 +73,7 @@ Measures baseline parsing, response writing dispatch, and simple static routing.
 | **TomoeJS (Node)** | 11,433 req/s | 8.25 ms | 22 ms |
 
 > [!NOTE]
-> **Honest Comparison**: In a pure serialization test, Hono (Bun) and Elysia (Bun) utilize their custom low-level C++ request handlers in JSC to deliver outstanding throughput. TomoeJS runs exceptionally fast and neck-and-neck, serving **36,789 req/s** natively on `Bun.serve`.
+> **Historical single-run result**: In this pure serialization test, Hono (Bun) and Elysia (Bun) led the table. TomoeJS served **36,789 req/s** natively on `Bun.serve`. TomoeJS on Node was slower than Express in this report because it uses the Web Request/Response adapter path.
 
 ### 2. Radix Dynamic Routing (`/user/:id/posts/:postId`)
 Tests parameter extraction speed, rad tree traversal, and URL path segment decoding.
@@ -100,7 +103,7 @@ Tests real-world middleware execution under composition (3 sequential middleware
 | **TomoeJS (Node)** | 11,930 req/s | 7.90 ms | 14 ms |
 
 > [!NOTE]
-> **Pre-compiled for real-world load**: TomoeJS is **30% faster than Hono (Bun)** under middleware composition! While Hono and Express search and bind middleware arrays dynamically on every incoming request, TomoeJS pre-computes and compiles route-level middleware execution lists **at startup**, saving massive execution cycles.
+> **Pre-compiled middleware**: TomoeJS led this single-run middleware scenario on Bun. Treat this as a benchmark hypothesis to verify on your target deployment platform with repeated runs and raw output, not as a universal guarantee.
 
 ---
 
@@ -133,7 +136,7 @@ app.get("/me", authRelic, (ctx) => {
 * 🛡️ **Contract-Driven Type Safety**: Declare requirements (Relics) and preconditions (Guards) at startup.
 * 📦 **Standard Schema Validation**: Built-in, high-performance validation (`body`, `query`, `params`, `headers`) supporting any standard validator schema (Zod, Valibot, ArkType, etc.) and TypeBox.
 * 🍪 **Robust Cookie API**: Lazy request cookie parsing cache and RFC 6265 cookie name validation shielding against injection attacks.
-* 🛡️ **Production-Ready Middlewares**: Built-in OOM-proof Rate Limiter, Reverse-Proxy friendly Host-matching CSRF middleware, CORS, and formatted console Logger.
+* 🛡️ **Production-Oriented Middlewares**: Built-in OOM-capped Rate Limiter, Reverse-Proxy friendly Host-matching CSRF middleware, CORS, and formatted console Logger.
 * 📝 **Auto-Generated OpenAPI & Swagger UI**: Serves interactive, self-documenting `/docs` with locked Swagger UI versions (`@5.18.2`) and CORS secure links.
 * 🔌 **E2E Path-Based Client SDK**: Enjoy complete static type-safety across frontend and backend.
 
@@ -185,7 +188,7 @@ bun run index.ts
 
 ## 🌸 Flagship Example Project
 
-To see a complete, fully featured blueprint built with TomoeJS, check out our **[Anime API Example](file:///C:/Users/saif/.gemini/antigravity/scratch/tomoe/apps/examples/anime.ts)** in the `apps/examples` directory.
+To see a complete, fully featured blueprint built with TomoeJS, check out our **[Anime API Example](apps/examples/anime.ts)** in the `apps/examples` directory.
 
 It demonstrates a comprehensive, real-world setup covering:
 * 🛡️ **Guards & Relics**: Injection of shared database contexts (`dbRelic`) and API authorization guards (`apiKeyGuard`) composed dynamically via `unite(...)`.