# Agents and prompts
Source: https://docs.aiparlance.org/en/agents

Guide for LLMs writing AI Parlance specs

# Agents and prompts

Guide for LLMs and agents that **write** AI Parlance. Spec: [Specification](/en/specification). Core syntax: [Syntax](/en/syntax).

***

## How the AI should write `.aip`

1. Predictable structure: `app` → `entity` → `crud` → `policy` → `workflow`
2. Clear domain names; one language per file
3. Explicit semantics (`required`, `belongs_to`, policy predicates)
4. Avoid long imperative logic inside `workflow`
5. Do not duplicate `auth` if already on `app`

***

## Minimal prompt → output

**Prompt:**

```txt theme={null}
Create a CRM with users, leads, and tasks.
```

**Expected output:**

```aip theme={null}
app CRM @0.1 {
  database postgres
  auth jwt
}

entity User {
  name: string required
  email: email required unique
}

entity Lead {
  name: string required
  phone: phone required
}

entity Task {
  title: string required
  lead: belongs_to Lead optional
}

crud User
crud Lead
crud Task
```

Add policies and workflows only when the prompt asks for access rules or behavior.

***

## Prompting strategy

Describe: entities, relations, business rules, who can do what.

Avoid asking for: “generate in Go/TypeScript”, framework details, manual route boilerplate.

```txt theme={null}
Domain: [description]
Entities: [fields]
Rules: [validation, duplicates, assignment]
Access: [roles / resource owner]
Events: [what triggers automation]
```

***

## `ai_context`

Semantic context for agents, validators, and RAG — not emitted as target code directly.

```aip theme={null}
ai_context Lead {
  description "
    Leads from the marketing site.
    No duplicate phone numbers after normalization.
    Assign to the first available seller.
  "
}
```

***

## Controlled grammar

Few alternative forms for the same structure — see [grammar](/en/specification#grammar). Prefer inline validation on `entity` over duplicate `validation` blocks.

***

## Agent → software flow

```txt theme={null}
Prompt → LLM → .aip → Validator → AST → Transpilers → artifacts
```

On validation failure, fix `.aip` — not generated Go/TS.

***

## Pre-delivery checklist

* [ ] `app` with `database` and `auth` when using `authenticated` / `role`
* [ ] every referenced `entity` exists
* [ ] `owner_*` policies reference a real FK field
* [ ] `workflow` has `when`
* [ ] `emit` uses declared `event` types
* [ ] canonical modifier order
* [ ] `@0.1` on `app` when using beta blocks

***

## Full reference

[examples/crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) — adapt, do not rewrite from scratch per chapter.

Minimal Core: [examples/minimal.aip](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip).


# Cost impact
Source: https://docs.aiparlance.org/en/cost-impact

Token economics and honest comparisons for AI Parlance

# Development cost impact

This chapter covers the economic argument for AI Parlance. Overview: [Introduction](/en/introduction). Spec: [Specification](/en/specification).

***

## Where cost shows up today

LLMs spend tokens on:

* context from already-generated code (models, handlers, routes, tests)
* fixing cross-layer inconsistencies
* structural repetition for each new endpoint or entity

Most of that is **repeated infrastructure**, not business logic.

***

## Honest comparison (same scope)

Scope: `User` entity with REST CRUD + validation + PostgreSQL migration.

### AI Parlance (source edited by the AI)

```aip theme={null}
app Demo @0.1 {
  database postgres
}

entity User {
  name: string required
  email: email required unique
}

crud User
```

\~6 lines in the spec; `id`, `created_at`, `updated_at` are implicit ([spec](/en/specification#implicit-fields)).

### Go (illustrative transpiler output)

Beyond the struct, a full stack often includes repository, service, handler, routes, validation, and migration — commonly **150–400+ lines** for an idiomatic CRUD.

Token savings are in **generating and reviewing the model** (`.aip`), not transpilation (offline, deterministic).

### TypeScript / Python / PHP

Isolated interfaces or classes are short (\~10–20 lines) but **do not equal** full CRUD — comparing only a struct to `crud User` is misleading.

***

## Smaller context for the AI

Working on `.aip` keeps in context:

* entities and relations
* policies and workflows
* rules in `ai_context`

Instead of thousands of lines of framework-specific implementation.

***

## Multi-target without manual duplication

The same spec in [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) feeds N transpilers — a change to `Lead` propagates to SQL, API, and guards without rewriting each stack.

***

## Financial impact (inference)

Variables: generations per month, average diff size, price per token.

High CRUD / low custom logic → higher ROI.

Heavy UI or unique integrations → smaller gain on the `.aip` layer; AI Parlance does not replace that work.

***

## Limits of the cost argument

* Transpilers must exist and be reliable — upfront engineering cost.
* Complex `workflow` logic can approach imperative code size.
* Future `custom` blocks reintroduce manual code outside compact metrics.

***

## Summary

| Metric                     | Expected effect    |
| -------------------------- | ------------------ |
| Tokens when editing domain | Strong reduction   |
| Architectural consistency  | Improves           |
| Transpilation cost         | Offline, amortized |
| UI / exotic integrations   | Outside main scope |


# Database
Source: https://docs.aiparlance.org/en/database

Infra extensions for schema, migrations, and naming in AI Parlance

# Database

**Infra** extensions on the `entity` model. Base: [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip). Spec: [Specification](/en/specification).

***

## Supported databases (v0.1)

| Database                    | Language (`app`) | Transpiler v0.1                                |
| --------------------------- | ---------------- | ---------------------------------------------- |
| PostgreSQL                  | `postgres`       | Preview (`aip emit sql` — DDL, indexes, seeds) |
| MySQL                       | `mysql`          | Preview (`aip emit mysql`)                     |
| SQLite, MariaDB, MongoDB, … | Roadmap          | —                                              |

PostgreSQL: `aip emit sql`. MySQL: declare `database mysql` and run `aip emit mysql` (see [`examples/mysql-minimal.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/mysql-minimal.aip)). Matrix: [Specification § Transpiler matrix](/en/specification#transpiler-matrix).

```aip theme={null}
app CRM @0.1 {
  database postgres
}
```

***

## Migrations

Generated from `entity` with implicit fields in DDL.

```sql theme={null}
CREATE TABLE users (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL
);
```

***

## `seed`

```aip theme={null}
seed User {
  name: "Administrator"
  email: "admin@example.com"
  role: admin
}
```

***

## Indexes and constraints

```aip theme={null}
index Lead {
  status
  created_at
}
```

| Modifier     | SQL            |
| ------------ | -------------- |
| `required`   | `NOT NULL`     |
| `unique`     | `UNIQUE`       |
| `belongs_to` | `REFERENCES …` |

***

## Naming

| Entity       | Table          | FK               |
| ------------ | -------------- | ---------------- |
| `User`       | `users`        | `user_id`        |
| `SalesOrder` | `sales_orders` | `sales_order_id` |

Rules: lowercase, `snake_case`, plural table names.

***

## UUID and audit

* `id`: `uuid` by default
* `timestamps`: `created_at`, `updated_at`
* `soft_delete`: nullable `deleted_at`

***

## Semantic types → PostgreSQL

| AI Parlance | PostgreSQL              |
| ----------- | ----------------------- |
| `email`     | `TEXT` + app validation |
| `json`      | `JSONB`                 |
| `datetime`  | `TIMESTAMPTZ`           |
| `phone`     | `TEXT` + normalization  |

***

## Flow

```txt theme={null}
entity / index / seed (.aip)
↓
AST
↓
Database Generator
↓
DDL / migrations / ORM
```


# Emitters
Source: https://docs.aiparlance.org/en/emitters

Preview emitters — roles, maturity scores, and how objectives are tested

# Emitters

Official Preview emitters live in the monorepo (`transpilers/`). They share one validated AST from `aip parse` / `aip validate`.

Maturity is tracked in [`EMITTER_OBJECTIVES.md`](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md) (**55** checklist IDs). Each package has a role-aware scorecard: ✅ Pass · ⚠️ Partial · ❌ Fail · ➖ N/A (outside role).

**Score** = ✅ ÷ (55 − ➖).

Each emitter page lists **✅ Passed**, **⚠️ Partial**, and **❌ Still failing** objectives for quick scanning (plus how to re-test).

***

## Scoreboard

| Emitter    | Role       | Score           | Docs                                  |
| ---------- | ---------- | --------------- | ------------------------------------- |
| PostgreSQL | `schema`   | **19/23** (83%) | [sql](/en/emitters/sql)               |
| MySQL      | `schema`   | **14/23** (61%) | [mysql](/en/emitters/mysql)           |
| OpenAPI    | `contract` | **28/33** (85%) | [openapi](/en/emitters/openapi)       |
| TypeScript | `app`      | **36/55** (65%) | [typescript](/en/emitters/typescript) |
| Tests      | `tests`    | **7/18** (39%)  | [tests](/en/emitters/tests)           |
| Docs       | `docs`     | **13/38** (34%) | [docs](/en/emitters/docs)             |
| Go         | `app`      | **12/55** (22%) | [go](/en/emitters/go)                 |
| Python     | `app`      | **12/55** (22%) | [python](/en/emitters/python)         |
| PHP        | `app`      | **11/55** (20%) | [php](/en/emitters/php)               |
| Workers    | `workers`  | **4/20** (20%)  | [workers](/en/emitters/workers)       |

Scored: 2026-08-08 (checklist v2 · D2 deepen).

***

## Roles

| Role       | Meaning                          |
| ---------- | -------------------------------- |
| `schema`   | DDL / durable schema             |
| `contract` | HTTP API contract                |
| `app`      | Application types → runnable API |
| `workers`  | Jobs / queues / workflows        |
| `docs`     | Human-readable reference         |
| `tests`    | Test fixtures / scaffolds        |

Specialized emitters are not expected to Pass HTTP runtime items — those are ➖ N/A.

***

## How objectives are tested

1. **Machine tests** — Vitest in `transpilers/<name>/` (+ repo `scripts/examples.test.ts` for goldens / full-tier smoke).
2. **Manual checklist** — Inspect emit output against each applicable ID in the package [`EMITTER_OBJECTIVES.md`](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md).
3. **Happy path (Phase D)** — Combined TS + OpenAPI + SQL criteria HP1–HP10 on `examples/blog-crud.aip`.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit <target> examples/minimal.aip
node packages/cli/dist/cli.js emit <target> examples/blog-crud.aip
```

Canonical checklist: [GitHub EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md) · Roadmap: [Phase D](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md).


# Docs emitter
Source: https://docs.aiparlance.org/en/emitters/docs

@aiparlance/docs — role docs, score 13/38, pass/partial/fail objectives

# Docs emitter

|           |                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/docs`                                                                                                                  |
| CLI       | `aip emit docs`                                                                                                                     |
| Role      | `docs`                                                                                                                              |
| **Score** | **13/38** (34%)                                                                                                                     |
| Band      | Useful Preview                                                                                                                      |
| Scorecard | [transpilers/docs/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/docs/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 13     | 0          | 25     | 17    |

N/A items are outside the `docs` role and do not affect the score denominator.

## What it produces

Markdown API/domain reference (Pass = documented, not executed).

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A4` | Emit enums / constrained variants from `enum(…)`                      |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete) |
| `D2` | Honor `api.prefix`                                                    |
| `D7` | Honor `api.format` (e.g. JSON)                                        |
| `H1` | Human-readable API / domain documentation                             |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

*No partial items.*

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `A2` | Emit create-input shapes (`EntityCreate` or equivalent)                      |
| `A3` | Emit update-input shapes (`EntityUpdate` or equivalent)                      |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows)                |
| `B1` | Honor `required` / `optional`                                                |
| `B2` | Honor `unique`                                                               |
| `B3` | Apply `validation { }` beyond required folding                               |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly                          |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`)        |
| `E2` | Wire auth into API (security requirements or middleware)                     |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `G1` | Emit `job` artifacts (callable or schedulable)                               |
| `G2` | Emit `queue` declarations / bindings                                         |
| `G3` | Wire workflow `dispatch`                                                     |
| `G4` | Wire workflow `notify`                                                       |
| `G5` | Wire workflow `emit` + `event` types                                         |
| `G6` | Wire `lifecycle` hooks (`on` / `before` / `after`)                           |
| `G7` | Surface `ai_context` (emit, embed, or agent-facing artifact)                 |
| `H2` | Automated test fixtures or scaffolds                                         |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/docs/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/docs/EMITTER_OBJECTIVES.md).

## Tests

Package Vitest Markdown smoke.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit docs examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# Go emitter
Source: https://docs.aiparlance.org/en/emitters/go

@aiparlance/go — role app, score 12/55, pass/partial/fail objectives

# Go emitter

|           |                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/go`                                                                                                                |
| CLI       | `aip emit go`                                                                                                                   |
| Role      | `app`                                                                                                                           |
| **Score** | **12/55** (22%)                                                                                                                 |
| Band      | Stub / early app Preview                                                                                                        |
| Scorecard | [transpilers/go/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/go/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 12     | 6          | 37     | 0     |

N/A items are outside the `app` role and do not affect the score denominator.

## What it produces

Structs + net/http CRUD stubs (501) + presence-only auth middleware.

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A2` | Emit create-input shapes (`EntityCreate` or equivalent)               |
| `A3` | Emit update-input shapes (`EntityUpdate` or equivalent)               |
| `A4` | Emit enums / constrained variants from `enum(…)`                      |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `B1` | Honor `required` / `optional`                                         |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `B3` | Apply `validation { }` beyond required folding                        |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly                   |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete) |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`) |
| `E2` | Wire auth into API (security requirements or middleware)              |
| `F2` | Handlers/jobs perform real work (not only 501 / `throw`)              |

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows)                |
| `B2` | Honor `unique`                                                               |
| `C1` | Durable schema (DDL or ORM / query models)                                   |
| `C2` | Indexes from `index { }`                                                     |
| `C3` | Seeds from `seed { }`                                                        |
| `C4` | Versioned migrations (ordered **up**)                                        |
| `C5` | Migration **down** / rollback                                                |
| `C6` | Respect `app.database` target                                                |
| `C7` | Transactions for multi-statement / workflow writes                           |
| `D2` | Honor `api.prefix`                                                           |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `D7` | Honor `api.format` (e.g. JSON)                                               |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `F1` | Runnable server or worker entrypoint                                         |
| `F3` | DB read/write (or generated query / ORM layer)                               |
| `F4` | Runtime request validation aligned with B\*                                  |
| `F5` | Runtime policy checks aligned with E\*                                       |
| `G1` | Emit `job` artifacts (callable or schedulable)                               |
| `G2` | Emit `queue` declarations / bindings                                         |
| `G3` | Wire workflow `dispatch`                                                     |
| `G4` | Wire workflow `notify`                                                       |
| `G5` | Wire workflow `emit` + `event` types                                         |
| `G6` | Wire `lifecycle` hooks (`on` / `before` / `after`)                           |
| `G7` | Surface `ai_context` (emit, embed, or agent-facing artifact)                 |
| `H1` | Human-readable API / domain documentation                                    |
| `H2` | Automated test fixtures or scaffolds                                         |
| `I1` | Typed API client / SDK (or codegen from the contract)                        |
| `I2` | Contract↔runtime parity story (shared paths/types or CI check)               |
| `J1` | Config/env for DB URL and secrets (no hardcoding)                            |
| `J2` | Minimal observability (request id and/or structured logs)                    |
| `J3` | Health/readiness endpoint or worker liveness hook                            |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/go/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/go/EMITTER_OBJECTIVES.md).

## Tests

Golden `minimal.go` + package tests + examples CI.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit go examples/minimal.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# MySQL emitter
Source: https://docs.aiparlance.org/en/emitters/mysql

@aiparlance/mysql — role schema, score 14/23, pass/partial/fail objectives

# MySQL emitter

|           |                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/mysql`                                                                                                                   |
| CLI       | `aip emit mysql`                                                                                                                      |
| Role      | `schema`                                                                                                                              |
| **Score** | **14/23** (61%)                                                                                                                       |
| Band      | Strong slice                                                                                                                          |
| Scorecard | [transpilers/mysql/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/mysql/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 14     | 2          | 7      | 32    |

N/A items are outside the `schema` role and do not affect the score denominator.

## What it produces

MySQL DDL twin of PostgreSQL (`database mysql` required).

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A4` | Emit enums / constrained variants from `enum(…)`                      |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `B1` | Honor `required` / `optional`                                         |
| `B2` | Honor `unique`                                                        |
| `C1` | Durable schema (DDL or ORM / query models)                            |
| `C2` | Indexes from `index { }`                                              |
| `C3` | Seeds from `seed { }`                                                 |
| `C6` | Respect `app.database` target                                         |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

| ID   | Objective                                                  |
| ---- | ---------------------------------------------------------- |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly        |
| `H4` | Emit succeeds on matching full-tier examples without crash |

## ❌ Still failing (applicable)

| ID   | Objective                                                     |
| ---- | ------------------------------------------------------------- |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows) |
| `B3` | Apply `validation { }` beyond required folding                |
| `C4` | Versioned migrations (ordered **up**)                         |
| `C5` | Migration **down** / rollback                                 |
| `C7` | Transactions for multi-statement / workflow writes            |
| `H1` | Human-readable API / domain documentation                     |
| `H2` | Automated test fixtures or scaffolds                          |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/mysql/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/mysql/EMITTER_OBJECTIVES.md).

