문제 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절
249 lines
6.9 KiB
TypeScript
249 lines
6.9 KiB
TypeScript
import {
|
|
mappingSuccess,
|
|
type InstalledBoundaryMapper,
|
|
} from "../../../src/contracts/boundary-mapper.ts";
|
|
import type { ApiOperationRow } from "../../../src/contracts/api-operations.ts";
|
|
import {
|
|
createRealtimePolicyRegistry,
|
|
defineEventTypeId,
|
|
defineExternalEventEffectProfileId,
|
|
defineRealtimeEndpointId,
|
|
defineRealtimeKillSwitchId,
|
|
defineStreamRegistrationId,
|
|
type RealtimeEventTypeRegistration,
|
|
type RealtimeLimits,
|
|
type RealtimePolicyRegistry,
|
|
type RealtimeRecoveryProfile,
|
|
type RealtimeStreamRegistration,
|
|
} from "../../../src/contracts/realtime-streams.ts";
|
|
import type { RuntimeSchemaCodec } from "../../../src/contracts/schema-registry.ts";
|
|
import {
|
|
createRealtimeEventCodec,
|
|
type RealtimeEventCodec,
|
|
} from "../../../src/adapters/realtime/event-codec.ts";
|
|
|
|
export const STREAM_ID = defineStreamRegistrationId("REFERENCE_STREAM");
|
|
export const EVENT_TYPE = defineEventTypeId("REFERENCE_CHANGED");
|
|
export const ENDPOINT_ID = defineRealtimeEndpointId("REFERENCE_ENDPOINT");
|
|
export const EFFECT_PROFILE_ID =
|
|
defineExternalEventEffectProfileId("REFERENCE_INVALIDATE");
|
|
export const KILL_SWITCH_ID =
|
|
defineRealtimeKillSwitchId("REFERENCE_KILL_SWITCH");
|
|
|
|
export const TEST_LIMITS: RealtimeLimits = Object.freeze({
|
|
maxEventBytes: 4_096,
|
|
maxPayloadDepth: 8,
|
|
maxPayloadNodes: 128,
|
|
maxQueueEvents: 8,
|
|
maxQueueBytes: 32_768,
|
|
maxDedupeEntries: 16,
|
|
maxDedupeBytes: 32_768,
|
|
dedupeTtlMs: 60_000,
|
|
});
|
|
|
|
const eventPayloadCodec: RuntimeSchemaCodec = Object.freeze({
|
|
schemaId: "ReferenceRealtimePayload",
|
|
parse(value) {
|
|
if (
|
|
!value ||
|
|
typeof value !== "object" ||
|
|
Array.isArray(value) ||
|
|
Object.keys(value).length !== 1 ||
|
|
typeof (value as Readonly<Record<string, unknown>>).value !== "string"
|
|
) {
|
|
return {
|
|
success: false,
|
|
issues: [{ path: "value", code: "INVALID_TYPE" }],
|
|
};
|
|
}
|
|
return {
|
|
success: true,
|
|
data: {
|
|
value: (value as Readonly<Record<string, string>>).value,
|
|
},
|
|
};
|
|
},
|
|
});
|
|
|
|
const checkpointCodec: RuntimeSchemaCodec = Object.freeze({
|
|
schemaId: "ReferenceRealtimeCheckpoint",
|
|
parse: (value) => ({ success: true, data: value }),
|
|
});
|
|
|
|
export const TEST_SCHEMA_CODECS = Object.freeze({
|
|
ReferenceRealtimePayload: eventPayloadCodec,
|
|
ReferenceRealtimeCheckpoint: checkpointCodec,
|
|
});
|
|
|
|
export const TEST_MAPPER: InstalledBoundaryMapper = Object.freeze({
|
|
mapperId: "ReferenceRealtimeMapper",
|
|
mapperVersion: 1,
|
|
inputSchemaId: "ReferenceRealtimePayload",
|
|
outputContractId: "ReferenceRealtimeEvent",
|
|
owner: "sample-owner",
|
|
maxOutputItems: 1,
|
|
map(input) {
|
|
if (
|
|
!input ||
|
|
typeof input !== "object" ||
|
|
typeof (input as Readonly<Record<string, unknown>>).value !== "string"
|
|
) {
|
|
return { ok: false, code: "MAPPING_INVARIANT_REJECTED" };
|
|
}
|
|
return mappingSuccess(
|
|
Object.freeze({
|
|
value: (input as Readonly<Record<string, string>>).value,
|
|
}),
|
|
);
|
|
},
|
|
});
|
|
|
|
export const TEST_MAPPERS = Object.freeze({
|
|
ReferenceRealtimeMapper: TEST_MAPPER,
|
|
});
|
|
|
|
const snapshotOperation: ApiOperationRow = Object.freeze({
|
|
operationId: "GET_REFERENCE_REALTIME_SNAPSHOT",
|
|
featureId: "sample-feature",
|
|
method: "GET",
|
|
path: "/api/reference-snapshot",
|
|
authProfileId: "EXTERNAL_BEARER",
|
|
retrySemantics: "SAFE",
|
|
requestBody: "NONE",
|
|
responseBody: "REQUIRED_JSON",
|
|
responseEnvelope: "NONE",
|
|
requestSchema: "NoRequest",
|
|
responseSchema: "ReferenceRealtimeCheckpoint",
|
|
problemSchema: "ReferenceRealtimeProblem",
|
|
acceptedStatuses: [200],
|
|
emptyBodyStatuses: [],
|
|
unvalidated: [],
|
|
requestByteLimit: 0,
|
|
responseByteLimit: 32_768,
|
|
totalDeadlineMs: 10_000,
|
|
retryBudget: 2,
|
|
traffic: null,
|
|
commandEffect: null,
|
|
commandRecovery: null,
|
|
});
|
|
|
|
export const TEST_API_OPERATIONS = Object.freeze({
|
|
GET_REFERENCE_REALTIME_SNAPSHOT: snapshotOperation,
|
|
});
|
|
|
|
export type TestRegistryOptions = Readonly<{
|
|
recovery?: RealtimeRecoveryProfile;
|
|
delivery?: RealtimeStreamRegistration["delivery"];
|
|
stateBearing?: boolean;
|
|
limits?: RealtimeLimits;
|
|
streamMutator?: (
|
|
stream: RealtimeStreamRegistration,
|
|
) => RealtimeStreamRegistration;
|
|
eventTypeMutator?: (
|
|
eventType: RealtimeEventTypeRegistration,
|
|
) => RealtimeEventTypeRegistration;
|
|
}>;
|
|
|
|
export function createTestRealtimeRegistry(
|
|
options: TestRegistryOptions = {},
|
|
): RealtimePolicyRegistry {
|
|
const recovery =
|
|
options.recovery ??
|
|
({
|
|
mode: "CURSOR",
|
|
snapshotOperationId: "GET_REFERENCE_REALTIME_SNAPSHOT",
|
|
checkpointCodecId: "ReferenceRealtimeCheckpoint",
|
|
barrier: "REPLAY",
|
|
} as const);
|
|
const eventType: RealtimeEventTypeRegistration = {
|
|
id: EVENT_TYPE,
|
|
owner: "sample-owner",
|
|
payloadSchemaId: "ReferenceRealtimePayload",
|
|
mapperId: "ReferenceRealtimeMapper",
|
|
effectProfileId: EFFECT_PROFILE_ID,
|
|
stateBearing: options.stateBearing ?? true,
|
|
};
|
|
const stream: RealtimeStreamRegistration = {
|
|
id: STREAM_ID,
|
|
protocol: "REALTIME_EVENT_V1",
|
|
owner: "sample-owner",
|
|
scope: "ACCOUNT_BOUND",
|
|
primaryTransport: "SSE",
|
|
endpointId: ENDPOINT_ID,
|
|
eventTypeIds: [EVENT_TYPE],
|
|
delivery: options.delivery ?? "AUTHORITATIVE_DELTA",
|
|
recovery,
|
|
fallback:
|
|
recovery.mode === "SESSION_REBUILD"
|
|
? "EXPLICITLY_STALE"
|
|
: "BOUNDED_POLLING",
|
|
hiddenPolicy: "CLOSE",
|
|
limits: options.limits ?? TEST_LIMITS,
|
|
killSwitchId: KILL_SWITCH_ID,
|
|
};
|
|
return createRealtimePolicyRegistry({
|
|
streams: [options.streamMutator?.(stream) ?? stream],
|
|
eventTypes: [
|
|
options.eventTypeMutator?.(eventType) ?? eventType,
|
|
],
|
|
bindings: {
|
|
schemaCodecs: TEST_SCHEMA_CODECS,
|
|
mappers: TEST_MAPPERS,
|
|
apiOperations: TEST_API_OPERATIONS,
|
|
endpointIds: [ENDPOINT_ID],
|
|
effectProfileIds: [EFFECT_PROFILE_ID],
|
|
killSwitchIds: [KILL_SWITCH_ID],
|
|
rebuildInputIds: ["referenceRealtimeRebuild"],
|
|
},
|
|
});
|
|
}
|
|
|
|
export function createTestRealtimeCodec(
|
|
registry = createTestRealtimeRegistry(),
|
|
): RealtimeEventCodec {
|
|
return createRealtimeEventCodec({
|
|
registry,
|
|
schemaCodecs: TEST_SCHEMA_CODECS,
|
|
});
|
|
}
|
|
|
|
export type EventOverrides = Readonly<{
|
|
protocol?: unknown;
|
|
streamId?: unknown;
|
|
streamEpoch?: unknown;
|
|
eventType?: unknown;
|
|
eventId?: unknown;
|
|
sequence?: unknown;
|
|
recoveryMode?: unknown;
|
|
resumeCursor?: unknown;
|
|
occurredAt?: unknown;
|
|
scopeBinding?: unknown;
|
|
payload?: unknown;
|
|
}>;
|
|
|
|
export function realtimeEventValue(
|
|
overrides: EventOverrides = {},
|
|
): Readonly<Record<string, unknown>> {
|
|
return {
|
|
protocol: "REALTIME_EVENT_V1",
|
|
streamId: STREAM_ID,
|
|
streamEpoch: "stream-epoch-0001",
|
|
eventType: EVENT_TYPE,
|
|
eventId: "event-00000001",
|
|
sequence: "1",
|
|
recoveryMode: "CURSOR",
|
|
resumeCursor: "cursor-00000001",
|
|
occurredAt: "2026-07-28T01:02:03.123Z",
|
|
scopeBinding: "scope-binding-0001",
|
|
payload: { value: "changed" },
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
export function realtimeEventJson(
|
|
overrides: EventOverrides = {},
|
|
): string {
|
|
return JSON.stringify(realtimeEventValue(overrides));
|
|
}
|
|
|