토파즈 5.20.1이 현재 릴리스 버전입니다. 현행 언어 모드는 topaz-5.20입니다.
5.20.1의 소스는 github.com/studiohaze/topaz 에 공개되어 있습니다. 공식 릴리스는 topaz.ooo와 npm에 나옵니다.
다음 명령으로 설치 상태를 확인하세요.
topaz version --verbose이 명령은 컴파일러, 언어 모드, 런타임, Rust 백엔드 식별자를 출력합니다. 설치 관련 문제를 제보할 때는 출력 결과 전체를 그대로 첨부하세요.
컴파일러 선택하기
토파즈는 컴파일러가 관여하는 모든 명령에 Rust Stage 0을 기본값으로 사용합니다.
설치된 Stage 2 self 컴파일러는 허용된 현재 모드 경로에서 --compiler self로
명시적으로 선택할 때 계속 사용할 수 있습니다.
topaz check app/main.tpz
topaz check app/main.tpz --compiler self
topaz test --root app --locked --compiler self
topaz emit app/main.tpz --compiler self
topaz emit app/main.tpz --target python --compiler self --out-dir python-source
topaz build app/main.tpz --compiler self --out-dir app-product
topaz build app/main.tpz --target web --compiler self --out-dir web-product
topaz dev --root web-app --locked --compiler self
topaz fmt app/main.tpz --compiler self
topaz lsp --compiler self
topaz doc --root app --locked --compiler self --out-dir api-docs
topaz compiler observe app/main.tpz --compiler self --out-dir observation
topaz check app/main.tpz --compiler rust
topaz compiler status --json선택 생략은 --compiler가 없을 때 토파즈가 기본적으로 Rust Stage 0을 실행함을
의미합니다. 명시적 self는 허용된 현재 모드 경로에서 설치된 Stage 2 self 컴파일러를
호출하기 위해 --compiler self를 지정하는 것을 의미합니다. 실행은 지정된 컴파일러에
따라 직접 진행되며 자동 재시도나 조용한 폴백은 수행되지 않습니다. 명시적 self 선택은
parse, dump-ast, check, 현재 프로필, export 보고서, run, test,
bench, 잠긴 패키지, compiler observe, 검사된 Rust·Python 생성, 네이티브·Web
계열 빌드, Web·서비스 dev, 코드 포맷팅, LSP, 패키지 문서 생성을 지원합니다.
단일 LSP 프로세스는 하나의 컴파일러 선택을 유지하므로 설정을 변경한 뒤 에디터 세션을
재시작하세요.
컴파일러를 사용하는 명령에 --verbose 옵션을 추가하면 확정된 선택이 명시적 선택인지,
현재 기본값인지, 또는 호환 선택인지 표시합니다.
CLI는 실제 언어 모드를 파악할 때까지 컴파일러 선택 의도를 유지합니다. 패키지
명령에서는 먼저 루트 topaz.toml만 읽어 검증합니다. 의존성 해석, 잠금 파일
검사, 소스 로드, 캐시 및 출력 작업은 그 이후에 시작됩니다. 이전 언어 모드를
지정한 패키지는 선택자를 생략하거나 rust를 직접 지정할 경우 Rust를 사용합니다.
self를 직접 지정하면 이후 작업을 진행하기 전에 오류로 중단됩니다. 이러한 실행 순서 덕분에 현재 모드의
기본 선택과 명시된 Rust 호환 선택을 서로 다른 결정으로 구분하여 관찰할 수 있습니다.
설치된 프로세스는 변경 불가능한 셀프호스팅 컴파일러 이미지를 한 번만 검증하고 디코딩한 뒤, 이렇게 준비된 프로그램을 self 컴파일러와 LSP 작업 스레드가 공유하여 사용합니다. 캐시 키에는 이미지, 소스 집합, 스키마, 런타임 템플릿, 툴체인 식별자가 포함됩니다. 하나라도 일치하지 않으면 self 작업이 중단됩니다. 타깃 소스, 진단 정보, 생성 소스 및 관리 아티팩트는 요청 시마다 다시 계산하며 준비된 컴파일러 상태를 재사용하지 않습니다. 이 준비 과정은 문서에 규정된 콜드 스타트, LSP 및 메모리 임계값 내에서 실행됩니다.
compiler status --json은 머신이 읽을 수 있는 기준 정보를 출력합니다. 설치된
생성자, 프로그램 이미지, 소스 집합 식별자, 지원 경로 및 거부 경로, 경로별 생략
선택, 기본값, 호환·복구 선택, 무폴백 정책이 여기에 포함됩니다. 관리 아티팩트에는
선택이 명시적이었는지, 현재 기본값이었는지, 아니면 호환 선택이었는지 여부도 함께 기록됩니다.
설치 제품의 복구 경계
설치된 제품에서 패키지 검사, 테스트, 빌드 및 소스 없는 실행은 Rust Stage 0 기본값을
사용합니다. 명시적 self는 허용된 현재 모드 경로에서 --compiler self를 전달하여
별도로 선택할 수 있습니다. 동일한 관리 출력 경로에 Rust와 self로 재빌드하면 출처를
원자적으로 교체합니다.
동일한 설치 기본값으로 2모듈 학습 애플리케이션을 검사하고 선택 테스트를 실행한 후 네이티브 릴리스 아티팩트로 패키징하면 소스 코드를 제거한 상태에서도 실행할 수 있습니다. 운영 현황 장부는 해결된 제품 문제만 종결 처리하며, 보다 광범위한 컴파일러·통합 검사는 공개 릴리스 후보에서 수행합니다.
설치된 Stage 1 및 Stage 2 경로는 새 소스에서 각각 새로운 관측 데이터를 생성하여 검증할 수 있습니다. 명시적 self 선택으로 새 네이티브 아티팩트를 생성하고 소스 코드 없이 실행할 수도 있습니다.
npm으로 설치된 결과물은 두 컴파일러 선택지를 단일 실행 파일에 내장합니다. 저장소를
checkout할 필요가 없습니다. 어떤 컴파일러로 빌드했든 토파즈 소스를 제거한 후에도
결과물을 실행할 수 있습니다. 설치된 셀프호스팅 컴파일러 이미지가 없거나
손상된 경우 self 요청은 즉시 실패합니다. Rust 컴파일 결과를 차용하거나 자동으로
재시도하지 않습니다. 복구를 직접 선택할 때만 원래 명령을
--compiler rust로 다시
실행하세요. Rust는 언제든지 별도로 사용할 수 있습니다. 공개된 Stage 0 복구 키트는 자동
폴백이 아닌, 수동으로 실행하는 오프라인 재구성 경로입니다.
설치된 self 컴파일러는 버전이 명시된 완전한 현재 모드 컴파일 아티팩트를 직접 생성합니다. 여기에는 순서가 고정된 모듈, 토큰 및 AST, 이름 해석 및 export, 타입 진단 및 프로필 진단, 로어링 결과와 런타임 요구 사항, 생성된 Rust 코드, 정확한 호출 출처 및 결과 출처 정보가 포함됩니다. 호스트 어댑터는 해당 정보를 검증하고 디코딩할 뿐, 누락된 컴파일러 결정을 자체적으로 재구성하지 않습니다. 허용된 명령 경로에서는 공유 패키지 호스트와 런타임이 검증된 동일한 아티팩트를 받아 사용합니다.
self의 Rust 코드 생성은 고정점 IR 테이블을 그대로 보존하고 일반 애플리케이션 호스트
파사드만 추가합니다. 이 테이블은 타깃 전용 공유 런타임이 실행합니다. 해당
런타임에는 컴파일러 이미지가 포함되지 않으며, Rust
파서·리졸버·검사기·로어러·생성기를 실행할 수도 없습니다. 네이티브 아티팩트
매니페스트는 선택한 컴파일러와 생성자, 컴파일러 소스 집합 및 타깃 소스 집합,
컴파일 아티팩트, 생성 소스 해시, targetCompilerFallback: false를 기록합니다.
사용할 수 있는 제품 경로
- CLI는 파일 및 패키지의 서식을 맞추고, 검사하고, 테스트하고, 실행하고, 생성 소스를 내보내고, 아티팩트를 빌드합니다.
- 네이티브 빌드는 해당 플랫폼에서 독자적으로 동작하는 실행 파일을 생성합니다.
- Python 빌드는
program.py및topaz_py_rt.py를 생성합니다. 실행하려면 Python 3.11 이상 버전이 필요합니다. - Raw Web 및 Web Worker는 기존 JavaScript 호스트가 사용할 WASM 패키지를 생성합니다.
- Web 애플리케이션은 완전한 관리형 정적 브라우저 아티팩트를 생성합니다.
- HTTP 서비스는 고정된 리스너, 요청, 대기열, 타임아웃, 로그, 종료 설정을 갖춘 관리형 네이티브 HTTP/1.1 프로세스를 생성합니다.
- 패키지 명령은 매니페스트, 잠금 파일, 경로 의존성, 검사된 로컬 벤더 의존성을 활용합니다.
topaz lispex embed run은 설치 바이너리의 평가기로 선언된 리소스 한도에 따라 리스펙스 요청 하나를 실행합니다.topaz lispex embed info --json은 구성 요소, 프로필, 계약, 런타임, 무폴백 식별자를 출력합니다.- 브라우저 플레이그라운드는 네이티브 CLI를 설치하지 않고도 검사와 인터프리터 실행을 체험할 수 있도록 지원합니다.
리스펙스 평가기 실행하기
해당 기능은 지정된 일반 파일 및 경로 4개를 인자로 받습니다. 출력 디렉터리는 미리 생성되어 있으면 안 됩니다.
topaz lispex embed run \
--source rule.lspx \
--input value.lpxvalue \
--limits limits.json \
--output lispex-result평가가 완료되면 result.lpxvalue와 report.json이 생성됩니다. 결정론적
의미 오류나 리소스 임계값 초과의 경우 report.json만 남깁니다. 요청 거부, 계약
실패, 엔진 오류 발생 시에는 출력 디렉터리를 생성하지 않습니다. 커밋되지 않은 결과와 트랜스크립트
바이트는 경계 외부로 노출되지 않습니다.
평가기·프로필·런타임 정책·수용 조건은 설치된 아티팩트에 고정됩니다. 평가기·프로필 선택기, 사이드카 다운로드, 콜백, 임포트, 폴백은 없습니다. 보고서에는 토파즈 실행과 수용 결과가 기록되며, 이식 가능한 리스펙스 형식 코어는 애플리케이션 아티팩트 API가 생성합니다. 두 경계 간 차이점은 리스펙스 평가기와 LIT에서 확인하세요.
잠긴 std.lispex 완전한 현재 프로필 API는 인터프리터와 다섯 네이티브 릴리스
타깃에서 실행됩니다. 매니페스트, 잠금, 빌드, 아티팩트, 재실행 워크플로는
리스펙스 규칙 실행하기를
참조하세요. generated-python, raw-web, worker-web, managed-web,
http-service, no-capability, mcp-empty-component-set 경로는 출력이나 실행
전에 거부합니다. 폴백은 없습니다.
컴파일러 관찰 자료 살펴보기
설치된 컴파일러 관측 결과 캡처하기
설치된 CLI는 현재 검사 컴파일러 파이프라인의 상태를 기록할 수 있습니다. 생성된 Rust 소스 단계까지의 내역을 단일 정본 관리형 번들로 묶어 제공합니다.
topaz compiler observe --root my-app --locked --out-dir compiler-observation
topaz compiler validate compiler-observation출력 경로는 my-app 외부에 지정하세요. 패키지 내부에 둘 경우, 다음 관찰 수행 시 관리형 출력
디렉터리 자체가 패키지 구성 정보로 오인될 수 있습니다. 번들에는 정확한 소스
바이트 및 소스 집합, 원시 토큰과 레이아웃 토큰, AST, 이름 해석, 구조화된 타입,
호출, 클로저 캡처, 소스 독립적 로어링, 런타임 연산, 생성된 Rust 코드, 진단,
요청, 응답, 출처 정보가 포함됩니다. 해당 번들은 소스 패키지와 동일한 보안 수준으로
보호하세요.
관측 결과 번들 검증하기
validate 명령은 읽기 전용입니다. 재컴파일을 수행하지 않으며 원본 소스 트리를 참조하지도
않습니다. 정본 인코딩, 스키마, 순서, 상호 참조, 완전성, 크기, 해시값만
검증합니다. 출처 정보에는 생성자가 Rust Stage 0으로 명시됩니다. 이는 이 관찰
경로의 구성 방식을 설명할 뿐, 다른 컴파일러 단계가 어떤 언어로 구현되었는지를 의미하지는
않습니다.
비교 경계 파악하기
비교 경계는 의미론적 관찰, 진단 정보, 생성 소스, 생성 아티팩트의 동작, 출처 정보를 각각 독립적으로
검증합니다. 명시된 다중 모듈 사례 및 검사 거부 사례에서 Rust Stage 0와 Stage 1
Preview의 실행 결과가 일치합니다. 명시된 비교 제품에서 링크 방식과 인터프리터 방식의
Stage 1 경로는 동일한 Rust 소스를 생성하고, Stage 0와 Stage 1이 생성한 Rust 소스는
서로 다릅니다. 컴파일한 Stage 1 제품은 정확히 42를 출력합니다. 잘못된 생성자
식별자나 손상된 관리형 Stage 1 아티팩트는 타깃을 Stage 0로 재시도하지 않고 거부됩니다.
저장소 복제 없이 비교하기
설치된 아티팩트만으로 저장소를 클론하지 않고 정확한 비교 검증을 수행할 수 있습니다.
topaz compiler observe main.tpz --terminal rust-source --out-dir rust-observation
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate rust-observation
topaz compiler validate stage1-observation
topaz compiler compare --layer semantic rust-observation stage1-observation두 개의 관리형 관측 번들을 생성한 이후에는 검사 및 비교 과정에서 원본 타깃 소스를 다시 읽지
않습니다. Stage 1 작업이 요청을 거부하거나 오류로 중단되는 경우 그대로 실패하며, 다른 관측
번들로 대체하지 않습니다. 이 경우 별도의 compiler observe 복구 명령을 안내할 뿐
자동으로 실행하지는 않습니다. Rust Stage 0 구동이 필요한 경우 일반 check 또는 빌드
명령 수행 시 --compiler rust 옵션을 직접 지정하세요.
비교 경계 선택하기
두 개의 완전한 관찰 번들을 비교할 때는 검증하고자 하는 목적에 맞는 계층 경계를 선택하세요.
topaz compiler compare --layer semantic observation-a observation-b
topaz compiler compare --layer generated-source observation-a observation-b
topaz compiler compare --layer provenance observation-a observation-b
topaz compiler compare --layer native-binary program-a program-b해당 명령은 규격화된 크기의 단일 JSON 레코드를 출력합니다. 선택한 계층의 정보가 서로 다르면 오류 상태로 종료됩니다. 의미론적 비교는 처음으로 불일치가 발생한 컴파일러 단계에서 구동을 중단합니다. 생성 소스와 출처 정보는 상호 독립적이므로, 생성자 식별자가 변경되었다고 해서 언어의 의미론적 명세가 어긋난 것은 아닙니다.
선택에 필요한 제한
모든 타깃은 파싱, 모듈 해석, 정적 검사 단계를 공유합니다. 그러나 호스트에
의존하는 연산을 모든 타깃에서 지원하는 것은 아닙니다. 특정 연산을 동일하게
유지할 수 없는 타깃은 아티팩트를 생성하기 전에 해당 연산을 거부해야 합니다. 특히 생성된
Python 코드는 fixed-Huffman DEFLATE, 고정 zlib, RS(255,223) 헬퍼, 변환 함수 toFloat와
toIntRadix, Regex 메서드 find와 findAll, 그리고 Date, BigInt, Decimal의 멤버를
사용하는 프로그램을 아티팩트를 쓰기 전에 거부합니다. 거부는 TPZ6PY0001 진단으로 소스
위치와 함께 보고되며, 정확한 멤버 목록은 Python 백엔드 문서에
있습니다. 바이너리 미디어, 달력 날짜, 임의 정밀도 숫자를 다루는 프로그램은 타깃을 선택하기
전에 백엔드 문서를 확인하세요.
HTTP 제품은 고정된 리스너, 요청, 대기열, 타임아웃, 로그, 종료 제어를 갖춘 관리형 HTTP/1.1을 구현합니다. TLS, HTTP/2, WebSocket, 아웃바운드 네트워크 액세스, 주변 환경 권한, 공유 가변 토파즈 상태, 범용 Web 프레임워크는 이 제품의 구성 요소가 아닙니다.
Web 애플리케이션 호스트는 선언된 브라우저 권한을 사용합니다. Raw Web과 Worker 아티팩트는 기존 JavaScript 호스트가 필요합니다. 브라우저 플레이그라운드는 소스를 실행하며, 배포 동작은 생성 제품을 소스 작업 공간 밖에서 실행해 확인합니다.
동시 실행 작업의 수행 순서는 지정되어 있지 않습니다. 순서가 있는 출력은 작업을 합류한 뒤 생성하세요.
설치 평가기는 topaz lispex embed를 처리하며, 토파즈 타깃 선택은 별도 표면입니다.
--target lispex는 산출물 출력 전에 거부됩니다. LIT는 하나의 소스 계보에서 실행되는
리스펙스 테스트·통합 표면으로, 설치 평가기와 출력 백엔드와 구분됩니다.
권장 작업 순서
fmt --check, check, test 순으로 검사를 시작하세요. 명령형 애플리케이션은 run으로,
Web 애플리케이션 또는 HTTP 서비스는 dev 명령으로 확인하세요. 실제 배포 타깃만
빌드하고, 배포 시에는 관리 타깃 디렉터리 전체를 복사하세요.