Topazdocs
Обзор

Знакомство с Топазом

Топаз — малый замкнутый язык для замысла приложения: один канонический способ сказать каждую вещь; пишут люди и агенты, проверяет тулчейн.

Топаз — малый замкнутый язык для замысла приложения. Он читается как Python или TypeScript, но держит поверхность намеренно узкой: один канонический способ выразить каждую распространённую вещь, одна поверхность для людей и агентов, одна проверка тулчейном.

Rust остаётся правильным инструментом там, где нужно напрямую договариваться с машиной. Топаз живёт уровнем выше: CLI-процессы, преобразование данных, серверная склейка, логика из конфигурации, оркестрация SQL, shell и путей. Здесь важно не открыть все рычаги, а записать намерение так ясно, чтобы тулчейн мог его выполнить, проверить и скомпилировать в самодостаточный нативный бинарник.

Каждая программа на этой странице, показывающая вывод, выполняется верификатором сайта на реальном тулчейне. Каждый блок вывода обязан байт в байт совпадать с записью запуска. Остальные фрагменты проходят проверку парсером.

Интероп с Lena Code. Топаз входит в семейство продуктов STUDIO HAZE вместе с Lena Code. Эти продукты спроектированы так, чтобы работать вместе: Lena Code может принимать Топаз как входной язык и выдавать Топаз как целевой язык в конвертационных процессах, поэтому код на Топазе естественно проходит через эти процессы и возвращается обратно. Сам Топаз остаётся малым, замкнутым, Unicode-first языком, который люди и ИИ-агенты пишут одинаково, с дифференциальными проверками run/build для поддержанной поверхности.

Первое доказательство: Unicode-first

Идентификаторы — Unicode начиная с лексера. Слова предметной области остаются на вашем языке, а не превращаются в латинизированные приближения:

TOPAZ
function greet(name: string, language: string) -> string {
    return match language {
        case "한국어" => "안녕하세요, {name}님!"
        case "Русский" => "Привет, {name}!"
        case _ => "Hello, {name}!"
    }
}

let 사용자 = "김토파즈"
print(greet(사용자, "한국어"))
print(greet("Topaz", "Русский"))
OUTPUT
안녕하세요, 김토파즈님!
Привет, Topaz!

사용자 — обычная переменная. Unicode-идентичность не терпимый крайний случай. Идентификатор — ровно та последовательность скаляров, которую вы написали, без тихой нормализации (§1), а резолвер модулей отвергает похожие имена модулей между файлами (§17).

Четыре вещи, которые нужно знать

Малая замкнутая поверхность

У каждого намерения один способ записи. Восстановимая ошибка — Result, отсутствие — опционал, очистка — defer, а match рассчитан на исчерпывающее покрытие. Политику фиксирует язык, поэтому каждый файл не становится собственным диалектом.

TOPAZ
function parsePort(raw: string) -> Result<int, string> {
    let n = toInt(raw) ?? -1
    if n < 1 {
        return Err("not a port: {raw}")
    }
    return Ok(n)
}

function startup(raw: string) -> Result<string, string> {
    defer print("config closed")
    let port = parsePort(raw)?
    return Ok("listening on {port}")
}

print("{startup("8080")}")
print("{startup("http")}")
OUTPUT
config closed
Ok(listening on 8080)
config closed
Err(not a port: http)

Оператор ? пробрасывает Err, а defer выполняется на каждом пути выхода. Поэтому config closed появляется в обоих транскриптах.

Готовность к агентам через ограничения

Топаз проектируется для генерируемого кода, но не полагается на осторожность агента. Спецификация мала, запрещённые формы названы, канонические профили проверяются машиной, а примеры на этом сайте верифицируются. Язык для агентов зарабатывает доверие не бесконечной выразительностью, а узкими режимами отказа.

Шаблоны сохраняют намерение

Строки sql, sh и path — это шаблоны. Они остаются структурированными значениями, где части и интерполяции не схлопываются в одну строку:

TOPAZ
let table = "users"
let q = sql"select * from {table} where active = {true}"
print("{q}")
OUTPUT
<sql template, 3 part(s), 2 interpolation(s)>

Этот плейсхолдер — честное состояние сегодня: значение-шаблон существует, ничего не было склеено, а политики рендеринга по доменам пока не специфицированы.

Статика, запуск, проверяемые backend'ы

По спецификации Топаз статически типизирован. Выпущенный чекер типизирует весь компилируемый юнит до запуска:

TOPAZ
type TrafficLight = "red" | "yellow" | "green"

function next(light: TrafficLight) -> TrafficLight {
    return match light {
        case "red" => "green"
        case "green" => "yellow"
        case _ => "red"
    }
}

Интерпретатор — эталон: topaz run разбирает, резолвит, проверяет типы и вычисляет ответ, который тулчейн считает верным. Из того же исходника topaz emit / topaz build понижают программу через два проверяемых backend-пути. Backend Rust создаёт самостоятельный нативный бинарник. Backend Python записывает program.py вместе с рантаймом topaz_py_rt.py для серверной, data и operations-работы.

Ни один backend не получает доверия по намерению. Каждый проверяется против интерпретатора на измеренной поверхности, а release proof фиксирует, где интерпретатор, Rust и Python согласуются. Runtime guards на основе типов переносятся в оба, поэтому скомпилированная программа удерживает поведение, которое видно в playground и интерпретаторе.

SH
topaz build app.tpz --target python --out-dir py-out

Точные гейты и доказательство измеренной поверхности за каждым backend отслеживает страница состояния.

Когда Топаз не подходит

Используйте Rust, C или Zig, если вам нужен прямой контроль ownership и lifetimes, unsafe-границы, embedded-цели, ручная оптимизация горячих мест или полный доступ к системной экосистеме. Узкая дорога Топаза в таких задачах становится настоящей ценой.

Топаз предназначен для другой формы работы: развёртываемая прикладная логика без системной поверхности исходников, предметный язык прямо в коде и малая грамматика, которую люди и агенты могут стабильно производить.

С чего начать

Один способ сказать.