Agent Lab

기업 데이터를 대상으로 한 AI 에이전트의 기술적 흐름을 살펴보기 위한 교육용 애플리케이션입니다. 이 프로젝트는 계약(contract), 프로토콜, 도구 호출(tool call), 구조화된 결과, 그리고 정화(sanitize)된 추적 정보를 보여줍니다.

상태

1~11단계 — 기반, MCP, Agent Runtime, 인증/RBAC, A2A, 평가, 클라우드, CI/CD, 결정론적 계약, 회복 탄력성, 의미론적 견고성:

• React + Vite 프론트엔드;

• Node.js + Express 백엔드;

• PostgreSQL 스키마 및 마이그레이션;

• admin 및 viewer 애플리케이션 사용자;

• 결정적 달력 기간;

• TraceEvent 기술 계약;

• 단위 테스트 및 Agent Lab의 시각적 셸;

• stdio 전송을 사용하는 공식 MCP 서버;

• 구조화된 응답을 반환하는 읽기 전용 MCP 도구 7개;

• 최소 권한 역할을 이용한 매개변수화된 PostgreSQL 질의;

• qwen3:8b을 사용하는 Ollama로 로컬 추론 및 툴 콜링 지원(토큰 비용 없음);

• 선택적 프로바이더로 유지하는 OpenAI Responses API;

• 도구 검색과 실행이 가능한 로컬 MCP 클라이언트;

• grounded 오케스트레이터 및 POST /api/agent/query 엔드포인트;

• 실제 응답과 기술 추적을 함께 표시하는 쿼리 인터페이스;

• PostgreSQL에 저장되는 불투명 세션 기반 인증;

• HttpOnly, SameSite=Strict 쿠키 및 만료 시간 설정 가능;

• admin 및 viewer 프로필의 RBAC 권한 부여;

• 감사 로그가 남는 사용자 등록 및 HR 데이터의 트랜잭션 삭제;

• A2A 1.0 Agent Cards를 게시하는 두 개의 에이전트;

• JSON-RPC SendMessage를 통한 HR → 재무 부서 위임;

• 라이프사이클과 구조화된 Artifact를 갖춘 재무 업무;

• MCP를 통해 조회한 결근 손실 보고서.

• 결정적 어서션(assertion) 기반 통합 평가 스위트;

• 참조 케이스, 빈 결과, PostgreSQL 신선도 검증;

• 정리 보장과 잔여 검증이 있는 격리된 동적 픽스처.

• 예산을 할당한 타임아웃, 제한된 일시 재시도, 핫 인스턴스별 서킷 브레이커;

• 내러티브만 실패한 경우에도 grounded answerPayload를 보존하는 안전한 성능 저하(degradation);

• 제어된 장애 주입을 통한 회복 탄력성 평가.

• 중립적·비격식·리오플라텐세 스페인어를 LLM 의미 제안으로 해석;

• MCP 호출 전에 capability, schema, 기간, 극성, 비즈니스 범위 한계 백엔드 검증;

• PostgreSQL에 접근하지 않는 clarification 및 미지원 쿼리 결정의 타입 지정;

• before/after 기준선과 실행 반복 간 안정성을 지닌 버전 관리형 언어 벤치마크.

이 애플리케이션은 정적 프론트엔드를 Render에, serverless 백엔드를 Vercel에, PostgreSQL을 Neon에 배포하고 있습니다. GitHub Actions는 프로덕션 대상 quality gates와 smoke tests를 적용합니다.

Related MCP server: Employee Management MCP Server

구조

frontend/   React, inspector técnico y system index
backend/    API, dominio, migraciones, acceso PostgreSQL y trazas

요구 사항

• Node. 로컬 qwen3:8b 모델.

• npm 10 이상.

• Ollama 0.32 이상 및 로컬 모델 qwen3:8b.

• 프로바이더가 허용하는 경우 분리된 자격 증명 세 개를 갖춘 PostgreSQL cloud.

설치

npm --prefix backend install
npm --prefix frontend install

backend/.env.example을 backend/.env로 복사하고, 포스트그레SQL 프로바이더 URL을 입력합니다. DATABASE_READONLY_URL 또는 DATABASE_ADMIN_URL에는 소유자(owner) 자격 증명을 넣지 않습니다.

기본 프로바이더는 로컬 Ollama입니다:

