# 타입 시스템의 한계와 그 대응 — quad 전역 규약 **이 문서는 "Luau 타입 시스템이 quad 설계에 대해 못 해주는 것"을 한 군데 모은 확정 문서입니다.** 각 한계마다 (a) 정확히 무엇이 안 되는가, (b) 그래서 우리가 코드/문서에서 뭘 해야 하는가, (c) 언제/어떻게 풀릴 전망인가를 적습니다. **왜 따로 모으는가**: 이 한계들은 여러 `base/` 문서에 흩어져 각자 캐비엇으로 붙어 있었고, 그러다 보니 (1) 새 API를 설계할 때 같은 벽에 매번 새로 부딪히고, (2) "이건 우리 설계 문제인가 Luau 문제인가"를 매번 다시 판정하고, (3) 나중에 Luau가 고쳐줬을 때 **어디를 되돌려야 하는지** 알 수 없었습니다. 2026-08-13 열세 번째 세션에 가장 큰 한 건 (아래 1번)이 확정되면서 같이 정리했습니다. --- ## 0. 대전제 — Luau의 한계를 우회하려고 타입/API를 비틀지 않는다 **[2026-08-13 확정, 사용자]** > "지금으로써 quad 프로젝트가 타입을 비틀어 해당 시도를 하는 건 전혀 > 적합하지 않고, 이것은 상위의 Luau의 현 한계다. RFC와 해당 이슈 > 해결의 수혜를 받게 될 때 해결될 이슈로써, 당장 우리가 할 수 있는 > 바 없다." 이 원칙이 아래 모든 항목에 우선합니다. 구체적으로: - **API의 자연스러운 모양을 타입 사정으로 바꾸지 않는다.** 리액티브 파생값 API가 `Compute(...) -> State` 모양인 건 본질이고, Luau가 지금 그걸 못 다룬다고 해서 반환 타입을 `any`로 열거나, API를 다른 모양으로 재설계하거나, 제네릭을 포기하고 타입별 코드를 생성하는 건 **전부 하지 않습니다.** - **이유는 "게을러서"가 아니라 "그게 더 비싸서"입니다.** 지금 비틀어 놓으면 (a) 비튼 만큼 복잡도와 사용자 인체공학 손해가 영구히 남고, (b) Luau가 고쳐졌을 때 자동으로 수혜를 받는 게 아니라 비튼 걸 되돌리는 별도 마이그레이션이 필요해집니다. 아래 1번의 실측이 이걸 구체적으로 보여줍니다 — **지금 그대로 두면 Luau 쪽 수정만으로 코드 변경 없이 풀립니다.** - **대신 반드시 하는 것**: (1) 한계를 이 문서에 명시, (2) 사용자 코드가 취해야 하는 관례를 명시, (3) 추적 링크(RFC/이슈)를 남겨 나중에 되돌릴 지점을 알 수 있게 함. **예외**: 그 한계를 우회하는 방법이 *비트는 게 아니라 그냥 더 나은 설계*인 경우엔 당연히 채택합니다(아래 1번의 "쪼개기"가 실제로 그런 사례 — 코드 생성 없이 타입 선언 두 개로 끝나고, 나중에 Luau가 고쳐져도 손해가 없음). --- ## 1. ⭐ 재귀 제네릭이 다른 타입 인자로 자기를 반환하면 타입 안전성이 조용히 사라짐 **실측 근거: `audit/type-recursion-issue/`**(REPORT.md + `spikes/`의 재현 스파이크 — 개수는 폴더가 소스). 이게 이 문서에서 가장 크고, 가장 넓게 영향을 주는 항목입니다. ### 무엇이 안 되는가 `Compute(self: State, fn) -> State`처럼 **자기 자신과 같은 이름의 재귀 타입을, 자기 타입 파라미터(`T`)와 다른 인자(`U`)로 다시 감싸서 반환**하면, 반환 타입이 실제로는 해소되지 않고 Luau 내부의 `Unifiable`로 **조용히** 샙니다. **"조용히"가 핵심입니다** — 컴파일 에러가 나서 막히는 게 아니라, 진단 0건으로 통과한 뒤 그 결과에 대한 타입 체크만 사라집니다: ```lua local s = n:Compute(function(x) return tostring(x:Get()) end) -- s는 State이어야 함 local wrong: number = s:Get() -- ❌이어야 하는데 에러 안 남 ``` `luau-analyze` / `luau-analyze --annotate` / `luau-lsp`(새 솔버) 세 경로 전부 동일 — 도구 문제가 아니라 Luau 자체의 현 한계입니다. ### 정확한 경계 (오해 방지 — 이것들은 멀쩡함) 실측으로 좁힌 결과 **"제네릭을 감싸서 반환하는 것" 자체는 문제가 아닙니다.** 아래는 전부 정상 작동합니다: | 패턴 | 상태 | |---|---| | 같은 인자로만 재귀(`-> State`, `U` 없음) | ✅ 정상 | | 재귀 아닌 컨테이너에 담아 반환(`-> Box`) | ✅ 정상 | | 감싸지 않고 그대로 반환(`-> U`) | ✅ 정상 | | 콜백 **파라미터**의 타입 추론 | ✅ 정상(아래 "쪼개기" 적용 시) | | 콜백 **안**의 로직(원본 값을 어떻게 다루는지) | ✅ 정상 | | 명시 주석 **이후** 다운스트림 전체 | ✅ 정상 | | **자기 이름을 다른 인자로 감싸 반환**(`State` → `State`) | ❌ **이것만** | 즉 구멍은 정확히 **"그 한 줄이 진짜 그 타입을 만드는가"** 하나로 좁혀집니다. ### 그래서 우리가 하는 것 — ① 명시적 타입 바인딩 강제 **파생 State를 만드는 자리마다 결과 타입을 `:` 주석으로 명시합니다.** ```lua -- ✅ 이렇게 local label: State = count:Compute(function(c) return tostring(c:Get()) end) -- ❌ 이렇게 두면 이후 코드 전체의 타입 체크가 사라짐 local label = count:Compute(function(c) return tostring(c:Get()) end) ``` 주석이 그 한 줄의 RHS를 검증해주진 않지만(그게 위의 구멍), **다운스트림에는 정확히 바인딩됩니다** — 실측으로 확인: 잘못된 사용(`local bad: number = label:Get()`)도, 없는 메소드 호출(`label:NoSuchMethod()`)도 정상적으로 에러가 납니다. 그래서 "한 줄만 못 믿고 나머지 코드베이스 전체는 안전"한 상태가 됩니다. 이건 **API 문서/예제/튜토리얼에도 그대로 반영해야 하는 관례**입니다 (사용자가 무주석으로 쓰면 조용히 타입 안전성을 잃으므로) — `research/documentation-plan.md`/`documentation-content-map.md`가 문서 작성에 들어갈 때 이 관례를 초심자 트랙에 넣을 것. ### 그래서 우리가 하는 것 — ② 타입 선언은 "데이터부/메소드부" 쪼개기 위 1번과 별개로, **콜백 파라미터가 무주석일 때 추론이 안 되는 문제**는 진짜로 풀립니다. 원인은 "로컬 제네릭 `U`를 가진 메소드가 자기를 재귀 참조하는 타입의 필드로 선언돼 있다"는 것이고, 그 필드가 참조하는 self 타입에서 자기 자신(`Compute`)을 빼면 됩니다: ```lua export type StateData = { Get: (self: StateData) -> T, -- 자기 자신만 재참조(Compute를 모름) } export type State = StateData & { Compute: (self: StateData, fn: (self: StateData) -> U) -> State, -- self / 콜백 파라미터 둘 다 StateData를 가리킴 } ``` - 이러면 `state:Compute(function(s) return s:Get() * 2 end)`가 **무주석으로 통과**하고, `s`에 대한 타입 체크도 진짜로 살아있습니다 (없는 필드 접근하면 정상적으로 에러남). - **코드 생성이 필요 없습니다.** `State`는 여전히 진짜 제네릭이고, 손으로 쓰는 타입 선언이 하나 늘 뿐입니다. (한때 검토했던 "T별로 구워서 인라이닝"은 채택 안 함 — 0번 대전제 위반이고, 제네릭을 없애버려서 나중에 Luau가 고쳐져도 수혜를 못 받음.) - **캐비엇**: 콜백이 받는 `s`는 `StateData`라 `Compute`/`With`가 없습니다. 콜백 안에서 다시 `s:Compute(...)`를 부르는 자리 (`:Apply`의 factory가 대표적)는 이 방식으로 못 풀고 `function(self: State)`처럼 파라미터 주석이 필요합니다 — 다만 `:Apply`는 이미 "이름 붙인 재사용 팩토리"를 권장하는 자리라 (`tween-plan.md`의 `Animate`, `research/operator-sugar-plan.md`의 `Sum`류) 그런 팩토리는 최상위 함수 선언이라 자연히 주석을 답니다. ### 그래서 우리가 하는 것 — ③ 선언 스타일: 인라인 대신 `typeof(named function)` **[2026-08-15 추가, 근거: `audit/type-recursive-issue-with-typeof/REPORT.md`]** ①②와 별개로 추가 검증된 **선언 스타일 규약**입니다 — ①의 "명시 바인딩 강제" 원칙을 대체하지 않고, 그 위에 얹히는 보강입니다. 재귀 메소드(`Compute` 등)를 타입 안에 **인라인 제네릭 시그니처로 직접 쓰지 않고**, 이름 붙은 top-level 함수로 선언한 뒤 `typeof(그함수)`로 필드 타입만 참조하면: ```lua -- ✅ 이렇게 (인라인 대신 이름 붙은 함수 + typeof) local function Compute(self: State, func: (State) -> U): State return nil :: any end type State = { Get: typeof(Get), Compute: typeof(Compute), } -- ❌ 이렇게 두면 반환 타입이 `Unifiable`로 샘(①이 다루는 원래 문제) type State = { Get: (self: State) -> T, Compute: (self: State, func: (State) -> U) -> State, } ``` **LHS 명시 주석 없이도 다운스트림이 정확히 타이핑됩니다** — 체이닝 깊이 50, 타입이 바뀌는 체이닝(number→boolean→string→number), 콜백 안에서 self를 다시 호출하는 중첩까지 전부 실측 확인(위 REPORT `2`~`3`절). 비용 없음(50단 체이닝 `luau-analyze` 0.02초 안팎, hover 타입 크기도 깊이와 무관하게 일정). **바뀌지 않는 것**: - **콜백 파라미터는 여전히 명시 주석 필요**(`function(a0: State)`) — ②의 "쪼개기"가 다루던 문제는 별개이고, `typeof`가 대신 풀어주지 않습니다. 무주석이면 자유 타입 변수(`a0: unknown`에 가까움). **[2026-08-15 추가 확인, `audit/type-recursive-issue-try-callback/`]** 사용자 요청으로 이 캐비엇을 뚫을 방법이 있는지 type function/메타테이블/ 오버로드/제네릭 디폴트 등 20개 formulation으로 재시도했으나 quad의 `state:Compute(fn)` 단일 호출 모양을 유지한 채로는 여전히 못 뚫음(REPORT TL;DR 참고). 부수적으로 원인 이해가 한 단계 더 정확해짐 — 이 실패는 "재귀 자기참조 특유의 문제"가 아니라 **"제네릭이 관여하는 함수 호출의 인자로 넘긴 함수 리터럴엔 Luau가 컨텍스트 타입을 전파하지 않는다"**는 더 일반적인 한계임(재귀가 전혀 없는 `Map(arr:{T}, fn:(T)->U)`류 콜백도 무주석이면 동일하게 샘). 재귀는 이 위에 얹혀 실패 양상을 "완전 무주석"에서 "구조적 duck-typing 오염"(정상 호출조차 타입에러)으로 악화시키는 부가 요인. `T`를 명시 중간 변수로 먼저 고정하거나 재사용 가능한 monomorphize 헬퍼 함수를 거치면 실제로 추론이 살아나는 것도 확인했지만(재귀형·quad 실제 계약·중첩 self 호출까지 검증), 둘 다 `state:Compute(fn)`(콜론 호출 = `state.Compute(state, fn)` 단일 호출)을 "먼저 특수화된 함수를 얻고 그걸 다시 호출하는" 2단계 체인으로 바꿔야만 작동해 0번 대전제로 채택 안 함. **[2026-08-15 후속 조사, 같은 폴더 REPORT 11번 절]** `/code-review` 지적으로 이중 꺾쇠 명시 인스턴스화(`state:Compute<>(fn)`, 코퍼스에 이미 `AttributeKey<>`류로 존재하는 문법)도 재검토 — **leaf(비-중첩) 호출에 한해 콜백 파라미터 무주석 추론이 실제로 성립하고 sound함을 확인**(②쪼개기 + `Get` 필드의 명시 `read` modifier + 매 호출 T·U 전부 명시가 함께 필요, 셋 중 하나라도 빠지면 스퓨리어스 진단이나 duck-typing 함정으로 되돌아감). 이 역시 **채택 안 함** — 매 호출마다 이미 self로부터 결정되는 `T`까지 중복 명시해야 하고 `U`(콜백을 쓰기도 전에 그 반환 타입)를 미리 선언해야 하는 부담이 지금의 "파라미터에 타입 하나만 주석" 관례보다 크고, `:Apply` 중첩 자기호출(§1②가 이미 캐비엇 건 자리)엔 여전히 안 통해 규칙이 하나로 안 줄고 오히려 둘로 늘어나며, 부분 인스턴스화(`<>`)는 이름이 아니라 선언 순서로 바인딩돼 이 재귀형에서 아예 내부 에러로 깨짐. 상세 근거·모든 formulation은 REPORT 11번 절. - **명시 LHS 오타입 그 줄 자체는 여전히 못 잡습니다**(`wrong: State = test:Compute(...)`처럼 대입 줄 자체에 틀린 타입을 달면 그 줄은 통과 — 다운스트림에서만 잡힘). ①이 이미 명시한 구멍과 정확히 같은 종류로, **이 규약이 그 구멍을 메워주지 않습니다** — "명시 바인딩 관례를 완화할 수 있다"는 뜻이 절대 아닙니다. - **옛 솔버는 ③의 `typeof(Compute)` 선언 자체를 거부합니다**(①이 이미 겪는 것과 같은 문제 — `--solver=old`에서 "Recursive type being used with different parameters"로 선언 시점에 막힘, 실측: `type-recursive-issue-with-typeof/spikes/ 19-oldsolver-crosscheck-rejects-typeof.luau`). ③을 관례로 채택해도 §8의 "M0 실착수 때 실제 에디터 환경(`luau-lsp`)에서 새 솔버 확정" 전제는 그대로 유효 — ③이 이 요구사항을 없애주지 않습니다. **시도했지만 채택 안 함 — `setmetatable<{...}, {__index: typeof(...)}>`**: 콜백 파라미터 자동 추론까지 노리고 `Modifier`의 `__index`+`table.clone` 체이닝(§6)과 같은 계열로 확장을 시도했으나, quad의 실제 계약(콜백이 self 핸들 자체를 받음)에서 **콜백 반환 타입이 self의 원래 T와 다르면 (= `Compute`가 존재하는 이유 그 자체) 올바른 대입에도 모순되는 진단 두 개가 동시에 남는 Luau 0.733 솔버 버그**를 만남 — `setmetatable` 없이 순수 `typeof`만 쓰면 같은 시나리오가 깨끗이 통과하므로, `typeof` 자체가 아니라 `setmetatable` 경로 특정 문제로 좁혀짐. 최소 재현 9줄: REPORT 5-3절. ### 영향 범위 | API | 선언 스타일 | 파라미터 추론 | 반환 타입 안전성(LHS 무주석 시) | |---|---|---|---| | `state:Compute(fn)` | 인라인 + 쪼개기 | 쪼개기로 자동 해결 | ❌ 명시 바인딩 필요 | | `state:Compute(fn)` | `typeof(named fn)`(③) | 콜백 파라미터 명시 주석 필요 | ✅ 무주석이어도 안전(다운스트림) | | `state:With(...)` | 인라인 + 쪼개기 | 쪼개기로 해결(이형 dep 포함) | ❌ 명시 바인딩 필요 | | `state:Apply(factory)` | 인라인 | factory 파라미터 주석 필요 | ❌ 명시 바인딩 필요 | | `Effect(fn, state)` | — | 해당 없음(자유 함수) | 해당 없음(반환이 재귀 타입 아님) | | `state:Observer(fn)` | — | 해당 없음(로컬 제네릭 없음) | 해당 없음(`EffectHandle` 반환) | `state:With(...)`/`state:Apply(factory)`도 원리상 ③으로 같은 이득을 받을 것으로 예상되나(둘 다 `Compute`와 같은 "재귀 자기 반환" 모양), **아직 개별 실측은 안 함** — 실제로 base pseudocode에 ③을 반영할 때 같이 확인할 것. **`Effect`/`Observer`는 이 문제와 무관합니다** — 한때 0-Y가 "같은 lazy 핸들 계약을 공유하니 같이 걸린다"고 서술했으나 실측 결과 아니었음 (각각 자유 함수라서, 그리고 로컬 제네릭 반환이 없어서). ### 언제 풀리는가 — 지금 그대로 두면 자동으로 풀림 - **Luau RFC**: [`relax-recursive-type-restriction`](https://rfcs.luau.org/relax-recursive-type-restriction.html) — 완화 근거로 "This pays for itself in the considerable gain in expressivity gained for users of the type system"을 명시. RFC가 직접 드는 "지금은 거부되는" 예시가 `Promise.andThen: (self: Promise, callback: (T) -> Promise) -> Promise`로, **우리 `Compute`와 글자 그대로 같은 모양**입니다. - **완화 메커니즘은 순수 내부 변경**("타입 별칭을 진짜 type function처럼 취급해 lazy expansion") — **사용자 문법 변경 없음.** 즉 지금 우리가 쓰는 선언 그대로 두면, Luau 쪽이 고쳐지는 순간 **코드 변경 없이** 올바르게 풀립니다. - **추적**: [`luau-lang/luau#2380`](https://github.com/luau-lang/luau/issues/2380) ("Allow recursive generic types to differ", 2026-08-13 기준 열려 있음). 이게 닫히면 이 절의 ①(명시 바인딩 강제)을 재검증하고, 불필요해지면 관례를 풀 것. - **참고 — 옛 솔버는 이 패턴을 선언 시점에 거부**했습니다(`--solver=old`). 새 솔버는 선언을 받아주지만 위처럼 조용히 새는 중간 상태입니다. 즉 RFC의 완화가 **선언 검사까지는 들어왔고 인스턴스화까지는 아직**인 것으로 보입니다. ### 미리 대비해 둘 것 — 없음 RFC가 순수 내부 변경이고 우리 선언이 이미 그 대상 모양이므로, "미래에 자연히 등록되도록 플레이스홀더를 심어두는" 종류의 작업은 **필요 없다는 게 실측 결론**입니다. 오히려 지금 뭔가 심어두는 게 0번 대전제 위반입니다. --- ## 2. `Modifier.Overridden`의 서브타입 합성은 정적 체크 포기 **근거: `luau-test/done/09-type-modifier-overridden-subtype.luau`** `FrameModifier`가 `GuiObjectModifier`의 서브타입이어야 자연스러운데, 필드 setter 메소드의 반환 타입이 각각 자기 자신이라 같은 이름 필드끼리 반환 타입이 갈려 구조적 서브타이핑이 깨집니다 — 실측으로 재현 확인. **우리가 하는 것**: `Modifier.Overridden`의 시그니처를 `(...: any): any`류로 느슨하게 열어 정적 체크를 포기(fallback이 정상 작동함도 같이 확인됨). 상세는 `base/modifier-plan.md` 9-2번 절. --- ## 3. `AttributeKey<>` 제네릭 키의 값 타입 narrowing은 안 됨 **근거: `luau-test/done/12-type-attribute-generic-key-narrowing.luau`** `[AttributeKey<> "name"] = value`에서 `T`가 이름별로 고정되지 않고 호출마다 독립 추론돼 narrowing이 전혀 강제되지 않음 — 실측으로 "안 됨" 확정. **우리가 하는 것**: `base/attribute-plan.md`가 이미 예비해둔 fallback을 채택 — 정적 체크가 필요하면 `BooleanAttribute` 같은 **타입 패밀리**가 유일하게 믿을 수 있는 경로. --- ## 4. `Source(default)`/`Ref(default)`의 nilable 캐비엇은 타입으로 못 막음 **근거: `luau-test/done/14-type-nilable-default-overload.luau`** `default` 생략이 `T`가 nilable일 때만 안전하다는 캐비엇을 함수 오버로드(교차 타입)로 막으려던 스케치는, 의도한 오용은 정확히 막지만 **정상 nilable 사용례까지 같이 막아** 채택 불가. **우리가 하는 것**: 타입으로 강제하지 않고 문서 경고(UB)로 유지 — `base/bind-system-plan.md`의 해당 절. 새 설계 결정이 필요한 항목은 아님(대안이 이미 존재). --- ## 5. `store.key` 레코드 필드 타이핑(`type function`) — ✅ 검증 완료 **[2026-08-15 확정, 근거: `luau-test/done/16-type-store-key-typefunction.luau`, `audit/type-recursive-issue-with-typeof/REPORT.md` 6-1절]** `Store` → `{[K]: Source}` 합성을 Luau `type function`으로 하는 설계(`pre-implementation-audit.md` 1-10)는 **설계와 실측 둘 다 확정**입니다. 원래 스파이크가 깨졌던 이유는 설계 문제가 아니라 **`types.newfunction`의 API 버전 드리프트**였습니다 — 시그니처가 `(parameters: {head: {type}?, tail: type?}, returns: {head: {type}?, tail: type?}?, generics: {type}?): type`로 parameters/returns 둘 다 **레코드**를 받는데, 원래 스파이크는 배열(`{ ty }`)을 그대로 넘기고 있었습니다. self 파라미터는 `types.newtable()`이 돌려주는 **뮤터블 핸들 자기 자신**을 그대로 참조하면 됩니다(나중에 `setproperty`로 채워도 핸들이라 소급 반영됨). 수정 후 `ProcessStoreType<{ty:string, count:number}>`가 정확히 `{ty: Source, count: Source}` 구조를 만족하고, 음성 대조군(틀린 타입 `Get`/`Set`, 존재하지 않는 메소드) 전부 정확히 에러납니다. 에러 메시지도 `t1 where t1 = { Get: (t1) -> string, ... }`처럼 `` 없이 한 단계로 표기돼 아래 1번의 `typeof` 간접참조보다 오히려 읽기 쉽습니다. **참고 — 1번(재귀 제네릭 반환 leak)과의 관계**: `type function`으로 `Compute: State`처럼 **자기 자신을 재귀 호출**하는 것(1번 문제 자체를 이 메커니즘으로 우회하는 것)은 별도로 시도해봤으나 막다른 길이었습니다 — 제네릭 인자가 아직 구체화되지 않은 채로 type function이 자기 자신을 호출하면 `stack overflow`로 즉시 크래시합니다(type function은 구체 타입에 대해서만 동작하는 실행 모델이라, RFC가 별칭에 주려는 "진짜 lazy expansion"과 다름 — `types` 라이브러리에 지연 적용을 표현하는 API 자체가 없음). 이 항목(레코드 필드 합성)과 1번은 **서로 다른 문제**이고, `type function`이 도와주는 건 이쪽뿐입니다. 상세는 `audit/type-recursive-issue-with-typeof/REPORT.md` 6-2절. --- ## 6. 성립이 확인된 것 (안심해도 되는 것) 한계만 모아두면 "타입이 다 안 되는구나"로 오독되기 쉬워서 같이 적습니다. 아래는 **실측으로 통과 확인**된 것들이라 다시 의심하지 말 것: - **`Source`가 `State`를 구조적으로 만족**(서브타입으로 그대로 넘길 수 있음) — `luau-test/done/08`. 단 **단방향 의존을 유지해야 함**(`State`가 `Source`를 참조하면 안 됨 — 두 제네릭 별칭의 상호 재귀는 솔버가 취약한 패턴). - **`PreRef`가 `Ref` 자리에 대입 가능** — `luau-test/13` A섹션. **[2026-08-14 아홉 번째 세션] `PostRef`도 완전히 같은 관계**(같은 `Ref` 런타임 재사용, 브랜드 태그만 다름 — `base/ref-plan.md`의 "`PostRef`" 절) — `13`은 지금 `rewrite-required/`라 재작성할 때 `PostRef`도 같이 커버할 것. - **Modifier의 제네릭 `__index` + `table.clone` 체이닝** — `luau-test/done/17`. - **콜백 파라미터/본문의 타입 체크**(1번의 쪼개기 적용 시) — 진짜 살아있음. --- ## 7. 새 타입/API를 설계할 때 체크리스트 1. **자기 이름을 다른 타입 인자로 감싸 반환하는가?**(`Foo` 안에서 `-> Foo`) → 1번 한계에 걸림. 설계를 바꾸지 말고(0번 대전제), 메소드를 인라인 대신 이름 붙은 함수 + `typeof`로 선언(1번 ③)하고, 그래도 명시 바인딩 관례는 그대로 문서에 같이 적을 것 — ③은 ①을 대체하지 않음. **⚠️ ③은 반환 타입 안전성(LHS 무주석 다운스트림)만 고쳐줍니다 — 콜백 파라미터 자동 추론이 같이 필요하면 이것만으론 부족하니 바로 아래 2번도 같이 볼 것.** 2. **로컬 제네릭을 가진 메소드가 재귀 타입의 필드인가?** → 콜백 파라미터 자동 추론이 필요하면 1번의 "쪼개기"(`XxxData` / `Xxx` 분리)를, 반환 타입 안전성이 우선이면 1번 ③(`typeof`)을 적용할 것 — 필요하면 병행 가능(개별 검증은 아직 안 됨, 위 "영향 범위" 표 참고). **`setmetatable<{...}, {__index: typeof(...)}>`로 확장해 두 이득을 한 번에 얻으려 하지 말 것** — quad의 self-핸들 콜백 계약에서 솔버 버그를 만남(1번 ③의 "시도했지만 채택 안 함" 참고). **콜백 파라미터 무주석 자동 추론 자체가 필요하면**(쪼개기로 해결 안 되는 자리, 예: `:Apply`의 factory) `audit/ type-recursive-issue-try-callback/`이 전방위로 재시도했지만 quad가 채택할 만한 방법은 못 찾음(REPORT 결론) — 지금은 명시 주석 관례를 유지할 것. 3. **제네릭 키로 값 타입을 좁히려 하는가?** → 3번, 안 됨. 타입 패밀리를 쓸 것. 4. **서브타입 관계인 두 타입을 합성하려 하는가?** → 2번, 메소드 반환 타입이 갈리면 깨짐. 5. **타입으로 오용을 막으려 하는가?** → 4번 사례처럼 정상 사용례까지 막는 경우가 흔함. 막기 전에 정상 사용례를 반드시 같이 테스트할 것. 6. **위 어디에도 안 걸리는데 안 되는 것 같다** → `luau-test/`에 스파이크를 추가하고 실측할 것. **추론만으로 "된다/안 된다"를 확정하지 말 것** — 이 문서의 항목 중 여러 개가 "된다고 믿었다가 실측에서 뒤집힌" 것들입니다. > **실측 방법 주의**: `luau-analyze`가 진단 0건이어도 타입이 제대로 > 해소됐다는 뜻이 아닙니다(1번이 정확히 그 사례). **`luau-analyze > --annotate`로 추론된 실제 타입을 눈으로 확인**하고, 가능하면 > "일부러 틀린 타입에 대입해서 진짜 에러가 나는지" 음성 대조군을 > 같이 둘 것. --- ## 8. 미해결 / 추적 중 - **[2026-08-19 설정 완료]** 에디터(`luau-lsp`)의 솔버 설정 — `luau-analyze` CLI는 새 솔버가 기본값이지만 `luau-lsp`는 **옛 솔버가 기본값** (`LuauSolverV2=false`)이라 같은 코드에 다른 진단이 남. `luau-lsp` 바이너리(1.69.0)를 직접 설치해 `luau-lsp analyze --flag:LuauSolverV2=true/false`로 실측 — 새 솔버가 필요하다는 결론 재확인, `quad/.vscode/settings.json`에 `"luau-lsp.fflags.enableNewSolver": true`를 반영·커밋 완료(`tbox`도 같은 설정 확인). 실제 VSCode 세션에서 이 설정이 반영되는지 육안 확인만 사람 몫으로 남음(`HUMAN_TODO.md` 6번). - **`luau-lang/luau#2380`** — 닫히면 1번 관례 재검증(③ 포함). - **`state:With(...)`/`state:Apply(factory)`에 1번 ③(`typeof`) 개별 실측** — `Compute`에서만 확인됐고, base pseudocode에 실제로 반영할 때 같이 확인할 것. - **`setmetatable`+`typeof(genericFn<>())` 조합의 모순 진단 버그**(1번 ③ "시도했지만 채택 안 함") — quad는 이 formulation을 안 쓰기로 해서 quad 쪽에서 더 팔 필요는 없지만, Luau 0.733의 실제 솔버 버그로 보이므로 이미 알려진 이슈인지 확인 후 업스트림 제보 검토(최소 재현 9줄, `audit/type-recursive-issue-with-typeof/spikes/ 08-metatable-BUG-contradictory-diagnostics.luau`).