quad/.claude/base/typing-limits.md

타입 시스템의 한계와 그 대응 — 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<U>(...) -> State<U> 모양인 건 본질이고, Luau가 지금 그걸 못 다룬다고 해서 반환 타입을 any로 열거나, API를 다른 모양으로 재설계하거나, 제네릭을 포기하고 타입별 코드를 생성하는 건 전부 하지 않습니다.
• 이유는 "게을러서"가 아니라 "그게 더 비싸서"입니다. 지금 비틀어 놓으면 (a) 비튼 만큼 복잡도와 사용자 인체공학 손해가 영구히 남고, (b) Luau가 고쳐졌을 때 자동으로 수혜를 받는 게 아니라 비튼 걸 되돌리는 별도 마이그레이션이 필요해집니다. 아래 1번의 실측이 이걸 구체적으로 보여줍니다 — 지금 그대로 두면 Luau 쪽 수정만으로 코드 변경 없이 풀립니다.
• 대신 반드시 하는 것: (1) 한계를 이 문서에 명시, (2) 사용자 코드가 취해야 하는 관례를 명시, (3) 추적 링크(RFC/이슈)를 남겨 나중에 되돌릴 지점을 알 수 있게 함.

예외: 그 한계를 우회하는 방법이 비트는 게 아니라 그냥 더 나은 설계인 경우엔 당연히 채택합니다(아래 1번의 "쪼개기"가 실제로 그런 사례 — 코드 생성 없이 타입 선언 두 개로 끝나고, 나중에 Luau가 고쳐져도 손해가 없음).

---

1. ⭐ 재귀 제네릭이 다른 타입 인자로 자기를 반환하면 타입 안전성이 조용히 사라짐

실측 근거: audit/type-recursion-issue/(REPORT.md + 재현 스파이크 44개). 이게 이 문서에서 가장 크고, 가장 넓게 영향을 주는 항목입니다.

무엇이 안 되는가

Compute<U>(self: State<T>, fn) -> State<U>처럼 자기 자신과 같은 이름의 재귀 타입을, 자기 타입 파라미터(T)와 다른 인자(U)로 다시 감싸서 반환하면, 반환 타입이 실제로는 해소되지 않고 Luau 내부의 Unifiable<Error>로 조용히 샙니다.

"조용히"가 핵심입니다 — 컴파일 에러가 나서 막히는 게 아니라, 진단 0건으로 통과한 뒤 그 결과에 대한 타입 체크만 사라집니다:

local s = n:Compute(function(x) return tostring(x:Get()) end) -- s는 State<string>이어야 함
local wrong: number = s:Get()   -- ❌이어야 하는데 에러 안 남

luau-analyze / luau-analyze --annotate / luau-lsp(새 솔버) 세 경로 전부 동일 — 도구 문제가 아니라 Luau 자체의 현 한계입니다.

정확한 경계 (오해 방지 — 이것들은 멀쩡함)

실측으로 좁힌 결과 "제네릭을 감싸서 반환하는 것" 자체는 문제가 아닙니다. 아래는 전부 정상 작동합니다:

패턴	상태
같은 인자로만 재귀(-> State<T>, U 없음)	✅ 정상
재귀 아닌 컨테이너에 담아 반환(-> Box<U>)	✅ 정상
감싸지 않고 그대로 반환(-> U)	✅ 정상
콜백 파라미터의 타입 추론	✅ 정상(아래 "쪼개기" 적용 시)
콜백 안의 로직(원본 값을 어떻게 다루는지)	✅ 정상
명시 주석 이후 다운스트림 전체	✅ 정상
자기 이름을 다른 인자로 감싸 반환(State<T> → State<U>)	❌ 이것만

즉 구멍은 정확히 "그 한 줄이 진짜 그 타입을 만드는가" 하나로 좁혀집니다.

그래서 우리가 하는 것 — ① 명시적 타입 바인딩 강제

파생 State를 만드는 자리마다 결과 타입을 : 주석으로 명시합니다.

-- ✅ 이렇게
local label: State<string> = 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)을 빼면 됩니다:

export type StateData<T> = {
	Get: (self: StateData<T>) -> T,   -- 자기 자신만 재참조(Compute를 모름)
}
export type State<T> = StateData<T> & {
	Compute: <U>(self: StateData<T>, fn: (self: StateData<T>) -> U) -> State<U>,
	-- self / 콜백 파라미터 둘 다 StateData<T>를 가리킴
}

• 이러면 state:Compute(function(s) return s:Get() * 2 end)가 무주석으로 통과하고, s에 대한 타입 체크도 진짜로 살아있습니다 (없는 필드 접근하면 정상적으로 에러남).
• 코드 생성이 필요 없습니다. State<T>는 여전히 진짜 제네릭이고, 손으로 쓰는 타입 선언이 하나 늘 뿐입니다. (한때 검토했던 "T별로 구워서 인라이닝"은 채택 안 함 — 0번 대전제 위반이고, 제네릭을 없애버려서 나중에 Luau가 고쳐져도 수혜를 못 받음.)
• 캐비엇: 콜백이 받는 s는 StateData<T>라 Compute/With가 없습니다. 콜백 안에서 다시 s:Compute(...)를 부르는 자리 (:Apply의 factory가 대표적)는 이 방식으로 못 풀고 function(self: State<T>)처럼 파라미터 주석이 필요합니다 — 다만 :Apply는 이미 "이름 붙인 재사용 팩토리"를 권장하는 자리라 (tween-plan.md의 Animate, research/operator-sugar-plan.md의 Sum류) 그런 팩토리는 최상위 함수 선언이라 자연히 주석을 답니다.

영향 범위

