Public engineering evidence · Grounded AI

Answers require evidence.

A Next.js and TypeScript RAG reference that treats retrieval as an untrusted input, refuses unsupported claims, validates citations, keeps providers behind server-only typed boundaries, and states exactly what is still missing before production.

Inspect the repository View Billy's portfolio
12automated and adversarial tests
100%committed-fixture citation validity
5verification gates: lint, types, tests, evals, build

Grounding controls

  • Evidence thresholds before an answer is allowed
  • Safe refusal for unsupported questions
  • Source-citation validation and untrusted-context boundaries
  • Deterministic fixtures for retrieval and answer evaluation
  • Four Playwright Chromium E2E checks covering grounded answers, refusal, API safety and layout overflow

Provider design

  • Optional OpenAI Responses API and embeddings providers
  • Server-only secrets and typed provider interfaces
  • Local deterministic behavior for repeatable tests
  • Production build and GitHub Actions verification

Human-verified AI delivery

  • AI may assist research, implementation, tests and review, but cannot approve its own output
  • Every accepted change requires reproducible evidence and a complete human diff review
  • Generated code is treated as an untrusted contribution
  • Secrets, client material, production logs and personal data stay outside prompts

Read ADR 003 and its trade-offs

Prototype-to-production decision

  • Current classification: independent reference prototype; production is explicitly not approved
  • Exit gates cover quality, security and privacy, tenant isolation, scale and latency, cost, reliability, observability, and release safety
  • No performance, scalability, availability, or cost-reduction claim exists without reproducible measurement conditions
  • The public review names the missing work and evidence required to approve each gate

Inspect the production-readiness review

Next.jsTypeScriptRAGOpenAI Responses APIEmbeddingsAdversarial testingGitHub Actions

Scope note: this is independent public evidence, not a claim of client-production RAG ownership. Percentages refer only to committed deterministic fixtures; the readiness review records a not-approved production decision until representative evidence exists.