quad/.claude/reference/epoch-brand-composition.md

# `Epoch` 인터페이스 + `EpochMap` 컴포지션, 그리고 `Brand` 인스턴스화 — 결정 근거 기록 (2026-08-21)

**상태**: **[2026-08-21] 전량 확정·승격 완료.** 이 문서는 이제 "왜 그렇게
정했나"의 근거 기록이고, **지금 유효한 설계는 `base/`가 소스**다 —
`base/state-epoch-plan.md`(`Epoch`/`EpochMap`/State의 두 맵),
`base/brand-plan.md`(인스턴스 브랜드), `base/source-state-plan.md`(`Source`가
`Epoch`를 구조적으로 만족 + `Observer` 클로저 시그니처),
`base/effect-plan.md`(`Effect`가 자기 `EpochMap`을 듦).
**[2026-08-21 `research/` → `reference/` 이동]** 확정된 뒤엔 "상의가 더 필요한
설계"가 아니라 "다른 문서가 근거로 인용하는 온디맨드 자료"이므로
(`slot-attach-decomposition.md`와 같은 처리).

**[2026-08-21] 열린 항목 없음** — 마지막까지 남았던 리비전 증가 방식도
같은 날 `bit32` 랩으로 확정됐다(§4의 4번).

**⚠️ [2026-08-22] 아래 본문의 `{Epoch}` 표기는 제안 당시 표기 그대로다** —
승격 후 실측에서 그게 Luau의 **배열**(`{[number]: Epoch}`)이라 실제 게이트
배치(`{[Epoch]: true}` 집합)와 안 맞는 게 드러나 **`EpochSet`으로
확정**됐다(`base/state-epoch-plan.md` §3). 마찬가지로 `Observer` 클로저의
`from`은 **옵셔널**이다(설치 발화엔 출처가 없다). 정본은 언제나 `base/`.

발단은 "다중 의존성 `Effect`에서 한 파동에 `fn`이 두 번 도는" 갭
(`base/effect-plan.md`의 다중 deps 절, 2026-08-21 대화에서 에이전트가 제기).

아래는 그 결론에 이른 제안·평가·회신을 그대로 보존한 것 — 원래 서술은
"승격 대기 중인 제안"이었다.

## 1. 제안 (사용자 원문 요지)

1. **에포크 부기를 State에서 떼어내 컴포지션 가능한 객체로.** 가칭
   `EpochMap()`, 표면은 `EpochMap:Update(Epoch|{Epoch}) -> boolean`이고
   그 boolean이 **"뒤로 전파가 필요한가"** 를 뜻한다. *"이건 invalid 랑은
   다른 구현이야."*
2. **`Observer`는 emit의 주체를 클로저 인자로 흘려준다**(값이 아니라 출처).
3. **`Effect`는 자기 `EpochMap`을 하나 갖고**, 각 dep의 observer 등록 함수
   안에서 그걸 `Update` 한다 → 한 파동에 여러 dep가 깨워도 **첫 번째만
   `true`** 라 `fn`이 한 번만 돈다.
4. **emit 페이로드에서 게이트를 뺀다.** `emit(from: Source|{Source})`이면
   충분하다 — *"하류가 Gate 노드를 받을 이유도 없거든."* 런타임 분기는
   `isSource`로.
5. **더 나아가 `Source`가 아니라 `Epoch`로 일반화**한다.
   `type Epoch = { Count: number }`이고 **그 자체로 키로 쓸 수 있는 unique
   테이블**. `emit(Epoch|{Epoch})`, `Update(Epoch|{Epoch})`.
   *"'소스를 전해주는것' 이라고 보기엔 너무 협소하고, 일반화된 형태가 아님."*
6. **그러려면 `Brand`가 다중 태깅을 허용해야 한다** — 나아가 `Brand` 자체를
   **인스턴스화 가능**하게: `Brand()`가 weak `[obj] = true|nil` 하나를 들고,
   `SomeBrand:register(obj)` / `SomeBrand:is(obj)`. *"본인이 거기 속하면,
   본인이 직접 해당 브랜드를 가져와 등록하면 … `isXXXX`에서 각각의 구현을
   넣을 필요가 없어짐. 따라서 외부 확장도 쉬워진다."*

## 2. 에이전트 평가 — 방향은 옳다

