feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다

문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.

고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
  HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
  쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
  UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
  IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
  SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
  422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
  "effect_certainty는 필요해지면 더한다" 문장은 지웠다.

버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
  먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
  섞인다. 비율은 effect_certainty로 센다.

위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
  응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
  맞춰야 한다.

검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
  8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
  effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
  tests/unit·integration·component·features·contract·runtime-schema·platform
  282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
  한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
This commit is contained in:
DongHyeonka
2026-11-04 20:54:24 +09:00
parent 631ce339b9
commit 39c1de2e5e
9 changed files with 179 additions and 30 deletions
@@ -43,21 +43,27 @@ vendor 결정 전에는 안전한 기본값이 아니다.
`createHttpObservationProjector`가 유일한 projection authority다. observation은
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
`operation`, `outcome`, `error_kind`, `http_status_group`,
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
`attempt_count_bucket`, `duration_bucket`, `effect_certainty`만 사용한다.
`effect_certainty`는 V3 `HttpEffectCertainty` 다섯 값(`NOT_APPLICABLE`,
`NOT_STARTED`, `NOT_APPLIED`, `APPLIED_CONFIRMED`, `MAYBE_APPLIED`)만 받는 닫힌
value policy(`isEffectCertainty`)를 두 sink가 함께 쓴다. 결과 불명 쓰기의 수를
세기 위해서다(1103/03-05). diagnostics에만
`correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를
더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`).
실행이 observation의 `diagnosticReason`(닫힌 집합 `HttpDiagnosticReason`)을
남기면 diagnostics에만 `reason`으로 더한다. 값은 둘 중 하나다. 기능 패키지의
남기면 diagnostics에만 `reason`으로 더한다. 값은 넷 중 하나다. 기능 패키지의
`classifyProblem`이 throw하거나 집합 밖 값을 돌려줘 효과를 `MAYBE_APPLIED`로
떨어뜨린 `CLASSIFIER_FAILED`(03-05), 그리고 전송 전에 거절한 요청의 원인
떨어뜨린 `CLASSIFIER_FAILED`(03-05), 전송 전에 거절한 요청의 원인
`HttpRequestRejectionReason`(입력 검증 실패, 요청 조립 실패, 최종 불변식 실패,
미설치 계약 `CONTRACT_NOT_INSTALLED`, 03-02)이다. 미설치 계약은 실행기를
미설치 계약 `CONTRACT_NOT_INSTALLED`, 03-02), Envelope 백엔드가 멱등 키를
거절한 `IdempotencyRefusalReason`, 그리고 Envelope 명령의 결과를 모르게 된
원인 `UnknownEffectReason`(`IN_FLIGHT`, `IDEMPOTENCY_UNAVAILABLE`,
`COMPLETION_UNKNOWN`, `RECOVERY_REQUIRED`, `SERVER_TIMEOUT`, `STAGE_UNKNOWN`,
1103/03-05)이다. 백엔드 `error.code` 원문은 싣지 않는다. 미설치 계약은 실행기를
거치지 않으므로 조립 지점이 같은 projector로 관측 1건을 직접 남긴다.
raw attempt count,
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
전달한다.
sink로 나가지 않는다.
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,
+54 -8
View File
@@ -205,29 +205,75 @@ export function isFieldValidationFailure(
Array.isArray(error.details);
}
/**
* 1103/03-05. Why a backend answer left a command's result unknown, a closed
* set for diagnostics `reason`: the key is still running (`IN_FLIGHT`), one of
* the backend's own 5xx answers below, or a 400, 409 or 422 whose code does
* not say whether it came before or after the write (`STAGE_UNKNOWN`).
*/
export type UnknownEffectReason =
| "IN_FLIGHT"
| "IDEMPOTENCY_UNAVAILABLE"
| "COMPLETION_UNKNOWN"
| "RECOVERY_REQUIRED"
| "SERVER_TIMEOUT"
| "STAGE_UNKNOWN";
/**
* 1103/03-04. The backend's answers outside 400, 409 and 422 that it defines
* itself (§2, §4), each with its status. None of them lets a client say the
* command did not run, and none takes a new key.
*/
const MAYBE_APPLIED_ANSWERS: Readonly<Record<string, number>> = Object.freeze({
const MAYBE_APPLIED_ANSWERS: Readonly<
Record<string, Readonly<{ status: number; reason: UnknownEffectReason }>>
> = Object.freeze({
// §2. Refused before the action, but to be resent with the same key, which
// only an unknown result keeps.
IDEMPOTENCY_UNAVAILABLE: 503,
IDEMPOTENCY_UNAVAILABLE: Object.freeze({
status: 503,
reason: "IDEMPOTENCY_UNAVAILABLE",
}),
// §2. The action ran and recording its result failed: same key later,
// never a new one.
IDEMPOTENCY_COMPLETION_UNKNOWN: 503,
IDEMPOTENCY_COMPLETION_UNKNOWN: Object.freeze({
status: 503,
reason: "COMPLETION_UNKNOWN",
}),
// §2. An earlier attempt's effect cannot be proven. Not resent on its own;
// the user checks the data.
IDEMPOTENCY_RECOVERY_REQUIRED: 500,
IDEMPOTENCY_RECOVERY_REQUIRED: Object.freeze({
status: 500,
reason: "RECOVERY_REQUIRED",
}),
// §4. An async request ran past its time; the work may still go on.
REQUEST_TIMEOUT: 503,
REQUEST_TIMEOUT: Object.freeze({ status: 503, reason: "SERVER_TIMEOUT" }),
});
function maybeAppliedAnswer(code: string, status: number) {
const answer = Object.hasOwn(MAYBE_APPLIED_ANSWERS, code)
? MAYBE_APPLIED_ANSWERS[code]
: undefined;
return answer !== undefined && answer.status === status ? answer : undefined;
}
function mayHaveApplied(code: string, status: number): boolean {
return Object.hasOwn(MAYBE_APPLIED_ANSWERS, code)
? MAYBE_APPLIED_ANSWERS[code] === status
: false;
return maybeAppliedAnswer(code, status) !== undefined;
}
/**
* 1103/03-05. The cause behind a `MAYBE_APPLIED` the table gave, or
* `undefined` when the answer did not leave the result unknown.
*/
export function unknownEffectReason(
status: number,
error: EnvelopeError,
declaredRefusals?: readonly string[],
): UnknownEffectReason | undefined {
if (envelopeFailureEffect(status, error, declaredRefusals) !== "MAYBE_APPLIED") {
return undefined;
}
if (status === 409 && error.code === "IDEMPOTENT_IN_FLIGHT") return "IN_FLIGHT";
return maybeAppliedAnswer(error.code, status)?.reason ?? "STAGE_UNKNOWN";
}
/**
+20 -7
View File
@@ -51,8 +51,10 @@ import {
invitesKeyedResend,
readFailureEnvelope,
readSuccessEnvelope,
unknownEffectReason,
type EnvelopePage,
type IdempotencyRefusalReason,
type UnknownEffectReason,
} from "./backend-envelope.ts";
import {
createExecutionContext,
@@ -351,13 +353,16 @@ export type HttpExecutionObservation = Readonly<{
* - an `HttpRequestRejectionReason`: copied from the refused request's
* violation (03-02).
* - an `IdempotencyRefusalReason`: an Envelope operation's backend refused
* the idempotency key (1101 README 14.4). No other backend code reaches
* diagnostics; the failure's code carries it.
* the idempotency key (1101 README 14.4).
* - an `UnknownEffectReason`: why an Envelope command's answer left its
* result unknown (1103/03-05).
* No backend code itself reaches diagnostics; the failure's code carries it.
*/
export type HttpDiagnosticReason =
| "CLASSIFIER_FAILED"
| HttpRequestRejectionReason
| IdempotencyRefusalReason;
| IdempotencyRefusalReason
| UnknownEffectReason;
/**
* The outcome is the single authority for the observed error kind. The terminal
@@ -1700,7 +1705,7 @@ async function admitProblem<Input, WireOutput, Problem>(
let validated: ValidatorInvocation<Problem>;
let problemMetadata = metadata;
let backendEffect: "NOT_APPLIED" | "MAYBE_APPLIED" | undefined;
let refusalReason: IdempotencyRefusalReason | undefined;
let backendReason: IdempotencyRefusalReason | UnknownEffectReason | undefined;
let keyedResend = false;
if (enveloped) {
const framed = readFailureEnvelope(decoded.value);
@@ -1720,7 +1725,15 @@ async function admitProblem<Input, WireOutput, Problem>(
framed.value,
contract.commandEffect?.refusedBeforeWrite,
);
refusalReason = idempotencyRefusalReason(framed.value.code, status);
backendReason =
idempotencyRefusalReason(framed.value.code, status) ??
(isCommand
? unknownEffectReason(
status,
framed.value,
contract.commandEffect?.refusedBeforeWrite,
)
: undefined);
keyedResend =
isCommand &&
contract.retrySemantics === "KEYED" &&
@@ -1774,9 +1787,9 @@ async function admitProblem<Input, WireOutput, Problem>(
retryAfterMs: metadata.retryAfterMs ?? null,
...(isCommand && classification.contractRuntimeFailure
? { diagnosticReason: "CLASSIFIER_FAILED" as const }
: refusalReason === undefined
: backendReason === undefined
? {}
: { diagnosticReason: refusalReason }),
: { diagnosticReason: backendReason }),
...(keyedResend ? { keyedResend: true as const } : {}),
});
}
+3
View File
@@ -200,6 +200,9 @@ export function createHttpObservationProjector(
http_status_group: statusGroup(observation.status),
attempt_count_bucket: attemptBucket(observation.attemptCount),
duration_bucket: durationBucket(observation.durationMs),
// 1103/03-05. Five closed values: counts unknown-result writes apart
// from refused ones without any request-scoped value.
effect_certainty: observation.effect,
};
try {
sinks.diagnostics.record({
+17
View File
@@ -43,6 +43,7 @@ export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([
"reason",
"queue_size_bucket",
"feature_override_key",
"effect_certainty",
] as const);
export type DiagnosticContextKey =
(typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number];
@@ -87,6 +88,8 @@ export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({
// 09-09. A key from the deployed runtime document; it changes with a config
// deployment, not with traffic.
feature_override_key: "deployment",
// 1103/03-05. The V3 effect certainty, five values.
effect_certainty: "bounded",
} satisfies Readonly<Record<DiagnosticContextKey, DiagnosticCardinalityClass>>);
export type DiagnosticContext = Readonly<
@@ -114,8 +117,22 @@ const BOUNDED_CONTEXT_VALUE_POLICIES: Readonly<
typeof value === "string" && /^(?:route|feature|boot)$/.test(value),
queue_size_bucket: (value) =>
typeof value === "string" && /^(?:0|1-10|11-50|51\+)$/.test(value),
effect_certainty: isEffectCertainty,
});
/**
* 1103/03-05. Exactly the V3 `HttpEffectCertainty` values. Telemetry and
* diagnostics both validate `effect_certainty` with it.
*/
export function isEffectCertainty(value: unknown): value is string {
return (
typeof value === "string" &&
/^(?:NOT_APPLICABLE|NOT_STARTED|NOT_APPLIED|APPLIED_CONFIRMED|MAYBE_APPLIED)$/.test(
value,
)
);
}
export type DiagnosticRecordInput = Readonly<{
level: DiagnosticLevel;
eventId: DiagnosticEventId;
+5 -2
View File
@@ -1,4 +1,4 @@
import { isHttpStatusGroup } from "./diagnostics.ts";
import { isEffectCertainty, isHttpStatusGroup } from "./diagnostics.ts";
import { isOperationId } from "./operation-id.ts";
export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([
@@ -18,6 +18,7 @@ export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([
"mismatch_kind",
"reason",
"queue_size_bucket",
"effect_certainty",
] as const);
export const TELEMETRY_FORBIDDEN_ATTRIBUTES = Object.freeze([
@@ -74,7 +75,7 @@ export const TELEMETRY_REGISTRY = Object.freeze({
"http_status_group",
"attempt_count_bucket",
"route_id",
], ["operation_id", "duration_bucket"]),
], ["operation_id", "duration_bucket", "effect_certainty"]),
"ui.render.failed": event("ui.render.failed", "React boundary catch", [
"route_id",
"build_id",
@@ -136,6 +137,8 @@ const ATTRIBUTE_VALUE_POLICIES: Readonly<
),
queue_size_bucket: (value) =>
/^(?:0|1-10|11-50|51\+)$/.test(value),
// 1103/03-05. Shared with diagnostics.
effect_certainty: isEffectCertainty,
});
function validAttributeValue(key: string, value: unknown): value is string {
@@ -11,7 +11,10 @@ import {
type InstalledHttpOperationExecutor,
} from "../../src/adapters/http/index.ts";
import { createHttpObservationProjector } from "../../src/bootstrap/runtime-adapters.ts";
import type { DiagnosticRecordInput } from "../../src/contracts/diagnostics.ts";
import {
projectDiagnosticRecord,
type DiagnosticRecordInput,
} from "../../src/contracts/diagnostics.ts";
import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts";
import type { AppFailure } from "../../src/contracts/errors.ts";
import {
@@ -796,12 +799,20 @@ describe("an operation's declared pre-write refusals", () => {
// and names an idempotency refusal in diagnostics (`reason`, a closed
// taxonomy); any other code stays out of diagnostics.
describe("V3 Envelope diagnostics name idempotency refusals", () => {
// 1103/03-05. An unknown result names its cause too, and every record
// carries the effect, so an in-flight 409 and a business 409 no longer
// read the same.
it.each([
["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH"],
["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH"],
["409 IDEMPOTENT_IN_FLIGHT", 409, "IDEMPOTENT_IN_FLIGHT", undefined],
["409 domain conflict", 409, "RESOURCE_CONFLICT", undefined],
] as const)("%s", async (_label, status, code, reason) => {
["422 IDEMPOTENT_REQUEST_MISMATCH", 422, "IDEMPOTENT_REQUEST_MISMATCH", "IDEMPOTENT_REQUEST_MISMATCH", "NOT_APPLIED"],
["400 IDEMPOTENCY_KEY_INVALID", 400, "IDEMPOTENCY_KEY_INVALID", "IDEMPOTENCY_KEY_RULE_MISMATCH", "NOT_APPLIED"],
["400 VALIDATION_FAILED", 400, "VALIDATION_FAILED", undefined, "NOT_APPLIED"],
["409 IDEMPOTENT_IN_FLIGHT", 409, "IDEMPOTENT_IN_FLIGHT", "IN_FLIGHT", "MAYBE_APPLIED"],
["409 domain conflict", 409, "RESOURCE_CONFLICT", "STAGE_UNKNOWN", "MAYBE_APPLIED"],
["503 IDEMPOTENCY_UNAVAILABLE", 503, "IDEMPOTENCY_UNAVAILABLE", "IDEMPOTENCY_UNAVAILABLE", "MAYBE_APPLIED"],
["503 IDEMPOTENCY_COMPLETION_UNKNOWN", 503, "IDEMPOTENCY_COMPLETION_UNKNOWN", "COMPLETION_UNKNOWN", "MAYBE_APPLIED"],
["500 IDEMPOTENCY_RECOVERY_REQUIRED", 500, "IDEMPOTENCY_RECOVERY_REQUIRED", "RECOVERY_REQUIRED", "MAYBE_APPLIED"],
["503 REQUEST_TIMEOUT", 503, "REQUEST_TIMEOUT", "SERVER_TIMEOUT", "MAYBE_APPLIED"],
] as const)("%s", async (_label, status, code, reason, effect) => {
answer("post", "/api/envelope-items", failure(code, "VALIDATION", false), { status });
const records: DiagnosticRecordInput[] = [];
const project = createHttpObservationProjector({
@@ -815,6 +826,8 @@ describe("V3 Envelope diagnostics name idempotency refusals", () => {
expect(records).toHaveLength(1);
expect(records[0]?.context?.reason).toBe(reason);
expect(records[0]?.context?.effect_certainty).toBe(effect);
expect(projectDiagnosticRecord(records[0]!).success).toBe(true);
});
});
@@ -130,6 +130,7 @@ describe("V3 HTTP observability projection", () => {
"http_status_group",
"attempt_count_bucket",
"duration_bucket",
"effect_certainty",
]),
);
for (const key of contextKeys) {
@@ -44,6 +44,53 @@ describe("observability cardinality policy", () => {
).toEqual({ success: false, reason: "invalid-context" });
});
// 1103/03-05. The effect certainty is a closed five-value dimension in
// both sinks.
it.each(["NOT_APPLICABLE", "NOT_STARTED", "NOT_APPLIED", "APPLIED_CONFIRMED", "MAYBE_APPLIED"])(
"admits effect_certainty %s in diagnostics and failure telemetry",
(effect) => {
expect(DIAGNOSTIC_CONTEXT_CARDINALITY.effect_certainty).toBe("bounded");
expect(
projectDiagnosticRecord({
level: "warn",
eventId: "http.request.completed",
context: { effect_certainty: effect },
}).success,
).toBe(true);
expect(
projectTelemetryEvent("api.request.failed", {
error_kind: "PROBLEM",
http_status_group: "4xx",
attempt_count_bucket: "1",
route_id: "TEST_ROUTE",
effect_certainty: effect,
}).success,
).toBe(true);
},
);
it.each(["maybe", "UNKNOWN", "MAYBE_APPLIED_ON_RETRY"])(
"rejects effect_certainty %j in both sinks",
(effect) => {
expect(
projectDiagnosticRecord({
level: "warn",
eventId: "http.request.completed",
context: { effect_certainty: effect },
}),
).toEqual({ success: false, reason: "invalid-context" });
expect(
projectTelemetryEvent("api.request.failed", {
error_kind: "PROBLEM",
http_status_group: "4xx",
attempt_count_bucket: "1",
route_id: "TEST_ROUTE",
effect_certainty: effect,
}),
).toEqual({ success: false, reason: "invalid-attribute-value" });
},
);
it("allows request correlation only in bounded diagnostics evidence", () => {
const projected = projectDiagnosticRecord({
level: "info",