Syntax Reference

Complete EnsuraScript language syntax reference.

Program Structure

An EnsuraScript program consists of statements:

<statement>*

Statements include:

• Resource declarations
• Ensure statements
• On blocks
• Policy declarations
• Apply statements
• For-each loops
• Invariant blocks
• Violation handlers
• Assumptions

Comments

# This is a comment

Line comments start with # and continue to end of line.

Resource Declarations

Basic Declaration

resource <type> "<path>"

Types: file, directory, http, cron, database, service, process

Examples:

resource file "/etc/app/config.yaml"
resource directory "/var/app/data"
resource http "https://api.example.com"
resource cron "backup_job"

Named Resources (Aliases)

resource <type> "<path>" as <identifier>

Examples:

resource file "/var/app/secrets.db" as secrets
resource http "https://api.example.com/health" as api_health

Reference by alias:

ensure exists on secrets
ensure reachable on api_health

Ensure Statements

Full Syntax

ensure <condition> [on <resource>] [with <handler> <args>] [when <guard>] [requires <condition>] [after <resource>] [before <resource>]

All clauses except <condition> are optional.

Basic Ensure

ensure <condition> on <resource>

Example:

ensure exists on file "config.yaml"

With Handler

ensure <condition> with <handler> <key> "<value>" ... on <resource>

Example:

ensure encrypted with AES:256 key "env:SECRET_KEY" on file "secrets.db"
ensure permissions with posix mode "0600" on file "secrets.db"

When Clause (Guards)

ensure <condition> when <identifier> <op> "<value>"

Operators: ==, !=

Example:

ensure encrypted when environment == "prod"
ensure permissions with posix mode "0644" when environment != "prod"

Requires Clause

ensure <condition-A> requires <condition-B>

Example:

ensure backed_up requires encrypted

After/Before Clauses

ensure <condition> after <resource>
ensure <condition> before <resource>

Examples:

ensure startup on service "app" after file "config.yaml"
ensure exists on file "log.txt" before service "app"

Implicit Subject

Inside an on block, on <resource> can be omitted:

on file "secrets.db" {
  ensure exists          # on file "secrets.db" is implicit
  ensure encrypted       # on file "secrets.db" is implicit
}

On Blocks

Group multiple statements on one resource:

on <resource> {
  <statement>*
}

Example:

on file "secrets.db" {
  ensure exists
  ensure encrypted with AES:256 key "env:SECRET_KEY"
  ensure permissions with posix mode "0600"
}

Policy Declarations

Define reusable guarantee templates:

policy <name>(<param1>, <param2>, ...) {
  <statement>*
}

Example:

policy secure_file(key_ref) {
  ensure encrypted with AES:256 key key_ref
  ensure permissions with posix mode "0600"
}

Apply Statements

Apply a policy:

apply <name>(<arg1>, <arg2>, ...)

Example:

on file "database.db" {
  apply secure_file("env:DB_KEY")
}

For-Each Loops

Iterate over collections:

for each <type> in <container> {
  <statement>*
}

Example:

for each file in directory "/secrets" {
  ensure encrypted with AES:256 key "env:SECRET_KEY"
}

Invariant Blocks

High-priority guarantees:

invariant {
  <statement>*
}

Example:

invariant {
  ensure exists on file "/etc/app/license.key"
}

Violation Handlers

Global

on violation {
  retry <count>
  notify "<target>"
}

Example:

on violation {
  retry 3
  notify "ops-team"
}

Per-Ensure

Place immediately after an ensure statement:

ensure exists on file "critical.db"
on violation {
  retry 10
  notify "critical-alerts"
}

Assumptions

Declare assumed values for guards:

assume <identifier> == "<value>"
assume <simple-statement>

Examples:

assume environment == "prod"
assume filesystem reliable

Parallel Blocks (Parsed, Not Yet Executed)

parallel {
  <statement>*
}

Example:

parallel {
  ensure reachable on http "https://api1.example.com"
  ensure reachable on http "https://api2.example.com"
}

Literals

Strings

"double quoted strings"

Strings can contain spaces, special characters. No escape sequences currently.

Numbers

123
456

Used in retry counts.

Identifiers

myalias
environment
region
feature_flag

Used for resource aliases and guard identifiers.

Keywords

Reserved keywords:

resource, ensure, on, with, requires, after, before
policy, apply, violation, retry, notify
assume, when, for, each, in, invariant, as
key, mode, directory, file, http, database
service, process, cron, environment, parallel

Operators

• == - Equality (guards)
• != - Inequality (guards)
• : - Handler separator (e.g., AES:256)

Complete Example

# Global violation handler
on violation {
  retry 3
  notify "dev-team"
}

# Policy definition
policy secure_file(key_ref) {
  ensure encrypted with AES:256 key key_ref
  ensure permissions with posix mode "0600"
}

# Named resource
resource file "/var/app/database.db" as db

# Invariant with for-each
invariant {
  for each file in directory "/var/app/secrets" {
    apply secure_file("env:SECRET_KEY")
  }
}

# Regular guarantees with guards
on db {
  ensure exists
  apply secure_file("env:DB_KEY") when environment == "prod"
  ensure permissions with posix mode "0644" when environment != "prod"
}

# HTTP monitoring
on http "https://api.production.com/health" {
  ensure reachable
  ensure tls
}
on violation {
  retry 5
  notify "oncall"
}

# Cron scheduling
on cron "daily_backup" {
  ensure scheduled with cron.native 
    schedule "0 2 * * *" 
    command "/usr/local/bin/backup.sh"
}

Grammar (EBNF)

program ::= statement*

statement ::= resource_decl
            | ensure_stmt
            | on_block
            | policy_decl
            | apply_stmt
            | for_each_stmt
            | invariant_block
            | on_violation_block
            | assume_stmt
            | parallel_block

resource_decl ::= "resource" resource_type string ["as" identifier]

ensure_stmt ::= "ensure" condition [ensure_clauses] [on_violation_block]

ensure_clauses ::= ["on" resource_ref] 
                   ["with" handler_spec] 
                   ["when" guard_expr]
                   ["requires" condition]
                   ["after" resource_ref]
                   ["before" resource_ref]

on_block ::= "on" resource_ref "{" statement* "}"

policy_decl ::= "policy" identifier "(" [param_list] ")" "{" statement* "}"

apply_stmt ::= "apply" identifier "(" [arg_list] ")"

for_each_stmt ::= "for" "each" resource_type "in" resource_ref "{" statement* "}"

invariant_block ::= "invariant" "{" statement* "}"

on_violation_block ::= "on" "violation" "{" violation_handler* "}"

violation_handler ::= "retry" number | "notify" string

assume_stmt ::= "assume" (guard_expr | identifier)

parallel_block ::= "parallel" "{" statement* "}"

resource_ref ::= resource_type string | identifier

resource_type ::= "file" | "directory" | "http" | "cron" | "database" | "service" | "process"

handler_spec ::= identifier [":" number] [handler_args]

handler_args ::= (identifier string)*

guard_expr ::= identifier ("==" | "!=") string

condition ::= identifier

param_list ::= identifier ("," identifier)*

arg_list ::= string ("," string)*