quad/.claude

.claude/ — quad-v2 계획/설계 문서 색인

이 레포 전체가 quad-v2(재작성) 프로젝트이므로, webmanager류 서브프로젝트 구분 없이 .claude/ 바로 아래에 전부 있음. 루트 CLAUDE.md가 현재 상태+TODO 색인의 최종 소스 — 먼저 그걸 보고, 특정 결정의 자세한 근거/논의가 필요할 때만 아래 개별 문서를 열어볼 것.

폴더 기준

폴더	기준
base/	결정 완료 + 프로젝트 전체에 걸치는 컨텍스트 — plan/done 개념 없음, 계속 참조되는 배경지식. 항상 읽어야 하는 배경지식만 여기 둠(다른 문서를 이해하는 데 전제되는 것)
reference/	[2026-08-07 신설] 결정 자체가 아니라 다른 문서가 근거로 인용하는 온디맨드 참고 자료(v1 스냅샷, 프레임워크 비교 리서치) — "완료" 개념 없는 건 base/와 같지만, 항상 읽을 필요는 없고 해당 문서가 인용될 때만 열어보면 됨. quadnomicon 소재 후보가 많음
research/	아직 착수 전, 사용자와 스코프/설계를 더 상의해야 함
qa-request/	구현 완료(코드/에이전트 검증까지 끝남) + 사용자 본인의 실기기(Roblox Studio) QA만 남음 — 지금은 구현 자체가 시작 전이라 비어있음
archive/	완료 + 사용자가 실사용/실기기로 직접 검증까지 마침 (구현 대상). [2026-08-06 확장] 완전히 뒤집힌 설계 결정을 원문+역전 이유+diff와 함께 보존하는 용도로도 사용(제목 [역전됨] — 한 번 확정했다가 뒤집힌 것) — 더 이상 능동적으로 참고 안 해도 되지만(토큰 낭비 방지 위해 base//research/에서 뺌) quadnomicon 소재로는 나중에 쓸 수 있음. [2026-08-07 확장] 후보였다가 채택 안 된 것(확정한 적 없이 검토 후 기각)도 같은 방식으로 보존, 제목은 구분을 위해 [기각됨] — [역전됨]과 의미가 다르므로 혼동하지 말 것. [2026-08-07 세 번째 확장] 설계 반전/기각과 별개로, 에이전트가 문서 작성 중 스스로 낸 개념 혼동을 정정한 이력은 [에이전트 실수] 태그로 agent-mistake.md 하나에 모음(CLAUDE.md 세션 로그 중복 방지)
feedback/	실사용 피드백을 정리한 긴 로그 — 지금은 비어있음(구현 시작 전)
luau-test/	[2026-08-09 신설] base/ 확정 사항 중 "추론만으로 확정하고 실제 Luau로 부딪혀본 적 없는 것"(M0 스파이크 대상)을 luau/luau-analyze/luau-lsp/Roblox Studio로 사용자가 직접 돌려볼 독립 실행 스크립트 모음. [2026-08-13 여섯 번째 세션, 첫 실측] luau/luau-analyze 바이너리가 생겨 처음으로 실제 실행 — 런타임 12개 전원 통과, 타입 쪽에서 :Compute(fn) lazy 핸들 계약이 Luau 추론과 충돌하는 게 드러남(question.md 0-Y). STATUS.md가 상태의 소스(pass / 사람 결정 필요 / 스파이크 깨짐 / 미실행 분류 — 사람이 먼저 볼 것만 위에), luau-test/README.md는 각 파일의 검증 의도·배경, 실행 결과 상세는 audit/luau-test-first-run-2026-08-13.md
audit/	[2026-08-13 신설] luau-test/ 등 스파이크를 실제로 돌려본 뒤 "무엇이 확인됐고 무엇이 아직 안 됐는지"를 기록하는 곳 — 스크립트/계획 자체가 아니라 실측 결과만 다룸. base/luau-test와 달리 부분 확인(일부만 통과)도 있는 그대로 기록, 완전히 해소되면 관련 base//luau-test/README.md 캐비엇을 지우고 이 문서는 근거로 남김. 현재 2개: luau-test-first-run-2026-08-13.md(첫 실측 라운드 전체 — 런타임 12개 통과, question.md 0-Y의 1차 근거), gcconn-trick-verification.md(사용자가 Studio에서 직접 돌린 gcconn 트릭 부분 확인 — 10의 A 섹션 앞부분만, A-1/A-2/B/C는 미확인)
tools/	[2026-08-13 아홉 번째 세션 신설] 코퍼스 기계 점검 — doc-check.py가 깨진 파일/절 참조, README 색인 누락, 날짜 없는 시한부 주장("아직 안 돌려봄" 등), 미반영 ⚠️ 배너를 한 번에 훑음. 중대 변경 후 커밋 전에 돌릴 것(python3 .claude/tools/doc-check.py) — 수동 감사에서 나온 발견의 대부분이 이 종류였고, 실제로 문서를 쪼개다 잘못 옮긴 참조를 이게 잡아냄. ERROR는 고치고 WARN은 판단 대상
session/	[2026-08-11 신설] 세션별 상세 로그 원문(시행착오·정정 전 서술 포함, quadnomicon 개발로그 소재용) — 루트 CLAUDE.md가 3196줄까지 불어나 성능 저하를 유발해서 분리함. 파일명 YYYY-MM-DD-NN-slug.md, CLAUDE.md의 "세션 히스토리" 절에서 각 항목이 여기로 링크. 항상 읽을 필요 없음 — 결정의 논의 과정이 궁금할 때만
initreq/	프로젝트 착수 시 클론해둔 참고 레포(quad v1, fusion, vide, rbvm, tbox, code-docker) + PA님 실 코드(artworks/, 4차 라운드 교차검증 근거) + 원본 요청(req.md, raw-userinput.md) + quad2-try(이전에 시도했다 폐기한 v2 재작성 시도 — 리서치 완료, 결론은 base/bind-system-plan.md) — 읽기 전용 리서치 소스, 여기 내용을 옮기지 말고 항상 원본 그대로 유지

research/의 문서가 설계 확정되면 base/로 승격(또는 구현 착수 시 qa-request/행). 지금은 구현 라운드 전(설계 단계)이라 전부 base//research/에만 있음.

base/ — 결정된 것, 프로젝트 전체 컨텍스트

문서	내용
architecture.md	quad-v2 전체 아키텍처 확정 사항 요약(제일 먼저 볼 문서). [2026-08-12 세션 신설, 같은 날 후속 세션에서 강화] "코드 스타일 — Luau 문법 관례" 절 신설 — if-then-else가 공식 Luau 문법임을 명문화(환각/오타로 오인해 and/or로 되돌리는 회귀 방지), A and B or C 삼항 관용구는 항상-truthy 예외도 없이 전면 금지로 강화(bind-system-plan.md의 retractUnder falsy-값 버그가 실사례). const 바인딩은 공식 문법이나 툴링 미성숙으로 지금은 채택 보류
lifecycle-pattern.md	rbvm의 Connected+GC 관용구를 quad-v2가 채택하는 방식
store-semantics.md	Store는 부작용 허용이 기본. State는 Store 위의 조합 가능한 캐시 레이어로 실제로 필요함(2026-08-04 정정) — 온톨로지 핵심 메커니즘은 2026-08-04 2차 라운드에서 확정, 최신 상세는 base/bind-system-plan.md
bind-system-plan.md	pluggable key/value 핸들러 레지스트리 — process/retract 디스패치 모델, Ref, Store/State/Source 온톨로지 + 인체공학 질문 전부 확정. 디스패치 엔진은 quad-base가 인터페이스로 소유(2026-08-04 5차 라운드). [2026-08-11 세션, 여섯 번째] Dispatch.setLength/setOffsetSource의 owner 키가 물리 Instance로 한정될 필요 없음을 명시(Slot-in-Slot 재귀의 근거) — 같은 절 recompute의 off-by-one 버그 발견·수정(offset이 자기 자신을 포함해 누적되던 것), 재진입 방지 가드는 검토 후 기각(Source⊇State 단방향 원칙과 같은 카테고리의 UB로 명명, 각 Slot이 독립 bk를 가져 nesting만으로는 재진입 경로 자체가 없음을 확인). [2026-08-12 열한 번째 세션, 전면 정정] "핸들러 타입이 안 바뀌면 retract 없이 process가 diff"는 틀렸음 — retract는 store 재발행마다(핸들러 타입 무관) 항상 불림, v는 대체 값 자체일 수 있어 nil로 가정 금지. Tag/Ref/Slot/Attribute 전부 이 오류로 설계돼 있었음이 드러나 한 세션에 전부 정정(archive/retract-always-fires-reversed.md). [2026-08-12 세션 후속] retractUnder의 A and B or C 삼항 관용구 버그(v가 false일 때 nil로 새던 것)를 if-then-else로 수정한 게 계기가 되어 and/or 삼항 전면 금지 규칙으로 발전(architecture.md "코드 스타일" 절). [2026-08-12 열일곱 번째 세션] 우선순위 동률/매치 실패 처리(HANDLER_PRIORITY_* 상수+디버그 동률 감지, 매치실패는 즉시 error) 확정, store.key 레코드 필드 타이핑이 Luau type function으로 가능함을 스케치로 확인(pre-implementation-audit.md 1-3/1-4/1-10 해소). [2026-08-12 스무 번째 세션] Ref 사용 관례 명문화 — React useRef급 스코프 감각(만든 컴포넌트 자신이 쓰거나 자식에게 넘기는 용도, 경계 밖 반출·전역 장기 보관은 비권장). [2026-08-12 스물한 번째 세션] :With가 Tag/Modifier의 : clone 체이닝과 겉보기엔 같은 문법이지만 실제로는 정반대(clone 아니라 매번 새 State 노드)라는 혼동 경고 추가, Compute가 -ed(Computed)가 아닌 이유 절 신설(quad 자기 관례상 Tag.Added/Modifier.Overridden이 이미 "-ed = clone 후 즉시 확정된 값"을 선점해 lazy한 State에 재사용하면 충돌). [2026-08-13 세션, 두 번째] State<State<T>>(store가 emit하는 값 자체가 또 State/Source)가 같은 (inst,k)에 같은 핸들러를 중복 push시켜 retractUnder의 첫-매치 cutoff가 안쪽 자신을 잘못 retract하는 실제 체인 파손 버그로 확인됨(손 트레이싱, luau-test/04가 no-op retract 스텁 때문에 이 증상을 못 잡던 사각지대였음도 같이 발견) — Dispatch.process에 중복 핸들러 즉시 error 가드 추가, "동일한 재귀적 디스패치로 처리 가능"이라던 낙관적 서술과 "Store가 Store를 저장 가능한가" 절도 정정. [2026-08-13 세션, 네 번째] 사각지대 손 트레이싱 라운드에서 isHandlable 필드를 선택적으로 허용(생략하면 스캔에 안 걸림)하고, 그런 "체크포인트" 핸들러를 명시적으로 체인에 꽂는 Dispatch.processAs/Dispatch.retractSelfAndUnder(target 자신 포함 철거) 신설 — attribute-plan.md의 그룹/직접쓰기 이름 소유권 충돌을 별도 레지스트리 없이 기존 재진입 가드로 흡수하는 데 씀. [2026-08-13 세션, 다섯 번째, 전면 재설계 — 위 processAs/retractSelfAndUnder 대체] chains를 핸들러 객체 identity가 아니라 재귀 깊이 인덱스로 추적하도록 재설계 — Dispatch.process(inst,k,v,index)가 핸들러 호출 전에 그 인덱스 점유 여부를 체크(핸들러 부작용 낭비 없음), process는 이제 retract 필드 대신 자기 retract 클로저((hintValue)->())를 반환. 같은 키 재귀는 index+1, 다른 키 위임은 항상 1부터 — 이걸로 State<State<T>>가 UB에서 정상 지원 대상으로 재정정됨(각 재귀 단계가 다른 슬롯을 쓰니 identity 충돌 자체가 없어짐), retractUnder/retractSelfAndUnder도 Dispatch.retractFrom(inst,k,index,v) 하나로 통합(자기 포함/미만은 호출자가 넘기는 인덱스로 표현)되며 체크포인트 패턴 자체가 불필요해짐(archive/checkpoint-handler-pattern-reversed.md). 계기: AttributeGroupHandler 소유권 버그를 체크포인트로 고치다, 그 근본 원인(identity 기반 추적)을 되짚은 사용자 지적. [2026-08-13 감사] 위 재설계 의사코드에서 실제 버그 셋 발견·수정 — (1) chains:SetStrong이 handler.process 뒤에 있어 최초 마운트에서 하위 위임 retractor가 통째로 유실되던 것(재귀가 자기 테이블을 만들었다 바깥이 덮어씀), (2) Ref retractor가 spurious 재발행에서도 relate를 지워 dedup이 무력화되던 것, (3) Dispatch.drive의 진입 인덱스(1) 미명시. 덧붙여 retractor 안에서는 같은 키에 대한 retractFrom도 process와 똑같이 금지(진행 중인 루프가 #list를 이미 캡처)임을 명문화
module-lifecycle-plan.md	프로바이더 패턴, bind/store 구현 책임 분리 — 확정
slot-plan.md	뮤터블 자식 배열, 엄격한 단일 마운트 소유권, 재마운트 시 throw, base/roblox 패키지 경계까지 확정. [2026-08-09 세 번째 세션] Add/Remove/Extract/Clear/Move/Swap CRUD(복잡도 표기 포함), isMounted 이중 추적 분리, 요소 타입 제약(nil/None/핸들러 계층 값 금지, Slot<T>() 제네릭), 키 기반 동적 컬렉션 재조정(Slot:List(data, updateFn, keyFn?))까지 전부 확정 통합, base/roblox 경계에 reposition 훅 추가. [2026-08-09 열한 번째 세션, 중간검토] CRUD 식별 기준을 element 레퍼런스에서 인덱스 기준으로 재정정(Remove(index)/Extract(index, newElement?)/Move(oldIndex, newIndex)), ExtractAll/Get/IndexOf 신설. [2026-08-11 세션] `updateFn(item, index: number, offset: Source, prev: T?, userdata: UD?): (T
modifier-plan.md	Modifier는 런타임 plug 아닌 정적 merge, immutable+clone 기반 체이닝 — 메커니즘 확정. [2026-08-07 다섯 번째 세션 추가] :Apply(factory) 팩토리 체이닝, Overridden(구 Merge→Override, 2026-08-08 세션에서 이름까지 확정) 값 결합+성능 기준, :Peek/isState 필드 읽기까지 전부 확정(Peek/isState는 이름만 용어 정리 라운드까지 잠정). [2026-08-12 열일곱 번째 세션] table.clone이 메타테이블을 참조로 공유한다는 핵심 전제(M7 "클래스별 코드 없이 제네릭 __index 하나로 충분" 설계의 근거)가 실제 Luau 동작으로 확인됨(pre-implementation-audit.md 1-11 해소). Property에 Attribute식 이름 소유권 레지스트리를 적용하는 안은 검토 후 기각(엔진이 정한 유한 프로퍼티 이름 집합은 전용 키를 못 만들어 소유권 판정 자체가 성립 안 함 — Property가 override 우선순위를 쓰는 이유)
purity-and-effects-plan.md	컴포넌트 "순수성"이 아니라 "이식성" 문제로 재정의 — 문서 경고 수준으로 확정
component-composition-plan.md	컴포넌트=플레인 함수, State/Source 읽기·쓰기 경계, Source가 State를 구조적으로 만족 — modifier/Ref 컴포넌트 경계 통과까지 전부 확정, 남은 건 API 이름뿐. [2026-08-07 정리] 폐기된 StoreSource 프록시 설계로의 역전 이력은 본문에서 빼고 archive/store-source-proxy-reversed.md 포인터로 압축
blocker-plan.md	[2026-08-07 신설] Blocker — 여러 Source를 한꺼번에 바꿔도 파생값 재계산이 한 번만 되게, State 마일스톤(M3)과 함께 개발. 메커니즘+이름 확정
effect-plan.md	[2026-08-07 신설, 여섯 번째 세션에 확정] Effect(fn, state?) — state 없으면 설치 1회+leaf 사망 시 확정 정리, 있으면 내부적으로 state:Observer(...)를 조합해 재실행+cleanup 체이닝(React useEffect 동형). Observer와의 관계 해소 완료
ui-shorthand-plan.md	[2026-08-07 research/에서 승격] UICorner/UIPadding/UIScale 인라인 편의 키 — 이름(v1 Corner/PaddingAll/Scale에서 Modifier 필드명과 안 겹치게 UI 프리픽스로 확정)·메커니즘(Handler)·패키지 배치(quad-roblox 코어)·store-bind 가능성까지 전부 확정. 이미지 라운드 트릭(RoundSize)은 드롭 — archive/ui-shorthand-roundsize-dropped.md 참고. v=nil이면 process 자신이 만든 자식 제거(retract 아님)
tag-plan.md	[2026-08-08 세 번째 세션 재설계, 2026-08-12 열한 번째 세션 메커니즘 정정] Tag(...) — array-part 값 객체, Modifier와 같은 immutable clone 체이닝(:Added/:Removed/:Contains/:Apply/Merged), CollectionService 글루만 quad-roblox. retract가 이전 Tag가 걸었던 이름을 이름별 참조 카운트 맵에서 빼고(다른 위치가 겹쳐 쓰면 실제 RemoveTag는 skip), process가 새 Tag의 이름을 등록 — 여러 위치가 같은 이름을 겹쳐 가져도(웹 className류 합집합) 안전. 구 해시 파트 boolean 모델은 archive/tag-hash-key-model-reversed.md, 구 assert(v==nil) 메커니즘은 archive/retract-always-fires-reversed.md. [2026-08-12 열다섯 번째 세션] Added/Removed가 vararg가 아니라 `string
attribute-plan.md	[2026-08-07 여덟 번째 세션 신설] 단일 키 [AttributeKey<T> "Name"](구 Attribute<T>) — SetAttribute(name, nil)이 네이티브 지우기라 None 센티널과 가장 깔끔하게 맞아떨어짐. [2026-08-11 아홉 번째 세션] 여러 Store를 한 번에 attribute로 묶는 그룹 Attribute(...) 프리미티브 신설(Tag와 동형 array-part 값 객체, Merged로 헤테로지니어스 Store 합성), 이름 충돌 방지로 단일 키를 AttributeKey로 리네임(잠정). [같은 세션 후속] AttributeKey(name)이 이름별 weak 캐시로 동등성 보장하도록 확정되며, 그룹 Handler는 자기 완결형 재구현 대신 메모이즈된 키로 기존 단일 키 경로에 재귀 위임하는 걸로 개정(중복 구현 제거). [2026-08-12 열 번째 세션] 그룹/직접 쓰기가 같은 이름을 동시에 관리하는 충돌을 막기 위해 그룹은 공개 캐시 대신 rawNew(name) 전용 키+소유권 Relate로 전환. [열한 번째 세션] retract가 store 재발행마다 항상 불린다는 정정에 맞춰 AttributeKeyHandler.retract를 손봄(이 시점엔 v==nil 가드 버전 — 아래 열여섯 번째 세션에서 최종 재정정됨), 그룹의 "남아있는 이름" 위임도 매번 retractUnder를 먼저 부르도록 정정(체인 누수 방지). [2026-08-12 열여섯 번째 세션, 최종 재정정] retract는 완전 no-op으로 굳어짐(SetAttribute는 오직 process(inst,k,nil)에서만) — Attribute는 명시적 None/nil로만 지워지고, 그룹 diff나 컴포넌트 언마운트로 이름이 조용히 사라져도 값은 자동으로 안 지워짐(Ref의 "Destroy 무관, 정리는 명시적으로" 철학과 통일), 단 사라진 이름의 구독은 끊어 자원 누수는 막음 — 위 "v==nil 가드" 버전은 이걸로 폐기. [2026-08-13 세션, 전면 재정정] rawNew+owners 수동 레지스트리 방식이 "그룹이 이름을 놓았다 다시 포함하면 자기 자신과 충돌"하는 실제 버그로 확인됨 — AttributeGroupKeyHandler라는 isHandlable 없는 순수 체크포인트 핸들러를 Dispatch.processAs로 명시 push하고 Dispatch.retractSelfAndUnder로 통째 철거하는 방식으로 전면 재설계, 소유권 충돌 감지도 별도 레지스트리 없이 기존 재진입 가드가 대신 잡아줌(bind-system-plan.md 참고). AttributeKeyHandler는 다시 완전 무상태로 단순화됨. [2026-08-13 세션, 다섯 번째, 전면 재설계 — 체크포인트조차 불필요해짐] Dispatch가 인덱스 기반으로 재설계되며 AttributeGroupKeyHandler/processAs/retractSelfAndUnder를 전부 걷어냄 — 그룹이 그냥 공개 AttributeKey(name)으로 항상 인덱스 1부터 Dispatch.process/retractFrom을 직접 부르면 끝(점유 체크 자체가 소유권 충돌 감지), groupState Relate도 필요 없어짐(반환 클로저가 이름 집합을 직접 캡처) — 중간 버전은 archive/checkpoint-handler-pattern-reversed.md. [2026-08-13 감사, 정정] 그런데 그 의사코드가 process 안에서 이름마다 retractFrom(...,1,...)을 먼저 부르고 있어 인덱스 1이 무조건 비워지는 바람에 점유 체크가 전혀 작동하지 않았음(그룹↔그룹 사이에서 조용한 last-write-wins가 그대로 남아 있었음) — process는 Dispatch.process만 부르고 철거는 반환 클로저가 자기가 등록한 이름 전부에 대해 하도록 정정. 그룹 Handler 시그니처가 계약과 안 맞던 것(process(inst,index,v) 3-인자)도 같이 수정
onchange-plan.md	[2026-08-10 세션 신설] OnChange(name) — GetPropertyChangedSignal 바인딩 전용 DI 키, Attribute와 달리 제네릭 타입 파라미터 없음(콜백 타입은 인라인 명시, 이벤트 바인딩과 같은 급 트레이드오프). 전부 quad-roblox(Handlers/OnChange.luau), State<function>은 기존 이벤트 store-bind 메커니즘 재사용. [2026-08-11 아홉 번째 세션 후속] AttributeKey와 동일한 이름별 weak 캐시로 OnChange(a) == OnChange(a) 동등성 보장
relate-plan.md	[2026-08-08 신설] Relate — inst를 weak 키로 하는 범용 릴레이션 프리미티브(SetWeak/GetWeak/SetStrong/GetStrong, 비싱글톤 생성자). 구 base.perInstanceState(inst) placeholder를 대체·정식 승격, lifecycle-pattern.md의 bindLifetime/canExecute가 그 위에 얹힘. [2026-08-12 열세/열네 번째 세션] 서로 다른 두 Relate가 서로의 키를 상대방 값으로 강하게 붙잡는 상호 순환 패턴 경고 신설 — Luau에 ephemeron 테이블이 없어(공식 확인, luau.org/compatibility) 이런 순환은 실제로 GC가 안 됨, Slot의 kSlotMap/slotOwner가 실제 사례이자 수정 사례
ref-plan.md	[2026-08-13 아홉 번째 세션, bind-system-plan.md에서 분리] Ref/PreRef — 지연 없는 확정 값 박스. 용도 재정의(leaf 노드를 담는 용도로도, leaf 노드에 바인딩하는 용도로도), .Value+:Set/:Callback/:Wait(전부 self 반환), Ref의 retract가 TagHandler와 같은 Relate diff 패턴이라는 것, 이중 바인딩 금지(canBound), PreRef 호이스팅 pre-pass와 1회용 _fired 가드. 분리는 순수 이동 — 결정은 하나도 안 바뀜
event-plan.md	[2026-08-13 아홉 번째 세션, bind-system-plan.md에서 분리 — 사용자가 직접 지목] 이벤트 바인딩 — 핸들러가 self(Instance)를 안 받는다는 확정(Ref가 이미 커버, 이중 쓰기 경로 방지), 이벤트도 store-bind 가능하며 false를 넣으면 disconnect. 이벤트 네이밍 관례는 인스턴스 생성과 한 절에 섞여 있어 bind-system-plan.md에 남음, GetPropertyChangedSignal은 onchange-plan.md. 분리는 순수 이동
brand-plan.md	[2026-08-13 아홉 번째 세션, bind-system-plan.md에서 분리] Brand — 런타임 nominal 타입 판별 통합 메커니즘(Brand.set/Brand.get), isState를 10종 branded 타입 전부로 일반화. 동작/구현은 확정, 이름 Brand 자체만 용어 정리 대기(question.md 1번). 분리는 순수 이동
tween-plan.md	[2026-08-12 세션, research/에서 승격] 값-레벨 Tween<T> 래퍼(PropertyHandler가 소비, 구 특수 bind key 모델은 archive/tween-special-bind-key-reversed.md). 3-상태 릴레이션 슬롯({Tween,Value}|true|nil), T'=T|Tween<T> 타입 치환. 옵션 값 모양은 Info: TweenInfo? 우선+편의 필드 폴백, override는 Tween.Cancel(기본)/Tween.Finish 2값. Animate(info)는 Tween opts를 T|State<T>로 받아 :Apply로 꽂는 sugar. 자연완료 시 per-instance 북키핑은 정리 안 해도 됨으로 확정(목표값 도달 상태라 부작용 없음, Completed 이벤트 구독 장치는 오버엔지니어링으로 판단). initValue는 사용자가 직접 처리(에이전트 범위 제외)

reference/ — 온디맨드 참고 자료 (2026-08-07 신설)

문서	내용
quad-v1-architecture.md	v1(initreq/quad) 내부 동작 스냅샷 — "이 문제를 안 반복하려면"의 기준선. [2026-08-07 base/→reference/ 이동] v2의 결정 자체가 아니라 다른 문서가 인용하는 온디맨드 자료라 항상 읽을 필요는 없음
comparison-fusion-vide.md	Fusion/Vide 아키텍처 비교 리서치 — 설계 결정 근거 자료(전파 모델 등 일부 서술은 이후 라운드에서 뒤집혔으니 bind-system-plan.md 쪽을 최신으로 볼 것). [2026-08-07 base/→reference/ 이동], quadnomicon 소재 후보
comparison-charm.md	[2026-08-09 신설] littensy/charm(Roblox Zustand류) 비교 — batch()/atom()/수동 dispose Effect 3가지는 quad가 이미 기각한 패턴이라 반면교사, None 센티널은 독립 재확인, charm-sync의 diff/patch는 quad 미착수 네트워크 복제 영역의 첫 참고자료, Blocker의 "previous 값 비교" 미결 문제엔 정황 증거(생성 시 필수 equals, computed의 previous-in-getter) 제공

research/ — 아직 착수 전, 상의 필요

문서	내용	우선순위
existing-instance-bind-plan.md	이미 생성된 인스턴스 재바인드 — 착수 안 하되 "미지원" 확정도 안 함, 열린 가능성 유지	하 — v2 초기 스코프 제외
debug-tooling-plan.md	실물 Instance→코드 위치 역추적 Studio 플러그인(quad-debug) — 채널 실현 가능성(BindableEvent/Function 크로스 컨텍스트)까지 실측 검증 완료, 세부 API 이름·구현만 남음	하 — 사용자가 "quad 개발 완료 전엔 착수 못 함"으로 직접 후순위 지정, base 설계 시 훅 확장 지점만 고려
documentation-plan.md	문서 사이트 구조(초심자/api/심화/quadnomicon 4축, 백엔드별 트랙 분리) + UI 네이밍 컨벤션·Store 부작용 패턴·권장 이벤트 핸들링 3개 세부 문서 뼈대	하 — 착수 시점 미정, 구조/스코프만 합의된 상태
documentation-content-map.md	위 4축에 실제로 뭘 채울지 base/ 전체를 초심자/api/심화/skip으로 서베이한 콘텐츠 맵 — 초심자 core loop 목차 초안 포함	하 — 문서화 착수 시점의 목차/우선순위표로 쓸 것
framework-comparison-findings.md	quad vs Fusion/Vide/react-lua 정직한 비교(실 소스 근거) — quad 강점, 못 고치는 트레이드오프(의도된 설계) 정리. [2026-08-12 열여덟 번째 세션] "고칠 만한 것" 절에 남아있던 마지막 두 항목(use-after-destroy 검증 안전망 부재, :With 동적 의존성 미지원)도 사용자가 "고칠 필요 없음"으로 최종 판단해 3번 절(못 고치는 트레이드오프)로 이전 — 2번 절은 이제 해소된 항목만 남음	하 — 배경 자료, 더 이상 사용자 판단 대기 상태 아님
additional-primitives-plan.md	[2026-08-09 세 번째 세션, 전부 해소] 마지막으로 남아있던 키 기반 동적 컬렉션 재조정도 Slot:List(...)로 확정되어 base/slot-plan.md로 승격 — 이 문서엔 새로 열린 설계 질문 없음, "빈 자리 아닌 것"/"문서화 백로그"/조사 소스 목록만 배경 자료로 유지	하 — 배경 리서치 기록용, 열린 결정 없음
pre-implementation-audit.md	M0 착수 직전 크리티컬 감사(2026-08-06 신설) — base/ 전체를 모호성/지연결정리스크/단순화후보 세 렌즈로 재검토, 11개 우선순위1 + 11개 우선순위2 + 2개 단순화후보. [2026-08-12 열일곱 번째 세션] 우선순위1 11개 전원 해소 — 남은 건 .claude/luau-test/ 스파이크 실측 확인뿐	상 — 설계는 전부 해소, .claude/luau-test/ 스파이크 실측만 남음
operator-sugar-plan.md	[2026-08-12 신설] Sum/Product/Not/비트연산 등 :Compute/:Apply용 연산자 콤비네이터 슈가 — 메커니즘은 이미 확정된 계약(Animate와 동형 패턴) 재사용이라 확정, 네임스페이스 이름만 미정. [2026-08-12 열아홉 번째 세션] 서브 에이전트 외부 리서치로 다른 리액티브 라이브러리 선례와 대조 — Operator가 가장 강한 선례(Python operator 모듈), Clamp/Min/Max가 추가 후보로 부상, 비트연산·비교연산자·Sub/Div는 선례 전무로 드랍 후보, Debounce/Throttle은 Blocker와 다른 시간 기반 메커니즘이라 별도 질문으로 분리, Filtered의 Slot 안/밖 구분 판단이 ReactiveUI/SolidJS 선례로 뒷받침됨 — 최종 이름 결정은 여전히 사용자 몫. [2026-08-13 세션, 두 번째] Haskell 비교 리서치 중 Alternative(nil 대체값, coalesce류) 후보 신설 — 카탈로그 확정 규칙에 그대로 맞음, 이전엔 없던 게 확인됨	하 — 구현은 맨 마지막(순수 슈가, 없어도 무방, 함수 간 의존 없음), 사용자가 직접 후순위 지정 [2026-08-13 여섯 번째 세션] `State<State
dispatch-redispatch-diff-plan.md	[2026-08-13 여섯 번째 세션 신설] 현행 hintValue가 "곧 디스패치될 raw 값"이라 None 센티널/State/Tween 래퍼가 그대로 넘어가 말단 핸들러의 isX(hint) 가드를 거짓으로 만들고 깜빡임/재생성 방지를 조용히 끄는 결함을 재현·확인(사용자 제기). 채택 모델: 래핑 핸들러의 retractFrom 선행 호출을 폐기하고 Dispatch.process 안에서 핸들러를 먼저 비교 — 같으면 그 자리 클로저에 새 값을 넘기고 자기 process 재호출, 다르면 그 자리부터 전량 철거. 이걸로 힌트 타입이 구조적으로 보장되고 깊은 체인의 힌트 유실도 사라짐(각 레벨이 자기 재프로세스에서 자기 힌트를 받으므로). oldValue 전달/HandlerChanged 마커는 둘 다 불필요로 판명 (클로저가 이미 old를 캡처, chains에 더할 건 비교용 handler 하나). 남은 열린 항목은 Attribute 이름 소유권 하나 — question.md 0-Z
v1-compat-plan.md	v1 하위호환(compat) 레이어 — quad-roblox-v1-compat 패키지, v2→v1 단방향 브리지(state:Observer()+v1 프로퍼티 재대입), v2-in-v1/v1-in-v2 두 임베딩 방향의 기술 규칙까지 확정. quad2-try의 quad-compat은 빈 폴더로 실제 시도된 적 없었음을 확인	하 — Slot이 foreign Instance를 어떻게 다루는지만 Slot 코어 구현 시점까지 미결

archive/ — 완료됐거나 완전히 뒤집힌 것, 능동 참고 불필요

문서	내용
store-source-proxy-reversed.md	[역전됨] 2026-08-04에 확정했던 StoreSource 프록시 설계(Store가 Source를 감춘 별도 프록시로 감쌈) — 2026-08-06 세 번째 세션에서 "Source가 State를 구조적으로 만족" 재구성으로 완전히 대체됨. 원문·역전 이유·신구 비교표 보존, quadnomicon 소재 후보
ref-phase-option-reversed.md	[역전됨] CreatedRef의 phase 옵션 — 위치 기반 순서 + PreRef 신설로 대체됨
ui-shorthand-roundsize-dropped.md	[기각됨, 2026-08-07 신설] v1 RoundSize(이미지 9-slice 라운드 트릭) — 네이티브 UICorner로 대체되어 포팅 불필요. 이 판단이 한 차례 "Corner/PaddingAll/Scale 숏핸드 전체가 불필요하다"로 과잉일반화됐다가 정정된 이력 포함
batch-rejected.md	[기각됨, 2026-08-07 신설] lexical Batch(fn) — 코루틴 yield 위에서 구조적으로 위험해 기각, 값 기반 Blocker(base/blocker-plan.md)로 대체
context-rejected.md	[기각됨, 2026-08-07 신설] Context(트리 하위 암묵 전파) + 대안이던 레이어드 Store 둘 다 기각 — 명시적 타입 강제 Store 전달로 충분하다는 판단
modifier-apply-mutable-rejected.md	[기각됨, 2026-08-08 신설] Modifier.Apply/setter를 mutable로 바꾸는 방안(및 "Apply 경계에서만 clone" 절충안) — 둘 다 형제 서브트리 오염 방지가 clone 비용 절감보다 우선이라 기각
tag-hash-key-model-reversed.md	[역전됨] 구 Tag 모델(해시 파트 boolean 키, 태그 개수만큼 키 갱신) — 2026-08-08 세 번째 세션에서 array-part 값 객체(Tag(...), :Added/:Removed/:Contains/:Apply/Merged) 모델로 완전히 대체됨
agent-mistake.md	[에이전트 실수, 2026-08-07 신설] 설계 반전이 아니라 에이전트가 문서 작성 중 개념을 혼동했다가 같은 세션 안에서 스스로 정정한 사례 모음(canExecute/isHandlable 혼동, isSource 불필요 오판) — CLAUDE.md 세션 로그의 중복 서술을 여기로 옮기고 포인터만 남김
quad2-try-research-findings-rejected.md	[기각됨, 2026-08-09 코퍼스 정리 신설] quad2-try 이전 시도 리서치 전문(OOP 상속/커스텀 파서/Slot 스텁/Pipe copy-on-write 4가지 죽은 접근 + :With 이름 방증) — base/bind-system-plan.md에 남아있던 인라인 전체 서술을 이전, 결론 한 줄 포인터만 본문에 남김
observer-cleanup-contract-rejected.md	[기각됨, 2026-08-09 코퍼스 정리 신설] Observer 자체에 React useEffect식 cleanup 반환 계약을 추가하는 안 — 클로저로 이미 충분해 기각, Effect가 opt-in 상위 계층으로 이 패턴을 제공
keyed-collection-state-method-rejected.md	[기각됨, 2026-08-09 코퍼스 정리 신설] 키 기반 동적 컬렉션 재조정 프리미티브를 state:Keyed(...) State 메소드로 두려던 초안 — Source 미사용 컴포넌트가 접근 못 한다는 반례로 철회, 현재는 자유 함수로 확정
debug-channel-replicatedstorage-rejected.md	[기각됨, 2026-08-09 코퍼스 정리 신설] quad-debug 채널을 ReplicatedStorage에 자동 생성하던 초안 — 게임 트리 오염 부작용으로 기각, quad 모듈 자신의 트리+CollectionService 태그로 대체
tween-special-bind-key-reversed.md	[역전됨, 2026-08-10 신설] 구 Tween 모델([Tween(key,tweenData...)] = storeValue 특수 bind key, 우선순위 최상위 Dispatch 핸들러) — 값-레벨 Tween<T> 래퍼 모델로 완전히 대체됨(base/tween-plan.md)
onchange-per-property-codegen-rejected.md	[기각됨, 2026-08-10 신설] OnChange.PropertyName 프로퍼티별 정적 코드 생성 — Attribute의 정적 지름길과 달리 (클래스 수 × 프로퍼티 수) 규모로 폭발해 기각, OnChange(name) 단일 팩토리로 대체
retract-always-fires-reversed.md	[역전됨, 2026-08-12 열한 번째 세션 신설] "핸들러 타입이 안 바뀌면 retract 없이 process가 diff" — 실제로는 retract가 store 재발행마다 항상 불림(핸들러 타입 무관). Tag/Ref/Slot/Attribute 전부 이 오류 위에서 설계돼 있었음이 드러나 한 세션에 전부 정정
slot-discard-no-portal-reversed.md	[역전됨, 2026-08-13 일곱 번째 세션 신설] Slot의 "retract = 폐기, 옮기지 않음"(2026-08-04 확정) + "portal은 오버엔지니어링이라 안 함" — 여섯 번째 세션에 State<Slot> 교체가 파괴에서 언마운트로 뒤집히며 portal이 별도 기능이 아니라 그 귀결이 됨(state<Frame>와 동일한 시맨틱). base/slot-plan.md에 히스토리로 남아 있던 세 덩어리(확정 문단 + State<Slot?> 왕복 분석 + 포탈 검토와 숙제 셋)를 원문 그대로 이전, 숙제 셋이 각각 어떻게 결말났는지도 정리
question-resolved.md	[해소 아카이브, 2026-08-13 아홉 번째 세션 신설] question.md에서 걷어낸 결정 완료 항목 전부(당시 32개 [해소됨] 마커) — 추가 프리미티브 필요성 라운드, 구현 착수 직전 감사 요약, 확정된 용어들(State/Relate/List/canBound/Ref/PreRef/Peek/isState/None/Handler), 포탈·State<Slot?> 왕복 해소 등. 분리 직전 전문을 그대로 보존. question.md는 이제 사용자가 답해야 할 것만 담음 — 항목이 해소되면 여기로 옮길 것
checkpoint-handler-pattern-reversed.md	[역전됨, 2026-08-13 다섯 번째 세션 신설] AttributeGroupHandler의 이름 소유권 충돌을 고치려고 만든 Dispatch.processAs/Dispatch.retractSelfAndUnder 체크포인트 핸들러 패턴(같은 날 네 번째 세션 신설) — chains를 핸들러 identity가 아니라 재귀 깊이 인덱스로 추적하는 더 근본적인 재설계로 대체되며 같은 날 바로 불필요해짐. State<State<T>>도 이 재설계로 UB에서 정상 지원 대상으로 바뀜

참고

• 저장소 소유자가 답해야 할 질문 전체 취합: .claude/question.md
• 사람만 할 수 있는 일(로컬 조작/결정): 루트 HUMAN_TODO.md
• 원본 브레인스토밍(raw chain-of-thought): .claude/initreq/raw-userinput.md, .claude/initreq/req.md — 위 문서들로 나누기 전의 원본, 참고용 백업이니 그대로 둘 것