diff --git a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md index 524a55bb..fe3fac79 100644 --- a/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md +++ b/docs/architecture/decisions/VD-07-diagnostics-and-telemetry-exporter.md @@ -45,7 +45,11 @@ vendor 결정 전에는 안전한 기본값이 아니다. `operation`, `outcome`, `error_kind`, `http_status_group`, `attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만 `correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를 - 더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). raw attempt count, + 더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). + 실행이 observation의 `diagnosticReason`(닫힌 집합 `HttpDiagnosticReason`)을 + 남기면 diagnostics에만 `reason`으로 더한다. 지금 값은 기능 패키지의 + `classifyProblem`이 throw하거나 집합 밖 값을 돌려줘 효과를 `MAYBE_APPLIED`로 + 떨어뜨린 `CLASSIFIER_FAILED` 하나다(03-05). raw attempt count, duration, status, URL, intent, key, input identity와 내부 `terminalReason`은 sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty` key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만 diff --git a/src/adapters/http/http-effect-certainty.ts b/src/adapters/http/http-effect-certainty.ts index 0ad44c28..42c29b51 100644 --- a/src/adapters/http/http-effect-certainty.ts +++ b/src/adapters/http/http-effect-certainty.ts @@ -92,7 +92,9 @@ const CLASSIFICATIONS: ReadonlySet = new Set([ /** * §4.4. The classifier is package-owned and pure. A throw or an unrecognised * return value fails safe to `MAYBE_APPLIED` and is recorded as a contract - * runtime failure rather than being silently treated as "not applied". + * runtime failure rather than being silently treated as "not applied": the + * executor turns `contractRuntimeFailure` into the observation's + * `diagnosticReason: "CLASSIFIER_FAILED"` (03-05). */ export function classifyProblemEffect( input: ProblemEffectInput, diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index d5fd0e09..70857e25 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -283,8 +283,22 @@ export type HttpExecutionObservation = Readonly<{ * projection never forwards it to diagnostics or telemetry. */ terminalReason: string; + /** + * 03-05. A client-side defect the outcome alone cannot show, from a closed + * set. Diagnostics carry it as `reason`; telemetry never does (VD-07). + */ + diagnosticReason?: HttpDiagnosticReason; }>; +/** + * Closed set behind `HttpExecutionObservation.diagnosticReason`. + * + * - `CLASSIFIER_FAILED`: the package `classifyProblem` threw or answered + * outside the closed classification set, so the effect fell back to + * `MAYBE_APPLIED` (03-05). + */ +export type HttpDiagnosticReason = "CLASSIFIER_FAILED"; + /** * The outcome is the single authority for the observed error kind. The terminal * reason only distinguishes an internal runtime failure from a transport @@ -590,6 +604,7 @@ export function createContractHttpExecutor( const finish = ( outcome: HttpExecutionOutcome, terminalReason: string, + diagnosticReason?: HttpDiagnosticReason, ): HttpExecutionOutcome => { disposeLifetime(); try { @@ -607,6 +622,7 @@ export function createContractHttpExecutor( durationMs: Math.max(0, now() - startedAt), effect: outcome.effect, terminalReason, + ...(diagnosticReason === undefined ? {} : { diagnosticReason }), ...(terminalCancellation === null ? {} : { cancellationOwner: terminalCancellation }), @@ -1070,6 +1086,7 @@ export function createContractHttpExecutor( effect, }) as HttpExecutionOutcome), outcome.certainty, + outcome.diagnosticReason, ); } finally { clearTimeout(deadlineTimer); @@ -1144,6 +1161,7 @@ type AdmissionOutcome = Readonly<{ certainty: string; retryHint: boolean; retryAfterMs: number | null; + diagnosticReason?: HttpDiagnosticReason; }>; /** @@ -1612,6 +1630,9 @@ async function admitProblem( certainty: effect, retryHint: retryable && effect !== "MAYBE_APPLIED", retryAfterMs: metadata.retryAfterMs ?? null, + ...(isCommand && classification.contractRuntimeFailure + ? { diagnosticReason: "CLASSIFIER_FAILED" as const } + : {}), }); } diff --git a/src/adapters/http/index.ts b/src/adapters/http/index.ts index a5f6a645..72723330 100644 --- a/src/adapters/http/index.ts +++ b/src/adapters/http/index.ts @@ -12,6 +12,7 @@ export { type ContractHttpExecutorDependencies, type HttpContractViolation, type HttpContractViolationKind, + type HttpDiagnosticReason, type HttpEffectCertainty, type HttpExecutionContext, type HttpExecutionObservation, diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index d3aa1216..29883ad3 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -251,6 +251,10 @@ export function createHttpObservationProjector( ...(observation.correlationId === undefined ? {} : { correlation_id: observation.correlationId }), + // 03-05. A closed client-defect code; diagnostics only. + ...(observation.diagnosticReason === undefined + ? {} + : { reason: observation.diagnosticReason }), }, }); } catch { diff --git a/tests/integration/http-execution-v3-observability.test.ts b/tests/integration/http-execution-v3-observability.test.ts index 19de1375..47129fa0 100644 --- a/tests/integration/http-execution-v3-observability.test.ts +++ b/tests/integration/http-execution-v3-observability.test.ts @@ -210,6 +210,84 @@ describe("V3 HTTP observability projection", () => { expect(JSON.stringify(sinks.telemetry)).not.toContain("server-ref-7"); }); + /** + * 03-05. A package problem classifier that throws, or answers outside the + * closed set, fails safe to MAYBE_APPLIED. Diagnostics must still tell that + * apart from a classifier that really answered MAYBE_APPLIED; telemetry stays + * on `error_kind` alone. + */ + it("keeps MAYBE_APPLIED and records a failed problem classifier in diagnostics only (03-05)", async () => { + async function runWithClassifier(classifyProblem: () => unknown) { + const sinks = recordingSinks(); + const contract = { + ...TEST_CREATE_HTTP_CONTRACT, + contract: { + ...TEST_CREATE_HTTP_CONTRACT.contract, + commandEffect: { + ...TEST_CREATE_HTTP_CONTRACT.contract.commandEffect!, + classifyProblem, + } as NonNullable< + typeof TEST_CREATE_HTTP_CONTRACT.contract.commandEffect + >, + }, + }; + const outcome = await createContractHttpExecutor({ + baseUrl: "https://api.example/", + maxRetryAttempts: 0, + attachCredentials: () => ({ kind: "READY" as const, headers: {} }), + fetcher: (async () => + Response.json( + { type: "about:blank", title: "conflict", status: 409 }, + { status: 409 }, + )) as unknown as typeof fetch, + observe: sinks.projector, + }).execute( + contract, + { name: "Created" }, + { + routeId: ROUTE_ID, + scope: scopeSnapshot(), + intent: Object.freeze({ + intentId: "intent-1", + operationId: "TEST_CREATE_ENTITY", + canonicalInputIdentity: "opaque-input-identity", + idempotencyKey: "key-1", + createdAtMonotonicMs: 1, + }), + }, + ); + expect(sinks.diagnostics).toHaveLength(1); + expect(projectDiagnosticRecord(sinks.diagnostics[0]!).success).toBe(true); + expect(sinks.telemetry).toHaveLength(1); + return { + kind: outcome.kind, + effect: outcome.effect, + reason: sinks.diagnostics[0]?.context?.reason, + telemetryKeys: Object.keys(sinks.telemetry[0]?.attributes ?? {}), + }; + } + + const answered = await runWithClassifier(() => "MAYBE_APPLIED"); + const thrown = await runWithClassifier(() => { + throw new Error("package classifier defect"); + }); + const unknownAnswer = await runWithClassifier(() => "NOT_STARTED"); + + expect(answered).toMatchObject({ + kind: "PROBLEM", + effect: "MAYBE_APPLIED", + reason: undefined, + }); + for (const failed of [thrown, unknownAnswer]) { + expect(failed).toMatchObject({ + kind: "PROBLEM", + effect: "MAYBE_APPLIED", + reason: "CLASSIFIER_FAILED", + }); + expect(failed.telemetryKeys).toEqual(answered.telemetryKeys); + } + }); + it("keeps a never-sent unauthenticated request out of telemetry (03-07)", async () => { const sinks = recordingSinks(); const fetcher = vi.fn();