LLM_PROVIDER=ollama
OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=qwen3:8b

Ollama를 설치하고 ollama pull qwen3:8b를 한 번 실행하여 모델을 다운로드합니다. 추론은 로컬 CPU/GPU와 저장소를 사용하므로 유료 API 비용이 발생하지 않습니다.

OpenAI는 LLM_PROVIDER=openai, OPENAI_API_KEY 및 OPENAI_MODEL을 설정해 대안으로 사용할 수 있습니다. 키는 Git이 무시하는 backend/.env에만 존재해야 하며, 프론트엔드로 전송하거나 추적(trace)에 포함하면 안 됩니다.

데이터베이스

1. 클라우드 프로바이더에 PostgreSQL 데이터베이스를 만듭니다.

2. backend/ops/database-roles.example.sql을 참조하여 역할을 만들거나 구성합니다.

3. 환경 변수를 설정합니다.

4. 다음을 실행합니다:

npm --prefix backend run db:migrate
npm --prefix backend run db:seed
npm --prefix backend run db:smoke
npm --prefix backend run db:verify-permissions

db:smoke은 DATABASE_READONLY_URL만 사용하며, 날짜 파라미터로 hr_late_arrivals 뷰를 조회합니다.

시드(seed)는 SEED_ADMIN_PASSWORD와 SEED_VIEWER_PASSWORD가 각각 12자 이상이어야 합니다. 저장소에는 기본 비밀번호가 없습니다.

개발

두 개의 터미널에서 실행합니다:

npm run dev:backend
npm run dev:frontend

• 프론트엔드: http://localhost:5173

• 백엔드: http://localhost:3000

클라우드 DB 없이 검증

npm test
npm run typecheck
npm run build

달력 테스트는 다음을 검증합니다:

• 이번 달의 1일부터 오늘까지(포함);

• 이전 달력의 전체 월;

• 윤년 2월;

• 최근 30일의 달력 날짜.

시간 구간

인터페이스는 포함 범위 날짜를 사용하지만 내부적으로는 반열린(seab–open) 구간을 사용합니다:

startInclusive <= timestamp < endExclusive

이렇게 하면 23:59:59에 의존하지 않으면서 PostgreSQL의 정밀도를 올바르게 유지할 수 있습니다.

추적성

프론트엔드는 기술 이벤트를 다음 정보와 함께 표시합니다:

• 이벤트 이름;

• 기술;

• 구성 요소;

• 카테고리;

• 관련 개념;

• 정화된 입력 및 출력;

• 소요 시간 및 상태.

자격 증명, 세션 토큰, 모델의 내부 추론은 표시되지 않습니다.

MCP Server

이 서버는 Model Context Protocol 공식 SDK를 사용하여 다음을 제공합니다:

• count_employees: 총·활성·비활성 직원 수를 계산합니다;

• list_employees: 직원 번호, 이름, 부서, 상태가 포함된 전체 디렉터리를 나열합니다;

• find_employee: 이름 또는 직원 번호로 검색합니다;

• summarize_employee_delays: 이름이나 직원 번호를 이용해 한 사람의 지각 이력을 집계합니다;

• list_late_arrivals: 기간과 선택된 직원을 기준으로 지각 목록을 조회합니다;

• list_employees_without_late_arrivals: 기간 동안 지각한 직원이 없는 활성 직원을 PostgreSQL에서 계산합니다;

• list_absences: 기간과 선택된 직원을 기준으로 결근 목록을 조회합니다.

이 도구들은 readOnlyHint을 선언하고, Zod로 입력과 출력을 검증하며, 텍스트 콘텐츠와 structuredContent를 모두 반환합니다. 결과에는 출처, 쿼리 시간, 적용 기간, 총 개수, 잘림(truncation) 신호가 포함됩니다. 각 호출은 PostgreSQL을 다시 조회하며, 이 단계에는 캐시가 없습니다.

로컬 MCP 서버를 시작하려면:

npm run mcp:server

검색, 실제 호출, 시드 데이터 및 빈 결과를 확인하려면:

npm run mcp:smoke

stdout은 MCP 프로토콜 전용으로 예약되어 있으며, 운영 오류는 stderr로 보내고 클라이언트 응답은 정화됩니다.

Agent Runtime

구현된 흐름:

