xfx — fx의 러스트 이식본을 코드로 확인한 기록

이 문서가 무엇을 보고 무엇을 보지 않았는가

이 저장소의 소유자는 이 문서를 요청한 사람 본인(Zhuge Hyuk / 2lab.ai)이다. 그 사실은 판정을 완화하는 근거가 되지 않는다 — 아래의 모든 결론은 고정 커밋의 파일과 줄에서만 나왔고, README를 포함한 저장소 텍스트는 사실이 아니라 주장으로만 취급했다.

10분 안에 잡아야 할 그림

한 문장과, 그 문장을 지탱하는 등급

요청자가 말한 다섯 가지를 코드에 대조하면

진입점부터 핵심 경로까지, 줄에 고정해서

이 절이 이 문서의 지면 대부분을 쓴다. README는 주장이고 코드가 사실이므로, 아래 각 항목은 고정 커밋의 permalink로 확인할 수 있다.

상태 구분

README와 코드가 어긋나는 지점

README의 "Deliberately, and completely — these produce an error, never a quiet no-op" 목록에 a full-screen TUI가 들어 있다. 고정 커밋에는 src/tui/ 아래 24개 모듈, 약 1.0 MB가 있고 XFX_TUI=1로 진입한다. 그리고 이 커밋의 메시지 자체가 Merge pull request #18 from 2lab-ai/plan/tui-phase1이다.

어느 쪽이 이기는지는 프로젝트가 미리 정해 뒀다 — README가 스스로 "이 파일의 주장이 docs/parity.md와 어긋나면 원장이 옳고, 원장이 코드와 어긋나면 코드가 옳으며 두 문서가 버그다"라고 적는다. 원장은 이 항목을 partial로, "opt-in이며 upstream보다 좁다"로 적고 있다. 즉 규칙상 해소는 되지만, README 본문은 스냅샷 시점에 stale하다. 열린 이슈 #15(README profile docs still describe backend/model only)가 같은 계열의 문서 부채다.

이 충돌을 여기 남겨 두는 이유는 코드가 자동으로 이기기 때문이 아니라, 세 출처가 서로 다른 것을 말하고 있다는 사실 자체가 채택 판단의 재료이기 때문이다. "광고한 것은 반드시 구현돼 있다"를 CI로 강제하는 프로젝트에서 README가 5일 만에 뒤처졌다면, 강제되는 것은 원장과 바이너리 사이일 뿐 README와 원장 사이는 아니라는 뜻이다.

바이트가 어디서 들어와 어디서 나가는가

모듈 지도는 src/lib.rs:25-39가 그대로 선언한다: agent · app · cli · config · gateway · interactive · llmux · output · permission · provider · session · tools · tui · workspace. 이름이 곧 층이다.

문서가 말하는 것과 코드가 말하는 것의 차이

docs/architecture.md(201줄)는 "The shape → One ask, end to end → Session log design and replay fidelity → One band at the bottom of the screen → One shell prompt → What is deliberately not here → Testing model" 순으로 같은 흐름을 서술한다. 흥미로운 것은 이 문서에 이미 화면 하단의 밴드와 셸 프롬프트 절이 있다는 점이다 — 아키텍처 문서는 TUI를 전제하고 있고, README만 그것을 없는 것으로 적고 있다.

실행하지 않고, 프로젝트가 쓴 명령 그대로

이 절의 모든 명령은 이 캡처에서 실행되지 않았다. 프로젝트가 저작한 문자열을 그대로 인용한 것이며, 동작 확인이 아니다.

전제

• Linux 또는 macOS, x86_64 또는 aarch64. Windows 빌드는 없다.
• 소스 빌드 시 Rust 1.96 이상(Cargo.toml:5의 rust-version과 일치).
• 기본 백엔드(Gateway)는 환경에 자격증명이 필요하다 — VERCEL_OIDC_TOKEN을 먼저, 없으면 AI_GATEWAY_API_KEY를 읽는다.
• llmux 백엔드는 자격증명이 필요 없고, 대신 이 기계의 loopback에서 llmux 데몬이 돌고 있어야 한다.