## Tests

Package Vitest. Use `examples/mysql-minimal.aip` (throws on postgres apps).

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit mysql examples/mysql-minimal.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# OpenAPI emitter
Source: https://docs.aiparlance.org/en/emitters/openapi

@aiparlance/openapi — role contract, score 28/33, pass/partial/fail objectives

# OpenAPI emitter

|           |                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/openapi`                                                                                                                     |
| CLI       | `aip emit openapi`                                                                                                                        |
| Role      | `contract`                                                                                                                                |
| **Score** | **28/33** (85%)                                                                                                                           |
| Band      | Happy-path ready                                                                                                                          |
| Scorecard | [transpilers/openapi/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-08).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 28     | 0          | 5      | 22    |

## What it produces

OpenAPI 3.0.3 JSON: schemas, CRUD paths, `api.prefix`, auth schemes, per-operation `security` from `policy`, `x-aip-cors` / `x-aip-rate-limit`, soft-delete notes, pagination query params, shared `Error` schema, 409/429.

## ✅ Passed

| ID               | Objective                                                         |
| ---------------- | ----------------------------------------------------------------- |
| `A1`–`A9`        | Entity schemas + soft-delete read semantics in the contract       |
| `B1`, `B2`, `B4` | required/optional, unique→409, `format: email`                    |
| `D1`–`D7`        | CRUD, prefix, cors, rate\_limit, pagination, typed errors, JSON   |
| `E1`–`E6`        | Auth schemes, policy security, owner\_or\_manager scopes, 401/403 |
| `H3`–`H5`        | Goldens / CI / naming                                             |

## ❌ Still failing (applicable)

| ID         | Objective                                                |
| ---------- | -------------------------------------------------------- |
| `B3`       | Richer `validation { }` constraints in schema            |
| `H1`, `H2` | Human docs / fixtures (prefer `docs` / `tests` emitters) |
| `I1`, `I2` | Client SDK emit / full contract↔runtime CI matrix        |

Full scorecard: [transpilers/openapi/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/EMITTER_OBJECTIVES.md).

## Tests

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit openapi examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [Get started here](/en/getting-started)


# PHP emitter
Source: https://docs.aiparlance.org/en/emitters/php

@aiparlance/php — role app, score 11/55, pass/partial/fail objectives

# PHP emitter

|           |                                                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/php`                                                                                                                 |
| CLI       | `aip emit php`                                                                                                                    |
| Role      | `app`                                                                                                                             |
| **Score** | **11/55** (20%)                                                                                                                   |
| Band      | Stub / early app Preview                                                                                                          |
| Scorecard | [transpilers/php/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/php/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 11     | 3          | 41     | 0     |

N/A items are outside the `app` role and do not affect the score denominator.

## What it produces

PHP typed classes; enums currently map to `string`.

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A2` | Emit create-input shapes (`EntityCreate` or equivalent)               |
| `A3` | Emit update-input shapes (`EntityUpdate` or equivalent)               |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `B1` | Honor `required` / `optional`                                         |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

| ID   | Objective                                           |
| ---- | --------------------------------------------------- |
| `A4` | Emit enums / constrained variants from `enum(…)`    |
| `B3` | Apply `validation { }` beyond required folding      |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly |

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows)                |
| `B2` | Honor `unique`                                                               |
| `C1` | Durable schema (DDL or ORM / query models)                                   |
| `C2` | Indexes from `index { }`                                                     |
| `C3` | Seeds from `seed { }`                                                        |
| `C4` | Versioned migrations (ordered **up**)                                        |
| `C5` | Migration **down** / rollback                                                |
| `C6` | Respect `app.database` target                                                |
| `C7` | Transactions for multi-statement / workflow writes                           |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete)        |
| `D2` | Honor `api.prefix`                                                           |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `D7` | Honor `api.format` (e.g. JSON)                                               |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`)        |
| `E2` | Wire auth into API (security requirements or middleware)                     |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `F1` | Runnable server or worker entrypoint                                         |
| `F2` | Handlers/jobs perform real work (not only 501 / `throw`)                     |
| `F3` | DB read/write (or generated query / ORM layer)                               |
| `F4` | Runtime request validation aligned with B\*                                  |
| `F5` | Runtime policy checks aligned with E\*                                       |
| `G1` | Emit `job` artifacts (callable or schedulable)                               |
| `G2` | Emit `queue` declarations / bindings                                         |
| `G3` | Wire workflow `dispatch`                                                     |
| `G4` | Wire workflow `notify`                                                       |
| `G5` | Wire workflow `emit` + `event` types                                         |
| `G6` | Wire `lifecycle` hooks (`on` / `before` / `after`)                           |
| `G7` | Surface `ai_context` (emit, embed, or agent-facing artifact)                 |
| `H1` | Human-readable API / domain documentation                                    |
| `H2` | Automated test fixtures or scaffolds                                         |
| `I1` | Typed API client / SDK (or codegen from the contract)                        |
| `I2` | Contract↔runtime parity story (shared paths/types or CI check)               |
| `J1` | Config/env for DB URL and secrets (no hardcoding)                            |
| `J2` | Minimal observability (request id and/or structured logs)                    |
| `J3` | Health/readiness endpoint or worker liveness hook                            |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/php/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/php/EMITTER_OBJECTIVES.md).

