# CSL-Core Syntax Specification

This document defines the official syntax, grammar, and semantics for **Chimera Specification Language (CSL-Core)**.

CSL is a domain-specific language (DSL) designed for defining deterministic policies for AI agents. It compiles into an executable Intermediate Representation (IR) verified by Z3.

---

## 1. File Structure

A standard `.csl` file consists of two main blocks:

1. **`CONFIG`** (Optional): Runtime and compiler settings.
2. **`DOMAIN`** (Required): The problem space definitions and constraints.

```csl
CONFIG {
  ENFORCEMENT_MODE: BLOCK
}

DOMAIN MyDomain {
  VARIABLES { ... }
  STATE_CONSTRAINT MyRule { ... }
}
```

---

## 2. Configuration (CONFIG)

The configuration block controls the behavior of the CSL Compiler and Runtime Guard.

| Key | Type | Allowed Values | Default | Description |
|-----|------|----------------|---------|-------------|
| `ENFORCEMENT_MODE` | Enum | `BLOCK`, `WARN`, `LOG` | `BLOCK` | Action to take on violation. |
| `CHECK_LOGICAL_CONSISTENCY` | Bool | `TRUE`, `FALSE` | `TRUE` | Enable Z3 formal verification at compile time. |
| `ENABLE_FORMAL_VERIFICATION` | Bool | `TRUE`, `FALSE` | `FALSE` | (Enterprise) Enable TLA+ engine. |
| `ENABLE_CAUSAL_INFERENCE` | Bool | `TRUE`, `FALSE` | `FALSE` | (Enterprise) Enable Causal Inference engine. |
| `INTEGRATION` | String | `"native"`, `"langchain"` | `"native"` | Integration context metadata. |
| `POLICY_ID` | String | any string | `null` | Stable identity for this policy, independent of the domain name. Stamped onto every `GuardResult` for audit trails. |
| `POLICY_VERSION` | String | any string | `null` | Version of this policy's rules (e.g. `"1.2.0"`). Bump it whenever the policy semantics change. Stamped onto every `GuardResult`. |

`POLICY_ID` and `POLICY_VERSION` are optional and independent of `policy_hash` (which is always computed automatically from the compiled source). Use `policy_hash` to prove *exactly which bytes* produced a decision; use `POLICY_ID`/`POLICY_VERSION` for a human-readable identity across policy revisions.

---

## 3. Domain Definition (DOMAIN)

The `DOMAIN` block encapsulates the context (variables) and the laws (constraints) of your system.

### 3.1 Variable Declarations (VARIABLES)

All variables referenced in constraints must be declared here to pass semantic validation. CSL supports three types of domains:

- **Range (Intervals)**: Defined by `start..end` (inclusive).
- **Set (Enums)**: Defined by explicit values `{ "A", "B" }`.
- **Primitive Types**: `Int`, `Nat`, `BOOLEAN`.

```csl
VARIABLES {
  amount: 0..100000            // Interval
  currency: {"USD", "EUR"}     // Set (String)
  risk_score: 0.0..1.0         // Interval (Float)
  is_verified: BOOLEAN         // Primitive
  kyc_level: Int               // Primitive
}
```

---

## 4. Constraints

Constraints are the core logic units. CSL-Core supports `STATE_CONSTRAINT` (invariants).

**Structure:**

```csl
STATE_CONSTRAINT rule_name {
  WHEN <condition_expression>
  THEN <action_expression>
}
```

### 4.1 Temporal Operators (WHEN Clause)

Defines when a rule applies.

| Operator | Description |
|----------|-------------|
| `WHEN` | Standard trigger. Applies if condition is true in current state. |
| `ALWAYS` | Invariant. Condition is effectively TRUE (applies to all states). |
| `BEFORE` | (Context-dependent) Pre-condition check. |
| `AFTER` | (Context-dependent) Post-condition check. |
| `EVENTUALLY` | (Liveness) Requires condition to be true in a future state. |

### 4.2 Modal Operators (THEN Clause)

Defines the obligation or prohibition.

| Operator | Usage | Logic Equivalent |
|----------|-------|------------------|
| `MUST BE` | `THEN status MUST BE "ACTIVE"` | `status == "ACTIVE"` |
| `MUST NOT BE` | `THEN risk MUST NOT BE "HIGH"` | `risk != "HIGH"` |
| `MAY BE` | `THEN status MAY BE "PENDING"` | (Permissive / No-op) |
| Comparisons | `THEN amount <= 1000` | `amount <= 1000` |

---

## 5. Expressions & Operators

CSL supports standard logic, arithmetic, and comparison operations within expressions.

### 5.1 Binary Operators

- **Logic**: `AND`, `OR`
- **Comparison**: `==`, `!=`, `<`, `>`, `<=`, `>=`
- **Arithmetic**: `+`, `-`, `*`, `/`, `%`

### 5.2 Unary Operators

- **Logic**: `NOT` (e.g., `NOT is_admin`)
- **Arithmetic**: `-` (e.g., `-amount`)

### 5.3 Built-in Functions

Only the following safe, side-effect-free functions are supported in CSL-Core:

- `len(x)`: Length of a string or list.
- `max(a, b)`: Maximum of two values.
- `min(a, b)`: Minimum of two values.
- `abs(x)`: Absolute value.

**Note**: Attempting to call other functions will result in a Compilation Error.

### 5.4 Member Access

Dot notation is supported for accessing nested JSON properties.

```csl
WHEN user.profile.age > 18
```

---

## 6. Lexical Structure

- **Comments**: Support C-style single line `//` and multi-line `/* ... */`.
- **Strings**: Double-quoted `"value"`.
- **Booleans**: Case-insensitive `TRUE`, `FALSE`.
- **Identifiers**: Alphanumeric, must start with a letter (`[a-zA-Z_][a-zA-Z0-9_]*`).

---

## 7. Example Policy

```csl
CONFIG {
  ENFORCEMENT_MODE: BLOCK
}

DOMAIN PaymentGuard {
  VARIABLES {
    action: {"TRANSFER", "REFUND"}
    amount: 0..50000
    user_tier: {"BASIC", "PREMIUM"}
  }

  STATE_CONSTRAINT limit_basic_tier {
    WHEN action == "TRANSFER" AND user_tier == "BASIC"
    THEN amount <= 1000
  }

  STATE_CONSTRAINT no_refund_abuse {
    WHEN action == "REFUND"
    THEN amount MUST NOT BE > 5000
  }
}
```