quad/.claude/session/2026-08-14-09-postref-confirmed.md

2026-08-14 아홉 번째 세션 — PostRef 확정, OnRendered 채택, PreRef/PostRef 계열 안 순서 미보장으로 역전, lifecycle-hooks-plan.md base 승격

사용자 지시 (원문 그대로)

PostRef 확정. PreRef 랑 PostRef(lifecycle-hooks-plan.md 에서 스케치됨) 을 이제 완전 ref 에 반영 가능할듯. PostRef 는 child 전부 마운트 된 후에 처리됨 - 중간 for문에서 모든 Slot, State, Frame 등 요소의 마운트가 처리될것이므로, Slot 의 실 확정이 바로 요소를 주입해주므로, 바로 뒤에서 실행하면 모든 트리가 완성된 이후가 됨. '착수 시점에 판단할 선택지' 는 (a) 택해도 될듯 하고, Pre-Post 둘을 지원 안 할 이유가 없고, 구현 난이도가 아주 낮아서 괜찮다는게 내 결론. ChildAdded 를 나중에 들어오는것만 처리하고 싶어서, boolean 으로 flag 지정해둔다던가 뭐, 아에 쓸모 없을 만한건 아니라 봄. Ref 는 그냥 설정해주고, 언제 설정할진 모름. PreRef 는 프로퍼티/자식 들어오기 전에 설정됨. 각 PreRef 간의 순서는 보장 안함. PostRef 는 프로퍼티/자식 들어온 후 설정됨, PostRef간 순서는 보장 안함(실제로 하더라도, 안 한다고 두는게 버그를 차라리 덜 만든다고 생각함. 같은 계열 내 Ref 등록 순서에 의존하는 무언가가 생겨선 안된다는 생각, 그건 구조부터 잘못된거니까) OnRendered 도 채택. ref 문서 업데이트와 lifecycle-hooks-plan.md 의 승격을 시키고, 핸드오버/세션기록 준비하고 커밋해줘, 뭔가 걸리는게 있으면 말 해

세션 도중 사용자 추가 메시지 둘: (1) 다른 에이전트가 session/에 파일을 export 중이니 커밋 시 예외하라 → (2) 곧이어 "이제 너 말고 다른 에이전트 없어, 무엇을 바꾸든 상관 없어"로 해제.

확정된 것

1. PostRef — base 프리미티브로 확정

여섯 번째 세션이 백로그 후보로만 남겨뒀던 스케치(그 뒤 네 번째 세션이 ProcessedPreRef 선례를 반영해 갱신)를 그대로 채택. 선택지 (a)/(b)/(c) 중 (a) — pre-pass 공동 수집 + 두 패스 뒤 postRefList 소비.

메커니즘(정본은 base/ref-plan.md의 "PostRef" 절):

1. 기존 PreRef pre-pass 한 스윕에 분기 하나 추가 — isPostRef(v)면 fire하지 않고 로컬 배열 postRefList에 push, 즉시 flattened[i] = ProcessedPostRef로 소진(+_fired 세팅).
2. 정상 두 패스가 ProcessedPostRefHandler로 그 자리를 매치해 setLength(0)/setOffsetSource(None) 등록(= ProcessedPreRefHandler의 완전한 거울상, 코드 한 글자 차이).
3. 두 패스가 끝난 뒤 Dispatch.drive가 postRefList를 순회하며 fire.

새 전체 순회 없음 — 추가 비용은 실제 PostRef 개수만큼의 짧은 루프뿐. 동적 경로 가드 Handler, 1회용 _fired, Modifier/Store 타입 차단, isRef 포함 관계까지 전부 PreRef의 거울상으로 그대로 복제됨.

2. 스코프 — 원래 문서의 (a)/(b) 구분이 애초에 잘못된 축이었음

원 문서는 "(a) 자기 프로퍼티/이벤트만 vs (b) 자식 서브트리까지"를 열어두고 "(a) 메커니즘은 (b)를 못 준다"고 적어놨었는데, 사용자 지적으로 그게 틀렸음이 드러남 — 배열 파트 루프가 각 자식의 마운트를 동기적으로 끝내고 넘어가고(Slot은 실 확정 시 요소를 그 자리에서 주입, State<Frame>도 최초 값을 그 자리에서 처리) 해시 파트는 그 뒤이므로, (a) 메커니즘이 사실상 (b) 스코프를 공짜로 줌.

대신 진짜 경계는 "자기 아래 vs 자기 위"였음 — Claude가 추가로 짚은 캐비엇: PostRef는 자기 서브트리 완성은 보장하지만 이 인스턴스가 부모에 붙는 것(.Parent 대입)보다는 여전히 먼저 불림. Frame{ Frame{...} } 처럼 리터럴로 중첩하면 안쪽 Frame 호출이 먼저 완결되어야 바깥 Frame의 props 테이블이 완성되기 때문. React componentDidMount(DOM 삽입 후)와 다르므로 OnRendered 이름과 함께 반드시 문서화하기로 함.