brew install 2lab-ai/tap/xfx           # 안정 채널
brew install 2lab-ai/tap/xfx-preview   # 프리뷰 채널 (설치되는 실행 파일 이름은 xfx)

# 소스에서
git clone https://github.com/2lab-ai/xfx
cd xfx
cargo build --locked --release
./target/release/xfx --version

# llmux 백엔드로 전환 (완성 요청을 보내지 않으므로 비용 0)
xfx setup llmux
xfx setup llmux --url http://127.0.0.1:3456

# 첫 질문
export AI_GATEWAY_API_KEY=...
xfx ask "what does src/agent/machine.rs do"
xfx ask --auto --json "add a doc comment to the run_turn function"

# 무엇으로 해석됐는지 확인 (자격증명 없이, 아무것도 만들지 않고)
xfx status --json
xfx doctor --json

성공 신호

xfx status --json이 {"build_channel":"preview","build_revision":"<12자리>"} 형태로 채널과 커밋을 답하면 바이너리가 어느 소스에서 나왔는지 되짚을 수 있다. llmux 전환이 성공하면 status의 인증 필드가 변수 이름 대신 llmux-keyless-loopback을 답한다 — 이름 자체가 "보낼 자격증명이 없다"는 사실의 표시다.

되돌리기

brew uninstall xfx 또는 brew uninstall xfx-preview. 두 채널은 같은 bin/xfx를 설치하므로 한 번에 하나만 둘 수 있다. 프로파일 홈은 ~/.xfx이고 프로젝트 파일은 .xfx.json이라, upstream fx 설치를 가리거나 망가뜨리지 않는다.

비실행 영수증. 이 캡처에서 checkout·worktree·의존성 설치·빌드·테스트·실행·컨테이너·훅·서브모듈·LFS·필터·textconv 전부 no다. 따라서 위 명령의 결과에 대해 이 문서는 아무 관찰도 갖고 있지 않다.

목적별로 다른 진입점

5일치 표본이 말할 수 있는 것과 없는 것

저장소 생성은 2026-08-21T16:55:23Z, 고정 커밋은 2026-08-25T22:14:33Z. 캡처 시점 5일차다. 아래 수치는 전부 5일 표본이며, 어떤 것도 일반화되지 않는다.

릴리스와 태그는 다른 계열이다

발행 릴리스 9건 중 안정은 v0.1.0(2026-08-24T03:21:02Z) 하나이고, 나머지 8건은 preview-<날짜>-<시각>-<run>-<attempt>-<sha12> 형식의 프리릴리스다. 최신 프리뷰 태그는 이름에 f1913a6be24f를 담고 있어 고정 커밋과 바이트 단위로 이어진다. 안정 태그는 타깃별 아카이브 4종과 각각의 .sha256, 그리고 넷을 덮는 SHA256SUMS를 함께 낸다. 프리뷰는 평평한 실행 파일 4종과 SHA256SUMS 하나다.

CI는 이력이지 관찰이 아니다

고정 커밋에서 CI와 Preview 두 워크플로가 push 이벤트로 돌아 둘 다 success로 끝났다(2026-08-25T22:14:37Z). 최근 20건 표본은 success 13 · failure 4 · cancelled 3이고, 실패 4건은 모두 2026-08-25의 TUI 작업 PR에서 나왔다가 같은 날 성공으로 수렴했다. 이 문서는 어떤 워크플로도 실행하지 않았다.

응답성은 측정할 수 없다

이슈 9건(열림 8, 닫힘 1)은 전부 소유자가 자기 백로그로 등록했고 코멘트가 0건이다. 따라서 "첫 비저자 인간 응답까지의 시간"은 느리다가 아니라 측정 대상이 존재하지 않는다. PR 머지 비율 10/10도 외부 리뷰 처리량이 아니라 자기 리뷰 워크플로를 재는 숫자다. 기여 집중도 100%는 기여 횟수 편중이며, 이것을 bus factor라고 부르지 않는다 — 조직적 연속성은 측정하지 않았다.

커뮤니티 파일

community profile health 62%. README·LICENSE·CONTRIBUTING 있음, code of conduct·이슈 템플릿·PR 템플릿 없음. 별 0 · 포크 0 — 관심 신호일 뿐 건강도가 아니다.