React → POST /api/agent/query → HrAgentOrchestrator
      → Ollama local + qwen3:8b (tool calling)
      → MCP Client → MCP Server → PostgreSQL
      → tool result → Ollama → respuesta + TraceEvent[]

MCP 클라이언트는 사용 가능한 도구를 검색하지만, 라우터는 모델에 실행 시간별로 제어되는 허용 목록(allowlist)의 단일 정의만 제공합니다. function calling의 스키마는 엄격하며, 병렬 호출은 비활성화되어 있어 개별 실행을 쉽게 검사할 수 있습니다.

grounded: true는 오케스트레이터가 승인된 도구 호출을 확인하고 최종 응답을 요청하기 전에 structuredContent를 받았다는 뜻입니다. 이것은 모델이 생산한 각 토큰에 수학적 보장이 존재한다는 의미가 아니며, 이 품질은 평가로 측정해야 합니다.

시스템 프롬프트는 기업 데이터가 반드시 도구에서만 나와야 하고, 빈 결과는 명시적으로 보고해야 하며, 받은 콘텐츠는 명령어가 아닌 데이터로 취급해야 한다고 요구합니다.

결정적 통합 테스트(API 소비 없음):

npm run agent:smoke

로컬 Ollama, MCP, Neon을 사용한 실제 테스트:

npm run agent:smoke:ollama

Groq, MCP, Neon을 사용한 실제 테스트:

npm run agent:smoke:groq

OpenAI, MCP, Neon을 사용한 선택적 테스트:

npm run agent:smoke:openai

엔드포인트:

POST /api/agent/query
Content-Type: application/json

{"question":"¿Qué empleados llegaron tarde durante el último mes?"}

응답에는 answer, model, grounded, toolsUsed 및 정화된 기술 이벤트 시퀀스가 포함됩니다. 토큰, 자격 증명, 내부 추론은 포함되지 않습니다.

의미론 견고성, 라우팅 검증, 결정적 프레젠테이션

LLM은 제어된 일곱 가지 capability를 받고 정확히 하나의 의사 결정을 제안합니다. 백엔드는 이 제안을 신뢰하지 않습니다: MCP 호출을 허용하기 전에 허용 목록, Zod 스키마, 사용자가 표현한 기간, 극성, 비즈니스 범위 한계를 확인합니다:

LLM propone → backend valida → MCP ejecuta → PostgreSQL → payload determinista

MCP 도구 7개 외에도 플래너에는 MCP에 전달되지 않는 내부 의사 결정이 두 가지 있습니다: request_clarification 및 reject_unsupported_query. 전자는 을 기간이 부족하거나 모호한 경우 agent_clarification_required을 반환하고, 후자는 요청이 아닌 능력, 순위, 빈도 또는 필터를 요구하면 unsupported_agent_query를 반환합니다. 공개 카탈로그는 GET /api/agent/capabilities에서 조회할 수 있으며 System index에도 표시됩니다.

비격식 표현은 의미로 해석됩니다. 예를 들어 "llegar", "entrar", "caer"란 단어들, "fichar" 또는 "marcar tarde"는 late_arrivals를 의미할 수 있습니다. "sin tardanzas" 및 "siempre puntual"는 명시된 기간 내에서만 제로(0) 이벤트로 해석됩니다. "band", "una bocha", "siempre" 또는 "seguido" 같은 표현은 임의로 숫자로 변환되지 않습니다.

MCP 실행 후 AnswerPresentation는 판별 유니온(discriminated union)을 사용해 structuredContent를 검증합니다. API는 두 가지 서로 다른 표면을 반환합니다:

• presentation: 타입이 지정된 결정적 answerPayload이며, 특정 React 컴포넌트로 렌더링됩니다;

• answer: LLM이 생성한 grounded 내러티브이며, 비결정적(non-deterministic)이라는 표시가 있는 보조 패널에 표시됩니다.

수량·테이블·날짜·빈 상태·출처 메타데이터는 presentation에서 표시되며 모델 텍스트에서 추출하지 않습니다. 11단계는 9단계의 이 계약을 변경하지 않습니다. 추적에는 제안-검증-결정적 표시를 분리하기 위한 llm.semantic_proposal.completed, agent.semantic_decision.validated, presentation.payload.validated 이벤트가 포함됩니다.