## Tests

Package Vitest emit smoke.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit php examples/minimal.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# Python emitter
Source: https://docs.aiparlance.org/en/emitters/python

@aiparlance/python — role app, score 12/55, pass/partial/fail objectives

# Python emitter

|           |                                                                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/python`                                                                                                                    |
| CLI       | `aip emit python`                                                                                                                       |
| Role      | `app`                                                                                                                                   |
| **Score** | **12/55** (22%)                                                                                                                         |
| Band      | Stub / early app Preview                                                                                                                |
| Scorecard | [transpilers/python/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/python/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 12     | 2          | 41     | 0     |

N/A items are outside the `app` role and do not affect the score denominator.

## What it produces

Python dataclasses (`Entity` / Create / Update) only.

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `A1` | Emit entity shapes (types / structs / schemas / tables) from `entity` |
| `A2` | Emit create-input shapes (`EntityCreate` or equivalent)               |
| `A3` | Emit update-input shapes (`EntityUpdate` or equivalent)               |
| `A4` | Emit enums / constrained variants from `enum(…)`                      |
| `A5` | Emit `belongs_to` as FKs or refs                                      |
| `A6` | Emit implicit `id` primary key                                        |
| `A7` | Emit `timestamps` (`created_at` / `updated_at`)                       |
| `A8` | Emit `soft_delete` field/column (`deleted_at`)                        |
| `B1` | Honor `required` / `optional`                                         |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

| ID   | Objective                                           |
| ---- | --------------------------------------------------- |
| `B3` | Apply `validation { }` beyond required folding      |
| `B4` | Map semantic types (`email`, `phone`, …) distinctly |

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `A9` | Soft-delete **semantics** (default reads filter deleted rows)                |
| `B2` | Honor `unique`                                                               |
| `C1` | Durable schema (DDL or ORM / query models)                                   |
| `C2` | Indexes from `index { }`                                                     |
| `C3` | Seeds from `seed { }`                                                        |
| `C4` | Versioned migrations (ordered **up**)                                        |
| `C5` | Migration **down** / rollback                                                |
| `C6` | Respect `app.database` target                                                |
| `C7` | Transactions for multi-statement / workflow writes                           |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete)        |
| `D2` | Honor `api.prefix`                                                           |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `D7` | Honor `api.format` (e.g. JSON)                                               |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`)        |
| `E2` | Wire auth into API (security requirements or middleware)                     |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `F1` | Runnable server or worker entrypoint                                         |
| `F2` | Handlers/jobs perform real work (not only 501 / `throw`)                     |
| `F3` | DB read/write (or generated query / ORM layer)                               |
| `F4` | Runtime request validation aligned with B\*                                  |
| `F5` | Runtime policy checks aligned with E\*                                       |
| `G1` | Emit `job` artifacts (callable or schedulable)                               |
| `G2` | Emit `queue` declarations / bindings                                         |
| `G3` | Wire workflow `dispatch`                                                     |
| `G4` | Wire workflow `notify`                                                       |
| `G5` | Wire workflow `emit` + `event` types                                         |
| `G6` | Wire `lifecycle` hooks (`on` / `before` / `after`)                           |
| `G7` | Surface `ai_context` (emit, embed, or agent-facing artifact)                 |
| `H1` | Human-readable API / domain documentation                                    |
| `H2` | Automated test fixtures or scaffolds                                         |
| `I1` | Typed API client / SDK (or codegen from the contract)                        |
| `I2` | Contract↔runtime parity story (shared paths/types or CI check)               |
| `J1` | Config/env for DB URL and secrets (no hardcoding)                            |
| `J2` | Minimal observability (request id and/or structured logs)                    |
| `J3` | Health/readiness endpoint or worker liveness hook                            |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/python/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/python/EMITTER_OBJECTIVES.md).

## Tests

Package Vitest emit snapshots/smoke.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit python examples/minimal.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# PostgreSQL emitter
Source: https://docs.aiparlance.org/en/emitters/sql

@aiparlance/sql — role schema, score 19/23, pass/partial/fail objectives

# PostgreSQL emitter

|           |                                                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/sql`                                                                                                                 |
| CLI       | `aip emit sql`                                                                                                                    |
| Role      | `schema`                                                                                                                          |
| **Score** | **19/23** (83%)                                                                                                                   |
| Band      | Happy-path ready                                                                                                                  |
| Scorecard | [transpilers/sql/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/sql/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-08).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 19     | 0          | 4      | 32    |

## What it produces

PostgreSQL DDL: `CREATE TABLE`, indexes, seeds, `email` as `CITEXT`, soft-delete `{table}_active` views, and versioned init migrations (`0001_init.up/down` via `aip emit sql --migrations`).

## ✅ Passed

| ID               | Objective                                                            |
| ---------------- | -------------------------------------------------------------------- |
| `A1`, `A4`–`A9`  | Tables, enums, FKs, id/timestamps, soft-delete column + active views |
| `B1`, `B2`, `B4` | NOT NULL, UNIQUE, `email` → CITEXT                                   |
| `C1`–`C6`        | DDL, indexes, seeds, up/down migrations, postgres target             |
| `H3`–`H5`        | Goldens / CI / naming                                                |

## ❌ Still failing (applicable)

| ID         | Objective                                           |
| ---------- | --------------------------------------------------- |
| `B3`       | CHECKs from `validation { }` beyond UNIQUE/required |
| `C7`       | Transactions for multi-statement / workflow writes  |
| `H1`, `H2` | COMMENT ON / fixture SQL                            |

Full scorecard: [transpilers/sql/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/sql/EMITTER_OBJECTIVES.md).

## Tests

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit sql examples/blog-crud.aip
node packages/cli/dist/cli.js emit sql --migrations examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [Get started here](/en/getting-started)


# Tests emitter
Source: https://docs.aiparlance.org/en/emitters/tests

@aiparlance/tests — role tests, score 7/18, pass/partial/fail objectives

# Tests emitter

|           |                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/tests`                                                                                                                   |
| CLI       | `aip emit tests`                                                                                                                      |
| Role      | `tests`                                                                                                                               |
| **Score** | **7/18** (39%)                                                                                                                        |
| Band      | Useful Preview                                                                                                                        |
| Scorecard | [transpilers/tests/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/tests/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 7      | 0          | 11     | 37    |

N/A items are outside the `tests` role and do not affect the score denominator.

## What it produces

Vitest-style CRUD path fixtures (Pass = fixture coverage).

## ✅ Passed

| ID   | Objective                                                             |
| ---- | --------------------------------------------------------------------- |
| `D1` | Full CRUD surface for `crud` entities (list/create/get/update/delete) |
| `D2` | Honor `api.prefix`                                                    |
| `D7` | Honor `api.format` (e.g. JSON)                                        |
| `H2` | Automated test fixtures or scaffolds                                  |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)                      |
| `H4` | Emit succeeds on matching full-tier examples without crash            |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case)         |

## ⚠️ Partial

*No partial items.*

## ❌ Still failing (applicable)

| ID   | Objective                                                                    |
| ---- | ---------------------------------------------------------------------------- |
| `D3` | Honor `api.cors` (config or middleware)                                      |
| `D4` | Honor `api.rate_limit` (config or enforcement)                               |
| `D5` | Pagination and/or filter/sort on list                                        |
| `D6` | Typed error responses (4xx/5xx + stable body shape)                          |
| `E1` | Auth scheme from `app.auth` (`jwt` / `api_key` / `session` / `oauth`)        |
| `E2` | Wire auth into API (security requirements or middleware)                     |
| `E3` | Reflect `policy` create/read/update/delete                                   |
| `E4` | Predicates: `public`, `authenticated`, `role(…)`                             |
| `E5` | Predicates: `owner` / `owner_or_manager(…)`                                  |
| `E6` | Consistent **401/403** denial paths (runtime **or** contract documents both) |
| `H1` | Human-readable API / domain documentation                                    |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/tests/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/tests/EMITTER_OBJECTIVES.md).

## Tests

Package Vitest for emitter output shape.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit tests examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# TypeScript emitter
Source: https://docs.aiparlance.org/en/emitters/typescript

@aiparlance/typescript — role app, score 36/55, pass/partial/fail objectives

# TypeScript emitter