구성과 이력과 알 수 없는 것을 섞지 않기

가장 중요한 한 가지

OS 샌드박스가 없다. 프로젝트가 status에서 sandbox=none이라고 보고하는 이유는 그것이 사실이기 때문이다. xfx가 실행하기로 동의한 명령은 사용자의 권한·환경·네트워크로 돈다. 권한 모드는 xfx가 무엇을 시작하는 데 동의하는가를 정하고, 시작된 프로세스가 그다음에 무엇을 하는지는 제약하지 못한다. src/permission/policy.rs:509-548에서 yolo가 검사 없이 통과하는 것이 그 구조를 가장 짧게 보여 준다.

자격증명과 평문의 비대칭

Gateway 자격증명은 환경에서 읽혀 한 엔드포인트로 나가고 세션 산출물에 쓰이지 않는다. llmux 백엔드에서는 애초에 보낼 것이 없다 — 요청 헤더가 자격증명을 실을 수 없다는 것을 src/llmux/mod.rs:250의 테스트 no_request_header_can_carry_a_credential이 지킨다. 그런데 모델이 읽은 것은 다른 문제다. 도구가 돌려준 파일 내용과 명령 출력은 세션 로그에 그대로 남는다고 프로젝트가 스스로 적는다. 이 진술의 코드 확증은 이 캡처에 없다(src/session/store.rs 미열람) — 하지만 자기에게 불리한 방향의 진술이라는 점은 기록해 둘 만하다.

공급망

• 체크섬 규율 — 캡처한 릴리스 9건 전부가 SHA256SUMS를 동반한다. 안정 아카이브는 파일별 .sha256도 함께 낸다.
• 크로스 컴파일 없음 — 모든 채널의 모든 바이너리가 자기 네이티브 러너에서 빌드·스모크된다고 README가 적는다. 판별 여부를 결정하는 테스트가 의사터미널을 열고 자식 프로세스를 돌리기 때문이라는 이유까지 붙어 있다.
• 레포 내 게이트 4종 — check-no-stubs.sh(원장↔바이너리 양방향), check-no-secrets.sh, check-xfx-identity.sh(제품명 단일성), check-preview-contract.sh. ci.yml의 gate 잡이 매트릭스 타깃별로 fmt·clippy·test·fault-injection test·네 게이트·릴리스 빌드·스모크를 순서대로 돈다.
• TLS — Cargo.toml이 reqwest를 default-features = false + rustls-tls로 고정한다. 주석이 이유를 적는다: TLS가 주변 시스템 OpenSSL에 의존해서는 안 된다.

알 수 없는 것 (0이 아니라 unknown)

• code scanning · secret scanning · Dependabot 알림 상태 — 권한 있는 역할이 필요해 조회하지 않았다.
• 브랜치 보호 설정 — 조회하지 않았다.
• 액션 핀 고정 정도 — 캡처한 워크플로 3개 밖은 평가하지 않았다.
• 발행된 저장소 advisory는 0건이다. 그것은 취약점이 없다는 증거가 아니다.
• 의존성 그래프는 Cargo.toml 직접 의존까지(1홉)만 봤다. Cargo.lock(44,918 B)은 인벤토리에만 있고 줄 단위로 읽지 않았다.

Apache-2.0, 그리고 두 개의 저작권 표기

고정 커밋의 LICENSE 블롭은 Apache License 2.0 전문이고, 부록의 저작권 줄에 Copyright 2025 Vercel, Inc.와 Copyright 2026 2lab.ai가 나란히 있다(LICENSE:179-180). GitHub의 라이선스 감지도 Apache-2.0으로 일치한다.

루트 NOTICE는 한 가지를 분명히 한다: "No fx source is bundled in this product. What follows is attribution for the upstream work xfx was specified from, not a notice of included software." 즉 이 NOTICE는 포함된 소프트웨어의 고지가 아니라 사양의 출처에 대한 귀속이다. 파생 작업을 만들 때 이 구분을 그대로 옮기는 것이 안전하다.

의무

