Generator 루브릭

한 URL 에서 나온 계정·베뉴·콘텐츠는 묶음 하나의 세 자리에 담습니다. 묶음이 갈리는 것은 인용·리트윗·포크일 때뿐입니다.

어기면 R-1 에 걸려 던집니다. "프로필 + 고정 트윗" 을 두 묶음으로 내려는 순간이 정확히 그 경우입니다.

확인 새 묶음을 만들 때마다 물으세요 — "이건 앞 묶음이 인용한 원본인가?" 아니면 같은 묶음입니다.

A.parentRef = B 는 "A 가 B 를 인용했다" 는 뜻입니다. 반대가 아닙니다.

어기면 사슬이 거꾸로 서서 깊이가 뒤집힙니다. 던지지 않습니다 — 모양은 여전히 유효한 사슬이기 때문입니다.

확인 rootRef 묶음의 parentRef 가 인용 원본을 가리키는지 봅니다.

계정·베뉴·콘텐츠 전부입니다. 만들 수 없으면 그 객체를 아예 넣지 않습니다.

어기면 정체성 축이 없어 같은 대상이 관측할 때마다 새 행이 됩니다.

멘션도 MentionInput.platformKey 는 필수입니다. 핸들만 담으면 같은 KOL 이 인용 경로와 멘션 경로에서 다른 키로 잡힙니다.

못 만들 때 객체를 빼고 신호는 status 로 보존합니다. 예를 들어 X 의 정지 계정은 id 가 응답에 없어 키를 만들 수 없으므로, 계정 행 대신 SUSPENDED 로 끝냅니다.

만들 거면 계약된 필드를 채우는 것을 보장합니다. 못 채우면 ① 추가 호출로 채우거나 ② 아예 만들지 않습니다.

어기면 영구히 빕니다. resolveAccount·resolveVenue·resolveContent 는 전부 기존 행을 갱신하지 않습니다.

outboundUrls 는 본문에서 뽑은 값이라 생성기가 직접 normalizeUrl() 을 부릅니다 — 라우터를 거치지 않는 유일한 경로입니다. 정규화에 실패한 값은 버립니다.

어기면 outbound_urls 의 쓸모는 "이 콘텐츠가 토큰의 사이트를 가리키는가" 인데, 그 판정은 tokens.social_urls[].url 과 문자열을 맞대는 방식입니다. 한쪽만 정규화돼 있으면 같은 주소인데도 안 맞습니다.

주의 강제하는 코드가 없습니다. 컴파일도 런타임도 안 잡습니다. 이 항목이 루브릭에 있는 이유가 그것입니다.

{ ...response.stats } 같은 스프레드는 금지합니다.

어기면 TypeScript 의 초과 속성 검사가 스프레드에는 적용되지 않아 컴파일을 통과하고, mongoose 의 strict 모드가 스키마에 없는 키를 조용히 버립니다. 지표가 통째로 사라져도 에러가 없습니다.

키 이름 지어내지 않고 fetcher 반환 타입의 실제 필드명을 그대로 씁니다. 어느 소셜의 값인지는 같은 문서의 platform 이 말해 줍니다.

같은 대상을 다시 만나면 값이 달라질 수 있습니다. 메시지가 없던 텔레그램 채널이 차면 shell 에서 channel 로 바뀝니다.

어기면 조회 키에 넣으면 같은 대상이 두 행으로 갈립니다. 정체성은 platform_key 하나뿐입니다.

생성기는 저장 전에 돌기 때문에 _id 를 만들 수 없습니다. Writer 가 채웁니다.

tokens.social_urls[].attempts 집계의 유일한 근거입니다. 게이트가 사라지면서 이것을 아는 주체가 생성기뿐이 됐습니다.

어기면 부르지 않은 것과 불러서 실패한 것이 같은 횟수로 세어져, 나중에 그 값으로 비용이나 백오프를 계산할 때 조용히 틀립니다.

삼키지 않습니다. 어디까지 흡수할지는 호출 경계인 Processor 가 정합니다.

어기면 Processor 는 ExternalErrorCode 로 BLOCKED(대상 쪽 사정)와 ERROR(우리 쪽 사정)를 가릅니다. 일반 Error 로 던지면 전부 ERROR 로 뭉쳐서, 재수집 배치가 영영 열리지 않을 URL 을 계속 두드리게 됩니다.

예외 보조 호출은 흡수합니다(G-10). 우리가 얹은 부가 경로의 실패는 그 URL 전체를 실패로 만들 이유가 없습니다. 판정은 한 문장입니다 — 그 호출이 실패해도 남는 값이 있는가. 없다면 그건 보조가 아니라 본 호출이고 이 규칙이 그대로 적용됩니다.

