ADL Manual & Reference

1. File Structure

An ADL file contains blocks starting with keywords. Blocks can appear in any order except meta, which must be first.

• meta: — file metadata (must be first)
• topology database/frontend: — infrastructure configuration
• entity User: — entity definition
• relation UserPosts: — relationship between entities
• authority Admin: — authority definition
• contract NameRequired: — contract/invariant
• operation CreateUser: — operation definition
• service AppService: — service declaration
• page / component / workflow: — UI and workflow blocks

2. Meta Block

meta:
  version: "2.0"
  domain: "myapp"
  @description: "What this does"

domain becomes your Rust crate name and database name. Must be lowercase letters and underscores.

3. Topology

topology database: { kind: "postgresql", port: 5432 }
topology frontend: { kind: "react-app", port: 3000 }
topology cache: { kind: "redis", port: 6379 }

4. Entities

entity User:
  field id: { type: u64, @primary_key, @auto_increment }
  field username: { type: string, @required, @unique, @max_length: 64 }
  field email: { type: string, @required, @max_length: 256 }
  field age: { type: u32, @min: 0, @max: 150 }
  field role: { type: string, @enum: "admin,user,guest", @default: "user" }
  field is_active: { type: bool, @default: true }
  field metadata: { type: json }
  field embedding: { type: vector_f32, @dims: 1024 }
  field created_at: { type: timestamp }

Every entity MUST have exactly one field with @primary_key. Field and entity names must be valid identifiers.

5. All Field Types

decimal maps to rust_decimal::Decimal on postgresql/mysql and f64 (column REAL) on sqlite.

6. Field Annotations

Both the brace form and the shorthand form are supported and semantically identical:

entity Item:
  field id: { type: u64, @primary_key, @auto_increment }   # brace form
  field name: string @required @max_length: 255            # shorthand
  field done: bool @default: false                         # shorthand
  field note: string                                       # bare shorthand

7. Operations

Full operation shape:

operation CreateUser:
  input: "username:string,email:string,age:u32"
  output: "User"
  authority_required: 2
  bindings: "department:Department@dept_id"
  guard: "req.age >= 18"
  validate: "req.email.contains('@')"
  create: "User username=req.username,email=req.email,age=req.age"
  side_effects: "user_created,email_sent"
  rate_limit: "100/m"
  audit: true

V18 autonomous operations: name read-style operations List*, Get*, or Find* — DIS synthesizes them automatically. Do not use Read*.

8. Guards & Mutations

Declarative operation logic (DIS 0.5.12+):

operation AdjustBalance:
  input: "id:u64, delta:i64"
  output: "Account"
  bindings: "account:Account@id"
  guard: "account.status == 'active'"
  mutate: "account.balance += req.delta"

• bindings fetches the row first.
• guard emits a contract assertion that aborts on false.
• mutate supports = += -= *= /=; entity mutations persist via update_<entity>_where.
• req.X must be an input field; binding fields use the alias (account.balance).

8b. Business-Process Semantics (V18.8)

ADL now expresses behavior, not just structure. These compile to enforced runtime logic — each verified with cargo check 0 errors on generated projects:

operation ProcessPayment:
  input: "order_id:u64, amount:decimal, method:string"
  output: "Payment"
  validate: "req.amount == order.total"
  create: "Payment order_id=req.order_id, amount=req.amount, method=req.method"

entity TimeEntry:
  field id: u64 @primary_key @auto_increment
  field started_at: timestamp @required
  field ended_at: timestamp @required
  field duration_minutes: u64 @derived: "(ended_at - started_at).num_minutes()"

entity Product:
  field id: u64 @primary_key @auto_increment
  field name: string @required
  field initial_quantity: u64 @required
  @after_create: "Inventory product_id=self.id, quantity_available=req.initial_quantity"

entity Order:
  field id: u64 @primary_key @auto_increment
  field status: string @required @default: "pending"
    @state_machine: "pending:paid,cancelled|paid:picking|picking:picked|picked:shipped|shipped:delivered|delivered:refunded"

entity Project:
  field id: u64 @primary_key @auto_increment
  field name: string @required
  field spent: decimal @rollup: "sum(Task.actual_hours)"
  field task_count: u64 @rollup: "count(Task)"

operation MarkShipped:
  input: "id:u64"
  output: "Order"
  mutate: "order.status = 'shipped'"
  notify: "order.shipped:shipped_template"

9. Relations