3. PreRef/PostRef 계열 안 fire 순서 — 미보장으로 역전

2026-08-07 아홉 번째 세션이 "복수 PreRef 간 순서 = 배열 index 순서 그대로 보장"으로 확정해뒀던 걸 뒤집음. 구현이 아니라 계약만 바뀜 (pre-pass는 여전히 index 순서로 훑음). 사용자 근거: "같은 계열 내 Ref 등록 순서에 의존하는 무언가가 생겨선 안된다는 생각, 그건 구조부터 잘못된거니까."

역전 원문·근거·영향 범위는 archive/preref-order-guaranteed-reversed.md. 보장이 그대로 유지되는 건 호이스팅(PreRef 전체가 나머지보다 먼저)과 PostRef("두 패스가 전부 끝난 뒤") 쪽.

4. OnRendered 채택 + lifecycle-hooks-plan.md base 승격

OnRendered(fn) = PostRef():Callback(fn). 이걸로 그 문서의 마지막 열린 항목(채택 여부/메커니즘/스코프)이 전부 닫혀 research/ → base/ 승격 (git mv). 패키지는 quad-base 확정. 남은 건 OnDestroyed 이름 재검토 여지 하나뿐이라 question.md 용어 정리 대기열에 3순위로 올림 — Slot/Brand처럼 "base 확정, 이름만 재검토 대상"인 기존 항목들과 같은 취급.

우선순위는 두 층위로 갈림: PostRef 프리미티브는 디스패치 코어라 ROADMAP M8에서 PreRef와 같이 구현되고, 훅 슈가 셋만 형제 백로그 (quad-mock/quad-debug/Operator/Fallback)와 동급으로 맨 뒤.

5. 대표 유스케이스 (사용자 제시)

ChildAdded 같은 이벤트에서 나중에 들어오는 것만 처리하고 싶을 때, PostRef 콜백이 mounted = true 플래그를 세우고 핸들러가 그걸 먼저 보는 패턴. 초기 construction 중 발생한 이벤트와 그 이후 동적으로 들어온 것을 사용자 코드가 스스로 구분할 수 있게 해줌 — PreRef만으론 표현이 안 되던 자리.

반영한 파일

• base/ref-plan.md — 제목 Ref / PreRef / PostRef, 승격/역전 배너, "PostRef" 절 신설(타이밍 대조표/보장 범위/메커니즘/Handler/가드/ 유스케이스), PreRef 순서 bullet 역전, pre-pass 서술에 postRefList 반영.
• base/lifecycle-hooks-plan.md — research/에서 git mv, 상태를 base 확정으로, OnRendered 절 신설, ② 절을 "보류"에서 "채택 확정"으로 (역전 배너 + 근거 보존), 스코프/선택지/이름/패키지/우선순위/열린 질문 절 전면 갱신.
• base/dispatch-core-plan.md — Dispatch.drive 정의에 pre-pass/후행 postRefList 소비 명시, None 센티널 절과 Length/Offset 절에 ProcessedPostRef 대칭 반영.
• base/brand-plan.md — PostRefTag/isPostRef 추가, isRef 포함 관계를 셋으로 확장, Leaf 핸들러 predicate 갱신.
• base/architecture.md — 소스 트리에 PostRef.luau/LifecycleHooks.luau, Leaf.luau 주석, 생성자/유틸 목록.
• base/slot-plan.md/base/modifier-plan.md — 핸들러 계층 값 금지 목록에 PostRef 추가(4곳+4곳).
• base/typing-limits.md — PostRef<T>도 PreRef<T>와 같은 서브타입 관계, 스파이크 13 재작성 시 같이 커버할 것.
• archive/preref-order-guaranteed-reversed.md — 신설.
• .claude/README.md — lifecycle-hooks 행을 research→base 표로 이동·전면 갱신, ref-plan.md/brand-plan.md 행 갱신, archive 새 행.
• ROADMAP.md — M8 체크리스트에 PostRef.luau/postRefList 소비/ ProcessedPostRefHandler/동적 경로 가드 추가, pre-pass 항목의 순서 보장 문구 역전 반영, Brand/Leaf 항목 갱신, 백로그에 훅 슈가 셋 추가.
• question.md — 용어 대기열에 OnDestroyed 항목, Brand 항목의 "10종" 표현 정리.
• CLAUDE.md — 백로그 항목 갱신 + 이 세션 요약.

python3 .claude/tools/doc-check.py ERROR 0 유지 확인.

Claude가 걸린다고 보고한 것

1. OnRendered가 "부모에 붙기 전"에 불린다는 캐비엇 — 위 2번. 이름이 React 관용어라 오해를 부를 수 있어 문서화로 대응하기로 함 (사용자가 채택을 지시했으므로 이름 자체는 유지).
2. 순서 미보장은 계약 변경이지 구현 변경이 아님 — 실제로는 여전히 index 순서로 fire될 것이므로, 사용자 코드가 우연히 그 순서에 기대도 당장은 안 깨짐(그래서 문서에 명시적으로 "의존 금지"로 적어둠).