- **`EpochMap` 분리는 이미 코퍼스가 발견한 구분을 형식화한다.** 같은 날
  `state-epoch-plan.md`가 맵을 둘로 가른 이유가 정확히 "값 유효성"과 "전파
  dedup"이 **비대칭으로 움직인다**는 것이었다(승격 후 정본은
  `base/state-epoch-plan.md` §4의 "왜 둘인가 — 순회 때문이다" 문단).
  후자만 떼어내 재사용 가능한 객체로 만들면, **노드가 아닌 소비자(leaf)도
  같은 판정을 쓸 수 있다** — 지금 State에만 있어서 못 쓰던 것.
- **다중 dep `Effect` 갭이 이걸로 정확히 닫힌다.** `A → b`, `A → c`,
  `Effect(fn, b, c)`에서 `b`/`c`는 서로 다른 노드라 **접어줄 공통 하류가
  없어** 에포크 dedup이 못 도왔다. `Effect`가 자기 `EpochMap`을 들면
  그 지점이 곧 공통 하류가 된다. 대안으로 검토했던 "deps를 하나의 파생
  노드로 수렴시키기"보다 낫다 — 노드를 더 안 만들고, `effect-plan.md`가
  확정한 "의존성 N개면 내부 Observer도 N개" 구조를 안 건드린다.
- **게이트를 페이로드에서 빼는 것도 맞다.** 하류는 게이트 identity를 **한
  번도 안 쓴다**(에포크 경계로 만드는 안은 `base/state-epoch-plan.md` §8의
  "기각된 대안 — 게이트를 에포크 경계로" 항목에서 기각됨). 배치가 "그 전파에만 쓰는 일회성 스냅샷"이라는 성질도
  그대로 유지된다.
- **`Epoch`로의 일반화가 실제로 계약을 정확하게 만든다.** 맵이 `Source`에서
  요구하는 건 **identity + 단조 증가 카운터** 둘뿐이다. 그걸 이름 붙이면
  `state-epoch-plan.md`가 `루트 Source들의 에포크`라 부르던 것이 그냥 `Epoch`들이 되어
  서술도 짧아지고, Source가 아닌 원천(외부 시계 등)도 특수분기 없이 낀다.
- **`Brand` 인스턴스화 — 다중 태깅 필요는 지금 실재한다.** `Source`가
  `SourceBrand`이면서 동시에 `EpochBrand`여야 하는데, 현행
  `Brand.get(x) -> tag`는 **객체당 태그 하나**라 표현이 안 된다
  (`base/brand-plan.md`). 게다가 지금 서브타입은 손으로 쓴 OR 체인
  (`isState = isSource(x) or Brand.get(x) == StateTag`)인데, 자기 등록
  방식이면 `StateBrand:is(x)` **한 번**으로 끝나 조회 수도 준다.

## 3. 대가 — [2026-08-21] 둘 다 사용자 회신으로 해소됨

에이전트가 대가로 짚었던 둘은 **둘 다 실제 비용이 아니었다.**

- **`Brand.get(x)` 역조회 상실** — *"확실히 의미가 없어진것 같습니다 필요하진
  않아요."* 코퍼스가 실제로 쓰는 건 전부 `isX` 형태의 멤버십 질문이고, "이
  값이 대체 뭔가"를 되묻는 자리는 없다.
- **"포함 관계가 코드 모양에 드러난다"는 성질이 흩어진다** — **에이전트 착오,
  철회.** 사용자 지적: *"여전합니다. `PreRefBrand` 가 존재할테니. 거기에
  `is()` 를 해서, 코드에 전부 드러나는거 똑같습니다."* 자기 등록 방식이
  **여러 브랜드에 등록하기를 강제하는 게 아니므로**, 지금처럼 각 타입이
  자기 브랜드에만 등록하고 포함 관계는 predicate 합성으로 한 곳에 쓰면 된다:
  ```lua
  local function isRef(x)
      return PreRefBrand:is(x) or PostRefBrand:is(x) or RefBrand:is(x)
  end
  ```
  `base/brand-plan.md`가 2026-08-09에 세운 성질이 그대로 유지된다.

## 4. 결정 상태

1. **[해소] `Epoch`는 `Source`가 구조적으로 만족한다** — 사용자: *"전자를
   처음부터 생각했고"*. `Source`가 `State`를 구조적으로 만족하는 기존 패턴과
   같은 모양.
