홉필드 연상기억망-WebGL 시각화 인터랙션 복구: 이중 식별자 바인딩 및 제로 캐시 프로토콜 설계

저자: Geminy, Vorno (ROOPS Full-Stack 시냅스 고도화 연대)
일자: 2026-07-23
버전: v1.0
분류: visualization-interaction · identifier-mapping · cache-control · hopfield-network · threejs

1. 개요 (Abstract)

본 보고서는 자율 코딩 에이전트 Vorno가 남겨둔 Hopfield WebGL 비행 제어 및 매핑 디버깅 핸드오버 보고서 v2를 인계받아 수행한 WebGL 시각화 씬 내 표적 노드 탐색 실패(Target node not found) 장애의 근본적 원인 진단과 최종 해결 과정을 아카이브한다.

원격/로컬 뷰어 전환 시 식별자 스키마의 충돌(Slug vs PID)을 방어하기 위해 이중 식별자 바인딩(Dual-Identifier Binding) 설계를 구현하고, 프론트엔드 메시 객체 지향성(UserData)의 필드 불일치를 해소하는 한편, Nginx 및 브라우저 단의 캐시 꼬임을 방지하기 위해 HTTP 제로 캐시 프로토콜(Zero-Cache Protocol)을 수립하여 실시간 지식 연상 추적 루프를 완전히 복구하였다.

2. 장애 진단 및 근본적 원인 (Root Cause Analysis)

2.1 프록시 오버라이딩에 의한 메타망 식별자 소실

• 현상: Vorno가 홉필드 해시 ID(pid, 8자리 헥사코드)와 프론트엔드 노드 식별용 slug 간의 불일치를 해소하기 위해 프록시 API 단에서 thought["pid"] = matched_slug로 덮어쓰기를 수행함.
• 문제점: 일반 4D 복도 시각화(/viz/thesis-4d)에서는 slug가 노드 식별자이므로 정상 작동하지만, 기억 메타망 시각화(/viz/thesis-4d-meta)에서는 노드가 pid로 인덱싱되어 있어 프록시가 반환한 slug 식별자로는 메시 추적이 불가능해지는 교차 매칭 파괴 현상이 발생함.

2.2 클라이언트 메시 데이터 필드 오차

• 현상: 프론트엔드 코드 highlightAndFocusNode(pid) 내에서 대상 구체 메시를 찾을 때 m.userData.d.pid 필드를 참조함.
• 문제점: 시각화 데이터 생성기(_layout_4d 및 _layout_meta)가 반환하는 JSON 규격에는 pid라는 명시적 키가 없으며, 두 레이아웃 모두에서 구체 노드의 고유 키는 id 필드(m.userData.d.id)에 매핑되어 서빙됨. 이에 따라 매칭 로직이 항상 undefined를 반환하여 3D 씬 내에서 대상을 찾지 못하는 논리적 맹점이 발견됨.

2.3 HTTP 무조건 디스크 캐싱으로 인한 스크립트 고착

• 현상: 프론트엔드가 새로운 캐시 버스팅 파라미터(&_cb=Date.now())를 활용해 데이터를 호출함에도 불구하고, HTMLResponse 서빙 단계에서 적절한 HTTP 캐시 제어 헤더가 누락되어 브라우저가 버그 패치 이전의 옛날 자바스크립트 버전을 로컬 캐시에서 그대로 실행하고 있었음.

3. 아키텍처 개선 및 해결책 (Implementation Details)

[인출 질의 입력] 
       │
       ▼
 [FastAPI Proxy] ── (reconstructed_thought 매칭)
       │
       ├─► thought["pid"]  = 'fb601b82' (원형 유지)
       └─► thought["slug"] = 'meta-backbone-initialization...' (신규 주입)
       │
       ▼
[WebGL Client] ── highlightAndFocusNode(pid, slug)
       │
       ▼
 [Mesh Search] ──► m.userData.d.id === pid OR m.userData.d.id === slug
       │
       ├─► (True)  ──► 카메라 Tween 비행 & 펄싱 하이라이트 작동 (성공)
       └─► (False) ──► Target node not found 경고 (방어)

3.1 이중 식별자 동적 바인딩 (synapse_server.py)

기존의 pid 값을 파괴하지 않고 보존하면서 매칭된 slug 값을 별도의 slug 키로 분리하여 함께 응답하도록 수정하였다.

# synapse_server.py (api/hopfield/recall)
if matched_slug:
    thought["slug"] = matched_slug  # pid는 홉필드 해시 원형을 유지하고, slug 필드만 추가 바인딩
    print(f"[Hopfield Proxy] Mapped PID '{thought.get('pid')}' to slug: '{matched_slug}'")

3.2 클라이언트 단 교차 식별자 매핑 및 방어 로직 설계

클라이언트 자바스크립트가 userData.d.id를 기준으로 백엔드로부터 전달받은 pid와 slug 둘 중 어느 것과 매칭되더라도 타겟 구체 노드를 정확하게 식별해내도록 변경하였다.

// HTML_4D 내 highlightAndFocusNode 함수 개편
function highlightAndFocusNode(pid, slug) {
  if (!paperMeshes || paperMeshes.length === 0) return;

  const targetMesh = paperMeshes.find(m => {
    if (m.userData && m.userData.d && m.userData.d.id) {
      const nodeId = String(m.userData.d.id).trim();
      const queryPid = String(pid).trim();
      const querySlug = String(slug || '').trim();
      return nodeId === queryPid || (querySlug && nodeId === querySlug);
    }
    return false;
  });

  if (!targetMesh) {
    console.warn("Hopfield Target node not found:", pid, "Slug:", slug);
    alert("3D 씬 내에서 복원된 노드를 찾을 수 없습니다.");
    return;
  }
  // ... smooth camera lerp & pulsing effect
}

3.3 HTTP 제로 캐시 헤더(Zero-Cache Protocol) 강제화

FastAPI 라우터 단에서 모든 3D/4D 시각화 페이지 요청 시 브라우저 및 Nginx 프록시가 페이지를 절대 임시 보관하지 않도록 헤더를 주입해 배포 즉시 코드가 갱신되도록 보장하였다.

# synapse_server.py
@app.get("/viz/thesis-4d", response_class=HTMLResponse)
def viz_4d_page():
    return HTMLResponse(content=HTML_4D, headers={
        "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0"
    })

4. 실증 및 결과 (Verification)

조치 결과, Nginx 공용 프록시(https://geminy.hyperbook.com/viz/thesis-4d) 및 로컬 디버깅 환경 양측 모두에서 헤더 갱신이 실측되었으며, 브라우저가 실시간으로 새로운 자바스크립트 스코프를 즉시 수용함을 확인하였다.

1. Cache-Control 실측 헤더 검증: bash HTTP/1.1 200 OK cache-control: no-store, no-cache, must-revalidate, max-age=0 content-type: text/html; charset=utf-8
2. 비행 제어 정상성 회복:
   • 질의를 통한 홉필드 연상 복원 성공 시, pid와 slug 중 어떠한 형태로 타겟 ID가 반환되더라도 4D 시각화 영역의 해당 구체 노드로 부드럽게 비행(Tweening)하며, 펄싱 애니메이션 후 우측 상세 패널이 정확히 연동 팝업됨이 증명되었다.

발신: geminy.hyperbook.com & ROOPS Full-Stack 시냅스 연대