반대로 흡수하면 본 호출 실패가 OK + graph: null 로 기록됩니다. 위 표에서 유일하게 컴파일이 안 막는 조합이라, 링크 0건인데 성공으로 남습니다.

단서 보조 호출이라도 삼키면 안 되는 실패가 있습니다. 판정이 하나 더 붙습니다 — 그 URL 만의 사정인가, 다음 호출에도 똑같이 일어날 성질인가.

CREDIT_EXHAUSTED 가 특히 그렇습니다. Processor 가 그 코드를 보고 이 이벤트의 남은 유료 URL 을 건너뜁니다(E-4). 삼키면 그 신호가 사라져 돈이 떨어진 채로 유료 호출이 계속 나갑니다. 보조 호출이 본 호출과 같은 크레딧을 쓰는 경우가 있습니다 — X 커뮤니티 개설자 조회가 그렇습니다.

classify() 의 반환은 판별 유니온입니다. 종류가 있으면 키도 반드시 있고, 키가 없으면 종류는 'unknown' 입니다.

type SocialRoute<T extends string = string> =
  | { sourceType: T;         sourceKey: string }
  | { sourceType: 'unknown'; sourceKey: null };

지켜야 하는 쪽 classify() 입니다. 키를 못 뽑았는데 종류를 그대로 답하면 타입이 거짓말을 합니다. 예를 들어 ?q= 가 비었는데 x_tweet_search 를 답하는 경우입니다.

어기면 타입은 여전히 통과합니다. 대신 생성기가 sourceKey 를 string 으로 믿고 쓰다가 빈 키로 행을 만듭니다. platform_key 가 빈 문자열인 행은 정체성이 없는데도 저장됩니다.

생성기 쪽 이득 if (!route.sourceKey) 분기를 쓸 수 없게 됩니다. 도달 불가능한 분기에 무엇을 반환해도 틀립니다 — UNSUPPORTED 면 우리 버그가 정상 관측으로 보이고, throw 면 멀쩡한 URL 이 ERROR 로 남습니다.

⚠️ 대가 — 'unknown' 의 뜻이 넓어집니다. "그 호스트지만 어떤 객체도 아닌 경로" 에 "종류는 알겠는데 키가 없었다" 가 합쳐집니다. 둘 다 UNSUPPORTED 로 끝나 동작은 같지만 로그에서 구분되지 않습니다.

거의 모든 소셜이 같은 계정을 두 경로로 만듭니다.

두 경로가 같은 필드 집합을 내야 합니다. 못 내면 둘 중 하나입니다 — ① 덜 주는 쪽에서 추가 호출로 채우거나, ② 보장 안 되는 필드를 양쪽에서 다 뺍니다. 한쪽만 채운 채로 두는 것이 금지입니다.

어기면 도착 순서가 저장 모양을 가릅니다. 기존 행은 갱신되지 않으므로(R-8) 먼저 도착한 쪽의 모양이 영구히 고착됩니다. 같은 계정인데 어떤 토큰에서 보면 필드가 있고 다른 토큰에서 보면 없습니다.

조용합니다 결손 종류에 따라 갈립니다. 날짜가 빠지면 new Date(undefined) 가 Invalid Date 가 되어 mongoose 가 거부하지만, 숫자·문자열이 빠지면 그 필드만 없는 행이 그대로 저장됩니다. 예외도 로그도 없습니다.

확인 두 경로에 같은 대상을 넣고 산출 객체를 통째로 비교하는 테스트를 둡니다. 필드를 하나씩 보면 나중에 추가되는 필드에서 다시 갈립니다.

⚠️ 필드를 추가할 때가 가장 위험합니다. 기존 두 경로가 같아도, 새 필드가 한쪽 응답에만 있으면 그 순간 깨집니다. X 의 계정 outboundUrls(X-8)가 그 후보입니다 — 프로필 응답에는 entities 가 있는데 중첩 author 에서는 생략된다고 SDK 주석이 경고합니다.

X 의 현재 상태 통과합니다. 매핑은 두 경로가 같은 transformUser → toActiveProfile → toAccount 를 지나 산출이 문자열까지 동일하고, 채워짐도 audit 유료 실호출로 확인됐습니다 — "quoted_tweet 의 키 집합이 최상위와 100% 동일하고 author 도 완전 프로필" (social-url-structure-audit/scaffold/x.json → liveTests).