문제 V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서 12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감, retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에 없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도 check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이 breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고 (X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도 behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에 204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다. 고른 방법 - projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다: acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기 칸 이름: input·output·problem), requestByteLimit, responseByteLimit, totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery. - commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지 (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite 목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로 읽고, 없으면 행에도 없다. - governance: problemSchema와 unvalidated를 breakingFields에 넣는다. status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이 빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에 넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지 증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다. - 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지, descriptor 함수는 행에 없다는 것을 적었다. 버린 대안 - descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지 기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다. - V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다. - 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감 조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다. 위험·한계 - governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어 기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다. - FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사 대상이 아니다. breaking 칸으로만 잠근다. - classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다. 검증 - 기준선 재승인 뒤 실험 재실행(check:registries): X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락), X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건), X5 GET 출력 검증기 생략 실패(unvalidated:field-changed), X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다. - tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite 있음·없음, governance JSON으로 분류한 8가지 변경. - run-vitest related(api-operations.ts, governance) 21파일 156건, registry 테스트 4파일 63건, check:registries:compatibility-fixtures, check:types, eslint, verify:documentation 통과. BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의 check:registries가 FE-REG-API:$contract:* contract-field-changed로 실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을 주고 update:registry-baseline을 한 번 돌린다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절
145 lines
5.6 KiB
TypeScript
145 lines
5.6 KiB
TypeScript
import type {
|
|
CommandEffectDescriptor,
|
|
CommandRecoveryDescriptor,
|
|
HttpMethod,
|
|
InstalledContractContribution,
|
|
InstalledHttpContract,
|
|
ResponseEnvelope,
|
|
RetrySemantics,
|
|
RuntimeValidator,
|
|
} from "./external-contract-runtime.ts";
|
|
import type { TrafficBudget } from "../platform/traffic/traffic-budget.ts";
|
|
|
|
/**
|
|
* 1103/07-01. The data of a command effect descriptor. Its classifiers are
|
|
* behaviour and stay out of the row; what the row keeps is whether the
|
|
* descriptor answers 401, 403 and 429 itself, and the problem codes it names
|
|
* as refused before any write when it names them.
|
|
*/
|
|
export type ApiCommandEffectRow = Readonly<{
|
|
classifiesStatus: boolean;
|
|
refusedBeforeWrite?: readonly string[];
|
|
}>;
|
|
|
|
/** A validator slot whose validation is skipped (`unvalidatedPayload`). */
|
|
export type ApiUnvalidatedSlot = "input" | "output" | "problem";
|
|
|
|
/**
|
|
* FE-REG-API. The governed row of one installed HTTP operation, projected
|
|
* from its V3 descriptor (`InstalledHttpContract`). A feature writes the
|
|
* operation once, in its contract contribution; `check:registries` compares
|
|
* these rows with the approved baseline.
|
|
*
|
|
* 1103/07-01. The row carries every wire-facing value of the descriptor:
|
|
* what is sent and accepted, the bounds, and the retry and command data. The
|
|
* governance grades a change (`config/contracts/registry-governance.json`).
|
|
* Only functions stay out (`projectRequest`, the validators' parsing, the
|
|
* command effect classifiers), with the policy and diagnostics names.
|
|
*/
|
|
export type ApiOperationRow = Readonly<{
|
|
operationId: string;
|
|
featureId: string;
|
|
method: HttpMethod;
|
|
path: string;
|
|
authProfileId: string;
|
|
retrySemantics: RetrySemantics;
|
|
requestBody: InstalledHttpContract<unknown, unknown, unknown>["contract"]["requestBody"];
|
|
responseBody: InstalledHttpContract<unknown, unknown, unknown>["contract"]["responseBody"];
|
|
responseEnvelope: ResponseEnvelope;
|
|
requestSchema: string;
|
|
responseSchema: string;
|
|
problemSchema: string;
|
|
acceptedStatuses: readonly number[];
|
|
emptyBodyStatuses: readonly number[];
|
|
/** Validator slots that skip validation by name; `[]` when all validate. */
|
|
unvalidated: readonly ApiUnvalidatedSlot[];
|
|
requestByteLimit: number;
|
|
responseByteLimit: number;
|
|
totalDeadlineMs: number;
|
|
retryBudget: 0 | 1 | 2;
|
|
traffic: TrafficBudget | null;
|
|
commandEffect: ApiCommandEffectRow | null;
|
|
commandRecovery: CommandRecoveryDescriptor | null;
|
|
}>;
|
|
|
|
/**
|
|
* Pass composed contributions (`composeContractContributions`): composition
|
|
* already refused duplicate operation ids and snapshotted every row.
|
|
*/
|
|
export function projectApiOperationRows(
|
|
contributions: readonly InstalledContractContribution[],
|
|
): Readonly<Record<string, ApiOperationRow>> {
|
|
const rows: Record<string, ApiOperationRow> = {};
|
|
for (const contribution of contributions) {
|
|
for (const { contract, frontend } of contribution.http) {
|
|
rows[contract.operationId] = Object.freeze({
|
|
operationId: contract.operationId,
|
|
featureId: contribution.featureId,
|
|
method: contract.method,
|
|
path: contract.pathTemplate,
|
|
authProfileId: frontend.authProfileId,
|
|
retrySemantics: contract.retrySemantics,
|
|
requestBody: contract.requestBody,
|
|
responseBody: contract.responseBody,
|
|
responseEnvelope: contract.responseEnvelope ?? "NONE",
|
|
requestSchema: contract.inputValidator.schemaId,
|
|
responseSchema: contract.outputValidator.schemaId,
|
|
problemSchema: contract.problemValidator.schemaId,
|
|
acceptedStatuses: Object.freeze([...contract.acceptedStatuses]),
|
|
emptyBodyStatuses: Object.freeze([...contract.emptyBodyStatuses]),
|
|
unvalidated: unvalidatedSlots({
|
|
input: contract.inputValidator,
|
|
output: contract.outputValidator,
|
|
problem: contract.problemValidator,
|
|
}),
|
|
requestByteLimit: frontend.requestByteLimit,
|
|
responseByteLimit: frontend.responseByteLimit,
|
|
totalDeadlineMs: frontend.totalDeadlineMs,
|
|
retryBudget: frontend.retryBudget,
|
|
traffic:
|
|
frontend.traffic === undefined
|
|
? null
|
|
: Object.freeze({
|
|
maxPhysicalRequests: frontend.traffic.maxPhysicalRequests,
|
|
maxRetries: frontend.traffic.maxRetries,
|
|
maxConcurrentRequests: frontend.traffic.maxConcurrentRequests,
|
|
maxQueuedRequests: frontend.traffic.maxQueuedRequests,
|
|
}),
|
|
commandEffect: commandEffectRow(contract.commandEffect),
|
|
commandRecovery:
|
|
contract.commandRecovery === null
|
|
? null
|
|
: Object.freeze({ ...contract.commandRecovery }),
|
|
});
|
|
}
|
|
}
|
|
return Object.freeze(rows);
|
|
}
|
|
|
|
/** The same marker rule as `listUnvalidatedPayloads`: any marker counts. */
|
|
function unvalidatedSlots(
|
|
validators: Readonly<Record<ApiUnvalidatedSlot, RuntimeValidator<unknown>>>,
|
|
): readonly ApiUnvalidatedSlot[] {
|
|
return Object.freeze(
|
|
(Object.keys(validators) as ApiUnvalidatedSlot[]).filter(
|
|
(slot) => validators[slot].validation !== undefined,
|
|
),
|
|
);
|
|
}
|
|
|
|
function commandEffectRow(
|
|
effect: CommandEffectDescriptor<unknown> | null,
|
|
): ApiCommandEffectRow | null {
|
|
if (effect === null) return null;
|
|
// Read structurally: a descriptor that does not name refused codes has no
|
|
// such list, and the row then has no such field.
|
|
const refused: unknown = (effect as Readonly<{ refusedBeforeWrite?: unknown }>)
|
|
.refusedBeforeWrite;
|
|
return Object.freeze({
|
|
classifiesStatus: typeof effect.classifyStatus === "function",
|
|
...(Array.isArray(refused)
|
|
? { refusedBeforeWrite: Object.freeze(refused.map(String)) }
|
|
: {}),
|
|
});
|
|
}
|