Commit Graph
3 Commits
Author SHA1 Message Date
DongHyeonka 6c5818faec refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.

고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
  V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
  새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
  JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
  하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
  그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
  해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
  "REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
  src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).

버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
  바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
  매핑을 알아야 한다. 프로필 항목 하나가 더 작다.

위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
  않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
  그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
  보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
  behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
  작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
  항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
  청크라 초기 크기에 영향이 없다.

검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
  undefined to match object { transport: 'BEARER_HEADER', …(1) }",
  "expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
  (FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
  207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
  http-scenario-evidence, ci-workflow-generation, lab-performance,
  fixture-node-modules, deployment-admission, security-followup-archive).
  tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
2026-11-03 00:55:33 +09:00
DongHyeonka c06338956e fix(contracts): 참조 기능 밖의 TEMPLATE_FIXTURE 기여를 거부한다 (07-04)
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.

고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
  ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
  쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
  기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
  있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
  (REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
  이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
  EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
  featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
  테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
  바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
  단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
  읽었는지 아닌지를 구분하지 못했다.

버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
  test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
  /REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
  잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
  남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
  필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
  depcruise로 볼 수 없다.

위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
  (라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
  스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
  복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
  거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
  측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
  꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
  참조 기능 id 하나로만 풀린다.

검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
  external-contract-runtime "rejects a fixture copied into a product
  feature" -> "Expected contract composition to fail."
  reference-fixture-provenance "rejects a second fixture contribution"
  -> "expected undefined to be 'reference-feature: only one
  TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features
  tests/platform tests/component tests/contract tests/runtime-schema
  tests/integration (pnpm·corepack을 띄우는 fixture-node-modules,
  security-followup-archive, deployment-admission, lab-performance 제외)
  267 files / 3107 tests 중 3106 통과. 실패 1건은
  provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로
  scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0.
- 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep).
- 미실행: test:sample-removal, check:architecture(pnpm 필요).

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonkaandClaude Opus 5.5 cb52c74710 fix(contracts): read every installed row through one exact snapshot (Q-6.7-6)
Six modules each had their own exact-key check. Several validated the
caller's object and then copied it again, so an accessor, an own
Symbol.iterator or a non-enumerable key could make the checked value
differ from the installed one (e.g. a TEMPLATE_FIXTURE contribution
passed the events.length === 0 check and still installed an event
through its iterator; a realtime limit getter installed 999,999,999).

exact-snapshot.ts now owns the single reader (decodeExactObject /
decodeOwnDataRecord report a reason; snapshotExactObject,
snapshotOwnDataRecord and exactOwnDataSnapshot are thin forms of it;
read-only-registry.ts re-exports exactOwnDataSnapshot). Contract
composition, browser RPC install, realtime registry, cache invalidation
wire decode, static asset manifest decode and REST auth profile install
validate that snapshot, and copy arrays by index (snapshotExactArray).

Behavior: accessors, non-enumerable keys and custom prototypes are now
rejected in all of these; a throwing reflection trap during contract
composition is a ContractContributionError instead of a native error.

Verified: new tests/unit/contract-snapshot-bypass.test.ts (10 cases,
all RED before), gates green except the known removal-fixture test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:45:37 +09:00