nudgeDSL Specification

1. What nudgeDSL is

nudgeDSL is a token-dense, human-readable Domain Specific Language for encoding executable intent from LLMs to multi-language backends (Go, Python, Dart).

An agent outputs a nudgeDSL string. A universal parser converts it to a JSON AST. Language-native executors read the AST and run the corresponding functions.

nudgeDSL does not: execute code directly, make network calls, or carry state between turns.

2. Core concepts

Atom

An Atom is a short-code (1–3 uppercase characters) registered by the developer and mapped to a backend function. Atoms are always uppercase. The atom registry is injected into the agent context at runtime.

REGISTRY — the special declaration atom

REGISTRY is a built-in atom that declares which domain registry a document expects. It must appear as the first expression if present. If the loaded registry does not match, the parser returns a RegistryError before evaluating any other atom.

Operator

An Operator encodes the relationship between atoms. Operators are fixed — part of the grammar, not redefinable by developers.

Argument types

v0.1 constraint: Strings cannot contain escaped double quotes. Design atom arguments to avoid this — use single-word identifiers or enum values where possible.

3. Operator table

Precedence (high to low)

1. ** — Amplify — binds tightest, applies to immediately preceding atom only
2. // — Parallel
3. >> — Chain
4. | — Fallback — binds loosest

Use parentheses to override precedence. A() // B() ** 3 is parsed as A() // (B() ** 3) — amplify binds before parallel.

4. EBNF grammar

5. Parallel failure modes

The // operator supports three configurable failure modes. Set at executor registration. Default is fail-fast.

fail-fast (default)

If any branch fails, all remaining branches are aborted immediately. No partial state is applied.

best-effort

All branches execute regardless of individual failures. Errors are collected and returned after all branches complete. Partial state is applied.

compensating

Each atom may declare a rollback atom in the registry. If a branch fails, the executor calls the rollback atom of each already-completed branch. The executor automatically passes the exact same arguments from the forward atom to its rollback atom.

6. JSON AST format

The parser always outputs this structure. Executors consume the AST — never the raw string.

{
  "version": "0.1.0",
  "root": {
    "type": "chain",
    "nodes": [
      {
        "type": "call",
        "atom": "MARK",
        "fn": "UpdateStatus",
        "args": [
          { "type": "string", "value": "task-1" },
          { "type": "string", "value": "done" }
        ]
      },
      {
        "type": "call",
        "atom": "NOTIFY",
        "fn": "BroadcastEvent",
        "args": [
          { "type": "string", "value": "ops" }
        ]
      }
    ]
  }
}

Node types

7. Atom registry format

Developers register atoms before injecting context. The registry is the single source of truth for prompt generation and GBNF grammar compilation.

{
  "domain": "my-project",
  "version": "0.1.0",
  "extends": [],
  "atoms": [
    {
      "atom": "MARK",
      "fn": "UpdateStatus",
      "description": "Transition an item to a new status.",
      "args": [
        { "name": "id", "type": "string" },
        { "name": "status", "type": "string",
          "enum": ["pending", "done", "skipped", "error"] }
      ],
      "rollback": null
    },
    {
      "atom": "HEAL",
      "fn": "HealUnit",
      "description": "Heal the target unit by a percentage of max HP.",
      "args": [
        { "name": "target", "type": "string",
          "enum": ["self", "ally1", "ally2"] },
        { "name": "amount", "type": "float",
          "min": 0.0, "max": 1.0 }
      ],
      "rollback": "UNHEAL"
    }
  ]
}

Arg constraint fields

Rollback signature validation

If an atom declares a rollback, these checks run at registry load time:

• The rollback atom must exist in the same registry
• The rollback atom must declare the same number of arguments as the forward atom
• Each argument must have the same type at the same position

Fail at load time, not at execution time. A misconfigured rollback that surfaces during a compensating transaction is a silent correctness hole.

8. Validation pipeline

Parsing and validation are two separate steps. A string can be syntactically valid and semantically invalid.

raw string
    │
    ▼
[ Parser ]  ──── syntax error ──▶  ParseError
    │
    ▼
  JSON AST
    │
    ▼
[ Semantic Validator ]  ──── constraint violation ──▶  ValidationError
    │
    ▼
[ Executor ]

nudgeDSL ships a DefaultValidator that enforces all registry-declared constraints. Developers may replace or extend it via the Validator interface.

9. Error taxonomy

All errors are structured. The parser and validator never panic.

ParseError codes

ValidationError codes

RegistryError codes

10. Auto-generated agent prompt

nudgeDSL generates the system prompt injection from the atom registry. Agents receive the generated prompt — not this spec.

You are operating with nudgeDSL v0.1.0.
Output ONLY valid nudgeDSL strings. No explanation, no preamble, no markdown.

## Registered Atoms
SHARD(id: string, phase: string)  — Open a shard context.
ACCEPT(criterion: string)  — Add acceptance criterion.
MARK(id: string, status: string)  — Transition item status.
NOTE(text: string)  — Record decision note.

## Operators
>>   chain (sequential)
|    fallback (try left, then right)
//   parallel (concurrent)
**N  amplify (repeat N times)

## Constraints
MARK.status: one of [pending, done, skipped, error, blocked]

Output nudgeDSL only.

11. Worked examples

12. Simulator / CLI

The nudgeDSL simulator takes existing agent output and produces the nudgeDSL equivalent, token comparison, inferred registry, and GBNF grammar.

nudge analyze ./output.json
nudge analyze ./output.py --format python
nudge analyze --stdin

# with custom registries (last-defined wins on conflicts)
nudge analyze ./output.json --registry core.json --registry nudge.json
nudge analyze ./output.json --registry ./atoms.json

Note: savings_percent is always net (output + amortized system prompt). Gross savings are not reported — they are misleading.

13. Versioning

This document is versioned. Breaking changes increment the minor version. The version field in every AST output references this spec version.

Agents and executors must agree on spec version. A mismatch is a runtime error, not a silent failure. Documents using REGISTRY() must declare the domain version — version mismatch returns REGISTRY_MISMATCH before any parsing occurs.

14. What is not in v0.1

These are explicitly out of scope. Do not implement them in v0.1 parsers.

• Variables or state references between atoms ($result >> M($x, $y))
• Conditional branching (IF(cond) >> A() | B())
• Loops with dynamic counts (SHOOT() ** $n)
• Typed return values from atoms
• Multi-agent addressing (@agent1 >> M(3,7))
• Streaming partial AST execution
• Registry inheritance ("extends" field is reserved, must be empty array in v0.1)
• Runtime registry merging beyond last-defined-wins

15. Registry system

nudgeDSL separates the grammar (this spec) from the vocabulary (atom registries). The grammar never changes within a major version. The vocabulary is fully customizable per project.

Three registry layers

Composition rules

• No inheritance — include both files explicitly, no extends logic in v0.1
• Last-defined wins — on atom name conflicts, the last --registry flag wins silently
• Load-time conflict check — signature mismatches (same atom name, different arg count) produce a RegistryError at load time
• REGISTRY() is optional — if omitted, no domain/version check is performed