|           |                                                                                                                                                 |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/typescript`                                                                                                                        |
| CLI       | `aip emit typescript`                                                                                                                           |
| Role      | `app`                                                                                                                                           |
| **Score** | **36/55** (65%)                                                                                                                                 |
| Band      | Strong slice                                                                                                                                    |
| Scorecard | [transpilers/typescript/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/typescript/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-08).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 36     | 0          | 19     | 0     |

## What it produces

Interfaces, Zod schemas, policy helpers, and a runnable `createCrudApp()` / `listenCrudApp()` with memory or Postgres (`DATABASE_URL`), JWT (`AIP_JWT_SECRET`), CORS, rate limits, unique→409, pagination, and typed errors. Peers: `zod`, `pg`, `jose`.

## ✅ Passed

| ID         | Objective                                                                    |
| ---------- | ---------------------------------------------------------------------------- |
| `A1`–`A9`  | Domain shapes through soft-delete **semantics**                              |
| `B1`–`B4`  | required/optional, unique→409, validation, semantic types                    |
| `D1`–`D7`  | CRUD, prefix, cors, rate\_limit, pagination, typed errors, JSON              |
| `E1`–`E6`  | JWT auth, policy wiring, owner / owner\_or\_manager (admin\|editor), 401/403 |
| `F1`–`F5`  | Runnable CRUD, Postgres or memory, Zod + policy at runtime                   |
| `H3`–`H5`  | Goldens / CI / naming                                                        |
| `J1`, `J3` | Env for DB/JWT/PORT; `/health`                                               |

## ❌ Still failing (applicable)

| ID         | Objective                                                        |
| ---------- | ---------------------------------------------------------------- |
| `C1`–`C7`  | ORM / query layer, indexes/seeds/migrations in-app, transactions |
| `G1`–`G7`  | Behavior (jobs, queues, workflows, lifecycle, ai\_context)       |
| `H1`, `H2` | Human docs / test scaffolds                                      |
| `I1`, `I2` | Client SDK / full contract↔runtime matrix                        |
| `J2`       | Structured logs / request id                                     |

Full scorecard: [transpilers/typescript/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/typescript/EMITTER_OBJECTIVES.md).

## Tests

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit typescript examples/blog-crud.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [Get started here](/en/getting-started)


# Workers emitter
Source: https://docs.aiparlance.org/en/emitters/workers

@aiparlance/workers — role workers, score 4/20, pass/partial/fail objectives

# Workers emitter

|           |                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Package   | `@aiparlance/workers`                                                                                                                     |
| CLI       | `aip emit workers`                                                                                                                        |
| Role      | `workers`                                                                                                                                 |
| **Score** | **4/20** (20%)                                                                                                                            |
| Band      | Stub Preview                                                                                                                              |
| Scorecard | [transpilers/workers/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/workers/EMITTER_OBJECTIVES.md) |

Scored against the master checklist ([55 IDs](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md), v2 · 2026-08-06).

## Summary

| ✅ Pass | ⚠️ Partial | ❌ Fail | ➖ N/A |
| ------ | ---------- | ------ | ----- |
| 4      | 3          | 13     | 35    |

N/A items are outside the `workers` role and do not affect the score denominator.

## What it produces

TS job/queue stubs + `dispatches` edges from workflows.

## ✅ Passed

| ID   | Objective                                                     |
| ---- | ------------------------------------------------------------- |
| `G2` | Emit `queue` declarations / bindings                          |
| `H3` | Golden / CI for `minimal.aip` (or matching twin)              |
| `H4` | Emit succeeds on matching full-tier examples without crash    |
| `H5` | Naming aligned with docs (plural tables, `*_id`, snake\_case) |

## ⚠️ Partial

| ID   | Objective                                                |
| ---- | -------------------------------------------------------- |
| `F2` | Handlers/jobs perform real work (not only 501 / `throw`) |
| `G1` | Emit `job` artifacts (callable or schedulable)           |
| `G3` | Wire workflow `dispatch`                                 |

## ❌ Still failing (applicable)

| ID   | Objective                                                    |
| ---- | ------------------------------------------------------------ |
| `F1` | Runnable server or worker entrypoint                         |
| `F3` | DB read/write (or generated query / ORM layer)               |
| `F4` | Runtime request validation aligned with B\*                  |
| `F5` | Runtime policy checks aligned with E\*                       |
| `G4` | Wire workflow `notify`                                       |
| `G5` | Wire workflow `emit` + `event` types                         |
| `G6` | Wire `lifecycle` hooks (`on` / `before` / `after`)           |
| `G7` | Surface `ai_context` (emit, embed, or agent-facing artifact) |
| `H1` | Human-readable API / domain documentation                    |
| `H2` | Automated test fixtures or scaffolds                         |
| `J1` | Config/env for DB URL and secrets (no hardcoding)            |
| `J2` | Minimal observability (request id and/or structured logs)    |
| `J3` | Health/readiness endpoint or worker liveness hook            |

Full ID-by-ID scorecard (including ➖ N/A): [transpilers/workers/EMITTER\_OBJECTIVES.md](https://github.com/eudameron/aiparlance/blob/main/transpilers/workers/EMITTER_OBJECTIVES.md).

## Tests

Fixture vs `ops-reference.aip`; package tests.

```bash theme={null}
npm test
node packages/cli/dist/cli.js emit workers examples/ops-reference.aip
```

## Related

* [Emitters overview](/en/emitters)
* [Master EMITTER\_OBJECTIVES](https://github.com/eudameron/aiparlance/blob/main/EMITTER_OBJECTIVES.md)
* [First emitters](/en/first-transpiler)
* [Get started here](/en/getting-started)


# Examples
Source: https://docs.aiparlance.org/en/examples

Reference .aip specs in the monorepo — Core smoke to full-tier CRUD

# Examples

All reference specs live in [`examples/`](https://github.com/eudameron/aiparlance/tree/main/examples) and are validated by CI (`npm test` / `scripts/examples.test.ts`).

| Spec                                                                                                  | Focus                                 | Doc page                                      |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------- |
| [`minimal.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip)               | Smallest Core smoke + emitter goldens | [Minimal](/en/examples/minimal)               |
| [`blog-crud.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/blog-crud.aip)           | Complete blog CRUD                    | [Blog CRUD](/en/examples/blog-crud)           |
| [`inventory-crud.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/inventory-crud.aip) | Inventory + jobs / queues             | [Inventory CRUD](/en/examples/inventory-crud) |
| [`mysql-minimal.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/mysql-minimal.aip)   | MySQL (`aip emit mysql`)              | [MySQL minimal](/en/examples/mysql-minimal)   |
| [`crm-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip)   | CRM — policies, API, workflows        | [CRM reference](/en/examples/crm-reference)   |
| [`ops-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip)   | Seed, lifecycle, jobs, `ai_context`   | [Ops reference](/en/examples/ops-reference)   |

Tutorial that walks through the blog spec: [CRUD walkthrough](/en/crud-walkthrough).

```bash theme={null}
node packages/cli/dist/cli.js validate examples/minimal.aip
node packages/cli/dist/cli.js emit sql examples/blog-crud.aip
node packages/cli/dist/cli.js emit mysql examples/mysql-minimal.aip
node packages/cli/dist/cli.js emit workers examples/inventory-crud.aip
```


# Blog CRUD
Source: https://docs.aiparlance.org/en/examples/blog-crud

Complete blog CRUD — entities, policies, API, seed, workflow

# Blog CRUD

[`examples/blog-crud.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/blog-crud.aip) — Author / Post / Comment with validation, policies, indexes, `/v1` API, seed, and a light workflow.

**Tiers:** Core + Infra + Security + Behavior (light).\
**Walkthrough:** [CRUD walkthrough](/en/crud-walkthrough).

```bash theme={null}
node packages/cli/dist/cli.js validate examples/blog-crud.aip
node packages/cli/dist/cli.js emit sql examples/blog-crud.aip
node packages/cli/dist/cli.js emit openapi examples/blog-crud.aip
node packages/cli/dist/cli.js emit tests examples/blog-crud.aip
```

```aip theme={null}
// AI Parlance — complete blog CRUD (Core + Infra + Security + light Behavior)
// Walkthrough: docs/en/crud-walkthrough.mdx

app Blog @0.1 {
  database postgres
  auth jwt
}

entity Author {
  timestamps
  soft_delete
  name: string required
  email: email required unique
  role: enum(admin, editor, writer) default(writer)
}

entity Post {
  timestamps
  soft_delete
  title: string required
  slug: string required unique
  body: text required
  status: enum(draft, published, archived) default(draft)
  author: belongs_to Author
}

entity Comment {
  timestamps
  body: text required
  post: belongs_to Post
  author: belongs_to Author optional
}

crud Author
crud Post
crud Comment

validation Post {
  title required
  slug required unique
  body required
}

policy Post {
  create authenticated
  read public
  update owner_or_manager(Post.author)
  delete role(admin)
}

policy Comment {
  create authenticated
  read public
  update owner_or_manager(Comment.author)
  delete role(admin)
}

index Post {
  status
  slug
}

index Comment {
  post
}

api {
  prefix "/v1"
  format json
  rate_limit 120/minute
  cors {
    allow "https://blog.example.com"
  }
}

seed Author {
  name: "Site Admin"
  email: "admin@blog.example.com"
  role: admin
}

workflow PostPublished {
  when Post.updated

  notify(Post.author, "Post status may have changed")
  emit PostStatusChanged {
    post: Post
    author: Post.author
  }
}

event PostStatusChanged {
  post: Post
  author: Author
}
```

See all examples: [Examples](/en/examples).


# CRM reference
Source: https://docs.aiparlance.org/en/examples/crm-reference

Full CRM reference — policies, indexes, API, workflows, events

# CRM reference

[`examples/crm-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) — User / Lead / Task with policies, indexes, `/v1` API, workflow, and domain event.

**Tiers:** Core + Infra + Security + Behavior.

```bash theme={null}
node packages/cli/dist/cli.js validate examples/crm-reference.aip
node packages/cli/dist/cli.js emit openapi examples/crm-reference.aip
node packages/cli/dist/cli.js emit sql examples/crm-reference.aip
```

```aip theme={null}
// AI Parlance reference spec — CRM
// Documented in docs/ (Mintlify). Normative details: spec/v0.1/

app CRM @0.1 {
  database postgres
  auth jwt
}

entity User {
  name: string required
  email: email required unique
  role: enum(admin, manager, seller) default(seller)
  active: bool default(true)
}

entity Lead {
  name: string required
  email: email optional
  phone: phone required
  status: enum(new, assigned, contacted, won, lost) default(new)
  seller: belongs_to User optional
}

entity Task {
  title: string required
  due_at: datetime optional
  lead: belongs_to Lead optional
}

crud User
crud Lead
crud Task

policy Lead {
  create authenticated
  read owner_or_manager(Lead.seller)
  update owner_or_manager(Lead.seller)
  delete role(admin)
}

index Lead {
  status
  phone
}

api {
  prefix "/v1"
  format json
  rate_limit 100/minute
  cors {
    allow "https://app.example.com"
  }
}

workflow LeadReceived {
  when Lead.created

  var seller = available_seller()

  assign Lead.seller seller

  create Task {
    title: "Follow up"
    due_at: now() + 15m
    lead: Lead
  }

  notify(seller, "New lead assigned")

  emit LeadAssigned {
    lead: Lead
    seller: seller
  }
}

event LeadAssigned {
  lead: Lead
  seller: User
}
```

Related: [Security](/en/security) · [Workflows](/en/workflows) · [Examples](/en/examples).


# Inventory CRUD
Source: https://docs.aiparlance.org/en/examples/inventory-crud

Inventory with stock moves, seeds, jobs, and queues

# Inventory CRUD

[`examples/inventory-crud.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/inventory-crud.aip) — Warehouse / Product / StockMove / User with policies, indexes, seeds, lifecycle, job, and queue.

