workflowConstraints
+) {
+
+ public MaskedAnalysisInput {
+ Objects.requireNonNull(maskedInstruction, "maskedInstruction must not be null");
+ Objects.requireNonNull(workers, "workers must not be null");
+ Objects.requireNonNull(workflowConstraints, "workflowConstraints must not be null");
+ workers = List.copyOf(workers);
+ workflowConstraints = List.copyOf(workflowConstraints);
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/model/MaskedWorkerContext.java b/src/main/java/com/fowoco/server/aiintegration/application/model/MaskedWorkerContext.java
new file mode 100644
index 0000000..191cb8f
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/model/MaskedWorkerContext.java
@@ -0,0 +1,25 @@
+package com.fowoco.server.aiintegration.application.model;
+
+import java.time.LocalDate;
+import java.util.Objects;
+import java.util.UUID;
+
+/**
+ * Minimum worker context allowed to cross the AI boundary.
+ *
+ * Legal name, phone, passport number, residence number, account number, and document contents
+ * must never be added here.
+ */
+public record MaskedWorkerContext(
+ UUID workerRef,
+ String preferredLanguage,
+ String workStatus,
+ LocalDate stayExpiryDate
+) {
+
+ public MaskedWorkerContext {
+ Objects.requireNonNull(workerRef, "workerRef must not be null");
+ Objects.requireNonNull(preferredLanguage, "preferredLanguage must not be null");
+ Objects.requireNonNull(workStatus, "workStatus must not be null");
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/model/WorkflowConstraint.java b/src/main/java/com/fowoco/server/aiintegration/application/model/WorkflowConstraint.java
new file mode 100644
index 0000000..8130ca7
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/model/WorkflowConstraint.java
@@ -0,0 +1,19 @@
+package com.fowoco.server.aiintegration.application.model;
+
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * Knowledge-owned Workflow identifiers and slot names that the Runtime may return.
+ */
+public record WorkflowConstraint(
+ String workflowId,
+ Set allowedSlotKeys
+) {
+
+ public WorkflowConstraint {
+ Objects.requireNonNull(workflowId, "workflowId must not be null");
+ Objects.requireNonNull(allowedSlotKeys, "allowedSlotKeys must not be null");
+ allowedSlotKeys = Set.copyOf(allowedSlotKeys);
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/port/AiRuntimeClient.java b/src/main/java/com/fowoco/server/aiintegration/application/port/AiRuntimeClient.java
new file mode 100644
index 0000000..c55a03f
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/port/AiRuntimeClient.java
@@ -0,0 +1,15 @@
+package com.fowoco.server.aiintegration.application.port;
+
+import com.fowoco.server.aiintegration.application.model.AiAnalysisRequest;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+
+/**
+ * Server-owned port for one attempt against a separately deployed AI Runtime.
+ *
+ * Implementations must not call a model Provider directly and must not retry transparently.
+ */
+@FunctionalInterface
+public interface AiRuntimeClient {
+
+ AiAnalysisResponse analyze(AiAnalysisRequest request);
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidator.java b/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidator.java
new file mode 100644
index 0000000..d1fcf60
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidator.java
@@ -0,0 +1,211 @@
+package com.fowoco.server.aiintegration.application.validation;
+
+import com.fowoco.server.aiintegration.application.error.AiRuntimeContractException;
+import com.fowoco.server.aiintegration.application.error.AiRuntimeFailureCode;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisRequest;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+import com.fowoco.server.aiintegration.application.model.AiCandidate;
+import com.fowoco.server.aiintegration.application.model.AiRuntimeVersions;
+import com.fowoco.server.aiintegration.application.model.MaskedWorkerContext;
+import com.fowoco.server.aiintegration.application.model.WorkflowConstraint;
+import java.math.BigDecimal;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.regex.Pattern;
+import org.springframework.stereotype.Component;
+
+/**
+ * Semantic validation applied before an outbound call and after an untrusted Runtime response.
+ */
+@Component
+public class AiRuntimeContractValidator {
+
+ private static final long MIN_DEADLINE_MS = 100;
+ private static final long MAX_DEADLINE_MS = 60_000;
+ private static final int MAX_WORKERS = 20;
+ private static final int MAX_WORKFLOWS = 20;
+ private static final int MAX_CANDIDATES = 50;
+ private static final Pattern VERSION = Pattern.compile("[A-Za-z0-9][A-Za-z0-9._+-]{0,63}");
+ private static final Pattern IDENTIFIER = Pattern.compile("[A-Za-z][A-Za-z0-9._-]{0,127}");
+ private static final Pattern CANDIDATE_REF = Pattern.compile("[A-Za-z0-9][A-Za-z0-9_-]{0,63}");
+
+ private final AiRuntimePrivacyPolicy privacyPolicy;
+
+ public AiRuntimeContractValidator(AiRuntimePrivacyPolicy privacyPolicy) {
+ this.privacyPolicy = privacyPolicy;
+ }
+
+ public void validateRequest(AiAnalysisRequest request) {
+ if (request == null) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime request is missing.");
+ }
+ validateVersion(request.contractVersion(), AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ validateVersion(request.requiredKnowledgeVersion(), AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ if (request.deadlineMs() < MIN_DEADLINE_MS || request.deadlineMs() > MAX_DEADLINE_MS) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime deadline is outside the allowed range.");
+ }
+ privacyPolicy.validateText(request.maskedInput().maskedInstruction(), 10_000, true);
+ validateWorkers(request);
+ validateWorkflowConstraints(request);
+ }
+
+ public void validateResponse(AiAnalysisRequest request, AiAnalysisResponse response) {
+ validateRequest(request);
+ if (response == null) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime response is missing.");
+ }
+ if (!request.requestId().equals(response.requestId())) {
+ reject(AiRuntimeFailureCode.REQUEST_ID_MISMATCH, "AI Runtime response requestId does not match.");
+ }
+ validateResponseVersions(request, response.versions());
+ if (response.providerAttemptCount() < 1 || response.providerAttemptCount() > 10) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "Provider attempt count is invalid.");
+ }
+ if (response.latencyMs() < 0 || response.latencyMs() > 86_400_000) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime latency is invalid.");
+ }
+ if (response.candidates().size() > MAX_CANDIDATES) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime returned too many candidates.");
+ }
+
+ Map> allowedSlotsByWorkflow = allowedSlotsByWorkflow(request);
+ Set allowedWorkers = request.maskedInput().workers().stream()
+ .map(MaskedWorkerContext::workerRef)
+ .collect(java.util.stream.Collectors.toUnmodifiableSet());
+ Set candidateRefs = new HashSet<>();
+ response.candidates().forEach(candidate ->
+ validateCandidate(candidate, allowedWorkers, allowedSlotsByWorkflow, candidateRefs));
+ response.validationErrors().forEach(error -> {
+ validateIdentifier(error.code(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ privacyPolicy.validateKey(error.field());
+ validateIdentifier(error.field(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ });
+ if (response.outcome() == com.fowoco.server.aiintegration.application.model.AiAnalysisOutcome.REVIEW_REQUIRED
+ && response.candidates().isEmpty()) {
+ reject(
+ AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT,
+ "REVIEW_REQUIRED response must include at least one candidate."
+ );
+ }
+ }
+
+ private void validateWorkers(AiAnalysisRequest request) {
+ var workers = request.maskedInput().workers();
+ if (workers.isEmpty() || workers.size() > MAX_WORKERS) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime worker context count is invalid.");
+ }
+ Set workerRefs = new HashSet<>();
+ for (MaskedWorkerContext worker : workers) {
+ if (!workerRefs.add(worker.workerRef())) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime worker reference is duplicated.");
+ }
+ privacyPolicy.validateText(worker.preferredLanguage(), 32, true);
+ privacyPolicy.validateText(worker.workStatus(), 32, true);
+ validateIdentifier(worker.preferredLanguage(), AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ validateIdentifier(worker.workStatus(), AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ }
+ }
+
+ private void validateWorkflowConstraints(AiAnalysisRequest request) {
+ var workflows = request.maskedInput().workflowConstraints();
+ if (workflows.isEmpty() || workflows.size() > MAX_WORKFLOWS) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime Workflow constraint count is invalid.");
+ }
+ Set workflowIds = new HashSet<>();
+ for (WorkflowConstraint workflow : workflows) {
+ validateIdentifier(workflow.workflowId(), AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ if (!workflowIds.add(workflow.workflowId()) || workflow.allowedSlotKeys().size() > 100) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI Runtime Workflow constraint is invalid.");
+ }
+ workflow.allowedSlotKeys().forEach(slot -> {
+ privacyPolicy.validateKey(slot);
+ validateIdentifier(slot, AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT);
+ });
+ }
+ }
+
+ private void validateResponseVersions(AiAnalysisRequest request, AiRuntimeVersions versions) {
+ validateVersion(versions.agentVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ validateIdentifier(versions.modelProvider(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ privacyPolicy.validateText(versions.modelName(), 128, true);
+ validateVersion(versions.modelVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ validateVersion(versions.promptVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ validateVersion(versions.contextPackVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ validateVersion(versions.workflowCatalogVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ validateVersion(versions.contractVersion(), AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+
+ if (!request.contractVersion().equals(versions.contractVersion())) {
+ reject(AiRuntimeFailureCode.CONTRACT_VERSION_MISMATCH, "AI Runtime contract version does not match.");
+ }
+ if (!request.requiredKnowledgeVersion().equals(versions.workflowCatalogVersion())) {
+ reject(AiRuntimeFailureCode.KNOWLEDGE_VERSION_MISMATCH, "AI Runtime Knowledge version does not match.");
+ }
+ }
+
+ private void validateCandidate(
+ AiCandidate candidate,
+ Set allowedWorkers,
+ Map> allowedSlotsByWorkflow,
+ Set candidateRefs
+ ) {
+ if (!CANDIDATE_REF.matcher(candidate.candidateRef()).matches() || !candidateRefs.add(candidate.candidateRef())) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime candidate reference is invalid.");
+ }
+ if (!allowedWorkers.contains(candidate.workerRef())) {
+ reject(AiRuntimeFailureCode.UNEXPECTED_WORKER_REFERENCE, "AI Runtime returned an unknown worker reference.");
+ }
+ Set allowedSlots = allowedSlotsByWorkflow.get(candidate.workflowId());
+ if (allowedSlots == null) {
+ reject(AiRuntimeFailureCode.UNEXPECTED_WORKFLOW, "AI Runtime returned an unexpected Workflow.");
+ }
+ if (candidate.confidence().compareTo(BigDecimal.ZERO) < 0
+ || candidate.confidence().compareTo(BigDecimal.ONE) > 0) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime confidence is invalid.");
+ }
+ candidate.extractedSlots().forEach((key, value) -> {
+ validateAllowedSlot(key, allowedSlots);
+ privacyPolicy.validateText(value, 4_000, true);
+ });
+ Set missingSlots = new HashSet<>();
+ candidate.missingSlots().forEach(slot -> {
+ validateAllowedSlot(slot, allowedSlots);
+ if (!missingSlots.add(slot) || candidate.extractedSlots().containsKey(slot)) {
+ reject(AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT, "AI Runtime missing slot is invalid.");
+ }
+ });
+ }
+
+ private void validateAllowedSlot(String slot, Set allowedSlots) {
+ privacyPolicy.validateKey(slot);
+ validateIdentifier(slot, AiRuntimeFailureCode.INVALID_RESPONSE_CONTRACT);
+ if (!allowedSlots.contains(slot)) {
+ reject(AiRuntimeFailureCode.UNEXPECTED_SLOT, "AI Runtime returned an unexpected slot.");
+ }
+ }
+
+ private Map> allowedSlotsByWorkflow(AiAnalysisRequest request) {
+ Map> allowed = new HashMap<>();
+ request.maskedInput().workflowConstraints()
+ .forEach(workflow -> allowed.put(workflow.workflowId(), workflow.allowedSlotKeys()));
+ return Map.copyOf(allowed);
+ }
+
+ private void validateVersion(String version, AiRuntimeFailureCode failureCode) {
+ if (version == null || !VERSION.matcher(version).matches()) {
+ reject(failureCode, "AI Runtime version is invalid.");
+ }
+ }
+
+ private void validateIdentifier(String identifier, AiRuntimeFailureCode failureCode) {
+ if (identifier == null || !IDENTIFIER.matcher(identifier).matches()) {
+ reject(failureCode, "AI Runtime identifier is invalid.");
+ }
+ }
+
+ private void reject(AiRuntimeFailureCode failureCode, String safeMessage) {
+ throw new AiRuntimeContractException(failureCode, safeMessage);
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimePrivacyPolicy.java b/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimePrivacyPolicy.java
new file mode 100644
index 0000000..e851c38
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/validation/AiRuntimePrivacyPolicy.java
@@ -0,0 +1,97 @@
+package com.fowoco.server.aiintegration.application.validation;
+
+import com.fowoco.server.aiintegration.application.error.AiRuntimeContractException;
+import com.fowoco.server.aiintegration.application.error.AiRuntimeFailureCode;
+import java.text.Normalizer;
+import java.util.Locale;
+import java.util.Set;
+import java.util.regex.Pattern;
+import org.springframework.stereotype.Component;
+
+/**
+ * Rejects sensitive values before they cross the AI boundary or enter an AiRun candidate.
+ */
+@Component
+public class AiRuntimePrivacyPolicy {
+
+ private static final Set FORBIDDEN_KEY_PARTS = Set.of(
+ "passportnumber",
+ "passportno",
+ "alienregistrationnumber",
+ "registrationnumber",
+ "residentnumber",
+ "rrn",
+ "phone",
+ "accountnumber",
+ "bankaccount",
+ "token",
+ "password",
+ "secret",
+ "authorization",
+ "prompt",
+ "여권번호",
+ "외국인등록번호",
+ "주민등록번호",
+ "전화",
+ "계좌",
+ "비밀번호"
+ );
+ private static final Pattern REGISTRATION_NUMBER =
+ Pattern.compile("(? maxLength) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI contract text exceeds its size limit.");
+ }
+ if (containsSensitiveValue(normalized)) {
+ reject(AiRuntimeFailureCode.SENSITIVE_DATA_REJECTED, "Sensitive data was rejected at the AI boundary.");
+ }
+ }
+
+ public void validateKey(String key) {
+ if (key == null || key.isBlank()) {
+ reject(AiRuntimeFailureCode.INVALID_REQUEST_CONTRACT, "AI contract key is missing.");
+ }
+ String normalizedKey = Normalizer.normalize(key, Normalizer.Form.NFKC)
+ .toLowerCase(Locale.ROOT)
+ .replace("_", "")
+ .replace("-", "");
+ boolean forbidden = FORBIDDEN_KEY_PARTS.stream()
+ .map(part -> part.replace("_", "").replace("-", ""))
+ .anyMatch(normalizedKey::contains);
+ if (forbidden) {
+ reject(AiRuntimeFailureCode.SENSITIVE_DATA_REJECTED, "Sensitive key was rejected at the AI boundary.");
+ }
+ }
+
+ private boolean containsSensitiveValue(String value) {
+ return REGISTRATION_NUMBER.matcher(value).find()
+ || PHONE_NUMBER.matcher(value).find()
+ || BEARER_TOKEN.matcher(value).find()
+ || SECRET_ASSIGNMENT.matcher(value).find()
+ || LABELED_SENSITIVE_VALUE.matcher(value).find();
+ }
+
+ private void reject(AiRuntimeFailureCode failureCode, String safeMessage) {
+ throw new AiRuntimeContractException(failureCode, safeMessage);
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClient.java b/src/main/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClient.java
new file mode 100644
index 0000000..dbd8da6
--- /dev/null
+++ b/src/main/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClient.java
@@ -0,0 +1,28 @@
+package com.fowoco.server.aiintegration.application.validation;
+
+import com.fowoco.server.aiintegration.application.model.AiAnalysisRequest;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+import com.fowoco.server.aiintegration.application.port.AiRuntimeClient;
+import java.util.Objects;
+
+/**
+ * Mandatory defensive decorator around a Fake or remote AI Runtime transport.
+ */
+public final class ValidatingAiRuntimeClient implements AiRuntimeClient {
+
+ private final AiRuntimeClient delegate;
+ private final AiRuntimeContractValidator validator;
+
+ public ValidatingAiRuntimeClient(AiRuntimeClient delegate, AiRuntimeContractValidator validator) {
+ this.delegate = Objects.requireNonNull(delegate, "delegate must not be null");
+ this.validator = Objects.requireNonNull(validator, "validator must not be null");
+ }
+
+ @Override
+ public AiAnalysisResponse analyze(AiAnalysisRequest request) {
+ validator.validateRequest(request);
+ AiAnalysisResponse response = delegate.analyze(request);
+ validator.validateResponse(request, response);
+ return response;
+ }
+}
diff --git a/src/main/java/com/fowoco/server/aiintegration/package-info.java b/src/main/java/com/fowoco/server/aiintegration/package-info.java
index 8d11c64..00ec762 100644
--- a/src/main/java/com/fowoco/server/aiintegration/package-info.java
+++ b/src/main/java/com/fowoco/server/aiintegration/package-info.java
@@ -1,4 +1,8 @@
/**
- * AI Runtime client ports, service authentication, and response validation.
+ * Provider-neutral boundary between the Server and the separately deployed AI Runtime.
+ *
+ * This module owns the internal request/response contract and defensive validation. Prompt
+ * assembly, model selection, Provider SDKs, and Knowledge content belong to the {@code ai} and
+ * {@code knowledge} repositories.
*/
package com.fowoco.server.aiintegration;
diff --git a/src/test/java/com/fowoco/server/aiintegration/application/model/AiRuntimeOutboundContractTest.java b/src/test/java/com/fowoco/server/aiintegration/application/model/AiRuntimeOutboundContractTest.java
new file mode 100644
index 0000000..67240fd
--- /dev/null
+++ b/src/test/java/com/fowoco/server/aiintegration/application/model/AiRuntimeOutboundContractTest.java
@@ -0,0 +1,46 @@
+package com.fowoco.server.aiintegration.application.model;
+
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validRequest;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+import tools.jackson.databind.JsonNode;
+import tools.jackson.databind.ObjectMapper;
+
+class AiRuntimeOutboundContractTest {
+
+ private final ObjectMapper objectMapper = new ObjectMapper();
+
+ @Test
+ void outboundJsonContainsOnlyTheExplicitMaskedContract() throws Exception {
+ JsonNode json = objectMapper.valueToTree(validRequest());
+ JsonNode worker = json.get("maskedInput").get("workers").get(0);
+
+ assertThat(json.properties().stream().map(java.util.Map.Entry::getKey).toList())
+ .containsExactlyInAnyOrder(
+ "requestId",
+ "attemptId",
+ "contractVersion",
+ "requiredKnowledgeVersion",
+ "deadlineMs",
+ "maskedInput"
+ );
+ assertThat(worker.properties().stream().map(java.util.Map.Entry::getKey).toList())
+ .containsExactlyInAnyOrder(
+ "workerRef",
+ "preferredLanguage",
+ "workStatus",
+ "stayExpiryDate"
+ );
+ assertThat(json.toString().toLowerCase())
+ .doesNotContain(
+ "passportnumber",
+ "alienregistrationnumber",
+ "phone",
+ "accountnumber",
+ "legalname",
+ "token",
+ "authorization"
+ );
+ }
+}
diff --git a/src/test/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidatorTest.java b/src/test/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidatorTest.java
new file mode 100644
index 0000000..b51cdde
--- /dev/null
+++ b/src/test/java/com/fowoco/server/aiintegration/application/validation/AiRuntimeContractValidatorTest.java
@@ -0,0 +1,190 @@
+package com.fowoco.server.aiintegration.application.validation;
+
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.CONTRACT_VERSION;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.KNOWLEDGE_VERSION;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.REQUEST_ID;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.WORKER_REF;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.WORKFLOW_ID;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.responseWithCandidate;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validCandidate;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validRequest;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validResponse;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validVersions;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.fowoco.server.aiintegration.application.error.AiRuntimeContractException;
+import com.fowoco.server.aiintegration.application.error.AiRuntimeFailureCode;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisOutcome;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+import com.fowoco.server.aiintegration.application.model.AiCandidate;
+import com.fowoco.server.aiintegration.application.model.AiRuntimeVersions;
+import com.fowoco.server.aiintegration.support.AiRuntimeContractFixture;
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+
+class AiRuntimeContractValidatorTest {
+
+ private final AiRuntimeContractValidator validator =
+ new AiRuntimeContractValidator(new AiRuntimePrivacyPolicy());
+
+ @Test
+ void acceptsValidRequestAndResponse() {
+ assertThatCode(() -> validator.validateResponse(validRequest(), validResponse()))
+ .doesNotThrowAnyException();
+ }
+
+ @ParameterizedTest
+ @MethodSource("sensitiveInstructions")
+ void rejectsSensitiveInstructionBeforeOutboundCall(String instruction) {
+ assertFailure(
+ () -> validator.validateRequest(AiRuntimeContractFixture.requestWithInstruction(instruction)),
+ AiRuntimeFailureCode.SENSITIVE_DATA_REJECTED
+ );
+ }
+
+ static Stream sensitiveInstructions() {
+ return Stream.of(
+ "연락처는 010-1234-5678입니다",
+ "외국인등록번호 990101-5123456",
+ "passport_number: M12345678",
+ "Authorization: Bearer secret-token-value",
+ "api_key=do-not-send-this"
+ );
+ }
+
+ @Test
+ void rejectsMismatchedRequestIdWithoutLeakingRawResponse() {
+ AiAnalysisResponse response = new AiAnalysisResponse(
+ UUID.randomUUID(),
+ AiAnalysisOutcome.REVIEW_REQUIRED,
+ validResponse().candidates(),
+ List.of(),
+ validVersions(),
+ 1,
+ 100
+ );
+
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), response),
+ AiRuntimeFailureCode.REQUEST_ID_MISMATCH
+ );
+ }
+
+ @Test
+ void rejectsContractAndKnowledgeVersionDrift() {
+ AiRuntimeVersions wrongContract = versions(CONTRACT_VERSION + "-other", KNOWLEDGE_VERSION);
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), responseWithVersions(wrongContract)),
+ AiRuntimeFailureCode.CONTRACT_VERSION_MISMATCH
+ );
+
+ AiRuntimeVersions wrongKnowledge = versions(CONTRACT_VERSION, "9.9.9");
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), responseWithVersions(wrongKnowledge)),
+ AiRuntimeFailureCode.KNOWLEDGE_VERSION_MISMATCH
+ );
+ }
+
+ @Test
+ void rejectsCandidateOutsideRequestAllowList() {
+ AiCandidate unknownWorker = new AiCandidate(
+ "candidate-worker",
+ UUID.randomUUID(),
+ WORKFLOW_ID,
+ Map.of(),
+ List.of("stay_expiry_date"),
+ BigDecimal.ONE
+ );
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), responseWithCandidate(unknownWorker)),
+ AiRuntimeFailureCode.UNEXPECTED_WORKER_REFERENCE
+ );
+
+ AiCandidate unknownWorkflow = new AiCandidate(
+ "candidate-workflow",
+ WORKER_REF,
+ "UNKNOWN_WORKFLOW",
+ Map.of(),
+ List.of(),
+ BigDecimal.ONE
+ );
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), responseWithCandidate(unknownWorkflow)),
+ AiRuntimeFailureCode.UNEXPECTED_WORKFLOW
+ );
+
+ AiCandidate unknownSlot = new AiCandidate(
+ "candidate-slot",
+ WORKER_REF,
+ WORKFLOW_ID,
+ Map.of("passport_number", "M12345678"),
+ List.of(),
+ BigDecimal.ONE
+ );
+ assertFailure(
+ () -> validator.validateResponse(validRequest(), responseWithCandidate(unknownSlot)),
+ AiRuntimeFailureCode.SENSITIVE_DATA_REJECTED
+ );
+ }
+
+ @Test
+ void rejectsSensitiveCandidateValueAndKeepsExceptionMessageSafe() {
+ AiCandidate sensitiveCandidate = new AiCandidate(
+ "candidate-sensitive",
+ WORKER_REF,
+ WORKFLOW_ID,
+ Map.of("contract_end_date", "담당자 전화 010-1234-5678"),
+ List.of(),
+ BigDecimal.ONE
+ );
+
+ assertThatThrownBy(() -> validator.validateResponse(
+ validRequest(),
+ responseWithCandidate(sensitiveCandidate)
+ )).isInstanceOfSatisfying(AiRuntimeContractException.class, exception -> {
+ assertThat(exception.failureCode()).isEqualTo(AiRuntimeFailureCode.SENSITIVE_DATA_REJECTED);
+ assertThat(exception.getMessage()).doesNotContain("010-1234-5678");
+ });
+ }
+
+ private AiAnalysisResponse responseWithVersions(AiRuntimeVersions versions) {
+ return new AiAnalysisResponse(
+ REQUEST_ID,
+ AiAnalysisOutcome.REVIEW_REQUIRED,
+ List.of(validCandidate()),
+ List.of(),
+ versions,
+ 1,
+ 100
+ );
+ }
+
+ private AiRuntimeVersions versions(String contractVersion, String knowledgeVersion) {
+ AiRuntimeVersions valid = validVersions();
+ return new AiRuntimeVersions(
+ valid.agentVersion(),
+ valid.modelProvider(),
+ valid.modelName(),
+ valid.modelVersion(),
+ valid.promptVersion(),
+ valid.contextPackVersion(),
+ knowledgeVersion,
+ contractVersion
+ );
+ }
+
+ private void assertFailure(Runnable invocation, AiRuntimeFailureCode expectedCode) {
+ assertThatThrownBy(invocation::run)
+ .isInstanceOfSatisfying(AiRuntimeContractException.class, exception ->
+ assertThat(exception.failureCode()).isEqualTo(expectedCode)
+ );
+ }
+}
diff --git a/src/test/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClientTest.java b/src/test/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClientTest.java
new file mode 100644
index 0000000..f190237
--- /dev/null
+++ b/src/test/java/com/fowoco/server/aiintegration/application/validation/ValidatingAiRuntimeClientTest.java
@@ -0,0 +1,38 @@
+package com.fowoco.server.aiintegration.application.validation;
+
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.requestWithInstruction;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validRequest;
+import static com.fowoco.server.aiintegration.support.AiRuntimeContractFixture.validResponse;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.fowoco.server.aiintegration.application.error.AiRuntimeContractException;
+import com.fowoco.server.aiintegration.support.FakeAiRuntimeClient;
+import org.junit.jupiter.api.Test;
+
+class ValidatingAiRuntimeClientTest {
+
+ private final AiRuntimeContractValidator validator =
+ new AiRuntimeContractValidator(new AiRuntimePrivacyPolicy());
+
+ @Test
+ void validatesBothSidesAndCapturesOneAttemptWithoutTransparentRetry() {
+ FakeAiRuntimeClient fake = new FakeAiRuntimeClient();
+ fake.enqueueResponse(validResponse());
+ ValidatingAiRuntimeClient client = new ValidatingAiRuntimeClient(fake, validator);
+
+ assertThat(client.analyze(validRequest())).isEqualTo(validResponse());
+ assertThat(fake.receivedRequests()).containsExactly(validRequest());
+ }
+
+ @Test
+ void rejectedInputNeverReachesTransport() {
+ FakeAiRuntimeClient fake = new FakeAiRuntimeClient();
+ fake.enqueueResponse(validResponse());
+ ValidatingAiRuntimeClient client = new ValidatingAiRuntimeClient(fake, validator);
+
+ assertThatThrownBy(() -> client.analyze(requestWithInstruction("전화 010-1234-5678")))
+ .isInstanceOf(AiRuntimeContractException.class);
+ assertThat(fake.receivedRequests()).isEmpty();
+ }
+}
diff --git a/src/test/java/com/fowoco/server/aiintegration/support/AiRuntimeContractFixture.java b/src/test/java/com/fowoco/server/aiintegration/support/AiRuntimeContractFixture.java
new file mode 100644
index 0000000..f744cde
--- /dev/null
+++ b/src/test/java/com/fowoco/server/aiintegration/support/AiRuntimeContractFixture.java
@@ -0,0 +1,98 @@
+package com.fowoco.server.aiintegration.support;
+
+import com.fowoco.server.aiintegration.application.model.AiAnalysisOutcome;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisRequest;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+import com.fowoco.server.aiintegration.application.model.AiCandidate;
+import com.fowoco.server.aiintegration.application.model.AiRuntimeVersions;
+import com.fowoco.server.aiintegration.application.model.MaskedAnalysisInput;
+import com.fowoco.server.aiintegration.application.model.MaskedWorkerContext;
+import com.fowoco.server.aiintegration.application.model.WorkflowConstraint;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+
+public final class AiRuntimeContractFixture {
+
+ public static final UUID REQUEST_ID = UUID.fromString("10000000-0000-0000-0000-000000000001");
+ public static final UUID ATTEMPT_ID = UUID.fromString("20000000-0000-0000-0000-000000000001");
+ public static final UUID WORKER_REF = UUID.fromString("30000000-0000-0000-0000-000000000001");
+ public static final String CONTRACT_VERSION = "1.0.0";
+ public static final String KNOWLEDGE_VERSION = "0.2.0";
+ public static final String WORKFLOW_ID = "EXPIRY_RENEWAL";
+
+ private AiRuntimeContractFixture() {
+ }
+
+ public static AiAnalysisRequest validRequest() {
+ return requestWithInstruction(
+ "workerRef 30000000-0000-0000-0000-000000000001의 체류연장 준비"
+ );
+ }
+
+ public static AiAnalysisRequest requestWithInstruction(String instruction) {
+ return new AiAnalysisRequest(
+ REQUEST_ID,
+ ATTEMPT_ID,
+ CONTRACT_VERSION,
+ KNOWLEDGE_VERSION,
+ 10_000,
+ new MaskedAnalysisInput(
+ instruction,
+ List.of(new MaskedWorkerContext(
+ WORKER_REF,
+ "vi",
+ "ACTIVE",
+ LocalDate.of(2026, 12, 31)
+ )),
+ List.of(new WorkflowConstraint(
+ WORKFLOW_ID,
+ Set.of("stay_expiry_date", "contract_end_date", "monthly_wage")
+ ))
+ )
+ );
+ }
+
+ public static AiAnalysisResponse validResponse() {
+ return responseWithCandidate(validCandidate());
+ }
+
+ public static AiAnalysisResponse responseWithCandidate(AiCandidate candidate) {
+ return new AiAnalysisResponse(
+ REQUEST_ID,
+ AiAnalysisOutcome.REVIEW_REQUIRED,
+ List.of(candidate),
+ List.of(),
+ validVersions(),
+ 1,
+ 245
+ );
+ }
+
+ public static AiCandidate validCandidate() {
+ return new AiCandidate(
+ "candidate-1",
+ WORKER_REF,
+ WORKFLOW_ID,
+ Map.of("stay_expiry_date", "2026-12-31"),
+ List.of("contract_end_date", "monthly_wage"),
+ new BigDecimal("0.92")
+ );
+ }
+
+ public static AiRuntimeVersions validVersions() {
+ return new AiRuntimeVersions(
+ "agent-1.0.0",
+ "openai",
+ "gpt-5-mini",
+ "2026-07-01",
+ "prompt-3",
+ "context-0.2.0",
+ KNOWLEDGE_VERSION,
+ CONTRACT_VERSION
+ );
+ }
+}
diff --git a/src/test/java/com/fowoco/server/aiintegration/support/FakeAiRuntimeClient.java b/src/test/java/com/fowoco/server/aiintegration/support/FakeAiRuntimeClient.java
new file mode 100644
index 0000000..5e85c5d
--- /dev/null
+++ b/src/test/java/com/fowoco/server/aiintegration/support/FakeAiRuntimeClient.java
@@ -0,0 +1,46 @@
+package com.fowoco.server.aiintegration.support;
+
+import com.fowoco.server.aiintegration.application.model.AiAnalysisRequest;
+import com.fowoco.server.aiintegration.application.model.AiAnalysisResponse;
+import com.fowoco.server.aiintegration.application.port.AiRuntimeClient;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Deque;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Function;
+
+/**
+ * Test-only scripted Runtime that makes no network request.
+ */
+public final class FakeAiRuntimeClient implements AiRuntimeClient {
+
+ private final Deque> scripts = new ArrayDeque<>();
+ private final List receivedRequests = new ArrayList<>();
+
+ public void enqueueResponse(AiAnalysisResponse response) {
+ Objects.requireNonNull(response, "response must not be null");
+ scripts.addLast(request -> response);
+ }
+
+ public void enqueueFailure(RuntimeException exception) {
+ Objects.requireNonNull(exception, "exception must not be null");
+ scripts.addLast(request -> {
+ throw exception;
+ });
+ }
+
+ @Override
+ public AiAnalysisResponse analyze(AiAnalysisRequest request) {
+ receivedRequests.add(request);
+ Function script = scripts.pollFirst();
+ if (script == null) {
+ throw new AssertionError("FakeAiRuntimeClient has no scripted result.");
+ }
+ return script.apply(request);
+ }
+
+ public List receivedRequests() {
+ return List.copyOf(receivedRequests);
+ }
+}