부정적 질의의 구현은 차집합입니다: 해당 기간에 지각이 한 번이라도 있는 활성 직원을 제외한 나머지입니다. 이 의미는 NOT EXISTS을 통해 PostgreSQL이 수행하며 LLM이 여집합을 계산하지 않습니다. Groq가 빈 최종 응답을 반환하거나, 최종 단계에서 두 번째 도구 호출을 시도하면 어댑터는 동일한 grounded 데이터로 텍스트 재시도를 한 번 수행합니다. llm.grounded_response.completed 이벤트는 recovery=not_required, 재시도한 여러 유형 또는 결정적 표시로의 fallback을 보고합니다.

LLM 프로바이더 회복탄력성

10단계는 외부 장애를 네 가지 명시적 메커니즘으로 처리합니다:

공개 엔드포인트 GET /api/resilience는 정책과 회로의 위생 처리된 상태를 노출하며, 자격 증명은 절대 노출하지 않습니다. 에이전트는 각 핫 인스턴스 내에서 재사용되어 circuit breaker가 요청 간 상태를 유지합니다. Vercel에서 각 인스턴스는 자체 회로를 보유합니다. 전역 조정은 분산 스토어를 요구하며 이 실험실에서는 정당화되지 않습니다.

초기 계획이 실패하면 아직 MCP 호출이나 grounded 데이터가 없으며 API는 타입화된 오류(llm_timeout, llm_rate_limited, llm_provider_unavailable 또는 llm_circuit_open)를 반환합니다. 최종 작성만 실패하면 API는 결정적 테이블로 성공 응답을 반환하고 llm.grounded_response.degraded를 발행합니다.

인증 및 권한 부여

자격 증명은 app_users의 bcrypt 해시와 대조하여 검증됩니다. 인증 시 백엔드는 무작위 토큰을 생성하고, app_sessions에 SHA-256 해시만 저장하며, HttpOnly 쿠키를 통해 토큰을 전달합니다. 프론트엔드는 토큰에 절대 접근하지 않습니다.

지속 시간은 SESSION_TTL_HOURS=8로 구성됩니다.

애플리케이션 권한:

• viewer: 에이전트에 질의하고 기술 인덱스를 볼 수 있음;

• admin: 질의 기능, 사용자 생성, 운영 데이터의 통제된 삭제를 포함.

관리자 삭제는 DROP DATABASE를 실행하지 않습니다. 단일 트랜잭션 내에서 attendance_records, employees, departments를 삭제하며, 스키마, 사용자, 세션 및 audit_events는 보존합니다. 리터럴 DELETE HR DATA 확인이 필요하며 결과는 감사 로그에 기록됩니다.

PostgreSQL 역할 app_admin은 DROP, CREATE DATABASE, 슈퍼유저 또는 neon_superuser 멤버십이 없습니다. 이 분리는 애플리케이션 RBAC와 데이터베이스 권한이 별개의 계층임을 보여줍니다.

두 사용자와 전체 세션 주기의 실제 테스트:

npm run auth:smoke

에이전트 및 A2A

프로젝트는 공식 SDK @a2a-js/sdk로 A2A Protocol 1.0을 구현합니다:

• HR Grounding Agent: MCP를 통한 grounded 직원 및 출석 조회;

• Absence Finance Agent: 결근의 결정적 경제 분석.

Agent Cards:

/.well-known/agent-card.json
/.well-known/hr-agent-card.json
/.well-known/finance-agent-card.json

금융 흐름:

Usuario → HR Agent / A2A Client
        → descubre Finance Agent Card
        → JSON-RPC SendMessage
        → Finance Agent Task: submitted → working
        → MCP list_absences → PostgreSQL
        → calculadora determinista
        → A2A Artifact application/json
        → Task completed → reporte + TraceEvent[]

A2A 엔드포인트는 무작위 내부 bearer 토큰을 사용합니다. Agent Card는 보안 스키마를 설명하지만 자격 증명은 절대 포함하지 않습니다.

데이터베이스에는 급여가 없습니다. 따라서 보고서는 명시적 매개변수를 요구합니다: 통화, 일일 비용, 대체 프리미엄 및 생산성 영향. 공식은 다음과 같습니다:

días × costo diario × (1 + prima de reemplazo + impacto de productividad)

