suaveplan/openspec/archive/2026-05-18-add-api-plugin-rate-limit/tasks.md

Tasks — add-api-plugin-rate-limit

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/api-plugin-rate-limit.md
• 1.2 Read openspec/AGENTS.md §13 + §14
• 1.3 Author proposal.md from template, fill ## Source mapping
• 1.4 Author specs/api-plugin-rate-limit/spec.md from template with **Verified by:** on every requirement

2. Implementation

• 2.1 src/error-codes/error-codes.{ts,md,index.ts} — 5 codes + RateLimitPluginError
• 2.2 src/types/types.{ts,md,index.ts} — public type surface
• 2.3 src/schemas/options.{ts,md,index.ts} — RateLimitPluginOptionsSchema
• 2.4 src/path-matcher/path-matcher.{ts,md,index.ts} — compilePathPattern / matchPath / isPathMatch
• 2.5 src/headers/headers.{ts,md,index.ts} — buildRateLimitHeaders + buildRateLimitProblem
• 2.6 src/otel/instruments.{ts,md,index.ts} — counters + histogram bundle + getRateLimitInstruments / resetRateLimitInstruments
• 2.7 src/services/rate-limit-service.{ts,md,index.ts} — RateLimitService factory + createDefaultStorage
• 2.8 src/services/registry-augmentation.{ts,md} — ServiceRegistry module augmentation + registerRateLimitServiceSlot
• 2.9 src/middleware/rate-limit.{ts,md,index.ts} — rateLimit factory + rateLimitExceeded
• 2.10 src/middleware/context-augmentation.{ts,md} — Hono ContextVariableMap augmentation
• 2.11 src/plugin/plugin.{ts,md,index.ts} — createRateLimitPlugin factory; canonical 6-step onInit
• 2.12 src/index.ts — named re-exports only

3. Tests

• 3.1 Co-located *.test.ts per implementation file
• 3.2 src/api-plugin-rate-limit.spec-conformance.test.ts — every code reachable + expectTypeOf on RateLimitService / RateLimitDecision / ContextVariableMap augmentation
• 3.3 tests/integration/full-app.test.ts — real Hono app + plugin + multiple routes; 429 emission, Retry-After, per-tenant isolation, headers on allowed AND denied responses
• 3.4 tests/dep-graph.test.ts — deps + 10 subpaths + sibling .md per feature
• 3.5 All tests via @suaveplan/testing/runner, { timeout: 5000 } (30000 for integration)

4. Documentation

• 4.1 Sibling .md per impl (≥200 words, basic + advanced examples)
• 4.2 README.md — quick start + manual service.check(...) recipe + module index

5. Pre-archive gates (in order)

• 5.1 cd /home/paul/web/genesis && bun run check
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-rate-limit --force
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-rate-limit → 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-rate-limit → exit 0
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-rate-limit --force
• 5.6 bun scripts/lint/check-test-runner-imports.ts

6. Pre-archive 9-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in error-codes.ts thrown / surfaced by ≥1 production code path
• 6.4 OTel instruments emitted from production paths and asserted with real MeterProvider
• 6.5 Lifecycle dedup — onInit idempotent; lazy limiter cache rebound per (route, tenant) pair
• 6.6 No retroactive tick — every box above reflects work done in this change
• 6.7 No export * in feature barrels (verified by grep)
• 6.8 No direct vitest / bun:test imports (verified by grep)
• 6.9 No banned patterns (TODO, FIXME, .skip, .only, any) in src

7. Archive

• 7.1 Fold spec → openspec/specs/api-plugin-rate-limit/spec.md
• 7.2 mv change → openspec/archive/2026-05-18-add-api-plugin-rate-limit/
• 7.3 DO NOT refresh MANIFEST or STATUS — orchestrator consolidates after the 4-package batch