2. **[해소] 리비전 필드는 공개로 둔다** — *"`Source` 는 예약 이름이 늘어나도
   됩니다(store 아님) 그냥 공개 필드로 두는게 맞는게, 그래야 타입 상 `Source`
   가 `Epoch`를 만족해요."* **근거가 정확하다** — 필드가 비공개면 구조적
   만족이 타입 레벨에서 성립하지 않는다. `Store`와 달리 `Source`는 키가 사용자
   것이 아니므로 예약 이름이 늘어도 충돌하지 않는다.
   - **이름**: 사용자가 `Count` 대신 `token`/`revision` 제안. 공개 필드는
     코퍼스 관례가 PascalCase(`Slot.Length`/`Slot.Offset`/`Ref.Value`/
     `blocker.IsBlocked`)이므로 **`Revision`**(숫자안) 또는 **`Token`**
     (테이블안)을 권고.
3. **[해소] 계약은 "직전 값과 다르다"만 요구한다** — 순서 비교(`<`)는 지금
   규칙 어디에도 안 쓰이고 전부 `==`/`~=`뿐이라, 단조 증가조차 계약으로는
   과하다.
   - **⚠️ 다만 사용자 근거 한 줄은 정정이 필요하다**: *"오버플로가 나든 뭐가
     되든, 이전값과 다르다는 보장될거예요."* — Luau 숫자는 double이라
     **랩어라운드가 아니라 포화**한다. `2^53`을 넘으면 `n + 1 == n`이 되어
     **다르다는 보장이 정확히 그 지점에서 깨진다.** 실제로는 도달 불가능하고
     (초당 100만 `Set`으로 285년), 그래서 **문제로 보지 않는다** — 근거만
     "오버플로해도 다르다"가 아니라 **"도달 불가능하다"**로 적어둘 것.