**Tiers:** Core + Infra + Security + Behavior.\
**Try:** `aip emit workers examples/inventory-crud.aip`

```bash theme={null}
node packages/cli/dist/cli.js validate examples/inventory-crud.aip
node packages/cli/dist/cli.js emit sql examples/inventory-crud.aip
node packages/cli/dist/cli.js emit workers examples/inventory-crud.aip
```

```aip theme={null}
// AI Parlance — inventory CRUD with stock moves + worker hooks
// Complements blog-crud.aip; exercises indexes, seeds, jobs/queues

app Inventory @0.1 {
  database postgres
  auth jwt
}

entity Warehouse {
  timestamps
  name: string required
  code: string required unique
}

entity Product {
  timestamps
  soft_delete
  sku: string required unique
  name: string required
  unit_price_cents: int required
  status: enum(active, discontinued) default(active)
}

entity StockMove {
  timestamps
  quantity: int required
  reason: enum(receive, ship, adjust) required
  product: belongs_to Product
  warehouse: belongs_to Warehouse
  actor: belongs_to User optional
}

entity User {
  timestamps
  name: string required
  email: email required unique
  role: enum(admin, manager, clerk) default(clerk)
}

crud Warehouse
crud Product
crud StockMove
crud User

validation Product {
  sku required unique
  name required
}

policy StockMove {
  create authenticated
  read role(manager)
  update role(manager)
  delete role(admin)
}

policy Product {
  create role(manager)
  read authenticated
  update role(manager)
  delete role(admin)
}

index Product {
  sku
  status
}

index StockMove {
  product
  warehouse
}

api {
  prefix "/api"
  format json
  rate_limit 200/minute
}

seed Warehouse {
  name: "Main DC"
  code: "DC-01"
}

seed Product {
  sku: "SKU-100"
  name: "Demo Widget"
  unit_price_cents: 999
  status: active
}

seed User {
  name: "Ops Manager"
  email: "manager@inventory.example.com"
  role: manager
}

queue StockAlerts

job LowStockNotify {
  retries 3
  timeout 2m
}

lifecycle StockMove {
  on created -> workflow StockMoveCreated
}

workflow StockMoveCreated {
  when StockMove.created

  notify(StockMove.actor, "Stock move recorded")
  dispatch LowStockNotify
  emit StockMoved {
    product: StockMove.product
    warehouse: StockMove.warehouse
    quantity: StockMove.quantity
  }
}

event StockMoved {
  product: Product
  warehouse: Warehouse
  quantity: int
}
```

See all examples: [Examples](/en/examples).


# Minimal
Source: https://docs.aiparlance.org/en/examples/minimal

Smallest valid v0.1 Core spec — emitter goldens

# Minimal

[`examples/minimal.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip) — smallest valid Core app: one entity + `crud`. Used for SQL / OpenAPI / TypeScript / Go golden fixtures.

**Tiers:** Core only.

```bash theme={null}
node packages/cli/dist/cli.js validate examples/minimal.aip
node packages/cli/dist/cli.js emit sql examples/minimal.aip
node packages/cli/dist/cli.js emit openapi examples/minimal.aip
node packages/cli/dist/cli.js emit typescript examples/minimal.aip
node packages/cli/dist/cli.js emit go examples/minimal.aip
```

```aip theme={null}
// AI Parlance minimal spec — Core only (v0.1)
// Documented in docs/en/introduction.mdx and docs/pt/introduction.mdx

app Demo @0.1 {
  database postgres
}

entity User {
  name: string required
  email: email required unique
}

crud User
```

See all examples: [Examples](/en/examples).


# MySQL minimal
Source: https://docs.aiparlance.org/en/examples/mysql-minimal

Minimal MySQL fixture for aip emit mysql

# MySQL minimal

[`examples/mysql-minimal.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/mysql-minimal.aip) — small app with `database mysql` for the MySQL Preview emitter.

**Tiers:** Core + Infra (api, seed).\
**Requires:** `database mysql` (PostgreSQL emit targets use other examples).

```bash theme={null}
node packages/cli/dist/cli.js validate examples/mysql-minimal.aip
node packages/cli/dist/cli.js emit mysql examples/mysql-minimal.aip
```

```aip theme={null}
// AI Parlance — minimal MySQL fixture for `aip emit mysql`

app MysqlDemo @0.1 {
  database mysql
  auth api_key
}

entity Item {
  timestamps
  name: string required
  sku: string required unique
  active: bool default(true)
}

crud Item

api {
  prefix "/v1"
  format json
}

seed Item {
  name: "Sample"
  sku: "SKU-1"
  active: true
}
```

See [Database](/en/database) · [Examples](/en/examples).


# Ops reference
Source: https://docs.aiparlance.org/en/examples/ops-reference

Infra + Behavior extras — seed, ai_context, jobs, queues, lifecycle

# Ops reference

