Capkin Language

Capkin - это Gherkin-compatible protocol DSL для описания CAP machine contracts. Он не расширяет синтаксис Gherkin: .feature файл остается валидным Gherkin, а Capkin добавляет строгую типизацию step text поверх него.

Canonical statement:

Capkin is valid Gherkin + typed protocol expressions + semantic compiler.

Смысловые уровни:

Level 0: Gherkin structure
  Feature / Background / Scenario / Given / When / Then / And

Level 1: Capkin Step Expressions
  typed phrases inside step text

Level 2: Semantic Binder
  principal, capability, guard, state and trace validation

 Level 3: CAP IR / protocol DTO
  executable machine contract

Level 4: Runtime and compiler backends
  Rust runtime, tests, docs, Cucumber, Behave, Reqnroll, Karate, Gauge

В opt-in protobuf binding profile внешняя .proto схема даёт структуру payload и RPC через закреплённые descriptors. Capkin Feature ссылается на смысловые Input/Output порты, а не на имена gRPC методов. Текущий Rust Machine compiler пока хранит Input/Output как имена; ограниченный compile-time binding checker описан в federation.

Core vocabulary:

Machine
Principal
Capability
State
Input
Guard
Transition
Output
Commitment
Trace

Минимальный executable scenario:

Feature: ComplianceGatedSwap

# @registry:CAPKIN-PROTOCOL-001

  Background:
    Given machine ComplianceGatedSwap
    And principal DEX
    And principal Compliance
    And capability DEX may commit SwapInput
    And capability Compliance may evaluate SwapInput
    And capability DEX may commit SwapExecutionOutput

  Scenario: CAPKIN-PROTOCOL-001
    Given DEX commits SwapInput
    When Compliance evaluates guard KycAndRiskPolicy
    Then the machine transitions from Requested to Approved
    And DEX may commit SwapExecutionOutput
    And the trace proof verifies every commitment

Правило MVP: Capkin source не является произвольной документацией. Если step text не мапится в MachineContract, ScenarioContract или Trace expectation, compiler обязан его отклонить. Русский Business Feature приложения находится выше Capkin: его можно создать из свободного текста, автоматически проверить и использовать для генерации черновиков отдельных Machine-контрактов. Это будущий pipeline Allium; сегодняшний Tyapkin compiler не принимает Business Feature напрямую. В базовом machine-v1 заголовок Feature: — синтаксис одной Machine, а не весь Business Feature приложения. В новом opt-in feature-module-v1 несколько строгих Scenario могут собираться в Machine; см. Feature и Machine. В machine-v1 Feature должен совпадать с MachineId, а Scenario должен быть каноническим CAPKIN-* ID с соответствующим # @registry:. Человекочитаемые названия живут в документации и UI-проекции, не внутри исполняемого контракта. Это правило относится к базовому Machine profile. Локальные opt-in Flow, native TypeSpec и type extension profiles имеют собственные закрытые грамматики и компиляторы; их текущий статус описан в Capkin federation. Они не требуются для одной Machine и не расширяют обязательный CAP kernel. Общая граница — малое ядро и расширения. В machine-v1 допускается только служебный комментарий # @registry:<ID>; произвольные комментарии и описания компилятор отклоняет. Компилятор также отклоняет шаг с неверным Given/When/Then/And, повторный legacy Input/Guard/Transition/Output и legacy-шаг, добавленный к aggregation profile без runtime binding.

Gherkin Compatibility

Capkin files are valid Gherkin files:

• standard Gherkin parsers can parse them;
• Feature, Background, Scenario, Given, When, Then, And keep their normal meaning;
• Capkin does not add new Gherkin keywords;
• Capkin is stricter than Gherkin at the semantic layer.

Important distinction:

Gherkin validates structure.
Capkin validates meaning.

Words such as machine, principal, capability, may, commit, evaluates, from, to, every are not Gherkin keywords. They are Capkin Step Expression vocabulary inside ordinary Gherkin step text.

Supported Statements

Протокольный Scenario задаёт один Input, Guard, Transition и Output вместе с явным требованием проверить Trace. Предметные QA-фразы и привязки fixture компилируются в продуктовых профилях; старый aggregation profile живёт в Allium и продолжает читать опубликованные версии.

Feature: <MachineId>
# @registry:<CAPKIN-REGISTRY-ID>
Background:
Given machine <MachineId>
And principal <PrincipalId>
And capability <PrincipalId> may <commit|evaluate> <Resource>
Scenario: <CAPKIN-REGISTRY-ID>
Given <PrincipalId> commits <InputType>
When <PrincipalId> evaluates guard <GuardId>
Then the machine transitions from <State> to <State>
And <PrincipalId> may commit <OutputType>
And the trace proof verifies every commitment

Step Expressions

Capkin Step Expressions are the controlled phrase layer. They are similar in spirit to Cucumber Expressions, but they compile to CAP IR instead of invoking test functions.

Given machine {machine}
And principal {principal}
And capability {principal} may {operation} {resource}
Given {principal} commits {input}
When {principal} evaluates guard {guard}
Then the machine transitions from {state} to {state}
And the trace proof verifies every commitment

Сейчас поддерживается только точная форма every commitment: она компилируется в TraceProofExpectation.VerifyEveryCommitment. Aggregation runner проверяет это требование на непустой CAP commitment chain и сохраняет результат в proof_expectation_valid. Удаление proof-шага теперь ошибка компиляции.

Другие квантификаторы пока проектируются, но компилятором отклоняются:

any commitment
exactly {int} commitments
at least {int} commitments
at most {int} commitments

Не используйте неоднозначные фразы вроде every 5 commitments. Для будущего batch-профиля рассматривается явная форма:

And the trace anchors each batch of 5 commitments

Extension Model

Capkin core stays small. Domain language is added through extensions:

capkin-core:
  Machine, Principal, Capability, State, Input, Guard, Transition, Output,
  Commitment, Trace

capkin-proof:
  verifies every commitment
  anchors each batch of N commitments

capkin-compliance:
  evaluates guard KycAndRiskPolicy
  rejects input when RiskScore exceeds N
  rejects input when wallet is in Badlist

capkin-dex:
  commits SwapInput
  commits SwapExecutionOutput

An extension may add:

• parameter types;
• step expressions;
• semantic validators;
• protobuf message bindings;
• runtime adapters;
• generated fixtures and tests.

Это модель расширений; свободные новые фразы сейчас не регистрируются динамически. Каждая поддержанная форма требует парсера, типизированного IR, валидатора и потребителя в runner/backend. Локальный opt-in kernel profile поддерживает составные Guard outcomes и несколько Output intentions; это не часть базовой Machine grammar. Его возможности и пределы описаны в CAP kernel vNext.

Validation

Compiler rejects:

• unknown Principal;
• missing Capability;
• transition without known states;
• guard without input binding;
• output without commit capability;
• unsupported free-form BDD text.

Важное правило: Machine, Principal и Capability не являются отдельным конфиг-языком рядом с Gherkin. В canonical Capkin они тоже записываются как Gherkin steps внутри Background. Отличие Capkin от свободного Gherkin не в ключевых словах, а в том, что текст каждого шага имеет строгий CAP mapping.