Lispex Vouch

Lispex Vouch не каркас для приложений, а способ прикрепить квитанции к небольшим решающим правилам внутри приложения. Здесь нет экранов, серверов и баз данных. Вы выносите одно решение, которое позже может понадобиться объяснить, записываете его как небольшое правило на Lispex, и каждый записанный ответ получает файл, который можно сверить позже. Программы Lispex по-прежнему выполняет эталонный интерпретатор.

Для каких вопросов это нужно

Некоторые решения, которые принимает ваш код, со временем возвращаются вопросами.

• Поддержка спрашивает, почему заказу отказали в автоматическом возврате. Нужно показать конкретную запись, оставленную для того правила и входных данных три месяца назад.
• Вы хотите изменить правило скидок. Перед мержем хочется получить список заказов прошлого квартала, для которых скидка вышла бы другой.
• Вы сопровождаете правила вроде лимитов одобрения или решений о доступе, где аудит или ревью просит показать основания.

Такие правила обычно занимают крошечную часть кода. Lispex Vouch берёт на себя только её.

Одно правило от начала до конца

Слово «правило» остаётся абстрактным, пока не увидишь его целиком, поэтому вот оно целиком. Пусть возврат одобряется автоматически, если с доставки прошло не больше четырнадцати дней и заказ не вскрыт.

(define (refund-auto-approved? days-since-delivery opened?)
  (and (<= days-since-delivery 14)
       (not opened?)))

(refund-auto-approved? 9 #f)  ; ⇒ #t

Входные данные передаёт хост-приложение, и они фиксируются ровно в переданном виде. Зафиксируйте девять дней с доставки и невскрытый заказ, вычислите, и ответ будет #t. В рабочем процессе Lispex Vouch это вычисление оставляет файл квитанции csk.differential-receipt/v0, в котором правило, зафиксированный вход и ответ записаны вместе с хешами. Закоммитьте квитанцию рядом с правилом, и через три месяца вопрос «почему мы тогда так ответили» начнётся с конкретного файла, а не с чьей-то памяти. Квитанция остаётся записью, а не доказательством. Она показывает, что было записано в момент вычисления, и заслуживает доверия ровно настолько, насколько его заслуживает создавший её процесс. Начиная с v1.3.4 нативный автономный бинарник является публичным путём генерации квитанций.

Это правило можно прямо сейчас вставить в Песочницу. Как выбирать, что выносить в правило, и более реалистичные примеры разобраны в руководстве «Пишем решающие правила».

На какие вопросы отвечают команды Vouch

lispex diff-receipt --input <datum-file> <rule.lspx> генерирует квитанцию в нативном автономном бинарнике. Команда применяет правило к зафиксированным данным и пишет JSON csk.differential-receipt/v0 в stdout.

lispex diff-receipt --input inputs/refund-2026-03-0412.datum rules/refund.lspx > receipts/refund-2026-03-0412.json

lispex verify <receipt> проверяет, что файл квитанции согласован сам с собой. Команда валидирует схему, пересчитывает хеши, записанные в квитанции, а с флагом --source сверяет локальный файл правила с записанным хешем исходника. Запускайте её, когда старая квитанция всплывает в обращении в поддержку, при аудите или передаче дел и нужно убедиться, что файл не изменился. Она работает офлайн, без сети и без сервиса. Она не выполняет вычисление заново и не может сказать, была ли квитанция создана честно, кто применил решение и когда. Пройденная проверка означает, что файл согласован сам с собой и с указанным текстом правила, не больше.

lispex verify receipts/refund-2026-03-0412.json

lispex replay <corpus> --against <version-or-receipts-dir> отвечает на вопрос «если изменить правило, какие прошлые ответы изменятся». Запускайте её перед мержем изменения правила. Она сверяет закоммиченный корпус решений с закреплённой версией или каталогом квитанций и показывает, какие ответы разошлись.

lispex replay decisions/refund --against receipts/2026-Q1

О чём квитанция говорит и о чём молчит

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

Дистрибутив verify и replay в npm проверяет артефакты публичной спецификации. Он сверяет байты и хеши, но не выполняет исходный код Lispex и не заменяет эталонный интерпретатор.

Условия проверяемого подмножества

Всё это работает, только если одно и то же правило на одном и том же входе всегда даёт один и тот же ответ. Поэтому Lispex Vouch действует только на срезе Lispex, закрытом ровно для этого.

• фиксированный набор форм в традиции R7RS, без макросов и скрытого состояния
• закреплённые встроенные процедуры и входные данные, которые явно привязывает хост, а не запрашивает само правило
• квитанции и остальные результаты следуют JSON-контрактам с точностью до байта

Код на Lispex за пределами этих условий тоже прекрасно выполняется. Просто обещание квитанции действует только внутри подмножества.

Что доступно сейчас и что готовится

• Сами правила прямо сейчас вычисляются в Песочнице.
• Нативный автономный бинарник генерирует квитанции командой lispex diff-receipt.
• CLI, устанавливаемый через npm install -g lispex, запускает файлы командой lispex run и проверяет существующие квитанции и корпусы командами lispex verify и lispex replay. Квитанции он не генерирует. Примеры команд есть в «Начале работы».
• Браузерная песочница только выполняет фрагменты кода. Квитанции она не генерирует.
• Публичное зеркало и релизный пакет включают examples/vouch-loop, корпус из одного правила, где генерация, проверка и повторное сравнение запускаются без приватного состояния репозитория.