LLM은 산술을 수행하지 않습니다. 결정적 TypeScript 함수가 소수점 둘째 자리로 반올림된 금액을 계산합니다. MCP가 결과가 잘렸음을 표시하면 에이전트는 불완전한 보고서를 피하기 위해 계산을 거부합니다.

구현은 흐름이 짧고 동기적이므로 인메모리 A2A 작업을 사용합니다. 여러 인스턴스 또는 장기 작업의 경우 TaskStore를 영구 저장소로 마이그레이션해야 합니다.

Agent Card, A2A, MCP 및 Neon의 실제 테스트:

npm run a2a:smoke

에이전트 평가

단위 테스트는 통제된 종속성으로 함수와 계약을 검증합니다. 평가 스위트는 구성된 모델, MCP 및 PostgreSQL로 실제 에이전트의 전체 동작을 측정합니다.

구현된 사례:

• employee-count: 수량 질문이 count_employees로만 라우팅되는지 확인;

• employee-directory: 이름 요청이 list_employees로 라우팅되고 디렉토리를 검색하는지 확인;

• employee-delay-summary: summarize_employee_delays를 통한 Bruno Silva 지연의 결정적 집계 확인;

• employees-without-late-arrivals: 부정 라우팅, 집합 차이 및 예상 결과 EMP-003 확인;

• known-late-arrivals: 도구, grounding 및 수량을 시드 데이터셋과 비교;

• unknown-employee: 빈 PostgreSQL 결과와 발명된 데이터가 없는 명시적 응답 요구;

• source-of-truth-freshness: 고유한 임시 직원과 지각을 삽입하고, 새로 생성된 레코드를 조회하여 에이전트가 업데이트를 관찰하는지 확인.

• finalization-failure-degradation: MCP 이후 통제된 실패를 주입하고 PostgreSQL 페이로드가 계속 사용 가능한지 확인.

• semantic-robustness-v1: 중립적, 공식적, 비공식적, 리오플라텐세 및 경계 표현 80개를 실행하고 의도, 결정, 논거, 시간성, 모호성 및 안정성을 측정.

동적 픽스처는 준비 및 정리 중에만 관리 역할을 사용합니다. 에이전트 조회는 계속 읽기 전용 역할을 사용합니다. finally 블록이 정확한 UUID와 직원 번호로 삭제하며, 완료 후 추가 조회로 EVAL-% 직원이나 agent-evaluation 소스의 출석이 존재하지 않음을 확인합니다.

구성된 LLM 공급자, MCP 및 Neon으로 실제 실행:

npm run evals:run
npm run resilience:eval
npm run semantic:eval
npm run semantic:stability

semantic:eval은 80개 사례를 한 번 순회하고 semantic:stability는 중요 집합을 다섯 번 반복합니다. 둘 다 validDecisionRate, intentRecognitionRate, toolSelectionRate, argumentExtractionRate, temporalInterpretationRate, exactOutcomeRate, stabilityRate, ambiguityPassRate 및 unsupportedPassRate를 보고합니다. 기본적으로 Groq의 무료 토큰 예산을 존중하고 공급자 한도를 의미론적 불안정성과 분리하기 위해 호출 간 30초를 기다립니다. Stage 10 기준선은 backend/evals/baselines/에 보존되고 Stage 11 결과는 backend/evals/results/에 있습니다.

다른 명령은 passRate, 기간, 예상/실제 검사 및 사례별 grounded 증거가 포함된 재현 가능한 JSON을 반환합니다. 평가 실패 또는 임시 픽스처가 남아 있으면 0이 아닌 코드로 종료됩니다. 참조 사례는 데모 시드가 존재한다고 가정합니다.

클라우드 배포

저장소는 frontend/와 backend/를 분리하여 유지하며 두 개의 배포 표면이 있습니다:

• agent-lab-ignac: Render Static Site로 제공되는 Vite 프론트엔드;

• agent-lab-api-ignac: Fluid Compute를 사용하는 Vercel Function으로 제공되는 Express 백엔드.

프로덕션 URL:

• 애플리케이션: https://agent-lab-ignac.onrender.com;

• API: https://agent-lab-api-ignac.vercel.app;

• 직접 health check: https://agent-lab-api-ignac.vercel.app/api/health.

