문제 짝 백엔드 계약의 기준 커밋은 계약 문서의 문장(백엔드 5786126c)뿐이고, 이 SHA를 읽는 코드·설정·테스트가 없다. 쓰기 전 거절 표 REFUSED_BEFORE_WRITE와 5xx 판정은 백엔드 http-contract.md §2를 손으로 옮긴 것이다. 리뷰 중 백엔드에 bbe944bd가 들어와 503 IDEMPOTENCY_COMPLETION_UNKNOWN이 새로 생겼는데 프론트의 어떤 검사도 알리지 않았다(README 10.6). 고른 방법 (결정 D6 (1)+(2)) - config/contracts/backend-contract-pin.json: repo, 전체 SHA(bbe944bd), 대조한 문서와 절(§1·§2·§4), 프론트 쪽 계약 절·판정 파일, 담당. - config/contracts/backend-idempotency-answers.json: 백엔드 §2 표 여섯 행과 §4 REQUEST_TIMEOUT을 code·status·쓰기 전 거절·같은 키 재전송 열로 옮겼다. 백엔드가 문서에 적은 사실만 담는다. - tests/unit/backend-contract-pin.test.ts: 두 JSON의 모양과 같은 SHA를 확인하고, 답마다 프론트 판정이 그 두 열에서 나오는 값인지(쓰기 전 거절이면서 같은 키 재전송이 아니면 NOT_APPLIED, 아니면 MAYBE_APPLIED, 자동 재전송은 둘 다 참일 때만) 본다. 반대로 프론트 표의 행이 모두 이 답 표나 6.1절 읽기(VALIDATION_FAILED)로 뒷받침되는지 본다. 그래서 백엔드 표에 행이 늘거나 status가 바뀐 JSON을 넣으면 실패한다. - scripts/check-backend-contract-drift.ts(check:backend-contract-drift): 형제 디렉터리(또는 --backend)의 백엔드 checkout이 pin 뒤에 http-contract.md를 바꿨는지 알리고 바뀐 표 행을 보인다. CI에는 백엔드가 없어 게이트 밖이다. ungated-scripts.json에 이유를 적었다. - 계약 문서 4.1·6절의 기준 커밋을 bbe944bd와 pin 파일로 옮겼다. 6.1절 표는 5786126c..bbe944bd 사이 바뀐 백엔드 파일 다섯을 다시 읽었다. 판정은 같고 줄 번호만 옮겼다(IdempotencyExecutor, GlobalExceptionHandler → HttpStatusErrorCodes, FailureCategory, PersistenceExceptionTranslator). 버린 대안 - 백엔드 error-codes.yaml과 문서 다이제스트를 기록: 다이제스트는 바뀐 것만 알리고 무엇을 고칠지 말하지 않는다. - 백엔드가 계약 패키지를 발행: 백엔드 빌드에 JS 발행이 생긴다. 지금 규모에는 pin과 표가 작다. 위험·한계 - 답 표 JSON은 사람이 백엔드 문서에서 옮긴다. 옮기는 실수는 drift 스크립트와 리뷰가 잡는다. 백엔드 쪽이 같은 JSON을 자기 레지스트리와 대조하는 일은 백엔드 저장소 몫이다. - 백엔드 HEAD는 이미 pin 뒤로 갔다(지금 c508b1ba). http-contract.md §2의 500 IDEMPOTENCY_RECOVERY_REQUIRED 행이 "같은 키 재전송은 안전하다"로 바뀌었다. 프론트 판정(MAYBE_APPLIED, 자동 재전송 없음, 사용자 재전송은 같은 키)은 그 문장과도 맞는다. pin은 지시대로 bbe944bd에 두었다. 검증 - 새 테스트 10건 통과. 변이 4종 검출: 답 표에 503 새 code 행 추가, 프론트 표에서 COMPLETION_UNKNOWN 제거, 프론트 표에 근거 없는 400 BAD_PARAMETER 추가, 답 표의 RECOVERY_REQUIRED status 변경. - check:backend-contract-drift: worktree에서 skipped(exit 0), 실제 백엔드 checkout으로 exit 1과 바뀐 RECOVERY_REQUIRED 행 출력. - test:unit 178파일 2,645건, check:ci, check:types, eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-06 Refs: docs/reviews/2026-11-03-maturity-review/README.md 10.6
144 lines
4.8 KiB
TypeScript
144 lines
4.8 KiB
TypeScript
import { readFileSync } from "node:fs";
|
|
|
|
import { describe, expect, it } from "vitest";
|
|
import { z } from "zod";
|
|
|
|
import {
|
|
envelopeFailureEffect,
|
|
invitesKeyedResend,
|
|
maybeAppliedAnswerRows,
|
|
refusedBeforeWriteRows,
|
|
} from "../../src/adapters/http/backend-envelope.ts";
|
|
|
|
/**
|
|
* 1103/12-06. The paired backend's contract is pinned in a file a machine
|
|
* reads, and its answer table (http-contract.md §2, with §4's async timeout)
|
|
* is copied next to the pin. This test holds the frontend's Envelope table to
|
|
* that copy, in both directions. When the backend adds or changes an answer,
|
|
* the copy changes with the pin and this test says which frontend verdict has
|
|
* to follow.
|
|
*/
|
|
const COMMIT = /^[0-9a-f]{40}$/u;
|
|
|
|
const pinSchema = z
|
|
.object({
|
|
schemaVersion: z.literal(1),
|
|
backend: z
|
|
.object({
|
|
repository: z.string().min(1),
|
|
commit: z.string().regex(COMMIT),
|
|
document: z.string().min(1),
|
|
sectionsCompared: z.array(z.string().min(1)).min(1),
|
|
})
|
|
.strict(),
|
|
frontend: z
|
|
.object({
|
|
contractDocument: z.string().min(1),
|
|
contractSections: z.array(z.string().min(1)).min(1),
|
|
readers: z.array(z.string().min(1)).min(1),
|
|
})
|
|
.strict(),
|
|
tables: z.object({ idempotencyAnswers: z.string().min(1) }).strict(),
|
|
owner: z.string().min(1),
|
|
comparedOn: z.string().regex(/^\d{4}-\d{2}-\d{2}$/u),
|
|
})
|
|
.strict();
|
|
|
|
const answersSchema = z
|
|
.object({
|
|
schemaVersion: z.literal(1),
|
|
source: z
|
|
.object({
|
|
repository: z.string().min(1),
|
|
commit: z.string().regex(COMMIT),
|
|
document: z.string().min(1),
|
|
})
|
|
.strict(),
|
|
answers: z
|
|
.array(
|
|
z
|
|
.object({
|
|
section: z.string().min(1),
|
|
code: z.string().regex(/^[A-Z0-9_]{1,64}$/u),
|
|
status: z.number().int().min(400).max(599),
|
|
// The backend says the command did not run and will not.
|
|
refusedBeforeWrite: z.boolean(),
|
|
// The backend asks for the same request with the same key.
|
|
sameKeyResend: z.boolean(),
|
|
})
|
|
.strict(),
|
|
)
|
|
.min(1),
|
|
})
|
|
.strict();
|
|
|
|
const pin = pinSchema.parse(
|
|
JSON.parse(readFileSync("config/contracts/backend-contract-pin.json", "utf8")),
|
|
);
|
|
const table = answersSchema.parse(
|
|
JSON.parse(readFileSync(pin.tables.idempotencyAnswers, "utf8")),
|
|
);
|
|
|
|
/**
|
|
* The refusal-table codes that come from the frontend's own reading of the
|
|
* backend code (contract 6.1), not from the backend's answer table.
|
|
*/
|
|
const FRONTEND_CODE_READINGS: readonly Readonly<{ code: string; status: number }>[] = [
|
|
{ code: "VALIDATION_FAILED", status: 400 },
|
|
];
|
|
|
|
describe("paired backend contract pin", () => {
|
|
it("names one backend commit for the pin and the copied table", () => {
|
|
expect(table.source).toEqual({
|
|
repository: pin.backend.repository,
|
|
commit: pin.backend.commit,
|
|
document: pin.backend.document,
|
|
});
|
|
expect(pin.frontend.readers).toContain("src/adapters/http/backend-envelope.ts");
|
|
});
|
|
|
|
it("copies each backend answer once", () => {
|
|
const keys = table.answers.map((answer) => `${answer.status} ${answer.code}`);
|
|
expect(new Set(keys).size).toBe(keys.length);
|
|
});
|
|
|
|
// What the frontend does with each backend answer, from the two facts the
|
|
// backend states. A refusal the backend asks to resend with the same key
|
|
// stays unknown, because only an unknown result keeps the key.
|
|
it.each(table.answers.map((answer) => [`${answer.status} ${answer.code}`, answer] as const))(
|
|
"reads the backend's %s as its table says",
|
|
(_label, answer) => {
|
|
const error = { code: answer.code };
|
|
const expected =
|
|
answer.refusedBeforeWrite && !answer.sameKeyResend
|
|
? "NOT_APPLIED"
|
|
: "MAYBE_APPLIED";
|
|
expect(envelopeFailureEffect(answer.status, error)).toBe(expected);
|
|
expect(invitesKeyedResend(answer.status, error)).toBe(
|
|
answer.refusedBeforeWrite && answer.sameKeyResend,
|
|
);
|
|
},
|
|
);
|
|
|
|
it("backs every frontend table row with the backend table or the 6.1 reading", () => {
|
|
const backed = (row: Readonly<{ code: string; status: number }>) =>
|
|
table.answers.some(
|
|
(answer) => answer.code === row.code && answer.status === row.status,
|
|
);
|
|
for (const row of refusedBeforeWriteRows()) {
|
|
const reading = FRONTEND_CODE_READINGS.some(
|
|
(candidate) => candidate.code === row.code && candidate.status === row.status,
|
|
);
|
|
expect(reading || backed(row), `${row.status} ${row.code}`).toBe(true);
|
|
if (!reading) {
|
|
expect(
|
|
table.answers.find((answer) => answer.code === row.code)?.refusedBeforeWrite,
|
|
).toBe(true);
|
|
}
|
|
}
|
|
for (const row of maybeAppliedAnswerRows()) {
|
|
expect(backed(row), `${row.status} ${row.code}`).toBe(true);
|
|
}
|
|
});
|
|
});
|