[`examples/ops-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip) — complements the CRM reference with seeds, `ai_context`, jobs, queues, and lifecycle hooks.

**Tiers:** Core + Infra + Behavior.\
**CI:** SQL seed inserts are asserted in examples tests.

```bash theme={null}
node packages/cli/dist/cli.js validate examples/ops-reference.aip
node packages/cli/dist/cli.js emit sql examples/ops-reference.aip
node packages/cli/dist/cli.js emit workers examples/ops-reference.aip
```

```aip theme={null}
// AI Parlance ops reference — Infra + Behavior extras (v0.1)
// Complements crm-reference.aip. Normative grammar: spec/v0.1/grammar.ebnf

app OpsDemo @0.1 {
  database postgres
  auth jwt
}

entity User {
  timestamps
  soft_delete
  name: string required
  email: email required unique
  role: enum(admin, seller) default(seller)
}

entity Lead {
  timestamps
  soft_delete
  name: string required
  phone: phone required unique
  seller: belongs_to User optional
}

crud User
crud Lead

validation User {
  name required
  email required unique
}

seed User {
  name: "Administrator"
  email: "admin@example.com"
  role: admin
}

ai_context Lead {
  description "
    Inbound leads. Normalize phone before insert.
    Reject duplicates. Assign first available seller.
  "
}

queue SendEmail

job SendWelcomeEmail {
  retries 3
  timeout 1m
}

job SendReminder {
  retries 2
  timeout 30m
}

lifecycle Lead {
  on created -> workflow LeadIntake
  before create {
    normalize_phone(Lead.phone)
  }
  after update {
    notify(Lead.seller, "Lead updated")
  }
}

workflow LeadIntake {
  when Lead.created

  if LeadExists(Lead.phone) {
    reject "Duplicate lead"
  }

  var seller = available_seller()
  assign Lead.seller seller

  notify(seller, "New lead assigned")
  dispatch SendWelcomeEmail
  dispatch SendReminder after 15m
}

event LeadReady {
  lead: Lead
  seller: User
}
```

Related: [Workflows](/en/workflows) · [Agents](/en/agents) · [Examples](/en/examples).


# First emitters
Source: https://docs.aiparlance.org/en/first-transpiler

Official AI Parlance Preview emitters — PostgreSQL through the full matrix

# First emitters

Phase C of the roadmap delivered the **first official emitters** (transpilers) for AI Parlance. They live in the monorepo as Preview targets — not npm-published packages yet, but real AST → artifact pipelines you can run with `aip emit`. **Phase D** deepens TypeScript, OpenAPI, and PostgreSQL toward a runnable happy path (see [ROADMAP](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md)).

***

## What “first transpiler” means here

Historically, the marketing site only had an **illustrative** playground. The language was specification-only.

With Phase C **M3–M6** and the matrix follow-up, the project ships **ten Preview emitters** from one validated AST:

| Target             | Package                  | CLI                   |
| ------------------ | ------------------------ | --------------------- |
| **PostgreSQL DDL** | `@aiparlance/sql`        | `aip emit sql`        |
| **OpenAPI 3**      | `@aiparlance/openapi`    | `aip emit openapi`    |
| **TypeScript**     | `@aiparlance/typescript` | `aip emit typescript` |
| **Go**             | `@aiparlance/go`         | `aip emit go`         |
| **MySQL DDL**      | `@aiparlance/mysql`      | `aip emit mysql`      |
| **Workers**        | `@aiparlance/workers`    | `aip emit workers`    |
| **Python**         | `@aiparlance/python`     | `aip emit python`     |
| **PHP**            | `@aiparlance/php`        | `aip emit php`        |
| **Docs**           | `@aiparlance/docs`       | `aip emit docs`       |
| **Tests**          | `@aiparlance/tests`      | `aip emit tests`      |

PostgreSQL was the **first** emitter because the docs treat it as the primary SQL target. OpenAPI, TypeScript, and Go completed the first multi-target wave; MySQL and the remaining matrix targets followed as Preview MVPs.

Together with `aip parse` and `aip validate` (Core + Infra + Security + Behavior), this is the **reference toolchain**.

***

## Pipeline

```txt theme={null}
.aip source
  → parse (AST)
  → validate (MUST rules)
  → emit sql | openapi | typescript | go | mysql | workers | python | php | docs | tests
```

One validated spec feeds all Preview emitters. Naming (snake\_case, FK `*_id`, plural tables) stays aligned across SQL targets, OpenAPI, and Go `json` tags.

***

## What each emitter produces

### PostgreSQL (`aip emit sql`)

* `CREATE EXTENSION IF NOT EXISTS pgcrypto`
* `CREATE TABLE` per `entity` (implicit `id`, timestamps; `deleted_at` when `soft_delete`)
* Types, `UNIQUE` / `NOT NULL`, enum `CHECK`s, `belongs_to` foreign keys
* `CREATE INDEX` from `index` blocks; `INSERT` from `seed` blocks

Golden: [`transpilers/sql/fixtures/minimal.sql`](https://github.com/eudameron/aiparlance/blob/main/transpilers/sql/fixtures/minimal.sql)

### OpenAPI 3 (`aip emit openapi`)

* Schemas `Entity` / `EntityCreate` / `EntityUpdate`
* CRUD paths when `crud Entity` is declared (honors `api.prefix`)
* Optional `securitySchemes` from `app.auth`

Golden: [`transpilers/openapi/fixtures/minimal.openapi.json`](https://github.com/eudameron/aiparlance/blob/main/transpilers/openapi/fixtures/minimal.openapi.json)

### TypeScript (`aip emit typescript`)

* Interfaces `Entity` / `EntityCreate` / `EntityUpdate`
* Runtime type guards (`isEntity`, `isEntityCreate`) — zero runtime deps
* Thin `entityPaths` helpers when CRUD is present

### Go (`aip emit go`)

* Structs with `json` tags; thin `net/http` CRUD stubs; `AuthMiddleware` from `app.auth`

### MySQL (`aip emit mysql`)

* MySQL DDL for specs with `database mysql` (see `examples/mysql-minimal.aip`)

### Workers / Python / PHP / Docs / Tests

MVP stubs from jobs/queues, dataclasses, classes, Markdown API refs, and CRUD fixtures — all Preview depth. See the [transpiler matrix](/en/specification#transpiler-matrix).

***

## Try it in one minute

```bash theme={null}
git clone https://github.com/eudameron/aiparlance.git
cd aiparlance && npm ci && npm run build

node packages/cli/dist/cli.js emit sql examples/minimal.aip
node packages/cli/dist/cli.js emit openapi examples/minimal.aip
node packages/cli/dist/cli.js emit typescript examples/minimal.aip
node packages/cli/dist/cli.js emit go examples/minimal.aip
node packages/cli/dist/cli.js emit mysql examples/mysql-minimal.aip
node packages/cli/dist/cli.js emit workers examples/ops-reference.aip
```

Full install and a complete CRUD story: [Get started here](/en/getting-started) · [CRUD walkthrough](/en/crud-walkthrough).

***

## Honest limits (v0.1 Preview)

* Language remains **draft**; emitter depth varies by target (MVP stubs vs richer SQL/OpenAPI).
* Full-tier examples **parse and validate**; not every Behavior/Security detail is reflected in every emitter yet (**Phase D** deepens TS / OpenAPI / SQL).
* No Nest/Express/Chi lock-in — TypeScript and Go emits stay thin (stdlib / interfaces).
* Site playground is still **illustrative** and must not be confused with these packages.

Matrix status: [Specification § Transpiler matrix](/en/specification#transpiler-matrix). Per-emitter scores: [Emitters](/en/emitters). Roadmap: [Phase D](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md).

***

## Related

* [Get started here](/en/getting-started)
* [CRUD walkthrough](/en/crud-walkthrough)
* [ROADMAP.md](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md)
* [CONTRIBUTING.md](https://github.com/eudameron/aiparlance/blob/main/CONTRIBUTING.md)


# Get started here
Source: https://docs.aiparlance.org/en/getting-started

Install the reference toolchain, validate .aip specs, and emit SQL, OpenAPI, TypeScript, Go, and the full Preview matrix

# Get started here

Use the **reference toolchain** from the monorepo today. Packages are not on the public npm registry yet — clone the repo and run the CLI locally.

Requirements: **Node.js 20+**, Git.

***

## 1. Clone and install

```bash theme={null}
git clone https://github.com/eudameron/aiparlance.git
cd aiparlance
npm ci
npm run build
```

This builds `@aiparlance/parser`, `validator`, `cli`, and the Preview emitters (`sql`, `openapi`, `typescript`, `go`, `mysql`, `workers`, `python`, `php`, `docs`, `tests`).

***

## 2. Run the CLI

The binary lives at `packages/cli/dist/cli.js` after build:

```bash theme={null}
node packages/cli/dist/cli.js --help
```

| Command                          | What it does                                                      |
| -------------------------------- | ----------------------------------------------------------------- |
| `aip parse <file.aip>`           | Print the AST as JSON                                             |
| `aip validate <file.aip>`        | Semantic checks (MUST rules) — Core + Infra + Security + Behavior |
| `aip emit sql <file.aip>`        | PostgreSQL DDL (+ indexes / seeds when present)                   |
| `aip emit openapi <file.aip>`    | OpenAPI 3.0.3 JSON                                                |
| `aip emit typescript <file.aip>` | TypeScript interfaces + type guards                               |
| `aip emit go <file.aip>`         | Go structs + thin handlers + auth middleware                      |
| `aip emit mysql <file.aip>`      | MySQL DDL (`database mysql`)                                      |
| `aip emit workers <file.aip>`    | Jobs / queues stubs                                               |
| `aip emit python <file.aip>`     | Python dataclasses                                                |
| `aip emit php <file.aip>`        | PHP classes                                                       |
| `aip emit docs <file.aip>`       | Markdown API reference                                            |
| `aip emit tests <file.aip>`      | CRUD test fixtures                                                |

### Try the minimal example

```bash theme={null}
node packages/cli/dist/cli.js validate examples/minimal.aip
node packages/cli/dist/cli.js emit sql examples/minimal.aip
node packages/cli/dist/cli.js emit openapi examples/minimal.aip
node packages/cli/dist/cli.js emit typescript examples/minimal.aip
node packages/cli/dist/cli.js emit go examples/minimal.aip
```

Write output to a file:

```bash theme={null}
node packages/cli/dist/cli.js emit sql examples/minimal.aip > /tmp/minimal.sql
node packages/cli/dist/cli.js emit openapi examples/minimal.aip > /tmp/minimal.openapi.json
node packages/cli/dist/cli.js emit typescript examples/minimal.aip > /tmp/minimal.ts
node packages/cli/dist/cli.js emit go examples/minimal.aip > /tmp/minimal.go
```

Full CRUD walkthrough (entities, policies, API, seeds, emit): [CRUD walkthrough](/en/crud-walkthrough).

### Blog CRUD happy path (TypeScript + SQL + OpenAPI)

```bash theme={null}
export DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/aiparlance
export AIP_JWT_SECRET=dev-secret
node packages/cli/dist/cli.js validate examples/blog-crud.aip
node packages/cli/dist/cli.js emit sql examples/blog-crud.aip | psql "$DATABASE_URL"
node packages/cli/dist/cli.js emit typescript examples/blog-crud.aip > /tmp/blog-app.ts
# npm i zod pg jose  (peers for the generated app)
npx tsx -e "import { listenCrudApp } from '/tmp/blog-app.ts'; listenCrudApp()"
```

`GET /v1/posts` is public; mutating routes need `Authorization: Bearer <JWT>` (`signCrudToken` in the generated file). Without `DATABASE_URL` the app stays in-memory.

***

## 3. Write your own `.aip`

Every v0.1 spec needs one `app` block first, then `entity` / `crud` / `validation` (Core). See [Syntax](/en/syntax) and [examples/](https://github.com/eudameron/aiparlance/tree/main/examples).

```aip theme={null}
app Demo @0.1 {
  database postgres
}

entity User {
  name: string required
  email: email required unique
}

crud User
```

Save as `my-app.aip`, then:

```bash theme={null}
node packages/cli/dist/cli.js validate my-app.aip
node packages/cli/dist/cli.js emit sql my-app.aip
```

<Note>
  Richer examples (`blog-crud.aip`, `crm-reference.aip`, `ops-reference.aip`, `inventory-crud.aip`) include Infra / Security / Behavior and **parse + validate** with the full v0.1 toolchain. Use `mysql-minimal.aip` for `aip emit mysql`.
</Note>

***

## 4. Run the test suite

From the repo root:

```bash theme={null}
npm test
```

This typechecks/builds workspaces and runs Vitest (parser, validator, emitters, CLI, and [examples CI](https://github.com/eudameron/aiparlance/blob/main/scripts/examples.test.ts)).

Examples-only:

```bash theme={null}
npm run check:examples
```

Typecheck without tests:

```bash theme={null}
npm run typecheck
```

***

## 5. What ships vs what is preview

| Status                    | Targets                                                                             |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Preview** (in monorepo) | PostgreSQL, MySQL, OpenAPI 3, TypeScript, Go, Python, PHP, Workers, Docs, Tests     |
| **Phase D focus**         | Deepen TypeScript, OpenAPI, PostgreSQL → runnable happy path; then playground + npm |
| **Illustrative only**     | Marketing site [playground](https://aiparlance.org) — not the official packages     |

Read more: [First emitters](/en/first-transpiler) · [CRUD walkthrough](/en/crud-walkthrough) · [Examples](/en/examples) · [Specification § Transpiler matrix](/en/specification#transpiler-matrix) · [ROADMAP](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md) · [CONTRIBUTING](https://github.com/eudameron/aiparlance/blob/main/CONTRIBUTING.md)

***

## Optional: docs and site locally

```bash theme={null}
# Docs (Mintlify)
cd docs && npx mintlify dev

# Marketing site
cd site && npm ci && npm run build:prod
```


# Introduction
Source: https://docs.aiparlance.org/en/introduction

AI-first intermediate representation for AI-assisted software generation

# AI Parlance

<Note>
  **v0.1 is still a draft language.** The monorepo ships a full v0.1 **parser/validator** (Core + Infra + Security + Behavior) and Preview emitters across the [transpiler matrix](/en/specification#transpiler-matrix) (`aip parse` / `validate` / `emit`). **Phase C** (reference toolchain) is complete; **Phase D** deepens TypeScript / OpenAPI / SQL and distribution — see [ROADMAP](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md) and [Get started here](/en/getting-started). This documentation remains the normative source for the language.
</Note>

AI Parlance is an AI-first language for **intermediate representation (IR)** in AI-assisted software generation — focused on data-oriented applications, APIs, authorization, and declarative automations.

Humans, agents, and LLMs describe systems in `.aip`; transpilers turn the spec into concrete implementations.

```txt theme={null}
Human or AI
↓
AI Parlance (.aip)
↓
AST + validation
↓
Transpilers
↓
Go, TypeScript, SQL, OpenAPI, …
```

Normative details: [Specification](/en/specification).

***

## Why it exists

When models generate code directly in general-purpose languages, they face:

* large amounts of boilerplate (CRUD, routes, validation, migrations)
* inconsistency across stacks
* large context → more tokens and more hallucination
* business rules and permissions scattered in generated code

AI Parlance concentrates **intent** in a compact semantic layer before implementation.

***

## What it describes (and what it does not)

| Describes                   | Does not describe                      |
| --------------------------- | -------------------------------------- |
| entities, types, relations  | custom UI                              |
| CRUD, indexes, migrations   | complex algorithms                     |
| auth, policies              | integrations without a dedicated block |
| domain workflows and events | hand-written imperative SQL            |

***

## Minimal example

```aip theme={null}
app Demo @0.1 {
  database postgres
}

entity User {
  name: string required
  email: email required unique
}

crud User
```

See [examples/minimal.aip](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip). Every v0.1 spec requires one `app` block ([Specification](/en/specification)).

One definition can feed multiple generators (see [transpiler matrix](/en/specification#transpiler-matrix)).

***

## AI-first principles

The language prioritizes, in order:

1. domain intent and semantics
2. predictable structure for LLMs
3. static validation before generation
4. multi-target implementation via transpilers

***

## Documentation map

| Page                                     | Content                                  |
| ---------------------------------------- | ---------------------------------------- |
| [Get started here](/en/getting-started)  | Install, CLI, emit, and test             |
| [First emitters](/en/first-transpiler)   | Official Preview emitters (matrix)       |
| [CRUD walkthrough](/en/crud-walkthrough) | Complete blog CRUD → emit                |
| [Examples](/en/examples)                 | All reference `.aip` specs               |
| [Emitters](/en/emitters)                 | Maturity scores & objectives per emitter |
| [Specification](/en/specification)       | Grammar, builtins, policies, stability   |
| [Cost impact](/en/cost-impact)           | Tokens, honest comparisons               |
| [Syntax](/en/syntax)                     | Core + Infra blocks                      |
| [Database](/en/database)                 | Migrations, indexes, naming              |
| [Security](/en/security)                 | Auth, policies, rate limit               |
| [Workflows](/en/workflows)               | Events, jobs, queues                     |
| [Agents](/en/agents)                     | Prompts, `ai_context`, best practices    |

Next step for newcomers: [Get started here](/en/getting-started) or the [CRUD walkthrough](/en/crud-walkthrough).

Reference specs: [blog-crud.aip](https://github.com/eudameron/aiparlance/blob/main/examples/blog-crud.aip) · [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip).


# Security
Source: https://docs.aiparlance.org/en/security

Auth, policies, rate limiting, and CORS in AI Parlance

# Security

**Security** layer (beta v0.1). Predicates: [Specification — Policies](/en/specification#policies). Example: [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip).

***

## `auth`

Global default on `app`:

```aip theme={null}
app CRM @0.1 {
  auth jwt
}
```

| Strategy  | Typical use                          |
| --------- | ------------------------------------ |
| `jwt`     | Stateless APIs (recommended initial) |
| `session` | Cookie-based web apps                |
| `api_key` | Machine-to-machine                   |
| `oauth`   | Social login / IdP                   |

Set JWT on `app` once; avoid duplicating `auth jwt` in `api` unless overriding.

***

## `policy`

```aip theme={null}
policy Lead {
  create authenticated
  read owner_or_manager(Lead.seller)
  update owner_or_manager(Lead.seller)
  delete role(admin)
}
```

`Lead.seller` must exist as `belongs_to User`.

***

## Roles and permissions

```aip theme={null}
entity User {
  role: enum(admin, manager, seller) default(seller)
}

(* Proposed — not in v0.1 grammar yet *)
permission export_reports

policy Report {
  read permission(export_reports)
}
```

The `permission(name)` **predicate** in `policy` is supported; top-level `permission` declarations are preview only.

***

## Predicates

| Predicate                 | Description                        |
| ------------------------- | ---------------------------------- |
| `public`                  | No auth                            |
| `authenticated`           | Valid session/JWT                  |
| `role(name)`              | Global role                        |
| `permission(name)`        | Named permission                   |
| `owner(field)`            | Authenticated user matches `field` |
| `owner_or_manager(field)` | Owner, manager, or admin           |

Arbitrary logic: a future `custom` block is reserved — do not mix hand-written SQL with generated policies in v0.1.

***

## `rate_limit` and CORS

```aip theme={null}
api {
  rate_limit 100/minute
  cors {
    allow "https://app.example.com"
  }
}
```

Per-route (**proposed** — not in v0.1 grammar):

```aip theme={null}
endpoint Login {
  rate_limit 5/minute
}
```

***

## SQL injection

Transpilers must emit **parameterized queries** / ORM only. Does not cover hand-written `custom` code.

***

## Multi-target output

| Target     | Artifact                       |
| ---------- | ------------------------------ |
| Go         | JWT middleware, handler checks |
| TypeScript | guards, decorators             |
| Python     | dependencies / decorators      |
| PHP        | policies, gates                |
| OpenAPI    | `securitySchemes`              |

[`crm-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) already includes `policy Lead` and `api` with rate limit + CORS.