4. **[해소] 숫자 리비전으로 간다** — 사용자 선택(*"Revision 숫자로 가는걸
   저는 선택하고 싶어요"*). 아래는 판단 재료였던 대조: 사용자 대안: *"아니면 안전하게 그냥
   테이블을 비교자로 씁시다. 별로 무겁지 않다고 보여요."* 비교가 identity
   동등성이라 **기능적으로는 둘 다 성립한다.**
   - **테이블**: 포화 문제 자체가 없음. 대신 **`Set` 한 번마다 테이블 하나를
     할당**한다 — 트윈처럼 매 프레임 `Set`하는 소스가 여럿이면 GC 압력이
     생긴다(quad는 GC-native 아키텍처라 이 축을 신경 써왔다).
   - **숫자**: 할당 0, 비교도 더 쌈. 위험은 도달 불가능한 `2^53`뿐.
   - **에이전트 권고도 숫자(`Revision`)** — 트윈처럼 매 프레임 `Set`하는
     소스가 여럿이면 테이블안은 GC 압력을 만든다.
   - **[해소, 2026-08-21] `bit32.bnot(-rev)`로 확정.** 사용자가 인용한
     `bit32.bnot(-1) == 0`, `bit32.bnot(-0) == 4294967295`,
     `bit32.bnot(-4294967295) == 4294967294`가 **예시가 아니라 연산 자체**
     였다 — `bit32.bnot(-a)`는 `a > 0`이면 `a - 1`, `0`이면 `4294967295`인
     **랩어라운드 감소**이고, 갱신과 랩이 **FASTCALL 하나**로 끝난다.
     랩이라 double 포화(`n + 1 == n`)가 안 생긴다. 충돌 거리 자체는
     오히려 짧아지지만(`2^53` vs `2^32`) **둘 다 도달 불가능이라 정확성은
     동률**이고, 사용자가 hot path 비용을 근거로 골랐다: *"매번 도는
     코드인지라, 값 싸게 native call + num 연산으로 가볍게 가고 싶어요."*
     - **⚠️ 에이전트가 한 번 잘못 옮겼다** — 형태를 `band(rev + 1, mask)`로
       적고 "덧셈 위에 fastcall이 하나 더 얹힌다"고 단서까지 달았는데,
       사용자 정정(*"제가 말한건, bit32.bnot(-a) 입니다"*)으로 둘 다 틀린
       게 확인됐다. 실측·정본은 `base/state-epoch-plan.md` §2.
5. **[해소] State는 `EpochMap`을 둘 컴포지션하고, `:Sync`는 필수 연산이
   아니다 — 에이전트 착오 정정.** 에이전트가 "재계산 후 전부 최신으로
   맞추려면 `Update` 외의 연산이 필요하다"고 적었으나, **`Update`가
   `Epoch|{Epoch}`를 받으므로 전체 deps를 넘기면 그게 곧 sync다**(사용자:
   *"애초에 Update 자체가 전부 최신 상태로 만들고, 업데이트 된게 있으면
   true 를 던지는거라"*). 에이전트가 `Update`를 "하나만 받는 것"으로 좁게
   본 탓이다.
   - **초기화도 같은 연산 하나로 끝난다** — `:With`/`:Compute`의 deps를
     전부 `Update`하고 **반환값은 안 보고** `rawInvalid = true`로 둔다.
     이미 확정된 노드 생성 규칙(`base/state-epoch-plan.md` §4의 "노드가
     생길 때의 초기값" 절)과 정확히
     같은 동작이다.
   - **내부 최적화(사용자 제안)**: `Update`가 목록을 돌 때 diff 때문에
     읽기가 들어가는데, **한 번 다름을 찾으면 반환값이 이미 `true`로
     확정**되므로 나머지는 읽지 않고 쓰기만 하면 된다.
   - **`:Sync`는 순수 최적화로만 둘 수 있다** — 읽기를 아예 건너뛰고 쓰기만
     하는 변형(반환값 없음). *"없다고 안되는건 아닌데, 그냥 다 안 읽고 set
     만 해버리는것은 처음 셋팅에 도움은 됩니다."*
6. **[방향 확정] `Observer` 클로저 인자는 `:Compute`와 같은 모양** —
   `fn(self, from: Epoch|{Epoch})`. 사용자: *"Compute 와 유사하게 나올 수
   있다 봐요. self 를 넘겨주고, 그 뒤에 epoch|{epoch} 를 주는게 맞아보입니다."*
   `base/source-state-plan.md`의 "`:With`/`:Compute` — self 인자도 lazy
   핸들로 통일" 절과 같은 결이고, 값이 아니라 **핸들과 메타데이터**만
   넘기므로 *"값을 안 실어주는 구독"* 계약도 안 깨진다.

   > **⚠️ [2026-08-26] 위 2-인자 표기는 2026-08-21 시점 기록이다** —
   > 지금 확정된 시그니처는 **세 자리** `fn(targetState, self, emitFrom)`이다
   > (8라운드 `H-109`: 여기서 `self`가 뜻하던 "리시버 State의 lazy 핸들"과
   > 전파 루프가 실제로 넘기던 Observer 값이 충돌해 있었고, Observer 핸들이
   > 가운데 자리로 들어왔다). **이 문서는 근거 기록이라 본문을 소급 수정하지
   > 않는다** — 지금 유효한 계약은 `base/source-state-plan.md`가 소스.
   - 반영 시 같이 손볼 것: 그 계약 문단과 인자 없는 `state:Observer()` 유틸,
     그리고 `base/effect-plan.md`의 내부 Observer 등록부(여기서 `Effect`가
     자기 `EpochMap`을 `Update`한다).
7. **[해소] `Brand` 전환 범위와 마일스톤** — 역조회가 불필요하고 포함 관계
   성질도 유지되므로 **인스턴스 브랜드로 전면 전환**이면 된다. **커밋된 M1
   코드는 `Brand`를 아직 안 쓴다**(`quad-base/src`는 `init.luau`/`Relate.luau`/
   `Debug`뿐, 2026-08-21 확인) — 전환 비용은 **문서뿐**이다. `Brand`라는 이름
   자체는 여전히 용어 정리 대기(`question.md` 1번).

## 관련 문서 (전부 승격 반영 완료)

- `base/state-epoch-plan.md` — `Epoch`/`EpochMap`과 State의 두 맵, 수신 규칙.
- `base/brand-plan.md` — 인스턴스 브랜드(옛 단일 레지스트리는
  `archive/brand-shared-registry-reversed.md`).
- `base/source-state-plan.md` — `Source`가 `Epoch`를 구조적으로 만족,
  `state:Observer(fn)`의 콜백 계약(**[2026-08-26]** 지금은 세 자리
  `fn(targetState, self, emitFrom)` — 위 6번의 ⚠️ 참고).
- `base/effect-plan.md` — `Effect`가 자기 `EpochMap`을 들어 다중 deps 중복
  발화를 접는다(이 제안이 닫은 갭).
- `base/gate-plan.md` — 배치 페이로드(4번), 빈 배치 무통지(8번).