render.yaml은 프론트엔드만 관리하고 /api/*를 https://agent-lab-api-ignac.vercel.app으로 재작성합니다. 브라우저의 경우 인증과 쿠키는 프론트엔드 오리진 아래에 유지되며, 세션 토큰은 HttpOnly로 유지되어 React에 노출되지 않습니다.

backend/vercel.json은 Express, 최대 300초 및 Neon 데이터베이스에 가까운 gru1(상파울루) 지역을 선언합니다. Vercel은 src/app.ts가 내보낸 lazy handler를 감지합니다. 애플리케이션과 해당 풀은 인스턴스가 첫 번째 요청을 받을 때 초기화됩니다. src/server.ts는 로컬 개발을 위해 app.listen()을 유지합니다.

MCP 전송은 MCP_TRANSPORT로 선택됩니다:

• stdio: 로컬 개발, 클라이언트가 독립 MCP 프로세스를 시작;

• in_process: Vercel, 클라이언트와 MCP 서버가 인메모리 전송 쌍으로 연결되며 프로토콜, 계약, 검증 및 tool discovery를 잃지 않음.

로컬 개발에서 LLM_PROVIDER=ollama는 qwen3:8b를 유지합니다. Vercel에서 LLM_PROVIDER=groq는 function calling을 지원하는 openai/gpt-oss-20b를 사용합니다. Groq 어댑터는 최소 하나의 도구를 강제하고 grounded 응답을 생성하기 위해 결과를 모델에 반환합니다.

Vercel 프로젝트에 필요한 프로덕션 변수:

NODE_ENV=production
FRONTEND_ORIGIN=https://agent-lab-ignac.onrender.com
APP_TIMEZONE=America/Argentina/Buenos_Aires
SESSION_TTL_HOURS=8
PUBLIC_BASE_URL=https://agent-lab-api-ignac.vercel.app
MCP_TRANSPORT=in_process
LLM_PROVIDER=groq
GROQ_MODEL=openai/gpt-oss-20b
GROQ_API_KEY=<secret>
LLM_TIMEOUT_MS=12000
LLM_TRANSIENT_RETRIES=1
LLM_CIRCUIT_FAILURE_THRESHOLD=3
LLM_CIRCUIT_RESET_MS=30000
DATABASE_READONLY_URL=<secret>
DATABASE_ADMIN_URL=<secret>
A2A_INTERNAL_TOKEN=<secret-aleatorio-de-32-o-mas-caracteres>

공개 백엔드는 Helmet 헤더, rate limit, 명시적 오류 처리 및 GET /api/health를 추가합니다. 인메모리 제한은 데모용이며 핫 인스턴스별로 작동합니다. 분산 프로덕션 애플리케이션은 공유 스토어를 사용합니다. PostgreSQL이 사용자, 세션 및 데이터를 보존하므로 서버리스 파일시스템은 폐기 가능한 상태로 유지됩니다.

CI/CD 및 품질 게이트

main에 대한 각 push와 각 pull request는 .github/workflows/ci.yml을 실행합니다. 백엔드와 프론트엔드는 Node.js 22에서 독립적이고 재현 가능한 작업으로 검증됩니다:

checkout → npm ci → typecheck → build → tests → audit de dependencias productivas

npm ci는 각 package-lock.json에 고정된 정확한 트리를 설치합니다. 작업은 저장소에 대한 읽기 권한만 가지며, timeout이 있고 같은 브랜치의 이전 실행을 취소합니다. 프로덕션 자격 증명은 CI 워크플로우에 전달되지 않습니다.

Vercel은 backend/를 Root Directory로 저장소에 연결되어 있으며, main에 수락된 커밋이 서버리스 배포를 생성합니다. Render는 frontend/에서 정적 프론트엔드를 유지합니다. 이 분리는 두 가지 제어를 구분합니다:

• 런타임 이전 품질 게이트: 타입, 컴파일, 테스트 및 감사;

• 배포 이후 smoke test: 실제로 배포된 공개 HTTP 계약.

.github/workflows/production-smoke.yml은 성공적인 배포 상태를 수신하고 수동 실행도 허용합니다. scripts/production-smoke.mjs는 다음을 확인합니다:

• Vercel 백엔드의 직접 health;

• /api/system 계약 및 현재 단계;

• /api/resilience의 공개 계약;

• Render 오리진에서 제공되는 /api/* 프록시;

• 프론트엔드 HTML 문서의 가용성.

동일한 프로덕션 계약의 로컬 실행:

node scripts/production-smoke.mjs