# Specification
Source: https://docs.aiparlance.org/en/specification

Normative grammar, builtins, policies, and stability levels for AI Parlance v0.1

# Specification

Normative document for AI Parlance (**v0.1**). Defines grammar, semantics, builtins, policies, and block stability levels.

Overview: [Introduction](/en/introduction). Syntax reference: [Syntax](/en/syntax).

***

## Glossary

| Term            | Meaning                                                                         |
| --------------- | ------------------------------------------------------------------------------- |
| **AI Parlance** | AI-first declarative language used as IR between intent and generated code.     |
| **Block**       | Top-level construct (`entity`, `workflow`, …).                                  |
| **Transpiler**  | Generator that converts AI Parlance (+ AST) into target artifacts (Go, SQL, …). |
| **AST**         | Syntax tree produced by the parser from `.aip` text; common transpiler input.   |
| **Builtin**     | Reserved function or command (`now()`, `notify()`, …).                          |
| **Predicate**   | Boolean expression in `policy` (`authenticated`, `role(admin)`, …).             |

***

## Scope and limits

AI Parlance currently covers:

* data and API modeling (CRUD)
* declarative authorization
* limited domain workflows and events

It does not replace:

* custom UI or design systems
* complex algorithms or manual performance tuning
* ad hoc integrations without a dedicated block
* hand-written imperative SQL (a future `custom` block is reserved; not in v0.1)

| Tool               | Focus                    | AI Parlance                                    |
| ------------------ | ------------------------ | ---------------------------------------------- |
| OpenAPI / AsyncAPI | HTTP / event contracts   | Model + behavior + policy in one spec          |
| Prisma / DBML      | Data schema              | Entities + relations + multi-target migrations |
| OPA / Cedar        | Authorization            | `policy` integrated with entities              |
| Temporal / Cadence | Imperative orchestration | Declarative `workflow` for common rules        |

***

## Pipeline

```txt theme={null}
Prompt or human edit
↓
.aip text
↓
Parser → AST
↓
Semantic validator
↓
Transpilers (per target)
↓
Go, SQL, OpenAPI, workers, …
```

`.aip` is the source; the AST is internal. Agents and humans edit `.aip`, not the AST directly.

