문제 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절
304 lines
9.1 KiB
TypeScript
304 lines
9.1 KiB
TypeScript
import { readFile } from "node:fs/promises";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
canonicalizeRegistryValue,
|
|
diffRegistrySnapshots,
|
|
} from "../../scripts/lib/registry-compatibility.ts";
|
|
import { projectApiOperationRows } from "../../src/contracts/api-operations.ts";
|
|
import { composeContractContributions } from "../../src/contracts/external-contract-runtime.ts";
|
|
import { unvalidatedPayload } from "../../src/contracts/unvalidated-payload.ts";
|
|
import {
|
|
API_OPERATIONS,
|
|
COMPOSED_CONTRACT_CONTRIBUTIONS,
|
|
} from "../../src/features/loaded-feature-runtimes.ts";
|
|
import {
|
|
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
|
|
TEST_CONTRACT_CONTRIBUTION,
|
|
TEST_CREATE_HTTP_CONTRACT,
|
|
TEST_LIST_HTTP_CONTRACT,
|
|
} from "../helpers/external-contract-fixture.ts";
|
|
|
|
/**
|
|
* FE-REG-API rows are projected from the installed HTTP descriptors, so an
|
|
* operation is written once and the governed row cannot disagree with what
|
|
* executes.
|
|
*/
|
|
describe("FE-REG-API rows projected from HTTP descriptors", () => {
|
|
it("projects each descriptor with its feature, wire and schema identities", () => {
|
|
const rows = projectApiOperationRows(
|
|
composeContractContributions([TEST_CONTRACT_CONTRIBUTION]).contributions,
|
|
);
|
|
|
|
expect(Object.keys(rows)).toEqual([
|
|
"TEST_LIST_ENTITIES",
|
|
"TEST_GET_ENTITY",
|
|
"TEST_CREATE_ENTITY",
|
|
]);
|
|
expect(rows.TEST_LIST_ENTITIES).toEqual({
|
|
operationId: "TEST_LIST_ENTITIES",
|
|
featureId: "test-feature",
|
|
method: "GET",
|
|
path: "/api/test-entities",
|
|
authProfileId: "ANONYMOUS",
|
|
retrySemantics: "SAFE",
|
|
requestBody: "NONE",
|
|
responseBody: "REQUIRED_JSON",
|
|
responseEnvelope: "NONE",
|
|
requestSchema: "TestEntityListQuery",
|
|
responseSchema: "TestEntityListPayload",
|
|
problemSchema: "TestProblem",
|
|
acceptedStatuses: [200],
|
|
emptyBodyStatuses: [],
|
|
unvalidated: [],
|
|
requestByteLimit: 0,
|
|
responseByteLimit: 32_768,
|
|
totalDeadlineMs: 10_000,
|
|
retryBudget: 2,
|
|
traffic: null,
|
|
commandEffect: null,
|
|
commandRecovery: null,
|
|
});
|
|
expect(rows.TEST_CREATE_ENTITY).toMatchObject({
|
|
method: "POST",
|
|
retrySemantics: "KEYED",
|
|
requestBody: "JSON",
|
|
acceptedStatuses: [201],
|
|
retryBudget: 0,
|
|
commandEffect: { classifiesStatus: false },
|
|
commandRecovery: {
|
|
mode: "IDEMPOTENCY_REPLAY",
|
|
operationIdentityField: "idempotencyKey",
|
|
},
|
|
});
|
|
expect(rows.TEST_CREATE_ENTITY?.commandEffect).not.toHaveProperty(
|
|
"refusedBeforeWrite",
|
|
);
|
|
});
|
|
|
|
it("carries the command effect data and the validator slots that skip validation", () => {
|
|
const traffic = Object.freeze({
|
|
maxPhysicalRequests: 2,
|
|
maxRetries: 1,
|
|
maxConcurrentRequests: 1,
|
|
maxQueuedRequests: 0,
|
|
});
|
|
const rows = projectApiOperationRows(
|
|
composeContractContributions([
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [
|
|
{
|
|
...TEST_LIST_HTTP_CONTRACT,
|
|
contract: {
|
|
...TEST_LIST_HTTP_CONTRACT.contract,
|
|
outputValidator: unvalidatedPayload(
|
|
"TestEntityListPayload",
|
|
"typed by the package",
|
|
),
|
|
},
|
|
frontend: { ...TEST_LIST_HTTP_CONTRACT.frontend, traffic },
|
|
},
|
|
{
|
|
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT,
|
|
contract: {
|
|
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract,
|
|
// A descriptor that names the codes refused before any write.
|
|
commandEffect: {
|
|
...TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract.commandEffect,
|
|
refusedBeforeWrite: ["VALIDATION_FAILED", "CONFLICT"],
|
|
},
|
|
},
|
|
},
|
|
] as never,
|
|
},
|
|
]).contributions,
|
|
);
|
|
|
|
expect(rows.TEST_LIST_ENTITIES).toMatchObject({
|
|
unvalidated: ["output"],
|
|
traffic,
|
|
});
|
|
expect(rows.TEST_CREATE_ENTITY?.commandEffect).toEqual({
|
|
classifiesStatus: true,
|
|
refusedBeforeWrite: ["VALIDATION_FAILED", "CONFLICT"],
|
|
});
|
|
});
|
|
|
|
it("carries an Envelope declaration", () => {
|
|
const rows = projectApiOperationRows(
|
|
composeContractContributions([
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [
|
|
{
|
|
...TEST_LIST_HTTP_CONTRACT,
|
|
contract: {
|
|
...TEST_LIST_HTTP_CONTRACT.contract,
|
|
responseEnvelope: "ENVELOPE_V1" as const,
|
|
},
|
|
},
|
|
] as never,
|
|
},
|
|
]).contributions,
|
|
);
|
|
|
|
expect(rows.TEST_LIST_ENTITIES?.responseEnvelope).toBe("ENVELOPE_V1");
|
|
});
|
|
|
|
it("is what the registry governance reads for the installed features", () => {
|
|
expect(API_OPERATIONS).toEqual(
|
|
projectApiOperationRows(COMPOSED_CONTRACT_CONTRIBUTIONS.contributions),
|
|
);
|
|
expect(Object.keys(API_OPERATIONS).sort()).toEqual(
|
|
[...COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.keys()].sort(),
|
|
);
|
|
});
|
|
});
|
|
|
|
/**
|
|
* 1103/07-01. The wire values of a descriptor are graded by the governance
|
|
* the repository ships, not only recorded: narrowing what the frontend
|
|
* accepts, or changing how it validates, needs baseline evidence.
|
|
*/
|
|
describe("FE-REG-API compatibility of descriptor wire values", () => {
|
|
async function snapshotOf(
|
|
rows: Readonly<Record<string, unknown>>,
|
|
): Promise<Readonly<Record<string, unknown>>> {
|
|
const governance = JSON.parse(
|
|
await readFile("config/contracts/registry-governance.json", "utf8"),
|
|
) as {
|
|
registries: Array<{
|
|
registryId: string;
|
|
breakingFields: string[];
|
|
fieldTypes: Record<string, string>;
|
|
}>;
|
|
};
|
|
const api = governance.registries.find(
|
|
(registry) => registry.registryId === "FE-REG-API",
|
|
)!;
|
|
return {
|
|
registries: [
|
|
{
|
|
registryId: "FE-REG-API",
|
|
contract: {
|
|
breakingFields: api.breakingFields,
|
|
fieldTypes: api.fieldTypes,
|
|
},
|
|
rows: canonicalizeRegistryValue(rows),
|
|
},
|
|
],
|
|
};
|
|
}
|
|
const rowsWith = (
|
|
contract: Partial<typeof TEST_CREATE_HTTP_CONTRACT.contract> = {},
|
|
frontend: Partial<typeof TEST_CREATE_HTTP_CONTRACT.frontend> = {},
|
|
) =>
|
|
projectApiOperationRows(
|
|
composeContractContributions([
|
|
{
|
|
...TEST_CONTRACT_CONTRIBUTION,
|
|
http: [
|
|
{
|
|
contract: {
|
|
...TEST_CREATE_HTTP_CONTRACT.contract,
|
|
acceptedStatuses: [200, 201],
|
|
emptyBodyStatuses: [201],
|
|
...contract,
|
|
},
|
|
frontend: { ...TEST_CREATE_HTTP_CONTRACT.frontend, ...frontend },
|
|
},
|
|
] as never,
|
|
},
|
|
]).contributions,
|
|
);
|
|
async function changesFor(after: Readonly<Record<string, unknown>>) {
|
|
const diff = diffRegistrySnapshots(
|
|
await snapshotOf(rowsWith()),
|
|
await snapshotOf(after),
|
|
);
|
|
return diff.changes.map(({ changeId, impact }) => `${changeId} ${impact}`);
|
|
}
|
|
|
|
it.each([
|
|
[
|
|
"a narrowed status list",
|
|
{ acceptedStatuses: [201] },
|
|
{},
|
|
[
|
|
"FE-REG-API:TEST_CREATE_ENTITY:acceptedStatuses:allowed-value-removed breaking",
|
|
],
|
|
],
|
|
[
|
|
"a narrowed empty-body list",
|
|
{ emptyBodyStatuses: [] },
|
|
{},
|
|
[
|
|
"FE-REG-API:TEST_CREATE_ENTITY:emptyBodyStatuses:allowed-value-removed breaking",
|
|
],
|
|
],
|
|
[
|
|
"another problem schema",
|
|
{
|
|
problemValidator: {
|
|
...TEST_CREATE_HTTP_CONTRACT.contract.problemValidator,
|
|
schemaId: "OtherProblem",
|
|
},
|
|
},
|
|
{},
|
|
["FE-REG-API:TEST_CREATE_ENTITY:problemSchema:field-changed breaking"],
|
|
],
|
|
[
|
|
"an output whose validation is skipped",
|
|
{ outputValidator: unvalidatedPayload("TestEntityPayload", "trusted") },
|
|
{},
|
|
["FE-REG-API:TEST_CREATE_ENTITY:unvalidated:field-changed breaking"],
|
|
],
|
|
[
|
|
"a widened status list",
|
|
{ acceptedStatuses: [200, 201, 202] },
|
|
{},
|
|
[
|
|
"FE-REG-API:TEST_CREATE_ENTITY:acceptedStatuses:field-changed behavior-change",
|
|
],
|
|
],
|
|
[
|
|
"a larger response limit and a longer deadline",
|
|
{},
|
|
{ responseByteLimit: 8_388_608, totalDeadlineMs: 60_000 },
|
|
[
|
|
"FE-REG-API:TEST_CREATE_ENTITY:responseByteLimit:field-changed behavior-change",
|
|
"FE-REG-API:TEST_CREATE_ENTITY:totalDeadlineMs:field-changed behavior-change",
|
|
],
|
|
],
|
|
[
|
|
"a traffic policy",
|
|
{},
|
|
{
|
|
traffic: {
|
|
maxPhysicalRequests: 1,
|
|
maxRetries: 0,
|
|
maxConcurrentRequests: 1,
|
|
maxQueuedRequests: 0,
|
|
},
|
|
},
|
|
["FE-REG-API:TEST_CREATE_ENTITY:traffic:field-changed behavior-change"],
|
|
],
|
|
[
|
|
"a status classifier",
|
|
{
|
|
commandEffect: TEST_CLASSIFIED_CREATE_HTTP_CONTRACT.contract.commandEffect,
|
|
},
|
|
{},
|
|
[
|
|
"FE-REG-API:TEST_CREATE_ENTITY:commandEffect:field-changed behavior-change",
|
|
],
|
|
],
|
|
] as const)("grades %s", async (_name, contract, frontend, expected) => {
|
|
expect(await changesFor(rowsWith(contract as never, frontend as never))).toEqual(
|
|
expected,
|
|
);
|
|
});
|
|
});
|