API	파라미터 추론	반환 타입 안전성
state:Compute(fn)	쪼개기로 해결	❌ 명시 바인딩 필요
state:With(...)	쪼개기로 해결(이형 dep 포함)	❌ 명시 바인딩 필요
state:Apply(factory)	factory 파라미터 주석 필요	❌ 명시 바인딩 필요
Effect(fn, state)	해당 없음(자유 함수)	해당 없음(반환이 재귀 타입 아님)
state:Observer(fn)	해당 없음(로컬 제네릭 없음)	해당 없음(EffectHandle 반환)

Effect/Observer는 이 문제와 무관합니다 — 한때 0-Y가 "같은 lazy 핸들 계약을 공유하니 같이 걸린다"고 서술했으나 실측 결과 아니었음 (각각 자유 함수라서, 그리고 로컬 제네릭 반환이 없어서).

언제 풀리는가 — 지금 그대로 두면 자동으로 풀림

• Luau RFC: relax-recursive-type-restriction — 완화 근거로 "This pays for itself in the considerable gain in expressivity gained for users of the type system"을 명시. RFC가 직접 드는 "지금은 거부되는" 예시가 Promise<T>.andThen: <U>(self: Promise<T>, callback: (T) -> Promise<U>) -> Promise<U>로, 우리 Compute와 글자 그대로 같은 모양입니다.
• 완화 메커니즘은 순수 내부 변경("타입 별칭을 진짜 type function처럼 취급해 lazy expansion") — 사용자 문법 변경 없음. 즉 지금 우리가 쓰는 선언 그대로 두면, Luau 쪽이 고쳐지는 순간 코드 변경 없이 올바르게 풀립니다.
• 추적: luau-lang/luau#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<<T>> 제네릭 키의 값 타입 narrowing은 안 됨

근거: luau-test/done/12-type-attribute-generic-key-narrowing.luau

[AttributeKey<<T>> "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)은 미검증

근거: luau-test/rewrite-required/16-type-store-key-typefunction.luau

Store<T> → {[K]: Source<V>} 합성을 Luau type function으로 하는 설계는 설계 레벨로는 확정(pre-implementation-audit.md 1-10)이지만, 스파이크가 types.newfunction 시그니처 불일치로 깨져 실측 확인이 안 된 상태입니다.

우리가 하는 것: 스파이크 재작성 후 재시도(에이전트 몫, luau-test/STATUS.md 🟠). type function은 비교적 최근/진화 중인 기능이라 버전에 따라 API가 다를 수 있음.

---

6. 성립이 확인된 것 (안심해도 되는 것)

한계만 모아두면 "타입이 다 안 되는구나"로 오독되기 쉬워서 같이 적습니다. 아래는 실측으로 통과 확인된 것들이라 다시 의심하지 말 것:

• Source<T>가 State<T>를 구조적으로 만족(서브타입으로 그대로 넘길 수 있음) — luau-test/review-required/08. 단 단방향 의존을 유지해야 함(State<T>가 Source를 참조하면 안 됨 — 두 제네릭 별칭의 상호 재귀는 솔버가 취약한 패턴).
• PreRef<T>가 Ref<T> 자리에 대입 가능 — luau-test/13 A섹션.
• Modifier의 제네릭 __index + table.clone 체이닝 — luau-test/done/17.
• 콜백 파라미터/본문의 타입 체크(1번의 쪼개기 적용 시) — 진짜 살아있음.

---

7. 새 타입/API를 설계할 때 체크리스트

1. 자기 이름을 다른 타입 인자로 감싸 반환하는가?(Foo<T> 안에서 -> Foo<U>) → 1번 한계에 걸림. 설계를 바꾸지 말고(0번 대전제), 명시 바인딩 관례를 문서에 같이 적을 것.
2. 로컬 제네릭을 가진 메소드가 재귀 타입의 필드인가? → 1번의 "쪼개기"를 적용할 것(XxxData<T> / Xxx<T> 분리).
3. 제네릭 키로 값 타입을 좁히려 하는가? → 3번, 안 됨. 타입 패밀리를 쓸 것.
4. 서브타입 관계인 두 타입을 합성하려 하는가? → 2번, 메소드 반환 타입이 갈리면 깨짐.
5. 타입으로 오용을 막으려 하는가? → 4번 사례처럼 정상 사용례까지 막는 경우가 흔함. 막기 전에 정상 사용례를 반드시 같이 테스트할 것.
6. 위 어디에도 안 걸리는데 안 되는 것 같다 → luau-test/에 스파이크를 추가하고 실측할 것. 추론만으로 "된다/안 된다"를 확정하지 말 것 — 이 문서의 항목 중 여러 개가 "된다고 믿었다가 실측에서 뒤집힌" 것들입니다.

실측 방법 주의: luau-analyze가 진단 0건이어도 타입이 제대로 해소됐다는 뜻이 아닙니다(1번이 정확히 그 사례). luau-analyze --annotate로 추론된 실제 타입을 눈으로 확인하고, 가능하면 "일부러 틀린 타입에 대입해서 진짜 에러가 나는지" 음성 대조군을 같이 둘 것.

---

8. 미해결 / 추적 중

• 에디터(luau-lsp)의 솔버 설정 — luau-analyze CLI는 새 솔버가 기본값이지만 luau-lsp는 옛 솔버가 기본값(LuauSolverV2=false)이라 같은 코드에 다른 진단이 나옵니다. 새 솔버로 맞추려면 "luau-lsp.fflags.enableNewSolver": true. M0 실착수 때 실제 에디터 환경에서 확정할 것 — 옛 솔버는 1번 패턴을 아예 거부하므로 사실상 새 솔버 외에 선택지가 없어 보이지만, 실환경에서 확인 필요.
• 5번(store.key type function) — 스파이크 재작성 후 실측.
• luau-lang/luau#2380 — 닫히면 1번 관례 재검증.