**Toolchain (v0.1):** Core **parser**, **validator**, and Preview emitters for **PostgreSQL**, **MySQL**, **OpenAPI**, **TypeScript**, **Go**, **Python**, **PHP**, **Workers**, **Docs**, and **Tests** ship in the monorepo (`aip parse` / `aip validate` / `aip emit …`). This document is the normative prose source; see [spec/v0.1/grammar.ebnf](https://github.com/eudameron/aiparlance/blob/main/spec/v0.1/grammar.ebnf) and [ROADMAP.md](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md).

***

## Required `app` block

Every v0.1 spec must start with exactly one `app` block (version tag recommended):

```aip theme={null}
app MyApp @0.1 {
  database postgres
}
```

Add `auth` when using `authenticated`, `role`, or `permission` in `policy`. Minimal example: [examples/minimal.aip](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip).

***

<h2>
  Grammar (EBNF summary)
</h2>

Complete normative grammar: [spec/v0.1/grammar.ebnf](https://github.com/eudameron/aiparlance/blob/main/spec/v0.1/grammar.ebnf). Summary:

```ebnf theme={null}
program        = app_block , { block } ;
block          = entity_block | crud_stmt | policy_block
               | index_block | api_block | workflow_block | event_block
               | lifecycle_block | seed_block | job_block | queue_block
               | ai_context_block | validation_block ;

app_block      = "app" IDENT [ "@" version ] "{" { app_member } "}" ;
entity_block   = "entity" IDENT "{" { field_decl | entity_modifier } "}" ;
field_decl     = IDENT ":" type_expr [ field_modifier { field_modifier } ] ;
crud_stmt      = "crud" IDENT ;
workflow_block = "workflow" IDENT "{" when_clause { stmt } "}" ;
when_clause    = "when" IDENT "." lifecycle_event ;
```

Exactly one `app_block` is required and must appear first. Field modifier order: `required` | `optional` → `unique` → `default(...)`.

Line comments: `//` to end of line (ignored by the parser).

***

## Stability levels

| Level        | Blocks                                                                                                                         | Status v0.1 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| **Core**     | `app`, `entity`, `crud`, inline field validation and `validation` block; inline `enum(…)` types; inline `belongs_to` relations | Stable      |
| **Infra**    | `index`, `api`, migrations, `seed`, naming; entity modifiers `timestamps`, `soft_delete`                                       | Stable      |
| **Security** | `auth` (on `app`), `policy`, predicates                                                                                        | Beta        |
| **Behavior** | `workflow`, `event`, `lifecycle`, `job`, `queue`, `ai_context`; workflow statements (`emit`, `create`, …)                      | Beta        |

Top-level `enum { }` / `relation { }` blocks and `has_one` / `has_many` / `many_to_many` are **roadmap**, not v0.1.

Beta blocks may change syntax between minor v0.x releases. Core is stable within v0.1; the overall language remains **draft** (Preview toolchain in the monorepo — not a frozen v1.0). See [ROADMAP](https://github.com/eudameron/aiparlance/blob/main/ROADMAP.md).

***

<h2>
  Implicit fields
</h2>

Every `entity` receives automatically (unless `id: uuid` is explicit):

| Field        | Type       | Notes                          |
| ------------ | ---------- | ------------------------------ |
| `id`         | `uuid`     | Primary key                    |
| `created_at` | `datetime` | Always injected (Core default) |
| `updated_at` | `datetime` | Always injected (Core default) |

The `timestamps` modifier on `entity` is optional documentation sugar; it does not disable these fields.

`soft_delete` on `entity` adds `deleted_at: datetime optional`.

***

<h2>
  Builtins
</h2>

| Name                         | Usage                       | Effect                                                                          |
| ---------------------------- | --------------------------- | ------------------------------------------------------------------------------- |
| `now()`                      | expressions                 | Current UTC datetime                                                            |
| `available_seller()`         | workflow                    | Returns available `User` with seller role                                       |
| `assign`                     | `assign Lead.seller seller` | Sets relation / FK field                                                        |
| `notify(recipient, message)` | workflow                    | Notification; `recipient` is a `User` variable, entity field, or string literal |
| `LeadExists(phone)`          | condition                   | Duplicate check on normalized phone                                             |
| `normalize_phone(value)`     | expression                  | Normalizes phone for comparison                                                 |
| `emit EventName { … }`       | workflow                    | Publishes declared domain event                                                 |
| `create Entity { … }`        | workflow                    | Creates declared entity record                                                  |
| `reject "msg"`               | workflow                    | Business error abort                                                            |
| `dispatch JobName`           | workflow                    | Enqueues declared job                                                           |

Unlisted builtins are invalid until added to the spec.

***

## Lifecycle

System events (`when` triggers):

```txt theme={null}
created | updated | deleted
```

```aip theme={null}
lifecycle Lead {
  on created -> workflow LeadReceived
  before create {
    normalize_phone(Lead.phone)
  }
  after update {
    notify(Lead.seller, "Lead updated")
  }
}
```

`when Lead.created` in `workflow` equals `on created` in `lifecycle`. Prefer `lifecycle` when an entity has multiple hooks.

### Workflow statements (v0.1)

Inside `workflow` / `lifecycle` hooks: `var`, `if` / `reject`, `assign`, `create`, `emit`, `notify`, `dispatch` (optional `after` + duration). Durations: `15m`, `1h`, `1d` (see [Workflows](/en/workflows)).

Forward references are allowed: `emit` and `create` may reference `event` / `entity` blocks declared later in the file.

***

<h2>
  Policies
</h2>

Predicates supported in v0.1:

| Predicate                 | Meaning                                            |
| ------------------------- | -------------------------------------------------- |
| `public`                  | No authentication                                  |
| `authenticated`           | Valid JWT/session                                  |
| `role(name)`              | Global role of authenticated user                  |
| `permission(name)`        | Explicit granted permission                        |
| `owner(field)`            | `auth.user_id` matches `field` (FK or id)          |
| `owner_or_manager(field)` | `owner(field)` or `role(manager)` or `role(admin)` |

```aip theme={null}
policy Lead {
  read owner_or_manager(Lead.seller)
}
```

Requires `Lead.seller` as `belongs_to User`.

### Default access

Entities without a `policy` block: transpilers should default to **`authenticated`** for CRUD when `app` has `auth`, or **`public`** when there is no `auth`. Explicit `policy` always wins.

### Proposed (not in v0.1 grammar)

* Top-level `permission name` declarations
* `endpoint` blocks for per-route rate limits

Documented in [Security](/en/security) as preview only until added to the grammar.

***

## Validation

The semantic validator must reject:

* missing or duplicate `app` block
* references to missing `entity` / `event` / `job`
* `policy` using `authenticated` or `role` without `auth` in `app`
* `owner(field)` when `field` does not exist
* `workflow` without `when`
* duplicate or out-of-order modifiers (warning vs error per rule)
* unregistered builtins

***

<h2>
  Transpiler matrix
</h2>

| Target     | Artifacts                                    | Status v0.1                     |
| ---------- | -------------------------------------------- | ------------------------------- |
| PostgreSQL | DDL, indexes, seeds, init up/down migrations | Preview (`aip emit sql`)        |
| MySQL      | DDL, indexes, seeds                          | Preview (`aip emit mysql`)      |
| Go         | structs, handlers, JWT middleware stubs      | Preview (`aip emit go`)         |
| TypeScript | interfaces, Zod, in-memory CRUD              | Preview (`aip emit typescript`) |
| Python     | models / dataclasses MVP                     | Preview (`aip emit python`)     |
| PHP        | classes MVP                                  | Preview (`aip emit php`)        |
| OpenAPI    | paths, schemas, policy security              | Preview (`aip emit openapi`)    |
| Docs       | Markdown / API reference                     | Preview (`aip emit docs`)       |
| Tests      | CRUD fixtures                                | Preview (`aip emit tests`)      |
| Workers    | queues, jobs from `workflow`                 | Preview (`aip emit workers`)    |

LLM inference cost applies to **editing `.aip`**, not offline transpilation.

***

## Reference specs

| File                                                                                                       | Role                                                    |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [examples/minimal.aip](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip)             | Smallest valid Core spec                                |
| [examples/crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) | CRM (policy, API, workflow)                             |
| [examples/ops-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip) | Infra + Behavior extras (`seed`, `lifecycle`, `job`, …) |

Domain chapters ([Database](/en/database), [Security](/en/security), [Workflows](/en/workflows)) document extensions relative to this file.


# Syntax
Source: https://docs.aiparlance.org/en/syntax

Core and Infra block reference for AI Parlance v0.1

# Syntax

Reference for **Core** and **Infra** blocks (stable in v0.1). Full grammar: [Specification](/en/specification) · [grammar.ebnf](https://github.com/eudameron/aiparlance/blob/main/spec/v0.1/grammar.ebnf). Examples: [minimal.aip](https://github.com/eudameron/aiparlance/blob/main/examples/minimal.aip), [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip), [ops-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip).

**Security** and **Behavior** blocks: [Security](/en/security), [Workflows](/en/workflows).

***

## Conventions

* Fields are declared **inside** `entity` (`name: type modifiers`).
* Modifier order: `required` | `optional` → `unique` → `default(value)`.
* Identifiers: `PascalCase` for entities/events; `snake_case` for fields.

***

## `app`

```aip theme={null}
app CRM @0.1 {
  database postgres
  auth jwt
}
```

| Member     | Initial values                       |
| ---------- | ------------------------------------ |
| `database` | `postgres`, `mysql`                  |
| `auth`     | `jwt`, `session`, `api_key`, `oauth` |

`auth` on `app` is the default; `api { }` may override HTTP exposure details.

***

## `entity`

```aip theme={null}
entity User {
  name: string required
  email: email required unique
  role: enum(admin, manager, seller) default(seller)
  active: bool default(true)
}
```

Implicit fields: [specification#implicit-fields](/en/specification#implicit-fields).

```aip theme={null}
entity User {
  timestamps   // optional marker; created_at/updated_at always injected
  soft_delete  // adds deleted_at
}
```

***

## Types

```aip theme={null}
string | text | int | float | bool
datetime | date | uuid | email | phone | json
```

```aip theme={null}
status: enum(new, assigned, won, lost) default(new)
```

***

## `relation`

```aip theme={null}
entity Lead {
  seller: belongs_to User optional
}
```

| Relation (inline, v0.1) | Usage                     |
| ----------------------- | ------------------------- |
| `belongs_to`            | FK to another entity      |
| `has_one`               | 1:1 inverse (**roadmap**) |
| `has_many`              | 1:N (**roadmap**)         |
| `many_to_many`          | N:N (**roadmap**)         |

`optional` marks nullable / optional FK.

***

## `crud`

```aip theme={null}
crud Lead
```

Typical routes:

```txt theme={null}
POST   /leads
GET    /leads
GET    /leads/:id
PUT    /leads/:id
DELETE /leads/:id
```

Artifacts depend on the [transpiler matrix](/en/specification#transpiler-matrix).

***

## Validation

Prefer **inline** modifiers:

```aip theme={null}
entity User {
  name: string required
  email: email required unique
}
```

`validation` block (equivalent, for many rules):

```aip theme={null}
validation User {
  name required
  email required unique
}
```

***

## `index`

```aip theme={null}
index Lead {
  status
  created_at
}
```

`unique` on a field already creates a constraint; use `index` for non-unique or composite lookups.

***

## `api`

```aip theme={null}
api {
  prefix "/v1"
  format json
}
```

HTTP auth inherits from `app.auth` unless overridden. Rate limit and CORS: [Security](/en/security).

***

## Summary (Core + Infra)

| Block                 | Level | Function                             |
| --------------------- | ----- | ------------------------------------ |
| `app`                 | Core  | Application defaults                 |
| `entity`              | Core  | Data model                           |
| inline `enum(…)`      | Core  | Enum field types                     |
| inline `belongs_to`   | Core  | Relationships (v0.1)                 |
| `crud`                | Core  | REST operations                      |
| inline / `validation` | Core  | Field rules                          |
| `index`               | Infra | Database indexes                     |
| `api`                 | Infra | HTTP config                          |
| `seed`                | Infra | Seed data — [Database](/en/database) |

***

## Blocks in other chapters

| Block                                            | Chapter                    |
| ------------------------------------------------ | -------------------------- |
| `policy`, `permission`, `auth`                   | [Security](/en/security)   |
| `workflow`, `event`, `lifecycle`, `job`, `queue` | [Workflows](/en/workflows) |
| `ai_context`                                     | [Agents](/en/agents)       |

***

## Core example (no full CRM)

```aip theme={null}
app Shop @0.1 {
  database postgres
  auth jwt
}

entity Product {
  name: string required
  price: float required
  sku: string required unique
}

crud Product

api {
  prefix "/v1"
  format json
}
```

Full CRM with policy and workflow: [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip).


# Workflows and events
Source: https://docs.aiparlance.org/en/workflows

Behavior layer for workflows, events, jobs, and queues

# Workflows and events

**Behavior** layer (beta v0.1). Builtins: [Specification](/en/specification#builtins). Examples: [crm-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) (workflow + event), [ops-reference.aip](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip) (`lifecycle`, `job`, `queue`, `if`/`reject`/`dispatch`).

***

## `event`

Domain event contract:

```aip theme={null}
event LeadAssigned {
  lead: Lead
  seller: User
}
```

Publish from a workflow with `emit` (do not redeclare `event` inside the workflow):

```aip theme={null}
workflow LeadReceived {
  when Lead.created
  emit LeadAssigned {
    lead: Lead
    seller: seller
  }
}
```

***

## `workflow`

`when` trigger is required:

```aip theme={null}
workflow LeadReceived {
  when Lead.created

  var seller = available_seller()

  assign Lead.seller seller

  create Task {
    title: "Follow up"
    due_at: now() + 15m
    lead: Lead
  }

  notify(seller, "New lead assigned")

  emit LeadAssigned {
    lead: Lead
    seller: seller
  }
}
```

`Task` must be declared as an `entity` in the reference spec. In `create`, `lead: Lead` refers to the instance from the `when` trigger.

Durations: `15m`, `1h`, `1d` in expressions and in `dispatch Job after 15m`.

Forward references are valid: `emit` may use `event` blocks declared later in the file.

***

## `lifecycle`

Prefer when multiple hooks exist on one entity:

```aip theme={null}
lifecycle Lead {
  on created -> workflow LeadReceived
  before create {
    normalize_phone(Lead.phone)
  }
  after update {
    notify(Lead.seller, "Lead updated")
  }
}
```

***

## Conditions and errors

```aip theme={null}
if LeadExists(phone) {
  reject "Duplicate lead"
}
```

***

## `job` and `queue`

```aip theme={null}
queue SendEmail

job SendWelcomeEmail {
  retries 3
  timeout 1m
}

workflow UserCreated {
  when User.created
  dispatch SendWelcomeEmail
}
```

Delayed dispatch: `dispatch SendReminder after 15m`.

***

## Best practices

* Declare every `entity` used in `create`.
* Use `emit` for publication; reserve `event { }` for type definition.
* Keep workflows short; split long logic into jobs.
* Prefer `lifecycle` for multiple hooks per entity.

[`crm-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/crm-reference.aip) contains `workflow LeadReceived`, `event LeadAssigned`, and `entity Task`. [`ops-reference.aip`](https://github.com/eudameron/aiparlance/blob/main/examples/ops-reference.aip) covers `lifecycle`, `job`, `queue`, and conditionals.