이 페이지는 토파즈 v5.17을 설명합니다. 현재 문서로 판단하기 전에 /version.json의 version 값을 5.17과 대조하세요.
토파즈 5.17.0이 현재 제품입니다. 현재 언어 모드는
topaz-5.17입니다.
다음 명령으로 설치 상태를 확인합니다.
topaz version --verbose
이 명령은 컴파일러, 언어 모드, 런타임, Rust 백엔드 식별자를 보여 줍니다. 설치 문제를 알릴 때는 출력 전체를 그대로 첨부하세요.
컴파일러 선택하기
설치된 Stage 2 컴파일러는 지원되는 현재 모드 경로의 기본값입니다. Rust Stage 0는 비교와 복구, 이전 언어 모드와 명시된 호환 경로에서 직접 고를 수 있습니다.
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를 생략하면 self를 고릅니다. 이
경로는 설치된 셀프호스트 컴파일러 이미지를 쓰며, 실패해도 Rust로 다시 시도하지
않습니다. 이 선택을 따르는 경로는 parse, dump-ast, check, 모든
현재 프로필, export
보고서, run, test, bench, 잠긴 패키지, compiler observe, 검사된 boxed
Rust 생성, 네이티브 빌드, Python 소스와 배포 제품, raw Web, worker, Web
애플리케이션, HTTP 서비스, 허용된 Web/서비스 dev, 서식 정리, LSP, 패키지
문서 생성입니다. self 서식 정리와 문서 생성은 선택한 구문·의미 제품을 받아
쓴 다음, Rust 경로와 같은 결정적 출력기와 표현 스키마를 함께 씁니다.
self LSP는 열어 둔 문서 집합에 대해 검증된 그 제품을 만들어 캐시하고, 선언된
모든 메서드에 Rust 컴파일러 단계를 부르지 않고 응답합니다. LSP 프로세스 하나는
컴파일러 선택 하나를 끝까지 유지하니, 설정을 바꾼 뒤에는 편집기
세션을 다시 시작하세요. self 대상 어댑터도 검증된 같은 정보만 받아 씁니다.
산출물에는 topaz-stage2 출처를 기록하고 Rust 대상 프런트엔드는 부르지
않습니다. 이전 언어 모드, 검사 생략, 네이티브 특화와 목록에 표시된 Rust 전용
명령은 선택자를 생략하면 컴파일 작업 전에 Rust 호환 경로로 정해집니다. 지원하지
않는 명시적 self 선택은 소스를 읽거나 출력을 만들기 전에 멈춥니다. 이때 Rust
복구 명령은 대신 실행하지 않고 안내만 합니다.
컴파일러를 쓰는 명령에 --verbose를 붙이면 확정된 선택이 명시적 선택인지,
현재 기본값인지, 호환 선택인지 보여 줍니다.
CLI는 실제 언어 모드를 알 때까지 컴파일러 선택 의도를 보존합니다. 패키지
명령에서는 먼저 루트 topaz.toml만 읽고 검증합니다. 의존성 해석, 잠금 파일
검사, 소스 읽기, 캐시와 출력 작업은 그 뒤에 시작합니다. 이전 언어 모드를
고른 패키지는 선택자를 생략하거나 rust를 직접 고르면 Rust를 씁니다.
self를 직접 고르면 나머지 작업 전에 실패합니다. 이 순서 덕분에 현재 모드의
기본 선택과 명시된 Rust 호환 선택을 서로 다른 결정으로 구분해 관찰할 수 있습니다.
설치된 프로세스는 정확한 불변 셀프호스트 컴파일러 이미지를 한 번만 검증하고 해독한 뒤, 그렇게 준비한 프로그램을 self 컴파일러와 LSP 작업 스레드가 함께 씁니다. 캐시 키에는 이미지, 소스 집합, 스키마, 런타임 템플릿, 도구 모음 식별자가 들어갑니다. 하나라도 맞지 않으면 self 작업이 멈춥니다. 타깃 소스, 진단, 생성 소스와 관리 산출물은 요청마다 다시 계산하며 준비된 컴파일러 상태로 재사용하지 않습니다. 이 준비 과정은 문서에 정한 콜드 시작, LSP와 메모리 한도 안에서 돌아갑니다.
compiler status --json은 기계가 읽을 수 있는 기준 정보를 보여 줍니다. 설치된
생성자, 프로그램 이미지, 소스 집합 식별자, 지원 경로와 거부 경로, 경로별 생략
선택, 기본값, 호환·복구 선택, 무폴백 정책이 여기에 들어갑니다. 관리 산출물은
선택이 명시적이었는지, 현재 기본값이었는지, 호환 선택이었는지도 기록합니다.
설치 제품의 복구 경계
npm으로 설치한 제품도 패키지 검사·선택 테스트·관리형 Python 패키징·소스 없는 실행에서 같은 기본값을 씁니다. 같은 관리 출력에 Rust와 self로 다시 빌드하면 다른 컴파일러의 결과를 재사용하지 않고 출처를 원자적으로 교체합니다.
같은 설치 기본값으로 2모듈 학습 애플리케이션을 검사하고 선택 테스트를 실행한 뒤 네이티브 릴리스 제품으로 패키징해 소스를 지운 상태에서도 실행할 수 있습니다. 현장 장부는 해결된 제품 문제만 닫으며, 더 넓은 컴파일러·통합 검사는 공개 후보에서 수행합니다.
설치된 Stage 1과 Stage 2 경로는 새 소스에서 각각 새 관측을 만들어 검증할 수 있습니다. 이어서 기본 self 경로가 새 네이티브 제품을 만들고 소스 없이 실행합니다. Rust Stage 0 복구는 설치 기본값이 아니라 별도로 고정된 재구성 경로입니다.
정확한 npm 설치 제품은 두 컴파일러 선택을 실행 파일 하나에 담습니다. 저장소를
checkout할 필요가 없습니다. 어느 쪽으로 빌드했든 토파즈 소스를 지운 뒤에도
제품을 실행할 수 있습니다. 설치된 셀프호스트 컴파일러 이미지가 없거나
깨졌다면 self 요청은 그대로 실패합니다. Rust 결과를 가져다 쓰거나 자동으로
다시 시도하는 일은 없습니다. 복구를 직접 선택할 때만 원래 명령을
--compiler rust로 다시
실행하세요. Rust는 언제든 따로 쓸 수 있습니다. 공개된 Stage 0 복구 키트는 자동
폴백이 아니라 따로 실행하는 오프라인 재구성 경로입니다.
설치된 self 컴파일러는 이제 버전이 붙은 완전한 현재 모드 컴파일 제품 하나를 직접 만들어 냅니다. 여기에는 순서가 고정된 모듈, 토큰과 AST, 이름 해석과 export, 타입 진단과 프로필 진단, 하강 결과와 런타임 요구 사항, 생성 Rust, 정확한 호출 출처와 결과 출처가 들어갑니다. 호스트 어댑터는 그 사실을 검증하고 해독할 뿐, 빠진 컴파일러 결정을 스스로 다시 만들지 않습니다. 허용된 명령 경로에서는 공유 패키지 호스트와 런타임이 검증된 같은 제품을 받아 씁니다.
self Rust 생성은 고정점 IR 테이블을 그대로 보존하고 일반 애플리케이션 호스트
facade만 덧붙입니다. 이 테이블은 대상 전용 공유 런타임이 실행합니다. 이
런타임에는 컴파일러 이미지가 들어 있지 않고, Rust
파서·리졸버·검사기·하강기·생성기를 실행할 수도 없습니다. 네이티브 산출물
manifest는 선택한 컴파일러와 생성자, 컴파일러 소스 집합과 대상 소스 집합,
컴파일 제품, 생성 소스 해시, 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은 설치 바이너리에 고정된 정확한 평가기로 한정된 Lispex 요청 하나를 실행합니다.topaz lispex embed info --json은 구성 요소, 프로필, 계약, 런타임, 무폴백 식별자를 보여 줍니다.- 브라우저 플레이그라운드는 네이티브 CLI를 설치하지 않고도 제한된 검사와 인터프리터 실행을 해 볼 수 있게 합니다.
한정된 Lispex 평가기 실행하기
제품은 이름이 있는 일반 파일과 경로 네 개를 받습니다. 출력 디렉터리는 미리 존재하면 안 됩니다.
topaz lispex embed run \
--source rule.lspx \
--input value.lpxvalue \
--limits limits.json \
--output lispex-result
평가가 완료되면 result.lpxvalue와 report.json이 생깁니다. 결정적인
의미 실패나 자원 한계 소진은 report.json만 남깁니다. 요청 거부, 계약
실패, 엔진 실패는 출력 디렉터리를 만들지 않습니다. 확정 전 결과와 전사
바이트는 경계 밖으로 나오지 않습니다.
평가기·프로필·런타임 정책·승인은 설치 제품에 고정됩니다. 평가기나 프로필 선택기, 사이드카 다운로드, 콜백, 임포트, 폴백은 없습니다. 이 보고서는 토파즈 제품 기록이며 이식 가능한 Lispex 제공자 영수증이 아닙니다. 두 경계의 차이는 Lispex 평가기와 LIT에서 확인하세요.
컴파일러 관찰 자료 살펴보기
설치된 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으로 명시합니다. 이는 이 관찰
경로를 설명할 뿐, 다른 컴파일러 단계가 어떤 언어로 작성됐는지는 말하지
않습니다.
명시적인 프리뷰 경로는 토파즈로 작성한 현재의 렉서, 레이아웃 구현, 파서, 논리적 import 폐쇄, 이름 해석기, 정적 검사기를 실행합니다. 이들을 띄우는 쪽은 Rust Stage 0입니다.
topaz compiler preview --root my-app --locked --out-dir typed-preview
topaz compiler validate typed-preview
이 번들은 타입 검사 단계에서 끝납니다. 기록에는 engine: topaz-front-end-preview,
생성·결과 단계 0/0, 부트스트랩 호스트 Rust Stage 0가 남습니다. 토파즈 프런트엔드는
현재 문법과 정본 AST를 다루고, 패키지 의존성과 마운트 의존성, 표준 모듈의
논리적 폐쇄까지 계산합니다. 정확한 스코프와 선언, 참조와 export, 정적 타입과
호출, 캡처, 구조화 진단도 여기서 맡습니다. 소스 사실, AST 노드와 Typed 노드, 노드 깊이,
셸 교환 크기에는 상한이 있습니다. 대상 코드를 하강하거나 생성하거나 빌드하거나
실행하지 않습니다. Stage 1이나 자기 호스팅 컴파일러라는 주장도 아닙니다.
프리뷰가 실패하면 그 자리에서 멈추고 대상 프런트엔드 작업을 Rust로 다시
시도하지 않습니다. 일반 컴파일러 명령은 설치된 경로별 기본값을 따릅니다.
설치 제품은 명시적인 Stage 1 Compiler Preview도 제공합니다.
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate stage1-observation
Stage 1 Preview는 토파즈로 작성한 하강기와 Rust 생성기가 만든 결과를 받아
씁니다. 그 결과는 버전이 붙은 교환 형식과 소스가 없는 비공개 IR입니다.
Preview는 이것만으로 일반 패키지를 컴파일합니다. 이때 대상 Rust 파서, 리졸버,
검사기, 하강기, 생성기, 인터프리터를 링크하지 않고, 실패했을 때 이들을
다시 부르는 일도 없습니다. 관리형 번들은 생성·결과 단계 1/1, 컴파일러 소스
집합, 생성 소스, 런타임 템플릿 식별자, targetCompilerFallback: false를
기록합니다. Stage 2 고정점을 주장하지는 않습니다.
비교 경계는 의미 관찰, 진단, 생성 소스, 생성 제품 동작, 출처를 각각 따로 판정합니다. 선언된 다중 모듈 사례와 검사 거부 사례에서 Rust Stage 0와 Stage 1 Preview의 결과가 일치합니다. Stage 1은 같은 것을 여러 번 생성해도 바이트가 그대로입니다. Stage 0와 Stage 1이 만든 Rust 소스는 서로 다릅니다. 다만 각 생성자 안에서는 결정적이므로 둘을 별도 결과로 기록하고 바이트가 같다는 거짓 주장을 만들지 않습니다. 잘못된 생성자 식별자나 손상된 관리형 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를 직접 지정하세요.
컴파일러가 만든 Rust는 생성자와 빌드 출처를 정본 소스 바이트 바깥에 기록합니다. 이렇게 떼어 놓으면 누가 만들었는지 지우지 않고도 이후 컴파일러 단계에서 생성 소스를 바이트 단위로 비교할 수 있습니다. 설치형 Stage 1 명령은 명시적인 생성자 Preview이며 일반 경로의 기본값과 분리됩니다.
Stage 1을 새로 실행하면 컴파일러 소스가 나옵니다. 고정된 빌드는 그 바이트를 그대로 별도의 설치형 Stage 2 컴파일러 이미지로 만듭니다. 두 세대는 정본 컴파일러 소스가 같아도 manifest와 내장 이미지를 서로 따로 둡니다. 이 빌드 경계만으로 Stage 2를 실행했다거나 고정점에 도달했다고 주장하지는 않습니다.
독립적으로 내장된 Stage 2 이미지는 다음처럼 명시적으로 실행합니다.
topaz compiler preview app/main.tpz \
--producer stage2 \
--terminal rust-source \
--out-dir stage2-observation
entry 경로 없이 --self-source를 쓰면 설치 제품에 들어 있는 컴파일러 소스
세트를 컴파일합니다. 이 명령은 Stage 2 제품 manifest를 쓰며, 다른 컴파일러
생성자나 Rust 대상 front end로 다시 시도하지 않습니다.
고정점 검사는 두 주장을 나눠서 다룹니다. 먼저 연속된 두 셀프호스트 세대가 해석한 컴파일러 프로그램 의미를 비교합니다. 정상 입력 하나와 진단 입력 하나에 대한 정본 관찰도 함께 비교합니다. 그다음 두 세대가 새로 만든 컴파일러 소스를 아무 정규화 없이 원시 바이트로 비교합니다. 두 계층 모두 결과가 같습니다. 이미지와 호출 출처는 서로 달라도 정상입니다. 네이티브 실행 파일 바이트는 이 주장에 넣지 않습니다. 이 결과는 명시적 Preview 컴파일러가 그 경계에서 안정됐다는 뜻입니다. 일반 Stage 2 기본값은 설치된 지원 계약이 별도로 정합니다. 어느 결과도 가능한 모든 컴파일러 동작이 옳다는 증명은 아닙니다.
제한된 실패 canary는 의미 투영, 생성 소스 식별자, Stage 2 출처, 생성자, seed, runtime 경계를 한 번에 하나씩 바꿔 봅니다. 소스 fact가 없을 때나 현재 Preview 경계 밖의 언어 모드를 골랐을 때도 완성된 출력 디렉터리를 확정하기 전에 멈춥니다. 어떤 실패에서도 다른 컴파일러 생성자나 Rust 대상 front end로 다시 시도하지 않습니다.
정확한 로컬 npm 패키지는 대상 소스와 저장소 경로가 없어도 일반 Stage 2 형식과
self-source 형식을 실행합니다. self-source 번들에는
stage2-fixed-point.json이 들어 있습니다. 여기서 의미와 생성 소스 상태는
pass이고 네이티브 바이너리 재현성은 not-run입니다. 오프라인 Stage 0 복구
소스에는 컴파일러 세대 manifest, 고정점 기록, 스키마, 런타임, 고정된 도구
모음 정보가 들어갑니다. 다시 만든 Stage 0는 자동 폴백이 아닙니다. 쓸 때마다
따로 지정해야 하는 엔진으로 남습니다.
완전한 관찰 번들 두 개를 비교할 때는 답을 얻고 싶은 질문에 맞는 경계를 고르세요.
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 레코드 하나를 출력합니다. 선택한 계층이 서로 다르면 실패 상태로 끝납니다. 의미 비교는 처음 달라진 컴파일러 단계에서 멈춥니다. 생성 소스와 출처 정보는 서로 독립적입니다. 그래서 생성자 식별자가 달라졌다고 해서 언어 의미가 어긋난 것은 아닙니다.
Rust Stage 0 기준점 복구
자기 호스팅 자격을 갖춘 릴리스에는 일반 플랫폼 바이너리 다섯 개와 함께 복구 매니페스트와 결정적 소스 아카이브가 따로 들어갑니다. 아카이브는 Rust 컴파일러 소스, 잠금 파일, 벤더 의존성과 라이선스, 런타임 템플릿, 프로토콜 스키마, 컴파일러 작업 부하, 재구성 도구를 고정합니다. 임베드된 토파즈 작성 컴파일러 파일도 따로 검증할 수 있는 소스 집합 하나로 기록합니다. 같은 입력으로 두 번 만들면 아카이브 바이트가 똑같습니다.
복구 세트에는 Rust 도구 모음 자체가 들어 있지 않습니다. 고정된 Rust 도구 모음을 먼저 설치해야 합니다. 그다음부터는 아카이브 안의 벤더 디렉터리만으로 오프라인에서 빌드합니다. 이 경로는 복구와 출처 확인을 따로 하려고 둔 것입니다. 일반 설치 경로가 아니며 Rust 복구 체인이 자기 호스팅된다는 뜻도 아닙니다.
부트스트랩에 적합한 컴파일러 소스 검사
Bootstrap Profile은 컴파일러 커널 소스가 쓸 수 있는 현재 언어의 범위를 기계가 읽을 수 있게 제한합니다. 새 문법이나 방언을 더하지는 않습니다. 잠긴 결정적 패키지는 주변 호스트 권한, extern 모듈, 부동소수점, 동시성, 리소스, 테스트 API, 그 밖의 호스트 의존 연산을 쓰지 않을 때만 통과합니다.
topaz check --profile bootstrap --locked --root compiler-kernel
사람이 읽는 진단에는 안정적인 bootstrap/* 규칙 이름이 나옵니다.
--format json을 쓰면 stderr로는 기계가 읽을 수 있는 프로필 진단이, stdout으로는
요약 하나가 나옵니다. 로컬 값은 철자가 아니라 해석된 식별자로 판정합니다.
그래서 직접 만든 함수의 이름이 print여도 호스트 연산이 되지 않습니다. 거꾸로
금지된 호스트 연산은 이름을 바꾸거나 별칭을 붙여도 숨길 수 없습니다.
선택에 필요한 제한
모든 대상이 파싱, 모듈 해석, 정적 검사를 똑같이 공유합니다. 하지만 호스트에 의존하는 연산까지 어디서나 쓸 수 있는 것은 아닙니다. 어떤 연산을 그대로 보존할 수 없는 대상은 제품을 만들기 전에 그 연산을 거부해야 합니다. 특히 생성 Python은 지금 fixed-Huffman DEFLATE, 고정 zlib, RS(255,223) 도우미를 지원하지 않습니다. 이때는 생성 단계에서 분명하게 실패합니다. 바이너리 미디어를 다룰 때는 대상을 고르기 전에 백엔드 페이지를 확인하세요.
HTTP 제품은 일부러 기능을 좁혀 놓았습니다. TLS, HTTP/2, WebSocket, 아웃바운드 네트워크 접근, 주변 환경 권한, 공유 가변 토파즈 상태, 범용 Web 프레임워크를 더하지 않습니다.
Web 애플리케이션 호스트는 선언한 브라우저 권한만 열어 줍니다. Raw Web과 Worker 제품에는 기존 JavaScript 호스트가 있어야 합니다. 플레이그라운드 실행은 소스를 시험해 보는 것일 뿐, 배포된다는 증거가 아닙니다.
동시에 도는 작업의 실행 순서는 정해 두지 않습니다. 특정 인터리빙에 기대면 안 됩니다.
설치된 한정 평가기는 Lispex 백엔드나 --target lispex가 아니며, 전체 언어
동등성을 확립하지 않습니다. LIT는 이 제품과 별개인 같은 계보의
도그푸딩·통합 경계입니다.
권장 작업 순서
fmt --check, check, test로 시작하세요. 명령형 애플리케이션은 run으로,
Web 애플리케이션이나 HTTP 서비스는 dev로 확인하세요. 실제로 배포할 대상만
빌드하고, 배포할 때는 관리되는 디렉터리 전체를 복사하세요.