Reference
Spec at a Glance
Every performative, tier, refusal code, and node type — the quick-reference card for the protocol and the DSL.
Performatives
A closed set of seven on the speaker plane, plus DECIDE on the owner plane. The kernel mnemonic is SEQRD-PC.
| Performative | Endpoint | Side effects | Purpose |
|---|---|---|---|
PROPOSE | Yes | None | Request a preview |
PROPOSAL | response | None | Preview or refusal |
COMMIT | Yes | Yes (idempotent) | Execute a proposal |
QUERY | Yes | None | Read |
STATUS | Yes | None | Check a prior op |
EVENT | Yes | — | Signed webhook |
ROLLBACK | Yes | None | Request a reversal |
DECIDE | owner plane | Authorizes | Approve / reject |
Consequence tiers
| Tier | Behavior | Cooling delay |
|---|---|---|
LOW | Execute immediately | — |
MEDIUM | Execute + notify owner | — |
HIGH | Park pending approval | — |
CRITICAL | Approve + delay | 300 s |
Reversibility tiers
| Tier | Meaning | Example |
|---|---|---|
REVERSIBLE | Clean inverse exists | create ↔ delete |
COMPENSABLE | Offsetting forward action | payment → refund |
IRREVERSIBLE | No reversal (default for unmarked) | — |
Refusal codes
Returned with 200 OK — a refusal is an outcome, not an error.
| Code | Meaning |
|---|---|
AMBIGUOUS | Multiple candidates (≤8) — ask, don’t guess |
UNRESOLVED | No match for the hint |
INVALID_ARGS | Args fail the profile contract |
POLICY_DENIED | Grant or policy forbids it |
BUDGET_EXHAUSTED | Grant budget spent |
QUOTA_EXHAUSTED | Rate/quota limit reached |
EXPIRED | Proposal or grant expired |
SUSPENDED | Speaker/workspace suspended |
UNSUPPORTED | Verb/feature not supported here |
IRREVERSIBLE | Verb has no reversal |
COMPENSATION_EXPIRED | The token is no longer valid |
DSL node types
| Node | Purpose |
|---|---|
action | Perform a verb (side effects) |
query | Read data |
condition | Branch on a side-effect-free guard |
parallel | Run branches concurrently (join all | any) |
foreach | Iterate a bounded collection |
await_approval | Human-in-the-loop gate |
notify | Send a notification |
wait | Durable delay |
Program envelope
{
"wosool": "0.1",
"workspace": "<workspace-id>",
"locale": "ar",
"entry": "step_1",
"pipeline": [ /* nodes */ ],
"on_error": "halt"
}Data references are backward-only: $.step_N.output.field, which guarantees a DAG. on_error is halt · continue · compensate.
Six Guarantees
| Guarantee | |
|---|---|
| G1 | Default-deny scoped grants |
| G2 | Two-phase: no direct-write |
| G3 | Out-of-band approval, credential-separated |
| G4 | Idempotency with outcome replay |
| G5 | Budgets before side effects, fail-closed |
| G6 | Append-only audit |
Guarantees never weaken across versions
The spec is extracted from running code.
CLI & install
pip install nilscript # core: schemas, docs, CLI — zero deps
pip install "nilscript[sdk]" # + typed Python SDK (httpx + pydantic)
npm install nilscript # spec + JSON Schemas (JS/TS)
nilscript verbs
nilscript profile <verb>
nilscript export-openapi [--format json|yaml] [-o file]