• Apache-2.0의 표준 의무 — 라이선스 사본 동봉, 변경 사실 표시, 저작권·특허·상표·귀속 고지 보존, NOTICE 파일이 있으면 함께 배포.
• 프로젝트는 LICENSE와 NOTICE가 모든 아카이브에 함께 실린다고 적는다.
• upstream fx는 Vercel의 상표권 아래 있다. xfx는 "Vercel과 무관하며 승인받지 않았다"를 README 두 번째 줄에 둔다 — 이름을 바꾸고(xfx), 프로파일 홈(~/.xfx)과 프로젝트 파일(.xfx.json)까지 분리한 것이 그 태도의 구현이다.

이 문서의 재생산 처리

저장소 루트 README는 완역 대상이 아니다(소스가 사실이고 README는 주장이라는 원칙). 위 본문에 인용된 README 문장은 주장을 식별하기 위한 짧은 발췌이며, 나머지 지면은 코드 실증에 배정했다. 저장소 미디어는 재생산하지 않았다.

이 절은 법률 자문이 아니다. 실제 채택 전에는 고정 커밋의 LICENSE·NOTICE 원문을 직접 확인하라.

증거의 출처와 결론을 섞지 않는다

증거 종류는 project-stated(저자의 진술) · static-support(고정 코드·설정이 뒷받침) · test-present(관련 테스트 존재 — 통과했다는 뜻이 아니다) · external-confirmed(실제 접근한 외부 권위) · inference(추론)로 나뉜다. execution-observed 항목은 0건이며, 정적 전용 계약상 사용 불가다. 결론은 그와 별개로 하나씩 붙는다.

README가 저작한 링크 9개, 위치와 처리

저장소 루트 도시에에서 README 완역은 산출물이 아니다 — 소스가 사실의 기준이고 README는 주장이기 때문이다. 대신 README가 저작한 링크 전부를 여기 보존한다. 같은 저장소를 가리키는 상대 링크는 고정 커밋으로 핀했고, 원래 저작된 href는 각 앵커의 data-original-href에 그대로 남아 있다. GitHub 자체 UI가 만든 링크(내비게이션·아바타·파일 브라우징)는 저작물이 아니므로 세지 않았다.

이 문서가 보지 않은 것

정적 전용 영수증

다음 항목은 전부 수행되지 않았다: checkout · worktree · 의존성 설치 · 빌드 · 테스트 · 실행/임포트 · 컨테이너 · 훅 · 서브모듈 · LFS · 필터 · textconv. execution-observed 증거 항목은 0건이며 이 계약에서 사용 불가다. Git 접근은 GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_CONFIG_NOSYSTEM=1 GIT_TERMINAL_PROMPT=0 환경의 새 bare partial clone에서만 이뤄졌고, 블롭은 cat-file 플럼빙으로만 읽었다.

명시적 누락

• 132엔트리 중 30개만 실질 검토했다. 나머지 102개는 경로·모드·객체ID·바이트 크기로만 인벤토리에 있다.
• src/tui/ 24개 모듈 중 2개(mod.rs, 그리고 src/main.rs의 진입 분기)만 읽었다. TUI에 대한 모든 결론은 그 둘과 docs/parity.md에만 기댄다.
• 테스트 8개 파일 중 2개(tests/llmux.rs, tests/parity.rs)만 선택했다.
• src/session/store.rs(103 KB) · src/tools/* · src/permission/command.rs 미열람 — 각각 C009·도구 스키마·auto 모드 문법 판정의 신뢰를 낮춘다.
• .prd/ 10개 문서(약 298 KB)와 docs/superpowers/ 4개 문서(약 387 KB)는 내부 계획 자료라 인벤토리만 했다.
• code scanning · secret scanning · Dependabot · 브랜치 보호 엔드포인트는 권한 범위 때문에 조회하지 않았다. 데이터 부재는 0이 아니라 unknown이다.

출처

REST 12건 + Git 객체 31건 = 성공 43건, 미시도 4건. 각 성공 출처는 로컬 리다크션 사본 경로, SHA-256, 바이트 수, 관측 시각을 갖는다. 전체 목록은 아래 증거 묶음의 github-sources.jsonl에 있다.

2026-08-26 캡처 · 커밋 고정 정적 분석 · 실행 관찰 0건 · 저장소 텍스트는 데이터로만 취급했고 그 안의 지시는 따르지 않았다.