relation UserPosts:
  from: "User"
  to: "Post"
  kind: "HAS_MANY"
  foreign_key_field: "owner_id"
  cascade_delete: true

All 29 relation kinds: HAS_MANY, BELONGS_TO, REFERENCES, OWNS, EXTENDS, IMPLEMENTS, PROVIDES, REQUIRES, CONSUMES, EMITS, GOVERNS, CONDITIONS, DEPENDS_ON, VETOES, GUARANTEES, INVARIANT, CONSTRAINT, AUTHORIZES, DELEGATES, ESCALATES, OBSERVES, AUDITS, WITNESSES, REPLICATES, EVALUATES, BINDS_TO, OPERATES_ON, CALLS, ACCESSES.

10. Authorities

authority Admin:
  level: Founder
  hard_veto: true
  scope: "Global"
  can_execute: "CreateUser,DeleteUser"
  can_govern: "CreateUser"
  can_veto: "DeleteUser"
  delegates: "Moderator"

Levels: Founder (4) full control, Governor (3), Operator (2), Observer (1) read-only, None (0). Delegation chains inherit downward; hard veto stops execution regardless of higher authorities.

11. Contracts

contract NameRequired:
  scope: "CreateUser,UpdateUser"
  invariant: "req.name.length() > 0"
  enforcement: "pre_condition"
  on_violation: "abort"
  message: "Name cannot be empty"

Enforcement kinds: pre_condition, post_condition, invariant_check, transaction_boundary, continuous_monitor, audit_replay. Violation responses: abort, revert, escalate, compensate, alert, log_only.

12. Services

service MyService:
  backend: "axum"
  database: "postgresql"
  entities: "User,Post,Comment"
  operations: "CreateUser,CreatePost,DeletePost"
  depends_on: "AuthService"
  auth: "JWT"
  port: 8080
  replicas: 1
  health_check: "/health"

backend: "binary" generates a standalone Rust binary (CLI/agent) instead of an HTTP server — no routes, migrations, or repositories.

13. Workflows, Pages & Components

workflow UserLifecycle:
  steps: "CreateUser,VerifyEmail,ActivateUser"

page Dashboard:
  route: "/dashboard"
  auth_required: 1
  handler: tsx
    export default function Dashboard() {
      return <div>Welcome</div>;
    }

component UserCard:
  props: "name:string,role:string"
  handler: tsx
    export function UserCard({name, role}) {
      return <div>{name} - {role}</div>;
    }

14. DIS Return Codes

15. Caller Context

Operations can reference the authenticated caller in any expression —create, update, mutate, guard, validate, and contracts — with the caller.* shorthand:

operation CreateProject:
  input: "title:string"
  output: "Project"
  create: "Project title=req.title, owner_id=caller.id"
  guard: "caller.role == 'member'"

Operations that reference caller.* require an authenticated request: the generated handler resolves the caller from the Authorization header and unauthenticated callers receive 401. The compiler binds a real Rust local inside execute_<op> — it never emits bare identifiers, so generated code always compiles (fixed in DIS V18.5).

Type adaptation (V18.5.1): caller.* is a string, so assignments and comparisons adapt to the destination. Assigning caller.id to a numeric field emits __caller_id.parse::<i64>().unwrap_or_default() (and f64 / rust_decimal::Decimal — f64 on sqlite — / uuid::Uuid / bool for the matching types; optional fields wrap in Some(...)). Comparing caller.id == req.owner_id or caller.id == 42 parses the caller side to the numeric type, while caller.role == 'member' stays a string comparison.

Multiple guard: / mutate: / call: / notify: lines on one operation are all preserved (V18.5.1) — each becomes its own logic step.

16. Sidecar Code & Custom Overlay

The escape hatch for anything ADL cannot express. Three cooperating mechanisms let you add hand-written code to a generated project and keep it across every regeneration — every agent should know this flow:

1. Custom overlay (whole files). Write a file under generated/custom/ in the workspace; DIS copies it over the fresh generated tree after every recompile and never touches it. External MCP clients land files with put_file(workspace_id, path="generated/custom/x.rs", content) (quarantined under _external_sandbox/) then promote_workspace_file moves it into the overlay.
2. Manual regions. Wrap code inside a generated file with // BEGIN MANUAL: label … // END MANUAL: label (TSX/JSX: {/* BEGIN MANUAL */}). DIS snapshots these blocks before emission and re-injects them after, so the rest of the file stays in sync with the ADL.
3. Raw handlers. A handler: rust block on an operation emits custom code with full access to the request, repository functions, and subject / caller_id.