SDK/API Integration

Android, iOS, BLE, Cloud API 연동자가 지켜야 할 schema와 처리 원칙을 정의한다.

API Principle

SDK/API는 measurement value를 받거나 만들지 않는다. 입력은 subject profile, candidate state, context state이며 출력은 decision, message, uiDirectives, adapterPayload, evidencePacketId다.

Android

Android adapter는 Kotlin data class와 ViewModel state로 연결된다. hapticPattern은 single-soft-pulse 등 제한된 안전 지시로 처리하고 반복 진동이나 공포 유도 UI를 금지한다.

iOS

iOS adapter는 Swift Codable schema와 feedback directive로 연결된다. HealthKit 데이터를 읽는다고 주장하지 않으며, 외부 센서 연동은 라이선시의 별도 권한·규제 책임이다.

Error Handling

NON_VALUE_RESPONSE, ORANGE_OUT_OF_RANGE, GRAY_CONTEXT_INVALID는 실패가 아니라 안전 응답이다. 앱은 이를 예외로 버리지 말고 사용자 안내와 evidence 보존 흐름으로 처리한다.

Persistence

evidencePacketId, policyVersion, timestamp, adapter directive는 보존 가능하지만 원시 건강값이나 식별 개인정보는 저장하지 않는 것이 기본 원칙이다.

Published Contract Artifacts

• TypeScript contract
• Android Kotlin models
• iOS Swift Codable models
• Evaluate request JSON Schema
• Evaluation response JSON Schema
• OpenAPI contract
• BLE / Cloud adapter contract

Safety Handling Rule

ORANGE_OUT_OF_RANGE, GRAY_CONTEXT_INVALID, and non-value style responses are 정상적인 safety response다. SDK는 이를 transport failure로 버리면 안 되며, UI directive, haptic directive, evidencePacketId, policyVersion을 보존해야 한다.

Non-Claims

• 체온, 심박, 리듬, 혈압 측정값을 이 엔진이 생성한다고 주장하지 않는다.
• 질병 확정 진단, 치료 결정, 약물 권고, 응급 분류를 수행한다고 주장하지 않는다.
• 원시 건강 데이터의 무제한 저장 또는 제3자 재사용 권한을 제공한다고 주장하지 않는다.
• 프론트엔드 색상 변화만으로 엔진 판단이 완료되었다고 주장하지 않는다.

Review Evidence

검토자는 /health/ready, /v1/docs/manifest, /v1/events/out-of-range, /v1/evidence/{id}, /v1/replay/{id}를 통해 문서 내용과 엔진 동작의 일치 여부를 확인한다.