문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.
고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.
위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.
검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx
BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.
Refs: 1103/16-05
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.
고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
온 이전 응답은 버려진 client에 쓰인다. 이 동작을
server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.
위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.
검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
"error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
통과(옮긴 테스트 포함). tests/unit·component·features·contract·
runtime-schema·architecture·scripts·integration(security-followup-
archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
(바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
raw 호출이 있어 harness와 함께 동기화해야 한다.
BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03